deep-link-expo 1.0.0

package/src/linkforty-sdk.ts

@@ -0,0 +1,342 @@
+import type { LinkFortyConfig } from './models/config';
+import type { InstallAttributionResponse } from './models/install-response';
+import type { DeepLinkData } from './models/deep-link-data';
+import type { CreateLinkOptions } from './models/create-link-options';
+import type { CreateLinkResult } from './models/create-link-result';
+import type { DeferredDeepLinkCallback, DeepLinkCallback } from './deeplink/deep-link-handler';
+import { validateConfig } from './models/config';
+import { LinkFortyError } from './errors/linkforty-error';
+import { NetworkManager } from './network/network-manager';
+import { StorageManager } from './storage/storage-manager';
+import { FingerprintCollector } from './fingerprint/fingerprint-collector';
+import { AttributionManager } from './attribution/attribution-manager';
+import { AttributionContext } from './attribution/attribution-context';
+import { DeepLinkHandler } from './deeplink/deep-link-handler';
+import { EventTracker } from './events/event-tracker';
+import { EventQueue } from './events/event-queue';
+import { NavigationTracker } from './navigation/navigation-tracker';
+import { logger } from './logger';
+
+export class LinkFortySDK {
+  private config: LinkFortyConfig | null = null;
+  private networkManager: NetworkManager | null = null;
+  private attributionManager: AttributionManager | null = null;
+  private attributionContext: AttributionContext | null = null;
+  private deepLinkHandler: DeepLinkHandler | null = null;
+  private eventTracker: EventTracker | null = null;
+  private navigationTracker: NavigationTracker | null = null;
+  private externalUserId: string | null = null;
+  private _isInitialized = false;
+
+  get isInitialized(): boolean {
+    return this._isInitialized;
+  }
+
+  // -- Initialization --
+
+  async initialize(config: LinkFortyConfig): Promise<InstallAttributionResponse> {
+    if (this._isInitialized) {
+      throw LinkFortyError.alreadyInitialized();
+    }
+
+    validateConfig(config);
+    this.config = config;
+    logger.setDebug(config.debug ?? false);
+
+    logger.log('Initializing SDK with config:', {
+      baseUrl: config.baseUrl,
+      debug: config.debug,
+      attributionWindowHours: config.attributionWindowHours,
+      linkPathPrefix: config.linkPathPrefix,
+      apiKey: config.apiKey ? '***' : undefined,
+    });
+
+    // Create managers
+    const networkManager = new NetworkManager(config.baseUrl, config.apiKey);
+    const storageManager = new StorageManager();
+    const fingerprintCollector = new FingerprintCollector();
+    const eventQueue = new EventQueue();
+    await eventQueue.load();
+
+    this.networkManager = networkManager;
+
+    this.attributionManager = new AttributionManager(
+      networkManager,
+      storageManager,
+      fingerprintCollector,
+    );
+
+    // Last-click attribution context: restore any persisted active link before
+    // we attribute the install or handle deep links.
+    const attributionContext = new AttributionContext();
+    await attributionContext.load();
+    this.attributionContext = attributionContext;
+
+    this.eventTracker = new EventTracker(
+      networkManager,
+      storageManager,
+      eventQueue,
+      attributionContext,
+    );
+
+    const deepLinkHandler = new DeepLinkHandler(
+      config.baseUrl,
+      networkManager,
+      fingerprintCollector,
+      config.linkPathPrefix,
+    );
+    this.deepLinkHandler = deepLinkHandler;
+
+    // Record every direct (re-engagement) deep-link open into the attribution
+    // context so subsequent events credit the link the user just tapped — not
+    // their original install link. Registered before any developer callbacks.
+    deepLinkHandler.onDeepLink((_url, data) => {
+      if (data?.linkId) {
+        void attributionContext.recordDeepLinkOpen(data.linkId);
+      }
+    });
+
+    this._isInitialized = true;
+
+    // Report install
+    const attributionWindowHours = config.attributionWindowHours ?? 168;
+    const response = await this.attributionManager.reportInstall(
+      attributionWindowHours,
+      undefined, // deviceId — IDFA/GAID not collected by Expo SDK
+      config.appToken,
+    );
+
+    // If attributed, deliver deferred deep link + seed the attribution context so
+    // the new user's first-session events credit the install link.
+    if (response.attributed && response.deepLinkData) {
+      if (response.deepLinkData.linkId) {
+        await attributionContext.recordDeepLinkOpen(response.deepLinkData.linkId);
+      }
+      deepLinkHandler.deliverDeferredDeepLink(response.deepLinkData);
+    } else {
+      deepLinkHandler.deliverDeferredDeepLink(null);
+    }
+
+    // Start listening for direct deep links
+    deepLinkHandler.startListening();
+
+    // Optional auto screen-view tracking. Screen views flow through trackEvent,
+    // so they inherit the attribution stamp. Guarded: a missing/invalid
+    // navigationRef (or no react-navigation) is a no-op.
+    if (config.autoTrackNavigation) {
+      if (config.navigationRef) {
+        const navOptions =
+          typeof config.autoTrackNavigation === 'object' ? config.autoTrackNavigation : {};
+        this.navigationTracker = new NavigationTracker(
+          config.navigationRef,
+          (name, properties) => {
+            void this.trackEvent(name, properties);
+          },
+          { captureParams: navOptions.captureParams, debounceMs: navOptions.debounceMs },
+        );
+        this.navigationTracker.start();
+      } else {
+        logger.warn(
+          'autoTrackNavigation is enabled but no navigationRef was provided — screen tracking is disabled.',
+        );
+      }
+    }
+
+    logger.log('SDK initialized successfully (attributed:', response.attributed, ')');
+
+    return response;
+  }
+
+  // -- Deep Linking --
+
+  onDeferredDeepLink(callback: DeferredDeepLinkCallback): void {
+    this.requireDeepLinkHandler().onDeferredDeepLink(callback);
+  }
+
+  onDeepLink(callback: DeepLinkCallback): void {
+    this.requireDeepLinkHandler().onDeepLink(callback);
+  }
+
+  handleDeepLink(url: string): void {
+    this.requireDeepLinkHandler().handleDeepLink(url);
+  }
+
+  // -- User Identity --
+
+  /**
+   * Sets the external user ID for attribution. This ID will be attached to all
+   * links created via createLink() unless overridden per-call. Pass null to clear.
+   */
+  setExternalUserId(id: string | null): void {
+    this.externalUserId = id;
+    logger.log('External user ID set:', id);
+  }
+
+  /**
+   * Returns the current external user ID, if set.
+   */
+  getExternalUserId(): string | null {
+    return this.externalUserId;
+  }
+
+  // -- Event Tracking --
+
+  async trackEvent(name: string, properties?: Record<string, unknown>): Promise<void> {
+    return this.requireEventTracker().trackEvent(name, properties);
+  }
+
+  async trackRevenue(
+    amount: number,
+    currency: string,
+    properties?: Record<string, unknown>,
+  ): Promise<void> {
+    return this.requireEventTracker().trackRevenue(amount, currency, properties);
+  }
+
+  async flushEvents(): Promise<void> {
+    return this.requireEventTracker().flushQueue();
+  }
+
+  async clearEventQueue(): Promise<void> {
+    return this.requireEventTracker().clearQueue();
+  }
+
+  get queuedEventCount(): number {
+    return this.eventTracker?.queuedEventCount ?? 0;
+  }
+
+  // -- Link Creation --
+
+  async createLink(options: CreateLinkOptions): Promise<CreateLinkResult> {
+    this.requireInitialized();
+
+    if (!this.config!.apiKey) {
+      throw LinkFortyError.missingApiKey();
+    }
+
+    const body: Record<string, unknown> = {};
+    if (options.templateId) body.templateId = options.templateId;
+    if (options.deepLinkParameters) body.deepLinkParameters = options.deepLinkParameters;
+    if (options.title) body.title = options.title;
+    if (options.description) body.description = options.description;
+    if (options.customCode) body.customCode = options.customCode;
+    if (options.utmParameters) body.utmParameters = options.utmParameters;
+    if (options.webFallbackUrl) body.webFallbackUrl = options.webFallbackUrl;
+    // Per-call externalUserId takes precedence, then fall back to SDK-level value
+    const resolvedUserId = options.externalUserId ?? this.externalUserId;
+    if (resolvedUserId) body.externalUserId = resolvedUserId;
+
+    const useSimplifiedEndpoint = !options.templateId;
+    const endpoint = useSimplifiedEndpoint ? '/api/sdk/v1/links' : '/api/links';
+
+    const response = await this.networkManager!.request<{
+      id: string;
+      short_code: string;
+      url?: string;
+      shortCode?: string;
+      linkId?: string;
+      deduplicated?: boolean;
+    }>(endpoint, {
+      method: 'POST',
+      body: JSON.stringify(body),
+    });
+
+    // SDK endpoint returns { url, shortCode, linkId, deduplicated? } directly
+    if (useSimplifiedEndpoint && response.url) {
+      return {
+        url: response.url,
+        shortCode: response.shortCode || response.short_code,
+        linkId: response.linkId || response.id,
+        deduplicated: response.deduplicated,
+      };
+    }
+
+    // Dashboard endpoint returns { id, short_code } — build URL from parts
+    const shortCode = response.short_code;
+    const baseUrl = this.config!.baseUrl.replace(/\/+$/, '');
+    const prefix = (options.templateSlug || this.config!.linkPathPrefix || '').replace(/^\/+|\/+$/g, '');
+    const url = prefix
+      ? `${baseUrl}/${prefix}/${shortCode}`
+      : `${baseUrl}/${shortCode}`;
+
+    return {
+      url,
+      shortCode,
+      linkId: response.id,
+    };
+  }
+
+  // -- Attribution Data --
+
+  async getInstallId(): Promise<string | null> {
+    return this.attributionManager?.getInstallId() ?? null;
+  }
+
+  async getInstallData(): Promise<DeepLinkData | null> {
+    return this.attributionManager?.getInstallData() ?? null;
+  }
+
+  async isFirstLaunch(): Promise<boolean> {
+    return this.attributionManager?.isFirstLaunch() ?? true;
+  }
+
+  // -- Data Management --
+
+  async clearData(): Promise<void> {
+    await this.attributionManager?.clearData();
+    await this.attributionContext?.clear();
+    await this.eventTracker?.clearQueue();
+    this.deepLinkHandler?.clearCallbacks();
+    this.externalUserId = null;
+    logger.log('All SDK data cleared');
+  }
+
+  reset(): void {
+    this.deepLinkHandler?.cleanup();
+    this.navigationTracker?.stop();
+    this.config = null;
+    this.networkManager = null;
+    this.attributionManager = null;
+    this.attributionContext = null;
+    this.deepLinkHandler = null;
+    this.eventTracker = null;
+    this.navigationTracker = null;
+    this.externalUserId = null;
+    this._isInitialized = false;
+    logger.log('SDK reset to uninitialized state');
+  }
+
+  // -- Attribution Session --
+
+  /**
+   * Current session id — identifies one app-open journey. Rotates on cold start
+   * and on each new deep-link open. Used to group a visit's screen-flow.
+   */
+  getSessionId(): string | null {
+    return this.attributionContext?.getSessionId() ?? null;
+  }
+
+  // -- Guards --
+
+  private requireInitialized(): void {
+    if (!this._isInitialized) {
+      throw LinkFortyError.notInitialized();
+    }
+  }
+
+  private requireDeepLinkHandler(): DeepLinkHandler {
+    if (!this._isInitialized || !this.deepLinkHandler) {
+      throw LinkFortyError.notInitialized();
+    }
+    return this.deepLinkHandler;
+  }
+
+  private requireEventTracker(): EventTracker {
+    if (!this._isInitialized || !this.eventTracker) {
+      throw LinkFortyError.notInitialized();
+    }
+    return this.eventTracker;
+  }
+}
+
+export default new LinkFortySDK();

package/src/logger.ts

@@ -0,0 +1,23 @@
+const TAG = '[LinkForty]';
+
+let debugEnabled = false;
+
+export const logger = {
+  setDebug(enabled: boolean): void {
+    debugEnabled = enabled;
+  },
+
+  log(...args: unknown[]): void {
+    if (debugEnabled) {
+      console.log(TAG, ...args);
+    }
+  },
+
+  warn(...args: unknown[]): void {
+    console.warn(TAG, ...args);
+  },
+
+  error(...args: unknown[]): void {
+    console.error(TAG, ...args);
+  },
+};

package/src/models/attribution.ts

@@ -0,0 +1,29 @@
+/**
+ * Last-click attribution models (SIT-237).
+ *
+ * In-app activity (screen views + custom events) is attributed to the deep link
+ * that drove it. Every deep-link open pins an active context; the newest open
+ * supersedes the previous one; events are stamped with the active context so the
+ * backend can credit the link under a last-click + window model.
+ */
+
+/** The deep link currently credited for in-app activity (last-click). */
+export interface ActiveAttribution {
+  /** The link the deep link resolved to (`DeepLinkData.linkId`) */
+  linkId: string;
+  /** Optional originating click id (link-level attribution works without it) */
+  clickId?: string;
+  /** ISO timestamp of when this deep link opened the app */
+  openedAt: string;
+}
+
+/**
+ * Attribution fields merged into every event payload. `sessionId` is always
+ * present; the link fields are absent for organic activity (no deep link yet).
+ */
+export interface AttributionStamp {
+  attributedLinkId?: string;
+  attributedClickId?: string;
+  linkOpenedAt?: string;
+  sessionId: string;
+}

package/src/models/config.ts

@@ -0,0 +1,109 @@
+import { LinkFortyError } from '../errors/linkforty-error';
+
+export interface LinkFortyConfig {
+  /** Base URL of your LinkForty instance (e.g., 'https://go.yourdomain.com') */
+  baseUrl: string;
+  /**
+   * Per-app short-link path prefix (e.g. '/mQuDYblrf6'). Required when multiple
+   * apps share one domain so short codes resolve under this app's path.
+   */
+  linkPathPrefix?: string;
+  /** Optional API key for Cloud authentication */
+  apiKey?: string;
+  /**
+   * Public workspace token (LinkForty Cloud only). Recommended — required
+   * for organic installs (App Store discovery, social mentions, etc.) to
+   * be attributed to your workspace. Find it in the dashboard under
+   * Workspace Settings → App Token. Safe to ship in your app bundle.
+   * Format: `at_<32 hex chars>`.
+   */
+  appToken?: string;
+  /** Enable debug logging (default: false) */
+  debug?: boolean;
+  /** Attribution window in hours (default: 168 = 7 days) */
+  attributionWindowHours?: number;
+  /**
+   * Auto-emit `screen_view` events from React Navigation state (no manual
+   * per-screen calls). Requires `navigationRef`. Off by default.
+   *
+   * Pass `true` for the privacy-safe default (screen name only, no params). To
+   * capture specific non-PII params, pass an options object with an explicit
+   * allow-list: `{ captureParams: ['productId', 'category'] }`. Screen views flow
+   * through the normal event pipeline and carry the active deep-link attribution
+   * context. Apps without react-navigation are unaffected.
+   */
+  autoTrackNavigation?: boolean | AutoTrackNavigationOptions;
+  /**
+   * The app's React Navigation container ref (`createNavigationContainerRef()`),
+   * required when `autoTrackNavigation` is enabled. Typed structurally so this
+   * SDK never has a compile-time dependency on `@react-navigation/native`.
+   */
+  navigationRef?: NavigationContainerRefLike;
+}
+
+/**
+ * Options for `autoTrackNavigation`. No route params are captured by default;
+ * opt in per key via `captureParams`.
+ */
+export interface AutoTrackNavigationOptions {
+  /**
+   * Explicit allow-list of route param keys whose primitive values may be
+   * captured on `screen_view`. Omitted/empty = capture no params. Never list
+   * keys that can hold personal data.
+   */
+  captureParams?: string[];
+  /** Debounce window for rapid transitions, in ms. Default 350. */
+  debounceMs?: number;
+}
+
+/**
+ * The slice of a React Navigation route the SDK reads. Structural — matches
+ * `getCurrentRoute()` without importing `@react-navigation/native`.
+ */
+export interface NavigationRouteLike {
+  name: string;
+  params?: Record<string, unknown>;
+}
+
+/** The slice of a React Navigation container ref the SDK uses. Structural. */
+export interface NavigationContainerRefLike {
+  addListener: (
+    type: 'state',
+    callback: (event?: unknown) => void,
+  ) => (() => void) | { remove?: () => void } | void;
+  getCurrentRoute: () => NavigationRouteLike | undefined;
+  isReady?: () => boolean;
+}
+
+const LOCALHOST_HOSTS = ['localhost', '127.0.0.1', '0.0.0.0', '10.0.2.2'];
+
+export function validateConfig(config: LinkFortyConfig): void {
+  if (!config.baseUrl) {
+    throw LinkFortyError.invalidConfiguration('baseUrl is required');
+  }
+
+  // Parse URL to validate scheme
+  let parsed: URL;
+  try {
+    parsed = new URL(config.baseUrl);
+  } catch {
+    throw LinkFortyError.invalidConfiguration(`Invalid base URL: ${config.baseUrl}`);
+  }
+
+  // HTTPS required except for localhost
+  if (parsed.protocol !== 'https:' && !LOCALHOST_HOSTS.includes(parsed.hostname)) {
+    throw LinkFortyError.invalidConfiguration(
+      'Base URL must use HTTPS (HTTP only allowed for localhost)',
+    );
+  }
+
+  // Validate attribution window bounds
+  const windowHours = config.attributionWindowHours;
+  if (windowHours !== undefined) {
+    if (!Number.isFinite(windowHours) || windowHours < 1 || windowHours > 2160) {
+      throw LinkFortyError.invalidConfiguration(
+        'Attribution window must be between 1 and 2160 hours',
+      );
+    }
+  }
+}

package/src/models/create-link-options.ts

@@ -0,0 +1,15 @@
+import type { UTMParameters } from './utm-parameters';
+
+export interface CreateLinkOptions {
+  templateId?: string;
+  templateSlug?: string;
+  deepLinkParameters?: Record<string, string>;
+  title?: string;
+  description?: string;
+  customCode?: string;
+  utmParameters?: UTMParameters;
+  /** Identifier for the app user creating the link (enables per-user deduplication and share attribution) */
+  externalUserId?: string;
+  /** Web fallback URL — used when the app is not installed or on desktop browsers */
+  webFallbackUrl?: string;
+}

package/src/models/create-link-result.ts

@@ -0,0 +1,7 @@
+export interface CreateLinkResult {
+  url: string;
+  shortCode: string;
+  linkId: string;
+  /** True if an existing link was returned instead of creating a new one (per-user deduplication) */
+  deduplicated?: boolean;
+}

package/src/models/deep-link-data.ts

@@ -0,0 +1,14 @@
+import type { UTMParameters } from './utm-parameters';
+
+export interface DeepLinkData {
+  shortCode: string;
+  iosUrl?: string;
+  androidUrl?: string;
+  webUrl?: string;
+  utmParameters?: UTMParameters;
+  customParameters?: Record<string, string>;
+  deepLinkPath?: string;
+  appScheme?: string;
+  clickedAt?: string;
+  linkId?: string;
+}

package/src/models/device-fingerprint.ts

@@ -0,0 +1,12 @@
+export interface DeviceFingerprint {
+  userAgent: string;
+  timezone: string;
+  language: string;
+  screenWidth: number;
+  screenHeight: number;
+  platform: string;
+  platformVersion: string;
+  appVersion: string;
+  deviceId?: string;
+  attributionWindowHours: number;
+}

package/src/models/event-request.ts

@@ -0,0 +1,15 @@
+export interface EventRequest {
+  installId: string;
+  eventName: string;
+  eventData: Record<string, unknown>;
+  timestamp: string;
+  // Last-click attribution stamp (SIT-237) — optional / backward compatible.
+  // Captured at event time so queued events keep their point-in-time attribution.
+  attributedLinkId?: string;
+  attributedClickId?: string;
+  linkOpenedAt?: string;
+  sessionId?: string;
+  // SDK identity for health/version diagnostics (SIT-235)
+  sdkName?: string;
+  sdkVersion?: string;
+}

package/src/models/install-response.ts

@@ -0,0 +1,9 @@
+import type { DeepLinkData } from './deep-link-data';
+
+export interface InstallAttributionResponse {
+  installId: string;
+  attributed: boolean;
+  confidenceScore: number;
+  matchedFactors: string[];
+  deepLinkData: DeepLinkData | null;
+}

package/src/models/utm-parameters.ts

@@ -0,0 +1,7 @@
+export interface UTMParameters {
+  source?: string;
+  medium?: string;
+  campaign?: string;
+  term?: string;
+  content?: string;
+}