.EVENTS

Zentrales Event-System des Bots (RAGAI.EVENTS): Registrieren, Auslösen und Entfernen von Hooks.

Hintergrund

Event-Namen folgen der Konvention RAGAI.<MODUL>.<Aktion> (z. B. RAGAI.MSG.prompt, RAGAI.KEYVAL.storeKeyValEntry). Jedes RAGAI-Modul triggert bei praktisch jeder Aktion ein eigenes Event - das macht RAGAI.EVENTS zum zentralen Beobachtungspunkt für alles, was im Bot passiert, unabhängig vom auslösenden Modul. Der Hook-Name "*" (Wildcard) lauscht auf alle Events, nicht nur ein bestimmtes - wird u. a. intern vom Debug-Manager genutzt, um jedes RAGAI-Event ins Debug-Log zu spiegeln. on/off/trigger sind kurze Aliase für listenTo/removeEventHook/triggerEventHook.

Methoden

.listenTo(hook, fn, id?)

Registriert einen Listener für ein Event und gibt dessen ID zurück (zum späteren Entfernen).

Parameter	Typ	Beschreibung
hook	string
fn	EventHookType
id	string

Rückgabewert: string

._datafromEvent(eventName, eventData, field)

Liest ein benanntes Feld aus rohen Event-Nutzdaten aus - normalisiert die je nach Event-Typ unterschiedliche Datenstruktur.

Parameter	Typ	Beschreibung
eventName	string
eventData	any
field	string

Rückgabewert: any

.on(hook, fn?, id?)

Kurzalias für listenTo(). Registriert einen Listener für ein Event.

Parameter	Typ	Beschreibung
hook	string | z.input<typeof eventsOnSchema>
fn	EventHookType
id	string

Objekt-Form (validiert über eventsOnSchema):

Feld	Typ	Pflicht	Beschreibung
hook	string	✔	Name des abzuhörenden Events.
fn	any	✔	Die bei Event-Auslösung aufzurufende Funktion.
id	string	–	Optionale eindeutige ID des Listeners (zum späteren Entfernen).

Rückgabewert: string

.off(id)

Kurzalias für removeEventHook(). Entfernt einen registrierten Listener anhand seiner ID.

Parameter	Typ	Beschreibung
id	string | z.input<typeof eventsOffSchema>

Objekt-Form (validiert über eventsOffSchema):

Feld	Typ	Pflicht	Beschreibung
id	string	✔	ID des zu entfernenden Listeners.

Rückgabewert: void

.removeEventHook(id)

Entfernt einen registrierten Listener anhand seiner ID.

Parameter	Typ	Beschreibung
id	string

Rückgabewert: void

.addEventHook(id, fn, hook?)

Registriert einen Listener direkt (ohne Zod-Validierung), Standard-Hook ist die Wildcard "*" (alle Events).

Parameter	Typ	Beschreibung
id	string
fn	EventHookType
hook	string

Rückgabewert: void

.addEventHookAddUserMessage(id, fn)

Registriert einen Listener speziell für das interne io_in_addUserMessage-Event.

Parameter	Typ	Beschreibung
id	string
fn	EventHookType

Rückgabewert: void

.triggerEventHook(hook, params)

Löst alle registrierten Listener aus, deren Hook exakt passt oder (bei Wildcard-Hooks) als Präfix matcht.

Parameter	Typ	Beschreibung
hook	string
params	unknown

Rückgabewert: void

.inActiveHook(seconds)

Liefert einen Hook, der auslöst, sobald der Nutzer die angegebene Anzahl Sekunden inaktiv war.

Parameter	Typ	Beschreibung
seconds	number | z.input<typeof eventsInActiveHookSchema>

Objekt-Form (validiert über eventsInActiveHookSchema):

Feld	Typ	Pflicht	Beschreibung
seconds	number	✔	Anzahl der Sekunden ohne Aktivität, nach denen der Inaktivitäts-Hook ausgelöst wird.

Rückgabewert: InactiveAction

.trigger(name, params?)

Kurzalias für triggerEventHook(). Löst ein benanntes Event manuell aus.

Parameter	Typ	Beschreibung
name	string | z.input<typeof eventsTriggerSchema>
params	any

Objekt-Form (validiert über eventsTriggerSchema):

Feld	Typ	Pflicht	Beschreibung
name	string	✔	Name des auszulösenden Events.
params	any	–	Parameter, die an die Event-Listener übergeben werden.

Rückgabewert: void

._trigger_RAGAI_EVENT(instance, eventParams?, additionalEventInfo?)

Interner Helfer: leitet aus dem Aufruf-Stack den auslösenden RAGAI-Modulnamen ab und triggert das passende RAGAI.<MODUL>.<METHODE>-Event.

Parameter	Typ	Beschreibung
instance	unknown | string
eventParams	any
additionalEventInfo	string

Rückgabewert: string

.manage(action, eventId)

Deaktiviert, aktiviert oder entfernt ein registriertes Event anhand seiner ID.

Parameter	Typ	Beschreibung
action	'disable' | 'enable' | 'remove'
eventId	string

Rückgabewert: Promise<void>