import { Client } from './client'; import { GetActionEnum, HttpHeaderKeysEnum, HttpMethodEnum, HttpQueryKeysEnum, HttpStatusEnum, PostActionEnum, SIGNATURE_TIMESTAMP_TOLERANCE, } from './constants'; import { BridgeError, FrameworkError, InvalidActionError, isFrameworkError, MethodNotAllowedError, SignatureExpiredError, SignatureInvalidError, SignatureMismatchError, SignatureNotFoundError, SigningKeyNotFoundError, } from './errors'; import { isPlatformError } from './errors/guard.errors'; import type { Agent } from './resources/agent'; import { type AgentBridgeRequest, AgentEventEnum } from './resources/agent/agent.types'; import { dispatchAgentEvent } from './resources/agent/agent-dispatch'; import { AgentLiveStream } from './resources/agent/agent-live-stream'; import type { Awaitable, EventTriggerParams, Workflow } from './types'; import { createHmacSubtle, initApiClient, timingSafeEqual } from './utils'; import { parseSignatureHeader } from './utils/bridge-signature'; /** Novu sends `onAbort` only to a bridge that lists it here: older frameworks fail the turn on an unknown event. */ const HANDLED_AGENT_EVENTS = Object.values(AgentEventEnum).join(','); export interface ServeHandlerOptions { client?: Client; workflows?: Array; agents?: Array; /** * 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) => void; } // biome-ignore lint/suspicious/noExplicitAny: each framework adapter supplies its own request and response types export type INovuRequestHandlerOptions = ServeHandlerOptions & { frameworkName: string; client?: Client; workflows?: Array; agents?: Array; handler: Handler; }; // biome-ignore lint/suspicious/noExplicitAny: each framework adapter supplies its own request and response types type Handler = (...args: Input) => HandlerResponse; // biome-ignore lint/suspicious/noExplicitAny: each framework adapter supplies its own response type type HandlerResponse = { // biome-ignore lint/suspicious/noExplicitAny: request bodies are not validated per action yet body: () => Awaitable; headers: (key: string) => Awaitable; method: () => Awaitable; queryString?: (key: string, url: URL) => Awaitable; url: () => Awaitable; transformResponse: (res: IActionResponse) => Output; /** Sends a streamed body. Adapters without it (e.g. Lambda behind API Gateway) never stream. */ transformStreamResponse?: (res: IActionStreamResponse) => Output; waitUntil?: (promise: Promise) => void; }; export type IActionResponse = { status: number; headers: Record; body: TBody; /** Replaces `body` on adapters that implement `transformStreamResponse`. */ stream?: ReadableStream; }; export type IActionStreamResponse = Omit & { body: ReadableStream }; // biome-ignore lint/suspicious/noExplicitAny: each framework adapter supplies its own request and response types export class NovuRequestHandler { public readonly frameworkName: string; public readonly handler: Handler; public readonly client: Client; private readonly hmacEnabled: boolean; private readonly http; private readonly workflows: Array; private readonly agents: Array; private readonly waitUntil?: (promise: Promise) => void; constructor(options: INovuRequestHandlerOptions) { this.handler = options.handler; this.client = options.client ? options.client : new Client(); this.workflows = options.workflows || []; this.agents = options.agents || []; this.http = initApiClient(this.client.secretKey, this.client.apiUrl); this.frameworkName = options.frameworkName; this.hmacEnabled = this.client.strictAuthentication; this.waitUntil = options.waitUntil; this.client.addAgents(this.agents); } public createHandler(): (...args: Input) => Promise { return async (...args: Input) => { await this.client.addWorkflows(this.workflows); const actions = await this.handler(...args); const { stream, ...actionResponse } = await this.handleAction({ actions, }); if (stream && actions.transformStreamResponse) { const headers: Record = { ...actionResponse.headers, [HttpHeaderKeysEnum.CONTENT_TYPE]: 'text/event-stream', // no-transform: compression (e.g. Next.js Pages Router, `compression` middleware) would buffer the stream. [HttpHeaderKeysEnum.CACHE_CONTROL]: 'no-cache, no-transform', }; // Only Novu reads live replies, server to server; no browser origin may read them. delete headers[HttpHeaderKeysEnum.ACCESS_CONTROL_ALLOW_ORIGIN]; return actions.transformStreamResponse({ status: actionResponse.status, headers, body: stream }); } return actions.transformResponse(actionResponse); }; } private getStaticHeaders(): Partial> { const sdkVersion = `novu-framework:v${this.client.version}`; return { [HttpHeaderKeysEnum.CONTENT_TYPE]: 'application/json', [HttpHeaderKeysEnum.ACCESS_CONTROL_ALLOW_ORIGIN]: '*', [HttpHeaderKeysEnum.ACCESS_CONTROL_ALLOW_PRIVATE_NETWORK]: 'true', [HttpHeaderKeysEnum.ACCESS_CONTROL_ALLOW_METHODS]: 'GET, POST', [HttpHeaderKeysEnum.ACCESS_CONTROL_ALLOW_HEADERS]: '*', [HttpHeaderKeysEnum.ACCESS_CONTROL_MAX_AGE]: '604800', [HttpHeaderKeysEnum.NOVU_FRAMEWORK_VERSION]: FRAMEWORK_VERSION, [HttpHeaderKeysEnum.NOVU_FRAMEWORK_SDK]: SDK_VERSION, [HttpHeaderKeysEnum.NOVU_FRAMEWORK_SERVER]: this.frameworkName, [HttpHeaderKeysEnum.NOVU_FRAMEWORK_AGENT_EVENTS]: HANDLED_AGENT_EVENTS, [HttpHeaderKeysEnum.USER_AGENT]: sdkVersion, }; } private createResponse(status: number, body: unknown): IActionResponse { return { status, body: JSON.stringify(body) as TBody, headers: { ...this.getStaticHeaders(), }, }; } private createError(error: FrameworkError): IActionResponse { return { status: error.statusCode, body: JSON.stringify({ message: error.message, data: error.data, code: error.code, }) as TBody, headers: this.getStaticHeaders(), }; } private async handleAction({ actions }: { actions: HandlerResponse }): Promise { const url = await actions.url(); const method = await actions.method(); const action = url.searchParams.get(HttpQueryKeysEnum.ACTION) || GetActionEnum.HEALTH_CHECK; const workflowId = url.searchParams.get(HttpQueryKeysEnum.WORKFLOW_ID) || ''; const stepId = url.searchParams.get(HttpQueryKeysEnum.STEP_ID) || ''; const agentId = url.searchParams.get(HttpQueryKeysEnum.AGENT_ID) || ''; const agentEvent = url.searchParams.get(HttpQueryKeysEnum.EVENT) || ''; const signatureHeader = (await actions.headers(HttpHeaderKeysEnum.NOVU_SIGNATURE)) || ''; const acceptHeader = (await actions.headers(HttpHeaderKeysEnum.ACCEPT)) || ''; const streamReplies = !!actions.transformStreamResponse && acceptHeader.includes('text/event-stream'); let body: Record = {}; try { if (method === HttpMethodEnum.POST) { body = await actions.body(); } } catch (error) { // NO-OP - body was not provided } try { if (action !== GetActionEnum.HEALTH_CHECK) { await this.validateHmac(body, signatureHeader); } const postActionMap = this.getPostActionMap( body, workflowId, stepId, action, agentId, agentEvent, // An explicitly provided `waitUntil` overrides the adapter's automatic detection. this.waitUntil ?? actions.waitUntil, streamReplies ); const getActionMap = this.getGetActionMap(workflowId, stepId); if (method === HttpMethodEnum.POST) { return await this.handlePostAction(action, postActionMap); } if (method === HttpMethodEnum.GET) { return await this.handleGetAction(action, getActionMap); } if (method === HttpMethodEnum.OPTIONS) { return this.createResponse(HttpStatusEnum.OK, {}); } } catch (error) { return this.handleError(error); } return this.createError(new MethodNotAllowedError(method)); } private getPostActionMap( // TODO: add validation for body per action. // biome-ignore lint/suspicious/noExplicitAny: request bodies are not validated per action yet body: any, workflowId: string, stepId: string, action: string, agentId: string, agentEvent: string, waitUntil?: (promise: Promise) => void, streamReplies = false ): Record Promise> { return { [PostActionEnum.TRIGGER]: this.triggerAction({ workflowId, ...body }), [PostActionEnum.EXECUTE]: async () => { const result = await this.client.executeWorkflow({ ...body, workflowId, stepId, action, }); return this.createResponse(HttpStatusEnum.OK, result); }, [PostActionEnum.PREVIEW]: async () => { const result = await this.client.executeWorkflow({ ...body, workflowId, stepId, action, }); return this.createResponse(HttpStatusEnum.OK, result); }, [PostActionEnum.AGENT_EVENT]: async () => { const registeredAgent = this.client.getAgent(agentId); if (!registeredAgent) { return this.createResponse(HttpStatusEnum.NOT_FOUND, { error: `Agent '${agentId}' not registered` }); } const live = streamReplies ? new AgentLiveStream() : undefined; const handlerPromise = dispatchAgentEvent({ agent: registeredAgent, event: agentEvent, bridge: body as AgentBridgeRequest, secretKey: this.client.secretKey, logger: this.client.logger, live, }); if (waitUntil) { waitUntil(handlerPromise); } else if (!live) { this.warnOnUnprotectedServerlessRuntime(agentId); } const ack = this.createResponse(HttpStatusEnum.OK, { status: 'ack' }); return live ? { ...ack, stream: live.body } : ack; }, }; } /** * 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(agentId: string): void { let detectedPlatform: string | undefined; try { if (process.env.AWS_LAMBDA_FUNCTION_NAME) { detectedPlatform = 'AWS Lambda'; } else if (process.env.VERCEL) { detectedPlatform = 'Vercel'; } } catch { // `process` is unavailable on some edge runtimes. } if (!detectedPlatform) { return; } this.client.logger.warn( `[agent:${agentId}] Agent event acknowledged without a \`waitUntil\` primitive while running on ${detectedPlatform}. ` + `The runtime may freeze once the response is sent, silently dropping the rest of the agent turn. ` + `Pass \`waitUntil\` to \`serve()\` (e.g. \`serve({ agents, waitUntil })\`) to extend the invocation lifetime.` ); } public triggerAction(triggerEvent: EventTriggerParams) { return async () => { const requestPayload = { name: triggerEvent.workflowId, to: triggerEvent.to, payload: triggerEvent?.payload || {}, transactionId: triggerEvent.transactionId, overrides: triggerEvent.overrides || {}, ...(triggerEvent.actor && { actor: triggerEvent.actor }), ...(triggerEvent.bridgeUrl && { bridgeUrl: triggerEvent.bridgeUrl }), ...(triggerEvent.controls && { controls: triggerEvent.controls }), ...(triggerEvent.context && { context: triggerEvent.context }), ...(triggerEvent.agentId !== undefined && { agentId: triggerEvent.agentId }), }; const result = await this.http.post('/events/trigger', requestPayload); return this.createResponse(HttpStatusEnum.OK, result); }; } private getGetActionMap(workflowId: string, stepId: string): Record Promise> { return { [GetActionEnum.DISCOVER]: async () => { const result = await this.client.discover(); return this.createResponse(HttpStatusEnum.OK, result); }, [GetActionEnum.HEALTH_CHECK]: async () => { const result = await this.client.healthCheck(); return this.createResponse(HttpStatusEnum.OK, result); }, [GetActionEnum.CODE]: async () => { const result = await this.client.getCode(workflowId, stepId); return this.createResponse(HttpStatusEnum.OK, result); }, }; } private async handlePostAction( action: string, postActionMap: Record Promise> ): Promise { if (Object.values(PostActionEnum).includes(action as PostActionEnum)) { const actionFunction = postActionMap[action as PostActionEnum]; return actionFunction(); } else { throw new InvalidActionError(action, PostActionEnum); } } private async handleGetAction( action: string, getActionMap: Record Promise> ): Promise { if (Object.values(GetActionEnum).includes(action as GetActionEnum)) { const actionFunction = getActionMap[action as GetActionEnum]; return actionFunction(); } else { throw new InvalidActionError(action, GetActionEnum); } } private handleError(error: unknown): IActionResponse { if (isFrameworkError(error)) { if (error.statusCode >= 500) { /* * Log bridge server errors to assist the Developer in debugging errors with their integration. * This path is reached when the Bridge application throws an error, ensuring they can see the error in their logs. */ this.client.logger.error(error); } return this.createError(error); } else if (isPlatformError(error)) { return this.createError(error); } else { const bridgeError = new BridgeError(error); this.client.logger.error(bridgeError); return this.createError(bridgeError); } } private async validateHmac(payload: unknown, hmacHeader: string | null): Promise { if (!this.hmacEnabled) return; if (!hmacHeader) { throw new SignatureNotFoundError(); } if (!this.client.secretKey) { throw new SigningKeyNotFoundError(); } const parsed = parseSignatureHeader(hmacHeader); if (!parsed.v1 || parsed.t === undefined) { throw new SignatureInvalidError(); } const now = Date.now(); if (parsed.t < now - SIGNATURE_TIMESTAMP_TOLERANCE || parsed.t > now + SIGNATURE_TIMESTAMP_TOLERANCE) { throw new SignatureExpiredError(); } const localHash = await createHmacSubtle(this.client.secretKey, `${parsed.t}.${JSON.stringify(payload)}`); if (!timingSafeEqual(localHash, parsed.v1)) { throw new SignatureMismatchError(); } } }