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