Leveled drift

Wrap a stitch's output with drift when you want to catch an API quietly changing shape — a field dropped, a type flipped, a new key appearing — and classify each change as error, warn, or info against a committed baseline.

Example

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

const getUser = stitch({
    baseUrl: 'https://api.example.com',
    path: '/users/{id}',
    output: drift(z.object({ id: z.number(), email: z.string() }), {
        critical: ['id'],
        watch: ['email'],
        snapshotFile: 'users.contract.json',
    }),
});

The first call records the baseline; every call after compares the response against users.contract.json and emits any deltas as leveled findings.

Options

critical lists paths whose change is an error; watch lists paths whose change is a warn; everything else that moves is a warn too. onNew sets the level for brand-new fields (default 'info'). snapshotFile names the committed baseline — a <name>.contract.json you check into the repo.

Each finding rides the event stream as a drift event. An error-level finding breaks the contract and surfaces as STITCH_DRIFT; warn and info findings are reported but do not fail the call, so you watch a field erode before it breaks.

This is the opposite end from plain Validation: validation rejects a single malformed response hard, here and now, while drift watches for the silent contract change across calls and lets you triage it by severity.

See Reference → Config types for the full DriftOptions and DriftFinding tables.

See also