@bedrock-rbx/ocale 0.1.4 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. package/dist/badges.mjs +3 -3
  2. package/dist/developer-products.mjs +4 -4
  3. package/dist/game-passes.mjs +4 -4
  4. package/dist/index.d.mts +2 -2
  5. package/dist/index.mjs +5 -5
  6. package/dist/luau-execution.mjs +4 -4
  7. package/dist/places.mjs +5 -5
  8. package/dist/{poll-timeout-DXfJVZzR.mjs → poll-timeout-VZuy48ii.mjs} +2 -2
  9. package/dist/{poll-timeout-DXfJVZzR.mjs.map → poll-timeout-VZuy48ii.mjs.map} +1 -1
  10. package/dist/{polling-helpers-SBN188o5.mjs → polling-helpers-O2Pk3rN0.mjs} +12 -6
  11. package/dist/{polling-helpers-SBN188o5.mjs.map → polling-helpers-O2Pk3rN0.mjs.map} +1 -1
  12. package/dist/{price-information-DziMfTQ6.mjs → price-information-CBkLZjYs.mjs} +2 -2
  13. package/dist/{price-information-DziMfTQ6.mjs.map → price-information-CBkLZjYs.mjs.map} +1 -1
  14. package/dist/{rate-limit-B20REZEY.mjs → rate-limit-D1MQZNAE.mjs} +3 -1
  15. package/dist/rate-limit-D1MQZNAE.mjs.map +1 -0
  16. package/dist/{resource-client-rQ9bBn4L.mjs → resource-client-6KaHBVI7.mjs} +56 -40
  17. package/dist/resource-client-6KaHBVI7.mjs.map +1 -0
  18. package/dist/{retry-PmpgEwFN.mjs → retry-D1HKlycK.mjs} +35 -7
  19. package/dist/retry-D1HKlycK.mjs.map +1 -0
  20. package/dist/{retry-DGY51INM.d.mts → retry-DANH6mM9.d.mts} +48 -2
  21. package/dist/retry-DANH6mM9.d.mts.map +1 -0
  22. package/dist/storage.d.mts +1 -1
  23. package/dist/storage.mjs +3 -3
  24. package/dist/testing.mjs +1 -1
  25. package/dist/universes.mjs +4 -4
  26. package/dist/{validation-BXhEM3OP.mjs → validation-BJ0-hNLs.mjs} +2 -2
  27. package/dist/{validation-BXhEM3OP.mjs.map → validation-BJ0-hNLs.mjs.map} +1 -1
  28. package/package.json +3 -3
  29. package/dist/rate-limit-B20REZEY.mjs.map +0 -1
  30. package/dist/resource-client-rQ9bBn4L.mjs.map +0 -1
  31. package/dist/retry-DGY51INM.d.mts.map +0 -1
  32. package/dist/retry-PmpgEwFN.mjs.map +0 -1
@@ -1,5 +1,5 @@
1
- import { n as NetworkError, r as ApiError, t as RateLimitError } from "./rate-limit-B20REZEY.mjs";
2
- import { a as computeRetryWaitMs, c as shouldRetry, n as IDEMPOTENT_METHOD_DEFAULTS, o as defaultRetryDelay, s as mergeConfig, u as PermissionError } from "./retry-PmpgEwFN.mjs";
1
+ import { n as NetworkError, r as ApiError, t as RateLimitError } from "./rate-limit-D1MQZNAE.mjs";
2
+ import { c as defaultRetryDelay, f as PermissionError, l as mergeConfig, r as IDEMPOTENT_METHOD_DEFAULTS, s as computeRetryWaitMs, u as shouldRetry } from "./retry-D1HKlycK.mjs";
3
3
  import { setTimeout } from "node:timers/promises";
4
4
  //#region src/internal/utils/is-date-time-string.ts
5
5
  /**
@@ -399,6 +399,8 @@ async function tryCatchAsync(promise) {
399
399
  }
400
400
  //#endregion
401
401
  //#region src/internal/http/diagnostics.ts
402
+ const MAX_DETAIL_LENGTH = 500;
403
+ const CONTENT_TYPE_HEADER$1 = "content-type";
402
404
  const DIAGNOSTIC_HEADER_ALLOWLIST = new Set([
403
405
  "cf-ray",
404
406
  "server",
@@ -448,6 +450,54 @@ function pickDiagnosticHeaders(headers) {
448
450
  for (const [name, value] of Object.entries(headers)) if (DIAGNOSTIC_HEADER_ALLOWLIST.has(name) || name.startsWith(DIAGNOSTIC_HEADER_PREFIX)) picked[name] = value;
449
451
  return picked;
450
452
  }
453
+ /**
454
+ * Converts a `Headers` object to a plain record with lowercased keys.
455
+ *
456
+ * @param headers - The `Headers` instance to convert.
457
+ * @returns A record mapping lowercased header names to their values.
458
+ */
459
+ function headersToRecord(headers) {
460
+ return Object.fromEntries(headers);
461
+ }
462
+ /**
463
+ * Projects a read body to the detail carried on an error: the parsed JSON when
464
+ * it parsed, otherwise the raw text truncated to {@link MAX_DETAIL_LENGTH}.
465
+ *
466
+ * @param text - The raw response body text.
467
+ * @param parsed - The best-effort parse result from the transport's body read.
468
+ * @returns The parsed body, or the truncated raw text on a parse failure.
469
+ */
470
+ function bodyDetail(text, parsed) {
471
+ return parsed.success ? parsed.data : text.slice(0, MAX_DETAIL_LENGTH);
472
+ }
473
+ /**
474
+ * Builds the error for a 2xx response whose body could not be parsed as JSON,
475
+ * preserving the parse `cause`, the (truncated) raw body, the declared
476
+ * content-type, and the request that produced it so the failure can be
477
+ * diagnosed after the fact.
478
+ *
479
+ * The received length is on the message rather than only on the error, because
480
+ * `details` retains just the first {@link MAX_DETAIL_LENGTH} characters: for a
481
+ * body that stopped mid-token the head says nothing and the length says
482
+ * everything. A `SyntaxError` position equal to this number is a body the edge
483
+ * cut short, not one the API mis-serialized.
484
+ *
485
+ * @param args - The Response, raw body text, request context, and underlying
486
+ * parse error.
487
+ * @returns An ApiError carrying the diagnostic context.
488
+ */
489
+ function parseFailureError({ cause, context, response, text }) {
490
+ return new ApiError(`Failed to parse response body (content-type: ${response.headers.get(CONTENT_TYPE_HEADER$1) ?? "unknown"}, ${String(text.length)} chars read)`, {
491
+ cause,
492
+ details: text.slice(0, MAX_DETAIL_LENGTH),
493
+ elapsedMs: context.elapsedMs,
494
+ method: context.method,
495
+ responseHeaders: pickDiagnosticHeaders(headersToRecord(response.headers)),
496
+ statusCode: response.status,
497
+ unparsedBodyLength: text.length,
498
+ url: context.url
499
+ });
500
+ }
451
501
  function firstTagText(html, tag) {
452
502
  const open = tag.open.exec(html);
453
503
  if (open === null) return;
@@ -557,19 +607,9 @@ function isUploadRequest(request) {
557
607
  }
558
608
  //#endregion
559
609
  //#region src/internal/http/fetch-client.ts
560
- const MAX_DETAIL_LENGTH = 500;
561
610
  const CONTENT_TYPE_HEADER = "content-type";
562
611
  const CONNECTION_HEADER = "connection";
563
612
  /**
564
- * Converts a `Headers` object to a plain record with lowercased keys.
565
- *
566
- * @param headers - The `Headers` instance to convert.
567
- * @returns A record mapping lowercased header names to their values.
568
- */
569
- function headersToRecord(headers) {
570
- return Object.fromEntries(headers);
571
- }
572
- /**
573
613
  * Permissively extracts a machine-readable error code from a response body.
574
614
  *
575
615
  * Modern Open Cloud responses use `{ errorCode: string, message: string }`;
@@ -778,17 +818,6 @@ function formatApiErrorMessage({ code, message, status }) {
778
818
  if (code === void 0) return `${base}: ${message}`;
779
819
  return `${base}: ${message} (code ${code})`;
780
820
  }
781
- /**
782
- * Projects a read body to the detail carried on an error: the parsed JSON when
783
- * it parsed, otherwise the raw text truncated to {@link MAX_DETAIL_LENGTH}.
784
- *
785
- * @param text - The raw response body text.
786
- * @param parsed - The best-effort parse result from {@link readResponseBodyAsync}.
787
- * @returns The parsed body, or the truncated raw text on a parse failure.
788
- */
789
- function bodyDetail(text, parsed) {
790
- return parsed.success ? parsed.data : text.slice(0, MAX_DETAIL_LENGTH);
791
- }
792
821
  function createApiError(args) {
793
822
  const { context, rawText, response } = args;
794
823
  const { status } = response;
@@ -871,21 +900,6 @@ async function createRateLimitErrorAsync(response) {
871
900
  });
872
901
  }
873
902
  /**
874
- * Builds the error for a 2xx response whose body could not be parsed as JSON,
875
- * preserving the parse `cause`, the (truncated) raw body, and the declared
876
- * content-type so the failure can be diagnosed after the fact.
877
- *
878
- * @param args - The Response, raw body text, and underlying parse error.
879
- * @returns An ApiError carrying the diagnostic context.
880
- */
881
- function parseFailureError({ cause, response, text }) {
882
- return new ApiError(`Failed to parse response body (content-type: ${response.headers.get(CONTENT_TYPE_HEADER) ?? "unknown"})`, {
883
- cause,
884
- details: text.slice(0, MAX_DETAIL_LENGTH),
885
- statusCode: response.status
886
- });
887
- }
888
- /**
889
903
  * Classifies a fetch `Response` into a typed `Result`.
890
904
  *
891
905
  * The body is read once and parsed best-effort. Error responses (status >= 300)
@@ -896,7 +910,8 @@ function parseFailureError({ cause, response, text }) {
896
910
  *
897
911
  * @param response - The raw fetch Response to classify.
898
912
  * @param context - The request context (method, url, elapsed time) threaded
899
- * onto any {@link ApiError} built for an error response.
913
+ * onto every {@link ApiError} built here, whether for an error response or
914
+ * for a 2xx whose body would not parse.
900
915
  * @returns A Result containing an HttpResponse on success or an OpenCloudError on failure.
901
916
  */
902
917
  async function classifyResponseAsync(response, context) {
@@ -917,6 +932,7 @@ async function classifyResponseAsync(response, context) {
917
932
  if (!parsed.success) return {
918
933
  err: parseFailureError({
919
934
  cause: parsed.err,
935
+ context,
920
936
  response,
921
937
  text
922
938
  }),
@@ -1138,4 +1154,4 @@ function enrichPermissionError(err, spec) {
1138
1154
  //#endregion
1139
1155
  export { isRecord as a, toJsonDetails as i, okRequest as n, isDateTimeString as o, parseEmptyResponse as r, ResourceClient as t };
1140
1156
 
1141
- //# sourceMappingURL=resource-client-rQ9bBn4L.mjs.map
1157
+ //# sourceMappingURL=resource-client-6KaHBVI7.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"resource-client-6KaHBVI7.mjs","names":["#window","#lastAllowedAt","#chains","#sleep","#trackers","#gateOnce","#tracker","#hooks","#intervalMs","#maxBucketLevel","#sleep","#chain","#waitForToken","#lastCheck","#bucketLevel","CONTENT_TYPE_HEADER","#budgets","#config","#hooks","#httpClient","#queues","#sleep","#getQueue","#gatedSend"],"sources":["../src/internal/utils/is-date-time-string.ts","../src/internal/utils/is-record.ts","../src/internal/utils/to-json-details.ts","../src/internal/http/budget-tracker.ts","../src/internal/http/budget-gate.ts","../src/internal/http/execute.ts","../src/internal/http/rate-limit-sample.ts","../src/internal/http/rate-limit-observation.ts","../src/internal/http/rate-limit-queue.ts","../src/internal/utils/try-catch.ts","../src/internal/http/diagnostics.ts","../src/internal/http/http1-dispatcher.ts","../src/internal/http/upload-request.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\tconst parsed = new Date(value);\n\treturn !Number.isNaN(parsed.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 { isRecord } from \"./is-record.ts\";\n\n/**\n * Narrows an untyped response body to the `JSONValue` accepted by\n * `ApiError.details`. `HttpResponse.body` is `unknown` because a transport may\n * hand back anything, but only a JSON graph is safe to retain on an error for\n * diagnostics. Anything else — functions, symbols, bigints, class instances,\n * or a cyclic graph — is dropped rather than asserted through.\n *\n * @param value - The parsed response body, or `undefined` for an empty body.\n * @returns The value as a `JSONValue`, or `undefined` when it is absent or not\n * JSON-representable.\n */\nexport function toJsonDetails(value: unknown): JSONValue | undefined {\n\treturn asJsonValue(value, new Set());\n}\n\nfunction asJsonValue(value: unknown, seen: Set<object>): JSONValue | undefined {\n\tif (value === null) {\n\t\t// eslint-disable-next-line unicorn/no-null -- JSON null is a JSONValue; the repo's undefined-only rule stops at this wire boundary\n\t\treturn null;\n\t}\n\n\tif (typeof value === \"string\" || typeof value === \"number\" || typeof value === \"boolean\") {\n\t\treturn value;\n\t}\n\n\tif (Array.isArray(value)) {\n\t\treturn asJsonArray(value, seen);\n\t}\n\n\tif (isRecord(value)) {\n\t\treturn asJsonObject(value, seen);\n\t}\n\n\treturn undefined;\n}\n\nfunction asJsonArray(value: ReadonlyArray<unknown>, seen: Set<object>): JSONValue | undefined {\n\tif (seen.has(value)) {\n\t\treturn undefined;\n\t}\n\n\tseen.add(value);\n\tconst items: Array<JSONValue> = [];\n\tfor (const item of value) {\n\t\tconst converted = asJsonValue(item, seen);\n\t\tif (converted === undefined) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\titems.push(converted);\n\t}\n\n\tseen.delete(value);\n\treturn items;\n}\n\nfunction asJsonObject(value: Record<string, unknown>, seen: Set<object>): JSONValue | undefined {\n\tif (seen.has(value)) {\n\t\treturn undefined;\n\t}\n\n\tseen.add(value);\n\tconst entries: Array<[string, JSONValue]> = [];\n\tfor (const [key, item] of Object.entries(value)) {\n\t\tconst converted = asJsonValue(item, seen);\n\t\tif (converted === undefined) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tentries.push([key, converted]);\n\t}\n\n\tseen.delete(value);\n\treturn Object.fromEntries(entries);\n}\n","import type { RateLimitSample } from \"./rate-limit-sample.ts\";\n\nconst MS_PER_SECOND = 1000;\n\n/** Live window state for one scope: budget left and when it resets. */\ninterface WindowState {\n\t/** Best estimate of requests still allowed before the window resets. */\n\treadonly predictedRemaining: number;\n\t/** Absolute time (ms) the window resets to full. */\n\treadonly resetAt: number;\n}\n\n/**\n * Tracks the live rate-limit budget for a single scope. Primed by `observe`\n * from response headers and drawn down by `reserve` as requests leave, so\n * `waitMs` can pace requests across the window.\n *\n * Pacing has two regimes. While budget remains, requests are spread evenly over\n * the time left in the window (`timeLeft / remaining`), so a burst does not\n * spend the whole window's budget up front and then stall. Once the budget is\n * spent, requests hold until the window resets. Budget and reset time move\n * together as one window, so the tracker is either unprimed or fully primed,\n * never half-known.\n */\nexport class BudgetTracker {\n\t/** Time (ms) the most recent request was allowed out, for spacing. */\n\t#lastAllowedAt: number | undefined = undefined;\n\t#window: undefined | WindowState = undefined;\n\n\t/**\n\t * Folds a fresh server reading in, replacing any prior window. The latest\n\t * reading wins: observe time is monotonic, so the most recently resolved\n\t * response is the best current estimate. The spacing reference is left\n\t * untouched so a window refresh does not reset pacing mid-stream.\n\t *\n\t * @param sample - Parsed `remaining`/`resetSeconds` from a response.\n\t * @param now - The current time in ms.\n\t */\n\tpublic observe(sample: RateLimitSample, now: number): void {\n\t\tthis.#window = {\n\t\t\tpredictedRemaining: sample.remaining,\n\t\t\tresetAt: now + sample.resetSeconds * MS_PER_SECOND,\n\t\t};\n\t}\n\n\t/**\n\t * Accounts for one request leaving at `now`: records the spacing reference\n\t * and decrements the prediction. A no-op on the prediction while unprimed.\n\t *\n\t * @param now - The time the request was allowed out, in ms.\n\t */\n\tpublic reserve(now: number): void {\n\t\tthis.#lastAllowedAt = now;\n\t\tif (this.#window !== undefined) {\n\t\t\tthis.#window = {\n\t\t\t\t...this.#window,\n\t\t\t\tpredictedRemaining: this.#window.predictedRemaining - 1,\n\t\t\t};\n\t\t}\n\t}\n\n\t/**\n\t * Milliseconds to wait before the next request is allowed.\n\t *\n\t * @param now - The current time in ms.\n\t * @returns `0` when a request may go now (unprimed, or the first paced send);\n\t * the time until reset when the budget is spent; otherwise the time until\n\t * this request's evenly-spaced slot.\n\t */\n\tpublic waitMs(now: number): number {\n\t\tif (this.#window === undefined) {\n\t\t\treturn 0;\n\t\t}\n\n\t\tconst { predictedRemaining, resetAt } = this.#window;\n\t\tif (predictedRemaining <= 0) {\n\t\t\treturn Math.max(0, resetAt - now);\n\t\t}\n\n\t\tif (this.#lastAllowedAt === undefined) {\n\t\t\treturn 0;\n\t\t}\n\n\t\tconst interval = (resetAt - now) / predictedRemaining;\n\t\treturn Math.max(0, this.#lastAllowedAt + interval - now);\n\t}\n}\n","import type { SleepFunc } from \"../utils/sleep.ts\";\nimport { BudgetTracker } from \"./budget-tracker.ts\";\nimport type { RateLimitSample } from \"./rate-limit-sample.ts\";\n\n/**\n * Header-primed rate-limit gate shared across a client. Holds one\n * {@link BudgetTracker} per API key, since the tightest Roblox window is the\n * per-key one shared across every operation. Before each request the caller\n * gates on the request's key (sleeping if its budget is spent), and after each\n * response folds the parsed sample back in, so a sibling operation on the same\n * key can head off a 429 the static per-operation token bucket cannot foresee.\n * A per-operation tracker is deliberately not kept: every operation reports the\n * same most-constrained `remaining`, so a per-key tracker (drawn down by all\n * operations) is always the binding constraint.\n *\n * Gating is serialized per scope through a promise chain so concurrent\n * requests on one key cannot read the same budget and reserve the same slot;\n * each waits for the prior gate's reserve before computing its own.\n */\nexport class BudgetGate {\n\treadonly #chains = new Map<string, Promise<void>>();\n\treadonly #sleep: SleepFunc;\n\treadonly #trackers = new Map<string, BudgetTracker>();\n\n\t/**\n\t * Creates a gate bound to an injectable sleep.\n\t *\n\t * @param sleep - Injectable sleep (tests pass a fake clock).\n\t */\n\tconstructor(sleep: SleepFunc) {\n\t\tthis.#sleep = sleep;\n\t}\n\n\t/**\n\t * Holds until the scope's budget permits a send, then reserves one slot.\n\t * Runs after the prior gate on the same scope settles, whether it resolved\n\t * or rejected, so one failed attempt cannot poison later gates on the key.\n\t *\n\t * @param scope - The scope key to gate on (the effective API key).\n\t */\n\tpublic async gateAsync(scope: string): Promise<void> {\n\t\tconst previous = this.#chains.get(scope) ?? Promise.resolve();\n\t\tconst runGateAsync = async (): Promise<void> => this.#gateOnce(scope);\n\t\t// The gate runs whether the previous link settled or rejected, so a\n\t\t// failed wait never strands the scope's chain.\n\t\t// Both handlers are the same function on purpose: this gate must run\n\t\t// whether the previous link settled or rejected, so a failed wait never\n\t\t// strands the scope's queue. `.then(...).catch(...)` would instead run\n\t\t// the gate a second time when the gate itself rejects.\n\t\t// eslint-disable-next-line unicorn/prefer-then-catch -- see above\n\t\tconst mine = previous.then(runGateAsync, runGateAsync);\n\t\tthis.#chains.set(scope, mine);\n\t\tawait mine;\n\t}\n\n\t/**\n\t * Folds a response's parsed budget back onto the scope. A `undefined`\n\t * sample (headers absent or non-numeric) is ignored, leaving the scope on\n\t * static pacing.\n\t *\n\t * @param scope - The same scope key passed to {@link gateAsync}.\n\t * @param sample - Parsed sample, or `undefined` when none was reported.\n\t */\n\tpublic observe(scope: string, sample: RateLimitSample | undefined): void {\n\t\tif (sample === undefined) {\n\t\t\treturn;\n\t\t}\n\n\t\tthis.#tracker(scope).observe(sample, Date.now());\n\t}\n\n\tasync #gateOnce(scope: string): Promise<void> {\n\t\tconst tracker = this.#tracker(scope);\n\t\tconst waitMs = tracker.waitMs(Date.now());\n\t\tif (waitMs > 0) {\n\t\t\tawait this.#sleep(waitMs);\n\t\t}\n\n\t\ttracker.reserve(Date.now());\n\t}\n\n\t#tracker(scope: string): BudgetTracker {\n\t\tconst existing = this.#trackers.get(scope);\n\t\tif (existing !== undefined) {\n\t\t\treturn existing;\n\t\t}\n\n\t\tconst tracker = new BudgetTracker();\n\t\tthis.#trackers.set(scope, tracker);\n\t\treturn tracker;\n\t}\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 executeWithRetryAsync} bundled as an options object to keep\n * the 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 executeWithRetryAsync(\n\trequest: HttpRequest,\n\t{ config, hooks, send, sleep }: ExecuteOptions,\n): Promise<Result<HttpResponse, OpenCloudError>> {\n\tasync function attemptAsync(): Promise<Result<HttpResponse, OpenCloudError>> {\n\t\thooks.onRequest?.(request);\n\t\treturn send(request);\n\t}\n\n\tlet result = await attemptAsync();\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 attemptAsync();\n\t}\n\n\treturn result;\n}\n","/**\n * A point-in-time rate-limit budget reading parsed from Roblox Open Cloud\n * response headers. Both fields are non-negative integers.\n */\nexport interface RateLimitSample {\n\t/**\n\t * Requests still allowed in the current window (the most-constrained one).\n\t */\n\treadonly remaining: number;\n\t/** Seconds until the most-constrained window resets to full. */\n\treadonly resetSeconds: number;\n}\n\n/**\n * Reduces a comma-separated rate-limit header value (e.g. `\"0, 70000\"`) to a\n * single non-negative integer via `combine`. Tokens are trimmed; blank and\n * non-finite tokens (`\"\"`, `\"Infinity\"`, `\"abc\"`) are dropped so a stray value\n * cannot corrupt the result. Returns `undefined` when the header is absent or\n * has no finite tokens.\n *\n * @param headerValue - The raw header value, or `undefined` if missing.\n * @param combine - Pairwise reducer, `Math.min` for remaining, `Math.max` for reset.\n * @returns The reduced, floored, clamped value, or `undefined`.\n */\nexport function reduceRateLimitTokens(\n\theaderValue: string | undefined,\n\tcombine: (a: number, b: number) => number,\n): number | undefined {\n\tif (headerValue === undefined) {\n\t\treturn undefined;\n\t}\n\n\tconst tokens = headerValue\n\t\t.split(\",\")\n\t\t.map((part) => part.trim())\n\t\t.filter((part) => part !== \"\")\n\t\t.map((part) => Number(part))\n\t\t.filter((value) => Number.isFinite(value));\n\tif (tokens.length === 0) {\n\t\treturn undefined;\n\t}\n\n\treturn Math.max(0, Math.floor(tokens.reduce(combine)));\n}\n\n/**\n * Parses the `x-ratelimit-remaining` and `x-ratelimit-reset` response headers\n * into a {@link RateLimitSample}. Each header may carry a comma-separated list\n * of per-window values; `remaining` takes the smallest (most constrained) and\n * `resetSeconds` takes the largest (longest wait), symmetric to how a 429's\n * retry delay is reduced. Returns `undefined` when either header is missing or\n * has no finite numeric tokens, so a caller can fall back to static pacing.\n *\n * @param headers - Response headers with lowercased keys.\n * @returns The parsed sample, or `undefined` when the budget cannot be read.\n */\nexport function parseRateLimitHeaders(\n\theaders: Readonly<Record<string, string>>,\n): RateLimitSample | undefined {\n\tconst remaining = reduceRateLimitTokens(headers[\"x-ratelimit-remaining\"], (a, b) => {\n\t\treturn Math.min(a, b);\n\t});\n\tconst resetSeconds = reduceRateLimitTokens(headers[\"x-ratelimit-reset\"], (a, b) => {\n\t\treturn Math.max(a, b);\n\t});\n\tif (remaining === undefined || resetSeconds === undefined) {\n\t\treturn undefined;\n\t}\n\n\treturn { remaining, resetSeconds };\n}\n","import type { OpenCloudError } from \"../../errors/base.ts\";\nimport { RateLimitError } from \"../../errors/rate-limit.ts\";\nimport type { Result } from \"../../types.ts\";\nimport type { RateLimitSample } from \"./rate-limit-sample.ts\";\nimport { parseRateLimitHeaders } from \"./rate-limit-sample.ts\";\nimport type { HttpResponse } from \"./types.ts\";\n\n/**\n * Extracts a {@link RateLimitSample} from a transport result so the budget gate\n * can be fed from every attempt. A 2xx carries the budget in its headers; a 429\n * carries it on the {@link RateLimitError} (the raw headers are dropped before\n * this point). Any other error, or a response that reported no budget, yields\n * `undefined` and leaves the gate on static pacing.\n *\n * @param result - The classified transport result for one attempt.\n * @returns The parsed sample, or `undefined` when none was reported.\n */\nexport function rateLimitSampleFromResult(\n\tresult: Result<HttpResponse, OpenCloudError>,\n): RateLimitSample | undefined {\n\tif (result.success) {\n\t\treturn parseRateLimitHeaders(result.data.headers);\n\t}\n\n\tconst { err } = result;\n\tif (err instanceof RateLimitError && err.remaining !== undefined) {\n\t\treturn { remaining: err.remaining, resetSeconds: err.retryAfterSeconds };\n\t}\n\n\treturn undefined;\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/**\n\t * How many requests may be issued back to back before pacing begins,\n\t * as a whole number of requests. Defaults to `max(1, maxPerSecond)`,\n\t * which leaves operations at or above 1/s paced exactly as their\n\t * sustained rate allows while still granting a slower operation one\n\t * request after it has idled. Set this to the allowance the schema\n\t * documents (e.g. 5 per minute) to grant the burst the server permits.\n\t */\n\treadonly burstCapacity?: number;\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. Tokens refill at\n * `maxPerSecond` per second, up to the operation's `burstCapacity`.\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. `#bucketLevel`\n * and `#maxBucketLevel` are both ms of drain debt, so the ceiling is the burst\n * expressed in that unit: `burstCapacity` refill intervals. Deriving it any\n * other way (notably `maxPerSecond * intervalMs`, whose units cancel to a\n * constant 1000) starves every operation slower than one request per second.\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\tconst burstCapacity = limit.burstCapacity ?? Math.max(1, limit.maxPerSecond);\n\t\tthis.#maxBucketLevel = burstCapacity * 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 acquireAsync<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 tryCatchAsync<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 { Result } 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\n/**\n * The request-level context threaded from the transport into error\n * construction: which call failed and how long it was in flight.\n */\nexport interface RequestContext {\n\t/** Wall-clock time the request was in flight, in milliseconds. */\n\treadonly elapsedMs: number;\n\t/** HTTP method of the request. */\n\treadonly method: string;\n\t/** Fully-qualified URL of the request. */\n\treadonly url: string;\n}\n\n/** Inputs to {@link parseFailureError}. */\nexport interface ParseFailureArgs {\n\t/** The `SyntaxError` thrown by the failed `JSON.parse`. */\n\treadonly cause: Error;\n\t/** The request that produced the unusable response. */\n\treadonly context: RequestContext;\n\t/** The 2xx response whose body would not parse. */\n\treadonly response: Response;\n\t/** The raw body text, read once by the transport. */\n\treadonly text: string;\n}\n\n// A small allowlist of response headers worth retaining on an ApiError for\n// diagnosis and escalation to Roblox. apis.roblox.com returns `server` (e.g.\n// `public-gateway`, or `haproxy` on a load-balancer error page) and\n// `x-roblox-edge` on every response; `via`, `x-request-id`, and `cf-ray` are\n// standard proxy/CDN request-id headers kept in case an edge adds them. The\n// full header set is never retained, to avoid surfacing anything sensitive.\nconst DIAGNOSTIC_HEADER_ALLOWLIST: ReadonlySet<string> = new Set([\n\t\"cf-ray\",\n\t\"server\",\n\t\"via\",\n\t\"x-request-id\",\n]);\n\nconst DIAGNOSTIC_HEADER_PREFIX = \"x-roblox-\";\n\n// Only the opening tag is matched; the closing tag is located with indexOf so\n// the inner text needs no unbounded pattern, which would backtrack\n// super-linearly on a hostile error page.\nconst TITLE_OPEN_PATTERN = /<title[^>]*>/i;\nconst H1_OPEN_PATTERN = /<h1[^>]*>/i;\nconst TAG_PATTERN = /<[^<>]*>/g;\nconst WHITESPACE_PATTERN = /\\s+/g;\n\n/**\n * Extracts a one-line human summary from an HTML gateway error page, or returns\n * `undefined` when the body is not such a page. A load balancer (HAProxy-style)\n * rejects a request before it reaches Open Cloud and answers with an HTML page,\n * not a JSON Open Cloud error; dumping that HTML whole is noise. The body is\n * treated as HTML when the content-type is `text/html` or the trimmed body is\n * tag-led (`<html`/`<!doctype html`), and the summary is taken from the\n * `<title>` (falling back to the first `<h1>`), tags stripped and whitespace\n * collapsed.\n *\n * @param contentType - The response `content-type` header, if present.\n * @param rawText - The raw response body text.\n * @returns The extracted summary, or `undefined` when the body is not an HTML\n * gateway page (or carries no title/h1 text).\n */\nexport function extractGatewaySummary(\n\tcontentType: string | undefined,\n\trawText: string,\n): string | undefined {\n\tif (!isHtmlBody(contentType, rawText)) {\n\t\treturn undefined;\n\t}\n\n\treturn (\n\t\tfirstTagText(rawText, { close: \"</title>\", open: TITLE_OPEN_PATTERN }) ??\n\t\tfirstTagText(rawText, { close: \"</h1>\", open: H1_OPEN_PATTERN })\n\t);\n}\n\n/**\n * Filters a lowercased header record down to the diagnostic allowlist: a few\n * named escalation headers plus any `x-roblox-*` header. Keeps errors light and\n * avoids retaining anything sensitive from the full response header set.\n *\n * @param headers - The full header record (lowercased keys).\n * @returns A record containing only the allowlisted headers that were present.\n */\nexport function pickDiagnosticHeaders(headers: Record<string, string>): Record<string, string> {\n\tconst picked: Record<string, string> = {};\n\tfor (const [name, value] of Object.entries(headers)) {\n\t\tif (DIAGNOSTIC_HEADER_ALLOWLIST.has(name) || name.startsWith(DIAGNOSTIC_HEADER_PREFIX)) {\n\t\t\tpicked[name] = value;\n\t\t}\n\t}\n\n\treturn picked;\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 * Projects a read body to the detail carried on an error: the parsed JSON when\n * it parsed, otherwise the raw text truncated to {@link MAX_DETAIL_LENGTH}.\n *\n * @param text - The raw response body text.\n * @param parsed - The best-effort parse result from the transport's body read.\n * @returns The parsed body, or the truncated raw text on a parse failure.\n */\nexport function bodyDetail(\n\ttext: string,\n\tparsed: Result<JSONValue | undefined>,\n): JSONValue | undefined {\n\treturn parsed.success ? parsed.data : text.slice(0, MAX_DETAIL_LENGTH);\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, the declared\n * content-type, and the request that produced it so the failure can be\n * diagnosed after the fact.\n *\n * The received length is on the message rather than only on the error, because\n * `details` retains just the first {@link MAX_DETAIL_LENGTH} characters: for a\n * body that stopped mid-token the head says nothing and the length says\n * everything. A `SyntaxError` position equal to this number is a body the edge\n * cut short, not one the API mis-serialized.\n *\n * @param args - The Response, raw body text, request context, and underlying\n * parse error.\n * @returns An ApiError carrying the diagnostic context.\n */\nexport function parseFailureError({ cause, context, response, text }: ParseFailureArgs): ApiError {\n\tconst contentType = response.headers.get(CONTENT_TYPE_HEADER) ?? \"unknown\";\n\treturn new ApiError(\n\t\t`Failed to parse response body (content-type: ${contentType}, ${String(text.length)} chars read)`,\n\t\t{\n\t\t\tcause,\n\t\t\tdetails: text.slice(0, MAX_DETAIL_LENGTH),\n\t\t\telapsedMs: context.elapsedMs,\n\t\t\tmethod: context.method,\n\t\t\tresponseHeaders: pickDiagnosticHeaders(headersToRecord(response.headers)),\n\t\t\tstatusCode: response.status,\n\t\t\tunparsedBodyLength: text.length,\n\t\t\turl: context.url,\n\t\t},\n\t);\n}\n\nfunction firstTagText(html: string, tag: { close: string; open: RegExp }): string | undefined {\n\tconst open = tag.open.exec(html);\n\tif (open === null) {\n\t\treturn undefined;\n\t}\n\n\tconst start = open.index + open[0].length;\n\tconst end = html.toLowerCase().indexOf(tag.close, start);\n\tif (end === -1) {\n\t\treturn undefined;\n\t}\n\n\tconst inner = html.slice(start, end);\n\n\tconst text = inner.replace(TAG_PATTERN, \" \").replace(WHITESPACE_PATTERN, \" \").trim();\n\treturn text === \"\" ? undefined : text;\n}\n\nfunction isHtmlBody(contentType: string | undefined, rawText: string): boolean {\n\tif (contentType?.toLowerCase().includes(\"text/html\") === true) {\n\t\treturn true;\n\t}\n\n\tconst head = rawText.trimStart().toLowerCase();\n\treturn head.startsWith(\"<html\") || head.startsWith(\"<!doctype html\");\n}\n","/** The shape the global dispatcher's class is assumed to have. */\ntype AgentConstructor = new (options: { allowH2: boolean }) => object;\n\n/**\n * Well-known globals under which undici publishes its global dispatcher,\n * newest first. The suffix is undici's own contract version: it moved from\n * `.1` to `.2` in undici 8, so a future major may move it again. Both are\n * probed, and {@link createHttp1Dispatcher} degrades to `undefined` when\n * neither is present — which is also the Bun path, since Bun's `fetch` is not\n * undici-backed and never publishes these.\n */\nconst GLOBAL_DISPATCHER_KEYS: ReadonlyArray<string> = Object.freeze([\n\t\"undici.globalDispatcher.2\",\n\t\"undici.globalDispatcher.1\",\n]);\n\n/**\n * Narrow a value read off the global dispatcher to something\n * `Reflect.construct` accepts. Exported so the narrowing is unit-testable: at\n * the call site every rejected shape funnels into the same `undefined`, which\n * makes the branch unobservable from `createHttp1Dispatcher` alone.\n *\n * @param value - The candidate `constructor` read off the global dispatcher.\n * @returns Whether the value can be constructed.\n */\nexport function isAgentConstructor(value: unknown): value is AgentConstructor {\n\treturn typeof value === \"function\";\n}\n\n/**\n * Builds a request dispatcher that negotiates HTTP/1.1 only, by reusing the\n * class of the runtime's own global dispatcher.\n *\n * From Node 26 (undici 8) `fetch` offers h2 in ALPN, which defeats the\n * `connection: close` an upload sets: `connection` is a connection-specific\n * header, so an h2 transport drops it before the wire and pools every upload\n * onto one multiplexed session. One session death then fails every upload in\n * flight. Constructing the same agent with `allowH2: false` restores the\n * per-upload connection the directive was written for.\n *\n * There is no standard `fetch` option for this, so the agent is reached\n * through undici's versioned global symbol and its class rather than through\n * an import — which keeps the package dependency-free. The contract is\n * internal, so every step is guarded: an absent symbol, a non-constructible\n * value, or a constructor that throws all yield `undefined`, and the caller\n * sends the request unmodified.\n *\n * @param scope - The object to read the global dispatcher from. Defaults to\n * `globalThis`; injectable so tests need not mutate the real global.\n * @returns A dispatcher restricted to HTTP/1.1, or `undefined` when this\n * runtime offers no reachable one.\n */\nexport function createHttp1Dispatcher(scope: object = globalThis): object | undefined {\n\tfor (const key of GLOBAL_DISPATCHER_KEYS) {\n\t\tconst dispatcher = constructHttp1(Reflect.get(scope, Symbol.for(key)));\n\t\tif (dispatcher !== undefined) {\n\t\t\treturn dispatcher;\n\t\t}\n\t}\n\n\treturn undefined;\n}\n\n/**\n * Reconstructs `agent`'s class with h2 disabled.\n *\n * Most ways `agent` can be wrong already throw: `Reflect.get` rejects a\n * primitive, `null`, and an absent key, and `Reflect.construct` rejects a\n * `constructor` that is not one, or that refuses the options. One shape gets\n * through — a plain object, whose `constructor` is `Object`, so constructing\n * it hands back the options bag. The result is therefore checked against the\n * one part of undici's surface that is public and stable: a `Dispatcher`\n * exposes `dispatch`.\n *\n * @param agent - The candidate global dispatcher; any value, since it comes\n * from an undocumented global.\n * @returns The new dispatcher, or `undefined` when `agent` is not an object\n * whose constructor accepts undici's agent options.\n */\nfunction constructHttp1(agent: unknown): object | undefined {\n\ttry {\n\t\t// No shape guard ahead of this: `Reflect.get` already rejects a\n\t\t// primitive, `null`, and an absent key, so every malformed value lands\n\t\t// in the same catch.\n\t\tconst agentClass = Reflect.get(agent, \"constructor\");\n\t\tif (!isAgentConstructor(agentClass)) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst dispatcher = Reflect.construct(agentClass, [{ allowH2: false }]);\n\t\treturn typeof Reflect.get(dispatcher, \"dispatch\") === \"function\" ? dispatcher : undefined;\n\t} catch {\n\t\t// An internal contract that moved under us is not worth failing a\n\t\t// deploy over: fall back to the runtime's default transport.\n\t\treturn undefined;\n\t}\n}\n","import type { HttpRequest } from \"../../client/types.ts\";\n\n/**\n * Reports whether a request is an upload: its body is `FormData`\n * (multipart) or `Uint8Array` (raw binary). Upload latency is\n * bandwidth-bound rather than compute-bound, so the SDK applies no default\n * request timeout to these requests; a sensible wall-clock budget depends on\n * payload size and link quality the SDK cannot know.\n *\n * @param request - The built request to classify.\n * @returns `true` when the body is `FormData` or `Uint8Array`.\n */\nexport function isUploadRequest(request: HttpRequest): boolean {\n\treturn request.body instanceof FormData || request.body instanceof Uint8Array;\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 { tryCatchAsync } from \"../utils/try-catch.ts\";\nimport {\n\tbodyDetail,\n\textractGatewaySummary,\n\theadersToRecord,\n\tparseFailureError,\n\tpickDiagnosticHeaders,\n\ttype RequestContext,\n} from \"./diagnostics.ts\";\nimport { createHttp1Dispatcher } from \"./http1-dispatcher.ts\";\nimport { reduceRateLimitTokens } from \"./rate-limit-sample.ts\";\nimport type { HttpClient, HttpRequest, HttpResponse, RequestConfig } from \"./types.ts\";\nimport { isUploadRequest } from \"./upload-request.ts\";\n\nconst CONTENT_TYPE_HEADER = \"content-type\";\n\n// Uploads opt out of keep-alive reuse. Roblox's edge gateway discards idle\n// pooled connections faster than a pooling `fetch` expects, and a request\n// written into a discarded connection never reaches Open Cloud: it surfaces as\n// a gateway error page or a socket reset, minutes later, having done nothing.\n// An upload holds a connection far longer than a JSON call, so it is the shape\n// that loses this race. The cost is a fresh handshake and a cold congestion\n// window per upload (real for a multi-megabyte body, and paid again on each\n// retry), but cheaper than a lost write. Small, frequent calls keep pooling.\nconst CONNECTION_HEADER = \"connection\";\n\n/**\n * `RequestInit` plus undici's non-standard `dispatcher`, the only way to\n * select a transport from `fetch`. Declared locally because it is absent from\n * the DOM lib and runtimes that do not understand it ignore it.\n */\ninterface FetchOptions extends RequestInit {\n\tdispatcher?: object | undefined;\n}\n\n/**\n * Collaborators of {@link createFetchHttpClient}, bundled so the factory keeps\n * a two-argument signature as they accumulate. Both have production defaults;\n * both are overridable, which is also what makes them testable.\n */\ninterface FetchHttpClientSeams {\n\t/**\n\t * Builds the HTTP/1.1-only transport uploads use, so the\n\t * `connection: close` directive is not dropped by an h2 transport.\n\t */\n\treadonly createDispatcher?: () => object | undefined;\n\t/** Monotonic-ish clock used to measure request elapsed time. */\n\treadonly now?: () => number;\n}\n\ninterface ErrorResponseArgs {\n\treadonly context: RequestContext;\n\treadonly parsed: Result<JSONValue | undefined>;\n\treadonly rawText: string;\n\treadonly response: Response;\n}\n\ninterface ApiErrorMessageParts {\n\treadonly code: string | undefined;\n\treadonly message: string | undefined;\n\treadonly status: number;\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. On a 429 the\n * header is a comma-separated list of per-window reset times (e.g. `\"22, 0\"`,\n * one entry per rate-limit window); the largest value is the longest-resetting\n * window and the only safe wait that won't retry into a still-exhausted\n * window. A single value is treated as a one-element list.\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\treturn reduceRateLimitTokens(headerValue, (a, b) => Math.max(a, b)) ?? 0;\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): FetchOptions {\n\tconst headers = new Headers({\n\t\t\"x-api-key\": config.apiKey,\n\t});\n\n\tconst options: FetchOptions = {\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\tapplyRequestHeaders(headers, request);\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 * @param seams - Injectable clock and dispatcher factory, so tests need not\n * depend on wall-clock time or on the runtime's global dispatcher.\n * @returns An HttpClient that classifies responses into typed Results.\n */\nexport function createFetchHttpClient(\n\tfetchFunc: (url: string, init: RequestInit) => Promise<Response> = fetch,\n\t{ createDispatcher = createHttp1Dispatcher, now = Date.now }: FetchHttpClientSeams = {},\n): HttpClient {\n\tconst dispatcherFor = createUploadDispatcherCache(createDispatcher);\n\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\t\t\t// Undefined is how `fetch` spells \"use the runtime's own\n\t\t\t// transport\", so this is safe to assign unconditionally.\n\t\t\toptions.dispatcher = dispatcherFor(httpRequest);\n\t\t\tconst target = { method: httpRequest.method, url };\n\n\t\t\tconst { elapsedMs, fetchResult } = await timedFetchAsync(now, async () => {\n\t\t\t\treturn fetchFunc(url, options);\n\t\t\t});\n\t\t\tif (!fetchResult.success) {\n\t\t\t\treturn { err: networkError(fetchResult.err, target), success: false };\n\t\t\t}\n\n\t\t\t// Reading and classifying the body can itself throw (an aborted or\n\t\t\t// undecodable body stream rejects `response.text()`); keep the\n\t\t\t// Result contract by mapping any such throw to a NetworkError.\n\t\t\tconst context: RequestContext = { elapsedMs, method: target.method, url: target.url };\n\t\t\tconst classified = await tryCatchAsync(\n\t\t\t\tclassifyResponseAsync(fetchResult.data, context),\n\t\t\t);\n\t\t\tif (!classified.success) {\n\t\t\t\treturn { err: networkError(classified.err, target), success: false };\n\t\t\t}\n\n\t\t\treturn classified.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\n/**\n * Merges the request's own headers onto the transport's, then applies the\n * transport-owned connection directive. `x-api-key` is skipped so a request\n * cannot override the configured credential, and the upload directive is set\n * last so a request header cannot silently re-enable pooling for an upload.\n *\n * @param headers - The headers being built for the fetch call. Mutated.\n * @param request - The request whose headers and body shape drive the merge.\n */\nfunction applyRequestHeaders(headers: Headers, request: HttpRequest): void {\n\tconst requestHeaders = request.headers ?? {};\n\tfor (const [name, value] of Object.entries(requestHeaders)) {\n\t\tif (name.toLowerCase() === \"x-api-key\") {\n\t\t\tcontinue;\n\t\t}\n\n\t\theaders.set(name, value);\n\t}\n\n\tif (isUploadRequest(request)) {\n\t\theaders.set(CONNECTION_HEADER, \"close\");\n\t}\n}\n\n/**\n * Wraps a dispatcher factory in the caching policy uploads need.\n *\n * Resolution happens on the first upload rather than at construction: undici\n * publishes its global dispatcher lazily, so before a process's first `fetch`\n * there is nothing to read. A resolved dispatcher is kept, and an unresolved\n * one is retried on the next upload — so a runtime that publishes late is\n * still picked up, and the first request of a process, which has no pooled\n * connection to lose, is safe either way.\n *\n * @param createDispatcher - Builds the HTTP/1.1-only transport.\n * @returns A function yielding the dispatcher for a request, or `undefined`\n * when the request is not an upload or no dispatcher is available.\n */\nfunction createUploadDispatcherCache(\n\tcreateDispatcher: () => object | undefined,\n): (request: HttpRequest) => object | undefined {\n\tlet cached: object | undefined;\n\treturn (request) => {\n\t\tif (!isUploadRequest(request)) {\n\t\t\treturn;\n\t\t}\n\n\t\tcached ??= createDispatcher();\n\t\treturn cached;\n\t};\n}\n\n/**\n * Runs `send` and reports both its Result and how long it was in flight,\n * measured with `now`. Isolated so the timing start need not sit in the request\n * body ahead of the transport-failure early return.\n *\n * @param now - The clock used to bound the call.\n * @param send - A thunk that issues the fetch.\n * @returns The fetch Result and the elapsed milliseconds.\n */\nasync function timedFetchAsync(\n\tnow: () => number,\n\tsend: () => Promise<Response>,\n): Promise<{ elapsedMs: number; fetchResult: Result<Response> }> {\n\tconst start = now();\n\tconst fetchResult = await tryCatchAsync(send());\n\t// Clamp to zero: `Date.now` is wall-clock, so an NTP adjustment mid-request\n\t// could otherwise report a negative \"after -0.1s\".\n\treturn { elapsedMs: Math.max(0, now() - start), fetchResult };\n}\n\nfunction networkError(cause: Error, target: { method: string; url: string }): NetworkError {\n\treturn new NetworkError(\"Network request failed\", {\n\t\tcause,\n\t\tmethod: target.method,\n\t\turl: target.url,\n\t});\n}\n\nfunction formatApiErrorMessage({ code, message, status }: ApiErrorMessageParts): string {\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(args: ErrorResponseArgs): ApiError {\n\tconst { context, rawText, response } = args;\n\tconst { status } = response;\n\tconst headers = headersToRecord(response.headers);\n\tconst requestContext = {\n\t\telapsedMs: context.elapsedMs,\n\t\tmethod: context.method,\n\t\tresponseHeaders: pickDiagnosticHeaders(headers),\n\t\tstatusCode: status,\n\t\turl: context.url,\n\t};\n\n\t// An HTML body is a load-balancer error page, not an Open Cloud response;\n\t// summarize it rather than retaining the raw HTML on `details`.\n\tconst gatewaySummary = extractGatewaySummary(headers[CONTENT_TYPE_HEADER], rawText);\n\tif (gatewaySummary !== undefined) {\n\t\treturn new ApiError(`HTTP ${status}`, { ...requestContext, gatewaySummary });\n\t}\n\n\tconst body = bodyDetail(rawText, args.parsed);\n\tconst code = extractErrorCode(body);\n\tconst message = extractErrorMessage(body);\n\treturn new ApiError(formatApiErrorMessage({ code, message, status }), {\n\t\t...requestContext,\n\t\tcode,\n\t\tdetails: body,\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\n * tryCatchAsync}.\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 * Reads a response body once and parses it best-effort: an empty body is a\n * successful `undefined`, otherwise the JSON parse result (which carries the\n * `SyntaxError` on failure). Returns the raw `text` alongside so callers that\n * need the original bytes (parse-failure diagnostics) do not re-read the\n * consumed stream.\n *\n * @param response - The Response whose body to read.\n * @returns The parse result and the raw text.\n */\nasync function readResponseBodyAsync(\n\tresponse: Response,\n): Promise<{ parsed: Result<JSONValue | undefined>; text: string }> {\n\tconst text = await response.text();\n\treturn {\n\t\tparsed: text === \"\" ? { data: undefined, success: true } : parseJson(text),\n\t\ttext,\n\t};\n}\n\nasync function createRateLimitErrorAsync(response: Response): Promise<RateLimitError> {\n\tconst headers = headersToRecord(response.headers);\n\tconst { parsed, text } = await readResponseBodyAsync(response);\n\treturn new RateLimitError(\"Rate limited\", {\n\t\tdetails: bodyDetail(text, parsed),\n\t\tremaining: reduceRateLimitTokens(headers[\"x-ratelimit-remaining\"], (a, b) => {\n\t\t\treturn Math.min(a, b);\n\t\t}),\n\t\tretryAfterSeconds: parseRetryAfterSeconds(headers[\"x-ratelimit-reset\"]),\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 degrades to a\n * status-based {@link ApiError} carrying the raw text, and an HTML gateway page\n * is summarized rather than dumped. A parse failure is only fatal on a 2xx,\n * where a parseable body is part of the contract.\n *\n * @param response - The raw fetch Response to classify.\n * @param context - The request context (method, url, elapsed time) threaded\n * onto every {@link ApiError} built here, whether for an error response or\n * for a 2xx whose body would not parse.\n * @returns A Result containing an HttpResponse on success or an OpenCloudError on failure.\n */\nasync function classifyResponseAsync(\n\tresponse: Response,\n\tcontext: RequestContext,\n): Promise<Result<HttpResponse, OpenCloudError>> {\n\tif (response.status === 429) {\n\t\treturn { err: await createRateLimitErrorAsync(response), success: false };\n\t}\n\n\tconst { parsed, text } = await readResponseBodyAsync(response);\n\n\tif (response.status >= 300) {\n\t\treturn {\n\t\t\terr: createApiError({ context, parsed, rawText: text, response }),\n\t\t\tsuccess: false,\n\t\t};\n\t}\n\n\tif (!parsed.success) {\n\t\treturn {\n\t\t\terr: parseFailureError({ cause: parsed.err, context, response, text }),\n\t\t\tsuccess: false,\n\t\t};\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/**\n\t * Test seam: custom {@link HttpClient}. Defaults to a fetch-backed client.\n\t */\n\treadonly httpClient?: HttpClient | undefined;\n\t/**\n\t * Test seam: custom {@link SleepFunc}. Defaults to a `setTimeout`-backed\n\t * sleep.\n\t */\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\tRequestConfig,\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 { BudgetGate } from \"./http/budget-gate.ts\";\nimport { executeWithRetryAsync } from \"./http/execute.ts\";\nimport { rateLimitSampleFromResult } from \"./http/rate-limit-observation.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\";\nimport { isUploadRequest } from \"./http/upload-request.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/**\n\t * Operation-level rate limit, keyed into the client's per-key queue map.\n\t */\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/**\n\t * Per-method binding of builder, parser, method kind, and operation limit.\n\t */\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 * Inputs to {@link buildRequestConfig}, bundled to keep the signature narrow.\n */\ninterface RequestConfigInputs {\n\t/** The resolved config for this call. */\n\treadonly merged: RetryResolvable;\n\t/** The caller's per-request overrides, if any. */\n\treadonly options: RequestOptions | undefined;\n\t/** The built request, inspected for an upload body. */\n\treadonly request: HttpRequest;\n}\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.executeAsync} 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 #budgets: BudgetGate;\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({ apiKey, hooks, httpClient, sleep, ...overrides }: OpenCloudClientOptions) {\n\t\tconst resolved = resolveDependencies({ httpClient, sleep });\n\t\tthis.#httpClient = resolved.httpClient;\n\t\tthis.#sleep = resolved.sleep;\n\t\tthis.#budgets = new BudgetGate(this.#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 executeAsync<P, T>({\n\t\toptions,\n\t\tparameters,\n\t\tspec,\n\t}: ExecuteCall<P, T>): Promise<Result<T, OpenCloudError>> {\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 = buildRequestConfig({ merged, options, request: requestResult.data });\n\t\tconst queue = this.#getQueue(merged.apiKey, spec.operationLimit);\n\t\tconst httpResult = await queue.acquireAsync(async () => {\n\t\t\treturn executeWithRetryAsync(requestResult.data, {\n\t\t\t\tconfig: merged,\n\t\t\t\thooks: this.#hooks,\n\t\t\t\tsend: this.#gatedSend(merged.apiKey, 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/**\n\t * Builds the transport callback for one logical call, wrapping the HTTP\n\t * client with the budget gate: each attempt waits on the API key's budget\n\t * before sending, then folds the response's reported budget back in so the\n\t * next attempt (or a sibling operation on the same key) can head off a 429.\n\t *\n\t * @param apiKey - The effective API key to gate on.\n\t * @param requestConfig - The resolved per-request transport config.\n\t * @returns A send callback for {@link executeWithRetryAsync}.\n\t */\n\t#gatedSend(\n\t\tapiKey: string,\n\t\trequestConfig: RequestConfig,\n\t): (request: HttpRequest) => Promise<Result<HttpResponse, OpenCloudError>> {\n\t\treturn async (toSend) => {\n\t\t\tawait this.#budgets.gateAsync(apiKey);\n\t\t\tconst sendResult = await this.#httpClient.request(toSend, requestConfig);\n\t\t\tthis.#budgets.observe(apiKey, rateLimitSampleFromResult(sendResult));\n\t\t\treturn sendResult;\n\t\t};\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\n/**\n * Resolves the per-request {@link RequestConfig}. Upload requests\n * ({@link isUploadRequest}) carry no default timeout: a multi-megabyte place\n * file over a slow link is bandwidth-bound, so a client-side deadline only\n * fires spuriously. An explicit `options.timeout` still applies to any\n * request; every non-upload request keeps the merged default.\n *\n * @param inputs - The merged config, the built request, and per-request overrides.\n * @returns The config to hand to the transport, with `timeout` omitted when\n * no client-side deadline should apply.\n */\nfunction buildRequestConfig({ merged, options, request }: RequestConfigInputs): RequestConfig {\n\tconst shouldOmitDefaultTimeout = options?.timeout === undefined && isUploadRequest(request);\n\treturn {\n\t\tapiKey: merged.apiKey,\n\t\tbaseUrl: merged.baseUrl,\n\t\t...(shouldOmitDefaultTimeout ? {} : { timeout: merged.timeout }),\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\tdetails: err.details,\n\t\toperationKey: spec.operationLimit.operationKey,\n\t\trequiredScopes: spec.requiredScopes,\n\t\tstatusCode: err.statusCode,\n\t});\n}\n"],"mappings":";;;;;;;;;;;;;;AAUA,SAAgB,iBAAiB,OAAiC;CACjE,IAAI,OAAO,UAAU,UACpB,OAAO;CAGR,MAAM,SAAS,IAAI,KAAK,KAAK;CAC7B,OAAO,CAAC,OAAO,MAAM,OAAO,QAAQ,CAAC;AACtC;;;;;;;;;;;;ACRA,SAAgB,SAAS,OAAkD;CAC1E,OAAO,OAAO,UAAU,SAAS,KAAK,KAAK,MAAM;AAClD;;;;;;;;;;;;;;ACEA,SAAgB,cAAc,OAAuC;CACpE,OAAO,YAAY,uBAAO,IAAI,IAAI,CAAC;AACpC;AAEA,SAAS,YAAY,OAAgB,MAA0C;CAC9E,IAAI,UAAU,MAEb,OAAO;CAGR,IAAI,OAAO,UAAU,YAAY,OAAO,UAAU,YAAY,OAAO,UAAU,WAC9E,OAAO;CAGR,IAAI,MAAM,QAAQ,KAAK,GACtB,OAAO,YAAY,OAAO,IAAI;CAG/B,IAAI,SAAS,KAAK,GACjB,OAAO,aAAa,OAAO,IAAI;AAIjC;AAEA,SAAS,YAAY,OAA+B,MAA0C;CAC7F,IAAI,KAAK,IAAI,KAAK,GACjB;CAGD,KAAK,IAAI,KAAK;CACd,MAAM,QAA0B,CAAC;CACjC,KAAK,MAAM,QAAQ,OAAO;EACzB,MAAM,YAAY,YAAY,MAAM,IAAI;EACxC,IAAI,cAAc,KAAA,GACjB;EAGD,MAAM,KAAK,SAAS;CACrB;CAEA,KAAK,OAAO,KAAK;CACjB,OAAO;AACR;AAEA,SAAS,aAAa,OAAgC,MAA0C;CAC/F,IAAI,KAAK,IAAI,KAAK,GACjB;CAGD,KAAK,IAAI,KAAK;CACd,MAAM,UAAsC,CAAC;CAC7C,KAAK,MAAM,CAAC,KAAK,SAAS,OAAO,QAAQ,KAAK,GAAG;EAChD,MAAM,YAAY,YAAY,MAAM,IAAI;EACxC,IAAI,cAAc,KAAA,GACjB;EAGD,QAAQ,KAAK,CAAC,KAAK,SAAS,CAAC;CAC9B;CAEA,KAAK,OAAO,KAAK;CACjB,OAAO,OAAO,YAAY,OAAO;AAClC;;;AC1EA,MAAM,gBAAgB;;;;;;;;;;;;;AAsBtB,IAAa,gBAAb,MAA2B;;CAE1B,iBAAqC,KAAA;CACrC,UAAmC,KAAA;;;;;;;;;;CAWnC,QAAe,QAAyB,KAAmB;EAC1D,KAAKA,UAAU;GACd,oBAAoB,OAAO;GAC3B,SAAS,MAAM,OAAO,eAAe;EACtC;CACD;;;;;;;CAQA,QAAe,KAAmB;EACjC,KAAKC,iBAAiB;EACtB,IAAI,KAAKD,YAAY,KAAA,GACpB,KAAKA,UAAU;GACd,GAAG,KAAKA;GACR,oBAAoB,KAAKA,QAAQ,qBAAqB;EACvD;CAEF;;;;;;;;;CAUA,OAAc,KAAqB;EAClC,IAAI,KAAKA,YAAY,KAAA,GACpB,OAAO;EAGR,MAAM,EAAE,oBAAoB,YAAY,KAAKA;EAC7C,IAAI,sBAAsB,GACzB,OAAO,KAAK,IAAI,GAAG,UAAU,GAAG;EAGjC,IAAI,KAAKC,mBAAmB,KAAA,GAC3B,OAAO;EAGR,MAAM,YAAY,UAAU,OAAO;EACnC,OAAO,KAAK,IAAI,GAAG,KAAKA,iBAAiB,WAAW,GAAG;CACxD;AACD;;;;;;;;;;;;;;;;;;ACnEA,IAAa,aAAb,MAAwB;CACvB,0BAAmB,IAAI,IAA2B;CAClD;CACA,4BAAqB,IAAI,IAA2B;;;;;;CAOpD,YAAY,OAAkB;EAC7B,KAAKE,SAAS;CACf;;;;;;;;CASA,MAAa,UAAU,OAA8B;EACpD,MAAM,WAAW,KAAKD,QAAQ,IAAI,KAAK,KAAK,QAAQ,QAAQ;EAC5D,MAAM,eAAe,YAA2B,KAAKG,UAAU,KAAK;EAQpE,MAAM,OAAO,SAAS,KAAK,cAAc,YAAY;EACrD,KAAKH,QAAQ,IAAI,OAAO,IAAI;EAC5B,MAAM;CACP;;;;;;;;;CAUA,QAAe,OAAe,QAA2C;EACxE,IAAI,WAAW,KAAA,GACd;EAGD,KAAKI,SAAS,KAAK,CAAC,CAAC,QAAQ,QAAQ,KAAK,IAAI,CAAC;CAChD;CAEA,MAAMD,UAAU,OAA8B;EAC7C,MAAM,UAAU,KAAKC,SAAS,KAAK;EACnC,MAAM,SAAS,QAAQ,OAAO,KAAK,IAAI,CAAC;EACxC,IAAI,SAAS,GACZ,MAAM,KAAKH,OAAO,MAAM;EAGzB,QAAQ,QAAQ,KAAK,IAAI,CAAC;CAC3B;CAEA,SAAS,OAA8B;EACtC,MAAM,WAAW,KAAKC,UAAU,IAAI,KAAK;EACzC,IAAI,aAAa,KAAA,GAChB,OAAO;EAGR,MAAM,UAAU,IAAI,cAAc;EAClC,KAAKA,UAAU,IAAI,OAAO,OAAO;EACjC,OAAO;CACR;AACD;;;;;;;;;;;;;;ACxDA,eAAsB,sBACrB,SACA,EAAE,QAAQ,OAAO,MAAM,SACyB;CAChD,eAAe,eAA8D;EAC5E,MAAM,YAAY,OAAO;EACzB,OAAO,KAAK,OAAO;CACpB;CAEA,IAAI,SAAS,MAAM,aAAa;CAEhC,KAAK,IAAI,QAAQ,GAAG,QAAQ,OAAO,YAAY,SAAS;EACvD,IAAI,OAAO,WAAW,CAAC,YAAY,OAAO,KAAK,MAAM,GACpD,OAAO;EAGR,MAAM,EAAE,QAAQ;EAChB,MAAM,UAAU,QAAQ,GAAG,GAAG;EAC9B,MAAM,SAAS,mBAAmB,KAAK;GAAE,SAAS;GAAO,YAAY,OAAO;EAAW,CAAC;EACxF,MAAM,cAAc,MAAM;EAC1B,MAAM,MAAM,MAAM;EAElB,SAAS,MAAM,aAAa;CAC7B;CAEA,OAAO;AACR;;;;;;;;;;;;;;ACrCA,SAAgB,sBACf,aACA,SACqB;CACrB,IAAI,gBAAgB,KAAA,GACnB;CAGD,MAAM,SAAS,YACb,MAAM,GAAG,CAAC,CACV,KAAK,SAAS,KAAK,KAAK,CAAC,CAAC,CAC1B,QAAQ,SAAS,SAAS,EAAE,CAAC,CAC7B,KAAK,SAAS,OAAO,IAAI,CAAC,CAAC,CAC3B,QAAQ,UAAU,OAAO,SAAS,KAAK,CAAC;CAC1C,IAAI,OAAO,WAAW,GACrB;CAGD,OAAO,KAAK,IAAI,GAAG,KAAK,MAAM,OAAO,OAAO,OAAO,CAAC,CAAC;AACtD;;;;;;;;;;;;AAaA,SAAgB,sBACf,SAC8B;CAC9B,MAAM,YAAY,sBAAsB,QAAQ,2BAA2B,GAAG,MAAM;EACnF,OAAO,KAAK,IAAI,GAAG,CAAC;CACrB,CAAC;CACD,MAAM,eAAe,sBAAsB,QAAQ,uBAAuB,GAAG,MAAM;EAClF,OAAO,KAAK,IAAI,GAAG,CAAC;CACrB,CAAC;CACD,IAAI,cAAc,KAAA,KAAa,iBAAiB,KAAA,GAC/C;CAGD,OAAO;EAAE;EAAW;CAAa;AAClC;;;;;;;;;;;;;ACrDA,SAAgB,0BACf,QAC8B;CAC9B,IAAI,OAAO,SACV,OAAO,sBAAsB,OAAO,KAAK,OAAO;CAGjD,MAAM,EAAE,QAAQ;CAChB,IAAI,eAAe,kBAAkB,IAAI,cAAc,KAAA,GACtD,OAAO;EAAE,WAAW,IAAI;EAAW,cAAc,IAAI;CAAkB;AAIzE;;;;;;;;;;;;;;;;;ACWA,IAAa,iBAAb,MAA4B;CAC3B;CACA;CACA;CACA;CAEA,eAAe;CACf,SAAwB,QAAQ,QAAQ;CACxC,aAAqB,KAAK,IAAI;;;;;;;;;CAU9B,YAAY,OAAuB,OAAuB,OAAkB;EAC3E,KAAKI,cAAc,MAAO,MAAM;EAChC,MAAM,gBAAgB,MAAM,iBAAiB,KAAK,IAAI,GAAG,MAAM,YAAY;EAC3E,KAAKC,kBAAkB,gBAAgB,KAAKD;EAC5C,KAAKD,SAAS;EACd,KAAKG,SAAS;CACf;;;;;;;;;;CAWA,MAAa,aAAgB,MAAoC;EAChE,MAAM,SAAS,KAAKC,OAAO,KAAK,YAAY,KAAKC,cAAc,CAAC;EAChE,KAAKD,SAAS;EACd,MAAM;EACN,OAAO,KAAK;CACb;CAEA,MAAMC,gBAA+B;EACpC,MAAM,MAAM,KAAK,IAAI,KAAK,IAAI,GAAG,KAAKC,UAAU;EAChD,MAAM,UAAU,KAAK,IAAI,GAAG,KAAKC,gBAAgB,MAAM,KAAKD,WAAW;EACvE,KAAKA,aAAa;EAElB,IAAI,UAAU,KAAKL,eAAe,KAAKC,iBAAiB;GACvD,KAAKK,eAAe,UAAU,KAAKN;GACnC;EACD;EAEA,MAAM,SAAS,UAAU,KAAKA,cAAc,KAAKC;EACjD,KAAKF,OAAO,cAAc,MAAM;EAChC,MAAM,KAAKG,OAAO,MAAM;EACxB,KAAKI,eAAe,KAAKL;EACzB,KAAKI,aAAa,MAAM;CACzB;AACD;;;;;;;;;;AC1FA,eAAsB,cAAiB,SAAyC;CAC/E,IAAI;EAEH,OAAO;GAAE,MAAA,MADU;GACJ,SAAS;EAAK;CAC9B,SAAS,KAAK;EACb,OAAO;GAAE,KAAK,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC;GAAG,SAAS;EAAM;CACnF;AACD;;;ACXA,MAAM,oBAAoB;AAE1B,MAAME,wBAAsB;AAiC5B,MAAM,8BAAmD,IAAI,IAAI;CAChE;CACA;CACA;CACA;AACD,CAAC;AAED,MAAM,2BAA2B;AAKjC,MAAM,qBAAqB;AAC3B,MAAM,kBAAkB;AACxB,MAAM,cAAc;AACpB,MAAM,qBAAqB;;;;;;;;;;;;;;;;AAiB3B,SAAgB,sBACf,aACA,SACqB;CACrB,IAAI,CAAC,WAAW,aAAa,OAAO,GACnC;CAGD,OACC,aAAa,SAAS;EAAE,OAAO;EAAY,MAAM;CAAmB,CAAC,KACrE,aAAa,SAAS;EAAE,OAAO;EAAS,MAAM;CAAgB,CAAC;AAEjE;;;;;;;;;AAUA,SAAgB,sBAAsB,SAAyD;CAC9F,MAAM,SAAiC,CAAC;CACxC,KAAK,MAAM,CAAC,MAAM,UAAU,OAAO,QAAQ,OAAO,GACjD,IAAI,4BAA4B,IAAI,IAAI,KAAK,KAAK,WAAW,wBAAwB,GACpF,OAAO,QAAQ;CAIjB,OAAO;AACR;;;;;;;AAQA,SAAgB,gBAAgB,SAA0C;CACzE,OAAO,OAAO,YAAY,OAAO;AAClC;;;;;;;;;AAUA,SAAgB,WACf,MACA,QACwB;CACxB,OAAO,OAAO,UAAU,OAAO,OAAO,KAAK,MAAM,GAAG,iBAAiB;AACtE;;;;;;;;;;;;;;;;;AAkBA,SAAgB,kBAAkB,EAAE,OAAO,SAAS,UAAU,QAAoC;CAEjG,OAAO,IAAI,SACV,gDAFmB,SAAS,QAAQ,IAAIA,qBAAmB,KAAK,UAEJ,IAAI,OAAO,KAAK,MAAM,EAAE,eACpF;EACC;EACA,SAAS,KAAK,MAAM,GAAG,iBAAiB;EACxC,WAAW,QAAQ;EACnB,QAAQ,QAAQ;EAChB,iBAAiB,sBAAsB,gBAAgB,SAAS,OAAO,CAAC;EACxE,YAAY,SAAS;EACrB,oBAAoB,KAAK;EACzB,KAAK,QAAQ;CACd,CACD;AACD;AAEA,SAAS,aAAa,MAAc,KAA0D;CAC7F,MAAM,OAAO,IAAI,KAAK,KAAK,IAAI;CAC/B,IAAI,SAAS,MACZ;CAGD,MAAM,QAAQ,KAAK,QAAQ,KAAK,EAAE,CAAC;CACnC,MAAM,MAAM,KAAK,YAAY,CAAC,CAAC,QAAQ,IAAI,OAAO,KAAK;CACvD,IAAI,QAAQ,IACX;CAKD,MAAM,OAFQ,KAAK,MAAM,OAAO,GAEf,CAAC,CAAC,QAAQ,aAAa,GAAG,CAAC,CAAC,QAAQ,oBAAoB,GAAG,CAAC,CAAC,KAAK;CACnF,OAAO,SAAS,KAAK,KAAA,IAAY;AAClC;AAEA,SAAS,WAAW,aAAiC,SAA0B;CAC9E,IAAI,aAAa,YAAY,CAAC,CAAC,SAAS,WAAW,MAAM,MACxD,OAAO;CAGR,MAAM,OAAO,QAAQ,UAAU,CAAC,CAAC,YAAY;CAC7C,OAAO,KAAK,WAAW,OAAO,KAAK,KAAK,WAAW,gBAAgB;AACpE;;;;;;;;;;;ACjLA,MAAM,yBAAgD,OAAO,OAAO,CACnE,6BACA,2BACD,CAAC;;;;;;;;;;AAWD,SAAgB,mBAAmB,OAA2C;CAC7E,OAAO,OAAO,UAAU;AACzB;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,SAAgB,sBAAsB,QAAgB,YAAgC;CACrF,KAAK,MAAM,OAAO,wBAAwB;EACzC,MAAM,aAAa,eAAe,QAAQ,IAAI,OAAO,OAAO,IAAI,GAAG,CAAC,CAAC;EACrE,IAAI,eAAe,KAAA,GAClB,OAAO;CAET;AAGD;;;;;;;;;;;;;;;;;AAkBA,SAAS,eAAe,OAAoC;CAC3D,IAAI;EAIH,MAAM,aAAa,QAAQ,IAAI,OAAO,aAAa;EACnD,IAAI,CAAC,mBAAmB,UAAU,GACjC;EAGD,MAAM,aAAa,QAAQ,UAAU,YAAY,CAAC,EAAE,SAAS,MAAM,CAAC,CAAC;EACrE,OAAO,OAAO,QAAQ,IAAI,YAAY,UAAU,MAAM,aAAa,aAAa,KAAA;CACjF,QAAQ;EAGP;CACD;AACD;;;;;;;;;;;;;ACpFA,SAAgB,gBAAgB,SAA+B;CAC9D,OAAO,QAAQ,gBAAgB,YAAY,QAAQ,gBAAgB;AACpE;;;ACKA,MAAM,sBAAsB;AAU5B,MAAM,oBAAoB;;;;;;;;;;;;;AAmD1B,SAAgB,iBAAiB,MAAmC;CACnE,IAAI,SAAS,QAAQ,OAAO,SAAS,UACpC;CAGD,MAAM,YAAY,QAAQ,IAAI,MAAM,WAAW;CAC/C,IAAI,OAAO,cAAc,UACxB,OAAO;CAGR,OAAO,kBAAkB,IAAI;AAC9B;;;;;;;;;;AAWA,SAAgB,oBAAoB,MAAmC;CACtE,IAAI,SAAS,QAAQ,OAAO,SAAS,UACpC;CAGD,MAAM,UAAU,QAAQ,IAAI,MAAM,SAAS;CAC3C,IAAI,OAAO,YAAY,UACtB,OAAO;CAGR,OAAO,qBAAqB,IAAI;AACjC;;;;;;;;;;;AAYA,SAAgB,uBAAuB,aAAyC;CAC/E,OAAO,sBAAsB,cAAc,GAAG,MAAM,KAAK,IAAI,GAAG,CAAC,CAAC,KAAK;AACxE;;;;;;;;AASA,SAAgB,SAAS,SAAsB,QAA+B;CAE7E,OAAO,GADM,OAAO,QAAQ,SAAS,GAAG,IAAI,OAAO,QAAQ,MAAM,GAAG,EAAE,IAAI,OAAO,UAChE,QAAQ;AAC1B;;;;;;;;AASA,SAAgB,kBAAkB,SAAsB,QAAqC;CAC5F,MAAM,UAAU,IAAI,QAAQ,EAC3B,aAAa,OAAO,OACrB,CAAC;CAED,MAAM,UAAwB;EAC7B;EACA,QAAQ,QAAQ;CACjB;CAEA,IAAI,QAAQ,gBAAgB,UAC3B,QAAQ,OAAO,QAAQ;MACjB,IAAI,QAAQ,gBAAgB,YAAY;EAC9C,QAAQ,IAAI,qBAAqB,0BAA0B;EAC3D,QAAQ,OAAO,QAAQ;CACxB,OAAO,IAAI,QAAQ,SAAS,KAAA,GAAW;EACtC,QAAQ,IAAI,qBAAqB,kBAAkB;EACnD,QAAQ,OAAO,KAAK,UAAU,QAAQ,IAAI;CAC3C;CAEA,oBAAoB,SAAS,OAAO;CAEpC,IAAI,OAAO,YAAY,KAAA,GACtB,QAAQ,SAAS,YAAY,QAAQ,OAAO,OAAO;CAGpD,OAAO;AACR;;;;;;;;;AAUA,SAAgB,sBACf,YAAmE,OACnE,EAAE,mBAAmB,uBAAuB,MAAM,KAAK,QAA8B,CAAC,GACzE;CACb,MAAM,gBAAgB,4BAA4B,gBAAgB;CAElE,OAAO,EACN,MAAM,QACL,aACA,QACgD;EAChD,MAAM,MAAM,SAAS,aAAa,MAAM;EACxC,MAAM,UAAU,kBAAkB,aAAa,MAAM;EAGrD,QAAQ,aAAa,cAAc,WAAW;EAC9C,MAAM,SAAS;GAAE,QAAQ,YAAY;GAAQ;EAAI;EAEjD,MAAM,EAAE,WAAW,gBAAgB,MAAM,gBAAgB,KAAK,YAAY;GACzE,OAAO,UAAU,KAAK,OAAO;EAC9B,CAAC;EACD,IAAI,CAAC,YAAY,SAChB,OAAO;GAAE,KAAK,aAAa,YAAY,KAAK,MAAM;GAAG,SAAS;EAAM;EAMrE,MAAM,UAA0B;GAAE;GAAW,QAAQ,OAAO;GAAQ,KAAK,OAAO;EAAI;EACpF,MAAM,aAAa,MAAM,cACxB,sBAAsB,YAAY,MAAM,OAAO,CAChD;EACA,IAAI,CAAC,WAAW,SACf,OAAO;GAAE,KAAK,aAAa,WAAW,KAAK,MAAM;GAAG,SAAS;EAAM;EAGpE,OAAO,WAAW;CACnB,EACD;AACD;AAEA,SAAS,qBAAqB,MAAkC;CAC/D,MAAM,SAAS,QAAQ,IAAI,MAAM,QAAQ;CACzC,IAAI,CAAC,MAAM,QAAQ,MAAM,GACxB;CAGD,MAAM,CAAC,SAAS;CAChB,IAAI,OAAO,UAAU,YAAY,UAAU,MAC1C;CAGD,OAAO;AACR;AAEA,SAAS,kBAAkB,MAAkC;CAC5D,MAAM,QAAQ,qBAAqB,IAAI;CACvC,IAAI,UAAU,KAAA,GACb;CAGD,MAAM,OAAO,QAAQ,IAAI,OAAO,MAAM;CACtC,IAAI,OAAO,SAAS,UACnB,OAAO;CAGR,OAAO,OAAO,SAAS,WAAW,OAAO,IAAI,IAAI,KAAA;AAClD;AAEA,SAAS,qBAAqB,MAAkC;CAC/D,MAAM,QAAQ,qBAAqB,IAAI;CACvC,IAAI,UAAU,KAAA,GACb;CAGD,MAAM,UAAU,QAAQ,IAAI,OAAO,SAAS;CAC5C,OAAO,OAAO,YAAY,WAAW,UAAU,KAAA;AAChD;;;;;;;;;;AAWA,SAAS,oBAAoB,SAAkB,SAA4B;CAC1E,MAAM,iBAAiB,QAAQ,WAAW,CAAC;CAC3C,KAAK,MAAM,CAAC,MAAM,UAAU,OAAO,QAAQ,cAAc,GAAG;EAC3D,IAAI,KAAK,YAAY,MAAM,aAC1B;EAGD,QAAQ,IAAI,MAAM,KAAK;CACxB;CAEA,IAAI,gBAAgB,OAAO,GAC1B,QAAQ,IAAI,mBAAmB,OAAO;AAExC;;;;;;;;;;;;;;;AAgBA,SAAS,4BACR,kBAC+C;CAC/C,IAAI;CACJ,QAAQ,YAAY;EACnB,IAAI,CAAC,gBAAgB,OAAO,GAC3B;EAGD,WAAW,iBAAiB;EAC5B,OAAO;CACR;AACD;;;;;;;;;;AAWA,eAAe,gBACd,KACA,MACgE;CAChE,MAAM,QAAQ,IAAI;CAClB,MAAM,cAAc,MAAM,cAAc,KAAK,CAAC;CAG9C,OAAO;EAAE,WAAW,KAAK,IAAI,GAAG,IAAI,IAAI,KAAK;EAAG;CAAY;AAC7D;AAEA,SAAS,aAAa,OAAc,QAAuD;CAC1F,OAAO,IAAI,aAAa,0BAA0B;EACjD;EACA,QAAQ,OAAO;EACf,KAAK,OAAO;CACb,CAAC;AACF;AAEA,SAAS,sBAAsB,EAAE,MAAM,SAAS,UAAwC;CACvF,MAAM,OAAO,QAAQ;CACrB,IAAI,YAAY,KAAA,KAAa,SAAS,KAAA,GACrC,OAAO;CAGR,IAAI,YAAY,KAAA,GACf,OAAO,GAAG,KAAK,SAAS,KAAK;CAG9B,IAAI,SAAS,KAAA,GACZ,OAAO,GAAG,KAAK,IAAI;CAGpB,OAAO,GAAG,KAAK,IAAI,QAAQ,SAAS,KAAK;AAC1C;AAEA,SAAS,eAAe,MAAmC;CAC1D,MAAM,EAAE,SAAS,SAAS,aAAa;CACvC,MAAM,EAAE,WAAW;CACnB,MAAM,UAAU,gBAAgB,SAAS,OAAO;CAChD,MAAM,iBAAiB;EACtB,WAAW,QAAQ;EACnB,QAAQ,QAAQ;EAChB,iBAAiB,sBAAsB,OAAO;EAC9C,YAAY;EACZ,KAAK,QAAQ;CACd;CAIA,MAAM,iBAAiB,sBAAsB,QAAQ,sBAAsB,OAAO;CAClF,IAAI,mBAAmB,KAAA,GACtB,OAAO,IAAI,SAAS,QAAQ,UAAU;EAAE,GAAG;EAAgB;CAAe,CAAC;CAG5E,MAAM,OAAO,WAAW,SAAS,KAAK,MAAM;CAC5C,MAAM,OAAO,iBAAiB,IAAI;CAElC,OAAO,IAAI,SAAS,sBAAsB;EAAE;EAAM,SADlC,oBAAoB,IACoB;EAAG;CAAO,CAAC,GAAG;EACrE,GAAG;EACH;EACA,SAAS;CACV,CAAC;AACF;;;;;;;;;AAUA,SAAS,UAAU,MAAiC;CACnD,IAAI;EACH,OAAO;GAAE,MAAM,KAAK,MAAM,IAAI;GAAG,SAAS;EAAK;CAChD,SAAS,KAAK;EACb,OAAO;GAAE,KAAK,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC;GAAG,SAAS;EAAM;CACnF;AACD;;;;;;;;;;;AAYA,eAAe,sBACd,UACmE;CACnE,MAAM,OAAO,MAAM,SAAS,KAAK;CACjC,OAAO;EACN,QAAQ,SAAS,KAAK;GAAE,MAAM,KAAA;GAAW,SAAS;EAAK,IAAI,UAAU,IAAI;EACzE;CACD;AACD;AAEA,eAAe,0BAA0B,UAA6C;CACrF,MAAM,UAAU,gBAAgB,SAAS,OAAO;CAChD,MAAM,EAAE,QAAQ,SAAS,MAAM,sBAAsB,QAAQ;CAC7D,OAAO,IAAI,eAAe,gBAAgB;EACzC,SAAS,WAAW,MAAM,MAAM;EAChC,WAAW,sBAAsB,QAAQ,2BAA2B,GAAG,MAAM;GAC5E,OAAO,KAAK,IAAI,GAAG,CAAC;EACrB,CAAC;EACD,mBAAmB,uBAAuB,QAAQ,oBAAoB;EACtE,YAAY,SAAS;CACtB,CAAC;AACF;;;;;;;;;;;;;;;;AAiBA,eAAe,sBACd,UACA,SACgD;CAChD,IAAI,SAAS,WAAW,KACvB,OAAO;EAAE,KAAK,MAAM,0BAA0B,QAAQ;EAAG,SAAS;CAAM;CAGzE,MAAM,EAAE,QAAQ,SAAS,MAAM,sBAAsB,QAAQ;CAE7D,IAAI,SAAS,UAAU,KACtB,OAAO;EACN,KAAK,eAAe;GAAE;GAAS;GAAQ,SAAS;GAAM;EAAS,CAAC;EAChE,SAAS;CACV;CAGD,IAAI,CAAC,OAAO,SACX,OAAO;EACN,KAAK,kBAAkB;GAAE,OAAO,OAAO;GAAK;GAAS;GAAU;EAAK,CAAC;EACrE,SAAS;CACV;CAGD,OAAO;EACN,MAAM;GACL,MAAM,OAAO;GACb,SAAS,gBAAgB,SAAS,OAAO;GACzC,QAAQ,SAAS;EAClB;EACA,SAAS;CACV;AACD;;;;;;;;;;;;;;;AC3bA,SAAgB,oBAAoB,SAA2D;CAC9F,OAAO;EACN,YAAY,QAAQ,cAAc,sBAAsB;EACxD,OAAO,QAAQ,SAAS;CACzB;AACD;;;;;;;;;;;;AC8DA,SAAgB,UAAU,SAA2D;CACpF,OAAO;EAAE,MAAM;EAAS,SAAS;CAAK;AACvC;;;;;;;;AASA,SAAgB,qBAAwD;CACvE,OAAO;EAAE,MAAM,KAAA;EAAW,SAAS;CAAK;AACzC;AAEA,MAAM,kBAAkB,OAAO,OAAO;CACrC,SAAS;CACT,YAAY;CACZ,mBAAmB,2BAA2B;CAC9C,yBAAyB,2BAA2B;CACpD,YAAY;CACZ,SAAS;AACV,CAA6C;;;;;;;;;;AAuB7C,IAAa,iBAAb,MAA4B;CAC3B;CACA;CACA;CACA;CACA,0BAAmB,IAAI,IAA4B;CACnD;;;;;;;;;CAUA,YAAY,EAAE,QAAQ,OAAO,YAAY,OAAO,GAAG,aAAqC;EACvF,MAAM,WAAW,oBAAoB;GAAE;GAAY;EAAM,CAAC;EAC1D,KAAKI,cAAc,SAAS;EAC5B,KAAKE,SAAS,SAAS;EACvB,KAAKL,WAAW,IAAI,WAAW,KAAKK,MAAM;EAC1C,KAAKH,SAAS,SAAS,CAAC;EACxB,KAAKD,UAAU,OAAO,OAAO;GAC5B,GAAG;GACH;GACA,GAAG;EACJ,CAAC;CACF;;;;;;;;;;;;;CAcA,MAAa,aAAmB,EAC/B,SACA,YACA,QACyD;EACzD,MAAM,SAAS,YAAY,KAAKA,SAAS;GACxC,gBAAgB,KAAK;GACrB,YAAY,KAAK;GACjB,gBAAgB,WAAW,CAAC;EAC7B,CAAC;EACD,MAAM,gBAAgB,KAAK,aAAa,UAAU;EAClD,IAAI,CAAC,cAAc,SAClB,OAAO;EAGR,MAAM,gBAAgB,mBAAmB;GAAE;GAAQ;GAAS,SAAS,cAAc;EAAK,CAAC;EAEzF,MAAM,aAAa,MADL,KAAKK,UAAU,OAAO,QAAQ,KAAK,cACpB,CAAC,CAAC,aAAa,YAAY;GACvD,OAAO,sBAAsB,cAAc,MAAM;IAChD,QAAQ;IACR,OAAO,KAAKJ;IACZ,MAAM,KAAKK,WAAW,OAAO,QAAQ,aAAa;IAClD,OAAO,KAAKF;GACb,CAAC;EACF,CAAC;EACD,IAAI,CAAC,WAAW,SACf,OAAO;GAAE,KAAK,sBAAsB,WAAW,KAAK,IAAI;GAAG,SAAS;EAAM;EAG3E,OAAO,KAAK,MAAM,WAAW,IAAI;CAClC;;;;;;CAOA,IAAW,QAAmB;EAC7B,OAAO,KAAKA;CACb;;;;;;;;;;;CAYA,WACC,QACA,eAC0E;EAC1E,OAAO,OAAO,WAAW;GACxB,MAAM,KAAKL,SAAS,UAAU,MAAM;GACpC,MAAM,aAAa,MAAM,KAAKG,YAAY,QAAQ,QAAQ,aAAa;GACvE,KAAKH,SAAS,QAAQ,QAAQ,0BAA0B,UAAU,CAAC;GACnE,OAAO;EACR;CACD;CAEA,UAAU,QAAgB,OAAuC;EAChE,MAAM,MAAM,GAAG,OAAO,IAAI,MAAM;EAChC,MAAM,WAAW,KAAKI,QAAQ,IAAI,GAAG;EACrC,IAAI,aAAa,KAAA,GAChB,OAAO;EAGR,MAAM,QAAQ,IAAI,eAAe,OAAO,KAAKF,QAAQ,KAAKG,MAAM;EAChE,KAAKD,QAAQ,IAAI,KAAK,KAAK;EAC3B,OAAO;CACR;AACD;;;;;;;;;;;;AAaA,SAAS,mBAAmB,EAAE,QAAQ,SAAS,WAA+C;CAC7F,MAAM,2BAA2B,SAAS,YAAY,KAAA,KAAa,gBAAgB,OAAO;CAC1F,OAAO;EACN,QAAQ,OAAO;EACf,SAAS,OAAO;EAChB,GAAI,2BAA2B,CAAC,IAAI,EAAE,SAAS,OAAO,QAAQ;CAC/D;AACD;AAEA,SAAS,sBACR,KACA,MACiB;CACjB,IAAI,KAAK,mBAAmB,KAAA,GAC3B,OAAO;CAGR,IAAI,eAAe,iBAClB,OAAO;CAGR,IAAI,EAAE,eAAe,WACpB,OAAO;CAGR,IAAI,IAAI,eAAe,OAAO,IAAI,eAAe,KAChD,OAAO;CAGR,OAAO,IAAI,gBAAgB,IAAI,SAAS;EACvC,OAAO,IAAI;EACX,MAAM,IAAI;EACV,SAAS,IAAI;EACb,cAAc,KAAK,eAAe;EAClC,gBAAgB,KAAK;EACrB,YAAY,IAAI;CACjB,CAAC;AACF"}
@@ -1,4 +1,4 @@
1
- import { n as NetworkError, r as ApiError, t as RateLimitError } from "./rate-limit-B20REZEY.mjs";
1
+ import { n as NetworkError, r as ApiError, t as RateLimitError } from "./rate-limit-D1MQZNAE.mjs";
2
2
  //#region src/errors/permission-error.ts
3
3
  /**
4
4
  * Thrown when the Roblox Open Cloud API returns a 401 or 403 for an operation
@@ -172,10 +172,35 @@ const TRANSIENT_TRANSPORT_CODES = Object.freeze([
172
172
  * HTTP status: the status belongs to the gateway, not to the API, and a
173
173
  * gateway `400` says nothing about the validity of the request.
174
174
  *
175
+ * Name it in a per-request `retryableTransportCodes` override to opt an
176
+ * operation into (or out of) gateway-rejection retry.
177
+ *
175
178
  * @since 0.1.2
176
179
  */
177
180
  const GATEWAY_REJECTED = "GATEWAY_REJECTED";
178
181
  /**
182
+ * Synthetic transport code for a 2xx whose body could not be parsed as JSON
183
+ * ({@link ApiError.unparsedBodyLength}). Open Cloud does not answer a success
184
+ * status with a malformed document; what this failure describes in practice is
185
+ * a body the edge delivered short, ending mid-token at exactly the length that
186
+ * arrived. The next read is a fresh body and usually a whole one.
187
+ *
188
+ * Classifying it by transport code rather than by HTTP status is what makes it
189
+ * recoverable at all: the status is a 200, which no `retryableStatuses` list
190
+ * contains, so a status-keyed decision could only ever say "do not retry".
191
+ *
192
+ * Retrying is justified by the operation being safe to repeat, never by the
193
+ * request having gone unprocessed — a 200 proves it was processed. So this code
194
+ * is in {@link IDEMPOTENT_METHOD_DEFAULTS} only. Creates and uploads leave it
195
+ * out: their write landed, and re-issuing it to re-read the answer would risk a
196
+ * second resource for a response body, which is the wrong trade. A consumer who
197
+ * can tolerate that duplicate names this code in a per-request
198
+ * `retryableTransportCodes` override.
199
+ *
200
+ * @since 0.1.5
201
+ */
202
+ const RESPONSE_UNPARSEABLE = "RESPONSE_UNPARSEABLE";
203
+ /**
179
204
  * Default retry policy for idempotent operations (read, list, update,
180
205
  * delete). Safe to retry on rate limits, transient server errors, and
181
206
  * transient transport failures.
@@ -188,7 +213,7 @@ const IDEMPOTENT_METHOD_DEFAULTS = Object.freeze({
188
213
  503,
189
214
  504
190
215
  ]),
191
- retryableTransportCodes: TRANSIENT_TRANSPORT_CODES
216
+ retryableTransportCodes: Object.freeze([...TRANSIENT_TRANSPORT_CODES, RESPONSE_UNPARSEABLE])
192
217
  });
193
218
  /**
194
219
  * Default retry policy for create operations. Retries rate limits only (no
@@ -279,9 +304,11 @@ function computeRetryWaitMs(error, options) {
279
304
  * Decides whether a failed request is eligible for retry. {@link
280
305
  * RateLimitError} (checked against 429) and {@link ApiError} (checked against
281
306
  * its `statusCode`) are retryable when their status is in `retryableStatuses`.
282
- * An {@link ApiError} carrying a `gatewaySummary` is the exception: it is
283
- * checked against {@link GATEWAY_REJECTED} in `retryableTransportCodes`
284
- * instead, and its status is never consulted. A {@link NetworkError} is
307
+ * Two {@link ApiError} shapes are the exception, both checked against
308
+ * `retryableTransportCodes` with their status never consulted: one carrying a
309
+ * `gatewaySummary` is checked against {@link GATEWAY_REJECTED}, and one
310
+ * carrying an `unparsedBodyLength` — a 2xx whose body would not parse —
311
+ * against {@link RESPONSE_UNPARSEABLE}. A {@link NetworkError} is
285
312
  * retryable when its transport code ({@link findErrorCode}) is in
286
313
  * `retryableTransportCodes`. This is how transient connection resets recover.
287
314
  * A self-aborted request timeout ({@link isTimeoutAbort}) carries no transport
@@ -323,6 +350,7 @@ function shouldRetry(error, config) {
323
350
  if (error instanceof RateLimitError) return config.retryableStatuses.includes(429);
324
351
  if (error instanceof ApiError) {
325
352
  if (error.gatewaySummary !== void 0) return config.retryableTransportCodes.includes(GATEWAY_REJECTED);
353
+ if (error.unparsedBodyLength !== void 0) return config.retryableTransportCodes.includes(RESPONSE_UNPARSEABLE);
326
354
  return config.retryableStatuses.includes(error.statusCode);
327
355
  }
328
356
  if (error instanceof NetworkError) {
@@ -425,6 +453,6 @@ function mergeConfig(clientConfig, { methodDefaults, methodKind, requestOptions
425
453
  }
426
454
  }
427
455
  //#endregion
428
- export { computeRetryWaitMs as a, shouldRetry as c, UPLOAD_METHOD_DEFAULTS as i, findErrorCode as l, IDEMPOTENT_METHOD_DEFAULTS as n, defaultRetryDelay as o, TRANSIENT_TRANSPORT_CODES as r, mergeConfig as s, CREATE_METHOD_DEFAULTS as t, PermissionError as u };
456
+ export { TRANSIENT_TRANSPORT_CODES as a, defaultRetryDelay as c, findErrorCode as d, PermissionError as f, RESPONSE_UNPARSEABLE as i, mergeConfig as l, GATEWAY_REJECTED as n, UPLOAD_METHOD_DEFAULTS as o, IDEMPOTENT_METHOD_DEFAULTS as r, computeRetryWaitMs as s, CREATE_METHOD_DEFAULTS as t, shouldRetry as u };
429
457
 
430
- //# sourceMappingURL=retry-PmpgEwFN.mjs.map
458
+ //# sourceMappingURL=retry-D1HKlycK.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"retry-D1HKlycK.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 operation requires plus the operation key, so a consumer\n * can name them when guiding the user to their API key settings.\n *\n * The scopes are what the operation needs, not a diagnosis of what the\n * credential lacks: a 403 does mean the scopes fall short, but Roblox also\n * answers 401 for a key that is invalid, disabled, or expired. Check\n * {@link ApiError.statusCode} before wording the failure as a missing scope.\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 * Codes for transport-level failures eligible for retry: node-style\n\t * transport codes ({@link findErrorCode}) surfaced as a\n\t * {@link NetworkError}, plus the synthetic {@link GATEWAY_REJECTED} for a\n\t * response served by an edge gateway. Not all of them prove the request\n\t * went unprocessed — see {@link TRANSIENT_TRANSPORT_CODES}. Empty for\n\t * create 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 * `ERR_HTTP2_STREAM_ERROR`, `ERR_HTTP2_SESSION_ERROR`, and `UND_ERR_INFO` are\n * the same deaths as spelled by a runtime whose `fetch` negotiates HTTP/2\n * (Node 26 and later). They differ from the socket codes in one way that\n * matters: they do not prove the request went unprocessed. `UND_ERR_INFO`\n * covers both a `GOAWAY` declaring a stream was never started and a stream\n * that was fully sent, and `UND_ERR_SOCKET` can fire once a response is\n * already streaming. Retrying them is therefore justified by the operation\n * being safe to repeat, never by the request having gone unseen — which is\n * why {@link UPLOAD_METHOD_DEFAULTS}, the one write policy that includes\n * them, documents its own grounds.\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\t\"ERR_HTTP2_STREAM_ERROR\",\n\t\"ERR_HTTP2_SESSION_ERROR\",\n\t\"UND_ERR_INFO\",\n]);\n\n/**\n * Synthetic transport code for a response that came from an edge gateway\n * rather than Open Cloud ({@link ApiError.gatewaySummary}). Such a response\n * proves the request was rejected before any Open Cloud handler saw it, so it\n * is classified alongside {@link TRANSIENT_TRANSPORT_CODES} rather than by its\n * HTTP status: the status belongs to the gateway, not to the API, and a\n * gateway `400` says nothing about the validity of the request.\n *\n * Name it in a per-request `retryableTransportCodes` override to opt an\n * operation into (or out of) gateway-rejection retry.\n *\n * @since 0.1.2\n */\nexport const GATEWAY_REJECTED = \"GATEWAY_REJECTED\";\n\n/**\n * Synthetic transport code for a 2xx whose body could not be parsed as JSON\n * ({@link ApiError.unparsedBodyLength}). Open Cloud does not answer a success\n * status with a malformed document; what this failure describes in practice is\n * a body the edge delivered short, ending mid-token at exactly the length that\n * arrived. The next read is a fresh body and usually a whole one.\n *\n * Classifying it by transport code rather than by HTTP status is what makes it\n * recoverable at all: the status is a 200, which no `retryableStatuses` list\n * contains, so a status-keyed decision could only ever say \"do not retry\".\n *\n * Retrying is justified by the operation being safe to repeat, never by the\n * request having gone unprocessed — a 200 proves it was processed. So this code\n * is in {@link IDEMPOTENT_METHOD_DEFAULTS} only. Creates and uploads leave it\n * out: their write landed, and re-issuing it to re-read the answer would risk a\n * second resource for a response body, which is the wrong trade. A consumer who\n * can tolerate that duplicate names this code in a per-request\n * `retryableTransportCodes` override.\n *\n * @since 0.1.5\n */\nexport const RESPONSE_UNPARSEABLE = \"RESPONSE_UNPARSEABLE\";\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: Object.freeze([...TRANSIENT_TRANSPORT_CODES, RESPONSE_UNPARSEABLE]),\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/**\n * Default retry policy for upload operations (place publish and save). Keeps\n * {@link CREATE_METHOD_DEFAULTS}'s 5xx guard (a 5xx comes from Open Cloud and\n * may describe a write that partly landed), but retries transport failures:\n * {@link TRANSIENT_TRANSPORT_CODES} and {@link GATEWAY_REJECTED}.\n *\n * This is the one write policy that retries codes which do not prove the\n * request went unprocessed, and the grounds are specific to a place version:\n * Roblox dedupes identical place content, so a retry that races a publish\n * which did land returns that same version rather than creating a second one.\n * That is load-bearing, not incidental — an upload operation without content\n * dedupe would need its own allowlist.\n */\nexport const UPLOAD_METHOD_DEFAULTS: MethodDefaults = Object.freeze({\n\t...CREATE_METHOD_DEFAULTS,\n\tretryableTransportCodes: Object.freeze([...TRANSIENT_TRANSPORT_CODES, GATEWAY_REJECTED]),\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\n * RateLimitError} (checked against 429) and {@link ApiError} (checked against\n * its `statusCode`) are retryable when their status is in `retryableStatuses`.\n * Two {@link ApiError} shapes are the exception, both checked against\n * `retryableTransportCodes` with their status never consulted: one carrying a\n * `gatewaySummary` is checked against {@link GATEWAY_REJECTED}, and one\n * carrying an `unparsedBodyLength` — a 2xx whose body would not parse —\n * against {@link RESPONSE_UNPARSEABLE}. A {@link NetworkError} is\n * retryable when its transport code ({@link findErrorCode}) is in\n * `retryableTransportCodes`. This is how transient connection resets recover.\n * A self-aborted request timeout ({@link isTimeoutAbort}) carries no transport\n * code, so it is classified as `ETIMEDOUT`: recovered for idempotent methods,\n * never for creates (whose 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\tif (error.gatewaySummary !== undefined) {\n\t\t\treturn config.retryableTransportCodes.includes(GATEWAY_REJECTED);\n\t\t}\n\n\t\tif (error.unparsedBodyLength !== undefined) {\n\t\t\treturn config.retryableTransportCodes.includes(RESPONSE_UNPARSEABLE);\n\t\t}\n\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\t{ methodDefaults, methodKind, requestOptions }: MergeConfigOptions<T>,\n): T {\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":"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"}
@@ -34,6 +34,15 @@ interface ApiErrorOptions extends ErrorOptions {
34
34
  responseHeaders?: Readonly<Record<string, string>> | undefined;
35
35
  /** HTTP status code from the API response. */
36
36
  statusCode: number;
37
+ /**
38
+ * Length, in decoded characters, of a 2xx body that could not be parsed as
39
+ * JSON. Set only by the transport, and only for that failure — nothing else
40
+ * builds an {@link ApiError} over a successful status — so its presence is
41
+ * also how a body-parse failure is told apart from an API rejection. The
42
+ * number is the diagnostic one: a body that stops mid-token at exactly the
43
+ * length the edge delivered is a truncated read, not malformed JSON.
44
+ */
45
+ unparsedBodyLength?: number | undefined;
37
46
  /** Fully-qualified URL of the request that produced this error. */
38
47
  url?: string | undefined;
39
48
  }
@@ -72,6 +81,7 @@ declare class ApiError extends OpenCloudError {
72
81
  override readonly name: string;
73
82
  readonly responseHeaders: Readonly<Record<string, string>> | undefined;
74
83
  readonly statusCode: number;
84
+ readonly unparsedBodyLength: number | undefined;
75
85
  readonly url: string | undefined;
76
86
  /**
77
87
  * Creates a new ApiError.
@@ -243,8 +253,44 @@ interface RetryResolvable {
243
253
  * @since 0.1.0
244
254
  */
245
255
  declare const TRANSIENT_TRANSPORT_CODES: ReadonlyArray<string>;
256
+ /**
257
+ * Synthetic transport code for a response that came from an edge gateway
258
+ * rather than Open Cloud ({@link ApiError.gatewaySummary}). Such a response
259
+ * proves the request was rejected before any Open Cloud handler saw it, so it
260
+ * is classified alongside {@link TRANSIENT_TRANSPORT_CODES} rather than by its
261
+ * HTTP status: the status belongs to the gateway, not to the API, and a
262
+ * gateway `400` says nothing about the validity of the request.
263
+ *
264
+ * Name it in a per-request `retryableTransportCodes` override to opt an
265
+ * operation into (or out of) gateway-rejection retry.
266
+ *
267
+ * @since 0.1.2
268
+ */
269
+ declare const GATEWAY_REJECTED = "GATEWAY_REJECTED";
270
+ /**
271
+ * Synthetic transport code for a 2xx whose body could not be parsed as JSON
272
+ * ({@link ApiError.unparsedBodyLength}). Open Cloud does not answer a success
273
+ * status with a malformed document; what this failure describes in practice is
274
+ * a body the edge delivered short, ending mid-token at exactly the length that
275
+ * arrived. The next read is a fresh body and usually a whole one.
276
+ *
277
+ * Classifying it by transport code rather than by HTTP status is what makes it
278
+ * recoverable at all: the status is a 200, which no `retryableStatuses` list
279
+ * contains, so a status-keyed decision could only ever say "do not retry".
280
+ *
281
+ * Retrying is justified by the operation being safe to repeat, never by the
282
+ * request having gone unprocessed — a 200 proves it was processed. So this code
283
+ * is in {@link IDEMPOTENT_METHOD_DEFAULTS} only. Creates and uploads leave it
284
+ * out: their write landed, and re-issuing it to re-read the answer would risk a
285
+ * second resource for a response body, which is the wrong trade. A consumer who
286
+ * can tolerate that duplicate names this code in a per-request
287
+ * `retryableTransportCodes` override.
288
+ *
289
+ * @since 0.1.5
290
+ */
291
+ declare const RESPONSE_UNPARSEABLE = "RESPONSE_UNPARSEABLE";
246
292
  /** Kind of HTTP method the merge is being performed for. */
247
293
  type MethodKind = "create" | "idempotent";
248
294
  //#endregion
249
- export { RateLimitErrorOptions as a, ApiError as c, RateLimitError as i, ApiErrorOptions as l, RetryResolvable as n, NetworkError as o, TRANSIENT_TRANSPORT_CODES as r, NetworkErrorOptions as s, MethodKind as t };
250
- //# sourceMappingURL=retry-DGY51INM.d.mts.map
295
+ export { TRANSIENT_TRANSPORT_CODES as a, NetworkError as c, ApiErrorOptions as d, RetryResolvable as i, NetworkErrorOptions as l, MethodKind as n, RateLimitError as o, RESPONSE_UNPARSEABLE as r, RateLimitErrorOptions as s, GATEWAY_REJECTED as t, ApiError as u };
296
+ //# sourceMappingURL=retry-DANH6mM9.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"retry-DANH6mM9.d.mts","names":[],"sources":["../src/errors/api-error.ts","../src/errors/network-error.ts","../src/errors/rate-limit.ts","../src/internal/http/retry.ts"],"mappings":";;;;;AAOA;;;UAAiB,eAAA,SAAwB,YAAA;;EAExC,IAAA;;EAEA,OAAA,GAAU,SAAA;EAJ8B;;;;;EAUxC,SAAA;;;;;;;EAOA,cAAA;;EAEA,MAAA;EAmBA;AA6BD;;;;EA1CC,eAAA,GAAkB,QAAA,CAAS,MAAA;;EAE3B,UAAA;;;;;;;;;EASA,kBAAA;;EAEA,GAAA;AAAA;;;;;;;;;;;AAkDsC;;;;ACxFvC;;;;;;;;AAIC;AAYD;;;cDmDa,QAAA,SAAiB,cAAA;EAAA,SACb,IAAA;EAAA,SACA,OAAA,EAAS,SAAA;EAAA,SACT,SAAA;EAAA,SACA,cAAA;EAAA,SACA,MAAA;EAAA,kBACS,IAAA;EAAA,SACT,eAAA,EAAiB,QAAA,CAAS,MAAA;EAAA,SAC1B,UAAA;EAAA,SACA,kBAAA;EAAA,SACA,GAAA;;;;AE7EjB;;;;;;EFwFC,WAAA,CAAY,OAAA,UAAiB,OAAA,EAAS,eAAA;AAAA;;;;;AAxFvC;;;UCAiB,mBAAA,SAA4B,YAAA;;EAE5C,MAAA;;EAEA,GAAA;AAAA;;;;;;;;;;cAYY,YAAA,SAAqB,cAAA;EAAA,SACjB,MAAA;EAAA,kBACS,IAAA;EAAA,SACT,GAAA;EDmBhB;AAAA;AA6BD;;;;;ECvCC,WAAA,CAAY,OAAA,UAAiB,OAAA,GAAU,mBAAA;AAAA;;;;;AD5BxC;;;UEAiB,qBAAA,SAA8B,YAAA;;;;;;EAM9C,OAAA,GAAU,SAAA;;;;;;;;EAQV,SAAA;;EAEA,iBAAA;;;;AFsBA;EEjBA,UAAA;AAAA;;;;;;;;;;;;;;;;;;;;cAsBY,cAAA,SAAuB,cAAA;;WAEnB,OAAA,EAAS,SAAA;EAAA,kBACA,IAAA;;;;WAIT,SAAA;EAAA,SACA,iBAAA;;WAEA,UAAA;;ADrDjB;;;;;EC6DC,WAAA,CAAY,OAAA,UAAiB,OAAA,EAAS,qBAAA;AAAA;;;AF7DvC;;;;;;;;AAAA,UGMiB,eAAA;;WAEP,MAAA;;WAEA,OAAA;;WAEA,UAAA;;WAEA,iBAAA,EAAmB,aAAA;;;;;;;AHwB5B;AA6BD;;WG3CU,uBAAA,EAAyB,aAAA;;WAEzB,UAAA,GAAa,OAAA;;WAEb,OAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;cAwBG,yBAAA,EAA2B,aAAA;;;;AFpDxC;;;;;;;;AAIC;AAYD;cE+Da,gBAAA;;;;;;;;;;;;AFnD2B;;;;AC5BxC;;;;;;cCsGa,oBAAA;AAhGb;AAAA,KA+IY,UAAA"}
@@ -1,5 +1,5 @@
1
1
  import { d as OpenCloudError, i as OpenCloudClientOptions, l as Result, n as HttpRequest, r as HttpResponse, s as RequestOptions, u as SleepFunc } from "./types-DXai6-hU.mjs";
2
- import { n as RetryResolvable, t as MethodKind } from "./retry-DGY51INM.mjs";
2
+ import { i as RetryResolvable, n as MethodKind } from "./retry-DANH6mM9.mjs";
3
3
 
4
4
  //#region src/domains/cloud-v2/memory-store-queues/types.d.ts
5
5
  /**
package/dist/storage.mjs CHANGED
@@ -1,6 +1,6 @@
1
- import { r as ApiError } from "./rate-limit-B20REZEY.mjs";
2
- import { n as IDEMPOTENT_METHOD_DEFAULTS, t as CREATE_METHOD_DEFAULTS } from "./retry-PmpgEwFN.mjs";
3
- import { a as isRecord, i as toJsonDetails, n as okRequest, o as isDateTimeString, r as parseEmptyResponse, t as ResourceClient } from "./resource-client-rQ9bBn4L.mjs";
1
+ import { r as ApiError } from "./rate-limit-D1MQZNAE.mjs";
2
+ import { r as IDEMPOTENT_METHOD_DEFAULTS, t as CREATE_METHOD_DEFAULTS } from "./retry-D1HKlycK.mjs";
3
+ import { a as isRecord, i as toJsonDetails, n as okRequest, o as isDateTimeString, r as parseEmptyResponse, t as ResourceClient } from "./resource-client-6KaHBVI7.mjs";
4
4
  //#region src/domains/cloud-v2/memory-store-queues/builders.ts
5
5
  /**
6
6
  * Builds a `POST` request for the Open Cloud
package/dist/testing.mjs CHANGED
@@ -1,4 +1,4 @@
1
- import { n as NetworkError, r as ApiError, t as RateLimitError } from "./rate-limit-B20REZEY.mjs";
1
+ import { n as NetworkError, r as ApiError, t as RateLimitError } from "./rate-limit-D1MQZNAE.mjs";
2
2
  import { n as RBXL_SIGNATURE, t as RBXLX_SIGNATURE } from "./signatures-JF-7Psce.mjs";
3
3
  //#region tests/helpers/badges.ts
4
4
  /**
@@ -1,8 +1,8 @@
1
- import { r as ApiError } from "./rate-limit-B20REZEY.mjs";
2
- import { n as IDEMPOTENT_METHOD_DEFAULTS, t as CREATE_METHOD_DEFAULTS } from "./retry-PmpgEwFN.mjs";
3
- import { t as ValidationError } from "./validation-BXhEM3OP.mjs";
1
+ import { r as ApiError } from "./rate-limit-D1MQZNAE.mjs";
2
+ import { r as IDEMPOTENT_METHOD_DEFAULTS, t as CREATE_METHOD_DEFAULTS } from "./retry-D1HKlycK.mjs";
3
+ import { t as ValidationError } from "./validation-BJ0-hNLs.mjs";
4
4
  import { t as toBlob } from "./to-blob-RPqMBuft.mjs";
5
- import { a as isRecord, i as toJsonDetails, n as okRequest, o as isDateTimeString, r as parseEmptyResponse, t as ResourceClient } from "./resource-client-rQ9bBn4L.mjs";
5
+ import { a as isRecord, i as toJsonDetails, n as okRequest, o as isDateTimeString, r as parseEmptyResponse, t as ResourceClient } from "./resource-client-6KaHBVI7.mjs";
6
6
  //#region src/domains/cloud-v2/universes/builders.ts
7
7
  /**
8
8
  * Dodges `unicorn/no-null` while still emitting a literal `null` onto
@@ -1,4 +1,4 @@
1
- import { i as OpenCloudError } from "./rate-limit-B20REZEY.mjs";
1
+ import { i as OpenCloudError } from "./rate-limit-D1MQZNAE.mjs";
2
2
  //#region src/errors/validation.ts
3
3
  /**
4
4
  * Thrown locally when caller-supplied input is rejected before any HTTP
@@ -37,4 +37,4 @@ var ValidationError = class extends OpenCloudError {
37
37
  //#endregion
38
38
  export { ValidationError as t };
39
39
 
40
- //# sourceMappingURL=validation-BXhEM3OP.mjs.map
40
+ //# sourceMappingURL=validation-BJ0-hNLs.mjs.map