@hyve-sdk/js 1.5.0 → 2.1.0

package/README.md

@@ -1,329 +1,139 @@
 # @hyve-sdk/js
 
-TypeScript SDK for web3 authentication and game integration, providing secure signature verification and utility functions.
+The core SDK for integrating with the Hyve platform, providing authentication, telemetry, persistent storage, billing, ads, and native bridge capabilities for web games.
 
-## Installation
+## Setup
 
-```bash
-bun add @hyve-sdk/js
-# or
-npm install @hyve-sdk/js
-# or
-pnpm add @hyve-sdk/js
-```
-
-## Features
-
-- **Web3 Authentication**: EVM signature validation and verification
-- **Modern & Legacy Token Support**: Dual authentication token formats
-- **JWT Authentication**: Support for JWT tokens passed via URL parameters
-- **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
-- **Billing Integration**: Unified billing for web (Stripe) and native (In-App Purchases) platforms
-- **Ads Integration**: Google H5 Games Ads support (disabled by default)
-- **Native Bridge**: Type-safe communication with React Native WebView apps
-- **Logger**: Environment-aware logging system with configurable log levels
-- **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 including authentication, telemetry, and API calls.
-
-```typescript
-import { HyveClient } from "@hyve-sdk/js";
+Load the SDK via script tag — no npm install required.
 
-// Initialize client
-// Environment (dev/prod) is automatically detected from the parent page URL
-const client = new HyveClient();
-
-// 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());
-}
-```
-
-**Environment Detection:**
-The SDK automatically detects whether to use dev or prod environment by checking the parent page URL:
-- **Dev**: `marvin.dev.hyve.gg` or `dev.hyve.gg`
-- **Prod**: `marvin.hyve.gg` or `hyve.gg`
-
-You can optionally override this for testing:
-```typescript
-// Only use for local testing - NOT for production code
-const client = new HyveClient({
-  isDev: true,                  // Force dev mode for testing
-  apiBaseUrl: 'https://...'     // Optional custom API URL
-});
-```
-
-### Authentication Utilities
-
-#### Parse URL Parameters
-Extract authentication and game parameters from URL:
-
-```typescript
-import { parseUrlParams } from "@hyve-sdk/js";
-
-const params = parseUrlParams(window.location.search);
-// Returns:
-// {
-//   signature: string,
-//   message: string,
-//   gameStartTab: string,
-//   hyveToken: string,
-//   platform: string,
-//   hyveAccess: string,   // JWT token
-//   gameId: string        // Game identifier
-// }
+```html
+<script src="https://package.hyve.gg/hyve-sdk.global.js"></script>
 ```
 
-#### Verify Authentication
-Unified verification supporting both modern and legacy tokens:
-
-```typescript
-import { verifyAuthentication } from "@hyve-sdk/js";
+All exports are available on `window.HyveSDK`:
 
-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'
-}
+```js
+const { HyveClient, NativeBridge, NativeMessageType } = window.HyveSDK;
 ```
 
-#### Modern Token Verification (Hyve Token)
-Verify modern authentication tokens with expiration:
+## Authentication
 
-```typescript
-import { verifyHyveToken } from "@hyve-sdk/js";
+Authenticate using the `hyve-access` JWT passed in the URL:
 
-// 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/js";
-
-// Method 1: Verify message with embedded metadata
-const address = handleVerifyMessage(signature, message);
-
-// Method 2: Simple signature validation
-const isValid = validateSignature(signature, message, userId);
+https://your-game.com?hyve-access=eyJhbGci...&game-id=my-game
 ```
 
-### Security Utilities
-
-#### Domain Validation
-Check if current domain is allowed:
-
-```typescript
-import { isDomainAllowed } from "@hyve-sdk/js";
+```js
+const { HyveClient } = window.HyveSDK;
 
-// 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
-);
+const client = new HyveClient();
+await client.authenticateFromUrl(window.location.search);
 
-// Note: localhost is always allowed
+console.log('User ID:', client.getUserId());
+console.log('Game ID:', client.getGameId());
 ```
 
-### Utility Functions
-
-#### UUID Generation
-Generate random UUID v4:
+**Environment Detection:**
+The SDK automatically detects dev vs prod by checking the parent page URL:
+- **Dev**: `marvin.dev.hyve.gg` or `dev.hyve.gg`
+- **Prod**: `marvin.hyve.gg` or `hyve.gg`
 
-```typescript
-import { generateUUID } from "@hyve-sdk/js";
+## Telemetry & Analytics
 
-const id = generateUUID();
-```
+Track user actions and game events:
 
-## Telemetry & Analytics
+```js
+const { HyveClient } = window.HyveSDK;
 
-### Send Telemetry Events
-Track user actions and game events using JWT authentication:
+const client = new HyveClient();
+await client.authenticateFromUrl(window.location.search);
 
-```typescript
-// 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)
-  {                                // Event details - auto-stringified (optional)
+  'game',       // location
+  'player',     // category
+  'action',     // action
+  'combat',     // sub-category (optional)
+  'attack',     // sub-action (optional)
+  {             // event details (optional)
     button: 'attack-btn',
-    screenPosition: { x: 100, y: 200 },
     damage: 100,
     targetId: 'enemy-123',
-    weaponType: 'sword',
-    level: 3
-  },
-  'web-chrome'                     // Platform ID (optional)
+  }
 );
 ```
 
 **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` are auto-stringified to JSON
-- Validates `event_details` is valid JSON before sending (returns false if invalid)
-- All events tied to authenticated user identity
-
-## API Integration
-
-### JWT Authentication
-The SDK supports JWT tokens and game IDs passed via URL parameters:
-
-```typescript
-// URL: https://game.com?hyve-access=your-jwt-token&game-id=my-game
+- `hyve-access` JWT in URL
+- `game-id` in URL or JWT
+- User authenticated via `authenticateFromUrl`
 
-// Authenticate extracts JWT and game ID automatically
-await client.authenticateFromUrl();
+See [docs/TELEMETRY.md](./docs/TELEMETRY.md) for validation rules and examples.
 
-// Check availability
-if (client.hasJwtToken()) {
-  console.log('JWT token:', client.getJwtToken());
-  console.log('Game ID:', client.getGameId());
-}
-```
+## API Integration
 
 ### Generic API Calls
-Make authenticated API requests:
 
-```typescript
+```js
 // GET request
 const userData = await client.callApi('/api/v1/user');
 
-// POST request with body
+// POST request
 const result = await client.callApi('/api/v1/game/score', {
   method: 'POST',
   body: JSON.stringify({ score: 1000 })
 });
-
-// With TypeScript typing
-interface UserData {
-  id: string;
-  username: string;
-}
-const user = await client.callApi<UserData>('/api/v1/user');
 ```
 
-### Inventory Management
-
-#### Get User Inventory
-Retrieve all inventory items:
+### Inventory
 
-```typescript
+```js
 const inventory = await client.getInventory();
-
 console.log(`Total items: ${inventory.total_count}`);
 inventory.items.forEach(item => {
   console.log(`${item.item_type}: ${item.quantity}x`);
 });
-```
-
-**Response Type:**
-```typescript
-interface Inventory {
-  items: InventoryItem[];
-  total_count: number;
-}
 
-interface InventoryItem {
-  id: string;
-  user_id: string;
-  item_type: string;
-  item_id: string;
-  quantity: number;
-  metadata?: Record<string, any>;
-  created_at: string;
-  updated_at: string;
-}
+const item = await client.getInventoryItem('item-id-123');
 ```
 
-#### Get Specific Inventory Item
-Fetch details for a single item:
-
-```typescript
-const item = await client.getInventoryItem('item-id-123');
+## Ads Integration
 
-console.log(`Item: ${item.item_type}`);
-console.log(`Quantity: ${item.quantity}`);
-if (item.metadata) {
-  console.log('Metadata:', item.metadata);
-}
-```
+Ads are **disabled by default** — must be explicitly enabled.
 
-**API Endpoints:**
-- `GET /api/v1/inventory` - Get all inventory items
-- `GET /api/v1/inventory/:id` - Get specific item
+### Prerequisites
 
-## Ads Integration
+Add the Google H5 Games Ads SDK to your HTML before the Hyve SDK:
 
-The SDK includes support for Google H5 Games Ads. **Ads are disabled by default** and must be explicitly enabled in the configuration.
+```html
+<script async src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"></script>
+<script>
+  window.adBreak = window.adBreak || function(o) {
+    (window.adsbygoogle = window.adsbygoogle || []).push(o);
+  };
+  window.adConfig = window.adConfig || function(o) {
+    (window.adsbygoogle = window.adsbygoogle || []).push(o);
+  };
+</script>
+<script src="https://package.hyve.gg/hyve-sdk.global.js"></script>
+```
 
 ### Quick Start
 
-```typescript
-import { HyveClient } from "@hyve-sdk/js";
+```js
+const { HyveClient } = window.HyveSDK;
 
-// Enable ads in initial config
 const client = new HyveClient({
   ads: {
-    enabled: true,  // Must be set to true
-    sound: 'on',
-    debug: true,
-    onBeforeAd: (type) => {
-      console.log('Pausing game for ad:', type);
-      game.pause();
-    },
-    onAfterAd: (type) => {
-      console.log('Resuming game after ad');
-      game.resume();
-    },
-    onRewardEarned: () => {
-      console.log('User earned reward!');
-      player.coins += 100;
-    }
+    enabled: true,
+    onBeforeAd: (type) => game.pause(),
+    onAfterAd: (type) => game.resume(),
+    onRewardEarned: () => { player.coins += 100; }
   }
 });
 
-// Show different ad types
+await client.authenticateFromUrl(window.location.search);
+
 const result = await client.showAd('rewarded');
 if (result.success) {
   console.log('User watched the ad!');
@@ -333,91 +143,38 @@ await client.showAd('interstitial');  // Between levels
 await client.showAd('preroll');       // Game start
 ```
 
-### Prerequisites
-
-Add the Google H5 Games Ads SDK to your HTML:
-
-```html
-<script async src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"></script>
-<script>
-  window.adBreak = window.adBreak || function(o) {
-    (window.adsbygoogle = window.adsbygoogle || []).push(o);
-  };
-  window.adConfig = window.adConfig || function(o) {
-    (window.adsbygoogle = window.adsbygoogle || []).push(o);
-  };
-</script>
-```
-
 ### Ad Types
 
 | Type | Use Case |
 |------|----------|
-| `rewarded` | User watches full ad for reward (coins, lives, etc.) |
+| `rewarded` | User watches full ad for reward |
 | `interstitial` | Between levels or game screens |
 | `preroll` | Before game starts |
 
-### Configuration
-
-```typescript
-interface AdConfig {
-  enabled?: boolean;           // Enable/disable ads (default: false)
-  sound?: 'on' | 'off';       // Sound setting (default: 'on')
-  debug?: boolean;             // Enable debug logging (default: false)
-  onBeforeAd?: (type) => void; // Called before ad shows
-  onAfterAd?: (type) => void;  // Called after ad finishes
-  onRewardEarned?: () => void; // Called when user earns reward
-}
-```
-
-### Methods
-
-```typescript
-// Configure ads after initialization
-client.configureAds({ enabled: true, sound: 'off' });
-
-// Show an ad
-const result = await client.showAd('rewarded');
-
-// Check status
-client.areAdsEnabled();  // Boolean
-client.areAdsReady();    // Boolean
-```
-
-See [docs/ads.md](./docs/ads.md) for detailed documentation and examples.
-
-**Requirements:**
-- JWT token must be available (via `hyve-access` URL parameter)
-- User must be authenticated
+See [docs/ads.md](./docs/ads.md) for detailed documentation.
 
 ## Billing Integration
 
-The SDK includes unified billing support for both web (Stripe) and native (In-App Purchases) platforms. Billing automatically detects the platform and routes to the appropriate payment method.
+Unified billing for web (Stripe) and native (In-App Purchases). Platform is detected automatically.
 
 ### Quick Start
 
-```typescript
-import { HyveClient } from "@hyve-sdk/js";
+```js
+const { HyveClient } = window.HyveSDK;
 
-// Enable billing in initial config
 const client = new HyveClient({
   billing: {
-    stripePublishableKey: 'pk_test_...',
-    checkoutUrl: 'https://your-api.com',
+    stripePublishableKey: 'pk_live_...',
+    checkoutUrl: 'https://checkout-api.hyve.gg',
   }
 });
 
-// Authenticate user
 await client.authenticateFromUrl(window.location.search);
-
-// Initialize billing (uses client's userId and gameId automatically)
 const initialized = await client.initializeBilling();
 
 if (initialized && client.isBillingAvailable()) {
-  // Set up purchase callbacks
   client.onPurchaseComplete((result) => {
     console.log('Purchase successful!', result.transactionId);
-    // Refresh inventory
     client.getInventory().then(inv => console.log('Updated inventory:', inv));
   });
 
@@ -425,409 +182,166 @@ if (initialized && client.isBillingAvailable()) {
     console.error('Purchase failed:', result.error?.message);
   });
 
-  // Get available products
   const products = await client.getBillingProducts();
-  console.log('Available products:', products);
-
-  // Purchase a product
-  await client.purchaseProduct('price_1234', {
-    elementId: 'stripe-checkout-element' // For web platform
-  });
+  await client.purchaseProduct('price_1234');
 }
 ```
 
 ### Platform Support
 
-The SDK automatically detects the platform and uses the appropriate billing method:
-
-| Platform | Payment Method | Requirements |
-|----------|---------------|--------------|
-| Web | Stripe Embedded Checkout | Stripe publishable key |
-| Native (iOS/Android) | In-App Purchases | Native app integration |
+| Platform | Payment Method | Detection |
+|----------|---------------|-----------|
+| Web | Stripe Embedded Checkout | Default (no ReactNativeWebView) |
+| Native (iOS/Android) | In-App Purchases | `ReactNativeWebView` in window |
 
 ### Prerequisites
 
-For web platform, add a container element for Stripe checkout:
+For web, add a container element for the Stripe checkout UI:
 
 ```html
 <div id="stripe-checkout-element"></div>
 ```
 
-Stripe.js will be loaded automatically by the SDK.
-
-For native platform, ensure the mobile app implements the Native Bridge billing messages.
-
-### Configuration
-
-```typescript
-interface BillingConfig {
-  stripePublishableKey?: string;  // Stripe key for web (required for web)
-  checkoutUrl?: string;           // API endpoint for checkout
-  gameId?: number;                // Game identifier
-  userId?: string;                // User identifier
-}
-```
-
-Note: When using billing through HyveClient, `userId` and `gameId` are automatically populated from the authenticated user.
-
-### Methods
-
-```typescript
-// Configure billing after initialization
-client.configureBilling({
-  stripePublishableKey: 'pk_live_...',
-  checkoutUrl: 'https://api.example.com'
-});
-
-// Initialize billing
-await client.initializeBilling();
-
-// Check platform and availability
-const platform = client.getBillingPlatform();  // 'web' | 'native' | 'unknown'
-const available = client.isBillingAvailable(); // Boolean
-
-// Get products
-const products = await client.getBillingProducts();
-
-// Purchase a product
-const result = await client.purchaseProduct(productId, {
-  elementId: 'stripe-checkout-element'  // Optional, defaults to 'stripe-checkout-element'
-});
-
-// Set up callbacks
-client.onPurchaseComplete((result) => {
-  console.log('Success!', result);
-});
-
-client.onPurchaseError((result) => {
-  console.error('Failed:', result.error);
-});
-
-// Optional: Listen to billing logs
-client.onBillingLog((level, message, data) => {
-  console.log(`[${level}] ${message}`, data);
-});
-
-// Clean up checkout UI
-client.unmountBillingCheckout();
-```
-
-### Product Interface
-
-```typescript
-interface BillingProduct {
-  productId: string;        // Product/price ID
-  title: string;            // Product name
-  description: string;      // Product description
-  price: number;            // Price in dollars (e.g., 9.99)
-  localizedPrice: string;   // Formatted price (e.g., "$9.99")
-  currency: string;         // Currency code (e.g., "USD")
-}
-```
-
-### Purchase Result
-
-```typescript
-interface PurchaseResult {
-  success: boolean;
-  productId: string;
-  transactionId?: string;
-  transactionDate?: string;
-  error?: {
-    code: string;
-    message: string;
-  };
-}
-```
-
-### Complete Example with Telemetry
-
-```typescript
-const client = new HyveClient({
-  billing: {
-    stripePublishableKey: process.env.VITE_STRIPE_KEY,
-    checkoutUrl: process.env.VITE_CHECKOUT_URL,
-  }
-});
-
-// Authenticate
-await client.authenticateFromUrl();
-
-// Initialize billing
-await client.initializeBilling();
-
-// Set up callbacks with telemetry
-client.onPurchaseComplete((result) => {
-  // Send success telemetry
-  client.sendTelemetry(
-    'shop',
-    'purchase',
-    'complete',
-    'success',
-    null,
-    { productId: result.productId, transactionId: result.transactionId }
-  );
-
-  // Refresh inventory
-  client.getInventory();
-});
-
-client.onPurchaseError((result) => {
-  // Send error telemetry
-  client.sendTelemetry(
-    'shop',
-    'purchase',
-    'error',
-    'failed',
-    null,
-    {
-      productId: result.productId,
-      errorCode: result.error?.code,
-      errorMessage: result.error?.message
-    }
-  );
-});
-
-// Get and display products
-const products = await client.getBillingProducts();
-```
-
-See [docs/examples/billing-with-client-example.ts](./docs/examples/billing-with-client-example.ts) for detailed examples including React components and Phaser integration.
-
-**Requirements:**
-- JWT token must be available (via `hyve-access` URL parameter)
-- User must be authenticated
-- Game ID must be available (via `game-id` URL parameter or JWT)
-- For web: Stripe publishable key required
-- For native: Mobile app must implement Native Bridge billing integration
+See [docs/BILLING_INTEGRATION.md](./docs/BILLING_INTEGRATION.md) for full documentation and examples.
 
 ## Native Bridge (React Native WebView)
 
-Provides type-safe bidirectional communication between your web application and the React Native mobile app.
+Type-safe bidirectional communication between your web game and a React Native mobile app.
 
 ### Quick Start
 
-```typescript
-import { NativeBridge, NativeMessageType } from "@hyve-sdk/js";
+```js
+const { NativeBridge } = window.HyveSDK;
 
-// Initialize on app start
 if (NativeBridge.isNativeContext()) {
   NativeBridge.initialize();
 }
 ```
 
-### Check IAP Availability
+### IAP Availability
 
-Request information about In-App Purchase availability:
-
-```typescript
-// Register response handler
-NativeBridge.on("IAP_AVAILABILITY_RESULT", (payload) => {
+```js
+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
+    console.log('IAP available on platform:', payload.platform);
   }
 });
 
-// Send request
 NativeBridge.checkIAPAvailability();
 ```
 
-### Request Push Notifications
-
-Request notification permissions from the native app:
+### Push Notifications
 
-```typescript
-// Register response handlers
-NativeBridge.on("PUSH_PERMISSION_GRANTED", (payload) => {
-  console.log("Push notifications enabled");
-  console.log("Token:", payload?.token);
+```js
+NativeBridge.on('PUSH_PERMISSION_GRANTED', (payload) => {
+  console.log('Token:', payload?.token);
 });
 
-NativeBridge.on("PUSH_PERMISSION_DENIED", () => {
-  console.log("Push notifications disabled");
+NativeBridge.on('PUSH_PERMISSION_DENIED', () => {
+  console.log('Permission denied');
 });
 
-// Send request
 NativeBridge.requestNotificationPermission();
 ```
 
-### Send Custom Messages
+### Custom Messages
 
-Send custom messages to the native app:
+```js
+NativeBridge.send('GAME_EVENT', { action: 'level_complete', level: 3 });
 
-```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);
+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
+- `NativeBridge.isNativeContext()` — Check if running in React Native WebView
+- `NativeBridge.initialize()` — Start message listener
+- `NativeBridge.send(type, payload?)` — Send message to native
+- `NativeBridge.on(type, handler)` — Register message handler
+- `NativeBridge.off(type)` — Remove message handler
+- `NativeBridge.clearHandlers()` — Remove all handlers
+- `NativeBridge.checkIAPAvailability()` — Request IAP availability
+- `NativeBridge.requestNotificationPermission()` — Request notification permission
 
-For complete documentation, see [docs/NATIVE_BRIDGE.md](./docs/NATIVE_BRIDGE.md).
+See [docs/NATIVE_BRIDGE.md](./docs/NATIVE_BRIDGE.md) for full documentation.
 
 ## Logger
 
-The SDK includes a built-in logger that's automatically enabled in development environments.
-
-### Quick Start
-
-```typescript
-import { logger } from "@hyve-sdk/js";
-
-logger.debug("Debug information", { data: "value" });
-logger.info("Informational message");
-logger.warn("Warning message");
-logger.error("Error message", error);
-```
-
-### Configuration
+```js
+const { logger } = window.HyveSDK;
 
-**Automatic Behavior:**
-- **Development** (`NODE_ENV !== 'production'`): Logging enabled by default
-- **Production** (`NODE_ENV === 'production'`): Logging disabled by default
-
-**Browser Override:**
-```javascript
-// Enable specific log levels
-localStorage.setItem('HYVE_SDK_LOG_LEVEL', 'error,warn');
-```
-
-**Node.js Override:**
-```bash
-HYVE_SDK_LOG_LEVEL=error,warn node app.js
-```
-
-**Programmatic Control:**
-```typescript
-import { Logger } from "@hyve-sdk/js";
-
-const logger = new Logger();
-logger.setLevels(['error', 'warn']);
-```
-
-### Child Loggers
-
-Create namespaced loggers for different parts of your application:
-
-```typescript
-import { logger } from "@hyve-sdk/js";
+logger.debug('Debug info', { data: 'value' });
+logger.info('Informational message');
+logger.warn('Warning message');
+logger.error('Error message', error);
 
+// Namespaced child loggers
 const gameLogger = logger.child('Game');
 gameLogger.info('Game started');
 // Output: [Hyve SDK] [Game] [INFO] [timestamp] Game started
-
-const uiLogger = logger.child('UI');
-uiLogger.debug('Button clicked');
-// Output: [Hyve SDK] [UI] [DEBUG] [timestamp] Button clicked
 ```
 
-### Features
-
-- **Automatic environment detection**: Enables/disables based on NODE_ENV
-- **Configurable log levels**: debug, info, warn, error
-- **Timestamps**: All logs include ISO 8601 timestamps
-- **Prefixed output**: All logs prefixed with `[Hyve SDK]`
-- **Child loggers**: Create namespaced loggers for different modules
-- **Browser storage**: Log level persists in localStorage
+**Log level override (browser):**
+```js
+localStorage.setItem('HYVE_SDK_LOG_LEVEL', 'error,warn');
+```
 
 ## Client Methods Reference
 
 ### Authentication
-- `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
-- `logout()` - Clear user authentication
-- `reset()` - Reset client state with new session
-
-### API Calls
-- `callApi<T>(endpoint, options?)` - Generic authenticated API call
-- `getInventory()` - Get user's inventory
-- `getInventoryItem(itemId)` - Get specific inventory item
+- `authenticateFromUrl(urlParams)` — Extract JWT and game ID from URL, authenticate user
+- `getUserId()` — Authenticated user ID
+- `getSessionId()` — Unique session ID
+- `getGameId()` — Game ID from URL or JWT
+- `isUserAuthenticated()` — Check if authenticated
+- `hasJwtToken()` — Check if JWT available
+- `getJwtToken()` — Get JWT string
+- `logout()` — Clear authentication
+- `reset()` — Reset client state
+
+### API
+- `callApi<T>(endpoint, options?)` — Authenticated API call
+- `getInventory()` — Get user inventory
+- `getInventoryItem(itemId)` — Get specific inventory item
 
 ### Telemetry
-- `sendTelemetry(location, category, action, subCategory?, subAction?, details?, platformId?)` - Send JWT-authenticated analytics event (uses game ID from URL)
-- `updateTelemetryConfig(config)` - Update telemetry settings
+- `sendTelemetry(location, category, action, subCategory?, subAction?, details?)` — Send analytics event
+- `updateTelemetryConfig(config)` — Update telemetry settings
 
 ### Ads
-- `configureAds(config)` - Configure ads service
-- `showAd(type)` - Show an ad ('rewarded', 'interstitial', or 'preroll')
-- `areAdsEnabled()` - Check if ads are enabled
-- `areAdsReady()` - Check if ads are ready to show
-
-### Configuration
-- `getApiBaseUrl()` - Get current API base URL
-- `updateTelemetryConfig(config)` - Update client configuration
-
-## 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()`
+- `configureAds(config)` — Configure ads service
+- `showAd(type)` — Show an ad (`'rewarded'` | `'interstitial'` | `'preroll'`)
+- `areAdsEnabled()` — Check if ads are enabled
+- `areAdsReady()` — Check if ads are ready
+
+### Billing
+- `configureBilling(config)` — Configure billing service
+- `initializeBilling()` — Initialize billing (resolves platform automatically)
+- `getBillingPlatform()` — `'web'` | `'native'` | `'unknown'`
+- `isBillingAvailable()` — Check if billing is ready
+- `getBillingProducts()` — Fetch available products
+- `purchaseProduct(productId, options?)` — Initiate purchase
+- `onPurchaseComplete(callback)` — Register purchase success handler
+- `onPurchaseError(callback)` — Register purchase error handler
+- `unmountBillingCheckout()` — Clean up Stripe checkout UI
 
 ## 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
+- Never expose secret keys in game code
+- Always validate receipts server-side
+- Use HTTPS for all requests
+- Don't trust client-reported prices
+- Verify user authentication before crediting purchases
 
-## TypeScript Support
+## Build Output
 
-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`)
+| Format | File | Use |
+|--------|------|-----|
+| CJS | `dist/index.js` | Node.js / bundler |
+| ESM | `dist/index.mjs` | Bundler (tree-shakeable) |
+| IIFE | `dist/hyve-sdk.global.js` | CDN / script tag |
 
 ## Development
 
@@ -847,16 +361,13 @@ bun run build
 
 ## Documentation
 
-For complete documentation and examples, visit [https://docs.hyve.gg](https://docs.hyve.gg)
-
-### Additional Guides
-
-- [Telemetry Guide](./docs/TELEMETRY.md) - Best practices, validation rules, and examples for event tracking
-- [Billing Integration](./docs/BILLING_INTEGRATION.md) - Platform-aware billing with Stripe and In-App Purchases
-- [Billing Migration Guide](./docs/BILLING_MIGRATION_GUIDE.md) - Upgrading from older billing implementations
-- [Ads Integration](./docs/ads.md) - Google H5 Games Ads integration
-- [Native Bridge](./docs/NATIVE_BRIDGE.md) - React Native WebView communication
+- [Telemetry Guide](./docs/TELEMETRY.md)
+- [Billing Integration](./docs/BILLING_INTEGRATION.md)
+- [Billing Migration Guide](./docs/BILLING_MIGRATION_GUIDE.md)
+- [Ads Integration](./docs/ads.md)
+- [Native Bridge](./docs/NATIVE_BRIDGE.md)
+- [Platform-Aware Billing](./docs/PLATFORM_AWARE_BILLING.md)
 
 ## License
 
-MIT
+MIT