@wopr-network/platform-core 1.14.7 → 1.15.0

package/dist/billing/payram/cents-credits-boundary.test.js

@@ -1,75 +0,0 @@
-import { describe, expect, it } from "vitest";
-/**
- * Regression tests for PayRam cents/credits boundary (WOP-1058).
- *
- * 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.
- */
-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)
-        const amountUsd = 25;
-        const amountUsdCents = Math.round(amountUsd * 100);
-        expect(amountUsdCents).toBe(2500);
-        // Must NOT be nanodollar scale
-        expect(amountUsdCents).toBeLessThan(1_000_000);
-    });
-    it("minimum payment amount converts to valid cents", () => {
-        const MIN_PAYMENT_USD = 10;
-        const cents = Math.round(MIN_PAYMENT_USD * 100);
-        expect(cents).toBe(1000);
-        expect(Number.isInteger(cents)).toBe(true);
-        // Sanity: $10 is 1000 cents, NOT 10_000_000_000 nanodollars
-        expect(cents).toBeLessThan(1_000_000);
-    });
-    it("fractional USD amounts round correctly to cents", () => {
-        // Edge case: floating point conversion
-        const amountUsd = 10.99;
-        const cents = Math.round(amountUsd * 100);
-        expect(cents).toBe(1099);
-        expect(cents).toBeLessThan(1_000_000);
-    });
-    it("amountUsdCents stored in charge record equals USD * 100 (not nanodollars)", () => {
-        // The core invariant: payram/checkout.ts stores Math.round(amountUsd * 100)
-        // as amountUsdCents. This test proves the conversion stays at cent scale.
-        const testCases = [
-            { usd: 10, expectedCents: 1000 },
-            { usd: 25, expectedCents: 2500 },
-            { usd: 50, expectedCents: 5000 },
-            { usd: 100, expectedCents: 10000 },
-        ];
-        for (const { usd, expectedCents } of testCases) {
-            const amountUsdCents = Math.round(usd * 100);
-            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.
-        const chargeAmountUsdCents = 2500; // $25.00
-        const creditCents = chargeAmountUsdCents; // 1:1 for PayRam
-        expect(creditCents).toBe(2500);
-        // creditedCents must be 2500 (cents), not 25_000_000_000 (nanodollars)
-        expect(creditCents).toBeLessThan(1_000_000);
-    });
-    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;
-        expect(NANODOLLARS_PER_CENT).toBe(10_000_000);
-        // $25 in cents = 2500. $25 in nanodollars = 25_000_000_000.
-        // These are 10_000_000x apart — confirming that mixing the two is catastrophic.
-        const twentyFiveDollarsInCents = 2500;
-        const twentyFiveDollarsInNanodollars = 25 * CREDIT_SCALE;
-        expect(twentyFiveDollarsInNanodollars / twentyFiveDollarsInCents).toBe(NANODOLLARS_PER_CENT);
-    });
-});

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

@@ -1,64 +0,0 @@
-import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
-import { beginTestTransaction, createTestDb, endTestTransaction, rollbackTestTransaction } from "../../test/db.js";
-import { PayRamChargeRepository } from "./charge-store.js";
-describe("PayRamChargeRepository", () => {
-    let pool;
-    let db;
-    let store;
-    beforeAll(async () => {
-        ({ db, pool } = await createTestDb());
-        await beginTestTransaction(pool);
-    });
-    afterAll(async () => {
-        await endTestTransaction(pool);
-        await pool.close();
-    });
-    beforeEach(async () => {
-        await rollbackTestTransaction(pool);
-        store = new PayRamChargeRepository(db);
-    });
-    it("create() stores a charge", async () => {
-        await store.create("ref-001", "tenant-1", 2500);
-        const charge = await store.getByReferenceId("ref-001");
-        expect(charge).not.toBeNull();
-        expect(charge?.referenceId).toBe("ref-001");
-        expect(charge?.tenantId).toBe("tenant-1");
-        expect(charge?.amountUsdCents).toBe(2500);
-        expect(charge?.status).toBe("OPEN");
-        expect(charge?.creditedAt).toBeNull();
-    });
-    it("getByReferenceId() returns null when not found", async () => {
-        const charge = await store.getByReferenceId("ref-nonexistent");
-        expect(charge).toBeNull();
-    });
-    it("updateStatus() updates status, currency and filled_amount", async () => {
-        await store.create("ref-002", "tenant-2", 5000);
-        await store.updateStatus("ref-002", "FILLED", "USDC", "50.00");
-        const charge = await store.getByReferenceId("ref-002");
-        expect(charge?.status).toBe("FILLED");
-        expect(charge?.currency).toBe("USDC");
-        expect(charge?.filledAmount).toBe("50.00");
-    });
-    it("updateStatus() handles partial updates (no currency)", async () => {
-        await store.create("ref-003", "tenant-3", 1000);
-        await store.updateStatus("ref-003", "VERIFYING");
-        const charge = await store.getByReferenceId("ref-003");
-        expect(charge?.status).toBe("VERIFYING");
-        expect(charge?.currency).toBeNull();
-    });
-    it("isCredited() returns false before markCredited", async () => {
-        await store.create("ref-004", "tenant-4", 1500);
-        expect(await store.isCredited("ref-004")).toBe(false);
-    });
-    it("markCredited() sets creditedAt", async () => {
-        await store.create("ref-005", "tenant-5", 3000);
-        await store.markCredited("ref-005");
-        const charge = await store.getByReferenceId("ref-005");
-        expect(charge?.creditedAt).not.toBeNull();
-    });
-    it("isCredited() returns true after markCredited", async () => {
-        await store.create("ref-006", "tenant-6", 2000);
-        await store.markCredited("ref-006");
-        expect(await store.isCredited("ref-006")).toBe(true);
-    });
-});

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

@@ -1,15 +0,0 @@
-import type { Payram } from "payram";
-import type { PayRamChargeRepository } from "./charge-store.js";
-import type { PayRamCheckoutOpts } from "./types.js";
-/** Minimum payment amount in USD. */
-export declare const MIN_PAYMENT_USD = 10;
-/**
- * Create a PayRam payment session and store the charge record.
- *
- * Returns the PayRam-hosted payment page URL and reference ID.
- * The user is redirected to this URL to complete the crypto payment.
- */
-export declare function createPayRamCheckout(payram: Payram, chargeStore: PayRamChargeRepository, opts: PayRamCheckoutOpts): Promise<{
-    referenceId: string;
-    url: string;
-}>;

package/dist/billing/payram/checkout.js

@@ -1,24 +0,0 @@
-/** Minimum payment amount in USD. */
-export const MIN_PAYMENT_USD = 10;
-/**
- * Create a PayRam payment session and store the charge record.
- *
- * Returns the PayRam-hosted payment page URL and reference ID.
- * The user is redirected to this URL to complete the crypto payment.
- */
-export async function createPayRamCheckout(payram, chargeStore, opts) {
-    if (opts.amountUsd < MIN_PAYMENT_USD) {
-        throw new Error(`Minimum payment amount is $${MIN_PAYMENT_USD}`);
-    }
-    const result = await payram.payments.initiatePayment({
-        customerEmail: `${opts.tenant}@${process.env.PLATFORM_DOMAIN ?? "wopr.bot"}`,
-        customerId: opts.tenant,
-        amountInUSD: opts.amountUsd,
-    });
-    // Store the charge record for webhook correlation.
-    await chargeStore.create(result.reference_id, opts.tenant, Math.round(opts.amountUsd * 100));
-    return {
-        referenceId: result.reference_id,
-        url: result.url,
-    };
-}

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

@@ -1,74 +0,0 @@
-import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
-import { beginTestTransaction, createTestDb, endTestTransaction, rollbackTestTransaction } from "../../test/db.js";
-import { PayRamChargeRepository } from "./charge-store.js";
-import { createPayRamCheckout, MIN_PAYMENT_USD } from "./checkout.js";
-function createMockPayram(overrides = {}) {
-    return {
-        payments: {
-            initiatePayment: overrides.initiatePayment ??
-                vi.fn().mockResolvedValue({
-                    reference_id: "ref-mock-001",
-                    url: "https://payram.example.com/pay/ref-mock-001",
-                }),
-        },
-    };
-}
-describe("createPayRamCheckout", () => {
-    let pool;
-    let db;
-    let chargeStore;
-    let payram;
-    beforeAll(async () => {
-        ({ db, pool } = await createTestDb());
-        await beginTestTransaction(pool);
-    });
-    afterAll(async () => {
-        await endTestTransaction(pool);
-        await pool.close();
-    });
-    beforeEach(async () => {
-        await rollbackTestTransaction(pool);
-        chargeStore = new PayRamChargeRepository(db);
-        payram = createMockPayram();
-    });
-    it("rejects amounts below $10 minimum", async () => {
-        await expect(createPayRamCheckout(payram, chargeStore, { tenant: "t-1", amountUsd: 5 })).rejects.toThrow(`Minimum payment amount is $${MIN_PAYMENT_USD}`);
-    });
-    it("rejects amounts of exactly $0", async () => {
-        await expect(createPayRamCheckout(payram, chargeStore, { tenant: "t-1", amountUsd: 0 })).rejects.toThrow();
-    });
-    it("calls payram.payments.initiatePayment with correct params", async () => {
-        const initiatePayment = vi.fn().mockResolvedValue({
-            reference_id: "ref-abc",
-            url: "https://payram.example.com/pay/ref-abc",
-        });
-        const mockPayram = createMockPayram({ initiatePayment });
-        await createPayRamCheckout(mockPayram, chargeStore, { tenant: "t-test", amountUsd: 25 });
-        expect(initiatePayment).toHaveBeenCalledWith({
-            customerEmail: "t-test@wopr.bot",
-            customerId: "t-test",
-            amountInUSD: 25,
-        });
-    });
-    it("stores the charge with correct amountUsdCents (converts from USD)", async () => {
-        const initiatePayment = vi.fn().mockResolvedValue({
-            reference_id: "ref-store-test",
-            url: "https://payram.example.com/pay/ref-store-test",
-        });
-        const mockPayram = createMockPayram({ initiatePayment });
-        await createPayRamCheckout(mockPayram, chargeStore, { tenant: "t-2", amountUsd: 25 });
-        const charge = await chargeStore.getByReferenceId("ref-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("OPEN");
-    });
-    it("returns referenceId and url from PayRam response", async () => {
-        const result = await createPayRamCheckout(payram, chargeStore, { tenant: "t-3", amountUsd: 10 });
-        expect(result.referenceId).toBe("ref-mock-001");
-        expect(result.url).toBe("https://payram.example.com/pay/ref-mock-001");
-    });
-    it("accepts exactly $10 (minimum boundary)", async () => {
-        await expect(createPayRamCheckout(payram, chargeStore, { tenant: "t-4", amountUsd: 10 })).resolves.not.toBeNull();
-    });
-});

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

@@ -1,7 +0,0 @@
-import { Payram } from "payram";
-export interface PayRamConfig {
-    apiKey: string;
-    baseUrl: string;
-}
-export declare function createPayRamClient(config: PayRamConfig): Payram;
-export declare function loadPayRamConfig(): PayRamConfig | null;

package/dist/billing/payram/client.js

@@ -1,15 +0,0 @@
-import { Payram } from "payram";
-export function createPayRamClient(config) {
-    return new Payram({
-        apiKey: config.apiKey,
-        baseUrl: config.baseUrl,
-        config: { timeoutMs: 30_000, maxRetries: 2, retryPolicy: "safe" },
-    });
-}
-export function loadPayRamConfig() {
-    const apiKey = process.env.PAYRAM_API_KEY;
-    const baseUrl = process.env.PAYRAM_BASE_URL;
-    if (!apiKey || !baseUrl)
-        return null;
-    return { apiKey, baseUrl };
-}

package/dist/billing/payram/client.test.js

@@ -1,52 +0,0 @@
-import { Payram } from "payram";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { createPayRamClient, loadPayRamConfig } from "./client.js";
-describe("createPayRamClient", () => {
-    it("returns a Payram instance", () => {
-        const client = createPayRamClient({ apiKey: "test-key", baseUrl: "https://api.payram.test" });
-        expect(client).toBeInstanceOf(Payram);
-    });
-    it("passes config through to the Payram constructor", () => {
-        const client = createPayRamClient({ apiKey: "pk_live_123", baseUrl: "https://api.payram.io" });
-        expect(client).toBeInstanceOf(Payram);
-    });
-});
-describe("loadPayRamConfig", () => {
-    beforeEach(() => {
-        delete process.env.PAYRAM_API_KEY;
-        delete process.env.PAYRAM_BASE_URL;
-    });
-    afterEach(() => {
-        vi.unstubAllEnvs();
-    });
-    it("returns null when PAYRAM_API_KEY is missing", () => {
-        vi.stubEnv("PAYRAM_BASE_URL", "https://api.payram.test");
-        expect(loadPayRamConfig()).toBeNull();
-    });
-    it("returns null when PAYRAM_BASE_URL is missing", () => {
-        vi.stubEnv("PAYRAM_API_KEY", "pk_test_123");
-        expect(loadPayRamConfig()).toBeNull();
-    });
-    it("returns null when PAYRAM_API_KEY is an empty string", () => {
-        vi.stubEnv("PAYRAM_API_KEY", "");
-        vi.stubEnv("PAYRAM_BASE_URL", "https://api.payram.test");
-        expect(loadPayRamConfig()).toBeNull();
-    });
-    it("returns null when PAYRAM_BASE_URL is an empty string", () => {
-        vi.stubEnv("PAYRAM_API_KEY", "pk_test_123");
-        vi.stubEnv("PAYRAM_BASE_URL", "");
-        expect(loadPayRamConfig()).toBeNull();
-    });
-    it("returns config when both env vars are set", () => {
-        vi.stubEnv("PAYRAM_API_KEY", "pk_test_123");
-        vi.stubEnv("PAYRAM_BASE_URL", "https://api.payram.test");
-        const config = loadPayRamConfig();
-        expect(config).toEqual({
-            apiKey: "pk_test_123",
-            baseUrl: "https://api.payram.test",
-        });
-    });
-    it("returns null when both env vars are missing", () => {
-        expect(loadPayRamConfig()).toBeNull();
-    });
-});

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

@@ -1,8 +0,0 @@
-export type { IPayRamChargeRepository, PayRamChargeRecord } from "./charge-store.js";
-export { DrizzlePayRamChargeRepository, PayRamChargeRepository } from "./charge-store.js";
-export { createPayRamCheckout, MIN_PAYMENT_USD } from "./checkout.js";
-export type { PayRamConfig } from "./client.js";
-export { createPayRamClient, loadPayRamConfig } from "./client.js";
-export type { PayRamBillingConfig, PayRamCheckoutOpts, PayRamPaymentState, PayRamWebhookPayload, PayRamWebhookResult, } from "./types.js";
-export type { PayRamWebhookDeps } from "./webhook.js";
-export { handlePayRamWebhook } from "./webhook.js";

package/dist/billing/payram/index.js

@@ -1,4 +0,0 @@
-export { DrizzlePayRamChargeRepository, PayRamChargeRepository } from "./charge-store.js";
-export { createPayRamCheckout, MIN_PAYMENT_USD } from "./checkout.js";
-export { createPayRamClient, loadPayRamConfig } from "./client.js";
-export { handlePayRamWebhook } from "./webhook.js";

package/dist/billing/payram/types.d.ts

@@ -1,40 +0,0 @@
-/** PayRam payment states (from PayRam API docs). */
-export type PayRamPaymentState = "OPEN" | "VERIFYING" | "FILLED" | "OVER_FILLED" | "PARTIALLY_FILLED" | "CANCELLED";
-/** Options for creating a PayRam payment session. */
-export interface PayRamCheckoutOpts {
-    /** Internal tenant ID. */
-    tenant: string;
-    /** Amount in USD (minimum $10). */
-    amountUsd: number;
-}
-/** Webhook payload received from PayRam. */
-export interface PayRamWebhookPayload {
-    /** Unique payment reference from session creation. */
-    reference_id: string;
-    /** Merchant invoice ID (echoed back if sent). */
-    invoice_id?: string;
-    /** Payment status. */
-    status: PayRamPaymentState;
-    /** Amount filled in this update. */
-    amount: string;
-    /** Currency symbol (ETH, USDC, USDT, etc.). */
-    currency: string;
-    /** Cumulative total filled so far. */
-    filled_amount: string;
-}
-/** Configuration for PayRam billing integration. */
-export interface PayRamBillingConfig {
-    /** PayRam API key (from dashboard). */
-    apiKey: string;
-    /** PayRam self-hosted server base URL. */
-    baseUrl: string;
-}
-/** Result of processing a PayRam webhook event. */
-export interface PayRamWebhookResult {
-    handled: boolean;
-    status: string;
-    tenant?: string;
-    creditedCents?: number;
-    reactivatedBots?: string[];
-    duplicate?: boolean;
-}

package/dist/billing/payram/webhook.d.ts

@@ -1,19 +0,0 @@
-import type { ILedger } from "../../credits/ledger.js";
-import type { IWebhookSeenRepository } from "../webhook-seen-repository.js";
-import type { PayRamChargeRepository } from "./charge-store.js";
-import type { PayRamWebhookPayload, PayRamWebhookResult } from "./types.js";
-export interface PayRamWebhookDeps {
-    chargeStore: PayRamChargeRepository;
-    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[]>;
-}
-/**
- * Process a PayRam webhook event.
- *
- * Only credits the ledger on FILLED or OVER_FILLED status.
- * Uses the PayRam reference_id mapped to the stored charge record
- * for tenant resolution and idempotency.
- */
-export declare function handlePayRamWebhook(deps: PayRamWebhookDeps, payload: PayRamWebhookPayload): Promise<PayRamWebhookResult>;

package/dist/billing/payram/webhook.js

@@ -1,71 +0,0 @@
-import { Credit } from "../../credits/credit.js";
-/**
- * Process a PayRam webhook event.
- *
- * Only credits the ledger on FILLED or OVER_FILLED status.
- * Uses the PayRam reference_id mapped to the stored charge record
- * for tenant resolution and idempotency.
- */
-export async function handlePayRamWebhook(deps, payload) {
-    const { chargeStore, creditLedger } = deps;
-    // Replay guard: deduplicate by reference_id + status combination.
-    const dedupeKey = `${payload.reference_id}:${payload.status}`;
-    if (await deps.replayGuard.isDuplicate(dedupeKey, "payram")) {
-        return { handled: true, status: payload.status, duplicate: true };
-    }
-    // Look up the charge record to find the tenant.
-    const charge = await chargeStore.getByReferenceId(payload.reference_id);
-    if (!charge) {
-        return { handled: false, status: payload.status };
-    }
-    // Update charge status regardless of payment state.
-    await chargeStore.updateStatus(payload.reference_id, payload.status, payload.currency, payload.filled_amount);
-    let result;
-    if (payload.status === "FILLED" || payload.status === "OVER_FILLED") {
-        // Idempotency: skip if already credited.
-        if (await chargeStore.isCredited(payload.reference_id)) {
-            result = {
-                handled: true,
-                status: payload.status,
-                tenant: charge.tenantId,
-                creditedCents: 0,
-            };
-        }
-        else {
-            // Credit the original USD amount requested (not the crypto amount).
-            // For OVER_FILLED, we still credit the requested amount — the
-            // overpayment stays in the PayRam wallet as a buffer.
-            const creditCents = charge.amountUsdCents;
-            await creditLedger.credit(charge.tenantId, Credit.fromCents(creditCents), "purchase", {
-                description: `Crypto credit purchase via PayRam (ref: ${payload.reference_id}, ${payload.currency ?? "crypto"})`,
-                referenceId: `payram:${payload.reference_id}`,
-                fundingSource: "payram",
-            });
-            await chargeStore.markCredited(payload.reference_id);
-            // 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: payload.status,
-                tenant: charge.tenantId,
-                creditedCents: creditCents,
-                reactivatedBots,
-            };
-        }
-    }
-    else {
-        // OPEN, VERIFYING, PARTIALLY_FILLED, CANCELLED — just track status.
-        result = {
-            handled: true,
-            status: payload.status,
-            tenant: charge.tenantId,
-        };
-    }
-    await deps.replayGuard.markSeen(dedupeKey, "payram");
-    return result;
-}

package/dist/billing/payram/webhook.test.d.ts

@@ -1,7 +0,0 @@
-/**
- * Unit tests for PayRam webhook handler (WOP-407).
- *
- * Covers FILLED/OVER_FILLED crediting the ledger, PARTIALLY_FILLED/CANCELLED
- * no-op status, idempotency, replay guard, and bot reactivation.
- */
-export {};