@bedrock-rbx/ocale 0.3.4-beta.1 → 0.4.0

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