@hyve-sdk/js 2.1.0 → 2.1.2

package/README.md

@@ -1,339 +1,370 @@
 # @hyve-sdk/js
 
-The core SDK for integrating with the Hyve platform, providing authentication, telemetry, persistent storage, billing, ads, and native bridge capabilities for web games.
+TypeScript SDK for integrating games with the Hyve platform. Provides authentication, telemetry, persistent storage, ads, billing, and native bridge capabilities.
 
-## Setup
+## Installation
 
-Load the SDK via script tag — no npm install required.
-
-```html
-<script src="https://package.hyve.gg/hyve-sdk.global.js"></script>
+```bash
+pnpm add @hyve-sdk/js
 ```
 
-All exports are available on `window.HyveSDK`:
+## Quick Start
 
-```js
-const { HyveClient, NativeBridge, NativeMessageType } = window.HyveSDK;
-```
+```ts
+import { HyveClient } from "@hyve-sdk/js";
+
+// Authentication is automatic — the SDK reads hyve-access and game-id from the URL
+const client = new HyveClient();
 
-## Authentication
+console.log("User ID:", client.getUserId());
+console.log("Game ID:", client.getGameId());
+console.log("Authenticated:", client.isUserAuthenticated());
+```
 
-Authenticate using the `hyve-access` JWT passed in the URL:
+The SDK reads authentication from URL parameters automatically during construction:
 
 ```
 https://your-game.com?hyve-access=eyJhbGci...&game-id=my-game
 ```
 
-```js
-const { HyveClient } = window.HyveSDK;
+**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
 
-const client = new HyveClient();
-await client.authenticateFromUrl(window.location.search);
+## React Integration
 
-console.log('User ID:', client.getUserId());
-console.log('Game ID:', client.getGameId());
-```
+Import from `@hyve-sdk/js/react` for the React provider and hook:
+
+```tsx
+import { HyveSdkProvider, useHyveSdk } from "@hyve-sdk/js/react";
 
-**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`
+function App() {
+  return (
+    <HyveSdkProvider config={{ isDev: true }}>
+      <Game />
+    </HyveSdkProvider>
+  );
+}
 
-## Telemetry & Analytics
+function Game() {
+  const sdk = useHyveSdk();
 
-Track user actions and game events:
+  const handleScore = () => {
+    sdk.sendTelemetry("game", "player", "score_submitted", null, null, { score: 1000 });
+  };
 
-```js
-const { HyveClient } = window.HyveSDK;
+  return <button onClick={handleScore}>Submit Score</button>;
+}
+```
 
-const client = new HyveClient();
-await client.authenticateFromUrl(window.location.search);
+You can also pass a pre-created client:
 
+```tsx
+const client = new HyveClient({ isDev: true });
+
+<HyveSdkProvider client={client}>
+  <App />
+</HyveSdkProvider>
+```
+
+## Telemetry
+
+```ts
 await client.sendTelemetry(
-  'game',       // location
-  'player',     // category
-  'action',     // action
-  'combat',     // sub-category (optional)
-  'attack',     // sub-action (optional)
-  {             // event details (optional)
-    button: 'attack-btn',
+  "game",        // location
+  "player",      // category
+  "action",      // action
+  "combat",      // sub-category (optional)
+  "attack",      // sub-action (optional)
+  {              // event details (optional)
     damage: 100,
-    targetId: 'enemy-123',
+    targetId: "enemy-123",
   }
 );
 ```
 
-**Requirements:**
-- `hyve-access` JWT in URL
-- `game-id` in URL or JWT
-- User authenticated via `authenticateFromUrl`
-
-See [docs/TELEMETRY.md](./docs/TELEMETRY.md) for validation rules and examples.
+Requires a valid `hyve-access` JWT and `game-id` in the URL.
 
-## API Integration
+## Persistent Game Data
 
-### Generic API Calls
+Save and retrieve game data with either cloud (default) or local storage:
 
-```js
-// GET request
-const userData = await client.callApi('/api/v1/user');
+```ts
+// Save a value
+await client.saveGameData("player_level", 5);
+await client.saveGameData("settings", { volume: 0.8, fullscreen: true });
 
-// POST request
-const result = await client.callApi('/api/v1/game/score', {
-  method: 'POST',
-  body: JSON.stringify({ score: 1000 })
-});
-```
+// Get a value
+const item = await client.getGameData("player_level");
+console.log(item?.value); // 5
 
-### Inventory
+// Batch save
+await client.batchSaveGameData([
+  { key: "coins", value: 1200 },
+  { key: "lives", value: 3 },
+]);
 
-```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`);
-});
+// Batch get
+const items = await client.getMultipleGameData(["coins", "lives"]);
 
-const item = await client.getInventoryItem('item-id-123');
+// Delete
+await client.deleteGameData("temp_key");
+await client.deleteMultipleGameData(["key1", "key2"]);
 ```
 
-## Ads Integration
-
-Ads are **disabled by default** — must be explicitly enabled.
+### Storage Modes
 
-### Prerequisites
+```ts
+// Set mode at construction
+const client = new HyveClient({ storageMode: "local" });
 
-Add the Google H5 Games Ads SDK to your HTML before the Hyve SDK:
+// Or override per-call
+await client.saveGameData("key", "value", "local");
+await client.getGameData("key", "cloud");
 
-```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>
+// Change mode at runtime
+client.configureStorage("cloud");
+console.log(client.getStorageMode()); // "cloud"
 ```
 
-### Quick Start
+| Mode | Description |
+|------|-------------|
+| `cloud` | Synced to backend API (default) |
+| `local` | Browser `localStorage`, device-only |
 
-```js
-const { HyveClient } = window.HyveSDK;
+## Ads
 
+Ads are disabled by default and must be explicitly configured.
+
+```ts
 const client = new HyveClient({
   ads: {
     enabled: true,
     onBeforeAd: (type) => game.pause(),
     onAfterAd: (type) => game.resume(),
-    onRewardEarned: () => { player.coins += 100; }
-  }
+    onRewardEarned: () => { player.coins += 100; },
+  },
 });
 
-await client.authenticateFromUrl(window.location.search);
-
-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
 ```
 
-### Ad Types
-
-| Type | Use Case |
-|------|----------|
-| `rewarded` | User watches full ad for reward |
+| Ad Type | Use Case |
+|---------|----------|
+| `rewarded` | User watches full ad for a reward |
 | `interstitial` | Between levels or game screens |
-| `preroll` | Before game starts |
+| `preroll` | Before the game starts |
 
-See [docs/ads.md](./docs/ads.md) for detailed documentation.
+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.
 
-## Billing Integration
+## Platform Integrations
 
-Unified billing for web (Stripe) and native (In-App Purchases). Platform is detected automatically.
+### CrazyGames
 
-### Quick Start
+When running on CrazyGames, the SDK auto-initializes the CrazyGames SDK and routes ads through it. Use these additional lifecycle methods:
 
-```js
-const { HyveClient } = window.HyveSDK;
+```ts
+// Call when gameplay begins (required by CrazyGames policy)
+await client.gameplayStart();
+
+// Call when gameplay stops (paused, died, menu, etc.)
+await client.gameplayStop();
+
+// Trigger a celebration effect on the CrazyGames website
+await client.happytime();
+```
+
+### Playgama
 
+When running on Playgama, the SDK auto-initializes the Playgama Bridge and routes ads through it. No additional setup required.
+
+## Billing
+
+Billing supports web (Stripe) and native (In-App Purchases) — platform is detected automatically.
+
+```ts
 const client = new HyveClient({
   billing: {
-    stripePublishableKey: 'pk_live_...',
-    checkoutUrl: 'https://checkout-api.hyve.gg',
-  }
+    stripePublishableKey: "pk_live_...",
+  },
 });
 
-await client.authenticateFromUrl(window.location.search);
-const initialized = await client.initializeBilling();
-
-if (initialized && client.isBillingAvailable()) {
+if (client.isBillingAvailable()) {
   client.onPurchaseComplete((result) => {
-    console.log('Purchase successful!', result.transactionId);
-    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);
   });
 
   const products = await client.getBillingProducts();
-  await client.purchaseProduct('price_1234');
+  await client.purchaseProduct("price_1234");
 }
 ```
 
-### Platform Support
-
-| Platform | Payment Method | Detection |
-|----------|---------------|-----------|
-| Web | Stripe Embedded Checkout | Default (no ReactNativeWebView) |
-| Native (iOS/Android) | In-App Purchases | `ReactNativeWebView` in window |
-
-### Prerequisites
-
 For web, add a container element for the Stripe checkout UI:
 
 ```html
 <div id="stripe-checkout-element"></div>
 ```
 
-See [docs/BILLING_INTEGRATION.md](./docs/BILLING_INTEGRATION.md) for full documentation and examples.
-
-## Native Bridge (React Native WebView)
+| Platform | Payment Method | Detection |
+|----------|---------------|-----------|
+| Web | Stripe Embedded Checkout | Default |
+| Native iOS/Android | In-App Purchases | `ReactNativeWebView` in window |
 
-Type-safe bidirectional communication between your web game and a React Native mobile app.
+## Native Bridge
 
-### Quick Start
+Type-safe bidirectional communication between your web game and a React Native WebView host.
 
-```js
-const { NativeBridge } = window.HyveSDK;
+```ts
+import { NativeBridge } from "@hyve-sdk/js";
 
 if (NativeBridge.isNativeContext()) {
   NativeBridge.initialize();
-}
-```
 
-### IAP Availability
+  // Listen for IAP availability
+  NativeBridge.on("IAP_AVAILABILITY_RESULT", (payload) => {
+    if (payload.available) {
+      console.log("IAP available on:", payload.platform);
+    }
+  });
+  NativeBridge.checkIAPAvailability();
 
-```js
-NativeBridge.on('IAP_AVAILABILITY_RESULT', (payload) => {
-  if (payload.available) {
-    console.log('IAP available on platform:', payload.platform);
-  }
-});
+  // Request push notification permission
+  NativeBridge.on("PUSH_PERMISSION_GRANTED", (payload) => {
+    console.log("Token:", payload?.token);
+  });
+  NativeBridge.requestNotificationPermission();
 
-NativeBridge.checkIAPAvailability();
+  // Send/receive custom messages
+  NativeBridge.send("GAME_EVENT", { action: "level_complete", level: 3 });
+  NativeBridge.on("CUSTOM_RESPONSE", (payload) => {
+    console.log("Received:", payload);
+  });
+}
 ```
 
-### Push Notifications
-
-```js
-NativeBridge.on('PUSH_PERMISSION_GRANTED', (payload) => {
-  console.log('Token:', payload?.token);
-});
+### NativeBridge API
 
-NativeBridge.on('PUSH_PERMISSION_DENIED', () => {
-  console.log('Permission denied');
-});
+| 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 |
 
-NativeBridge.requestNotificationPermission();
-```
+## Logger
 
-### Custom Messages
+```ts
+import { logger } from "@hyve-sdk/js";
 
-```js
-NativeBridge.send('GAME_EVENT', { action: 'level_complete', level: 3 });
+logger.debug("Debug info", { data: "value" });
+logger.info("Informational message");
+logger.warn("Warning message");
+logger.error("Error message", error);
 
-NativeBridge.on('CUSTOM_RESPONSE', (payload) => {
-  console.log('Received:', payload);
-});
+// Namespaced child logger
+const gameLogger = logger.child("Game");
+gameLogger.info("Game started");
+// Output: [Hyve SDK] [Game] [INFO] [timestamp] Game started
 ```
 
-### API Reference
-
-- `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
-
-See [docs/NATIVE_BRIDGE.md](./docs/NATIVE_BRIDGE.md) for full documentation.
-
-## Logger
+Override log level in the browser:
 
 ```js
-const { logger } = window.HyveSDK;
+localStorage.setItem("HYVE_SDK_LOG_LEVEL", "error,warn");
+```
 
-logger.debug('Debug info', { data: 'value' });
-logger.info('Informational message');
-logger.warn('Warning message');
-logger.error('Error message', error);
+## API Reference
 
-// Namespaced child loggers
-const gameLogger = logger.child('Game');
-gameLogger.info('Game started');
-// Output: [Hyve SDK] [Game] [INFO] [timestamp] Game started
-```
+### HyveClient Config
 
-**Log level override (browser):**
-```js
-localStorage.setItem('HYVE_SDK_LOG_LEVEL', 'error,warn');
+```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;
+})
 ```
 
-## Client Methods Reference
-
 ### Authentication
-- `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
+
+| 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
-- `callApi<T>(endpoint, options?)` — Authenticated API call
-- `getInventory()` — Get user inventory
-- `getInventoryItem(itemId)` — Get specific inventory item
+
+| 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 |
 
 ### Telemetry
-- `sendTelemetry(location, category, action, subCategory?, subAction?, details?)` — Send analytics event
-- `updateTelemetryConfig(config)` — Update telemetry settings
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `sendTelemetry(location, category, action, subCategory?, subAction?, details?)` | `Promise<boolean>` | Send an analytics event |
+| `updateTelemetryConfig(config)` | `void` | Update telemetry settings at runtime |
+
+### Storage
+
+| 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 |
 
 ### Ads
-- `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
+
+| 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
-- `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
-
-- 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
+
+| 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
 
@@ -341,33 +372,17 @@ localStorage.setItem('HYVE_SDK_LOG_LEVEL', 'error,warn');
 |--------|------|-----|
 | CJS | `dist/index.js` | Node.js / bundler |
 | ESM | `dist/index.mjs` | Bundler (tree-shakeable) |
-| IIFE | `dist/hyve-sdk.global.js` | CDN / script tag |
+| 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
-
-- [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

package/dist/index.js

@@ -1932,8 +1932,10 @@ var HyveClient = class {
    * Returns the current game ID or throws if not available.
    */
   requireGameId() {
-    const gameId = this.requireGameId();
-    return gameId;
+    if (!this.gameId) {
+      throw new Error("Game ID required. Ensure game-id URL parameter is set.");
+    }
+    return this.gameId;
   }
   /**
    * Save persistent game data

package/dist/index.mjs

@@ -1892,8 +1892,10 @@ var HyveClient = class {
    * Returns the current game ID or throws if not available.
    */
   requireGameId() {
-    const gameId = this.requireGameId();
-    return gameId;
+    if (!this.gameId) {
+      throw new Error("Game ID required. Ensure game-id URL parameter is set.");
+    }
+    return this.gameId;
   }
   /**
    * Save persistent game data

package/dist/react.js

@@ -1883,8 +1883,10 @@ var HyveClient = class {
    * Returns the current game ID or throws if not available.
    */
   requireGameId() {
-    const gameId = this.requireGameId();
-    return gameId;
+    if (!this.gameId) {
+      throw new Error("Game ID required. Ensure game-id URL parameter is set.");
+    }
+    return this.gameId;
   }
   /**
    * Save persistent game data

package/dist/react.mjs

@@ -1862,8 +1862,10 @@ var HyveClient = class {
    * Returns the current game ID or throws if not available.
    */
   requireGameId() {
-    const gameId = this.requireGameId();
-    return gameId;
+    if (!this.gameId) {
+      throw new Error("Game ID required. Ensure game-id URL parameter is set.");
+    }
+    return this.gameId;
   }
   /**
    * Save persistent game data

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyve-sdk/js",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "Hyve SDK - TypeScript wrapper for Hyve game server integration",
   "private": false,
   "publishConfig": {
@@ -68,8 +68,8 @@
     "@types/uuid": "^10.0.0",
     "tsup": "^8.4.0",
     "typescript": "^5.3.3",
-    "@repo/eslint-config": "0.0.0",
-    "@repo/typescript-config": "0.0.0"
+    "@repo/typescript-config": "0.0.0",
+    "@repo/eslint-config": "0.0.0"
   },
   "scripts": {
     "lint": "eslint . --max-warnings 0",