@bedrock-rbx/ocale 0.3.4 → 0.5.0

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 (95) hide show
  1. package/README.md +10 -5
  2. package/dist/assets.d.mts +64 -0
  3. package/dist/assets.d.mts.map +1 -0
  4. package/dist/assets.mjs +301 -0
  5. package/dist/assets.mjs.map +1 -0
  6. package/dist/badge-insufficient-funds-BLFvQZt1.mjs +91 -0
  7. package/dist/badge-insufficient-funds-BLFvQZt1.mjs.map +1 -0
  8. package/dist/badges.d.mts +359 -196
  9. package/dist/badges.d.mts.map +1 -1
  10. package/dist/badges.mjs +493 -59
  11. package/dist/badges.mjs.map +1 -1
  12. package/dist/capacity-admission-Ce2V9QNb.d.mts +347 -0
  13. package/dist/capacity-admission-Ce2V9QNb.d.mts.map +1 -0
  14. package/dist/{data.generated-B2ceLfSn.d.mts → data.generated-B4Fztv_7.d.mts} +23 -25
  15. package/dist/data.generated-B4Fztv_7.d.mts.map +1 -0
  16. package/dist/developer-products.d.mts +207 -194
  17. package/dist/developer-products.d.mts.map +1 -1
  18. package/dist/developer-products.mjs +125 -39
  19. package/dist/developer-products.mjs.map +1 -1
  20. package/dist/game-passes.d.mts +206 -211
  21. package/dist/game-passes.d.mts.map +1 -1
  22. package/dist/game-passes.mjs +35 -36
  23. package/dist/game-passes.mjs.map +1 -1
  24. package/dist/index.d.mts +947 -366
  25. package/dist/index.d.mts.map +1 -1
  26. package/dist/index.mjs +324 -12
  27. package/dist/index.mjs.map +1 -1
  28. package/dist/is-date-time-string-C91G44SI.mjs +19 -0
  29. package/dist/is-date-time-string-C91G44SI.mjs.map +1 -0
  30. package/dist/locales.d.mts +28 -2
  31. package/dist/locales.d.mts.map +1 -0
  32. package/dist/locales.mjs +24 -3
  33. package/dist/locales.mjs.map +1 -1
  34. package/dist/luau-execution.d.mts +154 -157
  35. package/dist/luau-execution.d.mts.map +1 -1
  36. package/dist/luau-execution.mjs +15 -16
  37. package/dist/luau-execution.mjs.map +1 -1
  38. package/dist/{network-error-DR9FX5hb.mjs → network-error-P4An7nUB.mjs} +48 -14
  39. package/dist/network-error-P4An7nUB.mjs.map +1 -0
  40. package/dist/places.d.mts +258 -186
  41. package/dist/places.d.mts.map +1 -1
  42. package/dist/places.mjs +187 -35
  43. package/dist/places.mjs.map +1 -1
  44. package/dist/{poll-timeout-3PXLsabj.mjs → poll-timeout-BCxgN97O.mjs} +4 -6
  45. package/dist/{poll-timeout-3PXLsabj.mjs.map → poll-timeout-BCxgN97O.mjs.map} +1 -1
  46. package/dist/{polling-helpers-CoVhsC33.mjs → polling-helpers-BtEYR5dN.mjs} +260 -105
  47. package/dist/polling-helpers-BtEYR5dN.mjs.map +1 -0
  48. package/dist/{price-information-B0tkOoAX.mjs → price-information--d6GZAcp.mjs} +3 -4
  49. package/dist/{price-information-B0tkOoAX.mjs.map → price-information--d6GZAcp.mjs.map} +1 -1
  50. package/dist/resource-client-CF8SPsV8.d.mts +162 -0
  51. package/dist/resource-client-CF8SPsV8.d.mts.map +1 -0
  52. package/dist/{resource-client-rqTMkBeR.mjs → resource-client-Cm_bPcCs.mjs} +589 -197
  53. package/dist/resource-client-Cm_bPcCs.mjs.map +1 -0
  54. package/dist/retry-DYxm_eBU.d.mts +225 -0
  55. package/dist/retry-DYxm_eBU.d.mts.map +1 -0
  56. package/dist/{retry-BlX4tUnT.mjs → retry-Dv5TsY9O.mjs} +312 -54
  57. package/dist/retry-Dv5TsY9O.mjs.map +1 -0
  58. package/dist/{signatures-JF-7Psce.mjs → signatures-CtJ7jfVN.mjs} +2 -3
  59. package/dist/{signatures-JF-7Psce.mjs.map → signatures-CtJ7jfVN.mjs.map} +1 -1
  60. package/dist/storage.d.mts +333 -344
  61. package/dist/storage.d.mts.map +1 -1
  62. package/dist/storage.mjs +39 -40
  63. package/dist/storage.mjs.map +1 -1
  64. package/dist/testing.d.mts +369 -434
  65. package/dist/testing.d.mts.map +1 -1
  66. package/dist/testing.mjs +18 -33
  67. package/dist/testing.mjs.map +1 -1
  68. package/dist/{to-blob-RPqMBuft.mjs → to-blob-Bqu7bmlE.mjs} +2 -3
  69. package/dist/{to-blob-RPqMBuft.mjs.map → to-blob-Bqu7bmlE.mjs.map} +1 -1
  70. package/dist/types-Z4abDJfK.d.mts +501 -0
  71. package/dist/types-Z4abDJfK.d.mts.map +1 -0
  72. package/dist/universes.d.mts +619 -436
  73. package/dist/universes.d.mts.map +1 -1
  74. package/dist/universes.mjs +432 -79
  75. package/dist/universes.mjs.map +1 -1
  76. package/dist/{validation-B_Zs1So2.mjs → validation-kaTLLAD1.mjs} +3 -4
  77. package/dist/{validation-B_Zs1So2.mjs.map → validation-kaTLLAD1.mjs.map} +1 -1
  78. package/dist/wire-DDG87I-d.d.mts +39 -0
  79. package/dist/wire-DDG87I-d.d.mts.map +1 -0
  80. package/package.json +15 -14
  81. package/dist/capacity-admission-IDO3fcUC.d.mts +0 -369
  82. package/dist/capacity-admission-IDO3fcUC.d.mts.map +0 -1
  83. package/dist/data.generated-B2ceLfSn.d.mts.map +0 -1
  84. package/dist/network-error-DR9FX5hb.mjs.map +0 -1
  85. package/dist/polling-helpers-CoVhsC33.mjs.map +0 -1
  86. package/dist/resource-client-B6NeFXUv.d.mts +0 -164
  87. package/dist/resource-client-B6NeFXUv.d.mts.map +0 -1
  88. package/dist/resource-client-rqTMkBeR.mjs.map +0 -1
  89. package/dist/retry-BlX4tUnT.mjs.map +0 -1
  90. package/dist/retry-war_-9tb.d.mts +0 -373
  91. package/dist/retry-war_-9tb.d.mts.map +0 -1
  92. package/dist/types-CvYh4SPC.d.mts +0 -386
  93. package/dist/types-CvYh4SPC.d.mts.map +0 -1
  94. package/dist/wire-D3K-a-UP.d.mts +0 -37
  95. package/dist/wire-D3K-a-UP.d.mts.map +0 -1
@@ -1,5 +1,5 @@
1
- import { a as ApiError, i as markServerRetryGuidance, n as RateLimitError, r as hasServerRetryGuidance, s as OpenCloudError, t as NetworkError } from "./network-error-DR9FX5hb.mjs";
2
- //#region src/internal/utils/try-catch.ts
1
+ import { a as ApiError, i as markServerRetryGuidance, n as RateLimitError, r as hasServerRetryGuidance, s as OpenCloudError, t as NetworkError } from "./network-error-P4An7nUB.mjs";
2
+ // src/internal/utils/try-catch.ts
3
3
  /**
4
4
  * Wraps a promise into a {@link Result}, catching rejections.
5
5
  *
@@ -20,18 +20,17 @@ async function tryCatchAsync(promise) {
20
20
  };
21
21
  }
22
22
  }
23
- //#endregion
24
- //#region src/internal/http/diagnostics.ts
23
+ // src/internal/http/diagnostics.ts
25
24
  const MAX_DETAIL_LENGTH = 500;
26
25
  const CONTENT_TYPE_HEADER$1 = "content-type";
27
- const DIAGNOSTIC_HEADER_ALLOWLIST = new Set([
26
+ const DIAGNOSTIC_HEADER_ALLOWLIST = /* @__PURE__ */ new Set([
28
27
  "cf-ray",
29
28
  "server",
30
29
  "via",
31
30
  "x-request-id"
32
31
  ]);
33
32
  const DIAGNOSTIC_HEADER_PREFIX = "x-roblox-";
34
- const RATE_LIMIT_HEADER_ALLOWLIST = new Set([
33
+ const RATE_LIMIT_HEADER_ALLOWLIST = /* @__PURE__ */ new Set([
35
34
  "date",
36
35
  "retry-after",
37
36
  "x-envoy-ratelimited",
@@ -128,7 +127,8 @@ function bodyDetail(text, parsed) {
128
127
  * @returns An ApiError carrying the diagnostic context.
129
128
  */
130
129
  function parseFailureError({ cause, context, response, text }) {
131
- return new ApiError(`Failed to parse response body (content-type: ${response.headers.get(CONTENT_TYPE_HEADER$1) ?? "unknown"}, ${String(text.length)} chars read)`, {
130
+ const contentType = response.headers.get(CONTENT_TYPE_HEADER$1) ?? "unknown";
131
+ return new ApiError(`Failed to parse response body (content-type: ${contentType}, ${String(text.length)} chars read)`, {
132
132
  cause,
133
133
  details: text.slice(0, MAX_DETAIL_LENGTH),
134
134
  elapsedMs: context.elapsedMs,
@@ -158,8 +158,7 @@ function pickHeaders(headers, additionalAllowlist) {
158
158
  for (const [name, value] of Object.entries(headers)) if (DIAGNOSTIC_HEADER_ALLOWLIST.has(name) || name.startsWith(DIAGNOSTIC_HEADER_PREFIX) || additionalAllowlist?.has(name) === true) picked[name] = value;
159
159
  return picked;
160
160
  }
161
- //#endregion
162
- //#region src/internal/http/error-body.ts
161
+ // src/internal/http/error-body.ts
163
162
  const CANONICAL_STATUS = /^[A-Z][A-Z0-9_]*$/;
164
163
  /**
165
164
  * Permissively extracts a machine-readable error code from a response body.
@@ -251,8 +250,7 @@ function extractLegacyMessage(body) {
251
250
  const message = Reflect.get(first, "message");
252
251
  return typeof message === "string" ? message : void 0;
253
252
  }
254
- //#endregion
255
- //#region src/internal/http/http1-dispatcher.ts
253
+ // src/internal/http/http1-dispatcher.ts
256
254
  /**
257
255
  * Well-known globals under which undici publishes its global dispatcher,
258
256
  * newest first. The suffix is undici's own contract version: it moved from
@@ -329,8 +327,20 @@ function constructHttp1(agent) {
329
327
  return;
330
328
  }
331
329
  }
332
- //#endregion
333
- //#region src/internal/http/rate-limit-sample.ts
330
+ // src/internal/utils/is-record.ts
331
+ /**
332
+ * Narrows `value` to a plain JSON-style record. Excludes arrays, class
333
+ * instances, primitives, and `null`/`undefined`. Used by resource
334
+ * parsers to gate property access on wire bodies whose shape isn't
335
+ * known at compile time.
336
+ *
337
+ * @param value - The unknown value to narrow.
338
+ * @returns `true` when `value` is a plain `[object Object]`.
339
+ */
340
+ function isRecord(value) {
341
+ return Object.prototype.toString.call(value) === "[object Object]";
342
+ }
343
+ // src/internal/http/rate-limit-sample.ts
334
344
  const LIMIT_POLICY_PATTERN = /^(\d+);w=(\d+)$/;
335
345
  const NON_NEGATIVE_INTEGER_PATTERN = /^\d+$/;
336
346
  /**
@@ -418,8 +428,7 @@ function parseRateLimitWindow(headerValue) {
418
428
  return isPositiveSafeInteger(capacity) && isPositiveSafeInteger(windowSeconds);
419
429
  }).toSorted((a, b) => rate(a) - rate(b) || a.windowSeconds - b.windowSeconds)[0];
420
430
  }
421
- //#endregion
422
- //#region src/internal/http/retry-guidance.ts
431
+ // src/internal/http/retry-guidance.ts
423
432
  const ABBREVIATED_WEEKDAYS = [
424
433
  "Sun",
425
434
  "Mon",
@@ -498,6 +507,29 @@ function resolveRetryGuidance({ headers, nowMs, remaining }) {
498
507
  const quotaReset = parseQuotaResetSeconds(headers["x-ratelimit-reset"]);
499
508
  return quotaReset === void 0 ? retryAfter : Math.max(retryAfter ?? 0, quotaReset);
500
509
  }
510
+ /**
511
+ * Points a 429 at `x-ratelimit-reset`, for endpoints whose `retry-after` is
512
+ * shorter than their fixed window, which reopens only at the reset. Any other
513
+ * error, or a 429 without a reset, passes through unchanged.
514
+ *
515
+ * @param error - The transport error of one attempt.
516
+ * @returns The error with its wait set to the reported reset.
517
+ */
518
+ function waitForQuotaReset(error) {
519
+ if (!(error instanceof RateLimitError)) return error;
520
+ const resetSeconds = parseQuotaResetSeconds(error.responseHeaders?.["x-ratelimit-reset"]);
521
+ if (resetSeconds === void 0) return error;
522
+ return new RateLimitError(error.message, {
523
+ cause: error.cause,
524
+ code: error.code,
525
+ details: error.details,
526
+ remaining: error.remaining,
527
+ responseHeaders: error.responseHeaders,
528
+ retryAfterSeconds: resetSeconds,
529
+ source: error.source,
530
+ statusCode: error.statusCode
531
+ });
532
+ }
501
533
  function httpDateTimestamp(parts) {
502
534
  if (parts.minute > 59 || parts.second > 59) return;
503
535
  const date = /* @__PURE__ */ new Date(0);
@@ -548,8 +580,23 @@ function parseObsoleteDate(value, nowMs) {
548
580
  function parseHttpDate(value, nowMs) {
549
581
  return parseFixedDate(value) ?? parseObsoleteDate(value, nowMs) ?? parseAnsiDate(value);
550
582
  }
551
- //#endregion
552
- //#region src/internal/http/rate-limit-response.ts
583
+ // src/internal/http/rate-limit-response.ts
584
+ /**
585
+ * Classifies which layer refused a 429 from its headers and parsed body.
586
+ * `"service"` needs a non-blank `x-roblox-system-reason` header. `"edge"`
587
+ * needs no such header and a body of only `{ code: 0, message: "" }` entries
588
+ * under `errors`. Anything else, including a body `code` alone, is
589
+ * `"unknown"`.
590
+ *
591
+ * @param headers - The response headers (lowercased keys).
592
+ * @param details - The parsed or safely truncated response body.
593
+ * @returns The refusing layer, or `"unknown"` without positive evidence.
594
+ */
595
+ function classifyRateLimitSource(headers, details) {
596
+ const reason = headers["x-roblox-system-reason"];
597
+ if (isNonBlankString(reason)) return "service";
598
+ return isEdgeBody(details) ? "edge" : "unknown";
599
+ }
553
600
  /**
554
601
  * Builds a public rate-limit error from a 429 response and its already-read
555
602
  * body, retaining safe raw evidence alongside the existing parsed guidance.
@@ -573,17 +620,25 @@ function createRateLimitError(response, details) {
573
620
  remaining,
574
621
  responseHeaders: pickRateLimitHeaders(headers),
575
622
  retryAfterSeconds: guidedRetrySeconds ?? 0,
623
+ source: classifyRateLimitSource(headers, details),
576
624
  statusCode: response.status
577
625
  });
578
626
  return guidedRetrySeconds === void 0 ? error : markServerRetryGuidance(error);
579
627
  }
628
+ function isEdgeBody(body) {
629
+ if (!isRecord(body)) return false;
630
+ const { errors } = body;
631
+ return Array.isArray(errors) && errors.length > 0 && errors.every((entry) => isRecord(entry) && entry["code"] === 0 && entry["message"] === "");
632
+ }
633
+ function isNonBlankString(value) {
634
+ return typeof value === "string" && value.trim() !== "";
635
+ }
580
636
  function extractRateLimitErrorCode(body) {
581
- if (body === null || typeof body !== "object") return;
582
- const code = Reflect.get(body, "code");
583
- return typeof code === "string" && code.trim() ? code : void 0;
637
+ if (!isRecord(body)) return;
638
+ const { code } = body;
639
+ return isNonBlankString(code) ? code : void 0;
584
640
  }
585
- //#endregion
586
- //#region src/errors/request-aborted.ts
641
+ // src/errors/request-aborted.ts
587
642
  /**
588
643
  * Returned when a caller's `AbortSignal` cancels an Open Cloud request.
589
644
  * The reason is preserved so intentional cancellation can be distinguished
@@ -618,8 +673,7 @@ var RequestAbortedError = class extends OpenCloudError {
618
673
  this.reason = options.reason;
619
674
  }
620
675
  };
621
- //#endregion
622
- //#region src/internal/utils/abort.ts
676
+ // src/internal/utils/abort.ts
623
677
  /**
624
678
  * Sentinel returned when an asynchronous operation loses a race with a signal.
625
679
  */
@@ -658,8 +712,7 @@ async function raceWithAbortAsync(operation, signal) {
658
712
  function requestAbortedError(signal) {
659
713
  return new RequestAbortedError("Request was aborted", { reason: signal?.reason });
660
714
  }
661
- //#endregion
662
- //#region src/internal/http/request-signal.ts
715
+ // src/internal/http/request-signal.ts
663
716
  /**
664
717
  * Composes caller cancellation with Ocale's transport-attempt timeout. The
665
718
  * winning signal's reason is retained by `AbortSignal.any`, allowing failure
@@ -688,8 +741,7 @@ function requestFailure({ cause, config, effectiveSignal, target }) {
688
741
  url: target.url
689
742
  });
690
743
  }
691
- //#endregion
692
- //#region src/internal/http/upload-request.ts
744
+ // src/internal/http/upload-request.ts
693
745
  /**
694
746
  * Reports whether a request is an upload: its body is `FormData`
695
747
  * (multipart) or `Uint8Array` (raw binary). Upload latency is
@@ -703,10 +755,11 @@ function requestFailure({ cause, config, effectiveSignal, target }) {
703
755
  function isUploadRequest(request) {
704
756
  return request.body instanceof FormData || request.body instanceof Uint8Array;
705
757
  }
706
- //#endregion
707
- //#region src/internal/http/fetch-client.ts
758
+ // src/internal/http/fetch-client.ts
708
759
  const CONTENT_TYPE_HEADER = "content-type";
709
760
  const CONNECTION_HEADER = "connection";
761
+ /** Headers the transport owns for the credential; a request cannot set them. */
762
+ const CREDENTIAL_HEADERS = /* @__PURE__ */ new Set(["authorization", "x-api-key"]);
710
763
  /**
711
764
  * Joins the base URL from config with the relative path from the request.
712
765
  *
@@ -721,11 +774,11 @@ function buildUrl(request, config) {
721
774
  * Constructs the `RequestInit` options for a `fetch` call.
722
775
  *
723
776
  * @param request - The HTTP request to build options for.
724
- * @param config - The request config containing API key and timeout.
777
+ * @param config - The request config containing the credential and timeout.
725
778
  * @returns A `RequestInit` object ready for `fetch`.
726
779
  */
727
780
  function buildFetchOptions(request, config) {
728
- const headers = new Headers({ "x-api-key": config.apiKey });
781
+ const headers = new Headers(credentialHeader(config));
729
782
  const options = {
730
783
  headers,
731
784
  method: request.method
@@ -764,10 +817,26 @@ function createFetchHttpClient(fetchFunc = fetch, { createDispatcher = createHtt
764
817
  } };
765
818
  }
766
819
  /**
820
+ * Picks the credential header for a request: `x-api-key` for an API key,
821
+ * `authorization: Bearer` for an OAuth access token, and none for an
822
+ * unauthenticated request.
823
+ *
824
+ * @param config - The request config holding the credential.
825
+ * @returns The credential header to send, if any.
826
+ */
827
+ function credentialHeader({ credential }) {
828
+ switch (credential.kind) {
829
+ case "apiKey": return { "x-api-key": credential.apiKey };
830
+ case "none": return {};
831
+ case "oauth": return { authorization: `Bearer ${credential.accessToken}` };
832
+ }
833
+ }
834
+ /**
767
835
  * Merges the request's own headers onto the transport's, then applies the
768
- * transport-owned connection directive. `x-api-key` is skipped so a request
769
- * cannot override the configured credential, and the upload directive is set
770
- * last so a request header cannot silently re-enable pooling for an upload.
836
+ * transport-owned connection directive. `x-api-key` and `authorization` are
837
+ * skipped so a request cannot override the configured credential, and the
838
+ * upload directive is set last so a request header cannot silently re-enable
839
+ * pooling for an upload.
771
840
  *
772
841
  * @param headers - The headers being built for the fetch call. Mutated.
773
842
  * @param request - The request whose headers and body shape drive the merge.
@@ -775,7 +844,7 @@ function createFetchHttpClient(fetchFunc = fetch, { createDispatcher = createHtt
775
844
  function applyRequestHeaders(headers, request) {
776
845
  const requestHeaders = request.headers ?? {};
777
846
  for (const [name, value] of Object.entries(requestHeaders)) {
778
- if (name.toLowerCase() === "x-api-key") continue;
847
+ if (CREDENTIAL_HEADERS.has(name.toLowerCase())) continue;
779
848
  headers.set(name, value);
780
849
  }
781
850
  if (isUploadRequest(request)) headers.set(CONNECTION_HEADER, "close");
@@ -828,9 +897,10 @@ function createApiError(args) {
828
897
  });
829
898
  const body = bodyDetail(rawText, args.parsed);
830
899
  const code = extractErrorCode(body);
900
+ const message = extractErrorMessage(body);
831
901
  return new ApiError(formatApiErrorMessage({
832
902
  code,
833
- message: extractErrorMessage(body),
903
+ message,
834
904
  status
835
905
  }), {
836
906
  ...requestContext,
@@ -979,8 +1049,109 @@ function createUploadDispatcherCache(createDispatcher) {
979
1049
  return cached;
980
1050
  };
981
1051
  }
982
- //#endregion
983
- //#region src/errors/permission-error.ts
1052
+ // src/errors/credential-error.ts
1053
+ /**
1054
+ * Returned when an OAuth credential's `getAccessToken` throws or rejects.
1055
+ * The provider's error is the `cause`, passed through unchanged. The client
1056
+ * sends no request for that attempt and spends no retry.
1057
+ *
1058
+ * @since 0.4.0
1059
+ *
1060
+ * @example
1061
+ *
1062
+ * ```ts
1063
+ * import { CredentialError } from "@bedrock-rbx/ocale";
1064
+ *
1065
+ * const providerError = new Error("refresh token revoked");
1066
+ * const error = new CredentialError("Credential provider failed", {
1067
+ * cause: providerError,
1068
+ * });
1069
+ *
1070
+ * expect(error).toBeInstanceOf(CredentialError);
1071
+ * expect(error.cause).toBe(providerError);
1072
+ * ```
1073
+ */
1074
+ var CredentialError = class extends OpenCloudError {
1075
+ name = "CredentialError";
1076
+ };
1077
+ // src/errors/credential-not-supported.ts
1078
+ /**
1079
+ * Returned when an OAuth credential calls an Operation that Roblox accepts
1080
+ * only with an API key (place publish and save, Luau execution and memory
1081
+ * stores). The client returns it before it asks the provider for a token, and
1082
+ * it sends no request.
1083
+ *
1084
+ * @since 0.4.0
1085
+ *
1086
+ * @example
1087
+ *
1088
+ * ```ts
1089
+ * import { CredentialNotSupportedError } from "@bedrock-rbx/ocale";
1090
+ *
1091
+ * const error = new CredentialNotSupportedError("Operation needs an API key", {
1092
+ * operationKey: "places.publishVersion",
1093
+ * });
1094
+ *
1095
+ * expect(error).toBeInstanceOf(CredentialNotSupportedError);
1096
+ * expect(error.operationKey).toBe("places.publishVersion");
1097
+ * ```
1098
+ */
1099
+ var CredentialNotSupportedError = class extends OpenCloudError {
1100
+ name = "CredentialNotSupportedError";
1101
+ operationKey;
1102
+ /**
1103
+ * Creates a new CredentialNotSupportedError.
1104
+ *
1105
+ * @param message - Human-readable description of the failure.
1106
+ * @param options - Error options including the Operation's key.
1107
+ */
1108
+ constructor(message, options) {
1109
+ super(message, options);
1110
+ this.operationKey = options.operationKey;
1111
+ }
1112
+ };
1113
+ // src/errors/credential-rejected.ts
1114
+ /**
1115
+ * Returned when Roblox refuses an OAuth Credential's token: a non-gateway
1116
+ * 401, or a non-gateway 502 whose body message is "Scope authorization
1117
+ * failed.". The grant is lost, so the client does not retry. Carries the
1118
+ * Credential `identity` (never the token) so the caller can ask that user to
1119
+ * consent again. The upstream `ApiError` is the `cause`.
1120
+ *
1121
+ * @since 0.4.0
1122
+ *
1123
+ * @example
1124
+ *
1125
+ * ```ts
1126
+ * import { CredentialRejectedError } from "@bedrock-rbx/ocale";
1127
+ *
1128
+ * const error = new CredentialRejectedError("HTTP 401: Invalid Token.", {
1129
+ * identity: "user-123",
1130
+ * statusCode: 401,
1131
+ * });
1132
+ *
1133
+ * expect(error.identity).toBe("user-123");
1134
+ * expect(error.statusCode).toBe(401);
1135
+ * ```
1136
+ */
1137
+ var CredentialRejectedError = class extends OpenCloudError {
1138
+ identity;
1139
+ name = "CredentialRejectedError";
1140
+ statusCode;
1141
+ /**
1142
+ * Creates a new CredentialRejectedError.
1143
+ *
1144
+ * @param message - Human-readable error description.
1145
+ * @param options - Error options including the Credential identity and
1146
+ * the HTTP status of the refusal.
1147
+ */
1148
+ constructor(message, options) {
1149
+ super(message, options);
1150
+ this.identity = options.identity;
1151
+ this.statusCode = options.statusCode;
1152
+ }
1153
+ };
1154
+ // src/errors/permission-error.ts
984
1155
  /**
985
1156
  * Thrown when the Roblox Open Cloud API returns a 401 or 403 for an operation
986
1157
  * whose required scopes are known. Subclass of {@link ApiError} carrying the
@@ -1027,8 +1198,7 @@ var PermissionError = class extends ApiError {
1027
1198
  this.requiredScopes = options.requiredScopes;
1028
1199
  }
1029
1200
  };
1030
- //#endregion
1031
- //#region src/errors/rate-limit-wait-refused.ts
1201
+ // src/errors/rate-limit-wait-refused.ts
1032
1202
  /**
1033
1203
  * Returned at once when a 429 asks for a wait longer than the 60 seconds the
1034
1204
  * SDK waits out on its own. The server's requested wait is kept exactly as
@@ -1081,8 +1251,7 @@ var RateLimitWaitRefusedError = class extends OpenCloudError {
1081
1251
  this.retryAfterSeconds = cause.retryAfterSeconds;
1082
1252
  }
1083
1253
  };
1084
- //#endregion
1085
- //#region src/errors/request-deadline-exceeded.ts
1254
+ // src/errors/request-deadline-exceeded.ts
1086
1255
  /**
1087
1256
  * Returned when a logical request cannot complete by its absolute deadline.
1088
1257
  * Optional wait details identify an SDK-managed admission wait that was
@@ -1130,8 +1299,7 @@ var RequestDeadlineExceededError = class extends OpenCloudError {
1130
1299
  this.waitReason = options.waitReason;
1131
1300
  }
1132
1301
  };
1133
- //#endregion
1134
- //#region src/errors/retry-delay-exceeded.ts
1302
+ // src/errors/retry-delay-exceeded.ts
1135
1303
  /**
1136
1304
  * Returned when the SDK refuses a retry delay that cannot complete before the
1137
1305
  * request deadline. This is distinct from cancellation so consumers can
@@ -1176,8 +1344,89 @@ var RetryDelayExceededError = class extends RequestDeadlineExceededError {
1176
1344
  this.retryAfterSeconds = options.retryAfterMs / 1e3;
1177
1345
  }
1178
1346
  };
1179
- //#endregion
1180
- //#region src/internal/utils/find-error-code.ts
1347
+ // src/errors/unexpected-response.ts
1348
+ const NEW_ISSUE_URL = "https://github.com/christopher-buss/bedrock/issues/new";
1349
+ /**
1350
+ * Returned when Open Cloud accepts a request and answers, but the response
1351
+ * body has a shape that ocale's wire model rejects. The API did not refuse the
1352
+ * request, so this is not an `ApiError`: the fault is more likely a stale wire
1353
+ * model or a parser bug in ocale than a problem with the caller's input. The
1354
+ * raw body is kept on `details`, with the request context, so the mismatch can
1355
+ * be reported. `reportUrl` opens an ocale bug report prefilled with the
1356
+ * message, status, and failing call. It leaves out the body, which can hold
1357
+ * private data.
1358
+ *
1359
+ * @since 0.4.0
1360
+ *
1361
+ * @example
1362
+ *
1363
+ * ```ts
1364
+ * import { ApiError, UnexpectedResponseError } from "@bedrock-rbx/ocale";
1365
+ *
1366
+ * const error = new UnexpectedResponseError("Malformed badge response", {
1367
+ * details: { id: "not-a-number" },
1368
+ * method: "GET",
1369
+ * statusCode: 200,
1370
+ * url: "https://apis.roblox.com/legacy-badges/v1/badges/1",
1371
+ * });
1372
+ *
1373
+ * // A shape mismatch is not an API rejection.
1374
+ * expect(error).not.toBeInstanceOf(ApiError);
1375
+ * expect(error.details).toStrictEqual({ id: "not-a-number" });
1376
+ * ```
1377
+ */
1378
+ var UnexpectedResponseError = class extends OpenCloudError {
1379
+ details;
1380
+ method;
1381
+ name = "UnexpectedResponseError";
1382
+ /** Link to a new ocale bug report, prefilled with this failure. */
1383
+ reportUrl;
1384
+ responseHeaders;
1385
+ statusCode;
1386
+ url;
1387
+ /**
1388
+ * Creates a new UnexpectedResponseError.
1389
+ *
1390
+ * @param message - Human-readable description naming the response that
1391
+ * did not match.
1392
+ * @param options - The status code, the raw body as `details`, and the
1393
+ * request context when known.
1394
+ */
1395
+ constructor(message, options) {
1396
+ const reportUrl = buildReportUrl(message, options);
1397
+ super(options.reportHint === true ? `${message}\n${reportLine(reportUrl)}` : message, options);
1398
+ this.details = options.details;
1399
+ this.method = options.method;
1400
+ this.responseHeaders = options.responseHeaders;
1401
+ this.statusCode = options.statusCode;
1402
+ this.url = options.url;
1403
+ this.reportUrl = reportUrl;
1404
+ }
1405
+ };
1406
+ function reportLine(reportUrl) {
1407
+ return `This is likely a bug in @bedrock-rbx/ocale. Report it at ${reportUrl}`;
1408
+ }
1409
+ function reportBody(message, { method, responseHeaders, statusCode, url }) {
1410
+ const request = method !== void 0 && url !== void 0 ? [`- Request: ${method} ${url}`] : [];
1411
+ const headers = Object.entries(responseHeaders ?? {}).map(([name, value]) => `- ${name}: ${value}`);
1412
+ return [
1413
+ "`UnexpectedResponseError` from `@bedrock-rbx/ocale`.",
1414
+ "",
1415
+ `- Message: ${message}`,
1416
+ `- Status: ${String(statusCode)}`,
1417
+ ...request,
1418
+ ...headers
1419
+ ].join("\n");
1420
+ }
1421
+ function buildReportUrl(message, options) {
1422
+ const query = new URLSearchParams({
1423
+ body: reportBody(message, options),
1424
+ template: "bug-report.md",
1425
+ title: `[Bug]: ${message}`
1426
+ });
1427
+ return `${NEW_ISSUE_URL}?${query.toString()}`;
1428
+ }
1429
+ // src/internal/utils/find-error-code.ts
1181
1430
  /**
1182
1431
  * Maximum cause-chain depth walked by {@link findErrorCode}. Caps pathological
1183
1432
  * self-referential or deeply nested chains; transport failures surface as
@@ -1258,8 +1507,7 @@ function isTimeoutAbort(error) {
1258
1507
  }
1259
1508
  return false;
1260
1509
  }
1261
- //#endregion
1262
- //#region src/internal/http/retry.ts
1510
+ // src/internal/http/retry.ts
1263
1511
  /**
1264
1512
  * Transient transport error codes that are safe to retry for idempotent
1265
1513
  * operations. Connection resets, timeouts, and DNS hiccups are recoverable on
@@ -1442,6 +1690,17 @@ function hasGuidedWait(error) {
1442
1690
  return error instanceof RateLimitError && error.retryAfterSeconds > 0;
1443
1691
  }
1444
1692
  /**
1693
+ * Whether a failure is a rate limit whose guided wait is longer than the
1694
+ * {@link MAX_GUIDED_WAIT_SECONDS} the SDK waits out on its own, so the SDK
1695
+ * refuses it.
1696
+ *
1697
+ * @param error - The error returned by the failing request.
1698
+ * @returns `true` for a rate limit naming a wait the SDK refuses.
1699
+ */
1700
+ function isRefusedGuidedWait(error) {
1701
+ return hasGuidedWait(error) && error.retryAfterSeconds > 60;
1702
+ }
1703
+ /**
1445
1704
  * Decides whether a failed request is eligible for retry. {@link
1446
1705
  * RateLimitError} (checked against 429) and {@link ApiError} (checked against
1447
1706
  * its `statusCode`) are retryable when their status is in `retryableStatuses`.
@@ -1527,8 +1786,8 @@ function shouldRetry(error, config) {
1527
1786
  * } from "./retry";
1528
1787
  *
1529
1788
  * const clientConfig: RetryResolvable = {
1530
- * apiKey: "k",
1531
1789
  * baseUrl: "https://apis.roblox.com",
1790
+ * credential: { apiKey: "k", kind: "apiKey" },
1532
1791
  * maxRetries: 3,
1533
1792
  * retryableStatuses: [429, 500],
1534
1793
  * retryableTransportCodes: [],
@@ -1555,8 +1814,8 @@ function shouldRetry(error, config) {
1555
1814
  * } from "./retry";
1556
1815
  *
1557
1816
  * const clientConfig: RetryResolvable = {
1558
- * apiKey: "k",
1559
1817
  * baseUrl: "https://apis.roblox.com",
1818
+ * credential: { apiKey: "k", kind: "apiKey" },
1560
1819
  * maxRetries: 3,
1561
1820
  * retryableStatuses: [429],
1562
1821
  * retryableTransportCodes: [],
@@ -1593,7 +1852,6 @@ function mergeConfig(clientConfig, { methodDefaults, methodKind, requestOptions
1593
1852
  default: throw new Error(`Unexpected methodKind: ${String(methodKind)}`);
1594
1853
  }
1595
1854
  }
1596
- //#endregion
1597
- export { parseRateLimitHeaders as C, RequestAbortedError as S, createFetchHttpClient as _, TRANSIENT_TRANSPORT_CODES as a, raceWithAbortAsync as b, defaultRetryDelay as c, shouldRetry as d, findErrorCode as f, PermissionError as g, RateLimitWaitRefusedError as h, RESPONSE_UNPARSEABLE as i, hasGuidedWait as l, RequestDeadlineExceededError as m, GATEWAY_REJECTED as n, UPLOAD_METHOD_DEFAULTS as o, RetryDelayExceededError as p, IDEMPOTENT_METHOD_DEFAULTS as r, computeRetryWaitMs as s, CREATE_METHOD_DEFAULTS as t, mergeConfig as u, isUploadRequest as v, withReportedWindow as w, requestAbortedError as x, ABORTED as y };
1855
+ export { waitForQuotaReset as A, isUploadRequest as C, requestAbortedError as D, raceWithAbortAsync as E, pickDiagnosticHeaders as F, tryCatchAsync as I, withReportedWindow as M, isRecord as N, RequestAbortedError as O, extractErrorMessage as P, createFetchHttpClient as S, ABORTED as T, RateLimitWaitRefusedError as _, TRANSIENT_TRANSPORT_CODES as a, CredentialNotSupportedError as b, defaultRetryDelay as c, mergeConfig as d, shouldRetry as f, RequestDeadlineExceededError as g, RetryDelayExceededError as h, RESPONSE_UNPARSEABLE as i, parseRateLimitHeaders as j, createRateLimitError as k, hasGuidedWait as l, UnexpectedResponseError as m, GATEWAY_REJECTED as n, UPLOAD_METHOD_DEFAULTS as o, findErrorCode as p, IDEMPOTENT_METHOD_DEFAULTS as r, computeRetryWaitMs as s, CREATE_METHOD_DEFAULTS as t, isRefusedGuidedWait as u, PermissionError as v, requestFailure as w, CredentialError as x, CredentialRejectedError as y };
1598
1856
 
1599
- //# sourceMappingURL=retry-BlX4tUnT.mjs.map
1857
+ //# sourceMappingURL=retry-Dv5TsY9O.mjs.map