@bedrock-rbx/ocale 0.3.4 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (95) hide show
  1. package/README.md +10 -5
  2. package/dist/assets.d.mts +64 -0
  3. package/dist/assets.d.mts.map +1 -0
  4. package/dist/assets.mjs +301 -0
  5. package/dist/assets.mjs.map +1 -0
  6. package/dist/badge-insufficient-funds-BLFvQZt1.mjs +91 -0
  7. package/dist/badge-insufficient-funds-BLFvQZt1.mjs.map +1 -0
  8. package/dist/badges.d.mts +359 -196
  9. package/dist/badges.d.mts.map +1 -1
  10. package/dist/badges.mjs +493 -59
  11. package/dist/badges.mjs.map +1 -1
  12. package/dist/capacity-admission-Ce2V9QNb.d.mts +347 -0
  13. package/dist/capacity-admission-Ce2V9QNb.d.mts.map +1 -0
  14. package/dist/{data.generated-B2ceLfSn.d.mts → data.generated-B4Fztv_7.d.mts} +23 -25
  15. package/dist/data.generated-B4Fztv_7.d.mts.map +1 -0
  16. package/dist/developer-products.d.mts +207 -194
  17. package/dist/developer-products.d.mts.map +1 -1
  18. package/dist/developer-products.mjs +125 -39
  19. package/dist/developer-products.mjs.map +1 -1
  20. package/dist/game-passes.d.mts +206 -211
  21. package/dist/game-passes.d.mts.map +1 -1
  22. package/dist/game-passes.mjs +35 -36
  23. package/dist/game-passes.mjs.map +1 -1
  24. package/dist/index.d.mts +947 -366
  25. package/dist/index.d.mts.map +1 -1
  26. package/dist/index.mjs +324 -12
  27. package/dist/index.mjs.map +1 -1
  28. package/dist/is-date-time-string-C91G44SI.mjs +19 -0
  29. package/dist/is-date-time-string-C91G44SI.mjs.map +1 -0
  30. package/dist/locales.d.mts +28 -2
  31. package/dist/locales.d.mts.map +1 -0
  32. package/dist/locales.mjs +24 -3
  33. package/dist/locales.mjs.map +1 -1
  34. package/dist/luau-execution.d.mts +154 -157
  35. package/dist/luau-execution.d.mts.map +1 -1
  36. package/dist/luau-execution.mjs +15 -16
  37. package/dist/luau-execution.mjs.map +1 -1
  38. package/dist/{network-error-DR9FX5hb.mjs → network-error-P4An7nUB.mjs} +48 -14
  39. package/dist/network-error-P4An7nUB.mjs.map +1 -0
  40. package/dist/places.d.mts +258 -186
  41. package/dist/places.d.mts.map +1 -1
  42. package/dist/places.mjs +187 -35
  43. package/dist/places.mjs.map +1 -1
  44. package/dist/{poll-timeout-3PXLsabj.mjs → poll-timeout-BCxgN97O.mjs} +4 -6
  45. package/dist/{poll-timeout-3PXLsabj.mjs.map → poll-timeout-BCxgN97O.mjs.map} +1 -1
  46. package/dist/{polling-helpers-CoVhsC33.mjs → polling-helpers-BtEYR5dN.mjs} +260 -105
  47. package/dist/polling-helpers-BtEYR5dN.mjs.map +1 -0
  48. package/dist/{price-information-B0tkOoAX.mjs → price-information--d6GZAcp.mjs} +3 -4
  49. package/dist/{price-information-B0tkOoAX.mjs.map → price-information--d6GZAcp.mjs.map} +1 -1
  50. package/dist/resource-client-CF8SPsV8.d.mts +162 -0
  51. package/dist/resource-client-CF8SPsV8.d.mts.map +1 -0
  52. package/dist/{resource-client-rqTMkBeR.mjs → resource-client-Cm_bPcCs.mjs} +589 -197
  53. package/dist/resource-client-Cm_bPcCs.mjs.map +1 -0
  54. package/dist/retry-DYxm_eBU.d.mts +225 -0
  55. package/dist/retry-DYxm_eBU.d.mts.map +1 -0
  56. package/dist/{retry-BlX4tUnT.mjs → retry-Dv5TsY9O.mjs} +312 -54
  57. package/dist/retry-Dv5TsY9O.mjs.map +1 -0
  58. package/dist/{signatures-JF-7Psce.mjs → signatures-CtJ7jfVN.mjs} +2 -3
  59. package/dist/{signatures-JF-7Psce.mjs.map → signatures-CtJ7jfVN.mjs.map} +1 -1
  60. package/dist/storage.d.mts +333 -344
  61. package/dist/storage.d.mts.map +1 -1
  62. package/dist/storage.mjs +39 -40
  63. package/dist/storage.mjs.map +1 -1
  64. package/dist/testing.d.mts +369 -434
  65. package/dist/testing.d.mts.map +1 -1
  66. package/dist/testing.mjs +18 -33
  67. package/dist/testing.mjs.map +1 -1
  68. package/dist/{to-blob-RPqMBuft.mjs → to-blob-Bqu7bmlE.mjs} +2 -3
  69. package/dist/{to-blob-RPqMBuft.mjs.map → to-blob-Bqu7bmlE.mjs.map} +1 -1
  70. package/dist/types-Z4abDJfK.d.mts +501 -0
  71. package/dist/types-Z4abDJfK.d.mts.map +1 -0
  72. package/dist/universes.d.mts +619 -436
  73. package/dist/universes.d.mts.map +1 -1
  74. package/dist/universes.mjs +432 -79
  75. package/dist/universes.mjs.map +1 -1
  76. package/dist/{validation-B_Zs1So2.mjs → validation-kaTLLAD1.mjs} +3 -4
  77. package/dist/{validation-B_Zs1So2.mjs.map → validation-kaTLLAD1.mjs.map} +1 -1
  78. package/dist/wire-DDG87I-d.d.mts +39 -0
  79. package/dist/wire-DDG87I-d.d.mts.map +1 -0
  80. package/package.json +15 -14
  81. package/dist/capacity-admission-IDO3fcUC.d.mts +0 -369
  82. package/dist/capacity-admission-IDO3fcUC.d.mts.map +0 -1
  83. package/dist/data.generated-B2ceLfSn.d.mts.map +0 -1
  84. package/dist/network-error-DR9FX5hb.mjs.map +0 -1
  85. package/dist/polling-helpers-CoVhsC33.mjs.map +0 -1
  86. package/dist/resource-client-B6NeFXUv.d.mts +0 -164
  87. package/dist/resource-client-B6NeFXUv.d.mts.map +0 -1
  88. package/dist/resource-client-rqTMkBeR.mjs.map +0 -1
  89. package/dist/retry-BlX4tUnT.mjs.map +0 -1
  90. package/dist/retry-war_-9tb.d.mts +0 -373
  91. package/dist/retry-war_-9tb.d.mts.map +0 -1
  92. package/dist/types-CvYh4SPC.d.mts +0 -386
  93. package/dist/types-CvYh4SPC.d.mts.map +0 -1
  94. package/dist/wire-D3K-a-UP.d.mts +0 -37
  95. package/dist/wire-D3K-a-UP.d.mts.map +0 -1
@@ -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"}