@bedrock-rbx/ocale 0.1.0-beta.1 → 0.1.0-beta.3

package/dist/storage.d.mts

@@ -0,0 +1,380 @@
+import { d as OpenCloudError, i as OpenCloudClientOptions, l as Result, n as HttpRequest, r as HttpResponse, s as RequestOptions, u as SleepFunc } from "./types-DUzm6maA.mjs";
+
+//#region src/domains/cloud-v2/memory-store-queues/types.d.ts
+/**
+* Caller-supplied input for the `enqueue` method on `StorageClient.queues`.
+* Mirrors `Cloud_CreateMemoryStoreQueueItem` on the Open Cloud API.
+*/
+interface EnqueueQueueItemParameters {
+  /**
+  * Opaque queue payload. Round-trips as JSON, including nested `null`
+  * values inside objects and arrays. The top-level value cannot be
+  * `null`: the server rejects null payloads with a 400, so the type
+  * forbids it at compile time.
+  */
+  readonly data: Exclude<JSONValue, null>;
+  /**
+  * Optional priority. Higher values are dequeued first; equal priorities
+  * preserve insertion order. Omitted entries are inserted at the back of
+  * the queue.
+  */
+  readonly priority?: number;
+  /** Stringified queue identifier; the queue is auto-created on first use. */
+  readonly queueId: string;
+  /**
+  * Optional time-to-live in seconds. After this many seconds the item is
+  * automatically removed from the queue. Omitted entries inherit the
+  * server-default TTL.
+  */
+  readonly ttl?: number;
+  /** Stringified ID of the universe that owns the queue. */
+  readonly universeId: string;
+}
+/**
+* Parsed representation of a memory-store queue item, as returned by the
+* Open Cloud `Cloud_CreateMemoryStoreQueueItem` and (inside the array)
+* `Cloud_ReadMemoryStoreQueueItems` endpoints.
+*/
+interface QueueItem {
+  /** Server-generated item identifier, parsed from the wire `path`. */
+  readonly id: string;
+  /**
+  * Opaque queue payload. Nested `null` values inside the JSON shape are
+  * preserved verbatim; only the top level is constrained.
+  */
+  readonly data: Exclude<JSONValue, null>;
+  /** Timestamp at which the server removes the item from the queue. */
+  readonly expiresAt: Date;
+  /** Priority recorded on the item, or `undefined` when none was set. */
+  readonly priority: number | undefined;
+  /** Stringified queue identifier, parsed from the wire `path`. */
+  readonly queueId: string;
+  /** Stringified universe identifier, parsed from the wire `path`. */
+  readonly universeId: string;
+}
+/**
+* Caller-supplied input for the `dequeue` method on
+* `StorageClient.queues`. Mirrors `Cloud_ReadMemoryStoreQueueItems`.
+*/
+interface DequeueQueueItemsParameters {
+  /**
+  * If `true`, the server returns 404 when fewer than `count` items
+  * are available. Defaults to `false`, in which case the server
+  * returns whatever subset is currently at the front of the queue.
+  */
+  readonly allOrNothing?: boolean;
+  /**
+  * Number of items to read from the front of the queue. Defaults to
+  * `1`; values above `200` are clamped server-side.
+  */
+  readonly count?: number;
+  /**
+  * Number of seconds the dequeued items remain invisible to
+  * subsequent reads. Items not acknowledged via `discard` reappear
+  * once the window elapses. Defaults to `30` seconds server-side.
+  */
+  readonly invisibilityWindow?: number;
+  /** Stringified queue identifier. */
+  readonly queueId: string;
+  /** Stringified ID of the universe that owns the queue. */
+  readonly universeId: string;
+}
+/**
+* Parsed result of a successful `Cloud_ReadMemoryStoreQueueItems`
+* response. The `readId` value must be passed to a subsequent
+* `discard` call to acknowledge the items; otherwise the items reappear
+* once the invisibility window elapses.
+*/
+interface DequeueResult {
+  /** Items dequeued from the front of the queue, in dequeue order. */
+  readonly items: ReadonlyArray<QueueItem>;
+  /**
+  * Identifier of the dequeue operation. Pass this to `discard` to
+  * remove the items from the queue permanently.
+  */
+  readonly readId: string;
+}
+/**
+* Caller-supplied input for the `discard` method on
+* `StorageClient.queues`. Mirrors `Cloud_DiscardMemoryStoreQueueItems`.
+* Acknowledging a `readId` removes the dequeued batch from the queue
+* permanently; without `discard`, the items reappear once their
+* invisibility window elapses.
+*/
+interface DiscardQueueItemsParameters {
+  /** Stringified queue identifier. */
+  readonly queueId: string;
+  /** Identifier returned by a prior `dequeue` call. */
+  readonly readId: string;
+  /** Stringified ID of the universe that owns the queue. */
+  readonly universeId: string;
+}
+//#endregion
+//#region src/internal/http/rate-limit-queue.d.ts
+/**
+* Identifies and bounds a single Roblox Open Cloud operation for rate
+* limiting, e.g. `{ operationKey: "game-passes.create", maxPerSecond: 5 }`.
+*/
+interface OperationLimit {
+  /** Maximum sustained request rate in requests per second. */
+  readonly maxPerSecond: number;
+  /**
+  * Stable identifier for the operation (e.g. "game-passes.create"). Not
+  * consumed by the queue itself; callers use it to key per-operation
+  * queues in a registry (see GamePassesClient).
+  */
+  readonly operationKey: string;
+}
+//#endregion
+//#region src/internal/http/retry.d.ts
+/**
+* Fully-resolved retry config shape that {@link mergeConfig} and
+* {@link shouldRetry} operate on. Fields are required because this represents
+* the post-defaulting, internal view — callers should supply every field (or
+* resolve them via a test factory / client constructor). The partial,
+* user-facing type lives on client construction options; method defaults and
+* per-request overrides use `Partial<RetryResolvable>`.
+*/
+interface RetryResolvable {
+  /** Roblox Open Cloud API key. */
+  readonly apiKey: string;
+  /** Base URL for the Open Cloud API. */
+  readonly baseUrl: string;
+  /** Maximum retry attempts before giving up. */
+  readonly maxRetries: number;
+  /** Status codes that are eligible for retry. */
+  readonly retryableStatuses: ReadonlyArray<number>;
+  /** Fallback delay function when no server hint is available. */
+  readonly retryDelay: (attempt: number) => number;
+  /** Per-request timeout in milliseconds. */
+  readonly timeout: number;
+}
+/** Kind of HTTP method the merge is being performed for. */
+type MethodKind = "create" | "idempotent";
+//#endregion
+//#region src/internal/resource-client.d.ts
+/**
+* Describes a single resource method's shape for dispatch through
+* `ResourceClient.execute`. Each resource client declares one module-level
+* constant per public method; that constant binds the four resource-specific
+* values (request builder, response parser, retry-policy method kind,
+* operation-level rate limit) and flows through `execute` uniformly.
+*
+* @template P - The resource-specific parameter shape the builder
+*   accepts.
+* @template T - The resource-specific parsed success type the parser
+*   produces.
+*/
+interface ResourceMethodSpec<P, T> {
+  /**
+  * Builds the pure {@link HttpRequest} for a single call. Returns a
+  * {@link Result} so a builder can short-circuit with a local error
+  * (typically a {@link OpenCloudError} subclass such as `ValidationError`)
+  * before any HTTP, queue, or retry work happens. Builders that cannot
+  * fail wrap their return as `{ data: request, success: true }`.
+  */
+  readonly buildRequest: (parameters: P) => Result<HttpRequest, OpenCloudError>;
+  /** Method-level retry defaults merged into the resolved config. */
+  readonly methodDefaults: Partial<RetryResolvable>;
+  /**
+  * Method kind, controlling merge precedence: `"create"` lets method
+  * defaults win over client config so create safety cannot be relaxed
+  * silently; `"idempotent"` lets client config win over method defaults
+  * so consumers can loosen retry globally.
+  */
+  readonly methodKind: MethodKind;
+  /** Operation-level rate limit, keyed into the client's per-key queue map. */
+  readonly operationLimit: OperationLimit;
+  /**
+  * Converts the full {@link HttpResponse} into the resource-specific
+  * parsed shape. Takes the whole response (body, status, headers) so
+  * future parsers can read headers without widening the signature.
+  */
+  readonly parse: (response: HttpResponse) => Result<T, OpenCloudError>;
+  /**
+  * Open Cloud scopes the API key or OAuth token must carry for this
+  * method, sourced from the vendored OpenAPI schema's `x-roblox-scopes`.
+  * When set, a 401 or 403 ApiError from the upstream call is upgraded to
+  * a {@link PermissionError} carrying these scopes alongside
+  * {@link OperationLimit.operationKey}, so callers can name the missing
+  * scope instead of just the HTTP status. Optional so test specs and
+  * not-yet-wired resources can opt out.
+  */
+  readonly requiredScopes?: ReadonlyArray<string>;
+}
+/**
+* Single-argument bundle consumed by `ResourceClient.execute`: the per-method
+* spec, the resource-specific parameters, and optional per-request config
+* overrides.
+*
+* @template P - The resource-specific parameter shape the builder accepts.
+* @template T - The resource-specific parsed success type the parser produces.
+*/
+interface ExecuteCall<P, T> {
+  /** Optional per-request config overrides. */
+  readonly options?: RequestOptions | undefined;
+  /** Resource-specific request parameters. */
+  readonly parameters: P;
+  /** Per-method binding of builder, parser, method kind, and operation limit. */
+  readonly spec: ResourceMethodSpec<P, T>;
+}
+/**
+* Wraps an infallible request build as a {@link Result}-returning
+* `buildRequest` callback compatible with {@link ResourceMethodSpec}.
+* Use from a resource client whose builder cannot fail; resource clients
+* with local validation should construct the {@link Result} directly.
+*
+* @param request - The pre-built {@link HttpRequest}.
+* @returns A success Result wrapping the request.
+*/
+/**
+* Internal orchestrator shared by every Open Cloud resource client. Holds
+* the frozen client config, observability hooks, injected HTTP client and
+* sleep, and the per-effective-key rate-limit queue registry. Resource
+* classes compose one instance and dispatch every public method through
+* {@link ResourceClient.execute} with a per-method {@link ResourceMethodSpec}.
+* Not exported from any package subpath; reachable only via sibling
+* `src/resources/**` modules in this package.
+*/
+declare class ResourceClient {
+  #private;
+  /**
+  * Creates a new {@link ResourceClient}. Resolves the injected HTTP
+  * client and sleep (defaulting to fetch + `setTimeout`) and freezes the
+  * merged client config so subsequent calls cannot mutate it.
+  *
+  * @param options - Client-level configuration including the API key
+  *   and optional construction-time test seams.
+  */
+  constructor(options: OpenCloudClientOptions);
+  /**
+  * Dispatches a single resource-method call. Merges the frozen client
+  * config with the method's `methodDefaults` and the caller's optional
+  * per-request `options`, routes through the effective-apiKey rate-limit
+  * queue, runs the retry loop, and finally parses the response with the
+  * spec's parser.
+  *
+  * @param call - The per-method spec, resource-specific parameters, and
+  *   optional per-request overrides.
+  * @returns The parsed success payload or the {@link OpenCloudError} that
+  *   caused the request to fail. Never throws.
+  */
+  execute<P, T>(call: ExecuteCall<P, T>): Promise<Result<T, OpenCloudError>>;
+  /**
+  * Returns the sleep function used by this client instance.
+  *
+  * @returns The sleep function injected at construction time.
+  */
+  get sleep(): SleepFunc;
+}
+//#endregion
+//#region src/resources/storage/queues-group.d.ts
+/**
+* Operation Group on `StorageClient` that exposes the memory-store
+* queue endpoints. Queues are FIFO collections of opaque JSON values
+* with optional priority and TTL; consumers enqueue items, dequeue
+* them in batches, and acknowledge processed batches with a read
+* identifier.
+*/
+declare class MemoryStoreQueuesGroup {
+  #private;
+  /**
+  * Wraps the shared {@link ResourceClient} so the Operation Group
+  * routes calls through the same retry, hooks, and rate-limit queues
+  * as the rest of the parent client.
+  *
+  * @param inner - The shared {@link ResourceClient} owned by the
+  *   parent client.
+  */
+  constructor(inner: ResourceClient);
+  /**
+  * Dequeues up to `count` items from the front of the queue. Items
+  * returned become invisible to subsequent reads for
+  * `invisibilityWindow` seconds (default 30 server-side); they
+  * reappear once the window elapses unless acknowledged via
+  * `discard` with the returned `readId`.
+  *
+  * On 5xx, dequeue does not retry: the server may have set
+  * invisibility on a batch before the response failed, so a retry
+  * would return a *different* batch and the first one is lost until
+  * the window expires. Callers that can detect duplicates externally
+  * may opt back into 5xx retry per call by passing `retryableStatuses`
+  * on `options`.
+  *
+  * @param parameters - Universe and queue identifiers, plus optional
+  *   `count`, `allOrNothing`, and `invisibilityWindow`.
+  * @param options - Optional per-request overrides.
+  * @returns A {@link Result} wrapping the parsed {@link DequeueResult}
+  *   or the {@link OpenCloudError} that caused the request to fail.
+  */
+  dequeue(parameters: DequeueQueueItemsParameters, options?: RequestOptions): Promise<Result<DequeueResult, OpenCloudError>>;
+  /**
+  * Acknowledges a dequeued batch of items, removing them from the
+  * queue permanently. Pass the `readId` returned from the prior
+  * `dequeue` call. Without `discard`, the items reappear once the
+  * invisibility window elapses.
+  *
+  * The call is idempotent: a second `discard` with the same `readId`
+  * is a no-op once the batch has been acknowledged. The retry policy
+  * therefore retries both 429 and 5xx.
+  *
+  * @param parameters - Universe and queue identifiers, plus the
+  *   `readId` returned from a prior dequeue.
+  * @param options - Optional per-request overrides.
+  * @returns A {@link Result} wrapping `undefined` on success (the
+  *   server returns an empty body) or the {@link OpenCloudError}
+  *   that caused the request to fail.
+  */
+  discard(parameters: DiscardQueueItemsParameters, options?: RequestOptions): Promise<Result<undefined, OpenCloudError>>;
+  /**
+  * Enqueues a single item onto a memory-store queue. The queue is
+  * auto-created on first use; the queue identifier is any string the
+  * caller picks. Items with higher `priority` values are dequeued
+  * first; equal priorities preserve insertion order. Items expire
+  * and are removed automatically after `ttl` seconds, or after a
+  * server-default lifetime when omitted.
+  *
+  * @param parameters - Universe and queue identifiers, the opaque
+  *   payload, and optional `priority` and `ttl`.
+  * @param options - Optional per-request overrides (e.g. A different
+  *   {@link OpenCloudClientOptions.apiKey} for this call only).
+  * @returns A {@link Result} wrapping the parsed {@link QueueItem} or
+  *   the {@link OpenCloudError} that caused the request to fail.
+  */
+  enqueue(parameters: EnqueueQueueItemParameters, options?: RequestOptions): Promise<Result<QueueItem, OpenCloudError>>;
+}
+//#endregion
+//#region src/resources/storage/client.d.ts
+/**
+* Public client for the Roblox Open Cloud `Data and memory stores`
+* Feature. Today it covers memory-store queues via the
+* {@link StorageClient.queues} Operation Group; future Operation
+* Groups for sorted maps and data stores slot in as siblings on the
+* same client.
+*
+* Every method returns a `Result` so callers handle failure
+* explicitly; no thrown error ever escapes the client.
+*
+* @example
+*
+* ```ts
+* import { StorageClient } from "@bedrock-rbx/ocale/storage";
+*
+* const client = new StorageClient({ apiKey: "your-key" });
+* expect(client).toBeInstanceOf(StorageClient);
+* ```
+*/
+declare class StorageClient {
+  /** Memory-store queue Operation Group. */
+  readonly queues: MemoryStoreQueuesGroup;
+  /**
+  * Creates a new {@link StorageClient}. Configuration is frozen on
+  * construction; per-request overrides are accepted on each method.
+  *
+  * @param options - Client-level configuration including the API key.
+  */
+  constructor(options: OpenCloudClientOptions);
+}
+//#endregion
+export { type DequeueQueueItemsParameters, type DequeueResult, type DiscardQueueItemsParameters, type EnqueueQueueItemParameters, type QueueItem, StorageClient };
+//# sourceMappingURL=storage.d.mts.map

package/dist/storage.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.mts","names":[],"sources":["../src/domains/cloud-v2/memory-store-queues/types.ts","../src/internal/http/rate-limit-queue.ts","../src/internal/http/retry.ts","../src/internal/resource-client.ts","../src/resources/storage/queues-group.ts","../src/resources/storage/client.ts"],"mappings":";;;;;;AAIA;UAAiB,0BAAA;;;;;;;WAOP,IAAA,EAAM,OAAA,CAAQ,SAAA;;;;;AAwBxB;WAlBU,QAAA;;WAEA,OAAA;;;;;;WAMA,GAAA;;WAEA,UAAA;AAAA;;;;;;UAQO,SAAA;EAsBjB;EAAA,SApBU,EAAA;;;;;WAKA,IAAA,EAAM,OAAA,CAAQ,SAAA;;WAEd,SAAA,EAAW,IAAA;;WAEX,QAAA;EAyCV;EAAA,SAvCU,OAAA;;WAEA,UAAA;AAAA;;;;;UAOO,2BAAA;EA+CjB;;;;;EAAA,SAzCU,YAAA;;;;;WAKA,KAAA;;AC7DV;;;;WDmEU,kBAAA;;WAEA,OAAA;;WAEA,UAAA;AAAA;;;;;;;UASO,aAAA;;WAEP,KAAA,EAAO,aAAA,CAAc,SAAA;;;;AE3C/B;WFgDU,MAAA;AAAA;;;;;;AGxDV;;UHkEiB,2BAAA;;WAEP,OAAA;;WAEA,MAAA;;WAEA,UAAA;AAAA;;;;AA1GV;;;UCGiB,cAAA;;WAEP,YAAA;;;;;;WAMA,YAAA;AAAA;;;;ADXV;;;;;;;UEOiB,eAAA;;WAEP,MAAA;;WAEA,OAAA;EFYA;EAAA,SEVA,UAAA;EFkBO;EAAA,SEhBP,iBAAA,EAAmB,aAAA;;WAEnB,UAAA,GAAa,OAAA;;WAEb,OAAA;AAAA;AFkCV;AAAA,KEXY,UAAA;;;;;;;;;;;;;;AFXZ;UGGiB,kBAAA;;;;;;;;WAQP,YAAA,GAAe,UAAA,EAAY,CAAA,KAAM,MAAA,CAAO,WAAA,EAAa,cAAA;;WAErD,cAAA,EAAgB,OAAA,CAAQ,eAAA;;;;;AHSlC;;WGFU,UAAA,EAAY,UAAA;EHEL;EAAA,SGAP,cAAA,EAAgB,cAAA;;;;;;WAMhB,KAAA,GAAQ,QAAA,EAAU,YAAA,KAAiB,MAAA,CAAO,CAAA,EAAG,cAAA;EHwBvD;;;;;;;;;EAAA,SGdU,cAAA,GAAiB,aAAA;AAAA;;;;;;;;;UAWjB,WAAA;EF7EO;EAAA,SE+EP,OAAA,GAAU,cAAA;EF/EH;EAAA,SEiFP,UAAA,EAAY,CAAA;;WAEZ,IAAA,EAAM,kBAAA,CAAmB,CAAA,EAAG,CAAA;AAAA;AD/EtC;;;;;;;;;;;;;AC2BA;;;;;cAgGa,cAAA;EAAA;;;;;;;;;EAeZ,WAAA,CAAY,OAAA,EAAS,sBAAA;;;;;;;;;;;;;EAyBrB,OAAA,MAAA,CAA2B,IAAA,EAAM,WAAA,CAAY,CAAA,EAAG,CAAA,IAAK,OAAA,CAAQ,MAAA,CAAO,CAAA,EAAG,cAAA;;;;;;MAsC5D,KAAA,CAAA,GAAS,SAAA;AAAA;;;;;;;;;;cCtIR,sBAAA;EAAA;;;AJ3Cb;;;;;;EIsDC,WAAA,CAAY,KAAA,EAAO,cAAA;EJ7CC;;;;;;;;;;;;AAarB;;;;;;;;EIwDC,OAAA,CACC,UAAA,EAAY,2BAAA,EACZ,OAAA,GAAU,cAAA,GACR,OAAA,CAAQ,MAAA,CAAO,aAAA,EAAe,cAAA;;;AJ7BlC;;;;;;;;;;AAiBA;;;;;EIiCC,OAAA,CACC,UAAA,EAAY,2BAAA,EACZ,OAAA,GAAU,cAAA,GACR,OAAA,CAAQ,MAAA,YAAkB,cAAA;;;;;;;AHrI9B;;;;;;;;ACIA;EEoJC,OAAA,CACC,UAAA,EAAY,0BAAA,EACZ,OAAA,GAAU,cAAA,GACR,OAAA,CAAQ,MAAA,CAAO,SAAA,EAAW,cAAA;AAAA;;;;AJ9J9B;;;;;;;;;;;;;AA+BA;;;;;cKZa,aAAA;;WAEI,MAAA,EAAQ,sBAAA;;;;;;;EAQxB,WAAA,CAAY,OAAA,EAAS,sBAAA;AAAA"}