deep-link-expo 1.0.0

package/llms.txt

@@ -0,0 +1,392 @@
+# @linkforty/mobile-sdk-expo
+
+> Expo SDK for LinkForty — an open-source mobile attribution and deep link management platform. Pure JavaScript implementation for Expo apps. Handles deep linking, deferred deep linking (install attribution), in-app event tracking with offline queue, revenue tracking, and link creation. Works with LinkForty Cloud (linkforty.com) or self-hosted Core instances.
+
+## Installation
+
+```bash
+npx expo install @linkforty/mobile-sdk-expo expo-device expo-application expo-localization expo-linking @react-native-async-storage/async-storage
+```
+
+All dependencies are Expo-compatible and use the Expo module system.
+
+## TypeScript Types
+
+```typescript
+interface LinkFortyConfig {
+  /** Base URL of your LinkForty instance (e.g., 'https://go.yourdomain.com') */
+  baseUrl: string;
+  /** API key — only needed if calling createLink() */
+  apiKey?: string;
+  /**
+   * Public workspace token (LinkForty Cloud only). Recommended — required
+   * for organic installs to be attributed to your workspace. Find it in
+   * the dashboard under Workspace Settings → App Token. Format:
+   * `at_<32 hex chars>`. Safe to ship in your app bundle.
+   */
+  appToken?: string;
+  /** Enable debug logging (default: false) */
+  debug?: boolean;
+  /** Attribution window in hours (default: 168 = 7 days, range: 1-2160) */
+  attributionWindowHours?: number;
+}
+
+interface DeepLinkData {
+  shortCode: string;
+  iosUrl?: string;
+  androidUrl?: string;
+  webUrl?: string;
+  utmParameters?: {
+    source?: string;
+    medium?: string;
+    campaign?: string;
+    term?: string;
+    content?: string;
+  };
+  /** Custom key-value parameters set when the link was created */
+  customParameters?: Record<string, string>;
+  /** In-app destination path (e.g., '/product/123') */
+  deepLinkPath?: string;
+  /** Custom URI scheme (e.g., 'myapp') */
+  appScheme?: string;
+  clickedAt?: string;
+  linkId?: string;
+}
+
+interface InstallAttributionResponse {
+  installId: string;
+  attributed: boolean;
+  /** Attribution confidence score (0-100) */
+  confidenceScore: number;
+  /** Matched fingerprint factors (e.g., ['ip', 'user_agent', 'timezone']) */
+  matchedFactors: string[];
+  deepLinkData: DeepLinkData | {};
+}
+
+interface CreateLinkOptions {
+  /** Template ID (UUID) — auto-selected when omitted */
+  templateId?: string;
+  /** Template slug — only needed when templateId is provided */
+  templateSlug?: string;
+  /** Custom parameters embedded in the link */
+  deepLinkParameters?: Record<string, string>;
+  title?: string;
+  description?: string;
+  /** Custom short code (auto-generated if omitted) */
+  customCode?: string;
+  utmParameters?: {
+    source?: string;
+    medium?: string;
+    campaign?: string;
+    term?: string;
+    content?: string;
+  };
+}
+
+interface CreateLinkResult {
+  /** Full shareable URL (e.g., 'https://go.example.com/tmpl/abc123') */
+  url: string;
+  shortCode: string;
+  linkId: string;
+}
+
+/** All SDK errors are this type */
+class LinkFortyError extends Error {
+  code: 'NOT_INITIALIZED' | 'ALREADY_INITIALIZED' | 'INVALID_CONFIGURATION'
+    | 'NETWORK_ERROR' | 'INVALID_RESPONSE' | 'DECODING_ERROR'
+    | 'INVALID_EVENT_DATA' | 'MISSING_API_KEY';
+}
+
+type DeepLinkCallback = (url: string, deepLinkData: DeepLinkData | null) => void;
+type DeferredDeepLinkCallback = (deepLinkData: DeepLinkData | null) => void;
+```
+
+## SDK API
+
+The SDK exports a singleton default export: `LinkFortySDK`.
+
+```typescript
+import LinkFortySDK from '@linkforty/mobile-sdk-expo';
+```
+
+### initialize(config: LinkFortyConfig): Promise\<InstallAttributionResponse\>
+
+Initialize the SDK, report the install, and return attribution data immediately. Must be called before any other method. HTTPS is required for `baseUrl` (except localhost for development).
+
+```typescript
+const attribution = await LinkFortySDK.initialize({
+  baseUrl: 'https://go.yourdomain.com',
+  apiKey: 'lf_live_abc123',         // optional — only for createLink()
+  appToken: 'at_a1b2c3d4...',       // recommended for Cloud — enables organic-install attribution
+  debug: __DEV__,
+  attributionWindowHours: 168,       // 7 days (default)
+});
+
+console.log(attribution.installId);       // UUID
+console.log(attribution.attributed);      // true/false
+console.log(attribution.confidenceScore); // 0-100
+console.log(attribution.matchedFactors);  // ['ip', 'user_agent', ...]
+```
+
+**Property:** `LinkFortySDK.isInitialized: boolean` — check if SDK is initialized.
+
+### onDeepLink(callback: DeepLinkCallback): void
+
+Register a callback for direct deep links — fires when user taps a LinkForty link and the app is already installed. Supports multiple callbacks.
+
+```typescript
+LinkFortySDK.onDeepLink((url, data) => {
+  console.log('Deep link URL:', url);
+  if (data?.customParameters?.route) {
+    router.push(`/${data.customParameters.route}/${data.customParameters.id}`);
+  }
+});
+```
+
+### onDeferredDeepLink(callback: DeferredDeepLinkCallback): void
+
+Register a callback for deferred deep links — fires on first app launch if the install was attributed to a link click.
+
+```typescript
+LinkFortySDK.onDeferredDeepLink((data) => {
+  if (data) {
+    console.log('Attributed install from:', data.shortCode);
+    router.push(`/${data.customParameters?.route}/${data.customParameters?.id}`);
+  }
+});
+```
+
+### handleDeepLink(url: string): void
+
+Manually pass a URL to the SDK for deep link handling. Use when you receive a URL through a channel other than the automatic listener.
+
+### trackEvent(name: string, properties?: Record\<string, unknown\>): Promise\<void\>
+
+Track in-app events. Failed sends are queued offline (max 100 events) and retried automatically on next successful send.
+
+```typescript
+await LinkFortySDK.trackEvent('add_to_cart', {
+  productId: '789',
+  price: 29.99,
+});
+```
+
+### trackRevenue(amount: number, currency: string, properties?: Record\<string, unknown\>): Promise\<void\>
+
+Track revenue events with a dedicated method for clearer analytics.
+
+```typescript
+await LinkFortySDK.trackRevenue(29.99, 'USD', {
+  productId: '789',
+  orderId: 'order_123',
+});
+```
+
+### createLink(options: CreateLinkOptions): Promise\<CreateLinkResult\>
+
+Create a shareable LinkForty link from within the app. Requires `apiKey` in the init config.
+
+```typescript
+const result = await LinkFortySDK.createLink({
+  deepLinkParameters: {
+    route: 'product',
+    productId: '789',
+  },
+  title: 'Check out this product!',
+  utmParameters: {
+    source: 'in_app_share',
+    medium: 'referral',
+  },
+});
+
+console.log(result.url);       // https://go.yourdomain.com/tmpl/abc12345
+console.log(result.shortCode); // abc12345
+console.log(result.linkId);    // uuid
+```
+
+### Offline Event Queue
+
+```typescript
+LinkFortySDK.queuedEventCount;       // number of events waiting to send
+await LinkFortySDK.flushEvents();     // manually flush the queue
+await LinkFortySDK.clearEventQueue(); // clear queue without sending
+```
+
+### Utility Methods
+
+```typescript
+const installId = await LinkFortySDK.getInstallId();
+const installData = await LinkFortySDK.getInstallData();
+const isFirst = await LinkFortySDK.isFirstLaunch();
+
+// Clear all stored data (e.g., on user logout)
+await LinkFortySDK.clearData();
+
+// Reset SDK to uninitialized state (does NOT clear stored data)
+LinkFortySDK.reset();
+```
+
+## Platform Setup (app.json / app.config.js)
+
+```json
+{
+  "expo": {
+    "ios": {
+      "associatedDomains": ["applinks:go.yourdomain.com"]
+    },
+    "android": {
+      "intentFilters": [
+        {
+          "action": "VIEW",
+          "autoVerify": true,
+          "data": [
+            {
+              "scheme": "https",
+              "host": "go.yourdomain.com"
+            }
+          ],
+          "category": ["BROWSABLE", "DEFAULT"]
+        }
+      ]
+    }
+  }
+}
+```
+
+LinkForty automatically serves `/.well-known/apple-app-site-association` (iOS) and `/.well-known/assetlinks.json` (Android) from your domain. No manual file hosting needed.
+
+## Complete Integration Example (Expo Router)
+
+```typescript
+// app/_layout.tsx
+import { useEffect } from 'react';
+import { Stack, useRouter } from 'expo-router';
+import { Share } from 'react-native';
+import LinkFortySDK, { LinkFortyError } from '@linkforty/mobile-sdk-expo';
+
+export default function RootLayout() {
+  const router = useRouter();
+
+  useEffect(() => {
+    async function initLinkForty() {
+      try {
+        const attribution = await LinkFortySDK.initialize({
+          baseUrl: 'https://go.yourdomain.com',
+          apiKey: 'lf_live_abc123',
+          appToken: 'at_a1b2c3d4...',
+          debug: __DEV__,
+        });
+
+        // Handle deferred deep links (first open after install)
+        LinkFortySDK.onDeferredDeepLink((data) => {
+          if (data?.customParameters?.route) {
+            router.push(`/${data.customParameters.route}/${data.customParameters.id}`);
+          }
+        });
+
+        // Handle direct deep links (app already installed)
+        LinkFortySDK.onDeepLink((url, data) => {
+          if (data?.customParameters?.route) {
+            router.push(`/${data.customParameters.route}/${data.customParameters.id}`);
+          }
+        });
+
+        if (attribution.attributed) {
+          console.log('Install attributed! Confidence:', attribution.confidenceScore);
+        }
+      } catch (error) {
+        if (error instanceof LinkFortyError) {
+          console.error('LinkForty error:', error.code, error.message);
+        }
+      }
+    }
+
+    initLinkForty();
+  }, []);
+
+  return (
+    <Stack>
+      <Stack.Screen name="index" />
+      <Stack.Screen name="product/[id]" />
+      <Stack.Screen name="profile/[id]" />
+    </Stack>
+  );
+}
+
+// Share a deep link from anywhere in your app
+export async function shareProduct(productId: string, productName: string) {
+  const result = await LinkFortySDK.createLink({
+    deepLinkParameters: { route: 'product', productId },
+    title: productName,
+    utmParameters: { source: 'in_app_share', medium: 'referral' },
+  });
+
+  await Share.share({
+    message: `Check out ${productName}! ${result.url}`,
+    url: result.url,
+  });
+}
+
+// Track a conversion from anywhere in your app
+export async function trackPurchase(orderId: string, amount: number) {
+  await LinkFortySDK.trackRevenue(amount, 'USD', { orderId });
+}
+```
+
+## Error Handling
+
+All SDK methods throw `LinkFortyError` with a `.code` property:
+
+```typescript
+import LinkFortySDK, { LinkFortyError } from '@linkforty/mobile-sdk-expo';
+
+try {
+  await LinkFortySDK.initialize({ baseUrl: 'https://go.yourdomain.com' });
+} catch (error) {
+  if (error instanceof LinkFortyError) {
+    switch (error.code) {
+      case 'ALREADY_INITIALIZED':
+        // SDK was already initialized — safe to ignore
+        break;
+      case 'INVALID_CONFIGURATION':
+        console.error('Check your baseUrl:', error.message);
+        break;
+      case 'NETWORK_ERROR':
+        console.error('Could not reach server:', error.message);
+        break;
+      default:
+        console.error('LinkForty error:', error.code, error.message);
+    }
+  }
+}
+```
+
+Error codes: `NOT_INITIALIZED`, `ALREADY_INITIALIZED`, `INVALID_CONFIGURATION`, `NETWORK_ERROR`, `INVALID_RESPONSE`, `DECODING_ERROR`, `INVALID_EVENT_DATA`, `MISSING_API_KEY`.
+
+## Testing Deep Links
+
+```bash
+# iOS Simulator
+xcrun simctl openurl booted "https://go.yourdomain.com/abc123"
+
+# Android Emulator
+adb shell am start -a android.intent.action.VIEW -d "https://go.yourdomain.com/abc123"
+
+# Expo CLI
+npx uri-scheme open "https://go.yourdomain.com/abc123" --ios
+npx uri-scheme open "https://go.yourdomain.com/abc123" --android
+```
+
+## Self-Hosted vs Cloud
+
+The only change is the `baseUrl`:
+
+```typescript
+// Cloud (managed SaaS)
+await LinkFortySDK.initialize({ baseUrl: 'https://go.linkforty.com' });
+
+// Self-hosted (@linkforty/core)
+await LinkFortySDK.initialize({ baseUrl: 'https://links.yourdomain.com' });
+```
+
+All SDK methods work identically with both.

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "deep-link-expo",
+  "version": "1.0.0",
+  "description": "Expo SDK for self-hosted deferred deep linking, attribution, and smart link routing.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "node scripts/gen-version.mjs && tsc",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "keywords": [
+    "deep-linking",
+    "deferred-deep-linking",
+    "mobile-attribution",
+    "expo",
+    "react-native",
+    "universal-links",
+    "app-links",
+    "self-hosted",
+    "open-source"
+  ],
+  "author": "Parth24072001",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Parth24072001/deep-link.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/Parth24072001/deep-link/issues"
+  },
+  "homepage": "https://github.com/Parth24072001/deep-link#readme",
+  "engines": {
+    "node": ">=20.0.0",
+    "npm": ">=10.0.0"
+  },
+  "peerDependencies": {
+    "@react-navigation/native": ">=6.0.0",
+    "expo": ">=51.0.0",
+    "react": ">=18.0.0",
+    "react-native": ">=0.74.0"
+  },
+  "peerDependenciesMeta": {
+    "@react-navigation/native": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@react-native-async-storage/async-storage": "^2.1.0",
+    "expo-application": "~6.0.0",
+    "expo-device": "~7.0.0",
+    "expo-linking": "~7.0.0",
+    "expo-localization": "~16.0.0"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^10.3.5",
+    "@semantic-release/npm": "^13.1.5",
+    "@types/react": "^19.0.0",
+    "@vitest/coverage-v8": "^3.0.0",
+    "conventional-changelog-conventionalcommits": "^7.0.2",
+    "semantic-release": "^25.0.3",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "files": [
+    "dist/**/*",
+    "src/**/*",
+    "llms.txt",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/attribution/attribution-context.ts

@@ -0,0 +1,106 @@
+/**
+ * AttributionContext — last-click attribution + session tracking (SIT-237).
+ *
+ * Mirrors the React Native SDK. Every deep-link open (deferred install OR direct
+ * re-engagement) pins an active attribution context to THAT link; the newest
+ * open supersedes the previous one. Every tracked event is stamped with the
+ * active context + a session id so the backend can credit the link under a
+ * last-click + window model. The active context is persisted so a reopen without
+ * a new click still attributes to the last link; the session is in-memory (a cold
+ * start is a new session).
+ *
+ * Uses AsyncStorage directly (not StorageManager) to stay self-contained.
+ */
+
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { STORAGE_KEYS } from '../storage/storage-keys';
+import type { ActiveAttribution, AttributionStamp } from '../models/attribution';
+import { logger } from '../logger';
+
+/**
+ * RFC4122-v4-style id for session grouping. Not a security token — `Math.random`
+ * is sufficient and avoids a native crypto dependency.
+ */
+function generateSessionId(): string {
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    const v = c === 'x' ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+}
+
+export class AttributionContext {
+  private active: ActiveAttribution | null = null;
+  private sessionId: string;
+  private loaded = false;
+
+  constructor() {
+    // Construction == cold start == a new session.
+    this.sessionId = generateSessionId();
+  }
+
+  /** Restore the persisted active context. Idempotent; never throws. */
+  async load(): Promise<void> {
+    if (this.loaded) return;
+    try {
+      const raw = await AsyncStorage.getItem(STORAGE_KEYS.ATTRIBUTION);
+      if (raw) {
+        this.active = JSON.parse(raw) as ActiveAttribution;
+      }
+    } catch (e) {
+      logger.warn('Failed to load attribution context:', e);
+    }
+    this.loaded = true;
+  }
+
+  /**
+   * Record a deep-link open. Newest open supersedes (last-click) and starts a new
+   * session. No-op when no `linkId` is known (organic open).
+   */
+  async recordDeepLinkOpen(linkId?: string | null, clickId?: string | null): Promise<void> {
+    if (!linkId) return;
+
+    this.active = {
+      linkId,
+      clickId: clickId ?? undefined,
+      openedAt: new Date().toISOString(),
+    };
+    this.sessionId = generateSessionId();
+
+    try {
+      await AsyncStorage.setItem(STORAGE_KEYS.ATTRIBUTION, JSON.stringify(this.active));
+    } catch (e) {
+      logger.warn('Failed to persist attribution context:', e);
+    }
+    logger.log('Attribution context set:', this.active, 'session:', this.sessionId);
+  }
+
+  /** Fields to merge into every event payload. */
+  getStamp(): AttributionStamp {
+    return {
+      attributedLinkId: this.active?.linkId,
+      attributedClickId: this.active?.clickId,
+      linkOpenedAt: this.active?.openedAt,
+      sessionId: this.sessionId,
+    };
+  }
+
+  getSessionId(): string {
+    return this.sessionId;
+  }
+
+  getActive(): ActiveAttribution | null {
+    return this.active;
+  }
+
+  /** Clear the persisted context and start a fresh session. */
+  async clear(): Promise<void> {
+    this.active = null;
+    this.sessionId = generateSessionId();
+    try {
+      await AsyncStorage.removeItem(STORAGE_KEYS.ATTRIBUTION);
+    } catch (e) {
+      logger.warn('Failed to clear attribution context:', e);
+    }
+  }
+}

package/src/attribution/attribution-manager.ts

@@ -0,0 +1,126 @@
+import type { FingerprintCollectorProtocol } from '../fingerprint/fingerprint-collector';
+import type { NetworkManagerProtocol } from '../network/network-manager';
+import type { StorageManagerProtocol } from '../storage/storage-manager';
+import type { InstallAttributionResponse } from '../models/install-response';
+import type { DeepLinkData } from '../models/deep-link-data';
+import { logger } from '../logger';
+import { SDK_NAME, SDK_VERSION } from '../version';
+
+export class AttributionManager {
+  private readonly network: NetworkManagerProtocol;
+  private readonly storage: StorageManagerProtocol;
+  private readonly fingerprint: FingerprintCollectorProtocol;
+
+  constructor(
+    network: NetworkManagerProtocol,
+    storage: StorageManagerProtocol,
+    fingerprint: FingerprintCollectorProtocol,
+  ) {
+    this.network = network;
+    this.storage = storage;
+    this.fingerprint = fingerprint;
+  }
+
+  async reportInstall(
+    attributionWindowHours: number,
+    deviceId?: string,
+    appToken?: string,
+  ): Promise<InstallAttributionResponse> {
+    const isFirst = await this.storage.isFirstLaunch();
+
+    if (!isFirst) {
+      return this.buildCachedResponse();
+    }
+
+    const fp = this.fingerprint.collect(attributionWindowHours, deviceId);
+    logger.log('Reporting install with fingerprint:', fp);
+
+    let response: InstallAttributionResponse;
+    try {
+      response = await this.network.request<InstallAttributionResponse>(
+        '/api/sdk/v1/install',
+        {
+          method: 'POST',
+          // appToken (when provided) lets Cloud scope organic installs
+          // to the right workspace. Omitted from the body when undefined.
+          // sdkName/sdkVersion (SIT-235) identify the SDK for health diagnostics.
+          body: JSON.stringify({
+            ...fp,
+            ...(appToken ? { appToken } : {}),
+            sdkName: SDK_NAME,
+            sdkVersion: SDK_VERSION,
+          }),
+        },
+      );
+    } catch (e) {
+      logger.error('Failed to report install:', e);
+      // Treat as organic on failure
+      await this.storage.setHasLaunched();
+      return {
+        installId: '',
+        attributed: false,
+        confidenceScore: 0,
+        matchedFactors: [],
+        deepLinkData: null,
+      };
+    }
+
+    logger.log('Install response:', response);
+
+    // Cache install ID
+    if (response.installId) {
+      await this.storage.saveInstallId(response.installId);
+    }
+
+    // Cache deep link data if attributed
+    if (response.attributed && response.deepLinkData) {
+      // Normalize deepLinkParameters -> customParameters
+      const deepLinkData: DeepLinkData = {
+        ...response.deepLinkData,
+        customParameters:
+          (response.deepLinkData as DeepLinkData & { deepLinkParameters?: Record<string, string> })
+            .deepLinkParameters ?? response.deepLinkData.customParameters,
+      };
+      await this.storage.saveInstallData(deepLinkData);
+      logger.log('Install attributed with confidence:', response.confidenceScore);
+
+      // Return with normalized data
+      response = { ...response, deepLinkData };
+    } else {
+      logger.log('Organic install (no attribution)');
+    }
+
+    await this.storage.setHasLaunched();
+    return response;
+  }
+
+  async getInstallId(): Promise<string | null> {
+    return this.storage.getInstallId();
+  }
+
+  async getInstallData(): Promise<DeepLinkData | null> {
+    return this.storage.getInstallData();
+  }
+
+  async isFirstLaunch(): Promise<boolean> {
+    return this.storage.isFirstLaunch();
+  }
+
+  async clearData(): Promise<void> {
+    await this.storage.clearAll();
+    logger.log('Attribution data cleared');
+  }
+
+  private async buildCachedResponse(): Promise<InstallAttributionResponse> {
+    const installId = await this.storage.getInstallId();
+    const deepLinkData = await this.storage.getInstallData();
+
+    return {
+      installId: installId ?? '',
+      attributed: deepLinkData !== null,
+      confidenceScore: deepLinkData ? 100 : 0,
+      matchedFactors: [],
+      deepLinkData,
+    };
+  }
+}