@advenue/react-native 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Advenue
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+# @advenue/react-native
+
+React Native / Expo SDK for [Advenue](https://advenue.io) — the open-source,
+self-hostable mobile attribution platform (MMP). Tracks installs, sessions and
+in-app events, resolves deferred deep links, and feeds Advenue's attribution
+engine.
+
+## Install
+
+```sh
+npx expo install @advenue/react-native @advenue/sdk-android @advenue/sdk-ios \
+  react-native-mmkv expo-secure-store
+```
+
+`@advenue/sdk-android` and `@advenue/sdk-ios` are Expo native modules built by
+your app's own Gradle/Xcode build — no manual linking.
+
+## Quick start
+
+```ts
+import { Advenue } from '@advenue/react-native';
+import { MMKV } from 'react-native-mmkv';
+import * as SecureStore from 'expo-secure-store';
+
+await Advenue.initialize({
+  apiKey: 'apk_live_...',        // from your Advenue dashboard
+  platform: 'ios',               // or 'android'
+  mmkv: new MMKV(),              // offline event buffering
+  secureStore: SecureStore,      // durable device identity
+  // endpoint: 'https://ingest.your-domain.com',  // self-hosted only
+});
+
+Advenue.track('signup_completed', { plan: 'pro' });
+```
+
+## Deep links (Universal Links / App Links)
+
+Add the config plugin so install-time deep links resolve on device:
+
+```jsonc
+// app.json
+"plugins": [
+  ["@advenue/react-native/plugin", { "domains": ["go.advenue.io"] }]
+]
+```
+
+## Docs
+
+Full integration guide, event reference and self-hosting docs:
+[docs.advenue.io](https://docs.advenue.io)
+
+## License
+
+MIT — the SDK is intentionally MIT-licensed so it can ship inside any app.
+The Advenue server platform is licensed separately (AGPLv3).

package/dist/index.d.ts

@@ -0,0 +1,161 @@
+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
+ * 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.
+ */
+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). */
+declare function createMMKVStorage(mmkv: MMKVLike): StorageAdapter;
+
+/**
+ * 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.
+ */
+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). */
+declare function createSecureStore(secureStore: SecureStoreLike): SecureStorageAdapter;
+
+/**
+ * Parses an OS-delivered link (Universal Link, App Link, or custom scheme) into
+ * the unified {@link DeepLink} shape. The `deepLinkValue` is a best-effort path
+ * (host + path for custom schemes, path for http(s)); the raw `url` is always
+ * provided so the host app can parse it itself when needed.
+ */
+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.
+ */
+declare function getIosNative(): AdvenueIosNativeModule | null;
+declare function getAndroidNative(): AdvenueAndroidNativeModule | null;
+
+/**
+ * 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.
+ */
+declare function resolveAdvertisingId(): Promise<void>;
+/**
+ * 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.
+ */
+declare function collectDeviceInfo(natives: {
+    platform: 'ios' | 'android' | string;
+    ios?: {
+        getDeviceInfo?: () => Partial<DeviceInfo>;
+    } | null;
+    android?: {
+        getDeviceInfo?: () => Partial<DeviceInfo>;
+    } | null;
+}): DeviceInfo;
+/**
+ * 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.)
+ */
+declare function resolveClipboardMatch(): Promise<DeepLink | null>;
+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.
+ */
+declare function applyAppState(client: Pick<AdvenueClient, 'notifyAppActive' | 'notifyAppBackground'>, status: string): void;
+/**
+ * React Native entry point. Wires MMKV-backed offline buffering automatically
+ * and re-exports the same track surface as the core SDK.
+ */
+declare const Advenue: {
+    initialize(config: RNAdvenueConfig): Promise<AdvenueClient>;
+    track: (name: string, properties?: Record<string, unknown>, opts?: TrackOptions) => void;
+    /**
+     * Shows the iOS ATT prompt (resolves 'authorized' immediately on Android/web,
+     * 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;
+    getTrackingConsent: () => boolean;
+    /** GDPR/CCPA erasure: stop tracking and wipe local identifiers/queue. */
+    forgetMe: () => void;
+    setConsentData(consent: Consent): void;
+    getConsentData: () => {
+        isUserSubjectToGDPR: boolean;
+        hasConsentForDataUsage?: boolean | undefined;
+        hasConsentForAdsPersonalization?: boolean | undefined;
+        hasConsentForAdStorage?: boolean | undefined;
+    } | null;
+    flush: () => Promise<void>;
+    getDeviceId: () => string;
+    shutdown(): void;
+};
+
+export { Advenue, type MMKVLike, type RNAdvenueConfig, type SecureStoreLike, applyAppState, collectDeviceInfo, createMMKVStorage, createSecureStore, getAndroidNative, getIosNative, parseDirectLink, resolveAdvertisingId, resolveClipboardMatch };