refactor(server): replace try/catch with neverthrow Result types

[Gengyscan]

Summary

Systematic bottom-up migration of error handling from try/catch to neverthrow Result types across the server package. 62 try/catch blocks analyzed, 33 converted (53% reduction), 29 intentionally kept where try/catch is the correct pattern.

What changed

New error types (errors/results.ts)

Discriminated union types — DbError, AuthError, SettleError, RefundError, ResourceError — for typed error handling throughout the codebase. Each variant carries structured context for downstream handling.

Data layer (DbService)

All methods return ResultAsync<T, DbError> via ResultAsync.fromPromise(), replacing try/catch at the database boundary.

Services

• EchoControlService: Business logic uses neverthrow chains with .andThen() for composable error propagation
• FreeTierService: Free tier flow returns typed Results
• HandleStreamService: Streaming response handling in ResultAsync
• ModelRequestService: Request preparation with typed errors

Handlers

• handlers.ts: Main request handler uses .match() to map typed errors to HTTP status codes
• settle.ts: Settlement flow with SettleError discrimination
• refund.ts: Refund flow with RefundError handling
• resources/handler.ts: Resource handler with ResourceError mapping

All HTTP boundaries preserve existing status code contracts (401, 402, 429, 500).

All providers (10 total)

handleBody() methods across all providers use ResultAsync.fromPromise():
AnthropicGPT, AnthropicNative, GPT, GeminiGPT, Gemini, Groq, OpenAIImage, OpenAIResponses, OpenRouter, XAI

Resources

• e2b: Code execution wrapped in ResultAsync

Migration strategy

Bottom-up: DB → Services → Handlers → Providers

Each layer returns typed Results that compose naturally via .andThen() chains. HTTP handler boundaries use .match() to convert discriminated error types to appropriate HTTP status codes. Provider handleBody() methods use the transitional pattern (ResultAsync.fromPromise() + .match() throw) to maintain API compatibility while using neverthrow internally.

Remaining try/catch (29 of 62)

Intentionally preserved where neverthrow adds no value:

• Top-level bootstrap (server.ts) — can't use Result at process entry point
• SSE parser defensive parsing — try/catch in loops for individual chunk parsing with continue-on-error
• Express route handlers — catch → next(error) is the idiomatic Express pattern
• Standalone client scripts — not part of server runtime
• Fetch timeout cleanup (facilitators) — try/finally for clearTimeout
• Type definitions and test files

Validation

• \ sc --noEmit: 0 errors
• HTTP contract preservation verified (401/402/429 responses unchanged)
• No changes to test files
• No changes to public API surface

Closes #581

[vercel]

@Gengyscan is attempting to deploy a commit to the Merit Systems Team on Vercel.

A member of the Team first needs to authorize it.

[Gengyscan]

Summary

This PR delivers a systematic, bottom-up migration from try/catch to neverthrow Result types across the entire server package.

Results

• 33 try/catch converted out of 62 total (53% reduction)
• 29 intentionally kept where try/catch is the correct pattern (bootstrap, SSE parsers, Express middleware, standalone scripts)
• 0 TypeScript errors ( sc --noEmit clean)
• No breaking changes to public API — HTTP 401/402/429 contracts fully preserved

Architecture

• Discriminated union error types: DbError, AuthError, SettleError, RefundError, ResourceError — each variant carries structured context
• Bottom-up migration: DB layer → Services → Handlers → All 10 providers
• Composable chains: .andThen() for error propagation, .match() at HTTP boundaries for status code mapping

Files touched

26 files, +1,238 / -1,084 lines — one clean squashed commit.

---

Happy to discuss the approach, iterate on feedback, or walk through any specific conversion in detail. For faster communication, feel free to reach me on Discord: gmttgengyscang