@wopr-network/platform-core 1.14.8 → 1.15.0

package/drizzle/migrations/0004_crypto_charges.sql

@@ -0,0 +1,25 @@
+-- Replace payram_charges with crypto_charges (BTCPay Server).
+-- payram_charges existed only in the initial schema (0000) and was never used
+-- in production — no data migration is needed. The table is dropped and replaced
+-- with crypto_charges which has the same column structure but uses BTCPay-specific
+-- naming (reference_id = BTCPay invoice ID).
+--> statement-breakpoint
+DROP TABLE IF EXISTS "payram_charges";
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "crypto_charges" (
+	"reference_id" text PRIMARY KEY NOT NULL,
+	"tenant_id" text NOT NULL,
+	"amount_usd_cents" integer NOT NULL,
+	"status" text DEFAULT 'New' NOT NULL,
+	"currency" text,
+	"filled_amount" text,
+	"created_at" text DEFAULT (now()) NOT NULL,
+	"updated_at" text DEFAULT (now()) NOT NULL,
+	"credited_at" text
+);
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "idx_crypto_charges_tenant" ON "crypto_charges" USING btree ("tenant_id");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "idx_crypto_charges_status" ON "crypto_charges" USING btree ("status");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "idx_crypto_charges_created" ON "crypto_charges" USING btree ("created_at");

package/drizzle/migrations/meta/_journal.json

@@ -29,6 +29,13 @@
       "when": 1741881600000,
       "tag": "0003_double_entry_ledger",
       "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1741968000000,
+      "tag": "0004_crypto_charges",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/platform-core",
-  "version": "1.14.8",
+  "version": "1.15.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -87,7 +87,6 @@
     "dockerode": ">=4",
     "drizzle-orm": ">=0.45",
     "hono": ">=4",
-    "payram": ">=1",
     "pg": ">=8",
     "resend": ">=4",
     "stripe": ">=17",
@@ -111,7 +110,6 @@
     "drizzle-orm": "^0.45.1",
     "hono": "^4.12.7",
     "lru-cache": "^11.2.6",
-    "payram": "^1.0.1",
     "pg": "^8.20.0",
     "resend": "^6.9.3",
     "stripe": "^20.4.1",

package/src/account/deletion-executor-repository.ts

@@ -10,11 +10,11 @@ import {
   botInstances,
   creditBalances,
   creditTransactions,
+  cryptoCharges,
   emailNotifications,
   meterEvents,
   notificationPreferences,
   notificationQueue,
-  payramCharges,
   snapshots,
   stripeUsageReports,
   tenantCustomers,
@@ -55,7 +55,7 @@ export interface IDeletionExecutorRepository {
   listSnapshotS3Keys(tenantId: string): Promise<{ id: string; s3Key: string | null }[]>;
   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>;
@@ -259,11 +259,11 @@ export class DrizzleDeletionExecutorRepository implements IDeletionExecutorRepos
     return result.length;
   }
 
-  async deletePayramCharges(tenantId: string): Promise<number> {
+  async deleteCryptoCharges(tenantId: string): Promise<number> {
     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;
   }
 

package/src/billing/{payram → crypto}/cents-credits-boundary.test.ts

@@ -1,20 +1,21 @@
 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);
@@ -22,7 +23,7 @@ describe("WOP-1058: PayRam cents/credits boundary", () => {
 
   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
@@ -30,16 +31,13 @@ describe("WOP-1058: PayRam cents/credits boundary", () => {
   });
 
   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: Array<{ usd: number; expectedCents: number }> = [
       { usd: 10, expectedCents: 1000 },
       { usd: 25, expectedCents: 2500 },
@@ -48,18 +46,18 @@ describe("WOP-1058: PayRam cents/credits boundary", () => {
     ];
 
     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);
@@ -68,7 +66,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/src/billing/crypto/charge-store.test.ts

@@ -0,0 +1,81 @@
+import type { PGlite } from "@electric-sql/pglite";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import type { PlatformDb } from "../../db/index.js";
+import { beginTestTransaction, createTestDb, endTestTransaction, rollbackTestTransaction } from "../../test/db.js";
+import { CryptoChargeRepository } from "./charge-store.js";
+
+describe("CryptoChargeRepository", () => {
+  let pool: PGlite;
+  let db: PlatformDb;
+  let store: CryptoChargeRepository;
+
+  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);
+  });
+});

package/src/billing/{payram → crypto}/charge-store.ts

@@ -1,9 +1,9 @@
 import { eq, sql } from "drizzle-orm";
 import type { PlatformDb } from "../../db/index.js";
-import { payramCharges } from "../../db/schema/payram.js";
-import type { PayRamPaymentState } from "./types.js";
+import { cryptoCharges } from "../../db/schema/crypto.js";
+import type { CryptoPaymentState } from "./types.js";
 
-export interface PayRamChargeRecord {
+export interface CryptoChargeRecord {
   referenceId: string;
   tenantId: string;
   amountUsdCents: number;
@@ -15,12 +15,12 @@ export interface PayRamChargeRecord {
   updatedAt: string;
 }
 
-export interface IPayRamChargeRepository {
+export interface ICryptoChargeRepository {
   create(referenceId: string, tenantId: string, amountUsdCents: number): Promise<void>;
-  getByReferenceId(referenceId: string): Promise<PayRamChargeRecord | null>;
+  getByReferenceId(referenceId: string): Promise<CryptoChargeRecord | null>;
   updateStatus(
     referenceId: string,
-    status: PayRamPaymentState,
+    status: CryptoPaymentState,
     currency?: string,
     filledAmount?: string,
   ): Promise<void>;
@@ -29,27 +29,31 @@ export interface IPayRamChargeRepository {
 }
 
 /**
- * Manages PayRam charge records in PostgreSQL.
+ * Manages crypto charge records in PostgreSQL.
  *
- * Each charge maps a PayRam reference_id to a tenant and tracks
- * the payment lifecycle (OPEN -> VERIFYING -> FILLED/CANCELLED).
+ * 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 DrizzlePayRamChargeRepository implements IPayRamChargeRepository {
+export class DrizzleCryptoChargeRepository implements ICryptoChargeRepository {
   constructor(private readonly db: PlatformDb) {}
 
-  /** Create a new charge record when a payment session is initiated. */
+  /** Create a new charge record when an invoice is created. */
   async create(referenceId: string, tenantId: string, amountUsdCents: number): Promise<void> {
-    await this.db.insert(payramCharges).values({
+    await this.db.insert(cryptoCharges).values({
       referenceId,
       tenantId,
       amountUsdCents,
-      status: "OPEN",
+      status: "New",
     });
   }
 
   /** Get a charge by reference ID. Returns null if not found. */
-  async getByReferenceId(referenceId: string): Promise<PayRamChargeRecord | null> {
-    const row = (await this.db.select().from(payramCharges).where(eq(payramCharges.referenceId, referenceId)))[0];
+  async getByReferenceId(referenceId: string): Promise<CryptoChargeRecord | null> {
+    const row = (await this.db.select().from(cryptoCharges).where(eq(cryptoCharges.referenceId, referenceId)))[0];
     if (!row) return null;
     return {
       referenceId: row.referenceId,
@@ -67,43 +71,42 @@ export class DrizzlePayRamChargeRepository implements IPayRamChargeRepository {
   /** Update charge status and payment details from webhook. */
   async updateStatus(
     referenceId: string,
-    status: PayRamPaymentState,
+    status: CryptoPaymentState,
     currency?: string,
     filledAmount?: string,
   ): Promise<void> {
     await this.db
-      .update(payramCharges)
+      .update(cryptoCharges)
       .set({
         status,
         currency,
         filledAmount,
         updatedAt: sql`now()`,
       })
-      .where(eq(payramCharges.referenceId, referenceId));
+      .where(eq(cryptoCharges.referenceId, referenceId));
   }
 
   /** Mark a charge as credited (idempotency flag). */
   async markCredited(referenceId: string): Promise<void> {
     await this.db
-      .update(payramCharges)
+      .update(cryptoCharges)
       .set({
         creditedAt: sql`now()`,
         updatedAt: sql`now()`,
       })
-      .where(eq(payramCharges.referenceId, referenceId));
+      .where(eq(cryptoCharges.referenceId, referenceId));
   }
 
   /** Check if a charge has already been credited (for idempotency). */
   async isCredited(referenceId: string): Promise<boolean> {
     const row = (
       await this.db
-        .select({ creditedAt: payramCharges.creditedAt })
-        .from(payramCharges)
-        .where(eq(payramCharges.referenceId, referenceId))
+        .select({ creditedAt: cryptoCharges.creditedAt })
+        .from(cryptoCharges)
+        .where(eq(cryptoCharges.referenceId, referenceId))
     )[0];
     return row?.creditedAt != null;
   }
 }
 
-// Backward-compat alias.
-export { DrizzlePayRamChargeRepository as PayRamChargeRepository };
+export { DrizzleCryptoChargeRepository as CryptoChargeRepository };

package/src/billing/crypto/checkout.test.ts

@@ -0,0 +1,93 @@
+import type { PGlite } from "@electric-sql/pglite";
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import type { PlatformDb } from "../../db/index.js";
+import { beginTestTransaction, createTestDb, endTestTransaction, rollbackTestTransaction } from "../../test/db.js";
+import { CryptoChargeRepository } from "./charge-store.js";
+import { createCryptoCheckout, MIN_PAYMENT_USD } from "./checkout.js";
+import type { BTCPayClient } from "./client.js";
+
+function createMockClient(overrides: { createInvoice?: ReturnType<typeof vi.fn> } = {}): BTCPayClient {
+  return {
+    createInvoice:
+      overrides.createInvoice ??
+      vi.fn().mockResolvedValue({
+        id: "inv-mock-001",
+        checkoutLink: "https://btcpay.example.com/i/inv-mock-001",
+      }),
+  } as unknown as BTCPayClient;
+}
+
+describe("createCryptoCheckout", () => {
+  let pool: PGlite;
+  let db: PlatformDb;
+  let chargeStore: CryptoChargeRepository;
+  let client: BTCPayClient;
+
+  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/src/billing/crypto/checkout.ts

@@ -0,0 +1,48 @@
+import crypto from "node:crypto";
+import { Credit } from "../../credits/credit.js";
+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 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: BTCPayClient,
+  chargeStore: ICryptoChargeRepository,
+  opts: CryptoCheckoutOpts,
+): Promise<{ referenceId: string; url: string }> {
+  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/src/billing/crypto/client.test.ts

@@ -0,0 +1,132 @@
+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 as Record<string, string>;
+    expect(headers.Authorization).toBe("token test-key");
+    expect(headers["Content-Type"]).toBe("application/json");
+
+    const body = JSON.parse(opts?.body as string);
+    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 as string);
+    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();
+  });
+});