linktrail-react-native 0.0.1

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "linktrail-react-native",
+  "version": "0.0.1",
+  "description": "React Native SDK for LinkTrail — mobile attribution and deferred deep linking. A New Architecture TurboModule wrapping the native LinkTrail iOS and Android SDKs.",
+  "main": "./lib/module/index.js",
+  "types": "./lib/typescript/src/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./lib/typescript/src/index.d.ts",
+      "default": "./lib/module/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "android",
+    "ios",
+    "*.podspec",
+    "!android/build",
+    "!ios/build",
+    "!**/.*"
+  ],
+  "scripts": {
+    "typecheck": "tsc",
+    "clean": "del-cli lib",
+    "prepare": "bob build"
+  },
+  "keywords": [
+    "react-native",
+    "linktrail",
+    "attribution",
+    "deferred-deep-linking",
+    "deep-linking",
+    "turbomodule",
+    "ios",
+    "android"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/linktrail-io/react-native.git"
+  },
+  "author": "LinkTrail",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/linktrail-io/react-native/issues"
+  },
+  "homepage": "https://github.com/linktrail-io/react-native#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "del-cli": "^6.0.0",
+    "react": "19.1.0",
+    "react-native": "^0.80.0",
+    "react-native-builder-bob": "^0.40.6",
+    "typescript": "^5.8.3"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*"
+  },
+  "codegenConfig": {
+    "name": "LinkTrailSpec",
+    "type": "modules",
+    "jsSrcsDir": "src",
+    "android": {
+      "javaPackageName": "io.linktrail.reactnative"
+    },
+    "ios": {
+      "modulesProvider": {
+        "LinkTrail": "LinkTrailModule"
+      }
+    }
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      "typescript"
+    ]
+  }
+}

package/src/NativeLinkTrail.ts

@@ -0,0 +1,63 @@
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+import type {
+  EventEmitter,
+  UnsafeObject,
+} from 'react-native/Libraries/Types/CodegenTypes';
+
+/**
+ * Codegen spec for the LinkTrail TurboModule.
+ *
+ * Payloads that cross the bridge (options, attribution, deep links, events) are
+ * typed as `UnsafeObject` here because their shapes contain string-keyed maps
+ * (`utm`, `customData`) that codegen cannot express. The public, fully-typed
+ * API lives in `types.ts` / `index.ts` — this module is not exported to users.
+ */
+export interface Spec extends TurboModule {
+  /**
+   * Configures the native SDK. Resolves once configured; rejects with
+   * `missing_api_key` when the key is blank.
+   */
+  configure(apiKey: string, options?: UnsafeObject): Promise<void>;
+
+  /** Sends the install event and resolves with the attribution result. */
+  trackInstall(force: boolean): Promise<UnsafeObject>;
+
+  /** Records a custom post-install event; resolves with the server ack. */
+  trackEvent(name: string, value?: number, currency?: string): Promise<UnsafeObject>;
+
+  /**
+   * Handles an incoming deep-link URL. Resolves with the resolved deep link,
+   * or `null` when the URL is not a LinkTrail link.
+   */
+  handleDeepLink(url: string): Promise<UnsafeObject>;
+
+  /** The most recent attribution result (cached across launches), or null. */
+  getLastAttribution(): Promise<UnsafeObject>;
+
+  /** The most recent resolved deep link from the current session, or null. */
+  getLastDeepLink(): Promise<UnsafeObject>;
+
+  /** iOS: requests ATT authorization. Android: resolves `false`. */
+  requestTrackingAuthorization(): Promise<boolean>;
+
+  /** iOS: registers for SKAdNetwork attribution. Android: no-op. */
+  registerForSKAdAttribution(): void;
+
+  /** iOS: updates the SKAdNetwork conversion value. Android: no-op. */
+  updateConversionValue(value: number, coarseValue?: string): void;
+
+  /** Clears the install flag, cached attribution, queued events, device id. */
+  resetForTesting(): void;
+
+  /** Fires for both deferred and re-engagement links: `{ link, source }`. */
+  readonly onLink: EventEmitter<UnsafeObject>;
+
+  /** Fires with every attribution result (attributed or organic). */
+  readonly onAttribution: EventEmitter<UnsafeObject>;
+
+  /** Fires when a fire-and-forget native operation fails after retries. */
+  readonly onError: EventEmitter<UnsafeObject>;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>('LinkTrail');

package/src/index.ts

@@ -0,0 +1,183 @@
+import { Linking } from 'react-native';
+import NativeLinkTrail from './NativeLinkTrail';
+import type {
+  LinkTrailAttribution,
+  LinkTrailCoarseConversionValue,
+  LinkTrailDeepLink,
+  LinkTrailErrorEvent,
+  LinkTrailEventResult,
+  LinkTrailLinkSource,
+  LinkTrailOptions,
+  LinkTrailSubscription,
+} from './types';
+
+export * from './types';
+
+let linkingSubscription: LinkTrailSubscription | null = null;
+let initialUrlForwarded = false;
+
+/** Forwards RN `Linking` URLs (initial + subsequent) to the native SDK. */
+function startLinkForwarding(): void {
+  if (!initialUrlForwarded) {
+    initialUrlForwarded = true;
+    Linking.getInitialURL()
+      .then((url) => (url ? NativeLinkTrail.handleDeepLink(url) : null))
+      .catch(() => {
+        // Non-LinkTrail URLs and transport failures are reported via onError.
+      });
+  }
+  linkingSubscription ??= Linking.addEventListener('url', ({ url }) => {
+    NativeLinkTrail.handleDeepLink(url).catch(() => {});
+  });
+}
+
+function stopLinkForwarding(): void {
+  linkingSubscription?.remove();
+  linkingSubscription = null;
+}
+
+export const LinkTrail = {
+  /**
+   * Configures the SDK with your workspace API key (`lt_live_…`). Call once at
+   * app launch, before any other LinkTrail API. The install is tracked
+   * automatically unless `options.autoTrackInstall` is `false`.
+   *
+   * Rejects with code `missing_api_key` when the key is blank.
+   */
+  async configure(apiKey: string, options: LinkTrailOptions = {}): Promise<void> {
+    const { autoHandleLinks = true, ...nativeOptions } = options;
+    await NativeLinkTrail.configure(apiKey, nativeOptions);
+    if (autoHandleLinks) {
+      startLinkForwarding();
+    } else {
+      stopLinkForwarding();
+    }
+  },
+
+  /**
+   * Registers a single listener for **both** deferred deep links (first launch
+   * after install) and re-engagement links (app already installed) — `source`
+   * says which. Fires immediately if a deferred link already resolved this
+   * session, so registration order vs. the auto-tracked install doesn't matter.
+   */
+  onLink(
+    listener: (link: LinkTrailDeepLink, source: LinkTrailLinkSource) => void
+  ): LinkTrailSubscription {
+    return NativeLinkTrail.onLink((payload) => {
+      const event = payload as {
+        link: LinkTrailDeepLink;
+        source: LinkTrailLinkSource;
+      };
+      listener(event.link, event.source);
+    });
+  },
+
+  /**
+   * Registers a listener for attribution results (attributed or organic).
+   * Fires immediately with the cached result if one already exists.
+   */
+  onAttribution(
+    listener: (attribution: LinkTrailAttribution) => void
+  ): LinkTrailSubscription {
+    return NativeLinkTrail.onAttribution((payload) => {
+      listener(payload as unknown as LinkTrailAttribution);
+    });
+  },
+
+  /**
+   * Registers a listener invoked when a fire-and-forget native operation
+   * (auto-tracked install, queued event, link open) fails after retries.
+   */
+  onError(
+    listener: (error: LinkTrailErrorEvent) => void
+  ): LinkTrailSubscription {
+    return NativeLinkTrail.onError((payload) => {
+      listener(payload as unknown as LinkTrailErrorEvent);
+    });
+  },
+
+  /**
+   * Sends the install event and resolves attribution. Only needed when
+   * `autoTrackInstall` is `false` (e.g. deferred until consent) — `configure`
+   * does this automatically otherwise. Already-tracked installs resolve from
+   * cache unless `force` is `true`.
+   */
+  trackInstall(force = false): Promise<LinkTrailAttribution> {
+    return NativeLinkTrail.trackInstall(force) as Promise<LinkTrailAttribution>;
+  },
+
+  /**
+   * Records a custom post-install event (purchase, signup, conversion).
+   * On failure the event is queued natively and retried; the returned promise
+   * rejects so you can observe the first failure.
+   */
+  trackEvent(
+    name: string,
+    options: { value?: number; currency?: string } = {}
+  ): Promise<LinkTrailEventResult> {
+    return NativeLinkTrail.trackEvent(
+      name,
+      options.value,
+      options.currency
+    ) as Promise<LinkTrailEventResult>;
+  },
+
+  /**
+   * Forwards an incoming URL to the SDK. Resolves with the resolved deep link,
+   * or `null` when the URL is not a LinkTrail link. You only need this when
+   * `autoHandleLinks` is `false`; routing normally happens via `onLink`.
+   */
+  handleDeepLink(url: string): Promise<LinkTrailDeepLink | null> {
+    return NativeLinkTrail.handleDeepLink(
+      url
+    ) as Promise<LinkTrailDeepLink | null>;
+  },
+
+  /** The most recent attribution result (cached across launches), or `null`. */
+  getLastAttribution(): Promise<LinkTrailAttribution | null> {
+    return NativeLinkTrail.getLastAttribution() as Promise<LinkTrailAttribution | null>;
+  },
+
+  /** The most recent resolved deep link from the current session, or `null`. */
+  getLastDeepLink(): Promise<LinkTrailDeepLink | null> {
+    return NativeLinkTrail.getLastDeepLink() as Promise<LinkTrailDeepLink | null>;
+  },
+
+  /**
+   * iOS: requests App Tracking Transparency authorization (for apps using
+   * SKAdNetwork) and resolves with whether tracking was granted.
+   * Android: resolves `false`.
+   */
+  requestTrackingAuthorization(): Promise<boolean> {
+    return NativeLinkTrail.requestTrackingAuthorization();
+  },
+
+  /**
+   * iOS: registers the app for SKAdNetwork attribution. Call early in the app
+   * lifecycle. Android: no-op.
+   */
+  registerForSKAdAttribution(): void {
+    NativeLinkTrail.registerForSKAdAttribution();
+  },
+
+  /**
+   * iOS: updates the SKAdNetwork conversion value for a post-install event.
+   * Android: no-op.
+   */
+  updateConversionValue(
+    value: number,
+    coarseValue?: LinkTrailCoarseConversionValue
+  ): void {
+    NativeLinkTrail.updateConversionValue(value, coarseValue);
+  },
+
+  /**
+   * Clears the install flag, cached attribution, queued events, and device id,
+   * so the next launch sends a fresh install event. Testing only.
+   */
+  resetForTesting(): void {
+    NativeLinkTrail.resetForTesting();
+  },
+};
+
+export default LinkTrail;

package/src/types.ts

@@ -0,0 +1,107 @@
+/**
+ * The deep-link payload the SDK routes on. Returned by install attribution
+ * (deferred deep linking), re-engagement opens, and link resolution.
+ */
+export interface LinkTrailDeepLink {
+  /** The link's short slug. */
+  slug?: string;
+  /** The canonical public URL of the link. */
+  url?: string;
+  /** The in-app destination path, e.g. `/products/42`. */
+  deepLinkPath?: string;
+  iosUrl?: string;
+  androidUrl?: string;
+  fallbackUrl?: string;
+  campaign?: string;
+  channel?: string;
+  /** UTM parameters carried by the link. */
+  utm?: Record<string, string>;
+  /** Arbitrary key/value payload configured on the link. */
+  customData?: Record<string, string>;
+  /** The destination path to route to, defaulting to `/` when none is set. */
+  path: string;
+  /** Whether this link points at a specific destination (not the app root). */
+  hasRoutableDestination: boolean;
+}
+
+/** Where a delivered deep link came from. */
+export type LinkTrailLinkSource = 'deferred' | 'reengagement';
+
+/** The result of recording an install or open and attributing it. */
+export interface LinkTrailAttribution {
+  /** Server-side event id for this install/open. */
+  id?: number;
+  /** Whether the event was matched to a click. */
+  attributed: boolean;
+  /** The resolved deep link to route on, when attributed. */
+  deepLink?: LinkTrailDeepLink;
+}
+
+/** The acknowledgement returned when recording a custom event. */
+export interface LinkTrailEventResult {
+  id?: number;
+  attributed: boolean;
+}
+
+/** An error reported by the native SDK via the `onError` callback. */
+export interface LinkTrailErrorEvent {
+  /**
+   * Stable machine-readable code: `missing_api_key`, `invalid_api_key`,
+   * `transport`, `server`, `decoding`, `empty_response`, `invalid_url`,
+   * `not_a_linktrail_url`, `not_configured`, or `unknown`.
+   */
+  code: string;
+  /** Human-readable description. */
+  message: string;
+}
+
+/** Severity levels for SDK logging, from most to least verbose. */
+export type LinkTrailLogLevel = 'debug' | 'info' | 'warning' | 'error' | 'none';
+
+/** Retry behavior for transient network failures (timeouts, 5xx, 429). */
+export interface LinkTrailRetryPolicy {
+  /** Total attempts including the first try (1 = no retry). Default 3. */
+  maxAttempts?: number;
+  /** Base delay for exponential backoff, in milliseconds. Default 500. */
+  baseDelayMillis?: number;
+  /** Upper bound on any single backoff delay, in milliseconds. Default 8000. */
+  maxDelayMillis?: number;
+}
+
+/** Configuration for `LinkTrail.configure(...)`. */
+export interface LinkTrailOptions {
+  /** Master switch for native SDK logging. Default `false`. */
+  logEnabled?: boolean;
+  /** Minimum severity to emit when logging is enabled. Default `'info'`. */
+  logLevel?: LinkTrailLogLevel;
+  /** Per-request network timeout, in milliseconds. Default 15000. */
+  requestTimeoutMillis?: number;
+  /** Retry policy applied to transient network failures. */
+  retryPolicy?: LinkTrailRetryPolicy;
+  /**
+   * Link hosts the SDK should treat as its own (e.g. `['go.acme.com']`).
+   * When non-empty, `handleDeepLink` ignores URLs on other hosts. Empty =
+   * handle every parseable link.
+   */
+  linkDomains?: string[];
+  /**
+   * Whether `configure` automatically sends the install event. Default `true`.
+   * Set `false` to defer until consent, then call `trackInstall()` manually.
+   */
+  autoTrackInstall?: boolean;
+  /**
+   * React Native-only convenience: when `true` (the default), the wrapper
+   * listens to the RN `Linking` API and forwards incoming URLs (including the
+   * initial launch URL) to the native SDK, so you don't have to call
+   * `handleDeepLink` yourself. Set `false` to forward URLs manually.
+   */
+  autoHandleLinks?: boolean;
+}
+
+/** SKAdNetwork 4.0+ coarse conversion value bucket (iOS only). */
+export type LinkTrailCoarseConversionValue = 'low' | 'medium' | 'high';
+
+/** A subscription returned by the event-listener APIs. */
+export interface LinkTrailSubscription {
+  remove(): void;
+}