@hyve-sdk/js 2.14.0-canary.1 → 2.14.0-canary.3

package/dist/index.d.mts

@@ -734,12 +734,16 @@ declare class HyveClient {
      */
     reset(): void;
     /**
-     * Get the storage adapter based on mode.
+     * Get the storage adapter based on platform and mode.
      *
      * Selection order:
-     * 1. An explicit `mode` override ('cloud' | 'local') always wins.
-     * 2. On the CrazyGames platform, the CrazyGames data store is auto-selected
-     *    (D3 — public storageMode type is preserved; this is chosen internally).
+     * 1. On the CrazyGames platform, the CrazyGames data store is ALWAYS used —
+     *    'cloud'/'local' are durability intents and the CrazyGames store
+     *    satisfies both (account-synced when logged in, device-local for
+     *    guests). This keeps games portable: per-call modes written for
+     *    hyve.gg need no changes on CrazyGames, where the cloud path cannot
+     *    work anyway (no hyve JWT exists there).
+     * 2. Otherwise an explicit `mode` override ('cloud' | 'local') wins.
      * 3. Otherwise the configured storageMode is used.
      *
      * Awaits CrazyGames SDK initialization so the data store is ready before use.
@@ -956,8 +960,9 @@ declare class PlaygamaService {
 /**
  * CrazyGames SDK integration service
  *
- * Loads and initializes the CrazyGames SDK v2 when running on the CrazyGames platform.
- * The SDK is loaded from CDN and exposes a global `window.CrazyGames.SDK` object.
+ * Loads and initializes the CrazyGames SDK v3 when running on the CrazyGames platform.
+ * The SDK is loaded from CDN, exposes a global `window.CrazyGames.SDK` object, and
+ * requires an explicit `await SDK.init()` before any module is usable.
  *
  * Detection: CrazyGames games run in an iframe on crazygames.com, so detection
  * uses document.referrer and parent frame location checks.
@@ -997,23 +1002,26 @@ interface CrazyGamesUserModule {
     removeAuthListener(callback: CrazyGamesAuthListener): void;
 }
 /**
- * CrazyGames key/value data store. Treated as async (promise-based) per the
- * SDK v2 docs; awaiting a synchronous return is harmless, so the wrappers
- * `await` every call regardless.
+ * CrazyGames key/value data store (SDK v3). Methods are synchronous
+ * (localStorage-like); the SDK debounces persistence by ~1s internally.
+ * Wrappers still `await` the calls, which is harmless and future-proof.
  */
 interface CrazyGamesDataModule {
-    getItem(key: string): Promise<string | null> | string | null;
-    setItem(key: string, value: string): Promise<void> | void;
-    removeItem(key: string): Promise<void> | void;
-    clear(): Promise<void> | void;
-    getKeys?(): Promise<string[]> | string[];
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
 }
 interface CrazyGamesSDK {
+    /** v3 requires init() to be awaited before any module is used. */
+    init(): Promise<void>;
+    /** Resolved environment — a plain property in v3 (getEnvironment() was removed). */
+    environment: CrazyGamesEnvironment;
     ad: CrazyGamesAdModule;
     game: CrazyGamesGameModule;
     user: CrazyGamesUserModule;
-    data: CrazyGamesDataModule;
-    getEnvironment(): Promise<CrazyGamesEnvironment>;
+    /** Absent unless the game submission has the "Progress Save" toggle enabled. */
+    data?: CrazyGamesDataModule;
 }
 declare global {
     interface Window {
@@ -1032,7 +1040,8 @@ declare class CrazyGamesService {
      */
     static isCrazyGamesDomain(): boolean;
     /**
-     * Loads the CrazyGames SDK from CDN and confirms the environment is 'crazygames'.
+     * Loads the CrazyGames SDK v3 from CDN, runs the mandatory `SDK.init()`, and
+     * confirms the environment is 'crazygames' (or 'local' for dev).
      * Safe to call multiple times — resolves immediately if already initialized.
      */
     initialize(): Promise<boolean>;
@@ -1093,8 +1102,13 @@ declare class CrazyGamesService {
     /** Removes a previously registered auth listener. */
     removeAuthListener(callback: CrazyGamesAuthListener): void;
     /**
-     * Reads a value from the CrazyGames data store. Returns null when the SDK
-     * is unavailable or the key is absent.
+     * Returns the SDK v3 data module, throwing an actionable error when the SDK
+     * is not initialized or the module is disabled for this game submission.
+     */
+    private getDataModule;
+    /**
+     * Reads a value from the CrazyGames data store. Returns null when the key
+     * is absent.
      */
     dataGetItem(key: string): Promise<string | null>;
     /** Writes a value to the CrazyGames data store. */

package/dist/index.d.ts

@@ -734,12 +734,16 @@ declare class HyveClient {
      */
     reset(): void;
     /**
-     * Get the storage adapter based on mode.
+     * Get the storage adapter based on platform and mode.
      *
      * Selection order:
-     * 1. An explicit `mode` override ('cloud' | 'local') always wins.
-     * 2. On the CrazyGames platform, the CrazyGames data store is auto-selected
-     *    (D3 — public storageMode type is preserved; this is chosen internally).
+     * 1. On the CrazyGames platform, the CrazyGames data store is ALWAYS used —
+     *    'cloud'/'local' are durability intents and the CrazyGames store
+     *    satisfies both (account-synced when logged in, device-local for
+     *    guests). This keeps games portable: per-call modes written for
+     *    hyve.gg need no changes on CrazyGames, where the cloud path cannot
+     *    work anyway (no hyve JWT exists there).
+     * 2. Otherwise an explicit `mode` override ('cloud' | 'local') wins.
      * 3. Otherwise the configured storageMode is used.
      *
      * Awaits CrazyGames SDK initialization so the data store is ready before use.
@@ -956,8 +960,9 @@ declare class PlaygamaService {
 /**
  * CrazyGames SDK integration service
  *
- * Loads and initializes the CrazyGames SDK v2 when running on the CrazyGames platform.
- * The SDK is loaded from CDN and exposes a global `window.CrazyGames.SDK` object.
+ * Loads and initializes the CrazyGames SDK v3 when running on the CrazyGames platform.
+ * The SDK is loaded from CDN, exposes a global `window.CrazyGames.SDK` object, and
+ * requires an explicit `await SDK.init()` before any module is usable.
  *
  * Detection: CrazyGames games run in an iframe on crazygames.com, so detection
  * uses document.referrer and parent frame location checks.
@@ -997,23 +1002,26 @@ interface CrazyGamesUserModule {
     removeAuthListener(callback: CrazyGamesAuthListener): void;
 }
 /**
- * CrazyGames key/value data store. Treated as async (promise-based) per the
- * SDK v2 docs; awaiting a synchronous return is harmless, so the wrappers
- * `await` every call regardless.
+ * CrazyGames key/value data store (SDK v3). Methods are synchronous
+ * (localStorage-like); the SDK debounces persistence by ~1s internally.
+ * Wrappers still `await` the calls, which is harmless and future-proof.
  */
 interface CrazyGamesDataModule {
-    getItem(key: string): Promise<string | null> | string | null;
-    setItem(key: string, value: string): Promise<void> | void;
-    removeItem(key: string): Promise<void> | void;
-    clear(): Promise<void> | void;
-    getKeys?(): Promise<string[]> | string[];
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
 }
 interface CrazyGamesSDK {
+    /** v3 requires init() to be awaited before any module is used. */
+    init(): Promise<void>;
+    /** Resolved environment — a plain property in v3 (getEnvironment() was removed). */
+    environment: CrazyGamesEnvironment;
     ad: CrazyGamesAdModule;
     game: CrazyGamesGameModule;
     user: CrazyGamesUserModule;
-    data: CrazyGamesDataModule;
-    getEnvironment(): Promise<CrazyGamesEnvironment>;
+    /** Absent unless the game submission has the "Progress Save" toggle enabled. */
+    data?: CrazyGamesDataModule;
 }
 declare global {
     interface Window {
@@ -1032,7 +1040,8 @@ declare class CrazyGamesService {
      */
     static isCrazyGamesDomain(): boolean;
     /**
-     * Loads the CrazyGames SDK from CDN and confirms the environment is 'crazygames'.
+     * Loads the CrazyGames SDK v3 from CDN, runs the mandatory `SDK.init()`, and
+     * confirms the environment is 'crazygames' (or 'local' for dev).
      * Safe to call multiple times — resolves immediately if already initialized.
      */
     initialize(): Promise<boolean>;
@@ -1093,8 +1102,13 @@ declare class CrazyGamesService {
     /** Removes a previously registered auth listener. */
     removeAuthListener(callback: CrazyGamesAuthListener): void;
     /**
-     * Reads a value from the CrazyGames data store. Returns null when the SDK
-     * is unavailable or the key is absent.
+     * Returns the SDK v3 data module, throwing an actionable error when the SDK
+     * is not initialized or the module is disabled for this game submission.
+     */
+    private getDataModule;
+    /**
+     * Reads a value from the CrazyGames data store. Returns null when the key
+     * is absent.
      */
     dataGetItem(key: string): Promise<string | null>;
     /** Writes a value to the CrazyGames data store. */

package/dist/index.js

@@ -1239,7 +1239,7 @@ var PlaygamaService = class {
 };
 
 // src/services/crazygames.ts
-var CRAZYGAMES_SDK_CDN = "https://sdk.crazygames.com/crazygames-sdk-v2.js";
+var CRAZYGAMES_SDK_CDN = "https://sdk.crazygames.com/crazygames-sdk-v3.js";
 var CrazyGamesService = class {
   initialized = false;
   environment = null;
@@ -1267,7 +1267,8 @@ var CrazyGamesService = class {
     }
   }
   /**
-   * Loads the CrazyGames SDK from CDN and confirms the environment is 'crazygames'.
+   * Loads the CrazyGames SDK v3 from CDN, runs the mandatory `SDK.init()`, and
+   * confirms the environment is 'crazygames' (or 'local' for dev).
    * Safe to call multiple times — resolves immediately if already initialized.
    */
   async initialize() {
@@ -1279,13 +1280,19 @@ var CrazyGamesService = class {
         logger.warn("[CrazyGamesService] SDK not found after script load");
         return false;
       }
-      const env = await sdk.getEnvironment();
+      await sdk.init();
+      const env = sdk.environment;
       if (env !== "crazygames" && env !== "local") {
         logger.warn("[CrazyGamesService] Unexpected environment:", env);
         return false;
       }
       this.environment = env;
       this.initialized = true;
+      if (!sdk.data) {
+        logger.warn(
+          '[CrazyGamesService] data module unavailable \u2014 enable the "Progress Save" toggle in the CrazyGames game submission settings to use persistent storage'
+        );
+      }
       return true;
     } catch (error) {
       logger.warn("[CrazyGamesService] Failed to initialize:", error);
@@ -1452,30 +1459,36 @@ var CrazyGamesService = class {
     }
   }
   /**
-   * Reads a value from the CrazyGames data store. Returns null when the SDK
-   * is unavailable or the key is absent.
+   * Returns the SDK v3 data module, throwing an actionable error when the SDK
+   * is not initialized or the module is disabled for this game submission.
    */
-  async dataGetItem(key) {
+  getDataModule() {
     const sdk = window.CrazyGames?.SDK;
-    if (!this.initialized || !sdk) return null;
-    const value = await sdk.data.getItem(key);
+    if (!this.initialized || !sdk) {
+      throw new Error("CrazyGames SDK not initialized");
+    }
+    if (!sdk.data) {
+      throw new Error(
+        'CrazyGames data module unavailable \u2014 enable the "Progress Save" toggle in the CrazyGames game submission settings'
+      );
+    }
+    return sdk.data;
+  }
+  /**
+   * Reads a value from the CrazyGames data store. Returns null when the key
+   * is absent.
+   */
+  async dataGetItem(key) {
+    const value = await this.getDataModule().getItem(key);
     return value ?? null;
   }
   /** Writes a value to the CrazyGames data store. */
   async dataSetItem(key, value) {
-    const sdk = window.CrazyGames?.SDK;
-    if (!this.initialized || !sdk) {
-      throw new Error("CrazyGames SDK not initialized");
-    }
-    await sdk.data.setItem(key, value);
+    await this.getDataModule().setItem(key, value);
   }
   /** Removes a value from the CrazyGames data store. */
   async dataRemoveItem(key) {
-    const sdk = window.CrazyGames?.SDK;
-    if (!this.initialized || !sdk) {
-      throw new Error("CrazyGames SDK not initialized");
-    }
-    await sdk.data.removeItem(key);
+    await this.getDataModule().removeItem(key);
   }
   loadScript() {
     return new Promise((resolve, reject) => {
@@ -2883,28 +2896,34 @@ var HyveClient = class {
     logger.info("Client reset with new sessionId:", this.sessionId);
   }
   /**
-   * Get the storage adapter based on mode.
+   * Get the storage adapter based on platform and mode.
    *
    * Selection order:
-   * 1. An explicit `mode` override ('cloud' | 'local') always wins.
-   * 2. On the CrazyGames platform, the CrazyGames data store is auto-selected
-   *    (D3 — public storageMode type is preserved; this is chosen internally).
+   * 1. On the CrazyGames platform, the CrazyGames data store is ALWAYS used —
+   *    'cloud'/'local' are durability intents and the CrazyGames store
+   *    satisfies both (account-synced when logged in, device-local for
+   *    guests). This keeps games portable: per-call modes written for
+   *    hyve.gg need no changes on CrazyGames, where the cloud path cannot
+   *    work anyway (no hyve JWT exists there).
+   * 2. Otherwise an explicit `mode` override ('cloud' | 'local') wins.
    * 3. Otherwise the configured storageMode is used.
    *
    * Awaits CrazyGames SDK initialization so the data store is ready before use.
    * @param mode Storage mode override (cloud or local)
    */
   async getStorageAdapter(mode) {
-    if (mode) {
-      return mode === "local" ? this.localStorageAdapter : this.cloudStorageAdapter;
-    }
     if (this.crazyGamesService && this.crazyGamesStorageAdapter) {
       if (this.crazyGamesInitPromise) await this.crazyGamesInitPromise;
-      if (this.crazyGamesService.getEnvironment() === "crazygames") {
+      const env = this.crazyGamesService.getEnvironment();
+      if (env === "crazygames" || env === "local") {
+        if (mode) {
+          logger.debug(`Storage mode '${mode}' ignored on CrazyGames \u2014 using the CrazyGames data store`);
+        }
         return this.crazyGamesStorageAdapter;
       }
     }
-    return this.storageMode === "local" ? this.localStorageAdapter : this.cloudStorageAdapter;
+    const selected = mode ?? this.storageMode;
+    return selected === "local" ? this.localStorageAdapter : this.cloudStorageAdapter;
   }
   /**
    * Returns the current game ID or throws if not available.

package/dist/index.mjs

@@ -1198,7 +1198,7 @@ var PlaygamaService = class {
 };
 
 // src/services/crazygames.ts
-var CRAZYGAMES_SDK_CDN = "https://sdk.crazygames.com/crazygames-sdk-v2.js";
+var CRAZYGAMES_SDK_CDN = "https://sdk.crazygames.com/crazygames-sdk-v3.js";
 var CrazyGamesService = class {
   initialized = false;
   environment = null;
@@ -1226,7 +1226,8 @@ var CrazyGamesService = class {
     }
   }
   /**
-   * Loads the CrazyGames SDK from CDN and confirms the environment is 'crazygames'.
+   * Loads the CrazyGames SDK v3 from CDN, runs the mandatory `SDK.init()`, and
+   * confirms the environment is 'crazygames' (or 'local' for dev).
    * Safe to call multiple times — resolves immediately if already initialized.
    */
   async initialize() {
@@ -1238,13 +1239,19 @@ var CrazyGamesService = class {
         logger.warn("[CrazyGamesService] SDK not found after script load");
         return false;
       }
-      const env = await sdk.getEnvironment();
+      await sdk.init();
+      const env = sdk.environment;
       if (env !== "crazygames" && env !== "local") {
         logger.warn("[CrazyGamesService] Unexpected environment:", env);
         return false;
       }
       this.environment = env;
       this.initialized = true;
+      if (!sdk.data) {
+        logger.warn(
+          '[CrazyGamesService] data module unavailable \u2014 enable the "Progress Save" toggle in the CrazyGames game submission settings to use persistent storage'
+        );
+      }
       return true;
     } catch (error) {
       logger.warn("[CrazyGamesService] Failed to initialize:", error);
@@ -1411,30 +1418,36 @@ var CrazyGamesService = class {
     }
   }
   /**
-   * Reads a value from the CrazyGames data store. Returns null when the SDK
-   * is unavailable or the key is absent.
+   * Returns the SDK v3 data module, throwing an actionable error when the SDK
+   * is not initialized or the module is disabled for this game submission.
    */
-  async dataGetItem(key) {
+  getDataModule() {
     const sdk = window.CrazyGames?.SDK;
-    if (!this.initialized || !sdk) return null;
-    const value = await sdk.data.getItem(key);
+    if (!this.initialized || !sdk) {
+      throw new Error("CrazyGames SDK not initialized");
+    }
+    if (!sdk.data) {
+      throw new Error(
+        'CrazyGames data module unavailable \u2014 enable the "Progress Save" toggle in the CrazyGames game submission settings'
+      );
+    }
+    return sdk.data;
+  }
+  /**
+   * Reads a value from the CrazyGames data store. Returns null when the key
+   * is absent.
+   */
+  async dataGetItem(key) {
+    const value = await this.getDataModule().getItem(key);
     return value ?? null;
   }
   /** Writes a value to the CrazyGames data store. */
   async dataSetItem(key, value) {
-    const sdk = window.CrazyGames?.SDK;
-    if (!this.initialized || !sdk) {
-      throw new Error("CrazyGames SDK not initialized");
-    }
-    await sdk.data.setItem(key, value);
+    await this.getDataModule().setItem(key, value);
   }
   /** Removes a value from the CrazyGames data store. */
   async dataRemoveItem(key) {
-    const sdk = window.CrazyGames?.SDK;
-    if (!this.initialized || !sdk) {
-      throw new Error("CrazyGames SDK not initialized");
-    }
-    await sdk.data.removeItem(key);
+    await this.getDataModule().removeItem(key);
   }
   loadScript() {
     return new Promise((resolve, reject) => {
@@ -2842,28 +2855,34 @@ var HyveClient = class {
     logger.info("Client reset with new sessionId:", this.sessionId);
   }
   /**
-   * Get the storage adapter based on mode.
+   * Get the storage adapter based on platform and mode.
    *
    * Selection order:
-   * 1. An explicit `mode` override ('cloud' | 'local') always wins.
-   * 2. On the CrazyGames platform, the CrazyGames data store is auto-selected
-   *    (D3 — public storageMode type is preserved; this is chosen internally).
+   * 1. On the CrazyGames platform, the CrazyGames data store is ALWAYS used —
+   *    'cloud'/'local' are durability intents and the CrazyGames store
+   *    satisfies both (account-synced when logged in, device-local for
+   *    guests). This keeps games portable: per-call modes written for
+   *    hyve.gg need no changes on CrazyGames, where the cloud path cannot
+   *    work anyway (no hyve JWT exists there).
+   * 2. Otherwise an explicit `mode` override ('cloud' | 'local') wins.
    * 3. Otherwise the configured storageMode is used.
    *
    * Awaits CrazyGames SDK initialization so the data store is ready before use.
    * @param mode Storage mode override (cloud or local)
    */
   async getStorageAdapter(mode) {
-    if (mode) {
-      return mode === "local" ? this.localStorageAdapter : this.cloudStorageAdapter;
-    }
     if (this.crazyGamesService && this.crazyGamesStorageAdapter) {
       if (this.crazyGamesInitPromise) await this.crazyGamesInitPromise;
-      if (this.crazyGamesService.getEnvironment() === "crazygames") {
+      const env = this.crazyGamesService.getEnvironment();
+      if (env === "crazygames" || env === "local") {
+        if (mode) {
+          logger.debug(`Storage mode '${mode}' ignored on CrazyGames \u2014 using the CrazyGames data store`);
+        }
         return this.crazyGamesStorageAdapter;
       }
     }
-    return this.storageMode === "local" ? this.localStorageAdapter : this.cloudStorageAdapter;
+    const selected = mode ?? this.storageMode;
+    return selected === "local" ? this.localStorageAdapter : this.cloudStorageAdapter;
   }
   /**
    * Returns the current game ID or throws if not available.

package/dist/react.d.mts

@@ -465,12 +465,16 @@ declare class HyveClient {
      */
     reset(): void;
     /**
-     * Get the storage adapter based on mode.
+     * Get the storage adapter based on platform and mode.
      *
      * Selection order:
-     * 1. An explicit `mode` override ('cloud' | 'local') always wins.
-     * 2. On the CrazyGames platform, the CrazyGames data store is auto-selected
-     *    (D3 — public storageMode type is preserved; this is chosen internally).
+     * 1. On the CrazyGames platform, the CrazyGames data store is ALWAYS used —
+     *    'cloud'/'local' are durability intents and the CrazyGames store
+     *    satisfies both (account-synced when logged in, device-local for
+     *    guests). This keeps games portable: per-call modes written for
+     *    hyve.gg need no changes on CrazyGames, where the cloud path cannot
+     *    work anyway (no hyve JWT exists there).
+     * 2. Otherwise an explicit `mode` override ('cloud' | 'local') wins.
      * 3. Otherwise the configured storageMode is used.
      *
      * Awaits CrazyGames SDK initialization so the data store is ready before use.

package/dist/react.d.ts

@@ -465,12 +465,16 @@ declare class HyveClient {
      */
     reset(): void;
     /**
-     * Get the storage adapter based on mode.
+     * Get the storage adapter based on platform and mode.
      *
      * Selection order:
-     * 1. An explicit `mode` override ('cloud' | 'local') always wins.
-     * 2. On the CrazyGames platform, the CrazyGames data store is auto-selected
-     *    (D3 — public storageMode type is preserved; this is chosen internally).
+     * 1. On the CrazyGames platform, the CrazyGames data store is ALWAYS used —
+     *    'cloud'/'local' are durability intents and the CrazyGames store
+     *    satisfies both (account-synced when logged in, device-local for
+     *    guests). This keeps games portable: per-call modes written for
+     *    hyve.gg need no changes on CrazyGames, where the cloud path cannot
+     *    work anyway (no hyve JWT exists there).
+     * 2. Otherwise an explicit `mode` override ('cloud' | 'local') wins.
      * 3. Otherwise the configured storageMode is used.
      *
      * Awaits CrazyGames SDK initialization so the data store is ready before use.

package/dist/react.js

@@ -1196,7 +1196,7 @@ var PlaygamaService = class {
 };
 
 // src/services/crazygames.ts
-var CRAZYGAMES_SDK_CDN = "https://sdk.crazygames.com/crazygames-sdk-v2.js";
+var CRAZYGAMES_SDK_CDN = "https://sdk.crazygames.com/crazygames-sdk-v3.js";
 var CrazyGamesService = class {
   initialized = false;
   environment = null;
@@ -1224,7 +1224,8 @@ var CrazyGamesService = class {
     }
   }
   /**
-   * Loads the CrazyGames SDK from CDN and confirms the environment is 'crazygames'.
+   * Loads the CrazyGames SDK v3 from CDN, runs the mandatory `SDK.init()`, and
+   * confirms the environment is 'crazygames' (or 'local' for dev).
    * Safe to call multiple times — resolves immediately if already initialized.
    */
   async initialize() {
@@ -1236,13 +1237,19 @@ var CrazyGamesService = class {
         logger.warn("[CrazyGamesService] SDK not found after script load");
         return false;
       }
-      const env = await sdk.getEnvironment();
+      await sdk.init();
+      const env = sdk.environment;
       if (env !== "crazygames" && env !== "local") {
         logger.warn("[CrazyGamesService] Unexpected environment:", env);
         return false;
       }
       this.environment = env;
       this.initialized = true;
+      if (!sdk.data) {
+        logger.warn(
+          '[CrazyGamesService] data module unavailable \u2014 enable the "Progress Save" toggle in the CrazyGames game submission settings to use persistent storage'
+        );
+      }
       return true;
     } catch (error) {
       logger.warn("[CrazyGamesService] Failed to initialize:", error);
@@ -1409,30 +1416,36 @@ var CrazyGamesService = class {
     }
   }
   /**
-   * Reads a value from the CrazyGames data store. Returns null when the SDK
-   * is unavailable or the key is absent.
+   * Returns the SDK v3 data module, throwing an actionable error when the SDK
+   * is not initialized or the module is disabled for this game submission.
    */
-  async dataGetItem(key) {
+  getDataModule() {
     const sdk = window.CrazyGames?.SDK;
-    if (!this.initialized || !sdk) return null;
-    const value = await sdk.data.getItem(key);
+    if (!this.initialized || !sdk) {
+      throw new Error("CrazyGames SDK not initialized");
+    }
+    if (!sdk.data) {
+      throw new Error(
+        'CrazyGames data module unavailable \u2014 enable the "Progress Save" toggle in the CrazyGames game submission settings'
+      );
+    }
+    return sdk.data;
+  }
+  /**
+   * Reads a value from the CrazyGames data store. Returns null when the key
+   * is absent.
+   */
+  async dataGetItem(key) {
+    const value = await this.getDataModule().getItem(key);
     return value ?? null;
   }
   /** Writes a value to the CrazyGames data store. */
   async dataSetItem(key, value) {
-    const sdk = window.CrazyGames?.SDK;
-    if (!this.initialized || !sdk) {
-      throw new Error("CrazyGames SDK not initialized");
-    }
-    await sdk.data.setItem(key, value);
+    await this.getDataModule().setItem(key, value);
   }
   /** Removes a value from the CrazyGames data store. */
   async dataRemoveItem(key) {
-    const sdk = window.CrazyGames?.SDK;
-    if (!this.initialized || !sdk) {
-      throw new Error("CrazyGames SDK not initialized");
-    }
-    await sdk.data.removeItem(key);
+    await this.getDataModule().removeItem(key);
   }
   loadScript() {
     return new Promise((resolve, reject) => {
@@ -2834,28 +2847,34 @@ var HyveClient = class {
     logger.info("Client reset with new sessionId:", this.sessionId);
   }
   /**
-   * Get the storage adapter based on mode.
+   * Get the storage adapter based on platform and mode.
    *
    * Selection order:
-   * 1. An explicit `mode` override ('cloud' | 'local') always wins.
-   * 2. On the CrazyGames platform, the CrazyGames data store is auto-selected
-   *    (D3 — public storageMode type is preserved; this is chosen internally).
+   * 1. On the CrazyGames platform, the CrazyGames data store is ALWAYS used —
+   *    'cloud'/'local' are durability intents and the CrazyGames store
+   *    satisfies both (account-synced when logged in, device-local for
+   *    guests). This keeps games portable: per-call modes written for
+   *    hyve.gg need no changes on CrazyGames, where the cloud path cannot
+   *    work anyway (no hyve JWT exists there).
+   * 2. Otherwise an explicit `mode` override ('cloud' | 'local') wins.
    * 3. Otherwise the configured storageMode is used.
    *
    * Awaits CrazyGames SDK initialization so the data store is ready before use.
    * @param mode Storage mode override (cloud or local)
    */
   async getStorageAdapter(mode) {
-    if (mode) {
-      return mode === "local" ? this.localStorageAdapter : this.cloudStorageAdapter;
-    }
     if (this.crazyGamesService && this.crazyGamesStorageAdapter) {
       if (this.crazyGamesInitPromise) await this.crazyGamesInitPromise;
-      if (this.crazyGamesService.getEnvironment() === "crazygames") {
+      const env = this.crazyGamesService.getEnvironment();
+      if (env === "crazygames" || env === "local") {
+        if (mode) {
+          logger.debug(`Storage mode '${mode}' ignored on CrazyGames \u2014 using the CrazyGames data store`);
+        }
         return this.crazyGamesStorageAdapter;
       }
     }
-    return this.storageMode === "local" ? this.localStorageAdapter : this.cloudStorageAdapter;
+    const selected = mode ?? this.storageMode;
+    return selected === "local" ? this.localStorageAdapter : this.cloudStorageAdapter;
   }
   /**
    * Returns the current game ID or throws if not available.

package/dist/react.mjs

@@ -1174,7 +1174,7 @@ var PlaygamaService = class {
 };
 
 // src/services/crazygames.ts
-var CRAZYGAMES_SDK_CDN = "https://sdk.crazygames.com/crazygames-sdk-v2.js";
+var CRAZYGAMES_SDK_CDN = "https://sdk.crazygames.com/crazygames-sdk-v3.js";
 var CrazyGamesService = class {
   initialized = false;
   environment = null;
@@ -1202,7 +1202,8 @@ var CrazyGamesService = class {
     }
   }
   /**
-   * Loads the CrazyGames SDK from CDN and confirms the environment is 'crazygames'.
+   * Loads the CrazyGames SDK v3 from CDN, runs the mandatory `SDK.init()`, and
+   * confirms the environment is 'crazygames' (or 'local' for dev).
    * Safe to call multiple times — resolves immediately if already initialized.
    */
   async initialize() {
@@ -1214,13 +1215,19 @@ var CrazyGamesService = class {
         logger.warn("[CrazyGamesService] SDK not found after script load");
         return false;
       }
-      const env = await sdk.getEnvironment();
+      await sdk.init();
+      const env = sdk.environment;
       if (env !== "crazygames" && env !== "local") {
         logger.warn("[CrazyGamesService] Unexpected environment:", env);
         return false;
       }
       this.environment = env;
       this.initialized = true;
+      if (!sdk.data) {
+        logger.warn(
+          '[CrazyGamesService] data module unavailable \u2014 enable the "Progress Save" toggle in the CrazyGames game submission settings to use persistent storage'
+        );
+      }
       return true;
     } catch (error) {
       logger.warn("[CrazyGamesService] Failed to initialize:", error);
@@ -1387,30 +1394,36 @@ var CrazyGamesService = class {
     }
   }
   /**
-   * Reads a value from the CrazyGames data store. Returns null when the SDK
-   * is unavailable or the key is absent.
+   * Returns the SDK v3 data module, throwing an actionable error when the SDK
+   * is not initialized or the module is disabled for this game submission.
    */
-  async dataGetItem(key) {
+  getDataModule() {
     const sdk = window.CrazyGames?.SDK;
-    if (!this.initialized || !sdk) return null;
-    const value = await sdk.data.getItem(key);
+    if (!this.initialized || !sdk) {
+      throw new Error("CrazyGames SDK not initialized");
+    }
+    if (!sdk.data) {
+      throw new Error(
+        'CrazyGames data module unavailable \u2014 enable the "Progress Save" toggle in the CrazyGames game submission settings'
+      );
+    }
+    return sdk.data;
+  }
+  /**
+   * Reads a value from the CrazyGames data store. Returns null when the key
+   * is absent.
+   */
+  async dataGetItem(key) {
+    const value = await this.getDataModule().getItem(key);
     return value ?? null;
   }
   /** Writes a value to the CrazyGames data store. */
   async dataSetItem(key, value) {
-    const sdk = window.CrazyGames?.SDK;
-    if (!this.initialized || !sdk) {
-      throw new Error("CrazyGames SDK not initialized");
-    }
-    await sdk.data.setItem(key, value);
+    await this.getDataModule().setItem(key, value);
   }
   /** Removes a value from the CrazyGames data store. */
   async dataRemoveItem(key) {
-    const sdk = window.CrazyGames?.SDK;
-    if (!this.initialized || !sdk) {
-      throw new Error("CrazyGames SDK not initialized");
-    }
-    await sdk.data.removeItem(key);
+    await this.getDataModule().removeItem(key);
   }
   loadScript() {
     return new Promise((resolve, reject) => {
@@ -2812,28 +2825,34 @@ var HyveClient = class {
     logger.info("Client reset with new sessionId:", this.sessionId);
   }
   /**
-   * Get the storage adapter based on mode.
+   * Get the storage adapter based on platform and mode.
    *
    * Selection order:
-   * 1. An explicit `mode` override ('cloud' | 'local') always wins.
-   * 2. On the CrazyGames platform, the CrazyGames data store is auto-selected
-   *    (D3 — public storageMode type is preserved; this is chosen internally).
+   * 1. On the CrazyGames platform, the CrazyGames data store is ALWAYS used —
+   *    'cloud'/'local' are durability intents and the CrazyGames store
+   *    satisfies both (account-synced when logged in, device-local for
+   *    guests). This keeps games portable: per-call modes written for
+   *    hyve.gg need no changes on CrazyGames, where the cloud path cannot
+   *    work anyway (no hyve JWT exists there).
+   * 2. Otherwise an explicit `mode` override ('cloud' | 'local') wins.
    * 3. Otherwise the configured storageMode is used.
    *
    * Awaits CrazyGames SDK initialization so the data store is ready before use.
    * @param mode Storage mode override (cloud or local)
    */
   async getStorageAdapter(mode) {
-    if (mode) {
-      return mode === "local" ? this.localStorageAdapter : this.cloudStorageAdapter;
-    }
     if (this.crazyGamesService && this.crazyGamesStorageAdapter) {
       if (this.crazyGamesInitPromise) await this.crazyGamesInitPromise;
-      if (this.crazyGamesService.getEnvironment() === "crazygames") {
+      const env = this.crazyGamesService.getEnvironment();
+      if (env === "crazygames" || env === "local") {
+        if (mode) {
+          logger.debug(`Storage mode '${mode}' ignored on CrazyGames \u2014 using the CrazyGames data store`);
+        }
         return this.crazyGamesStorageAdapter;
       }
     }
-    return this.storageMode === "local" ? this.localStorageAdapter : this.cloudStorageAdapter;
+    const selected = mode ?? this.storageMode;
+    return selected === "local" ? this.localStorageAdapter : this.cloudStorageAdapter;
   }
   /**
    * Returns the current game ID or throws if not available.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyve-sdk/js",
-  "version": "2.14.0-canary.1",
+  "version": "2.14.0-canary.3",
   "description": "Hyve SDK - TypeScript wrapper for Hyve game server integration",
   "private": false,
   "publishConfig": {