@varaos/db 1.3.1 → 1.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@varaos/db",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "private": false,
   "main": "index.js",
   "files": [

package/prisma/migrations/20260125074301_2026_01_25_billing_financial_primitives/migration.sql

@@ -0,0 +1,273 @@
+/*
+  Warnings:
+
+  - You are about to drop the column `processed` on the `BillingEvent` table. All the data in the column will be lost.
+  - You are about to drop the column `razorpayInvoiceId` on the `Invoice` table. All the data in the column will be lost.
+  - The `status` column on the `Job` table would be dropped and recreated. This will lead to data loss if there is data in the column.
+  - You are about to drop the column `razorpayCustomerId` on the `Subscription` table. All the data in the column will be lost.
+  - You are about to drop the column `razorpayPlanId` on the `Subscription` table. All the data in the column will be lost.
+  - You are about to drop the column `razorpaySubscriptionId` on the `Subscription` table. All the data in the column will be lost.
+  - A unique constraint covering the columns `[provider,eventId]` on the table `BillingEvent` will be added. If there are existing duplicate values, this will fail.
+  - A unique constraint covering the columns `[provider,providerInvoiceId]` on the table `Invoice` will be added. If there are existing duplicate values, this will fail.
+  - A unique constraint covering the columns `[provider,providerPaymentMethodId]` on the table `PaymentMethod` will be added. If there are existing duplicate values, this will fail.
+  - A unique constraint covering the columns `[providerSubscriptionId]` on the table `Subscription` will be added. If there are existing duplicate values, this will fail.
+  - Changed the type of `provider` on the `BillingEvent` table. No cast exists, the column would be dropped and recreated, which cannot be done if there is data, since the column is required.
+  - Added the required column `billingCustomerId` to the `Invoice` table without a default value. This is not possible if the table is not empty.
+  - Added the required column `provider` to the `Invoice` table without a default value. This is not possible if the table is not empty.
+  - Added the required column `providerInvoiceId` to the `Invoice` table without a default value. This is not possible if the table is not empty.
+  - Changed the type of `status` on the `Invoice` table. No cast exists, the column would be dropped and recreated, which cannot be done if there is data, since the column is required.
+  - Added the required column `billingCustomerId` to the `PaymentMethod` table without a default value. This is not possible if the table is not empty.
+  - Added the required column `providerPaymentMethodId` to the `PaymentMethod` table without a default value. This is not possible if the table is not empty.
+  - Changed the type of `provider` on the `PaymentMethod` table. No cast exists, the column would be dropped and recreated, which cannot be done if there is data, since the column is required.
+  - Changed the type of `type` on the `PaymentMethod` table. No cast exists, the column would be dropped and recreated, which cannot be done if there is data, since the column is required.
+  - Added the required column `billingCustomerId` to the `Subscription` table without a default value. This is not possible if the table is not empty.
+  - Added the required column `provider` to the `Subscription` table without a default value. This is not possible if the table is not empty.
+  - Added the required column `providerSubscriptionId` to the `Subscription` table without a default value. This is not possible if the table is not empty.
+
+*/
+-- CreateEnum
+CREATE TYPE "public"."BillingProvider" AS ENUM ('razorpay', 'stripe', 'juspay');
+
+-- CreateEnum
+CREATE TYPE "public"."SubscriptionEventType" AS ENUM ('created', 'activated', 'trial_started', 'trial_ended', 'charged', 'payment_failed', 'payment_recovered', 'paused', 'resumed', 'plan_changed', 'quantity_changed', 'canceled', 'completed', 'expired', 'refunded');
+
+-- CreateEnum
+CREATE TYPE "public"."InvoiceStatus" AS ENUM ('draft', 'open', 'paid', 'partially_paid', 'failed', 'void', 'refunded');
+
+-- CreateEnum
+CREATE TYPE "public"."PaymentMethodType" AS ENUM ('card', 'upi', 'bank', 'wallet');
+
+-- CreateEnum
+CREATE TYPE "public"."PaymentMethodStatus" AS ENUM ('active', 'inactive', 'expired', 'revoked');
+
+-- CreateEnum
+CREATE TYPE "public"."BillingEventStatus" AS ENUM ('received', 'processing', 'processed', 'failed');
+
+-- CreateEnum
+CREATE TYPE "public"."BillingLedgerEntryType" AS ENUM ('charge', 'refund', 'credit', 'debit', 'adjustment');
+
+-- CreateEnum
+CREATE TYPE "public"."BillingLedgerDirection" AS ENUM ('debit', 'credit');
+
+-- CreateEnum
+CREATE TYPE "public"."JobStatus" AS ENUM ('pending', 'scheduled', 'running', 'completed', 'failed', 'dead');
+
+-- CreateEnum
+CREATE TYPE "public"."CouponDiscountType" AS ENUM ('percentage', 'flat');
+
+-- CreateEnum
+CREATE TYPE "public"."CouponRedemptionScope" AS ENUM ('subscription', 'invoice', 'one_time');
+
+-- DropIndex
+DROP INDEX "public"."BillingEvent_eventId_key";
+
+-- DropIndex
+DROP INDEX "public"."Subscription_razorpayCustomerId_idx";
+
+-- DropIndex
+DROP INDEX "public"."Subscription_razorpaySubscriptionId_idx";
+
+-- DropIndex
+DROP INDEX "public"."Subscription_razorpaySubscriptionId_key";
+
+-- AlterTable
+ALTER TABLE "public"."BillingEvent" DROP COLUMN "processed",
+ADD COLUMN     "status" "public"."BillingEventStatus" NOT NULL DEFAULT 'received',
+DROP COLUMN "provider",
+ADD COLUMN     "provider" "public"."BillingProvider" NOT NULL;
+
+-- AlterTable
+ALTER TABLE "public"."Invoice" DROP COLUMN "razorpayInvoiceId",
+ADD COLUMN     "billingCustomerId" TEXT NOT NULL,
+ADD COLUMN     "hostedInvoiceUrl" TEXT,
+ADD COLUMN     "provider" "public"."BillingProvider" NOT NULL,
+ADD COLUMN     "providerInvoiceId" TEXT NOT NULL,
+DROP COLUMN "status",
+ADD COLUMN     "status" "public"."InvoiceStatus" NOT NULL,
+ALTER COLUMN "periodStart" DROP NOT NULL,
+ALTER COLUMN "periodEnd" DROP NOT NULL;
+
+-- AlterTable
+ALTER TABLE "public"."Job" DROP COLUMN "status",
+ADD COLUMN     "status" "public"."JobStatus" NOT NULL DEFAULT 'pending';
+
+-- AlterTable
+ALTER TABLE "public"."PaymentMethod" ADD COLUMN     "billingCustomerId" TEXT NOT NULL,
+ADD COLUMN     "providerPaymentMethodId" TEXT NOT NULL,
+ADD COLUMN     "status" "public"."PaymentMethodStatus" NOT NULL DEFAULT 'active',
+DROP COLUMN "provider",
+ADD COLUMN     "provider" "public"."BillingProvider" NOT NULL,
+DROP COLUMN "type",
+ADD COLUMN     "type" "public"."PaymentMethodType" NOT NULL,
+ALTER COLUMN "isDefault" SET DEFAULT false;
+
+-- AlterTable
+ALTER TABLE "public"."Subscription" DROP COLUMN "razorpayCustomerId",
+DROP COLUMN "razorpayPlanId",
+DROP COLUMN "razorpaySubscriptionId",
+ADD COLUMN     "billingCustomerId" TEXT NOT NULL,
+ADD COLUMN     "provider" "public"."BillingProvider" NOT NULL,
+ADD COLUMN     "providerPlanId" TEXT,
+ADD COLUMN     "providerSubscriptionId" TEXT NOT NULL;
+
+-- CreateTable
+CREATE TABLE "public"."BillingCustomer" (
+    "id" TEXT NOT NULL,
+    "userId" TEXT NOT NULL,
+    "provider" "public"."BillingProvider" NOT NULL,
+    "providerCustomerId" TEXT NOT NULL,
+    "email" TEXT,
+    "metadata" JSONB,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "BillingCustomer_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "public"."SubscriptionEvent" (
+    "id" TEXT NOT NULL,
+    "subscriptionId" TEXT NOT NULL,
+    "provider" "public"."BillingProvider" NOT NULL,
+    "eventType" "public"."SubscriptionEventType" NOT NULL,
+    "payload" JSONB NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "SubscriptionEvent_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "public"."BillingLedger" (
+    "id" TEXT NOT NULL,
+    "userId" TEXT NOT NULL,
+    "billingCustomerId" TEXT NOT NULL,
+    "provider" "public"."BillingProvider" NOT NULL,
+    "entryType" "public"."BillingLedgerEntryType" NOT NULL,
+    "direction" "public"."BillingLedgerDirection" NOT NULL,
+    "amount" INTEGER NOT NULL,
+    "currency" TEXT NOT NULL,
+    "referenceType" TEXT NOT NULL,
+    "referenceId" TEXT NOT NULL,
+    "description" TEXT,
+    "metadata" JSONB,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "BillingLedger_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "public"."Coupon" (
+    "id" TEXT NOT NULL,
+    "code" TEXT NOT NULL,
+    "discountType" "public"."CouponDiscountType" NOT NULL,
+    "discountValue" INTEGER NOT NULL,
+    "currency" TEXT,
+    "maxRedemptions" INTEGER,
+    "redeemedCount" INTEGER NOT NULL DEFAULT 0,
+    "validFrom" TIMESTAMP(3),
+    "validUntil" TIMESTAMP(3),
+    "applicablePlans" "public"."Plan"[],
+    "redemptionScope" "public"."CouponRedemptionScope" NOT NULL,
+    "active" BOOLEAN NOT NULL DEFAULT true,
+    "metadata" JSONB,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "Coupon_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "public"."RevenueAggregate" (
+    "id" TEXT NOT NULL,
+    "period" TEXT NOT NULL,
+    "provider" "public"."BillingProvider" NOT NULL,
+    "grossRevenue" INTEGER NOT NULL,
+    "refunds" INTEGER NOT NULL,
+    "credits" INTEGER NOT NULL,
+    "netRevenue" INTEGER NOT NULL,
+    "currency" TEXT NOT NULL,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "RevenueAggregate_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "BillingCustomer_providerCustomerId_idx" ON "public"."BillingCustomer"("providerCustomerId");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "BillingCustomer_provider_providerCustomerId_key" ON "public"."BillingCustomer"("provider", "providerCustomerId");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "BillingCustomer_userId_provider_key" ON "public"."BillingCustomer"("userId", "provider");
+
+-- CreateIndex
+CREATE INDEX "SubscriptionEvent_subscriptionId_createdAt_idx" ON "public"."SubscriptionEvent"("subscriptionId", "createdAt");
+
+-- CreateIndex
+CREATE INDEX "BillingLedger_userId_createdAt_idx" ON "public"."BillingLedger"("userId", "createdAt");
+
+-- CreateIndex
+CREATE INDEX "BillingLedger_billingCustomerId_createdAt_idx" ON "public"."BillingLedger"("billingCustomerId", "createdAt");
+
+-- CreateIndex
+CREATE INDEX "BillingLedger_provider_createdAt_idx" ON "public"."BillingLedger"("provider", "createdAt");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "Coupon_code_key" ON "public"."Coupon"("code");
+
+-- CreateIndex
+CREATE INDEX "RevenueAggregate_period_idx" ON "public"."RevenueAggregate"("period");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "RevenueAggregate_period_provider_currency_key" ON "public"."RevenueAggregate"("period", "provider", "currency");
+
+-- CreateIndex
+CREATE INDEX "BillingEvent_provider_eventType_idx" ON "public"."BillingEvent"("provider", "eventType");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "BillingEvent_provider_eventId_key" ON "public"."BillingEvent"("provider", "eventId");
+
+-- CreateIndex
+CREATE INDEX "Invoice_billingCustomerId_idx" ON "public"."Invoice"("billingCustomerId");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "Invoice_provider_providerInvoiceId_key" ON "public"."Invoice"("provider", "providerInvoiceId");
+
+-- CreateIndex
+CREATE INDEX "PaymentMethod_billingCustomerId_idx" ON "public"."PaymentMethod"("billingCustomerId");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "PaymentMethod_provider_providerPaymentMethodId_key" ON "public"."PaymentMethod"("provider", "providerPaymentMethodId");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "Subscription_providerSubscriptionId_key" ON "public"."Subscription"("providerSubscriptionId");
+
+-- CreateIndex
+CREATE INDEX "Subscription_provider_providerSubscriptionId_idx" ON "public"."Subscription"("provider", "providerSubscriptionId");
+
+-- CreateIndex
+CREATE INDEX "Subscription_billingCustomerId_idx" ON "public"."Subscription"("billingCustomerId");
+
+-- AddForeignKey
+ALTER TABLE "public"."Subscription" ADD CONSTRAINT "Subscription_billingCustomerId_fkey" FOREIGN KEY ("billingCustomerId") REFERENCES "public"."BillingCustomer"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "public"."Invoice" ADD CONSTRAINT "Invoice_subscriptionId_fkey" FOREIGN KEY ("subscriptionId") REFERENCES "public"."Subscription"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "public"."Invoice" ADD CONSTRAINT "Invoice_billingCustomerId_fkey" FOREIGN KEY ("billingCustomerId") REFERENCES "public"."BillingCustomer"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "public"."PaymentMethod" ADD CONSTRAINT "PaymentMethod_billingCustomerId_fkey" FOREIGN KEY ("billingCustomerId") REFERENCES "public"."BillingCustomer"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "public"."BillingCustomer" ADD CONSTRAINT "BillingCustomer_userId_fkey" FOREIGN KEY ("userId") REFERENCES "public"."User"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "public"."SubscriptionEvent" ADD CONSTRAINT "SubscriptionEvent_subscriptionId_fkey" FOREIGN KEY ("subscriptionId") REFERENCES "public"."Subscription"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "public"."BillingLedger" ADD CONSTRAINT "BillingLedger_userId_fkey" FOREIGN KEY ("userId") REFERENCES "public"."User"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "public"."BillingLedger" ADD CONSTRAINT "BillingLedger_billingCustomerId_fkey" FOREIGN KEY ("billingCustomerId") REFERENCES "public"."BillingCustomer"("id") ON DELETE RESTRICT ON UPDATE CASCADE;

package/prisma/migrations/20260125080918_2026_01_25_subscription_billing_intent_and_ledger/migration.sql

@@ -0,0 +1,2 @@
+-- AlterEnum
+ALTER TYPE "public"."SubscriptionStatus" ADD VALUE 'created';

package/prisma/schema.prisma

@@ -83,6 +83,7 @@ enum TwoFactorMethod {
 }
 
 enum SubscriptionStatus {
+  created     // intent created, payment pending
   active
   trialing
   past_due
@@ -90,6 +91,7 @@ enum SubscriptionStatus {
   paused
 }
 
+
 enum WorkflowStatus {
   draft
   active
@@ -119,6 +121,99 @@ enum WorkflowStepRunStatus {
   skipped
 }
 
+enum BillingProvider {
+  razorpay
+  stripe
+  juspay
+}
+
+enum SubscriptionEventType {
+  created // Subscription object created (before activation)
+  activated // First successful activation
+  trial_started // Trial period started
+  trial_ended // Trial expired or converted
+
+  charged // Successful recurring or first charge
+  payment_failed // Charge attempt failed
+  payment_recovered // Previously failed payment later succeeded
+
+  paused // Subscription paused (manual or system)
+  resumed // Subscription resumed after pause
+
+  plan_changed // Upgrade / downgrade
+  quantity_changed // Seats / units changed (enterprise)
+
+  canceled // User or system initiated cancellation
+  completed // Subscription ran its full course
+  expired // Ended due to non-payment / mandate expiry
+
+  refunded // Full or partial refund issued
+}
+
+enum InvoiceStatus {
+  draft
+  open
+  paid
+  partially_paid
+  failed
+  void
+  refunded
+}
+
+enum PaymentMethodType {
+  card
+  upi
+  bank
+  wallet
+}
+
+enum PaymentMethodStatus {
+  active
+  inactive
+  expired
+  revoked
+}
+
+enum BillingEventStatus {
+  received
+  processing
+  processed
+  failed
+}
+
+enum BillingLedgerEntryType {
+  charge
+  refund
+  credit
+  debit
+  adjustment
+}
+
+enum BillingLedgerDirection {
+  debit
+  credit
+}
+
+enum JobStatus {
+  pending
+  scheduled
+  running
+  completed
+  failed
+  dead
+}
+
+enum CouponDiscountType {
+  percentage
+  flat
+}
+
+enum CouponRedemptionScope {
+  subscription
+  invoice
+  one_time
+}
+
 /// ─────────────────────────────────────────────
 /// USERS & AUTH
 /// ─────────────────────────────────────────────
@@ -176,14 +271,16 @@ model User {
   Onboarding         Onboarding?
   ChatSession        ChatSession[]
 
-  createdAt      DateTime        @default(now())
-  updatedAt      DateTime        @updatedAt
-  posts          Post[]
-  userSessions   UserSession[]
-  paymentMethods PaymentMethod[]
-  userEmails     UserEmail[]
-  invoices       Invoice[]
-  userFiles      UserFile[]
+  createdAt        DateTime          @default(now())
+  updatedAt        DateTime          @updatedAt
+  posts            Post[]
+  userSessions     UserSession[]
+  paymentMethods   PaymentMethod[]
+  userEmails       UserEmail[]
+  invoices         Invoice[]
+  userFiles        UserFile[]
+  billingCustomers BillingCustomer[]
+  billingLedgers   BillingLedger[]
 
   @@index([status])
 }
@@ -725,85 +822,232 @@ model SecurityEvent {
 /// ─────────────────────────────────────────────
 
 model Subscription {
-  id     String             @id @default(uuid())
+  id String @id @default(uuid())
+
   userId String
   plan   Plan
-  status SubscriptionStatus // active | trialing | past_due | canceled
+  status SubscriptionStatus
 
-  // ── Lifecycle (rarely changes)
+  provider               BillingProvider // razorpay | stripe | juspay
+  providerSubscriptionId String          @unique
+  providerPlanId         String?
+
+  billingCustomerId String
+
+  // Lifecycle
   startedAt DateTime
   endedAt   DateTime?
 
-  // ── Billing cycle (changes every invoice)
+  // Billing cycle
   currentPeriodStart DateTime?
   currentPeriodEnd   DateTime?
-
-  // ── Provider scheduling (informational only)
-  nextPayment DateTime?
-
-  razorpayCustomerId     String?
-  razorpaySubscriptionId String? @unique
-  razorpayPlanId         String?
+  nextPayment        DateTime?
 
   metadata Json?
 
-  user User @relation(fields: [userId], references: [id])
+  user               User                @relation(fields: [userId], references: [id])
+  billingCustomer    BillingCustomer     @relation(fields: [billingCustomerId], references: [id])
+  invoices           Invoice[]
+  subscriptionEvents SubscriptionEvent[]
 
-  @@index([razorpayCustomerId])
-  @@index([razorpaySubscriptionId])
+  @@index([provider, providerSubscriptionId])
+  @@index([billingCustomerId])
 }
 
 model Invoice {
-  id                String   @id @default(uuid())
+  id String @id @default(uuid())
+
   userId            String
   subscriptionId    String?
-  razorpayInvoiceId String
-  amount            Int
-  currency          String
-  status            String // paid | open | failed | refunded
-  periodStart       DateTime
-  periodEnd         DateTime
-  pdfUrl            String?
-  metadata          Json?
+  billingCustomerId String
+
+  provider          BillingProvider // razorpay | stripe | juspay
+  providerInvoiceId String
+
+  amount   Int
+  currency String
+  status   InvoiceStatus
+
+  periodStart DateTime?
+  periodEnd   DateTime?
+
+  hostedInvoiceUrl String?
+  pdfUrl           String?
+
+  metadata Json?
 
   createdAt DateTime @default(now())
 
-  user User @relation(fields: [userId], references: [id])
+  user            User            @relation(fields: [userId], references: [id])
+  subscription    Subscription?   @relation(fields: [subscriptionId], references: [id])
+  billingCustomer BillingCustomer @relation(fields: [billingCustomerId], references: [id])
+
+  @@unique([provider, providerInvoiceId])
+  @@index([billingCustomerId])
 }
 
 model BillingEvent {
-  id       String @id @default(uuid())
-  provider String // razorpay
+  id String @id @default(uuid())
 
+  provider  BillingProvider // razorpay | stripe | juspay
   eventType String
-  eventId   String @unique // razorpay event ID
+  eventId   String
 
-  payload     Json
-  processed   Boolean   @default(false)
+  payload Json
+
+  status      BillingEventStatus @default(received)
   processedAt DateTime?
   error       String?
 
   createdAt DateTime @default(now())
 
+  @@unique([provider, eventId])
   @@index([provider, eventType])
 }
 
 model PaymentMethod {
-  id        String  @id @default(uuid())
-  userId    String
-  provider  String // razorpay | stripe | paypal
-  type      String // card
-  brand     String?
-  last4     String?
-  expMonth  Int?
-  expYear   Int?
-  isDefault Boolean @default(true)
-  metadata  Json?
+  id String @id @default(uuid())
+
+  userId            String
+  billingCustomerId String
+
+  provider                BillingProvider // razorpay | stripe | juspay
+  providerPaymentMethodId String // token_xxx, pm_xxx
+
+  type     PaymentMethodType // card | upi | bank
+  brand    String?
+  last4    String?
+  expMonth Int?
+  expYear  Int?
+
+  isDefault Boolean             @default(false)
+  status    PaymentMethodStatus @default(active)
+
+  metadata Json?
 
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
 
-  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+  user            User            @relation(fields: [userId], references: [id], onDelete: Cascade)
+  billingCustomer BillingCustomer @relation(fields: [billingCustomerId], references: [id])
+
+  @@unique([provider, providerPaymentMethodId])
+  @@index([billingCustomerId])
+}
+
+model BillingCustomer {
+  id String @id @default(uuid())
+
+  userId             String
+  provider           BillingProvider // razorpay | stripe | juspay
+  providerCustomerId String // cust_xxx, cus_xxx
+
+  email    String?
+  metadata Json?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  user           User            @relation(fields: [userId], references: [id], onDelete: Cascade)
+  subscriptions  Subscription[]
+  invoices       Invoice[]
+  paymentMethods PaymentMethod[]
+  billingLedgers BillingLedger[]
+
+  @@unique([provider, providerCustomerId])
+  @@unique([userId, provider])
+  @@index([providerCustomerId])
+}
+
+model SubscriptionEvent {
+  id String @id @default(uuid())
+
+  subscriptionId String
+  provider       BillingProvider
+  eventType      SubscriptionEventType
+  payload        Json
+
+  createdAt DateTime @default(now())
+
+  subscription Subscription @relation(fields: [subscriptionId], references: [id])
+
+  @@index([subscriptionId, createdAt])
+}
+
+model BillingLedger {
+  id String @id @default(uuid())
+
+  userId            String
+  billingCustomerId String
+
+  provider BillingProvider
+
+  entryType BillingLedgerEntryType // charge | refund | credit | debit | adjustment
+  direction BillingLedgerDirection // debit | credit
+
+  amount   Int
+  currency String
+
+  referenceType String // invoice | subscription | payment | coupon | reward
+  referenceId   String
+
+  description String?
+  metadata    Json?
+
+  createdAt DateTime @default(now())
+
+  user            User            @relation(fields: [userId], references: [id])
+  billingCustomer BillingCustomer @relation(fields: [billingCustomerId], references: [id])
+
+  @@index([userId, createdAt])
+  @@index([billingCustomerId, createdAt])
+  @@index([provider, createdAt])
+}
+
+model Coupon {
+  id String @id @default(uuid())
+
+  code String @unique
+
+  discountType  CouponDiscountType
+  discountValue Int // % or flat amount (minor units)
+
+  currency String? // required for flat discounts
+
+  maxRedemptions Int?
+  redeemedCount  Int  @default(0)
+
+  validFrom  DateTime?
+  validUntil DateTime?
+
+  applicablePlans Plan[]
+  redemptionScope CouponRedemptionScope
+
+  active Boolean @default(true)
+
+  metadata Json?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+}
+
+model RevenueAggregate {
+  id String @id @default(uuid())
+
+  period   String // YYYY-MM (e.g. 2026-02)
+  provider BillingProvider
+
+  grossRevenue Int
+  refunds      Int
+  credits      Int
+  netRevenue   Int
+
+  currency String
+
+  updatedAt DateTime @updatedAt
+
+  @@unique([period, provider, currency])
+  @@index([period])
 }
 
 model WaitList {
@@ -825,7 +1069,7 @@ model WaitList {
 model Job {
   id          String    @id @default(uuid())
   type        String
-  status      String    @default("pending")
+  status      JobStatus @default(pending)
   payload     Json
   retries     Int       @default(0)
   maxRetries  Int       @default(3)