feat: improve developer experience with validation, health checks, and guidelines

[Just-Bamford]

Summary

Resolves four critical issues to improve code quality, developer experience, and operational visibility.

Closes #213
Closes #212
Closes #214
Closes #215

Changes

1. Webhook Event Type Validation

• Enhanced webhookSubscriptionSchema in src/validation/schemas.js with superRefine for detailed error reporting
• Invalid event types now clearly show:
  • Which events are unknown
  • All valid events available for subscription
  • Examples: "Unknown event type(s): totally.fake. Valid events are: pool.created, pool.assets_locked, ..."
• Prevents permanently dead webhook subscriptions due to typos
• Test updated: test/webhooks.routes.test.js now validates error message content

2. Price Source Health Tracking

• Added last_success_at timestamp tracking to circuit breakers in src/services/sources/circuitBreaker.js
• When a fetch succeeds, close() now records the timestamp
• /health endpoint includes last_success_at per source in price_source_circuits
• Operators can now see when CoinGecko/CoinMarketCap APIs were last successfully reached
• Updated tests in test/circuitBreaker.test.js to validate timestamp tracking

3. Swagger UI Authentication Support

• Updated openapi.yaml security scheme from HTTP bearer to apiKey type
• Changed from type: http, scheme: bearer to type: apiKey, in: header, name: Authorization
• Improved description to clarify format: "Bearer " prefix required
• Swagger UI now provides a dedicated input field for API key testing on protected endpoints
• Updated test expectations in test/api-docs.test.js

4. Comprehensive Developer Guide

• Created CONTRIBUTING.md with complete development guidelines:
  • Setup: Docker Compose (recommended) and local development options
  • Testing: How to run tests, coverage details, key test files
  • Code style: ESLint and OpenAPI linting requirements
  • Migrations: Running, writing, and testing database migrations
  • Git workflow: Branching strategy and local setup process
  • PR guidelines: Pre-submission checklist and PR template
  • Commit conventions: Semantic commit format with examples
  • Troubleshooting: Common issues and solutions

[drips-wave]

@Just-Bamford 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