[CmxTop]

…lth probes from tracing

#756 [bug] Claims module does not handle timezone differences in date comparisons:

• Introduce UTC helpers (utcNow, utcNowMs, utcPlusMs) in src/common/utils/time.utils.ts
• Route all claim-window date comparisons in ClaimsService and ClaimsWorker through the UTC helpers so comparisons against Prisma's UTC-stored policy.endTime are explicit and auditable
• Add docs/CLAIMS_TIMEZONE_HANDLING.md auditing every date usage in the claims module
• Add tests covering timezone edge cases (UTC midnight boundary, fixed-clock comparisons) in claims.service.spec.ts and time.utils.spec.ts

#754 [perf] OpenTelemetry spans created for health check endpoints:

• Configure @opentelemetry/instrumentation-http with an ignoreUrls list so /api/v1/health and /health no longer generate spans
• Add parseIgnoreUrls() helper; defaults are merged with OTEL_HTTP_INSTRUMENTATION_IGNORE_URLS so built-in health probes are always excluded
• Add tests for the exclusion config in opentelemetry.spec.ts

#753 [bug] Policy module does not validate oracle threshold range:t (DTO range validation for CreateProductDto/UpdateProductDto threshold)

#755 [security] API key middleware does not hash stored API keys:
(hash API keys with bcrypt/argon2, store only hashes)

About this PR

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