@wopr-network/platform-core 0.1.0

package/src/billing/payram/charge-store.test.ts

@@ -0,0 +1,84 @@
+/**
+ * Unit tests for PayRamChargeRepository (WOP-407).
+ */
+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 { PayRamChargeRepository } from "./charge-store.js";
+
+describe("PayRamChargeRepository", () => {
+  let pool: PGlite;
+  let db: PlatformDb;
+  let store: PayRamChargeRepository;
+
+  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/src/billing/payram/charge-store.ts

@@ -0,0 +1,109 @@
+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";
+
+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 class DrizzlePayRamChargeRepository implements IPayRamChargeRepository {
+  constructor(private readonly db: PlatformDb) {}
+
+  /** Create a new charge record when a payment session is initiated. */
+  async create(referenceId: string, tenantId: string, amountUsdCents: number): Promise<void> {
+    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: string): Promise<PayRamChargeRecord | null> {
+    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: string,
+    status: PayRamPaymentState,
+    currency?: string,
+    filledAmount?: string,
+  ): Promise<void> {
+    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: string): Promise<void> {
+    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: string): Promise<boolean> {
+    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/src/billing/payram/checkout.test.ts

@@ -0,0 +1,99 @@
+/**
+ * Unit tests for createPayRamCheckout (WOP-407).
+ */
+import type { PGlite } from "@electric-sql/pglite";
+import type { Payram } from "payram";
+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 { PayRamChargeRepository } from "./charge-store.js";
+import { createPayRamCheckout, MIN_PAYMENT_USD } from "./checkout.js";
+
+function createMockPayram(overrides: { initiatePayment?: ReturnType<typeof vi.fn> } = {}): Payram {
+  return {
+    payments: {
+      initiatePayment:
+        overrides.initiatePayment ??
+        vi.fn().mockResolvedValue({
+          reference_id: "ref-mock-001",
+          url: "https://payram.example.com/pay/ref-mock-001",
+        }),
+    },
+  } as unknown as Payram;
+}
+
+describe("createPayRamCheckout", () => {
+  let pool: PGlite;
+  let db: PlatformDb;
+  let chargeStore: PayRamChargeRepository;
+  let payram: 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/src/billing/payram/checkout.ts

@@ -0,0 +1,40 @@
+import type { Payram } from "payram";
+import type { PayRamChargeRepository } from "./charge-store.js";
+import type { PayRamCheckoutOpts } from "./types.js";
+
+/** 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: Payram,
+  chargeStore: PayRamChargeRepository,
+  opts: PayRamCheckoutOpts,
+): Promise<{ referenceId: string; url: string }> {
+  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), // Convert to cents
+  );
+
+  return {
+    referenceId: result.reference_id,
+    url: result.url,
+  };
+}

package/src/billing/payram/client.test.ts

@@ -0,0 +1,62 @@
+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/src/billing/payram/client.ts

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

package/src/billing/payram/index.ts

@@ -0,0 +1,14 @@
+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/src/billing/payram/types.ts

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