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

package/dist/{resource-client-D6Efj9fU.mjs → resource-client-C_D--PYX.mjs}

@@ -1,5 +1,5 @@
-import { n as NetworkError, r as ApiError, t as RateLimitError } from "./rate-limit-D1q2Js-z.mjs";
-import { t as PermissionError } from "./permission-error-DOVtNq3A.mjs";
+import { n as NetworkError, r as ApiError, t as RateLimitError } from "./rate-limit-Co9i28qi.mjs";
+import { a as defaultRetryDelay, i as computeRetryWaitMs, l as PermissionError, n as IDEMPOTENT_METHOD_DEFAULTS, o as mergeConfig, s as shouldRetry } from "./retry-CbHBw60o.mjs";
 import { setTimeout } from "node:timers/promises";
 //#region src/internal/utils/is-date-time-string.ts
 /**
@@ -14,7 +14,8 @@ import { setTimeout } from "node:timers/promises";
 */
 function isDateTimeString(value) {
 	if (typeof value !== "string") return false;
-	return !Number.isNaN(new Date(value).getTime());
+	const parsed = new Date(value);
+	return !Number.isNaN(parsed.getTime());
 }
 //#endregion
 //#region src/internal/utils/is-record.ts
@@ -31,224 +32,138 @@ function isRecord(value) {
 	return Object.prototype.toString.call(value) === "[object Object]";
 }
 //#endregion
-//#region src/internal/http/retry.ts
+//#region src/internal/http/budget-tracker.ts
+const MS_PER_SECOND = 1e3;
 /**
-* Default retry status codes for idempotent operations (read, list, update,
-* delete). Safe to retry on both rate limits and transient server errors.
+* 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.
 */
-const IDEMPOTENT_METHOD_DEFAULTS = Object.freeze({ retryableStatuses: Object.freeze([
-	429,
-	500,
-	502,
-	503,
-	504
-]) });
-/**
-* Default retry status codes for create operations. Retries rate limits only,
-* to prevent duplicate resources on 5xx (Roblox Open Cloud has no
-* idempotency-key support).
-*/
-const CREATE_METHOD_DEFAULTS = Object.freeze({ retryableStatuses: Object.freeze([429]) });
-/**
-* Default exponential backoff: 1s → 2s → 4s → 8s → 16s → 30s (capped).
-*
-* @example
-*
-* ```ts
-* import { defaultRetryDelay } from "./retry";
-*
-* expect(defaultRetryDelay(0)).toBe(1000);
-* expect(defaultRetryDelay(4)).toBe(16_000);
-* expect(defaultRetryDelay(10)).toBe(30_000);
-* ```
-*
-* @param attempt - Zero-indexed retry attempt number.
-* @returns Wait duration in milliseconds.
-*/
-function defaultRetryDelay(attempt) {
-	return Math.min(1e3 * 2 ** attempt, 3e4);
-}
-/**
-* Computes how long to wait before the next retry. Prefers the server's
-* suggested delay when the error is a {@link RateLimitError} with a positive
-* `retryAfterSeconds`; otherwise falls through to `retryDelay(attempt)`.
-*
-* @example
-*
-* ```ts
-* import { RateLimitError } from "../../errors/rate-limit.ts";
-* import { computeRetryWaitMs, defaultRetryDelay } from "./retry";
-*
-* const error = new RateLimitError("slow down", { retryAfterSeconds: 3 });
-*
-* expect(computeRetryWaitMs(error, { attempt: 0, retryDelay: defaultRetryDelay })).toBe(
-*     3000,
-* );
-* ```
-*
-* @example
-*
-* ```ts
-* import { ApiError } from "../../errors/api-error.ts";
-* import { computeRetryWaitMs, defaultRetryDelay } from "./retry";
-*
-* const error = new ApiError("server error", { statusCode: 503 });
-*
-* expect(computeRetryWaitMs(error, { attempt: 2, retryDelay: defaultRetryDelay })).toBe(
-*     4000,
-* );
-* ```
-*
-* @param error - The error returned by the failing request.
-* @param options - Retry attempt index and fallback delay function.
-* @returns Wait duration in milliseconds before the next attempt.
-*/
-function computeRetryWaitMs(error, options) {
-	if (error instanceof RateLimitError && error.retryAfterSeconds > 0) return error.retryAfterSeconds * 1e3;
-	return options.retryDelay(options.attempt);
-}
-/**
-* Decides whether a failed request is eligible for retry under the given
-* `retryableStatuses`. Only {@link RateLimitError} (checked against 429) and
-* {@link ApiError} (checked against its `statusCode`) are retryable — network
-* errors and other failures always return `false`.
-*
-* @example
-*
-* ```ts
-* import { RateLimitError } from "../../errors/rate-limit.ts";
-* import { shouldRetry } from "./retry";
-*
-* const error = new RateLimitError("", { retryAfterSeconds: 1 });
-*
-* expect(shouldRetry(error, { retryableStatuses: [429] })).toBe(true);
-* ```
-*
-* @example
-*
-* ```ts
-* import { ApiError } from "../../errors/api-error.ts";
-* import { shouldRetry } from "./retry";
-*
-* const error = new ApiError("", { statusCode: 503 });
-*
-* expect(shouldRetry(error, { retryableStatuses: [429, 500, 502, 503, 504] })).toBe(
-*     true,
-* );
-* ```
-*
-* @example
-*
-* ```ts
-* import { NetworkError } from "../../errors/network-error.ts";
-* import { shouldRetry } from "./retry";
-*
-* const error = new NetworkError("offline");
-*
-* expect(shouldRetry(error, { retryableStatuses: [429] })).toBe(false);
-* ```
-*
-* @param error - The error returned by the failing request.
-* @param config - Object carrying the retry-eligible status list.
-* @returns `true` if the error should be retried, `false` otherwise.
-*/
-function shouldRetry(error, config) {
-	if (error instanceof RateLimitError) return config.retryableStatuses.includes(429);
-	if (error instanceof ApiError) return config.retryableStatuses.includes(error.statusCode);
-	return false;
-}
-/**
-* Resolves the effective config for a single request by shallow-merging the
-* client config, method defaults, and per-request options. Precedence depends
-* on `methodKind`:
-*
-* - `"create"`: method defaults override client config, so client-level
-*   settings cannot silently relax create-method safety. Only explicit
-*   per-request `requestOptions` can.
-* - `"idempotent"`: client config overrides method defaults, so consumers
-*   can loosen or tighten retry policy globally. `requestOptions` still wins
-*   when provided.
-*
-* Array-valued fields like `retryableStatuses` are *replaced*, not extended.
-*
-* @template T - Concrete `RetryResolvable` subtype being merged.
-*
-* @example
-*
-* ```ts
-* import {
-*     CREATE_METHOD_DEFAULTS,
-*     defaultRetryDelay,
-*     mergeConfig,
-*     type RetryResolvable,
-* } from "./retry";
-*
-* const clientConfig: RetryResolvable = {
-*     apiKey: "k",
-*     baseUrl: "https://apis.roblox.com",
-*     maxRetries: 3,
-*     retryableStatuses: [429, 500],
-*     retryDelay: defaultRetryDelay,
-*     timeout: 30_000,
-* };
-*
-* const merged = mergeConfig(clientConfig, {
-*     methodDefaults: CREATE_METHOD_DEFAULTS,
-*     methodKind: "create",
-* });
-*
-* expect(merged.retryableStatuses).toStrictEqual([429]);
-* ```
-*
-* @example
-*
-* ```ts
-* import {
-*     defaultRetryDelay,
-*     IDEMPOTENT_METHOD_DEFAULTS,
-*     mergeConfig,
-*     type RetryResolvable,
-* } from "./retry";
-*
-* const clientConfig: RetryResolvable = {
-*     apiKey: "k",
-*     baseUrl: "https://apis.roblox.com",
-*     maxRetries: 3,
-*     retryableStatuses: [429],
-*     retryDelay: defaultRetryDelay,
-*     timeout: 30_000,
-* };
-*
-* const merged = mergeConfig(clientConfig, {
-*     methodDefaults: IDEMPOTENT_METHOD_DEFAULTS,
-*     methodKind: "idempotent",
-*     requestOptions: { timeout: 10_000 },
-* });
-*
-* expect(merged.retryableStatuses).toStrictEqual([429]);
-* expect(merged.timeout).toBe(10_000);
-* ```
-*
-* @param clientConfig - Config frozen at client construction.
-* @param options - Method defaults, method kind, and optional per-request overrides.
-* @returns A new merged config object. Inputs are not mutated.
-*/
-function mergeConfig(clientConfig, options) {
-	const { methodDefaults, methodKind, requestOptions } = options;
-	switch (methodKind) {
-		case "create": return {
-			...clientConfig,
-			...methodDefaults,
-			...requestOptions
+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
 		};
-		case "idempotent": return {
-			...methodDefaults,
-			...clientConfig,
-			...requestOptions
+	}
+	/**
+	* 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
 		};
-		default: throw new Error(`Unexpected methodKind: ${String(methodKind)}`);
 	}
-}
+	/**
+	* 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
 /**
@@ -284,6 +199,65 @@ async function executeWithRetry(request, options) {
 	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
@@ -371,6 +345,8 @@ async function tryCatch(promise) {
 }
 //#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.
 *
@@ -414,15 +390,17 @@ function extractErrorMessage(body) {
 	return extractLegacyMessage(body);
 }
 /**
-* Parses the `x-ratelimit-reset` header value into seconds.
+* 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) {
-	const parsed = Number(headerValue);
-	if (Number.isNaN(parsed)) return 0;
-	return Math.max(0, Math.floor(parsed));
+	return reduceRateLimitTokens(headerValue, (a, b) => Math.max(a, b)) ?? 0;
 }
 /**
 * Joins the base URL from config with the relative path from the request.
@@ -449,10 +427,10 @@ function buildFetchOptions(request, config) {
 	};
 	if (request.body instanceof FormData) options.body = request.body;
 	else if (request.body instanceof Uint8Array) {
-		headers.set("content-type", "application/octet-stream");
+		headers.set(CONTENT_TYPE_HEADER, "application/octet-stream");
 		options.body = request.body;
 	} else if (request.body !== void 0) {
-		headers.set("content-type", "application/json");
+		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)) {
@@ -470,9 +448,14 @@ function buildFetchOptions(request, config) {
 */
 function createFetchHttpClient(fetchFunc = globalThis.fetch) {
 	return { async request(httpRequest, config) {
-		const fetchResult = await tryCatch(fetchFunc(buildUrl(httpRequest, config), buildFetchOptions(httpRequest, config)));
+		const url = buildUrl(httpRequest, config);
+		const fetchResult = await tryCatch(fetchFunc(url, buildFetchOptions(httpRequest, config)));
 		if (!fetchResult.success) return {
-			err: new NetworkError("Network request failed", { cause: fetchResult.err }),
+			err: new NetworkError("Network request failed", {
+				cause: fetchResult.err,
+				method: httpRequest.method,
+				url
+			}),
 			success: false
 		};
 		return classifyResponse(fetchResult.data);
@@ -519,25 +502,56 @@ function createApiError(status, body) {
 	});
 }
 function createRateLimitError(response) {
-	return new RateLimitError("Rate limited", { retryAfterSeconds: parseRetryAfterSeconds(response.headers.get("x-ratelimit-reset") ?? void 0) });
+	const headers = headersToRecord(response.headers);
+	return new RateLimitError("Rate limited", {
+		remaining: reduceRateLimitTokens(headers["x-ratelimit-remaining"], (a, b) => Math.min(a, b)),
+		retryAfterSeconds: parseRetryAfterSeconds(headers["x-ratelimit-reset"])
+	});
 }
-async function readResponseBody(response) {
+/**
+* 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 {
-		const text = await response.text();
 		return {
-			data: text === "" ? void 0 : JSON.parse(text),
+			data: JSON.parse(text),
 			success: true
 		};
-	} catch {
+	} catch (err) {
 		return {
-			err: new ApiError("Failed to parse response body", { statusCode: response.status }),
+			err: err instanceof Error ? err : new Error(String(err)),
 			success: false
 		};
 	}
 }
 /**
+* 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 (for example
+* an HTML gateway page) degrades to a status-based {@link ApiError} carrying
+* the raw text. 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.
 * @returns A Result containing an HttpResponse on success or an OpenCloudError on failure.
 */
@@ -546,15 +560,29 @@ async function classifyResponse(response) {
 		err: createRateLimitError(response),
 		success: false
 	};
-	const bodyResult = await readResponseBody(response);
-	if (!bodyResult.success) return bodyResult;
-	if (response.status >= 300) return {
-		err: createApiError(response.status, bodyResult.data),
+	const text = await response.text();
+	const parsed = text === "" ? {
+		data: void 0,
+		success: true
+	} : parseJson(text);
+	if (response.status >= 300) {
+		const body = parsed.success ? parsed.data : text.slice(0, MAX_DETAIL_LENGTH);
+		return {
+			err: createApiError(response.status, body),
+			success: false
+		};
+	}
+	if (!parsed.success) return {
+		err: parseFailureError({
+			cause: parsed.err,
+			response,
+			text
+		}),
 		success: false
 	};
 	return {
 		data: {
-			body: bodyResult.data,
+			body: parsed.data,
 			headers: headersToRecord(response.headers),
 			status: response.status
 		},
@@ -582,6 +610,21 @@ function resolveDependencies(options) {
 	};
 }
 //#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
@@ -615,6 +658,7 @@ 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
 });
@@ -628,6 +672,7 @@ const CLIENT_DEFAULTS = Object.freeze({
 * `src/resources/**` modules in this package.
 */
 var ResourceClient = class {
+	#budgets;
 	#config;
 	#hooks;
 	#httpClient;
@@ -649,6 +694,7 @@ var ResourceClient = class {
 		});
 		this.#httpClient = resolved.httpClient;
 		this.#sleep = resolved.sleep;
+		this.#budgets = new BudgetGate(this.#sleep);
 		this.#hooks = hooks ?? {};
 		this.#config = Object.freeze({
 			...CLIENT_DEFAULTS,
@@ -677,16 +723,16 @@ var ResourceClient = class {
 		});
 		const requestResult = spec.buildRequest(parameters);
 		if (!requestResult.success) return requestResult;
-		const requestConfig = {
-			apiKey: merged.apiKey,
-			baseUrl: merged.baseUrl,
-			timeout: merged.timeout
-		};
+		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: async (toSend) => this.#httpClient.request(toSend, requestConfig),
+				send: this.#gatedSend(merged.apiKey, requestConfig),
 				sleep: this.#sleep
 			});
 		});
@@ -704,6 +750,24 @@ var ResourceClient = class {
 	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);
@@ -713,6 +777,26 @@ var ResourceClient = class {
 		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;
@@ -721,12 +805,13 @@ function enrichPermissionError(err, spec) {
 	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 { IDEMPOTENT_METHOD_DEFAULTS as a, isDateTimeString as c, CREATE_METHOD_DEFAULTS as i, okRequest as n, defaultRetryDelay as o, parseEmptyResponse as r, isRecord as s, ResourceClient as t };
+export { isDateTimeString as a, isRecord as i, okRequest as n, parseEmptyResponse as r, ResourceClient as t };
 
-//# sourceMappingURL=resource-client-D6Efj9fU.mjs.map
+//# sourceMappingURL=resource-client-C_D--PYX.mjs.map