email-sdk

Email SDK

エージェントがこのリポジトリで作業する場合、または別の TypeScript アプリに @opencoredev/email-sdk を組み込む場合は、このスキルを使用してください。

このスキルは意図的に動的な内容になっています。以下の例を、現行の API やテンプレートカタログのすべてだと見なさないでください。まず、インストールされているバージョンのローカルパッケージドキュメントとソースを更新してから、リポジトリ、依存関係、および現在のマシン可読ドキュメントで実際に公開されている内容に基づいて実装してください。

現行ドキュメントの更新

コードを変更する前に、関連性の高い現行のソースを確認してください。

1. このリポジトリ内で作業している場合は、以下を読みます。
   • README.md
   • packages/email-sdk/README.md
   • packages/email-sdk/package.json
   • apps/fumadocs/content/docs/**/*.mdx
   • packages/email-sdk/src/index.ts
   • packages/email-sdk/src/<adapter>.ts 内の該当するアダプターファイル
   • メッセージの形式、ルーティング、再試行、フック、またはエラー処理が関係する場合は、packages/email-sdk/src/types.ts、core.ts、および errors.ts
2. @opencoredev/email-sdk がインストールされたアプリ内で作業している場合は、以下を確認します。
   • アプリのロックファイルと node_modules/@opencoredev/email-sdk/package.json
   • node_modules/@opencoredev/email-sdk/README.md
   • node_modules/@opencoredev/email-sdk/dist/*.d.ts
   • アプリに既存のメール、通知、キュー、環境変数、およびテストのパターン。
3. ローカルドキュメントがない場合、またはタスクがバージョン依存の挙動に関係する場合は、実装前に公開中のパッケージメタデータ／ドキュメントを取得します。
   • bun pm view @opencoredev/email-sdk
   • 対象アプリに CLI がインストールされている場合は bun email-sdk version
   • 現行のドキュメントツリーを確認するには https://email-sdk.dev/docs/llms.txt
   • 該当する raw Markdown ページは https://email-sdk.dev/docs/<path>.md
   • 使用中の正確なバージョンに対応するリポジトリのドキュメントまたはパッケージ README。

レンダリング済み HTML のスクレイピングより、raw .md エンドポイントを優先してください。これらは Content-Type: text/markdown を返し、現行の内部リンクを保持したうえで、ページタイトルと正規ルートを含みます。

React Email の UI またはテンプレートを扱う場合：

1. まず https://email-sdk.dev/docs/ui.md を取得します。
2. 固定のテンプレート一覧に頼らず、現行のカテゴリおよびテンプレートへのリンクをたどります。
3. 選んだテンプレートのページを raw Markdown として取得します。たとえば https://email-sdk.dev/docs/ui/account/verification-code.md です。
4. インストールを求められた場合は、ドキュメントに記載された shadcn@latest add のレジストリ URL を使用するか、同じページの Manual ソースをコピーします。
5. テンプレートでは実際の @opencoredev/email-sdk/react プリミティブを使用し、表示を変更する場合はライトとダークの両方のメールテーマを検証します。

ローカルソースと外部ドキュメントに食い違いがある場合は、インストールされている正確なバージョンのコード／型定義を優先し、不一致について言及してください。

デフォルト

• bun と bunx を優先します。
• コアに依存関係を追加しないでください。
• アダプターは、@opencoredev/email-sdk/resend、@opencoredev/email-sdk/smtp、および現行のパッケージエクスポートで示されるアダプター固有のエントリーポイントなど、個別のエントリーポイントからインポートしてください。
• SMTP に Nodemailer を追加しないでください。Email SDK には独自の SMTP トランスポートが含まれています。
• 非セキュアポートでの SMTP 認証は、デフォルトで STARTTLS にアップグレードします。allowInsecureAuth は、信頼できるローカルテストサーバーでのみ使用してください。
• アダプターは、正規化された EmailMessage のフィールドをマッピングするか、明確にエラーを返す必要があります。CC、BCC、返信先、ヘッダー、タグ、メタデータ、または添付ファイルを黙って破棄してはいけません。
• アダプターの認証情報は環境変数に保管してください。
• API キー、SMTP パスワード、生のトークン、メッセージ本文全体、または不要な宛先情報をログに記録しないでください。
• ホストアプリのキュー、テンプレート、環境変数の検証、再試行、およびテストのアーキテクチャを維持してください。

統合パターン

@opencoredev/email-sdk/resend や @opencoredev/email-sdk/smtp のようなエントリーポイント名は例示です。これらのインポートをコピーする前に、インストールしたバージョンの正確なエクスポートを確認してください。

Email SDK は、本番環境の送信パイプラインとして組み込むことをおすすめします。正規化されたメッセージ形式を1つ定め、アダプターのルートを明示し、フィールドのサポートを早い段階で確認し、リトライ、互換性のあるフォールバックルート、シークレットを安全に扱うオブザーバビリティ、テスト、CLI による検証を整えます。

import { createEmailClient } from "@opencoredev/email-sdk";
import { resend } from "@opencoredev/email-sdk/resend";
import { smtp } from "@opencoredev/email-sdk/smtp";

export const email = createEmailClient({
  adapters: [
    resend({ apiKey: process.env.RESEND_API_KEY! }),
    smtp({
      host: process.env.SMTP_HOST!,
      port: Number(process.env.SMTP_PORT ?? 587),
      auth: {
        user: process.env.SMTP_USER!,
        pass: process.env.SMTP_PASS!,
      },
    }),
  ],
  fallback: { adapters: ["smtp"] },
  retry: { maxAttempts: 2 },
});

フォールバックとリトライに関するガイダンス

• フォールバックルートを選ぶ前に、現在のフィールドサポートのドキュメントまたはアダプターのソースを確認してください。
• バックアップアダプターが同じ種類のメールを送信でき、アプリにとって重要なフィールドを保持できる場合にのみ、フォールバックを使用してください。
• SMTP を万能のバックアップとして扱わないでください。SMTP は、アドレスフィールドとヘッダーを含むシンプルなテキスト／HTML の送信に最適です。
• 外部に表示されるトランザクションメールの送信がリトライまたはフォールバックルート経由で送信される可能性がある場合は、冪等性キーを使用してください。
• マスキングされたルート、試行、リトライ、成功、エラーのイベントには、フックまたは observabilityPlugin() を使用してください。
• フォールバックやリトライの動作が重要な場合は、memoryAdapter()、failingAdapter()、capturePlugin() を使ってテストを追加してください。
• 実際のプロバイダー認証を確認する前に、CLI の doctor と send --dry-run を使用してください。
• v0 から v1 へのアプリケーション移行には、静的な検索置換ルールを適用するのではなく、専用の email-sdk-migrate スキルを使用してください。
• 2.x から v3 へのアップグレードでは、/docs/guides/migrate/v2-to-v3 に従ってください。型チェッカーを実行し、プレーンデータではない送信オプションの metadata を修正してください。

このリポジトリでは、このパターンに関する主な公開ドキュメントは次のとおりです。

• apps/fumadocs/content/docs/guides/production-send-pipeline.mdx
• apps/fumadocs/content/docs/concepts/fallbacks-and-retries.mdx
• apps/fumadocs/content/docs/adapters/field-support.mdx

検証

• SDK を変更した場合は、packages/email-sdk で bun test を実行してください。
• ドキュメントを変更した場合は、可能であればリポジトリのルートで bun run check-types と bun run build を実行してください。
• アプリを統合した場合は、送信経路をカバーする最小範囲のテストまたは型チェックを実行してください。
• 実際のプロバイダー認証を確認する場合は、利用可能であれば、リポジトリにある送信を行わない live:* スクリプトを使用してください。ユーザーから別途承認を得ずに、外部宛てのメールを送信しないでください。

レビューチェックリスト

• すべての送信に from、to、subject と、html または text のいずれかが含まれていますか？
• フォールバックは、同じ種類のメールを送信できるアダプターにのみ設定されていますか？
• 外部に表示されるトランザクションメールの送信に、冪等性キーが使用されていますか？
• プロバイダーのエラーは握りつぶされずに表面化していますか？
• フックはシークレットや本文全体のログ記録ではなく、メタデータとステータスに使用されていますか？
• フィールドのマッピングが変更される場合、各アダプターのペイロードにテストがありますか？