name: trembita-http-client description: Build resilient, type-safe HTTP integrations with trembita using Result-based error handling, retries, and circuit breaker patterns.

Trembita Skill

Use this repository as a practical reference for agents implementing HTTP clients with trembita.

When to Use

• Build TypeScript integrations for third-party REST APIs.
• Add robust error handling without exception-driven control flow.
• Implement retries, circuit breakers, and timeouts with minimal dependencies.
• Write testable API code by injecting fetchImpl.

Core Patterns

1. Initialize once with createTrembita() and handle init Result.
2. Use client.request() for parsed JSON body responses.
3. Use client.client() when you need HTTP metadata (statusCode, body).
4. Narrow failures by checking result.error.kind.
5. Add resilience via createRetryingFetch and circuitBreaker config.

Canonical References

• README.md - quick overview and install.
• QUICK_START.md - shortest path to first success.
• LEARNING_GUIDE.md - concepts and progressive examples.
• EXAMPLES.md - production-style patterns.
• ARCHITECTURE.md - request/error flow diagrams.

Agent Guardrails

• Prefer Result handling over try/catch for request outcomes.
• Keep endpoint configuration explicit and validated.
• Prefer expectedCodes to document acceptable HTTP outcomes.
• Use client.client() for 404/202 branching by status code.
• Inject fetchImpl in tests; avoid global fetch patching.