@hyve-sdk/js 1.1.2 → 1.2.2

package/README.md

@@ -34,17 +34,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 +62,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 +148,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());
 }
 ```
 
@@ -267,9 +285,10 @@ if (item.metadata) {
 ## 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 +301,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
@@ -165,6 +179,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

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
@@ -165,6 +179,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

package/dist/index.js

@@ -42,7 +42,8 @@ function parseUrlParams(searchParams) {
     gameStartTab: params.get("game_start_tab") || "",
     hyveToken: params.get("hyve-token") || "",
     platform: params.get("platform") || "",
-    hyveAccess: params.get("hyve-access") || ""
+    hyveAccess: params.get("hyve-access") || "",
+    gameId: params.get("game-id") || ""
   };
 }
 function validateSignature(signature, message) {
@@ -191,6 +192,7 @@ var HyveClient = class {
   sessionId;
   userId = null;
   jwtToken = null;
+  gameId = null;
   /**
    * Creates a new HyveClient instance
    * @param config Optional telemetry configuration
@@ -223,6 +225,14 @@ var HyveClient = class {
         this.jwtToken = params.hyveAccess;
         console.log("[Hyve SDK] JWT token extracted from hyve-access parameter");
       }
+      if (params.gameId) {
+        this.gameId = params.gameId;
+        console.log("[Hyve SDK] Game ID extracted from game-id parameter:", this.gameId);
+      }
+      if (this.jwtToken) {
+        console.log("[Hyve SDK] Authentication successful via JWT");
+        return true;
+      }
       const authResult = verifyAuthentication({
         hyveToken: params.hyveToken,
         signature: params.signature,
@@ -245,48 +255,51 @@ var HyveClient = class {
     }
   }
   /**
-   * 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
    */
-  async sendTelemetry(eventLocation, eventCategory, eventAction, eventSubCategory, eventSubAction, eventDetails, additionalData) {
-    if (!this.telemetryConfig.apiKey) {
-      console.error("[Hyve Telemetry] API key not configured");
+  async sendTelemetry(eventLocation, eventCategory, eventAction, eventSubCategory, eventSubAction, eventDetails, customData, platformId) {
+    if (!this.jwtToken) {
+      console.error("[Hyve Telemetry] JWT token required. Call authenticateFromUrl first.");
       return false;
     }
-    if (!this.userId) {
-      console.warn("[Hyve Telemetry] No user ID - sending anonymous telemetry");
+    if (!this.gameId) {
+      console.error("[Hyve Telemetry] Game ID required. Ensure game-id URL parameter is set.");
+      return false;
     }
     try {
-      let finalEventDetails = null;
-      if (additionalData && Object.keys(additionalData).length > 0) {
-        finalEventDetails = JSON.stringify(additionalData);
-      } else if (eventDetails) {
-        finalEventDetails = eventDetails;
-      }
+      const toJsonString = (data) => {
+        if (!data) return null;
+        return typeof data === "string" ? data : JSON.stringify(data);
+      };
       const telemetryEvent = {
+        game_id: this.gameId,
         session_id: this.sessionId,
-        hyve_user_id: this.userId || "anonymous",
+        platform_id: platformId || null,
         event_location: eventLocation,
         event_category: eventCategory,
         event_action: eventAction,
         event_sub_category: eventSubCategory || null,
         event_sub_action: eventSubAction || null,
-        event_details: finalEventDetails
+        event_details: toJsonString(eventDetails),
+        custom_data: toJsonString(customData)
       };
-      console.log("[Hyve Telemetry] Sending event:", telemetryEvent);
-      const telemetryUrl = `${this.apiBaseUrl}/api/v1/partners/analytics/events`;
+      console.log("[Hyve Telemetry] Sending user-level event:", telemetryEvent);
+      const telemetryUrl = `${this.apiBaseUrl}/api/v1/telemetry/send`;
       const response = await fetch(telemetryUrl, {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
-          "X-API-KEY": this.telemetryConfig.apiKey
+          "Authorization": `Bearer ${this.jwtToken}`
         },
         body: JSON.stringify(telemetryEvent)
       });
@@ -386,6 +399,13 @@ var HyveClient = class {
   getJwtToken() {
     return this.jwtToken;
   }
+  /**
+   * Gets the current game ID
+   * @returns Current game ID or null if not available
+   */
+  getGameId() {
+    return this.gameId;
+  }
   /**
    * Gets the API base URL
    * @returns API base URL
@@ -413,6 +433,7 @@ var HyveClient = class {
   logout() {
     this.userId = null;
     this.jwtToken = null;
+    this.gameId = null;
     console.log("[Hyve SDK] User logged out");
   }
   /**

package/dist/index.mjs

@@ -9,7 +9,8 @@ function parseUrlParams(searchParams) {
     gameStartTab: params.get("game_start_tab") || "",
     hyveToken: params.get("hyve-token") || "",
     platform: params.get("platform") || "",
-    hyveAccess: params.get("hyve-access") || ""
+    hyveAccess: params.get("hyve-access") || "",
+    gameId: params.get("game-id") || ""
   };
 }
 function validateSignature(signature, message) {
@@ -158,6 +159,7 @@ var HyveClient = class {
   sessionId;
   userId = null;
   jwtToken = null;
+  gameId = null;
   /**
    * Creates a new HyveClient instance
    * @param config Optional telemetry configuration
@@ -190,6 +192,14 @@ var HyveClient = class {
         this.jwtToken = params.hyveAccess;
         console.log("[Hyve SDK] JWT token extracted from hyve-access parameter");
       }
+      if (params.gameId) {
+        this.gameId = params.gameId;
+        console.log("[Hyve SDK] Game ID extracted from game-id parameter:", this.gameId);
+      }
+      if (this.jwtToken) {
+        console.log("[Hyve SDK] Authentication successful via JWT");
+        return true;
+      }
       const authResult = verifyAuthentication({
         hyveToken: params.hyveToken,
         signature: params.signature,
@@ -212,48 +222,51 @@ var HyveClient = class {
     }
   }
   /**
-   * 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
    */
-  async sendTelemetry(eventLocation, eventCategory, eventAction, eventSubCategory, eventSubAction, eventDetails, additionalData) {
-    if (!this.telemetryConfig.apiKey) {
-      console.error("[Hyve Telemetry] API key not configured");
+  async sendTelemetry(eventLocation, eventCategory, eventAction, eventSubCategory, eventSubAction, eventDetails, customData, platformId) {
+    if (!this.jwtToken) {
+      console.error("[Hyve Telemetry] JWT token required. Call authenticateFromUrl first.");
       return false;
     }
-    if (!this.userId) {
-      console.warn("[Hyve Telemetry] No user ID - sending anonymous telemetry");
+    if (!this.gameId) {
+      console.error("[Hyve Telemetry] Game ID required. Ensure game-id URL parameter is set.");
+      return false;
     }
     try {
-      let finalEventDetails = null;
-      if (additionalData && Object.keys(additionalData).length > 0) {
-        finalEventDetails = JSON.stringify(additionalData);
-      } else if (eventDetails) {
-        finalEventDetails = eventDetails;
-      }
+      const toJsonString = (data) => {
+        if (!data) return null;
+        return typeof data === "string" ? data : JSON.stringify(data);
+      };
       const telemetryEvent = {
+        game_id: this.gameId,
         session_id: this.sessionId,
-        hyve_user_id: this.userId || "anonymous",
+        platform_id: platformId || null,
         event_location: eventLocation,
         event_category: eventCategory,
         event_action: eventAction,
         event_sub_category: eventSubCategory || null,
         event_sub_action: eventSubAction || null,
-        event_details: finalEventDetails
+        event_details: toJsonString(eventDetails),
+        custom_data: toJsonString(customData)
       };
-      console.log("[Hyve Telemetry] Sending event:", telemetryEvent);
-      const telemetryUrl = `${this.apiBaseUrl}/api/v1/partners/analytics/events`;
+      console.log("[Hyve Telemetry] Sending user-level event:", telemetryEvent);
+      const telemetryUrl = `${this.apiBaseUrl}/api/v1/telemetry/send`;
       const response = await fetch(telemetryUrl, {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
-          "X-API-KEY": this.telemetryConfig.apiKey
+          "Authorization": `Bearer ${this.jwtToken}`
         },
         body: JSON.stringify(telemetryEvent)
       });
@@ -353,6 +366,13 @@ var HyveClient = class {
   getJwtToken() {
     return this.jwtToken;
   }
+  /**
+   * Gets the current game ID
+   * @returns Current game ID or null if not available
+   */
+  getGameId() {
+    return this.gameId;
+  }
   /**
    * Gets the API base URL
    * @returns API base URL
@@ -380,6 +400,7 @@ var HyveClient = class {
   logout() {
     this.userId = null;
     this.jwtToken = null;
+    this.gameId = null;
     console.log("[Hyve SDK] User logged out");
   }
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyve-sdk/js",
-  "version": "1.1.2",
+  "version": "1.2.2",
   "description": "Hyve SDK - TypeScript wrapper for Hyve game server integration",
   "private": false,
   "publishConfig": {
@@ -44,14 +44,14 @@
     "@types/uuid": "^10.0.0",
     "tsup": "^8.4.0",
     "typescript": "^5.3.3",
-    "@repo/eslint-config": "0.0.0",
-    "@repo/typescript-config": "0.0.0"
+    "@repo/typescript-config": "0.0.0",
+    "@repo/eslint-config": "0.0.0"
   },
   "scripts": {
     "lint": "eslint . --max-warnings 0",
     "check-types": "tsc --noEmit",
     "build": "tsup src/index.ts --format cjs,esm --dts --clean",
-    "publish:npm": "pnpm publish --access public --no-git-checks",
+    "publish:npm": "pnpm publish --access public",
     "publish:dry-run": "pnpm publish --dry-run --access public --no-git-checks"
   }
 }