@adaptware/eagles-db 0.6.14 → 0.6.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adaptware/eagles-db",
-  "version": "0.6.14",
+  "version": "0.6.15",
   "description": "A Prisma client package for Treadspace database operations",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/prisma/schema/integration.prisma

@@ -7,6 +7,7 @@ enum IntegrationProvider {
   MICROSOFT
   ZOOM
   CALENDLY
+  RAZORPAY
 
   @@schema("public")
 }

package/prisma/schema/licensing/purchasedLicense.prisma

@@ -19,9 +19,12 @@ model PurchasedLicensePackage {
   created_by         String
   updated_by         String
   is_active          Boolean                       @default(true)
+  /// Tax invoice for a paid or zero-amount purchase. Null = Super Admin grant (no invoice).
+  invoice_id         String?                       @unique
 
   organisation    Organisation          @relation(fields: [organisation_id], references: [id], onDelete: Restrict, onUpdate: Cascade)
   license_package LicensePackage        @relation(fields: [license_package_id], references: [id], onDelete: Restrict, onUpdate: Cascade)
+  invoice         Invoice?              @relation(fields: [invoice_id], references: [id], onDelete: Restrict)
   hiring_units    PurchasedHiringUnit[]
 
   @@index([organisation_id])

package/prisma/schema/migrations/20261022120000_billing_failure_category_provider_neutral/migration.sql

@@ -0,0 +1,28 @@
+-- BillingTransactionFailureCategory: rename Razorpay-specific values to provider-neutral ones.
+-- RENAME VALUE keeps existing billing_transactions rows on the renamed label.
+-- Guarded so it is a no-op where the enum was never created (migration-managed DBs
+-- without billing tables) or was already renamed.
+DO $$
+BEGIN
+  IF EXISTS (
+    SELECT 1 FROM pg_enum e
+    JOIN pg_type t ON t.oid = e.enumtypid
+    JOIN pg_namespace n ON n.oid = t.typnamespace
+    WHERE n.nspname = 'public'
+      AND t.typname = 'BillingTransactionFailureCategory'
+      AND e.enumlabel = 'RAZORPAY_ORDER'
+  ) THEN
+    ALTER TYPE "public"."BillingTransactionFailureCategory" RENAME VALUE 'RAZORPAY_ORDER' TO 'ORDER';
+  END IF;
+
+  IF EXISTS (
+    SELECT 1 FROM pg_enum e
+    JOIN pg_type t ON t.oid = e.enumtypid
+    JOIN pg_namespace n ON n.oid = t.typnamespace
+    WHERE n.nspname = 'public'
+      AND t.typname = 'BillingTransactionFailureCategory'
+      AND e.enumlabel = 'RAZORPAY_PAYMENT'
+  ) THEN
+    ALTER TYPE "public"."BillingTransactionFailureCategory" RENAME VALUE 'RAZORPAY_PAYMENT' TO 'PAYMENT';
+  END IF;
+END $$;

package/prisma/schema/organisation.prisma

@@ -59,6 +59,11 @@ model Organisation {
   timezone                  String                   @default("Asia/Kolkata")
   /// ISO 3166-1 alpha-2 (e.g. IN).
   country_code              String                   @default("IN")
+  /// Customer GSTIN; first 2 digits give the state for the CGST/SGST vs IGST split.
+  /// Optional: an Indian org without one is still charged GST.
+  gstin                     String?
+  /// Currency the organisation is billed in (INR or USD). Catalogue and checkout use only packages in this currency.
+  billing_currency          String                   @default("INR")
   /// Who may consume unused hiring units. Does not rewrite unit rows when changed.
   hiring_unit_assignment_scope HiringUnitAssignmentScope @default(DEPARTMENT)
   organisation_configs      OrganisationConfig[]
@@ -86,6 +91,9 @@ model Organisation {
   license_package_organisations  LicensePackageOrganisation[]
   ai_cost_ledger_entries         AiCostLedgerEntry[]
   consent_documents              ConsentDocument[]
+  billing_transactions      BillingTransaction[]
+  payment_webhook_events    PaymentWebhookEvent[]
+  invoices                  Invoice[]
 
   @@index([name])
   @@schema("public")

package/prisma/schema/payment/billingTransaction.prisma

@@ -0,0 +1,87 @@
+// PAYMENT SERVICE boundary — portable payment microservice owns these enums/columns.
+
+enum BillingTransactionStatus {
+  INITIATED
+  ORDER_CREATED
+  PAYMENT_PENDING
+  SUCCESS
+  FAILED
+  CANCELLED
+  REFUND_PENDING
+  REFUND_FAILED
+  REFUNDED
+
+  @@schema("public")
+}
+
+enum BillingTransactionType {
+  PURCHASE
+  TOP_UP
+  REFUND
+
+  @@schema("public")
+}
+
+/// Provider-neutral failure stage; provider detail goes in failure_reason.
+enum BillingTransactionFailureCategory {
+  ORDER
+  PAYMENT
+  REFUND
+  INTERNAL
+
+  @@schema("public")
+}
+
+/// Payment reconciliation state when Treadspace status is FAILED but Razorpay captured payment.
+enum BillingPaymentMismatchStatus {
+  DETECTED
+  UNFULFILLED
+
+  @@schema("public")
+}
+
+/// Financial transaction lifecycle for organisation billing purchases.
+model BillingTransaction {
+  id                               String                           @id @default(uuid())
+  organisation_id                  String
+  /// Opaque plan/product identity supplied at checkout. Not a catalog FK.
+  purchase_reference               String
+  /// Human-readable snapshot captured at checkout for invoices and receipts.
+  purchase_display_name            String?
+  transaction_type                 BillingTransactionType
+  status                           BillingTransactionStatus         @default(INITIATED)
+  failure_category                 BillingTransactionFailureCategory?
+  /// Human-readable or provider detail (e.g. Razorpay error_description).
+  failure_reason                   String?
+  amount                           Int
+  currency                         String                           @default("INR")
+  razorpay_order_id                String?
+  razorpay_payment_id              String?                          @unique
+  /// Razorpay payment method at capture (card, netbanking, upi, wallet, etc.).
+  payment_method                   String?
+  razorpay_subscription_id         String?
+  razorpay_refund_id               String?
+  refund_reason                    String?
+  refund_amount                    Int?
+  idempotency_key                  String                           @unique
+  /// Email of the org Admin who initiated checkout (bill-to).
+  purchaser_email                  String?
+  /// User id of the org Admin who started checkout; actor for fulfilment and the invoice.
+  created_by                       String?
+  /// Set when FAILED but Razorpay order/payment is captured (reconciliation path).
+  payment_mismatch_status          BillingPaymentMismatchStatus?
+  /// Strict same-intent SUCCESS transaction that fulfilled the purchase (UNFULFILLED only).
+  payment_mismatch_fulfilled_by_id String?
+  created_at                       DateTime                         @default(now())
+  updated_at                       DateTime                         @updatedAt
+
+  organisation Organisation @relation(fields: [organisation_id], references: [id])
+  /// Tax invoice issued for this payment (set once fulfilled).
+  invoice      Invoice?
+
+  @@index([organisation_id, status])
+  @@index([purchase_reference])
+  @@index([razorpay_order_id])
+  @@map("billing_transactions")
+  @@schema("public")
+}

package/prisma/schema/payment/invoice.prisma

@@ -0,0 +1,68 @@
+// Tax invoices issued by Treadspace. Shared by license package purchases and (later) platform subscriptions.
+
+/// What the invoice was raised for.
+enum InvoiceKind {
+  PACKAGE
+
+  @@schema("public")
+}
+
+/// Tax invoice. Raised only after money is received (or for a zero-amount purchase). Immutable once written.
+/// All amounts are integer minor units (paise / cents); total = cost + tax + fee + fee_tax (not stored).
+model Invoice {
+  id                     String      @id @default(uuid())
+  /// Sequential number, e.g. TS/26-27/000001 (at most 16 chars). The financial year is part of the number.
+  invoice_number         String      @unique
+  kind                   InvoiceKind
+  organisation_id        String
+  /// Payment that funded this invoice. Null for zero-amount purchases.
+  billing_transaction_id String?     @unique
+  currency               String
+  /// Optional line description snapshot, e.g. "Pro hiring pack (v2)".
+  description            String?
+  quantity               Int
+  /// Net cost of the goods/service (excludes GST and processing fee).
+  cost_amount            Int
+  /// GST on cost. 0 for non-Indian organisations.
+  tax_amount             Int
+  /// Payment processing fee.
+  fee_amount             Int
+  /// GST on the processing fee. 0 for non-Indian organisations.
+  fee_tax_amount         Int
+  /// GST rate in basis points (1800 = 18%) at issue time.
+  tax_rate_bps           Int
+  /// Processing fee rate in basis points (200 = 2%) at issue time.
+  fee_rate_bps           Int
+  /// Buyer snapshot from the organisation at issue time.
+  buyer_name             String
+  buyer_address          String
+  /// ISO 3166-1 alpha-2 (e.g. IN).
+  buyer_country_code     String
+  buyer_gstin            String?
+  /// Seller snapshot at issue time: { name, gstin, address, sac }.
+  seller_snapshot        Json
+  issued_at              DateTime    @default(now())
+  created_at             DateTime    @default(now())
+  /// User id that triggered the issue (checkout admin), or "system".
+  created_by             String
+
+  organisation              Organisation             @relation(fields: [organisation_id], references: [id], onDelete: Restrict)
+  billing_transaction       BillingTransaction?      @relation(fields: [billing_transaction_id], references: [id], onDelete: Restrict)
+  purchased_license_package PurchasedLicensePackage?
+
+  @@index([organisation_id, issued_at])
+  @@map("invoices")
+  @@schema("public")
+}
+
+/// Invoice number counter: one row per financial year (e.g. "2026-27"); the key only lives here, not on Invoice.
+/// Incremented inside the invoice-issuing transaction: concurrent issues wait on the row lock (no duplicate
+/// numbers, no retries) and a rolled-back issue rolls the counter back too (no gaps).
+model InvoiceSequence {
+  financial_year String   @id
+  last_sequence  Int      @default(0)
+  updated_at     DateTime @updatedAt
+
+  @@map("invoice_sequences")
+  @@schema("public")
+}

package/prisma/schema/payment/paymentWebhookEvent.prisma

@@ -0,0 +1,28 @@
+enum PaymentWebhookEventStatus {
+  RECEIVED
+  PROCESSED
+  FAILED
+
+  @@schema("public")
+}
+
+/// Idempotent record of payment provider webhook deliveries.
+model PaymentWebhookEvent {
+  id                     String                    @id @default(uuid())
+  organisation_id        String?
+  provider               String
+  provider_event_id      String
+  event_type             String
+  status                 PaymentWebhookEventStatus @default(RECEIVED)
+  billing_transaction_id String?
+  error_message          String?
+  processed_at           DateTime?
+  created_at             DateTime                  @default(now())
+
+  organisation Organisation? @relation(fields: [organisation_id], references: [id])
+
+  @@unique([provider, provider_event_id])
+  @@index([status, created_at])
+  @@map("payment_webhook_events")
+  @@schema("public")
+}