@rebilly/api 0.0.0-stage → 0.1.0

package/dist/runtime/retry.d.ts

@@ -0,0 +1,15 @@
+import { RetryConfig, RetryContext } from './types.ts';
+/**
+ * The default retry predicate: idempotent methods — or any request carrying an
+ * `Idempotency-Key` header, which makes re-sending safe — on a transport error or a
+ * transient status. A custom `retryOn` fully replaces this (no method check kept).
+ */
+export declare function defaultRetryOn(ctx: RetryContext): boolean;
+/**
+ * The delay before the next attempt: a `Retry-After` header (seconds or HTTP-date)
+ * wins; otherwise fixed/exponential backoff over `retryDelay`, with full jitter
+ * unless `jitter === false`.
+ */
+export declare function retryDelay(retry: RetryConfig, attempt: number, retryAfter: string | null): number;
+/** Abort-aware sleep: resolves after `ms`, rejects with the abort reason immediately on abort. */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;

package/dist/runtime/retry.js

@@ -0,0 +1,62 @@
+import { abortError } from "./errors.js";
+//#region src/runtime/retry.ts
+var IDEMPOTENT_METHODS = /* @__PURE__ */ new Set([
+	"GET",
+	"HEAD",
+	"PUT",
+	"DELETE",
+	"OPTIONS"
+]);
+var TRANSIENT_STATUS = /* @__PURE__ */ new Set([
+	408,
+	429,
+	500,
+	502,
+	503,
+	504
+]);
+/**
+* The default retry predicate: idempotent methods — or any request carrying an
+* `Idempotency-Key` header, which makes re-sending safe — on a transport error or a
+* transient status. A custom `retryOn` fully replaces this (no method check kept).
+*/
+function defaultRetryOn(ctx) {
+	if (!(IDEMPOTENT_METHODS.has(ctx.request.method.toUpperCase()) || "Idempotency-Key" in ctx.request.headers || "idempotency-key" in ctx.request.headers)) return false;
+	return ctx.response === void 0 || TRANSIENT_STATUS.has(ctx.response.status);
+}
+/**
+* The delay before the next attempt: a `Retry-After` header (seconds or HTTP-date)
+* wins; otherwise fixed/exponential backoff over `retryDelay`, with full jitter
+* unless `jitter === false`.
+*/
+function retryDelay(retry, attempt, retryAfter) {
+	if (retryAfter) {
+		const seconds = Number(retryAfter);
+		if (!Number.isNaN(seconds)) return seconds * 1e3;
+		const when = Date.parse(retryAfter);
+		if (!Number.isNaN(when)) return Math.max(0, when - Date.now());
+	}
+	const base = retry.retryDelay ?? 1e3;
+	const raw = retry.retryStrategy === "fixed" ? base : base * Math.pow(2, attempt - 1);
+	return retry.jitter === false ? raw : Math.random() * raw;
+}
+/** Abort-aware sleep: resolves after `ms`, rejects with the abort reason immediately on abort. */
+function sleep(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(abortError(signal));
+			return;
+		}
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(abortError(signal));
+		};
+		const timer = setTimeout(() => {
+			if (signal) signal.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		if (signal) signal.addEventListener("abort", onAbort, { once: true });
+	});
+}
+//#endregion
+export { defaultRetryOn, retryDelay, sleep };

package/dist/runtime/send.d.ts

@@ -0,0 +1,35 @@
+import { ClientConfig, Middleware, OperationContext, RequestContext, RequestOptions } from './types.ts';
+/**
+ * Optional behaviors the send core can use but never statically imports — wired by
+ * `createClient` (the same seam the future inline-mode assembler relies on).
+ */
+export type SendCapabilities = {
+    /** Serialize a typed multipart body (a plain object) to FormData. */
+    serializeMultipart?: (body: Record<string, unknown>) => FormData;
+};
+/**
+ * Normalize a caller's `HeadersInit` (plain record, `Headers` instance, or entry pairs)
+ * to a plain record — spreading a `Headers` or an array contributes no entries.
+ */
+export declare function toHeaderRecord(headers: HeadersInit | undefined): Record<string, string>;
+/**
+ * The effective middleware chain for a request: the single `onRequest`/`onResponse`/
+ * `onError` config hooks as one implicit first middleware, then `config.middleware`.
+ */
+export declare function middlewareChain(config: ClientConfig): Middleware[];
+/**
+ * The fetch core shared by every operation: default + config + per-call headers, the
+ * `onRequest` chain (BEFORE body serialization, so mutations are sent), body
+ * serialization (JSON, or FormData via the multipart capability; a stream passes
+ * through in one attempt), the retry loop
+ * (idempotent-only defaults, `Retry-After`, abandoned-body drain), and the reverse
+ * `onResponse` onion, then the `onSettled` chain once with the final outcome. Returns the
+ * final response plus the request context.
+ */
+export declare function send(config: ClientConfig, op: OperationContext, url: string, init: RequestOptions, body: unknown | undefined, bodySpec: {
+    contentType: string;
+    multipart?: boolean;
+} | undefined, caps: SendCapabilities, accept?: string): Promise<{
+    response: Response;
+    context: RequestContext;
+}>;

package/dist/runtime/send.js

@@ -0,0 +1,224 @@
+import { TimeoutError, abortError } from "./errors.js";
+import { defaultRetryOn, retryDelay, sleep } from "./retry.js";
+//#region src/runtime/send.ts
+/**
+* Normalize a caller's `HeadersInit` (plain record, `Headers` instance, or entry pairs)
+* to a plain record — spreading a `Headers` or an array contributes no entries.
+*/
+function toHeaderRecord(headers) {
+	if (headers === void 0) return {};
+	if (headers instanceof Headers) {
+		const record = {};
+		headers.forEach((value, key) => {
+			record[key] = value;
+		});
+		return record;
+	}
+	if (Array.isArray(headers)) return Object.fromEntries(headers);
+	return headers;
+}
+/**
+* The effective middleware chain for a request: the single `onRequest`/`onResponse`/
+* `onError` config hooks as one implicit first middleware, then `config.middleware`.
+*/
+function middlewareChain(config) {
+	return [...config.onRequest || config.onResponse || config.onError ? [{
+		onRequest: config.onRequest,
+		onResponse: config.onResponse,
+		onError: config.onError
+	}] : [], ...config.middleware ?? []];
+}
+/**
+* `AbortSignal.timeout()` where the platform has it, else an `AbortController` armed by
+* `setTimeout`: Chrome before 103, Safari before 16, and Firefox before 100 lack the
+* static, and every request with a timeout would throw before `fetch` runs.
+*/
+function timeoutSignal(ms) {
+	if (typeof AbortSignal.timeout === "function") return AbortSignal.timeout(ms);
+	const controller = new AbortController();
+	setTimeout(() => {
+		controller.abort(new DOMException(`Timed out after ${ms} ms`, "TimeoutError"));
+	}, ms);
+	return controller.signal;
+}
+/**
+* `AbortSignal.any()` where the platform has it, else a controller that follows whichever
+* signal aborts first: Chrome before 116, Safari before 17.4, and Firefox before 124 lack
+* the static. The listeners come off once one signal fires, so a caller's long-lived
+* signal does not keep one per request.
+*/
+function anySignal(signals) {
+	if (typeof AbortSignal.any === "function") return AbortSignal.any(signals);
+	const controller = new AbortController();
+	const listeners = /* @__PURE__ */ new Map();
+	const abort = (reason) => {
+		for (const [signal, listener] of listeners) signal.removeEventListener("abort", listener);
+		controller.abort(reason);
+	};
+	for (const signal of signals) {
+		const listener = () => abort(signal.reason);
+		listeners.set(signal, listener);
+		signal.addEventListener("abort", listener);
+	}
+	return controller.signal;
+}
+/**
+* The fetch core shared by every operation: default + config + per-call headers, the
+* `onRequest` chain (BEFORE body serialization, so mutations are sent), body
+* serialization (JSON, or FormData via the multipart capability; a stream passes
+* through in one attempt), the retry loop
+* (idempotent-only defaults, `Retry-After`, abandoned-body drain), and the reverse
+* `onResponse` onion, then the `onSettled` chain once with the final outcome. Returns the
+* final response plus the request context.
+*/
+async function send(config, op, url, init, body, bodySpec, caps, accept = "application/json") {
+	const { retry: callRetry, timeout: callTimeout, idempotencyKey: callKey, ...fetchInit } = init;
+	const retry = {
+		...config.retry,
+		...callRetry
+	};
+	const timeout = callTimeout ?? config.timeout;
+	const idempotency = callKey ?? config.idempotencyKey;
+	const headers = {
+		Accept: accept,
+		...typeof config.headers === "function" ? await config.headers() : config.headers,
+		...toHeaderRecord(fetchInit.headers)
+	};
+	const method = (fetchInit.method ?? "GET").toUpperCase();
+	if (idempotency !== void 0 && idempotency !== false && (method === "POST" || method === "PATCH") && !("Idempotency-Key" in headers) && !("idempotency-key" in headers)) headers["Idempotency-Key"] = typeof idempotency === "string" ? idempotency : typeof idempotency === "function" ? idempotency() : crypto.randomUUID();
+	if (typeof config.clientHeader === "string" && typeof document === "undefined" && !("X-Redocly-Client" in headers) && !("x-redocly-client" in headers)) headers["X-Redocly-Client"] = config.clientHeader;
+	const context = {
+		url,
+		method: fetchInit.method ?? "GET",
+		headers,
+		body,
+		operation: op
+	};
+	const middleware = middlewareChain(config);
+	for (const mw of middleware) if (mw.onRequest) await mw.onRequest(context);
+	let payload;
+	let isStream = false;
+	if (context.body !== void 0) {
+		const value = context.body;
+		const isBinary = value instanceof Blob || value instanceof ArrayBuffer || ArrayBuffer.isView(value);
+		const isFormData = typeof FormData !== "undefined" && value instanceof FormData;
+		const isURLSearchParams = value instanceof URLSearchParams;
+		isStream = typeof ReadableStream !== "undefined" && value instanceof ReadableStream || value !== null && typeof value[Symbol.asyncIterator] === "function";
+		const hasContentType = "Content-Type" in context.headers || "content-type" in context.headers;
+		if (isFormData || isURLSearchParams || isBinary || isStream || typeof value === "string") {
+			payload = value;
+			const declared = bodySpec?.contentType;
+			if (!isFormData && !isURLSearchParams && !hasContentType && declared !== void 0 && !declared.toLowerCase().includes("multipart")) context.headers["Content-Type"] = declared;
+		} else if (bodySpec?.multipart === true) {
+			if (!caps.serializeMultipart) throw new Error("Multipart capability not wired: cannot serialize the request body");
+			payload = caps.serializeMultipart(value);
+		} else {
+			payload = JSON.stringify(value);
+			if (!hasContentType) context.headers["Content-Type"] = bodySpec?.contentType ?? "application/json";
+		}
+	}
+	const doFetch = config.fetch ?? fetch;
+	const maxAttempts = isStream ? 1 : 1 + (retry.retries ?? 0);
+	const retryOn = retry.retryOn ?? defaultRetryOn;
+	const signal = fetchInit.signal ?? void 0;
+	const startedAt = Date.now();
+	let attempt = 0;
+	let finalResponse;
+	let lastResponse;
+	try {
+		while (true) {
+			if (signal?.aborted) throw abortError(signal);
+			attempt++;
+			const budget = timeout ? timeoutSignal(timeout) : void 0;
+			const attemptSignal = budget && signal ? anySignal([signal, budget]) : budget ?? signal;
+			let response;
+			try {
+				response = await doFetch(context.url, {
+					...fetchInit,
+					...isStream ? { duplex: "half" } : {},
+					signal: attemptSignal,
+					method: context.method,
+					headers: context.headers,
+					body: payload
+				});
+			} catch (error) {
+				const timedOut = timeout !== void 0 && budget?.aborted && !signal?.aborted;
+				if (attempt < maxAttempts && !signal?.aborted && await retryOn({
+					attempt,
+					request: context,
+					error
+				})) {
+					await sleep(retryDelay(retry, attempt, null), signal);
+					continue;
+				}
+				if (timedOut) throw new TimeoutError(op.id, timeout, attempt);
+				throw error;
+			}
+			lastResponse = response;
+			for (let i = middleware.length - 1; i >= 0; i--) {
+				const onResponse = middleware[i].onResponse;
+				if (onResponse) {
+					const replaced = await onResponse(response, context);
+					if (replaced && replaced !== response) {
+						await response.body?.cancel().catch(() => void 0);
+						response = replaced;
+						lastResponse = replaced;
+					}
+				}
+			}
+			if (!response.ok && attempt < maxAttempts && !signal?.aborted && await retryOn({
+				attempt,
+				request: context,
+				response
+			})) {
+				const retryAfter = response.headers.get("retry-after");
+				await response.body?.cancel().catch(() => void 0);
+				lastResponse = void 0;
+				await sleep(retryDelay(retry, attempt, retryAfter), signal);
+				continue;
+			}
+			finalResponse = response;
+			break;
+		}
+	} catch (error) {
+		const settled = {
+			response: lastResponse,
+			error,
+			attempts: attempt,
+			durationMs: Date.now() - startedAt
+		};
+		for (const mw of middleware) {
+			if (!mw.onSettled) continue;
+			try {
+				await mw.onSettled(context, settled);
+			} catch (hookError) {
+				globalThis.console?.warn("onSettled hook failed", hookError);
+			}
+		}
+		throw error;
+	}
+	const settled = {
+		response: finalResponse,
+		attempts: attempt,
+		durationMs: Date.now() - startedAt
+	};
+	const hookErrors = [];
+	for (const mw of middleware) {
+		if (!mw.onSettled) continue;
+		try {
+			await mw.onSettled(context, settled);
+		} catch (hookError) {
+			hookErrors.push(hookError);
+		}
+	}
+	if (hookErrors.length > 0) {
+		await finalResponse.body?.cancel().catch(() => void 0);
+		throw hookErrors[0];
+	}
+	return {
+		response: finalResponse,
+		context
+	};
+}
+//#endregion
+export { middlewareChain, send, toHeaderRecord };