@tolinku/web-sdk 0.3.0 → 0.4.0

package/dist/index.d.mts

@@ -393,8 +393,41 @@ declare class Deferred {
     constructor(client: HttpClient);
     /** Claim a deferred deep link by referrer token (from Play Store referrer or clipboard) */
     claimByToken(token: string): Promise<DeferredLink | null>;
+    /**
+     * Recover the link that led here, once.
+     *
+     * There is no Play Install Referrer on the web, so this is signal matching
+     * with the bookkeeping that makes calling it safe. That bookkeeping is the
+     * point: a claim is consumed the first time it succeeds, so an app calling
+     * claimBySignals on every page load asks again after the answer is already
+     * spent, and every one of those asks is recorded as a miss. The match rate on
+     * the dashboard then falls towards zero while the integration is working
+     * correctly, which is a hard thing to diagnose from the outside.
+     *
+     * Call it once on first run. Calling it again is free after the first.
+     *
+     * Named to match the Android, React Native and Flutter SDKs, where the same
+     * call also tries the install referrer before falling back to here.
+     */
+    claimDeferredLink(options: {
+        appspaceId: string;
+        /** Claim again even if an attempt was already recorded. For tests. */
+        force?: boolean;
+    }): Promise<DeferredLink | null>;
+    private alreadyAttempted;
+    private rememberAttempt;
     /** Claim a deferred deep link by device signal matching */
     claimBySignals(options: ClaimBySignalsOptions): Promise<DeferredLink | null>;
+    /**
+     * 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.
+     */
+    private attemptSignals;
 }
 
 declare class Tolinku {

package/dist/index.d.ts

@@ -393,8 +393,41 @@ declare class Deferred {
     constructor(client: HttpClient);
     /** Claim a deferred deep link by referrer token (from Play Store referrer or clipboard) */
     claimByToken(token: string): Promise<DeferredLink | null>;
+    /**
+     * Recover the link that led here, once.
+     *
+     * There is no Play Install Referrer on the web, so this is signal matching
+     * with the bookkeeping that makes calling it safe. That bookkeeping is the
+     * point: a claim is consumed the first time it succeeds, so an app calling
+     * claimBySignals on every page load asks again after the answer is already
+     * spent, and every one of those asks is recorded as a miss. The match rate on
+     * the dashboard then falls towards zero while the integration is working
+     * correctly, which is a hard thing to diagnose from the outside.
+     *
+     * Call it once on first run. Calling it again is free after the first.
+     *
+     * Named to match the Android, React Native and Flutter SDKs, where the same
+     * call also tries the install referrer before falling back to here.
+     */
+    claimDeferredLink(options: {
+        appspaceId: string;
+        /** Claim again even if an attempt was already recorded. For tests. */
+        force?: boolean;
+    }): Promise<DeferredLink | null>;
+    private alreadyAttempted;
+    private rememberAttempt;
     /** Claim a deferred deep link by device signal matching */
     claimBySignals(options: ClaimBySignalsOptions): Promise<DeferredLink | null>;
+    /**
+     * 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.
+     */
+    private attemptSignals;
 }
 
 declare class Tolinku {

package/dist/index.js

@@ -169,7 +169,11 @@ var HttpClient = class {
   }
   headers() {
     return {
-      "X-API-Key": this.apiKey
+      "X-API-Key": this.apiKey,
+      // Browsers default to "Accept: */*", which a server content-negotiating an
+      // error page reads as "HTML is fine". Saying so explicitly keeps an error
+      // parseable instead of arriving as a rendered page.
+      "Accept": "application/json"
     };
   }
 };
@@ -527,6 +531,7 @@ var Referrals = class {
 };
 
 // src/deferred.ts
+var CLAIMED_KEY = "tolinku_deferred_claimed";
 var Deferred = class {
   constructor(client) {
     this.client = client;
@@ -540,10 +545,60 @@ var Deferred = class {
       return null;
     }
   }
+  /**
+   * Recover the link that led here, once.
+   *
+   * There is no Play Install Referrer on the web, so this is signal matching
+   * with the bookkeeping that makes calling it safe. That bookkeeping is the
+   * point: a claim is consumed the first time it succeeds, so an app calling
+   * claimBySignals on every page load asks again after the answer is already
+   * spent, and every one of those asks is recorded as a miss. The match rate on
+   * the dashboard then falls towards zero while the integration is working
+   * correctly, which is a hard thing to diagnose from the outside.
+   *
+   * Call it once on first run. Calling it again is free after the first.
+   *
+   * Named to match the Android, React Native and Flutter SDKs, where the same
+   * call also tries the install referrer before falling back to here.
+   */
+  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 && this.alreadyAttempted()) return null;
+    const { link, settled } = await this.attemptSignals({ appspaceId: options.appspaceId });
+    if (settled) this.rememberAttempt();
+    return link;
+  }
+  alreadyAttempted() {
+    try {
+      return window.localStorage.getItem(CLAIMED_KEY) !== null;
+    } catch {
+      return false;
+    }
+  }
+  rememberAttempt() {
+    try {
+      window.localStorage.setItem(CLAIMED_KEY, (/* @__PURE__ */ new Date()).toISOString());
+    } catch {
+    }
+  }
   /** Claim a deferred deep link by device signal matching */
   async claimBySignals(options) {
+    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 {
-      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: options.timezone || Intl.DateTimeFormat().resolvedOptions().timeZone,
         language: options.language || navigator.language,
@@ -552,10 +607,11 @@ var Deferred = class {
         // Separates devices reporting identical logical dimensions.
         device_pixel_ratio: options.devicePixelRatio || window.devicePixelRatio || 1
       });
+      return { link, settled: true };
     } catch (err) {
       const status = err?.statusCode ?? err?.status;
       if (status === 404) {
-        return null;
+        return { link: null, settled: true };
       }
       if (status === 403) {
         console.warn(
@@ -564,10 +620,10 @@ var Deferred = class {
           "under Settings), not your subdomain or slug.",
           err
         );
-        return null;
+        return { link: null, settled: false };
       }
       console.warn("[Tolinku] Failed to claim deferred link by signals:", err);
-      return null;
+      return { link: null, settled: false };
     }
   }
 };