@advenue/react-native 0.3.1 → 0.5.0

package/dist/index.d.ts

@@ -1,8 +1,5 @@
 import { StorageAdapter, SecureStorageAdapter, DeepLink, AdvenueConfig, AdvenueClient, TrackOptions, Consent, DeviceInfo } from '@advenue/sdk-core';
 export { AdvenueConfig, Consent, DeepLink, TrackOptions } from '@advenue/sdk-core';
-import { AdvenueIosNativeModule, TrackingAuthorizationStatus } from '@advenue/sdk-ios';
-export { TrackingAuthorizationStatus } from '@advenue/sdk-ios';
-import { AdvenueAndroidNativeModule } from '@advenue/sdk-android';
 
 /**
  * Minimal structural type for the bits of `react-native-mmkv`'s MMKV instance
@@ -17,6 +14,172 @@ interface MMKVLike {
 /** Wraps an MMKV instance as an Advenue StorageAdapter (synchronous, fast). */
 declare function createMMKVStorage(mmkv: MMKVLike): StorageAdapter;
 
+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;
+}
+interface MetaInstallReferrerResult {
+    installReferrer: string;
+    isClickThrough: boolean;
+    actualTimestamp: number;
+    /** Which Meta app served the referrer (e.g. com.facebook.katana). */
+    provider: string;
+}
+/**
+ * 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.
+ */
+interface AdvenueDeviceInfo {
+    model?: string;
+    locale?: string;
+    carrier?: string;
+    timezone?: string;
+    screenWidth?: number;
+    screenHeight?: number;
+    screenDensity?: number;
+    cpuCores?: number;
+    totalStorageGb?: number;
+    freeStorageGb?: number;
+}
+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("<appId>:<deviceId>") — lowercase hex SHA-256
+     * of the literal string "<appId>:<deviceId>". The server's mapIntegrityVerdict
+     * re-derives the same string and compares it byte-for-byte.
+     *
+     * 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;
+}
+type TrackingAuthorizationStatus = 'notDetermined' | 'restricted' | 'denied' | 'authorized';
+interface AdvenueIosNativeModule {
+    registerAppForAttribution(): void;
+    /**
+     * Conversion value: fine 0–63, coarse 'low'|'medium'|'high'. Updates the
+     * SKAN 4.0 postback, and on iOS 17.4+ the AdAttributionKit postback too.
+     */
+    updateConversionValue(fineValue: number, coarse: string, lockWindow: boolean): Promise<void>;
+    /** Apple Search Ads attribution token (resolve server-side). */
+    getAttributionToken(): Promise<string | null>;
+    /**
+     * Shows the ATT consent prompt; requires NSUserTrackingUsageDescription in
+     * the app's Info.plist. Resolves with the resulting status.
+     */
+    requestTrackingAuthorization(): Promise<TrackingAuthorizationStatus>;
+    getTrackingAuthorizationStatus(): TrackingAuthorizationStatus;
+    getAdvertisingId(): Promise<string | null>;
+    /** Vendor-scoped device id (IDFV) — available without ATT; a fallback anchor. */
+    getIdentifierForVendor(): string | null;
+    /** Clipboard match token (advmatch:<id>) for deterministic deferred deep linking; null if absent. */
+    getPasteboardMatchToken(): 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;
+}
+
 /**
  * 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
@@ -25,6 +188,8 @@ declare function createMMKVStorage(mmkv: MMKVLike): StorageAdapter;
 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). */
 declare function createSecureStore(secureStore: SecureStoreLike): SecureStorageAdapter;
@@ -38,9 +203,11 @@ declare function createSecureStore(secureStore: SecureStoreLike): SecureStorageA
 declare function parseDirectLink(url: string): DeepLink;
 
 /**
- * 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.
+ * Lazy access to the native modules that ship inside this package (ios/ and
+ * android/, registered via expo-module.config.json). `requireNativeModule`
+ * throws when the native side isn't built (Expo Go, web, missing pods), so
+ * resolution happens inside try/catch — never at module scope.
+ * expo-modules-core is resolved from the consuming app's Expo install.
  */
 declare function getIosNative(): AdvenueIosNativeModule | null;
 declare function getAndroidNative(): AdvenueAndroidNativeModule | null;
@@ -80,20 +247,26 @@ declare function collectDeviceInfo(natives: {
  * paste banner — the user-visible, privacy-forward deferred path.)
  */
 declare function resolveClipboardMatch(): Promise<DeepLink | null>;
-interface RNAdvenueConfig extends Omit<AdvenueConfig, 'storage'> {
+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'];
     /**
-     * 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).
+     * @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 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
+     * 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).
      *
@@ -101,10 +274,10 @@ interface RNAdvenueConfig extends Omit<AdvenueConfig, 'storage'> {
      */
     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).
+     * @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;
     /**
@@ -115,6 +288,13 @@ interface RNAdvenueConfig extends Omit<AdvenueConfig, 'storage'> {
      * 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.
+     */
+    autoTrackInstall?: boolean;
 }
 /**
  * Maps a React Native AppState status to the client's session lifecycle hooks.
@@ -134,18 +314,10 @@ declare const Advenue: {
      * where ATT doesn't exist) and forwards the result to the consent gate.
      */
     requestTrackingAuthorization(): Promise<TrackingAuthorizationStatus>;
-    /**
-     * 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).
-     */
-    trackInstall(properties?: Record<string, unknown>): Promise<void>;
-    setTrackingConsent: (granted: boolean) => void;
+    setTrackingConsent(granted: boolean): void;
     getTrackingConsent: () => boolean;
     /** GDPR/CCPA erasure: stop tracking and wipe local identifiers/queue. */
-    forgetMe: () => void;
+    forgetMe(): void;
     setConsentData(consent: Consent): void;
     getConsentData: () => {
         isUserSubjectToGDPR: boolean;
@@ -157,5 +329,18 @@ declare const Advenue: {
     getDeviceId: () => string;
     shutdown(): void;
 };
+/**
+ * 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.
+ */
+declare function trackInstall(): Promise<void>;
 
-export { Advenue, type MMKVLike, type RNAdvenueConfig, type SecureStoreLike, applyAppState, collectDeviceInfo, createMMKVStorage, createSecureStore, getAndroidNative, getIosNative, parseDirectLink, resolveAdvertisingId, resolveClipboardMatch };
+export { Advenue, type AdvenueAndroidNativeModule, type AdvenueDeviceInfo, type AdvenueIosNativeModule, type InstallReferrerResult, type MMKVLike, type MetaInstallReferrerResult, type RNAdvenueConfig, type SecureStoreLike, type TrackingAuthorizationStatus, applyAppState, collectDeviceInfo, createMMKVStorage, createSecureStore, getAndroidNative, getIosNative, parseDirectLink, resolveAdvertisingId, resolveClipboardMatch, trackInstall };