@aws-blocks/bb-email-client 0.1.0

package/dist/index.cdk.js

@@ -0,0 +1,36 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { Effect, PolicyStatement } from 'aws-cdk-lib/aws-iam';
+import { Stack } from 'aws-cdk-lib';
+import { Scope } from '@aws-blocks/core/cdk';
+// Re-export public types and errors (no runtime dependencies)
+export { EmailErrors } from './errors.js';
+export class EmailClient extends Scope {
+    constructor(scope, id, options) {
+        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/dist/index.mock.d.ts

@@ -0,0 +1,58 @@
+import { Scope } from '@aws-blocks/core';
+import type { ScopeParent } from '@aws-blocks/core';
+export { EmailErrors, } from './errors.js';
+export type { EmailOptions, EmailMessage, SendResult, SendBatchResult, } from './types.js';
+import type { EmailOptions, EmailMessage, SendResult, SendBatchResult } from './types.js';
+import type { ChildLogger } from '@aws-blocks/bb-logger';
+/**
+ * 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 declare class EmailClient extends Scope {
+    private filePath;
+    private emails;
+    private fromAddress;
+    private replyTo?;
+    /** @internal Logger for internal operations. Defaults to error-level when not provided. */
+    protected log: ChildLogger;
+    constructor(scope: ScopeParent, id: string, options: EmailOptions);
+    /**
+     * 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.
+     */
+    send(message: EmailMessage): Promise<SendResult>;
+    /**
+     * 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).
+     */
+    sendBatch(messages: EmailMessage[]): Promise<SendBatchResult>;
+    private loadFromDisk;
+    private flushToDisk;
+}
+//# sourceMappingURL=index.mock.d.ts.map

package/dist/index.mock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mock.d.ts","sourceRoot":"","sources":["../src/index.mock.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAOpD,OAAO,EACN,WAAW,GACX,MAAM,aAAa,CAAC;AACrB,YAAY,EACX,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,eAAe,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAG1F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAqEzD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACrC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,OAAO,CAAC,CAAW;IAE3B,2FAA2F;IAC3F,SAAS,CAAC,GAAG,EAAE,WAAW,CAAC;gBAEf,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY;IASjE;;;;;;;OAOG;IACG,IAAI,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC;IA8CtD;;;;;;;;;;OAUG;IACG,SAAS,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,eAAe,CAAC;IAsBnE,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,WAAW;CAGnB"}

package/dist/index.mock.js

@@ -0,0 +1,179 @@
+// 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 { 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';
+import { EmailErrors } from './errors.js';
+import { Logger } 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, maxLen = LOG_TRUNCATE_LENGTH) {
+    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, message) {
+    const err = new Error(`${name}: ${message}`);
+    err.name = name;
+    return err;
+}
+function validateEmailAddress(address) {
+    if (!EMAIL_REGEX.test(address)) {
+        throw blocksError(EmailErrors.InvalidInput, `Invalid email address: ${address}`);
+    }
+}
+function validateAddresses(addresses) {
+    const list = Array.isArray(addresses) ? addresses : [addresses];
+    for (const addr of list) {
+        validateEmailAddress(addr);
+    }
+}
+function countRecipients(msg) {
+    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) {
+    const count = countRecipients(msg);
+    if (count > MAX_RECIPIENTS_PER_MESSAGE) {
+        throw blocksError(EmailErrors.InvalidInput, `Recipient count exceeds ${MAX_RECIPIENTS_PER_MESSAGE}.`);
+    }
+}
+function generateMockMessageId() {
+    return `mock-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}
+// ── 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 {
+    filePath;
+    emails;
+    fromAddress;
+    replyTo;
+    /** @internal Logger for internal operations. Defaults to error-level when not provided. */
+    log;
+    constructor(scope, id, options) {
+        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) {
+        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 = {
+            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) {
+        const results = [];
+        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) {
+                results.push({ status: 'failed', error: err.message ?? 'Unknown error' });
+            }
+        }
+        return { results };
+    }
+    // ── Disk persistence ──────────────────────────────────────────────────
+    loadFromDisk() {
+        if (!existsSync(this.filePath))
+            return [];
+        try {
+            return JSON.parse(readFileSync(this.filePath, 'utf8'));
+        }
+        catch {
+            return [];
+        }
+    }
+    flushToDisk() {
+        writeFileSync(this.filePath, JSON.stringify(this.emails, null, 2));
+    }
+}

package/dist/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/dist/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":""}

package/dist/index.test.js

@@ -0,0 +1,274 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { test, beforeEach } from 'node:test';
+import assert from 'node:assert';
+import { rmSync, existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { EmailClient, EmailErrors } from './index.mock.js';
+// Clean mock data between tests to avoid cross-contamination
+beforeEach(() => {
+    try {
+        rmSync('.bb-data', { recursive: true, force: true });
+    }
+    catch { }
+});
+// ── Single recipient ────────────────────────────────────────────────────────
+test('send to single recipient returns messageId', async () => {
+    const emailClient = new EmailClient({ id: 'root' }, 'test', {
+        fromAddress: 'noreply@example.com',
+    });
+    const result = await emailClient.send({
+        to: 'user@example.com',
+        subject: 'Hello',
+        body: 'World',
+    });
+    assert.ok(result.messageId);
+    assert.ok(result.messageId.startsWith('mock-'));
+    // Verify persistence
+    const dataDir = join(process.cwd(), '.bb-data', 'root-test');
+    assert.ok(existsSync(join(dataDir, 'emails.json')));
+    const stored = JSON.parse(readFileSync(join(dataDir, 'emails.json'), 'utf8'));
+    assert.strictEqual(stored.length, 1);
+    assert.strictEqual(stored[0].to, 'user@example.com');
+    assert.strictEqual(stored[0].subject, 'Hello');
+    assert.strictEqual(stored[0].body, 'World');
+    assert.strictEqual(stored[0].messageId, result.messageId);
+});
+// ── Multiple recipients ─────────────────────────────────────────────────────
+test('send to multiple recipients', async () => {
+    const emailClient = new EmailClient({ id: 'root' }, 'multi', {
+        fromAddress: 'noreply@example.com',
+    });
+    const result = await emailClient.send({
+        to: ['alice@example.com', 'bob@example.com'],
+        subject: 'Team Update',
+        body: 'Check this out',
+    });
+    assert.ok(result.messageId);
+    const dataDir = join(process.cwd(), '.bb-data', 'root-multi');
+    const stored = JSON.parse(readFileSync(join(dataDir, 'emails.json'), 'utf8'));
+    assert.strictEqual(stored.length, 1);
+    assert.deepStrictEqual(stored[0].to, ['alice@example.com', 'bob@example.com']);
+});
+// ── HTML email support ──────────────────────────────────────────────────────
+test('send HTML email', async () => {
+    const emailClient = new EmailClient({ id: 'root' }, 'html', {
+        fromAddress: 'noreply@example.com',
+    });
+    const result = await emailClient.send({
+        to: 'user@example.com',
+        subject: 'Rich Email',
+        body: 'Plain fallback',
+        html: '<h1>Hello</h1>',
+    });
+    assert.ok(result.messageId);
+    const dataDir = join(process.cwd(), '.bb-data', 'root-html');
+    const stored = JSON.parse(readFileSync(join(dataDir, 'emails.json'), 'utf8'));
+    assert.strictEqual(stored[0].html, '<h1>Hello</h1>');
+    assert.strictEqual(stored[0].body, 'Plain fallback');
+});
+// ── Invalid address rejection ───────────────────────────────────────────────
+test('rejects invalid recipient address', async () => {
+    const emailClient = new EmailClient({ id: 'root' }, 'invalid', {
+        fromAddress: 'noreply@example.com',
+    });
+    await assert.rejects(() => emailClient.send({ to: 'not-an-email', subject: 'Test', body: 'Body' }), (err) => err.name === EmailErrors.InvalidInput);
+});
+test('rejects invalid from address', async () => {
+    const emailClient = new EmailClient({ id: 'root' }, 'badfrom', {
+        fromAddress: 'bad-address',
+    });
+    await assert.rejects(() => emailClient.send({ to: 'user@example.com', subject: 'Test', body: 'Body' }), (err) => err.name === EmailErrors.InvalidInput);
+});
+test('rejects if any address in array is invalid', async () => {
+    const emailClient = new EmailClient({ id: 'root' }, 'mixedaddr', {
+        fromAddress: 'noreply@example.com',
+    });
+    await assert.rejects(() => emailClient.send({ to: ['valid@example.com', 'invalid@@'], subject: 'Test', body: 'Body' }), (err) => err.name === EmailErrors.InvalidInput);
+});
+// ── Per-message recipient limit (50 recipients) ─────────────────────────────
+test('rejects single message with more than 50 recipients', async () => {
+    const emailClient = new EmailClient({ id: 'root' }, 'toomany', {
+        fromAddress: 'noreply@example.com',
+    });
+    const recipients = Array.from({ length: 51 }, (_, i) => `user${i}@example.com`);
+    await assert.rejects(() => emailClient.send({ to: recipients, subject: 'Test', body: 'Body' }), (err) => {
+        assert.strictEqual(err.name, EmailErrors.InvalidInput);
+        assert.ok(err.message.includes('50'));
+        return true;
+    });
+});
+test('rejects message with combined To + CC + BCC exceeding 50', async () => {
+    const emailClient = new EmailClient({ id: 'root' }, 'combined', {
+        fromAddress: 'noreply@example.com',
+    });
+    const toAddrs = Array.from({ length: 20 }, (_, i) => `to${i}@example.com`);
+    const ccAddrs = Array.from({ length: 20 }, (_, i) => `cc${i}@example.com`);
+    const bccAddrs = Array.from({ length: 11 }, (_, i) => `bcc${i}@example.com`);
+    await assert.rejects(() => emailClient.send({ to: toAddrs, subject: 'Test', body: 'Body', cc: ccAddrs, bcc: bccAddrs }), (err) => {
+        assert.strictEqual(err.name, EmailErrors.InvalidInput);
+        assert.ok(err.message.includes('50'));
+        return true;
+    });
+});
+test('allows message with exactly 50 recipients', async () => {
+    const emailClient = new EmailClient({ id: 'root' }, 'exact50', {
+        fromAddress: 'noreply@example.com',
+    });
+    const recipients = Array.from({ length: 50 }, (_, i) => `user${i}@example.com`);
+    const result = await emailClient.send({ to: recipients, subject: 'Test', body: 'Body' });
+    assert.ok(result.messageId);
+    const dataDir = join(process.cwd(), '.bb-data', 'root-exact50');
+    const stored = JSON.parse(readFileSync(join(dataDir, 'emails.json'), 'utf8'));
+    assert.strictEqual(stored.length, 1);
+});
+// ── Batch: per-message recipient limit ──────────────────────────────────────
+test('sendBatch marks message with more than 50 recipients as failed', async () => {
+    const emailClient = new EmailClient({ id: 'root' }, 'batchrecip', {
+        fromAddress: 'noreply@example.com',
+    });
+    const recipients = Array.from({ length: 51 }, (_, i) => `user${i}@example.com`);
+    const result = await emailClient.sendBatch([
+        { to: recipients, subject: 'Too many', body: 'Body' },
+    ]);
+    assert.strictEqual(result.results.length, 1);
+    assert.strictEqual(result.results[0].status, 'failed');
+    assert.ok(result.results[0].error.includes('50'));
+});
+// ── Batch: returns SendBatchResult ──────────────────────────────────────────
+test('sendBatch returns SendBatchResult with results array in input order', async () => {
+    const emailClient = new EmailClient({ id: 'root' }, 'batchresult', {
+        fromAddress: 'noreply@example.com',
+    });
+    const messages = Array.from({ length: 3 }, (_, i) => ({
+        to: `user${i}@example.com`,
+        subject: `Msg ${i}`,
+        body: `Body ${i}`,
+    }));
+    const result = await emailClient.sendBatch(messages);
+    assert.strictEqual(result.results.length, 3);
+    for (let i = 0; i < 3; i++) {
+        assert.strictEqual(result.results[i].status, 'success');
+        assert.ok(result.results[i].messageId);
+    }
+});
+test('sendBatch reports partial failures in correct positions', async () => {
+    const emailClient = new EmailClient({ id: 'root' }, 'batchpartial', {
+        fromAddress: 'noreply@example.com',
+    });
+    const messages = [
+        { to: 'valid@example.com', subject: 'Good', body: 'Body' },
+        { to: 'invalid@@', subject: 'Bad', body: 'Body' },
+        { to: 'also-valid@example.com', subject: 'Good', body: 'Body' },
+    ];
+    const result = await emailClient.sendBatch(messages);
+    assert.strictEqual(result.results.length, 3);
+    assert.strictEqual(result.results[0].status, 'success');
+    assert.ok(result.results[0].messageId);
+    assert.strictEqual(result.results[1].status, 'failed');
+    assert.ok(result.results[1].error.includes('Invalid'));
+    assert.strictEqual(result.results[2].status, 'success');
+    assert.ok(result.results[2].messageId);
+});
+test('sendBatch returns all failures without throwing when ALL messages fail', async () => {
+    const emailClient = new EmailClient({ id: 'root' }, 'batchallfail', {
+        fromAddress: 'noreply@example.com',
+    });
+    const messages = [
+        { to: 'invalid@@', subject: 'Bad1', body: 'Body' },
+        { to: 'also-invalid@@', subject: 'Bad2', body: 'Body' },
+    ];
+    const result = await emailClient.sendBatch(messages);
+    assert.strictEqual(result.results.length, 2);
+    assert.strictEqual(result.results[0].status, 'failed');
+    assert.ok(result.results[0].error.includes('Invalid'));
+    assert.strictEqual(result.results[1].status, 'failed');
+    assert.ok(result.results[1].error.includes('Invalid'));
+});
+// ── Batch: many messages succeeds ───────────────────────────────────────────
+test('sendBatch sends many messages (no batch size limit)', async () => {
+    const emailClient = new EmailClient({ id: 'root' }, 'bigbatch', {
+        fromAddress: 'noreply@example.com',
+    });
+    const messages = Array.from({ length: 100 }, (_, i) => ({
+        to: `user${i}@example.com`,
+        subject: `Msg ${i}`,
+        body: `Body ${i}`,
+    }));
+    const result = await emailClient.sendBatch(messages);
+    assert.strictEqual(result.results.length, 100);
+    for (const r of result.results) {
+        assert.strictEqual(r.status, 'success');
+        assert.ok(r.messageId);
+    }
+    const dataDir = join(process.cwd(), '.bb-data', 'root-bigbatch');
+    const stored = JSON.parse(readFileSync(join(dataDir, 'emails.json'), 'utf8'));
+    assert.strictEqual(stored.length, 100);
+});
+test('sendBatch sends all messages within small batch', async () => {
+    const emailClient = new EmailClient({ id: 'root' }, 'batchok', {
+        fromAddress: 'noreply@example.com',
+    });
+    const messages = Array.from({ length: 3 }, (_, i) => ({
+        to: `user${i}@example.com`,
+        subject: `Msg ${i}`,
+        body: `Body ${i}`,
+    }));
+    const result = await emailClient.sendBatch(messages);
+    assert.strictEqual(result.results.length, 3);
+    for (const r of result.results) {
+        assert.strictEqual(r.status, 'success');
+    }
+    const dataDir = join(process.cwd(), '.bb-data', 'root-batchok');
+    const stored = JSON.parse(readFileSync(join(dataDir, 'emails.json'), 'utf8'));
+    assert.strictEqual(stored.length, 3);
+});
+// ── File persistence ────────────────────────────────────────────────────────
+test('emails persist across instances', async () => {
+    const emailClient1 = new EmailClient({ id: 'root' }, 'persist', {
+        fromAddress: 'noreply@example.com',
+    });
+    await emailClient1.send({ to: 'user@example.com', subject: 'First', body: 'First body' });
+    // New instance with same scope path reads from disk
+    const emailClient2 = new EmailClient({ id: 'root' }, 'persist', {
+        fromAddress: 'noreply@example.com',
+    });
+    await emailClient2.send({ to: 'user2@example.com', subject: 'Second', body: 'Second body' });
+    const dataDir = join(process.cwd(), '.bb-data', 'root-persist');
+    const stored = JSON.parse(readFileSync(join(dataDir, 'emails.json'), 'utf8'));
+    assert.strictEqual(stored.length, 2);
+    assert.strictEqual(stored[0].subject, 'First');
+    assert.strictEqual(stored[1].subject, 'Second');
+});
+// ── Message size limit ──────────────────────────────────────────────────────
+test('rejects messages exceeding 40 MB', async () => {
+    const emailClient = new EmailClient({ id: 'root' }, 'big', {
+        fromAddress: 'noreply@example.com',
+    });
+    const bigBody = 'x'.repeat(41 * 1024 * 1024);
+    await assert.rejects(() => emailClient.send({ to: 'user@example.com', subject: 'Big', body: bigBody }), (err) => err.name === EmailErrors.SendFailed);
+});
+// ── Error constants ─────────────────────────────────────────────────────────
+test('EmailErrors has expected constants', () => {
+    assert.strictEqual(EmailErrors.SendFailed, 'EmailSendFailedException');
+    assert.strictEqual(EmailErrors.InvalidInput, 'InvalidInputException');
+    assert.strictEqual(EmailErrors.DomainNotVerified, 'DomainNotVerifiedException');
+    assert.strictEqual(EmailErrors.AccountPaused, 'AccountSendingPausedException');
+    assert.strictEqual(EmailErrors.RateLimited, 'RateLimitedException');
+});
+// ── fullId generation ───────────────────────────────────────────────────────
+test('fullId generation with parent', () => {
+    const emailClient = new EmailClient({ id: 'parent' }, 'child', {
+        fromAddress: 'noreply@example.com',
+    });
+    assert.strictEqual(emailClient.fullId, 'parent-child');
+});
+// ── messageId uniqueness ────────────────────────────────────────────────────
+test('each send returns a unique messageId', async () => {
+    const emailClient = new EmailClient({ id: 'root' }, 'unique', {
+        fromAddress: 'noreply@example.com',
+    });
+    const r1 = await emailClient.send({ to: 'user@example.com', subject: 'A', body: 'a' });
+    const r2 = await emailClient.send({ to: 'user@example.com', subject: 'B', body: 'b' });
+    assert.notStrictEqual(r1.messageId, r2.messageId);
+});

package/dist/types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Shared types for Email. Imported by mock, aws, cdk, and browser entry points.
+ * This file has zero runtime dependencies — types only.
+ */
+import type { ChildLogger } from '@aws-blocks/bb-logger';
+/**
+ * Configuration options for the Email building block instance.
+ *
+ * @param fromAddress - The verified sender email address (e.g., "noreply@example.com").
+ * @param replyTo - Optional reply-to address(es).
+ * @param configurationSet - Optional SES configuration set name for tracking.
+ */
+export interface EmailOptions {
+    /** The verified sender email address. */
+    fromAddress: string;
+    /** Optional reply-to address(es). */
+    replyTo?: string[];
+    /** Optional SES configuration set name for tracking/events. */
+    configurationSet?: string;
+    /** Optional logger for internal operations. When omitted, a default Logger at error level is created. */
+    logger?: ChildLogger;
+}
+/**
+ * A complete email message used for both `send()` and `sendBatch()`.
+ *
+ * @param to - Recipient email address(es).
+ * @param subject - The email subject line.
+ * @param body - Plain text body content.
+ * @param html - Optional HTML body content.
+ * @param cc - Optional CC recipient address(es).
+ * @param bcc - Optional BCC recipient address(es).
+ */
+export interface EmailMessage {
+    /** Recipient email address(es). */
+    to: string | string[];
+    /** The email subject line. */
+    subject: string;
+    /** Plain text body content. */
+    body: string;
+    /** Optional HTML body content. */
+    html?: string;
+    /** Optional CC recipient address(es). */
+    cc?: string[];
+    /** Optional BCC recipient address(es). */
+    bcc?: string[];
+}
+/**
+ * Result of a `send()` operation.
+ *
+ * @param messageId - The SES message ID for the sent email.
+ */
+export interface SendResult {
+    /** The SES message ID for the sent email. */
+    messageId: string;
+}
+/**
+ * Result of a `sendBatch()` operation with per-entry status.
+ *
+ * The `results` array is in the same order as the input `messages` array,
+ * so callers can correlate each result to its corresponding input message by index.
+ *
+ * @param results - Array of per-message results matching input order.
+ */
+export interface SendBatchResult {
+    /** Per-message results in the same order as the input messages array. */
+    results: Array<{
+        /** Whether this message was sent successfully or failed permanently. */
+        status: 'success' | 'failed';
+        /** The SES message ID, present when status is 'success'. */
+        messageId?: string;
+        /** Error description, present when status is 'failed'. */
+        error?: string;
+    }>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC5B,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,+DAA+D;IAC/D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,yGAAyG;IACzG,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC5B,mCAAmC;IACnC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACtB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IACd,0CAA0C;IAC1C,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IAC1B,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC/B,yEAAyE;IACzE,OAAO,EAAE,KAAK,CAAC;QACd,wEAAwE;QACxE,MAAM,EAAE,SAAS,GAAG,QAAQ,CAAC;QAC7B,4DAA4D;QAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,0DAA0D;QAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;KACf,CAAC,CAAC;CACH"}

package/dist/types.js

@@ -0,0 +1,3 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+export {};

package/dist/version.d.ts

@@ -0,0 +1,3 @@
+export declare const BB_NAME = "EmailClient";
+export declare const BB_VERSION = "0.1.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,OAAO,gBAAgB,CAAC;AACrC,eAAO,MAAM,UAAU,UAAU,CAAC"}

package/dist/version.js

@@ -0,0 +1,3 @@
+// Auto-generated by scripts/generate-version.mjs — do not edit manually
+export const BB_NAME = 'EmailClient';
+export const BB_VERSION = '0.1.0';