deep-link-expo 1.0.0

package/src/deeplink/deep-link-handler.ts

@@ -0,0 +1,171 @@
+import * as Linking from 'expo-linking';
+import type { FingerprintCollectorProtocol } from '../fingerprint/fingerprint-collector';
+import type { NetworkManagerProtocol } from '../network/network-manager';
+import type { DeepLinkData } from '../models/deep-link-data';
+import { parseDeepLinkUrl, parseUrlString, buildQueryString } from './url-parser';
+import { logger } from '../logger';
+
+export type DeferredDeepLinkCallback = (deepLinkData: DeepLinkData | null) => void;
+export type DeepLinkCallback = (url: string, deepLinkData: DeepLinkData | null) => void;
+
+export class DeepLinkHandler {
+  private baseUrl: string;
+  private network: NetworkManagerProtocol;
+  private fingerprint: FingerprintCollectorProtocol;
+  private linkPathPrefix: string | undefined;
+
+  private deferredCallbacks: DeferredDeepLinkCallback[] = [];
+  private deepLinkCallbacks: DeepLinkCallback[] = [];
+  private deferredDelivered = false;
+  private cachedDeferredData: DeepLinkData | null = null;
+  private subscription: { remove(): void } | null = null;
+
+  constructor(
+    baseUrl: string,
+    network: NetworkManagerProtocol,
+    fingerprint: FingerprintCollectorProtocol,
+    linkPathPrefix?: string,
+  ) {
+    this.baseUrl = baseUrl.replace(/\/+$/, '');
+    this.network = network;
+    this.fingerprint = fingerprint;
+    this.linkPathPrefix = linkPathPrefix?.replace(/^\/+|\/+$/g, '') || undefined;
+  }
+
+  /**
+   * Start listening for deep links via expo-linking.
+   */
+  startListening(): void {
+    this.subscription = Linking.addEventListener('url', (event: { url: string }) => {
+      this.handleUrl(event.url);
+    });
+
+    // Check if app was opened via deep link
+    Linking.getInitialURL()
+      .then((url) => {
+        if (url) {
+          this.handleUrl(url);
+        }
+      })
+      .catch((e) => {
+        logger.warn('Failed to get initial URL:', e);
+      });
+  }
+
+  /**
+   * Manually pass a deep link URL.
+   */
+  handleDeepLink(url: string): void {
+    this.handleUrl(url);
+  }
+
+  /**
+   * Register a deferred deep link callback.
+   * If data was already delivered, calls back immediately.
+   */
+  onDeferredDeepLink(callback: DeferredDeepLinkCallback): void {
+    this.deferredCallbacks.push(callback);
+
+    if (this.deferredDelivered) {
+      callback(this.cachedDeferredData);
+    }
+  }
+
+  /**
+   * Register a direct deep link callback. Multiple callbacks supported.
+   */
+  onDeepLink(callback: DeepLinkCallback): void {
+    this.deepLinkCallbacks.push(callback);
+  }
+
+  /**
+   * Deliver deferred deep link data (called by SDK after install attribution).
+   */
+  deliverDeferredDeepLink(data: DeepLinkData | null): void {
+    this.cachedDeferredData = data;
+    this.deferredDelivered = true;
+    logger.log('Delivering deferred deep link:', data?.shortCode ?? 'organic');
+
+    for (const cb of this.deferredCallbacks) {
+      cb(data);
+    }
+  }
+
+  clearCallbacks(): void {
+    this.deferredCallbacks = [];
+    this.deepLinkCallbacks = [];
+    this.deferredDelivered = false;
+    this.cachedDeferredData = null;
+  }
+
+  cleanup(): void {
+    this.subscription?.remove();
+    this.subscription = null;
+    this.clearCallbacks();
+  }
+
+  private handleUrl(url: string): void {
+    if (!url || this.deepLinkCallbacks.length === 0) return;
+
+    logger.log('Handling deep link:', url);
+
+    // Parse locally first as fallback
+    const localData = parseDeepLinkUrl(url, this.baseUrl);
+
+    // If this is a LinkForty URL, try server-side resolution
+    if (localData && url.startsWith(this.baseUrl)) {
+      this.resolveUrl(url)
+        .then((resolvedData) => {
+          const data = resolvedData ?? localData;
+          for (const cb of this.deepLinkCallbacks) cb(url, data);
+        })
+        .catch(() => {
+          for (const cb of this.deepLinkCallbacks) cb(url, localData);
+        });
+    } else {
+      for (const cb of this.deepLinkCallbacks) cb(url, localData);
+    }
+  }
+
+  private async resolveUrl(url: string): Promise<DeepLinkData | null> {
+    const parsed = parseUrlString(url);
+    if (!parsed) return null;
+
+    const pathSegments = parsed.pathname.split('/').filter(Boolean);
+    if (pathSegments.length === 0) return null;
+
+    let resolvePath: string;
+    if (this.linkPathPrefix && pathSegments[0] === this.linkPathPrefix && pathSegments[1]) {
+      resolvePath = `/api/sdk/v1/resolve/${pathSegments[0]}/${pathSegments[1]}`;
+    } else if (pathSegments.length >= 2) {
+      resolvePath = `/api/sdk/v1/resolve/${pathSegments[0]}/${pathSegments[1]}`;
+    } else if (this.linkPathPrefix) {
+      resolvePath = `/api/sdk/v1/resolve/${this.linkPathPrefix}/${pathSegments[0]}`;
+    } else {
+      resolvePath = `/api/sdk/v1/resolve/${pathSegments[0]}`;
+    }
+
+    // Collect fingerprint for click attribution
+    try {
+      const fp = this.fingerprint.collect(168);
+      const fpParams: Record<string, string> = {
+        fp_tz: fp.timezone,
+        fp_lang: fp.language,
+        fp_sw: String(fp.screenWidth),
+        fp_sh: String(fp.screenHeight),
+        fp_platform: fp.platform,
+        fp_pv: fp.platformVersion,
+      };
+      resolvePath += `?${buildQueryString(fpParams)}`;
+    } catch (e) {
+      logger.warn('Fingerprint collection failed, resolving without fingerprint:', e);
+    }
+
+    try {
+      return await this.network.request<DeepLinkData>(resolvePath);
+    } catch (e) {
+      logger.warn('Server-side resolution failed:', e);
+      return null;
+    }
+  }
+}

package/src/deeplink/url-parser.ts

@@ -0,0 +1,96 @@
+import type { DeepLinkData } from '../models/deep-link-data';
+import type { UTMParameters } from '../models/utm-parameters';
+
+interface ParsedUrl {
+  pathname: string;
+  searchParams: Map<string, string>;
+}
+
+/**
+ * Hermes-safe URL parsing (URL.pathname may throw "not implemented" in Hermes).
+ */
+export function parseUrlString(url: string): ParsedUrl | null {
+  try {
+    const protocolEnd = url.indexOf('://');
+    if (protocolEnd === -1) return null;
+
+    const afterProtocol = url.substring(protocolEnd + 3);
+    const pathStart = afterProtocol.indexOf('/');
+    const pathAndQuery = pathStart === -1 ? '/' : afterProtocol.substring(pathStart);
+
+    const hashIndex = pathAndQuery.indexOf('#');
+    const withoutHash = hashIndex === -1 ? pathAndQuery : pathAndQuery.substring(0, hashIndex);
+
+    const queryStart = withoutHash.indexOf('?');
+    const pathname = queryStart === -1 ? withoutHash : withoutHash.substring(0, queryStart);
+    const queryString = queryStart === -1 ? '' : withoutHash.substring(queryStart + 1);
+
+    const searchParams = new Map<string, string>();
+    if (queryString) {
+      for (const pair of queryString.split('&')) {
+        const eqIndex = pair.indexOf('=');
+        if (eqIndex === -1) {
+          searchParams.set(decodeURIComponent(pair), '');
+        } else {
+          searchParams.set(
+            decodeURIComponent(pair.substring(0, eqIndex)),
+            decodeURIComponent(pair.substring(eqIndex + 1)),
+          );
+        }
+      }
+    }
+
+    return { pathname, searchParams };
+  } catch {
+    return null;
+  }
+}
+
+export function buildQueryString(params: Record<string, string>): string {
+  return Object.entries(params)
+    .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
+    .join('&');
+}
+
+const UTM_KEYS = new Set(['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content']);
+
+export function parseDeepLinkUrl(url: string, baseUrl?: string): DeepLinkData | null {
+  // If baseUrl is set, only parse URLs matching it
+  if (baseUrl && !url.startsWith(baseUrl)) {
+    return null;
+  }
+
+  const parsed = parseUrlString(url);
+  if (!parsed) return null;
+
+  const pathSegments = parsed.pathname.split('/').filter(Boolean);
+  const shortCode = pathSegments[pathSegments.length - 1];
+  if (!shortCode) return null;
+
+  // Extract UTM parameters
+  const utmParameters: UTMParameters = {};
+  let hasUtm = false;
+  for (const [key, value] of parsed.searchParams) {
+    if (key === 'utm_source') { utmParameters.source = value; hasUtm = true; }
+    else if (key === 'utm_medium') { utmParameters.medium = value; hasUtm = true; }
+    else if (key === 'utm_campaign') { utmParameters.campaign = value; hasUtm = true; }
+    else if (key === 'utm_term') { utmParameters.term = value; hasUtm = true; }
+    else if (key === 'utm_content') { utmParameters.content = value; hasUtm = true; }
+  }
+
+  // Extract custom (non-UTM) parameters
+  const customParameters: Record<string, string> = {};
+  let hasCustom = false;
+  for (const [key, value] of parsed.searchParams) {
+    if (!UTM_KEYS.has(key)) {
+      customParameters[key] = value;
+      hasCustom = true;
+    }
+  }
+
+  return {
+    shortCode,
+    utmParameters: hasUtm ? utmParameters : undefined,
+    customParameters: hasCustom ? customParameters : undefined,
+  };
+}

package/src/errors/linkforty-error.ts

@@ -0,0 +1,89 @@
+export enum LinkFortyErrorCode {
+  NOT_INITIALIZED = 'NOT_INITIALIZED',
+  ALREADY_INITIALIZED = 'ALREADY_INITIALIZED',
+  INVALID_CONFIGURATION = 'INVALID_CONFIGURATION',
+  NETWORK_ERROR = 'NETWORK_ERROR',
+  INVALID_RESPONSE = 'INVALID_RESPONSE',
+  DECODING_ERROR = 'DECODING_ERROR',
+  INVALID_EVENT_DATA = 'INVALID_EVENT_DATA',
+  INVALID_DEEP_LINK_URL = 'INVALID_DEEP_LINK_URL',
+  MISSING_API_KEY = 'MISSING_API_KEY',
+}
+
+export class LinkFortyError extends Error {
+  readonly code: LinkFortyErrorCode;
+  readonly cause?: Error;
+
+  constructor(code: LinkFortyErrorCode, message: string, cause?: Error) {
+    super(message);
+    this.name = 'LinkFortyError';
+    this.code = code;
+    this.cause = cause;
+  }
+
+  static notInitialized(): LinkFortyError {
+    return new LinkFortyError(
+      LinkFortyErrorCode.NOT_INITIALIZED,
+      'LinkForty SDK is not initialized. Call initialize() first.',
+    );
+  }
+
+  static alreadyInitialized(): LinkFortyError {
+    return new LinkFortyError(
+      LinkFortyErrorCode.ALREADY_INITIALIZED,
+      'LinkForty SDK has already been initialized.',
+    );
+  }
+
+  static invalidConfiguration(detail: string): LinkFortyError {
+    return new LinkFortyError(
+      LinkFortyErrorCode.INVALID_CONFIGURATION,
+      `Invalid configuration: ${detail}`,
+    );
+  }
+
+  static networkError(cause: Error): LinkFortyError {
+    return new LinkFortyError(
+      LinkFortyErrorCode.NETWORK_ERROR,
+      `Network error: ${cause.message}`,
+      cause,
+    );
+  }
+
+  static invalidResponse(statusCode: number, message?: string): LinkFortyError {
+    const detail = message ? `: ${message}` : '';
+    return new LinkFortyError(
+      LinkFortyErrorCode.INVALID_RESPONSE,
+      `Invalid server response (status: ${statusCode})${detail}`,
+    );
+  }
+
+  static decodingError(cause: Error): LinkFortyError {
+    return new LinkFortyError(
+      LinkFortyErrorCode.DECODING_ERROR,
+      `Failed to decode response: ${cause.message}`,
+      cause,
+    );
+  }
+
+  static invalidEventData(detail: string): LinkFortyError {
+    return new LinkFortyError(
+      LinkFortyErrorCode.INVALID_EVENT_DATA,
+      `Invalid event data: ${detail}`,
+    );
+  }
+
+  static invalidDeepLinkUrl(detail: string): LinkFortyError {
+    return new LinkFortyError(
+      LinkFortyErrorCode.INVALID_DEEP_LINK_URL,
+      `Invalid deep link URL: ${detail}`,
+    );
+  }
+
+  static missingApiKey(): LinkFortyError {
+    return new LinkFortyError(
+      LinkFortyErrorCode.MISSING_API_KEY,
+      'API key is required for this operation. Provide an apiKey in the config.',
+    );
+  }
+}

package/src/events/event-queue.ts

@@ -0,0 +1,75 @@
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import type { EventRequest } from '../models/event-request';
+import { STORAGE_KEYS } from '../storage/storage-keys';
+import { logger } from '../logger';
+
+const MAX_QUEUE_SIZE = 100;
+
+export class EventQueue {
+  private queue: EventRequest[] = [];
+  private loaded = false;
+
+  async load(): Promise<void> {
+    if (this.loaded) return;
+    try {
+      const json = await AsyncStorage.getItem(STORAGE_KEYS.EVENT_QUEUE);
+      if (json) {
+        this.queue = JSON.parse(json) as EventRequest[];
+      }
+    } catch (e) {
+      logger.error('Failed to load event queue:', e);
+      this.queue = [];
+    }
+    this.loaded = true;
+  }
+
+  async enqueue(event: EventRequest): Promise<boolean> {
+    await this.load();
+    if (this.queue.length >= MAX_QUEUE_SIZE) {
+      logger.log('Event queue full, dropping event:', event.eventName);
+      return false;
+    }
+    this.queue.push(event);
+    await this.persist();
+    logger.log(`Event queued: ${event.eventName} (queue size: ${this.queue.length})`);
+    return true;
+  }
+
+  async dequeue(): Promise<EventRequest | null> {
+    await this.load();
+    if (this.queue.length === 0) return null;
+    const event = this.queue.shift()!;
+    await this.persist();
+    return event;
+  }
+
+  async peek(): Promise<EventRequest[]> {
+    await this.load();
+    return [...this.queue];
+  }
+
+  async clear(): Promise<void> {
+    const size = this.queue.length;
+    this.queue = [];
+    await this.persist();
+    if (size > 0) {
+      logger.log(`Event queue cleared (${size} events removed)`);
+    }
+  }
+
+  get count(): number {
+    return this.queue.length;
+  }
+
+  get isEmpty(): boolean {
+    return this.queue.length === 0;
+  }
+
+  private async persist(): Promise<void> {
+    try {
+      await AsyncStorage.setItem(STORAGE_KEYS.EVENT_QUEUE, JSON.stringify(this.queue));
+    } catch (e) {
+      logger.error('Failed to persist event queue:', e);
+    }
+  }
+}

package/src/events/event-tracker.ts

@@ -0,0 +1,118 @@
+import type { NetworkManagerProtocol } from '../network/network-manager';
+import type { StorageManagerProtocol } from '../storage/storage-manager';
+import type { EventRequest } from '../models/event-request';
+import type { AttributionContext } from '../attribution/attribution-context';
+import { EventQueue } from './event-queue';
+import { LinkFortyError } from '../errors/linkforty-error';
+import { logger } from '../logger';
+import { SDK_NAME, SDK_VERSION } from '../version';
+
+export class EventTracker {
+  private readonly network: NetworkManagerProtocol;
+  private readonly storage: StorageManagerProtocol;
+  private readonly queue: EventQueue;
+  private readonly attribution?: AttributionContext;
+
+  constructor(
+    network: NetworkManagerProtocol,
+    storage: StorageManagerProtocol,
+    queue?: EventQueue,
+    attribution?: AttributionContext,
+  ) {
+    this.network = network;
+    this.storage = storage;
+    this.queue = queue ?? new EventQueue();
+    this.attribution = attribution;
+  }
+
+  async trackEvent(name: string, properties?: Record<string, unknown>): Promise<void> {
+    if (!name || !name.trim()) {
+      throw LinkFortyError.invalidEventData('Event name cannot be empty');
+    }
+
+    const installId = await this.storage.getInstallId();
+    if (!installId) {
+      throw LinkFortyError.notInitialized();
+    }
+
+    // Stamp the event with the active last-click attribution + session so it can
+    // be credited to the originating deep link. Stamped at event time, so a
+    // queued event keeps its point-in-time attribution.
+    const event: EventRequest = {
+      installId,
+      eventName: name,
+      eventData: properties ?? {},
+      timestamp: new Date().toISOString(),
+      ...this.attribution?.getStamp(),
+      // SDK identity for health/version diagnostics (SIT-235)
+      sdkName: SDK_NAME,
+      sdkVersion: SDK_VERSION,
+    };
+
+    try {
+      await this.sendEvent(event);
+      logger.log('Event tracked:', name);
+
+      // If send succeeds, try to flush queued events
+      await this.flushQueue();
+    } catch (e) {
+      // Queue the event on failure
+      await this.queue.enqueue(event);
+      logger.log('Event queued due to error:', e);
+      throw e;
+    }
+  }
+
+  async trackRevenue(
+    amount: number,
+    currency: string,
+    properties?: Record<string, unknown>,
+  ): Promise<void> {
+    if (amount < 0) {
+      throw LinkFortyError.invalidEventData('Revenue amount must be non-negative');
+    }
+
+    const eventProperties: Record<string, unknown> = {
+      ...properties,
+      revenue: amount,
+      currency,
+    };
+
+    await this.trackEvent('revenue', eventProperties);
+  }
+
+  async flushQueue(): Promise<void> {
+    await this.queue.load();
+    logger.log(`Flushing event queue (${this.queue.count} events)`);
+
+    while (!this.queue.isEmpty) {
+      const event = await this.queue.dequeue();
+      if (!event) break;
+
+      try {
+        await this.sendEvent(event);
+        logger.log('Queued event sent:', event.eventName);
+      } catch (e) {
+        // Re-queue the event and stop flushing
+        await this.queue.enqueue(event);
+        logger.log('Failed to send queued event:', e);
+        return;
+      }
+    }
+  }
+
+  async clearQueue(): Promise<void> {
+    await this.queue.clear();
+  }
+
+  get queuedEventCount(): number {
+    return this.queue.count;
+  }
+
+  private async sendEvent(event: EventRequest): Promise<void> {
+    await this.network.request('/api/sdk/v1/event', {
+      method: 'POST',
+      body: JSON.stringify(event),
+    });
+  }
+}

package/src/fingerprint/fingerprint-collector.ts

@@ -0,0 +1,35 @@
+import * as Device from 'expo-device';
+import * as Application from 'expo-application';
+import { getLocales, getCalendars } from 'expo-localization';
+import { Platform, Dimensions } from 'react-native';
+import type { DeviceFingerprint } from '../models/device-fingerprint';
+
+export interface FingerprintCollectorProtocol {
+  collect(attributionWindowHours: number, deviceId?: string): DeviceFingerprint;
+}
+
+export class FingerprintCollector implements FingerprintCollectorProtocol {
+  collect(attributionWindowHours: number, deviceId?: string): DeviceFingerprint {
+    const { width, height } = Dimensions.get('window');
+    const locales = getLocales();
+    const calendars = getCalendars();
+
+    const appName = Application.applicationName ?? 'App';
+    const appVersion = Application.nativeApplicationVersion ?? '1.0.0';
+    const platform = Platform.OS;
+    const platformVersion = Device.osVersion ?? '0';
+
+    return {
+      userAgent: `${appName}/${appVersion} ${platform}/${platformVersion}`,
+      timezone: calendars[0]?.timeZone ?? 'UTC',
+      language: locales[0]?.languageTag ?? 'en-US',
+      screenWidth: Math.round(width),
+      screenHeight: Math.round(height),
+      platform,
+      platformVersion,
+      appVersion,
+      deviceId,
+      attributionWindowHours,
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+export { default } from './linkforty-sdk';
+export { default as DeepLink } from './linkforty-sdk';
+export { LinkFortySDK } from './linkforty-sdk';
+
+export { LinkFortyError, LinkFortyErrorCode } from './errors/linkforty-error';
+
+export type {
+  LinkFortyConfig,
+  AutoTrackNavigationOptions,
+  NavigationRouteLike,
+  NavigationContainerRefLike,
+} from './models/config';
+export type { DeepLinkData } from './models/deep-link-data';
+export type { InstallAttributionResponse } from './models/install-response';
+export type { UTMParameters } from './models/utm-parameters';
+export type { DeviceFingerprint } from './models/device-fingerprint';
+export type { CreateLinkOptions } from './models/create-link-options';
+export type { CreateLinkResult } from './models/create-link-result';
+export type { EventRequest } from './models/event-request';
+export type { ActiveAttribution, AttributionStamp } from './models/attribution';
+
+export { AttributionContext } from './attribution/attribution-context';
+export { NavigationTracker, sanitizeScreenParams } from './navigation/navigation-tracker';
+export type {
+  ScreenEventEmitter,
+  NavigationTrackerOptions,
+} from './navigation/navigation-tracker';
+
+export type { DeferredDeepLinkCallback, DeepLinkCallback } from './deeplink/deep-link-handler';