deep-link-expo 1.0.0

package/dist/navigation/navigation-tracker.d.ts

@@ -0,0 +1,52 @@
+/**
+ * NavigationTracker — auto-emits `screen_view` events from React Navigation.
+ *
+ * When `autoTrackNavigation` is enabled with a `navigationRef`, the SDK
+ * subscribes to React Navigation's `'state'` event and emits a `screen_view`
+ * for the active route on each change — debounced (rapid transitions collapse to
+ * the final screen) and deduped (re-renders that don't change the screen are
+ * ignored). The event flows through the normal event pipeline, so it carries the
+ * active deep-link attribution context + session.
+ *
+ * Fully guarded: a missing/malformed `navigationRef` (or an app that doesn't use
+ * react-navigation) is a no-op, never a crash. The ref is typed structurally so
+ * there is no compile-time dependency on `@react-navigation/native`.
+ */
+import type { NavigationContainerRefLike } from '../models/config';
+/** Emit function the tracker calls — bound to the SDK's `trackEvent`. */
+export type ScreenEventEmitter = (name: string, properties: Record<string, unknown>) => void;
+export interface NavigationTrackerOptions {
+    /** Collapse rapid transitions; emit only the settled screen. Default 350ms. */
+    debounceMs?: number;
+    /**
+     * Explicit allow-list of route param keys whose primitive values may be
+     * captured. Omitted/empty = capture NO params (screen name only) — the
+     * privacy-safe default.
+     */
+    captureParams?: string[];
+}
+/**
+ * Reduce route params to a safe, flat set limited to an explicit allow-list of
+ * keys: only allow-listed keys are considered, and only primitive values
+ * survive (strings capped, nested objects/arrays/functions dropped). Returns
+ * undefined when nothing survives (including an empty/omitted allow-list).
+ */
+export declare function sanitizeScreenParams(params: Record<string, unknown> | undefined, allowList: string[] | undefined): Record<string, string | number | boolean> | undefined;
+export declare class NavigationTracker {
+    private readonly navigationRef;
+    private readonly emit;
+    private readonly debounceMs;
+    private readonly captureParams;
+    private unsubscribe;
+    private debounceTimer;
+    private lastScreen;
+    private started;
+    constructor(navigationRef: NavigationContainerRefLike, emit: ScreenEventEmitter, options?: NavigationTrackerOptions);
+    /** Subscribe to navigation changes. No-op if the ref is malformed. Idempotent. */
+    start(): void;
+    /** Unsubscribe and clear any pending debounce. Idempotent. */
+    stop(): void;
+    private scheduleCapture;
+    private captureCurrentScreen;
+}
+//# sourceMappingURL=navigation-tracker.d.ts.map

package/dist/navigation/navigation-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation-tracker.d.ts","sourceRoot":"","sources":["../../src/navigation/navigation-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,0BAA0B,EAAuB,MAAM,kBAAkB,CAAC;AAGxF,yEAAyE;AACzE,MAAM,MAAM,kBAAkB,GAAG,CAC/B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAChC,IAAI,CAAC;AAEV,MAAM,WAAW,wBAAwB;IACvC,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAMD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC3C,SAAS,EAAE,MAAM,EAAE,GAAG,SAAS,GAC9B,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,SAAS,CAkBvD;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6B;IAC3D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;IAC1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAuB;IAErD,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,aAAa,CAA8C;IACnE,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,OAAO,CAAS;gBAGtB,aAAa,EAAE,0BAA0B,EACzC,IAAI,EAAE,kBAAkB,EACxB,OAAO,GAAE,wBAA6B;IAQxC,kFAAkF;IAClF,KAAK,IAAI,IAAI;IAyCb,8DAA8D;IAC9D,IAAI,IAAI,IAAI;IAiBZ,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,oBAAoB;CAkC7B"}

package/dist/navigation/navigation-tracker.js

@@ -0,0 +1,153 @@
+/**
+ * NavigationTracker — auto-emits `screen_view` events from React Navigation.
+ *
+ * When `autoTrackNavigation` is enabled with a `navigationRef`, the SDK
+ * subscribes to React Navigation's `'state'` event and emits a `screen_view`
+ * for the active route on each change — debounced (rapid transitions collapse to
+ * the final screen) and deduped (re-renders that don't change the screen are
+ * ignored). The event flows through the normal event pipeline, so it carries the
+ * active deep-link attribution context + session.
+ *
+ * Fully guarded: a missing/malformed `navigationRef` (or an app that doesn't use
+ * react-navigation) is a no-op, never a crash. The ref is typed structurally so
+ * there is no compile-time dependency on `@react-navigation/native`.
+ */
+import { logger } from '../logger';
+const DEFAULT_DEBOUNCE_MS = 350;
+const SCREEN_VIEW_EVENT = 'screen_view';
+const MAX_PARAM_STRING_LENGTH = 256;
+/**
+ * Reduce route params to a safe, flat set limited to an explicit allow-list of
+ * keys: only allow-listed keys are considered, and only primitive values
+ * survive (strings capped, nested objects/arrays/functions dropped). Returns
+ * undefined when nothing survives (including an empty/omitted allow-list).
+ */
+export function sanitizeScreenParams(params, allowList) {
+    if (!params || typeof params !== 'object' || !allowList || allowList.length === 0) {
+        return undefined;
+    }
+    const allowed = new Set(allowList);
+    const out = {};
+    for (const [key, value] of Object.entries(params)) {
+        if (!allowed.has(key))
+            continue;
+        if (typeof value === 'string') {
+            out[key] =
+                value.length > MAX_PARAM_STRING_LENGTH ? value.slice(0, MAX_PARAM_STRING_LENGTH) : value;
+        }
+        else if (typeof value === 'number' || typeof value === 'boolean') {
+            out[key] = value;
+        }
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+export class NavigationTracker {
+    navigationRef;
+    emit;
+    debounceMs;
+    captureParams;
+    unsubscribe = null;
+    debounceTimer = null;
+    lastScreen = null;
+    started = false;
+    constructor(navigationRef, emit, options = {}) {
+        this.navigationRef = navigationRef;
+        this.emit = emit;
+        this.debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+        this.captureParams = options.captureParams;
+    }
+    /** Subscribe to navigation changes. No-op if the ref is malformed. Idempotent. */
+    start() {
+        if (this.started)
+            return;
+        if (!this.navigationRef ||
+            typeof this.navigationRef.addListener !== 'function' ||
+            typeof this.navigationRef.getCurrentRoute !== 'function') {
+            logger.warn('autoTrackNavigation enabled but navigationRef is missing or not a React Navigation container ref — screen tracking is disabled.');
+            return;
+        }
+        try {
+            const listener = this.navigationRef.addListener('state', () => {
+                this.scheduleCapture();
+            });
+            if (typeof listener === 'function') {
+                this.unsubscribe = listener;
+            }
+            else if (listener && typeof listener.remove === 'function') {
+                this.unsubscribe = () => listener.remove?.();
+            }
+            else {
+                this.unsubscribe = null;
+            }
+            this.started = true;
+            const ready = typeof this.navigationRef.isReady === 'function' ? this.navigationRef.isReady() : true;
+            if (ready) {
+                this.captureCurrentScreen();
+            }
+            logger.log('Navigation tracking started');
+        }
+        catch (e) {
+            logger.warn('Failed to start navigation tracking:', e);
+        }
+    }
+    /** Unsubscribe and clear any pending debounce. Idempotent. */
+    stop() {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        if (this.unsubscribe) {
+            try {
+                this.unsubscribe();
+            }
+            catch {
+                // ignore teardown errors
+            }
+            this.unsubscribe = null;
+        }
+        this.started = false;
+        this.lastScreen = null;
+    }
+    scheduleCapture() {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+        }
+        this.debounceTimer = setTimeout(() => {
+            this.debounceTimer = null;
+            this.captureCurrentScreen();
+        }, this.debounceMs);
+    }
+    captureCurrentScreen() {
+        let route;
+        try {
+            route = this.navigationRef.getCurrentRoute();
+        }
+        catch (e) {
+            logger.warn('getCurrentRoute failed:', e);
+            return;
+        }
+        if (!route || !route.name)
+            return;
+        // Dedupe: ignore state changes that don't move to a different screen.
+        if (route.name === this.lastScreen)
+            return;
+        const previousScreen = this.lastScreen;
+        this.lastScreen = route.name;
+        const properties = { screen: route.name };
+        if (previousScreen) {
+            properties.previousScreen = previousScreen;
+        }
+        if (this.captureParams && this.captureParams.length > 0) {
+            const params = sanitizeScreenParams(route.params, this.captureParams);
+            if (params) {
+                properties.params = params;
+            }
+        }
+        try {
+            this.emit(SCREEN_VIEW_EVENT, properties);
+        }
+        catch (e) {
+            logger.warn('Failed to emit screen_view:', e);
+        }
+    }
+}

package/dist/network/network-manager.d.ts

@@ -0,0 +1,13 @@
+export interface NetworkManagerProtocol {
+    request<T>(endpoint: string, options?: RequestInit): Promise<T>;
+}
+export declare class NetworkManager implements NetworkManagerProtocol {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly maxRetries;
+    constructor(baseUrl: string, apiKey?: string);
+    request<T>(endpoint: string, options?: RequestInit): Promise<T>;
+    private performRequest;
+    private delay;
+}
+//# sourceMappingURL=network-manager.d.ts.map

package/dist/network/network-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network-manager.d.ts","sourceRoot":"","sources":["../../src/network/network-manager.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACjE;AAED,qBAAa,cAAe,YAAW,sBAAsB;IAC3D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAK;gBAEpB,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;IAKtC,OAAO,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,CAAC,CAAC;YA+C3D,cAAc;IA0C5B,OAAO,CAAC,KAAK;CAGd"}

package/dist/network/network-manager.js

@@ -0,0 +1,90 @@
+import { LinkFortyError } from '../errors/linkforty-error';
+import { logger } from '../logger';
+import { SDK_NAME, SDK_VERSION } from '../version';
+export class NetworkManager {
+    baseUrl;
+    apiKey;
+    maxRetries = 3;
+    constructor(baseUrl, apiKey) {
+        this.baseUrl = baseUrl.replace(/\/+$/, '');
+        this.apiKey = apiKey;
+    }
+    async request(endpoint, options = {}) {
+        let lastError;
+        for (let attempt = 1; attempt <= this.maxRetries; attempt++) {
+            try {
+                return await this.performRequest(endpoint, options);
+            }
+            catch (e) {
+                lastError = e;
+                // Don't retry on client errors (4xx) or non-retryable errors
+                if (e instanceof LinkFortyError) {
+                    if (e.code === 'INVALID_RESPONSE' &&
+                        e.message.match(/status: (\d+)/)) {
+                        const statusMatch = e.message.match(/status: (\d+)/);
+                        if (statusMatch) {
+                            const status = parseInt(statusMatch[1], 10);
+                            if (status >= 400 && status < 500)
+                                throw e;
+                        }
+                    }
+                    if (e.code === 'INVALID_CONFIGURATION' ||
+                        e.code === 'DECODING_ERROR') {
+                        throw e;
+                    }
+                }
+                // Exponential backoff: 1s, 2s, 4s
+                if (attempt < this.maxRetries) {
+                    const delayMs = Math.pow(2, attempt - 1) * 1000;
+                    logger.log(`Request failed (attempt ${attempt}/${this.maxRetries}), retrying in ${delayMs / 1000}s...`);
+                    await this.delay(delayMs);
+                }
+            }
+        }
+        throw lastError instanceof LinkFortyError
+            ? lastError
+            : LinkFortyError.networkError(lastError ?? new Error(`Request failed after ${this.maxRetries} attempts`));
+    }
+    async performRequest(endpoint, options) {
+        const url = `${this.baseUrl}${endpoint}`;
+        const headers = {
+            'Content-Type': 'application/json',
+            // SDK identity header (SIT-235) — name/version on every SDK request.
+            'X-LinkForty-SDK': `${SDK_NAME}/${SDK_VERSION}`,
+            ...options.headers,
+        };
+        if (this.apiKey) {
+            headers['Authorization'] = `Bearer ${this.apiKey}`;
+        }
+        let response;
+        try {
+            response = await fetch(url, {
+                ...options,
+                headers,
+            });
+        }
+        catch (e) {
+            throw LinkFortyError.networkError(e);
+        }
+        if (!response.ok) {
+            let message;
+            try {
+                const body = await response.json();
+                message = body.message || body.error;
+            }
+            catch {
+                // ignore parse failure
+            }
+            throw LinkFortyError.invalidResponse(response.status, message);
+        }
+        try {
+            return (await response.json());
+        }
+        catch (e) {
+            throw LinkFortyError.decodingError(e);
+        }
+    }
+    delay(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}

package/dist/storage/storage-keys.d.ts

@@ -0,0 +1,8 @@
+export declare const STORAGE_KEYS: {
+    readonly INSTALL_ID: "@linkforty:install_id";
+    readonly INSTALL_DATA: "@linkforty:install_data";
+    readonly FIRST_LAUNCH: "@linkforty:first_launch";
+    readonly EVENT_QUEUE: "@linkforty:event_queue";
+    readonly ATTRIBUTION: "@linkforty:attribution";
+};
+//# sourceMappingURL=storage-keys.d.ts.map

package/dist/storage/storage-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-keys.d.ts","sourceRoot":"","sources":["../../src/storage/storage-keys.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,YAAY;;;;;;CAMf,CAAC"}

package/dist/storage/storage-keys.js

@@ -0,0 +1,7 @@
+export const STORAGE_KEYS = {
+    INSTALL_ID: '@linkforty:install_id',
+    INSTALL_DATA: '@linkforty:install_data',
+    FIRST_LAUNCH: '@linkforty:first_launch',
+    EVENT_QUEUE: '@linkforty:event_queue',
+    ATTRIBUTION: '@linkforty:attribution',
+};

package/dist/storage/storage-manager.d.ts

@@ -0,0 +1,20 @@
+import type { DeepLinkData } from '../models/deep-link-data';
+export interface StorageManagerProtocol {
+    saveInstallId(installId: string): Promise<void>;
+    getInstallId(): Promise<string | null>;
+    saveInstallData(data: DeepLinkData): Promise<void>;
+    getInstallData(): Promise<DeepLinkData | null>;
+    isFirstLaunch(): Promise<boolean>;
+    setHasLaunched(): Promise<void>;
+    clearAll(): Promise<void>;
+}
+export declare class StorageManager implements StorageManagerProtocol {
+    saveInstallId(installId: string): Promise<void>;
+    getInstallId(): Promise<string | null>;
+    saveInstallData(data: DeepLinkData): Promise<void>;
+    getInstallData(): Promise<DeepLinkData | null>;
+    isFirstLaunch(): Promise<boolean>;
+    setHasLaunched(): Promise<void>;
+    clearAll(): Promise<void>;
+}
+//# sourceMappingURL=storage-manager.d.ts.map

package/dist/storage/storage-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-manager.d.ts","sourceRoot":"","sources":["../../src/storage/storage-manager.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAI7D,MAAM,WAAW,sBAAsB;IACrC,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,YAAY,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACvC,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,cAAc,IAAI,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAC/C,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAClC,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED,qBAAa,cAAe,YAAW,sBAAsB;IACrD,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/C,YAAY,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAItC,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAQlD,cAAc,IAAI,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAW9C,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC;IAKjC,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAI/B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAQhC"}

package/dist/storage/storage-manager.js

@@ -0,0 +1,46 @@
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { logger } from '../logger';
+import { STORAGE_KEYS } from './storage-keys';
+export class StorageManager {
+    async saveInstallId(installId) {
+        await AsyncStorage.setItem(STORAGE_KEYS.INSTALL_ID, installId);
+    }
+    async getInstallId() {
+        return AsyncStorage.getItem(STORAGE_KEYS.INSTALL_ID);
+    }
+    async saveInstallData(data) {
+        try {
+            await AsyncStorage.setItem(STORAGE_KEYS.INSTALL_DATA, JSON.stringify(data));
+        }
+        catch (e) {
+            logger.error('Failed to encode install data:', e);
+        }
+    }
+    async getInstallData() {
+        try {
+            const json = await AsyncStorage.getItem(STORAGE_KEYS.INSTALL_DATA);
+            if (!json)
+                return null;
+            return JSON.parse(json);
+        }
+        catch (e) {
+            logger.error('Failed to decode install data:', e);
+            return null;
+        }
+    }
+    async isFirstLaunch() {
+        const flag = await AsyncStorage.getItem(STORAGE_KEYS.FIRST_LAUNCH);
+        return flag === null;
+    }
+    async setHasLaunched() {
+        await AsyncStorage.setItem(STORAGE_KEYS.FIRST_LAUNCH, 'true');
+    }
+    async clearAll() {
+        await AsyncStorage.multiRemove([
+            STORAGE_KEYS.INSTALL_ID,
+            STORAGE_KEYS.INSTALL_DATA,
+            STORAGE_KEYS.FIRST_LAUNCH,
+            STORAGE_KEYS.EVENT_QUEUE,
+        ]);
+    }
+}

package/dist/version.d.ts

@@ -0,0 +1,3 @@
+export declare const SDK_NAME = "expo";
+export declare const SDK_VERSION = "1.0.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,QAAQ,SAAS,CAAC;AAC/B,eAAO,MAAM,WAAW,UAAU,CAAC"}

package/dist/version.js

@@ -0,0 +1,3 @@
+// AUTO-GENERATED at build from package.json by scripts/gen-version.mjs — do not edit by hand.
+export const SDK_NAME = 'expo';
+export const SDK_VERSION = '1.0.0';