@bedrock-rbx/ocale 0.3.4-beta.1 → 0.4.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 (86) hide show
  1. package/README.md +9 -5
  2. package/dist/badge-cost-mismatch-DrlvhlQc.mjs +47 -0
  3. package/dist/badge-cost-mismatch-DrlvhlQc.mjs.map +1 -0
  4. package/dist/badges.d.mts +228 -184
  5. package/dist/badges.d.mts.map +1 -1
  6. package/dist/badges.mjs +176 -18
  7. package/dist/badges.mjs.map +1 -1
  8. package/dist/capacity-admission-hycCFkTo.d.mts +355 -0
  9. package/dist/capacity-admission-hycCFkTo.d.mts.map +1 -0
  10. package/dist/{data.generated-B2ceLfSn.d.mts → data.generated-D_vpa5-g.d.mts} +23 -23
  11. package/dist/data.generated-D_vpa5-g.d.mts.map +1 -0
  12. package/dist/developer-products.d.mts +181 -186
  13. package/dist/developer-products.d.mts.map +1 -1
  14. package/dist/developer-products.mjs +24 -24
  15. package/dist/developer-products.mjs.map +1 -1
  16. package/dist/game-passes.d.mts +206 -203
  17. package/dist/game-passes.d.mts.map +1 -1
  18. package/dist/game-passes.mjs +26 -21
  19. package/dist/game-passes.mjs.map +1 -1
  20. package/dist/index.d.mts +924 -306
  21. package/dist/index.d.mts.map +1 -1
  22. package/dist/index.mjs +325 -10
  23. package/dist/index.mjs.map +1 -1
  24. package/dist/locales.d.mts +30 -2
  25. package/dist/locales.d.mts.map +1 -0
  26. package/dist/locales.mjs +24 -1
  27. package/dist/locales.mjs.map +1 -1
  28. package/dist/luau-execution.d.mts +154 -151
  29. package/dist/luau-execution.d.mts.map +1 -1
  30. package/dist/luau-execution.mjs +11 -8
  31. package/dist/luau-execution.mjs.map +1 -1
  32. package/dist/{network-error-DR9FX5hb.mjs → network-error-iVSng5MT.mjs} +44 -6
  33. package/dist/network-error-iVSng5MT.mjs.map +1 -0
  34. package/dist/places.d.mts +204 -180
  35. package/dist/places.d.mts.map +1 -1
  36. package/dist/places.mjs +66 -20
  37. package/dist/places.mjs.map +1 -1
  38. package/dist/{poll-timeout-3PXLsabj.mjs → poll-timeout-DzztDymd.mjs} +2 -2
  39. package/dist/{poll-timeout-3PXLsabj.mjs.map → poll-timeout-DzztDymd.mjs.map} +1 -1
  40. package/dist/{polling-helpers-sKTsqEc1.mjs → polling-helpers-DfF5dspc.mjs} +249 -83
  41. package/dist/polling-helpers-DfF5dspc.mjs.map +1 -0
  42. package/dist/{price-information-hWXV6DAI.mjs → price-information-DEkEQ8Pq.mjs} +2 -2
  43. package/dist/{price-information-hWXV6DAI.mjs.map → price-information-DEkEQ8Pq.mjs.map} +1 -1
  44. package/dist/resource-client-BCKukheG.d.mts +168 -0
  45. package/dist/resource-client-BCKukheG.d.mts.map +1 -0
  46. package/dist/resource-client-CaIVr-go.mjs +1419 -0
  47. package/dist/resource-client-CaIVr-go.mjs.map +1 -0
  48. package/dist/retry-C2oHesDx.d.mts +229 -0
  49. package/dist/retry-C2oHesDx.d.mts.map +1 -0
  50. package/dist/{retry-vpHMIwaU.mjs → retry-CMRDvAR4.mjs} +390 -20
  51. package/dist/retry-CMRDvAR4.mjs.map +1 -0
  52. package/dist/storage.d.mts +333 -334
  53. package/dist/storage.d.mts.map +1 -1
  54. package/dist/storage.mjs +29 -22
  55. package/dist/storage.mjs.map +1 -1
  56. package/dist/testing.d.mts +347 -360
  57. package/dist/testing.d.mts.map +1 -1
  58. package/dist/testing.mjs +3 -4
  59. package/dist/testing.mjs.map +1 -1
  60. package/dist/types-CdMr_J1M.d.mts +509 -0
  61. package/dist/types-CdMr_J1M.d.mts.map +1 -0
  62. package/dist/universes.d.mts +619 -422
  63. package/dist/universes.d.mts.map +1 -1
  64. package/dist/universes.mjs +421 -48
  65. package/dist/universes.mjs.map +1 -1
  66. package/dist/{validation-B_Zs1So2.mjs → validation-964VNlbp.mjs} +2 -2
  67. package/dist/{validation-B_Zs1So2.mjs.map → validation-964VNlbp.mjs.map} +1 -1
  68. package/dist/wire-DJqupefn.d.mts +41 -0
  69. package/dist/wire-DJqupefn.d.mts.map +1 -0
  70. package/package.json +14 -14
  71. package/dist/capacity-admission-BvnJjY0S.d.mts +0 -369
  72. package/dist/capacity-admission-BvnJjY0S.d.mts.map +0 -1
  73. package/dist/data.generated-B2ceLfSn.d.mts.map +0 -1
  74. package/dist/network-error-DR9FX5hb.mjs.map +0 -1
  75. package/dist/polling-helpers-sKTsqEc1.mjs.map +0 -1
  76. package/dist/resource-client-3cOhqZpX.mjs +0 -899
  77. package/dist/resource-client-3cOhqZpX.mjs.map +0 -1
  78. package/dist/resource-client-BivRq3JZ.d.mts +0 -164
  79. package/dist/resource-client-BivRq3JZ.d.mts.map +0 -1
  80. package/dist/retry-DXEklFrt.d.mts +0 -373
  81. package/dist/retry-DXEklFrt.d.mts.map +0 -1
  82. package/dist/retry-vpHMIwaU.mjs.map +0 -1
  83. package/dist/types-C3Egi37J.d.mts +0 -378
  84. package/dist/types-C3Egi37J.d.mts.map +0 -1
  85. package/dist/wire-D3K-a-UP.d.mts +0 -37
  86. package/dist/wire-D3K-a-UP.d.mts.map +0 -1
@@ -1,4 +1,4 @@
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";
1
+ import { a as ApiError, i as markServerRetryGuidance, n as RateLimitError, r as hasServerRetryGuidance, s as OpenCloudError, t as NetworkError } from "./network-error-iVSng5MT.mjs";
2
2
  //#region src/internal/utils/try-catch.ts
3
3
  /**
4
4
  * Wraps a promise into a {@link Result}, catching rejections.
@@ -24,14 +24,14 @@ async function tryCatchAsync(promise) {
24
24
  //#region src/internal/http/diagnostics.ts
25
25
  const MAX_DETAIL_LENGTH = 500;
26
26
  const CONTENT_TYPE_HEADER$1 = "content-type";
27
- const DIAGNOSTIC_HEADER_ALLOWLIST = new Set([
27
+ const DIAGNOSTIC_HEADER_ALLOWLIST = /* @__PURE__ */ new Set([
28
28
  "cf-ray",
29
29
  "server",
30
30
  "via",
31
31
  "x-request-id"
32
32
  ]);
33
33
  const DIAGNOSTIC_HEADER_PREFIX = "x-roblox-";
34
- const RATE_LIMIT_HEADER_ALLOWLIST = new Set([
34
+ const RATE_LIMIT_HEADER_ALLOWLIST = /* @__PURE__ */ new Set([
35
35
  "date",
36
36
  "retry-after",
37
37
  "x-envoy-ratelimited",
@@ -128,7 +128,8 @@ function bodyDetail(text, parsed) {
128
128
  * @returns An ApiError carrying the diagnostic context.
129
129
  */
130
130
  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)`, {
131
+ const contentType = response.headers.get(CONTENT_TYPE_HEADER$1) ?? "unknown";
132
+ return new ApiError(`Failed to parse response body (content-type: ${contentType}, ${String(text.length)} chars read)`, {
132
133
  cause,
133
134
  details: text.slice(0, MAX_DETAIL_LENGTH),
134
135
  elapsedMs: context.elapsedMs,
@@ -330,7 +331,22 @@ function constructHttp1(agent) {
330
331
  }
331
332
  }
332
333
  //#endregion
334
+ //#region src/internal/utils/is-record.ts
335
+ /**
336
+ * Narrows `value` to a plain JSON-style record. Excludes arrays, class
337
+ * instances, primitives, and `null`/`undefined`. Used by resource
338
+ * parsers to gate property access on wire bodies whose shape isn't
339
+ * known at compile time.
340
+ *
341
+ * @param value - The unknown value to narrow.
342
+ * @returns `true` when `value` is a plain `[object Object]`.
343
+ */
344
+ function isRecord(value) {
345
+ return Object.prototype.toString.call(value) === "[object Object]";
346
+ }
347
+ //#endregion
333
348
  //#region src/internal/http/rate-limit-sample.ts
349
+ const LIMIT_POLICY_PATTERN = /^(\d+);w=(\d+)$/;
334
350
  const NON_NEGATIVE_INTEGER_PATTERN = /^\d+$/;
335
351
  /**
336
352
  * Reduces a comma-separated rate-limit header value (e.g. `"0, 70000"`) to a
@@ -350,6 +366,21 @@ function reduceRateLimitTokens(headerValue, combine) {
350
366
  return tokens.reduce(combine);
351
367
  }
352
368
  /**
369
+ * Attaches the window capacity an `x-ratelimit-limit` header reports to a
370
+ * sample, leaving the sample as is when the header has no usable policy.
371
+ *
372
+ * @param sample - The budget reading to extend.
373
+ * @param limitHeader - The raw limit header, or `undefined` if missing.
374
+ * @returns The sample, with `window` set when the header reports one.
375
+ */
376
+ function withReportedWindow(sample, limitHeader) {
377
+ const window = parseRateLimitWindow(limitHeader);
378
+ return window === void 0 ? sample : {
379
+ ...sample,
380
+ window
381
+ };
382
+ }
383
+ /**
353
384
  * Parses the `x-ratelimit-remaining` and `x-ratelimit-reset` response headers
354
385
  * into a {@link RateLimitSample}. Each header may carry a comma-separated list
355
386
  * of per-window values; `remaining` takes the smallest (most constrained) and
@@ -368,10 +399,39 @@ function parseRateLimitHeaders(headers) {
368
399
  return Math.max(a, b);
369
400
  });
370
401
  if (remaining === void 0 || resetSeconds === void 0) return;
371
- return {
402
+ return withReportedWindow({
372
403
  remaining,
373
404
  resetSeconds
374
- };
405
+ }, headers["x-ratelimit-limit"]);
406
+ }
407
+ function isPositiveSafeInteger(value) {
408
+ return Number.isSafeInteger(value) && value > 0;
409
+ }
410
+ function rate({ capacity, windowSeconds }) {
411
+ return capacity / windowSeconds;
412
+ }
413
+ /**
414
+ * Parses the `<capacity>;w=<seconds>` policies of an `x-ratelimit-limit`
415
+ * header (e.g. `"3, 3;w=1, 3;w=1"`). Bare tokens, which name no window, are
416
+ * skipped, as are policies whose values are zero or too large to be exact
417
+ * integers. When several policies are listed the one with the lowest sustained
418
+ * rate wins, since pacing to it keeps every other policy satisfied too; among
419
+ * equally slow policies the shorter window wins, as it allows the smaller
420
+ * burst.
421
+ *
422
+ * @param headerValue - The raw limit header, or `undefined` if missing.
423
+ * @returns The slowest policy, or `undefined` when none is usable.
424
+ */
425
+ function parseRateLimitWindow(headerValue) {
426
+ if (headerValue === void 0) return;
427
+ return headerValue.split(",").map((part) => LIMIT_POLICY_PATTERN.exec(part.trim())).filter((match) => match !== null).map((match) => {
428
+ return {
429
+ capacity: Number(match[1]),
430
+ windowSeconds: Number(match[2])
431
+ };
432
+ }).filter(({ capacity, windowSeconds }) => {
433
+ return isPositiveSafeInteger(capacity) && isPositiveSafeInteger(windowSeconds);
434
+ }).toSorted((a, b) => rate(a) - rate(b) || a.windowSeconds - b.windowSeconds)[0];
375
435
  }
376
436
  //#endregion
377
437
  //#region src/internal/http/retry-guidance.ts
@@ -506,6 +566,22 @@ function parseHttpDate(value, nowMs) {
506
566
  //#endregion
507
567
  //#region src/internal/http/rate-limit-response.ts
508
568
  /**
569
+ * Classifies which layer refused a 429 from its headers and parsed body.
570
+ * `"service"` needs a non-blank `x-roblox-system-reason` header. `"edge"`
571
+ * needs no such header and a body of only `{ code: 0, message: "" }` entries
572
+ * under `errors`. Anything else, including a body `code` alone, is
573
+ * `"unknown"`.
574
+ *
575
+ * @param headers - The response headers (lowercased keys).
576
+ * @param details - The parsed or safely truncated response body.
577
+ * @returns The refusing layer, or `"unknown"` without positive evidence.
578
+ */
579
+ function classifyRateLimitSource(headers, details) {
580
+ const reason = headers["x-roblox-system-reason"];
581
+ if (isNonBlankString(reason)) return "service";
582
+ return isEdgeBody(details) ? "edge" : "unknown";
583
+ }
584
+ /**
509
585
  * Builds a public rate-limit error from a 429 response and its already-read
510
586
  * body, retaining safe raw evidence alongside the existing parsed guidance.
511
587
  *
@@ -528,14 +604,25 @@ function createRateLimitError(response, details) {
528
604
  remaining,
529
605
  responseHeaders: pickRateLimitHeaders(headers),
530
606
  retryAfterSeconds: guidedRetrySeconds ?? 0,
607
+ source: classifyRateLimitSource(headers, details),
531
608
  statusCode: response.status
532
609
  });
533
610
  return guidedRetrySeconds === void 0 ? error : markServerRetryGuidance(error);
534
611
  }
612
+ function isEdgeBody(body) {
613
+ if (!isRecord(body)) return false;
614
+ const { errors } = body;
615
+ return Array.isArray(errors) && errors.length > 0 && errors.every((entry) => {
616
+ return isRecord(entry) && entry["code"] === 0 && entry["message"] === "";
617
+ });
618
+ }
619
+ function isNonBlankString(value) {
620
+ return typeof value === "string" && value.trim() !== "";
621
+ }
535
622
  function extractRateLimitErrorCode(body) {
536
- if (body === null || typeof body !== "object") return;
537
- const code = Reflect.get(body, "code");
538
- return typeof code === "string" && code.trim() ? code : void 0;
623
+ if (!isRecord(body)) return;
624
+ const { code } = body;
625
+ return isNonBlankString(code) ? code : void 0;
539
626
  }
540
627
  //#endregion
541
628
  //#region src/errors/request-aborted.ts
@@ -662,6 +749,8 @@ function isUploadRequest(request) {
662
749
  //#region src/internal/http/fetch-client.ts
663
750
  const CONTENT_TYPE_HEADER = "content-type";
664
751
  const CONNECTION_HEADER = "connection";
752
+ /** Headers the transport owns for the credential; a request cannot set them. */
753
+ const CREDENTIAL_HEADERS = /* @__PURE__ */ new Set(["authorization", "x-api-key"]);
665
754
  /**
666
755
  * Joins the base URL from config with the relative path from the request.
667
756
  *
@@ -676,11 +765,11 @@ function buildUrl(request, config) {
676
765
  * Constructs the `RequestInit` options for a `fetch` call.
677
766
  *
678
767
  * @param request - The HTTP request to build options for.
679
- * @param config - The request config containing API key and timeout.
768
+ * @param config - The request config containing the credential and timeout.
680
769
  * @returns A `RequestInit` object ready for `fetch`.
681
770
  */
682
771
  function buildFetchOptions(request, config) {
683
- const headers = new Headers({ "x-api-key": config.apiKey });
772
+ const headers = new Headers(credentialHeader(config));
684
773
  const options = {
685
774
  headers,
686
775
  method: request.method
@@ -719,10 +808,26 @@ function createFetchHttpClient(fetchFunc = fetch, { createDispatcher = createHtt
719
808
  } };
720
809
  }
721
810
  /**
811
+ * Picks the credential header for a request: `x-api-key` for an API key,
812
+ * `authorization: Bearer` for an OAuth access token, and none for an
813
+ * unauthenticated request.
814
+ *
815
+ * @param config - The request config holding the credential.
816
+ * @returns The credential header to send, if any.
817
+ */
818
+ function credentialHeader({ credential }) {
819
+ switch (credential.kind) {
820
+ case "apiKey": return { "x-api-key": credential.apiKey };
821
+ case "none": return {};
822
+ case "oauth": return { authorization: `Bearer ${credential.accessToken}` };
823
+ }
824
+ }
825
+ /**
722
826
  * Merges the request's own headers onto the transport's, then applies the
723
- * transport-owned connection directive. `x-api-key` is skipped so a request
724
- * cannot override the configured credential, and the upload directive is set
725
- * last so a request header cannot silently re-enable pooling for an upload.
827
+ * transport-owned connection directive. `x-api-key` and `authorization` are
828
+ * skipped so a request cannot override the configured credential, and the
829
+ * upload directive is set last so a request header cannot silently re-enable
830
+ * pooling for an upload.
726
831
  *
727
832
  * @param headers - The headers being built for the fetch call. Mutated.
728
833
  * @param request - The request whose headers and body shape drive the merge.
@@ -730,7 +835,7 @@ function createFetchHttpClient(fetchFunc = fetch, { createDispatcher = createHtt
730
835
  function applyRequestHeaders(headers, request) {
731
836
  const requestHeaders = request.headers ?? {};
732
837
  for (const [name, value] of Object.entries(requestHeaders)) {
733
- if (name.toLowerCase() === "x-api-key") continue;
838
+ if (CREDENTIAL_HEADERS.has(name.toLowerCase())) continue;
734
839
  headers.set(name, value);
735
840
  }
736
841
  if (isUploadRequest(request)) headers.set(CONNECTION_HEADER, "close");
@@ -783,9 +888,10 @@ function createApiError(args) {
783
888
  });
784
889
  const body = bodyDetail(rawText, args.parsed);
785
890
  const code = extractErrorCode(body);
891
+ const message = extractErrorMessage(body);
786
892
  return new ApiError(formatApiErrorMessage({
787
893
  code,
788
- message: extractErrorMessage(body),
894
+ message,
789
895
  status
790
896
  }), {
791
897
  ...requestContext,
@@ -935,6 +1041,111 @@ function createUploadDispatcherCache(createDispatcher) {
935
1041
  };
936
1042
  }
937
1043
  //#endregion
1044
+ //#region src/errors/credential-error.ts
1045
+ /**
1046
+ * Returned when an OAuth credential's `getAccessToken` throws or rejects.
1047
+ * The provider's error is the `cause`, passed through unchanged. The client
1048
+ * sends no request for that attempt and spends no retry.
1049
+ *
1050
+ * @since 0.4.0
1051
+ *
1052
+ * @example
1053
+ *
1054
+ * ```ts
1055
+ * import { CredentialError } from "@bedrock-rbx/ocale";
1056
+ *
1057
+ * const providerError = new Error("refresh token revoked");
1058
+ * const error = new CredentialError("Credential provider failed", {
1059
+ * cause: providerError,
1060
+ * });
1061
+ *
1062
+ * expect(error).toBeInstanceOf(CredentialError);
1063
+ * expect(error.cause).toBe(providerError);
1064
+ * ```
1065
+ */
1066
+ var CredentialError = class extends OpenCloudError {
1067
+ name = "CredentialError";
1068
+ };
1069
+ //#endregion
1070
+ //#region src/errors/credential-not-supported.ts
1071
+ /**
1072
+ * Returned when an OAuth credential calls an Operation that Roblox accepts
1073
+ * only with an API key (place publish and save, Luau execution and memory
1074
+ * stores). The client returns it before it asks the provider for a token, and
1075
+ * it sends no request.
1076
+ *
1077
+ * @since 0.4.0
1078
+ *
1079
+ * @example
1080
+ *
1081
+ * ```ts
1082
+ * import { CredentialNotSupportedError } from "@bedrock-rbx/ocale";
1083
+ *
1084
+ * const error = new CredentialNotSupportedError("Operation needs an API key", {
1085
+ * operationKey: "places.publishVersion",
1086
+ * });
1087
+ *
1088
+ * expect(error).toBeInstanceOf(CredentialNotSupportedError);
1089
+ * expect(error.operationKey).toBe("places.publishVersion");
1090
+ * ```
1091
+ */
1092
+ var CredentialNotSupportedError = class extends OpenCloudError {
1093
+ name = "CredentialNotSupportedError";
1094
+ operationKey;
1095
+ /**
1096
+ * Creates a new CredentialNotSupportedError.
1097
+ *
1098
+ * @param message - Human-readable description of the failure.
1099
+ * @param options - Error options including the Operation's key.
1100
+ */
1101
+ constructor(message, options) {
1102
+ super(message, options);
1103
+ this.operationKey = options.operationKey;
1104
+ }
1105
+ };
1106
+ //#endregion
1107
+ //#region src/errors/credential-rejected.ts
1108
+ /**
1109
+ * Returned when Roblox refuses an OAuth Credential's token: a non-gateway
1110
+ * 401, or a non-gateway 502 whose body message is "Scope authorization
1111
+ * failed.". The grant is lost, so the client does not retry. Carries the
1112
+ * Credential `identity` (never the token) so the caller can ask that user to
1113
+ * consent again. The upstream `ApiError` is the `cause`.
1114
+ *
1115
+ * @since 0.4.0
1116
+ *
1117
+ * @example
1118
+ *
1119
+ * ```ts
1120
+ * import { CredentialRejectedError } from "@bedrock-rbx/ocale";
1121
+ *
1122
+ * const error = new CredentialRejectedError("HTTP 401: Invalid Token.", {
1123
+ * identity: "user-123",
1124
+ * statusCode: 401,
1125
+ * });
1126
+ *
1127
+ * expect(error.identity).toBe("user-123");
1128
+ * expect(error.statusCode).toBe(401);
1129
+ * ```
1130
+ */
1131
+ var CredentialRejectedError = class extends OpenCloudError {
1132
+ identity;
1133
+ name = "CredentialRejectedError";
1134
+ statusCode;
1135
+ /**
1136
+ * Creates a new CredentialRejectedError.
1137
+ *
1138
+ * @param message - Human-readable error description.
1139
+ * @param options - Error options including the Credential identity and
1140
+ * the HTTP status of the refusal.
1141
+ */
1142
+ constructor(message, options) {
1143
+ super(message, options);
1144
+ this.identity = options.identity;
1145
+ this.statusCode = options.statusCode;
1146
+ }
1147
+ };
1148
+ //#endregion
938
1149
  //#region src/errors/permission-error.ts
939
1150
  /**
940
1151
  * Thrown when the Roblox Open Cloud API returns a 401 or 403 for an operation
@@ -983,6 +1194,60 @@ var PermissionError = class extends ApiError {
983
1194
  }
984
1195
  };
985
1196
  //#endregion
1197
+ //#region src/errors/rate-limit-wait-refused.ts
1198
+ /**
1199
+ * Returned at once when a 429 asks for a wait longer than the 60 seconds the
1200
+ * SDK waits out on its own. The server's requested wait is kept exactly as
1201
+ * sent, alongside the 429's evidence, so a caller can schedule its own retry.
1202
+ *
1203
+ * Distinct from a {@link RateLimitError} returned after `maxRetries` runs out,
1204
+ * and from a `RequestDeadlineExceededError`.
1205
+ *
1206
+ * @since 0.3.4
1207
+ *
1208
+ * @example
1209
+ *
1210
+ * ```ts
1211
+ * import { RateLimitError, RateLimitWaitRefusedError } from "@bedrock-rbx/ocale";
1212
+ *
1213
+ * const error = new RateLimitWaitRefusedError("Rate limit asks for a 300s wait", {
1214
+ * cause: new RateLimitError("Rate limited", { remaining: 0, retryAfterSeconds: 300 }),
1215
+ * });
1216
+ *
1217
+ * expect(error.retryAfterSeconds).toBe(300);
1218
+ * expect(error.remaining).toBe(0);
1219
+ * ```
1220
+ */
1221
+ var RateLimitWaitRefusedError = class extends OpenCloudError {
1222
+ /** The 429 whose requested wait was refused. */
1223
+ cause;
1224
+ name = "RateLimitWaitRefusedError";
1225
+ /** Requests left in the reported window, or `undefined` if not reported. */
1226
+ remaining;
1227
+ /**
1228
+ * Allowlisted raw response headers of the 429, or `undefined` if not set.
1229
+ */
1230
+ responseHeaders;
1231
+ /** The wait the server asked for, in seconds, uncapped. */
1232
+ retryAfterSeconds;
1233
+ /**
1234
+ * Creates a new RateLimitWaitRefusedError.
1235
+ *
1236
+ * @param message - Human-readable description of the refused wait.
1237
+ * @param options - The 429 whose requested wait was refused.
1238
+ */
1239
+ constructor(message, { cause }) {
1240
+ super(message, {
1241
+ cause,
1242
+ code: cause.code
1243
+ });
1244
+ this.cause = cause;
1245
+ this.remaining = cause.remaining;
1246
+ this.responseHeaders = cause.responseHeaders;
1247
+ this.retryAfterSeconds = cause.retryAfterSeconds;
1248
+ }
1249
+ };
1250
+ //#endregion
986
1251
  //#region src/errors/request-deadline-exceeded.ts
987
1252
  /**
988
1253
  * Returned when a logical request cannot complete by its absolute deadline.
@@ -1078,6 +1343,89 @@ var RetryDelayExceededError = class extends RequestDeadlineExceededError {
1078
1343
  }
1079
1344
  };
1080
1345
  //#endregion
1346
+ //#region src/errors/unexpected-response.ts
1347
+ const NEW_ISSUE_URL = "https://github.com/christopher-buss/bedrock/issues/new";
1348
+ /**
1349
+ * Returned when Open Cloud accepts a request and answers, but the response
1350
+ * body has a shape that ocale's wire model rejects. The API did not refuse the
1351
+ * request, so this is not an `ApiError`: the fault is more likely a stale wire
1352
+ * model or a parser bug in ocale than a problem with the caller's input. The
1353
+ * raw body is kept on `details`, with the request context, so the mismatch can
1354
+ * be reported. `reportUrl` opens an ocale bug report prefilled with the
1355
+ * message, status, and failing call. It leaves out the body, which can hold
1356
+ * private data.
1357
+ *
1358
+ * @since 0.4.0
1359
+ *
1360
+ * @example
1361
+ *
1362
+ * ```ts
1363
+ * import { ApiError, UnexpectedResponseError } from "@bedrock-rbx/ocale";
1364
+ *
1365
+ * const error = new UnexpectedResponseError("Malformed badge response", {
1366
+ * details: { id: "not-a-number" },
1367
+ * method: "GET",
1368
+ * statusCode: 200,
1369
+ * url: "https://apis.roblox.com/legacy-badges/v1/badges/1",
1370
+ * });
1371
+ *
1372
+ * // A shape mismatch is not an API rejection.
1373
+ * expect(error).not.toBeInstanceOf(ApiError);
1374
+ * expect(error.details).toStrictEqual({ id: "not-a-number" });
1375
+ * ```
1376
+ */
1377
+ var UnexpectedResponseError = class extends OpenCloudError {
1378
+ details;
1379
+ method;
1380
+ name = "UnexpectedResponseError";
1381
+ /** Link to a new ocale bug report, prefilled with this failure. */
1382
+ reportUrl;
1383
+ responseHeaders;
1384
+ statusCode;
1385
+ url;
1386
+ /**
1387
+ * Creates a new UnexpectedResponseError.
1388
+ *
1389
+ * @param message - Human-readable description naming the response that
1390
+ * did not match.
1391
+ * @param options - The status code, the raw body as `details`, and the
1392
+ * request context when known.
1393
+ */
1394
+ constructor(message, options) {
1395
+ const reportUrl = buildReportUrl(message, options);
1396
+ super(options.reportHint === true ? `${message}\n${reportLine(reportUrl)}` : message, options);
1397
+ this.details = options.details;
1398
+ this.method = options.method;
1399
+ this.responseHeaders = options.responseHeaders;
1400
+ this.statusCode = options.statusCode;
1401
+ this.url = options.url;
1402
+ this.reportUrl = reportUrl;
1403
+ }
1404
+ };
1405
+ function reportLine(reportUrl) {
1406
+ return `This is likely a bug in @bedrock-rbx/ocale. Report it at ${reportUrl}`;
1407
+ }
1408
+ function reportBody(message, { method, responseHeaders, statusCode, url }) {
1409
+ const request = method !== void 0 && url !== void 0 ? [`- Request: ${method} ${url}`] : [];
1410
+ const headers = Object.entries(responseHeaders ?? {}).map(([name, value]) => `- ${name}: ${value}`);
1411
+ return [
1412
+ "`UnexpectedResponseError` from `@bedrock-rbx/ocale`.",
1413
+ "",
1414
+ `- Message: ${message}`,
1415
+ `- Status: ${String(statusCode)}`,
1416
+ ...request,
1417
+ ...headers
1418
+ ].join("\n");
1419
+ }
1420
+ function buildReportUrl(message, options) {
1421
+ const query = new URLSearchParams({
1422
+ body: reportBody(message, options),
1423
+ template: "bug-report.md",
1424
+ title: `[Bug]: ${message}`
1425
+ });
1426
+ return `${NEW_ISSUE_URL}?${query.toString()}`;
1427
+ }
1428
+ //#endregion
1081
1429
  //#region src/internal/utils/find-error-code.ts
1082
1430
  /**
1083
1431
  * Maximum cause-chain depth walked by {@link findErrorCode}. Caps pathological
@@ -1332,6 +1680,28 @@ function computeRetryWaitMs(error, options) {
1332
1680
  return options.retryDelay(options.attempt);
1333
1681
  }
1334
1682
  /**
1683
+ * Whether a failure is a rate limit whose server guidance asks for a positive
1684
+ * wait. Such a wait is taken without spending one of `maxRetries`; guidance of
1685
+ * zero seconds is an immediate retry and spends one like any other.
1686
+ *
1687
+ * @param error - The error returned by the failing request.
1688
+ * @returns `true` for a rate limit naming a wait longer than zero.
1689
+ */
1690
+ function hasGuidedWait(error) {
1691
+ return error instanceof RateLimitError && error.retryAfterSeconds > 0;
1692
+ }
1693
+ /**
1694
+ * Whether a failure is a rate limit whose guided wait is longer than the
1695
+ * {@link MAX_GUIDED_WAIT_SECONDS} the SDK waits out on its own, so the SDK
1696
+ * refuses it.
1697
+ *
1698
+ * @param error - The error returned by the failing request.
1699
+ * @returns `true` for a rate limit naming a wait the SDK refuses.
1700
+ */
1701
+ function isRefusedGuidedWait(error) {
1702
+ return hasGuidedWait(error) && error.retryAfterSeconds > 60;
1703
+ }
1704
+ /**
1335
1705
  * Decides whether a failed request is eligible for retry. {@link
1336
1706
  * RateLimitError} (checked against 429) and {@link ApiError} (checked against
1337
1707
  * its `statusCode`) are retryable when their status is in `retryableStatuses`.
@@ -1417,8 +1787,8 @@ function shouldRetry(error, config) {
1417
1787
  * } from "./retry";
1418
1788
  *
1419
1789
  * const clientConfig: RetryResolvable = {
1420
- * apiKey: "k",
1421
1790
  * baseUrl: "https://apis.roblox.com",
1791
+ * credential: { apiKey: "k", kind: "apiKey" },
1422
1792
  * maxRetries: 3,
1423
1793
  * retryableStatuses: [429, 500],
1424
1794
  * retryableTransportCodes: [],
@@ -1445,8 +1815,8 @@ function shouldRetry(error, config) {
1445
1815
  * } from "./retry";
1446
1816
  *
1447
1817
  * const clientConfig: RetryResolvable = {
1448
- * apiKey: "k",
1449
1818
  * baseUrl: "https://apis.roblox.com",
1819
+ * credential: { apiKey: "k", kind: "apiKey" },
1450
1820
  * maxRetries: 3,
1451
1821
  * retryableStatuses: [429],
1452
1822
  * retryableTransportCodes: [],
@@ -1484,6 +1854,6 @@ function mergeConfig(clientConfig, { methodDefaults, methodKind, requestOptions
1484
1854
  }
1485
1855
  }
1486
1856
  //#endregion
1487
- export { ABORTED as _, TRANSIENT_TRANSPORT_CODES as a, RequestAbortedError as b, defaultRetryDelay as c, findErrorCode as d, RetryDelayExceededError as f, isUploadRequest as g, createFetchHttpClient as h, RESPONSE_UNPARSEABLE as i, mergeConfig as l, PermissionError as m, GATEWAY_REJECTED as n, UPLOAD_METHOD_DEFAULTS as o, RequestDeadlineExceededError as p, IDEMPOTENT_METHOD_DEFAULTS as r, computeRetryWaitMs as s, CREATE_METHOD_DEFAULTS as t, shouldRetry as u, raceWithAbortAsync as v, parseRateLimitHeaders as x, requestAbortedError as y };
1857
+ export { withReportedWindow as A, isUploadRequest as C, RequestAbortedError as D, requestAbortedError as E, extractErrorMessage as M, pickDiagnosticHeaders as N, parseQuotaResetSeconds as O, createFetchHttpClient as S, raceWithAbortAsync 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, isRecord as j, parseRateLimitHeaders 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, ABORTED as w, CredentialError as x, CredentialRejectedError as y };
1488
1858
 
1489
- //# sourceMappingURL=retry-vpHMIwaU.mjs.map
1859
+ //# sourceMappingURL=retry-CMRDvAR4.mjs.map