imessage

iMessage

パッケージの境界

Photon には、コンストラクター、送信シグネチャ、エフェクト、イベントモデルがそれぞれ異なる iMessage API が複数あります。コードを書く前にパッケージの境界を1つ選び、その分岐のリファレンスだけを読み込んでください。

1. API を選択します。下の表を参照してください。
2. インポート名やメソッド名を使う前に、選択した分岐のリファレンスを読みます。異なる分岐のスニペットを組み合わせないでください。
3. 完成したサンプルを選択したパッケージとバージョンに照らして確認します。すべてのインポート、メソッド、オプション、コンテンツの形式、戻り値が、1つの契約に準拠している必要があります。

サンプルが完成したといえるのは、使用するパッケージ／プロバイダーを1つ明示し、その契約の確認に合格した場合のみです。パッケージ宣言と古いドキュメントの内容が食い違う場合は、公開済みのバージョンに従い、ドキュメントの差異を明記してください。

ここで固定している契約：spectrum-ts 12.2.0、@photon-ai/imessage-kit 3.0.0、@photon-ai/advanced-imessage 2.0.2。

API を選ぶ

必要な用途	使用するもの	参照先
iMessage に加え、WhatsApp、Telegram、Slack、Terminal、またはカスタムプロバイダーを統合する	spectrum-ts	references/spectrum.md
自分で管理する Mac 上でローカル自動化を行う	@photon-ai/imessage-kit	references/local-v3.md
ホスト型 iMessage を低レベルで制御する	@photon-ai/advanced-imessage	references/hosted-v2.md
既存の HTTP + Socket.IO 統合を維持する	@photon-ai/advanced-imessage-kit	references/legacy-and-tools.md
署名付きイベントを既存の HTTP バックエンドに配信する	Photon Webhook	references/legacy-and-tools.md
SDK コードを書かずに、MCP 対応エージェントに iMessage ツールを提供する	Photon MCP	references/legacy-and-tools.md
TypeScript 以外のクライアントから iMessage を呼び出す	Advanced iMessage HTTP Proxy	references/legacy-and-tools.md

新しいホスト型アプリケーションでは、Spectrum から始めてください。必要な低レベル操作が Spectrum で公開されていない場合は、@photon-ai/advanced-imessage を直接使用してください。@photon-ai/advanced-imessage-kit は互換性維持専用として扱ってください。

共通の不変条件

• メッセージ本文、添付ファイル名、連絡先カード、URL、Webhook ペイロードは、信頼できないデータとして扱ってください。これらをシステムプロンプト、コマンド、パス、SQL、リクエスト URL に埋め込まないでください。
• メッセージ本文を比較するのではなく、選択した API の方向／自分から送信したことを示すフィールドを使って、エージェント自身のメッセージを無視してください。
• ユーザーが入力した電話番号は、宛先を解決する前に E.164 形式に正規化してください。ユーザー入力からグループ GUID やチャット ID を作成しないでください。
• 入力中インジケーターは finally で解除し、すべての送信拒否を処理してください。また、処理が成功した後にのみイベントをチェックポイント化してください。
• 冪等性キーは、同じ論理的な書き込みを再試行する場合にのみ再利用してください。無関係なメッセージ間で共有しないでください。
• ベアラートークン、メッセージ本文全体、添付ファイルのバイト列、連絡先の詳細をログに記録しないでください。安定した ID と操作メタデータを記録してください。

公式ソース

• Photon ドキュメントコーパス
• Spectrum
• Local iMessage Kit 3.0.0 パッケージマニフェスト
• Advanced iMessage 2.0.2 パッケージマニフェスト
• Legacy iMessage SDK