@hyve-sdk/js 2.3.0 → 2.4.1

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

@@ -125,6 +125,47 @@ interface GameDataBatchItem {
     /** Dot-notation path targeting a nested field (e.g. "stats.score") */
     path?: string;
 }
+/**
+ * Persistent Game Data Leaderboard Types
+ */
+/** A single entry in the game data leaderboard */
+interface GameDataLeaderboardEntry {
+    rank: number;
+    username: string;
+    avatar_url?: string | null;
+    hyve_user_id: string;
+    score: number;
+}
+/** The requesting user's position within the leaderboard */
+interface GameDataLeaderboardUserPosition {
+    rank: number;
+    score: number;
+    entry: GameDataLeaderboardEntry;
+}
+/** Response from the game data leaderboard endpoint */
+interface GameDataLeaderboardResponse {
+    entries: GameDataLeaderboardEntry[];
+    next_cursor?: string | null;
+    has_more: boolean;
+    /** Present when the authenticated user has data for the queried key */
+    user_position?: GameDataLeaderboardUserPosition | null;
+}
+/** Parameters for fetching a game data leaderboard */
+interface GetGameDataLeaderboardParams {
+    /** Data key to rank users by (e.g. "high_score", "lines_cleared") */
+    key: string;
+    /**
+     * Dot-notation path to extract a numeric score from a nested JSON value.
+     * Leave empty to use the top-level value (e.g. "stats.score").
+     */
+    score_path?: string;
+    /** Sort direction - "asc" or "desc" (default: "desc") */
+    sort?: 'asc' | 'desc';
+    /** Number of results per page, 1-100 (default: 10) */
+    limit?: number;
+    /** Pagination cursor from a previous response's next_cursor */
+    cursor?: string;
+}
 
 /**
  * Ads Service for Hyve SDK
@@ -586,6 +627,13 @@ declare class HyveClient {
      * @returns Promise resolving to number of entries deleted
      */
     deleteMultipleGameData(keys: string[], storage?: 'cloud' | 'local'): Promise<number>;
+    /**
+     * Fetch the persistent game data leaderboard for a given key.
+     * Rankings are derived from numeric values stored via saveGameData / batchSaveGameData.
+     * @param params Leaderboard query parameters (key is required)
+     * @returns Promise resolving to the leaderboard response including the caller's position
+     */
+    getGameDataLeaderboard(params: GetGameDataLeaderboardParams): Promise<GameDataLeaderboardResponse>;
     /**
      * Configure storage mode
      * @param mode Storage mode ('cloud' or 'local')
@@ -1095,4 +1143,4 @@ declare class NativeBridge {
  */
 declare function generateUUID(): string;
 
-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 };
+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 GameDataLeaderboardEntry, type GameDataLeaderboardResponse, type GameDataLeaderboardUserPosition, type GameDataOperation, type GameDataValue, type GetGameDataBatchResponse, type GetGameDataLeaderboardParams, 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

@@ -125,6 +125,47 @@ interface GameDataBatchItem {
     /** Dot-notation path targeting a nested field (e.g. "stats.score") */
     path?: string;
 }
+/**
+ * Persistent Game Data Leaderboard Types
+ */
+/** A single entry in the game data leaderboard */
+interface GameDataLeaderboardEntry {
+    rank: number;
+    username: string;
+    avatar_url?: string | null;
+    hyve_user_id: string;
+    score: number;
+}
+/** The requesting user's position within the leaderboard */
+interface GameDataLeaderboardUserPosition {
+    rank: number;
+    score: number;
+    entry: GameDataLeaderboardEntry;
+}
+/** Response from the game data leaderboard endpoint */
+interface GameDataLeaderboardResponse {
+    entries: GameDataLeaderboardEntry[];
+    next_cursor?: string | null;
+    has_more: boolean;
+    /** Present when the authenticated user has data for the queried key */
+    user_position?: GameDataLeaderboardUserPosition | null;
+}
+/** Parameters for fetching a game data leaderboard */
+interface GetGameDataLeaderboardParams {
+    /** Data key to rank users by (e.g. "high_score", "lines_cleared") */
+    key: string;
+    /**
+     * Dot-notation path to extract a numeric score from a nested JSON value.
+     * Leave empty to use the top-level value (e.g. "stats.score").
+     */
+    score_path?: string;
+    /** Sort direction - "asc" or "desc" (default: "desc") */
+    sort?: 'asc' | 'desc';
+    /** Number of results per page, 1-100 (default: 10) */
+    limit?: number;
+    /** Pagination cursor from a previous response's next_cursor */
+    cursor?: string;
+}
 
 /**
  * Ads Service for Hyve SDK
@@ -586,6 +627,13 @@ declare class HyveClient {
      * @returns Promise resolving to number of entries deleted
      */
     deleteMultipleGameData(keys: string[], storage?: 'cloud' | 'local'): Promise<number>;
+    /**
+     * Fetch the persistent game data leaderboard for a given key.
+     * Rankings are derived from numeric values stored via saveGameData / batchSaveGameData.
+     * @param params Leaderboard query parameters (key is required)
+     * @returns Promise resolving to the leaderboard response including the caller's position
+     */
+    getGameDataLeaderboard(params: GetGameDataLeaderboardParams): Promise<GameDataLeaderboardResponse>;
     /**
      * Configure storage mode
      * @param mode Storage mode ('cloud' or 'local')
@@ -1095,4 +1143,4 @@ declare class NativeBridge {
  */
 declare function generateUUID(): string;
 
-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 };
+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 GameDataLeaderboardEntry, type GameDataLeaderboardResponse, type GameDataLeaderboardUserPosition, type GameDataOperation, type GameDataValue, type GetGameDataBatchResponse, type GetGameDataLeaderboardParams, 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

@@ -2044,6 +2044,26 @@ var HyveClient = class {
     logger.info(`Deleted ${deletedCount} game data entries from ${storageMode}`);
     return deletedCount;
   }
+  /**
+   * Fetch the persistent game data leaderboard for a given key.
+   * Rankings are derived from numeric values stored via saveGameData / batchSaveGameData.
+   * @param params Leaderboard query parameters (key is required)
+   * @returns Promise resolving to the leaderboard response including the caller's position
+   */
+  async getGameDataLeaderboard(params) {
+    const gameId = this.requireGameId();
+    logger.debug(`Fetching game data leaderboard: ${gameId}/${params.key}`);
+    const query = new URLSearchParams({ game_id: gameId, key: params.key });
+    if (params.score_path) query.set("score_path", params.score_path);
+    if (params.sort) query.set("sort", params.sort);
+    if (params.limit !== void 0) query.set("limit", params.limit.toString());
+    if (params.cursor) query.set("cursor", params.cursor);
+    const response = await this.callApi(
+      `/api/v1/leaderboards/game-data?${query}`
+    );
+    logger.info(`Game data leaderboard fetched: ${response.entries.length} entries`);
+    return response;
+  }
   /**
    * Configure storage mode
    * @param mode Storage mode ('cloud' or 'local')

package/dist/index.mjs

@@ -2004,6 +2004,26 @@ var HyveClient = class {
     logger.info(`Deleted ${deletedCount} game data entries from ${storageMode}`);
     return deletedCount;
   }
+  /**
+   * Fetch the persistent game data leaderboard for a given key.
+   * Rankings are derived from numeric values stored via saveGameData / batchSaveGameData.
+   * @param params Leaderboard query parameters (key is required)
+   * @returns Promise resolving to the leaderboard response including the caller's position
+   */
+  async getGameDataLeaderboard(params) {
+    const gameId = this.requireGameId();
+    logger.debug(`Fetching game data leaderboard: ${gameId}/${params.key}`);
+    const query = new URLSearchParams({ game_id: gameId, key: params.key });
+    if (params.score_path) query.set("score_path", params.score_path);
+    if (params.sort) query.set("sort", params.sort);
+    if (params.limit !== void 0) query.set("limit", params.limit.toString());
+    if (params.cursor) query.set("cursor", params.cursor);
+    const response = await this.callApi(
+      `/api/v1/leaderboards/game-data?${query}`
+    );
+    logger.info(`Game data leaderboard fetched: ${response.entries.length} entries`);
+    return response;
+  }
   /**
    * Configure storage mode
    * @param mode Storage mode ('cloud' or 'local')

package/dist/react.d.mts

@@ -81,6 +81,47 @@ interface GameDataBatchItem {
     /** Dot-notation path targeting a nested field (e.g. "stats.score") */
     path?: string;
 }
+/**
+ * Persistent Game Data Leaderboard Types
+ */
+/** A single entry in the game data leaderboard */
+interface GameDataLeaderboardEntry {
+    rank: number;
+    username: string;
+    avatar_url?: string | null;
+    hyve_user_id: string;
+    score: number;
+}
+/** The requesting user's position within the leaderboard */
+interface GameDataLeaderboardUserPosition {
+    rank: number;
+    score: number;
+    entry: GameDataLeaderboardEntry;
+}
+/** Response from the game data leaderboard endpoint */
+interface GameDataLeaderboardResponse {
+    entries: GameDataLeaderboardEntry[];
+    next_cursor?: string | null;
+    has_more: boolean;
+    /** Present when the authenticated user has data for the queried key */
+    user_position?: GameDataLeaderboardUserPosition | null;
+}
+/** Parameters for fetching a game data leaderboard */
+interface GetGameDataLeaderboardParams {
+    /** Data key to rank users by (e.g. "high_score", "lines_cleared") */
+    key: string;
+    /**
+     * Dot-notation path to extract a numeric score from a nested JSON value.
+     * Leave empty to use the top-level value (e.g. "stats.score").
+     */
+    score_path?: string;
+    /** Sort direction - "asc" or "desc" (default: "desc") */
+    sort?: 'asc' | 'desc';
+    /** Number of results per page, 1-100 (default: 10) */
+    limit?: number;
+    /** Pagination cursor from a previous response's next_cursor */
+    cursor?: string;
+}
 
 /**
  * Ads Service for Hyve SDK
@@ -361,6 +402,13 @@ declare class HyveClient {
      * @returns Promise resolving to number of entries deleted
      */
     deleteMultipleGameData(keys: string[], storage?: 'cloud' | 'local'): Promise<number>;
+    /**
+     * Fetch the persistent game data leaderboard for a given key.
+     * Rankings are derived from numeric values stored via saveGameData / batchSaveGameData.
+     * @param params Leaderboard query parameters (key is required)
+     * @returns Promise resolving to the leaderboard response including the caller's position
+     */
+    getGameDataLeaderboard(params: GetGameDataLeaderboardParams): Promise<GameDataLeaderboardResponse>;
     /**
      * Configure storage mode
      * @param mode Storage mode ('cloud' or 'local')

package/dist/react.d.ts

@@ -81,6 +81,47 @@ interface GameDataBatchItem {
     /** Dot-notation path targeting a nested field (e.g. "stats.score") */
     path?: string;
 }
+/**
+ * Persistent Game Data Leaderboard Types
+ */
+/** A single entry in the game data leaderboard */
+interface GameDataLeaderboardEntry {
+    rank: number;
+    username: string;
+    avatar_url?: string | null;
+    hyve_user_id: string;
+    score: number;
+}
+/** The requesting user's position within the leaderboard */
+interface GameDataLeaderboardUserPosition {
+    rank: number;
+    score: number;
+    entry: GameDataLeaderboardEntry;
+}
+/** Response from the game data leaderboard endpoint */
+interface GameDataLeaderboardResponse {
+    entries: GameDataLeaderboardEntry[];
+    next_cursor?: string | null;
+    has_more: boolean;
+    /** Present when the authenticated user has data for the queried key */
+    user_position?: GameDataLeaderboardUserPosition | null;
+}
+/** Parameters for fetching a game data leaderboard */
+interface GetGameDataLeaderboardParams {
+    /** Data key to rank users by (e.g. "high_score", "lines_cleared") */
+    key: string;
+    /**
+     * Dot-notation path to extract a numeric score from a nested JSON value.
+     * Leave empty to use the top-level value (e.g. "stats.score").
+     */
+    score_path?: string;
+    /** Sort direction - "asc" or "desc" (default: "desc") */
+    sort?: 'asc' | 'desc';
+    /** Number of results per page, 1-100 (default: 10) */
+    limit?: number;
+    /** Pagination cursor from a previous response's next_cursor */
+    cursor?: string;
+}
 
 /**
  * Ads Service for Hyve SDK
@@ -361,6 +402,13 @@ declare class HyveClient {
      * @returns Promise resolving to number of entries deleted
      */
     deleteMultipleGameData(keys: string[], storage?: 'cloud' | 'local'): Promise<number>;
+    /**
+     * Fetch the persistent game data leaderboard for a given key.
+     * Rankings are derived from numeric values stored via saveGameData / batchSaveGameData.
+     * @param params Leaderboard query parameters (key is required)
+     * @returns Promise resolving to the leaderboard response including the caller's position
+     */
+    getGameDataLeaderboard(params: GetGameDataLeaderboardParams): Promise<GameDataLeaderboardResponse>;
     /**
      * Configure storage mode
      * @param mode Storage mode ('cloud' or 'local')

package/dist/react.js

@@ -1995,6 +1995,26 @@ var HyveClient = class {
     logger.info(`Deleted ${deletedCount} game data entries from ${storageMode}`);
     return deletedCount;
   }
+  /**
+   * Fetch the persistent game data leaderboard for a given key.
+   * Rankings are derived from numeric values stored via saveGameData / batchSaveGameData.
+   * @param params Leaderboard query parameters (key is required)
+   * @returns Promise resolving to the leaderboard response including the caller's position
+   */
+  async getGameDataLeaderboard(params) {
+    const gameId = this.requireGameId();
+    logger.debug(`Fetching game data leaderboard: ${gameId}/${params.key}`);
+    const query = new URLSearchParams({ game_id: gameId, key: params.key });
+    if (params.score_path) query.set("score_path", params.score_path);
+    if (params.sort) query.set("sort", params.sort);
+    if (params.limit !== void 0) query.set("limit", params.limit.toString());
+    if (params.cursor) query.set("cursor", params.cursor);
+    const response = await this.callApi(
+      `/api/v1/leaderboards/game-data?${query}`
+    );
+    logger.info(`Game data leaderboard fetched: ${response.entries.length} entries`);
+    return response;
+  }
   /**
    * Configure storage mode
    * @param mode Storage mode ('cloud' or 'local')

package/dist/react.mjs

@@ -1974,6 +1974,26 @@ var HyveClient = class {
     logger.info(`Deleted ${deletedCount} game data entries from ${storageMode}`);
     return deletedCount;
   }
+  /**
+   * Fetch the persistent game data leaderboard for a given key.
+   * Rankings are derived from numeric values stored via saveGameData / batchSaveGameData.
+   * @param params Leaderboard query parameters (key is required)
+   * @returns Promise resolving to the leaderboard response including the caller's position
+   */
+  async getGameDataLeaderboard(params) {
+    const gameId = this.requireGameId();
+    logger.debug(`Fetching game data leaderboard: ${gameId}/${params.key}`);
+    const query = new URLSearchParams({ game_id: gameId, key: params.key });
+    if (params.score_path) query.set("score_path", params.score_path);
+    if (params.sort) query.set("sort", params.sort);
+    if (params.limit !== void 0) query.set("limit", params.limit.toString());
+    if (params.cursor) query.set("cursor", params.cursor);
+    const response = await this.callApi(
+      `/api/v1/leaderboards/game-data?${query}`
+    );
+    logger.info(`Game data leaderboard fetched: ${response.entries.length} entries`);
+    return response;
+  }
   /**
    * Configure storage mode
    * @param mode Storage mode ('cloud' or 'local')

package/package.json

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