@ambushsoftworks/nestjs-payments-graphql 0.1.0 → 0.1.3

package/README.md

@@ -0,0 +1,612 @@
+# @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.
+- **Unrecognized event types** — Stripe fires many events per checkout (`payment_intent.created`, `charge.updated`, `charge.succeeded`, …) that the package does not route. These return 200 with a `debug`-level log and Stripe does not retry. The gateway surfaces them as an `IgnoredWebhookEvent` (`{ type: 'ignored', eventId, eventType }`) — if you implement a custom `PaymentGateway`, your `handleWebhook` must return this sentinel for unrouted events instead of throwing.
+- **Error reporting** — configure `webhook.errorReporter` to pipe exceptions into Sentry/GlitchTip/etc.
+
+> **Payable-status requirement.** `PaymentService.handlePaymentSucceeded` only applies an incoming payment if the invoice is in `SENT`, `PARTIALLY_PAID`, or `OVERDUE`. If a consumer creates a DRAFT invoice and starts checkout without first calling `InvoiceService.sendInvoice` to transition it to SENT, the SUCCEEDED payment lands in the `Payment` table but the invoice stays in DRAFT with `amountPaid=0`. As of v0.1.3 this fires a WARN log identifying the payment, provider, invoice, and status; call `sendInvoice` before `createPaymentSession` to avoid the case.
+
+`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/dist/gateways/payment-gateway.interface.d.ts

@@ -35,7 +35,7 @@ export interface PaymentGateway {
     handleWebhook(params: {
         headers: Record<string, string>;
         body: Buffer;
-    }): Promise<PaymentWebhookEvent>;
+    }): Promise<NormalizedWebhookEvent>;
 }
 export type PaymentWebhookEventType = 'payment.processing' | 'payment.succeeded' | 'payment.failed' | 'payment.cancelled' | 'refund.succeeded' | 'refund.failed' | 'setup.succeeded';
 export interface PaymentWebhookEvent {
@@ -48,3 +48,9 @@ export interface PaymentWebhookEvent {
     receiptUrl?: string;
     providerData: Record<string, unknown>;
 }
+export interface IgnoredWebhookEvent {
+    type: 'ignored';
+    eventId: string;
+    eventType: string;
+}
+export type NormalizedWebhookEvent = PaymentWebhookEvent | IgnoredWebhookEvent;

package/dist/gateways/stripe/stripe-webhook.controller.js

@@ -73,6 +73,10 @@ let StripeWebhookController = StripeWebhookController_1 = class StripeWebhookCon
             this.logger.error(`Stripe webhook signature verification failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
             throw new common_1.BadRequestException('Webhook signature verification failed');
         }
+        if (event.type === 'ignored') {
+            this.logger.debug(`Ignoring Stripe webhook event ${event.eventId} (type=${event.eventType})`);
+            return { received: true };
+        }
         try {
             await this.routeEvent(event);
         }

package/dist/gateways/stripe/stripe-webhook.controller.js.map

@@ -1 +1 @@
-{"version":3,"file":"stripe-webhook.controller.js","sourceRoot":"","sources":["../../../src/gateways/stripe/stripe-webhook.controller.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"stripe-webhook.controller.js","sourceRoot":"","sources":["../../../src/gateways/stripe/stripe-webhook.controller.ts"],"names":[],"mappings":"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"}

package/dist/gateways/stripe/stripe.gateway.d.ts

@@ -1,4 +1,4 @@
-import type { PaymentGateway, PaymentWebhookEvent } from '../payment-gateway.interface';
+import type { NormalizedWebhookEvent, PaymentGateway } from '../payment-gateway.interface';
 import type { RecurringPaymentGateway } from '../recurring-payment-gateway.interface';
 export declare class StripeGateway implements PaymentGateway, RecurringPaymentGateway {
     readonly providerType = "stripe";
@@ -43,7 +43,7 @@ export declare class StripeGateway implements PaymentGateway, RecurringPaymentGa
     handleWebhook(params: {
         headers: Record<string, string>;
         body: Buffer;
-    }): Promise<PaymentWebhookEvent>;
+    }): Promise<NormalizedWebhookEvent>;
     createOrRetrieveCustomer(params: {
         email: string;
         name?: string;