@wopr-network/platform-core 0.1.0

package/src/db/schema/affiliate-fraud.ts

@@ -0,0 +1,23 @@
+import { sql } from "drizzle-orm";
+import { index, pgTable, text, uniqueIndex } from "drizzle-orm/pg-core";
+
+export const affiliateFraudEvents = pgTable(
+  "affiliate_fraud_events",
+  {
+    id: text("id").primaryKey(),
+    referralId: text("referral_id").notNull(),
+    referrerTenantId: text("referrer_tenant_id").notNull(),
+    referredTenantId: text("referred_tenant_id").notNull(),
+    verdict: text("verdict").notNull(),
+    signals: text("signals").notNull(),
+    signalDetails: text("signal_details").notNull(),
+    phase: text("phase").notNull(),
+    createdAt: text("created_at").notNull().default(sql`(now())`),
+  },
+  (table) => [
+    index("idx_fraud_referrer").on(table.referrerTenantId),
+    index("idx_fraud_referred").on(table.referredTenantId),
+    index("idx_fraud_verdict").on(table.verdict),
+    uniqueIndex("uq_fraud_referral_phase").on(table.referralId, table.phase),
+  ],
+);

package/src/db/schema/affiliate.ts

@@ -0,0 +1,38 @@
+import { sql } from "drizzle-orm";
+import { boolean, index, integer, pgTable, text } from "drizzle-orm/pg-core";
+
+/**
+ * Affiliate codes — one per tenant, generated lazily on first request.
+ * Code is a short 6-char alphanumeric string used in referral links.
+ */
+export const affiliateCodes = pgTable("affiliate_codes", {
+  tenantId: text("tenant_id").primaryKey(),
+  code: text("code").notNull().unique(),
+  createdAt: text("created_at").notNull().default(sql`(now())`),
+});
+
+/**
+ * Affiliate referrals — tracks who referred whom and conversion status.
+ * referred_tenant_id is UNIQUE to enforce first-referrer-wins.
+ */
+export const affiliateReferrals = pgTable(
+  "affiliate_referrals",
+  {
+    id: text("id").primaryKey(),
+    referrerTenantId: text("referrer_tenant_id").notNull(),
+    referredTenantId: text("referred_tenant_id").notNull().unique(),
+    code: text("code").notNull(),
+    signedUpAt: text("signed_up_at").notNull().default(sql`(now())`),
+    firstPurchaseAt: text("first_purchase_at"),
+    matchAmountCents: integer("match_amount_cents"),
+    matchedAt: text("matched_at"),
+    payoutSuppressed: boolean("payout_suppressed").notNull().default(false),
+    suppressionReason: text("suppression_reason"),
+    signupIp: text("signup_ip"),
+    signupEmail: text("signup_email"),
+  },
+  (table) => [
+    index("idx_affiliate_ref_referrer").on(table.referrerTenantId),
+    index("idx_affiliate_ref_code").on(table.code),
+  ],
+);

package/src/db/schema/coupon-codes.ts

@@ -0,0 +1,22 @@
+import { index, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+import { promotions } from "./promotions.js";
+
+export const couponCodes = pgTable(
+  "coupon_codes",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    promotionId: uuid("promotion_id")
+      .notNull()
+      .references(() => promotions.id),
+    code: text("code").notNull().unique(),
+    assignedTenantId: text("assigned_tenant_id"),
+    assignedEmail: text("assigned_email"),
+    redeemedAt: timestamp("redeemed_at", { withTimezone: true }),
+    redeemedByTenantId: text("redeemed_by_tenant_id"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => [
+    index("coupon_codes_promotion_idx").on(t.promotionId),
+    index("coupon_codes_assigned_tenant_idx").on(t.assignedTenantId),
+  ],
+);

package/src/db/schema/credit-auto-topup-settings.ts

@@ -0,0 +1,32 @@
+import { sql } from "drizzle-orm";
+import { boolean, index, integer, pgTable, text } from "drizzle-orm/pg-core";
+
+/**
+ * Per-tenant auto-topup configuration.
+ * Two independent modes: usage-based (after spend) and schedule-based (cron).
+ */
+export const creditAutoTopupSettings = pgTable(
+  "credit_auto_topup_settings",
+  {
+    tenantId: text("tenant_id").primaryKey(),
+    // Usage-based trigger
+    usageEnabled: boolean("usage_enabled").notNull().default(false),
+    usageThresholdCents: integer("usage_threshold_cents").notNull().default(100),
+    usageTopupCents: integer("usage_topup_cents").notNull().default(500),
+    usageConsecutiveFailures: integer("usage_consecutive_failures").notNull().default(0),
+    usageChargeInFlight: boolean("usage_charge_in_flight").notNull().default(false),
+    // Schedule-based trigger
+    scheduleEnabled: boolean("schedule_enabled").notNull().default(false),
+    scheduleAmountCents: integer("schedule_amount_cents").notNull().default(500),
+    scheduleIntervalHours: integer("schedule_interval_hours").notNull().default(168),
+    scheduleNextAt: text("schedule_next_at"),
+    scheduleConsecutiveFailures: integer("schedule_consecutive_failures").notNull().default(0),
+    // Metadata
+    createdAt: text("created_at").notNull().default(sql`(now())`),
+    updatedAt: text("updated_at").notNull().default(sql`(now())`),
+  },
+  (table) => [
+    index("idx_auto_topup_settings_usage").on(table.usageEnabled),
+    index("idx_auto_topup_settings_schedule").on(table.scheduleEnabled, table.scheduleNextAt),
+  ],
+);

package/src/db/schema/credit-auto-topup.ts

@@ -0,0 +1,26 @@
+import { sql } from "drizzle-orm";
+import { index, integer, pgTable, text } from "drizzle-orm/pg-core";
+
+/**
+ * Records every auto-topup attempt — both successes and failures.
+ * Used by admin analytics to track auto-topup revenue and failure rates.
+ */
+export const creditAutoTopup = pgTable(
+  "credit_auto_topup",
+  {
+    id: text("id").primaryKey(),
+    tenantId: text("tenant_id").notNull(),
+    amountCents: integer("amount_cents").notNull(),
+    status: text("status").notNull(), // "success" | "failed"
+    failureReason: text("failure_reason"),
+    /** Stripe payment intent or charge ID, if applicable */
+    paymentReference: text("payment_reference"),
+    createdAt: text("created_at").notNull().default(sql`(now())`),
+  },
+  (table) => [
+    index("idx_auto_topup_tenant").on(table.tenantId),
+    index("idx_auto_topup_status").on(table.status),
+    index("idx_auto_topup_created").on(table.createdAt),
+    index("idx_auto_topup_tenant_created").on(table.tenantId, table.createdAt),
+  ],
+);

package/src/db/schema/credits.ts

@@ -0,0 +1,44 @@
+import { sql } from "drizzle-orm";
+import { index, pgTable, text } from "drizzle-orm/pg-core";
+import { creditColumn } from "../credit-column.js";
+
+/**
+ * Credit transaction ledger — every credit/debit is an immutable row.
+ * Positive amount = credit (money in), negative = debit (money out).
+ */
+export const creditTransactions = pgTable(
+  "credit_transactions",
+  {
+    id: text("id").primaryKey(),
+    tenantId: text("tenant_id").notNull(),
+    amount: creditColumn("amount_credits").notNull(),
+    balanceAfter: creditColumn("balance_after_credits").notNull(),
+    type: text("type").notNull(), // signup_grant | purchase | bounty | referral | promo | community_dividend | bot_runtime | adapter_usage | addon | refund | correction
+    description: text("description"),
+    referenceId: text("reference_id").unique(),
+    fundingSource: text("funding_source"), // "stripe" | "payram" | null (null = legacy/signup)
+    attributedUserId: text("attributed_user_id"), // nullable — null for system/bot charges
+    createdAt: text("created_at").notNull().default(sql`(now())`),
+    expiresAt: text("expires_at"), // nullable — null means never expires
+    stripeFingerprint: text("stripe_fingerprint"),
+  },
+  (table) => [
+    index("idx_credit_tx_tenant").on(table.tenantId),
+    index("idx_credit_tx_type").on(table.type),
+    index("idx_credit_tx_ref").on(table.referenceId),
+    index("idx_credit_tx_created").on(table.createdAt),
+    index("idx_credit_tx_tenant_created").on(table.tenantId, table.createdAt),
+    index("idx_credit_tx_expires").on(table.expiresAt),
+    index("idx_credit_tx_fingerprint").on(table.stripeFingerprint).where(sql`${table.stripeFingerprint} IS NOT NULL`),
+  ],
+);
+
+/**
+ * Denormalized credit balance per tenant — updated atomically alongside
+ * every credit_transactions insert via a Drizzle transaction.
+ */
+export const creditBalances = pgTable("credit_balances", {
+  tenantId: text("tenant_id").primaryKey(),
+  balance: creditColumn("balance_credits").notNull().default(sql`0`),
+  lastUpdated: text("last_updated").notNull().default(sql`(now())`),
+});

package/src/db/schema/dividend-distributions.ts

@@ -0,0 +1,24 @@
+import { sql } from "drizzle-orm";
+import { index, integer, pgTable, text } from "drizzle-orm/pg-core";
+
+/**
+ * Dividend distribution ledger — one row per tenant per day when a dividend is paid.
+ * Written by the nightly dividend cron; read by the dividend API endpoints.
+ */
+export const dividendDistributions = pgTable(
+  "dividend_distributions",
+  {
+    id: text("id").primaryKey(),
+    tenantId: text("tenant_id").notNull(),
+    date: text("date").notNull(),
+    amountCents: integer("amount_cents").notNull(),
+    poolCents: integer("pool_cents").notNull(),
+    activeUsers: integer("active_users").notNull(),
+    createdAt: text("created_at").notNull().default(sql`(now())`),
+  },
+  (table) => [
+    index("idx_dividend_dist_tenant").on(table.tenantId),
+    index("idx_dividend_dist_date").on(table.date),
+    index("idx_dividend_dist_tenant_date").on(table.tenantId, table.date),
+  ],
+);

package/src/db/schema/email-notifications.ts

@@ -0,0 +1,26 @@
+import { sql } from "drizzle-orm";
+import { index, pgTable, text, unique } from "drizzle-orm/pg-core";
+
+/**
+ * Email notification deduplication table.
+ *
+ * Tracks which billing emails have been sent to prevent duplicates.
+ * Unique constraint on (tenantId, emailType, sentDate) ensures max 1
+ * email per type per day per tenant.
+ */
+export const emailNotifications = pgTable(
+  "email_notifications",
+  {
+    id: text("id").primaryKey(),
+    tenantId: text("tenant_id").notNull(),
+    emailType: text("email_type").notNull(),
+    sentAt: text("sent_at").notNull().default(sql`(now())`),
+    /** Date string (YYYY-MM-DD) extracted from sentAt for dedup constraint. */
+    sentDate: text("sent_date").notNull(),
+  },
+  (table) => [
+    unique("uniq_email_per_day").on(table.tenantId, table.emailType, table.sentDate),
+    index("idx_email_notif_tenant").on(table.tenantId),
+    index("idx_email_notif_type").on(table.emailType),
+  ],
+);

package/src/db/schema/index.ts

@@ -0,0 +1,33 @@
+export * from "./account-deletion-requests.js";
+export * from "./account-export-requests.js";
+export * from "./admin-audit.js";
+export * from "./admin-users.js";
+export * from "./affiliate.js";
+export * from "./affiliate-fraud.js";
+export * from "./coupon-codes.js";
+export * from "./credits.js";
+export * from "./credit-auto-topup.js";
+export * from "./credit-auto-topup-settings.js";
+export * from "./dividend-distributions.js";
+export * from "./email-notifications.js";
+export * from "./meter-events.js";
+export * from "./notification-preferences.js";
+export * from "./notification-queue.js";
+export * from "./org-memberships.js";
+export * from "./organization-members.js";
+export * from "./payram.js";
+export * from "./platform-api-keys.js";
+export * from "./promotion-redemptions.js";
+export * from "./promotions.js";
+export * from "./provider-credentials.js";
+export * from "./rate-limit-entries.js";
+export * from "./secret-audit-log.js";
+export * from "./session-usage.js";
+export * from "./spending-limits.js";
+export * from "./tenant-addons.js";
+export * from "./tenant-api-keys.js";
+export * from "./tenant-capability-settings.js";
+export * from "./tenant-customers.js";
+export * from "./tenants.js";
+export * from "./user-roles.js";
+export * from "./webhook-seen-events.js";

package/src/db/schema/meter-events.ts

@@ -0,0 +1,70 @@
+import { bigint, index, integer, pgTable, real, text, uniqueIndex } from "drizzle-orm/pg-core";
+
+export const meterEvents = pgTable(
+  "meter_events",
+  {
+    id: text("id").primaryKey(),
+    tenant: text("tenant").notNull(),
+    cost: bigint("cost", { mode: "number" }).notNull(),
+    charge: bigint("charge", { mode: "number" }).notNull(),
+    capability: text("capability").notNull(),
+    provider: text("provider").notNull(),
+    timestamp: bigint("timestamp", { mode: "number" }).notNull(),
+    sessionId: text("session_id"),
+    duration: integer("duration"),
+    usageUnits: real("usage_units"),
+    usageUnitType: text("usage_unit_type"),
+    tier: text("tier"),
+    metadata: text("metadata"),
+  },
+  (table) => [
+    index("idx_meter_tenant").on(table.tenant),
+    index("idx_meter_timestamp").on(table.timestamp),
+    index("idx_meter_capability").on(table.capability),
+    index("idx_meter_session").on(table.sessionId),
+    index("idx_meter_tenant_timestamp").on(table.tenant, table.timestamp),
+    index("idx_meter_tier").on(table.tier),
+  ],
+);
+
+export const usageSummaries = pgTable(
+  "usage_summaries",
+  {
+    id: text("id").primaryKey(),
+    tenant: text("tenant").notNull(),
+    capability: text("capability").notNull(),
+    provider: text("provider").notNull(),
+    eventCount: integer("event_count").notNull(),
+    totalCost: bigint("total_cost", { mode: "number" }).notNull(),
+    totalCharge: bigint("total_charge", { mode: "number" }).notNull(),
+    totalDuration: integer("total_duration").notNull().default(0),
+    windowStart: bigint("window_start", { mode: "number" }).notNull(),
+    windowEnd: bigint("window_end", { mode: "number" }).notNull(),
+  },
+  (table) => [
+    index("idx_summary_tenant").on(table.tenant, table.windowStart),
+    index("idx_summary_window").on(table.windowStart, table.windowEnd),
+  ],
+);
+
+export const billingPeriodSummaries = pgTable(
+  "billing_period_summaries",
+  {
+    id: text("id").primaryKey(),
+    tenant: text("tenant").notNull(),
+    capability: text("capability").notNull(),
+    provider: text("provider").notNull(),
+    eventCount: integer("event_count").notNull(),
+    totalCost: bigint("total_cost", { mode: "number" }).notNull(),
+    totalCharge: bigint("total_charge", { mode: "number" }).notNull(),
+    totalDuration: integer("total_duration").notNull().default(0),
+    periodStart: bigint("period_start", { mode: "number" }).notNull(),
+    periodEnd: bigint("period_end", { mode: "number" }).notNull(),
+    updatedAt: bigint("updated_at", { mode: "number" }).notNull(),
+  },
+  (table) => [
+    uniqueIndex("idx_billing_period_unique").on(table.tenant, table.capability, table.provider, table.periodStart),
+    index("idx_billing_period_tenant").on(table.tenant, table.periodStart),
+    index("idx_billing_period_window").on(table.periodStart, table.periodEnd),
+  ],
+);

package/src/db/schema/notification-preferences.ts

@@ -0,0 +1,19 @@
+import { sql } from "drizzle-orm";
+import { bigint, boolean, pgTable, text } from "drizzle-orm/pg-core";
+
+/**
+ * Per-tenant notification preferences.
+ * Each row is a tenant with boolean flags for each notification category.
+ * Absent row = all defaults (everything enabled except agentStatusChanges).
+ */
+export const notificationPreferences = pgTable("notification_preferences", {
+  tenantId: text("tenant_id").primaryKey(),
+  billingLowBalance: boolean("billing_low_balance").notNull().default(true),
+  billingReceipts: boolean("billing_receipts").notNull().default(true),
+  billingAutoTopup: boolean("billing_auto_topup").notNull().default(true),
+  agentChannelDisconnect: boolean("agent_channel_disconnect").notNull().default(true),
+  agentStatusChanges: boolean("agent_status_changes").notNull().default(false),
+  accountRoleChanges: boolean("account_role_changes").notNull().default(true),
+  accountTeamInvites: boolean("account_team_invites").notNull().default(true),
+  updatedAt: bigint("updated_at", { mode: "number" }).notNull().default(sql`(extract(epoch from now()))::bigint`),
+});

package/src/db/schema/notification-queue.ts

@@ -0,0 +1,45 @@
+import { sql } from "drizzle-orm";
+import { bigint, index, integer, pgTable, text } from "drizzle-orm/pg-core";
+
+/**
+ * Notification queue — queues system emails with retry support.
+ *
+ * Types: low_balance, grace_entered, suspended, receipt, welcome, reactivated
+ * States: pending -> sent | failed | dead_letter
+ *
+ * All timestamps are unix epoch milliseconds (integer) to match admin_notes.
+ */
+export const notificationQueue = pgTable(
+  "notification_queue",
+  {
+    id: text("id").primaryKey(),
+    tenantId: text("tenant_id").notNull(),
+    emailType: text("email_type").notNull(),
+    /** Recipient email address */
+    recipientEmail: text("recipient_email").notNull(),
+    /** JSON payload for the email template */
+    payload: text("payload").notNull().default("{}"),
+    /** pending | sent | failed | dead_letter */
+    status: text("status").notNull().default("pending"),
+    /** Number of send attempts */
+    attempts: integer("attempts").notNull().default(0),
+    /** Max retry attempts before dead-lettering */
+    maxAttempts: integer("max_attempts").notNull().default(3),
+    /** Unix epoch ms of last attempt */
+    lastAttemptAt: bigint("last_attempt_at", { mode: "number" }),
+    /** Error message from last failed attempt */
+    lastError: text("last_error"),
+    /** When to next retry (unix epoch ms). Null = immediately eligible. */
+    retryAfter: bigint("retry_after", { mode: "number" }),
+    createdAt: bigint("created_at", { mode: "number" })
+      .notNull()
+      .default(sql`(extract(epoch from now()) * 1000)::bigint`),
+    sentAt: bigint("sent_at", { mode: "number" }),
+  },
+  (table) => [
+    index("idx_notif_queue_tenant").on(table.tenantId),
+    index("idx_notif_queue_status").on(table.status),
+    index("idx_notif_queue_type").on(table.emailType),
+    index("idx_notif_queue_retry").on(table.status, table.retryAfter),
+  ],
+);

package/src/db/schema/org-memberships.ts

@@ -0,0 +1,20 @@
+import { bigint, index, pgTable, primaryKey, text, uniqueIndex } from "drizzle-orm/pg-core";
+
+/**
+ * Org membership — maps member tenants to their parent org tenant.
+ * A member tenant can belong to at most one org (unique on member_tenant_id).
+ * Created by org management flows (WOP-1006). Read-only for this feature.
+ */
+export const orgMemberships = pgTable(
+  "org_memberships",
+  {
+    orgTenantId: text("org_tenant_id").notNull(),
+    memberTenantId: text("member_tenant_id").notNull(),
+    createdAt: bigint("created_at", { mode: "number" }).notNull(),
+  },
+  (table) => [
+    primaryKey({ columns: [table.orgTenantId, table.memberTenantId] }),
+    uniqueIndex("idx_org_memberships_member_unique").on(table.memberTenantId),
+    index("idx_org_memberships_org").on(table.orgTenantId),
+  ],
+);

package/src/db/schema/organization-members.ts

@@ -0,0 +1,37 @@
+import { sql } from "drizzle-orm";
+import { bigint, index, pgTable, text, uniqueIndex } from "drizzle-orm/pg-core";
+
+export const organizationMembers = pgTable(
+  "organization_members",
+  {
+    id: text("id").primaryKey(),
+    orgId: text("org_id").notNull(),
+    userId: text("user_id").notNull(),
+    role: text("role").notNull().default("member"), // "owner" | "admin" | "member"
+    joinedAt: bigint("joined_at", { mode: "number" })
+      .notNull()
+      .default(sql`(extract(epoch from now()) * 1000)::bigint`),
+  },
+  (table) => [
+    index("idx_org_members_org_id").on(table.orgId),
+    index("idx_org_members_user_id").on(table.userId),
+    uniqueIndex("org_members_org_user_unique").on(table.orgId, table.userId),
+  ],
+);
+
+export const organizationInvites = pgTable(
+  "organization_invites",
+  {
+    id: text("id").primaryKey(),
+    orgId: text("org_id").notNull(),
+    email: text("email").notNull(),
+    role: text("role").notNull().default("member"), // "admin" | "member"
+    invitedBy: text("invited_by").notNull(),
+    token: text("token").notNull().unique(),
+    expiresAt: bigint("expires_at", { mode: "number" }).notNull(),
+    createdAt: bigint("created_at", { mode: "number" })
+      .notNull()
+      .default(sql`(extract(epoch from now()) * 1000)::bigint`),
+  },
+  (table) => [index("idx_org_invites_org_id").on(table.orgId), index("idx_org_invites_token").on(table.token)],
+);

package/src/db/schema/payram.ts

@@ -0,0 +1,26 @@
+import { sql } from "drizzle-orm";
+import { index, integer, pgTable, text } from "drizzle-orm/pg-core";
+
+/**
+ * PayRam payment sessions — tracks the lifecycle of each crypto payment.
+ * reference_id is the PayRam-assigned unique identifier.
+ */
+export const payramCharges = pgTable(
+  "payram_charges",
+  {
+    referenceId: text("reference_id").primaryKey(),
+    tenantId: text("tenant_id").notNull(),
+    amountUsdCents: integer("amount_usd_cents").notNull(),
+    status: text("status").notNull().default("OPEN"),
+    currency: text("currency"),
+    filledAmount: text("filled_amount"),
+    createdAt: text("created_at").notNull().default(sql`(now())`),
+    updatedAt: text("updated_at").notNull().default(sql`(now())`),
+    creditedAt: text("credited_at"),
+  },
+  (table) => [
+    index("idx_payram_charges_tenant").on(table.tenantId),
+    index("idx_payram_charges_status").on(table.status),
+    index("idx_payram_charges_created").on(table.createdAt),
+  ],
+);

package/src/db/schema/platform-api-keys.ts

@@ -0,0 +1,25 @@
+import { bigint, index, pgTable, text, uniqueIndex } from "drizzle-orm/pg-core";
+
+export const platformApiKeys = pgTable(
+  "platform_api_keys",
+  {
+    id: text("id").primaryKey(),
+    /** SHA-256 hex digest of the raw API key. Raw key is NEVER stored. */
+    keyHash: text("key_hash").notNull(),
+    /** The user this key authenticates as. */
+    userId: text("user_id").notNull(),
+    /** JSON-serialized string[] of roles (e.g. '["admin","user"]'). */
+    roles: text("roles").notNull(),
+    /** Optional human-readable label. */
+    label: text("label").notNull().default(""),
+    /** Unix epoch ms. Null = never expires. */
+    expiresAt: bigint("expires_at", { mode: "number" }),
+    /** Unix epoch ms. Null = not revoked. */
+    revokedAt: bigint("revoked_at", { mode: "number" }),
+    createdAt: bigint("created_at", { mode: "number" }).notNull(),
+  },
+  (table) => [
+    uniqueIndex("idx_platform_api_keys_hash").on(table.keyHash),
+    index("idx_platform_api_keys_user").on(table.userId),
+  ],
+);

package/src/db/schema/promotion-redemptions.ts

@@ -0,0 +1,23 @@
+import { index, integer, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+import { couponCodes } from "./coupon-codes.js";
+import { promotions } from "./promotions.js";
+
+export const promotionRedemptions = pgTable(
+  "promotion_redemptions",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    promotionId: uuid("promotion_id")
+      .notNull()
+      .references(() => promotions.id),
+    tenantId: text("tenant_id").notNull(),
+    couponCodeId: uuid("coupon_code_id").references(() => couponCodes.id),
+    creditsGranted: integer("credits_granted").notNull(),
+    creditTransactionId: text("credit_transaction_id").notNull(),
+    purchaseAmountCredits: integer("purchase_amount_credits"),
+    redeemedAt: timestamp("redeemed_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => [
+    index("promotion_redemptions_promotion_idx").on(t.promotionId),
+    index("promotion_redemptions_tenant_idx").on(t.tenantId),
+  ],
+);

package/src/db/schema/promotions.ts

@@ -0,0 +1,57 @@
+import { boolean, index, integer, pgEnum, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+
+export const promotionTypeEnum = pgEnum("promotion_type", [
+  "bonus_on_purchase",
+  "coupon_fixed",
+  "coupon_unique",
+  "batch_grant",
+]);
+
+export const promotionStatusEnum = pgEnum("promotion_status", [
+  "draft",
+  "scheduled",
+  "active",
+  "paused",
+  "expired",
+  "cancelled",
+]);
+
+export const promotionValueTypeEnum = pgEnum("promotion_value_type", ["flat_credits", "percent_of_purchase"]);
+
+export const promotionUserSegmentEnum = pgEnum("promotion_user_segment", [
+  "all",
+  "new_users",
+  "existing_users",
+  "tenant_list",
+]);
+
+export const promotions = pgTable(
+  "promotions",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    name: text("name").notNull(),
+    type: promotionTypeEnum("type").notNull(),
+    status: promotionStatusEnum("status").notNull().default("draft"),
+    startsAt: timestamp("starts_at", { withTimezone: true }),
+    endsAt: timestamp("ends_at", { withTimezone: true }),
+    valueType: promotionValueTypeEnum("value_type").notNull(),
+    valueAmount: integer("value_amount").notNull(),
+    maxValueCredits: integer("max_value_credits"),
+    firstPurchaseOnly: boolean("first_purchase_only").notNull().default(false),
+    minPurchaseCredits: integer("min_purchase_credits"),
+    userSegment: promotionUserSegmentEnum("user_segment").notNull().default("all"),
+    eligibleTenantIds: text("eligible_tenant_ids").array(),
+    totalUseLimit: integer("total_use_limit"),
+    perUserLimit: integer("per_user_limit").notNull().default(1),
+    budgetCredits: integer("budget_credits"),
+    totalUses: integer("total_uses").notNull().default(0),
+    totalCreditsGranted: integer("total_credits_granted").notNull().default(0),
+    couponCode: text("coupon_code").unique(),
+    couponBatchId: uuid("coupon_batch_id"),
+    createdBy: text("created_by").notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+    notes: text("notes"),
+  },
+  (t) => [index("promotions_status_idx").on(t.status), index("promotions_coupon_code_idx").on(t.couponCode)],
+);

package/src/db/schema/provider-credentials.ts

@@ -0,0 +1,41 @@
+import { sql } from "drizzle-orm";
+import { boolean, index, pgTable, text } from "drizzle-orm/pg-core";
+
+/**
+ * Provider credentials table — stores encrypted platform-level API keys
+ * for upstream AI providers used in hosted/gateway mode.
+ *
+ * Keys are encrypted at rest with AES-256-GCM. Multiple keys per provider
+ * are supported for rotation and load distribution.
+ */
+export const providerCredentials = pgTable(
+  "provider_credentials",
+  {
+    id: text("id").primaryKey(),
+    /** Provider identifier (e.g. "anthropic", "openai", "openrouter") */
+    provider: text("provider").notNull(),
+    /** Human-readable label (e.g. "Anthropic Production") */
+    keyName: text("key_name").notNull(),
+    /** AES-256-GCM encrypted API key (JSON-serialized EncryptedPayload) */
+    encryptedValue: text("encrypted_value").notNull(),
+    /** Auth mechanism: "header", "bearer", "basic" */
+    authType: text("auth_type").notNull(),
+    /** HTTP header name for injection (e.g. "x-api-key", "Authorization") */
+    authHeader: text("auth_header"),
+    /** Whether this credential is active and eligible for use */
+    isActive: boolean("is_active").notNull().default(true),
+    /** ISO timestamp of last successful validation */
+    lastValidated: text("last_validated"),
+    /** ISO timestamp of record creation */
+    createdAt: text("created_at").notNull().default(sql`(now())`),
+    /** ISO timestamp of last key rotation */
+    rotatedAt: text("rotated_at"),
+    /** Admin user ID who created/last modified this credential */
+    createdBy: text("created_by").notNull(),
+  },
+  (table) => [
+    index("idx_provider_creds_provider").on(table.provider),
+    index("idx_provider_creds_active").on(table.provider, table.isActive),
+    index("idx_provider_creds_created_by").on(table.createdBy),
+  ],
+);