@hyve-sdk/js 1.1.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
@@ -34,17 +35,18 @@ import { HyveClient } from "@hyve-sdk/js";
 
 // Initialize with optional configuration
 const client = new HyveClient({
-  apiKey: 'your-api-key',      // For telemetry
   isDev: true,                  // Development mode (default: true)
   apiBaseUrl: 'https://...'     // Optional custom API URL
 });
 
 // Authenticate from URL parameters
+// Extracts: hyve-token/signature, hyve-access (JWT), game-id
 const authenticated = await client.authenticateFromUrl();
 if (authenticated) {
   console.log('User ID:', client.getUserId());
   console.log('Session ID:', client.getSessionId());
   console.log('Has JWT:', client.hasJwtToken());
+  console.log('Game ID:', client.getGameId());
 }
 ```
 
@@ -61,10 +63,11 @@ const params = parseUrlParams(window.location.search);
 // {
 //   signature: string,
 //   message: string,
-//   userId: string,
 //   gameStartTab: string,
 //   hyveToken: string,
-//   platform: string
+//   platform: string,
+//   hyveAccess: string,   // JWT token
+//   gameId: string        // Game identifier
 // }
 ```
 
@@ -146,46 +149,62 @@ const id = generateUUID();
 ## Telemetry & Analytics
 
 ### Send Telemetry Events
-Track user actions and game events:
+Track user actions and game events using JWT authentication:
 
 ```typescript
-// Send a custom telemetry event
+// Send a user-level telemetry event
+// Game ID is automatically extracted from 'game-id' URL parameter
 await client.sendTelemetry(
   'game',                          // Event location
   'player',                        // Event category
   'action',                        // Event action
   'combat',                        // Event sub-category (optional)
   'attack',                        // Event sub-action (optional)
-  null,                            // Event details string (optional)
-  {                                // Additional data (optional)
+  {                                // Event details - auto-stringified (optional)
+    button: 'attack-btn',
+    screenPosition: { x: 100, y: 200 }
+  },
+  {                                // Custom data - auto-stringified (optional)
     damage: 100,
     targetId: 'enemy-123',
-    weaponType: 'sword'
-  }
+    weaponType: 'sword',
+    level: 3
+  },
+  'web-chrome'                     // Platform ID (optional)
 );
 ```
 
-**Configuration:**
-- Requires `apiKey` in client configuration
-- Automatically includes `session_id` and `user_id`
-- Additional data is JSON-stringified into `event_details`
-- Supports anonymous telemetry (without authentication)
+**Requirements:**
+- Requires JWT token (from `hyve-access` URL parameter)
+- Requires authenticated user
+- Requires game ID (from `game-id` URL parameter)
+- User ID is automatically extracted from JWT (cannot be spoofed)
+
+**URL Parameters Expected:**
+- `hyve-access` - JWT authentication token
+- `game-id` - Game identifier (associates all telemetry with this game)
+- `hyve-token` or `signature`+`message` - For user authentication
+
+**Features:**
+- Automatically includes `session_id` and `game_id` from client
+- Objects in `event_details` and `custom_data` are auto-stringified to JSON
+- All events tied to authenticated user identity
 
 ## API Integration
 
 ### JWT Authentication
-The SDK supports JWT tokens passed via URL parameter `hyve-access`:
+The SDK supports JWT tokens and game IDs passed via URL parameters:
 
 ```typescript
-// URL: https://game.com?hyve-access=your-jwt-token
+// URL: https://game.com?hyve-access=your-jwt-token&game-id=my-game
 
-// Authenticate extracts JWT automatically
+// Authenticate extracts JWT and game ID automatically
 await client.authenticateFromUrl();
 
-// Check JWT availability
+// Check availability
 if (client.hasJwtToken()) {
-  const token = client.getJwtToken();
-  console.log('JWT token available');
+  console.log('JWT token:', client.getJwtToken());
+  console.log('Game ID:', client.getGameId());
 }
 ```
 
@@ -264,12 +283,108 @@ 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
-- `authenticateFromUrl(urlParams?)` - Authenticate from URL parameters
+- `authenticateFromUrl(urlParams?)` - Authenticate from URL parameters (extracts JWT, game ID, user auth)
 - `getUserId()` - Get authenticated user ID (address)
 - `getSessionId()` - Get unique session ID
+- `getGameId()` - Get game ID from URL parameters
 - `isUserAuthenticated()` - Check if user is authenticated
 - `hasJwtToken()` - Check if JWT token is available
 - `getJwtToken()` - Get JWT token string
@@ -282,7 +397,7 @@ if (item.metadata) {
 - `getInventoryItem(itemId)` - Get specific inventory item
 
 ### Telemetry
-- `sendTelemetry(location, category, action, subCategory?, subAction?, details?, additionalData?)` - Send analytics event
+- `sendTelemetry(location, category, action, subCategory?, subAction?, details?, customData?, platformId?)` - Send JWT-authenticated analytics event (uses game ID from URL)
 - `updateTelemetryConfig(config)` - Update telemetry settings
 
 ### Configuration

package/dist/index.d.mts

@@ -2,33 +2,39 @@
  * Telemetry configuration options
  */
 interface TelemetryConfig {
-    /** API key for telemetry service */
-    apiKey?: string;
     /** Environment: true for dev, false for prod. Defaults to true (dev) */
     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;
 }
 /**
- * Telemetry event data structure
+ * Telemetry event data structure for user-level events (JWT authenticated)
+ * Matches backend SendTelemetryRequest model
+ * Note: hyve_user_id is extracted from JWT by backend, not sent in request
  */
 interface TelemetryEvent {
-    /** Unique session identifier */
+    /** Game identifier (required) */
+    game_id: string;
+    /** Unique session identifier (required) */
     session_id: string;
-    /** Hyve user identifier (address) */
-    hyve_user_id: string;
-    /** Location where the event occurred */
+    /** Platform/user identifier (optional) */
+    platform_id?: string | null;
+    /** Location where the event occurred (required) */
     event_location: string;
-    /** Main category of the event */
+    /** Main category of the event (required) */
     event_category: string;
-    /** Primary action taken */
+    /** Sub-category for more granular classification (optional) */
+    event_sub_category?: string | null;
+    /** Primary action taken (required) */
     event_action: string;
-    /** Sub-category for more granular classification (null if not provided) */
-    event_sub_category: string | null;
-    /** Sub-action for detailed tracking (null if not provided) */
-    event_sub_action: string | null;
-    /** Additional data as JSON string (null if not provided) */
-    event_details: string | null;
+    /** Sub-action for detailed tracking (optional) */
+    event_sub_action?: string | null;
+    /** Event details as JSON string or object (optional) */
+    event_details?: Record<string, any> | string | null;
+    /** Mapping details as JSON string or object (optional) */
+    mapping_details?: Record<string, any> | string | null;
+    /** Custom data as JSON string or object (optional) */
+    custom_data?: Record<string, any> | string | null;
 }
 /**
  * Additional telemetry data that can be passed with events
@@ -67,6 +73,7 @@ declare class HyveClient {
     private sessionId;
     private userId;
     private jwtToken;
+    private gameId;
     /**
      * Creates a new HyveClient instance
      * @param config Optional telemetry configuration
@@ -79,17 +86,19 @@ declare class HyveClient {
      */
     authenticateFromUrl(urlParams?: URLSearchParams | string): Promise<boolean>;
     /**
-     * Sends a telemetry event
+     * 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
-     * @param additionalData Optional additional data
+     * @param eventDetails Optional event details (object or JSON string)
+     * @param customData Optional custom data (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?: string | null, additionalData?: TelemetryAdditionalData | null): Promise<boolean>;
+    sendTelemetry(eventLocation: string, eventCategory: string, eventAction: string, eventSubCategory?: string | null, eventSubAction?: string | null, eventDetails?: Record<string, any> | string | null, customData?: Record<string, any> | 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)
@@ -128,6 +137,11 @@ declare class HyveClient {
      * @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
@@ -153,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
@@ -165,6 +226,7 @@ declare function parseUrlParams(searchParams: URLSearchParams | string): {
     hyveToken: string;
     platform: string;
     hyveAccess: string;
+    gameId: string;
 };
 /**
  * Validates an EVM signature against a message and user ID
@@ -203,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
@@ -215,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 };