@flink-app/email-plugin 2.0.0-alpha.74 → 2.0.0-alpha.76

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@flink-app/email-plugin",
-  "version": "2.0.0-alpha.74",
-  "description": "Flink plugin that makes it possible to send email",
+  "version": "2.0.0-alpha.76",
+  "description": "Flink plugin that provides multi-provider email sending capabilities with support for SendGrid, SMTP, Flowmailer, and AWS SES",
   "author": "johan@frost.se",
   "publishConfig": {
     "access": "public"
@@ -10,6 +10,7 @@
   "types": "dist/index.d.ts",
   "main": "dist/index.js",
   "dependencies": {
+    "@aws-sdk/client-sesv2": "^3.700.0",
     "@sendgrid/mail": "^7.4.5",
     "@types/nodemailer": "^6.4.4",
     "axios": "^0.27.2",
@@ -17,15 +18,16 @@
     "querystring": "^0.2.1"
   },
   "devDependencies": {
+    "@types/jasmine": "^3.7.1",
     "@types/node": "22.13.10",
-    "@flink-app/flink": "2.0.0-alpha.74"
+    "@flink-app/flink": "2.0.0-alpha.76"
   },
   "gitHead": "4243e3b3cd6d4e1ca001a61baa8436bf2bbe4113",
   "peerDependencies": {
-    "@flink-app/flink": ">=2.0.0-alpha.74"
+    "@flink-app/flink": ">=2.0.0-alpha.76"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\"",
+    "test": "jasmine-ts --config=./spec/support/jasmine.json",
     "build": "tsc",
     "clean": "rimraf dist .flink"
   }

package/readme.md

@@ -1,6 +1,6 @@
 # Email Plugin
 
-A Flink plugin that provides multi-provider email sending capabilities with support for SendGrid, SMTP, and Flowmailer.
+A Flink plugin that provides multi-provider email sending capabilities with support for SendGrid, SMTP, Flowmailer, and AWS SES.
 
 ## Installation
 
@@ -12,7 +12,7 @@ npm install @flink-app/email-plugin
 
 ## Configuration
 
-The email plugin supports three different email providers through a unified client interface:
+The email plugin supports four different email providers through a unified client interface:
 
 ### Option 1: SendGrid
 
@@ -118,15 +118,59 @@ interface flowmailerClientOptions {
 }
 ```
 
+### Option 4: AWS SES
+
+Configure the plugin with AWS Simple Email Service (SESv2):
+
+```typescript
+import { emailPlugin, sesClient } from "@flink-app/email-plugin";
+
+function start() {
+  new FlinkApp<AppContext>({
+    name: "My app",
+    plugins: [
+      emailPlugin({
+        client: new sesClient({
+          region: "eu-north-1",
+          defaultFrom: "noreply@example.com",
+          configurationSet: "my-tracking-set",  // optional
+        })
+      })
+    ],
+  }).start();
+}
+```
+
+**SES Client Options:**
+
+```typescript
+interface sesClientOptions {
+  region?: string;          // AWS region (defaults to AWS_REGION env var)
+  credentials?: {           // Explicit credentials (defaults to AWS credential chain)
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+  };
+  defaultFrom?: string;     // Default sender address
+  configurationSet?: string; // Default SES configuration set for tracking
+}
+```
+
+Credentials are resolved in this order:
+1. Explicit `credentials` option
+2. Environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`)
+3. IAM instance profile / ECS task role
+4. AWS SSO / credential file
+
 ## TypeScript Setup
 
 Add the plugin context to your app's context type (usually in `Ctx.ts`):
 
 ```typescript
 import { FlinkContext } from "@flink-app/flink";
-import { emailPluginContext } from "@flink-app/email-plugin";
+import { EmailPluginContext } from "@flink-app/email-plugin";
 
-export interface Ctx extends FlinkContext<emailPluginContext> {
+export interface Ctx extends FlinkContext<EmailPluginContext> {
   // Your other context properties
 }
 ```
@@ -134,7 +178,7 @@ export interface Ctx extends FlinkContext<emailPluginContext> {
 **Plugin Context Interface:**
 
 ```typescript
-interface emailPluginContext {
+interface EmailPluginContext {
   emailPlugin: {
     client: client;  // Unified email client interface
   };
@@ -306,7 +350,7 @@ All email clients implement this unified interface:
 
 ```typescript
 interface client {
-  send(email: email | emailSendgrid | emailFlowmailer): Promise<boolean>;
+  send(email: email | emailSendgrid | emailFlowmailer | emailSes): Promise<boolean>;
 }
 ```
 
@@ -400,10 +444,161 @@ if (!success) {
 }
 ```
 
+## AWS SES — Extended Features
+
+The SES client supports additional features beyond the basic `send()` interface. Access them by casting the client to `sesClient`:
+
+```typescript
+import { sesClient } from "@flink-app/email-plugin";
+const ses = ctx.plugins.emailPlugin.client as sesClient;
+```
+
+### Rich Send Results
+
+Use `sendEmail()` instead of `send()` for detailed results:
+
+```typescript
+const result = await ses.sendEmail({
+  from: "noreply@example.com",
+  to: ["user@example.com"],
+  subject: "Hello",
+  html: "<h1>Welcome</h1>",
+  tags: { campaign: "welcome", env: "prod" },
+});
+
+if (result.success) {
+  console.log("Sent:", result.messageId);
+} else {
+  console.error(`Failed: ${result.error?.code} - ${result.error?.message}`);
+}
+```
+
+### Templated Emails
+
+Send emails using SES templates:
+
+```typescript
+const result = await ses.sendTemplated({
+  to: ["user@example.com"],
+  template: "WelcomeEmail",
+  templateData: { name: "Joel", company: "Frost" },
+});
+```
+
+### Bulk Email
+
+Send to many recipients using a single SES template:
+
+```typescript
+const result = await ses.sendBulk({
+  template: "Newsletter",
+  defaultTemplateData: { company: "Frost" },
+  destinations: [
+    { to: ["alice@example.com"], templateData: { name: "Alice" } },
+    { to: ["bob@example.com"], templateData: { name: "Bob" } },
+  ],
+});
+
+console.log(`Sent: ${result.successCount}, Failed: ${result.failureCount}`);
+
+// Check individual results
+for (const r of result.results) {
+  if (!r.success) {
+    console.error(`Failed: ${r.error?.code}`);
+  }
+}
+```
+
+### Verify Setup
+
+Check that your SES credentials and configuration are working:
+
+```typescript
+const status = await ses.verifySetup();
+console.log(status);
+// { verified: true, sendingEnabled: true, region: "eu-north-1" }
+```
+
+`sendingEnabled: false` means the account is still in the SES sandbox (can only send to verified addresses).
+
+### SES Email Type
+
+```typescript
+type emailSes = {
+  from: string;
+  to: string[];
+  replyTo?: string[];
+  cc?: string[];
+  bcc?: string[];
+  subject: string;
+  text?: string;
+  html?: string;
+  attachments?: SesAttachment[];
+  configurationSet?: string;   // Override default config set
+  tags?: Record<string, string>; // Event tracking tags
+};
+```
+
+## AWS SES Setup Guide
+
+### 1. Verify your sending domain
+
+```bash
+# Verify a domain (recommended for production)
+aws sesv2 create-email-identity --email-identity example.com --region eu-north-1
+
+# Or verify a single email address (for testing)
+aws sesv2 create-email-identity --email-identity sender@example.com --region eu-north-1
+```
+
+### 2. Check verification status
+
+```bash
+aws sesv2 get-email-identity --email-identity example.com --region eu-north-1
+```
+
+For domain verification, add the DKIM CNAME records shown in the response to your DNS.
+
+### 3. Check account status
+
+```bash
+aws sesv2 get-account --region eu-north-1
+```
+
+Look for `"ProductionAccessEnabled": true`. If `false`, you're in the sandbox.
+
+### 4. Request production access (exit sandbox)
+
+```bash
+aws sesv2 put-account-details \
+  --production-access-enabled \
+  --mail-type TRANSACTIONAL \
+  --website-url "https://example.com" \
+  --use-case-description "Sending transactional emails (order confirmations, password resets)" \
+  --region eu-north-1
+```
+
+### 5. Send a test email
+
+```bash
+aws sesv2 send-email \
+  --from-email-address sender@example.com \
+  --destination '{"ToAddresses":["recipient@example.com"]}' \
+  --content '{"Simple":{"Subject":{"Data":"Test"},"Body":{"Text":{"Data":"Hello from SES"}}}}' \
+  --region eu-north-1
+```
+
+### 6. Create a configuration set (optional, for tracking)
+
+```bash
+aws sesv2 create-configuration-set --configuration-set-name my-tracking-set --region eu-north-1
+```
+
 ## Notes
 
 - Either `text` or `html` must be provided (not both required, but at least one)
-- All clients return a boolean indicating success/failure
+- All clients return a boolean indicating success/failure via the `send()` interface
+- The SES client additionally offers `sendEmail()`, `sendTemplated()`, `sendBulk()`, and `verifySetup()` with richer return types
 - Flowmailer automatically handles OAuth token refresh
 - SendGrid attachments must be base64 encoded
 - SMTP client uses nodemailer internally