@advenue/react-native 0.3.0

package/src/index.ts

@@ -0,0 +1,574 @@
+import {
+  extractReferrerProperties,
+  parseInstallReferrer,
+  parseMetaInstallReferrer,
+} from '@advenue/install-referrer';
+import {
+  AdvenueClient,
+  type AdvenueConfig,
+  type Consent,
+  DEFAULT_ENDPOINT,
+  type DeepLink,
+  type DeviceInfo,
+  MemoryStorage,
+  type SecureStorageAdapter,
+  type StorageAdapter,
+  type TrackOptions,
+  resolveDurableDeviceId,
+} from '@advenue/sdk-core';
+import type { TrackingAuthorizationStatus } from '@advenue/sdk-ios';
+import { parseMatchToken } from '@advenue/shared/match-token';
+import { sha256Hex } from '@advenue/signing';
+import { type DeepLinkHandle, setupDeepLinks } from './deep-links';
+import { type MMKVLike, createMMKVStorage } from './mmkv-storage';
+import {
+  type AppStateSubscription,
+  getAndroidNative,
+  getAppState,
+  getIosNative,
+  getLinking,
+} from './native';
+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';
+export { parseDirectLink } from './deep-links';
+export type { AdvenueConfig, Consent, DeepLink, TrackOptions } from '@advenue/sdk-core';
+export { getAndroidNative, getIosNative } from './native';
+export type { TrackingAuthorizationStatus } from '@advenue/sdk-ios';
+
+/**
+ * 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 }) : {};
+    client.setAdvertisingId({ ...adFields, ...(vendorId ? { vendorId } : {}) });
+    return;
+  }
+  client.setAdvertisingId({});
+}
+
+/**
+ * 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 {};
+}
+
+/**
+ * iOS clipboard-match deferred deep linking: reads the `advmatch:<id>` token the
+ * link redirector wrote to the pasteboard and exchanges it for the deep link — a
+ * DETERMINISTIC match (no IDFA, no fingerprinting). Returns null off iOS, when
+ * there's no token, or without consent. (Reading the pasteboard shows the iOS
+ * paste banner — the user-visible, privacy-forward deferred path.)
+ */
+export async function resolveClipboardMatch(): Promise<DeepLink | null> {
+  const client = active();
+  if (client.getRequireConsent() && !client.getTrackingConsent()) return null;
+  const ios = getIosNative();
+  if (
+    !ios ||
+    typeof (ios as { getPasteboardMatchToken?: unknown }).getPasteboardMatchToken !== 'function'
+  ) {
+    return null;
+  }
+  const matchId = parseMatchToken(ios.getPasteboardMatchToken());
+  if (!matchId) return null;
+  return client.exchangeClipboardMatch(matchId);
+}
+
+export interface RNAdvenueConfig extends Omit<AdvenueConfig, 'storage'> {
+  /**
+   * An MMKV instance for the durable offline buffer:
+   *   import { MMKV } from 'react-native-mmkv';
+   *   Advenue.initialize({ apiKey, platform: 'ios', mmkv: new MMKV() });
+   * Omit to fall back to in-memory buffering (events lost on cold start).
+   */
+  mmkv?: MMKVLike;
+  /**
+   * G3.1n — Play Integrity (Android) / App Attest (iOS) attestation.
+   *
+   * Your app's Advenue appId (the UUID shown in the dashboard). When set on
+   * Android, `trackInstall()` will obtain a Play Integrity Standard token and
+   * attach 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;
+  /**
+   * An expo-secure-store module for a reinstall-resilient device identity:
+   *   import * as SecureStore from 'expo-secure-store';
+   *   await Advenue.initialize({ apiKey, platform: 'ios', secureStore: SecureStore });
+   * Omit to fall back to sync storage (deviceId is not reinstall-resilient).
+   */
+  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;
+}
+
+/**
+ * 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();
+  }
+}
+
+let instance: AdvenueClient | null = null;
+let appStateSub: AppStateSubscription | null = null;
+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;
+// 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;
+
+function active(): AdvenueClient {
+  if (!instance) {
+    throw new Error('Advenue.initialize() must be called before tracking events.');
+  }
+  return instance;
+}
+
+/**
+ * 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().
+ */
+function reportError(context: string, cause: unknown): void {
+  instance?.report(context, cause);
+}
+
+/**
+ * React Native entry point. Wires MMKV-backed offline buffering automatically
+ * and re-exports the same track surface as the core SDK.
+ */
+export const Advenue = {
+  async initialize(config: RNAdvenueConfig): Promise<AdvenueClient> {
+    const { mmkv, secureStore: secureMod, onDeepLink, appId, ...rest } = config;
+    configuredAppId = appId ?? null;
+    configuredApiKey = config.apiKey;
+    configuredEndpoint = config.endpoint ?? DEFAULT_ENDPOINT;
+    appStateSub?.remove();
+    appStateSub = null;
+    deepLinkSub?.remove();
+    deepLinkSub = null;
+    instance?.shutdown();
+    const storage = mmkv ? createMMKVStorage(mmkv) : new MemoryStorage();
+    installFlagStore = storage;
+    secureStore = secureMod ? createSecureStore(secureMod) : null;
+    const deviceId =
+      rest.deviceId ?? (await resolveDurableDeviceId(storage, secureStore ?? undefined));
+    instance = new AdvenueClient({ ...rest, deviceId, storage });
+    // (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: rest.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;
+            applyAppState(instance, status);
+          } else if (status === 'active') {
+            if (!seenBackground) return; // suppress: platform initial 'active' after cold-start
+            seenBackground = false;
+            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
+      }
+    }
+    if (onDeepLink) {
+      const linking = getLinking();
+      if (linking) {
+        const client = instance;
+        deepLinkSub = setupDeepLinks({
+          getInitialURL: () => linking.getInitialURL(),
+          addUrlListener: (handler) => linking.addEventListener('url', (e) => handler(e.url)),
+          // Deferred waterfall: clipboard (deterministic) first, then the
+          // server-side conversion poll (IDFA / probabilistic).
+          resolveDeferred: async () =>
+            (await resolveClipboardMatch()) ?? client.resolveDeferredDeepLink(),
+          onDeepLink,
+        });
+      }
+    }
+    return instance;
+  },
+  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.
+   */
+  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));
+    return status;
+  },
+
+  /**
+   * Tracks the install event enriched with native attribution data: Play +
+   * Meta install referrers on Android, SKAdNetwork registration on iOS.
+   * Safe to call on every launch — 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).
+   */
+  async trackInstall(properties?: Record<string, unknown>): Promise<void> {
+    const client = active();
+    // 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) {
+      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> = { ...properties };
+
+    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 emits both the legacy timestamp keys
+          // AND the explicit server-trusted keys (`*ServerTimestamp`) so the
+          // worker can apply the higher-trust (+0.7) click-injection weight.
+          // Both sets carry the same value — Play API timestamps are server-clock.
+          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);
+      }
+    }
+
+    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);
+      }
+    }
+
+    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);
+      }
+    }
+
+    // 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);
+      }
+    }
+
+    // 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);
+      }
+    }
+
+    client.track('install', props, trackOpts);
+    // 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.
+  },
+
+  setTrackingConsent: (granted: boolean) => active().setTrackingConsent(granted),
+  getTrackingConsent: () => active().getTrackingConsent(),
+  /** GDPR/CCPA erasure: stop tracking and wipe local identifiers/queue. */
+  forgetMe: () => active().forgetMe(),
+  setConsentData(consent: Consent): void {
+    active().setConsentData(consent);
+    // (d) re-resolve ad-id after a consent change
+    void resolveAdvertisingId().catch((err) => reportError('enrich.advertisingId', err));
+  },
+  getConsentData: () => active().getConsentData(),
+  flush: () => active().flush(),
+  getDeviceId: () => active().getDeviceId(),
+  shutdown() {
+    appStateSub?.remove();
+    appStateSub = null;
+    deepLinkSub?.remove();
+    deepLinkSub = null;
+    instance?.shutdown();
+    instance = null;
+    secureStore = null;
+    installInFlight = false; // reset so re-initialize + trackInstall works correctly
+    configuredAppId = null;
+    configuredApiKey = null;
+    configuredEndpoint = DEFAULT_ENDPOINT;
+  },
+};

package/src/mmkv-storage.ts

@@ -0,0 +1,21 @@
+import type { StorageAdapter } from '@advenue/sdk-core';
+
+/**
+ * Minimal structural type for the bits of `react-native-mmkv`'s MMKV instance
+ * we use. Declared locally so this package needs no react-native types at
+ * compile time — the app injects a real `new MMKV()` instance at runtime.
+ */
+export interface MMKVLike {
+  set(key: string, value: string): void;
+  getString(key: string): string | undefined;
+  delete(key: string): void;
+}
+
+/** Wraps an MMKV instance as an Advenue StorageAdapter (synchronous, fast). */
+export function createMMKVStorage(mmkv: MMKVLike): StorageAdapter {
+  return {
+    getItem: (key) => mmkv.getString(key) ?? null,
+    setItem: (key, value) => mmkv.set(key, value),
+    removeItem: (key) => mmkv.delete(key),
+  };
+}

package/src/native.ts

@@ -0,0 +1,76 @@
+import type { AdvenueAndroidNativeModule } from '@advenue/sdk-android';
+import type { AdvenueIosNativeModule } from '@advenue/sdk-ios';
+
+declare function require(id: string): unknown;
+
+/**
+ * Lazy access to the optional native modules. `requireNativeModule` throws at
+ * import time when the native side isn't installed (Expo Go, web, missing
+ * pods), so resolution happens inside try/catch — never at module scope.
+ */
+export function getIosNative(): AdvenueIosNativeModule | null {
+  try {
+    return (require('@advenue/sdk-ios') as { AdvenueIos: AdvenueIosNativeModule }).AdvenueIos;
+  } catch {
+    return null;
+  }
+}
+
+export function getAndroidNative(): AdvenueAndroidNativeModule | null {
+  try {
+    return (require('@advenue/sdk-android') as { AdvenueAndroid: AdvenueAndroidNativeModule })
+      .AdvenueAndroid;
+  } catch {
+    return null;
+  }
+}
+
+/** Subscription handle returned by AppState.addEventListener. */
+export interface AppStateSubscription {
+  remove(): void;
+}
+
+/** Minimal shape of React Native's AppState we depend on. */
+export interface AppStateLike {
+  addEventListener(type: 'change', handler: (status: string) => void): AppStateSubscription;
+}
+
+/**
+ * Lazy access to React Native's AppState. Returns null on web / when
+ * react-native isn't resolvable, so callers degrade to no automatic sessions.
+ */
+export function getAppState(): AppStateLike | null {
+  try {
+    return (require('react-native') as { AppState: AppStateLike }).AppState;
+  } catch {
+    return null;
+  }
+}
+
+/** Subscription handle returned by Linking.addEventListener. */
+export interface LinkingSubscription {
+  remove(): void;
+}
+
+/**
+ * Minimal shape of React Native's Linking we depend on. Captures both the
+ * cold-start URL and warm 'url' events — the OS delivers Universal Links (iOS)
+ * and App Links (Android) here, so no extra native code is needed for direct
+ * deep links.
+ */
+export interface LinkingLike {
+  getInitialURL(): Promise<string | null>;
+  addEventListener(type: 'url', handler: (event: { url: string }) => void): LinkingSubscription;
+}
+
+/**
+ * Lazy access to React Native's Linking. Returns null on web / when
+ * react-native isn't resolvable, so callers degrade to no direct deep links.
+ */
+export function getLinking(): LinkingLike | null {
+  try {
+    return (require('react-native') as { Linking: LinkingLike }).Linking;
+  } catch {
+    return null;
+  }
+}

package/src/secure-store.ts

@@ -0,0 +1,19 @@
+import type { SecureStorageAdapter } from '@advenue/sdk-core';
+
+/**
+ * Minimal structural type for the bits of `expo-secure-store` we use. Declared
+ * locally so this package needs no expo types at compile time — the app passes
+ * the module (`import * as SecureStore from 'expo-secure-store'`) at runtime.
+ */
+export interface SecureStoreLike {
+  getItemAsync(key: string): Promise<string | null>;
+  setItemAsync(key: string, value: string): Promise<void>;
+}
+
+/** Wraps expo-secure-store as an Advenue SecureStorageAdapter (async, durable). */
+export function createSecureStore(secureStore: SecureStoreLike): SecureStorageAdapter {
+  return {
+    getItemAsync: async (key) => (await secureStore.getItemAsync(key)) ?? null,
+    setItemAsync: (key, value) => secureStore.setItemAsync(key, value),
+  };
+}