@spectrum-ts/fastify 8.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License Copyright (c) 2025 Photon AI
+
+Permission is hereby granted,
+free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice
+(including the next paragraph) shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# @spectrum-ts/fastify
+
+[Fastify](https://fastify.dev) webhook adapter for [spectrum-ts](https://github.com/photon-hq/spectrum-ts).
+
+## Install
+
+```sh
+bun add spectrum-ts @spectrum-ts/fastify fastify
+```
+
+## Use
+
+```ts
+import { Spectrum } from "spectrum-ts";
+import { spectrum } from "@spectrum-ts/fastify";
+import Fastify from "fastify";
+
+const app = await Spectrum({
+  webhookSecret: process.env.SPECTRUM_WEBHOOK_SECRET,
+});
+
+const server = Fastify();
+// The plugin owns its own raw-body parser in an encapsulated scope.
+server.register(spectrum, {
+  app,
+  onMessage: async (space, message) => {
+    if (message.content.type === "text") {
+      await space.send(`echo: ${message.content.text}`);
+    }
+  },
+});
+// Await listen so a startup failure surfaces instead of going unhandled.
+await server.listen({ port: 3000 });
+```
+
+See the [spectrum-ts documentation](https://photon.codes/spectrum) for the full guide.

package/dist/index.d.ts

@@ -0,0 +1,60 @@
+import { Message, Space, WebhookHandler, WebhookHandler as WebhookHandler$1 } from "@spectrum-ts/core";
+import { FastifyInstance } from "fastify";
+
+//#region src/index.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$1): 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$1;
+  /**
+   * Route the webhook is mounted on.
+   *
+   * @default "/spectrum/webhook"
+   */
+  path?: string;
+}
+/**
+ * Mount a Spectrum webhook endpoint on a Fastify app.
+ *
+ * @example
+ * ```ts
+ * import Fastify from "fastify";
+ * import { Spectrum } from "spectrum-ts";
+ * import { spectrum } from "@spectrum-ts/fastify";
+ *
+ * const app = await Spectrum({ ...,  webhookSecret: process.env.SPECTRUM_WEBHOOK_SECRET });
+ *
+ * const server = Fastify();
+ * server.register(spectrum, {
+ *   app,
+ *   onMessage: async (space, message) => {
+ *     if (message.content.type === "text") await space.send(`echo: ${message.content.text}`);
+ *   },
+ * });
+ * server.listen({ port: 3000 });
+ * ```
+ */
+declare function spectrum(fastify: FastifyInstance, options: SpectrumPluginOptions): Promise<void>;
+//#endregion
+export { type Message, type Space, SpectrumPluginOptions, type WebhookHandler, spectrum };

package/dist/index.js

@@ -0,0 +1,55 @@
+//#region src/index.ts
+/**
+* Mount a Spectrum webhook endpoint on a Fastify app.
+*
+* @example
+* ```ts
+* import Fastify from "fastify";
+* import { Spectrum } from "spectrum-ts";
+* import { spectrum } from "@spectrum-ts/fastify";
+*
+* const app = await Spectrum({ ...,  webhookSecret: process.env.SPECTRUM_WEBHOOK_SECRET });
+*
+* const server = Fastify();
+* server.register(spectrum, {
+*   app,
+*   onMessage: async (space, message) => {
+*     if (message.content.type === "text") await space.send(`echo: ${message.content.text}`);
+*   },
+* });
+* server.listen({ port: 3000 });
+* ```
+*/
+async function spectrum(fastify, options) {
+	const { app, onMessage, path = "/spectrum/webhook" } = options;
+	fastify.removeAllContentTypeParsers();
+	fastify.addContentTypeParser("*", (_request, payload, done) => {
+		const chunks = [];
+		payload.on("data", (chunk) => {
+			chunks.push(chunk);
+		});
+		payload.on("end", () => {
+			done(null, Buffer.concat(chunks));
+		});
+		payload.on("error", (err) => {
+			done(err);
+		});
+	});
+	fastify.post(path, async (request, reply) => {
+		const result = await app.webhook({
+			body: request.body,
+			headers: normalizeHeaders(request.headers)
+		}, onMessage);
+		return reply.status(result.status).headers(result.headers).send(Buffer.from(result.body));
+	});
+}
+function normalizeHeaders(headers) {
+	const normalized = {};
+	for (const [key, value] of Object.entries(headers)) {
+		if (value === void 0) continue;
+		normalized[key] = Array.isArray(value) ? value[0] ?? "" : value;
+	}
+	return normalized;
+}
+//#endregion
+export { spectrum };

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@spectrum-ts/fastify",
+  "version": "8.0.0",
+  "description": "Fastify webhook adapter for spectrum-ts.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/photon-hq/spectrum-ts.git",
+    "directory": "packages/fastify"
+  },
+  "homepage": "https://photon.codes/spectrum",
+  "bugs": {
+    "url": "https://github.com/photon-hq/spectrum-ts/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@spectrum-ts/core": "^8.0.0",
+    "fastify": "^4 || ^5",
+    "typescript": "^5 || ^6.0.0"
+  },
+  "license": "MIT"
+}