@tolinku/react-native-sdk 0.4.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.
@@ -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 |
238
+ | `onButtonPress` | `(action, messageId) => void` | Called when a message button is pressed. Only for `http` and `https` actions; anything else is 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 |
315
+ | `onButtonPress` | Callback for button presses, for `http` and `https` actions only |
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;
@@ -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.4.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
  /**
@@ -434,6 +483,38 @@ declare class Tolinku {
434
483
  * Events are batched and flushed automatically.
435
484
  */
436
485
  static track(eventType: string, properties?: TrackProperties): Promise<void>;
486
+ /**
487
+ * Report that a link opened the app, when it opened without the browser.
488
+ *
489
+ * A Universal Link or App Link hands the app the URL directly, so Tolinku is
490
+ * never contacted and the tap goes unrecorded. Those taps come from people who
491
+ * already have your app, so leaving them out makes a re-engagement campaign
492
+ * look like a failure exactly when it worked.
493
+ *
494
+ * Both ways a link arrives need it. The listener fires only while the app is
495
+ * already running, so a link that launched the app cold arrives separately:
496
+ *
497
+ * ```ts
498
+ * // Launched by a link, app was not running.
499
+ * const initial = await Linking.getInitialURL();
500
+ * if (initial) Tolinku.trackLinkOpen(initial);
501
+ *
502
+ * // Tapped while the app was already open.
503
+ * Linking.addEventListener('url', ({ url }) => {
504
+ * Tolinku.trackLinkOpen(url);
505
+ * // your own routing
506
+ * });
507
+ * ```
508
+ *
509
+ * Wiring both is safe: the same link arriving twice in quick succession is
510
+ * reported once.
511
+ *
512
+ * Only http and https links are reported. A custom scheme means Tolinku's own
513
+ * hand-off page opened the app, and that tap is already counted.
514
+ *
515
+ * Never throws.
516
+ */
517
+ static trackLinkOpen(url: string): Promise<void>;
437
518
  /**
438
519
  * Immediately flush all queued analytics and ecommerce events to the server.
439
520
  */
@@ -444,6 +525,13 @@ declare class Tolinku {
444
525
  static get referrals(): Referrals;
445
526
  /** Deferred deep links: claimByToken, claimBySignals */
446
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;
447
535
  /**
448
536
  * Shut down the SDK and release resources.
449
537
  * Flushes remaining analytics events, cancels timers, removes listeners,
@@ -481,4 +569,4 @@ declare function TolinkuMessages({ trigger, triggerValue, onDismiss, onButtonPre
481
569
  */
482
570
  declare function isSafeUrl(url: string): boolean;
483
571
 
484
- 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.4.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
  /**
@@ -434,6 +483,38 @@ declare class Tolinku {
434
483
  * Events are batched and flushed automatically.
435
484
  */
436
485
  static track(eventType: string, properties?: TrackProperties): Promise<void>;
486
+ /**
487
+ * Report that a link opened the app, when it opened without the browser.
488
+ *
489
+ * A Universal Link or App Link hands the app the URL directly, so Tolinku is
490
+ * never contacted and the tap goes unrecorded. Those taps come from people who
491
+ * already have your app, so leaving them out makes a re-engagement campaign
492
+ * look like a failure exactly when it worked.
493
+ *
494
+ * Both ways a link arrives need it. The listener fires only while the app is
495
+ * already running, so a link that launched the app cold arrives separately:
496
+ *
497
+ * ```ts
498
+ * // Launched by a link, app was not running.
499
+ * const initial = await Linking.getInitialURL();
500
+ * if (initial) Tolinku.trackLinkOpen(initial);
501
+ *
502
+ * // Tapped while the app was already open.
503
+ * Linking.addEventListener('url', ({ url }) => {
504
+ * Tolinku.trackLinkOpen(url);
505
+ * // your own routing
506
+ * });
507
+ * ```
508
+ *
509
+ * Wiring both is safe: the same link arriving twice in quick succession is
510
+ * reported once.
511
+ *
512
+ * Only http and https links are reported. A custom scheme means Tolinku's own
513
+ * hand-off page opened the app, and that tap is already counted.
514
+ *
515
+ * Never throws.
516
+ */
517
+ static trackLinkOpen(url: string): Promise<void>;
437
518
  /**
438
519
  * Immediately flush all queued analytics and ecommerce events to the server.
439
520
  */
@@ -444,6 +525,13 @@ declare class Tolinku {
444
525
  static get referrals(): Referrals;
445
526
  /** Deferred deep links: claimByToken, claimBySignals */
446
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;
447
535
  /**
448
536
  * Shut down the SDK and release resources.
449
537
  * Flushes remaining analytics events, cancels timers, removes listeners,
@@ -481,4 +569,4 @@ declare function TolinkuMessages({ trigger, triggerValue, onDismiss, onButtonPre
481
569
  */
482
570
  declare function isSafeUrl(url: string): boolean;
483
571
 
484
- 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.4.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, {
@@ -253,12 +272,33 @@ function validateEventType(eventType) {
253
272
  var BATCH_SIZE = 10;
254
273
  var FLUSH_INTERVAL_MS = 5e3;
255
274
  var MAX_QUEUE_SIZE = 1e3;
256
- var Analytics = class {
275
+ var _Analytics = class _Analytics {
257
276
  constructor(client) {
258
277
  this.queue = [];
259
278
  this.flushTimer = null;
260
279
  this.appStateSubscription = null;
261
280
  this.isFlushing = false;
281
+ /**
282
+ * Track a custom event. The event is added to the internal queue
283
+ * and will be flushed automatically or when flush() is called.
284
+ *
285
+ * Event type must match /^custom\.[a-z0-9_]+$/.
286
+ * Auto-prefixes with "custom." if missing.
287
+ */
288
+ /**
289
+ * Set once the server says this Appspace does not attribute app opens, so the
290
+ * setting costs one request a launch rather than one per link.
291
+ */
292
+ this.appOpensDisabled = false;
293
+ /**
294
+ * The last link reported, and when. Cold start and the link stream can both
295
+ * deliver the same tap, depending on the plugin, so an app instrumenting both
296
+ * paths would otherwise report it twice and be billed twice. A genuine second
297
+ * tap of the same link inside this window is implausible; a duplicate delivery
298
+ * of one tap is not.
299
+ */
300
+ this.lastOpenUrl = null;
301
+ this.lastOpenAt = 0;
262
302
  this.handleAppStateChange = (state) => {
263
303
  if (state === "background" || state === "inactive") {
264
304
  this.flush().catch(() => {
@@ -272,12 +312,51 @@ var Analytics = class {
272
312
  );
273
313
  }
274
314
  /**
275
- * Track a custom event. The event is added to the internal queue
276
- * and will be flushed automatically or when flush() is called.
315
+ * Report that a link opened the app without the browser being involved.
316
+ *
317
+ * A Universal Link or App Link hands the app the URL directly, so Tolinku is
318
+ * never contacted and the tap goes unrecorded. Those taps come from people who
319
+ * already have the app, so leaving them out makes a re-engagement campaign
320
+ * look like a failure exactly when it worked.
321
+ *
322
+ * Only http and https links are reported. A custom scheme means Tolinku's own
323
+ * hand-off page opened the app, and that tap was counted when the page was
324
+ * served, so passing one does nothing rather than counting it twice.
277
325
  *
278
- * Event type must match /^custom\.[a-z0-9_]+$/.
279
- * Auto-prefixes with "custom." if missing.
326
+ * Never throws. This runs on the path that routes the user somewhere, and a
327
+ * tap that goes unrecorded is not worth interrupting that.
280
328
  */
329
+ async trackLinkOpen(url, userId) {
330
+ if (this.appOpensDisabled) return;
331
+ const trimmed = typeof url === "string" ? url.trim() : "";
332
+ if (!trimmed) return;
333
+ let parsed;
334
+ try {
335
+ parsed = new URL(trimmed);
336
+ } catch {
337
+ return;
338
+ }
339
+ if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return;
340
+ const now = Date.now();
341
+ if (this.lastOpenUrl === trimmed && now - this.lastOpenAt < _Analytics.OPEN_DEDUPE_MS) return;
342
+ this.lastOpenUrl = trimmed;
343
+ this.lastOpenAt = now;
344
+ try {
345
+ const result = await this.client.postPublic(
346
+ "/v1/api/opens",
347
+ {
348
+ url: trimmed,
349
+ // The User-Agent cannot say which platform this is: this SDK
350
+ // identifies itself the same way on both. Without it an app open has
351
+ // no platform and lands in a blank bucket on every breakdown.
352
+ platform: reactNative.Platform.OS === "ios" || reactNative.Platform.OS === "android" ? reactNative.Platform.OS : void 0,
353
+ ...userId ? { user_id: userId } : {}
354
+ }
355
+ );
356
+ if (result?.attribute === false) this.appOpensDisabled = true;
357
+ } catch {
358
+ }
359
+ }
281
360
  async track(eventType, properties) {
282
361
  const normalizedType = validateEventType(eventType);
283
362
  const event = {
@@ -353,6 +432,8 @@ var Analytics = class {
353
432
  }
354
433
  }
355
434
  };
435
+ _Analytics.OPEN_DEDUPE_MS = 5e3;
436
+ var Analytics = _Analytics;
356
437
  var BATCH_SIZE2 = 10;
357
438
  var FLUSH_INTERVAL_MS2 = 5e3;
358
439
  var MAX_QUEUE_SIZE2 = 500;
@@ -747,17 +828,17 @@ var Deferred = class {
747
828
  async attemptSignals(options) {
748
829
  try {
749
830
  const { width, height } = reactNative.Dimensions.get("screen");
750
- const resolvedTimezone = options.timezone || Intl.DateTimeFormat().resolvedOptions().timeZone;
751
- const resolvedLanguage = options.language || (typeof Intl !== "undefined" && typeof Intl.DateTimeFormat === "function" ? Intl.DateTimeFormat().resolvedOptions().locale : void 0) || "en";
831
+ const resolvedTimezone = override(options.timezone) || Intl.DateTimeFormat().resolvedOptions().timeZone;
832
+ const resolvedLanguage = override(options.language) || (typeof Intl !== "undefined" && typeof Intl.DateTimeFormat === "function" ? Intl.DateTimeFormat().resolvedOptions().locale : void 0) || "en";
752
833
  const link = await this.client.postPublic("/v1/api/deferred/claim-by-signals", {
753
834
  appspace_id: options.appspaceId,
754
835
  timezone: resolvedTimezone,
755
836
  language: resolvedLanguage,
756
- screen_width: options.screenWidth || width,
757
- screen_height: options.screenHeight || height,
837
+ screen_width: override(options.screenWidth) || width,
838
+ screen_height: override(options.screenHeight) || height,
758
839
  // Separates devices reporting identical dp dimensions.
759
- device_pixel_ratio: options.devicePixelRatio || reactNative.PixelRatio.get(),
760
- os_version: options.osVersion || String(reactNative.Platform.Version)
840
+ device_pixel_ratio: override(options.devicePixelRatio) || reactNative.PixelRatio.get(),
841
+ os_version: override(options.osVersion) || String(reactNative.Platform.Version)
761
842
  });
762
843
  return { link, settled: true };
763
844
  } catch (err) {
@@ -777,6 +858,61 @@ var Deferred = class {
777
858
  }
778
859
  }
779
860
  };
861
+ function override(value) {
862
+ if (typeof value === "string") {
863
+ const trimmed = value.trim();
864
+ return trimmed === "" ? void 0 : trimmed;
865
+ }
866
+ if (typeof value === "number") {
867
+ return Number.isFinite(value) && value > 0 ? value : void 0;
868
+ }
869
+ return void 0;
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
+ };
780
916
  var BASE_KEY = "tolinku_message_dismissed";
781
917
  var IMPRESSIONS_BASE_KEY = "tolinku_message_impressions";
782
918
  var LAST_SHOWN_BASE_KEY = "tolinku_message_last_shown";
@@ -900,6 +1036,7 @@ var _Tolinku = class _Tolinku {
900
1036
  _Tolinku.ecommerceInstance = new Ecommerce(_Tolinku.client, () => _Tolinku._userId);
901
1037
  _Tolinku.referralsInstance = new Referrals(_Tolinku.client);
902
1038
  _Tolinku.deferredInstance = new Deferred(_Tolinku.client);
1039
+ _Tolinku.linksInstance = new Links(_Tolinku.client);
903
1040
  _Tolinku._initialized = true;
904
1041
  debugLog(`Tolinku SDK v${SDK_VERSION} initialized (baseUrl=${baseUrl})`);
905
1042
  }
@@ -937,6 +1074,41 @@ var _Tolinku = class _Tolinku {
937
1074
  const mergedProps = _Tolinku._userId ? { user_id: _Tolinku._userId, ...properties } : properties;
938
1075
  return _Tolinku.analyticsInstance.track(eventType, mergedProps);
939
1076
  }
1077
+ /**
1078
+ * Report that a link opened the app, when it opened without the browser.
1079
+ *
1080
+ * A Universal Link or App Link hands the app the URL directly, so Tolinku is
1081
+ * never contacted and the tap goes unrecorded. Those taps come from people who
1082
+ * already have your app, so leaving them out makes a re-engagement campaign
1083
+ * look like a failure exactly when it worked.
1084
+ *
1085
+ * Both ways a link arrives need it. The listener fires only while the app is
1086
+ * already running, so a link that launched the app cold arrives separately:
1087
+ *
1088
+ * ```ts
1089
+ * // Launched by a link, app was not running.
1090
+ * const initial = await Linking.getInitialURL();
1091
+ * if (initial) Tolinku.trackLinkOpen(initial);
1092
+ *
1093
+ * // Tapped while the app was already open.
1094
+ * Linking.addEventListener('url', ({ url }) => {
1095
+ * Tolinku.trackLinkOpen(url);
1096
+ * // your own routing
1097
+ * });
1098
+ * ```
1099
+ *
1100
+ * Wiring both is safe: the same link arriving twice in quick succession is
1101
+ * reported once.
1102
+ *
1103
+ * Only http and https links are reported. A custom scheme means Tolinku's own
1104
+ * hand-off page opened the app, and that tap is already counted.
1105
+ *
1106
+ * Never throws.
1107
+ */
1108
+ static async trackLinkOpen(url) {
1109
+ if (!_Tolinku.analyticsInstance) return;
1110
+ return _Tolinku.analyticsInstance.trackLinkOpen(url, _Tolinku._userId ?? void 0);
1111
+ }
940
1112
  /**
941
1113
  * Immediately flush all queued analytics and ecommerce events to the server.
942
1114
  */
@@ -970,6 +1142,18 @@ var _Tolinku = class _Tolinku {
970
1142
  }
971
1143
  return _Tolinku.deferredInstance;
972
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
+ }
973
1157
  /**
974
1158
  * Shut down the SDK and release resources.
975
1159
  * Flushes remaining analytics events, cancels timers, removes listeners,
@@ -993,6 +1177,7 @@ var _Tolinku = class _Tolinku {
993
1177
  _Tolinku.ecommerceInstance = null;
994
1178
  _Tolinku.referralsInstance = null;
995
1179
  _Tolinku.deferredInstance = null;
1180
+ _Tolinku.linksInstance = null;
996
1181
  _Tolinku._initialized = false;
997
1182
  _Tolinku._userId = null;
998
1183
  setDebugEnabled(false);
@@ -1004,6 +1189,7 @@ _Tolinku.analyticsInstance = null;
1004
1189
  _Tolinku.ecommerceInstance = null;
1005
1190
  _Tolinku.referralsInstance = null;
1006
1191
  _Tolinku.deferredInstance = null;
1192
+ _Tolinku.linksInstance = null;
1007
1193
  _Tolinku._initialized = false;
1008
1194
  _Tolinku._userId = null;
1009
1195
  var Tolinku = _Tolinku;
@@ -1071,13 +1257,14 @@ function PuckComponentRenderer({ component, messageId, options }) {
1071
1257
  case "Button": {
1072
1258
  const handlePress = () => {
1073
1259
  const action = props.action || "";
1260
+ if (!action) return;
1261
+ if (!isSafeUrl(action)) {
1262
+ debugWarn(`Button action URL blocked (unsafe protocol): ${action}`);
1263
+ return;
1264
+ }
1074
1265
  if (options.onButtonPress) {
1075
1266
  options.onButtonPress(action, messageId);
1076
- } else if (action) {
1077
- if (!isSafeUrl(action)) {
1078
- debugWarn(`Button action URL blocked (unsafe protocol): ${action}`);
1079
- return;
1080
- }
1267
+ } else {
1081
1268
  reactNative.Linking.openURL(action).catch(() => {
1082
1269
  });
1083
1270
  }