Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

How It’s Built

Covering 11 APIs — several with hundreds of nested schemas — without drowning in hand-written models comes down to a deliberate two-layer split.

1. Type backbone (all 11 APIs)

openapi-typescript generates a paths/components type module per API into src/generated/. A single generic combinator, api<paths>() (core/typed.ts), turns any of them into typed, Effect-returning calls: path params, query, body, and the success response are all inferred from the generated type. Unknown paths, missing path params, and wrong body types don’t compile.

const call = api<paths>()
call("/v4/policies/{master-agreement-number}/policyspecs", "get", {
  path: { "master-agreement-number": mag },
}) // Effect<Transmission, TutelaError, RequestContext>

Regenerate the backbone whenever the specs change:

pnpm gen   # specs → src/generated/*.ts

2. Curated runtime validation (where it matters)

For the resources worth extra care, a hand-written layer adds effect/Schema response decoding and richer ergonomics (e.g. the EOI type-state builder). Response envelopes are decoded at runtime; the large request bodies are typed via the generated types rather than re-derived by hand.

Why this route

openapi-typescript consumes the OpenAPI 3.0 specs natively and is widely maintained. The alternatives didn’t fit:

  • openapi-to-effect is OpenAPI 3.1-only and targets the deprecated @effect/schema.
  • Hand-writing the 500-schema specs was never an option.

Project layout

src/
├── index.ts              # the Tutela entry point + live Layer wiring
├── core/
│   ├── brand.ts          # branded id constructors
│   ├── errors.ts         # the tagged TutelaError union
│   ├── config.ts         # TutelaConfig service (+ fromEnv)
│   ├── auth.ts           # OAuth2 client-credentials TokenProvider
│   ├── http.ts           # the `request` transport combinator
│   ├── typed.ts          # generic api<paths>() combinator (inference engine)
│   └── request-builder.ts# type-state machinery
├── generated/            # openapi-typescript output, one module per API (11)
├── schema/               # effect/Schema models for curated resources
└── resources/            # the per-API clients