react-native-revnix 1.4.0

package/dist/esm/device.js

@@ -0,0 +1,130 @@
+// 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.
+/** 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";
+/** 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() {
+    const nav = globalThis.navigator;
+    const facts = {};
+    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.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) {
+    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) {
+    const out = {};
+    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) {
+    return base64url(utf8Bytes(JSON.stringify(payload)));
+}
+function utf8Bytes(text) {
+    const bytes = [];
+    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) {
+    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/dist/esm/errors.js

@@ -0,0 +1,59 @@
+export class RevnixError extends Error {
+    constructor(status, message) {
+        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() {
+        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) {
+        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, message) {
+        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 {
+    constructor(message, retryAfterMs) {
+        super(429, message);
+        this.name = "RevnixRateLimitError";
+        this.retryAfterMs = retryAfterMs;
+    }
+}

package/dist/esm/iap.js

@@ -0,0 +1,101 @@
+// 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) {
+    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) {
+    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) {
+    try {
+        const segment = jws.split(".")[1];
+        if (!segment)
+            return undefined;
+        const parsed = JSON.parse(base64UrlDecode(segment));
+        return typeof parsed === "object" && parsed !== null
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function purchaseInputFromIap(purchase, source, extras) {
+    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/dist/esm/implicit.js

@@ -0,0 +1,63 @@
+// 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",
+];
+/** 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 = "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 * 60000;
+/** How long after a FAILED /v1/config read the SDK waits before asking again.
+ *  See RevnixClient.implicitConfigRetryAt. */
+export const IMPLICIT_CONFIG_RETRY_MS = 60000;
+/** 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() {
+    const doc = globalThis.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);
+        },
+    };
+}

package/dist/esm/index.js

@@ -0,0 +1,29 @@
+import { RevnixClient } from "./client.js";
+import { setLocale } from "./blocks/locale.js";
+export { RevnixClient } from "./client.js";
+export { PurchaseBlockedError, RevnixAuthError, RevnixError, RevnixNetworkError, RevnixRateLimitError, RevnixTimeoutError, } from "./errors.js";
+export { purchaseInputFromIap } 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, } from "./implicit.js";
+let instance = null;
+/** Singleton facade — configure once at app start, then import `Revnix`
+ *  anywhere. Prefer constructing RevnixClient directly in tests. */
+export const Revnix = {
+    configure(config) {
+        // 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() {
+        if (!instance) {
+            throw new Error("Revnix: call Revnix.configure(...) before use");
+        }
+        return instance;
+    },
+};

package/dist/esm/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/dist/esm/storage.js

@@ -0,0 +1,78 @@
+/** 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() {
+    const map = new Map();
+    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) {
+    if (configured)
+        return { storage: configured, persistent: true };
+    const ls = globalThis.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) {
+    const bytes = new Uint8Array(byteLength);
+    const cryptoObj = globalThis.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() {
+    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() {
+    return `rvx_view_${randomHex(16)}`;
+}
+export function generateEventId() {
+    return `rvx_evt_${randomHex(16)}`;
+}

package/dist/esm/types.js

@@ -0,0 +1,4 @@
+// Response and input types for the Revnix /v1 API. These mirror the shapes
+// returned by convex/http.ts in revnix-app — the backend is the source of
+// truth; update here when the API surface changes.
+export {};