@wopr-network/platform-core 1.14.7 → 1.15.0

package/dist/billing/crypto/client.test.js

@@ -0,0 +1,100 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { BTCPayClient, loadCryptoConfig } from "./client.js";
+describe("BTCPayClient", () => {
+    it("createInvoice sends correct request and returns id + checkoutLink", async () => {
+        const mockResponse = { id: "inv-001", checkoutLink: "https://btcpay.example.com/i/inv-001" };
+        const fetchSpy = vi
+            .spyOn(globalThis, "fetch")
+            .mockResolvedValue(new Response(JSON.stringify(mockResponse), { status: 200 }));
+        const client = new BTCPayClient({
+            apiKey: "test-key",
+            baseUrl: "https://btcpay.example.com",
+            storeId: "store-abc",
+        });
+        const result = await client.createInvoice({
+            amountUsd: 25,
+            orderId: "order-123",
+            buyerEmail: "test@example.com",
+        });
+        expect(result.id).toBe("inv-001");
+        expect(result.checkoutLink).toBe("https://btcpay.example.com/i/inv-001");
+        expect(fetchSpy).toHaveBeenCalledOnce();
+        const [url, opts] = fetchSpy.mock.calls[0];
+        expect(url).toBe("https://btcpay.example.com/api/v1/stores/store-abc/invoices");
+        expect(opts?.method).toBe("POST");
+        const headers = opts?.headers;
+        expect(headers.Authorization).toBe("token test-key");
+        expect(headers["Content-Type"]).toBe("application/json");
+        const body = JSON.parse(opts?.body);
+        expect(body.amount).toBe("25");
+        expect(body.currency).toBe("USD");
+        expect(body.metadata.orderId).toBe("order-123");
+        expect(body.metadata.buyerEmail).toBe("test@example.com");
+        expect(body.checkout.speedPolicy).toBe("MediumSpeed");
+        fetchSpy.mockRestore();
+    });
+    it("createInvoice includes redirectURL when provided", async () => {
+        const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response(JSON.stringify({ id: "inv-002", checkoutLink: "https://btcpay.example.com/i/inv-002" }), {
+            status: 200,
+        }));
+        const client = new BTCPayClient({ apiKey: "k", baseUrl: "https://btcpay.example.com", storeId: "s" });
+        await client.createInvoice({ amountUsd: 10, orderId: "o", redirectURL: "https://app.example.com/success" });
+        const body = JSON.parse(fetchSpy.mock.calls[0][1]?.body);
+        expect(body.checkout.redirectURL).toBe("https://app.example.com/success");
+        fetchSpy.mockRestore();
+    });
+    it("createInvoice throws on non-ok response", async () => {
+        const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response("Unauthorized", { status: 401 }));
+        const client = new BTCPayClient({ apiKey: "bad-key", baseUrl: "https://btcpay.example.com", storeId: "s" });
+        await expect(client.createInvoice({ amountUsd: 10, orderId: "o" })).rejects.toThrow("BTCPay createInvoice failed (401)");
+        fetchSpy.mockRestore();
+    });
+    it("getInvoice sends correct request", async () => {
+        const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response(JSON.stringify({ id: "inv-001", status: "Settled", amount: "25", currency: "USD" }), {
+            status: 200,
+        }));
+        const client = new BTCPayClient({ apiKey: "k", baseUrl: "https://btcpay.example.com", storeId: "store-abc" });
+        const result = await client.getInvoice("inv-001");
+        expect(result.status).toBe("Settled");
+        expect(fetchSpy.mock.calls[0][0]).toBe("https://btcpay.example.com/api/v1/stores/store-abc/invoices/inv-001");
+        fetchSpy.mockRestore();
+    });
+});
+describe("loadCryptoConfig", () => {
+    beforeEach(() => {
+        delete process.env.BTCPAY_API_KEY;
+        delete process.env.BTCPAY_BASE_URL;
+        delete process.env.BTCPAY_STORE_ID;
+    });
+    afterEach(() => {
+        vi.unstubAllEnvs();
+    });
+    it("returns null when BTCPAY_API_KEY is missing", () => {
+        vi.stubEnv("BTCPAY_BASE_URL", "https://btcpay.test");
+        vi.stubEnv("BTCPAY_STORE_ID", "store-1");
+        expect(loadCryptoConfig()).toBeNull();
+    });
+    it("returns null when BTCPAY_BASE_URL is missing", () => {
+        vi.stubEnv("BTCPAY_API_KEY", "test-key");
+        vi.stubEnv("BTCPAY_STORE_ID", "store-1");
+        expect(loadCryptoConfig()).toBeNull();
+    });
+    it("returns null when BTCPAY_STORE_ID is missing", () => {
+        vi.stubEnv("BTCPAY_API_KEY", "test-key");
+        vi.stubEnv("BTCPAY_BASE_URL", "https://btcpay.test");
+        expect(loadCryptoConfig()).toBeNull();
+    });
+    it("returns config when all env vars are set", () => {
+        vi.stubEnv("BTCPAY_API_KEY", "test-key");
+        vi.stubEnv("BTCPAY_BASE_URL", "https://btcpay.test");
+        vi.stubEnv("BTCPAY_STORE_ID", "store-1");
+        expect(loadCryptoConfig()).toEqual({
+            apiKey: "test-key",
+            baseUrl: "https://btcpay.test",
+            storeId: "store-1",
+        });
+    });
+    it("returns null when all env vars are missing", () => {
+        expect(loadCryptoConfig()).toBeNull();
+    });
+});

package/dist/billing/crypto/index.d.ts

@@ -0,0 +1,9 @@
+export type { CryptoChargeRecord, ICryptoChargeRepository } from "./charge-store.js";
+export { CryptoChargeRepository, DrizzleCryptoChargeRepository } from "./charge-store.js";
+export { createCryptoCheckout, MIN_PAYMENT_USD } from "./checkout.js";
+export type { CryptoConfig } from "./client.js";
+export { BTCPayClient, loadCryptoConfig } from "./client.js";
+export type { CryptoBillingConfig, CryptoCheckoutOpts, CryptoPaymentState, CryptoWebhookPayload, CryptoWebhookResult, } from "./types.js";
+export { mapBtcPayEventToStatus } from "./types.js";
+export type { CryptoWebhookDeps } from "./webhook.js";
+export { handleCryptoWebhook, verifyCryptoWebhookSignature } from "./webhook.js";

package/dist/billing/crypto/index.js

@@ -0,0 +1,5 @@
+export { CryptoChargeRepository, DrizzleCryptoChargeRepository } from "./charge-store.js";
+export { createCryptoCheckout, MIN_PAYMENT_USD } from "./checkout.js";
+export { BTCPayClient, loadCryptoConfig } from "./client.js";
+export { mapBtcPayEventToStatus } from "./types.js";
+export { handleCryptoWebhook, verifyCryptoWebhookSignature } from "./webhook.js";

package/dist/billing/crypto/types.d.ts

@@ -0,0 +1,61 @@
+/** BTCPay Server invoice states (Greenfield API v1). */
+export type CryptoPaymentState = "New" | "Processing" | "Expired" | "Invalid" | "Settled";
+/** Options for creating a crypto payment session. */
+export interface CryptoCheckoutOpts {
+    /** Internal tenant ID. */
+    tenant: string;
+    /** Amount in USD (minimum $10). */
+    amountUsd: number;
+}
+/** Webhook payload received from BTCPay Server (InvoiceSettled event). */
+export interface CryptoWebhookPayload {
+    /** BTCPay delivery ID (for deduplication). */
+    deliveryId: string;
+    /** Webhook ID. */
+    webhookId: string;
+    /** Original delivery ID (same as deliveryId on first delivery). */
+    originalDeliveryId: string;
+    /** Whether this is a redelivery. */
+    isRedelivery: boolean;
+    /** Event type (e.g. "InvoiceSettled", "InvoiceProcessing", "InvoiceExpired"). */
+    type: string;
+    /** Unix timestamp. */
+    timestamp: number;
+    /** BTCPay store ID. */
+    storeId: string;
+    /** BTCPay invoice ID. */
+    invoiceId: string;
+    /** Invoice metadata (echoed from creation). */
+    metadata: Record<string, unknown>;
+    /** Whether admin manually marked as settled (InvoiceSettled only). */
+    manuallyMarked?: boolean;
+    /** Whether customer overpaid (InvoiceSettled only). */
+    overPaid?: boolean;
+    /** Whether invoice was partially paid (InvoiceExpired only). */
+    partiallyPaid?: boolean;
+}
+/** Configuration for BTCPay Server integration. */
+export interface CryptoBillingConfig {
+    /** BTCPay API key (from Account > API keys). */
+    apiKey: string;
+    /** BTCPay Server base URL. */
+    baseUrl: string;
+    /** BTCPay store ID. */
+    storeId: string;
+}
+/** Result of processing a crypto webhook event. */
+export interface CryptoWebhookResult {
+    handled: boolean;
+    status: string;
+    tenant?: string;
+    creditedCents?: number;
+    reactivatedBots?: string[];
+    duplicate?: boolean;
+}
+/**
+ * Map BTCPay webhook event type string to a CryptoPaymentState.
+ *
+ * Shared between the core (billing) and consumer (monetization) webhook handlers.
+ * Throws on unrecognized event types to surface integration errors early.
+ */
+export declare function mapBtcPayEventToStatus(eventType: string): CryptoPaymentState;

package/dist/billing/crypto/types.js

@@ -0,0 +1,24 @@
+/**
+ * Map BTCPay webhook event type string to a CryptoPaymentState.
+ *
+ * Shared between the core (billing) and consumer (monetization) webhook handlers.
+ * Throws on unrecognized event types to surface integration errors early.
+ */
+export function mapBtcPayEventToStatus(eventType) {
+    switch (eventType) {
+        case "InvoiceCreated":
+            return "New";
+        case "InvoiceReceivedPayment":
+        case "InvoiceProcessing":
+            return "Processing";
+        case "InvoiceSettled":
+        case "InvoicePaymentSettled":
+            return "Settled";
+        case "InvoiceExpired":
+            return "Expired";
+        case "InvoiceInvalid":
+            return "Invalid";
+        default:
+            throw new Error(`Unknown BTCPay event type: ${eventType}`);
+    }
+}

package/dist/billing/crypto/webhook.d.ts

@@ -0,0 +1,34 @@
+import type { ILedger } from "../../credits/ledger.js";
+import type { IWebhookSeenRepository } from "../webhook-seen-repository.js";
+import type { ICryptoChargeRepository } from "./charge-store.js";
+import type { CryptoWebhookPayload, CryptoWebhookResult } from "./types.js";
+export interface CryptoWebhookDeps {
+    chargeStore: ICryptoChargeRepository;
+    creditLedger: ILedger;
+    replayGuard: IWebhookSeenRepository;
+    /** Called after credits are purchased — consumer can reactivate suspended resources. Returns reactivated resource IDs. */
+    onCreditsPurchased?: (tenantId: string, ledger: ILedger) => Promise<string[]>;
+}
+/**
+ * Verify BTCPay webhook signature (HMAC-SHA256).
+ *
+ * BTCPay sends the signature in the BTCPAY-SIG header as "sha256=<hex>".
+ */
+export declare function verifyCryptoWebhookSignature(rawBody: Buffer | string, sigHeader: string | undefined, secret: string): boolean;
+/**
+ * Process a BTCPay Server webhook event.
+ *
+ * Only credits the ledger on InvoiceSettled status.
+ * Uses the BTCPay invoice ID mapped to the stored charge record
+ * for tenant resolution and idempotency.
+ *
+ * Idempotency strategy (matches Stripe webhook pattern):
+ *   Primary: `creditLedger.hasReferenceId("crypto:<invoiceId>")` — atomic,
+ *   checked inside the ledger's serialized transaction.
+ *   Secondary: `chargeStore.markCredited()` — advisory flag for queries.
+ *
+ * CRITICAL: The charge store holds amountUsdCents (USD cents, integer).
+ * Credit.fromCents() converts cents → nanodollars for the ledger.
+ * Never pass raw cents to the ledger — always go through Credit.fromCents().
+ */
+export declare function handleCryptoWebhook(deps: CryptoWebhookDeps, payload: CryptoWebhookPayload): Promise<CryptoWebhookResult>;

package/dist/billing/crypto/webhook.js

@@ -0,0 +1,107 @@
+import crypto from "node:crypto";
+import { Credit } from "../../credits/credit.js";
+import { mapBtcPayEventToStatus } from "./types.js";
+/**
+ * Verify BTCPay webhook signature (HMAC-SHA256).
+ *
+ * BTCPay sends the signature in the BTCPAY-SIG header as "sha256=<hex>".
+ */
+export function verifyCryptoWebhookSignature(rawBody, sigHeader, secret) {
+    if (!sigHeader)
+        return false;
+    const expectedSig = `sha256=${crypto.createHmac("sha256", secret).update(rawBody).digest("hex")}`;
+    const expected = Buffer.from(expectedSig, "utf8");
+    const received = Buffer.from(sigHeader, "utf8");
+    if (expected.length !== received.length)
+        return false;
+    return crypto.timingSafeEqual(expected, received);
+}
+/**
+ * Process a BTCPay Server webhook event.
+ *
+ * Only credits the ledger on InvoiceSettled status.
+ * Uses the BTCPay invoice ID mapped to the stored charge record
+ * for tenant resolution and idempotency.
+ *
+ * Idempotency strategy (matches Stripe webhook pattern):
+ *   Primary: `creditLedger.hasReferenceId("crypto:<invoiceId>")` — atomic,
+ *   checked inside the ledger's serialized transaction.
+ *   Secondary: `chargeStore.markCredited()` — advisory flag for queries.
+ *
+ * CRITICAL: The charge store holds amountUsdCents (USD cents, integer).
+ * Credit.fromCents() converts cents → nanodollars for the ledger.
+ * Never pass raw cents to the ledger — always go through Credit.fromCents().
+ */
+export async function handleCryptoWebhook(deps, payload) {
+    const { chargeStore, creditLedger } = deps;
+    // Replay guard FIRST: deduplicate by invoiceId + event type.
+    // Must run before mapBtcPayEventToStatus() — unknown event types throw,
+    // and BTCPay retries webhooks on failure. Without this ordering, an unknown
+    // event type causes an infinite retry loop.
+    const dedupeKey = `${payload.invoiceId}:${payload.type}`;
+    if (await deps.replayGuard.isDuplicate(dedupeKey, "crypto")) {
+        return { handled: true, status: "New", duplicate: true };
+    }
+    // Map BTCPay event type to a CryptoPaymentState (throws on unknown types).
+    const status = mapBtcPayEventToStatus(payload.type);
+    // Look up the charge record to find the tenant.
+    const charge = await chargeStore.getByReferenceId(payload.invoiceId);
+    if (!charge) {
+        return { handled: false, status };
+    }
+    // Update charge status regardless of event type.
+    await chargeStore.updateStatus(payload.invoiceId, status);
+    let result;
+    if (payload.type === "InvoiceSettled") {
+        // Idempotency: use ledger referenceId check (same pattern as Stripe webhook).
+        // This is atomic — the referenceId is checked inside the ledger's serialized
+        // transaction, eliminating the TOCTOU race of isCredited() + creditLedger().
+        const creditRef = `crypto:${payload.invoiceId}`;
+        if (await creditLedger.hasReferenceId(creditRef)) {
+            result = {
+                handled: true,
+                status,
+                tenant: charge.tenantId,
+                creditedCents: 0,
+            };
+        }
+        else {
+            // Credit the original USD amount requested (not the crypto amount).
+            // For overpayments, we still credit the requested amount.
+            // charge.amountUsdCents is in USD cents (integer).
+            // Credit.fromCents() converts to nanodollars for the ledger.
+            const creditCents = charge.amountUsdCents;
+            await creditLedger.credit(charge.tenantId, Credit.fromCents(creditCents), "purchase", {
+                description: `Crypto credit purchase via BTCPay (invoice: ${payload.invoiceId})`,
+                referenceId: creditRef,
+                fundingSource: "crypto",
+            });
+            // Mark credited (advisory — primary idempotency is the ledger referenceId above).
+            await chargeStore.markCredited(payload.invoiceId);
+            // Reactivate suspended resources after credit purchase.
+            let reactivatedBots;
+            if (deps.onCreditsPurchased) {
+                reactivatedBots = await deps.onCreditsPurchased(charge.tenantId, creditLedger);
+                if (reactivatedBots.length === 0)
+                    reactivatedBots = undefined;
+            }
+            result = {
+                handled: true,
+                status,
+                tenant: charge.tenantId,
+                creditedCents: creditCents,
+                reactivatedBots,
+            };
+        }
+    }
+    else {
+        // New, Processing, Expired, Invalid — just track status.
+        result = {
+            handled: true,
+            status,
+            tenant: charge.tenantId,
+        };
+    }
+    await deps.replayGuard.markSeen(dedupeKey, "crypto");
+    return result;
+}

package/dist/billing/crypto/webhook.test.js

@@ -0,0 +1,266 @@
+import crypto from "node:crypto";
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { DrizzleLedger } from "../../credits/ledger.js";
+import { createTestDb, truncateAllTables } from "../../test/db.js";
+import { DrizzleWebhookSeenRepository } from "../drizzle-webhook-seen-repository.js";
+import { noOpReplayGuard } from "../webhook-seen-repository.js";
+import { CryptoChargeRepository } from "./charge-store.js";
+import { mapBtcPayEventToStatus } from "./types.js";
+import { handleCryptoWebhook, verifyCryptoWebhookSignature } from "./webhook.js";
+function makePayload(overrides = {}) {
+    return {
+        deliveryId: "del-001",
+        webhookId: "whk-001",
+        originalDeliveryId: "del-001",
+        isRedelivery: false,
+        type: "InvoiceSettled",
+        timestamp: Date.now(),
+        storeId: "store-test",
+        invoiceId: "inv-test-001",
+        metadata: { orderId: "order-001" },
+        ...overrides,
+    };
+}
+let pool;
+let db;
+beforeAll(async () => {
+    ({ db, pool } = await createTestDb());
+});
+afterAll(async () => {
+    await pool.close();
+});
+describe("handleCryptoWebhook", () => {
+    let chargeStore;
+    let creditLedger;
+    let deps;
+    beforeEach(async () => {
+        await truncateAllTables(pool);
+        chargeStore = new CryptoChargeRepository(db);
+        creditLedger = new DrizzleLedger(db);
+        await creditLedger.seedSystemAccounts();
+        deps = { chargeStore, creditLedger, replayGuard: noOpReplayGuard };
+        // Create a default test charge
+        await chargeStore.create("inv-test-001", "tenant-a", 2500);
+    });
+    // ---------------------------------------------------------------------------
+    // InvoiceSettled — should credit ledger
+    // ---------------------------------------------------------------------------
+    describe("InvoiceSettled", () => {
+        it("credits the ledger with the requested USD amount", async () => {
+            const result = await handleCryptoWebhook(deps, makePayload({ type: "InvoiceSettled" }));
+            expect(result.handled).toBe(true);
+            expect(result.status).toBe("Settled");
+            expect(result.tenant).toBe("tenant-a");
+            expect(result.creditedCents).toBe(2500);
+            const balance = await creditLedger.balance("tenant-a");
+            expect(balance.toCents()).toBe(2500);
+        });
+        it("uses crypto: prefix on reference ID in credit transaction", async () => {
+            await handleCryptoWebhook(deps, makePayload({ type: "InvoiceSettled" }));
+            const history = await creditLedger.history("tenant-a");
+            expect(history).toHaveLength(1);
+            expect(history[0].referenceId).toBe("crypto:inv-test-001");
+            expect(history[0].entryType).toBe("purchase");
+        });
+        it("records fundingSource as crypto", async () => {
+            await handleCryptoWebhook(deps, makePayload({ type: "InvoiceSettled" }));
+            const history = await creditLedger.history("tenant-a");
+            expect(history[0].metadata?.fundingSource).toBe("crypto");
+        });
+        it("marks the charge as credited after Settled", async () => {
+            await handleCryptoWebhook(deps, makePayload({ type: "InvoiceSettled" }));
+            expect(await chargeStore.isCredited("inv-test-001")).toBe(true);
+        });
+        it("is idempotent — duplicate InvoiceSettled does not double-credit", async () => {
+            await handleCryptoWebhook(deps, makePayload({ type: "InvoiceSettled" }));
+            const result2 = await handleCryptoWebhook(deps, makePayload({ type: "InvoiceSettled" }));
+            expect(result2.handled).toBe(true);
+            expect(result2.creditedCents).toBe(0);
+            const balance = await creditLedger.balance("tenant-a");
+            expect(balance.toCents()).toBe(2500); // Only credited once
+        });
+    });
+    // ---------------------------------------------------------------------------
+    // Statuses that should NOT credit the ledger
+    // ---------------------------------------------------------------------------
+    describe("InvoiceProcessing", () => {
+        it("does NOT credit the ledger", async () => {
+            const result = await handleCryptoWebhook(deps, makePayload({ type: "InvoiceProcessing" }));
+            expect(result.handled).toBe(true);
+            expect(result.tenant).toBe("tenant-a");
+            expect(result.creditedCents).toBeUndefined();
+            expect((await creditLedger.balance("tenant-a")).toCents()).toBe(0);
+        });
+    });
+    describe("InvoiceCreated", () => {
+        it("does NOT credit the ledger", async () => {
+            const result = await handleCryptoWebhook(deps, makePayload({ type: "InvoiceCreated" }));
+            expect(result.handled).toBe(true);
+            expect(result.creditedCents).toBeUndefined();
+            expect((await creditLedger.balance("tenant-a")).toCents()).toBe(0);
+        });
+    });
+    describe("InvoiceExpired", () => {
+        it("does NOT credit the ledger", async () => {
+            const result = await handleCryptoWebhook(deps, makePayload({ type: "InvoiceExpired" }));
+            expect(result.handled).toBe(true);
+            expect(result.creditedCents).toBeUndefined();
+            expect((await creditLedger.balance("tenant-a")).toCents()).toBe(0);
+        });
+    });
+    describe("InvoiceInvalid", () => {
+        it("does NOT credit the ledger", async () => {
+            const result = await handleCryptoWebhook(deps, makePayload({ type: "InvoiceInvalid" }));
+            expect(result.handled).toBe(true);
+            expect(result.creditedCents).toBeUndefined();
+            expect((await creditLedger.balance("tenant-a")).toCents()).toBe(0);
+        });
+    });
+    // ---------------------------------------------------------------------------
+    // Unknown invoice ID
+    // ---------------------------------------------------------------------------
+    describe("unknown invoiceId", () => {
+        it("returns handled:false when charge not found", async () => {
+            const result = await handleCryptoWebhook(deps, makePayload({ invoiceId: "inv-unknown-999" }));
+            expect(result.handled).toBe(false);
+            expect(result.tenant).toBeUndefined();
+        });
+    });
+    // ---------------------------------------------------------------------------
+    // Charge store updates
+    // ---------------------------------------------------------------------------
+    describe("charge store updates", () => {
+        it("updates charge status on every webhook call", async () => {
+            await handleCryptoWebhook(deps, makePayload({ type: "InvoiceProcessing" }));
+            const charge = await chargeStore.getByReferenceId("inv-test-001");
+            expect(charge?.status).toBe("Processing");
+        });
+    });
+    // ---------------------------------------------------------------------------
+    // Multiple tenants
+    // ---------------------------------------------------------------------------
+    describe("different invoices", () => {
+        it("processes multiple invoices independently", async () => {
+            await chargeStore.create("inv-b-001", "tenant-b", 5000);
+            await chargeStore.create("inv-c-001", "tenant-c", 1500);
+            await handleCryptoWebhook(deps, makePayload({ invoiceId: "inv-b-001", type: "InvoiceSettled" }));
+            await handleCryptoWebhook(deps, makePayload({ invoiceId: "inv-c-001", type: "InvoiceSettled" }));
+            expect((await creditLedger.balance("tenant-b")).toCents()).toBe(5000);
+            expect((await creditLedger.balance("tenant-c")).toCents()).toBe(1500);
+        });
+    });
+    // ---------------------------------------------------------------------------
+    // Replay guard
+    // ---------------------------------------------------------------------------
+    describe("replay guard", () => {
+        it("blocks duplicate invoiceId + event type combos", async () => {
+            const replayGuard = new DrizzleWebhookSeenRepository(db);
+            const depsWithGuard = { ...deps, replayGuard };
+            const first = await handleCryptoWebhook(depsWithGuard, makePayload({ type: "InvoiceSettled" }));
+            expect(first.handled).toBe(true);
+            expect(first.creditedCents).toBe(2500);
+            expect(first.duplicate).toBeUndefined();
+            const second = await handleCryptoWebhook(depsWithGuard, makePayload({ type: "InvoiceSettled" }));
+            expect(second.handled).toBe(true);
+            expect(second.duplicate).toBe(true);
+            expect(second.creditedCents).toBeUndefined();
+            expect((await creditLedger.balance("tenant-a")).toCents()).toBe(2500);
+        });
+        it("same invoice with different event type is not blocked", async () => {
+            const replayGuard = new DrizzleWebhookSeenRepository(db);
+            const depsWithGuard = { ...deps, replayGuard };
+            await handleCryptoWebhook(depsWithGuard, makePayload({ type: "InvoiceProcessing" }));
+            const result = await handleCryptoWebhook(depsWithGuard, makePayload({ type: "InvoiceSettled" }));
+            expect(result.duplicate).toBeUndefined();
+            expect(result.creditedCents).toBe(2500);
+        });
+    });
+    // ---------------------------------------------------------------------------
+    // Unknown event type
+    // ---------------------------------------------------------------------------
+    describe("unknown event type", () => {
+        it("throws on unrecognized BTCPay event type", async () => {
+            await expect(handleCryptoWebhook(deps, makePayload({ type: "SomeUnknownEvent" }))).rejects.toThrow("Unknown BTCPay event type: SomeUnknownEvent");
+        });
+    });
+    // ---------------------------------------------------------------------------
+    // Resource reactivation
+    // ---------------------------------------------------------------------------
+    describe("resource reactivation via onCreditsPurchased", () => {
+        it("calls onCreditsPurchased on Settled and includes reactivatedBots", async () => {
+            const mockOnCreditsPurchased = vi.fn().mockResolvedValue(["bot-1", "bot-2"]);
+            const depsWithCallback = {
+                ...deps,
+                onCreditsPurchased: mockOnCreditsPurchased,
+            };
+            const result = await handleCryptoWebhook(depsWithCallback, makePayload({ type: "InvoiceSettled" }));
+            expect(mockOnCreditsPurchased).toHaveBeenCalledWith("tenant-a", creditLedger);
+            expect(result.reactivatedBots).toEqual(["bot-1", "bot-2"]);
+        });
+        it("does not include reactivatedBots when no resources reactivated", async () => {
+            const mockOnCreditsPurchased = vi.fn().mockResolvedValue([]);
+            const depsWithCallback = {
+                ...deps,
+                onCreditsPurchased: mockOnCreditsPurchased,
+            };
+            const result = await handleCryptoWebhook(depsWithCallback, makePayload({ type: "InvoiceSettled" }));
+            expect(result.reactivatedBots).toBeUndefined();
+        });
+    });
+});
+// ---------------------------------------------------------------------------
+// Webhook signature verification
+// ---------------------------------------------------------------------------
+describe("verifyCryptoWebhookSignature", () => {
+    const secret = "test-webhook-secret";
+    const body = '{"type":"InvoiceSettled","invoiceId":"inv-001"}';
+    it("returns true for valid signature", () => {
+        const sig = `sha256=${crypto.createHmac("sha256", secret).update(body).digest("hex")}`;
+        expect(verifyCryptoWebhookSignature(body, sig, secret)).toBe(true);
+    });
+    it("returns false for invalid signature", () => {
+        expect(verifyCryptoWebhookSignature(body, "sha256=badhex", secret)).toBe(false);
+    });
+    it("returns false for wrong secret", () => {
+        const sig = `sha256=${crypto.createHmac("sha256", "wrong-secret").update(body).digest("hex")}`;
+        expect(verifyCryptoWebhookSignature(body, sig, secret)).toBe(false);
+    });
+    it("returns false for tampered body", () => {
+        const sig = `sha256=${crypto.createHmac("sha256", secret).update(body).digest("hex")}`;
+        expect(verifyCryptoWebhookSignature(`${body}tampered`, sig, secret)).toBe(false);
+    });
+});
+// ---------------------------------------------------------------------------
+// Replay guard unit tests
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// mapBtcPayEventToStatus
+// ---------------------------------------------------------------------------
+describe("mapBtcPayEventToStatus", () => {
+    it("maps known event types to CryptoPaymentState", () => {
+        expect(mapBtcPayEventToStatus("InvoiceCreated")).toBe("New");
+        expect(mapBtcPayEventToStatus("InvoiceReceivedPayment")).toBe("Processing");
+        expect(mapBtcPayEventToStatus("InvoiceProcessing")).toBe("Processing");
+        expect(mapBtcPayEventToStatus("InvoiceSettled")).toBe("Settled");
+        expect(mapBtcPayEventToStatus("InvoicePaymentSettled")).toBe("Settled");
+        expect(mapBtcPayEventToStatus("InvoiceExpired")).toBe("Expired");
+        expect(mapBtcPayEventToStatus("InvoiceInvalid")).toBe("Invalid");
+    });
+    it("throws on unknown event type", () => {
+        expect(() => mapBtcPayEventToStatus("SomethingElse")).toThrow("Unknown BTCPay event type: SomethingElse");
+    });
+});
+describe("DrizzleWebhookSeenRepository (crypto replay guard)", () => {
+    beforeEach(async () => {
+        await truncateAllTables(pool);
+    });
+    it("reports unseen keys as not duplicate", async () => {
+        const guard = new DrizzleWebhookSeenRepository(db);
+        expect(await guard.isDuplicate("inv-001:InvoiceSettled", "crypto")).toBe(false);
+    });
+    it("reports seen keys as duplicate", async () => {
+        const guard = new DrizzleWebhookSeenRepository(db);
+        await guard.markSeen("inv-001:InvoiceSettled", "crypto");
+        expect(await guard.isDuplicate("inv-001:InvoiceSettled", "crypto")).toBe(true);
+    });
+});

package/dist/billing/index.d.ts

@@ -1,7 +1,7 @@
+export * from "./crypto/index.js";
 export { DrizzleWebhookSeenRepository } from "./drizzle-webhook-seen-repository.js";
 export type { ChargeOpts, ChargeResult, CheckoutOpts, CheckoutSession, Invoice, IPaymentProcessor, PortalOpts, SavedPaymentMethod, SetupResult, WebhookResult, } from "./payment-processor.js";
 export { PaymentMethodOwnershipError } from "./payment-processor.js";
-export * from "./payram/index.js";
 export * from "./stripe/index.js";
 export type { IWebhookSeenRepository } from "./webhook-seen-repository.js";
 export { noOpReplayGuard } from "./webhook-seen-repository.js";

package/dist/billing/index.js

@@ -1,7 +1,7 @@
+// Crypto (BTCPay Server)
+export * from "./crypto/index.js";
 export { DrizzleWebhookSeenRepository } from "./drizzle-webhook-seen-repository.js";
 export { PaymentMethodOwnershipError } from "./payment-processor.js";
-// PayRam
-export * from "./payram/index.js";
 // Stripe
 export * from "./stripe/index.js";
 export { noOpReplayGuard } from "./webhook-seen-repository.js";

package/dist/billing/payment-processor.d.ts

@@ -6,7 +6,7 @@ export declare class PaymentMethodOwnershipError extends Error {
 }
 /** A saved payment method on file for a tenant (processor-agnostic). */
 export interface SavedPaymentMethod {
-    /** Processor-specific payment method ID (e.g. Stripe pm_xxx, PayRam wallet address). */
+    /** Processor-specific payment method ID (e.g. Stripe pm_xxx, BTCPay wallet address). */
     id: string;
     /** Human-readable label (e.g. "Visa ending 4242", "ETH wallet"). */
     label: string;
@@ -77,12 +77,12 @@ export interface WebhookResult {
 /**
  * Processor-agnostic payment interface.
  *
- * Each payment processor (Stripe, PayRam, future processors) implements
+ * Each payment processor (Stripe, BTCPay, future processors) implements
  * this interface. The platform layer programs against IPaymentProcessor
  * and never imports processor-specific types.
  */
 export interface IPaymentProcessor {
-    /** Human-readable processor name (e.g. "stripe", "payram"). */
+    /** Human-readable processor name (e.g. "stripe", "crypto"). */
     readonly name: string;
     /** Create a checkout session for a one-time credit purchase. */
     createCheckoutSession(opts: CheckoutOpts): Promise<CheckoutSession>;