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

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): 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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"}