@hyve-sdk/js 1.3.5 → 1.4.0

package/README.md

@@ -36,11 +36,9 @@ Main client class for SDK operations including authentication, telemetry, and AP
 ```typescript
 import { HyveClient } from "@hyve-sdk/js";
 
-// Initialize with optional configuration
-const client = new HyveClient({
-  isDev: true,                  // Development mode (default: true)
-  apiBaseUrl: 'https://...'     // Optional custom API URL
-});
+// Initialize client
+// Environment (dev/prod) is automatically detected from the parent page URL
+const client = new HyveClient();
 
 // Authenticate from URL parameters
 // Extracts: hyve-token/signature, hyve-access (JWT), game-id
@@ -53,6 +51,20 @@ if (authenticated) {
 }
 ```
 
+**Environment Detection:**
+The SDK automatically detects whether to use dev or prod environment by checking the parent page URL:
+- **Dev**: `marvin.dev.hyve.gg` or `dev.hyve.gg`
+- **Prod**: `marvin.hyve.gg` or `hyve.gg`
+
+You can optionally override this for testing:
+```typescript
+// Only use for local testing - NOT for production code
+const client = new HyveClient({
+  isDev: true,                  // Force dev mode for testing
+  apiBaseUrl: 'https://...'     // Optional custom API URL
+});
+```
+
 ### Authentication Utilities
 
 #### Parse URL Parameters
@@ -292,7 +304,6 @@ import { HyveClient } from "@hyve-sdk/js";
 
 // Enable ads in initial config
 const client = new HyveClient({
-  isDev: true,
   ads: {
     enabled: true,  // Must be set to true
     sound: 'on',
@@ -390,7 +401,6 @@ import { HyveClient } from "@hyve-sdk/js";
 
 // Enable billing in initial config
 const client = new HyveClient({
-  isDev: true,
   billing: {
     stripePublishableKey: 'pk_test_...',
     checkoutUrl: 'https://your-api.com',
@@ -534,7 +544,6 @@ interface PurchaseResult {
 
 ```typescript
 const client = new HyveClient({
-  isDev: true,
   billing: {
     stripePublishableKey: process.env.VITE_STRIPE_KEY,
     checkoutUrl: process.env.VITE_CHECKOUT_URL,

package/dist/index.d.mts

@@ -2,7 +2,11 @@
  * Telemetry configuration options
  */
 interface TelemetryConfig {
-    /** Environment: true for dev, false for prod. Defaults to true (dev) */
+    /**
+     * Environment: true for dev, false for prod.
+     * AUTO-DETECTED from parent page URL by default - only set for local testing.
+     * Use this ONLY for testing, NOT in production code.
+     */
     isDev?: boolean;
     /** Base API URL for all API calls (telemetry and external). Can be set via env. If not provided, defaults based on isDev */
     apiBaseUrl?: string;
@@ -79,6 +83,43 @@ interface AdConfig$1 {
     /** Callback when user earns a reward (rewarded ads only) */
     onRewardEarned?: () => void;
 }
+/**
+ * Persistent Game Data Types
+ */
+/** Generic value type for game data storage - can be any JSON-serializable value */
+type GameDataValue = string | number | boolean | null | GameDataValue[] | {
+    [key: string]: GameDataValue;
+};
+/** Single game data item with metadata */
+interface GameDataItem {
+    key: string;
+    value: GameDataValue;
+    created_at: string;
+    updated_at: string;
+}
+/** Response from save operations */
+interface SaveGameDataResponse {
+    success: boolean;
+    message: string;
+}
+/** Response when getting a single game data entry */
+interface GetGameDataResponse {
+    data: GameDataItem;
+}
+/** Response when getting multiple game data entries */
+interface GetGameDataBatchResponse {
+    data: GameDataItem[];
+}
+/** Response after deleting game data */
+interface DeleteGameDataResponse {
+    success: boolean;
+    deleted_count: number;
+}
+/** Batch item for saving multiple entries */
+interface GameDataBatchItem {
+    key: string;
+    value: GameDataValue;
+}
 
 /**
  * Ads Service for Hyve SDK
@@ -388,6 +429,8 @@ interface HyveClientConfig extends TelemetryConfig {
     ads?: AdConfig$1;
     /** Billing configuration (disabled by default) */
     billing?: BillingConfig;
+    /** Storage mode for persistent game data - 'cloud' (default) or 'local' */
+    storageMode?: 'cloud' | 'local';
 }
 /**
  * HyveClient provides telemetry and authentication functionality for Hyve games
@@ -403,6 +446,9 @@ declare class HyveClient {
     private billingService;
     private billingConfig;
     private billingCallbacks;
+    private storageMode;
+    private cloudStorageAdapter;
+    private localStorageAdapter;
     /**
      * Creates a new HyveClient instance
      * @param config Optional configuration including telemetry and ads
@@ -493,6 +539,64 @@ declare class HyveClient {
      * Resets the client state
      */
     reset(): void;
+    /**
+     * Get the storage adapter based on mode
+     * @param mode Storage mode override (cloud or local)
+     */
+    private getStorageAdapter;
+    /**
+     * Save persistent game data
+     * @param key Data key
+     * @param value Data value (any JSON-serializable value)
+     * @param storage Storage mode override ('cloud' or 'local')
+     * @returns Promise resolving to save response
+     */
+    saveGameData(key: string, value: GameDataValue, storage?: 'cloud' | 'local'): Promise<SaveGameDataResponse>;
+    /**
+     * Batch save persistent game data
+     * @param items Array of key-value pairs to save
+     * @param storage Storage mode override ('cloud' or 'local')
+     * @returns Promise resolving to save response
+     */
+    batchSaveGameData(items: GameDataBatchItem[], storage?: 'cloud' | 'local'): Promise<SaveGameDataResponse>;
+    /**
+     * Get persistent game data
+     * @param key Data key
+     * @param storage Storage mode override ('cloud' or 'local')
+     * @returns Promise resolving to game data item or null if not found
+     */
+    getGameData(key: string, storage?: 'cloud' | 'local'): Promise<GameDataItem | null>;
+    /**
+     * Get multiple persistent game data entries
+     * @param keys Array of data keys
+     * @param storage Storage mode override ('cloud' or 'local')
+     * @returns Promise resolving to array of game data items
+     */
+    getMultipleGameData(keys: string[], storage?: 'cloud' | 'local'): Promise<GameDataItem[]>;
+    /**
+     * Delete persistent game data
+     * @param key Data key
+     * @param storage Storage mode override ('cloud' or 'local')
+     * @returns Promise resolving to boolean indicating if data was deleted
+     */
+    deleteGameData(key: string, storage?: 'cloud' | 'local'): Promise<boolean>;
+    /**
+     * Delete multiple persistent game data entries
+     * @param keys Array of data keys
+     * @param storage Storage mode override ('cloud' or 'local')
+     * @returns Promise resolving to number of entries deleted
+     */
+    deleteMultipleGameData(keys: string[], storage?: 'cloud' | 'local'): Promise<number>;
+    /**
+     * Configure storage mode
+     * @param mode Storage mode ('cloud' or 'local')
+     */
+    configureStorage(mode: 'cloud' | 'local'): void;
+    /**
+     * Get current storage mode
+     * @returns Current storage mode
+     */
+    getStorageMode(): 'cloud' | 'local';
     /**
      * Configure ads service
      * @param config Ads configuration
@@ -570,6 +674,47 @@ declare class HyveClient {
     onBillingLog(callback: (level: "info" | "warn" | "error", message: string, data?: any) => void): void;
 }
 
+/**
+ * Storage adapter interface - supports cloud and local implementations
+ */
+interface StorageAdapter {
+    saveGameData(gameId: string, key: string, value: GameDataValue): Promise<SaveGameDataResponse>;
+    batchSaveGameData(gameId: string, items: GameDataBatchItem[]): Promise<SaveGameDataResponse>;
+    getGameData(gameId: string, key: string): Promise<GameDataItem | null>;
+    getMultipleGameData(gameId: string, keys: string[]): Promise<GameDataItem[]>;
+    deleteGameData(gameId: string, key: string): Promise<boolean>;
+    deleteMultipleGameData(gameId: string, keys: string[]): Promise<number>;
+}
+/**
+ * Cloud storage adapter - stores data via API calls to backend
+ */
+declare class CloudStorageAdapter implements StorageAdapter {
+    private callApi;
+    constructor(callApi: <T = any>(endpoint: string, options?: RequestInit) => Promise<T>);
+    saveGameData(gameId: string, key: string, value: GameDataValue): Promise<SaveGameDataResponse>;
+    batchSaveGameData(gameId: string, items: GameDataBatchItem[]): Promise<SaveGameDataResponse>;
+    getGameData(gameId: string, key: string): Promise<GameDataItem | null>;
+    getMultipleGameData(gameId: string, keys: string[]): Promise<GameDataItem[]>;
+    deleteGameData(gameId: string, key: string): Promise<boolean>;
+    deleteMultipleGameData(gameId: string, keys: string[]): Promise<number>;
+}
+/**
+ * Local storage adapter - stores data in browser's localStorage
+ * Namespaced by game_id only (device-specific storage)
+ */
+declare class LocalStorageAdapter implements StorageAdapter {
+    private getUserId;
+    private readonly storagePrefix;
+    constructor(getUserId: () => string | null);
+    private getStorageKey;
+    saveGameData(gameId: string, key: string, value: GameDataValue): Promise<SaveGameDataResponse>;
+    batchSaveGameData(gameId: string, items: GameDataBatchItem[]): Promise<SaveGameDataResponse>;
+    getGameData(gameId: string, key: string): Promise<GameDataItem | null>;
+    getMultipleGameData(gameId: string, keys: string[]): Promise<GameDataItem[]>;
+    deleteGameData(gameId: string, key: string): Promise<boolean>;
+    deleteMultipleGameData(gameId: string, keys: string[]): Promise<number>;
+}
+
 /**
  * Logger utility for the Hyve SDK
  * Automatically enabled in development (NODE_ENV !== 'production')
@@ -843,4 +988,4 @@ declare class NativeBridge {
  */
 declare function generateUUID(): string;
 
-export { type AdConfig$1 as AdConfig, type AdResult, type AdType, AdsService, type BillingConfig, BillingPlatform, type BillingProduct, BillingService, HyveClient, type HyveClientConfig, type Inventory, type InventoryItem, Logger, NativeBridge, type NativeMessage, type NativeMessageHandler, NativeMessageType, type PurchaseResult, type TelemetryAdditionalData, type TelemetryConfig, type TelemetryEvent, generateUUID, handleVerifyMessage, isDomainAllowed, logger, parseUrlParams, validateSignature, verifyAuthentication, verifyHyveToken };
+export { type AdConfig$1 as AdConfig, type AdResult, type AdType, AdsService, type BillingConfig, BillingPlatform, type BillingProduct, BillingService, CloudStorageAdapter, type DeleteGameDataResponse, type GameDataBatchItem, type GameDataItem, type GameDataValue, type GetGameDataBatchResponse, type GetGameDataResponse, HyveClient, type HyveClientConfig, type Inventory, type InventoryItem, LocalStorageAdapter, Logger, NativeBridge, type NativeMessage, type NativeMessageHandler, NativeMessageType, type PurchaseResult, type SaveGameDataResponse, type StorageAdapter, type TelemetryAdditionalData, type TelemetryConfig, type TelemetryEvent, generateUUID, handleVerifyMessage, isDomainAllowed, logger, parseUrlParams, validateSignature, verifyAuthentication, verifyHyveToken };

package/dist/index.d.ts

@@ -2,7 +2,11 @@
  * Telemetry configuration options
  */
 interface TelemetryConfig {
-    /** Environment: true for dev, false for prod. Defaults to true (dev) */
+    /**
+     * Environment: true for dev, false for prod.
+     * AUTO-DETECTED from parent page URL by default - only set for local testing.
+     * Use this ONLY for testing, NOT in production code.
+     */
     isDev?: boolean;
     /** Base API URL for all API calls (telemetry and external). Can be set via env. If not provided, defaults based on isDev */
     apiBaseUrl?: string;
@@ -79,6 +83,43 @@ interface AdConfig$1 {
     /** Callback when user earns a reward (rewarded ads only) */
     onRewardEarned?: () => void;
 }
+/**
+ * Persistent Game Data Types
+ */
+/** Generic value type for game data storage - can be any JSON-serializable value */
+type GameDataValue = string | number | boolean | null | GameDataValue[] | {
+    [key: string]: GameDataValue;
+};
+/** Single game data item with metadata */
+interface GameDataItem {
+    key: string;
+    value: GameDataValue;
+    created_at: string;
+    updated_at: string;
+}
+/** Response from save operations */
+interface SaveGameDataResponse {
+    success: boolean;
+    message: string;
+}
+/** Response when getting a single game data entry */
+interface GetGameDataResponse {
+    data: GameDataItem;
+}
+/** Response when getting multiple game data entries */
+interface GetGameDataBatchResponse {
+    data: GameDataItem[];
+}
+/** Response after deleting game data */
+interface DeleteGameDataResponse {
+    success: boolean;
+    deleted_count: number;
+}
+/** Batch item for saving multiple entries */
+interface GameDataBatchItem {
+    key: string;
+    value: GameDataValue;
+}
 
 /**
  * Ads Service for Hyve SDK
@@ -388,6 +429,8 @@ interface HyveClientConfig extends TelemetryConfig {
     ads?: AdConfig$1;
     /** Billing configuration (disabled by default) */
     billing?: BillingConfig;
+    /** Storage mode for persistent game data - 'cloud' (default) or 'local' */
+    storageMode?: 'cloud' | 'local';
 }
 /**
  * HyveClient provides telemetry and authentication functionality for Hyve games
@@ -403,6 +446,9 @@ declare class HyveClient {
     private billingService;
     private billingConfig;
     private billingCallbacks;
+    private storageMode;
+    private cloudStorageAdapter;
+    private localStorageAdapter;
     /**
      * Creates a new HyveClient instance
      * @param config Optional configuration including telemetry and ads
@@ -493,6 +539,64 @@ declare class HyveClient {
      * Resets the client state
      */
     reset(): void;
+    /**
+     * Get the storage adapter based on mode
+     * @param mode Storage mode override (cloud or local)
+     */
+    private getStorageAdapter;
+    /**
+     * Save persistent game data
+     * @param key Data key
+     * @param value Data value (any JSON-serializable value)
+     * @param storage Storage mode override ('cloud' or 'local')
+     * @returns Promise resolving to save response
+     */
+    saveGameData(key: string, value: GameDataValue, storage?: 'cloud' | 'local'): Promise<SaveGameDataResponse>;
+    /**
+     * Batch save persistent game data
+     * @param items Array of key-value pairs to save
+     * @param storage Storage mode override ('cloud' or 'local')
+     * @returns Promise resolving to save response
+     */
+    batchSaveGameData(items: GameDataBatchItem[], storage?: 'cloud' | 'local'): Promise<SaveGameDataResponse>;
+    /**
+     * Get persistent game data
+     * @param key Data key
+     * @param storage Storage mode override ('cloud' or 'local')
+     * @returns Promise resolving to game data item or null if not found
+     */
+    getGameData(key: string, storage?: 'cloud' | 'local'): Promise<GameDataItem | null>;
+    /**
+     * Get multiple persistent game data entries
+     * @param keys Array of data keys
+     * @param storage Storage mode override ('cloud' or 'local')
+     * @returns Promise resolving to array of game data items
+     */
+    getMultipleGameData(keys: string[], storage?: 'cloud' | 'local'): Promise<GameDataItem[]>;
+    /**
+     * Delete persistent game data
+     * @param key Data key
+     * @param storage Storage mode override ('cloud' or 'local')
+     * @returns Promise resolving to boolean indicating if data was deleted
+     */
+    deleteGameData(key: string, storage?: 'cloud' | 'local'): Promise<boolean>;
+    /**
+     * Delete multiple persistent game data entries
+     * @param keys Array of data keys
+     * @param storage Storage mode override ('cloud' or 'local')
+     * @returns Promise resolving to number of entries deleted
+     */
+    deleteMultipleGameData(keys: string[], storage?: 'cloud' | 'local'): Promise<number>;
+    /**
+     * Configure storage mode
+     * @param mode Storage mode ('cloud' or 'local')
+     */
+    configureStorage(mode: 'cloud' | 'local'): void;
+    /**
+     * Get current storage mode
+     * @returns Current storage mode
+     */
+    getStorageMode(): 'cloud' | 'local';
     /**
      * Configure ads service
      * @param config Ads configuration
@@ -570,6 +674,47 @@ declare class HyveClient {
     onBillingLog(callback: (level: "info" | "warn" | "error", message: string, data?: any) => void): void;
 }
 
+/**
+ * Storage adapter interface - supports cloud and local implementations
+ */
+interface StorageAdapter {
+    saveGameData(gameId: string, key: string, value: GameDataValue): Promise<SaveGameDataResponse>;
+    batchSaveGameData(gameId: string, items: GameDataBatchItem[]): Promise<SaveGameDataResponse>;
+    getGameData(gameId: string, key: string): Promise<GameDataItem | null>;
+    getMultipleGameData(gameId: string, keys: string[]): Promise<GameDataItem[]>;
+    deleteGameData(gameId: string, key: string): Promise<boolean>;
+    deleteMultipleGameData(gameId: string, keys: string[]): Promise<number>;
+}
+/**
+ * Cloud storage adapter - stores data via API calls to backend
+ */
+declare class CloudStorageAdapter implements StorageAdapter {
+    private callApi;
+    constructor(callApi: <T = any>(endpoint: string, options?: RequestInit) => Promise<T>);
+    saveGameData(gameId: string, key: string, value: GameDataValue): Promise<SaveGameDataResponse>;
+    batchSaveGameData(gameId: string, items: GameDataBatchItem[]): Promise<SaveGameDataResponse>;
+    getGameData(gameId: string, key: string): Promise<GameDataItem | null>;
+    getMultipleGameData(gameId: string, keys: string[]): Promise<GameDataItem[]>;
+    deleteGameData(gameId: string, key: string): Promise<boolean>;
+    deleteMultipleGameData(gameId: string, keys: string[]): Promise<number>;
+}
+/**
+ * Local storage adapter - stores data in browser's localStorage
+ * Namespaced by game_id only (device-specific storage)
+ */
+declare class LocalStorageAdapter implements StorageAdapter {
+    private getUserId;
+    private readonly storagePrefix;
+    constructor(getUserId: () => string | null);
+    private getStorageKey;
+    saveGameData(gameId: string, key: string, value: GameDataValue): Promise<SaveGameDataResponse>;
+    batchSaveGameData(gameId: string, items: GameDataBatchItem[]): Promise<SaveGameDataResponse>;
+    getGameData(gameId: string, key: string): Promise<GameDataItem | null>;
+    getMultipleGameData(gameId: string, keys: string[]): Promise<GameDataItem[]>;
+    deleteGameData(gameId: string, key: string): Promise<boolean>;
+    deleteMultipleGameData(gameId: string, keys: string[]): Promise<number>;
+}
+
 /**
  * Logger utility for the Hyve SDK
  * Automatically enabled in development (NODE_ENV !== 'production')
@@ -843,4 +988,4 @@ declare class NativeBridge {
  */
 declare function generateUUID(): string;
 
-export { type AdConfig$1 as AdConfig, type AdResult, type AdType, AdsService, type BillingConfig, BillingPlatform, type BillingProduct, BillingService, HyveClient, type HyveClientConfig, type Inventory, type InventoryItem, Logger, NativeBridge, type NativeMessage, type NativeMessageHandler, NativeMessageType, type PurchaseResult, type TelemetryAdditionalData, type TelemetryConfig, type TelemetryEvent, generateUUID, handleVerifyMessage, isDomainAllowed, logger, parseUrlParams, validateSignature, verifyAuthentication, verifyHyveToken };
+export { type AdConfig$1 as AdConfig, type AdResult, type AdType, AdsService, type BillingConfig, BillingPlatform, type BillingProduct, BillingService, CloudStorageAdapter, type DeleteGameDataResponse, type GameDataBatchItem, type GameDataItem, type GameDataValue, type GetGameDataBatchResponse, type GetGameDataResponse, HyveClient, type HyveClientConfig, type Inventory, type InventoryItem, LocalStorageAdapter, Logger, NativeBridge, type NativeMessage, type NativeMessageHandler, NativeMessageType, type PurchaseResult, type SaveGameDataResponse, type StorageAdapter, type TelemetryAdditionalData, type TelemetryConfig, type TelemetryEvent, generateUUID, handleVerifyMessage, isDomainAllowed, logger, parseUrlParams, validateSignature, verifyAuthentication, verifyHyveToken };

package/dist/index.js

@@ -23,7 +23,9 @@ __export(index_exports, {
   AdsService: () => AdsService,
   BillingPlatform: () => BillingPlatform,
   BillingService: () => BillingService,
+  CloudStorageAdapter: () => CloudStorageAdapter,
   HyveClient: () => HyveClient,
+  LocalStorageAdapter: () => LocalStorageAdapter,
   Logger: () => Logger,
   NativeBridge: () => NativeBridge,
   NativeMessageType: () => NativeMessageType,
@@ -1330,6 +1332,133 @@ var BillingService = class {
   }
 };
 
+// src/services/storage.ts
+var CloudStorageAdapter = class {
+  constructor(callApi) {
+    this.callApi = callApi;
+  }
+  async saveGameData(gameId, key, value) {
+    return this.callApi("/api/v1/persistent-game-data", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({ game_id: gameId, key, value })
+    });
+  }
+  async batchSaveGameData(gameId, items) {
+    return this.callApi(
+      "/api/v1/persistent-game-data/batch",
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ game_id: gameId, items })
+      }
+    );
+  }
+  async getGameData(gameId, key) {
+    try {
+      const params = new URLSearchParams({ game_id: gameId, key });
+      const response = await this.callApi(
+        `/api/v1/persistent-game-data?${params}`
+      );
+      return response.data;
+    } catch (error) {
+      if (error instanceof Error && error.message.includes("404")) {
+        return null;
+      }
+      throw error;
+    }
+  }
+  async getMultipleGameData(gameId, keys) {
+    const params = new URLSearchParams({ game_id: gameId });
+    keys.forEach((key) => params.append("keys", key));
+    const response = await this.callApi(
+      `/api/v1/persistent-game-data?${params}`
+    );
+    return response.data;
+  }
+  async deleteGameData(gameId, key) {
+    try {
+      const params = new URLSearchParams({ game_id: gameId, key });
+      const response = await this.callApi(
+        `/api/v1/persistent-game-data?${params}`,
+        { method: "DELETE" }
+      );
+      return response.success && response.deleted_count > 0;
+    } catch (error) {
+      if (error instanceof Error && error.message.includes("404")) {
+        return false;
+      }
+      throw error;
+    }
+  }
+  async deleteMultipleGameData(gameId, keys) {
+    const params = new URLSearchParams({ game_id: gameId });
+    keys.forEach((key) => params.append("keys", key));
+    const response = await this.callApi(
+      `/api/v1/persistent-game-data?${params}`,
+      { method: "DELETE" }
+    );
+    return response.deleted_count;
+  }
+};
+var LocalStorageAdapter = class {
+  constructor(getUserId) {
+    this.getUserId = getUserId;
+  }
+  storagePrefix = "hyve_game_data";
+  getStorageKey(gameId, key) {
+    return `${this.storagePrefix}:${gameId}:${key}`;
+  }
+  async saveGameData(gameId, key, value) {
+    try {
+      const storageKey = this.getStorageKey(gameId, key);
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const existing = localStorage.getItem(storageKey);
+      const createdAt = existing ? JSON.parse(existing).created_at || now : now;
+      const item = { key, value, created_at: createdAt, updated_at: now };
+      localStorage.setItem(storageKey, JSON.stringify(item));
+      return { success: true, message: "Data saved successfully" };
+    } catch (error) {
+      throw new Error(`Failed to save: ${error instanceof Error ? error.message : "Unknown"}`);
+    }
+  }
+  async batchSaveGameData(gameId, items) {
+    for (const item of items) {
+      await this.saveGameData(gameId, item.key, item.value);
+    }
+    return { success: true, message: `${items.length} items saved` };
+  }
+  async getGameData(gameId, key) {
+    const data = localStorage.getItem(this.getStorageKey(gameId, key));
+    return data ? JSON.parse(data) : 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 exists = localStorage.getItem(storageKey) !== null;
+    if (exists) localStorage.removeItem(storageKey);
+    return exists;
+  }
+  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() {
   try {
@@ -1371,6 +1500,9 @@ var HyveClient = class {
   billingConfig;
   // Store callbacks to preserve them when recreating BillingService
   billingCallbacks = {};
+  storageMode;
+  cloudStorageAdapter;
+  localStorageAdapter;
   /**
    * Creates a new HyveClient instance
    * @param config Optional configuration including telemetry and ads
@@ -1393,6 +1525,11 @@ var HyveClient = class {
     }
     this.billingConfig = config?.billing || {};
     this.billingService = new BillingService(this.billingConfig);
+    this.storageMode = config?.storageMode || "cloud";
+    this.cloudStorageAdapter = new CloudStorageAdapter(
+      (endpoint, options) => this.callApi(endpoint, options)
+    );
+    this.localStorageAdapter = new LocalStorageAdapter(() => this.getUserId());
     const envSource = config?.isDev !== void 0 ? "explicit config" : "auto-detected from parent URL";
     logger.info("==========================================");
     logger.info("HyveClient Initialized");
@@ -1409,11 +1546,13 @@ var HyveClient = class {
       "Billing configured:",
       Object.keys(this.billingConfig).length > 0
     );
+    logger.info("Storage mode:", this.storageMode);
     logger.debug("Config:", {
       isDev: this.telemetryConfig.isDev,
       hasCustomApiUrl: !!config?.apiBaseUrl,
       adsEnabled: config?.ads?.enabled || false,
-      billingConfigured: Object.keys(this.billingConfig).length > 0
+      billingConfigured: Object.keys(this.billingConfig).length > 0,
+      storageMode: this.storageMode
     });
     logger.info("==========================================");
   }
@@ -1678,6 +1817,146 @@ var HyveClient = class {
     this.sessionId = generateUUID();
     logger.info("Client reset with new sessionId:", this.sessionId);
   }
+  /**
+   * Get the storage adapter based on mode
+   * @param mode Storage mode override (cloud or local)
+   */
+  getStorageAdapter(mode) {
+    const storageMode = mode || this.storageMode;
+    return storageMode === "local" ? this.localStorageAdapter : this.cloudStorageAdapter;
+  }
+  /**
+   * Save persistent game data
+   * @param key Data key
+   * @param value Data value (any JSON-serializable value)
+   * @param storage Storage mode override ('cloud' or 'local')
+   * @returns Promise resolving to save response
+   */
+  async saveGameData(key, value, storage) {
+    const gameId = this.getGameId();
+    if (!gameId) {
+      throw new Error("game-id is required for persistent storage. Call authenticateFromUrl first.");
+    }
+    const storageMode = storage || this.storageMode;
+    logger.debug(`Saving game data to ${storageMode}: ${gameId}/${key}`);
+    const adapter = this.getStorageAdapter(storage);
+    const response = await adapter.saveGameData(gameId, key, value);
+    logger.info(`Game data saved successfully to ${storageMode}: ${gameId}/${key}`);
+    return response;
+  }
+  /**
+   * Batch save persistent game data
+   * @param items Array of key-value pairs to save
+   * @param storage Storage mode override ('cloud' or 'local')
+   * @returns Promise resolving to save response
+   */
+  async batchSaveGameData(items, storage) {
+    const gameId = this.getGameId();
+    if (!gameId) {
+      throw new Error("game-id is required for persistent storage. Call authenticateFromUrl first.");
+    }
+    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 response = await adapter.batchSaveGameData(gameId, items);
+    logger.info(`Batch saved ${items.length} game data entries successfully to ${storageMode}`);
+    return response;
+  }
+  /**
+   * Get persistent game data
+   * @param key Data key
+   * @param storage Storage mode override ('cloud' or 'local')
+   * @returns Promise resolving to game data item or null if not found
+   */
+  async getGameData(key, storage) {
+    const gameId = this.getGameId();
+    if (!gameId) {
+      throw new Error("game-id is required for persistent storage. Call authenticateFromUrl first.");
+    }
+    const storageMode = storage || this.storageMode;
+    logger.debug(`Getting game data from ${storageMode}: ${gameId}/${key}`);
+    const adapter = this.getStorageAdapter(storage);
+    const data = await adapter.getGameData(gameId, key);
+    if (data) {
+      logger.info(`Game data retrieved successfully from ${storageMode}: ${gameId}/${key}`);
+    } else {
+      logger.debug(`Game data not found in ${storageMode}: ${key}`);
+    }
+    return data;
+  }
+  /**
+   * Get multiple persistent game data entries
+   * @param keys Array of data keys
+   * @param storage Storage mode override ('cloud' or 'local')
+   * @returns Promise resolving to array of game data items
+   */
+  async getMultipleGameData(keys, storage) {
+    const gameId = this.getGameId();
+    if (!gameId) {
+      throw new Error("game-id is required for persistent storage. Call authenticateFromUrl first.");
+    }
+    const storageMode = storage || this.storageMode;
+    logger.debug(`Getting ${keys.length} game data entries from ${storageMode} for game: ${gameId}`);
+    const adapter = this.getStorageAdapter(storage);
+    const data = await adapter.getMultipleGameData(gameId, keys);
+    logger.info(`Retrieved ${data.length} game data entries from ${storageMode}`);
+    return data;
+  }
+  /**
+   * Delete persistent game data
+   * @param key Data key
+   * @param storage Storage mode override ('cloud' or 'local')
+   * @returns Promise resolving to boolean indicating if data was deleted
+   */
+  async deleteGameData(key, storage) {
+    const gameId = this.getGameId();
+    if (!gameId) {
+      throw new Error("game-id is required for persistent storage. Call authenticateFromUrl first.");
+    }
+    const storageMode = storage || this.storageMode;
+    logger.debug(`Deleting game data from ${storageMode}: ${gameId}/${key}`);
+    const adapter = this.getStorageAdapter(storage);
+    const deleted = await adapter.deleteGameData(gameId, key);
+    if (deleted) {
+      logger.info(`Game data deleted successfully from ${storageMode}: ${gameId}/${key}`);
+    } else {
+      logger.debug(`Game data not found in ${storageMode}: ${key}`);
+    }
+    return deleted;
+  }
+  /**
+   * Delete multiple persistent game data entries
+   * @param keys Array of data keys
+   * @param storage Storage mode override ('cloud' or 'local')
+   * @returns Promise resolving to number of entries deleted
+   */
+  async deleteMultipleGameData(keys, storage) {
+    const gameId = this.getGameId();
+    if (!gameId) {
+      throw new Error("game-id is required for persistent storage. Call authenticateFromUrl first.");
+    }
+    const storageMode = storage || this.storageMode;
+    logger.debug(`Deleting ${keys.length} game data entries from ${storageMode} for game: ${gameId}`);
+    const adapter = this.getStorageAdapter(storage);
+    const deletedCount = await adapter.deleteMultipleGameData(gameId, keys);
+    logger.info(`Deleted ${deletedCount} game data entries from ${storageMode}`);
+    return deletedCount;
+  }
+  /**
+   * Configure storage mode
+   * @param mode Storage mode ('cloud' or 'local')
+   */
+  configureStorage(mode) {
+    this.storageMode = mode;
+    logger.info("Storage mode updated to:", mode);
+  }
+  /**
+   * Get current storage mode
+   * @returns Current storage mode
+   */
+  getStorageMode() {
+    return this.storageMode;
+  }
   /**
    * Configure ads service
    * @param config Ads configuration
@@ -1815,7 +2094,9 @@ var HyveClient = class {
   AdsService,
   BillingPlatform,
   BillingService,
+  CloudStorageAdapter,
   HyveClient,
+  LocalStorageAdapter,
   Logger,
   NativeBridge,
   NativeMessageType,

package/dist/index.mjs

@@ -1290,6 +1290,133 @@ var BillingService = class {
   }
 };
 
+// src/services/storage.ts
+var CloudStorageAdapter = class {
+  constructor(callApi) {
+    this.callApi = callApi;
+  }
+  async saveGameData(gameId, key, value) {
+    return this.callApi("/api/v1/persistent-game-data", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({ game_id: gameId, key, value })
+    });
+  }
+  async batchSaveGameData(gameId, items) {
+    return this.callApi(
+      "/api/v1/persistent-game-data/batch",
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ game_id: gameId, items })
+      }
+    );
+  }
+  async getGameData(gameId, key) {
+    try {
+      const params = new URLSearchParams({ game_id: gameId, key });
+      const response = await this.callApi(
+        `/api/v1/persistent-game-data?${params}`
+      );
+      return response.data;
+    } catch (error) {
+      if (error instanceof Error && error.message.includes("404")) {
+        return null;
+      }
+      throw error;
+    }
+  }
+  async getMultipleGameData(gameId, keys) {
+    const params = new URLSearchParams({ game_id: gameId });
+    keys.forEach((key) => params.append("keys", key));
+    const response = await this.callApi(
+      `/api/v1/persistent-game-data?${params}`
+    );
+    return response.data;
+  }
+  async deleteGameData(gameId, key) {
+    try {
+      const params = new URLSearchParams({ game_id: gameId, key });
+      const response = await this.callApi(
+        `/api/v1/persistent-game-data?${params}`,
+        { method: "DELETE" }
+      );
+      return response.success && response.deleted_count > 0;
+    } catch (error) {
+      if (error instanceof Error && error.message.includes("404")) {
+        return false;
+      }
+      throw error;
+    }
+  }
+  async deleteMultipleGameData(gameId, keys) {
+    const params = new URLSearchParams({ game_id: gameId });
+    keys.forEach((key) => params.append("keys", key));
+    const response = await this.callApi(
+      `/api/v1/persistent-game-data?${params}`,
+      { method: "DELETE" }
+    );
+    return response.deleted_count;
+  }
+};
+var LocalStorageAdapter = class {
+  constructor(getUserId) {
+    this.getUserId = getUserId;
+  }
+  storagePrefix = "hyve_game_data";
+  getStorageKey(gameId, key) {
+    return `${this.storagePrefix}:${gameId}:${key}`;
+  }
+  async saveGameData(gameId, key, value) {
+    try {
+      const storageKey = this.getStorageKey(gameId, key);
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const existing = localStorage.getItem(storageKey);
+      const createdAt = existing ? JSON.parse(existing).created_at || now : now;
+      const item = { key, value, created_at: createdAt, updated_at: now };
+      localStorage.setItem(storageKey, JSON.stringify(item));
+      return { success: true, message: "Data saved successfully" };
+    } catch (error) {
+      throw new Error(`Failed to save: ${error instanceof Error ? error.message : "Unknown"}`);
+    }
+  }
+  async batchSaveGameData(gameId, items) {
+    for (const item of items) {
+      await this.saveGameData(gameId, item.key, item.value);
+    }
+    return { success: true, message: `${items.length} items saved` };
+  }
+  async getGameData(gameId, key) {
+    const data = localStorage.getItem(this.getStorageKey(gameId, key));
+    return data ? JSON.parse(data) : 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 exists = localStorage.getItem(storageKey) !== null;
+    if (exists) localStorage.removeItem(storageKey);
+    return exists;
+  }
+  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() {
   try {
@@ -1331,6 +1458,9 @@ var HyveClient = class {
   billingConfig;
   // Store callbacks to preserve them when recreating BillingService
   billingCallbacks = {};
+  storageMode;
+  cloudStorageAdapter;
+  localStorageAdapter;
   /**
    * Creates a new HyveClient instance
    * @param config Optional configuration including telemetry and ads
@@ -1353,6 +1483,11 @@ var HyveClient = class {
     }
     this.billingConfig = config?.billing || {};
     this.billingService = new BillingService(this.billingConfig);
+    this.storageMode = config?.storageMode || "cloud";
+    this.cloudStorageAdapter = new CloudStorageAdapter(
+      (endpoint, options) => this.callApi(endpoint, options)
+    );
+    this.localStorageAdapter = new LocalStorageAdapter(() => this.getUserId());
     const envSource = config?.isDev !== void 0 ? "explicit config" : "auto-detected from parent URL";
     logger.info("==========================================");
     logger.info("HyveClient Initialized");
@@ -1369,11 +1504,13 @@ var HyveClient = class {
       "Billing configured:",
       Object.keys(this.billingConfig).length > 0
     );
+    logger.info("Storage mode:", this.storageMode);
     logger.debug("Config:", {
       isDev: this.telemetryConfig.isDev,
       hasCustomApiUrl: !!config?.apiBaseUrl,
       adsEnabled: config?.ads?.enabled || false,
-      billingConfigured: Object.keys(this.billingConfig).length > 0
+      billingConfigured: Object.keys(this.billingConfig).length > 0,
+      storageMode: this.storageMode
     });
     logger.info("==========================================");
   }
@@ -1638,6 +1775,146 @@ var HyveClient = class {
     this.sessionId = generateUUID();
     logger.info("Client reset with new sessionId:", this.sessionId);
   }
+  /**
+   * Get the storage adapter based on mode
+   * @param mode Storage mode override (cloud or local)
+   */
+  getStorageAdapter(mode) {
+    const storageMode = mode || this.storageMode;
+    return storageMode === "local" ? this.localStorageAdapter : this.cloudStorageAdapter;
+  }
+  /**
+   * Save persistent game data
+   * @param key Data key
+   * @param value Data value (any JSON-serializable value)
+   * @param storage Storage mode override ('cloud' or 'local')
+   * @returns Promise resolving to save response
+   */
+  async saveGameData(key, value, storage) {
+    const gameId = this.getGameId();
+    if (!gameId) {
+      throw new Error("game-id is required for persistent storage. Call authenticateFromUrl first.");
+    }
+    const storageMode = storage || this.storageMode;
+    logger.debug(`Saving game data to ${storageMode}: ${gameId}/${key}`);
+    const adapter = this.getStorageAdapter(storage);
+    const response = await adapter.saveGameData(gameId, key, value);
+    logger.info(`Game data saved successfully to ${storageMode}: ${gameId}/${key}`);
+    return response;
+  }
+  /**
+   * Batch save persistent game data
+   * @param items Array of key-value pairs to save
+   * @param storage Storage mode override ('cloud' or 'local')
+   * @returns Promise resolving to save response
+   */
+  async batchSaveGameData(items, storage) {
+    const gameId = this.getGameId();
+    if (!gameId) {
+      throw new Error("game-id is required for persistent storage. Call authenticateFromUrl first.");
+    }
+    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 response = await adapter.batchSaveGameData(gameId, items);
+    logger.info(`Batch saved ${items.length} game data entries successfully to ${storageMode}`);
+    return response;
+  }
+  /**
+   * Get persistent game data
+   * @param key Data key
+   * @param storage Storage mode override ('cloud' or 'local')
+   * @returns Promise resolving to game data item or null if not found
+   */
+  async getGameData(key, storage) {
+    const gameId = this.getGameId();
+    if (!gameId) {
+      throw new Error("game-id is required for persistent storage. Call authenticateFromUrl first.");
+    }
+    const storageMode = storage || this.storageMode;
+    logger.debug(`Getting game data from ${storageMode}: ${gameId}/${key}`);
+    const adapter = this.getStorageAdapter(storage);
+    const data = await adapter.getGameData(gameId, key);
+    if (data) {
+      logger.info(`Game data retrieved successfully from ${storageMode}: ${gameId}/${key}`);
+    } else {
+      logger.debug(`Game data not found in ${storageMode}: ${key}`);
+    }
+    return data;
+  }
+  /**
+   * Get multiple persistent game data entries
+   * @param keys Array of data keys
+   * @param storage Storage mode override ('cloud' or 'local')
+   * @returns Promise resolving to array of game data items
+   */
+  async getMultipleGameData(keys, storage) {
+    const gameId = this.getGameId();
+    if (!gameId) {
+      throw new Error("game-id is required for persistent storage. Call authenticateFromUrl first.");
+    }
+    const storageMode = storage || this.storageMode;
+    logger.debug(`Getting ${keys.length} game data entries from ${storageMode} for game: ${gameId}`);
+    const adapter = this.getStorageAdapter(storage);
+    const data = await adapter.getMultipleGameData(gameId, keys);
+    logger.info(`Retrieved ${data.length} game data entries from ${storageMode}`);
+    return data;
+  }
+  /**
+   * Delete persistent game data
+   * @param key Data key
+   * @param storage Storage mode override ('cloud' or 'local')
+   * @returns Promise resolving to boolean indicating if data was deleted
+   */
+  async deleteGameData(key, storage) {
+    const gameId = this.getGameId();
+    if (!gameId) {
+      throw new Error("game-id is required for persistent storage. Call authenticateFromUrl first.");
+    }
+    const storageMode = storage || this.storageMode;
+    logger.debug(`Deleting game data from ${storageMode}: ${gameId}/${key}`);
+    const adapter = this.getStorageAdapter(storage);
+    const deleted = await adapter.deleteGameData(gameId, key);
+    if (deleted) {
+      logger.info(`Game data deleted successfully from ${storageMode}: ${gameId}/${key}`);
+    } else {
+      logger.debug(`Game data not found in ${storageMode}: ${key}`);
+    }
+    return deleted;
+  }
+  /**
+   * Delete multiple persistent game data entries
+   * @param keys Array of data keys
+   * @param storage Storage mode override ('cloud' or 'local')
+   * @returns Promise resolving to number of entries deleted
+   */
+  async deleteMultipleGameData(keys, storage) {
+    const gameId = this.getGameId();
+    if (!gameId) {
+      throw new Error("game-id is required for persistent storage. Call authenticateFromUrl first.");
+    }
+    const storageMode = storage || this.storageMode;
+    logger.debug(`Deleting ${keys.length} game data entries from ${storageMode} for game: ${gameId}`);
+    const adapter = this.getStorageAdapter(storage);
+    const deletedCount = await adapter.deleteMultipleGameData(gameId, keys);
+    logger.info(`Deleted ${deletedCount} game data entries from ${storageMode}`);
+    return deletedCount;
+  }
+  /**
+   * Configure storage mode
+   * @param mode Storage mode ('cloud' or 'local')
+   */
+  configureStorage(mode) {
+    this.storageMode = mode;
+    logger.info("Storage mode updated to:", mode);
+  }
+  /**
+   * Get current storage mode
+   * @returns Current storage mode
+   */
+  getStorageMode() {
+    return this.storageMode;
+  }
   /**
    * Configure ads service
    * @param config Ads configuration
@@ -1774,7 +2051,9 @@ export {
   AdsService,
   BillingPlatform,
   BillingService,
+  CloudStorageAdapter,
   HyveClient,
+  LocalStorageAdapter,
   Logger,
   NativeBridge,
   NativeMessageType,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyve-sdk/js",
-  "version": "1.3.5",
+  "version": "1.4.0",
   "description": "Hyve SDK - TypeScript wrapper for Hyve game server integration",
   "private": false,
   "publishConfig": {
@@ -15,14 +15,6 @@
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "lint": "eslint . --max-warnings 0",
-    "check-types": "tsc --noEmit",
-    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
-    "prepublishOnly": "pnpm run build && pnpm run check-types",
-    "publish:npm": "pnpm publish --access public",
-    "publish:dry-run": "pnpm publish --dry-run --access public --no-git-checks"
-  },
   "keywords": [
     "hyve",
     "game",
@@ -56,11 +48,18 @@
     }
   },
   "devDependencies": {
-    "@repo/eslint-config": "workspace:*",
-    "@repo/typescript-config": "workspace:*",
     "@types/minimatch": "^5.1.2",
     "@types/uuid": "^10.0.0",
     "tsup": "^8.4.0",
-    "typescript": "^5.3.3"
+    "typescript": "^5.3.3",
+    "@repo/eslint-config": "0.0.0",
+    "@repo/typescript-config": "0.0.0"
+  },
+  "scripts": {
+    "lint": "eslint . --max-warnings 0",
+    "check-types": "tsc --noEmit",
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "publish:npm": "pnpm publish --access public",
+    "publish:dry-run": "pnpm publish --dry-run --access public --no-git-checks"
   }
-}
+}