@tolinku/react-native-sdk 0.3.0 → 0.4.0

package/dist/index.mjs

@@ -1,10 +1,10 @@
-import { StyleSheet, AppState, Dimensions, Platform, PixelRatio, Modal, Pressable, TouchableOpacity, Text, ScrollView, View, ImageBackground, Image, Linking } from 'react-native';
+import { StyleSheet, Platform, NativeModules, AppState, Dimensions, PixelRatio, Modal, Pressable, TouchableOpacity, Text, ScrollView, View, ImageBackground, Image, Linking } from 'react-native';
 import AsyncStorage from '@react-native-async-storage/async-storage';
 import { useState, useRef, useMemo, useEffect, useCallback } from 'react';
 import { jsx, Fragment, jsxs } from 'react/jsx-runtime';
 
 // src/types.ts
-var SDK_VERSION = "0.1.0";
+var SDK_VERSION = "0.4.0";
 
 // src/debug.ts
 var _debugEnabled = false;
@@ -624,32 +624,126 @@ var Referrals = class {
     });
   }
 };
+var TOKEN_KEY = "tolk_token";
+function parseInstallReferrer(referrer) {
+  if (!referrer || !referrer.trim()) return null;
+  let decoded = referrer;
+  try {
+    decoded = decodeURIComponent(referrer);
+  } catch {
+  }
+  const pair = decoded.split("&").map((p) => p.trim()).find((p) => p.startsWith(`${TOKEN_KEY}=`));
+  if (!pair) return null;
+  const token = pair.slice(TOKEN_KEY.length + 1);
+  return token.trim() ? token : null;
+}
+function nativeProvider() {
+  const native = NativeModules?.TolinkuInstallReferrer;
+  if (!native || typeof native.getInstallReferrer !== "function") return null;
+  return () => native.getInstallReferrer();
+}
+async function getInstallReferrerToken(provider) {
+  if (Platform.OS !== "android") return null;
+  const source = provider ?? nativeProvider();
+  if (!source) return null;
+  try {
+    const referrer = await source();
+    return parseInstallReferrer(referrer);
+  } catch (err) {
+    debugWarn(`Install referrer lookup failed: ${err.message}`);
+    return null;
+  }
+}
+
+// src/deferred.ts
+var CLAIMED_KEY = "tolinku_deferred_claimed";
 var Deferred = class {
   constructor(client) {
     this.client = client;
   }
   /** Claim a deferred deep link by referrer token (from Play Store referrer or clipboard) */
-  async claimByToken(token) {
+  async claimByToken(token, appspaceId) {
     if (!token || !token.trim()) {
       throw new Error("Tolinku: token is required and must not be blank for claimByToken.");
     }
     try {
-      return await this.client.getPublic("/v1/api/deferred/claim", { token });
+      return await this.client.getPublic("/v1/api/deferred/claim", {
+        token,
+        ...appspaceId ? { appspace_id: appspaceId } : {}
+      });
     } catch (err) {
       debugWarn(`Deferred claimByToken failed: ${err.message}`);
       return null;
     }
   }
+  /**
+   * Recover the link that led to this install, trying both mechanisms.
+   *
+   * The Play Install Referrer is asked first on Android: it names the exact
+   * click, survives for days, and does not care which network the device was
+   * on. Device signals are the fallback, and the only option on iOS, where no
+   * equivalent exists.
+   *
+   * Call once on first launch. Safe to call again, but a claim is consumed the
+   * first time it succeeds, so a second call returns null.
+   *
+   * Reading the referrer needs a native Play Services binding, which this
+   * package deliberately does not bundle. Pass `referrerProvider`, or install a
+   * supported referrer package and it is used automatically. Without either,
+   * Android falls back to signal matching.
+   */
+  async claimDeferredLink(options) {
+    if (!options.appspaceId || !options.appspaceId.trim()) {
+      throw new Error("Tolinku: appspaceId is required and must not be blank for claimDeferredLink.");
+    }
+    if (!options.force && await this.alreadyAttempted()) return null;
+    const token = await getInstallReferrerToken(options.referrerProvider);
+    if (token) {
+      const byToken = await this.claimByToken(token, options.appspaceId).catch(() => null);
+      if (byToken) {
+        await this.rememberAttempt();
+        return byToken;
+      }
+    }
+    const { link, settled } = await this.attemptSignals({ appspaceId: options.appspaceId });
+    if (settled) await this.rememberAttempt();
+    return link;
+  }
+  async alreadyAttempted() {
+    try {
+      return await AsyncStorage.getItem(CLAIMED_KEY) !== null;
+    } catch {
+      return false;
+    }
+  }
+  async rememberAttempt() {
+    try {
+      await AsyncStorage.setItem(CLAIMED_KEY, (/* @__PURE__ */ new Date()).toISOString());
+    } catch {
+    }
+  }
   /** Claim a deferred deep link by device signal matching */
   async claimBySignals(options) {
     if (!options.appspaceId || !options.appspaceId.trim()) {
       throw new Error("Tolinku: appspaceId is required and must not be blank for claimBySignals.");
     }
+    return (await this.attemptSignals(options)).link;
+  }
+  /**
+   * The signal claim, with whether the server actually answered.
+   *
+   * `settled` separates "nothing is waiting for this device", which no amount
+   * of asking will change, from "the request never got there". Both surface as
+   * null to callers of claimBySignals, but claimDeferredLink has to tell them
+   * apart: recording an attempt that never reached the server would spend an
+   * install's one chance at attribution on a dropped connection.
+   */
+  async attemptSignals(options) {
     try {
       const { width, height } = Dimensions.get("screen");
       const resolvedTimezone = options.timezone || Intl.DateTimeFormat().resolvedOptions().timeZone;
       const resolvedLanguage = options.language || (typeof Intl !== "undefined" && typeof Intl.DateTimeFormat === "function" ? Intl.DateTimeFormat().resolvedOptions().locale : void 0) || "en";
-      return await this.client.postPublic("/v1/api/deferred/claim-by-signals", {
+      const link = await this.client.postPublic("/v1/api/deferred/claim-by-signals", {
         appspace_id: options.appspaceId,
         timezone: resolvedTimezone,
         language: resolvedLanguage,
@@ -659,20 +753,21 @@ var Deferred = class {
         device_pixel_ratio: options.devicePixelRatio || PixelRatio.get(),
         os_version: options.osVersion || String(Platform.Version)
       });
+      return { link, settled: true };
     } catch (err) {
       const status = err?.statusCode ?? err?.status;
       if (status === 404) {
         debugWarn("Deferred claimBySignals: no match for this device.");
-        return null;
+        return { link: null, settled: true };
       }
       if (status === 403) {
         console.warn(
           `[Tolinku] claimBySignals failed with HTTP 403. Check that appspaceId is your Appspace ID (copy it from the dashboard under Settings), not your subdomain or slug. ${err.message}`
         );
-        return null;
+        return { link: null, settled: false };
       }
       debugWarn(`Deferred claimBySignals failed: ${err.message}`);
-      return null;
+      return { link: null, settled: false };
     }
   }
 };
@@ -762,6 +857,17 @@ var _Tolinku = class _Tolinku {
    * If init() is called a second time without calling destroy() first,
    * a warning is logged and the existing instance is returned.
    */
+  /**
+   * Configure the SDK.
+   *
+   * The name the Android, iOS and Flutter SDKs use for this. {@link init} does
+   * the same thing and still works; it is what this package shipped and
+   * breaking it would serve nobody. It is meant for deprecation later, once
+   * moving off it is a one-line change rather than a surprise.
+   */
+  static configure(config) {
+    _Tolinku.init(config);
+  }
   static init(config) {
     if (!config.apiKey) throw new Error("Tolinku: apiKey is required");
     if (_Tolinku._initialized) {
@@ -1196,6 +1302,6 @@ function TolinkuMessages({
   );
 }
 
-export { Tolinku, TolinkuError, TolinkuMessages, isSafeUrl };
+export { Tolinku, TolinkuError, TolinkuMessages, getInstallReferrerToken, isSafeUrl, parseInstallReferrer };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map