@xyne/workflow-sdk 3.2.36 → 3.2.38

package/dist/router/workflow-router.js

@@ -2,8 +2,8 @@
  * createWorkflowRouter — framework-agnostic route definitions.
  *
  * Returns an array of `RouteDefinition` objects the host maps to their
- * HTTP framework. Each definition has: method, path, handler, and whether
- * it needs authentication.
+ * HTTP framework. Each definition has: method, path, handler, and its
+ * `access` class, which says who authenticates the caller.
  *
  * Usage with Express:
  * ```ts
@@ -14,7 +14,8 @@
  *   const handler = async (req, res) => {
  *     const result = await route.handler(
  *       { params: req.params, query: req.query, body: req.body, headers: req.headers },
- *       route.authenticated !== false ? await authenticate(req.headers) : null,
+ *       // The signed-in user; null for `provider` routes.
+ *       route.access === 'provider' ? null : await authenticate(req.headers),
  *     );
  *     res.status(result.status).json(result.body);
  *   };
@@ -27,8 +28,9 @@ import { createChatAgentTools } from '../agents/builtin/chat-tools.js';
 import { buildWorkflowContext, buildExecutionDataFile, collectExecutionAttachments, EXECUTION_DATA_PATH } from './approval-context.js';
 import { OPERATOR_DESCRIPTORS } from '../types/operators.js';
 import { getAvailableContext } from '../engine/available-context.js';
+import { executionTopic, workflowTopic } from '../events/types.js';
 import { isExecutable } from '../common/executable-check.js';
-import { createEventChannel } from '../runtime/execution-event-bus.js';
+import { createEventChannel } from '../util/event-channel.js';
 import { AccessDeniedError, ResourceNotFoundError } from '../authz/default.js';
 import { applyResolvedCredentialAuth, CredentialNameSchema, CredentialAuthSchema, validateCredentialValues, } from '../common/credentials.js';
 // ─── Helpers ───
@@ -131,6 +133,54 @@ async function buildMultipartTriggerPayload(req, storage, scope, inputSchema) {
 function formatSSE(event, data) {
     return `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
 }
+/**
+ * An SSE comment. Carries no event, so it never reaches a client handler — it
+ * exists purely so that something crosses the wire on an idle connection, before
+ * a proxy or load balancer decides the stream is dead and closes it.
+ */
+const SSE_KEEPALIVE = ': keepalive\n\n';
+/** How long an event stream may sit silent before it sends a keepalive. */
+const KEEPALIVE_INTERVAL_MS = 25_000;
+/**
+ * Marker pushed through an event channel to trigger a keepalive. A symbol so it
+ * can never be mistaken for — or collide with — a real event.
+ */
+const KEEPALIVE = Symbol('keepalive');
+/** Ceiling on topics per multiplexed connection. */
+const MAX_STREAM_TOPICS = 100;
+/**
+ * The writer's self-declared identity, read from `X-Workflow-Origin` and echoed
+ * back on the change event the mutation emits.
+ *
+ * A header rather than a body field: it describes the call, not the resource, so
+ * it works the same on JSON, multipart and empty-bodied routes without any of
+ * them having to make room for it in their schema.
+ *
+ * Untrusted by construction — a client may send whatever it likes. Nothing is
+ * authorized on it; it only ever lets a client recognise the echo of its own
+ * write. Truncated so a subscriber cannot be made to carry an unbounded string.
+ */
+function readOrigin(req) {
+    const raw = req.headers['x-workflow-origin'];
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    return value ? { origin: value.slice(0, 128) } : {};
+}
+/**
+ * Parse an id list from a query parameter, accepting both `?a=1,2` and `?a=1&a=2`
+ * so the route does not depend on how the host's framework folds repeats.
+ */
+function parseIdList(raw) {
+    const parts = Array.isArray(raw) ? raw : typeof raw === 'string' ? [raw] : [];
+    const ids = new Set();
+    for (const part of parts) {
+        for (const id of part.split(',')) {
+            const trimmed = id.trim();
+            if (trimmed)
+                ids.add(trimmed);
+        }
+    }
+    return [...ids];
+}
 // ─── Router Factory ───
 export function createWorkflowRouter(
 // `any` for services: the router never touches TServices, only forwards ctx.
@@ -139,9 +189,9 @@ runtime,
 // `authenticate` is invoked by the host glue, not the factory (see file header).
 _opts) {
     const routes = [];
-    // Authenticated route handlers always receive a resolved ctx — the host runs
-    // `authenticate` before dispatch. Unauthenticated routes never forward `auth`
-    // to a guarded runtime call, so this narrowing is sound.
+    // `session` handlers always receive a resolved ctx — the host authenticates
+    // before dispatch. `provider` routes never forward `auth` to a guarded runtime
+    // call, so this narrowing is sound.
     const asCtx = (auth) => auth;
     // ─── Workflow CRUD ───
     routes.push({
@@ -200,7 +250,7 @@ _opts) {
                     summary: typeof body['summary'] === 'string' ? body['summary'] : null,
                     folderId: body['folderId'],
                     attributes: body['attributes'],
-                });
+                }, readOrigin(req));
                 return created(workflow);
             }
             catch (err) {
@@ -233,7 +283,7 @@ _opts) {
                 }
                 if (typeof body['folderId'] === 'string')
                     input.folderId = body['folderId'];
-                const workflow = await runtime.updateWorkflow(asCtx(auth), id, input);
+                const workflow = await runtime.updateWorkflow(asCtx(auth), id, input, readOrigin(req));
                 return ok(workflow);
             }
             catch (err) {
@@ -363,7 +413,7 @@ _opts) {
             if (folders.length === 0 && workflows.length === 0)
                 return badRequest('Nothing to move');
             try {
-                await runtime.moveBatch(asCtx(auth), { folders, workflows });
+                await runtime.moveBatch(asCtx(auth), { folders, workflows }, readOrigin(req));
                 return ok({ moved: folders.length + workflows.length });
             }
             catch (err) {
@@ -395,7 +445,7 @@ _opts) {
             if (!id)
                 return badRequest('Missing workflow ID');
             try {
-                await runtime.activateWorkflow(asCtx(auth), id);
+                await runtime.activateWorkflow(asCtx(auth), id, readOrigin(req));
                 return ok({ activated: true });
             }
             catch (err) {
@@ -413,7 +463,7 @@ _opts) {
             if (!id)
                 return badRequest('Missing workflow ID');
             try {
-                await runtime.deactivateWorkflow(asCtx(auth), id);
+                await runtime.deactivateWorkflow(asCtx(auth), id, readOrigin(req));
                 return ok({ deactivated: true });
             }
             catch (err) {
@@ -449,9 +499,11 @@ _opts) {
     routes.push({
         method: 'POST',
         path: '/v2/workflows/:workflowId/trigger/v2',
-        authenticated: false,
+        // No session. The SDK does not authenticate this caller; a host that exposes
+        // the route guards it, for example with an API key.
+        access: 'provider',
         multipart: 'any',
-        handler: async (req, _auth) => {
+        handler: async (req) => {
             const workflowId = req.params['workflowId'];
             if (!workflowId)
                 return badRequest('Missing workflow ID');
@@ -468,13 +520,15 @@ _opts) {
                 }
             }
             try {
-                const inputSchema = await runtime.getWorkflowTriggerInputSchemaPublic(workflowId, 'WEBHOOK_V2');
-                const storageScope = await runtime.getWorkflowStorageScopePublic(workflowId, 'WEBHOOK_V2');
-                const payload = await buildMultipartTriggerPayload(req, runtime.storage, storageScope, inputSchema);
-                const executionId = await runtime.triggerWebhookV2Public(workflowId, payload);
+                const target = await runtime.getApiTriggerTarget(workflowId);
+                const payload = await buildMultipartTriggerPayload(req, runtime.storage, target.storageScope, target.inputSchema);
+                const executionId = await runtime.triggerViaApi(workflowId, payload);
                 return created({ executionId });
             }
             catch (err) {
+                // An unknown workflow goes to the uniform 404 mapping at the end of this file.
+                if (err instanceof ResourceNotFoundError)
+                    throw err;
                 if (err instanceof Error && err.message.includes('not found')) {
                     return notFound(err.message);
                 }
@@ -707,34 +761,36 @@ _opts) {
             return ok({ topErrors });
         },
     });
-    // ─── Webhooks (no auth — validated by secret in path) ───
+    // ─── Webhooks (no session — the trigger's own verify authenticates the sender) ───
     routes.push({
         method: 'POST',
-        path: '/webhooks/:workflowId/:secret',
-        authenticated: false,
-        handler: async (req, _auth) => {
-            const path = `/webhooks/${req.params['workflowId'] ?? ''}/${req.params['secret'] ?? ''}`;
-            const result = await runtime.handleWebhook(path, {
-                method: req.params['method'] ?? 'POST',
+        path: '/webhooks/:workflowId',
+        access: 'provider',
+        rawBody: true,
+        handler: async (req) => {
+            if (!req.rawBody) {
+                // A signature covers the bytes as sent, so a parsed body cannot be
+                // verified. Refuse rather than silently skip authentication.
+                return error(500, 'Webhook route requires the raw request body; the host must honour RouteDefinition.rawBody');
+            }
+            const { reply } = await runtime.handleWebhook(req.params['workflowId'] ?? '', {
+                method: 'POST',
                 headers: req.headers,
-                body: req.body,
                 query: req.query,
+                rawBody: req.rawBody,
             });
-            const response = {
-                status: result.httpResponse.status,
-                body: result.httpResponse.body,
+            return {
+                status: reply.status,
+                body: reply.body,
+                ...(reply.headers ? { headers: { ...reply.headers } } : {}),
             };
-            if (result.httpResponse.headers) {
-                response.headers = result.httpResponse.headers;
-            }
-            return response;
         },
     });
     // ─── Wait callbacks (no auth — validated by workflow secret in path) ───
     routes.push({
         method: 'POST',
         path: '/wait/callback/:secret/:executionId',
-        authenticated: false,
+        access: 'provider',
         handler: async (req, _auth) => {
             const secret = req.params['secret'] ?? '';
             const executionId = req.params['executionId'] ?? '';
@@ -743,12 +799,19 @@ _opts) {
         },
     });
     // ─── Schema metadata (for UI) ───
+    routes.push({
+        method: 'GET',
+        path: '/schema/credentials',
+        handler: async () => {
+            return ok({ connectors: runtime.connectors.listCredentialTypes() });
+        },
+    });
     routes.push({
         method: 'GET',
         path: '/schema/triggers',
         handler: async () => {
             return ok({
-                triggers: runtime.triggers.listSummaries(),
+                triggers: runtime.connectors.listTriggerSummaries(),
             });
         },
     });
@@ -757,7 +820,7 @@ _opts) {
         path: '/schema/steps',
         handler: async () => {
             return ok({
-                steps: runtime.steps.listSummaries(),
+                steps: runtime.connectors.listStepSummaries(),
             });
         },
     });
@@ -769,10 +832,10 @@ _opts) {
             const type = req.params['type'];
             if (!type)
                 return badRequest('Missing trigger type');
-            if (!runtime.triggers.has(type)) {
+            if (!runtime.connectors.hasTrigger(type)) {
                 return notFound(`Unknown trigger type "${type}"`);
             }
-            return ok(runtime.triggers.getDescriptor(type));
+            return ok(runtime.connectors.getTriggerDescriptor(type));
         },
     });
     routes.push({
@@ -782,10 +845,10 @@ _opts) {
             const type = req.params['type'];
             if (!type)
                 return badRequest('Missing step type');
-            if (!runtime.steps.has(type)) {
+            if (!runtime.connectors.hasStep(type)) {
                 return notFound(`Unknown step type "${type}"`);
             }
-            return ok(runtime.steps.getDescriptor(type));
+            return ok(runtime.connectors.getStepDescriptor(type));
         },
     });
     routes.push({
@@ -806,7 +869,7 @@ _opts) {
             }
             const config = body['config'];
             const atStepId = body['atStepId'];
-            const context = getAvailableContext(config, atStepId, runtime.steps, runtime.triggers);
+            const context = getAvailableContext(config, atStepId, runtime.connectors);
             return ok({ context });
         },
     });
@@ -909,8 +972,9 @@ _opts) {
         },
     });
     // ── POST /credentials ──
-    // Create a new credential. Strictly validates name and the discriminated
-    // authType/values pair.
+    // Create a new credential of a connector-declared type. The shape comes from
+    // the type's definition, never from the client, and values are validated
+    // strictly against it.
     routes.push({
         method: 'POST',
         path: '/credentials',
@@ -929,15 +993,23 @@ _opts) {
             if (!nameResult.success) {
                 return badRequest('Invalid or missing "name"');
             }
+            const credType = body['credType'];
+            const definition = typeof credType === 'string'
+                ? runtime.connectors.findCredentialDefinition(credType)
+                : undefined;
+            if (!definition) {
+                return badRequest('Invalid or missing "credType"');
+            }
             const credentialAuthResult = CredentialAuthSchema.safeParse({
-                authType: body['authType'],
+                authType: definition.authType,
                 values: body['values'],
             });
             if (!credentialAuthResult.success) {
-                return badRequest('Invalid or mismatched "authType" and "values"');
+                return badRequest(`Invalid "values" for credential type "${definition.credType}"`);
             }
             const input = {
                 name: nameResult.data,
+                credType: definition.credType,
                 ...credentialAuthResult.data,
             };
             try {
@@ -1113,6 +1185,99 @@ _opts) {
             }
         },
     });
+    // ─── SSE: Multiplexed Change Stream ───
+    //
+    // One connection, many topics: `GET /events?workflows=a,b`.
+    //
+    // The topic set lives in the URL and nowhere else, which is what keeps this
+    // working behind a load balancer with no session affinity. There is no
+    // server-side subscription to mutate, so a client that wants to watch something
+    // new simply reconnects with a different query string — and any pod can serve
+    // it, because every pod subscribes to whatever its own clients asked for.
+    //
+    // Frames are notifications, not payloads: `workflow_changed` says *that* a
+    // workflow changed, and the client re-reads through the ordinary authorized
+    // GET. Only `workflows` is accepted today — a live execution has its own richer
+    // stream at `/executions/:execId/stream`, which patches step state in place
+    // rather than re-reading, and duplicating it here would give it two meanings.
+    // The query shape is keyed by entity so further families slot in unchanged.
+    routes.push({
+        method: 'GET',
+        path: '/events',
+        handler: async (req, auth) => {
+            const eventBus = runtime.eventBus;
+            if (!eventBus) {
+                return error(501, 'Event streaming not configured');
+            }
+            const requested = parseIdList(req.query['workflows']);
+            if (requested.length === 0) {
+                return badRequest('Specify at least one id, e.g. ?workflows=a,b');
+            }
+            if (requested.length > MAX_STREAM_TOPICS) {
+                return badRequest(`Too many topics (${String(requested.length)}); the limit is ${String(MAX_STREAM_TOPICS)}`);
+            }
+            // Authorize every id up front, through the same read the client would do.
+            // A bus is addressed by resource id and knows nothing about principals, so
+            // this is the only place the caller's access is actually decided.
+            //
+            // One unreadable id does not fail the connection: on a multiplexed stream
+            // that would take down every other topic the client is watching, and access
+            // can be lost mid-session. The `ready` frame reports what was accepted, so
+            // the client is never left believing it is watching something it is not.
+            const subscribed = [];
+            const rejected = [];
+            await Promise.all(requested.map(async (id) => {
+                try {
+                    await runtime.getWorkflow(asCtx(auth), id);
+                    subscribed.push(id);
+                }
+                catch {
+                    rejected.push(id);
+                }
+            }));
+            const channel = createEventChannel();
+            const results = await Promise.allSettled(subscribed.map((id) => eventBus.subscribe(workflowTopic(id), channel.push)));
+            const unsubs = results.flatMap((r) => r.status === 'fulfilled' ? [r.value] : []);
+            if (unsubs.length !== results.length) {
+                // A partially-subscribed stream is worse than none: it looks live and is
+                // silently blind to some of its topics. Tear it down and let the client
+                // reconnect.
+                for (const unsub of unsubs)
+                    unsub();
+                channel.end();
+                return error(503, 'Could not open the event stream');
+            }
+            const keepalive = setInterval(() => {
+                channel.push(KEEPALIVE);
+            }, KEEPALIVE_INTERVAL_MS);
+            async function* generateSSE() {
+                try {
+                    // Sent before anything else so the client knows the subscription is
+                    // live and which topics it actually got.
+                    yield formatSSE('ready', { subscribed, rejected });
+                    for await (const frame of channel) {
+                        yield frame === KEEPALIVE ? SSE_KEEPALIVE : formatSSE(frame.event, frame.data);
+                    }
+                }
+                finally {
+                    clearInterval(keepalive);
+                    for (const unsub of unsubs)
+                        unsub();
+                    channel.end();
+                }
+            }
+            return {
+                status: 200,
+                body: null,
+                headers: {
+                    'Content-Type': 'text/event-stream',
+                    'Cache-Control': 'no-cache',
+                    'Connection': 'keep-alive',
+                },
+                stream: generateSSE(),
+            };
+        },
+    });
     // ─── SSE: Execution Event Stream ───
     routes.push({
         method: 'GET',
@@ -1125,27 +1290,51 @@ _opts) {
             if (!eventBus) {
                 return error(501, 'Event streaming not configured');
             }
-            const detail = await runtime.getExecutionDetail(asCtx(auth), execId);
-            if (!detail)
+            // Subscribe BEFORE reading the snapshot, not after.
+            //
+            // Anything published in between is then delivered twice — once folded into
+            // the snapshot, once live — which costs a redundant repaint, because every
+            // execution event is idempotent. A miss is not recoverable: drop
+            // `execution_completed` and the client sits on an open connection waiting
+            // for a frame that has already been and gone. Subscribing second is a race
+            // even in-process; against a distributed bus, where subscribe is a network
+            // round trip, it is a race you lose regularly.
+            //
+            // Ordering it this way subscribes fractionally before the caller's access is
+            // checked. Nothing is delivered in that window: every failure path below
+            // tears the subscription down and drops the channel unread, and the first
+            // frame is only ever yielded after `getExecutionDetail` has authorized it.
+            const channel = createEventChannel();
+            const unsub = await eventBus.subscribe(executionTopic(execId), channel.push);
+            const found = await runtime
+                .getExecutionDetail(asCtx(auth), execId)
+                .catch((err) => {
+                unsub();
+                throw err;
+            });
+            if (!found) {
+                unsub();
                 return notFound(`Execution ${execId} not found`);
+            }
+            // Re-bound after the guard: `generateSSE` is a hoisted declaration, so TS
+            // will not carry the null-narrowing of `found` into it.
+            const detail = found;
             const isTerminal = ['COMPLETED', 'FAILED', 'CANCELLED'].includes(detail.execution.status);
             async function* generateSSE() {
-                // 1. Send initial snapshot
-                yield formatSSE('snapshot', {
-                    ...detail.execution,
-                    steps: detail.steps,
-                    config: detail.config,
-                    triggerData: detail.triggerData,
-                    summary: detail.summary,
-                    name: detail.name,
-                });
-                // 2. If already terminal, close immediately
-                if (isTerminal)
-                    return;
-                // 3. Subscribe to live events
-                const channel = createEventChannel();
-                const unsub = eventBus.subscribe(execId, channel.push);
                 try {
+                    // 1. Send the initial snapshot (buffered events wait their turn).
+                    yield formatSSE('snapshot', {
+                        ...detail.execution,
+                        steps: detail.steps,
+                        config: detail.config,
+                        triggerData: detail.triggerData,
+                        summary: detail.summary,
+                        name: detail.name,
+                    });
+                    // 2. If already terminal, close immediately.
+                    if (isTerminal)
+                        return;
+                    // 3. Drain live events.
                     for await (const event of channel) {
                         yield formatSSE(event.event, event.data);
                         // Close stream on terminal events
@@ -1157,7 +1346,10 @@ _opts) {
                     }
                 }
                 finally {
+                    // Runs however the generator ends — terminal event, client disconnect,
+                    // or a throw mid-yield.
                     unsub();
+                    channel.end();
                 }
             }
             return {
@@ -1255,7 +1447,7 @@ _opts) {
         routes.push({
             method: 'POST',
             path: '/ai-builder/chat',
-            authenticated: false,
+            access: 'session',
             handler: async (req, auth) => {
                 const body = req.body;
                 if (!body.messages || !Array.isArray(body.messages)) {
@@ -1453,6 +1645,9 @@ _opts) {
     // than a 500 — and so a new route cannot forget to do it.
     return routes.map((route) => ({
         ...route,
+        // A route that does not declare its access needs a signed-in user, so
+        // forgetting to classify one never mounts it open.
+        access: route.access ?? 'session',
         handler: async (req, auth) => {
             try {
                 return await route.handler(req, auth);