@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.
- package/README.md +9 -5
- package/dist/badge-cost-mismatch-DrlvhlQc.mjs +47 -0
- package/dist/badge-cost-mismatch-DrlvhlQc.mjs.map +1 -0
- package/dist/badges.d.mts +228 -184
- package/dist/badges.d.mts.map +1 -1
- package/dist/badges.mjs +176 -18
- package/dist/badges.mjs.map +1 -1
- package/dist/capacity-admission-hycCFkTo.d.mts +355 -0
- package/dist/capacity-admission-hycCFkTo.d.mts.map +1 -0
- package/dist/{data.generated-B2ceLfSn.d.mts → data.generated-D_vpa5-g.d.mts} +23 -23
- package/dist/data.generated-D_vpa5-g.d.mts.map +1 -0
- package/dist/developer-products.d.mts +181 -186
- package/dist/developer-products.d.mts.map +1 -1
- package/dist/developer-products.mjs +24 -24
- package/dist/developer-products.mjs.map +1 -1
- package/dist/game-passes.d.mts +206 -203
- package/dist/game-passes.d.mts.map +1 -1
- package/dist/game-passes.mjs +26 -21
- package/dist/game-passes.mjs.map +1 -1
- package/dist/index.d.mts +924 -306
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +325 -10
- package/dist/index.mjs.map +1 -1
- package/dist/locales.d.mts +30 -2
- package/dist/locales.d.mts.map +1 -0
- package/dist/locales.mjs +24 -1
- package/dist/locales.mjs.map +1 -1
- package/dist/luau-execution.d.mts +154 -151
- package/dist/luau-execution.d.mts.map +1 -1
- package/dist/luau-execution.mjs +11 -8
- package/dist/luau-execution.mjs.map +1 -1
- package/dist/{network-error-DR9FX5hb.mjs → network-error-iVSng5MT.mjs} +44 -6
- package/dist/network-error-iVSng5MT.mjs.map +1 -0
- package/dist/places.d.mts +204 -180
- package/dist/places.d.mts.map +1 -1
- package/dist/places.mjs +66 -20
- package/dist/places.mjs.map +1 -1
- package/dist/{poll-timeout-3PXLsabj.mjs → poll-timeout-DzztDymd.mjs} +2 -2
- package/dist/{poll-timeout-3PXLsabj.mjs.map → poll-timeout-DzztDymd.mjs.map} +1 -1
- package/dist/{polling-helpers-sKTsqEc1.mjs → polling-helpers-DfF5dspc.mjs} +249 -83
- package/dist/polling-helpers-DfF5dspc.mjs.map +1 -0
- package/dist/{price-information-hWXV6DAI.mjs → price-information-DEkEQ8Pq.mjs} +2 -2
- package/dist/{price-information-hWXV6DAI.mjs.map → price-information-DEkEQ8Pq.mjs.map} +1 -1
- package/dist/resource-client-BCKukheG.d.mts +168 -0
- package/dist/resource-client-BCKukheG.d.mts.map +1 -0
- package/dist/resource-client-CaIVr-go.mjs +1419 -0
- package/dist/resource-client-CaIVr-go.mjs.map +1 -0
- package/dist/retry-C2oHesDx.d.mts +229 -0
- package/dist/retry-C2oHesDx.d.mts.map +1 -0
- package/dist/{retry-vpHMIwaU.mjs → retry-CMRDvAR4.mjs} +390 -20
- package/dist/retry-CMRDvAR4.mjs.map +1 -0
- package/dist/storage.d.mts +333 -334
- package/dist/storage.d.mts.map +1 -1
- package/dist/storage.mjs +29 -22
- package/dist/storage.mjs.map +1 -1
- package/dist/testing.d.mts +347 -360
- package/dist/testing.d.mts.map +1 -1
- package/dist/testing.mjs +3 -4
- package/dist/testing.mjs.map +1 -1
- package/dist/types-CdMr_J1M.d.mts +509 -0
- package/dist/types-CdMr_J1M.d.mts.map +1 -0
- package/dist/universes.d.mts +619 -422
- package/dist/universes.d.mts.map +1 -1
- package/dist/universes.mjs +421 -48
- package/dist/universes.mjs.map +1 -1
- package/dist/{validation-B_Zs1So2.mjs → validation-964VNlbp.mjs} +2 -2
- package/dist/{validation-B_Zs1So2.mjs.map → validation-964VNlbp.mjs.map} +1 -1
- package/dist/wire-DJqupefn.d.mts +41 -0
- package/dist/wire-DJqupefn.d.mts.map +1 -0
- package/package.json +14 -14
- package/dist/capacity-admission-BvnJjY0S.d.mts +0 -369
- package/dist/capacity-admission-BvnJjY0S.d.mts.map +0 -1
- package/dist/data.generated-B2ceLfSn.d.mts.map +0 -1
- package/dist/network-error-DR9FX5hb.mjs.map +0 -1
- package/dist/polling-helpers-sKTsqEc1.mjs.map +0 -1
- package/dist/resource-client-3cOhqZpX.mjs +0 -899
- package/dist/resource-client-3cOhqZpX.mjs.map +0 -1
- package/dist/resource-client-BivRq3JZ.d.mts +0 -164
- package/dist/resource-client-BivRq3JZ.d.mts.map +0 -1
- package/dist/retry-DXEklFrt.d.mts +0 -373
- package/dist/retry-DXEklFrt.d.mts.map +0 -1
- package/dist/retry-vpHMIwaU.mjs.map +0 -1
- package/dist/types-C3Egi37J.d.mts +0 -378
- package/dist/types-C3Egi37J.d.mts.map +0 -1
- package/dist/wire-D3K-a-UP.d.mts +0 -37
- 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
|
|
2
|
-
import { a as TRANSIENT_TRANSPORT_CODES, c as
|
|
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
|
-
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
* @
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
19
|
-
*
|
|
20
|
-
*
|
|
21
|
-
*
|
|
22
|
-
*
|
|
23
|
-
* import {
|
|
24
|
-
*
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
*
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
33
|
-
*
|
|
34
|
-
*
|
|
35
|
-
*
|
|
36
|
-
*
|
|
37
|
-
*
|
|
38
|
-
*
|
|
39
|
-
* const
|
|
40
|
-
*
|
|
41
|
-
*
|
|
42
|
-
*
|
|
43
|
-
*
|
|
44
|
-
*
|
|
45
|
-
*
|
|
46
|
-
* }
|
|
47
|
-
*
|
|
48
|
-
*
|
|
49
|
-
*
|
|
50
|
-
*
|
|
51
|
-
*
|
|
52
|
-
*
|
|
53
|
-
*
|
|
54
|
-
*
|
|
55
|
-
*
|
|
56
|
-
*
|
|
57
|
-
*
|
|
58
|
-
*
|
|
59
|
-
*
|
|
60
|
-
*
|
|
61
|
-
*
|
|
62
|
-
*
|
|
63
|
-
*
|
|
64
|
-
|
|
65
|
-
|
|
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
|
-
|
|
76
|
-
|
|
77
|
-
|
|
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
|
-
|
|
82
|
-
|
|
83
|
-
|
|
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
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
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
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
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
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
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
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
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
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
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
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
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
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
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,
|
|
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
|