@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.
- package/README.md +10 -5
- package/dist/assets.d.mts +64 -0
- package/dist/assets.d.mts.map +1 -0
- package/dist/assets.mjs +301 -0
- package/dist/assets.mjs.map +1 -0
- package/dist/badge-insufficient-funds-BLFvQZt1.mjs +91 -0
- package/dist/badge-insufficient-funds-BLFvQZt1.mjs.map +1 -0
- package/dist/badges.d.mts +359 -196
- package/dist/badges.d.mts.map +1 -1
- package/dist/badges.mjs +493 -59
- package/dist/badges.mjs.map +1 -1
- package/dist/capacity-admission-Ce2V9QNb.d.mts +347 -0
- package/dist/capacity-admission-Ce2V9QNb.d.mts.map +1 -0
- package/dist/{data.generated-B2ceLfSn.d.mts → data.generated-B4Fztv_7.d.mts} +23 -25
- package/dist/data.generated-B4Fztv_7.d.mts.map +1 -0
- package/dist/developer-products.d.mts +207 -194
- package/dist/developer-products.d.mts.map +1 -1
- package/dist/developer-products.mjs +125 -39
- package/dist/developer-products.mjs.map +1 -1
- package/dist/game-passes.d.mts +206 -211
- package/dist/game-passes.d.mts.map +1 -1
- package/dist/game-passes.mjs +35 -36
- package/dist/game-passes.mjs.map +1 -1
- package/dist/index.d.mts +947 -366
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +324 -12
- package/dist/index.mjs.map +1 -1
- package/dist/is-date-time-string-C91G44SI.mjs +19 -0
- package/dist/is-date-time-string-C91G44SI.mjs.map +1 -0
- package/dist/locales.d.mts +28 -2
- package/dist/locales.d.mts.map +1 -0
- package/dist/locales.mjs +24 -3
- package/dist/locales.mjs.map +1 -1
- package/dist/luau-execution.d.mts +154 -157
- package/dist/luau-execution.d.mts.map +1 -1
- package/dist/luau-execution.mjs +15 -16
- package/dist/luau-execution.mjs.map +1 -1
- package/dist/{network-error-DR9FX5hb.mjs → network-error-P4An7nUB.mjs} +48 -14
- package/dist/network-error-P4An7nUB.mjs.map +1 -0
- package/dist/places.d.mts +258 -186
- package/dist/places.d.mts.map +1 -1
- package/dist/places.mjs +187 -35
- package/dist/places.mjs.map +1 -1
- package/dist/{poll-timeout-3PXLsabj.mjs → poll-timeout-BCxgN97O.mjs} +4 -6
- package/dist/{poll-timeout-3PXLsabj.mjs.map → poll-timeout-BCxgN97O.mjs.map} +1 -1
- package/dist/{polling-helpers-CoVhsC33.mjs → polling-helpers-BtEYR5dN.mjs} +260 -105
- package/dist/polling-helpers-BtEYR5dN.mjs.map +1 -0
- package/dist/{price-information-B0tkOoAX.mjs → price-information--d6GZAcp.mjs} +3 -4
- package/dist/{price-information-B0tkOoAX.mjs.map → price-information--d6GZAcp.mjs.map} +1 -1
- package/dist/resource-client-CF8SPsV8.d.mts +162 -0
- package/dist/resource-client-CF8SPsV8.d.mts.map +1 -0
- package/dist/{resource-client-rqTMkBeR.mjs → resource-client-Cm_bPcCs.mjs} +589 -197
- package/dist/resource-client-Cm_bPcCs.mjs.map +1 -0
- package/dist/retry-DYxm_eBU.d.mts +225 -0
- package/dist/retry-DYxm_eBU.d.mts.map +1 -0
- package/dist/{retry-BlX4tUnT.mjs → retry-Dv5TsY9O.mjs} +312 -54
- package/dist/retry-Dv5TsY9O.mjs.map +1 -0
- package/dist/{signatures-JF-7Psce.mjs → signatures-CtJ7jfVN.mjs} +2 -3
- package/dist/{signatures-JF-7Psce.mjs.map → signatures-CtJ7jfVN.mjs.map} +1 -1
- package/dist/storage.d.mts +333 -344
- package/dist/storage.d.mts.map +1 -1
- package/dist/storage.mjs +39 -40
- package/dist/storage.mjs.map +1 -1
- package/dist/testing.d.mts +369 -434
- package/dist/testing.d.mts.map +1 -1
- package/dist/testing.mjs +18 -33
- package/dist/testing.mjs.map +1 -1
- package/dist/{to-blob-RPqMBuft.mjs → to-blob-Bqu7bmlE.mjs} +2 -3
- package/dist/{to-blob-RPqMBuft.mjs.map → to-blob-Bqu7bmlE.mjs.map} +1 -1
- package/dist/types-Z4abDJfK.d.mts +501 -0
- package/dist/types-Z4abDJfK.d.mts.map +1 -0
- package/dist/universes.d.mts +619 -436
- package/dist/universes.d.mts.map +1 -1
- package/dist/universes.mjs +432 -79
- package/dist/universes.mjs.map +1 -1
- package/dist/{validation-B_Zs1So2.mjs → validation-kaTLLAD1.mjs} +3 -4
- package/dist/{validation-B_Zs1So2.mjs.map → validation-kaTLLAD1.mjs.map} +1 -1
- package/dist/wire-DDG87I-d.d.mts +39 -0
- package/dist/wire-DDG87I-d.d.mts.map +1 -0
- package/package.json +15 -14
- package/dist/capacity-admission-IDO3fcUC.d.mts +0 -369
- package/dist/capacity-admission-IDO3fcUC.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-CoVhsC33.mjs.map +0 -1
- package/dist/resource-client-B6NeFXUv.d.mts +0 -164
- package/dist/resource-client-B6NeFXUv.d.mts.map +0 -1
- package/dist/resource-client-rqTMkBeR.mjs.map +0 -1
- package/dist/retry-BlX4tUnT.mjs.map +0 -1
- package/dist/retry-war_-9tb.d.mts +0 -373
- package/dist/retry-war_-9tb.d.mts.map +0 -1
- package/dist/types-CvYh4SPC.d.mts +0 -386
- package/dist/types-CvYh4SPC.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,663 @@
|
|
|
1
|
-
import { a as
|
|
2
|
-
import { a as TRANSIENT_TRANSPORT_CODES, c as
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
*
|
|
13
|
-
* @
|
|
14
|
-
*
|
|
15
|
-
* @
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
19
|
-
*
|
|
20
|
-
*
|
|
21
|
-
*
|
|
22
|
-
*
|
|
23
|
-
*
|
|
24
|
-
* type
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
*
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
33
|
-
*
|
|
34
|
-
*
|
|
35
|
-
* };
|
|
36
|
-
*
|
|
37
|
-
*
|
|
38
|
-
*
|
|
39
|
-
*
|
|
40
|
-
*
|
|
41
|
-
*
|
|
42
|
-
* }
|
|
43
|
-
* const
|
|
44
|
-
*
|
|
45
|
-
*
|
|
46
|
-
*
|
|
47
|
-
*
|
|
48
|
-
*
|
|
49
|
-
*
|
|
50
|
-
*
|
|
51
|
-
*
|
|
52
|
-
*
|
|
53
|
-
*
|
|
54
|
-
*
|
|
55
|
-
*
|
|
56
|
-
*
|
|
57
|
-
*
|
|
58
|
-
*
|
|
59
|
-
*
|
|
60
|
-
*
|
|
61
|
-
*
|
|
62
|
-
*
|
|
63
|
-
*
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
*
|
|
70
|
-
*
|
|
71
|
-
|
|
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
|
-
|
|
76
|
-
|
|
77
|
-
|
|
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
|
-
|
|
82
|
-
|
|
83
|
-
|
|
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
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
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
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
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
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
*
|
|
176
|
-
*
|
|
177
|
-
*
|
|
178
|
-
*
|
|
179
|
-
*
|
|
180
|
-
* @
|
|
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
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
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
|
-
|
|
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
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
constructor(message: string, {
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
}
|
|
282
|
-
|
|
283
|
-
|
|
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
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
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
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
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
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
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
|
-
*
|
|
437
|
-
*
|
|
438
|
-
*
|
|
439
|
-
|
|
440
|
-
|
|
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
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
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
|
-
|
|
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
|