@novu/framework 2.11.0 → 2.11.2-alpha.0

package/dist/cjs/cards.d.cts

@@ -0,0 +1,2 @@
+export { Actions, ActionsElement, Button, ButtonElement, Card, CardChild, CardElement, CardLink, CardText, Divider, DividerElement, LinkElement, Select, SelectElement, SelectOption, SelectOptionElement, TextElement, TextInput, TextInputElement } from 'chat';
+import 'chat/jsx-runtime';

package/dist/cjs/{health-check.types-uaDLF5bo.d.cts → health-check.types-CkUmYLNG.d.cts}

@@ -1,147 +1,27 @@
-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-PRaHFLJu.cjs';
+import { a as ContextPayload, b as Step, S as Subscriber, E as EnvironmentSystemVariables, C as ContextResolved, c as ChannelStepEnum, A as ActionStepEnum, W as WithPassthrough, d as StepOptions } from './subscriber.types-DxMMRBIi.cjs';
+import { I as ITriggerPayload, t as TriggerRecipientsPayload, u as ISubscriberPayload, v as TriggerEventStatusEnum, W as WorkflowPreferencesPartial } from './agent.types-DdgaVUb7.cjs';
+import { C as ConditionalPartial, P as PickRequiredKeys, a as Prettify, D as DeepPartial, A as Awaitable } from './util.types-DaFfsxgy.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",
-    Telegram = "telegram"
-}
-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;
 };
 
+/**
+ * A minimal logger interface used for all of the framework's internal logging
+ * (workflow discovery, execution and bridge error reporting).
+ *
+ * The methods (`info`/`warn`/`error`) are chosen so that both the global
+ * `console` and common structured loggers (pino, winston, ...) satisfy this
+ * interface directly, with no adapter. The global `console` is the default;
+ * provide your own to route Novu's internal logs wherever the rest of your
+ * application logs go.
+ */
+type Logger = {
+    info: typeof console.info;
+    warn: typeof console.warn;
+    error: typeof console.error;
+};
 type ClientOptions = {
     /**
      * Use Novu Cloud US (https://api.novu.co) or EU deployment (https://eu.api.novu.co). Defaults to US.
@@ -171,6 +51,19 @@ type ClientOptions = {
      * Defaults to `true` in development, `false` in production.
      */
     verbose?: boolean;
+    /**
+     * A custom logger used for all of the framework's internal logging
+     * (workflow discovery, execution and bridge error reporting).
+     *
+     * Defaults to the global `console`. Provide your own logger to route Novu's
+     * internal logs through your application's structured logger.
+     *
+     * Note: `verbose` still controls *whether* discovery and execution logs are
+     * emitted; `logger` only controls *where* all logs are written. Bridge errors
+     * (HTTP status >= 500) are always logged via this logger, regardless of
+     * `verbose`.
+     */
+    logger?: Logger;
 };
 
 declare enum PostActionEnum {
@@ -453,7 +346,7 @@ type ChannelPreference = {
 /**
  * A partial set of workflow preferences.
  */
-type WorkflowPreferences = DeepPartial$1<{
+type WorkflowPreferences = DeepPartial<{
     /**
      * A default preference for the channels.
      *
@@ -660,6 +553,7 @@ type Event = {
     state: State[];
     action: Exclude<PostActionEnum, PostActionEnum.TRIGGER>;
     subscriber: Subscriber;
+    actor?: Subscriber;
     context: ContextResolved;
     /** User-defined env vars merged with environment system variables (name, type). */
     env: EnvironmentSystemVariables & Record<string, string>;
@@ -700,4 +594,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 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 };
+export { type ClientOptions as C, type DiscoverAgentOutput as D, type ExecuteInput as E, GetActionEnum as G, type HealthCheck as H, type Logger as L, 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 };

package/dist/cjs/index-BCp3U0UG.d.cts

@@ -0,0 +1,189 @@
+import { g as AgentHandlers, A as Agent } from './agent.types-DdgaVUb7.cjs';
+import { L as Logger, 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-CkUmYLNG.cjs';
+import { A as Awaitable } from './util.types-DaFfsxgy.cjs';
+import 'chat';
+import { S as Schema, a as FromSchema, F as FromSchemaUnvalidated } from './base.schema.types-BApIn9jr.cjs';
+import './step-resolver.cjs';
+import './subscriber.types-DxMMRBIi.cjs';
+
+/**
+ * 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.
+ *
+ * @param agentId - Unique identifier matching the agent entity created in Novu (e.g. 'wine-bot')
+ * @param handlers - Handler functions for agent events
+ */
+declare function agent(agentId: string, handlers: AgentHandlers): Agent;
+
+declare class Client {
+    private discoveredWorkflows;
+    private discoverWorkflowPromises;
+    private registeredAgents;
+    private templateEngine;
+    secretKey: string;
+    apiUrl: string;
+    version: string;
+    strictAuthentication: boolean;
+    verbose: boolean;
+    logger: Logger;
+    constructor(options?: ClientOptions);
+    private buildOptions;
+    private log;
+    /**
+     * Adds workflows to the client.
+     *
+     * A locking mechanism is used to ensure that duplicate workflows are not added.
+     *
+     * @param workflows - The workflows to add.
+     */
+    addWorkflows(workflows: Array<Workflow>): Promise<void>;
+    addAgents(agents: Array<Agent>): void;
+    getAgent(agentId: string): Agent | undefined;
+    private addWorkflow;
+    healthCheck(): HealthCheck;
+    private getWorkflow;
+    private getStep;
+    private getRegisteredWorkflows;
+    discover(): DiscoverOutput;
+    /**
+     * Mocks data based on the given schema.
+     * The `default` value in the schema is used as the base data.
+     * If no `default` value is provided, the data is generated using JSONSchemaFaker.
+     *
+     * @param schema
+     * @returns mocked data
+     */
+    private mock;
+    private validate;
+    private throwInvalidProvider;
+    private throwInvalidStep;
+    private throwInvalidEvent;
+    private executeStepFactory;
+    private shouldSanitize;
+    private shouldSkip;
+    executeWorkflow(event: Event): Promise<ExecuteOutput>;
+    private createExecutionPayload;
+    private prettyPrintExecute;
+    private executeProviders;
+    private previewProvider;
+    private executeProvider;
+    private executeStep;
+    private compileControls;
+    /**
+     * Preprocesses standalone translation patterns.
+     * Transforms {{t.key}} to [T:key] placeholder (not Liquid syntax, passes through unchanged).
+     */
+    private preprocessTranslationPatterns;
+    /**
+     * Preprocesses translation keys used as filter arguments.
+     * Transforms 't.key' to '[T:key]' placeholder (not Liquid syntax, passes through unchanged).
+     * Example: pluralize: 't.apple', 't.apples' → pluralize: '[T:apple]', '[T:apples]'
+     */
+    private preprocessFilterTranslationArgs;
+    /**
+     * Post-processes placeholders back to translation markers after Liquid render.
+     * Transforms [T:key] back to {{t.key}} for the translation service.
+     */
+    private postprocessTranslationMarkers;
+    /**
+     * Create the controls for a step, taking both the event controls and the default controls into account
+     *
+     * @param step The step to create the controls for
+     * @param event The event that triggered the step
+     * @returns The controls for the step
+     */
+    private createStepControls;
+    private previewStep;
+    private constructStepForPreview;
+    private extractMockDataForPreviousSteps;
+    private previewRequiredStep;
+    private getStepState;
+    private getStepCode;
+    private getWorkflowCode;
+    getCode(workflowId: string, stepId?: string): CodeResult;
+}
+
+interface ServeHandlerOptions {
+    client?: Client;
+    workflows?: Array<Workflow>;
+    agents?: Array<Agent>;
+}
+type INovuRequestHandlerOptions<Input extends any[] = any[], Output = any> = ServeHandlerOptions & {
+    frameworkName: string;
+    client?: Client;
+    workflows?: Array<Workflow>;
+    agents?: Array<Agent>;
+    handler: Handler<Input, Output>;
+};
+type Handler<Input extends any[] = any[], Output = any> = (...args: Input) => HandlerResponse<Output>;
+type HandlerResponse<Output = any> = {
+    body: () => Awaitable<any>;
+    headers: (key: string) => Awaitable<string | null | undefined>;
+    method: () => Awaitable<string>;
+    queryString?: (key: string, url: URL) => Awaitable<string | null | undefined>;
+    url: () => Awaitable<URL>;
+    transformResponse: (res: IActionResponse<string>) => Output;
+    waitUntil?: (promise: Promise<unknown>) => void;
+};
+type IActionResponse<TBody extends string = string> = {
+    status: number;
+    headers: Record<string, string>;
+    body: TBody;
+};
+declare class NovuRequestHandler<Input extends any[] = any[], Output = any> {
+    readonly frameworkName: string;
+    readonly handler: Handler<Input, Output>;
+    readonly client: Client;
+    private readonly hmacEnabled;
+    private readonly http;
+    private readonly workflows;
+    private readonly agents;
+    constructor(options: INovuRequestHandlerOptions<Input, Output>);
+    createHandler(): (...args: Input) => Promise<Output>;
+    private getStaticHeaders;
+    private createResponse;
+    private createError;
+    private handleAction;
+    private getPostActionMap;
+    triggerAction(triggerEvent: EventTriggerParams): () => Promise<IActionResponse<string>>;
+    private getGetActionMap;
+    private handlePostAction;
+    private handleGetAction;
+    private handleError;
+    private validateHmac;
+}
+
+/**
+ * Define a new notification workflow.
+ */
+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 { AgentDeliveryError as A, Client as C, type INovuRequestHandlerOptions as I, NovuRequestHandler as N, type ServeHandlerOptions as S, agent as a, workflow as w };