@wopr-network/platform-core 1.14.8 → 1.16.0

package/dist/account/deletion-executor-repository.d.ts

@@ -27,7 +27,7 @@ export interface IDeletionExecutorRepository {
     }[]>;
     deleteSnapshots(tenantId: string): Promise<number>;
     deleteBackupStatus(tenantId: string): Promise<number>;
-    deletePayramCharges(tenantId: string): Promise<number>;
+    deleteCryptoCharges(tenantId: string): Promise<number>;
     deleteTenantStatus(tenantId: string): Promise<number>;
     deleteUserRolesByUser(tenantId: string): Promise<number>;
     deleteUserRolesByTenant(tenantId: string): Promise<number>;
@@ -71,7 +71,7 @@ export declare class DrizzleDeletionExecutorRepository implements IDeletionExecu
     }[]>;
     deleteSnapshots(tenantId: string): Promise<number>;
     deleteBackupStatus(tenantId: string): Promise<number>;
-    deletePayramCharges(tenantId: string): Promise<number>;
+    deleteCryptoCharges(tenantId: string): Promise<number>;
     deleteTenantStatus(tenantId: string): Promise<number>;
     deleteUserRolesByUser(tenantId: string): Promise<number>;
     deleteUserRolesByTenant(tenantId: string): Promise<number>;

package/dist/account/deletion-executor-repository.js

@@ -1,5 +1,5 @@
 import { and, eq, like, lte, or, sql } from "drizzle-orm";
-import { accountDeletionRequests, adminAuditLog, adminNotes, auditLog, backupStatus, billingPeriodSummaries, botInstances, creditBalances, creditTransactions, emailNotifications, meterEvents, notificationPreferences, notificationQueue, payramCharges, snapshots, stripeUsageReports, tenantCustomers, tenantStatus, usageSummaries, userRoles, } from "../db/schema/index.js";
+import { accountDeletionRequests, adminAuditLog, adminNotes, auditLog, backupStatus, billingPeriodSummaries, botInstances, creditBalances, creditTransactions, cryptoCharges, emailNotifications, meterEvents, notificationPreferences, notificationQueue, snapshots, stripeUsageReports, tenantCustomers, tenantStatus, usageSummaries, userRoles, } from "../db/schema/index.js";
 import { toRow } from "./deletion-repository.js";
 // ---------------------------------------------------------------------------
 // Implementation
@@ -172,11 +172,11 @@ export class DrizzleDeletionExecutorRepository {
             .returning({ containerId: backupStatus.containerId });
         return result.length;
     }
-    async deletePayramCharges(tenantId) {
+    async deleteCryptoCharges(tenantId) {
         const result = await this.db
-            .delete(payramCharges)
-            .where(eq(payramCharges.tenantId, tenantId))
-            .returning({ referenceId: payramCharges.referenceId });
+            .delete(cryptoCharges)
+            .where(eq(cryptoCharges.tenantId, tenantId))
+            .returning({ referenceId: cryptoCharges.referenceId });
         return result.length;
     }
     async deleteTenantStatus(tenantId) {

package/dist/{monetization/payram → billing/crypto}/cents-credits-boundary.test.js

@@ -1,41 +1,39 @@
 import { describe, expect, it } from "vitest";
+import { Credit } from "../../credits/credit.js";
 /**
- * Regression tests for PayRam cents/credits boundary (WOP-1058).
+ * Regression tests for crypto cents/credits boundary.
  *
  * Verifies that the USD-to-cents conversion in checkout and
  * the cents-to-credits flow in the webhook maintain correct units.
  *
  * If any of these tests fail after a rename/refactor, a _cents field was
  * incorrectly changed to store Credit raw units (nanodollars) instead of
- * USD cents. See src/monetization/credits/credit-ledger.ts for naming convention.
+ * USD cents. See src/credits/credit-ledger.ts for naming convention.
  */
-describe("WOP-1058: PayRam cents/credits boundary", () => {
-    it("USD to cents conversion is correct (mirrors checkout.ts pattern)", () => {
-        // This mirrors the conversion in payram/checkout.ts: Math.round(opts.amountUsd * 100)
+describe("Crypto cents/credits boundary", () => {
+    it("USD to cents conversion is correct (mirrors checkout.ts Credit.fromDollars pattern)", () => {
+        // This mirrors the conversion in crypto/checkout.ts: Credit.fromDollars(amountUsd).toCentsRounded()
         const amountUsd = 25;
-        const amountUsdCents = Math.round(amountUsd * 100);
+        const amountUsdCents = Credit.fromDollars(amountUsd).toCentsRounded();
         expect(amountUsdCents).toBe(2500);
         // Must NOT be nanodollar scale
         expect(amountUsdCents).toBeLessThan(1_000_000);
     });
     it("minimum payment amount converts to valid cents", () => {
         const MIN_PAYMENT_USD = 10;
-        const cents = Math.round(MIN_PAYMENT_USD * 100);
+        const cents = Credit.fromDollars(MIN_PAYMENT_USD).toCentsRounded();
         expect(cents).toBe(1000);
         expect(Number.isInteger(cents)).toBe(true);
         // Sanity: $10 is 1000 cents, NOT 10_000_000_000 nanodollars
         expect(cents).toBeLessThan(1_000_000);
     });
     it("fractional USD amounts round correctly to cents", () => {
-        // Edge case: floating point conversion
         const amountUsd = 10.99;
-        const cents = Math.round(amountUsd * 100);
+        const cents = Credit.fromDollars(amountUsd).toCentsRounded();
         expect(cents).toBe(1099);
         expect(cents).toBeLessThan(1_000_000);
     });
     it("amountUsdCents stored in charge record equals USD * 100 (not nanodollars)", () => {
-        // The core invariant: payram/checkout.ts stores Math.round(amountUsd * 100)
-        // as amountUsdCents. This test proves the conversion stays at cent scale.
         const testCases = [
             { usd: 10, expectedCents: 1000 },
             { usd: 25, expectedCents: 2500 },
@@ -43,17 +41,17 @@ describe("WOP-1058: PayRam cents/credits boundary", () => {
             { usd: 100, expectedCents: 10000 },
         ];
         for (const { usd, expectedCents } of testCases) {
-            const amountUsdCents = Math.round(usd * 100);
+            const amountUsdCents = Credit.fromDollars(usd).toCentsRounded();
             expect(amountUsdCents).toBe(expectedCents);
             // CREDIT SCALE = 1_000_000_000. If this value approaches that, unit confusion occurred.
             expect(amountUsdCents).toBeLessThan(1_000_000);
         }
     });
-    it("creditedCents in webhook equals amountUsdCents from charge store (1:1 for PayRam)", () => {
-        // payram/webhook.ts: const creditCents = charge.amountUsdCents;
-        // The credited amount always equals the stored USD cents — no bonus tiers for PayRam.
+    it("creditedCents in webhook equals amountUsdCents from charge store (1:1 for crypto)", () => {
+        // crypto/webhook.ts: const creditCents = charge.amountUsdCents;
+        // The credited amount always equals the stored USD cents — no bonus tiers for crypto.
         const chargeAmountUsdCents = 2500; // $25.00
-        const creditCents = chargeAmountUsdCents; // 1:1 for PayRam
+        const creditCents = chargeAmountUsdCents; // 1:1 for crypto
         expect(creditCents).toBe(2500);
         // creditedCents must be 2500 (cents), not 25_000_000_000 (nanodollars)
         expect(creditCents).toBeLessThan(1_000_000);
@@ -61,7 +59,6 @@ describe("WOP-1058: PayRam cents/credits boundary", () => {
     it("cents-to-nanodollar scale difference is preserved as a sanity constant", () => {
         // Credit.SCALE = 1_000_000_000 nanodollars per dollar
         // 1 USD cent = 10_000_000 nanodollars (SCALE / 100)
-        // This test documents the relationship so future developers understand the gap.
         const CREDIT_SCALE = 1_000_000_000;
         const CENTS_PER_DOLLAR = 100;
         const NANODOLLARS_PER_CENT = CREDIT_SCALE / CENTS_PER_DOLLAR;

package/dist/billing/crypto/charge-store.d.ts

@@ -0,0 +1,68 @@
+import type { PlatformDb } from "../../db/index.js";
+import type { CryptoPaymentState } from "./types.js";
+export interface CryptoChargeRecord {
+    referenceId: string;
+    tenantId: string;
+    amountUsdCents: number;
+    status: string;
+    currency: string | null;
+    filledAmount: string | null;
+    creditedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+    chain: string | null;
+    token: string | null;
+    depositAddress: string | null;
+    derivationIndex: number | null;
+}
+export interface StablecoinChargeInput {
+    referenceId: string;
+    tenantId: string;
+    amountUsdCents: number;
+    chain: string;
+    token: string;
+    depositAddress: string;
+    derivationIndex: number;
+}
+export interface ICryptoChargeRepository {
+    create(referenceId: string, tenantId: string, amountUsdCents: number): Promise<void>;
+    getByReferenceId(referenceId: string): Promise<CryptoChargeRecord | null>;
+    updateStatus(referenceId: string, status: CryptoPaymentState, currency?: string, filledAmount?: string): Promise<void>;
+    markCredited(referenceId: string): Promise<void>;
+    isCredited(referenceId: string): Promise<boolean>;
+    createStablecoinCharge(input: StablecoinChargeInput): Promise<void>;
+    getByDepositAddress(address: string): Promise<CryptoChargeRecord | null>;
+    getNextDerivationIndex(): Promise<number>;
+}
+/**
+ * Manages crypto charge records in PostgreSQL.
+ *
+ * Each charge maps a BTCPay invoice ID to a tenant and tracks
+ * the payment lifecycle (New → Processing → Settled/Expired/Invalid).
+ *
+ * amountUsdCents stores the requested amount in USD cents (integer).
+ * This is NOT nanodollars — Credit.fromCents() handles the conversion
+ * when crediting the ledger in the webhook handler.
+ */
+export declare class DrizzleCryptoChargeRepository implements ICryptoChargeRepository {
+    private readonly db;
+    constructor(db: PlatformDb);
+    /** Create a new charge record when an invoice is created. */
+    create(referenceId: string, tenantId: string, amountUsdCents: number): Promise<void>;
+    /** Get a charge by reference ID. Returns null if not found. */
+    getByReferenceId(referenceId: string): Promise<CryptoChargeRecord | null>;
+    private toRecord;
+    /** Update charge status and payment details from webhook. */
+    updateStatus(referenceId: string, status: CryptoPaymentState, currency?: string, filledAmount?: string): Promise<void>;
+    /** Mark a charge as credited (idempotency flag). */
+    markCredited(referenceId: string): Promise<void>;
+    /** Check if a charge has already been credited (for idempotency). */
+    isCredited(referenceId: string): Promise<boolean>;
+    /** Create a stablecoin charge with chain/token/deposit address. */
+    createStablecoinCharge(input: StablecoinChargeInput): Promise<void>;
+    /** Look up a charge by its deposit address. */
+    getByDepositAddress(address: string): Promise<CryptoChargeRecord | null>;
+    /** Get the next available HD derivation index (max + 1, or 0 if empty). */
+    getNextDerivationIndex(): Promise<number>;
+}
+export { DrizzleCryptoChargeRepository as CryptoChargeRepository };

package/dist/billing/crypto/charge-store.js

@@ -0,0 +1,109 @@
+import { eq, sql } from "drizzle-orm";
+import { cryptoCharges } from "../../db/schema/crypto.js";
+/**
+ * Manages crypto charge records in PostgreSQL.
+ *
+ * Each charge maps a BTCPay invoice ID to a tenant and tracks
+ * the payment lifecycle (New → Processing → Settled/Expired/Invalid).
+ *
+ * amountUsdCents stores the requested amount in USD cents (integer).
+ * This is NOT nanodollars — Credit.fromCents() handles the conversion
+ * when crediting the ledger in the webhook handler.
+ */
+export class DrizzleCryptoChargeRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /** Create a new charge record when an invoice is created. */
+    async create(referenceId, tenantId, amountUsdCents) {
+        await this.db.insert(cryptoCharges).values({
+            referenceId,
+            tenantId,
+            amountUsdCents,
+            status: "New",
+        });
+    }
+    /** Get a charge by reference ID. Returns null if not found. */
+    async getByReferenceId(referenceId) {
+        const row = (await this.db.select().from(cryptoCharges).where(eq(cryptoCharges.referenceId, referenceId)))[0];
+        if (!row)
+            return null;
+        return this.toRecord(row);
+    }
+    toRecord(row) {
+        return {
+            referenceId: row.referenceId,
+            tenantId: row.tenantId,
+            amountUsdCents: row.amountUsdCents,
+            status: row.status,
+            currency: row.currency ?? null,
+            filledAmount: row.filledAmount ?? null,
+            creditedAt: row.creditedAt ?? null,
+            createdAt: row.createdAt,
+            updatedAt: row.updatedAt,
+            chain: row.chain ?? null,
+            token: row.token ?? null,
+            depositAddress: row.depositAddress ?? null,
+            derivationIndex: row.derivationIndex ?? null,
+        };
+    }
+    /** Update charge status and payment details from webhook. */
+    async updateStatus(referenceId, status, currency, filledAmount) {
+        await this.db
+            .update(cryptoCharges)
+            .set({
+            status,
+            currency,
+            filledAmount,
+            updatedAt: sql `now()`,
+        })
+            .where(eq(cryptoCharges.referenceId, referenceId));
+    }
+    /** Mark a charge as credited (idempotency flag). */
+    async markCredited(referenceId) {
+        await this.db
+            .update(cryptoCharges)
+            .set({
+            creditedAt: sql `now()`,
+            updatedAt: sql `now()`,
+        })
+            .where(eq(cryptoCharges.referenceId, referenceId));
+    }
+    /** Check if a charge has already been credited (for idempotency). */
+    async isCredited(referenceId) {
+        const row = (await this.db
+            .select({ creditedAt: cryptoCharges.creditedAt })
+            .from(cryptoCharges)
+            .where(eq(cryptoCharges.referenceId, referenceId)))[0];
+        return row?.creditedAt != null;
+    }
+    /** Create a stablecoin charge with chain/token/deposit address. */
+    async createStablecoinCharge(input) {
+        await this.db.insert(cryptoCharges).values({
+            referenceId: input.referenceId,
+            tenantId: input.tenantId,
+            amountUsdCents: input.amountUsdCents,
+            status: "New",
+            chain: input.chain,
+            token: input.token,
+            depositAddress: input.depositAddress,
+            derivationIndex: input.derivationIndex,
+        });
+    }
+    /** Look up a charge by its deposit address. */
+    async getByDepositAddress(address) {
+        const row = (await this.db.select().from(cryptoCharges).where(eq(cryptoCharges.depositAddress, address)))[0];
+        if (!row)
+            return null;
+        return this.toRecord(row);
+    }
+    /** Get the next available HD derivation index (max + 1, or 0 if empty). */
+    async getNextDerivationIndex() {
+        const result = await this.db
+            .select({ maxIdx: sql `coalesce(max(${cryptoCharges.derivationIndex}), -1)` })
+            .from(cryptoCharges);
+        return (result[0]?.maxIdx ?? -1) + 1;
+    }
+}
+export { DrizzleCryptoChargeRepository as CryptoChargeRepository };

package/dist/billing/crypto/charge-store.test.js

@@ -0,0 +1,120 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { beginTestTransaction, createTestDb, endTestTransaction, rollbackTestTransaction } from "../../test/db.js";
+import { CryptoChargeRepository } from "./charge-store.js";
+describe("CryptoChargeRepository", () => {
+    let pool;
+    let db;
+    let store;
+    beforeAll(async () => {
+        ({ db, pool } = await createTestDb());
+        await beginTestTransaction(pool);
+    });
+    afterAll(async () => {
+        await endTestTransaction(pool);
+        await pool.close();
+    });
+    beforeEach(async () => {
+        await rollbackTestTransaction(pool);
+        store = new CryptoChargeRepository(db);
+    });
+    it("create() stores a charge with New status", async () => {
+        await store.create("inv-001", "tenant-1", 2500);
+        const charge = await store.getByReferenceId("inv-001");
+        expect(charge).not.toBeNull();
+        expect(charge?.referenceId).toBe("inv-001");
+        expect(charge?.tenantId).toBe("tenant-1");
+        expect(charge?.amountUsdCents).toBe(2500);
+        expect(charge?.status).toBe("New");
+        expect(charge?.creditedAt).toBeNull();
+    });
+    it("getByReferenceId() returns null when not found", async () => {
+        const charge = await store.getByReferenceId("inv-nonexistent");
+        expect(charge).toBeNull();
+    });
+    it("updateStatus() updates status, currency and filled_amount", async () => {
+        await store.create("inv-002", "tenant-2", 5000);
+        await store.updateStatus("inv-002", "Settled", "BTC", "0.00025");
+        const charge = await store.getByReferenceId("inv-002");
+        expect(charge?.status).toBe("Settled");
+        expect(charge?.currency).toBe("BTC");
+        expect(charge?.filledAmount).toBe("0.00025");
+    });
+    it("updateStatus() handles partial updates (no currency)", async () => {
+        await store.create("inv-003", "tenant-3", 1000);
+        await store.updateStatus("inv-003", "Processing");
+        const charge = await store.getByReferenceId("inv-003");
+        expect(charge?.status).toBe("Processing");
+        expect(charge?.currency).toBeNull();
+    });
+    it("isCredited() returns false before markCredited", async () => {
+        await store.create("inv-004", "tenant-4", 1500);
+        expect(await store.isCredited("inv-004")).toBe(false);
+    });
+    it("markCredited() sets creditedAt", async () => {
+        await store.create("inv-005", "tenant-5", 3000);
+        await store.markCredited("inv-005");
+        const charge = await store.getByReferenceId("inv-005");
+        expect(charge?.creditedAt).not.toBeNull();
+    });
+    it("isCredited() returns true after markCredited", async () => {
+        await store.create("inv-006", "tenant-6", 2000);
+        await store.markCredited("inv-006");
+        expect(await store.isCredited("inv-006")).toBe(true);
+    });
+    describe("stablecoin charges", () => {
+        it("creates a stablecoin charge with chain/token/address", async () => {
+            await store.createStablecoinCharge({
+                referenceId: "sc:base:usdc:0x123",
+                tenantId: "tenant-1",
+                amountUsdCents: 1000,
+                chain: "base",
+                token: "USDC",
+                depositAddress: "0xabc123",
+                derivationIndex: 42,
+            });
+            const charge = await store.getByReferenceId("sc:base:usdc:0x123");
+            expect(charge).not.toBeNull();
+            expect(charge?.chain).toBe("base");
+            expect(charge?.token).toBe("USDC");
+            expect(charge?.depositAddress).toBe("0xabc123");
+            expect(charge?.derivationIndex).toBe(42);
+            expect(charge?.amountUsdCents).toBe(1000);
+        });
+        it("looks up charge by deposit address", async () => {
+            await store.createStablecoinCharge({
+                referenceId: "sc:base:usdc:0x456",
+                tenantId: "tenant-2",
+                amountUsdCents: 5000,
+                chain: "base",
+                token: "USDC",
+                depositAddress: "0xdef456",
+                derivationIndex: 43,
+            });
+            const charge = await store.getByDepositAddress("0xdef456");
+            expect(charge).not.toBeNull();
+            expect(charge?.tenantId).toBe("tenant-2");
+            expect(charge?.amountUsdCents).toBe(5000);
+        });
+        it("returns null for unknown deposit address", async () => {
+            const charge = await store.getByDepositAddress("0xnonexistent");
+            expect(charge).toBeNull();
+        });
+        it("gets next derivation index (0 when empty)", async () => {
+            const idx = await store.getNextDerivationIndex();
+            expect(idx).toBe(0);
+        });
+        it("gets next derivation index (max + 1)", async () => {
+            await store.createStablecoinCharge({
+                referenceId: "sc:idx-test",
+                tenantId: "t",
+                amountUsdCents: 100,
+                chain: "base",
+                token: "USDC",
+                depositAddress: "0xidxtest",
+                derivationIndex: 5,
+            });
+            const idx = await store.getNextDerivationIndex();
+            expect(idx).toBe(6);
+        });
+    });
+});

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

@@ -0,0 +1,18 @@
+import type { ICryptoChargeRepository } from "./charge-store.js";
+import type { BTCPayClient } from "./client.js";
+import type { CryptoCheckoutOpts } from "./types.js";
+/** Minimum payment amount in USD. */
+export declare const MIN_PAYMENT_USD = 10;
+/**
+ * Create a BTCPay invoice and store the charge record.
+ *
+ * Returns the BTCPay-hosted checkout page URL and invoice ID.
+ * The user is redirected to checkoutLink to complete the crypto payment.
+ *
+ * NOTE: amountUsd is converted to cents (integer) for the charge store.
+ * The charge store holds USD cents, NOT nanodollars.
+ */
+export declare function createCryptoCheckout(client: BTCPayClient, chargeStore: ICryptoChargeRepository, opts: CryptoCheckoutOpts): Promise<{
+    referenceId: string;
+    url: string;
+}>;

package/dist/billing/crypto/checkout.js

@@ -0,0 +1,35 @@
+import crypto from "node:crypto";
+import { Credit } from "../../credits/credit.js";
+/** Minimum payment amount in USD. */
+export const MIN_PAYMENT_USD = 10;
+/**
+ * Create a BTCPay invoice and store the charge record.
+ *
+ * Returns the BTCPay-hosted checkout page URL and invoice ID.
+ * The user is redirected to checkoutLink to complete the crypto payment.
+ *
+ * NOTE: amountUsd is converted to cents (integer) for the charge store.
+ * The charge store holds USD cents, NOT nanodollars.
+ */
+export async function createCryptoCheckout(client, chargeStore, opts) {
+    if (opts.amountUsd < MIN_PAYMENT_USD) {
+        throw new Error(`Minimum payment amount is $${MIN_PAYMENT_USD}`);
+    }
+    const orderId = `crypto:${opts.tenant}:${crypto.randomUUID()}`;
+    const invoice = await client.createInvoice({
+        amountUsd: opts.amountUsd,
+        orderId,
+        buyerEmail: `${opts.tenant}@${process.env.PLATFORM_DOMAIN ?? "wopr.bot"}`,
+    });
+    // Store the charge record for webhook correlation.
+    // amountUsdCents = USD * 100 (cents, NOT nanodollars).
+    // Credit.fromDollars() handles the float → integer boundary safely via Math.round
+    // on the nanodollar scale, then toCentsRounded() converts back to integer cents.
+    // This avoids direct floating-point multiplication for the cents conversion.
+    const amountUsdCents = Credit.fromDollars(opts.amountUsd).toCentsRounded();
+    await chargeStore.create(invoice.id, opts.tenant, amountUsdCents);
+    return {
+        referenceId: invoice.id,
+        url: invoice.checkoutLink,
+    };
+}

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

@@ -0,0 +1,71 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { beginTestTransaction, createTestDb, endTestTransaction, rollbackTestTransaction } from "../../test/db.js";
+import { CryptoChargeRepository } from "./charge-store.js";
+import { createCryptoCheckout, MIN_PAYMENT_USD } from "./checkout.js";
+function createMockClient(overrides = {}) {
+    return {
+        createInvoice: overrides.createInvoice ??
+            vi.fn().mockResolvedValue({
+                id: "inv-mock-001",
+                checkoutLink: "https://btcpay.example.com/i/inv-mock-001",
+            }),
+    };
+}
+describe("createCryptoCheckout", () => {
+    let pool;
+    let db;
+    let chargeStore;
+    let client;
+    beforeAll(async () => {
+        ({ db, pool } = await createTestDb());
+        await beginTestTransaction(pool);
+    });
+    afterAll(async () => {
+        await endTestTransaction(pool);
+        await pool.close();
+    });
+    beforeEach(async () => {
+        await rollbackTestTransaction(pool);
+        chargeStore = new CryptoChargeRepository(db);
+        client = createMockClient();
+    });
+    it("rejects amounts below $10 minimum", async () => {
+        await expect(createCryptoCheckout(client, chargeStore, { tenant: "t-1", amountUsd: 5 })).rejects.toThrow(`Minimum payment amount is $${MIN_PAYMENT_USD}`);
+    });
+    it("rejects amounts of exactly $0", async () => {
+        await expect(createCryptoCheckout(client, chargeStore, { tenant: "t-1", amountUsd: 0 })).rejects.toThrow();
+    });
+    it("calls client.createInvoice with correct params", async () => {
+        const createInvoice = vi.fn().mockResolvedValue({
+            id: "inv-abc",
+            checkoutLink: "https://btcpay.example.com/i/inv-abc",
+        });
+        const mockClient = createMockClient({ createInvoice });
+        await createCryptoCheckout(mockClient, chargeStore, { tenant: "t-test", amountUsd: 25 });
+        expect(createInvoice).toHaveBeenCalledOnce();
+        const args = createInvoice.mock.calls[0][0];
+        expect(args.amountUsd).toBe(25);
+        expect(args.buyerEmail).toContain("t-test@");
+    });
+    it("stores the charge with correct amountUsdCents (converts from USD)", async () => {
+        const createInvoice = vi.fn().mockResolvedValue({
+            id: "inv-store-test",
+            checkoutLink: "https://btcpay.example.com/i/inv-store-test",
+        });
+        const mockClient = createMockClient({ createInvoice });
+        await createCryptoCheckout(mockClient, chargeStore, { tenant: "t-2", amountUsd: 25 });
+        const charge = await chargeStore.getByReferenceId("inv-store-test");
+        expect(charge).not.toBeNull();
+        expect(charge?.tenantId).toBe("t-2");
+        expect(charge?.amountUsdCents).toBe(2500); // $25.00 = 2500 cents
+        expect(charge?.status).toBe("New");
+    });
+    it("returns referenceId and url", async () => {
+        const result = await createCryptoCheckout(client, chargeStore, { tenant: "t-3", amountUsd: 10 });
+        expect(result.referenceId).toBe("inv-mock-001");
+        expect(result.url).toBe("https://btcpay.example.com/i/inv-mock-001");
+    });
+    it("accepts exactly $10 (minimum boundary)", async () => {
+        await expect(createCryptoCheckout(client, chargeStore, { tenant: "t-4", amountUsd: 10 })).resolves.not.toBeNull();
+    });
+});

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

@@ -0,0 +1,39 @@
+import type { CryptoBillingConfig } from "./types.js";
+export type { CryptoBillingConfig as CryptoConfig };
+/**
+ * Lightweight BTCPay Server Greenfield API client.
+ *
+ * Uses plain fetch — zero vendor dependencies.
+ * Auth header format: "token <apiKey>" (NOT "Bearer").
+ */
+export declare class BTCPayClient {
+    private readonly config;
+    constructor(config: CryptoBillingConfig);
+    private headers;
+    /**
+     * Create an invoice on the BTCPay store.
+     *
+     * Returns the invoice ID and checkout link (URL to redirect the user).
+     */
+    createInvoice(opts: {
+        amountUsd: number;
+        orderId: string;
+        buyerEmail?: string;
+        redirectURL?: string;
+    }): Promise<{
+        id: string;
+        checkoutLink: string;
+    }>;
+    /** Get invoice status by ID. */
+    getInvoice(invoiceId: string): Promise<{
+        id: string;
+        status: string;
+        amount: string;
+        currency: string;
+    }>;
+}
+/**
+ * Load BTCPay config from environment variables.
+ * Returns null if any required var is missing.
+ */
+export declare function loadCryptoConfig(): CryptoBillingConfig | null;

package/dist/billing/crypto/client.js

@@ -0,0 +1,72 @@
+/**
+ * Lightweight BTCPay Server Greenfield API client.
+ *
+ * Uses plain fetch — zero vendor dependencies.
+ * Auth header format: "token <apiKey>" (NOT "Bearer").
+ */
+export class BTCPayClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    headers() {
+        return {
+            "Content-Type": "application/json",
+            Authorization: `token ${this.config.apiKey}`,
+        };
+    }
+    /**
+     * Create an invoice on the BTCPay store.
+     *
+     * Returns the invoice ID and checkout link (URL to redirect the user).
+     */
+    async createInvoice(opts) {
+        const url = `${this.config.baseUrl}/api/v1/stores/${this.config.storeId}/invoices`;
+        const body = {
+            amount: String(opts.amountUsd),
+            currency: "USD",
+            metadata: {
+                orderId: opts.orderId,
+                buyerEmail: opts.buyerEmail,
+            },
+            checkout: {
+                speedPolicy: "MediumSpeed",
+                expirationMinutes: 30,
+                ...(opts.redirectURL ? { redirectURL: opts.redirectURL } : {}),
+            },
+        };
+        const res = await fetch(url, {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`BTCPay createInvoice failed (${res.status}): ${text}`);
+        }
+        const data = (await res.json());
+        return { id: data.id, checkoutLink: data.checkoutLink };
+    }
+    /** Get invoice status by ID. */
+    async getInvoice(invoiceId) {
+        const url = `${this.config.baseUrl}/api/v1/stores/${this.config.storeId}/invoices/${invoiceId}`;
+        const res = await fetch(url, { headers: this.headers() });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`BTCPay getInvoice failed (${res.status}): ${text}`);
+        }
+        return (await res.json());
+    }
+}
+/**
+ * Load BTCPay config from environment variables.
+ * Returns null if any required var is missing.
+ */
+export function loadCryptoConfig() {
+    const apiKey = process.env.BTCPAY_API_KEY;
+    const baseUrl = process.env.BTCPAY_BASE_URL;
+    const storeId = process.env.BTCPAY_STORE_ID;
+    if (!apiKey || !baseUrl || !storeId)
+        return null;
+    return { apiKey, baseUrl, storeId };
+}