castle-web-sdk 0.4.45 → 0.4.47

package/dist/save.d.ts

@@ -0,0 +1,197 @@
+import { CastleError } from "./errors";
+import type { Json } from "./types";
+export type SaveScope = "deck" | "user" | "private";
+export interface SaveTarget {
+    scope: SaveScope;
+    /** A user target's player. Omitted means the current player. */
+    subject?: string;
+    prefix: string;
+}
+/** Opaque. A reset of the deck's storage makes every older revision stale. */
+export type SaveRevision = string;
+/** Opaque proof of the latest claim on a target. */
+export type SaveWriter = string;
+export type SaveRows = Record<string, Json>;
+export type SaveSelection = {
+    prefix: string;
+} | {
+    keys: string[];
+};
+export interface SaveReadTarget {
+    target: SaveTarget;
+    /** Omitted reads the whole target. */
+    select?: SaveSelection;
+}
+export interface SaveSnapshot {
+    access: string;
+    targets: {
+        target: SaveTarget;
+        /** Null means the target has never been initialized. */
+        revision: SaveRevision | null;
+        rows: SaveRows;
+        /** True when the rows cover the whole target, not a selection of it. */
+        complete: boolean;
+    }[];
+}
+export interface SaveReceipt {
+    operationId: string;
+    access: string;
+    revisions: {
+        target: SaveTarget;
+        revision: SaveRevision;
+    }[];
+    writer?: SaveWriter;
+}
+export interface SaveCheck {
+    target: SaveTarget;
+    expectedRevision?: SaveRevision;
+    writer?: SaveWriter;
+}
+export interface SaveChange {
+    target: SaveTarget;
+    /** Null creates a target that has never been initialized. */
+    expectedRevision: SaveRevision | null;
+    writer?: SaveWriter;
+    put?: SaveRows;
+    remove?: string[];
+    /** Replaces every row of the target. Cannot be combined with put or remove. */
+    replace?: SaveRows;
+}
+export interface SaveTransactionInput {
+    operationId: string;
+    expectedAccess: string;
+    checks?: SaveCheck[];
+    changes: SaveChange[];
+}
+export interface SaveInitial {
+    target: SaveTarget;
+    rows: SaveRows;
+}
+export interface SaveClaimInput {
+    operationId: string;
+    expectedAccess?: string;
+    target: SaveTarget;
+    initial?: SaveInitial[];
+    /** Omitted loads the claimed and initial targets. */
+    load?: SaveReadTarget[];
+}
+export interface SaveInitializeInput {
+    operationId: string;
+    expectedAccess?: string;
+    initial: SaveInitial[];
+    /** Omitted loads the initial targets. */
+    load?: SaveReadTarget[];
+}
+export interface SaveOpened {
+    receipt: SaveReceipt;
+    snapshot: SaveSnapshot;
+}
+export interface SaveClaimed extends SaveOpened {
+    writer: SaveWriter;
+}
+export type SaveOperation = {
+    state: "committed";
+    receipt: SaveReceipt;
+} | {
+    state: "unknown";
+};
+export type SaveVerb = "snapshot" | "transaction" | "claim" | "initialize" | "operation";
+export interface SaveApi {
+    snapshot(input: {
+        targets: SaveReadTarget[];
+    }): Promise<SaveSnapshot>;
+    transaction(input: SaveTransactionInput): Promise<SaveReceipt>;
+    claim(input: SaveClaimInput): Promise<SaveClaimed>;
+    initialize(input: SaveInitializeInput): Promise<SaveOpened>;
+    operation(operationId: string): Promise<SaveOperation>;
+}
+export interface SaveBucketRead {
+    prefix: string;
+    select?: SaveSelection;
+}
+export interface SaveBucketApi {
+    /** This bucket's target for a prefix, for the root's multi-bucket calls. */
+    target(prefix: string): SaveTarget;
+    snapshot(input: SaveBucketRead): Promise<SaveSnapshot>;
+    transaction(input: {
+        operationId: string;
+        expectedAccess: string;
+        checks?: (Omit<SaveCheck, "target"> & {
+            prefix: string;
+        })[];
+        changes: (Omit<SaveChange, "target"> & {
+            prefix: string;
+        })[];
+    }): Promise<SaveReceipt>;
+    claim(input: {
+        operationId: string;
+        expectedAccess?: string;
+        prefix: string;
+        initial?: {
+            prefix: string;
+            rows: SaveRows;
+        }[];
+        load?: SaveBucketRead[];
+    }): Promise<SaveClaimed>;
+    initialize(input: {
+        operationId: string;
+        expectedAccess?: string;
+        initial: {
+            prefix: string;
+            rows: SaveRows;
+        }[];
+        load?: SaveBucketRead[];
+    }): Promise<SaveOpened>;
+    operation(operationId: string): Promise<SaveOperation>;
+}
+/** What a failed save says about itself, as the platform reports it. */
+export interface SaveErrorEnvelope {
+    code: string;
+    message: string;
+    operationId?: string;
+    retryable: boolean;
+    /** "unknown" means the request may still have committed. */
+    committed: boolean | "unknown";
+    /** The stored receipt, when the operation committed earlier. */
+    receipt?: SaveReceipt;
+    retryAfterMs?: number;
+    target?: SaveTarget;
+    [detail: string]: unknown;
+}
+export declare class SaveError extends CastleError {
+    readonly operationId?: string;
+    readonly retryable: boolean;
+    readonly committed: boolean | "unknown";
+    readonly receipt?: SaveReceipt;
+    readonly retryAfterMs?: number;
+    readonly target?: SaveTarget;
+    constructor(envelope: SaveErrorEnvelope);
+}
+/**
+ * Reads the envelope out of whatever a host or platform threw. A failure that
+ * does not say whether it committed is treated as one that might have.
+ */
+export declare function asSaveError(error: unknown, operationId?: string): SaveError;
+/**
+ * A session server has no current player, so it names a user target's player
+ * and cannot reach private storage.
+ */
+export declare function validateSaveTarget(target: SaveTarget, server?: boolean): SaveTarget;
+export declare function saveTargetKey(target: SaveTarget): string;
+/**
+ * Finds the caller's own target for one the platform names. The platform
+ * fills in the current player as a user target's subject, so a target the
+ * caller left without a subject matches any subject.
+ */
+export declare function matchSaveTarget(target: SaveTarget, candidates: readonly SaveTarget[]): SaveTarget;
+/** Validates and copies a request; the result is what goes on the wire. */
+export declare function encodeSaveInput(verb: SaveVerb, input: Record<string, unknown>, server?: boolean): Record<string, unknown>;
+/** Sends one encoded request; the transport behind it is the caller's. */
+export type SaveCall = (verb: SaveVerb, input: Record<string, unknown>) => Promise<unknown>;
+export declare function createSaveApi(call: SaveCall, server?: boolean): SaveApi;
+export declare function createSaveBucket(api: SaveApi, scope: SaveScope, subject?: string): SaveBucketApi;
+/**
+ * Refuses a request bigger than a transport carries. An atomic save is never
+ * split, so the whole encoded request has to fit.
+ */
+export declare function preflightSaveRequest(verb: SaveVerb, request: unknown, limitBytes: number): void;