@wopr-network/platform-core 1.14.7 → 1.15.0

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();
+  });
+});

package/src/billing/crypto/client.ts

@@ -0,0 +1,86 @@
+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 class BTCPayClient {
+  constructor(private readonly config: CryptoBillingConfig) {}
+
+  private headers(): Record<string, string> {
+    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: {
+    amountUsd: number;
+    orderId: string;
+    buyerEmail?: string;
+    redirectURL?: string;
+  }): Promise<{ id: string; checkoutLink: string }> {
+    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()) as { id: string; checkoutLink: string };
+    return { id: data.id, checkoutLink: data.checkoutLink };
+  }
+
+  /** Get invoice status by ID. */
+  async getInvoice(invoiceId: string): Promise<{ id: string; status: string; amount: string; currency: string }> {
+    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()) as { id: string; status: string; amount: string; currency: string };
+  }
+}
+
+/**
+ * Load BTCPay config from environment variables.
+ * Returns null if any required var is missing.
+ */
+export function loadCryptoConfig(): CryptoBillingConfig | null {
+  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 };
+}

package/src/billing/crypto/index.ts

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

package/src/billing/crypto/types.ts

@@ -0,0 +1,83 @@
+/** 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 function mapBtcPayEventToStatus(eventType: string): CryptoPaymentState {
+  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}`);
+  }
+}