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 SeamOptions 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' });

SeamOptions

The eight keys a seam refuses

SeamConfig — the shared fragment inside SeamOptions — 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 'SeamOptions'.
});

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.

secretStore splits the vault off by visibility, not by backend. Auth state lives in the vault, which defaults to a reserved, redacted namespace over store; pass a KMS- or Vault-backed store here to harden it. Either may be distributed.

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