docs: add SSE and webhook event documentation to Swagger

[Mainnet-ops]

Add comprehensive OpenAPI documentation for the real-time event systems:

• Create PolicyStatusEventDto for SSE event payload schema
• Create webhook DTOs (RegisterWebhookDto, WebhookRegistrationResponseDto, WebhookListItemDto, PolicyStatusChangePayloadDto, ClaimStatusChangePayloadDto) with validation decorators and Swagger metadata
• Document SSE endpoint with event data schema, status transition table, and EventSource connection example
• Document webhook registration with event type table, payload schemas, and HMAC-SHA256 signature verification instructions
• Add 'webhooks' and 'events' tags to Swagger config in DocumentBuilder

About this PR

Closes #405
Closes #406
Closes #407
Closes #408
What changed (5 files, +166/-9):

• src/common/events/dto/sse-event.dto.ts (new) — PolicyStatusEventDto documenting the SSE event payload (policyId, status, timestamp) with status enum values.

• src/common/webhooks/dto/webhook.dto.ts (new) — Full set of webhook DTOs:

  • RegisterWebhookDto with class-validator decorators
  • WebhookRegistrationResponseDto, WebhookListItemDto
  • PolicyStatusChangePayloadDto, ClaimStatusChangePayloadDto for delivery payloads
  • WebhookEventType enum (policy.status.change, claim.status.change)

• src/policy/policy.controller.ts — SSE endpoint now has a detailed description with status transition table, event data schema, and an EventSource connection example. Response schema references PolicyStatusEventDto.

• src/common/webhooks/webhooks.controller.ts — Registration endpoint documents the event type table with payload shapes, HMAC-SHA256 signature verification instructions, and uses typed DTOs instead of inline any. List endpoint response schema references WebhookListItemDto.

• src/main.ts — Added webhooks and events tags to the Swagger DocumentBuilder.

This PR resolves 4 enhancement issues:

Changes

#375 - API versioning strategy

• Implemented API versioning interceptor that adds X-API-Version response header
• Added Deprecation header for v1 with Link header pointing to v2 successor
• Updated Swagger config to support x-api-version header for API version negotiation

#373 - Pagination on policy and claims list endpoints

• Added page and limit query parameters to GET /api/v1/products endpoint
• Updated getActiveProducts service method to support Prisma-based pagination with take/skip
• Claims list endpoints (getClaimsByWalletQuery, getClaimHistory) already had pagination

#372 - Rate limiting on claim submission endpoint

• Added claim-specific rate limiting (limit: 5/60s) to POST /api/v1/claims endpoint
• Uses @Throttle decorator with stricter limits than global throttler (60/60s)

#374 - Webhook support for policy/claim status changes

• Created WebhooksService with register/unregister/list and status notification methods
• Created WebhooksController with POST /api/v1/webhooks/register and GET /api/v1/webhooks endpoints
• Policy status changes (e.g., cancel) trigger webhooks with policy.status.change event
• Claim status changes (e.g., PROCESSING → FAILED, PROCESSING → CLAIMED) trigger webhooks with claim.status.change event

Issue Closure

This PR closes the following issues using GitHub keyword syntax:

• Closes [Enhancement] No API versioning strategy #375 - API versioning strategy
• Closes [Enhancement] No pagination on policy and claims list endpoints #373 - No pagination on policy and claims list endpoints
• Closes [Enhancement] No rate limiting on claim submission endpoint #372 - No rate limiting on claim submission endpoint
• Closes [Enhancement] No webhook support for policy/claim status changes #374 - No webhook support for policy/claim status changes

Verification

• All endpoints return proper pagination metadata ({ success, data, total, page, limit })
• Rate limiting prevents claim submission spam beyond 5 attempts per 60 seconds
• Webhooks can be registered with specific events (policy.status.change, claim.status.change)
• API versioning headers are present on all responses

[drips-wave]

@Mainnet-ops Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits