@bedrock-rbx/ocale 0.1.0-beta.1

package/dist/resource-client-CaS_j3yg.mjs

@@ -0,0 +1,652 @@
+import { i as ApiError, n as PermissionError, r as NetworkError, t as RateLimitError } from "./rate-limit-BBU_4xnZ.mjs";
+import { setTimeout } from "node:timers/promises";
+//#region src/internal/utils/is-record.ts
+/**
+* Narrows `value` to a plain JSON-style record. Excludes arrays, class
+* instances, primitives, and `null`/`undefined`. Used by resource
+* parsers to gate property access on wire bodies whose shape isn't
+* known at compile time.
+*
+* @param value - The unknown value to narrow.
+* @returns `true` when `value` is a plain `[object Object]`.
+*/
+function isRecord(value) {
+	return Object.prototype.toString.call(value) === "[object Object]";
+}
+//#endregion
+//#region src/internal/http/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,
+* looping over `options.send` until it succeeds, the error is non-retryable,
+* or `options.config.maxRetries` is exhausted. Fires observability hooks
+* at each transition. Domain- and queue-agnostic: `send` may be any
+* callback, including one wrapped by a rate-limit queue.
+*
+* @param request - The immutable request to send.
+* @param options - The transport callback, resolved config, hooks, and sleep.
+* @returns The first success, or the final error after retries are exhausted.
+*/
+async function executeWithRetry(request, options) {
+	const { config, hooks, send, sleep } = options;
+	async function attempt() {
+		hooks.onRequest?.(request);
+		return send(request);
+	}
+	let result = await attempt();
+	for (let retry = 0; retry < config.maxRetries; retry++) {
+		if (result.success || !shouldRetry(result.err, config)) return result;
+		const { err } = result;
+		hooks.onRetry?.(retry + 1, err);
+		const waitMs = computeRetryWaitMs(err, {
+			attempt: retry,
+			retryDelay: config.retryDelay
+		});
+		hooks.onRateLimit?.(waitMs);
+		await sleep(waitMs);
+		result = await attempt();
+	}
+	return result;
+}
+//#endregion
+//#region src/internal/http/rate-limit-queue.ts
+/**
+* Token-bucket rate limiter for a single `(apiKey, operation)` pair. Every
+* call to `acquire` consumes one token; when the bucket is empty the call
+* waits until a token regenerates before invoking the task. Burst capacity
+* equals `maxPerSecond`, refilling at `maxPerSecond` tokens per second.
+*
+* Implemented as a leaky bucket tracking drain debt in ms. `#lastCheck`
+* advances by `waitMs` after every sleep so the algorithm stays correct
+* whether or not the injected sleep moves `Date.now()` forward.
+*/
+var RateLimitQueue = class {
+	#hooks;
+	#intervalMs;
+	#maxBucketLevel;
+	#sleep;
+	#bucketLevel = 0;
+	#chain = Promise.resolve();
+	#lastCheck = Date.now();
+	/**
+	* Creates a rate-limit queue bound to a single operation.
+	*
+	* @param limit - The operation key and its per-second request ceiling.
+	* @param hooks - Observability callbacks; `onRateLimit` fires when the
+	*   bucket is empty and a sleep is about to start.
+	* @param sleep - Injectable sleep (tests pass a fake).
+	*/
+	constructor(limit, hooks, sleep) {
+		this.#intervalMs = 1e3 / limit.maxPerSecond;
+		this.#maxBucketLevel = limit.maxPerSecond * this.#intervalMs;
+		this.#hooks = hooks;
+		this.#sleep = sleep;
+	}
+	/**
+	* Waits for a token — sleeping and firing `hooks.onRateLimit` if the
+	* bucket is empty — then executes `task`. Concurrent callers are
+	* serialized at token acquisition; tasks themselves run independently
+	* once their token is secured.
+	*
+	* @param task - The request to run once a token is available.
+	* @returns The value produced by `task`.
+	*/
+	async acquire(task) {
+		const myTurn = this.#chain.then(async () => this.#waitForToken());
+		this.#chain = myTurn;
+		await myTurn;
+		return task();
+	}
+	async #waitForToken() {
+		const now = Math.max(Date.now(), this.#lastCheck);
+		const drained = Math.max(0, this.#bucketLevel - (now - this.#lastCheck));
+		this.#lastCheck = now;
+		if (drained + this.#intervalMs <= this.#maxBucketLevel) {
+			this.#bucketLevel = drained + this.#intervalMs;
+			return;
+		}
+		const waitMs = drained + this.#intervalMs - this.#maxBucketLevel;
+		this.#hooks.onRateLimit?.(waitMs);
+		await this.#sleep(waitMs);
+		this.#bucketLevel = this.#maxBucketLevel;
+		this.#lastCheck = now + waitMs;
+	}
+};
+//#endregion
+//#region src/internal/utils/try-catch.ts
+/**
+* Wraps a promise into a {@link Result}, catching rejections.
+*
+* @template T - The resolved value type.
+* @param promise - The promise to wrap.
+* @returns A Result containing the resolved value or the rejection error.
+*/
+async function tryCatch(promise) {
+	try {
+		return {
+			data: await promise,
+			success: true
+		};
+	} catch (err) {
+		return {
+			err: err instanceof Error ? err : new Error(String(err)),
+			success: false
+		};
+	}
+}
+//#endregion
+//#region src/internal/http/fetch-client.ts
+/**
+* Converts a `Headers` object to a plain record with lowercased keys.
+*
+* @param headers - The `Headers` instance to convert.
+* @returns A record mapping lowercased header names to their values.
+*/
+function headersToRecord(headers) {
+	return Object.fromEntries(headers);
+}
+/**
+* Permissively extracts a top-level `errorCode` string field from a
+* response body.
+*
+* @param body - The parsed response body (unknown shape).
+* @returns The `errorCode` string if present, otherwise `undefined`.
+*/
+function extractErrorCode(body) {
+	if (body === null || typeof body !== "object") return;
+	const errorCode = Reflect.get(body, "errorCode");
+	return typeof errorCode === "string" ? errorCode : void 0;
+}
+/**
+* Parses the `x-ratelimit-reset` header value into seconds.
+*
+* @param headerValue - The raw header value, or `undefined` if missing.
+* @returns The number of seconds to wait, or 0 if missing/invalid.
+*/
+function parseRetryAfterSeconds(headerValue) {
+	const parsed = Number(headerValue);
+	if (Number.isNaN(parsed)) return 0;
+	return Math.max(0, Math.floor(parsed));
+}
+/**
+* Joins the base URL from config with the relative path from the request.
+*
+* @param request - The HTTP request containing the relative URL.
+* @param config - The request config containing the base URL.
+* @returns The fully-qualified URL string.
+*/
+function buildUrl(request, config) {
+	return `${config.baseUrl.endsWith("/") ? config.baseUrl.slice(0, -1) : config.baseUrl}${request.url}`;
+}
+/**
+* Constructs the `RequestInit` options for a `fetch` call.
+*
+* @param request - The HTTP request to build options for.
+* @param config - The request config containing API key and timeout.
+* @returns A `RequestInit` object ready for `fetch`.
+*/
+function buildFetchOptions(request, config) {
+	const headers = new Headers({ "x-api-key": config.apiKey });
+	const options = {
+		headers,
+		method: request.method
+	};
+	if (request.body instanceof FormData) options.body = request.body;
+	else if (request.body instanceof Uint8Array) {
+		headers.set("content-type", "application/octet-stream");
+		options.body = request.body;
+	} else if (request.body !== void 0) {
+		headers.set("content-type", "application/json");
+		options.body = JSON.stringify(request.body);
+	}
+	if (request.headers !== void 0) for (const [name, value] of Object.entries(request.headers)) {
+		if (name.toLowerCase() === "x-api-key") continue;
+		headers.set(name, value);
+	}
+	if (config.timeout !== void 0) options.signal = AbortSignal.timeout(config.timeout);
+	return options;
+}
+/**
+* Creates an {@link HttpClient} backed by the Fetch API.
+*
+* @param fetchFunc - The fetch implementation to use. Defaults to `globalThis.fetch`.
+* @returns An HttpClient that classifies responses into typed Results.
+*/
+function createFetchHttpClient(fetchFunc = globalThis.fetch) {
+	return { async request(httpRequest, config) {
+		const fetchResult = await tryCatch(fetchFunc(buildUrl(httpRequest, config), buildFetchOptions(httpRequest, config)));
+		if (!fetchResult.success) return {
+			err: new NetworkError("Network request failed", { cause: fetchResult.err }),
+			success: false
+		};
+		return classifyResponse(fetchResult.data);
+	} };
+}
+function createApiError(status, body) {
+	return new ApiError(`HTTP ${status}`, {
+		code: extractErrorCode(body),
+		statusCode: status
+	});
+}
+/**
+* Classifies a fetch `Response` into a typed `Result`.
+*
+* @param response - The raw fetch Response to classify.
+* @returns A Result containing an HttpResponse on success or an OpenCloudError on failure.
+*/
+function createRateLimitError(response) {
+	return new RateLimitError("Rate limited", { retryAfterSeconds: parseRetryAfterSeconds(response.headers.get("x-ratelimit-reset") ?? void 0) });
+}
+async function readResponseBody(response) {
+	try {
+		const text = await response.text();
+		return {
+			data: text === "" ? void 0 : JSON.parse(text),
+			success: true
+		};
+	} catch {
+		return {
+			err: new ApiError("Failed to parse response body", { statusCode: response.status }),
+			success: false
+		};
+	}
+}
+async function classifyResponse(response) {
+	if (response.status === 429) return {
+		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),
+		success: false
+	};
+	return {
+		data: {
+			body: bodyResult.data,
+			headers: headersToRecord(response.headers),
+			status: response.status
+		},
+		success: true
+	};
+}
+//#endregion
+//#region src/internal/http/resolve-dependencies.ts
+/**
+* Resolves the concrete HTTP client and sleep implementation a resource
+* client should use. Falls back to the fetch-backed HTTP client and the
+* default `setTimeout`-based sleep when the caller omits the test seams.
+*
+* Extracted so resource client constructors can keep their dependency
+* resolution logic in a single, unit-testable place; this makes the
+* default branches easy to cover without stubbing globals like `fetch`.
+*
+* @param options - Optional {@link HttpClient} and {@link SleepFunc} test seams.
+* @returns A {@link ResolvedDependencies} with defaults applied.
+*/
+function resolveDependencies(options) {
+	return {
+		httpClient: options.httpClient ?? createFetchHttpClient(),
+		sleep: options.sleep ?? setTimeout
+	};
+}
+//#endregion
+//#region src/internal/resource-client.ts
+/**
+* Wraps an infallible request build as a {@link Result}-returning
+* `buildRequest` callback compatible with {@link ResourceMethodSpec}.
+* Use from a resource client whose builder cannot fail; resource clients
+* with local validation should construct the {@link Result} directly.
+*
+* @param request - The pre-built {@link HttpRequest}.
+* @returns A success Result wrapping the request.
+*/
+function okRequest(request) {
+	return {
+		data: request,
+		success: true
+	};
+}
+/**
+* A {@link ResourceMethodSpec.parse} implementation for endpoints that return
+* no business payload on success (such as `DELETE` and reorder operations).
+* Surfaces `undefined` data and never inspects the response body.
+*
+* @returns A success Result with `undefined` data.
+*/
+function parseEmptyResponse() {
+	return {
+		data: void 0,
+		success: true
+	};
+}
+const CLIENT_DEFAULTS = Object.freeze({
+	baseUrl: "https://apis.roblox.com",
+	maxRetries: 3,
+	retryableStatuses: IDEMPOTENT_METHOD_DEFAULTS.retryableStatuses,
+	retryDelay: defaultRetryDelay,
+	timeout: 3e4
+});
+/**
+* Internal orchestrator shared by every Open Cloud resource client. Holds
+* the frozen client config, observability hooks, injected HTTP client and
+* sleep, and the per-effective-key rate-limit queue registry. Resource
+* classes compose one instance and dispatch every public method through
+* {@link ResourceClient.execute} with a per-method {@link ResourceMethodSpec}.
+* Not exported from any package subpath; reachable only via sibling
+* `src/resources/**` modules in this package.
+*/
+var ResourceClient = class {
+	#config;
+	#hooks;
+	#httpClient;
+	#queues = /* @__PURE__ */ new Map();
+	#sleep;
+	/**
+	* Creates a new {@link ResourceClient}. Resolves the injected HTTP
+	* client and sleep (defaulting to fetch + `setTimeout`) and freezes the
+	* merged client config so subsequent calls cannot mutate it.
+	*
+	* @param options - Client-level configuration including the API key
+	*   and optional construction-time test seams.
+	*/
+	constructor(options) {
+		const { apiKey, hooks, httpClient, sleep, ...overrides } = options;
+		const resolved = resolveDependencies({
+			httpClient,
+			sleep
+		});
+		this.#httpClient = resolved.httpClient;
+		this.#sleep = resolved.sleep;
+		this.#hooks = hooks ?? {};
+		this.#config = Object.freeze({
+			...CLIENT_DEFAULTS,
+			apiKey,
+			...overrides
+		});
+	}
+	/**
+	* Dispatches a single resource-method call. Merges the frozen client
+	* config with the method's `methodDefaults` and the caller's optional
+	* per-request `options`, routes through the effective-apiKey rate-limit
+	* queue, runs the retry loop, and finally parses the response with the
+	* spec's parser.
+	*
+	* @param call - The per-method spec, resource-specific parameters, and
+	*   optional per-request overrides.
+	* @returns The parsed success payload or the {@link OpenCloudError} that
+	*   caused the request to fail. Never throws.
+	*/
+	async execute(call) {
+		const { options, parameters, spec } = call;
+		const merged = mergeConfig(this.#config, {
+			methodDefaults: spec.methodDefaults,
+			methodKind: spec.methodKind,
+			requestOptions: options ?? {}
+		});
+		const requestResult = spec.buildRequest(parameters);
+		if (!requestResult.success) return requestResult;
+		const requestConfig = {
+			apiKey: merged.apiKey,
+			baseUrl: merged.baseUrl,
+			timeout: merged.timeout
+		};
+		const httpResult = await this.#getQueue(merged.apiKey, spec.operationLimit).acquire(async () => {
+			return executeWithRetry(requestResult.data, {
+				config: merged,
+				hooks: this.#hooks,
+				send: async (toSend) => this.#httpClient.request(toSend, requestConfig),
+				sleep: this.#sleep
+			});
+		});
+		if (!httpResult.success) return {
+			err: enrichPermissionError(httpResult.err, spec),
+			success: false
+		};
+		return spec.parse(httpResult.data);
+	}
+	#getQueue(apiKey, limit) {
+		const key = `${apiKey}::${limit.operationKey}`;
+		const existing = this.#queues.get(key);
+		if (existing !== void 0) return existing;
+		const queue = new RateLimitQueue(limit, this.#hooks, this.#sleep);
+		this.#queues.set(key, queue);
+		return queue;
+	}
+};
+function enrichPermissionError(err, spec) {
+	if (spec.requiredScopes === void 0) return err;
+	if (err instanceof PermissionError) return err;
+	if (!(err instanceof ApiError)) return err;
+	if (err.statusCode !== 401 && err.statusCode !== 403) return err;
+	return new PermissionError(err.message, {
+		cause: err.cause,
+		code: err.code,
+		operationKey: spec.operationLimit.operationKey,
+		requiredScopes: spec.requiredScopes,
+		statusCode: err.statusCode
+	});
+}
+//#endregion
+export { IDEMPOTENT_METHOD_DEFAULTS as a, CREATE_METHOD_DEFAULTS as i, okRequest as n, isRecord as o, parseEmptyResponse as r, ResourceClient as t };
+
+//# sourceMappingURL=resource-client-CaS_j3yg.mjs.map