@advenue/react-native 0.4.0 → 0.6.0

package/src/native-types.ts

@@ -0,0 +1,169 @@
+// 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).
+
+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;
+}
+
+export 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.
+ */
+export interface AdvenueDeviceInfo {
+  model?: string;
+  locale?: string;
+  carrier?: string;
+  timezone?: string;
+  screenWidth?: number;
+  screenHeight?: number;
+  screenDensity?: number;
+  cpuCores?: number;
+  totalStorageGb?: number;
+  freeStorageGb?: number;
+}
+
+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("<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;
+}
+
+export type TrackingAuthorizationStatus = 'notDetermined' | 'restricted' | 'denied' | 'authorized';
+
+export 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;
+}

package/src/native.ts

@@ -1,16 +1,22 @@
-import type { AdvenueAndroidNativeModule } from '@advenue/sdk-android';
-import type { AdvenueIosNativeModule } from '@advenue/sdk-ios';
+import type { AdvenueAndroidNativeModule, AdvenueIosNativeModule } from './native-types';
 
 declare function require(id: string): unknown;
 
+type ExpoModulesCore = {
+  requireNativeModule<T>(name: string): T;
+};
+
 /**
- * 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.
  */
 export function getIosNative(): AdvenueIosNativeModule | null {
   try {
-    return (require('@advenue/sdk-ios') as { AdvenueIos: AdvenueIosNativeModule }).AdvenueIos;
+    const core = require('expo-modules-core') as ExpoModulesCore;
+    return core.requireNativeModule<AdvenueIosNativeModule>('AdvenueIos');
   } catch {
     return null;
   }
@@ -18,8 +24,8 @@ export function getIosNative(): AdvenueIosNativeModule | null {
 
 export function getAndroidNative(): AdvenueAndroidNativeModule | null {
   try {
-    return (require('@advenue/sdk-android') as { AdvenueAndroid: AdvenueAndroidNativeModule })
-      .AdvenueAndroid;
+    const core = require('expo-modules-core') as ExpoModulesCore;
+    return core.requireNativeModule<AdvenueAndroidNativeModule>('AdvenueAndroid');
   } catch {
     return null;
   }