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

package/dist/index.d.ts

@@ -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 };