@wopr-network/platform-core 0.1.0

package/dist/email/notification-repository-types.d.ts

@@ -0,0 +1,70 @@
+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;
+    status: NotificationStatus;
+    attempts: number;
+    retryAfter: number | null;
+    sentAt: number | null;
+    createdAt: number;
+}
+/** 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;
+}
+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 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/dist/email/notification-repository-types.js

@@ -0,0 +1,6 @@
+// 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.
+export {};

package/dist/email/notification-service.d.ts

@@ -0,0 +1,41 @@
+/**
+ * NotificationService — facade for enqueueing all system notifications.
+ *
+ * All callers go through this service rather than the queue store directly.
+ * Resolves URLs and template data shapes so callers only need domain concepts.
+ */
+import type { INotificationQueueRepository } from "./notification-repository-types.js";
+export declare class NotificationService {
+    private readonly queue;
+    private readonly appBaseUrl;
+    constructor(queue: INotificationQueueRepository, appBaseUrl: string);
+    private creditsUrl;
+    notifyLowBalance(tenantId: string, email: string, balanceDollars: string, estimatedDays: number): void;
+    notifyCreditsDepeleted(tenantId: string, email: string): void;
+    notifyGracePeriodStart(tenantId: string, email: string, balanceDollars: string, graceDays: number): void;
+    notifyGracePeriodWarning(tenantId: string, email: string): void;
+    notifyAutoSuspended(tenantId: string, email: string, reason: string): void;
+    notifyAutoTopUpSuccess(tenantId: string, email: string, amountDollars: string, newBalanceDollars: string): void;
+    notifyAutoTopUpFailed(tenantId: string, email: string): void;
+    notifyAffiliateCreditMatch(tenantId: string, email: string, amountDollars: string): void;
+    notifyDisputeCreated(tenantId: string, email: string, disputeId: string, amountDollars: string, reason: string): void;
+    notifyDisputeWon(tenantId: string, email: string, disputeId: string, amountDollars: string): void;
+    notifyDisputeLost(tenantId: string, email: string, disputeId: string, amountDollars: string): void;
+    notifySpendThresholdAlert(tenantId: string, email: string, currentSpendDollars: string, alertAtDollars: string): void;
+    notifyCreditPurchaseReceipt(tenantId: string, email: string, amountDollars: string, newBalanceDollars: string): void;
+    notifyDividendWeeklyDigest(tenantId: string, email: string, weeklyTotalDollars: string, weeklyTotalCents: number, lifetimeTotalDollars: string, distributionCount: number, poolAvgCents: number, activeUsersAvg: number, nextDividendDate: string, weekStartDate: string, weekEndDate: string): void;
+    notifyCryptoPaymentConfirmed(tenantId: string, email: string, amountDollars: string, newBalanceDollars: string): void;
+    notifyAdminSuspended(tenantId: string, email: string, reason: string): void;
+    notifyAdminReactivated(tenantId: string, email: string): void;
+    notifyCreditsGranted(tenantId: string, email: string, amountDollars: string, reason: string): void;
+    notifyRoleChanged(tenantId: string, email: string, newRole: string): void;
+    notifyTeamInvite(tenantId: string, email: string, tenantName: string, inviteUrl: string): void;
+    notifyAgentCreated(tenantId: string, email: string, agentName: string): void;
+    notifyChannelConnected(tenantId: string, email: string, channelName: string, agentName: string): void;
+    notifyChannelDisconnected(tenantId: string, email: string, channelName: string, agentName: string, reason: string): void;
+    notifyAgentSuspended(tenantId: string, email: string, agentName: string, reason: string): void;
+    notifyAccountDeletionRequested(tenantId: string, email: string, deleteAfterDate: string): void;
+    notifyAccountDeletionCancelled(tenantId: string, email: string): void;
+    notifyAccountDeletionCompleted(tenantId: string, email: string): void;
+    sendCustomEmail(tenantId: string, email: string, subject: string, bodyText: string): void;
+}

package/dist/email/notification-service.js

@@ -0,0 +1,196 @@
+/**
+ * NotificationService — facade for enqueueing all system notifications.
+ *
+ * All callers go through this service rather than the queue store directly.
+ * Resolves URLs and template data shapes so callers only need domain concepts.
+ */
+export class NotificationService {
+    queue;
+    appBaseUrl;
+    constructor(queue, appBaseUrl) {
+        this.queue = queue;
+        this.appBaseUrl = appBaseUrl;
+    }
+    creditsUrl() {
+        return `${this.appBaseUrl}/billing/credits`;
+    }
+    // ---------------------------------------------------------------------------
+    // Credit & Billing
+    // ---------------------------------------------------------------------------
+    notifyLowBalance(tenantId, email, balanceDollars, estimatedDays) {
+        this.queue.enqueue(tenantId, "low-balance", {
+            email,
+            balanceDollars,
+            estimatedDaysRemaining: estimatedDays,
+            creditsUrl: this.creditsUrl(),
+        });
+    }
+    notifyCreditsDepeleted(tenantId, email) {
+        this.queue.enqueue(tenantId, "credits-depleted", {
+            email,
+            creditsUrl: this.creditsUrl(),
+        });
+    }
+    notifyGracePeriodStart(tenantId, email, balanceDollars, graceDays) {
+        this.queue.enqueue(tenantId, "grace-period-start", {
+            email,
+            balanceDollars,
+            graceDays,
+            creditsUrl: this.creditsUrl(),
+        });
+    }
+    notifyGracePeriodWarning(tenantId, email) {
+        this.queue.enqueue(tenantId, "grace-period-warning", {
+            email,
+            creditsUrl: this.creditsUrl(),
+        });
+    }
+    notifyAutoSuspended(tenantId, email, reason) {
+        this.queue.enqueue(tenantId, "auto-suspended", {
+            email,
+            reason,
+            creditsUrl: this.creditsUrl(),
+        });
+    }
+    notifyAutoTopUpSuccess(tenantId, email, amountDollars, newBalanceDollars) {
+        this.queue.enqueue(tenantId, "auto-topup-success", {
+            email,
+            amountDollars,
+            newBalanceDollars,
+            creditsUrl: this.creditsUrl(),
+        });
+    }
+    notifyAutoTopUpFailed(tenantId, email) {
+        this.queue.enqueue(tenantId, "auto-topup-failed", {
+            email,
+            creditsUrl: this.creditsUrl(),
+        });
+    }
+    notifyAffiliateCreditMatch(tenantId, email, amountDollars) {
+        this.queue.enqueue(tenantId, "affiliate-credit-match", {
+            email,
+            amountDollars,
+            creditsUrl: this.creditsUrl(),
+        });
+    }
+    notifyDisputeCreated(tenantId, email, disputeId, amountDollars, reason) {
+        this.queue.enqueue(tenantId, "dispute-created", {
+            email,
+            disputeId,
+            amountDollars,
+            reason,
+            creditsUrl: this.creditsUrl(),
+        });
+    }
+    notifyDisputeWon(tenantId, email, disputeId, amountDollars) {
+        this.queue.enqueue(tenantId, "dispute-won", {
+            email,
+            disputeId,
+            amountDollars,
+            creditsUrl: this.creditsUrl(),
+        });
+    }
+    notifyDisputeLost(tenantId, email, disputeId, amountDollars) {
+        this.queue.enqueue(tenantId, "dispute-lost", {
+            email,
+            disputeId,
+            amountDollars,
+            creditsUrl: this.creditsUrl(),
+        });
+    }
+    notifySpendThresholdAlert(tenantId, email, currentSpendDollars, alertAtDollars) {
+        this.queue.enqueue(tenantId, "spend-alert", {
+            email,
+            currentSpendDollars,
+            alertAtDollars,
+            creditsUrl: this.creditsUrl(),
+        });
+    }
+    notifyCreditPurchaseReceipt(tenantId, email, amountDollars, newBalanceDollars) {
+        this.queue.enqueue(tenantId, "credit-purchase-receipt", {
+            email,
+            amountDollars,
+            newBalanceDollars,
+            creditsUrl: this.creditsUrl(),
+        });
+    }
+    notifyDividendWeeklyDigest(tenantId, email, weeklyTotalDollars, weeklyTotalCents, lifetimeTotalDollars, distributionCount, poolAvgCents, activeUsersAvg, nextDividendDate, weekStartDate, weekEndDate) {
+        const unsubscribeUrl = `${this.appBaseUrl}/settings/notifications`;
+        this.queue.enqueue(tenantId, "dividend-weekly-digest", {
+            email,
+            weeklyTotalDollars,
+            weeklyTotalCents,
+            lifetimeTotalDollars,
+            distributionCount,
+            poolAvgCents,
+            activeUsersAvg,
+            nextDividendDate,
+            weekStartDate,
+            weekEndDate,
+            unsubscribeUrl,
+            creditsUrl: this.creditsUrl(),
+        });
+    }
+    notifyCryptoPaymentConfirmed(tenantId, email, amountDollars, newBalanceDollars) {
+        this.queue.enqueue(tenantId, "crypto-payment-confirmed", {
+            email,
+            amountDollars,
+            newBalanceDollars,
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Account
+    // ---------------------------------------------------------------------------
+    notifyAdminSuspended(tenantId, email, reason) {
+        this.queue.enqueue(tenantId, "admin-suspended", { email, reason });
+    }
+    notifyAdminReactivated(tenantId, email) {
+        this.queue.enqueue(tenantId, "admin-reactivated", { email });
+    }
+    notifyCreditsGranted(tenantId, email, amountDollars, reason) {
+        this.queue.enqueue(tenantId, "credits-granted", { email, amountDollars, reason });
+    }
+    notifyRoleChanged(tenantId, email, newRole) {
+        this.queue.enqueue(tenantId, "role-changed", { email, newRole });
+    }
+    notifyTeamInvite(tenantId, email, tenantName, inviteUrl) {
+        this.queue.enqueue(tenantId, "team-invite", { email, tenantName, inviteUrl });
+    }
+    // ---------------------------------------------------------------------------
+    // Agent & Channel
+    // ---------------------------------------------------------------------------
+    notifyAgentCreated(tenantId, email, agentName) {
+        this.queue.enqueue(tenantId, "agent-created", { email, agentName });
+    }
+    notifyChannelConnected(tenantId, email, channelName, agentName) {
+        this.queue.enqueue(tenantId, "channel-connected", { email, channelName, agentName });
+    }
+    notifyChannelDisconnected(tenantId, email, channelName, agentName, reason) {
+        this.queue.enqueue(tenantId, "channel-disconnected", { email, channelName, agentName, reason });
+    }
+    notifyAgentSuspended(tenantId, email, agentName, reason) {
+        this.queue.enqueue(tenantId, "agent-suspended", { email, agentName, reason });
+    }
+    // ---------------------------------------------------------------------------
+    // Account Deletion
+    // ---------------------------------------------------------------------------
+    notifyAccountDeletionRequested(tenantId, email, deleteAfterDate) {
+        this.queue.enqueue(tenantId, "account-deletion-requested", {
+            email,
+            deleteAfterDate,
+            cancelUrl: `${this.appBaseUrl}/settings/account`,
+        });
+    }
+    notifyAccountDeletionCancelled(tenantId, email) {
+        this.queue.enqueue(tenantId, "account-deletion-cancelled", { email });
+    }
+    notifyAccountDeletionCompleted(tenantId, email) {
+        this.queue.enqueue(tenantId, "account-deletion-completed", { email });
+    }
+    // ---------------------------------------------------------------------------
+    // Admin custom email
+    // ---------------------------------------------------------------------------
+    sendCustomEmail(tenantId, email, subject, bodyText) {
+        this.queue.enqueue(tenantId, "custom", { email, subject, bodyText });
+    }
+}

package/dist/email/notification-service.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/email/notification-service.test.js

@@ -0,0 +1,160 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { NotificationService } from "./notification-service.js";
+function makeQueueStore() {
+    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 }),
+    };
+}
+describe("NotificationService", () => {
+    let queue;
+    let service;
+    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`,
+            });
+        });
+    });
+});

package/dist/email/notification-templates.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Notification Templates — renders all system notification emails.
+ *
+ * Separate from templates.ts (which handles billing/auth emails) to keep
+ * each file focused. Imports shared layout helpers from templates.ts.
+ *
+ * Export: renderNotificationTemplate(template, data) → TemplateResult
+ */
+import type { TemplateResult } from "./templates.js";
+export type NotificationTemplateName = "credits-depleted" | "grace-period-start" | "grace-period-warning" | "auto-suspended" | "auto-topup-success" | "auto-topup-failed" | "crypto-payment-confirmed" | "admin-suspended" | "admin-reactivated" | "credits-granted" | "role-changed" | "team-invite" | "agent-created" | "channel-connected" | "channel-disconnected" | "agent-suspended" | "custom" | "account-deletion-requested" | "account-deletion-cancelled" | "account-deletion-completed" | "dividend-weekly-digest" | "affiliate-credit-match" | "spend-alert" | "low-balance" | "credit-purchase-receipt" | "welcome" | "password-reset";
+export type TemplateName = NotificationTemplateName;
+/**
+ * Render a notification template by name.
+ *
+ * All new templates are dispatched here. Legacy templates (verify-email,
+ * welcome, password-reset, etc.) are handled by templates.ts directly.
+ */
+export declare function renderNotificationTemplate(template: TemplateName, data: Record<string, unknown>): TemplateResult;