@tolinku/web-sdk 0.5.0 → 0.6.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/README.md CHANGED
@@ -160,6 +160,29 @@ tolinku.dismissBanner();
160
160
 
161
161
  Banners include an app icon, title, body text, and a call-to-action button. Dismissal state is tracked so banners do not reappear until the configured duration has passed.
162
162
 
163
+ ### Resolving a Link
164
+
165
+ Short links arrive as an opaque code, `/s7k2p9q/4821`. On the open web you will
166
+ rarely see one, since the browser follows it to Tolinku first. Inside a
167
+ Capacitor or Cordova app you will see it every time: the operating system hands
168
+ the web layer the URL that was tapped, and code parsing the path itself has no
169
+ idea what the code stands for, so the link opens the app and nothing happens.
170
+
171
+ `resolve` asks Tolinku, which answers with the route, the token and the
172
+ canonical path. A readable URL comes back unchanged, so you can resolve
173
+ everything rather than guessing which kind you have. It never throws: a link it
174
+ cannot resolve is one to fall back to your own handling for.
175
+
176
+ ```js
177
+ const link = await tolinku.links.resolve(url);
178
+ if (link) {
179
+ // link.deep_link_path -> "/order/4821/receipt"
180
+ // link.token -> "4821"
181
+ // link.route.prefix -> "order/{token}/receipt"
182
+ route(link.deep_link_path);
183
+ }
184
+ ```
185
+
163
186
  ## Configuration Options
164
187
 
165
188
  ```typescript
package/dist/index.d.mts CHANGED
@@ -268,6 +268,26 @@ interface SpendCreditsParams {
268
268
  revenue: number;
269
269
  currency: string;
270
270
  }
271
+ /**
272
+ * What a Tolinku link turned out to mean.
273
+ *
274
+ * The same shape in every SDK, so an app moving between them reads one thing.
275
+ * The Appspace the link belongs to is deliberately not here: the caller already
276
+ * knows which Appspace it is, and nothing about routing a link needs it.
277
+ */
278
+ interface ResolvedLink {
279
+ /** The route that answers this link. */
280
+ route: {
281
+ prefix: string;
282
+ name: string;
283
+ template: string;
284
+ link_type?: string;
285
+ };
286
+ /** The token the link carried, or '' where it carried none. */
287
+ token: string;
288
+ /** The canonical path, with the token wherever the route's prefix puts it. */
289
+ deep_link_path: string;
290
+ }
271
291
 
272
292
  declare class HttpClient {
273
293
  private _baseUrl;
@@ -284,6 +304,16 @@ declare class HttpClient {
284
304
  get key(): string;
285
305
  get<T>(path: string, params?: Record<string, string>): Promise<T>;
286
306
  post<T>(path: string, body?: Record<string, unknown>): Promise<T>;
307
+ /**
308
+ * POST to a host other than the configured one, without the API key.
309
+ *
310
+ * A few public endpoints work out which Appspace they belong to from the
311
+ * hostname the request arrives on rather than from a key or an id, so a
312
+ * question about a link on a customer's own domain has to be asked on that
313
+ * domain. No key goes with it: the origin comes from a URL the caller was
314
+ * handed, which is not necessarily ours.
315
+ */
316
+ postPublicToOrigin<T>(origin: string, path: string, body?: Record<string, unknown>): Promise<T>;
287
317
  /** GET without API key auth (for public endpoints like banner config) */
288
318
  getPublic<T>(path: string, params?: Record<string, string>): Promise<T>;
289
319
  /** POST without API key auth (for public endpoints like deferred claim) */
@@ -430,6 +460,44 @@ declare class Deferred {
430
460
  private attemptSignals;
431
461
  }
432
462
 
463
+ /**
464
+ * Working out what a link actually means.
465
+ *
466
+ * On the open web this rarely comes up: a browser follows a short link to
467
+ * Tolinku, which resolves it and serves the page, so nothing on the page ever
468
+ * sees an unreadable URL.
469
+ *
470
+ * Inside a Capacitor or Cordova app it comes up constantly. There the operating
471
+ * system hands the web layer the URL that was tapped, exactly as written, and
472
+ * the routing happens in JavaScript. A short link arrives as an opaque code:
473
+ *
474
+ * https://links.example.com/s7k2p9q/4821
475
+ *
476
+ * Nothing in that URL says which route it is, and nothing on the device can work
477
+ * it out. Code parsing the path itself sees a first segment it has never heard
478
+ * of and does nothing, so the link opens the app and then appears to fail: no
479
+ * error, no screen, no clue.
480
+ *
481
+ * `resolve` asks Tolinku, which answers with the route, the token and the
482
+ * canonical path. A readable URL comes back unchanged, so everything can be
483
+ * resolved rather than guessing which kind it is.
484
+ */
485
+ declare class Links {
486
+ private client;
487
+ constructor(client: HttpClient);
488
+ /**
489
+ * What this link means, or null if it means nothing here.
490
+ *
491
+ * The question goes to the link's own host, because that is how Tolinku knows
492
+ * which Appspace is being asked about, which also means a link on a domain
493
+ * that is not yours simply answers nothing.
494
+ *
495
+ * Never throws. A link that cannot be resolved, for a bad network or any
496
+ * other reason, is one to fall back to your own handling for.
497
+ */
498
+ resolve(url: string): Promise<ResolvedLink | null>;
499
+ }
500
+
433
501
  declare class Tolinku {
434
502
  private client;
435
503
  /** Analytics: track custom events */
@@ -440,6 +508,13 @@ declare class Tolinku {
440
508
  readonly referrals: Referrals;
441
509
  /** Deferred deep links: claim by token or signals */
442
510
  readonly deferred: Deferred;
511
+ /**
512
+ * Turning a link into the route and token it means.
513
+ *
514
+ * Needed for short links, which arrive as an opaque code. See
515
+ * {@link Links.resolve}.
516
+ */
517
+ readonly links: Links;
443
518
  private banners;
444
519
  private messages;
445
520
  /** The current user ID, used for segment targeting and analytics. */
@@ -470,4 +545,4 @@ declare class Tolinku {
470
545
  destroy(): void;
471
546
  }
472
547
 
473
- export { type AddPaymentInfoParams, type AddToCartParams, type AddToWishlistParams, type BannerConfig, type BannerItem, type BeginCheckoutParams, type ClaimBySignalsOptions, type CompleteReferralOptions, type CompleteReferralResult, type CreateReferralOptions, type CreateReferralResult, type DeferredLink, type EcommerceItem, type LeaderboardEntry, type Message, type MessageComponent, type MessageContent, type MilestoneOptions, type MilestoneResult, type PurchaseParams, type RateParams, type ReferralInfo, type RefundParams, type RemoveFromCartParams, type SearchParams, type ShareParams, type ShowBannerOptions, type ShowMessageOptions, type SpendCreditsParams, Tolinku, type TolinkuConfig, TolinkuError, type TrackProperties, type ViewItemParams };
548
+ export { type AddPaymentInfoParams, type AddToCartParams, type AddToWishlistParams, type BannerConfig, type BannerItem, type BeginCheckoutParams, type ClaimBySignalsOptions, type CompleteReferralOptions, type CompleteReferralResult, type CreateReferralOptions, type CreateReferralResult, type DeferredLink, type EcommerceItem, type LeaderboardEntry, type Message, type MessageComponent, type MessageContent, type MilestoneOptions, type MilestoneResult, type PurchaseParams, type RateParams, type ReferralInfo, type RefundParams, type RemoveFromCartParams, type ResolvedLink, type SearchParams, type ShareParams, type ShowBannerOptions, type ShowMessageOptions, type SpendCreditsParams, Tolinku, type TolinkuConfig, TolinkuError, type TrackProperties, type ViewItemParams };
package/dist/index.d.ts CHANGED
@@ -268,6 +268,26 @@ interface SpendCreditsParams {
268
268
  revenue: number;
269
269
  currency: string;
270
270
  }
271
+ /**
272
+ * What a Tolinku link turned out to mean.
273
+ *
274
+ * The same shape in every SDK, so an app moving between them reads one thing.
275
+ * The Appspace the link belongs to is deliberately not here: the caller already
276
+ * knows which Appspace it is, and nothing about routing a link needs it.
277
+ */
278
+ interface ResolvedLink {
279
+ /** The route that answers this link. */
280
+ route: {
281
+ prefix: string;
282
+ name: string;
283
+ template: string;
284
+ link_type?: string;
285
+ };
286
+ /** The token the link carried, or '' where it carried none. */
287
+ token: string;
288
+ /** The canonical path, with the token wherever the route's prefix puts it. */
289
+ deep_link_path: string;
290
+ }
271
291
 
272
292
  declare class HttpClient {
273
293
  private _baseUrl;
@@ -284,6 +304,16 @@ declare class HttpClient {
284
304
  get key(): string;
285
305
  get<T>(path: string, params?: Record<string, string>): Promise<T>;
286
306
  post<T>(path: string, body?: Record<string, unknown>): Promise<T>;
307
+ /**
308
+ * POST to a host other than the configured one, without the API key.
309
+ *
310
+ * A few public endpoints work out which Appspace they belong to from the
311
+ * hostname the request arrives on rather than from a key or an id, so a
312
+ * question about a link on a customer's own domain has to be asked on that
313
+ * domain. No key goes with it: the origin comes from a URL the caller was
314
+ * handed, which is not necessarily ours.
315
+ */
316
+ postPublicToOrigin<T>(origin: string, path: string, body?: Record<string, unknown>): Promise<T>;
287
317
  /** GET without API key auth (for public endpoints like banner config) */
288
318
  getPublic<T>(path: string, params?: Record<string, string>): Promise<T>;
289
319
  /** POST without API key auth (for public endpoints like deferred claim) */
@@ -430,6 +460,44 @@ declare class Deferred {
430
460
  private attemptSignals;
431
461
  }
432
462
 
463
+ /**
464
+ * Working out what a link actually means.
465
+ *
466
+ * On the open web this rarely comes up: a browser follows a short link to
467
+ * Tolinku, which resolves it and serves the page, so nothing on the page ever
468
+ * sees an unreadable URL.
469
+ *
470
+ * Inside a Capacitor or Cordova app it comes up constantly. There the operating
471
+ * system hands the web layer the URL that was tapped, exactly as written, and
472
+ * the routing happens in JavaScript. A short link arrives as an opaque code:
473
+ *
474
+ * https://links.example.com/s7k2p9q/4821
475
+ *
476
+ * Nothing in that URL says which route it is, and nothing on the device can work
477
+ * it out. Code parsing the path itself sees a first segment it has never heard
478
+ * of and does nothing, so the link opens the app and then appears to fail: no
479
+ * error, no screen, no clue.
480
+ *
481
+ * `resolve` asks Tolinku, which answers with the route, the token and the
482
+ * canonical path. A readable URL comes back unchanged, so everything can be
483
+ * resolved rather than guessing which kind it is.
484
+ */
485
+ declare class Links {
486
+ private client;
487
+ constructor(client: HttpClient);
488
+ /**
489
+ * What this link means, or null if it means nothing here.
490
+ *
491
+ * The question goes to the link's own host, because that is how Tolinku knows
492
+ * which Appspace is being asked about, which also means a link on a domain
493
+ * that is not yours simply answers nothing.
494
+ *
495
+ * Never throws. A link that cannot be resolved, for a bad network or any
496
+ * other reason, is one to fall back to your own handling for.
497
+ */
498
+ resolve(url: string): Promise<ResolvedLink | null>;
499
+ }
500
+
433
501
  declare class Tolinku {
434
502
  private client;
435
503
  /** Analytics: track custom events */
@@ -440,6 +508,13 @@ declare class Tolinku {
440
508
  readonly referrals: Referrals;
441
509
  /** Deferred deep links: claim by token or signals */
442
510
  readonly deferred: Deferred;
511
+ /**
512
+ * Turning a link into the route and token it means.
513
+ *
514
+ * Needed for short links, which arrive as an opaque code. See
515
+ * {@link Links.resolve}.
516
+ */
517
+ readonly links: Links;
443
518
  private banners;
444
519
  private messages;
445
520
  /** The current user ID, used for segment targeting and analytics. */
@@ -470,4 +545,4 @@ declare class Tolinku {
470
545
  destroy(): void;
471
546
  }
472
547
 
473
- export { type AddPaymentInfoParams, type AddToCartParams, type AddToWishlistParams, type BannerConfig, type BannerItem, type BeginCheckoutParams, type ClaimBySignalsOptions, type CompleteReferralOptions, type CompleteReferralResult, type CreateReferralOptions, type CreateReferralResult, type DeferredLink, type EcommerceItem, type LeaderboardEntry, type Message, type MessageComponent, type MessageContent, type MilestoneOptions, type MilestoneResult, type PurchaseParams, type RateParams, type ReferralInfo, type RefundParams, type RemoveFromCartParams, type SearchParams, type ShareParams, type ShowBannerOptions, type ShowMessageOptions, type SpendCreditsParams, Tolinku, type TolinkuConfig, TolinkuError, type TrackProperties, type ViewItemParams };
548
+ export { type AddPaymentInfoParams, type AddToCartParams, type AddToWishlistParams, type BannerConfig, type BannerItem, type BeginCheckoutParams, type ClaimBySignalsOptions, type CompleteReferralOptions, type CompleteReferralResult, type CreateReferralOptions, type CreateReferralResult, type DeferredLink, type EcommerceItem, type LeaderboardEntry, type Message, type MessageComponent, type MessageContent, type MilestoneOptions, type MilestoneResult, type PurchaseParams, type RateParams, type ReferralInfo, type RefundParams, type RemoveFromCartParams, type ResolvedLink, type SearchParams, type ShareParams, type ShowBannerOptions, type ShowMessageOptions, type SpendCreditsParams, Tolinku, type TolinkuConfig, TolinkuError, type TrackProperties, type ViewItemParams };
package/dist/index.js CHANGED
@@ -1,7 +1,7 @@
1
1
  'use strict';
2
2
 
3
3
  // src/types.ts
4
- var SDK_VERSION = "0.5.0";
4
+ var SDK_VERSION = "0.6.0";
5
5
 
6
6
  // src/client.ts
7
7
  var MAX_RETRIES = 3;
@@ -68,6 +68,28 @@ var HttpClient = class {
68
68
  }
69
69
  return this.parseJson(res);
70
70
  }
71
+ /**
72
+ * POST to a host other than the configured one, without the API key.
73
+ *
74
+ * A few public endpoints work out which Appspace they belong to from the
75
+ * hostname the request arrives on rather than from a key or an id, so a
76
+ * question about a link on a customer's own domain has to be asked on that
77
+ * domain. No key goes with it: the origin comes from a URL the caller was
78
+ * handed, which is not necessarily ours.
79
+ */
80
+ async postPublicToOrigin(origin, path, body) {
81
+ const res = await this.fetchWithRetry(origin.replace(/\/+$/, "") + path, {
82
+ method: "POST",
83
+ headers: { "Content-Type": "application/json" },
84
+ body: body ? JSON.stringify(body) : void 0,
85
+ signal: this.signal
86
+ });
87
+ if (!res.ok) {
88
+ const data = await res.json().catch(() => ({ error: res.statusText }));
89
+ throw new TolinkuError(data.error || res.statusText, res.status, data.code);
90
+ }
91
+ return this.parseJson(res);
92
+ }
71
93
  /** GET without API key auth (for public endpoints like banner config) */
72
94
  async getPublic(path, params) {
73
95
  let url = this._baseUrl + path;
@@ -646,6 +668,47 @@ function override(value) {
646
668
  return void 0;
647
669
  }
648
670
 
671
+ // src/links.ts
672
+ function isRoutablePath(path) {
673
+ return typeof path === "string" && path.startsWith("/") && !path.startsWith("//");
674
+ }
675
+ var Links = class {
676
+ constructor(client) {
677
+ this.client = client;
678
+ }
679
+ /**
680
+ * What this link means, or null if it means nothing here.
681
+ *
682
+ * The question goes to the link's own host, because that is how Tolinku knows
683
+ * which Appspace is being asked about, which also means a link on a domain
684
+ * that is not yours simply answers nothing.
685
+ *
686
+ * Never throws. A link that cannot be resolved, for a bad network or any
687
+ * other reason, is one to fall back to your own handling for.
688
+ */
689
+ async resolve(url) {
690
+ if (!url || typeof url !== "string") return null;
691
+ let parsed;
692
+ try {
693
+ parsed = new URL(url.trim());
694
+ } catch {
695
+ return null;
696
+ }
697
+ if (parsed.protocol !== "https:" && parsed.protocol !== "http:") return null;
698
+ try {
699
+ const result = await this.client.postPublicToOrigin(
700
+ parsed.origin,
701
+ "/v1/api/path",
702
+ { path: parsed.pathname }
703
+ );
704
+ if (!result || !result.route || !isRoutablePath(result.deep_link_path)) return null;
705
+ return result;
706
+ } catch {
707
+ return null;
708
+ }
709
+ }
710
+ };
711
+
649
712
  // src/url-safety.ts
650
713
  function isSafeUrl(url) {
651
714
  if (typeof url !== "string") return false;
@@ -1328,6 +1391,7 @@ var Tolinku = class {
1328
1391
  this.ecommerce = new Ecommerce(this.client, () => this._userId);
1329
1392
  this.referrals = new Referrals(this.client);
1330
1393
  this.deferred = new Deferred(this.client);
1394
+ this.links = new Links(this.client);
1331
1395
  this.banners = new Banners(this.client);
1332
1396
  this.messages = new Messages(this.client);
1333
1397
  }