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

package/src/hooks/useOfferings.ts

@@ -0,0 +1,192 @@
+/**
+ * useOfferings Hook - Fetches offerings list with filtering and pagination
+ */
+
+import { useState, useEffect, useCallback } from 'react';
+import { ApiClient } from '../utils/ApiClient';
+
+interface Package {
+  id: string;
+  package_identifier: string;
+  position: number;
+  metadata?: Record<string, any>;
+  product_id?: string;
+  product?: {
+    id: string;
+    product_identifier: string;
+    display_name: string;
+    description?: string;
+    type: string;
+    platform: string;
+    price_usd?: number;
+    currency?: string;
+  };
+}
+
+interface PaywallOffering {
+  is_primary: boolean;
+  paywall: {
+    id: string;
+    identifier: string;
+    name: string;
+    configuration: any;
+    version: number;
+  };
+}
+
+interface Offering {
+  id: string;
+  identifier: string;
+  display_name: string;
+  description?: string;
+  notes?: string;
+  is_current: boolean;
+  is_default: boolean;
+  metadata?: Record<string, any>;
+  created_at: string;
+  updated_at: string;
+  offering_packages?: Package[];
+  paywall_offerings?: PaywallOffering[];
+}
+
+export interface UseOfferingsOptions {
+  /** @deprecated Use BillDogConfiguration.configure({ apiKey }) instead */
+  apiKey?: string;
+  skipFetch?: boolean;
+  limit?: number;
+  offset?: number;
+  is_current?: boolean;
+  is_default?: boolean;
+  identifier?: string;
+  expand?: 'packages' | 'products' | 'paywall' | string;
+  sort_by?: 'created_at' | 'display_name' | 'identifier';
+  sort_order?: 'asc' | 'desc';
+}
+
+interface Pagination {
+  total: number;
+  limit: number;
+  offset: number;
+  has_more: boolean;
+}
+
+export interface UseOfferingsResult {
+  offerings: Offering[];
+  currentOffering: Offering | null;
+  allOfferings: Record<string, Offering> | null;
+  pagination: Pagination | null;
+  loading: boolean;
+  error: Error | null;
+  refetch: () => Promise<void>;
+  fetchCurrentOffering: () => Promise<Offering | null>;
+  fetchOfferingForPlacement: (placementIdentifier: string, userContext?: Record<string, any>) => Promise<any>;
+}
+
+export const useOfferings = ({
+  apiKey: apiKeyOverride,
+  skipFetch = false,
+  limit = 20,
+  offset = 0,
+  is_current,
+  is_default,
+  identifier,
+  expand,
+  sort_by = 'created_at',
+  sort_order = 'desc',
+}: UseOfferingsOptions): UseOfferingsResult => {
+  const [offerings, setOfferings] = useState<Offering[]>([]);
+  const [currentOffering, setCurrentOffering] = useState<Offering | null>(null);
+  const [allOfferings, setAllOfferings] = useState<Record<string, Offering> | null>(null);
+  const [pagination, setPagination] = useState<Pagination | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const resolvedApiKey = ApiClient.resolveApiKey(apiKeyOverride);
+  const deprecatedOptions = { apiKey: apiKeyOverride };
+
+  const fetchOfferings = async () => {
+    if (skipFetch || !resolvedApiKey) {
+      return;
+    }
+
+    setLoading(true);
+    setError(null);
+
+    try {
+      const body: any = {
+        limit,
+        offset,
+        sort_by,
+        sort_order,
+      };
+
+      if (is_current !== undefined) body.is_current = is_current;
+      if (is_default !== undefined) body.is_default = is_default;
+      if (identifier) body.identifier = identifier;
+      if (expand) body.expand = expand;
+
+      const json = await ApiClient.post('list-offerings', body, deprecatedOptions);
+      
+      // Phase M4: Extract from wrapped envelope { success, data, meta }
+      const data = json.data;
+      
+      setOfferings(data.offerings || []);
+      setCurrentOffering(data.current_offering || null);
+      setAllOfferings(data.all_offerings || null);
+      setPagination(data.pagination || null);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error('Unknown error'));
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  useEffect(() => {
+    fetchOfferings();
+  }, [resolvedApiKey, skipFetch, limit, offset, is_current, is_default, identifier, expand, sort_by, sort_order]);
+
+  const fetchCurrentOffering = useCallback(async (): Promise<Offering | null> => {
+    if (!resolvedApiKey) return null;
+    try {
+      const json = await ApiClient.post('fetch-offering', {
+        is_current: true,
+      }, deprecatedOptions);
+
+      const data = json.data;
+      return data.current_offering || null;
+    } catch (err) {
+      console.error('Error fetching current offering:', err);
+      return null;
+    }
+  }, [resolvedApiKey, apiKeyOverride]);
+
+  const fetchOfferingForPlacement = useCallback(async (
+    placementIdentifier: string,
+    userContext?: Record<string, any>
+  ): Promise<any> => {
+    if (!resolvedApiKey) return null;
+    try {
+      const json = await ApiClient.post('fetch-offerings-for-placement', {
+        placement_identifier: placementIdentifier,
+        ...userContext,
+      }, deprecatedOptions);
+
+      return json.data;
+    } catch (err) {
+      console.error('Error fetching offering for placement:', err);
+      return null;
+    }
+  }, [resolvedApiKey, apiKeyOverride]);
+
+  return {
+    offerings,
+    currentOffering,
+    allOfferings,
+    pagination,
+    loading,
+    error,
+    refetch: fetchOfferings,
+    fetchCurrentOffering,
+    fetchOfferingForPlacement,
+  };
+};

package/src/hooks/usePaywall.ts

@@ -0,0 +1,154 @@
+/**
+ * usePaywall Hook - Fetches paywall configuration from API
+ */
+
+import { useState, useEffect } from 'react';
+import { PaywallConfiguration } from '../types';
+import { AdvancedPaywallCache, AdvancedCacheConfig } from '../AdvancedPaywallCache';
+import { detectDeviceCategory } from '../utils/deviceDetection';
+import { resolveConfiguration, MultiPaywallConfig } from '../utils/configurationResolver';
+import { ApiClient } from '../utils/ApiClient';
+
+export interface UsePaywallOptions {
+  paywallIdentifier?: string;
+  /** @deprecated Use BillDogConfiguration.configure({ apiKey }) instead */
+  apiKey?: string;
+  skipFetch?: boolean;
+  cacheConfig?: Partial<AdvancedCacheConfig>;
+  userContext?: {
+    app_user_id?: string;
+    country?: string;
+    app_version?: string;
+    platform?: string;
+    sdk_version?: string;
+    custom_attributes?: Record<string, string>;
+  };
+}
+
+export interface UsePaywallResult {
+  configuration: PaywallConfiguration | null;
+  loading: boolean;
+  error: Error | null;
+  refetch: () => Promise<void>;
+}
+
+export const usePaywall = ({
+  paywallIdentifier,
+  apiKey: apiKeyOverride,
+  skipFetch = false,
+  cacheConfig,
+  userContext,
+}: UsePaywallOptions): UsePaywallResult => {
+  const [configuration, setConfiguration] = useState<PaywallConfiguration | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [cache] = useState(() => cacheConfig?.enabled !== false ? new AdvancedPaywallCache(cacheConfig || {}) : null);
+
+  const resolvedApiKey = ApiClient.resolveApiKey(apiKeyOverride);
+
+  const fetchPaywall = async () => {
+    if (skipFetch || !paywallIdentifier || !resolvedApiKey) {
+      return;
+    }
+
+    // Try cache first if enabled
+    if (cache) {
+      const cached = await cache.get(paywallIdentifier);
+      if (cached && Date.now() < cached.expiresAt) {
+        console.log(`[usePaywall] Cache HIT for ${paywallIdentifier}`);
+        setConfiguration(cached.paywall.configuration);
+        setLoading(false);
+        
+        // Check for updates in background
+        checkAndUpdateInBackground(paywallIdentifier, cached.version);
+        return;
+      }
+    }
+
+    setLoading(true);
+    setError(null);
+
+    try {
+      const json = await ApiClient.post('fetch-paywall', {
+        paywall_identifier: paywallIdentifier,
+        ...userContext,
+      }, {
+        apiKey: apiKeyOverride,
+      });
+      
+      // Phase M4: Extract from wrapped envelope { success, data, meta }
+      const data = json.data;
+      
+      if (data.paywall) {
+        // Detect device category
+        const deviceCategory = detectDeviceCategory();
+        
+        // Check if we have multi-config or single config
+        let resolvedConfig: PaywallConfiguration | null = null;
+        
+        if (data.paywall.configurations) {
+          // Multi-config mode
+          const multiConfig: MultiPaywallConfig = {
+            mode: data.paywall.configuration_mode || 'single',
+            ...data.paywall.configurations,
+          };
+          resolvedConfig = resolveConfiguration(multiConfig, deviceCategory);
+        } else if (data.paywall.configuration) {
+          // Single config mode (legacy)
+          resolvedConfig = data.paywall.configuration;
+        }
+        
+        if (!resolvedConfig) {
+          throw new Error('No configuration available for current device');
+        }
+        
+        setConfiguration(resolvedConfig);
+        
+        // Cache the result
+        if (cache) {
+          await cache.set(paywallIdentifier, {
+            paywall: data.paywall,
+            version: data.paywall.version || 1,
+            cachedAt: Date.now(),
+            expiresAt: Date.now() + (cacheConfig?.maxCacheAge || 604800000),
+          });
+        }
+      } else {
+        throw new Error('Invalid paywall data');
+      }
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error('Unknown error'));
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const checkAndUpdateInBackground = async (identifier: string, currentVersion: number) => {
+    try {
+      const versionInfo = await ApiClient.post('check-paywall-version', {
+        paywall_identifier: identifier,
+        current_version: currentVersion,
+      }, {
+        apiKey: apiKeyOverride,
+      });
+
+      if (versionInfo.has_update) {
+        console.log(`[usePaywall] New version available for ${identifier}`);
+        await fetchPaywall();
+      }
+    } catch (err) {
+      console.error('[usePaywall] Background update failed:', err);
+    }
+  };
+
+  useEffect(() => {
+    fetchPaywall();
+  }, [paywallIdentifier, resolvedApiKey, skipFetch]);
+
+  return {
+    configuration,
+    loading,
+    error,
+    refetch: fetchPaywall,
+  };
+};

package/src/hooks/usePlacement.ts

@@ -0,0 +1,143 @@
+/**
+ * usePlacement Hook — placement registration with a feature-callback model
+ * (API_Calls_Migration P4, Track D).
+ *
+ * Mirrors the iOS `register` / Android `registerFeature` feature gate:
+ *  - **non-gated** placement → `onFeatureUnlocked` runs immediately;
+ *  - **gated** placement → the paywall is presented (via the native bridge)
+ *    and `onFeatureUnlocked` runs only on an entitlement-granting outcome
+ *    (already-entitled / purchased / restored). A dismissed/errored outcome
+ *    does NOT run it.
+ *
+ * Gating is resolved in JS through the unified `get-wall-for-placement`
+ * endpoint (an unknown placement is auto-created server-side — P4 hybrid
+ * auto-create). `usePaywall` + `useOfferings` remain the escape-hatch hooks.
+ */
+
+import { useCallback, useState } from 'react';
+import { BillDog } from '../BillDog';
+import { ApiClient } from '../utils/ApiClient';
+import type { PlacementResult, PaywallPresentationHandler } from '../models/Placement';
+
+interface ResolvedPlacement {
+  paywallId: string | null;
+  gated: boolean;
+  holdout: boolean;
+}
+
+export interface UsePlacementResult {
+  /**
+   * Result-handler variant — register a placement and get the
+   * `PlacementResult`. The paywall (if any) is presented via the native bridge.
+   */
+  register: (
+    placementId: string,
+    params?: Record<string, unknown>,
+    handler?: PaywallPresentationHandler,
+  ) => Promise<PlacementResult>;
+  /**
+   * Feature-closure variant — Superwall's `register("feature") { unlock() }`.
+   * Non-gated → `onFeatureUnlocked` runs immediately; gated → it runs only
+   * when the placement yields entitlement (entitled / purchased / restored).
+   */
+  registerFeature: (
+    placementId: string,
+    onFeatureUnlocked: () => void,
+    params?: Record<string, unknown>,
+  ) => Promise<PlacementResult>;
+  /** True while a registration is in flight. */
+  loading: boolean;
+  /** The most recent `PlacementResult`, or null. */
+  lastResult: PlacementResult | null;
+}
+
+/** Resolve a placement in JS via `get-wall-for-placement` to learn its gating. */
+async function resolvePlacement(
+  placementId: string,
+  params?: Record<string, unknown>,
+): Promise<ResolvedPlacement | null> {
+  try {
+    const json: any = await ApiClient.post('get-wall-for-placement', {
+      placement_identifier: placementId,
+      ...(params ? { custom_attributes: params } : {}),
+    });
+    const data = json?.data ?? {};
+    if (data.placement?.source === 'sdk_autocreated') {
+      console.warn(
+        `[usePlacement] Placement '${placementId}' is unconfigured (auto-created on ` +
+          'first sighting). Configure it in the BillDog dashboard — or fix the ' +
+          'identifier if this is a typo.',
+      );
+    }
+    return {
+      paywallId: data.paywall?.id ?? null,
+      gated: data.presentation?.gated === true,
+      holdout: data.presentation?.holdout === true,
+    };
+  } catch {
+    // Resolution failed — caller falls back to presenting the paywall.
+    return null;
+  }
+}
+
+export const usePlacement = (): UsePlacementResult => {
+  const [loading, setLoading] = useState(false);
+  const [lastResult, setLastResult] = useState<PlacementResult | null>(null);
+
+  const register = useCallback(
+    async (
+      placementId: string,
+      params?: Record<string, unknown>,
+      handler?: PaywallPresentationHandler,
+    ): Promise<PlacementResult> => {
+      setLoading(true);
+      try {
+        const result = await BillDog.register(placementId, params, handler);
+        setLastResult(result);
+        return result;
+      } finally {
+        setLoading(false);
+      }
+    },
+    [],
+  );
+
+  const registerFeature = useCallback(
+    async (
+      placementId: string,
+      onFeatureUnlocked: () => void,
+      params?: Record<string, unknown>,
+    ): Promise<PlacementResult> => {
+      setLoading(true);
+      try {
+        const resolved = await resolvePlacement(placementId, params);
+
+        // Non-gated (or nothing to gate with) → unlock immediately.
+        if (resolved && (!resolved.gated || !resolved.paywallId)) {
+          onFeatureUnlocked();
+          const immediate: PlacementResult = { type: 'entitled' };
+          setLastResult(immediate);
+          return immediate;
+        }
+
+        // Gated — or resolution failed (fail safe by presenting). Present the
+        // paywall via the native bridge; unlock only on an entitlement outcome.
+        const result = await BillDog.register(placementId, params);
+        setLastResult(result);
+        if (
+          result.type === 'entitled' ||
+          result.type === 'purchased' ||
+          result.type === 'restored'
+        ) {
+          onFeatureUnlocked();
+        }
+        return result;
+      } finally {
+        setLoading(false);
+      }
+    },
+    [],
+  );
+
+  return { register, registerFeature, loading, lastResult };
+};

package/src/hooks/useSubscription.ts

@@ -0,0 +1,154 @@
+import { useState, useCallback } from 'react';
+import {
+  previewSubscriptionUpgrade,
+  upgradeSubscription,
+  downgradeSubscription,
+  type SubscriptionUpgradeOptions,
+  type ProrationPreview,
+  type SubscriptionUpgradeResult,
+} from '../utils/subscriptionUpgrade';
+
+
+export interface UseSubscriptionOptions {
+  /** @deprecated Use BillDogConfiguration.configure({ apiKey }) instead */
+  apiKey?: string;
+}
+
+export interface UseSubscriptionReturn {
+  /** Preview upgrade/downgrade costs before executing */
+  previewUpgrade: (newPriceId: string, options?: SubscriptionUpgradeOptions) => Promise<ProrationPreview>;
+  /** Upgrade to a higher-tier subscription */
+  upgradeSubscription: (newPriceId: string, options?: SubscriptionUpgradeOptions) => Promise<SubscriptionUpgradeResult>;
+  /** Downgrade to a lower-tier subscription */
+  downgradeSubscription: (newPriceId: string, options?: SubscriptionUpgradeOptions) => Promise<SubscriptionUpgradeResult>;
+  /** Whether an operation is in progress */
+  isLoading: boolean;
+  /** Last error that occurred */
+  error: Error | null;
+  /** Last proration preview */
+  preview: ProrationPreview | null;
+  /** Last upgrade/downgrade result */
+  result: SubscriptionUpgradeResult | null;
+  /** Clear error state */
+  clearError: () => void;
+}
+
+/**
+ * Hook for managing subscription upgrades and downgrades.
+ * 
+ * Credentials are resolved from `BillDogConfiguration` by default.
+ * Pass an `apiKey` override only for backward compatibility.
+ * 
+ * @example
+ * ```tsx
+ * // After calling BillDogConfiguration.configure({ apiKey: 'bd_...' })
+ * const { previewUpgrade, upgradeSubscription } = useSubscription();
+ * 
+ * const preview = await previewUpgrade('price_new_plan', {
+ *   customerId: 'customer_123',
+ * });
+ * ```
+ */
+export function useSubscription(options: UseSubscriptionOptions = {}): UseSubscriptionReturn {
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [preview, setPreview] = useState<ProrationPreview | null>(null);
+  const [result, setResult] = useState<SubscriptionUpgradeResult | null>(null);
+
+  const clearError = useCallback(() => {
+    setError(null);
+  }, []);
+
+  const handlePreviewUpgrade = useCallback(async (
+    newPriceId: string,
+    upgradeOptions?: SubscriptionUpgradeOptions
+  ): Promise<ProrationPreview> => {
+    setIsLoading(true);
+    setError(null);
+    
+    try {
+      const previewResult = await previewSubscriptionUpgrade(
+        options.apiKey,
+        newPriceId,
+        upgradeOptions
+      );
+      setPreview(previewResult);
+      return previewResult;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      setError(error);
+      throw error;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [options.apiKey]);
+
+  const handleUpgradeSubscription = useCallback(async (
+    newPriceId: string,
+    upgradeOptions?: SubscriptionUpgradeOptions
+  ): Promise<SubscriptionUpgradeResult> => {
+    setIsLoading(true);
+    setError(null);
+    
+    try {
+      const upgradeResult = await upgradeSubscription(
+        options.apiKey,
+        newPriceId,
+        upgradeOptions
+      );
+      setResult(upgradeResult);
+      
+      if (!upgradeResult.success) {
+        throw new Error(upgradeResult.errorMessage || 'Upgrade failed');
+      }
+      
+      return upgradeResult;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      setError(error);
+      throw error;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [options.apiKey]);
+
+  const handleDowngradeSubscription = useCallback(async (
+    newPriceId: string,
+    upgradeOptions?: SubscriptionUpgradeOptions
+  ): Promise<SubscriptionUpgradeResult> => {
+    setIsLoading(true);
+    setError(null);
+    
+    try {
+      const downgradeResult = await downgradeSubscription(
+        options.apiKey,
+        newPriceId,
+        upgradeOptions
+      );
+      setResult(downgradeResult);
+      
+      if (!downgradeResult.success) {
+        throw new Error(downgradeResult.errorMessage || 'Downgrade failed');
+      }
+      
+      return downgradeResult;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      setError(error);
+      throw error;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [options.apiKey]);
+
+  return {
+    previewUpgrade: handlePreviewUpgrade,
+    upgradeSubscription: handleUpgradeSubscription,
+    downgradeSubscription: handleDowngradeSubscription,
+    isLoading,
+    error,
+    preview,
+    result,
+    clearError,
+  };
+}