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

package/src/BillDog.ts

@@ -0,0 +1,983 @@
+/**
+ * BillDog — top-level RN facade.
+ *
+ * Spec:     PUR-063, PUR-064, PUR-080..085, PUR-121, PUR-122, PUR-140..146,
+ *           PUR-224, PUR-350, PUR-360, PUR-362, PUR-363, PUR-364
+ *           (.lovable/purchase-conformance-spec.md)
+ * Standard: mem://architecture/react-native/sdk-unified-standard
+ *           mem://architecture/customer-info-cache-standard
+ *           mem://architecture/entitlements-authoritative-standard
+ *           mem://architecture/purchase-conformance-standard
+ *
+ * Slice J (PUR-364) propagates the v1.4 purchase parity surface to the RN
+ * bridge with iOS/Android wire parity:
+ *  - `purchase(params)` — typed PurchaseParams, returns canonical PurchaseResult
+ *  - `purchase(custom)` — Superwall-style non-StoreKit products via host controller
+ *  - `setPurchaseController(...)` — JS-side controller for EXTERNAL/CUSTOM flows
+ *  - `setProxyURL` / `getProxyURL` — self-hosted proxy
+ *  - `canMakePayments`, `presentCodeRedemptionSheet`,
+ *    `checkTrialOrIntroDiscountEligibility`, `onStorefrontChange`
+ *  - 14-provider attribution matrix + `collectDeviceIdentifiers`
+ *
+ * Every method gracefully falls back when `NativeModules.BillDog` is null so
+ * consumer apps compile against the contract before the native bridge is wired
+ * in their host project. The facade NEVER throws across the public boundary —
+ * store/network errors are surfaced as typed result unions.
+ */
+
+import type { RestoreResult } from './models/RestoreResult';
+import type { CacheFetchPolicy } from './models/CacheFetchPolicy';
+import { DEFAULT_CACHE_FETCH_POLICY } from './models/CacheFetchPolicy';
+import {
+  type CustomerInfo,
+  entitlementsByProductId,
+} from './models/CustomerInfo';
+import type { EntitlementInfo } from './models/EntitlementInfo';
+import type { PurchaseParams } from './models/PurchaseParams';
+import { PurchaseParams as PurchaseParamsNS } from './models/PurchaseParams';
+import type { PurchaseResult } from './models/PurchaseResult';
+import type { CustomProduct } from './models/CustomProduct';
+import type {
+  PlacementResult,
+  PresentationResult,
+  PaywallPresentationHandler,
+} from './models/Placement';
+import type { BillDogDelegate } from './models/Delegate';
+import { AnalyticsManager } from './modules/Analytics';
+import { BillDogConfiguration } from './BillDogConfiguration';
+import { ApiClient } from './utils/ApiClient';
+
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const RN = (() => {
+  try {
+    return require('react-native');
+  } catch {
+    return null;
+  }
+})();
+
+const native: any = RN?.NativeModules?.BillDog ?? null;
+
+// Optional AsyncStorage for persisting currentUserId across launches.
+// Falls back to in-memory if the host app hasn't installed it.
+const AsyncStorage: any = (() => {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    return require('@react-native-async-storage/async-storage').default;
+  } catch {
+    return null;
+  }
+})();
+
+// -----------------------------------------------------------------------------
+// Identity API — Android parity (BillDog.kt: logIn, logOut, identify,
+// isAnonymous, getAppUserId, isConfigured, setSandboxMode).
+// Persisted across launches via AsyncStorage when available.
+// -----------------------------------------------------------------------------
+
+const CURRENT_USER_KEY = 'billdog.rn.currentUserId';
+let _currentUserId: string | null = null;
+
+// Rehydrate from storage on module load — best-effort, never throws.
+if (AsyncStorage?.getItem) {
+  AsyncStorage.getItem(CURRENT_USER_KEY)
+    .then((id: string | null) => {
+      if (id && !_currentUserId) _currentUserId = id;
+    })
+    .catch(() => {
+      /* ignore — degrade to in-memory */
+    });
+}
+
+/**
+ * PUR-142/224: multi-subscriber CustomerInfo emitter with replay-1 semantics.
+ * New subscribers immediately receive the most recent cached value (if any).
+ */
+type CustomerInfoListener = (info: CustomerInfo) => void;
+
+class CustomerInfoEmitter {
+  private listeners = new Set<CustomerInfoListener>();
+  private lastValue: CustomerInfo | null = null;
+
+  addListener(fn: CustomerInfoListener): { remove: () => void } {
+    this.listeners.add(fn);
+    if (this.lastValue) fn(this.lastValue);
+    return { remove: () => this.listeners.delete(fn) };
+  }
+
+  emit(info: CustomerInfo): void {
+    this.lastValue = info;
+    for (const l of this.listeners) l(info);
+  }
+
+  get latest(): CustomerInfo | null {
+    return this.lastValue;
+  }
+}
+
+const customerInfoEmitter = new CustomerInfoEmitter();
+
+/**
+ * PUR-364: Storefront country observer (iOS-only on the producer side; the
+ * RN bridge surfaces a no-op on Android until Play exposes a country API).
+ */
+type StorefrontListener = (storefront: { countryCode: string }) => void;
+const storefrontListeners = new Set<StorefrontListener>();
+
+/**
+ * PUR-364: JS-side PurchaseController contract — mirrors iOS/Android.
+ * Implementations MUST map user cancellation to `{type:'cancelled'}` and
+ * Ask-to-Buy / Android PENDING to `{type:'pending'}` — never `failed`.
+ */
+export interface PurchaseController {
+  purchase(productId: string): Promise<PurchaseResult>;
+  restorePurchases(): Promise<RestoreResult>;
+}
+
+let activeController: PurchaseController | null = null;
+let activeDelegate: BillDogDelegate | null = null;
+
+/** Stamp every receipt posted to BillDog's backend (PUR-185). */
+const sourceForResult = (): 'INTERNAL' | 'EXTERNAL' =>
+  activeController ? 'EXTERNAL' : 'INTERNAL';
+
+const cancelledResult: PurchaseResult = { type: 'cancelled' };
+
+const failedResult = (e: any, category: 'unknown' | 'network' = 'unknown'): PurchaseResult => ({
+  type: 'failed',
+  error: { category, message: e?.message ?? 'Purchase failed' },
+});
+
+/**
+ * Best-effort POST of an EXTERNAL (host-controller) custom-product purchase
+ * to BillDog's `record-external-purchase` endpoint, which resolves the
+ * catalog product from `providerProductId`, grants the entitlement, and
+ * reports revenue with `source = EXTERNAL`.
+ */
+async function recordExternalCustomPurchase(
+  product: CustomProduct,
+  transactionId?: string,
+  transactionType: string = 'initial_purchase'
+): Promise<void> {
+  const userId = BillDog.getAppUserId();
+  if (!userId) {
+    console.warn('[BD-EXTERNAL] Skipping record — app user id unresolved');
+    return;
+  }
+  const txId = transactionId || `ext_${Math.random().toString(36).substring(2)}${Date.now()}`;
+  const body = {
+    user_id: userId,
+    transaction_id: txId,
+    product_id: product.id,
+    provider: product.provider,
+    provider_product_id: product.providerProductId,
+    purchase_date: new Date().toISOString(),
+    store: 'external',
+    price: product.price,
+    currency: product.currency,
+    transaction_type: transactionType,
+  };
+  try {
+    await ApiClient.post('record-external-purchase', body);
+    console.log(`[BD-EXTERNAL] Recorded custom purchase '${product.id}' (provider=${product.provider})`);
+  } catch (e) {
+    console.warn(`[BD-EXTERNAL] record-external-purchase failed (not blocking):`, e);
+  }
+}
+
+/** SDK version constant — Android parity (BillDog.kt:51). */
+export const SDK_VERSION = '1.0.0-beta.2';
+
+export const BillDog = {
+  /** SDK version constant — re-exposed on the singleton for ergonomic access. */
+  SDK_VERSION,
+
+  // -------------------------------------------------------------------------
+  // PUR-350 / PUR-364 — Unified purchase API
+  // -------------------------------------------------------------------------
+
+  /**
+   * Purchase a product with typed `PurchaseParams`. Returns canonical
+   * `PurchaseResult` — NEVER throws across the public boundary.
+   *
+   * If a host `PurchaseController` is registered (see `setPurchaseController`),
+   * the controller drives the transaction and the receipt is stamped
+   * `source = EXTERNAL`. Otherwise the bundled native controller is used
+   * (`source = INTERNAL`).
+   */
+  async purchase(params: PurchaseParams): Promise<PurchaseResult> {
+    if (activeController) {
+      try {
+        return await activeController.purchase(params.productId);
+      } catch (e) {
+        return failedResult(e);
+      }
+    }
+    if (!native?.purchase) {
+      // Bridge not wired in host app — return cancelled so the UI is consistent.
+      return cancelledResult;
+    }
+    try {
+      const raw = await native.purchase({ ...params, source: sourceForResult() });
+      if (raw && typeof raw.type === 'string') return raw as PurchaseResult;
+      return cancelledResult;
+    } catch (e) {
+      return failedResult(e);
+    }
+  },
+
+  /**
+   * PUR-363: Purchase a Superwall-style non-StoreKit / non-Play product.
+   * Routing is ONLY through a host-provided PurchaseController.
+   */
+  async purchaseCustom(product: CustomProduct): Promise<PurchaseResult> {
+    if (!activeController) {
+      return failedResult(
+        new Error('CustomProduct requires a host PurchaseController. Call BillDog.setPurchaseController() first.'),
+      );
+    }
+    try {
+      const raw = await activeController.purchase(product.providerProductId);
+      if (raw && raw.type === 'purchased') {
+        // Best-effort EXTERNAL recording so the entitlement is granted and revenue reported.
+        recordExternalCustomPurchase(product, raw.transactionId).catch(() => {});
+        BillDog.getCustomerInfo('FETCH_CURRENT').catch(() => {});
+      }
+      return raw;
+    } catch (e) {
+      return failedResult(e);
+    }
+  },
+
+  /** Get the currently-registered host PurchaseController, or null. */
+  getPurchaseController(): PurchaseController | null {
+    return activeController;
+  },
+
+  /** Flush pending analytics events to the backend. */
+  async flushAnalytics(): Promise<void> {
+    try { await AnalyticsManager.getInstance().flush(); } catch { /* best-effort */ }
+  },
+
+  /** PUR-364: Register a host PurchaseController. Pass `null` to detach. */
+  setPurchaseController(controller: PurchaseController | null): void {
+    activeController = controller;
+    if (native?.setPurchaseControllerActive) {
+      try {
+        native.setPurchaseControllerActive(!!controller);
+      } catch {
+        /* bridge no-op */
+      }
+    }
+  },
+
+  /**
+   * Restore previous purchases (PUR-080).
+   *
+   *  - `{type:'restored', items: []}`         — nothing to restore
+   *  - `{type:'restored', items: [...]}`      — items resurfaced
+   *  - `{type:'failed', error: BillDogError}` — global failure
+   */
+  async restore(): Promise<RestoreResult> {
+    if (activeController) {
+      try {
+        return await activeController.restorePurchases();
+      } catch (e: any) {
+        return {
+          type: 'failed',
+          error: { category: 'unknown', message: e?.message ?? 'Restore failed' },
+        };
+      }
+    }
+    if (!native?.restore) {
+      return { type: 'restored', items: [] };
+    }
+    try {
+      const raw = await native.restore();
+      if (raw && (raw.type === 'restored' || raw.type === 'failed')) {
+        return raw as RestoreResult;
+      }
+      return { type: 'restored', items: [] };
+    } catch (e: any) {
+      return {
+        type: 'failed',
+        error: { category: 'unknown', message: e?.message ?? 'Restore failed' },
+      };
+    }
+  },
+
+  // -------------------------------------------------------------------------
+  // PUR-141/224 — CustomerInfo
+  // -------------------------------------------------------------------------
+
+  async getCustomerInfo(
+    policy: CacheFetchPolicy = DEFAULT_CACHE_FETCH_POLICY,
+  ): Promise<CustomerInfo | null> {
+    if (!native?.getCustomerInfo) {
+      return customerInfoEmitter.latest;
+    }
+    try {
+      const info = (await native.getCustomerInfo(policy)) as CustomerInfo;
+      customerInfoEmitter.emit(info);
+      return info;
+    } catch {
+      return customerInfoEmitter.latest;
+    }
+  },
+
+  customerInfoEmitter,
+
+  /**
+   * PUR-121: resolve entitlements unlocked by a [productId] from the local
+   * `productEntitlementMapping`. Used for instant gating.
+   */
+  entitlementsForProduct(productId: string): EntitlementInfo[] {
+    const info = customerInfoEmitter.latest;
+    if (!info) return [];
+    return entitlementsByProductId(info, productId);
+  },
+
+  // -------------------------------------------------------------------------
+  // PUR-201 / PUR-202 / PUR-330 / PUR-037 — store capability surface
+  // -------------------------------------------------------------------------
+
+  /** PUR-201: Can the device transact at all? (parental controls, MDM) */
+  async canMakePayments(): Promise<boolean> {
+    if (!native?.canMakePayments) return true;
+    try {
+      return !!(await native.canMakePayments());
+    } catch {
+      return true;
+    }
+  },
+
+  /** PUR-330: Present the App Store promo code redemption sheet (iOS-only). */
+  async presentCodeRedemptionSheet(): Promise<void> {
+    if (!native?.presentCodeRedemptionSheet) return;
+    try {
+      await native.presentCodeRedemptionSheet();
+    } catch {
+      /* ignore */
+    }
+  },
+
+  /**
+   * PUR-037: Check trial / intro-discount eligibility for an array of product
+   * ids. Returns a map of `productId` -> `'eligible' | 'ineligible' | 'unknown'`.
+   */
+  async checkTrialOrIntroDiscountEligibility(
+    productIds: string[],
+  ): Promise<Record<string, 'eligible' | 'ineligible' | 'unknown'>> {
+    if (!native?.checkTrialOrIntroDiscountEligibility) {
+      return Object.fromEntries(productIds.map((id) => [id, 'unknown']));
+    }
+    try {
+      return (await native.checkTrialOrIntroDiscountEligibility(productIds)) as Record<
+        string,
+        'eligible' | 'ineligible' | 'unknown'
+      >;
+    } catch {
+      return Object.fromEntries(productIds.map((id) => [id, 'unknown']));
+    }
+  },
+
+  /** PUR-202: Subscribe to storefront country changes (iOS-only producer). */
+  onStorefrontChange(listener: StorefrontListener): { remove: () => void } {
+    storefrontListeners.add(listener);
+    if (native?.subscribeStorefront) {
+      try {
+        native.subscribeStorefront();
+      } catch {
+        /* ignore */
+      }
+    }
+    return { remove: () => storefrontListeners.delete(listener) };
+  },
+
+  // -------------------------------------------------------------------------
+  // PUR-362 — Self-hosted proxy
+  // -------------------------------------------------------------------------
+
+  setProxyURL(url: string | null): void {
+    if (!native?.setProxyURL) return;
+    try {
+      native.setProxyURL(url);
+    } catch {
+      /* ignore */
+    }
+  },
+
+  // ---------------------------------------------------------------------------
+  // Consent (cross-SDK contract) — delegates to the native ConsentManager when the
+  // host wires the BillDog native module, and degrades to a no-op otherwise (this
+  // package is fallback-by-design; full native enforcement needs the BillDog native
+  // module + bridge registration on both platforms — tracked as a separate task).
+  // ---------------------------------------------------------------------------
+  setConsentRequired(required: boolean): void {
+    if (!native?.setConsentRequired) return;
+    try {
+      native.setConsentRequired(required);
+    } catch {
+      /* ignore */
+    }
+  },
+
+  setConsent(purpose: 'analytics' | 'replay' | 'messaging' | 'survey', granted: boolean): void {
+    if (!native?.setConsent) return;
+    try {
+      native.setConsent(purpose, granted);
+    } catch {
+      /* ignore */
+    }
+  },
+
+  setConsentGiven(given: boolean): void {
+    if (!native?.setConsentGiven) return;
+    try {
+      native.setConsentGiven(given);
+    } catch {
+      /* ignore */
+    }
+  },
+
+  async consentHeaderValue(): Promise<string | null> {
+    if (!native?.consentHeaderValue) return null;
+    try {
+      return (await native.consentHeaderValue()) ?? null;
+    } catch {
+      return null;
+    }
+  },
+
+  getProxyURL(): string | null {
+    if (!native?.getProxyURL) return null;
+    try {
+      return native.getProxyURL() ?? null;
+    } catch {
+      return null;
+    }
+  },
+
+  // -------------------------------------------------------------------------
+  // PUR-360 — Attribution matrix (14 providers, EXACT parity with the native
+  // SDKs: BillDog.kt / BillDog.swift). Each convenience setter forwards the
+  // provider's attribution key to the native `setAttribution` bridge, which
+  // delegates to the matching consent-gated native setter.
+  //
+  // Two provider groups, both natively backed:
+  //  - 11 "modern" providers routed through the native `setAttribution` map
+  //    (CleverTap … Segment).
+  //  - 3 MMP providers with dedicated native setters (Adjust, AppsFlyer,
+  //    Firebase). They share the same JS/bridge funnel — the bridge maps their
+  //    keys to `setAdjustId` / `setAppsflyerId` / `setFirebaseAppInstanceId`.
+  //
+  // NOTE: Branch, Amplitude and Singular are NOT supported natively and were
+  // removed (they were JS-only no-ops). `setIterableUserID` / `setFBAnonymousID`
+  // replace the previously-misnamed `setIterableID` / `setFirebaseAppInstanceID`.
+  // -------------------------------------------------------------------------
+
+  /**
+   * Set one or more attribution ids at once. Keys are the provider attribution
+   * keys (e.g. `mixpanelDistinctId`, `cleverTapId`, `iterableId`). Prefer the
+   * named convenience setters below unless batching.
+   */
+  setAttribution(data: Record<string, string>): void {
+    if (!native?.setAttribution) return;
+    try {
+      native.setAttribution(data);
+    } catch {
+      /* swallow — attribution is best-effort */
+    }
+  },
+
+  setCleverTapID: (id: string | null) => setAttributionKey('cleverTapId', id),
+  setMixpanelDistinctID: (id: string | null) => setAttributionKey('mixpanelDistinctId', id),
+  setOnesignalID: (id: string | null) => setAttributionKey('onesignalId', id),
+  setFBAnonymousID: (id: string | null) => setAttributionKey('fbAnonymousId', id),
+  setAirshipChannelID: (id: string | null) => setAttributionKey('airshipChannelId', id),
+  setMoEngageAnonymousID: (id: string | null) => setAttributionKey('moEngageAnonymousId', id),
+  setMparticleID: (id: string | null) => setAttributionKey('mparticleId', id),
+  setKochavaDeviceID: (id: string | null) => setAttributionKey('kochavaId', id),
+  setTenjinAnalyticsInstallationID: (id: string | null) => setAttributionKey('tenjinId', id),
+  setIterableUserID: (id: string | null) => setAttributionKey('iterableId', id),
+  setSegmentAnonymousID: (id: string | null) => setAttributionKey('segmentId', id),
+
+  // MMP providers — dedicated native setters, same JS/bridge funnel.
+  setAdjustId: (id: string | null) => setAttributionKey('adjustId', id),
+  setAppsflyerId: (id: string | null) => setAttributionKey('appsflyerId', id),
+  setFirebaseAppInstanceId: (id: string | null) => setAttributionKey('firebaseAppInstanceId', id),
+
+  /** Collect IDFA / GAID after consent has been granted. */
+  collectDeviceIdentifiers(): void {
+    if (!native?.collectDeviceIdentifiers) return;
+    try {
+      native.collectDeviceIdentifiers();
+    } catch {
+      /* ignore */
+    }
+  },
+
+  // -------------------------------------------------------------------------
+  // Identity API — Android parity (BillDog.kt:782/807/845/890/894/325)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Log in an app user. Persists the user id, propagates to the native bridge
+   * (if wired) and the analytics module. Throws on blank ids — mirrors KMP/Unity.
+   */
+  async logIn(appUserId: string): Promise<void> {
+    if (!appUserId || !appUserId.trim()) {
+      throw new Error('appUserId must be non-blank');
+    }
+    _currentUserId = appUserId;
+    if (AsyncStorage?.setItem) {
+      try {
+        await AsyncStorage.setItem(CURRENT_USER_KEY, appUserId);
+      } catch {
+        /* ignore — degrade to in-memory */
+      }
+    }
+    if (native?.logIn) {
+      try {
+        await native.logIn(appUserId);
+      } catch {
+        /* swallow — identity is also tracked locally */
+      }
+    }
+    try {
+      await AnalyticsManager.getInstance().identify(appUserId);
+    } catch {
+      /* analytics is best-effort */
+    }
+  },
+
+  /** Log out the current user and return to anonymous state. */
+  async logOut(): Promise<void> {
+    _currentUserId = null;
+    if (AsyncStorage?.removeItem) {
+      try {
+        await AsyncStorage.removeItem(CURRENT_USER_KEY);
+      } catch {
+        /* ignore */
+      }
+    }
+    if (native?.logOut) {
+      try {
+        await native.logOut();
+      } catch {
+        /* swallow */
+      }
+    }
+    try {
+      await AnalyticsManager.getInstance().reset();
+    } catch {
+      /* best-effort */
+    }
+  },
+
+  /**
+   * Identify a user with optional attributes. Behaves as `logIn` plus an
+   * analytics super-properties update for the supplied attributes.
+   */
+  async identify(userId: string, attributes?: Record<string, any>): Promise<void> {
+    await this.logIn(userId);
+    if (attributes && Object.keys(attributes).length > 0) {
+      try {
+        await AnalyticsManager.getInstance().setSuperProperties(attributes);
+      } catch {
+        /* analytics is best-effort */
+      }
+    }
+  },
+
+  /** True when no app user is currently logged in. */
+  isAnonymous(): boolean {
+    return !_currentUserId;
+  },
+
+  /** Returns the currently logged-in app user id, or null when anonymous. */
+  getAppUserId(): string | null {
+    return _currentUserId;
+  },
+
+  /**
+   * Mirrors Android `BillDog.isConfigured()` (BillDog.kt:325). Delegates to
+   * the configuration singleton so the apiKey-presence check lives in one place.
+   */
+  isConfigured(): boolean {
+    return BillDogConfiguration.isConfigured();
+  },
+
+  /**
+   * Cross-SDK parity stub matching KMP / Unity / Android. Toggles a local
+   * flag and forwards to the native bridge if wired; otherwise a documented
+   * no-op (sandbox is primarily controlled via API key prefix).
+   */
+  setSandboxMode(enabled: boolean): void {
+    if (native?.setSandboxMode) {
+      try {
+        native.setSandboxMode(enabled);
+      } catch {
+        /* ignore */
+      }
+    }
+  },
+
+  // -------------------------------------------------------------------------
+  // Placement registration — Android parity (BillDog.kt:981/990/1024/1938)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Register a placement and run the canonical placement flow: fetch config →
+   * check entitlement → present paywall if needed. Returns a `PlacementResult`
+   * describing the outcome. Optional `handler` receives lifecycle callbacks
+   * mirroring Android's `PaywallPresentationHandler`.
+   *
+   * Returns `{ type: 'entitled' }` immediately if the user already holds the
+   * placement's required entitlement (no paywall shown). Returns
+   * `{ type: 'error', message }` on any failure — never throws across the
+   * public boundary.
+   */
+  async register(
+    placementId: string,
+    params?: Record<string, unknown>,
+    handler?: PaywallPresentationHandler,
+  ): Promise<PlacementResult> {
+    if (!BillDogConfiguration.isConfigured()) {
+      const err = 'BillDog SDK not configured.';
+      handler?.onLoadingStateChange?.('failed');
+      handler?.onError?.(new Error(err));
+      handler?.onSkip?.('error');
+      return { type: 'error', message: err };
+    }
+    handler?.onLoadingStateChange?.('loading');
+
+    if (!native?.registerPlacement) {
+      // No native bridge — emit no-op success path so the contract is met.
+      handler?.onLoadingStateChange?.('ready');
+      handler?.onSkip?.('no_paywall_configured');
+      return { type: 'error', message: 'Native placement bridge not wired' };
+    }
+
+    try {
+      const raw = await native.registerPlacement({ placementId, params: params ?? {} });
+      const result = (raw && typeof raw.type === 'string'
+        ? raw
+        : { type: 'error', message: 'Malformed placement result' }) as PlacementResult;
+
+      switch (result.type) {
+        case 'entitled':
+          handler?.onLoadingStateChange?.('ready');
+          handler?.onSkip?.('user_has_entitlement');
+          break;
+        case 'purchased':
+        case 'dismissed':
+        case 'restored':
+          handler?.onLoadingStateChange?.('ready');
+          handler?.onPresent?.(placementId);
+          if (result.type === 'purchased') {
+            handler?.onPurchaseSuccess?.(result.productId);
+          }
+          handler?.onDismiss?.(placementId);
+          handler?.onFinish?.(placementId, true);
+          break;
+        case 'error':
+          handler?.onLoadingStateChange?.('failed');
+          handler?.onError?.(new Error(result.message));
+          handler?.onSkip?.('error');
+          break;
+      }
+      return result;
+    } catch (e: any) {
+      const msg = e?.message ?? 'Placement registration failed';
+      handler?.onLoadingStateChange?.('failed');
+      handler?.onError?.(new Error(msg));
+      handler?.onSkip?.('error');
+      return { type: 'error', message: msg };
+    }
+  },
+
+  /**
+   * Synchronous probe — does the current user have access to a placement?
+   * Returns `true` when the placement is unregistered or has no required
+   * entitlement (safe default matching Android's behaviour).
+   */
+  hasAccessForPlacement(placementId: string): boolean {
+    if (!native?.hasAccessForPlacement) return true;
+    try {
+      return !!native.hasAccessForPlacement(placementId);
+    } catch {
+      return true;
+    }
+  },
+
+  // Experiments & feature flags: the paywall-facade shim was removed. Use the
+  // standalone A/B module (BillDogABTest / ABTestManager) instead.
+
+  // ── In-app messages — Android parity (BillDog.kt:1969) ────────────
+
+  /** Open the IAM inbox / present a single message. */
+  async showInAppMessages(placementId?: string): Promise<void> {
+    if (native?.showInAppMessages) {
+      try { await native.showInAppMessages(placementId ?? null); } catch { /* ignore */ }
+    }
+  },
+
+  // ── Deep linking — Android parity (BillDog.kt:684) ────────────────
+
+  /** Route a deep link through the SDK. Returns true when handled. */
+  async handleDeepLink(uri: string): Promise<boolean> {
+    if (native?.handleDeepLink) {
+      try { return !!(await native.handleDeepLink(uri)); } catch { /* ignore */ }
+    }
+    return false;
+  },
+
+  // ── Component selection state — Android parity (BillDog.kt:1032–1044) ──
+
+  getSelectedProductIndex(componentId: string): number | null {
+    if (native?.getSelectedProductIndex) {
+      try { return native.getSelectedProductIndex(componentId); } catch { /* ignore */ }
+    }
+    return null;
+  },
+
+  setSelectedProductIndex(componentId: string, index: number): void {
+    if (native?.setSelectedProductIndex) {
+      try { native.setSelectedProductIndex(componentId, index); } catch { /* ignore */ }
+    }
+  },
+
+  // ── Theme override — Android parity (BillDog.kt:184) ──────────────
+
+  /** Apply runtime theme overrides. Map of token name → value. */
+  updateTheme(overrides: Record<string, string>): void {
+    if (native?.updateTheme) {
+      try { native.updateTheme(overrides); } catch { /* ignore */ }
+    }
+  },
+
+  /** Set the SDK-wide interface style. Pass `null` to follow system. */
+  setInterfaceStyle(style: 'light' | 'dark' | null): void {
+    if (native?.setInterfaceStyle) {
+      try { native.setInterfaceStyle(style); } catch { /* ignore */ }
+    }
+  },
+
+  // ── Subscription management — Android parity (BillDog.kt:1500) ────
+
+  /**
+   * Open the platform-native subscription management UI. iOS routes to
+   * the App Store; Android routes to Play Store; web throws since no
+   * platform UI is available.
+   */
+  async showManageSubscriptions(subscriptionId?: string): Promise<void> {
+    if (native?.showManageSubscriptions) {
+      try { await native.showManageSubscriptions(subscriptionId ?? null); } catch { /* ignore */ }
+    }
+  },
+
+  // ── Cache control — Android parity (BillDog.kt:1074, :1612) ───────
+
+  /** Clear all SDK caches (paywall configs, customer info, products). */
+  async clearCache(): Promise<void> {
+    if (native?.clearCache) {
+      try { await native.clearCache(); } catch { /* ignore */ }
+    }
+  },
+
+  /** Invalidate the cached customer info — next read triggers a refetch. */
+  async invalidateCustomerInfoCache(): Promise<void> {
+    if (native?.invalidateCustomerInfoCache) {
+      try { await native.invalidateCustomerInfoCache(); } catch { /* ignore */ }
+    }
+  },
+
+  // ── User attributes — Android parity (BillDog.kt:1714, :1729) ─────
+
+  /** Set typed attributes on the current user (targeting + analytics). */
+  async setUserAttributes(attributes: Record<string, unknown>): Promise<void> {
+    if (native?.setUserAttributes) {
+      try { await native.setUserAttributes(attributes); } catch { /* ignore */ }
+    }
+    // Also propagate to AnalyticsManager so events carry the same attrs.
+    try {
+      await AnalyticsManager.getInstance().setSuperProperties(attributes);
+    } catch { /* best-effort */ }
+  },
+
+  /** Get the current user attributes (snapshot). */
+  async getUserAttributes(): Promise<Record<string, unknown>> {
+    if (native?.getUserAttributes) {
+      try { return (await native.getUserAttributes()) ?? {}; } catch { /* ignore */ }
+    }
+    return {};
+  },
+
+  // ── External purchase observation — Android parity (BillDog.kt:1864–1878) ──
+
+  /** Notify BillDog that an externally-driven purchase has started. */
+  observePurchaseStart(productId: string): void {
+    if (native?.observePurchaseStart) {
+      try { native.observePurchaseStart(productId); } catch { /* ignore */ }
+    }
+  },
+
+  /** Notify BillDog that an externally-driven purchase succeeded. */
+  observePurchaseResult(productId: string, orderId?: string): void {
+    if (native?.observePurchaseResult) {
+      try { native.observePurchaseResult(productId, orderId ?? null); } catch { /* ignore */ }
+    }
+  },
+
+  /** Notify BillDog that an externally-driven purchase failed. */
+  observePurchaseError(productId: string, error: string): void {
+    if (native?.observePurchaseError) {
+      try { native.observePurchaseError(productId, error); } catch { /* ignore */ }
+    }
+  },
+
+  // ── BillDogDelegate — Android parity (BillDog.kt:71) ──────────────
+
+  /**
+   * Set the active delegate. Pass `null` to detach. All delegate callbacks
+   * are optional; the SDK fires the ones that are defined.
+   */
+  setDelegate(delegate: BillDogDelegate | null): void {
+    activeDelegate = delegate;
+  },
+
+  /** Internal — emit a typed lifecycle event to the delegate (if any). */
+  _emitDelegate<K extends keyof BillDogDelegate>(
+    event: K,
+    ...args: Parameters<NonNullable<BillDogDelegate[K]>>
+  ): void {
+    const fn = activeDelegate?.[event] as ((...a: any[]) => void) | undefined;
+    if (typeof fn === 'function') {
+      try {
+        fn(...args);
+      } catch {
+        /* delegate errors must not propagate into SDK flow */
+      }
+    }
+  },
+
+  /**
+   * Evaluate what would happen if `register(placementId)` were called, without
+   * presenting a paywall. Returns one of `paywall`, `userSubscribed`,
+   * `noPaywall`, `holdout`, or `error`.
+   */
+  async getPresentationResult(placementId: string): Promise<PresentationResult> {
+    if (!BillDogConfiguration.isConfigured()) {
+      return { type: 'error', message: 'BillDog SDK not configured.' };
+    }
+    if (!native?.getPresentationResult) {
+      return { type: 'noPaywall', reason: 'Native placement bridge not wired' };
+    }
+    try {
+      const raw = await native.getPresentationResult(placementId);
+      if (raw && typeof raw.type === 'string') return raw as PresentationResult;
+      return { type: 'error', message: 'Malformed presentation result' };
+    } catch (e: any) {
+      return { type: 'error', message: e?.message ?? 'Presentation evaluation failed' };
+    }
+  },
+
+  /**
+   * Execute a server-side paywall tap action (Route B).
+   * Delegates to native SDK bridge `executeAction` if present; falls back to direct
+   * JavaScript fetch request to `execute-paywall-action` Edge Function if native is absent.
+   */
+  async executeAction(
+    paywallId: string | null,
+    componentId: string,
+    actionType: string,
+    idempotencyKey: string | null = null,
+    metadata?: Record<string, any>
+  ): Promise<any> {
+    if (native?.executeAction) {
+      try {
+        return await native.executeAction(paywallId, componentId, actionType, idempotencyKey, metadata);
+      } catch (e: any) {
+        throw e;
+      }
+    }
+
+    try {
+      const endpoint = BillDogConfiguration.resolveEndpoint('execute-paywall-action');
+      const apiKey = BillDogConfiguration.getApiKey();
+      const appUserId = this.getAppUserId();
+
+      const body: Record<string, any> = {
+        paywall_id: paywallId,
+        component_id: componentId,
+        action_type: actionType,
+        idempotency_key: idempotencyKey,
+      };
+      if (appUserId) {
+        body.app_user_id = appUserId;
+      }
+      if (metadata) {
+        body.metadata = metadata;
+      }
+
+      const response = await fetch(endpoint, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-BillDog-API-Key': apiKey,
+        },
+        body: JSON.stringify(body),
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(errorText || `HTTP ${response.status}`);
+      }
+
+      return await response.json();
+    } catch (e: any) {
+      if (BillDogConfiguration.config.enableLogging) {
+        console.error('[BillDog] Failed to execute action:', e);
+      }
+      throw e;
+    }
+  },
+};
+
+/**
+ * Forward a single provider attribution id to the native `setAttribution`
+ * bridge. `null` is a documented no-op (native has no clear). Best-effort —
+ * native/bridge errors are swallowed so attribution never breaks a host app.
+ */
+function setAttributionKey(key: string, id: string | null): void {
+  if (!native?.setAttribution || id == null) return;
+  try {
+    native.setAttribution({ [key]: id });
+  } catch {
+    /* swallow — attribution is best-effort */
+  }
+}
+
+// Re-export the PurchaseParams namespace + builder for ergonomic imports.
+export { PurchaseParamsNS as PurchaseParams };
+
+export type { RestoreResult } from './models/RestoreResult';
+export type { RestoredItem, RestoreItemStatus } from './models/RestoredItem';
+export type { BillDogError } from './models/BillDogError';
+export type { CacheFetchPolicy } from './models/CacheFetchPolicy';
+export type { CustomerInfo } from './models/CustomerInfo';
+export type { EntitlementInfo, EntitlementState } from './models/EntitlementInfo';
+export type { PurchaseParams as PurchaseParamsType, GoogleReplacementMode } from './models/PurchaseParams';
+export type { PurchaseResult } from './models/PurchaseResult';
+export type { CustomProduct } from './models/CustomProduct';
+export type {
+  PlacementResult,
+  PresentationResult,
+  PaywallLoadingState,
+  SkipReason,
+  PostPurchaseBehavior,
+  PaywallPresentationHandler,
+} from './models/Placement';
+export type { BillDogDelegate } from './models/Delegate';
+