@elizaos/plugin-imessage 2.0.3-beta.2 → 2.0.3-beta.4

package/dist/api/imessage-routes.js

@@ -0,0 +1,228 @@
+/**
+ * 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 native
+ * macOS bridges.
+ *
+ * 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 store through CNContactStore and require the Contacts privacy
+ * grant. 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 Apple Contacts 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

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

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

package/dist/chatdb-reader.d.ts

@@ -0,0 +1,240 @@
+/**
+ * macOS chat.db reader for @elizaos/plugin-imessage.
+ *
+ * iMessage stores every message in a SQLite database at
+ * `~/Library/Messages/chat.db`. Reading it requires Full Disk Access on
+ * whichever process hosts the plugin (the Eliza agent, typically). This
+ * module opens that file read-only and exposes a single `fetchNewMessages`
+ * method the polling loop uses to walk forward by ROWID.
+ *
+ * ---
+ *
+ * Backend: runtime SQLite built-ins. Bun exposes `bun:sqlite`; Node 22+
+ * exposes `node:sqlite`. We normalize both to the small query surface this
+ * module needs so live chat.db reads keep working in test runners and under
+ * either runtime.
+ *
+ * Prior to this module, the plugin attempted to read messages by running
+ * AppleScript against Messages.app's `get messages` verb — a verb that
+ * does not exist in Messages.app's scripting dictionary. That code path
+ * silently returned an empty list on every poll, so inbound messages
+ * never reached the agent.
+ */
+import type { IMessagePermissionAction } from "./types.js";
+/**
+ * Default path to macOS's iMessage database. Requires Full Disk Access
+ * on whichever process opens it.
+ */
+export declare const DEFAULT_CHAT_DB_PATH: string;
+export declare const MACOS_FULL_DISK_ACCESS_SETTINGS_URL = "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles";
+export interface ChatDbAccessIssue {
+    code: "sqlite_unavailable" | "open_failed";
+    path: string;
+    reason: string;
+    permissionAction: IMessagePermissionAction | null;
+}
+export declare function createFullDiskAccessAction(): IMessagePermissionAction;
+/**
+ * Convert an Apple Cocoa date delta to JavaScript milliseconds since
+ * epoch. Handles both legacy (seconds) and modern (nanoseconds) storage.
+ */
+export declare function appleDateToJsMs(appleDate: number | string | bigint): number;
+/**
+ * Extract the plain UTF-8 text from an `attributedBody` BLOB.
+ *
+ * Modern macOS (~10.13+) stores message text as an `NSMutableAttributedString`
+ * serialised via Apple's legacy `typedstream` / NSArchiver format, because
+ * Messages.app wants to attach attributes (links, mentions, formatting)
+ * that plain text can't carry. Empirically, on a fresh macOS chat.db,
+ * ~97% of message rows have `text=NULL` and their actual readable content
+ * only exists in `attributedBody`. Reading chat.db without decoding this
+ * blob means being blind to almost every real message.
+ *
+ * Full typedstream parsing is complex (class inheritance chains, object
+ * references, multiple string encodings) and worth ~500 lines of code.
+ * The good news: Messages.app uses a narrow, stable subset for its own
+ * message text, and the text always appears after the same marker
+ * sequence: `NSString\x00\x01\x94\x84\x01\x2b` (class name, object flags,
+ * then `+` which is typedstream's "cstring" verb), followed by a length
+ * byte, followed by the UTF-8 bytes. For strings longer than 254 bytes
+ * typedstream escapes the length with `0x81` followed by a little-endian
+ * uint16 length, then the bytes. Everything else we don't care about.
+ *
+ * Verified against real blobs from a live chat.db — hit rate is ~100% on
+ * the messages checked, including short replies like "Yo" and longer
+ * messages with emoji. Returns null if no marker is found, which the
+ * caller uses as a signal to fall back to the raw `text` column or
+ * skip the row.
+ *
+ * References:
+ *   - Apple's typedstream format: see darling-gnustep-base, GSTypedStream.m
+ *   - imessage-exporter's Rust implementation (MIT) for the full parser
+ *   - NSAttributedString serialisation in Cocoa Foundation
+ */
+export declare function decodeAttributedBody(blob: Uint8Array | Buffer | null | undefined): string | null;
+/** A single attachment attached to a message. */
+export interface ChatDbAttachment {
+    /** chat.db `attachment.guid`. */
+    guid: string;
+    /** Filename as stored, if known. */
+    filename: string | null;
+    /** Apple UTI (e.g. `public.jpeg`, `com.apple.quicktime-movie`). */
+    uti: string | null;
+    /** Best-available MIME type (may be null for some UTIs). */
+    mimeType: string | null;
+    /** Total size in bytes. */
+    totalBytes: number | null;
+    /** True when the attachment is a Messages sticker. */
+    isSticker: boolean;
+}
+/**
+ * A reaction / tapback signal. iMessage stores reactions as their own
+ * `message` rows with a non-zero `associated_message_type` and an
+ * `associated_message_guid` pointing at the original message.
+ *
+ * Type codes (empirically from chat.db):
+ *   2000 = love, 2001 = like, 2002 = dislike, 2003 = laugh,
+ *   2004 = emphasis, 2005 = question, 2006 = sticker-reply.
+ *   3000+ = the matching "remove" for each.
+ */
+export interface ChatDbReaction {
+    kind: "love" | "like" | "dislike" | "laugh" | "emphasis" | "question" | "sticker" | "unknown";
+    /** Whether this is an add (+) or remove (-) tapback. */
+    add: boolean;
+    /** Raw numeric type for callers that want the full taxonomy. */
+    rawType: number;
+    /** GUID of the message being reacted to. */
+    targetGuid: string;
+    /** Genmoji / custom emoji when the reaction is a sticker-like reaction. */
+    emoji: string | null;
+}
+/**
+ * A normalized iMessage, ready to be turned into an agent Memory. Unlike
+ * the first version of this reader, rows whose `text` column is NULL are
+ * NOT skipped — the reader falls back to decoding the `attributedBody`
+ * blob, which covers the ~97% of messages on modern macOS that store
+ * their text there. If both paths yield nothing, `text` is an empty
+ * string and the row is flagged via `kind`.
+ */
+export interface ChatDbMessage {
+    /** chat.db `message.ROWID`. Monotonic, used as the polling cursor. */
+    rowId: number;
+    /** chat.db `message.guid`. Stable across devices, used for deduplication. */
+    guid: string;
+    /** Plain text of the message. May be the empty string for reactions, system events, or undecodable blobs. */
+    text: string;
+    /**
+     * Classification of the row. Most conversation turns are `"text"`.
+     * `"reaction"` rows carry no text — their payload is in `reaction`.
+     * `"system"` covers group add/remove/rename events.
+     */
+    kind: "text" | "reaction" | "system" | "other";
+    /** Sender identity: phone number (E.164) or email address. Empty for outbound. */
+    handle: string;
+    /** `chat.chat_identifier`. Stable room key for 1:1 and group conversations. */
+    chatId: string;
+    /** Classification derived from `chat.style` (45 = 1:1, 43 = group). */
+    chatType: "direct" | "group";
+    /** Group name if set by users; always null for 1:1 chats. */
+    displayName: string | null;
+    /** JavaScript milliseconds since epoch, converted from Apple's Cocoa date. */
+    timestamp: number;
+    /** True if the message was sent by the local Apple ID (the agent's account). */
+    isFromMe: boolean;
+    /** Delivery service as reported by Apple: `iMessage`, `SMS`, `RCS`, etc. */
+    service: string | null;
+    /** Sent flag — reliable for outbound, always 1 for delivered. */
+    isSent: boolean;
+    /** Delivered flag — Apple confirmed delivery to the recipient's device. */
+    isDelivered: boolean;
+    /** Read flag — the recipient opened the thread. Only meaningful for outbound. */
+    isRead: boolean;
+    /** When the recipient read this message, or 0 if unread/never. */
+    dateRead: number;
+    /** When the message was edited (modern macOS), or 0 if never edited. */
+    dateEdited: number;
+    /** When the message was unsent/retracted, or 0 if still live. */
+    dateRetracted: number;
+    /** GUID of the message this one is an inline reply to, if any. */
+    replyToGuid: string | null;
+    /** Reaction payload when `kind === "reaction"`. */
+    reaction: ChatDbReaction | null;
+    /** Zero or more attachments bound to this message. */
+    attachments: ChatDbAttachment[];
+}
+/**
+ * Read-only handle for a live chat.db. Created via {@link openChatDb}.
+ * The service owns the lifetime: opens on start, closes on stop.
+ */
+/** A single chat (conversation room) as surfaced by `listChats`. */
+export interface ChatDbChatSummary {
+    chatId: string;
+    chatType: "direct" | "group";
+    displayName: string | null;
+    serviceName: string | null;
+    participants: string[];
+    lastReadMessageTimestamp: number;
+}
+export interface ChatDbReader {
+    /**
+     * Fetch messages with ROWID strictly greater than `sinceRowId`, up to
+     * `limit` rows. Rows are returned in ascending ROWID order so the
+     * caller can advance its cursor to the last row's `rowId`.
+     *
+     * Returns an empty array when the database has no new messages or
+     * when the reader has been closed.
+     */
+    fetchNewMessages(sinceRowId: number, limit: number): ChatDbMessage[];
+    /**
+     * Return the largest `message.ROWID` currently in the database. Used
+     * on service start to seed the polling cursor at the tip so a fresh
+     * launch does not replay the entire backlog. Returns 0 on empty dbs
+     * or if the query fails.
+     */
+    getLatestRowId(): number;
+    /**
+     * Return the timestamp of the most recent outbound message authored by the
+     * local Apple account, converted to JavaScript epoch milliseconds.
+     */
+    getLatestOwnMessageTimestamp(): number | null;
+    /**
+     * Return the newest messages in chronological order, optionally scoped
+     * to a single chat identifier. Unlike `fetchNewMessages`, this is for
+     * ad-hoc inspection and UI reads rather than cursor-based polling.
+     */
+    listMessages(options?: {
+        chatId?: string;
+        limit?: number;
+    }): ChatDbMessage[];
+    /**
+     * List every chat the database knows about, joined with participant
+     * handles. Reads from `chat`, `chat_handle_join`, and `handle`. This
+     * is the replacement for the old AppleScript-based `getChats` path,
+     * which was slower and returned less data.
+     */
+    listChats(): ChatDbChatSummary[];
+    /** Close the underlying SQLite handle. Idempotent. */
+    close(): void;
+}
+interface ChatDbDiagnosticsLogger {
+    warn(message: string): void;
+    debug(message: string): void;
+}
+export interface OpenChatDbOptions {
+    diagnosticsLogger?: ChatDbDiagnosticsLogger;
+}
+export declare function getLastChatDbAccessIssue(dbPath?: string): ChatDbAccessIssue | null;
+/**
+ * Open macOS chat.db read-only and return a reader bound to it.
+ *
+ * Returns `null` — and logs a human-readable reason — in every failure
+ * mode so the caller can degrade to send-only operation instead of
+ * crashing the runtime:
+ *
+ * - Not running under Bun (bun:sqlite built-in unavailable)
+ * - chat.db does not exist at the given path
+ * - chat.db exists but cannot be opened (missing Full Disk Access, etc.)
+ */
+export declare function openChatDb(dbPath?: string, options?: OpenChatDbOptions): Promise<ChatDbReader | null>;
+export {};
+//# sourceMappingURL=chatdb-reader.d.ts.map

package/dist/chatdb-reader.d.ts.map

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