react-native-revnix 1.4.0

package/dist/client.d.ts

@@ -0,0 +1,402 @@
+import type { AdRevenue, AliasResult, CustomerEntitlements, IdentifyResult, IdentifyStrategy, IdentityInfo, LastDeepLink, MmpAttribution, PaywallInteraction, PlacementResolution, RegisterPurchaseInput, RegisterPurchaseResult, RevnixAttribution, RevnixConfig } from "./types.js";
+export declare class RevnixClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly storage;
+    private readonly fetchImpl;
+    private readonly reportInstalls;
+    private readonly persistentStorage;
+    /** True while the current id is a generated anon id living on
+     *  NON-persistent storage — it changes every launch, so sending it to
+     *  the experiments path would mint a phantom enrollment per launch
+     *  (same hazard class the M5 install guard covers). */
+    private ephemeralAnonId;
+    private readonly installMetadata?;
+    private readonly platform;
+    private readonly deviceHeaderPromise;
+    private readonly requestTimeoutMs;
+    private readonly readYourWritesDelaysMs;
+    private readonly offlineMaxCacheAgeMs;
+    private readonly entitlementsTtlMs;
+    private readonly onDiagnostic?;
+    private bgFailures;
+    private disposed;
+    private customerIdPromise;
+    private readonly onImplicitPaywall?;
+    private readonly onDeferredDeepLink?;
+    private readonly onAttribution?;
+    private deferredDeepLinkClaimed;
+    private landingUrl;
+    private lastDeepLinkWrite;
+    private readonly implicitEnabled;
+    private readonly sessionTimeoutMs;
+    private implicitConfigPromise;
+    private implicitConfigRetryAt;
+    private lifecycleUnsubscribe;
+    /** The cold-start batch while it runs, resolving to whether it presented a
+     *  paywall. A deep link delivered on the first frame — SwiftUI's onOpenURL,
+     *  RN's getInitialURL — must wait for it, or the customer gets the launch
+     *  paywall AND the link paywall stacked. Null once the batch is over. */
+    private launchBatch;
+    /** When the app last went to the BACKGROUND, or null while it has not.
+     *  A return after `sessionTimeoutMs` away is a new session; anything sooner
+     *  is an app switch. Measured from the background transition, not from the
+     *  last return — the latter would mint a session after 35 minutes of
+     *  continuous use plus a three-second switch. */
+    private lastBackgroundAt;
+    /** LOOP GUARD: view ids of displays that came FROM an implicit trigger. A
+     *  paywall shown because a paywall was dismissed must not itself fire
+     *  `paywall_decline`, or the customer is handed the same screen forever.
+     *  Recognised from the placementKey the host reports on logPaywallShown —
+     *  a host that reports no placementKey cannot be protected here, which is
+     *  why the server keeps its own same-paywall backstop. */
+    private readonly implicitViewIds;
+    /** True when this launch generated a fresh anonymous id — the same signal
+     *  /v1/installs uses, and independent of the device header (which an app
+     *  can turn off entirely). */
+    private freshInstall;
+    constructor(config: RevnixConfig);
+    /** The id every call is made as: the stored identified/canonical id, or a
+     *  generated-and-persisted anonymous id (rvx_anon_…) on first launch. */
+    getCustomerId(): Promise<string>;
+    private requireSecretKey;
+    /** Merges the current (usually anonymous) customer into `userId`. The
+     *  canonical id from the response becomes the id all subsequent calls use.
+     *  Safe to call repeatedly — a no-op when already identified as `userId`.
+     *
+     *  Secret-key only — call this from YOUR BACKEND on login, not from the
+     *  device. On a publishable key it throws RevnixAuthError locally, before
+     *  any network call: identity merges from a device would let any caller
+     *  claim any customer. Device flow: send `getCustomerId()` and your user id
+     *  to your server, identify there with an rvx_sk_ key, and the device picks
+     *  up the canonical id on its next registerPurchase() (its response always
+     *  carries the caller's canonical id). */
+    identify(userId: string, options?: {
+        strategy?: IdentifyStrategy;
+    }): Promise<IdentifyResult>;
+    /** Attach an additional external id (legacy id, email hash, …) to the
+     *  current customer without switching to it.
+     *
+     *  Secret-key only, like identify() — throws RevnixAuthError locally on a
+     *  publishable key; call it from your backend instead. */
+    alias(aliasId: string): Promise<AliasResult>;
+    /** Call on logout: forget the identified customer and start a fresh
+     *  anonymous one. Never merges — purchases made while logged out belong
+     *  to the new anonymous customer until the next identify(). */
+    logout(): Promise<string>;
+    /** Call right after a successful store purchase: binds the store token to
+     *  the current customer and appends the purchase to the ledger, so
+     *  entitlement never waits on the store webhook. Throws
+     *  PurchaseBlockedError when the token belongs to another customer and the
+     *  app's transfer behavior forbids reassignment. */
+    registerPurchase(input: RegisterPurchaseInput): Promise<RegisterPurchaseResult>;
+    private postPurchase;
+    /** C7: retry purchases that failed to register and were persisted locally.
+     *  Runs automatically at construction; call again when connectivity returns.
+     *  Idempotent and safe to call repeatedly. */
+    retryPendingPurchases(): Promise<void>;
+    private freshEntitlements;
+    private inflightEntitlements;
+    /** Current entitlements for this customer, merged across every id linked to
+     *  them. Served from memory when a fresh network read is younger than
+     *  `entitlementsTtlMs` (REV-199 — pass 0 to disable); otherwise reads the
+     *  network (concurrent callers share one request) and caches the result; if
+     *  that read FAILS transiently (offline / incident) it falls back to the
+     *  last cached entitlements with `stale: true`, so a paying customer is
+     *  never shown as unsubscribed just because the network is down. Throws on
+     *  a deliberate server rejection (revoked key, …) or when there is nothing
+     *  cached. */
+    getEntitlements(): Promise<CustomerEntitlements>;
+    /** The authoritative network read: no TTL, no cache fallback — throws so
+     *  the caller sees the real failure (waitForEntitlements needs 429s). */
+    private fetchFreshEntitlements;
+    private fetchEntitlementsWithFallback;
+    /** M9: read-your-writes — poll getEntitlements until the response's ledger
+     *  cursor is at least `seq` (i.e. the read provably includes that write),
+     *  then resolve with it. Resolves with the LAST read if the delays run out
+     *  or reads only come from the stale cache — never spins forever. Called
+     *  automatically by registerPurchase; public for manual flows (e.g. after
+     *  a webhook-driven grant the app learns about out-of-band). */
+    waitForEntitlements(seq: number): Promise<CustomerEntitlements>;
+    /** C7: the last entitlements cached for the current customer, with NO network
+     *  call — for an instant, offline-safe gate at launch. Always `stale: true`;
+     *  follow with getEntitlements() to revalidate. Null if nothing is cached. */
+    getCachedEntitlements(): Promise<CustomerEntitlements | null>;
+    /** REV-157: cached entitlements are a snapshot — re-evaluate expiry against
+     *  the local clock when serving them, so a subscription that ended long ago
+     *  never stays "active" offline forever. Active entitlements keep access
+     *  for LOCAL_EXPIRY_GRACE_MS past expiresAt (the renewal an offline device
+     *  cannot see yet). Inactive stays inactive; no expiresAt (lifetime/grant)
+     *  is untouched. */
+    private withLocalExpiry;
+    /** Convenience: is one entitlement active right now? */
+    isEntitled(entitlementId: string): Promise<boolean>;
+    /** How the current id resolves: canonical id, alias status, linked ids.
+     *
+     *  Secret-key only — the response is an identity graph, so the server 403s
+     *  a publishable key (REV-184). On an rvx_pk_ key this throws
+     *  RevnixAuthError locally, before any network call, like identify(). */
+    getIdentity(): Promise<IdentityInfo>;
+    /** Resolve a named in-app location to the currently published offering —
+     *  the one-line paywall call. REV-157: reads the network first and caches
+     *  the result; if that read FAILS (offline / incident) it falls back to the
+     *  last cached resolution with `stale: true`, so the paywall renders the
+     *  last published version rather than not at all. Throws only when there
+     *  is nothing cached. */
+    resolvePlacement(placementKey: string): Promise<PlacementResolution>;
+    /** REV-157: the last resolution cached for `placementKey`, with NO network
+     *  call — for an instant, offline-safe paywall at launch. Always
+     *  `stale: true`; follow with resolvePlacement() to revalidate. Null if
+     *  nothing is cached yet. */
+    getCachedPlacement(placementKey: string): Promise<PlacementResolution | null>;
+    /** Report that a paywall was displayed (REV-094). Fire-and-forget like
+     *  install reporting — never blocks rendering and never throws; each call
+     *  is one view (retries of the same display are deduped by viewId).
+     *  RevnixPaywall calls this automatically when given a `client`; headless
+     *  paywall UIs call it on their own show event. Powers the analytics
+     *  funnel's "Paywall displayed" stage and View → Trial/Paid conversions.
+     *
+     *  Returns the view id it generated (REV-252). Hold onto it and hand it to
+     *  logPaywallClosed when the customer dismisses this display: the pair
+     *  sharing one id is what lets the ledger tie a close to the display it
+     *  ended, rather than guessing from timestamps. Ignoring the return value
+     *  is still valid — it stays a fire-and-forget beacon. */
+    logPaywallShown(options?: {
+        placementKey?: string;
+        paywallId?: string;
+    }): string;
+    /** Report that the customer dismissed a paywall (REV-252) — the other half
+     *  of a display's life. Fire-and-forget and idempotent per view id, exactly
+     *  like logPaywallShown.
+     *
+     *  Pass the id that logPaywallShown returned for THIS display. The two
+     *  events then share a view id, so a reader can pair them, and the gap
+     *  between their timestamps is the customer's dwell on the screen. Calling
+     *  it with a fresh id still records a dismissal; it just cannot be tied
+     *  back to the display it ended. RevnixPaywall does all of this for you.
+     *
+     *  A close is a DECLINE. Do not report one for a display that ended in a
+     *  purchase — with implicit placements on, a close is also the
+     *  `paywall_decline` moment, and a win-back offer seconds after a successful
+     *  purchase is the one thing an operator never means. RevnixPaywall only
+     *  reports the close affordances, never a purchase-driven dismissal. */
+    logPaywallClosed(viewId: string, options?: {
+        placementKey?: string;
+        paywallId?: string;
+    }): void;
+    /** Report one of the six paywall interactions (REV-263) — what the customer
+     *  DID on a display, between the `logPaywallShown` that opened it and the
+     *  `logPaywallClosed` (or purchase) that ended it:
+     *
+     *    - `selected` — a package was picked
+     *    - `purchase_started` — checkout was started
+     *    - `purchase_abandoned` — the customer backed out at the store sheet
+     *    - `purchase_failed` — the store refused the payment
+     *    - `restore` — restore purchases was tapped
+     *    - `error` — the paywall itself failed (config, products, render)
+     *
+     *  Fire-and-forget like the other beacons: never blocks, never throws.
+     *
+     *  `viewId` is the id `logPaywallShown` returned for THIS display. Passing
+     *  it is what threads the whole life of one impression together and puts
+     *  the event on the paywall's own analytics row — a fresh id still records
+     *  the event, it just cannot be tied back to the display.
+     *
+     *  RevnixPaywall reports `selected`, `purchase_started`, `restore` and a
+     *  no-products `error` for you. The purchase OUTCOME is yours: only the
+     *  host performs the store call, so report `purchase_abandoned` /
+     *  `purchase_failed` from your own StoreKit / Play error handling — or let
+     *  RevnixPaywall do it by returning the outcome from `onPurchase`.
+     *
+     *  `eventId` is the idempotency key and defaults to the display's `viewId`,
+     *  which caps the report at one per display per event type. Pass one per
+     *  occurrence (and reuse it across your own retries) to record every
+     *  occurrence — e.g. a customer who fails, retries and fails again. */
+    logPaywallEvent(event: PaywallInteraction, viewId: string, options?: {
+        placementKey?: string;
+        paywallId?: string;
+        productId?: string;
+        /** Store error code — `purchase_failed` / `error`. */
+        code?: string;
+        message?: string;
+        /** Idempotency key for this occurrence; defaults to `viewId`. */
+        eventId?: string;
+    }): void;
+    /** Reports one ad impression's payout (POST /v1/ad-revenue).
+     *  Fire-and-forget like the other beacons: never blocks, never throws. */
+    logAdRevenue(input: AdRevenue): void;
+    /** Reports one custom in-app event (POST /v1/events), not for purchases.
+     *  Fire-and-forget like the other beacons: never blocks, never throws. */
+    track(event: string, properties?: Record<string, string | number | boolean>, options?: {
+        eventId?: string;
+    }): void;
+    /** PT11: forward an MMP's attribution callback (Adjust, AppsFlyer, …) so
+     *  Revnix credits revenue to the right network/campaign. */
+    setAttribution(attribution: MmpAttribution): void;
+    /** Register this device's push token for uninstall measurement: Revnix
+     *  sends a daily silent probe and records `app.uninstalled` when APNs/FCM
+     *  report the token dead. iOS/Android only (no-op on web),
+     *  fire-and-forget. */
+    setPushToken(token: string): void;
+    /** REV-272: the two moments that happen ON a paywall, with the loop guard
+     *  applied. `fromPaywallId` travels so the server can refuse to hand back
+     *  the very paywall being dismissed — the backstop for a host that reports
+     *  no placementKey, and for an operator who pointed the rule at the source
+     *  paywall by hand. */
+    private fireImplicitFromPaywall;
+    /** Set attributes on the current customer (REV-033 v2). Attributes are what
+     *  A/B-test audiences target, so this is how a mobile-only app becomes able
+     *  to run "US + UK users" tests: set `country`, `app_version`, `locale`, or
+     *  any custom key you want to segment on.
+     *
+     *  Pass `null` as a value to delete a key. Awaits the write — unlike the
+     *  fire-and-forget telemetry calls — because the very next placement
+     *  resolve may depend on it, and silently racing the audience check would
+     *  make targeting look broken.
+     *
+     *  Two server rules to know: `email` and `username` are reserved and only
+     *  settable with a secret key from your own backend, and any attribute your
+     *  backend already set is authoritative and cannot be changed from a device.
+     *  Both throw rather than partially applying. */
+    setAttributes(attributes: Record<string, string | number | null>): Promise<void>;
+    /** REV-272: hand the SDK the URL that opened your app, from wherever you
+     *  already receive it (Linking.getInitialURL / onNewIntent / your router).
+     *  This is the one implicit moment the SDK cannot see for itself — the URL
+     *  goes to your entry point, and an SDK intercepting it would be fighting
+     *  your router.
+     *
+     *  Fire-and-forget: never blocks, never throws. An ordinary link is
+     *  always reported so its `link.*` facts land on the customer; it only
+     *  presents a paywall when implicit placements are on AND `deeplink_open`
+     *  is configured in the dashboard. A dashboard preview link is always
+     *  handed to `onImplicitPaywall`. */
+    handleDeepLink(url: string): void;
+    /** Most recent deep link seen via `handleDeepLink` or a delivered
+     *  deferred deep link. Null when none recorded. Never throws. */
+    getLastDeepLink(): Promise<LastDeepLink | null>;
+    /** AT11: the install-attribution verdict for this customer — `null` when
+     *  none has been recorded yet (a normal cold-start race, matching the
+     *  server's `installMatch: "unknown"`) or when the read fails. Fetches
+     *  fresh on every call rather than caching in memory, since the point is
+     *  to answer with whatever the server currently believes; a changed
+     *  answer also reaches `onAttribution`, so a host that only wants updates
+     *  need not call this at all. Never throws. */
+    getAttribution(): Promise<RevnixAttribution | null>;
+    private refreshAttribution;
+    private deliverAttribution;
+    private rememberDeepLink;
+    private presentPreview;
+    /**
+     * REV-283: hand over the Android Play Store install referrer.
+     *
+     * The deferred half of link attribution. A deep link only ever reaches an
+     * app that already exists, which leaves out the customers an ad actually
+     * won — they saw it, had no app, and installed one. Google Play carries a
+     * referrer string through that install, so on Android the answer is exact
+     * rather than guessed. (Apple ships no equivalent; that half stays an
+     * attribution provider's job.)
+     *
+     * Read it yourself with the Play Install Referrer library and pass the raw
+     * string — `utm_source=instagram&utm_medium=cpc` — exactly as you received
+     * it. The SDK cannot read it for you: it is an Android API behind a service
+     * binding, and a cross-platform SDK has no business linking it.
+     *
+     * Safe to call late, and safe to call twice. The Play API answers
+     * asynchronously, so the install has usually been reported already; the
+     * server absorbs the duplicate and seeds the campaign facts from it anyway.
+     * They are fill-only, so a deep link the customer has opened since is never
+     * overwritten.
+     *
+     * Fire-and-forget: never blocks, never throws.
+     */
+    handleInstallReferrer(referrer: string): void;
+    /**
+     * AT9: the Apple Search Ads half of install attribution. `AAAttribution
+     * .attributionToken()` is an iOS framework call with no JavaScript
+     * binding, so a React Native host mints the token in a native module and
+     * hands it here — this package cannot mint it itself.
+     *
+     * Unlike `handleInstallReferrer`, this resolves to the server's verdict
+     * (`InstallResponse.appleAttribution`) rather than returning void, because
+     * a freshly minted token is unregistered on Apple's side for a few
+     * seconds and the server reports that as `"pending"`. The native iOS SDK
+     * retries on its own in that case; a host driving this manually needs the
+     * verdict to know whether a fresh token on the next cold start is worth
+     * trying. `"resolved"` (Apple named a campaign) and `"organic"` (Apple
+     * answered, not an ASA install) are final. Resolves to `undefined` when a
+     * guard held or the request failed — safe to leave unawaited.
+     *
+     * Same guards as `handleInstallReferrer`, same reasons: bails when
+     * disposed, when the trimmed token is empty, and when `ephemeralAnonId` is
+     * set, since an id that changes every launch would file the campaign
+     * against a customer nobody will see again.
+     */
+    handleAttributionToken(token: string): Promise<string | undefined>;
+    /** Unwraps a link an email provider rewrote through its click-tracking
+     *  domain into the deep link it points at. Never throws; returns `url`
+     *  unchanged on any failure. The result can still be an http(s) URL if the
+     *  chain could not be unwrapped, so check the scheme before routing on it. */
+    resolveDeepLink(url: string): Promise<string>;
+    private implicitConfig;
+    /** REV-272: report one implicit moment and present whatever it resolves to.
+     *  Fire-and-forget in every direction — this runs on an app launch and on
+     *  every return to the foreground, so it must never be able to throw into
+     *  the host or delay a frame. */
+    private fireImplicit;
+    /** The trigger itself. Resolves to true when a paywall was handed to the
+     *  host. `present` false still reports the moment (its ledger event is a
+     *  fact either way) but hands nothing over — how the launch batch keeps a
+     *  cold start to ONE paywall. Never throws past its caller's catch. */
+    private triggerImplicit;
+    private consumePreviousSessionMs;
+    /** REV-272: the launch-time moments, plus the foreground listener that
+     *  `session_start` is built on.
+     *
+     *  A cold start is always both a launch AND a session — an operator who
+     *  configured only `session_start` still wants the first one — and it is an
+     *  install too when this launch generated the anonymous id. All three are
+     *  independent placements, so an app may have any subset configured and the
+     *  others cost nothing. */
+    private startImplicit;
+    private onAppState;
+    /** REV-204 (L10): stop this client's background work (purchase retries,
+     *  read-your-writes polls). Called automatically when Revnix.configure()
+     *  replaces the singleton; call it yourself when discarding a manually
+     *  constructed client. */
+    dispose(): void;
+    /** A block paywall reporting a paint string it could not read. Routed to the
+     *  same sink as every other swallowed failure, so a host that already wired
+     *  `onDiagnostic` needs no new wiring to see render fallbacks. */
+    reportRenderDiagnostic(message: string): void;
+    private diag;
+    private deliverDeferredDeepLink;
+    private loadCustomerId;
+    /** Fire-and-forget install report (REV-093). Never blocks startup and
+     *  never throws — the backend absorbs retries idempotently per id. */
+    private reportInstall;
+    /** REV-268: assemble and encode the device facts once. Runtime-detected
+     *  facts first, the app's `device` over them, then the three the SDK owns.
+     *  `installedAt` is the first launch this storage ever saw — written on
+     *  that launch and read back on every later one — and `firstOpen` is true
+     *  for the whole of that first session. Both are skipped on non-persistent
+     *  storage: memory-only storage would make every launch a first open,
+     *  which is the same phantom-new-customer hazard the M5 install guard
+     *  exists for. */
+    private buildDeviceHeader;
+    /** REV-268: the decoded facts this client sends — for tests and for apps
+     *  that want to show what Revnix knows. `null` when disabled. */
+    getDeviceHeader(): Promise<string | null>;
+    private setCustomerId;
+    private readEntitlementsMap;
+    private writeEntitlementsCache;
+    private readEntitlementsCache;
+    private readPlacementMap;
+    private readPlacementCache;
+    private writePlacementCache;
+    private queueLock;
+    private mutateQueue;
+    private readPurchaseQueue;
+    private writePurchaseQueue;
+    private enqueuePurchase;
+    private request;
+}