spectrum-ts 4.2.0 → 5.0.0

package/README.md

@@ -1,80 +1,42 @@
-<div align="center">
-  <h1>Spectrum</h1>
-  <p><strong>Bring agents to any interface.</strong></p>
-  
-  Photon (photon.codes) builds Spectrum, a multi-channel agent framework that makes AI agents reachable over real conversation surfaces like iMessage, SMS, and email instead of trapping them in web chat.
-  
-  <p>
-    <a href="https://www.npmjs.com/package/spectrum-ts"><img src="https://img.shields.io/npm/v/spectrum-ts.svg?style=flat&colorA=1a1a1a&colorB=3178c6" alt="npm version" /></a>
-    <a href="https://www.npmjs.com/package/spectrum-ts"><img src="https://img.shields.io/npm/dm/spectrum-ts.svg?style=flat&colorA=1a1a1a&colorB=3178c6" alt="npm downloads" /></a>
-    <a href="https://github.com/photon-hq/spectrum-ts/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/spectrum-ts.svg?style=flat&colorA=1a1a1a&colorB=3178c6" alt="license" /></a>
-    <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5+-3178c6?style=flat&colorA=1a1a1a&colorB=3178c6" alt="TypeScript" /></a>
-    <a href="https://github.com/photon-hq/spectrum-ts/stargazers"><img src="https://img.shields.io/github/stars/photon-hq/spectrum-ts.svg?style=flat&colorA=1a1a1a&colorB=3178c6" alt="github stars" /></a>
-  </p>
-</div>
+# spectrum-ts
 
-## About Photon
+Bring agents to any interface — a unified messaging SDK for TypeScript.
 
-**[Photon](https://photon.codes)** builds infrastructure for AI agents that operate over real communication channels.
+`spectrum-ts` is the **batteries-included** package: it bundles the runtime
+([`@spectrum-ts/core`](https://npmjs.com/package/@spectrum-ts/core)) plus
+every official provider, so one install gets you everything.
 
-Spectrum is Photon’s open-source multi-channel agent framework, enabling AI agents to communicate through interfaces people already use—such as iMessage, SMS, email, Slack, Discord, and voice—instead of being confined to web chat.
+```sh
+bun add spectrum-ts
+```
 
-Learn more at **https://photon.codes**.
+```ts
+import { Spectrum } from "spectrum-ts";
+import { telegram } from "spectrum-ts/providers/telegram";
 
-## Getting Started
+const app = await Spectrum({ providers: [telegram.config({ botToken: "…" })] });
+```
 
-The fastest way to ship is with **Spectrum Cloud** — hosted infrastructure for platforms like iMessage, with credentials ready in minutes.
+## Lean installs
 
-1. Sign up at **[app.photon.codes](https://app.photon.codes)** to get your project ID and secret.
-2. Install the SDK:
+If you only use a couple of platforms and want a smaller install, depend on the
+runtime and just the providers you need instead of this metapackage:
 
-   ```bash
-   bun add spectrum-ts
-   ```
+```sh
+bun add @spectrum-ts/core @spectrum-ts/telegram
+```
 
-3. Start your app:
-
-   ```typescript
-   import { Spectrum } from "spectrum-ts";
-   import { imessage } from "spectrum-ts/providers/imessage";
-
-   const app = await Spectrum({
-     projectId: process.env.PROJECT_ID,
-     projectSecret: process.env.PROJECT_SECRET,
-     providers: [imessage.config()],
-   });
-
-   for await (const [space, message] of app.messages) {
-     await space.responding(async () => {
-       await message.reply("Hello from Spectrum.");
-     });
-   }
-   ```
-
-Spectrum also runs fully standalone — you can connect to a local iMessage database, bring your own gRPC endpoints, or build your own platform provider. See the [docs](https://docs.photon.codes) for self-hosted setups.
-
-## Documentation
-
-Visit **[docs.photon.codes](https://docs.photon.codes)** to view the full documentation.
-
-## Platforms
+```ts
+import { Spectrum } from "@spectrum-ts/core";
+import { telegram } from "@spectrum-ts/telegram";
+```
 
 | Platform | Package |
 |----------|---------|
-| iMessage | `spectrum-ts/providers/imessage` |
-| WhatsApp | `spectrum-ts/providers/whatsapp` |
-| Telegram | `spectrum-ts/providers/telegram` |
-| Terminal | `spectrum-ts/providers/terminal` |
-| Custom   | `definePlatform` from `spectrum-ts` |
-
-## Issues
-
-Found a bug or have a feature request? Please [open an issue](https://github.com/photon-hq/spectrum-ts/issues) on GitHub. Before filing, search existing issues to avoid duplicates.
-
-## Contributing
-
-Contributions are welcome. Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
-
-## License
+| iMessage | [`@spectrum-ts/imessage`](https://npmjs.com/package/@spectrum-ts/imessage) |
+| Telegram | [`@spectrum-ts/telegram`](https://npmjs.com/package/@spectrum-ts/telegram) |
+| Slack | [`@spectrum-ts/slack`](https://npmjs.com/package/@spectrum-ts/slack) |
+| WhatsApp Business | [`@spectrum-ts/whatsapp-business`](https://npmjs.com/package/@spectrum-ts/whatsapp-business) |
+| Terminal | [`@spectrum-ts/terminal`](https://npmjs.com/package/@spectrum-ts/terminal) |
 
-[MIT](./LICENSE) © [Photon](https://photon.codes)
+See the [documentation](https://photon.codes/spectrum) for the full guide.

package/dist/authoring.d.ts

@@ -1,6 +1 @@
-export { c as asAttachment } from './attachment-CnivEhr6.js';
-export { q as asContact, s as asCustom, u as asGroup, w as asPoll, x as asPollOption, y as asRichlink, z as asText, A as asVoice } from './authoring-b9AhXgPI.js';
-export { e as ProviderMessageRecord, $ as asReaction } from './types-CyfLJXgu.js';
-import 'zod';
-import 'vcf';
-import 'hotscript';
+export * from "@spectrum-ts/core/authoring";

package/dist/authoring.js

@@ -1,36 +1,2 @@
-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 {
-  asPoll,
-  asPollOption
-} from "./chunk-2D27WW5B.js";
-import {
-  asContact
-} from "./chunk-A37PM5N2.js";
-import "./chunk-6UZFVXQF.js";
-import {
-  asAttachment,
-  asCustom,
-  asReaction,
-  asText
-} from "./chunk-UXAKIXVM.js";
-export {
-  asAttachment,
-  asContact,
-  asCustom,
-  asGroup,
-  asPoll,
-  asPollOption,
-  asReaction,
-  asRichlink,
-  asText,
-  asVoice
-};
+export * from "@spectrum-ts/core/authoring";
+export {};

package/dist/elysia.d.ts

@@ -1,94 +1 @@
-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 };
+export * from "@spectrum-ts/core/elysia";

package/dist/elysia.js

@@ -1,15 +1,2 @@
-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
-};
+export * from "@spectrum-ts/core/elysia";
+export {};

package/dist/express.d.ts

@@ -1,62 +1 @@
-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 };
+export * from "@spectrum-ts/core/express";

package/dist/express.js

@@ -1,19 +1,2 @@
-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
-};
+export * from "@spectrum-ts/core/express";
+export {};

package/dist/hono.d.ts

@@ -1,64 +1 @@
-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 };
+export * from "@spectrum-ts/core/hono";

package/dist/hono.js

@@ -1,11 +1,2 @@
-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
-};
+export * from "@spectrum-ts/core/hono";
+export {};