@hyve-sdk/js 1.3.2 → 1.3.3

package/README.md

@@ -20,6 +20,7 @@ pnpm add @hyve-sdk/js
 - **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
@@ -379,6 +380,219 @@ See [docs/ads.md](./docs/ads.md) for detailed documentation and examples.
 - JWT token must be available (via `hyve-access` URL parameter)
 - User must be authenticated
 
+## 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.
+
+### Quick Start
+
+```typescript
+import { HyveClient } from "@hyve-sdk/js";
+
+// Enable billing in initial config
+const client = new HyveClient({
+  isDev: true,
+  billing: {
+    stripePublishableKey: 'pk_test_...',
+    checkoutUrl: 'https://your-api.com',
+  }
+});
+
+// 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));
+  });
+
+  client.onPurchaseError((result) => {
+    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
+  });
+}
+```
+
+### 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:
+
+```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({
+  isDev: true,
+  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
+
 ## Native Bridge (React Native WebView)
 
 Provides type-safe bidirectional communication between your web application and the React Native mobile app.

package/dist/index.d.mts

@@ -171,138 +171,6 @@ declare class AdsService {
     isReady(): boolean;
 }
 
-/**
- * HyveClient configuration options
- */
-interface HyveClientConfig extends TelemetryConfig {
-    /** Ads configuration (disabled by default) */
-    ads?: AdConfig$1;
-}
-/**
- * HyveClient provides telemetry and authentication functionality for Hyve games
- */
-declare class HyveClient {
-    private telemetryConfig;
-    private apiBaseUrl;
-    private sessionId;
-    private userId;
-    private jwtToken;
-    private gameId;
-    private adsService;
-    /**
-     * Creates a new HyveClient instance
-     * @param config Optional configuration including telemetry and ads
-     */
-    constructor(config?: HyveClientConfig);
-    /**
-     * Authenticates a user from URL parameters
-     * @param urlParams URL parameters or search string
-     * @returns Promise resolving to boolean indicating success
-     */
-    authenticateFromUrl(urlParams?: URLSearchParams | string): Promise<boolean>;
-    /**
-     * Sends a user-level telemetry event using JWT authentication
-     * Requires JWT token, authenticated user, and game ID from URL parameters
-     * @param eventLocation Location where the event occurred
-     * @param eventCategory Main category of the event
-     * @param eventAction Primary action taken
-     * @param eventSubCategory Optional sub-category
-     * @param eventSubAction Optional sub-action
-     * @param eventDetails Optional event details (object or JSON string)
-     * @param customData Optional custom data (object or JSON string)
-     * @param platformId Optional platform identifier
-     * @returns Promise resolving to boolean indicating success
-     */
-    sendTelemetry(eventLocation: string, eventCategory: string, eventAction: string, eventSubCategory?: string | null, eventSubAction?: string | null, eventDetails?: Record<string, any> | string | null, customData?: Record<string, any> | null, platformId?: string | null): Promise<boolean>;
-    /**
-     * Makes an authenticated API call using the JWT token
-     * @param endpoint API endpoint path (will be appended to base URL)
-     * @param options Fetch options (method, body, etc.)
-     * @returns Promise resolving to the API response
-     */
-    callApi<T = any>(endpoint: string, options?: RequestInit): Promise<T>;
-    /**
-     * Gets the user's inventory
-     * @returns Promise resolving to the user's inventory
-     */
-    getInventory(): Promise<Inventory>;
-    /**
-     * Gets a specific inventory item by ID
-     * @param itemId The inventory item ID
-     * @returns Promise resolving to the inventory item details
-     */
-    getInventoryItem(itemId: string): Promise<InventoryItem>;
-    /**
-     * Updates the telemetry configuration
-     * @param config New telemetry configuration
-     */
-    updateTelemetryConfig(config: TelemetryConfig): void;
-    /**
-     * Gets the current user ID
-     * @returns Current user ID or null if not authenticated
-     */
-    getUserId(): string | null;
-    /**
-     * Gets the current session ID
-     * @returns Current session ID
-     */
-    getSessionId(): string;
-    /**
-     * Gets the current JWT token
-     * @returns Current JWT token or null if not available
-     */
-    getJwtToken(): string | null;
-    /**
-     * Gets the current game ID
-     * @returns Current game ID or null if not available
-     */
-    getGameId(): string | null;
-    /**
-     * Gets the API base URL
-     * @returns API base URL
-     */
-    getApiBaseUrl(): string;
-    /**
-     * Checks if user is authenticated
-     * @returns Boolean indicating authentication status
-     */
-    isUserAuthenticated(): boolean;
-    /**
-     * Checks if JWT token is available
-     * @returns Boolean indicating if JWT token is present
-     */
-    hasJwtToken(): boolean;
-    /**
-     * Logs out the current user
-     */
-    logout(): void;
-    /**
-     * Resets the client state
-     */
-    reset(): void;
-    /**
-     * Configure ads service
-     * @param config Ads configuration
-     */
-    configureAds(config: AdConfig$1): void;
-    /**
-     * Show an ad
-     * @param type Type of ad to show ('rewarded', 'interstitial', or 'preroll')
-     * @returns Promise resolving to ad result
-     */
-    showAd(type: AdType): Promise<AdResult>;
-    /**
-     * Check if ads are enabled
-     * @returns Boolean indicating if ads are enabled
-     */
-    areAdsEnabled(): boolean;
-    /**
-     * Check if ads are ready to show
-     * @returns Boolean indicating if ads are ready
-     */
-    areAdsReady(): boolean;
-}
-
 /**
  * Product information from the native app or server
  */
@@ -514,6 +382,197 @@ declare class BillingService {
     dispose(): void;
 }
 
+/**
+ * HyveClient configuration options
+ */
+interface HyveClientConfig extends TelemetryConfig {
+    /** Ads configuration (disabled by default) */
+    ads?: AdConfig$1;
+    /** Billing configuration (disabled by default) */
+    billing?: BillingConfig;
+}
+/**
+ * HyveClient provides telemetry and authentication functionality for Hyve games
+ */
+declare class HyveClient {
+    private telemetryConfig;
+    private apiBaseUrl;
+    private sessionId;
+    private userId;
+    private jwtToken;
+    private gameId;
+    private adsService;
+    private billingService;
+    private billingConfig;
+    private billingCallbacks;
+    /**
+     * Creates a new HyveClient instance
+     * @param config Optional configuration including telemetry and ads
+     */
+    constructor(config?: HyveClientConfig);
+    /**
+     * Authenticates a user from URL parameters
+     * @param urlParams URL parameters or search string
+     * @returns Promise resolving to boolean indicating success
+     */
+    authenticateFromUrl(urlParams?: URLSearchParams | string): Promise<boolean>;
+    /**
+     * Sends a user-level telemetry event using JWT authentication
+     * Requires JWT token, authenticated user, and game ID from URL parameters
+     * @param eventLocation Location where the event occurred
+     * @param eventCategory Main category of the event
+     * @param eventAction Primary action taken
+     * @param eventSubCategory Optional sub-category
+     * @param eventSubAction Optional sub-action
+     * @param eventDetails Optional event details (object or JSON string)
+     * @param customData Optional custom data (object or JSON string)
+     * @param platformId Optional platform identifier
+     * @returns Promise resolving to boolean indicating success
+     */
+    sendTelemetry(eventLocation: string, eventCategory: string, eventAction: string, eventSubCategory?: string | null, eventSubAction?: string | null, eventDetails?: Record<string, any> | string | null, customData?: Record<string, any> | null, platformId?: string | null): Promise<boolean>;
+    /**
+     * Makes an authenticated API call using the JWT token
+     * @param endpoint API endpoint path (will be appended to base URL)
+     * @param options Fetch options (method, body, etc.)
+     * @returns Promise resolving to the API response
+     */
+    callApi<T = any>(endpoint: string, options?: RequestInit): Promise<T>;
+    /**
+     * Gets the user's inventory
+     * @returns Promise resolving to the user's inventory
+     */
+    getInventory(): Promise<Inventory>;
+    /**
+     * Gets a specific inventory item by ID
+     * @param itemId The inventory item ID
+     * @returns Promise resolving to the inventory item details
+     */
+    getInventoryItem(itemId: string): Promise<InventoryItem>;
+    /**
+     * Updates the telemetry configuration
+     * @param config New telemetry configuration
+     */
+    updateTelemetryConfig(config: TelemetryConfig): void;
+    /**
+     * Gets the current user ID
+     * @returns Current user ID or null if not authenticated
+     */
+    getUserId(): string | null;
+    /**
+     * Gets the current session ID
+     * @returns Current session ID
+     */
+    getSessionId(): string;
+    /**
+     * Gets the current JWT token
+     * @returns Current JWT token or null if not available
+     */
+    getJwtToken(): string | null;
+    /**
+     * Gets the current game ID
+     * @returns Current game ID or null if not available
+     */
+    getGameId(): string | null;
+    /**
+     * Gets the API base URL
+     * @returns API base URL
+     */
+    getApiBaseUrl(): string;
+    /**
+     * Checks if user is authenticated
+     * @returns Boolean indicating authentication status
+     */
+    isUserAuthenticated(): boolean;
+    /**
+     * Checks if JWT token is available
+     * @returns Boolean indicating if JWT token is present
+     */
+    hasJwtToken(): boolean;
+    /**
+     * Logs out the current user
+     */
+    logout(): void;
+    /**
+     * Resets the client state
+     */
+    reset(): void;
+    /**
+     * Configure ads service
+     * @param config Ads configuration
+     */
+    configureAds(config: AdConfig$1): void;
+    /**
+     * Show an ad
+     * @param type Type of ad to show ('rewarded', 'interstitial', or 'preroll')
+     * @returns Promise resolving to ad result
+     */
+    showAd(type: AdType): Promise<AdResult>;
+    /**
+     * Check if ads are enabled
+     * @returns Boolean indicating if ads are enabled
+     */
+    areAdsEnabled(): boolean;
+    /**
+     * Check if ads are ready to show
+     * @returns Boolean indicating if ads are ready
+     */
+    areAdsReady(): boolean;
+    /**
+     * Configure billing service
+     * @param config Billing configuration
+     */
+    configureBilling(config: BillingConfig): void;
+    /**
+     * Initialize billing service
+     * Must be called before using billing features
+     * @returns Promise resolving to boolean indicating success
+     */
+    initializeBilling(): Promise<boolean>;
+    /**
+     * Get the billing platform
+     * @returns Current billing platform
+     */
+    getBillingPlatform(): BillingPlatform;
+    /**
+     * Check if billing is available
+     * @returns Boolean indicating if billing is available
+     */
+    isBillingAvailable(): boolean;
+    /**
+     * Get available billing products
+     * @returns Promise resolving to array of products
+     */
+    getBillingProducts(): Promise<BillingProduct[]>;
+    /**
+     * Purchase a product
+     * @param productId Product ID to purchase
+     * @param options Optional purchase options (e.g., elementId for web)
+     * @returns Promise resolving to purchase result
+     */
+    purchaseProduct(productId: string, options?: {
+        elementId?: string;
+    }): Promise<PurchaseResult>;
+    /**
+     * Set callback for successful purchases
+     * @param callback Function to call on purchase completion
+     */
+    onPurchaseComplete(callback: (result: PurchaseResult) => void): void;
+    /**
+     * Set callback for failed purchases
+     * @param callback Function to call on purchase error
+     */
+    onPurchaseError(callback: (result: PurchaseResult) => void): void;
+    /**
+     * Unmount Stripe checkout element
+     */
+    unmountBillingCheckout(): void;
+    /**
+     * Register a callback to receive billing logs
+     * @param callback Function to call with log messages
+     */
+    onBillingLog(callback: (level: "info" | "warn" | "error", message: string, data?: any) => void): void;
+}
+
 /**
  * Logger utility for the Hyve SDK
  * Automatically enabled in development (NODE_ENV !== 'production')