@elizaos/plugin-imessage 2.0.0-alpha.9 → 2.0.0-beta.1

package/README.md

@@ -0,0 +1,184 @@
+# @elizaos/plugin-imessage
+
+iMessage plugin for ElizaOS agents. Enables chat integration with Apple's iMessage on macOS.
+
+**Note: This plugin only works on macOS systems.**
+
+## Features
+
+- **Send Messages**: Send text messages via iMessage
+- **Direct & Group Chats**: Support for direct messages and group conversations
+- **Attachments**: Send media attachments (via CLI tool)
+- **Message Polling**: Receive incoming messages via polling
+- **Policy Controls**: Configure DM and group policies
+
+## Requirements
+
+- **macOS**: This plugin only works on macOS
+- **Messages App Access**: Full Disk Access permission may be required
+- **Optional CLI Tool**: For enhanced functionality, use an iMessage CLI tool
+
+## Installation
+
+```bash
+# npm
+npm install @elizaos/plugin-imessage
+
+# bun
+bun add @elizaos/plugin-imessage
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `IMESSAGE_CLI_PATH` | Path to iMessage CLI tool | No |
+| `IMESSAGE_DB_PATH` | Path to iMessage database | No |
+| `IMESSAGE_POLL_INTERVAL_MS` | Polling interval in ms | No |
+| `IMESSAGE_DM_POLICY` | DM policy: open, pairing, allowlist, disabled | No |
+| `IMESSAGE_GROUP_POLICY` | Group policy: open, allowlist, disabled | No |
+| `IMESSAGE_ALLOW_FROM` | Comma-separated handles for allowlist | No |
+| `IMESSAGE_ENABLED` | Enable/disable the plugin | No |
+
+### Agent Configuration
+
+```json
+{
+  "plugins": ["@elizaos/plugin-imessage"],
+  "pluginParameters": {
+    "IMESSAGE_DM_POLICY": "pairing",
+    "IMESSAGE_GROUP_POLICY": "allowlist",
+    "IMESSAGE_POLL_INTERVAL_MS": "5000"
+  }
+}
+```
+
+## Setup
+
+### Permissions
+
+1. Open System Preferences > Security & Privacy > Privacy
+2. Grant Full Disk Access to:
+   - Terminal (or your terminal app)
+   - Your Node.js/Python executable
+3. Allow Messages app to be controlled via AppleScript
+
+### CLI Tool (Optional)
+
+For enhanced functionality, you can use an iMessage CLI tool like `imsg`:
+
+```bash
+# Install a CLI tool (example)
+brew install imessage-cli
+
+# Configure the path
+IMESSAGE_CLI_PATH=/usr/local/bin/imsg
+```
+
+## Usage
+
+### Actions
+
+iMessage sending is exposed through the canonical message connector action. Use
+`source: "imessage"` when a request needs to target iMessage explicitly.
+
+| Primary action | Operation | Description |
+|----------------|-----------|-------------|
+| `MESSAGE` | `send` | Send a text message to a phone number, email, contact, or chat |
+
+### Providers
+
+iMessage does not register standalone planner providers. Chat and contact
+context is exposed through the iMessage message connector hooks.
+
+## How It Works
+
+The plugin uses two methods to interact with iMessage:
+
+1. **AppleScript** (default): Uses macOS's built-in scripting support to send messages through the Messages app
+2. **CLI Tool** (optional): Uses a command-line tool for more features
+
+### AppleScript Method
+
+```applescript
+tell application "Messages"
+  set targetService to 1st account whose service type = iMessage
+  set targetBuddy to participant "+1234567890" of targetService
+  send "Hello!" to targetBuddy
+end tell
+```
+
+## Message Targets
+
+iMessage supports multiple target types:
+
+- **Phone Numbers**: `+1234567890`, `1234567890`
+- **Email Addresses**: `user@example.com`
+- **Chat IDs**: `chat_id:UUID` (for existing chats)
+
+## Policies
+
+### DM Policies
+
+| Policy | Description |
+|--------|-------------|
+| `open` | Accept DMs from anyone |
+| `pairing` | Accept DMs and remember senders |
+| `allowlist` | Only accept from IMESSAGE_ALLOW_FROM list |
+| `disabled` | Don't accept any DMs |
+
+### Group Policies
+
+| Policy | Description |
+|--------|-------------|
+| `open` | Respond to anyone in groups |
+| `allowlist` | Only respond to allowed users |
+| `disabled` | Don't respond in groups |
+
+## Limitations
+
+- **macOS Only**: iMessage doesn't have an official API and only works on macOS
+- **No Official API**: Relies on AppleScript or CLI tools
+- **Permissions**: Requires Full Disk Access and Automation permissions
+- **Rate Limits**: Apple may throttle excessive automation
+
+## Development
+
+### Building
+
+```bash
+cd typescript && npm run build
+```
+
+### Testing
+
+Testing requires a macOS environment with Messages app configured:
+
+```bash
+npm test
+```
+
+## Troubleshooting
+
+### "Cannot access Messages app"
+
+1. Ensure Full Disk Access is granted
+2. Ensure Automation permissions are granted
+3. Try opening Messages app manually first
+
+### "Service not available"
+
+1. Check that you're running on macOS
+2. Verify the Messages app is installed and configured
+
+### Messages not sending
+
+1. Check that iMessage is signed in and working
+2. Verify the recipient has iMessage enabled
+3. Check for rate limiting (try again later)
+
+## License
+
+MIT

package/auto-enable.ts

@@ -0,0 +1,21 @@
+// Auto-enable check for @elizaos/plugin-imessage.
+//
+// Plugin manifest entry-point — referenced by package.json's
+// `elizaos.plugin.autoEnableModule`. Keep this module light: env reads only,
+// no service init, no transitive imports of the full plugin runtime. The
+// auto-enable engine loads dozens of these per boot.
+import type { PluginAutoEnableContext } from "@elizaos/core";
+
+/** Enable when an `imessage` connector block is present and not explicitly disabled. */
+export function shouldEnable(ctx: PluginAutoEnableContext): boolean {
+  const c = (ctx.config?.connectors as Record<string, unknown> | undefined)
+    ?.imessage;
+  if (!c || typeof c !== "object") return false;
+  const config = c as Record<string, unknown>;
+  if (config.enabled === false) return false;
+  // The full per-connector field check (chat.db / Messages.app integration)
+  // lives in the central engine's isConnectorConfigured. We delegate to a
+  // simple "block present + not explicitly disabled" check here; the central
+  // engine's stricter check remains as a fallback during migration.
+  return true;
+}

package/dist/api/bluebubbles-routes.d.ts

@@ -0,0 +1,10 @@
+import type http from "node:http";
+import type { RouteHelpers } from "./imessage-routes.js";
+export interface BlueBubblesRouteState {
+    runtime?: {
+        getService(type: string): unknown;
+    };
+}
+export declare function resolveBlueBubblesWebhookPath(state: BlueBubblesRouteState): string;
+export declare function handleBlueBubblesRoute(req: http.IncomingMessage, res: http.ServerResponse, pathname: string, method: string, state: BlueBubblesRouteState, helpers: RouteHelpers): Promise<boolean>;
+//# sourceMappingURL=bluebubbles-routes.d.ts.map

package/dist/api/bluebubbles-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bluebubbles-routes.d.ts","sourceRoot":"","sources":["../../src/api/bluebubbles-routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AA0BzD,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE;QACR,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;KACnC,CAAC;CACH;AAUD,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,qBAAqB,GAAG,MAAM,CAOlF;AAED,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,IAAI,CAAC,eAAe,EACzB,GAAG,EAAE,IAAI,CAAC,cAAc,EACxB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,qBAAqB,EAC5B,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,OAAO,CAAC,CAkJlB"}

package/dist/api/bluebubbles-routes.js

@@ -0,0 +1,132 @@
+const BLUEBUBBLES_SERVICE_NAME = "bluebubbles";
+const DEFAULT_WEBHOOK_PATH = "/webhooks/bluebubbles";
+const MAX_BODY_BYTES = 1_048_576;
+function resolveService(state) {
+    if (!state.runtime) {
+        return null;
+    }
+    const raw = state.runtime.getService(BLUEBUBBLES_SERVICE_NAME);
+    return raw ?? null;
+}
+export function resolveBlueBubblesWebhookPath(state) {
+    const service = resolveService(state);
+    const configuredPath = service?.getWebhookPath();
+    if (typeof configuredPath === "string" && configuredPath.trim().length > 0) {
+        return configuredPath.trim();
+    }
+    return DEFAULT_WEBHOOK_PATH;
+}
+export async function handleBlueBubblesRoute(req, res, pathname, method, state, helpers) {
+    const webhookPath = resolveBlueBubblesWebhookPath(state);
+    const isWebhookPath = pathname === webhookPath;
+    const isApiPath = pathname.startsWith("/api/bluebubbles");
+    if (!isWebhookPath && !isApiPath) {
+        return false;
+    }
+    if (method === "GET" && pathname === "/api/bluebubbles/status") {
+        const service = resolveService(state);
+        if (!service) {
+            helpers.json(res, {
+                available: false,
+                connected: false,
+                webhookPath,
+                reason: "bluebubbles service not registered",
+            });
+            return true;
+        }
+        helpers.json(res, {
+            available: true,
+            connected: service.isConnected(),
+            webhookPath,
+        });
+        return true;
+    }
+    if (method === "GET" && pathname === "/api/bluebubbles/chats") {
+        const service = resolveService(state);
+        if (!service) {
+            helpers.error(res, "bluebubbles service not registered", 503);
+            return true;
+        }
+        const client = service.getClient();
+        if (!client) {
+            helpers.error(res, "bluebubbles client not available", 503);
+            return true;
+        }
+        const url = new URL(req.url ?? pathname, "http://localhost");
+        const limit = Math.min(Math.max(1, Number.parseInt(url.searchParams.get("limit") ?? "100", 10) || 100), 500);
+        const offset = Math.max(0, Number.parseInt(url.searchParams.get("offset") ?? "0", 10) || 0);
+        try {
+            const chats = await client.listChats(limit, offset);
+            helpers.json(res, { chats, count: chats.length, limit, offset });
+        }
+        catch (error) {
+            helpers.error(res, `failed to read bluebubbles chats: ${error instanceof Error ? error.message : String(error)}`, 500);
+        }
+        return true;
+    }
+    if (method === "GET" && pathname === "/api/bluebubbles/messages") {
+        const service = resolveService(state);
+        if (!service) {
+            helpers.error(res, "bluebubbles service not registered", 503);
+            return true;
+        }
+        const client = service.getClient();
+        if (!client) {
+            helpers.error(res, "bluebubbles client not available", 503);
+            return true;
+        }
+        const url = new URL(req.url ?? pathname, "http://localhost");
+        const chatGuid = (url.searchParams.get("chatGuid") ?? "").trim();
+        if (!chatGuid) {
+            helpers.error(res, "chatGuid query parameter is required", 400);
+            return true;
+        }
+        const limit = Math.min(Math.max(1, Number.parseInt(url.searchParams.get("limit") ?? "50", 10) || 50), 500);
+        const offset = Math.max(0, Number.parseInt(url.searchParams.get("offset") ?? "0", 10) || 0);
+        try {
+            const messages = await client.getMessages(chatGuid, limit, offset);
+            helpers.json(res, {
+                chatGuid,
+                messages,
+                count: messages.length,
+                limit,
+                offset,
+            });
+        }
+        catch (error) {
+            helpers.error(res, `failed to read bluebubbles messages: ${error instanceof Error ? error.message : String(error)}`, 500);
+        }
+        return true;
+    }
+    if (method === "POST" && isWebhookPath) {
+        const service = resolveService(state);
+        if (!service) {
+            helpers.error(res, "bluebubbles service not registered", 503);
+            return true;
+        }
+        const payload = await helpers.readJsonBody(req, res, {
+            maxBytes: MAX_BODY_BYTES,
+        });
+        if (!payload) {
+            return true;
+        }
+        if (typeof payload.type !== "string" ||
+            !payload.type.trim() ||
+            typeof payload.data !== "object" ||
+            payload.data === null ||
+            Array.isArray(payload.data)) {
+            helpers.error(res, "invalid BlueBubbles webhook payload", 400);
+            return true;
+        }
+        try {
+            await service.handleWebhook(payload);
+            helpers.json(res, { ok: true });
+        }
+        catch (error) {
+            helpers.error(res, `failed to handle bluebubbles webhook: ${error instanceof Error ? error.message : String(error)}`, 500);
+        }
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=bluebubbles-routes.js.map

package/dist/api/bluebubbles-routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bluebubbles-routes.js","sourceRoot":"","sources":["../../src/api/bluebubbles-routes.ts"],"names":[],"mappings":"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"}

package/dist/api/imessage-routes.d.ts

@@ -0,0 +1,80 @@
+/**
+ * iMessage connector HTTP routes.
+ *
+ * Exposes the @elizaos/plugin-imessage service state through Eliza's
+ * HTTP API so downstream UI layers (the dashboard, a future CLI, third-
+ * party integrations) can read and write against the macOS Messages.app
+ * world without each client having to go straight to chat.db or to
+ * AppleScript.
+ *
+ * Routes served (all under `/api/imessage`):
+ *
+ *   GET    /api/imessage/status         service health + cursor + counts
+ *   GET    /api/imessage/messages       recent messages from chat.db
+ *   GET    /api/imessage/chats          list of chats (DMs + groups)
+ *   GET    /api/imessage/contacts       every contact with full detail
+ *   POST   /api/imessage/contacts       create a new contact
+ *   PATCH  /api/imessage/contacts/:id   update an existing contact
+ *   DELETE /api/imessage/contacts/:id   delete a contact
+ *
+ * Each handler pulls the IMessageService instance off the runtime via
+ * `runtime.getService("imessage")` and calls the public methods added
+ * in the plugin's patched branch. If the service isn't registered (the
+ * plugin isn't enabled, Eliza booted before it was loaded, etc.) we
+ * return 503 with a structured reason so the UI can render an
+ * informative empty state.
+ *
+ * Write endpoints (POST/PATCH/DELETE on contacts) touch the real macOS
+ * Contacts.app and will trigger a one-time TCC permission prompt the
+ * first time they fire. That prompt targets whichever process ran the
+ * osascript child; in Eliza's case that's `bun`/`node`. Once granted
+ * the permission is persistent across restarts.
+ */
+import type http from "node:http";
+/**
+ * Minimal structural copy of the agent's RouteHelpers / RouteRequestMeta
+ * surface, inlined here so this file can live inside @elizaos/plugin-imessage
+ * without taking a build-time dependency on @elizaos/agent.
+ */
+export interface ReadJsonBodyOptions {
+    maxBytes?: number;
+    requireObject?: boolean;
+    readErrorStatus?: number;
+    nonObjectStatus?: number;
+    parseErrorStatus?: number;
+    readErrorMessage?: string;
+    nonObjectMessage?: string;
+    parseErrorMessage?: string;
+}
+export interface RouteRequestMeta {
+    req: http.IncomingMessage;
+    res: http.ServerResponse;
+    method: string;
+    pathname: string;
+}
+export interface RouteHelpers {
+    json: (res: http.ServerResponse, data: unknown, status?: number) => void;
+    error: (res: http.ServerResponse, message: string, status?: number) => void;
+    readJsonBody: <T extends object>(req: http.IncomingMessage, res: http.ServerResponse, options?: ReadJsonBodyOptions) => Promise<T | null>;
+}
+export interface IMessageRouteState {
+    /**
+     * The running AgentRuntime (or a test stub). Typed loosely as
+     * `unknown` so this route file doesn't re-declare core's stricter
+     * generic getService signature — we narrow the result inside
+     * resolveService via an unknown cast. Optional so route files
+     * tolerate the boot window where the runtime hasn't finished
+     * registering services yet.
+     */
+    runtime?: {
+        getService(type: string): unknown;
+    };
+}
+/**
+ * Route handler entry point. Returns `true` when a route matched and
+ * the response has been written; returns `false` so the caller can
+ * continue to other route handlers (mirrors the handleWhatsAppRoute /
+ * handleWalletRoute pattern used elsewhere in this codebase).
+ */
+export declare function handleIMessageRoute(req: http.IncomingMessage, res: http.ServerResponse, pathname: string, method: string, state: IMessageRouteState, helpers: RouteHelpers): Promise<boolean>;
+//# sourceMappingURL=imessage-routes.d.ts.map

package/dist/api/imessage-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imessage-routes.d.ts","sourceRoot":"","sources":["../../src/api/imessage-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,IAAI,CAAC,eAAe,CAAC;IAC1B,GAAG,EAAE,IAAI,CAAC,cAAc,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACzE,KAAK,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5E,YAAY,EAAE,CAAC,CAAC,SAAS,MAAM,EAC7B,GAAG,EAAE,IAAI,CAAC,eAAe,EACzB,GAAG,EAAE,IAAI,CAAC,cAAc,EACxB,OAAO,CAAC,EAAE,mBAAmB,KAC1B,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;CACxB;AA2ED,MAAM,WAAW,kBAAkB;IACjC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE;QACR,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;KACnC,CAAC;CACH;AAyBD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,IAAI,CAAC,eAAe,EACzB,GAAG,EAAE,IAAI,CAAC,cAAc,EACxB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,OAAO,CAAC,CA0NlB"}

package/dist/api/imessage-routes.js

@@ -0,0 +1,230 @@
+/**
+ * iMessage connector HTTP routes.
+ *
+ * Exposes the @elizaos/plugin-imessage service state through Eliza's
+ * HTTP API so downstream UI layers (the dashboard, a future CLI, third-
+ * party integrations) can read and write against the macOS Messages.app
+ * world without each client having to go straight to chat.db or to
+ * AppleScript.
+ *
+ * Routes served (all under `/api/imessage`):
+ *
+ *   GET    /api/imessage/status         service health + cursor + counts
+ *   GET    /api/imessage/messages       recent messages from chat.db
+ *   GET    /api/imessage/chats          list of chats (DMs + groups)
+ *   GET    /api/imessage/contacts       every contact with full detail
+ *   POST   /api/imessage/contacts       create a new contact
+ *   PATCH  /api/imessage/contacts/:id   update an existing contact
+ *   DELETE /api/imessage/contacts/:id   delete a contact
+ *
+ * Each handler pulls the IMessageService instance off the runtime via
+ * `runtime.getService("imessage")` and calls the public methods added
+ * in the plugin's patched branch. If the service isn't registered (the
+ * plugin isn't enabled, Eliza booted before it was loaded, etc.) we
+ * return 503 with a structured reason so the UI can render an
+ * informative empty state.
+ *
+ * Write endpoints (POST/PATCH/DELETE on contacts) touch the real macOS
+ * Contacts.app and will trigger a one-time TCC permission prompt the
+ * first time they fire. That prompt targets whichever process ran the
+ * osascript child; in Eliza's case that's `bun`/`node`. Once granted
+ * the permission is persistent across restarts.
+ */
+const IMESSAGE_SERVICE_NAME = "imessage";
+const MAX_BODY_BYTES = 256 * 1024; // Contacts payloads are tiny; cap aggressively.
+function resolveService(state) {
+    if (!state.runtime)
+        return null;
+    const raw = state.runtime.getService(IMESSAGE_SERVICE_NAME);
+    return raw ?? null;
+}
+/**
+ * Extract the `:id` segment from a contact path like
+ * `/api/imessage/contacts/ABCD-EFGH-...`. Returns null if the path
+ * doesn't match. The id is URL-decoded since Contacts.app ids are
+ * GUID-style and safe, but callers could URL-encode for paranoia.
+ */
+function parseContactId(pathname) {
+    const prefix = "/api/imessage/contacts/";
+    if (!pathname.startsWith(prefix))
+        return null;
+    const rest = pathname.slice(prefix.length);
+    if (!rest)
+        return null;
+    return decodeURIComponent(rest);
+}
+/**
+ * Route handler entry point. Returns `true` when a route matched and
+ * the response has been written; returns `false` so the caller can
+ * continue to other route handlers (mirrors the handleWhatsAppRoute /
+ * handleWalletRoute pattern used elsewhere in this codebase).
+ */
+export async function handleIMessageRoute(req, res, pathname, method, state, helpers) {
+    if (!pathname.startsWith("/api/imessage"))
+        return false;
+    const meta = { req, res, method, pathname };
+    // ── GET /api/imessage/status ──────────────────────────────────────
+    if (method === "GET" && pathname === "/api/imessage/status") {
+        const service = resolveService(state);
+        if (!service) {
+            helpers.json(res, {
+                available: false,
+                reason: "imessage service not registered",
+            });
+            return true;
+        }
+        helpers.json(res, {
+            available: true,
+            connected: service.isConnected(),
+            ...(service.getStatus?.() ?? {}),
+        });
+        return true;
+    }
+    // ── GET /api/imessage/messages?limit=N ────────────────────────────
+    if (method === "GET" && pathname === "/api/imessage/messages") {
+        const service = resolveService(state);
+        if (!service) {
+            helpers.error(res, "imessage service not registered", 503);
+            return true;
+        }
+        const url = new URL(req.url ?? pathname, "http://localhost");
+        const limitParam = url.searchParams.get("limit");
+        const limit = Math.min(Math.max(1, Number.parseInt(limitParam ?? "50", 10) || 50), 500);
+        try {
+            const messages = await service.getRecentMessages(limit);
+            helpers.json(res, { messages, count: messages.length });
+        }
+        catch (error) {
+            helpers.error(res, `failed to read messages: ${error instanceof Error ? error.message : String(error)}`, 500);
+        }
+        return true;
+    }
+    // ── GET /api/imessage/chats ───────────────────────────────────────
+    if (method === "GET" && pathname === "/api/imessage/chats") {
+        const service = resolveService(state);
+        if (!service) {
+            helpers.error(res, "imessage service not registered", 503);
+            return true;
+        }
+        try {
+            const chats = await service.getChats();
+            helpers.json(res, { chats, count: chats.length });
+        }
+        catch (error) {
+            helpers.error(res, `failed to read chats: ${error instanceof Error ? error.message : String(error)}`, 500);
+        }
+        return true;
+    }
+    // ── GET /api/imessage/contacts ────────────────────────────────────
+    if (method === "GET" && pathname === "/api/imessage/contacts") {
+        const service = resolveService(state);
+        if (!service) {
+            helpers.error(res, "imessage service not registered", 503);
+            return true;
+        }
+        try {
+            const contacts = await service.listAllContacts();
+            helpers.json(res, { contacts, count: contacts.length });
+        }
+        catch (error) {
+            helpers.error(res, `failed to read contacts: ${error instanceof Error ? error.message : String(error)}`, 500);
+        }
+        return true;
+    }
+    // ── POST /api/imessage/contacts ───────────────────────────────────
+    if (method === "POST" && pathname === "/api/imessage/contacts") {
+        const service = resolveService(state);
+        if (!service) {
+            helpers.error(res, "imessage service not registered", 503);
+            return true;
+        }
+        const body = await helpers.readJsonBody(req, res, { maxBytes: MAX_BODY_BYTES });
+        if (!body)
+            return true; // helpers.readJsonBody has already sent the error.
+        if (!body.firstName && !body.lastName && !body.phones?.length && !body.emails?.length) {
+            helpers.error(res, "at least one of firstName, lastName, phones, or emails is required", 400);
+            return true;
+        }
+        try {
+            const id = await service.addContact({
+                firstName: body.firstName,
+                lastName: body.lastName,
+                phones: body.phones,
+                emails: body.emails,
+            });
+            if (!id) {
+                helpers.error(res, "contact creation failed — see server logs. Common cause: Contacts write permission not granted yet.", 500);
+                return true;
+            }
+            helpers.json(res, { id, created: true }, 201);
+        }
+        catch (error) {
+            helpers.error(res, `addContact threw: ${error instanceof Error ? error.message : String(error)}`, 500);
+        }
+        return true;
+    }
+    // ── PATCH /api/imessage/contacts/:id ──────────────────────────────
+    if (method === "PATCH" && pathname.startsWith("/api/imessage/contacts/")) {
+        const id = parseContactId(pathname);
+        if (!id) {
+            helpers.error(res, "contact id is required in the path", 400);
+            return true;
+        }
+        const service = resolveService(state);
+        if (!service) {
+            helpers.error(res, "imessage service not registered", 503);
+            return true;
+        }
+        const body = await helpers.readJsonBody(req, res, { maxBytes: MAX_BODY_BYTES });
+        if (!body)
+            return true;
+        try {
+            const ok = await service.updateContact(id, {
+                firstName: body.firstName,
+                lastName: body.lastName,
+                addPhones: body.addPhones,
+                removePhones: body.removePhones,
+                addEmails: body.addEmails,
+                removeEmails: body.removeEmails,
+            });
+            if (!ok) {
+                helpers.error(res, "contact update failed — see server logs. Contact may not exist, or write permission may be denied.", 500);
+                return true;
+            }
+            helpers.json(res, { id, updated: true });
+        }
+        catch (error) {
+            helpers.error(res, `updateContact threw: ${error instanceof Error ? error.message : String(error)}`, 500);
+        }
+        return true;
+    }
+    // ── DELETE /api/imessage/contacts/:id ─────────────────────────────
+    if (method === "DELETE" && pathname.startsWith("/api/imessage/contacts/")) {
+        const id = parseContactId(pathname);
+        if (!id) {
+            helpers.error(res, "contact id is required in the path", 400);
+            return true;
+        }
+        const service = resolveService(state);
+        if (!service) {
+            helpers.error(res, "imessage service not registered", 503);
+            return true;
+        }
+        try {
+            const ok = await service.deleteContact(id);
+            if (!ok) {
+                helpers.error(res, "contact delete failed — see server logs. Contact may not exist, or write permission may be denied.", 500);
+                return true;
+            }
+            helpers.json(res, { id, deleted: true });
+        }
+        catch (error) {
+            helpers.error(res, `deleteContact threw: ${error instanceof Error ? error.message : String(error)}`, 500);
+        }
+        return true;
+    }
+    // Path starts with /api/imessage but none of the above matched.
+    void meta; // reserved for future telemetry spans
+    return false;
+}
+//# sourceMappingURL=imessage-routes.js.map