@hyve-sdk/js 1.2.2 → 1.3.1-canary.1

package/README.md

@@ -20,6 +20,8 @@ pnpm add @hyve-sdk/js
 - **API Integration**: Authenticated API calls with JWT token support
 - **Inventory Management**: Built-in methods for user inventory operations
 - **Telemetry Tracking**: Session-based analytics and event tracking
+- **Ads Integration**: Google H5 Games Ads support (disabled by default)
+- **Native Bridge**: Type-safe communication with React Native WebView apps
 - **Security Utilities**: Domain validation and referrer checking
 - **URL Parameter Parsing**: Easy extraction of authentication parameters
 - **UUID Generation**: Built-in UUID v4 generation
@@ -278,10 +280,199 @@ if (item.metadata) {
 - `GET /api/v1/inventory` - Get all inventory items
 - `GET /api/v1/inventory/:id` - Get specific item
 
+## Ads Integration
+
+The SDK includes support for Google H5 Games Ads. **Ads are disabled by default** and must be explicitly enabled in the configuration.
+
+### Quick Start
+
+```typescript
+import { HyveClient } from "@hyve-sdk/js";
+
+// Enable ads in initial config
+const client = new HyveClient({
+  isDev: true,
+  ads: {
+    enabled: true,  // Must be set to true
+    sound: 'on',
+    debug: true,
+    onBeforeAd: (type) => {
+      console.log('Pausing game for ad:', type);
+      game.pause();
+    },
+    onAfterAd: (type) => {
+      console.log('Resuming game after ad');
+      game.resume();
+    },
+    onRewardEarned: () => {
+      console.log('User earned reward!');
+      player.coins += 100;
+    }
+  }
+});
+
+// Show different ad types
+const result = await client.showAd('rewarded');
+if (result.success) {
+  console.log('User watched the ad!');
+}
+
+await client.showAd('interstitial');  // Between levels
+await client.showAd('preroll');       // Game start
+```
+
+### Prerequisites
+
+Add the Google H5 Games Ads SDK to your HTML:
+
+```html
+<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>
+```
+
+### Ad Types
+
+| Type | Use Case |
+|------|----------|
+| `rewarded` | User watches full ad for reward (coins, lives, etc.) |
+| `interstitial` | Between levels or game screens |
+| `preroll` | Before game starts |
+
+### Configuration
+
+```typescript
+interface AdConfig {
+  enabled?: boolean;           // Enable/disable ads (default: false)
+  sound?: 'on' | 'off';       // Sound setting (default: 'on')
+  debug?: boolean;             // Enable debug logging (default: false)
+  onBeforeAd?: (type) => void; // Called before ad shows
+  onAfterAd?: (type) => void;  // Called after ad finishes
+  onRewardEarned?: () => void; // Called when user earns reward
+}
+```
+
+### Methods
+
+```typescript
+// Configure ads after initialization
+client.configureAds({ enabled: true, sound: 'off' });
+
+// Show an ad
+const result = await client.showAd('rewarded');
+
+// Check status
+client.areAdsEnabled();  // Boolean
+client.areAdsReady();    // Boolean
+```
+
+See [docs/ads.md](./docs/ads.md) for detailed documentation and examples.
+
 **Requirements:**
 - JWT token must be available (via `hyve-access` URL parameter)
 - User must be authenticated
 
+## Native Bridge (React Native WebView)
+
+Provides type-safe bidirectional communication between your web application and the React Native mobile app.
+
+### Quick Start
+
+```typescript
+import { NativeBridge, NativeMessageType } from "@hyve-sdk/js";
+
+// Initialize on app start
+if (NativeBridge.isNativeContext()) {
+  NativeBridge.initialize();
+}
+```
+
+### Check IAP Availability
+
+Request information about In-App Purchase availability:
+
+```typescript
+// Register response handler
+NativeBridge.on("IAP_AVAILABILITY_RESULT", (payload) => {
+  if (payload.available) {
+    console.log("IAP is available on this device");
+    // Show purchase UI
+  } else {
+    console.log("IAP is not available");
+    // Hide purchase features
+  }
+});
+
+// Send request
+NativeBridge.checkIAPAvailability();
+```
+
+### Request Push Notifications
+
+Request notification permissions from the native app:
+
+```typescript
+// Register response handlers
+NativeBridge.on("PUSH_PERMISSION_GRANTED", (payload) => {
+  console.log("Push notifications enabled");
+  console.log("Token:", payload?.token);
+});
+
+NativeBridge.on("PUSH_PERMISSION_DENIED", () => {
+  console.log("Push notifications disabled");
+});
+
+// Send request
+NativeBridge.requestNotificationPermission();
+```
+
+### Send Custom Messages
+
+Send custom messages to the native app:
+
+```typescript
+// Send message with payload
+NativeBridge.send("CUSTOM_EVENT", {
+  action: "open_settings",
+  data: { setting: "notifications" }
+});
+
+// Listen for custom responses
+NativeBridge.on("CUSTOM_RESPONSE", (payload) => {
+  console.log("Received:", payload);
+});
+```
+
+### Built-in Message Types
+
+**Web → Native:**
+- `CHECK_IAP_AVAILABILITY` - Check if IAP is available
+- `REQUEST_NOTIFICATION_PERMISSION` - Request push notification permission
+
+**Native → Web:**
+- `IAP_AVAILABILITY_RESULT` - Response with IAP availability
+- `PUSH_PERMISSION_GRANTED` - Push permission granted
+- `PUSH_PERMISSION_DENIED` - Push permission denied
+
+### API Reference
+
+- `NativeBridge.isNativeContext()` - Check if running in React Native WebView
+- `NativeBridge.initialize()` - Initialize message listener
+- `NativeBridge.send(type, payload?)` - Send message to native
+- `NativeBridge.on(type, handler)` - Register message handler
+- `NativeBridge.off(type)` - Unregister message handler
+- `NativeBridge.clearHandlers()` - Clear all handlers
+- `NativeBridge.checkIAPAvailability()` - Helper for IAP check
+- `NativeBridge.requestNotificationPermission()` - Helper for notification permission
+
+For complete documentation, see [docs/NATIVE_BRIDGE.md](./docs/NATIVE_BRIDGE.md).
+
 ## Client Methods Reference
 
 ### Authentication

package/dist/index.d.mts

@@ -63,7 +63,121 @@ 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;
+}
+
+/**
+ * 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.
+ *
+ * Prerequisites:
+ * - Google H5 Games Ads SDK script must be loaded in HTML:
+ *   <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 {
+    enabled?: boolean;
+    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;
+    }
+}
+/**
+ * Simple Ads Manager
+ * Ads are disabled by default
+ */
+declare class AdsService {
+    private config;
+    private initialized;
+    private ready;
+    /**
+     * Configure the ads service
+     * Must set enabled: true to activate ads
+     */
+    configure(config: AdConfig): void;
+    /**
+     * Initialize the ads system
+     */
+    private initialize;
+    /**
+     * Show an ad
+     * Returns immediately if ads are disabled
+     */
+    show(type: AdType): Promise<AdResult>;
+    /**
+     * Show an ad break
+     */
+    private showAdBreak;
+    /**
+     * Check if ads are enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Check if ads are ready to show
+     */
+    isReady(): boolean;
+}
 
+/**
+ * HyveClient configuration options
+ */
+interface HyveClientConfig extends TelemetryConfig {
+    /** Ads configuration (disabled by default) */
+    ads?: AdConfig$1;
+}
 /**
  * HyveClient provides telemetry and authentication functionality for Hyve games
  */
@@ -74,11 +188,12 @@ declare class HyveClient {
     private userId;
     private jwtToken;
     private gameId;
+    private adsService;
     /**
      * Creates a new HyveClient instance
-     * @param config Optional telemetry configuration
+     * @param config Optional configuration including telemetry and ads
      */
-    constructor(config?: TelemetryConfig);
+    constructor(config?: HyveClientConfig);
     /**
      * Authenticates a user from URL parameters
      * @param urlParams URL parameters or search string
@@ -165,7 +280,75 @@ declare class HyveClient {
      * Resets the client state
      */
     reset(): void;
+    /**
+     * Configure ads service
+     * @param config Ads configuration
+     */
+    configureAds(config: AdConfig$1): 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>;
+    /**
+     * Check if ads are enabled
+     * @returns Boolean indicating if ads are enabled
+     */
+    areAdsEnabled(): boolean;
+    /**
+     * Check if ads are ready to show
+     * @returns Boolean indicating if ads are ready
+     */
+    areAdsReady(): boolean;
+}
+
+/**
+ * Logger utility for the Hyve SDK
+ * Automatically enabled in development (NODE_ENV !== 'production')
+ */
+type LogLevel = "debug" | "info" | "warn" | "error";
+declare class Logger {
+    private config;
+    constructor();
+    /**
+     * Initialize logger configuration based on NODE_ENV
+     */
+    private initializeConfig;
+    /**
+     * Set which log levels to display
+     */
+    setLevels(levels: LogLevel[]): void;
+    /**
+     * Check if logging is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Internal log method
+     */
+    private log;
+    /**
+     * Log a debug message
+     */
+    debug(...args: unknown[]): void;
+    /**
+     * Log an info message
+     */
+    info(...args: unknown[]): void;
+    /**
+     * Log a warning message
+     */
+    warn(...args: unknown[]): void;
+    /**
+     * Log an error message
+     */
+    error(...args: unknown[]): void;
+    /**
+     * Create a child logger with a specific prefix
+     */
+    child(prefix: string): Logger;
 }
+declare const logger: Logger;
 
 /**
  * Parses URL search parameters and returns commonly used values
@@ -218,11 +401,6 @@ declare function verifyAuthentication(params: {
     method: "modern" | "legacy" | "none";
     error?: string;
 };
-/**
- * Generates a random UUID (v4) using the uuid library
- * @returns A string containing a randomly generated UUID
- */
-declare function generateUUID(): string;
 /**
  * Checks if the current domain is in the list of allowed domains
  * @param allowedDomains Array of allowed domains or a single domain string
@@ -230,4 +408,172 @@ declare function generateUUID(): string;
  */
 declare function isDomainAllowed(allowedDomains?: string | string[], hostname?: string): boolean;
 
-export { HyveClient, type Inventory, type InventoryItem, type TelemetryAdditionalData, type TelemetryConfig, type TelemetryEvent, generateUUID, handleVerifyMessage, isDomainAllowed, parseUrlParams, validateSignature, verifyAuthentication, verifyHyveToken };
+/**
+ * Message structure for WebView to Native communication
+ */
+interface NativeMessage<T = any> {
+    type: string;
+    payload?: T;
+    timestamp?: number;
+}
+/**
+ * Message types for native communication
+ */
+declare enum NativeMessageType {
+    /** Check if In-App Purchases are available on the device */
+    CHECK_IAP_AVAILABILITY = "CHECK_IAP_AVAILABILITY",
+    /** Request notification permission from the native app */
+    REQUEST_NOTIFICATION_PERMISSION = "REQUEST_NOTIFICATION_PERMISSION",
+    /** Request available products for a game */
+    GET_PRODUCTS = "GET_PRODUCTS",
+    /** Initiate a purchase */
+    PURCHASE = "PURCHASE",
+    /** Response to CHECK_IAP_AVAILABILITY request */
+    IAP_AVAILABILITY_RESULT = "IAP_AVAILABILITY_RESULT",
+    /** Push notification permission was granted */
+    PUSH_PERMISSION_GRANTED = "PUSH_PERMISSION_GRANTED",
+    /** Push notification permission was denied */
+    PUSH_PERMISSION_DENIED = "PUSH_PERMISSION_DENIED",
+    /** Response with available products */
+    PRODUCTS_RESULT = "PRODUCTS_RESULT",
+    /** Purchase completed successfully */
+    PURCHASE_COMPLETE = "PURCHASE_COMPLETE",
+    /** Purchase failed or was cancelled */
+    PURCHASE_ERROR = "PURCHASE_ERROR"
+}
+/**
+ * Message handler function type for receiving messages from native
+ */
+type NativeMessageHandler<T = any> = (payload: T) => void | Promise<void>;
+/**
+ * NativeBridge - Provides utilities for WebView to React Native communication
+ *
+ * @example
+ * // Send message to React Native
+ * NativeBridge.send(NativeMessageType.CHECK_IAP_AVAILABILITY);
+ *
+ * // Listen for messages from React Native
+ * NativeBridge.on("PUSH_PERMISSION_GRANTED", (payload) => {
+ *   console.log("Permission granted:", payload);
+ * });
+ *
+ * // Check if running in React Native WebView
+ * if (NativeBridge.isNativeContext()) {
+ *   NativeBridge.checkIAPAvailability();
+ * }
+ */
+declare class NativeBridge {
+    private static handlers;
+    private static isInitialized;
+    /**
+     * Checks if the app is running inside a React Native WebView
+     */
+    static isNativeContext(): boolean;
+    /**
+     * Initializes the native bridge message listener
+     * Call this once when your app starts
+     */
+    static initialize(): void;
+    /**
+     * Handles incoming messages from React Native
+     */
+    private static handleNativeMessage;
+    /**
+     * Sends a message to React Native
+     * @param type Message type
+     * @param payload Optional payload data
+     */
+    static send<T = any>(type: string, payload?: T): void;
+    /**
+     * Registers a handler for messages from React Native
+     * @param type Message type to listen for
+     * @param handler Function to call when message is received
+     */
+    static on<T = any>(type: string, handler: NativeMessageHandler<T>): void;
+    /**
+     * Unregisters a handler for a specific message type
+     * @param type Message type to stop listening for
+     */
+    static off(type: string): void;
+    /**
+     * Clears all registered handlers
+     */
+    static clearHandlers(): void;
+    /**
+     * Checks if In-App Purchases are available on the device
+     * The native app will respond with a message containing availability status
+     *
+     * @example
+     * // Listen for the response
+     * NativeBridge.on("IAP_AVAILABILITY_RESULT", (payload) => {
+     *   console.log("IAP available:", payload.available);
+     * });
+     *
+     * // Send the request
+     * NativeBridge.checkIAPAvailability();
+     */
+    static checkIAPAvailability(): void;
+    /**
+     * Requests notification permission from the native app
+     * The native app will respond with PUSH_PERMISSION_GRANTED or PUSH_PERMISSION_DENIED
+     *
+     * @example
+     * // Listen for the response
+     * NativeBridge.on("PUSH_PERMISSION_GRANTED", () => {
+     *   console.log("Permission granted");
+     * });
+     *
+     * NativeBridge.on("PUSH_PERMISSION_DENIED", () => {
+     *   console.log("Permission denied");
+     * });
+     *
+     * // Send the request
+     * NativeBridge.requestNotificationPermission();
+     */
+    static requestNotificationPermission(): void;
+    /**
+     * Requests available products for a specific game
+     * The native app will respond with PRODUCTS_RESULT containing product details
+     *
+     * @param gameId - The game ID to fetch products for
+     *
+     * @example
+     * // Listen for the response
+     * NativeBridge.on("PRODUCTS_RESULT", (payload) => {
+     *   console.log("Products:", payload.products);
+     * });
+     *
+     * // Send the request
+     * NativeBridge.getProducts(123);
+     */
+    static getProducts(gameId: number): void;
+    /**
+     * Initiates a purchase for a specific product
+     * The native app will respond with PURCHASE_COMPLETE or PURCHASE_ERROR
+     *
+     * @param productId - The product ID to purchase
+     * @param userId - The user ID making the purchase
+     *
+     * @example
+     * // Listen for responses
+     * NativeBridge.on("PURCHASE_COMPLETE", (payload) => {
+     *   console.log("Purchase successful:", payload.productId);
+     * });
+     *
+     * NativeBridge.on("PURCHASE_ERROR", (payload) => {
+     *   console.error("Purchase failed:", payload.error);
+     * });
+     *
+     * // Initiate purchase
+     * NativeBridge.purchase("product_123", "user_456");
+     */
+    static purchase(productId: string, userId: string): void;
+}
+
+/**
+ * Generates a random UUID (v4) using the uuid library
+ * @returns A string containing a randomly generated UUID
+ */
+declare function generateUUID(): string;
+
+export { type AdConfig$1 as AdConfig, type AdResult, type AdType, AdsService, HyveClient, type HyveClientConfig, type Inventory, type InventoryItem, Logger, NativeBridge, type NativeMessage, type NativeMessageHandler, NativeMessageType, type TelemetryAdditionalData, type TelemetryConfig, type TelemetryEvent, generateUUID, handleVerifyMessage, isDomainAllowed, logger, parseUrlParams, validateSignature, verifyAuthentication, verifyHyveToken };