@hyve-sdk/js 1.5.1 → 2.1.0

package/dist/react.d.mts

@@ -0,0 +1,453 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * Telemetry configuration options
+ */
+interface TelemetryConfig {
+    /**
+     * Environment: true for dev, false for prod.
+     * AUTO-DETECTED from parent page URL by default - only set for local testing.
+     * Use this ONLY for testing, NOT in production code.
+     */
+    isDev?: boolean;
+    /** Base API URL for all API calls (telemetry and external). Can be set via env. If not provided, defaults based on isDev */
+    apiBaseUrl?: string;
+}
+/**
+ * User inventory item
+ */
+interface InventoryItem {
+    id: string;
+    user_id: string;
+    item_type: string;
+    item_id: string;
+    quantity: number;
+    metadata?: Record<string, any>;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * User inventory response
+ */
+interface Inventory {
+    items: InventoryItem[];
+    total_count: number;
+}
+/**
+ * Persistent Game Data Types
+ */
+/** Generic value type for game data storage - can be any JSON-serializable value */
+type GameDataValue = string | number | boolean | null | GameDataValue[] | {
+    [key: string]: GameDataValue;
+};
+/** Single game data item with metadata */
+interface GameDataItem {
+    key: string;
+    value: GameDataValue;
+    created_at: string;
+    updated_at: string;
+}
+/** Response from save operations */
+interface SaveGameDataResponse {
+    success: boolean;
+    message: string;
+}
+/** Batch item for saving multiple entries */
+interface GameDataBatchItem {
+    key: string;
+    value: GameDataValue;
+}
+
+/**
+ * Ads Service for Hyve SDK
+ *
+ * Wraps Google H5 Games Ads with auto-initialization and Playgama fallback.
+ * Ads are ON by default — just call showAd() and it works.
+ *
+ * Optional setup in HTML for Google H5 Games Ads:
+ *   <script async src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"></script>
+ *   <script>
+ *     window.adBreak = window.adBreak || function(o) { (window.adsbygoogle = window.adsbygoogle || []).push(o); };
+ *     window.adConfig = window.adConfig || function(o) { (window.adsbygoogle = window.adsbygoogle || []).push(o); };
+ *   </script>
+ *
+ * @packageDocumentation
+ */
+type AdType = 'rewarded' | 'interstitial' | 'preroll';
+interface AdResult {
+    success: boolean;
+    type: AdType;
+    error?: Error;
+    requestedAt: number;
+    completedAt: number;
+}
+interface AdConfig {
+    sound?: 'on' | 'off';
+    debug?: boolean;
+    onBeforeAd?: (type: AdType) => void;
+    onAfterAd?: (type: AdType) => void;
+    onRewardEarned?: () => void;
+}
+interface GoogleAdBreakConfig {
+    type: 'reward' | 'next' | 'start';
+    name: string;
+    beforeAd?: () => void;
+    afterAd?: () => void;
+    beforeReward?: (showAdFn: () => void) => void;
+    adViewed?: () => void;
+    adDismissed?: () => void;
+    adBreakDone?: (info?: any) => void;
+}
+interface GoogleAdConfigOptions {
+    sound?: 'on' | 'off';
+    preloadAdBreaks?: 'on' | 'off';
+    onReady?: () => void;
+}
+declare global {
+    interface Window {
+        adBreak?: (config: GoogleAdBreakConfig) => void;
+        adConfig?: (config: GoogleAdConfigOptions) => void;
+    }
+}
+
+/**
+ * Product information from the native app or server
+ */
+interface BillingProduct {
+    productId: string;
+    title: string;
+    description: string;
+    price: number;
+    localizedPrice: string;
+    currency: string;
+}
+/**
+ * Purchase result
+ */
+interface PurchaseResult {
+    success: boolean;
+    productId: string;
+    transactionId?: string;
+    transactionDate?: string;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+/**
+ * Billing configuration
+ */
+interface BillingConfig {
+    /**
+     * Stripe publishable key (required for web)
+     */
+    stripePublishableKey?: string;
+    /**
+     * Game ID for native purchases
+     */
+    gameId?: number;
+    /**
+     * User ID for purchases
+     */
+    userId?: string;
+    /**
+     * Checkout URL for API calls
+     */
+    checkoutUrl?: string;
+}
+/**
+ * Platform types
+ */
+declare enum BillingPlatform {
+    WEB = "web",
+    NATIVE = "native",
+    UNKNOWN = "unknown"
+}
+
+/**
+ * HyveClient configuration options
+ */
+interface HyveClientConfig extends TelemetryConfig {
+    /** Optional ads configuration (sound, debug, lifecycle callbacks) */
+    ads?: AdConfig;
+    /** Billing configuration (disabled by default) */
+    billing?: BillingConfig;
+    /** Storage mode for persistent game data - 'cloud' (default) or 'local' */
+    storageMode?: 'cloud' | 'local';
+}
+/**
+ * HyveClient provides telemetry and authentication functionality for Hyve games
+ */
+declare class HyveClient {
+    private telemetryConfig;
+    private apiBaseUrl;
+    private sessionId;
+    private userId;
+    private jwtToken;
+    private gameId;
+    private adsService;
+    private playgamaService;
+    private playgamaInitPromise;
+    private crazyGamesService;
+    private crazyGamesInitPromise;
+    private billingService;
+    private storageMode;
+    private cloudStorageAdapter;
+    private localStorageAdapter;
+    /**
+     * Creates a new HyveClient instance
+     * @param config Optional configuration including telemetry and ads
+     */
+    constructor(config?: HyveClientConfig);
+    /**
+     * Parses JWT and game ID from the current window URL and stores them on the client.
+     * Called automatically during construction.
+     */
+    private _parseUrlAuth;
+    /**
+     * Sends a user-level telemetry event using JWT authentication
+     * Requires JWT token, authenticated user, and game ID from URL parameters
+     * @param eventLocation Location where the event occurred
+     * @param eventCategory Main category of the event
+     * @param eventAction Primary action taken
+     * @param eventSubCategory Optional sub-category
+     * @param eventSubAction Optional sub-action
+     * @param eventDetails Optional event details (object or JSON string)
+     * @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>;
+    /**
+     * Makes an authenticated API call using the JWT token
+     * @param endpoint API endpoint path (will be appended to base URL)
+     * @param options Fetch options (method, body, etc.)
+     * @returns Promise resolving to the API response
+     */
+    callApi<T = any>(endpoint: string, options?: RequestInit): Promise<T>;
+    /**
+     * Gets the user's inventory
+     * @returns Promise resolving to the user's inventory
+     */
+    getInventory(): Promise<Inventory>;
+    /**
+     * Gets a specific inventory item by ID
+     * @param itemId The inventory item ID
+     * @returns Promise resolving to the inventory item details
+     */
+    getInventoryItem(itemId: string): Promise<InventoryItem>;
+    /**
+     * Updates the telemetry configuration
+     * @param config New telemetry configuration
+     */
+    updateTelemetryConfig(config: TelemetryConfig): void;
+    /**
+     * Gets the current user ID
+     * @returns Current user ID or null if not authenticated
+     */
+    getUserId(): string | null;
+    /**
+     * Gets the current session ID
+     * @returns Current session ID
+     */
+    getSessionId(): string;
+    /**
+     * Gets the current JWT token
+     * @returns Current JWT token or null if not available
+     */
+    getJwtToken(): string | null;
+    /**
+     * Gets the current game ID
+     * @returns Current game ID or null if not available
+     */
+    getGameId(): string | null;
+    /**
+     * Gets the API base URL
+     * @returns API base URL
+     */
+    getApiBaseUrl(): string;
+    /**
+     * Checks if user is authenticated
+     * @returns Boolean indicating authentication status
+     */
+    isUserAuthenticated(): boolean;
+    /**
+     * Checks if JWT token is available
+     * @returns Boolean indicating if JWT token is present
+     */
+    hasJwtToken(): boolean;
+    /**
+     * Logs out the current user
+     */
+    logout(): void;
+    /**
+     * Resets the client state
+     */
+    reset(): void;
+    /**
+     * Get the storage adapter based on mode
+     * @param mode Storage mode override (cloud or local)
+     */
+    private getStorageAdapter;
+    /**
+     * Returns the current game ID or throws if not available.
+     */
+    private requireGameId;
+    /**
+     * Save persistent game data
+     * @param key Data key
+     * @param value Data value (any JSON-serializable value)
+     * @param storage Storage mode override ('cloud' or 'local')
+     * @returns Promise resolving to save response
+     */
+    saveGameData(key: string, value: GameDataValue, storage?: 'cloud' | 'local'): Promise<SaveGameDataResponse>;
+    /**
+     * Batch save persistent game data
+     * @param items Array of key-value pairs to save
+     * @param storage Storage mode override ('cloud' or 'local')
+     * @returns Promise resolving to save response
+     */
+    batchSaveGameData(items: GameDataBatchItem[], storage?: 'cloud' | 'local'): Promise<SaveGameDataResponse>;
+    /**
+     * Get persistent game data
+     * @param key Data key
+     * @param storage Storage mode override ('cloud' or 'local')
+     * @returns Promise resolving to game data item or null if not found
+     */
+    getGameData(key: string, storage?: 'cloud' | 'local'): Promise<GameDataItem | null>;
+    /**
+     * Get multiple persistent game data entries
+     * @param keys Array of data keys
+     * @param storage Storage mode override ('cloud' or 'local')
+     * @returns Promise resolving to array of game data items
+     */
+    getMultipleGameData(keys: string[], storage?: 'cloud' | 'local'): Promise<GameDataItem[]>;
+    /**
+     * Delete persistent game data
+     * @param key Data key
+     * @param storage Storage mode override ('cloud' or 'local')
+     * @returns Promise resolving to boolean indicating if data was deleted
+     */
+    deleteGameData(key: string, storage?: 'cloud' | 'local'): Promise<boolean>;
+    /**
+     * Delete multiple persistent game data entries
+     * @param keys Array of data keys
+     * @param storage Storage mode override ('cloud' or 'local')
+     * @returns Promise resolving to number of entries deleted
+     */
+    deleteMultipleGameData(keys: string[], storage?: 'cloud' | 'local'): Promise<number>;
+    /**
+     * Configure storage mode
+     * @param mode Storage mode ('cloud' or 'local')
+     */
+    configureStorage(mode: 'cloud' | 'local'): void;
+    /**
+     * Get current storage mode
+     * @returns Current storage mode
+     */
+    getStorageMode(): 'cloud' | 'local';
+    /**
+     * Configure ads service
+     * @param config Ads configuration
+     */
+    configureAds(config: AdConfig): void;
+    /**
+     * Show an ad
+     * @param type Type of ad to show ('rewarded', 'interstitial', or 'preroll')
+     * @returns Promise resolving to ad result
+     */
+    showAd(type: AdType): Promise<AdResult>;
+    /**
+     * Notifies CrazyGames that gameplay has started.
+     * No-op on other platforms.
+     */
+    gameplayStart(): Promise<void>;
+    /**
+     * Notifies CrazyGames that gameplay has stopped.
+     * No-op on other platforms.
+     */
+    gameplayStop(): Promise<void>;
+    /**
+     * Triggers a celebration effect on the CrazyGames website for significant achievements.
+     * No-op on other platforms.
+     */
+    happytime(): Promise<void>;
+    /**
+     * Check if ads are ready to show
+     * @returns Boolean indicating if ads have initialized successfully
+     */
+    areAdsReady(): boolean;
+    /**
+     * Get the billing platform
+     * @returns Current billing platform
+     */
+    getBillingPlatform(): BillingPlatform;
+    /**
+     * Check if billing is available
+     * @returns Boolean indicating if billing is available
+     */
+    isBillingAvailable(): boolean;
+    /**
+     * Get available billing products
+     * @returns Promise resolving to array of products
+     */
+    getBillingProducts(): Promise<BillingProduct[]>;
+    /**
+     * Purchase a product
+     * @param productId Product ID to purchase
+     * @param options Optional purchase options (e.g., elementId for web)
+     * @returns Promise resolving to purchase result
+     */
+    purchaseProduct(productId: string, options?: {
+        elementId?: string;
+    }): Promise<PurchaseResult>;
+    /**
+     * Set callback for successful purchases
+     * @param callback Function to call on purchase completion
+     */
+    onPurchaseComplete(callback: (result: PurchaseResult) => void): void;
+    /**
+     * Set callback for failed purchases
+     * @param callback Function to call on purchase error
+     */
+    onPurchaseError(callback: (result: PurchaseResult) => void): void;
+    /**
+     * Unmount Stripe checkout element
+     */
+    unmountBillingCheckout(): void;
+}
+
+interface HyveSdkProviderProps {
+    /** Pre-created HyveClient instance, or omit to have the provider create one from config */
+    client?: HyveClient;
+    /** Config to create a HyveClient instance — ignored when client prop is provided */
+    config?: HyveClientConfig;
+    children: ReactNode;
+}
+/**
+ * Provides a HyveClient instance to all descendant components.
+ *
+ * @example
+ * // Option A: pass a pre-created client
+ * const client = new HyveClient({ isDev: true });
+ * <HyveSdkProvider client={client}><App /></HyveSdkProvider>
+ *
+ * @example
+ * // Option B: let the provider create the client from config
+ * <HyveSdkProvider config={{ isDev: true }}><App /></HyveSdkProvider>
+ */
+declare function HyveSdkProvider({ client, config, children, }: HyveSdkProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Returns the HyveClient instance from the nearest HyveSdkProvider.
+ * Throws if used outside of a provider.
+ *
+ * @example
+ * function MyComponent() {
+ *   const sdk = useHyveSdk();
+ *   const handleClick = () => sdk.sendTelemetry("game", "ui", "button_click");
+ *   return <button onClick={handleClick}>Play</button>;
+ * }
+ */
+declare function useHyveSdk(): HyveClient;
+
+export { HyveSdkProvider, useHyveSdk };