@advenue/react-native 0.8.0 → 1.0.0

package/src/index.ts

@@ -1,859 +1,323 @@
-import {
-  extractReferrerProperties,
-  parseInstallReferrer,
-  parseMetaInstallReferrer,
-} from '@advenue/install-referrer';
-import {
-  AdvenueClient,
-  type AdvenueConfig,
-  type Consent,
-  DEFAULT_ENDPOINT,
-  DEVICE_ID_KEY,
-  type DeepLink,
-  type DeviceInfo,
-  MemoryStorage,
-  type SecureStorageAdapter,
-  type StorageAdapter,
-  type TrackOptions,
-  resolveDurableDeviceId,
-  tcfToConsent,
-} from '@advenue/sdk-core';
-import { sha256Hex } from '@advenue/signing';
+/**
+ * `@advenue/react-native` — a bridge over the native Advenue SDKs.
+ *
+ * Everything that computes lives in Swift and Kotlin now. What remains here is
+ * the JavaScript API apps already call, plus the one thing only React Native
+ * can see: `Linking`. Sessions are not among them — both native SDKs observe
+ * the app's lifecycle themselves.
+ *
+ * The public surface is unchanged on purpose. An app upgrading across this
+ * release edits nothing.
+ */
 import pkg from '../package.json' with { type: 'json' };
-import { extractAemCampaignIds } from './aem';
 import { type DeepLinkHandle, setupDeepLinks } from './deep-links';
-import { type MMKVLike, createMMKVStorage } from './mmkv-storage';
-import {
-  type AppStateSubscription,
-  getAndroidNative,
-  getAppState,
-  getIosNative,
-  getLinking,
-  getOsVersion,
-  getPlatformOS,
-} from './native';
-import { createNativeSecureStore, createNativeStorage } from './native-storage';
-import type { TrackingAuthorizationStatus } from './native-types';
-import { type SecureStoreLike, createSecureStore } from './secure-store';
-
-export { createMMKVStorage } from './mmkv-storage';
-export type { MMKVLike } from './mmkv-storage';
-export { createSecureStore } from './secure-store';
-export type { SecureStoreLike } from './secure-store';
+import { getAndroidNative, getIosNative, getLinking, getPlatformOS } from './native';
+import type { NativeErrorEvent, TrackingAuthorizationStatus } from './native-types';
+import type { AdvenueConfig, Consent, DeepLink } from './types';
+
 export { parseDirectLink } from './deep-links';
-export type { AdvenueConfig, Consent, DeepLink, TrackOptions } from '@advenue/sdk-core';
 export { getAndroidNative, getIosNative } from './native';
+export type { AdvenueConfig, Consent, DeepLink, TrackOptions, ClientEventType } from './types';
 export type {
   AdvenueAndroidNativeModule,
-  AdvenueDeviceInfo,
+  AdvenueBridge,
   AdvenueIosNativeModule,
-  InstallReferrerResult,
-  MetaInstallReferrerResult,
-  NativeTcfData,
+  BridgeInitOptions,
   TrackingAuthorizationStatus,
 } from './native-types';
 
-/**
- * Resolves the device advertising id (IDFA on iOS, GAID on Android), gates it
- * on ATT authorization status (iOS) / limitAdTracking flag (Android), and on
- * DMA consent when the user is subject to GDPR.  Pushes the result — or an
- * empty object to clear — into the active client via `setAdvertisingId`.
- *
- * Fire-and-forget at call sites; errors are suppressed internally.
- */
-export async function resolveAdvertisingId(): Promise<void> {
-  const client = active();
-  const consent = client.getConsentData();
-  // When consent is required but not yet known, do not collect any ad id.
-  // Guards the cold-start window where init fires before the CMP result lands.
-  if (client.getRequireConsent() && consent == null) {
-    client.setAdvertisingId({});
-    return;
-  }
-  if (consent?.isUserSubjectToGDPR === true && consent.hasConsentForDataUsage !== true) {
-    client.setAdvertisingId({});
-    return;
-  }
-  const ios = getIosNative();
-  if (ios) {
-    const idfa =
-      ios.getTrackingAuthorizationStatus() === 'authorized' ? await ios.getAdvertisingId() : null;
-    // IDFV — first-party fraud/dedup signal only (NOT cross-network attribution;
-    // that would be "tracking" under ATT). Available without ATT for this reason.
-    const vendorId =
-      typeof (ios as { getIdentifierForVendor?: unknown }).getIdentifierForVendor === 'function'
-        ? ios.getIdentifierForVendor()
-        : null;
-    client.setAdvertisingId({ ...(idfa ? { idfa } : {}), ...(vendorId ? { vendorId } : {}) });
-    return;
-  }
-  const android = getAndroidNative();
-  if (
-    android &&
-    typeof (android as { getAdvertisingId?: unknown }).getAdvertisingId === 'function'
-  ) {
-    const r = await android.getAdvertisingId();
-    // App Set ID — first-party fraud/dedup signal only (Google forbids using it
-    // for ads/measurement). Available even when ad tracking is limited.
-    const vendorId =
-      typeof (android as { getAppSetId?: unknown }).getAppSetId === 'function'
-        ? await android.getAppSetId()
-        : null;
-    const adFields = r ? (r.limitAdTracking ? { limitAdTracking: true } : { gaid: r.id }) : {};
-    // SSAID fallback (Adjust parity): only when no usable GAID exists (no Play
-    // Services, or ad tracking limited). Play policy forbids linking a
-    // persistent device id to the advertising id, so a device WITH a usable
-    // GAID never reports its SSAID — the SSAID's job is reinstall detection
-    // and device dedup where GAID can't do it (first-party fraud use).
-    const hasUsableGaid = !!r && !r.limitAdTracking;
-    const rawAndroidId =
-      !hasUsableGaid && typeof (android as { getAndroidId?: unknown }).getAndroidId === 'function'
-        ? (android as { getAndroidId(): string | null }).getAndroidId()
-        : null;
-    // Mirror the server schema (events.ts androidIdSchema): a non-conforming
-    // OEM value attached to every event would 400 the whole batch and poison
-    // the queue — a malformed SSAID must degrade to "absent", never to loss.
-    const androidId =
-      rawAndroidId && /^[0-9a-fA-F]{8,32}$/.test(rawAndroidId) ? rawAndroidId : null;
-    client.setAdvertisingId({
-      ...adFields,
-      ...(vendorId ? { vendorId } : {}),
-      ...(androidId ? { androidId } : {}),
-    });
-    return;
-  }
-  client.setAdvertisingId({});
-}
-
-/** Field-wise equality for the small, flat Consent shape. */
-function consentEquals(a: Consent, b: Consent): boolean {
-  return (
-    a.isUserSubjectToGDPR === b.isUserSubjectToGDPR &&
-    a.hasConsentForDataUsage === b.hasConsentForDataUsage &&
-    a.hasConsentForAdsPersonalization === b.hasConsentForAdsPersonalization &&
-    a.hasConsentForAdStorage === b.hasConsentForAdStorage
-  );
-}
+/** Options this package used to act on and the native SDKs now decide. */
+const IGNORED_OPTIONS = ['mmkv', 'secureStore', 'sdkConfigFetcher', 'tcfDataCollection'] as const;
 
-/**
- * Reads IAB TCF v2 consent (written by a TCF-compliant CMP, e.g. Google UMP,
- * to the platform default store), maps it to the DMA Consent shape, and
- * pushes it into the active client. No-op — returning null — when consent was
- * set manually this session, the native module or its getter is absent, no
- * TCF data exists, or the freshly-mapped consent is identical to what the
- * client already has (skip-if-unchanged: avoids re-persisting to storage and
- * re-firing the ad-id resolve on every foreground when nothing changed):
- * absent/unchanged consent must stay untouched, never fabricated or re-churned.
- *
- * Must be called after `Advenue.initialize()` — like every facade method, it
- * throws via the uninitialized guard otherwise.
- */
-export function resolveDmaConsent(): Consent | null {
-  if (manualConsentSet) return null;
-  const native = getIosNative() ?? getAndroidNative();
-  if (!native || typeof native.getTcfData !== 'function') return null;
-  let consent: Consent | null = null;
-  try {
-    consent = tcfToConsent(native.getTcfData());
-  } catch (err) {
-    reportError('consent.tcfRead', err);
-    return null;
-  }
-  if (!consent) return null;
-  const client = active();
-  const current = client.getConsentData();
-  if (current && consentEquals(current, consent)) return null;
-  client.setConsentData(consent);
-  // Consent feeds the ad-id gate — re-resolve, same as manual setConsentData.
-  void resolveAdvertisingId().catch((err) => reportError('enrich.advertisingId', err));
-  return consent;
-}
-
-/**
- * Collects native device metadata (model, locale, screen, cpu, storage, timezone)
- * used to populate Meta CAPI `extinfo`. Reads from the platform-appropriate
- * native module's `getDeviceInfo()`; returns `{}` when the native module or the
- * method is unavailable (bare React Native without the native SDK, web, Expo
- * Go, or an older native build predating this method). Never throws — any
- * native-side error degrades to an empty object so callers can unconditionally
- * pass the result through.
- */
-export function collectDeviceInfo(natives: {
-  platform: 'ios' | 'android' | string;
-  ios?: { getDeviceInfo?: () => Partial<DeviceInfo> } | null;
-  android?: { getDeviceInfo?: () => Partial<DeviceInfo> } | null;
-}): DeviceInfo {
-  try {
-    if (natives.platform === 'android' && natives.android?.getDeviceInfo) {
-      return natives.android.getDeviceInfo();
-    }
-    if (natives.platform === 'ios' && natives.ios?.getDeviceInfo) {
-      return natives.ios.getDeviceInfo();
-    }
-  } catch {
-    // native call failed — degrade to empty; extinfo will use "" placeholders
-  }
-  return {};
-}
-
-export interface RNAdvenueConfig extends Omit<AdvenueConfig, 'storage' | 'platform'> {
-  /**
-   * Auto-detected from React Native's `Platform.OS` — omit it. Pass explicitly
-   * only outside a React Native runtime (tests, custom embeddings); `ios` and
-   * `android` map verbatim, any other RN target (web, desktop) reports as
-   * `web`.
-   */
-  platform?: AdvenueConfig['platform'];
-  /**
-   * @internal Storage override (tests / custom embeddings). The SDK persists
-   * via its own native modules (UserDefaults/SharedPreferences) — apps never
-   * supply storage. When set, it replaces the built-in native storage.
-   */
-  mmkv?: MMKVLike;
-  /**
-   * G3.1n — Play Integrity (Android) / App Attest (iOS) attestation.
-   *
-   * Your app's Advenue appId (the UUID in Settings → API Keys). When set on
-   * Android, the automatic install obtains a Play Integrity Standard token and
-   * attaches it to the install event. The requestHash is computed as
-   * `sha256Hex("<appId>:<deviceId>")`, matching the server's verification
-   * formula exactly (see `makeDecodeAndroid` in the worker).
-   *
-   * Omit to run without attestation (the server field stays `unavailable`).
-   */
-  appId?: string;
-  /**
-   * @internal Secure-store override (tests / custom embeddings). The SDK uses
-   * its own Keychain-backed native storage on iOS for the reinstall-resilient
-   * device identity — apps never supply a secure store. When set, it replaces
-   * the built-in Keychain adapter.
-   */
-  secureStore?: SecureStoreLike;
-  /**
-   * Unified deep-link callback (AppsFlyer UDL style). Fires for both direct
-   * Universal/App Links (the OS opened the app via a link) and deferred deep
-   * links (resolved after an attributed install). The SDK never navigates — the
-   * host app reads `link.deepLinkValue` and routes. Inspect `link.isDeferred`
-   * to distinguish the two. Omit to disable deep-link handling entirely.
-   */
-  onDeepLink?: (link: DeepLink) => void;
-  /**
-   * @internal Test hook — disables the automatic install fired by
-   * `initialize()`. Install tracking is always automatic in production (there
-   * is no public `trackInstall`); tests turn it off to exercise the internal
-   * install path deterministically.
-   */
+export interface RNAdvenueConfig extends AdvenueConfig {
+  /** Meta app id, for the Meta install referrer on Android. */
+  fbAppId?: string;
+  /** Fires automatically unless set to false. */
   autoTrackInstall?: boolean;
-  /**
-   * Auto-collect IAB TCF v2 consent written by a TCF-compliant CMP (e.g.
-   * Google UMP) and attach it to every event as DMA consent data (AppsFlyer
-   * `enableTCFDataCollection` parity). Read at init and re-read on each
-   * foreground, so a CMP decision made after startup lands on later events.
-   * A manual `setConsentData()` call always wins. Default false.
-   */
+  /** Called when a link resolves, deferred or direct. */
+  onDeepLink?: (link: DeepLink) => void;
+  /** Firebase App Instance ID, if the app has Firebase Analytics. */
+  appInstanceIdProvider?: () => Promise<string | null>;
+  /** Accepted and ignored — the native SDKs own storage. */
+  mmkv?: unknown;
+  secureStore?: unknown;
+  sdkConfigFetcher?: unknown;
   tcfDataCollection?: boolean;
 }
 
-/**
- * Maps a React Native AppState status to the client's session lifecycle hooks.
- * Exported for testing. 'inactive' (transient on iOS) is intentionally ignored
- * so brief interruptions (Control Center, incoming call) don't end the session.
- */
-export function applyAppState(
-  client: Pick<AdvenueClient, 'notifyAppActive' | 'notifyAppBackground'>,
-  status: string,
-): void {
-  if (status === 'active') {
-    client.notifyAppActive();
-  } else if (status === 'background') {
-    client.notifyAppBackground();
-  }
-}
+// --- module state -----------------------------------------------------------
+//
+// Four values, where there used to be eighteen. Everything else was state the
+// TypeScript core needed to compute, and computing is not this package's job
+// any more.
 
-let instance: AdvenueClient | null = null;
-let appStateSub: AppStateSubscription | null = null;
+let started = false;
 let deepLinkSub: DeepLinkHandle | null = null;
-let secureStore: SecureStorageAdapter | null = null;
-// Sync storage (MMKV) reference for client-side install dedup without a secure
-// store wired. Set in initialize() alongside the client.
-let installFlagStore: StorageAdapter | null = null;
-const INSTALL_SENT_KEY = 'advenue.install_sent';
-// In-memory same-process dedup guard. Prevents a rapid double-call (e.g. two
-// concurrent trackInstall() in the same process) from enqueuing two install
-// events while the async referrer/ad-id resolution is in-flight.
-// Does NOT replace the durable flag (which guards across process restarts);
-// reset in shutdown() so tests and multi-lifecycle scenarios behave correctly.
-let installInFlight = false;
-// Auto-install deferral: set by initialize() when autoTrackInstall is on but the
-// consent gate (requireConsent without a grant) blocks tracking. Consumed by the
-// consent-granting paths (setTrackingConsent / requestTrackingAuthorization).
-let autoInstallPending = false;
-// Whether the current initialize() opted into auto install. Gates re-arming the
-// deferral when an in-flight install is dropped by a mid-flight consent
-// revocation — manual-mode integrators retry trackInstall() themselves.
-let autoInstallEnabled = true;
-// D5: an explicit setConsentData() call disables auto-TCF application for the
-// rest of the session (AppsFlyer semantics: manual wins). Reset by
-// initialize()/shutdown().
-let manualConsentSet = false;
-// Whether the current initialize() opted into TCF auto-collection
-// (RNAdvenueConfig.tcfDataCollection). Reset by initialize()/shutdown().
-let tcfCollectionEnabled = false;
-// G3.1n: app-scoped id for attestation requestHash. Set from RNAdvenueConfig.appId
-// in initialize(). Null when the integrator has not configured attestation.
-let configuredAppId: string | null = null;
-// G3.2n: API key + endpoint needed to fetch the App Attest challenge from the
-// server. Stored at module level so trackInstall() can issue the challenge
-// request without reaching into the private AdvenueClient fields.
-//
-// The challenge route `/v1/attest/challenge` is served by the INGESTION service
-// (alongside `/v1/events`), not the api/dashboard service — so it must be fetched
-// from `endpoint`, not `apiEndpoint`. On any deploy where the two hosts differ
-// (the default, and every split self-host), targeting apiEndpoint 404s and
-// attestation silently never works.
-let configuredApiKey: string | null = null;
-let configuredEndpoint = DEFAULT_ENDPOINT;
-// Meta AEM campaign_ids capture: per-process dedup so a URL delivered twice in
-// one open (cold-start + a redundant warm listener re-delivery) enqueues only
-// one adv_meta_aem event. Keyed on the sourceUrlHash (sha256 of the raw URL),
-// not the campaign_ids blob, so two distinct URLs carrying the same blob
-// still each get their own event. Cleared in shutdown().
-const aemSeenUrlHashes = new Set<string>();
-
-function active(): AdvenueClient {
-  if (!instance) {
-    throw new Error('Advenue.initialize() must be called before tracking events.');
-  }
-  return instance;
-}
+let errorSub: { remove(): void } | null = null;
+let onErrorHook: ((context: string, cause: unknown) => void) | undefined;
 
 /**
- * Routes a best-effort RN-layer failure (native enrichment, attestation, durable
- * flag write) through the active client's diagnostics, so the host app's
- * `onError` hook / `debug` log can observe it. No-op before initialize().
+ * `getTrackingConsent` is synchronous in JavaScript and the value lives in the
+ * native engine, so it is answered from here rather than by a round trip — an
+ * Expo call onto the JS thread per read is a cost an app pays in a render loop.
+ *
+ * It is **seeded at initialize** from the native value. Consent is persisted
+ * and survives restarts, so an unseeded cache would answer "not granted" on
+ * every cold start and silently discard a preference the user actually gave.
  */
-function reportError(context: string, cause: unknown): void {
-  instance?.report(context, cause);
-}
+let consentCache = false;
 
-/**
- * Fire-and-forget install used by the auto-install paths (initialize and the
- * consent-granting deferral). Failures surface via diagnostics — auto tracking
- * must never reject into the host app.
- */
-function fireAutoInstall(): void {
-  void trackInstall().catch((err) => reportError('install.auto', err));
+function bridge(): {
+  ios: ReturnType<typeof getIosNative>;
+  android: ReturnType<typeof getAndroidNative>;
+} {
+  return { ios: getIosNative(), android: getAndroidNative() };
 }
 
-/**
- * Resolves the event platform: an explicit config value wins; otherwise React
- * Native's `Platform.OS` (`ios`/`android` verbatim, any other RN target →
- * `web`). Throws outside a React Native runtime rather than guessing — a
- * wrong-platform default would misattribute every event from the device.
- */
-function resolvePlatform(explicit?: AdvenueConfig['platform']): AdvenueConfig['platform'] {
-  if (explicit) {
-    return explicit;
-  }
-  const os = getPlatformOS();
-  if (os === 'ios' || os === 'android') {
-    return os;
-  }
-  if (os) {
-    return 'web';
+/** Calls the first native module that has `name`. */
+function call<T>(name: string, ...args: unknown[]): T | undefined {
+  const { ios, android } = bridge();
+  for (const mod of [ios, android]) {
+    const fn = (mod as Record<string, unknown> | null)?.[name];
+    if (typeof fn === 'function') {
+      try {
+        return (fn as (...a: unknown[]) => T)(...args);
+      } catch (error) {
+        report(`bridge.${name}`, error);
+        return undefined;
+      }
+    }
   }
-  throw new Error(
-    "Advenue.initialize(): platform could not be detected (react-native unavailable) — pass platform: 'ios' | 'android' | 'web'.",
-  );
+  return undefined;
 }
 
-/** Consumes a pending consent-deferred auto install once consent is granted. */
-function fireAutoInstallIfPending(): void {
-  if (!autoInstallPending) {
-    return;
+function report(context: string, cause: unknown): void {
+  try {
+    onErrorHook?.(context, cause);
+  } catch {
+    // A throwing diagnostics hook must never break the SDK.
   }
-  autoInstallPending = false;
-  fireAutoInstall();
 }
 
-/**
- * React Native entry point. Wires MMKV-backed offline buffering automatically
- * and re-exports the same track surface as the core SDK.
- */
+function requireStarted(): boolean {
+  if (started) return true;
+  // A no-op, not a throw: an SDK that traps when called out of order takes the
+  // host app down with it.
+  report('sdk.notInitialized', new Error('Advenue.initialize() has not been called'));
+  return false;
+}
+
 export const Advenue = {
-  async initialize(config: RNAdvenueConfig): Promise<AdvenueClient> {
-    const {
-      mmkv,
-      secureStore: secureMod,
-      onDeepLink,
-      appId,
-      autoTrackInstall,
-      tcfDataCollection,
-      ...rest
-    } = config;
-    // A deferral armed by a previous initialize() must not leak into this one —
-    // a stale pending would override this config's autoTrackInstall opt-out.
-    autoInstallPending = false;
-    manualConsentSet = false;
-    tcfCollectionEnabled = tcfDataCollection === true;
-    autoInstallEnabled = autoTrackInstall !== false;
-    const platform = resolvePlatform(rest.platform);
-    configuredAppId = appId ?? null;
-    configuredApiKey = config.apiKey;
-    configuredEndpoint = config.endpoint ?? DEFAULT_ENDPOINT;
-    appStateSub?.remove();
-    appStateSub = null;
-    deepLinkSub?.remove();
-    deepLinkSub = null;
-    instance?.shutdown();
-    // Built-in storage: the SDK's own native modules persist state
-    // (UserDefaults/SharedPreferences + iOS Keychain, Adjust-style) — the app
-    // supplies nothing. In-memory fallback covers Expo Go / web / old natives.
-    const iosMod = getIosNative();
-    const androidMod = getAndroidNative();
-    const storage = mmkv
-      ? createMMKVStorage(mmkv)
-      : (createNativeStorage(iosMod ?? androidMod) ?? new MemoryStorage());
-    installFlagStore = storage;
-    secureStore = secureMod ? createSecureStore(secureMod) : createNativeSecureStore(iosMod);
-    const deviceId =
-      rest.deviceId ?? (await resolveDurableDeviceId(storage, secureStore ?? undefined));
-    // Auto-collect the OS release version — it feeds the server's normalized
-    // probabilistic fingerprint (spec D1); an explicit config value wins.
-    const osVersion = rest.osVersion ?? getOsVersion() ?? undefined;
-    instance = new AdvenueClient({
-      ...rest,
-      platform,
-      deviceId,
-      storage,
-      ...(osVersion ? { osVersion } : {}),
-    });
-    // One-line ground truth for "which SDK build talks to which host" — the
-    // exact questions a silent integration always raises first.
-    instance.debugLog(`SDK v${pkg.version} — events -> ${configuredEndpoint}`);
-    // TCF auto-collection (opt-in): populate DMA consent before the ad-id
-    // resolve below and before any event is enqueued.
-    if (tcfCollectionEnabled) resolveDmaConsent();
-    // (a) resolve ad-id at init time
-    void resolveAdvertisingId().catch((err) => reportError('enrich.advertisingId', err));
-    // Collect native device info (Meta CAPI extinfo) once at init time; a
-    // best-effort, synchronous read, so no fire-and-forget needed.
-    const deviceInfo = collectDeviceInfo({
-      platform,
-      ios: getIosNative(),
-      android: getAndroidNative(),
-    });
-    if (Object.keys(deviceInfo).length > 0) instance.setDeviceInfo(deviceInfo);
-    if (!config.disableAutoSessions) {
-      const appState = getAppState();
-      if (appState) {
-        (appStateSub as AppStateSubscription | null)?.remove();
-        // C5: guard against the platform delivering a redundant initial 'active'
-        // event after cold-start. We fire the cold-start session synchronously
-        // via notifyAppActive(), then suppress any subsequent 'active' from the
-        // listener until a 'background' has been seen in between — that way the
-        // platform's initial delivery is a no-op instead of a second session_start.
-        let seenBackground = false;
-        const handler = (status: string) => {
-          if (!instance) return;
-          if (status === 'background') {
-            seenBackground = true;
-            // The CMP dialog usually completes mid-foreground, so the
-            // background flush is the first moment that decision can leave
-            // the device — refresh TCF consent BEFORE applyAppState()
-            // enqueues session_end, so it ships with the flush rather than
-            // one session late.
-            if (tcfCollectionEnabled) resolveDmaConsent();
-            applyAppState(instance, status);
-          } else if (status === 'active') {
-            if (!seenBackground) return; // suppress: platform initial 'active' after cold-start
-            seenBackground = false;
-            // CMP dialogs usually complete after init — refresh TCF consent
-            // BEFORE applyAppState() enqueues session_start, so that event (and
-            // the ad-id re-resolve below) see the up-to-date consent instead of
-            // a stale snapshot from before the CMP decision changed.
-            if (tcfCollectionEnabled) resolveDmaConsent();
-            applyAppState(instance, status);
-            // (c) re-resolve ad-id on foreground (after a real background→active transition)
-            void resolveAdvertisingId().catch((err) => reportError('enrich.advertisingId', err));
-          }
-        };
-        appStateSub = appState.addEventListener('change', handler);
-        instance.notifyAppActive(); // cold-start session
-      } else {
-        instance.notifyAppActive(); // non-RN / test env fallback
+  /**
+   * Starts the SDK. Safe to call from the app's entry point, and safe to call
+   * twice: the native side replaces its previous instance.
+   */
+  async initialize(config: RNAdvenueConfig): Promise<void> {
+    onErrorHook = config.onError;
+
+    for (const option of IGNORED_OPTIONS) {
+      if ((config as unknown as Record<string, unknown>)[option] !== undefined) {
+        // Reported rather than dropped: passing storage to an SDK that owns its
+        // own storage should not look like it worked.
+        report(
+          `config.ignored:${option}`,
+          new Error(`${option} is decided by the native SDK and has no effect`),
+        );
       }
     }
-    {
-      // The OS-link listener is set up unconditionally — Meta AEM capture
-      // (onDirectUrl below) must run regardless of whether the integrator
-      // wants navigation callbacks; the old `if (onDeepLink)` gate silently
-      // disabled capture whenever onDeepLink was omitted. `onDeepLink` itself
-      // stays optional: a no-op stands in when the integrator didn't pass one.
-      const linking = getLinking();
-      if (linking) {
-        const client = instance;
-        deepLinkSub = setupDeepLinks({
-          getInitialURL: () => linking.getInitialURL(),
-          addUrlListener: (handler) => linking.addEventListener('url', (e) => handler(e.url)),
-          // Deferred deep link: server-side conversion poll (deterministic ids
-          // where available, probabilistic otherwise).
-          resolveDeferred: () => client.resolveDeferredDeepLink(),
-          onDeepLink: onDeepLink ?? (() => {}),
-          onDirectUrl: (url, link) => {
-            const raw = link.params?.al_applink_data;
-            if (typeof raw !== 'string') return;
-            const campaignIds = extractAemCampaignIds(raw);
-            if (!campaignIds) return;
-            const sourceUrlHash = sha256Hex(url);
-            // Cold-start + warm-listener can deliver the same URL twice in
-            // one open — one marker per distinct URL per process.
-            if (aemSeenUrlHashes.has(sourceUrlHash)) return;
-            // Consent gate closed: client.track() silently drops the event.
-            // Don't burn the dedup slot on a URL that never actually got
-            // enqueued — otherwise it could never fire even after consent is
-            // later granted. Mirrors the auto-install consent gate check.
-            if (client.getRequireConsent() && !client.getTrackingConsent()) return;
-            client.track('adv_meta_aem', { campaignIds, sourceUrlHash });
-            aemSeenUrlHashes.add(sourceUrlHash);
-          },
+
+    Advenue.shutdown();
+
+    call('bridgeInitialize', {
+      apiKey: config.apiKey,
+      endpoint: config.endpoint,
+      appVersion: config.appVersion,
+      requireConsent: config.requireConsent ?? false,
+      batchSize: config.batchSize,
+      flushIntervalMs: config.flushIntervalMs,
+      signingSecret: config.signingSecret,
+      fbAppId: config.fbAppId,
+      autoTrackInstall: config.autoTrackInstall !== false,
+      sdkVersion: pkg.version,
+    });
+    started = true;
+
+    // Subscribed BEFORE anything else the native side can fail at, so a
+    // failure during startup is reported rather than missed.
+    //
+    // `onError` is a JavaScript closure and cannot cross the bridge, so the
+    // native side emits an event instead and this turns it back into a call.
+    // Without it the SDK's own swallowed failures reach nobody — which is
+    // exactly what the docs promise they do not.
+    const { ios: iosForErrors, android: androidForErrors } = bridge();
+    const emitter = (iosForErrors ?? androidForErrors) as {
+      addListener?: (name: string, handler: (e: NativeErrorEvent) => void) => { remove(): void };
+    } | null;
+    if (typeof emitter?.addListener === 'function') {
+      try {
+        errorSub = emitter.addListener('onAdvenueError', (event) => {
+          report(event.context, new Error(event.message));
         });
-        // Cold-start resolution is fire-and-forget: a failure (Linking or the
-        // deferred poll rejecting) must surface via diagnostics, never as an
-        // unhandled rejection crashing the host app.
-        deepLinkSub.ready.catch((err) => reportError('deepLink.resolve', err));
+      } catch (error) {
+        report('diagnostics.subscribe', error);
       }
     }
-    if (autoTrackInstall !== false) {
-      if (instance.getRequireConsent() && !instance.getTrackingConsent()) {
-        // Consent gate is closed — defer to the consent-granting paths so the
-        // install is neither dropped nor fired pre-consent.
-        autoInstallPending = true;
-        instance.debugLog('install deferred until consent is granted');
-      } else {
-        // Fire-and-forget: referrer/attestation resolution must not delay init.
-        fireAutoInstall();
+
+    // Seeded, not defaulted — see `consentCache`.
+    consentCache = call<boolean>('bridgeGetConsent') ?? false;
+
+    if (config.appInstanceIdProvider) {
+      try {
+        const id = await config.appInstanceIdProvider();
+        if (id) call('bridgeSetAppInstanceId', id);
+      } catch (error) {
+        report('enrich.appInstanceId', error);
       }
     }
-    return instance;
+
+    // No lifecycle code here, on either platform.
+    //
+    // Both native SDKs observe the app themselves now — Android through
+    // ActivityLifecycleCallbacks, iOS through the UIApplication notifications.
+    // This used to drive iOS from an AppState listener, and that was the wrong
+    // place: the asymmetry it created (iOS driven from JS, Android not) is a
+    // trap every wrapper would have had to re-learn, and driving both would
+    // have counted every Android session twice.
+
+    // Links. The listener is unconditional: the native side captures Meta AEM
+    // from the URL regardless of whether the integrator wants a navigation
+    // callback, and gating it on `onDeepLink` silently disabled capture.
+    const linking = getLinking();
+    if (linking) {
+      deepLinkSub = setupDeepLinks({
+        getInitialURL: () => linking.getInitialURL(),
+        addUrlListener: (handler) => linking.addEventListener('url', (e) => handler(e.url)),
+        resolveDeferred: () => Advenue.resolveDeferredDeepLink(),
+        onDeepLink: config.onDeepLink ?? (() => {}),
+        onDirectUrl: (url) => {
+          call('bridgeProcessDeepLink', url);
+        },
+      });
+      // Fire-and-forget: a failure must surface as a diagnostic, never as an
+      // unhandled rejection crashing the host app.
+      deepLinkSub.ready.catch((error) => report('deepLink.resolve', error));
+    }
+  },
+
+  track(name: string, properties?: Record<string, unknown>): void {
+    if (!requireStarted()) return;
+    call('bridgeTrack', name, properties ?? null);
+  },
+
+  /** Adds exact local revenue to Apple's conversion-value state. iOS only. */
+  async recordSkanRevenue(input: { amount: string; currency: string }): Promise<void> {
+    if (!requireStarted()) return;
+    call('bridgeRecordSkanRevenue', input.amount, input.currency);
+  },
+
+  setAppInstanceId(id: string | null): void {
+    if (!requireStarted()) return;
+    call('bridgeSetAppInstanceId', id);
+  },
+
+  /**
+   * Cross-device linking: associates subsequent events with your user id.
+   * Pass null to clear.
+   *
+   * New on this object. The previous release reached it through the client
+   * `initialize()` resolved to, and that client no longer exists — so it is
+   * promoted here rather than dropped, which is what an app following the
+   * documented cross-device recipe would otherwise hit at runtime.
+   */
+  setUserId(id: string | null): void {
+    if (!requireStarted()) return;
+    call('bridgeSetUserId', id);
   },
-  track: (name: string, properties?: Record<string, unknown>, opts?: TrackOptions) =>
-    active().track(name, properties, opts),
 
   /**
-   * Shows the iOS ATT prompt (resolves 'authorized' immediately on Android/web,
-   * where ATT doesn't exist) and forwards the result to the consent gate.
+   * Registers the device's push token for uninstall measurement.
+   *
+   * Advenue never requests the notification permission and never displays
+   * anything: pass the token your push library already produced, on every
+   * launch and from its refresh listener. A stale token is the one thing that
+   * makes uninstall measurement report churn that did not happen.
+   */
+  setPushToken(token: string | null, provider?: 'apns' | 'fcm'): void {
+    if (!requireStarted()) return;
+    call('bridgeSetPushToken', token, provider ?? null);
+  },
+
+  /**
+   * Shows the iOS ATT prompt. Where ATT does not exist (non-iOS, or the iOS
+   * module is absent) there is no prompt to show and no signal to read, so
+   * consent is left untouched and the call resolves 'unavailable'.
    */
   async requestTrackingAuthorization(): Promise<TrackingAuthorizationStatus> {
-    const ios = getIosNative();
-    const status = ios ? await ios.requestTrackingAuthorization() : 'authorized';
-    active().setTrackingConsent(status === 'authorized');
-    // (b) re-resolve ad-id after ATT prompt result is known
-    void resolveAdvertisingId().catch((err) => reportError('enrich.advertisingId', err));
-    if (status === 'authorized') {
-      fireAutoInstallIfPending();
-    }
+    const { ios } = bridge();
+    if (!ios) return 'unavailable';
+    const status = await ios.requestTrackingAuthorization();
+    Advenue.setTrackingConsent(status === 'authorized');
     return status;
   },
 
   setTrackingConsent(granted: boolean): void {
-    active().setTrackingConsent(granted);
-    if (granted) {
-      fireAutoInstallIfPending();
-    }
-  },
-  getTrackingConsent: () => active().getTrackingConsent(),
-  /** GDPR/CCPA erasure: stop tracking and wipe local identifiers/queue. */
-  forgetMe(): void {
-    active().forgetMe();
-    // The install guard is facade state, not client state — wipe the sync copy
-    // here so it can't diverge from the (also wiped) Keychain copy.
-    try {
-      installFlagStore?.removeItem(INSTALL_SENT_KEY);
-    } catch (err) {
-      reportError('forget.wipe', err);
-    }
-    // Best-effort wipe of the reinstall-durable secure entries — without this
-    // the Keychain copy would resurrect the erased device id on next launch.
-    const secure = secureStore;
-    if (secure?.deleteItemAsync) {
-      for (const key of [DEVICE_ID_KEY, INSTALL_SENT_KEY]) {
-        void secure.deleteItemAsync(key).catch((err) => reportError('forget.secureWipe', err));
-      }
-    }
+    if (!requireStarted()) return;
+    consentCache = granted;
+    call('bridgeSetConsent', granted);
   },
+
+  getTrackingConsent: (): boolean => consentCache,
+
   setConsentData(consent: Consent): void {
-    manualConsentSet = true;
-    active().setConsentData(consent);
-    // (d) re-resolve ad-id after a consent change
-    void resolveAdvertisingId().catch((err) => reportError('enrich.advertisingId', err));
+    if (!requireStarted()) return;
+    call('bridgeSetConsentData', consent);
   },
-  getConsentData: () => active().getConsentData(),
-  flush: () => active().flush(),
-  getDeviceId: () => active().getDeviceId(),
-  /** The Advenue ID — alias of getDeviceId (see AdvenueClient.getAdvenueId). */
-  getAdvenueId: () => active().getAdvenueId(),
-  shutdown() {
-    appStateSub?.remove();
-    appStateSub = null;
-    deepLinkSub?.remove();
-    deepLinkSub = null;
-    instance?.shutdown();
-    instance = null;
-    secureStore = null;
-    installInFlight = false; // reset so re-initialize works correctly
-    autoInstallPending = false;
-    autoInstallEnabled = true;
-    manualConsentSet = false;
-    tcfCollectionEnabled = false;
-    configuredAppId = null;
-    configuredApiKey = null;
-    configuredEndpoint = DEFAULT_ENDPOINT;
-    aemSeenUrlHashes.clear();
+
+  getConsentData: (): Consent | null => call<Consent | null>('bridgeGetConsentData') ?? null,
+
+  /** GDPR/CCPA erasure: stops tracking and wipes local identifiers and queue. */
+  forgetMe(): void {
+    if (!requireStarted()) return;
+    call('bridgeForgetMe');
+    consentCache = false;
   },
-};
 
-/**
- * Tracks the install event enriched with native attribution data: Play + Meta
- * install referrers on Android, SKAdNetwork registration on iOS. Fired
- * automatically by `initialize()` (or its consent deferral); when a
- * `secureStore` is wired it fires at most once per device (reinstall-resilient
- * on iOS via Keychain; Android re-fires after a reinstall, which is
- * unavoidable post-GAID).
- *
- * @internal Exported for tests only — install tracking is automatic and this
- * function is deliberately NOT on the `Advenue` facade. Do not call it from
- * app code.
- */
-export async function trackInstall(): Promise<void> {
-  const client = active();
-  // Consent gate: client.track() would silently drop the event, but the
-  // durable flag below would still be written — permanently losing the
-  // install. Bail before any side effect; the caller (or the auto-install
-  // deferral) retries after consent is granted.
-  if (client.getRequireConsent() && !client.getTrackingConsent()) {
-    return;
-  }
-  // Client-side dedup works even without a secure store: check the sync MMKV
-  // flag (durable across launches) AND, when wired, the secure store (durable
-  // across reinstall on iOS).
-  let sent = installFlagStore?.getItem(INSTALL_SENT_KEY) === '1';
-  if (!sent && secureStore) {
-    try {
-      sent = (await secureStore.getItemAsync(INSTALL_SENT_KEY)) === '1';
-    } catch (err) {
-      // fail-open: a missed install is worse than a duplicate
-      reportError('install.guardRead', err);
-    }
-  }
-  if (sent) {
-    client.debugLog('install skipped (already sent on this device)');
-    return; // already counted this device (durable flag from a prior launch)
-  }
-  // C7: same-process dedup guard. If another trackInstall() call is already
-  // in-flight within this process (awaiting referrer/ad-id resolution), bail
-  // out — the first call will enqueue the install. This replaces the previous
-  // synchronous flag write which permanently suppressed the install if the
-  // process crashed before the flag was written to durable storage.
-  //
-  // Tradeoff: if the process crashes AFTER client.track() but BEFORE the
-  // durable flag write below, the next launch re-fires the install. The
-  // backend per-device dedup window absorbs the duplicate. A permanently missed
-  // install is worse than a duplicate.
-  if (installInFlight) {
-    return; // another call is already processing this install in this process
-  }
-  installInFlight = true;
-
-  const opts: { network?: string; campaign?: string; adservicesToken?: string } = {};
-  const props: Record<string, unknown> = {};
-
-  const android = getAndroidNative();
-  if (android) {
-    try {
-      const result = await android.getInstallReferrer();
-      if (result) {
-        const parsed = parseInstallReferrer(result.referrer);
-        if (parsed.network) opts.network = parsed.network;
-        if (parsed.campaign) opts.campaign = parsed.campaign;
-        if (parsed.gclid) props.gclid = parsed.gclid;
-        if (parsed.fbclid) props.fbclid = parsed.fbclid;
-        // G1: extractReferrerProperties always forwards the device-clock keys
-        // (referrerClickTimestamp/installBeginTimestamp → referrerTrust:'client')
-        // and, ONLY when Play returned non-zero server-clock values, the
-        // server-trusted `*ServerTimestamp` keys (referrerTrust:'server', +0.7).
-        // Device-clock values are never aliased into the server keys.
-        Object.assign(props, extractReferrerProperties(result));
-      }
-    } catch (err) {
-      // referrer is best-effort enrichment
-      reportError('enrich.installReferrer', err);
-    }
-    try {
-      const meta = await android.getMetaInstallReferrer();
-      const parsedMeta = meta ? parseMetaInstallReferrer(meta) : null;
-      if (parsedMeta) {
-        props.metaInstallReferrer = parsedMeta.raw;
-        if (parsedMeta.encryptedData) props.metaReferrerData = parsedMeta.encryptedData;
-        if (parsedMeta.nonce) props.metaReferrerNonce = parsedMeta.nonce;
-        if (!opts.network && parsedMeta.isClickThrough) {
-          opts.network = 'meta';
-          if (parsedMeta.campaign) opts.campaign = parsedMeta.campaign;
-        }
-      }
-    } catch (err) {
-      // best-effort
-      reportError('enrich.metaReferrer', err);
-    }
-  }
+  flush(): void {
+    if (!requireStarted()) return;
+    call('bridgeFlush');
+  },
 
-  const ios = getIosNative();
-  if (ios) {
-    try {
-      ios.registerAppForAttribution();
-    } catch (err) {
-      // best-effort
-      reportError('enrich.skanRegister', err);
-    }
-    // Apple Ads AdServices attribution token (iOS 14.3+). Best-effort: a
-    // rejection (older OS / AdServices unavailable) must NOT fail the
-    // install — the token is simply omitted and attribution proceeds
-    // without it (resolved server-side against the AdServices API).
-    try {
-      const asaToken = await ios.getAttributionToken();
-      if (asaToken) {
-        opts.adservicesToken = asaToken;
-      }
-    } catch (err) {
-      reportError('enrich.adservicesToken', err);
-    }
-  }
+  getDeviceId: (): Promise<string | null> =>
+    Promise.resolve(
+      call<string | Promise<string | null> | null>('bridgeDeviceId') ?? null,
+    ) as Promise<string | null>,
 
-  await resolveAdvertisingId(); // ensure idfa/gaid is attached to the install event
-
-  // G3.1n — Play Integrity attestation (Android only). Best-effort: any error
-  // leaves attestation absent; the install is never blocked.
-  const trackOpts: TrackOptions = { type: 'install', ...opts };
-  if (
-    configuredAppId &&
-    android &&
-    typeof (android as { getIntegrityToken?: unknown }).getIntegrityToken === 'function'
-  ) {
-    try {
-      // requestHash = sha256_hex("<appId>:<deviceId>") — must match the server's
-      // mapIntegrityVerdict computation byte-for-byte (see makeDecodeAndroid in
-      // apps/worker/src/attestation-decoders.ts):
-      //   expectedRequestHash = sha256(`${event.appId}:${event.deviceId}`)
-      // configuredAppId must be the app's UUID from the Advenue dashboard.
-      const deviceId = client.getDeviceId();
-      const requestHash = sha256Hex(`${configuredAppId}:${deviceId}`);
-      const token = await (
-        android as { getIntegrityToken(h: string): Promise<string> }
-      ).getIntegrityToken(requestHash);
-      if (token) {
-        trackOpts.attestationToken = token;
-        trackOpts.attestationType = 'play-integrity';
-      }
-    } catch (err) {
-      // attestation is best-effort — never block the install
-      reportError('attest.playIntegrity', err);
-    }
-  }
+  /** The Advenue ID — alias of `getDeviceId`. */
+  getAdvenueId: (): Promise<string | null> => Advenue.getDeviceId(),
 
-  // G3.2n — App Attest attestation (iOS only). Best-effort: any error (no
-  // support on simulator, challenge fetch failure, attest failure) leaves
-  // attestation absent; the install is NEVER blocked.
-  if (
-    configuredAppId &&
-    configuredApiKey &&
-    ios &&
-    typeof (ios as { attestKey?: unknown }).attestKey === 'function'
-  ) {
-    try {
-      // Step 1: fetch a one-time server challenge bound to this device.
-      const deviceId = client.getDeviceId();
-      const challengeUrl = `${configuredEndpoint}/v1/attest/challenge?deviceId=${encodeURIComponent(deviceId)}`;
-      const challengeRes = await fetch(challengeUrl, {
-        headers: { 'x-api-key': configuredApiKey },
-      });
-      if (!challengeRes.ok) throw new Error(`challenge HTTP ${challengeRes.status}`);
-      const { challenge } = (await challengeRes.json()) as { challenge: string };
-
-      // Step 2: call the native module (generates/reuses keychain key, attests).
-      const { keyId, attestationObject } = await (
-        ios as { attestKey(c: string): Promise<{ keyId: string; attestationObject: string }> }
-      ).attestKey(challenge);
-
-      // Step 3: attach the four G3.4-schema fields to the install event.
-      trackOpts.attestationToken = attestationObject;
-      trackOpts.attestationType = 'app-attest';
-      trackOpts.attestationKeyId = keyId;
-      trackOpts.attestationChallenge = challenge;
-    } catch (err) {
-      // fail-safe: attestation absent, install proceeds normally
-      reportError('attest.appAttest', err);
-    }
-  }
+  /** Which app the server resolved this API key to; null until a batch lands. */
+  getResolvedAppId: (): string | null => call<string | null>('bridgeResolvedAppId') ?? null,
 
-  // G3.3n — DeviceCheck token (iOS only). Generates a per-physical-device opaque
-  // token via DCDevice.current.generateToken. The server uses it with the
-  // per-app DeviceCheck key to detect reinstall abuse (bit0 = "already produced
-  // a paid install"). Fail-safe: any error (unsupported device, simulator, native
-  // error) silently omits the token — the install is NEVER blocked.
-  if (ios && typeof (ios as { getDeviceCheckToken?: unknown }).getDeviceCheckToken === 'function') {
-    try {
-      const token = await (ios as { getDeviceCheckToken(): Promise<string> }).getDeviceCheckToken();
-      if (token) {
-        trackOpts.deviceCheckToken = token;
-      }
-    } catch (err) {
-      // fail-safe: deviceCheckToken absent, install proceeds normally
-      reportError('attest.deviceCheck', err);
-    }
-  }
+  /**
+   * Resolves the deferred deep link for this install, or null for an organic
+   * one — which is most of them.
+   */
+  async resolveDeferredDeepLink(): Promise<DeepLink | null> {
+    if (!requireStarted()) return null;
+    const result = call<Promise<DeepLink | null>>('bridgeResolveDeferredDeepLink');
+    return (await result) ?? null;
+  },
 
-  // The gate was open at entry, but the enrichment awaits above leave a
-  // window where consent can be revoked (e.g. CMP grant → ATT deny) or
-  // forgetMe() can run — client.track() then silently drops the event.
-  // Enqueue-confirm via the synchronous pendingCount delta (enqueue is sync;
-  // a flush can only ack after its transport await) so a dropped install
-  // never burns the durable flag. Known edge: at the queue's hard cap,
-  // enqueue evicts the head so the delta reads 0 for an event that WAS
-  // enqueued — the flag stays unwritten and the next launch re-fires, which
-  // the backend per-device guard dedups. Duplicate over lost, by design.
-  const pendingBefore = client.pendingCount;
-  client.track('install', props, trackOpts);
-  if (client.pendingCount === pendingBefore) {
-    // Dropped. Allow a same-process retry, and re-arm the auto deferral when
-    // the drop was the consent gate closing (not erasure) so a later grant
-    // re-fires without waiting for the next launch.
-    installInFlight = false;
-    client.debugLog('install dropped (consent revoked mid-flight)');
-    if (autoInstallEnabled && client.getRequireConsent() && !client.getTrackingConsent()) {
-      autoInstallPending = true;
-    }
-    return;
-  }
-  client.debugLog('install fired');
-  // Write durable flags AFTER the install event is successfully enqueued. If
-  // the process crashes between here and the flag write, the next launch will
-  // re-fire the install — the backend per-device dedup window absorbs the
-  // duplicate. Writing the flag before enqueue (the old behavior) permanently
-  // suppressed the install on crash, which is unacceptable.
-  try {
-    installFlagStore?.setItem(INSTALL_SENT_KEY, '1');
-  } catch (err) {
-    // best-effort; backend per-device window dedups a re-fire
-    reportError('install.flagPersist', err);
-  }
-  if (secureStore) {
-    try {
-      await secureStore.setItemAsync(INSTALL_SENT_KEY, '1');
-    } catch (err) {
-      // best-effort; backend per-device window dedups a re-fire
-      reportError('install.flagPersistSecure', err);
-    }
-  }
-  // Do NOT reset installInFlight — once-per-process is correct. The durable
-  // flag above handles cross-launch dedup; installInFlight handles same-process.
-}
+  shutdown(): void {
+    deepLinkSub?.remove();
+    deepLinkSub = null;
+    errorSub?.remove();
+    errorSub = null;
+    if (started) call('bridgeShutdown');
+    started = false;
+    consentCache = false;
+  },
+};
+
+/** The platform this build reports, for diagnostics. */
+export const platform = getPlatformOS;