@photon‑ai/imessage‑kit

macOS で動作し、クロスランタイム対応の型安全で洗練された iMessage SDK。

概要

iMessage Kit はフル機能を備えた SDK で、以下が可能です：

• macOS 上で iMessage の会話を読み取り・送信・自動化
• AI エージェント、オートメーションツール、チャットファースト型アプリの構築

注意: フルディスクアクセス が必要です（「権限付与」セクション参照）。

速やかな始め方

インストール

bun add @photon-ai/imessage-kit

npm install @photon-ai/imessage-kit better-sqlite3

基本的な使用例

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

const sdk = new IMessageSDK();

// メッセージを送信
await sdk.send('+1234567890', 'Hello from iMessage Kit!');

// 後片付け
await sdk.close();

設定

interface IMessageConfig {
  debug?: boolean;               // デバッグログを有効化
  maxConcurrent?: number;        // 同時送信数の上限（デフォルト: 5）
  scriptTimeout?: number;        // AppleScript のタイムアウト (ms)
  databasePath?: string;         // カスタム DB パス
  plugins?: Plugin[];            // プラグイン

  watcher?: {
    pollInterval?: number;       // ポーリング間隔（デフォルト: 2000）
    unreadOnly?: boolean;        // 未読のみ監視（デフォルト: false）
    excludeOwnMessages?: boolean;// 自分のメッセージを除外（デフォルト: true）
  };

  webhook?: {
    url: string;
    headers?: Record<string, string>;
  };
}

権限付与方法

1. システム設定 → プライバシーとセキュリティ → フルディスクアクセス を開く
2. 「+」をクリックし、IDE またはターミナル（例: Cursor, VS Code, Terminal, Warp）を追加する。

機能一覧とサンプル

sdk.send()

01-send-text.ts

sdk.send()

02-send-image.ts

sdk.sendFile()

03-send-file.ts

sdk.send()

04-send-group.ts

sdk.getMessages()

05-query-messages.ts

sdk.listChats()

06-list-chats.ts

sdk.startWatching()

07-watch-messages.ts

sdk.message()

08-auto-reply.ts

sdk.sendBatch()

09-batch-send.ts

sdk.send()

10-get-sent-message.ts

sdk.use()

11-plugin.ts

12-error-handling.ts

sdk.startWatching()

13-watch-own-messages.ts

MessageScheduler

14-scheduled-messages.ts

Reminders

15-smart-reminders.ts

コアメソッド

// フィルタ付きでメッセージを検索
getMessages(filter?): Promise<Message[]>;

// 送信者別に未読数を取得
getUnreadMessages(): Promise<{ total: number; senderCount: number }>;

listChats(options?): Promise<Chat[]>;

// テキスト・画像・ファイルの送信
send(to: string, content: string | MessageContent): Promise<SendResult>;
sendFile(to: string, path: string, text?: string): Promise<SendResult>;
sendFiles(to: string, paths: string[], text?: string): Promise<SendResult>;

// 複数メッセージを並列送信
sendBatch(messages: BatchMessage[]): Promise<SendResult[]>;

// メッセージ処理チェーン
message(msg: Message);

// 新着メッセージの監視開始/停止
startWatching(events?): void;
stopWatching(): void;

// プラグイン登録
use(plugin: Plugin): void;

// SDK を閉じてリソースを解放
close(): Promise<void>;

型定義

interface Message {
  id: string;
  guid: string;
  text: string | null;
  sender: string;
  senderName: string | null;
  chatId: string;
  isGroupChat: boolean;
  isFromMe: boolean;
  isRead: boolean;
  service: 'iMessage' | 'SMS' | 'RCS';
  attachments: Attachment[];
  date: Date;

  // リアクション関連
  isReaction: boolean;
  reactionType: 'love' | 'like' | 'dislike' | 'laugh' | 'emphasize' | 'question' | null;
  isReactionRemoval: boolean;
  associatedMessageGuid: string | null;
}

interface SendResult {
  sentAt: Date;
  message?: Message; // 監視中のみ取得可能
}

添付ファイルヘルパー

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

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

if (await attachmentExists(attachment)) {
  const size = await getAttachmentSize(attachment);
  if (isImageAttachment(attachment)) {
    await downloadAttachment(attachment, '/path/to/save.jpg');
  }
}

PDF、DOC、画像、vCard、CSV、ZIP、MP4 等がサポートされています。

スケジューリング

MessageScheduler

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

const sdk = new IMessageSDK();
const scheduler = new MessageScheduler(sdk, { debug: true }, {
  onSent: (msg, result) => console.log(`✅ Sent: ${msg.id}`),
  onError: (msg, error) => console.error(`❌ Failed: ${error.message}`),
  onComplete: (msg) => console.log(`🏁 Completed: ${msg.id}`)
});

// 一度限りのメッセージ
const id = scheduler.schedule({
  to: '+1234567890',
  content: 'Reminder!',
  sendAt: new Date(Date.now() + 5 * 60 * 1000) // 5 分後
});

スマートリマインダー

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

const sdk = new IMessageSDK();
const reminders = new Reminders(sdk);

// 相対時間
reminders.in('5 minutes', '+1234567890', 'Take a break!');

// 固定時刻
reminders.at('5pm', '+1234567890', 'End of day review');

// 正確な日時
reminders.exact(new Date('2025-12-25T10:00:00'), '+1234567890', 'Merry Christmas!');

サポート形式：

プラグインシステム

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

// ビルト‑インロガー
sdk.use(loggerPlugin({
  level: 'info',
  colored: true
}));

// カスタムプラグイン
sdk.use({
  name: 'my-plugin',
  onInit: async () => console.log('Initialized'),
  onBeforeSend: async (to, content) => {
    console.log('Sending to:', to);
    return { to, content };
  },
  onAfterSend: async (result) => console.log('Sent:', result),
  onDestroy: async () => console.log('Destroyed')
});

エラー処理

import { SendError, DatabaseError, PlatformError } from '@photon-ai/imessage-kit';

try {
  await sdk.send('+1234567890', 'Hello');
} catch (error) {
  if (error instanceof SendError) {
    console.error('Send failed:', error.message);
  } else if (error instanceof DatabaseError) {
    console.error('Database error:', error.message);
  } else if (error instanceof PlatformError) {
    console.error('Platform error:', error.message);
  }
}

サンプル実行

# Bun を使う場合
bun run examples/<filename>.ts

01-send-text.ts

02-send-image.ts

03-send-file.ts

04-send-group.ts

05-query-messages.ts

06-list-chats.ts

07-watch-messages.ts

08-auto-reply.ts

09-batch-send.ts

10-get-sent-message.ts

11-plugin.ts

12-error-handling.ts

13-watch-own-messages.ts

14-scheduled-messages.ts

15-smart-reminders.ts

API 参照（コアメソッド）

getMessages(filter?)

getUnreadMessages()

listChats(options?)

send(to, content)

sendFile(to, path, text?)

sendFiles(to, paths, text?)

sendBatch(messages)

message(msg)

startWatching(events?)

stopWatching()

use(plugin)

close()

要件

• OS: macOS（専用）
• ランタイム: Node.js ≥ 18.0.0 または Bun ≥ 1.0.0
• 権限: フルディスクアクセスが必要

ライセンス

MIT License – 教育・開発用途のみ。ユーザーのプライバシーと Apple の利用規約を尊重してください。