@wopr-network/platform-core 0.1.0

package/dist/billing/stripe/tenant-store.test.js

@@ -0,0 +1,97 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { beginTestTransaction, createTestDb, endTestTransaction, rollbackTestTransaction } from "../../test/db.js";
+import { TenantCustomerRepository } from "./tenant-store.js";
+describe("TenantCustomerRepository", () => {
+    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 TenantCustomerRepository(db);
+    });
+    describe("upsert and getByTenant", () => {
+        it("inserts a new tenant mapping", async () => {
+            await store.upsert({ tenant: "t-1", processorCustomerId: "cus_abc" });
+            const row = await store.getByTenant("t-1");
+            expect(row).not.toBeNull();
+            expect(row?.tenant).toBe("t-1");
+            expect(row?.processor_customer_id).toBe("cus_abc");
+            expect(row?.tier).toBe("free");
+        });
+        it("updates existing mapping on conflict", async () => {
+            await store.upsert({ tenant: "t-1", processorCustomerId: "cus_old" });
+            await store.upsert({ tenant: "t-1", processorCustomerId: "cus_new" });
+            const row = await store.getByTenant("t-1");
+            expect(row?.processor_customer_id).toBe("cus_new");
+        });
+        it("returns null for non-existent tenant", async () => {
+            expect(await store.getByTenant("nonexistent")).toBeNull();
+        });
+    });
+    describe("getByProcessorCustomerId", () => {
+        it("looks up by processor customer ID", async () => {
+            await store.upsert({ tenant: "t-1", processorCustomerId: "cus_lookup" });
+            const row = await store.getByProcessorCustomerId("cus_lookup");
+            expect(row).not.toBeNull();
+            expect(row?.tenant).toBe("t-1");
+        });
+        it("returns null for unknown processor customer", async () => {
+            expect(await store.getByProcessorCustomerId("cus_unknown")).toBeNull();
+        });
+    });
+    describe("setTier", () => {
+        it("updates the tier for a tenant", async () => {
+            await store.upsert({ tenant: "t-1", processorCustomerId: "cus_abc" });
+            await store.setTier("t-1", "enterprise");
+            const row = await store.getByTenant("t-1");
+            expect(row?.tier).toBe("enterprise");
+        });
+    });
+    describe("setBillingHold and hasBillingHold", () => {
+        it("sets and checks billing hold", async () => {
+            await store.upsert({ tenant: "t-1", processorCustomerId: "cus_abc" });
+            expect(await store.hasBillingHold("t-1")).toBe(false);
+            await store.setBillingHold("t-1", true);
+            expect(await store.hasBillingHold("t-1")).toBe(true);
+            await store.setBillingHold("t-1", false);
+            expect(await store.hasBillingHold("t-1")).toBe(false);
+        });
+        it("returns false for non-existent tenant", async () => {
+            expect(await store.hasBillingHold("nonexistent")).toBe(false);
+        });
+    });
+    describe("list", () => {
+        it("returns all tenant mappings", async () => {
+            await store.upsert({ tenant: "t-1", processorCustomerId: "cus_1" });
+            await store.upsert({ tenant: "t-2", processorCustomerId: "cus_2" });
+            await store.upsert({ tenant: "t-3", processorCustomerId: "cus_3" });
+            const rows = await store.list();
+            expect(rows).toHaveLength(3);
+        });
+        it("returns empty array when no tenants exist", async () => {
+            expect(await store.list()).toHaveLength(0);
+        });
+    });
+    describe("buildCustomerIdMap", () => {
+        it("builds a tenant->processorCustomerId map", async () => {
+            await store.upsert({ tenant: "t-1", processorCustomerId: "cus_1" });
+            await store.upsert({ tenant: "t-2", processorCustomerId: "cus_2" });
+            const map = await store.buildCustomerIdMap();
+            expect(map).toEqual({
+                "t-1": "cus_1",
+                "t-2": "cus_2",
+            });
+        });
+        it("returns empty object when no tenants exist", async () => {
+            expect(await store.buildCustomerIdMap()).toEqual({});
+        });
+    });
+});

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

@@ -0,0 +1,49 @@
+/** Tenant-to-payment-processor customer mapping stored in SQLite. */
+export interface TenantCustomerRow {
+    tenant: string;
+    processor_customer_id: string;
+    processor: string;
+    tier: string;
+    billing_hold: number;
+    inference_mode: string;
+    created_at: number;
+    updated_at: number;
+}
+/** Options for creating a Stripe credit purchase Checkout session. */
+export interface CreditCheckoutOpts {
+    /** Internal tenant ID. */
+    tenant: string;
+    /** Stripe Price ID for the credit purchase. */
+    priceId: string;
+    /** URL to redirect to after successful checkout. */
+    successUrl: string;
+    /** URL to redirect to if the user cancels checkout. */
+    cancelUrl: string;
+}
+/** Options for creating a Stripe Customer Portal session. */
+export interface PortalSessionOpts {
+    /** Internal tenant ID (used to look up Stripe customer). */
+    tenant: string;
+    /** URL to redirect to when the user is done managing billing. */
+    returnUrl: string;
+}
+/** Options for creating a Stripe VPS subscription Checkout session. */
+export interface VpsCheckoutOpts {
+    /** Internal tenant ID. */
+    tenant: string;
+    /** Bot instance ID being upgraded. */
+    botId: string;
+    /** Stripe Price ID for the VPS subscription. */
+    vpsPriceId: string;
+    /** URL to redirect to after successful checkout. */
+    successUrl: string;
+    /** URL to redirect to if the user cancels checkout. */
+    cancelUrl: string;
+}
+/** Configuration for the Stripe billing integration. */
+export interface StripeBillingConfig {
+    /** Stripe secret API key. */
+    secretKey: string;
+    /** Stripe webhook signing secret. */
+    webhookSecret: string;
+}

package/dist/billing/stripe/types.js

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

package/dist/billing/webhook-seen-repository.d.ts

@@ -0,0 +1,14 @@
+import type { WebhookSeenEvent } from "../credits/repository-types.js";
+export interface IWebhookSeenRepository {
+    /** Returns true if the event ID + source combination has already been seen. */
+    isDuplicate(eventId: string, source: string): Promise<boolean>;
+    /** Mark an event ID + source as seen. */
+    markSeen(eventId: string, source: string): Promise<WebhookSeenEvent>;
+    /** Delete entries older than ttlMs. Returns count of deleted rows. */
+    purgeExpired(ttlMs: number): Promise<number>;
+}
+/**
+ * No-op replay guard that never reports duplicates.
+ * Use in tests that don't need deduplication behaviour.
+ */
+export declare const noOpReplayGuard: IWebhookSeenRepository;

package/dist/billing/webhook-seen-repository.js

@@ -0,0 +1,13 @@
+/**
+ * No-op replay guard that never reports duplicates.
+ * Use in tests that don't need deduplication behaviour.
+ */
+export const noOpReplayGuard = {
+    isDuplicate: async () => false,
+    markSeen: async (eventId, source) => ({
+        eventId,
+        source,
+        seenAt: Date.now(),
+    }),
+    purgeExpired: async () => 0,
+};

package/dist/config/billing-env.test.d.ts

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

package/dist/config/billing-env.test.js

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+// We test the schema directly, not the singleton config export,
+// because the singleton is already parsed at import time.
+// Instead we test the schema shape by importing and re-parsing.
+describe("billing env validation", () => {
+    it("uses correct defaults when no env vars set", async () => {
+        // Dynamic import to test schema defaults
+        const { billingConfigSchema } = await import("./index.js");
+        const result = billingConfigSchema.parse({});
+        expect(result).toEqual({
+            affiliateMatchRate: 1.0,
+            affiliateMaxReferrals30d: 20,
+            affiliateMaxMatchCredits30d: 20000,
+            affiliateNewUserBonusRate: 0.2,
+            dividendMatchRate: 1.0,
+            meterMaxRetries: 3,
+        });
+    });
+    it("coerces valid string values to numbers", async () => {
+        const { billingConfigSchema } = await import("./index.js");
+        const result = billingConfigSchema.parse({
+            affiliateMatchRate: "0.5",
+            affiliateMaxReferrals30d: "10",
+            affiliateMaxMatchCredits30d: "5000",
+            affiliateNewUserBonusRate: "0.15",
+            dividendMatchRate: "0.75",
+            meterMaxRetries: "5",
+        });
+        expect(result.affiliateMatchRate).toBe(0.5);
+        expect(result.affiliateMaxReferrals30d).toBe(10);
+        expect(result.affiliateMaxMatchCredits30d).toBe(5000);
+        expect(result.affiliateNewUserBonusRate).toBe(0.15);
+        expect(result.dividendMatchRate).toBe(0.75);
+        expect(result.meterMaxRetries).toBe(5);
+    });
+    it("rejects non-numeric strings", async () => {
+        const { billingConfigSchema } = await import("./index.js");
+        expect(() => billingConfigSchema.parse({ affiliateMatchRate: "not-a-number" })).toThrow();
+    });
+    it("rejects negative rates", async () => {
+        const { billingConfigSchema } = await import("./index.js");
+        expect(() => billingConfigSchema.parse({ affiliateMatchRate: "-0.5" })).toThrow();
+    });
+    it("rejects non-integer retries", async () => {
+        const { billingConfigSchema } = await import("./index.js");
+        expect(() => billingConfigSchema.parse({ meterMaxRetries: "2.5" })).toThrow();
+    });
+});

package/dist/config/index.d.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+declare const platformConfigSchema: z.ZodObject<{
+    port: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    nodeEnv: z.ZodDefault<z.ZodEnum<{
+        development: "development";
+        production: "production";
+        test: "test";
+    }>>;
+    logLevel: z.ZodDefault<z.ZodEnum<{
+        error: "error";
+        warn: "warn";
+        info: "info";
+        debug: "debug";
+    }>>;
+    billing: z.ZodDefault<z.ZodObject<{
+        affiliateMatchRate: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+        affiliateMaxReferrals30d: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+        affiliateMaxMatchCredits30d: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+        affiliateNewUserBonusRate: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+        dividendMatchRate: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+        meterMaxRetries: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const billingConfigSchema: z.ZodDefault<z.ZodObject<{
+    affiliateMatchRate: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    affiliateMaxReferrals30d: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    affiliateMaxMatchCredits30d: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    affiliateNewUserBonusRate: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    dividendMatchRate: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    meterMaxRetries: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>>;
+export declare const config: {
+    port: number;
+    nodeEnv: "development" | "production" | "test";
+    logLevel: "error" | "warn" | "info" | "debug";
+    billing: {
+        affiliateMatchRate: number;
+        affiliateMaxReferrals30d: number;
+        affiliateMaxMatchCredits30d: number;
+        affiliateNewUserBonusRate: number;
+        dividendMatchRate: number;
+        meterMaxRetries: number;
+    };
+};
+export type PlatformConfig = z.infer<typeof platformConfigSchema>;
+export {};

package/dist/config/index.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+const platformConfigSchema = z.object({
+    port: z.coerce.number().default(3100),
+    nodeEnv: z.enum(["development", "production", "test"]).default("development"),
+    logLevel: z.enum(["error", "warn", "info", "debug"]).default("info"),
+    /** Billing / affiliate / metering numeric env vars — validated at startup. */
+    billing: z
+        .object({
+        affiliateMatchRate: z.coerce.number().min(0).max(10).default(1.0),
+        affiliateMaxReferrals30d: z.coerce.number().int().min(0).default(20),
+        affiliateMaxMatchCredits30d: z.coerce.number().int().min(0).default(20000),
+        affiliateNewUserBonusRate: z.coerce.number().min(0).max(1).default(0.2),
+        dividendMatchRate: z.coerce.number().min(0).max(10).default(1.0),
+        meterMaxRetries: z.coerce.number().int().min(0).max(100).default(3),
+    })
+        .default({
+        affiliateMatchRate: 1.0,
+        affiliateMaxReferrals30d: 20,
+        affiliateMaxMatchCredits30d: 20000,
+        affiliateNewUserBonusRate: 0.2,
+        dividendMatchRate: 1.0,
+        meterMaxRetries: 3,
+    }),
+});
+export const billingConfigSchema = platformConfigSchema.shape.billing;
+export const config = platformConfigSchema.parse({
+    port: process.env.PORT,
+    nodeEnv: process.env.NODE_ENV,
+    logLevel: process.env.LOG_LEVEL,
+    billing: {
+        affiliateMatchRate: process.env.AFFILIATE_MATCH_RATE,
+        affiliateMaxReferrals30d: process.env.AFFILIATE_MAX_REFERRALS_30D,
+        affiliateMaxMatchCredits30d: process.env.AFFILIATE_MAX_MATCH_CREDITS_30D,
+        affiliateNewUserBonusRate: process.env.AFFILIATE_NEW_USER_BONUS_RATE,
+        dividendMatchRate: process.env.DIVIDEND_MATCH_RATE,
+        meterMaxRetries: process.env.METER_MAX_RETRIES,
+    },
+});

package/dist/config/logger.d.ts

@@ -0,0 +1,2 @@
+import winston from "winston";
+export declare const logger: winston.Logger;

package/dist/config/logger.js

@@ -0,0 +1,11 @@
+import winston from "winston";
+import { config } from "./index.js";
+export const logger = winston.createLogger({
+    level: config.logLevel,
+    format: winston.format.combine(winston.format.timestamp(), winston.format.json()),
+    transports: [
+        new winston.transports.Console({
+            format: winston.format.combine(winston.format.colorize(), winston.format.simple()),
+        }),
+    ],
+});

package/dist/config/provider-endpoints.d.ts

@@ -0,0 +1,6 @@
+import type { Provider } from "../security/types.js";
+/**
+ * Base API URLs used to validate provider keys.
+ * Centralised here so every consumer references one source of truth.
+ */
+export declare const PROVIDER_API_URLS: Record<Provider, string>;

package/dist/config/provider-endpoints.js

@@ -0,0 +1,12 @@
+/**
+ * Base API URLs used to validate provider keys.
+ * Centralised here so every consumer references one source of truth.
+ */
+export const PROVIDER_API_URLS = {
+    anthropic: "https://api.anthropic.com/v1/models",
+    openai: "https://api.openai.com/v1/models",
+    google: "https://generativelanguage.googleapis.com/v1/models",
+    discord: "https://discord.com/api/v10/users/@me",
+    elevenlabs: "https://api.elevenlabs.io/v1/user",
+    deepgram: "https://api.deepgram.com/v1/projects",
+};

package/dist/credits/auto-topup-charge.d.ts

@@ -0,0 +1,27 @@
+import Stripe from "stripe";
+import type { Credit } from "./credit.js";
+import type { ITenantCustomerRepository } from "./tenant-customer-repository.js";
+import type { IAutoTopupEventLogRepository } from "./auto-topup-event-log-repository.js";
+import type { ICreditLedger } from "./credit-ledger.js";
+/** After this many consecutive Stripe failures, the auto-topup mode is disabled. */
+export declare const MAX_CONSECUTIVE_FAILURES = 3;
+export interface AutoTopupChargeDeps {
+    stripe: Stripe;
+    tenantRepo: ITenantCustomerRepository;
+    creditLedger: ICreditLedger;
+    eventLogRepo: IAutoTopupEventLogRepository;
+}
+export interface AutoTopupChargeResult {
+    success: boolean;
+    paymentReference?: string;
+    error?: string;
+}
+/**
+ * Charge a tenant's default Stripe payment method off-session and credit their ledger.
+ *
+ * Writes to both `credit_transactions` (type=purchase) and `credit_auto_topup` event log.
+ *
+ * @param source - Descriptive source tag for the credit_transactions description
+ *                 (e.g., "auto_topup_usage" or "auto_topup_schedule")
+ */
+export declare function chargeAutoTopup(deps: AutoTopupChargeDeps, tenantId: string, amount: Credit, source: string): Promise<AutoTopupChargeResult>;

package/dist/credits/auto-topup-charge.js

@@ -0,0 +1,139 @@
+import Stripe from "stripe";
+import { logger } from "../config/logger.js";
+/** After this many consecutive Stripe failures, the auto-topup mode is disabled. */
+export const MAX_CONSECUTIVE_FAILURES = 3;
+/**
+ * Charge a tenant's default Stripe payment method off-session and credit their ledger.
+ *
+ * Writes to both `credit_transactions` (type=purchase) and `credit_auto_topup` event log.
+ *
+ * @param source - Descriptive source tag for the credit_transactions description
+ *                 (e.g., "auto_topup_usage" or "auto_topup_schedule")
+ */
+export async function chargeAutoTopup(deps, tenantId, amount, source) {
+    const amountCents = amount.toCentsFloor();
+    // 1. Look up Stripe customer
+    const mapping = await deps.tenantRepo.getByTenant(tenantId);
+    if (!mapping) {
+        const error = `No Stripe customer for tenant ${tenantId}`;
+        await deps.eventLogRepo.writeEvent({ tenantId, amountCents, status: "failed", failureReason: error });
+        return { success: false, error };
+    }
+    const customerId = mapping.processor_customer_id;
+    // 2. Get default payment method
+    let paymentMethodId;
+    try {
+        const methods = await deps.stripe.customers.listPaymentMethods(customerId, { limit: 1 });
+        if (!methods.data.length) {
+            const error = `No payment method on file for tenant ${tenantId}`;
+            await deps.eventLogRepo.writeEvent({ tenantId, amountCents, status: "failed", failureReason: error });
+            return { success: false, error };
+        }
+        paymentMethodId = methods.data[0].id;
+    }
+    catch (err) {
+        let error;
+        if (err instanceof Stripe.errors.StripeCardError) {
+            error = `Card declined listing payment methods: ${err.code ?? "unknown"} (decline_code=${err.decline_code ?? "none"})`;
+            logger.warn("Card error listing payment methods", { tenantId, code: err.code, declineCode: err.decline_code });
+        }
+        else if (err instanceof Stripe.errors.StripeError) {
+            error = `Stripe error listing payment methods: ${err.type} (code=${err.code ?? "none"}, status=${err.statusCode})`;
+            logger.error("Stripe error listing payment methods", {
+                tenantId,
+                type: err.type,
+                code: err.code,
+                statusCode: err.statusCode,
+            });
+        }
+        else {
+            error = `Failed to list payment methods: ${err instanceof Error ? err.message : String(err)}`;
+            logger.error("Unexpected error listing payment methods", { tenantId, error });
+        }
+        await deps.eventLogRepo.writeEvent({ tenantId, amountCents, status: "failed", failureReason: error });
+        return { success: false, error };
+    }
+    // 3. Create off-session PaymentIntent (Stripe expects integer cents)
+    let paymentIntent;
+    try {
+        paymentIntent = await deps.stripe.paymentIntents.create({
+            amount: amountCents,
+            currency: "usd",
+            customer: customerId,
+            payment_method: paymentMethodId,
+            off_session: true,
+            confirm: true,
+            metadata: {
+                wopr_tenant: tenantId,
+                wopr_source: source,
+            },
+        });
+    }
+    catch (err) {
+        if (err instanceof Stripe.errors.StripeCardError) {
+            const error = `Card declined during auto top-up: ${err.code ?? "unknown"} (decline_code=${err.decline_code ?? "none"})`;
+            await deps.eventLogRepo.writeEvent({ tenantId, amountCents, status: "failed", failureReason: error });
+            logger.warn("Card declined during auto top-up", {
+                tenantId,
+                code: err.code,
+                declineCode: err.decline_code,
+                source,
+            });
+            return { success: false, error };
+        }
+        else if (err instanceof Stripe.errors.StripeError) {
+            const error = `Stripe error during auto top-up: ${err.type} (code=${err.code ?? "none"}, status=${err.statusCode})`;
+            await deps.eventLogRepo.writeEvent({ tenantId, amountCents, status: "failed", failureReason: error });
+            logger.error("Stripe error during auto top-up", {
+                tenantId,
+                type: err.type,
+                code: err.code,
+                statusCode: err.statusCode,
+                source,
+            });
+            return { success: false, error };
+        }
+        else {
+            throw err;
+        }
+    }
+    // 4. Verify payment succeeded (could be requires_action for 3DS)
+    if (paymentIntent.status !== "succeeded") {
+        const error = `PaymentIntent status: ${paymentIntent.status}`;
+        await deps.eventLogRepo.writeEvent({
+            tenantId,
+            amountCents,
+            status: "failed",
+            failureReason: error,
+            paymentReference: paymentIntent.id,
+        });
+        logger.warn("Auto-topup PaymentIntent not succeeded", { tenantId, status: paymentIntent.status });
+        return { success: false, error, paymentReference: paymentIntent.id };
+    }
+    // 5. Credit the ledger (idempotent via referenceId = PI ID)
+    try {
+        if (!(await deps.creditLedger.hasReferenceId(paymentIntent.id))) {
+            await deps.creditLedger.credit(tenantId, amount, "purchase", `Auto-topup (${source})`, paymentIntent.id, "stripe");
+        }
+    }
+    catch (err) {
+        const message = `Stripe charge ${paymentIntent.id} succeeded but credit grant failed: ${err instanceof Error ? err.message : String(err)}`;
+        await deps.eventLogRepo
+            .writeEvent({
+            tenantId,
+            amountCents,
+            status: "failed",
+            failureReason: message,
+            paymentReference: paymentIntent.id,
+        })
+            .catch((logErr) => {
+            logger.error("Failed to write failure event after ledger error", { tenantId, piId: paymentIntent.id, logErr });
+        });
+        logger.error(message, { tenantId, piId: paymentIntent.id, source });
+        throw new Error(message);
+    }
+    // 6. Write success event
+    await deps.eventLogRepo.writeEvent({ tenantId, amountCents, status: "success", paymentReference: paymentIntent.id });
+    logger.info("Auto-topup charge succeeded", { tenantId, amount: amount.toString(), source, piId: paymentIntent.id });
+    return { success: true, paymentReference: paymentIntent.id };
+}

package/dist/credits/auto-topup-charge.test.d.ts

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