@rig-ts/client 0.1.0

package/dist/index.mjs

@@ -0,0 +1,994 @@
+//#region src/credential.ts
+/** Reports whether a credential wants the runtime handed to it. */
+function isBindable(c) {
+	return c !== void 0 && typeof c.bind === "function";
+}
+/** Reports whether a credential can answer a 401 with something new. */
+function isReauthorizer(c) {
+	return c !== void 0 && typeof c.reauthorize === "function";
+}
+/**
+* A bearer token that never changes.
+*
+* Right for a token from somewhere else — a test fixture, an environment
+* variable, a token minted by the surrounding application. A token that expires
+* wants a `Session`, which refreshes ahead of the expiry rather than discovering
+* it through a failed request.
+*/
+function staticToken(token) {
+	return { apply(headers) {
+		headers.set("Authorization", `Bearer ${token}`);
+	} };
+}
+/**
+* An API key, presented the same way a token is.
+*
+* The server tells the two apart by what the value is, not by how it arrived, so
+* this is a separate name only because a caller holding one should not have to
+* know that. It is {@link staticToken} and not a copy of it: two bodies that
+* have to stay identical is how one of them eventually does not, and there is
+* nothing here that could correctly differ — the day a key travels somewhere a
+* token does not, this stops being an alias and starts being a function.
+*/
+const apiKey = staticToken;
+//#endregion
+//#region src/rate-limit.ts
+/**
+* The headers a rig server describes a caller's budget with.
+*
+* They go out on every response, not only on a refusal, which is the whole
+* point: a client that can see it is at 900 of 1000 can slow down before it is
+* refused.
+*/
+const RATE_LIMIT_LIMIT = "RateLimit-Limit";
+/** How much of the budget has been spent. */
+const used = (s) => Math.max(s.limit - s.remaining, 0);
+/**
+* How much of the budget is spent, from 0 to 1.
+*
+* It is the number worth alerting on, and it is here rather than left to the
+* caller because the obvious arithmetic divides by zero: a response from a
+* server with no limit configured carries no headers and leaves `limit` at 0.
+*/
+const fraction = (s) => s.limit <= 0 ? 0 : used(s) / s.limit;
+/**
+* Reads the status out of a response, or `undefined` when the server said
+* nothing at all.
+*
+* A server with no `throttle:` block sends none of these headers, and a caller
+* that treated an absent header as zero would read "no budget left" out of a
+* server that has no limits.
+*/
+const rateLimitOf = (op, res) => {
+	const limit = readInt(res.headers.get(RATE_LIMIT_LIMIT));
+	if (limit === void 0) return void 0;
+	return {
+		op,
+		limit,
+		remaining: readInt(res.headers.get("RateLimit-Remaining")) ?? 0,
+		resetAfterMs: (readInt(res.headers.get("RateLimit-Reset")) ?? 0) * 1e3,
+		refused: res.status === 429
+	};
+};
+const readInt = (raw) => {
+	if (raw === null || raw.trim() === "") return void 0;
+	const n = Number(raw);
+	return Number.isInteger(n) && n >= 0 ? n : void 0;
+};
+//#endregion
+//#region src/runtime.ts
+/** Where the generated server looks for a caller's own request identifier. */
+const DEFAULT_REQUEST_ID_HEADER = "X-Request-Id";
+/**
+* Carries the API revision, and is what `rig.yaml`'s `api.revision_header`
+* defaults to. A generated client passes its project's own, so this is the
+* fallback for a client somebody built by hand.
+*/
+const DEFAULT_REVISION_HEADER = "API-Revision";
+/**
+* One client's configuration and the state it accumulates.
+*
+* The remembered QUERY decision is the reason this is state rather than
+* configuration: a client that learned an intermediary refuses QUERY should not
+* have to learn it again on the next search.
+*/
+var Runtime = class {
+	api;
+	fetch;
+	now;
+	retry;
+	timeoutMs;
+	/**
+	* Where a caller's own request identifier is sent. Readable rather than
+	* private because the transport writes to it too: a call that names its own
+	* identifier has to land in the header this client was configured with, or a
+	* deployment that moved the header gets two of them disagreeing.
+	*/
+	requestIdHeader;
+	/** The randomness in a backoff, held here so a test can make one deterministic. */
+	jitter = (n) => Math.floor(Math.random() * n);
+	baseUrl;
+	headers;
+	requestIdOf;
+	revision;
+	revisionHeader;
+	credential;
+	onRateLimit;
+	/** Records that QUERY was refused once and is not worth trying again. */
+	searchByPost = false;
+	constructor(config, api) {
+		if (config.baseUrl === void 0) throw new Error("@rig-ts/client: a baseUrl is required");
+		this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+		this.api = api;
+		this.headers = new Headers(config.headers);
+		this.credential = config.credential;
+		this.requestIdOf = config.requestId;
+		this.requestIdHeader = config.requestIdHeader ?? "X-Request-Id";
+		this.revision = config.revision ?? api.revision ?? "";
+		this.revisionHeader = config.revisionHeader ?? api.revisionHeader ?? "API-Revision";
+		this.fetch = config.fetch ?? globalThis.fetch.bind(globalThis);
+		this.now = config.now ?? Date.now;
+		this.retry = config.retry ?? {};
+		this.timeoutMs = config.timeoutMs;
+		this.onRateLimit = config.onRateLimit;
+		if (isBindable(this.credential)) this.credential.bind(this);
+	}
+	/**
+	* Hands the caller's budget to the configured callback, if the response said
+	* anything about it and anybody is listening.
+	*
+	* A throwing callback must not fail the call it was observing: it is
+	* telemetry about a request that otherwise succeeded, and turning a bad
+	* gauge into a failed write would be the wrong trade in both directions.
+	*/
+	observeRateLimit(op, res) {
+		if (this.onRateLimit === void 0) return;
+		const status = rateLimitOf(op, res);
+		if (status === void 0) return;
+		try {
+			this.onRateLimit(status);
+		} catch {}
+	}
+	/** The origin requests go to. */
+	get origin() {
+		return this.baseUrl;
+	}
+	/** The credential in force, or `undefined`. */
+	getCredential() {
+		return this.credential;
+	}
+	/**
+	* Installs a credential, replacing whatever was there. It is what signing in
+	* does, and what a caller does by hand when they already hold a token from
+	* somewhere else.
+	*/
+	use(credential) {
+		this.credential = credential;
+		if (isBindable(credential)) credential.bind(this);
+	}
+	/** Whether this client has learned that QUERY does not get through. */
+	searchesByPost() {
+		return this.searchByPost;
+	}
+	/** Remembers a refused QUERY, so it is tried once per client and not once per call. */
+	rememberSearchByPost() {
+		this.searchByPost = true;
+	}
+	/**
+	* The absolute URL for an operation.
+	*
+	* `extra` is what a call option added, and it wins where the two name the
+	* same parameter: the operation's own query came from the typed arguments of
+	* a generated method, and an option is the caller saying something about
+	* this one call afterwards.
+	*/
+	url(path, query, extra, root) {
+		const base = root ? "" : this.api.basePath;
+		let out = `${this.baseUrl}${base}${path}`;
+		const merged = new URLSearchParams(query);
+		if (extra !== void 0) for (const [key, value] of extra) merged.set(key, value);
+		const search = merged.toString();
+		if (search !== "") out += `?${search}`;
+		return out;
+	}
+	/** The headers every request from this client carries, before the call's own. */
+	baseHeaders() {
+		const headers = new Headers(this.headers);
+		if (this.revision !== "") headers.set(this.revisionHeader, this.revision);
+		if (this.requestIdOf !== void 0) {
+			const id = this.requestIdOf();
+			if (id !== "") headers.set(this.requestIdHeader, id);
+		}
+		return headers;
+	}
+};
+//#endregion
+//#region src/errors.ts
+/**
+* A request the server refused.
+*
+* The code, not the status, is what to switch on. Three unrelated failures
+* share a 400 and none of them share a code, which is the whole reason the
+* generated server sends one.
+*
+* `TFields` is the shape of the body that caused the refusal. A caller does not
+* name it: the generated client declares a guard per call that does, so
+* `isTodoCreateError(err)` reads back what `todos.create` refused. Naming it by
+* hand is what `fieldsAs` asks for, and it is why the per-call guard exists —
+* the wrong shape decodes perfectly and answers with an empty object, because
+* every member of a field-error shape is optional.
+*/
+var RigError = class extends Error {
+	/**
+	* The HTTP status, for the cases where only it is meaningful — a 502 from
+	* something in front of the server, say, which carries no code.
+	*/
+	status;
+	/**
+	* The machine-readable reason. Empty when the failure came from something
+	* that is not a rig server.
+	*/
+	code;
+	/** Prose, for a person. It is not meant to be parsed. */
+	detail;
+	/**
+	* Correlates this failure with the server's logs. Quoting it in a bug
+	* report is the difference between a search and a guess.
+	*/
+	requestId;
+	/**
+	* What was wrong with each member of the body — one member per field,
+	* holding what was wrong with it.
+	*
+	* `undefined` for every refusal but a 422. A 404 has a code and a message
+	* and nothing to put beside a control, and an empty object there would read
+	* as a body nobody complained about.
+	*/
+	fields;
+	/**
+	* How long the server asked the caller to wait, in milliseconds, from the
+	* header of the same name in either form it takes: the seconds rig's own
+	* server sends, and the date something in front of it might. Zero when it
+	* said nothing, or asked for a moment already past.
+	*
+	* The SDK honours it for a call it may repeat, so this is mostly for the
+	* refusal that came back anyway — where the interval was longer than the
+	* call had left to spend.
+	*/
+	retryAfterMs;
+	/**
+	* The start of the raw response, kept for a failure that decoded into
+	* nothing useful — a proxy's HTML error page, say. Bounded even where the
+	* read was not, so a large validation failure is complete in `fields` and
+	* cut short here.
+	*/
+	body;
+	constructor(init) {
+		super(describe(init.status, init.code ?? "", init.detail ?? "", init.requestId ?? ""));
+		this.name = "RigError";
+		this.status = init.status;
+		this.code = init.code ?? "";
+		this.detail = init.detail ?? "";
+		this.requestId = init.requestId ?? "";
+		this.fields = init.fields;
+		this.retryAfterMs = init.retryAfterMs ?? 0;
+		this.body = init.body ?? "";
+	}
+};
+/**
+* The codes a rig server sends, matching `rig/runtime/rigerr`. The constant a
+* client switches on is the constant a handler returned.
+*/
+const ErrorCode = {
+	BadRequest: "BadRequest",
+	Unauthorized: "Unauthorized",
+	Forbidden: "Forbidden",
+	NotFound: "NotFound",
+	Conflict: "Conflict",
+	UnprocessableEntity: "UnprocessableEntity",
+	RateLimited: "RateLimited",
+	TooLarge: "TooLarge",
+	UnsupportedMediaType: "UnsupportedMediaType",
+	UpgradeRequired: "UpgradeRequired",
+	Internal: "Internal"
+};
+/**
+* Why one member of a body was refused, matching `rig/runtime/rigerr`.
+*
+* The same nine codes for every project, so a form can decide what to show from
+* the code and fall back to the message rather than parsing it.
+*/
+const FieldCode = {
+	CannotBeEmpty: "CannotBeEmpty",
+	CannotBeNull: "CannotBeNull",
+	TooLong: "TooLong",
+	TooShort: "TooShort",
+	OutOfRange: "OutOfRange",
+	InvalidValue: "InvalidValue",
+	AlreadyExists: "AlreadyExists",
+	NotFound: "NotFound",
+	NotAllowed: "NotAllowed"
+};
+/**
+* Reports whether a thrown value is a refusal the server explained.
+*
+* False for anything that never reached the server — a DNS failure, an aborted
+* request — because there is no envelope for a code or a field to have come
+* from.
+*/
+function isRigError(err) {
+	return err instanceof RigError;
+}
+/**
+* The code on a refusal, or the empty string for anything else.
+*
+* The predicates below are one line each on top of it; reach for it directly
+* when switching over several codes at once.
+*/
+function codeOf(err) {
+	return isRigError(err) ? err.code : "";
+}
+/** True when the row, or the route, was not there. */
+const isNotFound = (err) => codeOf(err) === ErrorCode.NotFound;
+/** True when the write lost a race, or would have broken a uniqueness rule. */
+const isConflict = (err) => codeOf(err) === ErrorCode.Conflict;
+/** True when the caller was not signed in, or the token had expired. */
+const isUnauthorized = (err) => codeOf(err) === ErrorCode.Unauthorized;
+/** True when the caller was signed in and still not allowed. */
+const isForbidden = (err) => codeOf(err) === ErrorCode.Forbidden;
+/** True when the body was refused field by field. `fields` says which. */
+const isInvalid = (err) => codeOf(err) === ErrorCode.UnprocessableEntity;
+/** True when the caller was asked to slow down. `retryAfterMs` says how long. */
+const isRateLimited = (err) => codeOf(err) === ErrorCode.RateLimited;
+/** True when the body, or the upload, was over the limit. */
+const isTooLarge = (err) => codeOf(err) === ErrorCode.TooLarge;
+/** True when the content type was not one this route accepts. */
+const isUnsupportedMediaType = (err) => codeOf(err) === ErrorCode.UnsupportedMediaType;
+/** True when the client is older than the API surface still supports. */
+const isUpgradeRequired = (err) => codeOf(err) === ErrorCode.UpgradeRequired;
+/**
+* Reads a refusal back as the shape of the body that caused it.
+*
+* This is the hand-written counterpart of the generated per-call guards, for a
+* request made through the runtime directly. It cannot check that the shape is
+* the right one — that is what the generated guard is for.
+*/
+function fieldsAs(err) {
+	return isRigError(err) ? err.fields : void 0;
+}
+/**
+* The longest response kept on {@link RigError.body}. Enough to recognise a
+* proxy's error page, short enough that it does not become the log line.
+*/
+const MAX_ERROR_BODY = 8 * 1024;
+/**
+* Reads a refused response into an error.
+*
+* The response is consumed here, whatever the content type — a caller that got
+* this far is not going to read the body a second way.
+*
+* `requestIdHeader` is the name the client is configured with, passed in rather
+* than written here: a project that renamed the header on the way out was still
+* having the answer read back under the default name, so the identifier went
+* missing from every refusal in exactly the projects that cared enough to
+* rename it.
+*/
+async function readError(res, nowMs, requestIdHeader) {
+	const headerRequestId = res.headers.get(requestIdHeader) ?? "";
+	const retryAfterMs = parseRetryAfter(res.headers.get("Retry-After"), nowMs);
+	let raw = "";
+	try {
+		raw = await res.text();
+	} catch {}
+	const envelope = isJson(res.headers.get("Content-Type")) ? decode(raw) : void 0;
+	return new RigError({
+		status: res.status,
+		code: envelope?.code ?? "",
+		detail: envelope?.message ?? "",
+		requestId: envelope?.request_id ?? headerRequestId,
+		...envelope?.fields !== void 0 ? { fields: envelope.fields } : {},
+		retryAfterMs,
+		body: raw.slice(0, MAX_ERROR_BODY)
+	});
+}
+function decode(raw) {
+	if (raw === "") return void 0;
+	try {
+		const parsed = JSON.parse(raw);
+		if (typeof parsed !== "object" || parsed === null) return void 0;
+		return parsed;
+	} catch {
+		return;
+	}
+}
+function isJson(contentType) {
+	if (contentType === null) return false;
+	const media = contentType.split(";")[0]?.trim().toLowerCase() ?? "";
+	return media === "application/json" || media.endsWith("+json");
+}
+/**
+* Reads Retry-After in either form the specification allows: a count of seconds,
+* or an HTTP date. An interval already past is zero rather than negative.
+*/
+function parseRetryAfter(value, nowMs) {
+	if (value === null || value.trim() === "") return 0;
+	const seconds = Number(value.trim());
+	if (Number.isFinite(seconds)) return seconds > 0 ? seconds * 1e3 : 0;
+	const at = Date.parse(value);
+	if (Number.isNaN(at)) return 0;
+	return Math.max(0, at - nowMs);
+}
+function describe(status, code, detail, requestId) {
+	let out = "rig: ";
+	if (code !== "") out += `${code}: `;
+	out += detail !== "" ? detail : `HTTP ${status}`;
+	out += ` (${status})`;
+	if (requestId !== "") out += ` [request ${requestId}]`;
+	return out;
+}
+//#endregion
+//#region src/op.ts
+/**
+* The HTTP method a generated search uses.
+*
+* A method rather than a POST because a search is a read: it has a body, and it
+* is safe and idempotent, and pretending otherwise is what made every API in the
+* world invent `/_search`.
+*/
+const METHOD_QUERY = "QUERY";
+/**
+* Reports whether this operation may be sent twice.
+*
+* Asked of the operation the generated method built, before a refused QUERY is
+* rewritten: a deployment whose proxy refuses QUERY is exactly the one whose
+* searches most need retrying, and keying on the wire method would quietly take
+* that away.
+*
+* A delete is in, on the strength of what it leaves behind rather than what it
+* answers. If the first attempt succeeded and its answer was lost, the second
+* one is a 404 — so a delete that worked can come back `isNotFound`. The row is
+* gone either way, and a duplicated create is not recoverable that way, which is
+* the whole of the distinction.
+*/
+function isIdempotent(op) {
+	return op.method === "GET" || op.method === "HEAD" || op.method === "DELETE" || op.method === "QUERY";
+}
+/**
+* Reports whether this operation can produce something a second one would
+* duplicate, and so whether it is worth naming with an idempotency key.
+*
+* A form is excluded, and that is about the server rather than about the client.
+* An upload route is the one write a rig server does not record against a key:
+* its body is still arriving when the service is called, and a transaction held
+* open for a transfer is a pooled connection held open for a transfer. So a key
+* generated here would name a write nobody wrote down, and repeating it would
+* store the file twice.
+*/
+function writes(op) {
+	if (op.form !== void 0) return false;
+	return op.method === "POST" || op.method === "PATCH" || op.method === "PUT";
+}
+/** The same operation addressed to the alias route. */
+function asPost(op) {
+	const { fallback, ...rest } = op;
+	return {
+		...rest,
+		method: "POST",
+		path: fallback ?? op.path
+	};
+}
+/**
+* How long to wait before the next attempt, where `attempt` is the one that just
+* failed.
+*
+* `afterMs` is what the server asked for, and it wins outright: `Retry-After` is
+* not a hint, it is the interval after which the request stops being refused,
+* and guessing a shorter one spends the next attempt on the same refusal. It is
+* not jittered, because it is a boundary rather than a guess — and it also
+* cancels the immediate first retry, because a server that has just said when to
+* come back has answered that question.
+*
+* It is returned whole rather than clamped to {@link MAX_RETRY_AFTER_MS}.
+* Clamping would mean going back before the server said to, which is a request
+* refused twice; an interval too long to agree to is one the caller is told
+* about instead.
+*/
+function retryDelayMs(retry, attempt, afterMs, jitter) {
+	if (afterMs > 0) return afterMs;
+	if (attempt <= 1) return 0;
+	const cap = retry.capMs ?? 2e3;
+	const base = retry.baseMs ?? 1e3;
+	const window = Math.min(base * 2 ** Math.min(attempt - 2, 32), cap);
+	const half = Math.floor(window / 2);
+	return half + jitter(half + 1);
+}
+/** How many attempts this configuration allows. */
+function attemptsOf(retry) {
+	const n = retry.attempts ?? 0;
+	return n > 0 ? n : 4;
+}
+/**
+* Reports whether a status is worth sending the same request for again.
+*
+* A list rather than `status >= 500`. A 501 is excluded deliberately: it is the
+* QUERY fallback's own signal, and a method nobody in the chain has heard of
+* will not have been heard of a second later. A 505 is about the protocol, and
+* no wait fixes that either.
+*/
+function retryable(status) {
+	return status === 429 || status === 500 || status === 502 || status === 503 || status === 504;
+}
+/** Whether a wait of `ms` still leaves time to make the attempt after it. */
+function budgetAllows(budget, ms) {
+	if (budget.deadlineMs === void 0) return true;
+	return budget.now() + ms < budget.deadlineMs;
+}
+/** What one attempt may spend, or `undefined` when the call has no ceiling. */
+function budgetLeash(budget) {
+	if (budget.deadlineMs === void 0) return void 0;
+	return Math.max(0, budget.deadlineMs - budget.now());
+}
+/**
+* Waits, unless the caller's signal goes first.
+*
+* Rejects with the reason the wait was abandoned rather than with a timer
+* error, so an aborted call reports what aborted it.
+*/
+function waitFor(ms, signal) {
+	if (ms <= 0) return Promise.resolve();
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted === true) {
+			reject(signal.reason);
+			return;
+		}
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		function onAbort() {
+			clearTimeout(timer);
+			reject(signal?.reason);
+		}
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+//#endregion
+//#region src/transport.ts
+/** The query-string key that widens an owner-scoped read. */
+const SCOPE_PARAM = "scope";
+/**
+* Performs a call the document says answers with a body, and decodes it.
+*
+* A 204 where a body was promised throws rather than resolving to `undefined`.
+* That is a deliberate trade against {@link sendOptional}: the alternative is
+* every generated method answering `T | undefined`, so every call site narrows a
+* value that in practice is always there — and the one time it is not, the
+* server and the document disagree, which is a bug and reads better as one.
+*/
+async function send(rt, op, opts = {}) {
+	const out = await sendOptional(rt, op, opts);
+	if (out === void 0) throw new Error(`@rig-ts/client: ${op.method} ${op.path} answered with no body, but the API document says it has one`);
+	return out;
+}
+/**
+* Performs a call and decodes the response body, or `undefined` when there was
+* none.
+*
+* This is the shape for an endpoint that can honestly answer either way, and for
+* a request made through the runtime by hand.
+*/
+async function sendOptional(rt, op, opts = {}) {
+	const res = await call(rt, op, opts);
+	if (res.status === 204 || res.status === 304) return void 0;
+	const raw = await res.text();
+	if (raw === "") return void 0;
+	try {
+		return JSON.parse(raw);
+	} catch (cause) {
+		throw new Error(`@rig-ts/client: reading the response to ${op.method} ${op.path}`, { cause });
+	}
+}
+/**
+* Performs a call that answers with nothing, such as a delete.
+*
+* Any body is drained and discarded rather than parsed: an endpoint that grows
+* one later should not break a client that never wanted it.
+*/
+async function sendNoContent(rt, op, opts = {}) {
+	await (await call(rt, op, opts)).arrayBuffer().catch(() => void 0);
+}
+/**
+* Performs a call and hands back the response unread, for a download.
+*
+* The caller owns the body from here: nothing below reads it, so streaming a
+* large file does not require buffering it first.
+*/
+async function sendContent(rt, op, opts = {}) {
+	return await call(rt, op, opts);
+}
+/**
+* Sends the request, handling the three things every call shares: a credential
+* that may need refreshing, a QUERY an intermediary may refuse, and a failure
+* the server has asked to be given another go at.
+*
+* The three re-sends are counted separately, deliberately. The fallback happens
+* at most once and is the same request addressed differently; the
+* reauthorization happens at most once and is the same request with a different
+* credential; only the retry is the same request in the same words, and only it
+* spends the attempt budget. Counting them together would leave a search behind
+* a refusing proxy with one retry fewer than the read beside it, for a reason
+* nobody looking at either could see.
+*/
+async function call(rt, initial, opts) {
+	let op = initial;
+	let repeatable = isIdempotent(op);
+	const retry = {
+		...rt.retry,
+		...opts.attempts !== void 0 ? { attempts: opts.attempts } : {}
+	};
+	const budget = budgetFor(rt, opts);
+	const headers = new Headers(opts.headers);
+	const attempts = attemptsOf(retry);
+	const ladder = {
+		rt,
+		opts,
+		retry,
+		budget,
+		attempts
+	};
+	if (!repeatable && writes(op) && attempts > 1) {
+		const key = opts.idempotencyKey ?? headers.get("Idempotency-Key") ?? newIdempotencyKey();
+		if (key !== "") {
+			headers.set("Idempotency-Key", key);
+			repeatable = true;
+		}
+	} else if (opts.idempotencyKey !== void 0) headers.set("Idempotency-Key", opts.idempotencyKey);
+	if (op.method === "QUERY" && op.fallback !== void 0 && rt.searchesByPost()) op = asPost(op);
+	let attempt = 1;
+	let fellBack = false;
+	let reauthorized = false;
+	for (;;) {
+		let res;
+		try {
+			res = await attemptOnce(rt, op, opts, headers, budgetLeash(budget));
+		} catch (err) {
+			attempt = await backoffOrThrow(ladder, attempt, repeatable && !isAbort(err, opts.signal), 0, err);
+			continue;
+		}
+		if (!fellBack && op.method === "QUERY" && op.fallback !== void 0 && (res.status === 405 || res.status === 501)) {
+			await res.arrayBuffer().catch(() => void 0);
+			rt.rememberSearchByPost();
+			fellBack = true;
+			op = asPost(op);
+			continue;
+		}
+		if (res.status === 401 && !reauthorized) {
+			const cred = rt.getCredential();
+			if (isReauthorizer(cred) && opts.anonymous !== true) {
+				const refusal = await readError(res, rt.now(), rt.requestIdHeader);
+				if (!await cred.reauthorize(opts.signal)) throw refusal;
+				reauthorized = true;
+				continue;
+			}
+		}
+		if (res.status === 304 && opts.ifNoneMatch !== void 0) return res;
+		if (res.status < 200 || res.status > 299) {
+			const refusal = await readError(res, rt.now(), rt.requestIdHeader);
+			attempt = await backoffOrThrow(ladder, attempt, repeatable && retryable(res.status), refusal.retryAfterMs, refusal);
+			continue;
+		}
+		return res;
+	}
+}
+/**
+* Waits for the gap before the next send, and answers what attempt it is.
+*
+* Throws `cause` — the caller's own error, never one invented here — when there
+* is no next send: nothing left to repeat, no attempts left, or no room in the
+* budget. So the caller gets the transport's own failure, or the server's own
+* refusal with `retryAfterMs` still on it, rather than a timeout from this
+* clock blaming it for somebody else's outage.
+*
+* The two call sites disagree about exactly two things, and those are the two
+* parameters: what makes a failure worth repeating at all — an abort is the
+* transport's own answer and a 400 is the server's — and what the server asked
+* to be waited. Everything under them is one ladder: the attempt ceiling, the
+* delay, the budget, the wait, the increment. It is written once because a
+* retry engine whose two halves count differently is a bug that surfaces as a
+* call giving up one send early, on the path nobody was looking at.
+*
+* A `retryAfterMs` of 0 is a wait nobody asked for, which is why the ceiling
+* test below is safe for the transport-throw site that passes it: no server
+* said anything, so there is nothing to refuse.
+*/
+async function backoffOrThrow(ladder, attempt, worthRepeating, retryAfterMs, cause) {
+	const { rt, opts, retry, budget, attempts } = ladder;
+	if (!worthRepeating || attempt >= attempts) throw cause;
+	const wait = retryDelayMs(retry, attempt, retryAfterMs, rt.jitter);
+	if (retryAfterMs > 3e4 || !budgetAllows(budget, wait)) throw cause;
+	await waitFor(wait, opts.signal);
+	return attempt + 1;
+}
+/** Builds and performs one HTTP request. */
+async function attemptOnce(rt, op, opts, callHeaders, leashMs) {
+	if (op.body !== void 0 && op.form !== void 0) throw new Error(`@rig-ts/client: ${op.method} ${op.path} carries both a JSON body and a form; a generated method sends one or the other`);
+	const headers = rt.baseHeaders();
+	for (const [key, value] of callHeaders) headers.set(key, value);
+	headers.set("Accept", op.accept ?? "application/json");
+	if (opts.requestId !== void 0) headers.set(rt.requestIdHeader, opts.requestId);
+	if (opts.ifNoneMatch !== void 0) headers.set("If-None-Match", opts.ifNoneMatch);
+	let body;
+	if (op.form !== void 0) body = op.form;
+	else if (op.body !== void 0) {
+		headers.set("Content-Type", "application/json");
+		body = JSON.stringify(op.body);
+	}
+	if (opts.anonymous !== true) await rt.getCredential()?.apply(headers, opts.signal);
+	const extra = new URLSearchParams(opts.query);
+	if (opts.wide === true) extra.set(SCOPE_PARAM, "all");
+	const url = rt.url(op.path, op.query, extra, op.root === true);
+	const signal = leashMs === void 0 ? opts.signal : combine(opts.signal, leashMs);
+	const res = await rt.fetch(url, {
+		method: op.method,
+		headers,
+		...body !== void 0 ? { body } : {},
+		...signal !== void 0 ? { signal } : {}
+	});
+	rt.observeRateLimit(op.name, res);
+	return res;
+}
+/** What is left of the time this call was given. */
+function budgetFor(rt, opts) {
+	const ms = opts.timeoutMs ?? rt.timeoutMs;
+	return {
+		deadlineMs: ms === void 0 ? void 0 : rt.now() + ms,
+		now: rt.now
+	};
+}
+/**
+* A key that names this write.
+*
+* Generated rather than asked for, because a key a caller has to remember is a
+* key most callers will not send, and then the retry they were counting on is
+* the one thing this SDK will not do for them. It is per call and not per
+* attempt: the point is for the second send to be recognisable as the first.
+*/
+function newIdempotencyKey() {
+	return globalThis.crypto?.randomUUID?.() ?? "";
+}
+/** Whether a thrown value is this call being abandoned rather than failing. */
+function isAbort(err, signal) {
+	if (signal?.aborted === true) return true;
+	return err instanceof Error && err.name === "AbortError";
+}
+/**
+* The caller's signal, or a fresh one that also fires when this attempt's share
+* of the budget runs out.
+*/
+function combine(signal, ms) {
+	const timeout = AbortSignal.timeout(ms);
+	return signal === void 0 ? timeout : AbortSignal.any([signal, timeout]);
+}
+//#endregion
+//#region src/session.ts
+/** Thrown when a session has nothing left to present. */
+var NoSessionError = class extends Error {
+	constructor() {
+		super("@rig-ts/client: no session; sign in again");
+		this.name = "NoSessionError";
+	}
+};
+/**
+* A credential that keeps itself fresh.
+*
+* It holds the pair a sign-in returned and exchanges the refresh token before
+* the access token expires, using the leeway in the document's auth profile — so
+* a page open all day makes a handful of refresh calls at moments of its own
+* choosing, rather than discovering the expiry through a failed request in the
+* middle of something.
+*
+* Several calls arriving at an expiry at once take turns: the ones behind find
+* the work already done instead of each spending a rotation. That matters more
+* than it sounds — the server bounds how often a session may rotate, and a
+* client that raced with itself would spend that budget on nothing.
+*/
+var Session = class {
+	tokens;
+	runtime;
+	/**
+	* Held for the length of an exchange, so a hundred callers discovering the
+	* same expiry produce one refresh.
+	*/
+	inFlight;
+	/** Called when a new pair is issued — a place to persist it. */
+	onTokens;
+	constructor(tokens = {}) {
+		this.tokens = tokens;
+	}
+	/** The pair currently held, for a program that stores it between runs. */
+	getTokens() {
+		return this.tokens;
+	}
+	/** Identifies the session, for showing it in a list and revoking it. */
+	get sessionId() {
+		return this.tokens.sessionId ?? "";
+	}
+	/**
+	* Swaps in a newly issued pair, which is what a refresh, a tenant switch and
+	* a password change all produce.
+	*/
+	replace(pair) {
+		this.tokens = pair.refreshToken === void 0 || pair.refreshToken === "" ? {
+			...pair,
+			...this.tokens.refreshToken !== void 0 ? { refreshToken: this.tokens.refreshToken } : {},
+			...this.tokens.refreshExpiresAt !== void 0 ? { refreshExpiresAt: this.tokens.refreshExpiresAt } : {}
+		} : pair;
+		this.onTokens?.(this.tokens);
+	}
+	/** Receives the client this session refreshes through. */
+	bind(runtime) {
+		this.runtime = runtime;
+	}
+	/**
+	* Adds the token, refreshing first if this request might outlive it.
+	*/
+	async apply(headers, signal) {
+		if (this.stale()) await this.exchange(signal);
+		const token = this.tokens.accessToken;
+		if (token === void 0 || token === "") throw new NoSessionError();
+		headers.set("Authorization", `Bearer ${token}`);
+	}
+	/**
+	* A 401 despite a token that looked current is a revoked or invalidated one,
+	* and the refresh token is the only thing left to try.
+	*
+	* It exchanges whatever the expiry says, because the expiry is exactly what
+	* has just been proved wrong.
+	*/
+	async reauthorize(signal) {
+		return await this.exchange(signal);
+	}
+	/** Whether the access token is expired or close enough to it. */
+	stale() {
+		const rt = this.runtime;
+		if (rt === void 0) return false;
+		if (this.tokens.accessToken === void 0 || this.tokens.accessToken === "") return false;
+		const expiresAt = this.tokens.expiresAt;
+		if (expiresAt === void 0) return false;
+		const at = Date.parse(expiresAt);
+		if (Number.isNaN(at)) return false;
+		const leeway = rt.api.auth?.rotationLeewayMs ?? 0;
+		return rt.now() + leeway >= at;
+	}
+	/**
+	* Exchanges the refresh token for a new pair, once however many callers ask.
+	*
+	* Answers false rather than throwing when there is nothing to exchange: a
+	* session that was never signed in leaves the 401 that prompted this as the
+	* answer, which is what the caller needs to see.
+	*/
+	async exchange(signal) {
+		if (this.inFlight !== void 0) return await this.inFlight;
+		const rt = this.runtime;
+		const refreshToken = this.tokens.refreshToken;
+		if (rt === void 0 || refreshToken === void 0 || refreshToken === "") return false;
+		const basePath = rt.api.auth?.basePath ?? "/auth";
+		this.inFlight = (async () => {
+			const pair = await send(rt, {
+				name: "authRefresh",
+				method: "POST",
+				root: true,
+				path: `${basePath}/refresh`,
+				body: { refreshToken }
+			}, {
+				anonymous: true,
+				...signal !== void 0 ? { signal } : {}
+			});
+			if (pair === void 0) return false;
+			this.replace(pair);
+			return true;
+		})().finally(() => {
+			this.inFlight = void 0;
+		});
+		return await this.inFlight;
+	}
+};
+//#endregion
+//#region src/paginate.ts
+/**
+* Walks a paginated read to its end.
+*
+* `fetch` is handed the offset to ask for and returns one page; the limit is
+* whatever the caller's query said, which `fetch` closes over. Iteration stops
+* after the page that reaches the reported total, at the first failure, or when
+* a page comes back empty — that last one is the guard against a server whose
+* total disagrees with what it returns, which would otherwise be an infinite
+* loop rather than a bug report.
+*
+* A failure is thrown, so `for await` reports it where the caller is standing.
+* There is no partial answer: what came before the failure was yielded, and
+* nothing after it is.
+*
+* ```ts
+* for await (const todo of paginate(0, (offset) =>
+*     client.todos.list({ limit: 100, offset }).then(toPage)
+* )) {
+*     …
+* }
+* ```
+*/
+async function* paginate(startOffset, fetch) {
+	let offset = startOffset;
+	for (;;) {
+		const page = await fetch(offset);
+		for (const item of page.items) yield item;
+		if (page.items.length === 0) return;
+		offset += page.items.length;
+		if (offset >= page.total) return;
+	}
+}
+//#endregion
+//#region src/query.ts
+/** Writes one parameter, or nothing when the value is absent. */
+function setParam(query, key, value) {
+	if (value === void 0 || value === null) return;
+	query.set(key, formatParam(value));
+}
+/**
+* Writes a repeated parameter, one key per value.
+*
+* An empty array writes nothing rather than an empty key, for the same reason a
+* single absent value does: the server distinguishes "no filter" from "a filter
+* matching nothing".
+*/
+function setParams(query, key, values) {
+	if (values === void 0 || values === null) return;
+	for (const value of values) query.append(key, formatParam(value));
+}
+/** How one value is written. */
+function formatParam(value) {
+	if (value instanceof Date) return value.toISOString();
+	return String(value);
+}
+/**
+* Escapes a value for a path segment.
+*
+* An identifier that arrived from somewhere else can be anything at all, and a
+* slash in one would otherwise silently address a different route.
+*/
+function pathValue(value) {
+	return encodeURIComponent(value);
+}
+//#endregion
+//#region src/upload.ts
+/** The part the row travels in. The server reads the parts in order and needs
+* the row before it has anywhere to put the bytes. */
+const JSON_PART = "json";
+/**
+* Builds the `multipart/form-data` body rig's upload endpoints take: the row,
+* and the files beside it.
+*
+* It is the shape rig's own endpoints take rather than a general form encoder. A
+* generated method calls it; a caller supplies the {@link Upload}s.
+*
+* `row` is left out entirely when absent, which is what a bare upload does:
+* there is no row to send, only bytes for a row that already exists.
+*
+* An absent upload is left out the same way, so a generated method can name
+* every file column of a create unconditionally. What makes a required one
+* impossible to leave out is the generated shape it arrives in — the member is
+* optional there only where the column is nullable — and not a check here,
+* which would report at runtime what the compiler has already refused.
+*/
+function multipart(row, files) {
+	const form = new FormData();
+	if (row !== void 0) form.append(JSON_PART, new Blob([JSON.stringify(row)], { type: "application/json" }));
+	for (const [field, upload] of files) {
+		if (upload === void 0) continue;
+		const body = upload.contentType === void 0 ? upload.body : new Blob([upload.body], { type: upload.contentType });
+		form.append(field, body, upload.name);
+	}
+	return form;
+}
+//#endregion
+export { DEFAULT_REQUEST_ID_HEADER, DEFAULT_REVISION_HEADER, ErrorCode, FieldCode, METHOD_QUERY, NoSessionError, RigError, Runtime, Session, apiKey, codeOf, fieldsAs, fraction, isConflict, isForbidden, isInvalid, isNotFound, isRateLimited, isReauthorizer, isRigError, isTooLarge, isUnauthorized, isUnsupportedMediaType, isUpgradeRequired, multipart, paginate, pathValue, rateLimitOf, send, sendContent, sendNoContent, sendOptional, setParam, setParams, staticToken, used };