Catch a breaking API change before your users do

Task

A vendor can rename or drop a field without telling you, and a plain type check will not notice until something breaks in production. You want a hard failure the moment a field you depend on disappears, and soft notifications for other structural changes — without committing a snapshot or maintaining a baseline.

Example

Wrap the output schema with drift. The schema is the contract. Declare the fields you depend on as required — their disappearance will throw immediately.

import { drift, stitch } from 'stitchapi';
import { z } from 'zod';

const getUser = stitch({
    baseUrl: 'https://api.example.com',
    path: '/users/{id}',
    output: drift(
        // `id` and `email` are required: if either disappears the call throws.
        z.object({ id: z.number(), email: z.string() }),
    ),
});

const user = await getUser({ params: { id: 1 } });

How it works

Every call validates the response against the schema first. If a required field is missing or has an incompatible value, validation throws STITCH_DRIFT immediately — a drift finding with change: 'invalid' and level: 'error'. No soft-level configuration is needed to make this fatal; making a field required in the schema is sufficient.

On a clean validation, drift diffs the raw body against the validated value and emits any difference as a non-fatal drift event on the event stream:

• undeclared (info by default) — a key the schema stripped; the API added something you do not model.
• coerced (warn by default) — a value the schema coerced, e.g. "42" → 42; a wire-type shift that validation hides.
• defaulted (verbose by default) — a .default() fired because the field was absent.

These non-fatal findings do not throw — they ride the event stream so you can watch a field erode before it becomes a hard failure. Declared variance (an optional field absent, a nullable null, an empty array) validates clean and produces no finding. Drift sits at the opposite end from plain validation, which rejects one malformed response hard, here and now.

The call returns the validated value — defaults applied, unknown keys stripped, types coerced — so the result matches the declared TypeScript type exactly.

See also