@hyve-sdk/js 2.3.0 → 2.4.0

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.0",
   "description": "Hyve SDK - TypeScript wrapper for Hyve game server integration",
   "private": false,
   "publishConfig": {