@haddowg/json-api-client 1.3.1 → 1.4.0

package/README.md

@@ -297,6 +297,12 @@ Retries are deliberately out of scope here — the transport (or the TanStack la
 or `$next({ signal })`). Forward it to your HTTP library so the request can be cancelled; the
 default `fetch` transport passes it to `fetch`.
 
+Two optional members matter only for custom actions with non-JSON:API media types. Send
+`req.rawBody` as is when it's set: a binary, `FormData` or `URLSearchParams` body in place of
+`req.body`. When `req.responseType` is `'blob'` or `'arraybuffer'`, read a successful response
+into `binary` as that type and leave `body` empty; read an error response as text in `body` as
+usual. The `fetch` transport does both.
+
 ## Opt-in validation
 
 The core runtime trusts the wire (you own both ends; the envelope is invariant) and only runs the

package/dist/ajv.d.cts

@@ -1,4 +1,4 @@
-import { a as Validator, n as SchemaMap } from "./validate-B98ghVgw.cjs";
+import { a as Validator, n as SchemaMap } from "./validate-CQv5lmqO.cjs";
 import { ValidateFunction } from "ajv";
 
 //#region src/ajv.d.ts

package/dist/ajv.d.mts

@@ -1,4 +1,4 @@
-import { a as Validator, n as SchemaMap } from "./validate-B98ghVgw.mjs";
+import { a as Validator, n as SchemaMap } from "./validate-CQv5lmqO.mjs";
 import { ValidateFunction } from "ajv";
 
 //#region src/ajv.d.ts

package/dist/index.cjs

@@ -570,7 +570,7 @@ 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);
+const isPlainObject$1 = (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
@@ -579,7 +579,7 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 * wire as `filter[k]=[object Object]` and be silently ignored by the server (D23).
 */
 const appendFilterValue = (parts, key, value) => {
-	if (isPlainObject(value)) {
+	if (isPlainObject$1(value)) {
 		for (const [subKey, subValue] of Object.entries(value)) appendFilterValue(parts, `${key}[${subKey}]`, subValue);
 		return;
 	}
@@ -609,6 +609,22 @@ function serializeQuery(query) {
 * parsed error objects (tolerating a non-JSON error body with an empty list).
 */
 async function execute(ctx, req) {
+	return parseDocument((await send(ctx, req)).body);
+}
+async function executeRaw(ctx, req, as) {
+	const res = await send(ctx, req, as === "text" ? void 0 : as);
+	if (as === "text") return res.body === "" ? void 0 : res.body;
+	if (res.status === 204) return;
+	if (res.binary === void 0) throw new Error("The transport returned no binary body for a request that asked for one; a custom transport must read the response as binary when the request sets responseType.");
+	return res.binary;
+}
+/**
+* Build the URL (a server link resolved against `baseUrl` and held to its origin, an absolute
+* path verbatim, else `baseUrl + path`), apply content negotiation and any async per-request
+* headers, then drive the transport. A non-2xx throws a {@link JsonApiError} carrying the parsed
+* error objects (tolerating a non-JSON error body with an empty list).
+*/
+async function send(ctx, req, responseType) {
 	let url;
 	let sendHeaders = true;
 	if (req.link) {
@@ -632,15 +648,23 @@ async function execute(ctx, req) {
 		headers
 	};
 	if (req.signal !== void 0) transportReq.signal = req.signal;
-	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 (responseType !== void 0) transportReq.responseType = responseType;
+	if (req.body !== void 0 || req.method.toUpperCase() === "POST") {
+		const contentType = req.contentType === void 0 ? negotiated : req.contentType;
+		if (contentType !== null) headers["Content-Type"] = contentType;
 	}
+	if (typeof req.body === "string" && req.raw) transportReq.body = req.body;
+	else if (req.raw && isRawBody(req.body)) transportReq.rawBody = req.body;
+	else if (req.body !== void 0) transportReq.body = JSON.stringify(req.body);
 	if (ctx.headers && sendHeaders) mergeHeaders(headers, await ctx.headers());
 	const res = await ctx.transport(transportReq);
-	if (res.status >= 200 && res.status < 300) return parseDocument(res.body);
+	if (res.status >= 200 && res.status < 300) return res;
 	throw new JsonApiError(res.status, parseErrors(res.body));
 }
+/** Whether a raw body goes to the transport as is rather than through `JSON.stringify`. */
+function isRawBody(body) {
+	return typeof Blob !== "undefined" && body instanceof Blob || body instanceof ArrayBuffer || ArrayBuffer.isView(body) || typeof FormData !== "undefined" && body instanceof FormData || typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams;
+}
 /**
 * Merge a `HeadersInit` (object / tuple array / `Headers`) into the outgoing map,
 * preserving the caller's casing (unlike the WHATWG `Headers`, which lowercases). The
@@ -1028,13 +1052,23 @@ const fetchTransport = async (req) => {
 		method: req.method,
 		headers: req.headers
 	};
-	if (req.body !== void 0) init.body = req.body;
+	if (req.rawBody !== void 0) init.body = req.rawBody;
+	else if (req.body !== void 0) init.body = req.body;
 	if (req.signal !== void 0) init.signal = req.signal;
 	const res = await fetch(req.url, init);
 	const headers = {};
 	res.headers.forEach((value, key) => {
 		headers[key] = value;
 	});
+	if (req.responseType !== void 0 && res.ok) {
+		const binary = req.responseType === "blob" ? await res.blob() : await res.arrayBuffer();
+		return {
+			status: res.status,
+			headers,
+			body: "",
+			binary
+		};
+	}
 	return {
 		status: res.status,
 		headers,
@@ -1145,36 +1179,145 @@ async function runWrite(ctx, spec) {
 * - `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.
 *
+* An action listing several request media types (`inputMedia`) sends the one the caller picks
+* with `options.contentType`, or JSON:API when listed, else the first.
+*
 * 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).
+* `204` / no body). An action declaring `rawOutput` answers in the media type the caller picks
+* with `options.accept`: JSON:API as above, or a `string`, a `Blob` or `ArrayBuffer`, or parsed
+* JSON by the media type's kind.
 */
-async function runAction(ctx, action, vars, input) {
+async function runAction(ctx, action, vars, input, options = {}) {
 	const req = {
 		method: action.method ?? "POST",
 		path: fill(action.path, vars)
 	};
+	if (options.signal !== void 0) req.signal = options.signal;
 	let remap;
-	if (action.input === "document") if (action.inputType !== void 0) {
+	const media = requestMedia(action, options.contentType);
+	if (media !== void 0 && media.kind !== "document") {
+		req.body = encodeFields(media.mediaType, media.kind, input);
+		req.raw = true;
+		req.contentType = sentContentType(media.mediaType, media.kind, req.body);
+	} else 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.body = encodeFields(action.contentType ?? "*/*", void 0, input);
+		req.contentType = sentContentType(action.contentType ?? "*/*", void 0, req.body);
 		req.raw = true;
 	}
-	let doc;
+	const raw = responseMedia(action, options.accept);
 	try {
-		doc = await execute(ctx.request, req);
+		if (raw !== void 0) {
+			req.accept = raw.mediaType;
+			if (raw.kind === "binary") return await executeRaw(ctx.request, req, options.responseType === "arrayBuffer" ? "arraybuffer" : "blob");
+			const text = await executeRaw(ctx.request, req, "text");
+			return raw.kind === "json" && text !== void 0 ? JSON.parse(text) : text;
+		}
+		const doc = await execute(ctx.request, req);
+		if (action.output === "none" || doc === void 0) return;
+		if (action.output === "meta") return doc.meta;
+		return materialise(doc, ctx.materialise);
 	} 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);
+}
+/**
+* The request media type an action with several (`inputMedia`) sends: the caller's pick, matched
+* exactly or through a declared wildcard such as `image/*`, else JSON:API when listed, else the
+* first. `undefined` for an action with a single request media type.
+*/
+function requestMedia(action, picked) {
+	const listed = action.inputMedia;
+	if (listed === void 0 || listed.length === 0) {
+		if (picked !== void 0) throw new Error(`This action declares no request media types to choose "${picked}" from.`);
+		return;
+	}
+	if (picked === void 0) {
+		const media = listed.find((entry) => entry.mediaType === "application/vnd.api+json") ?? listed[0];
+		return {
+			mediaType: media.mediaType,
+			kind: media.kind
+		};
+	}
+	const essence = picked.split(";")[0].trim().toLowerCase();
+	const match = listed.find((entry) => entry.mediaType === essence) ?? listed.find((entry) => entry.mediaType === `${essence.split("/")[0]}/*`) ?? listed.find((entry) => entry.mediaType === "*/*");
+	if (match === void 0) throw new Error(`This action does not accept "${picked}"; it accepts ${listed.map((entry) => entry.mediaType).join(", ")}.`);
+	return {
+		mediaType: picked,
+		kind: match.kind
+	};
+}
+/**
+* A multipart or URL-encoded body given as a plain object of fields, encoded into a `FormData` or
+* `URLSearchParams`. Any other body, a ready `FormData` included, is sent as it is.
+*/
+function encodeFields(mediaType, kind, body) {
+	const multipart = kind === "multipart" || mediaType.startsWith("multipart/");
+	if (!multipart && !(kind === "form" || mediaType === "application/x-www-form-urlencoded") || !isPlainObject(body)) return body;
+	return multipart ? toFormData(body) : toSearchParams(body);
+}
+/** Whether a body is a plain object of fields rather than a ready payload. */
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+/**
+* The entries a field contributes: nothing for `null` or `undefined`, one `name[]` entry per item
+* for an array (the bracket suffix is how PHP servers read a repeated field as a list), else one
+* `name` entry.
+*/
+function fieldEntries(name, value) {
+	if (value === null || value === void 0) return [];
+	if (Array.isArray(value)) return value.filter((item) => item !== null && item !== void 0).map((item) => [`${name}[]`, item]);
+	return [[name, value]];
+}
+/** A field's text value: booleans as `true` or `false`, everything else through `String`. */
+function fieldText(value) {
+	return typeof value === "boolean" ? value ? "true" : "false" : String(value);
+}
+/** A multipart body from fields. A `File` keeps its name; a bare `Blob` is named after its field. */
+function toFormData(fields) {
+	const data = new FormData();
+	for (const [field, value] of Object.entries(fields)) for (const [name, item] of fieldEntries(field, value)) if (typeof Blob !== "undefined" && item instanceof Blob) {
+		const fileName = typeof File !== "undefined" && item instanceof File && item.name !== "" ? item.name : field;
+		data.append(name, item, fileName);
+	} else data.append(name, fieldText(item));
+	return data;
+}
+/** A URL-encoded body from fields. */
+function toSearchParams(fields) {
+	const params = new URLSearchParams();
+	for (const [field, value] of Object.entries(fields)) for (const [name, item] of fieldEntries(field, value)) params.append(name, fieldText(item));
+	return params;
+}
+/**
+* The `Content-Type` for a non-JSON:API body. A multipart `FormData` body gets none, so the
+* transport writes the boundary. A wildcard media type takes a `Blob` body's own type.
+*/
+function sentContentType(mediaType, kind, body) {
+	if ((kind === "multipart" || mediaType.startsWith("multipart/")) && typeof FormData !== "undefined" && body instanceof FormData) return null;
+	if (mediaType.includes("*") && typeof Blob !== "undefined" && body instanceof Blob) return body.type === "" ? mediaType : body.type;
+	return mediaType;
+}
+/**
+* The non-JSON:API media type an action is asked to answer in: the caller's `accept` when it isn't
+* JSON:API, else, with no `accept`, the first raw media type of an action that answers in no
+* JSON:API document. `undefined` means a JSON:API response.
+*/
+function responseMedia(action, accept) {
+	const raw = action.rawOutput ?? [];
+	if (accept === void 0) return action.output === "none" ? raw[0] : void 0;
+	if (accept === "application/vnd.api+json") return;
+	const media = raw.find((entry) => entry.mediaType === accept);
+	if (media === void 0) throw new Error(`This action does not answer in "${accept}"; it answers in ${[...action.output === "none" ? [] : [JSON_API_MEDIA_TYPE], ...raw.map((entry) => entry.mediaType)].join(", ")}.`);
+	return media;
 }
 /**
 * Build the typed `.actions` accessor at one scope: a plain object exposing exactly the
@@ -1186,7 +1329,7 @@ async function runAction(ctx, action, vars, input) {
 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);
+	for (const [name, action] of Object.entries(actions)) if (action.scope === scope) out[name] = (...args) => action.input === "none" ? runAction(ctx, action, vars, void 0, args[0]) : runAction(ctx, action, vars, args[0], args[1]);
 	return out;
 }
 /**
@@ -1360,6 +1503,7 @@ exports.StructuralGuardError = StructuralGuardError;
 exports.assertJsonApiDocument = assertJsonApiDocument;
 exports.createClient = createClient;
 exports.execute = execute;
+exports.executeRaw = executeRaw;
 exports.fetchTransport = fetchTransport;
 exports.hasErrorCode = hasErrorCode;
 exports.materialise = materialise;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { $ as RelationshipAccessor, $t as ActionDescriptor, A as DefaultActionTypes, At as DocumentEnvelope, B as IdentifierMember, Bt as relatedPaginatorKind, C as fetchTransport, Ct as ATOMIC_MEDIA_TYPE, D as Collection, Dt as ResourceIdentifier, E as Client, Et as MediaTypeParams, F as FieldSelectionMap, Ft as RelationView, G as MemberName, Gt as PageLinks, H as IncludedRelations, Ht as ExactPageParams, I as FieldsMap, It as ResourceEnvelope, J as ReadableRelationName, Jt as PageParams, K as PivotInput, Kt as PageMeta, L as FilterKey, Lt as ResourceLinks, M as DefaultWriteAttributes, Mt as EdgeEnvelope, N as EdgeMembers, Nt as MaterialiseContext, O as CountToken, Ot as mediaType, P as ErrorCodeOf, Pt as NavigateOptions, Q as RelationReadQuery, Qt as resolvePaginator, R as FilterQuery, Rt as materialise, S as TransportResponse, St as ATOMIC_EXT, T as AtomicResultOf, Tt as LocalIdentifier, U as LinkageRef, Ut as Page, V as IncludePath, Vt as CANONICAL_PAGE_KEYS, W as ListPageParams, Wt as PageKeys, X as RelationPageParams, Xt as ResolvedPaginator, Y as RelationName, Yt as PageParamsOf, Z as RelationPaginator, Zt as TypedPage, _ as HANDLE_RESERVED, _n as StrategyDescriptor, _t as AtomicResult, a as Validator, an as Cardinality, at as SortToken, b as JsonApiTransport, bt as AtomicUpdateInput, c as resolveValidator, cn as MenuDescriptor, ct as TypedReadQuery, d as JsonApiContext, dn as PaginatorRole, dt as AtomicCreateHandle, en as ActionInput, et as ResourceAccessors, f as JsonApiRequest, fn as PaginatorStrategy, ft as AtomicCreateInput, g as ClientOptions, gn as ResourceDescriptor, gt as AtomicRef, h as serializeQuery, hn as RelationMutations, ht as AtomicRecorder, i as ValidationOption, in as AtomicDescriptor, it as SortQuery, j as DefaultAttributes, jt as Edge, k as CreateInput, kt as ArrayEnvelope, l as validateDocument, ln as PaginatorDescriptor, lt as UpdateInput, m as execute, mn as RelationDescriptor, mt as AtomicHandle, n as SchemaMap, nn as ActionScope, nt as ResourceObjectView, o as WireResource, on as ClientIdPolicy, ot as TypeAccessor, p as ReadQuery, pn as PivotDescriptor, pt as AtomicDeleteHandle, q as ReadResult, qt as PageOf, r as ValidationConfig, rn as ApiDescriptor, rt as SingleReadQuery, s as assertJsonApiDocument, sn as CountableDescriptor, st as TypeName, t as ResolvedValidator, tn as ActionOutput, tt as ResourceHandle, u as Document, un as PaginatorKind, ut as WriteOptions, v as HeadersInit, vt as AtomicResults, w as ActionsAccessor, wt as JSON_API_MEDIA_TYPE, x as TransportRequest, xt as runAtomic, y as createClient, yt as AtomicUpdateHandle, z as HydratedMember, zt as relatedPaginator } from "./validate-B98ghVgw.cjs";
+import { $ as ReadResult, $t as PageOf, A as BinaryBody, At as JSON_API_MEDIA_TYPE, B as ErrorCodeOf, Bt as NavigateOptions, C as TransportRawBody, Cn as RawOutputMedia, Ct as AtomicResult, D as ActionCallOptions, Dn as StrategyDescriptor, Dt as runAtomic, E as fetchTransport, En as ResourceDescriptor, Et as AtomicUpdateInput, F as CreateInput, Ft as ArrayEnvelope, G as HydratedMember, Gt as relatedPaginator, H as FieldsMap, Ht as ResourceEnvelope, I as DefaultActionTypes, It as DocumentEnvelope, J as IncludedRelations, Jt as ExactPageParams, K as IdentifierMember, Kt as relatedPaginatorKind, L as DefaultAttributes, Lt as Edge, M as Client, Mt as MediaTypeParams, N as Collection, Nt as ResourceIdentifier, O as ActionsAccessor, Ot as ATOMIC_EXT, P as CountToken, Pt as mediaType, Q as PivotInput, Qt as PageMeta, R as DefaultWriteAttributes, Rt as EdgeEnvelope, S as JsonApiTransport, Sn as RawMediaKind, St as AtomicRef, T as TransportResponse, Tn as RelationMutations, Tt as AtomicUpdateHandle, U as FilterKey, Ut as ResourceLinks, V as FieldSelectionMap, Vt as RelationView, W as FilterQuery, Wt as materialise, X as ListPageParams, Xt as PageKeys, Y as LinkageRef, Yt as Page, Z as MemberName, Zt as PageLinks, _ as serializeQuery, _n as PaginatorDescriptor, _t as AtomicCreateHandle, a as Validator, an as ActionDescriptor, at as RelationshipAccessor, b as HeadersInit, bn as PaginatorStrategy, bt as AtomicHandle, c as resolveValidator, cn as ActionScope, ct as ResourceObjectView, d as JsonApiContext, dn as Cardinality, dt as SortToken, en as PageParams, et as ReadableRelationName, f as JsonApiRequest, fn as ClientIdPolicy, ft as TypeAccessor, g as executeRaw, gn as MenuDescriptor, gt as WriteOptions, h as execute, hn as InputMediaKind, ht as UpdateInput, i as ValidationOption, in as resolvePaginator, it as RelationReadQuery, j as BinaryResponseType, jt as LocalIdentifier, k as AtomicResultOf, kt as ATOMIC_MEDIA_TYPE, l as validateDocument, ln as ApiDescriptor, lt as SingleReadQuery, m as ReadQuery, mn as InputMedia, mt as TypedReadQuery, n as SchemaMap, nn as ResolvedPaginator, nt as RelationPageParams, o as WireResource, on as ActionInput, ot as ResourceAccessors, p as RawResponseType, pn as CountableDescriptor, pt as TypeName, q as IncludePath, qt as CANONICAL_PAGE_KEYS, r as ValidationConfig, rn as TypedPage, rt as RelationPaginator, s as assertJsonApiDocument, sn as ActionOutput, st as ResourceHandle, t as ResolvedValidator, tn as PageParamsOf, tt as RelationName, u as Document, un as AtomicDescriptor, ut as SortQuery, v as ClientOptions, vn as PaginatorKind, vt as AtomicCreateInput, w as TransportRequest, wn as RelationDescriptor, wt as AtomicResults, x as createClient, xn as PivotDescriptor, xt as AtomicRecorder, y as HANDLE_RESERVED, yn as PaginatorRole, yt as AtomicDeleteHandle, z as EdgeMembers, zt as MaterialiseContext } from "./validate-CQv5lmqO.cjs";
 
 //#region src/errors.d.ts
 /**
@@ -216,5 +216,5 @@ declare function withRemappedRelationshipPaths(error: JsonApiError, rel: string,
  */
 declare function withRemappedAtomicPaths(error: JsonApiError, descriptor: ApiDescriptor, typeForOp: (opIndex: number) => string | undefined): JsonApiError;
 //#endregion
-export { ATOMIC_EXT, ATOMIC_MEDIA_TYPE, ActionDescriptor, ActionInput, ActionOutput, ActionScope, ActionsAccessor, ApiDescriptor, ArrayEnvelope, AtomicCreateHandle, AtomicCreateInput, AtomicDeleteHandle, AtomicDescriptor, AtomicHandle, AtomicRecorder, AtomicRef, AtomicResult, AtomicResultOf, AtomicResults, AtomicUpdateHandle, AtomicUpdateInput, CANONICAL_PAGE_KEYS, Cardinality, Client, ClientIdPolicy, ClientOptions, Collection, CountToken, CountableDescriptor, CreateInput, DefaultActionTypes, DefaultAttributes, DefaultWriteAttributes, Document, DocumentEnvelope, Edge, EdgeEnvelope, EdgeMembers, ErrorCodeGuard, ErrorCodeOf, ExactPageParams, FieldSelectionMap, FieldsMap, FilterKey, FilterQuery, HANDLE_RESERVED, HeadersInit, HydratedMember, IdentifierMember, IncludePath, IncludedRelations, JSON_API_MEDIA_TYPE, JsonApiContext, JsonApiError, JsonApiErrorObject, JsonApiRequest, JsonApiTransport, LinkageRef, ListPageParams, LocalIdentifier, MaterialiseContext, MediaTypeParams, MemberName, MenuDescriptor, NavigateOptions, Page, PageKeys, PageLinks, PageMeta, PageOf, PageParams, PageParamsOf, PaginatorDescriptor, PaginatorKind, PaginatorRole, PaginatorStrategy, PivotDescriptor, PivotInput, ReadQuery, ReadResult, ReadableRelationName, RelationDescriptor, RelationMutations, RelationName, RelationPageParams, RelationPaginator, RelationReadQuery, RelationView, RelationshipAccessor, RelationshipDocument, ResolvedPaginator, ResolvedValidator, ResourceAccessors, ResourceDescriptor, ResourceEnvelope, ResourceHandle, ResourceIdentifier, ResourceLinks, ResourceObjectView, SchemaMap, SingleReadQuery, SortQuery, SortToken, StrategyDescriptor, StructuralGuardError, ToDocumentOptions, TransportRequest, TransportResponse, TypeAccessor, TypeName, TypedPage, TypedReadQuery, UpdateInput, ValidationConfig, ValidationOption, Validator, WireResource, WriteDocument, WriteOptions, assertJsonApiDocument, createClient, execute, fetchTransport, hasErrorCode, materialise, mediaType, relatedPaginator, relatedPaginatorKind, remapPointer, remapRelationshipPointer, resolvePaginator, resolveValidator, runAtomic, serializeQuery, toDocument, toRelationshipDocument, validateDocument, withRemappedAtomicPaths, withRemappedPaths, withRemappedRelationshipPaths };
+export { ATOMIC_EXT, ATOMIC_MEDIA_TYPE, ActionCallOptions, ActionDescriptor, ActionInput, ActionOutput, ActionScope, ActionsAccessor, ApiDescriptor, ArrayEnvelope, AtomicCreateHandle, AtomicCreateInput, AtomicDeleteHandle, AtomicDescriptor, AtomicHandle, AtomicRecorder, AtomicRef, AtomicResult, AtomicResultOf, AtomicResults, AtomicUpdateHandle, AtomicUpdateInput, BinaryBody, BinaryResponseType, CANONICAL_PAGE_KEYS, Cardinality, Client, ClientIdPolicy, ClientOptions, Collection, CountToken, CountableDescriptor, CreateInput, DefaultActionTypes, DefaultAttributes, DefaultWriteAttributes, Document, DocumentEnvelope, Edge, EdgeEnvelope, EdgeMembers, ErrorCodeGuard, ErrorCodeOf, ExactPageParams, FieldSelectionMap, FieldsMap, FilterKey, FilterQuery, HANDLE_RESERVED, HeadersInit, HydratedMember, IdentifierMember, IncludePath, IncludedRelations, InputMedia, InputMediaKind, JSON_API_MEDIA_TYPE, JsonApiContext, JsonApiError, JsonApiErrorObject, JsonApiRequest, JsonApiTransport, LinkageRef, ListPageParams, LocalIdentifier, MaterialiseContext, MediaTypeParams, MemberName, MenuDescriptor, NavigateOptions, Page, PageKeys, PageLinks, PageMeta, PageOf, PageParams, PageParamsOf, PaginatorDescriptor, PaginatorKind, PaginatorRole, PaginatorStrategy, PivotDescriptor, PivotInput, RawMediaKind, RawOutputMedia, RawResponseType, ReadQuery, ReadResult, ReadableRelationName, RelationDescriptor, RelationMutations, RelationName, RelationPageParams, RelationPaginator, RelationReadQuery, RelationView, RelationshipAccessor, RelationshipDocument, ResolvedPaginator, ResolvedValidator, ResourceAccessors, ResourceDescriptor, ResourceEnvelope, ResourceHandle, ResourceIdentifier, ResourceLinks, ResourceObjectView, SchemaMap, SingleReadQuery, SortQuery, SortToken, StrategyDescriptor, StructuralGuardError, ToDocumentOptions, TransportRawBody, TransportRequest, TransportResponse, TypeAccessor, TypeName, TypedPage, TypedReadQuery, UpdateInput, ValidationConfig, ValidationOption, Validator, WireResource, WriteDocument, WriteOptions, assertJsonApiDocument, createClient, execute, executeRaw, fetchTransport, hasErrorCode, materialise, mediaType, relatedPaginator, relatedPaginatorKind, remapPointer, remapRelationshipPointer, resolvePaginator, resolveValidator, runAtomic, serializeQuery, toDocument, toRelationshipDocument, validateDocument, withRemappedAtomicPaths, withRemappedPaths, withRemappedRelationshipPaths };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { $ as RelationshipAccessor, $t as ActionDescriptor, A as DefaultActionTypes, At as DocumentEnvelope, B as IdentifierMember, Bt as relatedPaginatorKind, C as fetchTransport, Ct as ATOMIC_MEDIA_TYPE, D as Collection, Dt as ResourceIdentifier, E as Client, Et as MediaTypeParams, F as FieldSelectionMap, Ft as RelationView, G as MemberName, Gt as PageLinks, H as IncludedRelations, Ht as ExactPageParams, I as FieldsMap, It as ResourceEnvelope, J as ReadableRelationName, Jt as PageParams, K as PivotInput, Kt as PageMeta, L as FilterKey, Lt as ResourceLinks, M as DefaultWriteAttributes, Mt as EdgeEnvelope, N as EdgeMembers, Nt as MaterialiseContext, O as CountToken, Ot as mediaType, P as ErrorCodeOf, Pt as NavigateOptions, Q as RelationReadQuery, Qt as resolvePaginator, R as FilterQuery, Rt as materialise, S as TransportResponse, St as ATOMIC_EXT, T as AtomicResultOf, Tt as LocalIdentifier, U as LinkageRef, Ut as Page, V as IncludePath, Vt as CANONICAL_PAGE_KEYS, W as ListPageParams, Wt as PageKeys, X as RelationPageParams, Xt as ResolvedPaginator, Y as RelationName, Yt as PageParamsOf, Z as RelationPaginator, Zt as TypedPage, _ as HANDLE_RESERVED, _n as StrategyDescriptor, _t as AtomicResult, a as Validator, an as Cardinality, at as SortToken, b as JsonApiTransport, bt as AtomicUpdateInput, c as resolveValidator, cn as MenuDescriptor, ct as TypedReadQuery, d as JsonApiContext, dn as PaginatorRole, dt as AtomicCreateHandle, en as ActionInput, et as ResourceAccessors, f as JsonApiRequest, fn as PaginatorStrategy, ft as AtomicCreateInput, g as ClientOptions, gn as ResourceDescriptor, gt as AtomicRef, h as serializeQuery, hn as RelationMutations, ht as AtomicRecorder, i as ValidationOption, in as AtomicDescriptor, it as SortQuery, j as DefaultAttributes, jt as Edge, k as CreateInput, kt as ArrayEnvelope, l as validateDocument, ln as PaginatorDescriptor, lt as UpdateInput, m as execute, mn as RelationDescriptor, mt as AtomicHandle, n as SchemaMap, nn as ActionScope, nt as ResourceObjectView, o as WireResource, on as ClientIdPolicy, ot as TypeAccessor, p as ReadQuery, pn as PivotDescriptor, pt as AtomicDeleteHandle, q as ReadResult, qt as PageOf, r as ValidationConfig, rn as ApiDescriptor, rt as SingleReadQuery, s as assertJsonApiDocument, sn as CountableDescriptor, st as TypeName, t as ResolvedValidator, tn as ActionOutput, tt as ResourceHandle, u as Document, un as PaginatorKind, ut as WriteOptions, v as HeadersInit, vt as AtomicResults, w as ActionsAccessor, wt as JSON_API_MEDIA_TYPE, x as TransportRequest, xt as runAtomic, y as createClient, yt as AtomicUpdateHandle, z as HydratedMember, zt as relatedPaginator } from "./validate-B98ghVgw.mjs";
+import { $ as ReadResult, $t as PageOf, A as BinaryBody, At as JSON_API_MEDIA_TYPE, B as ErrorCodeOf, Bt as NavigateOptions, C as TransportRawBody, Cn as RawOutputMedia, Ct as AtomicResult, D as ActionCallOptions, Dn as StrategyDescriptor, Dt as runAtomic, E as fetchTransport, En as ResourceDescriptor, Et as AtomicUpdateInput, F as CreateInput, Ft as ArrayEnvelope, G as HydratedMember, Gt as relatedPaginator, H as FieldsMap, Ht as ResourceEnvelope, I as DefaultActionTypes, It as DocumentEnvelope, J as IncludedRelations, Jt as ExactPageParams, K as IdentifierMember, Kt as relatedPaginatorKind, L as DefaultAttributes, Lt as Edge, M as Client, Mt as MediaTypeParams, N as Collection, Nt as ResourceIdentifier, O as ActionsAccessor, Ot as ATOMIC_EXT, P as CountToken, Pt as mediaType, Q as PivotInput, Qt as PageMeta, R as DefaultWriteAttributes, Rt as EdgeEnvelope, S as JsonApiTransport, Sn as RawMediaKind, St as AtomicRef, T as TransportResponse, Tn as RelationMutations, Tt as AtomicUpdateHandle, U as FilterKey, Ut as ResourceLinks, V as FieldSelectionMap, Vt as RelationView, W as FilterQuery, Wt as materialise, X as ListPageParams, Xt as PageKeys, Y as LinkageRef, Yt as Page, Z as MemberName, Zt as PageLinks, _ as serializeQuery, _n as PaginatorDescriptor, _t as AtomicCreateHandle, a as Validator, an as ActionDescriptor, at as RelationshipAccessor, b as HeadersInit, bn as PaginatorStrategy, bt as AtomicHandle, c as resolveValidator, cn as ActionScope, ct as ResourceObjectView, d as JsonApiContext, dn as Cardinality, dt as SortToken, en as PageParams, et as ReadableRelationName, f as JsonApiRequest, fn as ClientIdPolicy, ft as TypeAccessor, g as executeRaw, gn as MenuDescriptor, gt as WriteOptions, h as execute, hn as InputMediaKind, ht as UpdateInput, i as ValidationOption, in as resolvePaginator, it as RelationReadQuery, j as BinaryResponseType, jt as LocalIdentifier, k as AtomicResultOf, kt as ATOMIC_MEDIA_TYPE, l as validateDocument, ln as ApiDescriptor, lt as SingleReadQuery, m as ReadQuery, mn as InputMedia, mt as TypedReadQuery, n as SchemaMap, nn as ResolvedPaginator, nt as RelationPageParams, o as WireResource, on as ActionInput, ot as ResourceAccessors, p as RawResponseType, pn as CountableDescriptor, pt as TypeName, q as IncludePath, qt as CANONICAL_PAGE_KEYS, r as ValidationConfig, rn as TypedPage, rt as RelationPaginator, s as assertJsonApiDocument, sn as ActionOutput, st as ResourceHandle, t as ResolvedValidator, tn as PageParamsOf, tt as RelationName, u as Document, un as AtomicDescriptor, ut as SortQuery, v as ClientOptions, vn as PaginatorKind, vt as AtomicCreateInput, w as TransportRequest, wn as RelationDescriptor, wt as AtomicResults, x as createClient, xn as PivotDescriptor, xt as AtomicRecorder, y as HANDLE_RESERVED, yn as PaginatorRole, yt as AtomicDeleteHandle, z as EdgeMembers, zt as MaterialiseContext } from "./validate-CQv5lmqO.mjs";
 
 //#region src/errors.d.ts
 /**
@@ -216,5 +216,5 @@ declare function withRemappedRelationshipPaths(error: JsonApiError, rel: string,
  */
 declare function withRemappedAtomicPaths(error: JsonApiError, descriptor: ApiDescriptor, typeForOp: (opIndex: number) => string | undefined): JsonApiError;
 //#endregion
-export { ATOMIC_EXT, ATOMIC_MEDIA_TYPE, ActionDescriptor, ActionInput, ActionOutput, ActionScope, ActionsAccessor, ApiDescriptor, ArrayEnvelope, AtomicCreateHandle, AtomicCreateInput, AtomicDeleteHandle, AtomicDescriptor, AtomicHandle, AtomicRecorder, AtomicRef, AtomicResult, AtomicResultOf, AtomicResults, AtomicUpdateHandle, AtomicUpdateInput, CANONICAL_PAGE_KEYS, Cardinality, Client, ClientIdPolicy, ClientOptions, Collection, CountToken, CountableDescriptor, CreateInput, DefaultActionTypes, DefaultAttributes, DefaultWriteAttributes, Document, DocumentEnvelope, Edge, EdgeEnvelope, EdgeMembers, ErrorCodeGuard, ErrorCodeOf, ExactPageParams, FieldSelectionMap, FieldsMap, FilterKey, FilterQuery, HANDLE_RESERVED, HeadersInit, HydratedMember, IdentifierMember, IncludePath, IncludedRelations, JSON_API_MEDIA_TYPE, JsonApiContext, JsonApiError, JsonApiErrorObject, JsonApiRequest, JsonApiTransport, LinkageRef, ListPageParams, LocalIdentifier, MaterialiseContext, MediaTypeParams, MemberName, MenuDescriptor, NavigateOptions, Page, PageKeys, PageLinks, PageMeta, PageOf, PageParams, PageParamsOf, PaginatorDescriptor, PaginatorKind, PaginatorRole, PaginatorStrategy, PivotDescriptor, PivotInput, ReadQuery, ReadResult, ReadableRelationName, RelationDescriptor, RelationMutations, RelationName, RelationPageParams, RelationPaginator, RelationReadQuery, RelationView, RelationshipAccessor, RelationshipDocument, ResolvedPaginator, ResolvedValidator, ResourceAccessors, ResourceDescriptor, ResourceEnvelope, ResourceHandle, ResourceIdentifier, ResourceLinks, ResourceObjectView, SchemaMap, SingleReadQuery, SortQuery, SortToken, StrategyDescriptor, StructuralGuardError, ToDocumentOptions, TransportRequest, TransportResponse, TypeAccessor, TypeName, TypedPage, TypedReadQuery, UpdateInput, ValidationConfig, ValidationOption, Validator, WireResource, WriteDocument, WriteOptions, assertJsonApiDocument, createClient, execute, fetchTransport, hasErrorCode, materialise, mediaType, relatedPaginator, relatedPaginatorKind, remapPointer, remapRelationshipPointer, resolvePaginator, resolveValidator, runAtomic, serializeQuery, toDocument, toRelationshipDocument, validateDocument, withRemappedAtomicPaths, withRemappedPaths, withRemappedRelationshipPaths };
+export { ATOMIC_EXT, ATOMIC_MEDIA_TYPE, ActionCallOptions, ActionDescriptor, ActionInput, ActionOutput, ActionScope, ActionsAccessor, ApiDescriptor, ArrayEnvelope, AtomicCreateHandle, AtomicCreateInput, AtomicDeleteHandle, AtomicDescriptor, AtomicHandle, AtomicRecorder, AtomicRef, AtomicResult, AtomicResultOf, AtomicResults, AtomicUpdateHandle, AtomicUpdateInput, BinaryBody, BinaryResponseType, CANONICAL_PAGE_KEYS, Cardinality, Client, ClientIdPolicy, ClientOptions, Collection, CountToken, CountableDescriptor, CreateInput, DefaultActionTypes, DefaultAttributes, DefaultWriteAttributes, Document, DocumentEnvelope, Edge, EdgeEnvelope, EdgeMembers, ErrorCodeGuard, ErrorCodeOf, ExactPageParams, FieldSelectionMap, FieldsMap, FilterKey, FilterQuery, HANDLE_RESERVED, HeadersInit, HydratedMember, IdentifierMember, IncludePath, IncludedRelations, InputMedia, InputMediaKind, JSON_API_MEDIA_TYPE, JsonApiContext, JsonApiError, JsonApiErrorObject, JsonApiRequest, JsonApiTransport, LinkageRef, ListPageParams, LocalIdentifier, MaterialiseContext, MediaTypeParams, MemberName, MenuDescriptor, NavigateOptions, Page, PageKeys, PageLinks, PageMeta, PageOf, PageParams, PageParamsOf, PaginatorDescriptor, PaginatorKind, PaginatorRole, PaginatorStrategy, PivotDescriptor, PivotInput, RawMediaKind, RawOutputMedia, RawResponseType, ReadQuery, ReadResult, ReadableRelationName, RelationDescriptor, RelationMutations, RelationName, RelationPageParams, RelationPaginator, RelationReadQuery, RelationView, RelationshipAccessor, RelationshipDocument, ResolvedPaginator, ResolvedValidator, ResourceAccessors, ResourceDescriptor, ResourceEnvelope, ResourceHandle, ResourceIdentifier, ResourceLinks, ResourceObjectView, SchemaMap, SingleReadQuery, SortQuery, SortToken, StrategyDescriptor, StructuralGuardError, ToDocumentOptions, TransportRawBody, TransportRequest, TransportResponse, TypeAccessor, TypeName, TypedPage, TypedReadQuery, UpdateInput, ValidationConfig, ValidationOption, Validator, WireResource, WriteDocument, WriteOptions, assertJsonApiDocument, createClient, execute, executeRaw, fetchTransport, hasErrorCode, materialise, mediaType, relatedPaginator, relatedPaginatorKind, remapPointer, remapRelationshipPointer, resolvePaginator, resolveValidator, runAtomic, serializeQuery, toDocument, toRelationshipDocument, validateDocument, withRemappedAtomicPaths, withRemappedPaths, withRemappedRelationshipPaths };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -569,7 +569,7 @@ 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);
+const isPlainObject$1 = (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
@@ -578,7 +578,7 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 * wire as `filter[k]=[object Object]` and be silently ignored by the server (D23).
 */
 const appendFilterValue = (parts, key, value) => {
-	if (isPlainObject(value)) {
+	if (isPlainObject$1(value)) {
 		for (const [subKey, subValue] of Object.entries(value)) appendFilterValue(parts, `${key}[${subKey}]`, subValue);
 		return;
 	}
@@ -608,6 +608,22 @@ function serializeQuery(query) {
 * parsed error objects (tolerating a non-JSON error body with an empty list).
 */
 async function execute(ctx, req) {
+	return parseDocument((await send(ctx, req)).body);
+}
+async function executeRaw(ctx, req, as) {
+	const res = await send(ctx, req, as === "text" ? void 0 : as);
+	if (as === "text") return res.body === "" ? void 0 : res.body;
+	if (res.status === 204) return;
+	if (res.binary === void 0) throw new Error("The transport returned no binary body for a request that asked for one; a custom transport must read the response as binary when the request sets responseType.");
+	return res.binary;
+}
+/**
+* Build the URL (a server link resolved against `baseUrl` and held to its origin, an absolute
+* path verbatim, else `baseUrl + path`), apply content negotiation and any async per-request
+* headers, then drive the transport. A non-2xx throws a {@link JsonApiError} carrying the parsed
+* error objects (tolerating a non-JSON error body with an empty list).
+*/
+async function send(ctx, req, responseType) {
 	let url;
 	let sendHeaders = true;
 	if (req.link) {
@@ -631,15 +647,23 @@ async function execute(ctx, req) {
 		headers
 	};
 	if (req.signal !== void 0) transportReq.signal = req.signal;
-	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 (responseType !== void 0) transportReq.responseType = responseType;
+	if (req.body !== void 0 || req.method.toUpperCase() === "POST") {
+		const contentType = req.contentType === void 0 ? negotiated : req.contentType;
+		if (contentType !== null) headers["Content-Type"] = contentType;
 	}
+	if (typeof req.body === "string" && req.raw) transportReq.body = req.body;
+	else if (req.raw && isRawBody(req.body)) transportReq.rawBody = req.body;
+	else if (req.body !== void 0) transportReq.body = JSON.stringify(req.body);
 	if (ctx.headers && sendHeaders) mergeHeaders(headers, await ctx.headers());
 	const res = await ctx.transport(transportReq);
-	if (res.status >= 200 && res.status < 300) return parseDocument(res.body);
+	if (res.status >= 200 && res.status < 300) return res;
 	throw new JsonApiError(res.status, parseErrors(res.body));
 }
+/** Whether a raw body goes to the transport as is rather than through `JSON.stringify`. */
+function isRawBody(body) {
+	return typeof Blob !== "undefined" && body instanceof Blob || body instanceof ArrayBuffer || ArrayBuffer.isView(body) || typeof FormData !== "undefined" && body instanceof FormData || typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams;
+}
 /**
 * Merge a `HeadersInit` (object / tuple array / `Headers`) into the outgoing map,
 * preserving the caller's casing (unlike the WHATWG `Headers`, which lowercases). The
@@ -1027,13 +1051,23 @@ const fetchTransport = async (req) => {
 		method: req.method,
 		headers: req.headers
 	};
-	if (req.body !== void 0) init.body = req.body;
+	if (req.rawBody !== void 0) init.body = req.rawBody;
+	else if (req.body !== void 0) init.body = req.body;
 	if (req.signal !== void 0) init.signal = req.signal;
 	const res = await fetch(req.url, init);
 	const headers = {};
 	res.headers.forEach((value, key) => {
 		headers[key] = value;
 	});
+	if (req.responseType !== void 0 && res.ok) {
+		const binary = req.responseType === "blob" ? await res.blob() : await res.arrayBuffer();
+		return {
+			status: res.status,
+			headers,
+			body: "",
+			binary
+		};
+	}
 	return {
 		status: res.status,
 		headers,
@@ -1144,36 +1178,145 @@ async function runWrite(ctx, spec) {
 * - `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.
 *
+* An action listing several request media types (`inputMedia`) sends the one the caller picks
+* with `options.contentType`, or JSON:API when listed, else the first.
+*
 * 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).
+* `204` / no body). An action declaring `rawOutput` answers in the media type the caller picks
+* with `options.accept`: JSON:API as above, or a `string`, a `Blob` or `ArrayBuffer`, or parsed
+* JSON by the media type's kind.
 */
-async function runAction(ctx, action, vars, input) {
+async function runAction(ctx, action, vars, input, options = {}) {
 	const req = {
 		method: action.method ?? "POST",
 		path: fill(action.path, vars)
 	};
+	if (options.signal !== void 0) req.signal = options.signal;
 	let remap;
-	if (action.input === "document") if (action.inputType !== void 0) {
+	const media = requestMedia(action, options.contentType);
+	if (media !== void 0 && media.kind !== "document") {
+		req.body = encodeFields(media.mediaType, media.kind, input);
+		req.raw = true;
+		req.contentType = sentContentType(media.mediaType, media.kind, req.body);
+	} else 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.body = encodeFields(action.contentType ?? "*/*", void 0, input);
+		req.contentType = sentContentType(action.contentType ?? "*/*", void 0, req.body);
 		req.raw = true;
 	}
-	let doc;
+	const raw = responseMedia(action, options.accept);
 	try {
-		doc = await execute(ctx.request, req);
+		if (raw !== void 0) {
+			req.accept = raw.mediaType;
+			if (raw.kind === "binary") return await executeRaw(ctx.request, req, options.responseType === "arrayBuffer" ? "arraybuffer" : "blob");
+			const text = await executeRaw(ctx.request, req, "text");
+			return raw.kind === "json" && text !== void 0 ? JSON.parse(text) : text;
+		}
+		const doc = await execute(ctx.request, req);
+		if (action.output === "none" || doc === void 0) return;
+		if (action.output === "meta") return doc.meta;
+		return materialise(doc, ctx.materialise);
 	} 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);
+}
+/**
+* The request media type an action with several (`inputMedia`) sends: the caller's pick, matched
+* exactly or through a declared wildcard such as `image/*`, else JSON:API when listed, else the
+* first. `undefined` for an action with a single request media type.
+*/
+function requestMedia(action, picked) {
+	const listed = action.inputMedia;
+	if (listed === void 0 || listed.length === 0) {
+		if (picked !== void 0) throw new Error(`This action declares no request media types to choose "${picked}" from.`);
+		return;
+	}
+	if (picked === void 0) {
+		const media = listed.find((entry) => entry.mediaType === "application/vnd.api+json") ?? listed[0];
+		return {
+			mediaType: media.mediaType,
+			kind: media.kind
+		};
+	}
+	const essence = picked.split(";")[0].trim().toLowerCase();
+	const match = listed.find((entry) => entry.mediaType === essence) ?? listed.find((entry) => entry.mediaType === `${essence.split("/")[0]}/*`) ?? listed.find((entry) => entry.mediaType === "*/*");
+	if (match === void 0) throw new Error(`This action does not accept "${picked}"; it accepts ${listed.map((entry) => entry.mediaType).join(", ")}.`);
+	return {
+		mediaType: picked,
+		kind: match.kind
+	};
+}
+/**
+* A multipart or URL-encoded body given as a plain object of fields, encoded into a `FormData` or
+* `URLSearchParams`. Any other body, a ready `FormData` included, is sent as it is.
+*/
+function encodeFields(mediaType, kind, body) {
+	const multipart = kind === "multipart" || mediaType.startsWith("multipart/");
+	if (!multipart && !(kind === "form" || mediaType === "application/x-www-form-urlencoded") || !isPlainObject(body)) return body;
+	return multipart ? toFormData(body) : toSearchParams(body);
+}
+/** Whether a body is a plain object of fields rather than a ready payload. */
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+/**
+* The entries a field contributes: nothing for `null` or `undefined`, one `name[]` entry per item
+* for an array (the bracket suffix is how PHP servers read a repeated field as a list), else one
+* `name` entry.
+*/
+function fieldEntries(name, value) {
+	if (value === null || value === void 0) return [];
+	if (Array.isArray(value)) return value.filter((item) => item !== null && item !== void 0).map((item) => [`${name}[]`, item]);
+	return [[name, value]];
+}
+/** A field's text value: booleans as `true` or `false`, everything else through `String`. */
+function fieldText(value) {
+	return typeof value === "boolean" ? value ? "true" : "false" : String(value);
+}
+/** A multipart body from fields. A `File` keeps its name; a bare `Blob` is named after its field. */
+function toFormData(fields) {
+	const data = new FormData();
+	for (const [field, value] of Object.entries(fields)) for (const [name, item] of fieldEntries(field, value)) if (typeof Blob !== "undefined" && item instanceof Blob) {
+		const fileName = typeof File !== "undefined" && item instanceof File && item.name !== "" ? item.name : field;
+		data.append(name, item, fileName);
+	} else data.append(name, fieldText(item));
+	return data;
+}
+/** A URL-encoded body from fields. */
+function toSearchParams(fields) {
+	const params = new URLSearchParams();
+	for (const [field, value] of Object.entries(fields)) for (const [name, item] of fieldEntries(field, value)) params.append(name, fieldText(item));
+	return params;
+}
+/**
+* The `Content-Type` for a non-JSON:API body. A multipart `FormData` body gets none, so the
+* transport writes the boundary. A wildcard media type takes a `Blob` body's own type.
+*/
+function sentContentType(mediaType, kind, body) {
+	if ((kind === "multipart" || mediaType.startsWith("multipart/")) && typeof FormData !== "undefined" && body instanceof FormData) return null;
+	if (mediaType.includes("*") && typeof Blob !== "undefined" && body instanceof Blob) return body.type === "" ? mediaType : body.type;
+	return mediaType;
+}
+/**
+* The non-JSON:API media type an action is asked to answer in: the caller's `accept` when it isn't
+* JSON:API, else, with no `accept`, the first raw media type of an action that answers in no
+* JSON:API document. `undefined` means a JSON:API response.
+*/
+function responseMedia(action, accept) {
+	const raw = action.rawOutput ?? [];
+	if (accept === void 0) return action.output === "none" ? raw[0] : void 0;
+	if (accept === "application/vnd.api+json") return;
+	const media = raw.find((entry) => entry.mediaType === accept);
+	if (media === void 0) throw new Error(`This action does not answer in "${accept}"; it answers in ${[...action.output === "none" ? [] : [JSON_API_MEDIA_TYPE], ...raw.map((entry) => entry.mediaType)].join(", ")}.`);
+	return media;
 }
 /**
 * Build the typed `.actions` accessor at one scope: a plain object exposing exactly the
@@ -1185,7 +1328,7 @@ async function runAction(ctx, action, vars, input) {
 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);
+	for (const [name, action] of Object.entries(actions)) if (action.scope === scope) out[name] = (...args) => action.input === "none" ? runAction(ctx, action, vars, void 0, args[0]) : runAction(ctx, action, vars, args[0], args[1]);
 	return out;
 }
 /**
@@ -1349,6 +1492,6 @@ function createClient(descriptor, options) {
 	});
 }
 //#endregion
-export { ATOMIC_EXT, ATOMIC_MEDIA_TYPE, CANONICAL_PAGE_KEYS, HANDLE_RESERVED, JSON_API_MEDIA_TYPE, JsonApiError, StructuralGuardError, assertJsonApiDocument, createClient, execute, fetchTransport, hasErrorCode, materialise, mediaType, relatedPaginator, relatedPaginatorKind, remapPointer, remapRelationshipPointer, resolvePaginator, resolveValidator, runAtomic, serializeQuery, toDocument, toRelationshipDocument, validateDocument, withRemappedAtomicPaths, withRemappedPaths, withRemappedRelationshipPaths };
+export { ATOMIC_EXT, ATOMIC_MEDIA_TYPE, CANONICAL_PAGE_KEYS, HANDLE_RESERVED, JSON_API_MEDIA_TYPE, JsonApiError, StructuralGuardError, assertJsonApiDocument, createClient, execute, executeRaw, fetchTransport, hasErrorCode, materialise, mediaType, relatedPaginator, relatedPaginatorKind, remapPointer, remapRelationshipPointer, resolvePaginator, resolveValidator, runAtomic, serializeQuery, toDocument, toRelationshipDocument, validateDocument, withRemappedAtomicPaths, withRemappedPaths, withRemappedRelationshipPaths };
 
 //# sourceMappingURL=index.mjs.map