@billdog.io/react-native 1.0.0-beta.2

package/src/BillDogConfiguration.ts

@@ -0,0 +1,318 @@
+/**
+ * Default API base URL — routes through BillDog's Cloudflare proxy.
+ * Matches Android's `BillDogConfig.apiBaseUrl` and iOS's `BillDogConfig.API_BASE_URL`.
+ */
+export const DEFAULT_API_BASE_URL = 'https://api.billdog.io/v1';
+
+// Optional native module — present in a native build (Android/iOS), null in a
+// JS-only Metro run / Expo Go. `configure()` propagates the apiKey to the native
+// BillDog singleton so delegating calls (getCustomerInfo/register/purchase/…)
+// actually reach the configured native SDK.
+const _nativeBillDog: any = (() => {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    return require('react-native')?.NativeModules?.BillDog ?? null;
+  } catch {
+    return null;
+  }
+})();
+
+/**
+ * BillDog Paywalls SDK configuration
+ */
+export interface BillDogConfig {
+  /** API key for authentication (must start with "bd_") */
+  apiKey?: string;
+  
+  /**
+   * Base URL for all API calls.
+   * Defaults to `https://api.billdog.io/v1` (the branded API host).
+   * Override only for testing or self-hosted deployments — the override must
+   * point at a host that behaves like the BillDog edge Worker.
+   */
+  apiBaseUrl: string;
+  
+  /** Enable advanced caching features (compression, multi-level cache) */
+  enableAdvancedCaching: boolean;
+  
+  /** Maximum cache size in bytes (default: 50MB) */
+  maxCacheSize?: number;
+  
+  /** Cache TTL in milliseconds (default: 7 days) */
+  cacheTTL?: number;
+  
+  
+  /**
+   * Override device locale for all paywalls.
+   * Use ISO 639-1 language codes (e.g., "es", "fr", "de", "ja").
+   * Set to undefined to use device locale (default).
+   */
+  localeOverride?: string;
+  
+  /** SDK environment */
+  environment?: 'sandbox' | 'production';
+  
+  /** Enable debug logging */
+  enableLogging?: boolean;
+
+  /**
+   * PUR-262: granular log level. When set, overrides `enableLogging`.
+   * Canonical 5-level set: `verbose, debug, info, warn, error`.
+   */
+  logLevel?: import('./models/BillDogError').BillDogLogLevel;
+
+  // Analytics configuration overrides (client override > server config > SDK defaults)
+  
+  /** Override analytics enabled state (master kill switch). undefined = use server config. */
+  analyticsEnabled?: boolean;
+  
+  /** Override flush interval in seconds. Minimum: 10s. undefined = use server config. */
+  analyticsFlushInterval?: number;
+  
+  /** Override batch size (events before auto-flush). Minimum: 5. undefined = use server config. */
+  analyticsBatchSize?: number;
+  
+  /** Override max queue size. undefined = use server config. */
+  analyticsMaxQueueSize?: number;
+  
+  /** Override session timeout in seconds. undefined = use server config. */
+  analyticsSessionTimeout?: number;
+  
+  /** Override sampling rate (0.0–1.0). undefined = use server config. */
+  analyticsSamplingRate?: number;
+
+  /**
+   * App Store numeric ID (iOS) — used only for the Smart Review store-page
+   * fallback when the native `react-native-in-app-review` module isn't installed.
+   * e.g. '1234567890'. Without it (and without the native module) iOS review
+   * requests report unavailable instead of opening a broken URL.
+   */
+  appStoreId?: string;
+
+  /**
+   * Google Play package name (Android) — used only for the Smart Review
+   * store-page fallback when `react-native-in-app-review` isn't installed.
+   * e.g. 'com.acme.app'.
+   */
+  androidPackageName?: string;
+}
+
+/**
+ * Global configuration singleton
+ */
+export const BillDogConfiguration = {
+  config: {
+    apiKey: undefined,
+    apiBaseUrl: DEFAULT_API_BASE_URL,
+    enableAdvancedCaching: true,
+    maxCacheSize: 50 * 1024 * 1024, // 50MB
+    cacheTTL: 7 * 24 * 60 * 60 * 1000, // 7 days
+    localeOverride: undefined,
+    environment: 'production' as const,
+    enableLogging: false,
+  } as BillDogConfig,
+  
+  /**
+   * Configure the SDK with custom settings.
+   * Should be called early in app initialization (e.g., App.tsx or index.js).
+   * 
+   * @example
+   * ```typescript
+   * // Minimal configuration
+   * BillDogConfiguration.configure({
+   *   apiKey: 'bd_live_abc123',
+   * });
+   * 
+   * // Full configuration
+   * BillDogConfiguration.configure({
+   *   apiKey: 'bd_live_abc123',
+   *   environment: 'production',
+   *   localeOverride: 'es',
+   * });
+   * 
+   * // Self-hosted / testing
+   * BillDogConfiguration.configure({
+   *   apiKey: 'bd_test_abc123',
+   *   apiBaseUrl: 'https://my-proxy.example.com',
+   *   environment: 'sandbox',
+   * });
+   * ```
+   */
+  configure(newConfig: Partial<BillDogConfig>) {
+    this.config = { ...this.config, ...newConfig };
+    if (this.config.enableLogging) {
+      console.log('[BillDogConfiguration] Updated:', {
+        apiBaseUrl: this.config.apiBaseUrl,
+        hasApiKey: !!this.config.apiKey,
+        environment: this.config.environment,
+      });
+    }
+    // Propagate to the native SDK so its singleton is configured (thin-bridge
+    // calls delegate to it). Fire-and-forget — best-effort, never blocks JS.
+    if (this.config.apiKey && _nativeBillDog?.configure) {
+      try {
+        const result = _nativeBillDog.configure(this.config.apiKey, {
+          enableLogging: !!this.config.enableLogging,
+          environment: this.config.environment,
+          localeOverride: this.config.localeOverride,
+        });
+        if (result && typeof result.catch === 'function') result.catch(() => {});
+      } catch {
+        /* native configure is best-effort */
+      }
+    }
+    // Fetch remote SDK config in background (non-blocking)
+    if (this.config.apiKey) {
+      this.fetchSdkConfig().catch(() => {});
+    }
+  },
+
+  /** Cached server-driven SDK config */
+  _serverConfig: null as Record<string, any> | null,
+
+  /**
+   * Fetch server-driven SDK configuration.
+   * Applies server config under client overrides (client > server > defaults).
+   * Called automatically during `configure()` — can also be called manually to refresh.
+   */
+  async fetchSdkConfig(): Promise<Record<string, any> | null> {
+    try {
+      const endpoint = this.resolveEndpoint('sdk-config');
+      const response = await fetch(endpoint, {
+        method: 'GET',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-BillDog-API-Key': this.config.apiKey!,
+        },
+      });
+      if (!response.ok) return null;
+      const json = await response.json();
+      const data = json?.data;
+      if (!data) return null;
+      
+      this._serverConfig = data;
+      
+      // Apply server analytics config where client hasn't overridden
+      const analytics = data.analytics;
+      if (analytics) {
+        if (this.config.analyticsEnabled === undefined) {
+          this.config.analyticsEnabled = analytics.enabled ?? true;
+        }
+        if (this.config.analyticsFlushInterval === undefined) {
+          const serverInterval = (analytics.flush_interval_seconds ?? 30);
+          this.config.analyticsFlushInterval = Math.max(serverInterval, 10);
+        }
+        if (this.config.analyticsBatchSize === undefined) {
+          this.config.analyticsBatchSize = Math.max(analytics.batch_size ?? 20, 5);
+        }
+        if (this.config.analyticsMaxQueueSize === undefined) {
+          this.config.analyticsMaxQueueSize = Math.max(analytics.max_queue_size ?? 1000, 100);
+        }
+        if (this.config.analyticsSamplingRate === undefined) {
+          this.config.analyticsSamplingRate = Math.min(Math.max(analytics.sampling_rate ?? 1.0, 0), 1);
+        }
+        if (this.config.analyticsSessionTimeout === undefined) {
+          this.config.analyticsSessionTimeout = analytics.session_timeout_seconds ?? 300;
+        }
+      }
+      
+      if (this.config.enableLogging) {
+        console.log('[BillDogConfiguration] Server SDK config applied:', {
+          analyticsEnabled: this.config.analyticsEnabled,
+          flushInterval: this.config.analyticsFlushInterval,
+          batchSize: this.config.analyticsBatchSize,
+        });
+      }
+      
+      return data;
+    } catch (e) {
+      if (this.config.enableLogging) {
+        console.warn('[BillDogConfiguration] Failed to fetch SDK config:', e);
+      }
+      return null;
+    }
+  },
+
+  /**
+   * Get the resolved server SDK config (null if not yet fetched).
+   */
+  getServerConfig(): Record<string, any> | null {
+    return this._serverConfig;
+  },
+  
+  /**
+   * Get the resolved API base URL.
+   * Returns the configured `apiBaseUrl` (defaults to `https://api.billdog.io/v1`).
+   */
+  getApiBaseUrl(): string {
+    return this.config.apiBaseUrl || DEFAULT_API_BASE_URL;
+  },
+  
+  /**
+   * Get the configured API key.
+   * @throws if API key has not been configured.
+   */
+  getApiKey(): string {
+    if (!this.config.apiKey) {
+      throw new Error(
+        '[BillDogConfiguration] API key not configured. Call BillDogConfiguration.configure({ apiKey: "bd_..." }) first.'
+      );
+    }
+    return this.config.apiKey;
+  },
+  
+  /**
+   * Check if the SDK has been configured with an API key.
+   */
+  isConfigured(): boolean {
+    return !!this.config.apiKey;
+  },
+  
+  /**
+   * Build a full endpoint URL from a function name.
+   * e.g., `resolveEndpoint('fetch-paywall')` → `https://api.billdog.io/v1/fetch-paywall`
+   */
+  resolveEndpoint(functionName: string): string {
+    const base = this.getApiBaseUrl().replace(/\/$/, '');
+    return `${base}/${functionName}`;
+  },
+  
+  /**
+   * Set the locale override at runtime.
+   * This will affect all future paywall displays.
+   * 
+   * @param locale - ISO 639-1 language code (e.g., "es", "fr", "de") or undefined to use device locale
+   */
+  setLocaleOverride(locale: string | undefined) {
+    this.config.localeOverride = locale;
+    if (this.config.enableLogging) {
+      console.log(`[BillDogConfiguration] Locale override set to: ${locale ?? 'device default'}`);
+    }
+  },
+  
+  /**
+   * Get the current locale override.
+   * @returns The current locale override, or undefined if using device locale
+   */
+  getLocaleOverride(): string | undefined {
+    return this.config.localeOverride;
+  },
+  
+  /**
+   * Reset to default configuration
+   */
+  reset() {
+    this.config = {
+      apiKey: undefined,
+      apiBaseUrl: DEFAULT_API_BASE_URL,
+      enableAdvancedCaching: true,
+      maxCacheSize: 50 * 1024 * 1024,
+      cacheTTL: 7 * 24 * 60 * 60 * 1000,
+      
+      localeOverride: undefined,
+      environment: 'production',
+      enableLogging: false,
+    };
+    console.log('[BillDogConfiguration] Reset to defaults');
+  }
+};