@haddowg/json-api-client 1.0.0

package/dist/index.cjs

@@ -0,0 +1,1254 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/errors.ts
+/**
+* Thrown by the always-on light structural guards (ADR 0004) when a parsed response is not a
+* JSON:API document, or a `data`/`included` member is not a resource object carrying `type`+`id`.
+* Distinct from {@link JsonApiError} (a non-2xx server response): this signals the wire shape the
+* runtime relies on was violated, not an application error the server reported. The opt-in
+* per-field validator throws its engine's own error type, never this one.
+*/
+var StructuralGuardError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "StructuralGuardError";
+	}
+};
+/**
+* Thrown for any non-2xx JSON:API response. Carries the parsed error document plus
+* expressive status matchers and pointer-grouping helpers.
+*/
+var JsonApiError = class extends Error {
+	status;
+	errors;
+	constructor(status, errors, message) {
+		super(message ?? `JSON:API request failed with status ${status}`);
+		this.name = "JsonApiError";
+		this.status = status;
+		this.errors = errors;
+	}
+	hasStatus(status) {
+		return this.status === status;
+	}
+	is4xx() {
+		return this.status >= 400 && this.status < 500;
+	}
+	is5xx() {
+		return this.status >= 500 && this.status < 600;
+	}
+	isBadRequest() {
+		return this.status === 400;
+	}
+	isUnauthorized() {
+		return this.status === 401;
+	}
+	isForbidden() {
+		return this.status === 403;
+	}
+	isNotFound() {
+		return this.status === 404;
+	}
+	isNotAcceptable() {
+		return this.status === 406;
+	}
+	isConflict() {
+		return this.status === 409;
+	}
+	isUnsupportedMediaType() {
+		return this.status === 415;
+	}
+	isUnprocessable() {
+		return this.status === 422;
+	}
+	/** Alias of {@link isUnprocessable} — the JSON:API validation status. */
+	isValidationError() {
+		return this.status === 422;
+	}
+	isRateLimited() {
+		return this.status === 429;
+	}
+	/**
+	* Group errors by user-facing input path (falls back to the raw pointer, then the
+	* query parameter). The payoff for form/validation UX — 422 `source.pointer`s are
+	* remapped to the flat shape the caller actually supplied.
+	*/
+	byPath() {
+		const out = {};
+		for (const e of this.errors) {
+			const key = e.path ?? e.source?.pointer ?? e.source?.parameter ?? "_";
+			(out[key] ??= []).push(e);
+		}
+		return out;
+	}
+};
+//#endregion
+//#region src/validate.ts
+/** Whether a `validate` option is the schema-driven config (vs a bare validator function). */
+function isConfig(option) {
+	return typeof option === "object" && option !== null && !Array.isArray(option);
+}
+/**
+* Normalise the `validate?` option to a single per-resource validator. The config form looks the
+* schema up by `resource.type` and skips a type with no schema (the seam stays graceful for a
+* partially-covered bundle); the bare-function form calls the validator with `schema = undefined`,
+* delegating the whole decision to the caller. Returns `undefined` when validation is off.
+*/
+function resolveValidator(option) {
+	if (option === void 0) return;
+	if (isConfig(option)) {
+		const { schemas, validator } = option;
+		return { validate(resource) {
+			const schema = schemas[resource.type];
+			if (schema !== void 0) validator(resource, schema);
+		} };
+	}
+	return { validate(resource) {
+		option(resource, void 0);
+	} };
+}
+const isObject$3 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/**
+* The light structural guards every parsed response passes through (ADR 0004): assert the body
+* is a JSON:API document and that each `data`/`included` member carries a string `type` (and,
+* for a full resource, an `id`). This is the always-on, engine-free floor — it never duplicates
+* the opt-in per-field validation; it only proves the envelope invariant the runtime relies on.
+*
+* A primary-`data` resource and every `included` resource must carry `type`+`id`. A relationship
+* endpoint's primary data is pure resource-identifier linkage, which also carries `type`+`id`, so
+* the same guard holds; `linkage` is accepted for symmetry with the materialiser but the assertion
+* is identical (an identifier is `type`+`id`). `data: null` (an empty to-one) and a missing
+* `data` (a meta-only document) are valid and pass.
+*/
+function assertJsonApiDocument(body) {
+	if (!isObject$3(body)) throw new StructuralGuardError("Response body is not a JSON:API document (expected an object)");
+	if (!("data" in body) && !("meta" in body)) throw new StructuralGuardError("Response body is not a JSON:API document (missing top-level \"data\" or \"meta\")");
+	const data = body["data"];
+	if (Array.isArray(data)) data.forEach((member, i) => assertResource(member, `data[${i}]`));
+	else if (data !== null && data !== void 0) assertResource(data, "data");
+	const included = body["included"];
+	if (included !== void 0) {
+		if (!Array.isArray(included)) throw new StructuralGuardError("Response \"included\" is not an array");
+		included.forEach((member, i) => assertResource(member, `included[${i}]`));
+	}
+}
+/** Assert a single member is a resource object/identifier carrying string `type` + `id`. */
+function assertResource(member, at) {
+	if (!isObject$3(member)) throw new StructuralGuardError(`${at} is not a JSON:API resource object`);
+	if (typeof member["type"] !== "string") throw new StructuralGuardError(`${at} is missing a string "type"`);
+	if (typeof member["id"] !== "string") throw new StructuralGuardError(`${at} (type "${member["type"]}") is missing a string "id"`);
+}
+/**
+* Run the opt-in validator over every wire resource in a document's `data` + `included`, each
+* against its per-type schema. Called only when a validator is configured (off by default). The
+* structural guards have already proven each member carries `type`+`id`, so the cast is sound.
+*/
+function validateDocument(body, validator) {
+	const data = body.data;
+	if (Array.isArray(data)) for (const member of data) validateResourceMember(member, validator);
+	else if (data !== null && data !== void 0) validateResourceMember(data, validator);
+	if (body.included !== void 0) for (const member of body.included) validator.validate(member);
+}
+/**
+* Validate a `data` member, but only when it is a full RESOURCE OBJECT. A relationship-linkage
+* endpoint's `data` is bare resource IDENTIFIERS (`type`+`id`[+`meta`], no `attributes`/
+* `relationships`); the per-type schema describes the resource object, so running it over an
+* identifier would spuriously fail. The structural guard already covered the identifier shape.
+*/
+function validateResourceMember(member, validator) {
+	if (isObject$3(member) && ("attributes" in member || "relationships" in member)) validator.validate(member);
+}
+//#endregion
+//#region src/materialise.ts
+const isObject$2 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const define = (target, key, value) => {
+	Object.defineProperty(target, key, {
+		value,
+		enumerable: false,
+		configurable: true
+	});
+};
+const defineGetter = (target, key, get) => {
+	Object.defineProperty(target, key, {
+		get,
+		enumerable: false,
+		configurable: true
+	});
+};
+/**
+* Materialise a JSON:API document into a hydrated graph (ADR 0002 / CONTEXT.md):
+*
+* - single resource -> a flattened resource object (own enumerable type/id/attributes/
+*   relations + non-enumerable `$`-accessors);
+* - collection / related collection -> an augmented array of resource objects;
+* - relationship linkage -> an augmented array of identifier views (to-many) or a single
+*   identifier / null (to-one).
+*
+* Included resources hydrate into nested per-edge views (reads through to the shared
+* node for attributes, owns its own `$edge`/`$pivot`); linked-but-not-included relations
+* stay as identifiers; links-only relations are `undefined`. The envelope rides
+* non-enumerable `$`-accessors so `{...res}` / `JSON.stringify(res)` are clean.
+*
+* `linkage` discriminates a relationship-endpoint response (primary `data` is pure
+* resource-identifier linkage) from a resource/collection response (primary `data` is a
+* full resource) — a structural guess can't tell them apart for an attribute-less,
+* relation-less resource, so the caller passes the surface it issued.
+*
+* `paginatorOverride` sets the top-level array's `$page.kind` for a related/relationship read,
+* where the paginator is the RELATION's (which may diverge from the related type's collection —
+* D6a) and an empty page carries no member to sniff a type from. `primaryType` is preferred for a
+* top-level collection read (statically-known); both override the sniff-from-`data[0]` fallback.
+*/
+function materialise(doc, ctx, linkage = false, primaryType, paginatorOverride) {
+	assertJsonApiDocument(doc);
+	if (ctx.validate !== void 0) validateDocument(doc, ctx.validate);
+	const env = {};
+	if (doc.jsonapi !== void 0) env.jsonapi = doc.jsonapi;
+	if (doc.meta !== void 0) env.meta = doc.meta;
+	if (doc.links !== void 0) env.links = doc.links;
+	const index = buildIndex(doc.included);
+	const nodes = /* @__PURE__ */ new Map();
+	const build = (raw) => buildNode(raw, env, index, nodes, ctx);
+	const data = doc.data;
+	if (data === null) return null;
+	if (Array.isArray(data)) {
+		const raws = data;
+		return augmentArray(linkage ? raws.map((raw) => buildIdentifierView(raw)) : raws.map((raw) => buildEdgeView(build(raw), raw)), doc, ctx, linkage, primaryType, paginatorOverride);
+	}
+	if (isObject$2(data)) {
+		const raw = data;
+		if (linkage) return buildIdentifierView(raw);
+		return build(raw);
+	}
+}
+/** Index `included` by `type:id` so relationship linkage can be hydrated. */
+function buildIndex(included) {
+	const index = /* @__PURE__ */ new Map();
+	if (!included) return index;
+	for (const raw of included) if (isObject$2(raw) && typeof raw["type"] === "string" && typeof raw["id"] === "string") index.set(key(raw["type"], raw["id"]), raw);
+	return index;
+}
+const key = (type, id) => `${type}:${id}`;
+/**
+* Build (or reuse) the shared NODE for a resource: flattened type/id/attributes + hydrated
+* relations as own enumerable props, plus the resource-level `$`-accessors. The node is
+* memoised by `type:id` so attribute reads share one object; per-edge data never lands here.
+*/
+function buildNode(raw, env, index, nodes, ctx) {
+	const id = key(raw.type, raw.id);
+	const existing = nodes.get(id);
+	if (existing) return existing;
+	const node = {
+		type: raw.type,
+		id: raw.id
+	};
+	nodes.set(id, node);
+	if (raw.attributes) for (const [k, v] of Object.entries(raw.attributes)) node[k] = v;
+	const rels = raw.relationships ?? {};
+	const resType = ctx.descriptor[raw.type];
+	for (const [name, rel] of Object.entries(rels)) {
+		if (!("data" in rel)) continue;
+		const relDesc = resType?.relations[name];
+		node[name] = hydrateRelation(rel, relDesc?.cardinality, relatedPaginatorKind(relDesc, ctx), env, index, nodes, ctx);
+	}
+	attachResourceEnvelope(node, raw, env, rels);
+	return node;
+}
+/**
+* Resolve one relationship's value: an included member hydrates to a per-edge view, a
+* linked-but-not-included member stays an identifier, an empty to-one is `null`, and a
+* to-many is always an augmented array (of views and/or identifiers).
+*
+* `relatedKind` is the related type's paginator kind (from the descriptor), threaded so a
+* to-many array reports the same `$page.kind` it would on its dedicated endpoint.
+*/
+function hydrateRelation(rel, cardinality, relatedKind, env, index, nodes, ctx) {
+	const data = rel.data;
+	if (Array.isArray(data)) return augmentRelationArray(data.map((member) => resolveMember(member, env, index, nodes, ctx)), rel, relatedKind, ctx);
+	if (data === void 0 && cardinality === "many") return augmentRelationArray([], rel, relatedKind, ctx);
+	if (data === null || data === void 0) return data === null ? null : void 0;
+	if (isObject$2(data)) return resolveMember(data, env, index, nodes, ctx, {
+		links: rel.links,
+		meta: rel.meta
+	});
+}
+/** A single linkage member -> a hydrated per-edge view if included, else an identifier view. */
+function resolveMember(member, env, index, nodes, ctx, relationEdge) {
+	const included = index.get(key(member.type, member.id));
+	if (included) return buildEdgeView(buildNode(included, env, index, nodes, ctx), member, relationEdge);
+	return buildIdentifierView(member, relationEdge);
+}
+/** Attach the resource-level `$`-accessors ($meta/$links/$self/$document/$raw/$rel). */
+function attachResourceEnvelope(node, raw, env, rels) {
+	defineGetter(node, "$meta", () => raw.meta);
+	defineGetter(node, "$links", () => raw.links);
+	defineGetter(node, "$self", () => raw.links?.self);
+	defineGetter(node, "$document", () => env);
+	defineGetter(node, "$raw", () => raw);
+	define(node, "$rel", (name) => {
+		const rel = rels[name];
+		if (!rel) return void 0;
+		const view = {};
+		if ("data" in rel) view.data = rel.data;
+		if (rel.links !== void 0) view.links = rel.links;
+		if (rel.meta !== void 0) view.meta = rel.meta;
+		return view;
+	});
+}
+/**
+* A per-edge VIEW over a node: a distinct wrapper per membership that reads through to the
+* shared node for attributes (and the resource-level `$`-accessors) but owns its own
+* edge-local `$edge`/`$pivot`. Identity is by `type:id`, never reference.
+*
+* `relationEdge` (set for a to-one) carries the relationship object's self/related links and
+* meta, which ride the value's `$edge` per CONTEXT.md.
+*/
+function buildEdgeView(node, member, relationEdge) {
+	const view = {};
+	Object.assign(view, node);
+	for (const k of [
+		"$meta",
+		"$links",
+		"$self",
+		"$document",
+		"$raw",
+		"$rel"
+	]) delegate(view, node, k);
+	attachEdgeEnvelope(view, member, false, relationEdge);
+	return view;
+}
+/** An identifier VIEW for a linked-but-not-included member: a clean `{type,id,meta?}` + edge. */
+function buildIdentifierView(member, relationEdge) {
+	const view = {
+		type: member.type,
+		id: member.id
+	};
+	if (member.meta !== void 0) view.meta = member.meta;
+	attachEdgeEnvelope(view, member, true, relationEdge);
+	return view;
+}
+/**
+* Attach `$edge` (the member's identifier-level edge meta/links) and `$pivot` sugar over it.
+* For a to-one, the relationship object's self/related links + meta (`relationEdge`) merge in,
+* with member-level meta winning on key collision.
+*/
+function attachEdgeEnvelope(view, member, includeLinks, relationEdge) {
+	defineGetter(view, "$edge", () => {
+		const links = (includeLinks ? member.links : void 0) ?? relationEdge?.links;
+		const meta = mergeMeta(relationEdge?.meta, member.meta);
+		if (links === void 0 && meta === void 0) return void 0;
+		const edge = {};
+		if (links !== void 0) edge.links = links;
+		if (meta !== void 0) edge.meta = meta;
+		return edge;
+	});
+	defineGetter(view, "$pivot", () => {
+		const pivot = member.meta?.["pivot"];
+		return isObject$2(pivot) ? pivot : void 0;
+	});
+}
+/** Merge a relationship-object meta with member-level meta (member wins on key collision). */
+function mergeMeta(base, override) {
+	if (base === void 0) return override;
+	if (override === void 0) return base;
+	return {
+		...base,
+		...override
+	};
+}
+/** Mirror a non-enumerable accessor from `source` onto `target`, reading through live. */
+function delegate(target, source, k) {
+	const value = source[k];
+	if (typeof value === "function") define(target, k, value.bind(source));
+	else defineGetter(target, k, () => source[k]);
+}
+/**
+* A top-level / related collection array: `$page` from `doc`, links/meta from the document.
+* `linkage` propagates to `$next()`/`$prev()` so a relationship-endpoint page re-materialises
+* as identifiers, not resources.
+*/
+function augmentArray(members, doc, ctx, linkage, primaryType, paginatorOverride) {
+	const arr = [...members];
+	const links = doc.links;
+	defineGetter(arr, "$links", () => links);
+	defineGetter(arr, "$meta", () => doc.meta);
+	attachPage(arr, paginatorOverride ?? paginatorKind(doc, ctx, primaryType), pageMeta(doc.meta), links, ctx, linkage);
+	return arr;
+}
+/**
+* A to-many relationship array: `$page`/links/meta come from the relationship object. `kind`
+* is the related type's paginator (so an in-document compound-include to-many reports the same
+* discriminant it would when fetched at its own relationship/related endpoint — "one model,
+* three surfaces").
+*/
+function augmentRelationArray(members, rel, kind, ctx) {
+	const arr = [...members];
+	const links = rel.links;
+	defineGetter(arr, "$links", () => links);
+	defineGetter(arr, "$meta", () => rel.meta);
+	attachPage(arr, kind, pageMeta(rel.meta), links, ctx, false);
+	return arr;
+}
+/** Attach `$page` + `$next()`/`$prev()` driven by link presence (count-free-safe). */
+function attachPage(arr, kind, meta, links, ctx, linkage) {
+	const page = {
+		kind,
+		links: pageLinks(links)
+	};
+	if (meta !== void 0) page.meta = meta;
+	defineGetter(arr, "$page", () => page);
+	define(arr, "$next", () => navigateLink(page.links.next, ctx, linkage, kind));
+	define(arr, "$prev", () => navigateLink(page.links.prev, ctx, linkage, kind));
+}
+const navigateLink = (link, ctx, linkage, paginator) => link === void 0 ? Promise.resolve(void 0) : ctx.navigate(link, linkage, paginator);
+/** Extract the navigation links (a link may be a string or a `{href}` object). */
+function pageLinks(links) {
+	const out = {};
+	if (!links) return out;
+	for (const k of [
+		"first",
+		"prev",
+		"next",
+		"last"
+	]) {
+		const href = linkHref(links[k]);
+		if (href !== void 0) out[k] = href;
+	}
+	return out;
+}
+const linkHref = (link) => {
+	if (typeof link === "string") return link;
+	if (isObject$2(link) && typeof link["href"] === "string") return link["href"];
+};
+const pageMeta = (meta) => isObject$2(meta?.["page"]) ? meta["page"] : void 0;
+/**
+* The document's paginator kind (from the primary type's descriptor; default `none`). Prefers the
+* statically-known `primaryType` (passed by the descriptor binding at the call site) so an EMPTY
+* page still reports the collection's real kind; falls back to sniffing the first member's type
+* (for a re-materialised `$next()` page or a related read, where the primary type isn't threaded).
+*/
+function paginatorKind(doc, ctx, primaryType) {
+	const first = Array.isArray(doc.data) ? doc.data[0] : doc.data;
+	const type = primaryType ?? (isObject$2(first) && typeof first["type"] === "string" ? first["type"] : void 0);
+	return type !== void 0 ? ctx.descriptor[type]?.paginator ?? "none" : "none";
+}
+/**
+* A to-many relation's paginator kind. The relation's OWN related/relationship endpoint may
+* paginate differently than the related type's top-level collection (D6a), so prefer the
+* per-relation `paginator` (carried in the descriptor only when it diverges); otherwise fall back
+* to the related type's own paginator (the relationship and related endpoints both paginate that
+* type), so the discriminant is identical across the three surfaces. A polymorphic relation
+* resolves off its first declared related type (its members span types, matching the relationship
+* endpoint's first-member resolution).
+*/
+function relatedPaginatorKind(relation, ctx) {
+	if (relation?.paginator !== void 0) return relation.paginator;
+	const relatedType = relation?.types[0];
+	if (relatedType === void 0) return "none";
+	return ctx.descriptor[relatedType]?.paginator ?? "none";
+}
+//#endregion
+//#region src/types.ts
+/** The JSON:API media type. */
+const JSON_API_MEDIA_TYPE = "application/vnd.api+json";
+/** The Atomic Operations extension URI. */
+const ATOMIC_EXT = "https://jsonapi.org/ext/atomic";
+/**
+* Compose the JSON:API media type with any opted-in `ext`/`profile` parameters. Each parameter
+* is a space-joined, double-quoted URI list, in the canonical order `ext` then `profile` so the
+* output is deterministic (stable for caching/assertions). Empty/absent lists are omitted; with
+* neither, the bare {@link JSON_API_MEDIA_TYPE} is returned (no behaviour change for a plain
+* request). Used for both `Accept` and (when a body is present) `Content-Type`.
+*/
+function mediaType(params = {}) {
+	let out = JSON_API_MEDIA_TYPE;
+	if (params.ext !== void 0 && params.ext.length > 0) out += `; ext="${params.ext.join(" ")}"`;
+	if (params.profiles !== void 0 && params.profiles.length > 0) out += `; profile="${params.profiles.join(" ")}"`;
+	return out;
+}
+/**
+* The media type for an Atomic Operations request/response: the JSON:API media type carrying
+* the atomic `ext` parameter. Sent as both `Content-Type` and `Accept` on a `client.atomic`
+* batch (per the JSON:API atomic extension).
+*/
+const ATOMIC_MEDIA_TYPE = mediaType({ ext: [ATOMIC_EXT] });
+//#endregion
+//#region src/request.ts
+const isAbsolute = (path) => /^https?:\/\//i.test(path);
+const append = (parts, key, value) => {
+	if (value === void 0 || value === null || value === "") return;
+	parts.push(`${key}=${encodeURIComponent(String(value))}`);
+};
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+* Append a filter value under its (already-bracketed) key. A plain object is a STRUCTURED filter
+* value — a `Range`/`DateRange` deepObject (`{ min, max }`) — and recurses into nested bracketed
+* keys (`filter[k][min]=`), matching the server's deepObject wire shape; an array joins with `,`;
+* a scalar is appended directly. Without the object branch a `{ min, max }` value would reach the
+* wire as `filter[k]=[object Object]` and be silently ignored by the server (D23).
+*/
+const appendFilterValue = (parts, key, value) => {
+	if (isPlainObject(value)) {
+		for (const [subKey, subValue] of Object.entries(value)) appendFilterValue(parts, `${key}[${subKey}]`, subValue);
+		return;
+	}
+	append(parts, key, Array.isArray(value) ? value.join(",") : value);
+};
+/**
+* Serialise a read query to a query string (no leading `?`). Bracketed keys
+* (`filter[title]`, `page[number]`, `fields[albums]`) are kept literal; only values
+* are percent-encoded. Empty/undefined entries are skipped; key order is deterministic
+* (family order, then insertion order within a family) so URLs are stable for caching.
+*/
+function serializeQuery(query) {
+	const parts = [];
+	if (query.filter) for (const [key, value] of Object.entries(query.filter)) appendFilterValue(parts, `filter[${key}]`, value);
+	if (query.sort !== void 0) append(parts, "sort", Array.isArray(query.sort) ? query.sort.join(",") : query.sort);
+	if (query.include) append(parts, "include", query.include.join(","));
+	if (query.fields) for (const [type, names] of Object.entries(query.fields)) parts.push(`fields[${type}]=${encodeURIComponent(names.join(","))}`);
+	if (query.withCount && query.withCount.length > 0) append(parts, "withCount", query.withCount.join(","));
+	if (query.page) for (const [key, value] of Object.entries(query.page)) append(parts, `page[${key}]`, Array.isArray(value) ? value.join(",") : value);
+	return parts.join("&");
+}
+/**
+* Execute a request: build the URL (verbatim when already absolute — for page links —
+* else `baseUrl + path`), apply content negotiation and any async per-request headers,
+* then drive the transport. A 2xx with a body parses to a {@link Document}; an empty /
+* 204 body resolves to `undefined`. A non-2xx throws a {@link JsonApiError} carrying the
+* parsed error objects (tolerating a non-JSON error body with an empty list).
+*/
+async function execute(ctx, req) {
+	let url = isAbsolute(req.path) ? req.path : ctx.baseUrl + req.path;
+	if (req.query) {
+		const qs = serializeQuery(req.query);
+		if (qs) url += (url.includes("?") ? "&" : "?") + qs;
+	}
+	const negotiated = mediaType({
+		ext: req.ext,
+		profiles: req.profiles
+	});
+	const headers = { Accept: req.accept ?? negotiated };
+	const transportReq = {
+		method: req.method,
+		url,
+		headers
+	};
+	if (req.body !== void 0) {
+		headers["Content-Type"] = req.contentType ?? negotiated;
+		transportReq.body = req.raw && typeof req.body === "string" ? req.body : JSON.stringify(req.body);
+	}
+	if (ctx.headers) mergeHeaders(headers, await ctx.headers());
+	const res = await ctx.transport(transportReq);
+	if (res.status >= 200 && res.status < 300) return parseDocument(res.body);
+	throw new JsonApiError(res.status, parseErrors(res.body));
+}
+/**
+* Merge a `HeadersInit` (object / tuple array / `Headers`) into the outgoing map,
+* preserving the caller's casing (unlike the WHATWG `Headers`, which lowercases). The
+* caller's headers override the runtime defaults, so per-request `Accept` etc. can win.
+*/
+function mergeHeaders(into, extra) {
+	if (extra instanceof Headers) extra.forEach((value, key) => {
+		into[key] = value;
+	});
+	else if (Array.isArray(extra)) {
+		for (const [key, value] of extra) if (key !== void 0 && value !== void 0) into[key] = String(value);
+	} else for (const [key, value] of Object.entries(extra)) into[key] = String(value);
+}
+function parseDocument(body) {
+	if (body === "") return;
+	return JSON.parse(body);
+}
+function parseErrors(body) {
+	if (body === "") return [];
+	try {
+		const doc = JSON.parse(body);
+		return Array.isArray(doc.errors) ? doc.errors : [];
+	} catch {
+		return [];
+	}
+}
+//#endregion
+//#region src/serialize-write.ts
+/** Per-edge writable pivot data, supplied on a to-many member as the `$pivot` key. */
+const PIVOT_KEY = "$pivot";
+/** The reserved input keys never routed to attributes/relationships. */
+const RESERVED_INPUT = /* @__PURE__ */ new Set(["type", "id"]);
+const isObject$1 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/**
+* Build a JSON:API write document from FLAT input. Each input key is routed via the
+* descriptor: a declared relation -> `data.relationships[name] = { data: <linkage> }`;
+* anything else -> `data.attributes[name]`. Relationship linkage is coerced by cardinality:
+*
+* - to-one accepts an identifier `{type,id}`, a materialised resource object (its `{type,id}`
+*   are extracted), or `null` (-> `data: null`, clearing the relationship);
+* - to-many accepts an array of those; a member may carry a `$pivot` object, rendered as the
+*   member identifier's `meta.pivot` (writable pivot fields).
+*
+* `data.type` is always the accessor `type`. `data.id` is written from `opts.id` (an update),
+* else from `input.id` only when the type's `clientId` policy allows it (omitted when
+* `forbidden`, passed through when `optional`/`required`).
+*/
+function toDocument(descriptor, type, input, opts) {
+	const resource = descriptor[type];
+	const relations = resource?.relations ?? {};
+	const data = { type };
+	const id = resolveId(input, opts, resource?.clientId);
+	if (id !== void 0) data.id = id;
+	const attributes = {};
+	const relationships = {};
+	for (const [keyName, value] of Object.entries(input)) {
+		if (RESERVED_INPUT.has(keyName)) continue;
+		const relation = relations[keyName];
+		if (relation !== void 0) relationships[keyName] = { data: coerceLinkage(value, relation.cardinality) };
+		else attributes[keyName] = value;
+	}
+	if (Object.keys(attributes).length > 0) data.attributes = attributes;
+	if (Object.keys(relationships).length > 0) data.relationships = relationships;
+	return { data };
+}
+/**
+* Build a relationship-mutation document `{ data: <linkage> }` for the
+* `/{type}/{id}/relationships/{rel}` endpoints, coercing the caller's refs by cardinality:
+*
+* - to-one accepts an identifier `{type,id}`, a materialised resource object, or `null`
+*   (-> `data: null`, clearing the relationship);
+* - to-many accepts an array of those; a member may carry `$pivot`, rendered as the member
+*   identifier's `meta.pivot`.
+*
+* The same {@link coerceLinkage} the whole-resource writer uses, so a relationship written
+* standalone and one embedded in a resource serialise identically.
+*/
+function toRelationshipDocument(refs, cardinality) {
+	return { data: coerceLinkage(refs, cardinality) };
+}
+/** Resolve the document id: an update's handle id always wins; a create honours the policy. */
+function resolveId(input, opts, clientId) {
+	if (opts?.id !== void 0) return opts.id;
+	if (clientId === "forbidden") return;
+	const candidate = input["id"];
+	return typeof candidate === "string" ? candidate : void 0;
+}
+/** Coerce one relationship value to linkage by cardinality (array for to-many, identifier/null for to-one). */
+function coerceLinkage(value, cardinality) {
+	if (cardinality === "many") return (Array.isArray(value) ? value : value == null ? [] : [value]).map((member) => toIdentifier(member));
+	if (value === null || value === void 0) return null;
+	return toIdentifier(value);
+}
+/**
+* Extract a resource identifier from a linkage input value: an identifier `{type,id}`, a
+* materialised resource object (the same `{type,id}` enumerable props), or — inside an atomic
+* batch — a local identifier `{type,lid}` referencing a just-created resource (the handle a
+* `tx.create` returns). A `$pivot` key is lifted onto `meta.pivot` (writable pivot fields).
+* Throws on a value carrying no `type`, or neither an `id` nor a `lid`.
+*/
+function toIdentifier(value) {
+	if (!isObject$1(value)) throw new TypeError(`Relationship linkage must be an identifier or resource object; received ${describe(value)}`);
+	const { type, id, lid } = value;
+	if (typeof type !== "string") throw new TypeError("Relationship linkage requires a `type`");
+	const identifier = typeof id === "string" ? {
+		type,
+		id
+	} : typeof lid === "string" ? {
+		type,
+		lid
+	} : (() => {
+		throw new TypeError("Relationship linkage requires an `id` or a `lid`");
+	})();
+	const pivot = value[PIVOT_KEY];
+	if (isObject$1(pivot)) identifier.meta = { pivot };
+	return identifier;
+}
+const describe = (value) => value === null ? "null" : Array.isArray(value) ? "an array" : typeof value;
+/**
+* Invert a write error's `source.pointer` to the caller's FLAT input path, descriptor-aware:
+*
+* - `/data/attributes/title`                                 -> `title`
+* - `/data/relationships/artist/data`                        -> `artist`
+* - `/data/id`                                               -> `id` (client-id create conflict)
+* - `/data/attributes/releaseInfo/label`                     -> `releaseInfo.label` (nested map)
+* - `/data/relationships/orderedTracks/data/0/meta/pivot/position` -> `orderedTracks[0].$pivot.position`
+*
+* Pivot values nest under a member's `meta.pivot` (symmetric with reads — see
+* `JsonPointerBuilder::forLinkageMeta` / bundle ADR 0103), so a `meta/pivot/<field>` tail on
+* a member of a pivot-bearing to-many is surfaced as `.$pivot.<field>`.
+*
+* A query-side pointer is left untouched (those are already user-facing — see
+* {@link withRemappedPaths}). An unrecognised / non-write pointer is returned verbatim.
+* `/data/type` and a bare `/data` are passed through (the client owns those; the caller
+* never supplies them).
+*/
+function remapPointer(descriptor, type, pointer) {
+	const segments = pointer.split("/").filter((s) => s !== "");
+	if (segments[0] !== "data") return pointer;
+	if (segments[1] === "attributes") return remapAttribute(segments.slice(2));
+	if (segments[1] === "id") return "id";
+	if (segments[1] === "relationships") return remapRelationship(descriptor[type]?.relations ?? {}, segments.slice(2));
+	return pointer;
+}
+/** `[releaseInfo, label]` -> `releaseInfo.label`; a bare `[title]` -> `title`. */
+function remapAttribute(rest) {
+	return rest.join(".");
+}
+/**
+* Remap a relationship pointer's tail (everything after `relationships/`, or — for a
+* relationship-endpoint document — the relation name spliced ahead of the `data` tail). The
+* leading segment is the relation name; a `data` segment is dropped; a numeric index becomes
+* `[n]`; a `meta/pivot/<field>` tail on a pivot-bearing relation becomes `.$pivot.<field>`. The
+* `relations` map tells us whether the relation carries pivot (so a member's `meta.pivot`
+* fields are the pivot data the bundle validates).
+*/
+function remapRelationship(relations, rest) {
+	const name = rest[0];
+	if (name === void 0) return "data/relationships";
+	const hasPivot = relations[name]?.pivot === true;
+	let path = name;
+	for (let i = 1; i < rest.length; i++) {
+		const seg = rest[i];
+		if (seg === "data") continue;
+		if (/^\d+$/.test(seg)) path += `[${seg}]`;
+		else if (seg === "meta" && hasPivot && rest[i + 1] === "pivot") {
+			path += ".$pivot";
+			i++;
+		} else path += `.${seg}`;
+	}
+	return path;
+}
+/**
+* Invert a relationship-MUTATION error's `source.pointer` to the caller's flat path, for the
+* `/{type}/{id}/relationships/{rel}` endpoints. Two pointer shapes reach here:
+*
+* - the LINKAGE document shape (validation on the linkage members), rooted at `data` — the
+*   relation name is supplied by the route, not the wire:
+*   - `/data`                             -> `<rel>`                  (to-one clear/set)
+*   - `/data/meta/pivot/position`         -> `<rel>.$pivot.position`  (to-one pivot, rare)
+*   - `/data/0/meta/pivot/position`       -> `<rel>[0].$pivot.position`
+* - the RESOURCE-document shape that core's relationship prohibitions emit unchanged
+*   (`FullReplacementProhibited`/`RemovalProhibited`/`AdditionProhibited`/
+*   `RelationshipTypeInappropriate` all point at `/data/relationships/<name>`) — short-circuited
+*   to the relation name (drop the `relationships/<name>` prefix) rather than treating
+*   `relationships` as a linkage sub-segment.
+*
+* A non-`data` pointer is returned verbatim.
+*/
+function remapRelationshipPointer(rel, hasPivot, pointer) {
+	const segments = pointer.split("/").filter((s) => s !== "");
+	if (segments[0] !== "data") return pointer;
+	const tail = segments[1] === "relationships" ? segments.slice(3) : segments.slice(1);
+	return remapRelationship({ [rel]: { pivot: hasPivot } }, [rel, ...tail]);
+}
+/**
+* Return a {@link JsonApiError} with each error object's `path` populated by remapping its
+* `source.pointer` (descriptor-aware) — so {@link JsonApiError.byPath} groups by the flat input
+* shape. Errors with no write pointer (e.g. a `source.parameter` query-side error, or no
+* source) are passed through unchanged. The original error is not mutated.
+*/
+function withRemappedPaths(error, descriptor, type) {
+	return mapErrors(error, (pointer) => ({ path: remapPointer(descriptor, type, pointer) }));
+}
+/**
+* The relationship-mutation twin of {@link withRemappedPaths}: remap each error's pointer
+* keyed by the relation name from the route. Handles both the linkage-document shape (rooted
+* at `data`) and the resource-document shape core's prohibition exceptions emit
+* (`/data/relationships/<rel>`). `hasPivot` lets a member-level `meta` field surface as
+* `$pivot`. The original error is not mutated.
+*/
+function withRemappedRelationshipPaths(error, rel, hasPivot) {
+	return mapErrors(error, (pointer) => ({ path: remapRelationshipPointer(rel, hasPivot, pointer) }));
+}
+/**
+* Invert an atomic-batch error's `source.pointer` to `(opIndex, flatPath)`: an atomic 422
+* points at `/atomic:operations/{n}/data/...`, so strip the `atomic:operations/{n}` prefix to
+* the op index, resolve that op's wire type (`typeForOp`), and delegate the remaining `/data`
+* tail to the same {@link remapPointer} a standalone write uses (so the flat path is identical
+* — `title`, `releaseInfo.label`, `artist`, …). A pointer without the atomic prefix is remapped
+* verbatim under the (whole-batch) document at op index `undefined`. The original error is not
+* mutated.
+*/
+function withRemappedAtomicPaths(error, descriptor, typeForOp) {
+	return mapErrors(error, (pointer) => {
+		const segments = pointer.split("/").filter((s) => s !== "");
+		if (segments[0] !== "atomic:operations" || segments[1] === void 0) return { path: pointer };
+		const opIndex = Number(segments[1]);
+		if (!Number.isInteger(opIndex)) return { path: pointer };
+		const type = typeForOp(opIndex);
+		const tail = `/${segments.slice(2).join("/")}`;
+		return {
+			opIndex,
+			path: type === void 0 ? tail : remapPointer(descriptor, type, tail)
+		};
+	});
+}
+/** Shared error-mapper: clone each error with `path`/`opIndex` from its `source.pointer`, else pass through. */
+function mapErrors(error, remap) {
+	const remapped = error.errors.map((e) => {
+		const pointer = e.source?.pointer;
+		if (pointer === void 0) return e;
+		const { path, opIndex } = remap(pointer);
+		return opIndex === void 0 ? {
+			...e,
+			path
+		} : {
+			...e,
+			path,
+			opIndex
+		};
+	});
+	return new JsonApiError(error.status, remapped, error.message);
+}
+//#endregion
+//#region src/atomic.ts
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** The deterministic local id for the create at `opIndex` (stable + human-readable). */
+const lidFor = (opIndex) => `atomic-${opIndex}`;
+async function runAtomic(request, materialiseCtx, descriptor, path, build) {
+	const operations = [];
+	/** The wire type of each op, by index — drives the error-pointer remap. */
+	const typeByOp = [];
+	const returned = build({
+		create(input) {
+			const opIndex = operations.length;
+			const lid = lidFor(opIndex);
+			const data = atomicResourceData(descriptor, input, { lid });
+			operations.push({
+				op: "add",
+				data
+			});
+			typeByOp.push(input.type);
+			return {
+				type: input.type,
+				lid,
+				kind: "create",
+				opIndex
+			};
+		},
+		update(input) {
+			const opIndex = operations.length;
+			const identity = input.id !== void 0 ? { id: input.id } : { lid: input.lid };
+			const data = atomicResourceData(descriptor, input, identity);
+			operations.push({
+				op: "update",
+				ref: {
+					type: input.type,
+					...identity
+				},
+				data
+			});
+			typeByOp.push(input.type);
+			return {
+				type: input.type,
+				kind: "update",
+				opIndex
+			};
+		},
+		delete(ref) {
+			const opIndex = operations.length;
+			const { type, identity } = toRef(ref);
+			operations.push({
+				op: "remove",
+				ref: {
+					type,
+					...identity
+				}
+			});
+			typeByOp.push(type);
+			return {
+				kind: "delete",
+				opIndex
+			};
+		}
+	});
+	const req = {
+		method: "POST",
+		path,
+		body: { "atomic:operations": operations },
+		ext: [ATOMIC_EXT]
+	};
+	let doc;
+	try {
+		doc = await execute(request, req);
+	} catch (error) {
+		if (error instanceof JsonApiError) throw withRemappedAtomicPaths(error, descriptor, (opIndex) => typeByOp[opIndex]);
+		throw error;
+	}
+	const results = parseResults(doc, materialiseCtx);
+	if (!(Array.isArray(returned) && returned.every((h) => h !== null && typeof h === "object" && "opIndex" in h))) return results;
+	return returned.map((handle) => handle.kind === "delete" ? void 0 : results[handle.opIndex]);
+}
+/**
+* Build the resource `data` for an `add`/`update` op from flat input via {@link toDocument}
+* (so attributes/relationships route identically to a standalone write), then carry the op's
+* identity onto the resource: a server `id` (a create's server-assigned id is omitted; an
+* update by id keeps it) or a same-batch `lid` (a create's generated lid, or an update/remove
+* targeting an earlier op's resource).
+*/
+function atomicResourceData(descriptor, input, identity) {
+	const { id: _id, lid: _lid, ...fields } = input;
+	const { data } = toDocument(descriptor, input.type, fields, "id" in identity ? { id: identity.id } : void 0);
+	const out = { ...data };
+	if ("lid" in identity) {
+		delete out["id"];
+		out["lid"] = identity.lid;
+	}
+	return out;
+}
+/**
+* Coerce a remove ref (an identifier, a materialised resource, or a same-batch `{type,lid}`
+* handle) to `{ type, identity }` — `identity` an `id` or a `lid`; throws if neither is present.
+*/
+function toRef(ref) {
+	if (!isObject(ref)) throw new TypeError("atomic delete requires an identifier `{ type, id }` or `{ type, lid }`");
+	const { type, id, lid } = ref;
+	if (typeof type !== "string") throw new TypeError("atomic delete requires a `type`");
+	if (typeof id === "string") return {
+		type,
+		identity: { id }
+	};
+	if (typeof lid === "string") return {
+		type,
+		identity: { lid }
+	};
+	throw new TypeError("atomic delete requires an `id` or a `lid`");
+}
+/** Parse `{ "atomic:results": [...] }` positionally, materialising each result's `data`. An absent results array (an all-`204` batch) yields `[]`. */
+function parseResults(doc, ctx) {
+	const results = doc?.["atomic:results"];
+	if (!Array.isArray(results)) return [];
+	return results.map((result) => {
+		const entry = isObject(result) ? result : {};
+		const out = { data: entry["data"] === void 0 ? void 0 : materialise({ data: entry["data"] }, ctx) };
+		if (isObject(entry["meta"])) out.meta = entry["meta"];
+		return out;
+	});
+}
+//#endregion
+//#region src/transport.ts
+/** The default transport, backed by the global `fetch`. */
+const fetchTransport = async (req) => {
+	const init = {
+		method: req.method,
+		headers: req.headers
+	};
+	if (req.body !== void 0) init.body = req.body;
+	const res = await fetch(req.url, init);
+	const headers = {};
+	res.headers.forEach((value, key) => {
+		headers[key] = value;
+	});
+	return {
+		status: res.status,
+		headers,
+		body: await res.text()
+	};
+};
+//#endregion
+//#region src/client.ts
+/** Substitute `{key}` placeholders in a path template (`/albums/{id}/{rel}` -> `/albums/1/tracks`). */
+const fill = (template, vars) => template.replace(/\{(\w+)\}/g, (_, key) => vars[key] ?? `{${key}}`);
+/**
+* Run an operation: resolve the path template from the type's descriptor, fill its
+* placeholders, execute, and materialise the resulting document. A no-body / 204 response
+* materialises to `undefined`; an operation the type does not declare (no path template) throws
+* a local `Error` before any request. `linkage` marks a relationship-endpoint read (primary
+* `data` is pure resource-identifier linkage) so an attribute-less, relation-less member is
+* still materialised as an identifier.
+*/
+async function run(ctx, type, operation, vars, query, linkage = false, relationForCount) {
+	const template = ctx.descriptor[type]?.paths[operation];
+	if (template === void 0) throw new Error(`No "${operation}" path declared for type "${type}"`);
+	const req = {
+		method: "GET",
+		path: fill(template, vars)
+	};
+	if (query !== void 0) {
+		req.query = query;
+		negotiateProfiles(ctx, type, query, req, relationForCount);
+	}
+	const doc = await execute(ctx.request, req);
+	const primaryType = operation === "fetchMany" ? type : void 0;
+	const paginatorOverride = (operation === "fetchRelated" || operation === "fetchRelationship") && vars["rel"] !== void 0 ? relatedPaginatorKind(ctx.descriptor[type]?.relations[vars["rel"]], ctx.materialise) : void 0;
+	return doc === void 0 ? void 0 : materialise(doc, ctx.materialise, linkage, primaryType, paginatorOverride);
+}
+/**
+* Add any profiles a query's parameters require to the request's negotiated `profiles`. A
+* `withCount` read needs the type's Countable profile in `Accept` — else the server rejects it
+* (400) under strict query-param validation. The profile URI is read from the descriptor's
+* `countable` block (never hardcoded); absent when the type advertises no Countable profile.
+*/
+function negotiateProfiles(ctx, type, query, req, relationForCount) {
+	if (query.withCount === void 0 || query.withCount.length === 0) return;
+	const profile = relationForCount !== void 0 ? ctx.descriptor[type]?.relations[relationForCount]?.countable?.profile : ctx.descriptor[type]?.countable?.profile;
+	if (profile !== void 0) req.profiles = [...req.profiles ?? [], profile];
+}
+/** Project a write's opts to the read-query families the response honours (`include`/`fields`). */
+function writeQuery(opts) {
+	if (opts === void 0) return;
+	const query = {};
+	if (opts.include !== void 0) query.include = [...opts.include];
+	if (opts.fields !== void 0) {
+		const fields = {};
+		for (const [k, v] of Object.entries(opts.fields)) fields[k] = [...v];
+		query.fields = fields;
+	}
+	return Object.keys(query).length > 0 ? query : void 0;
+}
+/**
+* Drive a write: fill the path template, attach the body (and any `include`/`fields` query),
+* execute, and materialise the response (`undefined` for a `204`/no body — so create/update
+* return the resource and delete/`204` relationship mutations resolve `undefined`/`void`).
+* On a thrown {@link JsonApiError}, each error's flat `path` is populated (via `spec.remap`)
+* before it propagates, so a caller's `byPath()` keys are the flat input shape.
+*/
+async function runWrite(ctx, spec) {
+	const template = ctx.descriptor[spec.type]?.paths[spec.operation];
+	if (template === void 0) throw new Error(`No "${spec.operation}" path declared for type "${spec.type}"`);
+	const req = {
+		method: spec.method,
+		path: fill(template, spec.vars),
+		body: spec.body
+	};
+	if (spec.query !== void 0) req.query = spec.query;
+	let doc;
+	try {
+		doc = await execute(ctx.request, req);
+	} catch (error) {
+		if (error instanceof JsonApiError) throw spec.remap(error);
+		throw error;
+	}
+	return doc === void 0 ? void 0 : materialise(doc, ctx.materialise, spec.linkage ?? false);
+}
+/**
+* Invoke a custom action over its declared HTTP method (`action.method`, default `POST`) at its
+* (filled) path, with a body shaped by the action's `input` mode:
+*
+* - `none` — no body;
+* - `document` — when the action names an `inputType`, FLAT input (the resource's attributes /
+*   relationships) is built into the JSON:API envelope like `create`, and a `422`'s
+*   `source.pointer`s are remapped to the flat paths; a bespoke command document (no `inputType`)
+*   is sent verbatim;
+* - `raw` — the caller's payload, sent with the action's declared media type (e.g.
+*   `application/octet-stream`), falling back to a wildcard when the spec declared none.
+*
+* The response is shaped by the action's `output`: `document` materialises into the resource /
+* collection view, `meta` returns the document's top-level `meta`, `none` resolves `undefined` (a
+* `204` / no body).
+*/
+async function runAction(ctx, action, vars, input) {
+	const req = {
+		method: action.method ?? "POST",
+		path: fill(action.path, vars)
+	};
+	let remap;
+	if (action.input === "document") if (action.inputType !== void 0) {
+		const inputType = action.inputType;
+		req.body = toDocument(ctx.descriptor, inputType, input ?? {});
+		remap = (error) => withRemappedPaths(error, ctx.descriptor, inputType);
+	} else req.body = input;
+	else if (action.input === "raw") {
+		req.body = input;
+		req.contentType = action.contentType ?? "*/*";
+		req.raw = true;
+	}
+	let doc;
+	try {
+		doc = await execute(ctx.request, req);
+	} catch (error) {
+		if (remap !== void 0 && error instanceof JsonApiError) throw remap(error);
+		throw error;
+	}
+	if (action.output === "none" || doc === void 0) return;
+	if (action.output === "meta") return doc.meta;
+	return materialise(doc, ctx.materialise);
+}
+/**
+* Build the typed `.actions` accessor at one scope: a plain object exposing exactly the
+* type's actions declared at `scope` (collection on the type accessor, resource on a handle),
+* each a function dispatching to {@link runAction} with the action descriptor + the scope's
+* path vars (resource scope supplies `{id}`). Names not declared at this scope are absent —
+* `client.albums.actions.reissue` (resource-scoped) is undefined; reach it via `.id(id)`.
+*/
+function actionsAccessor(ctx, type, scope, vars) {
+	const actions = ctx.descriptor[type]?.actions ?? {};
+	const out = {};
+	for (const [name, action] of Object.entries(actions)) if (action.scope === scope) out[name] = (input) => runAction(ctx, action, vars, input);
+	return out;
+}
+/**
+* Build the relationship accessor for `client.<type>.id(id).<rel>`: reads
+* (`.get()` linkage / `.related()` collection) plus mutations — to-many `.add` (POST) /
+* `.remove` (DELETE) / `.replace` (PATCH) and to-one `.set` (PATCH). Every mutation posts
+* a `{ data: <linkage> }` body to `fetchRelationship` and materialises the response as
+* linkage (or `undefined`/`void` for a `204`). The cardinality is read off the descriptor
+* so the linkage is coerced correctly; the static types gate which verb is callable.
+*/
+function relationshipAccessor(ctx, type, id, rel) {
+	const vars = {
+		id,
+		rel
+	};
+	const relation = ctx.descriptor[type]?.relations[rel];
+	const cardinality = relation?.cardinality ?? "many";
+	const hasPivot = relation?.pivot === true;
+	const mutate = (method, refs) => runWrite(ctx, {
+		type,
+		operation: "fetchRelationship",
+		vars,
+		method,
+		body: toRelationshipDocument(refs, cardinality),
+		linkage: true,
+		remap: (error) => withRemappedRelationshipPaths(error, rel, hasPivot)
+	});
+	const advertises = (verb) => {
+		const mutations = relation?.mutations;
+		return mutations === void 0 ? true : mutations[verb] === true;
+	};
+	const accessor = {};
+	if (relation?.relationship !== false) accessor["get"] = (query) => run(ctx, type, "fetchRelationship", vars, query, true, rel);
+	if (relation?.related !== false) accessor["related"] = (query) => run(ctx, type, "fetchRelated", vars, query, false, rel);
+	if (cardinality === "many") {
+		if (advertises("add")) accessor["add"] = (refs) => mutate("POST", refs);
+		if (advertises("remove")) accessor["remove"] = (refs) => mutate("DELETE", refs);
+		if (advertises("replace")) accessor["replace"] = (refs) => mutate("PATCH", refs);
+	} else if (advertises("set")) accessor["set"] = (ref) => mutate("PATCH", ref);
+	return accessor;
+}
+/**
+* The reserved members on a {@link ResourceHandle} — names the Proxy resolves itself, so a
+* relation of the same name is shadowed and must route through `.rel(name)`. The codegen
+* imports this to warn at build time (keeping the runtime + the collision detector in sync).
+* `then` is reserved so a handle is never mistaken for a thenable.
+*/
+const HANDLE_RESERVED = /* @__PURE__ */ new Set([
+	"type",
+	"id",
+	"get",
+	"update",
+	"delete",
+	"rel",
+	"actions",
+	"then"
+]);
+/** Build the id-scoped resource handle (a Proxy resolving relation accessors by name). */
+function resourceHandle(ctx, type, id) {
+	const relations = ctx.descriptor[type]?.relations ?? {};
+	const base = {
+		type,
+		id,
+		get: (query) => run(ctx, type, "fetchOne", { id }, query),
+		update: (patch, opts) => runWrite(ctx, {
+			type,
+			operation: "update",
+			vars: { id },
+			method: "PATCH",
+			body: toDocument(ctx.descriptor, type, patch, { id }),
+			query: writeQuery(opts),
+			remap: (error) => withRemappedPaths(error, ctx.descriptor, type)
+		}),
+		delete: () => runWrite(ctx, {
+			type,
+			operation: "delete",
+			vars: { id },
+			method: "DELETE",
+			body: void 0,
+			remap: (error) => withRemappedPaths(error, ctx.descriptor, type)
+		}),
+		rel: (name) => relationshipAccessor(ctx, type, id, name),
+		actions: actionsAccessor(ctx, type, "resource", { id })
+	};
+	return new Proxy(base, { get(target, prop, receiver) {
+		if (typeof prop === "string" && !HANDLE_RESERVED.has(prop) && prop in relations) return relationshipAccessor(ctx, type, id, prop);
+		return Reflect.get(target, prop, receiver);
+	} });
+}
+/** Build the collection-scoped accessor for one wire type (`client.albums`). */
+function typeAccessor(ctx, type) {
+	return {
+		list: (query) => run(ctx, type, "fetchMany", {}, query),
+		get: (id, query) => run(ctx, type, "fetchOne", { id }, query),
+		create: (input, opts) => runWrite(ctx, {
+			type,
+			operation: "create",
+			vars: {},
+			method: "POST",
+			body: toDocument(ctx.descriptor, type, input),
+			query: writeQuery(opts),
+			remap: (error) => withRemappedPaths(error, ctx.descriptor, type)
+		}),
+		id: (id) => resourceHandle(ctx, type, id),
+		actions: actionsAccessor(ctx, type, "collection", {})
+	};
+}
+/**
+* Build a descriptor-driven read client. Generic at runtime (a Proxy over the descriptor),
+* not per-type codegen: `client.<type>` yields a {@link TypeAccessor}, `.id(id)` a handle,
+* and a handle's relation accessors drive the relationship/related endpoints. Navigation
+* (`$next()`/`$prev()`, related links) is wired through `materialise`'s `navigate` seam,
+* which executes the (absolute) link and re-materialises.
+*/
+function createClient(descriptor, options) {
+	const request = {
+		baseUrl: options.baseUrl,
+		transport: options.transport ?? fetchTransport,
+		...options.headers !== void 0 ? { headers: options.headers } : {}
+	};
+	const validator = resolveValidator(options.validate);
+	const ctx = {
+		request,
+		descriptor,
+		materialise: {
+			descriptor,
+			navigate: async (url, linkage = false, paginator) => {
+				const doc = await execute(request, {
+					method: "GET",
+					path: url
+				});
+				return doc === void 0 ? void 0 : materialise(doc, ctx.materialise, linkage, void 0, paginator);
+			},
+			...validator !== void 0 ? { validate: validator } : {}
+		}
+	};
+	const atomicDescriptor = options.atomic ?? null;
+	const atomic = (build) => {
+		if (atomicDescriptor === null) throw new Error("This API does not expose an Atomic Operations endpoint");
+		return runAtomic(request, ctx.materialise, descriptor, atomicDescriptor.path, build);
+	};
+	const accessors = /* @__PURE__ */ new Map();
+	return new Proxy(Object.create(null), {
+		get(_target, prop) {
+			if (prop === "atomic") return atomic;
+			if (typeof prop !== "string" || !(prop in descriptor)) return;
+			let accessor = accessors.get(prop);
+			if (accessor === void 0) {
+				accessor = typeAccessor(ctx, prop);
+				accessors.set(prop, accessor);
+			}
+			return accessor;
+		},
+		has(_target, prop) {
+			return prop === "atomic" || typeof prop === "string" && prop in descriptor;
+		}
+	});
+}
+//#endregion
+exports.ATOMIC_EXT = ATOMIC_EXT;
+exports.ATOMIC_MEDIA_TYPE = ATOMIC_MEDIA_TYPE;
+exports.HANDLE_RESERVED = HANDLE_RESERVED;
+exports.JSON_API_MEDIA_TYPE = JSON_API_MEDIA_TYPE;
+exports.JsonApiError = JsonApiError;
+exports.StructuralGuardError = StructuralGuardError;
+exports.assertJsonApiDocument = assertJsonApiDocument;
+exports.createClient = createClient;
+exports.execute = execute;
+exports.fetchTransport = fetchTransport;
+exports.materialise = materialise;
+exports.mediaType = mediaType;
+exports.relatedPaginatorKind = relatedPaginatorKind;
+exports.remapPointer = remapPointer;
+exports.remapRelationshipPointer = remapRelationshipPointer;
+exports.resolveValidator = resolveValidator;
+exports.runAtomic = runAtomic;
+exports.serializeQuery = serializeQuery;
+exports.toDocument = toDocument;
+exports.toRelationshipDocument = toRelationshipDocument;
+exports.validateDocument = validateDocument;
+exports.withRemappedAtomicPaths = withRemappedAtomicPaths;
+exports.withRemappedPaths = withRemappedPaths;
+exports.withRemappedRelationshipPaths = withRemappedRelationshipPaths;