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