@ambushsoftworks/nestjs-payments-graphql 0.6.0-rc.1 → 0.6.0

package/CHANGELOG.md

@@ -56,7 +56,21 @@ prose for buried obligations. The marker was introduced in v0.4.0 and
 >    they settle. If you report on invoices closing, expect the lag to appear.
 > 6. Services now reject non-integer and negative money. Anything that was
 >    silently storing fractional cents will start throwing.
-> 7. **The package no longer searches the provider for a customer to adopt.**
+> 7. **If you took Checkout payments before 0.3.1, back them up to the
+>    PaymentIntent id before upgrading, or refunds for them are silently
+>    skipped.** 0.3.1 fixed how new payments are keyed; it did not migrate
+>    existing rows. A pre-0.3.1 Checkout payment can be keyed on the Checkout
+>    Session id while refund webhooks quote the PaymentIntent id, and the lookup
+>    is an exact match with no fallback — so `RefundService` logs an error and
+>    skips, the customer's money goes back, and the invoice stays PAID. The
+>    README's "Backfilling Checkout payments taken before 0.3.1" has the SQL.
+>    Found by the jobsites team while upgrading from 0.2.0; our own answer to
+>    their question about this had said 0.3.1 covered it, which was true only
+>    for rows written after it.
+> 8. **Subscribe to `charge.dispute.created` and `charge.dispute.closed`** — see
+>    the external-configuration section below. Build the list from
+>    `STRIPE_WEBHOOK_EVENTS` rather than prose, or set `stripe.verifyOnBoot`.
+> 9. **The package no longer searches the provider for a customer to adopt.**
 >    If you lose a `PaymentCustomer` row while the provider customer survives,
 >    a new one is created and the client re-saves their card. In exchange,
 >    whether two divisions share a wallet is now entirely your repository's
@@ -252,7 +266,7 @@ prose for buried obligations. The marker was introduced in v0.4.0 and
   schema still passes unchanged.
 
 ### Testing
-- **+65 specs, 529 across 23 suites.** New: `payment-method.service.spec.ts`,
+- **+87 specs, 551 across 24 suites.** New: `payment-method.service.spec.ts`,
   `recurring-invoice-scheduling.spec.ts`, `money-validation.spec.ts`, plus
   saved-card coverage on the Stripe gateway and the catch-up storm, the
   session-cancellation path, the auto-charge convergence race and the money

package/README.md

@@ -26,6 +26,8 @@ Production-grade payments module for NestJS with GraphQL support. Invoicing (inc
   - [Email Notifications](#email-notifications)
   - [Event Listeners](#event-listeners)
   - [Transactions](#transactions)
+- [Entry points](#entry-points)
+  - [Testing your integration](#testing-your-integration)
 - [Services](#services)
   - [Manual payments and confirmation](#manual-payments-and-confirmation)
   - [Money and types](#money-and-types)
@@ -34,6 +36,7 @@ Production-grade payments module for NestJS with GraphQL support. Invoicing (inc
 - [Error handling](#error-handling)
 - [Operations](#operations)
 - [Upgrading](#upgrading)
+  - [Backfilling Checkout payments taken before 0.3.1](#backfilling-checkout-payments-taken-before-031)
 - [Configuration Reference](#configuration-reference)
   - [Required Options](#required-options)
   - [Optional Repositories](#optional-repositories)
@@ -239,6 +242,8 @@ The controller is registered at `POST /webhooks/stripe` and marked with `@Paymen
 - Have guards check `Reflector.get(PAYMENTS_WEBHOOK, handler)` and bail out early, **or**
 - The controller sets `isPublic` and `skipTenant` metadata via the `@PaymentsWebhook()` decorator; read them with `Reflector` and let the request through. `PAYMENTS_WEBHOOK` is the **metadata key** those are set under — not a path, so comparing it to `request.url` never matches.
 
+`PaymentsWebhook` is exported, so you can apply the same three metadata keys to a route of your own if you proxy the webhook rather than exposing the package's controller directly. You do not need it otherwise — the controller already carries it.
+
 See [Critical Integration Requirements](#critical-integration-requirements).
 
 ### 5. Build a resolver
@@ -248,8 +253,11 @@ import { Resolver, Mutation, Args } from '@nestjs/graphql';
 import {
   InvoiceService,
   InvoiceModel,
-  CreateInvoiceInput,
 } from '@ambushsoftworks/nestjs-payments-graphql';
+// The @InputType classes live on the /graphql subpath. The plain names on the
+// root are the *service* interfaces — what you pass to the service, which is a
+// different shape (it carries `createdBy`, for one). See Upgrading.
+import { CreateInvoiceInput } from '@ambushsoftworks/nestjs-payments-graphql/graphql';
 
 @Resolver()
 export class InvoiceResolver {
@@ -853,9 +861,17 @@ Utility helpers exported:
 import {
   computeNextInvoiceDate,
   computeCycleCount,
+  computeNextInvoiceDateAfter,
 } from '@ambushsoftworks/nestjs-payments-graphql';
 ```
 
+`computeNextInvoiceDateAfter(anchor, unit, value, after)` is the one to use when
+a schedule has fallen behind: it returns the first scheduled date strictly after
+an instant, staying on the anchor's cadence. `computeCycleCount` rounds, which
+is right for an exact cycle boundary and overshoots for an arbitrary one — a Jan
+15 anchor evaluated on May 3 rounds to cycle 4 and returns June 15, stepping
+over a May 15 that has not happened yet. Added in v0.6.0.
+
 The consumer provides the scheduler (typically `@nestjs/schedule`) that calls `RecurringInvoiceService.processDueRecurringInvoices(now)` on a cron. See [Scheduled jobs](#scheduled-jobs).
 
 ### Saved Cards
@@ -944,6 +960,8 @@ const repositories = createPrismaPaymentRepositories(prisma, Prisma, {
 
 Declare `@@unique([clientDetailsId, provider])` on `PaymentCustomer` to match, and read the hazard in the scope-key section before you do.
 
+**Keep the `divisionId` column** even though you no longer key on it. The bundled adapter still writes it on create and `assertPaymentsSchema` still requires it, so dropping it because "we do not scope by division" fails at boot — or on the first card save if you skip the schema assertion. It stays useful as a record of which division first created the customer.
+
 A custom gateway must implement `adoptSetupPaymentMethod` to support saved cards. It is optional on `RecurringPaymentGateway` so v0.2.x gateways still compile; without it the webhook logs a warning and the card stays unusable for auto-charge.
 
 ### E-Transfer
@@ -1033,6 +1051,63 @@ await transactionManager.runInTransaction(async (repos) => {
 
 ---
 
+## Entry points
+
+The package publishes four. The root carries everything you need to call a
+service; the other three exist so a name means one thing.
+
+| Import from | Carries |
+|---|---|
+| `@ambushsoftworks/nestjs-payments-graphql` | Services, service input interfaces, entity types, exceptions, `@ObjectType` models, DI tokens, `StripeGateway`, utilities |
+| `…/graphql` | The `@InputType` classes for your resolvers, and the `IsMetadata` validator |
+| `…/prisma` | The bundled Prisma adapter — repositories, `createPrismaPaymentRepositories`, `assertPaymentsSchema` |
+| `…/testing` | In-memory repositories for testing your integration without a database |
+
+**Why `/graphql` is separate.** Six names collided: `CreateRefundInput`,
+`RecordManualPaymentInput`, `CreateInvoiceInput`, `CreatePaymentPlanInput`,
+`CreateRecurringInvoiceInput` and `UpdateRecurringTemplateInput` each named both
+a GraphQL `@InputType` and the service interface of the same purpose — and they
+are different shapes. The DTO has no `createdBy`; the service requires it. On
+the root the plain name is now the **service** interface, because that is what a
+resolver needs to call through. Moved in v0.6.0; see [Upgrading](#upgrading).
+
+### Testing your integration
+
+`/testing` ships the in-memory repositories the package's own suites use, so you
+can test resolvers and services without a database:
+
+```typescript
+import { createInMemoryRepositories } from '@ambushsoftworks/nestjs-payments-graphql/testing';
+
+const repos = createInMemoryRepositories(myInvoiceRepository, {
+  // Mirror your own schema. 'division' (the default) matches the reference
+  // schema's @@unique([divisionId, clientDetailsId, provider]); 'client'
+  // matches @@unique([clientDetailsId, provider]).
+  customerKey: 'division',
+});
+
+const moduleRef = await Test.createTestingModule({
+  imports: [PaymentsModule.forRootAsync({ useFactory: () => ({ ...repos }) })],
+}).compile();
+```
+
+The keys match `PaymentsModuleOptions`, so the result spreads straight into your
+factory. `repos.store` is the raw data if you want to assert on stored rows, and
+`repos.openTransactions()` lets you assert no transaction is open at a gateway
+call.
+
+**They enforce the unique constraints the reference schema declares**, because
+the package's recovery paths depend on them — `createPendingPayment`,
+`recordAutoChargePayment`, `createOrLinkCustomer` and the refund converger all
+catch `UniqueConstraintViolationException` and adopt the existing row. A fake
+without those constraints is more forgiving than any real database, and a test
+against it proves less than it appears to. That is also why `customerKey` exists:
+set it wrong and the double stops matching your schema.
+
+**They do not model row locking.** `findByIdForUpdate` is a plain read. For
+anything that turns on locking — concurrent claims, `SKIP LOCKED`, the
+installment race — run against PostgreSQL.
+
 ## Services
 
 Every service is exported from the package root and injectable anywhere once the module is registered (it is `global: true`). Listed here so you can see the whole surface in one place; the feature sections above cover behaviour.
@@ -1041,7 +1116,7 @@ Every service is exported from the package root and injectable anywhere once the
 |---|---|---|
 | `InvoiceService` | Invoice lifecycle: create, send, line items, tax, void, overdue | `ensureSent` is the one to call before opening a payment session |
 | `InvoiceNumberService` | Invoice number generation | Numbers are **global**, not per-division — see [Invoicing](#invoicing) |
-| `PaymentService` | Recording payments, webhook handling, reconciliation | `recordManualPayment`, `confirmPayment`, `rejectPayment` for the offline flow |
+| `PaymentService` | Recording payments, webhook handling, reconciliation | `recordManualPayment`, `confirmPayment`, `rejectPayment` for the offline flow; `cancelPendingPaymentsForInvoice` cancels live provider sessions and is called for you when an invoice is voided |
 | `RefundService` | Full and partial refunds, refund webhooks | `createRefund`, `refundInvoice`, `findRefundsByPaymentId` |
 | `PaymentConfigService` | Per-division `PaymentConfig` and active providers | `getConfig` returns `null` for an unconfigured division; `getDefaultProvider` throws |
 | `PaymentPlanService` | Instalment plans and their invoices | `createPaymentPlan`, `invoiceInstallment`, `waiveInstallment`, `cancelPaymentPlan` |
@@ -1051,7 +1126,7 @@ Every service is exported from the package root and injectable anywhere once the
 | `ETransferService` | E-transfer code and answer generation, instruction text | `getInstructions` is pure |
 | `PaymentEmailService` | All outbound email | **Never throws**, and silently does nothing when no sender is configured |
 | `PaymentJobsService` | The three scheduled jobs | See [Scheduled jobs](#scheduled-jobs) |
-| `GatewayRegistryService` | Gateway lookup and capability narrowing | `getRecurring`, `getInlineCapable`, `getPaymentMethodCapable` |
+| `GatewayRegistryService` | Gateway lookup and capability narrowing | `getRecurring`, `getInlineCapable` → `InlineCapableGateway`, `getPaymentMethodCapable` → `PaymentMethodCapableGateway`. Each returns the gateway with that capability's optional members narrowed to non-optional, or throws. |
 
 ### Manual payments and confirmation
 
@@ -1073,6 +1148,15 @@ Without that step the invoice never closes. If you record e-transfers and see in
 
 **Every monetary value is an integer number of cents.** Since v0.6.0 the services reject anything else rather than storing it — a negative or fractional amount throws `InvalidInvoiceStateException`.
 
+Two helpers are exported for the same invariant. `assertMoneyAmount(amount, field)`
+throws `InvalidInvoiceStateException` unless the value is a whole, non-negative
+number of cents — the services call it at every money entry point, and you can
+use it at your own. `deriveInvoiceAmounts(total, ledgerAmountPaid)` returns the
+`{ amountPaid, amountDue, overpaidBy, clampedFromNegative }` an invoice should
+store: `amountPaid` records reality and never goes negative, `amountDue` is
+always derived from it, and an overpayment is reported rather than absorbed.
+Both added in v0.6.0.
+
 **Tax rates are `DecimalLike`, not `number`.** `Invoice.taxRate` and `InvoiceTaxComponent.rate` expose `.toNumber()` and `.toString()`, so a Prisma `Decimal` satisfies them directly. `invoice.taxRate * subtotal` gives `NaN`; use `invoice.taxRate.toNumber()`.
 
 ## Tenancy and scoping
@@ -1159,10 +1243,43 @@ The CHANGELOG carries the detail; this is the map. Every version's own section h
 
 | From | Read | Out-of-repo work |
 |---|---|---|
-| 0.2.x | 0.2.1, 0.3.0, 0.3.1, 0.4.0, 0.5.0, 0.6.0 | Subscribe to `payment_intent.succeeded`; replace `charge.refunded` with `refund.created` + `refund.updated` |
-| 0.3.x | 0.3.1, 0.4.0, 0.5.0, 0.6.0 | Replace `charge.refunded` with `refund.created` + `refund.updated` |
-| 0.4.x | 0.4.0, 0.5.0, 0.6.0 | Widen tax-rate columns to `Decimal(6,5)`; add `@@unique([paymentId, providerRefundId])` to `Refund` |
-| 0.5.x | 0.6.0 | Add `PaymentCustomer.defaultPaymentMethodId` if you want saved cards |
+| 0.2.x | 0.2.1, 0.3.0, 0.3.1, 0.4.0, 0.5.0, 0.6.0 | Subscribe to `payment_intent.succeeded`, `refund.created`, `refund.updated`, `charge.dispute.created`, `charge.dispute.closed`; drop `charge.refunded`. **Backfill existing Checkout payments — see below.** |
+| 0.3.x | 0.3.1, 0.4.0, 0.5.0, 0.6.0 | Subscribe to `refund.created`, `refund.updated`, `charge.dispute.created`, `charge.dispute.closed`; drop `charge.refunded`. **Backfill if you took Checkout payments before 0.3.1.** |
+| 0.4.x | 0.4.0, 0.5.0, 0.6.0 | Subscribe to `charge.dispute.created`, `charge.dispute.closed`. Widen tax-rate columns to `Decimal(6,5)`; add `@@unique([paymentId, providerRefundId])` to `Refund` |
+| 0.5.x | 0.6.0 | Subscribe to `charge.dispute.created`, `charge.dispute.closed`. Add `PaymentCustomer.defaultPaymentMethodId` if you want saved cards |
+
+**Do not transcribe that event list by hand.** `STRIPE_WEBHOOK_EVENTS` in `gateways/stripe/types` is the canonical set for the version you are on; build your preflight from it, or set `stripe.verifyOnBoot` and let the verifier tell you what is missing. The jobsites team followed the prose above when it was incomplete and the verifier caught the gap in seconds — which is the argument for not trusting prose here.
+
+**Swap the refund events add-then-remove, not all at once.** 0.2.0 ignores `refund.created`/`refund.updated` and 0.6.0 ignores `charge.refunded`, so subscribing to all three across the deploy leaves no window where a refund arrives with nothing listening. Remove `charge.refunded` once the new version is live. (Discovered by the jobsites team doing exactly this.)
+
+### Backfilling Checkout payments taken before 0.3.1
+
+**If you took Checkout payments before 0.3.1, refunds for them will be silently skipped until you backfill.** This is the one upgrade step that loses money if you miss it.
+
+Before 0.3.1 a Checkout payment's row could be keyed on the Checkout **Session** id (`cs_…`). Refund webhooks quote the **PaymentIntent** id (`pi_…`), and `RefundService` looks the payment up by an exact match with no fallback — so it logs an error, skips, and the customer's money goes back while the invoice stays `PAID`. 0.3.1 fixed the keying **for rows written from then on**; it does not migrate what you already have.
+
+Find them:
+
+```sql
+SELECT COUNT(*) FROM "Payment"
+WHERE provider = 'stripe'
+  AND "providerPaymentId" LIKE 'cs_%'
+  AND "providerData"->>'paymentIntentId' IS NOT NULL;
+```
+
+Backfill them:
+
+```sql
+UPDATE "Payment"
+SET "providerPaymentId" = "providerData"->>'paymentIntentId'
+WHERE provider = 'stripe'
+  AND "providerPaymentId" LIKE 'cs_%'
+  AND "providerData"->>'paymentIntentId' IS NOT NULL;
+```
+
+Run it inside a transaction and check the count first. `Payment` carries `@@unique([provider, providerPaymentId])`, so the update fails rather than corrupting anything if a row already holds the target id — which happens when both success events were processed for one payment. Resolve those individually; the 0.3.1 notes describe how the package retires such a duplicate.
+
+A row with a `cs_…` id and no `providerData.paymentIntentId` is a zero-amount session with no PaymentIntent at all. Leave it: there is nothing to refund.
 
 Two database constraints are load-bearing wherever you are coming from, because the package's recovery paths depend on them: `Payment` needs `@@unique([provider, providerPaymentId])` and `Refund` needs `@@unique([paymentId, providerRefundId])`. `PaymentCustomer` needs **a** unique constraint for the same reason — `createOrLinkCustomer` adopts the winner of a concurrent create rather than failing, and without one there is no winner to adopt. Which columns is your choice: `[divisionId, clientDetailsId, provider]` for the reference schema's per-division customers, or `[clientDetailsId, provider]` for one wallet per client. See [Provider customers and the scope key](#provider-customers-and-the-scope-key).
 
@@ -1284,6 +1401,8 @@ import {
 
 The package registers these names on module import. Consumers **must not** redefine or re-register them, or GraphQL will throw `"type already registered"`.
 
+The three `Paginated*` object types are built by the exported `Paginated(ItemModel)` mixin, which returns an `@ObjectType` with `items` and `totalCount`. Call it to build your own paginated wrapper over a package model; each call must produce a distinctly-named type, or GraphQL rejects the duplicate.
+
 **Object types:** `Invoice`, `InvoiceLineItem`, `InvoiceTaxComponent`, `InvoiceClient`, `Payment`, `Refund`, `PaymentPlan`, `PaymentPlanInstallment`, `PaymentConfig`, `PaymentProvider`, `PaymentMethodSetup`, `ETransferInstructions`, `OnlinePaymentSession`, `RecurringInvoice`, `RecurringInvoiceLineItem`, `RecurringInvoiceTaxComponent`, `PaginatedInvoices`, `PaginatedPaymentPlans`, `PaginatedRecurringInvoices`, `InlinePaymentIntent`, `StripePublicConfig`, `SavedPaymentMethod`
 
 **Enums:** `InvoiceStatus`, `PaymentMethod`, `PaymentStatus`, `RefundStatus`, `PaymentPlanStatus`, `InstallmentStatus`, `RecurringIntervalUnit`, `RecurringInvoiceStatus`, `PaymentIntentStatus`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ambushsoftworks/nestjs-payments-graphql",
-  "version": "0.6.0-rc.1",
+  "version": "0.6.0",
   "description": "NestJS payments module with GraphQL support — invoicing, payment processing, recurring billing, and email notifications",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",