spectrum-ts 1.16.0 → 1.16.1

package/dist/index.d.ts

@@ -2629,8 +2629,17 @@ interface FusorClient<TPayload = unknown> {
 /**
  * Request-scoped handler invoked once per inbound message that
  * `spectrum.webhook()` resolves. Receives the same fully-built `[space,
- * message]` pair that `spectrum.messages` yields; awaited before the HTTP
- * response is returned to fusor.
+ * message]` pair that `spectrum.messages` yields.
+ *
+ * Runs **fire-and-forget**: it is dispatched after the HTTP response (the
+ * platform's `respond()` reply) has already been computed, so its outcome never
+ * affects the response, and a throw is caught + logged rather than surfaced —
+ * mirroring the body of a `for await (… of spectrum.messages)` loop.
+ *
+ * On a long-running server the event loop keeps the handler alive. On
+ * serverless/edge runtimes the function may be frozen once the response is
+ * returned, so keeping background work alive is the caller's responsibility —
+ * the usual pattern is to enqueue the work and process it in a separate worker.
  */
 type WebhookHandler = (space: Space, message: Message) => void | Promise<void>;
 /**
@@ -2752,9 +2761,17 @@ type SpectrumInstance<Providers extends PlatformProviderConfig[] = PlatformProvi
     /**
      * Handle one inbound fusor webhook delivery. Call this from your HTTP
      * server's POST route — it verifies, decodes, routes to the matching
-     * provider's verify + message pipeline, invokes `handler` once per resolved
-     * message, and returns the HTTP response fusor relays back to the platform
-     * (including protocol echoes like Slack `url_verification`).
+     * provider's verify + message pipeline, and returns the HTTP response fusor
+     * relays back to the platform: the platform's `respond()` reply (including
+     * protocol echoes like Slack `url_verification`), computed synchronously and
+     * returned immediately.
+     *
+     * `handler` is invoked once per resolved message **fire-and-forget** — it is
+     * dispatched after the response is computed and is NOT awaited, so its
+     * outcome never changes the response (a throw is logged, not surfaced). On a
+     * long-running server the event loop keeps it alive; on serverless/edge,
+     * keeping the work alive past the response is the caller's job (e.g. enqueue
+     * and process in a separate worker).
      *
      * Stateless and request-scoped: it does NOT feed `spectrum.messages`, and it
      * never opens the gRPC stream. fusor delivers at-least-once, so `handler`

package/dist/index.js

@@ -28013,11 +28013,23 @@ async function Spectrum(options) {
     }
     return { asWeb: false, bodyBytes, headers };
   };
-  const deliverWebhookMessages = async (collected, runtime, handler) => {
+  const deliverWebhookMessages = async (collected, runtime, handler, event) => {
     for (const record of collected) {
       const tuples = await resolveRecordToMessages(record, runtime);
       for (const [space, message] of tuples) {
-        await handler(space, message);
+        try {
+          await handler(space, message);
+        } catch (error) {
+          lifecycleLog.error(
+            `spectrum.webhook: handler threw (async), ${error}`,
+            {
+              eventId: event.eventId,
+              platform: event.platform,
+              messageId: message.id,
+              error: error instanceof Error ? error.message : String(error)
+            }
+          );
+        }
       }
     }
   };
@@ -28037,19 +28049,6 @@ async function Spectrum(options) {
       return null;
     }
   };
-  const runWebhookDelivery = async (collected, runtime, handler, event) => {
-    try {
-      await deliverWebhookMessages(collected, runtime, handler);
-      return null;
-    } catch (error) {
-      lifecycleLog.error(`spectrum.webhook: handler threw, ${error}`, {
-        eventId: event.eventId,
-        platform: event.platform,
-        error: error instanceof Error ? error.message : String(error)
-      });
-      return { status: 500, headers: {}, body: new Uint8Array(0) };
-    }
-  };
   const processWebhookEvent = async (core, event, handler) => {
     const collected = [];
     const reply2 = await core.processEvent(event, (record) => {
@@ -28062,23 +28061,27 @@ async function Spectrum(options) {
         body: encodeText(reply2.errorReason)
       };
     }
-    const runtime = platformStates.get(event.platform);
-    if (runtime) {
-      const failure = await runWebhookDelivery(
-        collected,
-        runtime,
-        handler,
-        event
-      );
-      if (failure) {
-        return failure;
-      }
-    }
-    return {
+    const result = {
       status: reply2.status === 0 ? 200 : reply2.status,
       headers: reply2.headers ?? {},
       body: reply2.body ?? new Uint8Array(0)
     };
+    const runtime = platformStates.get(event.platform);
+    if (runtime && collected.length > 0) {
+      deliverWebhookMessages(collected, runtime, handler, event).catch(
+        (error) => {
+          lifecycleLog.error(
+            `spectrum.webhook: delivery failed (async), ${error}`,
+            {
+              eventId: event.eventId,
+              platform: event.platform,
+              error: error instanceof Error ? error.message : String(error)
+            }
+          );
+        }
+      );
+    }
+    return result;
   };
   const handleWebhook = async (request, handler) => {
     if (!fusorCore) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spectrum-ts",
-  "version": "1.16.0",
+  "version": "1.16.1",
   "description": "Bring agents to any interface — unified messaging SDK for TypeScript.",
   "repository": {
     "type": "git",