@wopr-network/platform-core 1.14.7 → 1.15.0

package/dist/monetization/crypto/webhook.js

@@ -0,0 +1,88 @@
+import { mapBtcPayEventToStatus } from "@wopr-network/platform-core/billing";
+import { Credit } from "@wopr-network/platform-core/credits";
+/**
+ * Process a BTCPay Server webhook event (WOPR-specific version).
+ *
+ * Only credits the ledger on InvoiceSettled.
+ * Uses botBilling.checkReactivation for WOPR bot suspension recovery.
+ *
+ * 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: charge.amountUsdCents is in USD cents (integer).
+ * Credit.fromCents() converts cents → nanodollars for the ledger.
+ */
+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).
+            // 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 bots (same as Stripe webhook).
+            let reactivatedBots;
+            if (deps.botBilling) {
+                reactivatedBots = await deps.botBilling.checkReactivation(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/monetization/index.d.ts

@@ -41,14 +41,14 @@ export type { BudgetCheckerConfig, BudgetCheckResult, SpendLimits } from "./budg
 export { BudgetChecker, DrizzleBudgetChecker } from "./budget/index.js";
 export type { BillingState, CreditType, DebitType, GetActiveBotCount, HistoryOptions, ILedger, JournalEntry, OnSuspend, RuntimeCronConfig, RuntimeCronResult, TransactionType, } from "./credits/index.js";
 export { BotBilling, buildResourceTierCosts, DAILY_BOT_COST, DrizzleBotBilling, DrizzleLedger, grantSignupCredits, InsufficientBalanceError, Ledger, runRuntimeDeductions, SIGNUP_GRANT, SUSPENSION_GRACE_DAYS, } from "./credits/index.js";
+export type { CryptoBillingConfig, CryptoCheckoutOpts, CryptoConfig, CryptoPaymentState, CryptoWebhookDeps, CryptoWebhookPayload, CryptoWebhookResult, } from "./crypto/index.js";
+export { BTCPayClient, CryptoChargeRepository, createCryptoCheckout, DrizzleCryptoChargeRepository, handleCryptoWebhook, loadCryptoConfig, MIN_PAYMENT_USD, mapBtcPayEventToStatus, verifyCryptoWebhookSignature, } from "./crypto/index.js";
 export { type CreditGateConfig, createBalanceGate, createCreditGate, createFeatureGate, type FeatureGateConfig, type GetUserBalance, type ResolveTenantId, } from "./feature-gate.js";
 export type { BillingPeriod, BillingPeriodSummary, MeterEventRow, UsageSummary, } from "./metering/index.js";
 export { DrizzleMeterAggregator, DrizzleMeterEmitter, MeterAggregator, MeterEmitter, } from "./metering/index.js";
-export type { PayRamBillingConfig, PayRamCheckoutOpts, PayRamConfig, PayRamPaymentState, PayRamWebhookDeps, PayRamWebhookPayload, PayRamWebhookResult, } from "./payram/index.js";
-export { createPayRamCheckout, createPayRamClient, DrizzlePayRamChargeRepository, handlePayRamWebhook, loadPayRamConfig, MIN_PAYMENT_USD, PayRamChargeRepository, } from "./payram/index.js";
 export { checkInstanceQuota, DEFAULT_INSTANCE_LIMITS, type InstanceLimits, type QuotaCheckResult, } from "./quotas/quota-check.js";
 export { buildResourceLimits, type ContainerResourceLimits, DEFAULT_RESOURCE_CONFIG, type ResourceConfig, } from "./quotas/resource-limits.js";
-export type { IBotBilling, IBudgetChecker, IMeterAggregator, IMeterEmitter, IPayRamChargeRepository, ITenantCustomerRepository, PayRamChargeRecord, } from "./repository-types.js";
+export type { CryptoChargeRecord, IBotBilling, IBudgetChecker, ICryptoChargeRepository, IMeterAggregator, IMeterEmitter, ITenantCustomerRepository, } from "./repository-types.js";
 export { AdapterSocket, type SocketConfig, type SocketRequest } from "./socket/socket.js";
 export type { CreditCheckoutOpts, CreditPriceMap, CreditPricePoint, PortalSessionOpts, StripeBillingConfig, TenantCustomerRow, WebhookDeps, WebhookResult, } from "./stripe/index.js";
 export { CREDIT_PRICE_POINTS, createCreditCheckoutSession, createPortalSession, createStripeClient, DrizzleTenantCustomerRepository, getConfiguredPriceIds, getCreditAmountForPurchase, handleWebhookEvent, loadCreditPriceMap, loadStripeConfig, lookupCreditPrice, TenantCustomerRepository, } from "./stripe/index.js";

package/dist/monetization/index.js

@@ -50,10 +50,10 @@ export { withMargin, } from "./adapters/types.js";
 export { ArbitrageRouter, NoProviderAvailableError, ProviderRegistry, } from "./arbitrage/index.js";
 export { BudgetChecker, DrizzleBudgetChecker } from "./budget/index.js";
 export { BotBilling, buildResourceTierCosts, DAILY_BOT_COST, DrizzleBotBilling, DrizzleLedger, grantSignupCredits, InsufficientBalanceError, Ledger, runRuntimeDeductions, SIGNUP_GRANT, SUSPENSION_GRACE_DAYS, } from "./credits/index.js";
+export { BTCPayClient, CryptoChargeRepository, createCryptoCheckout, DrizzleCryptoChargeRepository, handleCryptoWebhook, loadCryptoConfig, MIN_PAYMENT_USD, mapBtcPayEventToStatus, verifyCryptoWebhookSignature, } from "./crypto/index.js";
 // Feature gating middleware (WOP-384 — replaced tier gates with balance gates)
 export { createBalanceGate, createCreditGate, createFeatureGate, } from "./feature-gate.js";
 export { DrizzleMeterAggregator, DrizzleMeterEmitter, MeterAggregator, MeterEmitter, } from "./metering/index.js";
-export { createPayRamCheckout, createPayRamClient, DrizzlePayRamChargeRepository, handlePayRamWebhook, loadPayRamConfig, MIN_PAYMENT_USD, PayRamChargeRepository, } from "./payram/index.js";
 export { checkInstanceQuota, DEFAULT_INSTANCE_LIMITS, } from "./quotas/quota-check.js";
 export { buildResourceLimits, DEFAULT_RESOURCE_CONFIG, } from "./quotas/resource-limits.js";
 // Socket layer — adapter orchestrator (WOP-376)

package/dist/monetization/repository-types.d.ts

@@ -1,4 +1,4 @@
-export type { IPayRamChargeRepository, ITenantCustomerRepository, PayRamChargeRecord, } from "@wopr-network/platform-core/billing";
+export type { CryptoChargeRecord, ICryptoChargeRepository, ITenantCustomerRepository, } from "@wopr-network/platform-core/billing";
 export type { IAutoTopupSettingsRepository, ILedger } from "@wopr-network/platform-core/credits";
 export type { IMeterAggregator, IMeterEmitter } from "@wopr-network/platform-core/metering";
 export type { FraudEvent, FraudEventInput, IAffiliateFraudRepository } from "./affiliate/affiliate-fraud-repository.js";

package/dist/observability/pagerduty.test.js

@@ -5,6 +5,7 @@ describe("PagerDutyNotifier", () => {
         vi.stubGlobal("fetch", vi.fn());
     });
     afterEach(() => {
+        vi.useRealTimers();
         vi.restoreAllMocks();
     });
     it("no-ops when disabled", async () => {

package/dist/security/key-validation.test.js

@@ -1,15 +1,20 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { PROVIDER_API_URLS } from "../config/provider-endpoints.js";
 import { PROVIDER_ENDPOINTS, validateProviderKey } from "./key-validation.js";
 describe("key-validation", () => {
     describe("PROVIDER_API_URLS", () => {
-        it("exports a URL for every supported provider", () => {
-            expect(PROVIDER_API_URLS.anthropic).toBe("https://api.anthropic.com/v1/models");
-            expect(PROVIDER_API_URLS.openai).toBe("https://api.openai.com/v1/models");
-            expect(PROVIDER_API_URLS.google).toBe("https://generativelanguage.googleapis.com/v1/models");
-            expect(PROVIDER_API_URLS.discord).toBe("https://discord.com/api/v10/users/@me");
-            expect(PROVIDER_API_URLS.elevenlabs).toBe("https://api.elevenlabs.io/v1/user");
-            expect(PROVIDER_API_URLS.deepgram).toBe("https://api.deepgram.com/v1/projects");
+        afterEach(() => {
+            vi.unstubAllEnvs();
+            vi.resetModules();
+        });
+        it("exports a URL for every supported provider", async () => {
+            vi.resetModules();
+            const { PROVIDER_API_URLS: urls } = await import("../config/provider-endpoints.js");
+            expect(urls.anthropic).toBe("https://api.anthropic.com/v1/models");
+            expect(urls.openai).toBe("https://api.openai.com/v1/models");
+            expect(urls.google).toBe("https://generativelanguage.googleapis.com/v1/models");
+            expect(urls.discord).toBe("https://discord.com/api/v10/users/@me");
+            expect(urls.elevenlabs).toBe("https://api.elevenlabs.io/v1/user");
+            expect(urls.deepgram).toBe("https://api.deepgram.com/v1/projects");
         });
     });
     describe("PROVIDER_ENDPOINTS", () => {
@@ -84,4 +89,56 @@ describe("key-validation", () => {
             }));
         });
     });
+    describe("PROVIDER_API_URLS env overrides", () => {
+        afterEach(() => {
+            vi.unstubAllEnvs();
+            vi.resetModules();
+        });
+        it("uses ANTHROPIC_API_URL when set", async () => {
+            vi.stubEnv("ANTHROPIC_API_URL", "https://custom-anthropic.example.com/v1/models");
+            vi.resetModules();
+            const { PROVIDER_API_URLS: urls } = await import("../config/provider-endpoints.js");
+            expect(urls.anthropic).toBe("https://custom-anthropic.example.com/v1/models");
+        });
+        it("uses OPENAI_API_URL when set", async () => {
+            vi.stubEnv("OPENAI_API_URL", "https://custom-openai.example.com/v1/models");
+            vi.resetModules();
+            const { PROVIDER_API_URLS: urls } = await import("../config/provider-endpoints.js");
+            expect(urls.openai).toBe("https://custom-openai.example.com/v1/models");
+        });
+        it("uses GOOGLE_API_URL when set", async () => {
+            vi.stubEnv("GOOGLE_API_URL", "https://custom-google.example.com/v1/models");
+            vi.resetModules();
+            const { PROVIDER_API_URLS: urls } = await import("../config/provider-endpoints.js");
+            expect(urls.google).toBe("https://custom-google.example.com/v1/models");
+        });
+        it("uses DISCORD_API_URL when set", async () => {
+            vi.stubEnv("DISCORD_API_URL", "https://custom-discord.example.com/api/v10/users/@me");
+            vi.resetModules();
+            const { PROVIDER_API_URLS: urls } = await import("../config/provider-endpoints.js");
+            expect(urls.discord).toBe("https://custom-discord.example.com/api/v10/users/@me");
+        });
+        it("uses ELEVENLABS_API_URL when set", async () => {
+            vi.stubEnv("ELEVENLABS_API_URL", "https://custom-elevenlabs.example.com/v1/user");
+            vi.resetModules();
+            const { PROVIDER_API_URLS: urls } = await import("../config/provider-endpoints.js");
+            expect(urls.elevenlabs).toBe("https://custom-elevenlabs.example.com/v1/user");
+        });
+        it("uses DEEPGRAM_API_URL when set", async () => {
+            vi.stubEnv("DEEPGRAM_API_URL", "https://custom-deepgram.example.com/v1/projects");
+            vi.resetModules();
+            const { PROVIDER_API_URLS: urls } = await import("../config/provider-endpoints.js");
+            expect(urls.deepgram).toBe("https://custom-deepgram.example.com/v1/projects");
+        });
+        it("falls back to defaults when env vars are not set", async () => {
+            vi.resetModules();
+            const { PROVIDER_API_URLS: urls } = await import("../config/provider-endpoints.js");
+            expect(urls.anthropic).toBe("https://api.anthropic.com/v1/models");
+            expect(urls.openai).toBe("https://api.openai.com/v1/models");
+            expect(urls.google).toBe("https://generativelanguage.googleapis.com/v1/models");
+            expect(urls.discord).toBe("https://discord.com/api/v10/users/@me");
+            expect(urls.elevenlabs).toBe("https://api.elevenlabs.io/v1/user");
+            expect(urls.deepgram).toBe("https://api.deepgram.com/v1/projects");
+        });
+    });
 });

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.7",
+  "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 };