@tolinku/web-sdk 0.8.1 → 0.8.2

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,5 +1,5 @@
1
1
  // src/types.ts
2
- var SDK_VERSION = "0.8.1";
2
+ var SDK_VERSION = "0.8.2";
3
3
 
4
4
  // src/client.ts
5
5
  var MAX_RETRIES = 3;
@@ -67,26 +67,47 @@ var HttpClient = class {
67
67
  return this.parseJson(res);
68
68
  }
69
69
  /**
70
- * POST to a host other than the configured one, without the API key.
70
+ * One POST, no retries, with a time limit, reporting what came back instead
71
+ * of throwing.
71
72
  *
72
- * A few public endpoints work out which Appspace they belong to from the
73
- * hostname the request arrives on rather than from a key or an id, so a
74
- * question about a link on a customer's own domain has to be asked on that
75
- * domain. No key goes with it: the origin comes from a URL the caller was
76
- * handed, which is not necessarily ours.
73
+ * For questions where asking twice is worse than not getting an answer:
74
+ * resolving a link counts as a click on the server, so a retry would count
75
+ * it again. The caller decides what a reply means, so this hands back the
76
+ * status and the parsed JSON body. It resolves to null when there was no
77
+ * readable reply: a network error, a CORS refusal (which a browser reports
78
+ * as a network error), the time limit, or a body that is not JSON.
79
+ *
80
+ * `url` is absolute. With `authenticated` the SDK's normal headers go along
81
+ * (the API key); without it only Content-Type does, for a request to a host
82
+ * taken from a URL the caller was handed, which is not necessarily ours.
77
83
  */
78
- async postPublicToOrigin(origin, path, body) {
79
- const res = await this.fetchWithRetry(origin.replace(/\/+$/, "") + path, {
80
- method: "POST",
81
- headers: { "Content-Type": "application/json" },
82
- body: body ? JSON.stringify(body) : void 0,
83
- signal: this.signal
84
- });
85
- if (!res.ok) {
86
- const data = await res.json().catch(() => ({ error: res.statusText }));
87
- throw new TolinkuError(data.error || res.statusText, res.status, data.code);
84
+ async postOnce(url, body, options) {
85
+ const controller = new AbortController();
86
+ const outer = this.signal;
87
+ const onAbort = () => controller.abort();
88
+ if (outer.aborted) controller.abort();
89
+ else outer.addEventListener("abort", onAbort, { once: true });
90
+ const timer = setTimeout(() => controller.abort(), options.timeoutMs);
91
+ try {
92
+ const res = await fetch(url, {
93
+ method: "POST",
94
+ headers: options.authenticated ? { ...this.headers(), "Content-Type": "application/json" } : { "Content-Type": "application/json" },
95
+ body: JSON.stringify(body),
96
+ signal: controller.signal
97
+ });
98
+ let data;
99
+ try {
100
+ data = await res.json();
101
+ } catch {
102
+ return null;
103
+ }
104
+ return { status: res.status, data };
105
+ } catch {
106
+ return null;
107
+ } finally {
108
+ clearTimeout(timer);
109
+ outer.removeEventListener("abort", onAbort);
88
110
  }
89
- return this.parseJson(res);
90
111
  }
91
112
  /** GET without API key auth (for public endpoints like banner config) */
92
113
  async getPublic(path, params) {
@@ -677,35 +698,89 @@ var Links = class {
677
698
  /**
678
699
  * What this link means, or null if it means nothing here.
679
700
  *
680
- * The question goes to the link's own host, because that is how Tolinku knows
681
- * which Appspace is being asked about, which also means a link on a domain
682
- * that is not yours simply answers nothing.
701
+ * The question goes to the link's own host first, because that is how Tolinku
702
+ * knows which Appspace is being asked about, which also means a link on a
703
+ * domain that is not yours simply answers nothing there.
704
+ *
705
+ * If that host gives no reply Tolinku would give (on the web, a third-party
706
+ * click-tracking host usually refuses the request outright under CORS),
707
+ * Tolinku's own API is asked once with the whole link. A link in an email
708
+ * usually arrives wrapped in the email platform's click-tracking URL, on a
709
+ * host that has never heard of Tolinku; the API knows how to unwrap those,
710
+ * and the publishable key tells it which Appspace is asking.
711
+ *
712
+ * Each question is asked once, with a short time limit: resolving a link
713
+ * counts a click on the server, so a retry would count it twice.
683
714
  *
684
715
  * Never throws. A link that cannot be resolved, for a bad network or any
685
716
  * other reason, is one to fall back to your own handling for.
686
717
  */
687
718
  async resolve(url) {
688
- if (!url || typeof url !== "string") return null;
689
- let parsed;
690
719
  try {
691
- parsed = new URL(url.trim());
720
+ return await this.resolveLink(url);
692
721
  } catch {
693
722
  return null;
694
723
  }
695
- if (parsed.protocol !== "https:" && parsed.protocol !== "http:") return null;
724
+ }
725
+ async resolveLink(url) {
726
+ if (!url || typeof url !== "string") return null;
727
+ const link = normaliseLink(url);
728
+ if (!link) return null;
729
+ const own = await this.client.postOnce(
730
+ link.origin + "/v1/api/path",
731
+ { path: link.path, url: link.whole },
732
+ { authenticated: false, timeoutMs: RESOLVE_TIMEOUT_MS }
733
+ );
734
+ if (own && own.status === 200 && isAnswer(own.data)) return own.data;
735
+ if (own && isTolinkuReply(own.data)) return null;
736
+ if (!this.shouldAskApi(link.hostname)) return null;
737
+ const api = await this.client.postOnce(
738
+ this.client.baseUrl + "/v1/api/links/resolve",
739
+ { url: link.whole },
740
+ { authenticated: true, timeoutMs: RESOLVE_TIMEOUT_MS }
741
+ );
742
+ if (api && api.status === 200 && isAnswer(api.data)) return api.data;
743
+ return null;
744
+ }
745
+ /**
746
+ * Whether a second question to Tolinku's own API could add anything.
747
+ *
748
+ * Not without a key, since the API would not know which Appspace is asking.
749
+ * Not when the link is already on the API's host either: that host was just
750
+ * asked, and asking again only doubles the wait for the same answer.
751
+ */
752
+ shouldAskApi(hostname) {
753
+ if (!this.client.key) return false;
696
754
  try {
697
- const result = await this.client.postPublicToOrigin(
698
- parsed.origin,
699
- "/v1/api/path",
700
- { path: parsed.pathname }
701
- );
702
- if (!result || !result.route || !isRoutablePath(result.deep_link_path)) return null;
703
- return result;
755
+ return new URL(this.client.baseUrl).hostname.toLowerCase() !== hostname;
704
756
  } catch {
705
- return null;
757
+ return false;
706
758
  }
707
759
  }
708
760
  };
761
+ var RESOLVE_TIMEOUT_MS = 5e3;
762
+ function normaliseLink(input) {
763
+ let parsed;
764
+ try {
765
+ parsed = new URL(input.trim());
766
+ } catch {
767
+ return null;
768
+ }
769
+ if (parsed.protocol !== "https:" && parsed.protocol !== "http:") return null;
770
+ const hostname = parsed.hostname.toLowerCase();
771
+ const port = parsed.port === "" || parsed.port === "443" || parsed.port === "80" ? "" : ":" + parsed.port;
772
+ const origin = "https://" + hostname + port;
773
+ const path = parsed.pathname;
774
+ return { origin, hostname, path, whole: origin + path + parsed.search };
775
+ }
776
+ function isTolinkuReply(data) {
777
+ return typeof data === "object" && data !== null && typeof data.error === "string";
778
+ }
779
+ function isAnswer(data) {
780
+ if (typeof data !== "object" || data === null) return false;
781
+ const result = data;
782
+ return !!result.route && isRoutablePath(result.deep_link_path);
783
+ }
709
784
 
710
785
  // src/url-safety.ts
711
786
  function isSafeUrl(url) {
@@ -861,31 +936,31 @@ var Banners = class {
861
936
  this.currentPosition = "top";
862
937
  }
863
938
  /**
864
- * Tell the server a banner was tapped.
939
+ * Tell the server what happened to a banner: shown, closed, or its call to
940
+ * action tapped. Shown gives the dashboard a tap rate; closed is otherwise
941
+ * known only to this browser's storage.
865
942
  *
866
- * sendBeacon, because the navigation that follows cancels a plain fetch. It
867
- * is queued by the browser and delivered regardless, which is the only way to
868
- * report something that happens as the page is being left.
943
+ * sendBeacon, because the navigation that follows a tap cancels a plain
944
+ * fetch. It is queued by the browser and delivered regardless. The body is a
945
+ * string, so it goes as text/plain: the one content type a browser sends
946
+ * cross-origin without a preflight. The server reads it as JSON either way.
869
947
  *
870
- * Never throws and never awaits: a banner that cannot report a tap must still
871
- * open the link.
948
+ * Never throws and never awaits: a banner that cannot report must still work.
872
949
  */
873
- reportClick(bannerId, target) {
950
+ report(kind, bannerId, extra) {
874
951
  try {
875
- const url = this.client.baseUrl + "/v1/api/banner/click";
876
- const body = JSON.stringify({ banner_id: bannerId, target });
952
+ const url = this.client.baseUrl + "/v1/api/banner/" + kind;
953
+ const page = typeof location !== "undefined" ? location.origin + location.pathname : "";
954
+ const body = JSON.stringify({ banner_id: bannerId, page, ...extra || {} });
877
955
  const nav = navigator;
878
- if (typeof nav.sendBeacon === "function") {
879
- nav.sendBeacon(url, new Blob([body], { type: "application/json" }));
880
- } else {
881
- void fetch(url, {
882
- method: "POST",
883
- headers: { "Content-Type": "application/json" },
884
- body,
885
- keepalive: true
886
- }).catch(() => {
887
- });
888
- }
956
+ if (typeof nav.sendBeacon === "function" && nav.sendBeacon(url, body)) return;
957
+ void fetch(url, {
958
+ method: "POST",
959
+ headers: { "Content-Type": "text/plain" },
960
+ body,
961
+ keepalive: true
962
+ }).catch(() => {
963
+ });
889
964
  } catch {
890
965
  }
891
966
  }
@@ -1094,6 +1169,7 @@ var Banners = class {
1094
1169
  closeBtn.textContent = "\xD7";
1095
1170
  closeBtn.addEventListener("click", () => {
1096
1171
  saveBannerDismissal(banner.id);
1172
+ this.report("dismiss", banner.id);
1097
1173
  this.dismiss();
1098
1174
  });
1099
1175
  inner.appendChild(closeBtn);
@@ -1123,7 +1199,7 @@ var Banners = class {
1123
1199
  cta.href = isSafeUrl(installUrl) ? installUrl : "#";
1124
1200
  cta.textContent = ctaText;
1125
1201
  cta.addEventListener("click", () => {
1126
- this.reportClick(banner.id, cta.href);
1202
+ this.report("click", banner.id, { target: cta.href });
1127
1203
  });
1128
1204
  inner.appendChild(cta);
1129
1205
  container.appendChild(inner);
@@ -1150,6 +1226,7 @@ var Banners = class {
1150
1226
  }
1151
1227
  this.container = container;
1152
1228
  this.styleEl = style;
1229
+ this.report("view", banner.id);
1153
1230
  requestAnimationFrame(() => {
1154
1231
  requestAnimationFrame(() => {
1155
1232
  container.classList.add("tolk-visible");
@@ -1182,12 +1259,33 @@ function findStackedAnchor(position, explicit) {
1182
1259
  }
1183
1260
 
1184
1261
  // src/messages.ts
1262
+ var MAX_REPORTED_URL = 1e3;
1185
1263
  var Messages = class {
1186
1264
  constructor(client) {
1187
1265
  this.client = client;
1188
1266
  this.overlay = null;
1189
1267
  this.styleEl = null;
1190
1268
  this.app = null;
1269
+ this.tapped = false;
1270
+ }
1271
+ /**
1272
+ * Tell the server a message was shown, closed, or had a button tapped, so the dashboard has
1273
+ * numbers per message. A plain-text beacon (no preflight, survives a navigation) carrying the
1274
+ * publishable key in the body, since a beacon can't set headers. Never throws.
1275
+ */
1276
+ report(messageId, kind, url) {
1277
+ if (kind === "view") this.tapped = false;
1278
+ if (kind === "tap") this.tapped = true;
1279
+ if (kind === "dismiss" && this.tapped) return;
1280
+ try {
1281
+ const endpoint = this.client.baseUrl + "/v1/api/messages/" + encodeURIComponent(messageId) + "/event";
1282
+ const body = JSON.stringify(url ? { kind, apiKey: this.client.key, url: url.slice(0, MAX_REPORTED_URL) } : { kind, apiKey: this.client.key });
1283
+ const nav = navigator;
1284
+ if (typeof nav.sendBeacon === "function" && nav.sendBeacon(endpoint, body)) return;
1285
+ void fetch(endpoint, { method: "POST", headers: { "Content-Type": "text/plain" }, body, keepalive: true }).catch(() => {
1286
+ });
1287
+ } catch {
1288
+ }
1191
1289
  }
1192
1290
  /** Fetch messages and show the highest-priority non-dismissed one */
1193
1291
  async show(options = {}, userId) {
@@ -1202,6 +1300,7 @@ var Messages = class {
1202
1300
  const message = candidates[0];
1203
1301
  recordMessageImpression(message.id);
1204
1302
  this.render(message, options);
1303
+ this.report(message.id, "view");
1205
1304
  }
1206
1305
  /** Remove the message overlay */
1207
1306
  dismiss() {
@@ -1252,6 +1351,7 @@ var Messages = class {
1252
1351
  overlay.addEventListener("click", (e) => {
1253
1352
  if (e.target === overlay) {
1254
1353
  saveMessageDismissal(message.id);
1354
+ this.report(message.id, "dismiss");
1255
1355
  options.onDismiss?.(message.id);
1256
1356
  this.dismiss();
1257
1357
  }
@@ -1282,6 +1382,7 @@ var Messages = class {
1282
1382
  closeBtn.textContent = "\xD7";
1283
1383
  closeBtn.addEventListener("click", () => {
1284
1384
  saveMessageDismissal(message.id);
1385
+ this.report(message.id, "dismiss");
1285
1386
  options.onDismiss?.(message.id);
1286
1387
  this.dismiss();
1287
1388
  });
@@ -1500,11 +1601,13 @@ var Messages = class {
1500
1601
  el.addEventListener("click", () => {
1501
1602
  if (action === "close") {
1502
1603
  saveMessageDismissal(context.messageId);
1604
+ this.report(context.messageId, "dismiss");
1503
1605
  context.options.onDismiss?.(context.messageId);
1504
1606
  this.dismiss();
1505
1607
  return;
1506
1608
  }
1507
1609
  if (action && !isNavigableUrl(action)) return;
1610
+ if (action) this.report(context.messageId, "tap", action);
1508
1611
  if (context.options.onButtonPress) {
1509
1612
  context.options.onButtonPress(action, context.messageId);
1510
1613
  } else if (action) {