@anweather/game-plugin-ssdk 1.9.0 → 1.10.1

package/dist-types/runtime/blobClient.d.ts

@@ -0,0 +1,84 @@
+/** `save:{id}`, `player:{id}` or `world:{uuid}` -- see the model's doc. */
+export type BlobOwnerKey = `save:${string}` | `player:${string}` | `world:${string}`;
+export declare const blobOwner: {
+    save: (saveFileId: string) => BlobOwnerKey;
+    player: (participantId: string) => BlobOwnerKey;
+    world: (worldId: string) => BlobOwnerKey;
+};
+export interface BlobClientOptions {
+    /** The platform's base URL, e.g. http://platform:8080. */
+    platformUrl: string;
+    gameType: string;
+    /** The token this plugin registered with; sent as X-Plugin-Auth. */
+    authToken: string | undefined;
+    /** Per-request timeout. Keep it well inside ApplyMove's own RPC budget
+     * when calling from a move. Default 5000. */
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}
+export interface Blob<T = unknown> {
+    /** Absent when the blob doesn't exist. */
+    value?: T;
+    /** 0 when the blob doesn't exist -- the expectedVersion a create needs. */
+    version: number;
+    sizeBytes: number;
+    updatedAt?: string;
+}
+export interface BlobItem<T = unknown> extends Blob<T> {
+    key: string;
+}
+export interface BlobInfo {
+    key: string;
+    version: number;
+    sizeBytes: number;
+    updatedAt: string;
+}
+export interface BlobWrite {
+    key: string;
+    value: unknown;
+    /** The version the write is based on; 0 = only if absent. */
+    expectedVersion: number;
+}
+export type BlobErrorType = "VersionConflict" | "BlobTooLarge" | "BlobQuotaExceeded" | "BlobOwnerNotFound" | "InvalidBlobRequest" | "PluginUnauthorized";
+/** A refusal from the store. `details` is the error body: for
+ * VersionConflict `{key, expectedVersion, currentVersion}`, for
+ * BlobTooLarge `{key, sizeBytes, limitBytes}`, and so on -- see the
+ * model. Any other failure (network, timeout, a 5xx) is a plain Error. */
+export declare class BlobStoreError extends Error {
+    readonly type: BlobErrorType;
+    readonly status: number;
+    readonly details: Record<string, unknown>;
+    constructor(type: BlobErrorType, status: number, details: Record<string, unknown>);
+}
+export declare function isVersionConflict(e: unknown): e is BlobStoreError;
+export interface BlobClient {
+    get<T = unknown>(owner: BlobOwnerKey, key: string): Promise<Blob<T>>;
+    put(owner: BlobOwnerKey, key: string, value: unknown, expectedVersion: number): Promise<{
+        version: number;
+        sizeBytes: number;
+    }>;
+    /** Without expectedVersion the delete is unconditional. */
+    delete(owner: BlobOwnerKey, key: string, expectedVersion?: number): Promise<{
+        deleted: boolean;
+    }>;
+    /** One item per key, in the order asked; absent keys have version 0. */
+    batchGet(owner: BlobOwnerKey, keys: string[]): Promise<BlobItem[]>;
+    /** All or nothing: one stale write fails the lot with VersionConflict. */
+    batchPut(owner: BlobOwnerKey, writes: BlobWrite[]): Promise<BlobInfo[]>;
+    list(owner: BlobOwnerKey): Promise<{
+        items: BlobInfo[];
+        totalBytes: number;
+        quotaBytes: number;
+    }>;
+}
+export declare function createBlobClient(options: BlobClientOptions): BlobClient;
+/** Read `key`, apply `change` to its value (undefined when absent), and
+ * write the result conditional on the version read -- re-reading and
+ * re-applying on a VersionConflict, up to `maxAttempts` times. `change`
+ * must therefore be a pure merge of "what's stored now" and "what I want",
+ * never a blind overwrite: that is what makes concurrent writers to one
+ * shared document safe. Returning undefined leaves the blob as it is. */
+export declare function casUpdate<T>(client: BlobClient, owner: BlobOwnerKey, key: string, change: (current: T | undefined) => T | undefined, maxAttempts?: number): Promise<{
+    value: T | undefined;
+    version: number;
+}>;

package/dist-types/runtime/index.d.ts

@@ -8,3 +8,5 @@ export type { RegistrationOptions, RegistrationLoop } from "./registration";
 export { runConformance, assertConformance } from "./conformance";
 export type { ConformanceOptions, ConformanceReport } from "./conformance";
 export { PLUGIN_PROTOCOL_VERSION, runtimeVersion } from "./version";
+export { createBlobClient, casUpdate, blobOwner, BlobStoreError, isVersionConflict } from "./blobClient";
+export type { BlobClient, BlobClientOptions, BlobOwnerKey, Blob, BlobItem, BlobInfo, BlobWrite, BlobErrorType, } from "./blobClient";

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@anweather/game-plugin-ssdk",
     "description": "Generated GamePlugin RPC types/server (plugin-protocol/model/game-plugin.smithy) plus a hand-written Express bridge and default-handler wrapper (./runtime) -- see plugin-protocol/CLAUDE.md's \"Publishing for cross-repo plugins\".",
-    "version": "1.9.0",
+    "version": "1.10.1",
     "scripts": {
         "build": "concurrently 'npm:build:cjs' 'npm:build:es' 'npm:build:types'",
         "build:cjs": "tsc -p tsconfig.cjs.json",