imessage-kit

It is important to distinguish between sending a message and observing its arrival in the database:

• sdk.send(request): Returns a Promise<void> that resolves when the underlying osascript command exits successfully. It does not confirm the message was written to chat.db or return a Message object.
• Observation: To confirm a message has actually landed in the database (and to track delivery status), you must use sdk.startWatching() and listen to the onFromMeMessage callback.

// Fire-and-forget send
await sdk.send({ to: '+1234567890', text: 'Hi' })

// Observe the landed row
await sdk.startWatching({
    onFromMeMessage: (msg) => console.log('Landed in chat.db:', msg.id, msg.isDelivered),
})

Import IMessageSDK to start interacting with iMessage. You can use standard await sdk.close() for manual teardown or use the await using (async-dispose) pattern to guarantee the SDK is closed automatically when the scope ends.

import { IMessageSDK } from '@photon-ai/imessage-kit'

const sdk = new IMessageSDK()

// Send a text message
await sdk.send({ to: '+1234567890', text: 'Hello from iMessage Kit!' })

// Or use async-dispose to guarantee teardown:
await using disposable = new IMessageSDK()
await disposable.send({ to: '+1234567890', text: 'Hi!' })

// Manual teardown
await sdk.close()

Install the SDK based on your runtime. Bun users can use the zero-dependency version, while Node.js users must also install better-sqlite3 to interact with the Messages database.

# For Bun (zero dependencies)
bun add @photon-ai/imessage-kit

# For Node.js (requires better-sqlite3)
npm install @photon-ai/imessage-kit better-sqlite3

You can run the provided examples using Bun. Ensure you are on macOS and have granted Full Disk Access to your terminal/Bun.

Example command to run the basic text send example:

bun run examples/01-send-text.ts

When constructing IMessageSDK, you can pass an IMessageConfig object to customize behavior. Note that numeric values outside the allowed ranges will throw an IMessageError(code: 'CONFIG') rather than being clamped. The valid ranges are available via the exported BOUNDS constant.

interface IMessageConfig {
    databasePath?: string        // Path to Messages SQLite database (default: ~/Library/Messages/chat.db)
    maxConcurrentSends?: number  // Concurrent send cap (default: 10, range 1..50)
    sendTimeout?: number         // ms per AppleScript invocation (default: 30_000, range 1_000..300_000)
    debug?: boolean              // Verbose SDK logs
    plugins?: Plugin[]           // Plugins registered at construction; sdk.use() is also available later
}

The MessageSender implements a robust retry and error-wrapping strategy:

1. Retry Logic: Retries are performed per-step (per AppleScript call), not end-to-end. For a message with $N$ attachments, the first call bundles the text and the first attachment. Subsequent attachments are sent via individual AppleScript calls. If a failure occurs, the system retries that specific step up to retryAttempts times.
2. Error Guarantees: The send() method ensures that any error thrown is an IMessageError. This allows you to reliably catch and inspect error codes like CONFIG, DATABASE, or SEND.
3. Resuming Failures: Because dispatch is non-transactional, if a batch of attachments fails, you should re-invoke send() with a slice of the remaining attachments (e.g., attachments.slice(k-1)) to resume the process.

The imessage-kit library normalizes raw macOS transfer_state integer codes into a set of human-readable TransferStatus strings. This allows developers to handle file transfer lifecycles without managing low-level system codes.

The MessageDispatcher processes batches of messages by partitioning them into two parallel branches: Incoming (non-from-me) and From-Me.

• Parallelism: The two branches (incoming vs. from-me) are processed independently using Promise.all. A slow handler in the onFromMe branch will not block the delivery of incoming messages.
• Ordering: Within each branch, messages are processed sequentially. This ensures that the order of messages within your user-provided callbacks is preserved.
• Dispatch Logic:
  • Incoming messages are further routed based on chatKind (group or dm).
  • From-me messages are routed to the onFromMeMessage handler.

To use the dispatcher, call the dispatch(messages: readonly Message[]) method.

The SDK requires Full Disk Access to read the macOS chat.db file.

1. Open System Settings → Privacy & Security → Full Disk Access.
2. Click "+" and add your terminal or IDE (e.g., Cursor, VS Code, Terminal, Warp).