@tolinku/react-native-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 CHANGED
@@ -131,6 +131,30 @@ await Tolinku.ecommerce.flush();
131
131
 
132
132
  The SDK supports 13 event types covering the full shopping journey. Cart IDs are managed automatically via `AsyncStorage` and cleared after purchase. Events auto-flush when the app enters the background.
133
133
 
134
+ ### Resolving a Link
135
+
136
+ Short links open your app but arrive as an opaque code, `/s7k2p9q/4821`.
137
+ Nothing in that URL says which route it is, and nothing on the device can work
138
+ it out, so an app parsing the path itself does nothing and the link appears to
139
+ fail with no error and no screen.
140
+
141
+ `resolve` asks Tolinku, which answers with the route, the token and the
142
+ canonical path. A readable URL comes back unchanged, so you can resolve
143
+ everything rather than guessing which kind you have. It never throws: a link it
144
+ cannot resolve is one to fall back to your own handling for.
145
+
146
+ ```js
147
+ import { Tolinku } from '@tolinku/react-native-sdk';
148
+
149
+ const link = await Tolinku.links.resolve(url);
150
+ if (link) {
151
+ // link.deep_link_path -> "/order/4821/receipt"
152
+ // link.token -> "4821"
153
+ // link.route.prefix -> "order/{token}/receipt"
154
+ route(link.deep_link_path);
155
+ }
156
+ ```
157
+
134
158
  ### Deferred Deep Links
135
159
 
136
160
  Recover deep link context for users who installed your app after clicking a link. Deferred deep linking lets you route users to specific content even when the app was not installed at the time of the click.
@@ -211,7 +235,7 @@ The component automatically filters dismissed and suppressed messages, and shows
211
235
  |------|------|-------------|
212
236
  | `trigger` | `string?` | Filter messages by trigger type |
213
237
  | `triggerValue` | `string?` | Match a specific trigger value |
214
- | `onButtonPress` | `(action, messageId) => void` | Called when a message button is pressed. Only for `http` and `https` actions; anything else is blocked before this runs |
238
+ | `onButtonPress` | `(action, messageId) => void` | Called when a message button is pressed, including a deep link into your own app such as `myapp://order/4821`. Schemes that can run code (`javascript:`, `data:`, `file:` and the like) are blocked before this runs |
215
239
  | `onDismiss` | `(messageId) => void` | Called when a message is dismissed |
216
240
 
217
241
  ## Configuration Options
@@ -288,7 +312,7 @@ await Tolinku.destroy();
288
312
  |------|-------------|
289
313
  | `trigger` | Filter messages by trigger type |
290
314
  | `triggerValue` | Match a specific trigger value |
291
- | `onButtonPress` | Callback for button presses, for `http` and `https` actions only |
315
+ | `onButtonPress` | Callback for button presses, including your own app's deep link scheme |
292
316
  | `onDismiss` | Callback for message dismissal |
293
317
 
294
318
  ## Documentation
package/dist/index.d.mts CHANGED
@@ -104,6 +104,26 @@ interface DeferredLink {
104
104
  referrer_id?: string;
105
105
  referral_code?: string;
106
106
  }
107
+ /**
108
+ * What a Tolinku link turned out to mean.
109
+ *
110
+ * The same shape in every SDK, so an app moving between them reads one thing.
111
+ * The Appspace the link belongs to is deliberately not here: the app already
112
+ * knows which Appspace it is, and nothing about routing a link needs it.
113
+ */
114
+ interface ResolvedLink {
115
+ /** The route that answers this link. */
116
+ route: {
117
+ prefix: string;
118
+ name: string;
119
+ template: string;
120
+ link_type?: string;
121
+ };
122
+ /** The token the link carried, or '' where it carried none. */
123
+ token: string;
124
+ /** The canonical path, with the token wherever the route's prefix puts it. */
125
+ deep_link_path: string;
126
+ }
107
127
  /** Options for claiming deferred link by signals */
108
128
  interface ClaimBySignalsOptions {
109
129
  appspaceId: string;
@@ -137,6 +157,15 @@ interface MessageContent {
137
157
  props: Record<string, unknown>;
138
158
  };
139
159
  content: MessageComponent[];
160
+ /**
161
+ * A Section's children, keyed "<component id>:content".
162
+ *
163
+ * Puck keeps nested content here rather than on the parent's props, so a
164
+ * renderer that reads props.children finds nothing and draws every Section
165
+ * as an empty box. This was missing from the type entirely, which is part of
166
+ * how that went unnoticed.
167
+ */
168
+ zones?: Record<string, MessageComponent[]>;
140
169
  }
141
170
  /** A single Puck component */
142
171
  interface MessageComponent {
@@ -235,6 +264,16 @@ declare class HttpClient {
235
264
  post<T>(path: string, body?: Record<string, unknown>): Promise<T>;
236
265
  /** GET without API key auth (for public endpoints like deferred claim) */
237
266
  getPublic<T>(path: string, params?: Record<string, string>): Promise<T>;
267
+ /**
268
+ * POST to a host other than the configured one, without the API key.
269
+ *
270
+ * A few public endpoints work out which Appspace they belong to from the
271
+ * hostname the request arrived on rather than from a key or an id, so a
272
+ * question about a link on a customer's own domain has to be asked on that
273
+ * domain. Everything else about the request is unchanged: same timeout, same
274
+ * retries, same headers.
275
+ */
276
+ postPublicToOrigin<T>(origin: string, path: string, body?: Record<string, unknown>): Promise<T>;
238
277
  /** POST without API key auth (for public endpoints like deferred claim) */
239
278
  postPublic<T>(path: string, body?: Record<string, unknown>): Promise<T>;
240
279
  /**
@@ -383,6 +422,24 @@ declare class Deferred {
383
422
  private attemptSignals;
384
423
  }
385
424
 
425
+ declare class Links {
426
+ private client;
427
+ constructor(client: HttpClient);
428
+ /**
429
+ * What this link means, or null if it means nothing here.
430
+ *
431
+ * `url` is a whole link as the app received it. The question goes to the
432
+ * link's own host, because that is how the platform knows which Appspace is
433
+ * being asked about, which also means a link on a domain that is not yours
434
+ * simply answers nothing.
435
+ *
436
+ * Never throws. A link that cannot be resolved, for a bad network or any
437
+ * other reason, is one the app should fall back to its own handling for, and
438
+ * an exception in the middle of a cold start is no way to say so.
439
+ */
440
+ resolve(url: string): Promise<ResolvedLink | null>;
441
+ }
442
+
386
443
  /**
387
444
  * Main Tolinku SDK singleton.
388
445
  *
@@ -393,12 +450,13 @@ declare class Deferred {
393
450
  * await Tolinku.track('signup', { source: 'onboarding' });
394
451
  */
395
452
  declare class Tolinku {
396
- static readonly VERSION = "0.5.0";
453
+ static readonly VERSION = "0.6.1";
397
454
  private static client;
398
455
  private static analyticsInstance;
399
456
  private static ecommerceInstance;
400
457
  private static referralsInstance;
401
458
  private static deferredInstance;
459
+ private static linksInstance;
402
460
  private static _initialized;
403
461
  private static _userId;
404
462
  /**
@@ -476,6 +534,13 @@ declare class Tolinku {
476
534
  static get referrals(): Referrals;
477
535
  /** Deferred deep links: claimByToken, claimBySignals */
478
536
  static get deferred(): Deferred;
537
+ /**
538
+ * Turning a link the app was handed into the route and token it means.
539
+ *
540
+ * Needed for short links, which arrive as an opaque code that nothing on the
541
+ * device can interpret. See {@link Links.resolve}.
542
+ */
543
+ static get links(): Links;
479
544
  /**
480
545
  * Shut down the SDK and release resources.
481
546
  * Flushes remaining analytics events, cancels timers, removes listeners,
@@ -513,4 +578,4 @@ declare function TolinkuMessages({ trigger, triggerValue, onDismiss, onButtonPre
513
578
  */
514
579
  declare function isSafeUrl(url: string): boolean;
515
580
 
516
- export { type AddPaymentInfoParams, type AddToCartParams, type AddToWishlistParams, 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 ReferrerProvider, type RefundParams, type RemoveFromCartParams, type ResolvedTolinkuConfig, type SearchParams, type ShareParams, type ShowMessageOptions, type SpendCreditsParams, Tolinku, type TolinkuConfig, TolinkuError, TolinkuMessages, type TrackProperties, type ViewItemParams, getInstallReferrerToken, isSafeUrl, parseInstallReferrer };
581
+ export { type AddPaymentInfoParams, type AddToCartParams, type AddToWishlistParams, 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 ReferrerProvider, type RefundParams, type RemoveFromCartParams, type ResolvedLink, type ResolvedTolinkuConfig, type SearchParams, type ShareParams, type ShowMessageOptions, type SpendCreditsParams, Tolinku, type TolinkuConfig, TolinkuError, TolinkuMessages, type TrackProperties, type ViewItemParams, getInstallReferrerToken, isSafeUrl, parseInstallReferrer };
package/dist/index.d.ts CHANGED
@@ -104,6 +104,26 @@ interface DeferredLink {
104
104
  referrer_id?: string;
105
105
  referral_code?: string;
106
106
  }
107
+ /**
108
+ * What a Tolinku link turned out to mean.
109
+ *
110
+ * The same shape in every SDK, so an app moving between them reads one thing.
111
+ * The Appspace the link belongs to is deliberately not here: the app already
112
+ * knows which Appspace it is, and nothing about routing a link needs it.
113
+ */
114
+ interface ResolvedLink {
115
+ /** The route that answers this link. */
116
+ route: {
117
+ prefix: string;
118
+ name: string;
119
+ template: string;
120
+ link_type?: string;
121
+ };
122
+ /** The token the link carried, or '' where it carried none. */
123
+ token: string;
124
+ /** The canonical path, with the token wherever the route's prefix puts it. */
125
+ deep_link_path: string;
126
+ }
107
127
  /** Options for claiming deferred link by signals */
108
128
  interface ClaimBySignalsOptions {
109
129
  appspaceId: string;
@@ -137,6 +157,15 @@ interface MessageContent {
137
157
  props: Record<string, unknown>;
138
158
  };
139
159
  content: MessageComponent[];
160
+ /**
161
+ * A Section's children, keyed "<component id>:content".
162
+ *
163
+ * Puck keeps nested content here rather than on the parent's props, so a
164
+ * renderer that reads props.children finds nothing and draws every Section
165
+ * as an empty box. This was missing from the type entirely, which is part of
166
+ * how that went unnoticed.
167
+ */
168
+ zones?: Record<string, MessageComponent[]>;
140
169
  }
141
170
  /** A single Puck component */
142
171
  interface MessageComponent {
@@ -235,6 +264,16 @@ declare class HttpClient {
235
264
  post<T>(path: string, body?: Record<string, unknown>): Promise<T>;
236
265
  /** GET without API key auth (for public endpoints like deferred claim) */
237
266
  getPublic<T>(path: string, params?: Record<string, string>): Promise<T>;
267
+ /**
268
+ * POST to a host other than the configured one, without the API key.
269
+ *
270
+ * A few public endpoints work out which Appspace they belong to from the
271
+ * hostname the request arrived on rather than from a key or an id, so a
272
+ * question about a link on a customer's own domain has to be asked on that
273
+ * domain. Everything else about the request is unchanged: same timeout, same
274
+ * retries, same headers.
275
+ */
276
+ postPublicToOrigin<T>(origin: string, path: string, body?: Record<string, unknown>): Promise<T>;
238
277
  /** POST without API key auth (for public endpoints like deferred claim) */
239
278
  postPublic<T>(path: string, body?: Record<string, unknown>): Promise<T>;
240
279
  /**
@@ -383,6 +422,24 @@ declare class Deferred {
383
422
  private attemptSignals;
384
423
  }
385
424
 
425
+ declare class Links {
426
+ private client;
427
+ constructor(client: HttpClient);
428
+ /**
429
+ * What this link means, or null if it means nothing here.
430
+ *
431
+ * `url` is a whole link as the app received it. The question goes to the
432
+ * link's own host, because that is how the platform knows which Appspace is
433
+ * being asked about, which also means a link on a domain that is not yours
434
+ * simply answers nothing.
435
+ *
436
+ * Never throws. A link that cannot be resolved, for a bad network or any
437
+ * other reason, is one the app should fall back to its own handling for, and
438
+ * an exception in the middle of a cold start is no way to say so.
439
+ */
440
+ resolve(url: string): Promise<ResolvedLink | null>;
441
+ }
442
+
386
443
  /**
387
444
  * Main Tolinku SDK singleton.
388
445
  *
@@ -393,12 +450,13 @@ declare class Deferred {
393
450
  * await Tolinku.track('signup', { source: 'onboarding' });
394
451
  */
395
452
  declare class Tolinku {
396
- static readonly VERSION = "0.5.0";
453
+ static readonly VERSION = "0.6.1";
397
454
  private static client;
398
455
  private static analyticsInstance;
399
456
  private static ecommerceInstance;
400
457
  private static referralsInstance;
401
458
  private static deferredInstance;
459
+ private static linksInstance;
402
460
  private static _initialized;
403
461
  private static _userId;
404
462
  /**
@@ -476,6 +534,13 @@ declare class Tolinku {
476
534
  static get referrals(): Referrals;
477
535
  /** Deferred deep links: claimByToken, claimBySignals */
478
536
  static get deferred(): Deferred;
537
+ /**
538
+ * Turning a link the app was handed into the route and token it means.
539
+ *
540
+ * Needed for short links, which arrive as an opaque code that nothing on the
541
+ * device can interpret. See {@link Links.resolve}.
542
+ */
543
+ static get links(): Links;
479
544
  /**
480
545
  * Shut down the SDK and release resources.
481
546
  * Flushes remaining analytics events, cancels timers, removes listeners,
@@ -513,4 +578,4 @@ declare function TolinkuMessages({ trigger, triggerValue, onDismiss, onButtonPre
513
578
  */
514
579
  declare function isSafeUrl(url: string): boolean;
515
580
 
516
- export { type AddPaymentInfoParams, type AddToCartParams, type AddToWishlistParams, 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 ReferrerProvider, type RefundParams, type RemoveFromCartParams, type ResolvedTolinkuConfig, type SearchParams, type ShareParams, type ShowMessageOptions, type SpendCreditsParams, Tolinku, type TolinkuConfig, TolinkuError, TolinkuMessages, type TrackProperties, type ViewItemParams, getInstallReferrerToken, isSafeUrl, parseInstallReferrer };
581
+ export { type AddPaymentInfoParams, type AddToCartParams, type AddToWishlistParams, 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 ReferrerProvider, type RefundParams, type RemoveFromCartParams, type ResolvedLink, type ResolvedTolinkuConfig, type SearchParams, type ShareParams, type ShowMessageOptions, type SpendCreditsParams, Tolinku, type TolinkuConfig, TolinkuError, TolinkuMessages, type TrackProperties, type ViewItemParams, getInstallReferrerToken, isSafeUrl, parseInstallReferrer };