@hyve-sdk/js 1.5.1 → 2.1.1

package/README.md

@@ -1,862 +1,388 @@
 # @hyve-sdk/js
 
-TypeScript SDK for web3 authentication and game integration, providing secure signature verification and utility functions.
+TypeScript SDK for integrating games with the Hyve platform. Provides authentication, telemetry, persistent storage, ads, billing, and native bridge capabilities.
 
 ## Installation
 
 ```bash
-bun add @hyve-sdk/js
-# or
-npm install @hyve-sdk/js
-# or
 pnpm add @hyve-sdk/js
 ```
 
-## Features
+## Quick Start
 
-- **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
+```ts
 import { HyveClient } from "@hyve-sdk/js";
 
-// Initialize client
-// Environment (dev/prod) is automatically detected from the parent page URL
+// Authentication is automatic — the SDK reads hyve-access and game-id from the 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());
-}
+console.log("User ID:", client.getUserId());
+console.log("Game ID:", client.getGameId());
+console.log("Authenticated:", client.isUserAuthenticated());
 ```
 
-**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`
+The SDK reads authentication from URL parameters automatically during construction:
 
-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
-// }
+https://your-game.com?hyve-access=eyJhbGci...&game-id=my-game
 ```
 
-#### Verify Authentication
-Unified verification supporting both modern and legacy tokens:
-
-```typescript
-import { verifyAuthentication } from "@hyve-sdk/js";
-
-const result = verifyAuthentication({
-  hyveToken: params.hyveToken,    // Modern token format
-  signature: params.signature,     // Legacy format
-  message: params.message          // Legacy format
-});
+**Environment detection** happens automatically from the parent page URL (games run in iframes):
+- Dev: `marvin.dev.hyve.gg` or `dev.hyve.gg`
+- Prod: `marvin.hyve.gg` or `hyve.gg`
+- Override with `isDev` in config for local testing only
 
-if (result.isValid) {
-  console.log('Authenticated address:', result.address);
-  console.log('Auth method used:', result.method); // 'modern' or 'legacy'
-}
-```
+## React Integration
 
-#### Modern Token Verification (Hyve Token)
-Verify modern authentication tokens with expiration:
+Import from `@hyve-sdk/js/react` for the React provider and hook:
 
-```typescript
-import { verifyHyveToken } from "@hyve-sdk/js";
+```tsx
+import { HyveSdkProvider, useHyveSdk } from "@hyve-sdk/js/react";
 
-// Token format: signature.address.randomBase64.timestamp
-const address = verifyHyveToken(hyveToken, 600); // 600 seconds max age
-if (address) {
-  console.log('Valid token for address:', address);
+function App() {
+  return (
+    <HyveSdkProvider config={{ isDev: true }}>
+      <Game />
+    </HyveSdkProvider>
+  );
 }
-```
-
-#### 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);
-```
-
-### Security Utilities
-
-#### Domain Validation
-Check if current domain is allowed:
 
-```typescript
-import { isDomainAllowed } from "@hyve-sdk/js";
+function Game() {
+  const sdk = useHyveSdk();
 
-// 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 handleScore = () => {
+    sdk.sendTelemetry("game", "player", "score_submitted", null, null, { score: 1000 });
+  };
 
-// Note: localhost is always allowed
+  return <button onClick={handleScore}>Submit Score</button>;
+}
 ```
 
-### Utility Functions
-
-#### UUID Generation
-Generate random UUID v4:
+You can also pass a pre-created client:
 
-```typescript
-import { generateUUID } from "@hyve-sdk/js";
+```tsx
+const client = new HyveClient({ isDev: true });
 
-const id = generateUUID();
+<HyveSdkProvider client={client}>
+  <App />
+</HyveSdkProvider>
 ```
 
-## Telemetry & Analytics
-
-### Send Telemetry Events
-Track user actions and game events using JWT authentication:
+## Telemetry
 
-```typescript
-// Send a user-level telemetry event
-// Game ID is automatically extracted from 'game-id' URL parameter
+```ts
 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)
-    button: 'attack-btn',
-    screenPosition: { x: 100, y: 200 },
+  "game",        // location
+  "player",      // category
+  "action",      // action
+  "combat",      // sub-category (optional)
+  "attack",      // sub-action (optional)
+  {              // event details (optional)
     damage: 100,
-    targetId: 'enemy-123',
-    weaponType: 'sword',
-    level: 3
-  },
-  'web-chrome'                     // Platform ID (optional)
+    targetId: "enemy-123",
+  }
 );
 ```
 
-**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)
+Requires a valid `hyve-access` JWT and `game-id` in the URL.
 
-**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
+## Persistent Game Data
 
-**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
+Save and retrieve game data with either cloud (default) or local storage:
 
-## API Integration
+```ts
+// Save a value
+await client.saveGameData("player_level", 5);
+await client.saveGameData("settings", { volume: 0.8, fullscreen: true });
 
-### JWT Authentication
-The SDK supports JWT tokens and game IDs passed via URL parameters:
+// Get a value
+const item = await client.getGameData("player_level");
+console.log(item?.value); // 5
 
-```typescript
-// URL: https://game.com?hyve-access=your-jwt-token&game-id=my-game
+// Batch save
+await client.batchSaveGameData([
+  { key: "coins", value: 1200 },
+  { key: "lives", value: 3 },
+]);
 
-// Authenticate extracts JWT and game ID automatically
-await client.authenticateFromUrl();
+// Batch get
+const items = await client.getMultipleGameData(["coins", "lives"]);
 
-// Check availability
-if (client.hasJwtToken()) {
-  console.log('JWT token:', client.getJwtToken());
-  console.log('Game ID:', client.getGameId());
-}
+// Delete
+await client.deleteGameData("temp_key");
+await client.deleteMultipleGameData(["key1", "key2"]);
 ```
 
-### Generic API Calls
-Make authenticated API requests:
-
-```typescript
-// GET request
-const userData = await client.callApi('/api/v1/user');
-
-// POST request with body
-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:
-
-```typescript
-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;
-}
-```
+### Storage Modes
 
-#### Get Specific Inventory Item
-Fetch details for a single item:
+```ts
+// Set mode at construction
+const client = new HyveClient({ storageMode: "local" });
 
-```typescript
-const item = await client.getInventoryItem('item-id-123');
+// Or override per-call
+await client.saveGameData("key", "value", "local");
+await client.getGameData("key", "cloud");
 
-console.log(`Item: ${item.item_type}`);
-console.log(`Quantity: ${item.quantity}`);
-if (item.metadata) {
-  console.log('Metadata:', item.metadata);
-}
+// Change mode at runtime
+client.configureStorage("cloud");
+console.log(client.getStorageMode()); // "cloud"
 ```
 
-**API Endpoints:**
-- `GET /api/v1/inventory` - Get all inventory items
-- `GET /api/v1/inventory/:id` - Get specific item
-
-## Ads Integration
-
-The SDK includes support for Google H5 Games Ads. **Ads are disabled by default** and must be explicitly enabled in the configuration.
+| Mode | Description |
+|------|-------------|
+| `cloud` | Synced to backend API (default) |
+| `local` | Browser `localStorage`, device-only |
 
-### Quick Start
+## Ads
 
-```typescript
-import { HyveClient } from "@hyve-sdk/js";
+Ads are disabled by default and must be explicitly configured.
 
-// Enable ads in initial config
+```ts
 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
-const result = await client.showAd('rewarded');
+const result = await client.showAd("rewarded");
 if (result.success) {
-  console.log('User watched the ad!');
+  console.log("User watched the ad");
 }
 
-await client.showAd('interstitial');  // Between levels
-await client.showAd('preroll');       // Game start
+await client.showAd("interstitial");  // between levels
+await client.showAd("preroll");       // game start
 ```
 
-### Prerequisites
-
-Add the Google H5 Games Ads SDK to your HTML:
+| Ad Type | Use Case |
+|---------|----------|
+| `rewarded` | User watches full ad for a reward |
+| `interstitial` | Between levels or game screens |
+| `preroll` | Before the game starts |
 
-```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>
-```
+The SDK automatically routes ad calls through the appropriate platform SDK (CrazyGames, Playgama, or the default Google H5 Ads SDK) based on the current domain.
 
-### Ad Types
+## Platform Integrations
 
-| Type | Use Case |
-|------|----------|
-| `rewarded` | User watches full ad for reward (coins, lives, etc.) |
-| `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
-}
-```
+### CrazyGames
 
-### Methods
+When running on CrazyGames, the SDK auto-initializes the CrazyGames SDK and routes ads through it. Use these additional lifecycle methods:
 
-```typescript
-// Configure ads after initialization
-client.configureAds({ enabled: true, sound: 'off' });
+```ts
+// Call when gameplay begins (required by CrazyGames policy)
+await client.gameplayStart();
 
-// Show an ad
-const result = await client.showAd('rewarded');
+// Call when gameplay stops (paused, died, menu, etc.)
+await client.gameplayStop();
 
-// Check status
-client.areAdsEnabled();  // Boolean
-client.areAdsReady();    // Boolean
+// Trigger a celebration effect on the CrazyGames website
+await client.happytime();
 ```
 
-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
-
-## Billing Integration
+### Playgama
 
-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.
+When running on Playgama, the SDK auto-initializes the Playgama Bridge and routes ads through it. No additional setup required.
 
-### Quick Start
+## Billing
 
-```typescript
-import { HyveClient } from "@hyve-sdk/js";
+Billing supports web (Stripe) and native (In-App Purchases) — platform is detected automatically.
 
-// Enable billing in initial config
+```ts
 const client = new HyveClient({
   billing: {
-    stripePublishableKey: 'pk_test_...',
-    checkoutUrl: 'https://your-api.com',
-  }
+    stripePublishableKey: "pk_live_...",
+  },
 });
 
-// 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
+if (client.isBillingAvailable()) {
   client.onPurchaseComplete((result) => {
-    console.log('Purchase successful!', result.transactionId);
-    // Refresh inventory
-    client.getInventory().then(inv => console.log('Updated inventory:', inv));
+    console.log("Purchase successful:", result.transactionId);
   });
 
   client.onPurchaseError((result) => {
-    console.error('Purchase failed:', result.error?.message);
+    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 |
-
-### 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,
-  }
-});
+| Platform | Payment Method | Detection |
+|----------|---------------|-----------|
+| Web | Stripe Embedded Checkout | Default |
+| Native iOS/Android | In-App Purchases | `ReactNativeWebView` in window |
 
-// 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 }
-  );
+## Native Bridge
 
-  // Refresh inventory
-  client.getInventory();
-});
+Type-safe bidirectional communication between your web game and a React Native WebView host.
 
-client.onPurchaseError((result) => {
-  // Send error telemetry
-  client.sendTelemetry(
-    'shop',
-    'purchase',
-    'error',
-    'failed',
-    null,
-    {
-      productId: result.productId,
-      errorCode: result.error?.code,
-      errorMessage: result.error?.message
-    }
-  );
-});
+```ts
+import { NativeBridge } from "@hyve-sdk/js";
 
-// 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
-
-## Native Bridge (React Native WebView)
-
-Provides type-safe bidirectional communication between your web application and the React Native mobile app.
-
-### Quick Start
-
-```typescript
-import { NativeBridge, NativeMessageType } from "@hyve-sdk/js";
-
-// Initialize on app start
 if (NativeBridge.isNativeContext()) {
   NativeBridge.initialize();
-}
-```
-
-### Check IAP Availability
-
-Request information about In-App Purchase availability:
-
-```typescript
-// Register response handler
-NativeBridge.on("IAP_AVAILABILITY_RESULT", (payload) => {
-  if (payload.available) {
-    console.log("IAP is available on this device");
-    // Show purchase UI
-  } else {
-    console.log("IAP is not available");
-    // Hide purchase features
-  }
-});
-
-// Send request
-NativeBridge.checkIAPAvailability();
-```
-
-### Request Push Notifications
-
-Request notification permissions from the native app:
-
-```typescript
-// Register response handlers
-NativeBridge.on("PUSH_PERMISSION_GRANTED", (payload) => {
-  console.log("Push notifications enabled");
-  console.log("Token:", payload?.token);
-});
-
-NativeBridge.on("PUSH_PERMISSION_DENIED", () => {
-  console.log("Push notifications disabled");
-});
-
-// Send request
-NativeBridge.requestNotificationPermission();
-```
-
-### Send Custom Messages
 
-Send custom messages to the native app:
+  // Listen for IAP availability
+  NativeBridge.on("IAP_AVAILABILITY_RESULT", (payload) => {
+    if (payload.available) {
+      console.log("IAP available on:", payload.platform);
+    }
+  });
+  NativeBridge.checkIAPAvailability();
 
-```typescript
-// Send message with payload
-NativeBridge.send("CUSTOM_EVENT", {
-  action: "open_settings",
-  data: { setting: "notifications" }
-});
+  // Request push notification permission
+  NativeBridge.on("PUSH_PERMISSION_GRANTED", (payload) => {
+    console.log("Token:", payload?.token);
+  });
+  NativeBridge.requestNotificationPermission();
 
-// Listen for custom responses
-NativeBridge.on("CUSTOM_RESPONSE", (payload) => {
-  console.log("Received:", payload);
-});
+  // Send/receive custom messages
+  NativeBridge.send("GAME_EVENT", { action: "level_complete", level: 3 });
+  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 API
 
-- `NativeBridge.isNativeContext()` - Check if running in React Native WebView
-- `NativeBridge.initialize()` - Initialize message listener
-- `NativeBridge.send(type, payload?)` - Send message to native
-- `NativeBridge.on(type, handler)` - Register message handler
-- `NativeBridge.off(type)` - Unregister message handler
-- `NativeBridge.clearHandlers()` - Clear all handlers
-- `NativeBridge.checkIAPAvailability()` - Helper for IAP check
-- `NativeBridge.requestNotificationPermission()` - Helper for notification permission
-
-For complete documentation, see [docs/NATIVE_BRIDGE.md](./docs/NATIVE_BRIDGE.md).
+| Method | Description |
+|--------|-------------|
+| `isNativeContext()` | Check if running in React Native WebView |
+| `initialize()` | Start the message listener |
+| `send(type, payload?)` | Send a message to the native app |
+| `on(type, handler)` | Register a message handler |
+| `off(type)` | Remove a message handler |
+| `clearHandlers()` | Remove all handlers |
+| `checkIAPAvailability()` | Request IAP availability from native |
+| `requestNotificationPermission()` | Request push notification permission |
 
 ## Logger
 
-The SDK includes a built-in logger that's automatically enabled in development environments.
-
-### Quick Start
-
-```typescript
+```ts
 import { logger } from "@hyve-sdk/js";
 
-logger.debug("Debug information", { data: "value" });
+logger.debug("Debug info", { data: "value" });
 logger.info("Informational message");
 logger.warn("Warning message");
 logger.error("Error message", error);
-```
-
-### Configuration
-
-**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
+// Namespaced child logger
+const gameLogger = logger.child("Game");
+gameLogger.info("Game started");
+// Output: [Hyve SDK] [Game] [INFO] [timestamp] Game started
 ```
 
-**Programmatic Control:**
-```typescript
-import { Logger } from "@hyve-sdk/js";
+Override log level in the browser:
 
-const logger = new Logger();
-logger.setLevels(['error', 'warn']);
+```js
+localStorage.setItem("HYVE_SDK_LOG_LEVEL", "error,warn");
 ```
 
-### Child Loggers
-
-Create namespaced loggers for different parts of your application:
+## API Reference
 
-```typescript
-import { logger } from "@hyve-sdk/js";
+### HyveClient Config
 
-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
+```ts
+new HyveClient(config?: {
+  isDev?: boolean;             // Override env detection (local testing only)
+  apiBaseUrl?: string;         // Override API base URL
+  storageMode?: "cloud" | "local";
+  ads?: AdConfig;
+  billing?: BillingConfig;
+})
 ```
 
-### 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
-
-## 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
-
-### Telemetry
-- `sendTelemetry(location, category, action, subCategory?, subAction?, details?, platformId?)` - Send JWT-authenticated analytics event (uses game ID from URL)
-- `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()`
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getUserId()` | `string \| null` | Authenticated user ID |
+| `getGameId()` | `string \| null` | Game ID from URL or JWT |
+| `getSessionId()` | `string` | Unique session ID |
+| `getJwtToken()` | `string \| null` | Raw JWT string |
+| `isUserAuthenticated()` | `boolean` | Whether a user ID was extracted |
+| `hasJwtToken()` | `boolean` | Whether a JWT is present |
+| `logout()` | `void` | Clear auth state |
+| `reset()` | `void` | Clear auth and generate new session ID |
+
+### API
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `callApi<T>(endpoint, options?)` | `Promise<T>` | Authenticated fetch to the Hyve API |
+| `getInventory()` | `Promise<Inventory>` | Get user inventory |
+| `getInventoryItem(itemId)` | `Promise<InventoryItem>` | Get a specific inventory item |
 
-## 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
+### Telemetry
 
-Full TypeScript support with exported types for all utilities and return values.
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `sendTelemetry(location, category, action, subCategory?, subAction?, details?)` | `Promise<boolean>` | Send an analytics event |
+| `updateTelemetryConfig(config)` | `void` | Update telemetry settings at runtime |
 
-## Dependencies
+### Storage
 
-- **ethers**: ^6.13.7 - Ethereum signature verification
-- **uuid**: (peer dependency) - UUID generation
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `saveGameData(key, value, storage?)` | `Promise<SaveGameDataResponse>` | Save a single value |
+| `batchSaveGameData(items, storage?)` | `Promise<SaveGameDataResponse>` | Save multiple values |
+| `getGameData(key, storage?)` | `Promise<GameDataItem \| null>` | Get a single value |
+| `getMultipleGameData(keys, storage?)` | `Promise<GameDataItem[]>` | Get multiple values |
+| `deleteGameData(key, storage?)` | `Promise<boolean>` | Delete a single value |
+| `deleteMultipleGameData(keys, storage?)` | `Promise<number>` | Delete multiple values |
+| `configureStorage(mode)` | `void` | Set default storage mode |
+| `getStorageMode()` | `"cloud" \| "local"` | Get current storage mode |
 
-## Build Configuration
+### Ads
 
-The SDK builds to multiple formats:
-- CommonJS (`dist/index.js`)
-- ES Modules (`dist/index.mjs`)  
-- TypeScript declarations (`dist/index.d.ts`)
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `configureAds(config)` | `void` | Configure the ads service |
+| `showAd(type)` | `Promise<AdResult>` | Show an ad |
+| `areAdsReady()` | `boolean` | Check if ads have initialized |
+| `gameplayStart()` | `Promise<void>` | Notify gameplay started (CrazyGames) |
+| `gameplayStop()` | `Promise<void>` | Notify gameplay stopped (CrazyGames) |
+| `happytime()` | `Promise<void>` | Trigger celebration effect (CrazyGames) |
+
+### Billing
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getBillingPlatform()` | `BillingPlatform` | `"web"` \| `"native"` \| `"unknown"` |
+| `isBillingAvailable()` | `boolean` | Check if billing is ready |
+| `getBillingProducts()` | `Promise<BillingProduct[]>` | Fetch available products |
+| `purchaseProduct(productId, options?)` | `Promise<PurchaseResult>` | Initiate a purchase |
+| `onPurchaseComplete(callback)` | `void` | Register purchase success handler |
+| `onPurchaseError(callback)` | `void` | Register purchase error handler |
+| `unmountBillingCheckout()` | `void` | Clean up Stripe checkout UI |
+
+## Build Output
+
+| Format | File | Use |
+|--------|------|-----|
+| CJS | `dist/index.js` | Node.js / bundler |
+| ESM | `dist/index.mjs` | Bundler (tree-shakeable) |
+| CJS (React) | `dist/react.js` | React integration |
+| ESM (React) | `dist/react.mjs` | React integration (tree-shakeable) |
 
 ## Development
 
 ```bash
-# Install dependencies
-bun install
-
-# Type checking
-bun run check-types
-
-# Linting
-bun run lint
-
-# Build
-bun run build
+pnpm run check-types   # Type check
+pnpm run lint          # Lint
+pnpm run build         # 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
-
 ## License
 
-MIT
+MIT