@bedrock-rbx/ocale 0.1.0-beta.13 → 0.1.0-beta.15

package/dist/{rate-limit-D1q2Js-z.mjs → rate-limit-nY4BF079.mjs}

@@ -57,10 +57,27 @@ var ApiError = class extends OpenCloudError {
 //#region src/errors/network-error.ts
 /**
 * Thrown when a network-level failure prevents the request from reaching
-* the Roblox Open Cloud API (e.g., DNS resolution failure, connection timeout).
+* the Roblox Open Cloud API (e.g., DNS resolution failure, connection reset).
+* The `method` and `url` name the failing call so a transport failure that
+* survives every retry can be diagnosed; the underlying transport error is
+* carried on `cause`.
 */
 var NetworkError = class extends OpenCloudError {
+	method;
 	name = "NetworkError";
+	url;
+	/**
+	* Creates a new NetworkError.
+	*
+	* @param message - Human-readable error description.
+	* @param options - Error options including the optional `cause` and the
+	*   `method` / `url` of the request that failed.
+	*/
+	constructor(message, options) {
+		super(message, options);
+		this.method = options?.method;
+		this.url = options?.url;
+	}
 };
 //#endregion
 //#region src/errors/rate-limit.ts
@@ -98,4 +115,4 @@ var RateLimitError = class extends OpenCloudError {
 //#endregion
 export { OpenCloudError as i, NetworkError as n, ApiError as r, RateLimitError as t };
 
-//# sourceMappingURL=rate-limit-D1q2Js-z.mjs.map
+//# sourceMappingURL=rate-limit-nY4BF079.mjs.map

package/dist/rate-limit-nY4BF079.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit-nY4BF079.mjs","names":[],"sources":["../src/errors/base.ts","../src/errors/api-error.ts","../src/errors/network-error.ts","../src/errors/rate-limit.ts"],"sourcesContent":["/**\n * Base error class for all Open Cloud SDK errors.\n *\n * All specific error types (RateLimitError, ApiError, NetworkError)\n * extend this class, enabling `instanceof OpenCloudError` checks.\n */\nexport class OpenCloudError extends Error {\n\tpublic override readonly name: string = \"OpenCloudError\";\n}\n","import { OpenCloudError } from \"./base.ts\";\n\n/**\n * Options for constructing an {@link ApiError}.\n */\nexport interface ApiErrorOptions extends ErrorOptions {\n\t/** Optional machine-readable error code from the API. */\n\tcode?: string | undefined;\n\t/** Parsed response body, when present. */\n\tdetails?: JSONValue | undefined;\n\t/** HTTP status code from the API response. */\n\tstatusCode: number;\n}\n\n/**\n * Thrown when the Roblox Open Cloud API returns a non-2xx response\n * that is not a rate limit (429).\n *\n * @example\n *\n * ```ts\n * import { ApiError } from \"@bedrock-rbx/ocale\";\n *\n * const error = new ApiError(\"HTTP 404: Pass not found (code NotFound)\", {\n *     code: \"NotFound\",\n *     details: { errorCode: \"NotFound\", message: \"Pass not found\" },\n *     statusCode: 404,\n * });\n *\n * expect(error).toBeInstanceOf(ApiError);\n * expect(error.statusCode).toBe(404);\n * expect(error.code).toBe(\"NotFound\");\n * expect(error.details).toEqual({\n *     errorCode: \"NotFound\",\n *     message: \"Pass not found\",\n * });\n * ```\n */\nexport class ApiError extends OpenCloudError {\n\tpublic readonly code: string | undefined;\n\tpublic readonly details: JSONValue | undefined;\n\tpublic override readonly name: string = \"ApiError\";\n\tpublic readonly statusCode: number;\n\n\t/**\n\t * Creates a new ApiError.\n\t *\n\t * @param message - Human-readable error description.\n\t * @param options - Error options including status code, optional error\n\t *   code, and the parsed response body when present.\n\t */\n\tconstructor(message: string, options: ApiErrorOptions) {\n\t\tsuper(message, options);\n\t\tthis.statusCode = options.statusCode;\n\t\tthis.code = options.code;\n\t\tthis.details = options.details;\n\t}\n}\n","import { OpenCloudError } from \"./base.ts\";\n\n/**\n * Options for constructing a {@link NetworkError}.\n */\nexport interface NetworkErrorOptions extends ErrorOptions {\n\t/** HTTP method of the request that failed. */\n\tmethod?: string | undefined;\n\t/** Fully-qualified URL of the request that failed. */\n\turl?: string | undefined;\n}\n\n/**\n * Thrown when a network-level failure prevents the request from reaching\n * the Roblox Open Cloud API (e.g., DNS resolution failure, connection reset).\n * The `method` and `url` name the failing call so a transport failure that\n * survives every retry can be diagnosed; the underlying transport error is\n * carried on `cause`.\n */\nexport class NetworkError extends OpenCloudError {\n\tpublic readonly method: string | undefined;\n\tpublic override readonly name: string = \"NetworkError\";\n\tpublic readonly url: string | undefined;\n\n\t/**\n\t * Creates a new NetworkError.\n\t *\n\t * @param message - Human-readable error description.\n\t * @param options - Error options including the optional `cause` and the\n\t *   `method` / `url` of the request that failed.\n\t */\n\tconstructor(message: string, options?: NetworkErrorOptions) {\n\t\tsuper(message, options);\n\t\tthis.method = options?.method;\n\t\tthis.url = options?.url;\n\t}\n}\n","import { OpenCloudError } from \"./base.ts\";\n\n/**\n * Options for constructing a {@link RateLimitError}.\n */\nexport interface RateLimitErrorOptions extends ErrorOptions {\n\t/** Seconds to wait before retrying the request. */\n\tretryAfterSeconds: number;\n}\n\n/**\n * Thrown when the Roblox Open Cloud API returns a 429 Too Many Requests response.\n * Contains the server-suggested retry delay.\n *\n * @example\n *\n * ```ts\n * import { RateLimitError } from \"@bedrock-rbx/ocale\";\n *\n * const error = new RateLimitError(\"Too many requests\", {\n *     retryAfterSeconds: 30,\n * });\n *\n * expect(error).toBeInstanceOf(RateLimitError);\n * expect(error.retryAfterSeconds).toBe(30);\n * ```\n */\nexport class RateLimitError extends OpenCloudError {\n\tpublic override readonly name = \"RateLimitError\";\n\tpublic readonly retryAfterSeconds: number;\n\n\t/**\n\t * Creates a new RateLimitError.\n\t *\n\t * @param message - Human-readable error description.\n\t * @param options - Error options including the retry delay.\n\t */\n\tconstructor(message: string, options: RateLimitErrorOptions) {\n\t\tsuper(message, options);\n\t\tthis.retryAfterSeconds = options.retryAfterSeconds;\n\t}\n}\n"],"mappings":";;;;;;;AAMA,IAAa,iBAAb,cAAoC,MAAM;CACzC,OAAwC;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC+BzC,IAAa,WAAb,cAA8B,eAAe;CAC5C;CACA;CACA,OAAwC;CACxC;;;;;;;;CASA,YAAY,SAAiB,SAA0B;AACtD,QAAM,SAAS,QAAQ;AACvB,OAAK,aAAa,QAAQ;AAC1B,OAAK,OAAO,QAAQ;AACpB,OAAK,UAAU,QAAQ;;;;;;;;;;;;ACpCzB,IAAa,eAAb,cAAkC,eAAe;CAChD;CACA,OAAwC;CACxC;;;;;;;;CASA,YAAY,SAAiB,SAA+B;AAC3D,QAAM,SAAS,QAAQ;AACvB,OAAK,SAAS,SAAS;AACvB,OAAK,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;ACPtB,IAAa,iBAAb,cAAoC,eAAe;CAClD,OAAgC;CAChC;;;;;;;CAQA,YAAY,SAAiB,SAAgC;AAC5D,QAAM,SAAS,QAAQ;AACvB,OAAK,oBAAoB,QAAQ"}

package/dist/{resource-client-D6Efj9fU.mjs → resource-client-CG9-BG81.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-nY4BF079.mjs";
+import { a as defaultRetryDelay, i as computeRetryWaitMs, l as PermissionError, n as IDEMPOTENT_METHOD_DEFAULTS, o as mergeConfig, s as shouldRetry } from "./retry-BzX29aw_.mjs";
 import { setTimeout } from "node:timers/promises";
 //#region src/internal/utils/is-date-time-string.ts
 /**
@@ -31,225 +31,6 @@ function isRecord(value) {
 	return Object.prototype.toString.call(value) === "[object Object]";
 }
 //#endregion
-//#region src/internal/http/retry.ts
-/**
-* Default retry status codes for idempotent operations (read, list, update,
-* delete). Safe to retry on both rate limits and transient server errors.
-*/
-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
-		};
-		case "idempotent": return {
-			...methodDefaults,
-			...clientConfig,
-			...requestOptions
-		};
-		default: throw new Error(`Unexpected methodKind: ${String(methodKind)}`);
-	}
-}
-//#endregion
 //#region src/internal/http/execute.ts
 /**
 * Retry-aware orchestration loop. Coordinates a single logical request,
@@ -371,6 +152,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.
 *
@@ -449,10 +232,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 +253,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);
@@ -521,23 +309,50 @@ function createApiError(status, body) {
 function createRateLimitError(response) {
 	return new RateLimitError("Rate limited", { retryAfterSeconds: parseRetryAfterSeconds(response.headers.get("x-ratelimit-reset") ?? void 0) });
 }
-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 +361,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
 		},
@@ -615,6 +444,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
 });
@@ -727,6 +557,6 @@ function enrichPermissionError(err, spec) {
 	});
 }
 //#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-CG9-BG81.mjs.map

package/dist/resource-client-CG9-BG81.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-client-CG9-BG81.mjs","names":["#hooks","#intervalMs","#maxBucketLevel","#sleep","#chain","#waitForToken","#lastCheck","#bucketLevel","#config","#hooks","#httpClient","#queues","#sleep","#getQueue"],"sources":["../src/internal/utils/is-date-time-string.ts","../src/internal/utils/is-record.ts","../src/internal/http/execute.ts","../src/internal/http/rate-limit-queue.ts","../src/internal/utils/try-catch.ts","../src/internal/http/fetch-client.ts","../src/internal/http/resolve-dependencies.ts","../src/internal/resource-client.ts"],"sourcesContent":["/**\n * Narrows `value` to a string that parses to a real {@link Date} via the\n * `Date(string)` constructor. Used by resource parsers to gate\n * `format: date-time` wire fields before handing them to `new Date(...)`,\n * which silently produces an `Invalid Date` for invalid input.\n *\n * @param value - The unknown wire value to validate.\n * @returns `true` when `value` is a string and `new Date(value).getTime()`\n *   is not `NaN`.\n */\nexport function isDateTimeString(value: unknown): value is string {\n\tif (typeof value !== \"string\") {\n\t\treturn false;\n\t}\n\n\treturn !Number.isNaN(new Date(value).getTime());\n}\n","/**\n * Narrows `value` to a plain JSON-style record. Excludes arrays, class\n * instances, primitives, and `null`/`undefined`. Used by resource\n * parsers to gate property access on wire bodies whose shape isn't\n * known at compile time.\n *\n * @param value - The unknown value to narrow.\n * @returns `true` when `value` is a plain `[object Object]`.\n */\nexport function isRecord(value: unknown): value is Record<string, unknown> {\n\treturn Object.prototype.toString.call(value) === \"[object Object]\";\n}\n","import type { OpenCloudError } from \"../../errors/base.ts\";\nimport type { Result } from \"../../types.ts\";\nimport type { SleepFunc } from \"../utils/sleep.ts\";\nimport { computeRetryWaitMs, type RetryResolvable, shouldRetry } from \"./retry.ts\";\nimport type { HttpRequest, HttpResponse, OpenCloudHooks } from \"./types.ts\";\n\n/** A transport callback: takes a request, returns a classified Result. */\ntype SendFunc = (request: HttpRequest) => Promise<Result<HttpResponse, OpenCloudError>>;\n\n/**\n * Inputs to {@link executeWithRetry} bundled as an options object to keep the\n * function signature narrow.\n */\ninterface ExecuteOptions {\n\t/** Fully-resolved retry config (post-merge). */\n\treadonly config: RetryResolvable;\n\t/** Client-level observability hooks. */\n\treadonly hooks: OpenCloudHooks;\n\t/** Transport callback. May be pre-wrapped by a rate-limit queue. */\n\treadonly send: SendFunc;\n\t/** Injectable sleep (tests pass a fake). */\n\treadonly sleep: SleepFunc;\n}\n\n/**\n * Retry-aware orchestration loop. Coordinates a single logical request,\n * looping over `options.send` until it succeeds, the error is non-retryable,\n * or `options.config.maxRetries` is exhausted. Fires observability hooks\n * at each transition. Domain- and queue-agnostic: `send` may be any\n * callback, including one wrapped by a rate-limit queue.\n *\n * @param request - The immutable request to send.\n * @param options - The transport callback, resolved config, hooks, and sleep.\n * @returns The first success, or the final error after retries are exhausted.\n */\nexport async function executeWithRetry(\n\trequest: HttpRequest,\n\toptions: ExecuteOptions,\n): Promise<Result<HttpResponse, OpenCloudError>> {\n\tconst { config, hooks, send, sleep } = options;\n\n\tasync function attempt(): Promise<Result<HttpResponse, OpenCloudError>> {\n\t\thooks.onRequest?.(request);\n\t\treturn send(request);\n\t}\n\n\tlet result = await attempt();\n\n\tfor (let retry = 0; retry < config.maxRetries; retry++) {\n\t\tif (result.success || !shouldRetry(result.err, config)) {\n\t\t\treturn result;\n\t\t}\n\n\t\tconst { err } = result;\n\t\thooks.onRetry?.(retry + 1, err);\n\t\tconst waitMs = computeRetryWaitMs(err, { attempt: retry, retryDelay: config.retryDelay });\n\t\thooks.onRateLimit?.(waitMs);\n\t\tawait sleep(waitMs);\n\n\t\tresult = await attempt();\n\t}\n\n\treturn result;\n}\n","import type { SleepFunc } from \"../utils/sleep.ts\";\nimport type { OpenCloudHooks } from \"./types.ts\";\n\n/**\n * Identifies and bounds a single Roblox Open Cloud operation for rate\n * limiting, e.g. `{ operationKey: \"game-passes.create\", maxPerSecond: 5 }`.\n */\nexport interface OperationLimit {\n\t/** Maximum sustained request rate in requests per second. */\n\treadonly maxPerSecond: number;\n\t/**\n\t * Stable identifier for the operation (e.g. \"game-passes.create\"). Not\n\t * consumed by the queue itself; callers use it to key per-operation\n\t * queues in a registry (see GamePassesClient).\n\t */\n\treadonly operationKey: string;\n}\n\n/**\n * Token-bucket rate limiter for a single `(apiKey, operation)` pair. Every\n * call to `acquire` consumes one token; when the bucket is empty the call\n * waits until a token regenerates before invoking the task. Burst capacity\n * equals `maxPerSecond`, refilling at `maxPerSecond` tokens per second.\n *\n * Implemented as a leaky bucket tracking drain debt in ms. `#lastCheck`\n * advances by `waitMs` after every sleep so the algorithm stays correct\n * whether or not the injected sleep moves `Date.now()` forward.\n */\nexport class RateLimitQueue {\n\treadonly #hooks: OpenCloudHooks;\n\treadonly #intervalMs: number;\n\treadonly #maxBucketLevel: number;\n\treadonly #sleep: SleepFunc;\n\n\t#bucketLevel = 0;\n\t#chain: Promise<void> = Promise.resolve();\n\t#lastCheck: number = Date.now();\n\n\t/**\n\t * Creates a rate-limit queue bound to a single operation.\n\t *\n\t * @param limit - The operation key and its per-second request ceiling.\n\t * @param hooks - Observability callbacks; `onRateLimit` fires when the\n\t *   bucket is empty and a sleep is about to start.\n\t * @param sleep - Injectable sleep (tests pass a fake).\n\t */\n\tconstructor(limit: OperationLimit, hooks: OpenCloudHooks, sleep: SleepFunc) {\n\t\tthis.#intervalMs = 1000 / limit.maxPerSecond;\n\t\tthis.#maxBucketLevel = limit.maxPerSecond * this.#intervalMs;\n\t\tthis.#hooks = hooks;\n\t\tthis.#sleep = sleep;\n\t}\n\n\t/**\n\t * Waits for a token — sleeping and firing `hooks.onRateLimit` if the\n\t * bucket is empty — then executes `task`. Concurrent callers are\n\t * serialized at token acquisition; tasks themselves run independently\n\t * once their token is secured.\n\t *\n\t * @param task - The request to run once a token is available.\n\t * @returns The value produced by `task`.\n\t */\n\tpublic async acquire<T>(task: () => Promise<T>): Promise<T> {\n\t\tconst myTurn = this.#chain.then(async () => this.#waitForToken());\n\t\tthis.#chain = myTurn;\n\t\tawait myTurn;\n\t\treturn task();\n\t}\n\n\tasync #waitForToken(): Promise<void> {\n\t\tconst now = Math.max(Date.now(), this.#lastCheck);\n\t\tconst drained = Math.max(0, this.#bucketLevel - (now - this.#lastCheck));\n\t\tthis.#lastCheck = now;\n\n\t\tif (drained + this.#intervalMs <= this.#maxBucketLevel) {\n\t\t\tthis.#bucketLevel = drained + this.#intervalMs;\n\t\t\treturn;\n\t\t}\n\n\t\tconst waitMs = drained + this.#intervalMs - this.#maxBucketLevel;\n\t\tthis.#hooks.onRateLimit?.(waitMs);\n\t\tawait this.#sleep(waitMs);\n\t\tthis.#bucketLevel = this.#maxBucketLevel;\n\t\tthis.#lastCheck = now + waitMs;\n\t}\n}\n","import type { Result } from \"../../types.ts\";\n\n/**\n * Wraps a promise into a {@link Result}, catching rejections.\n *\n * @template T - The resolved value type.\n * @param promise - The promise to wrap.\n * @returns A Result containing the resolved value or the rejection error.\n */\nexport async function tryCatch<T>(promise: Promise<T>): Promise<Result<T>> {\n\ttry {\n\t\tconst data = await promise;\n\t\treturn { data, success: true };\n\t} catch (err) {\n\t\treturn { err: err instanceof Error ? err : new Error(String(err)), success: false };\n\t}\n}\n","import { ApiError } from \"../../errors/api-error.ts\";\nimport type { OpenCloudError } from \"../../errors/base.ts\";\nimport { NetworkError } from \"../../errors/network-error.ts\";\nimport { RateLimitError } from \"../../errors/rate-limit.ts\";\nimport type { Result } from \"../../types.ts\";\nimport { tryCatch } from \"../utils/try-catch.ts\";\nimport type { HttpClient, HttpRequest, HttpResponse, RequestConfig } from \"./types.ts\";\n\n// Caps the raw body retained when a response cannot be parsed, so a multi-KB\n// HTML error page is not surfaced or logged whole.\nconst MAX_DETAIL_LENGTH = 500;\n\nconst CONTENT_TYPE_HEADER = \"content-type\";\n\ninterface ParseFailureArgs {\n\treadonly cause: Error;\n\treadonly response: Response;\n\treadonly text: string;\n}\n\ninterface ApiErrorMessageParts {\n\treadonly code: string | undefined;\n\treadonly message: string | undefined;\n\treadonly status: number;\n}\n\n/**\n * Converts a `Headers` object to a plain record with lowercased keys.\n *\n * @param headers - The `Headers` instance to convert.\n * @returns A record mapping lowercased header names to their values.\n */\nexport function headersToRecord(headers: Headers): Record<string, string> {\n\treturn Object.fromEntries(headers);\n}\n\n/**\n * Permissively extracts a machine-readable error code from a response body.\n *\n * Modern Open Cloud responses use `{ errorCode: string, message: string }`;\n * the legacy game-internationalization endpoints use\n * `{ errors: [{ code: number, message: string }, ...] }`. Both shapes are\n * checked; numeric legacy codes are returned as strings so callers see one\n * consistent type.\n *\n * @param body - The parsed response body (unknown shape).\n * @returns The error code if present, otherwise `undefined`.\n */\nexport function extractErrorCode(body: unknown): string | undefined {\n\tif (body === null || typeof body !== \"object\") {\n\t\treturn undefined;\n\t}\n\n\tconst errorCode = Reflect.get(body, \"errorCode\");\n\tif (typeof errorCode === \"string\") {\n\t\treturn errorCode;\n\t}\n\n\treturn extractLegacyCode(body);\n}\n\n/**\n * Permissively extracts a human-readable error message from a response body.\n *\n * Modern Open Cloud responses expose `message` at the top level; the legacy\n * game-internationalization endpoints nest it under `errors[0].message`.\n *\n * @param body - The parsed response body (unknown shape).\n * @returns The message if present, otherwise `undefined`.\n */\nexport function extractErrorMessage(body: unknown): string | undefined {\n\tif (body === null || typeof body !== \"object\") {\n\t\treturn undefined;\n\t}\n\n\tconst message = Reflect.get(body, \"message\");\n\tif (typeof message === \"string\") {\n\t\treturn message;\n\t}\n\n\treturn extractLegacyMessage(body);\n}\n\n/**\n * Parses the `x-ratelimit-reset` header value into seconds.\n *\n * @param headerValue - The raw header value, or `undefined` if missing.\n * @returns The number of seconds to wait, or 0 if missing/invalid.\n */\nexport function parseRetryAfterSeconds(headerValue: string | undefined): number {\n\tconst parsed = Number(headerValue);\n\tif (Number.isNaN(parsed)) {\n\t\treturn 0;\n\t}\n\n\treturn Math.max(0, Math.floor(parsed));\n}\n\n/**\n * Joins the base URL from config with the relative path from the request.\n *\n * @param request - The HTTP request containing the relative URL.\n * @param config - The request config containing the base URL.\n * @returns The fully-qualified URL string.\n */\nexport function buildUrl(request: HttpRequest, config: RequestConfig): string {\n\tconst base = config.baseUrl.endsWith(\"/\") ? config.baseUrl.slice(0, -1) : config.baseUrl;\n\treturn `${base}${request.url}`;\n}\n\n/**\n * Constructs the `RequestInit` options for a `fetch` call.\n *\n * @param request - The HTTP request to build options for.\n * @param config - The request config containing API key and timeout.\n * @returns A `RequestInit` object ready for `fetch`.\n */\nexport function buildFetchOptions(request: HttpRequest, config: RequestConfig): RequestInit {\n\tconst headers = new Headers({\n\t\t\"x-api-key\": config.apiKey,\n\t});\n\n\tconst options: RequestInit = {\n\t\theaders,\n\t\tmethod: request.method,\n\t};\n\n\tif (request.body instanceof FormData) {\n\t\toptions.body = request.body;\n\t} else if (request.body instanceof Uint8Array) {\n\t\theaders.set(CONTENT_TYPE_HEADER, \"application/octet-stream\");\n\t\toptions.body = request.body;\n\t} else if (request.body !== undefined) {\n\t\theaders.set(CONTENT_TYPE_HEADER, \"application/json\");\n\t\toptions.body = JSON.stringify(request.body);\n\t}\n\n\tif (request.headers !== undefined) {\n\t\tfor (const [name, value] of Object.entries(request.headers)) {\n\t\t\tif (name.toLowerCase() === \"x-api-key\") {\n\t\t\t\tcontinue;\n\t\t\t}\n\n\t\t\theaders.set(name, value);\n\t\t}\n\t}\n\n\tif (config.timeout !== undefined) {\n\t\toptions.signal = AbortSignal.timeout(config.timeout);\n\t}\n\n\treturn options;\n}\n\n/**\n * Creates an {@link HttpClient} backed by the Fetch API.\n *\n * @param fetchFunc - The fetch implementation to use. Defaults to `globalThis.fetch`.\n * @returns An HttpClient that classifies responses into typed Results.\n */\nexport function createFetchHttpClient(\n\tfetchFunc: (url: string, init: RequestInit) => Promise<Response> = globalThis.fetch,\n): HttpClient {\n\treturn {\n\t\tasync request(\n\t\t\thttpRequest: HttpRequest,\n\t\t\tconfig: RequestConfig,\n\t\t): Promise<Result<HttpResponse, OpenCloudError>> {\n\t\t\tconst url = buildUrl(httpRequest, config);\n\t\t\tconst options = buildFetchOptions(httpRequest, config);\n\n\t\t\tconst fetchResult = await tryCatch(fetchFunc(url, options));\n\t\t\tif (!fetchResult.success) {\n\t\t\t\treturn {\n\t\t\t\t\terr: new NetworkError(\"Network request failed\", {\n\t\t\t\t\t\tcause: fetchResult.err,\n\t\t\t\t\t\tmethod: httpRequest.method,\n\t\t\t\t\t\turl,\n\t\t\t\t\t}),\n\t\t\t\t\tsuccess: false,\n\t\t\t\t};\n\t\t\t}\n\n\t\t\treturn classifyResponse(fetchResult.data);\n\t\t},\n\t};\n}\n\nfunction readLegacyErrorEntry(body: object): object | undefined {\n\tconst errors = Reflect.get(body, \"errors\");\n\tif (!Array.isArray(errors)) {\n\t\treturn undefined;\n\t}\n\n\tconst [first] = errors;\n\tif (typeof first !== \"object\" || first === null) {\n\t\treturn undefined;\n\t}\n\n\treturn first;\n}\n\nfunction extractLegacyCode(body: object): string | undefined {\n\tconst first = readLegacyErrorEntry(body);\n\tif (first === undefined) {\n\t\treturn undefined;\n\t}\n\n\tconst code = Reflect.get(first, \"code\");\n\tif (typeof code === \"string\") {\n\t\treturn code;\n\t}\n\n\treturn typeof code === \"number\" ? String(code) : undefined;\n}\n\nfunction extractLegacyMessage(body: object): string | undefined {\n\tconst first = readLegacyErrorEntry(body);\n\tif (first === undefined) {\n\t\treturn undefined;\n\t}\n\n\tconst message = Reflect.get(first, \"message\");\n\treturn typeof message === \"string\" ? message : undefined;\n}\n\nfunction formatApiErrorMessage(parts: ApiErrorMessageParts): string {\n\tconst { code, message, status } = parts;\n\tconst base = `HTTP ${status}`;\n\tif (message === undefined && code === undefined) {\n\t\treturn base;\n\t}\n\n\tif (message === undefined) {\n\t\treturn `${base} (code ${code})`;\n\t}\n\n\tif (code === undefined) {\n\t\treturn `${base}: ${message}`;\n\t}\n\n\treturn `${base}: ${message} (code ${code})`;\n}\n\nfunction createApiError(status: number, body: JSONValue | undefined): ApiError {\n\tconst code = extractErrorCode(body);\n\tconst message = extractErrorMessage(body);\n\treturn new ApiError(formatApiErrorMessage({ code, message, status }), {\n\t\tcode,\n\t\tdetails: body,\n\t\tstatusCode: status,\n\t});\n}\n\nfunction createRateLimitError(response: Response): RateLimitError {\n\treturn new RateLimitError(\"Rate limited\", {\n\t\tretryAfterSeconds: parseRetryAfterSeconds(\n\t\t\tresponse.headers.get(\"x-ratelimit-reset\") ?? undefined,\n\t\t),\n\t});\n}\n\n/**\n * Parses response text as JSON, returning the underlying `SyntaxError` on\n * failure rather than throwing. The synchronous sibling of {@link tryCatch}.\n *\n * @param text - The raw response body text.\n * @returns A Result wrapping the parsed value, or the parse error.\n */\nfunction parseJson(text: string): Result<JSONValue> {\n\ttry {\n\t\treturn { data: JSON.parse(text), success: true };\n\t} catch (err) {\n\t\treturn { err: err instanceof Error ? err : new Error(String(err)), success: false };\n\t}\n}\n\n/**\n * Builds the error for a 2xx response whose body could not be parsed as JSON,\n * preserving the parse `cause`, the (truncated) raw body, and the declared\n * content-type so the failure can be diagnosed after the fact.\n *\n * @param args - The Response, raw body text, and underlying parse error.\n * @returns An ApiError carrying the diagnostic context.\n */\nfunction parseFailureError({ cause, response, text }: ParseFailureArgs): ApiError {\n\tconst contentType = response.headers.get(CONTENT_TYPE_HEADER) ?? \"unknown\";\n\treturn new ApiError(`Failed to parse response body (content-type: ${contentType})`, {\n\t\tcause,\n\t\tdetails: text.slice(0, MAX_DETAIL_LENGTH),\n\t\tstatusCode: response.status,\n\t});\n}\n\n/**\n * Classifies a fetch `Response` into a typed `Result`.\n *\n * The body is read once and parsed best-effort. Error responses (status >= 300)\n * never require valid JSON: an error body that is not valid JSON (for example\n * an HTML gateway page) degrades to a status-based {@link ApiError} carrying\n * the raw text. A parse failure is only fatal on a 2xx, where a parseable body is part\n * of the contract.\n *\n * @param response - The raw fetch Response to classify.\n * @returns A Result containing an HttpResponse on success or an OpenCloudError on failure.\n */\nasync function classifyResponse(response: Response): Promise<Result<HttpResponse, OpenCloudError>> {\n\tif (response.status === 429) {\n\t\treturn { err: createRateLimitError(response), success: false };\n\t}\n\n\tconst text = await response.text();\n\tconst parsed: Result<JSONValue | undefined> =\n\t\ttext === \"\" ? { data: undefined, success: true } : parseJson(text);\n\n\tif (response.status >= 300) {\n\t\tconst body = parsed.success ? parsed.data : text.slice(0, MAX_DETAIL_LENGTH);\n\t\treturn { err: createApiError(response.status, body), success: false };\n\t}\n\n\tif (!parsed.success) {\n\t\treturn { err: parseFailureError({ cause: parsed.err, response, text }), success: false };\n\t}\n\n\treturn {\n\t\tdata: {\n\t\t\tbody: parsed.data,\n\t\t\theaders: headersToRecord(response.headers),\n\t\t\tstatus: response.status,\n\t\t},\n\t\tsuccess: true,\n\t};\n}\n","import { setTimeout } from \"node:timers/promises\";\n\nimport type { HttpClient, SleepFunc } from \"../../client/types.ts\";\nimport { createFetchHttpClient } from \"./fetch-client.ts\";\n\n/**\n * Options accepted by {@link resolveDependencies}. Mirrors the test-seam\n * subset of the public client options.\n */\ninterface ResolveDependenciesOptions {\n\t/** Test seam: custom {@link HttpClient}. Defaults to a fetch-backed client. */\n\treadonly httpClient?: HttpClient | undefined;\n\t/** Test seam: custom {@link SleepFunc}. Defaults to a `setTimeout`-backed sleep. */\n\treadonly sleep?: SleepFunc | undefined;\n}\n\n/**\n * Fully-populated dependency set consumed by resource client constructors.\n */\ninterface ResolvedDependencies {\n\t/** Concrete {@link HttpClient} implementation. */\n\treadonly httpClient: HttpClient;\n\t/** Concrete {@link SleepFunc} implementation. */\n\treadonly sleep: SleepFunc;\n}\n\n/**\n * Resolves the concrete HTTP client and sleep implementation a resource\n * client should use. Falls back to the fetch-backed HTTP client and the\n * default `setTimeout`-based sleep when the caller omits the test seams.\n *\n * Extracted so resource client constructors can keep their dependency\n * resolution logic in a single, unit-testable place; this makes the\n * default branches easy to cover without stubbing globals like `fetch`.\n *\n * @param options - Optional {@link HttpClient} and {@link SleepFunc} test seams.\n * @returns A {@link ResolvedDependencies} with defaults applied.\n */\nexport function resolveDependencies(options: ResolveDependenciesOptions): ResolvedDependencies {\n\treturn {\n\t\thttpClient: options.httpClient ?? createFetchHttpClient(),\n\t\tsleep: options.sleep ?? setTimeout,\n\t};\n}\n","import type { Except } from \"type-fest\";\n\nimport type {\n\tHttpClient,\n\tHttpRequest,\n\tHttpResponse,\n\tOpenCloudClientOptions,\n\tOpenCloudHooks,\n\tRequestOptions,\n\tSleepFunc,\n} from \"../client/types.ts\";\nimport { ApiError } from \"../errors/api-error.ts\";\nimport type { OpenCloudError } from \"../errors/base.ts\";\nimport { PermissionError } from \"../errors/permission-error.ts\";\nimport type { Result } from \"../types.ts\";\nimport { executeWithRetry } from \"./http/execute.ts\";\nimport { type OperationLimit, RateLimitQueue } from \"./http/rate-limit-queue.ts\";\nimport { resolveDependencies } from \"./http/resolve-dependencies.ts\";\nimport {\n\tdefaultRetryDelay,\n\tIDEMPOTENT_METHOD_DEFAULTS,\n\tmergeConfig,\n\ttype MethodKind,\n\ttype RetryResolvable,\n} from \"./http/retry.ts\";\n\n/**\n * Describes a single resource method's shape for dispatch through\n * `ResourceClient.execute`. Each resource client declares one module-level\n * constant per public method; that constant binds the four resource-specific\n * values (request builder, response parser, retry-policy method kind,\n * operation-level rate limit) and flows through `execute` uniformly.\n *\n * @template P - The resource-specific parameter shape the builder\n *   accepts.\n * @template T - The resource-specific parsed success type the parser\n *   produces.\n */\nexport interface ResourceMethodSpec<P, T> {\n\t/**\n\t * Builds the pure {@link HttpRequest} for a single call. Returns a\n\t * {@link Result} so a builder can short-circuit with a local error\n\t * (typically a {@link OpenCloudError} subclass such as `ValidationError`)\n\t * before any HTTP, queue, or retry work happens. Builders that cannot\n\t * fail wrap their return as `{ data: request, success: true }`.\n\t */\n\treadonly buildRequest: (parameters: P) => Result<HttpRequest, OpenCloudError>;\n\t/** Method-level retry defaults merged into the resolved config. */\n\treadonly methodDefaults: Partial<RetryResolvable>;\n\t/**\n\t * Method kind, controlling merge precedence: `\"create\"` lets method\n\t * defaults win over client config so create safety cannot be relaxed\n\t * silently; `\"idempotent\"` lets client config win over method defaults\n\t * so consumers can loosen retry globally.\n\t */\n\treadonly methodKind: MethodKind;\n\t/** Operation-level rate limit, keyed into the client's per-key queue map. */\n\treadonly operationLimit: OperationLimit;\n\t/**\n\t * Converts the full {@link HttpResponse} into the resource-specific\n\t * parsed shape. Takes the whole response (body, status, headers) so\n\t * future parsers can read headers without widening the signature.\n\t */\n\treadonly parse: (response: HttpResponse) => Result<T, OpenCloudError>;\n\t/**\n\t * Open Cloud scopes the API key or OAuth token must carry for this\n\t * method, sourced from the vendored OpenAPI schema's `x-roblox-scopes`.\n\t * When set, a 401 or 403 ApiError from the upstream call is upgraded to\n\t * a {@link PermissionError} carrying these scopes alongside\n\t * {@link OperationLimit.operationKey}, so callers can name the missing\n\t * scope instead of just the HTTP status. Optional so test specs and\n\t * not-yet-wired resources can opt out.\n\t */\n\treadonly requiredScopes?: ReadonlyArray<string>;\n}\n\n/**\n * Single-argument bundle consumed by `ResourceClient.execute`: the per-method\n * spec, the resource-specific parameters, and optional per-request config\n * overrides.\n *\n * @template P - The resource-specific parameter shape the builder accepts.\n * @template T - The resource-specific parsed success type the parser produces.\n */\ninterface ExecuteCall<P, T> {\n\t/** Optional per-request config overrides. */\n\treadonly options?: RequestOptions | undefined;\n\t/** Resource-specific request parameters. */\n\treadonly parameters: P;\n\t/** Per-method binding of builder, parser, method kind, and operation limit. */\n\treadonly spec: ResourceMethodSpec<P, T>;\n}\n\n/**\n * Wraps an infallible request build as a {@link Result}-returning\n * `buildRequest` callback compatible with {@link ResourceMethodSpec}.\n * Use from a resource client whose builder cannot fail; resource clients\n * with local validation should construct the {@link Result} directly.\n *\n * @param request - The pre-built {@link HttpRequest}.\n * @returns A success Result wrapping the request.\n */\nexport function okRequest(request: HttpRequest): Result<HttpRequest, OpenCloudError> {\n\treturn { data: request, success: true };\n}\n\n/**\n * A {@link ResourceMethodSpec.parse} implementation for endpoints that return\n * no business payload on success (such as `DELETE` and reorder operations).\n * Surfaces `undefined` data and never inspects the response body.\n *\n * @returns A success Result with `undefined` data.\n */\nexport function parseEmptyResponse(): Result<undefined, OpenCloudError> {\n\treturn { data: undefined, success: true };\n}\n\nconst CLIENT_DEFAULTS = Object.freeze({\n\tbaseUrl: \"https://apis.roblox.com\",\n\tmaxRetries: 3,\n\tretryableStatuses: IDEMPOTENT_METHOD_DEFAULTS.retryableStatuses,\n\tretryableTransportCodes: IDEMPOTENT_METHOD_DEFAULTS.retryableTransportCodes,\n\tretryDelay: defaultRetryDelay,\n\ttimeout: 30_000,\n} satisfies Except<RetryResolvable, \"apiKey\">);\n\n/**\n * Internal orchestrator shared by every Open Cloud resource client. Holds\n * the frozen client config, observability hooks, injected HTTP client and\n * sleep, and the per-effective-key rate-limit queue registry. Resource\n * classes compose one instance and dispatch every public method through\n * {@link ResourceClient.execute} with a per-method {@link ResourceMethodSpec}.\n * Not exported from any package subpath; reachable only via sibling\n * `src/resources/**` modules in this package.\n */\nexport class ResourceClient {\n\treadonly #config: Readonly<RetryResolvable>;\n\treadonly #hooks: OpenCloudHooks;\n\treadonly #httpClient: HttpClient;\n\treadonly #queues = new Map<string, RateLimitQueue>();\n\treadonly #sleep: SleepFunc;\n\n\t/**\n\t * Creates a new {@link ResourceClient}. Resolves the injected HTTP\n\t * client and sleep (defaulting to fetch + `setTimeout`) and freezes the\n\t * merged client config so subsequent calls cannot mutate it.\n\t *\n\t * @param options - Client-level configuration including the API key\n\t *   and optional construction-time test seams.\n\t */\n\tconstructor(options: OpenCloudClientOptions) {\n\t\tconst { apiKey, hooks, httpClient, sleep, ...overrides } = options;\n\t\tconst resolved = resolveDependencies({ httpClient, sleep });\n\t\tthis.#httpClient = resolved.httpClient;\n\t\tthis.#sleep = resolved.sleep;\n\t\tthis.#hooks = hooks ?? {};\n\t\tthis.#config = Object.freeze({\n\t\t\t...CLIENT_DEFAULTS,\n\t\t\tapiKey,\n\t\t\t...overrides,\n\t\t});\n\t}\n\n\t/**\n\t * Dispatches a single resource-method call. Merges the frozen client\n\t * config with the method's `methodDefaults` and the caller's optional\n\t * per-request `options`, routes through the effective-apiKey rate-limit\n\t * queue, runs the retry loop, and finally parses the response with the\n\t * spec's parser.\n\t *\n\t * @param call - The per-method spec, resource-specific parameters, and\n\t *   optional per-request overrides.\n\t * @returns The parsed success payload or the {@link OpenCloudError} that\n\t *   caused the request to fail. Never throws.\n\t */\n\tpublic async execute<P, T>(call: ExecuteCall<P, T>): Promise<Result<T, OpenCloudError>> {\n\t\tconst { options, parameters, spec } = call;\n\t\tconst merged = mergeConfig(this.#config, {\n\t\t\tmethodDefaults: spec.methodDefaults,\n\t\t\tmethodKind: spec.methodKind,\n\t\t\trequestOptions: options ?? {},\n\t\t});\n\t\tconst requestResult = spec.buildRequest(parameters);\n\t\tif (!requestResult.success) {\n\t\t\treturn requestResult;\n\t\t}\n\n\t\tconst requestConfig = {\n\t\t\tapiKey: merged.apiKey,\n\t\t\tbaseUrl: merged.baseUrl,\n\t\t\ttimeout: merged.timeout,\n\t\t};\n\t\tconst queue = this.#getQueue(merged.apiKey, spec.operationLimit);\n\t\tconst httpResult = await queue.acquire(async () => {\n\t\t\treturn executeWithRetry(requestResult.data, {\n\t\t\t\tconfig: merged,\n\t\t\t\thooks: this.#hooks,\n\t\t\t\tsend: async (toSend) => this.#httpClient.request(toSend, requestConfig),\n\t\t\t\tsleep: this.#sleep,\n\t\t\t});\n\t\t});\n\t\tif (!httpResult.success) {\n\t\t\treturn { err: enrichPermissionError(httpResult.err, spec), success: false };\n\t\t}\n\n\t\treturn spec.parse(httpResult.data);\n\t}\n\n\t/**\n\t * Returns the sleep function used by this client instance.\n\t *\n\t * @returns The sleep function injected at construction time.\n\t */\n\tpublic get sleep(): SleepFunc {\n\t\treturn this.#sleep;\n\t}\n\n\t#getQueue(apiKey: string, limit: OperationLimit): RateLimitQueue {\n\t\tconst key = `${apiKey}::${limit.operationKey}`;\n\t\tconst existing = this.#queues.get(key);\n\t\tif (existing !== undefined) {\n\t\t\treturn existing;\n\t\t}\n\n\t\tconst queue = new RateLimitQueue(limit, this.#hooks, this.#sleep);\n\t\tthis.#queues.set(key, queue);\n\t\treturn queue;\n\t}\n}\n\nfunction enrichPermissionError<P, T>(\n\terr: OpenCloudError,\n\tspec: ResourceMethodSpec<P, T>,\n): OpenCloudError {\n\tif (spec.requiredScopes === undefined) {\n\t\treturn err;\n\t}\n\n\tif (err instanceof PermissionError) {\n\t\treturn err;\n\t}\n\n\tif (!(err instanceof ApiError)) {\n\t\treturn err;\n\t}\n\n\tif (err.statusCode !== 401 && err.statusCode !== 403) {\n\t\treturn err;\n\t}\n\n\treturn new PermissionError(err.message, {\n\t\tcause: err.cause,\n\t\tcode: err.code,\n\t\toperationKey: spec.operationLimit.operationKey,\n\t\trequiredScopes: spec.requiredScopes,\n\t\tstatusCode: err.statusCode,\n\t});\n}\n"],"mappings":"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"}