spoonfeeder 0.1.0

package/templates/recipes/oauth-github/tests/unit/shared/auth/github.strategy.spec.ts

@@ -0,0 +1,72 @@
+import { ConfigService } from '@nestjs/config';
+import { Test } from '@nestjs/testing';
+import { GitHubStrategy } from '@/shared/auth/github.strategy';
+
+describe('GitHubStrategy', () => {
+  let strategy: GitHubStrategy;
+
+  const mockConfigService = {
+    getOrThrow: jest.fn((key: string) => {
+      const config: Record<string, string> = {
+        GITHUB_CLIENT_ID: 'test-client-id',
+        GITHUB_CLIENT_SECRET: 'test-client-secret',
+        GITHUB_CALLBACK_URL: 'http://localhost:3000/auth/github/callback',
+      };
+      return config[key];
+    }),
+  };
+
+  beforeEach(async () => {
+    const module = await Test.createTestingModule({
+      providers: [GitHubStrategy, { provide: ConfigService, useValue: mockConfigService }],
+    }).compile();
+
+    strategy = module.get(GitHubStrategy);
+  });
+
+  it('should be defined', () => {
+    expect(strategy).toBeDefined();
+  });
+
+  it('should extract user profile from GitHub OAuth callback', () => {
+    const profile = {
+      id: 'gh-789',
+      displayName: 'GitHub User',
+      emails: [{ value: 'ghuser@example.com' }],
+      photos: [{ value: 'https://avatars.githubusercontent.com/u/123' }],
+    };
+    const done = jest.fn();
+
+    strategy.validate('access-token', 'refresh-token', profile as any, done);
+
+    expect(done).toHaveBeenCalledWith(null, {
+      provider: 'github',
+      providerId: 'gh-789',
+      email: 'ghuser@example.com',
+      name: 'GitHub User',
+      avatar: 'https://avatars.githubusercontent.com/u/123',
+      accessToken: 'access-token',
+    });
+  });
+
+  it('should handle profile with missing optional fields', () => {
+    const profile = {
+      id: 'gh-000',
+      displayName: 'Private User',
+      emails: undefined,
+      photos: undefined,
+    };
+    const done = jest.fn();
+
+    strategy.validate('access-token', 'refresh-token', profile as any, done);
+
+    expect(done).toHaveBeenCalledWith(null, {
+      provider: 'github',
+      providerId: 'gh-000',
+      email: undefined,
+      name: 'Private User',
+      avatar: undefined,
+      accessToken: 'access-token',
+    });
+  });
+});

package/templates/recipes/oauth-google/README.md

@@ -0,0 +1,64 @@
+# Google OAuth 2.0
+
+Google OAuth 2.0 login strategy using Passport for NestJS applications.
+
+## Links
+
+- [Google Identity: OAuth 2.0 for Web Server Applications](https://developers.google.com/identity/protocols/oauth2/web-server)
+- [Google Cloud Console - Credentials](https://console.cloud.google.com/apis/credentials)
+- [NestJS Authentication Documentation](https://docs.nestjs.com/security/authentication)
+- [passport-google-oauth20 on npm](https://www.npmjs.com/package/passport-google-oauth20)
+- [@nestjs/passport on npm](https://www.npmjs.com/package/@nestjs/passport)
+
+## Dependencies
+
+| Package                          | Version  | Purpose                                            |
+| -------------------------------- | -------- | -------------------------------------------------- |
+| `passport-google-oauth20`        | `2.0.0`  | Google OAuth 2.0 strategy for Passport             |
+| `@nestjs/passport`               | `10.0.3` | Passport integration for NestJS                    |
+| `passport`                       | `0.7.0`  | Authentication middleware                          |
+| `@types/passport-google-oauth20` | `2.0.16` | TypeScript definitions for passport-google-oauth20 |
+
+## Setup
+
+1. Go to the [Google Cloud Console](https://console.cloud.google.com/apis/credentials).
+2. Create a new project or select an existing one.
+3. Navigate to **APIs & Services > Credentials**.
+4. Click **Create Credentials > OAuth client ID**.
+5. Select **Web application** as the application type.
+6. Add your callback URL (e.g. `http://localhost:3000/auth/google/callback`) under **Authorized redirect URIs**.
+7. Copy the **Client ID** and **Client Secret** into your environment variables.
+
+## Environment Variables
+
+| Variable               | Description                                       |
+| ---------------------- | ------------------------------------------------- |
+| `GOOGLE_CLIENT_ID`     | OAuth 2.0 client ID from Google Cloud Console     |
+| `GOOGLE_CLIENT_SECRET` | OAuth 2.0 client secret from Google Cloud Console |
+| `GOOGLE_CALLBACK_URL`  | Callback URL registered in Google Cloud Console   |
+
+## Usage
+
+```typescript
+@Controller('auth')
+export class AuthController {
+  @Get('google')
+  @UseGuards(GoogleAuthGuard)
+  googleLogin() {
+    // Redirects to Google login page
+  }
+
+  @Get('google/callback')
+  @UseGuards(GoogleAuthGuard)
+  googleCallback(@Request() req) {
+    return req.user;
+  }
+}
+```
+
+## Generated Files
+
+| File                                   | Description                                      |
+| -------------------------------------- | ------------------------------------------------ |
+| `src/shared/auth/google.strategy.ts`   | Google OAuth 2.0 Passport strategy               |
+| `src/shared/auth/google-auth.guard.ts` | Auth guard wrapping the Google Passport strategy |

package/templates/recipes/oauth-google/src/shared/auth/google-auth.guard.ts

@@ -0,0 +1,5 @@
+import { Injectable } from '@nestjs/common';
+import { AuthGuard } from '@nestjs/passport';
+
+@Injectable()
+export class GoogleAuthGuard extends AuthGuard('google') {}

package/templates/recipes/oauth-google/src/shared/auth/google.strategy.ts

@@ -0,0 +1,33 @@
+import { Injectable } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { PassportStrategy } from '@nestjs/passport';
+import { Strategy, VerifyCallback, Profile } from 'passport-google-oauth20';
+
+@Injectable()
+export class GoogleStrategy extends PassportStrategy(Strategy, 'google') {
+  constructor(private readonly configService: ConfigService) {
+    super({
+      clientID: configService.getOrThrow<string>('GOOGLE_CLIENT_ID'),
+      clientSecret: configService.getOrThrow<string>('GOOGLE_CLIENT_SECRET'),
+      callbackURL: configService.getOrThrow<string>('GOOGLE_CALLBACK_URL'),
+      scope: ['email', 'profile'],
+    });
+  }
+
+  validate(
+    accessToken: string,
+    refreshToken: string,
+    profile: Profile,
+    done: VerifyCallback,
+  ): void {
+    const user = {
+      provider: 'google',
+      providerId: profile.id,
+      email: profile.emails?.[0]?.value,
+      name: profile.displayName,
+      avatar: profile.photos?.[0]?.value,
+      accessToken,
+    };
+    done(null, user);
+  }
+}

package/templates/recipes/oauth-google/tests/unit/shared/auth/google.strategy.spec.ts

@@ -0,0 +1,72 @@
+import { ConfigService } from '@nestjs/config';
+import { Test } from '@nestjs/testing';
+import { GoogleStrategy } from '@/shared/auth/google.strategy';
+
+describe('GoogleStrategy', () => {
+  let strategy: GoogleStrategy;
+
+  const mockConfigService = {
+    getOrThrow: jest.fn((key: string) => {
+      const config: Record<string, string> = {
+        GOOGLE_CLIENT_ID: 'test-client-id',
+        GOOGLE_CLIENT_SECRET: 'test-client-secret',
+        GOOGLE_CALLBACK_URL: 'http://localhost:3000/auth/google/callback',
+      };
+      return config[key];
+    }),
+  };
+
+  beforeEach(async () => {
+    const module = await Test.createTestingModule({
+      providers: [GoogleStrategy, { provide: ConfigService, useValue: mockConfigService }],
+    }).compile();
+
+    strategy = module.get(GoogleStrategy);
+  });
+
+  it('should be defined', () => {
+    expect(strategy).toBeDefined();
+  });
+
+  it('should extract user profile from Google OAuth callback', () => {
+    const profile = {
+      id: 'google-123',
+      displayName: 'Test User',
+      emails: [{ value: 'test@example.com', verified: true }],
+      photos: [{ value: 'https://lh3.googleusercontent.com/photo.jpg' }],
+    };
+    const done = jest.fn();
+
+    strategy.validate('access-token', 'refresh-token', profile as any, done);
+
+    expect(done).toHaveBeenCalledWith(null, {
+      provider: 'google',
+      providerId: 'google-123',
+      email: 'test@example.com',
+      name: 'Test User',
+      avatar: 'https://lh3.googleusercontent.com/photo.jpg',
+      accessToken: 'access-token',
+    });
+  });
+
+  it('should handle profile with missing optional fields', () => {
+    const profile = {
+      id: 'google-456',
+      displayName: 'No Email User',
+      emails: undefined,
+      photos: undefined,
+    };
+    const done = jest.fn();
+
+    strategy.validate('access-token', 'refresh-token', profile as any, done);
+
+    expect(done).toHaveBeenCalledWith(null, {
+      provider: 'google',
+      providerId: 'google-456',
+      email: undefined,
+      name: 'No Email User',
+      avatar: undefined,
+      accessToken: 'access-token',
+    });
+  });
+});

package/templates/recipes/oauth2-introspection/README.md

@@ -0,0 +1,62 @@
+# OAuth 2.0 Token Introspection
+
+Validates opaque OAuth 2.0 access tokens by calling a token introspection endpoint as defined in [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662).
+
+## When to use
+
+Use this recipe when your application receives **opaque** (non-JWT) access tokens that must be validated against an authorization server. If your tokens are self-contained JWTs, use the `jwt-auth` recipe instead.
+
+## Environment variables
+
+| Variable                   | Required | Default                                      | Description                           |
+| -------------------------- | -------- | -------------------------------------------- | ------------------------------------- |
+| `OAUTH2_INTROSPECTION_URL` | Yes      | `https://auth.example.com/oauth2/introspect` | Token introspection endpoint URL      |
+| `OAUTH2_CLIENT_ID`         | Yes      | —                                            | OAuth 2.0 client ID for introspection |
+| `OAUTH2_CLIENT_SECRET`     | Yes      | —                                            | OAuth 2.0 client secret               |
+
+## Usage
+
+Apply the guard to any controller or route that requires a valid OAuth 2.0 token:
+
+```typescript
+import { Controller, Get, UseGuards } from '@nestjs/common';
+import { TokenIntrospectionGuard } from '@/shared/guards/token-introspection.guard';
+
+@Controller('protected')
+@UseGuards(TokenIntrospectionGuard)
+export class ProtectedController {
+  @Get()
+  getProtectedResource() {
+    return { message: 'You have a valid token' };
+  }
+}
+```
+
+Access the authenticated user information via the request object:
+
+```typescript
+import { Controller, Get, Req, UseGuards } from '@nestjs/common';
+import { TokenIntrospectionGuard } from '@/shared/guards/token-introspection.guard';
+import { FastifyRequest } from 'fastify';
+
+@Controller('me')
+@UseGuards(TokenIntrospectionGuard)
+export class MeController {
+  @Get()
+  getProfile(@Req() request: FastifyRequest) {
+    return (request as any).user;
+  }
+}
+```
+
+## How it works
+
+1. Extracts the `Bearer` token from the `Authorization` header.
+2. Sends a `POST` request to the introspection endpoint with the token and client credentials (HTTP Basic auth).
+3. If the response indicates `active: true`, the guard attaches the token metadata (`sub`, `username`, `scope`, `clientId`) to `request.user`.
+4. If the token is inactive or the introspection call fails, a `401 Unauthorized` response is returned.
+
+## References
+
+- [RFC 7662 - OAuth 2.0 Token Introspection](https://datatracker.ietf.org/doc/html/rfc7662)
+- [NestJS Guards](https://docs.nestjs.com/guards)

package/templates/recipes/oauth2-introspection/src/shared/guards/token-introspection.guard.ts

@@ -0,0 +1,77 @@
+import {
+  CanActivate,
+  ExecutionContext,
+  Injectable,
+  UnauthorizedException,
+  Logger,
+} from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { FastifyRequest } from 'fastify';
+
+interface IntrospectionResponse {
+  active: boolean;
+  scope?: string;
+  client_id?: string;
+  username?: string;
+  sub?: string;
+  exp?: number;
+}
+
+@Injectable()
+export class TokenIntrospectionGuard implements CanActivate {
+  private readonly logger = new Logger(TokenIntrospectionGuard.name);
+  private readonly introspectionUrl: string;
+  private readonly clientId: string;
+  private readonly clientSecret: string;
+
+  constructor(private readonly configService: ConfigService) {
+    this.introspectionUrl = this.configService.getOrThrow<string>('OAUTH2_INTROSPECTION_URL');
+    this.clientId = this.configService.getOrThrow<string>('OAUTH2_CLIENT_ID');
+    this.clientSecret = this.configService.getOrThrow<string>('OAUTH2_CLIENT_SECRET');
+  }
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const request = context.switchToHttp().getRequest<FastifyRequest>();
+    const authHeader = request.headers.authorization;
+
+    if (!authHeader?.startsWith('Bearer ')) {
+      throw new UnauthorizedException('Missing or invalid Authorization header');
+    }
+
+    const token = authHeader.slice(7);
+    const result = await this.introspect(token);
+
+    if (!result.active) {
+      throw new UnauthorizedException('Token is not active');
+    }
+
+    (request as any).user = {
+      sub: result.sub,
+      username: result.username,
+      scope: result.scope,
+      clientId: result.client_id,
+    };
+
+    return true;
+  }
+
+  private async introspect(token: string): Promise<IntrospectionResponse> {
+    const credentials = Buffer.from(`${this.clientId}:${this.clientSecret}`).toString('base64');
+
+    const response = await fetch(this.introspectionUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Authorization: `Basic ${credentials}`,
+      },
+      body: `token=${encodeURIComponent(token)}`,
+    });
+
+    if (!response.ok) {
+      this.logger.error(`Introspection endpoint returned ${response.status}`);
+      throw new UnauthorizedException('Token introspection failed');
+    }
+
+    return (await response.json()) as IntrospectionResponse;
+  }
+}

package/templates/recipes/oauth2-introspection/tests/unit/shared/guards/token-introspection.guard.spec.ts

@@ -0,0 +1,99 @@
+import { ExecutionContext, UnauthorizedException } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { Test } from '@nestjs/testing';
+import { TokenIntrospectionGuard } from '@/shared/guards/token-introspection.guard';
+
+describe('TokenIntrospectionGuard', () => {
+  let guard: TokenIntrospectionGuard;
+
+  const mockConfigService = {
+    getOrThrow: jest.fn((key: string) => {
+      const config: Record<string, string> = {
+        OAUTH2_INTROSPECTION_URL: 'https://auth.example.com/introspect',
+        OAUTH2_CLIENT_ID: 'client-id',
+        OAUTH2_CLIENT_SECRET: 'client-secret',
+      };
+      return config[key];
+    }),
+  };
+
+  function createMockContext(authHeader?: string): ExecutionContext {
+    return {
+      switchToHttp: () => ({
+        getRequest: () => ({
+          headers: { authorization: authHeader },
+        }),
+      }),
+    } as unknown as ExecutionContext;
+  }
+
+  beforeEach(async () => {
+    const module = await Test.createTestingModule({
+      providers: [TokenIntrospectionGuard, { provide: ConfigService, useValue: mockConfigService }],
+    }).compile();
+
+    guard = module.get(TokenIntrospectionGuard);
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('should be defined', () => {
+    expect(guard).toBeDefined();
+  });
+
+  it('should throw UnauthorizedException when Authorization header is missing', async () => {
+    const context = createMockContext(undefined);
+    await expect(guard.canActivate(context)).rejects.toThrow(UnauthorizedException);
+  });
+
+  it('should throw UnauthorizedException when Authorization header does not use Bearer scheme', async () => {
+    const context = createMockContext('Basic dXNlcjpwYXNz');
+    await expect(guard.canActivate(context)).rejects.toThrow(UnauthorizedException);
+  });
+
+  it('should throw UnauthorizedException when token is not active', async () => {
+    jest.spyOn(global, 'fetch').mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ active: false }),
+    } as Response);
+
+    const context = createMockContext('Bearer expired-token');
+    await expect(guard.canActivate(context)).rejects.toThrow(UnauthorizedException);
+  });
+
+  it('should set request.user and return true for an active token', async () => {
+    const introspectionResponse = {
+      active: true,
+      sub: 'user-123',
+      username: 'testuser',
+      scope: 'read write',
+      client_id: 'client-id',
+    };
+
+    jest.spyOn(global, 'fetch').mockResolvedValueOnce({
+      ok: true,
+      json: async () => introspectionResponse,
+    } as Response);
+
+    const request: Record<string, unknown> = {
+      headers: { authorization: 'Bearer valid-token' },
+    };
+    const context = {
+      switchToHttp: () => ({
+        getRequest: () => request,
+      }),
+    } as unknown as ExecutionContext;
+
+    const result = await guard.canActivate(context);
+
+    expect(result).toBe(true);
+    expect(request.user).toEqual({
+      sub: 'user-123',
+      username: 'testuser',
+      scope: 'read write',
+      clientId: 'client-id',
+    });
+  });
+});

package/templates/recipes/opentelemetry/README.md

@@ -0,0 +1,44 @@
+# OpenTelemetry
+
+Distributed tracing and metrics collection using the OpenTelemetry SDK.
+
+## Links
+
+- [OpenTelemetry JS Documentation](https://opentelemetry.io/docs/languages/js/)
+- [@opentelemetry/sdk-node on npm](https://www.npmjs.com/package/@opentelemetry/sdk-node)
+- [@opentelemetry/api on npm](https://www.npmjs.com/package/@opentelemetry/api)
+- [OpenTelemetry JS on GitHub](https://github.com/open-telemetry/opentelemetry-js)
+
+## Dependencies
+
+| Package                                   | Version  | Purpose                          |
+| ----------------------------------------- | -------- | -------------------------------- |
+| `@opentelemetry/sdk-node`                 | `0.57.2` | OpenTelemetry Node.js SDK        |
+| `@opentelemetry/api`                      | `1.9.0`  | OpenTelemetry API                |
+| `@opentelemetry/exporter-trace-otlp-http` | `0.57.2` | OTLP HTTP trace exporter         |
+| `@opentelemetry/instrumentation-http`     | `0.57.2` | Auto-instrumentation for HTTP    |
+| `@opentelemetry/instrumentation-fastify`  | `0.44.2` | Auto-instrumentation for Fastify |
+| `@opentelemetry/resources`                | `1.30.1` | Resource attributes              |
+| `@opentelemetry/semantic-conventions`     | `1.30.0` | Semantic convention constants    |
+
+## Environment Variables
+
+| Variable                      | Description             | Example                 |
+| ----------------------------- | ----------------------- | ----------------------- |
+| `OTEL_SERVICE_NAME`           | Service name for traces | `my-api`                |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP collector endpoint | `http://localhost:4318` |
+
+## Usage
+
+Import the tracing setup **before** any other application code in `main.ts`:
+
+```typescript
+import '@/infrastructure/telemetry/tracing';
+import { NestFactory } from '@nestjs/core';
+```
+
+## Generated Files
+
+| File                                      | Description                            |
+| ----------------------------------------- | -------------------------------------- |
+| `src/infrastructure/telemetry/tracing.ts` | OTel SDK setup with NodeTracerProvider |

package/templates/recipes/opentelemetry/src/infrastructure/telemetry/tracing.ts

@@ -0,0 +1,38 @@
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { HttpInstrumentation } from '@opentelemetry/instrumentation-http';
+import { FastifyInstrumentation } from '@opentelemetry/instrumentation-fastify';
+import { Resource } from '@opentelemetry/resources';
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
+
+const serviceName = process.env.OTEL_SERVICE_NAME || 'nestjs-app';
+const exporterEndpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318';
+
+const sdk = new NodeSDK({
+  resource: new Resource({
+    [ATTR_SERVICE_NAME]: serviceName,
+    [ATTR_SERVICE_VERSION]: process.env.npm_package_version || '0.0.0',
+  }),
+  traceExporter: new OTLPTraceExporter({
+    url: `${exporterEndpoint}/v1/traces`,
+  }),
+  instrumentations: [
+    new HttpInstrumentation({
+      ignoreIncomingRequestHook: (request) => {
+        const url = request.url || '';
+        return url.includes('/health') || url.includes('/readiness');
+      },
+    }),
+    new FastifyInstrumentation(),
+  ],
+});
+
+sdk.start();
+
+process.on('SIGTERM', async () => {
+  await sdk.shutdown();
+});
+
+process.on('SIGINT', async () => {
+  await sdk.shutdown();
+});

package/templates/recipes/opentelemetry/tests/unit/infrastructure/telemetry/tracing.spec.ts

@@ -0,0 +1,23 @@
+import { Resource } from '@opentelemetry/resources';
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
+
+describe('OpenTelemetry tracing configuration', () => {
+  it('should build a Resource with the expected service name attribute', () => {
+    const serviceName = 'test-service';
+    const resource = new Resource({
+      [ATTR_SERVICE_NAME]: serviceName,
+      [ATTR_SERVICE_VERSION]: '1.0.0',
+    });
+
+    expect(resource.attributes[ATTR_SERVICE_NAME]).toBe(serviceName);
+    expect(resource.attributes[ATTR_SERVICE_VERSION]).toBe('1.0.0');
+  });
+
+  it('should fall back to defaults when environment variables are not set', () => {
+    const defaultName = process.env.OTEL_SERVICE_NAME || 'nestjs-app';
+    const defaultEndpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318';
+
+    expect(defaultName).toBe('nestjs-app');
+    expect(defaultEndpoint).toBe('http://localhost:4318');
+  });
+});

package/templates/recipes/pagination/README.md

@@ -0,0 +1,71 @@
+# Pagination
+
+Offset-based pagination pattern with reusable DTOs and a parameter decorator.
+
+## Links
+
+- [NestJS Techniques: Serialization](https://docs.nestjs.com/techniques/serialization)
+- [class-validator on npm](https://www.npmjs.com/package/class-validator)
+- [class-transformer on npm](https://www.npmjs.com/package/class-transformer)
+
+## Dependencies
+
+| Package             | Version  | Purpose                   |
+| ------------------- | -------- | ------------------------- |
+| `class-validator`   | `0.14.1` | DTO validation decorators |
+| `class-transformer` | `0.5.1`  | DTO transformation        |
+
+## Usage
+
+```typescript
+import { PaginatedQuery, PaginatedResponse } from '@/shared/dto/pagination.dto';
+import { Paginate } from '@/shared/decorators/paginate.decorator';
+
+@Get()
+async findAll(@Paginate() query: PaginatedQuery): Promise<PaginatedResponse<User>> {
+  const [items, total] = await this.userRepo.findAndCount({
+    skip: query.skip,
+    take: query.limit,
+  });
+
+  return new PaginatedResponse(items, total, query.page, query.limit);
+}
+```
+
+## RFC 8288 Link Headers
+
+The pagination recipe includes an interceptor that automatically adds [RFC 8288](https://www.rfc-editor.org/rfc/rfc8288) `Link` headers to paginated responses. These headers allow API clients to navigate between pages without parsing the response body.
+
+### Setup
+
+Apply the `PaginationLinkInterceptor` globally or on specific controllers:
+
+```typescript
+import { PaginationLinkInterceptor } from '@/shared/interceptors/pagination-link.interceptor';
+
+// Global (in main.ts or AppModule)
+app.useGlobalInterceptors(new PaginationLinkInterceptor());
+
+// Or per-controller
+@UseInterceptors(PaginationLinkInterceptor)
+@Controller('users')
+export class UserController {}
+```
+
+The interceptor inspects each response for a `pagination` property. When found, it generates a `Link` header with `prev`, `next`, `first`, and `last` relations:
+
+```
+Link: <https://api.example.com/users?page=2&pageSize=20>; rel="next",
+      <https://api.example.com/users?page=1&pageSize=20>; rel="first",
+      <https://api.example.com/users?page=5&pageSize=20>; rel="last"
+```
+
+A standalone `buildPaginationLinks` utility is also exported from `pagination.dto.ts` for manual use.
+
+## Generated Files
+
+| File                                                     | Description                                   |
+| -------------------------------------------------------- | --------------------------------------------- |
+| `src/shared/dto/pagination.dto.ts`                       | `PaginatedQuery` and `PaginatedResponse` DTOs |
+| `src/shared/decorators/paginate.decorator.ts`            | `@Paginate()` parameter decorator             |
+| `src/shared/interceptors/pagination-link.interceptor.ts` | RFC 8288 `Link` header interceptor            |