Catch a silent selector rename in scraped HTML

Task

You scrape a page that has no API — a catalog provider returns HTML, and you parse it into a structured object with a selector. The danger is silent: the provider renames a CSS class or moves a cell, your selector quietly stops matching, and the field comes back undefined. Nothing throws; downstream code keeps running on corrupted data until someone notices a ranking is wrong. You want that markup rename to surface the moment it happens, as a loud error on the structured shape — not the raw HTML.

Example

The response pipeline is transform → pick → validation, so transform reshapes the HTML into a structured object before drift ever runs — drift then validates the parsed value, not the raw markup. Declare score as required in the schema: its loss is the breakage you want caught.

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

// A trivial hand-rolled scraper: the `score` selector keys off `td.score` —
// exactly the class a markup rename silently breaks.
function scrape(html: unknown): { items: Record<string, unknown>[] } {
    const text = String(html);
    const rows = text.split(/<tr[^>]*class="row1"[^>]*>/i).slice(1);
    const items = rows.map((row) => {
        const item: Record<string, unknown> = {};
        const title = /<td[^>]*class="title"[^>]*>([^<]+)<\/td>/i.exec(row);
        const score = /<td[^>]*class="score"[^>]*>\s*(\d+)\s*<\/td>/i.exec(
            row,
        )?.[1];
        if (title) item['title'] = title[1]!.trim();
        if (score !== undefined) item['score'] = Number(score); // omitted when the selector misses
        return item;
    });
    return { items };
}

const catalog = stitch({
    baseUrl: 'https://api.example.com',
    path: '/catalog',
    transform: scrape, // HTML string -> { items: [...] }
    pick: 'items',
    output: drift(
        // `score` is REQUIRED — its loss is the breakage we want caught.
        // A required field that goes missing throws (`STITCH_DRIFT`, `change: 'invalid'`).
        z.array(z.object({ title: z.string(), score: z.number() })),
    ),
});

const items = await catalog();

How it works

Each call parses the page and validates the transformed shape — [{ title, score }], not the HTML body — against the schema. No baseline to generate or commit: the schema is the contract.

When the provider renames the score cell's class (score → rank), the selector stops matching and scrape drops score from each item. Because the schema requires score, validation sees a missing required field and throws STITCH_DRIFT — a finding with { level: 'error', change: 'invalid', path: '[].score' }. The path is the proof: [].score exists only on the parsed object, so a finding on it can only come from drift inspecting the transform output, not the raw markup. The silent undefined is now a loud, immediate failure.

Other non-fatal soft-drift findings (undeclared, coerced, defaulted) ride the event stream without throwing — you can watch them before any becomes a hard failure.

See also