@aws-blocks/bb-email-client 0.1.0

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@aws-blocks/bb-email-client",
+  "version": "0.1.0",
+  "author": "Amazon Web Services",
+  "license": "Apache-2.0",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "DESIGN.md",
+    "src",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "browser": "./dist/index.browser.js",
+      "cdk": {
+        "types": "./dist/index.cdk.d.ts",
+        "default": "./dist/index.cdk.js"
+      },
+      "aws-runtime": "./dist/index.aws.js",
+      "types": "./dist/index.mock.d.ts",
+      "default": "./dist/index.mock.js"
+    }
+  },
+  "scripts": {
+    "prebuild": "node ../../scripts/generate-version.mjs EmailClient",
+    "build": "tsc --build",
+    "test": "node --test dist/*.test.js"
+  },
+  "dependencies": {
+    "@aws-blocks/core": "^0.1.0",
+    "@aws-blocks/bb-logger": "^0.1.0",
+    "@aws-sdk/client-sesv2": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.3.0"
+  },
+  "peerDependencies": {
+    "aws-cdk-lib": "^2.257.0",
+    "constructs": "^10.6.0"
+  }
+}

package/src/errors.ts

@@ -0,0 +1,28 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Typed error constants for Email. Use with `isBlocksError()` in catch blocks.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await email.send('user@example.com', { subject: 'Hi', body: 'Hello' });
+ * } catch (e: unknown) {
+ *   if (isBlocksError(e, EmailErrors.SendFailed)) {
+ *     // General send failure — check error message for details
+ *   }
+ *   if (isBlocksError(e, EmailErrors.InvalidInput)) {
+ *     // malformed input (e.g. invalid email address)
+ *   }
+ *   throw e;
+ * }
+ * ```
+ */
+export const EmailErrors = {
+	SendFailed: 'EmailSendFailedException',
+	InvalidInput: 'InvalidInputException',
+	DomainNotVerified: 'DomainNotVerifiedException',
+	AccountPaused: 'AccountSendingPausedException',
+	RateLimited: 'RateLimitedException',
+} as const;

package/src/index.aws.ts

@@ -0,0 +1,220 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { SESv2Client, SendEmailCommand, SendBulkEmailCommand } from '@aws-sdk/client-sesv2';
+import { Scope } from '@aws-blocks/core';
+import type { ScopeParent } from '@aws-blocks/core';
+import { BB_NAME, BB_VERSION } from './version.js';
+
+// Re-export public types and errors
+export { EmailErrors } from './errors.js';
+export type { EmailOptions, EmailMessage, SendResult, SendBatchResult } from './types.js';
+
+import type { EmailOptions, EmailMessage, SendResult, SendBatchResult } from './types.js';
+import { EmailErrors } from './errors.js';
+import { Logger } from '@aws-blocks/bb-logger';
+import type { ChildLogger } from '@aws-blocks/bb-logger';
+
+const BATCH_CHUNK_SIZE = 50;
+
+function blocksError(name: string, message: string): Error {
+	const err = new Error(`${name}: ${message}`);
+	err.name = name;
+	return err;
+}
+
+function mapSesError(err: any): Error {
+	const message = err.message ?? 'Unknown SES error';
+
+	if (err.name === 'MailFromDomainNotVerifiedException') {
+		return blocksError(EmailErrors.DomainNotVerified, message);
+	}
+
+	if (err.name === 'MessageRejected') {
+		const lower = message.toLowerCase();
+		if (lower.includes('not verified') || lower.includes('identity')) {
+			return blocksError(EmailErrors.DomainNotVerified, message);
+		}
+		return blocksError(EmailErrors.SendFailed, message);
+	}
+
+	if (err.name === 'AccountSuspendedException' || err.name === 'SendingPausedException') {
+		return blocksError(EmailErrors.AccountPaused, message);
+	}
+
+	if (err.name === 'TooManyRequestsException' || err.name === 'ThrottlingException') {
+		return blocksError(EmailErrors.RateLimited, message);
+	}
+
+	if (err.name === 'BadRequestException') {
+		return blocksError(EmailErrors.InvalidInput, message);
+	}
+
+	return blocksError(EmailErrors.SendFailed, message);
+}
+
+/**
+ * Send transactional emails via Amazon SES.
+ *
+ * **When to use:** You need to send transactional emails (welcome messages,
+ * password resets, notifications, order confirmations).
+ *
+ * **When NOT to use:** For bulk marketing campaigns, use a dedicated ESP.
+ * For in-app notifications, use a notification service.
+ *
+ * **Best practices:**
+ * - Verify your sending domain in SES before production use
+ * - Use a configuration set for delivery tracking
+ * - Keep email content under 40 MB
+ * - Each message is limited to 50 recipients (To + CC + BCC combined)
+ *
+ * **Scaling:** SES handles up to 200 emails/second by default (can request increase).
+ * No infrastructure to manage.
+ */
+export class EmailClient extends Scope {
+	private client: SESv2Client;
+	private fromAddress: string;
+	private replyTo?: string[];
+	private configurationSet?: string;
+
+	/** @internal Logger for internal operations. Defaults to error-level when not provided. */
+	protected log: ChildLogger;
+
+	constructor(scope: ScopeParent, id: string, options: EmailOptions) {
+		super(id, { parent: scope, bbName: BB_NAME, bbVersion: BB_VERSION });
+		this.log = options?.logger ?? new Logger(this, 'logger', { level: 'error' });
+		this.client = new SESv2Client({
+			maxAttempts: 3,
+			customUserAgent: this.buildUserAgentChain(),
+		});
+		this.fromAddress = options.fromAddress;
+		this.replyTo = options.replyTo;
+		this.configurationSet = options.configurationSet;
+	}
+
+	/**
+	 * Send an email to one or more recipients.
+	 *
+	 * Uses the SDK's built-in adaptive retry with maxAttempts: 3.
+	 *
+	 * @param message - The email message to send (to, subject, body, optional html/cc/bcc).
+	 * @returns The SES message ID for the sent email.
+	 * @throws {EmailErrors.SendFailed} General send failure.
+	 * @throws {EmailErrors.InvalidInput} If input is invalid (e.g. malformed address, too many recipients).
+	 * @throws {EmailErrors.DomainNotVerified} If the sending domain is not verified.
+	 * @throws {EmailErrors.AccountPaused} If account sending is paused.
+	 * @throws {EmailErrors.RateLimited} If rate limit is exceeded.
+	 */
+	async send(message: EmailMessage): Promise<SendResult> {
+		const { to, subject, body, html, cc, bcc } = message;
+		const recipients = Array.isArray(to) ? to : [to];
+
+		const command = new SendEmailCommand({
+			FromEmailAddress: this.fromAddress,
+			Destination: {
+				ToAddresses: recipients,
+				...(cc?.length ? { CcAddresses: cc } : {}),
+				...(bcc?.length ? { BccAddresses: bcc } : {}),
+			},
+			...(this.replyTo && { ReplyToAddresses: this.replyTo }),
+			Content: {
+				Simple: {
+					Subject: { Data: subject },
+					Body: {
+						Text: { Data: body },
+						...(html ? { Html: { Data: html } } : {}),
+					},
+				},
+			},
+			...(this.configurationSet ? { ConfigurationSetName: this.configurationSet } : {}),
+		});
+
+		try {
+			const response = await this.client.send(command);
+			return { messageId: response.MessageId ?? '' };
+		} catch (err: any) {
+			if (err.name && err.name in EmailErrors) throw err;
+			throw mapSesError(err);
+		}
+	}
+
+	/**
+	 * Send a batch of email messages using the SES SendBulkEmail API with inline passthrough templates.
+	 *
+	 * Messages are chunked into groups of 50 destinations per API call (SES limit).
+	 *
+	 * TODO: Add retry logic for transient failures (throttling, 5xx).
+	 *
+	 * @param messages - Array of email messages to send.
+	 * @returns Result with per-message status in the same order as the input array.
+	 */
+	async sendBatch(messages: EmailMessage[]): Promise<SendBatchResult> {
+		const results: Array<{ status: 'success' | 'failed'; messageId?: string; error?: string }> =
+			new Array(messages.length);
+
+		// Process in chunks of BATCH_CHUNK_SIZE
+		for (let chunkStart = 0; chunkStart < messages.length; chunkStart += BATCH_CHUNK_SIZE) {
+			const chunkIndices = messages
+				.slice(chunkStart, chunkStart + BATCH_CHUNK_SIZE)
+				.map((_, i) => chunkStart + i);
+			const chunk = chunkIndices.map(idx => messages[idx]);
+
+			const command = new SendBulkEmailCommand({
+				FromEmailAddress: this.fromAddress,
+				...(this.replyTo && { ReplyToAddresses: this.replyTo }),
+				...(this.configurationSet ? { ConfigurationSetName: this.configurationSet } : {}),
+				DefaultContent: {
+					Template: {
+						TemplateContent: {
+							Subject: '{{subject}}',
+							Html: '{{html}}',
+							Text: '{{body}}',
+						},
+						TemplateData: JSON.stringify({ subject: '', body: '', html: '' }),
+					},
+				},
+				BulkEmailEntries: chunk.map(msg => ({
+					Destination: {
+						ToAddresses: Array.isArray(msg.to) ? msg.to : [msg.to],
+						CcAddresses: msg.cc || [],
+						BccAddresses: msg.bcc || [],
+					},
+					ReplacementEmailContent: {
+						ReplacementTemplate: {
+							ReplacementTemplateData: JSON.stringify({
+								subject: msg.subject,
+								body: msg.body,
+								...(msg.html ? { html: msg.html } : { html: msg.body }),
+							}),
+						},
+					},
+				})),
+			});
+
+			try {
+				const response = await this.client.send(command);
+				const bulkResults = response.BulkEmailEntryResults ?? [];
+
+				for (let i = 0; i < chunkIndices.length; i++) {
+					const globalIdx = chunkIndices[i];
+					const entry = bulkResults[i];
+
+					if (entry?.Status === 'SUCCESS') {
+						results[globalIdx] = { status: 'success', messageId: entry.MessageId ?? '' };
+					} else {
+						const errorMsg = entry?.Error ?? 'Unknown bulk send error';
+						results[globalIdx] = { status: 'failed', error: errorMsg };
+					}
+				}
+			} catch (err: any) {
+				// Entire chunk failed — mark all as failed
+				for (const globalIdx of chunkIndices) {
+					const mapped = mapSesError(err);
+					results[globalIdx] = { status: 'failed', error: mapped.message };
+				}
+			}
+		}
+
+		return { results };
+	}
+}

package/src/index.browser.ts

@@ -0,0 +1,7 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+// Browser stub - Email runs server-side only
+export class EmailClient {
+  constructor(...args: any[]) {}
+}

package/src/index.cdk.ts

@@ -0,0 +1,49 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { CfnConfigurationSet } from 'aws-cdk-lib/aws-ses';
+import { Effect, PolicyStatement } from 'aws-cdk-lib/aws-iam';
+import { Stack } from 'aws-cdk-lib';
+import { Scope } from '@aws-blocks/core/cdk';
+import type { ScopeParent } from '@aws-blocks/core';
+
+// Re-export public types and errors (no runtime dependencies)
+export { EmailErrors } from './errors.js';
+export type { EmailOptions, EmailMessage, SendResult, SendBatchResult } from './types.js';
+
+import type { EmailOptions } from './types.js';
+
+export class EmailClient extends Scope {
+	constructor(scope: ScopeParent, id: string, options: EmailOptions) {
+		super(id, { parent: scope });
+
+		console.warn(
+			`\n⚠️  [Email] Prerequisite: Domain for "${options.fromAddress}" must be verified in SES.\n` +
+			`   Guide: https://docs.aws.amazon.com/ses/latest/dg/creating-identities.html\n`
+		);
+
+		// TODO: Add a CDK custom resource that validates the SES email identity at deploy time.
+		// Deploy time is the earliest point where AWS credentials are available to check SES state.
+		// The custom resource should:
+		//   1. Call sesv2:GetEmailIdentity for the domain extracted from fromAddress
+		//   2. If not verified: emit a CloudFormation warning (do not fail the deployment)
+		//   3. Include a link to the SES identity setup guide in the warning message
+
+		// Grant the Lambda handler permission to send emails
+		// Scoped to this account's SES identities rather than '*'
+		this.handler.addToRolePolicy(new PolicyStatement({
+			effect: Effect.ALLOW,
+			actions: [
+				'ses:SendEmail',
+				'ses:SendBulkEmail',
+				'ses:SendRawEmail',
+				'ses:SendTemplatedEmail',
+				'ses:SendBulkTemplatedEmail',
+			],
+			resources: [
+				`arn:aws:ses:*:${Stack.of(this).account}:identity/*`,
+				`arn:aws:ses:*:${Stack.of(this).account}:configuration-set/*`,
+			],
+		}));
+	}
+}

package/src/index.mock.ts

@@ -0,0 +1,231 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { Scope } from '@aws-blocks/core';
+import { getMockDataDir } from '@aws-blocks/core/bb-utils';
+import type { ScopeParent } from '@aws-blocks/core';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { BB_NAME, BB_VERSION } from './version.js';
+
+// ── Public types ────────────────────────────────────────────────────────────
+
+export {
+	EmailErrors,
+} from './errors.js';
+export type {
+	EmailOptions,
+	EmailMessage,
+	SendResult,
+	SendBatchResult,
+} from './types.js';
+
+import type { EmailOptions, EmailMessage, SendResult, SendBatchResult } from './types.js';
+import { EmailErrors } from './errors.js';
+import { Logger } from '@aws-blocks/bb-logger';
+import type { ChildLogger } from '@aws-blocks/bb-logger';
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+const MAX_RECIPIENTS_PER_MESSAGE = 50;
+const MAX_MESSAGE_BYTES = 40 * 1024 * 1024; // 40 MB
+const LOG_TRUNCATE_LENGTH = 80;
+
+function truncate(text: string, maxLen: number = LOG_TRUNCATE_LENGTH): string {
+	const oneLine = text.replace(/\n/g, ' ').trim();
+	if (oneLine.length <= maxLen) return oneLine;
+	return oneLine.substring(0, maxLen) + '...';
+}
+
+// Basic RFC 5322 email regex
+const EMAIL_REGEX = /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;
+
+function blocksError(name: string, message: string): Error {
+	const err = new Error(`${name}: ${message}`);
+	err.name = name;
+	return err;
+}
+
+function validateEmailAddress(address: string): void {
+	if (!EMAIL_REGEX.test(address)) {
+		throw blocksError(EmailErrors.InvalidInput, `Invalid email address: ${address}`);
+	}
+}
+
+function validateAddresses(addresses: string | string[]): void {
+	const list = Array.isArray(addresses) ? addresses : [addresses];
+	for (const addr of list) {
+		validateEmailAddress(addr);
+	}
+}
+
+function countRecipients(msg: { to: string | string[]; cc?: string[]; bcc?: string[] }): number {
+	const toCount = Array.isArray(msg.to) ? msg.to.length : 1;
+	const ccCount = msg.cc?.length ?? 0;
+	const bccCount = msg.bcc?.length ?? 0;
+	return toCount + ccCount + bccCount;
+}
+
+function validateRecipientCount(msg: { to: string | string[]; cc?: string[]; bcc?: string[] }): void {
+	const count = countRecipients(msg);
+	if (count > MAX_RECIPIENTS_PER_MESSAGE) {
+		throw blocksError(
+			EmailErrors.InvalidInput,
+			`Recipient count exceeds ${MAX_RECIPIENTS_PER_MESSAGE}.`,
+		);
+	}
+}
+
+function generateMockMessageId(): string {
+	return `mock-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}
+
+interface StoredEmail {
+	to: string | string[];
+	subject: string;
+	body: string;
+	html?: string;
+	from: string;
+	messageId: string;
+	timestamp: string;
+}
+
+// ── Email (mock) ────────────────────────────────────────────────────────────
+
+/**
+ * Send transactional emails via Amazon SES.
+ *
+ * **When to use:** You need to send transactional emails (welcome messages,
+ * password resets, notifications, order confirmations).
+ *
+ * **When NOT to use:** For bulk marketing campaigns, use a dedicated ESP.
+ * For in-app notifications, use a notification service.
+ *
+ * **Best practices:**
+ * - Verify your sending domain in SES before production use
+ * - Use a configuration set for delivery tracking
+ * - Keep email content under 40 MB
+ * - Each message is limited to 50 recipients (To + CC + BCC combined)
+ * - Batch sends use the SES SendBulkEmail API (max 50 destinations per API call)
+ *
+ * **Scaling:** SES handles up to 200 emails/second by default (can request increase).
+ * No infrastructure to manage.
+ */
+export class EmailClient extends Scope {
+	private filePath: string;
+	private emails: StoredEmail[];
+	private fromAddress: string;
+	private replyTo?: string[];
+
+	/** @internal Logger for internal operations. Defaults to error-level when not provided. */
+	protected log: ChildLogger;
+
+	constructor(scope: ScopeParent, id: string, options: EmailOptions) {
+		super(id, { parent: scope, bbName: BB_NAME, bbVersion: BB_VERSION });
+		this.log = options?.logger ?? new Logger(this, 'logger', { level: 'error' });
+		this.fromAddress = options.fromAddress;
+		this.replyTo = options.replyTo;
+		this.filePath = join(getMockDataDir(this), 'emails.json');
+		this.emails = this.loadFromDisk();
+	}
+
+	/**
+	 * Send an email to one or more recipients.
+	 *
+	 * @param message - The email message to send (to, subject, body, optional html/cc/bcc).
+	 * @returns The mock message ID for the sent email.
+	 * @throws {EmailErrors.InvalidInput} If any address fails validation.
+	 * @throws {EmailErrors.SendFailed} If the message exceeds 40 MB or recipient count exceeds 50.
+	 */
+	async send(message: EmailMessage): Promise<SendResult> {
+		const { to, subject, body, html, cc, bcc } = message;
+
+		validateAddresses(to);
+		validateEmailAddress(this.fromAddress);
+		if (cc) validateAddresses(cc);
+		if (bcc) validateAddresses(bcc);
+
+		validateRecipientCount({ to, cc, bcc });
+
+		const messageSize = Buffer.byteLength(
+			JSON.stringify(message),
+			'utf8',
+		);
+		if (messageSize > MAX_MESSAGE_BYTES) {
+			throw blocksError(EmailErrors.SendFailed, `Message size ${messageSize} bytes exceeds the 40 MB limit`);
+		}
+
+		const recipients = Array.isArray(to) ? to : [to];
+		const messageId = generateMockMessageId();
+		const lines = [
+			`[Email:${this.id}]`,
+			`  Recipient: ${recipients.join(', ')}`,
+			`  Subject:   ${subject}`,
+			`  Body:      ${truncate(body)}`,
+		];
+		if (html) {
+			lines.push(`  HTML:      ${truncate(html)}`);
+		}
+		console.log(lines.join('\n'));
+
+		const stored: StoredEmail = {
+			to,
+			subject,
+			body,
+			html,
+			from: this.fromAddress,
+			messageId,
+			timestamp: new Date().toISOString(),
+		};
+		this.emails.push(stored);
+		this.flushToDisk();
+
+		return { messageId };
+	}
+
+	/**
+	 * Send a batch of email messages.
+	 *
+	 * Each individual message must not exceed 50 recipients (To + CC + BCC combined).
+	 * Messages exceeding this limit are marked as failed in the results (not thrown).
+	 * This matches SES SendBulkEmail behavior which returns per-entry status.
+	 *
+	 * @param messages - Array of email messages to send.
+	 * @returns Result with per-message status in the same order as the input array.
+	 *          Each entry has status ('success' | 'failed'), messageId (on success), or error (on failure).
+	 */
+	async sendBatch(messages: EmailMessage[]): Promise<SendBatchResult> {
+		const results: Array<{ status: 'success' | 'failed'; messageId?: string; error?: string }> = [];
+
+		for (let i = 0; i < messages.length; i++) {
+			const msg = messages[i];
+			if (countRecipients(msg) > MAX_RECIPIENTS_PER_MESSAGE) {
+				results.push({ status: 'failed', error: `Recipient count exceeds ${MAX_RECIPIENTS_PER_MESSAGE}.` });
+				continue;
+			}
+			try {
+				const sendResult = await this.send(msg);
+				results.push({ status: 'success', messageId: sendResult.messageId });
+			} catch (err: any) {
+				results.push({ status: 'failed', error: err.message ?? 'Unknown error' });
+			}
+		}
+
+		return { results };
+	}
+
+	// ── Disk persistence ──────────────────────────────────────────────────
+
+	private loadFromDisk(): StoredEmail[] {
+		if (!existsSync(this.filePath)) return [];
+		try {
+			return JSON.parse(readFileSync(this.filePath, 'utf8'));
+		} catch {
+			return [];
+		}
+	}
+
+	private flushToDisk(): void {
+		writeFileSync(this.filePath, JSON.stringify(this.emails, null, 2));
+	}
+}