@novu/framework 2.12.1 → 2.13.0

package/dist/cjs/{index-1DobCKAF.d.cts → index-CLZZRnNV.d.cts}

@@ -106,6 +106,30 @@ interface ServeHandlerOptions {
     client?: Client;
     workflows?: Array<Workflow>;
     agents?: Array<Agent>;
+    /**
+     * Extends the lifetime of the request handler until the given promise settles.
+     *
+     * Agent events are acknowledged immediately while the turn (LLM calls, replies,
+     * tool use) continues in the background. On serverless platforms the runtime is
+     * frozen as soon as the response is sent, so the background work is silently
+     * dropped unless a platform `waitUntil` primitive is provided.
+     *
+     * The Next.js adapter (on Next.js >= 15.1) and the Hono adapter (on Cloudflare
+     * Workers) wire this automatically. Provide it explicitly for other serverless
+     * platforms, or to override the automatic detection.
+     *
+     * @example Cloudflare Workers (without Hono)
+     * ```ts
+     * export default {
+     *   async fetch(request, env, ctx) {
+     *     const handler = serve({ agents: [myAgent], waitUntil: (promise) => ctx.waitUntil(promise) });
+     *
+     *     return handler(request);
+     *   },
+     * };
+     * ```
+     */
+    waitUntil?: (promise: Promise<unknown>) => void;
 }
 type INovuRequestHandlerOptions<Input extends any[] = any[], Output = any> = ServeHandlerOptions & {
     frameworkName: string;
@@ -137,6 +161,7 @@ declare class NovuRequestHandler<Input extends any[] = any[], Output = any> {
     private readonly http;
     private readonly workflows;
     private readonly agents;
+    private readonly waitUntil?;
     constructor(options: INovuRequestHandlerOptions<Input, Output>);
     createHandler(): (...args: Input) => Promise<Output>;
     private getStaticHeaders;
@@ -144,6 +169,14 @@ declare class NovuRequestHandler<Input extends any[] = any[], Output = any> {
     private createError;
     private handleAction;
     private getPostActionMap;
+    /**
+     * Agent events are acknowledged immediately and the turn continues in the
+     * background. On serverless platforms the runtime freezes once the response
+     * is sent, so without a `waitUntil` primitive the turn is silently dropped
+     * mid-flight. Detecting the known freeze-prone platforms lets us surface an
+     * actionable warning instead of logs that just stop with no error.
+     */
+    private warnOnUnprotectedServerlessRuntime;
     triggerAction(triggerEvent: EventTriggerParams): () => Promise<IActionResponse<string>>;
     private getGetActionMap;
     private handlePostAction;