Hyve SDK

JavaScript SDK for integrating Hyve platform features into web games.

Installation

bun add @hyve-sdk/js

Setup

Wrap your app with HyveSdkProvider. Access the SDK anywhere with useHyveSdk().

import { HyveSdkProvider, useHyveSdk } from '@hyve-sdk/js/react';

function App() {
  return (
    <HyveSdkProvider config={{ billing: { stripePublishableKey: 'pk_live_...' } }}>
      <Game />
    </HyveSdkProvider>
  );
}

function Game() {
  const hyve = useHyveSdk();
  // hyve.*
}

HyveSdkProvider creates one HyveClient instance. Stable across re-renders and StrictMode. Pass a pre-created client via client prop instead of config if needed.

Configuration

interface HyveClientConfig {
  isDev?: boolean;                  // Auto-detected from parent URL
  apiBaseUrl?: string;              // Override API base URL
  storageMode?: 'cloud' | 'local'; // Default: 'cloud'
  billing?: {
    stripePublishableKey?: string;
  };
  ads?: {
    sound?: 'on' | 'off';
    debug?: boolean;
    onBeforeAd?: (type: AdType) => void;
    onAfterAd?: (type: AdType) => void;
    onRewardEarned?: () => void;
  };
}

Environment is auto-detected from the parent page URL (games run in iframes):

Parent URL	Environment	API
dev.hyve.gg, marvin.dev.hyve.gg	dev	product-api.dev.hyve.gg
hyve.gg, marvin.hyve.gg	prod	product-api.prod.hyve.gg
localhost / unknown	dev	product-api.dev.hyve.gg

Authentication

The SDK reads hyve-access (JWT) and game-id from the URL on construction. No separate auth call needed.

https://yourgame.com?hyve-access=eyJhbGci...&game-id=123

hyve.hasJwtToken()          // boolean — JWT present
hyve.isUserAuthenticated()  // boolean — user ID extracted from JWT
hyve.getUserId()            // string | null
hyve.getJwtToken()          // string | null
hyve.getGameId()            // string | null
hyve.getSessionId()         // string — auto-generated UUID
hyve.getApiBaseUrl()        // string
hyve.logout()               // clear JWT, userId, gameId
hyve.reset()                // logout + new sessionId

Features

• Telemetry — Track game events. Requires JWT + game-id.
• Storage — Persist player data. Cloud or local, atomic ops, batch writes, leaderboards.
• Billing — Web (Stripe) and native (IAP) purchases.
• Ads — Rewarded, interstitial, and preroll with platform auto-routing.

Generic API

const data = await hyve.callApi('/api/v1/user');
const result = await hyve.callApi('/api/v1/score', {
  method: 'POST',
  body: JSON.stringify({ score: 1000 }),
});

JWT is automatically included in Authorization: Bearer.

Inventory

const inventory = await hyve.getInventory();
// { items: InventoryItem[], total_count: number }

const item = await hyve.getInventoryItem('item-id-123');

interface InventoryItem {
  id: string;
  user_id: string;
  item_type: string;
  item_id: string;
  quantity: number;
  metadata?: Record<string, unknown>;
  created_at: string;
  updated_at: string;
}

Logger

import { logger } from '@hyve-sdk/js';

logger.debug('msg', { data });
logger.info('msg');
logger.warn('msg');
logger.error('msg', error);

logger.setLevels(['error', 'warn']);
localStorage.setItem('HYVE_SDK_LOG_LEVEL', 'debug,info,warn,error');

const gameLogger = logger.child('Game');
// [Hyve SDK] [Game] [INFO] started

Auto-enabled when NODE_ENV !== 'production'.

Troubleshooting

Symptom	Cause
hasJwtToken() false	hyve-access URL param missing — game must launch from Hyve platform
getGameId() null	game-id URL param missing — required for telemetry and storage
sendTelemetry returns false	Missing JWT or game-id
API returns 401	JWT expired or malformed
Storage fails	game-id missing