feat: Telegram provider (direct Bot API)

.gitignore

@@ -43,3 +43,9 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 
 # Finder (MacOS) folder config
 .DS_Store
+
+# test results
+test-results/
+
+# local backup of full telegram provider (pre-strip)
+telegram-full-backup/

README.md

@@ -53,6 +53,7 @@ Visit **[docs.photon.codes](https://docs.photon.codes)** to view the full docume
 | Platform | Package |
 |----------|---------|
 | iMessage | `spectrum-ts/providers/imessage` |
+| Telegram | `spectrum-ts/providers/telegram` |
 | WhatsApp | `spectrum-ts/providers/whatsapp` |
 | Terminal | `spectrum-ts/providers/terminal` |
 | Custom   | `definePlatform` from `spectrum-ts` |

package.json

@@ -11,7 +11,8 @@
     "build": "turbo build",
     "dev": "turbo dev",
     "check": "ultracite check",
-    "fix": "ultracite fix"
+    "fix": "ultracite fix",
+    "gen:telegram": "bun run packages/spectrum-ts/src/providers/telegram/bot-api-spec/generators/typescript.ts"
   },
   "workspaces": [
     "packages/*",

packages/spectrum-ts/package.json

@@ -44,7 +44,8 @@
   "scripts": {
     "build": "tsup && cp ../../README.md ../../LICENSE .",
     "dev": "tsup --watch",
-    "generate:emoji": "bun scripts/generate-emoji.ts"
+    "generate:emoji": "bun scripts/generate-emoji.ts",
+    "gen:telegram": "bun src/providers/telegram/bot-api-spec/generators/typescript.ts"
   },
   "dependencies": {
     "@photon-ai/advanced-imessage": "^0.7.0",
@@ -54,6 +55,7 @@
     "better-grpc": "^0.3.2",
     "mime-types": "^3.0.1",
     "open-graph-scraper": "^6.11.0",
+    "quick-lru": "^7.3.0",
     "type-fest": "^5.4.1",
     "vcf": "^2.1.2",
     "zod": "^4.2.1"

packages/spectrum-ts/src/providers/telegram/bot-api-spec/README.md

@@ -0,0 +1,98 @@
+# Telegram Bot API Spec
+
+JSON schema of the Telegram Bot API subset used by the Telegram provider, plus the generator that emits `providers/telegram/generated/*.ts`.
+
+## Layout
+
+```text
+packages/spectrum-ts/src/providers/telegram/bot-api-spec/
+├── schema/
+│   └── telegram.json
+├── generators/
+│   └── typescript.ts
+└── README.md
+```
+
+## Scope
+
+The schema covers the Bot API surface that maps onto Spectrum's `Platform`:
+
+- `send` — `text`, `richlink`, `attachment`, `voice`, `contact`, `poll`, `reply`, `edit`, `reaction`, `typing`, `group`
+- `messages` — long-polling stream of inbound `Update`s
+- Lifecycle: `getMe`, `getChat`, `getFile`
+
+Notes on a few non-obvious mappings:
+
+- `typing` with `state: "stop"` is a no-op. `sendChatAction` is one-shot and the indicator auto-expires after ~5s; there's no cancel endpoint.
+- `Update.poll_answer` is diffed against the bot's prior cached vote vector and emitted as per-option `poll_option` events. `sendPoll` always pins `is_anonymous: false` to enable this. `Update.poll` aggregate state is unmapped.
+- Outbound `richlink` drops `title` / `summary` / `cover` — Telegram's preview scraper owns that metadata; the Bot API exposes only layout knobs.
+
+### Provider-local cache
+
+Bridges the gaps in the Bot API (no fetch-by-id, no album update kind, no chat on `poll_answer`):
+
+- **Messages cache** — bounded LRU written by every inbound `Update.message` and outbound send. `space.getMessage(id)` reads from it. Reaction events also use it to hydrate `reaction.target`.
+- **Poll cache** — maps `poll_id` to the original Spectrum poll + chat snapshot, plus per-voter vote vectors for diffing.
+- **Album buffer** — with `coalesceAlbums: true`, debounces members sharing `media_group_id` into a single `group`; off by default.
+
+In-process, capacity-bounded, no TTL, torn down with the runtime. Defaults: 5000 messages, 500 polls, 5000 vote vectors, 100 concurrent albums, 500ms debounce, 2s ceiling. Set any capacity to `0` to disable that slot.
+
+Inline queries, callback queries, payments, passports, forum topics, and admin operations are out of scope; surface them via custom events if needed.
+
+## Schema format
+
+TypeRef DSL:
+
+- Primitives: `string`, `integer`, `float`, `boolean`, `any`
+- Reference: `Ref:<TypeName>`
+- Composition: `Array:<Inner>`, `Union:<A>|<B>|...`
+
+`InputFile` is a marker; the generator emits `string | Blob`.
+
+### Type
+
+```json
+"Message": {
+  "description": "A message.",
+  "fields": [
+    { "name": "message_id", "type": "integer", "required": true },
+    { "name": "text", "type": "string", "required": false },
+    { "name": "chat", "type": "Ref:Chat", "required": true }
+  ]
+}
+```
+
+Field options: `required`, `description`, `enum`, `const`.
+
+### Method
+
+```json
+"sendMessage": {
+  "description": "Sends a text message.",
+  "httpMethod": "POST",
+  "params": [
+    { "name": "chat_id", "type": "Union:integer|string", "required": true },
+    { "name": "text", "type": "string", "required": true }
+  ],
+  "returns": "Ref:Message"
+}
+```
+
+## Regeneration
+
+```bash
+bun run gen:telegram
+```
+
+Rewrites `providers/telegram/generated/*.ts`. Generated files are committed; CI runs `git diff --exit-code` after regen.
+
+## Adding a method
+
+1. Add any new type under `types`.
+2. Add the method under `methods` with params and return type.
+3. `bun run gen:telegram`.
+4. Commit schema + generated output together.
+
+## Version
+
+Tracking **Bot API 9.6** (April 3, 2026).