docs: update spectrum-ts documentation for v2.0.0 (#82)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: photon-action-bot[bot]

docs-src/spectrum-ts/content.mdx.vel

@@ -8,7 +8,7 @@ import { TypeTooltip } from "/snippets/type-tooltip.mdx";
 {% set ci = symbol("ts:spectrum-ts#ContentInput") %}
 {% set cb = symbol("ts:spectrum-ts#ContentBuilder") %}
 
-Spectrum exposes a family of content builders — `text`, `attachment`, `voice`, `contact`, `richlink`, `poll`, `group`, `custom`, `reaction`, `reply`, `edit`, `typing`, `rename`, and `avatar` — plus a string shortcut that's equivalent to `text()`. Any API that takes a <TypeTooltip name="ContentInput" type={`{{ ci.signature }}`} /> accepts a plain string or a <TypeTooltip name="ContentBuilder" type={`{{ cb.signature }}`} />.
+Spectrum exposes a family of content builders — `text`, `streamText`, `attachment`, `voice`, `contact`, `richlink`, `poll`, `group`, `custom`, `reaction`, `reply`, `edit`, `typing`, `rename`, and `avatar` — plus a string shortcut that's equivalent to `text()`. Any API that takes a <TypeTooltip name="ContentInput" type={`{{ ci.signature }}`} /> accepts a plain string or a <TypeTooltip name="ContentBuilder" type={`{{ cb.signature }}`} />.
 
 ## Text
 
@@ -21,6 +21,53 @@ await space.send(text("Hello, world."));
 await space.send("Hello, world.");
 ```
 
+## Streaming text
+
+Send streaming LLM output as Spectrum content. The `streamText` builder wraps an async stream of text deltas so it can be sent like any other content item. On platforms that support it (iMessage in remote mode), the first chunk is sent immediately as a real message and then edited in place as more text arrives.
+
+```ts
+import { streamText } from "spectrum-ts";
+```
+
+`streamText` accepts whatever the popular LLM SDKs return — the Vercel AI SDK `streamText()` result, a raw `AsyncIterable` of chunks, or a `ReadableStream`:
+
+<Tabs>
+  <Tab title="Vercel AI SDK">
+    ```ts
+    import { streamText } from "spectrum-ts";
+    import { streamText as aiStreamText } from "ai";
+
+    const result = aiStreamText({ model, prompt: message.content.text });
+    await space.send(streamText(result));
+    ```
+  </Tab>
+  <Tab title="AsyncIterable">
+    ```ts
+    import { streamText } from "spectrum-ts";
+
+    async function* generate() {
+      yield "Hello, ";
+      yield "world!";
+    }
+
+    await space.send(streamText(generate()));
+    ```
+  </Tab>
+  <Tab title="Custom extractor">
+    ```ts
+    import { streamText } from "spectrum-ts";
+
+    await space.send(
+      streamText(customStream, {
+        extract: (chunk) => chunk.delta?.text ?? null,
+      }),
+    );
+    ```
+  </Tab>
+</Tabs>
+
+Platforms that cannot stream silently skip the send with a warning.
+
 ## Attachments
 
 Pass a file path or a `Buffer`. MIME types are detected from the file extension; override with `options.mimeType` when you already have the bytes.

docs-src/spectrum-ts/custom-events-and-lifecycle.mdx.vel

@@ -34,6 +34,18 @@ for await (const event of im.typing) {
 
 Use the flat form on `app` when you want a merged feed across platforms; use the narrowed form when you only care about one.
 
+### Fusor custom events
+
+Fusor-backed providers can emit non-message events (presence, read receipts, delivery status) into typed event streams using `fusorEvent`. Inside a Fusor `messages` handler, yield a `fusorEvent(name, data)` alongside regular messages to push events into `app.<name>` streams:
+
+```ts
+import { fusorEvent } from "spectrum-ts";
+
+yield fusorEvent("presence", { userId: update.userId, online: true });
+```
+
+Events emitted this way are available as `app.presence` (merged across providers) or `narrowedInstance.presence` (scoped to the emitting provider). The event name and data shape are fully typed based on the provider's event declarations.
+
 ## Lifecycle
 
 ### Graceful shutdown

docs-src/spectrum-ts/custom-platforms.mdx.vel

@@ -175,6 +175,54 @@ const msg = await mine.getMessage(space, "msg-123");
 const thread = await mine.lookupThread("thread-456");
 ```
 
+## Fusor-backed providers
+
+When your platform receives inbound messages through webhooks (rather than a persistent connection), use `fusor(...)` as the client in `lifecycle.createClient`. A Fusor client handles webhook signature verification and delivers parsed payloads to your `messages` handler:
+
+```ts
+import { definePlatform, fusor, fusorEvent } from "spectrum-ts";
+import z from "zod";
+
+export const myWebhookPlatform = definePlatform("my-webhook-platform", {
+  config: z.object({
+    webhookSecret: z.string(),
+  }),
+
+  lifecycle: {
+    createClient: async ({ config }) =>
+      fusor("my-webhook-platform", (req) => {
+        verifySignature(req.rawBody, req.headers, config.webhookSecret);
+        return JSON.parse(new TextDecoder().decode(req.rawBody));
+      }),
+  },
+
+  messages: async function* ({ payload, config, respond }) {
+    respond({ status: 200 });
+    yield {
+      id: payload.id,
+      content: { type: "text", text: payload.text },
+      sender: { id: payload.userId },
+      space: { id: payload.chatId },
+      timestamp: new Date(payload.ts),
+    };
+  },
+
+  send: async ({ space, content, config }) => {
+    // dispatch outbound messages
+  },
+
+  user: {
+    resolve: async ({ input }) => ({ id: input.userID }),
+  },
+
+  space: {
+    resolve: async ({ input }) => ({ id: input.users[0].id }),
+  },
+});
+```
+
+The Fusor overload of `definePlatform` replaces the top-level `messages` async generator with a per-webhook-delivery handler that receives `{ payload, config, respond }`. Call `respond()` to set the HTTP response sent back to the webhook caller.
+
 ## Registering your platform
 
 Exported platforms work like the built-ins — register with `.config()` and use narrowing for the typed surface:

docs-src/spectrum-ts/introduction.mdx.vel

@@ -23,19 +23,22 @@ A user might message you in iMessage today, WhatsApp tomorrow, and your app next
 
 With Spectrum, you run one agent server and add providers for the interfaces you want to support. Each provider connects a native interface to the same Spectrum API, so your agent can feel consistent everywhere.
 
-Today, Spectrum supports iMessage, WhatsApp Business, and terminal development. The same model is built for more interfaces over time: Slack, Discord, websites, apps, phone calls, meetings, and hardware like HomePod.
+Today, Spectrum supports iMessage, WhatsApp Business, Telegram, and terminal development. The same model is built for more interfaces over time: Slack, Discord, websites, apps, phone calls, meetings, and hardware like HomePod.
 
 ## Supported interfaces today
 
 Spectrum currently includes official providers for:
 
-<CardGroup cols={3}>
+<CardGroup cols={2}>
   <Card title="iMessage" icon="comment" href="/spectrum-ts/providers/imessage">
     Run production iMessage agents through managed iMessage lines.
   </Card>
   <Card title="WhatsApp Business" icon="whatsapp" href="/spectrum-ts/providers/whatsapp-business">
     Connect to the official WhatsApp Business Cloud API.
   </Card>
+  <Card title="Telegram" icon="paper-plane" href="/spectrum-ts/providers/telegram">
+    Build bots on the Telegram Bot API with inbound webhooks through Fusor.
+  </Card>
   <Card title="Terminal" icon="terminal" href="/spectrum-ts/providers/terminal">
     Build, test, and demo agents from your local terminal.
   </Card>

docs-src/spectrum-ts/messages.mdx.vel

@@ -126,6 +126,7 @@ for await (const [space, message] of app.messages) {
   | `"reply"` | `content: Content`, `target: Message` — threaded reply wrapping inner content |
   | `"edit"` | `content: Content`, `target: Message` — rewrite of a previously-sent message |
   | `"typing"` | `state: "start" \| "stop"` — typing indicator signal |
+  | `"streamText"` | `stream: () => AsyncIterable<string>` — streaming text content |
   | `"custom"` | `raw: unknown` — platform-specific structured data |
 </Accordion>
 

docs-src/spectrum-ts/platform-narrowing.mdx.vel

@@ -7,7 +7,7 @@ import { TypeTooltip } from "/snippets/type-tooltip.mdx";
 
 {% set pi = symbol("ts:spectrum-ts#PlatformInstance") %}
 
-Every platform provider exports a callable — `imessage`, `terminal`, `whatsappBusiness` — that **narrows** generic Spectrum types into platform-specific ones. The same function handles three different inputs.
+Every platform provider exports a callable — `imessage`, `terminal`, `whatsappBusiness`, `telegram` — that **narrows** generic Spectrum types into platform-specific ones. The same function handles three different inputs.
 
 ## Narrowing the app
 
@@ -41,7 +41,7 @@ for await (const [space, message] of app.messages) {
 }
 ```
 
-Narrowing a space from the wrong platform throws at runtime. Always gate on `message.platform` (or a similar signal) first.
+Narrowing a space from the wrong platform logs a structured warning at runtime. Always gate on `message.platform` (or a similar signal) first to avoid unexpected behavior.
 
 ## Narrowing a message
 

docs-src/spectrum-ts/providers.mdx.vel

@@ -17,6 +17,9 @@ Providers plug into Spectrum's type system and runtime. Each one exports a calla
   <Card title="WhatsApp Business" icon="whatsapp" href="/spectrum-ts/providers/whatsapp-business">
     Official WhatsApp Business Cloud API. Native reactions and replies, 1:1 conversations only.
   </Card>
+  <Card title="Telegram" icon="paper-plane" href="/spectrum-ts/providers/telegram">
+    Telegram Bot API with Fusor webhooks. Text, media, reactions, replies, typing, and edits.
+  </Card>
 </CardGroup>
 
 ## Combining providers

docs-src/spectrum-ts/providers/telegram.mdx.vel

@@ -0,0 +1,74 @@
+---
+title: "Telegram"
+description: "Send and receive messages through the Telegram Bot API"
+---
+
+```ts
+import { telegram } from "spectrum-ts/providers/telegram";
+```
+
+The Telegram provider connects your agent to the Telegram Bot API. Inbound messages are delivered through Fusor webhooks; outbound messages use the Bot API directly. The provider supports text, media, reactions, replies, typing indicators, edits, and lazy media downloads.
+
+## Config
+
+```ts
+telegram.config({
+  botToken: "your-bot-token",
+});
+```
+
+| Option | Description |
+|---|---|
+| `botToken` | Bot token from [@BotFather](https://t.me/BotFather). |
+| `webhookSecret` | Optional secret token for verifying webhook payloads. |
+
+## Example
+
+```ts
+import { Spectrum } from "spectrum-ts";
+import { telegram } from "spectrum-ts/providers/telegram";
+
+const app = await Spectrum({
+  projectId: process.env.PROJECT_ID!,
+  projectSecret: process.env.PROJECT_SECRET!,
+  providers: [
+    telegram.config({
+      botToken: process.env.TELEGRAM_BOT_TOKEN!,
+    }),
+  ],
+});
+
+for await (const [space, message] of app.messages) {
+  if (message.content.type === "text") {
+    await space.send(`Echo: ${message.content.text}`);
+  }
+}
+```
+
+## Starting a conversation
+
+Resolve a user by their Telegram user ID and open a space. You can also pass a `chatId` parameter to target a specific Telegram chat:
+
+```ts
+const tg = telegram(app);
+const user = await tg.user("123456789");
+const space = await tg.space(user);
+
+await space.send("Hello from Spectrum.");
+```
+
+## Webhook registration
+
+In cloud mode (when `projectId` and `projectSecret` are provided), the Telegram provider automatically registers its Fusor webhook on startup. In local or direct mode, you need to configure the webhook yourself through the Telegram Bot API.
+
+## Supported features
+
+| Feature | Support |
+|---|---|
+| Text messages | Send and receive |
+| Media (photos, documents, audio, video) | Send and receive |
+| Reactions | Send and receive |
+| Threaded replies | Send and receive |
+| Typing indicators | Send |
+| Message edits | Send and receive |
+| Custom Bot API calls | Via platform-specific actions |

docs.json

@@ -41,7 +41,8 @@
                   "spectrum-ts/providers",
                   "spectrum-ts/providers/imessage",
                   "spectrum-ts/providers/terminal",
-                  "spectrum-ts/providers/whatsapp-business"
+                  "spectrum-ts/providers/whatsapp-business",
+                  "spectrum-ts/providers/telegram"
                 ]
               },
               {

package.json

@@ -28,7 +28,7 @@
     "eslint-plugin-format": "^2.0.1",
     "husky": "^9.1.7",
     "oxfmt": "^0.44.0",
-    "spectrum-ts": "1.18.0",
+    "spectrum-ts": "2.0.0",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   }