@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
|
@@ -0,0 +1,501 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Options for constructing an {@link OpenCloudError}.
|
|
3
|
+
*
|
|
4
|
+
* @since 0.3.0
|
|
5
|
+
*/
|
|
6
|
+
interface OpenCloudErrorOptions extends ErrorOptions {
|
|
7
|
+
/**
|
|
8
|
+
* Machine-readable classifier for the failure, when the error has one. An
|
|
9
|
+
* `ApiError` and `RateLimitError` fill it from the response body; a
|
|
10
|
+
* `ValidationError` narrows it to its own closed union. Errors with nothing
|
|
11
|
+
* to classify (transport failures and poll timeouts) leave it `undefined`.
|
|
12
|
+
*/
|
|
13
|
+
readonly code?: string | undefined;
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* Base error class for all Open Cloud SDK errors.
|
|
17
|
+
*
|
|
18
|
+
* All specific error types (RateLimitError, ApiError, NetworkError)
|
|
19
|
+
* extend this class, enabling `instanceof OpenCloudError` checks.
|
|
20
|
+
*
|
|
21
|
+
* `code` is declared here rather than on the subclasses that populate it, so a
|
|
22
|
+
* caller holding the `OpenCloudError` that `Result.err` is typed as can branch
|
|
23
|
+
* on it without first narrowing to a subclass.
|
|
24
|
+
*
|
|
25
|
+
* @since 0.1.0
|
|
26
|
+
*
|
|
27
|
+
* @example
|
|
28
|
+
*
|
|
29
|
+
* ```ts
|
|
30
|
+
* import { ApiError, OpenCloudError } from "@bedrock-rbx/ocale";
|
|
31
|
+
*
|
|
32
|
+
* // `Result.err` is typed as OpenCloudError, so a caller draining a queue
|
|
33
|
+
* // branches on the canonical status without narrowing to a subclass first.
|
|
34
|
+
* const err: OpenCloudError = new ApiError("HTTP 404: Queue items not found.", {
|
|
35
|
+
* code: "NOT_FOUND",
|
|
36
|
+
* statusCode: 404,
|
|
37
|
+
* });
|
|
38
|
+
*
|
|
39
|
+
* expect(err.code).toBe("NOT_FOUND");
|
|
40
|
+
* expect(new OpenCloudError("no classifier").code).toBeUndefined();
|
|
41
|
+
* ```
|
|
42
|
+
*/
|
|
43
|
+
declare class OpenCloudError extends Error {
|
|
44
|
+
/** Machine-readable classifier, or `undefined` when the error has none. */
|
|
45
|
+
readonly code: string | undefined;
|
|
46
|
+
override readonly name: string;
|
|
47
|
+
/**
|
|
48
|
+
* Creates a new OpenCloudError.
|
|
49
|
+
*
|
|
50
|
+
* @param message - Human-readable error description.
|
|
51
|
+
* @param options - Error options including the optional `cause` and the
|
|
52
|
+
* machine-readable `code`.
|
|
53
|
+
*/
|
|
54
|
+
constructor(message?: string, options?: OpenCloudErrorOptions);
|
|
55
|
+
/**
|
|
56
|
+
* Failures of the earlier attempts of the same logical request, oldest
|
|
57
|
+
* first. A failure that is this error's own `cause` is not repeated here.
|
|
58
|
+
* Empty when the request was not retried.
|
|
59
|
+
*
|
|
60
|
+
* @since 0.4.0
|
|
61
|
+
* @returns The earlier attempts' failures.
|
|
62
|
+
*/
|
|
63
|
+
get previousAttempts(): ReadonlyArray<OpenCloudError>;
|
|
64
|
+
}
|
|
65
|
+
/**
|
|
66
|
+
* Injectable sleep function signature for testing.
|
|
67
|
+
*
|
|
68
|
+
* @since 0.1.0
|
|
69
|
+
*/
|
|
70
|
+
type SleepFunc = (ms: number, signal?: AbortSignal) => Promise<void>;
|
|
71
|
+
/**
|
|
72
|
+
* Discriminated union for explicit error handling.
|
|
73
|
+
*
|
|
74
|
+
* Every SDK client method returns `Promise<Result<T, OpenCloudError>>`.
|
|
75
|
+
* Errors are never thrown; they are returned as `{ err, success: false }`.
|
|
76
|
+
*
|
|
77
|
+
* @since 0.1.0
|
|
78
|
+
*
|
|
79
|
+
* @template T - The success value type.
|
|
80
|
+
* @template E - The error type (defaults to `Error`).
|
|
81
|
+
*
|
|
82
|
+
* @example
|
|
83
|
+
*
|
|
84
|
+
* ```ts
|
|
85
|
+
* import type { Result } from "@bedrock-rbx/ocale";
|
|
86
|
+
*
|
|
87
|
+
* function parseAge(input: string): Result<number, Error> {
|
|
88
|
+
* const age = Number(input);
|
|
89
|
+
* return Number.isFinite(age)
|
|
90
|
+
* ? { data: age, success: true }
|
|
91
|
+
* : { err: new Error(`Not a number: ${input}`), success: false };
|
|
92
|
+
* }
|
|
93
|
+
*
|
|
94
|
+
* const ok = parseAge("42");
|
|
95
|
+
* if (ok.success) {
|
|
96
|
+
* // ok.data is narrowed to number here; value is 42
|
|
97
|
+
* expect(ok.data).toBe(42);
|
|
98
|
+
* }
|
|
99
|
+
*
|
|
100
|
+
* const bad = parseAge("nope");
|
|
101
|
+
* if (!bad.success) {
|
|
102
|
+
* // bad.err is narrowed to Error here; message mentions the input
|
|
103
|
+
* expect(bad.err.message).toContain("Not a number");
|
|
104
|
+
* }
|
|
105
|
+
* ```
|
|
106
|
+
*/
|
|
107
|
+
type Result<T, E = Error> = {
|
|
108
|
+
data: T;
|
|
109
|
+
success: true;
|
|
110
|
+
} | {
|
|
111
|
+
err: E;
|
|
112
|
+
success: false;
|
|
113
|
+
};
|
|
114
|
+
/**
|
|
115
|
+
* One page of a cursor-paginated SDK response.
|
|
116
|
+
*
|
|
117
|
+
* `list`-style methods on resource clients (for example
|
|
118
|
+
* `GamePassesClient.list`) return a {@link Result} wrapping a `Page<T>`.
|
|
119
|
+
* `nextPageToken` carries the cursor for the next page when one exists,
|
|
120
|
+
* or `undefined` on the last page; the SDK normalizes the wire's
|
|
121
|
+
* `null`-vs-absent variants to `undefined` so callers only ever see one
|
|
122
|
+
* shape.
|
|
123
|
+
*
|
|
124
|
+
* @since 0.1.0
|
|
125
|
+
*
|
|
126
|
+
* @template T - The public item type for the listed resource.
|
|
127
|
+
*
|
|
128
|
+
* @example
|
|
129
|
+
*
|
|
130
|
+
* ```ts
|
|
131
|
+
* import type { Page } from "@bedrock-rbx/ocale";
|
|
132
|
+
*
|
|
133
|
+
* const middle: Page<string> = { items: ["a", "b"], nextPageToken: "cursor" };
|
|
134
|
+
* expect(middle.items).toEqual(["a", "b"]);
|
|
135
|
+
* expect(middle.nextPageToken).toBe("cursor");
|
|
136
|
+
*
|
|
137
|
+
* const last: Page<string> = { items: ["c"], nextPageToken: undefined };
|
|
138
|
+
* expect(last.items).toEqual(["c"]);
|
|
139
|
+
* expect(last.nextPageToken).toBeUndefined();
|
|
140
|
+
* ```
|
|
141
|
+
*/
|
|
142
|
+
interface Page<T> {
|
|
143
|
+
/** Items in this page, in the order returned by the API. */
|
|
144
|
+
readonly items: ReadonlyArray<T>;
|
|
145
|
+
/** Cursor for the next page; `undefined` on the last page. */
|
|
146
|
+
readonly nextPageToken: string | undefined;
|
|
147
|
+
}
|
|
148
|
+
/**
|
|
149
|
+
* Why a logical request is waiting for SDK-managed admission.
|
|
150
|
+
*
|
|
151
|
+
* @example
|
|
152
|
+
*
|
|
153
|
+
* ```ts
|
|
154
|
+
* import type { AdmissionWaitReason } from "@bedrock-rbx/ocale";
|
|
155
|
+
*
|
|
156
|
+
* const reason: AdmissionWaitReason = "retry-delay";
|
|
157
|
+
* expect(reason).toBe("retry-delay");
|
|
158
|
+
* ```
|
|
159
|
+
*
|
|
160
|
+
* @since 0.3.1
|
|
161
|
+
*/
|
|
162
|
+
type AdmissionWaitReason = "operation-capacity" | "operation-queue" | "reported-budget" | "retry-delay";
|
|
163
|
+
/**
|
|
164
|
+
* One boundary in a request's SDK-managed admission-wait lifecycle.
|
|
165
|
+
*
|
|
166
|
+
* `durationMs` is the scheduler's intended duration, not elapsed wall time,
|
|
167
|
+
* and is absent when the SDK cannot know the duration up front.
|
|
168
|
+
*
|
|
169
|
+
* @example
|
|
170
|
+
*
|
|
171
|
+
* ```ts
|
|
172
|
+
* import type { AdmissionWaitEvent } from "@bedrock-rbx/ocale";
|
|
173
|
+
*
|
|
174
|
+
* const event: AdmissionWaitEvent = {
|
|
175
|
+
* durationMs: 500,
|
|
176
|
+
* phase: "started",
|
|
177
|
+
* reason: "reported-budget",
|
|
178
|
+
* };
|
|
179
|
+
* expect(event.durationMs).toBe(500);
|
|
180
|
+
* ```
|
|
181
|
+
*
|
|
182
|
+
* @since 0.3.1
|
|
183
|
+
*/
|
|
184
|
+
interface AdmissionWaitEvent {
|
|
185
|
+
/** Intended wait duration in milliseconds, when known. */
|
|
186
|
+
readonly durationMs?: number;
|
|
187
|
+
/** Whether the wait has just begun or has finished. */
|
|
188
|
+
readonly phase: "ended" | "started";
|
|
189
|
+
/** SDK admission mechanism responsible for the wait. */
|
|
190
|
+
readonly reason: AdmissionWaitReason;
|
|
191
|
+
}
|
|
192
|
+
/**
|
|
193
|
+
* Receives request-scoped admission-wait lifecycle notifications.
|
|
194
|
+
*
|
|
195
|
+
* @example
|
|
196
|
+
*
|
|
197
|
+
* ```ts
|
|
198
|
+
* import type { AdmissionWaitEvent, AdmissionWaitObserver } from "@bedrock-rbx/ocale";
|
|
199
|
+
*
|
|
200
|
+
* const events: AdmissionWaitEvent[] = [];
|
|
201
|
+
* const observer: AdmissionWaitObserver = (event) => events.push(event);
|
|
202
|
+
* observer({ phase: "started", reason: "operation-queue" });
|
|
203
|
+
* expect(events).toHaveLength(1);
|
|
204
|
+
* ```
|
|
205
|
+
*
|
|
206
|
+
* @since 0.3.1
|
|
207
|
+
*/
|
|
208
|
+
type AdmissionWaitObserver = (event: AdmissionWaitEvent) => unknown;
|
|
209
|
+
/**
|
|
210
|
+
* How a client authenticates to Open Cloud. Pass it as
|
|
211
|
+
* {@link OpenCloudClientOptions.credential}, or for one call as
|
|
212
|
+
* `credential` on {@link RequestOptions}.
|
|
213
|
+
*
|
|
214
|
+
* @example
|
|
215
|
+
*
|
|
216
|
+
* ```ts
|
|
217
|
+
* import type { Credential } from "@bedrock-rbx/ocale";
|
|
218
|
+
*
|
|
219
|
+
* const credential: Credential = { apiKey: "your-key", kind: "apiKey" };
|
|
220
|
+
* expect(credential.kind).toBe("apiKey");
|
|
221
|
+
* ```
|
|
222
|
+
*
|
|
223
|
+
* @since 0.4.0
|
|
224
|
+
*/
|
|
225
|
+
type Credential = {
|
|
226
|
+
/**
|
|
227
|
+
* Returns a current OAuth 2.0 access token. The client calls it
|
|
228
|
+
* once per transport attempt, after every admission wait (retry
|
|
229
|
+
* backoff, rate-limit queue, budget gate) and just before the
|
|
230
|
+
* send, with the request's `signal`. It may return the token or a
|
|
231
|
+
* promise of it.
|
|
232
|
+
*
|
|
233
|
+
* Contract: return a token that stays valid for at least 60 s, and
|
|
234
|
+
* throw (or reject) when no such token is available. A throw ends
|
|
235
|
+
* the call with a `CredentialError` whose `cause` is the thrown
|
|
236
|
+
* value, and spends no retry.
|
|
237
|
+
*/
|
|
238
|
+
readonly getAccessToken: (context: {
|
|
239
|
+
readonly signal: AbortSignal;
|
|
240
|
+
}) => Promise<string> | string;
|
|
241
|
+
/**
|
|
242
|
+
* Stable, caller-chosen name of the grant, for example the Roblox
|
|
243
|
+
* user id. It keys the rate-limit queue and the budget gate, so
|
|
244
|
+
* it must not change when the token rotates.
|
|
245
|
+
*/
|
|
246
|
+
readonly identity: string;
|
|
247
|
+
/** Selects OAuth authentication, sent as a Bearer token. */
|
|
248
|
+
readonly kind: "oauth";
|
|
249
|
+
} | {
|
|
250
|
+
/**
|
|
251
|
+
* Selects no authentication. Only the endpoints Roblox documents as
|
|
252
|
+
* unauthenticated, such as the free badge quota read, succeed with
|
|
253
|
+
* it. No credential header is sent.
|
|
254
|
+
*/
|
|
255
|
+
readonly kind: "none";
|
|
256
|
+
} | {
|
|
257
|
+
/** The Roblox Open Cloud API key. */
|
|
258
|
+
readonly apiKey: string;
|
|
259
|
+
/** Selects API-key authentication, sent as `x-api-key`. */
|
|
260
|
+
readonly kind: "apiKey";
|
|
261
|
+
};
|
|
262
|
+
/**
|
|
263
|
+
* The credential a transport receives on {@link RequestConfig.credential},
|
|
264
|
+
* ready to turn into a request header.
|
|
265
|
+
*
|
|
266
|
+
* @since 0.4.0
|
|
267
|
+
*/
|
|
268
|
+
type ResolvedCredential = {
|
|
269
|
+
/**
|
|
270
|
+
* Selects no authentication, for an endpoint Roblox documents as
|
|
271
|
+
* unauthenticated. No credential header is sent.
|
|
272
|
+
*/
|
|
273
|
+
readonly kind: "none";
|
|
274
|
+
} | {
|
|
275
|
+
/** The OAuth access token, sent as `Authorization: Bearer`. */
|
|
276
|
+
readonly accessToken: string;
|
|
277
|
+
/** Selects OAuth authentication. */
|
|
278
|
+
readonly kind: "oauth";
|
|
279
|
+
} | {
|
|
280
|
+
/** The Roblox Open Cloud API key, sent as `x-api-key`. */
|
|
281
|
+
readonly apiKey: string;
|
|
282
|
+
/** Selects API-key authentication. */
|
|
283
|
+
readonly kind: "apiKey";
|
|
284
|
+
};
|
|
285
|
+
/**
|
|
286
|
+
* A normalized HTTP request to send to the Roblox Open Cloud API.
|
|
287
|
+
*
|
|
288
|
+
* @since 0.1.0
|
|
289
|
+
*/
|
|
290
|
+
interface HttpRequest {
|
|
291
|
+
/** The request body. */
|
|
292
|
+
readonly body?: HttpRequestBody;
|
|
293
|
+
/**
|
|
294
|
+
* Caller-supplied request headers. Applied after the transport sets the
|
|
295
|
+
* credential header and any body-driven `Content-Type`, so a
|
|
296
|
+
* caller-supplied header replaces the transport's default. `x-api-key`
|
|
297
|
+
* and `authorization` are skipped, so a request header cannot replace
|
|
298
|
+
* the configured credential.
|
|
299
|
+
*/
|
|
300
|
+
readonly headers?: Readonly<Record<string, string>>;
|
|
301
|
+
/** The HTTP method. */
|
|
302
|
+
readonly method: "DELETE" | "GET" | "PATCH" | "POST";
|
|
303
|
+
/** Relative path, e.g. `/game-passes/v1/universes/123/...`. */
|
|
304
|
+
readonly url: string;
|
|
305
|
+
}
|
|
306
|
+
/**
|
|
307
|
+
* A normalized HTTP response from the Roblox Open Cloud API.
|
|
308
|
+
*
|
|
309
|
+
* @since 0.1.0
|
|
310
|
+
*/
|
|
311
|
+
interface HttpResponse {
|
|
312
|
+
/**
|
|
313
|
+
* The parsed response body. `undefined` when the response had an empty
|
|
314
|
+
* body (for example HTTP 204 No Content, or any other status where the
|
|
315
|
+
* server returned no payload).
|
|
316
|
+
*/
|
|
317
|
+
readonly body: unknown;
|
|
318
|
+
/** Response headers with lowercased keys. */
|
|
319
|
+
readonly headers: Readonly<Record<string, string>>;
|
|
320
|
+
/** The HTTP status code. */
|
|
321
|
+
readonly status: number;
|
|
322
|
+
}
|
|
323
|
+
/**
|
|
324
|
+
* Per-request configuration passed to {@link HttpClient.request}.
|
|
325
|
+
*
|
|
326
|
+
* @since 0.1.0
|
|
327
|
+
*/
|
|
328
|
+
interface RequestConfig {
|
|
329
|
+
/** Base URL for the API, e.g. `https://apis.roblox.com`. */
|
|
330
|
+
readonly baseUrl: string;
|
|
331
|
+
/** The resolved credential for this request. */
|
|
332
|
+
readonly credential: ResolvedCredential;
|
|
333
|
+
/** Caller cancellation signal for this request. */
|
|
334
|
+
readonly signal?: AbortSignal;
|
|
335
|
+
/** Optional request timeout in milliseconds. */
|
|
336
|
+
readonly timeout?: number;
|
|
337
|
+
}
|
|
338
|
+
/**
|
|
339
|
+
* HTTP transport abstraction. Implementations classify every response into
|
|
340
|
+
* a typed {@link Result}.
|
|
341
|
+
*
|
|
342
|
+
* A custom implementation receives the resolved credential on
|
|
343
|
+
* {@link RequestConfig.credential}. Ocale passes its results and errors
|
|
344
|
+
* through unchanged, so they are outside the guarantee that ocale-built
|
|
345
|
+
* errors and hook arguments never hold the API key or the access token.
|
|
346
|
+
* The same applies to `NetworkError.cause` from a wrapped `fetch`,
|
|
347
|
+
* `CredentialError.cause` from the token provider, and `ApiError.details`
|
|
348
|
+
* and `UnexpectedResponseError.details` from a Roblox response body.
|
|
349
|
+
*
|
|
350
|
+
* @since 0.1.0
|
|
351
|
+
*/
|
|
352
|
+
interface HttpClient {
|
|
353
|
+
/** Sends an HTTP request and classifies the response. */
|
|
354
|
+
request(request: HttpRequest, config: RequestConfig): Promise<Result<HttpResponse, OpenCloudError>>;
|
|
355
|
+
}
|
|
356
|
+
/**
|
|
357
|
+
* Client-level observability hooks. All hooks are notification-only and
|
|
358
|
+
* fire-and-forget; they cannot alter retry behaviour.
|
|
359
|
+
*
|
|
360
|
+
* @since 0.1.0
|
|
361
|
+
*/
|
|
362
|
+
interface OpenCloudHooks {
|
|
363
|
+
/** Fired before the SDK sleeps for a computed retry or rate-limit wait. */
|
|
364
|
+
readonly onRateLimit?: (waitMs: number) => void;
|
|
365
|
+
/** Fired before each HTTP attempt (including retries). */
|
|
366
|
+
readonly onRequest?: (request: HttpRequest) => void;
|
|
367
|
+
/**
|
|
368
|
+
* Fired before each wait that precedes a retry. `attempt` is 1-indexed and
|
|
369
|
+
* counts every such wait, including server-guided rate-limit waits that do
|
|
370
|
+
* not spend `maxRetries`, so it can exceed `maxRetries`.
|
|
371
|
+
*/
|
|
372
|
+
readonly onRetry?: (attempt: number, error: OpenCloudError) => void;
|
|
373
|
+
}
|
|
374
|
+
/**
|
|
375
|
+
* Options accepted by every resource client constructor. Cross-cutting
|
|
376
|
+
* configuration that applies to all requests made through the client instance.
|
|
377
|
+
*
|
|
378
|
+
* @since 0.1.0
|
|
379
|
+
*/
|
|
380
|
+
interface OpenCloudClientOptions {
|
|
381
|
+
/** Base URL for the Open Cloud API. Defaults to `https://apis.roblox.com`. */
|
|
382
|
+
readonly baseUrl?: string;
|
|
383
|
+
/**
|
|
384
|
+
* The credential used as the default for every request.
|
|
385
|
+
*
|
|
386
|
+
* For an OAuth credential, `getAccessToken` must return a token that
|
|
387
|
+
* stays valid for at least 60 s, and must throw (or reject) when it
|
|
388
|
+
* cannot. The client calls it once per transport attempt, after every
|
|
389
|
+
* admission wait, with the request's `signal`. A throw returns a
|
|
390
|
+
* `CredentialError` with the provider error as `cause` and spends
|
|
391
|
+
* no retry. The provider's own error is passed through unchanged, so
|
|
392
|
+
* scrub any secret from it yourself.
|
|
393
|
+
*
|
|
394
|
+
* No message, error, `cause` chain or hook argument that ocale builds
|
|
395
|
+
* holds the API key or the access token. These values pass through
|
|
396
|
+
* from outside ocale and are not covered:
|
|
397
|
+
*
|
|
398
|
+
* - anything a custom {@link HttpClient} returns or throws;
|
|
399
|
+
* - `NetworkError.cause`, the error thrown by a wrapped `fetch`;
|
|
400
|
+
* - `CredentialError.cause`, the error thrown by `getAccessToken`;
|
|
401
|
+
* - `ApiError.details` and `UnexpectedResponseError.details`, the
|
|
402
|
+
* response body Roblox sent.
|
|
403
|
+
*/
|
|
404
|
+
readonly credential: Credential;
|
|
405
|
+
/** Optional observability hooks. */
|
|
406
|
+
readonly hooks?: OpenCloudHooks;
|
|
407
|
+
/**
|
|
408
|
+
* Plug in a custom {@link HttpClient} to wrap or replace the default
|
|
409
|
+
* fetch-backed transport. Useful for wrapping `fetch` with tracing
|
|
410
|
+
* or metrics, routing through a custom proxy, or feeding the SDK
|
|
411
|
+
* from a recorded-fixture or replay layer. Most consumers leave this
|
|
412
|
+
* unset and use the default.
|
|
413
|
+
*/
|
|
414
|
+
readonly httpClient?: HttpClient;
|
|
415
|
+
/**
|
|
416
|
+
* Maximum retry attempts. Defaults to `3`. A rate limit whose response
|
|
417
|
+
* says how long to wait is waited out without spending an attempt; leave
|
|
418
|
+
* `429` out of `retryableStatuses` to stop retrying rate limits at all.
|
|
419
|
+
*/
|
|
420
|
+
readonly maxRetries?: number;
|
|
421
|
+
/**
|
|
422
|
+
* End the message of an `UnexpectedResponseError` with a line that links
|
|
423
|
+
* to a prefilled ocale bug report (`UnexpectedResponseError.reportUrl`).
|
|
424
|
+
* Defaults to `true`. Set `false` when your tool renders its own failure
|
|
425
|
+
* output or sends users to its own tracker. `reportUrl` stays set.
|
|
426
|
+
*/
|
|
427
|
+
readonly reportHint?: boolean;
|
|
428
|
+
/**
|
|
429
|
+
* Status codes eligible for retry. Defaults to the idempotent-method set
|
|
430
|
+
* `[429, 500, 502, 503, 504]`. Resource clients may tighten this per
|
|
431
|
+
* method (e.g. `create` only retries `429`).
|
|
432
|
+
*/
|
|
433
|
+
readonly retryableStatuses?: ReadonlyArray<number>;
|
|
434
|
+
/**
|
|
435
|
+
* Node-style transport error codes eligible for retry when a request fails
|
|
436
|
+
* with a `NetworkError` (e.g. `["ECONNRESET", "ETIMEDOUT"]`).
|
|
437
|
+
* Defaults to the idempotent-method transient set. Create methods default
|
|
438
|
+
* to none and cannot be relaxed by a client-level value. Pass the exported
|
|
439
|
+
* `TRANSIENT_TRANSPORT_CODES` set (or your own subset) on a single call's
|
|
440
|
+
* {@link RequestOptions} to opt a create into transport retries when a
|
|
441
|
+
* duplicate resource is acceptable.
|
|
442
|
+
*/
|
|
443
|
+
readonly retryableTransportCodes?: ReadonlyArray<string>;
|
|
444
|
+
/** Fallback delay function used when no server hint is available. */
|
|
445
|
+
readonly retryDelay?: (attempt: number) => number;
|
|
446
|
+
/**
|
|
447
|
+
* Plug in a custom {@link SleepFunc} used between retry attempts and
|
|
448
|
+
* for rate-limit waits. Useful for integrating with a custom
|
|
449
|
+
* scheduler or virtual clock. Most consumers leave this unset and
|
|
450
|
+
* use the default `setTimeout`-backed sleep.
|
|
451
|
+
*/
|
|
452
|
+
readonly sleep?: SleepFunc;
|
|
453
|
+
/**
|
|
454
|
+
* Default per-request timeout in milliseconds for JSON-bound methods,
|
|
455
|
+
* defaulting to `30_000`. Upload methods (those whose request body is
|
|
456
|
+
* `FormData` or `Uint8Array`, such as place publishes and icon uploads)
|
|
457
|
+
* have no default timeout and ignore this option: upload latency is
|
|
458
|
+
* bandwidth-bound, and the SDK cannot size a wall-clock budget without
|
|
459
|
+
* knowing payload size and link quality. Set a transport-attempt timeout
|
|
460
|
+
* on any single call, upload or otherwise, with `options.timeout`.
|
|
461
|
+
*/
|
|
462
|
+
readonly timeout?: number;
|
|
463
|
+
}
|
|
464
|
+
/**
|
|
465
|
+
* Per-request override shape. Any subset of the overridable client options
|
|
466
|
+
* may be supplied for a single request; omitted fields fall through to the
|
|
467
|
+
* client-level defaults.
|
|
468
|
+
*
|
|
469
|
+
* @since 0.1.0
|
|
470
|
+
*/
|
|
471
|
+
type RequestOptions = Partial<Pick<OpenCloudClientOptions, "baseUrl" | "credential" | "maxRetries" | "retryableStatuses" | "retryableTransportCodes" | "retryDelay" | "timeout">> & {
|
|
472
|
+
/**
|
|
473
|
+
* Absolute Unix timestamp in milliseconds by which this logical request
|
|
474
|
+
* must finish. SDK-managed waits that cannot fit fail with a typed
|
|
475
|
+
* `RequestDeadlineExceededError` instead of consuming the remaining budget.
|
|
476
|
+
*/
|
|
477
|
+
readonly deadlineMs?: number;
|
|
478
|
+
/**
|
|
479
|
+
* Receives the admission waits entered by this logical request only.
|
|
480
|
+
* Notifications cannot alter scheduling or retry behavior.
|
|
481
|
+
*/
|
|
482
|
+
readonly onAdmissionWait?: AdmissionWaitObserver;
|
|
483
|
+
/** Cancels this request at any point in its lifecycle. */
|
|
484
|
+
readonly signal?: AbortSignal;
|
|
485
|
+
};
|
|
486
|
+
/**
|
|
487
|
+
* Supported request body types.
|
|
488
|
+
*
|
|
489
|
+
* - `FormData` for multipart uploads (Content-Type set automatically by
|
|
490
|
+
* fetch).
|
|
491
|
+
* - `Record<string, unknown>` for JSON bodies (serialized with
|
|
492
|
+
* `JSON.stringify`).
|
|
493
|
+
* - `Uint8Array<ArrayBuffer>` for raw binary uploads (default Content-Type is
|
|
494
|
+
* `application/octet-stream`; override via {@link HttpRequest.headers}).
|
|
495
|
+
* `SharedArrayBuffer`-backed views are not accepted by `fetch`; wrap them
|
|
496
|
+
* via `new Uint8Array(bytes)` to obtain an `ArrayBuffer`-backed copy.
|
|
497
|
+
* - `undefined` for requests without a body (GET, DELETE).
|
|
498
|
+
*/
|
|
499
|
+
type HttpRequestBody = FormData | Record<string, unknown> | Uint8Array<ArrayBuffer> | undefined;
|
|
500
|
+
export { OpenCloudErrorOptions as _, HttpClient as a, OpenCloudClientOptions as c, RequestOptions as d, ResolvedCredential as f, OpenCloudError as g, SleepFunc as h, Credential as i, OpenCloudHooks as l, Result as m, AdmissionWaitObserver as n, HttpRequest as o, Page as p, AdmissionWaitReason as r, HttpResponse as s, AdmissionWaitEvent as t, RequestConfig as u };
|
|
501
|
+
//# sourceMappingURL=types-Z4abDJfK.d.mts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"types-Z4abDJfK.d.mts","names":[],"sources":["../src/errors/base.ts","../src/internal/utils/sleep.ts","../src/types.ts","../src/client/types.ts"],"mappings":";;;;;UAKiB,8BAA8B;;;;;;;WAOrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAmCG,uBAAuB;;WAEnB;oBACS;;;;;;;;EASzB,YAAY,kBAAkB,UAAU;;;;;;;;;MAa7B,oBAAoB,cAAc;;;;;;;KCjElC,aAAa,YAAY,SAAS,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KC6BlD,OAAO,GAAG,IAAI;EAAW,MAAM;EAAG;;EAAoB,KAAK;EAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UA8BzD,KAAK;;WAEZ,OAAO,cAAc;;WAErB;;;;;;;;;;;;;;;;KClDE;;;;;;;;;;;;;;;;;;;;;;UA2BK;;WAEP;;WAEA;;WAEA,QAAQ;;;;;;;;;;;;;;;;;;KAmBN,yBAAyB,OAAO;;;;;;;;;;;;;;;;;KAkBhC;;;;;;;;;;;;;WAcA,iBAAiB;aAChB,QAAQ;QACZ;;;;;;WAMG;;WAEA;;;;;;;WAQA;;;WAIA;;WAEA;;;;;;;;KASA;;;;;WAMA;;;WAIA;;WAEA;;;WAIA;;WAEA;;;;;;;UAQK;;WAEP,OAAO;;;;;;;;WAQP,UAAU,SAAS;;WAEnB;;WAEA;;;;;;;UAQO;;;;;;WAMP;;WAEA,SAAS,SAAS;;WAElB;;;;;;;UAQO;;WAEP;;WAEA,YAAY;;WAEZ,SAAS;;WAET;;;;;;;;;;;;;;;;UAiBO;;EAEhB,QACC,SAAS,aACT,QAAQ,gBACN,QAAQ,OAAO,cAAc;;;;;;;;UAShB;;WAEP,eAAe;;WAEf,aAAa,SAAS;;;;;;WAMtB,WAAW,iBAAiB,OAAO;;;;;;;;UAS5B;;WAEP;;;;;;;;;;;;;;;;;;;;;;WAsBA,YAAY;;WAEZ,QAAQ;;;;;;;;WAQR,aAAa;;;;;;WAMb;;;;;;;WAOA;;;;;;WAMA,oBAAoB;;;;;;;;;;WAUpB,0BAA0B;;WAE1B,cAAc;;;;;;;WAOd,QAAQ;;;;;;;;;;WAUR;;;;;;;;;KAUE,iBAAiB,QAC5B,KACC;;;;;;WAeQ;;;;;WAKA,kBAAkB;;WAElB,SAAS;;;;;;;;;;;;;;;KAgBd,kBAAkB,WAAW,0BAA0B,WAAW"}
|