@photon-ai/chat-adapter-imessage 2.1.0 → 2.2.1

package/dist/index.js

@@ -1,15 +1,115 @@
 // src/adapter.ts
-import { extractFiles, ValidationError as ValidationError4 } from "@chat-adapter/shared";
+import { extractFiles, ValidationError as ValidationError8 } from "@chat-adapter/shared";
 import { NotImplementedError } from "chat";
 import {
+  app as appContent,
+  markdown as markdownContent,
   poll as pollContent,
   Spectrum,
   text as textContent
 } from "spectrum-ts";
-import { imessage } from "spectrum-ts/providers/imessage";
+import {
+  customizedMiniApp,
+  effect as effectContent,
+  imessage as imessage2
+} from "spectrum-ts/providers/imessage";
 
-// src/config.ts
+// src/background.ts
 import { ValidationError } from "@chat-adapter/shared";
+import { lookup as lookupMimeType } from "mime-types";
+import { background as backgroundContent } from "spectrum-ts/providers/imessage";
+var IMAGE_MIME_PATTERN = /^image\//i;
+async function toBytes(input) {
+  if (input instanceof Uint8Array) {
+    return { bytes: Buffer.from(input) };
+  }
+  if (input instanceof ArrayBuffer) {
+    return { bytes: Buffer.from(input) };
+  }
+  if (input instanceof Blob) {
+    return {
+      bytes: Buffer.from(await input.arrayBuffer()),
+      mimeHint: input.type || void 0
+    };
+  }
+  const data = input.data;
+  if (data === void 0) {
+    throw new ValidationError(
+      "imessage",
+      "Chat background must be a Uint8Array, ArrayBuffer, Blob, or FileUpload"
+    );
+  }
+  const nested = await toBytes(data);
+  return {
+    bytes: nested.bytes,
+    mimeHint: input.mimeType || nested.mimeHint,
+    nameHint: input.filename || nested.nameHint
+  };
+}
+function toBackgroundUrl(input) {
+  if (input instanceof URL) {
+    return input;
+  }
+  if (typeof input !== "string") {
+    return;
+  }
+  let url;
+  try {
+    url = new URL(input);
+  } catch {
+    throw new ValidationError(
+      "imessage",
+      `Chat background string input must be an http(s) URL, got "${input}". Pass image bytes for local files.`
+    );
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new ValidationError(
+      "imessage",
+      `Chat background URL must be http(s), got "${url.protocol}"`
+    );
+  }
+  return url;
+}
+function resolveBytesMime(hint, name) {
+  if (hint && IMAGE_MIME_PATTERN.test(hint)) {
+    return hint;
+  }
+  if (name) {
+    const inferred = lookupMimeType(name);
+    if (inferred && IMAGE_MIME_PATTERN.test(inferred)) {
+      return inferred;
+    }
+  }
+  throw new ValidationError(
+    "imessage",
+    hint ? `Chat background requires an image/* MIME type, got "${hint}"` : 'Chat background requires an image/* MIME type \u2014 pass options.mimeType (e.g. "image/jpeg") or a name with an image extension'
+  );
+}
+async function resolveBackground(input, options = {}) {
+  if (input === "clear") {
+    return backgroundContent("clear");
+  }
+  if (options.mimeType && !IMAGE_MIME_PATTERN.test(options.mimeType)) {
+    throw new ValidationError(
+      "imessage",
+      `Chat background requires an image/* MIME type, got "${options.mimeType}"`
+    );
+  }
+  const url = toBackgroundUrl(input);
+  if (url) {
+    return backgroundContent(
+      url,
+      options.mimeType ? { mimeType: options.mimeType } : void 0
+    );
+  }
+  const { bytes, mimeHint, nameHint } = await toBytes(input);
+  const name = options.name ?? nameHint;
+  const mimeType = resolveBytesMime(options.mimeType ?? mimeHint, name);
+  return backgroundContent(bytes, { mimeType });
+}
+
+// src/config.ts
+import { ValidationError as ValidationError2 } from "@chat-adapter/shared";
 var SHARED_PHONE = "shared";
 var URL_SCHEME_RE = /^[a-z][a-z0-9+.-]*:\/\//i;
 function deriveAddress(serverUrl) {
@@ -45,18 +145,47 @@ function resolveSpectrumConfig(local, auth) {
       }
     };
   }
-  throw new ValidationError(
+  throw new ValidationError2(
     "imessage",
     "Remote mode requires Spectrum Cloud credentials (projectId + projectSecret), explicit clients, or serverUrl + apiKey."
   );
 }
 
+// src/effects.ts
+import { ValidationError as ValidationError3 } from "@chat-adapter/shared";
+import { imessage } from "spectrum-ts/providers/imessage";
+var iMessageEffect = imessage.effect.message;
+var EFFECT_IDS = new Set(Object.values(iMessageEffect));
+var EFFECT_NAMES = Object.keys(iMessageEffect);
+function resolveEffect(effect) {
+  if (effect in iMessageEffect) {
+    return iMessageEffect[effect];
+  }
+  if (EFFECT_IDS.has(effect)) {
+    return effect;
+  }
+  throw new ValidationError3(
+    "imessage",
+    `Unknown iMessage effect: "${effect}". Supported: ${EFFECT_NAMES.join(", ")}`
+  );
+}
+
 // src/internal/cache.ts
 var DEFAULT_MAX_SPACES = 256;
 var DEFAULT_MAX_MESSAGES = 1024;
 var InboundCache = class {
   spaces = /* @__PURE__ */ new Map();
   messages = /* @__PURE__ */ new Map();
+  /** Sending line last seen per chat GUID — a hint for rebuilding an uncached
+   * Space on the right line when several are configured. */
+  phones = /* @__PURE__ */ new Map();
+  /**
+   * Reaction messages this session sent via `addReaction`, keyed by their
+   * target so `removeReaction` can `unsend()` them. spectrum-ts models a
+   * tapback as its own message, and the only handle to retract one is the
+   * `Message` that `react()` returns — there is no by-target removal API.
+   */
+  reactions = /* @__PURE__ */ new Map();
   maxSpaces;
   maxMessages;
   constructor(maxSpaces = DEFAULT_MAX_SPACES, maxMessages = DEFAULT_MAX_MESSAGES) {
@@ -84,10 +213,38 @@ var InboundCache = class {
   getSpace(chatGuid) {
     return this.spaces.get(chatGuid);
   }
+  /** Record the sending line seen for a chat GUID, if the delivery carried one. */
+  rememberPhone(chatGuid, phone) {
+    if (!phone) {
+      return;
+    }
+    this.phones.set(chatGuid, phone);
+    evict(this.phones, this.maxSpaces);
+  }
+  getPhone(chatGuid) {
+    return this.phones.get(chatGuid);
+  }
   getMessage(id) {
     return this.messages.get(id);
   }
+  /** Record the reaction message returned by `react()` for later removal. */
+  rememberReaction(targetMessageId, glyph, reaction) {
+    this.reactions.set(reactionKey(targetMessageId, glyph), reaction);
+    evict(this.reactions, this.maxMessages);
+  }
+  /** Look up (and forget) a tracked reaction so it can be `unsend()`-ed once. */
+  takeReaction(targetMessageId, glyph) {
+    const key = reactionKey(targetMessageId, glyph);
+    const reaction = this.reactions.get(key);
+    if (reaction) {
+      this.reactions.delete(key);
+    }
+    return reaction;
+  }
 };
+function reactionKey(targetMessageId, glyph) {
+  return `${targetMessageId}::${glyph}`;
+}
 function evict(map, max) {
   if (map.size <= max) {
     return;
@@ -168,26 +325,31 @@ var MessagePump = class {
 import { Message, parseMarkdown } from "chat";
 
 // src/internal/thread.ts
-import { ValidationError as ValidationError2 } from "@chat-adapter/shared";
+import { ValidationError as ValidationError4 } from "@chat-adapter/shared";
 var THREAD_PREFIX = "imessage:";
+var LINE_SEP = "~";
 function encodeThreadId(platformData) {
-  return `${THREAD_PREFIX}${platformData.chatGuid}`;
+  const { chatGuid, phone } = platformData;
+  return phone ? `${THREAD_PREFIX}${chatGuid}${LINE_SEP}${phone}` : `${THREAD_PREFIX}${chatGuid}`;
 }
 function decodeThreadId(threadId) {
   if (!threadId.startsWith(THREAD_PREFIX)) {
-    throw new ValidationError2(
+    throw new ValidationError4(
       "imessage",
       `Invalid iMessage thread ID: ${threadId}`
     );
   }
-  const chatGuid = threadId.slice(THREAD_PREFIX.length);
+  const rest = threadId.slice(THREAD_PREFIX.length);
+  const sepIndex = rest.indexOf(LINE_SEP);
+  const chatGuid = sepIndex === -1 ? rest : rest.slice(0, sepIndex);
+  const phone = sepIndex === -1 ? void 0 : rest.slice(sepIndex + 1);
   if (!chatGuid) {
-    throw new ValidationError2(
+    throw new ValidationError4(
       "imessage",
       `Invalid iMessage thread ID: ${threadId} (empty chat GUID)`
     );
   }
-  return { chatGuid };
+  return phone ? { chatGuid, phone } : { chatGuid };
 }
 function isDMChatGuid(chatGuid) {
   return chatGuid.includes(";-;");
@@ -198,7 +360,7 @@ function buildChatMessageFromFields(fields) {
   const text = extractText(fields.content);
   return new Message({
     id: fields.id,
-    threadId: encodeThreadId({ chatGuid: fields.chatGuid }),
+    threadId: encodeThreadId({ chatGuid: fields.chatGuid, phone: fields.phone }),
     text,
     formatted: parseMarkdown(text),
     author: {
@@ -226,6 +388,7 @@ function buildChatMessage(message, space) {
     content: message.content,
     senderId: message.sender?.id ?? "",
     isOutbound: message.direction === "outbound",
+    phone: space.phone,
     timestamp: message.timestamp,
     raw: message
   });
@@ -317,8 +480,8 @@ function titleKey(chatGuid, title) {
 }
 
 // src/internal/outbound.ts
-import { ValidationError as ValidationError3 } from "@chat-adapter/shared";
-import { lookup as lookupMimeType } from "mime-types";
+import { ValidationError as ValidationError5 } from "@chat-adapter/shared";
+import { lookup as lookupMimeType2 } from "mime-types";
 import { attachment } from "spectrum-ts";
 var EMOJI_GLYPHS = {
   heart: "\u2764\uFE0F",
@@ -336,7 +499,7 @@ function emojiToGlyph(emoji) {
   const name = typeof emoji === "string" ? emoji : emoji.name;
   const glyph = EMOJI_GLYPHS[name];
   if (!glyph) {
-    throw new ValidationError3(
+    throw new ValidationError5(
       "imessage",
       `Unsupported iMessage tapback: "${name}". Supported: heart, thumbs_up, thumbs_down, laugh, emphasize, question`
     );
@@ -354,7 +517,7 @@ async function fileToAttachment(file) {
     buffer = Buffer.from(data);
   }
   const name = file.filename || "attachment";
-  const mimeType = file.mimeType || lookupMimeType(name) || "application/octet-stream";
+  const mimeType = file.mimeType || lookupMimeType2(name) || "application/octet-stream";
   return attachment(buffer, { name, mimeType });
 }
 
@@ -390,6 +553,7 @@ function buildChatMessageFromWebhook(message, space) {
     content: message.content,
     senderId: message.sender?.id ?? "",
     isOutbound: message.direction === "outbound",
+    phone: space.phone ?? message.space?.phone,
     timestamp: message.timestamp ? new Date(message.timestamp) : /* @__PURE__ */ new Date(),
     raw: message
   });
@@ -411,7 +575,8 @@ import {
   isParagraphNode,
   isStrongNode,
   isTextNode,
-  parseMarkdown as parseMarkdown2
+  parseMarkdown as parseMarkdown2,
+  stringifyMarkdown
 } from "chat";
 var iMessageFormatConverter = class extends BaseFormatConverter {
   /**
@@ -431,6 +596,30 @@ var iMessageFormatConverter = class extends BaseFormatConverter {
   toAst(text) {
     return parseMarkdown2(text);
   }
+  /**
+   * 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) {
+    if (message && typeof message === "object") {
+      if ("markdown" in message && typeof message.markdown === "string") {
+        return { body: message.markdown, markdown: true };
+      }
+      if ("ast" in message && message.ast) {
+        return { body: stringifyMarkdown(message.ast), markdown: true };
+      }
+    }
+    return { body: this.renderPostable(message), markdown: false };
+  }
   nodeToPlainText(node) {
     if (isParagraphNode(node)) {
       return getNodeChildren(node).map((child) => this.nodeToPlainText(child)).join("");
@@ -478,6 +667,169 @@ var iMessageFormatConverter = class extends BaseFormatConverter {
   }
 };
 
+// src/miniapp.ts
+import { ValidationError as ValidationError6 } from "@chat-adapter/shared";
+async function toImageBytes(image) {
+  if (image instanceof Uint8Array) {
+    return new Uint8Array(image);
+  }
+  if (image instanceof ArrayBuffer) {
+    return new Uint8Array(image);
+  }
+  if (image instanceof Blob) {
+    return new Uint8Array(await image.arrayBuffer());
+  }
+  const data = image.data;
+  if (data === void 0) {
+    throw new ValidationError6(
+      "imessage",
+      "Mini-app card image must be a Uint8Array, ArrayBuffer, Blob, or FileUpload"
+    );
+  }
+  return toImageBytes(data);
+}
+function requireField(value, field) {
+  if (!value || value.trim().length === 0) {
+    throw new ValidationError6(
+      "imessage",
+      `Mini-app card requires a non-empty "${field}"`
+    );
+  }
+  return value;
+}
+async function resolveMiniApp(card) {
+  const url = typeof card.url === "string" ? card.url : card.url.toString();
+  try {
+    new URL(url);
+  } catch {
+    throw new ValidationError6(
+      "imessage",
+      `Mini-app card has an invalid url: "${url}"`
+    );
+  }
+  const layout = card.layout ?? {};
+  const image = layout.image ? await toImageBytes(layout.image) : void 0;
+  return {
+    appName: requireField(card.appName, "appName"),
+    teamId: requireField(card.teamId, "teamId"),
+    extensionBundleId: requireField(
+      card.extensionBundleId,
+      "extensionBundleId"
+    ),
+    url,
+    ...card.appStoreId === void 0 ? {} : { appStoreId: card.appStoreId },
+    layout: {
+      caption: layout.caption,
+      subcaption: layout.subcaption,
+      trailingCaption: layout.trailingCaption,
+      trailingSubcaption: layout.trailingSubcaption,
+      imageTitle: layout.imageTitle,
+      imageSubtitle: layout.imageSubtitle,
+      summary: layout.summary,
+      ...image ? { image } : {}
+    }
+  };
+}
+function isAppUrl(input) {
+  return typeof input === "string" || typeof input === "function" || typeof input === "object" && input !== null && typeof input.then === "function";
+}
+
+// src/voice.ts
+import { ValidationError as ValidationError7 } from "@chat-adapter/shared";
+import { lookup as lookupMimeType3 } from "mime-types";
+import { voice as voiceContent } from "spectrum-ts";
+var AUDIO_MIME_PATTERN = /^audio\//i;
+async function toBytes2(input) {
+  if (input instanceof Uint8Array) {
+    return { bytes: Buffer.from(input) };
+  }
+  if (input instanceof ArrayBuffer) {
+    return { bytes: Buffer.from(input) };
+  }
+  if (input instanceof Blob) {
+    return {
+      bytes: Buffer.from(await input.arrayBuffer()),
+      mimeHint: input.type || void 0
+    };
+  }
+  const data = input.data;
+  if (data === void 0) {
+    throw new ValidationError7(
+      "imessage",
+      "Voice message must be a Uint8Array, ArrayBuffer, Blob, or FileUpload"
+    );
+  }
+  const nested = await toBytes2(data);
+  return {
+    bytes: nested.bytes,
+    mimeHint: input.mimeType || nested.mimeHint,
+    nameHint: input.filename || nested.nameHint
+  };
+}
+function toVoiceUrl(input) {
+  if (input instanceof URL) {
+    return input;
+  }
+  if (typeof input !== "string") {
+    return;
+  }
+  let url;
+  try {
+    url = new URL(input);
+  } catch {
+    throw new ValidationError7(
+      "imessage",
+      `Voice message string input must be an http(s) URL, got "${input}". Pass audio bytes for local files.`
+    );
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new ValidationError7(
+      "imessage",
+      `Voice message URL must be http(s), got "${url.protocol}"`
+    );
+  }
+  return url;
+}
+function resolveBytesMime2(hint, name) {
+  if (hint && AUDIO_MIME_PATTERN.test(hint)) {
+    return hint;
+  }
+  if (name) {
+    const inferred = lookupMimeType3(name);
+    if (inferred && AUDIO_MIME_PATTERN.test(inferred)) {
+      return inferred;
+    }
+  }
+  throw new ValidationError7(
+    "imessage",
+    hint ? `Voice message requires an audio/* MIME type, got "${hint}"` : 'Voice message requires an audio/* MIME type \u2014 pass options.mimeType (e.g. "audio/mp4") or a name with an audio extension'
+  );
+}
+async function resolveVoice(input, options = {}) {
+  if (options.mimeType && !AUDIO_MIME_PATTERN.test(options.mimeType)) {
+    throw new ValidationError7(
+      "imessage",
+      `Voice message requires an audio/* MIME type, got "${options.mimeType}"`
+    );
+  }
+  const url = toVoiceUrl(input);
+  if (url) {
+    return voiceContent(url, {
+      ...options.mimeType ? { mimeType: options.mimeType } : {},
+      ...options.name ? { name: options.name } : {},
+      ...options.duration === void 0 ? {} : { duration: options.duration }
+    });
+  }
+  const { bytes, mimeHint, nameHint } = await toBytes2(input);
+  const name = options.name ?? nameHint;
+  const mimeType = resolveBytesMime2(options.mimeType ?? mimeHint, name);
+  return voiceContent(bytes, {
+    mimeType,
+    ...name ? { name } : {},
+    ...options.duration === void 0 ? {} : { duration: options.duration }
+  });
+}
+
 // src/adapter.ts
 var TYPING_DURATION_MS = 3e3;
 var iMessageAdapter = class {
@@ -491,8 +843,10 @@ var iMessageAdapter = class {
   clients;
   phone;
   webhookSecret;
-  /** The spectrum-ts instance — null until `initialize()` runs. */
+  /** The spectrum-ts instance — null until `initialize()` or `ensureApp()` runs. */
   app = null;
+  /** In-flight app build, so concurrent callers share one construction. */
+  appBuild = null;
   chat = null;
   logger;
   formatConverter = new iMessageFormatConverter();
@@ -502,7 +856,7 @@ var iMessageAdapter = class {
   pump = null;
   constructor(config) {
     if (config.local && process.platform !== "darwin") {
-      throw new ValidationError4(
+      throw new ValidationError8(
         "imessage",
         "iMessage adapter local mode requires macOS. Current platform: " + process.platform
       );
@@ -521,6 +875,34 @@ var iMessageAdapter = class {
   }
   async initialize(chat) {
     this.chat = chat;
+    await this.ensureApp();
+    this.pump = new MessagePump(
+      () => {
+        if (!this.app) {
+          throw new Error("Adapter not initialized");
+        }
+        return this.app.messages;
+      },
+      (space, message) => this.routeInbound(space, message, this.gatewayOptions),
+      this.logger
+    );
+  }
+  /**
+   * Build the spectrum-ts app on demand. eve may call the adapter in an
+   * invocation that never ran `initialize()` (e.g. a Vercel Workflow reply
+   * callback), leaving `this.app` null — every send funnels through here first.
+   */
+  async ensureApp() {
+    if (this.app) {
+      return;
+    }
+    this.appBuild ??= this.buildApp().catch((error) => {
+      this.appBuild = null;
+      throw error;
+    });
+    await this.appBuild;
+  }
+  async buildApp() {
     const { providerConfig, projectId, projectSecret } = resolveSpectrumConfig(
       this.local,
       {
@@ -532,18 +914,8 @@ var iMessageAdapter = class {
         serverUrl: this.serverUrl
       }
     );
-    const providers = [imessage.config(providerConfig)];
+    const providers = [imessage2.config(providerConfig)];
     this.app = projectId && projectSecret ? await Spectrum({ providers, projectId, projectSecret }) : await Spectrum({ providers });
-    this.pump = new MessagePump(
-      () => {
-        if (!this.app) {
-          throw new Error("Adapter not initialized");
-        }
-        return this.app.messages;
-      },
-      (space, message) => this.routeInbound(space, message, this.gatewayOptions),
-      this.logger
-    );
     let mode;
     if (this.local) {
       mode = "local";
@@ -612,26 +984,152 @@ var iMessageAdapter = class {
     this.routeWebhookMessage(payload, options);
     return new Response(null, { status: 200 });
   }
+  /**
+   * 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.
+   */
+  toSpectrumContent(message) {
+    const { body, markdown } = this.formatConverter.renderPostableContent(message);
+    return {
+      body,
+      content: markdown ? markdownContent(body) : textContent(body)
+    };
+  }
   async postMessage(threadId, message) {
     const space = await this.requireSpace(threadId, "postMessage");
-    const body = this.formatConverter.renderPostable(message);
+    const { body, content } = this.toSpectrumContent(message);
     const files = extractFiles(message);
     let first;
     if (body && body.trim().length > 0) {
-      first = await space.send(textContent(body)) ?? first;
+      first = await space.send(content) ?? first;
     }
     for (const file of files) {
       const sent = await space.send(await fileToAttachment(file)) ?? void 0;
       first ??= sent;
     }
     if (!first) {
-      throw new ValidationError4(
+      throw new ValidationError8(
         "imessage",
         "postMessage requires non-empty text or at least one attachment"
       );
     }
     return { id: first.id, threadId, raw: first };
   }
+  /**
+   * 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.
+   */
+  async sendEffect(threadId, message, effect) {
+    if (this.local) {
+      throw new NotImplementedError(
+        "sendEffect is not supported in local mode",
+        "sendEffect"
+      );
+    }
+    const space = await this.requireSpace(threadId, "sendEffect");
+    const { body, content } = this.toSpectrumContent(message);
+    if (!body || body.trim().length === 0) {
+      throw new ValidationError8(
+        "imessage",
+        "sendEffect requires non-empty text content"
+      );
+    }
+    const effectId = resolveEffect(effect);
+    const sent = await space.send(effectContent(content, effectId));
+    if (!sent) {
+      throw new ValidationError8(
+        "imessage",
+        "sendEffect could not send the message"
+      );
+    }
+    return { id: sent.id, threadId, raw: sent };
+  }
+  async sendMiniApp(threadId, input) {
+    if (this.local) {
+      throw new NotImplementedError(
+        "sendMiniApp is not supported in local mode",
+        "sendMiniApp"
+      );
+    }
+    const space = await this.requireSpace(threadId, "sendMiniApp");
+    const content = isAppUrl(input) ? appContent(input) : customizedMiniApp(await resolveMiniApp(input));
+    const sent = await space.send(content);
+    if (!sent) {
+      throw new ValidationError8(
+        "imessage",
+        "sendMiniApp could not send the card"
+      );
+    }
+    return { id: sent.id, threadId, raw: sent };
+  }
+  /**
+   * 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.
+   */
+  async sendVoice(threadId, input, options) {
+    if (this.local) {
+      throw new NotImplementedError(
+        "sendVoice is not supported in local mode",
+        "sendVoice"
+      );
+    }
+    const space = await this.requireSpace(threadId, "sendVoice");
+    const content = await resolveVoice(input, options);
+    const sent = await space.send(content);
+    if (!sent) {
+      throw new ValidationError8(
+        "imessage",
+        "sendVoice could not send the voice message"
+      );
+    }
+    return { id: sent.id, threadId, raw: sent };
+  }
+  /**
+   * 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}.
+   */
+  async setBackground(threadId, input, options) {
+    if (this.local) {
+      throw new NotImplementedError(
+        "setBackground is not supported in local mode",
+        "setBackground"
+      );
+    }
+    const space = await this.requireSpace(threadId, "setBackground");
+    const content = await resolveBackground(input, options);
+    await space.send(content);
+  }
   async editMessage(threadId, messageId, message) {
     if (this.local) {
       throw new NotImplementedError(
@@ -646,21 +1144,42 @@ var iMessageAdapter = class {
         "editMessage"
       );
     }
-    await target.edit(
-      textContent(this.formatConverter.renderPostable(message))
-    );
+    await target.edit(this.toSpectrumContent(message).content);
     return { id: messageId, threadId, raw: target };
   }
-  async deleteMessage(_threadId, _messageId) {
-    throw new NotImplementedError(
-      "deleteMessage is not implemented",
-      "deleteMessage"
-    );
+  async deleteMessage(threadId, messageId) {
+    if (this.local) {
+      throw new NotImplementedError(
+        "deleteMessage is not supported in local mode",
+        "deleteMessage"
+      );
+    }
+    const target = await this.resolveMessage(threadId, messageId);
+    if (!target) {
+      throw new NotImplementedError(
+        "deleteMessage requires the target message to have been sent or received in this session",
+        "deleteMessage"
+      );
+    }
+    await target.unsend();
   }
   parseMessage(raw) {
     const message = raw;
     return buildChatMessage(message, message.space);
   }
+  /**
+   * 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.
+   */
+  async fetchMessage(threadId, messageId) {
+    const target = await this.resolveMessage(threadId, messageId);
+    if (!target) {
+      return null;
+    }
+    return this.parseMessage(target);
+  }
   async fetchMessages(_threadId, _options) {
     throw new NotImplementedError(
       "fetchMessages (message history) is not supported by spectrum-ts",
@@ -691,13 +1210,27 @@ var iMessageAdapter = class {
         "addReaction"
       );
     }
-    await target.react(glyph);
+    const reaction = await target.react(glyph);
+    if (reaction) {
+      this.cache.rememberReaction(messageId, glyph, reaction);
+    }
   }
-  async removeReaction(_threadId, _messageId, _emoji) {
-    throw new NotImplementedError(
-      "removeReaction is not supported (spectrum-ts has no reaction-removal API)",
-      "removeReaction"
-    );
+  async removeReaction(_threadId, messageId, emoji) {
+    if (this.local) {
+      throw new NotImplementedError(
+        "removeReaction is not supported in local mode",
+        "removeReaction"
+      );
+    }
+    const glyph = emojiToGlyph(emoji);
+    const reaction = this.cache.takeReaction(messageId, glyph);
+    if (!reaction) {
+      throw new NotImplementedError(
+        "removeReaction requires the reaction to have been added via addReaction in this session",
+        "removeReaction"
+      );
+    }
+    await reaction.unsend();
   }
   async startTyping(threadId, _status) {
     if (this.local) {
@@ -713,6 +1246,48 @@ var iMessageAdapter = class {
       });
     }, TYPING_DURATION_MS);
   }
+  /**
+   * 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`.
+   */
+  async openDM(userId) {
+    await this.ensureApp();
+    if (!this.app) {
+      throw new NotImplementedError(
+        "openDM requires the adapter to be initialized",
+        "openDM"
+      );
+    }
+    const space = await this.platformSpaces().create(userId);
+    this.cache.rememberSpace(space);
+    return encodeThreadId({
+      chatGuid: space.id,
+      phone: space.phone
+    });
+  }
+  /**
+   * 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.
+   */
+  async markRead(threadId, messageId) {
+    if (this.local) {
+      throw new NotImplementedError(
+        "markRead is not supported in local mode",
+        "markRead"
+      );
+    }
+    const target = await this.resolveMessage(threadId, messageId);
+    if (!target) {
+      throw new NotImplementedError(
+        "markRead requires the target message to have been received in this session",
+        "markRead"
+      );
+    }
+    await target.read();
+  }
   async openModal(triggerId, modal, contextId) {
     if (this.local) {
       throw new NotImplementedError(
@@ -724,14 +1299,14 @@ var iMessageAdapter = class {
       (c) => c.type === "select"
     );
     if (!select) {
-      throw new ValidationError4(
+      throw new ValidationError8(
         "imessage",
         "openModal requires at least one Select child \u2014 iMessage modals map to native polls"
       );
     }
     const labels = select.options.map((o) => o.label);
     if (labels.length < 2 || labels.length > 10) {
-      throw new ValidationError4(
+      throw new ValidationError8(
         "imessage",
         `iMessage polls require between 2 and 10 options, received ${labels.length}`
       );
@@ -813,6 +1388,7 @@ var iMessageAdapter = class {
       return;
     }
     const { message, space } = payload;
+    this.cache.rememberPhone(space.id, space.phone ?? message.space?.phone);
     if (message.direction === "outbound") {
       return;
     }
@@ -887,29 +1463,25 @@ var iMessageAdapter = class {
     );
   }
   /**
-   * 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 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.
+   * Resolve a sendable spectrum-ts `Space` for a thread. Prefers a cached live
+   * Space; otherwise rebuilds it from the chat GUID, passing the sending line
+   * so `space.get` can pick it when multiple lines are configured. Returns
+   * `undefined` when no Space can be obtained.
    */
   async resolveSpace(threadId) {
-    const { chatGuid } = decodeThreadId(threadId);
+    const { chatGuid, phone: threadPhone } = decodeThreadId(threadId);
     const cached = this.cache.getSpace(chatGuid);
     if (cached) {
       return cached;
     }
+    await this.ensureApp();
     if (!this.app) {
       return;
     }
-    const platform = imessage(this.app);
     try {
-      const space = await platform.space.get(chatGuid);
+      const phone = threadPhone ?? this.cache.getPhone(chatGuid);
+      const spaces = this.platformSpaces();
+      const space = phone ? await spaces.get(chatGuid, { phone }) : await spaces.get(chatGuid);
       this.cache.rememberSpace(space);
       return space;
     } catch (error) {
@@ -920,6 +1492,17 @@ var iMessageAdapter = class {
       return;
     }
   }
+  /**
+   * 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.
+   */
+  platformSpaces() {
+    if (!this.app) {
+      throw new Error("Adapter not initialized");
+    }
+    return imessage2(this.app).space;
+  }
   async requireSpace(threadId, action) {
     const space = await this.resolveSpace(threadId);
     if (!space) {
@@ -950,7 +1533,7 @@ function toClientArray(clients) {
 }
 
 // src/factory.ts
-import { ValidationError as ValidationError5 } from "@chat-adapter/shared";
+import { ValidationError as ValidationError9 } from "@chat-adapter/shared";
 import { ConsoleLogger } from "chat";
 function resolveLocalMode(explicit, hasRemoteCreds) {
   if (explicit !== void 0) {
@@ -970,13 +1553,13 @@ function assertRemoteCredentials(creds) {
     return;
   }
   if (!creds.hasServerUrl) {
-    throw new ValidationError5(
+    throw new ValidationError9(
       "imessage",
       "serverUrl is required when local is false. Set IMESSAGE_SERVER_URL (or use IMESSAGE_PROJECT_ID/IMESSAGE_PROJECT_SECRET for Spectrum Cloud), or provide it in config."
     );
   }
   if (!creds.hasApiKey) {
-    throw new ValidationError5(
+    throw new ValidationError9(
       "imessage",
       "apiKey is required when local is false. Set IMESSAGE_API_KEY or provide it in config."
     );
@@ -1016,6 +1599,12 @@ export {
   createiMessageAdapter,
   deriveAddress,
   iMessageAdapter,
-  iMessageFormatConverter
+  iMessageEffect,
+  iMessageFormatConverter,
+  isAppUrl,
+  resolveBackground,
+  resolveEffect,
+  resolveMiniApp,
+  resolveVoice
 };
 //# sourceMappingURL=index.js.map