📧 メールサービスドライバー

メールサービスドライバーは、NodeBlocksアプリケーションでメール送信のための一貫したインターフェースを提供します。メールプロバイダーの設定と操作を抽象化し、ビジネスロジックを変更することなく異なるメールサービスを使用できるようにします。

---

🎯 概要

NodeBlocksのメールサービスドライバーは、設定されたメールサービスインスタンスを作成するファクトリ関数です。これらは以下を提供します：

• 一貫したインターフェース - 異なるメールプロバイダー間で
• シンプルな設定 - APIキーと設定を使用
• 柔軟な実装 - カスタムメールプロバイダー用

---

📋 利用可能なメールサービスドライバー

SendGrid Driver

SendGridドライバーは、SendGrid APIを通じてメールを送信するための設定されたSendGridメールサービスを作成します。

getSendGridClient

APIキーとオプションのベースURL設定でSendGridメールサービスクライアントを作成します。

パラメータ:

• apiKey: string - 認証用のSendGrid APIキー
• baseUrl?: string - SendGrid APIのオプショナルベースURL（テスト/ステージングに便利）

戻り値: MailService - sendMailメソッドを持つ設定されたメールサービス

使用例:

import { getSendGridClient } from '@nodeblocks/backend-sdk/drivers';

const mailService = getSendGridClient(process.env.SENDGRID_API_KEY);

カスタムベースURLの例:

import { getSendGridClient } from '@nodeblocks/backend-sdk/drivers';

const mailService = getSendGridClient(
  process.env.SENDGRID_API_KEY,
  'https://api.sendgrid.com/v3'
);

オプション付きの例:

import { getSendGridClient } from '@nodeblocks/backend-sdk/drivers';

const mailService = getSendGridClient(process.env.SENDGRID_API_KEY);

// ロギングを有効にして送信
const success = await mailService.sendMail({
  to: 'user@example.com',
  from: 'noreply@company.com',
  subject: 'Welcome!',
  text: 'Welcome to our platform'
}, {
  logger: myLogger,
  sandboxMode: process.env.NODE_ENV === 'development'
});

setBaseUrl

カスタムエンドポイントやテストを有効にするために、SendGrid APIリクエストのベースURLを設定します。

パラメータ:

• baseUrl: string - SendGrid APIリクエストのベースURL（例：'https://api.sendgrid.com/v3'）

使用例:

import { setBaseUrl } from '@nodeblocks/backend-sdk/drivers';

// 本番SendGrid API URLを設定
setBaseUrl('https://api.sendgrid.com/v3');

// ステージング/テストURLを設定
setBaseUrl('https://api-staging.sendgrid.com/v3');

---

🔧 メールサービスドライバーの使用

直接使用

メール送信のためにメールサービスドライバーを直接使用します：

import { getSendGridClient } from '@nodeblocks/backend-sdk/drivers';

const mailService = getSendGridClient(process.env.SENDGRID_API_KEY);

// サービスを使用してメールを送信
const success = await mailService.sendMail({
  to: 'identity@example.com',
  from: 'noreply@company.com',
  subject: 'Welcome!',
  text: 'Welcome to our platform'
});

---

📧 メールインターフェース

メールデータインターフェース

MailDataインターフェースは、メールメッセージの構造を定義します。基本的なメールフィールドとコンテンツが必要で、シンプルだが厳密な構造を持ちます：

// すべてのメールに必要なフィールド
interface RequiredMailData {
  from: string;    // 送信者メールアドレス
  subject: string; // メール件名
  to: string;      // 受信者メールアドレス
}

// 完全なメールデータ - コンテンツ（HTMLまたはテキスト）が必要
type MailData = RequiredMailData & ({ html: string } | { text: string });

インターフェースルール:

• 常に必須: from、subject、toフィールド
• コンテンツの選択: htmlまたはtextコンテンツのいずれかを含める（両方ではない）
• 単一受信者: メールごとに1人の受信者のみ
• 添付ファイルなし: ファイル添付はサポートされていません

使用例:

// ✅ 有効: HTMLメール
const htmlEmail: MailData = {
  to: 'identity@example.com',
  from: 'noreply@company.com',
  subject: 'Welcome!',
  html: '<h1>Welcome!</h1><p>Thank you for joining.</p>'
};

// ✅ 有効: テキストメール
const textEmail: MailData = {
  to: 'identity@example.com',
  from: 'noreply@company.com',
  subject: 'Password Reset',
  text: 'Your reset token: ABC123'
};

メールサービスインターフェース

MailServiceインターフェースは、すべてのメールサービスドライバーの契約を定義します：

interface MailService {
  sendMail(mailData: MailData, opts?: MailOptions): Promise<boolean>;
}

パラメータ:

• mailData: MailData - 送信者、受信者、件名、コンテンツを含むメールデータ
• opts?: MailOptions - オプション設定（サンドボックスモード、ロガー）

戻り値: Promise<boolean> - メール送信が成功した場合（ステータスコード202）はtrue、それ以外はfalse

MailOptions:

interface MailOptions {
  logger?: Logger;      // デバッグ用のオプションロガー
  sandboxMode?: boolean; // テスト用のサンドボックスモードを有効化
}