@wopr-network/platform-core 0.1.0

package/src/email/client.test.ts

@@ -0,0 +1,149 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { EmailClient, getEmailClient, resetEmailClient, setEmailClient } from "./client.js";
+
+const mockSend = vi.fn();
+
+vi.mock("resend", () => ({
+  Resend: class MockResend {
+    emails = { send: mockSend };
+  },
+}));
+
+vi.mock("../config/logger.js", () => ({
+  logger: {
+    info: vi.fn(),
+    error: vi.fn(),
+    warn: vi.fn(),
+    debug: vi.fn(),
+  },
+}));
+
+describe("EmailClient", () => {
+  let client: EmailClient;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockSend.mockResolvedValue({ data: { id: "email-123" }, error: null });
+    client = new EmailClient({
+      apiKey: "test-api-key",
+      from: "noreply@wopr.bot",
+      replyTo: "support@wopr.bot",
+    });
+  });
+
+  it("should send email with correct parameters", async () => {
+    const result = await client.send({
+      to: "user@test.com",
+      subject: "Test Subject",
+      html: "<p>Test</p>",
+      text: "Test",
+    });
+
+    expect(result).toEqual({ id: "email-123", success: true });
+    expect(mockSend).toHaveBeenCalledWith({
+      from: "noreply@wopr.bot",
+      replyTo: "support@wopr.bot",
+      to: "user@test.com",
+      subject: "Test Subject",
+      html: "<p>Test</p>",
+      text: "Test",
+    });
+  });
+
+  it("should throw on Resend API error", async () => {
+    mockSend.mockResolvedValueOnce({ data: null, error: { message: "Rate limit" } });
+
+    await expect(client.send({ to: "user@test.com", subject: "Test", html: "<p>T</p>", text: "T" })).rejects.toThrow(
+      "Failed to send email: Rate limit",
+    );
+  });
+
+  it("should invoke onEmailSent callback after successful send", async () => {
+    const callback = vi.fn();
+    client.onEmailSent(callback);
+
+    const result = await client.send({
+      to: "user@test.com",
+      subject: "Test",
+      html: "<p>T</p>",
+      text: "T",
+      userId: "user-1",
+      templateName: "verify-email",
+    });
+
+    expect(callback).toHaveBeenCalledWith(
+      expect.objectContaining({ to: "user@test.com", templateName: "verify-email" }),
+      result,
+    );
+  });
+
+  it("should not throw if onEmailSent callback errors", async () => {
+    const callback = vi.fn().mockImplementation(() => {
+      throw new Error("callback failed");
+    });
+    client.onEmailSent(callback);
+
+    const result = await client.send({
+      to: "user@test.com",
+      subject: "Test",
+      html: "<p>T</p>",
+      text: "T",
+    });
+
+    expect(result.success).toBe(true);
+    expect(callback).toHaveBeenCalled();
+  });
+
+  it("should handle empty id from Resend", async () => {
+    mockSend.mockResolvedValueOnce({ data: { id: undefined }, error: null });
+
+    const result = await client.send({
+      to: "user@test.com",
+      subject: "Test",
+      html: "<p>T</p>",
+      text: "T",
+    });
+
+    expect(result).toEqual({ id: "", success: true });
+  });
+});
+
+describe("getEmailClient / setEmailClient / resetEmailClient", () => {
+  beforeEach(() => {
+    resetEmailClient();
+    delete process.env.RESEND_API_KEY;
+    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 create client from env vars", () => {
+    process.env.RESEND_API_KEY = "re_test123";
+    const client = getEmailClient();
+    expect(client).toBeInstanceOf(EmailClient);
+  });
+
+  it("should return singleton", () => {
+    process.env.RESEND_API_KEY = "re_test123";
+    const a = getEmailClient();
+    const b = getEmailClient();
+    expect(a).toBe(b);
+  });
+
+  it("should allow replacing singleton for testing", () => {
+    const mock = new EmailClient({ apiKey: "mock", from: "mock@test.com" });
+    setEmailClient(mock);
+    expect(getEmailClient()).toBe(mock);
+  });
+
+  it("should reset singleton", () => {
+    process.env.RESEND_API_KEY = "re_test123";
+    const a = getEmailClient();
+    resetEmailClient();
+    const b = getEmailClient();
+    expect(a).not.toBe(b);
+  });
+});

package/src/email/client.ts

@@ -0,0 +1,137 @@
+/**
+ * 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.
+ */
+
+import { Resend } from "resend";
+import { logger } from "../config/logger.js";
+
+export interface EmailClientConfig {
+  apiKey: string;
+  from: string;
+  replyTo?: string;
+}
+
+export interface SendTemplateEmailOpts {
+  to: string;
+  subject: string;
+  html: string;
+  text: string;
+  /** Audit metadata: who triggered this email */
+  userId?: string;
+  /** Audit metadata: which template was used */
+  templateName?: string;
+}
+
+export interface EmailSendResult {
+  id: string;
+  success: boolean;
+}
+
+/**
+ * Transactional email client backed by Resend.
+ *
+ * Usage:
+ * ```ts
+ * const client = new EmailClient({ apiKey: "re_xxx", from: "noreply@wopr.bot" });
+ * 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 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;
+  }
+
+  /** Register a callback invoked after each successful send (for audit logging). */
+  onEmailSent(callback: (opts: SendTemplateEmailOpts, result: EmailSendResult) => void): void {
+    this.onSend = callback;
+  }
+
+  /** Send a transactional email. */
+  async send(opts: SendTemplateEmailOpts): Promise<EmailSendResult> {
+    const { data, error } = await this.resend.emails.send({
+      from: this.from,
+      replyTo: this.replyTo,
+      to: opts.to,
+      subject: opts.subject,
+      html: opts.html,
+      text: opts.text,
+    });
+
+    if (error) {
+      logger.error("Failed to send email", {
+        to: opts.to,
+        template: opts.templateName,
+        error: error.message,
+      });
+      throw new Error(`Failed to send email: ${error.message}`);
+    }
+
+    const result: EmailSendResult = {
+      id: data?.id || "",
+      success: true,
+    };
+
+    logger.info("Email sent", {
+      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")
+ */
+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");
+    }
+    _client = new EmailClient({
+      apiKey,
+      from: process.env.RESEND_FROM || "noreply@wopr.bot",
+      replyTo: process.env.RESEND_REPLY_TO || "support@wopr.bot",
+    });
+  }
+  return _client;
+}
+
+/** Reset the singleton (for testing). */
+export function resetEmailClient(): void {
+  _client = null;
+}
+
+/** Replace the singleton (for testing). */
+export function setEmailClient(client: EmailClient): void {
+  _client = client;
+}

package/src/email/drizzle-billing-email-repository.test.ts

@@ -0,0 +1,52 @@
+import type { PGlite } from "@electric-sql/pglite";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import type { PlatformDb } from "../db/index.js";
+import { createTestDb } from "../test/db.js";
+import { DrizzleBillingEmailRepository } from "./drizzle-billing-email-repository.js";
+
+describe("DrizzleBillingEmailRepository", () => {
+  let db: PlatformDb;
+  let pool: PGlite;
+  let repo: DrizzleBillingEmailRepository;
+
+  beforeAll(async () => {
+    const result = await createTestDb();
+    db = result.db;
+    pool = result.pool;
+    repo = new DrizzleBillingEmailRepository(db);
+  });
+
+  afterAll(async () => {
+    await pool.close();
+  });
+
+  it("shouldSend returns true when no email sent today", async () => {
+    const result = await repo.shouldSend("tenant-email-1", "low-balance");
+    expect(result).toBe(true);
+  });
+
+  it("recordSent inserts a dedup record", async () => {
+    await repo.recordSent("tenant-email-1", "low-balance");
+    const result = await repo.shouldSend("tenant-email-1", "low-balance");
+    expect(result).toBe(false);
+  });
+
+  it("shouldSend returns true for different email type same tenant", async () => {
+    const result = await repo.shouldSend("tenant-email-1", "bot-suspended");
+    expect(result).toBe(true);
+  });
+
+  it("shouldSend returns true for same email type different tenant", async () => {
+    const result = await repo.shouldSend("tenant-email-2", "low-balance");
+    expect(result).toBe(true);
+  });
+
+  it("recordSent for different tenant does not affect dedup", async () => {
+    await repo.recordSent("tenant-email-3", "low-balance");
+    const result = await repo.shouldSend("tenant-email-3", "low-balance");
+    expect(result).toBe(false);
+    // original tenant-email-1 dedup still holds
+    const result2 = await repo.shouldSend("tenant-email-1", "low-balance");
+    expect(result2).toBe(false);
+  });
+});

package/src/email/drizzle-billing-email-repository.ts

@@ -0,0 +1,59 @@
+/**
+ * Billing Email Repository — deduplication record storage for billing emails.
+ *
+ * Implements IBillingEmailRepository using Drizzle ORM.
+ * BillingEmailService depends on this interface, not on PlatformDb directly.
+ */
+
+import crypto from "node:crypto";
+import { and, eq } from "drizzle-orm";
+import type { PlatformDb } from "../db/index.js";
+import { emailNotifications } from "../db/schema/email-notifications.js";
+import type { BillingEmailType } from "./billing-emails.js";
+
+// ---------------------------------------------------------------------------
+// Interface
+// ---------------------------------------------------------------------------
+
+/** Repository interface for billing email deduplication records. */
+export interface IBillingEmailRepository {
+  /** Returns true if no email of this type was sent to this tenant today. */
+  shouldSend(tenantId: string, emailType: BillingEmailType): Promise<boolean>;
+  /** Records that an email was sent. */
+  recordSent(tenantId: string, emailType: BillingEmailType): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Drizzle Implementation
+// ---------------------------------------------------------------------------
+
+export class DrizzleBillingEmailRepository implements IBillingEmailRepository {
+  constructor(private readonly db: PlatformDb) {}
+
+  async shouldSend(tenantId: string, emailType: BillingEmailType): Promise<boolean> {
+    const today = new Date().toISOString().split("T")[0];
+    const rows = await this.db
+      .select({ id: emailNotifications.id })
+      .from(emailNotifications)
+      .where(
+        and(
+          eq(emailNotifications.tenantId, tenantId),
+          eq(emailNotifications.emailType, emailType),
+          eq(emailNotifications.sentDate, today),
+        ),
+      )
+      .limit(1);
+
+    return rows.length === 0;
+  }
+
+  async recordSent(tenantId: string, emailType: BillingEmailType): Promise<void> {
+    const today = new Date().toISOString().split("T")[0];
+    await this.db.insert(emailNotifications).values({
+      id: crypto.randomUUID(),
+      tenantId,
+      emailType,
+      sentDate: today,
+    });
+  }
+}

package/src/email/index.ts

@@ -0,0 +1,57 @@
+/**
+ * Email — Transactional email system via Resend.
+ *
+ * Provides:
+ * - EmailClient for sending template-based emails
+ * - 8 email templates (verify, welcome, password-reset, credit-purchase, low-balance, bot-suspended, bot-destruction, data-deleted)
+ * - BillingEmailService for deduplication + billing notifications (WOP-450)
+ * - Email verification flow (token generation, validation)
+ * - requireEmailVerified middleware for gating actions
+ */
+
+export type { BillingEmailServiceConfig, BillingEmailType } from "./billing-emails.js";
+export { BillingEmailService } from "./billing-emails.js";
+export type { EmailClientConfig, EmailSendResult, SendTemplateEmailOpts } from "./client.js";
+export { EmailClient, getEmailClient, resetEmailClient, setEmailClient } from "./client.js";
+export type { IBillingEmailRepository } from "./drizzle-billing-email-repository.js";
+export { DrizzleBillingEmailRepository } from "./drizzle-billing-email-repository.js";
+export type { INotificationPreferencesRepository } from "./notification-preferences-store.js";
+export { DrizzleNotificationPreferencesStore } from "./notification-preferences-store.js";
+export type { INotificationQueueRepository } from "./notification-queue-store.js";
+export { DrizzleNotificationQueueStore } from "./notification-queue-store.js";
+export type {
+  NotificationPrefs,
+  NotificationStatus,
+  QueuedNotification,
+  NotificationEmailType,
+  NotificationInput,
+  NotificationRow,
+} from "./notification-repository-types.js";
+export { NotificationService } from "./notification-service.js";
+export type { TemplateName as NotificationTemplateName } from "./notification-templates.js";
+export { renderNotificationTemplate } from "./notification-templates.js";
+export { NotificationWorker } from "./notification-worker.js";
+export type { IEmailVerifier } from "./require-verified.js";
+export { requireEmailVerified } from "./require-verified.js";
+export type { EmailOptions } from "./resend-adapter.js";
+export { escapeHtml, passwordResetTemplate, passwordResetText, sendEmail } from "./resend-adapter.js";
+export type { TemplateName, TemplateResult } from "./templates.js";
+export {
+  botDestructionTemplate,
+  botSuspendedTemplate,
+  creditPurchaseTemplate,
+  dataDeletedTemplate,
+  lowBalanceTemplate,
+  passwordResetEmailTemplate,
+  verifyEmailTemplate,
+  welcomeTemplate,
+} from "./templates.js";
+export type { VerificationToken } from "./verification.js";
+export {
+  generateVerificationToken,
+  getUserEmail,
+  initVerificationSchema,
+  isEmailVerified,
+  PgEmailVerifier,
+  verifyToken,
+} from "./verification.js";

package/src/email/notification-preferences-store.test.ts

@@ -0,0 +1,102 @@
+import type { PGlite } from "@electric-sql/pglite";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import type { PlatformDb } from "../db/index.js";
+import { beginTestTransaction, createTestDb, endTestTransaction, rollbackTestTransaction } from "../test/db.js";
+import { DrizzleNotificationPreferencesStore } from "./notification-preferences-store.js";
+
+describe("DrizzleNotificationPreferencesStore", () => {
+  let db: PlatformDb;
+  let pool: PGlite;
+  let store: DrizzleNotificationPreferencesStore;
+
+  beforeAll(async () => {
+    ({ db, pool } = await createTestDb());
+    await beginTestTransaction(pool);
+  });
+
+  afterAll(async () => {
+    await endTestTransaction(pool);
+    await pool.close();
+  });
+
+  beforeEach(async () => {
+    await rollbackTestTransaction(pool);
+    store = new DrizzleNotificationPreferencesStore(db);
+  });
+
+  describe("get", () => {
+    it("returns defaults when no row exists", async () => {
+      const prefs = await store.get("tenant-1");
+      expect(prefs).toEqual({
+        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,
+      });
+    });
+
+    it("returns stored values when row exists", async () => {
+      await store.update("tenant-1", { billing_low_balance: false, agent_status_changes: true });
+      const prefs = await store.get("tenant-1");
+      expect(prefs.billing_low_balance).toBe(false);
+      expect(prefs.agent_status_changes).toBe(true);
+    });
+
+    it("maps integer 1 to true and 0 to false", async () => {
+      await store.update("tenant-1", { billing_low_balance: true });
+      const prefs = await store.get("tenant-1");
+      expect(typeof prefs.billing_low_balance).toBe("boolean");
+      expect(prefs.billing_low_balance).toBe(true);
+    });
+  });
+
+  describe("update", () => {
+    it("creates row on first call (upsert)", async () => {
+      await store.update("tenant-1", { billing_low_balance: false });
+      const prefs = await store.get("tenant-1");
+      expect(prefs.billing_low_balance).toBe(false);
+    });
+
+    it("merges partial updates without touching unspecified fields", async () => {
+      await store.update("tenant-1", { billing_low_balance: false });
+      await store.update("tenant-1", { billing_receipts: false });
+
+      const prefs = await store.get("tenant-1");
+      expect(prefs.billing_low_balance).toBe(false);
+      expect(prefs.billing_receipts).toBe(false);
+      expect(prefs.billing_auto_topup).toBe(true); // default unchanged
+    });
+
+    it("allows setting all preferences at once", async () => {
+      await store.update("tenant-1", {
+        billing_low_balance: false,
+        billing_receipts: false,
+        billing_auto_topup: false,
+        agent_channel_disconnect: false,
+        agent_status_changes: true,
+        account_role_changes: false,
+        account_team_invites: false,
+      });
+
+      const prefs = await store.get("tenant-1");
+      expect(prefs.billing_low_balance).toBe(false);
+      expect(prefs.billing_receipts).toBe(false);
+      expect(prefs.billing_auto_topup).toBe(false);
+      expect(prefs.agent_channel_disconnect).toBe(false);
+      expect(prefs.agent_status_changes).toBe(true);
+      expect(prefs.account_role_changes).toBe(false);
+      expect(prefs.account_team_invites).toBe(false);
+    });
+
+    it("second call updates existing row", async () => {
+      await store.update("tenant-1", { billing_low_balance: false });
+      await store.update("tenant-1", { billing_low_balance: true });
+
+      const prefs = await store.get("tenant-1");
+      expect(prefs.billing_low_balance).toBe(true);
+    });
+  });
+});

package/src/email/notification-preferences-store.ts

@@ -0,0 +1,90 @@
+import { eq } from "drizzle-orm";
+import type { PlatformDb } from "../db/index.js";
+import { notificationPreferences } from "../db/schema/notification-preferences.js";
+import type { INotificationPreferencesRepository, NotificationPrefs } from "./notification-repository-types.js";
+
+// Re-export domain type for backward compat
+export type { NotificationPrefs } from "./notification-repository-types.js";
+
+// Re-export with old name for backward compat
+export type { INotificationPreferencesRepository };
+
+type NotificationPrefsRow = typeof notificationPreferences.$inferInsert;
+
+// ---------------------------------------------------------------------------
+// Drizzle Implementation
+// ---------------------------------------------------------------------------
+
+const DEFAULTS: NotificationPrefs = {
+  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,
+};
+
+export class DrizzleNotificationPreferencesStore implements INotificationPreferencesRepository {
+  constructor(private readonly db: PlatformDb) {}
+
+  /** Get preferences for a tenant. Returns defaults if no row exists. */
+  async get(tenantId: string): Promise<NotificationPrefs> {
+    const rows = await this.db
+      .select()
+      .from(notificationPreferences)
+      .where(eq(notificationPreferences.tenantId, tenantId));
+    const row = rows[0];
+
+    if (!row) return { ...DEFAULTS };
+
+    return {
+      billing_low_balance: row.billingLowBalance,
+      billing_receipts: row.billingReceipts,
+      billing_auto_topup: row.billingAutoTopup,
+      agent_channel_disconnect: row.agentChannelDisconnect,
+      agent_status_changes: row.agentStatusChanges,
+      account_role_changes: row.accountRoleChanges,
+      account_team_invites: row.accountTeamInvites,
+    };
+  }
+
+  /** Update preferences for a tenant. Upserts — creates row if missing. */
+  async update(tenantId: string, prefs: Partial<NotificationPrefs>): Promise<void> {
+    const values: Partial<NotificationPrefsRow> = { tenantId, updatedAt: Math.floor(Date.now() / 1000) };
+
+    if (prefs.billing_low_balance !== undefined) values.billingLowBalance = prefs.billing_low_balance;
+    if (prefs.billing_receipts !== undefined) values.billingReceipts = prefs.billing_receipts;
+    if (prefs.billing_auto_topup !== undefined) values.billingAutoTopup = prefs.billing_auto_topup;
+    if (prefs.agent_channel_disconnect !== undefined) values.agentChannelDisconnect = prefs.agent_channel_disconnect;
+    if (prefs.agent_status_changes !== undefined) values.agentStatusChanges = prefs.agent_status_changes;
+    if (prefs.account_role_changes !== undefined) values.accountRoleChanges = prefs.account_role_changes;
+    if (prefs.account_team_invites !== undefined) values.accountTeamInvites = prefs.account_team_invites;
+
+    // Get existing row to merge with defaults
+    const existing = await this.db
+      .select()
+      .from(notificationPreferences)
+      .where(eq(notificationPreferences.tenantId, tenantId));
+
+    if (existing.length > 0) {
+      // Only update the set fields
+      await this.db.update(notificationPreferences).set(values).where(eq(notificationPreferences.tenantId, tenantId));
+    } else {
+      // Insert with defaults for unspecified fields
+      const insertValues: NotificationPrefsRow = {
+        tenantId,
+        billingLowBalance: DEFAULTS.billing_low_balance,
+        billingReceipts: DEFAULTS.billing_receipts,
+        billingAutoTopup: DEFAULTS.billing_auto_topup,
+        agentChannelDisconnect: DEFAULTS.agent_channel_disconnect,
+        agentStatusChanges: DEFAULTS.agent_status_changes,
+        accountRoleChanges: DEFAULTS.account_role_changes,
+        accountTeamInvites: DEFAULTS.account_team_invites,
+        updatedAt: Math.floor(Date.now() / 1000),
+        ...values,
+      };
+      await this.db.insert(notificationPreferences).values(insertValues);
+    }
+  }
+}