@sendoracloud/sdk-react-native 0.15.1 → 0.16.0

package/README.md

@@ -22,6 +22,14 @@ import "react-native-get-random-values";
 
 If you forget, `init()` throws with a paste-ready remediation block — it never fails silently.
 
+### Optional peers (deep links)
+
+| Peer | When to install |
+| --- | --- |
+| `expo-localization` | Improves device-fingerprint locale accuracy. Most Expo apps already have it. |
+| `expo-crypto` | Hardens the SHA-256 used by `computeDeviceFingerprint()`. Auto-used when installed; SDK falls back to web crypto and then a pure-JS impl if not. |
+| `react-native-play-install-referrer` | Android-only. Enables 100%-accurate deferred deep-link matching via Play Install Referrer. SDK auto-probes — no-op on iOS or when uninstalled. |
+
 ## Quick start
 
 ```ts
@@ -29,41 +37,31 @@ import SendoraCloud from "@sendoracloud/sdk-react-native";
 
 // App.tsx or wherever you initialise app-level services
 await SendoraCloud.init({
-  publicKey: "pk_live_...", // from Settings → API Keys in the SendoraCloud dashboard
-  orgId: "YOUR_ORG_UUID",
+  apiKey: "pk_prod_...",          // from Settings → API Keys in the dashboard
+  iosBundleId: "com.yourapp",     // bundle-id gate — required for SDK link mint
+  androidPackageName: "com.yourapp",
+  // linkDomain: "pulse.link",    // optional — only if you use a custom share host
 });
 
 // Identify the signed-in user
-SendoraCloud.identify("user-123", {
-  email: "user@example.com",
-  name: "Ada Lovelace",
-});
+SendoraCloud.identify("user-123", { email: "user@example.com" });
 
-// Track a product event
+// Track product events + screen views
 SendoraCloud.track("signup.completed", { plan: "growth" });
-
-// Track screen views (RN equivalent of page views)
 SendoraCloud.screen("Pricing");
 
-// Register the device push token (get it from expo-notifications)
-import * as Notifications from "expo-notifications";
-const { data } = await Notifications.getExpoPushTokenAsync();
+// Push tokens
 const receipt = await SendoraCloud.registerPushToken({
-  token: data,
+  token: expoPushToken,
   platform: Platform.OS as "ios" | "android",
-  // bundleId is OPTIONAL but strongly recommended for multi-env apps:
-  // Sendora uses it to route to the right APNs / FCM credentials so a
-  // dev token never receives a prod push.
-  bundleId: "com.yourcompany.app",
+  bundleId: "com.yourapp",
 });
-// Returns { tokenId, created } — log it for debugging fan-out issues.
-console.log("registered:", receipt.tokenId, "new?", receipt.created);
 
 // On logout
-SendoraCloud.reset();
+await SendoraCloud.reset();
 ```
 
-## API
+## API surface
 
 | Method | Description |
 | --- | --- |
@@ -72,82 +70,122 @@ 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. |
-| `links.create(input)` | Mint a Sendora deep link from inside the app (Branch / Firebase parity). |
+| `auth.*` | Sign-in / sign-up / MFA / passkeys / OIDC / SSO. 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. |
-| `links.matchDeferred({ installReferrer?, fingerprintHash? })` | Cold-launch deferred deep link match. |
-| `links.onLinkOpened(cb)` | Register a callback fired for both warm + deferred opens. |
+| `links.matchDeferred(input?)` | Cold-launch deferred match. Auto-probes Play Install Referrer + fingerprint. |
+| `links.attachLinkingApi({ onLegacyUrl })` | One-call replacement for `Linking.getInitialURL` + `addEventListener` + extract-pre-check. |
+| `links.onLinkOpened<T>(cb)` | Register a callback fired for both warm + deferred opens. |
+| `links.revoke(shortcode)` | Soft-delete a link (private-content unsend). Idempotent. |
+| `links.getStats(shortcode)` | `{ totalClicks, uniqueClicks, deferredMatches, byOs, byCountry, byDevice }`. |
+| `computeDeviceFingerprint()` | Standalone — returns canonical hex SHA-256. Identical recipe across all 3 mobile SDKs. |
 | `reset()` | Clear identity + rotate anonymous id. Call on logout. |
 | `getAnonymousId()` | Stable device id (persisted across restarts). |
 | `getUserId()` | Currently identified user id, or null. |
 
-### Deep links example (Pulse-style share button)
+## Deep links (Branch / Firebase Dynamic Links parity)
 
 ```ts
-// In your share button handler — mints a Sendora short URL the user
-// can paste into iMessage / Slack / wherever. The link survives an
-// App Store / Play Store detour and reopens the article in your app.
-const { url } = await SendoraCloud.links.create({
-  title: article.title,
-  fallbackUrl: `https://yourapp.com/articles/${article.id}`,
-  iosDeepLinkPath: `/articles/${article.id}`,
-  androidDeepLinkPath: `/articles/${article.id}`,
-  ogTitle: article.title,
-  ogImageUrl: article.heroImage,
-  linkData: { articleId: article.id, sharedBy: currentUser.id },
-});
-Share.share({ message: url });
+import SendoraCloud, { LinkError } from "@sendoracloud/sdk-react-native";
+
+// 1. Typed linkData — define your app's deep-link shape once.
+interface ArticleLink extends Record<string, unknown> {
+  type: "article";
+  articleId: string;
+  category: "tech" | "design" | "policy";
+  sharedBy: string;
+}
 
-// In your app root — fires once on every link open (warm or deferred):
-SendoraCloud.links.onLinkOpened((event) => {
-  const articleId = event.linkData.articleId as string | undefined;
-  if (articleId) navigateToArticle(articleId);
-});
+// 2. Prewarm on row mount → share tap completes instantly.
+SendoraCloud.links.prewarm<ArticleLink>(
+  {
+    title: `Share: ${article.title}`,
+    iosDeepLinkPath: `/articles/${article.id}`,
+    androidDeepLinkPath: `/articles/${article.id}`,
+    ogTitle: article.title,
+    linkData: { type: "article", articleId: article.id, category: article.category, sharedBy: currentUser.id },
+    // fallbackUrl optional — backend defaults from your project's apps registry.
+  },
+  { key: `article:${article.id}` },
+);
+
+// 3. Mint on tap — returns from prewarm cache when keys match.
+try {
+  const link = await SendoraCloud.links.create<ArticleLink>(input, { key: `article:${article.id}` });
+  await Share.share({ message: link.url });
+} catch (err) {
+  if (err instanceof LinkError) {
+    switch (err.code) {
+      case "BUNDLE_MISMATCH": /* register bundle in Dashboard → Apps */ break;
+      case "PLAN_LIMIT":      /* upgrade plan */ break;
+      case "RATE_LIMITED":    /* back off + retry */ break;
+      case "FALLBACK_REQUIRED": /* configure App Store URL in apps registry */ break;
+    }
+  }
+}
 
-// Wire URL handlers — warm path (app already installed):
-import { Linking } from "react-native";
-Linking.addEventListener("url", ({ url }) => {
-  SendoraCloud.links.handleUniversalLink(url);
-});
+// 4. App-root router — one call replaces the Linking boilerplate.
+useEffect(() => {
+  const offOpen = SendoraCloud.links.onLinkOpened<ArticleLink>((event) => {
+    if (event.linkData.type === "article") navigateToArticle(event.linkData.articleId);
+  });
+  let detach: (() => void) | undefined;
+  void SendoraCloud.links
+    .attachLinkingApi({ onLegacyUrl: (url) => myExistingRouter.handle(url) })
+    .then((d) => { detach = d; });
+  // Cold-launch deferred match — auto-picks installReferrer / fingerprint.
+  void SendoraCloud.links.matchDeferred();
+  return () => { detach?.(); offOpen(); };
+}, []);
+
+// 5. Revoke + stats — no dashboard scraping.
+await SendoraCloud.links.revoke("ab3xk9p");
+const stats = await SendoraCloud.links.getStats("ab3xk9p");
+// → { totalClicks, uniqueClicks, deferredMatches, byOs, byCountry, byDevice }
+```
+
+Full paste-ready recipes live in [`examples/links-share.tsx`](./examples/links-share.tsx) and [`examples/links-router.tsx`](./examples/links-router.tsx).
+
+### Typed errors
+
+`LinkError` is thrown for every backend rejection. Branch on `err.code` (a typed `LinkErrorCode`) rather than string-matching `err.message`:
 
-// Cold path (deferred deep link after install) — Android Play Install Referrer
-// preferred (100% accurate). iOS: ship a fingerprint hash if you have one.
-import { PlayInstallReferrer } from "react-native-play-install-referrer";
-const ref = await PlayInstallReferrer.getInstallReferrerInfo();
-await SendoraCloud.links.matchDeferred({ installReferrer: ref?.installReferrer });
 ```
+"BUNDLE_MISMATCH" | "DATA_TOO_LARGE" | "EXPIRED" | "NETWORK" | "RATE_LIMITED"
+| "NOT_FOUND" | "UNAUTHORIZED" | "INVALID_INPUT" | "PLAN_LIMIT"
+| "FALLBACK_REQUIRED" | "SERVER" | "UNKNOWN"
+```
+
+### Bundle-id gate
+
+`init()` accepts `iosBundleId` / `androidPackageName`. The SDK auto-forwards them on every `links.create()` / `links.matchDeferred()` call. The backend cross-checks against your project's apps registry (Dashboard → Apps); a leaked public key plus a wrong bundle returns `LinkError(code: "BUNDLE_MISMATCH", statusCode: 422)`. Fail-closed when zero apps are registered — register your iOS bundle id + Android package name + SHA-256 fingerprint before going to prod.
+
+## Auth
+
+`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).
 
 ## Config
 
 ```ts
 {
-  publicKey: string;           // Required. Must start with "pk_".
-  orgId?: string;              // Your workspace UUID.
+  apiKey: string;              // Required. pk_(prod|staging|dev)_<16+ alphanumerics>.
   apiUrl?: string;             // Defaults to https://api.sendoracloud.com
-  environment?: "prod" | "staging" | "dev";  // Routing hint.
-  projectId?: string;          // Optional project scoping.
+  environment?: "prod" | "staging" | "dev";
+  projectId?: string;
   consentedByDefault?: boolean; // Defaults to true.
-  /**
-   * Auto-collect lifecycle events. Default true. Object form:
-   * { appOpen?, sessionStart?, appBackground? } for granular control.
-   * - appOpen — `app.opened` once per init.
-   * - sessionStart — `session.start` once per session (idle >sessionIdleMs).
-   * - appBackground — AppState 'change' fires `app.foregrounded` /
-   *   `app.backgrounded`.
-   * Note: `screen.viewed` is NOT auto — call `SendoraCloud.screen(name)`
-   * from your navigation listener (RN has no canonical router).
-   */
   autoTrack?: boolean | { appOpen?: boolean; sessionStart?: boolean; appBackground?: boolean };
-  sessionIdleMs?: number; // Idle threshold for session expiry. Default 30 min.
-  /** iOS bundle id — forwarded to backend on `links.create()` for the bundle-id gate. */
-  iosBundleId?: string;
-  /** Android package name — same purpose as iosBundleId. */
+  sessionIdleMs?: number;       // Idle threshold for session expiry. Default 30 min.
+  iosBundleId?: string;         // Bundle-id gate input for links.create / matchDeferred.
   androidPackageName?: string;
+  linkDomain?: string;          // Custom share host (e.g. "pulse.link"). Defaults to Sendora's.
+  debug?: boolean;
 }
 ```
 
 ## Stability
 
-This SDK is on the **0.10.x line**. Patch bumps (0.10.x → 0.10.y) are backwards-compatible; minor bumps may include breaking changes — always read the [CHANGELOG](https://github.com/sendoracloud/sdk-react-native/blob/main/CHANGELOG.md) before upgrading. The next major (1.0) is targeted once the HttpOnly-cookie SSR auth + auto-trait extraction features have soaked in production for two consecutive months without a schema change. Once 1.0 ships, semver is strict.
+This SDK is on the **0.16.x line**. Patch bumps (0.16.x → 0.16.y) are backwards-compatible; minor bumps may include breaking changes — always read the [CHANGELOG](https://github.com/sendoracloud/sdk-react-native/blob/main/CHANGELOG.md) before upgrading. 1.0 ships once the SDK has soaked 2 consecutive months in production without a schema change.
 
 ## JWT verification (custom backend)
 
@@ -168,15 +206,16 @@ const claims = decodeJwt(token);
 const { payload } = await jwtVerify(token, getJwks(claims.iss as string));
 ```
 
-The `iss` claim is a per-org Sendora URL (e.g. `https://api.sendoracloud.com/api/v1/auth-service/<orgId>`); appending `/.well-known/jwks.json` resolves on the same host. This means a customer can rotate signing keys without your code redeploying. **Don't** copy a hardcoded JWKS URL from a tutorial — it'll break in 12 months when an org rotates.
+The `iss` claim is a per-org Sendora URL (e.g. `https://api.sendoracloud.com/api/v1/auth-service/<orgId>`); appending `/.well-known/jwks.json` resolves on the same host. This means a customer can rotate signing keys without your code redeploying.
 
 ## Security
 
-- **Secret keys refused on the client.** The SDK only accepts `pk_(live|test)_<alphanumerics>` keys — `sk_*` (any case) or malformed values throw at init. Secret keys must stay on your backend.
-- **HTTPS enforced** outside local dev. The SDK rejects non-`https:` `apiUrl` values unless the hostname is `localhost` / `127.0.0.1` and `environment` is not `"prod"`.
-- **AsyncStorage** backs the anonymous id so a single user has one identity across app restarts, but never across devices. `reset()` awaits the storage writes and clears every SDK-owned key.
-- **Use opaque userIds, not emails.** Whatever you pass to `identify(userId)` persists to on-device AsyncStorage in plaintext. Use your internal user UUID, not the user's email. Emails can go in `traits: { email }` — traits aren't persisted to disk, only sent with the identify event.
-- **Push token + metadata capped** at 4 KB each to prevent a buggy or hostile host app from flooding the backend.
+- **Secret keys refused on the client.** Only `pk_*` keys accepted; `sk_*` throws at init.
+- **HTTPS enforced** outside local dev. Non-`https:` `apiUrl` values are rejected unless `localhost` / `127.0.0.1` + `environment != "prod"`.
+- **AsyncStorage** backs the anonymous id for cross-restart identity; never cross-device. `reset()` awaits the storage writes.
+- **Use opaque userIds, not emails.** Persisted to AsyncStorage plaintext. Put email in `traits` instead.
+- **Push token + metadata capped** at 4 KB each.
+- **Deep-link bundle-id gate** — a leaked public key cannot mint links pointed at someone else's app.
 
 ## License