@tolinku/react-native-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
@@ -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.
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;
@@ -235,6 +255,16 @@ declare class HttpClient {
235
255
  post<T>(path: string, body?: Record<string, unknown>): Promise<T>;
236
256
  /** GET without API key auth (for public endpoints like deferred claim) */
237
257
  getPublic<T>(path: string, params?: Record<string, string>): Promise<T>;
258
+ /**
259
+ * POST to a host other than the configured one, without the API key.
260
+ *
261
+ * A few public endpoints work out which Appspace they belong to from the
262
+ * hostname the request arrived on rather than from a key or an id, so a
263
+ * question about a link on a customer's own domain has to be asked on that
264
+ * domain. Everything else about the request is unchanged: same timeout, same
265
+ * retries, same headers.
266
+ */
267
+ postPublicToOrigin<T>(origin: string, path: string, body?: Record<string, unknown>): Promise<T>;
238
268
  /** POST without API key auth (for public endpoints like deferred claim) */
239
269
  postPublic<T>(path: string, body?: Record<string, unknown>): Promise<T>;
240
270
  /**
@@ -383,6 +413,24 @@ declare class Deferred {
383
413
  private attemptSignals;
384
414
  }
385
415
 
416
+ declare class Links {
417
+ private client;
418
+ constructor(client: HttpClient);
419
+ /**
420
+ * What this link means, or null if it means nothing here.
421
+ *
422
+ * `url` is a whole link as the app received it. The question goes to the
423
+ * link's own host, because that is how the platform knows which Appspace is
424
+ * being asked about, which also means a link on a domain that is not yours
425
+ * simply answers nothing.
426
+ *
427
+ * Never throws. A link that cannot be resolved, for a bad network or any
428
+ * other reason, is one the app should fall back to its own handling for, and
429
+ * an exception in the middle of a cold start is no way to say so.
430
+ */
431
+ resolve(url: string): Promise<ResolvedLink | null>;
432
+ }
433
+
386
434
  /**
387
435
  * Main Tolinku SDK singleton.
388
436
  *
@@ -393,12 +441,13 @@ declare class Deferred {
393
441
  * await Tolinku.track('signup', { source: 'onboarding' });
394
442
  */
395
443
  declare class Tolinku {
396
- static readonly VERSION = "0.5.0";
444
+ static readonly VERSION = "0.6.0";
397
445
  private static client;
398
446
  private static analyticsInstance;
399
447
  private static ecommerceInstance;
400
448
  private static referralsInstance;
401
449
  private static deferredInstance;
450
+ private static linksInstance;
402
451
  private static _initialized;
403
452
  private static _userId;
404
453
  /**
@@ -476,6 +525,13 @@ declare class Tolinku {
476
525
  static get referrals(): Referrals;
477
526
  /** Deferred deep links: claimByToken, claimBySignals */
478
527
  static get deferred(): Deferred;
528
+ /**
529
+ * Turning a link the app was handed into the route and token it means.
530
+ *
531
+ * Needed for short links, which arrive as an opaque code that nothing on the
532
+ * device can interpret. See {@link Links.resolve}.
533
+ */
534
+ static get links(): Links;
479
535
  /**
480
536
  * Shut down the SDK and release resources.
481
537
  * Flushes remaining analytics events, cancels timers, removes listeners,
@@ -513,4 +569,4 @@ declare function TolinkuMessages({ trigger, triggerValue, onDismiss, onButtonPre
513
569
  */
514
570
  declare function isSafeUrl(url: string): boolean;
515
571
 
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 };
572
+ 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;
@@ -235,6 +255,16 @@ declare class HttpClient {
235
255
  post<T>(path: string, body?: Record<string, unknown>): Promise<T>;
236
256
  /** GET without API key auth (for public endpoints like deferred claim) */
237
257
  getPublic<T>(path: string, params?: Record<string, string>): Promise<T>;
258
+ /**
259
+ * POST to a host other than the configured one, without the API key.
260
+ *
261
+ * A few public endpoints work out which Appspace they belong to from the
262
+ * hostname the request arrived on rather than from a key or an id, so a
263
+ * question about a link on a customer's own domain has to be asked on that
264
+ * domain. Everything else about the request is unchanged: same timeout, same
265
+ * retries, same headers.
266
+ */
267
+ postPublicToOrigin<T>(origin: string, path: string, body?: Record<string, unknown>): Promise<T>;
238
268
  /** POST without API key auth (for public endpoints like deferred claim) */
239
269
  postPublic<T>(path: string, body?: Record<string, unknown>): Promise<T>;
240
270
  /**
@@ -383,6 +413,24 @@ declare class Deferred {
383
413
  private attemptSignals;
384
414
  }
385
415
 
416
+ declare class Links {
417
+ private client;
418
+ constructor(client: HttpClient);
419
+ /**
420
+ * What this link means, or null if it means nothing here.
421
+ *
422
+ * `url` is a whole link as the app received it. The question goes to the
423
+ * link's own host, because that is how the platform knows which Appspace is
424
+ * being asked about, which also means a link on a domain that is not yours
425
+ * simply answers nothing.
426
+ *
427
+ * Never throws. A link that cannot be resolved, for a bad network or any
428
+ * other reason, is one the app should fall back to its own handling for, and
429
+ * an exception in the middle of a cold start is no way to say so.
430
+ */
431
+ resolve(url: string): Promise<ResolvedLink | null>;
432
+ }
433
+
386
434
  /**
387
435
  * Main Tolinku SDK singleton.
388
436
  *
@@ -393,12 +441,13 @@ declare class Deferred {
393
441
  * await Tolinku.track('signup', { source: 'onboarding' });
394
442
  */
395
443
  declare class Tolinku {
396
- static readonly VERSION = "0.5.0";
444
+ static readonly VERSION = "0.6.0";
397
445
  private static client;
398
446
  private static analyticsInstance;
399
447
  private static ecommerceInstance;
400
448
  private static referralsInstance;
401
449
  private static deferredInstance;
450
+ private static linksInstance;
402
451
  private static _initialized;
403
452
  private static _userId;
404
453
  /**
@@ -476,6 +525,13 @@ declare class Tolinku {
476
525
  static get referrals(): Referrals;
477
526
  /** Deferred deep links: claimByToken, claimBySignals */
478
527
  static get deferred(): Deferred;
528
+ /**
529
+ * Turning a link the app was handed into the route and token it means.
530
+ *
531
+ * Needed for short links, which arrive as an opaque code that nothing on the
532
+ * device can interpret. See {@link Links.resolve}.
533
+ */
534
+ static get links(): Links;
479
535
  /**
480
536
  * Shut down the SDK and release resources.
481
537
  * Flushes remaining analytics events, cancels timers, removes listeners,
@@ -513,4 +569,4 @@ declare function TolinkuMessages({ trigger, triggerValue, onDismiss, onButtonPre
513
569
  */
514
570
  declare function isSafeUrl(url: string): boolean;
515
571
 
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 };
572
+ 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.js CHANGED
@@ -10,7 +10,7 @@ function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
10
10
  var AsyncStorage__default = /*#__PURE__*/_interopDefault(AsyncStorage);
11
11
 
12
12
  // src/types.ts
13
- var SDK_VERSION = "0.5.0";
13
+ var SDK_VERSION = "0.6.0";
14
14
 
15
15
  // src/debug.ts
16
16
  var _debugEnabled = false;
@@ -74,6 +74,25 @@ var HttpClient = class {
74
74
  headers: this.publicHeaders()
75
75
  });
76
76
  }
77
+ /**
78
+ * POST to a host other than the configured one, without the API key.
79
+ *
80
+ * A few public endpoints work out which Appspace they belong to from the
81
+ * hostname the request arrived on rather than from a key or an id, so a
82
+ * question about a link on a customer's own domain has to be asked on that
83
+ * domain. Everything else about the request is unchanged: same timeout, same
84
+ * retries, same headers.
85
+ */
86
+ async postPublicToOrigin(origin, path, body) {
87
+ return this.executeWithRetry(origin.replace(/\/+$/, "") + path, {
88
+ method: "POST",
89
+ headers: {
90
+ ...this.publicHeaders(),
91
+ "Content-Type": "application/json"
92
+ },
93
+ body: body ? JSON.stringify(body) : void 0
94
+ });
95
+ }
77
96
  /** POST without API key auth (for public endpoints like deferred claim) */
78
97
  async postPublic(path, body) {
79
98
  return this.executeWithRetry(this.baseUrl + path, {
@@ -849,6 +868,51 @@ function override(value) {
849
868
  }
850
869
  return void 0;
851
870
  }
871
+
872
+ // src/links.ts
873
+ function isRoutablePath(path) {
874
+ return typeof path === "string" && path.startsWith("/") && !path.startsWith("//");
875
+ }
876
+ var Links = class {
877
+ constructor(client) {
878
+ this.client = client;
879
+ }
880
+ /**
881
+ * What this link means, or null if it means nothing here.
882
+ *
883
+ * `url` is a whole link as the app received it. The question goes to the
884
+ * link's own host, because that is how the platform knows which Appspace is
885
+ * being asked about, which also means a link on a domain that is not yours
886
+ * simply answers nothing.
887
+ *
888
+ * Never throws. A link that cannot be resolved, for a bad network or any
889
+ * other reason, is one the app should fall back to its own handling for, and
890
+ * an exception in the middle of a cold start is no way to say so.
891
+ */
892
+ async resolve(url) {
893
+ if (!url || typeof url !== "string") return null;
894
+ let parsed;
895
+ try {
896
+ parsed = new URL(url.trim());
897
+ } catch {
898
+ debugWarn(`Links.resolve: not a URL: ${url}`);
899
+ return null;
900
+ }
901
+ if (parsed.protocol !== "https:" && parsed.protocol !== "http:") return null;
902
+ try {
903
+ const result = await this.client.postPublicToOrigin(
904
+ parsed.origin,
905
+ "/v1/api/path",
906
+ { path: parsed.pathname }
907
+ );
908
+ if (!result || !result.route || !isRoutablePath(result.deep_link_path)) return null;
909
+ return result;
910
+ } catch (err) {
911
+ debugWarn(`Links.resolve failed: ${err.message}`);
912
+ return null;
913
+ }
914
+ }
915
+ };
852
916
  var BASE_KEY = "tolinku_message_dismissed";
853
917
  var IMPRESSIONS_BASE_KEY = "tolinku_message_impressions";
854
918
  var LAST_SHOWN_BASE_KEY = "tolinku_message_last_shown";
@@ -972,6 +1036,7 @@ var _Tolinku = class _Tolinku {
972
1036
  _Tolinku.ecommerceInstance = new Ecommerce(_Tolinku.client, () => _Tolinku._userId);
973
1037
  _Tolinku.referralsInstance = new Referrals(_Tolinku.client);
974
1038
  _Tolinku.deferredInstance = new Deferred(_Tolinku.client);
1039
+ _Tolinku.linksInstance = new Links(_Tolinku.client);
975
1040
  _Tolinku._initialized = true;
976
1041
  debugLog(`Tolinku SDK v${SDK_VERSION} initialized (baseUrl=${baseUrl})`);
977
1042
  }
@@ -1077,6 +1142,18 @@ var _Tolinku = class _Tolinku {
1077
1142
  }
1078
1143
  return _Tolinku.deferredInstance;
1079
1144
  }
1145
+ /**
1146
+ * Turning a link the app was handed into the route and token it means.
1147
+ *
1148
+ * Needed for short links, which arrive as an opaque code that nothing on the
1149
+ * device can interpret. See {@link Links.resolve}.
1150
+ */
1151
+ static get links() {
1152
+ if (!_Tolinku.linksInstance) {
1153
+ throw new Error("Tolinku: SDK not initialized. Call Tolinku.init() first.");
1154
+ }
1155
+ return _Tolinku.linksInstance;
1156
+ }
1080
1157
  /**
1081
1158
  * Shut down the SDK and release resources.
1082
1159
  * Flushes remaining analytics events, cancels timers, removes listeners,
@@ -1100,6 +1177,7 @@ var _Tolinku = class _Tolinku {
1100
1177
  _Tolinku.ecommerceInstance = null;
1101
1178
  _Tolinku.referralsInstance = null;
1102
1179
  _Tolinku.deferredInstance = null;
1180
+ _Tolinku.linksInstance = null;
1103
1181
  _Tolinku._initialized = false;
1104
1182
  _Tolinku._userId = null;
1105
1183
  setDebugEnabled(false);
@@ -1111,6 +1189,7 @@ _Tolinku.analyticsInstance = null;
1111
1189
  _Tolinku.ecommerceInstance = null;
1112
1190
  _Tolinku.referralsInstance = null;
1113
1191
  _Tolinku.deferredInstance = null;
1192
+ _Tolinku.linksInstance = null;
1114
1193
  _Tolinku._initialized = false;
1115
1194
  _Tolinku._userId = null;
1116
1195
  var Tolinku = _Tolinku;