@haddowg/json-api-client 1.3.0 → 1.4.0

package/dist/index.mjs

@@ -539,18 +539,37 @@ const ATOMIC_MEDIA_TYPE = mediaType({ ext: [ATOMIC_EXT] });
 //#region src/request.ts
 const isAbsolute = (path) => /^https?:\/\//i.test(path);
 const RELATIVE_ORIGIN = "http://relative.invalid";
-/** Resolve a server link against `baseUrl` per RFC 3986. An absolute link is kept verbatim. */
+/**
+* Resolve a server link against `baseUrl` per RFC 3986 and check where it lands. A link on the
+* base's origin is followed; a relative base (e.g. `/api`) takes the page's origin in a browser and
+* otherwise only accepts a link that keeps the host. Anything that isn't plain http(s) is refused.
+*/
 function resolveLink(link, baseUrl) {
-	if (isAbsolute(link)) return link;
-	if (isAbsolute(baseUrl)) return new URL(link, baseUrl).href;
-	const resolved = new URL(link, new URL(baseUrl, RELATIVE_ORIGIN));
-	return resolved.origin === RELATIVE_ORIGIN ? resolved.pathname + resolved.search + resolved.hash : resolved.href;
+	let normalised = link.replace(/[\t\n\r]/g, "");
+	let start = 0;
+	while (start < normalised.length && normalised.charCodeAt(start) <= 32) start++;
+	normalised = normalised.slice(start);
+	const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(normalised)?.[1]?.toLowerCase();
+	if (scheme !== void 0 && scheme !== "http" && scheme !== "https") throw new Error(`Refusing to follow link "${link}": only http(s) links are followed`);
+	const relativeBase = !isAbsolute(baseUrl);
+	const page = globalThis.location?.href;
+	const base = new URL(baseUrl, relativeBase ? typeof page === "string" ? page : RELATIVE_ORIGIN : void 0);
+	const resolved = new URL(link, base);
+	const sameOrigin = resolved.origin === base.origin && (scheme === void 0 || /^https?:\/\//i.test(normalised));
+	if (!sameOrigin) return {
+		url: resolved.href,
+		sameOrigin
+	};
+	return {
+		url: relativeBase ? resolved.pathname + resolved.search + resolved.hash : resolved.href,
+		sameOrigin
+	};
 }
 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
@@ -559,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;
 	}
@@ -582,14 +601,37 @@ function serializeQuery(query) {
 	return parts.join("&");
 }
 /**
-* Execute a request: build the URL (a server link resolved against `baseUrl`, an absolute path
-* verbatim, else `baseUrl + path`), apply content negotiation and any async per-request headers,
+* Execute a request: 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 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 = req.link ? resolveLink(req.path, ctx.baseUrl) : isAbsolute(req.path) ? req.path : ctx.baseUrl + req.path;
+	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) {
+		const link = resolveLink(req.path, ctx.baseUrl);
+		if (!link.sameOrigin && ctx.allowCrossOriginLinks !== true) throw new Error(`Refusing to follow link "${req.path}": it leaves the base URL's origin (set allowCrossOriginLinks to follow it without the configured headers)`);
+		url = link.url;
+		sendHeaders = link.sameOrigin;
+	} else url = isAbsolute(req.path) ? req.path : ctx.baseUrl + req.path;
 	if (req.query) {
 		const qs = serializeQuery(req.query);
 		if (qs) url += (url.includes("?") ? "&" : "?") + qs;
@@ -605,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 (ctx.headers) mergeHeaders(headers, await ctx.headers());
+	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
@@ -1001,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,
@@ -1118,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
@@ -1159,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;
 }
 /**
@@ -1279,7 +1448,8 @@ function createClient(descriptor, options) {
 	const request = {
 		baseUrl: options.baseUrl,
 		transport: options.transport ?? fetchTransport,
-		...options.headers !== void 0 ? { headers: options.headers } : {}
+		...options.headers !== void 0 ? { headers: options.headers } : {},
+		...options.allowCrossOriginLinks !== void 0 ? { allowCrossOriginLinks: options.allowCrossOriginLinks } : {}
 	};
 	const validator = resolveValidator(options.validate);
 	const ctx = {
@@ -1322,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