@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
package/dist/index.d.mts CHANGED
@@ -1,186 +1,629 @@
1
- import { a as HttpRequest, c as OpenCloudHooks, d as Page, f as Result, h as OpenCloudErrorOptions, i as HttpClient, l as RequestConfig, m as OpenCloudError, n as AdmissionWaitObserver, o as HttpResponse, p as SleepFunc, r as AdmissionWaitReason, s as OpenCloudClientOptions, t as AdmissionWaitEvent, u as RequestOptions } from "./types-C3Egi37J.mjs";
2
- import { a as TRANSIENT_TRANSPORT_CODES, c as NetworkError, d as ApiErrorOptions, f as ApiRequestContext, l as NetworkErrorOptions, o as RateLimitError, p as requestContextOf, r as RESPONSE_UNPARSEABLE, s as RateLimitErrorOptions, t as GATEWAY_REJECTED, u as ApiError } from "./retry-DXEklFrt.mjs";
3
-
1
+ import { _ as OpenCloudErrorOptions, a as HttpClient, c as OpenCloudClientOptions, d as RequestOptions, f as ResolvedCredential, g as OpenCloudError, h as SleepFunc, i as Credential, l as OpenCloudHooks, m as Result, n as AdmissionWaitObserver, o as HttpRequest, p as Page, r as AdmissionWaitReason, s as HttpResponse, t as AdmissionWaitEvent, u as RequestConfig } from "./types-CdMr_J1M.mjs";
2
+ import { a as TRANSIENT_TRANSPORT_CODES, c as RateLimitSource, o as RateLimitError, r as RESPONSE_UNPARSEABLE, s as RateLimitErrorOptions, t as GATEWAY_REJECTED } from "./retry-C2oHesDx.mjs";
4
3
  //#region src/client/fetch-http-client.d.ts
5
4
  /**
6
- * Creates the fetch-backed HTTP transport Ocale uses by default.
7
- *
8
- * Wrap the returned transport to add tracing, metrics, recording, or other
9
- * request-level behavior while retaining Ocale's authentication, timeout,
10
- * upload, response-parsing, and error-classification semantics.
11
- *
12
- * @returns Ocale's default fetch-backed HTTP transport.
13
- * @since 0.3.1
14
- *
15
- * @example
16
- *
17
- * ```ts
18
- * import {
19
- * createFetchHttpClient,
20
- * type HttpClient,
21
- * type HttpRequest,
22
- * } from "@bedrock-rbx/ocale";
23
- * import {
24
- * type DeleteExperienceIconParameters,
25
- * UniversesClient,
26
- * } from "@bedrock-rbx/ocale/universes";
27
- *
28
- * const defaultHttpClient = createFetchHttpClient();
29
- * let observedRequests: ReadonlyArray<HttpRequest> = [];
30
- * const tracedHttpClient: HttpClient = {
31
- * async request(request, config) {
32
- * observedRequests = [...observedRequests, request];
33
- * return defaultHttpClient.request(request, config);
34
- * },
35
- * };
36
- * // A data URL keeps this executable example offline. Production clients
37
- * // normally omit baseUrl and use Ocale's Roblox Open Cloud default.
38
- * const commonOptions = { apiKey: "your-key", baseUrl: "data:,#" };
39
- * const client = new UniversesClient({
40
- * ...commonOptions,
41
- * httpClient: tracedHttpClient,
42
- * });
43
- * const undecoratedClient = new UniversesClient({
44
- * ...commonOptions,
45
- * httpClient: defaultHttpClient,
46
- * });
47
- * const parameters: DeleteExperienceIconParameters = {
48
- * languageCode: "en",
49
- * universeId: "42",
50
- * };
51
- * expect(client).toBeInstanceOf(UniversesClient);
52
- * return Promise.all([
53
- * client.icon.delete(parameters),
54
- * undecoratedClient.icon.delete(parameters),
55
- * ]).then(([result, undecoratedResult]) => {
56
- * expect(observedRequests).toStrictEqual([{
57
- * method: "DELETE",
58
- * url: "/legacy-game-internationalization/v1/game-icon/games/42/language-codes/en",
59
- * }]);
60
- * expect(result).toStrictEqual({ data: undefined, success: true });
61
- * expect(result).toStrictEqual(undecoratedResult);
62
- * });
63
- * ```
64
- */
65
- declare const createFetchHttpClient: () => HttpClient;
5
+ * Creates the fetch-backed HTTP transport Ocale uses by default.
6
+ *
7
+ * Wrap the returned transport to add tracing, metrics, recording, or other
8
+ * request-level behavior while retaining Ocale's authentication, timeout,
9
+ * upload, response-parsing, and error-classification semantics.
10
+ *
11
+ * Pass `fetch` to send through a wrapped or replacement `fetch`. Omit it to
12
+ * use the global `fetch`.
13
+ *
14
+ * @param options - Optional transport settings.
15
+ * @param options.fetch - The `fetch` to send requests through.
16
+ * @returns Ocale's default fetch-backed HTTP transport.
17
+ * @since 0.3.1
18
+ *
19
+ * @example
20
+ *
21
+ * ```ts
22
+ * import {
23
+ * createFetchHttpClient,
24
+ * type HttpClient,
25
+ * type HttpRequest,
26
+ * } from "@bedrock-rbx/ocale";
27
+ * import {
28
+ * type DeleteExperienceIconParameters,
29
+ * UniversesClient,
30
+ * } from "@bedrock-rbx/ocale/universes";
31
+ *
32
+ * // An injected response keeps this executable example offline.
33
+ * // Omit fetch in production to use the runtime's global fetch.
34
+ * const defaultHttpClient = createFetchHttpClient({
35
+ * fetch: async () => new Response(),
36
+ * });
37
+ * let observedRequests: ReadonlyArray<HttpRequest> = [];
38
+ * const tracedHttpClient: HttpClient = {
39
+ * async request(request, config) {
40
+ * observedRequests = [...observedRequests, request];
41
+ * return defaultHttpClient.request(request, config);
42
+ * },
43
+ * };
44
+ * const commonOptions = {
45
+ * credential: { apiKey: "your-key", kind: "apiKey" as const },
46
+ * };
47
+ * const client = new UniversesClient({
48
+ * ...commonOptions,
49
+ * httpClient: tracedHttpClient,
50
+ * });
51
+ * const undecoratedClient = new UniversesClient({
52
+ * ...commonOptions,
53
+ * httpClient: defaultHttpClient,
54
+ * });
55
+ * const parameters: DeleteExperienceIconParameters = {
56
+ * languageCode: "en",
57
+ * universeId: "42",
58
+ * };
59
+ * expect(client).toBeInstanceOf(UniversesClient);
60
+ * return Promise.all([
61
+ * client.icon.delete(parameters),
62
+ * undecoratedClient.icon.delete(parameters),
63
+ * ]).then(([result, undecoratedResult]) => {
64
+ * expect(observedRequests).toStrictEqual([{
65
+ * method: "DELETE",
66
+ * url: "/legacy-game-internationalization/v1/game-icon/games/42/language-codes/en",
67
+ * }]);
68
+ * expect(result).toStrictEqual({ data: undefined, success: true });
69
+ * expect(result).toStrictEqual(undecoratedResult);
70
+ * });
71
+ * ```
72
+ */
73
+ export declare function createFetchHttpClient(options?: {
74
+ readonly fetch?: (input: string, init: RequestInit) => Promise<Response>;
75
+ }): HttpClient;
76
+ //#endregion
77
+ //#region src/client/oauth-token-refresher.d.ts
78
+ /**
79
+ * Options for {@link createOAuthTokenRefresher}.
80
+ *
81
+ * @since 0.4.0
82
+ */
83
+ interface OAuthTokenRefresherOptions {
84
+ /** The OAuth app's client id. */
85
+ readonly clientId: string;
86
+ /**
87
+ * The client secret of a confidential app. Omit it for a public app that
88
+ * uses a code verifier.
89
+ */
90
+ readonly clientSecret?: string;
91
+ /**
92
+ * The `fetch` to send token requests through. Defaults to the global
93
+ * `fetch`.
94
+ */
95
+ readonly fetch?: (input: string, init: RequestInit) => Promise<Response>;
96
+ /**
97
+ * Saves the new refresh token after each rotation. The new access token is
98
+ * used only after it resolves. If it throws, the call throws, and the next
99
+ * call retries it with the same token and does no exchange.
100
+ */
101
+ readonly onRotate: (refreshToken: string) => Promise<void> | void;
102
+ /** The current refresh token. It is spent by the first refresh. */
103
+ readonly refreshToken: string;
104
+ }
105
+ /** The `getAccessToken` of an OAuth {@link Credential}. */
106
+ type AccessTokenProvider = Extract<Credential, {
107
+ kind: "oauth";
108
+ }>["getAccessToken"];
109
+ /**
110
+ * Creates a `getAccessToken` that keeps an OAuth access token fresh by
111
+ * rotating one refresh token against the Roblox token endpoint. Use it as
112
+ * the `getAccessToken` of an OAuth `Credential`; you write the `identity`.
113
+ *
114
+ * Use one refresher per refresh token, in one process. A refresh token is
115
+ * single use, so two refreshers (or two processes) sharing one will spend it
116
+ * twice and lose the grant. Multi-instance consumers bring their own
117
+ * provider.
118
+ *
119
+ * - The first call refreshes. Later calls refresh when less than 120 s
120
+ * remain, measured on the local clock from receipt plus `expires_in`.
121
+ * - The new access token is used only after `onRotate` resolves. A spent
122
+ * refresh token is never sent again. If the saved access token then has
123
+ * less than 60 s left, it exchanges once more.
124
+ * - A network error, 5xx or 429 returns the current token while 60 s or
125
+ * more remain, and throws otherwise.
126
+ * - Each exchange has its own 30 s limit, for the request and the body
127
+ * read. A timeout is handled like a network error.
128
+ * - Any other non-2xx, or a 2xx without a usable token pair, throws a
129
+ * {@link TokenRefreshError}. After `invalid_grant` or such a 2xx, every
130
+ * call throws it again and sends nothing.
131
+ * - Concurrent calls share one exchange. A caller's `signal` stops only its
132
+ * own wait, never the exchange.
133
+ *
134
+ * @param options - The client, the refresh token and the rotation callback.
135
+ * @returns A `getAccessToken` for an OAuth `Credential`.
136
+ * @since 0.4.0
137
+ *
138
+ * @example
139
+ *
140
+ * ```ts
141
+ * import { createOAuthTokenRefresher, type Credential } from "@bedrock-rbx/ocale";
142
+ *
143
+ * let saved = "refresh-0";
144
+ * const getAccessToken = createOAuthTokenRefresher({
145
+ * clientId: "client-id",
146
+ * fetch: async () =>
147
+ * Response.json({ access_token: "access-1", expires_in: 900, refresh_token: "refresh-1" }),
148
+ * onRotate: (refreshToken) => {
149
+ * saved = refreshToken;
150
+ * },
151
+ * refreshToken: saved,
152
+ * });
153
+ * const credential: Credential = { getAccessToken, identity: "user-1", kind: "oauth" };
154
+ *
155
+ * expect(credential.kind).toBe("oauth");
156
+ * return getAccessToken({ signal: new AbortController().signal }).then((token) => {
157
+ * expect(token).toBe("access-1");
158
+ * expect(saved).toBe("refresh-1");
159
+ * });
160
+ * ```
161
+ */
162
+ export declare function createOAuthTokenRefresher(options: OAuthTokenRefresherOptions): (...args: Parameters<AccessTokenProvider>) => Promise<string>;
163
+ //#endregion
164
+ //#region src/errors/api-error.d.ts
165
+ /**
166
+ * Options for constructing an {@link ApiError}.
167
+ *
168
+ * @since 0.1.0
169
+ */
170
+ interface ApiErrorOptions extends OpenCloudErrorOptions {
171
+ /** Parsed response body, when present. */
172
+ details?: JSONValue | undefined;
173
+ /**
174
+ * Wall-clock time the request was in flight before this error, in
175
+ * milliseconds. Present for errors built by the transport; a long elapsed
176
+ * time on an intermittent failure points at a load or timeout correlation.
177
+ */
178
+ elapsedMs?: number | undefined;
179
+ /**
180
+ * Human-readable summary extracted from an HTML gateway error page, set
181
+ * when the error body was such a page (an HAProxy-style load-balancer
182
+ * rejection) rather than an Open Cloud response. When present, the raw HTML
183
+ * is not retained on {@link ApiError.details}.
184
+ */
185
+ gatewaySummary?: string | undefined;
186
+ /** HTTP method of the request that produced this error. */
187
+ method?: string | undefined;
188
+ /**
189
+ * Allowlisted response headers useful for diagnosis and escalation (request
190
+ * ids, edge/server identifiers). The full header set is never retained, to
191
+ * avoid surfacing anything sensitive and to keep errors light.
192
+ */
193
+ responseHeaders?: Readonly<Record<string, string>> | undefined;
194
+ /** HTTP status code from the API response. */
195
+ statusCode: number;
196
+ /**
197
+ * Length, in decoded characters, of a 2xx body that could not be parsed as
198
+ * JSON. Set only by the transport, and only for that failure — nothing else
199
+ * builds an {@link ApiError} over a successful status — so its presence is
200
+ * also how a body-parse failure is told apart from an API rejection. The
201
+ * number is the diagnostic one: a body that stops mid-token at exactly the
202
+ * length the edge delivered is a truncated read, not malformed JSON.
203
+ */
204
+ unparsedBodyLength?: number | undefined;
205
+ /** Fully-qualified URL of the request that produced this error. */
206
+ url?: string | undefined;
207
+ }
208
+ /**
209
+ * Everything in {@link ApiErrorOptions} except what the API answered ({@link
210
+ * ApiErrorOptions.code}, {@link ApiErrorOptions.details}, and {@link
211
+ * ApiErrorOptions.statusCode}): the request the transport made, how long it was
212
+ * in flight, and what the response carried alongside its body. Every field is
213
+ * required, and every one accepts `undefined` for a field the transport did not
214
+ * capture.
215
+ *
216
+ * @since 0.2.0
217
+ */
218
+ type ApiRequestContext = { [K in Exclude<keyof ApiErrorOptions, "cause" | "code" | "details" | "statusCode">]-?: ApiErrorOptions[K] | undefined; };
219
+ /**
220
+ * Thrown when the Roblox Open Cloud API returns a non-2xx response
221
+ * that is not a rate limit (429).
222
+ *
223
+ * @since 0.1.0
224
+ *
225
+ * @example
226
+ *
227
+ * ```ts
228
+ * import { ApiError } from "@bedrock-rbx/ocale";
229
+ *
230
+ * const error = new ApiError("HTTP 404: Pass not found (code NotFound)", {
231
+ * code: "NotFound",
232
+ * details: { errorCode: "NotFound", message: "Pass not found" },
233
+ * statusCode: 404,
234
+ * });
235
+ *
236
+ * expect(error).toBeInstanceOf(ApiError);
237
+ * expect(error.statusCode).toBe(404);
238
+ * expect(error.code).toBe("NotFound");
239
+ * expect(error.details).toEqual({
240
+ * errorCode: "NotFound",
241
+ * message: "Pass not found",
242
+ * });
243
+ * ```
244
+ */
245
+ export declare class ApiError extends OpenCloudError {
246
+ readonly details: JSONValue | undefined;
247
+ readonly elapsedMs: number | undefined;
248
+ readonly gatewaySummary: string | undefined;
249
+ readonly method: string | undefined;
250
+ override readonly name: string;
251
+ readonly responseHeaders: Readonly<Record<string, string>> | undefined;
252
+ readonly statusCode: number;
253
+ readonly unparsedBodyLength: number | undefined;
254
+ readonly url: string | undefined;
255
+ /**
256
+ * Creates a new ApiError.
257
+ *
258
+ * @param message - Human-readable error description.
259
+ * @param options - Error options including status code, optional error
260
+ * code, the parsed response body when present, and the request context
261
+ * (method, url, elapsed time, allowlisted response headers) when built by
262
+ * the transport.
263
+ */
264
+ constructor(message: string, options: ApiErrorOptions);
265
+ }
266
+ /**
267
+ * Reads the request context off an {@link ApiError} so a replacement error can
268
+ * carry it. Spread the result into the options of the new error. {@link
269
+ * OpenCloudError.code}, {@link ApiError.details}, and {@link
270
+ * ApiError.statusCode} describe the API's answer and are left to the caller.
271
+ *
272
+ * @since 0.2.0
273
+ *
274
+ * @param err - The error to read the request context from.
275
+ * @returns The transport-captured fields, each undefined when unset.
276
+ *
277
+ * @example
278
+ *
279
+ * ```ts
280
+ * import { ApiError, requestContextOf } from "@bedrock-rbx/ocale";
281
+ *
282
+ * const original = new ApiError("HTTP 404", {
283
+ * elapsedMs: 512,
284
+ * method: "GET",
285
+ * statusCode: 404,
286
+ * url: "https://apis.roblox.com/cloud/v2/universes/1",
287
+ * });
288
+ *
289
+ * const rewrapped = new ApiError("Universe 1 was not found; adoption failed", {
290
+ * ...requestContextOf(original),
291
+ * statusCode: 404,
292
+ * });
293
+ *
294
+ * expect(rewrapped.method).toBe("GET");
295
+ * expect(rewrapped.url).toBe("https://apis.roblox.com/cloud/v2/universes/1");
296
+ * expect(rewrapped.elapsedMs).toBe(512);
297
+ * ```
298
+ */
299
+ export declare function requestContextOf(err: ApiError): ApiRequestContext;
300
+ //#endregion
301
+ //#region src/errors/badge-cost-mismatch.d.ts
302
+ /**
303
+ * Options for constructing a {@link BadgeCostMismatchError}.
304
+ *
305
+ * @since 0.4.0
306
+ */
307
+ interface BadgeCostMismatchErrorOptions extends OpenCloudErrorOptions {
308
+ /** The `expectedCost` the create sent, or `undefined` when it sent none. */
309
+ readonly expectedCost: number | undefined;
310
+ /** HTTP status code of the refusal. */
311
+ readonly statusCode: number;
312
+ }
313
+ /**
314
+ * Returned when Roblox refuses a badge create because its `expectedCost`
315
+ * differs from what the badge would actually cost (body error code `18`).
316
+ * Nothing is charged. A create sent with `expectedCost: 0` gets this once the
317
+ * universe has used its free badge quota for the day. The upstream `ApiError`
318
+ * is the `cause`.
319
+ *
320
+ * @since 0.4.0
321
+ *
322
+ * @example
323
+ *
324
+ * ```ts
325
+ * import { BadgeCostMismatchError } from "@bedrock-rbx/ocale";
326
+ *
327
+ * const error = new BadgeCostMismatchError(
328
+ * "Expected badge cost is different from the actual badge cost.",
329
+ * { code: "18", expectedCost: 0, statusCode: 403 },
330
+ * );
331
+ *
332
+ * // A free create was refused: the free badge quota is spent for today.
333
+ * expect(error.expectedCost).toBe(0);
334
+ * expect(error.statusCode).toBe(403);
335
+ * ```
336
+ */
337
+ export declare class BadgeCostMismatchError extends OpenCloudError {
338
+ readonly expectedCost: number | undefined;
339
+ override readonly name: string;
340
+ readonly statusCode: number;
341
+ /**
342
+ * Creates a new BadgeCostMismatchError.
343
+ *
344
+ * @param message - Human-readable error description.
345
+ * @param options - Error options including the cost the create expected
346
+ * and the HTTP status of the refusal.
347
+ */
348
+ constructor(message: string, options: BadgeCostMismatchErrorOptions);
349
+ }
350
+ //#endregion
351
+ //#region src/errors/credential-error.d.ts
352
+ /**
353
+ * Options for constructing a {@link CredentialError}.
354
+ *
355
+ * @since 0.4.0
356
+ */
357
+ type CredentialErrorOptions = OpenCloudErrorOptions;
358
+ /**
359
+ * Returned when an OAuth credential's `getAccessToken` throws or rejects.
360
+ * The provider's error is the `cause`, passed through unchanged. The client
361
+ * sends no request for that attempt and spends no retry.
362
+ *
363
+ * @since 0.4.0
364
+ *
365
+ * @example
366
+ *
367
+ * ```ts
368
+ * import { CredentialError } from "@bedrock-rbx/ocale";
369
+ *
370
+ * const providerError = new Error("refresh token revoked");
371
+ * const error = new CredentialError("Credential provider failed", {
372
+ * cause: providerError,
373
+ * });
374
+ *
375
+ * expect(error).toBeInstanceOf(CredentialError);
376
+ * expect(error.cause).toBe(providerError);
377
+ * ```
378
+ */
379
+ export declare class CredentialError extends OpenCloudError {
380
+ override readonly name: string;
381
+ }
382
+ //#endregion
383
+ //#region src/errors/credential-not-supported.d.ts
384
+ /**
385
+ * Options for constructing a {@link CredentialNotSupportedError}.
386
+ *
387
+ * @since 0.4.0
388
+ */
389
+ interface CredentialNotSupportedErrorOptions extends OpenCloudErrorOptions {
390
+ /** Rate-limit key of the Operation that accepts only an API key. */
391
+ readonly operationKey: string;
392
+ }
393
+ /**
394
+ * Returned when an OAuth credential calls an Operation that Roblox accepts
395
+ * only with an API key (place publish and save, Luau execution and memory
396
+ * stores). The client returns it before it asks the provider for a token, and
397
+ * it sends no request.
398
+ *
399
+ * @since 0.4.0
400
+ *
401
+ * @example
402
+ *
403
+ * ```ts
404
+ * import { CredentialNotSupportedError } from "@bedrock-rbx/ocale";
405
+ *
406
+ * const error = new CredentialNotSupportedError("Operation needs an API key", {
407
+ * operationKey: "places.publishVersion",
408
+ * });
409
+ *
410
+ * expect(error).toBeInstanceOf(CredentialNotSupportedError);
411
+ * expect(error.operationKey).toBe("places.publishVersion");
412
+ * ```
413
+ */
414
+ export declare class CredentialNotSupportedError extends OpenCloudError {
415
+ override readonly name: string;
416
+ readonly operationKey: string;
417
+ /**
418
+ * Creates a new CredentialNotSupportedError.
419
+ *
420
+ * @param message - Human-readable description of the failure.
421
+ * @param options - Error options including the Operation's key.
422
+ */
423
+ constructor(message: string, options: CredentialNotSupportedErrorOptions);
424
+ }
425
+ //#endregion
426
+ //#region src/errors/credential-rejected.d.ts
427
+ /**
428
+ * Options for constructing a {@link CredentialRejectedError}.
429
+ *
430
+ * @since 0.4.0
431
+ */
432
+ interface CredentialRejectedErrorOptions extends OpenCloudErrorOptions {
433
+ /** The OAuth Credential identity whose token Roblox refused. */
434
+ readonly identity: string;
435
+ /** HTTP status code of the refusal (401 or 502). */
436
+ readonly statusCode: number;
437
+ }
438
+ /**
439
+ * Returned when Roblox refuses an OAuth Credential's token: a non-gateway
440
+ * 401, or a non-gateway 502 whose body message is "Scope authorization
441
+ * failed.". The grant is lost, so the client does not retry. Carries the
442
+ * Credential `identity` (never the token) so the caller can ask that user to
443
+ * consent again. The upstream `ApiError` is the `cause`.
444
+ *
445
+ * @since 0.4.0
446
+ *
447
+ * @example
448
+ *
449
+ * ```ts
450
+ * import { CredentialRejectedError } from "@bedrock-rbx/ocale";
451
+ *
452
+ * const error = new CredentialRejectedError("HTTP 401: Invalid Token.", {
453
+ * identity: "user-123",
454
+ * statusCode: 401,
455
+ * });
456
+ *
457
+ * expect(error.identity).toBe("user-123");
458
+ * expect(error.statusCode).toBe(401);
459
+ * ```
460
+ */
461
+ export declare class CredentialRejectedError extends OpenCloudError {
462
+ readonly identity: string;
463
+ override readonly name: string;
464
+ readonly statusCode: number;
465
+ /**
466
+ * Creates a new CredentialRejectedError.
467
+ *
468
+ * @param message - Human-readable error description.
469
+ * @param options - Error options including the Credential identity and
470
+ * the HTTP status of the refusal.
471
+ */
472
+ constructor(message: string, options: CredentialRejectedErrorOptions);
473
+ }
474
+ //#endregion
475
+ //#region src/errors/network-error.d.ts
476
+ /**
477
+ * Options for constructing a {@link NetworkError}.
478
+ *
479
+ * @since 0.1.0
480
+ */
481
+ interface NetworkErrorOptions extends ErrorOptions {
482
+ /** HTTP method of the request that failed. */
483
+ method?: string | undefined;
484
+ /** Fully-qualified URL of the request that failed. */
485
+ url?: string | undefined;
486
+ }
487
+ /**
488
+ * Thrown when a network-level failure prevents the request from reaching
489
+ * the Roblox Open Cloud API (e.g., DNS resolution failure, connection reset).
490
+ * The `method` and `url` name the failing call so a transport failure that
491
+ * survives every retry can be diagnosed; the underlying transport error is
492
+ * carried on `cause`.
493
+ *
494
+ * @since 0.1.0
495
+ */
496
+ export declare class NetworkError extends OpenCloudError {
497
+ readonly method: string | undefined;
498
+ override readonly name: string;
499
+ readonly url: string | undefined;
500
+ /**
501
+ * Creates a new NetworkError.
502
+ *
503
+ * @param message - Human-readable error description.
504
+ * @param options - Error options including the optional `cause` and the
505
+ * `method` / `url` of the request that failed.
506
+ */
507
+ constructor(message: string, options?: NetworkErrorOptions);
508
+ }
66
509
  //#endregion
67
510
  //#region src/errors/permission-error.d.ts
68
511
  /**
69
- * Options for constructing a {@link PermissionError}.
70
- *
71
- * @since 0.1.0
72
- */
512
+ * Options for constructing a {@link PermissionError}.
513
+ *
514
+ * @since 0.1.0
515
+ */
73
516
  interface PermissionErrorOptions extends ApiErrorOptions {
74
517
  /**
75
- * Stable identifier of the Open Cloud operation that returned the
76
- * permission failure (matches `OperationLimit.operationKey`, e.g.
77
- * `"developer-products.create"`).
78
- */
518
+ * Stable identifier of the Open Cloud operation that returned the
519
+ * permission failure (matches `OperationLimit.operationKey`, e.g.
520
+ * `"developer-products.create"`).
521
+ */
79
522
  operationKey: string;
80
523
  /**
81
- * Scope strings the API key or OAuth token must carry for the failing
82
- * operation, sourced from the vendored OpenAPI schema's `x-roblox-scopes`
83
- * for that operationId.
84
- */
524
+ * Scope strings the API key or OAuth token must carry for the failing
525
+ * operation, sourced from the vendored OpenAPI schema's `x-roblox-scopes`
526
+ * for that operationId.
527
+ */
85
528
  requiredScopes: ReadonlyArray<string>;
86
529
  }
87
530
  /**
88
- * Thrown when the Roblox Open Cloud API returns a 401 or 403 for an operation
89
- * whose required scopes are known. Subclass of {@link ApiError} carrying the
90
- * scope strings the operation requires plus the operation key, so a consumer
91
- * can name them when guiding the user to their API key settings.
92
- *
93
- * The scopes are what the operation needs, not a diagnosis of what the
94
- * credential lacks: a 403 does mean the scopes fall short, but Roblox also
95
- * answers 401 for a key that is invalid, disabled, or expired. Check
96
- * {@link ApiError.statusCode} before wording the failure as a missing scope.
97
- *
98
- * @since 0.1.0
99
- *
100
- * @example
101
- *
102
- * ```ts
103
- * import { PermissionError } from "@bedrock-rbx/ocale";
104
- *
105
- * const error = new PermissionError("HTTP 403", {
106
- * operationKey: "developer-products.create",
107
- * requiredScopes: ["creator-store-product:write"],
108
- * statusCode: 403,
109
- * });
110
- *
111
- * expect(error).toBeInstanceOf(PermissionError);
112
- * expect(error.requiredScopes).toStrictEqual(["creator-store-product:write"]);
113
- * expect(error.operationKey).toBe("developer-products.create");
114
- * ```
115
- */
116
- declare class PermissionError extends ApiError {
531
+ * Thrown when the Roblox Open Cloud API returns a 401 or 403 for an operation
532
+ * whose required scopes are known. Subclass of {@link ApiError} carrying the
533
+ * scope strings the operation requires plus the operation key, so a consumer
534
+ * can name them when guiding the user to their API key settings.
535
+ *
536
+ * The scopes are what the operation needs, not a diagnosis of what the
537
+ * credential lacks: a 403 does mean the scopes fall short, but Roblox also
538
+ * answers 401 for a key that is invalid, disabled, or expired. Check
539
+ * {@link ApiError.statusCode} before wording the failure as a missing scope.
540
+ *
541
+ * @since 0.1.0
542
+ *
543
+ * @example
544
+ *
545
+ * ```ts
546
+ * import { PermissionError } from "@bedrock-rbx/ocale";
547
+ *
548
+ * const error = new PermissionError("HTTP 403", {
549
+ * operationKey: "developer-products.create",
550
+ * requiredScopes: ["creator-store-product:write"],
551
+ * statusCode: 403,
552
+ * });
553
+ *
554
+ * expect(error).toBeInstanceOf(PermissionError);
555
+ * expect(error.requiredScopes).toStrictEqual(["creator-store-product:write"]);
556
+ * expect(error.operationKey).toBe("developer-products.create");
557
+ * ```
558
+ */
559
+ export declare class PermissionError extends ApiError {
117
560
  override readonly name: string;
118
561
  readonly operationKey: string;
119
562
  readonly requiredScopes: ReadonlyArray<string>;
120
563
  /**
121
- * Creates a new PermissionError.
122
- *
123
- * @param message - Human-readable error description.
124
- * @param options - Error options including status code, the operation key,
125
- * and the scopes the caller's credential must carry.
126
- */
564
+ * Creates a new PermissionError.
565
+ *
566
+ * @param message - Human-readable error description.
567
+ * @param options - Error options including status code, the operation key,
568
+ * and the scopes the caller's credential must carry.
569
+ */
127
570
  constructor(message: string, options: PermissionErrorOptions);
128
571
  }
129
572
  //#endregion
130
573
  //#region src/errors/poll-aborted.d.ts
131
574
  /**
132
- * Options for constructing a {@link PollAbortedError}.
133
- *
134
- * @since 0.1.0
135
- */
575
+ * Options for constructing a {@link PollAbortedError}.
576
+ *
577
+ * @since 0.1.0
578
+ */
136
579
  interface PollAbortedErrorOptions extends ErrorOptions {
137
580
  /** Whatever `AbortSignal.reason` was at the moment of abort. */
138
581
  readonly reason?: unknown;
139
582
  }
140
583
  /**
141
- * Returned when `pollUntilDone` is interrupted by an `AbortSignal` before
142
- * a terminal task state is reached. The `reason` field mirrors
143
- * `AbortSignal.reason` so callers can distinguish intentional cancellation
144
- * from unexpected abort sources.
145
- *
146
- * @since 0.1.0
147
- *
148
- * @example
149
- *
150
- * ```ts
151
- * import { PollAbortedError } from "@bedrock-rbx/ocale";
152
- *
153
- * const error = new PollAbortedError("polling was aborted", {
154
- * reason: "user cancelled",
155
- * });
156
- *
157
- * expect(error).toBeInstanceOf(PollAbortedError);
158
- * expect(error.reason).toBe("user cancelled");
159
- * ```
160
- */
161
- declare class PollAbortedError extends OpenCloudError {
584
+ * Returned when `pollUntilDone` is interrupted by an `AbortSignal` before
585
+ * a terminal task state is reached. The `reason` field mirrors
586
+ * `AbortSignal.reason` so callers can distinguish intentional cancellation
587
+ * from unexpected abort sources.
588
+ *
589
+ * @since 0.1.0
590
+ *
591
+ * @example
592
+ *
593
+ * ```ts
594
+ * import { PollAbortedError } from "@bedrock-rbx/ocale";
595
+ *
596
+ * const error = new PollAbortedError("polling was aborted", {
597
+ * reason: "user cancelled",
598
+ * });
599
+ *
600
+ * expect(error).toBeInstanceOf(PollAbortedError);
601
+ * expect(error.reason).toBe("user cancelled");
602
+ * ```
603
+ */
604
+ export declare class PollAbortedError extends OpenCloudError {
162
605
  override readonly name: string;
163
606
  readonly reason?: unknown;
164
607
  /**
165
- * Creates a new PollAbortedError.
166
- *
167
- * @param message - Human-readable description of the abort.
168
- * @param options - Error options including the abort reason.
169
- */
608
+ * Creates a new PollAbortedError.
609
+ *
610
+ * @param message - Human-readable description of the abort.
611
+ * @param options - Error options including the abort reason.
612
+ */
170
613
  constructor(message: string, options?: PollAbortedErrorOptions);
171
614
  }
172
615
  //#endregion
173
616
  //#region src/errors/poll-timeout.d.ts
174
617
  /**
175
- * Options for {@link PollTimeoutError}. The `T` type parameter captures the
176
- * resource-specific task variant the caller polled for; defaults to `unknown`
177
- * so the class can be reused by future Resources without forcing a parallel
178
- * hierarchy.
179
- *
180
- * @since 0.1.0
181
- *
182
- * @template T - Resource-specific task type being polled.
183
- */
618
+ * Options for {@link PollTimeoutError}. The `T` type parameter captures the
619
+ * resource-specific task variant the caller polled for; defaults to `unknown`
620
+ * so the class can be reused by future Resources without forcing a parallel
621
+ * hierarchy.
622
+ *
623
+ * @since 0.1.0
624
+ *
625
+ * @template T - Resource-specific task type being polled.
626
+ */
184
627
  interface PollTimeoutErrorOptions<T = unknown> extends ErrorOptions {
185
628
  /** Last task observed before the timeout budget was exhausted. */
186
629
  readonly lastObservedTask?: T | undefined;
@@ -188,90 +631,144 @@ interface PollTimeoutErrorOptions<T = unknown> extends ErrorOptions {
188
631
  readonly timeoutMs: number;
189
632
  }
190
633
  /**
191
- * Returned when `pollUntilDone` exhausts its wall-clock budget without
192
- * observing a terminal task state. Carries the last task polled so callers
193
- * can inspect state and decide whether to retry with a fresh budget.
194
- *
195
- * @since 0.1.0
196
- *
197
- * @template T - Resource-specific task type being polled.
198
- *
199
- * @example
200
- *
201
- * ```ts
202
- * import { PollTimeoutError } from "@bedrock-rbx/ocale";
203
- *
204
- * const error = new PollTimeoutError("polling timed out after 5 s", {
205
- * lastObservedTask: { state: "PROCESSING" as const },
206
- * timeoutMs: 5000,
207
- * });
208
- *
209
- * expect(error).toBeInstanceOf(PollTimeoutError);
210
- * expect(error.timeoutMs).toBe(5000);
211
- * expect(error.lastObservedTask).toStrictEqual({ state: "PROCESSING" });
212
- * ```
213
- */
214
- declare class PollTimeoutError<T = unknown> extends OpenCloudError {
634
+ * Returned when `pollUntilDone` exhausts its wall-clock budget without
635
+ * observing a terminal task state. Carries the last task polled so callers
636
+ * can inspect state and decide whether to retry with a fresh budget.
637
+ *
638
+ * @since 0.1.0
639
+ *
640
+ * @template T - Resource-specific task type being polled.
641
+ *
642
+ * @example
643
+ *
644
+ * ```ts
645
+ * import { PollTimeoutError } from "@bedrock-rbx/ocale";
646
+ *
647
+ * const error = new PollTimeoutError("polling timed out after 5 s", {
648
+ * lastObservedTask: { state: "PROCESSING" as const },
649
+ * timeoutMs: 5000,
650
+ * });
651
+ *
652
+ * expect(error).toBeInstanceOf(PollTimeoutError);
653
+ * expect(error.timeoutMs).toBe(5000);
654
+ * expect(error.lastObservedTask).toStrictEqual({ state: "PROCESSING" });
655
+ * ```
656
+ */
657
+ export declare class PollTimeoutError<T = unknown> extends OpenCloudError {
215
658
  readonly lastObservedTask: T | undefined;
216
659
  override readonly name: string;
217
660
  readonly timeoutMs: number;
218
661
  /**
219
- * Creates a new PollTimeoutError.
220
- *
221
- * @param message - Human-readable description of the timeout.
222
- * @param options - Error options including the budget and last-observed task.
223
- */
662
+ * Creates a new PollTimeoutError.
663
+ *
664
+ * @param message - Human-readable description of the timeout.
665
+ * @param options - Error options including the budget and last-observed task.
666
+ */
224
667
  constructor(message: string, options: PollTimeoutErrorOptions<T>);
225
668
  }
226
669
  //#endregion
670
+ //#region src/errors/rate-limit-wait-refused.d.ts
671
+ /**
672
+ * Options for constructing a {@link RateLimitWaitRefusedError}.
673
+ *
674
+ * @since 0.3.4
675
+ */
676
+ interface RateLimitWaitRefusedErrorOptions {
677
+ /** The 429 whose requested wait the SDK refused. */
678
+ readonly cause: RateLimitError;
679
+ }
680
+ /**
681
+ * Returned at once when a 429 asks for a wait longer than the 60 seconds the
682
+ * SDK waits out on its own. The server's requested wait is kept exactly as
683
+ * sent, alongside the 429's evidence, so a caller can schedule its own retry.
684
+ *
685
+ * Distinct from a {@link RateLimitError} returned after `maxRetries` runs out,
686
+ * and from a `RequestDeadlineExceededError`.
687
+ *
688
+ * @since 0.3.4
689
+ *
690
+ * @example
691
+ *
692
+ * ```ts
693
+ * import { RateLimitError, RateLimitWaitRefusedError } from "@bedrock-rbx/ocale";
694
+ *
695
+ * const error = new RateLimitWaitRefusedError("Rate limit asks for a 300s wait", {
696
+ * cause: new RateLimitError("Rate limited", { remaining: 0, retryAfterSeconds: 300 }),
697
+ * });
698
+ *
699
+ * expect(error.retryAfterSeconds).toBe(300);
700
+ * expect(error.remaining).toBe(0);
701
+ * ```
702
+ */
703
+ export declare class RateLimitWaitRefusedError extends OpenCloudError {
704
+ /** The 429 whose requested wait was refused. */
705
+ override readonly cause: RateLimitError;
706
+ override readonly name: string;
707
+ /** Requests left in the reported window, or `undefined` if not reported. */
708
+ readonly remaining: number | undefined;
709
+ /**
710
+ * Allowlisted raw response headers of the 429, or `undefined` if not set.
711
+ */
712
+ readonly responseHeaders: Readonly<Record<string, string>> | undefined;
713
+ /** The wait the server asked for, in seconds, uncapped. */
714
+ readonly retryAfterSeconds: number;
715
+ /**
716
+ * Creates a new RateLimitWaitRefusedError.
717
+ *
718
+ * @param message - Human-readable description of the refused wait.
719
+ * @param options - The 429 whose requested wait was refused.
720
+ */
721
+ constructor(message: string, { cause }: RateLimitWaitRefusedErrorOptions);
722
+ }
723
+ //#endregion
227
724
  //#region src/errors/request-aborted.d.ts
228
725
  /**
229
- * Options for constructing a {@link RequestAbortedError}.
230
- *
231
- * @since 0.3.1
232
- */
726
+ * Options for constructing a {@link RequestAbortedError}.
727
+ *
728
+ * @since 0.3.1
729
+ */
233
730
  interface RequestAbortedErrorOptions extends ErrorOptions {
234
731
  /** Whatever `AbortSignal.reason` was at the moment of cancellation. */
235
732
  readonly reason?: unknown;
236
733
  }
237
734
  /**
238
- * Returned when a caller's `AbortSignal` cancels an Open Cloud request.
239
- * The reason is preserved so intentional cancellation can be distinguished
240
- * from transport failures and SDK-owned request timeouts.
241
- *
242
- * @since 0.3.1
243
- *
244
- * @example
245
- *
246
- * ```ts
247
- * import { RequestAbortedError } from "@bedrock-rbx/ocale";
248
- *
249
- * const error = new RequestAbortedError("Request was aborted", {
250
- * reason: "superseded",
251
- * });
252
- *
253
- * expect(error).toBeInstanceOf(RequestAbortedError);
254
- * expect(error.reason).toBe("superseded");
255
- * ```
256
- */
257
- declare class RequestAbortedError extends OpenCloudError {
735
+ * Returned when a caller's `AbortSignal` cancels an Open Cloud request.
736
+ * The reason is preserved so intentional cancellation can be distinguished
737
+ * from transport failures and SDK-owned request timeouts.
738
+ *
739
+ * @since 0.3.1
740
+ *
741
+ * @example
742
+ *
743
+ * ```ts
744
+ * import { RequestAbortedError } from "@bedrock-rbx/ocale";
745
+ *
746
+ * const error = new RequestAbortedError("Request was aborted", {
747
+ * reason: "superseded",
748
+ * });
749
+ *
750
+ * expect(error).toBeInstanceOf(RequestAbortedError);
751
+ * expect(error.reason).toBe("superseded");
752
+ * ```
753
+ */
754
+ export declare class RequestAbortedError extends OpenCloudError {
258
755
  override readonly name: string;
259
756
  readonly reason?: unknown;
260
757
  /**
261
- * Creates a new RequestAbortedError.
262
- *
263
- * @param message - Human-readable description of the cancellation.
264
- * @param options - Error options including the caller's abort reason.
265
- */
758
+ * Creates a new RequestAbortedError.
759
+ *
760
+ * @param message - Human-readable description of the cancellation.
761
+ * @param options - Error options including the caller's abort reason.
762
+ */
266
763
  constructor(message: string, options?: RequestAbortedErrorOptions);
267
764
  }
268
765
  //#endregion
269
766
  //#region src/errors/request-deadline-exceeded.d.ts
270
767
  /**
271
- * Options for constructing a {@link RequestDeadlineExceededError}.
272
- *
273
- * @since 0.3.2
274
- */
768
+ * Options for constructing a {@link RequestDeadlineExceededError}.
769
+ *
770
+ * @since 0.3.2
771
+ */
275
772
  interface RequestDeadlineExceededErrorOptions extends ErrorOptions {
276
773
  /** Absolute caller-supplied deadline, as Unix epoch milliseconds. */
277
774
  readonly deadlineMs: number;
@@ -283,29 +780,29 @@ interface RequestDeadlineExceededErrorOptions extends ErrorOptions {
283
780
  readonly waitReason?: AdmissionWaitReason | undefined;
284
781
  }
285
782
  /**
286
- * Returned when a logical request cannot complete by its absolute deadline.
287
- * Optional wait details identify an SDK-managed admission wait that was
288
- * refused. This is distinct from caller cancellation so consumers can report
289
- * exhausted wall-clock budget accurately.
290
- *
291
- * @since 0.3.2
292
- *
293
- * @example
294
- *
295
- * ```ts
296
- * import { RequestDeadlineExceededError } from "@bedrock-rbx/ocale";
297
- *
298
- * const error = new RequestDeadlineExceededError("Request deadline elapsed", {
299
- * deadlineMs: 1_000_000,
300
- * remainingMs: 0,
301
- * waitReason: "operation-queue",
302
- * });
303
- *
304
- * expect(error.remainingMs).toBe(0);
305
- * expect(error.waitReason).toBe("operation-queue");
306
- * ```
307
- */
308
- declare class RequestDeadlineExceededError extends OpenCloudError {
783
+ * Returned when a logical request cannot complete by its absolute deadline.
784
+ * Optional wait details identify an SDK-managed admission wait that was
785
+ * refused. This is distinct from caller cancellation so consumers can report
786
+ * exhausted wall-clock budget accurately.
787
+ *
788
+ * @since 0.3.2
789
+ *
790
+ * @example
791
+ *
792
+ * ```ts
793
+ * import { RequestDeadlineExceededError } from "@bedrock-rbx/ocale";
794
+ *
795
+ * const error = new RequestDeadlineExceededError("Request deadline elapsed", {
796
+ * deadlineMs: 1_000_000,
797
+ * remainingMs: 0,
798
+ * waitReason: "operation-queue",
799
+ * });
800
+ *
801
+ * expect(error.remainingMs).toBe(0);
802
+ * expect(error.waitReason).toBe("operation-queue");
803
+ * ```
804
+ */
805
+ export declare class RequestDeadlineExceededError extends OpenCloudError {
309
806
  /** Absolute caller-supplied deadline, as Unix epoch milliseconds. */
310
807
  readonly deadlineMs: number;
311
808
  override readonly name: string;
@@ -316,20 +813,20 @@ declare class RequestDeadlineExceededError extends OpenCloudError {
316
813
  /** SDK admission mechanism whose wait could not meet the deadline. */
317
814
  readonly waitReason: AdmissionWaitReason | undefined;
318
815
  /**
319
- * Creates a new RequestDeadlineExceededError.
320
- *
321
- * @param message - Human-readable description of the exhausted deadline.
322
- * @param options - Deadline, remaining budget, and optional wait details.
323
- */
816
+ * Creates a new RequestDeadlineExceededError.
817
+ *
818
+ * @param message - Human-readable description of the exhausted deadline.
819
+ * @param options - Deadline, remaining budget, and optional wait details.
820
+ */
324
821
  constructor(message: string, options: RequestDeadlineExceededErrorOptions);
325
822
  }
326
823
  //#endregion
327
824
  //#region src/errors/retry-delay-exceeded.d.ts
328
825
  /**
329
- * Options for constructing a {@link RetryDelayExceededError}.
330
- *
331
- * @since 0.3.2
332
- */
826
+ * Options for constructing a {@link RetryDelayExceededError}.
827
+ *
828
+ * @since 0.3.2
829
+ */
333
830
  interface RetryDelayExceededErrorOptions extends ErrorOptions {
334
831
  /** Absolute caller-supplied deadline, as Unix epoch milliseconds. */
335
832
  readonly deadlineMs: number;
@@ -339,91 +836,212 @@ interface RetryDelayExceededErrorOptions extends ErrorOptions {
339
836
  readonly retryAfterMs: number;
340
837
  }
341
838
  /**
342
- * Returned when the SDK refuses a retry delay that cannot complete before the
343
- * request deadline. This is distinct from cancellation so consumers can
344
- * report the server's stated retry time without waiting for it.
345
- *
346
- * @since 0.3.2
347
- *
348
- * @example
349
- *
350
- * ```ts
351
- * import { RetryDelayExceededError } from "@bedrock-rbx/ocale";
352
- *
353
- * const error = new RetryDelayExceededError("Retry delay exceeds the request deadline", {
354
- * deadlineMs: 1_000_000,
355
- * remainingMs: 495_000,
356
- * retryAfterMs: 1_856_000,
357
- * });
358
- *
359
- * expect(error.retryAfterMs).toBe(1_856_000);
360
- * expect(error.remainingMs).toBe(495_000);
361
- * ```
362
- */
363
- declare class RetryDelayExceededError extends RequestDeadlineExceededError {
839
+ * Returned when the SDK refuses a retry delay that cannot complete before the
840
+ * request deadline. This is distinct from cancellation so consumers can
841
+ * report the server's stated retry time without waiting for it.
842
+ *
843
+ * @since 0.3.2
844
+ *
845
+ * @example
846
+ *
847
+ * ```ts
848
+ * import { RetryDelayExceededError } from "@bedrock-rbx/ocale";
849
+ *
850
+ * const error = new RetryDelayExceededError("Retry delay exceeds the request deadline", {
851
+ * deadlineMs: 1_000_000,
852
+ * remainingMs: 495_000,
853
+ * retryAfterMs: 1_856_000,
854
+ * });
855
+ *
856
+ * expect(error.retryAfterMs).toBe(1_856_000);
857
+ * expect(error.remainingMs).toBe(495_000);
858
+ * ```
859
+ */
860
+ export declare class RetryDelayExceededError extends RequestDeadlineExceededError {
364
861
  override readonly name: string;
365
862
  /** Computed retry delay refused by the SDK, in milliseconds. */
366
863
  readonly retryAfterMs: number;
367
864
  /** Computed retry delay refused by the SDK, in seconds. */
368
865
  readonly retryAfterSeconds: number;
369
866
  /**
370
- * Creates a new RetryDelayExceededError.
371
- *
372
- * @param message - Human-readable description of the refused retry delay.
373
- * @param options - Refused delay, deadline budget, and original failure.
374
- */
867
+ * Creates a new RetryDelayExceededError.
868
+ *
869
+ * @param message - Human-readable description of the refused retry delay.
870
+ * @param options - Refused delay, deadline budget, and original failure.
871
+ */
375
872
  constructor(message: string, options: RetryDelayExceededErrorOptions);
376
873
  }
377
874
  //#endregion
875
+ //#region src/errors/token-refresh-error.d.ts
876
+ /**
877
+ * Options for constructing a {@link TokenRefreshError}.
878
+ *
879
+ * @since 0.4.0
880
+ */
881
+ interface TokenRefreshErrorOptions extends OpenCloudErrorOptions {
882
+ /** HTTP status of the token endpoint's response. */
883
+ readonly statusCode: number;
884
+ }
885
+ /**
886
+ * Thrown by the `getAccessToken` that `createOAuthTokenRefresher` returns
887
+ * when the Roblox token endpoint refuses a refresh. `code` is the OAuth
888
+ * `error` field of the response body (for example `invalid_grant`), or
889
+ * `undefined` when the body has none. A client that calls the provider
890
+ * returns it as the `cause` of a `CredentialError`.
891
+ *
892
+ * @since 0.4.0
893
+ *
894
+ * @example
895
+ *
896
+ * ```ts
897
+ * import { TokenRefreshError } from "@bedrock-rbx/ocale";
898
+ *
899
+ * const error = new TokenRefreshError("Token refresh refused", {
900
+ * code: "invalid_grant",
901
+ * statusCode: 400,
902
+ * });
903
+ *
904
+ * expect(error.code).toBe("invalid_grant");
905
+ * expect(error.statusCode).toBe(400);
906
+ * ```
907
+ */
908
+ export declare class TokenRefreshError extends OpenCloudError {
909
+ override readonly name: string;
910
+ /** HTTP status of the token endpoint's response. */
911
+ readonly statusCode: number;
912
+ /**
913
+ * Creates a new TokenRefreshError.
914
+ *
915
+ * @param message - Human-readable error description.
916
+ * @param options - The OAuth error code and the HTTP status.
917
+ */
918
+ constructor(message: string, options: TokenRefreshErrorOptions);
919
+ }
920
+ //#endregion
921
+ //#region src/errors/unexpected-response.d.ts
922
+ /**
923
+ * Options for constructing an {@link UnexpectedResponseError}.
924
+ *
925
+ * @since 0.4.0
926
+ */
927
+ interface UnexpectedResponseErrorOptions extends OpenCloudErrorOptions {
928
+ /** The response body that did not match, when it was JSON or text. */
929
+ details?: JSONValue | undefined;
930
+ /** HTTP method of the request whose response did not match. */
931
+ method?: string | undefined;
932
+ /**
933
+ * End the message with a line that links to {@link
934
+ * UnexpectedResponseError.reportUrl}.
935
+ */
936
+ reportHint?: boolean | undefined;
937
+ /**
938
+ * Allowlisted response headers useful for diagnosis and escalation
939
+ * (request ids, edge/server identifiers), as on `ApiError.responseHeaders`.
940
+ */
941
+ responseHeaders?: Readonly<Record<string, string>> | undefined;
942
+ /** HTTP status code of the response that did not match. */
943
+ statusCode: number;
944
+ /** Fully-qualified URL of the request whose response did not match. */
945
+ url?: string | undefined;
946
+ }
947
+ /**
948
+ * Returned when Open Cloud accepts a request and answers, but the response
949
+ * body has a shape that ocale's wire model rejects. The API did not refuse the
950
+ * request, so this is not an `ApiError`: the fault is more likely a stale wire
951
+ * model or a parser bug in ocale than a problem with the caller's input. The
952
+ * raw body is kept on `details`, with the request context, so the mismatch can
953
+ * be reported. `reportUrl` opens an ocale bug report prefilled with the
954
+ * message, status, and failing call. It leaves out the body, which can hold
955
+ * private data.
956
+ *
957
+ * @since 0.4.0
958
+ *
959
+ * @example
960
+ *
961
+ * ```ts
962
+ * import { ApiError, UnexpectedResponseError } from "@bedrock-rbx/ocale";
963
+ *
964
+ * const error = new UnexpectedResponseError("Malformed badge response", {
965
+ * details: { id: "not-a-number" },
966
+ * method: "GET",
967
+ * statusCode: 200,
968
+ * url: "https://apis.roblox.com/legacy-badges/v1/badges/1",
969
+ * });
970
+ *
971
+ * // A shape mismatch is not an API rejection.
972
+ * expect(error).not.toBeInstanceOf(ApiError);
973
+ * expect(error.details).toStrictEqual({ id: "not-a-number" });
974
+ * ```
975
+ */
976
+ export declare class UnexpectedResponseError extends OpenCloudError {
977
+ readonly details: JSONValue | undefined;
978
+ readonly method: string | undefined;
979
+ override readonly name: string;
980
+ /** Link to a new ocale bug report, prefilled with this failure. */
981
+ readonly reportUrl: string;
982
+ readonly responseHeaders: Readonly<Record<string, string>> | undefined;
983
+ readonly statusCode: number;
984
+ readonly url: string | undefined;
985
+ /**
986
+ * Creates a new UnexpectedResponseError.
987
+ *
988
+ * @param message - Human-readable description naming the response that
989
+ * did not match.
990
+ * @param options - The status code, the raw body as `details`, and the
991
+ * request context when known.
992
+ */
993
+ constructor(message: string, options: UnexpectedResponseErrorOptions);
994
+ }
995
+ //#endregion
378
996
  //#region src/errors/validation.d.ts
379
997
  /**
380
- * Closed discriminator for a {@link ValidationError}. Consumers can
381
- * exhaustively `switch` over this union so TypeScript will refuse to compile
382
- * if a new variant is added without a handler.
383
- *
384
- * @since 0.1.0
385
- */
998
+ * Closed discriminator for a {@link ValidationError}. Consumers can
999
+ * exhaustively `switch` over this union so TypeScript will refuse to compile
1000
+ * if a new variant is added without a handler.
1001
+ *
1002
+ * @since 0.1.0
1003
+ */
386
1004
  type ValidationErrorCode = "empty_body" | "empty_image_ids" | "empty_place_ids" | "empty_update" | "format_mismatch" | "incomplete_ref" | "invalid_image_id" | "invalid_place_id";
387
1005
  /**
388
- * Options for constructing a {@link ValidationError}.
389
- *
390
- * @since 0.1.0
391
- */
1006
+ * Options for constructing a {@link ValidationError}.
1007
+ *
1008
+ * @since 0.1.0
1009
+ */
392
1010
  interface ValidationErrorOptions extends ErrorOptions {
393
1011
  /** Machine-readable discriminator identifying the validation failure. */
394
1012
  code: ValidationErrorCode;
395
1013
  }
396
1014
  /**
397
- * Thrown locally when caller-supplied input is rejected before any HTTP
398
- * round-trip. The `code` discriminator lets consumers branch on local-input
399
- * errors separately from server-side errors.
400
- *
401
- * @since 0.1.0
402
- *
403
- * @example
404
- *
405
- * ```ts
406
- * import { ValidationError } from "@bedrock-rbx/ocale";
407
- *
408
- * const error = new ValidationError("Place body is empty", {
409
- * code: "empty_body",
410
- * });
411
- *
412
- * expect(error).toBeInstanceOf(ValidationError);
413
- * expect(error.code).toBe("empty_body");
414
- * ```
415
- */
416
- declare class ValidationError extends OpenCloudError {
1015
+ * Thrown locally when caller-supplied input is rejected before any HTTP
1016
+ * round-trip. The `code` discriminator lets consumers branch on local-input
1017
+ * errors separately from server-side errors.
1018
+ *
1019
+ * @since 0.1.0
1020
+ *
1021
+ * @example
1022
+ *
1023
+ * ```ts
1024
+ * import { ValidationError } from "@bedrock-rbx/ocale";
1025
+ *
1026
+ * const error = new ValidationError("Place body is empty", {
1027
+ * code: "empty_body",
1028
+ * });
1029
+ *
1030
+ * expect(error).toBeInstanceOf(ValidationError);
1031
+ * expect(error.code).toBe("empty_body");
1032
+ * ```
1033
+ */
1034
+ export declare class ValidationError extends OpenCloudError {
417
1035
  override readonly code: ValidationErrorCode;
418
1036
  override readonly name: string;
419
1037
  /**
420
- * Creates a new ValidationError.
421
- *
422
- * @param message - Human-readable error description.
423
- * @param options - Error options including the validation failure code.
424
- */
1038
+ * Creates a new ValidationError.
1039
+ *
1040
+ * @param message - Human-readable error description.
1041
+ * @param options - Error options including the validation failure code.
1042
+ */
425
1043
  constructor(message: string, options: ValidationErrorOptions);
426
1044
  }
427
1045
  //#endregion
428
- export { type AdmissionWaitEvent, type AdmissionWaitObserver, type AdmissionWaitReason, ApiError, type ApiErrorOptions, type ApiRequestContext, GATEWAY_REJECTED, type HttpClient, type HttpRequest, type HttpResponse, NetworkError, type NetworkErrorOptions, type OpenCloudClientOptions, OpenCloudError, type OpenCloudErrorOptions, type OpenCloudHooks, type Page, PermissionError, type PermissionErrorOptions, PollAbortedError, type PollAbortedErrorOptions, PollTimeoutError, type PollTimeoutErrorOptions, RESPONSE_UNPARSEABLE, RateLimitError, type RateLimitErrorOptions, RequestAbortedError, type RequestAbortedErrorOptions, type RequestConfig, RequestDeadlineExceededError, type RequestDeadlineExceededErrorOptions, type RequestOptions, type Result, RetryDelayExceededError, type RetryDelayExceededErrorOptions, type SleepFunc, TRANSIENT_TRANSPORT_CODES, ValidationError, type ValidationErrorCode, type ValidationErrorOptions, createFetchHttpClient, requestContextOf };
1046
+ export { type AdmissionWaitEvent, type AdmissionWaitObserver, type AdmissionWaitReason, type ApiErrorOptions, type ApiRequestContext, type BadgeCostMismatchErrorOptions, type Credential, type CredentialErrorOptions, type CredentialNotSupportedErrorOptions, type CredentialRejectedErrorOptions, GATEWAY_REJECTED, type HttpClient, type HttpRequest, type HttpResponse, type NetworkErrorOptions, type OAuthTokenRefresherOptions, type OpenCloudClientOptions, OpenCloudError, type OpenCloudErrorOptions, type OpenCloudHooks, type Page, type PermissionErrorOptions, type PollAbortedErrorOptions, type PollTimeoutErrorOptions, RESPONSE_UNPARSEABLE, RateLimitError, type RateLimitErrorOptions, type RateLimitSource, type RateLimitWaitRefusedErrorOptions, type RequestAbortedErrorOptions, type RequestConfig, type RequestDeadlineExceededErrorOptions, type RequestOptions, type ResolvedCredential, type Result, type RetryDelayExceededErrorOptions, type SleepFunc, TRANSIENT_TRANSPORT_CODES, type TokenRefreshErrorOptions, type UnexpectedResponseErrorOptions, type ValidationErrorCode, type ValidationErrorOptions };
429
1047
  //# sourceMappingURL=index.d.mts.map