spectrum-ts 4.0.0 → 4.2.0

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

@@ -1,12 +1,13 @@
-export { A as Attachment, a as AttachmentInput, b as attachment } from './attachment-CEpGtZLm.js';
+export { A as Attachment, a as AttachmentInput, b as attachment } from './attachment-CnivEhr6.js';
 import z__default from 'zod';
-import { P as PhotoInput } from './photo-content-BJKnqgN-.js';
-import { C as ContentBuilder, M as Message, U as User, e as Space, h as ContentInput, i as Content, g as ProviderMessage, E as EventProducer, j as SpaceActionFn, k as MessageActionFn, I as InstanceActionFn, l as CreateClientContext, c as Store, a as PlatformDef, P as Platform, m as PlatformProviderConfig, n as SpectrumLike, o as CustomEventStreams, A as AgentSender, b as ProjectData } from './types-Be0T6E0e.js';
-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, S 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-Be0T6E0e.js';
-import { S as StreamTextSource, T as TextStreamOptions, C as ContactInput, a as Contact } from './authoring-CP3vRza8.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-CP3vRza8.js';
-import { a as FusorVerify, F as FusorClient, b as FusorMessages, W as WebhookHandler, c as WebhookRawRequest, d as WebhookRawResult } from './types-CDYXH2R7.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-CDYXH2R7.js';
+import { P as PhotoInput } from './read-C4uvozGX.js';
+export { R as Read, r as read } from './read-C4uvozGX.js';
+import { C as ContentBuilder, M as Message, U as User, S as Space, h as ContentInput, i as Content, g as ProviderMessage, E as EventProducer, j as SpaceActionFn, k as MessageActionFn, I as InstanceActionFn, l as CreateClientContext, d as Store, b as PlatformDef, P as Platform, m as PlatformProviderConfig, n as SpectrumLike, o as CustomEventStreams, A as AgentSender, c as ProjectData } from './types-CyfLJXgu.js';
+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-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';
 
@@ -67,7 +68,7 @@ declare function avatar(input: Buffer, options: {
  * (no new message id is produced; the existing message mutates in place).
  *
  * Edit cannot wrap `edit`, `reply`, `reaction`, `group`, `typing`, `rename`,
- * `avatar`, or `unsend` content.
+ * `avatar`, `unsend`, or `read` content.
  */
 declare const editSchema: z__default.ZodObject<{
     type: z__default.ZodLiteral<"edit">;
@@ -427,7 +428,7 @@ declare function rename(displayName: string): ContentBuilder;
  * `reply` like any other content type and route to a threaded send.
  *
  * Reply cannot wrap `reply`, `edit`, `reaction`, `group`, `typing`,
- * `rename`, `avatar`, or `unsend` content.
+ * `rename`, `avatar`, `unsend`, or `read` content.
  */
 declare const replySchema: z__default.ZodObject<{
     type: z__default.ZodLiteral<"reply">;
@@ -2756,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
@@ -2771,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>;
@@ -2799,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;
 }>;
@@ -2808,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";