通知モジュール

NotificationModuleは、MBC CQRS Serverlessフレームワークで2種類の通知機能を提供します：

• WebSocketベースの更新用のリアルタイム通知（AWS AppSync経由）
• メール送信用のメール通知（AWS SES経由）

アーキテクチャ

リアルタイム通知

概要

DynamoDBでデータ変更が発生すると、リアルタイム通知が自動的に送信されます。システムはAWS AppSyncを使用して、購読中のWebSocketクライアントに通知を配信します。

INotificationインターフェース

通知ペイロードの構造：

interface INotification {
  id: string;        // Unique notification ID (一意の通知ID)
  table: string;     // Source DynamoDB table name (ソースDynamoDBテーブル名)
  pk: string;        // Partition key of the changed item (変更されたアイテムのパーティションキー)
  sk: string;        // Sort key of the changed item (変更されたアイテムのソートキー)
  tenantCode: string; // Tenant code for filtering notifications (通知フィルタリング用のテナントコード)
  action: string;    // Type of change: 'INSERT', 'MODIFY', 'REMOVE' (変更タイプ)
  content?: object;  // Optional payload with changed data (変更データを含むオプションのペイロード)
}

AppSyncService

AppSyncServiceはリアルタイム通知をAppSyncに送信し、WebSocket経由で配信します。

メソッド: sendMessage(msg: INotification): Promise<void>

GraphQLミューテーション経由でAppSyncに通知を送信します。通知はすべての購読中のWebSocketクライアントに配信されます。

バージョン情報

sendMessage の戻り値型はバージョン1.3.0で Promise<any> から Promise<void> に変更されました。テストでこのメソッドを mockResolvedValue(null) でモックしている場合は mockResolvedValue(undefined) に更新してください。詳細はv1.3.0移行ガイドを参照してください。

await this.appSyncService.sendMessage({
  id: "unique-id",
  table: "my-table",
  pk: "tenant1#ITEM",
  sk: "ITEM#001",
  tenantCode: "tenant1",
  action: "MODIFY",
  content: { status: "updated" },
});

設定

以下の環境変数を設定してください：

APPSYNC_ENDPOINT=https://xxxxx.appsync-api.ap-northeast-1.amazonaws.com/graphql
APPSYNC_API_KEY=da2-xxxxxxxxxx  # Optional: Use API key auth instead of IAM (オプション: IAMの代わりにAPIキー認証を使用)

使用方法

import { AppSyncService, INotification } from "@mbc-cqrs-serverless/core";

@Injectable()
export class MyService {
  constructor(private readonly appSyncService: AppSyncService) {}

  async notifyClients() {
    const notification: INotification = {
      id: "notification-123",
      table: "my-table",
      pk: "tenant1#ITEM",
      sk: "ITEM#item001",
      tenantCode: "tenant1",
      action: "MODIFY",
      content: { status: "updated" },
    };

    await this.appSyncService.sendMessage(notification);
  }
}

認証

AppSyncServiceは2つの認証方法をサポートしています：

1. API キー: APPSYNC_API_KEY環境変数を設定
2. IAM署名V4: APIキーが設定されていない場合に自動的に使用

自動通知

フレームワークはデータ変更時に以下の流れで自動的に通知を送信します：

1. DynamoDBストリームがNotificationEventHandlerをトリガー
2. ハンドラーが変更情報を抽出しINotificationを作成
3. AppSyncService.sendMessage()がAppSyncに配信
4. 接続されたクライアントがWebSocket購読経由で更新を受信

NotificationEvent

NotificationEventクラスはSQSからの通知イベントを表します。IEventを実装し、通知データを含むSQSレコードをラップします。

import { NotificationEvent } from "@mbc-cqrs-serverless/core";

class NotificationEvent implements IEvent, SQSRecord {
  source: string;
  messageId: string;
  receiptHandle: string;
  body: string;              // JSON string containing INotification data (INotificationデータを含むJSON文字列)
  attributes: SQSRecordAttributes;
  messageAttributes: SQSMessageAttributes;
  md5OfBody: string;
  eventSource: string;
  eventSourceARN: string;
  awsRegion: string;

  // Creates a NotificationEvent from an SQS record (SQSレコードからNotificationEventを作成)
  fromSqsRecord(record: SQSRecord): NotificationEvent;
}

NotificationEventHandler

NotificationEventHandlerはNotificationEventを処理してAppSyncに通知を送信する組み込みイベントハンドラーです。通知モジュールを使用する際に自動的に登録されます。

import { NotificationEventHandler, NotificationEvent } from "@mbc-cqrs-serverless/core";

@EventHandler(NotificationEvent)
export class NotificationEventHandler implements IEventHandler<NotificationEvent> {
  async execute(event: NotificationEvent): Promise<void> {
    // Parses the notification from event body (イベント本文から通知をパース)
    // Sends to AppSync via sendMessage() (sendMessage()経由でAppSyncに送信)
  }
}

通常、このハンドラーと直接やり取りする必要はありません - SQSキューに通知が発行されると自動的に動作します。

AppSync Events API（オプトイン）

バージョン情報

AppSyncEventsService とデュアルパブリッシュサポートは バージョン 1.3.0 で追加されました。

概要

AppSyncEventsService は AWS AppSync Events API（スキーマ不要の HTTP pub/sub サービス）をベースにした、代替（または補完）のリアルタイムトランスポートを提供します。GraphQL サブスクリプションとは異なり、GraphQL スキーマが不要で、クライアントはワイルドカードチャンネルパスでサブスクライブします。

NOTIFICATION_TRANSPORTS=appsync-event を設定してオプトインします。NOTIFICATION_TRANSPORTS=appsync-graphql,appsync-event と両方のエンドポイントを設定すると、フレームワークは両方のトランスポートにデュアルパブリッシュし、ダウンタイムなしのマイグレーションを可能にします。

チャンネル構造

すべての通知は最も具体的な単一チャンネルにパブリッシュされます。クライアントは AppSync Events のワイルドカード（/*）を使って必要な粒度でサブスクライブします：

/{namespace}/{tenantCode}/{action}/{sanitizedId}
  seg 1        seg 2       seg 3    seg 4

クライアントの目的	サブスクライブ先
テナントの全イベント	/{namespace}/{tenantCode}/*
アクションでフィルタリング	/{namespace}/{tenantCode}/{action}/*
特定コマンドを追跡	/{namespace}/{tenantCode}/{action}/{sanitizedId}

設定

# Events API トランスポートを有効にします（Events API のみ）
NOTIFICATION_TRANSPORTS=appsync-event
APPSYNC_EVENTS_ENDPOINT=https://xxxx.appsync-api.ap-northeast-1.amazonaws.com/event
# オプション：AppSync Event API に事前作成されたネームスペースと一致する必要があります
APPSYNC_EVENTS_NAMESPACE=default

AppSync Events 環境変数 を参照してください。

GraphQL サブスクリプションからの移行

デュアルパブリッシュモードを使用して、ダウンタイムなしでクライアントを段階的に移行します：

フェーズ 1 — デュアルパブリッシュ（両方のトランスポートが有効）：

NOTIFICATION_TRANSPORTS=appsync-graphql,appsync-event
APPSYNC_EVENTS_ENDPOINT=https://xxxx.appsync-api.ap-northeast-1.amazonaws.com/event
APPSYNC_EVENTS_NAMESPACE=default
APPSYNC_ENDPOINT=https://xxxx.appsync-api.ap-northeast-1.amazonaws.com/graphql  # 設定済みのまま

フェーズ 2 — Events API のみ（全クライアントの移行完了後）：

NOTIFICATION_TRANSPORTS=appsync-event
APPSYNC_EVENTS_ENDPOINT=https://xxxx.appsync-api.ap-northeast-1.amazonaws.com/event
APPSYNC_EVENTS_NAMESPACE=default
# APPSYNC_ENDPOINT を削除

CDK インフラストラクチャ

EventApi と ChannelNamespace を自動的にプロビジョニングするには、Config に appsyncEvents を追加します：

// infra/config/config.ts
export const config: Config = {
  // ...
  appsyncEvents: {
    enabled: true,
    namespace: 'default',       // オプション、デフォルトは 'default'
    apiKeyExpireDays: 365,      // オプション、デフォルトは 365
  },
}

CDK スタックは AppSyncEventsHttpEndpoint と AppSyncEventsNamespace を出力し、Lambda と ECS に NOTIFICATION_TRANSPORTS、APPSYNC_EVENTS_ENDPOINT、APPSYNC_EVENTS_NAMESPACE を自動で注入します。

認証

AppSyncEventsService はパブリッシュに2種類の認証方式をサポートします：

1. IAM SigV4（Lambda/ECS 推奨）: パブリッシュ時に自動で使用されます。CDK スタックの grantPublish() により Lambda と ECS タスクロールに appsync:EventPublish 権限が付与されます。
2. API キー: ブラウザクライアントのサブスクライブに使用します。クライアント側（Amplify の apiKey 設定など）で設定します。サーバー側では不要です。

メール通知

EmailService

EmailServiceはAWS SESを使用してメールを送信します。

設定

SES_FROM_EMAIL=noreply@your-domain.com  # Required: Default sender address (必須: デフォルト送信者アドレス)
SES_REGION=ap-northeast-1                # Optional: SES region (オプション: SESリージョン)
SES_ENDPOINT=                            # Optional: Custom endpoint for LocalStack (オプション: LocalStack用カスタムエンドポイント)

基本的な使い方

import { EmailService, EmailNotification } from "@mbc-cqrs-serverless/core";

@Injectable()
export class MyService {
  constructor(private readonly emailService: EmailService) {}

  async sendWelcomeEmail(userEmail: string) {
    const email: EmailNotification = {
      toAddrs: [userEmail],
      subject: "Welcome to Our Service",
      body: "<h1>Welcome!</h1><p>Thank you for signing up.</p>",
    };

    await this.emailService.sendEmail(email);
  }
}

添付ファイル付きメール

import { EmailNotification, Attachment } from "@mbc-cqrs-serverless/core";
import * as fs from "fs";

const pdfBuffer = fs.readFileSync("report.pdf");

const email: EmailNotification = {
  toAddrs: ["user@example.com"],
  subject: "Monthly Report",
  body: "<p>Please find attached your monthly report.</p>",
  attachments: [
    {
      filename: "report.pdf",
      content: pdfBuffer,
      contentType: "application/pdf",
    },
  ],
};

await this.emailService.sendEmail(email);

インラインテンプレートメール

sendInlineTemplateEmail()メソッドを使用すると、SESに事前登録されたテンプレートを必要とせずに、動的データ置換を使用したテンプレートメールを送信できます。

バージョン情報

インラインテンプレートメール（sendInlineTemplateEmail()）はバージョン1.0.23で追加されました。

基本的な使い方

import { EmailService, TemplatedEmailNotification } from "@mbc-cqrs-serverless/core";

@Injectable()
export class MyService {
  constructor(private readonly emailService: EmailService) {}

  async sendWelcomeEmail(user: { name: string; email: string }) {
    const notification: TemplatedEmailNotification = {
      toAddrs: [user.email],
      template: {
        subject: "Welcome, name!",
        html: "<h1>Hello name</h1><p>Welcome to our service!</p>",
        text: "Hello name, Welcome to our service!", // Optional plain text version (オプションのプレーンテキスト版)
      },
      data: {
        name: user.name,
      },
    };

    await this.emailService.sendInlineTemplateEmail(notification);
  }
}

テンプレート構文

テンプレートは variableName プレースホルダーを使用し、dataオブジェクトの値に置き換えられます：

const notification: TemplatedEmailNotification = {
  toAddrs: ["user@example.com"],
  template: {
    subject: "Order orderId Confirmation",
    html: `
      <h1>Thank you, customerName!</h1>
      <p>Your order #orderId has been confirmed.</p>
      <p>Total: currencytotalAmount</p>
    `,
  },
  data: {
    customerName: "John Doe",
    orderId: "12345",
    currency: "$",
    totalAmount: "99.99",
  },
};

高度なテンプレート機能

バージョン情報

ネストプロパティアクセスとUnicode/日本語キーのサポートはバージョン1.0.25で追加されました。

ネストプロパティアクセス

ドット記法を使用してネストされたオブジェクトプロパティにアクセスできます：

const notification: TemplatedEmailNotification = {
  toAddrs: ["user@example.com"],
  template: {
    subject: "Welcome user.profile.firstName!",
    html: `
      <p>Hello user.profile.firstName user.profile.lastName,</p>
      <p>Your verification code is: auth.otp</p>
    `,
  },
  data: {
    user: {
      profile: {
        firstName: "John",
        lastName: "Doe",
      },
    },
    auth: {
      otp: "123456",
    },
  },
};

Unicode/日本語キーのサポート

テンプレート変数は日本語キーを含むUnicode文字をサポートします：

const notification: TemplatedEmailNotification = {
  toAddrs: ["user@example.com"],
  template: {
    subject: "注文.確認番号 - Order Confirmation",
    html: `
      <p>顧客.名前 様</p>
      <p>ご注文番号: 注文.確認番号</p>
      <p>商品: 注文.詳細.品名</p>
    `,
  },
  data: {
    "顧客": {
      "名前": "山田 太郎",
    },
    "注文": {
      "確認番号": "ORD-2024-001",
      "詳細": {
        "品名": "ワイヤレスイヤホン",
      },
    },
  },
};

プレースホルダー内の空白

プレースホルダー内の空白は自動的にトリミングされるため、前後に空白があるプレースホルダーは空白なしのものと同等です（以下の例を参照）：

// Both of these work identically (これらは同じように動作します)
template: {
  subject: "Hello {{ name }}!",  // Whitespace is trimmed (空白はトリミングされます)
  html: "<p>Hello name!</p>", // No whitespace (空白なし)
}

存在しない変数

データオブジェクトに変数が見つからない場合、プレースホルダーは出力に保持されます。これは開発中に欠落データを特定するのに役立ちます：

// データに 'missingKey' がない場合、出力に ' missingKey ' が残ります
template: {
  html: "<p>Value: missingKey</p>",
}

制限事項

セキュリティ上の理由から、テンプレート変数名には以下の制限が適用されます：

制限	値	理由
変数名の最大長	255文字	ReDoS（正規表現サービス拒否）攻撃を防止

255文字を超える変数名は置換されず、出力にそのままプレースホルダーとして残ります。

TemplatedEmailNotificationインターフェース

プロパティ	型	必須	説明
fromAddr	string	いいえ	送信者メール（設定されていない場合はSES_FROM_EMAILを使用）
toAddrs	string[]	はい	受信者メールアドレスのリスト
ccAddrs	string[]	いいえ	CC受信者
bccAddrs	string[]	いいえ	BCC受信者
replyToAddrs	string[]	いいえ	返信先アドレス
template	InlineTemplateContent	はい	件名、HTML、オプションのテキストを含むテンプレート
data	Record<string, any>	はい	テンプレート変数置換用のデータオブジェクト
configurationSetName	string	いいえ	トラッキング用のSES設定セット名

InlineTemplateContentインターフェース

プロパティ	型	必須	説明
subject	string	はい	メール件名（テンプレート変数をサポート）
html	string	はい	HTML本文（テンプレート変数をサポート）
text	string	いいえ	プレーンテキスト本文（テンプレート変数をサポート）

ローカル開発

SESアクセスなしでローカルで実行する場合、メソッドは自動的に手動テンプレートコンパイルにフォールバックし、開発中にメールフローをテストできます。

EmailNotificationインターフェース

プロパティ	型	必須	説明
fromAddr	string	いいえ	送信者メール（設定されていない場合はSES_FROM_EMAILを使用）
toAddrs	string[]	はい	受信者メールアドレスのリスト
ccAddrs	string[]	いいえ	CC受信者
bccAddrs	string[]	いいえ	BCC受信者
subject	string	はい	メール件名
body	string	はい	HTMLとしてのメール本文
replyToAddrs	string[]	いいえ	返信先アドレス
attachments	Attachment[]	いいえ	添付ファイル
emailTags	EmailTag[]	いいえ	メール分類用のタグ（SES Email Tags）

メールタグ

メールタグを使用すると、AWS SES経由で送信されたメールを分類および追跡できます。タグはSES分析、CloudWatch、およびイベント宛先でメールをフィルタリングするのに役立ちます。

バージョン情報

EmailTagsサポートはバージョン1.1.0で追加されました。

基本的な使い方

import { EmailService, EmailNotification, EmailTag } from "@mbc-cqrs-serverless/core";

const email: EmailNotification = {
  toAddrs: ["user@example.com"],
  subject: "Order Confirmation",
  body: "<p>Your order has been confirmed.</p>",
  emailTags: [
    { name: "category", value: "order-confirmation" },
    { name: "tenant", value: "tenant-123" },
    { name: "environment", value: "production" },
  ],
};

await this.emailService.sendEmail(email);

EmailTagインターフェース

プロパティ	型	必須	説明
name	string	はい	タグ名（例: 'category', 'campaign'）
value	string	はい	分類用のタグ値

ユースケース

• キャンペーントラッキング: マーケティングキャンペーンごとにメールにタグ付けしてパフォーマンスを分析
• テナント分離: マルチテナントメール分析用にテナントコードでタグ付け
• メールタイプの分類: トランザクションメールとプロモーションメールを区別
• 環境タグ付け: 開発、ステージング、本番環境間でメールを追跡

Attachmentインターフェース

プロパティ	型	必須	説明
filename	string	はい	受信者に表示されるファイル名
content	Buffer	はい	Buffer形式のファイルコンテンツ
contentType	string	いいえ	MIMEタイプ（例：'application/pdf'）

関連ドキュメント

• メールサービス - SESメール送信
• イベントハンドリングパターン - 通知がイベントとどのように統合されるか
• 環境変数 - AppSyncとSESの設定
• キュー - 通知キューイングのSQS