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

package/README.md

@@ -20,6 +20,7 @@ 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
+- **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
@@ -282,6 +283,101 @@ if (item.metadata) {
 - 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

@@ -167,6 +167,53 @@ declare class HyveClient {
     reset(): void;
 }
 
+/**
+ * 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
  * @param searchParams URLSearchParams object or string
@@ -218,11 +265,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 +272,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 { HyveClient, 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 };

package/dist/index.d.ts

@@ -167,6 +167,53 @@ declare class HyveClient {
     reset(): void;
 }
 
+/**
+ * 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
  * @param searchParams URLSearchParams object or string
@@ -218,11 +265,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 +272,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 { HyveClient, 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 };