@tolinku/web-sdk 0.5.0 → 0.6.1
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 +102 -3
- package/dist/index.d.ts +102 -3
- package/dist/index.js +396 -56
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +396 -56
- package/dist/index.mjs.map +1 -1
- package/dist/tolinku.min.js +27 -25
- 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
|
@@ -179,16 +179,40 @@ interface Message {
|
|
|
179
179
|
}
|
|
180
180
|
/** Puck component content tree */
|
|
181
181
|
interface MessageContent {
|
|
182
|
-
root
|
|
183
|
-
props
|
|
182
|
+
root?: {
|
|
183
|
+
props?: Record<string, unknown>;
|
|
184
184
|
};
|
|
185
185
|
content: MessageComponent[];
|
|
186
|
+
/**
|
|
187
|
+
* Where a Section's children actually live.
|
|
188
|
+
*
|
|
189
|
+
* Puck stores the contents of a drop zone here, keyed `<component id>:content`,
|
|
190
|
+
* and never writes `props.children`. A renderer that reads `props.children`
|
|
191
|
+
* draws every Section as an empty box and loses everything inside it.
|
|
192
|
+
*/
|
|
193
|
+
zones?: Record<string, MessageComponent[]>;
|
|
186
194
|
}
|
|
187
195
|
/** A single Puck component */
|
|
188
196
|
interface MessageComponent {
|
|
189
197
|
type: string;
|
|
190
198
|
props: Record<string, unknown>;
|
|
191
199
|
}
|
|
200
|
+
/**
|
|
201
|
+
* The app a message belongs to, sent alongside the messages.
|
|
202
|
+
*
|
|
203
|
+
* AppIcon, StoreButtons and DeepLinkButton describe the app rather than the
|
|
204
|
+
* message, so the content itself carries nothing to draw them from.
|
|
205
|
+
*/
|
|
206
|
+
interface MessageAppContext {
|
|
207
|
+
name: string;
|
|
208
|
+
icon_url: string | null;
|
|
209
|
+
ios_store_url: string | null;
|
|
210
|
+
android_store_url: string | null;
|
|
211
|
+
deep_link_url: string | null;
|
|
212
|
+
/** The store badge artwork, absolute and PNG, served by the API host. */
|
|
213
|
+
ios_badge_url?: string | null;
|
|
214
|
+
android_badge_url?: string | null;
|
|
215
|
+
}
|
|
192
216
|
/** Options for showing an in-app message */
|
|
193
217
|
interface ShowMessageOptions {
|
|
194
218
|
trigger?: string;
|
|
@@ -268,6 +292,26 @@ interface SpendCreditsParams {
|
|
|
268
292
|
revenue: number;
|
|
269
293
|
currency: string;
|
|
270
294
|
}
|
|
295
|
+
/**
|
|
296
|
+
* What a Tolinku link turned out to mean.
|
|
297
|
+
*
|
|
298
|
+
* The same shape in every SDK, so an app moving between them reads one thing.
|
|
299
|
+
* The Appspace the link belongs to is deliberately not here: the caller already
|
|
300
|
+
* knows which Appspace it is, and nothing about routing a link needs it.
|
|
301
|
+
*/
|
|
302
|
+
interface ResolvedLink {
|
|
303
|
+
/** The route that answers this link. */
|
|
304
|
+
route: {
|
|
305
|
+
prefix: string;
|
|
306
|
+
name: string;
|
|
307
|
+
template: string;
|
|
308
|
+
link_type?: string;
|
|
309
|
+
};
|
|
310
|
+
/** The token the link carried, or '' where it carried none. */
|
|
311
|
+
token: string;
|
|
312
|
+
/** The canonical path, with the token wherever the route's prefix puts it. */
|
|
313
|
+
deep_link_path: string;
|
|
314
|
+
}
|
|
271
315
|
|
|
272
316
|
declare class HttpClient {
|
|
273
317
|
private _baseUrl;
|
|
@@ -284,6 +328,16 @@ declare class HttpClient {
|
|
|
284
328
|
get key(): string;
|
|
285
329
|
get<T>(path: string, params?: Record<string, string>): Promise<T>;
|
|
286
330
|
post<T>(path: string, body?: Record<string, unknown>): Promise<T>;
|
|
331
|
+
/**
|
|
332
|
+
* POST to a host other than the configured one, without the API key.
|
|
333
|
+
*
|
|
334
|
+
* A few public endpoints work out which Appspace they belong to from the
|
|
335
|
+
* hostname the request arrives on rather than from a key or an id, so a
|
|
336
|
+
* question about a link on a customer's own domain has to be asked on that
|
|
337
|
+
* domain. No key goes with it: the origin comes from a URL the caller was
|
|
338
|
+
* handed, which is not necessarily ours.
|
|
339
|
+
*/
|
|
340
|
+
postPublicToOrigin<T>(origin: string, path: string, body?: Record<string, unknown>): Promise<T>;
|
|
287
341
|
/** GET without API key auth (for public endpoints like banner config) */
|
|
288
342
|
getPublic<T>(path: string, params?: Record<string, string>): Promise<T>;
|
|
289
343
|
/** POST without API key auth (for public endpoints like deferred claim) */
|
|
@@ -430,6 +484,44 @@ declare class Deferred {
|
|
|
430
484
|
private attemptSignals;
|
|
431
485
|
}
|
|
432
486
|
|
|
487
|
+
/**
|
|
488
|
+
* Working out what a link actually means.
|
|
489
|
+
*
|
|
490
|
+
* On the open web this rarely comes up: a browser follows a short link to
|
|
491
|
+
* Tolinku, which resolves it and serves the page, so nothing on the page ever
|
|
492
|
+
* sees an unreadable URL.
|
|
493
|
+
*
|
|
494
|
+
* Inside a Capacitor or Cordova app it comes up constantly. There the operating
|
|
495
|
+
* system hands the web layer the URL that was tapped, exactly as written, and
|
|
496
|
+
* the routing happens in JavaScript. A short link arrives as an opaque code:
|
|
497
|
+
*
|
|
498
|
+
* https://links.example.com/s7k2p9q/4821
|
|
499
|
+
*
|
|
500
|
+
* Nothing in that URL says which route it is, and nothing on the device can work
|
|
501
|
+
* it out. Code parsing the path itself sees a first segment it has never heard
|
|
502
|
+
* of and does nothing, so the link opens the app and then appears to fail: no
|
|
503
|
+
* error, no screen, no clue.
|
|
504
|
+
*
|
|
505
|
+
* `resolve` asks Tolinku, which answers with the route, the token and the
|
|
506
|
+
* canonical path. A readable URL comes back unchanged, so everything can be
|
|
507
|
+
* resolved rather than guessing which kind it is.
|
|
508
|
+
*/
|
|
509
|
+
declare class Links {
|
|
510
|
+
private client;
|
|
511
|
+
constructor(client: HttpClient);
|
|
512
|
+
/**
|
|
513
|
+
* What this link means, or null if it means nothing here.
|
|
514
|
+
*
|
|
515
|
+
* The question goes to the link's own host, because that is how Tolinku knows
|
|
516
|
+
* which Appspace is being asked about, which also means a link on a domain
|
|
517
|
+
* that is not yours simply answers nothing.
|
|
518
|
+
*
|
|
519
|
+
* Never throws. A link that cannot be resolved, for a bad network or any
|
|
520
|
+
* other reason, is one to fall back to your own handling for.
|
|
521
|
+
*/
|
|
522
|
+
resolve(url: string): Promise<ResolvedLink | null>;
|
|
523
|
+
}
|
|
524
|
+
|
|
433
525
|
declare class Tolinku {
|
|
434
526
|
private client;
|
|
435
527
|
/** Analytics: track custom events */
|
|
@@ -440,6 +532,13 @@ declare class Tolinku {
|
|
|
440
532
|
readonly referrals: Referrals;
|
|
441
533
|
/** Deferred deep links: claim by token or signals */
|
|
442
534
|
readonly deferred: Deferred;
|
|
535
|
+
/**
|
|
536
|
+
* Turning a link into the route and token it means.
|
|
537
|
+
*
|
|
538
|
+
* Needed for short links, which arrive as an opaque code. See
|
|
539
|
+
* {@link Links.resolve}.
|
|
540
|
+
*/
|
|
541
|
+
readonly links: Links;
|
|
443
542
|
private banners;
|
|
444
543
|
private messages;
|
|
445
544
|
/** The current user ID, used for segment targeting and analytics. */
|
|
@@ -470,4 +569,4 @@ declare class Tolinku {
|
|
|
470
569
|
destroy(): void;
|
|
471
570
|
}
|
|
472
571
|
|
|
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 };
|
|
572
|
+
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 MessageAppContext, 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
|
@@ -179,16 +179,40 @@ interface Message {
|
|
|
179
179
|
}
|
|
180
180
|
/** Puck component content tree */
|
|
181
181
|
interface MessageContent {
|
|
182
|
-
root
|
|
183
|
-
props
|
|
182
|
+
root?: {
|
|
183
|
+
props?: Record<string, unknown>;
|
|
184
184
|
};
|
|
185
185
|
content: MessageComponent[];
|
|
186
|
+
/**
|
|
187
|
+
* Where a Section's children actually live.
|
|
188
|
+
*
|
|
189
|
+
* Puck stores the contents of a drop zone here, keyed `<component id>:content`,
|
|
190
|
+
* and never writes `props.children`. A renderer that reads `props.children`
|
|
191
|
+
* draws every Section as an empty box and loses everything inside it.
|
|
192
|
+
*/
|
|
193
|
+
zones?: Record<string, MessageComponent[]>;
|
|
186
194
|
}
|
|
187
195
|
/** A single Puck component */
|
|
188
196
|
interface MessageComponent {
|
|
189
197
|
type: string;
|
|
190
198
|
props: Record<string, unknown>;
|
|
191
199
|
}
|
|
200
|
+
/**
|
|
201
|
+
* The app a message belongs to, sent alongside the messages.
|
|
202
|
+
*
|
|
203
|
+
* AppIcon, StoreButtons and DeepLinkButton describe the app rather than the
|
|
204
|
+
* message, so the content itself carries nothing to draw them from.
|
|
205
|
+
*/
|
|
206
|
+
interface MessageAppContext {
|
|
207
|
+
name: string;
|
|
208
|
+
icon_url: string | null;
|
|
209
|
+
ios_store_url: string | null;
|
|
210
|
+
android_store_url: string | null;
|
|
211
|
+
deep_link_url: string | null;
|
|
212
|
+
/** The store badge artwork, absolute and PNG, served by the API host. */
|
|
213
|
+
ios_badge_url?: string | null;
|
|
214
|
+
android_badge_url?: string | null;
|
|
215
|
+
}
|
|
192
216
|
/** Options for showing an in-app message */
|
|
193
217
|
interface ShowMessageOptions {
|
|
194
218
|
trigger?: string;
|
|
@@ -268,6 +292,26 @@ interface SpendCreditsParams {
|
|
|
268
292
|
revenue: number;
|
|
269
293
|
currency: string;
|
|
270
294
|
}
|
|
295
|
+
/**
|
|
296
|
+
* What a Tolinku link turned out to mean.
|
|
297
|
+
*
|
|
298
|
+
* The same shape in every SDK, so an app moving between them reads one thing.
|
|
299
|
+
* The Appspace the link belongs to is deliberately not here: the caller already
|
|
300
|
+
* knows which Appspace it is, and nothing about routing a link needs it.
|
|
301
|
+
*/
|
|
302
|
+
interface ResolvedLink {
|
|
303
|
+
/** The route that answers this link. */
|
|
304
|
+
route: {
|
|
305
|
+
prefix: string;
|
|
306
|
+
name: string;
|
|
307
|
+
template: string;
|
|
308
|
+
link_type?: string;
|
|
309
|
+
};
|
|
310
|
+
/** The token the link carried, or '' where it carried none. */
|
|
311
|
+
token: string;
|
|
312
|
+
/** The canonical path, with the token wherever the route's prefix puts it. */
|
|
313
|
+
deep_link_path: string;
|
|
314
|
+
}
|
|
271
315
|
|
|
272
316
|
declare class HttpClient {
|
|
273
317
|
private _baseUrl;
|
|
@@ -284,6 +328,16 @@ declare class HttpClient {
|
|
|
284
328
|
get key(): string;
|
|
285
329
|
get<T>(path: string, params?: Record<string, string>): Promise<T>;
|
|
286
330
|
post<T>(path: string, body?: Record<string, unknown>): Promise<T>;
|
|
331
|
+
/**
|
|
332
|
+
* POST to a host other than the configured one, without the API key.
|
|
333
|
+
*
|
|
334
|
+
* A few public endpoints work out which Appspace they belong to from the
|
|
335
|
+
* hostname the request arrives on rather than from a key or an id, so a
|
|
336
|
+
* question about a link on a customer's own domain has to be asked on that
|
|
337
|
+
* domain. No key goes with it: the origin comes from a URL the caller was
|
|
338
|
+
* handed, which is not necessarily ours.
|
|
339
|
+
*/
|
|
340
|
+
postPublicToOrigin<T>(origin: string, path: string, body?: Record<string, unknown>): Promise<T>;
|
|
287
341
|
/** GET without API key auth (for public endpoints like banner config) */
|
|
288
342
|
getPublic<T>(path: string, params?: Record<string, string>): Promise<T>;
|
|
289
343
|
/** POST without API key auth (for public endpoints like deferred claim) */
|
|
@@ -430,6 +484,44 @@ declare class Deferred {
|
|
|
430
484
|
private attemptSignals;
|
|
431
485
|
}
|
|
432
486
|
|
|
487
|
+
/**
|
|
488
|
+
* Working out what a link actually means.
|
|
489
|
+
*
|
|
490
|
+
* On the open web this rarely comes up: a browser follows a short link to
|
|
491
|
+
* Tolinku, which resolves it and serves the page, so nothing on the page ever
|
|
492
|
+
* sees an unreadable URL.
|
|
493
|
+
*
|
|
494
|
+
* Inside a Capacitor or Cordova app it comes up constantly. There the operating
|
|
495
|
+
* system hands the web layer the URL that was tapped, exactly as written, and
|
|
496
|
+
* the routing happens in JavaScript. A short link arrives as an opaque code:
|
|
497
|
+
*
|
|
498
|
+
* https://links.example.com/s7k2p9q/4821
|
|
499
|
+
*
|
|
500
|
+
* Nothing in that URL says which route it is, and nothing on the device can work
|
|
501
|
+
* it out. Code parsing the path itself sees a first segment it has never heard
|
|
502
|
+
* of and does nothing, so the link opens the app and then appears to fail: no
|
|
503
|
+
* error, no screen, no clue.
|
|
504
|
+
*
|
|
505
|
+
* `resolve` asks Tolinku, which answers with the route, the token and the
|
|
506
|
+
* canonical path. A readable URL comes back unchanged, so everything can be
|
|
507
|
+
* resolved rather than guessing which kind it is.
|
|
508
|
+
*/
|
|
509
|
+
declare class Links {
|
|
510
|
+
private client;
|
|
511
|
+
constructor(client: HttpClient);
|
|
512
|
+
/**
|
|
513
|
+
* What this link means, or null if it means nothing here.
|
|
514
|
+
*
|
|
515
|
+
* The question goes to the link's own host, because that is how Tolinku knows
|
|
516
|
+
* which Appspace is being asked about, which also means a link on a domain
|
|
517
|
+
* that is not yours simply answers nothing.
|
|
518
|
+
*
|
|
519
|
+
* Never throws. A link that cannot be resolved, for a bad network or any
|
|
520
|
+
* other reason, is one to fall back to your own handling for.
|
|
521
|
+
*/
|
|
522
|
+
resolve(url: string): Promise<ResolvedLink | null>;
|
|
523
|
+
}
|
|
524
|
+
|
|
433
525
|
declare class Tolinku {
|
|
434
526
|
private client;
|
|
435
527
|
/** Analytics: track custom events */
|
|
@@ -440,6 +532,13 @@ declare class Tolinku {
|
|
|
440
532
|
readonly referrals: Referrals;
|
|
441
533
|
/** Deferred deep links: claim by token or signals */
|
|
442
534
|
readonly deferred: Deferred;
|
|
535
|
+
/**
|
|
536
|
+
* Turning a link into the route and token it means.
|
|
537
|
+
*
|
|
538
|
+
* Needed for short links, which arrive as an opaque code. See
|
|
539
|
+
* {@link Links.resolve}.
|
|
540
|
+
*/
|
|
541
|
+
readonly links: Links;
|
|
443
542
|
private banners;
|
|
444
543
|
private messages;
|
|
445
544
|
/** The current user ID, used for segment targeting and analytics. */
|
|
@@ -470,4 +569,4 @@ declare class Tolinku {
|
|
|
470
569
|
destroy(): void;
|
|
471
570
|
}
|
|
472
571
|
|
|
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 };
|
|
572
|
+
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 MessageAppContext, 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 };
|