@novu/framework 2.10.1-alpha.2 → 2.10.1-alpha.4

package/dist/cjs/{health-check.types-Nhsa_lGZ.d.cts → health-check.types-S8oS3AQZ.d.cts}

@@ -1,6 +1,142 @@
-import { b as ContextPayload, c as ConditionalPartial, P as PickRequiredKeys, d as Step, e as Prettify, S as Subscriber, E as EnvironmentSystemVariables, C as ContextResolved, D as DeepPartial$1, f as ChannelStepEnum, A as ActionStepEnum, g as Awaitable, W as WithPassthrough, h as StepOptions } from './subscriber.types-CNLicO8m.cjs';
+import { b as ContextPayload, c as ConditionalPartial, P as PickRequiredKeys, d as Step, e as Prettify, S as Subscriber, E as EnvironmentSystemVariables, C as ContextResolved, D as DeepPartial$1, f as ChannelStepEnum, A as ActionStepEnum, g as Awaitable, W as WithPassthrough, h as StepOptions } from './subscriber.types-DgRgSKMw.cjs';
 import { S as Schema, J as JsonSchema } from './base.schema.types-BApIn9jr.cjs';
 
+declare enum ChannelTypeEnum {
+    IN_APP = "in_app",
+    EMAIL = "email",
+    SMS = "sms",
+    CHAT = "chat",
+    PUSH = "push"
+}
+interface IAttachmentOptions {
+    mime: string;
+    file: Buffer;
+    name?: string;
+    channels?: ChannelTypeEnum[];
+    cid?: string;
+    disposition?: string;
+}
+interface ITriggerPayload {
+    attachments?: IAttachmentOptions[];
+    [key: string]: string | string[] | boolean | number | undefined | IAttachmentOptions | IAttachmentOptions[] | Record<string, unknown>;
+}
+interface ISubscriberPayload {
+    subscriberId: string;
+    firstName?: string;
+    lastName?: string;
+    email?: string;
+    phone?: string;
+    avatar?: string;
+    locale?: string;
+    data?: Record<string, unknown>;
+    channels?: ISubscriberChannel[];
+}
+interface ISubscriberChannel {
+    providerId: ChatProviderIdEnum | PushProviderIdEnum;
+    integrationIdentifier?: string;
+    credentials: IChannelCredentials;
+}
+interface IChannelCredentials {
+    webhookUrl?: string;
+    deviceTokens?: string[];
+}
+interface ITopic {
+    type: 'Topic';
+    topicKey: string;
+    exclude?: string[];
+}
+type TriggerRecipientsPayload = string | ISubscriberPayload | ITopic | ISubscriberPayload[] | ITopic[];
+declare enum TriggerEventStatusEnum {
+    ERROR = "error",
+    NOT_ACTIVE = "trigger_not_active",
+    NO_WORKFLOW_ACTIVE_STEPS = "no_workflow_active_steps_defined",
+    NO_WORKFLOW_STEPS = "no_workflow_steps_defined",
+    PROCESSED = "processed",
+    SUBSCRIBER_MISSING = "subscriber_id_missing",
+    TENANT_MISSING = "no_tenant_found"
+}
+declare enum ChatProviderIdEnum {
+    Slack = "slack",
+    Discord = "discord",
+    MsTeams = "msteams",
+    Mattermost = "mattermost",
+    Ryver = "ryver",
+    Zulip = "zulip",
+    GrafanaOnCall = "grafana-on-call",
+    GetStream = "getstream",
+    RocketChat = "rocket-chat",
+    WhatsAppBusiness = "whatsapp-business",
+    ChatWebhook = "chat-webhook"
+}
+declare enum PushProviderIdEnum {
+    FCM = "fcm",
+    APNS = "apns",
+    EXPO = "expo",
+    OneSignal = "one-signal",
+    Pushpad = "pushpad",
+    PushWebhook = "push-webhook",
+    PusherBeams = "pusher-beams",
+    AppIO = "appio"
+}
+/**
+ * A preference for a notification delivery workflow.
+ *
+ * This provides a shortcut to setting all channels to the same preference.
+ */
+type WorkflowPreference$1 = {
+    /**
+     * A flag specifying if notification delivery is enabled for the workflow.
+     *
+     * If `true`, notification delivery is enabled by default for all channels.
+     *
+     * This setting can be overridden by the channel preferences.
+     *
+     * @default true
+     */
+    enabled: boolean;
+    /**
+     * A flag specifying if the preference is read-only.
+     *
+     * If `true`, the preference cannot be changed by the Subscriber.
+     *
+     * @default false
+     */
+    readOnly: boolean;
+};
+/** A preference for a notification delivery channel. */
+type ChannelPreference$1 = {
+    /**
+     * A flag specifying if notification delivery is enabled for the channel.
+     *
+     * If `true`, notification delivery is enabled.
+     *
+     * @default true
+     */
+    enabled: boolean;
+};
+type WorkflowPreferences$1 = {
+    /**
+     * A preference for the workflow.
+     *
+     * The values specified here will be used if no preference is specified for a channel.
+     */
+    all: WorkflowPreference$1;
+    /**
+     * A preference for each notification delivery channel.
+     *
+     * If no preference is specified for a channel, the `all` preference will be used.
+     */
+    channels: Record<ChannelTypeEnum, ChannelPreference$1>;
+};
+/**
+ * Recursively make all properties of type `T` optional.
+ */
+type DeepPartial<T> = T extends object ? {
+    [P in keyof T]?: DeepPartial<T[P]>;
+} : T;
+/** A partial set of workflow preferences. */
+type WorkflowPreferencesPartial = DeepPartial<WorkflowPreferences$1>;
+
 type CodeResult = {
     code: string;
 };
@@ -151,142 +287,6 @@ declare enum WorkflowChannelEnum {
     IN_APP = "inApp"
 }
 
-declare enum ChannelTypeEnum {
-    IN_APP = "in_app",
-    EMAIL = "email",
-    SMS = "sms",
-    CHAT = "chat",
-    PUSH = "push"
-}
-interface IAttachmentOptions {
-    mime: string;
-    file: Buffer;
-    name?: string;
-    channels?: ChannelTypeEnum[];
-    cid?: string;
-    disposition?: string;
-}
-interface ITriggerPayload {
-    attachments?: IAttachmentOptions[];
-    [key: string]: string | string[] | boolean | number | undefined | IAttachmentOptions | IAttachmentOptions[] | Record<string, unknown>;
-}
-interface ISubscriberPayload {
-    subscriberId: string;
-    firstName?: string;
-    lastName?: string;
-    email?: string;
-    phone?: string;
-    avatar?: string;
-    locale?: string;
-    data?: Record<string, unknown>;
-    channels?: ISubscriberChannel[];
-}
-interface ISubscriberChannel {
-    providerId: ChatProviderIdEnum | PushProviderIdEnum;
-    integrationIdentifier?: string;
-    credentials: IChannelCredentials;
-}
-interface IChannelCredentials {
-    webhookUrl?: string;
-    deviceTokens?: string[];
-}
-interface ITopic {
-    type: 'Topic';
-    topicKey: string;
-    exclude?: string[];
-}
-type TriggerRecipientsPayload = string | ISubscriberPayload | ITopic | ISubscriberPayload[] | ITopic[];
-declare enum TriggerEventStatusEnum {
-    ERROR = "error",
-    NOT_ACTIVE = "trigger_not_active",
-    NO_WORKFLOW_ACTIVE_STEPS = "no_workflow_active_steps_defined",
-    NO_WORKFLOW_STEPS = "no_workflow_steps_defined",
-    PROCESSED = "processed",
-    SUBSCRIBER_MISSING = "subscriber_id_missing",
-    TENANT_MISSING = "no_tenant_found"
-}
-declare enum ChatProviderIdEnum {
-    Slack = "slack",
-    Discord = "discord",
-    MsTeams = "msteams",
-    Mattermost = "mattermost",
-    Ryver = "ryver",
-    Zulip = "zulip",
-    GrafanaOnCall = "grafana-on-call",
-    GetStream = "getstream",
-    RocketChat = "rocket-chat",
-    WhatsAppBusiness = "whatsapp-business",
-    ChatWebhook = "chat-webhook"
-}
-declare enum PushProviderIdEnum {
-    FCM = "fcm",
-    APNS = "apns",
-    EXPO = "expo",
-    OneSignal = "one-signal",
-    Pushpad = "pushpad",
-    PushWebhook = "push-webhook",
-    PusherBeams = "pusher-beams",
-    AppIO = "appio"
-}
-/**
- * A preference for a notification delivery workflow.
- *
- * This provides a shortcut to setting all channels to the same preference.
- */
-type WorkflowPreference$1 = {
-    /**
-     * A flag specifying if notification delivery is enabled for the workflow.
-     *
-     * If `true`, notification delivery is enabled by default for all channels.
-     *
-     * This setting can be overridden by the channel preferences.
-     *
-     * @default true
-     */
-    enabled: boolean;
-    /**
-     * A flag specifying if the preference is read-only.
-     *
-     * If `true`, the preference cannot be changed by the Subscriber.
-     *
-     * @default false
-     */
-    readOnly: boolean;
-};
-/** A preference for a notification delivery channel. */
-type ChannelPreference$1 = {
-    /**
-     * A flag specifying if notification delivery is enabled for the channel.
-     *
-     * If `true`, notification delivery is enabled.
-     *
-     * @default true
-     */
-    enabled: boolean;
-};
-type WorkflowPreferences$1 = {
-    /**
-     * A preference for the workflow.
-     *
-     * The values specified here will be used if no preference is specified for a channel.
-     */
-    all: WorkflowPreference$1;
-    /**
-     * A preference for each notification delivery channel.
-     *
-     * If no preference is specified for a channel, the `all` preference will be used.
-     */
-    channels: Record<ChannelTypeEnum, ChannelPreference$1>;
-};
-/**
- * Recursively make all properties of type `T` optional.
- */
-type DeepPartial<T> = T extends object ? {
-    [P in keyof T]?: DeepPartial<T[P]>;
-} : T;
-/** A partial set of workflow preferences. */
-type WorkflowPreferencesPartial = DeepPartial<WorkflowPreferences$1>;
-
 type EventPayload = ITriggerPayload;
 type Actor = string | ISubscriberPayload;
 type Recipients = TriggerRecipientsPayload;
@@ -699,4 +699,4 @@ type HealthCheck = {
     };
 };
 
-export { type ClientOptions as C, type DiscoverAgentOutput as D, type ExecuteInput as E, GetActionEnum as G, type HealthCheck as H, PostActionEnum as P, SeverityLevelEnum as S, type Workflow as W, CronExpression as a, type CancelEventTriggerResponse as b, type ChannelPreference as c, type CodeResult as d, type DiscoverOutput as e, type DiscoverProviderOutput as f, type DiscoverStepOutput as g, type DiscoverWorkflowOutput as h, type Event as i, type EventTriggerParams as j, type EventTriggerResponse as k, type EventTriggerResult as l, type Execute as m, type ExecuteOutput as n, type ExecuteOutputMetadata as o, type ExecuteOutputOptions as p, type State as q, type StepType as r, WorkflowChannelEnum as s, type WorkflowOptions as t, type WorkflowPreference as u, type WorkflowPreferences as v };
+export { type ClientOptions as C, type DiscoverAgentOutput as D, type ExecuteInput as E, GetActionEnum as G, type HealthCheck as H, PostActionEnum as P, SeverityLevelEnum as S, type TriggerRecipientsPayload as T, type Workflow as W, CronExpression as a, type CancelEventTriggerResponse as b, type ChannelPreference as c, type CodeResult as d, type DiscoverOutput as e, type DiscoverProviderOutput as f, type DiscoverStepOutput as g, type DiscoverWorkflowOutput as h, type Event as i, type EventTriggerParams as j, type EventTriggerResponse as k, type EventTriggerResult as l, type Execute as m, type ExecuteOutput as n, type ExecuteOutputMetadata as o, type ExecuteOutputOptions as p, type State as q, type StepType as r, WorkflowChannelEnum as s, type WorkflowOptions as t, type WorkflowPreference as u, type WorkflowPreferences as v };

package/dist/cjs/{index-gi0_Wcu3.d.cts → index-ZVAtl8F3.d.cts}

@@ -1,6 +1,6 @@
-import { ChatElement, CardElement } from 'chat';
-import { C as ClientOptions, W as Workflow, H as HealthCheck, e as DiscoverOutput, i as Event, n as ExecuteOutput, d as CodeResult, j as EventTriggerParams, m as Execute, t as WorkflowOptions } from './health-check.types-Nhsa_lGZ.cjs';
-import { g as Awaitable } from './subscriber.types-CNLicO8m.cjs';
+import { ChatElement, Emoji, CardElement } from 'chat';
+import { T as TriggerRecipientsPayload, C as ClientOptions, W as Workflow, H as HealthCheck, e as DiscoverOutput, i as Event, n as ExecuteOutput, d as CodeResult, j as EventTriggerParams, m as Execute, t as WorkflowOptions } from './health-check.types-S8oS3AQZ.cjs';
+import { g as Awaitable } from './subscriber.types-DgRgSKMw.cjs';
 import { S as Schema, a as FromSchema, F as FromSchemaUnvalidated } from './base.schema.types-BApIn9jr.cjs';
 import './step-resolver.cjs';
 
@@ -76,18 +76,14 @@ interface FileRef {
 /**
  * Content accepted by ctx.reply() and handle.edit().
  *
- * - `string` — plain text
- * - `{ markdown, files? }` — markdown-formatted text, optionally with file attachments
+ * - `string` — plain text or markdown; converted to platform format by the chat SDK
  * - `ChatElement` — interactive card built with Card(), Button(), etc.
- *   (must be a CardElement at runtime; validated by serializeContent)
+ *
+ * For file attachments, pass a `files` array as the second argument to reply()/edit().
  */
-type MessageContent = string | {
-    markdown: string;
-    files?: FileRef[];
-} | ChatElement;
+type MessageContent = string | ChatElement;
 /** Normalized content shape sent over HTTP to the reply endpoint. */
 interface ReplyContent {
-    text?: string;
     markdown?: string;
     card?: CardElement;
     files?: FileRef[];
@@ -115,7 +111,9 @@ interface ReplyHandle {
     /** Platform-native thread id this message lives in. */
     readonly platformThreadId: string;
     /** Edit this message in place with new content. Returns the same handle for chaining. */
-    edit(content: MessageContent): Promise<ReplyHandle>;
+    edit(content: MessageContent, options?: {
+        files?: FileRef[];
+    }): Promise<ReplyHandle>;
 }
 interface AgentContext {
     readonly event: string;
@@ -133,24 +131,63 @@ interface AgentContext {
      *
      * @example
      *   const msg = await ctx.reply('Thinking…');
-     *   // ... do work ...
      *   await msg.edit('Here is the answer');
+     *
+     * @example with file attachment
+     *   await ctx.reply('Here is your report', {
+     *     files: [{ filename: 'report.pdf', url: 'https://...' }],
+     *   });
      */
-    reply(content: MessageContent): Promise<ReplyHandle>;
+    reply(content: MessageContent, options?: {
+        files?: FileRef[];
+    }): Promise<ReplyHandle>;
     resolve(summary?: string): void;
     metadata: {
         set(key: string, value: unknown): void;
     };
+    /**
+     * Trigger a Novu workflow from within this agent handler.
+     *
+     * Signals are batched and flushed with the next `ctx.reply()`, or automatically when the
+     * handler completes. The workflow executes asynchronously — the agent reply is not blocked.
+     *
+     * @param workflowId - Workflow identifier (e.g. `'escalation-email'`).
+     * @param opts.to - Recipient(s). Omit to target the conversation's resolved subscriber.
+     * @param opts.payload - Data forwarded to the workflow payload schema.
+     *
+     * @example
+     *   // Target the conversation subscriber automatically
+     *   ctx.trigger('follow-up-email', { payload: { reason: 'unresolved' } });
+     *
+     *   // Explicit recipient
+     *   ctx.trigger('escalation-email', { to: 'agent-inbox', payload: { priority: 'high' } });
+     *
+     *   // Topic broadcast
+     *   ctx.trigger('team-alert', { to: { type: 'Topic', topicKey: 'support-team' } });
+     */
     trigger(workflowId: string, opts?: {
-        to?: string;
+        to?: TriggerRecipientsPayload;
         payload?: Record<string, unknown>;
     }): void;
+    /**
+     * Add an emoji reaction to any platform message.
+     * Reactions are queued and sent with the next `ctx.reply()`, or flushed automatically
+     * when the handler completes (same batching contract as `ctx.trigger()`).
+     *
+     * @param messageId - Platform-native message ID to react to (e.g. Slack `ts`).
+     * @param emojiName - Emoji short-name (e.g. `'thumbs_up'`, `'check_mark'`).
+     *
+     * @example
+     *   ctx.addReaction(ctx.reaction!.messageId, 'check_mark');
+     *   await ctx.reply('Done!');
+     */
+    addReaction(messageId: string, emojiName: Emoji): void;
 }
 interface AgentHandlers {
-    onMessage: (ctx: AgentContext) => Promise<void>;
-    onReaction?: (ctx: AgentContext) => Promise<void>;
-    onAction?: (ctx: AgentContext) => Promise<void>;
-    onResolve?: (ctx: AgentContext) => Promise<void>;
+    onMessage: (ctx: AgentContext) => Awaitable<MessageContent | void>;
+    onReaction?: (ctx: AgentContext) => Awaitable<MessageContent | void>;
+    onAction?: (ctx: AgentContext) => Awaitable<MessageContent | void>;
+    onResolve?: (ctx: AgentContext) => Awaitable<MessageContent | void>;
 }
 interface Agent {
     id: string;
@@ -179,10 +216,19 @@ type MetadataSignal = {
     key: string;
     value: unknown;
 };
+/**
+ * Queued by `ctx.trigger()` — instructs Novu to fire a workflow from inside an agent handler.
+ *
+ * - `workflowId` — the workflow identifier (same string used in `novu.events.trigger()`).
+ * - `to` — recipient(s) for the workflow. Accepts a subscriberId string, a subscriber object,
+ *   a topic, or arrays thereof. When omitted, Novu falls back to the conversation's resolved
+ *   subscriber. If no subscriber can be resolved, the trigger is skipped and a warning is logged.
+ * - `payload` — arbitrary data forwarded to the workflow's payload schema.
+ */
 type TriggerSignal = {
     type: 'trigger';
     workflowId: string;
-    to?: string;
+    to?: TriggerRecipientsPayload;
     payload?: Record<string, unknown>;
 };
 type Signal = MetadataSignal | TriggerSignal;
@@ -191,6 +237,11 @@ interface EditPayload {
     messageId: string;
     content: ReplyContent;
 }
+/** An emoji reaction to be added to a platform message. */
+interface AddReactionPayload {
+    messageId: string;
+    emojiName: Emoji;
+}
 interface AgentReplyPayload {
     conversationId: string;
     integrationIdentifier: string;
@@ -200,6 +251,7 @@ interface AgentReplyPayload {
         summary?: string;
     };
     signals?: Signal[];
+    addReactions?: AddReactionPayload[];
 }
 /** Shape returned by /agents/:id/reply when a reply or edit was delivered. */
 interface SentMessageInfo {
@@ -207,6 +259,35 @@ interface SentMessageInfo {
     platformThreadId: string;
 }
 
+/**
+ * Thrown by `ctx.reply()` and `handle.edit()` when the upstream message delivery
+ * fails — e.g. the configured email provider returns 401, Slack rejects the token,
+ * or Teams rejects the request.
+ *
+ * `message` is always a short, human-readable summary.
+ * `responseBody` preserves the raw upstream body for debugging.
+ *
+ * @example
+ * ```ts
+ * import { AgentDeliveryError } from '@novu/framework';
+ *
+ * try {
+ *   await ctx.reply('Hello!');
+ * } catch (err) {
+ *   if (err instanceof AgentDeliveryError) {
+ *     console.error('Delivery failed:', err.message);
+ *     return;
+ *   }
+ *   throw err;
+ * }
+ * ```
+ */
+declare class AgentDeliveryError extends Error {
+    readonly statusCode: number;
+    readonly responseBody: string;
+    constructor(statusCode: number, responseBody: string);
+}
+
 /**
  * Define a new conversational agent.
  *
@@ -358,4 +439,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, AgentEventEnum as f, type AgentHandlers as g, type AgentHistoryEntry as h, type AgentMessage as i, type AgentMessageAuthor as j, type AgentPlatformContext as k, type AgentReaction as l, type AgentReplyPayload as m, type AgentSubscriber as n, type MetadataSignal as o, type ReplyHandle as p, type SentMessageInfo as q, type Signal as r, agent as s, 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 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 };