@hyve-sdk/js 2.4.0 → 2.4.2

package/README.md

@@ -5,53 +5,27 @@ TypeScript SDK for integrating games with the Hyve platform. Provides authentica
 ## Installation
 
 ```bash
-pnpm add @hyve-sdk/js
+bun add @hyve-sdk/js
 ```
 
 ## Quick Start
 
-```ts
-import { HyveClient } from "@hyve-sdk/js";
-
-// Authentication is automatic — the SDK reads hyve-access and game-id from the URL
-const client = new HyveClient();
-
-console.log("User ID:", client.getUserId());
-console.log("Game ID:", client.getGameId());
-console.log("Authenticated:", client.isUserAuthenticated());
-```
-
-The SDK reads authentication from URL parameters automatically during construction:
-
-```
-https://your-game.com?hyve-access=eyJhbGci...&game-id=my-game
-```
-
-**Environment detection** happens automatically from the parent page URL (games run in iframes):
-- Dev: `marvin.dev.hyve.gg` or `dev.hyve.gg`
-- Prod: `marvin.hyve.gg` or `hyve.gg`
-- Override with `isDev` in config for local testing only
-
-## React Integration
-
-Import from `@hyve-sdk/js/react` for the React provider and hook:
-
 ```tsx
 import { HyveSdkProvider, useHyveSdk } from "@hyve-sdk/js/react";
 
 function App() {
   return (
-    <HyveSdkProvider config={{ isDev: true }}>
+    <HyveSdkProvider>
       <Game />
     </HyveSdkProvider>
   );
 }
 
 function Game() {
-  const sdk = useHyveSdk();
+  const hyve = useHyveSdk();
 
   const handleScore = () => {
-    sdk.sendTelemetry("game", "player", "score_submitted", null, null, { score: 1000 });
+    hyve.sendTelemetry("game", "player", "score_submitted", null, null, { score: 1000 });
   };
 
   return <button onClick={handleScore}>Submit Score</button>;
@@ -61,17 +35,32 @@ function Game() {
 You can also pass a pre-created client:
 
 ```tsx
-const client = new HyveClient({ isDev: true });
+import { HyveClient } from "@hyve-sdk/js";
+import { HyveSdkProvider } from "@hyve-sdk/js/react";
+
+const client = new HyveClient();
 
 <HyveSdkProvider client={client}>
   <App />
 </HyveSdkProvider>
 ```
 
+The SDK reads authentication from URL parameters automatically during construction:
+
+```
+https://your-game.com?hyve-access=eyJhbGci...&game-id=my-game
+```
+
+**Environment detection** happens automatically from the parent page URL (games run in iframes):
+- Dev: `marvin.dev.hyve.gg` or `dev.hyve.gg`
+- Prod: `marvin.hyve.gg` or `hyve.gg`
+
 ## Telemetry
 
 ```ts
-await client.sendTelemetry(
+const hyve = useHyveSdk();
+
+await hyve.sendTelemetry(
   "game",        // location
   "player",      // category
   "action",      // action
@@ -80,7 +69,8 @@ await client.sendTelemetry(
   {              // event details (optional)
     damage: 100,
     targetId: "enemy-123",
-  }
+  },
+  "playgama"     // platform ID (optional)
 );
 ```
 
@@ -91,26 +81,34 @@ Requires a valid `hyve-access` JWT and `game-id` in the URL.
 Save and retrieve game data with either cloud (default) or local storage:
 
 ```ts
+const hyve = useHyveSdk();
+
 // Save a value
-await client.saveGameData("player_level", 5);
-await client.saveGameData("settings", { volume: 0.8, fullscreen: true });
+await hyve.saveGameData("player_level", 5);
+await hyve.saveGameData("settings", { volume: 0.8, fullscreen: true });
+
+// Atomic operations — read-modify-write server-side
+await hyve.saveGameData("coins", 100, "add");           // increment
+await hyve.saveGameData("high_score", 9999, "max");      // keep highest
+await hyve.saveGameData("stats", 1, "add", "level");     // nested path
 
 // Get a value
-const item = await client.getGameData("player_level");
+const item = await hyve.getGameData("player_level");
 console.log(item?.value); // 5
 
-// Batch save
-await client.batchSaveGameData([
+// Batch save (per-item operations supported)
+await hyve.batchSaveGameData([
   { key: "coins", value: 1200 },
   { key: "lives", value: 3 },
+  { key: "high_score", value: 5000, operation: "max" },
 ]);
 
 // Batch get
-const items = await client.getMultipleGameData(["coins", "lives"]);
+const items = await hyve.getMultipleGameData(["coins", "lives"]);
 
 // Delete
-await client.deleteGameData("temp_key");
-await client.deleteMultipleGameData(["key1", "key2"]);
+await hyve.deleteGameData("temp_key");
+await hyve.deleteMultipleGameData(["key1", "key2"]);
 ```
 
 ### Storage Modes
@@ -119,13 +117,13 @@ await client.deleteMultipleGameData(["key1", "key2"]);
 // Set mode at construction
 const client = new HyveClient({ storageMode: "local" });
 
-// Or override per-call
-await client.saveGameData("key", "value", "local");
-await client.getGameData("key", "cloud");
+// Or override per-call (storage is the last parameter)
+await hyve.saveGameData("key", "value", undefined, undefined, "local");
+await hyve.getGameData("key", "cloud");
 
 // Change mode at runtime
-client.configureStorage("cloud");
-console.log(client.getStorageMode()); // "cloud"
+hyve.configureStorage("cloud");
+console.log(hyve.getStorageMode()); // "cloud"
 ```
 
 | Mode | Description |
@@ -133,11 +131,52 @@ console.log(client.getStorageMode()); // "cloud"
 | `cloud` | Synced to backend API (default) |
 | `local` | Browser `localStorage`, device-only |
 
+## Leaderboards
+
+Rank players by numeric values stored in persistent game data.
+
+```ts
+const hyve = useHyveSdk();
+
+// 1. Store the player's score
+await hyve.saveGameData("high_score", 4200);
+
+// 2. Fetch the leaderboard
+const board = await hyve.getGameDataLeaderboard({ key: "high_score" });
+
+for (const entry of board.entries) {
+  console.log(`#${entry.rank} ${entry.username}: ${entry.score}`);
+}
+
+// The caller's own rank is included automatically
+if (board.user_position) {
+  console.log("Your rank:", board.user_position.rank);
+}
+```
+
+Use `score_path` to rank by a nested field, and `sort`/`limit`/`cursor` for pagination:
+
+```ts
+const board = await hyve.getGameDataLeaderboard({
+  key: "tetris_progress",
+  score_path: "stats.score",  // dot-notation path to numeric field
+  sort: "desc",               // "asc" | "desc" (default: "desc")
+  limit: 20,                  // 1–100 (default: 10)
+});
+
+if (board.has_more && board.next_cursor) {
+  const next = await hyve.getGameDataLeaderboard({
+    key: "tetris_progress",
+    cursor: board.next_cursor,
+  });
+}
+```
+
 ## Ads
 
 Ads are disabled by default and must be explicitly configured.
 
-```ts
+```tsx
 const client = new HyveClient({
   ads: {
     enabled: true,
@@ -147,13 +186,21 @@ const client = new HyveClient({
   },
 });
 
-const result = await client.showAd("rewarded");
+<HyveSdkProvider client={client}>
+  <App />
+</HyveSdkProvider>
+```
+
+```ts
+const hyve = useHyveSdk();
+
+const result = await hyve.showAd("rewarded");
 if (result.success) {
   console.log("User watched the ad");
 }
 
-await client.showAd("interstitial");  // between levels
-await client.showAd("preroll");       // game start
+await hyve.showAd("interstitial");  // between levels
+await hyve.showAd("preroll");       // game start
 ```
 
 | Ad Type | Use Case |
@@ -171,14 +218,16 @@ The SDK automatically routes ad calls through the appropriate platform SDK (Craz
 When running on CrazyGames, the SDK auto-initializes the CrazyGames SDK and routes ads through it. Use these additional lifecycle methods:
 
 ```ts
+const hyve = useHyveSdk();
+
 // Call when gameplay begins (required by CrazyGames policy)
-await client.gameplayStart();
+await hyve.gameplayStart();
 
 // Call when gameplay stops (paused, died, menu, etc.)
-await client.gameplayStop();
+await hyve.gameplayStop();
 
 // Trigger a celebration effect on the CrazyGames website
-await client.happytime();
+await hyve.happytime();
 ```
 
 ### Playgama
@@ -189,24 +238,32 @@ When running on Playgama, the SDK auto-initializes the Playgama Bridge and route
 
 Billing supports web (Stripe) and native (In-App Purchases) — platform is detected automatically.
 
-```ts
+```tsx
 const client = new HyveClient({
   billing: {
     stripePublishableKey: "pk_live_...",
   },
 });
 
-if (client.isBillingAvailable()) {
-  client.onPurchaseComplete((result) => {
+<HyveSdkProvider client={client}>
+  <App />
+</HyveSdkProvider>
+```
+
+```ts
+const hyve = useHyveSdk();
+
+if (hyve.isBillingAvailable()) {
+  hyve.onPurchaseComplete((result) => {
     console.log("Purchase successful:", result.transactionId);
   });
 
-  client.onPurchaseError((result) => {
+  hyve.onPurchaseError((result) => {
     console.error("Purchase failed:", result.error?.message);
   });
 
-  const products = await client.getBillingProducts();
-  await client.purchaseProduct("price_1234");
+  const products = await hyve.getBillingProducts();
+  await hyve.purchaseProduct("price_1234");
 }
 ```
 
@@ -294,7 +351,6 @@ localStorage.setItem("HYVE_SDK_LOG_LEVEL", "error,warn");
 
 ```ts
 new HyveClient(config?: {
-  isDev?: boolean;             // Override env detection (local testing only)
   apiBaseUrl?: string;         // Override API base URL
   storageMode?: "cloud" | "local";
   ads?: AdConfig;
@@ -310,6 +366,7 @@ new HyveClient(config?: {
 | `getGameId()` | `string \| null` | Game ID from URL or JWT |
 | `getSessionId()` | `string` | Unique session ID |
 | `getJwtToken()` | `string \| null` | Raw JWT string |
+| `getApiBaseUrl()` | `string` | Current API base URL |
 | `isUserAuthenticated()` | `boolean` | Whether a user ID was extracted |
 | `hasJwtToken()` | `boolean` | Whether a JWT is present |
 | `logout()` | `void` | Clear auth state |
@@ -322,24 +379,26 @@ new HyveClient(config?: {
 | `callApi<T>(endpoint, options?)` | `Promise<T>` | Authenticated fetch to the Hyve API |
 | `getInventory()` | `Promise<Inventory>` | Get user inventory |
 | `getInventoryItem(itemId)` | `Promise<InventoryItem>` | Get a specific inventory item |
+| `getMachineRender(machineId)` | `Promise<string>` | Fetch rendered HTML for a project machine |
 
 ### Telemetry
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `sendTelemetry(location, category, action, subCategory?, subAction?, details?)` | `Promise<boolean>` | Send an analytics event |
+| `sendTelemetry(location, category, action, subCategory?, subAction?, details?, platformId?)` | `Promise<boolean>` | Send an analytics event |
 | `updateTelemetryConfig(config)` | `void` | Update telemetry settings at runtime |
 
 ### Storage
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `saveGameData(key, value, storage?)` | `Promise<SaveGameDataResponse>` | Save a single value |
-| `batchSaveGameData(items, storage?)` | `Promise<SaveGameDataResponse>` | Save multiple values |
+| `saveGameData(key, value, operation?, path?, storage?)` | `Promise<SaveGameDataResponse>` | Save a single value; optional atomic operation and nested path |
+| `batchSaveGameData(items, storage?)` | `Promise<BatchSaveGameDataResponse>` | Save multiple values; each item may include an operation and path |
 | `getGameData(key, storage?)` | `Promise<GameDataItem \| null>` | Get a single value |
 | `getMultipleGameData(keys, storage?)` | `Promise<GameDataItem[]>` | Get multiple values |
 | `deleteGameData(key, storage?)` | `Promise<boolean>` | Delete a single value |
-| `deleteMultipleGameData(keys, storage?)` | `Promise<number>` | Delete multiple values |
+| `deleteMultipleGameData(keys, storage?)` | `Promise<number>` | Delete multiple values; returns count |
+| `getGameDataLeaderboard(params)` | `Promise<GameDataLeaderboardResponse>` | Fetch players ranked by a game data key |
 | `configureStorage(mode)` | `void` | Set default storage mode |
 | `getStorageMode()` | `"cloud" \| "local"` | Get current storage mode |
 

package/dist/index.d.mts

@@ -33,8 +33,8 @@ interface TelemetryEvent {
     event_action: string;
     /** Sub-action for detailed tracking (optional) */
     event_sub_action?: string | null;
-    /** Event details as JSON string or object (optional) */
-    event_details?: Record<string, any> | string | null;
+    /** Event details as object (optional) */
+    event_details?: Record<string, unknown> | null;
     /** Mapping details as JSON string or object (optional) */
     mapping_details?: Record<string, any> | string | null;
 }
@@ -42,7 +42,7 @@ interface TelemetryEvent {
  * Additional telemetry data that can be passed with events
  */
 interface TelemetryAdditionalData {
-    /** Optional additional data object (will be JSON stringified and put in event_details) */
+    /** Optional additional data object passed as event_details */
     [key: string]: any;
 }
 /**
@@ -506,7 +506,7 @@ declare class HyveClient {
      * @param platformId Optional platform identifier
      * @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>;
+    sendTelemetry(eventLocation: string, eventCategory: string, eventAction: string, eventSubCategory?: string | null, eventSubAction?: string | null, eventDetails?: Record<string, unknown> | null, platformId?: string | null): Promise<boolean>;
     /**
      * Makes an authenticated API call using the JWT token
      * @param endpoint API endpoint path (will be appended to base URL)

package/dist/index.d.ts

@@ -33,8 +33,8 @@ interface TelemetryEvent {
     event_action: string;
     /** Sub-action for detailed tracking (optional) */
     event_sub_action?: string | null;
-    /** Event details as JSON string or object (optional) */
-    event_details?: Record<string, any> | string | null;
+    /** Event details as object (optional) */
+    event_details?: Record<string, unknown> | null;
     /** Mapping details as JSON string or object (optional) */
     mapping_details?: Record<string, any> | string | null;
 }
@@ -42,7 +42,7 @@ interface TelemetryEvent {
  * Additional telemetry data that can be passed with events
  */
 interface TelemetryAdditionalData {
-    /** Optional additional data object (will be JSON stringified and put in event_details) */
+    /** Optional additional data object passed as event_details */
     [key: string]: any;
 }
 /**
@@ -506,7 +506,7 @@ declare class HyveClient {
      * @param platformId Optional platform identifier
      * @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>;
+    sendTelemetry(eventLocation: string, eventCategory: string, eventAction: string, eventSubCategory?: string | null, eventSubAction?: string | null, eventDetails?: Record<string, unknown> | null, platformId?: string | null): Promise<boolean>;
     /**
      * Makes an authenticated API call using the JWT token
      * @param endpoint API endpoint path (will be appended to base URL)

package/dist/index.js

@@ -1740,23 +1740,6 @@ 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;
-        }
-      }
-      const toJsonString = (data) => {
-        if (!data) return null;
-        return typeof data === "string" ? data : JSON.stringify(data);
-      };
       const telemetryEvent = {
         game_id: this.gameId,
         session_id: this.sessionId,
@@ -1766,7 +1749,7 @@ var HyveClient = class {
         event_action: eventAction,
         event_sub_category: eventSubCategory || null,
         event_sub_action: eventSubAction || null,
-        event_details: toJsonString(eventDetails)
+        event_details: eventDetails || null
       };
       logger.debug("Sending telemetry event:", telemetryEvent);
       const telemetryUrl = `${this.apiBaseUrl}/api/v1/analytics/send`;

package/dist/index.mjs

@@ -1700,23 +1700,6 @@ 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;
-        }
-      }
-      const toJsonString = (data) => {
-        if (!data) return null;
-        return typeof data === "string" ? data : JSON.stringify(data);
-      };
       const telemetryEvent = {
         game_id: this.gameId,
         session_id: this.sessionId,
@@ -1726,7 +1709,7 @@ var HyveClient = class {
         event_action: eventAction,
         event_sub_category: eventSubCategory || null,
         event_sub_action: eventSubAction || null,
-        event_details: toJsonString(eventDetails)
+        event_details: eventDetails || null
       };
       logger.debug("Sending telemetry event:", telemetryEvent);
       const telemetryUrl = `${this.apiBaseUrl}/api/v1/analytics/send`;

package/dist/react.d.mts

@@ -281,7 +281,7 @@ declare class HyveClient {
      * @param platformId Optional platform identifier
      * @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>;
+    sendTelemetry(eventLocation: string, eventCategory: string, eventAction: string, eventSubCategory?: string | null, eventSubAction?: string | null, eventDetails?: Record<string, unknown> | null, platformId?: string | null): Promise<boolean>;
     /**
      * Makes an authenticated API call using the JWT token
      * @param endpoint API endpoint path (will be appended to base URL)

package/dist/react.d.ts

@@ -281,7 +281,7 @@ declare class HyveClient {
      * @param platformId Optional platform identifier
      * @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>;
+    sendTelemetry(eventLocation: string, eventCategory: string, eventAction: string, eventSubCategory?: string | null, eventSubAction?: string | null, eventDetails?: Record<string, unknown> | null, platformId?: string | null): Promise<boolean>;
     /**
      * Makes an authenticated API call using the JWT token
      * @param endpoint API endpoint path (will be appended to base URL)

package/dist/react.js

@@ -1691,23 +1691,6 @@ 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;
-        }
-      }
-      const toJsonString = (data) => {
-        if (!data) return null;
-        return typeof data === "string" ? data : JSON.stringify(data);
-      };
       const telemetryEvent = {
         game_id: this.gameId,
         session_id: this.sessionId,
@@ -1717,7 +1700,7 @@ var HyveClient = class {
         event_action: eventAction,
         event_sub_category: eventSubCategory || null,
         event_sub_action: eventSubAction || null,
-        event_details: toJsonString(eventDetails)
+        event_details: eventDetails || null
       };
       logger.debug("Sending telemetry event:", telemetryEvent);
       const telemetryUrl = `${this.apiBaseUrl}/api/v1/analytics/send`;

package/dist/react.mjs

@@ -1670,23 +1670,6 @@ 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;
-        }
-      }
-      const toJsonString = (data) => {
-        if (!data) return null;
-        return typeof data === "string" ? data : JSON.stringify(data);
-      };
       const telemetryEvent = {
         game_id: this.gameId,
         session_id: this.sessionId,
@@ -1696,7 +1679,7 @@ var HyveClient = class {
         event_action: eventAction,
         event_sub_category: eventSubCategory || null,
         event_sub_action: eventSubAction || null,
-        event_details: toJsonString(eventDetails)
+        event_details: eventDetails || null
       };
       logger.debug("Sending telemetry event:", telemetryEvent);
       const telemetryUrl = `${this.apiBaseUrl}/api/v1/analytics/send`;

package/package.json

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