Event types

The events a stitch emits as it runs. A stitch streams an async iterable of StitchEvent values; this page documents their shapes.

StitchEventCopy Anchor Link

StitchEvent<T> is a discriminated union on type. The T parameter is the type of the value carried by the result event.

import type { StitchEvent } from 'stitchapi';

The eventsCopy Anchor Link

A union table can render sparsely, so here is each of the eight variants and its fields. Every event carries an at field — a millisecond timestamp.

• start — the request is about to go out. Fields: name (the stitch label), method, url, input (the StitchInput for this call), surface? (the surface id: http, graphql, shell, …), transport? (http when the HTTP adapter carries the request, else the id of the surface that replaces it), template? (the stitch's unexpanded path template, /users/{id}, when one is known), the run identity (spanId?, traceId?, parentSpanId?), at.
• progress — a lifecycle beat within an attempt. Fields: phase (a ProgressPhase), attempt (1-based), detail?, waited? (set when the phase involved a wait, e.g. throttled or retry), status? (the response status behind a retry, an auth refresh or a paginate step), errorType? (the class of the error a retry re-attempts), at. A request step carries spanId?/parentSpanId? — the id the engine minted for that physical request and its parent (the run, or the page) — and a paginate step carries the id of the page it closes. The OTLP sink builds its span tree from them.
• info — an announcement, never carrying a secret. Fields: topic, detail?, at. An auth strategy uses it for a decision it made (topic auth — which env var a bearer token resolved from, or that oauth2 fetched a token). The engine uses it for a teaching note: adapter.upload-progress-unsupported when the transport can't report upload progress, and throttle.per-process — once per throttle — when a rate or concurrency limit can't be fleet-wide because the store lacks the verbs (see the capability table). topic is an open string, so a sink should ignore topics it doesn't know.
• drift — a single contract-drift observation against the response. Fields: finding (a DriftFinding with level, path, change, detail?), at.
• delta — a streamed chunk of the response body. Fields: chunk (unknown), at.
• result — the call succeeded and produced a value. Fields: data (the T), status (HTTP status), attempts (how many it took), at.
• error — the call failed. Fields: name, message, errorType? (the failing error's class — TimeoutError, RateLimitError, TypeError — omitted for a plain Error, such as an HTTP status failure), status?, attempts, at.
• done — the stream is finished, success or failure. Fields: ok, elapsed (total duration), attempts, at.

Span idsCopy Anchor Link

Wherever an event carries spanId, it is the id of the span the event belongs to, and parentSpanId is that span's parent. Which span depends on the event:

Only those carry ids today. The meaning does not change when more events do: a later change that stamps ids on every event (#874) fills in fields that already exist, so a consumer that reads spanId as "the span this event belongs to" keeps working without a rename.

ProgressPhase is one of 'auth', 'request', 'throttled', 'retry', 'paginate', or 'circuit'.

See alsoCopy Anchor Link