@wopr-network/platform-core 0.1.0

package/dist/billing/payram/charge-store.d.ts

@@ -0,0 +1,41 @@
+import type { PlatformDb } from "../../db/index.js";
+import type { PayRamPaymentState } from "./types.js";
+export interface PayRamChargeRecord {
+    referenceId: string;
+    tenantId: string;
+    amountUsdCents: number;
+    status: string;
+    currency: string | null;
+    filledAmount: string | null;
+    creditedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface IPayRamChargeRepository {
+    create(referenceId: string, tenantId: string, amountUsdCents: number): Promise<void>;
+    getByReferenceId(referenceId: string): Promise<PayRamChargeRecord | null>;
+    updateStatus(referenceId: string, status: PayRamPaymentState, currency?: string, filledAmount?: string): Promise<void>;
+    markCredited(referenceId: string): Promise<void>;
+    isCredited(referenceId: string): Promise<boolean>;
+}
+/**
+ * Manages PayRam charge records in PostgreSQL.
+ *
+ * Each charge maps a PayRam reference_id to a tenant and tracks
+ * the payment lifecycle (OPEN -> VERIFYING -> FILLED/CANCELLED).
+ */
+export declare class DrizzlePayRamChargeRepository implements IPayRamChargeRepository {
+    private readonly db;
+    constructor(db: PlatformDb);
+    /** Create a new charge record when a payment session is initiated. */
+    create(referenceId: string, tenantId: string, amountUsdCents: number): Promise<void>;
+    /** Get a charge by reference ID. Returns null if not found. */
+    getByReferenceId(referenceId: string): Promise<PayRamChargeRecord | null>;
+    /** Update charge status and payment details from webhook. */
+    updateStatus(referenceId: string, status: PayRamPaymentState, currency?: string, filledAmount?: string): Promise<void>;
+    /** Mark a charge as credited (idempotency flag). */
+    markCredited(referenceId: string): Promise<void>;
+    /** Check if a charge has already been credited (for idempotency). */
+    isCredited(referenceId: string): Promise<boolean>;
+}
+export { DrizzlePayRamChargeRepository as PayRamChargeRepository };

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

@@ -0,0 +1,72 @@
+import { eq, sql } from "drizzle-orm";
+import { payramCharges } from "../../db/schema/payram.js";
+/**
+ * Manages PayRam charge records in PostgreSQL.
+ *
+ * Each charge maps a PayRam reference_id to a tenant and tracks
+ * the payment lifecycle (OPEN -> VERIFYING -> FILLED/CANCELLED).
+ */
+export class DrizzlePayRamChargeRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /** Create a new charge record when a payment session is initiated. */
+    async create(referenceId, tenantId, amountUsdCents) {
+        await this.db.insert(payramCharges).values({
+            referenceId,
+            tenantId,
+            amountUsdCents,
+            status: "OPEN",
+        });
+    }
+    /** Get a charge by reference ID. Returns null if not found. */
+    async getByReferenceId(referenceId) {
+        const row = (await this.db.select().from(payramCharges).where(eq(payramCharges.referenceId, referenceId)))[0];
+        if (!row)
+            return null;
+        return {
+            referenceId: row.referenceId,
+            tenantId: row.tenantId,
+            amountUsdCents: row.amountUsdCents,
+            status: row.status,
+            currency: row.currency ?? null,
+            filledAmount: row.filledAmount ?? null,
+            creditedAt: row.creditedAt ?? null,
+            createdAt: row.createdAt,
+            updatedAt: row.updatedAt,
+        };
+    }
+    /** Update charge status and payment details from webhook. */
+    async updateStatus(referenceId, status, currency, filledAmount) {
+        await this.db
+            .update(payramCharges)
+            .set({
+            status,
+            currency,
+            filledAmount,
+            updatedAt: sql `now()`,
+        })
+            .where(eq(payramCharges.referenceId, referenceId));
+    }
+    /** Mark a charge as credited (idempotency flag). */
+    async markCredited(referenceId) {
+        await this.db
+            .update(payramCharges)
+            .set({
+            creditedAt: sql `now()`,
+            updatedAt: sql `now()`,
+        })
+            .where(eq(payramCharges.referenceId, referenceId));
+    }
+    /** Check if a charge has already been credited (for idempotency). */
+    async isCredited(referenceId) {
+        const row = (await this.db
+            .select({ creditedAt: payramCharges.creditedAt })
+            .from(payramCharges)
+            .where(eq(payramCharges.referenceId, referenceId)))[0];
+        return row?.creditedAt != null;
+    }
+}
+// Backward-compat alias.
+export { DrizzlePayRamChargeRepository as PayRamChargeRepository };

package/dist/billing/payram/charge-store.test.d.ts

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

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

@@ -0,0 +1,64 @@
+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

@@ -0,0 +1,15 @@
+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

@@ -0,0 +1,24 @@
+/** 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.d.ts

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

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

@@ -0,0 +1,74 @@
+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

@@ -0,0 +1,7 @@
+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

@@ -0,0 +1,15 @@
+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.d.ts

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

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

@@ -0,0 +1,52 @@
+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

@@ -0,0 +1,8 @@
+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

@@ -0,0 +1,4 @@
+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

@@ -0,0 +1,40 @@
+/** 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/types.js

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

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

@@ -0,0 +1,19 @@
+import type { ICreditLedger } from "../../credits/credit-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: ICreditLedger;
+    replayGuard: IWebhookSeenRepository;
+    /** Called after credits are purchased — consumer can reactivate suspended resources. Returns reactivated resource IDs. */
+    onCreditsPurchased?: (tenantId: string, ledger: ICreditLedger) => 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

@@ -0,0 +1,67 @@
+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", `Crypto credit purchase via PayRam (ref: ${payload.reference_id}, ${payload.currency ?? "crypto"})`, `payram:${payload.reference_id}`, "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

@@ -0,0 +1,7 @@
+/**
+ * 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 {};