@photon-ai/chat-adapter-imessage 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Photon
+
+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 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,358 @@
+# @photon-ai/chat-adapter-imessage
+
+iMessage community adapter for [Chat SDK](https://chat-sdk.dev/docs). Built on [spectrum-ts](https://github.com/photon-hq/spectrum-ts), Photon's unified messaging SDK. Supports **cloud** ([Spectrum Cloud](https://app.photon.codes)), **self-hosted**, and **local** (on-device, macOS) iMessage.
+
+## Installation
+
+```bash
+pnpm add chat @photon-ai/chat-adapter-imessage
+```
+
+## Usage
+
+The adapter has three modes:
+
+- **Cloud** (recommended) — connects to [Spectrum Cloud](https://app.photon.codes) with a project ID + secret. Runs anywhere.
+- **Self-hosted** — connects to your own `@photon-ai/advanced-imessage` gRPC endpoint.
+- **Local** — runs directly on a Mac, reading the local iMessage database. macOS only.
+
+The mode is auto-detected from environment variables (see [Configuration](#configuration)).
+
+### Cloud mode
+
+```typescript
+import { Chat } from "chat";
+import { createiMessageAdapter } from "@photon-ai/chat-adapter-imessage";
+
+const bot = new Chat({
+  userName: "mybot",
+  adapters: {
+    imessage: createiMessageAdapter({
+      local: false,
+      projectId: process.env.IMESSAGE_PROJECT_ID,
+      projectSecret: process.env.IMESSAGE_PROJECT_SECRET,
+    }),
+  },
+});
+
+bot.onNewMention(async (thread, message) => {
+  await thread.post("Hello from iMessage!");
+});
+```
+
+### Local mode
+
+For development or self-hosted deployments on a Mac. Reads from the local iMessage database and sends via the on-device APIs. Must run on macOS with **Full Disk Access** granted.
+
+```typescript
+import { Chat } from "chat";
+import { createiMessageAdapter } from "@photon-ai/chat-adapter-imessage";
+
+const bot = new Chat({
+  userName: "mybot",
+  adapters: {
+    imessage: createiMessageAdapter({ local: true }),
+  },
+});
+
+bot.onNewMention(async (thread, message) => {
+  await thread.post("Hello from iMessage!");
+});
+```
+
+## Setup
+
+### Cloud mode
+
+1. Sign up at [app.photon.codes](https://app.photon.codes) to get your **project ID** and **project secret**.
+2. Set `IMESSAGE_PROJECT_ID` and `IMESSAGE_PROJECT_SECRET`.
+3. Set `IMESSAGE_LOCAL=false`.
+
+### Self-hosted mode
+
+Point the adapter at your own `@photon-ai/advanced-imessage` gRPC server.
+
+1. Set `IMESSAGE_SERVER_URL` to the server's gRPC address as `host:port` (e.g. `imessage.example.com:443`).
+2. Set `IMESSAGE_API_KEY` to the server's auth token.
+3. Set `IMESSAGE_LOCAL=false`.
+
+> ⚠️ **Transport change.** Previous versions of this adapter spoke HTTP/Socket.IO. It now uses gRPC via spectrum-ts, so `IMESSAGE_SERVER_URL` must be a gRPC `host:port`, **not** an `https://` URL. A bare host gets `:443` appended; any URL scheme is stripped.
+
+For advanced multi-number setups, pass explicit `clients` instead:
+
+```typescript
+createiMessageAdapter({
+  local: false,
+  clients: [
+    { address: "imessage.example.com:443", token: "…", phone: "+1234567890" },
+  ],
+});
+```
+
+### Local mode
+
+Local mode requires running directly on a macOS machine with iMessage. It uses Apple's native APIs — reading from the local `chat.db` and sending on-device — with no external server.
+
+1. Grant **Full Disk Access** to your terminal or application in **System Settings → Privacy & Security → Full Disk Access**.
+2. Ensure iMessage is signed in and working on the Mac.
+3. No additional environment variables are required — local mode is the default.
+
+## Receiving messages
+
+There are two ways to receive inbound messages:
+
+- **Webhooks** (recommended for serverless) — Spectrum Cloud delivers each message to an HTTPS endpoint as signed JSON. No long-lived connection or cron job. Remote (cloud) mode only.
+- **Gateway listener** — `startGatewayListener()` consumes spectrum-ts's message stream in real time. Works in all modes; in serverless it needs a cron job to stay connected.
+
+## Webhooks
+
+In remote (cloud) mode, [Spectrum Cloud](https://app.photon.codes) can deliver inbound messages to your HTTPS endpoint as signed JSON — see the [webhook docs](https://photon.codes/docs/webhooks/overview). This is the simplest path for serverless: no cron, no persistent connection.
+
+### 1. Register the endpoint
+
+In the [Spectrum Cloud dashboard](https://app.photon.codes), register your endpoint URL (public HTTPS only) and copy the per-webhook **signing secret** — it is shown only once.
+
+### 2. Configure the secret
+
+Set `IMESSAGE_WEBHOOK_SECRET` to that signing secret. The adapter verifies the `X-Spectrum-Signature` HMAC on every delivery and rejects unsigned, mismatched, or stale (>5 min) requests.
+
+```bash
+IMESSAGE_WEBHOOK_SECRET=whsec_...
+```
+
+### 3. Create the webhook route
+
+```typescript
+// app/api/imessage/webhook/route.ts
+import { after } from "next/server";
+import { bot } from "@/lib/bot";
+
+export async function POST(request: Request): Promise<Response> {
+  return bot.webhooks.imessage(request, {
+    waitUntil: (task) => after(() => task),
+  });
+}
+```
+
+`bot.webhooks.imessage` calls the adapter's `handleWebhook`: it verifies the signature, parses the `messages` event, and routes the message into your bot. Processing runs in the background via `waitUntil`, so the endpoint acknowledges immediately. Spectrum Cloud retries failed deliveries with backoff and delivers at-least-once — dedupe on `X-Spectrum-Webhook-Id` + `message.id` if you need exactly-once side effects.
+
+### Replying
+
+A webhook delivery carries no live connection, but your bot can still respond: for a **DM**, the adapter rebuilds the thread from its address and sends, reacts, edits, and shows typing over spectrum-ts (gRPC) — no gateway needed.
+
+```typescript
+bot.onNewMention(async (thread, message) => {
+  await thread.post("Got it!"); // works directly from a webhook delivery (DM)
+});
+```
+
+Replying into a **group** still requires that group to have been received over the [gateway listener](#gateway-setup-for-serverless) in the same session — an unseen group can't be reconstructed from its id (see [Limitations](#limitations)).
+
+## Gateway setup for serverless
+
+### 1. Create Gateway route
+
+```typescript
+// app/api/imessage/gateway/route.ts
+import { after } from "next/server";
+import { bot } from "@/lib/bot";
+
+export const maxDuration = 800;
+
+export async function GET(request: Request): Promise<Response> {
+  const cronSecret = process.env.CRON_SECRET;
+  if (!cronSecret) {
+    return new Response("CRON_SECRET not configured", { status: 500 });
+  }
+
+  const authHeader = request.headers.get("authorization");
+  if (authHeader !== `Bearer ${cronSecret}`) {
+    return new Response("Unauthorized", { status: 401 });
+  }
+
+  const durationMs = 600 * 1000;
+
+  return bot.adapters.imessage.startGatewayListener(
+    { waitUntil: (task) => after(() => task) },
+    durationMs
+  );
+}
+```
+
+### 2. Configure Vercel Cron
+
+```json
+// vercel.json
+{
+  "crons": [
+    {
+      "path": "/api/imessage/gateway",
+      "schedule": "*/9 * * * *"
+    }
+  ]
+}
+```
+
+This runs every 9 minutes, ensuring overlap with the 10-minute listener duration.
+
+### 3. Environment variables
+
+`CRON_SECRET` is automatically added by Vercel when you configure cron jobs.
+
+## Configuration
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `local` | No | `true` for local, `false` for cloud/self-host. Defaults to local unless `local: false`, `IMESSAGE_LOCAL=false`, or remote credentials (cloud/self-host) are provided |
+| `projectId` | Cloud | Spectrum Cloud project ID. Auto-detected from `IMESSAGE_PROJECT_ID` |
+| `projectSecret` | Cloud | Spectrum Cloud project secret. Auto-detected from `IMESSAGE_PROJECT_SECRET` |
+| `serverUrl` | Self-host | gRPC `host:port` of your iMessage server. Auto-detected from `IMESSAGE_SERVER_URL` |
+| `apiKey` | Self-host | Auth token for the self-hosted server. Auto-detected from `IMESSAGE_API_KEY` |
+| `clients` | No | Explicit `{ address, token, phone }[]` for multi-number self-host setups |
+| `phone` | No | Routing/identity phone for legacy self-host (defaults to `"shared"`). Auto-detected from `IMESSAGE_PHONE` |
+| `webhookSecret` | No | Per-webhook signing secret for verifying Spectrum Cloud deliveries. Required to receive [webhooks](#webhooks). Auto-detected from `IMESSAGE_WEBHOOK_SECRET` |
+| `logger` | No | Logger instance (defaults to `ConsoleLogger("info")`) |
+
+## Environment variables
+
+```bash
+# .env.local
+IMESSAGE_LOCAL=false                  # "false" for cloud/self-host (default: true)
+
+# Cloud (recommended)
+IMESSAGE_PROJECT_ID=...
+IMESSAGE_PROJECT_SECRET=...
+
+# Self-hosted (alternative)
+IMESSAGE_SERVER_URL=imessage.example.com:443   # gRPC host:port (NOT an https URL)
+IMESSAGE_API_KEY=...
+IMESSAGE_PHONE=+1234567890                      # optional, for multi-number routing
+
+# Webhooks (remote/cloud only; see "Webhooks")
+IMESSAGE_WEBHOOK_SECRET=whsec_...               # per-webhook signing secret
+```
+
+## Features
+
+| Feature | Supported |
+|---------|-----------|
+| Mentions | DMs only |
+| DMs | Yes |
+| File uploads | Yes (send) |
+| Reactions (add) | Remote only |
+| Reactions (remove) | No |
+| Message editing | Remote only |
+| Typing indicator | Remote only |
+| Modals | Limited (Remote only) |
+| Message history | No |
+| Thread/chat info | No |
+| Cards | No |
+| Streaming | No |
+| Ephemeral messages | No |
+| Webhooks | Yes (remote — Spectrum Cloud delivery) |
+
+> **Remote** means cloud or self-hosted mode (anything other than `local: true`).
+
+## Modals (Limited)
+
+Remote mode supports limited modal functionality by mapping the Chat SDK's `openModal()` to iMessage native polls. Only `Select` children are supported — the first `Select` in the modal becomes a poll.
+
+- `Modal.title` becomes the poll question.
+- `Select.options` become the poll choices (2–10 supported).
+- Votes trigger `onModalSubmit` with the selected option's `value`.
+
+```typescript
+import { Chat, Modal, Select, SelectOption } from "chat";
+import { createiMessageAdapter } from "@photon-ai/chat-adapter-imessage";
+
+const bot = new Chat({
+  userName: "mybot",
+  adapters: {
+    imessage: createiMessageAdapter({ local: false }),
+  },
+});
+
+bot.onNewMention(async (thread, message) => {
+  await message.openModal(
+    Modal({
+      callbackId: "fav-color",
+      title: "What is your favorite color?",
+      children: [
+        Select({
+          id: "color",
+          label: "Pick a color",
+          options: [
+            SelectOption({ label: "Red", value: "red" }),
+            SelectOption({ label: "Blue", value: "blue" }),
+            SelectOption({ label: "Green", value: "green" }),
+          ],
+        }),
+      ],
+    })
+  );
+});
+
+bot.onModalSubmit("fav-color", async (event) => {
+  const color = event.values.color; // "red", "blue", or "green"
+});
+```
+
+**Not supported:** `Select.placeholder`/`label`, `TextInput`, `RadioSelect`, `Modal.submitLabel`/`closeLabel`, more than one `Select`, and poll vote *deselection*. Polls in the same chat must have distinct titles (votes are matched back to the modal by title). Local mode throws `NotImplementedError`.
+
+## Tapback reactions
+
+iMessage uses tapbacks instead of emoji reactions. The adapter maps standard emoji names to iMessage tapbacks:
+
+| Emoji name | Tapback |
+|------------|---------|
+| `love` / `heart` | Love |
+| `like` / `thumbs_up` | Like |
+| `dislike` / `thumbs_down` | Dislike |
+| `laugh` | Laugh |
+| `emphasize` / `exclamation` | Emphasize |
+| `question` | Question |
+
+## Limitations
+
+- **DMs send cold; groups are session-bound.** For a **DM**, the adapter rebuilds the thread from its address via spectrum-ts (gRPC), so it can send, react, edit, and show typing even into a thread it hasn't seen this session — including a [webhook](#webhooks) delivery. A **group** chat has no by-id resolver, so addressing one requires it to have been received over the gateway/stream in the current session; cold sends to an unseen group throw `NotImplementedError`. (Local mode cannot create spaces at all — it only replies to received messages.)
+- **No message history.** `fetchMessages` is not supported — spectrum-ts exposes no paginated history API.
+- **No thread/chat info.** `fetchThread` is not supported.
+- **No reaction removal.** `removeReaction` is not supported.
+- **Local mode** supports sending and receiving (reply to an inbound message), but not reactions, typing, editing, modals, history, or thread info.
+- **Formatting.** iMessage is plain-text only; Markdown formatting is stripped when sending, preserving the text content.
+- **Platform.** Local mode requires macOS. Cloud and self-host run anywhere.
+- **Cards.** iMessage has no structured card layouts.
+
+## Breaking changes
+
+This version re-platforms the adapter onto **spectrum-ts**. If you are upgrading:
+
+- **Dependency** — replaces `@photon-ai/imessage-kit` + `@photon-ai/advanced-imessage-kit` with `spectrum-ts`.
+- **`IMESSAGE_SERVER_URL` is now a gRPC `host:port`** (self-host), not an `https://` / Socket.IO URL.
+- **New cloud path** — set `IMESSAGE_PROJECT_ID` + `IMESSAGE_PROJECT_SECRET` for Spectrum Cloud.
+- **Removed capabilities** (now `NotImplementedError`): `fetchMessages`, `fetchThread`, `removeReaction`, and cold `postMessage` to an unseen **group** thread (DMs are rebuilt from their address over gRPC — see [Limitations](#limitations)). Local `fetchMessages` (previously supported) is also removed.
+- **`adapter.sdk` → `adapter.app`** — the adapter now exposes the underlying `SpectrumInstance` as `adapter.app` (null until `initialize()`).
+
+## Troubleshooting
+
+### "serverUrl is required when local is false"
+
+- Provide cloud credentials (`IMESSAGE_PROJECT_ID` + `IMESSAGE_PROJECT_SECRET`), or a self-host `IMESSAGE_SERVER_URL` + `IMESSAGE_API_KEY`.
+
+### Self-host connection issues
+
+- Confirm `IMESSAGE_SERVER_URL` is a gRPC `host:port` (e.g. `imessage.example.com:443`), not an `https://` URL.
+- Verify the token matches your server's credentials.
+
+### Local mode not receiving messages
+
+- Verify **Full Disk Access** is granted to your terminal or application.
+- Check that iMessage is signed in and working.
+
+### `NotImplementedError` from `fetchMessages` / `fetchThread` / `removeReaction`
+
+- These are not supported by spectrum-ts. See [Limitations](#limitations).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,175 @@
+import { Logger, Adapter, ChatInstance, WebhookOptions, AdapterPostableMessage, RawMessage, Message, FetchOptions, FetchResult, ThreadInfo, EmojiValue, ModalElement, FormattedContent, BaseFormatConverter, Root } from 'chat';
+import { SpectrumInstance } from 'spectrum-ts';
+
+/** Thread ID components for iMessage */
+interface iMessageThreadId {
+    /** Chat GUID (e.g., "iMessage;-;+1234567890") */
+    chatGuid: string;
+}
+/**
+ * Explicit self-hosted iMessage client entry, passed straight through to
+ * spectrum-ts's `imessage.config({ clients: [...] })`.
+ *
+ * - `address`: gRPC endpoint (`host:port`) of an `@photon-ai/advanced-imessage`
+ *   server.
+ * - `token`: auth token for that server.
+ * - `phone`: the number this client sends/receives as (routing key in
+ *   multi-number setups; use the `"shared"` sentinel for single-number).
+ */
+interface IMessageClientEntry {
+    address: string;
+    phone: string;
+    token: string;
+}
+
+interface iMessageAdapterLocalConfig {
+    /** Unused in local mode; accepted for symmetry/back-compat. */
+    apiKey?: string;
+    local: true;
+    logger: Logger;
+    /** Unused in local mode; accepted for symmetry/back-compat. */
+    serverUrl?: string;
+}
+interface iMessageAdapterRemoteConfig {
+    /** Legacy self-host token. Mapped to a `clients` entry's `token`. */
+    apiKey?: string;
+    /** Explicit self-host gRPC clients (advanced). */
+    clients?: IMessageClientEntry | IMessageClientEntry[];
+    local: false;
+    logger: Logger;
+    /** Routing/identity phone for legacy self-host (defaults to `"shared"`). */
+    phone?: string;
+    /** Spectrum Cloud project id (recommended remote path). */
+    projectId?: string;
+    /** Spectrum Cloud project secret (recommended remote path). */
+    projectSecret?: string;
+    /** Legacy self-host endpoint. Now a gRPC `host:port` (see README). */
+    serverUrl?: string;
+    /** Per-webhook signing secret for verifying Spectrum Cloud deliveries. */
+    webhookSecret?: string;
+}
+type iMessageAdapterConfig = iMessageAdapterLocalConfig | iMessageAdapterRemoteConfig;
+interface CreateiMessageAdapterOptions {
+    apiKey?: string;
+    clients?: IMessageClientEntry | IMessageClientEntry[];
+    local?: boolean;
+    logger?: Logger;
+    phone?: string;
+    projectId?: string;
+    projectSecret?: string;
+    serverUrl?: string;
+    webhookSecret?: string;
+}
+/**
+ * Normalize a legacy `serverUrl` into a gRPC `host:port` address.
+ *
+ * `@photon-ai/advanced-imessage` (the transport spectrum-ts uses) speaks gRPC,
+ * not HTTP/Socket.IO, so any scheme is stripped and a default `:443` port is
+ * appended when none is present.
+ */
+declare function deriveAddress(serverUrl: string): string;
+
+declare class iMessageAdapter implements Adapter {
+    readonly name = "imessage";
+    readonly userName: string;
+    readonly local: boolean;
+    readonly serverUrl?: string;
+    readonly apiKey?: string;
+    readonly projectId?: string;
+    readonly projectSecret?: string;
+    readonly clients?: IMessageClientEntry[];
+    readonly phone?: string;
+    readonly webhookSecret?: string;
+    /** The spectrum-ts instance — null until `initialize()` runs. */
+    app: SpectrumInstance | null;
+    private chat;
+    private readonly logger;
+    private readonly formatConverter;
+    private readonly cache;
+    private readonly modals;
+    private gatewayOptions?;
+    private pump;
+    constructor(config: iMessageAdapterConfig);
+    initialize(chat: ChatInstance): Promise<void>;
+    /**
+     * Handle a Spectrum Cloud webhook delivery (signed JSON `messages` event).
+     *
+     * Verifies the `X-Spectrum-Signature` HMAC, then routes the message into the
+     * Chat SDK. Webhook deliveries are receive-only: a delivered thread has no
+     * live spectrum-ts `Space`, so replying/reacting still requires the gateway
+     * stream (see `startGatewayListener`).
+     *
+     * @see https://photon.codes/docs/webhooks/overview
+     */
+    handleWebhook(request: Request, options?: WebhookOptions): Promise<Response>;
+    postMessage(threadId: string, message: AdapterPostableMessage): Promise<RawMessage>;
+    editMessage(threadId: string, messageId: string, message: AdapterPostableMessage): Promise<RawMessage>;
+    deleteMessage(_threadId: string, _messageId: string): Promise<void>;
+    parseMessage(raw: unknown): Message;
+    fetchMessages(_threadId: string, _options?: FetchOptions): Promise<FetchResult>;
+    fetchThread(_threadId: string): Promise<ThreadInfo>;
+    channelIdFromThreadId(threadId: string): string;
+    addReaction(threadId: string, messageId: string, emoji: EmojiValue | string): Promise<void>;
+    removeReaction(_threadId: string, _messageId: string, _emoji: EmojiValue | string): Promise<void>;
+    startTyping(threadId: string, _status?: string): Promise<void>;
+    openModal(triggerId: string, modal: ModalElement, contextId?: string): Promise<{
+        viewId: string;
+    }>;
+    renderFormatted(content: FormattedContent): string;
+    encodeThreadId(platformData: iMessageThreadId): string;
+    decodeThreadId(threadId: string): iMessageThreadId;
+    isDM(threadId: string): boolean;
+    startGatewayListener(options: WebhookOptions, durationMs?: number, abortSignal?: AbortSignal): Promise<Response>;
+    private routeWebhookMessage;
+    private routeInbound;
+    private handlePollOption;
+    /**
+     * Resolve a sendable spectrum-ts `Space` for a thread.
+     *
+     * Prefers a live `Space` cached from the inbound stream (correct sending
+     * line, no extra round-trip). On a miss — e.g. a webhook-only deployment, or
+     * a cold send — it reconstructs the Space over gRPC via
+     * `imessage(app).space([address])`. Only DMs can be rebuilt from a chatGuid:
+     * the resolver derives them from the peer address, whereas an unseen group
+     * has no by-id resolver (passing participants would create a *new* chat).
+     * Returns `undefined` when no Space can be obtained.
+     */
+    private resolveSpace;
+    private requireSpace;
+    private resolveMessage;
+}
+
+/**
+ * Construct an {@link iMessageAdapter}, filling unset options from environment
+ * variables.
+ *
+ * Mode is chosen by an explicit local signal first — `config.local`, then
+ * `IMESSAGE_LOCAL` — otherwise remote when remote credentials are present (cloud
+ * `projectId` + `projectSecret`, or self-host `clients` / `serverUrl` +
+ * `apiKey`), else local.
+ */
+declare function createiMessageAdapter(config?: CreateiMessageAdapterOptions): iMessageAdapter;
+
+/**
+ * iMessage format conversion using AST-based parsing.
+ *
+ * iMessage supports plain text only -- no rich formatting syntax.
+ * The converter strips formatting markers and outputs clean plain text,
+ * preserving structure (lists, blockquotes, code blocks) with whitespace.
+ */
+
+declare class iMessageFormatConverter extends BaseFormatConverter {
+    /**
+     * Render an AST to iMessage plain text format.
+     * Strips all formatting markers since iMessage doesn't support rich text via API.
+     */
+    fromAst(ast: Root): string;
+    /**
+     * Parse iMessage text into an AST.
+     * iMessage sends plain text, so we just parse it as markdown.
+     */
+    toAst(text: string): Root;
+    private nodeToPlainText;
+}
+
+export { type CreateiMessageAdapterOptions, type IMessageClientEntry, createiMessageAdapter, deriveAddress, iMessageAdapter, type iMessageAdapterConfig, type iMessageAdapterLocalConfig, type iMessageAdapterRemoteConfig, iMessageFormatConverter, type iMessageThreadId };