GitHub - photon-hq/imessage-kit: A type-safe, elegant iMessage SDK for macOS with zero dependencies

A type-safe, elegant iMessage SDK for macOS with cross-runtime support

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

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

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()

// Simplified; `readonly` modifiers omitted for readability — see src/types/config.ts
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
}

// 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),
})

// Simplified; `readonly` modifiers omitted for readability — see src/types/send.ts
interface SendRequest {
    to: string                  // phone, email, or chatId
    text?: string
    attachments?: string[]      // local absolute paths; remote URLs are rejected
}

// Text
await sdk.send({ to: '+1234567890', text: 'Hello World!' })

// Email recipient
await sdk.send({ to: 'user@example.com', text: 'Hello!' })

// Local file paths only — download remote URLs yourself first.
await sdk.send({ to: '+1234567890', attachments: ['/abs/path/image.jpg'] })

// Text + multiple attachments — non-transactional: the first osascript call
// bundles text + attachments[0]; each later attachment is its own call with
// a ~500ms inter-step pacing. A mid-batch failure is labelled
// "attachment N/total".
await sdk.send({
    to: '+1234567890',
    text: 'Check this out',
    attachments: ['/abs/path/photo.jpg', '/abs/path/report.pdf']
})

const messages = await sdk.getMessages({
    chatId: 'any;+;chat534ce85d...',   // optional — scopes to one conversation
    participant: '+1234567890',
    service: 'iMessage',                // 'iMessage' | 'SMS' | 'RCS'
    isFromMe: false,                    // tri-state: omit → both
    isRead: false,                      // tri-state: omit → both
    hasAttachments: true,               // tri-state: omit → both
    excludeReactions: true,             // drop tapback/sticker rows
    since: new Date('2025-01-01'),
    before: new Date('2025-02-01'),
    search: 'meeting',                  // app-layer substring over decoded text
    limit: 20,
    offset: 0,
})

const chats = await sdk.listChats({
    chatId: 'any;+;chat...',   // optional — scope to one chat
    kind: 'group',              // 'group' | 'dm'
    service: 'iMessage',
    isArchived: false,
    hasUnread: true,
    sortBy: 'recent',           // 'recent' | 'name'
    search: 'Project',          // LIKE over display_name / chat_identifier (escaped)
    limit: 20,
    offset: 0,
})

for (const chat of chats) {
    console.log({
        chatId: chat.chatId,
        name: chat.name,
        kind: chat.kind,
        unread: chat.unreadCount,
        lastMessageAt: chat.lastMessageAt,
    })
}

// From listChats
const groups = await sdk.listChats({ kind: 'group' })
await sdk.send({ to: groups[0].chatId, text: 'Hello group!' })

// From the watcher
await sdk.startWatching({
    onGroupMessage: async (msg) => {
        if (msg.chatId) await sdk.send({ to: msg.chatId, text: 'ack' })
    }
})

import { ChatId, resolveTarget } from '@photon-ai/imessage-kit'

const cid = ChatId.fromUserInput('iMessage;-;pilot@photon.codes')
cid.isGroup            // false
cid.coreIdentifier     // 'pilot@photon.codes'

const target = resolveTarget('+1234567890')   // MessageTarget (dm | group)

await sdk.startWatching({
    onIncomingMessage: (msg) => { /* every incoming (non-from-me) row */ },
    onDirectMessage:   (msg) => { /* incoming DMs only */ },
    onGroupMessage:    (msg) => { /* incoming group messages only */ },
    onFromMeMessage:   (msg) => { /* any from-me row — this SDK or another client */ },
    onError:           (err) => { /* dispatch errors */ },
})

await sdk.stopWatching()   // safe to call even if never started

await sdk.startWatching({
    onDirectMessage: async (msg) => {
        if (!msg.text || !/hello/i.test(msg.text)) return
        if (!msg.chatId) return   // rare WAL race before chat_message_join flushes
        await sdk.send({ to: msg.chatId, text: 'Hi there!' })
    }
})

import {
    attachmentExists,
    getAttachmentExtension,
    isImageAttachment,
    isVideoAttachment,
    isAudioAttachment,
} from '@photon-ai/imessage-kit'

const [msg] = await sdk.getMessages({ hasAttachments: true, limit: 1 })
const attachment = msg?.attachments[0]

if (attachment && await attachmentExists(attachment)) {
    if (isImageAttachment(attachment)) {
        const ext = getAttachmentExtension(attachment)   // lowercase, no leading dot — e.g. 'jpg'
        // Use node:fs for anything further (copyFile, createReadStream, stat, …)
    }
}

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

const audit = definePlugin({
    name: 'audit',
    version: '1.0.0',
    onBeforeSend: ({ request }) => {
        // Throw here to veto the send; cause is attached to IMessageError(SEND).
        if (request.text?.includes('forbidden')) throw new Error('blocked by policy')
    },
    onAfterSend: ({ request }) => {
        console.log('[audit] dispatched to', request.to)
    },
})

sdk.use(audit)

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

try {
    await sdk.send({ to: '+1234567890', text: 'Hello' })
} catch (error) {
    if (error instanceof IMessageError) {
        // error.code: 'PLATFORM' | 'DATABASE' | 'SEND' | 'CONFIG'
        // error.cause: original thrown Error (when applicable)
        console.error(`[${error.code}] ${error.message}`)
    }
}

bun run examples/01-send-text.ts

interface Message {
    rowId: number
    id: string
    text: string | null
    participant: string | null
    chatId: string | null
    chatKind: 'dm' | 'group' | 'unknown'
    service: 'iMessage' | 'SMS' | 'RCS' | null
    kind: 'text' | 'memberAdded' | 'memberRemoved' | 'nameChanged' | 'groupAction' | 'unknown'
    isFromMe: boolean
    isRead: boolean
    isSent: boolean
    isDelivered: boolean
    createdAt: Date
    deliveredAt: Date | null
    readAt: Date | null
    editedAt: Date | null
    retractedAt: Date | null
    reaction: Reaction | null
    attachments: Attachment[]
    // ...plus ~30 additional fields; see src/domain/message.ts for the full interface
}

use context7: photon-hq/imessage-kit