@dcl/sdk 7.30.2-37804519171.commit-60e3717 → 7.30.2-37807847179.commit-24c42ea

package/server/env-var.js

@@ -0,0 +1,31 @@
+import { getStorageServerUrl } from './storage-url';
+import { assertIsServer, wrapSignedFetch } from './utils';
+const MODULE_NAME = 'EnvVar';
+/**
+ * EnvVar provides methods to fetch environment variables from the
+ * Server Side Storage service. This module only works when running
+ * on server-side scenes.
+ */
+export const EnvVar = {
+    /**
+     * Fetches a specific environment variable by key as plain text.
+     *
+     * @param key - The name of the environment variable to fetch
+     * @returns A promise that resolves to the plain text value, or empty string if not found
+     * @throws Error if not running on a server-side scene
+     */
+    async get(key) {
+        assertIsServer(MODULE_NAME);
+        const baseUrl = await getStorageServerUrl();
+        const url = `${baseUrl}/env/${encodeURIComponent(key)}`;
+        const [error, data] = await wrapSignedFetch({
+            url
+        });
+        if (error) {
+            console.error(`Failed to fetch environment variable '${key}': ${error}`);
+            return '';
+        }
+        return data?.value ?? '';
+    }
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZW52LXZhci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy9zZXJ2ZXIvZW52LXZhci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsbUJBQW1CLEVBQUUsTUFBTSxlQUFlLENBQUE7QUFDbkQsT0FBTyxFQUFFLGNBQWMsRUFBRSxlQUFlLEVBQUUsTUFBTSxTQUFTLENBQUE7QUFFekQsTUFBTSxXQUFXLEdBQUcsUUFBUSxDQUFBO0FBRTVCOzs7O0dBSUc7QUFDSCxNQUFNLENBQUMsTUFBTSxNQUFNLEdBQUc7SUFDcEI7Ozs7OztPQU1HO0lBQ0gsS0FBSyxDQUFDLEdBQUcsQ0FBQyxHQUFXO1FBQ25CLGNBQWMsQ0FBQyxXQUFXLENBQUMsQ0FBQTtRQUUzQixNQUFNLE9BQU8sR0FBRyxNQUFNLG1CQUFtQixFQUFFLENBQUE7UUFDM0MsTUFBTSxHQUFHLEdBQUcsR0FBRyxPQUFPLFFBQVEsa0JBQWtCLENBQUMsR0FBRyxDQUFDLEVBQUUsQ0FBQTtRQUV2RCxNQUFNLENBQUMsS0FBSyxFQUFFLElBQUksQ0FBQyxHQUFHLE1BQU0sZUFBZSxDQUFvQjtZQUM3RCxHQUFHO1NBQ0osQ0FBQyxDQUFBO1FBRUYsSUFBSSxLQUFLLEVBQUU7WUFDVCxPQUFPLENBQUMsS0FBSyxDQUFDLHlDQUF5QyxHQUFHLE1BQU0sS0FBSyxFQUFFLENBQUMsQ0FBQTtZQUN4RSxPQUFPLEVBQUUsQ0FBQTtTQUNWO1FBRUQsT0FBTyxJQUFJLEVBQUUsS0FBSyxJQUFJLEVBQUUsQ0FBQTtJQUMxQixDQUFDO0NBQ0YsQ0FBQSIsInNvdXJjZXNDb250ZW50IjpbImltcG9ydCB7IGdldFN0b3JhZ2VTZXJ2ZXJVcmwgfSBmcm9tICcuL3N0b3JhZ2UtdXJsJ1xuaW1wb3J0IHsgYXNzZXJ0SXNTZXJ2ZXIsIHdyYXBTaWduZWRGZXRjaCB9IGZyb20gJy4vdXRpbHMnXG5cbmNvbnN0IE1PRFVMRV9OQU1FID0gJ0VudlZhcidcblxuLyoqXG4gKiBFbnZWYXIgcHJvdmlkZXMgbWV0aG9kcyB0byBmZXRjaCBlbnZpcm9ubWVudCB2YXJpYWJsZXMgZnJvbSB0aGVcbiAqIFNlcnZlciBTaWRlIFN0b3JhZ2Ugc2VydmljZS4gVGhpcyBtb2R1bGUgb25seSB3b3JrcyB3aGVuIHJ1bm5pbmdcbiAqIG9uIHNlcnZlci1zaWRlIHNjZW5lcy5cbiAqL1xuZXhwb3J0IGNvbnN0IEVudlZhciA9IHtcbiAgLyoqXG4gICAqIEZldGNoZXMgYSBzcGVjaWZpYyBlbnZpcm9ubWVudCB2YXJpYWJsZSBieSBrZXkgYXMgcGxhaW4gdGV4dC5cbiAgICpcbiAgICogQHBhcmFtIGtleSAtIFRoZSBuYW1lIG9mIHRoZSBlbnZpcm9ubWVudCB2YXJpYWJsZSB0byBmZXRjaFxuICAgKiBAcmV0dXJucyBBIHByb21pc2UgdGhhdCByZXNvbHZlcyB0byB0aGUgcGxhaW4gdGV4dCB2YWx1ZSwgb3IgZW1wdHkgc3RyaW5nIGlmIG5vdCBmb3VuZFxuICAgKiBAdGhyb3dzIEVycm9yIGlmIG5vdCBydW5uaW5nIG9uIGEgc2VydmVyLXNpZGUgc2NlbmVcbiAgICovXG4gIGFzeW5jIGdldChrZXk6IHN0cmluZyk6IFByb21pc2U8c3RyaW5nPiB7XG4gICAgYXNzZXJ0SXNTZXJ2ZXIoTU9EVUxFX05BTUUpXG5cbiAgICBjb25zdCBiYXNlVXJsID0gYXdhaXQgZ2V0U3RvcmFnZVNlcnZlclVybCgpXG4gICAgY29uc3QgdXJsID0gYCR7YmFzZVVybH0vZW52LyR7ZW5jb2RlVVJJQ29tcG9uZW50KGtleSl9YFxuXG4gICAgY29uc3QgW2Vycm9yLCBkYXRhXSA9IGF3YWl0IHdyYXBTaWduZWRGZXRjaDx7IHZhbHVlOiBzdHJpbmcgfT4oe1xuICAgICAgdXJsXG4gICAgfSlcblxuICAgIGlmIChlcnJvcikge1xuICAgICAgY29uc29sZS5lcnJvcihgRmFpbGVkIHRvIGZldGNoIGVudmlyb25tZW50IHZhcmlhYmxlICcke2tleX0nOiAke2Vycm9yfWApXG4gICAgICByZXR1cm4gJydcbiAgICB9XG5cbiAgICByZXR1cm4gZGF0YT8udmFsdWUgPz8gJydcbiAgfVxufVxuIl19

package/server/index.d.ts

@@ -0,0 +1,2 @@
+export { EnvVar } from './env-var';
+export { Storage, IStorage, ISceneStorage, IPlayerStorage, GetOptions, GetValuesOptions, GetValuesResult, SetOptions, StorageOptions } from './storage';

package/server/index.js

@@ -0,0 +1,3 @@
+export { EnvVar } from './env-var';
+export { Storage } from './storage';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvc2VydmVyL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxNQUFNLEVBQUUsTUFBTSxXQUFXLENBQUE7QUFDbEMsT0FBTyxFQUNMLE9BQU8sRUFTUixNQUFNLFdBQVcsQ0FBQSIsInNvdXJjZXNDb250ZW50IjpbImV4cG9ydCB7IEVudlZhciB9IGZyb20gJy4vZW52LXZhcidcbmV4cG9ydCB7XG4gIFN0b3JhZ2UsXG4gIElTdG9yYWdlLFxuICBJU2NlbmVTdG9yYWdlLFxuICBJUGxheWVyU3RvcmFnZSxcbiAgR2V0T3B0aW9ucyxcbiAgR2V0VmFsdWVzT3B0aW9ucyxcbiAgR2V0VmFsdWVzUmVzdWx0LFxuICBTZXRPcHRpb25zLFxuICBTdG9yYWdlT3B0aW9uc1xufSBmcm9tICcuL3N0b3JhZ2UnXG4iXX0=

package/server/storage/constants.d.ts

@@ -0,0 +1,80 @@
+export declare const MODULE_NAME = "Storage";
+/**
+ * Options for getValues pagination and filtering.
+ */
+export interface GetValuesOptions {
+    prefix?: string;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Result of getValues with pagination metadata.
+ */
+export interface GetValuesResult {
+    /** Key-value entries for the current page. */
+    data: Array<{
+        key: string;
+        value: unknown;
+    }>;
+    pagination: {
+        offset: number;
+        total: number;
+    };
+}
+/**
+ * Per-call options for Storage get().
+ */
+export interface GetOptions {
+    /**
+     * When true, bypasses the read cache and forces a network read (the result
+     * still refreshes the cache). Concurrent gets for the same key still share
+     * one in-flight request. Default: false.
+     */
+    fresh?: boolean;
+}
+/**
+ * Per-call options for Storage set().
+ */
+export interface SetOptions {
+    /**
+     * When true, skips the network write if the serialized value matches the
+     * last value known to be stored for this key (from a previous successful
+     * set(), get() or getValues()). Overrides the configured default. Default: true.
+     */
+    skipIfUnchanged?: boolean;
+}
+/**
+ * Module-wide configuration for Storage, applied to both scene-scoped and
+ * player-scoped storage via Storage.configure().
+ */
+export interface StorageOptions {
+    /**
+     * Default for set()'s skipIfUnchanged when not passed per call. A skip only
+     * suppresses a proven no-op: the exact serialized value was confirmed stored
+     * by a previous network round-trip within cacheMaxAgeMs. Default: true.
+     */
+    skipIfUnchanged?: boolean;
+    /**
+     * When true, get() serves values from the local cache within cacheMaxAgeMs,
+     * including confirmed "not found" results, without a network request.
+     * Out-of-band writers (e.g. CLI storage commands) may not be visible for up
+     * to cacheMaxAgeMs; pass { fresh: true } per call to force a network read.
+     * Default: true.
+     */
+    cacheReads?: boolean;
+    /**
+     * Max cache entries per scope (scene / player) before oldest entries are
+     * evicted. Entries hold the serialized value body, so memory scales with
+     * value size — this bounds entry count, not bytes. Infinity removes the bound.
+     * Default: 512.
+     */
+    cacheMaxEntries?: number;
+    /**
+     * Max age of a cache entry in milliseconds, bounding both read-cache
+     * staleness and write-dedup trust; older entries are treated as unknown.
+     * The default is deliberately short so out-of-band writers (CLI storage
+     * commands, dashboards) become visible within a minute, while still
+     * absorbing hot per-frame reads. Infinity never expires. Default: 60000 (1 minute).
+     */
+    cacheMaxAgeMs?: number;
+}

package/server/storage/constants.js

@@ -0,0 +1,19 @@
+export const MODULE_NAME = 'Storage';
+/**
+ * Default values for the resolved storage configuration.
+ * @internal
+ */
+export const DEFAULT_STORAGE_CONFIG = {
+    skipIfUnchanged: true,
+    cacheReads: true,
+    cacheMaxEntries: 512,
+    cacheMaxAgeMs: 60 * 1000
+};
+/**
+ * Creates a mutable config object, later mutated by Storage.configure().
+ * @internal
+ */
+export function createStorageConfig(overrides) {
+    return { ...DEFAULT_STORAGE_CONFIG, ...overrides };
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29uc3RhbnRzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3NlcnZlci9zdG9yYWdlL2NvbnN0YW50cy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxNQUFNLENBQUMsTUFBTSxXQUFXLEdBQUcsU0FBUyxDQUFBO0FBOEZwQzs7O0dBR0c7QUFDSCxNQUFNLENBQUMsTUFBTSxzQkFBc0IsR0FBaUM7SUFDbEUsZUFBZSxFQUFFLElBQUk7SUFDckIsVUFBVSxFQUFFLElBQUk7SUFDaEIsZUFBZSxFQUFFLEdBQUc7SUFDcEIsYUFBYSxFQUFFLEVBQUUsR0FBRyxJQUFJO0NBQ3pCLENBQUE7QUFFRDs7O0dBR0c7QUFDSCxNQUFNLFVBQVUsbUJBQW1CLENBQUMsU0FBMEI7SUFDNUQsT0FBTyxFQUFFLEdBQUcsc0JBQXNCLEVBQUUsR0FBRyxTQUFTLEVBQUUsQ0FBQTtBQUNwRCxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiZXhwb3J0IGNvbnN0IE1PRFVMRV9OQU1FID0gJ1N0b3JhZ2UnXG5cbi8qKlxuICogT3B0aW9ucyBmb3IgZ2V0VmFsdWVzIHBhZ2luYXRpb24gYW5kIGZpbHRlcmluZy5cbiAqL1xuZXhwb3J0IGludGVyZmFjZSBHZXRWYWx1ZXNPcHRpb25zIHtcbiAgcHJlZml4Pzogc3RyaW5nXG4gIGxpbWl0PzogbnVtYmVyXG4gIG9mZnNldD86IG51bWJlclxufVxuXG4vKipcbiAqIFJlc3VsdCBvZiBnZXRWYWx1ZXMgd2l0aCBwYWdpbmF0aW9uIG1ldGFkYXRhLlxuICovXG5leHBvcnQgaW50ZXJmYWNlIEdldFZhbHVlc1Jlc3VsdCB7XG4gIC8qKiBLZXktdmFsdWUgZW50cmllcyBmb3IgdGhlIGN1cnJlbnQgcGFnZS4gKi9cbiAgZGF0YTogQXJyYXk8eyBrZXk6IHN0cmluZzsgdmFsdWU6IHVua25vd24gfT5cbiAgcGFnaW5hdGlvbjoge1xuICAgIG9mZnNldDogbnVtYmVyXG4gICAgdG90YWw6IG51bWJlclxuICB9XG59XG5cbi8qKlxuICogUGVyLWNhbGwgb3B0aW9ucyBmb3IgU3RvcmFnZSBnZXQoKS5cbiAqL1xuZXhwb3J0IGludGVyZmFjZSBHZXRPcHRpb25zIHtcbiAgLyoqXG4gICAqIFdoZW4gdHJ1ZSwgYnlwYXNzZXMgdGhlIHJlYWQgY2FjaGUgYW5kIGZvcmNlcyBhIG5ldHdvcmsgcmVhZCAodGhlIHJlc3VsdFxuICAgKiBzdGlsbCByZWZyZXNoZXMgdGhlIGNhY2hlKS4gQ29uY3VycmVudCBnZXRzIGZvciB0aGUgc2FtZSBrZXkgc3RpbGwgc2hhcmVcbiAgICogb25lIGluLWZsaWdodCByZXF1ZXN0LiBEZWZhdWx0OiBmYWxzZS5cbiAgICovXG4gIGZyZXNoPzogYm9vbGVhblxufVxuXG4vKipcbiAqIFBlci1jYWxsIG9wdGlvbnMgZm9yIFN0b3JhZ2Ugc2V0KCkuXG4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgU2V0T3B0aW9ucyB7XG4gIC8qKlxuICAgKiBXaGVuIHRydWUsIHNraXBzIHRoZSBuZXR3b3JrIHdyaXRlIGlmIHRoZSBzZXJpYWxpemVkIHZhbHVlIG1hdGNoZXMgdGhlXG4gICAqIGxhc3QgdmFsdWUga25vd24gdG8gYmUgc3RvcmVkIGZvciB0aGlzIGtleSAoZnJvbSBhIHByZXZpb3VzIHN1Y2Nlc3NmdWxcbiAgICogc2V0KCksIGdldCgpIG9yIGdldFZhbHVlcygpKS4gT3ZlcnJpZGVzIHRoZSBjb25maWd1cmVkIGRlZmF1bHQuIERlZmF1bHQ6IHRydWUuXG4gICAqL1xuICBza2lwSWZVbmNoYW5nZWQ/OiBib29sZWFuXG59XG5cbi8qKlxuICogTW9kdWxlLXdpZGUgY29uZmlndXJhdGlvbiBmb3IgU3RvcmFnZSwgYXBwbGllZCB0byBib3RoIHNjZW5lLXNjb3BlZCBhbmRcbiAqIHBsYXllci1zY29wZWQgc3RvcmFnZSB2aWEgU3RvcmFnZS5jb25maWd1cmUoKS5cbiAqL1xuZXhwb3J0IGludGVyZmFjZSBTdG9yYWdlT3B0aW9ucyB7XG4gIC8qKlxuICAgKiBEZWZhdWx0IGZvciBzZXQoKSdzIHNraXBJZlVuY2hhbmdlZCB3aGVuIG5vdCBwYXNzZWQgcGVyIGNhbGwuIEEgc2tpcCBvbmx5XG4gICAqIHN1cHByZXNzZXMgYSBwcm92ZW4gbm8tb3A6IHRoZSBleGFjdCBzZXJpYWxpemVkIHZhbHVlIHdhcyBjb25maXJtZWQgc3RvcmVkXG4gICAqIGJ5IGEgcHJldmlvdXMgbmV0d29yayByb3VuZC10cmlwIHdpdGhpbiBjYWNoZU1heEFnZU1zLiBEZWZhdWx0OiB0cnVlLlxuICAgKi9cbiAgc2tpcElmVW5jaGFuZ2VkPzogYm9vbGVhblxuICAvKipcbiAgICogV2hlbiB0cnVlLCBnZXQoKSBzZXJ2ZXMgdmFsdWVzIGZyb20gdGhlIGxvY2FsIGNhY2hlIHdpdGhpbiBjYWNoZU1heEFnZU1zLFxuICAgKiBpbmNsdWRpbmcgY29uZmlybWVkIFwibm90IGZvdW5kXCIgcmVzdWx0cywgd2l0aG91dCBhIG5ldHdvcmsgcmVxdWVzdC5cbiAgICogT3V0LW9mLWJhbmQgd3JpdGVycyAoZS5nLiBDTEkgc3RvcmFnZSBjb21tYW5kcykgbWF5IG5vdCBiZSB2aXNpYmxlIGZvciB1cFxuICAgKiB0byBjYWNoZU1heEFnZU1zOyBwYXNzIHsgZnJlc2g6IHRydWUgfSBwZXIgY2FsbCB0byBmb3JjZSBhIG5ldHdvcmsgcmVhZC5cbiAgICogRGVmYXVsdDogdHJ1ZS5cbiAgICovXG4gIGNhY2hlUmVhZHM/OiBib29sZWFuXG4gIC8qKlxuICAgKiBNYXggY2FjaGUgZW50cmllcyBwZXIgc2NvcGUgKHNjZW5lIC8gcGxheWVyKSBiZWZvcmUgb2xkZXN0IGVudHJpZXMgYXJlXG4gICAqIGV2aWN0ZWQuIEVudHJpZXMgaG9sZCB0aGUgc2VyaWFsaXplZCB2YWx1ZSBib2R5LCBzbyBtZW1vcnkgc2NhbGVzIHdpdGhcbiAgICogdmFsdWUgc2l6ZSDigJQgdGhpcyBib3VuZHMgZW50cnkgY291bnQsIG5vdCBieXRlcy4gSW5maW5pdHkgcmVtb3ZlcyB0aGUgYm91bmQuXG4gICAqIERlZmF1bHQ6IDUxMi5cbiAgICovXG4gIGNhY2hlTWF4RW50cmllcz86IG51bWJlclxuICAvKipcbiAgICogTWF4IGFnZSBvZiBhIGNhY2hlIGVudHJ5IGluIG1pbGxpc2Vjb25kcywgYm91bmRpbmcgYm90aCByZWFkLWNhY2hlXG4gICAqIHN0YWxlbmVzcyBhbmQgd3JpdGUtZGVkdXAgdHJ1c3Q7IG9sZGVyIGVudHJpZXMgYXJlIHRyZWF0ZWQgYXMgdW5rbm93bi5cbiAgICogVGhlIGRlZmF1bHQgaXMgZGVsaWJlcmF0ZWx5IHNob3J0IHNvIG91dC1vZi1iYW5kIHdyaXRlcnMgKENMSSBzdG9yYWdlXG4gICAqIGNvbW1hbmRzLCBkYXNoYm9hcmRzKSBiZWNvbWUgdmlzaWJsZSB3aXRoaW4gYSBtaW51dGUsIHdoaWxlIHN0aWxsXG4gICAqIGFic29yYmluZyBob3QgcGVyLWZyYW1lIHJlYWRzLiBJbmZpbml0eSBuZXZlciBleHBpcmVzLiBEZWZhdWx0OiA2MDAwMCAoMSBtaW51dGUpLlxuICAgKi9cbiAgY2FjaGVNYXhBZ2VNcz86IG51bWJlclxufVxuXG4vKipcbiAqIEZ1bGx5LXJlc29sdmVkIHN0b3JhZ2UgY29uZmlndXJhdGlvbiBzaGFyZWQgYnkgc2NlbmUgYW5kIHBsYXllciBzdG9yYWdlLlxuICogQGludGVybmFsXG4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgU3RvcmFnZUNvbmZpZ1N0YXRlIHtcbiAgc2tpcElmVW5jaGFuZ2VkOiBib29sZWFuXG4gIGNhY2hlUmVhZHM6IGJvb2xlYW5cbiAgY2FjaGVNYXhFbnRyaWVzOiBudW1iZXJcbiAgY2FjaGVNYXhBZ2VNczogbnVtYmVyXG59XG5cbi8qKlxuICogRGVmYXVsdCB2YWx1ZXMgZm9yIHRoZSByZXNvbHZlZCBzdG9yYWdlIGNvbmZpZ3VyYXRpb24uXG4gKiBAaW50ZXJuYWxcbiAqL1xuZXhwb3J0IGNvbnN0IERFRkFVTFRfU1RPUkFHRV9DT05GSUc6IFJlYWRvbmx5PFN0b3JhZ2VDb25maWdTdGF0ZT4gPSB7XG4gIHNraXBJZlVuY2hhbmdlZDogdHJ1ZSxcbiAgY2FjaGVSZWFkczogdHJ1ZSxcbiAgY2FjaGVNYXhFbnRyaWVzOiA1MTIsXG4gIGNhY2hlTWF4QWdlTXM6IDYwICogMTAwMFxufVxuXG4vKipcbiAqIENyZWF0ZXMgYSBtdXRhYmxlIGNvbmZpZyBvYmplY3QsIGxhdGVyIG11dGF0ZWQgYnkgU3RvcmFnZS5jb25maWd1cmUoKS5cbiAqIEBpbnRlcm5hbFxuICovXG5leHBvcnQgZnVuY3Rpb24gY3JlYXRlU3RvcmFnZUNvbmZpZyhvdmVycmlkZXM/OiBTdG9yYWdlT3B0aW9ucyk6IFN0b3JhZ2VDb25maWdTdGF0ZSB7XG4gIHJldHVybiB7IC4uLkRFRkFVTFRfU1RPUkFHRV9DT05GSUcsIC4uLm92ZXJyaWRlcyB9XG59XG4iXX0=

package/server/storage/error-message.d.ts

@@ -0,0 +1 @@
+export {};

package/server/storage/error-message.js

@@ -0,0 +1,9 @@
+/**
+ * The message of a thrown value, or `fallback` when it carries none.
+ * @internal
+ */
+export function errorMessage(error, fallback = 'unknown error') {
+    const message = error instanceof Error ? error.message : typeof error === 'string' ? error : '';
+    return message || fallback;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXJyb3ItbWVzc2FnZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9zZXJ2ZXIvc3RvcmFnZS9lcnJvci1tZXNzYWdlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7R0FHRztBQUNILE1BQU0sVUFBVSxZQUFZLENBQUMsS0FBYyxFQUFFLFFBQVEsR0FBRyxlQUFlO0lBQ3JFLE1BQU0sT0FBTyxHQUFHLEtBQUssWUFBWSxLQUFLLENBQUMsQ0FBQyxDQUFDLEtBQUssQ0FBQyxPQUFPLENBQUMsQ0FBQyxDQUFDLE9BQU8sS0FBSyxLQUFLLFFBQVEsQ0FBQyxDQUFDLENBQUMsS0FBSyxDQUFDLENBQUMsQ0FBQyxFQUFFLENBQUE7SUFDL0YsT0FBTyxPQUFPLElBQUksUUFBUSxDQUFBO0FBQzVCLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvKipcbiAqIFRoZSBtZXNzYWdlIG9mIGEgdGhyb3duIHZhbHVlLCBvciBgZmFsbGJhY2tgIHdoZW4gaXQgY2FycmllcyBub25lLlxuICogQGludGVybmFsXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBlcnJvck1lc3NhZ2UoZXJyb3I6IHVua25vd24sIGZhbGxiYWNrID0gJ3Vua25vd24gZXJyb3InKTogc3RyaW5nIHtcbiAgY29uc3QgbWVzc2FnZSA9IGVycm9yIGluc3RhbmNlb2YgRXJyb3IgPyBlcnJvci5tZXNzYWdlIDogdHlwZW9mIGVycm9yID09PSAnc3RyaW5nJyA/IGVycm9yIDogJydcbiAgcmV0dXJuIG1lc3NhZ2UgfHwgZmFsbGJhY2tcbn1cbiJdfQ==

package/server/storage/index.d.ts

@@ -0,0 +1,54 @@
+import { StorageOptions } from './constants';
+import { ISceneStorage } from './scene';
+import { IPlayerStorage } from './player';
+export { GetOptions, GetValuesOptions, GetValuesResult, SetOptions, StorageOptions } from './constants';
+export { ISceneStorage } from './scene';
+export { IPlayerStorage } from './player';
+/**
+ * Storage interface with methods for scene-scoped and player-scoped storage.
+ */
+export interface IStorage extends ISceneStorage {
+    /** Player-scoped storage for key-value pairs */
+    player: IPlayerStorage;
+    /**
+     * Sets module-wide defaults for both scene-scoped and player-scoped storage.
+     * Merges the given partial options into the current configuration.
+     * Note: cacheMaxEntries applies per scope (scene and player each keep their
+     * own cache) and bounds entry count, not bytes (entries hold serialized
+     * value bodies).
+     */
+    configure(options: StorageOptions): void;
+}
+/**
+ * Storage provides methods to store and retrieve key-value data from the
+ * Server Side Storage service.
+ *
+ * - Use Storage.get/set/delete/getValues for scene-scoped storage
+ * - Use Storage.player.get/set/delete/getValues for player-scoped storage
+ * - Use Storage.configure to change module-wide defaults (e.g. skipIfUnchanged, cacheReads)
+ *
+ * A failure is never reported as absence. A read that fails throws; get() resolves
+ * null only for a confirmed absence (a 404, or a delete that landed) or a stored
+ * JSON null, and getValues() returns an empty page only for a genuinely empty
+ * listing. A delete that fails throws, and resolves false only for a confirmed 404.
+ * set() reports failure through its boolean result, and throws for a value that
+ * cannot be JSON-serialized. A get() issued while writes to its key are pending
+ * waits for them, so it reflects them; getValues() does not wait. Nothing is
+ * retried — that is the caller's to decide.
+ *
+ * Reads are cached by default: get() serves values known from a network
+ * round-trip within the last cacheMaxAgeMs (including confirmed "not found"
+ * results) without hitting the service, and concurrent gets for the same key
+ * share one request. Overlapping writes to the same key are serialized so the
+ * service commits them in issue order, and rapid writes coalesce to the
+ * latest value; a set()/delete() settles once its own write, or the newer
+ * write that replaced it, lands or fails. By default (skipIfUnchanged)
+ * an unchanged set is skipped, but only when a previous confirmed round-trip
+ * proved the exact value is already stored. Out-of-band writers (e.g. CLI storage commands)
+ * may not be visible for up to cacheMaxAgeMs; use get(key, { fresh: true })
+ * for an authoritative read or Storage.configure({ cacheReads: false }) to
+ * disable read caching.
+ *
+ * This module only works when running on server-side scenes.
+ */
+export declare const Storage: IStorage;

package/server/storage/index.js

@@ -0,0 +1,60 @@
+import { createStorageConfig } from './constants';
+import { createSceneStorage } from './scene';
+import { createPlayerStorage } from './player';
+/**
+ * Creates the Storage module with scene-scoped and player-scoped storage.
+ */
+const createStorage = () => {
+    const config = createStorageConfig();
+    const sceneStorage = createSceneStorage(config);
+    const playerStorage = createPlayerStorage(config);
+    return {
+        // Spread scene storage methods at top level
+        get: sceneStorage.get,
+        set: sceneStorage.set,
+        delete: sceneStorage.delete,
+        getValues: sceneStorage.getValues,
+        // Keep player as nested property
+        player: playerStorage,
+        configure(options) {
+            for (const [key, value] of Object.entries(options)) {
+                if (value !== undefined)
+                    config[key] = value;
+            }
+        }
+    };
+};
+/**
+ * Storage provides methods to store and retrieve key-value data from the
+ * Server Side Storage service.
+ *
+ * - Use Storage.get/set/delete/getValues for scene-scoped storage
+ * - Use Storage.player.get/set/delete/getValues for player-scoped storage
+ * - Use Storage.configure to change module-wide defaults (e.g. skipIfUnchanged, cacheReads)
+ *
+ * A failure is never reported as absence. A read that fails throws; get() resolves
+ * null only for a confirmed absence (a 404, or a delete that landed) or a stored
+ * JSON null, and getValues() returns an empty page only for a genuinely empty
+ * listing. A delete that fails throws, and resolves false only for a confirmed 404.
+ * set() reports failure through its boolean result, and throws for a value that
+ * cannot be JSON-serialized. A get() issued while writes to its key are pending
+ * waits for them, so it reflects them; getValues() does not wait. Nothing is
+ * retried — that is the caller's to decide.
+ *
+ * Reads are cached by default: get() serves values known from a network
+ * round-trip within the last cacheMaxAgeMs (including confirmed "not found"
+ * results) without hitting the service, and concurrent gets for the same key
+ * share one request. Overlapping writes to the same key are serialized so the
+ * service commits them in issue order, and rapid writes coalesce to the
+ * latest value; a set()/delete() settles once its own write, or the newer
+ * write that replaced it, lands or fails. By default (skipIfUnchanged)
+ * an unchanged set is skipped, but only when a previous confirmed round-trip
+ * proved the exact value is already stored. Out-of-band writers (e.g. CLI storage commands)
+ * may not be visible for up to cacheMaxAgeMs; use get(key, { fresh: true })
+ * for an authoritative read or Storage.configure({ cacheReads: false }) to
+ * disable read caching.
+ *
+ * This module only works when running on server-side scenes.
+ */
+export const Storage = createStorage();
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvc2VydmVyL3N0b3JhZ2UvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLG1CQUFtQixFQUFrQixNQUFNLGFBQWEsQ0FBQTtBQUNqRSxPQUFPLEVBQUUsa0JBQWtCLEVBQWlCLE1BQU0sU0FBUyxDQUFBO0FBQzNELE9BQU8sRUFBRSxtQkFBbUIsRUFBa0IsTUFBTSxVQUFVLENBQUE7QUF3QjlEOztHQUVHO0FBQ0gsTUFBTSxhQUFhLEdBQUcsR0FBYSxFQUFFO0lBQ25DLE1BQU0sTUFBTSxHQUFHLG1CQUFtQixFQUFFLENBQUE7SUFDcEMsTUFBTSxZQUFZLEdBQUcsa0JBQWtCLENBQUMsTUFBTSxDQUFDLENBQUE7SUFDL0MsTUFBTSxhQUFhLEdBQUcsbUJBQW1CLENBQUMsTUFBTSxDQUFDLENBQUE7SUFFakQsT0FBTztRQUNMLDRDQUE0QztRQUM1QyxHQUFHLEVBQUUsWUFBWSxDQUFDLEdBQUc7UUFDckIsR0FBRyxFQUFFLFlBQVksQ0FBQyxHQUFHO1FBQ3JCLE1BQU0sRUFBRSxZQUFZLENBQUMsTUFBTTtRQUMzQixTQUFTLEVBQUUsWUFBWSxDQUFDLFNBQVM7UUFDakMsaUNBQWlDO1FBQ2pDLE1BQU0sRUFBRSxhQUFhO1FBQ3JCLFNBQVMsQ0FBQyxPQUF1QjtZQUMvQixLQUFLLE1BQU0sQ0FBQyxHQUFHLEVBQUUsS0FBSyxDQUFDLElBQUksTUFBTSxDQUFDLE9BQU8sQ0FBQyxPQUFPLENBQUMsRUFBRTtnQkFDbEQsSUFBSSxLQUFLLEtBQUssU0FBUztvQkFBRyxNQUE2QyxDQUFDLEdBQUcsQ0FBQyxHQUFHLEtBQUssQ0FBQTthQUNyRjtRQUNILENBQUM7S0FDRixDQUFBO0FBQ0gsQ0FBQyxDQUFBO0FBRUQ7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7R0ErQkc7QUFDSCxNQUFNLENBQUMsTUFBTSxPQUFPLEdBQWEsYUFBYSxFQUFFLENBQUEiLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgeyBjcmVhdGVTdG9yYWdlQ29uZmlnLCBTdG9yYWdlT3B0aW9ucyB9IGZyb20gJy4vY29uc3RhbnRzJ1xuaW1wb3J0IHsgY3JlYXRlU2NlbmVTdG9yYWdlLCBJU2NlbmVTdG9yYWdlIH0gZnJvbSAnLi9zY2VuZSdcbmltcG9ydCB7IGNyZWF0ZVBsYXllclN0b3JhZ2UsIElQbGF5ZXJTdG9yYWdlIH0gZnJvbSAnLi9wbGF5ZXInXG5cbi8vIFJlLWV4cG9ydCBpbnRlcmZhY2VzIGFuZCB0eXBlc1xuZXhwb3J0IHsgR2V0T3B0aW9ucywgR2V0VmFsdWVzT3B0aW9ucywgR2V0VmFsdWVzUmVzdWx0LCBTZXRPcHRpb25zLCBTdG9yYWdlT3B0aW9ucyB9IGZyb20gJy4vY29uc3RhbnRzJ1xuZXhwb3J0IHsgSVNjZW5lU3RvcmFnZSB9IGZyb20gJy4vc2NlbmUnXG5leHBvcnQgeyBJUGxheWVyU3RvcmFnZSB9IGZyb20gJy4vcGxheWVyJ1xuXG4vKipcbiAqIFN0b3JhZ2UgaW50ZXJmYWNlIHdpdGggbWV0aG9kcyBmb3Igc2NlbmUtc2NvcGVkIGFuZCBwbGF5ZXItc2NvcGVkIHN0b3JhZ2UuXG4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgSVN0b3JhZ2UgZXh0ZW5kcyBJU2NlbmVTdG9yYWdlIHtcbiAgLyoqIFBsYXllci1zY29wZWQgc3RvcmFnZSBmb3Iga2V5LXZhbHVlIHBhaXJzICovXG4gIHBsYXllcjogSVBsYXllclN0b3JhZ2VcblxuICAvKipcbiAgICogU2V0cyBtb2R1bGUtd2lkZSBkZWZhdWx0cyBmb3IgYm90aCBzY2VuZS1zY29wZWQgYW5kIHBsYXllci1zY29wZWQgc3RvcmFnZS5cbiAgICogTWVyZ2VzIHRoZSBnaXZlbiBwYXJ0aWFsIG9wdGlvbnMgaW50byB0aGUgY3VycmVudCBjb25maWd1cmF0aW9uLlxuICAgKiBOb3RlOiBjYWNoZU1heEVudHJpZXMgYXBwbGllcyBwZXIgc2NvcGUgKHNjZW5lIGFuZCBwbGF5ZXIgZWFjaCBrZWVwIHRoZWlyXG4gICAqIG93biBjYWNoZSkgYW5kIGJvdW5kcyBlbnRyeSBjb3VudCwgbm90IGJ5dGVzIChlbnRyaWVzIGhvbGQgc2VyaWFsaXplZFxuICAgKiB2YWx1ZSBib2RpZXMpLlxuICAgKi9cbiAgY29uZmlndXJlKG9wdGlvbnM6IFN0b3JhZ2VPcHRpb25zKTogdm9pZFxufVxuXG4vKipcbiAqIENyZWF0ZXMgdGhlIFN0b3JhZ2UgbW9kdWxlIHdpdGggc2NlbmUtc2NvcGVkIGFuZCBwbGF5ZXItc2NvcGVkIHN0b3JhZ2UuXG4gKi9cbmNvbnN0IGNyZWF0ZVN0b3JhZ2UgPSAoKTogSVN0b3JhZ2UgPT4ge1xuICBjb25zdCBjb25maWcgPSBjcmVhdGVTdG9yYWdlQ29uZmlnKClcbiAgY29uc3Qgc2NlbmVTdG9yYWdlID0gY3JlYXRlU2NlbmVTdG9yYWdlKGNvbmZpZylcbiAgY29uc3QgcGxheWVyU3RvcmFnZSA9IGNyZWF0ZVBsYXllclN0b3JhZ2UoY29uZmlnKVxuXG4gIHJldHVybiB7XG4gICAgLy8gU3ByZWFkIHNjZW5lIHN0b3JhZ2UgbWV0aG9kcyBhdCB0b3AgbGV2ZWxcbiAgICBnZXQ6IHNjZW5lU3RvcmFnZS5nZXQsXG4gICAgc2V0OiBzY2VuZVN0b3JhZ2Uuc2V0LFxuICAgIGRlbGV0ZTogc2NlbmVTdG9yYWdlLmRlbGV0ZSxcbiAgICBnZXRWYWx1ZXM6IHNjZW5lU3RvcmFnZS5nZXRWYWx1ZXMsXG4gICAgLy8gS2VlcCBwbGF5ZXIgYXMgbmVzdGVkIHByb3BlcnR5XG4gICAgcGxheWVyOiBwbGF5ZXJTdG9yYWdlLFxuICAgIGNvbmZpZ3VyZShvcHRpb25zOiBTdG9yYWdlT3B0aW9ucyk6IHZvaWQge1xuICAgICAgZm9yIChjb25zdCBba2V5LCB2YWx1ZV0gb2YgT2JqZWN0LmVudHJpZXMob3B0aW9ucykpIHtcbiAgICAgICAgaWYgKHZhbHVlICE9PSB1bmRlZmluZWQpIChjb25maWcgYXMgdW5rbm93biBhcyBSZWNvcmQ8c3RyaW5nLCB1bmtub3duPilba2V5XSA9IHZhbHVlXG4gICAgICB9XG4gICAgfVxuICB9XG59XG5cbi8qKlxuICogU3RvcmFnZSBwcm92aWRlcyBtZXRob2RzIHRvIHN0b3JlIGFuZCByZXRyaWV2ZSBrZXktdmFsdWUgZGF0YSBmcm9tIHRoZVxuICogU2VydmVyIFNpZGUgU3RvcmFnZSBzZXJ2aWNlLlxuICpcbiAqIC0gVXNlIFN0b3JhZ2UuZ2V0L3NldC9kZWxldGUvZ2V0VmFsdWVzIGZvciBzY2VuZS1zY29wZWQgc3RvcmFnZVxuICogLSBVc2UgU3RvcmFnZS5wbGF5ZXIuZ2V0L3NldC9kZWxldGUvZ2V0VmFsdWVzIGZvciBwbGF5ZXItc2NvcGVkIHN0b3JhZ2VcbiAqIC0gVXNlIFN0b3JhZ2UuY29uZmlndXJlIHRvIGNoYW5nZSBtb2R1bGUtd2lkZSBkZWZhdWx0cyAoZS5nLiBza2lwSWZVbmNoYW5nZWQsIGNhY2hlUmVhZHMpXG4gKlxuICogQSBmYWlsdXJlIGlzIG5ldmVyIHJlcG9ydGVkIGFzIGFic2VuY2UuIEEgcmVhZCB0aGF0IGZhaWxzIHRocm93czsgZ2V0KCkgcmVzb2x2ZXNcbiAqIG51bGwgb25seSBmb3IgYSBjb25maXJtZWQgYWJzZW5jZSAoYSA0MDQsIG9yIGEgZGVsZXRlIHRoYXQgbGFuZGVkKSBvciBhIHN0b3JlZFxuICogSlNPTiBudWxsLCBhbmQgZ2V0VmFsdWVzKCkgcmV0dXJucyBhbiBlbXB0eSBwYWdlIG9ubHkgZm9yIGEgZ2VudWluZWx5IGVtcHR5XG4gKiBsaXN0aW5nLiBBIGRlbGV0ZSB0aGF0IGZhaWxzIHRocm93cywgYW5kIHJlc29sdmVzIGZhbHNlIG9ubHkgZm9yIGEgY29uZmlybWVkIDQwNC5cbiAqIHNldCgpIHJlcG9ydHMgZmFpbHVyZSB0aHJvdWdoIGl0cyBib29sZWFuIHJlc3VsdCwgYW5kIHRocm93cyBmb3IgYSB2YWx1ZSB0aGF0XG4gKiBjYW5ub3QgYmUgSlNPTi1zZXJpYWxpemVkLiBBIGdldCgpIGlzc3VlZCB3aGlsZSB3cml0ZXMgdG8gaXRzIGtleSBhcmUgcGVuZGluZ1xuICogd2FpdHMgZm9yIHRoZW0sIHNvIGl0IHJlZmxlY3RzIHRoZW07IGdldFZhbHVlcygpIGRvZXMgbm90IHdhaXQuIE5vdGhpbmcgaXNcbiAqIHJldHJpZWQg4oCUIHRoYXQgaXMgdGhlIGNhbGxlcidzIHRvIGRlY2lkZS5cbiAqXG4gKiBSZWFkcyBhcmUgY2FjaGVkIGJ5IGRlZmF1bHQ6IGdldCgpIHNlcnZlcyB2YWx1ZXMga25vd24gZnJvbSBhIG5ldHdvcmtcbiAqIHJvdW5kLXRyaXAgd2l0aGluIHRoZSBsYXN0IGNhY2hlTWF4QWdlTXMgKGluY2x1ZGluZyBjb25maXJtZWQgXCJub3QgZm91bmRcIlxuICogcmVzdWx0cykgd2l0aG91dCBoaXR0aW5nIHRoZSBzZXJ2aWNlLCBhbmQgY29uY3VycmVudCBnZXRzIGZvciB0aGUgc2FtZSBrZXlcbiAqIHNoYXJlIG9uZSByZXF1ZXN0LiBPdmVybGFwcGluZyB3cml0ZXMgdG8gdGhlIHNhbWUga2V5IGFyZSBzZXJpYWxpemVkIHNvIHRoZVxuICogc2VydmljZSBjb21taXRzIHRoZW0gaW4gaXNzdWUgb3JkZXIsIGFuZCByYXBpZCB3cml0ZXMgY29hbGVzY2UgdG8gdGhlXG4gKiBsYXRlc3QgdmFsdWU7IGEgc2V0KCkvZGVsZXRlKCkgc2V0dGxlcyBvbmNlIGl0cyBvd24gd3JpdGUsIG9yIHRoZSBuZXdlclxuICogd3JpdGUgdGhhdCByZXBsYWNlZCBpdCwgbGFuZHMgb3IgZmFpbHMuIEJ5IGRlZmF1bHQgKHNraXBJZlVuY2hhbmdlZClcbiAqIGFuIHVuY2hhbmdlZCBzZXQgaXMgc2tpcHBlZCwgYnV0IG9ubHkgd2hlbiBhIHByZXZpb3VzIGNvbmZpcm1lZCByb3VuZC10cmlwXG4gKiBwcm92ZWQgdGhlIGV4YWN0IHZhbHVlIGlzIGFscmVhZHkgc3RvcmVkLiBPdXQtb2YtYmFuZCB3cml0ZXJzIChlLmcuIENMSSBzdG9yYWdlIGNvbW1hbmRzKVxuICogbWF5IG5vdCBiZSB2aXNpYmxlIGZvciB1cCB0byBjYWNoZU1heEFnZU1zOyB1c2UgZ2V0KGtleSwgeyBmcmVzaDogdHJ1ZSB9KVxuICogZm9yIGFuIGF1dGhvcml0YXRpdmUgcmVhZCBvciBTdG9yYWdlLmNvbmZpZ3VyZSh7IGNhY2hlUmVhZHM6IGZhbHNlIH0pIHRvXG4gKiBkaXNhYmxlIHJlYWQgY2FjaGluZy5cbiAqXG4gKiBUaGlzIG1vZHVsZSBvbmx5IHdvcmtzIHdoZW4gcnVubmluZyBvbiBzZXJ2ZXItc2lkZSBzY2VuZXMuXG4gKi9cbmV4cG9ydCBjb25zdCBTdG9yYWdlOiBJU3RvcmFnZSA9IGNyZWF0ZVN0b3JhZ2UoKVxuIl19

package/server/storage/player.d.ts

@@ -0,0 +1,60 @@
+import { GetOptions, GetValuesOptions, GetValuesResult, SetOptions } from './constants';
+/**
+ * Player-scoped storage interface for key-value pairs from the Server Side Storage service.
+ * This is NOT filesystem storage - data is stored in the remote storage service.
+ */
+export interface IPlayerStorage {
+    /**
+     * Retrieves a value from a player's storage by key from the Server Side Storage service.
+     *
+     * By default (cacheReads), values read or written during the last cacheMaxAgeMs
+     * are served from a local cache without a network request, including confirmed
+     * "not found" results. Concurrent gets for the same player and key share one
+     * request. Out-of-band writers (e.g. CLI storage commands) may not be visible
+     * for up to cacheMaxAgeMs — pass { fresh: true } to force a network read.
+     * A read first waits for writes to the same key that were pending when it was
+     * issued, so it reflects every write issued before it.
+     * @param address - The player's wallet address
+     * @param key - The key to retrieve
+     * @param options - Optional { fresh } to bypass the read cache
+     * @returns A promise that resolves to the parsed JSON value, or null if not found
+     * @throws Error if the read fails, so a failure is never mistaken for a missing key
+     * @throws TypeError if the address or key is invalid
+     */
+    get<T = unknown>(address: string, key: string, options?: GetOptions): Promise<T | null>;
+    /**
+     * Stores a value in a player's storage in the Server Side Storage service.
+     * @param address - The player's wallet address
+     * @param key - The key to store the value under
+     * @param value - The value to store (will be JSON serialized)
+     * @param options - Optional { skipIfUnchanged } to skip the network write when the value is already stored
+     * @returns true once stored, or once a newer write that replaced this one lands
+     * (rapid writes coalesce); false if the write, or its replacement, fails
+     * @throws TypeError if the address or key is invalid, or the value cannot be stored unchanged: undefined,
+     * circular, a BigInt, or containing a function, a symbol, a non-finite number, an undefined array
+     * element or hole, a Map, Set, typed array or other built-in with no JSON form, or text with an
+     * unpaired surrogate or a NUL character. An undefined object property is dropped; a Date is
+     * stored as its ISO string and a class instance as its own enumerable data.
+     */
+    set<T = unknown>(address: string, key: string, value: T, options?: SetOptions): Promise<boolean>;
+    /**
+     * Deletes a value from a player's storage in the Server Side Storage service.
+     * @param address - The player's wallet address
+     * @param key - The key to delete
+     * @returns true once applied, or once a newer write that replaced it lands;
+     * false only for a confirmed 404
+     * @throws Error if the delete, or its replacement, fails; a failure is never reported as absence
+     * @throws TypeError if the address or key is invalid
+     */
+    delete(address: string, key: string): Promise<boolean>;
+    /**
+     * Returns key-value entries from a player's storage, optionally filtered by prefix.
+     * Supports pagination via limit and offset.
+     * @param address - The player's wallet address
+     * @param options - Optional { prefix, limit, offset } for filtering and pagination.
+     * @returns A promise that resolves to { data, pagination: { offset, total } } for pagination UI
+     * @throws Error if the read fails, so a failure is never mistaken for an empty page
+     * @throws TypeError if the address is invalid
+     */
+    getValues(address: string, options?: GetValuesOptions): Promise<GetValuesResult>;
+}