@tolinku/web-sdk 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.mjs CHANGED
@@ -1,3 +1,6 @@
1
+ // src/types.ts
2
+ var SDK_VERSION = "0.5.0";
3
+
1
4
  // src/client.ts
2
5
  var MAX_RETRIES = 3;
3
6
  var BASE_DELAY_MS = 500;
@@ -167,7 +170,16 @@ var HttpClient = class {
167
170
  }
168
171
  headers() {
169
172
  return {
170
- "X-API-Key": this.apiKey
173
+ "X-API-Key": this.apiKey,
174
+ // Which SDK and version made the call. The other Tolinku SDKs say this in
175
+ // User-Agent, which a browser will not let a script set, so it goes in a
176
+ // header of our own. Without it a web integration is unidentifiable in the
177
+ // field and a version-specific bug cannot be traced to a version.
178
+ "X-Tolinku-SDK": `web/${SDK_VERSION}`,
179
+ // Browsers default to "Accept: */*", which a server content-negotiating an
180
+ // error page reads as "HTML is fine". Saying so explicitly keeps an error
181
+ // parseable instead of arriving as a rendered page.
182
+ "Accept": "application/json"
171
183
  };
172
184
  }
173
185
  };
@@ -525,6 +537,7 @@ var Referrals = class {
525
537
  };
526
538
 
527
539
  // src/deferred.ts
540
+ var CLAIMED_KEY = "tolinku_deferred_claimed";
528
541
  var Deferred = class {
529
542
  constructor(client) {
530
543
  this.client = client;
@@ -538,22 +551,73 @@ var Deferred = class {
538
551
  return null;
539
552
  }
540
553
  }
554
+ /**
555
+ * Recover the link that led here, once.
556
+ *
557
+ * There is no Play Install Referrer on the web, so this is signal matching
558
+ * with the bookkeeping that makes calling it safe. That bookkeeping is the
559
+ * point: a claim is consumed the first time it succeeds, so an app calling
560
+ * claimBySignals on every page load asks again after the answer is already
561
+ * spent, and every one of those asks is recorded as a miss. The match rate on
562
+ * the dashboard then falls towards zero while the integration is working
563
+ * correctly, which is a hard thing to diagnose from the outside.
564
+ *
565
+ * Call it once on first run. Calling it again is free after the first.
566
+ *
567
+ * Named to match the Android, React Native and Flutter SDKs, where the same
568
+ * call also tries the install referrer before falling back to here.
569
+ */
570
+ async claimDeferredLink(options) {
571
+ if (!options.appspaceId || !options.appspaceId.trim()) {
572
+ throw new Error("Tolinku: appspaceId is required and must not be blank for claimDeferredLink.");
573
+ }
574
+ if (!options.force && this.alreadyAttempted()) return null;
575
+ const { link, settled } = await this.attemptSignals({ appspaceId: options.appspaceId });
576
+ if (settled) this.rememberAttempt();
577
+ return link;
578
+ }
579
+ alreadyAttempted() {
580
+ try {
581
+ return window.localStorage.getItem(CLAIMED_KEY) !== null;
582
+ } catch {
583
+ return false;
584
+ }
585
+ }
586
+ rememberAttempt() {
587
+ try {
588
+ window.localStorage.setItem(CLAIMED_KEY, (/* @__PURE__ */ new Date()).toISOString());
589
+ } catch {
590
+ }
591
+ }
541
592
  /** Claim a deferred deep link by device signal matching */
542
593
  async claimBySignals(options) {
594
+ return (await this.attemptSignals(options)).link;
595
+ }
596
+ /**
597
+ * The signal claim, with whether the server actually answered.
598
+ *
599
+ * `settled` separates "nothing is waiting for this device", which no amount
600
+ * of asking will change, from "the request never got there". Both surface as
601
+ * null to callers of claimBySignals, but claimDeferredLink has to tell them
602
+ * apart: recording an attempt that never reached the server would spend an
603
+ * install's one chance at attribution on a dropped connection.
604
+ */
605
+ async attemptSignals(options) {
543
606
  try {
544
- return await this.client.postPublic("/v1/api/deferred/claim-by-signals", {
607
+ const link = await this.client.postPublic("/v1/api/deferred/claim-by-signals", {
545
608
  appspace_id: options.appspaceId,
546
- timezone: options.timezone || Intl.DateTimeFormat().resolvedOptions().timeZone,
547
- language: options.language || navigator.language,
548
- screen_width: options.screenWidth || window.screen.width,
549
- screen_height: options.screenHeight || window.screen.height,
609
+ timezone: override(options.timezone) || Intl.DateTimeFormat().resolvedOptions().timeZone,
610
+ language: override(options.language) || navigator.language,
611
+ screen_width: override(options.screenWidth) || window.screen.width,
612
+ screen_height: override(options.screenHeight) || window.screen.height,
550
613
  // Separates devices reporting identical logical dimensions.
551
- device_pixel_ratio: options.devicePixelRatio || window.devicePixelRatio || 1
614
+ device_pixel_ratio: override(options.devicePixelRatio) || window.devicePixelRatio || 1
552
615
  });
616
+ return { link, settled: true };
553
617
  } catch (err) {
554
618
  const status = err?.statusCode ?? err?.status;
555
619
  if (status === 404) {
556
- return null;
620
+ return { link: null, settled: true };
557
621
  }
558
622
  if (status === 403) {
559
623
  console.warn(
@@ -562,13 +626,37 @@ var Deferred = class {
562
626
  "under Settings), not your subdomain or slug.",
563
627
  err
564
628
  );
565
- return null;
629
+ return { link: null, settled: false };
566
630
  }
567
631
  console.warn("[Tolinku] Failed to claim deferred link by signals:", err);
568
- return null;
632
+ return { link: null, settled: false };
569
633
  }
570
634
  }
571
635
  };
636
+ function override(value) {
637
+ if (typeof value === "string") {
638
+ const trimmed = value.trim();
639
+ return trimmed === "" ? void 0 : trimmed;
640
+ }
641
+ if (typeof value === "number") {
642
+ return Number.isFinite(value) && value > 0 ? value : void 0;
643
+ }
644
+ return void 0;
645
+ }
646
+
647
+ // src/url-safety.ts
648
+ function isSafeUrl(url) {
649
+ if (typeof url !== "string") return false;
650
+ const trimmed = url.trim();
651
+ if (!trimmed) return false;
652
+ try {
653
+ const base = typeof window !== "undefined" ? window.location.href : void 0;
654
+ const parsed = new URL(trimmed, base);
655
+ return parsed.protocol === "http:" || parsed.protocol === "https:";
656
+ } catch {
657
+ return false;
658
+ }
659
+ }
572
660
 
573
661
  // src/storage.ts
574
662
  var BANNER_KEY = "tolinku_banner_dismissed";
@@ -687,14 +775,6 @@ function sanitizeClass(val) {
687
775
  if (!val || typeof val !== "string") return "";
688
776
  return val.replace(/[^a-zA-Z0-9_\-\s]/g, "").slice(0, 100).trim();
689
777
  }
690
- function isSafeUrl(url) {
691
- try {
692
- const parsed = new URL(url, window.location.href);
693
- return parsed.protocol === "http:" || parsed.protocol === "https:";
694
- } catch {
695
- return false;
696
- }
697
- }
698
778
  var Banners = class {
699
779
  constructor(client) {
700
780
  this.client = client;
@@ -1120,7 +1200,7 @@ var Messages = class {
1120
1200
  }
1121
1201
  case "Image": {
1122
1202
  const url = props.url || "";
1123
- if (!isSafeUrl2(url)) return null;
1203
+ if (!isSafeUrl(url)) return null;
1124
1204
  const el = document.createElement("img");
1125
1205
  el.src = url;
1126
1206
  el.alt = props.alt || "";
@@ -1151,7 +1231,7 @@ var Messages = class {
1151
1231
  if (options.onButtonPress) {
1152
1232
  options.onButtonPress(action, messageId);
1153
1233
  } else if (action) {
1154
- if (isSafeUrl2(action)) {
1234
+ if (isSafeUrl(action)) {
1155
1235
  window.location.href = action;
1156
1236
  }
1157
1237
  }
@@ -1196,16 +1276,8 @@ var Messages = class {
1196
1276
  }
1197
1277
  }
1198
1278
  };
1199
- function isSafeUrl2(url) {
1200
- try {
1201
- const parsed = new URL(url, window.location.href);
1202
- return parsed.protocol === "http:" || parsed.protocol === "https:";
1203
- } catch {
1204
- return false;
1205
- }
1206
- }
1207
1279
  function sanitizeCssUrl(url) {
1208
- if (!isSafeUrl2(url)) return null;
1280
+ if (!isSafeUrl(url)) return null;
1209
1281
  return url.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "").replace(/\r/g, "");
1210
1282
  }
1211
1283
  function sanitizeTextAlign(value) {