seam()

Every prop seam() accepts, and the two handles it hands back. The option shapes those props take — retry, throttle, cache, and the rest — are documented once in Reference → Config types.

seam()

seam(options?) takes a SeamConfig fragment and returns a Seam: the long-lived entity its members belong to, owning one store, one auth vault, one throttle bucket, and one trace sink. Members come from .stitch() and .graphql(), and inherit the seam's props as the base they extend.

import { seam } from 'stitchapi';
import { bearer, env } from 'stitchapi/auth';

const api = seam({
    baseUrl: 'https://api.example.com',
    auth: bearer(env('API_TOKEN')),
    retry: { attempts: 3, on: [429, 503] },
});

const getUser = api.stitch({ path: '/users/{id}', pick: 'data' });

SeamConfig

The eight keys a seam refuses

SeamConfig is StitchConfig minus the keys that are intrinsically per-endpoint: the address (path, url, method, document) and the request and response shape (name, input, output, kind). A member sets those. Naming one on the seam is a type error rather than a silently-dropped field, so the type answers what belongs at the seam on its own.

import { seam } from 'stitchapi';

const api = seam({
    baseUrl: 'https://api.example.com',
    path: '/users/{id}',
Object literal may only specify known properties, and 'path' does not exist in type 'SeamConfig'.
});

Four props name shared runtime, not a copied value

throttle is one bucket, not one per member. Every member acquires under a single seam-stable key, so the rate and concurrency budget pools across the whole surface; pool: 'host' keeps the engine's per-host key instead. A member's own throttle stacks on top — it gates that one stitch tighter, and never escapes the shared budget.

store is one instance the members share, not a copy each: the same cache entries, throttle counters, and sessions. It defaults to an in-memory store.

trace is one sink for the whole surface. Every member's events land in it, and flush() drains it.

vault splits the secrets off by visibility, not by backend. Auth tokens and sessions live in the vault, which defaults to a reserved, redacted namespace over store; point vault at a KMS-, Vault- or keychain-backed store to harden those alone. Either may be distributed. It is an ordinary StitchConfig prop, so a standalone stitch() takes it too — the seam shares one vault across its members rather than being the only way to have one.

Seam

The root handle: the member builders, the principal boundary, and the lifecycle over the runtime it owns.

PrincipalSeam

seam.as(id) binds a principal in the closure and returns a PrincipalSeam — the same member builders, minus flush, close, and invalidate. Its members carry the principal in their auth context, so each principal gets its own sessions while the throttle bucket stays shared.

import { seam } from 'stitchapi';

const api = seam({ baseUrl: 'https://api.example.com' });

// One handle per request — bind the caller's identity, then create members.
const forTenant = api.as('tenant-42');
const getUser = forTenant.stitch({ path: '/users/{id}', pick: 'data' });

See also