@aws-blocks/bb-email-client 0.1.2 → 0.1.4

package/DESIGN.md

@@ -0,0 +1,47 @@
+# Email — Design
+
+Design document for the Email Building Block. For usage, examples, best practices, and scaling guidance, see [README.md](./README.md).
+
+**Package:** `@aws-blocks/bb-email-client`
+**Type:** Primitive (new infrastructure)
+**AWS Service:** Amazon SES
+
+## Purpose
+
+Email sending for transactional emails — welcome emails, password resets, order confirmations, notifications. For real-time messaging, use `Realtime`. For async job notifications, use `AsyncJob`.
+
+## Infrastructure (CDK)
+
+Creates the following resources:
+
+- **SES Configuration Set:** For delivery tracking and event publishing
+	- **Name:** Derived from `scope.fullId`
+- **SES Email Identity:** Verifies the `fromAddress` (email-level verification)
+	- Domain-level verification is preferred for production but requires DNS access
+- **IAM Permissions:** `ses:SendEmail` and `ses:SendBulkEmail` granted to the parent scope's handler automatically
+
+No SNS topics for bounce/complaint handling, no SES templates, no dedicated IP pools.
+
+## Mock Implementation
+
+- Emails are logged to the console with sender, recipients, subject, and a body preview:
+	```
+	[Email:notifications]
+	  Recipient: user@example.com
+	  Subject:   Welcome!
+	  Body:      Thanks for signing up.
+	```
+- Emails are also written to `.bb-data/{scope.fullId}/emails.json` as a JSON array for programmatic inspection. Each entry includes `to`, `subject`, `body`, `html` (if provided), `from`, `messageId`, and `timestamp` (ISO 8601).
+- `sendBatch()` appends all messages to the same file in a single write.
+- Mock validates email address format (basic RFC 5322 check) and throws `InvalidInputException` for malformed addresses.
+
+### Mock vs AWS Behavior Differences
+
+| Behavior Difference | Impact | Mitigation |
+|------------|--------|------------|
+| No actual email delivery | Emails are never sent; delivery issues only surface in AWS | No mitigation — mock is for development flow, not delivery testing. Sandbox testing covers real delivery |
+| No bounce/complaint handling | Bounces and complaints only occur with real email delivery | No mitigation — these are inherently production concerns |
+| No sending rate limits | Code that would be throttled in SES sandbox succeeds locally | No mitigation — the mock does not simulate SES rate limits. Recommend sandbox testing for throughput-sensitive flows |
+| No domain verification | `DomainNotVerifiedException` never thrown locally | No mitigation — verification is an infrastructure concern handled by CDK. Sandbox testing covers it |
+| Per-message recipient limit (50) | A message exceeding 50 recipients (To + CC + BCC) would be rejected by SES | `send()` throws `InvalidInputException`; within `sendBatch()` the offending message is marked `failed` in the per-entry results (matching SES per-entry behavior) |
+| No 40 MB message size limit | Oversized messages succeed locally | Mock validates total message size and throws `EmailSendFailedException` when it exceeds 40 MB |

package/README.md

@@ -2,6 +2,8 @@
 
 Transactional email sending via Amazon SES.
 
+> Design & mock parity details: [DESIGN.md](./DESIGN.md)
+
 ## Usage
 
 ```typescript

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

@@ -1,6 +1,15 @@
 {
   "name": "@aws-blocks/bb-email-client",
-  "version": "0.1.2",
+  "version": "0.1.4",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aws-devtools-labs/aws-blocks.git",
+    "directory": "packages/bb-email-client"
+  },
+  "homepage": "https://github.com/aws-devtools-labs/aws-blocks/tree/main/packages/bb-email-client#readme",
+  "bugs": {
+    "url": "https://github.com/aws-devtools-labs/aws-blocks/issues"
+  },
   "author": "Amazon Web Services",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,8 +38,8 @@
     "test": "node --test --test-concurrency=1 dist/*.test.js"
   },
   "dependencies": {
-    "@aws-blocks/core": "^0.1.2",
-    "@aws-blocks/bb-logger": "^0.1.1",
+    "@aws-blocks/core": "^0.2.0",
+    "@aws-blocks/bb-logger": "^0.1.4",
     "@aws-sdk/client-sesv2": "^3.0.0"
   },
   "devDependencies": {

package/src/version.ts

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