@wopr-network/platform-core 0.1.0

package/src/credits/dividend-repository.ts

@@ -0,0 +1,182 @@
+import { and, desc, eq, gte, lt, sql } from "drizzle-orm";
+import type { PlatformDb } from "../db/index.js";
+import { adminUsers } from "../db/schema/admin-users.js";
+import { creditTransactions } from "../db/schema/credits.js";
+import { dividendDistributions } from "../db/schema/dividend-distributions.js";
+import { Credit } from "./credit.js";
+import type { DividendHistoryEntry, DividendStats } from "./repository-types.js";
+
+export type { DividendHistoryEntry, DividendStats };
+
+export interface DigestTenantRow {
+  tenantId: string;
+  total: Credit;
+  distributionCount: number;
+  avgPool: Credit;
+  avgActiveUsers: number;
+}
+
+export interface IDividendRepository {
+  getStats(tenantId: string): Promise<DividendStats>;
+  getHistory(tenantId: string, limit: number, offset: number): Promise<DividendHistoryEntry[]>;
+  getLifetimeTotal(tenantId: string): Promise<Credit>;
+  /** Aggregate dividend distributions per tenant for a date window [windowStart, windowEnd). */
+  getDigestTenantAggregates(windowStart: string, windowEnd: string): Promise<DigestTenantRow[]>;
+  /** Resolve email for a tenant from admin_users. Returns undefined if no row exists. */
+  getTenantEmail(tenantId: string): Promise<string | undefined>;
+}
+
+export class DrizzleDividendRepository implements IDividendRepository {
+  constructor(private readonly db: PlatformDb) {}
+
+  async getStats(tenantId: string): Promise<DividendStats> {
+    // 1. Pool = sum of purchase amounts from yesterday UTC
+    const poolRow = (
+      await this.db
+        // raw SQL: Drizzle cannot express COALESCE(SUM(...), 0) aggregate
+        .select({ total: sql<number>`COALESCE(SUM(${creditTransactions.amount}), 0)` })
+        .from(creditTransactions)
+        .where(
+          and(
+            eq(creditTransactions.type, "purchase"),
+            // raw SQL: Drizzle cannot express date_trunc with interval arithmetic
+            sql`${creditTransactions.createdAt}::timestamp >= date_trunc('day', timezone('UTC', now())) - INTERVAL '1 day'`,
+            sql`${creditTransactions.createdAt}::timestamp < date_trunc('day', timezone('UTC', now()))`,
+          ),
+        )
+    )[0];
+    const poolCents = poolRow?.total ?? 0;
+    const pool = Credit.fromCents(poolCents);
+
+    // 2. Active users = distinct tenants with a purchase in the last 7 days
+    const activeRow = (
+      await this.db
+        // raw SQL: Drizzle cannot express COUNT(DISTINCT col)
+        .select({ count: sql<number>`COUNT(DISTINCT ${creditTransactions.tenantId})` })
+        .from(creditTransactions)
+        .where(
+          and(
+            eq(creditTransactions.type, "purchase"),
+            // raw SQL: Drizzle cannot express timestamp comparison with interval arithmetic
+            sql`${creditTransactions.createdAt}::timestamp >= timezone('UTC', now()) - INTERVAL '7 days'`,
+          ),
+        )
+    )[0];
+    const activeUsers = activeRow?.count ?? 0;
+
+    // 3. Per-user projection (avoid division by zero)
+    const perUser = activeUsers > 0 ? Credit.fromRaw(Math.floor(pool.toRaw() / activeUsers)) : Credit.ZERO;
+
+    // 4. Next distribution = midnight UTC tonight
+    const now = new Date();
+    const nextMidnight = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() + 1, 0, 0, 0));
+    const nextDistributionAt = nextMidnight.toISOString();
+
+    // 5. User eligibility — last purchase within 7 days
+    const userPurchaseRow = (
+      await this.db
+        .select({ createdAt: creditTransactions.createdAt })
+        .from(creditTransactions)
+        .where(and(eq(creditTransactions.tenantId, tenantId), eq(creditTransactions.type, "purchase")))
+        .orderBy(desc(creditTransactions.createdAt))
+        .limit(1)
+    )[0];
+
+    let userEligible = false;
+    let userLastPurchaseAt: string | null = null;
+    let userWindowExpiresAt: string | null = null;
+
+    if (userPurchaseRow) {
+      const rawTs = userPurchaseRow.createdAt;
+      // Parse the timestamp directly. PGlite may return ISO strings with or without
+      // timezone suffix. JavaScript's Date constructor handles ISO 8601 strings natively.
+      const lastPurchase = new Date(rawTs);
+      userLastPurchaseAt = lastPurchase.toISOString();
+
+      const windowExpiry = new Date(lastPurchase.getTime() + 7 * 24 * 60 * 60 * 1000);
+      userWindowExpiresAt = windowExpiry.toISOString();
+
+      userEligible = windowExpiry.getTime() > Date.now();
+    }
+
+    return {
+      pool,
+      activeUsers,
+      perUser,
+      nextDistributionAt,
+      userEligible,
+      userLastPurchaseAt,
+      userWindowExpiresAt,
+    };
+  }
+
+  async getHistory(tenantId: string, limit: number, offset: number): Promise<DividendHistoryEntry[]> {
+    const safeLimit = Math.min(Math.max(1, limit), 250);
+    const safeOffset = Math.max(0, offset);
+
+    const rows = await this.db
+      .select({
+        date: dividendDistributions.date,
+        amountCents: dividendDistributions.amountCents,
+        poolCents: dividendDistributions.poolCents,
+        activeUsers: dividendDistributions.activeUsers,
+      })
+      .from(dividendDistributions)
+      .where(eq(dividendDistributions.tenantId, tenantId))
+      .orderBy(desc(dividendDistributions.date))
+      .limit(safeLimit)
+      .offset(safeOffset);
+
+    return rows.map((row) => ({
+      date: row.date,
+      amount: Credit.fromCents(row.amountCents),
+      pool: Credit.fromCents(row.poolCents),
+      activeUsers: row.activeUsers,
+    }));
+  }
+
+  async getLifetimeTotal(tenantId: string): Promise<Credit> {
+    const row = (
+      await this.db
+        // raw SQL: Drizzle cannot express COALESCE(SUM(...), 0) aggregate
+        .select({ total: sql<number>`COALESCE(SUM(${dividendDistributions.amountCents}), 0)` })
+        .from(dividendDistributions)
+        .where(eq(dividendDistributions.tenantId, tenantId))
+    )[0];
+    return Credit.fromCents(row?.total ?? 0);
+  }
+
+  async getDigestTenantAggregates(windowStart: string, windowEnd: string): Promise<DigestTenantRow[]> {
+    const rows = await this.db
+      .select({
+        tenantId: dividendDistributions.tenantId,
+        // raw SQL: Drizzle cannot express SUM/COUNT(DISTINCT)/AVG with CAST aggregates
+        totalCents: sql<number>`SUM(${dividendDistributions.amountCents})`,
+        distributionCount: sql<number>`COUNT(DISTINCT ${dividendDistributions.date})`,
+        avgPoolCents: sql<number>`CAST(AVG(${dividendDistributions.poolCents}) AS INTEGER)`,
+        avgActiveUsers: sql<number>`CAST(AVG(${dividendDistributions.activeUsers}) AS INTEGER)`,
+      })
+      .from(dividendDistributions)
+      .where(and(gte(dividendDistributions.date, windowStart), lt(dividendDistributions.date, windowEnd)))
+      .groupBy(dividendDistributions.tenantId);
+
+    return rows.map((row) => ({
+      tenantId: row.tenantId,
+      total: Credit.fromCents(row.totalCents),
+      distributionCount: row.distributionCount,
+      avgPool: Credit.fromCents(row.avgPoolCents),
+      avgActiveUsers: row.avgActiveUsers,
+    }));
+  }
+
+  async getTenantEmail(tenantId: string): Promise<string | undefined> {
+    const row = (
+      await this.db
+        .select({ email: adminUsers.email })
+        .from(adminUsers)
+        .where(eq(adminUsers.tenantId, tenantId))
+        .limit(1)
+    )[0];
+    return row?.email;
+  }
+}

package/src/credits/index.ts

@@ -0,0 +1,25 @@
+export type {
+  AutoTopupSettings,
+  IAutoTopupSettingsRepository,
+} from "./auto-topup-settings-repository.js";
+export {
+  ALLOWED_SCHEDULE_INTERVALS,
+  ALLOWED_THRESHOLDS,
+  ALLOWED_TOPUP_AMOUNTS,
+  computeNextScheduleAt,
+  DrizzleAutoTopupSettingsRepository,
+} from "./auto-topup-settings-repository.js";
+export type { CreditExpiryCronConfig, CreditExpiryCronResult } from "./credit-expiry-cron.js";
+export { runCreditExpiryCron } from "./credit-expiry-cron.js";
+export type {
+  CreditTransaction,
+  CreditType,
+  DebitType,
+  HistoryOptions,
+  ICreditLedger,
+  TransactionType,
+} from "./credit-ledger.js";
+export { CreditLedger, DrizzleCreditLedger, InsufficientBalanceError } from "./credit-ledger.js";
+export { grantSignupCredits, SIGNUP_GRANT } from "./signup-grant.js";
+export { Credit } from "./credit.js";
+export type { ITenantCustomerRepository, TenantCustomerRow } from "./tenant-customer-repository.js";

package/src/credits/repository-types.ts

@@ -0,0 +1,33 @@
+import type { Credit } from "./credit.js";
+
+/** Domain type for a provisioned phone number tracked for monthly billing. */
+export interface ProvisionedPhoneNumber {
+  sid: string;
+  tenantId: string;
+  phoneNumber: string;
+  provisionedAt: string;
+  lastBilledAt: string | null;
+}
+
+export interface DividendStats {
+  pool: Credit;
+  activeUsers: number;
+  perUser: Credit;
+  nextDistributionAt: string;
+  userEligible: boolean;
+  userLastPurchaseAt: string | null;
+  userWindowExpiresAt: string | null;
+}
+
+export interface DividendHistoryEntry {
+  date: string;
+  amount: Credit;
+  pool: Credit;
+  activeUsers: number;
+}
+
+export interface WebhookSeenEvent {
+  eventId: string;
+  source: string;
+  seenAt: number;
+}

package/src/credits/signup-grant.test.ts

@@ -0,0 +1,63 @@
+import type { PGlite } from "@electric-sql/pglite";
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import type { PlatformDb } from "../db/index.js";
+import { createTestDb, truncateAllTables } from "../test/db.js";
+import { CreditLedger } from "./credit-ledger.js";
+import { grantSignupCredits, SIGNUP_GRANT } from "./signup-grant.js";
+
+describe("grantSignupCredits", () => {
+  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("grants credits to a new tenant and returns true", async () => {
+    const result = await grantSignupCredits(ledger, "tenant-1");
+    expect(result).toBe(true);
+    expect((await ledger.balance("tenant-1")).toCents()).toBe(SIGNUP_GRANT.toCents());
+  });
+
+  it("returns false for duplicate grant (idempotency)", async () => {
+    await grantSignupCredits(ledger, "tenant-1");
+    const result = await grantSignupCredits(ledger, "tenant-1");
+    expect(result).toBe(false);
+    expect((await ledger.balance("tenant-1")).toCents()).toBe(SIGNUP_GRANT.toCents());
+  });
+
+  it("grants independently to different tenants", async () => {
+    await grantSignupCredits(ledger, "tenant-1");
+    await grantSignupCredits(ledger, "tenant-2");
+    expect((await ledger.balance("tenant-1")).toCents()).toBe(SIGNUP_GRANT.toCents());
+    expect((await ledger.balance("tenant-2")).toCents()).toBe(SIGNUP_GRANT.toCents());
+  });
+
+  it("SIGNUP_GRANT.toCents() equals 500", () => {
+    expect(SIGNUP_GRANT.toCents()).toBe(500);
+  });
+
+  it("returns false when credit() throws a unique constraint violation (TOCTOU race)", async () => {
+    // Simulate two concurrent requests: both pass hasReferenceId check,
+    // then the second credit() call loses the race and gets a unique constraint error.
+    const uniqueErr = Object.assign(new Error("duplicate key value violates unique constraint"), {
+      code: "23505",
+    });
+    const racingLedger = new CreditLedger(db);
+    vi.spyOn(racingLedger, "hasReferenceId").mockResolvedValue(false);
+    vi.spyOn(racingLedger, "credit").mockRejectedValue(uniqueErr);
+
+    const result = await grantSignupCredits(racingLedger, "tenant-race");
+    expect(result).toBe(false);
+  });
+});

package/src/credits/signup-grant.ts

@@ -0,0 +1,44 @@
+import { Credit } from "./credit.js";
+import type { ICreditLedger } from "./credit-ledger.js";
+
+/** Signup grant amount: $5.00 */
+export const SIGNUP_GRANT = Credit.fromDollars(5);
+
+/**
+ * Grant the signup credit bonus to a newly verified tenant.
+ *
+ * Idempotent: uses `signup:<tenantId>` as referenceId to prevent double-grants.
+ *
+ * @returns true if the grant was applied, false if already granted.
+ */
+export async function grantSignupCredits(ledger: ICreditLedger, tenantId: string): Promise<boolean> {
+  const refId = `signup:${tenantId}`;
+
+  // Idempotency check
+  if (await ledger.hasReferenceId(refId)) {
+    return false;
+  }
+
+  try {
+    await ledger.credit(
+      tenantId,
+      SIGNUP_GRANT,
+      "signup_grant",
+      "Welcome bonus — $5.00 credit on email verification",
+      refId,
+    );
+  } catch (err) {
+    // Concurrent verify-email request won the race and already inserted the same referenceId.
+    // Treat unique constraint violation as a no-op (idempotent).
+    if (isUniqueConstraintViolation(err)) return false;
+    throw err;
+  }
+
+  return true;
+}
+
+function isUniqueConstraintViolation(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  if ((err as { code?: string }).code === "23505") return true;
+  return err.message.includes("UNIQUE") || err.message.includes("duplicate key");
+}

package/src/credits/tenant-customer-repository.ts

@@ -0,0 +1,28 @@
+/**
+ * Stub interface for tenant-customer repository.
+ * The Drizzle implementation lives in the billing module (extracted in Task 12).
+ */
+
+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;
+}
+
+export interface ITenantCustomerRepository {
+  getByTenant(tenant: string): Promise<TenantCustomerRow | null>;
+  getByProcessorCustomerId(processorCustomerId: string): Promise<TenantCustomerRow | null>;
+  upsert(row: { tenant: string; processorCustomerId: string; tier?: string }): Promise<void>;
+  setTier(tenant: string, tier: string): Promise<void>;
+  setBillingHold(tenant: string, hold: boolean): Promise<void>;
+  hasBillingHold(tenant: string): Promise<boolean>;
+  getInferenceMode(tenant: string): Promise<string>;
+  setInferenceMode(tenant: string, mode: string): Promise<void>;
+  list(): Promise<TenantCustomerRow[]>;
+  buildCustomerIdMap(): Promise<Record<string, string>>;
+}

package/src/db/auth-user-repository.ts

@@ -0,0 +1,124 @@
+/**
+ * Auth user repository — read/write the better-auth PostgreSQL user and account tables.
+ *
+ * Uses raw pg queries because better-auth manages its own schema
+ * independently of Drizzle.
+ */
+
+import { hashPassword, verifyPassword } from "better-auth/crypto";
+import type { Pool } from "pg";
+
+/**
+ * Ensure the twoFactorEnabled column exists on the better-auth user table.
+ * Idempotent — safe to call on every startup alongside runAuthMigrations().
+ */
+export async function initTwoFactorSchema(pool: Pool): Promise<void> {
+  // raw SQL: better-auth manages its own schema outside Drizzle
+  await pool.query(`ALTER TABLE "user" ADD COLUMN IF NOT EXISTS "twoFactorEnabled" BOOLEAN NOT NULL DEFAULT false`);
+}
+
+export interface AuthUser {
+  id: string;
+  name: string;
+  email: string;
+  image: string | null;
+  twoFactorEnabled: boolean;
+}
+
+export interface LinkedAccount {
+  id: string;
+  providerId: string;
+  accountId: string;
+}
+
+export interface IAuthUserRepository {
+  getUser(userId: string): Promise<AuthUser | null>;
+  updateUser(userId: string, data: { name?: string; image?: string | null }): Promise<AuthUser>;
+  changePassword(userId: string, currentPassword: string, newPassword: string): Promise<boolean>;
+  listAccounts(userId: string): Promise<LinkedAccount[]>;
+  unlinkAccount(userId: string, providerId: string): Promise<boolean>;
+}
+
+export class BetterAuthUserRepository implements IAuthUserRepository {
+  constructor(private readonly pool: Pool) {}
+
+  async getUser(userId: string): Promise<AuthUser | null> {
+    // raw SQL: better-auth manages its own schema outside Drizzle
+    const { rows } = await this.pool.query(
+      `SELECT id, name, email, image, "twoFactorEnabled" FROM "user" WHERE id = $1`,
+      [userId],
+    );
+    const row = rows[0] as AuthUser | undefined;
+    if (row) row.twoFactorEnabled = row.twoFactorEnabled ?? false;
+    return row ?? null;
+  }
+
+  async updateUser(userId: string, data: { name?: string; image?: string | null }): Promise<AuthUser> {
+    const fields: string[] = [];
+    const values: unknown[] = [];
+    let paramIndex = 1;
+
+    if (data.name !== undefined) {
+      fields.push(`name = $${paramIndex++}`);
+      values.push(data.name);
+    }
+    if (data.image !== undefined) {
+      fields.push(`image = $${paramIndex++}`);
+      values.push(data.image);
+    }
+    if (fields.length > 0) {
+      values.push(userId);
+      // raw SQL: better-auth manages its own schema outside Drizzle
+      await this.pool.query(`UPDATE "user" SET ${fields.join(", ")} WHERE id = $${paramIndex}`, values);
+    }
+    // raw SQL: better-auth manages its own schema outside Drizzle
+    const { rows } = await this.pool.query(
+      `SELECT id, name, email, image, "twoFactorEnabled" FROM "user" WHERE id = $1`,
+      [userId],
+    );
+    if (rows.length === 0) throw new Error(`User not found: ${userId}`);
+    const result = rows[0] as AuthUser;
+    result.twoFactorEnabled = result.twoFactorEnabled ?? false;
+    return result;
+  }
+
+  async changePassword(userId: string, currentPassword: string, newPassword: string): Promise<boolean> {
+    // raw SQL: better-auth manages its own schema outside Drizzle
+    const { rows } = await this.pool.query(
+      `SELECT password FROM account WHERE user_id = $1 AND provider_id = 'credential'`,
+      [userId],
+    );
+    const row = rows[0] as { password: string } | undefined;
+    if (!row?.password) return false;
+    const valid = await verifyPassword({ hash: row.password, password: currentPassword });
+    if (!valid) return false;
+    const newHash = await hashPassword(newPassword);
+    // raw SQL: better-auth manages its own schema outside Drizzle
+    await this.pool.query(`UPDATE account SET password = $1 WHERE user_id = $2 AND provider_id = 'credential'`, [
+      newHash,
+      userId,
+    ]);
+    return true;
+  }
+
+  async listAccounts(userId: string): Promise<LinkedAccount[]> {
+    // raw SQL: better-auth manages its own schema outside Drizzle
+    const { rows } = await this.pool.query(`SELECT id, provider_id, account_id FROM account WHERE user_id = $1`, [
+      userId,
+    ]);
+    return rows.map((r: { id: string; provider_id: string; account_id: string }) => ({
+      id: r.id,
+      providerId: r.provider_id,
+      accountId: r.account_id,
+    }));
+  }
+
+  async unlinkAccount(userId: string, providerId: string): Promise<boolean> {
+    // raw SQL: better-auth manages its own schema outside Drizzle
+    const { rowCount } = await this.pool.query(`DELETE FROM account WHERE user_id = $1 AND provider_id = $2`, [
+      userId,
+      providerId,
+    ]);
+    return (rowCount ?? 0) > 0;
+  }
+}

package/src/db/credit-column.ts

@@ -0,0 +1,17 @@
+import { customType } from "drizzle-orm/pg-core";
+import { Credit } from "../credits/credit.js";
+
+export const creditColumn = customType<{
+  data: Credit;
+  driverData: string;
+}>({
+  dataType() {
+    return "bigint"; // nanodollar values exceed int4 range
+  },
+  toDriver(value: Credit): string {
+    return String(value.toRaw());
+  },
+  fromDriver(value: number | string): Credit {
+    return Credit.fromRaw(Number(value));
+  },
+});

package/src/db/index.ts

@@ -0,0 +1,21 @@
+import { drizzle } from "drizzle-orm/node-postgres";
+import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";
+import type { Pool } from "pg";
+import * as schema from "./schema/index.js";
+
+/** The platform schema type (subset of the full application schema). */
+export type PlatformSchema = typeof schema;
+
+/**
+ * Narrower DB type used by platform-core repositories.
+ * wopr-platform's full DrizzleDb (wider schema) satisfies this constraint.
+ */
+export type PlatformDb = PgDatabase<PgQueryResultHKT, PlatformSchema>;
+
+/** Create a Drizzle database instance wrapping the given pg.Pool. */
+export function createDb(pool: Pool): PlatformDb {
+  return drizzle(pool, { schema }) as unknown as PlatformDb;
+}
+
+export { schema };
+export { creditColumn } from "./credit-column.js";

package/src/db/schema/account-deletion-requests.ts

@@ -0,0 +1,41 @@
+import { sql } from "drizzle-orm";
+import { index, pgTable, text } from "drizzle-orm/pg-core";
+
+/**
+ * Account deletion requests — tracks the lifecycle of GDPR deletion requests.
+ *
+ * States: pending -> completed | cancelled
+ *
+ * A pending request has a 30-day grace period. After the grace deadline,
+ * the deletion cron executes the purge and marks the request completed.
+ * Users can cancel a pending request within the grace period.
+ */
+export const accountDeletionRequests = pgTable(
+  "account_deletion_requests",
+  {
+    id: text("id").primaryKey(),
+    /** Tenant / user ID requesting deletion */
+    tenantId: text("tenant_id").notNull(),
+    /** User ID who initiated the request */
+    requestedBy: text("requested_by").notNull(),
+    /** pending | completed | cancelled */
+    status: text("status").notNull().default("pending"),
+    /** ISO timestamp after which deletion should execute */
+    deleteAfter: text("delete_after").notNull(),
+    /** Reason provided when the deletion was triggered */
+    reason: text("reason"),
+    /** Reason for cancellation (if cancelled) */
+    cancelReason: text("cancel_reason"),
+    /** ISO timestamp when purge completed */
+    completedAt: text("completed_at"),
+    /** JSON summary of what was deleted (table row counts) */
+    deletionSummary: text("deletion_summary"),
+    createdAt: text("created_at").notNull().default(sql`(now())`),
+    updatedAt: text("updated_at").notNull().default(sql`(now())`),
+  },
+  (table) => [
+    index("idx_acct_del_tenant").on(table.tenantId),
+    index("idx_acct_del_status").on(table.status),
+    index("idx_acct_del_delete_after").on(table.status, table.deleteAfter),
+  ],
+);

package/src/db/schema/account-export-requests.ts

@@ -0,0 +1,24 @@
+import { index, pgTable, text, timestamp } from "drizzle-orm/pg-core";
+
+/**
+ * Account export requests — tracks GDPR Article 15 data export requests.
+ *
+ * States: pending -> processing -> completed | failed
+ */
+export const accountExportRequests = pgTable(
+  "account_export_requests",
+  {
+    id: text("id").primaryKey(),
+    tenantId: text("tenant_id").notNull(),
+    requestedBy: text("requested_by").notNull(),
+    /** pending | processing | completed | failed */
+    status: text("status").notNull().default("pending"),
+    /** Export format — "json" by default */
+    format: text("format").notNull().default("json"),
+    /** Signed URL to download the export archive (set on completion) */
+    downloadUrl: text("download_url"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [index("idx_acct_export_tenant").on(table.tenantId), index("idx_acct_export_status").on(table.status)],
+);

package/src/db/schema/admin-audit.ts

@@ -0,0 +1,26 @@
+import { sql } from "drizzle-orm";
+import { bigint, index, pgTable, text } from "drizzle-orm/pg-core";
+
+export const adminAuditLog = pgTable(
+  "admin_audit_log",
+  {
+    id: text("id").primaryKey(),
+    adminUser: text("admin_user").notNull(),
+    action: text("action").notNull(),
+    category: text("category").notNull(),
+    targetTenant: text("target_tenant"),
+    targetUser: text("target_user"),
+    details: text("details").notNull().default("{}"),
+    ipAddress: text("ip_address"),
+    userAgent: text("user_agent"),
+    createdAt: bigint("created_at", { mode: "number" })
+      .notNull()
+      .default(sql`(extract(epoch from now()) * 1000)::bigint`),
+    outcome: text("outcome"),
+  },
+  (table) => [
+    index("idx_admin_audit_admin").on(table.adminUser, table.createdAt),
+    index("idx_admin_audit_tenant").on(table.targetTenant, table.createdAt),
+    index("idx_admin_audit_action").on(table.action, table.createdAt),
+  ],
+);

package/src/db/schema/admin-users.ts

@@ -0,0 +1,31 @@
+import { sql } from "drizzle-orm";
+import { bigint, check, index, integer, pgTable, text } from "drizzle-orm/pg-core";
+
+export const adminUsers = pgTable(
+  "admin_users",
+  {
+    id: text("id").primaryKey(),
+    email: text("email").notNull(),
+    name: text("name"),
+    tenantId: text("tenant_id").notNull(),
+    status: text("status").notNull().default("active"),
+    role: text("role").notNull().default("user"),
+    creditBalanceCents: integer("credit_balance_cents").notNull().default(0),
+    agentCount: integer("agent_count").notNull().default(0),
+    lastSeen: bigint("last_seen", { mode: "number" }),
+    createdAt: bigint("created_at", { mode: "number" }).notNull(),
+  },
+  (table) => [
+    index("idx_admin_users_email").on(table.email),
+    index("idx_admin_users_tenant").on(table.tenantId),
+    index("idx_admin_users_status").on(table.status),
+    index("idx_admin_users_role").on(table.role),
+    index("idx_admin_users_created").on(table.createdAt),
+    index("idx_admin_users_last_seen").on(table.lastSeen),
+    check(
+      "chk_admin_users_status",
+      sql`${table.status} IN ('active', 'suspended', 'grace_period', 'dormant', 'banned')`,
+    ),
+    check("chk_admin_users_role", sql`${table.role} IN ('platform_admin', 'tenant_admin', 'user')`),
+  ],
+);