@joryio/react-native-sdk 0.0.0-stage → 1.3.0

package/lib/index.js

@@ -0,0 +1,1928 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ecommerce = exports.MAX_PRE_INIT_CALLS = void 0;
+const react_native_1 = require("react-native");
+const { JoryioModule } = react_native_1.NativeModules;
+const MODULE_MISSING_MESSAGE = '@joryio/react-native-sdk: NativeModule not found. ' +
+    'Make sure you ran `pod install` (iOS) / rebuilt the app (Android). ' +
+    'All Joryio calls will be no-ops until the native module is linked.';
+// Degrade instead of crashing the whole JS bundle on import: if the native
+// module isn't linked, warn once and turn every method into a safe no-op.
+const isModuleAvailable = !!JoryioModule;
+if (!isModuleAvailable) {
+    // eslint-disable-next-line no-console
+    console.warn(MODULE_MISSING_MESSAGE);
+}
+// ─── Event Emitter ───────────────────────────────────────────────────────────
+// Only construct the emitter when the native module exists — NativeEventEmitter
+// throws if handed a null module.
+const emitter = isModuleAvailable ? new react_native_1.NativeEventEmitter(JoryioModule) : null;
+/**
+ * One meaning for "no capabilities" on both platforms: an omitted or empty
+ * list is NOT DECLARED (null). Android already read `[]` that way; iOS
+ * forwarded it as "this app can draw nothing", which targets every campaign
+ * away from the device.
+ */
+function normalizeCapabilities(capabilities) {
+    const declared = (Array.isArray(capabilities) ? capabilities : []).filter((c) => typeof c === 'string' && c.length > 0);
+    return declared.length > 0 ? declared : null;
+}
+// ─── Host-input guards (contract item 19) ────────────────────────────────────
+//
+// Null or undefined from host code must never crash the app and never disable
+// the SDK. JavaScript does not enforce the TypeScript signatures, and a null
+// reaching a non-null Kotlin parameter is a NullPointerException on the native
+// modules thread - a crash in a release build, not a red box. So every value
+// is checked HERE, before the bridge; the bridges also take nullable
+// parameters, as the second line of defence.
+function warn(message) {
+    // eslint-disable-next-line no-console
+    console.warn(`[Joryio] ${message}`);
+}
+/** A non-empty string, or a warning naming the call and the argument. */
+function requireString(caller, name, value) {
+    if (typeof value === 'string' && value.length > 0)
+        return true;
+    warn(`${caller}() needs a non-empty string ${name}; ignored.`);
+    return false;
+}
+/** A plain object (not null, not an array). */
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * An e-commerce id or label: not empty and not only whitespace, the same as
+ * the native trackers. (Event names are different: a whitespace-only name is
+ * the server's to judge - requireString does not trim.)
+ */
+function isNonBlankString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+/** Properties as a plain object; null, undefined or a non-object means none. */
+function plainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+/**
+ * A tracking consent value in the one spelling every SDK uses, or null.
+ *
+ * Case-insensitive, because the two bridges were not: Android matched
+ * `'Denied'` and iOS ignored it, so the same config started one platform
+ * denied and the other with no decision at all.
+ */
+function parseConsent(value) {
+    if (typeof value !== 'string')
+        return null;
+    const lower = value.trim().toLowerCase();
+    return lower === 'granted' || lower === 'denied' || lower === 'pending' ? lower : null;
+}
+/**
+ * The config as the bridges receive it: null values left out (see
+ * withoutNullValues) and `trackingConsent` in its lowercase spelling. An
+ * unrecognised consent is left out with a warning - UNSET, never a guess -
+ * so the native SDK keeps whatever decision it has stored.
+ */
+function nativeConfig(config) {
+    const out = withoutNullValues(config);
+    // Lower-cased like trackingConsent: iOS matched 'Warn' against nothing and
+    // fell back to the enableDebug level, while Android upper-cased it.
+    if (typeof out.logLevel === 'string')
+        out.logLevel = out.logLevel.trim().toLowerCase();
+    if ('trackingConsent' in out) {
+        const parsed = parseConsent(out.trackingConsent);
+        if (parsed === null) {
+            warn(`initialize() trackingConsent takes 'granted', 'denied' or 'pending', not ` +
+                `'${String(out.trackingConsent)}'; left unset.`);
+            delete out.trackingConsent;
+        }
+        else {
+            out.trackingConsent = parsed;
+        }
+    }
+    return out;
+}
+/**
+ * The config with every null / undefined value left out, so the native SDK
+ * applies its own default for it. A present-but-null key used to reach the
+ * Android bridge, whose `getInt` threw - initialize() failed and the SDK was
+ * off for the whole session because of a `batchSize: null`.
+ */
+function withoutNullValues(config) {
+    const out = {};
+    for (const [key, value] of Object.entries(plainObject(config))) {
+        if (value !== null && value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+/** A number that is NaN or +/-Infinity. */
+function isNonFiniteNumber(value) {
+    return typeof value === 'number' && !Number.isFinite(value);
+}
+/**
+ * An object the bridge serializes by its own enumerable keys - a class
+ * instance, a MobX observable, a model object - but not a Date, which it
+ * serializes as a value. Scanned for NaN like a plain object.
+ */
+function isKeyedObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) && !(value instanceof Date);
+}
+/** Plain `{}` / `Object.create(null)` objects - not Dates, class instances or arrays. */
+function isPlainObject(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/** Nesting followed when dropping non-finite numbers; the backend allows 5. */
+const MAX_FINITE_SCAN_DEPTH = 10;
+/**
+ * The value with every NaN / Infinity left out (contract v5 49): an object
+ * key holding one is omitted, an array element is removed, and the call goes
+ * ahead with the rest. Each drop is reported once per call through `dropped`.
+ *
+ * Not left to the natives, because the bridge changes them on the way: the
+ * JSON bridge turns NaN into `null`, which means UNSET to an attribute write,
+ * so `setAttribute('score', NaN)` erased the stored score.
+ */
+function withoutNonFinite(value, path, dropped, depth = 0) {
+    if (depth > MAX_FINITE_SCAN_DEPTH)
+        return value;
+    if (Array.isArray(value)) {
+        const out = [];
+        value.forEach((item, i) => {
+            if (isNonFiniteNumber(item))
+                dropped.push(`${path}[${i}]`);
+            else
+                out.push(withoutNonFinite(item, `${path}[${i}]`, dropped, depth + 1));
+        });
+        return out;
+    }
+    if (isKeyedObject(value)) {
+        const droppedBefore = dropped.length;
+        const out = {};
+        for (const [key, item] of Object.entries(value)) {
+            const at = path ? `${path}.${key}` : key;
+            if (isNonFiniteNumber(item))
+                dropped.push(at);
+            else
+                out[key] = withoutNonFinite(item, at, dropped, depth + 1);
+        }
+        // A class instance (a cart line built from `class Line`, a MobX
+        // observable) is scanned too: it reached the bridge with its NaN, which
+        // Android read as a quantity of 0 and iOS as none. Copied into a plain
+        // object only when something was dropped - the bridge sends the same own
+        // keys either way - and otherwise passed on untouched.
+        if (!isPlainObject(value) && dropped.length === droppedBefore)
+            return value;
+        return out;
+    }
+    return value;
+}
+/** {@link withoutNonFinite} for a properties object, warning once naming the keys. */
+function finiteProperties(caller, properties) {
+    const dropped = [];
+    const out = withoutNonFinite(properties, '', dropped);
+    if (dropped.length > 0) {
+        warn(`${caller}() left out ${dropped.join(', ')}: NaN and Infinity are not valid values.`);
+    }
+    return out;
+}
+/**
+ * A host callback that can never throw into the event dispatch (contract
+ * items 34 and 56). React Native runs every listener of an event in one loop:
+ * a callback that threw - a renderer meeting a message shape it did not
+ * expect - was a fatal JS error in a release build and skipped every other
+ * listener of the same event. A returned promise that rejects is caught too.
+ */
+function guardedCallback(name, callback) {
+    const report = (err) => {
+        // eslint-disable-next-line no-console
+        console.warn(`[Joryio] your ${name} callback threw; the SDK carries on.`, err);
+    };
+    return (event) => {
+        try {
+            const result = callback(event);
+            if (result !== null && typeof result === 'object' && typeof result.then === 'function') {
+                result.then(undefined, report);
+            }
+        }
+        catch (err) {
+            report(err);
+        }
+    };
+}
+/**
+ * An APNs device token: hex, 32 bytes or more. Joryio sends iOS push through
+ * APNs, so an FCM registration token registered on iOS replaces the device's
+ * working APNs token with one APNs refuses - and React Native Firebase's
+ * onTokenRefresh hands the FCM token over at every app start on iOS.
+ */
+const APNS_TOKEN = /^(?:[0-9a-fA-F]{2}){32,100}$/;
+/** The highest |rating| both native trackers can take: they hold it as a 32-bit Int. */
+const MAX_RATING_MAGNITUDE = 2147483647;
+// ─── SDK Class ───────────────────────────────────────────────────────────────
+/**
+ * How long a value-returning call waits for initialize() before giving up and
+ * returning its documented "not available" value. See _awaitReady.
+ */
+const READY_TIMEOUT_MS = 5000;
+/**
+ * Most fire-and-forget calls held while initialize() has not completed. Beyond
+ * it the OLDEST are dropped. The same cap and policy as every native SDK's
+ * pre-initialization buffer (contract item 20), so a call is not kept by one
+ * layer and dropped by the next. Before 1.3.0 the hold was unbounded: an app
+ * that never called initialize() grew it for the life of the process.
+ */
+exports.MAX_PRE_INIT_CALLS = 1000;
+/**
+ * Longest wait for native's answer about the decisions stored by an earlier
+ * launch before initialize() goes ahead without it. Native answers from
+ * storage at once; this only guards against a bridge that never settles.
+ */
+const STORED_DECISIONS_TIMEOUT_MS = 3000;
+/** A full pre-init hold drops the oldest of these first, in this order (contract v5 51). */
+const EVICTION_ORDER = ['data', 'identity', 'token', 'control'];
+const DISCARDED_BY_WITHDRAWN_CONSENT = ['data'];
+const DISCARDED_BY_WIPE = ['data', 'identity', 'token'];
+class JoryioSDK {
+    constructor() {
+        /** True once initialize() has completed SUCCESSFULLY. */
+        this._initialized = false;
+        /**
+         * True when initialize() ran and FAILED. Distinct from "not yet initialized":
+         * that one is temporary and worth waiting for, this one never resolves, so
+         * every subsequent call must degrade instead of waiting or throwing.
+         */
+        this._initFailed = false;
+        /**
+         * Fire-and-forget calls made before initialize() succeeded, in call order,
+         * each with its {@link CallKind}. An opt-out or a denial made later
+         * discards the held `data` calls, and a wipe also the held `identity` and
+         * `token` calls, exactly as the native SDKs discard what they hold. A
+         * `withdrawal` is kept through all three and delivered (contract v4 36).
+         */
+        this._pending = [];
+        /** The initialize() call in progress, if any. A second call joins it. */
+        this._initInFlight = null;
+        this._warnedPendingOverflow = false;
+        /**
+         * A wipeData() was handed to native before its initialize(), which runs it
+         * inside init. A token set after it must stay held here and follow init:
+         * native would apply it before that wipe, which retires it.
+         */
+        this._wipeHandedToNative = false;
+        /**
+         * The two privacy switches as decided by calls made in this process
+         * before initialize() succeeded (contract v7 73): set by optOut()/optIn()
+         * and updateConsent('denied')/'granted' exactly as native records them -
+         * 'pending' never reopens a denial. null = no decision made here yet.
+         */
+        this._preInitOptedOut = null;
+        this._preInitDenied = null;
+        /**
+         * The two switches as the config of the initialize() IN FLIGHT sets them
+         * (contract v9 91): `trackingConsent: 'granted'` lifts a stored denial and
+         * 'denied' refuses; `optOut: true` refuses, `optOut: false` lifts nothing.
+         * Native applies them when that init runs, so a call made meanwhile is
+         * judged by them, between this process's decisions and the stored ones.
+         * null = the config says nothing; both cleared when that init settles.
+         */
+        this._initConfigOptedOut = null;
+        this._initConfigDenied = null;
+        /**
+         * The same two switches as STORED on the device by an earlier launch
+         * (contract v8 83), read from native when this module loads - both natives
+         * answer isUserOptedOut()/getTrackingConsent() from storage before their own
+         * initialize() (contract item 44). null until native has answered.
+         *
+         * Without them, `track('x'); optIn(); initialize()` for a person whose
+         * opt-out was stored last launch sent x: the call was held here, optIn went
+         * to native straight away, and x reached native only after init, when the
+         * opt-out was already lifted.
+         */
+        this._storedOptedOut = null;
+        this._storedDenied = null;
+        /** Settles once the stored decisions are known (or could not be read). */
+        this._storedKnown = Promise.resolve();
+        this._warnedDroppedWhileOptedOut = false;
+        /** Live onInAppMessage subscriptions. Rendering is handed to JS only while > 0. */
+        this._inAppListeners = 0;
+        this._ready = new Promise((resolve) => {
+            this._markReady = resolve;
+        });
+        if (isModuleAvailable)
+            this._storedKnown = this._readStoredDecisions();
+    }
+    /**
+     * Ask native, first thing, for the decisions an earlier launch stored. The
+     * first call this module makes, so native answers before any decision made
+     * in this process reaches it. Never rejects and never waits forever: an
+     * unreadable answer counts as "nothing stored", which leaves native's own
+     * judgement at replay - the behaviour before this read existed.
+     */
+    async _readStoredDecisions() {
+        let timer;
+        try {
+            // Both asked synchronously, here in the constructor: native serves
+            // calls in the order JS makes them, so these reads are answered before
+            // any decision or initialize() made in this process reaches it.
+            const asked = Promise.all([JoryioModule.isUserOptedOut?.(), JoryioModule.getTrackingConsent?.()]);
+            const read = asked.then(([optedOut, consent]) => [
+                optedOut === true,
+                parseConsent(consent) === 'denied',
+            ]);
+            const answer = await Promise.race([
+                read,
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve(null), STORED_DECISIONS_TIMEOUT_MS);
+                    // Never keeps a host app's Jest run (or Node) alive on its own.
+                    timer.unref?.();
+                }),
+            ]);
+            if (answer === null) {
+                // eslint-disable-next-line no-console
+                console.warn('[Joryio] The stored privacy decisions could not be read in time; continuing without them.');
+            }
+            [this._storedOptedOut, this._storedDenied] = answer ?? [false, false];
+        }
+        catch (e) {
+            // eslint-disable-next-line no-console
+            console.warn('[Joryio] The stored privacy decisions could not be read.', e);
+            this._storedOptedOut = false;
+            this._storedDenied = false;
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+        this._settleStored();
+    }
+    /**
+     * Whether collecting is refused before initialize(): a decision made in this
+     * process wins over the stored one (it is later). 'unknown' while the stored
+     * one is still being read and could make the answer yes.
+     */
+    _refusedBeforeInit(at) {
+        const optedOut = at.optedOut ?? this._storedOptedOut;
+        const denied = at.denied ?? this._storedDenied;
+        if (optedOut === true || denied === true)
+            return true;
+        if (optedOut === null || denied === null)
+            return 'unknown';
+        return false;
+    }
+    /**
+     * Native has answered: drop the `data` calls held while its answer was
+     * unknown that were made while refused, as they would have been dropped
+     * at call time had the answer been there (contract v7 73).
+     */
+    _settleStored() {
+        const kept = [];
+        let dropped = false;
+        for (const call of this._pending) {
+            if (call.madeUnder === undefined) {
+                kept.push(call);
+                continue;
+            }
+            if (this._refusedBeforeInit(call.madeUnder) === true) {
+                dropped = true;
+                continue;
+            }
+            delete call.madeUnder;
+            kept.push(call);
+        }
+        this._pending = kept;
+        if (dropped)
+            this._warnDroppedWhileRefused();
+    }
+    /**
+     * An initialize() failed, so native never applied its config: the `data`
+     * calls judged with it while it was in flight are judged again by this
+     * process's decisions and the stored ones alone (contract v9 91).
+     */
+    _rejudgeWithoutInitConfig() {
+        const kept = [];
+        let dropped = false;
+        for (const call of this._pending) {
+            const at = call.madeInWindow;
+            if (at !== undefined) {
+                delete call.madeInWindow;
+                const refused = this._refusedBeforeInit(at);
+                if (refused === true) {
+                    dropped = true;
+                    continue;
+                }
+                if (refused === 'unknown')
+                    call.madeUnder = at;
+            }
+            kept.push(call);
+        }
+        this._pending = kept;
+        if (dropped)
+            this._warnDroppedWhileRefused();
+    }
+    _warnDroppedWhileRefused() {
+        if (this._warnedDroppedWhileOptedOut)
+            return;
+        this._warnedDroppedWhileOptedOut = true;
+        // eslint-disable-next-line no-console
+        console.warn('[Joryio] A call that collects data was made while tracking is opted out or consent is ' +
+            'denied; it is dropped and a later optIn() or grant does not send it.');
+    }
+    /**
+     * Wait for initialize(), but never forever.
+     *
+     * An unbounded await would be WORSE than the throw it replaces: a host app
+     * that forgets initialize() (or whose init failed) would hang on the first
+     * getter with no error to search for. On timeout the caller gets the same
+     * "not available" value it already gets when the native module is missing,
+     * plus a warning naming the actual cause.
+     *
+     * @returns true if the SDK became ready, false if it timed out.
+     */
+    async _awaitReady(caller) {
+        if (this._initialized)
+            return true;
+        if (this._initFailed)
+            return false;
+        const timedOut = Symbol('timeout');
+        let timer;
+        const result = await Promise.race([
+            this._ready,
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(timedOut), READY_TIMEOUT_MS);
+            }),
+        ]);
+        // Cleared either way: a timer left running after initialize() won the
+        // race keeps a host app's Jest run alive ("worker failed to exit").
+        if (timer !== undefined)
+            clearTimeout(timer);
+        if (result === timedOut) {
+            // eslint-disable-next-line no-console
+            console.warn(`[Joryio] ${caller}() was called but initialize() has not completed after ` +
+                `${READY_TIMEOUT_MS}ms - returning a default. Call Joryio.initialize() at app start.`);
+            return false;
+        }
+        // Readiness settles on a FAILED initialize() too (it must, or every waiter
+        // would hang). Settling is not success: answering true here sent a caller
+        // that was waiting when init failed on to the native module, which was
+        // never initialized - and a native promise that is never settled there
+        // (registerPushToken's completion, for one) hung the caller forever.
+        return this._initialized && !this._initFailed;
+    }
+    /**
+     * A privacy getter (isUserOptedOut, getTrackingConsent). Both native SDKs
+     * answer these from STORED state before their own initialize() (contract
+     * item 44), so before initialize() has been called - or after one that
+     * failed - native is asked straight away. They used to wait up to five
+     * seconds for an initialize() that might never come and then answer
+     * `false` / `null`, which reads as "not opted out" for a person whose
+     * opt-out is stored on the device.
+     *
+     * While an initialize() is in flight the answer waits for it, because a
+     * decision made in that window is queued behind it and native would not
+     * know it yet. Native is asked whatever the outcome (contract v6 65): when
+     * that init FAILS, the decisions held meanwhile have just been handed to
+     * native (_handHeldDecisionsToNative), so its stored answer is current. It
+     * used to answer the default `false` / `null` then without asking native.
+     */
+    async _queryDecision(caller, fallback, fn) {
+        if (!isModuleAvailable)
+            return fallback;
+        if (this._initInFlight !== null && !this._initialized)
+            await this._awaitReady(caller);
+        try {
+            const value = await fn();
+            return value ?? fallback;
+        }
+        catch (e) {
+            // eslint-disable-next-line no-console
+            console.warn(`[Joryio] ${caller}() failed`, e);
+            return fallback;
+        }
+    }
+    /**
+     * Route a fire-and-forget native call safely:
+     *  - no-op when the native module isn't linked,
+     *  - defer until initialize() resolves so we never hit native before init,
+     *  - swallow (and warn) native errors so a bad call can't crash the host app.
+     */
+    _dispatch(fn, kind = 'control', tag) {
+        if (!isModuleAvailable)
+            return;
+        if (this._initialized) {
+            this._invoke(fn);
+            return;
+        }
+        // Not ready yet - or initialize() FAILED: hold the call, in order, for the
+        // initialize() that succeeds. A failed init used to DROP every call made
+        // after it and discard everything held before it, so an app whose first
+        // initialize() failed (a wrong key from a remote config) and whose retry
+        // worked had lost its onInAppMessage hand-off (native kept drawing and JS
+        // never received a message), its SDK-auth error listener and every
+        // unsubscribe made meanwhile. Both native SDKs keep what they hold for
+        // an initialize() that succeeds; this does the same.
+        //
+        // Except a data call made while opted out or denied (contract v7 73) -
+        // by a decision made in this process or one an earlier launch stored
+        // (contract v8 83): dropped now, so a later optIn()/grant never sends
+        // it. Identity, tokens, control calls, withdrawals and decisions are kept
+        // (D-b keeps a held identify for the withdrawals). While the stored
+        // decisions are still being read, the call is held with the decisions
+        // made so far and judged when native answers (_settleStored), before any
+        // initialize() replays it.
+        let madeUnder;
+        let madeInWindow;
+        if (kind === 'data') {
+            // In-process decision, else the in-flight init's config, else stored.
+            const at = {
+                optedOut: this._preInitOptedOut ?? this._initConfigOptedOut,
+                denied: this._preInitDenied ?? this._initConfigDenied,
+            };
+            const refused = this._refusedBeforeInit(at);
+            if (refused === true) {
+                this._warnDroppedWhileRefused();
+                return;
+            }
+            if (refused === 'unknown')
+                madeUnder = at;
+            if (this._initConfigOptedOut !== null || this._initConfigDenied !== null) {
+                madeInWindow = { optedOut: this._preInitOptedOut, denied: this._preInitDenied };
+            }
+        }
+        if (this._pending.length >= exports.MAX_PRE_INIT_CALLS) {
+            this._evictOneHeld();
+            if (!this._warnedPendingOverflow) {
+                this._warnedPendingOverflow = true;
+                // eslint-disable-next-line no-console
+                console.warn(`[Joryio] More than ${exports.MAX_PRE_INIT_CALLS} calls were made before initialize() ` +
+                    'succeeded; the oldest are being dropped (withdrawals and privacy decisions last). ' +
+                    'Call Joryio.initialize() at app start.');
+            }
+        }
+        const call = { fn, kind };
+        if (tag)
+            call.tag = tag;
+        if (madeUnder)
+            call.madeUnder = madeUnder;
+        if (madeInWindow)
+            call.madeInWindow = madeInWindow;
+        this._pending.push(call);
+    }
+    /**
+     * Make room in a full pre-init hold (contract v5 51): the oldest call of the
+     * first kind present in EVICTION_ORDER goes. An unsubscribe, a push
+     * unregister or a privacy decision is dropped only when the hold holds
+     * nothing else. It used to drop the oldest call whatever it was, so an
+     * unsubscribe followed by a thousand track() calls lost the unsubscribe.
+     */
+    _evictOneHeld() {
+        for (const kind of EVICTION_ORDER) {
+            const i = this._pending.findIndex((call) => call.kind === kind);
+            if (i >= 0) {
+                this._pending.splice(i, 1);
+                return;
+            }
+        }
+        this._pending.shift();
+    }
+    /**
+     * A privacy decision - optOut, optIn, updateConsent, wipeData.
+     *
+     * Made BEFORE initialize() (contract item 25), it goes to the native module
+     * straight away instead of waiting in the queue above. Both native SDKs
+     * record a decision made before their own initialize() and apply it INSIDE
+     * it, ahead of the Session Start, the in-app sync and the push
+     * re-registration. Queued here, it reached native only after all three had
+     * run - so an app that called optOut() before initialize() still sent a
+     * Session Start for someone who had said no, and then a `tracking_opted_out`
+     * marker for a person who had never consented to anything.
+     *
+     * The native module processes calls in the order JS makes them, so the
+     * decision is recorded before the initialize() that follows it.
+     *
+     * @param discards the kinds of held call the decision drops instead of
+     *   replaying after it: `data` for an opt-out or a denial, and also
+     *   `identity` and `token` for a wipe. Nothing for optIn or a grant.
+     */
+    _decide(fn, discards) {
+        if (!isModuleAvailable)
+            return;
+        if (discards.length > 0)
+            this._discardHeld(discards);
+        if (!this._initialized && this._initInFlight === null) {
+            // A wipe erases the identity the withdrawals held here were made under.
+            // They go to native first, so native buffers them AHEAD of the wipe and
+            // runs them under that identity before erasing it (Unity scan 5, N4).
+            // Held here, they replayed after native's init had already wiped, under
+            // the new anonymous id - a profile that never received anything.
+            if (discards === DISCARDED_BY_WIPE) {
+                this._sendHeldWithdrawalsNow();
+                this._wipeHandedToNative = true;
+            }
+            // Not started (or a failed start): native records it for its next init.
+            this._invoke(fn);
+            return;
+        }
+        // initialize() already called: the decision comes after it, in order.
+        // If that initialize() fails, _handHeldDecisionsToNative passes it on.
+        this._dispatch(fn, 'decision', discards === DISCARDED_BY_WIPE ? 'wipe' : undefined);
+    }
+    /**
+     * After a FAILED initialize(), hand the privacy decisions held while it was
+     * in flight to native now, in call order (contract v6 65). Nothing is in
+     * flight any more, so they take the pre-init path of _decide: native
+     * records each for its next initialize() and applies it ahead of that
+     * init's Session Start, in-app sync and push registration.
+     *
+     * Left held, they replayed only after the RETRY's initialize() and its side
+     * effects - a person who declined while the first init was failing got a
+     * Session Start - and after any decision made since the failure, which goes
+     * to native directly: an optIn() held from the failing window overrode a
+     * later optOut(), so the person ended opted in.
+     *
+     * Withdrawals go too, in place, while nothing but decisions and
+     * withdrawals precede them. One held behind a data, identity or control
+     * call stays held with it: handed ahead of an earlier subscribe for the
+     * same channel, the subscribe would replay later and supersede it; ahead of
+     * an identify, it would be filed under the wrong person. A wipe takes the
+     * withdrawals held before it along first, as _decide does, so native runs
+     * them under the identity being erased.
+     */
+    _handHeldDecisionsToNative() {
+        const held = this._pending;
+        this._pending = [];
+        let onlyPrivacyCallsSoFar = true;
+        for (const call of held) {
+            if (call.kind === 'decision') {
+                if (call.tag === 'wipe') {
+                    this._sendHeldWithdrawalsNow();
+                    this._wipeHandedToNative = true;
+                }
+                this._invoke(call.fn);
+            }
+            else if (call.kind === 'withdrawal' && onlyPrivacyCallsSoFar) {
+                this._invoke(call.fn);
+            }
+            else {
+                if (call.kind !== 'withdrawal')
+                    onlyPrivacyCallsSoFar = false;
+                this._pending.push(call);
+            }
+        }
+    }
+    /** Hand the held withdrawals to native now, in order; keep the rest held. */
+    _sendHeldWithdrawalsNow() {
+        const withdrawals = this._pending.filter((call) => call.kind === 'withdrawal');
+        this._pending = this._pending.filter((call) => call.kind !== 'withdrawal');
+        withdrawals.forEach((call) => this._invoke(call.fn));
+    }
+    /** Drop the held calls of these kinds; keep the rest, in order. */
+    _discardHeld(kinds) {
+        this._pending = this._pending.filter((call) => !kinds.includes(call.kind));
+    }
+    _invoke(fn) {
+        try {
+            fn();
+        }
+        catch (e) {
+            // eslint-disable-next-line no-console
+            console.warn('[Joryio] native call failed', e);
+        }
+    }
+    /**
+     * Replay the calls held before a SUCCESSFUL init. After a failed one they
+     * stay held for the next initialize() (see _dispatch).
+     */
+    _drainPending() {
+        if (this._initFailed)
+            return;
+        const held = this._pending;
+        this._pending = [];
+        held.forEach((call) => this._invoke(call.fn));
+    }
+    /**
+     * Value-returning native call, gated on readiness, that never throws into
+     * the host app: a missing module, an init that never completed and a native
+     * rejection all answer `fallback`.
+     */
+    async _query(caller, fallback, fn) {
+        if (!isModuleAvailable)
+            return fallback;
+        if (!(await this._awaitReady(caller)))
+            return fallback;
+        try {
+            const value = await fn();
+            return value ?? fallback;
+        }
+        catch (e) {
+            // eslint-disable-next-line no-console
+            console.warn(`[Joryio] ${caller}() failed`, e);
+            return fallback;
+        }
+    }
+    /**
+     * Initialize the SDK. Must be called before any other method.
+     *
+     * @example
+     * ```ts
+     * import Joryio from '@joryio/react-native-sdk';
+     *
+     * // Each platform has its own key: iOS keys start with jry_sdk_ios_,
+     * // Android keys with jry_sdk_android_. The other platform's key is refused.
+     * const sdkKey = Platform.select({
+     *   ios: 'jry_sdk_ios_abc123',
+     *   android: 'jry_sdk_android_def456',
+     * })!;
+     * Joryio.initialize(sdkKey, 'api-eu1.joryio.com', {
+     *   enableDebug: __DEV__,
+     *   trackSessionStart: true,
+     * });
+     * ```
+     */
+    async initialize(sdkKey, apiHost, config = {}) {
+        if (!isModuleAvailable) {
+            // eslint-disable-next-line no-console
+            console.warn(`${MODULE_MISSING_MESSAGE} initialize() is a no-op.`);
+            return;
+        }
+        // A missing key or host cannot start anything, but it must not switch the
+        // SDK off either: nothing is marked failed, so a later initialize() with
+        // real values still works and the calls held meanwhile are replayed.
+        if (!requireString('initialize', 'sdkKey', sdkKey))
+            return;
+        if (!requireString('initialize', 'apiHost', apiHost))
+            return;
+        // Two overlapping calls - React StrictMode runs effects twice - share one
+        // native initialize(). The second used to run its own: the first resolved
+        // and set `_initialized`, the second rejected and set `_initFailed`, and
+        // `_dispatch` then dropped every call of a working SDK.
+        if (this._initInFlight)
+            return this._initInFlight;
+        this._initInFlight = this._initialize(sdkKey, apiHost, config);
+        try {
+            await this._initInFlight;
+        }
+        finally {
+            this._initInFlight = null;
+        }
+    }
+    async _initialize(sdkKey, apiHost, config) {
+        if (this._initFailed) {
+            // A retry after a failed initialize(). The failure used to be permanent
+            // for the life of the JS context: `_initFailed` was never cleared, so
+            // even a successful second initialize() left every call dropped.
+            // Readiness is re-armed, so calls made from here on are held and
+            // replayed again instead of being discarded.
+            this._initFailed = false;
+            this._ready = new Promise((resolve) => {
+                this._markReady = resolve;
+            });
+        }
+        let failure = null;
+        const forNative = nativeConfig(config);
+        if (!this._initialized) {
+            // Calls made while this init is in flight are judged with its config
+            // (contract v9 91): native applies it before replaying them.
+            if (forNative.trackingConsent === 'granted')
+                this._initConfigDenied = false;
+            if (forNative.trackingConsent === 'denied')
+                this._initConfigDenied = true;
+            if (forNative.optOut === true)
+                this._initConfigOptedOut = true;
+        }
+        try {
+            await JoryioModule.initialize(sdkKey, apiHost, forNative);
+        }
+        catch (e) {
+            failure = { error: e };
+        }
+        try {
+            // The held data calls are judged against the decisions stored by an
+            // earlier launch before anything is replayed or sent straight through
+            // (contract v8 83). Native was asked for them first thing, ahead of
+            // this initialize(), so they are normally known by now; the read never
+            // rejects and is bounded.
+            await this._storedKnown;
+            this._initConfigOptedOut = null;
+            this._initConfigDenied = null;
+            if (failure === null) {
+                this._pending.forEach((call) => delete call.madeInWindow);
+                this._initialized = true;
+                this._wipeHandedToNative = false;
+                return;
+            }
+            if (this._initialized) {
+                // A later initialize() on an SDK that is already running. Native
+                // keeps the running instance, so this is not a failure of the SDK.
+                // eslint-disable-next-line no-console
+                console.warn('[Joryio] initialize() was called again and ignored; the SDK keeps running.', failure.error);
+                return;
+            }
+            // Record the failure rather than rethrowing into the host app's startup.
+            // Everything downstream then degrades to a no-op with one clear warning,
+            // instead of each call throwing its own "SDK not initialized".
+            this._initFailed = true;
+            this._rejudgeWithoutInitConfig();
+            this._handHeldDecisionsToNative();
+            // eslint-disable-next-line no-console
+            console.warn('[Joryio] initialize() failed; calls are held (at most ' +
+                `${exports.MAX_PRE_INIT_CALLS}) and sent once a later initialize() succeeds. ` +
+                'Calling it again with corrected values is allowed.', failure.error);
+        }
+        finally {
+            // Settle READINESS even when native init THREW. Leaving it unresolved
+            // would hang every deferred call and every getter for the life of the
+            // process — a failed init must degrade, not deadlock. `_initFailed` is
+            // what makes that degradation quiet: fire-and-forget calls stay held
+            // for the next initialize() and getters return defaults, rather than
+            // each throwing its own red box.
+            this._markReady();
+            this._drainPending();
+        }
+    }
+    // ─── Event Tracking ──────────────────────────────────────────────────────
+    /**
+     * Track a custom event.
+     *
+     * @example
+     * ```ts
+     * Joryio.track('Tutorial Completed', { step: 4 });
+     *
+     * // For e-commerce, prefer the typed surface - it applies the platform's
+     * // canonical event names and property keys for you. A hand-typed name that
+     * // is close but not exact is stored verbatim and matches no report, because
+     * // there is deliberately no alias layer:
+     * Joryio.ecommerce.addToCart({ productId: '123', name: 'Buds', price: 29.99, quantity: 1 });
+     * ```
+     */
+    track(eventName, properties = {}) {
+        if (!requireString('track', 'eventName', eventName))
+            return;
+        const props = finiteProperties('track', plainObject(properties));
+        this._dispatch(() => JoryioModule.track(eventName, props), 'data');
+    }
+    /**
+     * Track a screen view.
+     *
+     * @example
+     * ```ts
+     * Joryio.trackScreen('ProductDetail', { productId: '123' });
+     * ```
+     */
+    trackScreen(screenName, properties = {}) {
+        if (!requireString('trackScreen', 'screenName', screenName))
+            return;
+        const props = finiteProperties('trackScreen', plainObject(properties));
+        this._dispatch(() => JoryioModule.trackScreen(screenName, props), 'data');
+    }
+    // ─── User Identity ───────────────────────────────────────────────────────
+    /**
+     * Identify the current user by their user ID.
+     * Call this after login or when you know who the user is.
+     *
+     * @example
+     * ```ts
+     * Joryio.identify('user-123');
+     * ```
+     */
+    identify(userId) {
+        if (!requireString('identify', 'userId', userId))
+            return;
+        this._dispatch(() => JoryioModule.identify(userId), 'identity');
+    }
+    /**
+     * Attach a labelled alias to the current person - an id from another system,
+     * such as `addAlias('crm_id', 'C-1042')`. Works for anonymous visitors as
+     * well as identified users: the alias is stored against the anonymous id and
+     * travels with it when the visitor is identified later.
+     *
+     * There is no unlabelled `alias(userId)`; to name the current person, call
+     * {@link identify}.
+     *
+     * @param aliasLabel what kind of id this is, e.g. `crm_id`
+     * @param aliasName  the id itself
+     */
+    addAlias(aliasLabel, aliasName) {
+        if (!requireString('addAlias', 'aliasLabel', aliasLabel))
+            return;
+        if (!requireString('addAlias', 'aliasName', aliasName))
+            return;
+        this._dispatch(() => JoryioModule.addAlias(aliasLabel, aliasName), 'data');
+    }
+    /**
+     * Reset the user identity. Call this on logout.
+     * Clears user ID, starts new anonymous session, clears in-app messages.
+     */
+    reset() {
+        this._dispatch(() => JoryioModule.reset(), 'control', 'reset');
+    }
+    // ─── Tracking consent ────────────────────────────────────────────────────
+    /**
+     * Stop collecting and sending. Call when a user declines tracking.
+     *
+     * TRACKING consent, not marketing subscription - this does not unsubscribe
+     * anyone from email or SMS. Those live on the contact's subscription state
+     * and are changed through the API or the preference centre.
+     *
+     * Existed on web, Android, iOS and Unity; React Native had no consent surface
+     * at all, so an app built on it could not honour a "do not track" choice
+     * through the SDK. The native SDKs record `tracking_opted_out` on the profile
+     * as part of opting out, so that behaviour comes through this bridge
+     * unchanged - nothing about the wire is decided here.
+     *
+     * Stored on the device: it holds across restarts until {@link optIn}.
+     * Independent of tracking consent - `updateConsent('granted')` does not
+     * cancel it.
+     *
+     * Safe before initialize(), and applied FIRST: the SDK then starts opted out,
+     * with no Session Start, in-app sync or push registration in between. Calls
+     * that collect data made before it, or after it until {@link optIn}, are
+     * dropped: a later optIn() does not send them.
+     */
+    optOut() {
+        this._preInitOptedOut = true;
+        this._decide(() => JoryioModule.optOut(), DISCARDED_BY_WITHDRAWN_CONSENT);
+    }
+    /**
+     * Resume collecting and sending after {@link optOut}. The only call that
+     * lifts an opt-out. It does not change tracking consent: with consent
+     * `'denied'` or `'pending'` nothing is sent until consent is granted too.
+     * Safe before initialize(), and applied before the SDK starts. Calls that
+     * collect data made before it while an opt-out was in force - one made in
+     * this launch or one stored by an earlier launch - are not sent by it.
+     */
+    optIn() {
+        this._preInitOptedOut = false;
+        this._decide(() => JoryioModule.optIn(), []);
+    }
+    /**
+     * Erase everything this device holds for the current person - identity,
+     * queued events, pending writes, in-app state, session, device id and push
+     * token - and unregister the token on the server. The opt-out is KEPT, so a
+     * person who opted out and asked for erasure stays opted out. Push stays
+     * unregistered until {@link registerPushToken} or a permission grant.
+     *
+     * Safe before initialize(), and applied before the SDK starts: nothing is
+     * sent under the erased identity first. Calls made before it that collect
+     * data are dropped, since the wipe would erase them anyway.
+     */
+    wipeData() {
+        this._decide(() => JoryioModule.wipeData(), DISCARDED_BY_WIPE);
+    }
+    /**
+     * Whether the user has opted out of tracking - the opt-out switch only
+     * ({@link optOut} / {@link optIn}). Consent is a separate switch; read it
+     * with {@link getTrackingConsent}.
+     *
+     * Safe before initialize(): the answer then comes from what is stored on the
+     * device, so an opt-out from an earlier launch reads as `true` straight
+     * away. While initialize() is running it waits for it, and then asks native
+     * whether that initialize() succeeded or failed. Answers `false` when the
+     * native module is not linked or the native read fails.
+     */
+    isUserOptedOut() {
+        return this._queryDecision('isUserOptedOut', false, () => {
+            return JoryioModule.isUserOptedOut();
+        });
+    }
+    /**
+     * Change tracking consent - typically when the user answers your consent
+     * banner, for example after you initialized with `trackingConsent: 'pending'`.
+     *
+     *  - `'granted'` releases everything held while consent was pending and
+     *    starts normal collection. It lifts a stored `'denied'`, but never an
+     *    opt-out: only {@link optIn} does that.
+     *  - `'denied'` discards what was held and collects nothing more - calls
+     *    made while denied are dropped, and a later `'granted'` does not send
+     *    them. Stored, so it holds on later launches until `'granted'`.
+     *  - `'pending'` holds data on the device and sends nothing, for this launch
+     *    only. It never replaces a stored `'denied'`.
+     *
+     * It does not opt the user out and {@link isUserOptedOut} does not change.
+     * Safe before initialize(), and applied before the SDK starts.
+     */
+    updateConsent(consent) {
+        const parsed = parseConsent(consent);
+        if (parsed === null) {
+            warn(`updateConsent() takes 'granted', 'denied' or 'pending', not '${String(consent)}'; ignored.`);
+            return;
+        }
+        if (parsed === 'denied')
+            this._preInitDenied = true;
+        if (parsed === 'granted')
+            this._preInitDenied = false;
+        const discards = parsed === 'denied' ? DISCARDED_BY_WITHDRAWN_CONSENT : [];
+        this._decide(() => JoryioModule.updateConsent(parsed), discards);
+    }
+    /**
+     * The current tracking consent: `'granted'`, `'denied'` or `'pending'`.
+     * Separate from the opt-out, which {@link isUserOptedOut} reports.
+     *
+     * Safe before initialize(): the answer then comes from what is stored on the
+     * device (a stored `'denied'` reads as `'denied'`) and from any decision
+     * made earlier in this launch; with nothing decided and nothing stored it
+     * is `'granted'`, the state the SDK runs in, on both platforms. While
+     * initialize() is running it waits for it, and then asks native whether
+     * that initialize() succeeded or failed. Native's answer is passed through
+     * as it is. Answers `null` only when the native module is not linked or the
+     * native call fails.
+     */
+    getTrackingConsent() {
+        return this._queryDecision('getTrackingConsent', null, async () => {
+            const raw = await JoryioModule.getTrackingConsent?.();
+            return parseConsent(raw);
+        });
+    }
+    // ─── Marketing subscription ──────────────────────────────────────────────
+    /**
+     * Set the marketing subscription status for one channel.
+     *
+     * A DIFFERENT consent from {@link optOut}: that controls whether we may
+     * OBSERVE this person, this controls whether we may MESSAGE them. Neither
+     * implies the other - somebody can decline tracking and still want the
+     * newsletter.
+     *
+     * This is what an in-app preference centre writes. It existed on web only,
+     * so a mobile user had to find an email and click its unsubscribe link -
+     * unsubscribing being harder in the app than on the web, which is the wrong
+     * way round for the one action that must always be easy.
+     *
+     * @param channel one of email, sms, whatsapp, push, viber
+     * @param status  one of optedIn, subscribed, unsubscribed
+     */
+    setSubscription(channel, status) {
+        if (!requireString('setSubscription', 'channel', channel))
+            return;
+        if (!requireString('setSubscription', 'status', status))
+            return;
+        // An unsubscribe is a withdrawal: a pre-init optOut, denial or wipe never
+        // discards it (contract v4 36).
+        const kind = status === 'unsubscribed' ? 'withdrawal' : 'data';
+        this._dispatch(() => JoryioModule.setSubscription(channel, status), kind);
+    }
+    /** Join a subscription group (list) on a channel. */
+    addToSubscriptionGroup(groupId, channel) {
+        if (!requireString('addToSubscriptionGroup', 'groupId', groupId))
+            return;
+        if (!requireString('addToSubscriptionGroup', 'channel', channel))
+            return;
+        this._dispatch(() => JoryioModule.addToSubscriptionGroup(groupId, channel), 'data');
+    }
+    /** Leave a subscription group (list) on a channel. */
+    removeFromSubscriptionGroup(groupId, channel) {
+        if (!requireString('removeFromSubscriptionGroup', 'groupId', groupId))
+            return;
+        if (!requireString('removeFromSubscriptionGroup', 'channel', channel))
+            return;
+        this._dispatch(() => JoryioModule.removeFromSubscriptionGroup(groupId, channel), 'withdrawal');
+    }
+    // ─── User Attributes ─────────────────────────────────────────────────────
+    /**
+     * Set multiple user attributes at once.
+     *
+     * @example
+     * ```ts
+     * Joryio.setAttributes({
+     *   firstName: 'John',
+     *   plan: 'premium',
+     *   age: 28,
+     * });
+     * ```
+     */
+    setAttributes(attributes) {
+        // `null` means UNSET, on both platforms. Split here so the two bridges
+        // receive the same thing; they also treat a null as an unset themselves.
+        // Android used to crash the app on a null value (a NullPointerException
+        // casting it to Any), and iOS forwarded it as NSNull.
+        if (attributes === null || typeof attributes !== 'object' || Array.isArray(attributes)) {
+            warn('setAttributes() needs an object of attributes; ignored.');
+            return;
+        }
+        const values = {};
+        const unset = [];
+        const nonFinite = [];
+        for (const [key, value] of Object.entries(attributes)) {
+            if (value === null || value === undefined)
+                unset.push(key);
+            else if (isNonFiniteNumber(value))
+                nonFinite.push(key);
+            else
+                values[key] = value;
+        }
+        // Left out, not unset: a NaN is a mistake, not a request to erase.
+        if (nonFinite.length > 0) {
+            warn(`setAttributes() left out ${nonFinite.join(', ')}: NaN and Infinity are not valid values.`);
+        }
+        if (Object.keys(values).length > 0) {
+            this._dispatch(() => JoryioModule.setAttributes(values), 'data');
+        }
+        unset.forEach((key) => this._dispatch(() => JoryioModule.unsetAttribute(key), 'data'));
+    }
+    /**
+     * Set a single user attribute. `null` unsets it.
+     */
+    setAttribute(key, value) {
+        if (!requireString('setAttribute', 'key', key))
+            return;
+        if (value === null || value === undefined) {
+            this._dispatch(() => JoryioModule.unsetAttribute(key), 'data');
+            return;
+        }
+        if (isNonFiniteNumber(value)) {
+            // Over the bridge a NaN arrives as null - an UNSET of the stored value.
+            warn(`setAttribute('${key}') needs a finite number, not ${String(value)}; ignored.`);
+            return;
+        }
+        this._dispatch(() => JoryioModule.setAttribute(key, value), 'data');
+    }
+    /**
+     * Increment a numeric user attribute.
+     *
+     * @example
+     * ```ts
+     * Joryio.incrementAttribute('loginCount', 1);
+     * ```
+     */
+    incrementAttribute(key, by = 1) {
+        if (!requireString('incrementAttribute', 'key', key))
+            return;
+        // null means the default step, like an omitted argument.
+        const step = by === null || by === undefined ? 1 : by;
+        if (typeof step !== 'number' || !Number.isFinite(step)) {
+            warn(`incrementAttribute('${key}') needs a finite number to add; ignored.`);
+            return;
+        }
+        this._dispatch(() => JoryioModule.incrementAttribute(key, step), 'data');
+    }
+    /**
+     * Remove a user attribute.
+     */
+    unsetAttribute(key) {
+        if (!requireString('unsetAttribute', 'key', key))
+            return;
+        this._dispatch(() => JoryioModule.unsetAttribute(key), 'data');
+    }
+    // ─── Push Notifications ──────────────────────────────────────────────────
+    /**
+     * Register a push notification token (FCM on Android, APNs on iOS).
+     * Typically called after receiving the token from Firebase or Apple.
+     *
+     * Resolves with the registration outcome - it never rejects, so a caller
+     * that ignores the promise gets exactly the previous fire-and-forget
+     * behaviour. Before 1.3.0 the bridge dropped the native result: a
+     * device-side DNS blip left the device unregistered for push with no
+     * signal and nothing to retry (Teamder, 2026-09-29). `isRetryable` says
+     * whether trying again is worth it; `isUnauthorized` says the SDK key is
+     * wrong and a retry will not help.
+     *
+     * On iOS register the APNs device token, never the FCM one: Joryio sends
+     * iOS push through APNs. A token that is not an APNs token (hex) is refused
+     * on iOS with `isRetryable: false`; registered, it would replace the
+     * device's working APNs token with one APNs rejects.
+     *
+     * @example
+     * ```ts
+     * // With @react-native-firebase/messaging
+     * const token = Platform.OS === 'ios'
+     *   ? await messaging().getAPNSToken() // APNs device token (hex)
+     *   : await messaging().getToken();    // FCM token
+     * if (token) {
+     *   const result = await Joryio.registerPushToken(token);
+     *   if (!result.success && result.isRetryable) {
+     *     // transient (offline, DNS, 5xx): register again when the network is back
+     *   }
+     * }
+     *
+     * // onTokenRefresh delivers the FCM token - on iOS too, at every app start.
+     * // Register it on Android only.
+     * messaging().onTokenRefresh((fcmToken) => {
+     *   if (Platform.OS === 'android') Joryio.registerPushToken(fcmToken);
+     * });
+     * ```
+     */
+    async registerPushToken(token) {
+        if (!isModuleAvailable) {
+            return { success: false, message: 'Joryio native module is not linked', isUnauthorized: false, isRetryable: false };
+        }
+        // Trimmed first, like both native SDKs (contract v6 69): a token read
+        // with a trailing newline was refused on iOS as "not an APNs token" here
+        // while native would have trimmed and registered it.
+        token = typeof token === 'string' ? token.trim() : token;
+        if (!requireString('registerPushToken', 'token', token)) {
+            return { success: false, message: 'A push token is required', isUnauthorized: false, isRetryable: false };
+        }
+        if (react_native_1.Platform?.OS === 'ios' && !APNS_TOKEN.test(token)) {
+            const message = 'On iOS registerPushToken() needs the APNs device token (hex), from ' +
+                'messaging().getAPNSToken() - this looks like an FCM token. Not registered.';
+            warn(message);
+            return { success: false, message, isUnauthorized: false, isRetryable: false };
+        }
+        if (!(await this._awaitReady('registerPushToken'))) {
+            // The token was not sent. Retryable only when initialize() is merely
+            // late - calling again after it resolves works. After a FAILED
+            // initialize() a plain retry cannot work: the token has to be registered
+            // again once a later initialize() succeeds, so `isRetryable` is false
+            // (contract item 48) - retrying in a backoff loop would spin.
+            return this._initFailed
+                ? { success: false, message: 'SDK initialization failed', isUnauthorized: false, isRetryable: false }
+                : { success: false, message: 'SDK not initialized', isUnauthorized: false, isRetryable: true };
+        }
+        try {
+            const r = await JoryioModule.registerPushToken(token);
+            return {
+                success: !!r?.success,
+                message: r?.message ?? undefined,
+                isUnauthorized: !!r?.isUnauthorized,
+                isRetryable: !!r?.isRetryable,
+            };
+        }
+        catch (e) {
+            // eslint-disable-next-line no-console
+            console.warn('[Joryio] native call failed', e);
+            return { success: false, message: String(e?.message ?? e), isUnauthorized: false, isRetryable: true };
+        }
+    }
+    /**
+     * Report that a push ARRIVED on this device.
+     *
+     * Needed because most React Native apps run their OWN messaging service -
+     * @react-native-firebase/messaging, Expo notifications - so a push never
+     * passes through our native service and would report no delivery at all.
+     * The same apps already call `registerPushToken`; this is the matching half.
+     *
+     * ```ts
+     * messaging().onMessage(async (msg) => {
+     *   if (msg.data?.trackingId) Joryio.reportPushDelivered(msg.data.trackingId);
+     * });
+     * messaging().setBackgroundMessageHandler(async (msg) => {
+     *   if (msg.data?.trackingId) Joryio.reportPushDelivered(msg.data.trackingId);
+     * });
+     * ```
+     *
+     * @param trackingId the `trackingId` from the message's data payload.
+     */
+    reportPushDelivered(trackingId) {
+        if (!requireString('reportPushDelivered', 'trackingId', trackingId))
+            return;
+        this._dispatch(() => JoryioModule.reportPushDelivered(trackingId), 'data');
+    }
+    /**
+     * Unregister from push notifications.
+     */
+    unregisterPush() {
+        // A withdrawal (contract v4 36): held before initialize() through an
+        // optOut, a denial or a wipe, and the last thing a full hold drops.
+        this._dispatch(() => JoryioModule.unregisterPush(), 'withdrawal');
+    }
+    /**
+     * Where the user stands on notifications, without asking them anything.
+     *
+     * Check this BEFORE showing a primer: `notDetermined` is the ONLY state in
+     * which the system prompt can still appear. Push permission is one-shot on
+     * iOS and Android 13+ - a denial is recoverable only in system Settings - so a
+     * primer shown to an already-denied user spends their goodwill on a prompt
+     * that can never be displayed.
+     */
+    async getPushPermissionStatus() {
+        return this._query('getPushPermissionStatus', 'unavailable', () => {
+            return JoryioModule.getPushPermissionStatus();
+        });
+    }
+    /**
+     * Show the system notification prompt, resolving the resulting status.
+     *
+     * The SDK never calls this for you. The prompt can only be shown once, and
+     * neither `initialize()` nor a dashboard toggle can know when your app has
+     * earned the right to ask - so the moment is yours. Ask after a booking, a
+     * purchase, or from a notification settings screen; not on first launch.
+     *
+     * ```ts
+     * if ((await Joryio.getPushPermissionStatus()) === 'notDetermined') {
+     *   // show your own primer first, then:
+     *   const status = await Joryio.requestPushPermission();
+     * }
+     * ```
+     *
+     * On Android this covers the API 33+ POST_NOTIFICATIONS runtime permission and
+     * registers the FCM token on a grant. Below API 33 nothing is shown and the
+     * current Settings state is reported.
+     *
+     * The same on both platforms when the user has opted out of tracking: the
+     * prompt is still shown (whether the app may NOTIFY is the user's choice in
+     * the OS, not a tracking decision) and the resulting status is resolved, but
+     * nothing is registered or reported to Joryio while opted out. iOS used to
+     * skip the prompt and answer `notDetermined`, so a primer asked forever.
+     *
+     * Always settles. If Android recreates the Activity while the prompt is up
+     * (a rotation, a theme change), the answer is lost with it; the promise then
+     * resolves with the status as it stands once the app is back in front.
+     */
+    async requestPushPermission() {
+        return this._query('requestPushPermission', 'unavailable', () => {
+            return JoryioModule.requestPushPermission();
+        });
+    }
+    /**
+     * Check if push notifications are enabled.
+     */
+    async isPushEnabled() {
+        return this._query('isPushEnabled', false, () => {
+            return JoryioModule.isPushEnabled();
+        });
+    }
+    /**
+     * Track a push notification click (for analytics).
+     * Call this when the user taps a push notification.
+     */
+    trackPushClick(trackingId) {
+        if (!requireString('trackPushClick', 'trackingId', trackingId))
+            return;
+        this._dispatch(() => JoryioModule.trackPushClick(trackingId), 'data');
+    }
+    // ─── In-App Messaging ────────────────────────────────────────────────────
+    /**
+     * Listen for in-app messages that are ready to display.
+     * Returns an unsubscribe function.
+     *
+     * Subscribing OVERRIDES the SDK's own rendering: you draw the message, and
+     * therefore YOU MUST REPORT what happened via {@link trackInAppImpression}.
+     * The SDK cannot see a message it did not draw. Handing a message to you
+     * neither emits `in_app.displayed` nor spends the campaign's frequency
+     * budget: both happen when you report `'displayed'`, once, as the message
+     * appears - the same rule on iOS and Android. Report it exactly once per
+     * message you show; a message you never report counts toward no frequency
+     * cap and reads as delivered to nobody, which also breaks revenue
+     * attribution, which joins on that event.
+     *
+     * Declare what YOUR renderer can draw via `options.capabilities`. Campaigns
+     * are targeted on it, and an undeclared capability is read as "cannot" rather
+     * than "unknown" - so an app with `react-native-webview` should include
+     * `content.html`, and one without it should not. Omitting the option keeps the
+     * previous behaviour, where the value came from a native config flag
+     * describing the native SDK's own views, which never run here.
+     *
+     * @example
+     * ```ts
+     * const unsubscribe = Joryio.onInAppMessage((message) => {
+     *   showMyOwnUI(message);
+     *   Joryio.trackInAppImpression(message.id, 'displayed');
+     *   // ... 'clicked' (with the button's id) when a button is tapped, and
+     *   // 'dismissed' whenever the message leaves the screen - after a click too.
+     * });
+     *
+     * // Later:
+     * unsubscribe();
+     * ```
+     *
+     * A message you reported `'displayed'` holds the display slot until you
+     * report `'dismissed'`: until then no other in-app message is shown on iOS,
+     * and the same campaign is not shown again on Android. If `'dismissed'`
+     * never comes, the SDK frees the slot after 5 minutes. So report it whenever
+     * the message leaves the screen, including after a click.
+     *
+     * A callback that throws (or returns a promise that rejects) is caught and
+     * logged; it never crashes the app or stops other listeners.
+     *
+     * Unsubscribing the LAST listener hands rendering back to the native SDK, so
+     * messages that arrive afterwards are drawn natively instead of being handed
+     * to a listener that no longer exists. Before 1.3.0 they were silently lost
+     * on both platforms for the rest of the session.
+     */
+    onInAppMessage(callback, options) {
+        if (typeof callback !== 'function') {
+            warn('onInAppMessage() needs a callback function; ignored.');
+            return () => { };
+        }
+        if (!isModuleAvailable || !emitter) {
+            return () => { };
+        }
+        const subscription = emitter.addListener('JoryioInAppMessage', guardedCallback('onInAppMessage', callback));
+        this._inAppListeners += 1;
+        // Via _dispatch, like every other native call. Called directly, this threw
+        // "Joryio SDK not initialized" and RN surfaced a red box: a host app
+        // naturally subscribes on mount, which is BEFORE initialize() resolves, so
+        // in-app messaging never enabled at all. _dispatch queues the call until the
+        // SDK is ready and then replays it, in order with the matching disable.
+        // Declared capabilities describe YOUR renderer, not the SDK's.
+        const capabilities = normalizeCapabilities(options?.capabilities);
+        this._dispatch(() => JoryioModule.enableInAppMessages(capabilities));
+        let removed = false;
+        return () => {
+            // Idempotent: a second call must not decrement someone else's listener.
+            if (removed)
+                return;
+            removed = true;
+            subscription.remove();
+            this._inAppListeners = Math.max(0, this._inAppListeners - 1);
+            if (this._inAppListeners === 0) {
+                this._dispatch(() => JoryioModule.disableInAppMessages());
+            }
+        };
+    }
+    /**
+     * Hand in-app messages to JavaScript and say what YOUR renderer can draw
+     * (`content.native`, `content.html`). `onInAppMessage` calls this for you;
+     * call it directly only when you listen for the `JoryioInAppMessage` event
+     * some other way, and pair it with {@link disableInAppMessages}.
+     *
+     * An empty or omitted list means "not declared" on both platforms - the SDK
+     * then describes its own renderer - never "this app can draw nothing".
+     */
+    enableInAppMessages(capabilities) {
+        const declared = normalizeCapabilities(capabilities);
+        this._dispatch(() => JoryioModule.enableInAppMessages(declared));
+    }
+    /**
+     * Hand in-app rendering back to the native SDK after
+     * {@link enableInAppMessages}. Removing the last `onInAppMessage` listener
+     * does this for you.
+     */
+    disableInAppMessages() {
+        this._dispatch(() => JoryioModule.disableInAppMessages());
+    }
+    /**
+     * E-commerce events with the platform's canonical names applied for you:
+     * `Joryio.ecommerce.purchase(order)`.
+     *
+     * A real typed property, not something bolted on after construction. The
+     * first version assigned it with `(Joryio as any).ecommerce = ...`, which
+     * worked at runtime and was invisible to TypeScript - so every call site got
+     * "Property 'ecommerce' does not exist". The demo app found it immediately,
+     * which is what a reference integration is for.
+     */
+    get ecommerce() {
+        return (this._ecommerce ?? (this._ecommerce = new JoryioEcommerce(this)));
+    }
+    /**
+     * Report what happened to an in-app message YOUR app rendered.
+     *
+     * @param campaignId the message's `id`
+     * @param action     `'displayed'` once when it appears (this is also what
+     *                   spends the campaign's frequency budget), `'clicked'`
+     *                   when a button is tapped, and `'dismissed'` whenever it
+     *                   leaves the screen - after a click too, because the
+     *                   message holds the display slot until then
+     * @param elementId  for a click, the id of the button or link tapped - sent
+     *                   as `elementId`, the same name on every SDK, so reports can
+     *                   say which button. Omit it for other actions.
+     */
+    trackInAppImpression(campaignId, action, elementId) {
+        if (!requireString('trackInAppImpression', 'campaignId', campaignId))
+            return;
+        if (!requireString('trackInAppImpression', 'action', action))
+            return;
+        const element = typeof elementId === 'string' && elementId.length > 0 ? elementId : null;
+        this._dispatch(() => JoryioModule.trackInAppImpression(campaignId, action, element), 'data');
+    }
+    /**
+     * Submit a form shown inside an HTML in-app message that your app renders
+     * itself (a `<form data-jry-form>` in the campaign's html). The values are
+     * posted with the SDK's identity; the backend validates them against the
+     * form the campaign carries and writes the person. Resolves with the
+     * server's verdict - `{ ok, message?, redirect?, errors? }` - and never
+     * throws: a failure is `ok: false`.
+     */
+    async submitInAppForm(campaignId, values) {
+        const failed = { ok: false, message: 'Something went wrong. Please try again.' };
+        if (!requireString('submitInAppForm', 'campaignId', campaignId))
+            return failed;
+        const fields = plainObject(values);
+        return this._query('submitInAppForm', failed, async () => {
+            const raw = await JoryioModule.submitInAppForm(campaignId, fields);
+            // Android answers a JSON string, iOS an object; both mean the same thing.
+            return typeof raw === 'string' ? JSON.parse(raw) : raw;
+        });
+    }
+    // ─── SDK Authentication ──────────────────────────────────────────────────
+    /**
+     * Set/replace the customer-minted JWT used for SDK Authentication.
+     * Attached as the `X-Joryio-Auth` header on every subsequent ingest request.
+     * Call after login, and again from your `onSdkAuthenticationError` handler to
+     * supply a freshly minted token.
+     *
+     * @example
+     * ```ts
+     * const jwt = await mintJoryioJwt(); // your backend mints it
+     * Joryio.setSdkAuthenticationToken(jwt);
+     * ```
+     */
+    setSdkAuthenticationToken(token) {
+        if (!requireString('setSdkAuthenticationToken', 'token', token))
+            return;
+        const send = () => JoryioModule.setSdkAuthenticationToken(token);
+        // Before initialize() has started, straight to native, which holds a
+        // token set before its own init and applies it ahead of the Session Start
+        // and the in-app sync. Held here until init resolved, it arrived after
+        // both, so a stored identified user's first requests went out with no
+        // token, were refused 401 `missing` and waited on the refresh round-trip.
+        //
+        // Only when no identify() or reset() is held: the token belongs to the
+        // identity those set up, and handed over ahead of them it would be
+        // applied to the previous one (a held reset() replayed after init would
+        // even retire it). Nor after a wipeData() handed to native: native runs
+        // that wipe inside init and would retire the new visitor's token with
+        // the erased person's. A wipe made AFTER it is native's to apply: both
+        // natives keep a token recorded before their pre-init wipe and the wipe
+        // retires it to the erased person's own withdrawals, so it is never
+        // carried over to the next visitor.
+        if (isModuleAvailable &&
+            !this._initialized &&
+            this._initInFlight === null &&
+            !this._wipeHandedToNative &&
+            !this._pending.some((call) => call.kind === 'identity' || call.kind === 'token' || call.tag === 'reset')) {
+            this._invoke(send);
+            return;
+        }
+        this._dispatch(send, 'token');
+    }
+    /**
+     * Listen for SDK-authentication failures (the backend rejected the JWT with a
+     * 401 `sdk_authentication_error`). Mint a fresh JWT in the callback and call
+     * `setSdkAuthenticationToken()`; the refreshed token is carried on the next
+     * flush. Returns an unsubscribe function.
+     *
+     * @example
+     * ```ts
+     * const unsubscribe = Joryio.onSdkAuthenticationError(async ({ reason }) => {
+     *   const jwt = await mintJoryioJwt(); // re-mint (esp. on 'expired')
+     *   Joryio.setSdkAuthenticationToken(jwt);
+     * });
+     * ```
+     */
+    // Works on BOTH platforms, by different routes: Android exposes an explicit
+    // enable call, iOS registers the handler during initialize(). The asymmetry is
+    // invisible to callers and is handled below.
+    onSdkAuthenticationError(callback) {
+        if (typeof callback !== 'function') {
+            warn('onSdkAuthenticationError() needs a callback function; ignored.');
+            return () => { };
+        }
+        if (!isModuleAvailable || !emitter) {
+            return () => { };
+        }
+        const subscription = emitter.addListener('JoryioSdkAuthError', guardedCallback('onSdkAuthenticationError', callback));
+        // Straight to native, before initialize() too, and as an optional call:
+        //
+        //  - straight away: the Android bridge installs the handler through the
+        //    native SDK's pre-init-aware setter, so one set before initialize()
+        //    is in place for the first requests (Session Start, in-app sync) and
+        //    survives a pre-init wipeData() (contract v8 84). Held here until
+        //    init, it arrived after those requests, whose 401s nobody heard.
+        //  - `?.()`: the method exists on ANDROID ONLY. iOS registers the same
+        //    handler inside initialize() instead, so the callback works there
+        //    either way - but calling a method iOS does not export would throw
+        //    "undefined is not a function". Same convention as syncInAppCampaigns.
+        //
+        // Safe before init on both platforms (the same shape as the pre-init token
+        // in setSdkAuthenticationToken): Android's bridge calls the companion
+        // setter, iOS has no such method. _invoke catches a native throw.
+        const enable = () => JoryioModule.enableSdkAuthenticationErrors?.();
+        this._invoke(enable);
+        return () => subscription.remove();
+    }
+    // ─── Utilities ───────────────────────────────────────────────────────────
+    /**
+     * Flush the event queue immediately.
+     * Events are normally batched and sent periodically.
+     */
+    flush() {
+        this._dispatch(() => JoryioModule.flush());
+    }
+    /**
+     * Fetch in-app campaigns now and display any that are eligible.
+     *
+     * The SDK already syncs on session start and on foreground; use this for the
+     * moments in between - after resetDisplayedCampaigns(), or once the user has
+     * done something that should make them newly eligible.
+     *
+     * Both platforms. It was iOS-only, which was a missing BINDING rather than a
+     * missing capability - the Android facade has exposed `syncInAppCampaigns()`
+     * all along and the module simply never bound it, so this call was
+     * `undefined` on Android and did nothing at all.
+     *
+     * `?.()` is kept for a different reason than before: an app on an older
+     * native module than this JS package would otherwise throw
+     * "undefined is not a function".
+     */
+    syncInAppCampaigns() {
+        this._dispatch(() => JoryioModule.syncInAppCampaigns?.());
+    }
+    /**
+     * Forget which in-app campaigns have already been shown on this device.
+     *
+     * The SDK skips any campaign it has displayed before, and that set is
+     * persisted - so a message appears once per install and then never again.
+     * Useful when testing: without it you must delete and reinstall the app to
+     * see the same campaign twice.
+     *
+     * Both platforms, but they forget different things, and the difference is
+     * real rather than an oversight:
+     *
+     *   iOS      clears the persisted show-once-ever set AND the per-campaign
+     *            impression history.
+     *   Android  has no show-once-ever set - a campaign with no frequency cap
+     *            repeats there by design - so it clears the impression history
+     *            and the cross-campaign gap, which is the state that actually
+     *            suppresses a repeat on that platform.
+     *
+     * This was documented as "iOS ONLY - Android has nothing to reset", which was
+     * out of date: Joryio.kt has exposed resetDisplayedCampaigns() throughout and
+     * it does the second thing above. Debug-gated natively, so release builds are
+     * unaffected on both.
+     */
+    resetDisplayedCampaigns() {
+        // `?.()` guards an app on an older native module than this JS package, not
+        // a platform gap.
+        this._dispatch(() => JoryioModule.resetDisplayedCampaigns?.());
+    }
+    /**
+     * What the SDK is EXPERIENCING: which server it talks to, and the last
+     * transport failure (null once a call succeeds again).
+     *
+     * "Initialized" and "the server accepts us" are different claims. Without
+     * this, a wrong SDK key looks identical to a healthy integration - the SDK
+     * reports itself up while every request is rejected 401.
+     *
+     * Implemented on BOTH platforms. It was iOS-only, which meant the one call you
+     * reach for when an integration misbehaves was absent on Android.
+     *
+     * It is also what the SDK is ACTUALLY doing, as opposed to the config your
+     * app believes it set: `initialize()` ignores a second call, so changing
+     * settings without restarting leaves the SDK on the old values while your UI
+     * shows the new ones.
+     */
+    async getDiagnostics() {
+        // Gated like the other getters. "initialize() never completed" IS the
+        // diagnostic in that case, and _awaitReady logs exactly that.
+        return this._query('getDiagnostics', { apiEndpoint: null }, () => {
+            return JoryioModule.getDiagnostics();
+        });
+    }
+    /**
+     * Get the anonymous ID assigned to this device.
+     */
+    async getAnonymousId() {
+        return this._query('getAnonymousId', '', () => {
+            return JoryioModule.getAnonymousId();
+        });
+    }
+    /**
+     * Get the current user ID (null if not identified).
+     */
+    async getUserId() {
+        return this._query('getUserId', null, () => {
+            return JoryioModule.getUserId();
+        });
+    }
+    /**
+     * Get the current session ID.
+     */
+    async getSessionId() {
+        return this._query('getSessionId', '', () => {
+            return JoryioModule.getSessionId();
+        });
+    }
+}
+/**
+ * E-commerce events, with the platform's canonical names applied for you.
+ *
+ * WHY THIS EXISTS. The web, iOS and Android SDKs have always had this; React
+ * Native did not, so every RN integration hand-typed event names - and there is
+ * deliberately NO alias layer server-side. "Added to Cart" is not a near-miss
+ * for "Product Added", it is a different event: stored verbatim, matching no
+ * e-commerce report, no revenue attribution and no recommendation feature.
+ *
+ * Our own demo shop did exactly that and recorded zero revenue while looking
+ * completely healthy on screen, which is the failure mode this closes: not an
+ * error, a plausible number.
+ *
+ * Every call forwards to the native tracker, which owns the vocabulary. Nothing
+ * here re-spells an event name.
+ */
+/** The lines of a cart or order without its null entries. */
+function withoutNullLines(items) {
+    return items.filter((item) => item !== null && item !== undefined);
+}
+class JoryioEcommerce {
+    constructor(sdk) {
+        this.sdk = sdk;
+    }
+    send(method, payload) {
+        // Optional arguments left out rather than sent as null: the bridges read a
+        // present key as a value, and a null where a number was expected is the
+        // native SDK's default, not an error (contract item 19).
+        const clean = withoutNullValues(payload);
+        // A null line is skipped (see lines()), so it must not reach the bridge
+        // either: both bridges turned it into a line with no productId, and both
+        // native trackers then refused the WHOLE call - an order lost, with
+        // nothing in JS to say so.
+        if (Array.isArray(clean.items))
+            clean.items = withoutNullLines(clean.items);
+        if (isRecord(clean.order) && Array.isArray(clean.order.items)) {
+            clean.order = { ...clean.order, items: withoutNullLines(clean.order.items) };
+        }
+        // An optional count that is NaN or Infinity (a line's quantity, a search's
+        // resultCount) is left out with a warning, so the native default applies
+        // (contract v5 49). Android read NaN as 0 and iOS as absent.
+        const finite = finiteProperties(`ecommerce.${method}`, clean);
+        // Same queue-until-ready path as every other call, so a tracker built in a
+        // module field before initialize() resolves does not silently drop events.
+        this.sdk._dispatch(() => JoryioModule.ecommerce(method, finite), 'data');
+    }
+    // ── Required arguments (contract items 19 and 42) ──────────────────────
+    //
+    // A missing required argument warns and sends NOTHING. Both bridges used to
+    // fill the gap with a default, so `purchase(null)` tracked an Order
+    // Completed with orderId "" and total 0 - not an error anyone would see, a
+    // plausible zero in the revenue report. The native trackers check again.
+    //
+    // ONE set on every Joryio SDK and wrapper (pinned by the backend's
+    // ecommerce-guard-parity spec): a product - and every cart/order line -
+    // needs a productId and a finite price; cart calls a finite cartValue;
+    // purchase an orderId and a finite value (the items may be empty); every
+    // other id or label is required; an optional amount may be left out, but
+    // one given must be finite. An id that is only whitespace counts as missing.
+    product(caller, value, name = 'product') {
+        if (!isRecord(value) || !isNonBlankString(value.productId)) {
+            warn(`ecommerce.${caller}() needs a ${name} with a productId; ignored.`);
+            return false;
+        }
+        return this.amount(caller, `${name}.price`, value.price);
+    }
+    /** Every line (a null entry is skipped, and not sent) a valid product. */
+    lines(caller, items) {
+        return items.every((item) => item == null || this.product(caller, item, 'item'));
+    }
+    text(caller, name, value) {
+        if (isNonBlankString(value))
+            return true;
+        warn(`ecommerce.${caller}() needs a non-empty string ${name}; ignored.`);
+        return false;
+    }
+    amount(caller, name, value) {
+        if (typeof value === 'number' && Number.isFinite(value))
+            return true;
+        warn(`ecommerce.${caller}() needs a number ${name}; ignored.`);
+        return false;
+    }
+    /** Absent is fine; present must be finite. */
+    optionalAmount(caller, name, value) {
+        return value === undefined || value === null || this.amount(caller, name, value);
+    }
+    cart(caller, items, cartValue) {
+        if (!Array.isArray(items)) {
+            warn(`ecommerce.${caller}() needs an array of items; ignored.`);
+            return false;
+        }
+        return this.lines(caller, items) && this.amount(caller, 'cartValue', cartValue);
+    }
+    viewProduct(product) {
+        if (!this.product('viewProduct', product))
+            return;
+        this.send('viewProduct', { product });
+    }
+    viewCategory(categoryId, categoryName) {
+        if (!this.text('viewCategory', 'categoryId', categoryId))
+            return;
+        if (!this.text('viewCategory', 'categoryName', categoryName))
+            return;
+        this.send('viewCategory', { categoryId, categoryName });
+    }
+    search(query, resultCount) {
+        if (!this.text('search', 'query', query))
+            return;
+        this.send('search', { query, resultCount });
+    }
+    addToCart(item, cartValue) {
+        if (!this.product('addToCart', item, 'item'))
+            return;
+        if (!this.optionalAmount('addToCart', 'cartValue', cartValue))
+            return;
+        this.send('addToCart', { item, cartValue });
+    }
+    removeFromCart(product, quantity = 1) {
+        if (!this.product('removeFromCart', product))
+            return;
+        this.send('removeFromCart', { product, quantity });
+    }
+    cartViewed(items, cartValue) {
+        if (!this.cart('cartViewed', items, cartValue))
+            return;
+        this.send('cartViewed', { items, cartValue });
+    }
+    updateCart(items, cartValue) {
+        if (!this.cart('updateCart', items, cartValue))
+            return;
+        this.send('updateCart', { items, cartValue });
+    }
+    startCheckout(items, cartValue) {
+        if (!this.cart('startCheckout', items, cartValue))
+            return;
+        this.send('startCheckout', { items, cartValue });
+    }
+    addPaymentInfo(paymentMethod) {
+        if (!this.text('addPaymentInfo', 'paymentMethod', paymentMethod))
+            return;
+        this.send('addPaymentInfo', { paymentMethod });
+    }
+    /**
+     * An order. `orderId`, `items` (an array, may be empty) and a finite `value`
+     * are required: the value is sent as `total`, the key revenue reports read,
+     * and a purchase missing any of them is ignored with a warning rather than
+     * recorded as a zero or an empty order.
+     */
+    purchase(order) {
+        if (!isRecord(order) || !isNonBlankString(order.orderId)) {
+            warn('ecommerce.purchase() needs an order with an orderId; ignored.');
+            return;
+        }
+        if (!Array.isArray(order.items)) {
+            warn('ecommerce.purchase() needs an order with an items array; ignored.');
+            return;
+        }
+        if (!this.amount('purchase', 'order.value', order.value))
+            return;
+        if (!this.lines('purchase', order.items))
+            return;
+        if (!this.optionalAmount('purchase', 'order.shipping', order.shipping))
+            return;
+        if (!this.optionalAmount('purchase', 'order.tax', order.tax))
+            return;
+        if (!this.optionalAmount('purchase', 'order.discount', order.discount))
+            return;
+        this.send('purchase', { order });
+    }
+    orderFulfilled(orderId, trackingNumber, carrier) {
+        if (!this.text('orderFulfilled', 'orderId', orderId))
+            return;
+        this.send('orderFulfilled', { orderId, trackingNumber, carrier });
+    }
+    orderDelivered(orderId) {
+        if (!this.text('orderDelivered', 'orderId', orderId))
+            return;
+        this.send('orderDelivered', { orderId });
+    }
+    orderCancelled(orderId, reason) {
+        if (!this.text('orderCancelled', 'orderId', orderId))
+            return;
+        this.send('orderCancelled', { orderId, reason });
+    }
+    orderRefunded(orderId, refundAmount, reason) {
+        if (!this.text('orderRefunded', 'orderId', orderId))
+            return;
+        if (!this.optionalAmount('orderRefunded', 'refundAmount', refundAmount))
+            return;
+        this.send('orderRefunded', { orderId, refundAmount, reason });
+    }
+    addToWishlist(product) {
+        if (!this.product('addToWishlist', product))
+            return;
+        this.send('addToWishlist', { product });
+    }
+    removeFromWishlist(product) {
+        if (!this.product('removeFromWishlist', product))
+            return;
+        this.send('removeFromWishlist', { product });
+    }
+    shareProduct(product, shareMethod) {
+        if (!this.product('shareProduct', product))
+            return;
+        if (!this.text('shareProduct', 'shareMethod', shareMethod))
+            return;
+        this.send('shareProduct', { product, shareMethod });
+    }
+    applyCoupon(couponCode, discountAmount, discountType) {
+        if (!this.text('applyCoupon', 'couponCode', couponCode))
+            return;
+        if (!this.optionalAmount('applyCoupon', 'discountAmount', discountAmount))
+            return;
+        this.send('applyCoupon', { couponCode, discountAmount, discountType });
+    }
+    removeCoupon(couponCode) {
+        if (!this.text('removeCoupon', 'couponCode', couponCode))
+            return;
+        this.send('removeCoupon', { couponCode });
+    }
+    submitReview(productId, rating, reviewText) {
+        if (!this.text('submitReview', 'productId', productId))
+            return;
+        if (!this.amount('submitReview', 'rating', rating))
+            return;
+        // Both native trackers take an Int. Swift's Int(Double) TRAPS past
+        // Int.max - a crash of the host app from `Number(userInput)` - and
+        // Kotlin's toInt() quietly saturates, so the platforms disagreed too.
+        if (Math.abs(rating) > MAX_RATING_MAGNITUDE) {
+            warn(`ecommerce.submitReview() needs a rating a whole-number type can hold, not ${rating}; ignored.`);
+            return;
+        }
+        this.send('submitReview', { productId, rating, reviewText });
+    }
+}
+const Joryio = new JoryioSDK();
+/** Also exported standalone, for `import {ecommerce} from ...`. */
+exports.ecommerce = Joryio.ecommerce;
+exports.default = Joryio;
+//# sourceMappingURL=index.js.map