chore(api): migrate omnichannel single-route endpoints to typed HTTP methods

Draft
GG
3mo ago
+987-419

Proposed changes

Continues the API endpoint migration (docs/api-endpoint-migration.md): moves legacy API.v1.addRoute() omnichannel endpoints to the typed API.v1.get/post/put pattern with AJV request/response validation.

Migrated (14 single-route files)

  • livechat/offline.message, livechat/integrations.settings, livechat/queue, livechat/transfer.history/:rid, livechat/page.visited, livechat/agents/:agentId/departments, livechat/webhook.test, omnichannel/integrations, livechat/appearance (GET + POST), livechat/business-hour, livechat/config
  • ee: livechat/business-hours, livechat/inquiry.setSLA, omnichannel/:rid/request-transcript

Pre-existing typed endpoints keep their manual rest-typings entry (moderation pattern); untyped ones (webhook.test, request-transcript) are augmented via ExtractRoutesFromAPI.

Docs

Extended docs/api-endpoint-migration.md:

  • New section on migrating endpoints already declared in Endpoints (keep manual entry, do not re-augment — avoids TS2717).
  • New "Common Type Errors" section: SuccessResult interface-vs-object-literal, optional this.user.username/this.requestIp, failure() requiring 400, method-scoped permissionsRequired.
  • Refreshed reference paths after the backend reorg (#41126).

Notes

  • No behavior change — pure refactor/typing; no changeset needed.
  • upload.ts and sms.ts deferred (complex payloads; upload hits the known IMessage attachment oneOf validation issue). ~223 addRoute calls remain repo-wide.

Testing

  • tsc --noEmit clean for all migrated files.
  • eslint + prettier clean.
  • Response schemas validate only under TEST_MODE; no migrated GET-query path asserts the old invalid-params error format, so no e2e test changes required.

Summary by CodeRabbit

  • Improvements
    • Standardized multiple Livechat omnichannel endpoints to use explicit AJV-based request/response validation with consistent success and error payloads (including business hours, inquiries/SLA, transcripts, agent departments, appearance, config, integrations, offline messages, page visited, queue metrics, transfers, and webhooks).
    • Refined error handling and response shaping for invalid-room/access and webhook/transcript failure scenarios.
    • Improved robustness with test-mode cache timing adjustments and safer audit metadata defaults.
  • Documentation
    • Updated the API Endpoint Migration Guide with new conventions, conflict guidance, troubleshooting, and expanded schema reference coverage.
  • Chores
    • Expanded the shared AJV schema bundle to include additional Livechat and settings types.