@ambushsoftworks/nestjs-payments-graphql 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,90 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.2] - 2026-04-19
+
+### Fixed
+- **CI publish pipeline** — switched the publish job to `node:24`, which ships with npm 11.x and supports OIDC trusted publishing natively. The previous config ran `npm install -g npm@latest` on top of node:22's bundled npm 10.9.x, which failed with `MODULE_NOT_FOUND: promise-retry` during npm's self-upgrade. 0.1.2 is the first version since 0.1.0 to actually land on the npm registry.
+
+0.1.2 contains all the 0.1.1 content — README, CHANGELOG, CONTRIBUTING, LICENSE, `prisma/payment-models.prisma`, Jest config and tests, and the `package.json` metadata additions.
+
+## [0.1.1] - 2026-04-19
+
+> **Note:** Tagged in git but never published to npm — the CI publish stage failed on an upstream `npm install -g npm@latest` self-upgrade bug. Superseded by 0.1.2 with an identical feature set.
+
+Docs and tooling release. No runtime code changed — compiled `dist/` output is identical to 0.1.0.
+
+### Added
+- `README.md` — full public-facing documentation (design principles, install, quick-start, features, configuration reference, reserved GraphQL type names, exception table, critical integration requirements, local development workflow).
+- `CHANGELOG.md`, `CONTRIBUTING.md`, `LICENSE` (MIT).
+- `prisma/payment-models.prisma` — documentation-only reference schema shipped inside the package tarball. Covers every model and enum (core, payment plans, recurring invoices, payment customers, webhook idempotency). Consumer-owned relations marked `// CONSUMER:` for easy copy-paste into a host `schema.prisma`.
+- Jest configuration (inline in `package.json`) and the first test suites: `recurring-interval.util.spec.ts` (19 cases covering DAYS/MONTHS math, month-end clamp, leap years, year rollover, round-tripping with `computeCycleCount`) and `invoice-number.service.spec.ts` (7 cases covering first-number, increment, zero-padding past 10k, unparseable-max fallback, and global numbering across divisions). `.gitlab-ci.yml`'s `test` stage now exercises real code instead of silently passing.
+- `package.json` metadata: `keywords`, `homepage`, `bugs` URL. `CHANGELOG.md` added to `files[]`.
+
+### Changed
+- `.gitignore` now excludes `*.tsbuildinfo` (TypeScript incremental build cache was previously tracked by accident) and `docs/archive/` (local-only planning docs).
+
+## [0.1.0] - 2026-04-19
+
+### Added
+
+Initial public release. Extracted from the Ariadne monorepo (`apps/api/src/payments/core/`) into a standalone, ORM-agnostic NestJS package.
+
+#### Core features
+
+- **Invoicing** — `InvoiceService` creates DRAFT invoices with optional line items, tax rate resolution, metadata, and globally unique invoice numbers (via `InvoiceNumberService` with retry-on-collision).
+- **Payments** — `PaymentService` records manual payments, online/Stripe payments, and e-transfer payments. Uses row-level locking and sum-of-pending-confirmation checks to prevent over-payment.
+- **Refunds** — `RefundService` supports full and partial refunds, Stripe-backed and manual, with automatic invoice status transitions.
+- **Payment plans** — `PaymentPlanService` splits invoices into installments with per-installment due dates and status tracking.
+- **Recurring invoices** — `RecurringInvoiceService` auto-generates invoices on a schedule with anchor-date interval math (`DAYS`/`MONTHS`), optional auto-charge via stored `PaymentCustomer`, and consecutive-failure auto-pause.
+- **E-transfer** — `ETransferService` generates prefixed codes + security answers and GraphQL instructions for Canadian Interac e-transfer flows.
+- **Composable email notifications** — `IPaymentEmailSender` + `IPaymentEmailTemplateRenderer` + `IPaymentEmailBrandingResolver` + `IPaymentClientResolver`. Ships `StaticBrandingResolver` and `DefaultPaymentEmailTemplateRenderer`.
+- **Event listeners** — consumer-registered `IPaymentEventListener` with hooks for `onInvoicePaid`, `onInvoiceRefunded`, `onRecurringInvoiceGenerated`, `onRecurringPaymentFailed`, `onRecurringInvoicePaused`. Event payloads include invoice metadata and full line items.
+
+#### Stripe integration
+
+- Bundled `StripeGateway` plus `StripeWebhookController` mounted at `POST /webhooks/stripe`.
+- `@PaymentsWebhook()` decorator (also sets `isPublic` + `skipTenant` metadata) and `PAYMENTS_WEBHOOK` string constant for consumer auth-guard exemption.
+- Webhook idempotency via `IWebhookIdempotencyRepository`.
+- Signature verification requires `rawBody: true` in `NestFactory.create()`.
+- Payment-succeeded retry loop (3 attempts, 2s delay) for out-of-order webhook deliveries.
+- Optional `webhook.errorReporter` hook for Sentry/GlitchTip/etc.
+- `stripe@^17.0.0` bundled as a hard dependency.
+
+#### Module & DI
+
+- `PaymentsModule.forRootAsync()` dynamic module registered as `global: true`.
+- Instance-based DI for all repositories and adapters.
+- Startup validation throws when feature flags are enabled without their backing repositories or config.
+- All tokens are exported as `Symbol` constants (`INVOICE_REPOSITORY`, `PAYMENT_REPOSITORY`, `TRANSACTION_MANAGER`, …).
+- Internal services use `ModuleRef.get()` instead of `@Optional() @Inject()` to work around a NestJS DI bug affecting optional tokens with `forwardRef()` imports.
+
+#### GraphQL types
+
+- 17 `@ObjectType` classes, 8 `@registerEnumType` enums, and 15+ `@InputType` classes exported. Enums are registered as a side effect of importing `PaymentsModule` — consumers must not re-register them.
+
+#### Exceptions
+
+- Domain exceptions (`InvalidInvoiceStateException`, `PaymentAmountExceededException`, `PaymentGatewayException`, `DuplicatePaymentException`, `InvoiceNotPayableException`, `InvoiceNumberExhaustedException`, `RefundNotAllowedException`, `InvalidPaymentStateException`, `InvalidRecurringInvoiceStateException`, `UniqueConstraintViolationException`) all extend `PaymentException` with stable `.code` strings.
+
+#### Utilities
+
+- `computeNextInvoiceDate` / `computeCycleCount` — anchor-based recurring-interval math.
+- `StaticBrandingResolver` — single-tenant branding resolver.
+- `DefaultPaymentEmailTemplateRenderer` — responsive inline-styled email HTML.
+
+### CI/CD
+
+- GitLab pipeline at `.gitlab-ci.yml`.
+- `test` stage runs on merge requests and tags.
+- `publish` stage runs on git tags, publishing to npm via OIDC provenance (`npm publish --provenance --access public`). No static npm token required.
+
+### Infrastructure
+
+- Currently running in production on the Ariadne API (Railway deployment, consumes `@ambushsoftworks/nestjs-payments-graphql@^0.1.0` from npm).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ambush Softworks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,609 @@
+# @ambushsoftworks/nestjs-payments-graphql
+
+Production-grade payments module for NestJS with GraphQL support. Invoicing, Stripe payment processing, refunds, payment plans, recurring invoicing with auto-charge, e-transfer, and composable email notifications — with zero database coupling.
+
+## Table of Contents
+
+- [Design Principles](#design-principles)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Architecture](#architecture)
+- [Features](#features)
+  - [Invoicing](#invoicing)
+  - [Stripe Gateway & Webhooks](#stripe-gateway--webhooks)
+  - [Refunds](#refunds)
+  - [Payment Plans](#payment-plans)
+  - [Recurring Invoices](#recurring-invoices)
+  - [E-Transfer](#e-transfer)
+  - [Email Notifications](#email-notifications)
+  - [Event Listeners](#event-listeners)
+  - [Transactions](#transactions)
+- [Configuration Reference](#configuration-reference)
+  - [Required Options](#required-options)
+  - [Optional Repositories](#optional-repositories)
+  - [Stripe Options](#stripe-options)
+  - [Email Options](#email-options)
+  - [Defaults & Feature Flags](#defaults--feature-flags)
+- [DI Tokens](#di-tokens)
+- [Reserved GraphQL Type Names](#reserved-graphql-type-names)
+- [Exceptions](#exceptions)
+- [Critical Integration Requirements](#critical-integration-requirements)
+- [Local Development](#local-development)
+- [License](#license)
+
+---
+
+## Design Principles
+
+- **Interface-driven persistence** — All storage is behind interfaces (`IInvoiceRepository`, `IPaymentRepository`, `IRefundRepository`, etc.). Bring your own ORM; Prisma is the expected default, but any ORM works.
+- **Instance-based DI** — Repositories and adapters are injected as instances via `useFactory`, not as classes.
+- **Framework-agnostic core** — Services are pure business logic. Resolvers, schedulers, and Prisma adapters live in your application.
+- **Consumer owns GraphQL decoration** — The package ships `@ObjectType`/`@InputType` classes. You build resolvers that call services and return these types.
+- **Composable email** — A sender (transport) plus a renderer (HTML) plus a branding resolver plus a client resolver. All but the first two are optional with sane defaults.
+- **Stripe is bundled, not required** — The Stripe gateway and webhook controller ship with the package, but are only activated when `stripe` config is provided.
+
+---
+
+## Installation
+
+```bash
+npm install @ambushsoftworks/nestjs-payments-graphql
+# or
+pnpm add @ambushsoftworks/nestjs-payments-graphql
+```
+
+### Peer Dependencies
+
+```bash
+npm install @nestjs/common @nestjs/core @nestjs/graphql \
+  class-transformer class-validator graphql graphql-type-json \
+  reflect-metadata rxjs
+```
+
+`stripe` is bundled as a hard dependency of this package — you do not need to install it separately.
+
+---
+
+## Quick Start
+
+A minimal setup: invoices, manual payments, and a Stripe gateway.
+
+### 1. Implement the required repositories
+
+Each repository is a pure TypeScript interface backed by your ORM. Here is the sketch for Prisma. A ready-to-copy reference schema lives at [`prisma/payment-models.prisma`](./prisma/payment-models.prisma) and ships inside the npm tarball — it contains every model and enum you need, with consumer-owned relations marked `// CONSUMER:`.
+
+```typescript
+// prisma-invoice.repository.ts
+import { Injectable } from '@nestjs/common';
+import { PrismaService } from './prisma.service';
+import {
+  IInvoiceRepository,
+  UniqueConstraintViolationException,
+} from '@ambushsoftworks/nestjs-payments-graphql';
+
+@Injectable()
+export class PrismaInvoiceRepository implements IInvoiceRepository {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async create(data) {
+    try {
+      return await this.prisma.invoice.create({ data });
+    } catch (e: any) {
+      if (e.code === 'P2002') throw new UniqueConstraintViolationException();
+      throw e;
+    }
+  }
+
+  async findById(id) { return this.prisma.invoice.findUnique({ where: { id } }); }
+  // ... implement the rest of IInvoiceRepository
+  async withTransaction(fn) {
+    return this.prisma.$transaction(async (tx) => {
+      const scoped = new PrismaInvoiceRepository({ ...this.prisma, invoice: tx.invoice } as any);
+      return fn(scoped);
+    });
+  }
+}
+```
+
+Repositories you must implement:
+
+| Interface | Purpose |
+|-----------|---------|
+| `IInvoiceRepository` | Invoice + line item persistence |
+| `IPaymentRepository` | Payment records |
+| `IRefundRepository` | Refund records |
+| `IPaymentConfigRepository` | Per-division payment config + providers |
+| `IWebhookIdempotencyRepository` | Dedupe Stripe webhook deliveries |
+| `ITransactionManager` | Multi-repo transaction coordinator |
+
+Opt-in interfaces:
+
+| Interface | Required when |
+|-----------|---------------|
+| `IPaymentPlanRepository` | `features.paymentPlans = true` |
+| `IRecurringInvoiceRepository` | `features.recurringInvoices = true` |
+| `IPaymentCustomerRepository` | `features.recurringInvoices = true` |
+
+### 2. Register the module
+
+```typescript
+import { Module } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { PaymentsModule } from '@ambushsoftworks/nestjs-payments-graphql';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot(),
+    PaymentsModule.forRootAsync({
+      imports: [ConfigModule, MyRepositoriesModule, MyAdaptersModule],
+      inject: [
+        PrismaInvoiceRepository,
+        PrismaPaymentRepository,
+        PrismaRefundRepository,
+        PrismaPaymentConfigRepository,
+        PrismaWebhookIdempotencyRepository,
+        PrismaTransactionManager,
+        ConfigService,
+      ],
+      useFactory: (invoices, payments, refunds, config, webhooks, tx, cfg) => ({
+        invoiceRepositoryInstance: invoices,
+        paymentRepositoryInstance: payments,
+        refundRepositoryInstance: refunds,
+        paymentConfigRepositoryInstance: config,
+        webhookIdempotencyRepositoryInstance: webhooks,
+        transactionManagerInstance: tx,
+
+        stripe: {
+          secretKey: cfg.get('STRIPE_SECRET_KEY'),
+          webhookSecret: cfg.get('STRIPE_WEBHOOK_SECRET'),
+        },
+
+        defaultCurrency: 'USD',
+      }),
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### 3. Enable `rawBody` for Stripe signature verification
+
+Stripe's webhook signature check requires the unparsed request body.
+
+```typescript
+// main.ts
+const app = await NestFactory.create(AppModule, { rawBody: true });
+```
+
+### 4. Exempt the webhook path from auth
+
+The controller is registered at `POST /webhooks/stripe` and marked with `@PaymentsWebhook()`. Your auth/tenant guards must respect this metadata. Either:
+
+- Have guards check `Reflector.get(PAYMENTS_WEBHOOK, handler)` and bail out early, **or**
+- Have guards check the route path against the exported `PAYMENTS_WEBHOOK` string constant.
+
+See [Critical Integration Requirements](#critical-integration-requirements).
+
+### 5. Build a resolver
+
+```typescript
+import { Resolver, Mutation, Args } from '@nestjs/graphql';
+import {
+  InvoiceService,
+  InvoiceModel,
+  CreateInvoiceInput,
+} from '@ambushsoftworks/nestjs-payments-graphql';
+
+@Resolver()
+export class InvoiceResolver {
+  constructor(private readonly invoices: InvoiceService) {}
+
+  @Mutation(() => InvoiceModel)
+  async createInvoice(
+    @Args('input') input: CreateInvoiceInput,
+    // resolve divisionId + userId from your auth/tenant context
+  ) {
+    return this.invoices.createInvoice(divisionId, input, userId);
+  }
+}
+```
+
+---
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  Consumer App (e.g. Ariadne API)                             │
+│  ──────────────────────────────                              │
+│  • Prisma repositories (implements IInvoiceRepository, ...)  │
+│  • Resolvers (GraphQL queries/mutations)                     │
+│  • Schedulers (@nestjs/schedule)                             │
+│  • Auth guards (respect @PaymentsWebhook metadata)           │
+│  • Event listener (implements IPaymentEventListener)         │
+│  • Email adapters (IPaymentEmailSender, IPaymentClient...)   │
+│                                                              │
+│  Wires together via PaymentsModule.forRootAsync({ ... })     │
+└──────────────────────────────────────────────────────────────┘
+                              ↓ imports
+┌──────────────────────────────────────────────────────────────┐
+│  @ambushsoftworks/nestjs-payments-graphql                    │
+│  ─────────────────────────────────────────                   │
+│  • Services (pure business logic)                            │
+│  • Interfaces (what consumer must implement)                 │
+│  • DI tokens (Symbols)                                       │
+│  • GraphQL models + input types                              │
+│  • StripeGateway + StripeWebhookController (opt-in)          │
+│  • Exceptions                                                │
+└──────────────────────────────────────────────────────────────┘
+```
+
+The dynamic module is registered as `global: true` — any module in your app can inject services and tokens without re-importing.
+
+---
+
+## Features
+
+### Invoicing
+
+- Create DRAFT invoices with optional line items.
+- Line item edits allowed only in DRAFT; totals auto-recalculate on mutation.
+- `InvoiceNumberService` generates globally-unique numbers against a per-division prefix, retrying on unique-constraint collisions up to 5 times.
+- Tax rate resolution: use the value passed on `createInvoice` if provided, otherwise `PaymentConfig.defaultTaxRate` for the division, otherwise `0`.
+- Status transitions: `DRAFT → SENT → {PARTIALLY_PAID, PAID, OVERDUE, VOID, REFUNDED}`.
+- Invoice `metadata` is a Stripe-style `Record<string, string>` for consumer-specific context.
+
+### Stripe Gateway & Webhooks
+
+When `stripe` config is provided, the module registers `StripeGateway` and mounts `POST /webhooks/stripe`. Webhook security relies entirely on Stripe signature verification. Behaviour:
+
+- **Idempotency** — every event ID is recorded via `IWebhookIdempotencyRepository` before the handler runs; replays no-op.
+- **Retries** — `payment_intent.succeeded` events retry up to 3 times with a 2-second delay if the corresponding `Payment` row has not yet been created.
+- **Error reporting** — configure `webhook.errorReporter` to pipe exceptions into Sentry/GlitchTip/etc.
+
+`GatewayRegistryService` keeps a runtime lookup of registered gateways so the package can work without `@Optional() @Inject()`.
+
+### Refunds
+
+Full and partial refunds through Stripe (when the originating payment went through Stripe) or manual refund records. All amounts in cents.
+
+### Payment Plans
+
+Split an invoice into installments with per-installment due dates.
+
+Enable:
+
+```typescript
+features: { paymentPlans: true },
+paymentPlanRepositoryInstance: paymentPlanRepo,
+```
+
+Each installment can optionally reference a generated invoice; the service tracks `PENDING → INVOICED → PAID → OVERDUE → WAIVED → CANCELLED`.
+
+### Recurring Invoices
+
+Auto-generates invoices on a recurring schedule. Supports `DAYS` and `MONTHS` interval units anchored to an original date (handles month-end correctly via `computeNextInvoiceDate`).
+
+Enable:
+
+```typescript
+features: { recurringInvoices: true },
+recurringInvoiceRepositoryInstance: recurringRepo,
+paymentCustomerRepositoryInstance: paymentCustomerRepo,
+```
+
+Phase 2 auto-charge: when `autoCharge: true`, the scheduler pulls the stored `PaymentCustomer` for the client, issues a charge via the gateway, and fires either `onRecurringInvoiceGenerated` or `onRecurringPaymentFailed`. Consecutive failures can auto-pause the schedule (`onRecurringInvoicePaused`).
+
+Utility helpers exported:
+
+```typescript
+import {
+  computeNextInvoiceDate,
+  computeCycleCount,
+} from '@ambushsoftworks/nestjs-payments-graphql';
+```
+
+The consumer provides the scheduler (typically `@nestjs/schedule`) that calls `RecurringInvoiceService.generateDue()` and friends on a cron.
+
+### E-Transfer
+
+Canadian Interac e-transfer flow: `ETransferService` generates human-readable codes (`<prefix>-<invoice>-<random>`) and security answers, then exposes GraphQL instructions for the client.
+
+Enable:
+
+```typescript
+features: { eTransfer: true },
+eTransferCodePrefix: 'ARD-', // whatever short prefix makes sense for your brand
+```
+
+### Email Notifications
+
+Composable: transport + rendering + branding + client lookup.
+
+```typescript
+import {
+  PaymentsModule,
+  StaticBrandingResolver,
+  DefaultPaymentEmailTemplateRenderer,
+} from '@ambushsoftworks/nestjs-payments-graphql';
+
+PaymentsModule.forRootAsync({
+  useFactory: (..., emailSender, clientResolver) => ({
+    // ... required deps
+    features: { emailNotifications: true },
+    email: {
+      senderInstance: emailSender,
+      clientResolverInstance: clientResolver,
+      brandingResolverInstance: new StaticBrandingResolver({
+        appName: 'My App',
+        primaryColor: '#1976D2',
+        fromEmail: 'billing@example.com',
+        fromName: 'My App Billing',
+        companyName: 'My App Inc.',
+        supportEmail: 'support@example.com',
+      }),
+      templateRendererInstance: new DefaultPaymentEmailTemplateRenderer(),
+    },
+  }),
+});
+```
+
+You implement:
+
+- **`IPaymentEmailSender`** — a `send()` method that posts to your transport (Resend, SendGrid, SES, etc.).
+- **`IPaymentClientResolver`** — returns `{ email, name } | null` for a `clientDetailsId`. Returning `null` skips that email silently.
+
+You can override:
+
+- **`IPaymentEmailBrandingResolver`** — per-division branding. Use `StaticBrandingResolver` for single-tenant apps.
+- **`IPaymentEmailTemplateRenderer`** — full HTML control (e.g. React Email, MJML, Handlebars). `DefaultPaymentEmailTemplateRenderer` ships inline-styled responsive templates.
+
+Covered emails: invoice sent, e-transfer instructions, payment confirmation, overdue reminder, refund confirmation.
+
+### Event Listeners
+
+Register a single `IPaymentEventListener` to react to domain events without touching services. All handlers except `onInvoicePaid` are optional.
+
+```typescript
+paymentEventListenerInstance: {
+  async onInvoicePaid(event) { /* fulfill the order, confirm the booking, ... */ },
+  async onInvoiceRefunded(event) { /* undo fulfillment */ },
+  async onRecurringInvoiceGenerated(event) { /* notify, audit */ },
+  async onRecurringPaymentFailed(event) { /* alert, retry */ },
+  async onRecurringInvoicePaused(event) { /* notify billing team */ },
+}
+```
+
+Event payloads include `metadata` from the invoice plus the full `lineItems` snapshot so consumers don't need to re-query.
+
+### Transactions
+
+`ITransactionManager.runInTransaction(fn)` gives the callback a `TransactionRepositories` bag with all repositories bound to the same ORM transaction. The package uses this internally when recording payments and mutating totals.
+
+```typescript
+await transactionManager.runInTransaction(async (repos) => {
+  const invoice = await repos.invoices.findByIdForUpdate(id);
+  await repos.payments.create({ ... });
+  await repos.invoices.update(id, { amountPaid: invoice.amountPaid + amount });
+});
+```
+
+---
+
+## Configuration Reference
+
+### Required Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `invoiceRepositoryInstance` | `IInvoiceRepository` | Invoice + line item persistence |
+| `paymentRepositoryInstance` | `IPaymentRepository` | Payment records |
+| `refundRepositoryInstance` | `IRefundRepository` | Refund records |
+| `paymentConfigRepositoryInstance` | `IPaymentConfigRepository` | Per-division payment config |
+| `webhookIdempotencyRepositoryInstance` | `IWebhookIdempotencyRepository` | Stripe webhook dedupe |
+| `transactionManagerInstance` | `ITransactionManager` | Multi-repo transactions |
+
+### Optional Repositories
+
+| Option | Required when |
+|--------|---------------|
+| `paymentPlanRepositoryInstance` | `features.paymentPlans` is enabled |
+| `recurringInvoiceRepositoryInstance` | `features.recurringInvoices` is enabled |
+| `paymentCustomerRepositoryInstance` | `features.recurringInvoices` is enabled |
+
+### Stripe Options
+
+```typescript
+stripe: {
+  secretKey: string;
+  webhookSecret: string;
+}
+```
+
+Omit the entire `stripe` key for non-Stripe deployments. A warning logs at startup if no gateway is configured.
+
+### Email Options
+
+```typescript
+email: {
+  senderInstance: IPaymentEmailSender;        // required
+  clientResolverInstance: IPaymentClientResolver; // required
+  brandingResolverInstance?: IPaymentEmailBrandingResolver;  // optional
+  templateRendererInstance?: IPaymentEmailTemplateRenderer;  // optional
+}
+```
+
+Required when `features.emailNotifications` is enabled.
+
+### Defaults & Feature Flags
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `defaultCurrency` | `string` | `'USD'` | ISO 4217 currency used when an invoice omits one |
+| `eTransferCodePrefix` | `string` | `''` | Short prefix prepended to generated e-transfer codes |
+| `webhook.errorReporter` | `(err, ctx) => void` | — | Forward webhook errors to Sentry/GlitchTip/etc. |
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `features.paymentPlans` | `false` | Enable payment-plan services + GraphQL types |
+| `features.recurringInvoices` | `false` | Enable recurring invoice services + auto-charge |
+| `features.eTransfer` | `false` | Enable e-transfer code generation and instruction emails |
+| `features.emailNotifications` | `false` | Enable outbound email; requires `email` config |
+
+Validation runs when the module boots. Enabling a feature without providing the backing repository or config throws at startup.
+
+---
+
+## DI Tokens
+
+All DI tokens are exported from the package as `Symbol`s. Use them with `ModuleRef.get()` (see [Critical Integration Requirements](#critical-integration-requirements)).
+
+```typescript
+import {
+  INVOICE_REPOSITORY,
+  PAYMENT_REPOSITORY,
+  REFUND_REPOSITORY,
+  PAYMENT_PLAN_REPOSITORY,
+  PAYMENT_CONFIG_REPOSITORY,
+  WEBHOOK_IDEMPOTENCY_REPOSITORY,
+  RECURRING_INVOICE_REPOSITORY,
+  PAYMENT_CUSTOMER_REPOSITORY,
+  TRANSACTION_MANAGER,
+  PAYMENT_EVENT_LISTENER,
+  PAYMENT_EMAIL_SENDER,
+  PAYMENT_CLIENT_RESOLVER,
+  PAYMENT_EMAIL_BRANDING_RESOLVER,
+  PAYMENT_EMAIL_TEMPLATE_RENDERER,
+  WEBHOOK_ERROR_REPORTER,
+  DEFAULT_CURRENCY,
+  E_TRANSFER_CODE_PREFIX,
+} from '@ambushsoftworks/nestjs-payments-graphql';
+```
+
+---
+
+## Reserved GraphQL Type Names
+
+The package registers these names on module import. Consumers **must not** redefine or re-register them, or GraphQL will throw `"type already registered"`.
+
+**Object types:** `Invoice`, `InvoiceLineItem`, `InvoiceClient`, `Payment`, `Refund`, `PaymentPlan`, `PaymentPlanInstallment`, `PaymentConfig`, `PaymentProvider`, `PaymentMethodSetup`, `ETransferInstructions`, `OnlinePaymentSession`, `RecurringInvoice`, `RecurringInvoiceLineItem`, `PaginatedInvoices`, `PaginatedPaymentPlans`, `PaginatedRecurringInvoices`
+
+**Enums:** `InvoiceStatus`, `PaymentMethod`, `PaymentStatus`, `RefundStatus`, `PaymentPlanStatus`, `InstallmentStatus`, `RecurringIntervalUnit`, `RecurringInvoiceStatus`
+
+**Input types:** `CreateInvoiceInput`, `CreateLineItemInput`, `CreateRefundInput`, `CreateInstallmentInput`, `CreatePaymentPlanInput`, `CreateRecurringInvoiceInput`, `CreateRecurringLineItemInput`, `RecordManualPaymentInput`, `UpdatePaymentConfigInput`, `UpdateInvoiceMetadataInput`, `UpdateRecurringTemplateInput`, `UpsertPaymentProviderInput`, `InvoiceFilterInput`, `PaymentPlanFilterInput`, `RecurringInvoiceFilterInput`
+
+---
+
+## Exceptions
+
+All exceptions extend `PaymentException` (a plain `Error` subclass) with a stable `.code` string so consumers can map them to GraphQL/HTTP status codes.
+
+| Exception | `.code` |
+|-----------|---------|
+| `InvalidInvoiceStateException` | `INVALID_INVOICE_STATE` |
+| `PaymentAmountExceededException` | `PAYMENT_AMOUNT_EXCEEDED` |
+| `PaymentGatewayException` | `PAYMENT_GATEWAY_ERROR` |
+| `DuplicatePaymentException` | `DUPLICATE_PAYMENT` |
+| `InvoiceNotPayableException` | `INVOICE_NOT_PAYABLE` |
+| `InvoiceNumberExhaustedException` | `INVOICE_NUMBER_EXHAUSTED` |
+| `RefundNotAllowedException` | `REFUND_NOT_ALLOWED` |
+| `InvalidPaymentStateException` | `INVALID_PAYMENT_STATE` |
+| `InvalidRecurringInvoiceStateException` | `INVALID_RECURRING_INVOICE_STATE` |
+| `UniqueConstraintViolationException` | `UNIQUE_CONSTRAINT_VIOLATION` |
+
+Repository adapters are responsible for translating ORM-specific unique-constraint errors (e.g. Prisma `P2002`) into `UniqueConstraintViolationException` so core services stay ORM-agnostic.
+
+---
+
+## Critical Integration Requirements
+
+### 1. Use `ModuleRef.get()` for package tokens
+
+There is a known NestJS bug where `@Optional() @Inject(TOKEN)` combined with `forwardRef()` module imports delivers `null` even when the provider exists. The package itself works around this internally. **Consumer code that needs a package token must do the same:**
+
+```typescript
+// BAD — will fail with "Nest can't resolve dependencies"
+constructor(@Inject(WEBHOOK_IDEMPOTENCY_REPOSITORY) private readonly repo: IWebhookIdempotencyRepository) {}
+
+// GOOD — resolve lazily in onModuleInit
+constructor(private readonly moduleRef: ModuleRef) {}
+onModuleInit() {
+  this.repo = this.moduleRef.get(WEBHOOK_IDEMPOTENCY_REPOSITORY, { strict: false });
+}
+```
+
+### 2. Do not re-register GraphQL enums
+
+`PaymentsModule` imports `register-payment-enums.ts` as a side effect, which calls `registerEnumType()` for every enum listed under [Reserved GraphQL Type Names](#reserved-graphql-type-names). Remove any duplicate `registerEnumType()` calls from your app.
+
+### 3. Exempt `/webhooks/stripe` from auth
+
+The webhook controller mounts at a fixed path and is decorated with `@PaymentsWebhook()`. Your auth/tenant guards must either:
+
+- Check for the `PAYMENTS_WEBHOOK` metadata key via `Reflector`, **or**
+- Skip the route by path (use the exported `PAYMENTS_WEBHOOK` constant if you match on string keys).
+
+`@PaymentsWebhook()` also sets `isPublic` and `skipTenant` metadata, so guards that honour those keys work out of the box.
+
+### 4. Enable `rawBody` in `NestFactory.create()`
+
+Stripe signature verification requires the unparsed request body:
+
+```typescript
+const app = await NestFactory.create(AppModule, { rawBody: true });
+```
+
+### 5. Translate ORM errors to `UniqueConstraintViolationException`
+
+Repository adapters must catch ORM-specific unique constraint errors and rethrow as `UniqueConstraintViolationException` so core services (especially `InvoiceNumberService`) can apply their retry logic.
+
+### 6. Use `"moduleResolution": "nodenext"` friendly imports
+
+The `package.json` has an explicit `exports` field, so `nodenext` resolution is supported. If you use `node16`/`nodenext`, you do not need to opt into any special import syntax.
+
+---
+
+## Local Development
+
+### Developing the package alongside a consumer
+
+Terminal 1 — package watch mode:
+
+```bash
+cd nestjs-payments-graphql
+pnpm link --global
+pnpm run build:watch
+```
+
+Terminal 2 — consumer:
+
+```bash
+cd my-app
+pnpm link --global @ambushsoftworks/nestjs-payments-graphql
+pnpm start:dev
+```
+
+Before committing or deploying the consumer:
+
+```bash
+cd my-app
+pnpm uninstall @ambushsoftworks/nestjs-payments-graphql
+pnpm install
+```
+
+**Do not** commit `package.json` or `pnpm-lock.yaml` with a `link:` or `workspace:` reference to this package. BuildKit-based deploys (e.g. Railway) cannot resolve those references.
+
+### Publishing
+
+```bash
+npm version patch   # or minor/major
+git push --follow-tags
+```
+
+GitLab CI publishes to npm via OIDC provenance on tag push. See `.gitlab-ci.yml` for the pipeline.
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ambushsoftworks/nestjs-payments-graphql",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "NestJS payments module with GraphQL support — invoicing, payment processing, recurring billing, and email notifications",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,7 +14,8 @@
     "dist",
     "prisma",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
@@ -65,6 +66,44 @@
     "type": "git",
     "url": "https://gitlab.com/ambushworks/nestjs-payments-graphql.git"
   },
+  "jest": {
+    "moduleFileExtensions": [
+      "js",
+      "json",
+      "ts"
+    ],
+    "rootDir": "src",
+    "testRegex": ".*\\.spec\\.ts$",
+    "transform": {
+      "^.+\\.(t|j)s$": "ts-jest"
+    },
+    "collectCoverageFrom": [
+      "**/*.(t|j)s"
+    ],
+    "coverageDirectory": "../coverage",
+    "testEnvironment": "node"
+  },
+  "homepage": "https://gitlab.com/ambushworks/nestjs-payments-graphql#readme",
+  "bugs": {
+    "url": "https://gitlab.com/ambushworks/nestjs-payments-graphql/-/issues"
+  },
+  "keywords": [
+    "nestjs",
+    "graphql",
+    "payments",
+    "invoicing",
+    "stripe",
+    "stripe-webhook",
+    "refunds",
+    "payment-plans",
+    "recurring-invoices",
+    "recurring-billing",
+    "subscriptions",
+    "e-transfer",
+    "interac",
+    "billing",
+    "prisma"
+  ],
   "author": "Ambush Softworks",
   "license": "MIT"
 }

package/prisma/payment-models.prisma

@@ -0,0 +1,504 @@
+// =============================================================================
+// @ambushsoftworks/nestjs-payments-graphql — Reference Prisma schema
+// =============================================================================
+//
+// This file is a DOCUMENTATION FRAGMENT. It is not loaded by Prisma at runtime
+// and it is not imported automatically anywhere. Copy the models and enums
+// below into your own `schema.prisma` and wire up the consumer-owned relations
+// (marked with `// CONSUMER:`) to the models in your application.
+//
+// Field shapes are fixed by the package's repository interfaces
+// (IInvoiceRepository, IPaymentRepository, etc.). You may:
+//   - Rename models freely (your repo adapter is the mapping layer).
+//   - Add columns (e.g. a soft-delete flag, additional audit fields).
+//   - Swap column types for compatible ones (e.g. `@db.VarChar(255)` on strings).
+//
+// You may NOT:
+//   - Change the cardinality of a field (e.g. make a required field optional
+//     without reflecting that in your repository adapter).
+//   - Drop tracked enum values (listed below).
+//
+// The package is database-agnostic — PostgreSQL examples are shown (e.g.
+// `@db.Decimal(5, 4)`); swap for your provider's equivalents as needed.
+//
+// -----------------------------------------------------------------------------
+// Model checklist
+// -----------------------------------------------------------------------------
+//
+// Always required:
+//   - Invoice
+//   - InvoiceLineItem
+//   - Payment
+//   - Refund
+//   - PaymentConfig
+//   - PaymentProvider
+//   - ProcessedWebhookEvent
+//
+// Required when `features.paymentPlans = true`:
+//   - PaymentPlan
+//   - PaymentPlanInstallment
+//
+// Required when `features.recurringInvoices = true`:
+//   - RecurringInvoice
+//   - RecurringInvoiceLineItem
+//   - PaymentCustomer
+//
+// All enums are required if you use the corresponding model.
+// =============================================================================
+
+
+// -----------------------------------------------------------------------------
+// Enums
+// -----------------------------------------------------------------------------
+// These enum value sets must match exactly — core services compare against
+// these strings. Add new values at your own risk; the package will not
+// recognize them.
+
+enum InvoiceStatus {
+  DRAFT
+  SENT
+  PARTIALLY_PAID
+  PAID
+  OVERDUE
+  VOID
+  REFUNDED
+}
+
+enum PaymentMethod {
+  CREDIT_CARD
+  DEBIT
+  E_TRANSFER
+  BANK_TRANSFER
+  CHEQUE
+  CASH
+  OTHER
+}
+
+enum PaymentStatus {
+  PENDING
+  PENDING_CONFIRMATION
+  PROCESSING
+  SUCCEEDED
+  FAILED
+  CANCELLED
+  REJECTED
+  REFUNDED
+  PARTIALLY_REFUNDED
+}
+
+enum RefundStatus {
+  PENDING
+  PROCESSING
+  SUCCEEDED
+  FAILED
+}
+
+enum PaymentPlanStatus {
+  ACTIVE
+  COMPLETED
+  CANCELLED
+  DEFAULTED
+}
+
+enum InstallmentStatus {
+  PENDING
+  INVOICED
+  PAID
+  OVERDUE
+  WAIVED
+  CANCELLED
+}
+
+enum RecurringIntervalUnit {
+  DAYS
+  MONTHS
+}
+
+enum RecurringInvoiceStatus {
+  ACTIVE
+  PAUSED
+  CANCELLED
+}
+
+
+// -----------------------------------------------------------------------------
+// Core models (always required)
+// -----------------------------------------------------------------------------
+
+model PaymentConfig {
+  id         String @id @default(uuid())
+  divisionId String @unique // CONSUMER: tenant/org/division scope — unique per tenant
+
+  // E-transfer settings
+  eTransferEnabled     Boolean @default(false)
+  eTransferEmail       String?
+  eTransferRecipient   String? // Display name for e-transfer recipient
+  eTransferAutoDeposit Boolean @default(true)
+
+  // Defaults applied when an invoice omits currency or tax rate
+  defaultCurrency String   @default("USD")
+  defaultTaxRate  Decimal? @db.Decimal(5, 4) // e.g. 0.1300 for 13%
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  providers PaymentProvider[]
+
+  // CONSUMER: add @relation to your Tenant/Division/Organization model
+  // division Division @relation(fields: [divisionId], references: [id], onDelete: Cascade)
+}
+
+model PaymentProvider {
+  id              String  @id @default(uuid())
+  paymentConfigId String
+  providerType    String // e.g. "stripe"
+  isActive        Boolean @default(true)
+  config          Json? // Non-secret config (account IDs, webhook endpoint IDs)
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  paymentConfig PaymentConfig @relation(fields: [paymentConfigId], references: [id], onDelete: Cascade)
+
+  @@unique([paymentConfigId, providerType])
+}
+
+model Invoice {
+  id            String        @id @default(uuid())
+  divisionId    String // CONSUMER: tenant/org scope
+  invoiceNumber String        @unique
+  status        InvoiceStatus @default(DRAFT)
+
+  // CONSUMER: opaque foreign key to your client/customer/contact record.
+  // The package treats this as an opaque string.
+  clientDetailsId String
+
+  // Polymorphic entity reference — what this invoice is FOR (booking, order,
+  // enrollment, etc.). Both fields nullable so invoices may stand alone.
+  referenceType String?
+  referenceId   String?
+
+  // Payment plan link (populated when an invoice is generated from an installment)
+  paymentPlanId     String?
+  installmentNumber Int?
+
+  // Recurring invoice link (populated when an invoice is generated from a recurring config)
+  recurringInvoiceId String?
+
+  // Financial amounts — ALL IN CENTS (integer minor units).
+  // taxRate is a decimal fraction: 0.1300 = 13%.
+  subtotal   Int     @default(0)
+  taxRate    Decimal @default(0) @db.Decimal(5, 4)
+  taxAmount  Int     @default(0)
+  discount   Int     @default(0)
+  total      Int     @default(0)
+  amountPaid Int     @default(0)
+  amountDue  Int     @default(0)
+
+  currency String @default("USD")
+
+  // E-transfer — code is the client-visible confirmation string, answer is
+  // the security answer the client must provide to the bank.
+  eTransferCode   String? @unique
+  eTransferAnswer String?
+
+  issuedAt DateTime?
+  dueAt    DateTime?
+
+  notes       String? // Internal staff notes (never exposed to clients)
+  clientNotes String? // Visible on invoice to client
+
+  // Consumer-defined key-value pairs (opaque to the package)
+  metadata Json?
+
+  // Audit fields
+  createdBy  String // CONSUMER: accountId/userId who created this invoice
+  voidedBy   String?
+  voidedAt   DateTime?
+  voidReason String?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  // Relations
+  lineItems        InvoiceLineItem[]
+  payments         Payment[]
+  // Reverse relation for PaymentPlanInstallment.invoiceId one-to-one
+  installment      PaymentPlanInstallment?
+  paymentPlan      PaymentPlan?             @relation("InvoicePlan", fields: [paymentPlanId], references: [id], onDelete: SetNull)
+  recurringInvoice RecurringInvoice?        @relation(fields: [recurringInvoiceId], references: [id])
+
+  // CONSUMER: add relations to your tenant and client models.
+  // Use `onDelete: Restrict` on financial relations — data-retention rules
+  // typically forbid cascade-deleting invoices when a client is removed.
+  // division      Division @relation(fields: [divisionId], references: [id], onDelete: Restrict)
+  // clientDetails Details  @relation(fields: [clientDetailsId], references: [id], onDelete: Restrict)
+
+  @@index([divisionId, status])
+  @@index([clientDetailsId])
+  @@index([referenceType, referenceId])
+  @@index([paymentPlanId])
+  @@index([recurringInvoiceId])
+  @@index([status, dueAt]) // For overdue scheduler
+}
+
+model InvoiceLineItem {
+  id        String @id @default(uuid())
+  invoiceId String
+
+  description String
+  quantity    Int     @default(1)
+  unitPrice   Int // cents
+  sortOrder   Int     @default(0)
+  isTaxable   Boolean @default(true)
+
+  // Optional polymorphic reference — what this line item represents
+  referenceType String?
+  referenceId   String?
+
+  // Consumer-defined key-value pairs (opaque to the package)
+  metadata Json?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  invoice Invoice @relation(fields: [invoiceId], references: [id], onDelete: Cascade)
+
+  @@index([invoiceId, sortOrder])
+}
+
+model Payment {
+  id        String        @id @default(uuid())
+  invoiceId String
+  amount    Int // cents
+  currency  String        @default("USD")
+  method    PaymentMethod
+  status    PaymentStatus @default(PENDING)
+
+  // Provider fields (both null for manual payments, both set for online)
+  provider          String? // e.g. "stripe"
+  providerPaymentId String?
+  providerData      Json? // Provider-specific metadata — NEVER log raw card data
+  receiptUrl        String?
+
+  // Manual payment fields
+  referenceNumber String? // cheque number, e-transfer confirmation, etc.
+  notes           String?
+  processedAt     DateTime? // When payment was actually processed (may differ from createdAt)
+  receivedBy      String? // CONSUMER: accountId who recorded the manual payment
+
+  // Reconciliation — set true when gateway cancellation fails during voidInvoice
+  needsReconciliation Boolean @default(false)
+
+  // Audit
+  createdBy String // CONSUMER: accountId/userId who created the payment
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  invoice Invoice  @relation(fields: [invoiceId], references: [id], onDelete: Restrict)
+  refunds Refund[]
+
+  // Note: null-null is valid (manual payments) — PostgreSQL unique allows multiple nulls.
+  @@unique([provider, providerPaymentId])
+  @@index([invoiceId, status])
+}
+
+model Refund {
+  id        String       @id @default(uuid())
+  paymentId String
+  amount    Int // cents
+  currency  String       @default("USD")
+  status    RefundStatus @default(PENDING)
+  reason    String?
+
+  // Provider fields (null for manual refunds)
+  providerRefundId String?
+  providerData     Json?
+
+  // Audit
+  createdBy   String // CONSUMER: accountId/userId who created the refund
+  processedBy String? // CONSUMER: accountId who processed a manual refund
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  payment Payment @relation(fields: [paymentId], references: [id], onDelete: Restrict)
+
+  @@index([paymentId])
+}
+
+model ProcessedWebhookEvent {
+  // Stripe event IDs are their own primary key.
+  // The package's IWebhookIdempotencyRepository uses this to no-op on replays.
+  eventId     String   @id
+  processedAt DateTime @default(now())
+
+  @@index([processedAt]) // For TTL cleanup via cleanupBefore()
+}
+
+
+// -----------------------------------------------------------------------------
+// Payment plan models (required when features.paymentPlans = true)
+// -----------------------------------------------------------------------------
+
+model PaymentPlan {
+  id         String            @id @default(uuid())
+  divisionId String // CONSUMER: tenant/org scope
+  status     PaymentPlanStatus @default(ACTIVE)
+
+  clientDetailsId String // CONSUMER: opaque client ID
+
+  // Polymorphic entity reference
+  referenceType String?
+  referenceId   String?
+
+  totalAmount Int // cents
+  currency    String @default("USD")
+
+  name        String?
+  description String?
+
+  createdBy    String // CONSUMER: accountId
+  cancelledBy  String?
+  cancelledAt  DateTime?
+  cancelReason String?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  installments PaymentPlanInstallment[]
+  invoices     Invoice[]                @relation("InvoicePlan")
+
+  // CONSUMER: add relations to your tenant and client models.
+  // division      Division @relation(fields: [divisionId], references: [id], onDelete: Restrict)
+  // clientDetails Details  @relation(fields: [clientDetailsId], references: [id], onDelete: Restrict)
+
+  @@index([divisionId, status])
+  @@index([clientDetailsId])
+  @@index([referenceType, referenceId])
+}
+
+model PaymentPlanInstallment {
+  id            String            @id @default(uuid())
+  paymentPlanId String
+  sequenceOrder Int
+  amount        Int // cents
+  status        InstallmentStatus @default(PENDING)
+  dueAt         DateTime?
+
+  // One-to-one link to the generated invoice (null until invoiced).
+  // INVARIANT: when set, Invoice.paymentPlanId and Invoice.installmentNumber
+  // must also be set atomically by the consumer repository adapter.
+  invoiceId String? @unique
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  paymentPlan PaymentPlan @relation(fields: [paymentPlanId], references: [id], onDelete: Cascade)
+  invoice     Invoice?    @relation(fields: [invoiceId], references: [id], onDelete: SetNull)
+
+  @@index([paymentPlanId, sequenceOrder])
+}
+
+
+// -----------------------------------------------------------------------------
+// Recurring invoice models (required when features.recurringInvoices = true)
+// -----------------------------------------------------------------------------
+
+model RecurringInvoice {
+  id         String @id @default(uuid())
+  divisionId String // CONSUMER: tenant/org scope
+
+  // Schedule configuration
+  intervalUnit    RecurringIntervalUnit
+  intervalValue   Int
+  anchorDate      DateTime // Immutable after creation — all next dates are computed from this
+  nextInvoiceAt   DateTime
+  lastGeneratedAt DateTime? // Null = never generated; set after each successful generation
+
+  status   RecurringInvoiceStatus @default(ACTIVE)
+  autoSend Boolean                @default(true)
+
+  // Invoice template fields
+  clientDetailsId String // CONSUMER: opaque client ID
+  currency        String  @default("USD")
+  taxRate         Decimal @default(0) @db.Decimal(5, 4)
+  notes           String?
+  clientNotes     String?
+
+  // Polymorphic entity reference
+  referenceType String?
+  referenceId   String?
+
+  // Auto-charge (Phase 2) — uses the stored PaymentCustomer for the client
+  autoCharge          Boolean @default(false)
+  metadata            Json?
+  consecutiveFailures Int     @default(0)
+  lastFailureReason   String?
+
+  // Lifecycle tracking
+  pausedAt     DateTime?
+  pausedBy     String?
+  cancelledAt  DateTime?
+  cancelledBy  String?
+  cancelReason String?
+
+  createdBy String
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  templateLineItems RecurringInvoiceLineItem[]
+  generatedInvoices Invoice[]
+
+  // CONSUMER: add relations to your tenant and client models.
+  // division      Division @relation(fields: [divisionId], references: [id], onDelete: Restrict)
+  // clientDetails Details  @relation(fields: [clientDetailsId], references: [id], onDelete: Restrict)
+
+  @@index([status, nextInvoiceAt]) // Used by the generator claim query
+  @@index([divisionId, status])
+}
+
+model RecurringInvoiceLineItem {
+  id                 String @id @default(uuid())
+  recurringInvoiceId String
+
+  description String
+  quantity    Int     @default(1)
+  unitPrice   Int // cents
+  sortOrder   Int     @default(0)
+  isTaxable   Boolean @default(true)
+
+  referenceType String?
+  referenceId   String?
+
+  metadata Json?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  recurringInvoice RecurringInvoice @relation(fields: [recurringInvoiceId], references: [id], onDelete: Cascade)
+
+  @@index([recurringInvoiceId, sortOrder])
+}
+
+model PaymentCustomer {
+  // Maps a (division, client, provider) triple to a provider-side customer ID
+  // (e.g. Stripe Customer). Powers auto-charge on recurring invoices and
+  // future saved-payment-method flows.
+  id                 String   @id @default(uuid())
+  divisionId         String
+  clientDetailsId    String
+  provider           String // "stripe"
+  providerCustomerId String
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  // CONSUMER: add relations to your tenant and client models.
+  // division      Division @relation(fields: [divisionId], references: [id], onDelete: Restrict)
+  // clientDetails Details  @relation(fields: [clientDetailsId], references: [id], onDelete: Restrict)
+
+  @@unique([divisionId, clientDetailsId, provider])
+  @@index([providerCustomerId])
+}