react-native-revnix 1.4.0

package/src/device.ts

@@ -0,0 +1,146 @@
+// REV-268: the device attribute contract, SDK side. Every SDK sends the same
+// twelve facts about the device on each placement resolve, in the
+// X-Revnix-Device header, and the server stores them as reserved `device.*`
+// customer attributes — the facts a targeting rule ("US only", "app version
+// at least 3", "first open") evaluates against on the very request that
+// serves the paywall.
+//
+// This SDK runs in a browser, in React Native, and under Node, so it cannot
+// read most of the facts itself the way the native SDKs can: there is no
+// StoreKit storefront in a browser and no `navigator` in Node. The split is
+//   - what the runtime can tell us safely (detectDeviceFacts): platform,
+//     locale, and — in a browser — the OS version from the user agent;
+//   - what the app must tell us (RevnixConfig.device): app version, model,
+//     storefront, currency, sandbox — a React Native app has
+//     react-native-device-info in hand and this SDK should not depend on it;
+//   - what the SDK owns outright: sdkVersion, installedAt, firstOpen.
+// Anything unknown is simply omitted; the server treats every field as
+// optional and normalizes what it gets (lib/deviceAttributes.ts in
+// revnix-app), so nothing here needs to be exact — only honest.
+
+import { SDK_VERSION } from "./version.js";
+import type { DeviceFacts } from "./types.js";
+
+/** The header the server reads. Keep in sync with
+ *  convex/lib/deviceAttributes.ts DEVICE_HEADER. */
+export const DEVICE_HEADER = "X-Revnix-Device";
+
+/** Storage key for the first-launch timestamp. */
+export const INSTALLED_AT_KEY = "revnix.installedAt";
+
+/** What goes on the wire: the app-supplied facts plus the three the SDK owns. */
+export interface DevicePayload extends DeviceFacts {
+  sdkVersion: string;
+  installedAt?: number;
+  firstOpen?: boolean;
+}
+
+/** The facts this runtime can report about itself without help. Browser
+ *  only in practice — under Node and React Native `navigator` is absent or
+ *  says nothing useful, and those callers pass `device` in configure(). */
+export function detectDeviceFacts(): DeviceFacts {
+  const nav = (globalThis as { navigator?: Navigator }).navigator;
+  const facts: DeviceFacts = {};
+  if (!nav) return facts;
+  // A React Native runtime also exposes `navigator` (product: "ReactNative")
+  // but its language/userAgent are not the device's — leave those to the app.
+  if ((nav as { product?: string }).product === "ReactNative") return facts;
+  if (typeof nav.userAgent === "string" && nav.userAgent.length > 0) {
+    facts.platform = "web";
+    const os = osVersionFromUserAgent(nav.userAgent);
+    if (os !== undefined) facts.osVersion = os;
+  }
+  if (typeof nav.language === "string" && nav.language.length > 0) {
+    facts.locale = nav.language;
+  }
+  return facts;
+}
+
+/** Best-effort OS version from a browser UA string; undefined when the UA
+ *  gives nothing recognizable. Only the major desktop/mobile families —
+ *  this is a targeting hint, not a fingerprinting library. */
+export function osVersionFromUserAgent(ua: string): string | undefined {
+  const ios = /(?:iPhone|iPad|CPU) OS (\d+(?:_\d+)*)/.exec(ua)?.[1];
+  if (ios !== undefined) return ios.replace(/_/g, ".");
+  const android = /Android (\d+(?:\.\d+)*)/.exec(ua)?.[1];
+  if (android !== undefined) return android;
+  const mac = /Mac OS X (\d+(?:[._]\d+)*)/.exec(ua)?.[1];
+  if (mac !== undefined) return mac.replace(/_/g, ".");
+  const windows = /Windows NT (\d+(?:\.\d+)*)/.exec(ua)?.[1];
+  if (windows !== undefined) return windows;
+  return undefined;
+}
+
+/** Drop undefined/empty fields so the encoded header carries only what is
+ *  known — the server would drop them anyway, but bytes on every resolve
+ *  are bytes on every resolve. */
+export function compactPayload(payload: DevicePayload): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(payload)) {
+    if (value === undefined || value === null || value === "") continue;
+    out[key] = value;
+  }
+  return out;
+}
+
+/** base64url of the UTF-8 JSON payload. Hand-rolled rather than
+ *  btoa/TextEncoder: neither is guaranteed on every React Native runtime
+ *  this SDK supports, and a missing global here would fail every paywall
+ *  resolve on that platform for the sake of one header. */
+export function encodeDeviceHeader(payload: Record<string, unknown>): string {
+  return base64url(utf8Bytes(JSON.stringify(payload)));
+}
+
+function utf8Bytes(text: string): number[] {
+  const bytes: number[] = [];
+  for (let i = 0; i < text.length; i++) {
+    let code = text.charCodeAt(i);
+    // Surrogate pair → one code point.
+    if (code >= 0xd800 && code <= 0xdbff && i + 1 < text.length) {
+      const low = text.charCodeAt(i + 1);
+      if (low >= 0xdc00 && low <= 0xdfff) {
+        code = 0x10000 + ((code - 0xd800) << 10) + (low - 0xdc00);
+        i++;
+      }
+    }
+    if (code < 0x80) {
+      bytes.push(code);
+    } else if (code < 0x800) {
+      bytes.push(0xc0 | (code >> 6), 0x80 | (code & 0x3f));
+    } else if (code < 0x10000) {
+      bytes.push(
+        0xe0 | (code >> 12),
+        0x80 | ((code >> 6) & 0x3f),
+        0x80 | (code & 0x3f)
+      );
+    } else {
+      bytes.push(
+        0xf0 | (code >> 18),
+        0x80 | ((code >> 12) & 0x3f),
+        0x80 | ((code >> 6) & 0x3f),
+        0x80 | (code & 0x3f)
+      );
+    }
+  }
+  return bytes;
+}
+
+const B64 =
+  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
+function base64url(bytes: number[]): string {
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const a = bytes[i] ?? 0;
+    const b = i + 1 < bytes.length ? bytes[i + 1] : undefined;
+    const c = i + 2 < bytes.length ? bytes[i + 2] : undefined;
+    out += B64[a >> 2];
+    out += B64[((a & 0x03) << 4) | ((b ?? 0) >> 4)];
+    if (b === undefined) break;
+    out += B64[((b & 0x0f) << 2) | ((c ?? 0) >> 6)];
+    if (c === undefined) break;
+    out += B64[c & 0x3f];
+  }
+  // No padding: base64url as the server decodes it (it re-pads itself).
+  return out;
+}

package/src/errors.ts

@@ -0,0 +1,69 @@
+export class RevnixError extends Error {
+  readonly status: number;
+
+  constructor(status: number, message: string) {
+    super(message);
+    this.name = "RevnixError";
+    this.status = status;
+  }
+
+  /** Transient failures worth retrying (network, timeout, rate limit, 5xx).
+   *  4xx other than 429 are the caller's fault and won't fix themselves. */
+  get isRetryable(): boolean {
+    return this.status === 0 || this.status === 429 || this.status >= 500;
+  }
+}
+
+/** POST /v1/purchases returned 409: the store token belongs to another
+ *  customer and the app's transfer behavior is "block". Surface this to the
+ *  user as "this subscription is linked to a different account". */
+export class PurchaseBlockedError extends RevnixError {
+  constructor(message: string) {
+    super(409, message);
+    this.name = "PurchaseBlockedError";
+  }
+}
+
+/** C7: the request didn't complete within the configured timeout (default
+ *  10s). `fetch` has no default timeout on React Native / browsers, so without
+ *  this a slow or dead backend would hang the app until the OS TCP timeout. */
+export class RevnixTimeoutError extends RevnixError {
+  constructor(message = "Revnix request timed out") {
+    super(0, message);
+    this.name = "RevnixTimeoutError";
+  }
+}
+
+/** C7: the request never reached the server (offline, DNS/TLS failure, captive
+ *  portal). Distinct from an HTTP error so callers can show an offline state
+ *  instead of treating it as a bug. */
+export class RevnixNetworkError extends RevnixError {
+  constructor(message = "Revnix request failed to reach the server") {
+    super(0, message);
+    this.name = "RevnixNetworkError";
+  }
+}
+
+/** L4: the API returned 401/403 — the key is missing, revoked, or the wrong
+ *  kind (e.g. a secret key where a public key is required) — or the SDK
+ *  refused locally before the network for the same reason (identify()/alias()
+ *  on a publishable key). Retrying is pointless; the fix is reconfiguration,
+ *  so surface this to the developer. */
+export class RevnixAuthError extends RevnixError {
+  constructor(status: number, message: string) {
+    super(status, message);
+    this.name = "RevnixAuthError";
+  }
+}
+
+/** C7: the API returned 429 (rate limited). `retryAfterMs` mirrors the
+ *  server's Retry-After header when present — back off at least that long. */
+export class RevnixRateLimitError extends RevnixError {
+  readonly retryAfterMs?: number;
+
+  constructor(message: string, retryAfterMs?: number) {
+    super(429, message);
+    this.name = "RevnixRateLimitError";
+    this.retryAfterMs = retryAfterMs;
+  }
+}

package/src/iap.ts

@@ -0,0 +1,137 @@
+import type { RegisterPurchaseInput, Store } from "./types.js";
+
+// Glue for react-native-iap: turn its purchase object into the
+// RegisterPurchaseInput the Revnix API expects. Structurally typed so the
+// SDK carries no dependency on react-native-iap itself.
+//
+// Token semantics per store (must match what the store webhook reports, or
+// client-register and webhook won't dedupe):
+//   Apple  → originalTransactionId  (StoreKit 2 originalTransactionIdentifierIOS)
+//   Google → purchaseToken
+
+export interface IapPurchase {
+  productId: string;
+  transactionId?: string | null;
+  /** Unix ms. */
+  transactionDate?: number | null;
+  /** Android purchase token. react-native-iap v13+ also sets it on iOS,
+   *  where it is the StoreKit 2 JWS — not the token Revnix needs, but the
+   *  proof it wants (`signedTransactionInfo`), so the Apple branch picks it
+   *  up from here when it has the JWS shape. */
+  purchaseToken?: string | null;
+  /** StoreKit 2 JWS (`VerificationResult.jwsRepresentation`), for IAP
+   *  libraries that expose it under its own name. */
+  jwsRepresentation?: string | null;
+  originalTransactionIdentifierIOS?: string | null;
+}
+
+// A JWS is three dot-separated base64url segments. Older react-native-iap
+// versions put other receipt shapes in purchaseToken on iOS — shape-check so
+// only a real JWS is sent as proof (the server rejects a malformed one).
+const JWS_SHAPE = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+
+function jwsFromIap(purchase: IapPurchase): string | undefined {
+  for (const candidate of [purchase.jwsRepresentation, purchase.purchaseToken]) {
+    if (candidate && JWS_SHAPE.test(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+// REV-200 (CTO-R2 M25): base64url → string without atob (not available on
+// every React Native runtime). The ids read from the payload are ASCII;
+// multi-byte content is never consulted.
+const B64_ALPHABET =
+  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+function base64UrlDecode(segment: string): string {
+  const b64 = segment.replace(/-/g, "+").replace(/_/g, "/");
+  let out = "";
+  let buffer = 0;
+  let bits = 0;
+  for (const ch of b64) {
+    const idx = B64_ALPHABET.indexOf(ch);
+    if (idx === -1) continue; // padding / stray characters
+    buffer = (buffer << 6) | idx;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      out += String.fromCharCode((buffer >> bits) & 0xff);
+    }
+  }
+  return out;
+}
+
+// The JWS payload's own ids — read WITHOUT verifying the signature, which is
+// fine here: the server verifies the chain and only trusts the proof when the
+// verified payload's ids match what we send. Reading them locally is exactly
+// how we make them match.
+function jwsPayload(
+  jws: string
+): { originalTransactionId?: string; transactionId?: string } | undefined {
+  try {
+    const segment = jws.split(".")[1];
+    if (!segment) return undefined;
+    const parsed: unknown = JSON.parse(base64UrlDecode(segment));
+    return typeof parsed === "object" && parsed !== null
+      ? (parsed as { originalTransactionId?: string; transactionId?: string })
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function purchaseInputFromIap(
+  purchase: IapPurchase,
+  source: Store,
+  extras?: { expiresAt?: number; rawPayload?: unknown }
+): RegisterPurchaseInput {
+  if (source === "apple") {
+    const transactionId = purchase.transactionId;
+    if (!transactionId) {
+      throw new Error("Revnix: Apple purchase is missing transactionId");
+    }
+    const jws = jwsFromIap(purchase);
+    const proof = jws ? jwsPayload(jws) : undefined;
+    return {
+      source,
+      // REV-200 (M25): token precedence. The old fallback (original id
+      // missing → the renewal's own transactionId) minted a purchaseKey the
+      // store webhook would never produce — a second purchase.completed and
+      // double-counted revenue — AND failed the server's proof check, which
+      // requires the verified JWS's originalTransactionId to EQUAL this
+      // token, silently downgrading a proof-carrying purchase to
+      // provisional. The JWS payload names the true original id, so when a
+      // JWS is present it wins; the IAP library's field is next; the bare
+      // transactionId remains only for the proof-less first purchase, where
+      // original === transaction anyway.
+      token:
+        proof?.originalTransactionId ??
+        purchase.originalTransactionIdentifierIOS ??
+        transactionId,
+      productId: purchase.productId,
+      transactionId,
+      occurredAt: purchase.transactionDate ?? undefined,
+      expiresAt: extras?.expiresAt,
+      rawPayload: extras?.rawPayload,
+      // Without this the purchase lands PROVISIONAL (see
+      // RegisterPurchaseInput.signedTransactionInfo).
+      signedTransactionInfo: jws,
+    };
+  }
+  const token = purchase.purchaseToken;
+  if (!token) {
+    throw new Error("Revnix: Google purchase is missing purchaseToken");
+  }
+  return {
+    source,
+    token,
+    productId: purchase.productId,
+    // The Google webhook adapter (convex/lib/google.ts) reports the
+    // purchaseToken as the transactionId — send the same, never the Play
+    // orderId, or client-register and webhook won't share a purchaseKey.
+    transactionId: token,
+    occurredAt: purchase.transactionDate ?? undefined,
+    expiresAt: extras?.expiresAt,
+    rawPayload: extras?.rawPayload,
+  };
+}

package/src/implicit.ts

@@ -0,0 +1,129 @@
+// REV-272: implicit placements — the six moments the SDK reports on its own.
+//
+// A placement is normally a location the HOST resolves by name, so every new
+// place a paywall could appear costs a code change and a release. Six moments
+// are the same in every app and visible to the SDK without the host saying
+// anything, so an operator can attach a paywall to them from the dashboard
+// alone. This module owns the vocabulary and the platform-lifecycle seam;
+// client.ts owns the firing.
+//
+// Mirrors convex/lib/implicitPlacements.ts in revnix-app — the backend is the
+// source of truth for the key spellings, and a mismatch here is silent (the
+// server 400s a key it does not know, and the moment is simply never
+// configured), so the two lists are checked against each other in the tests.
+
+/** The six reserved keys. Lowercase throughout: a placement key must match
+ *  `^[a-z0-9][a-z0-9._-]{0,63}$` server-side, which is why this is
+ *  `deeplink_open` and not Superwall's `deepLink_open`. */
+export const IMPLICIT_PLACEMENTS = [
+  "app_install",
+  "app_launch",
+  "session_start",
+  "deeplink_open",
+  "paywall_decline",
+  "transaction_abandon",
+] as const;
+
+export type ImplicitPlacement = (typeof IMPLICIT_PLACEMENTS)[number];
+
+/** Why a trigger came back with no paywall — as opposed to a placement that
+ *  resolved fine and simply has none attached, which is `null`. */
+export type ImplicitSkipReason = "not_configured" | "same_paywall";
+
+/** The one moment the SDK cannot see unaided: the URL that opened the app is
+ *  delivered to the host's own entry point, and an SDK trying to intercept it
+ *  would be fighting the host's router. Call `handleDeepLink(url)`. */
+export const HOST_CALL_PLACEMENT: ImplicitPlacement = "deeplink_open";
+
+/** The placementKey `handleDeepLink` reports for a dashboard QR/link preview
+ *  (`<scheme>://revnix-preview?revnix_preview=<token>`) — not one of the six
+ *  above, and never sent to /v1/placements/triggered. */
+export const PREVIEW_PLACEMENT_KEY = "revnix_preview";
+
+/** How long the app must have been backgrounded for the return to count as a
+ *  new session rather than an app switch. Matches Superwall's own definition
+ *  so a team moving over gets the same numbers. */
+export const DEFAULT_SESSION_TIMEOUT_MS = 30 * 60_000;
+
+/** How long after a FAILED /v1/config read the SDK waits before asking again.
+ *  See RevnixClient.implicitConfigRetryAt. */
+export const IMPLICIT_CONFIG_RETRY_MS = 60_000;
+
+/** Where the app is. Both transitions matter: a session is defined by how
+ *  long the app was in the BACKGROUND, which cannot be known from foreground
+ *  events alone — "time since the last return" would mint a session after 35
+ *  minutes of continuous use plus a three-second app switch. */
+export type RevnixAppState = "foreground" | "background";
+
+/** The platform seam. The SDK ships a browser implementation (see
+ *  `browserLifecycle`); React Native passes an adapter over `AppState`, which
+ *  is a few lines and keeps `react-native` out of this package's dependencies:
+ *
+ *      lifecycle: {
+ *        onStateChange: (handler) => {
+ *          const sub = AppState.addEventListener("change", (s) => {
+ *            handler(s === "active" ? "foreground" : "background");
+ *          });
+ *          return () => sub.remove();
+ *        },
+ *      }
+ */
+export interface RevnixLifecycle {
+  /** Subscribe to app state transitions. Returns an unsubscribe. Called at
+   *  most once per client; the client calls the unsubscribe from dispose().
+   *  Repeated reports of the same state are harmless. */
+  onStateChange(handler: (state: RevnixAppState) => void): () => void;
+}
+
+/** Foreground detection in a browser tab. `visibilitychange` rather than
+ *  `focus`: switching windows fires focus without the page ever having been
+ *  hidden, which would mint sessions for someone alt-tabbing. Returns null
+ *  where there is no document (React Native, Node, SSR) — the host passes its
+ *  own adapter there. */
+export function browserLifecycle(): RevnixLifecycle | null {
+  // Structurally typed rather than leaning on the DOM lib: this package
+  // compiles without `lib: dom` (it has to run under React Native and Node),
+  // the same reason device.ts reaches for `navigator` through a cast.
+  interface VisibilityDocument {
+    visibilityState?: string;
+    addEventListener?: (type: string, listener: () => void) => void;
+    removeEventListener?: (type: string, listener: () => void) => void;
+  }
+  const doc = (globalThis as { document?: VisibilityDocument }).document;
+  if (
+    !doc ||
+    typeof doc.addEventListener !== "function" ||
+    typeof doc.removeEventListener !== "function"
+  ) {
+    return null;
+  }
+  const add = doc.addEventListener.bind(doc);
+  const remove = doc.removeEventListener.bind(doc);
+  return {
+    onStateChange(handler) {
+      const listener = () => {
+        handler(doc.visibilityState === "visible" ? "foreground" : "background");
+      };
+      add("visibilitychange", listener);
+      return () => remove("visibilitychange", listener);
+    },
+  };
+}
+
+/** What the host is handed when a moment resolved to a paywall. */
+export interface ImplicitTrigger<TResolution> {
+  /** Which of the six fired, or `PREVIEW_PLACEMENT_KEY` for a dashboard preview. */
+  placement: ImplicitPlacement | typeof PREVIEW_PLACEMENT_KEY;
+  /** The resolution, exactly as `resolvePlacement` would have returned it —
+   *  offering, paywall, experiment and targeting all included. */
+  resolution: TResolution;
+}
+
+/** The trigger response body. The resolve shape plus the two fields the
+ *  trigger route adds. */
+export interface ImplicitTriggerResponse {
+  skipReason: ImplicitSkipReason | null;
+  /** True when this call appended a NEW ledger event (false for a duplicate,
+   *  and for the three moments that reuse an event reported elsewhere). */
+  recorded: boolean;
+}

package/src/index.ts

@@ -0,0 +1,82 @@
+import { RevnixClient } from "./client.js";
+import { setLocale } from "./blocks/locale.js";
+import type { RevnixConfig } from "./types.js";
+
+export { RevnixClient } from "./client.js";
+export {
+  PurchaseBlockedError,
+  RevnixAuthError,
+  RevnixError,
+  RevnixNetworkError,
+  RevnixRateLimitError,
+  RevnixTimeoutError,
+} from "./errors.js";
+export { purchaseInputFromIap, type IapPurchase } from "./iap.js";
+export { memoryStorage, generateAnonymousId } from "./storage.js";
+export { SDK_VERSION } from "./version.js";
+export { DEVICE_HEADER, encodeDeviceHeader } from "./device.js";
+export {
+  browserLifecycle,
+  DEFAULT_SESSION_TIMEOUT_MS,
+  HOST_CALL_PLACEMENT,
+  IMPLICIT_PLACEMENTS,
+  PREVIEW_PLACEMENT_KEY,
+  type ImplicitPlacement,
+  type ImplicitSkipReason,
+  type ImplicitTrigger,
+  type ImplicitTriggerResponse,
+  type RevnixLifecycle,
+} from "./implicit.js";
+export type {
+  AdRevenue,
+  AliasResult,
+  CustomerEntitlements,
+  DeviceFacts,
+  Entitlement,
+  EntitlementSource,
+  Environment,
+  IdentifyResult,
+  IdentifyStrategy,
+  IdentityInfo,
+  ImplicitResolution,
+  LastDeepLink,
+  MmpAttribution,
+  MmpProvider,
+  PaywallConfig,
+  PaywallInteraction,
+  PaywallPurchaseOutcome,
+  PlacementOffering,
+  PlacementPackage,
+  PlacementPaywall,
+  PlacementProduct,
+  PlacementResolution,
+  RegisterPurchaseInput,
+  RegisterPurchaseResult,
+  RevnixAttribution,
+  RevnixConfig,
+  RevnixDiagnostic,
+  RevnixStorage,
+  Store,
+} from "./types.js";
+
+let instance: RevnixClient | null = null;
+
+/** Singleton facade — configure once at app start, then import `Revnix`
+ *  anywhere. Prefer constructing RevnixClient directly in tests. */
+export const Revnix = {
+  configure(config: RevnixConfig): RevnixClient {
+    // REV-204 (L10): dev fast-refresh re-runs configure(); without teardown
+    // the old client kept its retry/prefetch background work running
+    // alongside the new one.
+    instance?.dispose();
+    instance = new RevnixClient(config);
+    return instance;
+  },
+  setLocale,
+  get client(): RevnixClient {
+    if (!instance) {
+      throw new Error("Revnix: call Revnix.configure(...) before use");
+    }
+    return instance;
+  },
+};

package/src/storage.ts

@@ -0,0 +1,92 @@
+import type { RevnixStorage } from "./types.js";
+
+/** Default storage: survives only the current JS runtime. Real apps must
+ *  pass a persistent adapter (MMKV, AsyncStorage, localStorage) or every
+ *  launch becomes a new anonymous customer. */
+export function memoryStorage(): RevnixStorage {
+  const map = new Map<string, string>();
+  return {
+    getItem: (key) => map.get(key) ?? null,
+    setItem: (key, value) => {
+      map.set(key, value);
+    },
+  };
+}
+
+// CTO-SCALE-REVIEW M5: what actually backs the client when `storage` is
+// omitted. Memory-only used to be the silent default — every launch became a
+// new anonymous customer + a new install report (analytics inflated by the
+// DAU multiplier, purchases orphaned on the previous launch's id). Now:
+//   1. explicit adapter → use it (unchanged);
+//   2. web (localStorage usable) → use localStorage automatically;
+//   3. truly nothing (React Native without an adapter) → memory, but WARN
+//      loudly, and the client skips install reporting (see client.ts) so a
+//      forgotten config line can't fabricate fleet-wide installs.
+export function resolveStorage(configured?: RevnixStorage): {
+  storage: RevnixStorage;
+  persistent: boolean;
+} {
+  if (configured) return { storage: configured, persistent: true };
+
+  const ls = (globalThis as { localStorage?: Storage }).localStorage;
+  if (ls) {
+    try {
+      const probe = "revnix.__probe";
+      ls.setItem(probe, "1");
+      ls.removeItem(probe);
+      return {
+        storage: {
+          getItem: (key) => ls.getItem(key),
+          setItem: (key, value) => {
+            ls.setItem(key, value);
+          },
+        },
+        persistent: true,
+      };
+    } catch {
+      // Private mode / quota quirks — fall through to memory.
+    }
+  }
+
+  console.warn(
+    "[revnix] No `storage` adapter configured and no localStorage available; " +
+      "the customer id lives in memory only. Every launch will look like a NEW " +
+      "anonymous customer: prior purchases won't be attached and analytics " +
+      "would be inflated, so install reporting and experiment enrollment are " +
+      "disabled. Pass a persistent adapter (AsyncStorage/MMKV on React " +
+      "Native) to fix this."
+  );
+  return { storage: memoryStorage(), persistent: false };
+}
+
+function randomHex(byteLength: number): string {
+  const bytes = new Uint8Array(byteLength);
+  const cryptoObj = (globalThis as { crypto?: Crypto }).crypto;
+  // L2: no Math.random fallback — a guessable customer id is readable by
+  // anyone holding the public key, so failing loudly beats failing silently.
+  // Every supported runtime (browsers, RN ≥0.72 via Hermes, Node ≥19) exposes
+  // getRandomValues; older Node needs `globalThis.crypto = require("crypto").webcrypto`.
+  if (!cryptoObj?.getRandomValues) {
+    throw new Error(
+      "[revnix] crypto.getRandomValues is unavailable in this runtime; " +
+        "cannot generate a secure customer id. Polyfill globalThis.crypto " +
+        "or pass an explicit `customerId` in configure()."
+    );
+  }
+  cryptoObj.getRandomValues(bytes);
+  return [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+export function generateAnonymousId(): string {
+  return `rvx_anon_${randomHex(16)}`;
+}
+
+/** One id per paywall display (REV-094) — the backend dedupes retries on it
+ *  while genuine repeat views (fresh ids) count separately. */
+export function generateViewId(): string {
+  return `rvx_view_${randomHex(16)}`;
+}
+
+export function generateEventId(): string {
+  return `rvx_evt_${randomHex(16)}`;
+}