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

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,44 @@ 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();
+  /**
+   * 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) {
@@ -87,7 +213,24 @@ var InboundCache = class {
   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,21 +311,21 @@ 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:";
 function encodeThreadId(platformData) {
   return `${THREAD_PREFIX}${platformData.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);
   if (!chatGuid) {
-    throw new ValidationError2(
+    throw new ValidationError4(
       "imessage",
       `Invalid iMessage thread ID: ${threadId} (empty chat GUID)`
     );
@@ -192,11 +335,6 @@ function decodeThreadId(threadId) {
 function isDMChatGuid(chatGuid) {
   return chatGuid.includes(";-;");
 }
-var DM_SEPARATOR = ";-;";
-function dmAddressFromChatGuid(chatGuid) {
-  const idx = chatGuid.indexOf(DM_SEPARATOR);
-  return idx === -1 ? "" : chatGuid.slice(idx + DM_SEPARATOR.length);
-}
 
 // src/internal/inbound.ts
 function buildChatMessageFromFields(fields) {
@@ -322,8 +460,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",
@@ -341,7 +479,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`
     );
@@ -359,7 +497,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 });
 }
 
@@ -416,7 +554,8 @@ import {
   isParagraphNode,
   isStrongNode,
   isTextNode,
-  parseMarkdown as parseMarkdown2
+  parseMarkdown as parseMarkdown2,
+  stringifyMarkdown
 } from "chat";
 var iMessageFormatConverter = class extends BaseFormatConverter {
   /**
@@ -436,6 +575,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("");
@@ -483,6 +646,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 {
@@ -507,7 +833,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
       );
@@ -537,7 +863,7 @@ 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(
       () => {
@@ -566,9 +892,9 @@ var iMessageAdapter = class {
    * 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
    */
@@ -617,26 +943,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(
@@ -651,21 +1103,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",
@@ -696,13 +1169,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) {
@@ -718,6 +1205,44 @@ 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) {
+    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 });
+  }
+  /**
+   * 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(
@@ -729,14 +1254,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}`
       );
@@ -896,11 +1421,12 @@ var iMessageAdapter = class {
    *
    * 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.
    */
   async resolveSpace(threadId) {
     const { chatGuid } = decodeThreadId(threadId);
@@ -908,23 +1434,37 @@ var iMessageAdapter = class {
     if (cached) {
       return cached;
     }
-    if (!this.app || this.local || !isDMChatGuid(chatGuid)) {
+    if (!this.app) {
       return;
     }
-    const address = dmAddressFromChatGuid(chatGuid);
-    if (!address) {
+    try {
+      const space = await this.platformSpaces().get(chatGuid);
+      this.cache.rememberSpace(space);
+      return space;
+    } catch (error) {
+      this.logger.debug("Could not rebuild Space from chat GUID", {
+        chatGuid,
+        error: String(error)
+      });
       return;
     }
-    const platform = imessage(this.app);
-    const space = await platform.space([address]);
-    this.cache.rememberSpace(space);
-    return space;
+  }
+  /**
+   * 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) {
       throw new NotImplementedError(
-        `${action} requires a DM thread (rebuilt from its address) or a group received in this session; spectrum-ts cannot reconstruct an unseen group chat from its id. Respond within a received message's thread instead.`,
+        `${action} could not resolve this thread. With multiple iMessage lines configured, spectrum-ts needs the chat's sending line to rebuild an unseen thread. Respond within a received message's thread instead.`,
         action
       );
     }
@@ -950,7 +1490,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 +1510,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 +1556,12 @@ export {
   createiMessageAdapter,
   deriveAddress,
   iMessageAdapter,
-  iMessageFormatConverter
+  iMessageEffect,
+  iMessageFormatConverter,
+  isAppUrl,
+  resolveBackground,
+  resolveEffect,
+  resolveMiniApp,
+  resolveVoice
 };
 //# sourceMappingURL=index.js.map