@advenue/react-native 0.9.0 → 1.0.0

package/src/native-types.ts

@@ -1,200 +1,93 @@
-// Native module contracts for the Expo modules that ship inside this package
-// (ios/ and android/ directories, registered via expo-module.config.json).
-// Formerly the public surface of @advenue/sdk-ios and @advenue/sdk-android —
-// both retired when the native code moved in-package (single-install DX).
+// Contracts for the Expo modules that ship inside this package (ios/ and
+// android/, registered via expo-module.config.json).
+//
+// These are a bridge, not a toolbox. The old surface exposed one function per
+// native capability — storage, advertising ids, attestation, TCF — because a
+// TypeScript core drove them. That core is gone: each function below maps to
+// one method on the native SDK, and the native SDK decides everything else.
 
-export interface InstallReferrerResult {
-  referrer: string;
-  /** Device-clock: referrerClickTimestampSeconds. */
-  clickTimestamp: number;
-  /** Device-clock: installBeginTimestampSeconds. */
-  installTimestamp: number;
-  /**
-   * Server-clock: referrerClickTimestampServerSeconds (G1 fraud trust —
-   * referrerTrust:'server'). 0 = unverified; absent on older native builds.
-   */
-  clickServerTimestamp?: number;
-  /** Server-clock: installBeginTimestampServerSeconds. 0 = unverified. */
-  installServerTimestamp?: number;
-  googlePlayInstant: boolean;
-}
+import type { Consent, DeepLink } from './types';
 
-export interface MetaInstallReferrerResult {
-  installReferrer: string;
-  isClickThrough: boolean;
-  actualTimestamp: number;
-  /** Which Meta app served the referrer (e.g. com.facebook.katana). */
-  provider: string;
-}
+export type TrackingAuthorizationStatus =
+  | 'authorized'
+  | 'denied'
+  | 'restricted'
+  | 'notDetermined'
+  | 'unavailable';
 
-/**
- * Device metadata for Meta CAPI `extinfo` (Task 3n). Structurally mirrors
- * `DeviceInfo` from `@advenue/shared` — kept as a local subset type (rather
- * than importing that package) so this native-module-only package stays
- * dependency-free; the RN facade's `collectDeviceInfo()` merges it into the
- * real `DeviceInfo` shape.
- */
-export interface AdvenueDeviceInfo {
-  /** Bundle id / package name — Meta CAPI extinfo slot 1. */
-  packageName?: string;
-  /** User-facing app version (CFBundleShortVersionString / versionName) —
-   *  extinfo slot 2. Surfaced as the event's top-level `appVersion`, not as
-   *  part of the deviceInfo blob. */
-  shortVersion?: string;
-  /** Build identifier (CFBundleVersion / versionCode) — extinfo slot 3. */
-  longVersion?: string;
-  model?: string;
-  locale?: string;
-  carrier?: string;
-  timezone?: string;
-  screenWidth?: number;
-  screenHeight?: number;
-  screenDensity?: number;
-  cpuCores?: number;
-  totalStorageGb?: number;
-  freeStorageGb?: number;
+/** What `bridgeInitialize` accepts. Anything absent takes the native default. */
+export interface BridgeInitOptions {
+  apiKey: string;
+  endpoint?: string;
+  appVersion?: string;
+  requireConsent: boolean;
+  batchSize?: number;
+  flushIntervalMs?: number;
+  signingSecret?: string;
+  /** Meta app id, for the Meta install referrer. Android only. */
+  fbAppId?: string;
+  autoTrackInstall: boolean;
+  /** Stamped by this package, never by the host app. */
+  sdkVersion: string;
 }
 
 /**
- * Raw IAB TCF v2 CMP values from the platform default store
- * (`UserDefaults.standard` / default SharedPreferences) — where TCF-compliant
- * CMPs (e.g. Google UMP) write `IABTCF_*` keys. Structurally mirrors
- * `TcfData` from `@advenue/sdk-core`.
+ * One diagnostic the SDK swallowed, on its way back to JavaScript.
+ *
+ * `context` is a stable dot-path identifier of the step that failed
+ * (`identity.deferred`, `track.rejected:name_too_long`, `flush.transport`), not
+ * a message to show a user. Never carries PII.
  */
-export interface NativeTcfData {
-  gdprApplies?: number | null;
-  purposeConsents?: string | null;
+export interface NativeErrorEvent {
+  context: string;
+  message: string;
 }
 
-export interface AdvenueAndroidNativeModule {
-  /** Raw Play Install Referrer; parse with @advenue/install-referrer. */
-  getInstallReferrer(): Promise<InstallReferrerResult | null>;
-  /**
-   * Meta install referrer (null when no Facebook/Instagram app is installed);
-   * parse with parseMetaInstallReferrer from @advenue/install-referrer.
-   */
-  getMetaInstallReferrer(): Promise<MetaInstallReferrerResult | null>;
-  /** Google Advertising ID (GAID) + limit-ad-tracking flag; null when unavailable. */
-  getAdvertisingId(): Promise<{ id: string; limitAdTracking: boolean } | null>;
-  /** App Set ID — non-advertising, developer-scoped fallback id; null when unavailable. */
-  getAppSetId(): Promise<string | null>;
-  /**
-   * Play Integrity Standard API token (G3.1n).
-   *
-   * `requestHash` MUST be sha256_hex("<deviceId>") — lowercase hex SHA-256 of the
-   * device id alone. The server's mapIntegrityVerdict re-derives the same string
-   * and compares it byte-for-byte. No app id is hashed in: the token is decoded
-   * against the app's Play package name and must be PLAY_RECOGNIZED, which binds
-   * the app already.
-   *
-   * Rejects when:
-   *  - ECONFIG: `io.advenue.INTEGRITY_CLOUD_PROJECT_NUMBER` meta-data is absent.
-   *  - EUNSUPPORTED: Play Services unavailable or provider warming failed.
-   *  - EINTEGRITY: Play returned an API-level error (network, quota, etc.).
-   *
-   * The JS bridge treats any rejection as "no attestation" and omits the token
-   * from the install event — rejection must never block the install track call.
-   */
-  getIntegrityToken(requestHash: string): Promise<string>;
-  /**
-   * Device metadata (model, locale, screen, cpu, storage, timezone) used to
-   * populate Meta CAPI `extinfo` (Task 3n). Synchronous, best-effort — the JS
-   * facade (`collectDeviceInfo`) treats a thrown error as "unavailable" and
-   * degrades to `{}` rather than blocking anything.
-   */
-  getDeviceInfo(): AdvenueDeviceInfo;
-  /**
-   * Built-in SDK storage (SharedPreferences `io.advenue.sdk`, MODE_PRIVATE) —
-   * the durable offline buffer + SDK state, so the app never supplies storage.
-   * Optional: absent on native builds predating this capability; the RN facade
-   * feature-detects and falls back to in-memory buffering. (No secure variant:
-   * Android has no reinstall-durable store — a reinstall legitimately re-fires
-   * the install, which the backend per-device window deduplicates.)
-   */
-  storageGetItem?(key: string): string | null;
-  storageSetItem?(key: string, value: string): void;
-  storageRemoveItem?(key: string): void;
-  /**
-   * Android SSAID (Settings.Secure.ANDROID_ID) — signing-key-scoped, stable
-   * across reinstalls. The RN facade reads it ONLY when no usable GAID exists
-   * (Adjust-style fallback) and it is used strictly as a first-party
-   * fraud/dedup + reinstall-detection signal, never for ad attribution (Play
-   * policy). Optional: absent on older native builds; feature-detected.
-   */
-  getAndroidId?(): string | null;
-  /**
-   * IAB TCF v2 CMP data, null when no CMP has written TCF keys. Optional:
-   * older native builds lack it — callers feature-detect (getAndroidId
-   * precedent).
-   */
-  getTcfData?(): NativeTcfData | null;
+/** The methods both native modules implement. */
+export interface AdvenueBridge {
+  /** Expo's event subscription, used for `onAdvenueError`. */
+  addListener?(
+    name: 'onAdvenueError',
+    handler: (event: NativeErrorEvent) => void,
+  ): { remove(): void };
+  bridgeInitialize(options: BridgeInitOptions): void;
+  bridgeTrack(name: string, properties: Record<string, unknown> | null): void;
+  bridgeFlush(): void;
+  bridgeSetUserId(id: string | null): void;
+  bridgeSetConsent(granted: boolean): void;
+  /** Reads the persisted value; the JavaScript consent cache is seeded from it. */
+  bridgeGetConsent(): boolean;
+  bridgeSetConsentData(consent: Consent): void;
+  bridgeGetConsentData(): Consent | null;
+  bridgeSetAppInstanceId(id: string | null): void;
+  bridgeSetPushToken(token: string | null, provider: string | null): void;
+  bridgeProcessDeepLink(url: string): void;
+  bridgeForgetMe(): void;
+  bridgeShutdown(): void;
+  bridgeResolvedAppId(): string | null;
+  bridgeResolveDeferredDeepLink(): Promise<DeepLink | null>;
 }
 
-export type TrackingAuthorizationStatus = 'notDetermined' | 'restricted' | 'denied' | 'authorized';
-
-export interface AdvenueIosNativeModule {
-  registerAppForAttribution(): void;
+export interface AdvenueIosNativeModule extends AdvenueBridge {
   /**
-   * Conversion value: fine 0–63, coarse 'low'|'medium'|'high'. Updates the
-   * SKAN 4.0 postback, and on iOS 17.4+ the AdAttributionKit postback too.
+   * The app's price string ("9.99"), not micros. The conversion to exact
+   * micros happens natively: a money computation in JavaScript is the thing
+   * this release removed.
    */
-  updateConversionValue(fineValue: number, coarse: string, lockWindow: boolean): Promise<void>;
-  /** Apple Search Ads attribution token (resolve server-side). */
-  getAttributionToken(): Promise<string | null>;
+  bridgeRecordSkanRevenue(amount: string, currency: string): void;
+  /** Resolves synchronously on the native side; a Promise across the bridge. */
+  bridgeDeviceId(): Promise<string | null>;
   /**
    * Shows the ATT consent prompt; requires NSUserTrackingUsageDescription in
    * the app's Info.plist. Resolves with the resulting status.
+   *
+   * Still a capability rather than a bridge call because the app chooses when
+   * to prompt, and that decision belongs to the app's UX, not the SDK.
    */
   requestTrackingAuthorization(): Promise<TrackingAuthorizationStatus>;
-  getTrackingAuthorizationStatus(): TrackingAuthorizationStatus;
-  getAdvertisingId(): Promise<string | null>;
-  /** Vendor-scoped device id (IDFV) — available without ATT; a fallback anchor. */
-  getIdentifierForVendor(): string | null;
-  /**
-   * G3.2n — App Attest. Generates (or reuses a keychain-cached) DCAppAttest
-   * key, computes clientDataHash = SHA-256(challenge), and calls
-   * DCAppAttestService.attestKey. Resolves { keyId, attestationObject } where
-   * attestationObject is a base64-encoded CBOR attestation for the server.
-   * Rejects with code EUNSUPPORTED on simulators (isSupported == false).
-   */
-  attestKey(challenge: string): Promise<{ keyId: string; attestationObject: string }>;
-  /**
-   * G3.3n — DeviceCheck. Calls DCDevice.current.generateToken to obtain the
-   * opaque base64 token that identifies this physical device to the Apple
-   * DeviceCheck API. The server queries/updates the persistent 2-bit per-device
-   * flag to detect reinstall abuse. Rejects with code EUNSUPPORTED on devices
-   * where DCDevice.current.isSupported is false (simulator, Catalyst, etc.).
-   */
-  getDeviceCheckToken(): Promise<string>;
-  /**
-   * Device metadata (model, locale, screen, cpu, storage, timezone) used to
-   * populate Meta CAPI `extinfo` (Task 3n). Synchronous, best-effort — the JS
-   * facade (`collectDeviceInfo`) treats a thrown error as "unavailable" and
-   * degrades to `{}` rather than blocking anything.
-   */
-  getDeviceInfo(): AdvenueDeviceInfo;
-  /**
-   * Built-in SDK storage (UserDefaults suite `io.advenue.sdk`) — the durable
-   * offline buffer + SDK state, so the app never supplies storage. Optional:
-   * absent on native builds predating this capability; the RN facade
-   * feature-detects and falls back to in-memory buffering.
-   */
-  storageGetItem?(key: string): string | null;
-  storageSetItem?(key: string, value: string): void;
-  storageRemoveItem?(key: string): void;
-  /**
-   * Built-in secure storage (Keychain, kSecAttrAccessibleAfterFirstUnlock,
-   * ThisDeviceOnly) — survives app reinstall, which is what makes the device
-   * identity and the install guard reinstall-resilient (Adjust-style).
-   * Optional: absent on older native builds; feature-detected.
-   */
-  secureGetItem?(key: string): string | null;
-  secureSetItem?(key: string, value: string): void;
-  secureRemoveItem?(key: string): void;
-  /**
-   * IAB TCF v2 CMP data, null when no CMP has written TCF keys. Optional:
-   * older native builds lack it — callers feature-detect (getAndroidId
-   * precedent).
-   */
-  getTcfData?(): NativeTcfData | null;
+}
+
+export interface AdvenueAndroidNativeModule extends AdvenueBridge {
+  /** Synchronous on Android: the identity is resolved before start returns. */
+  bridgeDeviceId(): string | null;
 }

package/src/native.ts

@@ -44,29 +44,6 @@ export function getPlatformOS(): string | null {
   }
 }
 
-/**
- * OS *release* version for attribution matching: iOS `Platform.Version` is the
- * system version string ('18.2'); Android `Platform.Version` is the API LEVEL
- * (34) — sending it would break the server's normalized fingerprint (the
- * click-side browser UA says "Android 14"), so Android reads
- * `Platform.constants.Release` and degrades to null when it's absent.
- */
-export function getOsVersion(): string | null {
-  try {
-    const rn = requireReactNative() as {
-      Platform: { OS: string; Version?: unknown; constants?: { Release?: unknown } };
-    } | null;
-    if (!rn) return null;
-    if (rn.Platform.OS === 'android') {
-      const release = rn.Platform.constants?.Release;
-      return release != null ? String(release) : null;
-    }
-    return rn.Platform.Version != null ? String(rn.Platform.Version) : null;
-  } catch {
-    return null;
-  }
-}
-
 /** Subscription handle returned by AppState.addEventListener. */
 export interface AppStateSubscription {
   remove(): void;

package/src/types.ts

@@ -0,0 +1,81 @@
+/**
+ * The types the package used to re-export from the retired TypeScript core.
+ *
+ * They live here now because the TypeScript core is retired and the native
+ * SDKs own the behaviour — but they are still the shapes apps destructure, so
+ * they must keep their names and fields exactly.
+ */
+
+/** Granular ad-platform consent (Google DMA). */
+export interface Consent {
+  /** Whether GDPR/EEA rules apply to this user. → Google `gdpr_applies` */
+  isUserSubjectToGDPR: boolean;
+  /** Consent to use data for advertising purposes. → Google `ad_user_data` */
+  hasConsentForDataUsage?: boolean;
+  /** Consent for personalized advertising. → Google `ad_personalization` */
+  hasConsentForAdsPersonalization?: boolean;
+  /** Consent for ad storage. → Google `ad_storage` */
+  hasConsentForAdStorage?: boolean;
+}
+
+/** A resolved deep link, deferred or direct. */
+export interface DeepLink {
+  /** In-app destination, e.g. "product/123". Absent for an attributed install with no link. */
+  deepLinkValue?: string;
+  campaign?: string;
+  network?: string;
+  influencerId?: string;
+  params?: Record<string, unknown>;
+  /** Raw opening URL for direct (OS-delivered) links; absent for deferred. */
+  url?: string;
+  /** True when the link survived an install rather than arriving on an open. */
+  isDeferred: boolean;
+  /** True when this is the device's first-launch attribution (always true for deferred). */
+  isFirstLaunch: boolean;
+}
+
+/**
+ * The event types a client SDK may emit. Revenue-bearing subscription events
+ * are deliberately absent: those originate only from verified S2S sources, and
+ * the server rejects a batch that claims one.
+ */
+export type ClientEventType = 'install' | 'session' | 'custom';
+
+/** Per-event options. Most apps never pass any of these. */
+export interface TrackOptions {
+  type?: ClientEventType;
+  network?: string;
+  campaign?: string;
+}
+
+/**
+ * SDK configuration.
+ *
+ * Several options that used to shape the TypeScript core are now decided
+ * natively and are accepted but ignored — see `initialize`, which reports each
+ * one through `onError` rather than dropping it silently. Passing storage to an
+ * SDK that owns its own storage should not look like it worked.
+ */
+export interface AdvenueConfig {
+  apiKey: string;
+  endpoint?: string;
+  platform?: 'ios' | 'android' | 'web' | string;
+  appVersion?: string;
+  osVersion?: string;
+  /** Gates every event on `setTrackingConsent(true)`. */
+  requireConsent?: boolean;
+  /** Events per request. */
+  batchSize?: number;
+  /** Auto-flush period in milliseconds; 0 disables the timer. */
+  flushIntervalMs?: number;
+  /**
+   * Per-key HMAC secret. The signature provides integrity and replay
+   * protection, not authentication: anything inside an app binary can be
+   * extracted from it.
+   */
+  signingSecret?: string;
+  disableAutoSessions?: boolean;
+  /** Called when the SDK swallows a best-effort failure. Never receives PII. */
+  onError?: (context: string, cause: unknown) => void;
+  debug?: boolean;
+}

package/src/aem.ts

@@ -1,33 +0,0 @@
-/**
- * Meta AEM campaign_ids extraction from an al_applink_data payload.
- *
- * The input string is the ALREADY percent-decoded query-param value
- * (URLSearchParams decodes; decoding again would corrupt blobs containing
- * '%'). Meta does not publicly document the al_applink_data schema for AEM,
- * so we accept the two shapes observed in the wild — top-level
- * `campaign_ids` and `extras.campaign_ids` — top level first. VERIFY against
- * a real captured payload when one is available and update this comment
- * with what production links actually show (spec: implementation-time
- * verification).
- *
- * The blob is opaque, Meta-encrypted, non-user metadata: returned verbatim,
- * never trimmed/re-encoded. ≤ 2048 chars as URL hygiene (the worker
- * re-validates — SDK caps are advisory at the trust boundary).
- */
-export function extractAemCampaignIds(alApplinkData: string): string | null {
-  try {
-    const parsed = JSON.parse(alApplinkData) as {
-      campaign_ids?: unknown;
-      extras?: { campaign_ids?: unknown };
-    };
-    const value =
-      typeof parsed.campaign_ids === 'string' && parsed.campaign_ids
-        ? parsed.campaign_ids
-        : typeof parsed.extras?.campaign_ids === 'string' && parsed.extras.campaign_ids
-          ? parsed.extras.campaign_ids
-          : null;
-    return value && value.length <= 2048 ? value : null;
-  } catch {
-    return null;
-  }
-}

package/src/mmkv-storage.ts

@@ -1,21 +0,0 @@
-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-storage.ts

@@ -1,63 +0,0 @@
-// Adapters over the native modules' built-in storage (UserDefaults /
-// SharedPreferences + iOS Keychain), so the app never supplies storage —
-// Adjust/AppsFlyer parity. Pure functions over a passed module (rather than
-// resolving the module themselves) so they stay unit-testable and respect the
-// test mocks of './native'.
-import type { SecureStorageAdapter, StorageAdapter } from '@advenue/sdk-core';
-
-interface NativeStorageFns {
-  storageGetItem?(key: string): string | null;
-  storageSetItem?(key: string, value: string): void;
-  storageRemoveItem?(key: string): void;
-}
-
-interface NativeSecureFns {
-  secureGetItem?(key: string): string | null;
-  secureSetItem?(key: string, value: string): void;
-  secureRemoveItem?(key: string): void;
-}
-
-/**
- * Wraps a native module's built-in key/value storage as the sync
- * {@link StorageAdapter}. Returns null when the module is absent or predates
- * the storage capability (feature-detected), so callers fall back.
- */
-export function createNativeStorage(mod: unknown): StorageAdapter | null {
-  const m = mod as NativeStorageFns | null;
-  if (
-    !m ||
-    typeof m.storageGetItem !== 'function' ||
-    typeof m.storageSetItem !== 'function' ||
-    typeof m.storageRemoveItem !== 'function'
-  ) {
-    return null;
-  }
-  return {
-    getItem: (key) => m.storageGetItem?.(key) ?? null,
-    setItem: (key, value) => m.storageSetItem?.(key, value),
-    removeItem: (key) => m.storageRemoveItem?.(key),
-  };
-}
-
-/**
- * Wraps the iOS module's Keychain functions as the async
- * {@link SecureStorageAdapter} (with erasure support). Returns null when the
- * module is absent or predates the capability — including all of Android,
- * which has no reinstall-durable store.
- */
-export function createNativeSecureStore(mod: unknown): SecureStorageAdapter | null {
-  const m = mod as NativeSecureFns | null;
-  if (
-    !m ||
-    typeof m.secureGetItem !== 'function' ||
-    typeof m.secureSetItem !== 'function' ||
-    typeof m.secureRemoveItem !== 'function'
-  ) {
-    return null;
-  }
-  return {
-    getItemAsync: async (key) => m.secureGetItem?.(key) ?? null,
-    setItemAsync: async (key, value) => m.secureSetItem?.(key, value),
-    deleteItemAsync: async (key) => m.secureRemoveItem?.(key),
-  };
-}

package/src/secure-store.ts

@@ -1,26 +0,0 @@
-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>;
-  /** Optional — forwarded so GDPR erasure can wipe the durable entries. */
-  deleteItemAsync?(key: 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),
-    ...(secureStore.deleteItemAsync
-      ? {
-          deleteItemAsync: (key: string) => secureStore.deleteItemAsync?.(key) ?? Promise.resolve(),
-        }
-      : {}),
-  };
-}