nestjs-boost 0.0.0-stage → 1.2.0

package/skills/nestjs-upgrading/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: nestjs-upgrading
+description: Migrates NestJS applications from v11 to v12 and keeps them current — nest upgrade, Node.js floors for running (20.19+/22.12+) vs CLI schematics (22.22.3+/24.15+/26+), ESM-only packages consumed via require(esm) and the Lambda NODE_OPTIONS flag, Jest on Node 24.9+ vs Vitest, TypeScript 6, lifecycle hook ordering by hierarchy, @Optional no longer inherited, Standard Schema in @Body/@Query/@Param and @nestjs/config (Joi 18 libraryOptions), Terminus HealthIndicatorService, graphql-ws and GraphiQL defaults, NATS v3, Rspack replacing webpack flags, routeConflictPolicy, errorCode, structured logging, and the optional CommonJS-to-ESM switch (type module, nodenext, .js extensions, import.meta.dirname). Use when upgrading Nest majors, fixing ERR_REQUIRE_ESM / ERR_REQUIRE_ASYNC_MODULE or UnknownDependenciesException after an upgrade, or converting a project to ESM. Not for adopting new v12 packages (use their own skills).
+compatibility: Upgrading from NestJS 11.x to 12.x; TypeScript 6
+metadata:
+  version: "0.1.0"
+  nestjs-major: "12"
+  docs-crawled: "2026-11-05"
+---
+
+# Upgrading NestJS (v11 → v12)
+
+```bash
+npm i -g @nestjs/cli@latest @nestjs/schematics@latest            # global binary first: `nest upgrade` ships with it
+npm i -D @nestjs/cli@latest @nestjs/schematics@latest typescript@^6
+nest upgrade                                                      # bumps every @nestjs/* package to the same major
+```
+
+Upgrade on a branch with a green test suite. Move **all** `@nestjs/*` packages together, then fix compile errors, then go through the checklist below.
+
+## Node.js
+
+| Task | Minimum |
+| --- | --- |
+| Run a v12 app | **20.19+** or **22.12+** (21.x unsupported) |
+| `nest new` / `generate` / `upgrade` | **22.22.3+**, **24.15+** or **26+** |
+| Jest loading v12 packages | **24.9+** (otherwise `ERR_REQUIRE_ASYNC_MODULE`) |
+
+The packages are ESM-only. CommonJS apps load them through `require(esm)`. **AWS Lambda disables it** on its Node 20/22/24 runtimes, so set `NODE_OPTIONS=--experimental-require-module` there (appended to any existing flags). Simplest path: the latest active LTS everywhere (CI, Docker, dev machines).
+
+Your app **may stay CommonJS**. `nest upgrade` doesn't change module format.
+
+## Breaking or behavioural changes
+
+| Area | What to do |
+| --- | --- |
+| Lifecycle hooks | Now called by component hierarchy level, so the order of `onModuleInit`/`onApplicationBootstrap`/shutdown hooks may change. Review code that depends on ordering between related providers, and its tests |
+| `@Optional()` | No longer inherited when a subclass redeclares its constructor (`UnknownDependenciesException`). Repeat `@Optional()` on the subclass constructor parameters |
+| `@nestjs/config` | `validationSchema` takes any Standard Schema (Zod recommended). Joi needs **v18+**, and Joi settings move to `validationOptions.libraryOptions` (defaults stay `allowUnknown: true`, `abortEarly: false`) |
+| `@nestjs/terminus` | `HealthIndicator`/`HealthCheckError` are removed. Inject `HealthIndicatorService` and use `check(key).up()/.down()`, or `.attempt(fn).withTimeout(ms)` |
+| `@nestjs/graphql` | `subscriptions-transport-ws` is removed; use `subscriptions: { 'graphql-ws': true }`. GraphiQL is the default IDE; customise it with a `graphiql: { … }` object |
+| NATS | Run `npm uninstall nats && npm i @nats-io/transport-node`. Headers come from `@nats-io/nats-core` |
+| Testing | Jest needs Node 24.9+ (`nest upgrade` bumps Jest to v30), or migrate to Vitest (the default for ESM projects): update the test scripts and globals, and check `supertest` default imports |
+| CLI bundling | `--webpack`/`--webpackPath` (and `webpack`/`webpackConfigPath` in `nest-cli.json`) are deprecated; use `--builder rspack` and `--rspackPath`. Rspack is the monorepo default. The `angular` schematic is removed |
+| Custom pipes | Transform signatures are stricter and `ArgumentMetadata` is generic; fix hand-written types |
+| Adapters | HTTP error mapping was reworked, and Express now drains in-flight requests on shutdown. Re-run e2e tests |
+
+## New, opt-in (adopt deliberately)
+
+- Standard Schema validation: `@Body({ schema })`, `@Param('id', { schema: z.coerce.number() })`, `StandardSchemaValidationPipe`, `StandardSchemaSerializerInterceptor` + `@SerializeOptions({ schema })`. `ValidationPipe`/`ClassSerializerInterceptor` remain supported (nestjs-validation-serialization).
+- `ValidationPipe({ errorFormat: 'list' | 'grouped' })`.
+- `NestFactory.create(AppModule, { routeConflictPolicy: { duplicate: 'error', shadow: 'warn' }, routeResolutionStrategy: 'specificity' })`. Shadowing such as `@Get(':id')` before `@Get('me')` is common, so turn on `warn` during the upgrade.
+- `new BadRequestException('…', { errorCode: 'WEAK_PASSWORD' })`.
+- Structured logging: `logger.log('User created', { userId })` attaches the object to the same entry.
+- Observability: `createObserveModule()` + `instrument: ObserveInstrument`.
+- gRPC `GrpcExceptionFilter`, Kafka `RegExp` patterns, request-scoped gateways, `handleDisconnect(client, reason)`, microservice pre-request hooks.
+- CLI: `nest deploy` (Mau), `--emit-declarations` (SWC), `--no-type-check`, `--silent`, `nest build --all --parallel`, `includeLibraryAssets`, `bun` as package manager, oxlint for new projects, decorators generated as `Reflector.createDecorator()`.
+
+## Optional: switch the project to ESM
+
+Steps:
+1. Add `"type": "module"` to `package.json`.
+2. Ensure `tsconfig` has `"module": "nodenext"`, `"moduleResolution": "nodenext"`, `"resolvePackageJsonExports": true`, `"target": "ES2023"`. Projects from v11 schematics 11.0.6+ already have these.
+3. Fix every relative import to end in `.js`.
+4. Replace `__dirname` with `import.meta.dirname`, and `require` with `createRequire(import.meta.url)`.
+5. Use top-level `await bootstrap()`.
+
+The whole project switches at once. See `references/esm-switch.md`.
+
+## Workflow
+
+- [ ] 1. Raise Node.js in CI, Docker, `engines` and Lambda (`NODE_OPTIONS`). Upgrade the global CLI, then run `nest upgrade` and update TypeScript to 6.
+- [ ] 2. Fix compile errors (pipe types, removed Terminus API, config `libraryOptions`, NATS imports, GraphQL subscription transport).
+- [ ] 3. Check lifecycle-ordering assumptions and `@Optional()` subclasses. Enable `routeConflictPolicy` warnings and fix shadowed routes.
+- [ ] 4. Fix the test runner (Jest 30 on Node 24.9+, or Vitest). Run unit and e2e tests, especially error responses and graceful shutdown.
+- [ ] 5. Replace deprecated webpack flags with Rspack where used. Build, lint, run tests, start the app. Then optionally plan the ESM switch as a separate change.
+
+## Reference files
+
+- `references/esm-switch.md`: the complete ESM `tsconfig`, Jest vs Vitest `types`, import-extension and global replacements, and before/after snippets for the Terminus, config and NATS changes. Read when editing code for the upgrade or converting to ESM.
+
+Sources: [Migration guide](https://docs.nestjs.com/migration-guide)

package/skills/nestjs-upgrading/references/esm-switch.md

@@ -0,0 +1,114 @@
+# v12 upgrade snippets and ESM switch
+
+## Contents
+- Terminus custom indicators
+- @Optional in subclasses
+- Config validation
+- GraphQL IDE and subscriptions
+- NATS headers
+- Switching to ESM
+- Moving code to ESM
+
+## Terminus custom indicators
+
+```typescript
+// v11 (removed)
+export class DogHealthIndicator extends HealthIndicator {
+  async isHealthy(key: string) {
+    const badboys = await this.dogService.getBadboys();
+    const result = this.getStatus(key, badboys.length === 0, { badboys: badboys.length });
+    if (badboys.length) throw new HealthCheckError('Dog check failed', result);
+    return result;
+  }
+}
+
+// v12
+@Injectable()
+export class DogHealthIndicator {
+  constructor(private readonly dogService: DogService, private readonly healthIndicatorService: HealthIndicatorService) {}
+  async isHealthy(key: string) {
+    const indicator = this.healthIndicatorService.check(key);
+    const badboys = await this.dogService.getBadboys();
+    return badboys.length > 0 ? indicator.down({ badboys: badboys.length }) : indicator.up();
+  }
+  ping(key: string) {
+    return this.healthIndicatorService.check(key).attempt(() => this.dogService.ping()).withTimeout(1000);
+  }
+}
+```
+
+## @Optional in subclasses
+
+```typescript
+@Injectable()
+class Child extends Base {
+  constructor(@Optional() options?: Options) { super(options); }   // re-declare the marker
+}
+```
+
+From 12.1, a subclass *without* its own constructor keeps its parent's markers again. 12.0.x dropped them in that case too, so upgrade to ≥ 12.1.
+
+## Config validation
+
+```typescript
+ConfigModule.forRoot({
+  validationSchema: z.object({
+    NODE_ENV: z.enum(['development', 'production', 'test', 'provision']).default('development'),
+    PORT: z.coerce.number().default(3000),
+  }),
+});
+
+// Joi 18+: library options move
+validationOptions: { libraryOptions: { allowUnknown: false, abortEarly: true } },
+```
+
+## GraphQL IDE and subscriptions
+
+```typescript
+GraphQLModule.forRoot<ApolloDriverConfig>({
+  driver: ApolloDriver,
+  graphiql: { url: '/graphql', headers: { authorization: 'Bearer <token>' }, shouldPersistHeaders: true, isHeadersEditorEnabled: true },
+  subscriptions: { 'graphql-ws': true },          // subscriptions-transport-ws removed
+});
+```
+
+## NATS headers
+
+```typescript
+import * as nats from '@nats-io/nats-core';
+const headers = nats.headers();
+headers.set('x-version', '1.0.0');
+this.client.send('record-builder-duplex', new NatsRecordBuilder(payload).setHeaders(headers).build());
+```
+
+## Switching to ESM
+
+`package.json`: `"type": "module"`. Projects generated with schematics ≥ 11.0.6 already have the right `tsconfig`. Older projects need `module`/`moduleResolution: "nodenext"`, `resolvePackageJsonExports: true` and `target: "ES2023"`. The complete set generated by `nest new` (ESM):
+
+```json
+{
+  "compilerOptions": {
+    "module": "nodenext", "moduleResolution": "nodenext", "resolvePackageJsonExports": true,
+    "esModuleInterop": true, "isolatedModules": true, "declaration": true, "removeComments": true,
+    "emitDecoratorMetadata": true, "experimentalDecorators": true, "allowSyntheticDefaultImports": true,
+    "target": "ES2023", "sourceMap": true, "outDir": "./dist", "rootDir": ".", "incremental": true,
+    "skipLibCheck": true, "strict": true, "strictPropertyInitialization": false,
+    "types": ["vitest/globals", "node"]
+  }
+}
+```
+
+- CommonJS + Jest uses `"types": ["node", "jest"]`.
+- `nest-cli.json` and `tsconfig.build.json` don't change.
+- With `nodenext`, every file's emit format follows `package.json`. After adding `type: module`, expect every missing import extension to error at once, and fix them all in one pass.
+
+## Moving code to ESM
+
+| CommonJS | ESM |
+| --- | --- |
+| `import { AppModule } from './app.module'` | `'./app.module.js'` (the extension refers to the emitted file) |
+| `__dirname`, `__filename` | `import.meta.dirname` (or `fileURLToPath(import.meta.url)`) |
+| `require(x)` | `createRequire(import.meta.url)` from `node:module` |
+| `bootstrap();` | `await bootstrap();` |
+
+Also check custom bootstrap scripts, bundler configs, and test-runner configs that assume CommonJS.

package/skills/nestjs-validation-serialization/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: nestjs-validation-serialization
+description: Validates and transforms NestJS 12 request input (body, query, params) and shapes responses — StandardSchemaValidationPipe with Zod/Valibot/ArkType schemas via the decorator `schema` option, or ValidationPipe with class-validator DTOs; coercing query strings to numbers with defaults; rejecting unknown fields; mapped/derived DTOs; and hiding fields such as passwords with StandardSchemaSerializerInterceptor or ClassSerializerInterceptor. Use when adding or fixing request validation, pagination/query parsing, DTOs, "strip/forbid unknown properties", validation error format, or when a sensitive field leaks in responses, even if the user only says "make sure the input is valid" or "don't return X". Not for config/env validation (nestjs-configuration) or OpenAPI docs (nestjs-openapi).
+compatibility: NestJS 12.x; zod (or valibot/arktype) for schema validation, or class-validator + class-transformer for DTO classes
+metadata:
+  version: "0.1.0"
+  nestjs-major: "12"
+  docs-crawled: "2026-11-04"
+---
+
+# NestJS validation and serialization
+
+NestJS 12 ships two equally supported validation flows. Both pipes can be registered together; each validates only the parameters it understands.
+
+| | Schema-first | Class-based DTOs |
+| --- | --- | --- |
+| Pipe | `StandardSchemaValidationPipe` | `ValidationPipe` |
+| Rules live in | A Zod/Valibot/ArkType schema; the type is inferred | Decorators on a DTO class |
+| Attach with | `@Body({ schema })`, `@Query({ schema })`, `@Param('id', { schema })` | Parameter typed with the DTO class |
+| Unknown fields | `z.strictObject()` rejects, `z.object()` strips | `whitelist: true` strips, plus `forbidNonWhitelisted: true` rejects |
+| Responses | `StandardSchemaSerializerInterceptor` + `@SerializeOptions({ schema })` | `ClassSerializerInterceptor` + `@Exclude()` |
+
+**Pick the flow by detection:** `zod`/`valibot`/`arktype` in dependencies → schema-first. `class-validator` → class-based. Neither → schema-first with Zod: no reflection metadata, and the same library `@nestjs/config` uses for env validation in v12. Don't mix flows inside one feature.
+
+## Default recipe: schema-first
+
+```typescript
+// main.ts — global, safe: only parameters that declare a schema are validated
+app.useGlobalPipes(new StandardSchemaValidationPipe());
+```
+
+```typescript
+// products/create-product.schema.ts
+export const createProductSchema = z.strictObject({           // strictObject: unknown keys → 400
+  name: z.string().trim().min(1),
+  price: z.number().positive(),                               // body numbers are NOT coerced: "5" → 400
+  tags: z.array(z.string()).optional(),
+});
+export type CreateProductDto = z.infer<typeof createProductSchema>;
+
+// products/list-products.query.ts — query strings ARE strings: coerce + defaults + bounds
+export const listProductsQuery = z.object({
+  page: z.coerce.number().int().min(1).default(1),
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+});
+export type ListProductsQuery = z.infer<typeof listProductsQuery>;
+```
+
+```typescript
+@Post() create(@Body({ schema: createProductSchema }) dto: CreateProductDto) {}
+@Get() list(@Query({ schema: listProductsQuery }) query: ListProductsQuery) {}
+@Get(':id') findOne(@Param('id', { schema: z.coerce.number().int().positive() }) id: number) {}
+```
+
+The handler receives the schema's **output** (coerced, defaulted, trimmed). Invalid input returns `400` with `message: ["price: ...", ...]`.
+
+## Class-based recipe
+
+```typescript
+app.useGlobalPipes(new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true, transform: true }));
+
+export class CreateProductDto {
+  @IsString() @IsNotEmpty() name: string;
+  @IsNumber() @IsPositive() price: number;
+  @IsOptional() @IsArray() @IsString({ each: true }) tags?: string[];
+}
+
+// query values: documented per-parameter conversion with defaults
+@Get() list(
+  @Query('page', new DefaultValuePipe(1), ParseIntPipe) page: number,
+  @Query('limit', new DefaultValuePipe(20), ParseIntPipe) limit: number,   // range check: throw BadRequestException, or use a schema
+) {}
+```
+
+- `transform: true` turns payloads into DTO instances and converts primitive path/query params from their declared types. With it off, convert explicitly with `ParseIntPipe`/`ParseBoolPipe`.
+- Arrays of DTOs in a body: `@Body(new ParseArrayPipe({ items: CreateUserDto })) dtos: CreateUserDto[]`. Arrays in a query (`?ids=1,2`): `new ParseArrayPipe({ items: Number, separator: ',' })`.
+- For bounded query numbers (min/max), a schema (`z.coerce.number().int().min(1).max(100)`) is the least code; `StandardSchemaValidationPipe` and `ValidationPipe` can coexist.
+- Derive DTOs with `PartialType`, `PickType`, `OmitType`, `IntersectionType` from `@nestjs/mapped-types` (or `@nestjs/swagger` when using OpenAPI). With schemas, use `.partial()`, `.pick()`, `.omit()`, `.extend()`.
+- v12 adds `errorFormat: 'grouped'` (errors keyed by property path) next to the default `'list'`.
+
+## Never hand-parse input in services
+
+Validation belongs in the pipe layer. Parsing `page`/`limit` strings or checking `typeof body.price` inside a service bypasses the shared 400 format and OpenAPI generation, and repeats work in every handler. Use the schema/DTO recipes above, or the `Parse*Pipe` + `DefaultValuePipe` pair for a single param: `@Query('page', new DefaultValuePipe(1), ParseIntPipe)`.
+
+## Hiding response fields
+
+Enforce it once, centrally, so future endpoints are covered too:
+
+- **Schema allowlist (default):** a response schema lists exactly what may leave the API; `z.object()` strips everything else.
+
+  ```typescript
+  export const userResponseSchema = z.object({ id: z.number(), email: z.string(), name: z.string() });
+
+  @Controller('users')
+  @UseInterceptors(StandardSchemaSerializerInterceptor)
+  @SerializeOptions({ schema: userResponseSchema })        // class level: every handler; arrays → per element
+  export class UsersController {}
+  ```
+
+  App-wide: `{ provide: APP_INTERCEPTOR, useClass: StandardSchemaSerializerInterceptor }` (Nest injects `Reflector`). Handlers without a schema pass through unchanged.
+
+- **Class-based:** `@Exclude() passwordHash` on the entity, plus `ClassSerializerInterceptor` (global via `APP_INTERCEPTOR`). It only applies to **class instances**. If services return plain objects, add `@SerializeOptions({ type: UserEntity })` so they are converted first; otherwise the field still leaks.
+
+## Gotchas
+
+- Zod requires `strictNullChecks` in `tsconfig.json`.
+- `ValidationPipe` validates only class-typed parameters. Interfaces are erased (`metatype` is `Object`), so nothing is validated.
+- `ValidationPipe` skips custom param decorators unless `validateCustomDecorators: true`.
+- Global pipes in a hybrid app don't cover connected microservices by default. For WebSockets/microservices, return `WsException`/`RpcException` from `exceptionFactory`.
+- Path and query values always arrive as strings: coerce them explicitly (`z.coerce.number()`, `ParseIntPipe`, or `transform: true` for primitive params).
+
+## Workflow
+
+- [ ] 1. Detect the flow (dependencies), and install what's missing (`npm i zod`, or `npm i class-validator class-transformer`).
+- [ ] 2. Register the pipe once, globally.
+- [ ] 3. Write the schema/DTO next to the feature; attach it to the parameter.
+- [ ] 4. For responses with sensitive or internal fields, add a response schema (or `@Exclude` + `type`).
+- [ ] 5. Add e2e cases for the 400s (missing field, wrong type, unknown field) and for hidden fields; run build, lint and tests.
+
+## Reference files
+
+- `references/validation-options.md`: every `ValidationPipe` and `StandardSchemaValidationPipe` option, Valibot/ArkType equivalents, arrays and custom decorators, and schema serialization errors. Read when tuning options or using a library other than Zod.
+
+Sources: [Validation](https://docs.nestjs.com/application/validation) · [Serialization](https://docs.nestjs.com/application/serialization) · [Pipes](https://docs.nestjs.com/pipes)

package/skills/nestjs-validation-serialization/references/validation-options.md

@@ -0,0 +1,84 @@
+# Validation and serialization options
+
+Sources: [Validation](https://docs.nestjs.com/application/validation) · [Serialization](https://docs.nestjs.com/application/serialization)
+
+## Contents
+- ValidationPipe options
+- StandardSchemaValidationPipe options
+- Custom error shape
+- Valibot and ArkType
+- Custom param decorators
+- StandardSchemaSerializerInterceptor options and errors
+- Non-HTTP transports
+
+## ValidationPipe options
+
+`new ValidationPipe({ ... })`; it extends class-validator's `ValidatorOptions`.
+
+| Option | Effect |
+| --- | --- |
+| `transform` | Convert payloads to DTO instances, and primitive params to their declared types |
+| `whitelist` | Strip properties without validation decorators |
+| `forbidNonWhitelisted` | With `whitelist`: reject such properties instead (400) |
+| `forbidUnknownValues` | Fail validation of unknown objects |
+| `skipMissingProperties` / `skipNullProperties` / `skipUndefinedProperties` | Skip validating missing / null / undefined properties |
+| `stopAtFirstError` | Stop at the first failed constraint per property |
+| `errorFormat` | `'list'` (default, array of strings) or `'grouped'` (object keyed by property path), v12 |
+| `disableErrorMessages` | Omit details from 400 responses (production hardening) |
+| `errorHttpStatusCode` | Status for failures (default 400) |
+| `exceptionFactory` | `(errors: ValidationError[]) => any`: build your own exception |
+| `groups`, `always`, `strictGroups` | class-validator groups |
+| `dismissDefaultMessages` | Drop class-validator default messages |
+| `validationError.target` / `.value` | Include target/value in `ValidationError` |
+| `enableDebugMessages` | Warn when something is misconfigured |
+
+## StandardSchemaValidationPipe options
+
+| Option | Default | Effect |
+| --- | --- | --- |
+| `transform` | `true` | Handler gets the schema output (coercion, defaults, transforms); `false` passes the original input |
+| `validateCustomDecorators` | `false` | Also validate `createParamDecorator()` params that declare a schema |
+| `validateOptions` | — | Forwarded to `~standard.validate()` |
+| `errorHttpStatusCode` | `400` | Status on failure |
+| `exceptionFactory` | — | `(issues) => exception`; each issue has `message` and an optional `path` |
+
+## Custom error shape
+
+```typescript
+new StandardSchemaValidationPipe({
+  exceptionFactory: (issues) => new UnprocessableEntityException({
+    message: 'Validation failed',
+    errors: issues.map((i) => ({
+      path: i.path?.map((s) => (typeof s === 'object' ? s.key : s)).join('.'),
+      message: i.message,
+    })),
+  }),
+});
+```
+
+To keep a global error format (e.g. `errorCode`), throw `new BadRequestException('Validation failed', { errorCode: 'VALIDATION_FAILED' })` from `exceptionFactory`, and let the app's global exception filter add the rest.
+
+## Valibot and ArkType
+
+Any Standard Schema library works the same way with the `schema` option:
+- Valibot: `v.object({...})` strips, `v.strictObject({...})` rejects unknown keys. Use `v.pipe(v.string(), v.transform(Number))` for coercion.
+- ArkType: `type({ ... })`.
+
+Zod quick reference: `z.object` strips, `z.strictObject` rejects, `z.looseObject` keeps unknown keys. Use `z.coerce.number()` for query/path numbers, and `.default()` for defaults. Derive schemas with `.partial()`, `.pick()`, `.omit()`, `.extend()`.
+
+## Custom param decorators
+
+```typescript
+@Get() find(@User('email', { schema: z.email() }) email: string) {}   // needs validateCustomDecorators: true on the pipe
+```
+
+## StandardSchemaSerializerInterceptor options and errors
+
+- `@SerializeOptions({ schema })` on a handler or class; the handler-level setting wins. Arrays get the item schema applied per element.
+- `null`, `undefined`, primitives and `StreamableFile` responses are not processed.
+- Constructor defaults: `new StandardSchemaSerializerInterceptor(reflector, { schema, validateOptions })`. When registered via `APP_INTERCEPTOR`, Reflector is injected.
+- A response that fails its schema (missing or mistyped property) is treated as a server bug: the client gets `500` instead of partial data, and the issues are logged.
+
+## Non-HTTP transports
+
+Both validation pipes throw HTTP exceptions by default. For WebSockets/microservices, return `new WsException(...)` / `new RpcException(...)` from `exceptionFactory`.

package/skills/nestjs-webhooks/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: nestjs-webhooks
+description: Sends and receives webhooks in NestJS 12 with @nestjs/webhooks — outgoing Standard Webhooks dispatched in your database transaction through @nestjs/outbox, signed and retried by a worker with backoff, endpoint subscriptions per tenant, secret rotation and encryption at rest, the delivery log and replay, SSRF protection; and incoming webhooks verified on the raw body with @VerifyWebhook (standard, Stripe-style, GitHub or custom schemes), deduplicated and processed exactly once with processInTransaction(). Use when the user wants to notify partners or customers of events by webhook, let them register endpoints, retry or replay deliveries, or accept and verify webhooks from Stripe, GitHub, a payment provider or any signed sender. Not for raw body setup alone (nestjs-http-platform), the outbox itself (nestjs-outbox) or calling third-party APIs (nestjs-http-client).
+compatibility: NestJS 12.x; @nestjs/webhooks + @nestjs/outbox; PostgreSQL or MySQL 8.4+ via Drizzle, TypeORM, Prisma (driver adapter), Kysely, pg or mysql2
+metadata:
+  version: "0.1.0"
+  nestjs-major: "12"
+  docs-crawled: "2026-11-05"
+---
+
+# NestJS webhooks (@nestjs/webhooks)
+
+Don't hand-roll HMAC signing, retry loops or `crypto.timingSafeEqual` checks when `@nestjs/webhooks` is installed or acceptable: it implements the Standard Webhooks spec, at-least-once delivery after commit, SSRF guards and an inbox for exactly-once processing.
+
+```bash
+npm i @nestjs/webhooks @nestjs/outbox
+```
+
+## Setup (outgoing + incoming)
+
+```typescript
+@Module({
+  imports: [
+    DrizzleModule.forRootAsync({ useFactory: () => ({ drizzle, connection: process.env.DATABASE_URL!, schema }) }),
+    OutboxModule.forRootAsync({ useFactory: () => ({ relay: { enabled: process.env.OUTBOX_RELAY !== 'off', pollInterval: '1s' } }) }),
+    WebhooksModule.forRootAsync({
+      useFactory: () => ({
+        eventTypes: ['order.shipped', 'order.cancelled'],            // dispatch() refuses others
+        retry: { attempts: 10, backoff: { delay: '5s', factor: 4, maxDelay: '1d' } },
+        worker: { enabled: process.env.WEBHOOKS_WORKER !== 'off' },
+        encryption: { keys: process.env.WEBHOOKS_ENCRYPTION_KEYS!.split(',') },   // seal endpoint secrets
+        receivers: {
+          payments: { scheme: 'standard', secret: process.env.PAYMENTS_WEBHOOK_SECRET! },
+          carrier: { scheme: 'stripe', header: 'Carrier-Signature', secret: process.env.CARRIER_WEBHOOK_SECRET! },
+        },
+      }),
+    }),
+  ],
+  providers: [
+    { provide: PostgresOutboxStore, inject: [getDrizzleToken(), OutboxStorage],
+      useFactory: (db, s: OutboxStorage) => new PostgresOutboxStore({ executor: fromDrizzle(db) }, s) },
+    { provide: PostgresWebhookStore, inject: [getDrizzleToken(), WebhooksStorage],
+      useFactory: (db, s: WebhooksStorage) => new PostgresWebhookStore({ executor: fromDrizzle(db) }, s) },
+  ],
+})
+export class AppModule {}
+
+// main.ts
+const app = await NestFactory.create(AppModule, { rawBody: true });   // required to verify incoming webhooks
+app.enableShutdownHooks();
+```
+
+- `WebhooksModule` requires `OutboxModule`; startup fails without it.
+- Stores create and migrate their own schemas (`nest_webhooks`, `nest_outbox`); no entities to write. With `NODE_ENV=production` they don't auto-migrate (run `npx @nestjs/webhooks migrate` and `npx @nestjs/outbox migrate`, check with `status` in CI) and startup fails with no store registered.
+- Import `fromDrizzle`/`fromTypeOrm`/`fromPrisma`/`fromKysely`/`fromPg` from the store's subpath (`@nestjs/webhooks/postgres` or `/mysql`).
+- Load secrets through validated config (nestjs-configuration) in real code.
+
+## Send: dispatch inside the transaction
+
+```typescript
+constructor(@InjectDrizzle() private readonly db: Database, private readonly webhooks: Webhooks<Transaction>) {}
+
+await this.db.transaction(async (tx) => {
+  await tx.update(orders).set({ status: 'cancelled' }).where(eq(orders.id, id));
+  await this.webhooks.dispatch(tx, { type: 'order.cancelled', tenant: partnerId, data: { orderId: id, reason } });
+});
+```
+
+- Pass the **transaction** (Drizzle `tx`, TypeORM `EntityManager` from `dataSource.transaction()`, Prisma interactive tx client), never the database: rollback means nothing is sent.
+- Delivery is **at least once and unordered**; receivers dedupe by `webhook-id`. Payload `timestamp` is dispatch time.
+- Version payloads: only add fields; for breaking changes add `order.shipped.v2` and dispatch both.
+
+## Let partners subscribe and inspect deliveries
+
+Inject `WebhookEndpoints` (`create({ url, eventTypes, tenant })`, `list`, `update`, `delete`, `getSecret`, `rotateSecret(id, { tenant, overlap })`) and `WebhookDeliveries` (`list`, `get`, `retry(idOrFilter, scope)`, `stats()`, `prune('30d')`). Always pass the caller's tenant as scope. Map `WebhooksError` (has `status`) to HTTP responses with a small `BaseExceptionFilter` subclass.
+
+## Receive: verify, dedupe, process once
+
+```typescript
+@Post() @HttpCode(HttpStatus.OK)
+@VerifyWebhook('payments')
+async receive(@IncomingWebhook() webhook: IncomingWebhook<PaymentEvent>) {
+  if (webhook.payload.type !== 'payment.succeeded') return;
+  const result = await this.db.transaction((tx) =>
+    webhook.processInTransaction(tx, () => this.orders.markPaid(tx, webhook.payload.data.orderId)));
+  if (result.duplicate) return;
+}
+```
+
+- `@VerifyWebhook()` answers 401 on bad signatures (400 for non-JSON); missing `rawBody: true` → 500.
+- GitHub (`scheme: 'github'`) signs no timestamp or id: set `id: (payload) => sha256(JSON.stringify(payload))` so replays dedupe.
+- During a sender's rotation, list both secrets: `secret: [newSecret, oldSecret]`.
+- A service that only receives: `WebhooksModule.forRootAsync({ outgoing: false, useFactory: () => ({ receivers }) })` plus `OutboxModule.forRoot({ relay: { enabled: false } })`. The outbox inbox does the deduplication, so register the outbox store on your database in production; no webhook store is needed.
+
+## Gotchas
+
+- Leave `delivery.allowHttp` / `allowPrivateNetworks` off outside development; partner URLs are untrusted (SSRF). Use `allowedAddresses` for a specific private range.
+- Run the worker in a few instances (`worker.enabled: false` elsewhere), not every API pod.
+- PostgreSQL default isolation must stay READ COMMITTED; the stores refuse stricter defaults.
+- Nothing prunes the log for you: schedule `deliveries.prune('30d')` and `OutboxInbox.prune()` (nestjs-scheduling).
+- Rotate endpoint secrets with the default 24h overlap; `overlap: 0` only after a leak.
+
+## Workflow
+
+- [ ] 1. Install both packages; register Drizzle/TypeORM/Prisma, `OutboxModule`, `WebhooksModule`, and both stores.
+- [ ] 2. Set `rawBody: true` and `enableShutdownHooks()` in `main.ts` (and in e2e `createNestApplication({ rawBody: true })`).
+- [ ] 3. Dispatch inside the transaction that changes state; declare every type in `eventTypes`.
+- [ ] 4. For incoming webhooks, add a receiver per sender and `@VerifyWebhook()` + `processInTransaction()`.
+- [ ] 5. E2E test with PGlite, `InMemoryWebhookTransport`, relay/worker off and driven by `runOnce()`, `signWebhook()` for incoming (see reference).
+- [ ] 6. Build, lint, run unit and e2e tests, start the app.
+
+## Reference files
+
+- `references/webhooks-reference.md`: module and receiver options, store executors and migrations, services, testing recipe, events, errors, custom transports and production checklist. Read when configuring options beyond the example, writing tests, or preparing production.
+
+Sources: [Webhooks](https://docs.nestjs.com/http/webhooks)