@ambushsoftworks/nestjs-payments-graphql 0.1.0 → 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,100 @@
+# 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.3] - 2026-05-15
+
+### Added
+- **`NormalizedWebhookEvent` / `IgnoredWebhookEvent` types** exported from the package root. `PaymentGateway.handleWebhook` now returns the discriminated union; the `'ignored'` variant signals "received but no action needed" so the webhook controller responds 200 instead of 400 + Stripe retry loop. See "Stripe Gateway & Webhooks" in the README.
+
+### Changed
+- **Stripe webhook controller now responds 200 for unrecognized Stripe event types** (e.g. `payment_intent.created`, `charge.updated`, `charge.succeeded`). Previously it threw inside the gateway's `normalizeWebhookEvent` and the controller's signature-verification try/catch re-threw as `BadRequestException('Webhook signature verification failed')`, causing Stripe to retry the delivery for ~3 days and filling logs with misleading "signature verification failed" messages. The new behavior matches Stripe's documented contract: log unrecognized events at `debug`, acknowledge with 200. Real signature failures are unchanged (still 400 with the correct error message).
+- **`PaymentService` now logs a WARN when a SUCCEEDED payment lands on an invoice in a non-payable status** (DRAFT, VOID, PAID, REFUNDED, …). Previously this was a silent skip — the consumer's card was charged but the invoice never updated. Affects both `handlePaymentSucceeded` (webhook path) and `reconcilePayment` (reconciliation scheduler path). Most commonly hit when a consumer creates a DRAFT invoice and starts checkout without first calling `InvoiceService.sendInvoice` to transition it to SENT.
+- **`PaymentGateway.handleWebhook` return type widened from `Promise<PaymentWebhookEvent>` to `Promise<NormalizedWebhookEvent>`** to express the new `'ignored'` variant. TypeScript covariance: existing custom-gateway implementations whose `handleWebhook` is declared as `Promise<PaymentWebhookEvent>` continue to satisfy the interface without modification (no TS error). Callers who destructure the return value should add a guard on the discriminator (`if (event.type === 'ignored') return;`) before accessing `PaymentWebhookEvent`-only fields.
+
+## [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.