@bedrock-rbx/ocale 0.1.0-beta.9 → 0.1.1

package/dist/resource-client-CIAkS2xQ.mjs

@@ -0,0 +1,960 @@
+import { n as NetworkError, r as ApiError, t as RateLimitError } from "./rate-limit-Dh2leqaB.mjs";
+import { a as defaultRetryDelay, i as computeRetryWaitMs, l as PermissionError, n as IDEMPOTENT_METHOD_DEFAULTS, o as mergeConfig, s as shouldRetry } from "./retry-BvZRZDXs.mjs";
+import { setTimeout } from "node:timers/promises";
+//#region src/internal/utils/is-date-time-string.ts
+/**
+* Narrows `value` to a string that parses to a real {@link Date} via the
+* `Date(string)` constructor. Used by resource parsers to gate
+* `format: date-time` wire fields before handing them to `new Date(...)`,
+* which silently produces an `Invalid Date` for invalid input.
+*
+* @param value - The unknown wire value to validate.
+* @returns `true` when `value` is a string and `new Date(value).getTime()`
+*   is not `NaN`.
+*/
+function isDateTimeString(value) {
+	if (typeof value !== "string") return false;
+	const parsed = new Date(value);
+	return !Number.isNaN(parsed.getTime());
+}
+//#endregion
+//#region src/internal/utils/is-record.ts
+/**
+* Narrows `value` to a plain JSON-style record. Excludes arrays, class
+* instances, primitives, and `null`/`undefined`. Used by resource
+* parsers to gate property access on wire bodies whose shape isn't
+* known at compile time.
+*
+* @param value - The unknown value to narrow.
+* @returns `true` when `value` is a plain `[object Object]`.
+*/
+function isRecord(value) {
+	return Object.prototype.toString.call(value) === "[object Object]";
+}
+//#endregion
+//#region src/internal/http/budget-tracker.ts
+const MS_PER_SECOND = 1e3;
+/**
+* Tracks the live rate-limit budget for a single scope. Primed by `observe`
+* from response headers and drawn down by `reserve` as requests leave, so
+* `waitMs` can pace requests across the window.
+*
+* Pacing has two regimes. While budget remains, requests are spread evenly over
+* the time left in the window (`timeLeft / remaining`), so a burst does not
+* spend the whole window's budget up front and then stall. Once the budget is
+* spent, requests hold until the window resets. Budget and reset time move
+* together as one window, so the tracker is either unprimed or fully primed,
+* never half-known.
+*/
+var BudgetTracker = class {
+	/** Time (ms) the most recent request was allowed out, for spacing. */
+	#lastAllowedAt = void 0;
+	#window = void 0;
+	/**
+	* Folds a fresh server reading in, replacing any prior window. The latest
+	* reading wins: observe time is monotonic, so the most recently resolved
+	* response is the best current estimate. The spacing reference is left
+	* untouched so a window refresh does not reset pacing mid-stream.
+	*
+	* @param sample - Parsed `remaining`/`resetSeconds` from a response.
+	* @param now - The current time in ms.
+	*/
+	observe(sample, now) {
+		this.#window = {
+			predictedRemaining: sample.remaining,
+			resetAt: now + sample.resetSeconds * MS_PER_SECOND
+		};
+	}
+	/**
+	* Accounts for one request leaving at `now`: records the spacing reference
+	* and decrements the prediction. A no-op on the prediction while unprimed.
+	*
+	* @param now - The time the request was allowed out, in ms.
+	*/
+	reserve(now) {
+		this.#lastAllowedAt = now;
+		if (this.#window !== void 0) this.#window = {
+			...this.#window,
+			predictedRemaining: this.#window.predictedRemaining - 1
+		};
+	}
+	/**
+	* Milliseconds to wait before the next request is allowed.
+	*
+	* @param now - The current time in ms.
+	* @returns `0` when a request may go now (unprimed, or the first paced send);
+	*   the time until reset when the budget is spent; otherwise the time until
+	*   this request's evenly-spaced slot.
+	*/
+	waitMs(now) {
+		if (this.#window === void 0) return 0;
+		const { predictedRemaining, resetAt } = this.#window;
+		if (predictedRemaining <= 0) return Math.max(0, resetAt - now);
+		if (this.#lastAllowedAt === void 0) return 0;
+		const interval = (resetAt - now) / predictedRemaining;
+		return Math.max(0, this.#lastAllowedAt + interval - now);
+	}
+};
+//#endregion
+//#region src/internal/http/budget-gate.ts
+/**
+* Header-primed rate-limit gate shared across a client. Holds one
+* {@link BudgetTracker} per API key, since the tightest Roblox window is the
+* per-key one shared across every operation. Before each request the caller
+* gates on the request's key (sleeping if its budget is spent), and after each
+* response folds the parsed sample back in, so a sibling operation on the same
+* key can head off a 429 the static per-operation token bucket cannot foresee.
+* A per-operation tracker is deliberately not kept: every operation reports the
+* same most-constrained `remaining`, so a per-key tracker (drawn down by all
+* operations) is always the binding constraint.
+*
+* Gating is serialized per scope through a promise chain so concurrent
+* requests on one key cannot read the same budget and reserve the same slot;
+* each waits for the prior gate's reserve before computing its own.
+*/
+var BudgetGate = class {
+	#chains = /* @__PURE__ */ new Map();
+	#sleep;
+	#trackers = /* @__PURE__ */ new Map();
+	/**
+	* Creates a gate bound to an injectable sleep.
+	*
+	* @param sleep - Injectable sleep (tests pass a fake clock).
+	*/
+	constructor(sleep) {
+		this.#sleep = sleep;
+	}
+	/**
+	* Holds until the scope's budget permits a send, then reserves one slot.
+	* Runs after the prior gate on the same scope settles, whether it resolved
+	* or rejected, so one failed attempt cannot poison later gates on the key.
+	*
+	* @param scope - The scope key to gate on (the effective API key).
+	*/
+	async gate(scope) {
+		const previous = this.#chains.get(scope) ?? Promise.resolve();
+		const runGate = async () => this.#gateOnce(scope);
+		const mine = previous.then(runGate, runGate);
+		this.#chains.set(scope, mine);
+		await mine;
+	}
+	/**
+	* Folds a response's parsed budget back onto the scope. A `undefined`
+	* sample (headers absent or non-numeric) is ignored, leaving the scope on
+	* static pacing.
+	*
+	* @param scope - The same scope key passed to {@link gate}.
+	* @param sample - Parsed sample, or `undefined` when none was reported.
+	*/
+	observe(scope, sample) {
+		if (sample === void 0) return;
+		this.#tracker(scope).observe(sample, Date.now());
+	}
+	async #gateOnce(scope) {
+		const tracker = this.#tracker(scope);
+		const waitMs = tracker.waitMs(Date.now());
+		if (waitMs > 0) await this.#sleep(waitMs);
+		tracker.reserve(Date.now());
+	}
+	#tracker(scope) {
+		const existing = this.#trackers.get(scope);
+		if (existing !== void 0) return existing;
+		const tracker = new BudgetTracker();
+		this.#trackers.set(scope, tracker);
+		return tracker;
+	}
+};
+//#endregion
+//#region src/internal/http/execute.ts
+/**
+* Retry-aware orchestration loop. Coordinates a single logical request,
+* looping over `options.send` until it succeeds, the error is non-retryable,
+* or `options.config.maxRetries` is exhausted. Fires observability hooks
+* at each transition. Domain- and queue-agnostic: `send` may be any
+* callback, including one wrapped by a rate-limit queue.
+*
+* @param request - The immutable request to send.
+* @param options - The transport callback, resolved config, hooks, and sleep.
+* @returns The first success, or the final error after retries are exhausted.
+*/
+async function executeWithRetry(request, options) {
+	const { config, hooks, send, sleep } = options;
+	async function attempt() {
+		hooks.onRequest?.(request);
+		return send(request);
+	}
+	let result = await attempt();
+	for (let retry = 0; retry < config.maxRetries; retry++) {
+		if (result.success || !shouldRetry(result.err, config)) return result;
+		const { err } = result;
+		hooks.onRetry?.(retry + 1, err);
+		const waitMs = computeRetryWaitMs(err, {
+			attempt: retry,
+			retryDelay: config.retryDelay
+		});
+		hooks.onRateLimit?.(waitMs);
+		await sleep(waitMs);
+		result = await attempt();
+	}
+	return result;
+}
+//#endregion
+//#region src/internal/http/rate-limit-sample.ts
+/**
+* Reduces a comma-separated rate-limit header value (e.g. `"0, 70000"`) to a
+* single non-negative integer via `combine`. Tokens are trimmed; blank and
+* non-finite tokens (`""`, `"Infinity"`, `"abc"`) are dropped so a stray value
+* cannot corrupt the result. Returns `undefined` when the header is absent or
+* has no finite tokens.
+*
+* @param headerValue - The raw header value, or `undefined` if missing.
+* @param combine - Pairwise reducer, `Math.min` for remaining, `Math.max` for reset.
+* @returns The reduced, floored, clamped value, or `undefined`.
+*/
+function reduceRateLimitTokens(headerValue, combine) {
+	if (headerValue === void 0) return;
+	const tokens = headerValue.split(",").map((part) => part.trim()).filter((part) => part !== "").map((part) => Number(part)).filter((value) => Number.isFinite(value));
+	if (tokens.length === 0) return;
+	return Math.max(0, Math.floor(tokens.reduce(combine)));
+}
+/**
+* Parses the `x-ratelimit-remaining` and `x-ratelimit-reset` response headers
+* into a {@link RateLimitSample}. Each header may carry a comma-separated list
+* of per-window values; `remaining` takes the smallest (most constrained) and
+* `resetSeconds` takes the largest (longest wait), symmetric to how a 429's
+* retry delay is reduced. Returns `undefined` when either header is missing or
+* has no finite numeric tokens, so a caller can fall back to static pacing.
+*
+* @param headers - Response headers with lowercased keys.
+* @returns The parsed sample, or `undefined` when the budget cannot be read.
+*/
+function parseRateLimitHeaders(headers) {
+	const remaining = reduceRateLimitTokens(headers["x-ratelimit-remaining"], (a, b) => Math.min(a, b));
+	const resetSeconds = reduceRateLimitTokens(headers["x-ratelimit-reset"], (a, b) => Math.max(a, b));
+	if (remaining === void 0 || resetSeconds === void 0) return;
+	return {
+		remaining,
+		resetSeconds
+	};
+}
+//#endregion
+//#region src/internal/http/rate-limit-observation.ts
+/**
+* Extracts a {@link RateLimitSample} from a transport result so the budget gate
+* can be fed from every attempt. A 2xx carries the budget in its headers; a 429
+* carries it on the {@link RateLimitError} (the raw headers are dropped before
+* this point). Any other error, or a response that reported no budget, yields
+* `undefined` and leaves the gate on static pacing.
+*
+* @param result - The classified transport result for one attempt.
+* @returns The parsed sample, or `undefined` when none was reported.
+*/
+function rateLimitSampleFromResult(result) {
+	if (result.success) return parseRateLimitHeaders(result.data.headers);
+	const { err } = result;
+	if (err instanceof RateLimitError && err.remaining !== void 0) return {
+		remaining: err.remaining,
+		resetSeconds: err.retryAfterSeconds
+	};
+}
+//#endregion
+//#region src/internal/http/rate-limit-queue.ts
+/**
+* Token-bucket rate limiter for a single `(apiKey, operation)` pair. Every
+* call to `acquire` consumes one token; when the bucket is empty the call
+* waits until a token regenerates before invoking the task. Burst capacity
+* equals `maxPerSecond`, refilling at `maxPerSecond` tokens per second.
+*
+* Implemented as a leaky bucket tracking drain debt in ms. `#lastCheck`
+* advances by `waitMs` after every sleep so the algorithm stays correct
+* whether or not the injected sleep moves `Date.now()` forward.
+*/
+var RateLimitQueue = class {
+	#hooks;
+	#intervalMs;
+	#maxBucketLevel;
+	#sleep;
+	#bucketLevel = 0;
+	#chain = Promise.resolve();
+	#lastCheck = Date.now();
+	/**
+	* Creates a rate-limit queue bound to a single operation.
+	*
+	* @param limit - The operation key and its per-second request ceiling.
+	* @param hooks - Observability callbacks; `onRateLimit` fires when the
+	*   bucket is empty and a sleep is about to start.
+	* @param sleep - Injectable sleep (tests pass a fake).
+	*/
+	constructor(limit, hooks, sleep) {
+		this.#intervalMs = 1e3 / limit.maxPerSecond;
+		this.#maxBucketLevel = limit.maxPerSecond * this.#intervalMs;
+		this.#hooks = hooks;
+		this.#sleep = sleep;
+	}
+	/**
+	* Waits for a token — sleeping and firing `hooks.onRateLimit` if the
+	* bucket is empty — then executes `task`. Concurrent callers are
+	* serialized at token acquisition; tasks themselves run independently
+	* once their token is secured.
+	*
+	* @param task - The request to run once a token is available.
+	* @returns The value produced by `task`.
+	*/
+	async acquire(task) {
+		const myTurn = this.#chain.then(async () => this.#waitForToken());
+		this.#chain = myTurn;
+		await myTurn;
+		return task();
+	}
+	async #waitForToken() {
+		const now = Math.max(Date.now(), this.#lastCheck);
+		const drained = Math.max(0, this.#bucketLevel - (now - this.#lastCheck));
+		this.#lastCheck = now;
+		if (drained + this.#intervalMs <= this.#maxBucketLevel) {
+			this.#bucketLevel = drained + this.#intervalMs;
+			return;
+		}
+		const waitMs = drained + this.#intervalMs - this.#maxBucketLevel;
+		this.#hooks.onRateLimit?.(waitMs);
+		await this.#sleep(waitMs);
+		this.#bucketLevel = this.#maxBucketLevel;
+		this.#lastCheck = now + waitMs;
+	}
+};
+//#endregion
+//#region src/internal/utils/try-catch.ts
+/**
+* Wraps a promise into a {@link Result}, catching rejections.
+*
+* @template T - The resolved value type.
+* @param promise - The promise to wrap.
+* @returns A Result containing the resolved value or the rejection error.
+*/
+async function tryCatch(promise) {
+	try {
+		return {
+			data: await promise,
+			success: true
+		};
+	} catch (err) {
+		return {
+			err: err instanceof Error ? err : new Error(String(err)),
+			success: false
+		};
+	}
+}
+//#endregion
+//#region src/internal/http/diagnostics.ts
+const DIAGNOSTIC_HEADER_ALLOWLIST = new Set([
+	"cf-ray",
+	"server",
+	"via",
+	"x-request-id"
+]);
+const DIAGNOSTIC_HEADER_PREFIX = "x-roblox-";
+const TITLE_PATTERN = /<title[^>]*>([\S\s]*?)<\/title>/i;
+const H1_PATTERN = /<h1[^>]*>([\S\s]*?)<\/h1>/i;
+const TAG_PATTERN = /<[^>]*>/g;
+const WHITESPACE_PATTERN = /\s+/g;
+/**
+* Extracts a one-line human summary from an HTML gateway error page, or returns
+* `undefined` when the body is not such a page. A load balancer (HAProxy-style)
+* rejects a request before it reaches Open Cloud and answers with an HTML page,
+* not a JSON Open Cloud error; dumping that HTML whole is noise. The body is
+* treated as HTML when the content-type is `text/html` or the trimmed body is
+* tag-led (`<html`/`<!doctype html`), and the summary is taken from the
+* `<title>` (falling back to the first `<h1>`), tags stripped and whitespace
+* collapsed.
+*
+* @param contentType - The response `content-type` header, if present.
+* @param rawText - The raw response body text.
+* @returns The extracted summary, or `undefined` when the body is not an HTML
+*   gateway page (or carries no title/h1 text).
+*/
+function extractGatewaySummary(contentType, rawText) {
+	if (!isHtmlBody(contentType, rawText)) return;
+	return firstTagText(rawText, TITLE_PATTERN) ?? firstTagText(rawText, H1_PATTERN);
+}
+/**
+* Filters a lowercased header record down to the diagnostic allowlist: a few
+* named escalation headers plus any `x-roblox-*` header. Keeps errors light and
+* avoids retaining anything sensitive from the full response header set.
+*
+* @param headers - The full header record (lowercased keys).
+* @returns A record containing only the allowlisted headers that were present.
+*/
+function pickDiagnosticHeaders(headers) {
+	const picked = {};
+	for (const [name, value] of Object.entries(headers)) if (DIAGNOSTIC_HEADER_ALLOWLIST.has(name) || name.startsWith(DIAGNOSTIC_HEADER_PREFIX)) picked[name] = value;
+	return picked;
+}
+function firstTagText(html, pattern) {
+	const inner = pattern.exec(html)?.[1];
+	if (inner === void 0) return;
+	const text = inner.replace(TAG_PATTERN, " ").replace(WHITESPACE_PATTERN, " ").trim();
+	return text === "" ? void 0 : text;
+}
+function isHtmlBody(contentType, rawText) {
+	if (contentType?.toLowerCase().includes("text/html") === true) return true;
+	const head = rawText.trimStart().toLowerCase();
+	return head.startsWith("<html") || head.startsWith("<!doctype html");
+}
+//#endregion
+//#region src/internal/http/fetch-client.ts
+const MAX_DETAIL_LENGTH = 500;
+const CONTENT_TYPE_HEADER = "content-type";
+/**
+* Converts a `Headers` object to a plain record with lowercased keys.
+*
+* @param headers - The `Headers` instance to convert.
+* @returns A record mapping lowercased header names to their values.
+*/
+function headersToRecord(headers) {
+	return Object.fromEntries(headers);
+}
+/**
+* Permissively extracts a machine-readable error code from a response body.
+*
+* Modern Open Cloud responses use `{ errorCode: string, message: string }`;
+* the legacy game-internationalization endpoints use
+* `{ errors: [{ code: number, message: string }, ...] }`. Both shapes are
+* checked; numeric legacy codes are returned as strings so callers see one
+* consistent type.
+*
+* @param body - The parsed response body (unknown shape).
+* @returns The error code if present, otherwise `undefined`.
+*/
+function extractErrorCode(body) {
+	if (body === null || typeof body !== "object") return;
+	const errorCode = Reflect.get(body, "errorCode");
+	if (typeof errorCode === "string") return errorCode;
+	return extractLegacyCode(body);
+}
+/**
+* Permissively extracts a human-readable error message from a response body.
+*
+* Modern Open Cloud responses expose `message` at the top level; the legacy
+* game-internationalization endpoints nest it under `errors[0].message`.
+*
+* @param body - The parsed response body (unknown shape).
+* @returns The message if present, otherwise `undefined`.
+*/
+function extractErrorMessage(body) {
+	if (body === null || typeof body !== "object") return;
+	const message = Reflect.get(body, "message");
+	if (typeof message === "string") return message;
+	return extractLegacyMessage(body);
+}
+/**
+* Parses the `x-ratelimit-reset` header value into seconds. On a 429 the header
+* is a comma-separated list of per-window reset times (e.g. `"22, 0"`, one entry
+* per rate-limit window); the largest value is the longest-resetting window and
+* the only safe wait that won't retry into a still-exhausted window. A single
+* value is treated as a one-element list.
+*
+* @param headerValue - The raw header value, or `undefined` if missing.
+* @returns The number of seconds to wait, or 0 if missing/invalid.
+*/
+function parseRetryAfterSeconds(headerValue) {
+	return reduceRateLimitTokens(headerValue, (a, b) => Math.max(a, b)) ?? 0;
+}
+/**
+* Joins the base URL from config with the relative path from the request.
+*
+* @param request - The HTTP request containing the relative URL.
+* @param config - The request config containing the base URL.
+* @returns The fully-qualified URL string.
+*/
+function buildUrl(request, config) {
+	return `${config.baseUrl.endsWith("/") ? config.baseUrl.slice(0, -1) : config.baseUrl}${request.url}`;
+}
+/**
+* Constructs the `RequestInit` options for a `fetch` call.
+*
+* @param request - The HTTP request to build options for.
+* @param config - The request config containing API key and timeout.
+* @returns A `RequestInit` object ready for `fetch`.
+*/
+function buildFetchOptions(request, config) {
+	const headers = new Headers({ "x-api-key": config.apiKey });
+	const options = {
+		headers,
+		method: request.method
+	};
+	if (request.body instanceof FormData) options.body = request.body;
+	else if (request.body instanceof Uint8Array) {
+		headers.set(CONTENT_TYPE_HEADER, "application/octet-stream");
+		options.body = request.body;
+	} else if (request.body !== void 0) {
+		headers.set(CONTENT_TYPE_HEADER, "application/json");
+		options.body = JSON.stringify(request.body);
+	}
+	if (request.headers !== void 0) for (const [name, value] of Object.entries(request.headers)) {
+		if (name.toLowerCase() === "x-api-key") continue;
+		headers.set(name, value);
+	}
+	if (config.timeout !== void 0) options.signal = AbortSignal.timeout(config.timeout);
+	return options;
+}
+/**
+* Creates an {@link HttpClient} backed by the Fetch API.
+*
+* @param fetchFunc - The fetch implementation to use. Defaults to `globalThis.fetch`.
+* @param now - Monotonic-ish clock used to measure request elapsed time.
+*   Defaults to `Date.now`; injectable so tests can assert a fixed duration.
+* @returns An HttpClient that classifies responses into typed Results.
+*/
+function createFetchHttpClient(fetchFunc = globalThis.fetch, now = Date.now) {
+	return { async request(httpRequest, config) {
+		const url = buildUrl(httpRequest, config);
+		const options = buildFetchOptions(httpRequest, config);
+		const target = {
+			method: httpRequest.method,
+			url
+		};
+		const { elapsedMs, fetchResult } = await timedFetch(now, async () => fetchFunc(url, options));
+		if (!fetchResult.success) return {
+			err: networkError(fetchResult.err, target),
+			success: false
+		};
+		const context = {
+			elapsedMs,
+			method: target.method,
+			url: target.url
+		};
+		const classified = await tryCatch(classifyResponse(fetchResult.data, context));
+		if (!classified.success) return {
+			err: networkError(classified.err, target),
+			success: false
+		};
+		return classified.data;
+	} };
+}
+function readLegacyErrorEntry(body) {
+	const errors = Reflect.get(body, "errors");
+	if (!Array.isArray(errors)) return;
+	const [first] = errors;
+	if (typeof first !== "object" || first === null) return;
+	return first;
+}
+function extractLegacyCode(body) {
+	const first = readLegacyErrorEntry(body);
+	if (first === void 0) return;
+	const code = Reflect.get(first, "code");
+	if (typeof code === "string") return code;
+	return typeof code === "number" ? String(code) : void 0;
+}
+function extractLegacyMessage(body) {
+	const first = readLegacyErrorEntry(body);
+	if (first === void 0) return;
+	const message = Reflect.get(first, "message");
+	return typeof message === "string" ? message : void 0;
+}
+/**
+* Runs `send` and reports both its Result and how long it was in flight,
+* measured with `now`. Isolated so the timing start need not sit in the request
+* body ahead of the transport-failure early return.
+*
+* @param now - The clock used to bound the call.
+* @param send - A thunk that issues the fetch.
+* @returns The fetch Result and the elapsed milliseconds.
+*/
+async function timedFetch(now, send) {
+	const start = now();
+	const fetchResult = await tryCatch(send());
+	return {
+		elapsedMs: Math.max(0, now() - start),
+		fetchResult
+	};
+}
+function networkError(cause, target) {
+	return new NetworkError("Network request failed", {
+		cause,
+		method: target.method,
+		url: target.url
+	});
+}
+function formatApiErrorMessage(parts) {
+	const { code, message, status } = parts;
+	const base = `HTTP ${status}`;
+	if (message === void 0 && code === void 0) return base;
+	if (message === void 0) return `${base} (code ${code})`;
+	if (code === void 0) return `${base}: ${message}`;
+	return `${base}: ${message} (code ${code})`;
+}
+/**
+* Projects a read body to the detail carried on an error: the parsed JSON when
+* it parsed, otherwise the raw text truncated to {@link MAX_DETAIL_LENGTH}.
+*
+* @param text - The raw response body text.
+* @param parsed - The best-effort parse result from {@link readResponseBody}.
+* @returns The parsed body, or the truncated raw text on a parse failure.
+*/
+function bodyDetail(text, parsed) {
+	return parsed.success ? parsed.data : text.slice(0, MAX_DETAIL_LENGTH);
+}
+function createApiError(args) {
+	const { context, rawText, response } = args;
+	const { status } = response;
+	const headers = headersToRecord(response.headers);
+	const requestContext = {
+		elapsedMs: context.elapsedMs,
+		method: context.method,
+		responseHeaders: pickDiagnosticHeaders(headers),
+		statusCode: status,
+		url: context.url
+	};
+	const gatewaySummary = extractGatewaySummary(headers[CONTENT_TYPE_HEADER], rawText);
+	if (gatewaySummary !== void 0) return new ApiError(`HTTP ${status}`, {
+		...requestContext,
+		gatewaySummary
+	});
+	const body = bodyDetail(rawText, args.parsed);
+	const code = extractErrorCode(body);
+	return new ApiError(formatApiErrorMessage({
+		code,
+		message: extractErrorMessage(body),
+		status
+	}), {
+		...requestContext,
+		code,
+		details: body
+	});
+}
+/**
+* Parses response text as JSON, returning the underlying `SyntaxError` on
+* failure rather than throwing. The synchronous sibling of {@link tryCatch}.
+*
+* @param text - The raw response body text.
+* @returns A Result wrapping the parsed value, or the parse error.
+*/
+function parseJson(text) {
+	try {
+		return {
+			data: JSON.parse(text),
+			success: true
+		};
+	} catch (err) {
+		return {
+			err: err instanceof Error ? err : new Error(String(err)),
+			success: false
+		};
+	}
+}
+/**
+* Reads a response body once and parses it best-effort: an empty body is a
+* successful `undefined`, otherwise the JSON parse result (which carries the
+* `SyntaxError` on failure). Returns the raw `text` alongside so callers that
+* need the original bytes (parse-failure diagnostics) do not re-read the
+* consumed stream.
+*
+* @param response - The Response whose body to read.
+* @returns The parse result and the raw text.
+*/
+async function readResponseBody(response) {
+	const text = await response.text();
+	return {
+		parsed: text === "" ? {
+			data: void 0,
+			success: true
+		} : parseJson(text),
+		text
+	};
+}
+async function createRateLimitError(response) {
+	const headers = headersToRecord(response.headers);
+	const { parsed, text } = await readResponseBody(response);
+	return new RateLimitError("Rate limited", {
+		details: bodyDetail(text, parsed),
+		remaining: reduceRateLimitTokens(headers["x-ratelimit-remaining"], (a, b) => Math.min(a, b)),
+		retryAfterSeconds: parseRetryAfterSeconds(headers["x-ratelimit-reset"]),
+		statusCode: response.status
+	});
+}
+/**
+* Builds the error for a 2xx response whose body could not be parsed as JSON,
+* preserving the parse `cause`, the (truncated) raw body, and the declared
+* content-type so the failure can be diagnosed after the fact.
+*
+* @param args - The Response, raw body text, and underlying parse error.
+* @returns An ApiError carrying the diagnostic context.
+*/
+function parseFailureError({ cause, response, text }) {
+	return new ApiError(`Failed to parse response body (content-type: ${response.headers.get(CONTENT_TYPE_HEADER) ?? "unknown"})`, {
+		cause,
+		details: text.slice(0, MAX_DETAIL_LENGTH),
+		statusCode: response.status
+	});
+}
+/**
+* Classifies a fetch `Response` into a typed `Result`.
+*
+* The body is read once and parsed best-effort. Error responses (status >= 300)
+* never require valid JSON: an error body that is not valid JSON degrades to a
+* status-based {@link ApiError} carrying the raw text, and an HTML gateway page
+* is summarized rather than dumped. A parse failure is only fatal on a 2xx,
+* where a parseable body is part of the contract.
+*
+* @param response - The raw fetch Response to classify.
+* @param context - The request context (method, url, elapsed time) threaded
+*   onto any {@link ApiError} built for an error response.
+* @returns A Result containing an HttpResponse on success or an OpenCloudError on failure.
+*/
+async function classifyResponse(response, context) {
+	if (response.status === 429) return {
+		err: await createRateLimitError(response),
+		success: false
+	};
+	const { parsed, text } = await readResponseBody(response);
+	if (response.status >= 300) return {
+		err: createApiError({
+			context,
+			parsed,
+			rawText: text,
+			response
+		}),
+		success: false
+	};
+	if (!parsed.success) return {
+		err: parseFailureError({
+			cause: parsed.err,
+			response,
+			text
+		}),
+		success: false
+	};
+	return {
+		data: {
+			body: parsed.data,
+			headers: headersToRecord(response.headers),
+			status: response.status
+		},
+		success: true
+	};
+}
+//#endregion
+//#region src/internal/http/resolve-dependencies.ts
+/**
+* Resolves the concrete HTTP client and sleep implementation a resource
+* client should use. Falls back to the fetch-backed HTTP client and the
+* default `setTimeout`-based sleep when the caller omits the test seams.
+*
+* Extracted so resource client constructors can keep their dependency
+* resolution logic in a single, unit-testable place; this makes the
+* default branches easy to cover without stubbing globals like `fetch`.
+*
+* @param options - Optional {@link HttpClient} and {@link SleepFunc} test seams.
+* @returns A {@link ResolvedDependencies} with defaults applied.
+*/
+function resolveDependencies(options) {
+	return {
+		httpClient: options.httpClient ?? createFetchHttpClient(),
+		sleep: options.sleep ?? setTimeout
+	};
+}
+//#endregion
+//#region src/internal/http/upload-request.ts
+/**
+* Reports whether a request is an upload: its body is `FormData`
+* (multipart) or `Uint8Array` (raw binary). Upload latency is
+* bandwidth-bound rather than compute-bound, so the SDK applies no default
+* request timeout to these requests; a sensible wall-clock budget depends on
+* payload size and link quality the SDK cannot know.
+*
+* @param request - The built request to classify.
+* @returns `true` when the body is `FormData` or `Uint8Array`.
+*/
+function isUploadRequest(request) {
+	return request.body instanceof FormData || request.body instanceof Uint8Array;
+}
+//#endregion
+//#region src/internal/resource-client.ts
+/**
+* Wraps an infallible request build as a {@link Result}-returning
+* `buildRequest` callback compatible with {@link ResourceMethodSpec}.
+* Use from a resource client whose builder cannot fail; resource clients
+* with local validation should construct the {@link Result} directly.
+*
+* @param request - The pre-built {@link HttpRequest}.
+* @returns A success Result wrapping the request.
+*/
+function okRequest(request) {
+	return {
+		data: request,
+		success: true
+	};
+}
+/**
+* A {@link ResourceMethodSpec.parse} implementation for endpoints that return
+* no business payload on success (such as `DELETE` and reorder operations).
+* Surfaces `undefined` data and never inspects the response body.
+*
+* @returns A success Result with `undefined` data.
+*/
+function parseEmptyResponse() {
+	return {
+		data: void 0,
+		success: true
+	};
+}
+const CLIENT_DEFAULTS = Object.freeze({
+	baseUrl: "https://apis.roblox.com",
+	maxRetries: 3,
+	retryableStatuses: IDEMPOTENT_METHOD_DEFAULTS.retryableStatuses,
+	retryableTransportCodes: IDEMPOTENT_METHOD_DEFAULTS.retryableTransportCodes,
+	retryDelay: defaultRetryDelay,
+	timeout: 3e4
+});
+/**
+* Internal orchestrator shared by every Open Cloud resource client. Holds
+* the frozen client config, observability hooks, injected HTTP client and
+* sleep, and the per-effective-key rate-limit queue registry. Resource
+* classes compose one instance and dispatch every public method through
+* {@link ResourceClient.execute} with a per-method {@link ResourceMethodSpec}.
+* Not exported from any package subpath; reachable only via sibling
+* `src/resources/**` modules in this package.
+*/
+var ResourceClient = class {
+	#budgets;
+	#config;
+	#hooks;
+	#httpClient;
+	#queues = /* @__PURE__ */ new Map();
+	#sleep;
+	/**
+	* Creates a new {@link ResourceClient}. Resolves the injected HTTP
+	* client and sleep (defaulting to fetch + `setTimeout`) and freezes the
+	* merged client config so subsequent calls cannot mutate it.
+	*
+	* @param options - Client-level configuration including the API key
+	*   and optional construction-time test seams.
+	*/
+	constructor(options) {
+		const { apiKey, hooks, httpClient, sleep, ...overrides } = options;
+		const resolved = resolveDependencies({
+			httpClient,
+			sleep
+		});
+		this.#httpClient = resolved.httpClient;
+		this.#sleep = resolved.sleep;
+		this.#budgets = new BudgetGate(this.#sleep);
+		this.#hooks = hooks ?? {};
+		this.#config = Object.freeze({
+			...CLIENT_DEFAULTS,
+			apiKey,
+			...overrides
+		});
+	}
+	/**
+	* Dispatches a single resource-method call. Merges the frozen client
+	* config with the method's `methodDefaults` and the caller's optional
+	* per-request `options`, routes through the effective-apiKey rate-limit
+	* queue, runs the retry loop, and finally parses the response with the
+	* spec's parser.
+	*
+	* @param call - The per-method spec, resource-specific parameters, and
+	*   optional per-request overrides.
+	* @returns The parsed success payload or the {@link OpenCloudError} that
+	*   caused the request to fail. Never throws.
+	*/
+	async execute(call) {
+		const { options, parameters, spec } = call;
+		const merged = mergeConfig(this.#config, {
+			methodDefaults: spec.methodDefaults,
+			methodKind: spec.methodKind,
+			requestOptions: options ?? {}
+		});
+		const requestResult = spec.buildRequest(parameters);
+		if (!requestResult.success) return requestResult;
+		const requestConfig = buildRequestConfig({
+			merged,
+			options,
+			request: requestResult.data
+		});
+		const httpResult = await this.#getQueue(merged.apiKey, spec.operationLimit).acquire(async () => {
+			return executeWithRetry(requestResult.data, {
+				config: merged,
+				hooks: this.#hooks,
+				send: this.#gatedSend(merged.apiKey, requestConfig),
+				sleep: this.#sleep
+			});
+		});
+		if (!httpResult.success) return {
+			err: enrichPermissionError(httpResult.err, spec),
+			success: false
+		};
+		return spec.parse(httpResult.data);
+	}
+	/**
+	* Returns the sleep function used by this client instance.
+	*
+	* @returns The sleep function injected at construction time.
+	*/
+	get sleep() {
+		return this.#sleep;
+	}
+	/**
+	* Builds the transport callback for one logical call, wrapping the HTTP
+	* client with the budget gate: each attempt waits on the API key's budget
+	* before sending, then folds the response's reported budget back in so the
+	* next attempt (or a sibling operation on the same key) can head off a 429.
+	*
+	* @param apiKey - The effective API key to gate on.
+	* @param requestConfig - The resolved per-request transport config.
+	* @returns A send callback for {@link executeWithRetry}.
+	*/
+	#gatedSend(apiKey, requestConfig) {
+		return async (toSend) => {
+			await this.#budgets.gate(apiKey);
+			const sendResult = await this.#httpClient.request(toSend, requestConfig);
+			this.#budgets.observe(apiKey, rateLimitSampleFromResult(sendResult));
+			return sendResult;
+		};
+	}
+	#getQueue(apiKey, limit) {
+		const key = `${apiKey}::${limit.operationKey}`;
+		const existing = this.#queues.get(key);
+		if (existing !== void 0) return existing;
+		const queue = new RateLimitQueue(limit, this.#hooks, this.#sleep);
+		this.#queues.set(key, queue);
+		return queue;
+	}
+};
+/**
+* Resolves the per-request {@link RequestConfig}. Upload requests
+* ({@link isUploadRequest}) carry no default timeout: a multi-megabyte place
+* file over a slow link is bandwidth-bound, so a client-side deadline only
+* fires spuriously. An explicit `options.timeout` still applies to any
+* request; every non-upload request keeps the merged default.
+*
+* @param inputs - The merged config, the built request, and per-request overrides.
+* @returns The config to hand to the transport, with `timeout` omitted when
+*   no client-side deadline should apply.
+*/
+function buildRequestConfig(inputs) {
+	const { merged, options, request } = inputs;
+	const shouldOmitDefaultTimeout = options?.timeout === void 0 && isUploadRequest(request);
+	return {
+		apiKey: merged.apiKey,
+		baseUrl: merged.baseUrl,
+		...shouldOmitDefaultTimeout ? {} : { timeout: merged.timeout }
+	};
+}
+function enrichPermissionError(err, spec) {
+	if (spec.requiredScopes === void 0) return err;
+	if (err instanceof PermissionError) return err;
+	if (!(err instanceof ApiError)) return err;
+	if (err.statusCode !== 401 && err.statusCode !== 403) return err;
+	return new PermissionError(err.message, {
+		cause: err.cause,
+		code: err.code,
+		details: err.details,
+		operationKey: spec.operationLimit.operationKey,
+		requiredScopes: spec.requiredScopes,
+		statusCode: err.statusCode
+	});
+}
+//#endregion
+export { isDateTimeString as a, isRecord as i, okRequest as n, parseEmptyResponse as r, ResourceClient as t };
+
+//# sourceMappingURL=resource-client-CIAkS2xQ.mjs.map