@hyve-sdk/js 2.1.1 → 2.2.0

package/dist/index.d.mts

@@ -72,6 +72,8 @@ interface Inventory {
 type GameDataValue = string | number | boolean | null | GameDataValue[] | {
     [key: string]: GameDataValue;
 };
+/** Atomic operation type for persistent game data */
+type GameDataOperation = 'set' | 'add' | 'subtract' | 'multiply' | 'divide' | 'modulo' | 'min' | 'max' | 'append';
 /** Single game data item with metadata */
 interface GameDataItem {
     key: string;
@@ -79,10 +81,27 @@ interface GameDataItem {
     created_at: string;
     updated_at: string;
 }
-/** Response from save operations */
+/** Response from a single save operation */
 interface SaveGameDataResponse {
     success: boolean;
     message: string;
+    /** Resulting value after an atomic operation (only present when operation is used) */
+    result?: GameDataValue;
+}
+/** Per-item result in a batch save response */
+interface BatchSaveResultItem {
+    key: string;
+    success: boolean;
+    /** Resulting value after an atomic operation */
+    result?: GameDataValue;
+    error?: string;
+}
+/** Response from a batch save operation */
+interface BatchSaveGameDataResponse {
+    success: boolean;
+    message: string;
+    /** Per-item results (present when any item uses an operation) */
+    results?: BatchSaveResultItem[];
 }
 /** Response when getting a single game data entry */
 interface GetGameDataResponse {
@@ -101,6 +120,10 @@ interface DeleteGameDataResponse {
 interface GameDataBatchItem {
     key: string;
     value: GameDataValue;
+    /** Atomic operation to perform on the value */
+    operation?: GameDataOperation;
+    /** Dot-notation path targeting a nested field (e.g. "stats.score") */
+    path?: string;
 }
 
 /**
@@ -522,17 +545,19 @@ declare class HyveClient {
      * Save persistent game data
      * @param key Data key
      * @param value Data value (any JSON-serializable value)
+     * @param operation Optional atomic operation (e.g. 'add', 'max', 'append')
+     * @param path Optional dot-notation path to a nested field (e.g. 'stats.score')
      * @param storage Storage mode override ('cloud' or 'local')
      * @returns Promise resolving to save response
      */
-    saveGameData(key: string, value: GameDataValue, storage?: 'cloud' | 'local'): Promise<SaveGameDataResponse>;
+    saveGameData(key: string, value: GameDataValue, operation?: GameDataOperation, path?: string, storage?: 'cloud' | 'local'): Promise<SaveGameDataResponse>;
     /**
      * Batch save persistent game data
-     * @param items Array of key-value pairs to save
+     * @param items Array of items to save (each may include an optional operation and path)
      * @param storage Storage mode override ('cloud' or 'local')
-     * @returns Promise resolving to save response
+     * @returns Promise resolving to batch save response with per-item results
      */
-    batchSaveGameData(items: GameDataBatchItem[], storage?: 'cloud' | 'local'): Promise<SaveGameDataResponse>;
+    batchSaveGameData(items: GameDataBatchItem[], storage?: 'cloud' | 'local'): Promise<BatchSaveGameDataResponse>;
     /**
      * Get persistent game data
      * @param key Data key
@@ -794,8 +819,8 @@ declare class CrazyGamesService {
  * 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>;
+    saveGameData(gameId: string, key: string, value: GameDataValue, operation?: GameDataOperation, path?: string): Promise<SaveGameDataResponse>;
+    batchSaveGameData(gameId: string, items: GameDataBatchItem[]): Promise<BatchSaveGameDataResponse>;
     getGameData(gameId: string, key: string): Promise<GameDataItem | null>;
     getMultipleGameData(gameId: string, keys: string[]): Promise<GameDataItem[]>;
     deleteGameData(gameId: string, key: string): Promise<boolean>;
@@ -807,8 +832,8 @@ interface StorageAdapter {
 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>;
+    saveGameData(gameId: string, key: string, value: GameDataValue, operation?: GameDataOperation, path?: string): Promise<SaveGameDataResponse>;
+    batchSaveGameData(gameId: string, items: GameDataBatchItem[]): Promise<BatchSaveGameDataResponse>;
     getGameData(gameId: string, key: string): Promise<GameDataItem | null>;
     getMultipleGameData(gameId: string, keys: string[]): Promise<GameDataItem[]>;
     deleteGameData(gameId: string, key: string): Promise<boolean>;
@@ -823,8 +848,8 @@ declare class LocalStorageAdapter implements StorageAdapter {
     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>;
+    saveGameData(gameId: string, key: string, value: GameDataValue, _operation?: GameDataOperation, _path?: string): Promise<SaveGameDataResponse>;
+    batchSaveGameData(gameId: string, items: GameDataBatchItem[]): Promise<BatchSaveGameDataResponse>;
     getGameData(gameId: string, key: string): Promise<GameDataItem | null>;
     getMultipleGameData(gameId: string, keys: string[]): Promise<GameDataItem[]>;
     deleteGameData(gameId: string, key: string): Promise<boolean>;
@@ -1064,4 +1089,4 @@ declare class NativeBridge {
  */
 declare function generateUUID(): string;
 
-export { type AdConfig, type AdResult, type AdType, AdsService, type BillingConfig, BillingPlatform, type BillingProduct, BillingService, CloudStorageAdapter, CrazyGamesService, 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, PlaygamaService, type PurchaseResult, type SaveGameDataResponse, type StorageAdapter, type TelemetryAdditionalData, type TelemetryConfig, type TelemetryEvent, generateUUID, isDomainAllowed, logger, parseUrlParams };
+export { type AdConfig, type AdResult, type AdType, AdsService, type BatchSaveGameDataResponse, type BatchSaveResultItem, type BillingConfig, BillingPlatform, type BillingProduct, BillingService, CloudStorageAdapter, CrazyGamesService, type DeleteGameDataResponse, type GameDataBatchItem, type GameDataItem, type GameDataOperation, type GameDataValue, type GetGameDataBatchResponse, type GetGameDataResponse, HyveClient, type HyveClientConfig, type Inventory, type InventoryItem, LocalStorageAdapter, Logger, NativeBridge, type NativeMessage, type NativeMessageHandler, NativeMessageType, PlaygamaService, type PurchaseResult, type SaveGameDataResponse, type StorageAdapter, type TelemetryAdditionalData, type TelemetryConfig, type TelemetryEvent, generateUUID, isDomainAllowed, logger, parseUrlParams };

package/dist/index.d.ts

@@ -72,6 +72,8 @@ interface Inventory {
 type GameDataValue = string | number | boolean | null | GameDataValue[] | {
     [key: string]: GameDataValue;
 };
+/** Atomic operation type for persistent game data */
+type GameDataOperation = 'set' | 'add' | 'subtract' | 'multiply' | 'divide' | 'modulo' | 'min' | 'max' | 'append';
 /** Single game data item with metadata */
 interface GameDataItem {
     key: string;
@@ -79,10 +81,27 @@ interface GameDataItem {
     created_at: string;
     updated_at: string;
 }
-/** Response from save operations */
+/** Response from a single save operation */
 interface SaveGameDataResponse {
     success: boolean;
     message: string;
+    /** Resulting value after an atomic operation (only present when operation is used) */
+    result?: GameDataValue;
+}
+/** Per-item result in a batch save response */
+interface BatchSaveResultItem {
+    key: string;
+    success: boolean;
+    /** Resulting value after an atomic operation */
+    result?: GameDataValue;
+    error?: string;
+}
+/** Response from a batch save operation */
+interface BatchSaveGameDataResponse {
+    success: boolean;
+    message: string;
+    /** Per-item results (present when any item uses an operation) */
+    results?: BatchSaveResultItem[];
 }
 /** Response when getting a single game data entry */
 interface GetGameDataResponse {
@@ -101,6 +120,10 @@ interface DeleteGameDataResponse {
 interface GameDataBatchItem {
     key: string;
     value: GameDataValue;
+    /** Atomic operation to perform on the value */
+    operation?: GameDataOperation;
+    /** Dot-notation path targeting a nested field (e.g. "stats.score") */
+    path?: string;
 }
 
 /**
@@ -522,17 +545,19 @@ declare class HyveClient {
      * Save persistent game data
      * @param key Data key
      * @param value Data value (any JSON-serializable value)
+     * @param operation Optional atomic operation (e.g. 'add', 'max', 'append')
+     * @param path Optional dot-notation path to a nested field (e.g. 'stats.score')
      * @param storage Storage mode override ('cloud' or 'local')
      * @returns Promise resolving to save response
      */
-    saveGameData(key: string, value: GameDataValue, storage?: 'cloud' | 'local'): Promise<SaveGameDataResponse>;
+    saveGameData(key: string, value: GameDataValue, operation?: GameDataOperation, path?: string, storage?: 'cloud' | 'local'): Promise<SaveGameDataResponse>;
     /**
      * Batch save persistent game data
-     * @param items Array of key-value pairs to save
+     * @param items Array of items to save (each may include an optional operation and path)
      * @param storage Storage mode override ('cloud' or 'local')
-     * @returns Promise resolving to save response
+     * @returns Promise resolving to batch save response with per-item results
      */
-    batchSaveGameData(items: GameDataBatchItem[], storage?: 'cloud' | 'local'): Promise<SaveGameDataResponse>;
+    batchSaveGameData(items: GameDataBatchItem[], storage?: 'cloud' | 'local'): Promise<BatchSaveGameDataResponse>;
     /**
      * Get persistent game data
      * @param key Data key
@@ -794,8 +819,8 @@ declare class CrazyGamesService {
  * 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>;
+    saveGameData(gameId: string, key: string, value: GameDataValue, operation?: GameDataOperation, path?: string): Promise<SaveGameDataResponse>;
+    batchSaveGameData(gameId: string, items: GameDataBatchItem[]): Promise<BatchSaveGameDataResponse>;
     getGameData(gameId: string, key: string): Promise<GameDataItem | null>;
     getMultipleGameData(gameId: string, keys: string[]): Promise<GameDataItem[]>;
     deleteGameData(gameId: string, key: string): Promise<boolean>;
@@ -807,8 +832,8 @@ interface StorageAdapter {
 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>;
+    saveGameData(gameId: string, key: string, value: GameDataValue, operation?: GameDataOperation, path?: string): Promise<SaveGameDataResponse>;
+    batchSaveGameData(gameId: string, items: GameDataBatchItem[]): Promise<BatchSaveGameDataResponse>;
     getGameData(gameId: string, key: string): Promise<GameDataItem | null>;
     getMultipleGameData(gameId: string, keys: string[]): Promise<GameDataItem[]>;
     deleteGameData(gameId: string, key: string): Promise<boolean>;
@@ -823,8 +848,8 @@ declare class LocalStorageAdapter implements StorageAdapter {
     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>;
+    saveGameData(gameId: string, key: string, value: GameDataValue, _operation?: GameDataOperation, _path?: string): Promise<SaveGameDataResponse>;
+    batchSaveGameData(gameId: string, items: GameDataBatchItem[]): Promise<BatchSaveGameDataResponse>;
     getGameData(gameId: string, key: string): Promise<GameDataItem | null>;
     getMultipleGameData(gameId: string, keys: string[]): Promise<GameDataItem[]>;
     deleteGameData(gameId: string, key: string): Promise<boolean>;
@@ -1064,4 +1089,4 @@ declare class NativeBridge {
  */
 declare function generateUUID(): string;
 
-export { type AdConfig, type AdResult, type AdType, AdsService, type BillingConfig, BillingPlatform, type BillingProduct, BillingService, CloudStorageAdapter, CrazyGamesService, 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, PlaygamaService, type PurchaseResult, type SaveGameDataResponse, type StorageAdapter, type TelemetryAdditionalData, type TelemetryConfig, type TelemetryEvent, generateUUID, isDomainAllowed, logger, parseUrlParams };
+export { type AdConfig, type AdResult, type AdType, AdsService, type BatchSaveGameDataResponse, type BatchSaveResultItem, type BillingConfig, BillingPlatform, type BillingProduct, BillingService, CloudStorageAdapter, CrazyGamesService, type DeleteGameDataResponse, type GameDataBatchItem, type GameDataItem, type GameDataOperation, type GameDataValue, type GetGameDataBatchResponse, type GetGameDataResponse, HyveClient, type HyveClientConfig, type Inventory, type InventoryItem, LocalStorageAdapter, Logger, NativeBridge, type NativeMessage, type NativeMessageHandler, NativeMessageType, PlaygamaService, type PurchaseResult, type SaveGameDataResponse, type StorageAdapter, type TelemetryAdditionalData, type TelemetryConfig, type TelemetryEvent, generateUUID, isDomainAllowed, logger, parseUrlParams };

package/dist/index.js

@@ -1433,13 +1433,19 @@ var CloudStorageAdapter = class {
   constructor(callApi) {
     this.callApi = callApi;
   }
-  async saveGameData(gameId, key, value) {
+  async saveGameData(gameId, key, value, operation, path) {
     return this.callApi("/api/v1/persistent-game-data", {
       method: "POST",
       headers: {
         "Content-Type": "application/json"
       },
-      body: JSON.stringify({ game_id: gameId, key, value })
+      body: JSON.stringify({
+        game_id: gameId,
+        key,
+        value,
+        ...operation !== void 0 && { operation },
+        ...path !== void 0 && { path }
+      })
     });
   }
   async batchSaveGameData(gameId, items) {
@@ -1509,7 +1515,7 @@ var LocalStorageAdapter = class {
   getStorageKey(gameId, key) {
     return `${this.storagePrefix}:${gameId}:${key}`;
   }
-  async saveGameData(gameId, key, value) {
+  async saveGameData(gameId, key, value, _operation, _path) {
     try {
       const storageKey = this.getStorageKey(gameId, key);
       const now = (/* @__PURE__ */ new Date()).toISOString();
@@ -1932,30 +1938,34 @@ var HyveClient = class {
    * Returns the current game ID or throws if not available.
    */
   requireGameId() {
-    const gameId = this.requireGameId();
-    return gameId;
+    if (!this.gameId) {
+      throw new Error("Game ID required. Ensure game-id URL parameter is set.");
+    }
+    return this.gameId;
   }
   /**
    * Save persistent game data
    * @param key Data key
    * @param value Data value (any JSON-serializable value)
+   * @param operation Optional atomic operation (e.g. 'add', 'max', 'append')
+   * @param path Optional dot-notation path to a nested field (e.g. 'stats.score')
    * @param storage Storage mode override ('cloud' or 'local')
    * @returns Promise resolving to save response
    */
-  async saveGameData(key, value, storage) {
+  async saveGameData(key, value, operation, path, storage) {
     const gameId = this.requireGameId();
     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);
+    const response = await adapter.saveGameData(gameId, key, value, operation, path);
     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 items Array of items to save (each may include an optional operation and path)
    * @param storage Storage mode override ('cloud' or 'local')
-   * @returns Promise resolving to save response
+   * @returns Promise resolving to batch save response with per-item results
    */
   async batchSaveGameData(items, storage) {
     const gameId = this.requireGameId();

package/dist/index.mjs

@@ -1393,13 +1393,19 @@ var CloudStorageAdapter = class {
   constructor(callApi) {
     this.callApi = callApi;
   }
-  async saveGameData(gameId, key, value) {
+  async saveGameData(gameId, key, value, operation, path) {
     return this.callApi("/api/v1/persistent-game-data", {
       method: "POST",
       headers: {
         "Content-Type": "application/json"
       },
-      body: JSON.stringify({ game_id: gameId, key, value })
+      body: JSON.stringify({
+        game_id: gameId,
+        key,
+        value,
+        ...operation !== void 0 && { operation },
+        ...path !== void 0 && { path }
+      })
     });
   }
   async batchSaveGameData(gameId, items) {
@@ -1469,7 +1475,7 @@ var LocalStorageAdapter = class {
   getStorageKey(gameId, key) {
     return `${this.storagePrefix}:${gameId}:${key}`;
   }
-  async saveGameData(gameId, key, value) {
+  async saveGameData(gameId, key, value, _operation, _path) {
     try {
       const storageKey = this.getStorageKey(gameId, key);
       const now = (/* @__PURE__ */ new Date()).toISOString();
@@ -1892,30 +1898,34 @@ var HyveClient = class {
    * Returns the current game ID or throws if not available.
    */
   requireGameId() {
-    const gameId = this.requireGameId();
-    return gameId;
+    if (!this.gameId) {
+      throw new Error("Game ID required. Ensure game-id URL parameter is set.");
+    }
+    return this.gameId;
   }
   /**
    * Save persistent game data
    * @param key Data key
    * @param value Data value (any JSON-serializable value)
+   * @param operation Optional atomic operation (e.g. 'add', 'max', 'append')
+   * @param path Optional dot-notation path to a nested field (e.g. 'stats.score')
    * @param storage Storage mode override ('cloud' or 'local')
    * @returns Promise resolving to save response
    */
-  async saveGameData(key, value, storage) {
+  async saveGameData(key, value, operation, path, storage) {
     const gameId = this.requireGameId();
     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);
+    const response = await adapter.saveGameData(gameId, key, value, operation, path);
     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 items Array of items to save (each may include an optional operation and path)
    * @param storage Storage mode override ('cloud' or 'local')
-   * @returns Promise resolving to save response
+   * @returns Promise resolving to batch save response with per-item results
    */
   async batchSaveGameData(items, storage) {
     const gameId = this.requireGameId();

package/dist/react.d.mts

@@ -41,6 +41,8 @@ interface Inventory {
 type GameDataValue = string | number | boolean | null | GameDataValue[] | {
     [key: string]: GameDataValue;
 };
+/** Atomic operation type for persistent game data */
+type GameDataOperation = 'set' | 'add' | 'subtract' | 'multiply' | 'divide' | 'modulo' | 'min' | 'max' | 'append';
 /** Single game data item with metadata */
 interface GameDataItem {
     key: string;
@@ -48,15 +50,36 @@ interface GameDataItem {
     created_at: string;
     updated_at: string;
 }
-/** Response from save operations */
+/** Response from a single save operation */
 interface SaveGameDataResponse {
     success: boolean;
     message: string;
+    /** Resulting value after an atomic operation (only present when operation is used) */
+    result?: GameDataValue;
+}
+/** Per-item result in a batch save response */
+interface BatchSaveResultItem {
+    key: string;
+    success: boolean;
+    /** Resulting value after an atomic operation */
+    result?: GameDataValue;
+    error?: string;
+}
+/** Response from a batch save operation */
+interface BatchSaveGameDataResponse {
+    success: boolean;
+    message: string;
+    /** Per-item results (present when any item uses an operation) */
+    results?: BatchSaveResultItem[];
 }
 /** Batch item for saving multiple entries */
 interface GameDataBatchItem {
     key: string;
     value: GameDataValue;
+    /** Atomic operation to perform on the value */
+    operation?: GameDataOperation;
+    /** Dot-notation path targeting a nested field (e.g. "stats.score") */
+    path?: string;
 }
 
 /**
@@ -297,17 +320,19 @@ declare class HyveClient {
      * Save persistent game data
      * @param key Data key
      * @param value Data value (any JSON-serializable value)
+     * @param operation Optional atomic operation (e.g. 'add', 'max', 'append')
+     * @param path Optional dot-notation path to a nested field (e.g. 'stats.score')
      * @param storage Storage mode override ('cloud' or 'local')
      * @returns Promise resolving to save response
      */
-    saveGameData(key: string, value: GameDataValue, storage?: 'cloud' | 'local'): Promise<SaveGameDataResponse>;
+    saveGameData(key: string, value: GameDataValue, operation?: GameDataOperation, path?: string, storage?: 'cloud' | 'local'): Promise<SaveGameDataResponse>;
     /**
      * Batch save persistent game data
-     * @param items Array of key-value pairs to save
+     * @param items Array of items to save (each may include an optional operation and path)
      * @param storage Storage mode override ('cloud' or 'local')
-     * @returns Promise resolving to save response
+     * @returns Promise resolving to batch save response with per-item results
      */
-    batchSaveGameData(items: GameDataBatchItem[], storage?: 'cloud' | 'local'): Promise<SaveGameDataResponse>;
+    batchSaveGameData(items: GameDataBatchItem[], storage?: 'cloud' | 'local'): Promise<BatchSaveGameDataResponse>;
     /**
      * Get persistent game data
      * @param key Data key

package/dist/react.d.ts

@@ -41,6 +41,8 @@ interface Inventory {
 type GameDataValue = string | number | boolean | null | GameDataValue[] | {
     [key: string]: GameDataValue;
 };
+/** Atomic operation type for persistent game data */
+type GameDataOperation = 'set' | 'add' | 'subtract' | 'multiply' | 'divide' | 'modulo' | 'min' | 'max' | 'append';
 /** Single game data item with metadata */
 interface GameDataItem {
     key: string;
@@ -48,15 +50,36 @@ interface GameDataItem {
     created_at: string;
     updated_at: string;
 }
-/** Response from save operations */
+/** Response from a single save operation */
 interface SaveGameDataResponse {
     success: boolean;
     message: string;
+    /** Resulting value after an atomic operation (only present when operation is used) */
+    result?: GameDataValue;
+}
+/** Per-item result in a batch save response */
+interface BatchSaveResultItem {
+    key: string;
+    success: boolean;
+    /** Resulting value after an atomic operation */
+    result?: GameDataValue;
+    error?: string;
+}
+/** Response from a batch save operation */
+interface BatchSaveGameDataResponse {
+    success: boolean;
+    message: string;
+    /** Per-item results (present when any item uses an operation) */
+    results?: BatchSaveResultItem[];
 }
 /** Batch item for saving multiple entries */
 interface GameDataBatchItem {
     key: string;
     value: GameDataValue;
+    /** Atomic operation to perform on the value */
+    operation?: GameDataOperation;
+    /** Dot-notation path targeting a nested field (e.g. "stats.score") */
+    path?: string;
 }
 
 /**
@@ -297,17 +320,19 @@ declare class HyveClient {
      * Save persistent game data
      * @param key Data key
      * @param value Data value (any JSON-serializable value)
+     * @param operation Optional atomic operation (e.g. 'add', 'max', 'append')
+     * @param path Optional dot-notation path to a nested field (e.g. 'stats.score')
      * @param storage Storage mode override ('cloud' or 'local')
      * @returns Promise resolving to save response
      */
-    saveGameData(key: string, value: GameDataValue, storage?: 'cloud' | 'local'): Promise<SaveGameDataResponse>;
+    saveGameData(key: string, value: GameDataValue, operation?: GameDataOperation, path?: string, storage?: 'cloud' | 'local'): Promise<SaveGameDataResponse>;
     /**
      * Batch save persistent game data
-     * @param items Array of key-value pairs to save
+     * @param items Array of items to save (each may include an optional operation and path)
      * @param storage Storage mode override ('cloud' or 'local')
-     * @returns Promise resolving to save response
+     * @returns Promise resolving to batch save response with per-item results
      */
-    batchSaveGameData(items: GameDataBatchItem[], storage?: 'cloud' | 'local'): Promise<SaveGameDataResponse>;
+    batchSaveGameData(items: GameDataBatchItem[], storage?: 'cloud' | 'local'): Promise<BatchSaveGameDataResponse>;
     /**
      * Get persistent game data
      * @param key Data key

package/dist/react.js

@@ -1384,13 +1384,19 @@ var CloudStorageAdapter = class {
   constructor(callApi) {
     this.callApi = callApi;
   }
-  async saveGameData(gameId, key, value) {
+  async saveGameData(gameId, key, value, operation, path) {
     return this.callApi("/api/v1/persistent-game-data", {
       method: "POST",
       headers: {
         "Content-Type": "application/json"
       },
-      body: JSON.stringify({ game_id: gameId, key, value })
+      body: JSON.stringify({
+        game_id: gameId,
+        key,
+        value,
+        ...operation !== void 0 && { operation },
+        ...path !== void 0 && { path }
+      })
     });
   }
   async batchSaveGameData(gameId, items) {
@@ -1460,7 +1466,7 @@ var LocalStorageAdapter = class {
   getStorageKey(gameId, key) {
     return `${this.storagePrefix}:${gameId}:${key}`;
   }
-  async saveGameData(gameId, key, value) {
+  async saveGameData(gameId, key, value, _operation, _path) {
     try {
       const storageKey = this.getStorageKey(gameId, key);
       const now = (/* @__PURE__ */ new Date()).toISOString();
@@ -1883,30 +1889,34 @@ var HyveClient = class {
    * Returns the current game ID or throws if not available.
    */
   requireGameId() {
-    const gameId = this.requireGameId();
-    return gameId;
+    if (!this.gameId) {
+      throw new Error("Game ID required. Ensure game-id URL parameter is set.");
+    }
+    return this.gameId;
   }
   /**
    * Save persistent game data
    * @param key Data key
    * @param value Data value (any JSON-serializable value)
+   * @param operation Optional atomic operation (e.g. 'add', 'max', 'append')
+   * @param path Optional dot-notation path to a nested field (e.g. 'stats.score')
    * @param storage Storage mode override ('cloud' or 'local')
    * @returns Promise resolving to save response
    */
-  async saveGameData(key, value, storage) {
+  async saveGameData(key, value, operation, path, storage) {
     const gameId = this.requireGameId();
     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);
+    const response = await adapter.saveGameData(gameId, key, value, operation, path);
     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 items Array of items to save (each may include an optional operation and path)
    * @param storage Storage mode override ('cloud' or 'local')
-   * @returns Promise resolving to save response
+   * @returns Promise resolving to batch save response with per-item results
    */
   async batchSaveGameData(items, storage) {
     const gameId = this.requireGameId();

package/dist/react.mjs

@@ -1363,13 +1363,19 @@ var CloudStorageAdapter = class {
   constructor(callApi) {
     this.callApi = callApi;
   }
-  async saveGameData(gameId, key, value) {
+  async saveGameData(gameId, key, value, operation, path) {
     return this.callApi("/api/v1/persistent-game-data", {
       method: "POST",
       headers: {
         "Content-Type": "application/json"
       },
-      body: JSON.stringify({ game_id: gameId, key, value })
+      body: JSON.stringify({
+        game_id: gameId,
+        key,
+        value,
+        ...operation !== void 0 && { operation },
+        ...path !== void 0 && { path }
+      })
     });
   }
   async batchSaveGameData(gameId, items) {
@@ -1439,7 +1445,7 @@ var LocalStorageAdapter = class {
   getStorageKey(gameId, key) {
     return `${this.storagePrefix}:${gameId}:${key}`;
   }
-  async saveGameData(gameId, key, value) {
+  async saveGameData(gameId, key, value, _operation, _path) {
     try {
       const storageKey = this.getStorageKey(gameId, key);
       const now = (/* @__PURE__ */ new Date()).toISOString();
@@ -1862,30 +1868,34 @@ var HyveClient = class {
    * Returns the current game ID or throws if not available.
    */
   requireGameId() {
-    const gameId = this.requireGameId();
-    return gameId;
+    if (!this.gameId) {
+      throw new Error("Game ID required. Ensure game-id URL parameter is set.");
+    }
+    return this.gameId;
   }
   /**
    * Save persistent game data
    * @param key Data key
    * @param value Data value (any JSON-serializable value)
+   * @param operation Optional atomic operation (e.g. 'add', 'max', 'append')
+   * @param path Optional dot-notation path to a nested field (e.g. 'stats.score')
    * @param storage Storage mode override ('cloud' or 'local')
    * @returns Promise resolving to save response
    */
-  async saveGameData(key, value, storage) {
+  async saveGameData(key, value, operation, path, storage) {
     const gameId = this.requireGameId();
     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);
+    const response = await adapter.saveGameData(gameId, key, value, operation, path);
     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 items Array of items to save (each may include an optional operation and path)
    * @param storage Storage mode override ('cloud' or 'local')
-   * @returns Promise resolving to save response
+   * @returns Promise resolving to batch save response with per-item results
    */
   async batchSaveGameData(items, storage) {
     const gameId = this.requireGameId();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyve-sdk/js",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "Hyve SDK - TypeScript wrapper for Hyve game server integration",
   "private": false,
   "publishConfig": {
@@ -27,6 +27,14 @@
     "README.md",
     "LICENSE"
   ],
+  "scripts": {
+    "lint": "eslint . --max-warnings 0",
+    "check-types": "tsc --noEmit",
+    "build": "tsup",
+    "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",
@@ -63,19 +71,12 @@
     }
   },
   "devDependencies": {
+    "@repo/eslint-config": "workspace:*",
+    "@repo/typescript-config": "workspace:*",
     "@types/minimatch": "^5.1.2",
     "@types/react": "^18.3.28",
     "@types/uuid": "^10.0.0",
     "tsup": "^8.4.0",
-    "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",
-    "publish:npm": "pnpm publish --access public",
-    "publish:dry-run": "pnpm publish --dry-run --access public --no-git-checks"
+    "typescript": "^5.3.3"
   }
-}
+}