@wopr-network/platform-core 1.14.8 → 1.16.0

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

@@ -0,0 +1,57 @@
+import { Credit } from "../../../credits/credit.js";
+import { deriveDepositAddress } from "./address-gen.js";
+import { getTokenConfig, tokenAmountFromCents } from "./config.js";
+export const MIN_STABLECOIN_USD = 10;
+/**
+ * Create a stablecoin checkout — derive a unique deposit address, store the charge.
+ *
+ * Race safety: the unique constraint on derivation_index prevents two concurrent
+ * checkouts from claiming the same index. On conflict, we retry with the next index.
+ *
+ * CRITICAL: amountUsd is converted to integer cents via Credit.fromDollars().toCentsRounded().
+ * The charge store holds USD cents (integer). Credit.fromCents() handles the
+ * cents → nanodollars conversion when crediting the ledger in the settler.
+ */
+export async function createStablecoinCheckout(deps, opts) {
+    if (!Number.isFinite(opts.amountUsd) || opts.amountUsd < MIN_STABLECOIN_USD) {
+        throw new Error(`Minimum payment amount is $${MIN_STABLECOIN_USD}`);
+    }
+    const tokenCfg = getTokenConfig(opts.token, opts.chain);
+    // Convert dollars to integer cents via Credit (no floating point in billing path).
+    const amountUsdCents = Credit.fromDollars(opts.amountUsd).toCentsRounded();
+    const rawAmount = tokenAmountFromCents(amountUsdCents, tokenCfg.decimals);
+    const maxRetries = 3;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        const derivationIndex = await deps.chargeStore.getNextDerivationIndex();
+        const depositAddress = deriveDepositAddress(deps.xpub, derivationIndex);
+        const referenceId = `sc:${opts.chain}:${opts.token.toLowerCase()}:${depositAddress.toLowerCase()}`;
+        try {
+            await deps.chargeStore.createStablecoinCharge({
+                referenceId,
+                tenantId: opts.tenant,
+                amountUsdCents,
+                chain: opts.chain,
+                token: opts.token,
+                depositAddress: depositAddress.toLowerCase(),
+                derivationIndex,
+            });
+            return {
+                depositAddress,
+                amountRaw: rawAmount.toString(),
+                amountUsd: opts.amountUsd,
+                chain: opts.chain,
+                token: opts.token,
+                referenceId,
+            };
+        }
+        catch (err) {
+            // Unique constraint violation = another checkout claimed this index concurrently.
+            // Retry with the next available index.
+            const msg = err instanceof Error ? err.message : "";
+            const isConflict = msg.includes("unique") || msg.includes("duplicate") || msg.includes("23505");
+            if (!isConflict || attempt === maxRetries)
+                throw err;
+        }
+    }
+    throw new Error("Failed to claim derivation index after retries");
+}

package/dist/billing/crypto/evm/config.d.ts

@@ -0,0 +1,13 @@
+import type { ChainConfig, EvmChain, StablecoinToken, TokenConfig } from "./types.js";
+export declare function getChainConfig(chain: EvmChain): ChainConfig;
+export declare function getTokenConfig(token: StablecoinToken, chain: EvmChain): TokenConfig;
+/**
+ * Convert USD cents (integer) to token raw amount (BigInt).
+ * Stablecoins are 1:1 USD. Integer math only.
+ */
+export declare function tokenAmountFromCents(cents: number, decimals: number): bigint;
+/**
+ * Convert token raw amount (BigInt) to USD cents (integer).
+ * Truncates fractional cents.
+ */
+export declare function centsFromTokenAmount(rawAmount: bigint, decimals: number): number;

package/dist/billing/crypto/evm/config.js

@@ -0,0 +1,46 @@
+const CHAINS = {
+    base: {
+        chain: "base",
+        rpcUrl: process.env.EVM_RPC_BASE ?? "http://op-geth:8545",
+        confirmations: 1,
+        blockTimeMs: 2000,
+        chainId: 8453,
+    },
+};
+const TOKENS = {
+    "USDC:base": {
+        token: "USDC",
+        chain: "base",
+        contractAddress: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+        decimals: 6,
+    },
+};
+export function getChainConfig(chain) {
+    const cfg = CHAINS[chain];
+    if (!cfg)
+        throw new Error(`Unsupported chain: ${chain}`);
+    return cfg;
+}
+export function getTokenConfig(token, chain) {
+    const key = `${token}:${chain}`;
+    const cfg = TOKENS[key];
+    if (!cfg)
+        throw new Error(`Unsupported token ${token} on ${chain}`);
+    return cfg;
+}
+/**
+ * Convert USD cents (integer) to token raw amount (BigInt).
+ * Stablecoins are 1:1 USD. Integer math only.
+ */
+export function tokenAmountFromCents(cents, decimals) {
+    if (!Number.isInteger(cents))
+        throw new Error("cents must be an integer");
+    return (BigInt(cents) * 10n ** BigInt(decimals)) / 100n;
+}
+/**
+ * Convert token raw amount (BigInt) to USD cents (integer).
+ * Truncates fractional cents.
+ */
+export function centsFromTokenAmount(rawAmount, decimals) {
+    return Number((rawAmount * 100n) / 10n ** BigInt(decimals));
+}

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

@@ -0,0 +1,9 @@
+export { deriveDepositAddress, isValidXpub } from "./address-gen.js";
+export type { StablecoinCheckoutDeps, StablecoinCheckoutResult } from "./checkout.js";
+export { createStablecoinCheckout, MIN_STABLECOIN_USD } from "./checkout.js";
+export { centsFromTokenAmount, getChainConfig, getTokenConfig, tokenAmountFromCents } from "./config.js";
+export type { EvmSettlerDeps } from "./settler.js";
+export { settleEvmPayment } from "./settler.js";
+export type { ChainConfig, EvmChain, EvmPaymentEvent, StablecoinCheckoutOpts, StablecoinToken, TokenConfig, } from "./types.js";
+export type { EvmWatcherOpts } from "./watcher.js";
+export { createRpcCaller, EvmWatcher } from "./watcher.js";

package/dist/billing/crypto/evm/index.js

@@ -0,0 +1,5 @@
+export { deriveDepositAddress, isValidXpub } from "./address-gen.js";
+export { createStablecoinCheckout, MIN_STABLECOIN_USD } from "./checkout.js";
+export { centsFromTokenAmount, getChainConfig, getTokenConfig, tokenAmountFromCents } from "./config.js";
+export { settleEvmPayment } from "./settler.js";
+export { createRpcCaller, EvmWatcher } from "./watcher.js";

package/dist/billing/crypto/evm/settler.d.ts

@@ -0,0 +1,23 @@
+import type { ILedger } from "../../../credits/ledger.js";
+import type { ICryptoChargeRepository } from "../charge-store.js";
+import type { CryptoWebhookResult } from "../types.js";
+import type { EvmPaymentEvent } from "./types.js";
+export interface EvmSettlerDeps {
+    chargeStore: Pick<ICryptoChargeRepository, "getByDepositAddress" | "updateStatus" | "markCredited">;
+    creditLedger: Pick<ILedger, "credit" | "hasReferenceId">;
+    onCreditsPurchased?: (tenantId: string, ledger: ILedger) => Promise<string[]>;
+}
+/**
+ * Settle an EVM payment event — look up charge by deposit address, credit ledger.
+ *
+ * Same idempotency pattern as handleCryptoWebhook():
+ *   Primary: creditLedger.hasReferenceId() — atomic in ledger transaction
+ *   Secondary: chargeStore.markCredited() — advisory
+ *
+ * Credits the CHARGE amount (not the transfer amount) for overpayment safety.
+ *
+ * CRITICAL: charge.amountUsdCents is in 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 settleEvmPayment(deps: EvmSettlerDeps, event: EvmPaymentEvent): Promise<CryptoWebhookResult>;

package/dist/billing/crypto/evm/settler.js

@@ -0,0 +1,60 @@
+import { Credit } from "../../../credits/credit.js";
+/**
+ * Settle an EVM payment event — look up charge by deposit address, credit ledger.
+ *
+ * Same idempotency pattern as handleCryptoWebhook():
+ *   Primary: creditLedger.hasReferenceId() — atomic in ledger transaction
+ *   Secondary: chargeStore.markCredited() — advisory
+ *
+ * Credits the CHARGE amount (not the transfer amount) for overpayment safety.
+ *
+ * CRITICAL: charge.amountUsdCents is in 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 settleEvmPayment(deps, event) {
+    const { chargeStore, creditLedger } = deps;
+    const charge = await chargeStore.getByDepositAddress(event.to.toLowerCase());
+    if (!charge) {
+        return { handled: false, status: "Settled" };
+    }
+    // Update charge status to Settled.
+    await chargeStore.updateStatus(charge.referenceId, "Settled");
+    // Charge-level idempotency: if this charge was already credited (by any transfer),
+    // reject. Prevents double-credit when a user sends two transactions to the same address.
+    if (charge.creditedAt != null) {
+        return { handled: true, status: "Settled", tenant: charge.tenantId, creditedCents: 0 };
+    }
+    // Transfer-level idempotency: if this specific tx was already processed, skip.
+    const creditRef = `evm:${event.chain}:${event.txHash}:${event.logIndex}`;
+    if (await creditLedger.hasReferenceId(creditRef)) {
+        return { handled: true, status: "Settled", tenant: charge.tenantId, creditedCents: 0 };
+    }
+    // Reject underpayment — transfer must cover the charge amount.
+    if (event.amountUsdCents < charge.amountUsdCents) {
+        return { handled: true, status: "Settled", tenant: charge.tenantId, creditedCents: 0 };
+    }
+    // Credit the CHARGE amount (NOT the transfer amount — overpayment stays in wallet).
+    // 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: `Stablecoin credit purchase (${event.token} on ${event.chain}, tx: ${event.txHash})`,
+        referenceId: creditRef,
+        fundingSource: "crypto",
+    });
+    await chargeStore.markCredited(charge.referenceId);
+    let reactivatedBots;
+    if (deps.onCreditsPurchased) {
+        reactivatedBots = await deps.onCreditsPurchased(charge.tenantId, creditLedger);
+        if (reactivatedBots.length === 0)
+            reactivatedBots = undefined;
+    }
+    return {
+        handled: true,
+        status: "Settled",
+        tenant: charge.tenantId,
+        creditedCents: creditCents,
+        reactivatedBots,
+    };
+}

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

@@ -0,0 +1,40 @@
+/** Supported EVM chains. */
+export type EvmChain = "base";
+/** Supported stablecoin tokens. */
+export type StablecoinToken = "USDC";
+/** Chain configuration. */
+export interface ChainConfig {
+    readonly chain: EvmChain;
+    readonly rpcUrl: string;
+    readonly confirmations: number;
+    readonly blockTimeMs: number;
+    readonly chainId: number;
+}
+/** Token configuration on a specific chain. */
+export interface TokenConfig {
+    readonly token: StablecoinToken;
+    readonly chain: EvmChain;
+    readonly contractAddress: `0x${string}`;
+    readonly decimals: number;
+}
+/** Event emitted when a Transfer is detected and confirmed. */
+export interface EvmPaymentEvent {
+    readonly chain: EvmChain;
+    readonly token: StablecoinToken;
+    readonly from: string;
+    readonly to: string;
+    /** Raw token amount (BigInt as string for serialization). */
+    readonly rawAmount: string;
+    /** USD cents equivalent (integer). */
+    readonly amountUsdCents: number;
+    readonly txHash: string;
+    readonly blockNumber: number;
+    readonly logIndex: number;
+}
+/** Options for creating a stablecoin checkout. */
+export interface StablecoinCheckoutOpts {
+    tenant: string;
+    amountUsd: number;
+    chain: EvmChain;
+    token: StablecoinToken;
+}

package/dist/billing/crypto/evm/types.js

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

package/dist/billing/crypto/evm/watcher.d.ts

@@ -0,0 +1,31 @@
+import type { EvmChain, EvmPaymentEvent, StablecoinToken } from "./types.js";
+type RpcCall = (method: string, params: unknown[]) => Promise<unknown>;
+export interface EvmWatcherOpts {
+    chain: EvmChain;
+    token: StablecoinToken;
+    rpcCall: RpcCall;
+    fromBlock: number;
+    onPayment: (event: EvmPaymentEvent) => void | Promise<void>;
+    /** Active deposit addresses to watch. Filters eth_getLogs by topic[2] (to address). */
+    watchedAddresses?: string[];
+}
+export declare class EvmWatcher {
+    private _cursor;
+    private readonly chain;
+    private readonly token;
+    private readonly rpc;
+    private readonly onPayment;
+    private readonly confirmations;
+    private readonly contractAddress;
+    private readonly decimals;
+    private _watchedAddresses;
+    constructor(opts: EvmWatcherOpts);
+    /** Update the set of watched deposit addresses (e.g. after a new checkout). */
+    setWatchedAddresses(addresses: string[]): void;
+    get cursor(): number;
+    /** Poll for new Transfer events. Call on an interval. */
+    poll(): Promise<void>;
+}
+/** Create an RPC caller for a given URL (plain JSON-RPC over fetch). */
+export declare function createRpcCaller(rpcUrl: string): RpcCall;
+export {};

package/dist/billing/crypto/evm/watcher.js

@@ -0,0 +1,91 @@
+import { centsFromTokenAmount, getChainConfig, getTokenConfig } from "./config.js";
+const TRANSFER_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
+export class EvmWatcher {
+    _cursor;
+    chain;
+    token;
+    rpc;
+    onPayment;
+    confirmations;
+    contractAddress;
+    decimals;
+    _watchedAddresses;
+    constructor(opts) {
+        this.chain = opts.chain;
+        this.token = opts.token;
+        this.rpc = opts.rpcCall;
+        this._cursor = opts.fromBlock;
+        this.onPayment = opts.onPayment;
+        this._watchedAddresses = (opts.watchedAddresses ?? []).map((a) => a.toLowerCase());
+        const chainCfg = getChainConfig(opts.chain);
+        const tokenCfg = getTokenConfig(opts.token, opts.chain);
+        this.confirmations = chainCfg.confirmations;
+        this.contractAddress = tokenCfg.contractAddress.toLowerCase();
+        this.decimals = tokenCfg.decimals;
+    }
+    /** Update the set of watched deposit addresses (e.g. after a new checkout). */
+    setWatchedAddresses(addresses) {
+        this._watchedAddresses = addresses.map((a) => a.toLowerCase());
+    }
+    get cursor() {
+        return this._cursor;
+    }
+    /** Poll for new Transfer events. Call on an interval. */
+    async poll() {
+        const latestHex = (await this.rpc("eth_blockNumber", []));
+        const latest = Number.parseInt(latestHex, 16);
+        const confirmed = latest - this.confirmations;
+        if (confirmed < this._cursor)
+            return;
+        // Filter by topic[2] (to address) when watched addresses are set.
+        // This avoids fetching ALL USDC transfers on the chain (millions/day on Base).
+        // topic[2] values are 32-byte zero-padded: 0x000000000000000000000000<address>
+        const toFilter = this._watchedAddresses.length > 0
+            ? this._watchedAddresses.map((a) => `0x000000000000000000000000${a.slice(2)}`)
+            : null;
+        const logs = (await this.rpc("eth_getLogs", [
+            {
+                address: this.contractAddress,
+                topics: [TRANSFER_TOPIC, null, toFilter],
+                fromBlock: `0x${this._cursor.toString(16)}`,
+                toBlock: `0x${confirmed.toString(16)}`,
+            },
+        ]));
+        for (const log of logs) {
+            const to = `0x${log.topics[2].slice(26)}`.toLowerCase();
+            const from = `0x${log.topics[1].slice(26)}`.toLowerCase();
+            const rawAmount = BigInt(log.data);
+            const amountUsdCents = centsFromTokenAmount(rawAmount, this.decimals);
+            const event = {
+                chain: this.chain,
+                token: this.token,
+                from,
+                to,
+                rawAmount: rawAmount.toString(),
+                amountUsdCents,
+                txHash: log.transactionHash,
+                blockNumber: Number.parseInt(log.blockNumber, 16),
+                logIndex: Number.parseInt(log.logIndex, 16),
+            };
+            await this.onPayment(event);
+        }
+        this._cursor = confirmed + 1;
+    }
+}
+/** Create an RPC caller for a given URL (plain JSON-RPC over fetch). */
+export function createRpcCaller(rpcUrl) {
+    let id = 0;
+    return async (method, params) => {
+        const res = await fetch(rpcUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ jsonrpc: "2.0", id: ++id, method, params }),
+        });
+        if (!res.ok)
+            throw new Error(`RPC ${method} failed: ${res.status}`);
+        const data = (await res.json());
+        if (data.error)
+            throw new Error(`RPC ${method} error: ${data.error.message}`);
+        return data.result;
+    };
+}

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

@@ -0,0 +1,10 @@
+export type { CryptoChargeRecord, ICryptoChargeRepository, StablecoinChargeInput } 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 * from "./evm/index.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,6 @@
+export { CryptoChargeRepository, DrizzleCryptoChargeRepository } from "./charge-store.js";
+export { createCryptoCheckout, MIN_PAYMENT_USD } from "./checkout.js";
+export { BTCPayClient, loadCryptoConfig } from "./client.js";
+export * from "./evm/index.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.d.ts

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