feat: add comprehensive OpenAPI documentation and refactor routes

[typelets]

Summary

This PR adds comprehensive OpenAPI/Swagger documentation for all API endpoints and refactors route files into a
modular folder structure. It also fixes several TypeScript type inference issues and resolves critical bugs with
route registration and rate limiting.

Changes

📚 OpenAPI/Swagger Documentation

• Added complete Swagger documentation for all endpoints:
  • Files endpoints (upload, list, get, delete)
  • Code execution endpoints (execute, status, languages, health)
  • Notes endpoints (CRUD, actions, trash, counts)
  • Folders endpoints (CRUD, actions)
  • Users endpoints (profile, delete)
• Added Swagger UI accessible at /docs
• Added OpenAPI spec endpoint at /api/openapi.json
• Created comprehensive schemas in src/lib/openapi-schemas.ts
• Updated README with link to production Swagger docs: https://api.typelets.com/docs

🗂️ Route Refactoring

• Refactored monolithic route files into modular folder structure:
  • src/routes/folders/ → crud.ts + actions.ts
  • src/routes/notes/ → crud.ts + actions.ts + trash.ts + counts.ts
  • src/routes/files/ → crud.ts
  • src/routes/users/ → crud.ts
  • src/routes/code/ → crud.ts
• Added descriptive route comments matching consistent style
• Improved code organization and maintainability

🔧 TypeScript Fixes

• Fixed type inference issues with @hono/zod-openapi validators
• Removed explicit Context type annotations that broke type inference
• Added proper RouteHandler<typeof route> types for separately defined handlers
• Fixed all type errors across 20+ route handlers
• Added type guards for error handling (instanceof Error)
• Added non-null assertions for validated environment variables

🐛 Bug Fixes

• Critical: Fixed empty trash route being caught by /{id} route
  • Reordered route registration so specific paths are checked before parameterized routes
  • src/server.ts:361 - trash router now registered before crud router
• Rate Limiting: Increased file download rate limit in development
  • Changed from 100 to 1000 requests per 15 minutes in dev mode
  • Production limit remains at 100 requests per 15 minutes
  • Configurable via HTTP_FILE_RATE_LIMIT_MAX environment variable

📝 Documentation

• Updated README.md with prominent link to Swagger documentation
• Added OpenAPI badges and references throughout documentation

Test Plan

• All routes tested with Swagger UI
• Empty trash endpoint works correctly
• File downloads no longer hit rate limits during testing
• TypeScript compilation succeeds with no errors
• Linting passes (9 acceptable warnings for OpenAPI dynamic typing)
• Build succeeds
• Web application tested successfully
• Mobile application testing in progress

Breaking Changes

None - this is purely additive and fixes existing bugs.

[typelets]

🎉 This PR is included in version 1.8.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀