deep-link-expo 1.0.0

package/src/navigation/navigation-tracker.ts

@@ -0,0 +1,195 @@
+/**
+ * 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, NavigationRouteLike } from '../models/config';
+import { logger } from '../logger';
+
+/** 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[];
+}
+
+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: Record<string, unknown> | undefined,
+  allowList: string[] | undefined,
+): Record<string, string | number | boolean> | undefined {
+  if (!params || typeof params !== 'object' || !allowList || allowList.length === 0) {
+    return undefined;
+  }
+
+  const allowed = new Set(allowList);
+  const out: Record<string, string | number | boolean> = {};
+  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 {
+  private readonly navigationRef: NavigationContainerRefLike;
+  private readonly emit: ScreenEventEmitter;
+  private readonly debounceMs: number;
+  private readonly captureParams: string[] | undefined;
+
+  private unsubscribe: (() => void) | null = null;
+  private debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  private lastScreen: string | null = null;
+  private started = false;
+
+  constructor(
+    navigationRef: NavigationContainerRefLike,
+    emit: ScreenEventEmitter,
+    options: NavigationTrackerOptions = {},
+  ) {
+    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(): void {
+    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(): void {
+    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;
+  }
+
+  private scheduleCapture(): void {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+    }
+    this.debounceTimer = setTimeout(() => {
+      this.debounceTimer = null;
+      this.captureCurrentScreen();
+    }, this.debounceMs);
+  }
+
+  private captureCurrentScreen(): void {
+    let route: NavigationRouteLike | undefined;
+    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: Record<string, unknown> = { 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/src/network/network-manager.ts

@@ -0,0 +1,111 @@
+import { LinkFortyError } from '../errors/linkforty-error';
+import { logger } from '../logger';
+import { SDK_NAME, SDK_VERSION } from '../version';
+
+export interface NetworkManagerProtocol {
+  request<T>(endpoint: string, options?: RequestInit): Promise<T>;
+}
+
+export class NetworkManager implements NetworkManagerProtocol {
+  private readonly baseUrl: string;
+  private readonly apiKey: string | undefined;
+  private readonly maxRetries = 3;
+
+  constructor(baseUrl: string, apiKey?: string) {
+    this.baseUrl = baseUrl.replace(/\/+$/, '');
+    this.apiKey = apiKey;
+  }
+
+  async request<T>(endpoint: string, options: RequestInit = {}): Promise<T> {
+    let lastError: Error | undefined;
+
+    for (let attempt = 1; attempt <= this.maxRetries; attempt++) {
+      try {
+        return await this.performRequest<T>(endpoint, options);
+      } catch (e) {
+        lastError = e as Error;
+
+        // 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`),
+        );
+  }
+
+  private async performRequest<T>(endpoint: string, options: RequestInit): Promise<T> {
+    const url = `${this.baseUrl}${endpoint}`;
+
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      // SDK identity header (SIT-235) — name/version on every SDK request.
+      'X-LinkForty-SDK': `${SDK_NAME}/${SDK_VERSION}`,
+      ...(options.headers as Record<string, string> | undefined),
+    };
+
+    if (this.apiKey) {
+      headers['Authorization'] = `Bearer ${this.apiKey}`;
+    }
+
+    let response: Response;
+    try {
+      response = await fetch(url, {
+        ...options,
+        headers,
+      });
+    } catch (e) {
+      throw LinkFortyError.networkError(e as Error);
+    }
+
+    if (!response.ok) {
+      let message: string | undefined;
+      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()) as T;
+    } catch (e) {
+      throw LinkFortyError.decodingError(e as Error);
+    }
+  }
+
+  private delay(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}

package/src/storage/storage-keys.ts

@@ -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',
+} as const;

package/src/storage/storage-manager.ts

@@ -0,0 +1,61 @@
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import type { DeepLinkData } from '../models/deep-link-data';
+import { logger } from '../logger';
+import { STORAGE_KEYS } from './storage-keys';
+
+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 class StorageManager implements StorageManagerProtocol {
+  async saveInstallId(installId: string): Promise<void> {
+    await AsyncStorage.setItem(STORAGE_KEYS.INSTALL_ID, installId);
+  }
+
+  async getInstallId(): Promise<string | null> {
+    return AsyncStorage.getItem(STORAGE_KEYS.INSTALL_ID);
+  }
+
+  async saveInstallData(data: DeepLinkData): Promise<void> {
+    try {
+      await AsyncStorage.setItem(STORAGE_KEYS.INSTALL_DATA, JSON.stringify(data));
+    } catch (e) {
+      logger.error('Failed to encode install data:', e);
+    }
+  }
+
+  async getInstallData(): Promise<DeepLinkData | null> {
+    try {
+      const json = await AsyncStorage.getItem(STORAGE_KEYS.INSTALL_DATA);
+      if (!json) return null;
+      return JSON.parse(json) as DeepLinkData;
+    } catch (e) {
+      logger.error('Failed to decode install data:', e);
+      return null;
+    }
+  }
+
+  async isFirstLaunch(): Promise<boolean> {
+    const flag = await AsyncStorage.getItem(STORAGE_KEYS.FIRST_LAUNCH);
+    return flag === null;
+  }
+
+  async setHasLaunched(): Promise<void> {
+    await AsyncStorage.setItem(STORAGE_KEYS.FIRST_LAUNCH, 'true');
+  }
+
+  async clearAll(): Promise<void> {
+    await AsyncStorage.multiRemove([
+      STORAGE_KEYS.INSTALL_ID,
+      STORAGE_KEYS.INSTALL_DATA,
+      STORAGE_KEYS.FIRST_LAUNCH,
+      STORAGE_KEYS.EVENT_QUEUE,
+    ]);
+  }
+}

package/src/version.ts

@@ -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';