@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 +23 -0
- package/dist/index.d.mts +76 -1
- package/dist/index.d.ts +76 -1
- package/dist/index.js +65 -1
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +65 -1
- package/dist/index.mjs.map +1 -1
- package/dist/tolinku.min.js +17 -17
- package/dist/tolinku.min.js.map +1 -1
- package/package.json +1 -1
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.
|
|
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
|
}
|