@spectrum-ts/core 5.0.0

package/dist/authoring.d.ts

@@ -0,0 +1,94 @@
+import { $t as groupSchema, Bt as asPollOption, Dn as buildPhotoAction, En as PhotoInput, H as ProviderMessageRecord, K as ManagedStream, Nt as asRead, On as photoActionSchema, St as asText, Tt as asRichlink, Wt as asMarkdown, Zt as asGroup, cn as reactionSchema, gt as asVoice, ln as asCustom, on as asReaction, r as asAttachment, yn as asContact, zt as asPoll } from "./attachment-a_lrhg6w.js";
+import z from "zod";
+import { LogAttrs, LogAttrs as LogAttrs$1, LogLevel, PhotonLogger, createLogger, sanitizeEmail, sanitizeErrorMessage, sanitizePhone, setLogLevel } from "@photon-ai/otel";
+import { Token } from "marked";
+
+//#region src/content/effect.d.ts
+declare const messageEffectSchema: z.ZodObject<{
+  type: z.ZodLiteral<"effect">;
+  content: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    text: z.ZodString;
+  }, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"markdown">;
+    markdown: z.ZodString;
+  }, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"attachment">;
+    id: z.ZodString;
+    name: z.ZodString;
+    mimeType: z.ZodString;
+    size: z.ZodOptional<z.ZodNumber>;
+    read: z.ZodFunction<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
+    stream: z.ZodFunction<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodCustom<ReadableStream<unknown>, ReadableStream<unknown>>>>;
+  }, z.core.$strip>], "type">;
+  effect: z.ZodString;
+}, z.core.$strip>;
+//#endregion
+//#region src/utils/audio.d.ts
+declare const ensureM4a: (buffer: Buffer, mimeType: string) => Promise<{
+  buffer: Buffer;
+  duration?: number;
+}>;
+//#endregion
+//#region src/utils/markdown.d.ts
+/**
+ * Render a run of inline markdown tokens (a paragraph's or table cell's
+ * children) to plain text. Package-internal: platform renderers reuse it
+ * where their native format has no inline markup (e.g. Telegram tables).
+ */
+declare const renderInlineTokens: (tokens: Token[]) => string;
+//#endregion
+//#region src/utils/resumable-stream.d.ts
+interface CloseableAsyncIterable<T> extends AsyncIterable<T> {
+  close?: () => Promise<void> | void;
+}
+interface ResumableStreamItem<T> {
+  cursor?: string;
+  id: string;
+  values: readonly T[];
+}
+interface FetchMissedOptions {
+  limit: number;
+}
+interface ResumableOrderedStreamOptions<TLive, TMissed, TOutput> {
+  bufferLimit?: number;
+  catchUpPageSize?: number;
+  fetchMissed: (cursor: string, options: FetchMissedOptions) => AsyncIterable<TMissed>;
+  initialRetryDelayMs?: number;
+  /**
+   * Recognizes a `fetchMissed` failure that means the server rejected the
+   * resume cursor (e.g. it was pruned). The stream then drops the cursor,
+   * accepts the event gap, and resumes live. Only errors raised by the
+   * `fetchMissed` iteration itself are classified.
+   */
+  isCursorRejectedError?: (error: unknown) => boolean;
+  /** Maps a nominal retry delay to the actual sleep; injectable for tests. */
+  jitter?: (delayMs: number) => number;
+  /** Log provenance, e.g. "imessage.messages:+1555…". */
+  label?: string;
+  maxRetryDelayMs?: number;
+  processLive: (event: TLive) => Promise<ResumableStreamItem<TOutput>>;
+  processMissed: (event: TMissed) => Promise<ResumableStreamItem<TOutput>>;
+  subscribeLive: (cursor?: string) => CloseableAsyncIterable<TLive>;
+}
+/**
+ * Wraps a live event stream with cursor-based catch-up and reconnects forever
+ * with capped, jittered exponential backoff — the stream never ends with an
+ * error. The only terminal events are `close()` and consumer disconnect. When
+ * the server rejects the resume cursor, the cursor is dropped and consumption
+ * falls back to live, accepting (and logging) the event gap.
+ */
+declare const resumableOrderedStream: <TLive, TMissed, TOutput>(options: ResumableOrderedStreamOptions<TLive, TMissed, TOutput>) => ManagedStream<TOutput>;
+//#endregion
+//#region src/utils/telemetry.d.ts
+/**
+ * Structured attributes for an unknown thrown value: its type, sanitized
+ * message, `code`/`status` when present, and one level of `cause`. Enough to
+ * debug from a log line or span without leaking PII or dumping a raw `Error`
+ * (which stringifies to "[object Object]" inside an attrs object). The stack is
+ * intentionally omitted — pass the `Error` as the logger's 3rd argument (or
+ * wrap with `withSpan`) so it lands on the OTLP record's `exception.*` fields.
+ */
+declare function errorAttrs(error: unknown, prefix?: string): LogAttrs$1;
+//#endregion
+export { type CloseableAsyncIterable, type LogAttrs, type LogLevel, type PhotoInput, type PhotonLogger, type ProviderMessageRecord, type ResumableStreamItem, asAttachment, asContact, asCustom, asGroup, asMarkdown, asPoll, asPollOption, asReaction, asRead, asRichlink, asText, asVoice, buildPhotoAction, createLogger, ensureM4a, errorAttrs, groupSchema, messageEffectSchema, photoActionSchema, reactionSchema, renderInlineTokens, resumableOrderedStream, sanitizeEmail, sanitizeErrorMessage, sanitizePhone, setLogLevel };

package/dist/authoring.js

@@ -0,0 +1,389 @@
+import { D as asGroup, E as markdownSchema, H as buildPhotoAction, I as asCustom, K as attachmentSchema, N as textSchema, R as asContact, U as photoActionSchema, W as asAttachment, _ as asReaction, b as asPoll, d as asVoice, h as asRead, i as stream, j as asText, k as groupSchema, l as renderInlineTokens, o as errorAttrs, p as asRichlink, w as asMarkdown, x as asPollOption, y as reactionSchema } from "./stream-BLWs7NJ5.js";
+import z from "zod";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { createLogger, createLogger as createLogger$1, sanitizeEmail, sanitizeErrorMessage, sanitizePhone, setLogLevel } from "@photon-ai/otel";
+import { spawn } from "node:child_process";
+import { tmpdir } from "node:os";
+//#region src/content/effect.ts
+const effectInnerSchema = z.discriminatedUnion("type", [
+	textSchema,
+	markdownSchema,
+	attachmentSchema
+]);
+const messageEffectSchema = z.object({
+	type: z.literal("effect"),
+	content: effectInnerSchema,
+	effect: z.string().nonempty()
+});
+//#endregion
+//#region src/utils/audio.ts
+const M4A_BRANDS = new Set([
+	"M4A ",
+	"M4B ",
+	"M4P ",
+	"mp42",
+	"mp41",
+	"isom",
+	"iso2"
+]);
+const M4A_MIME_TYPES = new Set([
+	"audio/mp4",
+	"audio/mp4a-latm",
+	"audio/x-m4a",
+	"audio/aac",
+	"audio/aacp"
+]);
+const FFMPEG_MISSING_MESSAGE = "voice content: input is not m4a/aac and ffmpeg is unavailable. Install `ffmpeg-static` or ensure `ffmpeg` is on PATH.";
+const isM4a = (buffer) => {
+	if (buffer.length < 12) return false;
+	if (buffer.toString("ascii", 4, 8) !== "ftyp") return false;
+	return M4A_BRANDS.has(buffer.toString("ascii", 8, 12));
+};
+const isM4aMimeType = (mimeType) => M4A_MIME_TYPES.has(mimeType.toLowerCase());
+let cachedFfmpegPath;
+const tryStaticBinary = async () => {
+	try {
+		return (await import("ffmpeg-static")).default ?? void 0;
+	} catch {
+		return;
+	}
+};
+const resolveFfmpegPath = async () => {
+	if (cachedFfmpegPath) return cachedFfmpegPath;
+	cachedFfmpegPath = await tryStaticBinary() ?? "ffmpeg";
+	return cachedFfmpegPath;
+};
+const collectStream = (stream) => {
+	if (!stream) return Promise.resolve("");
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		stream.on("data", (chunk) => {
+			chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+		});
+		stream.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+		stream.on("error", reject);
+	});
+};
+const isMissingBinaryError = (err) => err?.code === "ENOENT";
+const runFfmpeg = (ffmpegPath, args) => {
+	const proc = spawn(ffmpegPath, args, { stdio: [
+		"ignore",
+		"ignore",
+		"pipe"
+	] });
+	const stderr = collectStream(proc.stderr);
+	const exit = new Promise((resolve, reject) => {
+		proc.on("error", (err) => reject(isMissingBinaryError(err) ? /* @__PURE__ */ new Error(FFMPEG_MISSING_MESSAGE) : err));
+		proc.on("exit", (code) => resolve(code ?? -1));
+	});
+	return Promise.all([exit, stderr]).then(([code, text]) => ({
+		code,
+		stderr: text
+	}));
+};
+const DURATION_PATTERN = /Duration:\s*(\d+):(\d{2}):(\d{2})(?:\.(\d{1,3}))?/;
+const parseDuration = (stderr) => {
+	const match = stderr.match(DURATION_PATTERN);
+	if (!match) return;
+	const [, hh, mm, ss, frac] = match;
+	const seconds = Number(hh) * 3600 + Number(mm) * 60 + Number(ss) + Number(`0.${frac ?? 0}`);
+	return Number.isFinite(seconds) ? seconds : void 0;
+};
+const transcodeToM4a = async (buffer) => {
+	const ffmpeg = await resolveFfmpegPath();
+	const dir = await mkdtemp(join(tmpdir(), "spectrum-voice-"));
+	const inPath = join(dir, "in");
+	const outPath = join(dir, "out.m4a");
+	try {
+		await writeFile(inPath, buffer);
+		const { code, stderr } = await runFfmpeg(ffmpeg, [
+			"-y",
+			"-i",
+			inPath,
+			"-f",
+			"ipod",
+			"-c:a",
+			"aac",
+			outPath
+		]);
+		if (code !== 0) throw new Error(`ffmpeg conversion failed (exit ${code}): ${stderr}`);
+		return {
+			buffer: await readFile(outPath),
+			duration: parseDuration(stderr)
+		};
+	} finally {
+		await rm(dir, {
+			recursive: true,
+			force: true
+		}).catch(() => {});
+	}
+};
+const ensureM4a = async (buffer, mimeType) => {
+	if (isM4aMimeType(mimeType) || isM4a(buffer)) return { buffer };
+	return transcodeToM4a(buffer);
+};
+const log = createLogger$1("spectrum.stream");
+var RetryableStreamError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "RetryableStreamError";
+	}
+};
+var LiveBufferOverflowError = class extends RetryableStreamError {
+	constructor(limit) {
+		super(`Live stream buffer exceeded ${limit} events during catch-up`);
+		this.name = "LiveBufferOverflowError";
+	}
+};
+var CursorRejectedError = class extends Error {
+	constructor(cause) {
+		super("Server rejected resume cursor", { cause });
+		this.name = "CursorRejectedError";
+	}
+};
+const closeIterable = async (iterable) => {
+	if (!iterable) return;
+	await iterable.close?.();
+};
+const ignoreCleanupError = () => void 0;
+const jitterDelay = (delayMs) => delayMs * (.5 + Math.random() * .5);
+async function* throwOnCursorRejection(source, isCursorRejected) {
+	try {
+		yield* source;
+	} catch (error) {
+		throw isCursorRejected(error) ? new CursorRejectedError(error) : error;
+	}
+}
+const numericCursor = (cursor) => {
+	if (!cursor) return;
+	const value = Number(cursor);
+	return Number.isSafeInteger(value) && value >= 0 ? value : void 0;
+};
+const isCursorRegression = (next, current) => {
+	const nextValue = numericCursor(next);
+	const currentValue = numericCursor(current);
+	return nextValue !== void 0 && currentValue !== void 0 && nextValue < currentValue;
+};
+/**
+* Wraps a live event stream with cursor-based catch-up and reconnects forever
+* with capped, jittered exponential backoff — the stream never ends with an
+* error. The only terminal events are `close()` and consumer disconnect. When
+* the server rejects the resume cursor, the cursor is dropped and consumption
+* falls back to live, accepting (and logging) the event gap.
+*/
+const resumableOrderedStream = (options) => stream((emit, end) => {
+	const catchUpPageSize = options.catchUpPageSize ?? 100;
+	const bufferLimit = options.bufferLimit ?? 1e3;
+	const initialRetryDelayMs = options.initialRetryDelayMs ?? 500;
+	const maxRetryDelayMs = options.maxRetryDelayMs ?? 3e4;
+	const jitter = options.jitter ?? jitterDelay;
+	const label = options.label;
+	let activeLive;
+	let closed = false;
+	let failedAttempts = 0;
+	let lastCursor;
+	let retryDelayMs = initialRetryDelayMs;
+	let sleepTimer;
+	let wakeSleep;
+	const deliveredSinceCursor = /* @__PURE__ */ new Set();
+	const streamId = globalThis.crypto?.randomUUID?.() ?? `s_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
+	const baseStreamAttrs = (phase) => ({
+		"spectrum.stream.id": streamId,
+		"spectrum.stream.label": label,
+		"spectrum.stream.phase": phase,
+		"spectrum.stream.has_cursor": lastCursor !== void 0,
+		"spectrum.stream.cursor": lastCursor
+	});
+	const noteRecovery = () => {
+		retryDelayMs = initialRetryDelayMs;
+		if (failedAttempts === 0) return;
+		log.info("stream recovered", {
+			"spectrum.stream.id": streamId,
+			"spectrum.stream.label": label,
+			"spectrum.stream.attempt": failedAttempts
+		});
+		failedAttempts = 0;
+	};
+	const advanceCursor = (cursor, clearDelivered) => {
+		if (!cursor || cursor === lastCursor || isCursorRegression(cursor, lastCursor)) return;
+		lastCursor = cursor;
+		if (clearDelivered) deliveredSinceCursor.clear();
+	};
+	const deliverItem = async (item, resetRetry, clearOnCursorAdvance) => {
+		if (!deliveredSinceCursor.has(item.id)) for (const value of item.values) await emit(value);
+		advanceCursor(item.cursor, clearOnCursorAdvance);
+		deliveredSinceCursor.add(item.id);
+		if (resetRetry) noteRecovery();
+	};
+	const isCursorRejected = (error) => options.isCursorRejectedError?.(error) === true;
+	const sleep = async (delayMs) => {
+		if (delayMs <= 0 || closed) return;
+		await new Promise((resolve) => {
+			wakeSleep = resolve;
+			sleepTimer = setTimeout(resolve, jitter(delayMs));
+		});
+		sleepTimer = void 0;
+		wakeSleep = void 0;
+	};
+	const cancelSleep = () => {
+		if (sleepTimer) {
+			clearTimeout(sleepTimer);
+			sleepTimer = void 0;
+		}
+		wakeSleep?.();
+		wakeSleep = void 0;
+	};
+	const nextRetryDelay = () => {
+		const delay = retryDelayMs;
+		retryDelayMs = Math.min(retryDelayMs * 2, maxRetryDelayMs);
+		return delay;
+	};
+	const failureKind = (error) => {
+		if (error instanceof CursorRejectedError) return "cursor-rejected";
+		if (failedAttempts >= 5) return "persistent";
+		return "transient";
+	};
+	const handleFailure = (error, phase) => {
+		failedAttempts += 1;
+		const delayMs = nextRetryDelay();
+		const attrs = {
+			...baseStreamAttrs(phase),
+			"spectrum.stream.attempt": failedAttempts,
+			"spectrum.stream.delay_ms": delayMs,
+			"spectrum.stream.failure_kind": failureKind(error),
+			...errorAttrs(error instanceof CursorRejectedError ? error.cause : error)
+		};
+		if (error instanceof CursorRejectedError) {
+			lastCursor = void 0;
+			deliveredSinceCursor.clear();
+			log.warn("resume cursor rejected; accepting event gap and resuming live", attrs, error);
+			return delayMs;
+		}
+		if (failedAttempts >= 5) {
+			log.error("stream persistently failing; still retrying", attrs, error);
+			return delayMs;
+		}
+		log.warn("stream interrupted; reconnecting", attrs, error);
+		return delayMs;
+	};
+	const consumeLive = async () => {
+		const live = options.subscribeLive(lastCursor);
+		activeLive = live;
+		try {
+			for await (const event of live) await deliverItem(await options.processLive(event), true, true);
+			throw new RetryableStreamError("Live stream ended");
+		} finally {
+			if (activeLive === live) activeLive = void 0;
+			await closeIterable(live);
+		}
+	};
+	const throwLiveError = (liveError) => {
+		if (liveError) throw liveError;
+	};
+	const bufferLiveEvent = (buffer, event) => {
+		if (buffer.length >= bufferLimit) throw new LiveBufferOverflowError(bufferLimit);
+		buffer.push(event);
+	};
+	const startLivePump = (live, isBuffering, liveBuffer) => {
+		let liveError;
+		return {
+			getError: () => liveError,
+			pump: (async () => {
+				try {
+					for await (const event of live) {
+						if (isBuffering()) {
+							bufferLiveEvent(liveBuffer, event);
+							continue;
+						}
+						await deliverItem(await options.processLive(event), true, true);
+					}
+					throw new RetryableStreamError("Live stream ended");
+				} catch (error) {
+					liveError = error;
+				}
+			})()
+		};
+	};
+	const replayMissed = async (cursor, getLiveError) => {
+		const missed = throwOnCursorRejection(options.fetchMissed(cursor, { limit: catchUpPageSize }), isCursorRejected);
+		for await (const event of missed) {
+			throwLiveError(getLiveError());
+			await deliverItem(await options.processMissed(event), false, false);
+		}
+		throwLiveError(getLiveError());
+	};
+	const flushLiveBuffer = async (liveBuffer, getLiveError, stopBuffering) => {
+		let index = 0;
+		let lastFlushedId;
+		while (index < liveBuffer.length) {
+			throwLiveError(getLiveError());
+			const event = liveBuffer[index];
+			if (event === void 0) throw new RetryableStreamError("Live stream buffer index missing");
+			const item = await options.processLive(event);
+			await deliverItem(item, true, false);
+			lastFlushedId = item.id;
+			index += 1;
+		}
+		liveBuffer.length = 0;
+		throwLiveError(getLiveError());
+		compactDeliveredIds(lastFlushedId);
+		stopBuffering();
+	};
+	const compactDeliveredIds = (lastId) => {
+		if (!lastId) return;
+		deliveredSinceCursor.clear();
+		deliveredSinceCursor.add(lastId);
+	};
+	const catchUpThenConsumeLive = async (cursor) => {
+		const live = options.subscribeLive(cursor);
+		activeLive = live;
+		let buffering = true;
+		const liveBuffer = [];
+		const livePump = startLivePump(live, () => buffering, liveBuffer);
+		try {
+			await replayMissed(cursor, livePump.getError);
+			await flushLiveBuffer(liveBuffer, livePump.getError, () => {
+				buffering = false;
+			});
+			noteRecovery();
+			await livePump.pump;
+			throwLiveError(livePump.getError());
+		} finally {
+			buffering = false;
+			if (activeLive === live) activeLive = void 0;
+			await closeIterable(live);
+			await livePump.pump.catch(ignoreCleanupError);
+		}
+	};
+	const run = async () => {
+		while (!closed) {
+			const phase = lastCursor ? "catch-up" : "live";
+			try {
+				if (lastCursor) await catchUpThenConsumeLive(lastCursor);
+				else await consumeLive();
+			} catch (error) {
+				await closeIterable(activeLive).catch(ignoreCleanupError);
+				activeLive = void 0;
+				if (closed) break;
+				await sleep(handleFailure(error, phase));
+			}
+		}
+		end();
+	};
+	const pump = run().catch((error) => {
+		log.error("resumable stream loop crashed", {
+			"spectrum.stream.id": streamId,
+			"spectrum.stream.label": label
+		}, error);
+		if (!closed) end(error);
+	});
+	return async () => {
+		closed = true;
+		cancelSleep();
+		await closeIterable(activeLive);
+		await pump.catch(ignoreCleanupError);
+	};
+});
+//#endregion
+export { asAttachment, asContact, asCustom, asGroup, asMarkdown, asPoll, asPollOption, asReaction, asRead, asRichlink, asText, asVoice, buildPhotoAction, createLogger, ensureM4a, errorAttrs, groupSchema, messageEffectSchema, photoActionSchema, reactionSchema, renderInlineTokens, resumableOrderedStream, sanitizeEmail, sanitizeErrorMessage, sanitizePhone, setLogLevel };

package/dist/elysia.d.ts

@@ -0,0 +1,92 @@
+import { T as WebhookHandler, nn as Message, rn as Space } from "./attachment-a_lrhg6w.js";
+import { Elysia } from "elysia";
+
+//#region src/elysia.d.ts
+/**
+ * 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: {};
+}>;
+//#endregion
+export { type Message, type Space, SpectrumPluginOptions, type WebhookHandler, spectrum };

package/dist/elysia.js

@@ -0,0 +1,32 @@
+import { Elysia } from "elysia";
+//#region src/elysia.ts
+/**
+* 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);
+* ```
+*/
+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" });
+}
+//#endregion
+export { spectrum };

package/dist/express.d.ts

@@ -0,0 +1,60 @@
+import { T as WebhookHandler, nn as Message, rn as Space } from "./attachment-a_lrhg6w.js";
+import { Router } from "express";
+
+//#region src/express.d.ts
+/**
+ * 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;
+//#endregion
+export { type Message, type Space, SpectrumPluginOptions, type WebhookHandler, spectrum };