spectrum-ts 4.1.0 → 4.2.0

package/dist/authoring.js

@@ -1,13 +1,13 @@
 import { createRequire as __spectrumCreateRequire } from "node:module"; const require = __spectrumCreateRequire(import.meta.url);
+import {
+  asVoice
+} from "./chunk-FAIFTUV2.js";
 import {
   asRichlink
 } from "./chunk-ZR3TKZMT.js";
 import {
   asGroup
 } from "./chunk-LZXPLXZF.js";
-import {
-  asVoice
-} from "./chunk-FAIFTUV2.js";
 import {
   asPoll,
   asPollOption

package/dist/elysia.d.ts

@@ -0,0 +1,94 @@
+import { Elysia } from 'elysia';
+import { W as WebhookHandler } from './types-ZgFTj5hJ.js';
+export { M as Message, S as Space } from './types-CyfLJXgu.js';
+import 'hotscript';
+import 'zod';
+
+/**
+ * The minimal structural surface of a Spectrum instance the plugin needs. Kept
+ * structural (rather than importing the generic `SpectrumInstance<Providers>`)
+ * so the plugin stays decoupled from provider typing; a real instance is
+ * assignable via its Web `Request` webhook overload.
+ */
+interface WebhookReceiver {
+    webhook(request: Request, handler: WebhookHandler): Promise<Response>;
+}
+interface SpectrumPluginOptions {
+    /** The Spectrum instance returned by `await Spectrum({...})`. */
+    app: WebhookReceiver;
+    /**
+     * Invoked once per inbound message, fire-and-forget after the response — the
+     * same `(space, message)` contract as `app.webhook(request, handler)`. Covers
+     * both native Spectrum webhooks and fusor webhooks identically.
+     */
+    onMessage: WebhookHandler;
+    /**
+     * Route the webhook is mounted on.
+     *
+     * @default "/spectrum/webhook"
+     */
+    path?: string;
+}
+/**
+ * Mount a Spectrum webhook endpoint on an Elysia app.
+ *
+ * @example
+ * ```ts
+ * import { Elysia } from "elysia";
+ * import { Spectrum } from "spectrum-ts";
+ * import { spectrum } from "spectrum-ts/elysia";
+ *
+ * const app = await Spectrum({ ...,  webhookSecret: process.env.SPECTRUM_WEBHOOK_SECRET });
+ *
+ * new Elysia()
+ *   .use(spectrum({
+ *     app,
+ *     onMessage: async (space, message) => {
+ *       if (message.content.type === "text") await space.send(`echo: ${message.content.text}`);
+ *     },
+ *   }))
+ *   .listen(3000);
+ * ```
+ */
+declare function spectrum(options: SpectrumPluginOptions): Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {
+    [x: string]: {
+        post: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: Response;
+            };
+        };
+    };
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;
+
+export { type SpectrumPluginOptions, WebhookHandler, spectrum };

package/dist/elysia.js

@@ -0,0 +1,15 @@
+import { createRequire as __spectrumCreateRequire } from "node:module"; const require = __spectrumCreateRequire(import.meta.url);
+
+// src/elysia.ts
+import { Elysia } from "elysia";
+function spectrum(options) {
+  const { app, onMessage, path = "/spectrum/webhook" } = options;
+  return new Elysia({ name: "spectrum-webhook", seed: path }).post(
+    path,
+    ({ request }) => app.webhook(request, onMessage),
+    { parse: "none" }
+  );
+}
+export {
+  spectrum
+};

package/dist/express.d.ts

@@ -0,0 +1,62 @@
+import { Router } from 'express';
+import { W as WebhookHandler } from './types-ZgFTj5hJ.js';
+export { M as Message, S as Space } from './types-CyfLJXgu.js';
+import 'hotscript';
+import 'zod';
+
+/**
+ * The minimal structural surface of a Spectrum instance the plugin needs. Kept
+ * structural (rather than importing the generic `SpectrumInstance<Providers>`)
+ * so the plugin stays decoupled from provider typing; a real instance is
+ * assignable via its raw (`{ body, headers }`) webhook overload.
+ */
+interface WebhookReceiver {
+    webhook(request: {
+        body: Uint8Array | ArrayBuffer;
+        headers?: Record<string, string>;
+    }, handler: WebhookHandler): Promise<{
+        body: Uint8Array;
+        headers: Record<string, string>;
+        status: number;
+    }>;
+}
+interface SpectrumPluginOptions {
+    /** The Spectrum instance returned by `await Spectrum({...})`. */
+    app: WebhookReceiver;
+    /**
+     * Invoked once per inbound message, fire-and-forget after the response — the
+     * same `(space, message)` contract as `app.webhook(request, handler)`. Covers
+     * both native Spectrum webhooks and fusor webhooks identically.
+     */
+    onMessage: WebhookHandler;
+    /**
+     * Route the webhook is mounted on.
+     *
+     * @default "/spectrum/webhook"
+     */
+    path?: string;
+}
+/**
+ * Mount a Spectrum webhook endpoint on an Express app.
+ *
+ * @example
+ * ```ts
+ * import express from "express";
+ * import { Spectrum } from "spectrum-ts";
+ * import { spectrum } from "spectrum-ts/express";
+ *
+ * const app = await Spectrum({ ...,  webhookSecret: process.env.SPECTRUM_WEBHOOK_SECRET });
+ *
+ * const server = express();
+ * server.use(spectrum({ // mount before any global express.json()
+ *   app,
+ *   onMessage: async (space, message) => {
+ *     if (message.content.type === "text") await space.send(`echo: ${message.content.text}`);
+ *   },
+ * }));
+ * server.listen(3000);
+ * ```
+ */
+declare function spectrum(options: SpectrumPluginOptions): Router;
+
+export { type SpectrumPluginOptions, WebhookHandler, spectrum };

package/dist/express.js

@@ -0,0 +1,19 @@
+import { createRequire as __spectrumCreateRequire } from "node:module"; const require = __spectrumCreateRequire(import.meta.url);
+
+// src/express.ts
+import express from "express";
+function spectrum(options) {
+  const { app, onMessage, path = "/spectrum/webhook" } = options;
+  const router = express.Router();
+  router.post(path, express.raw({ type: "*/*" }), async (req, res) => {
+    const result = await app.webhook(
+      { body: req.body, headers: req.headers },
+      onMessage
+    );
+    res.status(result.status).set(result.headers).send(Buffer.from(result.body));
+  });
+  return router;
+}
+export {
+  spectrum
+};

package/dist/hono.d.ts

@@ -0,0 +1,64 @@
+import * as hono_hono_base from 'hono/hono-base';
+import * as hono_utils_http_status from 'hono/utils/http-status';
+import * as hono_types from 'hono/types';
+import { W as WebhookHandler } from './types-ZgFTj5hJ.js';
+export { M as Message, S as Space } from './types-CyfLJXgu.js';
+import 'hotscript';
+import 'zod';
+
+/**
+ * The minimal structural surface of a Spectrum instance the plugin needs. Kept
+ * structural (rather than importing the generic `SpectrumInstance<Providers>`)
+ * so the plugin stays decoupled from provider typing; a real instance is
+ * assignable via its Web `Request` webhook overload.
+ */
+interface WebhookReceiver {
+    webhook(request: Request, handler: WebhookHandler): Promise<Response>;
+}
+interface SpectrumPluginOptions {
+    /** The Spectrum instance returned by `await Spectrum({...})`. */
+    app: WebhookReceiver;
+    /**
+     * Invoked once per inbound message, fire-and-forget after the response — the
+     * same `(space, message)` contract as `app.webhook(request, handler)`. Covers
+     * both native Spectrum webhooks and fusor webhooks identically.
+     */
+    onMessage: WebhookHandler;
+    /**
+     * Route the webhook is mounted on.
+     *
+     * @default "/spectrum/webhook"
+     */
+    path?: string;
+}
+/**
+ * Mount a Spectrum webhook endpoint on a Hono app.
+ *
+ * @example
+ * ```ts
+ * import { Hono } from "hono";
+ * import { Spectrum } from "spectrum-ts";
+ * import { spectrum } from "spectrum-ts/hono";
+ *
+ * const app = await Spectrum({ ...,  webhookSecret: process.env.SPECTRUM_WEBHOOK_SECRET });
+ *
+ * const server = new Hono().route("/", spectrum({
+ *   app,
+ *   onMessage: async (space, message) => {
+ *     if (message.content.type === "text") await space.send(`echo: ${message.content.text}`);
+ *   },
+ * }));
+ * ```
+ */
+declare function spectrum(options: SpectrumPluginOptions): hono_hono_base.HonoBase<hono_types.BlankEnv, {
+    [x: string]: {
+        $post: {
+            input: {};
+            output: {};
+            outputFormat: string;
+            status: hono_utils_http_status.StatusCode;
+        };
+    };
+}, "/", string>;
+
+export { type SpectrumPluginOptions, WebhookHandler, spectrum };

package/dist/hono.js

@@ -0,0 +1,11 @@
+import { createRequire as __spectrumCreateRequire } from "node:module"; const require = __spectrumCreateRequire(import.meta.url);
+
+// src/hono.ts
+import { Hono } from "hono";
+function spectrum(options) {
+  const { app, onMessage, path = "/spectrum/webhook" } = options;
+  return new Hono().post(path, (c) => app.webhook(c.req.raw, onMessage));
+}
+export {
+  spectrum
+};

package/dist/index.d.ts

@@ -6,8 +6,8 @@ import { C as ContentBuilder, M as Message, U as User, S as Space, h as ContentI
 export { p as AnyPlatformDef, B as Broadcaster, q as CloudPlatform, D as DedicatedTokenData, F as FusorTokenData, r as ImessageInfoData, s as ManagedStream, t as PlatformInstance, u as PlatformMessage, v as PlatformRuntime, w as PlatformSpace, x as PlatformStatus, y as PlatformUser, z as PlatformsData, G as ProjectProfile, R as Reaction, H as ReactionBuilder, a as SchemaMessage, J as SharedTokenData, K as SlackTeamMeta, L as SlackTokenData, N as SpaceNamespace, O as SpectrumCloudError, Q as SubscriptionData, T as SubscriptionStatus, V as TokenData, W as broadcast, X as cloud, Y as mergeStreams, Z as reaction, _ as stream } from './types-CyfLJXgu.js';
 import { S as StreamTextSource, T as TextStreamOptions, C as ContactInput, a as Contact } from './authoring-b9AhXgPI.js';
 export { b as ContactAddress, c as ContactDetails, d as ContactEmail, e as ContactName, f as ContactOrg, g as ContactPhone, D as DeltaExtractor, G as Group, P as Poll, h as PollChoice, i as PollChoiceInput, j as PollOption, R as Richlink, k as StreamText, V as Voice, l as contact, m as custom, n as group, o as option, p as poll, r as richlink, t as text, v as voice } from './authoring-b9AhXgPI.js';
-import { a as FusorVerify, F as FusorClient, b as FusorMessages, W as WebhookHandler, c as WebhookRawRequest, d as WebhookRawResult } from './types-BIta6Kxi.js';
-export { e as FusorEvent, f as FusorMessagesCtx, g as FusorMessagesReturn, h as FusorReply, i as FusorRespond, j as FusorVerifyRequest, k as fusorEvent, l as isFusorEvent } from './types-BIta6Kxi.js';
+import { a as FusorVerify, F as FusorClient, b as FusorMessages, W as WebhookHandler, c as WebhookRawRequest, d as WebhookRawResult } from './types-ZgFTj5hJ.js';
+export { e as FusorEvent, f as FusorMessagesCtx, g as FusorMessagesReturn, h as FusorReply, i as FusorRespond, j as FusorVerifyRequest, k as fusorEvent, l as isFusorEvent } from './types-ZgFTj5hJ.js';
 import 'hotscript';
 import 'vcf';
 
@@ -2757,12 +2757,23 @@ type SpectrumInstance<Providers extends PlatformProviderConfig[] = PlatformProvi
     edit(message: Message, newContent: ContentInput): Promise<void>;
     responding<T>(space: Space, fn: () => T | Promise<T>): Promise<T>;
     /**
-     * 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, 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.
+     * Handle one inbound webhook delivery. Call this from your HTTP server's
+     * POST route — it auto-detects which of the two Spectrum webhook formats the
+     * request carries and routes accordingly:
+     *
+     * - **Native Spectrum webhook** (the body is normalized JSON): Spectrum Cloud
+     *   POSTs already-normalized, HMAC-signed JSON. The signature is verified
+     *   against `Spectrum({ webhookSecret })` (a bad signature → 401), the slim
+     *   payload is deserialized into `[space, message]`, and a `200` is returned.
+     *   Works without any fusor provider configured.
+     * - **Fusor webhook** (the body is a protobuf envelope): a protobuf wrapping a
+     *   raw provider request is decoded and routed to the matching provider's
+     *   verify + message pipeline; the HTTP response is that platform's
+     *   `respond()` reply (including protocol echoes like Slack
+     *   `url_verification`), computed synchronously and returned immediately.
+     *
+     * Detection is by payload shape, not headers — Spectrum signs both kinds with
+     * `X-Spectrum-Signature`, so the header can't discriminate.
      *
      * `handler` is invoked once per resolved message **fire-and-forget** — it is
      * dispatched after the response is computed and is NOT awaited, so its
@@ -2772,8 +2783,9 @@ type SpectrumInstance<Providers extends PlatformProviderConfig[] = PlatformProvi
      * 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`
-     * should dedupe on `message`/the event id for exactly-once side effects.
+     * never opens the streaming connection. Both formats deliver at-least-once,
+     * so `handler` should dedupe on `message`/the event id for exactly-once side
+     * effects.
      */
     webhook(request: Request, handler: WebhookHandler): Promise<Response>;
     webhook(request: WebhookRawRequest, handler: WebhookHandler): Promise<WebhookRawResult>;
@@ -2800,6 +2812,7 @@ declare function Spectrum<const Providers extends PlatformProviderConfig[]>(opti
     providers: [...Providers];
     options?: SpectrumOptions;
     telemetry?: boolean;
+    webhookSecret?: string;
 }): Promise<SpectrumInstance<Providers> & {
     readonly config: ProjectData;
 }>;
@@ -2809,6 +2822,7 @@ declare function Spectrum<const Providers extends PlatformProviderConfig[]>(opti
     providers: [...Providers];
     options?: SpectrumOptions;
     telemetry?: boolean;
+    webhookSecret?: string;
 }): Promise<SpectrumInstance<Providers>>;
 
 type UnsupportedKind = "content" | "action";

package/dist/index.js

@@ -1,7 +1,4 @@
 import { createRequire as __spectrumCreateRequire } from "node:module"; const require = __spectrumCreateRequire(import.meta.url);
-import {
-  richlink
-} from "./chunk-ZR3TKZMT.js";
 import {
   FUSOR_MESSAGES_CHANNEL,
   fusor,
@@ -9,33 +6,38 @@ import {
   isFusorClient,
   isFusorEvent
 } from "./chunk-34FQGGD7.js";
-import {
-  group
-} from "./chunk-LZXPLXZF.js";
 import {
   voice
 } from "./chunk-FAIFTUV2.js";
+import {
+  asRichlink,
+  richlink
+} from "./chunk-ZR3TKZMT.js";
+import {
+  group
+} from "./chunk-LZXPLXZF.js";
 import {
   option,
   poll
 } from "./chunk-2D27WW5B.js";
+import {
+  asContact,
+  contact
+} from "./chunk-A37PM5N2.js";
+import {
+  fromVCard,
+  toVCard
+} from "./chunk-6UZFVXQF.js";
 import {
   SpectrumCloudError,
   cloud
 } from "./chunk-3GEJYGZK.js";
-import {
-  contact
-} from "./chunk-A37PM5N2.js";
 import {
   broadcast,
   createAsyncQueue,
   mergeStreams,
   stream
 } from "./chunk-5XEFJBN2.js";
-import {
-  fromVCard,
-  toVCard
-} from "./chunk-6UZFVXQF.js";
 import {
   UnsupportedError,
   avatar,
@@ -53,6 +55,8 @@ import {
   wrapProviderMessage
 } from "./chunk-B52VPQO3.js";
 import {
+  asAttachment,
+  asCustom,
   attachment,
   custom,
   reaction,
@@ -1996,7 +2000,7 @@ import {
   withSpan
 } from "@photon-ai/otel";
 import { RawInboundEvent } from "@photon-ai/proto/photon/fusor/v1/inbound";
-import z from "zod";
+import z2 from "zod";
 
 // src/build-env.ts
 var SPECTRUM_SDK_VERSION = "local";
@@ -2707,28 +2711,284 @@ function createStore() {
   };
 }
 
+// src/webhook/deserialize.ts
+var MESSAGES_EVENT = "messages";
+var DEFAULT_ATTACHMENT_NAME = "attachment";
+var DEFAULT_MIME_TYPE = "application/octet-stream";
+var isRecord = (value) => typeof value === "object" && value !== null;
+var asString = (value) => typeof value === "string" ? value : "";
+var asOptionalDate = (value) => typeof value === "string" ? new Date(value) : void 0;
+function deserializeSpectrumMessage(envelope, ctx) {
+  if (envelope.event !== MESSAGES_EVENT) {
+    return null;
+  }
+  const message = envelope.message;
+  const platform = resolvePlatform(message);
+  if (!platform) {
+    return null;
+  }
+  const spaceRef = { ...message.space };
+  return {
+    platform,
+    record: {
+      id: message.id,
+      direction: "inbound",
+      content: deserializeContent(message.content, platform, spaceRef, ctx),
+      space: spaceRef,
+      sender: message.sender ? { ...message.sender } : void 0,
+      timestamp: asOptionalDate(message.timestamp)
+    }
+  };
+}
+var resolvePlatform = (message) => message.platform ?? message.space.platform;
+var deserializeContent = (content, platform, spaceRef, ctx) => {
+  try {
+    return mapContent(content, platform, spaceRef, ctx);
+  } catch {
+    return asCustom(content);
+  }
+};
+var mapContent = (content, platform, spaceRef, ctx) => {
+  const raw = content;
+  switch (content.type) {
+    case "text":
+      return { type: "text", text: asString(raw.text) };
+    case "richlink":
+      return asRichlink({ url: asString(raw.url) });
+    case "contact":
+      return deserializeContact(raw);
+    case "reaction":
+      return deserializeReaction(raw, spaceRef);
+    case "group":
+      return deserializeGroup(raw, platform, spaceRef, ctx);
+    case "attachment":
+      return deserializeAttachment(raw, platform, spaceRef, ctx);
+    default:
+      return asCustom(content);
+  }
+};
+var deserializeAttachment = (raw, platform, spaceRef, ctx) => {
+  const id = asString(raw.id);
+  const bytes = ctx.resolveAttachment?.(platform, spaceRef, id);
+  const unavailable = () => Promise.reject(
+    UnsupportedError.action(
+      "getAttachment",
+      platform,
+      `attachment "${id}" arrived without bytes over the Spectrum webhook and "${platform}" exposes no getAttachment`
+    )
+  );
+  return asAttachment({
+    id,
+    name: asString(raw.name) || DEFAULT_ATTACHMENT_NAME,
+    mimeType: asString(raw.mimeType) || DEFAULT_MIME_TYPE,
+    size: typeof raw.size === "number" ? raw.size : void 0,
+    read: bytes ? bytes.read : unavailable,
+    stream: bytes?.stream
+  });
+};
+var deserializeReaction = (raw, spaceRef) => (
+  // `target` is a raw record; `wrapNestedContent` wraps it into a Message.
+  {
+    type: "reaction",
+    emoji: asString(raw.emoji),
+    target: buildTargetRecord(raw.target, spaceRef)
+  }
+);
+var buildTargetRecord = (target, spaceRef) => {
+  const ref = isRecord(target) ? target : {};
+  return {
+    id: asString(ref.id),
+    // The target's full content is not delivered; the 80-char `contentPreview`
+    // (text targets only) is the best available stand-in.
+    content: { type: "text", text: asString(ref.contentPreview) },
+    space: { ...spaceRef },
+    sender: ref.sender ? { ...ref.sender } : void 0,
+    timestamp: asOptionalDate(ref.timestamp)
+  };
+};
+var deserializeGroup = (raw, platform, spaceRef, ctx) => {
+  const rawItems = Array.isArray(raw.items) ? raw.items : [];
+  return {
+    type: "group",
+    items: rawItems.map(
+      (item) => buildItemRecord(item, platform, spaceRef, ctx)
+    )
+  };
+};
+var buildItemRecord = (item, platform, spaceRef, ctx) => {
+  const record = isRecord(item) ? item : {};
+  const itemSpace = isRecord(record.space) ? {
+    ...record.space,
+    id: asString(record.space.id) || spaceRef.id
+  } : spaceRef;
+  const content = isRecord(record.content) ? deserializeContent(
+    record.content,
+    platform,
+    itemSpace,
+    ctx
+  ) : asCustom(record.content);
+  return {
+    id: asString(record.id),
+    content,
+    space: itemSpace,
+    sender: isRecord(record.sender) ? { ...record.sender, id: asString(record.sender.id) } : void 0,
+    timestamp: asOptionalDate(record.timestamp)
+  };
+};
+var deserializeContact = (raw) => {
+  const input = {};
+  const name = normalizeContactName(raw.name);
+  if (name) {
+    input.name = name;
+  }
+  const phones = normalizeContactPhones(raw.phones);
+  if (phones) {
+    input.phones = phones;
+  }
+  if (typeof raw.note === "string") {
+    input.note = raw.note;
+  }
+  if (raw.raw !== void 0) {
+    input.raw = raw.raw;
+  }
+  return asContact(input);
+};
+var CONTACT_NAME_KEYS = [
+  "formatted",
+  "first",
+  "last",
+  "middle",
+  "prefix",
+  "suffix"
+];
+var normalizeContactName = (value) => {
+  if (typeof value === "string") {
+    return { formatted: value };
+  }
+  if (!isRecord(value)) {
+    return;
+  }
+  const name = {};
+  for (const key of CONTACT_NAME_KEYS) {
+    const part = value[key];
+    if (typeof part === "string") {
+      name[key] = part;
+    }
+  }
+  return Object.keys(name).length > 0 ? name : void 0;
+};
+var normalizeContactPhones = (value) => {
+  if (!Array.isArray(value)) {
+    return;
+  }
+  const phones = [];
+  for (const entry of value) {
+    if (typeof entry === "string") {
+      phones.push({ value: entry });
+    } else if (isRecord(entry) && typeof entry.value === "string") {
+      phones.push({ value: entry.value });
+    }
+  }
+  return phones.length > 0 ? phones : void 0;
+};
+
+// src/webhook/types.ts
+import z from "zod";
+var slimSenderSchema = z.looseObject({
+  id: z.string(),
+  platform: z.string().optional()
+});
+var slimSpaceSchema = z.looseObject({
+  id: z.string(),
+  platform: z.string().optional()
+});
+var slimContentSchema = z.looseObject({
+  type: z.string()
+});
+var slimMessageRefSchema = z.looseObject({
+  id: z.string(),
+  platform: z.string().optional(),
+  timestamp: z.string().optional(),
+  sender: slimSenderSchema.optional(),
+  contentPreview: z.string().optional()
+});
+var slimMessageSchema = z.looseObject({
+  id: z.string(),
+  platform: z.string().optional(),
+  // Webhooks are inbound-only; `direction` is left loose (not a `"inbound"`
+  // literal) so a future direction value cannot fail an older SDK's parse.
+  direction: z.string().optional(),
+  timestamp: z.string().optional(),
+  sender: slimSenderSchema.optional(),
+  space: slimSpaceSchema,
+  content: slimContentSchema
+});
+var slimEnvelopeSchema = z.looseObject({
+  event: z.string(),
+  space: slimSpaceSchema.optional(),
+  message: slimMessageSchema
+});
+
+// src/webhook/verify.ts
+import { createHmac, timingSafeEqual } from "crypto";
+var SIGNATURE_HEADER = "x-spectrum-signature";
+var TIMESTAMP_HEADER = "x-spectrum-timestamp";
+var SIGNATURE_PREFIX = "v0=";
+var SIGNATURE_SCHEME = "v0";
+var REPLAY_TOLERANCE_SECONDS = 300;
+var MILLIS_PER_SECOND = 1e3;
+function verifySpectrumSignature(input) {
+  const { rawBody, headers, secret, now = Date.now() } = input;
+  const provided = headers[SIGNATURE_HEADER];
+  const timestamp = headers[TIMESTAMP_HEADER];
+  if (!(provided && timestamp)) {
+    return { ok: false, reason: "missing-headers" };
+  }
+  const timestampSeconds = Number(timestamp);
+  if (!Number.isFinite(timestampSeconds)) {
+    return { ok: false, reason: "missing-headers" };
+  }
+  const nowSeconds = Math.floor(now / MILLIS_PER_SECOND);
+  if (Math.abs(nowSeconds - timestampSeconds) > REPLAY_TOLERANCE_SECONDS) {
+    return { ok: false, reason: "expired" };
+  }
+  const base = Buffer.concat([
+    Buffer.from(`${SIGNATURE_SCHEME}:${timestamp}:`, "utf8"),
+    Buffer.from(rawBody)
+  ]);
+  const expected = createHmac("sha256", secret).update(base).digest();
+  const providedHex = provided.startsWith(SIGNATURE_PREFIX) ? provided.slice(SIGNATURE_PREFIX.length) : provided;
+  const providedBytes = Buffer.from(providedHex, "hex");
+  if (providedBytes.length !== expected.length || !timingSafeEqual(providedBytes, expected)) {
+    return { ok: false, reason: "signature-mismatch" };
+  }
+  return { ok: true };
+}
+
 // src/spectrum.ts
 var PHOTON_OTEL_ENDPOINT = "https://otlp.photon.codes";
 var STREAM_CLOSE_TIMEOUT_MS = 5e3;
 var lifecycleLog = createLogger3("spectrum.lifecycle");
 var ignoreCleanupError = () => void 0;
-var spectrumOptionsSchema = z.object({
-  flattenGroups: z.boolean().optional()
+var spectrumOptionsSchema = z2.object({
+  flattenGroups: z2.boolean().optional()
 }).optional();
-var spectrumConfigSchema = z.union([
-  z.object({
-    projectId: z.string().min(1),
-    projectSecret: z.string().min(1),
-    providers: z.array(z.custom()),
+var spectrumConfigSchema = z2.union([
+  z2.object({
+    projectId: z2.string().min(1),
+    projectSecret: z2.string().min(1),
+    providers: z2.array(z2.custom()),
     options: spectrumOptionsSchema,
-    telemetry: z.boolean().optional()
+    telemetry: z2.boolean().optional(),
+    webhookSecret: z2.string().min(1).optional()
   }),
-  z.object({
-    projectId: z.undefined().optional(),
-    projectSecret: z.undefined().optional(),
-    providers: z.array(z.custom()),
+  z2.object({
+    projectId: z2.undefined().optional(),
+    projectSecret: z2.undefined().optional(),
+    providers: z2.array(z2.custom()),
     options: spectrumOptionsSchema,
-    telemetry: z.boolean().optional()
+    telemetry: z2.boolean().optional(),
+    webhookSecret: z2.string().min(1).optional()
   })
 ]);
 function bootstrapTelemetry(opts) {
@@ -2758,9 +3018,11 @@ async function Spectrum(options) {
     projectSecret,
     providers,
     options: runtimeOptions,
-    telemetry
+    telemetry,
+    webhookSecret
   } = options;
   const flattenGroups = runtimeOptions?.flattenGroups ?? false;
+  const resolvedWebhookSecret = webhookSecret ?? process.env.SPECTRUM_WEBHOOK_SECRET;
   const otelHandle = telemetry ? bootstrapTelemetry({ projectId, projectSecret }) : void 0;
   const projectConfig = projectId !== void 0 && projectSecret !== void 0 ? await cloud.getProject(projectId, projectSecret) : void 0;
   const platformStates = /* @__PURE__ */ new Map();
@@ -3217,16 +3479,25 @@ async function Spectrum(options) {
   };
   const readWebhookInput = async (request) => {
     if (typeof Request !== "undefined" && request instanceof Request) {
+      const headers2 = {};
+      for (const [key, value] of request.headers) {
+        headers2[key.toLowerCase()] = value;
+      }
       return {
         asWeb: true,
-        bodyBytes: new Uint8Array(await request.arrayBuffer())
+        bodyBytes: new Uint8Array(await request.arrayBuffer()),
+        headers: headers2
       };
     }
     const raw = request;
     const bodyBytes = raw.body instanceof ArrayBuffer ? new Uint8Array(raw.body) : raw.body;
-    return { asWeb: false, bodyBytes };
+    const headers = {};
+    for (const [key, value] of Object.entries(raw.headers ?? {})) {
+      headers[key.toLowerCase()] = String(value);
+    }
+    return { asWeb: false, bodyBytes, headers };
   };
-  const deliverWebhookMessages = async (collected, runtime, handler, event) => {
+  const deliverWebhookMessages = async (collected, runtime, handler, context) => {
     for (const record of collected) {
       const tuples = await resolveRecordToMessages(record, runtime);
       for (const [space, message] of tuples) {
@@ -3236,8 +3507,8 @@ async function Spectrum(options) {
           lifecycleLog.error(
             `spectrum.webhook: handler threw (async), ${error}`,
             {
-              eventId: event.eventId,
-              platform: event.platform,
+              eventId: context.eventId,
+              platform: context.platform,
               messageId: message.id,
               error: error instanceof Error ? error.message : String(error)
             }
@@ -3290,13 +3561,132 @@ async function Spectrum(options) {
     }
     return result;
   };
+  const looksLikeNativePayload = (bodyBytes) => {
+    for (const byte of bodyBytes) {
+      if (byte === 32 || byte === 9 || byte === 10 || byte === 13) {
+        continue;
+      }
+      return byte === 123;
+    }
+    return false;
+  };
+  const webhookText = (status, text2) => ({
+    status,
+    headers: {},
+    body: encodeText(text2)
+  });
+  const resolveWebhookAttachment = (platform, spaceRef, attachmentId) => {
+    const runtime = platformStates.get(platform);
+    const action = runtime?.definition?.actions?.getAttachment;
+    if (!runtime || typeof action !== "function") {
+      return;
+    }
+    const getAttachment = action;
+    const phone = typeof spaceRef.phone === "string" ? spaceRef.phone : void 0;
+    let cached;
+    const fetchOnce = () => {
+      cached ??= getAttachment(
+        {
+          client: runtime.client,
+          config: runtime.config,
+          store: runtime.store
+        },
+        attachmentId,
+        phone
+      );
+      return cached;
+    };
+    return {
+      read: async () => {
+        const found = await fetchOnce();
+        if (!found) {
+          throw new Error(
+            `Spectrum webhook attachment "${attachmentId}" not found on "${platform}"`
+          );
+        }
+        return found.read();
+      },
+      stream: async () => {
+        const found = await fetchOnce();
+        if (!found?.stream) {
+          throw new Error(
+            `Spectrum webhook attachment "${attachmentId}" has no stream on "${platform}"`
+          );
+        }
+        return found.stream();
+      }
+    };
+  };
+  const handleSpectrumWebhook = async (bodyBytes, headers, handler) => {
+    if (!resolvedWebhookSecret) {
+      lifecycleLog.error(
+        "spectrum.webhook: received a signed Spectrum webhook but no webhookSecret is configured (set Spectrum({ webhookSecret }) or SPECTRUM_WEBHOOK_SECRET)"
+      );
+      return webhookText(500, "webhook secret not configured");
+    }
+    const verification = verifySpectrumSignature({
+      rawBody: bodyBytes,
+      headers,
+      secret: resolvedWebhookSecret
+    });
+    if (!verification.ok) {
+      const status = verification.reason === "missing-headers" ? 400 : 401;
+      return webhookText(status, verification.reason);
+    }
+    let envelope;
+    try {
+      const parsed = JSON.parse(new TextDecoder().decode(bodyBytes));
+      envelope = slimEnvelopeSchema.parse(parsed);
+    } catch (error) {
+      lifecycleLog.warn(
+        `spectrum.webhook: malformed Spectrum webhook payload, ${error}`
+      );
+      return webhookText(400, "malformed payload");
+    }
+    const deserialized = deserializeSpectrumMessage(envelope, {
+      resolveAttachment: resolveWebhookAttachment
+    });
+    if (!deserialized) {
+      return webhookText(200, "ok");
+    }
+    const { platform, record } = deserialized;
+    const runtime = platformStates.get(platform);
+    if (!runtime) {
+      lifecycleLog.warn(
+        `spectrum.webhook: no provider configured for platform "${platform}"; acknowledging without delivery`,
+        { platform }
+      );
+      return webhookText(200, "ok");
+    }
+    deliverWebhookMessages([record], runtime, handler, { platform }).catch(
+      (error) => {
+        lifecycleLog.error(
+          `spectrum.webhook: Spectrum delivery failed (async), ${error}`,
+          {
+            platform,
+            messageId: record.id,
+            error: error instanceof Error ? error.message : String(error)
+          }
+        );
+      }
+    );
+    return webhookText(200, "ok");
+  };
   const handleWebhook = async (request, handler) => {
+    const { asWeb, bodyBytes, headers } = await readWebhookInput(request);
+    if (looksLikeNativePayload(bodyBytes)) {
+      const spectrumResult = await handleSpectrumWebhook(
+        bodyBytes,
+        headers,
+        handler
+      );
+      return buildWebhookResult(asWeb, spectrumResult);
+    }
     if (!fusorCore) {
       throw new Error(
-        "spectrum.webhook() requires at least one fusor provider; none are configured"
+        "spectrum.webhook() received a non-Spectrum (fusor) request but no fusor provider is configured"
       );
     }
-    const { asWeb, bodyBytes } = await readWebhookInput(request);
     const event = decodeWebhookEvent(bodyBytes);
     if (!event) {
       return buildWebhookResult(asWeb, {

package/dist/providers/imessage/index.d.ts

@@ -124,8 +124,8 @@ declare const userSchema: z__default.ZodObject<{}, z__default.core.$strip>;
 declare const spaceSchema: z__default.ZodObject<{
     id: z__default.ZodString;
     type: z__default.ZodEnum<{
-        group: "group";
         dm: "dm";
+        group: "group";
     }>;
     phone: z__default.ZodString;
 }, z__default.core.$strip>;
@@ -151,8 +151,8 @@ declare const imessage: Platform<PlatformDef<"iMessage", z.ZodUnion<readonly [z.
 }, zod_v4_core.$strip>]>, z.ZodType<object, unknown, zod_v4_core.$ZodTypeInternals<object, unknown>> | undefined, z.ZodObject<{
     id: z.ZodString;
     type: z.ZodEnum<{
-        group: "group";
         dm: "dm";
+        group: "group";
     }>;
     phone: z.ZodString;
 }, zod_v4_core.$strip>, z.ZodObject<{
@@ -161,7 +161,7 @@ declare const imessage: Platform<PlatformDef<"iMessage", z.ZodUnion<readonly [z.
     id: string;
 }, {
     id: string;
-    type: "group" | "dm";
+    type: "dm" | "group";
     phone: string;
 }, z.ZodObject<{
     partIndex: z.ZodOptional<z.ZodNumber>;
@@ -190,7 +190,7 @@ declare const imessage: Platform<PlatformDef<"iMessage", z.ZodUnion<readonly [z.
         store: Store;
     }, space: {
         id: string;
-        type: "group" | "dm";
+        type: "dm" | "group";
         phone: string;
     } & {
         id: string;

package/dist/providers/imessage/index.js

@@ -4,14 +4,14 @@ import {
   customizedMiniApp,
   effect,
   imessage
-} from "../../chunk-DMT6BFJV.js";
+} from "../../chunk-NLMQ75LH.js";
 import "../../chunk-ZR3TKZMT.js";
 import "../../chunk-LZXPLXZF.js";
 import "../../chunk-2D27WW5B.js";
-import "../../chunk-3GEJYGZK.js";
 import "../../chunk-A37PM5N2.js";
-import "../../chunk-5XEFJBN2.js";
 import "../../chunk-6UZFVXQF.js";
+import "../../chunk-3GEJYGZK.js";
+import "../../chunk-5XEFJBN2.js";
 import {
   read
 } from "../../chunk-B52VPQO3.js";

package/dist/providers/index.d.ts

@@ -13,7 +13,7 @@ import '@photon-ai/advanced-imessage';
 import '@photon-ai/imessage-kit';
 import '@photon-ai/slack';
 import '@photon-ai/telegram-ts';
-import '../types-BIta6Kxi.js';
+import '../types-ZgFTj5hJ.js';
 import 'node:child_process';
 import 'node:net';
 import '@photon-ai/whatsapp-business';

package/dist/providers/index.js

@@ -1,28 +1,28 @@
 import { createRequire as __spectrumCreateRequire } from "node:module"; const require = __spectrumCreateRequire(import.meta.url);
-import {
-  imessage
-} from "../chunk-DMT6BFJV.js";
-import "../chunk-ZR3TKZMT.js";
-import {
-  slack
-} from "../chunk-WXLQNANA.js";
 import {
   telegram
-} from "../chunk-U3QQ56YZ.js";
-import "../chunk-34FQGGD7.js";
-import "../chunk-LZXPLXZF.js";
+} from "../chunk-N6THJDZV.js";
 import {
   terminal
-} from "../chunk-IM5ADDZS.js";
-import "../chunk-FAIFTUV2.js";
+} from "../chunk-ARL2NOBO.js";
 import {
   whatsappBusiness
-} from "../chunk-3KWFP4L2.js";
+} from "../chunk-DMPDLSFU.js";
+import "../chunk-34FQGGD7.js";
+import "../chunk-FAIFTUV2.js";
+import {
+  imessage
+} from "../chunk-NLMQ75LH.js";
+import "../chunk-ZR3TKZMT.js";
+import "../chunk-LZXPLXZF.js";
 import "../chunk-2D27WW5B.js";
-import "../chunk-3GEJYGZK.js";
 import "../chunk-A37PM5N2.js";
-import "../chunk-5XEFJBN2.js";
 import "../chunk-6UZFVXQF.js";
+import {
+  slack
+} from "../chunk-WXLQNANA.js";
+import "../chunk-3GEJYGZK.js";
+import "../chunk-5XEFJBN2.js";
 import "../chunk-B52VPQO3.js";
 import "../chunk-UXAKIXVM.js";
 export {

package/dist/providers/telegram/index.d.ts

@@ -3,7 +3,7 @@ import * as _photon_ai_telegram_ts from '@photon-ai/telegram-ts';
 import * as zod_v4_core from 'zod/v4/core';
 import * as z from 'zod';
 import z__default from 'zod';
-import { F as FusorClient } from '../../types-BIta6Kxi.js';
+import { F as FusorClient } from '../../types-ZgFTj5hJ.js';
 import 'hotscript';
 
 interface TelegramSpace {

package/dist/providers/telegram/index.js

@@ -1,10 +1,10 @@
 import { createRequire as __spectrumCreateRequire } from "node:module"; const require = __spectrumCreateRequire(import.meta.url);
 import {
   telegram
-} from "../../chunk-U3QQ56YZ.js";
+} from "../../chunk-N6THJDZV.js";
 import "../../chunk-34FQGGD7.js";
-import "../../chunk-LZXPLXZF.js";
 import "../../chunk-FAIFTUV2.js";
+import "../../chunk-LZXPLXZF.js";
 import "../../chunk-6UZFVXQF.js";
 import "../../chunk-B52VPQO3.js";
 import "../../chunk-UXAKIXVM.js";

package/dist/providers/terminal/index.js

@@ -1,11 +1,11 @@
 import { createRequire as __spectrumCreateRequire } from "node:module"; const require = __spectrumCreateRequire(import.meta.url);
 import {
   terminal
-} from "../../chunk-IM5ADDZS.js";
+} from "../../chunk-ARL2NOBO.js";
 import "../../chunk-FAIFTUV2.js";
 import "../../chunk-A37PM5N2.js";
-import "../../chunk-5XEFJBN2.js";
 import "../../chunk-6UZFVXQF.js";
+import "../../chunk-5XEFJBN2.js";
 import "../../chunk-B52VPQO3.js";
 import "../../chunk-UXAKIXVM.js";
 export {

package/dist/providers/whatsapp-business/index.js

@@ -1,12 +1,12 @@
 import { createRequire as __spectrumCreateRequire } from "node:module"; const require = __spectrumCreateRequire(import.meta.url);
 import {
   whatsappBusiness
-} from "../../chunk-3KWFP4L2.js";
+} from "../../chunk-DMPDLSFU.js";
 import "../../chunk-2D27WW5B.js";
-import "../../chunk-3GEJYGZK.js";
 import "../../chunk-A37PM5N2.js";
-import "../../chunk-5XEFJBN2.js";
 import "../../chunk-6UZFVXQF.js";
+import "../../chunk-3GEJYGZK.js";
+import "../../chunk-5XEFJBN2.js";
 import "../../chunk-B52VPQO3.js";
 import "../../chunk-UXAKIXVM.js";
 export {

package/dist/{types-BIta6Kxi.d.ts → types-ZgFTj5hJ.d.ts}

@@ -62,11 +62,16 @@ interface FusorClient<TPayload = unknown> {
 type WebhookHandler = (space: Space, message: Message) => void | Promise<void>;
 /**
  * Raw webhook input for HTTP servers without Web `Request`/`Response` (Express,
- * raw Node). `body` MUST be the exact bytes fusor POSTed — never a re-encoded
- * JSON/text body — so the protobuf decode works. `headers` are accepted (so the
- * natural `{ headers: req.headers, body: req.body }` shape keeps working) but are
- * not read: inbound authenticity is established by the per-platform `verify()`,
- * which reads the inner request reconstructed from the envelope.
+ * raw Node). `body` MUST be the exact bytes POSTed — never a re-encoded
+ * JSON/text body — so both the protobuf decode (fusor) and the HMAC
+ * verification (native Spectrum webhook) work.
+ *
+ * `headers` ARE read for **native Spectrum webhooks**: `X-Spectrum-Signature` /
+ * `X-Spectrum-Timestamp` carry the HMAC verified against
+ * `Spectrum({ webhookSecret })`, and the signature header also selects the
+ * native path. For **fusor** envelopes they are ignored (authenticity is the
+ * per-platform `verify()` reading the inner reconstructed request). The natural
+ * `{ headers: req.headers, body: req.body }` shape works for both.
  */
 interface WebhookRawRequest {
     body: Uint8Array | ArrayBuffer;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spectrum-ts",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "Bring agents to any interface — unified messaging SDK for TypeScript.",
   "repository": {
     "type": "git",
@@ -27,6 +27,18 @@
       "types": "./dist/authoring.d.ts",
       "default": "./dist/authoring.js"
     },
+    "./elysia": {
+      "types": "./dist/elysia.d.ts",
+      "default": "./dist/elysia.js"
+    },
+    "./express": {
+      "types": "./dist/express.d.ts",
+      "default": "./dist/express.js"
+    },
+    "./hono": {
+      "types": "./dist/hono.d.ts",
+      "default": "./dist/hono.js"
+    },
     "./providers": {
       "types": "./dist/providers/index.d.ts",
       "default": "./dist/providers/index.js"
@@ -55,12 +67,24 @@
     "zod": "^4.2.1"
   },
   "peerDependencies": {
+    "elysia": "^1",
+    "express": "^4 || ^5",
     "ffmpeg-static": "^5",
+    "hono": "^4",
     "typescript": "^5 || ^6.0.0"
   },
   "peerDependenciesMeta": {
+    "elysia": {
+      "optional": true
+    },
+    "express": {
+      "optional": true
+    },
     "ffmpeg-static": {
       "optional": true
+    },
+    "hono": {
+      "optional": true
     }
   },
   "license": "MIT"

package/dist/{chunk-IM5ADDZS.js → chunk-ARL2NOBO.js}

@@ -5,13 +5,13 @@ import {
 import {
   asContact
 } from "./chunk-A37PM5N2.js";
-import {
-  stream
-} from "./chunk-5XEFJBN2.js";
 import {
   fromVCard,
   toVCard
 } from "./chunk-6UZFVXQF.js";
+import {
+  stream
+} from "./chunk-5XEFJBN2.js";
 import {
   UnsupportedError,
   definePlatform

package/dist/{chunk-3KWFP4L2.js → chunk-DMPDLSFU.js}

@@ -2,12 +2,12 @@ import { createRequire as __spectrumCreateRequire } from "node:module"; const re
 import {
   asPollOption
 } from "./chunk-2D27WW5B.js";
-import {
-  cloud
-} from "./chunk-3GEJYGZK.js";
 import {
   asContact
 } from "./chunk-A37PM5N2.js";
+import {
+  cloud
+} from "./chunk-3GEJYGZK.js";
 import {
   mergeStreams,
   stream

package/dist/{chunk-U3QQ56YZ.js → chunk-N6THJDZV.js}

@@ -2,12 +2,12 @@ import { createRequire as __spectrumCreateRequire } from "node:module"; const re
 import {
   fusor
 } from "./chunk-34FQGGD7.js";
-import {
-  asGroup
-} from "./chunk-LZXPLXZF.js";
 import {
   asVoice
 } from "./chunk-FAIFTUV2.js";
+import {
+  asGroup
+} from "./chunk-LZXPLXZF.js";
 import {
   toVCard
 } from "./chunk-6UZFVXQF.js";

package/dist/{chunk-DMT6BFJV.js → chunk-NLMQ75LH.js}

@@ -10,20 +10,20 @@ import {
   asPoll,
   asPollOption
 } from "./chunk-2D27WW5B.js";
-import {
-  cloud
-} from "./chunk-3GEJYGZK.js";
 import {
   asContact
 } from "./chunk-A37PM5N2.js";
-import {
-  mergeStreams,
-  stream
-} from "./chunk-5XEFJBN2.js";
 import {
   fromVCard,
   toVCard
 } from "./chunk-6UZFVXQF.js";
+import {
+  cloud
+} from "./chunk-3GEJYGZK.js";
+import {
+  mergeStreams,
+  stream
+} from "./chunk-5XEFJBN2.js";
 import {
   UnsupportedError,
   buildPhotoAction,