nestjs-boost 0.0.0-stage → 1.2.0

package/skills/nestjs-graphql/references/federation.md

@@ -0,0 +1,110 @@
+# GraphQL federation
+
+## Contents
+- Packages and drivers
+- Users subgraph (owns the entity)
+- Posts subgraph (references and extends it)
+- Federation 2
+- Gateway
+- Mercurius federation
+- Subscriptions and hiding operations
+
+## Packages and drivers
+
+| Role | Apollo | Mercurius |
+| --- | --- | --- |
+| Subgraph | `npm i @apollo/subgraph`; `ApolloFederationDriver` / `ApolloFederationDriverConfig` from `@nestjs/apollo` | `npm i @apollo/subgraph @nestjs/mercurius`; `MercuriusFederationDriver` |
+| Gateway | `npm i @apollo/gateway`; `ApolloGatewayDriver` / `ApolloGatewayDriverConfig` | `npm i @mercuriusjs/gateway`; `MercuriusGatewayDriver` |
+
+## Users subgraph (owns the entity)
+
+```typescript
+@ObjectType()
+@Directive('@key(fields: "id")')
+export class User {
+  @Field(() => ID) id: number;
+  @Field() name: string;
+}
+
+@Resolver(() => User)
+export class UsersResolver {
+  constructor(private readonly users: UsersService) {}
+  @Query(() => User) getUser(@Args('id') id: number) { return this.users.findById(id); }
+  @ResolveReference()
+  resolveReference(reference: { __typename: string; id: number }) { return this.users.findById(reference.id); }   // called by the gateway
+}
+
+GraphQLModule.forRoot<ApolloFederationDriverConfig>({ driver: ApolloFederationDriver, autoSchemaFile: true }),
+```
+
+Schema first: `type User @key(fields: "id") { … }` and `extend type Query { … }` with `typePaths`.
+
+## Posts subgraph (references and extends it)
+
+```typescript
+@ObjectType()
+@Directive('@extends')                       // Federation 1 only
+@Directive('@key(fields: "id")')
+export class User {
+  @Field(() => ID) @Directive('@external') id: number;   // Federation 1 only
+  @Field(() => [Post]) posts?: Post[];
+}
+
+@Resolver(() => User)
+export class UsersResolver {
+  @ResolveField(() => [Post]) posts(@Parent() user: User) { return this.posts.forAuthor(user.id); }
+}
+
+@Resolver(() => Post)
+export class PostsResolver {
+  @ResolveField(() => User) user(@Parent() post: Post) { return { __typename: 'User', id: post.authorId }; }   // reference, resolved by the Users subgraph
+}
+
+GraphQLModule.forRoot<ApolloFederationDriverConfig>({
+  driver: ApolloFederationDriver,
+  autoSchemaFile: true,
+  buildSchemaOptions: { orphanedTypes: [User] },      // entity only reachable via _entities
+}),
+```
+
+## Federation 2
+
+- Code first: `autoSchemaFile: { federation: 2 }` — Nest adds the `@link` directive.
+- Schema first: `extend schema @link(url: "https://specs.apollo.dev/federation/v2.0", import: ["@key"])`.
+- Entities have no originating subgraph: drop `extend`, `@extends`, `@external`, and no need to extend `Query`.
+- Mercurius doesn't fully support Federation 2.
+
+## Gateway
+
+```typescript
+GraphQLModule.forRoot<ApolloGatewayDriverConfig>({
+  driver: ApolloGatewayDriver,
+  server: { /* Apollo Server options, e.g. context */ },
+  gateway: {
+    supergraphSdl: new IntrospectAndCompose({
+      subgraphs: [
+        { name: 'users', url: 'http://user-service/graphql' },
+        { name: 'posts', url: 'http://post-service/graphql' },
+      ],
+    }),
+  },
+}),
+```
+
+Other gateway options (header forwarding, polling) come from `@apollo/gateway`'s own API; pass them in `gateway`.
+
+## Mercurius federation
+
+```typescript
+GraphQLModule.forRoot<MercuriusFederationDriverConfig>({ driver: MercuriusFederationDriver, autoSchemaFile: true });   // subgraph (or typePaths)
+GraphQLModule.forRoot<MercuriusGatewayDriverConfig>({
+  driver: MercuriusGatewayDriver,
+  gateway: { services: [{ name: 'users', url: 'http://user-service/graphql' }, { name: 'posts', url: 'http://post-service/graphql' }] },
+});
+```
+
+## Subscriptions and hiding operations
+
+- Subgraphs support subscriptions (`subscriptions` for Apollo, `subscription: true` for Mercurius), but `ApolloGatewayDriver` doesn't forward them: use Apollo Router with federated subscriptions, or the Mercurius gateway (`subscription: true` and `wsUrl` per service).
+- Keep a field/operation out of the public supergraph with Federation 2 `@inaccessible`: `@Directive('@inaccessible')`. It stays executable on the subgraph.
+- Generate SDL offline for federation with `GraphQLSchemaFactory`, passing entity stubs in `orphanedTypes`.

package/skills/nestjs-graphql/references/schema-features.md

@@ -0,0 +1,133 @@
+# GraphQL schema features
+
+## Contents
+- Schema first
+- Scalars
+- Directives
+- Interfaces
+- Unions and enums
+- Field middleware and extensions
+- Mapped types and inheritance
+- Complexity plugin and other Apollo plugins
+- CLI plugin
+- Generating SDL without running the app
+- Sharing models with the browser
+- Multiple endpoints
+- Mercurius
+
+## Schema first
+
+```typescript
+GraphQLModule.forRoot<ApolloDriverConfig>({
+  driver: ApolloDriver,
+  typePaths: ['./**/*.graphql'],
+  definitions: { path: join(process.cwd(), 'src/graphql.ts'), outputAs: 'class' },   // generated at startup
+});
+```
+
+On-demand typings: a `generate-typings.ts` script with `new GraphQLDefinitionsFactory().generate({ typePaths, path, outputAs: 'class', watch: true })`. Resolver classes use `@Resolver('Author')`, `@Query()`, `@ResolveField()` matching SDL names; interfaces/unions need a `__resolveType` resolver. Add a `ValidationPipe` for argument validation.
+
+## Scalars
+
+- Built-ins: `ID`, `String`, `Boolean`, `Int`, `Float`, `GraphQLISODateTime` (default for `Date`), `GraphQLTimestamp`.
+- `buildSchemaOptions: { dateScalarMode: 'timestamp', numberScalarMode: 'integer' }`.
+- Code-first custom scalar class: `@Scalar('Date', () => Date) class DateScalar implements CustomScalar<number, Date> { parseValue, serialize, parseLiteral }` registered as a provider.
+- Imported scalars (e.g. `graphql-type-json`): `resolvers: { JSON: GraphQLJSON }` and `@Field(() => GraphQLJSON)`.
+- `new GraphQLScalarType({ name: 'UUID', serialize, parseValue, parseLiteral })` + `resolvers: { UUID: CustomUuidScalar }`.
+
+## Directives
+
+```typescript
+@Directive('@upper') @Field() title: string;          // also @Directive('@deprecated(reason: "…")')
+
+GraphQLModule.forRoot({
+  transformSchema: (schema) => upperDirectiveTransformer(schema, 'upper'),   // mapSchema/getDirective from @graphql-tools/utils
+  buildSchemaOptions: { directives: [new GraphQLDirective({ name: 'upper', locations: [DirectiveLocation.FIELD_DEFINITION] })] },
+});
+```
+
+Directives added with `@Directive()` aren't reflected in the generated schema file.
+
+## Interfaces
+
+- `@InterfaceType() abstract class Character { @Field(() => ID) id: string }` (TypeScript interfaces can't be used).
+- `@ObjectType({ implements: () => [Character] }) class Human implements Character`.
+- Default `resolveType` needs class instances; otherwise `@InterfaceType({ resolveType(value) { return value.pages ? Book : Author; } })`.
+- Shared field resolvers: `@Resolver(() => Character)` class with `@ResolveField` + `inheritResolversFromInterfaces: true`.
+
+## Unions and enums
+
+```typescript
+export const ResultUnion = createUnionType({ name: 'ResultUnion', types: () => [Author, Book] as const, resolveType(v) { … } });   // `as const` required
+@Query(() => [ResultUnion]) search(): Array<typeof ResultUnion> { … }
+
+export enum AllowedColor { RED, GREEN }
+registerEnumType(AllowedColor, { name: 'AllowedColor', description: '…', valuesMap: { RED: { deprecationReason: '…' } } });
+```
+
+## Field middleware and extensions
+
+```typescript
+const loggerMiddleware: FieldMiddleware = async (ctx: MiddlewareContext, next: NextFn) => { const value = await next(); return value; };
+@Field({ middleware: [loggerMiddleware] }) title: string;
+GraphQLModule.forRoot({ buildSchemaOptions: { fieldMiddleware: [loggerMiddleware] } });   // global, runs before local
+```
+
+- Code first only; no DI; keep them cheap; only on `ObjectType` classes. With `fieldResolverEnhancers`, interceptors/guards also wrap them.
+- Metadata: `@Extensions({ role: Role.ADMIN })` on fields/classes/methods; read in middleware via `ctx.info.parentType.getFields()[ctx.info.fieldName].extensions` (field-level permissions).
+
+## Mapped types and inheritance
+
+`PartialType`, `PickType`, `OmitType`, `IntersectionType` from `@nestjs/graphql`, composable; pass the target decorator as the 2nd arg (`PartialType(CreateUserInput, InputType)`) when deriving between kinds. Abstract base classes with `@ObjectType({ isAbstract: true })` / generic resolvers via a factory function returning a class. Custom mapped helpers: treat returned field metadata as read-only.
+
+## Complexity plugin and other Apollo plugins
+
+```typescript
+@Plugin()
+export class ComplexityPlugin implements ApolloServerPlugin {
+  constructor(private gqlSchemaHost: GraphQLSchemaHost) {}
+  async requestDidStart(): Promise<GraphQLRequestListener<BaseContext>> {
+    const { schema } = this.gqlSchemaHost;
+    return {
+      async didResolveOperation({ request, document }) {
+        const complexity = getComplexity({ schema, operationName: request.operationName, query: document, variables: request.variables,
+          estimators: [fieldExtensionsEstimator(), simpleEstimator({ defaultComplexity: 1 })] });
+        if (complexity > 20) throw new GraphQLError(`Query is too complex: ${complexity}`);
+      },
+    };
+  }
+}
+```
+
+`npm i graphql-query-complexity`; register as a provider; `@Field({ complexity: 3 })` or an estimator function; `@Query(() => T, { complexity: … })`. External plugins: `plugins: [ApolloServerPluginCacheControl({ defaultMaxAge: 5 })]`. Mercurius: register Fastify plugins via `plugins: [{ plugin, options }]` (mercurius-upload in `main.ts`).
+
+## CLI plugin
+
+`nest-cli.json`: `"plugins": [{ "name": "@nestjs/graphql", "options": { "typeFileNameSuffix": [".input.ts", ".args.ts", ".entity.ts", ".model.ts"], "introspectComments": true } }]`. Infers `@Field()` from types/optionality; override with explicit `@Field()`. SWC needs `--type-check`; ts-jest needs the `@nestjs/graphql/plugin` AST transformer (same pattern as the Swagger plugin).
+
+## Generating SDL without running the app
+
+```typescript
+const app = await NestFactory.create(GraphQLSchemaBuilderModule);
+await app.init();
+const schema = await app.get(GraphQLSchemaFactory).create([RecipesResolver], [DateScalar], { skipCheck: false, orphanedTypes: [] });
+console.log(printSchema(schema));
+```
+
+`GraphQLSchemaHost#schema` gives the built schema after `onModuleInit`. Federation entities only referenced through `_entities` go into `orphanedTypes`.
+
+## Sharing models with the browser
+
+`@nestjs/graphql` exposes a decorator shim via the `browser` export condition; bundlers without it can alias `@nestjs/graphql` to `node_modules/@nestjs/graphql/dist/extra/graphql-model-shim`.
+
+## Multiple endpoints
+
+`GraphQLModule.forRoot({ path: '/cats', include: [CatsModule] })` per endpoint. In code first, `include` limits resolvers; types are global unless `@ObjectType({ registerIn: () => CatsModule })` (also on `@InputType`, `@InterfaceType`, `@ArgsType`, `registerEnumType`, `createUnionType`). Prefer the factory form to avoid circular references.
+
+## Mercurius
+
+```typescript
+GraphQLModule.forRoot<MercuriusDriverConfig>({ driver: MercuriusDriver, graphiql: true, subscription: true });   // Fastify only
+```
+
+GraphiQL at `/graphiql`. Subscriptions: `PubSub` from `mercurius` (`mqemitter`; use `mqemitter-redis` in production), auth via `subscription.onConnect`. Async config with `forRootAsync`. Access the schema with `GraphQLSchemaHost`.

package/skills/nestjs-health-checks/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: nestjs-health-checks
+description: Adds liveness and readiness health checks to NestJS 12 with @nestjs/terminus — TerminusModule.forRoot options, HealthCheckService with @HealthCheck() controllers, built-in indicators (HTTP ping/response checks, TypeORM, Mongoose, Sequelize, MikroORM, Prisma, microservice, gRPC, memory heap/RSS, disk), custom indicators with HealthIndicatorService attempt()/up()/down()/degraded(), withTimeout() and cacheFor() on attempts, the shutting_down status and gracefulShutdownTimeoutMs for zero-downtime Kubernetes rollouts, and custom Terminus logging. Use when adding /health, /health/live or /health/ready endpoints, Kubernetes probes, dependency checks for databases or upstream APIs, or when pods are killed or kept in rotation wrongly. Not for metrics, tracing or alerting (nestjs-observability) or retries/circuit breakers (nestjs-resilience).
+compatibility: NestJS 12.x; @nestjs/terminus; @nestjs/axios for HttpHealthIndicator
+metadata:
+  version: "0.1.0"
+  nestjs-major: "12"
+  docs-crawled: "2026-11-05"
+---
+
+# NestJS health checks (@nestjs/terminus)
+
+```bash
+npm i @nestjs/terminus
+npm i @nestjs/axios axios        # only for HttpHealthIndicator
+nest g module health && nest g controller health
+```
+
+## Liveness vs readiness
+
+| Probe | Checks | Failing means |
+| --- | --- | --- |
+| Liveness `/health/live` | The process works (event loop answers; optionally heap/RSS limits) | Restart the container — so **no dependency checks** here |
+| Readiness `/health/ready` | Dependencies it needs to serve (DB, required upstreams) | Stop routing traffic; also reports `shutting_down` during shutdown |
+
+## Setup
+
+```typescript
+@Module({
+  imports: [TerminusModule.forRoot({ gracefulShutdownTimeoutMs: 5000, errorLogStyle: 'json' }), HttpModule],
+  controllers: [HealthController],
+  providers: [CacheHealthIndicator],
+})
+export class HealthModule {}
+
+@Controller('health')
+export class HealthController {
+  constructor(
+    private readonly health: HealthCheckService,
+    private readonly db: TypeOrmHealthIndicator,
+    private readonly memory: MemoryHealthIndicator,
+    private readonly cacheIndicator: CacheHealthIndicator,
+  ) {}
+
+  @Get('live') @HealthCheck()
+  live() { return this.health.check([() => this.memory.checkHeap('memory_heap', 300 * 1024 * 1024)]); }
+
+  @Get('ready') @HealthCheck()
+  ready() {
+    return this.health.check([
+      () => this.db.pingCheck('database').withTimeout(1500).cacheFor(5000),
+      () => this.cacheIndicator.isHealthy('cache'),
+    ]);
+  }
+}
+```
+
+- Enable `app.enableShutdownHooks()` — required for the `shutting_down` status and the graceful delay.
+- Make health routes public and unthrottled: `@Public()` (nestjs-authentication / request-pipeline), `@SkipThrottle()`, exclude from the global prefix/versioning if your probes expect `/health` (`setGlobalPrefix('api', { exclude: ['health/(.*)'] })` or `VERSION_NEUTRAL`).
+- Response: `{ status: 'ok' | 'error' | 'degraded' | 'shutting_down', info, error, details }` (`HealthCheckResult`); failures return **503**.
+
+## Built-in indicators
+
+- HTTP: `http.pingCheck('docs', url)`, `http.responseCheck('svc', url, (res) => res.status === 204)`.
+- Databases: `TypeOrmHealthIndicator`, `MongooseHealthIndicator`, `SequelizeHealthIndicator`, `MikroOrmHealthIndicator`, `PrismaHealthIndicator` (`pingCheck(key, …)`). Multiple TypeORM data sources: inject each and pass `{ connection }`.
+- `MicroserviceHealthIndicator`, `GRPCHealthIndicator`.
+- `memory.checkHeap(key, bytes)`, `memory.checkRSS(key, bytes)`, `disk.checkStorage(key, { path: '/', thresholdPercent: 0.9 })` or `{ threshold: bytes }`.
+- Use `.withTimeout(ms)` (the `timeout` option is deprecated) and `.cacheFor(ms)` for expensive checks; cached results carry `cachedResponse: true`.
+
+## Custom indicators
+
+```typescript
+@Injectable()
+export class PaymentsApiHealthIndicator {
+  constructor(private readonly indicators: HealthIndicatorService, private readonly http: HttpClient) {}
+  isHealthy(key: string) {
+    return this.indicators.check(key).attempt(async ({ signal }) => {        // up on resolve, down on throw
+      const { data } = await this.http.get<{ version: string }>('/status', { signal, retry: false });
+      return { version: data.version };                                       // appended to the result
+    }).withTimeout(1000);
+  }
+}
+
+@Injectable()
+export class CacheHealthIndicator {
+  constructor(private readonly indicators: HealthIndicatorService, private readonly cache: CacheService) {}
+  async isHealthy(key: string) {
+    const indicator = this.indicators.check(key);
+    return (await this.cache.isConnected()) ? indicator.up() : indicator.degraded('serving without cache');   // degraded ≠ fail
+  }
+}
+```
+
+- Pass the `signal` to the operation so timeouts cancel it.
+- With `up()/down()/degraded()`, return the state — a thrown error is treated as a bug (500 instead of 503); wrap risky code in try/catch and return `down()`.
+- Any `down` → overall `error`; `degraded` only if none are down.
+
+## Zero-downtime shutdown
+
+`gracefulShutdownTimeoutMs` (applied on SIGTERM only): readiness answers 503 `shutting_down` while the app keeps serving for the delay — set it slightly longer than the readiness probe period, and keep the pod's termination grace period longer than delay + drain time.
+
+## Logging
+
+`TerminusModule.forRoot({ logger: TerminusLogger })` (a transient `ConsoleLogger` subclass), `logger: false` to silence, `errorLogStyle: 'pretty' | 'json'`.
+
+## Workflow
+
+- [ ] 1. Install; `HealthModule` with `TerminusModule.forRoot()`; shutdown hooks on.
+- [ ] 2. Separate live and ready routes; public, unthrottled, outside prefix/versioning as probes require.
+- [ ] 3. Add indicators for required dependencies with timeouts (and caching); degraded for optional ones.
+- [ ] 4. E2E test: 200 when healthy, 503 when an indicator is overridden to fail.
+- [ ] 5. Build, lint, run tests, start the app and curl both endpoints; wire the probes in the deployment manifest.
+
+Sources: [Health checks (Terminus)](https://docs.nestjs.com/reliability/terminus)

package/skills/nestjs-http-client/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: nestjs-http-client
+description: Calls external HTTP APIs from NestJS 12 with the first-party fetch-based @nestjs/http-client — HttpClientModule.register/registerAsync named clients with baseUrl, headers and timeouts, forRoot app-wide defaults, typed get/post/put/patch/delete with params, query, json and responseType, per-attempt timeouts and AbortSignal deadlines, retries on by default for idempotent methods with backoff and Retry-After, idempotency keys for POST, HttpResponseError/HttpTimeoutError/HttpNetworkError handling and toHttpException 502/504 mapping, function and class interceptors, streaming responses, undici dispatchers, testing with a stub fetch, and migrating from @nestjs/axios. Use when a service must call another service or third-party API, when adding auth headers, retries or timeouts to outbound calls, or when replacing HttpModule/HttpService (Axios). Not for receiving webhooks (nestjs-webhooks), circuit breakers and bulkheads around calls (nestjs-resilience) or microservice transports (nestjs-microservices).
+compatibility: NestJS 12.x; @nestjs/http-client (no runtime deps); optional undici for custom dispatchers
+metadata:
+  version: "0.1.0"
+  nestjs-major: "12"
+  docs-crawled: "2026-11-05"
+---
+
+# NestJS HTTP client (@nestjs/http-client)
+
+Prefer `@nestjs/http-client` for new outbound calls; it replaces `@nestjs/axios`'s `HttpService`. If the project uses `@nestjs/axios`, keep it unless asked to migrate (map in `references/http-client-reference.md`). Every method returns a Promise — no `firstValueFrom`.
+
+```bash
+npm i @nestjs/http-client
+```
+
+## Register clients
+
+```typescript
+// app.module.ts — shared defaults (always global; no baseUrl here)
+HttpClientModule.forRoot({ headers: { 'user-agent': 'orders-service/1.0' }, timeout: '10s' }),
+
+// github/github.module.ts — one named client per upstream
+HttpClientModule.registerAsync({
+  name: 'github',
+  imports: [ConfigModule],
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    baseUrl: config.getOrThrow<string>('GITHUB_API_URL'),
+    headers: { authorization: `Bearer ${config.getOrThrow<string>('GITHUB_TOKEN')}` },
+    timeout: '5s',
+  }),
+  interceptors: [GithubAuthInterceptor],      // classes go beside useFactory
+}),
+```
+
+- `register()` scopes the client to the importing module (`isGlobal: true` to share). Unnamed = default client injected as `HttpClient`; named clients with `@InjectHttpClient('github')`; token `getHttpClientToken(name)`.
+- Client settings override `forRoot()` defaults, except headers (merged; `null` removes), retry (merged per field) and interceptors (forRoot's run first).
+
+## Make requests
+
+```typescript
+@Injectable()
+export class ReposService {
+  constructor(@InjectHttpClient('github') private readonly github: HttpClient) {}
+
+  async findAll(org: string) {
+    const { data } = await this.github.get<Repo[]>('/orgs/:org/repos', {
+      params: { org },                                   // fills :org, URI-encoded; '..' or missing throws
+      query: { type: 'public', topic: ['nest', 'ts'] },  // arrays repeat the key
+    });
+    return data;                                         // type arg is NOT validated at runtime
+  }
+
+  async createIssue(owner: string, repo: string, issue: CreateIssueDto) {
+    const { data } = await this.github.post<Issue>('/repos/:owner/:repo/issues', { params: { owner, repo }, json: issue });
+    return data;
+  }
+}
+```
+
+- Relative URLs append to `baseUrl` with one `/` (the `/v1` prefix is kept). Never interpolate user input into paths — use `params`/`query`.
+- `json` (sets content-type) or `body` (string, Buffer, FormData, stream…), not both. `responseType`: `'auto'` (default), `'json'`, `'text'`, `'arrayBuffer'`, `'stream'`, `'response'`.
+- Response: `{ status, statusText, ok, headers (web Headers: .get()), data, url, request }`.
+- Validate responses from APIs you don't control (e.g. a Standard Schema `parse`).
+
+## Timeouts, retries, idempotency
+
+- `timeout` applies **per attempt**; a call can take `attempts × timeout` + waits. Cap the whole call with `signal: AbortSignal.timeout(10_000)`.
+- Retries are **on by default**: 3 attempts for GET/HEAD/OPTIONS/PUT/DELETE on network errors, timeouts and 408/429/500/502/503/504, exponential backoff with full jitter (honours `Retry-After`). Configure with `retry: { attempts, backoff: { delay, factor, maxDelay, jitter }, retryIf, methods, statusCodes }` or `retry: false`; `methods`/`statusCodes` **replace** the defaults.
+- POST/PATCH aren't retried. With an upstream that supports idempotency keys: `headers: { 'idempotency-key': \`charge-${order.id}\` }, retry: { methods: ['POST'] }` on that request only.
+- Retry at one layer of a service chain only (retries multiply).
+
+## Errors
+
+```typescript
+try {
+  return (await this.github.get<Repo>('/repos/:owner/:repo', { params: { owner, repo } })).data;
+} catch (error) {
+  if (error instanceof HttpResponseError && error.status === 404) throw new NotFoundException();
+  throw toHttpException(error);       // upstream non-2xx/network/parse → 502, timeouts → 504 (logged)
+}
+```
+
+- Errors extend `HttpClientError`: `HttpResponseError` (`status`, `body`), `HttpTimeoutError`, `HttpNetworkError` (`cause.code`), `HttpParseError`. `throwOnHttpError: false` returns non-2xx as values.
+- Or map centrally: `@Catch(HttpClientError, DOMException) class F extends BaseExceptionFilter { catch(e, h) { super.catch(toHttpException(e), h); } }`.
+- `toHttpException(error, { forward: [422] })` passes selected upstream statuses/bodies through; `log: false` if you log elsewhere. In RPC/WS handlers convert to `RpcException`/`WsException` yourself.
+
+## Security defaults
+
+A client with `baseUrl` only talks to its origin (other hosts and cross-origin redirects throw), credentials in URLs are refused, and error messages mask query values. Keep `redirect` default unless the API intentionally redirects off-origin (`'follow'`).
+
+## Testing
+
+```typescript
+const fetch = vi.fn<typeof globalThis.fetch>();
+const moduleRef = await Test.createTestingModule({ imports: [HttpClientModule.forRoot({ fetch }), ReposModule] }).compile();
+await moduleRef.init();
+fetch.mockResolvedValueOnce(Response.json([{ name: 'nest' }]));    // one Response per call (bodies read once)
+```
+
+E2E: `.overrideProvider(HTTP_CLIENT_MODULE_OPTIONS).useValue({ fetch })`, or replace a client via `getHttpClientToken('github')`. Test retries with `retry: false` or several queued responses.
+
+## Workflow
+
+- [ ] 1. Install; `forRoot()` defaults; one named client per upstream with `registerAsync` + `ConfigService`.
+- [ ] 2. Service methods with `params`/`query`/`json`; validate responses.
+- [ ] 3. Set timeouts, a deadline for user-facing calls, retry policy and idempotency keys for unsafe methods.
+- [ ] 4. Map errors with `toHttpException` or a filter; add a logging interceptor if no tracing.
+- [ ] 5. Stub-fetch tests. Build, lint, run tests, start the app.
+
+## Reference files
+
+- `references/http-client-reference.md`: interceptors (function and class, per-attempt), streaming to `StreamableFile`, undici `Agent`/`ProxyAgent` dispatchers, redirect modes, RxJS wrapping with cancellation, and the `@nestjs/axios` migration table. Read when going beyond the basics or migrating.
+
+Sources: [HTTP client](https://docs.nestjs.com/application/http-client)

package/skills/nestjs-http-client/references/http-client-reference.md

@@ -0,0 +1,116 @@
+# @nestjs/http-client reference
+
+## Contents
+- Interceptors
+- Streaming responses
+- Dispatchers: pools, proxies, mTLS
+- Redirects
+- Async configuration variants
+- RxJS
+- Migrating from @nestjs/axios
+
+## Interceptors
+
+Function form:
+
+```typescript
+export function apiKeyInterceptor(apiKey: string): HttpClientInterceptorFn {
+  return (request, next) => { request.headers.set('x-api-key', apiKey); return next(request); };
+}
+```
+
+Class form (DI):
+
+```typescript
+@Injectable()
+export class GithubAuthInterceptor implements HttpClientInterceptor {
+  constructor(private readonly tokens: GithubTokenService) {}
+  async intercept(request: HttpRequest, next: HttpHandler): Promise<Response> {
+    request.headers.set('authorization', `Bearer ${await this.tokens.getToken()}`);
+    return next(request);
+  }
+}
+```
+
+- `HttpRequest`: `method`, `url` (URL), `headers` (Headers), `body`, `signal`, `attempt`, `context` (from the request's `context` option).
+- Listed first = outermost; `forRoot()` interceptors run before the client's. They run **once per attempt** (fresh tokens on retry). They see the raw `Response` before the client throws for non-2xx.
+- Class interceptors resolve at app init; an existing provider instance is reused.
+- Logging interceptor: log `method origin+pathname status ms attempt` — not the query string (PII/keys). Tracing needs no interceptor with `@nestjs/observe`.
+
+## Streaming responses
+
+```typescript
+@Get(':id/pdf')
+async download(@Param('id') id: string) {
+  const { data, headers } = await this.billing.get('/invoices/:id/pdf', { params: { id }, responseType: 'stream' });
+  return new StreamableFile(data, { type: headers.get('content-type') ?? 'application/pdf' });
+}
+```
+
+Timeout stops once headers arrive; the `signal` still cancels. Don't forward upstream `content-length` (fetch decompresses).
+
+## Dispatchers: pools, proxies, mTLS
+
+```typescript
+import { Agent, ProxyAgent } from 'undici';   // install undici yourself, matching your Node's bundled major
+
+HttpClientModule.register({
+  name: 'partner',
+  baseUrl: 'https://partner.example.com',
+  dispatcher: new Agent({ connections: 20, connect: { ca, cert, key } }),
+});
+// proxy: dispatcher: new ProxyAgent('http://proxy.internal:3128')
+```
+
+Node `http.Agent` instances don't work with fetch.
+
+## Redirects
+
+Default with `baseUrl`: follow same-origin only, cross-origin → `HttpNetworkError`. `'follow'` anywhere, `'error'` on any redirect, `'manual'` returns 3xx (combine with `throwOnHttpError: false`).
+
+## Async configuration variants
+
+- `registerAsync({ name, imports, inject, useFactory, interceptors, isGlobal })` — factory returns `HttpClientFactoryOptions` (no name/isGlobal/imports/interceptor classes).
+- `useClass: GithubClientConfig` implementing `HttpClientOptionsFactory.createHttpClientOptions()`; `useExisting` with the exporting module in `imports`.
+- `forRootAsync()` with `HttpClientModuleOptionsFactory`.
+- Outside Nest (scripts): `new HttpClient(options)`.
+
+## RxJS
+
+`defer(() => this.http.get('/cats'))` starts on subscribe; neither `defer` nor `from` cancels on unsubscribe. For cancellation:
+
+```typescript
+function fromRequest<T>(send: (signal: AbortSignal) => Promise<T>): Observable<T> {
+  return new Observable<T>((subscriber) => {
+    const controller = new AbortController();
+    send(controller.signal).then((v) => { subscriber.next(v); subscriber.complete(); }, (e) => subscriber.error(e));
+    return () => controller.abort();
+  });
+}
+```
+
+## Migrating from @nestjs/axios
+
+| `@nestjs/axios` | `@nestjs/http-client` |
+| --- | --- |
+| `HttpModule.register({ baseURL })` | `HttpClientModule.register({ baseUrl })` |
+| `HttpModule.registerAsync()` | `HttpClientModule.registerAsync()` (also takes `name`) |
+| `HttpModuleOptionsFactory.createHttpOptions()` | `HttpClientOptionsFactory.createHttpClientOptions()` |
+| `extraProviders` | a module exporting the providers, in `imports` |
+| one `HttpService` per module | named clients, `@InjectHttpClient(name)` |
+| Observables + `firstValueFrom(...)` | `await this.http.get(url)` |
+| `post(url, data)` | `post(url, { json: data })` |
+| `params` (query) | `query` (arrays repeat keys); `params` = path segments |
+| `response.headers['etag']` | `response.headers.get('etag')` |
+| `AxiosError` / `error.response?.status` | `HttpResponseError` / `error.status`, `error.body` |
+| `error.code === 'ECONNABORTED'` | `HttpTimeoutError` |
+| `validateStatus: () => true` | `throwOnHttpError: false` |
+| `axiosRef` | none; options or a custom `fetch` |
+| `axiosRef.interceptors.*.use()` | `interceptors` (one function for request + response) |
+| `httpsAgent` / `proxy` | `dispatcher` (undici `Agent` / `ProxyAgent`) |
+| `maxRedirects: 0` | `redirect: 'manual'` |
+| no retries | retries on by default; `retry: false` to match old behaviour |
+| `timeout` whole request | `timeout` per attempt (`'5s'`) |
+| `onUploadProgress` / `onDownloadProgress` | none; count stream bytes |
+
+Both packages can coexist during migration. Update tests: mock `fetch` instead of `HttpService`.