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

package/dist/retry-BvZRZDXs.mjs

@@ -0,0 +1,380 @@
+import { n as NetworkError, r as ApiError, t as RateLimitError } from "./rate-limit-Dh2leqaB.mjs";
+//#region src/errors/permission-error.ts
+/**
+* Thrown when the Roblox Open Cloud API returns a 401 or 403 for an operation
+* whose required scopes are known. Subclass of {@link ApiError} carrying the
+* scope strings the caller's credential is missing plus the operation key, so
+* a CLI consumer can tell the user exactly which scope to grant on their API
+* key.
+*
+* @since 0.1.0
+*
+* @example
+*
+* ```ts
+* import { PermissionError } from "@bedrock-rbx/ocale";
+*
+* const error = new PermissionError("HTTP 403", {
+*     operationKey: "developer-products.create",
+*     requiredScopes: ["creator-store-product:write"],
+*     statusCode: 403,
+* });
+*
+* expect(error).toBeInstanceOf(PermissionError);
+* expect(error.requiredScopes).toStrictEqual(["creator-store-product:write"]);
+* expect(error.operationKey).toBe("developer-products.create");
+* ```
+*/
+var PermissionError = class extends ApiError {
+	name = "PermissionError";
+	operationKey;
+	requiredScopes;
+	/**
+	* Creates a new PermissionError.
+	*
+	* @param message - Human-readable error description.
+	* @param options - Error options including status code, the operation key,
+	*   and the scopes the caller's credential must carry.
+	*/
+	constructor(message, options) {
+		super(message, options);
+		this.operationKey = options.operationKey;
+		this.requiredScopes = options.requiredScopes;
+	}
+};
+//#endregion
+//#region src/internal/utils/find-error-code.ts
+/**
+* Maximum cause-chain depth walked by {@link findErrorCode}. Caps pathological
+* self-referential or deeply nested chains; transport failures surface as
+* `NetworkError → TypeError("fetch failed") → OS Error{code}`, so three
+* levels is the expected shape and five leaves headroom.
+*/
+const MAX_DEPTH = 5;
+/**
+* Walks an error's `cause` chain and returns the first node-style string
+* `code` it finds (for example `"ECONNRESET"`, `"ETIMEDOUT"`). Native `fetch`
+* surfaces a transport reset as a `NetworkError` wrapping a
+* `TypeError("fetch failed")` whose own cause carries the OS-level `code`, so
+* the code lives several links down the chain.
+*
+* @example
+*
+* ```ts
+* import { findErrorCode } from "./find-error-code";
+*
+* const root = Object.assign(new Error("read ECONNRESET"), { code: "ECONNRESET" });
+* const outer = new Error("Network request failed", {
+*     cause: new TypeError("fetch failed", { cause: root }),
+* });
+*
+* expect(findErrorCode(outer)).toBe("ECONNRESET");
+* ```
+*
+* @param error - The error to inspect; typically a `NetworkError`.
+* @returns The first string `code` in the chain, or `undefined` if none.
+*/
+function findErrorCode(error) {
+	let current = error;
+	for (let depth = 0; depth < MAX_DEPTH && current instanceof Error; depth += 1) {
+		const code = readCode(current);
+		if (code !== void 0) return code;
+		current = current.cause;
+	}
+}
+function readCode(error) {
+	const code = Reflect.get(error, "code");
+	return typeof code === "string" ? code : void 0;
+}
+/**
+* `DOMException.name` produced when an `AbortSignal.timeout` fires. This is the
+* web-standard discriminator (stable across Node and Bun, unlike the
+* runtime-specific message) and distinguishes the SDK's own request timeout
+* from a caller-supplied cancellation, which surfaces as `"AbortError"`.
+*/
+const TIMEOUT_ABORT_NAME = "TimeoutError";
+/**
+* Reports whether an error chain was produced by the SDK's own
+* `AbortSignal.timeout` self-abort. Such a `DOMException` carries a numeric
+* `code` (23), so {@link findErrorCode} (which only reads string codes)
+* cannot classify it; this walk keys on `name` instead. A caller-supplied
+* abort (`"AbortError"`) is deliberately not matched.
+*
+* @example
+*
+* ```ts
+* import { isTimeoutAbort } from "./find-error-code";
+*
+* const error = new Error("Network request failed", {
+*     cause: new DOMException("timed out", "TimeoutError"),
+* });
+*
+* expect(isTimeoutAbort(error)).toBe(true);
+* expect(isTimeoutAbort(new DOMException("cancelled", "AbortError"))).toBe(false);
+* ```
+*
+* @param error - The error to inspect; typically a `NetworkError`.
+* @returns `true` when a `TimeoutError` abort sits within the cause chain.
+*/
+function isTimeoutAbort(error) {
+	let current = error;
+	for (let depth = 0; depth < MAX_DEPTH && current instanceof Error; depth += 1) {
+		if (Reflect.get(current, "name") === TIMEOUT_ABORT_NAME) return true;
+		current = current.cause;
+	}
+	return false;
+}
+//#endregion
+//#region src/internal/http/retry.ts
+/**
+* Transient transport error codes that are safe to retry for idempotent
+* operations. Connection resets, timeouts, and DNS hiccups are recoverable on
+* a retry. A self-aborted request timeout carries no OS-level `code`, so
+* {@link shouldRetry} folds it into this set as `ETIMEDOUT` (via
+* {@link isTimeoutAbort}) for idempotent methods; create methods retry no
+* transport codes and so still never re-issue a timed-out write.
+*
+* @since 0.1.0
+*/
+const TRANSIENT_TRANSPORT_CODES = Object.freeze([
+	"ECONNRESET",
+	"ECONNREFUSED",
+	"ETIMEDOUT",
+	"EPIPE",
+	"ENETUNREACH",
+	"EHOSTDOWN",
+	"EAI_AGAIN",
+	"UND_ERR_SOCKET"
+]);
+/**
+* Default retry policy for idempotent operations (read, list, update,
+* delete). Safe to retry on rate limits, transient server errors, and
+* transient transport failures.
+*/
+const IDEMPOTENT_METHOD_DEFAULTS = Object.freeze({
+	retryableStatuses: Object.freeze([
+		429,
+		500,
+		502,
+		503,
+		504
+	]),
+	retryableTransportCodes: TRANSIENT_TRANSPORT_CODES
+});
+/**
+* Default retry policy for create operations. Retries rate limits only (no
+* 5xx and no transport-error retries) to prevent duplicate resources, since
+* Roblox Open Cloud has no idempotency-key support. Consumers who can tolerate
+* a duplicate opt in per request.
+*/
+const CREATE_METHOD_DEFAULTS = Object.freeze({
+	retryableStatuses: Object.freeze([429]),
+	retryableTransportCodes: Object.freeze([])
+});
+/**
+* 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. {@link RateLimitError}
+* (checked against 429) and {@link ApiError} (checked against its `statusCode`)
+* are retryable when their status is in `retryableStatuses`. A
+* {@link NetworkError} is retryable when its transport code
+* ({@link findErrorCode}) is in `retryableTransportCodes`. This is how
+* transient connection resets recover. A self-aborted request timeout
+* ({@link isTimeoutAbort}) carries no transport code, so it is classified as
+* `ETIMEDOUT`: recovered for idempotent methods, never for creates (whose
+* list is empty). All other failures 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], retryableTransportCodes: [] })).toBe(
+*     true,
+* );
+* ```
+*
+* @example
+*
+* ```ts
+* import { NetworkError } from "../../errors/network-error.ts";
+* import { shouldRetry } from "./retry";
+*
+* const reset = Object.assign(new Error("read ECONNRESET"), { code: "ECONNRESET" });
+* const error = new NetworkError("Network request failed", { cause: reset });
+*
+* expect(
+*     shouldRetry(error, { retryableStatuses: [], retryableTransportCodes: ["ECONNRESET"] }),
+* ).toBe(true);
+* ```
+*
+* @param error - The error returned by the failing request.
+* @param config - Object carrying the retry-eligible status and transport-code lists.
+* @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);
+	if (error instanceof NetworkError) {
+		const code = findErrorCode(error) ?? (isTimeoutAbort(error) ? "ETIMEDOUT" : void 0);
+		return code !== void 0 && config.retryableTransportCodes.includes(code);
+	}
+	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],
+*     retryableTransportCodes: [],
+*     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],
+*     retryableTransportCodes: [],
+*     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
+export { defaultRetryDelay as a, findErrorCode as c, computeRetryWaitMs as i, PermissionError as l, IDEMPOTENT_METHOD_DEFAULTS as n, mergeConfig as o, TRANSIENT_TRANSPORT_CODES as r, shouldRetry as s, CREATE_METHOD_DEFAULTS as t };
+
+//# sourceMappingURL=retry-BvZRZDXs.mjs.map

package/dist/retry-BvZRZDXs.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-BvZRZDXs.mjs","names":["exhaustive"],"sources":["../src/errors/permission-error.ts","../src/internal/utils/find-error-code.ts","../src/internal/http/retry.ts"],"sourcesContent":["import { ApiError, type ApiErrorOptions } from \"./api-error.ts\";\n\n/**\n * Options for constructing a {@link PermissionError}.\n *\n * @since 0.1.0\n */\nexport interface PermissionErrorOptions extends ApiErrorOptions {\n\t/**\n\t * Stable identifier of the Open Cloud operation that returned the\n\t * permission failure (matches `OperationLimit.operationKey`, e.g.\n\t * `\"developer-products.create\"`).\n\t */\n\toperationKey: string;\n\t/**\n\t * Scope strings the API key or OAuth token must carry for the failing\n\t * operation, sourced from the vendored OpenAPI schema's `x-roblox-scopes`\n\t * for that operationId.\n\t */\n\trequiredScopes: ReadonlyArray<string>;\n}\n\n/**\n * Thrown when the Roblox Open Cloud API returns a 401 or 403 for an operation\n * whose required scopes are known. Subclass of {@link ApiError} carrying the\n * scope strings the caller's credential is missing plus the operation key, so\n * a CLI consumer can tell the user exactly which scope to grant on their API\n * key.\n *\n * @since 0.1.0\n *\n * @example\n *\n * ```ts\n * import { PermissionError } from \"@bedrock-rbx/ocale\";\n *\n * const error = new PermissionError(\"HTTP 403\", {\n *     operationKey: \"developer-products.create\",\n *     requiredScopes: [\"creator-store-product:write\"],\n *     statusCode: 403,\n * });\n *\n * expect(error).toBeInstanceOf(PermissionError);\n * expect(error.requiredScopes).toStrictEqual([\"creator-store-product:write\"]);\n * expect(error.operationKey).toBe(\"developer-products.create\");\n * ```\n */\nexport class PermissionError extends ApiError {\n\tpublic override readonly name: string = \"PermissionError\";\n\tpublic readonly operationKey: string;\n\tpublic readonly requiredScopes: ReadonlyArray<string>;\n\n\t/**\n\t * Creates a new PermissionError.\n\t *\n\t * @param message - Human-readable error description.\n\t * @param options - Error options including status code, the operation key,\n\t *   and the scopes the caller's credential must carry.\n\t */\n\tconstructor(message: string, options: PermissionErrorOptions) {\n\t\tsuper(message, options);\n\t\tthis.operationKey = options.operationKey;\n\t\tthis.requiredScopes = options.requiredScopes;\n\t}\n}\n","/**\n * Maximum cause-chain depth walked by {@link findErrorCode}. Caps pathological\n * self-referential or deeply nested chains; transport failures surface as\n * `NetworkError → TypeError(\"fetch failed\") → OS Error{code}`, so three\n * levels is the expected shape and five leaves headroom.\n */\nconst MAX_DEPTH = 5;\n\n/**\n * Walks an error's `cause` chain and returns the first node-style string\n * `code` it finds (for example `\"ECONNRESET\"`, `\"ETIMEDOUT\"`). Native `fetch`\n * surfaces a transport reset as a `NetworkError` wrapping a\n * `TypeError(\"fetch failed\")` whose own cause carries the OS-level `code`, so\n * the code lives several links down the chain.\n *\n * @example\n *\n * ```ts\n * import { findErrorCode } from \"./find-error-code\";\n *\n * const root = Object.assign(new Error(\"read ECONNRESET\"), { code: \"ECONNRESET\" });\n * const outer = new Error(\"Network request failed\", {\n *     cause: new TypeError(\"fetch failed\", { cause: root }),\n * });\n *\n * expect(findErrorCode(outer)).toBe(\"ECONNRESET\");\n * ```\n *\n * @param error - The error to inspect; typically a `NetworkError`.\n * @returns The first string `code` in the chain, or `undefined` if none.\n */\nexport function findErrorCode(error: unknown): string | undefined {\n\tlet current: unknown = error;\n\tfor (let depth = 0; depth < MAX_DEPTH && current instanceof Error; depth += 1) {\n\t\tconst code = readCode(current);\n\t\tif (code !== undefined) {\n\t\t\treturn code;\n\t\t}\n\n\t\tcurrent = current.cause;\n\t}\n\n\treturn undefined;\n}\n\nfunction readCode(error: Error): string | undefined {\n\tconst code = Reflect.get(error, \"code\");\n\treturn typeof code === \"string\" ? code : undefined;\n}\n\n/**\n * `DOMException.name` produced when an `AbortSignal.timeout` fires. This is the\n * web-standard discriminator (stable across Node and Bun, unlike the\n * runtime-specific message) and distinguishes the SDK's own request timeout\n * from a caller-supplied cancellation, which surfaces as `\"AbortError\"`.\n */\nconst TIMEOUT_ABORT_NAME = \"TimeoutError\";\n\n/**\n * Reports whether an error chain was produced by the SDK's own\n * `AbortSignal.timeout` self-abort. Such a `DOMException` carries a numeric\n * `code` (23), so {@link findErrorCode} (which only reads string codes)\n * cannot classify it; this walk keys on `name` instead. A caller-supplied\n * abort (`\"AbortError\"`) is deliberately not matched.\n *\n * @example\n *\n * ```ts\n * import { isTimeoutAbort } from \"./find-error-code\";\n *\n * const error = new Error(\"Network request failed\", {\n *     cause: new DOMException(\"timed out\", \"TimeoutError\"),\n * });\n *\n * expect(isTimeoutAbort(error)).toBe(true);\n * expect(isTimeoutAbort(new DOMException(\"cancelled\", \"AbortError\"))).toBe(false);\n * ```\n *\n * @param error - The error to inspect; typically a `NetworkError`.\n * @returns `true` when a `TimeoutError` abort sits within the cause chain.\n */\nexport function isTimeoutAbort(error: unknown): boolean {\n\tlet current: unknown = error;\n\tfor (let depth = 0; depth < MAX_DEPTH && current instanceof Error; depth += 1) {\n\t\tif (Reflect.get(current, \"name\") === TIMEOUT_ABORT_NAME) {\n\t\t\treturn true;\n\t\t}\n\n\t\tcurrent = current.cause;\n\t}\n\n\treturn false;\n}\n","import { ApiError } from \"../../errors/api-error.ts\";\nimport { NetworkError } from \"../../errors/network-error.ts\";\nimport { RateLimitError } from \"../../errors/rate-limit.ts\";\nimport { findErrorCode, isTimeoutAbort } from \"../utils/find-error-code.ts\";\n\n/**\n * Fully-resolved retry config shape that {@link mergeConfig} and\n * {@link shouldRetry} operate on. Fields are required because this represents\n * the post-defaulting, internal view; callers should supply every field (or\n * resolve them via a test factory / client constructor). The partial,\n * user-facing type lives on client construction options; method defaults and\n * per-request overrides use `Partial<RetryResolvable>`.\n */\nexport interface RetryResolvable {\n\t/** Roblox Open Cloud API key. */\n\treadonly apiKey: string;\n\t/** Base URL for the Open Cloud API. */\n\treadonly baseUrl: string;\n\t/** Maximum retry attempts before giving up. */\n\treadonly maxRetries: number;\n\t/** Status codes that are eligible for retry. */\n\treadonly retryableStatuses: ReadonlyArray<number>;\n\t/**\n\t * Node-style transport error codes ({@link findErrorCode}) eligible for\n\t * retry when surfaced as a {@link NetworkError}. Empty for create\n\t * operations by default; consumers opt a create in via a per-request\n\t * override.\n\t */\n\treadonly retryableTransportCodes: ReadonlyArray<string>;\n\t/** Fallback delay function when no server hint is available. */\n\treadonly retryDelay: (attempt: number) => number;\n\t/** Per-request timeout in milliseconds. */\n\treadonly timeout: number;\n}\n\n/**\n * Transient transport error codes that are safe to retry for idempotent\n * operations. Connection resets, timeouts, and DNS hiccups are recoverable on\n * a retry. A self-aborted request timeout carries no OS-level `code`, so\n * {@link shouldRetry} folds it into this set as `ETIMEDOUT` (via\n * {@link isTimeoutAbort}) for idempotent methods; create methods retry no\n * transport codes and so still never re-issue a timed-out write.\n *\n * @since 0.1.0\n */\nexport const TRANSIENT_TRANSPORT_CODES: ReadonlyArray<string> = Object.freeze([\n\t\"ECONNRESET\",\n\t\"ECONNREFUSED\",\n\t\"ETIMEDOUT\",\n\t\"EPIPE\",\n\t\"ENETUNREACH\",\n\t\"EHOSTDOWN\",\n\t\"EAI_AGAIN\",\n\t\"UND_ERR_SOCKET\",\n]);\n\n/** Method-level retry defaults, keyed by {@link MethodKind}. */\ntype MethodDefaults = Readonly<\n\tPick<RetryResolvable, \"retryableStatuses\" | \"retryableTransportCodes\">\n>;\n\n/**\n * Default retry policy for idempotent operations (read, list, update,\n * delete). Safe to retry on rate limits, transient server errors, and\n * transient transport failures.\n */\nexport const IDEMPOTENT_METHOD_DEFAULTS: MethodDefaults = Object.freeze({\n\tretryableStatuses: Object.freeze([429, 500, 502, 503, 504] as const),\n\tretryableTransportCodes: TRANSIENT_TRANSPORT_CODES,\n});\n\n/**\n * Default retry policy for create operations. Retries rate limits only (no\n * 5xx and no transport-error retries) to prevent duplicate resources, since\n * Roblox Open Cloud has no idempotency-key support. Consumers who can tolerate\n * a duplicate opt in per request.\n */\nexport const CREATE_METHOD_DEFAULTS: MethodDefaults = Object.freeze({\n\tretryableStatuses: Object.freeze([429] as const),\n\tretryableTransportCodes: Object.freeze([] as const),\n});\n\n/** Kind of HTTP method the merge is being performed for. */\nexport type MethodKind = \"create\" | \"idempotent\";\n\n/**\n * Options for {@link mergeConfig}.\n *\n * @template T - Concrete `RetryResolvable` subtype being merged.\n */\ninterface MergeConfigOptions<T> {\n\t/** Method-level defaults (e.g. {@link CREATE_METHOD_DEFAULTS}). */\n\treadonly methodDefaults: Partial<T>;\n\t/** Whether the method is a create or idempotent operation. */\n\treadonly methodKind: MethodKind;\n\t/** Optional per-request overrides; always win when provided. */\n\treadonly requestOptions?: Partial<T>;\n}\n\n/**\n * Options for {@link computeRetryWaitMs}.\n */\ninterface ComputeRetryWaitMsOptions {\n\t/** Zero-indexed retry attempt number. */\n\treadonly attempt: number;\n\t/** Fallback delay function when no server hint is available. */\n\treadonly retryDelay: (attempt: number) => number;\n}\n\n/**\n * Default exponential backoff: 1s → 2s → 4s → 8s → 16s → 30s (capped).\n *\n * @example\n *\n * ```ts\n * import { defaultRetryDelay } from \"./retry\";\n *\n * expect(defaultRetryDelay(0)).toBe(1000);\n * expect(defaultRetryDelay(4)).toBe(16_000);\n * expect(defaultRetryDelay(10)).toBe(30_000);\n * ```\n *\n * @param attempt - Zero-indexed retry attempt number.\n * @returns Wait duration in milliseconds.\n */\nexport function defaultRetryDelay(attempt: number): number {\n\treturn Math.min(1000 * 2 ** attempt, 30_000);\n}\n\n/**\n * Computes how long to wait before the next retry. Prefers the server's\n * suggested delay when the error is a {@link RateLimitError} with a positive\n * `retryAfterSeconds`; otherwise falls through to `retryDelay(attempt)`.\n *\n * @example\n *\n * ```ts\n * import { RateLimitError } from \"../../errors/rate-limit.ts\";\n * import { computeRetryWaitMs, defaultRetryDelay } from \"./retry\";\n *\n * const error = new RateLimitError(\"slow down\", { retryAfterSeconds: 3 });\n *\n * expect(computeRetryWaitMs(error, { attempt: 0, retryDelay: defaultRetryDelay })).toBe(\n *     3000,\n * );\n * ```\n *\n * @example\n *\n * ```ts\n * import { ApiError } from \"../../errors/api-error.ts\";\n * import { computeRetryWaitMs, defaultRetryDelay } from \"./retry\";\n *\n * const error = new ApiError(\"server error\", { statusCode: 503 });\n *\n * expect(computeRetryWaitMs(error, { attempt: 2, retryDelay: defaultRetryDelay })).toBe(\n *     4000,\n * );\n * ```\n *\n * @param error - The error returned by the failing request.\n * @param options - Retry attempt index and fallback delay function.\n * @returns Wait duration in milliseconds before the next attempt.\n */\nexport function computeRetryWaitMs(\n\terror: ApiError | NetworkError | RateLimitError,\n\toptions: ComputeRetryWaitMsOptions,\n): number {\n\tif (error instanceof RateLimitError && error.retryAfterSeconds > 0) {\n\t\treturn error.retryAfterSeconds * 1000;\n\t}\n\n\treturn options.retryDelay(options.attempt);\n}\n\n/**\n * Decides whether a failed request is eligible for retry. {@link RateLimitError}\n * (checked against 429) and {@link ApiError} (checked against its `statusCode`)\n * are retryable when their status is in `retryableStatuses`. A\n * {@link NetworkError} is retryable when its transport code\n * ({@link findErrorCode}) is in `retryableTransportCodes`. This is how\n * transient connection resets recover. A self-aborted request timeout\n * ({@link isTimeoutAbort}) carries no transport code, so it is classified as\n * `ETIMEDOUT`: recovered for idempotent methods, never for creates (whose\n * list is empty). All other failures return `false`.\n *\n * @example\n *\n * ```ts\n * import { RateLimitError } from \"../../errors/rate-limit.ts\";\n * import { shouldRetry } from \"./retry\";\n *\n * const error = new RateLimitError(\"\", { retryAfterSeconds: 1 });\n *\n * expect(shouldRetry(error, { retryableStatuses: [429], retryableTransportCodes: [] })).toBe(\n *     true,\n * );\n * ```\n *\n * @example\n *\n * ```ts\n * import { NetworkError } from \"../../errors/network-error.ts\";\n * import { shouldRetry } from \"./retry\";\n *\n * const reset = Object.assign(new Error(\"read ECONNRESET\"), { code: \"ECONNRESET\" });\n * const error = new NetworkError(\"Network request failed\", { cause: reset });\n *\n * expect(\n *     shouldRetry(error, { retryableStatuses: [], retryableTransportCodes: [\"ECONNRESET\"] }),\n * ).toBe(true);\n * ```\n *\n * @param error - The error returned by the failing request.\n * @param config - Object carrying the retry-eligible status and transport-code lists.\n * @returns `true` if the error should be retried, `false` otherwise.\n */\nexport function shouldRetry(\n\terror: unknown,\n\tconfig: {\n\t\treadonly retryableStatuses: ReadonlyArray<number>;\n\t\treadonly retryableTransportCodes: ReadonlyArray<string>;\n\t},\n): error is ApiError | NetworkError | RateLimitError {\n\tif (error instanceof RateLimitError) {\n\t\treturn config.retryableStatuses.includes(429);\n\t}\n\n\tif (error instanceof ApiError) {\n\t\treturn config.retryableStatuses.includes(error.statusCode);\n\t}\n\n\tif (error instanceof NetworkError) {\n\t\tconst code = findErrorCode(error) ?? (isTimeoutAbort(error) ? \"ETIMEDOUT\" : undefined);\n\t\treturn code !== undefined && config.retryableTransportCodes.includes(code);\n\t}\n\n\treturn false;\n}\n\n/**\n * Resolves the effective config for a single request by shallow-merging the\n * client config, method defaults, and per-request options. Precedence depends\n * on `methodKind`:\n *\n * - `\"create\"`: method defaults override client config, so client-level\n *   settings cannot silently relax create-method safety. Only explicit\n *   per-request `requestOptions` can.\n * - `\"idempotent\"`: client config overrides method defaults, so consumers\n *   can loosen or tighten retry policy globally. `requestOptions` still wins\n *   when provided.\n *\n * Array-valued fields like `retryableStatuses` are *replaced*, not extended.\n *\n * @template T - Concrete `RetryResolvable` subtype being merged.\n *\n * @example\n *\n * ```ts\n * import {\n *     CREATE_METHOD_DEFAULTS,\n *     defaultRetryDelay,\n *     mergeConfig,\n *     type RetryResolvable,\n * } from \"./retry\";\n *\n * const clientConfig: RetryResolvable = {\n *     apiKey: \"k\",\n *     baseUrl: \"https://apis.roblox.com\",\n *     maxRetries: 3,\n *     retryableStatuses: [429, 500],\n *     retryableTransportCodes: [],\n *     retryDelay: defaultRetryDelay,\n *     timeout: 30_000,\n * };\n *\n * const merged = mergeConfig(clientConfig, {\n *     methodDefaults: CREATE_METHOD_DEFAULTS,\n *     methodKind: \"create\",\n * });\n *\n * expect(merged.retryableStatuses).toStrictEqual([429]);\n * ```\n *\n * @example\n *\n * ```ts\n * import {\n *     defaultRetryDelay,\n *     IDEMPOTENT_METHOD_DEFAULTS,\n *     mergeConfig,\n *     type RetryResolvable,\n * } from \"./retry\";\n *\n * const clientConfig: RetryResolvable = {\n *     apiKey: \"k\",\n *     baseUrl: \"https://apis.roblox.com\",\n *     maxRetries: 3,\n *     retryableStatuses: [429],\n *     retryableTransportCodes: [],\n *     retryDelay: defaultRetryDelay,\n *     timeout: 30_000,\n * };\n *\n * const merged = mergeConfig(clientConfig, {\n *     methodDefaults: IDEMPOTENT_METHOD_DEFAULTS,\n *     methodKind: \"idempotent\",\n *     requestOptions: { timeout: 10_000 },\n * });\n *\n * expect(merged.retryableStatuses).toStrictEqual([429]);\n * expect(merged.timeout).toBe(10_000);\n * ```\n *\n * @param clientConfig - Config frozen at client construction.\n * @param options - Method defaults, method kind, and optional per-request overrides.\n * @returns A new merged config object. Inputs are not mutated.\n */\nexport function mergeConfig<T extends RetryResolvable>(\n\tclientConfig: T,\n\toptions: MergeConfigOptions<T>,\n): T {\n\tconst { methodDefaults, methodKind, requestOptions } = options;\n\n\tswitch (methodKind) {\n\t\tcase \"create\": {\n\t\t\treturn { ...clientConfig, ...methodDefaults, ...requestOptions };\n\t\t}\n\t\tcase \"idempotent\": {\n\t\t\treturn { ...methodDefaults, ...clientConfig, ...requestOptions };\n\t\t}\n\t\tdefault: {\n\t\t\tconst exhaustive: never = methodKind;\n\t\t\tthrow new Error(`Unexpected methodKind: ${String(exhaustive)}`);\n\t\t}\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AA+CA,IAAa,kBAAb,cAAqC,SAAS;CAC7C,OAAwC;CACxC;CACA;;;;;;;;CASA,YAAY,SAAiB,SAAiC;EAC7D,MAAM,SAAS,OAAO;EACtB,KAAK,eAAe,QAAQ;EAC5B,KAAK,iBAAiB,QAAQ;CAC/B;AACD;;;;;;;;;AC1DA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;AAyBlB,SAAgB,cAAc,OAAoC;CACjE,IAAI,UAAmB;CACvB,KAAK,IAAI,QAAQ,GAAG,QAAQ,aAAa,mBAAmB,OAAO,SAAS,GAAG;EAC9E,MAAM,OAAO,SAAS,OAAO;EAC7B,IAAI,SAAS,KAAA,GACZ,OAAO;EAGR,UAAU,QAAQ;CACnB;AAGD;AAEA,SAAS,SAAS,OAAkC;CACnD,MAAM,OAAO,QAAQ,IAAI,OAAO,MAAM;CACtC,OAAO,OAAO,SAAS,WAAW,OAAO,KAAA;AAC1C;;;;;;;AAQA,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;AAyB3B,SAAgB,eAAe,OAAyB;CACvD,IAAI,UAAmB;CACvB,KAAK,IAAI,QAAQ,GAAG,QAAQ,aAAa,mBAAmB,OAAO,SAAS,GAAG;EAC9E,IAAI,QAAQ,IAAI,SAAS,MAAM,MAAM,oBACpC,OAAO;EAGR,UAAU,QAAQ;CACnB;CAEA,OAAO;AACR;;;;;;;;;;;;;AC/CA,MAAa,4BAAmD,OAAO,OAAO;CAC7E;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACD,CAAC;;;;;;AAYD,MAAa,6BAA6C,OAAO,OAAO;CACvE,mBAAmB,OAAO,OAAO;EAAC;EAAK;EAAK;EAAK;EAAK;CAAG,CAAU;CACnE,yBAAyB;AAC1B,CAAC;;;;;;;AAQD,MAAa,yBAAyC,OAAO,OAAO;CACnE,mBAAmB,OAAO,OAAO,CAAC,GAAG,CAAU;CAC/C,yBAAyB,OAAO,OAAO,CAAC,CAAU;AACnD,CAAC;;;;;;;;;;;;;;;;;AA6CD,SAAgB,kBAAkB,SAAyB;CAC1D,OAAO,KAAK,IAAI,MAAO,KAAK,SAAS,GAAM;AAC5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,SAAgB,mBACf,OACA,SACS;CACT,IAAI,iBAAiB,kBAAkB,MAAM,oBAAoB,GAChE,OAAO,MAAM,oBAAoB;CAGlC,OAAO,QAAQ,WAAW,QAAQ,OAAO;AAC1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CA,SAAgB,YACf,OACA,QAIoD;CACpD,IAAI,iBAAiB,gBACpB,OAAO,OAAO,kBAAkB,SAAS,GAAG;CAG7C,IAAI,iBAAiB,UACpB,OAAO,OAAO,kBAAkB,SAAS,MAAM,UAAU;CAG1D,IAAI,iBAAiB,cAAc;EAClC,MAAM,OAAO,cAAc,KAAK,MAAM,eAAe,KAAK,IAAI,cAAc,KAAA;EAC5E,OAAO,SAAS,KAAA,KAAa,OAAO,wBAAwB,SAAS,IAAI;CAC1E;CAEA,OAAO;AACR;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgFA,SAAgB,YACf,cACA,SACI;CACJ,MAAM,EAAE,gBAAgB,YAAY,mBAAmB;CAEvD,QAAQ,YAAR;EACC,KAAK,UACJ,OAAO;GAAE,GAAG;GAAc,GAAG;GAAgB,GAAG;EAAe;EAEhE,KAAK,cACJ,OAAO;GAAE,GAAG;GAAgB,GAAG;GAAc,GAAG;EAAe;EAEhE,SAEC,MAAM,IAAI,MAAM,0BAA0B,OAAOA,UAAU,GAAG;CAEhE;AACD"}

package/dist/{signatures-B5Fojgn0.mjs → signatures-JF-7Psce.mjs}

@@ -56,4 +56,4 @@ function matchesSignature(body, signature) {
 //#endregion
 export { RBXL_SIGNATURE as n, matchesSignature as r, RBXLX_SIGNATURE as t };
 
-//# sourceMappingURL=signatures-B5Fojgn0.mjs.map
+//# sourceMappingURL=signatures-JF-7Psce.mjs.map

package/dist/{signatures-B5Fojgn0.mjs.map → signatures-JF-7Psce.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"signatures-B5Fojgn0.mjs","names":[],"sources":["../src/domains/universes/places/signatures.ts"],"sourcesContent":["/**\n * Magic-byte prefix every Roblox binary place file (`.rbxl`) starts with.\n * The first 8 bytes spell out `<roblox!` in ASCII; the remaining 6 bytes\n * (`\\x89\\xff\\r\\n\\x1a\\n`) are the binary-format marker that distinguishes a\n * binary place file from the XML form (`.rbxlx`), whose ASCII-only header\n * begins with `<roblox `.\n */\nexport const RBXL_SIGNATURE: Readonly<Uint8Array<ArrayBuffer>> = new Uint8Array([\n\t0x3c, 0x72, 0x6f, 0x62, 0x6c, 0x6f, 0x78, 0x21, 0x89, 0xff, 0x0d, 0x0a, 0x1a, 0x0a,\n]);\n\n/**\n * Magic-byte prefix every Roblox XML place file (`.rbxlx`) starts with.\n * Equivalent to the ASCII string `<roblox ` (note the trailing space): a\n * well-formed rbxlx file opens with `<roblox` followed by attributes, while\n * an rbxl file uses `<roblox!` (exclamation mark) as the eighth byte. The\n * trailing space is what proves the file is the XML variant rather than\n * the binary one.\n */\nexport const RBXLX_SIGNATURE: Readonly<Uint8Array<ArrayBuffer>> = new Uint8Array([\n\t0x3c, 0x72, 0x6f, 0x62, 0x6c, 0x6f, 0x78, 0x20,\n]);\n\n/**\n * Reports whether `body` begins with `signature`. A pure byte-prefix check\n * with no allocation; used by the place builder to disambiguate `.rbxl` and\n * `.rbxlx` payloads against their declared `format`.\n *\n * @param body - The caller-supplied place file bytes.\n * @param signature - One of the frozen signature constants from this module.\n * @returns `true` if every byte of `signature` matches `body[0..signature.length]`.\n */\nexport function matchesSignature(\n\tbody: Uint8Array,\n\tsignature: Readonly<Uint8Array<ArrayBuffer>>,\n): boolean {\n\tfor (const [index, expected] of signature.entries()) {\n\t\tif (body[index] !== expected) {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\treturn true;\n}\n"],"mappings":";;;;;;;;AAOA,MAAa,iBAAoD,IAAI,WAAW;CAC/E;CAAM;CAAM;CAAM;CAAM;CAAM;CAAM;CAAM;CAAM;CAAM;CAAM;CAAM;CAAM;CAAM;CAC9E,CAAC;;;;;;;;;AAUF,MAAa,kBAAqD,IAAI,WAAW;CAChF;CAAM;CAAM;CAAM;CAAM;CAAM;CAAM;CAAM;CAC1C,CAAC;;;;;;;;;;AAWF,SAAgB,iBACf,MACA,WACU;AACV,MAAK,MAAM,CAAC,OAAO,aAAa,UAAU,SAAS,CAClD,KAAI,KAAK,WAAW,SACnB,QAAO;AAIT,QAAO"}
+{"version":3,"file":"signatures-JF-7Psce.mjs","names":[],"sources":["../src/domains/universes/places/signatures.ts"],"sourcesContent":["/**\n * Magic-byte prefix every Roblox binary place file (`.rbxl`) starts with.\n * The first 8 bytes spell out `<roblox!` in ASCII; the remaining 6 bytes\n * (`\\x89\\xff\\r\\n\\x1a\\n`) are the binary-format marker that distinguishes a\n * binary place file from the XML form (`.rbxlx`), whose ASCII-only header\n * begins with `<roblox `.\n */\nexport const RBXL_SIGNATURE: Readonly<Uint8Array<ArrayBuffer>> = new Uint8Array([\n\t0x3c, 0x72, 0x6f, 0x62, 0x6c, 0x6f, 0x78, 0x21, 0x89, 0xff, 0x0d, 0x0a, 0x1a, 0x0a,\n]);\n\n/**\n * Magic-byte prefix every Roblox XML place file (`.rbxlx`) starts with.\n * Equivalent to the ASCII string `<roblox ` (note the trailing space): a\n * well-formed rbxlx file opens with `<roblox` followed by attributes, while\n * an rbxl file uses `<roblox!` (exclamation mark) as the eighth byte. The\n * trailing space is what proves the file is the XML variant rather than\n * the binary one.\n */\nexport const RBXLX_SIGNATURE: Readonly<Uint8Array<ArrayBuffer>> = new Uint8Array([\n\t0x3c, 0x72, 0x6f, 0x62, 0x6c, 0x6f, 0x78, 0x20,\n]);\n\n/**\n * Reports whether `body` begins with `signature`. A pure byte-prefix check\n * with no allocation; used by the place builder to disambiguate `.rbxl` and\n * `.rbxlx` payloads against their declared `format`.\n *\n * @param body - The caller-supplied place file bytes.\n * @param signature - One of the frozen signature constants from this module.\n * @returns `true` if every byte of `signature` matches `body[0..signature.length]`.\n */\nexport function matchesSignature(\n\tbody: Uint8Array,\n\tsignature: Readonly<Uint8Array<ArrayBuffer>>,\n): boolean {\n\tfor (const [index, expected] of signature.entries()) {\n\t\tif (body[index] !== expected) {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\treturn true;\n}\n"],"mappings":";;;;;;;;AAOA,MAAa,iBAAoD,IAAI,WAAW;CAC/E;CAAM;CAAM;CAAM;CAAM;CAAM;CAAM;CAAM;CAAM;CAAM;CAAM;CAAM;CAAM;CAAM;AAC/E,CAAC;;;;;;;;;AAUD,MAAa,kBAAqD,IAAI,WAAW;CAChF;CAAM;CAAM;CAAM;CAAM;CAAM;CAAM;CAAM;AAC3C,CAAC;;;;;;;;;;AAWD,SAAgB,iBACf,MACA,WACU;CACV,KAAK,MAAM,CAAC,OAAO,aAAa,UAAU,QAAQ,GACjD,IAAI,KAAK,WAAW,UACnB,OAAO;CAIT,OAAO;AACR"}

package/dist/storage.d.mts

@@ -1,9 +1,12 @@
-import { d as OpenCloudError, i as OpenCloudClientOptions, l as Result, n as HttpRequest, r as HttpResponse, s as RequestOptions, u as SleepFunc } from "./types-CwtZT1ek.mjs";
+import { d as OpenCloudError, i as OpenCloudClientOptions, l as Result, n as HttpRequest, r as HttpResponse, s as RequestOptions, u as SleepFunc } from "./types-CRiJg5EQ.mjs";
+import { n as RetryResolvable, t as MethodKind } from "./retry-Bh2nNjBV.mjs";
 
 //#region src/domains/cloud-v2/memory-store-queues/types.d.ts
 /**
 * Caller-supplied input for the `enqueue` method on `StorageClient.queues`.
 * Mirrors `Cloud_CreateMemoryStoreQueueItem` on the Open Cloud API.
+*
+* @since 0.1.0
 */
 interface EnqueueQueueItemParameters {
   /**
@@ -34,6 +37,8 @@ interface EnqueueQueueItemParameters {
 * Parsed representation of a memory-store queue item, as returned by the
 * Open Cloud `Cloud_CreateMemoryStoreQueueItem` and (inside the array)
 * `Cloud_ReadMemoryStoreQueueItems` endpoints.
+*
+* @since 0.1.0
 */
 interface QueueItem {
   /** Server-generated item identifier, parsed from the wire `path`. */
@@ -55,6 +60,8 @@ interface QueueItem {
 /**
 * Caller-supplied input for the `dequeue` method on
 * `StorageClient.queues`. Mirrors `Cloud_ReadMemoryStoreQueueItems`.
+*
+* @since 0.1.0
 */
 interface DequeueQueueItemsParameters {
   /**
@@ -84,6 +91,8 @@ interface DequeueQueueItemsParameters {
 * response. The `readId` value must be passed to a subsequent
 * `discard` call to acknowledge the items; otherwise the items reappear
 * once the invisibility window elapses.
+*
+* @since 0.1.0
 */
 interface DequeueResult {
   /** Items dequeued from the front of the queue, in dequeue order. */
@@ -100,6 +109,8 @@ interface DequeueResult {
 * Acknowledging a `readId` removes the dequeued batch from the queue
 * permanently; without `discard`, the items reappear once their
 * invisibility window elapses.
+*
+* @since 0.1.0
 */
 interface DiscardQueueItemsParameters {
   /** Stringified queue identifier. */
@@ -116,6 +127,8 @@ interface DiscardQueueItemsParameters {
 * server contract requires at most one of `stringSortKey` or
 * `numericSortKey`; the union surfaces that constraint at the type
 * level so callers cannot accidentally set both.
+*
+* @since 0.1.0
 */
 type SortKey = {
   readonly kind: "numeric";
@@ -128,6 +141,8 @@ type SortKey = {
 * Caller-supplied input for the `create` method on
 * `StorageClient.sortedMaps`. Mirrors
 * `Cloud_CreateMemoryStoreSortedMapItem` on the Open Cloud API.
+*
+* @since 0.1.0
 */
 interface CreateSortedMapItemParameters {
   /**
@@ -159,6 +174,8 @@ interface CreateSortedMapItemParameters {
 * `Cloud_ListMemoryStoreSortedMapItems` on the Open Cloud API. All
 * paging and filtering parameters are optional; omitting them returns
 * up to one item server-side (`maxPageSize` defaults to `1`).
+*
+* @since 0.1.0
 */
 interface ListSortedMapItemsParameters {
   /**
@@ -190,6 +207,8 @@ interface ListSortedMapItemsParameters {
 /**
 * Parsed representation of a sorted-map item, as returned by every
 * sorted-map operation that yields a single item.
+*
+* @since 0.1.0
 */
 interface SortedMapItem {
   /** Item identifier, parsed from the wire `path`. */
@@ -221,6 +240,8 @@ interface SortedMapItem {
 /**
 * Parsed result of a successful `Cloud_ListMemoryStoreSortedMapItems`
 * response.
+*
+* @since 0.1.0
 */
 interface ListSortedMapItemsResult {
   /** Items returned in the current page, ordered per `orderBy`. */
@@ -235,6 +256,8 @@ interface ListSortedMapItemsResult {
 * Caller-supplied input for the `delete` method on
 * `StorageClient.sortedMaps`. Mirrors
 * `Cloud_DeleteMemoryStoreSortedMapItem` on the Open Cloud API.
+*
+* @since 0.1.0
 */
 interface DeleteSortedMapItemParameters {
   /** Caller-supplied item identifier. URL-encoded by the builder. */
@@ -248,6 +271,8 @@ interface DeleteSortedMapItemParameters {
 * Caller-supplied input for the `get` method on
 * `StorageClient.sortedMaps`. Mirrors
 * `Cloud_GetMemoryStoreSortedMapItem` on the Open Cloud API.
+*
+* @since 0.1.0
 */
 interface GetSortedMapItemParameters {
   /** Caller-supplied item identifier. URL-encoded by the builder. */
@@ -263,6 +288,8 @@ interface GetSortedMapItemParameters {
 * `Cloud_UpdateMemoryStoreSortedMapItem` on the Open Cloud API. Body
 * fields (`value`, `ttl`, `sortKey`) are optional under PATCH
 * semantics; omitted fields are left unchanged on the server.
+*
+* @since 0.1.0
 */
 interface UpdateSortedMapItemParameters {
   /**
@@ -308,32 +335,6 @@ interface OperationLimit {
   readonly operationKey: string;
 }
 //#endregion
-//#region src/internal/http/retry.d.ts
-/**
-* Fully-resolved retry config shape that {@link mergeConfig} and
-* {@link shouldRetry} operate on. Fields are required because this represents
-* the post-defaulting, internal view — callers should supply every field (or
-* resolve them via a test factory / client constructor). The partial,
-* user-facing type lives on client construction options; method defaults and
-* per-request overrides use `Partial<RetryResolvable>`.
-*/
-interface RetryResolvable {
-  /** Roblox Open Cloud API key. */
-  readonly apiKey: string;
-  /** Base URL for the Open Cloud API. */
-  readonly baseUrl: string;
-  /** Maximum retry attempts before giving up. */
-  readonly maxRetries: number;
-  /** Status codes that are eligible for retry. */
-  readonly retryableStatuses: ReadonlyArray<number>;
-  /** Fallback delay function when no server hint is available. */
-  readonly retryDelay: (attempt: number) => number;
-  /** Per-request timeout in milliseconds. */
-  readonly timeout: number;
-}
-/** Kind of HTTP method the merge is being performed for. */
-type MethodKind = "create" | "idempotent";
-//#endregion
 //#region src/internal/resource-client.d.ts
 /**
 * Describes a single resource method's shape for dispatch through
@@ -635,6 +636,8 @@ declare class MemoryStoreSortedMapsGroup {
 * Every method returns a `Result` so callers handle failure
 * explicitly; no thrown error ever escapes the client.
 *
+* @since 0.1.0
+*
 * @example
 *
 * ```ts

package/dist/storage.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.d.mts","names":[],"sources":["../src/domains/cloud-v2/memory-store-queues/types.ts","../src/domains/cloud-v2/memory-store-sorted-maps/types.ts","../src/internal/http/rate-limit-queue.ts","../src/internal/http/retry.ts","../src/internal/resource-client.ts","../src/resources/storage/queues-group.ts","../src/resources/storage/sorted-maps-group.ts","../src/resources/storage/client.ts"],"mappings":"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"}
+{"version":3,"file":"storage.d.mts","names":[],"sources":["../src/domains/cloud-v2/memory-store-queues/types.ts","../src/domains/cloud-v2/memory-store-sorted-maps/types.ts","../src/internal/http/rate-limit-queue.ts","../src/internal/resource-client.ts","../src/resources/storage/queues-group.ts","../src/resources/storage/sorted-maps-group.ts","../src/resources/storage/client.ts"],"mappings":"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"}