linktrail-react-native 0.0.1

package/ios/LinkTrailModuleImpl.swift

@@ -0,0 +1,238 @@
+import Foundation
+import LinkTrailSDK
+
+/// Swift half of the LinkTrail TurboModule. The ObjC++ module (LinkTrailModule.mm)
+/// cannot call the Swift-only LinkTrailSDK directly, so this class exposes an
+/// @objc surface with dictionary payloads and closure-based promises.
+@objc(LinkTrailModuleImpl)
+public final class LinkTrailModuleImpl: NSObject {
+
+  public typealias Resolve = (Any?) -> Void
+  public typealias Reject = (String, String) -> Void
+
+  /// Event sinks wired up by the ObjC++ module to the codegen emitters.
+  @objc public var onLink: ((NSDictionary) -> Void)?
+  @objc public var onAttribution: ((NSDictionary) -> Void)?
+  @objc public var onError: ((NSDictionary) -> Void)?
+
+  private var sdk: LinkTrailSDK.LinkTrail? { LinkTrailSDK.LinkTrail.shared }
+
+  // MARK: - Configuration
+
+  @objc public func configure(
+    _ apiKey: String,
+    options: NSDictionary?,
+    resolve: @escaping Resolve,
+    reject: @escaping Reject
+  ) {
+    do {
+      let sdk = try LinkTrailSDK.LinkTrail.configure(apiKey: apiKey, options: Self.parseOptions(options))
+      sdk.onAttribution { [weak self] attribution in
+        self?.onAttribution?(Self.attributionDict(attribution))
+      }
+      sdk.onLink { [weak self] link, source in
+        self?.onLink?([
+          "link": Self.deepLinkDict(link),
+          "source": Self.sourceName(source),
+        ])
+      }
+      sdk.onError { [weak self] error in
+        self?.onError?([
+          "code": Self.errorCode(error),
+          "message": error.localizedDescription,
+        ])
+      }
+      resolve(nil)
+    } catch {
+      reject(Self.errorCode(error), error.localizedDescription)
+    }
+  }
+
+  // MARK: - Install / events
+
+  @objc public func trackInstall(
+    _ force: Bool,
+    resolve: @escaping Resolve,
+    reject: @escaping Reject
+  ) {
+    guard let sdk = requireSDK(reject) else { return }
+    Task {
+      do {
+        resolve(Self.attributionDict(try await sdk.trackInstall(force: force)))
+      } catch {
+        reject(Self.errorCode(error), error.localizedDescription)
+      }
+    }
+  }
+
+  @objc public func trackEvent(
+    _ name: String,
+    value: NSNumber?,
+    currency: String?,
+    resolve: @escaping Resolve,
+    reject: @escaping Reject
+  ) {
+    guard let sdk = requireSDK(reject) else { return }
+    Task {
+      do {
+        let result = try await sdk.trackEvent(name: name, value: value?.doubleValue, currency: currency)
+        var dict: [String: Any] = ["attributed": result.attributed]
+        if let id = result.id { dict["id"] = id }
+        resolve(dict)
+      } catch {
+        reject(Self.errorCode(error), error.localizedDescription)
+      }
+    }
+  }
+
+  // MARK: - Deep linking
+
+  @objc public func handleDeepLink(
+    _ urlString: String,
+    resolve: @escaping Resolve,
+    reject: @escaping Reject
+  ) {
+    guard let sdk = requireSDK(reject) else { return }
+    guard let url = URL(string: urlString) else {
+      resolve(nil) // unparseable → not a LinkTrail link
+      return
+    }
+    Task {
+      do {
+        resolve(Self.deepLinkDict(try await sdk.handleDeepLink(url)))
+      } catch LinkTrailError.notALinkTrailURL {
+        resolve(nil)
+      } catch {
+        reject(Self.errorCode(error), error.localizedDescription)
+      }
+    }
+  }
+
+  @objc public func getLastAttribution(_ resolve: @escaping Resolve) {
+    resolve(sdk?.lastAttribution.map(Self.attributionDict))
+  }
+
+  @objc public func getLastDeepLink(_ resolve: @escaping Resolve) {
+    resolve(sdk?.lastDeepLink.map(Self.deepLinkDict))
+  }
+
+  // MARK: - ATT / SKAdNetwork
+
+  @objc public func requestTrackingAuthorization(
+    _ resolve: @escaping Resolve,
+    reject: @escaping Reject
+  ) {
+    guard let sdk = requireSDK(reject) else { return }
+    Task {
+      resolve(await sdk.requestTrackingAuthorization())
+    }
+  }
+
+  @objc public func registerForSKAdAttribution() {
+    sdk?.registerForSKAdAttribution()
+  }
+
+  @objc public func updateConversionValue(_ value: Int, coarseValue: String?) {
+    let coarse = coarseValue.flatMap(LinkTrailCoarseConversionValue.init(rawValue:))
+    sdk?.updateConversionValue(value, coarseValue: coarse)
+  }
+
+  // MARK: - Testing
+
+  @objc public func resetForTesting() {
+    LinkTrailSDK.LinkTrail.resetForTesting()
+  }
+
+  // MARK: - Helpers
+
+  private func requireSDK(_ reject: Reject) -> LinkTrailSDK.LinkTrail? {
+    guard let sdk else {
+      reject("not_configured", "LinkTrail is not configured. Call LinkTrail.configure(apiKey) first.")
+      return nil
+    }
+    return sdk
+  }
+
+  private static func parseOptions(_ dict: NSDictionary?) -> LinkTrailOptions {
+    guard let dict else { return LinkTrailOptions() }
+    let defaults = LinkTrailOptions()
+
+    let defaultRetry = LinkTrailRetryPolicy.default
+    var retryPolicy = defaultRetry
+    if let retry = dict["retryPolicy"] as? NSDictionary {
+      retryPolicy = LinkTrailRetryPolicy(
+        maxAttempts: (retry["maxAttempts"] as? NSNumber)?.intValue ?? defaultRetry.maxAttempts,
+        baseDelay: (retry["baseDelayMillis"] as? NSNumber).map { $0.doubleValue / 1000 } ?? defaultRetry.baseDelay,
+        maxDelay: (retry["maxDelayMillis"] as? NSNumber).map { $0.doubleValue / 1000 } ?? defaultRetry.maxDelay
+      )
+    }
+
+    return LinkTrailOptions(
+      logEnabled: (dict["logEnabled"] as? NSNumber)?.boolValue ?? defaults.logEnabled,
+      logLevel: logLevel(dict["logLevel"] as? String) ?? defaults.logLevel,
+      requestTimeout: (dict["requestTimeoutMillis"] as? NSNumber).map { $0.doubleValue / 1000 } ?? defaults.requestTimeout,
+      retryPolicy: retryPolicy,
+      linkDomains: (dict["linkDomains"] as? [Any])?.compactMap { $0 as? String } ?? defaults.linkDomains,
+      autoTrackInstall: (dict["autoTrackInstall"] as? NSNumber)?.boolValue ?? defaults.autoTrackInstall
+    )
+  }
+
+  private static func logLevel(_ name: String?) -> LinkTrailLogLevel? {
+    switch name {
+    case "debug": return .debug
+    case "info": return .info
+    case "warning": return .warning
+    case "error": return .error
+    case "none": return LinkTrailLogLevel.none
+    default: return nil
+    }
+  }
+
+  private static func sourceName(_ source: LinkTrailLinkSource) -> String {
+    switch source {
+    case .deferred: return "deferred"
+    case .reengagement: return "reengagement"
+    @unknown default: return "reengagement"
+    }
+  }
+
+  private static func attributionDict(_ attribution: LinkTrailAttribution) -> NSDictionary {
+    var dict: [String: Any] = ["attributed": attribution.attributed]
+    if let id = attribution.id { dict["id"] = id }
+    if let deepLink = attribution.deepLink { dict["deepLink"] = deepLinkDict(deepLink) }
+    return dict as NSDictionary
+  }
+
+  private static func deepLinkDict(_ link: LinkTrailDeepLink) -> NSDictionary {
+    var dict: [String: Any] = [
+      "path": link.path,
+      "hasRoutableDestination": link.hasRoutableDestination,
+    ]
+    if let slug = link.slug { dict["slug"] = slug }
+    if let url = link.url { dict["url"] = url }
+    if let deepLinkPath = link.deepLinkPath { dict["deepLinkPath"] = deepLinkPath }
+    if let iosURL = link.iosURL { dict["iosUrl"] = iosURL }
+    if let androidURL = link.androidURL { dict["androidUrl"] = androidURL }
+    if let fallbackURL = link.fallbackURL { dict["fallbackUrl"] = fallbackURL }
+    if let campaign = link.campaign { dict["campaign"] = campaign }
+    if let channel = link.channel { dict["channel"] = channel }
+    if let utm = link.utm { dict["utm"] = utm }
+    if let customData = link.customData { dict["customData"] = customData }
+    return dict as NSDictionary
+  }
+
+  private static func errorCode(_ error: Error) -> String {
+    guard let error = error as? LinkTrailError else { return "unknown" }
+    switch error {
+    case .invalidURL: return "invalid_url"
+    case .transport: return "transport"
+    case .server: return "server"
+    case .decoding: return "decoding"
+    case .emptyResponse: return "empty_response"
+    case .notALinkTrailURL: return "not_a_linktrail_url"
+    case .missingAPIKey: return "missing_api_key"
+    case .invalidAPIKey: return "invalid_api_key"
+    @unknown default: return "unknown"
+    }
+  }
+}

package/lib/module/NativeLinkTrail.js

@@ -0,0 +1,15 @@
+"use strict";
+
+import { TurboModuleRegistry } from 'react-native';
+
+/**
+ * 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 default TurboModuleRegistry.getEnforcing('LinkTrail');
+//# sourceMappingURL=NativeLinkTrail.js.map

package/lib/module/NativeLinkTrail.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["TurboModuleRegistry","getEnforcing"],"sourceRoot":"../../src","sources":["NativeLinkTrail.ts"],"mappings":";;AACA,SAASA,mBAAmB,QAAQ,cAAc;;AAMlD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAgDA,eAAeA,mBAAmB,CAACC,YAAY,CAAO,WAAW,CAAC","ignoreList":[]}

package/lib/module/index.js

@@ -0,0 +1,141 @@
+"use strict";
+
+import { Linking } from 'react-native';
+import NativeLinkTrail from "./NativeLinkTrail.js";
+export * from "./types.js";
+let linkingSubscription = null;
+let initialUrlForwarded = false;
+
+/** Forwards RN `Linking` URLs (initial + subsequent) to the native SDK. */
+function startLinkForwarding() {
+  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() {
+  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, options = {}) {
+    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) {
+    return NativeLinkTrail.onLink(payload => {
+      const event = payload;
+      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) {
+    return NativeLinkTrail.onAttribution(payload => {
+      listener(payload);
+    });
+  },
+  /**
+   * Registers a listener invoked when a fire-and-forget native operation
+   * (auto-tracked install, queued event, link open) fails after retries.
+   */
+  onError(listener) {
+    return NativeLinkTrail.onError(payload => {
+      listener(payload);
+    });
+  },
+  /**
+   * 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) {
+    return NativeLinkTrail.trackInstall(force);
+  },
+  /**
+   * 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, options = {}) {
+    return NativeLinkTrail.trackEvent(name, options.value, options.currency);
+  },
+  /**
+   * 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) {
+    return NativeLinkTrail.handleDeepLink(url);
+  },
+  /** The most recent attribution result (cached across launches), or `null`. */
+  getLastAttribution() {
+    return NativeLinkTrail.getLastAttribution();
+  },
+  /** The most recent resolved deep link from the current session, or `null`. */
+  getLastDeepLink() {
+    return NativeLinkTrail.getLastDeepLink();
+  },
+  /**
+   * iOS: requests App Tracking Transparency authorization (for apps using
+   * SKAdNetwork) and resolves with whether tracking was granted.
+   * Android: resolves `false`.
+   */
+  requestTrackingAuthorization() {
+    return NativeLinkTrail.requestTrackingAuthorization();
+  },
+  /**
+   * iOS: registers the app for SKAdNetwork attribution. Call early in the app
+   * lifecycle. Android: no-op.
+   */
+  registerForSKAdAttribution() {
+    NativeLinkTrail.registerForSKAdAttribution();
+  },
+  /**
+   * iOS: updates the SKAdNetwork conversion value for a post-install event.
+   * Android: no-op.
+   */
+  updateConversionValue(value, coarseValue) {
+    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() {
+    NativeLinkTrail.resetForTesting();
+  }
+};
+export default LinkTrail;
+//# sourceMappingURL=index.js.map

package/lib/module/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["Linking","NativeLinkTrail","linkingSubscription","initialUrlForwarded","startLinkForwarding","getInitialURL","then","url","handleDeepLink","catch","addEventListener","stopLinkForwarding","remove","LinkTrail","configure","apiKey","options","autoHandleLinks","nativeOptions","onLink","listener","payload","event","link","source","onAttribution","onError","trackInstall","force","trackEvent","name","value","currency","getLastAttribution","getLastDeepLink","requestTrackingAuthorization","registerForSKAdAttribution","updateConversionValue","coarseValue","resetForTesting"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/lib/module/types.js

@@ -0,0 +1,2 @@
+"use strict";
+//# sourceMappingURL=types.js.map

package/lib/module/types.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../src","sources":["types.ts"],"mappings":"","ignoreList":[]}

package/lib/typescript/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/lib/typescript/src/NativeLinkTrail.d.ts

@@ -0,0 +1,47 @@
+import type { TurboModule } 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>;
+}
+declare const _default: Spec;
+export default _default;
+//# sourceMappingURL=NativeLinkTrail.d.ts.map

package/lib/typescript/src/NativeLinkTrail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NativeLinkTrail.d.ts","sourceRoot":"","sources":["../../../src/NativeLinkTrail.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EACb,MAAM,2CAA2C,CAAC;AAEnD;;;;;;;GAOG;AACH,MAAM,WAAW,IAAK,SAAQ,WAAW;IACvC;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjE,wEAAwE;IACxE,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAEpD,yEAAyE;IACzE,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAEnF;;;OAGG;IACH,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAEnD,4EAA4E;IAC5E,kBAAkB,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC;IAE5C,4EAA4E;IAC5E,eAAe,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC;IAEzC,kEAAkE;IAClE,4BAA4B,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAEjD,kEAAkE;IAClE,0BAA0B,IAAI,IAAI,CAAC;IAEnC,qEAAqE;IACrE,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEjE,6EAA6E;IAC7E,eAAe,IAAI,IAAI,CAAC;IAExB,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC,YAAY,CAAC,CAAC;IAE5C,mEAAmE;IACnE,QAAQ,CAAC,aAAa,EAAE,YAAY,CAAC,YAAY,CAAC,CAAC;IAEnD,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,YAAY,CAAC,CAAC;CAC9C;;AAED,wBAAmE"}

package/lib/typescript/src/index.d.ts

@@ -0,0 +1,78 @@
+import type { LinkTrailAttribution, LinkTrailCoarseConversionValue, LinkTrailDeepLink, LinkTrailErrorEvent, LinkTrailEventResult, LinkTrailLinkSource, LinkTrailOptions, LinkTrailSubscription } from './types';
+export * from './types';
+export declare 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.
+     */
+    configure(apiKey: string, options?: LinkTrailOptions): Promise<void>;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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?: boolean): 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>;
+    /**
+     * 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>;
+    /** The most recent attribution result (cached across launches), or `null`. */
+    getLastAttribution(): Promise<LinkTrailAttribution | null>;
+    /** The most recent resolved deep link from the current session, or `null`. */
+    getLastDeepLink(): 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>;
+    /**
+     * iOS: registers the app for SKAdNetwork attribution. Call early in the app
+     * lifecycle. Android: no-op.
+     */
+    registerForSKAdAttribution(): void;
+    /**
+     * iOS: updates the SKAdNetwork conversion value for a post-install event.
+     * Android: no-op.
+     */
+    updateConversionValue(value: number, coarseValue?: LinkTrailCoarseConversionValue): void;
+    /**
+     * Clears the install flag, cached attribution, queued events, and device id,
+     * so the next launch sends a fresh install event. Testing only.
+     */
+    resetForTesting(): void;
+};
+export default LinkTrail;
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,oBAAoB,EACpB,8BAA8B,EAC9B,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,EACtB,MAAM,SAAS,CAAC;AAEjB,cAAc,SAAS,CAAC;AAyBxB,eAAO,MAAM,SAAS;IACpB;;;;;;OAMG;sBACqB,MAAM,YAAW,gBAAgB,GAAQ,OAAO,CAAC,IAAI,CAAC;IAU9E;;;;;OAKG;qBAES,CAAC,IAAI,EAAE,iBAAiB,EAAE,MAAM,EAAE,mBAAmB,KAAK,IAAI,GACvE,qBAAqB;IAUxB;;;OAGG;4BAES,CAAC,WAAW,EAAE,oBAAoB,KAAK,IAAI,GACpD,qBAAqB;IAMxB;;;OAGG;sBAES,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,GAC7C,qBAAqB;IAMxB;;;;;OAKG;mCAC0B,OAAO,CAAC,oBAAoB,CAAC;IAI1D;;;;OAIG;qBAEK,MAAM,YACH;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAC7C,OAAO,CAAC,oBAAoB,CAAC;IAQhC;;;;OAIG;wBACiB,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAM9D,8EAA8E;0BACxD,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAI1D,8EAA8E;uBAC3D,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAIpD;;;;OAIG;oCAC6B,OAAO,CAAC,OAAO,CAAC;IAIhD;;;OAGG;kCAC2B,IAAI;IAIlC;;;OAGG;iCAEM,MAAM,gBACC,8BAA8B,GAC3C,IAAI;IAIP;;;OAGG;uBACgB,IAAI;CAGxB,CAAC;AAEF,eAAe,SAAS,CAAC"}

package/lib/typescript/src/types.d.ts

@@ -0,0 +1,99 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/typescript/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,6BAA6B;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,sBAAsB,EAAE,OAAO,CAAC;CACjC;AAED,6CAA6C;AAC7C,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,cAAc,CAAC;AAE9D,qEAAqE;AACrE,MAAM,WAAW,oBAAoB;IACnC,kDAAkD;IAClD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,gDAAgD;IAChD,UAAU,EAAE,OAAO,CAAC;IACpB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CAC9B;AAED,kEAAkE;AAClE,MAAM,WAAW,oBAAoB;IACnC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,sEAAsE;AACtE,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,mEAAmE;AACnE,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;AAEhF,0EAA0E;AAC1E,MAAM,WAAW,oBAAoB;IACnC,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,8EAA8E;IAC9E,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,oDAAoD;AACpD,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,mEAAmE;IACnE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,0DAA0D;IAC1D,WAAW,CAAC,EAAE,oBAAoB,CAAC;IACnC;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,kEAAkE;AAClE,MAAM,MAAM,8BAA8B,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEvE,0DAA0D;AAC1D,MAAM,WAAW,qBAAqB;IACpC,MAAM,IAAI,IAAI,CAAC;CAChB"}