@wopr-network/platform-core 0.1.0

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

@@ -0,0 +1,215 @@
+import type { PGlite } from "@electric-sql/pglite";
+import { eq } from "drizzle-orm";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import type { PlatformDb } from "../db/index.js";
+import { notificationQueue } from "../db/schema/notification-queue.js";
+import { beginTestTransaction, createTestDb, endTestTransaction, rollbackTestTransaction } from "../test/db.js";
+import { DrizzleNotificationQueueStore } from "./notification-queue-store.js";
+
+describe("DrizzleNotificationQueueStore", () => {
+  let db: PlatformDb;
+  let pool: PGlite;
+  let store: DrizzleNotificationQueueStore;
+
+  beforeAll(async () => {
+    ({ db, pool } = await createTestDb());
+    await beginTestTransaction(pool);
+  });
+
+  afterAll(async () => {
+    await endTestTransaction(pool);
+    await pool.close();
+  });
+
+  beforeEach(async () => {
+    await rollbackTestTransaction(pool);
+    store = new DrizzleNotificationQueueStore(db);
+  });
+
+  describe("enqueue", () => {
+    it("creates a pending notification row", async () => {
+      const id = await store.enqueue("tenant-1", "low-balance", { email: "user@example.com" });
+      expect(id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+
+      const rows = await db.select().from(notificationQueue);
+      expect(rows).toHaveLength(1);
+      expect(rows[0].id).toBe(id);
+      expect(rows[0].tenantId).toBe("tenant-1");
+      // emailType stores the template name
+      expect(rows[0].emailType).toBe("low-balance");
+      expect(rows[0].status).toBe("pending");
+      expect(rows[0].attempts).toBe(0);
+    });
+
+    it("serializes data as JSON payload", async () => {
+      await store.enqueue("tenant-1", "low-balance", { email: "a@b.com", amount: 42 });
+      const rows = await db.select().from(notificationQueue);
+      expect(JSON.parse(rows[0].payload)).toEqual({ email: "a@b.com", amount: 42 });
+    });
+
+    it("returns a unique ID each call", async () => {
+      const id1 = await store.enqueue("tenant-1", "low-balance", {});
+      const id2 = await store.enqueue("tenant-1", "low-balance", {});
+      expect(id1).not.toBe(id2);
+    });
+
+    it("exposes template via QueuedNotification interface", async () => {
+      await store.enqueue("tenant-1", "low-balance", { email: "a@b.com" });
+      const pending = await store.fetchPending(10);
+      expect(pending[0].template).toBe("low-balance");
+    });
+
+    it("exposes data via QueuedNotification interface", async () => {
+      await store.enqueue("tenant-1", "low-balance", { email: "a@b.com", amount: 42 });
+      const pending = await store.fetchPending(10);
+      expect(JSON.parse(pending[0].data)).toEqual({ email: "a@b.com", amount: 42 });
+    });
+  });
+
+  describe("fetchPending", () => {
+    it("returns pending notifications", async () => {
+      await store.enqueue("tenant-1", "low-balance", { email: "a@b.com" });
+      const pending = await store.fetchPending(10);
+      expect(pending).toHaveLength(1);
+      expect(pending[0].template).toBe("low-balance");
+    });
+
+    it("does not return sent notifications", async () => {
+      const id = await store.enqueue("tenant-1", "low-balance", { email: "a@b.com" });
+      await store.markSent(id);
+      const pending = await store.fetchPending(10);
+      expect(pending).toHaveLength(0);
+    });
+
+    it("does not return permanently failed notifications", async () => {
+      const id = await store.enqueue("tenant-1", "low-balance", { email: "a@b.com" });
+      // 5 attempts = permanently failed
+      await store.markFailed(id, 5);
+      const pending = await store.fetchPending(10);
+      expect(pending).toHaveLength(0);
+    });
+
+    it("respects limit parameter", async () => {
+      await store.enqueue("tenant-1", "low-balance", {});
+      await store.enqueue("tenant-1", "low-balance", {});
+      await store.enqueue("tenant-1", "low-balance", {});
+      const pending = await store.fetchPending(2);
+      expect(pending).toHaveLength(2);
+    });
+  });
+
+  describe("markSent", () => {
+    it("transitions status to sent and sets sentAt", async () => {
+      const id = await store.enqueue("tenant-1", "low-balance", {});
+      const before = Date.now();
+      await store.markSent(id);
+      const after = Date.now();
+
+      const rows = await db.select().from(notificationQueue);
+      expect(rows[0].status).toBe("sent");
+      expect(rows[0].sentAt).toBeGreaterThanOrEqual(before);
+      expect(rows[0].sentAt).toBeLessThanOrEqual(after);
+    });
+  });
+
+  describe("markFailed", () => {
+    it("increments attempts and applies exponential backoff for first failure", async () => {
+      const id = await store.enqueue("tenant-1", "low-balance", {});
+      const before = Date.now();
+      await store.markFailed(id, 1);
+      const after = Date.now();
+
+      const rows = await db.select().from(notificationQueue);
+      expect(rows[0].attempts).toBe(1);
+      // 1st attempt: 60s * 2^1 = 120s backoff
+      const expectedBackoff = 60_000 * 2 ** 1;
+      expect(rows[0].retryAfter).toBeGreaterThanOrEqual(before + expectedBackoff - 100);
+      expect(rows[0].retryAfter).toBeLessThanOrEqual(after + expectedBackoff + 100);
+    });
+
+    it("caps backoff at 1 hour", async () => {
+      const id = await store.enqueue("tenant-1", "low-balance", {});
+      await store.markFailed(id, 4);
+
+      const rows = await db.select().from(notificationQueue);
+      // backoff = 60_000 * 2^4 = 960_000ms > 3_600_000ms cap
+      const maxBackoff = 3_600_000;
+      expect(rows[0].retryAfter).toBeLessThanOrEqual(Date.now() + maxBackoff + 1000);
+    });
+
+    it("permanently fails after 5 attempts", async () => {
+      const id = await store.enqueue("tenant-1", "low-balance", {});
+      await store.markFailed(id, 5);
+
+      const rows = await db.select().from(notificationQueue);
+      expect(rows[0].status).toBe("failed");
+      expect(rows[0].attempts).toBe(5);
+    });
+
+    it("keeps status as pending with retry for attempts below 5", async () => {
+      const id = await store.enqueue("tenant-1", "low-balance", {});
+      await store.markFailed(id, 3);
+
+      const rows = await db.select().from(notificationQueue);
+      expect(rows[0].status).toBe("pending");
+    });
+  });
+
+  describe("listForTenant", () => {
+    it("returns notifications for the given tenant", async () => {
+      await store.enqueue("tenant-1", "low-balance", {});
+      await store.enqueue("tenant-2", "low-balance", {});
+      await store.enqueue("tenant-1", "welcome", {});
+
+      const result = await store.listForTenant("tenant-1");
+      expect(result.entries).toHaveLength(2);
+      expect(result.total).toBe(2);
+    });
+
+    it("returns most recent first (ordered by createdAt desc)", async () => {
+      const id1 = await store.enqueue("tenant-1", "template-a", {});
+      const id2 = await store.enqueue("tenant-1", "template-b", {});
+
+      // Force distinct timestamps so ordering is deterministic
+      await db.update(notificationQueue).set({ createdAt: 1000 }).where(eq(notificationQueue.id, id1));
+      await db.update(notificationQueue).set({ createdAt: 2000 }).where(eq(notificationQueue.id, id2));
+
+      const result = await store.listForTenant("tenant-1");
+      // Most recent (id2, createdAt=2000) should be first
+      expect(result.entries[0].id).toBe(id2);
+      expect(result.entries[1].id).toBe(id1);
+    });
+
+    it("paginates results", async () => {
+      await store.enqueue("tenant-1", "template-a", {});
+      await store.enqueue("tenant-1", "template-b", {});
+      await store.enqueue("tenant-1", "template-c", {});
+
+      const page1 = await store.listForTenant("tenant-1", { limit: 2, offset: 0 });
+      expect(page1.entries).toHaveLength(2);
+      expect(page1.total).toBe(3);
+
+      const page2 = await store.listForTenant("tenant-1", { limit: 2, offset: 2 });
+      expect(page2.entries).toHaveLength(1);
+    });
+
+    it("filters by status", async () => {
+      const id = await store.enqueue("tenant-1", "low-balance", {});
+      await store.enqueue("tenant-1", "welcome", {});
+      await store.markSent(id);
+
+      const sent = await store.listForTenant("tenant-1", { status: "sent" });
+      expect(sent.entries).toHaveLength(1);
+      expect(sent.entries[0].status).toBe("sent");
+
+      const pending = await store.listForTenant("tenant-1", { status: "pending" });
+      expect(pending.entries).toHaveLength(1);
+    });
+
+    it("returns empty for unknown tenant", async () => {
+      const result = await store.listForTenant("nonexistent");
+      expect(result.entries).toHaveLength(0);
+      expect(result.total).toBe(0);
+    });
+  });
+});

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

@@ -0,0 +1,127 @@
+import crypto from "node:crypto";
+import { and, desc, eq, lte, or, sql } from "drizzle-orm";
+import type { PlatformDb } from "../db/index.js";
+import { notificationQueue } from "../db/schema/notification-queue.js";
+import type {
+  INotificationQueueRepository,
+  NotificationStatus,
+  QueuedNotification,
+} from "./notification-repository-types.js";
+
+// Re-export domain types for backward compat
+export type { NotificationStatus, QueuedNotification } from "./notification-repository-types.js";
+
+// Re-export with old name for backward compat
+export type { INotificationQueueRepository };
+
+// ---------------------------------------------------------------------------
+// Drizzle Implementation
+// ---------------------------------------------------------------------------
+
+export class DrizzleNotificationQueueStore implements INotificationQueueRepository {
+  constructor(private readonly db: PlatformDb) {}
+
+  /** Enqueue a notification for async delivery. Returns the new row ID. */
+  async enqueue(tenantId: string, template: string, data: Record<string, unknown>): Promise<string> {
+    const id = crypto.randomUUID();
+    const recipientEmail = (data.email as string | undefined) ?? "";
+    await this.db.insert(notificationQueue).values({
+      id,
+      tenantId,
+      emailType: template,
+      recipientEmail,
+      payload: JSON.stringify(data),
+      status: "pending",
+      attempts: 0,
+    });
+    return id;
+  }
+
+  /** Fetch up to `limit` notifications ready to send. */
+  async fetchPending(limit = 10): Promise<QueuedNotification[]> {
+    const now = Date.now();
+    const rows = await this.db
+      .select()
+      .from(notificationQueue)
+      .where(
+        and(
+          eq(notificationQueue.status, "pending"),
+          or(sql`${notificationQueue.retryAfter} IS NULL`, lte(notificationQueue.retryAfter, now)),
+        ),
+      )
+      .limit(limit);
+
+    return rows.map((r) => ({
+      id: r.id,
+      tenantId: r.tenantId,
+      template: r.emailType,
+      data: r.payload,
+      status: r.status as NotificationStatus,
+      attempts: r.attempts,
+      retryAfter: r.retryAfter ?? null,
+      sentAt: r.sentAt ?? null,
+      createdAt: r.createdAt,
+    }));
+  }
+
+  /** Mark a notification as sent. */
+  async markSent(id: string): Promise<void> {
+    await this.db
+      .update(notificationQueue)
+      .set({ status: "sent", sentAt: Date.now() })
+      .where(eq(notificationQueue.id, id));
+  }
+
+  /** Mark a notification as failed with exponential backoff retry. */
+  async markFailed(id: string, attempts: number): Promise<void> {
+    const maxAttempts = 5;
+    const isPermanentFail = attempts >= maxAttempts;
+    const backoffMs = Math.min(60_000 * 2 ** attempts, 3_600_000); // max 1 hour
+    await this.db
+      .update(notificationQueue)
+      .set({
+        status: isPermanentFail ? "failed" : "pending",
+        attempts,
+        retryAfter: isPermanentFail ? null : Date.now() + backoffMs,
+      })
+      .where(eq(notificationQueue.id, id));
+  }
+
+  /** List notifications for a tenant (for admin view). Paginated. */
+  async listForTenant(
+    tenantId: string,
+    opts: { limit?: number; offset?: number; status?: NotificationStatus } = {},
+  ): Promise<{ entries: QueuedNotification[]; total: number }> {
+    const conditions: ReturnType<typeof eq>[] = [eq(notificationQueue.tenantId, tenantId)];
+    if (opts.status) {
+      conditions.push(eq(notificationQueue.status, opts.status));
+    }
+
+    const whereClause = conditions.length === 1 ? conditions[0] : and(...conditions);
+
+    const totalRows = await this.db.select({ count: sql<number>`count(*)` }).from(notificationQueue).where(whereClause);
+    const total = totalRows[0]?.count ?? 0;
+
+    const rows = await this.db
+      .select()
+      .from(notificationQueue)
+      .where(whereClause)
+      .orderBy(desc(notificationQueue.createdAt))
+      .limit(opts.limit ?? 50)
+      .offset(opts.offset ?? 0);
+
+    const entries = rows.map((r) => ({
+      id: r.id,
+      tenantId: r.tenantId,
+      template: r.emailType,
+      data: r.payload,
+      status: r.status as NotificationStatus,
+      attempts: r.attempts,
+      retryAfter: r.retryAfter ?? null,
+      sentAt: r.sentAt ?? null,
+      createdAt: r.createdAt,
+    }));
+
+    return { entries, total };
+  }
+}

package/src/email/notification-repository-types.ts

@@ -0,0 +1,101 @@
+// src/email/notification-repository-types.ts
+//
+// Plain TypeScript interfaces for email/notification domain objects.
+// No Drizzle types. No better-sqlite3. These are the contracts
+// the notification layer works against.
+
+// ---------------------------------------------------------------------------
+// Notification Queue (email layer — src/email/notification-queue-store.ts)
+// ---------------------------------------------------------------------------
+
+export type NotificationStatus = "pending" | "sent" | "failed";
+
+/** Domain object for a queued notification in the email layer. */
+export interface QueuedNotification {
+  id: string;
+  tenantId: string;
+  template: string;
+  data: string; // JSON-serialized payload
+  status: NotificationStatus;
+  attempts: number;
+  retryAfter: number | null;
+  sentAt: number | null;
+  createdAt: number;
+}
+
+// ---------------------------------------------------------------------------
+// Notification Preferences
+// ---------------------------------------------------------------------------
+
+/** Per-tenant notification preference flags. */
+export interface NotificationPrefs {
+  billing_low_balance: boolean;
+  billing_receipts: boolean;
+  billing_auto_topup: boolean;
+  agent_channel_disconnect: boolean;
+  agent_status_changes: boolean;
+  account_role_changes: boolean;
+  account_team_invites: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Admin Notification Queue (src/admin/notifications/store.ts)
+// ---------------------------------------------------------------------------
+
+export type NotificationEmailType =
+  | "low_balance"
+  | "grace_entered"
+  | "suspended"
+  | "receipt"
+  | "welcome"
+  | "reactivated";
+
+export interface NotificationInput {
+  tenantId: string;
+  emailType: NotificationEmailType;
+  recipientEmail: string;
+  payload?: Record<string, unknown>;
+  maxAttempts?: number;
+}
+
+export interface NotificationRow {
+  id: string;
+  tenantId: string;
+  emailType: string;
+  recipientEmail: string;
+  payload: string;
+  status: string;
+  attempts: number;
+  maxAttempts: number;
+  /** Unix epoch ms of last attempt */
+  lastAttemptAt: number | null;
+  lastError: string | null;
+  /** Unix epoch ms for next retry. Null = immediately eligible. */
+  retryAfter: number | null;
+  /** Unix epoch ms */
+  createdAt: number;
+  /** Unix epoch ms */
+  sentAt: number | null;
+}
+
+// ---------------------------------------------------------------------------
+// Repository Interfaces
+// ---------------------------------------------------------------------------
+
+/** Repository interface for notification preferences. */
+export interface INotificationPreferencesRepository {
+  get(tenantId: string): Promise<NotificationPrefs>;
+  update(tenantId: string, prefs: Partial<NotificationPrefs>): Promise<void>;
+}
+
+/** Repository interface for the email notification queue. */
+export interface INotificationQueueRepository {
+  enqueue(tenantId: string, template: string, data: Record<string, unknown>): Promise<string>;
+  fetchPending(limit?: number): Promise<QueuedNotification[]>;
+  markSent(id: string): Promise<void>;
+  markFailed(id: string, attempts: number): Promise<void>;
+  listForTenant(
+    tenantId: string,
+    opts?: { limit?: number; offset?: number; status?: NotificationStatus },
+  ): Promise<{ entries: QueuedNotification[]; total: number }>;
+}

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

@@ -0,0 +1,178 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { INotificationQueueRepository } from "./notification-repository-types.js";
+import { NotificationService } from "./notification-service.js";
+
+function makeQueueStore(): INotificationQueueRepository {
+  return {
+    enqueue: vi.fn().mockReturnValue("notif-id-123"),
+    fetchPending: vi.fn().mockReturnValue([]),
+    markSent: vi.fn(),
+    markFailed: vi.fn(),
+    listForTenant: vi.fn().mockReturnValue({ entries: [], total: 0 }),
+  } as unknown as INotificationQueueRepository;
+}
+
+describe("NotificationService", () => {
+  let queue: INotificationQueueRepository;
+  let service: NotificationService;
+  const BASE_URL = "https://app.wopr.bot";
+
+  beforeEach(() => {
+    queue = makeQueueStore();
+    service = new NotificationService(queue, BASE_URL);
+  });
+
+  describe("notifyLowBalance", () => {
+    it("enqueues a low-balance notification with correct data", () => {
+      service.notifyLowBalance("tenant-1", "user@example.com", "$2.50", 5);
+      expect(queue.enqueue).toHaveBeenCalledWith("tenant-1", "low-balance", {
+        email: "user@example.com",
+        balanceDollars: "$2.50",
+        estimatedDaysRemaining: 5,
+        creditsUrl: `${BASE_URL}/billing/credits`,
+      });
+    });
+  });
+
+  describe("notifyCreditsDepeleted", () => {
+    it("enqueues a credits-depleted notification", () => {
+      service.notifyCreditsDepeleted("tenant-1", "user@example.com");
+      expect(queue.enqueue).toHaveBeenCalledWith("tenant-1", "credits-depleted", {
+        email: "user@example.com",
+        creditsUrl: `${BASE_URL}/billing/credits`,
+      });
+    });
+  });
+
+  describe("notifyGracePeriodStart", () => {
+    it("enqueues a grace-period-start notification", () => {
+      service.notifyGracePeriodStart("tenant-1", "user@example.com", "$0.50", 7);
+      expect(queue.enqueue).toHaveBeenCalledWith("tenant-1", "grace-period-start", {
+        email: "user@example.com",
+        balanceDollars: "$0.50",
+        graceDays: 7,
+        creditsUrl: `${BASE_URL}/billing/credits`,
+      });
+    });
+  });
+
+  describe("notifyGracePeriodWarning", () => {
+    it("enqueues a grace-period-warning notification", () => {
+      service.notifyGracePeriodWarning("tenant-1", "user@example.com");
+      expect(queue.enqueue).toHaveBeenCalledWith("tenant-1", "grace-period-warning", {
+        email: "user@example.com",
+        creditsUrl: `${BASE_URL}/billing/credits`,
+      });
+    });
+  });
+
+  describe("notifyAutoSuspended", () => {
+    it("enqueues an auto-suspended notification", () => {
+      service.notifyAutoSuspended("tenant-1", "user@example.com", "Grace period expired");
+      expect(queue.enqueue).toHaveBeenCalledWith("tenant-1", "auto-suspended", {
+        email: "user@example.com",
+        reason: "Grace period expired",
+        creditsUrl: `${BASE_URL}/billing/credits`,
+      });
+    });
+  });
+
+  describe("notifyAdminSuspended", () => {
+    it("enqueues an admin-suspended notification", () => {
+      service.notifyAdminSuspended("tenant-1", "user@example.com", "ToS violation");
+      expect(queue.enqueue).toHaveBeenCalledWith("tenant-1", "admin-suspended", {
+        email: "user@example.com",
+        reason: "ToS violation",
+      });
+    });
+  });
+
+  describe("notifyAdminReactivated", () => {
+    it("enqueues an admin-reactivated notification", () => {
+      service.notifyAdminReactivated("tenant-1", "user@example.com");
+      expect(queue.enqueue).toHaveBeenCalledWith("tenant-1", "admin-reactivated", {
+        email: "user@example.com",
+      });
+    });
+  });
+
+  describe("notifyCreditsGranted", () => {
+    it("enqueues a credits-granted notification", () => {
+      service.notifyCreditsGranted("tenant-1", "user@example.com", "$5.00", "Support credit");
+      expect(queue.enqueue).toHaveBeenCalledWith("tenant-1", "credits-granted", {
+        email: "user@example.com",
+        amountDollars: "$5.00",
+        reason: "Support credit",
+      });
+    });
+  });
+
+  describe("notifyRoleChanged", () => {
+    it("enqueues a role-changed notification", () => {
+      service.notifyRoleChanged("tenant-1", "user@example.com", "tenant_admin");
+      expect(queue.enqueue).toHaveBeenCalledWith("tenant-1", "role-changed", {
+        email: "user@example.com",
+        newRole: "tenant_admin",
+      });
+    });
+  });
+
+  describe("notifyTeamInvite", () => {
+    it("enqueues a team-invite notification", () => {
+      service.notifyTeamInvite("tenant-1", "user@example.com", "Acme Corp", "https://app.wopr.bot/invite/abc");
+      expect(queue.enqueue).toHaveBeenCalledWith("tenant-1", "team-invite", {
+        email: "user@example.com",
+        tenantName: "Acme Corp",
+        inviteUrl: "https://app.wopr.bot/invite/abc",
+      });
+    });
+  });
+
+  describe("notifyChannelDisconnected", () => {
+    it("enqueues a channel-disconnected notification", () => {
+      service.notifyChannelDisconnected("tenant-1", "user@example.com", "Discord", "MyBot", "Token expired");
+      expect(queue.enqueue).toHaveBeenCalledWith("tenant-1", "channel-disconnected", {
+        email: "user@example.com",
+        channelName: "Discord",
+        agentName: "MyBot",
+        reason: "Token expired",
+      });
+    });
+  });
+
+  describe("sendCustomEmail", () => {
+    it("enqueues a custom template notification", () => {
+      service.sendCustomEmail("tenant-1", "user@example.com", "Hello there", "This is the body.");
+      expect(queue.enqueue).toHaveBeenCalledWith("tenant-1", "custom", {
+        email: "user@example.com",
+        subject: "Hello there",
+        bodyText: "This is the body.",
+      });
+    });
+  });
+
+  describe("notifyDisputeCreated", () => {
+    it("enqueues dispute-created notification", () => {
+      service.notifyDisputeCreated("t1", "admin@test.com", "dp_123", "$50.00", "fraudulent");
+      expect(queue.enqueue).toHaveBeenCalledWith("t1", "dispute-created", {
+        email: "admin@test.com",
+        disputeId: "dp_123",
+        amountDollars: "$50.00",
+        reason: "fraudulent",
+        creditsUrl: `${BASE_URL}/billing/credits`,
+      });
+    });
+  });
+
+  describe("notifyDisputeWon", () => {
+    it("enqueues dispute-won notification", () => {
+      service.notifyDisputeWon("t1", "admin@test.com", "dp_123", "$50.00");
+      expect(queue.enqueue).toHaveBeenCalledWith("t1", "dispute-won", {
+        email: "admin@test.com",
+        disputeId: "dp_123",
+        amountDollars: "$50.00",
+        creditsUrl: `${BASE_URL}/billing/credits`,
+      });
+    });
+  });
+});