@sendoracloud/sdk-react-native 0.15.1 → 0.16.1

package/dist/index.js

@@ -802,44 +802,293 @@ function decodeJwtPayload(token) {
 }
 
 // src/links.ts
+var LinkError = class extends Error {
+  constructor(code, message, statusCode = 0, details) {
+    super(message);
+    this.name = "LinkError";
+    this.code = code;
+    this.statusCode = statusCode;
+    this.details = details;
+  }
+};
+function mapToLinkError(status, body, fallback) {
+  const code = body?.error?.code ?? void 0;
+  const msg = body?.error?.message ?? fallback;
+  if (status === 0) return new LinkError("NETWORK", msg || "Network unavailable", 0);
+  if (status === 401) return new LinkError("UNAUTHORIZED", msg, 401);
+  if (status === 403) {
+    return new LinkError("UNAUTHORIZED", msg, 403);
+  }
+  if (status === 404) return new LinkError("NOT_FOUND", msg, 404);
+  if (status === 410) return new LinkError("EXPIRED", msg, 410);
+  if (status === 429) return new LinkError("RATE_LIMITED", msg, 429, body?.error?.details);
+  if (status === 412) return new LinkError("INVALID_INPUT", msg, 412);
+  if (status === 422) {
+    if (/iOS bundle|Android package/i.test(msg)) return new LinkError("BUNDLE_MISMATCH", msg, 422);
+    if (/2KB|10KB|linkData/i.test(msg)) return new LinkError("DATA_TOO_LARGE", msg, 422);
+    if (/fallbackUrl/i.test(msg) && /apps/i.test(msg)) return new LinkError("FALLBACK_REQUIRED", msg, 422);
+    return new LinkError("INVALID_INPUT", msg, 422);
+  }
+  if (status === 402 || code === "ENTITLEMENT_ERROR" || /plan limit/i.test(msg)) {
+    return new LinkError("PLAN_LIMIT", msg, status);
+  }
+  if (status >= 500) return new LinkError("SERVER", msg || "Server error", status);
+  return new LinkError("UNKNOWN", msg || fallback, status);
+}
 async function unwrap(res, ctx) {
-  if (!res) throw new Error(`[sendoracloud] ${ctx}: network error`);
+  if (!res) throw new LinkError("NETWORK", `${ctx}: network error`);
   if (!res.ok) {
-    let msg = `HTTP ${res.status}`;
+    let body = null;
     try {
-      const parsed2 = await res.clone().json();
-      if (parsed2.error?.code || parsed2.error?.message) {
-        msg = `${parsed2.error.code ?? ""}${parsed2.error.code && parsed2.error.message ? ": " : ""}${parsed2.error.message ?? ""}`;
-      }
+      body = await res.clone().json();
     } catch {
     }
-    throw new Error(`[sendoracloud] ${ctx}: ${msg}`);
+    throw mapToLinkError(res.status, body, `${ctx}: HTTP ${res.status}`);
   }
   const parsed = await res.json();
   return parsed.data ?? null;
 }
 var SHORTCODE_RE = /^[a-z0-9-]{3,20}$/;
-function extractShortcodeFromUrl(url) {
+var RESERVED_TAILS = /* @__PURE__ */ new Set(["link"]);
+function extractShortcodeFromUrl(url, linkDomain) {
   try {
     const u = new URL(url);
+    if (linkDomain) {
+      const wantHost = linkDomain.toLowerCase();
+      const gotHost = u.hostname.toLowerCase();
+      if (gotHost !== wantHost && !gotHost.endsWith(`.${wantHost}`)) return null;
+    }
     const segs = u.pathname.split("/").filter(Boolean);
     if (segs.length === 0) return null;
-    const tail = segs[segs.length - 1];
+    let tail = segs[segs.length - 1];
+    if (segs.length >= 2 && RESERVED_TAILS.has(segs[0]) && SHORTCODE_RE.test(tail)) {
+      return tail;
+    }
     return SHORTCODE_RE.test(tail) ? tail : null;
   } catch {
     return null;
   }
 }
+function dynRequire(id) {
+  const dyn = globalThis.require;
+  if (typeof dyn !== "function") return null;
+  try {
+    return dyn(id);
+  } catch {
+    return null;
+  }
+}
+function loadRn() {
+  return dynRequire("react-native");
+}
+function readTimezone() {
+  try {
+    const tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    return tz || "UTC";
+  } catch {
+    return "UTC";
+  }
+}
+function readLocale() {
+  const loc = dynRequire("expo-localization");
+  if (loc) {
+    const tag = loc.getLocales?.()[0]?.languageTag || loc.locale;
+    if (tag) return tag;
+  }
+  const rn = loadRn();
+  if (rn) {
+    const nm = rn.NativeModules;
+    const ios = nm.SettingsManager;
+    if (ios) {
+      const settings = ios.settings;
+      if (settings?.AppleLocale) return settings.AppleLocale;
+      if (Array.isArray(settings?.AppleLanguages) && settings.AppleLanguages[0]) return settings.AppleLanguages[0];
+    }
+    const android = nm.I18nManager;
+    if (android?.localeIdentifier) return android.localeIdentifier;
+  }
+  return "en-US";
+}
+async function sha256Hex(input) {
+  const g = globalThis;
+  if (g.crypto?.subtle?.digest) {
+    const enc = new TextEncoder().encode(input);
+    const buf = await g.crypto.subtle.digest("SHA-256", enc);
+    const view = new Uint8Array(buf);
+    return Array.from(view, (b) => b.toString(16).padStart(2, "0")).join("");
+  }
+  const c = dynRequire("expo-crypto");
+  if (c?.digestStringAsync) {
+    const hex = await c.digestStringAsync("SHA-256", input);
+    return hex.toLowerCase();
+  }
+  return sha256HexPureJs(input);
+}
+function sha256HexPureJs(message) {
+  const utf8 = unescape(encodeURIComponent(message));
+  const bytes = new Uint8Array(utf8.length);
+  for (let i = 0; i < utf8.length; i++) bytes[i] = utf8.charCodeAt(i);
+  const bitLen = bytes.length * 8;
+  const padLen = bytes.length + 9 + 63 & ~63;
+  const buf = new Uint8Array(padLen);
+  buf.set(bytes);
+  buf[bytes.length] = 128;
+  const dv = new DataView(buf.buffer);
+  dv.setUint32(padLen - 4, bitLen >>> 0, false);
+  dv.setUint32(padLen - 8, Math.floor(bitLen / 4294967296), false);
+  const K = [
+    1116352408,
+    1899447441,
+    3049323471,
+    3921009573,
+    961987163,
+    1508970993,
+    2453635748,
+    2870763221,
+    3624381080,
+    310598401,
+    607225278,
+    1426881987,
+    1925078388,
+    2162078206,
+    2614888103,
+    3248222580,
+    3835390401,
+    4022224774,
+    264347078,
+    604807628,
+    770255983,
+    1249150122,
+    1555081692,
+    1996064986,
+    2554220882,
+    2821834349,
+    2952996808,
+    3210313671,
+    3336571891,
+    3584528711,
+    113926993,
+    338241895,
+    666307205,
+    773529912,
+    1294757372,
+    1396182291,
+    1695183700,
+    1986661051,
+    2177026350,
+    2456956037,
+    2730485921,
+    2820302411,
+    3259730800,
+    3345764771,
+    3516065817,
+    3600352804,
+    4094571909,
+    275423344,
+    430227734,
+    506948616,
+    659060556,
+    883997877,
+    958139571,
+    1322822218,
+    1537002063,
+    1747873779,
+    1955562222,
+    2024104815,
+    2227730452,
+    2361852424,
+    2428436474,
+    2756734187,
+    3204031479,
+    3329325298
+  ];
+  const H = [1779033703, 3144134277, 1013904242, 2773480762, 1359893119, 2600822924, 528734635, 1541459225];
+  const W = new Uint32Array(64);
+  for (let chunk = 0; chunk < padLen; chunk += 64) {
+    for (let i = 0; i < 16; i++) W[i] = dv.getUint32(chunk + i * 4, false);
+    for (let i = 16; i < 64; i++) {
+      const s0 = ror(W[i - 15], 7) ^ ror(W[i - 15], 18) ^ W[i - 15] >>> 3;
+      const s1 = ror(W[i - 2], 17) ^ ror(W[i - 2], 19) ^ W[i - 2] >>> 10;
+      W[i] = W[i - 16] + s0 + W[i - 7] + s1 >>> 0;
+    }
+    let [a, b, c, d, e, f, g, h] = H;
+    for (let i = 0; i < 64; i++) {
+      const S1 = ror(e, 6) ^ ror(e, 11) ^ ror(e, 25);
+      const ch = e & f ^ ~e & g;
+      const t1 = h + S1 + ch + K[i] + W[i] >>> 0;
+      const S0 = ror(a, 2) ^ ror(a, 13) ^ ror(a, 22);
+      const mj = a & b ^ a & c ^ b & c;
+      const t2 = S0 + mj >>> 0;
+      h = g;
+      g = f;
+      f = e;
+      e = d + t1 >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = t1 + t2 >>> 0;
+    }
+    H[0] = H[0] + a >>> 0;
+    H[1] = H[1] + b >>> 0;
+    H[2] = H[2] + c >>> 0;
+    H[3] = H[3] + d >>> 0;
+    H[4] = H[4] + e >>> 0;
+    H[5] = H[5] + f >>> 0;
+    H[6] = H[6] + g >>> 0;
+    H[7] = H[7] + h >>> 0;
+  }
+  return H.map((x) => x.toString(16).padStart(8, "0")).join("");
+}
+function ror(x, n) {
+  return (x >>> n | x << 32 - n) >>> 0;
+}
+async function computeDeviceFingerprint() {
+  const rn = loadRn();
+  const platform = rn?.Platform.OS ?? "unknown";
+  let screen = "0x0";
+  if (rn) {
+    try {
+      const d = rn.Dimensions.get("window");
+      screen = `${Math.round(d.width)}x${Math.round(d.height)}`;
+    } catch {
+    }
+  }
+  const tz = readTimezone();
+  const locale = readLocale();
+  return sha256Hex(`${platform}|${screen}|${tz}|${locale}`);
+}
+async function getPlayInstallReferrer() {
+  const rn = loadRn();
+  if (!rn || rn.Platform.OS !== "android") return null;
+  const mod = dynRequire("react-native-play-install-referrer");
+  const cli = mod?.PlayInstallReferrer;
+  if (!cli?.getInstallReferrerInfo) return null;
+  return await new Promise((resolve) => {
+    cli.getInstallReferrerInfo((err, info) => {
+      if (err) {
+        resolve(null);
+        return;
+      }
+      resolve(info?.installReferrer ?? null);
+    });
+  });
+}
+var PREWARM_TTL_MS = 5 * 6e4;
+var PREWARM_MAX = 50;
 var Links = class {
   constructor(deps) {
     this.deps = deps;
     this.listeners = [];
+    this.prewarmCache = /* @__PURE__ */ new Map();
+    this.linkingSub = null;
   }
-  /** Register a callback for warm + deferred deep-link opens. Returns unsubscribe fn. */
+  /** Register a callback for warm + deferred deep-link opens. Returns
+   *  unsubscribe fn. Generic `T` lets callers type `linkData` per-app. */
   onLinkOpened(handler) {
-    this.listeners.push(handler);
+    const widened = handler;
+    this.listeners.push(widened);
     return () => {
-      const idx = this.listeners.indexOf(handler);
+      const idx = this.listeners.indexOf(widened);
       if (idx >= 0) this.listeners.splice(idx, 1);
     };
   }
@@ -852,11 +1101,58 @@ var Links = class {
       }
     }
   }
-  /** Mint a new short link. Returns the share URL + shortcode. */
-  async create(input) {
-    if (!input.title) throw new Error("[sendoracloud] links.create: title is required");
-    if (!input.fallbackUrl) throw new Error("[sendoracloud] links.create: fallbackUrl is required");
-    const body = { title: input.title, fallbackUrl: input.fallbackUrl };
+  /* ------------------------ create + prewarm ------------------------- */
+  /** Stable cache key. Customer can override per call with `opts.key`. */
+  cacheKey(input, override) {
+    if (override) return `k:${override}`;
+    const sorted = {};
+    const flat = input;
+    for (const k of Object.keys(flat).sort()) sorted[k] = flat[k];
+    return `s:${JSON.stringify(sorted)}`;
+  }
+  evictExpired() {
+    const now = Date.now();
+    for (const [k, v] of this.prewarmCache) {
+      if (now - v.ts > PREWARM_TTL_MS) this.prewarmCache.delete(k);
+    }
+    while (this.prewarmCache.size > PREWARM_MAX) {
+      const first = this.prewarmCache.keys().next().value;
+      if (first === void 0) break;
+      this.prewarmCache.delete(first);
+    }
+  }
+  /**
+   * Background-mint a link + cache the promise so a subsequent `create()`
+   * with the same input (or matching `key`) returns instantly.
+   *
+   * Fire-and-forget. Errors are swallowed; the matching `create()` call
+   * will surface them on demand instead.
+   */
+  prewarm(input, opts) {
+    this.evictExpired();
+    const key = this.cacheKey(input, opts?.key);
+    if (this.prewarmCache.has(key)) return;
+    const promise = this.doCreate(input).catch((err) => {
+      this.prewarmCache.delete(key);
+      throw err;
+    });
+    this.prewarmCache.set(key, { promise, ts: Date.now() });
+  }
+  /** Mint a new short link. Uses prewarm cache when the input matches. */
+  async create(input, opts) {
+    if (!input.title) throw new LinkError("INVALID_INPUT", "links.create: title is required");
+    this.evictExpired();
+    const key = this.cacheKey(input, opts?.key);
+    const cached = this.prewarmCache.get(key);
+    if (cached) {
+      this.prewarmCache.delete(key);
+      return cached.promise;
+    }
+    return this.doCreate(input);
+  }
+  async doCreate(input) {
+    const body = { title: input.title };
+    if (input.fallbackUrl) body.fallbackUrl = input.fallbackUrl;
     if (input.iosDeepLinkPath) body.iosDeepLinkPath = input.iosDeepLinkPath;
     if (input.androidDeepLinkPath) body.androidDeepLinkPath = input.androidDeepLinkPath;
     if (input.linkData) body.linkData = input.linkData;
@@ -869,8 +1165,9 @@ var Links = class {
     if (input.channel) body.channel = input.channel;
     if (input.tags) body.tags = input.tags;
     if (input.expiresAt) body.expiresAt = input.expiresAt;
-    const ios = input.iosBundleId ?? this.deps.iosBundleId;
-    const android = input.androidPackageName ?? this.deps.androidPackageName;
+    const rnPlatform = loadRn()?.Platform.OS;
+    const ios = input.iosBundleId ?? (rnPlatform === "ios" ? this.deps.iosBundleId : void 0);
+    const android = input.androidPackageName ?? (rnPlatform === "android" ? this.deps.androidPackageName : void 0);
     if (ios) body.iosBundleId = ios;
     if (android) body.androidPackageName = android;
     const res = await post(
@@ -880,17 +1177,18 @@ var Links = class {
     );
     const data = await unwrap(res, "links.create");
     if (!data?.shortcode) {
-      throw new Error("[sendoracloud] links.create returned no shortcode");
+      throw new LinkError("UNKNOWN", "links.create returned no shortcode");
     }
     return data;
   }
+  /* -------------------- warm + deferred resolve ---------------------- */
   /**
    * Warm-path: app received a universal/app-link delivery. Resolves the
    * shortcode against the backend and fires `onLinkOpened`. No-op (and
    * returns false) when the URL isn't a Sendora link.
    */
   async handleUniversalLink(url) {
-    const shortcode = extractShortcodeFromUrl(url);
+    const shortcode = extractShortcodeFromUrl(url, this.deps.linkDomain);
     if (!shortcode) return false;
     try {
       const res = await getJson(
@@ -909,26 +1207,44 @@ var Links = class {
       return true;
     } catch (err) {
       if (this.deps.debug) console.warn("[sendoracloud] handleUniversalLink failed:", err);
+      if (err instanceof LinkError) throw err;
       return false;
     }
   }
   /**
-   * Cold-launch deferred deep link match. Pass the Android Play Install
-   * Referrer string (preferred — 100% accurate) and/or a precomputed
-   * fingerprint hash (iOS — probabilistic).
+   * Cold-launch deferred deep link match. When neither `fingerprintHash` nor
+   * `installReferrer` is supplied, the SDK auto-discovers:
+   *   - Android: probes `react-native-play-install-referrer` (preferred — 100%
+   *     accurate when present).
+   *   - Otherwise: computes the canonical device fingerprint hash.
    *
-   * SDK fires `onLinkOpened` with `isDeferred: true` on success.
-   * Returns the event payload on match, `null` on no match.
+   * Fires `onLinkOpened` with `isDeferred: true` on success.
    */
-  async matchDeferred(input) {
-    if (!input.fingerprintHash && !input.installReferrer) {
-      throw new Error("[sendoracloud] links.matchDeferred: pass fingerprintHash or installReferrer");
+  async matchDeferred(input = {}) {
+    let fingerprintHash = input.fingerprintHash;
+    let installReferrer = input.installReferrer;
+    if (!fingerprintHash && !installReferrer) {
+      installReferrer = await getPlayInstallReferrer() ?? void 0;
+      if (!installReferrer) {
+        try {
+          fingerprintHash = await computeDeviceFingerprint();
+        } catch (err) {
+          if (this.deps.debug) console.warn("[sendoracloud] fingerprint compute failed:", err);
+        }
+      }
+    }
+    if (!fingerprintHash && !installReferrer) {
+      throw new LinkError(
+        "INVALID_INPUT",
+        "links.matchDeferred: install `react-native-play-install-referrer` for Android, or ensure web crypto / expo-crypto is available for iOS fingerprint compute."
+      );
     }
     const body = {};
-    if (input.fingerprintHash) body.fingerprintHash = input.fingerprintHash;
-    if (input.installReferrer) body.installReferrer = input.installReferrer;
-    const ios = input.iosBundleId ?? this.deps.iosBundleId;
-    const android = input.androidPackageName ?? this.deps.androidPackageName;
+    if (fingerprintHash) body.fingerprintHash = fingerprintHash;
+    if (installReferrer) body.installReferrer = installReferrer;
+    const rnPlatform = loadRn()?.Platform.OS;
+    const ios = input.iosBundleId ?? (rnPlatform === "ios" ? this.deps.iosBundleId : void 0);
+    const android = input.androidPackageName ?? (rnPlatform === "android" ? this.deps.androidPackageName : void 0);
     if (ios) body.iosBundleId = ios;
     if (android) body.androidPackageName = android;
     const res = await post(
@@ -948,6 +1264,99 @@ var Links = class {
     this.emit(event);
     return event;
   }
+  /* --------------------------- revoke ------------------------------- */
+  /** Soft-delete a link. Idempotent — repeated calls succeed. */
+  async revoke(shortcode) {
+    if (!SHORTCODE_RE.test(shortcode)) {
+      throw new LinkError("INVALID_INPUT", `links.revoke: '${shortcode}' is not a valid shortcode`);
+    }
+    const res = await post(
+      { apiUrl: this.deps.apiUrl, publicKey: this.deps.publicKey, debug: this.deps.debug },
+      `/api/v1/sdk/links/${encodeURIComponent(shortcode)}/revoke`,
+      {}
+    );
+    const data = await unwrap(res, "links.revoke");
+    if (!data) throw new LinkError("UNKNOWN", "links.revoke returned empty body");
+    return { shortcode: data.shortcode, revoked: true };
+  }
+  /* ---------------------------- stats ------------------------------- */
+  /** Click totals + breakdowns for a link the SDK owns. */
+  async getStats(shortcode) {
+    if (!SHORTCODE_RE.test(shortcode)) {
+      throw new LinkError("INVALID_INPUT", `links.getStats: '${shortcode}' is not a valid shortcode`);
+    }
+    const res = await getJson(
+      { apiUrl: this.deps.apiUrl, publicKey: this.deps.publicKey, debug: this.deps.debug },
+      `/api/v1/sdk/links/${encodeURIComponent(shortcode)}/stats`
+    );
+    const data = await unwrap(res, "links.getStats");
+    if (!data) throw new LinkError("UNKNOWN", "links.getStats returned empty body");
+    return data;
+  }
+  /* ----------------------- Linking-API wiring ----------------------- */
+  /**
+   * One-call replacement for the standard cold + warm URL boilerplate:
+   *
+   *     const detach = await sendora.links.attachLinkingApi({
+   *       onLegacyUrl: (url) => myRouter.handle(url),
+   *     });
+   *     // …later in unmount:
+   *     detach();
+   *
+   * Internally:
+   *   - Reads `Linking.getInitialURL()` once.
+   *   - Subscribes to `Linking.addEventListener('url', …)`.
+   *   - For each URL: checks `extractShortcodeFromUrl(url, linkDomain)`.
+   *     Sendora-shaped → calls `handleUniversalLink`.
+   *     Otherwise → forwards to `onLegacyUrl` (if supplied).
+   *
+   * Idempotent: re-attaching while a subscription is active replaces it.
+   */
+  async attachLinkingApi(opts = {}) {
+    const rn = loadRn();
+    if (!rn) throw new LinkError("UNKNOWN", "react-native Linking is not available in this runtime");
+    const Linking = rn.Linking;
+    if (!Linking) throw new LinkError("UNKNOWN", "react-native Linking module is undefined");
+    if (this.linkingSub) {
+      try {
+        this.linkingSub.remove();
+      } catch {
+      }
+      this.linkingSub = null;
+    }
+    const handle = async (url) => {
+      if (!url) return;
+      const sc = extractShortcodeFromUrl(url, this.deps.linkDomain);
+      if (sc) {
+        try {
+          await this.handleUniversalLink(url);
+        } catch (err) {
+          if (this.deps.debug) console.warn("[sendoracloud] attachLinkingApi resolve failed:", err);
+        }
+      } else if (opts.onLegacyUrl) {
+        try {
+          opts.onLegacyUrl(url);
+        } catch (err) {
+          if (this.deps.debug) console.warn("[sendoracloud] onLegacyUrl handler threw:", err);
+        }
+      }
+    };
+    try {
+      await handle(await Linking.getInitialURL());
+    } catch (err) {
+      if (this.deps.debug) console.warn("[sendoracloud] getInitialURL failed:", err);
+    }
+    this.linkingSub = Linking.addEventListener("url", (ev) => {
+      void handle(ev?.url ?? null);
+    });
+    return () => {
+      try {
+        this.linkingSub?.remove();
+      } catch {
+      }
+      this.linkingSub = null;
+    };
+  }
 };
 
 // src/auto-track.ts
@@ -1033,7 +1442,7 @@ function installAutoTrack(args) {
 }
 
 // src/index.ts
-var SDK_VERSION = "0.15.0";
+var SDK_VERSION = "0.16.1";
 var DEFAULT_API_URL = "https://api.sendoracloud.com";
 var ANON_KEY = "anon_id";
 var USER_ID_KEY = "user_id";
@@ -1177,7 +1586,8 @@ var SendoraSDK = class {
       publicKey: this.config.publicKey,
       debug: this.debug,
       iosBundleId: this.config.iosBundleId,
-      androidPackageName: this.config.androidPackageName
+      androidPackageName: this.config.androidPackageName,
+      linkDomain: this.config.linkDomain
     });
     this.ready = true;
     if (config.autoTrack !== false) {
@@ -1372,8 +1782,11 @@ export {
   Auth,
   AuthError,
   EmailAlreadyTakenError,
+  LinkError,
   Links,
   SendoraCloud,
+  computeDeviceFingerprint,
   index_default as default,
-  extractShortcodeFromUrl
+  extractShortcodeFromUrl,
+  getPlayInstallReferrer
 };

package/examples/links-router.tsx

@@ -0,0 +1,79 @@
+/**
+ * Example: app-root deep-link router (warm + deferred + legacy fallthrough).
+ *
+ * Mount once at app root. Replaces the ~20-line Linking.getInitialURL +
+ * addEventListener + extract-pre-check + handle-or-fallthrough recipe with
+ * a single `attachLinkingApi` call.
+ *
+ * Copy into your app and adjust `routeFromLinkData` for your nav schema.
+ */
+
+import { useEffect } from "react";
+import SendoraCloud from "@sendoracloud/sdk-react-native";
+
+// Discriminated union — every deep link your app accepts.
+type DeepLinkPayload =
+  | { type: "article"; articleId: string; category: "tech" | "design" | "policy"; sharedBy: string }
+  | { type: "profile"; userId: string }
+  | { type: "comment"; articleId: string; commentId: string };
+
+function routeFromLinkData(linkData: DeepLinkPayload): void {
+  switch (linkData.type) {
+    case "article":
+      // navigation.navigate("Article", { id: linkData.articleId });
+      break;
+    case "profile":
+      // navigation.navigate("Profile", { userId: linkData.userId });
+      break;
+    case "comment":
+      // navigation.navigate("Article", { id: linkData.articleId, scrollTo: linkData.commentId });
+      break;
+  }
+}
+
+export function useSendoraLinkRouter(): void {
+  useEffect(() => {
+    const subs: Array<() => void> = [];
+
+    // 1. Subscribe to all opens — warm + deferred — with typed linkData.
+    subs.push(
+      SendoraCloud.links.onLinkOpened<DeepLinkPayload>((event) => {
+        if (event.isDeferred) {
+          // Cold-launch attribution: navigate after the app's initial
+          // splash → home transition completes (or schedule a redirect
+          // via your nav library's `setParams` once a screen is ready).
+        }
+        routeFromLinkData(event.linkData);
+      }),
+    );
+
+    // 2. Wire the Linking API. Sendora-shaped URLs flow into
+    //    handleUniversalLink → onLinkOpened automatically. Anything else
+    //    is forwarded to onLegacyUrl so your existing router still handles
+    //    OAuth callbacks, magic links, etc.
+    let detach: (() => void) | undefined;
+    void SendoraCloud.links
+      .attachLinkingApi({
+        onLegacyUrl: (url) => {
+          // myExistingRouter.handle(url);
+          console.log("non-Sendora URL", url);
+        },
+      })
+      .then((d) => {
+        detach = d;
+      });
+
+    // 3. Cold-launch deferred match — call once on first foregrounded
+    //    launch. SDK auto-picks installReferrer (Android) or
+    //    fingerprintHash (iOS / fallback) — no boilerplate.
+    void SendoraCloud.links.matchDeferred().catch((err) => {
+      // matchDeferred only throws when both probe paths fail.
+      console.log("deferred match probe skipped:", err);
+    });
+
+    return () => {
+      detach?.();
+      subs.forEach((fn) => fn());
+    };
+  }, []);
+}