@sendoracloud/sdk-react-native 0.15.0 → 0.16.0

package/dist/index.d.cts

@@ -305,35 +305,62 @@ declare class Auth {
 }
 
 /**
- * Sendora Deep Links surface for React Native.
+ * Sendora Deep Links surface for React Native (s58.50 — Pulse DX rewrite).
  *
- * Three core moves:
- *   1. `create(...)`            — mint a Sendora short link from inside the app
- *                                  (Pulse-style "share article" UX).
- *   2. `handleUniversalLink(url)` — call when iOS / Android delivers a Universal
- *                                  Link or App Link to the app. SDK resolves the
- *                                  shortcode against backend and fires
- *                                  `onLinkOpened` with the link's `linkData`.
- *   3. `matchDeferred({ ... })`  — call once on cold launch after install. If the
- *                                  device fingerprint OR Android Play Install
- *                                  Referrer match a recent click, SDK fires
- *                                  `onLinkOpened` with `isDeferred: true`.
+ * Surface:
+ *   1. `create<T>(...)`             — mint a Sendora short link from inside the app.
+ *   2. `prewarm<T>(...)`            — background-mint + cache so share row taps
+ *                                     skip the HTTPS round-trip ActivityIndicator.
+ *   3. `handleUniversalLink(url)`   — resolve a delivered universal / app link
+ *                                     and fire `onLinkOpened`.
+ *   4. `matchDeferred({ ... })`     — cold-launch deferred match.
+ *   5. `attachLinkingApi({ ... })`  — one-call replacement for the
+ *                                     `Linking.getInitialURL` + `addEventListener`
+ *                                     + extract-pre-check + fallthrough boilerplate.
+ *   6. `computeDeviceFingerprint()` — canonical recipe (matches iOS + Android),
+ *                                     no client-side boilerplate required.
+ *   7. `revoke(shortcode)`          — soft-delete (private-content unsend).
+ *   8. `getStats(shortcode)`        — totals + breakdowns; no dashboard scraping.
+ *   9. `onLinkOpened<T>(cb)`        — generic-typed handler.
+ *  10. `LinkError`                  — typed errors with codes
+ *                                     (`instanceof` + `err.code` rather than
+ *                                     `err.message.includes(...)`).
  *
- * The host app supplies the iOS bundle id / Android package via `init()` of
- * the main SDK, OR per-call. Sendora-side `apps` table is the source of
- * truth — a leaked public key + wrong bundle = 400 from the backend.
+ * Bundle-id gate: SDK auto-supplies `iosBundleId` / `androidPackageName`
+ * from `init()` config — host app never has to thread them through per call.
+ * Sendora-side `apps` table is the source of truth — a leaked public key
+ * + wrong bundle = 422 from the backend mapped to
+ * `LinkError(code: "BUNDLE_MISMATCH")` here.
  */
-interface LinkCreateInput {
+/**
+ * Error code taxonomy. Mirrors `apps/backend/src/modules/links/*` outcomes.
+ * Callers branch on `err.code` (string compare) or `err instanceof LinkError`.
+ */
+type LinkErrorCode = "BUNDLE_MISMATCH" | "DATA_TOO_LARGE" | "EXPIRED" | "NETWORK" | "RATE_LIMITED" | "NOT_FOUND" | "UNAUTHORIZED" | "INVALID_INPUT" | "PLAN_LIMIT" | "FALLBACK_REQUIRED" | "SERVER" | "UNKNOWN";
+declare class LinkError extends Error {
+    readonly code: LinkErrorCode;
+    readonly statusCode: number;
+    readonly details?: unknown;
+    constructor(code: LinkErrorCode, message: string, statusCode?: number, details?: unknown);
+}
+/** Default linkData shape — opaque record. Override with a discriminated
+ *  union or product-specific interface in the host app for full type-safety. */
+type LinkData = Record<string, unknown>;
+interface LinkCreateInput<T extends LinkData = LinkData> {
     /** Customer-facing title. Shown in dashboard list views. */
     title: string;
     /** In-app deep-link path the host app routes to (e.g. `/articles/123`). */
     iosDeepLinkPath?: string;
     /** In-app deep-link path the host app routes to (e.g. `/articles/123`). */
     androidDeepLinkPath?: string;
-    /** Web fallback URL — shown when app is not installed + Play Store fallback. */
-    fallbackUrl: string;
-    /** Custom JSON delivered to onLinkOpened. Max 2KB serialized. */
-    linkData?: Record<string, unknown>;
+    /**
+     * Web fallback URL. **Optional as of 0.16.0** — backend defaults from
+     * the project's apps registry (web origin > iOS App Store URL > Android
+     * Play Store URL). Pass explicitly for per-link override.
+     */
+    fallbackUrl?: string;
+    /** Custom typed JSON delivered to onLinkOpened. Max 2KB serialized. */
+    linkData?: T;
     /** Optional OG preview overrides for richer share cards. */
     ogTitle?: string;
     ogDescription?: string;
@@ -344,72 +371,130 @@ interface LinkCreateInput {
     medium?: string;
     channel?: string;
     tags?: string[];
-    /** ISO timestamp when the link stops resolving. */
+    /** ISO timestamp when the link stops resolving. Must be future + within 5y. */
     expiresAt?: string;
-    /** Bundle ID / package name for the bundle-id gate. */
+    /** Bundle ID / package name for the bundle-id gate. Defaults from init. */
     iosBundleId?: string;
     androidPackageName?: string;
 }
-interface LinkCreateResult {
+interface LinkCreateResult<T extends LinkData = LinkData> {
     id: string;
     shortcode: string;
-    /** Fully qualified share URL — what you pass to RN `Share.share({ message: ... })`. */
+    /** Fully qualified share URL — pass to RN `Share.share({ message: ... })`. */
     url: string;
     iosDeepLinkPath: string | null;
     androidDeepLinkPath: string | null;
     fallbackUrl: string;
-    linkData: Record<string, unknown>;
+    linkData: T;
     expiresAt: string | null;
 }
-interface LinkOpenedEvent {
+interface LinkOpenedEvent<T extends LinkData = LinkData> {
     shortcode: string;
-    /** Custom JSON the link was created with. Pulse navigates off `articleId` here. */
-    linkData: Record<string, unknown>;
-    /** Server's iOS deep-link path. Useful when host app's URL parser needs a hint. */
+    /** Custom typed JSON the link was created with. */
+    linkData: T;
     iosDeepLinkPath: string | null;
-    /** Server's Android deep-link path. */
     androidDeepLinkPath: string | null;
-    /**
-     * `true` when this event came from the deferred deep link path —
-     * i.e. user installed the app from the App / Play Store after
-     * clicking the link, and the SDK matched their fingerprint /
-     * install-referrer to the prior click.
-     */
+    /** `true` when this event came from the deferred deep link path. */
     isDeferred: boolean;
 }
-type LinkOpenedHandler = (event: LinkOpenedEvent) => void;
+type LinkOpenedHandler<T extends LinkData = LinkData> = (event: LinkOpenedEvent<T>) => void;
 interface LinkMatchInput {
-    /** Hex-encoded SHA-256 of (ip + ua + screen + tz + locale). Pre-hashed by caller. */
+    /** Hex-encoded SHA-256 — pass output of `computeDeviceFingerprint()`. */
     fingerprintHash?: string;
-    /** Raw Play Install Referrer (`PlayInstallReferrerClient.getInstallReferrer().installReferrer`). */
+    /** Raw Play Install Referrer. Sendora probes
+     *  `react-native-play-install-referrer` automatically when this is omitted. */
     installReferrer?: string;
     iosBundleId?: string;
     androidPackageName?: string;
 }
+interface LinkStats {
+    totalClicks: number;
+    uniqueClicks: number;
+    deferredMatches: number;
+    byDevice: Array<{
+        deviceType: string | null;
+        count: number;
+    }>;
+    byCountry: Array<{
+        country: string | null;
+        count: number;
+    }>;
+    byOs: Array<{
+        os: string | null;
+        count: number;
+    }>;
+}
+/**
+ * Extract a Sendora shortcode from a URL.
+ *
+ * - When `linkDomain` is supplied, only matches URLs whose host equals it
+ *   (or is a subdomain) — prevents firing `handleUniversalLink` on unrelated
+ *   inbound URLs from other deep-link providers.
+ * - When omitted, host-agnostic (matches any tail segment that looks like a
+ *   shortcode — back-compat with 0.15.x).
+ * - Accepts both `https://<host>/<shortcode>` and `https://<host>/link/<shortcode>`.
+ */
+declare function extractShortcodeFromUrl(url: string, linkDomain?: string): string | null;
 /**
- * Extract a Sendora shortcode from a universal link URL. Accepts either:
- *  - https://go.sendoracloud.com/<shortcode>
- *  - https://go.sendoracloud.com/link/<shortcode>   (Worker rewrites this path)
- *  - any custom host the customer pointed at the Sendora Worker (lookup by tail
- *    segment matches `SHORTCODE_RE`).
+ * Canonical device-fingerprint recipe. Identical byte-for-byte across the
+ * RN / iOS / Android SDKs so a click logged from one platform and an
+ * install completing on another won't accidentally match.
+ *
+ * Input: `${platform}|${screenW}x${screenH}|${timezone}|${locale}`
+ * Output: lowercase hex SHA-256.
  */
-declare function extractShortcodeFromUrl(url: string): string | null;
+declare function computeDeviceFingerprint(): Promise<string>;
+/** Probe optional `react-native-play-install-referrer` peer. Returns the
+ *  raw referrer string (which Play passes Sendora's `?sd_sc=<shortcode>`
+ *  inside) when the peer is installed, or `null` when not. Safe to call
+ *  on iOS — returns null. */
+declare function getPlayInstallReferrer(): Promise<string | null>;
+interface AttachLinkingApiOptions {
+    /** Called with URLs that aren't Sendora-shaped so the host app can hand
+     *  them to its existing router (other deep-link providers, OAuth callbacks,
+     *  etc). */
+    onLegacyUrl?: (url: string) => void;
+}
 interface LinksDeps {
     apiUrl: string;
     publicKey: string;
     debug: boolean;
     iosBundleId?: string;
     androidPackageName?: string;
+    /** Custom share domain (e.g. `pulse.link`). Used by `attachLinkingApi` to
+     *  filter Sendora vs legacy URLs. When unset, falls back to the default
+     *  Sendora host pattern (host-agnostic — any URL whose tail looks like a
+     *  shortcode is treated as Sendora). */
+    linkDomain?: string;
 }
 declare class Links {
     private deps;
     private listeners;
+    private prewarmCache;
+    private linkingSub;
     constructor(deps: LinksDeps);
-    /** Register a callback for warm + deferred deep-link opens. Returns unsubscribe fn. */
-    onLinkOpened(handler: LinkOpenedHandler): () => void;
+    /** Register a callback for warm + deferred deep-link opens. Returns
+     *  unsubscribe fn. Generic `T` lets callers type `linkData` per-app. */
+    onLinkOpened<T extends LinkData = LinkData>(handler: LinkOpenedHandler<T>): () => void;
     private emit;
-    /** Mint a new short link. Returns the share URL + shortcode. */
-    create(input: LinkCreateInput): Promise<LinkCreateResult>;
+    /** Stable cache key. Customer can override per call with `opts.key`. */
+    private cacheKey;
+    private evictExpired;
+    /**
+     * Background-mint a link + cache the promise so a subsequent `create()`
+     * with the same input (or matching `key`) returns instantly.
+     *
+     * Fire-and-forget. Errors are swallowed; the matching `create()` call
+     * will surface them on demand instead.
+     */
+    prewarm<T extends LinkData = LinkData>(input: LinkCreateInput<T>, opts?: {
+        key?: string;
+    }): void;
+    /** Mint a new short link. Uses prewarm cache when the input matches. */
+    create<T extends LinkData = LinkData>(input: LinkCreateInput<T>, opts?: {
+        key?: string;
+    }): Promise<LinkCreateResult<T>>;
+    private doCreate;
     /**
      * Warm-path: app received a universal/app-link delivery. Resolves the
      * shortcode against the backend and fires `onLinkOpened`. No-op (and
@@ -417,14 +502,41 @@ declare class Links {
      */
     handleUniversalLink(url: string): Promise<boolean>;
     /**
-     * Cold-launch deferred deep link match. Pass the Android Play Install
-     * Referrer string (preferred — 100% accurate) and/or a precomputed
-     * fingerprint hash (iOS — probabilistic).
+     * Cold-launch deferred deep link match. When neither `fingerprintHash` nor
+     * `installReferrer` is supplied, the SDK auto-discovers:
+     *   - Android: probes `react-native-play-install-referrer` (preferred — 100%
+     *     accurate when present).
+     *   - Otherwise: computes the canonical device fingerprint hash.
+     *
+     * Fires `onLinkOpened` with `isDeferred: true` on success.
+     */
+    matchDeferred(input?: LinkMatchInput): Promise<LinkOpenedEvent<LinkData> | null>;
+    /** Soft-delete a link. Idempotent — repeated calls succeed. */
+    revoke(shortcode: string): Promise<{
+        shortcode: string;
+        revoked: true;
+    }>;
+    /** Click totals + breakdowns for a link the SDK owns. */
+    getStats(shortcode: string): Promise<LinkStats>;
+    /**
+     * One-call replacement for the standard cold + warm URL boilerplate:
+     *
+     *     const detach = await sendora.links.attachLinkingApi({
+     *       onLegacyUrl: (url) => myRouter.handle(url),
+     *     });
+     *     // …later in unmount:
+     *     detach();
      *
-     * SDK fires `onLinkOpened` with `isDeferred: true` on success.
-     * Returns the event payload on match, `null` on no match.
+     * Internally:
+     *   - Reads `Linking.getInitialURL()` once.
+     *   - Subscribes to `Linking.addEventListener('url', …)`.
+     *   - For each URL: checks `extractShortcodeFromUrl(url, linkDomain)`.
+     *     Sendora-shaped → calls `handleUniversalLink`.
+     *     Otherwise → forwards to `onLegacyUrl` (if supplied).
+     *
+     * Idempotent: re-attaching while a subscription is active replaces it.
      */
-    matchDeferred(input: LinkMatchInput): Promise<LinkOpenedEvent | null>;
+    attachLinkingApi(opts?: AttachLinkingApiOptions): Promise<() => void>;
 }
 
 interface SendoraConfig {
@@ -492,6 +604,14 @@ interface SendoraConfig {
      * `iosBundleId` above.
      */
     androidPackageName?: string;
+    /**
+     * Optional share-link host (e.g. `pulse.link`). When set, the deep
+     * links module's URL extractor only treats Sendora-routed URLs whose
+     * host matches this domain (or a subdomain). Leave unset on apps that
+     * use the default Sendora-hosted share domain (`go.sendoracloud.com`).
+     * Added 0.16.0.
+     */
+    linkDomain?: string;
 }
 type TraitValue = string | number | boolean | null | undefined;
 interface IdentifyTraits {
@@ -612,4 +732,4 @@ declare class SendoraSDK {
 }
 declare const SendoraCloud: SendoraSDK;
 
-export { Auth, AuthError, type AuthTokens, type AuthUser, EmailAlreadyTakenError, type IdentifyTraits, type LinkCreateInput, type LinkCreateResult, type LinkMatchInput, type LinkOpenedEvent, type LinkOpenedHandler, Links, type PushTokenReceipt, type PushTokenRegistration, SendoraCloud, type SendoraConfig, type TrackProperties, SendoraCloud as default, extractShortcodeFromUrl };
+export { type AttachLinkingApiOptions, Auth, AuthError, type AuthTokens, type AuthUser, EmailAlreadyTakenError, type IdentifyTraits, type LinkCreateInput, type LinkCreateResult, type LinkData, LinkError, type LinkErrorCode, type LinkMatchInput, type LinkOpenedEvent, type LinkOpenedHandler, type LinkStats, Links, type PushTokenReceipt, type PushTokenRegistration, SendoraCloud, type SendoraConfig, type TrackProperties, computeDeviceFingerprint, SendoraCloud as default, extractShortcodeFromUrl, getPlayInstallReferrer };

package/dist/index.d.ts

@@ -305,35 +305,62 @@ declare class Auth {
 }
 
 /**
- * Sendora Deep Links surface for React Native.
+ * Sendora Deep Links surface for React Native (s58.50 — Pulse DX rewrite).
  *
- * Three core moves:
- *   1. `create(...)`            — mint a Sendora short link from inside the app
- *                                  (Pulse-style "share article" UX).
- *   2. `handleUniversalLink(url)` — call when iOS / Android delivers a Universal
- *                                  Link or App Link to the app. SDK resolves the
- *                                  shortcode against backend and fires
- *                                  `onLinkOpened` with the link's `linkData`.
- *   3. `matchDeferred({ ... })`  — call once on cold launch after install. If the
- *                                  device fingerprint OR Android Play Install
- *                                  Referrer match a recent click, SDK fires
- *                                  `onLinkOpened` with `isDeferred: true`.
+ * Surface:
+ *   1. `create<T>(...)`             — mint a Sendora short link from inside the app.
+ *   2. `prewarm<T>(...)`            — background-mint + cache so share row taps
+ *                                     skip the HTTPS round-trip ActivityIndicator.
+ *   3. `handleUniversalLink(url)`   — resolve a delivered universal / app link
+ *                                     and fire `onLinkOpened`.
+ *   4. `matchDeferred({ ... })`     — cold-launch deferred match.
+ *   5. `attachLinkingApi({ ... })`  — one-call replacement for the
+ *                                     `Linking.getInitialURL` + `addEventListener`
+ *                                     + extract-pre-check + fallthrough boilerplate.
+ *   6. `computeDeviceFingerprint()` — canonical recipe (matches iOS + Android),
+ *                                     no client-side boilerplate required.
+ *   7. `revoke(shortcode)`          — soft-delete (private-content unsend).
+ *   8. `getStats(shortcode)`        — totals + breakdowns; no dashboard scraping.
+ *   9. `onLinkOpened<T>(cb)`        — generic-typed handler.
+ *  10. `LinkError`                  — typed errors with codes
+ *                                     (`instanceof` + `err.code` rather than
+ *                                     `err.message.includes(...)`).
  *
- * The host app supplies the iOS bundle id / Android package via `init()` of
- * the main SDK, OR per-call. Sendora-side `apps` table is the source of
- * truth — a leaked public key + wrong bundle = 400 from the backend.
+ * Bundle-id gate: SDK auto-supplies `iosBundleId` / `androidPackageName`
+ * from `init()` config — host app never has to thread them through per call.
+ * Sendora-side `apps` table is the source of truth — a leaked public key
+ * + wrong bundle = 422 from the backend mapped to
+ * `LinkError(code: "BUNDLE_MISMATCH")` here.
  */
-interface LinkCreateInput {
+/**
+ * Error code taxonomy. Mirrors `apps/backend/src/modules/links/*` outcomes.
+ * Callers branch on `err.code` (string compare) or `err instanceof LinkError`.
+ */
+type LinkErrorCode = "BUNDLE_MISMATCH" | "DATA_TOO_LARGE" | "EXPIRED" | "NETWORK" | "RATE_LIMITED" | "NOT_FOUND" | "UNAUTHORIZED" | "INVALID_INPUT" | "PLAN_LIMIT" | "FALLBACK_REQUIRED" | "SERVER" | "UNKNOWN";
+declare class LinkError extends Error {
+    readonly code: LinkErrorCode;
+    readonly statusCode: number;
+    readonly details?: unknown;
+    constructor(code: LinkErrorCode, message: string, statusCode?: number, details?: unknown);
+}
+/** Default linkData shape — opaque record. Override with a discriminated
+ *  union or product-specific interface in the host app for full type-safety. */
+type LinkData = Record<string, unknown>;
+interface LinkCreateInput<T extends LinkData = LinkData> {
     /** Customer-facing title. Shown in dashboard list views. */
     title: string;
     /** In-app deep-link path the host app routes to (e.g. `/articles/123`). */
     iosDeepLinkPath?: string;
     /** In-app deep-link path the host app routes to (e.g. `/articles/123`). */
     androidDeepLinkPath?: string;
-    /** Web fallback URL — shown when app is not installed + Play Store fallback. */
-    fallbackUrl: string;
-    /** Custom JSON delivered to onLinkOpened. Max 2KB serialized. */
-    linkData?: Record<string, unknown>;
+    /**
+     * Web fallback URL. **Optional as of 0.16.0** — backend defaults from
+     * the project's apps registry (web origin > iOS App Store URL > Android
+     * Play Store URL). Pass explicitly for per-link override.
+     */
+    fallbackUrl?: string;
+    /** Custom typed JSON delivered to onLinkOpened. Max 2KB serialized. */
+    linkData?: T;
     /** Optional OG preview overrides for richer share cards. */
     ogTitle?: string;
     ogDescription?: string;
@@ -344,72 +371,130 @@ interface LinkCreateInput {
     medium?: string;
     channel?: string;
     tags?: string[];
-    /** ISO timestamp when the link stops resolving. */
+    /** ISO timestamp when the link stops resolving. Must be future + within 5y. */
     expiresAt?: string;
-    /** Bundle ID / package name for the bundle-id gate. */
+    /** Bundle ID / package name for the bundle-id gate. Defaults from init. */
     iosBundleId?: string;
     androidPackageName?: string;
 }
-interface LinkCreateResult {
+interface LinkCreateResult<T extends LinkData = LinkData> {
     id: string;
     shortcode: string;
-    /** Fully qualified share URL — what you pass to RN `Share.share({ message: ... })`. */
+    /** Fully qualified share URL — pass to RN `Share.share({ message: ... })`. */
     url: string;
     iosDeepLinkPath: string | null;
     androidDeepLinkPath: string | null;
     fallbackUrl: string;
-    linkData: Record<string, unknown>;
+    linkData: T;
     expiresAt: string | null;
 }
-interface LinkOpenedEvent {
+interface LinkOpenedEvent<T extends LinkData = LinkData> {
     shortcode: string;
-    /** Custom JSON the link was created with. Pulse navigates off `articleId` here. */
-    linkData: Record<string, unknown>;
-    /** Server's iOS deep-link path. Useful when host app's URL parser needs a hint. */
+    /** Custom typed JSON the link was created with. */
+    linkData: T;
     iosDeepLinkPath: string | null;
-    /** Server's Android deep-link path. */
     androidDeepLinkPath: string | null;
-    /**
-     * `true` when this event came from the deferred deep link path —
-     * i.e. user installed the app from the App / Play Store after
-     * clicking the link, and the SDK matched their fingerprint /
-     * install-referrer to the prior click.
-     */
+    /** `true` when this event came from the deferred deep link path. */
     isDeferred: boolean;
 }
-type LinkOpenedHandler = (event: LinkOpenedEvent) => void;
+type LinkOpenedHandler<T extends LinkData = LinkData> = (event: LinkOpenedEvent<T>) => void;
 interface LinkMatchInput {
-    /** Hex-encoded SHA-256 of (ip + ua + screen + tz + locale). Pre-hashed by caller. */
+    /** Hex-encoded SHA-256 — pass output of `computeDeviceFingerprint()`. */
     fingerprintHash?: string;
-    /** Raw Play Install Referrer (`PlayInstallReferrerClient.getInstallReferrer().installReferrer`). */
+    /** Raw Play Install Referrer. Sendora probes
+     *  `react-native-play-install-referrer` automatically when this is omitted. */
     installReferrer?: string;
     iosBundleId?: string;
     androidPackageName?: string;
 }
+interface LinkStats {
+    totalClicks: number;
+    uniqueClicks: number;
+    deferredMatches: number;
+    byDevice: Array<{
+        deviceType: string | null;
+        count: number;
+    }>;
+    byCountry: Array<{
+        country: string | null;
+        count: number;
+    }>;
+    byOs: Array<{
+        os: string | null;
+        count: number;
+    }>;
+}
+/**
+ * Extract a Sendora shortcode from a URL.
+ *
+ * - When `linkDomain` is supplied, only matches URLs whose host equals it
+ *   (or is a subdomain) — prevents firing `handleUniversalLink` on unrelated
+ *   inbound URLs from other deep-link providers.
+ * - When omitted, host-agnostic (matches any tail segment that looks like a
+ *   shortcode — back-compat with 0.15.x).
+ * - Accepts both `https://<host>/<shortcode>` and `https://<host>/link/<shortcode>`.
+ */
+declare function extractShortcodeFromUrl(url: string, linkDomain?: string): string | null;
 /**
- * Extract a Sendora shortcode from a universal link URL. Accepts either:
- *  - https://go.sendoracloud.com/<shortcode>
- *  - https://go.sendoracloud.com/link/<shortcode>   (Worker rewrites this path)
- *  - any custom host the customer pointed at the Sendora Worker (lookup by tail
- *    segment matches `SHORTCODE_RE`).
+ * Canonical device-fingerprint recipe. Identical byte-for-byte across the
+ * RN / iOS / Android SDKs so a click logged from one platform and an
+ * install completing on another won't accidentally match.
+ *
+ * Input: `${platform}|${screenW}x${screenH}|${timezone}|${locale}`
+ * Output: lowercase hex SHA-256.
  */
-declare function extractShortcodeFromUrl(url: string): string | null;
+declare function computeDeviceFingerprint(): Promise<string>;
+/** Probe optional `react-native-play-install-referrer` peer. Returns the
+ *  raw referrer string (which Play passes Sendora's `?sd_sc=<shortcode>`
+ *  inside) when the peer is installed, or `null` when not. Safe to call
+ *  on iOS — returns null. */
+declare function getPlayInstallReferrer(): Promise<string | null>;
+interface AttachLinkingApiOptions {
+    /** Called with URLs that aren't Sendora-shaped so the host app can hand
+     *  them to its existing router (other deep-link providers, OAuth callbacks,
+     *  etc). */
+    onLegacyUrl?: (url: string) => void;
+}
 interface LinksDeps {
     apiUrl: string;
     publicKey: string;
     debug: boolean;
     iosBundleId?: string;
     androidPackageName?: string;
+    /** Custom share domain (e.g. `pulse.link`). Used by `attachLinkingApi` to
+     *  filter Sendora vs legacy URLs. When unset, falls back to the default
+     *  Sendora host pattern (host-agnostic — any URL whose tail looks like a
+     *  shortcode is treated as Sendora). */
+    linkDomain?: string;
 }
 declare class Links {
     private deps;
     private listeners;
+    private prewarmCache;
+    private linkingSub;
     constructor(deps: LinksDeps);
-    /** Register a callback for warm + deferred deep-link opens. Returns unsubscribe fn. */
-    onLinkOpened(handler: LinkOpenedHandler): () => void;
+    /** Register a callback for warm + deferred deep-link opens. Returns
+     *  unsubscribe fn. Generic `T` lets callers type `linkData` per-app. */
+    onLinkOpened<T extends LinkData = LinkData>(handler: LinkOpenedHandler<T>): () => void;
     private emit;
-    /** Mint a new short link. Returns the share URL + shortcode. */
-    create(input: LinkCreateInput): Promise<LinkCreateResult>;
+    /** Stable cache key. Customer can override per call with `opts.key`. */
+    private cacheKey;
+    private evictExpired;
+    /**
+     * Background-mint a link + cache the promise so a subsequent `create()`
+     * with the same input (or matching `key`) returns instantly.
+     *
+     * Fire-and-forget. Errors are swallowed; the matching `create()` call
+     * will surface them on demand instead.
+     */
+    prewarm<T extends LinkData = LinkData>(input: LinkCreateInput<T>, opts?: {
+        key?: string;
+    }): void;
+    /** Mint a new short link. Uses prewarm cache when the input matches. */
+    create<T extends LinkData = LinkData>(input: LinkCreateInput<T>, opts?: {
+        key?: string;
+    }): Promise<LinkCreateResult<T>>;
+    private doCreate;
     /**
      * Warm-path: app received a universal/app-link delivery. Resolves the
      * shortcode against the backend and fires `onLinkOpened`. No-op (and
@@ -417,14 +502,41 @@ declare class Links {
      */
     handleUniversalLink(url: string): Promise<boolean>;
     /**
-     * Cold-launch deferred deep link match. Pass the Android Play Install
-     * Referrer string (preferred — 100% accurate) and/or a precomputed
-     * fingerprint hash (iOS — probabilistic).
+     * Cold-launch deferred deep link match. When neither `fingerprintHash` nor
+     * `installReferrer` is supplied, the SDK auto-discovers:
+     *   - Android: probes `react-native-play-install-referrer` (preferred — 100%
+     *     accurate when present).
+     *   - Otherwise: computes the canonical device fingerprint hash.
+     *
+     * Fires `onLinkOpened` with `isDeferred: true` on success.
+     */
+    matchDeferred(input?: LinkMatchInput): Promise<LinkOpenedEvent<LinkData> | null>;
+    /** Soft-delete a link. Idempotent — repeated calls succeed. */
+    revoke(shortcode: string): Promise<{
+        shortcode: string;
+        revoked: true;
+    }>;
+    /** Click totals + breakdowns for a link the SDK owns. */
+    getStats(shortcode: string): Promise<LinkStats>;
+    /**
+     * One-call replacement for the standard cold + warm URL boilerplate:
+     *
+     *     const detach = await sendora.links.attachLinkingApi({
+     *       onLegacyUrl: (url) => myRouter.handle(url),
+     *     });
+     *     // …later in unmount:
+     *     detach();
      *
-     * SDK fires `onLinkOpened` with `isDeferred: true` on success.
-     * Returns the event payload on match, `null` on no match.
+     * Internally:
+     *   - Reads `Linking.getInitialURL()` once.
+     *   - Subscribes to `Linking.addEventListener('url', …)`.
+     *   - For each URL: checks `extractShortcodeFromUrl(url, linkDomain)`.
+     *     Sendora-shaped → calls `handleUniversalLink`.
+     *     Otherwise → forwards to `onLegacyUrl` (if supplied).
+     *
+     * Idempotent: re-attaching while a subscription is active replaces it.
      */
-    matchDeferred(input: LinkMatchInput): Promise<LinkOpenedEvent | null>;
+    attachLinkingApi(opts?: AttachLinkingApiOptions): Promise<() => void>;
 }
 
 interface SendoraConfig {
@@ -492,6 +604,14 @@ interface SendoraConfig {
      * `iosBundleId` above.
      */
     androidPackageName?: string;
+    /**
+     * Optional share-link host (e.g. `pulse.link`). When set, the deep
+     * links module's URL extractor only treats Sendora-routed URLs whose
+     * host matches this domain (or a subdomain). Leave unset on apps that
+     * use the default Sendora-hosted share domain (`go.sendoracloud.com`).
+     * Added 0.16.0.
+     */
+    linkDomain?: string;
 }
 type TraitValue = string | number | boolean | null | undefined;
 interface IdentifyTraits {
@@ -612,4 +732,4 @@ declare class SendoraSDK {
 }
 declare const SendoraCloud: SendoraSDK;
 
-export { Auth, AuthError, type AuthTokens, type AuthUser, EmailAlreadyTakenError, type IdentifyTraits, type LinkCreateInput, type LinkCreateResult, type LinkMatchInput, type LinkOpenedEvent, type LinkOpenedHandler, Links, type PushTokenReceipt, type PushTokenRegistration, SendoraCloud, type SendoraConfig, type TrackProperties, SendoraCloud as default, extractShortcodeFromUrl };
+export { type AttachLinkingApiOptions, Auth, AuthError, type AuthTokens, type AuthUser, EmailAlreadyTakenError, type IdentifyTraits, type LinkCreateInput, type LinkCreateResult, type LinkData, LinkError, type LinkErrorCode, type LinkMatchInput, type LinkOpenedEvent, type LinkOpenedHandler, type LinkStats, Links, type PushTokenReceipt, type PushTokenRegistration, SendoraCloud, type SendoraConfig, type TrackProperties, computeDeviceFingerprint, SendoraCloud as default, extractShortcodeFromUrl, getPlayInstallReferrer };