react-native-revnix 1.4.0

package/src/types.ts

@@ -0,0 +1,528 @@
+// Response and input types for the Revnix /v1 API. These mirror the shapes
+// returned by convex/http.ts in revnix-app — the backend is the source of
+// truth; update here when the API surface changes.
+
+import type {
+  ImplicitTrigger,
+  ImplicitTriggerResponse,
+  RevnixLifecycle,
+} from "./implicit.js";
+
+export type Environment = "sandbox" | "production";
+export type Store = "apple" | "google";
+
+export interface RevnixConfig {
+  /** API key issued from the Revnix dashboard — publishable (rvx_pk_live_… /
+   *  rvx_pk_test_…, safe on-device) or secret (rvx_sk_…, server-side only;
+   *  required for identify/alias). Legacy rvx_live_…/rvx_test_… keys have
+   *  full access. The key fixes both the app and the environment server-side. */
+  apiKey: string;
+  /** Convex site URL of the Revnix deployment, e.g. https://xyz.convex.site */
+  baseUrl: string;
+  /** CTO-SCALE-REVIEW M9: retry delays for the read-your-writes poll after
+   *  registerPurchase (entitlements re-fetched until the read's cursor
+   *  reflects the purchase). Pass [] to disable. Default [250,500,1000,2000]. */
+  readYourWritesDelaysMs?: number[];
+  /** Persistent key-value storage for the customer id. Pass an adapter over
+   *  MMKV/AsyncStorage in React Native; defaults to in-memory (ids reset on
+   *  every app launch — fine for tests, wrong for production). */
+  storage?: RevnixStorage;
+  /** Start as this customer instead of generating/loading an anonymous id. */
+  customerId?: string;
+  /** Custom fetch implementation (tests, polyfills). Defaults to global fetch. */
+  fetch?: typeof fetch;
+  /** Report an install (POST /v1/installs) when a fresh anonymous id is
+   *  generated — powers the dashboard's Installs / install-conversion charts.
+   *  Fire-and-forget; never blocks startup. Defaults to true. */
+  reportInstalls?: boolean;
+  /** Optional device context attached to the install report. Superseded by
+   *  `device` (REV-268), which feeds the install report too; kept so
+   *  existing configurations keep working. */
+  installMetadata?: { platform?: string; appVersion?: string };
+  /** REV-268: facts about the device, sent with every placement resolve so
+   *  targeting rules ("US storefront", "app version at least 3") can be
+   *  evaluated on the request that serves the paywall, and stored on the
+   *  customer as reserved `device.*` attributes visible in the dashboard.
+   *
+   *  In a browser the SDK detects platform, OS version and locale itself;
+   *  everything else — and everything, under React Native — comes from
+   *  here (react-native-device-info has all of it). Fields you leave out are
+   *  simply not reported. Pass `false` to send nothing at all. */
+  device?: DeviceFacts | false;
+  /** C7: per-request timeout in ms (AbortController-based). Defaults to 10000.
+   *  A slow or dead backend then fails fast with RevnixTimeoutError instead of
+   *  hanging the app until the OS TCP timeout (60–120s+). */
+  requestTimeoutMs?: number;
+  /** REV-157: placement keys to resolve-and-cache at construction (fire and
+   *  forget, never blocks startup), so the session's first paywall can render
+   *  from cache even when the device is offline by the time it is shown. */
+  prefetchPlacements?: string[];
+  /** REV-198 (M23): how old a cached entitlements snapshot may be and still
+   *  grant access when served offline. Beyond this (or when the device clock
+   *  sits BEFORE the snapshot was written — a rollback), cached entitlements
+   *  are served inactive. Default 14 days. */
+  offlineMaxCacheAgeMs?: number;
+  /** REV-199 (M21): soft TTL on entitlement reads — a fresh network read
+   *  younger than this answers getEntitlements()/isEntitled() from memory,
+   *  so gating several screens costs one request, not one each. Pass 0 for
+   *  the old always-fetch behavior. Default 30000. */
+  entitlementsTtlMs?: number;
+  /** REV-200 (M26): called whenever a background operation fails — purchase
+   *  retries, placement prefetch, install/paywall reporting, storage
+   *  read/writes. These were all silent (`catch(() => {})`), so a fleet
+   *  failing BEFORE the server (DNS block, broken storage adapter) produced
+   *  no signal anywhere. Wire this to your crash/analytics reporter. Must
+   *  not throw; exceptions from it are swallowed. */
+  onDiagnostic?: (event: RevnixDiagnostic) => void;
+  /** REV-272: called when one of the six implicit moments resolved to a
+   *  paywall — an app launch, a session start, a deep link, a dismissed
+   *  paywall, an abandoned checkout, or the install itself. Present it however
+   *  your app presents paywalls; the SDK deliberately does not present for
+   *  you, because it does not own your navigation stack and a paywall pushed
+   *  over a splash screen is worse than no paywall.
+   *
+   *  Providing this handler is what TURNS IMPLICIT PLACEMENTS ON. Without it
+   *  the SDK makes no extra requests at all — there would be nothing to do
+   *  with the answer. With it, the SDK asks GET /v1/config once at
+   *  construction and then fires only for the moments this app has actually
+   *  configured in the dashboard, so an app that configured none still costs
+   *  one cached response per launch. The one exception is `handleDeepLink`:
+   *  it always reports the URL it is handed, handler or not, because the
+   *  server files that link's attribution facts from the report itself.
+   *
+   *  ⚠️ Pass `trigger.resolution.placementKey` to `logPaywallShown` for the
+   *  display you present. That is what tells the SDK this display came FROM an
+   *  implicit trigger, and it is the only thing that stops a `paywall_decline`
+   *  paywall from firing `paywall_decline` again when the customer dismisses
+   *  it — a loop with no way out but force-quitting. The server refuses to
+   *  serve back the very same paywall as a backstop, but it cannot see a rule
+   *  that points at a DIFFERENT paywall which points back.
+   *
+   *  Never throws into your app: an exception from this handler is reported
+   *  through `onDiagnostic` and swallowed. */
+  onImplicitPaywall?: (trigger: ImplicitTrigger<ImplicitResolution>) => void;
+  /** REV-272: explicit off switch for implicit placements, even when
+   *  `onImplicitPaywall` is set. Defaults to whether that handler is present.
+   *  Does not stop `handleDeepLink` from reporting the link it is handed —
+   *  that report still lands the link's attribution facts on the customer,
+   *  it just never presents a paywall for an ordinary deep link. A dashboard
+   *  preview link is the exception: it always presents. */
+  implicitPlacements?: boolean;
+  /** REV-299: the link the customer clicked before they had the app.
+   *  `POST /v1/installs` returns it whenever the install matched an ad click
+   *  (Android: exact, from the Play Install Referrer; iOS: probabilistic IP
+   *  match) — on Android that can be every referrer call. The SDK delivers it
+   *  to this handler at most once per install. Route it yourself — you may
+   *  also pass it to `handleDeepLink` for `deeplink_open` paywall rules.
+   *  Never throws into your app: an exception from this handler is reported
+   *  through `onDiagnostic` and swallowed. */
+  onDeferredDeepLink?: (
+    url: string,
+    match: "exact" | "probabilistic"
+  ) => void;
+  /** REV-272: how the SDK learns the app came to the foreground, which is what
+   *  `session_start` is built on. Defaults to a `visibilitychange` listener in
+   *  a browser and to nothing under React Native — pass an adapter over
+   *  `AppState` there (see RevnixLifecycle). `false` disables foreground
+   *  detection; launch-time moments still fire. */
+  lifecycle?: RevnixLifecycle | false;
+  /** REV-272: how long the app must have been backgrounded for the return to
+   *  count as a new session rather than an app switch. Default 30 minutes. */
+  sessionTimeoutMs?: number;
+  /** AT11: called whenever the install-attribution verdict changes — a fresh
+   *  Play referrer, an ASA token resolving, or a re-attribution genuinely
+   *  changes the answer, so this can fire more than once across a session
+   *  (Adjust's `attributionChanged` semantics). Fired after the cold-start
+   *  install report resolves, and again after `handleInstallReferrer` or
+   *  `handleAttributionToken` bring in a late signal. Call `getAttribution()`
+   *  for the same answer on demand.
+   *  Never throws into your app: an exception from this handler is reported
+   *  through `onDiagnostic` and swallowed. */
+  onAttribution?: (attribution: RevnixAttribution) => void;
+}
+
+/** AT11: the install-attribution verdict — GET
+ *  /v1/customers/{id}/attribution. `installMatch: "unknown"` (no install
+ *  recorded yet, a normal cold-start race) is never sent to hosts as such;
+ *  `getAttribution()` and `onAttribution` both surface it as `null` instead,
+ *  so there is one "no attribution yet" representation, not two. */
+export interface RevnixAttribution {
+  installMatch: "referrer" | "click" | "impression" | "organic";
+  /** Unix ms. */
+  attributedAt: number;
+  /** Unix ms — set when the customer was later re-attributed. */
+  reattributedAt?: number;
+  linkToken?: string;
+  referrerSource?: string;
+  matchSignals?: string[];
+  source?: string;
+  medium?: string;
+  campaign?: string;
+  term?: string;
+  content?: string;
+}
+
+/** REV-272: what an implicit trigger resolves to — an ordinary placement
+ *  resolution plus why it carries no paywall, when it does not. */
+export type ImplicitResolution = PlacementResolution & ImplicitTriggerResponse;
+
+/** REV-268: the app-suppliable half of the device attribute contract. The
+ *  SDK adds `sdkVersion`, `installedAt` and `firstOpen` itself. Every field
+ *  is optional; the server normalizes case, locale separators and
+ *  alpha-3 storefronts, so pass what the platform gives you. */
+export interface DeviceFacts {
+  /** "ios", "android", "web", … — lowercase family name. */
+  platform?: string;
+  /** e.g. "18.1". */
+  osVersion?: string;
+  /** The host app's version string, e.g. "1.2.10". The server derives a
+   *  zero-padded sortable form (`device.appVersionPadded`) from it. */
+  appVersion?: string;
+  /** "en-US" or "en_US" — either separator. */
+  locale?: string;
+  /** ISO 4217, e.g. "USD". */
+  currency?: string;
+  /** App Store / Play storefront country — alpha-2 ("US") or alpha-3 ("USA"). */
+  storefront?: string;
+  /** Hardware model identifier, e.g. "iPhone15,3". */
+  model?: string;
+  /** True in a sandbox / debug build. */
+  sandbox?: boolean;
+}
+
+/** REV-200 (M26): one background failure. */
+export interface RevnixDiagnostic {
+  /** Which background operation failed, e.g. "retryPendingPurchases",
+   *  "prefetchPlacement", "reportInstall", "logPaywallShown",
+   *  "waitForEntitlements", "storageWrite", "storageRead". */
+  op: string;
+  error: unknown;
+  /** Unix ms. */
+  at: number;
+}
+
+export interface RevnixStorage {
+  getItem(key: string): string | null | Promise<string | null>;
+  setItem(key: string, value: string): void | Promise<void>;
+}
+
+// ——— POST /v1/purchases ———
+
+export interface RegisterPurchaseInput {
+  source: Store;
+  /** Apple: originalTransactionId · Google: purchaseToken. */
+  token: string;
+  productId: string;
+  transactionId: string;
+  /** Unix ms. Defaults server-side to registration time. */
+  occurredAt?: number;
+  /** Unix ms subscription expiry, when the client knows it. */
+  expiresAt?: number;
+  /** Raw store payload to retain in the ledger for reprocessing. */
+  rawPayload?: unknown;
+  /** iOS only — the JWS StoreKit 2 hands you on every transaction
+   *  (`VerificationResult.jwsRepresentation`). Send it and the purchase is
+   *  proven: Revnix verifies it against Apple's certificate chain, checks it
+   *  names this exact transaction, and records a full purchase.
+   *
+   *  Without it the purchase is accepted but PROVISIONAL — a publishable key
+   *  ships inside your app binary, so an unproven claim is only an assertion.
+   *  A provisional purchase still grants the entitlement, for a short window,
+   *  and is promoted automatically when Apple's or Google's own notification
+   *  confirms the charge. Always send it if you can; apps that enable
+   *  "require store-verified purchases" reject claims that lack it. */
+  signedTransactionInfo?: string;
+  /** REV-261: which paywall sold it. Pass the `viewId` `logPaywallShown`
+   *  returned for the display the customer bought from and the server
+   *  resolves it to that view's paywall and placement, so per-paywall
+   *  analytics credit the purchase (and every renewal on it) exactly.
+   *  Without it the server attributes the purchase to the customer's last
+   *  paywall view inside the previous 24 hours. */
+  viewId?: string;
+  /** Explicit paywall / placement; each wins over the view's when sent. */
+  paywallId?: string;
+  placementKey?: string;
+}
+
+export interface RegisterPurchaseResult {
+  eventId: string;
+  /** Ledger position of the write — read-your-writes is assertable (ADR 0004). */
+  seq: number;
+  /** True when the store webhook already recorded this purchase. */
+  duplicate: boolean;
+  /** The id THIS caller should use going forward — its own canonical id.
+   *  Differs from the id you sent only when identity resolution merged it
+   *  away, so following it is always safe. */
+  customerId: string;
+  /** True when the store token belongs to a different customer than the
+   *  caller: the purchase was recorded against them, not you. Safe for every
+   *  caller — it reports the outcome without naming anyone. */
+  ownedByOtherCustomer?: boolean;
+  /** Which customer holds the token, when it is not you. Present only for
+   *  secret-key callers — a publishable key learns the outcome above but
+   *  never another customer's id. */
+  tokenOwner?: string;
+  /** True when the token was reassigned TO this caller. */
+  transferred: boolean;
+  /** Set when an identity side-effect (a transfer, or absorbing an imported
+   *  history) was refused because the claim carried no proof. Send
+   *  `signedTransactionInfo`, or register from your server with a secret
+   *  key. */
+  refused?: "unverified-claim";
+  /** True when this transaction was already in the ledger — a StoreKit
+   *  replay or restore, not a new sale. */
+  restored?: boolean;
+  /** True when the purchase was recorded without store proof: the entitlement
+   *  is live but time-boxed until the store confirms the charge. Send
+   *  `signedTransactionInfo` (iOS) to avoid it. */
+  provisional?: boolean;
+}
+
+// ——— GET /v1/customers/{id}/entitlements ———
+
+export interface EntitlementSource {
+  kind: "subscription" | "grant";
+  key: string;
+  isActive: boolean;
+  expiresAt?: number;
+}
+
+export interface Entitlement {
+  entitlementId: string;
+  isActive: boolean;
+  expiresAt?: number;
+  sources: EntitlementSource[];
+}
+
+export interface CustomerEntitlements {
+  customerId: string;
+  /** Ledger cursor this read reflects. */
+  cursor: number;
+  entitlements: Entitlement[];
+  /** C7 (SDK-populated): true when this was served from the local cache
+   *  because the live read failed (offline / incident) — a paying customer is
+   *  shown as subscribed from cache rather than as unsubscribed. false on a
+   *  fresh server read. */
+  stale?: boolean;
+  /** C7 (SDK-populated): unix ms these entitlements were fetched/cached. */
+  fetchedAt?: number;
+}
+
+// ——— POST /v1/identify · POST /v1/customers/{id}/alias ———
+
+export type IdentifyStrategy = "merge" | "block";
+
+export interface IdentifyResult {
+  canonicalId: string;
+  merged: boolean;
+}
+
+export interface AliasResult {
+  canonicalId: string;
+  aliased: boolean;
+}
+
+// ——— GET /v1/customers/{id}/identity ———
+
+export interface IdentityInfo {
+  canonicalId: string;
+  isAlias: boolean;
+  anonymous: boolean;
+  linkedIds?: string[];
+}
+
+export interface LastDeepLink {
+  url: string;
+  receivedAt: number;
+}
+
+// ——— GET /v1/placements/{key}/offering ———
+
+export interface PlacementPackage {
+  packageId: string;
+  productId: string;
+  metadata?: Record<string, unknown>;
+  product: PlacementProduct | null;
+}
+
+export interface PlacementProduct {
+  productId: string;
+  displayName: string;
+  entitlementIds: string[];
+  prices?: Array<{
+    store: Store | "stripe";
+    currency: string;
+    amountMinor: number;
+  }>;
+  metadata?: Record<string, unknown>;
+}
+
+export interface PlacementOffering {
+  offeringId: string;
+  displayName: string;
+  metadata?: Record<string, unknown>;
+  packages: PlacementPackage[];
+}
+
+// REV-028: remote paywall design attached to a placement. Render contract —
+// the app draws this with its own components; prices still come from the
+// store (StoreKit / Play Billing) so the display never disagrees with the
+// charge.
+export interface PaywallConfig {
+  /** Layout — the screen structure RevnixPaywall renders. The dashboard's
+   *  template gallery is presets over these layouts; the first three are the
+   *  original templates and render exactly as before. */
+  template:
+    | "focus"
+    | "feature-list"
+    | "minimal"
+    | "hero"
+    | "timeline"
+    | "plans"
+    | "feature-grid"
+    | "offer"
+    | "reveal";
+  /** Color scheme the paywall renders in. Absent (legacy config) = dark.
+   *  The host app's explicit `theme` prop still overrides either scheme. */
+  mode?: "dark" | "light";
+  headline: string;
+  subheadline?: string;
+  features: Array<{ icon?: string; title: string; description?: string }>;
+  ctaLabel: string;
+  /** packageId of the visually highlighted package. */
+  highlightPackageId?: string;
+  /** Badge on the highlighted package, e.g. "SAVE 17%". */
+  badgeText?: string;
+  /** Accent hex like "#6478ff"; fall back to the app theme when absent. */
+  accent?: string;
+  /** Hero image URL rendered above the headline in place of the icon tile. */
+  heroImageUrl?: string;
+  /** Social proof, dashboard-configured. Any layout renders the pieces that
+   *  are set: stars/quote card above the packages, `count` under the CTA. */
+  review?: {
+    /** 0–5; rendered as a star row. */
+    rating?: number;
+    quote?: string;
+    author?: string;
+    /** e.g. "Join 2M+ users" — small line under the CTA. */
+    count?: string;
+  };
+  /** Win-back/offer presentation: anchor price struck through on the
+   *  highlighted package, urgency line above the CTA. Any layout. */
+  offer?: {
+    strikethroughPrice?: string;
+    urgencyText?: string;
+  };
+  /** Footer links, dashboard-configured. Absent (legacy config) = show all
+   *  three. When a URL is set the SDK opens it directly; otherwise the host
+   *  app's onTerms/onPrivacy handler runs. */
+  footer?: {
+    showRestore: boolean;
+    showTerms: boolean;
+    showPrivacy: boolean;
+    termsUrl?: string;
+    privacyUrl?: string;
+  };
+  /** A designed paywall: the block tree the dashboard's builder authored.
+   *  When present RevnixPaywall renders THIS and the fields above act as the
+   *  fallback for clients that predate block rendering — so an older app
+   *  keeps showing a sane classic screen instead of nothing. Typed as the
+   *  block document in "revnix-react/ui"; the core entrypoint keeps it opaque
+   *  so non-UI consumers pull in no renderer types. */
+  blocks?: unknown;
+}
+
+export interface PlacementPaywall {
+  paywallId: string;
+  name: string;
+  config: PaywallConfig;
+}
+
+export interface PlacementResolution {
+  status: "ok";
+  placementKey: string;
+  revision: number;
+  placementMetadata?: Record<string, unknown>;
+  offering: PlacementOffering | null;
+  paywall: PlacementPaywall | null;
+  /** REV-219: the A/B test serving this resolution — set when the customer
+   *  is enrolled in an experiment on this placement (the offering/paywall
+   *  above are the assigned variant's). Null when no experiment applies.
+   *  Assignment is sticky per customer, survives identity merges, and the
+   *  enrollment is recorded as an `experiment.enrolled` ledger event. */
+  experiment: { key: string; variantId: string } | null;
+  /** REV-157 (SDK-populated): true when this was served from the local cache
+   *  because the live read failed (offline / incident) — the paywall renders
+   *  the last published resolution rather than not at all. false on a fresh
+   *  server read. */
+  stale?: boolean;
+  /** REV-157 (SDK-populated): unix ms this resolution was fetched/cached. */
+  fetchedAt?: number;
+  /** Set only on a dashboard preview resolution, never on a real resolve. */
+  preview?: true;
+}
+
+/** REV-263: the six paywall interactions `logPaywallEvent` can report — what
+ *  the customer did on a display, between the view that opened it and the
+ *  close or purchase that ended it. The server turns each into the ledger
+ *  type `paywall.<name>`. */
+export type PaywallInteraction =
+  | "selected"
+  | "purchase_started"
+  | "purchase_abandoned"
+  | "purchase_failed"
+  | "restore"
+  | "error";
+
+/** What the host tells RevnixPaywall about a purchase it performed (REV-263).
+ *  Returning it from `onPurchase` is what lets the paywall report
+ *  `purchase_abandoned` / `purchase_failed` itself — without it the SDK sees
+ *  only that checkout STARTED, because the store call happens in the host.
+ *
+ *  `completed` needs no report of its own: the purchase lands as
+ *  `purchase.completed` through registerPurchase. */
+export interface PaywallPurchaseOutcome {
+  status: "completed" | "cancelled" | "failed";
+  /** Store error code — a StoreKit `SKError` code, a Play
+   *  `BillingResponseCode`, or whatever your layer calls it. */
+  code?: string;
+  message?: string;
+}
+
+/** Input for `logAdRevenue` — one ad impression's payout. */
+export interface AdRevenue {
+  /** Major units, e.g. 0.0032. Must be > 0. */
+  revenue: number;
+  /** ISO 4217, e.g. "USD". */
+  currency: string;
+  /** Monetization network that paid, e.g. "admob". */
+  network?: string;
+  /** Mediation platform that reported it, e.g. "applovin_max". */
+  mediation?: string;
+  adUnit?: string;
+  placement?: string;
+  /** "banner" | "interstitial" | "rewarded" | … free text. */
+  format?: string;
+  /** Idempotency key for this impression; omit to let the server generate one. */
+  eventId?: string;
+}
+
+/** MMP that produced an attribution callback. */
+export type MmpProvider =
+  | "adjust"
+  | "appsflyer"
+  | "singular"
+  | "branch"
+  | "kochava"
+  | "tenjin"
+  | "airbridge";
+
+/** Input for `setAttribution` — the network/campaign an MMP's attribution
+ *  callback (Adjust, AppsFlyer, …) resolved for this install. */
+export interface MmpAttribution {
+  provider: MmpProvider;
+  network: string;
+  campaign?: string;
+  adGroup?: string;
+  creative?: string;
+}