@hyve-sdk/js 2.13.0 → 2.14.0-canary.1

package/dist/index.d.mts

@@ -525,6 +525,25 @@ interface HyveClientConfig extends TelemetryConfig {
     billing?: BillingConfig;
     /** Storage mode for persistent game data - 'cloud' (default) or 'local' */
     storageMode?: 'cloud' | 'local';
+    /**
+     * Partner API key for externally-hosted games (e.g. CrazyGames) that cannot
+     * carry a hyve JWT. When set, telemetry is sent to the partner analytics
+     * endpoint with an `x-api-key` header instead of the JWT path. The key is
+     * scoped to the `analytics` domain and bound to a game_id server-side.
+     * NOTE: this key ships in client-side game code and is therefore public.
+     */
+    partnerApiKey?: string;
+    /**
+     * Optional base URL for partner analytics requests. Defaults to apiBaseUrl
+     * when omitted.
+     */
+    partnerApiBaseUrl?: string;
+    /**
+     * Game ID for externally-hosted builds (e.g. CrazyGames) whose URL carries
+     * no `game-id` parameter or hyve JWT. Used for storage key namespacing and
+     * telemetry. A `game-id` URL parameter still takes precedence when present.
+     */
+    gameId?: string;
 }
 /**
  * HyveClient provides telemetry and authentication functionality for Hyve games
@@ -545,6 +564,11 @@ declare class HyveClient {
     private storageMode;
     private cloudStorageAdapter;
     private localStorageAdapter;
+    private crazyGamesStorageAdapter;
+    private partnerApiKey;
+    private partnerApiBaseUrl;
+    /** Raw (unprefixed) CrazyGames __dangerousUserId, seeded at init and on login. */
+    private crazyGamesUserId;
     /**
      * Creates a new HyveClient instance
      * @param config Optional configuration including telemetry and ads
@@ -568,6 +592,28 @@ declare class HyveClient {
      * @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>;
+    /**
+     * Validates and enriches user-provided event details with device info,
+     * attribution data, and session context — matching the enrichment
+     * platform-v2 applies in sendAnalyticsEvent. Shared by the JWT and partner
+     * telemetry paths.
+     * @returns Enriched details object, or null if eventDetails is not valid JSON.
+     */
+    private enrichEventDetails;
+    /**
+     * Sends a telemetry event via the partner analytics endpoint using a partner
+     * API key (x-api-key) instead of a hyve JWT. Used by externally-hosted games
+     * such as CrazyGames. game_id is derived from the API key server-side and is
+     * therefore not sent. hyve_user_id carries the `cg:`-prefixed CrazyGames id,
+     * or a guest sentinel when the player is not logged in.
+     */
+    private sendPartnerTelemetry;
+    /**
+     * Seeds the CrazyGames user id used for telemetry attribution and registers
+     * an auth listener so the id updates if a guest logs in mid-session.
+     * The id is client-asserted (spoofable) and used only as an attribution label.
+     */
+    private seedCrazyGamesUser;
     /**
      * Required lifecycle telemetry — Session start.
      * See https://docs.hyve.gg/docs/telemetry#required-lifecycle-events
@@ -688,7 +734,15 @@ declare class HyveClient {
      */
     reset(): void;
     /**
-     * Get the storage adapter based on mode
+     * Get the storage adapter based on mode.
+     *
+     * Selection order:
+     * 1. An explicit `mode` override ('cloud' | 'local') always wins.
+     * 2. On the CrazyGames platform, the CrazyGames data store is auto-selected
+     *    (D3 — public storageMode type is preserved; this is chosen internally).
+     * 3. Otherwise the configured storageMode is used.
+     *
+     * Awaits CrazyGames SDK initialization so the data store is ready before use.
      * @param mode Storage mode override (cloud or local)
      */
     private getStorageAdapter;
@@ -925,9 +979,40 @@ interface CrazyGamesGameModule {
     gameplayStop(): void;
     happytime(): void;
 }
+/**
+ * CrazyGames user, as returned by `SDK.user.getUser()`.
+ * `__dangerousUserId` is client-asserted (spoofable) — we use it only as a
+ * telemetry attribution label, never for authentication.
+ */
+interface CrazyGamesUser {
+    __dangerousUserId: string;
+    username: string;
+    profilePictureUrl: string;
+}
+type CrazyGamesAuthListener = (user: CrazyGamesUser | null) => void;
+interface CrazyGamesUserModule {
+    isUserAccountAvailable: boolean;
+    getUser(): Promise<CrazyGamesUser | null>;
+    addAuthListener(callback: CrazyGamesAuthListener): void;
+    removeAuthListener(callback: CrazyGamesAuthListener): void;
+}
+/**
+ * CrazyGames key/value data store. Treated as async (promise-based) per the
+ * SDK v2 docs; awaiting a synchronous return is harmless, so the wrappers
+ * `await` every call regardless.
+ */
+interface CrazyGamesDataModule {
+    getItem(key: string): Promise<string | null> | string | null;
+    setItem(key: string, value: string): Promise<void> | void;
+    removeItem(key: string): Promise<void> | void;
+    clear(): Promise<void> | void;
+    getKeys?(): Promise<string[]> | string[];
+}
 interface CrazyGamesSDK {
     ad: CrazyGamesAdModule;
     game: CrazyGamesGameModule;
+    user: CrazyGamesUserModule;
+    data: CrazyGamesDataModule;
     getEnvironment(): Promise<CrazyGamesEnvironment>;
 }
 declare global {
@@ -939,6 +1024,7 @@ declare global {
 }
 declare class CrazyGamesService {
     private initialized;
+    private environment;
     /**
      * Detects if the game is running on the CrazyGames platform.
      * Games on CrazyGames run inside an iframe, so we check document.referrer
@@ -982,6 +1068,39 @@ declare class CrazyGamesService {
      * Use sparingly for significant achievements (boss defeat, personal record, etc.)
      */
     happytime(): void;
+    /**
+     * Returns the resolved CrazyGames environment ('crazygames' | 'local' |
+     * 'disabled'), or null if the SDK has not initialized yet. Used to
+     * auto-select the CrazyGames storage adapter.
+     */
+    getEnvironment(): CrazyGamesEnvironment | null;
+    /**
+     * Whether the CrazyGames account system is present (sync). When false,
+     * there is no logged-in user concept and telemetry falls back to guests.
+     */
+    isUserAccountAvailable(): boolean;
+    /**
+     * Fetches the current CrazyGames user, or null if the player is not logged
+     * in (guest). The returned `__dangerousUserId` is client-asserted and used
+     * only as a telemetry attribution label.
+     */
+    getUser(): Promise<CrazyGamesUser | null>;
+    /**
+     * Registers a listener that fires when a guest logs in mid-session.
+     * No-op if the SDK or account system is unavailable.
+     */
+    addAuthListener(callback: CrazyGamesAuthListener): void;
+    /** Removes a previously registered auth listener. */
+    removeAuthListener(callback: CrazyGamesAuthListener): void;
+    /**
+     * Reads a value from the CrazyGames data store. Returns null when the SDK
+     * is unavailable or the key is absent.
+     */
+    dataGetItem(key: string): Promise<string | null>;
+    /** Writes a value to the CrazyGames data store. */
+    dataSetItem(key: string, value: string): Promise<void>;
+    /** Removes a value from the CrazyGames data store. */
+    dataRemoveItem(key: string): Promise<void>;
     private loadScript;
 }
 
@@ -1025,6 +1144,29 @@ declare class LocalStorageAdapter implements StorageAdapter {
     deleteGameData(gameId: string, key: string): Promise<boolean>;
     deleteMultipleGameData(gameId: string, keys: string[]): Promise<number>;
 }
+/**
+ * CrazyGames storage adapter — persists game data via the CrazyGames `SDK.data`
+ * key/value store. CrazyGames syncs this to the player's account when logged in
+ * and falls back to device-local storage for guests.
+ *
+ * Keys are namespaced as `${gameId}:${key}` to avoid collisions across games
+ * that share the CrazyGames data store. Each entry stores a full GameDataItem
+ * (value + timestamps) as a JSON string.
+ *
+ * Atomic operations are implemented client-side as read-modify-write since the
+ * underlying store is a plain key/value store.
+ */
+declare class CrazyGamesStorageAdapter implements StorageAdapter {
+    private service;
+    constructor(service: CrazyGamesService);
+    private getStorageKey;
+    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>;
+    deleteMultipleGameData(gameId: string, keys: string[]): Promise<number>;
+}
 
 /**
  * Logger utility for the Hyve SDK
@@ -1331,4 +1473,4 @@ declare class NativeBridge {
  */
 declare function generateUUID(): string;
 
-export { type AdConfig, type AdMobFormat, type AdRequestPayload, 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, type NativeAdResult, 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 AdMobFormat, type AdRequestPayload, type AdResult, type AdType, AdsService, type BatchSaveGameDataResponse, type BatchSaveResultItem, type BillingConfig, BillingPlatform, type BillingProduct, BillingService, CloudStorageAdapter, CrazyGamesService, CrazyGamesStorageAdapter, 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, type NativeAdResult, 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

@@ -525,6 +525,25 @@ interface HyveClientConfig extends TelemetryConfig {
     billing?: BillingConfig;
     /** Storage mode for persistent game data - 'cloud' (default) or 'local' */
     storageMode?: 'cloud' | 'local';
+    /**
+     * Partner API key for externally-hosted games (e.g. CrazyGames) that cannot
+     * carry a hyve JWT. When set, telemetry is sent to the partner analytics
+     * endpoint with an `x-api-key` header instead of the JWT path. The key is
+     * scoped to the `analytics` domain and bound to a game_id server-side.
+     * NOTE: this key ships in client-side game code and is therefore public.
+     */
+    partnerApiKey?: string;
+    /**
+     * Optional base URL for partner analytics requests. Defaults to apiBaseUrl
+     * when omitted.
+     */
+    partnerApiBaseUrl?: string;
+    /**
+     * Game ID for externally-hosted builds (e.g. CrazyGames) whose URL carries
+     * no `game-id` parameter or hyve JWT. Used for storage key namespacing and
+     * telemetry. A `game-id` URL parameter still takes precedence when present.
+     */
+    gameId?: string;
 }
 /**
  * HyveClient provides telemetry and authentication functionality for Hyve games
@@ -545,6 +564,11 @@ declare class HyveClient {
     private storageMode;
     private cloudStorageAdapter;
     private localStorageAdapter;
+    private crazyGamesStorageAdapter;
+    private partnerApiKey;
+    private partnerApiBaseUrl;
+    /** Raw (unprefixed) CrazyGames __dangerousUserId, seeded at init and on login. */
+    private crazyGamesUserId;
     /**
      * Creates a new HyveClient instance
      * @param config Optional configuration including telemetry and ads
@@ -568,6 +592,28 @@ declare class HyveClient {
      * @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>;
+    /**
+     * Validates and enriches user-provided event details with device info,
+     * attribution data, and session context — matching the enrichment
+     * platform-v2 applies in sendAnalyticsEvent. Shared by the JWT and partner
+     * telemetry paths.
+     * @returns Enriched details object, or null if eventDetails is not valid JSON.
+     */
+    private enrichEventDetails;
+    /**
+     * Sends a telemetry event via the partner analytics endpoint using a partner
+     * API key (x-api-key) instead of a hyve JWT. Used by externally-hosted games
+     * such as CrazyGames. game_id is derived from the API key server-side and is
+     * therefore not sent. hyve_user_id carries the `cg:`-prefixed CrazyGames id,
+     * or a guest sentinel when the player is not logged in.
+     */
+    private sendPartnerTelemetry;
+    /**
+     * Seeds the CrazyGames user id used for telemetry attribution and registers
+     * an auth listener so the id updates if a guest logs in mid-session.
+     * The id is client-asserted (spoofable) and used only as an attribution label.
+     */
+    private seedCrazyGamesUser;
     /**
      * Required lifecycle telemetry — Session start.
      * See https://docs.hyve.gg/docs/telemetry#required-lifecycle-events
@@ -688,7 +734,15 @@ declare class HyveClient {
      */
     reset(): void;
     /**
-     * Get the storage adapter based on mode
+     * Get the storage adapter based on mode.
+     *
+     * Selection order:
+     * 1. An explicit `mode` override ('cloud' | 'local') always wins.
+     * 2. On the CrazyGames platform, the CrazyGames data store is auto-selected
+     *    (D3 — public storageMode type is preserved; this is chosen internally).
+     * 3. Otherwise the configured storageMode is used.
+     *
+     * Awaits CrazyGames SDK initialization so the data store is ready before use.
      * @param mode Storage mode override (cloud or local)
      */
     private getStorageAdapter;
@@ -925,9 +979,40 @@ interface CrazyGamesGameModule {
     gameplayStop(): void;
     happytime(): void;
 }
+/**
+ * CrazyGames user, as returned by `SDK.user.getUser()`.
+ * `__dangerousUserId` is client-asserted (spoofable) — we use it only as a
+ * telemetry attribution label, never for authentication.
+ */
+interface CrazyGamesUser {
+    __dangerousUserId: string;
+    username: string;
+    profilePictureUrl: string;
+}
+type CrazyGamesAuthListener = (user: CrazyGamesUser | null) => void;
+interface CrazyGamesUserModule {
+    isUserAccountAvailable: boolean;
+    getUser(): Promise<CrazyGamesUser | null>;
+    addAuthListener(callback: CrazyGamesAuthListener): void;
+    removeAuthListener(callback: CrazyGamesAuthListener): void;
+}
+/**
+ * CrazyGames key/value data store. Treated as async (promise-based) per the
+ * SDK v2 docs; awaiting a synchronous return is harmless, so the wrappers
+ * `await` every call regardless.
+ */
+interface CrazyGamesDataModule {
+    getItem(key: string): Promise<string | null> | string | null;
+    setItem(key: string, value: string): Promise<void> | void;
+    removeItem(key: string): Promise<void> | void;
+    clear(): Promise<void> | void;
+    getKeys?(): Promise<string[]> | string[];
+}
 interface CrazyGamesSDK {
     ad: CrazyGamesAdModule;
     game: CrazyGamesGameModule;
+    user: CrazyGamesUserModule;
+    data: CrazyGamesDataModule;
     getEnvironment(): Promise<CrazyGamesEnvironment>;
 }
 declare global {
@@ -939,6 +1024,7 @@ declare global {
 }
 declare class CrazyGamesService {
     private initialized;
+    private environment;
     /**
      * Detects if the game is running on the CrazyGames platform.
      * Games on CrazyGames run inside an iframe, so we check document.referrer
@@ -982,6 +1068,39 @@ declare class CrazyGamesService {
      * Use sparingly for significant achievements (boss defeat, personal record, etc.)
      */
     happytime(): void;
+    /**
+     * Returns the resolved CrazyGames environment ('crazygames' | 'local' |
+     * 'disabled'), or null if the SDK has not initialized yet. Used to
+     * auto-select the CrazyGames storage adapter.
+     */
+    getEnvironment(): CrazyGamesEnvironment | null;
+    /**
+     * Whether the CrazyGames account system is present (sync). When false,
+     * there is no logged-in user concept and telemetry falls back to guests.
+     */
+    isUserAccountAvailable(): boolean;
+    /**
+     * Fetches the current CrazyGames user, or null if the player is not logged
+     * in (guest). The returned `__dangerousUserId` is client-asserted and used
+     * only as a telemetry attribution label.
+     */
+    getUser(): Promise<CrazyGamesUser | null>;
+    /**
+     * Registers a listener that fires when a guest logs in mid-session.
+     * No-op if the SDK or account system is unavailable.
+     */
+    addAuthListener(callback: CrazyGamesAuthListener): void;
+    /** Removes a previously registered auth listener. */
+    removeAuthListener(callback: CrazyGamesAuthListener): void;
+    /**
+     * Reads a value from the CrazyGames data store. Returns null when the SDK
+     * is unavailable or the key is absent.
+     */
+    dataGetItem(key: string): Promise<string | null>;
+    /** Writes a value to the CrazyGames data store. */
+    dataSetItem(key: string, value: string): Promise<void>;
+    /** Removes a value from the CrazyGames data store. */
+    dataRemoveItem(key: string): Promise<void>;
     private loadScript;
 }
 
@@ -1025,6 +1144,29 @@ declare class LocalStorageAdapter implements StorageAdapter {
     deleteGameData(gameId: string, key: string): Promise<boolean>;
     deleteMultipleGameData(gameId: string, keys: string[]): Promise<number>;
 }
+/**
+ * CrazyGames storage adapter — persists game data via the CrazyGames `SDK.data`
+ * key/value store. CrazyGames syncs this to the player's account when logged in
+ * and falls back to device-local storage for guests.
+ *
+ * Keys are namespaced as `${gameId}:${key}` to avoid collisions across games
+ * that share the CrazyGames data store. Each entry stores a full GameDataItem
+ * (value + timestamps) as a JSON string.
+ *
+ * Atomic operations are implemented client-side as read-modify-write since the
+ * underlying store is a plain key/value store.
+ */
+declare class CrazyGamesStorageAdapter implements StorageAdapter {
+    private service;
+    constructor(service: CrazyGamesService);
+    private getStorageKey;
+    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>;
+    deleteMultipleGameData(gameId: string, keys: string[]): Promise<number>;
+}
 
 /**
  * Logger utility for the Hyve SDK
@@ -1331,4 +1473,4 @@ declare class NativeBridge {
  */
 declare function generateUUID(): string;
 
-export { type AdConfig, type AdMobFormat, type AdRequestPayload, 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, type NativeAdResult, 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 AdMobFormat, type AdRequestPayload, type AdResult, type AdType, AdsService, type BatchSaveGameDataResponse, type BatchSaveResultItem, type BillingConfig, BillingPlatform, type BillingProduct, BillingService, CloudStorageAdapter, CrazyGamesService, CrazyGamesStorageAdapter, 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, type NativeAdResult, NativeBridge, type NativeMessage, type NativeMessageHandler, NativeMessageType, PlaygamaService, type PurchaseResult, type SaveGameDataResponse, type StorageAdapter, type TelemetryAdditionalData, type TelemetryConfig, type TelemetryEvent, generateUUID, isDomainAllowed, logger, parseUrlParams };