@novu/framework 2.10.1-alpha.5 → 2.10.1-alpha.7

package/dist/cjs/{index-B4t9LyOV.d.cts → index-DtCBrkhW.d.cts}

@@ -10,12 +10,14 @@ declare enum AgentEventEnum {
     ON_RESOLVE = "onResolve",
     ON_REACTION = "onReaction"
 }
+/** Identity of the user or bot that authored a message. */
 interface AgentMessageAuthor {
     userId: string;
     fullName: string;
     userName: string;
     isBot: boolean | 'unknown';
 }
+/** A file or media attachment included with a message. */
 interface AgentAttachment {
     type: string;
     url?: string;
@@ -23,22 +25,35 @@ interface AgentAttachment {
     mimeType?: string;
     size?: number;
 }
+/** An incoming message from the user in the current conversation. */
 interface AgentMessage {
+    /** Plain-text content of the message. */
     text: string;
+    /** Platform-native message ID (e.g. Slack `ts`, Teams `activityId`). */
     platformMessageId: string;
     author: AgentMessageAuthor;
     timestamp: string;
     attachments?: AgentAttachment[];
 }
+/** Live state of the current conversation thread. */
 interface AgentConversation {
+    /** Stable identifier for this conversation. */
     identifier: string;
+    /** Lifecycle status (e.g. `'open'`, `'resolved'`). */
     status: string;
+    /**
+     * Key/value store for this conversation.
+     * Values are written via `ctx.metadata.set()` and readable on subsequent messages.
+     */
     metadata: Record<string, unknown>;
+    /** Number of messages exchanged so far; starts at 1 for the first message. */
     messageCount: number;
     createdAt: string;
     lastActivityAt: string;
 }
+/** The Novu subscriber who initiated or is participating in the conversation. */
 interface AgentSubscriber {
+    /** Stable Novu subscriber ID. */
     subscriberId: string;
     firstName?: string;
     lastName?: string;
@@ -46,23 +61,37 @@ interface AgentSubscriber {
     phone?: string;
     avatar?: string;
     locale?: string;
+    /** Arbitrary custom data attached to the subscriber in Novu. */
     data?: Record<string, unknown>;
 }
+/**
+ * A single entry in the conversation history.
+ * `ctx.history` is an ordered array of these entries — map them to your LLM's
+ * message format before making a model call.
+ */
 interface AgentHistoryEntry {
+    /** Message role: `'user'`, `'assistant'`, or `'system'`. */
     role: string;
+    /** Content type: `'text'`, `'card'`, etc. */
     type: string;
+    /** Plain-text representation of the message content. */
     content: string;
     richContent?: Record<string, unknown>;
     senderName?: string;
+    /** Present on system entries that carry a Novu signal (e.g. metadata updates). */
     signalData?: {
         type: string;
         payload?: Record<string, unknown>;
     };
     createdAt: string;
 }
+/** Platform-specific identifiers for the thread and channel. */
 interface AgentPlatformContext {
+    /** Platform-native thread ID (e.g. Slack thread `ts`, Teams conversation ID). */
     threadId: string;
+    /** Platform-native channel or chat ID. */
     channelId: string;
+    /** Whether the message arrived in a direct message rather than a shared channel. */
     isDM: boolean;
 }
 interface FileRef {
@@ -97,16 +126,30 @@ interface ReplyContent {
     card?: CardElement;
     files?: FileRef[];
 }
+/**
+ * Data carried by a button click or other interactive action.
+ *
+ * Used both on the bridge wire (`AgentBridgeRequest.action`) and as the
+ * handler-facing argument passed to `onAction(action, ctx)`.
+ */
 interface AgentAction {
-    actionId: string;
+    /** The `id` prop of the clicked `<Button>` or action element. */
+    id: string;
+    /** The `value` prop of the clicked element, if set. */
     value?: string;
+    /** Platform-native message ID of the message containing the clicked button/action. */
+    sourceMessageId?: string;
 }
+/** An emoji reaction added to or removed from a message. */
 interface AgentReaction {
+    /** Platform-native ID of the message that was reacted to. */
     messageId: string;
     emoji: {
         name: string;
     };
+    /** `true` when the reaction was added, `false` when it was removed. */
     added: boolean;
+    /** The message that was reacted to, if available. */
     message: AgentMessage | null;
 }
 /**
@@ -124,15 +167,23 @@ interface ReplyHandle {
         files?: FileRef[];
     }): Promise<ReplyHandle>;
 }
-interface AgentContext {
-    readonly event: string;
-    readonly action: AgentAction | null;
-    readonly message: AgentMessage | null;
-    readonly reaction: AgentReaction | null;
+interface AgentContextBase {
+    /** Live state of the current conversation, including persisted metadata. */
     readonly conversation: AgentConversation;
+    /**
+     * The Novu subscriber who sent the message, or `null` if Novu could not
+     * resolve a subscriber for this conversation.
+     */
     readonly subscriber: AgentSubscriber | null;
+    /**
+     * Full conversation history as an ordered array of entries.
+     * Map to your LLM's message format before making a model call:
+     * `ctx.history.map(h => ({ role: h.role, content: h.content }))`
+     */
     readonly history: AgentHistoryEntry[];
+    /** Platform identifier (e.g. `'slack'`, `'msteams'`, `'in-app'`). */
     readonly platform: string;
+    /** Platform-specific thread and channel identifiers. */
     readonly platformContext: AgentPlatformContext;
     /**
      * Post a message to the conversation and return a handle to it.
@@ -150,9 +201,26 @@ interface AgentContext {
     reply(content: MessageContent, options?: {
         files?: FileRef[];
     }): Promise<ReplyHandle>;
+    /**
+     * Mark the conversation as resolved. Optionally provide a summary for the resolution record.
+     * Triggers the `onResolve` handler if one is registered.
+     */
     resolve(summary?: string): void;
+    /**
+     * Persistent key/value store for this conversation.
+     *
+     * - `get(key)` — read a value from the current metadata state
+     * - `set(key, value)` — write a value (flushed with the next reply or on handler completion)
+     * - `delete(key)` — remove a key
+     * - `clear()` — reset metadata to `{}`
+     * - `current` — readonly snapshot of the current state
+     */
     metadata: {
+        get(key: string): unknown;
         set(key: string, value: unknown): void;
+        delete(key: string): void;
+        clear(): void;
+        readonly current: Readonly<Record<string, unknown>>;
     };
     /**
      * Trigger a Novu workflow from within this agent handler.
@@ -192,11 +260,66 @@ interface AgentContext {
      */
     addReaction(messageId: string, emojiName: Emoji): void;
 }
+/** Context passed to the `onMessage` handler. */
+interface AgentMessageContext extends AgentContextBase {
+    readonly event: 'onMessage';
+}
+/** Context passed to the `onAction` handler. */
+interface AgentActionContext extends AgentContextBase {
+    readonly event: 'onAction';
+    /** The button click or interactive action that triggered this handler. */
+    readonly action: AgentAction;
+}
+/** Context passed to the `onReaction` handler. */
+interface AgentReactionContext extends AgentContextBase {
+    readonly event: 'onReaction';
+    /** The emoji reaction that triggered this handler. */
+    readonly reaction: AgentReaction;
+}
+/** Context passed to the `onResolve` handler. */
+interface AgentResolveContext extends AgentContextBase {
+    readonly event: 'onResolve';
+}
+type AgentContext = AgentMessageContext | AgentActionContext | AgentReactionContext | AgentResolveContext;
+/** Event handlers for a conversational agent. */
 interface AgentHandlers {
-    onMessage: (ctx: AgentContext) => Awaitable<MessageContent | void>;
-    onReaction?: (ctx: AgentContext) => Awaitable<MessageContent | void>;
-    onAction?: (ctx: AgentContext) => Awaitable<MessageContent | void>;
-    onResolve?: (ctx: AgentContext) => Awaitable<MessageContent | void>;
+    /**
+     * Fires on every text message the user sends.
+     *
+     * @param message - The incoming message that triggered this handler.
+     * @param ctx - Conversation history, subscriber, metadata, and reply/trigger methods.
+     *
+     * Return a string or JSX card to reply, or call `ctx.reply()` directly
+     * for more control (e.g. editing a message in place).
+     */
+    onMessage: (message: AgentMessage, ctx: AgentMessageContext) => Awaitable<MessageContent | void>;
+    /**
+     * Fires when the user adds or removes an emoji reaction to a message.
+     *
+     * @param reaction - The emoji reaction (carries the emoji and whether it was added or removed).
+     * @param ctx - Conversation context (history, subscriber, metadata, reply/trigger methods).
+     *
+     * Return a string or card to post a reply, or return nothing to silently acknowledge.
+     */
+    onReaction?: (reaction: AgentReaction, ctx: AgentReactionContext) => Awaitable<MessageContent | void>;
+    /**
+     * Fires when the user clicks a `<Button>` or other interactive element.
+     *
+     * @param action - The interactive action that triggered this handler.
+     *   `action.id` is the `id` prop of the clicked element; `action.value` is its `value` prop.
+     * @param ctx - Conversation context (history, subscriber, metadata, reply/trigger methods).
+     *
+     * Return a string or card to reply, or return nothing to silently acknowledge the click.
+     */
+    onAction?: (action: AgentAction, ctx: AgentActionContext) => Awaitable<MessageContent | void>;
+    /**
+     * Fires after `ctx.resolve()` is called and the conversation is marked resolved.
+     * Use for post-resolution side-effects (e.g. triggering a follow-up workflow).
+     *
+     * @param ctx - Conversation context. Access subscriber and conversation via
+     *   `ctx.subscriber` and `ctx.conversation`.
+     */
+    onResolve?: (ctx: AgentResolveContext) => Awaitable<MessageContent | void>;
 }
 interface Agent {
     id: string;
@@ -222,8 +345,16 @@ interface AgentBridgeRequest {
 }
 type MetadataSignal = {
     type: 'metadata';
+    action: 'set';
     key: string;
     value: unknown;
+} | {
+    type: 'metadata';
+    action: 'delete';
+    key: string;
+} | {
+    type: 'metadata';
+    action: 'clear';
 };
 /**
  * Queued by `ctx.trigger()` — instructs Novu to fire a workflow from inside an agent handler.
@@ -448,4 +579,4 @@ declare class NovuRequestHandler<Input extends any[] = any[], Output = any> {
  */
 declare function workflow<T_PayloadSchema extends Schema, T_ControlSchema extends Schema, T_EnvSchema extends Schema, T_PayloadValidated extends Record<string, unknown> = FromSchema<T_PayloadSchema>, T_PayloadUnvalidated extends Record<string, unknown> = FromSchemaUnvalidated<T_PayloadSchema>, T_Controls extends Record<string, unknown> = FromSchema<T_ControlSchema>, T_Env extends Record<string, unknown> = FromSchema<T_EnvSchema>>(workflowId: string, execute: Execute<T_PayloadValidated, T_Controls, T_Env>, workflowOptions?: WorkflowOptions<T_PayloadSchema, T_ControlSchema, T_EnvSchema>): Workflow<T_PayloadUnvalidated>;
 
-export { type Agent as A, Client as C, type EditPayload as E, type FileRef as F, type INovuRequestHandlerOptions as I, type MessageContent as M, NovuRequestHandler as N, type ReplyContent as R, type ServeHandlerOptions as S, type TriggerSignal as T, type AgentAction as a, type AgentAttachment as b, type AgentBridgeRequest as c, type AgentContext as d, type AgentConversation as e, AgentDeliveryError as f, AgentEventEnum as g, type AgentHandlers as h, type AgentHistoryEntry as i, type AgentMessage as j, type AgentMessageAuthor as k, type AgentPlatformContext as l, type AgentReaction as m, type AgentReplyPayload as n, type AgentSubscriber as o, type MetadataSignal as p, type ReplyHandle as q, type SentMessageInfo as r, type Signal as s, agent as t, workflow as w };
+export { type Agent as A, Client as C, type EditPayload as E, type FileRef as F, type INovuRequestHandlerOptions as I, type MessageContent as M, NovuRequestHandler as N, type ReplyContent as R, type ServeHandlerOptions as S, type TriggerSignal as T, type AgentAction as a, type AgentActionContext as b, type AgentAttachment as c, type AgentBridgeRequest as d, type AgentContext as e, type AgentConversation as f, AgentDeliveryError as g, AgentEventEnum as h, type AgentHandlers as i, type AgentHistoryEntry as j, type AgentMessage as k, type AgentMessageAuthor as l, type AgentMessageContext as m, type AgentPlatformContext as n, type AgentReaction as o, type AgentReactionContext as p, type AgentReplyPayload as q, type AgentResolveContext as r, type AgentSubscriber as s, type MetadataSignal as t, type ReplyHandle as u, type SentMessageInfo as v, type Signal as w, agent as x, workflow as y };