@wopr-network/platform-core 0.1.0

package/src/config/index.ts

@@ -0,0 +1,44 @@
+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,
+  },
+});
+
+export type PlatformConfig = z.infer<typeof platformConfigSchema>;

package/src/config/logger.ts

@@ -0,0 +1,12 @@
+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/src/config/provider-endpoints.ts

@@ -0,0 +1,14 @@
+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 const PROVIDER_API_URLS: Record<Provider, string> = {
+  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/src/credits/auto-topup-charge.test.ts

@@ -0,0 +1,292 @@
+import crypto from "node:crypto";
+import type { PGlite } from "@electric-sql/pglite";
+import Stripe from "stripe";
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import type { PlatformDb } from "../db/index.js";
+import { creditAutoTopup } from "../db/schema/credit-auto-topup.js";
+import { createTestDb, truncateAllTables } from "../test/db.js";
+import { Credit } from "./credit.js";
+import type { ITenantCustomerRepository } from "./tenant-customer-repository.js";
+import { type AutoTopupChargeDeps, chargeAutoTopup, MAX_CONSECUTIVE_FAILURES } from "./auto-topup-charge.js";
+import { DrizzleAutoTopupEventLogRepository } from "./auto-topup-event-log-repository.js";
+import { CreditLedger } from "./credit-ledger.js";
+
+function mockStripe(overrides?: {
+  paymentIntentId?: string;
+  shouldFail?: boolean;
+  failMessage?: string;
+  failWithStripeError?: boolean;
+}) {
+  const piId = overrides?.paymentIntentId ?? `pi_${crypto.randomUUID()}`;
+  return {
+    paymentIntents: {
+      create: vi.fn().mockImplementation(async () => {
+        if (overrides?.shouldFail) {
+          if (overrides.failWithStripeError !== false) {
+            throw new Stripe.errors.StripeCardError({
+              message: overrides.failMessage ?? "card_declined",
+              type: "card_error",
+              code: overrides.failMessage ?? "card_declined",
+            });
+          }
+          throw new Error(overrides.failMessage ?? "card_declined");
+        }
+        return { id: piId, status: "succeeded" };
+      }),
+    },
+    customers: {
+      listPaymentMethods: vi.fn().mockResolvedValue({ data: [{ id: "pm_123" }] }),
+    },
+  };
+}
+
+function mockTenantStore(stripeCustomerId = "cus_123") {
+  return {
+    getByTenant: vi.fn().mockResolvedValue({ tenant: "t1", processor_customer_id: stripeCustomerId }),
+  };
+}
+
+describe("chargeAutoTopup", () => {
+  let pool: PGlite;
+  let db: PlatformDb;
+  let ledger: CreditLedger;
+
+  beforeAll(async () => {
+    ({ db, pool } = await createTestDb());
+  });
+
+  afterAll(async () => {
+    await pool.close();
+  });
+
+  beforeEach(async () => {
+    await truncateAllTables(pool);
+    ledger = new CreditLedger(db);
+  });
+
+  it("charges Stripe and credits ledger on success", async () => {
+    const stripe = mockStripe();
+    const tenantRepo = mockTenantStore();
+    const deps: AutoTopupChargeDeps = {
+      stripe: stripe as unknown as Stripe,
+      tenantRepo: tenantRepo as unknown as ITenantCustomerRepository,
+      creditLedger: ledger,
+      eventLogRepo: new DrizzleAutoTopupEventLogRepository(db),
+    };
+
+    const result = await chargeAutoTopup(deps, "t1", Credit.fromCents(500), "auto_topup_usage");
+
+    expect(result.success).toBe(true);
+    expect(result.paymentReference).toEqual(expect.any(String));
+    expect((await ledger.balance("t1")).toCents()).toBe(500);
+    const history = await ledger.history("t1");
+    expect(history[0].type).toBe("purchase");
+    expect(history[0].fundingSource).toBe("stripe");
+  });
+
+  it("writes success event to credit_auto_topup log", async () => {
+    const stripe = mockStripe();
+    const tenantRepo = mockTenantStore();
+    const deps: AutoTopupChargeDeps = {
+      stripe: stripe as unknown as Stripe,
+      tenantRepo: tenantRepo as unknown as ITenantCustomerRepository,
+      creditLedger: ledger,
+      eventLogRepo: new DrizzleAutoTopupEventLogRepository(db),
+    };
+
+    await chargeAutoTopup(deps, "t1", Credit.fromCents(500), "auto_topup_usage");
+
+    const events = await db
+      .select()
+      .from(creditAutoTopup)
+      .where((await import("drizzle-orm")).eq(creditAutoTopup.tenantId, "t1"));
+    expect(events).toHaveLength(1);
+    expect(events[0].status).toBe("success");
+    expect(events[0].amountCents).toBe(500);
+  });
+
+  it("returns failure result and writes failure event on Stripe error", async () => {
+    const stripe = mockStripe({ shouldFail: true, failMessage: "card_declined" });
+    const tenantRepo = mockTenantStore();
+    const deps: AutoTopupChargeDeps = {
+      stripe: stripe as unknown as Stripe,
+      tenantRepo: tenantRepo as unknown as ITenantCustomerRepository,
+      creditLedger: ledger,
+      eventLogRepo: new DrizzleAutoTopupEventLogRepository(db),
+    };
+
+    const result = await chargeAutoTopup(deps, "t1", Credit.fromCents(500), "auto_topup_usage");
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("Card declined");
+    expect(result.error).toContain("card_declined");
+    expect((await ledger.balance("t1")).toCents()).toBe(0);
+    const events = await db
+      .select()
+      .from(creditAutoTopup)
+      .where((await import("drizzle-orm")).eq(creditAutoTopup.tenantId, "t1"));
+    expect(events).toHaveLength(1);
+    expect(events[0].status).toBe("failed");
+  });
+
+  it("returns failure when tenant has no Stripe customer", async () => {
+    const stripe = mockStripe();
+    const tenantRepo = { getByTenant: vi.fn().mockResolvedValue(null) };
+    const deps: AutoTopupChargeDeps = {
+      stripe: stripe as unknown as Stripe,
+      tenantRepo: tenantRepo as unknown as ITenantCustomerRepository,
+      creditLedger: ledger,
+      eventLogRepo: new DrizzleAutoTopupEventLogRepository(db),
+    };
+
+    const result = await chargeAutoTopup(deps, "t1", Credit.fromCents(500), "auto_topup_usage");
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("No Stripe customer");
+  });
+
+  it("returns failure when tenant has no payment methods", async () => {
+    const stripe = mockStripe();
+    stripe.customers.listPaymentMethods = vi.fn().mockResolvedValue({ data: [] });
+    const tenantRepo = mockTenantStore();
+    const deps: AutoTopupChargeDeps = {
+      stripe: stripe as unknown as Stripe,
+      tenantRepo: tenantRepo as unknown as ITenantCustomerRepository,
+      creditLedger: ledger,
+      eventLogRepo: new DrizzleAutoTopupEventLogRepository(db),
+    };
+
+    const result = await chargeAutoTopup(deps, "t1", Credit.fromCents(500), "auto_topup_usage");
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("No payment method");
+  });
+
+  it("is idempotent -- referenceId already credited means hasReferenceId returns true", async () => {
+    const piId = `pi_${crypto.randomUUID()}`;
+    const stripe = mockStripe({ paymentIntentId: piId });
+    const tenantRepo = mockTenantStore();
+    const deps: AutoTopupChargeDeps = {
+      stripe: stripe as unknown as Stripe,
+      tenantRepo: tenantRepo as unknown as ITenantCustomerRepository,
+      creditLedger: ledger,
+      eventLogRepo: new DrizzleAutoTopupEventLogRepository(db),
+    };
+
+    await chargeAutoTopup(deps, "t1", Credit.fromCents(500), "auto_topup_usage");
+    expect((await ledger.balance("t1")).toCents()).toBe(500);
+    expect(await ledger.hasReferenceId(piId)).toBe(true);
+  });
+
+  it("exports MAX_CONSECUTIVE_FAILURES as 3", () => {
+    expect(MAX_CONSECUTIVE_FAILURES).toBe(3);
+  });
+
+  it("logs structured card-decline info when Stripe throws StripeCardError on payment", async () => {
+    const cardError = new Stripe.errors.StripeCardError({
+      message: "Your card was declined.",
+      type: "card_error",
+      code: "card_declined",
+      decline_code: "insufficient_funds",
+    });
+    const stripe = mockStripe();
+    stripe.paymentIntents.create = vi.fn().mockRejectedValue(cardError);
+    const tenantRepo = mockTenantStore();
+    const deps: AutoTopupChargeDeps = {
+      stripe: stripe as unknown as Stripe,
+      tenantRepo: tenantRepo as unknown as ITenantCustomerRepository,
+      creditLedger: ledger,
+      eventLogRepo: new DrizzleAutoTopupEventLogRepository(db),
+    };
+
+    const result = await chargeAutoTopup(deps, "t1", Credit.fromCents(500), "auto_topup_usage");
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("Card declined");
+    expect(result.error).toContain("card_declined");
+  });
+
+  it("logs structured Stripe error info when Stripe throws StripeAPIError on payment", async () => {
+    const apiError = new Stripe.errors.StripeAPIError({
+      message: "Internal Stripe error",
+      type: "api_error",
+    });
+    const stripe = mockStripe();
+    stripe.paymentIntents.create = vi.fn().mockRejectedValue(apiError);
+    const tenantRepo = mockTenantStore();
+    const deps: AutoTopupChargeDeps = {
+      stripe: stripe as unknown as Stripe,
+      tenantRepo: tenantRepo as unknown as ITenantCustomerRepository,
+      creditLedger: ledger,
+      eventLogRepo: new DrizzleAutoTopupEventLogRepository(db),
+    };
+
+    const result = await chargeAutoTopup(deps, "t1", Credit.fromCents(500), "auto_topup_usage");
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("Stripe error");
+  });
+
+  it("re-throws non-Stripe errors from paymentIntents.create", async () => {
+    const stripe = mockStripe();
+    stripe.paymentIntents.create = vi.fn().mockRejectedValue(new TypeError("Cannot read properties of undefined"));
+    const tenantRepo = mockTenantStore();
+    const deps: AutoTopupChargeDeps = {
+      stripe: stripe as unknown as Stripe,
+      tenantRepo: tenantRepo as unknown as ITenantCustomerRepository,
+      creditLedger: ledger,
+      eventLogRepo: new DrizzleAutoTopupEventLogRepository(db),
+    };
+
+    await expect(chargeAutoTopup(deps, "t1", Credit.fromCents(500), "auto_topup_usage")).rejects.toThrow(TypeError);
+  });
+
+  it("returns structured error when StripeCardError thrown by listPaymentMethods", async () => {
+    const cardError = new Stripe.errors.StripeCardError({
+      message: "Card error on list",
+      type: "card_error",
+      code: "card_declined",
+    });
+    const stripe = mockStripe();
+    stripe.customers.listPaymentMethods = vi.fn().mockRejectedValue(cardError);
+    const tenantRepo = mockTenantStore();
+    const deps: AutoTopupChargeDeps = {
+      stripe: stripe as unknown as Stripe,
+      tenantRepo: tenantRepo as unknown as ITenantCustomerRepository,
+      creditLedger: ledger,
+      eventLogRepo: new DrizzleAutoTopupEventLogRepository(db),
+    };
+
+    const result = await chargeAutoTopup(deps, "t1", Credit.fromCents(500), "auto_topup_usage");
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("Card declined");
+  });
+
+  it("propagates error with PaymentIntent ID when credit grant fails after Stripe charge", async () => {
+    const piId = "pi_ledger_fail_test";
+    const stripe = mockStripe({ paymentIntentId: piId });
+    const tenantRepo = mockTenantStore();
+    const deps: AutoTopupChargeDeps = {
+      stripe: stripe as unknown as Stripe,
+      tenantRepo: tenantRepo as unknown as ITenantCustomerRepository,
+      creditLedger: ledger,
+      eventLogRepo: new DrizzleAutoTopupEventLogRepository(db),
+    };
+
+    // Make credit() fail after Stripe succeeds
+    vi.spyOn(ledger, "credit").mockRejectedValueOnce(new Error("DB connection lost"));
+
+    // Error propagates and contains the PI ID for manual reconciliation
+    await expect(chargeAutoTopup(deps, "t1", Credit.fromCents(500), "auto_topup_usage")).rejects.toThrow(piId);
+
+    // Also verify the original error message is preserved
+    vi.spyOn(ledger, "credit").mockRejectedValueOnce(new Error("DB connection lost"));
+    await expect(chargeAutoTopup(deps, "t1", Credit.fromCents(500), "auto_topup_usage")).rejects.toThrow(
+      "DB connection lost",
+    );
+
+    // No credits were silently granted
+    expect((await ledger.balance("t1")).toCents()).toBe(0);
+  });
+});

package/src/credits/auto-topup-charge.ts

@@ -0,0 +1,171 @@
+import Stripe from "stripe";
+import { logger } from "../config/logger.js";
+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 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 async function chargeAutoTopup(
+  deps: AutoTopupChargeDeps,
+  tenantId: string,
+  amount: Credit,
+  source: string,
+): Promise<AutoTopupChargeResult> {
+  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: string;
+  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: string;
+    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: Stripe.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/src/credits/auto-topup-event-log-repository.test.ts

@@ -0,0 +1,99 @@
+import type { PGlite } from "@electric-sql/pglite";
+import { eq } from "drizzle-orm";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import type { PlatformDb } from "../db/index.js";
+import { creditAutoTopup } from "../db/schema/credit-auto-topup.js";
+import { beginTestTransaction, createTestDb, endTestTransaction, rollbackTestTransaction } from "../test/db.js";
+import { DrizzleAutoTopupEventLogRepository } from "./auto-topup-event-log-repository.js";
+
+describe("DrizzleAutoTopupEventLogRepository", () => {
+  let pool: PGlite;
+  let db: PlatformDb;
+  let repo: DrizzleAutoTopupEventLogRepository;
+
+  beforeAll(async () => {
+    ({ db, pool } = await createTestDb());
+    await beginTestTransaction(pool);
+  });
+
+  afterAll(async () => {
+    await endTestTransaction(pool);
+    await pool.close();
+  });
+
+  beforeEach(async () => {
+    await rollbackTestTransaction(pool);
+    repo = new DrizzleAutoTopupEventLogRepository(db);
+  });
+
+  it("writes a success event with all fields", async () => {
+    await repo.writeEvent({
+      tenantId: "t1",
+      amountCents: 500,
+      status: "success",
+      failureReason: null,
+      paymentReference: "pi_abc123",
+    });
+
+    const rows = await db.select().from(creditAutoTopup).where(eq(creditAutoTopup.tenantId, "t1"));
+    expect(rows).toHaveLength(1);
+    expect(rows[0].tenantId).toBe("t1");
+    expect(rows[0].amountCents).toBe(500);
+    expect(rows[0].status).toBe("success");
+    expect(rows[0].failureReason).toBeNull();
+    expect(rows[0].paymentReference).toBe("pi_abc123");
+    expect(rows[0].id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+    expect(rows[0].createdAt).toMatch(/^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}/);
+  });
+
+  it("writes a failed event with failure reason", async () => {
+    await repo.writeEvent({
+      tenantId: "t1",
+      amountCents: 1000,
+      status: "failed",
+      failureReason: "card_declined",
+      paymentReference: null,
+    });
+
+    const rows = await db.select().from(creditAutoTopup).where(eq(creditAutoTopup.tenantId, "t1"));
+    expect(rows).toHaveLength(1);
+    expect(rows[0].status).toBe("failed");
+    expect(rows[0].failureReason).toBe("card_declined");
+    expect(rows[0].paymentReference).toBeNull();
+  });
+
+  it("defaults optional fields to null when omitted", async () => {
+    await repo.writeEvent({
+      tenantId: "t1",
+      amountCents: 200,
+      status: "success",
+    });
+
+    const rows = await db.select().from(creditAutoTopup).where(eq(creditAutoTopup.tenantId, "t1"));
+    expect(rows).toHaveLength(1);
+    expect(rows[0].failureReason).toBeNull();
+    expect(rows[0].paymentReference).toBeNull();
+  });
+
+  it("generates unique ids for each event", async () => {
+    await repo.writeEvent({ tenantId: "t1", amountCents: 100, status: "success" });
+    await repo.writeEvent({ tenantId: "t1", amountCents: 200, status: "success" });
+
+    const rows = await db.select().from(creditAutoTopup).where(eq(creditAutoTopup.tenantId, "t1"));
+    expect(rows).toHaveLength(2);
+    expect(rows[0].id).not.toBe(rows[1].id);
+  });
+
+  it("isolates events by tenant", async () => {
+    await repo.writeEvent({ tenantId: "t1", amountCents: 100, status: "success" });
+    await repo.writeEvent({ tenantId: "t2", amountCents: 200, status: "failed", failureReason: "insufficient_funds" });
+
+    const t1Rows = await db.select().from(creditAutoTopup).where(eq(creditAutoTopup.tenantId, "t1"));
+    const t2Rows = await db.select().from(creditAutoTopup).where(eq(creditAutoTopup.tenantId, "t2"));
+    expect(t1Rows).toHaveLength(1);
+    expect(t1Rows[0].amountCents).toBe(100);
+    expect(t2Rows).toHaveLength(1);
+    expect(t2Rows[0].amountCents).toBe(200);
+    expect(t2Rows[0].failureReason).toBe("insufficient_funds");
+  });
+});

package/src/credits/auto-topup-event-log-repository.ts

@@ -0,0 +1,30 @@
+import crypto from "node:crypto";
+import type { PlatformDb } from "../db/index.js";
+import { creditAutoTopup } from "../db/schema/credit-auto-topup.js";
+
+export interface AutoTopupEventLogEntry {
+  tenantId: string;
+  amountCents: number;
+  status: "success" | "failed";
+  failureReason?: string | null;
+  paymentReference?: string | null;
+}
+
+export interface IAutoTopupEventLogRepository {
+  writeEvent(entry: AutoTopupEventLogEntry): Promise<void>;
+}
+
+export class DrizzleAutoTopupEventLogRepository implements IAutoTopupEventLogRepository {
+  constructor(private readonly db: PlatformDb) {}
+
+  async writeEvent(entry: AutoTopupEventLogEntry): Promise<void> {
+    await this.db.insert(creditAutoTopup).values({
+      id: crypto.randomUUID(),
+      tenantId: entry.tenantId,
+      amountCents: entry.amountCents,
+      status: entry.status,
+      failureReason: entry.failureReason ?? null,
+      paymentReference: entry.paymentReference ?? null,
+    });
+  }
+}