@sendoracloud/sdk-react-native 0.13.0 → 0.15.0

package/dist/index.cjs

@@ -33,8 +33,10 @@ __export(index_exports, {
   Auth: () => Auth,
   AuthError: () => AuthError,
   EmailAlreadyTakenError: () => EmailAlreadyTakenError,
+  Links: () => Links,
   SendoraCloud: () => SendoraCloud,
-  default: () => index_default
+  default: () => index_default,
+  extractShortcodeFromUrl: () => extractShortcodeFromUrl
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -235,21 +237,41 @@ var Auth = class {
       this.resolveReady = res;
     });
   }
-  /** Re-hydrate session from storage. Called by the parent SDK
-   *  during init() after Storage.hydrate() has run. Marks the
-   *  internal ready promise as resolved so queued auth calls
-   *  unblock. */
+  /**
+   * Re-hydrate session from storage. Called by the parent SDK during
+   * init() after Storage.hydrate() has run. Marks the internal ready
+   * promise as resolved so queued auth calls unblock.
+   *
+   * s58.47 — restore the user even when the cached ACCESS token is
+   * missing/expired, as long as USER_KEY + REFRESH_KEY are present.
+   * Pre-s58.47 this required BOTH USER_KEY and TOKEN_KEY, which
+   * caused a cold-start regression: if the access token rotated out
+   * of storage (TTL elapsed, app killed between persists, partial
+   * write, AsyncStorage eviction) the user appeared signed out even
+   * though their refresh chain was still alive in storage. Hosts
+   * then called `signInAnonymously()` on every launch and minted a
+   * fresh anon user, fragmenting analytics across sessions
+   * (Pulse News symptom). With the refresh token present, the next
+   * `getAccessToken()` call will silently refresh + restore a valid
+   * access token without disturbing identity.
+   */
   hydrate() {
     const cachedUser = this.hooks.storage.get(USER_KEY);
     const cachedToken = this.hooks.storage.get(TOKEN_KEY);
+    const cachedRefresh = this.hooks.storage.get(REFRESH_KEY);
     const cachedExpires = this.hooks.storage.get(TOKEN_EXPIRES_KEY);
-    if (cachedUser && cachedToken) {
+    if (cachedUser && (cachedToken || cachedRefresh)) {
       try {
         const parsed = JSON.parse(cachedUser);
         if (typeof parsed.id !== "string" || parsed.id.length === 0) throw new Error("invalid cache");
         this.user = parsed;
-        this.accessToken = cachedToken;
-        this.accessExpiresAt = cachedExpires ? Number(cachedExpires) : 0;
+        if (cachedToken) {
+          this.accessToken = cachedToken;
+          this.accessExpiresAt = cachedExpires ? Number(cachedExpires) : 0;
+        } else {
+          this.accessToken = null;
+          this.accessExpiresAt = 0;
+        }
         this.hooks.onIdentityChange(this.user.id);
       } catch {
         this.hooks.storage.remove(USER_KEY);
@@ -821,6 +843,155 @@ function decodeJwtPayload(token) {
   }
 }
 
+// src/links.ts
+async function unwrap(res, ctx) {
+  if (!res) throw new Error(`[sendoracloud] ${ctx}: network error`);
+  if (!res.ok) {
+    let msg = `HTTP ${res.status}`;
+    try {
+      const parsed2 = await res.clone().json();
+      if (parsed2.error?.code || parsed2.error?.message) {
+        msg = `${parsed2.error.code ?? ""}${parsed2.error.code && parsed2.error.message ? ": " : ""}${parsed2.error.message ?? ""}`;
+      }
+    } catch {
+    }
+    throw new Error(`[sendoracloud] ${ctx}: ${msg}`);
+  }
+  const parsed = await res.json();
+  return parsed.data ?? null;
+}
+var SHORTCODE_RE = /^[a-z0-9-]{3,20}$/;
+function extractShortcodeFromUrl(url) {
+  try {
+    const u = new URL(url);
+    const segs = u.pathname.split("/").filter(Boolean);
+    if (segs.length === 0) return null;
+    const tail = segs[segs.length - 1];
+    return SHORTCODE_RE.test(tail) ? tail : null;
+  } catch {
+    return null;
+  }
+}
+var Links = class {
+  constructor(deps) {
+    this.deps = deps;
+    this.listeners = [];
+  }
+  /** Register a callback for warm + deferred deep-link opens. Returns unsubscribe fn. */
+  onLinkOpened(handler) {
+    this.listeners.push(handler);
+    return () => {
+      const idx = this.listeners.indexOf(handler);
+      if (idx >= 0) this.listeners.splice(idx, 1);
+    };
+  }
+  emit(event) {
+    for (const fn of this.listeners) {
+      try {
+        fn(event);
+      } catch (err) {
+        if (this.deps.debug) console.warn("[sendoracloud] onLinkOpened handler threw:", err);
+      }
+    }
+  }
+  /** Mint a new short link. Returns the share URL + shortcode. */
+  async create(input) {
+    if (!input.title) throw new Error("[sendoracloud] links.create: title is required");
+    if (!input.fallbackUrl) throw new Error("[sendoracloud] links.create: fallbackUrl is required");
+    const body = { title: input.title, fallbackUrl: input.fallbackUrl };
+    if (input.iosDeepLinkPath) body.iosDeepLinkPath = input.iosDeepLinkPath;
+    if (input.androidDeepLinkPath) body.androidDeepLinkPath = input.androidDeepLinkPath;
+    if (input.linkData) body.linkData = input.linkData;
+    if (input.ogTitle) body.ogTitle = input.ogTitle;
+    if (input.ogDescription) body.ogDescription = input.ogDescription;
+    if (input.ogImageUrl) body.ogImageUrl = input.ogImageUrl;
+    if (input.campaign) body.campaign = input.campaign;
+    if (input.source) body.source = input.source;
+    if (input.medium) body.medium = input.medium;
+    if (input.channel) body.channel = input.channel;
+    if (input.tags) body.tags = input.tags;
+    if (input.expiresAt) body.expiresAt = input.expiresAt;
+    const ios = input.iosBundleId ?? this.deps.iosBundleId;
+    const android = input.androidPackageName ?? this.deps.androidPackageName;
+    if (ios) body.iosBundleId = ios;
+    if (android) body.androidPackageName = android;
+    const res = await post(
+      { apiUrl: this.deps.apiUrl, publicKey: this.deps.publicKey, debug: this.deps.debug },
+      "/api/v1/sdk/links",
+      body
+    );
+    const data = await unwrap(res, "links.create");
+    if (!data?.shortcode) {
+      throw new Error("[sendoracloud] links.create returned no shortcode");
+    }
+    return data;
+  }
+  /**
+   * Warm-path: app received a universal/app-link delivery. Resolves the
+   * shortcode against the backend and fires `onLinkOpened`. No-op (and
+   * returns false) when the URL isn't a Sendora link.
+   */
+  async handleUniversalLink(url) {
+    const shortcode = extractShortcodeFromUrl(url);
+    if (!shortcode) return false;
+    try {
+      const res = await getJson(
+        { apiUrl: this.deps.apiUrl, publicKey: this.deps.publicKey, debug: this.deps.debug },
+        `/api/v1/sdk/links/${encodeURIComponent(shortcode)}`
+      );
+      const data = await unwrap(res, "links.handleUniversalLink");
+      if (!data) return false;
+      this.emit({
+        shortcode: data.shortcode,
+        linkData: data.linkData ?? {},
+        iosDeepLinkPath: data.iosDeepLinkPath,
+        androidDeepLinkPath: data.androidDeepLinkPath,
+        isDeferred: false
+      });
+      return true;
+    } catch (err) {
+      if (this.deps.debug) console.warn("[sendoracloud] handleUniversalLink failed:", err);
+      return false;
+    }
+  }
+  /**
+   * Cold-launch deferred deep link match. Pass the Android Play Install
+   * Referrer string (preferred — 100% accurate) and/or a precomputed
+   * fingerprint hash (iOS — probabilistic).
+   *
+   * SDK fires `onLinkOpened` with `isDeferred: true` on success.
+   * Returns the event payload on match, `null` on no match.
+   */
+  async matchDeferred(input) {
+    if (!input.fingerprintHash && !input.installReferrer) {
+      throw new Error("[sendoracloud] links.matchDeferred: pass fingerprintHash or installReferrer");
+    }
+    const body = {};
+    if (input.fingerprintHash) body.fingerprintHash = input.fingerprintHash;
+    if (input.installReferrer) body.installReferrer = input.installReferrer;
+    const ios = input.iosBundleId ?? this.deps.iosBundleId;
+    const android = input.androidPackageName ?? this.deps.androidPackageName;
+    if (ios) body.iosBundleId = ios;
+    if (android) body.androidPackageName = android;
+    const res = await post(
+      { apiUrl: this.deps.apiUrl, publicKey: this.deps.publicKey, debug: this.deps.debug },
+      "/api/v1/sdk/links/match",
+      body
+    );
+    const data = await unwrap(res, "links.matchDeferred");
+    if (!data || !data.shortcode) return null;
+    const event = {
+      shortcode: data.shortcode,
+      linkData: data.linkData ?? {},
+      iosDeepLinkPath: data.iosDeepLinkPath,
+      androidDeepLinkPath: data.androidDeepLinkPath,
+      isDeferred: true
+    };
+    this.emit(event);
+    return event;
+  }
+};
+
 // src/auto-track.ts
 var DEFAULT_IDLE_MS = 30 * 60 * 1e3;
 function resolveFlags(cfg) {
@@ -904,7 +1075,7 @@ function installAutoTrack(args) {
 }
 
 // src/index.ts
-var SDK_VERSION = "0.11.0";
+var SDK_VERSION = "0.15.0";
 var DEFAULT_API_URL = "https://api.sendoracloud.com";
 var ANON_KEY = "anon_id";
 var USER_ID_KEY = "user_id";
@@ -1043,6 +1214,13 @@ var SendoraSDK = class {
       }
     });
     this.auth.hydrate();
+    this.links = new Links({
+      apiUrl: this.config.apiUrl,
+      publicKey: this.config.publicKey,
+      debug: this.debug,
+      iosBundleId: this.config.iosBundleId,
+      androidPackageName: this.config.androidPackageName
+    });
     this.ready = true;
     if (config.autoTrack !== false) {
       this.autoTrackCleanup = installAutoTrack({
@@ -1237,5 +1415,7 @@ var index_default = SendoraCloud;
   Auth,
   AuthError,
   EmailAlreadyTakenError,
-  SendoraCloud
+  Links,
+  SendoraCloud,
+  extractShortcodeFromUrl
 });

package/dist/index.d.cts

@@ -122,10 +122,24 @@ declare class Auth {
     private readyPromise;
     private resolveReady;
     constructor(hooks: AuthHooks);
-    /** Re-hydrate session from storage. Called by the parent SDK
-     *  during init() after Storage.hydrate() has run. Marks the
-     *  internal ready promise as resolved so queued auth calls
-     *  unblock. */
+    /**
+     * Re-hydrate session from storage. Called by the parent SDK during
+     * init() after Storage.hydrate() has run. Marks the internal ready
+     * promise as resolved so queued auth calls unblock.
+     *
+     * s58.47 — restore the user even when the cached ACCESS token is
+     * missing/expired, as long as USER_KEY + REFRESH_KEY are present.
+     * Pre-s58.47 this required BOTH USER_KEY and TOKEN_KEY, which
+     * caused a cold-start regression: if the access token rotated out
+     * of storage (TTL elapsed, app killed between persists, partial
+     * write, AsyncStorage eviction) the user appeared signed out even
+     * though their refresh chain was still alive in storage. Hosts
+     * then called `signInAnonymously()` on every launch and minted a
+     * fresh anon user, fragmenting analytics across sessions
+     * (Pulse News symptom). With the refresh token present, the next
+     * `getAccessToken()` call will silently refresh + restore a valid
+     * access token without disturbing identity.
+     */
     hydrate(): void;
     getCurrentUser(): AuthUser | null;
     /**
@@ -290,6 +304,129 @@ declare class Auth {
     private wipeLocalIdentity;
 }
 
+/**
+ * Sendora Deep Links surface for React Native.
+ *
+ * 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`.
+ *
+ * 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.
+ */
+interface LinkCreateInput {
+    /** 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>;
+    /** Optional OG preview overrides for richer share cards. */
+    ogTitle?: string;
+    ogDescription?: string;
+    ogImageUrl?: string;
+    /** Attribution tags. */
+    campaign?: string;
+    source?: string;
+    medium?: string;
+    channel?: string;
+    tags?: string[];
+    /** ISO timestamp when the link stops resolving. */
+    expiresAt?: string;
+    /** Bundle ID / package name for the bundle-id gate. */
+    iosBundleId?: string;
+    androidPackageName?: string;
+}
+interface LinkCreateResult {
+    id: string;
+    shortcode: string;
+    /** Fully qualified share URL — what you pass to RN `Share.share({ message: ... })`. */
+    url: string;
+    iosDeepLinkPath: string | null;
+    androidDeepLinkPath: string | null;
+    fallbackUrl: string;
+    linkData: Record<string, unknown>;
+    expiresAt: string | null;
+}
+interface LinkOpenedEvent {
+    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. */
+    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.
+     */
+    isDeferred: boolean;
+}
+type LinkOpenedHandler = (event: LinkOpenedEvent) => void;
+interface LinkMatchInput {
+    /** Hex-encoded SHA-256 of (ip + ua + screen + tz + locale). Pre-hashed by caller. */
+    fingerprintHash?: string;
+    /** Raw Play Install Referrer (`PlayInstallReferrerClient.getInstallReferrer().installReferrer`). */
+    installReferrer?: string;
+    iosBundleId?: string;
+    androidPackageName?: string;
+}
+/**
+ * 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`).
+ */
+declare function extractShortcodeFromUrl(url: string): string | null;
+interface LinksDeps {
+    apiUrl: string;
+    publicKey: string;
+    debug: boolean;
+    iosBundleId?: string;
+    androidPackageName?: string;
+}
+declare class Links {
+    private deps;
+    private listeners;
+    constructor(deps: LinksDeps);
+    /** Register a callback for warm + deferred deep-link opens. Returns unsubscribe fn. */
+    onLinkOpened(handler: LinkOpenedHandler): () => void;
+    private emit;
+    /** Mint a new short link. Returns the share URL + shortcode. */
+    create(input: LinkCreateInput): Promise<LinkCreateResult>;
+    /**
+     * Warm-path: app received a universal/app-link delivery. Resolves the
+     * shortcode against the backend and fires `onLinkOpened`. No-op (and
+     * returns false) when the URL isn't a Sendora link.
+     */
+    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).
+     *
+     * SDK fires `onLinkOpened` with `isDeferred: true` on success.
+     * Returns the event payload on match, `null` on no match.
+     */
+    matchDeferred(input: LinkMatchInput): Promise<LinkOpenedEvent | null>;
+}
+
 interface SendoraConfig {
     /**
      * Public API key (`pk_live_…` or `pk_test_…`). Secret keys are refused.
@@ -344,6 +481,17 @@ interface SendoraConfig {
     };
     /** Idle threshold (ms) for session expiry; default 30 minutes. */
     sessionIdleMs?: number;
+    /**
+     * iOS bundle id (e.g. `com.pulse.news`). Forwarded to backend on
+     * `links.create()` / `links.matchDeferred()` for the bundle-id gate —
+     * blocks a leaked public key from being used by a different app.
+     */
+    iosBundleId?: string;
+    /**
+     * Android package name (e.g. `com.pulse.news`). Same purpose as
+     * `iosBundleId` above.
+     */
+    androidPackageName?: string;
 }
 type TraitValue = string | number | boolean | null | undefined;
 interface IdentifyTraits {
@@ -416,6 +564,8 @@ declare class SendoraSDK {
     private autoTrackCleanup;
     /** Lazy-initialised in init() once we know the apiUrl + publicKey. */
     auth: Auth;
+    /** Lazy-initialised in init(). Deep-link surface: create + handleUniversalLink + matchDeferred. */
+    links: Links;
     /** Initialize the SDK. Must be awaited at app startup before identify/track. */
     init(config: SendoraConfig): Promise<void>;
     /** Current logical session id, if auto-track is enabled. */
@@ -462,4 +612,4 @@ declare class SendoraSDK {
 }
 declare const SendoraCloud: SendoraSDK;
 
-export { Auth, AuthError, type AuthTokens, type AuthUser, EmailAlreadyTakenError, type IdentifyTraits, type PushTokenReceipt, type PushTokenRegistration, SendoraCloud, type SendoraConfig, type TrackProperties, SendoraCloud as default };
+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 };

package/dist/index.d.ts

@@ -122,10 +122,24 @@ declare class Auth {
     private readyPromise;
     private resolveReady;
     constructor(hooks: AuthHooks);
-    /** Re-hydrate session from storage. Called by the parent SDK
-     *  during init() after Storage.hydrate() has run. Marks the
-     *  internal ready promise as resolved so queued auth calls
-     *  unblock. */
+    /**
+     * Re-hydrate session from storage. Called by the parent SDK during
+     * init() after Storage.hydrate() has run. Marks the internal ready
+     * promise as resolved so queued auth calls unblock.
+     *
+     * s58.47 — restore the user even when the cached ACCESS token is
+     * missing/expired, as long as USER_KEY + REFRESH_KEY are present.
+     * Pre-s58.47 this required BOTH USER_KEY and TOKEN_KEY, which
+     * caused a cold-start regression: if the access token rotated out
+     * of storage (TTL elapsed, app killed between persists, partial
+     * write, AsyncStorage eviction) the user appeared signed out even
+     * though their refresh chain was still alive in storage. Hosts
+     * then called `signInAnonymously()` on every launch and minted a
+     * fresh anon user, fragmenting analytics across sessions
+     * (Pulse News symptom). With the refresh token present, the next
+     * `getAccessToken()` call will silently refresh + restore a valid
+     * access token without disturbing identity.
+     */
     hydrate(): void;
     getCurrentUser(): AuthUser | null;
     /**
@@ -290,6 +304,129 @@ declare class Auth {
     private wipeLocalIdentity;
 }
 
+/**
+ * Sendora Deep Links surface for React Native.
+ *
+ * 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`.
+ *
+ * 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.
+ */
+interface LinkCreateInput {
+    /** 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>;
+    /** Optional OG preview overrides for richer share cards. */
+    ogTitle?: string;
+    ogDescription?: string;
+    ogImageUrl?: string;
+    /** Attribution tags. */
+    campaign?: string;
+    source?: string;
+    medium?: string;
+    channel?: string;
+    tags?: string[];
+    /** ISO timestamp when the link stops resolving. */
+    expiresAt?: string;
+    /** Bundle ID / package name for the bundle-id gate. */
+    iosBundleId?: string;
+    androidPackageName?: string;
+}
+interface LinkCreateResult {
+    id: string;
+    shortcode: string;
+    /** Fully qualified share URL — what you pass to RN `Share.share({ message: ... })`. */
+    url: string;
+    iosDeepLinkPath: string | null;
+    androidDeepLinkPath: string | null;
+    fallbackUrl: string;
+    linkData: Record<string, unknown>;
+    expiresAt: string | null;
+}
+interface LinkOpenedEvent {
+    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. */
+    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.
+     */
+    isDeferred: boolean;
+}
+type LinkOpenedHandler = (event: LinkOpenedEvent) => void;
+interface LinkMatchInput {
+    /** Hex-encoded SHA-256 of (ip + ua + screen + tz + locale). Pre-hashed by caller. */
+    fingerprintHash?: string;
+    /** Raw Play Install Referrer (`PlayInstallReferrerClient.getInstallReferrer().installReferrer`). */
+    installReferrer?: string;
+    iosBundleId?: string;
+    androidPackageName?: string;
+}
+/**
+ * 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`).
+ */
+declare function extractShortcodeFromUrl(url: string): string | null;
+interface LinksDeps {
+    apiUrl: string;
+    publicKey: string;
+    debug: boolean;
+    iosBundleId?: string;
+    androidPackageName?: string;
+}
+declare class Links {
+    private deps;
+    private listeners;
+    constructor(deps: LinksDeps);
+    /** Register a callback for warm + deferred deep-link opens. Returns unsubscribe fn. */
+    onLinkOpened(handler: LinkOpenedHandler): () => void;
+    private emit;
+    /** Mint a new short link. Returns the share URL + shortcode. */
+    create(input: LinkCreateInput): Promise<LinkCreateResult>;
+    /**
+     * Warm-path: app received a universal/app-link delivery. Resolves the
+     * shortcode against the backend and fires `onLinkOpened`. No-op (and
+     * returns false) when the URL isn't a Sendora link.
+     */
+    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).
+     *
+     * SDK fires `onLinkOpened` with `isDeferred: true` on success.
+     * Returns the event payload on match, `null` on no match.
+     */
+    matchDeferred(input: LinkMatchInput): Promise<LinkOpenedEvent | null>;
+}
+
 interface SendoraConfig {
     /**
      * Public API key (`pk_live_…` or `pk_test_…`). Secret keys are refused.
@@ -344,6 +481,17 @@ interface SendoraConfig {
     };
     /** Idle threshold (ms) for session expiry; default 30 minutes. */
     sessionIdleMs?: number;
+    /**
+     * iOS bundle id (e.g. `com.pulse.news`). Forwarded to backend on
+     * `links.create()` / `links.matchDeferred()` for the bundle-id gate —
+     * blocks a leaked public key from being used by a different app.
+     */
+    iosBundleId?: string;
+    /**
+     * Android package name (e.g. `com.pulse.news`). Same purpose as
+     * `iosBundleId` above.
+     */
+    androidPackageName?: string;
 }
 type TraitValue = string | number | boolean | null | undefined;
 interface IdentifyTraits {
@@ -416,6 +564,8 @@ declare class SendoraSDK {
     private autoTrackCleanup;
     /** Lazy-initialised in init() once we know the apiUrl + publicKey. */
     auth: Auth;
+    /** Lazy-initialised in init(). Deep-link surface: create + handleUniversalLink + matchDeferred. */
+    links: Links;
     /** Initialize the SDK. Must be awaited at app startup before identify/track. */
     init(config: SendoraConfig): Promise<void>;
     /** Current logical session id, if auto-track is enabled. */
@@ -462,4 +612,4 @@ declare class SendoraSDK {
 }
 declare const SendoraCloud: SendoraSDK;
 
-export { Auth, AuthError, type AuthTokens, type AuthUser, EmailAlreadyTakenError, type IdentifyTraits, type PushTokenReceipt, type PushTokenRegistration, SendoraCloud, type SendoraConfig, type TrackProperties, SendoraCloud as default };
+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 };

package/dist/index.js

@@ -195,21 +195,41 @@ var Auth = class {
       this.resolveReady = res;
     });
   }
-  /** Re-hydrate session from storage. Called by the parent SDK
-   *  during init() after Storage.hydrate() has run. Marks the
-   *  internal ready promise as resolved so queued auth calls
-   *  unblock. */
+  /**
+   * Re-hydrate session from storage. Called by the parent SDK during
+   * init() after Storage.hydrate() has run. Marks the internal ready
+   * promise as resolved so queued auth calls unblock.
+   *
+   * s58.47 — restore the user even when the cached ACCESS token is
+   * missing/expired, as long as USER_KEY + REFRESH_KEY are present.
+   * Pre-s58.47 this required BOTH USER_KEY and TOKEN_KEY, which
+   * caused a cold-start regression: if the access token rotated out
+   * of storage (TTL elapsed, app killed between persists, partial
+   * write, AsyncStorage eviction) the user appeared signed out even
+   * though their refresh chain was still alive in storage. Hosts
+   * then called `signInAnonymously()` on every launch and minted a
+   * fresh anon user, fragmenting analytics across sessions
+   * (Pulse News symptom). With the refresh token present, the next
+   * `getAccessToken()` call will silently refresh + restore a valid
+   * access token without disturbing identity.
+   */
   hydrate() {
     const cachedUser = this.hooks.storage.get(USER_KEY);
     const cachedToken = this.hooks.storage.get(TOKEN_KEY);
+    const cachedRefresh = this.hooks.storage.get(REFRESH_KEY);
     const cachedExpires = this.hooks.storage.get(TOKEN_EXPIRES_KEY);
-    if (cachedUser && cachedToken) {
+    if (cachedUser && (cachedToken || cachedRefresh)) {
       try {
         const parsed = JSON.parse(cachedUser);
         if (typeof parsed.id !== "string" || parsed.id.length === 0) throw new Error("invalid cache");
         this.user = parsed;
-        this.accessToken = cachedToken;
-        this.accessExpiresAt = cachedExpires ? Number(cachedExpires) : 0;
+        if (cachedToken) {
+          this.accessToken = cachedToken;
+          this.accessExpiresAt = cachedExpires ? Number(cachedExpires) : 0;
+        } else {
+          this.accessToken = null;
+          this.accessExpiresAt = 0;
+        }
         this.hooks.onIdentityChange(this.user.id);
       } catch {
         this.hooks.storage.remove(USER_KEY);
@@ -781,6 +801,155 @@ function decodeJwtPayload(token) {
   }
 }
 
+// src/links.ts
+async function unwrap(res, ctx) {
+  if (!res) throw new Error(`[sendoracloud] ${ctx}: network error`);
+  if (!res.ok) {
+    let msg = `HTTP ${res.status}`;
+    try {
+      const parsed2 = await res.clone().json();
+      if (parsed2.error?.code || parsed2.error?.message) {
+        msg = `${parsed2.error.code ?? ""}${parsed2.error.code && parsed2.error.message ? ": " : ""}${parsed2.error.message ?? ""}`;
+      }
+    } catch {
+    }
+    throw new Error(`[sendoracloud] ${ctx}: ${msg}`);
+  }
+  const parsed = await res.json();
+  return parsed.data ?? null;
+}
+var SHORTCODE_RE = /^[a-z0-9-]{3,20}$/;
+function extractShortcodeFromUrl(url) {
+  try {
+    const u = new URL(url);
+    const segs = u.pathname.split("/").filter(Boolean);
+    if (segs.length === 0) return null;
+    const tail = segs[segs.length - 1];
+    return SHORTCODE_RE.test(tail) ? tail : null;
+  } catch {
+    return null;
+  }
+}
+var Links = class {
+  constructor(deps) {
+    this.deps = deps;
+    this.listeners = [];
+  }
+  /** Register a callback for warm + deferred deep-link opens. Returns unsubscribe fn. */
+  onLinkOpened(handler) {
+    this.listeners.push(handler);
+    return () => {
+      const idx = this.listeners.indexOf(handler);
+      if (idx >= 0) this.listeners.splice(idx, 1);
+    };
+  }
+  emit(event) {
+    for (const fn of this.listeners) {
+      try {
+        fn(event);
+      } catch (err) {
+        if (this.deps.debug) console.warn("[sendoracloud] onLinkOpened handler threw:", err);
+      }
+    }
+  }
+  /** Mint a new short link. Returns the share URL + shortcode. */
+  async create(input) {
+    if (!input.title) throw new Error("[sendoracloud] links.create: title is required");
+    if (!input.fallbackUrl) throw new Error("[sendoracloud] links.create: fallbackUrl is required");
+    const body = { title: input.title, fallbackUrl: input.fallbackUrl };
+    if (input.iosDeepLinkPath) body.iosDeepLinkPath = input.iosDeepLinkPath;
+    if (input.androidDeepLinkPath) body.androidDeepLinkPath = input.androidDeepLinkPath;
+    if (input.linkData) body.linkData = input.linkData;
+    if (input.ogTitle) body.ogTitle = input.ogTitle;
+    if (input.ogDescription) body.ogDescription = input.ogDescription;
+    if (input.ogImageUrl) body.ogImageUrl = input.ogImageUrl;
+    if (input.campaign) body.campaign = input.campaign;
+    if (input.source) body.source = input.source;
+    if (input.medium) body.medium = input.medium;
+    if (input.channel) body.channel = input.channel;
+    if (input.tags) body.tags = input.tags;
+    if (input.expiresAt) body.expiresAt = input.expiresAt;
+    const ios = input.iosBundleId ?? this.deps.iosBundleId;
+    const android = input.androidPackageName ?? this.deps.androidPackageName;
+    if (ios) body.iosBundleId = ios;
+    if (android) body.androidPackageName = android;
+    const res = await post(
+      { apiUrl: this.deps.apiUrl, publicKey: this.deps.publicKey, debug: this.deps.debug },
+      "/api/v1/sdk/links",
+      body
+    );
+    const data = await unwrap(res, "links.create");
+    if (!data?.shortcode) {
+      throw new Error("[sendoracloud] links.create returned no shortcode");
+    }
+    return data;
+  }
+  /**
+   * Warm-path: app received a universal/app-link delivery. Resolves the
+   * shortcode against the backend and fires `onLinkOpened`. No-op (and
+   * returns false) when the URL isn't a Sendora link.
+   */
+  async handleUniversalLink(url) {
+    const shortcode = extractShortcodeFromUrl(url);
+    if (!shortcode) return false;
+    try {
+      const res = await getJson(
+        { apiUrl: this.deps.apiUrl, publicKey: this.deps.publicKey, debug: this.deps.debug },
+        `/api/v1/sdk/links/${encodeURIComponent(shortcode)}`
+      );
+      const data = await unwrap(res, "links.handleUniversalLink");
+      if (!data) return false;
+      this.emit({
+        shortcode: data.shortcode,
+        linkData: data.linkData ?? {},
+        iosDeepLinkPath: data.iosDeepLinkPath,
+        androidDeepLinkPath: data.androidDeepLinkPath,
+        isDeferred: false
+      });
+      return true;
+    } catch (err) {
+      if (this.deps.debug) console.warn("[sendoracloud] handleUniversalLink failed:", err);
+      return false;
+    }
+  }
+  /**
+   * Cold-launch deferred deep link match. Pass the Android Play Install
+   * Referrer string (preferred — 100% accurate) and/or a precomputed
+   * fingerprint hash (iOS — probabilistic).
+   *
+   * SDK fires `onLinkOpened` with `isDeferred: true` on success.
+   * Returns the event payload on match, `null` on no match.
+   */
+  async matchDeferred(input) {
+    if (!input.fingerprintHash && !input.installReferrer) {
+      throw new Error("[sendoracloud] links.matchDeferred: pass fingerprintHash or installReferrer");
+    }
+    const body = {};
+    if (input.fingerprintHash) body.fingerprintHash = input.fingerprintHash;
+    if (input.installReferrer) body.installReferrer = input.installReferrer;
+    const ios = input.iosBundleId ?? this.deps.iosBundleId;
+    const android = input.androidPackageName ?? this.deps.androidPackageName;
+    if (ios) body.iosBundleId = ios;
+    if (android) body.androidPackageName = android;
+    const res = await post(
+      { apiUrl: this.deps.apiUrl, publicKey: this.deps.publicKey, debug: this.deps.debug },
+      "/api/v1/sdk/links/match",
+      body
+    );
+    const data = await unwrap(res, "links.matchDeferred");
+    if (!data || !data.shortcode) return null;
+    const event = {
+      shortcode: data.shortcode,
+      linkData: data.linkData ?? {},
+      iosDeepLinkPath: data.iosDeepLinkPath,
+      androidDeepLinkPath: data.androidDeepLinkPath,
+      isDeferred: true
+    };
+    this.emit(event);
+    return event;
+  }
+};
+
 // src/auto-track.ts
 var DEFAULT_IDLE_MS = 30 * 60 * 1e3;
 function resolveFlags(cfg) {
@@ -864,7 +1033,7 @@ function installAutoTrack(args) {
 }
 
 // src/index.ts
-var SDK_VERSION = "0.11.0";
+var SDK_VERSION = "0.15.0";
 var DEFAULT_API_URL = "https://api.sendoracloud.com";
 var ANON_KEY = "anon_id";
 var USER_ID_KEY = "user_id";
@@ -1003,6 +1172,13 @@ var SendoraSDK = class {
       }
     });
     this.auth.hydrate();
+    this.links = new Links({
+      apiUrl: this.config.apiUrl,
+      publicKey: this.config.publicKey,
+      debug: this.debug,
+      iosBundleId: this.config.iosBundleId,
+      androidPackageName: this.config.androidPackageName
+    });
     this.ready = true;
     if (config.autoTrack !== false) {
       this.autoTrackCleanup = installAutoTrack({
@@ -1196,6 +1372,8 @@ export {
   Auth,
   AuthError,
   EmailAlreadyTakenError,
+  Links,
   SendoraCloud,
-  index_default as default
+  index_default as default,
+  extractShortcodeFromUrl
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sendoracloud/sdk-react-native",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Sendora Cloud React Native + Expo SDK — analytics, identity, push-token registration, auth. Expo Go compatible, no native modules beyond AsyncStorage.",
   "type": "module",
   "main": "./dist/index.cjs",