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

package/lib/index.d.ts

@@ -0,0 +1,1098 @@
+/**
+ * Mirrors the backend's SUBSCRIPTION_CHANNELS and the web SDK. Five, including
+ * viber - it was added to the backend and to no SDK.
+ */
+export type SubscriptionChannel = 'email' | 'sms' | 'whatsapp' | 'push' | 'viber';
+/**
+ * Wire values are camelCase. The backend 400s on `opted_in` - a
+ * NormalizeEnumCasing migration renamed the stored value and the enum NAME,
+ * not the wire string, is what changed.
+ */
+export type SubscriptionStatus = 'optedIn' | 'subscribed' | 'unsubscribed';
+export interface JoryioConfig {
+    /**
+     * Ask for notification permission automatically, soon after initialize().
+     *
+     * **Off by default, and that default is the recommendation.** The system
+     * prompt can be shown exactly once and a refusal is permanent short of a trip
+     * to Settings, so firing it at launch - before the user has any reason to
+     * want notifications from you - is how apps spend their single ask for
+     * nothing. Prefer a primer (the `request_push_permission` in-app button) and
+     * call `requestPushPermission()` when the user says yes.
+     *
+     * Turn this on only when notifications ARE the product.
+     *
+     * Works on both platforms. On iOS the prompt fires straight after
+     * initialize(); on Android it waits for the first foreground, because the
+     * system prompt there needs an Activity.
+     */
+    requestPushPermissionAtLaunch?: boolean;
+    /** Enable debug logging (default: false) */
+    enableDebug?: boolean;
+    /**
+     * Log level: 'debug' | 'info' | 'warn' | 'error'.
+     *
+     * No fixed default: left unset, both native bridges derive it from
+     * `enableDebug` - 'debug' when that is true, 'error' otherwise. Set it only
+     * to override that derivation (for example 'warn' with `enableDebug: true`).
+     */
+    logLevel?: 'debug' | 'info' | 'warn' | 'error';
+    /** Event batch size before auto-flush. Omit to use the native default (50). */
+    batchSize?: number;
+    /** Event flush interval in ms. Omit to use the native default (5000). */
+    flushInterval?: number;
+    /**
+     * Send each event as soon as it is tracked instead of batching (default:
+     * false). Not recommended for production - one request per event.
+     */
+    sendImmediately?: boolean;
+    /**
+     * Most events the local queue holds while flushes fail; beyond it the oldest
+     * are dropped. Omit to use the native default (1000).
+     */
+    maxQueueSize?: number;
+    /** Per-request HTTP timeout in ms. Omit to use the native default (10000). */
+    requestTimeout?: number;
+    /** Session timeout in ms. Omit to use the native default (1800000 / 30 min). */
+    sessionTimeout?: number;
+    /** Automatically track session start (default: true) */
+    trackSessionStart?: boolean;
+    /** Initial user ID if known at init time */
+    userId?: string;
+    /**
+     * Your own anonymous id, if you already have one for this device.
+     *
+     * Used for this run and stored only when nothing is stored yet, exactly as
+     * the native SDKs and the web SDK treat it - so an id set once at init
+     * survives the app dropping the option later. Omit to let the SDK generate
+     * one.
+     */
+    anonymousId?: string;
+    /**
+     * Enable JWT-based SDK Authentication (default: false). When enabled, supply a
+     * customer-minted JWT via `sdkAuthenticationToken` and/or
+     * `setSdkAuthenticationToken()`; it is attached to every ingest request.
+     */
+    enableSdkAuthentication?: boolean;
+    /** Initial SDK-authentication JWT, if known at init time. */
+    sdkAuthenticationToken?: string;
+    /**
+     * Allow in-app messages authored as HTML, which can execute JavaScript
+     * inside your app.
+     *
+     * OFF BY DEFAULT. The server strips `<script>` and every `on*` handler
+     * before sending, so author JavaScript does not run in normal operation. The
+     * document is still rendered in a web view that can execute script, so the
+     * residual risk is a sanitiser bypass - and because the document is authored
+     * server-side, a compromised marketing account would then mean code
+     * executing in every user's session, which is why regulated apps often
+     * prohibit it outright.
+     *
+     * Leaving this off does NOT disable in-app messaging: native messages still
+     * display, because they are data your app renders with its own components.
+     */
+    allowHtmlJsInAppMessages?: boolean;
+    /**
+     * Tracking consent at start-up. Same option and values as the web, iOS,
+     * Android and Unity SDKs.
+     *
+     * Leave it UNSET unless your consent banner has an answer for this launch.
+     * Unset means "no decision here": with nothing stored the SDK runs as
+     * `'granted'`, and a `'denied'` stored by an earlier launch stays in force.
+     * Passing `'granted'` is an explicit decision and lifts a stored denial.
+     *
+     *  - `'granted'` - normal operation.
+     *  - `'pending'` - nothing is SENT: events and attribute writes queue on the
+     *    device (bounded by `maxQueueSize`), and there is no session start, no
+     *    in-app sync and no push registration until you call
+     *    `updateConsent('granted')`. `updateConsent('denied')` discards them.
+     *    Applies to this launch only and never replaces a stored `'denied'`.
+     *  - `'denied'` - nothing is collected and queued events are cleared. Stored,
+     *    so it holds on later launches until `updateConsent('granted')` or an
+     *    explicit `trackingConsent: 'granted'`.
+     *
+     * Consent and the opt-out ({@link JoryioSDK.optOut}) are separate switches,
+     * and any "no" wins: `'granted'` never cancels an opt-out.
+     */
+    trackingConsent?: TrackingConsent;
+    /**
+     * Start opted out of tracking (default: false). The same as calling
+     * {@link JoryioSDK.optOut} straight after initialize(), without the window in
+     * between. An opt-out is stored on the device and survives restarts, so
+     * passing `false` here does not undo an earlier `optOut()` - call `optIn()`.
+     */
+    optOut?: boolean;
+    /**
+     * Android only: the name of the notification channel Joryio push uses, as
+     * people see it in system Settings (Android 8+). Pass it localized - for
+     * example from your app's own strings. Omit to use the native default,
+     * "Notifications". Ignored on iOS, which has no notification channels.
+     */
+    notificationChannelName?: string;
+}
+/** Tracking consent values, identical on every Joryio SDK. */
+export type TrackingConsent = 'granted' | 'denied' | 'pending';
+/**
+ * Attribute values. `null` UNSETS the attribute - the same as
+ * `unsetAttribute(key)` - on both platforms.
+ */
+export type UserAttributes = Record<string, string | number | boolean | null>;
+/**
+ * Notification permission state, identical on iOS and Android.
+ *
+ * `unavailable` means we could not ask at all (no Activity, SDK not ready, or a
+ * platform with no notification support) - distinct from `denied`, which means
+ * the user said no and the prompt will not appear again.
+ */
+export type PushPermissionStatus = 'granted' | 'denied' | 'notDetermined' | 'unavailable';
+/** Reason an ingest request was rejected with a 401 `sdk_authentication_error`. */
+export interface SdkAuthError {
+    reason: 'missing' | 'invalid' | 'expired' | 'sub_mismatch' | 'unknown';
+    /**
+     * Raw wire `reason` string, for logging / forward-compat.
+     *
+     * Worth reading whenever `reason` is `'unknown'`: that value means only that
+     * THIS SDK version did not recognise what the server sent, and this is the
+     * only place the server's actual word survives.
+     */
+    rawReason?: string;
+    /** The ingest endpoint whose request was rejected. */
+    endpoint?: string;
+    /**
+     * The SDK has STOPPED trying for this request - either no fresh token
+     * arrived, or one did and was rejected as well.
+     *
+     * `false` means the SDK is asking you for a token; `true` means it gave up.
+     * Branch on this rather than on the arrival of an error, or a handler that
+     * signs the user out fires on the first recoverable rejection.
+     *
+     * Both platforms emit all four fields. Until 2026-08-31 iOS sent
+     * {reason, endpoint, refreshExhausted} and Android sent {reason, rawReason},
+     * so half of any handler was dead on whichever platform was not tested.
+     */
+    refreshExhausted?: boolean;
+}
+/**
+ * An in-app message to display.
+ *
+ * `kind` discriminates the content. BOTH kinds reach JS: a React Native app
+ * renders its own UI, so dropping native here would mean native campaigns never
+ * display in RN apps while still counting as delivered server-side.
+ *
+ * Native fields are TEXT, not markup - the server does not HTML-escape them
+ * (escaping would show the user `A &amp; B`), so rendering one into a WebView
+ * or `dangerouslySetInnerHTML` would reintroduce the injection native avoids.
+ * Put them in a <Text>.
+ */
+export type InAppMessage = InAppMessageBase & ({
+    kind: 'html';
+    html: string;
+    css: string;
+} | {
+    kind: 'native';
+    title?: string;
+    body: string;
+    imageUrl?: string;
+    buttons: Array<{
+        id: string;
+        text: string;
+        /**
+         * What the button does when your renderer draws it:
+         *
+         *  - `dismiss` - close the message.
+         *  - `url` - open `url` in the browser.
+         *  - `deep_link` - route to `url` inside your app.
+         *  - `request_push_permission` - a push primer's "yes" button: close
+         *    the message and call `Joryio.requestPushPermission()`.
+         *
+         * Report the tap with `trackInAppImpression(message.id, 'clicked')`
+         * in every case.
+         */
+        action: InAppButtonAction;
+        url?: string;
+    }>;
+    closeButton: boolean;
+    backdropDismissible: boolean;
+    /**
+     * Optional presentation overrides set by the campaign author.
+     *
+     * Every field is optional and an absent one means INHERIT your app's
+     * own styling - which is why a message with no overrides looks like the
+     * rest of your UI. Apply the ones that are present; do not substitute
+     * defaults of your own for the ones that are not.
+     *
+     * `fontFamily` is best effort: apply it only if your app bundles that
+     * font, and keep your own typeface when it does not - substituting an
+     * arbitrary font looks worse than ignoring the override.
+     */
+    style?: {
+        backgroundColor?: string;
+        textColor?: string;
+        primaryButtonColor?: string;
+        primaryButtonTextColor?: string;
+        cornerRadius?: number;
+        /** Body size; scale the headline from it to keep the hierarchy. */
+        fontSize?: number;
+        titleWeight?: 'regular' | 'medium' | 'semibold' | 'bold';
+        /**
+         * `auto` (or absent) means align by the MESSAGE's own language, not
+         * the device locale - `I18nManager.isRTL` is the wrong test, because
+         * one workspace sends Hebrew and English to the same app. React
+         * Native's `writingDirection: 'auto'` does this for you.
+         */
+        textAlign?: 'auto' | 'start' | 'center' | 'end';
+        /** Apply only if your app bundles it; otherwise keep your own. */
+        fontFamily?: string;
+    };
+});
+/** Native in-app button actions, spelled as both native bridges send them. */
+export type InAppButtonAction = 'dismiss' | 'url' | 'deep_link' | 'request_push_permission';
+export interface InAppMessageBase {
+    id: string;
+    name: string;
+    type: 'modal' | 'banner' | 'slideup' | 'fullscreen' | 'custom';
+    priority: number;
+}
+/** The server's verdict on a form submitted from an HTML in-app message. */
+export interface InAppFormResult {
+    ok: boolean;
+    message?: string;
+    redirect?: string;
+    errors?: string[];
+}
+/**
+ * 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.
+ */
+export declare const MAX_PRE_INIT_CALLS = 1000;
+/**
+ * Outcome of `registerPushToken`. Same four fields as the native
+ * `PushRegistrationResult` on Android and iOS.
+ */
+export interface PushRegistrationResult {
+    success: boolean;
+    /** Provider or transport message on failure; absent on success. */
+    message?: string;
+    /** A bad or missing SDK key - retrying will not fix it. */
+    isUnauthorized: boolean;
+    /** Transient (offline, DNS, 5xx, not initialized yet): worth another try. */
+    isRetryable: boolean;
+}
+declare class JoryioSDK {
+    /**
+     * Resolves once initialize() has completed. This is the SDK's readiness
+     * primitive, and BOTH call shapes are built on it:
+     *
+     *  - fire-and-forget calls (track, identify, …) chain onto it, so they run
+     *    after init instead of hitting an uninitialized native module;
+     *  - value-returning calls (getAnonymousId, getUserId, …) AWAIT it, which a
+     *    callback queue could never do — you cannot buffer something the caller
+     *    is waiting on the answer to.
+     *
+     * That gap is what broke React Native in-app messaging: the queue covered the
+     * void calls, so every getter called before init threw "Joryio SDK not
+     * initialized" straight through to a red box.
+     */
+    private _ready;
+    private _markReady;
+    /** True once initialize() has completed SUCCESSFULLY. */
+    private _initialized;
+    /**
+     * 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.
+     */
+    private _initFailed;
+    /**
+     * 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).
+     */
+    private _pending;
+    /** The initialize() call in progress, if any. A second call joins it. */
+    private _initInFlight;
+    private _warnedPendingOverflow;
+    /**
+     * 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.
+     */
+    private _wipeHandedToNative;
+    /**
+     * 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.
+     */
+    private _preInitOptedOut;
+    private _preInitDenied;
+    /**
+     * 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.
+     */
+    private _initConfigOptedOut;
+    private _initConfigDenied;
+    /**
+     * 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.
+     */
+    private _storedOptedOut;
+    private _storedDenied;
+    /** Settles once the stored decisions are known (or could not be read). */
+    private _storedKnown;
+    private _warnedDroppedWhileOptedOut;
+    /** Live onInAppMessage subscriptions. Rendering is handed to JS only while > 0. */
+    private _inAppListeners;
+    constructor();
+    /**
+     * 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.
+     */
+    private _readStoredDecisions;
+    /**
+     * 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.
+     */
+    private _refusedBeforeInit;
+    /**
+     * 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).
+     */
+    private _settleStored;
+    /**
+     * 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).
+     */
+    private _rejudgeWithoutInitConfig;
+    private _warnDroppedWhileRefused;
+    /**
+     * 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.
+     */
+    private _awaitReady;
+    /**
+     * 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.
+     */
+    private _queryDecision;
+    /**
+     * 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.
+     */
+    private _dispatch;
+    /**
+     * 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.
+     */
+    private _evictOneHeld;
+    /**
+     * 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.
+     */
+    private _decide;
+    /**
+     * 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.
+     */
+    private _handHeldDecisionsToNative;
+    /** Hand the held withdrawals to native now, in order; keep the rest held. */
+    private _sendHeldWithdrawalsNow;
+    /** Drop the held calls of these kinds; keep the rest, in order. */
+    private _discardHeld;
+    private _invoke;
+    /**
+     * Replay the calls held before a SUCCESSFUL init. After a failed one they
+     * stay held for the next initialize() (see _dispatch).
+     */
+    private _drainPending;
+    /**
+     * 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`.
+     */
+    private _query;
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    initialize(sdkKey: string, apiHost: string, config?: JoryioConfig): Promise<void>;
+    private _initialize;
+    /**
+     * 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: string, properties?: Record<string, unknown>): void;
+    /**
+     * Track a screen view.
+     *
+     * @example
+     * ```ts
+     * Joryio.trackScreen('ProductDetail', { productId: '123' });
+     * ```
+     */
+    trackScreen(screenName: string, properties?: Record<string, unknown>): void;
+    /**
+     * 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: string): void;
+    /**
+     * 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: string, aliasName: string): void;
+    /**
+     * Reset the user identity. Call this on logout.
+     * Clears user ID, starts new anonymous session, clears in-app messages.
+     */
+    reset(): void;
+    /**
+     * 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(): void;
+    /**
+     * 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(): void;
+    /**
+     * 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(): void;
+    /**
+     * 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(): Promise<boolean>;
+    /**
+     * 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: TrackingConsent): void;
+    /**
+     * 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(): Promise<TrackingConsent | null>;
+    /**
+     * 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: SubscriptionChannel, status: SubscriptionStatus): void;
+    /** Join a subscription group (list) on a channel. */
+    addToSubscriptionGroup(groupId: string, channel: SubscriptionChannel): void;
+    /** Leave a subscription group (list) on a channel. */
+    removeFromSubscriptionGroup(groupId: string, channel: SubscriptionChannel): void;
+    /**
+     * Set multiple user attributes at once.
+     *
+     * @example
+     * ```ts
+     * Joryio.setAttributes({
+     *   firstName: 'John',
+     *   plan: 'premium',
+     *   age: 28,
+     * });
+     * ```
+     */
+    setAttributes(attributes: UserAttributes): void;
+    /**
+     * Set a single user attribute. `null` unsets it.
+     */
+    setAttribute(key: string, value: string | number | boolean | null): void;
+    /**
+     * Increment a numeric user attribute.
+     *
+     * @example
+     * ```ts
+     * Joryio.incrementAttribute('loginCount', 1);
+     * ```
+     */
+    incrementAttribute(key: string, by?: number): void;
+    /**
+     * Remove a user attribute.
+     */
+    unsetAttribute(key: string): void;
+    /**
+     * 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);
+     * });
+     * ```
+     */
+    registerPushToken(token: string): Promise<PushRegistrationResult>;
+    /**
+     * 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: string): void;
+    /**
+     * Unregister from push notifications.
+     */
+    unregisterPush(): void;
+    /**
+     * 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.
+     */
+    getPushPermissionStatus(): Promise<PushPermissionStatus>;
+    /**
+     * 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.
+     */
+    requestPushPermission(): Promise<PushPermissionStatus>;
+    /**
+     * Check if push notifications are enabled.
+     */
+    isPushEnabled(): Promise<boolean>;
+    /**
+     * Track a push notification click (for analytics).
+     * Call this when the user taps a push notification.
+     */
+    trackPushClick(trackingId: string): void;
+    /**
+     * 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: (message: InAppMessage) => unknown, options?: {
+        capabilities?: Array<'content.native' | 'content.html'>;
+    }): () => void;
+    /**
+     * 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?: string[]): void;
+    /**
+     * Hand in-app rendering back to the native SDK after
+     * {@link enableInAppMessages}. Removing the last `onInAppMessage` listener
+     * does this for you.
+     */
+    disableInAppMessages(): void;
+    private _ecommerce?;
+    /**
+     * 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(): JoryioEcommerce;
+    /**
+     * 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: string, action: string, elementId?: string): void;
+    /**
+     * 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`.
+     */
+    submitInAppForm(campaignId: string, values: Record<string, string | string[]>): Promise<InAppFormResult>;
+    /**
+     * 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: string): void;
+    /**
+     * 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);
+     * });
+     * ```
+     */
+    onSdkAuthenticationError(callback: (error: SdkAuthError) => unknown): () => void;
+    /**
+     * Flush the event queue immediately.
+     * Events are normally batched and sent periodically.
+     */
+    flush(): void;
+    /**
+     * 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(): void;
+    /**
+     * 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(): void;
+    /**
+     * 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.
+     */
+    getDiagnostics(): Promise<{
+        apiEndpoint: string | null;
+        lastError?: {
+            message: string;
+            isUnauthorized: boolean;
+            isRetryable: boolean;
+            at: number;
+        };
+    }>;
+    /**
+     * Get the anonymous ID assigned to this device.
+     */
+    getAnonymousId(): Promise<string>;
+    /**
+     * Get the current user ID (null if not identified).
+     */
+    getUserId(): Promise<string | null>;
+    /**
+     * Get the current session ID.
+     */
+    getSessionId(): Promise<string>;
+}
+/** A product as the e-commerce tracker expects it. */
+export interface EcommerceProduct {
+    productId: string;
+    name: string;
+    price: number;
+    quantity?: number;
+    category?: string;
+    brand?: string;
+    variant?: string;
+    variantId?: string;
+    sku?: string;
+    imageUrl?: string;
+    url?: string;
+}
+/** A cart line. `quantity` is required here; a line without one is not a line. */
+export interface EcommerceCartItem extends EcommerceProduct {
+    quantity: number;
+}
+export interface EcommerceOrder {
+    orderId: string;
+    items: EcommerceCartItem[];
+    value: number;
+    currency?: string;
+    shipping?: number;
+    tax?: number;
+    discount?: number;
+    coupon?: string;
+}
+declare class JoryioEcommerce {
+    private readonly sdk;
+    constructor(sdk: JoryioSDK);
+    private send;
+    private product;
+    /** Every line (a null entry is skipped, and not sent) a valid product. */
+    private lines;
+    private text;
+    private amount;
+    /** Absent is fine; present must be finite. */
+    private optionalAmount;
+    private cart;
+    viewProduct(product: EcommerceProduct): void;
+    viewCategory(categoryId: string, categoryName: string): void;
+    search(query: string, resultCount?: number): void;
+    addToCart(item: EcommerceCartItem, cartValue?: number): void;
+    removeFromCart(product: EcommerceProduct, quantity?: number): void;
+    cartViewed(items: EcommerceCartItem[], cartValue: number): void;
+    updateCart(items: EcommerceCartItem[], cartValue: number): void;
+    startCheckout(items: EcommerceCartItem[], cartValue: number): void;
+    addPaymentInfo(paymentMethod: string): void;
+    /**
+     * 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: EcommerceOrder): void;
+    orderFulfilled(orderId: string, trackingNumber?: string, carrier?: string): void;
+    orderDelivered(orderId: string): void;
+    orderCancelled(orderId: string, reason?: string): void;
+    orderRefunded(orderId: string, refundAmount?: number, reason?: string): void;
+    addToWishlist(product: EcommerceProduct): void;
+    removeFromWishlist(product: EcommerceProduct): void;
+    shareProduct(product: EcommerceProduct, shareMethod: string): void;
+    applyCoupon(couponCode: string, discountAmount?: number, discountType?: string): void;
+    removeCoupon(couponCode: string): void;
+    submitReview(productId: string, rating: number, reviewText?: string): void;
+}
+declare const Joryio: JoryioSDK;
+/** Also exported standalone, for `import {ecommerce} from ...`. */
+export declare const ecommerce: JoryioEcommerce;
+export default Joryio;