@hyve-sdk/js 1.3.1 → 1.3.2-canary.1

package/README.md

@@ -22,6 +22,7 @@ pnpm add @hyve-sdk/js
 - **Telemetry Tracking**: Session-based analytics and event tracking
 - **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
@@ -473,6 +474,71 @@ NativeBridge.on("CUSTOM_RESPONSE", (payload) => {
 
 For complete documentation, see [docs/NATIVE_BRIDGE.md](./docs/NATIVE_BRIDGE.md).
 
+## 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
+
+**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";
+
+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
+
 ## Client Methods Reference
 
 ### Authentication
@@ -495,6 +561,12 @@ For complete documentation, see [docs/NATIVE_BRIDGE.md](./docs/NATIVE_BRIDGE.md)
 - `sendTelemetry(location, category, action, subCategory?, subAction?, details?, customData?, 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

package/dist/index.d.mts

@@ -303,6 +303,217 @@ declare class HyveClient {
     areAdsReady(): boolean;
 }
 
+/**
+ * Product information from the native app or server
+ */
+interface BillingProduct {
+    productId: string;
+    title: string;
+    description: string;
+    price: number;
+    localizedPrice: string;
+    currency: string;
+}
+/**
+ * Purchase result
+ */
+interface PurchaseResult {
+    success: boolean;
+    productId: string;
+    transactionId?: string;
+    transactionDate?: string;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+/**
+ * Billing configuration
+ */
+interface BillingConfig {
+    /**
+     * Stripe publishable key (required for web)
+     */
+    stripePublishableKey?: string;
+    /**
+     * Game ID for native purchases
+     */
+    gameId?: number;
+    /**
+     * User ID for purchases
+     */
+    userId?: string;
+    /**
+     * Checkout URL for API calls
+     */
+    checkoutUrl?: string;
+}
+/**
+ * Platform types
+ */
+declare enum BillingPlatform {
+    WEB = "web",
+    NATIVE = "native",
+    UNKNOWN = "unknown"
+}
+/**
+ * BillingService - Unified billing service for web and native platforms
+ *
+ * Automatically detects the platform and routes to the appropriate payment method:
+ * - Web: Stripe Embedded Checkout (Stripe Elements)
+ * - Native: In-App Purchases via NativeBridge
+ *
+ * @example
+ * ```typescript
+ * import { BillingService } from '@hyve-sdk/js';
+ *
+ * // Initialize billing
+ * const billing = new BillingService({
+ *   stripePublishableKey: 'pk_test_...',
+ *   checkoutUrl: 'https://your-api.com',
+ *   gameId: 123,
+ *   userId: 'user_456'
+ * });
+ *
+ * await billing.initialize();
+ *
+ * // Check which platform we're on
+ * const platform = billing.getPlatform();
+ * console.log('Running on:', platform);
+ *
+ * // Get available products
+ * const products = await billing.getProducts();
+ *
+ * // For web: Ensure you have a container element in your HTML
+ * // <div id="stripe-checkout-element"></div>
+ *
+ * // Purchase a product (web will mount Stripe checkout form)
+ * const result = await billing.purchase('price_1234', {
+ *   elementId: 'stripe-checkout-element' // optional, defaults to 'stripe-checkout-element'
+ * });
+ *
+ * // Set up callbacks for purchase events
+ * billing.onPurchaseComplete((result) => {
+ *   console.log('Purchase successful!', result);
+ * });
+ *
+ * billing.onPurchaseError((result) => {
+ *   console.error('Purchase failed:', result.error);
+ * });
+ *
+ * // Clean up when done
+ * billing.dispose();
+ * ```
+ */
+declare class BillingService {
+    private config;
+    private platform;
+    private isInitialized;
+    private nativeAvailable;
+    private products;
+    private stripe;
+    private checkoutElement;
+    private onPurchaseCompleteCallback?;
+    private onPurchaseErrorCallback?;
+    private onLogCallback?;
+    constructor(config: BillingConfig);
+    /**
+     * Register a callback to receive all internal logs
+     * Useful for displaying logs in a UI
+     */
+    onLog(callback: (level: "info" | "warn" | "error", message: string, data?: any) => void): void;
+    /**
+     * Internal logging method that calls both logger and custom callback
+     */
+    private log;
+    /**
+     * Detects if running on web or native platform
+     */
+    private detectPlatform;
+    /**
+     * Get the current platform
+     */
+    getPlatform(): BillingPlatform;
+    /**
+     * Initialize the billing service
+     * Must be called before using any other methods
+     */
+    initialize(): Promise<boolean>;
+    /**
+     * Initialize native billing
+     */
+    private initializeNative;
+    /**
+     * Initialize web billing (Stripe)
+     */
+    private initializeWeb;
+    /**
+     * Load Stripe.js script dynamically
+     */
+    private loadStripeScript;
+    /**
+     * Check if billing is available
+     */
+    isAvailable(): boolean;
+    /**
+     * Get available products
+     */
+    getProducts(): Promise<BillingProduct[]>;
+    /**
+     * Get products from native IAP
+     */
+    private getProductsNative;
+    /**
+     * Get products from web API (Stripe)
+     */
+    private getProductsWeb;
+    /**
+     * Purchase a product
+     * @param productId - The product ID (priceId for web/Stripe, productId for native)
+     * @param options - Optional purchase options
+     * @param options.elementId - For web: DOM element ID to mount Stripe checkout (default: 'stripe-checkout-element')
+     */
+    purchase(productId: string, options?: {
+        elementId?: string;
+    }): Promise<PurchaseResult>;
+    /**
+     * Purchase via native IAP
+     */
+    private purchaseNative;
+    /**
+     * Purchase via web (Stripe)
+     * @param productId - The priceId (Stripe price ID) for web purchases
+     * @param elementId - Optional DOM element ID to mount the checkout form (default: 'stripe-checkout-element')
+     */
+    private purchaseWeb;
+    /**
+     * Mount Stripe embedded checkout element to the DOM
+     * @param clientSecret - The client secret from the checkout session
+     * @param elementId - The ID of the DOM element to mount to
+     */
+    private mountCheckoutElement;
+    /**
+     * Set up event listeners for checkout completion
+     */
+    private setupCheckoutEventListeners;
+    /**
+     * Unmount and destroy the checkout element
+     */
+    unmountCheckoutElement(): void;
+    /**
+     * Set callback for successful purchases
+     */
+    onPurchaseComplete(callback: (result: PurchaseResult) => void): void;
+    /**
+     * Set callback for failed purchases
+     */
+    onPurchaseError(callback: (result: PurchaseResult) => void): void;
+    /**
+     * Clean up resources
+     */
+    dispose(): void;
+}
+
 /**
  * Logger utility for the Hyve SDK
  * Automatically enabled in development (NODE_ENV !== 'production')
@@ -576,4 +787,4 @@ declare class NativeBridge {
  */
 declare function generateUUID(): string;
 
-export { type AdConfig$1 as AdConfig, type AdResult, type AdType, AdsService, HyveClient, type HyveClientConfig, type Inventory, type InventoryItem, Logger, NativeBridge, type NativeMessage, type NativeMessageHandler, NativeMessageType, type TelemetryAdditionalData, type TelemetryConfig, type TelemetryEvent, generateUUID, handleVerifyMessage, isDomainAllowed, logger, parseUrlParams, validateSignature, verifyAuthentication, verifyHyveToken };
+export { type AdConfig$1 as AdConfig, type AdResult, type AdType, AdsService, type BillingConfig, BillingPlatform, type BillingProduct, BillingService, HyveClient, type HyveClientConfig, type Inventory, type InventoryItem, Logger, NativeBridge, type NativeMessage, type NativeMessageHandler, NativeMessageType, type PurchaseResult, type TelemetryAdditionalData, type TelemetryConfig, type TelemetryEvent, generateUUID, handleVerifyMessage, isDomainAllowed, logger, parseUrlParams, validateSignature, verifyAuthentication, verifyHyveToken };

package/dist/index.d.ts

@@ -303,6 +303,217 @@ declare class HyveClient {
     areAdsReady(): boolean;
 }
 
+/**
+ * Product information from the native app or server
+ */
+interface BillingProduct {
+    productId: string;
+    title: string;
+    description: string;
+    price: number;
+    localizedPrice: string;
+    currency: string;
+}
+/**
+ * Purchase result
+ */
+interface PurchaseResult {
+    success: boolean;
+    productId: string;
+    transactionId?: string;
+    transactionDate?: string;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+/**
+ * Billing configuration
+ */
+interface BillingConfig {
+    /**
+     * Stripe publishable key (required for web)
+     */
+    stripePublishableKey?: string;
+    /**
+     * Game ID for native purchases
+     */
+    gameId?: number;
+    /**
+     * User ID for purchases
+     */
+    userId?: string;
+    /**
+     * Checkout URL for API calls
+     */
+    checkoutUrl?: string;
+}
+/**
+ * Platform types
+ */
+declare enum BillingPlatform {
+    WEB = "web",
+    NATIVE = "native",
+    UNKNOWN = "unknown"
+}
+/**
+ * BillingService - Unified billing service for web and native platforms
+ *
+ * Automatically detects the platform and routes to the appropriate payment method:
+ * - Web: Stripe Embedded Checkout (Stripe Elements)
+ * - Native: In-App Purchases via NativeBridge
+ *
+ * @example
+ * ```typescript
+ * import { BillingService } from '@hyve-sdk/js';
+ *
+ * // Initialize billing
+ * const billing = new BillingService({
+ *   stripePublishableKey: 'pk_test_...',
+ *   checkoutUrl: 'https://your-api.com',
+ *   gameId: 123,
+ *   userId: 'user_456'
+ * });
+ *
+ * await billing.initialize();
+ *
+ * // Check which platform we're on
+ * const platform = billing.getPlatform();
+ * console.log('Running on:', platform);
+ *
+ * // Get available products
+ * const products = await billing.getProducts();
+ *
+ * // For web: Ensure you have a container element in your HTML
+ * // <div id="stripe-checkout-element"></div>
+ *
+ * // Purchase a product (web will mount Stripe checkout form)
+ * const result = await billing.purchase('price_1234', {
+ *   elementId: 'stripe-checkout-element' // optional, defaults to 'stripe-checkout-element'
+ * });
+ *
+ * // Set up callbacks for purchase events
+ * billing.onPurchaseComplete((result) => {
+ *   console.log('Purchase successful!', result);
+ * });
+ *
+ * billing.onPurchaseError((result) => {
+ *   console.error('Purchase failed:', result.error);
+ * });
+ *
+ * // Clean up when done
+ * billing.dispose();
+ * ```
+ */
+declare class BillingService {
+    private config;
+    private platform;
+    private isInitialized;
+    private nativeAvailable;
+    private products;
+    private stripe;
+    private checkoutElement;
+    private onPurchaseCompleteCallback?;
+    private onPurchaseErrorCallback?;
+    private onLogCallback?;
+    constructor(config: BillingConfig);
+    /**
+     * Register a callback to receive all internal logs
+     * Useful for displaying logs in a UI
+     */
+    onLog(callback: (level: "info" | "warn" | "error", message: string, data?: any) => void): void;
+    /**
+     * Internal logging method that calls both logger and custom callback
+     */
+    private log;
+    /**
+     * Detects if running on web or native platform
+     */
+    private detectPlatform;
+    /**
+     * Get the current platform
+     */
+    getPlatform(): BillingPlatform;
+    /**
+     * Initialize the billing service
+     * Must be called before using any other methods
+     */
+    initialize(): Promise<boolean>;
+    /**
+     * Initialize native billing
+     */
+    private initializeNative;
+    /**
+     * Initialize web billing (Stripe)
+     */
+    private initializeWeb;
+    /**
+     * Load Stripe.js script dynamically
+     */
+    private loadStripeScript;
+    /**
+     * Check if billing is available
+     */
+    isAvailable(): boolean;
+    /**
+     * Get available products
+     */
+    getProducts(): Promise<BillingProduct[]>;
+    /**
+     * Get products from native IAP
+     */
+    private getProductsNative;
+    /**
+     * Get products from web API (Stripe)
+     */
+    private getProductsWeb;
+    /**
+     * Purchase a product
+     * @param productId - The product ID (priceId for web/Stripe, productId for native)
+     * @param options - Optional purchase options
+     * @param options.elementId - For web: DOM element ID to mount Stripe checkout (default: 'stripe-checkout-element')
+     */
+    purchase(productId: string, options?: {
+        elementId?: string;
+    }): Promise<PurchaseResult>;
+    /**
+     * Purchase via native IAP
+     */
+    private purchaseNative;
+    /**
+     * Purchase via web (Stripe)
+     * @param productId - The priceId (Stripe price ID) for web purchases
+     * @param elementId - Optional DOM element ID to mount the checkout form (default: 'stripe-checkout-element')
+     */
+    private purchaseWeb;
+    /**
+     * Mount Stripe embedded checkout element to the DOM
+     * @param clientSecret - The client secret from the checkout session
+     * @param elementId - The ID of the DOM element to mount to
+     */
+    private mountCheckoutElement;
+    /**
+     * Set up event listeners for checkout completion
+     */
+    private setupCheckoutEventListeners;
+    /**
+     * Unmount and destroy the checkout element
+     */
+    unmountCheckoutElement(): void;
+    /**
+     * Set callback for successful purchases
+     */
+    onPurchaseComplete(callback: (result: PurchaseResult) => void): void;
+    /**
+     * Set callback for failed purchases
+     */
+    onPurchaseError(callback: (result: PurchaseResult) => void): void;
+    /**
+     * Clean up resources
+     */
+    dispose(): void;
+}
+
 /**
  * Logger utility for the Hyve SDK
  * Automatically enabled in development (NODE_ENV !== 'production')
@@ -576,4 +787,4 @@ declare class NativeBridge {
  */
 declare function generateUUID(): string;
 
-export { type AdConfig$1 as AdConfig, type AdResult, type AdType, AdsService, HyveClient, type HyveClientConfig, type Inventory, type InventoryItem, Logger, NativeBridge, type NativeMessage, type NativeMessageHandler, NativeMessageType, type TelemetryAdditionalData, type TelemetryConfig, type TelemetryEvent, generateUUID, handleVerifyMessage, isDomainAllowed, logger, parseUrlParams, validateSignature, verifyAuthentication, verifyHyveToken };
+export { type AdConfig$1 as AdConfig, type AdResult, type AdType, AdsService, type BillingConfig, BillingPlatform, type BillingProduct, BillingService, HyveClient, type HyveClientConfig, type Inventory, type InventoryItem, Logger, NativeBridge, type NativeMessage, type NativeMessageHandler, NativeMessageType, type PurchaseResult, type TelemetryAdditionalData, type TelemetryConfig, type TelemetryEvent, generateUUID, handleVerifyMessage, isDomainAllowed, logger, parseUrlParams, validateSignature, verifyAuthentication, verifyHyveToken };