get to prod tasks

tasks/web-production/29-api-documentation.md

@@ -0,0 +1,82 @@
+# 29. API Documentation (OpenAPI/tRPC Docs)
+
+meta:
+  id: web-production-29
+  feature: web-production
+  priority: P2
+  depends_on: []
+  tags: [api, documentation, production]
+
+objective:
+- Generate and publish comprehensive API documentation for internal and external developers
+
+deliverables:
+- Auto-generated API documentation
+- Interactive API explorer
+- Authentication documentation
+- Error code reference
+
+steps:
+1. Set up tRPC documentation generation:
+   - Use trpc-openapi or @trpc/openapi-v3 to generate OpenAPI spec
+   - Or use trpc-docs or @trpc/doc-generator
+   - Export spec as JSON/YAML
+2. Create documentation site:
+   - Use Swagger UI or Scalar for interactive docs
+   - Host at /api/docs or separate docs subdomain
+   - Include request/response examples
+   - Include authentication requirements
+3. Document all routers:
+   - User router: login, signup, profile, family
+   - Billing router: subscription, checkout, webhooks
+   - DarkWatch router: watchlist, exposures, scan
+   - VoicePrint router: enrollments, analysis
+   - SpamShield router: rules, phone check
+   - HomeTitle router: properties, monitoring
+   - RemoveBrokers router: listings, removals
+   - Alerts router: list, resolve, correlation
+   - Admin router: user management, blog
+4. Add authentication docs:
+   - Session cookie authentication
+   - JWT bearer token authentication
+   - API key authentication (for extensions)
+   - Clerk webhook handling
+5. Add error documentation:
+   - Standard error codes (400, 401, 403, 404, 429, 500)
+   - tRPC error codes and meanings
+   - Rate limit headers explanation
+6. Add webhook documentation:
+   - Stripe webhook events
+   - Clerk webhook events
+   - Payload schemas and verification
+7. Keep docs in sync:
+   - Auto-generate on build
+   - CI check for doc changes
+   - Version docs with API versions
+
+tests:
+- Unit: Test OpenAPI spec generation
+- Integration: Verify docs site loads and examples work
+- Review: Team review for accuracy
+
+acceptance_criteria:
+- API docs accessible at /api/docs
+- All tRPC routers documented with input/output schemas
+- Interactive explorer allowing test requests
+- Authentication methods documented with examples
+- All error codes explained with examples
+- Webhook payloads documented with verification steps
+- Docs auto-generated from code (single source of truth)
+- Examples use realistic test data
+
+validation:
+- Navigate to /api/docs → interactive explorer loads
+- Try user.me endpoint → returns example response
+- Check auth section → all methods documented
+- Review webhook docs → verification steps clear
+
+notes:
+- trpc-openapi requires adding meta tags to procedures
+- Consider using Scalar (modern alternative to Swagger UI)
+- Docs should be public but sensitive endpoints marked as auth-required
+- Keep examples updated when schemas change