@hyve-sdk/js 2.13.0 → 2.14.0-canary.0

package/dist/index.mjs

@@ -1201,6 +1201,7 @@ var PlaygamaService = class {
 var CRAZYGAMES_SDK_CDN = "https://sdk.crazygames.com/crazygames-sdk-v2.js";
 var CrazyGamesService = class {
   initialized = false;
+  environment = null;
   /**
    * Detects if the game is running on the CrazyGames platform.
    * Games on CrazyGames run inside an iframe, so we check document.referrer
@@ -1242,6 +1243,7 @@ var CrazyGamesService = class {
         logger.warn("[CrazyGamesService] Unexpected environment:", env);
         return false;
       }
+      this.environment = env;
       this.initialized = true;
       return true;
     } catch (error) {
@@ -1352,6 +1354,88 @@ var CrazyGamesService = class {
     if (!this.initialized) return;
     window.CrazyGames?.SDK.game.happytime();
   }
+  /**
+   * Returns the resolved CrazyGames environment ('crazygames' | 'local' |
+   * 'disabled'), or null if the SDK has not initialized yet. Used to
+   * auto-select the CrazyGames storage adapter.
+   */
+  getEnvironment() {
+    return this.environment;
+  }
+  /**
+   * Whether the CrazyGames account system is present (sync). When false,
+   * there is no logged-in user concept and telemetry falls back to guests.
+   */
+  isUserAccountAvailable() {
+    if (!this.initialized) return false;
+    return window.CrazyGames?.SDK.user.isUserAccountAvailable ?? false;
+  }
+  /**
+   * Fetches the current CrazyGames user, or null if the player is not logged
+   * in (guest). The returned `__dangerousUserId` is client-asserted and used
+   * only as a telemetry attribution label.
+   */
+  async getUser() {
+    const sdk = window.CrazyGames?.SDK;
+    if (!this.initialized || !sdk || !this.isUserAccountAvailable()) {
+      return null;
+    }
+    try {
+      return await sdk.user.getUser() ?? null;
+    } catch (error) {
+      logger.warn("[CrazyGamesService] getUser failed:", error);
+      return null;
+    }
+  }
+  /**
+   * Registers a listener that fires when a guest logs in mid-session.
+   * No-op if the SDK or account system is unavailable.
+   */
+  addAuthListener(callback) {
+    const sdk = window.CrazyGames?.SDK;
+    if (!this.initialized || !sdk || !this.isUserAccountAvailable()) return;
+    try {
+      sdk.user.addAuthListener(callback);
+    } catch (error) {
+      logger.warn("[CrazyGamesService] addAuthListener failed:", error);
+    }
+  }
+  /** Removes a previously registered auth listener. */
+  removeAuthListener(callback) {
+    const sdk = window.CrazyGames?.SDK;
+    if (!this.initialized || !sdk) return;
+    try {
+      sdk.user.removeAuthListener(callback);
+    } catch (error) {
+      logger.warn("[CrazyGamesService] removeAuthListener failed:", error);
+    }
+  }
+  /**
+   * Reads a value from the CrazyGames data store. Returns null when the SDK
+   * is unavailable or the key is absent.
+   */
+  async dataGetItem(key) {
+    const sdk = window.CrazyGames?.SDK;
+    if (!this.initialized || !sdk) return null;
+    const value = await sdk.data.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);
+  }
+  /** 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);
+  }
   loadScript() {
     return new Promise((resolve, reject) => {
       if (window.CrazyGames?.SDK) {
@@ -2019,6 +2103,162 @@ var LocalStorageAdapter = class {
     return count;
   }
 };
+function isGameDataObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function toNumber(value) {
+  return typeof value === "number" ? value : 0;
+}
+function applyOperation(operation, current, operand) {
+  switch (operation) {
+    case "set":
+      return operand;
+    case "add":
+      return toNumber(current) + toNumber(operand);
+    case "subtract":
+      return toNumber(current) - toNumber(operand);
+    case "multiply":
+      return toNumber(current) * toNumber(operand);
+    case "divide": {
+      const divisor = toNumber(operand);
+      if (divisor === 0) throw new Error("Cannot divide by zero");
+      return toNumber(current) / divisor;
+    }
+    case "modulo": {
+      const divisor = toNumber(operand);
+      if (divisor === 0) throw new Error("Cannot modulo by zero");
+      return toNumber(current) % divisor;
+    }
+    // For min/max, a missing current has nothing to compare against — adopt the operand.
+    case "min":
+      return typeof current === "number" ? Math.min(current, toNumber(operand)) : operand;
+    case "max":
+      return typeof current === "number" ? Math.max(current, toNumber(operand)) : operand;
+    case "append": {
+      const base = Array.isArray(current) ? [...current] : current === void 0 || current === null ? [] : [current];
+      if (Array.isArray(operand)) {
+        base.push(...operand);
+      } else {
+        base.push(operand);
+      }
+      return base;
+    }
+    default:
+      return operand;
+  }
+}
+function getAtPath(value, path) {
+  let current = value;
+  for (const segment of path.split(".")) {
+    if (!isGameDataObject(current)) return void 0;
+    current = current[segment];
+  }
+  return current;
+}
+function setAtPath(value, path, newValue) {
+  const segments = path.split(".");
+  const root = isGameDataObject(value) ? { ...value } : {};
+  let cursor = root;
+  for (let i = 0; i < segments.length - 1; i++) {
+    const segment = segments[i];
+    const existing = cursor[segment];
+    const next = isGameDataObject(existing) ? { ...existing } : {};
+    cursor[segment] = next;
+    cursor = next;
+  }
+  cursor[segments[segments.length - 1]] = newValue;
+  return root;
+}
+var CrazyGamesStorageAdapter = class {
+  constructor(service) {
+    this.service = service;
+  }
+  getStorageKey(gameId, key) {
+    return `${gameId}:${key}`;
+  }
+  async saveGameData(gameId, key, value, operation, path) {
+    const storageKey = this.getStorageKey(gameId, key);
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const existingRaw = await this.service.dataGetItem(storageKey);
+    const existing = existingRaw ? JSON.parse(existingRaw) : null;
+    const createdAt = existing?.created_at ?? now;
+    const useOperation = operation !== void 0;
+    let storedValue;
+    let opResult;
+    if (path) {
+      const current = getAtPath(existing?.value, path);
+      const next = useOperation ? applyOperation(operation, current, value) : value;
+      storedValue = setAtPath(existing?.value, path, next);
+      opResult = next;
+    } else {
+      const current = existing?.value;
+      const next = useOperation ? applyOperation(operation, current, value) : value;
+      storedValue = next;
+      opResult = next;
+    }
+    const item = {
+      key,
+      value: storedValue,
+      created_at: createdAt,
+      updated_at: now
+    };
+    await this.service.dataSetItem(storageKey, JSON.stringify(item));
+    const response = { success: true, message: "Data saved successfully" };
+    if (useOperation && operation !== "set") {
+      response.result = opResult;
+    }
+    return response;
+  }
+  async batchSaveGameData(gameId, items) {
+    const results = [];
+    let usedOperation = false;
+    for (const item of items) {
+      if (item.operation !== void 0) usedOperation = true;
+      try {
+        const saved = await this.saveGameData(gameId, item.key, item.value, item.operation, item.path);
+        results.push({ key: item.key, success: true, ...saved.result !== void 0 && { result: saved.result } });
+      } catch (error) {
+        results.push({
+          key: item.key,
+          success: false,
+          error: error instanceof Error ? error.message : "Unknown error"
+        });
+      }
+    }
+    const allSucceeded = results.every((r) => r.success);
+    return {
+      success: allSucceeded,
+      message: `${results.filter((r) => r.success).length}/${items.length} items saved`,
+      ...usedOperation && { results }
+    };
+  }
+  async getGameData(gameId, key) {
+    const raw = await this.service.dataGetItem(this.getStorageKey(gameId, key));
+    return raw ? JSON.parse(raw) : null;
+  }
+  async getMultipleGameData(gameId, keys) {
+    const items = [];
+    for (const key of keys) {
+      const item = await this.getGameData(gameId, key);
+      if (item) items.push(item);
+    }
+    return items;
+  }
+  async deleteGameData(gameId, key) {
+    const storageKey = this.getStorageKey(gameId, key);
+    const existing = await this.service.dataGetItem(storageKey);
+    if (existing === null) return false;
+    await this.service.dataRemoveItem(storageKey);
+    return true;
+  }
+  async deleteMultipleGameData(gameId, keys) {
+    let count = 0;
+    for (const key of keys) {
+      if (await this.deleteGameData(gameId, key)) count++;
+    }
+    return count;
+  }
+};
 
 // src/core/client.ts
 function determineEnvironmentFromParentUrl() {
@@ -2065,6 +2305,11 @@ var HyveClient = class {
   storageMode;
   cloudStorageAdapter;
   localStorageAdapter;
+  crazyGamesStorageAdapter = null;
+  partnerApiKey = null;
+  partnerApiBaseUrl = null;
+  /** Raw (unprefixed) CrazyGames __dangerousUserId, seeded at init and on login. */
+  crazyGamesUserId = null;
   /**
    * Creates a new HyveClient instance
    * @param config Optional configuration including telemetry and ads
@@ -2092,10 +2337,16 @@ var HyveClient = class {
         return success;
       });
     }
+    this.partnerApiKey = config?.partnerApiKey ?? null;
+    this.partnerApiBaseUrl = config?.partnerApiBaseUrl ?? null;
     if (typeof window !== "undefined" && CrazyGamesService.isCrazyGamesDomain()) {
       this.crazyGamesService = new CrazyGamesService();
-      this.crazyGamesInitPromise = this.crazyGamesService.initialize().then((success) => {
+      this.crazyGamesStorageAdapter = new CrazyGamesStorageAdapter(this.crazyGamesService);
+      this.crazyGamesInitPromise = this.crazyGamesService.initialize().then(async (success) => {
         logger.info("CrazyGames SDK initialized:", success);
+        if (success) {
+          await this.seedCrazyGamesUser();
+        }
         return success;
       });
     }
@@ -2191,6 +2442,16 @@ var HyveClient = class {
    * @returns Promise resolving to boolean indicating success
    */
   async sendTelemetry(eventLocation, eventCategory, eventAction, eventSubCategory, eventSubAction, eventDetails, platformId) {
+    if (this.partnerApiKey) {
+      return this.sendPartnerTelemetry(
+        eventLocation,
+        eventCategory,
+        eventAction,
+        eventSubCategory,
+        eventSubAction,
+        eventDetails
+      );
+    }
     if (!this.jwtToken) {
       logger.error("JWT token required. Ensure hyve-access and game-id are present in the URL.");
       return false;
@@ -2200,42 +2461,11 @@ var HyveClient = class {
       return false;
     }
     try {
-      if (eventDetails) {
-        try {
-          if (typeof eventDetails === "string") {
-            JSON.parse(eventDetails);
-          } else if (typeof eventDetails === "object") {
-            JSON.stringify(eventDetails);
-          }
-        } catch (validationError) {
-          logger.error("Invalid JSON in eventDetails:", validationError);
-          logger.error("eventDetails value:", eventDetails);
-          return false;
-        }
-      }
-      let parsedEventDetails = {};
-      if (eventDetails) {
-        if (typeof eventDetails === "string") {
-          try {
-            parsedEventDetails = JSON.parse(eventDetails);
-          } catch {
-          }
-        } else {
-          parsedEventDetails = eventDetails;
-        }
+      const enrichedEventDetails = this.enrichEventDetails(eventDetails);
+      if (enrichedEventDetails === null) {
+        return false;
       }
       const attribution = getAttributionData();
-      const enrichedEventDetails = {
-        // Device info
-        ...getEssentialDeviceInfo(),
-        // Attribution data
-        ...attribution,
-        // Timestamp and session context
-        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-        session_id: this.sessionId,
-        // Event-specific details can override any of the above
-        ...parsedEventDetails
-      };
       const telemetryEvent = {
         game_id: this.gameId,
         session_id: this.sessionId,
@@ -2274,6 +2504,122 @@ var HyveClient = class {
       return false;
     }
   }
+  /**
+   * Validates and enriches user-provided event details with device info,
+   * attribution data, and session context — matching the enrichment
+   * platform-v2 applies in sendAnalyticsEvent. Shared by the JWT and partner
+   * telemetry paths.
+   * @returns Enriched details object, or null if eventDetails is not valid JSON.
+   */
+  enrichEventDetails(eventDetails) {
+    let parsedEventDetails = {};
+    if (eventDetails) {
+      try {
+        if (typeof eventDetails === "string") {
+          parsedEventDetails = JSON.parse(eventDetails);
+        } else if (typeof eventDetails === "object") {
+          JSON.stringify(eventDetails);
+          parsedEventDetails = eventDetails;
+        }
+      } catch (validationError) {
+        logger.error("Invalid JSON in eventDetails:", validationError);
+        logger.error("eventDetails value:", eventDetails);
+        return null;
+      }
+    }
+    const attribution = getAttributionData();
+    return {
+      // Device info
+      ...getEssentialDeviceInfo(),
+      // Attribution data
+      ...attribution,
+      // Timestamp and session context
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      session_id: this.sessionId,
+      // Event-specific details can override any of the above
+      ...parsedEventDetails
+    };
+  }
+  /**
+   * Sends a telemetry event via the partner analytics endpoint using a partner
+   * API key (x-api-key) instead of a hyve JWT. Used by externally-hosted games
+   * such as CrazyGames. game_id is derived from the API key server-side and is
+   * therefore not sent. hyve_user_id carries the `cg:`-prefixed CrazyGames id,
+   * or a guest sentinel when the player is not logged in.
+   */
+  async sendPartnerTelemetry(eventLocation, eventCategory, eventAction, eventSubCategory, eventSubAction, eventDetails) {
+    if (!this.partnerApiKey) {
+      logger.error("Partner API key required for partner telemetry path.");
+      return false;
+    }
+    if (this.crazyGamesService && this.crazyGamesInitPromise) {
+      await this.crazyGamesInitPromise;
+    }
+    try {
+      const enrichedEventDetails = this.enrichEventDetails(eventDetails);
+      if (enrichedEventDetails === null) {
+        return false;
+      }
+      const hyveUserId = this.crazyGamesUserId ? `cg:${this.crazyGamesUserId}` : "cg:guest";
+      const partnerEvent = {
+        session_id: this.sessionId,
+        hyve_user_id: hyveUserId,
+        event_location: eventLocation,
+        event_category: eventCategory,
+        event_sub_category: eventSubCategory || null,
+        event_action: eventAction,
+        event_sub_action: eventSubAction || null,
+        event_details: enrichedEventDetails
+      };
+      logger.debug("Sending partner telemetry event:", partnerEvent);
+      const base = this.partnerApiBaseUrl || this.apiBaseUrl;
+      const telemetryUrl = `${base}/api/v1/partners/analytics/events`;
+      const response = await fetch(telemetryUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-api-key": this.partnerApiKey
+        },
+        body: JSON.stringify(partnerEvent)
+      });
+      if (response.ok) {
+        logger.info("Partner telemetry event sent successfully:", response.status);
+        return true;
+      } else {
+        const errorText = await response.text();
+        logger.error(
+          "Failed to send partner telemetry event:",
+          response.status,
+          errorText
+        );
+        return false;
+      }
+    } catch (error) {
+      logger.error("Error sending partner telemetry event:", error);
+      return false;
+    }
+  }
+  /**
+   * Seeds the CrazyGames user id used for telemetry attribution and registers
+   * an auth listener so the id updates if a guest logs in mid-session.
+   * The id is client-asserted (spoofable) and used only as an attribution label.
+   */
+  async seedCrazyGamesUser() {
+    if (!this.crazyGamesService) return;
+    if (!this.crazyGamesService.isUserAccountAvailable()) {
+      logger.info("CrazyGames account system unavailable \u2014 telemetry attributed by session only");
+      return;
+    }
+    const user = await this.crazyGamesService.getUser();
+    this.crazyGamesUserId = user?.__dangerousUserId ?? null;
+    if (this.crazyGamesUserId) {
+      logger.info("CrazyGames user id seeded for telemetry attribution");
+    }
+    this.crazyGamesService.addAuthListener((updatedUser) => {
+      this.crazyGamesUserId = updatedUser?.__dangerousUserId ?? null;
+      logger.info("CrazyGames auth state changed; telemetry user id updated");
+    });
+  }
   /**
    * Required lifecycle telemetry — Session start.
    * See https://docs.hyve.gg/docs/telemetry#required-lifecycle-events
@@ -2494,12 +2840,28 @@ 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 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).
+   * 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)
    */
-  getStorageAdapter(mode) {
-    const storageMode = mode || this.storageMode;
-    return storageMode === "local" ? this.localStorageAdapter : this.cloudStorageAdapter;
+  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") {
+        return this.crazyGamesStorageAdapter;
+      }
+    }
+    return this.storageMode === "local" ? this.localStorageAdapter : this.cloudStorageAdapter;
   }
   /**
    * Returns the current game ID or throws if not available.
@@ -2523,7 +2885,7 @@ var HyveClient = class {
     const gameId = this.requireGameId();
     const storageMode = storage || this.storageMode;
     logger.debug(`Saving game data to ${storageMode}: ${gameId}/${key}`);
-    const adapter = this.getStorageAdapter(storage);
+    const adapter = await this.getStorageAdapter(storage);
     const response = await adapter.saveGameData(gameId, key, value, operation, path);
     logger.info(`Game data saved successfully to ${storageMode}: ${gameId}/${key}`);
     return response;
@@ -2538,7 +2900,7 @@ var HyveClient = class {
     const gameId = this.requireGameId();
     const storageMode = storage || this.storageMode;
     logger.debug(`Batch saving ${items.length} game data entries to ${storageMode} for game: ${gameId}`);
-    const adapter = this.getStorageAdapter(storage);
+    const adapter = await this.getStorageAdapter(storage);
     const response = await adapter.batchSaveGameData(gameId, items);
     logger.info(`Batch saved ${items.length} game data entries successfully to ${storageMode}`);
     return response;
@@ -2553,7 +2915,7 @@ var HyveClient = class {
     const gameId = this.requireGameId();
     const storageMode = storage || this.storageMode;
     logger.debug(`Getting game data from ${storageMode}: ${gameId}/${key}`);
-    const adapter = this.getStorageAdapter(storage);
+    const adapter = await this.getStorageAdapter(storage);
     const data = await adapter.getGameData(gameId, key);
     if (data) {
       logger.info(`Game data retrieved successfully from ${storageMode}: ${gameId}/${key}`);
@@ -2572,7 +2934,7 @@ var HyveClient = class {
     const gameId = this.requireGameId();
     const storageMode = storage || this.storageMode;
     logger.debug(`Getting ${keys.length} game data entries from ${storageMode} for game: ${gameId}`);
-    const adapter = this.getStorageAdapter(storage);
+    const adapter = await this.getStorageAdapter(storage);
     const data = await adapter.getMultipleGameData(gameId, keys);
     logger.info(`Retrieved ${data.length} game data entries from ${storageMode}`);
     return data;
@@ -2587,7 +2949,7 @@ var HyveClient = class {
     const gameId = this.requireGameId();
     const storageMode = storage || this.storageMode;
     logger.debug(`Deleting game data from ${storageMode}: ${gameId}/${key}`);
-    const adapter = this.getStorageAdapter(storage);
+    const adapter = await this.getStorageAdapter(storage);
     const deleted = await adapter.deleteGameData(gameId, key);
     if (deleted) {
       logger.info(`Game data deleted successfully from ${storageMode}: ${gameId}/${key}`);
@@ -2606,7 +2968,7 @@ var HyveClient = class {
     const gameId = this.requireGameId();
     const storageMode = storage || this.storageMode;
     logger.debug(`Deleting ${keys.length} game data entries from ${storageMode} for game: ${gameId}`);
-    const adapter = this.getStorageAdapter(storage);
+    const adapter = await this.getStorageAdapter(storage);
     const deletedCount = await adapter.deleteMultipleGameData(gameId, keys);
     logger.info(`Deleted ${deletedCount} game data entries from ${storageMode}`);
     return deletedCount;
@@ -2824,6 +3186,7 @@ export {
   BillingService,
   CloudStorageAdapter,
   CrazyGamesService,
+  CrazyGamesStorageAdapter,
   HyveClient,
   LocalStorageAdapter,
   Logger,

package/dist/react.d.mts

@@ -256,6 +256,19 @@ interface HyveClientConfig extends TelemetryConfig {
     billing?: BillingConfig;
     /** Storage mode for persistent game data - 'cloud' (default) or 'local' */
     storageMode?: 'cloud' | 'local';
+    /**
+     * Partner API key for externally-hosted games (e.g. CrazyGames) that cannot
+     * carry a hyve JWT. When set, telemetry is sent to the partner analytics
+     * endpoint with an `x-api-key` header instead of the JWT path. The key is
+     * scoped to the `analytics` domain and bound to a game_id server-side.
+     * NOTE: this key ships in client-side game code and is therefore public.
+     */
+    partnerApiKey?: string;
+    /**
+     * Optional base URL for partner analytics requests. Defaults to apiBaseUrl
+     * when omitted.
+     */
+    partnerApiBaseUrl?: string;
 }
 /**
  * HyveClient provides telemetry and authentication functionality for Hyve games
@@ -276,6 +289,11 @@ declare class HyveClient {
     private storageMode;
     private cloudStorageAdapter;
     private localStorageAdapter;
+    private crazyGamesStorageAdapter;
+    private partnerApiKey;
+    private partnerApiBaseUrl;
+    /** Raw (unprefixed) CrazyGames __dangerousUserId, seeded at init and on login. */
+    private crazyGamesUserId;
     /**
      * Creates a new HyveClient instance
      * @param config Optional configuration including telemetry and ads
@@ -299,6 +317,28 @@ declare class HyveClient {
      * @returns Promise resolving to boolean indicating success
      */
     sendTelemetry(eventLocation: string, eventCategory: string, eventAction: string, eventSubCategory?: string | null, eventSubAction?: string | null, eventDetails?: Record<string, any> | string | null, platformId?: string | null): Promise<boolean>;
+    /**
+     * Validates and enriches user-provided event details with device info,
+     * attribution data, and session context — matching the enrichment
+     * platform-v2 applies in sendAnalyticsEvent. Shared by the JWT and partner
+     * telemetry paths.
+     * @returns Enriched details object, or null if eventDetails is not valid JSON.
+     */
+    private enrichEventDetails;
+    /**
+     * Sends a telemetry event via the partner analytics endpoint using a partner
+     * API key (x-api-key) instead of a hyve JWT. Used by externally-hosted games
+     * such as CrazyGames. game_id is derived from the API key server-side and is
+     * therefore not sent. hyve_user_id carries the `cg:`-prefixed CrazyGames id,
+     * or a guest sentinel when the player is not logged in.
+     */
+    private sendPartnerTelemetry;
+    /**
+     * Seeds the CrazyGames user id used for telemetry attribution and registers
+     * an auth listener so the id updates if a guest logs in mid-session.
+     * The id is client-asserted (spoofable) and used only as an attribution label.
+     */
+    private seedCrazyGamesUser;
     /**
      * Required lifecycle telemetry — Session start.
      * See https://docs.hyve.gg/docs/telemetry#required-lifecycle-events
@@ -419,7 +459,15 @@ declare class HyveClient {
      */
     reset(): void;
     /**
-     * Get the storage adapter based on mode
+     * Get the storage adapter based on 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).
+     * 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)
      */
     private getStorageAdapter;