@wopr-network/platform-core 0.1.0

package/src/email/notification-worker.test.ts

@@ -0,0 +1,189 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { EmailClient } from "./client.js";
+import type {
+  INotificationPreferencesRepository,
+  INotificationQueueRepository,
+  QueuedNotification,
+} from "./notification-repository-types.js";
+import { NotificationWorker } from "./notification-worker.js";
+
+vi.mock("../config/logger.js", () => ({
+  logger: {
+    info: vi.fn(),
+    error: vi.fn(),
+    warn: vi.fn(),
+    debug: vi.fn(),
+  },
+}));
+
+function makeNotif(overrides: Partial<QueuedNotification> = {}): QueuedNotification {
+  return {
+    id: "notif-1",
+    tenantId: "tenant-1",
+    template: "low-balance",
+    data: JSON.stringify({ email: "user@example.com", balanceDollars: "$1.00" }),
+    status: "pending",
+    attempts: 0,
+    retryAfter: null,
+    sentAt: null,
+    createdAt: Date.now(),
+    ...overrides,
+  };
+}
+
+function makeQueue(pending: QueuedNotification[] = []): INotificationQueueRepository {
+  return {
+    enqueue: vi.fn().mockReturnValue("notif-id"),
+    fetchPending: vi.fn().mockReturnValue(pending),
+    markSent: vi.fn(),
+    markFailed: vi.fn(),
+    listForTenant: vi.fn().mockReturnValue({ entries: [], total: 0 }),
+  } as unknown as INotificationQueueRepository;
+}
+
+function makePrefs(prefs: Record<string, boolean> = {}): INotificationPreferencesRepository {
+  const defaultPrefs = {
+    billing_low_balance: true,
+    billing_receipts: true,
+    billing_auto_topup: true,
+    agent_channel_disconnect: true,
+    agent_status_changes: false,
+    account_role_changes: true,
+    account_team_invites: true,
+  };
+  return {
+    get: vi.fn().mockReturnValue({ ...defaultPrefs, ...prefs }),
+    update: vi.fn(),
+  } as unknown as INotificationPreferencesRepository;
+}
+
+function makeEmailClient(): EmailClient {
+  return {
+    send: vi.fn().mockResolvedValue({ id: "email-123", success: true }),
+    onEmailSent: vi.fn(),
+  } as unknown as EmailClient;
+}
+
+describe("NotificationWorker", () => {
+  let emailClient: EmailClient;
+
+  beforeEach(() => {
+    emailClient = makeEmailClient();
+  });
+
+  describe("processBatch", () => {
+    it("sends emails for pending notifications and marks them sent", async () => {
+      const notif = makeNotif();
+      const queue = makeQueue([notif]);
+      const prefs = makePrefs();
+      const worker = new NotificationWorker({ queue, emailClient, preferences: prefs });
+
+      const count = await worker.processBatch();
+
+      expect(emailClient.send).toHaveBeenCalledOnce();
+      expect(queue.markSent).toHaveBeenCalledWith("notif-1");
+      expect(count).toBe(1);
+    });
+
+    it("returns 0 when no pending notifications", async () => {
+      const queue = makeQueue([]);
+      const prefs = makePrefs();
+      const worker = new NotificationWorker({ queue, emailClient, preferences: prefs });
+
+      const count = await worker.processBatch();
+      expect(count).toBe(0);
+      expect(emailClient.send).not.toHaveBeenCalled();
+    });
+
+    it("marks notification as failed (not sent) when email is missing", async () => {
+      const notif = makeNotif({ data: JSON.stringify({}) }); // no email
+      const queue = makeQueue([notif]);
+      const prefs = makePrefs();
+      const worker = new NotificationWorker({ queue, emailClient, preferences: prefs });
+
+      await worker.processBatch();
+
+      expect(emailClient.send).not.toHaveBeenCalled();
+      expect(queue.markFailed).toHaveBeenCalledWith("notif-1", 1);
+    });
+
+    it("marks as sent (skipped) when user preference disables that template", async () => {
+      const notif = makeNotif({ template: "agent-created" }); // pref: agent_status_changes
+      const queue = makeQueue([notif]);
+      const prefs = makePrefs({ agent_status_changes: false }); // disabled
+      const worker = new NotificationWorker({ queue, emailClient, preferences: prefs });
+
+      await worker.processBatch();
+
+      expect(emailClient.send).not.toHaveBeenCalled();
+      expect(queue.markSent).toHaveBeenCalledWith("notif-1"); // cleared from queue
+    });
+
+    it("sends critical templates even when preferences would disable them", async () => {
+      // grace-period-start is critical — should bypass preference check
+      const notif = makeNotif({
+        template: "grace-period-start",
+        data: JSON.stringify({
+          email: "user@example.com",
+          balanceDollars: "$0.00",
+          graceDays: 7,
+          creditsUrl: "https://app.wopr.bot/billing/credits",
+        }),
+      });
+      const queue = makeQueue([notif]);
+      // Even if all prefs disabled, critical templates must send
+      const prefs = makePrefs({
+        billing_low_balance: false,
+        billing_receipts: false,
+        billing_auto_topup: false,
+      });
+      const worker = new NotificationWorker({ queue, emailClient, preferences: prefs });
+
+      await worker.processBatch();
+
+      expect(emailClient.send).toHaveBeenCalledOnce();
+      expect(queue.markSent).toHaveBeenCalledWith(notif.id);
+    });
+
+    it("marks as failed and increments attempts when send throws", async () => {
+      const notif = makeNotif({ attempts: 2 });
+      const queue = makeQueue([notif]);
+      const prefs = makePrefs();
+      vi.spyOn(emailClient, "send").mockRejectedValueOnce(new Error("Network error"));
+      const worker = new NotificationWorker({ queue, emailClient, preferences: prefs });
+
+      await worker.processBatch();
+
+      expect(queue.markFailed).toHaveBeenCalledWith("notif-1", 3); // attempts + 1
+      expect(queue.markSent).not.toHaveBeenCalled();
+    });
+
+    it("processes multiple notifications in one batch", async () => {
+      const notif1 = makeNotif({ id: "n1" });
+      const notif2 = makeNotif({
+        id: "n2",
+        template: "welcome",
+        data: JSON.stringify({ email: "b@b.com" }),
+      });
+      const queue = makeQueue([notif1, notif2]);
+      const prefs = makePrefs();
+      const worker = new NotificationWorker({ queue, emailClient, preferences: prefs });
+
+      const count = await worker.processBatch();
+
+      expect(count).toBe(2);
+      expect(emailClient.send).toHaveBeenCalledTimes(2);
+    });
+
+    it("respects custom batchSize", async () => {
+      const notifs = Array.from({ length: 5 }, (_, i) => makeNotif({ id: `n${i}` }));
+      const queue = makeQueue(notifs.slice(0, 3)); // fetchPending called with batchSize
+      const prefs = makePrefs();
+      const worker = new NotificationWorker({ queue, emailClient, preferences: prefs, batchSize: 3 });
+
+      await worker.processBatch();
+
+      expect(queue.fetchPending).toHaveBeenCalledWith(3);
+    });
+  });
+});

package/src/email/notification-worker.ts

@@ -0,0 +1,133 @@
+/**
+ * NotificationWorker — processes pending notification queue entries.
+ *
+ * Called on a timer (e.g. every 30s) from the server startup code.
+ * Do NOT put the interval inside this class.
+ */
+
+import { logger } from "../config/logger.js";
+import type { EmailClient } from "./client.js";
+import type {
+  INotificationPreferencesRepository,
+  INotificationQueueRepository,
+} from "./notification-repository-types.js";
+import { renderNotificationTemplate, type TemplateName } from "./notification-templates.js";
+
+export interface NotificationWorkerConfig {
+  queue: INotificationQueueRepository;
+  emailClient: EmailClient;
+  preferences: INotificationPreferencesRepository;
+  batchSize?: number;
+}
+
+/** Templates that bypass user preference checks — always sent. */
+const CRITICAL_TEMPLATES: Set<string> = new Set([
+  "grace-period-start",
+  "grace-period-warning",
+  "auto-suspended",
+  "admin-suspended",
+  "admin-reactivated",
+  "password-reset",
+  "welcome",
+  "account-deletion-requested",
+  "account-deletion-cancelled",
+  "account-deletion-completed",
+]);
+
+/** Map from template name to preference key. */
+const PREF_MAP: Record<string, string> = {
+  "low-balance": "billing_low_balance",
+  "credits-depleted": "billing_low_balance",
+  "auto-topup-success": "billing_auto_topup",
+  "auto-topup-failed": "billing_auto_topup",
+  "credit-purchase-receipt": "billing_receipts",
+  "crypto-payment-confirmed": "billing_receipts",
+  "channel-disconnected": "agent_channel_disconnect",
+  "agent-created": "agent_status_changes",
+  "channel-connected": "agent_status_changes",
+  "agent-suspended": "agent_status_changes",
+  "credits-granted": "billing_receipts",
+  "dividend-weekly-digest": "billing_receipts",
+  "role-changed": "account_role_changes",
+  "team-invite": "account_team_invites",
+};
+
+export class NotificationWorker {
+  private readonly queue: INotificationQueueRepository;
+  private readonly emailClient: EmailClient;
+  private readonly preferences: INotificationPreferencesRepository;
+  private readonly batchSize: number;
+
+  constructor(config: NotificationWorkerConfig) {
+    this.queue = config.queue;
+    this.emailClient = config.emailClient;
+    this.preferences = config.preferences;
+    this.batchSize = config.batchSize ?? 10;
+  }
+
+  /** Process one batch of pending notifications. Returns count of processed items. */
+  async processBatch(): Promise<number> {
+    const pending = await this.queue.fetchPending(this.batchSize);
+    let processed = 0;
+
+    for (const notif of pending) {
+      try {
+        const data = JSON.parse(notif.data) as Record<string, unknown>;
+        const email = data.email as string | undefined;
+
+        if (!email) {
+          logger.error("Notification missing email field", {
+            notificationId: notif.id,
+            template: notif.template,
+          });
+          this.queue.markFailed(notif.id, notif.attempts + 1);
+          processed++;
+          continue;
+        }
+
+        // Check preferences (skip for critical notifications)
+        if (!CRITICAL_TEMPLATES.has(notif.template)) {
+          const prefs = this.preferences.get(notif.tenantId);
+          if (!this.isEnabledByPreferences(notif.template, prefs as unknown as Record<string, boolean>)) {
+            // User has disabled this notification type — mark sent to clear queue
+            this.queue.markSent(notif.id);
+            processed++;
+            continue;
+          }
+        }
+
+        // Render the template
+        const rendered = renderNotificationTemplate(notif.template as TemplateName, data);
+
+        // Send via email client
+        await this.emailClient.send({
+          to: email,
+          subject: rendered.subject,
+          html: rendered.html,
+          text: rendered.text,
+          userId: notif.tenantId,
+          templateName: notif.template,
+        });
+
+        this.queue.markSent(notif.id);
+        processed++;
+      } catch (err) {
+        logger.error("Notification send failed", {
+          notificationId: notif.id,
+          template: notif.template,
+          error: err instanceof Error ? err.message : String(err),
+        });
+        this.queue.markFailed(notif.id, notif.attempts + 1);
+        processed++;
+      }
+    }
+
+    return processed;
+  }
+
+  private isEnabledByPreferences(template: string, prefs: Record<string, boolean>): boolean {
+    const prefKey = PREF_MAP[template];
+    if (!prefKey) return true; // unknown template -> send by default
+    return prefs[prefKey] !== false; // default to enabled if key missing
+  }
+}

package/src/email/require-verified.ts

@@ -0,0 +1,65 @@
+/**
+ * Email Verification Middleware — Blocks actions until email is verified.
+ *
+ * When used after session auth middleware, checks that the authenticated user
+ * has verified their email. API token auth (machine-to-machine) is not subject
+ * to email verification and is always allowed through.
+ */
+
+import type { Context, Next } from "hono";
+import { logger } from "../config/logger.js";
+
+/** Minimal interface for checking email verification status. */
+export interface IEmailVerifier {
+  isVerified(userId: string): Promise<boolean>;
+}
+
+/**
+ * Create middleware that blocks session-authenticated users who haven't verified their email.
+ *
+ * API token auth (authMethod === "api_key") bypasses this check since machine
+ * clients don't have email addresses to verify.
+ *
+ * @param verifier - Email verification store
+ */
+export function requireEmailVerified(verifier: IEmailVerifier) {
+  return async (c: Context, next: Next) => {
+    let authMethod: string | undefined;
+    let userId: string | undefined;
+
+    try {
+      authMethod = c.get("authMethod");
+      const user = c.get("user") as { id: string } | undefined;
+      userId = user?.id;
+    } catch {
+      // No auth context set — let downstream auth middleware handle 401
+      return next();
+    }
+
+    // API token auth bypasses email verification
+    if (authMethod === "api_key") {
+      return next();
+    }
+
+    // Session auth requires verified email
+    if (authMethod === "session" && userId) {
+      try {
+        if (!(await verifier.isVerified(userId))) {
+          return c.json(
+            {
+              error: "Email verification required",
+              message: "Please verify your email address before creating bots",
+              code: "EMAIL_NOT_VERIFIED",
+            },
+            403,
+          );
+        }
+      } catch (error) {
+        // If we can't check verification (DB issue), don't block the user
+        logger.warn("Email verification check failed", { error });
+      }
+    }
+
+    return next();
+  };
+}

package/src/email/resend-adapter.test.ts

@@ -0,0 +1,253 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  type EmailOptions,
+  escapeHtml,
+  passwordResetTemplate,
+  passwordResetText,
+  sendEmail,
+} from "./resend-adapter.js";
+
+// Create a mock send function that can be controlled in tests
+const mockSend = vi.fn();
+
+// Mock the Resend module
+vi.mock("resend", () => {
+  return {
+    Resend: class MockResend {
+      emails = {
+        send: mockSend,
+      };
+    },
+  };
+});
+
+describe("escapeHtml", () => {
+  it("should escape all dangerous HTML characters", () => {
+    expect(escapeHtml("<script>alert('XSS')</script>")).toBe("&lt;script&gt;alert(&#39;XSS&#39;)&lt;/script&gt;");
+    expect(escapeHtml('Test "quotes" & <tags>')).toBe("Test &quot;quotes&quot; &amp; &lt;tags&gt;");
+    expect(escapeHtml("user@example.com")).toBe("user@example.com");
+  });
+
+  it("should handle empty strings", () => {
+    expect(escapeHtml("")).toBe("");
+  });
+
+  it("should handle strings with no special characters", () => {
+    expect(escapeHtml("normal text 123")).toBe("normal text 123");
+  });
+});
+
+describe("sendEmail", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    delete process.env.RESEND_API_KEY;
+    delete process.env.RESEND_FROM_EMAIL;
+    // Reset mock to default success response
+    mockSend.mockResolvedValue({
+      data: { id: "test-email-id" },
+      error: null,
+    });
+  });
+
+  it("should send email with required options", async () => {
+    process.env.RESEND_API_KEY = "test-api-key";
+
+    const options: EmailOptions = {
+      to: "user@example.com",
+      subject: "Test Subject",
+      html: "<p>Test HTML</p>",
+    };
+
+    const result = await sendEmail(options);
+
+    expect(result).toEqual({
+      id: "test-email-id",
+      success: true,
+    });
+  });
+
+  it("should use custom API key when provided", async () => {
+    const options: EmailOptions = {
+      to: "user@example.com",
+      subject: "Test Subject",
+      html: "<p>Test HTML</p>",
+    };
+
+    const result = await sendEmail(options, "custom-api-key");
+
+    expect(result.success).toBe(true);
+  });
+
+  it("should use custom from address when provided", async () => {
+    process.env.RESEND_API_KEY = "test-api-key";
+
+    const options: EmailOptions = {
+      to: "user@example.com",
+      subject: "Test Subject",
+      html: "<p>Test HTML</p>",
+    };
+
+    const result = await sendEmail(options, undefined, "custom@example.com");
+
+    expect(result.success).toBe(true);
+  });
+
+  it("should throw error when RESEND_API_KEY is missing", async () => {
+    const options: EmailOptions = {
+      to: "user@example.com",
+      subject: "Test Subject",
+      html: "<p>Test HTML</p>",
+    };
+
+    await expect(sendEmail(options)).rejects.toThrow("RESEND_API_KEY environment variable is required");
+  });
+
+  it("should handle Resend API errors", async () => {
+    process.env.RESEND_API_KEY = "test-api-key";
+
+    // Mock Resend to return an error for this specific test
+    mockSend.mockResolvedValueOnce({
+      data: null,
+      error: { message: "API error" },
+    });
+
+    const options: EmailOptions = {
+      to: "user@example.com",
+      subject: "Test Subject",
+      html: "<p>Test HTML</p>",
+    };
+
+    await expect(sendEmail(options)).rejects.toThrow("Failed to send email: API error");
+  });
+
+  it("should use default from email when env var is set", async () => {
+    process.env.RESEND_API_KEY = "test-api-key";
+    process.env.RESEND_FROM_EMAIL = "default@example.com";
+
+    const options: EmailOptions = {
+      to: "user@example.com",
+      subject: "Test Subject",
+      html: "<p>Test HTML</p>",
+    };
+
+    const result = await sendEmail(options);
+
+    expect(result.success).toBe(true);
+  });
+
+  it("should include text version when provided", async () => {
+    process.env.RESEND_API_KEY = "test-api-key";
+
+    const options: EmailOptions = {
+      to: "user@example.com",
+      subject: "Test Subject",
+      html: "<p>Test HTML</p>",
+      text: "Test plain text",
+    };
+
+    const result = await sendEmail(options);
+
+    expect(result.success).toBe(true);
+  });
+});
+
+describe("passwordResetTemplate", () => {
+  it("should generate HTML template with reset URL", () => {
+    const resetUrl = "https://wopr.bot/reset?token=abc123";
+    const email = "user@example.com";
+
+    const html = passwordResetTemplate(resetUrl, email);
+
+    expect(html).toContain(resetUrl);
+    expect(html).toContain(email);
+    expect(html).toContain("Reset Your Password");
+    expect(html).toContain("Reset Password");
+    expect(html).toContain("<!DOCTYPE html>");
+  });
+
+  it("should escape HTML characters in email and URL to prevent XSS", () => {
+    const resetUrl = "https://wopr.bot/reset?token=<script>alert(1)</script>";
+    const email = "<script>alert('xss')</script>@example.com";
+
+    const html = passwordResetTemplate(resetUrl, email);
+
+    // Verify email is escaped in the text where it's displayed
+    expect(html).toContain("&lt;script&gt;alert(&#39;xss&#39;)&lt;/script&gt;@example.com");
+
+    // Verify resetUrl is escaped in the displayed text (not href)
+    expect(html).toContain("&lt;script&gt;alert(1)&lt;/script&gt;");
+
+    // Verify the email script tag doesn't appear unescaped in body text
+    // (it may appear in href attribute, which is safe from XSS)
+    const bodyMatch = html.match(/<p>.*<\/p>/gs);
+    const bodyText = bodyMatch ? bodyMatch.join("") : "";
+    expect(bodyText).not.toContain("<script>alert('xss')</script>");
+  });
+
+  it("should include current year in footer", () => {
+    const resetUrl = "https://wopr.bot/reset?token=abc123";
+    const email = "user@example.com";
+
+    const html = passwordResetTemplate(resetUrl, email);
+
+    const currentYear = new Date().getFullYear();
+    expect(html).toContain(`© ${currentYear} WOPR Network`);
+  });
+
+  it("should be valid HTML structure", () => {
+    const resetUrl = "https://wopr.bot/reset?token=abc123";
+    const email = "user@example.com";
+
+    const html = passwordResetTemplate(resetUrl, email);
+
+    expect(html).toContain("<html>");
+    expect(html).toContain("</html>");
+    expect(html).toContain("<head>");
+    expect(html).toContain("</head>");
+    expect(html).toContain("<body");
+    expect(html).toContain("</body>");
+  });
+});
+
+describe("passwordResetText", () => {
+  it("should generate plain text with reset URL", () => {
+    const resetUrl = "https://wopr.bot/reset?token=abc123";
+    const email = "user@example.com";
+
+    const text = passwordResetText(resetUrl, email);
+
+    expect(text).toContain(resetUrl);
+    expect(text).toContain(email);
+    expect(text).toContain("Reset Your Password");
+  });
+
+  it("should not contain HTML tags", () => {
+    const resetUrl = "https://wopr.bot/reset?token=abc123";
+    const email = "user@example.com";
+
+    const text = passwordResetText(resetUrl, email);
+
+    expect(text).not.toContain("<");
+    expect(text).not.toContain(">");
+  });
+
+  it("should include current year in footer", () => {
+    const resetUrl = "https://wopr.bot/reset?token=abc123";
+    const email = "user@example.com";
+
+    const text = passwordResetText(resetUrl, email);
+
+    const currentYear = new Date().getFullYear();
+    expect(text).toContain(`© ${currentYear} WOPR Network`);
+  });
+
+  it("should be readable plain text format", () => {
+    const resetUrl = "https://wopr.bot/reset?token=abc123";
+    const email = "user@example.com";
+
+    const text = passwordResetText(resetUrl, email);
+
+    // Should have line breaks and be formatted
+    expect(text.split("\n").length).toBeGreaterThan(5);
+  });
+});