@photon-ai/chat-adapter-imessage 1.1.0

package/dist/index.js

@@ -0,0 +1,1021 @@
+// src/adapter.ts
+import { extractFiles, ValidationError as ValidationError4 } from "@chat-adapter/shared";
+import { NotImplementedError } from "chat";
+import {
+  poll as pollContent,
+  Spectrum,
+  text as textContent
+} from "spectrum-ts";
+import { imessage } from "spectrum-ts/providers/imessage";
+
+// src/config.ts
+import { ValidationError } from "@chat-adapter/shared";
+var SHARED_PHONE = "shared";
+var URL_SCHEME_RE = /^[a-z][a-z0-9+.-]*:\/\//i;
+function deriveAddress(serverUrl) {
+  const trimmed = serverUrl.trim();
+  const hasScheme = URL_SCHEME_RE.test(trimmed);
+  const url = new URL(hasScheme ? trimmed : `https://${trimmed}`);
+  return `${url.hostname}:${url.port || "443"}`;
+}
+function resolveSpectrumConfig(local, auth) {
+  if (local) {
+    return { providerConfig: { local: true } };
+  }
+  if (auth.projectId && auth.projectSecret) {
+    return {
+      providerConfig: {},
+      projectId: auth.projectId,
+      projectSecret: auth.projectSecret
+    };
+  }
+  if (auth.clients?.length) {
+    return { providerConfig: { clients: auth.clients } };
+  }
+  if (auth.serverUrl && auth.apiKey) {
+    return {
+      providerConfig: {
+        clients: [
+          {
+            address: deriveAddress(auth.serverUrl),
+            token: auth.apiKey,
+            phone: auth.phone ?? SHARED_PHONE
+          }
+        ]
+      }
+    };
+  }
+  throw new ValidationError(
+    "imessage",
+    "Remote mode requires Spectrum Cloud credentials (projectId + projectSecret), explicit clients, or serverUrl + apiKey."
+  );
+}
+
+// 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();
+  maxSpaces;
+  maxMessages;
+  constructor(maxSpaces = DEFAULT_MAX_SPACES, maxMessages = DEFAULT_MAX_MESSAGES) {
+    this.maxSpaces = maxSpaces;
+    this.maxMessages = maxMessages;
+  }
+  /** Cache the Space + Message (and any group sub-items) from one inbound event. */
+  remember(space, message) {
+    this.rememberSpace(space);
+    this.rememberMessage(message);
+    if (message.content.type === "group") {
+      for (const item of message.content.items) {
+        this.rememberMessage(item);
+      }
+    }
+  }
+  rememberSpace(space) {
+    this.spaces.set(space.id, space);
+    evict(this.spaces, this.maxSpaces);
+  }
+  rememberMessage(message) {
+    this.messages.set(message.id, message);
+    evict(this.messages, this.maxMessages);
+  }
+  getSpace(chatGuid) {
+    return this.spaces.get(chatGuid);
+  }
+  getMessage(id) {
+    return this.messages.get(id);
+  }
+};
+function evict(map, max) {
+  if (map.size <= max) {
+    return;
+  }
+  const overflow = map.size - max;
+  let removed = 0;
+  for (const key of map.keys()) {
+    if (removed >= overflow) {
+      break;
+    }
+    map.delete(key);
+    removed += 1;
+  }
+}
+
+// src/internal/gateway.ts
+var MessagePump = class {
+  started = false;
+  iterator = null;
+  source;
+  onMessage;
+  logger;
+  constructor(source, onMessage, logger) {
+    this.source = source;
+    this.onMessage = onMessage;
+    this.logger = logger;
+  }
+  /** Start consuming if not already running. Idempotent. */
+  ensureRunning() {
+    if (this.started) {
+      return;
+    }
+    this.started = true;
+    const iterator = this.source()[Symbol.asyncIterator]();
+    this.iterator = iterator;
+    this.consume(iterator).catch(() => {
+    });
+  }
+  /** Close the underlying stream and stop consuming. */
+  stop() {
+    const iterator = this.iterator;
+    this.iterator = null;
+    this.started = false;
+    iterator?.return?.().catch(() => {
+    });
+  }
+  async consume(iterator) {
+    try {
+      while (true) {
+        const next = await iterator.next();
+        if (next.done) {
+          break;
+        }
+        const [space, message] = next.value;
+        try {
+          await this.onMessage(space, message);
+        } catch (error) {
+          this.logger.error("iMessage inbound handler error", {
+            error: String(error)
+          });
+        }
+      }
+    } catch (error) {
+      this.logger.error("iMessage message stream error", {
+        error: String(error)
+      });
+    } finally {
+      if (this.iterator === iterator) {
+        this.iterator = null;
+        this.started = false;
+      }
+      this.logger.info("iMessage Gateway listener stopped");
+    }
+  }
+};
+
+// src/internal/inbound.ts
+import { Message, parseMarkdown } from "chat";
+
+// src/internal/thread.ts
+import { ValidationError as ValidationError2 } 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(
+      "imessage",
+      `Invalid iMessage thread ID: ${threadId}`
+    );
+  }
+  const chatGuid = threadId.slice(THREAD_PREFIX.length);
+  if (!chatGuid) {
+    throw new ValidationError2(
+      "imessage",
+      `Invalid iMessage thread ID: ${threadId} (empty chat GUID)`
+    );
+  }
+  return { chatGuid };
+}
+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) {
+  const text = extractText(fields.content);
+  return new Message({
+    id: fields.id,
+    threadId: encodeThreadId({ chatGuid: fields.chatGuid }),
+    text,
+    formatted: parseMarkdown(text),
+    author: {
+      userId: fields.senderId,
+      userName: fields.senderId,
+      fullName: fields.senderId,
+      isBot: false,
+      isMe: fields.isOutbound
+    },
+    metadata: { dateSent: fields.timestamp, edited: false },
+    attachments: extractAttachments(fields.content).map((a) => ({
+      type: getAttachmentType(a.mimeType),
+      name: a.name,
+      mimeType: a.mimeType,
+      size: a.size ?? 0
+    })),
+    raw: fields.raw,
+    isMention: isDMChatGuid(fields.chatGuid)
+  });
+}
+function buildChatMessage(message, space) {
+  return buildChatMessageFromFields({
+    id: message.id,
+    chatGuid: space.id,
+    content: message.content,
+    senderId: message.sender?.id ?? "",
+    isOutbound: message.direction === "outbound",
+    timestamp: message.timestamp,
+    raw: message
+  });
+}
+function extractText(content) {
+  switch (content.type) {
+    case "text":
+      return content.text;
+    case "richlink":
+      return String(content.url);
+    case "poll":
+      return content.title;
+    case "group":
+      return content.items.map((item) => extractText(item.content)).filter((t) => t.length > 0).join("\n");
+    default:
+      return "";
+  }
+}
+function extractAttachments(content) {
+  const out = [];
+  const visit = (c) => {
+    if (c.type === "attachment") {
+      out.push({ name: c.name, mimeType: c.mimeType, size: c.size });
+    } else if (c.type === "voice") {
+      const voice = c;
+      out.push({
+        name: voice.name ?? "voice",
+        mimeType: voice.mimeType,
+        size: voice.size
+      });
+    } else if (c.type === "group") {
+      for (const item of c.items) {
+        visit(item.content);
+      }
+    }
+  };
+  visit(content);
+  return out;
+}
+function getAttachmentType(mimeType) {
+  if (!mimeType) {
+    return "file";
+  }
+  if (mimeType.startsWith("image/")) {
+    return "image";
+  }
+  if (mimeType.startsWith("video/")) {
+    return "video";
+  }
+  if (mimeType.startsWith("audio/")) {
+    return "audio";
+  }
+  return "file";
+}
+
+// src/internal/modals.ts
+var DEFAULT_MAX_MODALS = 512;
+var ModalPollRegistry = class {
+  byTitle = /* @__PURE__ */ new Map();
+  maxEntries;
+  constructor(maxEntries = DEFAULT_MAX_MODALS) {
+    this.maxEntries = maxEntries;
+  }
+  register(chatGuid, title, meta) {
+    const key = titleKey(chatGuid, title);
+    this.byTitle.delete(key);
+    this.byTitle.set(key, meta);
+    if (this.byTitle.size > this.maxEntries) {
+      const oldest = this.byTitle.keys().next().value;
+      if (oldest !== void 0) {
+        this.byTitle.delete(oldest);
+      }
+    }
+  }
+  resolveVote(chatGuid, pollTitle, optionTitle) {
+    const meta = this.byTitle.get(titleKey(chatGuid, pollTitle));
+    if (!meta) {
+      return;
+    }
+    const option = meta.options.find((o) => o.label === optionTitle);
+    if (!option) {
+      return;
+    }
+    return { meta, value: option.value };
+  }
+};
+function titleKey(chatGuid, title) {
+  return `${chatGuid}::${title}`;
+}
+
+// src/internal/outbound.ts
+import { ValidationError as ValidationError3 } from "@chat-adapter/shared";
+import { lookup as lookupMimeType } from "mime-types";
+import { attachment } from "spectrum-ts";
+var EMOJI_GLYPHS = {
+  heart: "\u2764\uFE0F",
+  love: "\u2764\uFE0F",
+  thumbs_up: "\u{1F44D}",
+  like: "\u{1F44D}",
+  thumbs_down: "\u{1F44E}",
+  dislike: "\u{1F44E}",
+  laugh: "\u{1F602}",
+  emphasize: "\u203C\uFE0F",
+  exclamation: "\u203C\uFE0F",
+  question: "\u2753"
+};
+function emojiToGlyph(emoji) {
+  const name = typeof emoji === "string" ? emoji : emoji.name;
+  const glyph = EMOJI_GLYPHS[name];
+  if (!glyph) {
+    throw new ValidationError3(
+      "imessage",
+      `Unsupported iMessage tapback: "${name}". Supported: heart, thumbs_up, thumbs_down, laugh, emphasize, question`
+    );
+  }
+  return glyph;
+}
+async function fileToAttachment(file) {
+  const data = file.data;
+  let buffer;
+  if (Buffer.isBuffer(data)) {
+    buffer = data;
+  } else if (data instanceof Blob) {
+    buffer = Buffer.from(await data.arrayBuffer());
+  } else {
+    buffer = Buffer.from(data);
+  }
+  const name = file.filename || "attachment";
+  const mimeType = file.mimeType || lookupMimeType(name) || "application/octet-stream";
+  return attachment(buffer, { name, mimeType });
+}
+
+// src/internal/webhook.ts
+import { createHmac, timingSafeEqual } from "crypto";
+var SPECTRUM_SIGNATURE_HEADER = "x-spectrum-signature";
+var SPECTRUM_TIMESTAMP_HEADER = "x-spectrum-timestamp";
+var SPECTRUM_EVENT_HEADER = "x-spectrum-event";
+var SPECTRUM_MESSAGES_EVENT = "messages";
+var TIMESTAMP_TOLERANCE_SEC = 5 * 60;
+function verifySpectrumSignature(opts) {
+  const { rawBody, secret, signature, timestamp } = opts;
+  if (!(signature && timestamp)) {
+    return { ok: false, status: 400, reason: "missing signature headers" };
+  }
+  const nowSec = opts.now ?? Math.floor(Date.now() / 1e3);
+  const age = Math.abs(nowSec - Number(timestamp));
+  if (!Number.isFinite(age) || age > TIMESTAMP_TOLERANCE_SEC) {
+    return { ok: false, status: 400, reason: "stale or invalid timestamp" };
+  }
+  const expected = `v0=${createHmac("sha256", secret).update(`v0:${timestamp}:${rawBody}`).digest("hex")}`;
+  const a = Buffer.from(expected);
+  const b = Buffer.from(signature);
+  if (a.length !== b.length || !timingSafeEqual(a, b)) {
+    return { ok: false, status: 401, reason: "bad signature" };
+  }
+  return { ok: true };
+}
+function buildChatMessageFromWebhook(message, space) {
+  return buildChatMessageFromFields({
+    id: message.id,
+    chatGuid: space.id,
+    content: message.content,
+    senderId: message.sender?.id ?? "",
+    isOutbound: message.direction === "outbound",
+    timestamp: message.timestamp ? new Date(message.timestamp) : /* @__PURE__ */ new Date(),
+    raw: message
+  });
+}
+
+// src/markdown.ts
+import {
+  BaseFormatConverter,
+  getNodeChildren,
+  getNodeValue,
+  isBlockquoteNode,
+  isCodeNode,
+  isDeleteNode,
+  isEmphasisNode,
+  isInlineCodeNode,
+  isLinkNode,
+  isListItemNode,
+  isListNode,
+  isParagraphNode,
+  isStrongNode,
+  isTextNode,
+  parseMarkdown as parseMarkdown2
+} from "chat";
+var iMessageFormatConverter = class extends BaseFormatConverter {
+  /**
+   * Render an AST to iMessage plain text format.
+   * Strips all formatting markers since iMessage doesn't support rich text via API.
+   */
+  fromAst(ast) {
+    return this.fromAstWithNodeConverter(
+      ast,
+      (node) => this.nodeToPlainText(node)
+    );
+  }
+  /**
+   * Parse iMessage text into an AST.
+   * iMessage sends plain text, so we just parse it as markdown.
+   */
+  toAst(text) {
+    return parseMarkdown2(text);
+  }
+  nodeToPlainText(node) {
+    if (isParagraphNode(node)) {
+      return getNodeChildren(node).map((child) => this.nodeToPlainText(child)).join("");
+    }
+    if (isTextNode(node)) {
+      return node.value;
+    }
+    if (isStrongNode(node) || isEmphasisNode(node) || isDeleteNode(node)) {
+      return getNodeChildren(node).map((child) => this.nodeToPlainText(child)).join("");
+    }
+    if (isInlineCodeNode(node)) {
+      return node.value;
+    }
+    if (isCodeNode(node)) {
+      return node.value;
+    }
+    if (isLinkNode(node)) {
+      const linkText = getNodeChildren(node).map((child) => this.nodeToPlainText(child)).join("");
+      return linkText ? `${linkText} (${node.url})` : node.url;
+    }
+    if (isBlockquoteNode(node)) {
+      return getNodeChildren(node).map((child) => `> ${this.nodeToPlainText(child)}`).join("\n");
+    }
+    if (isListNode(node)) {
+      return getNodeChildren(node).map((item, i) => {
+        const prefix = node.ordered ? `${i + 1}.` : "-";
+        const content = getNodeChildren(item).map((child) => this.nodeToPlainText(child)).join("");
+        return `${prefix} ${content}`;
+      }).join("\n");
+    }
+    if (isListItemNode(node)) {
+      return getNodeChildren(node).map((child) => this.nodeToPlainText(child)).join("");
+    }
+    if (node.type === "break") {
+      return "\n";
+    }
+    if (node.type === "thematicBreak") {
+      return "---";
+    }
+    const children = getNodeChildren(node);
+    if (children.length > 0) {
+      return children.map((child) => this.nodeToPlainText(child)).join("");
+    }
+    return getNodeValue(node);
+  }
+};
+
+// src/adapter.ts
+var TYPING_DURATION_MS = 3e3;
+var iMessageAdapter = class {
+  name = "imessage";
+  userName = "";
+  local;
+  serverUrl;
+  apiKey;
+  projectId;
+  projectSecret;
+  clients;
+  phone;
+  webhookSecret;
+  /** The spectrum-ts instance — null until `initialize()` runs. */
+  app = null;
+  chat = null;
+  logger;
+  formatConverter = new iMessageFormatConverter();
+  cache = new InboundCache();
+  modals = new ModalPollRegistry();
+  gatewayOptions;
+  pump = null;
+  constructor(config) {
+    if (config.local && process.platform !== "darwin") {
+      throw new ValidationError4(
+        "imessage",
+        "iMessage adapter local mode requires macOS. Current platform: " + process.platform
+      );
+    }
+    this.local = config.local;
+    this.logger = config.logger;
+    this.serverUrl = config.serverUrl;
+    this.apiKey = config.apiKey;
+    if (!config.local) {
+      this.projectId = config.projectId;
+      this.projectSecret = config.projectSecret;
+      this.phone = config.phone;
+      this.clients = toClientArray(config.clients);
+      this.webhookSecret = config.webhookSecret?.trim();
+    }
+  }
+  async initialize(chat) {
+    this.chat = chat;
+    const { providerConfig, projectId, projectSecret } = resolveSpectrumConfig(
+      this.local,
+      {
+        apiKey: this.apiKey,
+        clients: this.clients,
+        phone: this.phone,
+        projectId: this.projectId,
+        projectSecret: this.projectSecret,
+        serverUrl: this.serverUrl
+      }
+    );
+    const providers = [imessage.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";
+    } else if (projectId) {
+      mode = "cloud";
+    } else {
+      mode = "self-host";
+    }
+    this.logger.info("iMessage adapter initialized", {
+      local: this.local,
+      mode
+    });
+  }
+  /**
+   * Handle a Spectrum Cloud webhook delivery (signed JSON `messages` event).
+   *
+   * Verifies the `X-Spectrum-Signature` HMAC, then routes the message into the
+   * Chat SDK. Webhook deliveries are receive-only: a delivered thread has no
+   * live spectrum-ts `Space`, so replying/reacting still requires the gateway
+   * stream (see `startGatewayListener`).
+   *
+   * @see https://photon.codes/docs/webhooks/overview
+   */
+  async handleWebhook(request, options) {
+    if (!this.chat) {
+      return new Response("Chat instance not initialized", { status: 500 });
+    }
+    if (this.local) {
+      return new Response(
+        "Webhooks require remote (cloud) mode \u2014 local mode receives via startGatewayListener()",
+        { status: 501 }
+      );
+    }
+    if (!this.webhookSecret) {
+      return new Response(
+        "Webhook signing secret not configured (set IMESSAGE_WEBHOOK_SECRET)",
+        { status: 500 }
+      );
+    }
+    const rawBody = await request.text();
+    const verdict = verifySpectrumSignature({
+      secret: this.webhookSecret,
+      signature: request.headers.get(SPECTRUM_SIGNATURE_HEADER),
+      timestamp: request.headers.get(SPECTRUM_TIMESTAMP_HEADER),
+      rawBody
+    });
+    if (!verdict.ok) {
+      this.logger.warn("Rejected iMessage webhook delivery", {
+        reason: verdict.reason
+      });
+      return new Response(verdict.reason, { status: verdict.status });
+    }
+    const event = request.headers.get(SPECTRUM_EVENT_HEADER);
+    if (event && event !== SPECTRUM_MESSAGES_EVENT) {
+      return new Response(null, { status: 204 });
+    }
+    let payload;
+    try {
+      payload = JSON.parse(rawBody);
+    } catch {
+      return new Response("Invalid JSON body", { status: 400 });
+    }
+    if (payload.event !== SPECTRUM_MESSAGES_EVENT || !(payload.message && payload.space)) {
+      return new Response(null, { status: 204 });
+    }
+    this.routeWebhookMessage(payload, options);
+    return new Response(null, { status: 200 });
+  }
+  async postMessage(threadId, message) {
+    const space = await this.requireSpace(threadId, "postMessage");
+    const body = this.formatConverter.renderPostable(message);
+    const files = extractFiles(message);
+    let first;
+    if (body && body.trim().length > 0) {
+      first = await space.send(textContent(body)) ?? first;
+    }
+    for (const file of files) {
+      const sent = await space.send(await fileToAttachment(file)) ?? void 0;
+      first ??= sent;
+    }
+    if (!first) {
+      throw new ValidationError4(
+        "imessage",
+        "postMessage requires non-empty text or at least one attachment"
+      );
+    }
+    return { id: first.id, threadId, raw: first };
+  }
+  async editMessage(threadId, messageId, message) {
+    if (this.local) {
+      throw new NotImplementedError(
+        "editMessage is not supported in local mode",
+        "editMessage"
+      );
+    }
+    const target = await this.resolveMessage(threadId, messageId);
+    if (!target) {
+      throw new NotImplementedError(
+        "editMessage requires the original message to have been received in this session",
+        "editMessage"
+      );
+    }
+    await target.edit(
+      textContent(this.formatConverter.renderPostable(message))
+    );
+    return { id: messageId, threadId, raw: target };
+  }
+  async deleteMessage(_threadId, _messageId) {
+    throw new NotImplementedError(
+      "deleteMessage is not implemented",
+      "deleteMessage"
+    );
+  }
+  parseMessage(raw) {
+    const message = raw;
+    return buildChatMessage(message, message.space);
+  }
+  async fetchMessages(_threadId, _options) {
+    throw new NotImplementedError(
+      "fetchMessages (message history) is not supported by spectrum-ts",
+      "fetchMessages"
+    );
+  }
+  async fetchThread(_threadId) {
+    throw new NotImplementedError(
+      "fetchThread (chat info) is not supported by spectrum-ts",
+      "fetchThread"
+    );
+  }
+  channelIdFromThreadId(threadId) {
+    return threadId;
+  }
+  async addReaction(threadId, messageId, emoji) {
+    if (this.local) {
+      throw new NotImplementedError(
+        "addReaction is not supported in local mode",
+        "addReaction"
+      );
+    }
+    const glyph = emojiToGlyph(emoji);
+    const target = await this.resolveMessage(threadId, messageId);
+    if (!target) {
+      throw new NotImplementedError(
+        "addReaction requires the target message to have been received in this session",
+        "addReaction"
+      );
+    }
+    await target.react(glyph);
+  }
+  async removeReaction(_threadId, _messageId, _emoji) {
+    throw new NotImplementedError(
+      "removeReaction is not supported (spectrum-ts has no reaction-removal API)",
+      "removeReaction"
+    );
+  }
+  async startTyping(threadId, _status) {
+    if (this.local) {
+      throw new NotImplementedError(
+        "startTyping is not supported in local mode",
+        "startTyping"
+      );
+    }
+    const space = await this.requireSpace(threadId, "startTyping");
+    await space.startTyping();
+    setTimeout(() => {
+      space.stopTyping().catch(() => {
+      });
+    }, TYPING_DURATION_MS);
+  }
+  async openModal(triggerId, modal, contextId) {
+    if (this.local) {
+      throw new NotImplementedError(
+        "openModal is not supported in local mode",
+        "openModal"
+      );
+    }
+    const select = modal.children.find(
+      (c) => c.type === "select"
+    );
+    if (!select) {
+      throw new ValidationError4(
+        "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(
+        "imessage",
+        `iMessage polls require between 2 and 10 options, received ${labels.length}`
+      );
+    }
+    const { chatGuid } = decodeThreadId(triggerId);
+    const space = await this.requireSpace(triggerId, "openModal");
+    const sent = await space.send(pollContent(modal.title, labels));
+    const viewId = sent?.id ?? `poll-${Date.now()}`;
+    this.modals.register(chatGuid, modal.title, {
+      viewId,
+      callbackId: modal.callbackId,
+      selectId: select.id,
+      options: select.options,
+      contextId,
+      privateMetadata: modal.privateMetadata
+    });
+    return { viewId };
+  }
+  renderFormatted(content) {
+    return this.formatConverter.fromAst(content);
+  }
+  encodeThreadId(platformData) {
+    return encodeThreadId(platformData);
+  }
+  decodeThreadId(threadId) {
+    return decodeThreadId(threadId);
+  }
+  isDM(threadId) {
+    return isDMChatGuid(decodeThreadId(threadId).chatGuid);
+  }
+  async startGatewayListener(options, durationMs = 18e4, abortSignal) {
+    if (!this.chat) {
+      return new Response("Chat instance not initialized", { status: 500 });
+    }
+    if (!options.waitUntil) {
+      return new Response("waitUntil not provided", { status: 500 });
+    }
+    if (!(this.app && this.pump)) {
+      return new Response("Adapter not initialized", { status: 500 });
+    }
+    this.logger.info("Starting iMessage Gateway listener", {
+      durationMs,
+      mode: this.local ? "local" : "remote"
+    });
+    this.gatewayOptions = options;
+    this.pump.ensureRunning();
+    const listenerPromise = new Promise((resolve) => {
+      const timeout = setTimeout(resolve, durationMs);
+      if (abortSignal) {
+        const onAbort = () => {
+          this.logger.info("iMessage Gateway listener received abort signal");
+          clearTimeout(timeout);
+          this.pump?.stop();
+          resolve();
+        };
+        if (abortSignal.aborted) {
+          onAbort();
+          return;
+        }
+        abortSignal.addEventListener("abort", onAbort, { once: true });
+      }
+    });
+    options.waitUntil(listenerPromise);
+    return new Response(
+      JSON.stringify({
+        status: "listening",
+        durationMs,
+        mode: this.local ? "local" : "remote",
+        message: `Gateway listener started, will run for ${durationMs / 1e3} seconds`
+      }),
+      {
+        status: 200,
+        headers: { "Content-Type": "application/json" }
+      }
+    );
+  }
+  routeWebhookMessage(payload, options) {
+    if (!this.chat) {
+      return;
+    }
+    const { message, space } = payload;
+    if (message.direction === "outbound") {
+      return;
+    }
+    if (message.content?.type === "reaction") {
+      return;
+    }
+    const chatMessage = buildChatMessageFromWebhook(message, space);
+    this.chat.processMessage(this, chatMessage.threadId, chatMessage, options);
+  }
+  async routeInbound(space, message, options) {
+    if (!this.chat) {
+      return;
+    }
+    this.cache.remember(space, message);
+    const contentType = message.content.type;
+    if (contentType === "poll_option") {
+      this.handlePollOption(space, message, options);
+      return;
+    }
+    if (contentType === "reaction") {
+      return;
+    }
+    if (message.direction === "outbound") {
+      return;
+    }
+    const chatMessage = buildChatMessage(message, space);
+    this.chat.processMessage(this, chatMessage.threadId, chatMessage, options);
+  }
+  handlePollOption(space, message, options) {
+    if (!this.chat) {
+      return;
+    }
+    const content = message.content;
+    if (content.type !== "poll_option") {
+      return;
+    }
+    if (!content.selected) {
+      return;
+    }
+    const resolved = this.modals.resolveVote(
+      space.id,
+      content.poll.title,
+      content.option.title
+    );
+    if (!resolved) {
+      this.logger.debug("Poll vote did not match a known modal, skipping", {
+        title: content.poll.title,
+        option: content.option.title
+      });
+      return;
+    }
+    const { meta, value } = resolved;
+    const handle = message.sender?.id ?? "";
+    this.chat.processModalSubmit(
+      {
+        adapter: this,
+        callbackId: meta.callbackId,
+        privateMetadata: meta.privateMetadata,
+        viewId: meta.viewId,
+        user: {
+          userId: handle,
+          userName: handle,
+          fullName: handle,
+          isBot: false,
+          isMe: false
+        },
+        values: { [meta.selectId]: value },
+        raw: message
+      },
+      meta.contextId,
+      options
+    );
+  }
+  /**
+   * Resolve a sendable spectrum-ts `Space` for a thread.
+   *
+   * Prefers a live `Space` cached from the inbound stream (correct sending
+   * line, no extra round-trip). On a miss — e.g. a webhook-only deployment, or
+   * a cold send — it reconstructs the Space over gRPC via
+   * `imessage(app).space([address])`. Only DMs can be rebuilt from a chatGuid:
+   * the resolver derives them from the peer address, whereas an unseen group
+   * has no by-id resolver (passing participants would create a *new* chat).
+   * Returns `undefined` when no Space can be obtained.
+   */
+  async resolveSpace(threadId) {
+    const { chatGuid } = decodeThreadId(threadId);
+    const cached = this.cache.getSpace(chatGuid);
+    if (cached) {
+      return cached;
+    }
+    if (!this.app || this.local || !isDMChatGuid(chatGuid)) {
+      return;
+    }
+    const address = dmAddressFromChatGuid(chatGuid);
+    if (!address) {
+      return;
+    }
+    const platform = imessage(this.app);
+    const space = await platform.space([address]);
+    this.cache.rememberSpace(space);
+    return 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
+      );
+    }
+    return space;
+  }
+  async resolveMessage(threadId, messageId) {
+    const cached = this.cache.getMessage(messageId);
+    if (cached) {
+      return cached;
+    }
+    const space = await this.resolveSpace(threadId);
+    if (!space) {
+      return;
+    }
+    return await space.getMessage(messageId) ?? void 0;
+  }
+};
+function toClientArray(clients) {
+  if (!clients) {
+    return;
+  }
+  return Array.isArray(clients) ? clients : [clients];
+}
+
+// src/factory.ts
+import { ValidationError as ValidationError5 } from "@chat-adapter/shared";
+import { ConsoleLogger } from "chat";
+function resolveLocalMode(explicit, hasRemoteCreds) {
+  if (explicit !== void 0) {
+    return explicit;
+  }
+  const env = process.env.IMESSAGE_LOCAL;
+  if (env === "false") {
+    return false;
+  }
+  if (env === void 0) {
+    return !hasRemoteCreds;
+  }
+  return true;
+}
+function assertRemoteCredentials(creds) {
+  if (creds.hasCloud || creds.hasClients) {
+    return;
+  }
+  if (!creds.hasServerUrl) {
+    throw new ValidationError5(
+      "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(
+      "imessage",
+      "apiKey is required when local is false. Set IMESSAGE_API_KEY or provide it in config."
+    );
+  }
+}
+function createiMessageAdapter(config) {
+  const logger = config?.logger ?? new ConsoleLogger("info").child("imessage");
+  const projectId = config?.projectId ?? process.env.IMESSAGE_PROJECT_ID;
+  const projectSecret = config?.projectSecret ?? process.env.IMESSAGE_PROJECT_SECRET;
+  const clients = config?.clients;
+  const serverUrl = (config?.serverUrl ?? process.env.IMESSAGE_SERVER_URL)?.trim();
+  const apiKey = (config?.apiKey ?? process.env.IMESSAGE_API_KEY)?.trim();
+  const phone = config?.phone ?? process.env.IMESSAGE_PHONE;
+  const webhookSecret = (config?.webhookSecret ?? process.env.IMESSAGE_WEBHOOK_SECRET)?.trim();
+  const hasClients = Array.isArray(clients) ? clients.length > 0 : Boolean(clients);
+  const hasCloud = Boolean(projectId && projectSecret);
+  const hasServerUrl = Boolean(serverUrl);
+  const hasApiKey = Boolean(apiKey);
+  const hasRemoteCreds = hasCloud || hasClients || hasServerUrl && hasApiKey;
+  if (resolveLocalMode(config?.local, hasRemoteCreds)) {
+    return new iMessageAdapter({ local: true, logger, serverUrl, apiKey });
+  }
+  assertRemoteCredentials({ hasApiKey, hasClients, hasCloud, hasServerUrl });
+  return new iMessageAdapter({
+    local: false,
+    logger,
+    projectId,
+    projectSecret,
+    clients,
+    serverUrl,
+    apiKey,
+    phone,
+    webhookSecret
+  });
+}
+export {
+  createiMessageAdapter,
+  deriveAddress,
+  iMessageAdapter,
+  iMessageFormatConverter
+};
+//# sourceMappingURL=index.js.map