@hyve-sdk/js 1.5.0 → 2.1.0

package/dist/index.d.mts

@@ -65,24 +65,6 @@ interface Inventory {
     items: InventoryItem[];
     total_count: number;
 }
-/**
- * Ads configuration options
- * Ads are disabled by default and must be explicitly enabled
- */
-interface AdConfig$1 {
-    /** Enable/disable ads (default: false) */
-    enabled?: boolean;
-    /** Sound setting for ads (default: 'on') */
-    sound?: 'on' | 'off';
-    /** Enable debug logging (default: false) */
-    debug?: boolean;
-    /** Callback before ad is shown */
-    onBeforeAd?: (type: 'rewarded' | 'interstitial' | 'preroll') => void;
-    /** Callback after ad is shown */
-    onAfterAd?: (type: 'rewarded' | 'interstitial' | 'preroll') => void;
-    /** Callback when user earns a reward (rewarded ads only) */
-    onRewardEarned?: () => void;
-}
 /**
  * Persistent Game Data Types
  */
@@ -124,11 +106,10 @@ interface GameDataBatchItem {
 /**
  * Ads Service for Hyve SDK
  *
- * Simple wrapper around Google H5 Games Ads with configurable enable/disable.
- * Ads are OFF by default and must be explicitly enabled in SDK config.
+ * Wraps Google H5 Games Ads with auto-initialization and Playgama fallback.
+ * Ads are ON by default — just call showAd() and it works.
  *
- * Prerequisites:
- * - Google H5 Games Ads SDK script must be loaded in HTML:
+ * 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); };
@@ -146,7 +127,6 @@ interface AdResult {
     completedAt: number;
 }
 interface AdConfig {
-    enabled?: boolean;
     sound?: 'on' | 'off';
     debug?: boolean;
     onBeforeAd?: (type: AdType) => void;
@@ -175,37 +155,42 @@ declare global {
     }
 }
 /**
- * Simple Ads Manager
- * Ads are disabled by default
+ * Ads Manager — enabled by default, auto-initializes on first show() call.
  */
 declare class AdsService {
     private config;
-    private initialized;
+    private initPromise;
     private ready;
     /**
-     * Configure the ads service
-     * Must set enabled: true to activate ads
+     * Optionally configure the ads service.
+     * Not required — ads work without calling this.
      */
     configure(config: AdConfig): void;
     /**
-     * Initialize the ads system
+     * Initialize the Google H5 Ads system.
+     * Returns a cached promise — safe to call multiple times.
      */
     private initialize;
     /**
-     * Show an ad
-     * Returns immediately if ads are disabled
+     * Show an ad. Auto-initializes on the first call.
+     * Returns immediately with success: false if ads are disabled or unavailable.
      */
     show(type: AdType): Promise<AdResult>;
     /**
-     * Show an ad break
+     * Show an ad break via the Google H5 API.
      */
     private showAdBreak;
     /**
-     * Check if ads are enabled
+     * Returns the configured ad lifecycle callbacks.
+     * Used by platform-specific providers (e.g. Playgama) to fire the same hooks.
      */
-    isEnabled(): boolean;
+    getCallbacks(): {
+        onBeforeAd: (type: AdType) => void;
+        onAfterAd: (type: AdType) => void;
+        onRewardEarned: () => void;
+    };
     /**
-     * Check if ads are ready to show
+     * Check if ads have successfully initialized and are ready to show.
      */
     isReady(): boolean;
 }
@@ -270,11 +255,12 @@ declare enum BillingPlatform {
  * - Web: Stripe Embedded Checkout (Stripe Elements)
  * - Native: In-App Purchases via NativeBridge
  *
+ * Auto-initializes on first getProducts() or purchase() call — no manual initialize() needed.
+ *
  * @example
  * ```typescript
  * import { BillingService } from '@hyve-sdk/js';
  *
- * // Initialize billing
  * const billing = new BillingService({
  *   stripePublishableKey: 'pk_test_...',
  *   checkoutUrl: 'https://your-api.com',
@@ -282,24 +268,10 @@ declare enum BillingPlatform {
  *   userId: 'user_456'
  * });
  *
- * await billing.initialize();
- *
  * // Check which platform we're on
  * const platform = billing.getPlatform();
- * console.log('Running on:', platform);
- *
- * // Get available products
- * const products = await billing.getProducts();
- *
- * // For web: Ensure you have a container element in your HTML
- * // <div id="stripe-checkout-element"></div>
  *
- * // Purchase a product (web will mount Stripe checkout form)
- * const result = await billing.purchase('price_1234', {
- *   elementId: 'stripe-checkout-element' // optional, defaults to 'stripe-checkout-element'
- * });
- *
- * // Set up callbacks for purchase events
+ * // Set up callbacks
  * billing.onPurchaseComplete((result) => {
  *   console.log('Purchase successful!', result);
  * });
@@ -308,6 +280,10 @@ declare enum BillingPlatform {
  *   console.error('Purchase failed:', result.error);
  * });
  *
+ * // Auto-inits on first call:
+ * const products = await billing.getProducts();
+ * const result = await billing.purchase('price_1234');
+ *
  * // Clean up when done
  * billing.dispose();
  * ```
@@ -315,24 +291,17 @@ declare enum BillingPlatform {
 declare class BillingService {
     private config;
     private platform;
-    private isInitialized;
+    private initPromise;
     private nativeAvailable;
-    private products;
     private stripe;
     private checkoutElement;
     private onPurchaseCompleteCallback?;
     private onPurchaseErrorCallback?;
-    private onLogCallback?;
     constructor(config: BillingConfig);
     /**
-     * Register a callback to receive all internal logs
-     * Useful for displaying logs in a UI
-     */
-    onLog(callback: (level: "info" | "warn" | "error", message: string, data?: any) => void): void;
-    /**
-     * Internal logging method that calls both logger and custom callback
+     * Update billing configuration. Resets initialization so next call re-inits with new config.
      */
-    private log;
+    configure(config: Partial<BillingConfig>): void;
     /**
      * Detects if running on web or native platform
      */
@@ -342,10 +311,10 @@ declare class BillingService {
      */
     getPlatform(): BillingPlatform;
     /**
-     * Initialize the billing service
-     * Must be called before using any other methods
+     * Initialize the billing service. Idempotent — returns cached promise on subsequent calls.
+     * Called automatically by getProducts() and purchase().
      */
-    initialize(): Promise<boolean>;
+    private initialize;
     /**
      * Initialize native billing
      */
@@ -359,11 +328,11 @@ declare class BillingService {
      */
     private loadStripeScript;
     /**
-     * Check if billing is available
+     * Check if billing is available based on current config and platform state
      */
     isAvailable(): boolean;
     /**
-     * Get available products
+     * Get available products. Auto-initializes on first call.
      */
     getProducts(): Promise<BillingProduct[]>;
     /**
@@ -375,7 +344,7 @@ declare class BillingService {
      */
     private getProductsWeb;
     /**
-     * Purchase a product
+     * Purchase a product. Auto-initializes on first call.
      * @param productId - The product ID (priceId for web/Stripe, productId for native)
      * @param options - Optional purchase options
      * @param options.elementId - For web: DOM element ID to mount Stripe checkout (default: 'stripe-checkout-element')
@@ -425,8 +394,8 @@ declare class BillingService {
  * HyveClient configuration options
  */
 interface HyveClientConfig extends TelemetryConfig {
-    /** Ads configuration (disabled by default) */
-    ads?: AdConfig$1;
+    /** 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' */
@@ -444,9 +413,10 @@ declare class HyveClient {
     private gameId;
     private adsService;
     private playgamaService;
+    private playgamaInitPromise;
+    private crazyGamesService;
+    private crazyGamesInitPromise;
     private billingService;
-    private billingConfig;
-    private billingCallbacks;
     private storageMode;
     private cloudStorageAdapter;
     private localStorageAdapter;
@@ -456,11 +426,10 @@ declare class HyveClient {
      */
     constructor(config?: HyveClientConfig);
     /**
-     * Authenticates a user from URL parameters
-     * @param urlParams URL parameters or search string
-     * @returns Promise resolving to boolean indicating success
+     * Parses JWT and game ID from the current window URL and stores them on the client.
+     * Called automatically during construction.
      */
-    authenticateFromUrl(urlParams?: URLSearchParams | string): Promise<boolean>;
+    private _parseUrlAuth;
     /**
      * Sends a user-level telemetry event using JWT authentication
      * Requires JWT token, authenticated user, and game ID from URL parameters
@@ -545,6 +514,10 @@ declare class HyveClient {
      * @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
@@ -602,7 +575,7 @@ declare class HyveClient {
      * Configure ads service
      * @param config Ads configuration
      */
-    configureAds(config: AdConfig$1): void;
+    configureAds(config: AdConfig): void;
     /**
      * Show an ad
      * @param type Type of ad to show ('rewarded', 'interstitial', or 'preroll')
@@ -610,26 +583,25 @@ declare class HyveClient {
      */
     showAd(type: AdType): Promise<AdResult>;
     /**
-     * Check if ads are enabled
-     * @returns Boolean indicating if ads are enabled
+     * Notifies CrazyGames that gameplay has started.
+     * No-op on other platforms.
      */
-    areAdsEnabled(): boolean;
+    gameplayStart(): Promise<void>;
     /**
-     * Check if ads are ready to show
-     * @returns Boolean indicating if ads are ready
+     * Notifies CrazyGames that gameplay has stopped.
+     * No-op on other platforms.
      */
-    areAdsReady(): boolean;
+    gameplayStop(): Promise<void>;
     /**
-     * Configure billing service
-     * @param config Billing configuration
+     * Triggers a celebration effect on the CrazyGames website for significant achievements.
+     * No-op on other platforms.
      */
-    configureBilling(config: BillingConfig): void;
+    happytime(): Promise<void>;
     /**
-     * Initialize billing service
-     * Must be called before using billing features
-     * @returns Promise resolving to boolean indicating success
+     * Check if ads are ready to show
+     * @returns Boolean indicating if ads have initialized successfully
      */
-    initializeBilling(): Promise<boolean>;
+    areAdsReady(): boolean;
     /**
      * Get the billing platform
      * @returns Current billing platform
@@ -668,11 +640,6 @@ declare class HyveClient {
      * Unmount Stripe checkout element
      */
     unmountBillingCheckout(): void;
-    /**
-     * Register a callback to receive billing logs
-     * @param callback Function to call with log messages
-     */
-    onBillingLog(callback: (level: "info" | "warn" | "error", message: string, data?: any) => void): void;
 }
 
 /**
@@ -688,6 +655,8 @@ declare class HyveClient {
  */
 
 interface PlaygamaBridgeAdvertisement {
+    isInterstitialSupported: boolean;
+    isRewardedSupported: boolean;
     interstitialState: string;
     rewardedState: string;
     showInterstitial(placement?: string): void;
@@ -698,6 +667,11 @@ interface PlaygamaBridgeAdvertisement {
 interface PlaygamaBridge {
     initialize(): Promise<void>;
     advertisement: PlaygamaBridgeAdvertisement;
+    EVENT_NAME: {
+        INTERSTITIAL_STATE_CHANGED: string;
+        REWARDED_STATE_CHANGED: string;
+        [key: string]: string;
+    };
 }
 declare global {
     interface Window {
@@ -718,8 +692,101 @@ declare class PlaygamaService {
      */
     initialize(): Promise<boolean>;
     isInitialized(): boolean;
-    showInterstitial(): Promise<AdResult>;
-    showRewarded(): Promise<AdResult>;
+    showInterstitial(callbacks?: {
+        onBeforeAd?: () => void;
+        onAfterAd?: () => void;
+    }): Promise<AdResult>;
+    showRewarded(callbacks?: {
+        onBeforeAd?: () => void;
+        onAfterAd?: () => void;
+        onRewardEarned?: () => void;
+    }): Promise<AdResult>;
+    private loadScript;
+}
+
+/**
+ * CrazyGames SDK integration service
+ *
+ * Loads and initializes the CrazyGames SDK v2 when running on the CrazyGames platform.
+ * The SDK is loaded from CDN and exposes a global `window.CrazyGames.SDK` object.
+ *
+ * Detection: CrazyGames games run in an iframe on crazygames.com, so detection
+ * uses document.referrer and parent frame location checks.
+ *
+ * @packageDocumentation
+ */
+
+type CrazyGamesEnvironment = 'local' | 'crazygames' | 'disabled';
+interface CrazyGamesAdCallbacks {
+    adStarted?: () => void;
+    adFinished?: () => void;
+    adError?: (error: string, errorData?: unknown) => void;
+}
+interface CrazyGamesAdModule {
+    requestAd(type: 'midgame' | 'rewarded', callbacks: CrazyGamesAdCallbacks): void;
+}
+interface CrazyGamesGameModule {
+    gameplayStart(): void;
+    gameplayStop(): void;
+    happytime(): void;
+}
+interface CrazyGamesSDK {
+    ad: CrazyGamesAdModule;
+    game: CrazyGamesGameModule;
+    getEnvironment(): Promise<CrazyGamesEnvironment>;
+}
+declare global {
+    interface Window {
+        CrazyGames?: {
+            SDK: CrazyGamesSDK;
+        };
+    }
+}
+declare class CrazyGamesService {
+    private initialized;
+    /**
+     * Detects if the game is running on the CrazyGames platform.
+     * Games on CrazyGames run inside an iframe, so we check document.referrer
+     * and attempt to read the parent frame location.
+     */
+    static isCrazyGamesDomain(): boolean;
+    /**
+     * Loads the CrazyGames SDK from CDN and confirms the environment is 'crazygames'.
+     * Safe to call multiple times — resolves immediately if already initialized.
+     */
+    initialize(): Promise<boolean>;
+    isInitialized(): boolean;
+    /**
+     * Shows a midgame (interstitial) ad via the CrazyGames SDK.
+     */
+    showInterstitial(callbacks?: {
+        onBeforeAd?: () => void;
+        onAfterAd?: () => void;
+    }): Promise<AdResult>;
+    /**
+     * Shows a rewarded ad via the CrazyGames SDK.
+     * Resolves with success: true only when adFinished fires (ad was fully watched).
+     */
+    showRewarded(callbacks?: {
+        onBeforeAd?: () => void;
+        onAfterAd?: () => void;
+        onRewardEarned?: () => void;
+    }): Promise<AdResult>;
+    /**
+     * Notifies CrazyGames that gameplay has started.
+     * Call when the player actively begins or resumes playing.
+     */
+    gameplayStart(): void;
+    /**
+     * Notifies CrazyGames that gameplay has stopped.
+     * Call during menu access, level completion, or pausing.
+     */
+    gameplayStop(): void;
+    /**
+     * Triggers a celebration effect on the CrazyGames website.
+     * Use sparingly for significant achievements (boss defeat, personal record, etc.)
+     */
+    happytime(): void;
     private loadScript;
 }
 
@@ -817,51 +884,11 @@ declare const logger: Logger;
  * @returns Object containing parsed parameters with default values
  */
 declare function parseUrlParams(searchParams: URLSearchParams | string): {
-    signature: string;
-    message: string;
     gameStartTab: string;
-    hyveToken: string;
     platform: string;
     hyveAccess: string;
     gameId: string;
 };
-/**
- * Validates an EVM signature against a message and user ID
- * @param signature The signature to validate
- * @param message The original message that was signed
- * @returns Promise resolving to boolean indicating if signature is valid
- */
-declare function validateSignature(signature: string, message: string): boolean;
-/**
- * Verifies a signed message containing metadata with expiration and address (LEGACY)
- * @param signature The signature to verify
- * @param message The encoded message containing metadata (JSON)
- * @returns The address that signed the message if valid, false otherwise
- */
-declare function handleVerifyMessage(signature: string, message: string): string | false;
-/**
- * Verifies a modern hyve-token
- * @param hyveToken The modern token in format: signature.address.randomBase64.timestamp
- * @param maxAgeSec Maximum age in seconds (default: 600 = 10 minutes)
- * @returns The verified address if valid, false otherwise
- */
-declare function verifyHyveToken(hyveToken: string, maxAgeSec?: number): string | false;
-/**
- * Unified authentication verification - tries modern token first, then falls back to legacy
- * @param params Object containing hyveToken, signature, message from URL params
- * @param maxAgeSec Maximum age for modern tokens in seconds (default: 600)
- * @returns Object with verification result and method used
- */
-declare function verifyAuthentication(params: {
-    hyveToken?: string;
-    signature?: string;
-    message?: string;
-}, maxAgeSec?: number): {
-    isValid: boolean;
-    address: string | null;
-    method: "modern" | "legacy" | "none";
-    error?: string;
-};
 /**
  * Checks if the current domain is in the list of allowed domains
  * @param allowedDomains Array of allowed domains or a single domain string
@@ -1037,4 +1064,4 @@ declare class NativeBridge {
  */
 declare function generateUUID(): string;
 
-export { type AdConfig$1 as AdConfig, type AdResult, type AdType, AdsService, type BillingConfig, BillingPlatform, type BillingProduct, BillingService, CloudStorageAdapter, type DeleteGameDataResponse, type GameDataBatchItem, type GameDataItem, 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, handleVerifyMessage, isDomainAllowed, logger, parseUrlParams, validateSignature, verifyAuthentication, verifyHyveToken };
+export { type AdConfig, type AdResult, type AdType, AdsService, type BillingConfig, BillingPlatform, type BillingProduct, BillingService, CloudStorageAdapter, CrazyGamesService, type DeleteGameDataResponse, type GameDataBatchItem, type GameDataItem, 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 };