@sendoracloud/sdk-react-native 0.17.1 → 0.18.0

package/README.md

@@ -88,7 +88,7 @@ await SendoraCloud.reset();
 | `track(event, props?)` | Fire a custom product event. |
 | `screen(name, props?)` | Track a screen view. |
 | `registerPushToken(reg)` | Register an APNs or FCM push token. |
-| `auth.*` | Sign-in / sign-up / MFA / passkeys / OIDC / SSO. See `auth.ts`. |
+| `auth.*` | Sign-in / sign-up / MFA / passkeys / OIDC / SSO + `auth.getRefreshToken()` + `auth.merge(anonRefresh, targetRefresh?)`. See `auth.ts`. |
 | `links.create<T>(input, opts?)` | Mint a Sendora deep link. Generic `T` for typed `linkData`. |
 | `links.prewarm<T>(input, opts?)` | Background-mint + cache so share-tap is instant. |
 | `links.handleUniversalLink(url)` | Resolve a warm-path Universal Link / App Link delivery. |
@@ -183,6 +183,39 @@ Full paste-ready recipes live in [`examples/links-share.tsx`](./examples/links-s
 
 `SendoraCloud.auth` covers anonymous sign-in, email + password, magic link, email OTP, TOTP MFA, recovery codes, OIDC / SAML SSO, Sign in with Apple, Google, Microsoft, LinkedIn, Facebook, Discord. See [auth quickstart](https://sendoracloud.com/docs/quickstart-react-native#auth).
 
+### Anonymous → identified lifecycle
+
+The SDK creates an anonymous user on first `init()`. Every `track()` / `identify()` attaches to that `user_id` until the user signs up or signs in. Two transitions exist; both preserve analytics continuity, but the second one requires one extra line of code from your app:
+
+**Case 1 — fresh signup.** `auth.signUp(email, password)` detects the anonymous refresh token and calls `/auth-service/upgrade` first, which flips `is_anonymous=false` + sets the password on the SAME row. The `user_id` is preserved — no funnel break. Falls back to a fresh `/signup` if the bound user is already identified (rare race).
+
+```ts
+const { user } = await SendoraCloud.auth.signUp(email, password);
+// user.id === the same id the anon user had. Done.
+```
+
+**Case 2 — email already exists.** `signUp()` throws `EmailAlreadyTakenError` without consuming the anon refresh. You fall back to `signIn()` — but `signIn()` wipes the local anon identity, so anon events stay orphaned on the backend unless you transfer them with `auth.merge(anonRefresh)`. Capture the anon refresh BEFORE the signIn:
+
+```ts
+try {
+  const { user } = await SendoraCloud.auth.signUp(email, password);
+} catch (err) {
+  if (!(err instanceof EmailAlreadyTakenError)) throw err;
+
+  const anonRefresh = await SendoraCloud.auth.getRefreshToken();
+  const { user } = await SendoraCloud.auth.signIn(email, password);
+
+  // Best-effort, silent-fail-tolerant — anon row may be already drained.
+  if (anonRefresh) {
+    SendoraCloud.auth.merge(anonRefresh).catch(() => undefined);
+  }
+}
+```
+
+**Why merge isn't automatic on signIn.** Two people sharing a device (browser kiosk, family iPad) would silently get their anon-session events combined with a third party's real account. Forcing the merge call into your app keeps the data-mixing decision explicit. Wrap `signIn()` with the snippet above if you want auto behaviour.
+
+Full reference + edge-case writeup: [/docs/quickstart-react-native#anon-existing-email](https://sendoracloud.com/docs/quickstart-react-native#anon-existing-email).
+
 ## Config
 
 ```ts

package/dist/index.cjs

@@ -785,6 +785,75 @@ var Auth = class {
     })();
     return this.refreshInflight;
   }
+  /**
+   * Returns the currently-stored refresh token (or null when signed out).
+   * Primary use: capture the anonymous refresh token BEFORE calling
+   * `signIn()` so it can be transferred via `merge()` after the existing
+   * account is authenticated. See the "Anonymous → identified" section
+   * of the SDK README + /docs/quickstart-react-native#anon-existing-email.
+   */
+  getRefreshToken() {
+    return this.hooks.storage.get(REFRESH_KEY) ?? null;
+  }
+  /**
+   * Transfer every event + trait from an anonymous user to the
+   * currently-signed-in (target) user, then delete the anonymous row.
+   * `targetRefreshToken` defaults to the SDK's currently-stored refresh
+   * token — call this AFTER a successful `signIn()` so the storage
+   * already holds the target's refresh.
+   *
+   * Throws AuthError when:
+   *   - `anonymousRefreshToken` is invalid / expired / revoked,
+   *   - the bound source row is not anonymous (CONFLICT — use upgrade),
+   *   - the target is anonymous (CONFLICT — sign in first),
+   *   - both tokens resolve to the same user (CONFLICT — no-op).
+   *
+   * Mirrors Auth0 `accounts.link` + Firebase manual transfer semantics.
+   */
+  async merge(anonymousRefreshToken, targetRefreshToken) {
+    const target = targetRefreshToken ?? this.getRefreshToken();
+    if (!target) {
+      throw new AuthError(
+        "NO_TARGET_REFRESH",
+        "merge() needs a target refresh token. Call signIn() first or pass targetRefreshToken explicitly."
+      );
+    }
+    const res = await post(
+      { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
+      "/api/v1/auth-service/merge",
+      { anonymousRefreshToken, targetRefreshToken: target }
+    );
+    if (!res) throw new AuthError("NETWORK_ERROR", "Network request failed");
+    let parsed;
+    try {
+      parsed = await res.json();
+    } catch {
+      throw new AuthError("PARSE_ERROR", `HTTP ${res.status}`);
+    }
+    if (!res.ok || !parsed.success || !parsed.data) {
+      throw new AuthError(
+        parsed.error?.code ?? `HTTP_${res.status}`,
+        parsed.error?.message ?? `HTTP ${res.status}`
+      );
+    }
+    const t = parsed.data.tokens;
+    if (t?.accessToken && t.refreshToken && typeof t.expiresIn === "number") {
+      this.accessToken = t.accessToken;
+      this.accessExpiresAt = Date.now() + t.expiresIn * 1e3;
+      this.hooks.storage.set(TOKEN_KEY, t.accessToken);
+      this.hooks.storage.set(TOKEN_EXPIRES_KEY, String(this.accessExpiresAt));
+      this.hooks.storage.set(REFRESH_KEY, t.refreshToken);
+    }
+    return {
+      mergedUserId: parsed.data.mergedUserId ?? "",
+      deletedAnonymousId: parsed.data.deletedAnonymousId ?? "",
+      eventsReassigned: parsed.data.eventsReassigned ?? 0,
+      profilesReassigned: parsed.data.profilesReassigned ?? 0,
+      profilesDropped: parsed.data.profilesDropped ?? 0,
+      entitiesReassigned: parsed.data.entitiesReassigned ?? 0,
+      entitiesDropped: parsed.data.entitiesDropped ?? 0
+    };
+  }
   async callAuth(path, body) {
     const res = await post(
       { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
@@ -1771,6 +1840,55 @@ var SendoraSDK = class {
       }
     };
   }
+  /**
+   * Attribution namespace — mobile install + deferred deep-link reporting.
+   * Mirrors the backend's `/attribution/{install,deferred}` SDK routes.
+   *
+   * Backend resolves `orgId` + `projectId` from the API key, so the SDK
+   * helper accepts only the device-side context (fingerprint, OS, app
+   * version). Both methods are safe to call on every cold-start —
+   * backend deduplicates installs by `deviceId` within a 24h window so
+   * a paranoid app calling `reportInstall()` on every launch sees
+   * `deduplicated: true` after the first match.
+   *
+   * Typical pairing:
+   *   await SendoraCloud.attribution.reportInstall({
+   *     deviceId,
+   *     fingerprintHash: await computeDeviceFingerprint(),
+   *     appVersion,
+   *   });
+   *   const deferred = await SendoraCloud.attribution.checkDeferred();
+   *   if (deferred?.deepLinkPath) router.replace(deferred.deepLinkPath);
+   */
+  get attribution() {
+    const self = this;
+    return {
+      reportInstall: async (input) => {
+        if (!self.config) throw new Error("[sendoracloud] init() must complete before attribution.reportInstall().");
+        const res = await post(
+          { apiUrl: self.config.apiUrl, publicKey: self.config.publicKey, debug: self.debug },
+          "/attribution/install",
+          input ?? {}
+        );
+        if (!res || !res.ok) throw new Error(`[sendoracloud] attribution.reportInstall failed (${res?.status ?? "network"})`);
+        const parsed = await res.json();
+        if (!parsed.success || !parsed.data) throw new Error("[sendoracloud] attribution.reportInstall: bad response");
+        return parsed.data;
+      },
+      checkDeferred: async (input) => {
+        if (!self.config) throw new Error("[sendoracloud] init() must complete before attribution.checkDeferred().");
+        const res = await post(
+          { apiUrl: self.config.apiUrl, publicKey: self.config.publicKey, debug: self.debug },
+          "/attribution/deferred",
+          input ?? {}
+        );
+        if (!res || !res.ok) throw new Error(`[sendoracloud] attribution.checkDeferred failed (${res?.status ?? "network"})`);
+        const parsed = await res.json();
+        if (!parsed.success) throw new Error("[sendoracloud] attribution.checkDeferred: bad response");
+        return parsed.data ?? null;
+      }
+    };
+  }
   /**
    * Clear identity + rotate the anonymous id. Call on logout. Awaits
    * the AsyncStorage writes so a caller who kills the app immediately

package/dist/index.d.cts

@@ -299,6 +299,38 @@ declare class Auth {
      * surface NOT_SIGNED_IN to the host app instead of looping.
      */
     private refreshAccessToken;
+    /**
+     * Returns the currently-stored refresh token (or null when signed out).
+     * Primary use: capture the anonymous refresh token BEFORE calling
+     * `signIn()` so it can be transferred via `merge()` after the existing
+     * account is authenticated. See the "Anonymous → identified" section
+     * of the SDK README + /docs/quickstart-react-native#anon-existing-email.
+     */
+    getRefreshToken(): string | null;
+    /**
+     * Transfer every event + trait from an anonymous user to the
+     * currently-signed-in (target) user, then delete the anonymous row.
+     * `targetRefreshToken` defaults to the SDK's currently-stored refresh
+     * token — call this AFTER a successful `signIn()` so the storage
+     * already holds the target's refresh.
+     *
+     * Throws AuthError when:
+     *   - `anonymousRefreshToken` is invalid / expired / revoked,
+     *   - the bound source row is not anonymous (CONFLICT — use upgrade),
+     *   - the target is anonymous (CONFLICT — sign in first),
+     *   - both tokens resolve to the same user (CONFLICT — no-op).
+     *
+     * Mirrors Auth0 `accounts.link` + Firebase manual transfer semantics.
+     */
+    merge(anonymousRefreshToken: string, targetRefreshToken?: string): Promise<{
+        mergedUserId: string;
+        deletedAnonymousId: string;
+        eventsReassigned: number;
+        profilesReassigned: number;
+        profilesDropped: number;
+        entitiesReassigned: number;
+        entitiesDropped: number;
+    }>;
     private callAuth;
     private persist;
     private wipeLocalIdentity;
@@ -719,6 +751,63 @@ declare class SendoraSDK {
         registerToken: (reg: PushTokenRegistration) => Promise<PushTokenReceipt>;
         trackOpen: (sendId: string, clickAction?: string) => Promise<void>;
     };
+    /**
+     * Attribution namespace — mobile install + deferred deep-link reporting.
+     * Mirrors the backend's `/attribution/{install,deferred}` SDK routes.
+     *
+     * Backend resolves `orgId` + `projectId` from the API key, so the SDK
+     * helper accepts only the device-side context (fingerprint, OS, app
+     * version). Both methods are safe to call on every cold-start —
+     * backend deduplicates installs by `deviceId` within a 24h window so
+     * a paranoid app calling `reportInstall()` on every launch sees
+     * `deduplicated: true` after the first match.
+     *
+     * Typical pairing:
+     *   await SendoraCloud.attribution.reportInstall({
+     *     deviceId,
+     *     fingerprintHash: await computeDeviceFingerprint(),
+     *     appVersion,
+     *   });
+     *   const deferred = await SendoraCloud.attribution.checkDeferred();
+     *   if (deferred?.deepLinkPath) router.replace(deferred.deepLinkPath);
+     */
+    get attribution(): {
+        reportInstall: (input?: {
+            deviceId?: string;
+            fingerprintHash?: string;
+            appVersion?: string;
+            os?: string;
+            osVersion?: string;
+            country?: string;
+        }) => Promise<{
+            installId: string;
+            deduplicated: boolean;
+            attributed: boolean;
+            result?: {
+                matchType: string;
+                confidence?: number;
+                clickId?: string;
+                linkId?: string;
+                campaign?: string;
+                source?: string;
+                medium?: string;
+                deepLinkData?: Record<string, unknown>;
+                deepLinkPath?: string;
+            };
+        }>;
+        checkDeferred: (input?: {
+            fingerprintHash?: string;
+            deviceId?: string;
+        }) => Promise<{
+            matchType: string;
+            confidence?: number;
+            campaign?: string;
+            source?: string;
+            medium?: string;
+            deepLinkData?: Record<string, unknown>;
+            deepLinkPath?: string;
+        } | null>;
+    };
     /**
      * Clear identity + rotate the anonymous id. Call on logout. Awaits
      * the AsyncStorage writes so a caller who kills the app immediately

package/dist/index.d.ts

@@ -299,6 +299,38 @@ declare class Auth {
      * surface NOT_SIGNED_IN to the host app instead of looping.
      */
     private refreshAccessToken;
+    /**
+     * Returns the currently-stored refresh token (or null when signed out).
+     * Primary use: capture the anonymous refresh token BEFORE calling
+     * `signIn()` so it can be transferred via `merge()` after the existing
+     * account is authenticated. See the "Anonymous → identified" section
+     * of the SDK README + /docs/quickstart-react-native#anon-existing-email.
+     */
+    getRefreshToken(): string | null;
+    /**
+     * Transfer every event + trait from an anonymous user to the
+     * currently-signed-in (target) user, then delete the anonymous row.
+     * `targetRefreshToken` defaults to the SDK's currently-stored refresh
+     * token — call this AFTER a successful `signIn()` so the storage
+     * already holds the target's refresh.
+     *
+     * Throws AuthError when:
+     *   - `anonymousRefreshToken` is invalid / expired / revoked,
+     *   - the bound source row is not anonymous (CONFLICT — use upgrade),
+     *   - the target is anonymous (CONFLICT — sign in first),
+     *   - both tokens resolve to the same user (CONFLICT — no-op).
+     *
+     * Mirrors Auth0 `accounts.link` + Firebase manual transfer semantics.
+     */
+    merge(anonymousRefreshToken: string, targetRefreshToken?: string): Promise<{
+        mergedUserId: string;
+        deletedAnonymousId: string;
+        eventsReassigned: number;
+        profilesReassigned: number;
+        profilesDropped: number;
+        entitiesReassigned: number;
+        entitiesDropped: number;
+    }>;
     private callAuth;
     private persist;
     private wipeLocalIdentity;
@@ -719,6 +751,63 @@ declare class SendoraSDK {
         registerToken: (reg: PushTokenRegistration) => Promise<PushTokenReceipt>;
         trackOpen: (sendId: string, clickAction?: string) => Promise<void>;
     };
+    /**
+     * Attribution namespace — mobile install + deferred deep-link reporting.
+     * Mirrors the backend's `/attribution/{install,deferred}` SDK routes.
+     *
+     * Backend resolves `orgId` + `projectId` from the API key, so the SDK
+     * helper accepts only the device-side context (fingerprint, OS, app
+     * version). Both methods are safe to call on every cold-start —
+     * backend deduplicates installs by `deviceId` within a 24h window so
+     * a paranoid app calling `reportInstall()` on every launch sees
+     * `deduplicated: true` after the first match.
+     *
+     * Typical pairing:
+     *   await SendoraCloud.attribution.reportInstall({
+     *     deviceId,
+     *     fingerprintHash: await computeDeviceFingerprint(),
+     *     appVersion,
+     *   });
+     *   const deferred = await SendoraCloud.attribution.checkDeferred();
+     *   if (deferred?.deepLinkPath) router.replace(deferred.deepLinkPath);
+     */
+    get attribution(): {
+        reportInstall: (input?: {
+            deviceId?: string;
+            fingerprintHash?: string;
+            appVersion?: string;
+            os?: string;
+            osVersion?: string;
+            country?: string;
+        }) => Promise<{
+            installId: string;
+            deduplicated: boolean;
+            attributed: boolean;
+            result?: {
+                matchType: string;
+                confidence?: number;
+                clickId?: string;
+                linkId?: string;
+                campaign?: string;
+                source?: string;
+                medium?: string;
+                deepLinkData?: Record<string, unknown>;
+                deepLinkPath?: string;
+            };
+        }>;
+        checkDeferred: (input?: {
+            fingerprintHash?: string;
+            deviceId?: string;
+        }) => Promise<{
+            matchType: string;
+            confidence?: number;
+            campaign?: string;
+            source?: string;
+            medium?: string;
+            deepLinkData?: Record<string, unknown>;
+            deepLinkPath?: string;
+        } | null>;
+    };
     /**
      * Clear identity + rotate the anonymous id. Call on logout. Awaits
      * the AsyncStorage writes so a caller who kills the app immediately

package/dist/index.js

@@ -742,6 +742,75 @@ var Auth = class {
     })();
     return this.refreshInflight;
   }
+  /**
+   * Returns the currently-stored refresh token (or null when signed out).
+   * Primary use: capture the anonymous refresh token BEFORE calling
+   * `signIn()` so it can be transferred via `merge()` after the existing
+   * account is authenticated. See the "Anonymous → identified" section
+   * of the SDK README + /docs/quickstart-react-native#anon-existing-email.
+   */
+  getRefreshToken() {
+    return this.hooks.storage.get(REFRESH_KEY) ?? null;
+  }
+  /**
+   * Transfer every event + trait from an anonymous user to the
+   * currently-signed-in (target) user, then delete the anonymous row.
+   * `targetRefreshToken` defaults to the SDK's currently-stored refresh
+   * token — call this AFTER a successful `signIn()` so the storage
+   * already holds the target's refresh.
+   *
+   * Throws AuthError when:
+   *   - `anonymousRefreshToken` is invalid / expired / revoked,
+   *   - the bound source row is not anonymous (CONFLICT — use upgrade),
+   *   - the target is anonymous (CONFLICT — sign in first),
+   *   - both tokens resolve to the same user (CONFLICT — no-op).
+   *
+   * Mirrors Auth0 `accounts.link` + Firebase manual transfer semantics.
+   */
+  async merge(anonymousRefreshToken, targetRefreshToken) {
+    const target = targetRefreshToken ?? this.getRefreshToken();
+    if (!target) {
+      throw new AuthError(
+        "NO_TARGET_REFRESH",
+        "merge() needs a target refresh token. Call signIn() first or pass targetRefreshToken explicitly."
+      );
+    }
+    const res = await post(
+      { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
+      "/api/v1/auth-service/merge",
+      { anonymousRefreshToken, targetRefreshToken: target }
+    );
+    if (!res) throw new AuthError("NETWORK_ERROR", "Network request failed");
+    let parsed;
+    try {
+      parsed = await res.json();
+    } catch {
+      throw new AuthError("PARSE_ERROR", `HTTP ${res.status}`);
+    }
+    if (!res.ok || !parsed.success || !parsed.data) {
+      throw new AuthError(
+        parsed.error?.code ?? `HTTP_${res.status}`,
+        parsed.error?.message ?? `HTTP ${res.status}`
+      );
+    }
+    const t = parsed.data.tokens;
+    if (t?.accessToken && t.refreshToken && typeof t.expiresIn === "number") {
+      this.accessToken = t.accessToken;
+      this.accessExpiresAt = Date.now() + t.expiresIn * 1e3;
+      this.hooks.storage.set(TOKEN_KEY, t.accessToken);
+      this.hooks.storage.set(TOKEN_EXPIRES_KEY, String(this.accessExpiresAt));
+      this.hooks.storage.set(REFRESH_KEY, t.refreshToken);
+    }
+    return {
+      mergedUserId: parsed.data.mergedUserId ?? "",
+      deletedAnonymousId: parsed.data.deletedAnonymousId ?? "",
+      eventsReassigned: parsed.data.eventsReassigned ?? 0,
+      profilesReassigned: parsed.data.profilesReassigned ?? 0,
+      profilesDropped: parsed.data.profilesDropped ?? 0,
+      entitiesReassigned: parsed.data.entitiesReassigned ?? 0,
+      entitiesDropped: parsed.data.entitiesDropped ?? 0
+    };
+  }
   async callAuth(path, body) {
     const res = await post(
       { apiUrl: this.hooks.apiUrl, publicKey: this.hooks.publicKey, debug: this.hooks.debug },
@@ -1733,6 +1802,55 @@ var SendoraSDK = class {
       }
     };
   }
+  /**
+   * Attribution namespace — mobile install + deferred deep-link reporting.
+   * Mirrors the backend's `/attribution/{install,deferred}` SDK routes.
+   *
+   * Backend resolves `orgId` + `projectId` from the API key, so the SDK
+   * helper accepts only the device-side context (fingerprint, OS, app
+   * version). Both methods are safe to call on every cold-start —
+   * backend deduplicates installs by `deviceId` within a 24h window so
+   * a paranoid app calling `reportInstall()` on every launch sees
+   * `deduplicated: true` after the first match.
+   *
+   * Typical pairing:
+   *   await SendoraCloud.attribution.reportInstall({
+   *     deviceId,
+   *     fingerprintHash: await computeDeviceFingerprint(),
+   *     appVersion,
+   *   });
+   *   const deferred = await SendoraCloud.attribution.checkDeferred();
+   *   if (deferred?.deepLinkPath) router.replace(deferred.deepLinkPath);
+   */
+  get attribution() {
+    const self = this;
+    return {
+      reportInstall: async (input) => {
+        if (!self.config) throw new Error("[sendoracloud] init() must complete before attribution.reportInstall().");
+        const res = await post(
+          { apiUrl: self.config.apiUrl, publicKey: self.config.publicKey, debug: self.debug },
+          "/attribution/install",
+          input ?? {}
+        );
+        if (!res || !res.ok) throw new Error(`[sendoracloud] attribution.reportInstall failed (${res?.status ?? "network"})`);
+        const parsed = await res.json();
+        if (!parsed.success || !parsed.data) throw new Error("[sendoracloud] attribution.reportInstall: bad response");
+        return parsed.data;
+      },
+      checkDeferred: async (input) => {
+        if (!self.config) throw new Error("[sendoracloud] init() must complete before attribution.checkDeferred().");
+        const res = await post(
+          { apiUrl: self.config.apiUrl, publicKey: self.config.publicKey, debug: self.debug },
+          "/attribution/deferred",
+          input ?? {}
+        );
+        if (!res || !res.ok) throw new Error(`[sendoracloud] attribution.checkDeferred failed (${res?.status ?? "network"})`);
+        const parsed = await res.json();
+        if (!parsed.success) throw new Error("[sendoracloud] attribution.checkDeferred: bad response");
+        return parsed.data ?? null;
+      }
+    };
+  }
   /**
    * Clear identity + rotate the anonymous id. Call on logout. Awaits
    * the AsyncStorage writes so a caller who kills the app immediately

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sendoracloud/sdk-react-native",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "Sendora Cloud React Native + Expo SDK — analytics, identity, push-token registration, auth, deep links (Branch / Firebase Dynamic Links parity). Auth + analytics + deep links work in Expo Go; push token registration requires a Dev Client (EAS Build or `npx expo prebuild`).",
   "type": "module",
   "main": "./dist/index.cjs",