@dainamite/billing 0.17.0 → 0.18.0

package/src/modules/billing/data/entities.ts

@@ -32,6 +32,8 @@ export class BillingAccount {
   [OptionalProps]?:
     | 'taxId'
     | 'lastBillDate'
+    | 'billingMode'
+    | 'creditLimit'
     | 'isActive'
     | 'createdAt'
     | 'updatedAt'
@@ -94,6 +96,19 @@ export class BillingAccount {
   @Property({ name: 'last_bill_date', type: 'date', columnType: 'date', nullable: true })
   lastBillDate?: Date | null
 
+  // Billing mode — 'postpaid' (default; the shipped Bill Run → draft →
+  // post flow) or 'prepaid' (top up a balance, draw it down in real time;
+  // SPEC-002). Immutable after create (like currency_code); validated at
+  // API ingress. Existing rows default to postpaid — zero behavior change.
+  @Property({ name: 'billing_mode', type: 'text', default: 'postpaid' })
+  billingMode: string = 'postpaid'
+
+  // Credit line extended to this customer (both modes). Prepaid: permitted
+  // overdraft below zero. Postpaid: max outstanding AR exposure. `0` = no
+  // credit. Reported, never enforced by billing (SPEC-002 assumption #11).
+  @Property({ name: 'credit_limit', type: 'numeric', columnType: 'numeric(18, 4)', default: '0' })
+  creditLimit: string = '0'
+
   @Property({ name: 'is_active', type: 'boolean', default: true })
   isActive: boolean = true
 
@@ -422,6 +437,7 @@ export class BillRunOutcome {
     | 'errorMessage'
     | 'warnings'
     | 'draftInvoiceId'
+    | 'statementId'
     | 'isActive'
     | 'createdAt'
     | 'updatedAt'
@@ -458,6 +474,12 @@ export class BillRunOutcome {
   @Property({ name: 'draft_invoice_id', type: 'uuid', nullable: true })
   draftInvoiceId?: string | null
 
+  // FK (string) to the BillingStatement produced for a PREPAID account
+  // (SPEC-002). Prepaid accounts get a statement instead of a draft invoice
+  // at period close, so this is the prepaid analogue of `draft_invoice_id`.
+  @Property({ name: 'statement_id', type: 'uuid', nullable: true })
+  statementId?: string | null
+
   @Property({ name: 'is_active', type: 'boolean', default: true })
   isActive: boolean = true
 
@@ -531,3 +553,364 @@ export class DraftInvoiceEdit {
   @Property({ name: 'deleted_at', type: Date, nullable: true })
   deletedAt?: Date | null
 }
+
+// ─── BillingAccountBalance (SPEC-002) ────────────────────────────
+//
+// The denormalized running balance for a prepaid account — exactly one
+// row per prepaid account. It is the O(1) read AND the row the atomic
+// `UPDATE … RETURNING` debit/credit locks, which is why the balance is
+// NOT a column on `billing_accounts`: the high-write balance update never
+// touches the account row that the Bill Run hot-path index sits on.
+//
+// `balance` is the cache; the source of truth is
+// `SUM(billing_account_transactions.amount)`. The reconciliation invariant
+// `balance == SUM(amount) == latest.balance_after` is unit-tested.
+
+@Entity({ tableName: 'billing_account_balances' })
+@Unique({
+  name: 'billing_account_balances_account_unique',
+  properties: ['tenantId', 'billAccountId'],
+})
+@Index({
+  name: 'billing_account_balances_balance_idx',
+  properties: ['organizationId', 'tenantId', 'balance'],
+})
+export class BillingAccountBalance {
+  [OptionalProps]?:
+    | 'lowBalanceThreshold'
+    | 'lastMovementAt'
+    | 'createdAt'
+    | 'updatedAt'
+
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'organization_id', type: 'uuid' })
+  organizationId!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  // Unique FK (string) to BillingAccount.id — one balance per account.
+  @Property({ name: 'bill_account_id', type: 'uuid' })
+  billAccountId!: string
+
+  // Denormalized from the account so the balance row is self-contained.
+  @Property({ name: 'currency_code', type: 'text' })
+  currencyCode!: string
+
+  // Running balance. May be NEGATIVE (usage is never rejected). Maintained
+  // exclusively by the atomic `UPDATE … RETURNING` in lib/balanceLedger.ts.
+  @Property({ name: 'balance', type: 'numeric', columnType: 'numeric(18, 4)', default: '0' })
+  balance: string = '0'
+
+  // When `balance <= threshold` → status `low` + `billing.balance.low`.
+  // Null = use the tenant config default
+  // (`billing.prepaid.low_balance_threshold_default`).
+  @Property({
+    name: 'low_balance_threshold',
+    type: 'numeric',
+    columnType: 'numeric(18, 4)',
+    nullable: true,
+  })
+  lowBalanceThreshold?: string | null
+
+  // Timestamp of the most recent transaction — a cheap "is this account
+  // active?" signal.
+  @Property({ name: 'last_movement_at', type: Date, nullable: true })
+  lastMovementAt?: Date | null
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: Date, onUpdate: () => new Date() })
+  updatedAt: Date = new Date()
+}
+
+// ─── BillingAccountTransaction (SPEC-002, append-only) ───────────
+//
+// The source of truth for every balance movement. Append-only — pattern
+// mirrors DraftInvoiceEdit (no `updated_at` / `is_active`; `deleted_at`
+// reserved for compliance erasure only). `balance = SUM(amount)`.
+//
+// The unique `(tenant_id, bill_account_id, source_ref)` is the idempotency
+// gate: a deduplicated usage upload or a retried recurring charge can never
+// double-debit (Postgres treats NULL source_ref as distinct — manual
+// adjustments without a key always insert).
+
+@Entity({ tableName: 'billing_account_transactions' })
+@Unique({
+  name: 'billing_account_transactions_source_ref_unique',
+  properties: ['tenantId', 'billAccountId', 'sourceRef'],
+})
+@Index({
+  name: 'billing_account_transactions_history_idx',
+  properties: ['organizationId', 'tenantId', 'billAccountId', 'createdAt'],
+})
+@Index({
+  name: 'billing_account_transactions_account_type_idx',
+  properties: ['billAccountId', 'type', 'createdAt'],
+})
+export class BillingAccountTransaction {
+  [OptionalProps]?:
+    | 'usageId'
+    | 'billingItemId'
+    | 'topupId'
+    | 'statementId'
+    | 'sourceRef'
+    | 'metadata'
+    | 'userId'
+    | 'createdAt'
+    | 'deletedAt'
+
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'organization_id', type: 'uuid' })
+  organizationId!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  @Property({ name: 'bill_account_id', type: 'uuid' })
+  billAccountId!: string
+
+  // 'topup' | 'usage' | 'recurring' | 'one_time' | 'adjustment' | 'reversal'.
+  @Property({ type: 'text' })
+  type!: string
+
+  // SIGNED: `> 0` credit, `< 0` debit. Balance = SUM(amount).
+  @Property({ type: 'numeric', columnType: 'numeric(18, 4)' })
+  amount!: string
+
+  @Property({ name: 'currency_code', type: 'text' })
+  currencyCode!: string
+
+  // Running balance AFTER this transaction — snapshotted from the atomic
+  // `UPDATE … RETURNING`. Enables audit + fast statement math without
+  // re-summing the whole ledger.
+  @Property({ name: 'balance_after', type: 'numeric', columnType: 'numeric(18, 4)' })
+  balanceAfter!: string
+
+  // FK (string) to BillingAccountUsage for type='usage'.
+  @Property({ name: 'usage_id', type: 'uuid', nullable: true })
+  usageId?: string | null
+
+  // FK (string) to the Billing Item that priced this debit.
+  @Property({ name: 'billing_item_id', type: 'uuid', nullable: true })
+  billingItemId?: string | null
+
+  // FK (string) to BillingTopup for type='topup'.
+  @Property({ name: 'topup_id', type: 'uuid', nullable: true })
+  topupId?: string | null
+
+  // FK (string) to the BillingStatement a period-close charge was rolled into.
+  @Property({ name: 'statement_id', type: 'uuid', nullable: true })
+  statementId?: string | null
+
+  @Property({ type: 'text' })
+  description!: string
+
+  // Idempotency key, unique per (tenant_id, bill_account_id, source_ref).
+  // usage debits = the usage record's source_ref; recurring =
+  // `recurring-{itemId}-{periodEndISO}`; topup = `topup-{paymentId}`.
+  @Property({ name: 'source_ref', type: 'text', nullable: true })
+  sourceRef?: string | null
+
+  // e.g. usage_tier_breakdown, uom_code, bill_period_start/end, gateway ids.
+  @Property({ type: 'jsonb', nullable: true })
+  metadata?: Record<string, unknown> | null
+
+  // Operator for manual `adjustment` / `reversal`.
+  @Property({ name: 'user_id', type: 'uuid', nullable: true })
+  userId?: string | null
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+
+  // Compliance erasure only.
+  @Property({ name: 'deleted_at', type: Date, nullable: true })
+  deletedAt?: Date | null
+}
+
+// ─── BillingTopup (SPEC-002 — the "registered top-up") ───────────
+//
+// One row per top-up attempt with a lifecycle (pending → captured | failed
+// | expired | cancelled), linked to its GatewayTransaction, its balance
+// credit transaction, and its VAT receipt invoice. "The balance went up"
+// is always explainable.
+
+@Entity({ tableName: 'billing_topups' })
+@Unique({
+  name: 'billing_topups_payment_id_unique',
+  properties: ['tenantId', 'paymentId'],
+})
+@Index({
+  name: 'billing_topups_account_history_idx',
+  properties: ['organizationId', 'tenantId', 'billAccountId', 'createdAt'],
+})
+@Index({
+  name: 'billing_topups_status_idx',
+  properties: ['tenantId', 'status'],
+})
+export class BillingTopup {
+  [OptionalProps]?:
+    | 'gatewayTransactionId'
+    | 'transactionId'
+    | 'receiptInvoiceId'
+    | 'sourceRef'
+    | 'metadata'
+    | 'createdAt'
+    | 'updatedAt'
+    | 'deletedAt'
+
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'organization_id', type: 'uuid' })
+  organizationId!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  @Property({ name: 'bill_account_id', type: 'uuid' })
+  billAccountId!: string
+
+  // 'pending' | 'captured' | 'failed' | 'expired' | 'cancelled'.
+  @Property({ type: 'text' })
+  status!: string
+
+  @Property({ type: 'numeric', columnType: 'numeric(18, 4)' })
+  amount!: string
+
+  @Property({ name: 'currency_code', type: 'text' })
+  currencyCode!: string
+
+  @Property({ name: 'provider_key', type: 'text' })
+  providerKey!: string
+
+  // The UUID we pass to createPaymentSession and match the captured event
+  // on. Unique per tenant.
+  @Property({ name: 'payment_id', type: 'uuid' })
+  paymentId!: string
+
+  // FK (string) to payment_gateways.GatewayTransaction once the session is
+  // created.
+  @Property({ name: 'gateway_transaction_id', type: 'uuid', nullable: true })
+  gatewayTransactionId?: string | null
+
+  // FK (string) to the credit BillingAccountTransaction written on capture.
+  @Property({ name: 'transaction_id', type: 'uuid', nullable: true })
+  transactionId?: string | null
+
+  // FK (string) to the core/sales VAT receipt invoice.
+  @Property({ name: 'receipt_invoice_id', type: 'uuid', nullable: true })
+  receiptInvoiceId?: string | null
+
+  // Optional idempotency for the initiating request.
+  @Property({ name: 'source_ref', type: 'text', nullable: true })
+  sourceRef?: string | null
+
+  // success_url / cancel_url, provider payload echoes.
+  @Property({ type: 'jsonb', nullable: true })
+  metadata?: Record<string, unknown> | null
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: Date, onUpdate: () => new Date() })
+  updatedAt: Date = new Date()
+
+  @Property({ name: 'deleted_at', type: Date, nullable: true })
+  deletedAt?: Date | null
+}
+
+// ─── BillingStatement (SPEC-002 — period close) ──────────────────
+//
+// A non-fiscal consumption summary for a prepaid account's bill period.
+// Chains cleanly: each statement's `opening_balance` equals the prior
+// statement's `closing_balance`. Anti-duplicate via the unique
+// (tenant_id, bill_account_id, period_start, period_end).
+
+@Entity({ tableName: 'billing_statements' })
+@Unique({
+  name: 'billing_statements_period_unique',
+  properties: ['tenantId', 'billAccountId', 'periodStart', 'periodEnd'],
+})
+@Index({
+  name: 'billing_statements_account_period_idx',
+  properties: ['organizationId', 'tenantId', 'billAccountId', 'periodEnd'],
+})
+export class BillingStatement {
+  [OptionalProps]?:
+    | 'billRunId'
+    | 'totalAdjustments'
+    | 'createdAt'
+    | 'updatedAt'
+
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'organization_id', type: 'uuid' })
+  organizationId!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  @Property({ name: 'bill_account_id', type: 'uuid' })
+  billAccountId!: string
+
+  // FK (string) to the BillRun that generated it (period close reuses the
+  // run engine). Null for a manually-generated statement.
+  @Property({ name: 'bill_run_id', type: 'uuid', nullable: true })
+  billRunId?: string | null
+
+  @Property({ name: 'period_start', type: 'date', columnType: 'date' })
+  periodStart!: Date
+
+  @Property({ name: 'period_end', type: 'date', columnType: 'date' })
+  periodEnd!: Date
+
+  @Property({ name: 'currency_code', type: 'text' })
+  currencyCode!: string
+
+  // Balance at period_start (= the prior statement's closing_balance).
+  @Property({ name: 'opening_balance', type: 'numeric', columnType: 'numeric(18, 4)' })
+  openingBalance!: string
+
+  // Sum of credits in window.
+  @Property({ name: 'total_topups', type: 'numeric', columnType: 'numeric(18, 4)' })
+  totalTopups!: string
+
+  // Sum of metered (real-time) usage debits in window (absolute).
+  @Property({ name: 'total_usage', type: 'numeric', columnType: 'numeric(18, 4)' })
+  totalUsage!: string
+
+  // Sum of recurring + one_time charges debited at this close (absolute).
+  @Property({ name: 'total_recurring', type: 'numeric', columnType: 'numeric(18, 4)' })
+  totalRecurring!: string
+
+  // Signed sum of manual adjustment + reversal movements in the window. Kept as
+  // its own term so the statement stays self-consistent (closing reproduces
+  // from the shown components) and the opening→closing chain never drifts.
+  @Property({ name: 'total_adjustments', type: 'numeric', columnType: 'numeric(18, 4)', default: '0' })
+  totalAdjustments: string = '0'
+
+  // opening + topups + adjustments − usage − recurring (= the period's net).
+  @Property({ name: 'closing_balance', type: 'numeric', columnType: 'numeric(18, 4)' })
+  closingBalance!: string
+
+  // Per billing_item_id: { billing_type, uom_code?, quantity, amount }.
+  @Property({ name: 'debit_breakdown', type: 'jsonb' })
+  debitBreakdown!: Record<string, unknown>
+
+  // 'generated' | 'sent'.
+  @Property({ type: 'text' })
+  status!: string
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: Date, onUpdate: () => new Date() })
+  updatedAt: Date = new Date()
+}

package/src/modules/billing/data/entityIds.ts

@@ -20,6 +20,11 @@ export const billingEntityIds = {
   run: 'billing:billing_run',
   runOutcome: 'billing:billing_run_outcome',
   draftInvoiceEdit: 'billing:billing_draft_invoice_edit',
+  // SPEC-002 (prepaid balance billing)
+  balance: 'billing:billing_account_balance',
+  transaction: 'billing:billing_account_transaction',
+  topup: 'billing:billing_topup',
+  statement: 'billing:billing_statement',
 } as const
 
 export type BillingEntityId = (typeof billingEntityIds)[keyof typeof billingEntityIds]

package/src/modules/billing/data/validators.ts

@@ -18,6 +18,9 @@ export const BILL_RUN_OUTCOME_STATUSES = [
   'success',
   'success_with_warnings',
   'skipped_existing_draft',
+  // SPEC-002: prepaid period close was skipped because a statement already
+  // exists for the window.
+  'skipped_existing_statement',
   'failed',
 ] as const
 export type BillRunOutcomeStatus = (typeof BILL_RUN_OUTCOME_STATUSES)[number]
@@ -28,6 +31,41 @@ export type DraftInvoiceEditAction = (typeof DRAFT_INVOICE_EDIT_ACTIONS)[number]
 export const INVOICE_STATUSES = ['draft', 'posted', 'paid', 'void'] as const
 export type InvoiceStatus = (typeof INVOICE_STATUSES)[number]
 
+// ─── Prepaid (SPEC-002) enums ────────────────────────────────────
+
+export const BILLING_MODES = ['postpaid', 'prepaid'] as const
+export type BillingMode = (typeof BILLING_MODES)[number]
+
+export const TRANSACTION_TYPES = [
+  'topup',
+  'usage',
+  'recurring',
+  'one_time',
+  'adjustment',
+  'reversal',
+] as const
+export type TransactionType = (typeof TRANSACTION_TYPES)[number]
+
+export const TOPUP_STATUSES = [
+  'pending',
+  'captured',
+  'failed',
+  'expired',
+  'cancelled',
+] as const
+export type TopupStatus = (typeof TOPUP_STATUSES)[number]
+
+export const STATEMENT_STATUSES = ['generated', 'sent'] as const
+export type StatementStatus = (typeof STATEMENT_STATUSES)[number]
+
+// Prepaid funds status (the account's own money).
+export const BALANCE_STATUSES = ['ok', 'low', 'exhausted'] as const
+export type BalanceStatus = (typeof BALANCE_STATUSES)[number]
+
+// Credit-line status (extended overdraft / AR exposure — both modes).
+export const CREDIT_STATUSES = ['within_limit', 'near_limit', 'over_limit'] as const
+export type CreditStatus = (typeof CREDIT_STATUSES)[number]
+
 // `mon`–`sun` for weekly cycles; 1–28 (as text) for the others.
 // Why text for numeric anchors: the column type stays uniform across cycles
 // and we never do arithmetic on the raw value (the engine parses it on use).
@@ -213,6 +251,10 @@ const listPaginationBase = {
 
 // ─── BillingAccount payloads ─────────────────────────────────────
 
+// numeric(18,4) money inputs arrive as numbers; the command coerces to a
+// 4dp string at persist time.
+const moneyNonNegative = z.number().finite().nonnegative()
+
 export const billingAccountCreateSchema = scopedSchema.extend({
   customerId: z.string().min(1).max(255),
   name: z.string().trim().min(1).max(255),
@@ -229,6 +271,14 @@ export const billingAccountCreateSchema = scopedSchema.extend({
   nextBillDate: z.coerce.date(),
   lastBillDate: z.coerce.date().optional(),
   isActive: z.boolean().optional(),
+  // SPEC-002: mode is immutable after create (like currencyCode). Default
+  // 'postpaid' so existing callers are unaffected.
+  billingMode: z.enum(BILLING_MODES).optional(),
+  // Credit line (both modes). 0 = no credit.
+  creditLimit: moneyNonNegative.optional(),
+  // Initial low-balance threshold for a prepaid account's balance row.
+  // Null = resolve the tenant config default at read time.
+  lowBalanceThreshold: moneyNonNegative.nullable().optional(),
 })
 
 export type BillingAccountCreateInput = z.infer<typeof billingAccountCreateSchema>
@@ -245,6 +295,13 @@ export const billingAccountUpdateSchema = scopedSchema.extend({
   nextBillDate: z.coerce.date().optional(),
   lastBillDate: z.coerce.date().nullable().optional(),
   isActive: z.boolean().optional(),
+  // SPEC-002: credit_limit is editable (it's an AR/overdraft policy knob);
+  // `billingMode` is intentionally NOT updatable — mode is frozen at create
+  // (like currencyCode), no live postpaid↔prepaid switch in v1.
+  creditLimit: moneyNonNegative.optional(),
+  // Editing the prepaid balance row's low-balance threshold. Null clears it
+  // back to the tenant config default.
+  lowBalanceThreshold: moneyNonNegative.nullable().optional(),
   // `currencyCode` is intentionally NOT updatable — currency is frozen at
   // account create time so historical invoices keep their currency context.
   // `customerId` is also immutable; create a new account if the customer
@@ -266,6 +323,7 @@ export const billingAccountListQuerySchema = z
     customerId: z.string().optional(),
     currencyCode: z.string().optional(),
     billCycle: z.enum(BILL_CYCLES).optional(),
+    billingMode: z.enum(BILLING_MODES).optional(),
     isActive: z.coerce.boolean().optional(),
     search: z.string().optional(),
   })
@@ -559,4 +617,90 @@ export const billingWipeTestInvoicesSchema = scopedSchema.extend({
 
 export type BillingWipeTestInvoicesInput = z.infer<typeof billingWipeTestInvoicesSchema>
 
+// ─── Prepaid: top-ups (SPEC-002 P2) ──────────────────────────────
+
+export const billingTopupCreateSchema = scopedSchema.extend({
+  // The route maps the `/accounts/{id}/topups` path param into billAccountId.
+  billAccountId: z.string().uuid(),
+  amount: z.number().finite().positive(),
+  // Optional — defaults to the tenant config `prepaid.topup_provider`.
+  providerKey: z.string().trim().min(1).max(64).optional(),
+  successUrl: z.string().trim().url().max(2048).optional(),
+  cancelUrl: z.string().trim().url().max(2048).optional(),
+  // Optional idempotency for the initiating request.
+  sourceRef: z.string().trim().min(1).max(255).optional(),
+})
+
+export type BillingTopupCreateInput = z.infer<typeof billingTopupCreateSchema>
+
+export const billingTopupListQuerySchema = z
+  .object({
+    ...listPaginationBase,
+    id: z.string().uuid().optional(),
+    billAccountId: z.string().uuid().optional(),
+    status: z.enum(TOPUP_STATUSES).optional(),
+    search: z.string().optional(),
+  })
+  .passthrough()
+
+export type BillingTopupListQuery = z.infer<typeof billingTopupListQuerySchema>
+
+// ─── Prepaid: transactions / manual adjustments (SPEC-002 P1/P5) ──
+
+export const billingTransactionAdjustSchema = scopedSchema
+  .extend({
+    billAccountId: z.string().uuid(),
+    // SIGNED: > 0 credit, < 0 debit. Zero is rejected.
+    amount: z.number().finite(),
+    description: z.string().trim().min(1).max(500),
+    sourceRef: z.string().trim().min(1).max(255).optional(),
+  })
+  .superRefine((val, ctx) => {
+    if (val.amount === 0) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['amount'],
+        message: 'amount must be non-zero (positive credit or negative debit)',
+      })
+    }
+  })
+
+export type BillingTransactionAdjustInput = z.infer<typeof billingTransactionAdjustSchema>
+
+export const billingTransactionListQuerySchema = z
+  .object({
+    ...listPaginationBase,
+    id: z.string().uuid().optional(),
+    billAccountId: z.string().uuid().optional(),
+    type: z.enum(TRANSACTION_TYPES).optional(),
+    createdFrom: z.coerce.date().optional(),
+    createdTo: z.coerce.date().optional(),
+  })
+  .passthrough()
+
+export type BillingTransactionListQuery = z.infer<typeof billingTransactionListQuerySchema>
+
+// ─── Prepaid: statements (SPEC-002 P3) ───────────────────────────
+
+export const billingStatementGenerateSchema = scopedSchema.extend({
+  billAccountId: z.string().uuid(),
+  // "today" the close evaluates the due period against. Defaults to now.
+  asOfDate: z.coerce.date().optional(),
+})
+
+export type BillingStatementGenerateInput = z.infer<typeof billingStatementGenerateSchema>
+
+export const billingStatementListQuerySchema = z
+  .object({
+    ...listPaginationBase,
+    id: z.string().uuid().optional(),
+    billAccountId: z.string().uuid().optional(),
+    status: z.enum(STATEMENT_STATUSES).optional(),
+    periodEndFrom: z.coerce.date().optional(),
+    periodEndTo: z.coerce.date().optional(),
+  })
+  .passthrough()
+
+export type BillingStatementListQuery = z.infer<typeof billingStatementListQuerySchema>
+
 

package/src/modules/billing/events.ts

@@ -34,6 +34,58 @@ const events = [
     category: 'lifecycle',
     clientBroadcast: true,
   },
+  // ─── Prepaid balance billing (SPEC-002) ──────────────────────
+  {
+    id: 'billing.balance.topped_up',
+    label: 'Balance Topped Up',
+    entity: 'balance',
+    category: 'lifecycle',
+    clientBroadcast: true,
+  },
+  {
+    id: 'billing.balance.low',
+    label: 'Balance Low',
+    entity: 'balance',
+    category: 'lifecycle',
+    clientBroadcast: true,
+  },
+  {
+    id: 'billing.balance.exhausted',
+    label: 'Balance Exhausted',
+    entity: 'balance',
+    category: 'lifecycle',
+    clientBroadcast: true,
+  },
+  {
+    // Per-debit signal — useful for a live balance UI but potentially
+    // high-volume, so excluded from workflow triggers (see Open Question #2).
+    id: 'billing.usage.rated',
+    label: 'Usage Rated',
+    entity: 'transaction',
+    category: 'lifecycle',
+    excludeFromTriggers: true,
+  },
+  {
+    id: 'billing.statement.generated',
+    label: 'Consumption Statement Generated',
+    entity: 'statement',
+    category: 'lifecycle',
+    clientBroadcast: true,
+  },
+  {
+    id: 'billing.credit.over_limit',
+    label: 'Credit Over Limit',
+    entity: 'credit',
+    category: 'lifecycle',
+    clientBroadcast: true,
+  },
+  {
+    id: 'billing.credit.near_limit',
+    label: 'Credit Near Limit',
+    entity: 'credit',
+    category: 'lifecycle',
+    clientBroadcast: true,
+  },
 ] as const
 
 export const eventsConfig = createModuleEvents({