@wopr-network/platform-core 1.61.2 → 1.63.0

package/dist/email/client.d.ts

@@ -1,11 +1,10 @@
 /**
  * Email Client — Template-based transactional email sender.
  *
- * 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.
+ * Supports three backends (first match wins):
+ * 1. **AWS SES**: Set AWS_SES_REGION env var (+ AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
+ * 2. **Postmark**: Set POSTMARK_API_KEY env var
+ * 3. **Resend**: Set RESEND_API_KEY env var
  */
 export interface EmailClientConfig {
     apiKey: string;
@@ -49,7 +48,20 @@ export declare class EmailClient {
     /** Send a transactional email. */
     send(opts: SendTemplateEmailOpts): Promise<EmailSendResult>;
 }
-export declare function getEmailClient(): EmailClient;
+export interface EmailClientOverrides {
+    /** Sender address — overrides EMAIL_FROM env var. */
+    from?: string;
+    /** Reply-to address — overrides EMAIL_REPLY_TO env var. */
+    replyTo?: string;
+}
+/**
+ * Create a lazily-initialized singleton EmailClient.
+ *
+ * Optional overrides (from DB-driven product config) take precedence
+ * over env vars. Pass them on first call; subsequent calls return the
+ * cached singleton.
+ */
+export declare function getEmailClient(overrides?: EmailClientOverrides): EmailClient;
 /** Reset the singleton (for testing). */
 export declare function resetEmailClient(): void;
 /** Replace the singleton (for testing). */

package/dist/email/client.js

@@ -1,14 +1,14 @@
 /**
  * Email Client — Template-based transactional email sender.
  *
- * 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.
+ * Supports three backends (first match wins):
+ * 1. **AWS SES**: Set AWS_SES_REGION env var (+ AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
+ * 2. **Postmark**: Set POSTMARK_API_KEY env var
+ * 3. **Resend**: Set RESEND_API_KEY env var
  */
 import { Resend } from "resend";
 import { logger } from "../config/logger.js";
+import { PostmarkTransport } from "./postmark-transport.js";
 import { SesTransport } from "./ses-transport.js";
 /**
  * Transactional email client with pluggable transport.
@@ -94,7 +94,8 @@ class ResendTransport {
  *
  * Backend selection (first match wins):
  * 1. AWS SES — AWS_SES_REGION is set
- * 2. Resend — RESEND_API_KEY is set
+ * 2. Postmark — POSTMARK_API_KEY is set
+ * 3. Resend — RESEND_API_KEY is set
  *
  * Common env vars:
  * - EMAIL_FROM (default: "noreply@wopr.bot") — sender address
@@ -105,6 +106,9 @@ class ResendTransport {
  * - AWS_ACCESS_KEY_ID
  * - AWS_SECRET_ACCESS_KEY
  *
+ * Postmark env vars:
+ * - POSTMARK_API_KEY (server token from Postmark dashboard)
+ *
  * Resend env vars:
  * - RESEND_API_KEY
  *
@@ -113,10 +117,17 @@ class ResendTransport {
  * - RESEND_REPLY_TO → falls back if EMAIL_REPLY_TO is not set
  */
 let _client = null;
-export function getEmailClient() {
+/**
+ * Create a lazily-initialized singleton EmailClient.
+ *
+ * Optional overrides (from DB-driven product config) take precedence
+ * over env vars. Pass them on first call; subsequent calls return the
+ * cached singleton.
+ */
+export function getEmailClient(overrides) {
     if (!_client) {
-        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 from = overrides?.from || process.env.EMAIL_FROM || process.env.RESEND_FROM || "noreply@wopr.bot";
+        const replyTo = overrides?.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({
@@ -129,10 +140,19 @@ export function getEmailClient() {
             _client = new EmailClient(transport);
             logger.info("Email client initialized with AWS SES", { region: sesRegion, from });
         }
+        else if (process.env.POSTMARK_API_KEY) {
+            const transport = new PostmarkTransport({
+                apiKey: process.env.POSTMARK_API_KEY,
+                from,
+                replyTo,
+            });
+            _client = new EmailClient(transport);
+            logger.info("Email client initialized with Postmark", { 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");
+                throw new Error("Set AWS_SES_REGION, POSTMARK_API_KEY, or RESEND_API_KEY environment variable");
             }
             _client = new EmailClient({ apiKey, from, replyTo });
             logger.info("Email client initialized with Resend", { from });

package/dist/email/client.test.js

@@ -91,8 +91,8 @@ describe("getEmailClient / setEmailClient / resetEmailClient", () => {
         delete process.env.RESEND_FROM;
         delete process.env.RESEND_REPLY_TO;
     });
-    it("should throw if RESEND_API_KEY is not set", () => {
-        expect(() => getEmailClient()).toThrow("RESEND_API_KEY environment variable is required");
+    it("should throw if no email provider is configured", () => {
+        expect(() => getEmailClient()).toThrow("Set AWS_SES_REGION, POSTMARK_API_KEY, or RESEND_API_KEY");
     });
     it("should create client from env vars", () => {
         process.env.RESEND_API_KEY = "re_test123";

package/dist/email/index.d.ts

@@ -10,7 +10,7 @@
  */
 export type { BillingEmailServiceConfig, BillingEmailType } from "./billing-emails.js";
 export { BillingEmailService } from "./billing-emails.js";
-export type { EmailClientConfig, EmailSendResult, SendTemplateEmailOpts } from "./client.js";
+export type { EmailClientConfig, EmailClientOverrides, EmailSendResult, SendTemplateEmailOpts } from "./client.js";
 export { EmailClient, getEmailClient, resetEmailClient, setEmailClient } from "./client.js";
 export { DEFAULT_TEMPLATES } from "./default-templates.js";
 export type { IBillingEmailRepository } from "./drizzle-billing-email-repository.js";

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

@@ -0,0 +1,19 @@
+/**
+ * Postmark email transport.
+ *
+ * Env vars:
+ *   POSTMARK_API_KEY — server API token from Postmark
+ */
+import type { EmailSendResult, EmailTransport, SendTemplateEmailOpts } from "./client.js";
+export interface PostmarkTransportConfig {
+    apiKey: string;
+    from: string;
+    replyTo?: string;
+}
+export declare class PostmarkTransport implements EmailTransport {
+    private client;
+    private from;
+    private replyTo;
+    constructor(config: PostmarkTransportConfig);
+    send(opts: SendTemplateEmailOpts): Promise<EmailSendResult>;
+}

package/dist/email/postmark-transport.js

@@ -0,0 +1,45 @@
+/**
+ * Postmark email transport.
+ *
+ * Env vars:
+ *   POSTMARK_API_KEY — server API token from Postmark
+ */
+import { ServerClient } from "postmark";
+import { logger } from "../config/logger.js";
+export class PostmarkTransport {
+    client;
+    from;
+    replyTo;
+    constructor(config) {
+        this.client = new ServerClient(config.apiKey);
+        this.from = config.from;
+        this.replyTo = config.replyTo;
+    }
+    async send(opts) {
+        const result = await this.client.sendEmail({
+            From: this.from,
+            To: opts.to,
+            Subject: opts.subject,
+            HtmlBody: opts.html,
+            TextBody: opts.text,
+            ReplyTo: this.replyTo,
+            MessageStream: "outbound",
+        });
+        if (result.ErrorCode !== 0) {
+            logger.error("Failed to send email via Postmark", {
+                to: opts.to,
+                template: opts.templateName,
+                error: result.Message,
+                code: result.ErrorCode,
+            });
+            throw new Error(`Postmark error ${result.ErrorCode}: ${result.Message}`);
+        }
+        logger.info("Email sent via Postmark", {
+            emailId: result.MessageID,
+            to: opts.to,
+            template: opts.templateName,
+            userId: opts.userId,
+        });
+        return { id: result.MessageID, success: true };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/platform-core",
-  "version": "1.61.2",
+  "version": "1.63.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -138,6 +138,7 @@
     "@scure/bip39": "^2.0.1",
     "handlebars": "^4.7.8",
     "js-yaml": "^4.1.1",
+    "postmark": "^4.0.7",
     "viem": "^2.47.4",
     "yaml": "^2.8.2"
   }

package/src/email/client.test.ts

@@ -116,8 +116,8 @@ describe("getEmailClient / setEmailClient / resetEmailClient", () => {
     delete process.env.RESEND_REPLY_TO;
   });
 
-  it("should throw if RESEND_API_KEY is not set", () => {
-    expect(() => getEmailClient()).toThrow("RESEND_API_KEY environment variable is required");
+  it("should throw if no email provider is configured", () => {
+    expect(() => getEmailClient()).toThrow("Set AWS_SES_REGION, POSTMARK_API_KEY, or RESEND_API_KEY");
   });
 
   it("should create client from env vars", () => {

package/src/email/client.ts

@@ -1,15 +1,15 @@
 /**
  * Email Client — Template-based transactional email sender.
  *
- * 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.
+ * Supports three backends (first match wins):
+ * 1. **AWS SES**: Set AWS_SES_REGION env var (+ AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
+ * 2. **Postmark**: Set POSTMARK_API_KEY env var
+ * 3. **Resend**: Set RESEND_API_KEY env var
  */
 
 import { Resend } from "resend";
 import { logger } from "../config/logger.js";
+import { PostmarkTransport } from "./postmark-transport.js";
 import { SesTransport } from "./ses-transport.js";
 
 export interface EmailClientConfig {
@@ -134,7 +134,8 @@ class ResendTransport implements EmailTransport {
  *
  * Backend selection (first match wins):
  * 1. AWS SES — AWS_SES_REGION is set
- * 2. Resend — RESEND_API_KEY is set
+ * 2. Postmark — POSTMARK_API_KEY is set
+ * 3. Resend — RESEND_API_KEY is set
  *
  * Common env vars:
  * - EMAIL_FROM (default: "noreply@wopr.bot") — sender address
@@ -145,6 +146,9 @@ class ResendTransport implements EmailTransport {
  * - AWS_ACCESS_KEY_ID
  * - AWS_SECRET_ACCESS_KEY
  *
+ * Postmark env vars:
+ * - POSTMARK_API_KEY (server token from Postmark dashboard)
+ *
  * Resend env vars:
  * - RESEND_API_KEY
  *
@@ -154,10 +158,25 @@ class ResendTransport implements EmailTransport {
  */
 let _client: EmailClient | null = null;
 
-export function getEmailClient(): EmailClient {
+export interface EmailClientOverrides {
+  /** Sender address — overrides EMAIL_FROM env var. */
+  from?: string;
+  /** Reply-to address — overrides EMAIL_REPLY_TO env var. */
+  replyTo?: string;
+}
+
+/**
+ * Create a lazily-initialized singleton EmailClient.
+ *
+ * Optional overrides (from DB-driven product config) take precedence
+ * over env vars. Pass them on first call; subsequent calls return the
+ * cached singleton.
+ */
+export function getEmailClient(overrides?: EmailClientOverrides): EmailClient {
   if (!_client) {
-    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 from = overrides?.from || process.env.EMAIL_FROM || process.env.RESEND_FROM || "noreply@wopr.bot";
+    const replyTo =
+      overrides?.replyTo || process.env.EMAIL_REPLY_TO || process.env.RESEND_REPLY_TO || "support@wopr.bot";
 
     const sesRegion = process.env.AWS_SES_REGION;
     if (sesRegion) {
@@ -170,10 +189,18 @@ export function getEmailClient(): EmailClient {
       });
       _client = new EmailClient(transport);
       logger.info("Email client initialized with AWS SES", { region: sesRegion, from });
+    } else if (process.env.POSTMARK_API_KEY) {
+      const transport = new PostmarkTransport({
+        apiKey: process.env.POSTMARK_API_KEY,
+        from,
+        replyTo,
+      });
+      _client = new EmailClient(transport);
+      logger.info("Email client initialized with Postmark", { 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");
+        throw new Error("Set AWS_SES_REGION, POSTMARK_API_KEY, or RESEND_API_KEY environment variable");
       }
       _client = new EmailClient({ apiKey, from, replyTo });
       logger.info("Email client initialized with Resend", { from });

package/src/email/index.ts

@@ -11,7 +11,7 @@
 
 export type { BillingEmailServiceConfig, BillingEmailType } from "./billing-emails.js";
 export { BillingEmailService } from "./billing-emails.js";
-export type { EmailClientConfig, EmailSendResult, SendTemplateEmailOpts } from "./client.js";
+export type { EmailClientConfig, EmailClientOverrides, EmailSendResult, SendTemplateEmailOpts } from "./client.js";
 export { EmailClient, getEmailClient, resetEmailClient, setEmailClient } from "./client.js";
 export { DEFAULT_TEMPLATES } from "./default-templates.js";
 export type { IBillingEmailRepository } from "./drizzle-billing-email-repository.js";

package/src/email/postmark-transport.ts

@@ -0,0 +1,59 @@
+/**
+ * Postmark email transport.
+ *
+ * Env vars:
+ *   POSTMARK_API_KEY — server API token from Postmark
+ */
+
+import { ServerClient } from "postmark";
+import { logger } from "../config/logger.js";
+import type { EmailSendResult, EmailTransport, SendTemplateEmailOpts } from "./client.js";
+
+export interface PostmarkTransportConfig {
+  apiKey: string;
+  from: string;
+  replyTo?: string;
+}
+
+export class PostmarkTransport implements EmailTransport {
+  private client: ServerClient;
+  private from: string;
+  private replyTo: string | undefined;
+
+  constructor(config: PostmarkTransportConfig) {
+    this.client = new ServerClient(config.apiKey);
+    this.from = config.from;
+    this.replyTo = config.replyTo;
+  }
+
+  async send(opts: SendTemplateEmailOpts): Promise<EmailSendResult> {
+    const result = await this.client.sendEmail({
+      From: this.from,
+      To: opts.to,
+      Subject: opts.subject,
+      HtmlBody: opts.html,
+      TextBody: opts.text,
+      ReplyTo: this.replyTo,
+      MessageStream: "outbound",
+    });
+
+    if (result.ErrorCode !== 0) {
+      logger.error("Failed to send email via Postmark", {
+        to: opts.to,
+        template: opts.templateName,
+        error: result.Message,
+        code: result.ErrorCode,
+      });
+      throw new Error(`Postmark error ${result.ErrorCode}: ${result.Message}`);
+    }
+
+    logger.info("Email sent via Postmark", {
+      emailId: result.MessageID,
+      to: opts.to,
+      template: opts.templateName,
+      userId: opts.userId,
+    });
+
+    return { id: result.MessageID, success: true };
+  }
+}