@wopr-network/platform-core 1.50.2 → 1.51.0

package/dist/email/client.d.ts

@@ -1,8 +1,11 @@
 /**
  * Email Client — Template-based transactional email sender.
  *
- * Wraps Resend SDK and provides a typed interface for sending emails
- * using the platform's templates. Every email is logged for audit.
+ * Supports two backends:
+ * - **Resend**: Set RESEND_API_KEY env var
+ * - **AWS SES**: Set AWS_SES_REGION env var (+ AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
+ *
+ * SES takes priority when both are configured.
  */
 export interface EmailClientConfig {
     apiKey: string;
@@ -23,22 +26,24 @@ export interface EmailSendResult {
     id: string;
     success: boolean;
 }
+/** Transport abstraction — any backend that can send an email. */
+export interface EmailTransport {
+    send(opts: SendTemplateEmailOpts): Promise<EmailSendResult>;
+}
 /**
- * Transactional email client backed by Resend.
+ * Transactional email client with pluggable transport.
  *
  * Usage:
  * ```ts
- * const client = new EmailClient({ apiKey: "re_xxx", from: "noreply@wopr.bot" });
+ * const client = new EmailClient({ apiKey: "re_xxx", from: "noreply@example.com" });
  * const template = verifyEmailTemplate(url, email);
  * await client.send({ to: email, ...template, userId: "user-123", templateName: "verify-email" });
  * ```
  */
 export declare class EmailClient {
-    private resend;
-    private from;
-    private replyTo;
+    private transport;
     private onSend;
-    constructor(config: EmailClientConfig);
+    constructor(configOrTransport: EmailClientConfig | EmailTransport);
     /** Register a callback invoked after each successful send (for audit logging). */
     onEmailSent(callback: (opts: SendTemplateEmailOpts, result: EmailSendResult) => void): void;
     /** Send a transactional email. */

package/dist/email/client.js

@@ -1,36 +1,64 @@
 /**
  * Email Client — Template-based transactional email sender.
  *
- * Wraps Resend SDK and provides a typed interface for sending emails
- * using the platform's templates. Every email is logged for audit.
+ * Supports two backends:
+ * - **Resend**: Set RESEND_API_KEY env var
+ * - **AWS SES**: Set AWS_SES_REGION env var (+ AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
+ *
+ * SES takes priority when both are configured.
  */
 import { Resend } from "resend";
 import { logger } from "../config/logger.js";
+import { SesTransport } from "./ses-transport.js";
 /**
- * Transactional email client backed by Resend.
+ * Transactional email client with pluggable transport.
  *
  * Usage:
  * ```ts
- * const client = new EmailClient({ apiKey: "re_xxx", from: "noreply@wopr.bot" });
+ * const client = new EmailClient({ apiKey: "re_xxx", from: "noreply@example.com" });
  * const template = verifyEmailTemplate(url, email);
  * await client.send({ to: email, ...template, userId: "user-123", templateName: "verify-email" });
  * ```
  */
 export class EmailClient {
+    transport;
+    onSend = null;
+    constructor(configOrTransport) {
+        if ("send" in configOrTransport) {
+            this.transport = configOrTransport;
+        }
+        else {
+            this.transport = new ResendTransport(configOrTransport);
+        }
+    }
+    /** Register a callback invoked after each successful send (for audit logging). */
+    onEmailSent(callback) {
+        this.onSend = callback;
+    }
+    /** Send a transactional email. */
+    async send(opts) {
+        const result = await this.transport.send(opts);
+        if (this.onSend) {
+            try {
+                this.onSend(opts, result);
+            }
+            catch {
+                // Audit callback failure should not break email sending
+            }
+        }
+        return result;
+    }
+}
+/** Resend-backed transport (original implementation). */
+class ResendTransport {
     resend;
     from;
     replyTo;
-    onSend = null;
     constructor(config) {
         this.resend = new Resend(config.apiKey);
         this.from = config.from;
         this.replyTo = config.replyTo;
     }
-    /** Register a callback invoked after each successful send (for audit logging). */
-    onEmailSent(callback) {
-        this.onSend = callback;
-    }
-    /** Send a transactional email. */
     async send(opts) {
         const { data, error } = await this.resend.emails.send({
             from: this.from,
@@ -41,7 +69,7 @@ export class EmailClient {
             text: opts.text,
         });
         if (error) {
-            logger.error("Failed to send email", {
+            logger.error("Failed to send email via Resend", {
                 to: opts.to,
                 template: opts.templateName,
                 error: error.message,
@@ -52,43 +80,63 @@ export class EmailClient {
             id: data?.id || "",
             success: true,
         };
-        logger.info("Email sent", {
+        logger.info("Email sent via Resend", {
             emailId: result.id,
             to: opts.to,
             template: opts.templateName,
             userId: opts.userId,
         });
-        if (this.onSend) {
-            try {
-                this.onSend(opts, result);
-            }
-            catch {
-                // Audit callback failure should not break email sending
-            }
-        }
         return result;
     }
 }
 /**
  * Create a lazily-initialized singleton EmailClient from environment variables.
  *
- * Env vars:
- * - RESEND_API_KEY (required)
- * - RESEND_FROM (default: "noreply@wopr.bot")
- * - RESEND_REPLY_TO (default: "support@wopr.bot")
+ * Backend selection (first match wins):
+ * 1. AWS SES — AWS_SES_REGION is set
+ * 2. Resend — RESEND_API_KEY is set
+ *
+ * Common env vars:
+ * - EMAIL_FROM (default: "noreply@wopr.bot") — sender address
+ * - EMAIL_REPLY_TO (default: "support@wopr.bot") — reply-to address
+ *
+ * SES env vars:
+ * - AWS_SES_REGION (e.g. "us-east-1")
+ * - AWS_ACCESS_KEY_ID
+ * - AWS_SECRET_ACCESS_KEY
+ *
+ * Resend env vars:
+ * - RESEND_API_KEY
+ *
+ * Legacy env vars (still supported):
+ * - RESEND_FROM → falls back if EMAIL_FROM is not set
+ * - RESEND_REPLY_TO → falls back if EMAIL_REPLY_TO is not set
  */
 let _client = null;
 export function getEmailClient() {
     if (!_client) {
-        const apiKey = process.env.RESEND_API_KEY;
-        if (!apiKey) {
-            throw new Error("RESEND_API_KEY environment variable is required");
+        const from = process.env.EMAIL_FROM || process.env.RESEND_FROM || "noreply@wopr.bot";
+        const replyTo = process.env.EMAIL_REPLY_TO || process.env.RESEND_REPLY_TO || "support@wopr.bot";
+        const sesRegion = process.env.AWS_SES_REGION;
+        if (sesRegion) {
+            const transport = new SesTransport({
+                region: sesRegion,
+                from,
+                replyTo,
+                accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+                secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+            });
+            _client = new EmailClient(transport);
+            logger.info("Email client initialized with AWS SES", { region: sesRegion, from });
+        }
+        else {
+            const apiKey = process.env.RESEND_API_KEY;
+            if (!apiKey) {
+                throw new Error("Either AWS_SES_REGION or RESEND_API_KEY environment variable is required");
+            }
+            _client = new EmailClient({ apiKey, from, replyTo });
+            logger.info("Email client initialized with Resend", { from });
         }
-        _client = new EmailClient({
-            apiKey,
-            from: process.env.RESEND_FROM || "noreply@wopr.bot",
-            replyTo: process.env.RESEND_REPLY_TO || "support@wopr.bot",
-        });
     }
     return _client;
 }

package/dist/email/ses-transport.d.ts

@@ -0,0 +1,26 @@
+/**
+ * AWS SES Email Transport.
+ *
+ * Drop-in alternative to Resend for transactional email.
+ * Activated when AWS_SES_REGION env var is set.
+ *
+ * Required env vars:
+ * - AWS_SES_REGION (e.g. "us-east-1")
+ * - AWS_ACCESS_KEY_ID
+ * - AWS_SECRET_ACCESS_KEY
+ */
+import type { EmailSendResult, EmailTransport, SendTemplateEmailOpts } from "./client.js";
+export interface SesTransportConfig {
+    region: string;
+    from: string;
+    replyTo?: string;
+    accessKeyId?: string;
+    secretAccessKey?: string;
+}
+export declare class SesTransport implements EmailTransport {
+    private client;
+    private from;
+    private replyTo;
+    constructor(config: SesTransportConfig);
+    send(opts: SendTemplateEmailOpts): Promise<EmailSendResult>;
+}

package/dist/email/ses-transport.js

@@ -0,0 +1,63 @@
+/**
+ * AWS SES Email Transport.
+ *
+ * Drop-in alternative to Resend for transactional email.
+ * Activated when AWS_SES_REGION env var is set.
+ *
+ * Required env vars:
+ * - AWS_SES_REGION (e.g. "us-east-1")
+ * - AWS_ACCESS_KEY_ID
+ * - AWS_SECRET_ACCESS_KEY
+ */
+import { SESClient, SendEmailCommand } from "@aws-sdk/client-ses";
+import { logger } from "../config/logger.js";
+export class SesTransport {
+    client;
+    from;
+    replyTo;
+    constructor(config) {
+        const credentials = config.accessKeyId && config.secretAccessKey
+            ? { accessKeyId: config.accessKeyId, secretAccessKey: config.secretAccessKey }
+            : undefined;
+        this.client = new SESClient({
+            region: config.region,
+            ...(credentials ? { credentials } : {}),
+        });
+        this.from = config.from;
+        this.replyTo = config.replyTo;
+    }
+    async send(opts) {
+        const command = new SendEmailCommand({
+            Source: this.from,
+            ReplyToAddresses: this.replyTo ? [this.replyTo] : undefined,
+            Destination: { ToAddresses: [opts.to] },
+            Message: {
+                Subject: { Data: opts.subject, Charset: "UTF-8" },
+                Body: {
+                    Html: { Data: opts.html, Charset: "UTF-8" },
+                    ...(opts.text ? { Text: { Data: opts.text, Charset: "UTF-8" } } : {}),
+                },
+            },
+        });
+        try {
+            const response = await this.client.send(command);
+            const messageId = response.MessageId || "";
+            logger.info("Email sent via SES", {
+                messageId,
+                to: opts.to,
+                template: opts.templateName,
+                userId: opts.userId,
+            });
+            return { id: messageId, success: true };
+        }
+        catch (error) {
+            logger.error("Failed to send email via SES", {
+                to: opts.to,
+                template: opts.templateName,
+                userId: opts.userId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/platform-core",
-  "version": "1.50.2",
+  "version": "1.51.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -128,6 +128,7 @@
   },
   "packageManager": "pnpm@10.31.0",
   "dependencies": {
+    "@aws-sdk/client-ses": "^3.1014.0",
     "@hono/node-server": "^1.19.11",
     "@noble/hashes": "^2.0.1",
     "@scure/base": "^2.0.0",

package/src/email/client.ts

@@ -1,12 +1,16 @@
 /**
  * Email Client — Template-based transactional email sender.
  *
- * Wraps Resend SDK and provides a typed interface for sending emails
- * using the platform's templates. Every email is logged for audit.
+ * Supports two backends:
+ * - **Resend**: Set RESEND_API_KEY env var
+ * - **AWS SES**: Set AWS_SES_REGION env var (+ AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
+ *
+ * SES takes priority when both are configured.
  */
 
 import { Resend } from "resend";
 import { logger } from "../config/logger.js";
+import { SesTransport } from "./ses-transport.js";
 
 export interface EmailClientConfig {
   apiKey: string;
@@ -30,26 +34,31 @@ export interface EmailSendResult {
   success: boolean;
 }
 
+/** Transport abstraction — any backend that can send an email. */
+export interface EmailTransport {
+  send(opts: SendTemplateEmailOpts): Promise<EmailSendResult>;
+}
+
 /**
- * Transactional email client backed by Resend.
+ * Transactional email client with pluggable transport.
  *
  * Usage:
  * ```ts
- * const client = new EmailClient({ apiKey: "re_xxx", from: "noreply@wopr.bot" });
+ * const client = new EmailClient({ apiKey: "re_xxx", from: "noreply@example.com" });
  * const template = verifyEmailTemplate(url, email);
  * await client.send({ to: email, ...template, userId: "user-123", templateName: "verify-email" });
  * ```
  */
 export class EmailClient {
-  private resend: Resend;
-  private from: string;
-  private replyTo: string | undefined;
+  private transport: EmailTransport;
   private onSend: ((opts: SendTemplateEmailOpts, result: EmailSendResult) => void) | null = null;
 
-  constructor(config: EmailClientConfig) {
-    this.resend = new Resend(config.apiKey);
-    this.from = config.from;
-    this.replyTo = config.replyTo;
+  constructor(configOrTransport: EmailClientConfig | EmailTransport) {
+    if ("send" in configOrTransport) {
+      this.transport = configOrTransport;
+    } else {
+      this.transport = new ResendTransport(configOrTransport);
+    }
   }
 
   /** Register a callback invoked after each successful send (for audit logging). */
@@ -58,6 +67,33 @@ export class EmailClient {
   }
 
   /** Send a transactional email. */
+  async send(opts: SendTemplateEmailOpts): Promise<EmailSendResult> {
+    const result = await this.transport.send(opts);
+
+    if (this.onSend) {
+      try {
+        this.onSend(opts, result);
+      } catch {
+        // Audit callback failure should not break email sending
+      }
+    }
+
+    return result;
+  }
+}
+
+/** Resend-backed transport (original implementation). */
+class ResendTransport implements EmailTransport {
+  private resend: Resend;
+  private from: string;
+  private replyTo: string | undefined;
+
+  constructor(config: EmailClientConfig) {
+    this.resend = new Resend(config.apiKey);
+    this.from = config.from;
+    this.replyTo = config.replyTo;
+  }
+
   async send(opts: SendTemplateEmailOpts): Promise<EmailSendResult> {
     const { data, error } = await this.resend.emails.send({
       from: this.from,
@@ -69,7 +105,7 @@ export class EmailClient {
     });
 
     if (error) {
-      logger.error("Failed to send email", {
+      logger.error("Failed to send email via Resend", {
         to: opts.to,
         template: opts.templateName,
         error: error.message,
@@ -82,21 +118,13 @@ export class EmailClient {
       success: true,
     };
 
-    logger.info("Email sent", {
+    logger.info("Email sent via Resend", {
       emailId: result.id,
       to: opts.to,
       template: opts.templateName,
       userId: opts.userId,
     });
 
-    if (this.onSend) {
-      try {
-        this.onSend(opts, result);
-      } catch {
-        // Audit callback failure should not break email sending
-      }
-    }
-
     return result;
   }
 }
@@ -104,24 +132,52 @@ export class EmailClient {
 /**
  * Create a lazily-initialized singleton EmailClient from environment variables.
  *
- * Env vars:
- * - RESEND_API_KEY (required)
- * - RESEND_FROM (default: "noreply@wopr.bot")
- * - RESEND_REPLY_TO (default: "support@wopr.bot")
+ * Backend selection (first match wins):
+ * 1. AWS SES — AWS_SES_REGION is set
+ * 2. Resend — RESEND_API_KEY is set
+ *
+ * Common env vars:
+ * - EMAIL_FROM (default: "noreply@wopr.bot") — sender address
+ * - EMAIL_REPLY_TO (default: "support@wopr.bot") — reply-to address
+ *
+ * SES env vars:
+ * - AWS_SES_REGION (e.g. "us-east-1")
+ * - AWS_ACCESS_KEY_ID
+ * - AWS_SECRET_ACCESS_KEY
+ *
+ * Resend env vars:
+ * - RESEND_API_KEY
+ *
+ * Legacy env vars (still supported):
+ * - RESEND_FROM → falls back if EMAIL_FROM is not set
+ * - RESEND_REPLY_TO → falls back if EMAIL_REPLY_TO is not set
  */
 let _client: EmailClient | null = null;
 
 export function getEmailClient(): EmailClient {
   if (!_client) {
-    const apiKey = process.env.RESEND_API_KEY;
-    if (!apiKey) {
-      throw new Error("RESEND_API_KEY environment variable is required");
+    const from = process.env.EMAIL_FROM || process.env.RESEND_FROM || "noreply@wopr.bot";
+    const replyTo = process.env.EMAIL_REPLY_TO || process.env.RESEND_REPLY_TO || "support@wopr.bot";
+
+    const sesRegion = process.env.AWS_SES_REGION;
+    if (sesRegion) {
+      const transport = new SesTransport({
+        region: sesRegion,
+        from,
+        replyTo,
+        accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+      });
+      _client = new EmailClient(transport);
+      logger.info("Email client initialized with AWS SES", { region: sesRegion, from });
+    } else {
+      const apiKey = process.env.RESEND_API_KEY;
+      if (!apiKey) {
+        throw new Error("Either AWS_SES_REGION or RESEND_API_KEY environment variable is required");
+      }
+      _client = new EmailClient({ apiKey, from, replyTo });
+      logger.info("Email client initialized with Resend", { from });
     }
-    _client = new EmailClient({
-      apiKey,
-      from: process.env.RESEND_FROM || "noreply@wopr.bot",
-      replyTo: process.env.RESEND_REPLY_TO || "support@wopr.bot",
-    });
   }
   return _client;
 }

package/src/email/ses-transport.ts

@@ -0,0 +1,80 @@
+/**
+ * AWS SES Email Transport.
+ *
+ * Drop-in alternative to Resend for transactional email.
+ * Activated when AWS_SES_REGION env var is set.
+ *
+ * Required env vars:
+ * - AWS_SES_REGION (e.g. "us-east-1")
+ * - AWS_ACCESS_KEY_ID
+ * - AWS_SECRET_ACCESS_KEY
+ */
+
+import { SESClient, SendEmailCommand } from "@aws-sdk/client-ses";
+import { logger } from "../config/logger.js";
+import type { EmailSendResult, EmailTransport, SendTemplateEmailOpts } from "./client.js";
+
+export interface SesTransportConfig {
+  region: string;
+  from: string;
+  replyTo?: string;
+  accessKeyId?: string;
+  secretAccessKey?: string;
+}
+
+export class SesTransport implements EmailTransport {
+  private client: SESClient;
+  private from: string;
+  private replyTo: string | undefined;
+
+  constructor(config: SesTransportConfig) {
+    const credentials =
+      config.accessKeyId && config.secretAccessKey
+        ? { accessKeyId: config.accessKeyId, secretAccessKey: config.secretAccessKey }
+        : undefined;
+
+    this.client = new SESClient({
+      region: config.region,
+      ...(credentials ? { credentials } : {}),
+    });
+    this.from = config.from;
+    this.replyTo = config.replyTo;
+  }
+
+  async send(opts: SendTemplateEmailOpts): Promise<EmailSendResult> {
+    const command = new SendEmailCommand({
+      Source: this.from,
+      ReplyToAddresses: this.replyTo ? [this.replyTo] : undefined,
+      Destination: { ToAddresses: [opts.to] },
+      Message: {
+        Subject: { Data: opts.subject, Charset: "UTF-8" },
+        Body: {
+          Html: { Data: opts.html, Charset: "UTF-8" },
+          ...(opts.text ? { Text: { Data: opts.text, Charset: "UTF-8" } } : {}),
+        },
+      },
+    });
+
+    try {
+      const response = await this.client.send(command);
+      const messageId = response.MessageId || "";
+
+      logger.info("Email sent via SES", {
+        messageId,
+        to: opts.to,
+        template: opts.templateName,
+        userId: opts.userId,
+      });
+
+      return { id: messageId, success: true };
+    } catch (error) {
+      logger.error("Failed to send email via SES", {
+        to: opts.to,
+        template: opts.templateName,
+        userId: opts.userId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      throw error;
+    }
+  }
+}