バージョン: 0.13.0 (Previous)

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

メールサービスドライバーは、NodeBlocks アプリケーションでメールを送信するための一貫したインターフェースを提供します。メールプロバイダー構成と、SDK サービスが使用する sendMail 契約を抽象化します。

🎯 概要

NodeBlocks のメールサービスドライバーは、構成済み SendGrid メールサービスインスタンスを作成するファクトリー関数です。SDK は現在 1 つの SendGrid ドライバーを提供します。カスタムプロバイダーは src/types/email.ts の MailService インターフェースを実装し、同じ方法で注入できます。

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

const { getSendGridClient, setBaseUrl } = drivers;

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

SendGrid ドライバー

SendGrid ドライバーは、SendGrid API を介してメールを送信するための構成済み SendGrid メールサービスを作成します。

`getSendGridClient`

API キーと省略可能なベース URL 構成を持つ SendGrid メールサービスクライアントを作成します。これは同期ファクトリーであり、await は不要です。

パラメーター:

パラメーター	型	説明
`apiKey`	`string`	認証用 SendGrid API キー
`baseUrl?`	`string`	SendGrid API の省略可能なベース URL（テスト／ステージングに有用）

戻り値: MailService — sendMail メソッドを備えた構成済みメールサービス

グローバル副作用: getSendGridClient は共有 @sendgrid/mail シングルトンで mail.setApiKey(apiKey) を呼び出します。繰り返し呼び出すか複数の API キーを使うと、プロセス内のすべての SendGrid 操作に影響します。baseUrl が指定された場合は、内部で setBaseUrl も呼び出します。これは setBaseUrl を直接呼び出すのと同じシングルトン変更です。

使用方法:

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

const { getSendGridClient } = 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',
});
// SendGrid がステータスコード 202 で応答した場合は true を返します

カスタムベース URL の例:

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

const { getSendGridClient } = drivers;

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

エラー動作:

結果	動作
HTTP 202	`true` を返します
その他の HTTP ステータス	`false` を返します
SendGrid API 失敗	スローします。`mail.send()` のエラーは伝播し、`false` に吸収されません。

注記: 共通の MailService 型では、省略可能な第 2 opts 引数（MailOptions）を許可しますが、getSendGridClient は現在 sendMail(mailData) のみを実装します。logger または sandboxMode は SendGrid に渡しません。

`SendGridMail`

基になる SendGrid クライアント用に SDK ソース（src/drivers/sendgrid.ts）からエクスポートされる型です。

type SendGridMail = typeof mail & {
  client: Parameters<typeof mail.setClient>[0];
};

この型は主に、共有 SendGrid クライアントを直接構成またはテストする際に有用です。ほとんどのアプリケーションでは、getSendGridClient が返す MailService を使用してください。

`setBaseUrl`

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

グローバル副作用: setBaseUrl は mail.client.setDefaultRequest('baseUrl', baseUrl) を介して共有 @sendgrid/mail シングルトンを変更します。getSendGridClient が返す 1 つのクライアントインスタンスだけでなく、プロセス内のすべての後続 SendGrid 操作に影響します。

パラメーター:

パラメーター	型	説明
`baseUrl`	`string`	SendGrid API リクエストのベース URL（例: `'https://api.sendgrid.com/v3'`）

戻り値: void

使用方法:

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

const { setBaseUrl } = drivers;

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

📧 メール型

共通メール型は types 名前空間にあります（SDK ソース: src/types/email.ts）。

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

type MailData = types.MailData;
type MailService = types.MailService;
type MailOptions = types.MailOptions;

MailData の規則（sendMail に渡すもの）:

規則	詳細
必須フィールド	`from`、`subject`、`to`
コンテンツ	`html` または `text` の少なくとも一方が必要です。TypeScript のユニオンは両方の指定を禁止しません。
受信者	メール 1 件につき 1 受信者
添付ファイル	`MailData` 型ではサポートされません。

const email: MailData = {
  to: 'user@example.com',
  from: 'noreply@company.com',
  subject: 'Welcome!',
  text: 'Welcome to our platform',
};

完全な MailData、MailService、MailOptions 定義は src/types/email.ts を参照してください。MailOptions（logger、sandboxMode）は共通 MailService インターフェースにありますが、現在 getSendGridClient では使用されません。