@photon-ai/chat-adapter-imessage 2.0.0 → 2.2.0

package/README.md

@@ -138,15 +138,15 @@ export async function POST(request: Request): Promise<Response> {
 
 ### 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.
+A webhook delivery carries no live connection, but your bot can still respond: the adapter rebuilds the thread — **DM or group** — from its chat GUID via spectrum-ts's `space.get` and sends, reacts, edits, and shows typing — no gateway needed.
 
 ```typescript
 bot.onNewMention(async (thread, message) => {
-  await thread.post("Got it!"); // works directly from a webhook delivery (DM)
+  await thread.post("Got it!"); // works directly from a webhook delivery
 });
 ```
 
-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)).
+The rebuild needs spectrum-ts to know which iMessage line the chat belongs to; with **multiple lines** configured, an unseen thread can't be resolved and the adapter throws `NotImplementedError` — respond within a thread received over the [gateway listener](#gateway-setup-for-serverless) instead (see [Limitations](#limitations)).
 
 ## Gateway setup for serverless
 
@@ -238,15 +238,23 @@ IMESSAGE_WEBHOOK_SECRET=whsec_...               # per-webhook signing secret
 |---------|-----------|
 | Mentions | DMs only |
 | DMs | Yes |
+| Open DM (cold-start) | Yes (`openDM`) |
 | File uploads | Yes (send) |
 | Reactions (add) | Remote only |
-| Reactions (remove) | No |
+| Reactions (remove) | Remote only (session-added tapbacks) |
 | Message editing | Remote only |
+| Message delete | Remote only (iMessage unsend window) |
+| Mark read | Remote only (`markRead`) |
 | Typing indicator | Remote only |
+| Message effects | Remote only (`sendEffect`) |
+| Mini-app cards | Remote only (`sendMiniApp`) |
+| Voice messages | Remote only (`sendVoice`) |
+| Chat background | Remote only (`setBackground`) |
 | Modals | Limited (Remote only) |
+| Fetch single message | Yes (`fetchMessage`) |
 | Message history | No |
 | Thread/chat info | No |
-| Cards | No |
+| Cards | Mini-app cards only (`sendMiniApp`) |
 | Streaming | No |
 | Ephemeral messages | No |
 | Webhooks | Yes (remote — Spectrum Cloud delivery) |
@@ -312,14 +320,100 @@ iMessage uses tapbacks instead of emoji reactions. The adapter maps standard emo
 | `emphasize` / `exclamation` | Emphasize |
 | `question` | Question |
 
+## Message effects
+
+iMessage expressive-send effects animate a message when it arrives. The adapter exposes them through `sendEffect(threadId, message, effect)` — an adapter-specific extra (there is no first-class Chat SDK slot for effects). It sends the text with the effect attached and returns the sent message. Remote only; local mode throws `NotImplementedError`.
+
+```typescript
+import { createiMessageAdapter, iMessageEffect } from "@photon-ai/chat-adapter-imessage";
+
+const adapter = createiMessageAdapter({ local: false });
+
+bot.onNewMention(async (thread) => {
+  // Friendly name…
+  await adapter.sendEffect(thread.id, "🎉 Task complete!", "confetti");
+  // …or the typed constant:
+  await adapter.sendEffect(thread.id, "🎉 Task complete!", iMessageEffect.confetti);
+});
+```
+
+The `effect` argument accepts a friendly name or a value from the re-exported `iMessageEffect` map. Full-screen effects: `confetti`, `fireworks`, `balloons`, `heart`, `lasers`, `celebration`, `sparkles`, `spotlight`, `echo`. Bubble effects: `slam`, `loud`, `gentle`, `invisible` (invisible ink). Effects attach to text only, so `sendEffect` requires non-empty text content; an unknown effect throws a `ValidationError`.
+
+## Mini-app cards
+
+Mini-app cards are native `MSMessageExtension` balloons — a rich card with a tap-through URL, the closest iMessage gets to a Slack-style rich card rather than a bare link. The adapter exposes them through `sendMiniApp(threadId, card)` — an adapter-specific extra (there is no first-class Chat SDK slot for cards). Remote only; local mode throws `NotImplementedError`.
+
+`sendMiniApp` takes **either** a bare URL **or** a fully-specified card.
+
+### Just a URL (`app(url)`)
+
+The lightweight form: pass a URL string and iMessage renders it as a mini-app — no extension identifiers required. You can also pass a `Promise<string>` or a thunk (`() => string | Promise<string>`), so the link can be minted at send time (e.g. a signed URL).
+
+```typescript
+import { createiMessageAdapter } from "@photon-ai/chat-adapter-imessage";
+
+const adapter = createiMessageAdapter({ local: false });
+
+bot.onNewMention(async (thread) => {
+  await adapter.sendMiniApp(thread.id, "https://example.com/menu");
+
+  // …or compute the URL lazily at send time:
+  await adapter.sendMiniApp(thread.id, async () => mintSignedLink(thread.id));
+});
+```
+
+### A full card (`customizedMiniApp`)
+
+Pass an object to control the bubble's image, captions, and the exact iMessage extension that opens on tap.
+
+```typescript
+await adapter.sendMiniApp(thread.id, {
+  appName: "Poll Kit",
+  teamId: "TEAM123",
+  extensionBundleId: "com.example.pollkit.MessagesExtension",
+  url: "https://example.com/poll/42",
+  appStoreId: 1_234_567, // optional — for recipients without the extension
+  layout: {
+    caption: "Pizza night?",
+    subcaption: "Tap to vote",
+    imageTitle: "Friday",
+    image: pngBytes, // Uint8Array | Buffer | ArrayBuffer | Blob | FileUpload
+    summary: "Vote on Friday's dinner",
+  },
+});
+```
+
+`appName`, `teamId`, and `extensionBundleId` identify the iMessage extension that opens (receiving `url`) when the recipient taps the card; the server builds the matching `MSMessageExtensionBalloonPlugin` id from `teamId` + `extensionBundleId`. Every `layout` field is optional. The `url` accepts a string or `URL` and is validated; a missing required field or an invalid URL throws a `ValidationError`.
+
+## Chat background
+
+iMessage lets a conversation carry its own wallpaper — a touch with no analog on the plain-text competitors. The adapter exposes it through `setBackground(threadId, input, options?)` — an adapter-specific extra (there is no first-class Chat SDK slot for it). It is fire-and-forget: iMessage acknowledges the control signal without returning a message, so the call resolves to `void`. Remote only; local mode throws `NotImplementedError`.
+
+```typescript
+import { readFile } from "node:fs/promises";
+
+// From image bytes (Uint8Array | Buffer | ArrayBuffer | Blob | FileUpload).
+await adapter.setBackground(thread.id, await readFile("./wallpaper.jpg"), {
+  mimeType: "image/jpeg",
+});
+
+// From an http(s) URL, fetched at send time.
+await adapter.setBackground(thread.id, "https://example.com/wallpaper.jpg");
+
+// Remove the current background.
+await adapter.setBackground(thread.id, "clear");
+```
+
+Pass the literal `"clear"` to remove the current background, in-memory image bytes, or an `http(s)` URL (a `URL` or a string) that spectrum-ts fetches at send time. Image bytes need an `image/*` MIME type — supply `options.mimeType` (e.g. `"image/jpeg"`) or an `options.name` with an image extension when it can't be inferred. Local file-path strings are rejected — read the file into bytes and pass those instead. A non-image MIME type, an unresolvable MIME type, or a non-`http(s)` string throws a `ValidationError`.
+
 ## 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.
+- **Cold sends need a resolvable line.** The adapter rebuilds a thread — DM or group — from its chat GUID via spectrum-ts's `space.get`, so it can send, react, edit, and show typing even into a thread it hasn't seen this session, including a [webhook](#webhooks) delivery. With **multiple iMessage lines** configured, spectrum-ts cannot infer which line an unseen chat belongs to, so cold sends there throw `NotImplementedError` — respond within a received message's thread instead.
+- **No message history.** `fetchMessages` is not supported — spectrum-ts exposes no paginated history API. Single messages resolve via `fetchMessage` (from the session cache or spectrum-ts's by-id lookup).
 - **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.
+- **Session-scoped delete & reaction removal.** `deleteMessage` unsends a message resolved from this session (subject to iMessage's ~2-minute unsend window); `removeReaction` retracts a tapback only if it was added via `addReaction` earlier in this session — spectrum-ts exposes no by-target reaction lookup.
+- **Local mode** supports sending (including cold sends by chat GUID), receiving, and opening DMs, but not reactions, typing, editing, deleting, marking read, effects, modals, history, or thread info.
+- **Formatting.** Markdown-typed content (`{ markdown }` or `{ ast }`) renders as native iMessage styled text on remote — bold, italics, links, and lists — via spectrum-ts's `markdown()` builder. Plain strings and `{ raw }` are sent as-is (never reinterpreted as Markdown). Inbound messages always surface as plain text.
 - **Platform.** Local mode requires macOS. Cloud and self-host run anywhere.
 - **Cards.** iMessage has no structured card layouts.
 
@@ -330,7 +424,8 @@ 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.
+- **Unsupported capabilities** (throw `NotImplementedError`): `fetchMessages` and `fetchThread` — spectrum-ts exposes no paginated history or chat-info API. Local `fetchMessages` (previously supported) is also removed. Cold `postMessage` works for DMs and groups alike (rebuilt from the chat GUID — see [Limitations](#limitations)).
+- **Newly supported on spectrum-ts v8**: `deleteMessage` (unsend), `removeReaction` (retract a session-added tapback), `openDM` (cold-start a DM from a handle), `fetchMessage` (single message by id), and `markRead` — all remote-only where noted in [Features](#features).
 - **`adapter.sdk` → `adapter.app`** — the adapter now exposes the underlying `SpectrumInstance` as `adapter.app` (null until `initialize()`).
 
 ## Troubleshooting
@@ -349,10 +444,14 @@ This version re-platforms the adapter onto **spectrum-ts**. If you are upgrading
 - Verify **Full Disk Access** is granted to your terminal or application.
 - Check that iMessage is signed in and working.
 
-### `NotImplementedError` from `fetchMessages` / `fetchThread` / `removeReaction`
+### `NotImplementedError` from `fetchMessages` / `fetchThread`
 
 - These are not supported by spectrum-ts. See [Limitations](#limitations).
 
+### `NotImplementedError` from `deleteMessage` / `removeReaction` / `markRead`
+
+- These are remote-only and session-scoped. `deleteMessage` and `markRead` need the target message to have been seen this session (and delete is bound by iMessage's ~2-minute unsend window); `removeReaction` needs the tapback to have been added via `addReaction` this session. In local mode they throw. See [Limitations](#limitations).
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -1,5 +1,44 @@
-import { Logger, Adapter, ChatInstance, WebhookOptions, AdapterPostableMessage, RawMessage, Message, FetchOptions, FetchResult, ThreadInfo, EmojiValue, ModalElement, FormattedContent, BaseFormatConverter, Root } from 'chat';
-import { SpectrumInstance } from 'spectrum-ts';
+import { FileUpload, Logger, Adapter, ChatInstance, WebhookOptions, AdapterPostableMessage, RawMessage, Message, FetchOptions, FetchResult, ThreadInfo, EmojiValue, ModalElement, FormattedContent, BaseFormatConverter, Root } from 'chat';
+import { ContentBuilder, AppUrl, SpectrumInstance } from 'spectrum-ts';
+export { AppUrl } from 'spectrum-ts';
+import { IMessageMessageEffect, CustomizedMiniAppInput } from 'spectrum-ts/providers/imessage';
+export { CustomizedMiniAppInput, IMessageMessageEffect } from 'spectrum-ts/providers/imessage';
+
+/**
+ * Image bytes for a chat background. Accepts raw bytes (`Uint8Array` / `Buffer`
+ * / `ArrayBuffer`), a `Blob`, or a Chat SDK `FileUpload` — whatever your image
+ * pipeline hands back gets normalized to the bytes spectrum-ts expects.
+ */
+type BackgroundBytes = Uint8Array | ArrayBuffer | Blob | FileUpload;
+/**
+ * A chat-background source. Either:
+ *
+ * - the literal `"clear"` sentinel, to remove the current background;
+ * - in-memory {@link BackgroundBytes};
+ * - an `http(s)` URL (a `URL` or a string) that spectrum-ts fetches at send
+ *   time. Local file paths aren't accepted — read the file into bytes and pass
+ *   those instead.
+ */
+type BackgroundInput = "clear" | BackgroundBytes | URL | string;
+/** Optional chat-background metadata. */
+interface BackgroundOptions {
+    /**
+     * MIME type of the image (`image/*`). Required for raw bytes when the `name`
+     * carries no image extension; inferred from the URL / name otherwise.
+     */
+    mimeType?: string;
+    /** File name used to infer the MIME type from its extension. */
+    name?: string;
+}
+/**
+ * Validate and normalize a chat-background source into the spectrum-ts
+ * `background()` content builder. The `"clear"` sentinel removes the current
+ * background; URL sources are fetched by spectrum-ts at send time; byte sources
+ * are copied to a detached `Buffer` and tagged with a resolved `image/*` MIME
+ * type. The builder is a fire-and-forget control signal — remote and
+ * iMessage-only.
+ */
+declare function resolveBackground(input: BackgroundInput, options?: BackgroundOptions): Promise<ContentBuilder>;
 
 /** Thread ID components for iMessage */
 interface iMessageThreadId {
@@ -69,6 +108,136 @@ interface CreateiMessageAdapterOptions {
  */
 declare function deriveAddress(serverUrl: string): string;
 
+/**
+ * iMessage expressive-send effects, keyed by friendly name. Bubble effects
+ * (`slam`, `loud`, `gentle`, `invisible`) animate the message bubble; the rest
+ * are full-screen effects (`confetti`, `fireworks`, `balloons`, `heart`,
+ * `lasers`, `celebration`, `sparkles`, `spotlight`, `echo`).
+ *
+ * Re-exported from spectrum-ts so callers can reference effects by name without
+ * reaching into the provider package — e.g. `iMessageEffect.confetti`.
+ */
+declare const iMessageEffect: {
+    readonly slam: "com.apple.MobileSMS.expressivesend.impact";
+    readonly loud: "com.apple.MobileSMS.expressivesend.loud";
+    readonly gentle: "com.apple.MobileSMS.expressivesend.gentle";
+    readonly invisible: "com.apple.MobileSMS.expressivesend.invisibleink";
+    readonly confetti: "com.apple.messages.effect.CKConfettiEffect";
+    readonly fireworks: "com.apple.messages.effect.CKFireworksEffect";
+    readonly balloons: "com.apple.messages.effect.CKBalloonEffect";
+    readonly heart: "com.apple.messages.effect.CKHeartEffect";
+    readonly lasers: "com.apple.messages.effect.CKLasersEffect";
+    readonly celebration: "com.apple.messages.effect.CKHappyBirthdayEffect";
+    readonly sparkles: "com.apple.messages.effect.CKSparklesEffect";
+    readonly spotlight: "com.apple.messages.effect.CKSpotlightEffect";
+    readonly echo: "com.apple.messages.effect.CKEchoEffect";
+};
+/** Accepted effect names (`"confetti"`, `"fireworks"`, …). */
+type iMessageEffectName = keyof typeof iMessageEffect;
+/**
+ * Resolve an effect argument to a spectrum-ts effect id. Accepts either a
+ * friendly name (`"confetti"`) or the raw effect id
+ * (`iMessageEffect.confetti`), so both styles work. Throws a `ValidationError`
+ * on an unknown effect.
+ */
+declare function resolveEffect(effect: IMessageMessageEffect | iMessageEffectName): IMessageMessageEffect;
+
+/**
+ * Image bytes for a mini-app card's inline image. Accepts raw bytes
+ * (`Uint8Array` / `Buffer` / `ArrayBuffer`), a `Blob`, or a Chat SDK
+ * `FileUpload` — whatever you already have on hand gets converted to the
+ * `Uint8Array` spectrum-ts expects.
+ */
+type MiniAppImage = Uint8Array | ArrayBuffer | Blob | FileUpload;
+/**
+ * Layout of a mini-app card — everything the recipient sees in the bubble.
+ * Every field is optional; supply the ones that make sense for your card. The
+ * `image` renders as the card's artwork, with `imageTitle` / `imageSubtitle`
+ * overlaid; the caption fields fill the text rows, and `summary` is the
+ * fallback text shown where the mini-app can't render.
+ */
+interface MiniAppCardLayout {
+    caption?: string;
+    image?: MiniAppImage;
+    imageSubtitle?: string;
+    imageTitle?: string;
+    subcaption?: string;
+    summary?: string;
+    trailingCaption?: string;
+    trailingSubcaption?: string;
+}
+/**
+ * A native iMessage mini-app card (an `MSMessageExtension` balloon). The
+ * `appName`, `teamId`, and `extensionBundleId` identify the iMessage extension
+ * that opens when the recipient taps the card, receiving `url`; `appStoreId`
+ * optionally points recipients without the extension installed at its App
+ * Store entry.
+ */
+interface MiniAppCard {
+    /** Display name of the iMessage extension. */
+    appName: string;
+    /** Optional App Store id, for recipients without the extension installed. */
+    appStoreId?: number;
+    /** Bundle id of the `MSMessageExtension` that receives the tap. */
+    extensionBundleId: string;
+    /** What the recipient sees in the bubble. */
+    layout?: MiniAppCardLayout;
+    /** Apple Developer team id that signs the extension. */
+    teamId: string;
+    /** URL handed to the extension when the card is tapped. */
+    url: string | URL;
+}
+/**
+ * Validate and normalize a {@link MiniAppCard} into the
+ * {@link CustomizedMiniAppInput} spectrum-ts's `customizedMiniApp()` builder
+ * expects: required identifiers are checked non-empty, `url` is normalized to a
+ * validated string, and the layout image (if any) is decoded to bytes.
+ */
+declare function resolveMiniApp(card: MiniAppCard): Promise<CustomizedMiniAppInput>;
+/**
+ * Distinguish the lightweight `app(url)` form from a fully-specified
+ * {@link MiniAppCard}. An {@link AppUrl} is a string, a `Promise<string>`, or a
+ * thunk (`() => string | Promise<string>`) — the mini-app card is a plain
+ * object with named fields, so it never matches any of those shapes.
+ */
+declare function isAppUrl(input: MiniAppCard | AppUrl): input is AppUrl;
+
+/**
+ * Audio bytes for a voice message. Accepts raw bytes (`Uint8Array` / `Buffer` /
+ * `ArrayBuffer`), a `Blob`, or a Chat SDK `FileUpload` — whatever your TTS
+ * pipeline hands back gets normalized to the bytes spectrum-ts expects.
+ */
+type VoiceBytes = Uint8Array | ArrayBuffer | Blob | FileUpload;
+/**
+ * A voice message source: in-memory {@link VoiceBytes}, or an `http(s)` URL (a
+ * `URL` or a string) that spectrum-ts fetches at send time. Local file paths
+ * aren't accepted — read the file into bytes and pass those instead.
+ */
+type VoiceInput = VoiceBytes | URL | string;
+/** Optional voice-message metadata. */
+interface VoiceOptions {
+    /**
+     * Playback duration in seconds, surfaced on the waveform bubble. Optional —
+     * iMessage derives the waveform from the audio itself when omitted.
+     */
+    duration?: number;
+    /**
+     * MIME type of the audio (`audio/*`). Required for raw bytes when the `name`
+     * carries no audio extension; inferred from the URL / name otherwise.
+     */
+    mimeType?: string;
+    /** File name handed to spectrum-ts (also used to infer the MIME type). */
+    name?: string;
+}
+/**
+ * Validate and normalize a voice source into the spectrum-ts `voice()` content
+ * builder. URL sources are fetched by spectrum-ts at send time; byte sources
+ * are copied to a detached `Buffer` and tagged with a resolved `audio/*` MIME
+ * type. The builder is sent as a native iMessage voice note (a waveform
+ * bubble), not an audio-file attachment.
+ */
+declare function resolveVoice(input: VoiceInput, options?: VoiceOptions): Promise<ContentBuilder>;
+
 declare class iMessageAdapter implements Adapter {
     readonly name = "imessage";
     readonly userName: string;
@@ -95,23 +264,112 @@ declare class iMessageAdapter implements Adapter {
      * 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`).
+     * Chat SDK. A delivered thread has no live spectrum-ts `Space`, but the
+     * adapter rebuilds one from the chat GUID on demand (see `resolveSpace`), so
+     * replying works directly from a webhook delivery.
      *
      * @see https://photon.codes/docs/webhooks/overview
      */
     handleWebhook(request: Request, options?: WebhookOptions): Promise<Response>;
+    /**
+     * Build the spectrum content for an outbound message. Markdown-typed inputs
+     * are sent via `markdown()` so remote iMessage renders them as native styled
+     * text; raw/string/card inputs stay plain `text()`. Returns the rendered
+     * `body` too so callers can skip an empty send.
+     */
+    private toSpectrumContent;
     postMessage(threadId: string, message: AdapterPostableMessage): Promise<RawMessage>;
+    /**
+     * Send a message with an iMessage expressive-send effect — a bubble effect
+     * (`slam`, `loud`, `gentle`, `invisible`) or a full-screen effect
+     * (`confetti`, `fireworks`, `balloons`, `heart`, `lasers`, `celebration`,
+     * `sparkles`, `spotlight`, `echo`). Not part of the Chat SDK `Adapter`
+     * interface — exposed as an adapter-specific extra (e.g. celebratory confetti
+     * on task completion). Remote only.
+     *
+     * The `effect` argument accepts a friendly name (`"confetti"`) or a value from
+     * the re-exported `iMessageEffect` map. Effects attach to text content only,
+     * so this requires non-empty text.
+     */
+    sendEffect(threadId: string, message: AdapterPostableMessage, effect: IMessageMessageEffect | iMessageEffectName): Promise<RawMessage>;
+    /**
+     * Send an iMessage mini-app card — an `MSMessageExtension` balloon, the
+     * closest iMessage gets to a rich card (à la Slack Block Kit) instead of a
+     * bare link. Not part of the Chat SDK `Adapter` interface — exposed as an
+     * adapter-specific extra. Remote only.
+     *
+     * Two forms:
+     *
+     * - **Just a URL** — pass a string (or a `Promise`/thunk resolving to one, so
+     *   the link can be minted at send time). This is the lightweight `app(url)`
+     *   card: the URL is rendered as a mini-app with no extension identifiers
+     *   required.
+     * - **A full {@link MiniAppCard}** — pass an object to control the bubble's
+     *   image, captions, and the exact iMessage extension that opens on tap. Its
+     *   `appName`, `teamId`, and `extensionBundleId` identify that extension.
+     */
+    sendMiniApp(threadId: string, url: AppUrl): Promise<RawMessage>;
+    sendMiniApp(threadId: string, card: MiniAppCard): Promise<RawMessage>;
+    /**
+     * Send a native iMessage voice note — a real, playable waveform bubble (the
+     * message renders with `isAudioMessage`), not an audio file dropped in as an
+     * attachment. A natural fit for TTS-capable bots that reply with speech. Not
+     * part of the Chat SDK `Adapter` interface — exposed as an adapter-specific
+     * extra. Remote only.
+     *
+     * The `input` is either in-memory audio bytes (`Uint8Array` / `Buffer` /
+     * `ArrayBuffer`, a `Blob`, or a Chat SDK `FileUpload`) or an `http(s)` URL (a
+     * `URL` or a string) that is fetched at send time. Audio bytes need an
+     * `audio/*` MIME type — supply `options.mimeType` (e.g. `"audio/mp4"`) or an
+     * `options.name` with an audio extension when it can't be inferred.
+     */
+    sendVoice(threadId: string, input: VoiceInput, options?: VoiceOptions): Promise<RawMessage>;
+    /**
+     * Set or clear the chat background — the wallpaper behind a conversation, an
+     * iMessage-only touch with no analog on the plain-text competitors. Not part
+     * of the Chat SDK `Adapter` interface — exposed as an adapter-specific extra.
+     * Remote only.
+     *
+     * The `input` is either the literal `"clear"` (to remove the current
+     * background), in-memory image bytes (`Uint8Array` / `Buffer` / `ArrayBuffer`,
+     * a `Blob`, or a Chat SDK `FileUpload`), or an `http(s)` URL (a `URL` or a
+     * string) that is fetched at send time. Image bytes need an `image/*` MIME
+     * type — supply `options.mimeType` (e.g. `"image/jpeg"`) or an `options.name`
+     * with an image extension when it can't be inferred.
+     *
+     * Fire-and-forget: iMessage acknowledges the control signal without returning
+     * a message, so this resolves to `void` rather than a {@link RawMessage}.
+     */
+    setBackground(threadId: string, input: BackgroundInput, options?: BackgroundOptions): Promise<void>;
     editMessage(threadId: string, messageId: string, message: AdapterPostableMessage): Promise<RawMessage>;
-    deleteMessage(_threadId: string, _messageId: string): Promise<void>;
+    deleteMessage(threadId: string, messageId: string): Promise<void>;
     parseMessage(raw: unknown): Message;
+    /**
+     * Fetch a single message by id. spectrum-ts can resolve a message by id
+     * (from the inbound cache or the provider's by-id lookup) even though it has
+     * no paginated history API, so single-message reads work where
+     * `fetchMessages` cannot. Returns `null` when the message can't be resolved.
+     */
+    fetchMessage(threadId: string, messageId: string): Promise<Message | null>;
     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>;
+    removeReaction(_threadId: string, messageId: string, emoji: EmojiValue | string): Promise<void>;
     startTyping(threadId: string, _status?: string): Promise<void>;
+    /**
+     * Cold-start a DM with a phone number / handle. spectrum-ts resolves (or
+     * creates) the 1:1 conversation from the participant via `space.create`, so
+     * the bot can message a user it has never received from. Returns the encoded
+     * thread id, ready to pass to `postMessage`.
+     */
+    openDM(userId: string): Promise<string>;
+    /**
+     * Mark a received message (and the conversation up to it) as read, surfacing
+     * a read receipt where iMessage supports one. Remote only; not part of the
+     * Chat SDK `Adapter` interface — exposed as an adapter-specific extra.
+     */
+    markRead(threadId: string, messageId: string): Promise<void>;
     openModal(triggerId: string, modal: ModalElement, contextId?: string): Promise<{
         viewId: string;
     }>;
@@ -128,13 +386,20 @@ declare class iMessageAdapter implements Adapter {
      *
      * 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.
+     * a cold send — it rebuilds the Space from the chat GUID via
+     * `imessage(app).space.get(chatGuid)`, which works for DMs and groups alike.
+     * The rebuild can still fail when several iMessage lines are configured and
+     * spectrum-ts cannot infer which line the chat belongs to (`space.get`
+     * requires `params.phone` there). Returns `undefined` when no Space can be
+     * obtained.
      */
     private resolveSpace;
+    /**
+     * The iMessage provider's Space namespace (`get` / `create`). `HasProvider`
+     * over the default provider tuple won't narrow to `true`, so `imessage(app)`
+     * types as `never` — cast to the slice of the instance we use.
+     */
+    private platformSpaces;
     private requireSpace;
     private resolveMessage;
 }
@@ -153,11 +418,24 @@ declare function createiMessageAdapter(config?: CreateiMessageAdapterOptions): i
 /**
  * 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.
+ * Remote iMessage (via spectrum-ts) renders CommonMark natively as styled text
+ * (bold/italic/links etc. via UTF-16 formatting ranges), so markdown-typed
+ * outbound content is sent through spectrum's `markdown()` builder verbatim --
+ * see `renderPostableContent`. The plain-text rendering here (`fromAst`) is
+ * still used for inbound parsing, `renderFormatted`, and the raw/card fallback
+ * paths: it strips formatting markers and preserves structure (lists,
+ * blockquotes, code blocks) with whitespace.
  */
 
+/**
+ * The spectrum content a postable message should be sent as: the body string
+ * plus whether spectrum should render it as native markdown (styled text) or
+ * pass it through as plain text.
+ */
+interface PostableContent {
+    body: string;
+    markdown: boolean;
+}
 declare class iMessageFormatConverter extends BaseFormatConverter {
     /**
      * Render an AST to iMessage plain text format.
@@ -169,7 +447,21 @@ declare class iMessageFormatConverter extends BaseFormatConverter {
      * iMessage sends plain text, so we just parse it as markdown.
      */
     toAst(text: string): Root;
+    /**
+     * Decide how a postable message should reach spectrum-ts.
+     *
+     * Markdown-typed inputs -- `{ markdown }` and `{ ast }` -- carry CommonMark
+     * the caller wants styled, so their source is preserved verbatim and flagged
+     * `markdown: true`; the adapter sends it via spectrum's `markdown()` builder,
+     * which renders bold/italic/links/lists as native iMessage styled text.
+     *
+     * Everything else is pass-through-as-is by contract -- a plain `string` or
+     * `{ raw }` must not have stray `*`/`_` reinterpreted as formatting, and
+     * cards fall back to plain text -- so those are rendered to plain text and
+     * flagged `markdown: false`.
+     */
+    renderPostableContent(message: AdapterPostableMessage): PostableContent;
     private nodeToPlainText;
 }
 
-export { type CreateiMessageAdapterOptions, type IMessageClientEntry, createiMessageAdapter, deriveAddress, iMessageAdapter, type iMessageAdapterConfig, type iMessageAdapterLocalConfig, type iMessageAdapterRemoteConfig, iMessageFormatConverter, type iMessageThreadId };
+export { type BackgroundBytes, type BackgroundInput, type BackgroundOptions, type CreateiMessageAdapterOptions, type IMessageClientEntry, type MiniAppCard, type MiniAppCardLayout, type MiniAppImage, type VoiceBytes, type VoiceInput, type VoiceOptions, createiMessageAdapter, deriveAddress, iMessageAdapter, type iMessageAdapterConfig, type iMessageAdapterLocalConfig, type iMessageAdapterRemoteConfig, iMessageEffect, type iMessageEffectName, iMessageFormatConverter, type iMessageThreadId, isAppUrl, resolveBackground, resolveEffect, resolveMiniApp, resolveVoice };