@hyve-sdk/js 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hyve
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+# @hyve/sdk
+
+TypeScript SDK for web3 authentication and game integration, providing secure signature verification and utility functions.
+
+## Installation
+
+```bash
+bun add @hyve/sdk
+# or
+npm install @hyve/sdk
+# or
+pnpm add @hyve/sdk
+```
+
+## Features
+
+- **Web3 Authentication**: EVM signature validation and verification
+- **Modern & Legacy Token Support**: Dual authentication token formats
+- **Security Utilities**: Domain validation and referrer checking  
+- **URL Parameter Parsing**: Easy extraction of authentication parameters
+- **UUID Generation**: Built-in UUID v4 generation
+
+## Core Components
+
+### HyveClient
+Main client class for SDK operations (currently minimal implementation).
+
+```typescript
+import { HyveClient } from "@hyve/sdk";
+
+const client = new HyveClient();
+```
+
+### Authentication Utilities
+
+#### Parse URL Parameters
+Extract authentication and game parameters from URL:
+
+```typescript
+import { parseUrlParams } from "@hyve/sdk";
+
+const params = parseUrlParams(window.location.search);
+// Returns:
+// {
+//   signature: string,
+//   message: string,
+//   userId: string,
+//   gameStartTab: string,
+//   hyveToken: string,
+//   platform: string
+// }
+```
+
+#### Verify Authentication
+Unified verification supporting both modern and legacy tokens:
+
+```typescript
+import { verifyAuthentication } from "@hyve/sdk";
+
+const result = verifyAuthentication({
+  hyveToken: params.hyveToken,    // Modern token format
+  signature: params.signature,     // Legacy format
+  message: params.message          // Legacy format
+});
+
+if (result.isValid) {
+  console.log('Authenticated address:', result.address);
+  console.log('Auth method used:', result.method); // 'modern' or 'legacy'
+}
+```
+
+#### Modern Token Verification (Hyve Token)
+Verify modern authentication tokens with expiration:
+
+```typescript
+import { verifyHyveToken } from "@hyve/sdk";
+
+// Token format: signature.address.randomBase64.timestamp
+const address = verifyHyveToken(hyveToken, 600); // 600 seconds max age
+if (address) {
+  console.log('Valid token for address:', address);
+}
+```
+
+#### Legacy Token Verification
+Verify legacy signed messages with metadata:
+
+```typescript
+import { handleVerifyMessage, validateSignature } from "@hyve/sdk";
+
+// Method 1: Verify message with embedded metadata
+const address = handleVerifyMessage(signature, message);
+
+// Method 2: Simple signature validation
+const isValid = validateSignature(signature, message, userId);
+```
+
+### Security Utilities
+
+#### Domain Validation
+Check if current domain is allowed:
+
+```typescript
+import { isDomainAllowed } from "@hyve/sdk";
+
+// Single domain
+const allowed = isDomainAllowed('example.com', window.location.hostname);
+
+// Multiple domains with wildcard support
+const allowed = isDomainAllowed(
+  ['example.com', '*.subdomain.com'],
+  window.location.hostname
+);
+
+// Note: localhost is always allowed
+```
+
+### Utility Functions
+
+#### UUID Generation
+Generate random UUID v4:
+
+```typescript
+import { generateUUID } from "@hyve/sdk";
+
+const id = generateUUID();
+```
+
+## Authentication Flow
+
+### Modern Token Flow (Recommended)
+1. User authenticates on platform
+2. Platform generates hyve-token: `signature.address.random.timestamp`
+3. Token passed via URL parameter `hyve-token`
+4. SDK verifies token with `verifyHyveToken()` or `verifyAuthentication()`
+
+### Legacy Token Flow
+1. User signs message containing metadata (expiration, address)
+2. Signature and message passed via URL parameters
+3. SDK verifies with `handleVerifyMessage()` or `verifyAuthentication()`
+
+## Security Considerations
+
+- **Token Expiration**: Modern tokens expire after 10 minutes by default
+- **Domain Validation**: Always validate origin domains in production
+- **Signature Verification**: All signatures verified using ethers.js
+- **Localhost Exception**: localhost always allowed for development
+
+## TypeScript Support
+
+Full TypeScript support with exported types for all utilities and return values.
+
+## Dependencies
+
+- **ethers**: ^6.13.7 - Ethereum signature verification
+- **uuid**: (peer dependency) - UUID generation
+
+## Build Configuration
+
+The SDK builds to multiple formats:
+- CommonJS (`dist/index.js`)
+- ES Modules (`dist/index.mjs`)  
+- TypeScript declarations (`dist/index.d.ts`)
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Type checking
+bun run check-types
+
+# Linting
+bun run lint
+
+# Build
+bun run build
+```
+
+## Documentation
+
+For complete documentation and examples, visit [https://docs.hyve.gg](https://docs.hyve.gg)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,161 @@
+/**
+ * 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;
+}
+/**
+ * Telemetry event data structure
+ */
+interface TelemetryEvent {
+    /** Unique session identifier */
+    session_id: string;
+    /** Hyve user identifier (address) */
+    hyve_user_id: string;
+    /** Location where the event occurred */
+    event_location: string;
+    /** Main category of the event */
+    event_category: string;
+    /** Primary action taken */
+    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;
+}
+/**
+ * Additional telemetry data that can be passed with events
+ */
+interface TelemetryAdditionalData {
+    /** Optional additional data object (will be JSON stringified and put in event_details) */
+    [key: string]: any;
+}
+
+/**
+ * HyveClient provides telemetry and authentication functionality for Hyve games
+ */
+declare class HyveClient {
+    private telemetryConfig;
+    private telemetryApiUrl;
+    private sessionId;
+    private userId;
+    /**
+     * Creates a new HyveClient instance
+     * @param config Optional telemetry configuration
+     */
+    constructor(config?: TelemetryConfig);
+    /**
+     * Authenticates a user from URL parameters
+     * @param urlParams URL parameters or search string
+     * @returns Promise resolving to boolean indicating success
+     */
+    authenticateFromUrl(urlParams?: URLSearchParams | string): Promise<boolean>;
+    /**
+     * Sends a telemetry event
+     * @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
+     * @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>;
+    /**
+     * Updates the telemetry configuration
+     * @param config New telemetry configuration
+     */
+    updateTelemetryConfig(config: TelemetryConfig): void;
+    /**
+     * Gets the current user ID
+     * @returns Current user ID or null if not authenticated
+     */
+    getUserId(): string | null;
+    /**
+     * Gets the current session ID
+     * @returns Current session ID
+     */
+    getSessionId(): string;
+    /**
+     * Checks if user is authenticated
+     * @returns Boolean indicating authentication status
+     */
+    isUserAuthenticated(): boolean;
+    /**
+     * Logs out the current user
+     */
+    logout(): void;
+    /**
+     * Resets the client state
+     */
+    reset(): void;
+}
+
+/**
+ * Parses URL search parameters and returns commonly used values
+ * @param searchParams URLSearchParams object or string
+ * @returns Object containing parsed parameters with default values
+ */
+declare function parseUrlParams(searchParams: URLSearchParams | string): {
+    signature: string;
+    message: string;
+    gameStartTab: string;
+    hyveToken: string;
+    platform: string;
+};
+/**
+ * Validates an EVM signature against a message and user ID
+ * @param signature The signature to validate
+ * @param message The original message that was signed
+ * @returns Promise resolving to boolean indicating if signature is valid
+ */
+declare function validateSignature(signature: string, message: string): boolean;
+/**
+ * Verifies a signed message containing metadata with expiration and address (LEGACY)
+ * @param signature The signature to verify
+ * @param message The encoded message containing metadata (JSON)
+ * @returns The address that signed the message if valid, false otherwise
+ */
+declare function handleVerifyMessage(signature: string, message: string): string | false;
+/**
+ * Verifies a modern hyve-token
+ * @param hyveToken The modern token in format: signature.address.randomBase64.timestamp
+ * @param maxAgeSec Maximum age in seconds (default: 600 = 10 minutes)
+ * @returns The verified address if valid, false otherwise
+ */
+declare function verifyHyveToken(hyveToken: string, maxAgeSec?: number): string | false;
+/**
+ * Unified authentication verification - tries modern token first, then falls back to legacy
+ * @param params Object containing hyveToken, signature, message from URL params
+ * @param maxAgeSec Maximum age for modern tokens in seconds (default: 600)
+ * @returns Object with verification result and method used
+ */
+declare function verifyAuthentication(params: {
+    hyveToken?: string;
+    signature?: string;
+    message?: string;
+}, maxAgeSec?: number): {
+    isValid: boolean;
+    address: string | null;
+    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
+ * @returns Boolean indicating if the current domain is allowed
+ */
+declare function isDomainAllowed(allowedDomains?: string | string[], hostname?: string): boolean;
+
+export { HyveClient, type TelemetryAdditionalData, type TelemetryConfig, type TelemetryEvent, generateUUID, handleVerifyMessage, isDomainAllowed, parseUrlParams, validateSignature, verifyAuthentication, verifyHyveToken };

package/dist/index.d.ts

@@ -0,0 +1,161 @@
+/**
+ * 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;
+}
+/**
+ * Telemetry event data structure
+ */
+interface TelemetryEvent {
+    /** Unique session identifier */
+    session_id: string;
+    /** Hyve user identifier (address) */
+    hyve_user_id: string;
+    /** Location where the event occurred */
+    event_location: string;
+    /** Main category of the event */
+    event_category: string;
+    /** Primary action taken */
+    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;
+}
+/**
+ * Additional telemetry data that can be passed with events
+ */
+interface TelemetryAdditionalData {
+    /** Optional additional data object (will be JSON stringified and put in event_details) */
+    [key: string]: any;
+}
+
+/**
+ * HyveClient provides telemetry and authentication functionality for Hyve games
+ */
+declare class HyveClient {
+    private telemetryConfig;
+    private telemetryApiUrl;
+    private sessionId;
+    private userId;
+    /**
+     * Creates a new HyveClient instance
+     * @param config Optional telemetry configuration
+     */
+    constructor(config?: TelemetryConfig);
+    /**
+     * Authenticates a user from URL parameters
+     * @param urlParams URL parameters or search string
+     * @returns Promise resolving to boolean indicating success
+     */
+    authenticateFromUrl(urlParams?: URLSearchParams | string): Promise<boolean>;
+    /**
+     * Sends a telemetry event
+     * @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
+     * @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>;
+    /**
+     * Updates the telemetry configuration
+     * @param config New telemetry configuration
+     */
+    updateTelemetryConfig(config: TelemetryConfig): void;
+    /**
+     * Gets the current user ID
+     * @returns Current user ID or null if not authenticated
+     */
+    getUserId(): string | null;
+    /**
+     * Gets the current session ID
+     * @returns Current session ID
+     */
+    getSessionId(): string;
+    /**
+     * Checks if user is authenticated
+     * @returns Boolean indicating authentication status
+     */
+    isUserAuthenticated(): boolean;
+    /**
+     * Logs out the current user
+     */
+    logout(): void;
+    /**
+     * Resets the client state
+     */
+    reset(): void;
+}
+
+/**
+ * Parses URL search parameters and returns commonly used values
+ * @param searchParams URLSearchParams object or string
+ * @returns Object containing parsed parameters with default values
+ */
+declare function parseUrlParams(searchParams: URLSearchParams | string): {
+    signature: string;
+    message: string;
+    gameStartTab: string;
+    hyveToken: string;
+    platform: string;
+};
+/**
+ * Validates an EVM signature against a message and user ID
+ * @param signature The signature to validate
+ * @param message The original message that was signed
+ * @returns Promise resolving to boolean indicating if signature is valid
+ */
+declare function validateSignature(signature: string, message: string): boolean;
+/**
+ * Verifies a signed message containing metadata with expiration and address (LEGACY)
+ * @param signature The signature to verify
+ * @param message The encoded message containing metadata (JSON)
+ * @returns The address that signed the message if valid, false otherwise
+ */
+declare function handleVerifyMessage(signature: string, message: string): string | false;
+/**
+ * Verifies a modern hyve-token
+ * @param hyveToken The modern token in format: signature.address.randomBase64.timestamp
+ * @param maxAgeSec Maximum age in seconds (default: 600 = 10 minutes)
+ * @returns The verified address if valid, false otherwise
+ */
+declare function verifyHyveToken(hyveToken: string, maxAgeSec?: number): string | false;
+/**
+ * Unified authentication verification - tries modern token first, then falls back to legacy
+ * @param params Object containing hyveToken, signature, message from URL params
+ * @param maxAgeSec Maximum age for modern tokens in seconds (default: 600)
+ * @returns Object with verification result and method used
+ */
+declare function verifyAuthentication(params: {
+    hyveToken?: string;
+    signature?: string;
+    message?: string;
+}, maxAgeSec?: number): {
+    isValid: boolean;
+    address: string | null;
+    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
+ * @returns Boolean indicating if the current domain is allowed
+ */
+declare function isDomainAllowed(allowedDomains?: string | string[], hostname?: string): boolean;
+
+export { HyveClient, type TelemetryAdditionalData, type TelemetryConfig, type TelemetryEvent, generateUUID, handleVerifyMessage, isDomainAllowed, parseUrlParams, validateSignature, verifyAuthentication, verifyHyveToken };

package/dist/index.js

@@ -0,0 +1,353 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  HyveClient: () => HyveClient,
+  generateUUID: () => generateUUID,
+  handleVerifyMessage: () => handleVerifyMessage,
+  isDomainAllowed: () => isDomainAllowed,
+  parseUrlParams: () => parseUrlParams,
+  validateSignature: () => validateSignature,
+  verifyAuthentication: () => verifyAuthentication,
+  verifyHyveToken: () => verifyHyveToken
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/utils/index.ts
+var import_ethers = require("ethers");
+var import_uuid = require("uuid");
+function parseUrlParams(searchParams) {
+  const params = typeof searchParams === "string" ? new URLSearchParams(searchParams) : searchParams;
+  return {
+    signature: params.get("signature") || "",
+    message: params.get("message") || "",
+    gameStartTab: params.get("game_start_tab") || "",
+    hyveToken: params.get("hyve-token") || "",
+    platform: params.get("platform") || ""
+  };
+}
+function validateSignature(signature, message) {
+  try {
+    const recoveredAddress = import_ethers.ethers.verifyMessage(message, signature);
+    return !!recoveredAddress;
+  } catch (error) {
+    console.error("Signature validation error:", error);
+    return false;
+  }
+}
+function handleVerifyMessage(signature, message) {
+  try {
+    const metadata = JSON.parse(decodeURI(message));
+    if (!metadata.expiration || metadata.expiration < Date.now()) {
+      return false;
+    }
+    const userAddress = metadata.userId || metadata.address;
+    if (!userAddress) {
+      return false;
+    }
+    const byteMessage = new TextEncoder().encode(message);
+    const addressThatSignedMessage = import_ethers.ethers.verifyMessage(
+      byteMessage,
+      signature
+    );
+    if (!addressThatSignedMessage) {
+      return false;
+    }
+    if (addressThatSignedMessage.toLowerCase() !== userAddress.toLowerCase()) {
+      return false;
+    }
+    return userAddress;
+  } catch (error) {
+    console.error("Error verifying message:", error);
+    return false;
+  }
+}
+function verifyHyveToken(hyveToken, maxAgeSec = 600) {
+  try {
+    const parts = hyveToken.split(".");
+    if (parts.length !== 4) {
+      console.error(
+        "Invalid hyve-token format: expected 4 parts, got",
+        parts.length
+      );
+      return false;
+    }
+    const [signature, address, randomBase64, timestampStr] = parts;
+    if (!signature || !address || !randomBase64 || !timestampStr) {
+      console.error("Missing hyve-token components");
+      return false;
+    }
+    const message = `${address}.${randomBase64}.${timestampStr}`;
+    const recoveredAddress = import_ethers.ethers.verifyMessage(message, signature);
+    if (recoveredAddress.toLowerCase() !== address.toLowerCase()) {
+      console.error("Hyve-token signature verification failed");
+      return false;
+    }
+    const timestamp = parseInt(timestampStr, 10);
+    if (!Number.isFinite(timestamp)) {
+      console.error("Invalid hyve-token timestamp");
+      return false;
+    }
+    const now = Math.floor(Date.now() / 1e3);
+    if (now - timestamp > maxAgeSec) {
+      console.error(
+        `Hyve-token expired (age: ${now - timestamp}s, max: ${maxAgeSec}s)`
+      );
+      return false;
+    }
+    return address;
+  } catch (error) {
+    console.error("Hyve-token verification error:", error);
+    return false;
+  }
+}
+function verifyAuthentication(params, maxAgeSec = 600) {
+  if (params.hyveToken) {
+    const modernAddress = verifyHyveToken(params.hyveToken, maxAgeSec);
+    if (modernAddress) {
+      return {
+        isValid: true,
+        address: modernAddress,
+        method: "modern"
+      };
+    } else {
+      return {
+        isValid: false,
+        address: null,
+        method: "modern",
+        error: "Modern token verification failed"
+      };
+    }
+  }
+  if (params.signature && params.message) {
+    const legacyAddress = handleVerifyMessage(params.signature, params.message);
+    if (legacyAddress) {
+      return {
+        isValid: true,
+        address: legacyAddress,
+        method: "legacy"
+      };
+    } else {
+      return {
+        isValid: false,
+        address: null,
+        method: "legacy",
+        error: "Legacy token verification failed"
+      };
+    }
+  }
+  return {
+    isValid: false,
+    address: null,
+    method: "none",
+    error: "No authentication tokens provided"
+  };
+}
+function generateUUID() {
+  return (0, import_uuid.v4)();
+}
+function isDomainAllowed(allowedDomains, hostname) {
+  console.log("Hostname", hostname);
+  if (!allowedDomains) return true;
+  const targetHostname = hostname || "";
+  if (!targetHostname) return false;
+  if (targetHostname === "localhost" || targetHostname.startsWith("localhost:")) {
+    return true;
+  }
+  const domains = Array.isArray(allowedDomains) ? allowedDomains : [allowedDomains];
+  return domains.some((domain) => {
+    if (domain === targetHostname) return true;
+    if (domain.startsWith("*.")) {
+      const baseDomain = domain.substring(2);
+      return targetHostname.endsWith(baseDomain) && targetHostname.length > baseDomain.length && targetHostname.charAt(targetHostname.length - baseDomain.length - 1) === ".";
+    }
+    return false;
+  });
+}
+
+// src/core/client.ts
+var HyveClient = class {
+  telemetryConfig;
+  telemetryApiUrl;
+  sessionId;
+  userId = null;
+  /**
+   * Creates a new HyveClient instance
+   * @param config Optional telemetry configuration
+   */
+  constructor(config) {
+    this.telemetryConfig = {
+      isDev: true,
+      // Default to dev environment
+      ...config
+    };
+    this.telemetryApiUrl = this.telemetryConfig.isDev ? "https://product-api.dev.hyve.gg/api/v1/partners/analytics/events" : "https://product-api.prod.hyve.gg/api/v1/partners/analytics/events";
+    this.sessionId = generateUUID();
+    console.log("[Hyve SDK] Client initialized with sessionId:", this.sessionId);
+    console.log("[Hyve SDK] Telemetry environment:", this.telemetryConfig.isDev ? "dev" : "prod");
+  }
+  /**
+   * Authenticates a user from URL parameters
+   * @param urlParams URL parameters or search string
+   * @returns Promise resolving to boolean indicating success
+   */
+  async authenticateFromUrl(urlParams) {
+    try {
+      const params = urlParams ? parseUrlParams(urlParams) : parseUrlParams(window.location.search);
+      const authResult = verifyAuthentication({
+        hyveToken: params.hyveToken,
+        signature: params.signature,
+        message: params.message
+      });
+      if (authResult.isValid && authResult.address) {
+        this.userId = authResult.address;
+        console.log("[Hyve SDK] Authentication successful:", authResult.address);
+        console.log("[Hyve SDK] Authentication method:", authResult.method);
+        return true;
+      } else {
+        console.error("[Hyve SDK] Authentication failed:", authResult.error);
+        this.userId = null;
+        return false;
+      }
+    } catch (error) {
+      console.error("[Hyve SDK] Authentication error:", error);
+      this.userId = null;
+      return false;
+    }
+  }
+  /**
+   * Sends a telemetry event
+   * @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
+   * @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");
+      return false;
+    }
+    if (!this.userId) {
+      console.warn("[Hyve Telemetry] No user ID - sending anonymous telemetry");
+    }
+    try {
+      let finalEventDetails = null;
+      if (additionalData && Object.keys(additionalData).length > 0) {
+        finalEventDetails = JSON.stringify(additionalData);
+      } else if (eventDetails) {
+        finalEventDetails = eventDetails;
+      }
+      const telemetryEvent = {
+        session_id: this.sessionId,
+        hyve_user_id: this.userId || "anonymous",
+        event_location: eventLocation,
+        event_category: eventCategory,
+        event_action: eventAction,
+        event_sub_category: eventSubCategory || null,
+        event_sub_action: eventSubAction || null,
+        event_details: finalEventDetails
+      };
+      console.log("[Hyve Telemetry] Sending event:", telemetryEvent);
+      const response = await fetch(this.telemetryApiUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-API-KEY": this.telemetryConfig.apiKey
+        },
+        body: JSON.stringify(telemetryEvent)
+      });
+      if (response.ok) {
+        console.log("[Hyve Telemetry] Event sent successfully:", response.status);
+        return true;
+      } else {
+        const errorText = await response.text();
+        console.error("[Hyve Telemetry] Failed to send event:", response.status, errorText);
+        return false;
+      }
+    } catch (error) {
+      console.error("[Hyve Telemetry] Error sending event:", error);
+      return false;
+    }
+  }
+  /**
+   * Updates the telemetry configuration
+   * @param config New telemetry configuration
+   */
+  updateTelemetryConfig(config) {
+    this.telemetryConfig = {
+      ...this.telemetryConfig,
+      ...config
+    };
+    this.telemetryApiUrl = this.telemetryConfig.isDev ? "https://product-api.dev.hyve.gg/api/v1/partners/analytics/events" : "https://product-api.prod.hyve.gg/api/v1/partners/analytics/events";
+    console.log("[Hyve SDK] Telemetry config updated");
+  }
+  /**
+   * Gets the current user ID
+   * @returns Current user ID or null if not authenticated
+   */
+  getUserId() {
+    return this.userId;
+  }
+  /**
+   * Gets the current session ID
+   * @returns Current session ID
+   */
+  getSessionId() {
+    return this.sessionId;
+  }
+  /**
+   * Checks if user is authenticated
+   * @returns Boolean indicating authentication status
+   */
+  isUserAuthenticated() {
+    return this.userId !== null;
+  }
+  /**
+   * Logs out the current user
+   */
+  logout() {
+    this.userId = null;
+    console.log("[Hyve SDK] User logged out");
+  }
+  /**
+   * Resets the client state
+   */
+  reset() {
+    this.logout();
+    this.sessionId = generateUUID();
+    console.log("[Hyve SDK] Client reset with new sessionId:", this.sessionId);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HyveClient,
+  generateUUID,
+  handleVerifyMessage,
+  isDomainAllowed,
+  parseUrlParams,
+  validateSignature,
+  verifyAuthentication,
+  verifyHyveToken
+});

package/dist/index.mjs

@@ -0,0 +1,319 @@
+// src/utils/index.ts
+import { ethers } from "ethers";
+import { v4 as uuidv4 } from "uuid";
+function parseUrlParams(searchParams) {
+  const params = typeof searchParams === "string" ? new URLSearchParams(searchParams) : searchParams;
+  return {
+    signature: params.get("signature") || "",
+    message: params.get("message") || "",
+    gameStartTab: params.get("game_start_tab") || "",
+    hyveToken: params.get("hyve-token") || "",
+    platform: params.get("platform") || ""
+  };
+}
+function validateSignature(signature, message) {
+  try {
+    const recoveredAddress = ethers.verifyMessage(message, signature);
+    return !!recoveredAddress;
+  } catch (error) {
+    console.error("Signature validation error:", error);
+    return false;
+  }
+}
+function handleVerifyMessage(signature, message) {
+  try {
+    const metadata = JSON.parse(decodeURI(message));
+    if (!metadata.expiration || metadata.expiration < Date.now()) {
+      return false;
+    }
+    const userAddress = metadata.userId || metadata.address;
+    if (!userAddress) {
+      return false;
+    }
+    const byteMessage = new TextEncoder().encode(message);
+    const addressThatSignedMessage = ethers.verifyMessage(
+      byteMessage,
+      signature
+    );
+    if (!addressThatSignedMessage) {
+      return false;
+    }
+    if (addressThatSignedMessage.toLowerCase() !== userAddress.toLowerCase()) {
+      return false;
+    }
+    return userAddress;
+  } catch (error) {
+    console.error("Error verifying message:", error);
+    return false;
+  }
+}
+function verifyHyveToken(hyveToken, maxAgeSec = 600) {
+  try {
+    const parts = hyveToken.split(".");
+    if (parts.length !== 4) {
+      console.error(
+        "Invalid hyve-token format: expected 4 parts, got",
+        parts.length
+      );
+      return false;
+    }
+    const [signature, address, randomBase64, timestampStr] = parts;
+    if (!signature || !address || !randomBase64 || !timestampStr) {
+      console.error("Missing hyve-token components");
+      return false;
+    }
+    const message = `${address}.${randomBase64}.${timestampStr}`;
+    const recoveredAddress = ethers.verifyMessage(message, signature);
+    if (recoveredAddress.toLowerCase() !== address.toLowerCase()) {
+      console.error("Hyve-token signature verification failed");
+      return false;
+    }
+    const timestamp = parseInt(timestampStr, 10);
+    if (!Number.isFinite(timestamp)) {
+      console.error("Invalid hyve-token timestamp");
+      return false;
+    }
+    const now = Math.floor(Date.now() / 1e3);
+    if (now - timestamp > maxAgeSec) {
+      console.error(
+        `Hyve-token expired (age: ${now - timestamp}s, max: ${maxAgeSec}s)`
+      );
+      return false;
+    }
+    return address;
+  } catch (error) {
+    console.error("Hyve-token verification error:", error);
+    return false;
+  }
+}
+function verifyAuthentication(params, maxAgeSec = 600) {
+  if (params.hyveToken) {
+    const modernAddress = verifyHyveToken(params.hyveToken, maxAgeSec);
+    if (modernAddress) {
+      return {
+        isValid: true,
+        address: modernAddress,
+        method: "modern"
+      };
+    } else {
+      return {
+        isValid: false,
+        address: null,
+        method: "modern",
+        error: "Modern token verification failed"
+      };
+    }
+  }
+  if (params.signature && params.message) {
+    const legacyAddress = handleVerifyMessage(params.signature, params.message);
+    if (legacyAddress) {
+      return {
+        isValid: true,
+        address: legacyAddress,
+        method: "legacy"
+      };
+    } else {
+      return {
+        isValid: false,
+        address: null,
+        method: "legacy",
+        error: "Legacy token verification failed"
+      };
+    }
+  }
+  return {
+    isValid: false,
+    address: null,
+    method: "none",
+    error: "No authentication tokens provided"
+  };
+}
+function generateUUID() {
+  return uuidv4();
+}
+function isDomainAllowed(allowedDomains, hostname) {
+  console.log("Hostname", hostname);
+  if (!allowedDomains) return true;
+  const targetHostname = hostname || "";
+  if (!targetHostname) return false;
+  if (targetHostname === "localhost" || targetHostname.startsWith("localhost:")) {
+    return true;
+  }
+  const domains = Array.isArray(allowedDomains) ? allowedDomains : [allowedDomains];
+  return domains.some((domain) => {
+    if (domain === targetHostname) return true;
+    if (domain.startsWith("*.")) {
+      const baseDomain = domain.substring(2);
+      return targetHostname.endsWith(baseDomain) && targetHostname.length > baseDomain.length && targetHostname.charAt(targetHostname.length - baseDomain.length - 1) === ".";
+    }
+    return false;
+  });
+}
+
+// src/core/client.ts
+var HyveClient = class {
+  telemetryConfig;
+  telemetryApiUrl;
+  sessionId;
+  userId = null;
+  /**
+   * Creates a new HyveClient instance
+   * @param config Optional telemetry configuration
+   */
+  constructor(config) {
+    this.telemetryConfig = {
+      isDev: true,
+      // Default to dev environment
+      ...config
+    };
+    this.telemetryApiUrl = this.telemetryConfig.isDev ? "https://product-api.dev.hyve.gg/api/v1/partners/analytics/events" : "https://product-api.prod.hyve.gg/api/v1/partners/analytics/events";
+    this.sessionId = generateUUID();
+    console.log("[Hyve SDK] Client initialized with sessionId:", this.sessionId);
+    console.log("[Hyve SDK] Telemetry environment:", this.telemetryConfig.isDev ? "dev" : "prod");
+  }
+  /**
+   * Authenticates a user from URL parameters
+   * @param urlParams URL parameters or search string
+   * @returns Promise resolving to boolean indicating success
+   */
+  async authenticateFromUrl(urlParams) {
+    try {
+      const params = urlParams ? parseUrlParams(urlParams) : parseUrlParams(window.location.search);
+      const authResult = verifyAuthentication({
+        hyveToken: params.hyveToken,
+        signature: params.signature,
+        message: params.message
+      });
+      if (authResult.isValid && authResult.address) {
+        this.userId = authResult.address;
+        console.log("[Hyve SDK] Authentication successful:", authResult.address);
+        console.log("[Hyve SDK] Authentication method:", authResult.method);
+        return true;
+      } else {
+        console.error("[Hyve SDK] Authentication failed:", authResult.error);
+        this.userId = null;
+        return false;
+      }
+    } catch (error) {
+      console.error("[Hyve SDK] Authentication error:", error);
+      this.userId = null;
+      return false;
+    }
+  }
+  /**
+   * Sends a telemetry event
+   * @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
+   * @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");
+      return false;
+    }
+    if (!this.userId) {
+      console.warn("[Hyve Telemetry] No user ID - sending anonymous telemetry");
+    }
+    try {
+      let finalEventDetails = null;
+      if (additionalData && Object.keys(additionalData).length > 0) {
+        finalEventDetails = JSON.stringify(additionalData);
+      } else if (eventDetails) {
+        finalEventDetails = eventDetails;
+      }
+      const telemetryEvent = {
+        session_id: this.sessionId,
+        hyve_user_id: this.userId || "anonymous",
+        event_location: eventLocation,
+        event_category: eventCategory,
+        event_action: eventAction,
+        event_sub_category: eventSubCategory || null,
+        event_sub_action: eventSubAction || null,
+        event_details: finalEventDetails
+      };
+      console.log("[Hyve Telemetry] Sending event:", telemetryEvent);
+      const response = await fetch(this.telemetryApiUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-API-KEY": this.telemetryConfig.apiKey
+        },
+        body: JSON.stringify(telemetryEvent)
+      });
+      if (response.ok) {
+        console.log("[Hyve Telemetry] Event sent successfully:", response.status);
+        return true;
+      } else {
+        const errorText = await response.text();
+        console.error("[Hyve Telemetry] Failed to send event:", response.status, errorText);
+        return false;
+      }
+    } catch (error) {
+      console.error("[Hyve Telemetry] Error sending event:", error);
+      return false;
+    }
+  }
+  /**
+   * Updates the telemetry configuration
+   * @param config New telemetry configuration
+   */
+  updateTelemetryConfig(config) {
+    this.telemetryConfig = {
+      ...this.telemetryConfig,
+      ...config
+    };
+    this.telemetryApiUrl = this.telemetryConfig.isDev ? "https://product-api.dev.hyve.gg/api/v1/partners/analytics/events" : "https://product-api.prod.hyve.gg/api/v1/partners/analytics/events";
+    console.log("[Hyve SDK] Telemetry config updated");
+  }
+  /**
+   * Gets the current user ID
+   * @returns Current user ID or null if not authenticated
+   */
+  getUserId() {
+    return this.userId;
+  }
+  /**
+   * Gets the current session ID
+   * @returns Current session ID
+   */
+  getSessionId() {
+    return this.sessionId;
+  }
+  /**
+   * Checks if user is authenticated
+   * @returns Boolean indicating authentication status
+   */
+  isUserAuthenticated() {
+    return this.userId !== null;
+  }
+  /**
+   * Logs out the current user
+   */
+  logout() {
+    this.userId = null;
+    console.log("[Hyve SDK] User logged out");
+  }
+  /**
+   * Resets the client state
+   */
+  reset() {
+    this.logout();
+    this.sessionId = generateUUID();
+    console.log("[Hyve SDK] Client reset with new sessionId:", this.sessionId);
+  }
+};
+export {
+  HyveClient,
+  generateUUID,
+  handleVerifyMessage,
+  isDomainAllowed,
+  parseUrlParams,
+  validateSignature,
+  verifyAuthentication,
+  verifyHyveToken
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@hyve-sdk/js",
+  "version": "1.0.1",
+  "description": "Hyve SDK - TypeScript wrapper for Hyve game server integration",
+  "private": false,
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "hyve",
+    "game",
+    "sdk",
+    "multiplayer",
+    "realtime",
+    "gaming",
+    "platform"
+  ],
+  "author": "Hyve",
+  "homepage": "https://docs.hyve.gg",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hyve/web-mono.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/hyve/web-mono/issues"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "ethers": "^6.13.7",
+    "uuid": "^10.0.0"
+  },
+  "devDependencies": {
+    "@types/minimatch": "^5.1.2",
+    "@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"
+  },
+  "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 restricted",
+    "publish:dry-run": "pnpm publish --dry-run --access restricted --no-git-checks"
+  }
+}