@elizaos/plugin-imessage 2.0.0-beta.1 → 2.0.3-beta.2

package/dist/chatdb-reader.d.ts

@@ -1,240 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"version":3,"file":"chatdb-reader.d.ts","sourceRoot":"","sources":["../src/chatdb-reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAMH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAE3D;;;GAGG;AACH,eAAO,MAAM,oBAAoB,QAAoD,CAAC;AAEtF,eAAO,MAAM,mCAAmC,6EAC4B,CAAC;AAE7E,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,oBAAoB,GAAG,aAAa,CAAC;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE,wBAAwB,GAAG,IAAI,CAAC;CACnD;AAED,wBAAgB,0BAA0B,IAAI,wBAAwB,CAWrE;AAWD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAOzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAsEhG;AAmDD,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,mEAAmE;IACnE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,2BAA2B;IAC3B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,sDAAsD;IACtD,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;IAC9F,wDAAwD;IACxD,GAAG,EAAE,OAAO,CAAC;IACb,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,6GAA6G;IAC7G,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC/C,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC7B,6DAA6D;IAC7D,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,8EAA8E;IAC9E,SAAS,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,QAAQ,EAAE,OAAO,CAAC;IAClB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,iEAAiE;IACjE,MAAM,EAAE,OAAO,CAAC;IAChB,2EAA2E;IAC3E,WAAW,EAAE,OAAO,CAAC;IACrB,iFAAiF;IACjF,MAAM,EAAE,OAAO,CAAC;IAChB,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,aAAa,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,mDAAmD;IACnD,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IAChC,sDAAsD;IACtD,WAAW,EAAE,gBAAgB,EAAE,CAAC;CACjC;AAED;;;GAGG;AACH,oEAAoE;AACpE,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC7B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,wBAAwB,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,EAAE,CAAC;IACrE;;;;;OAKG;IACH,cAAc,IAAI,MAAM,CAAC;IACzB;;;OAGG;IACH,4BAA4B,IAAI,MAAM,GAAG,IAAI,CAAC;IAC9C;;;;OAIG;IACH,YAAY,CAAC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,aAAa,EAAE,CAAC;IAC7E;;;;;OAKG;IACH,SAAS,IAAI,iBAAiB,EAAE,CAAC;IACjC,sDAAsD;IACtD,KAAK,IAAI,IAAI,CAAC;CACf;AAgBD,UAAU,uBAAuB;IAC/B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,iBAAiB,CAAC,EAAE,uBAAuB,CAAC;CAC7C;AAOD,wBAAgB,wBAAwB,CACtC,MAAM,GAAE,MAA6B,GACpC,iBAAiB,GAAG,IAAI,CAE1B;AAqED;;;;;;;;;;GAUG;AACH,wBAAsB,UAAU,CAC9B,MAAM,GAAE,MAA6B,EACrC,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAyb9B"}