react-native-revnix 1.7.0 → 1.9.0

package/src/blocks/types.ts

@@ -135,13 +135,15 @@ export interface BlockStyle {
  *  one. Ignored outside a package card — a root block is always drawn. */
 export type BlockVisibility = "selected" | "unselected";
 
-export type BlockAction = "close";
+/** `close` dismisses the paywall; `next`/`back` move between onboarding
+ *  screens and only appear inside `screens`. */
+export type BlockAction = "close" | "next" | "back";
 
 export interface TextBlock {
   id: string;
   type: "text";
   text: string;
-  /** Tapping this block dismisses the paywall. See BlockAction. */
+  /** What tapping this block does. See BlockAction. */
   action?: BlockAction;
   style?: BlockStyle;
   /** REV-262: merged over `style`, field by field, while the block sits in a
@@ -159,7 +161,7 @@ export interface ImageBlock {
   shape?: "rect" | "circle";
   fit?: "cover" | "contain";
   placeholder?: string;
-  /** Tapping this block dismisses the paywall. See BlockAction. */
+  /** What tapping this block does. See BlockAction. */
   action?: BlockAction;
   style?: BlockStyle;
   /** REV-262: merged over `style`, field by field, while the block sits in a
@@ -206,8 +208,9 @@ export interface ButtonBlock {
   id: string;
   type: "button";
   label: string;
-  /** `close` turns this button into a dismiss ("Not now") instead of the
-   *  purchase CTA, which is what a button means by default. */
+  /** `close` turns this button into a dismiss ("Not now"), and `next`/`back`
+   *  into onboarding navigation, instead of the purchase CTA, which is what a
+   *  button means by default. */
   action?: BlockAction;
   style?: BlockStyle;
   /** REV-262: merged over `style`, field by field, while the block sits in a
@@ -356,6 +359,10 @@ export interface PaywallBlockDoc {
   accentInk: string;
   fontFamily?: string;
   blocks: PaywallBlock[];
+  /** Onboarding: intro screens shown in order before `blocks`, which stays
+   *  the last (purchase) screen. They share the doc's palette, layout and
+   *  locale table. Absent or empty = `blocks` alone. */
+  screens?: PaywallBlock[][];
   /** REV-271: the language the blocks' own copy is written in. Absent = "en".
    *  Never a key in a stored doc's `locales` — the tree IS that language's
    *  version. A localized copy names the language it was localized to. */
@@ -399,3 +406,26 @@ export function hasCloseAction(blocks: PaywallBlock[]): boolean {
           b.action === "close"
   );
 }
+
+export function onboardingScreen(
+  doc: PaywallBlockDoc,
+  index: number
+): { blocks: PaywallBlock[]; dots?: { count: number; active: number } } {
+  const intro = doc.screens?.[index];
+  if (intro === undefined) return { blocks: doc.blocks };
+  return {
+    blocks: intro,
+    dots: { count: doc.screens!.length + 1, active: index },
+  };
+}
+
+export function stepScreen(
+  doc: PaywallBlockDoc,
+  index: number,
+  action: BlockAction | undefined
+): number | undefined {
+  if (index >= (doc.screens?.length ?? 0)) return undefined;
+  if (action === "next") return index + 1;
+  if (action === "back" && index > 0) return index - 1;
+  return undefined;
+}

package/src/client.ts

@@ -1,4 +1,5 @@
 import {
+  PurchaseAlreadyOwnedError,
   PurchaseBlockedError,
   RevnixAuthError,
   RevnixError,
@@ -193,6 +194,33 @@ const pendingKey = (p: RegisterPurchaseInput) =>
 const worthQueueing = (err: unknown): boolean =>
   !(err instanceof RevnixError) || err.isRetryable;
 
+const ATTRIBUTION_QUERY_PARAMS = new Set([
+  "utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content", "utm_id", "campaign_id",
+  "pid", "source", "af_channel", "medium", "c", "campaign", "term", "af_ad",
+  "content", "gclid", "gbraid", "wbraid", "ttclid", "sccid", "twclid",
+  "revnix_link", "web_id",
+]);
+
+function queryParamName(pair: string): string {
+  const raw = pair.split("=")[0] ?? "";
+  try {
+    return decodeURIComponent(raw.replace(/\+/g, " ")).toLowerCase();
+  } catch {
+    return raw.toLowerCase();
+  }
+}
+
+function attributionOnlyUrl(rawUrl: string): string {
+  const url = rawUrl.trim();
+  const parts = /^([a-z][a-z0-9+.-]*:)(\/\/[^/?#]*)?([^?#]*)(?:\?([^#]*))?/i.exec(url);
+  if (!parts) return url.split(/[?#]/)[0] ?? "";
+  const [, scheme, authority = "", path, query = ""] = parts;
+  const kept = query
+    .split("&")
+    .filter((pair) => ATTRIBUTION_QUERY_PARAMS.has(queryParamName(pair)));
+  return `${scheme}${authority.replace(/^\/\/.*@/, "//")}${path}${kept.length > 0 ? `?${kept.join("&")}` : ""}`;
+}
+
 const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
 
 // REV-199 (CTO-R2 M24): ±20% on every scheduled delay.
@@ -263,6 +291,7 @@ export class RevnixClient {
   private readonly onDeferredDeepLink?: RevnixConfig["onDeferredDeepLink"];
   private readonly onAttribution?: RevnixConfig["onAttribution"];
   private readonly deviceIntegrity?: RevnixConfig["deviceIntegrity"];
+  private readonly consumableProductIds: string[];
   private integrityRequest: {
     customerId: string;
     body: Promise<{ integrity?: IntegrityEvidence }>;
@@ -340,6 +369,7 @@ export class RevnixClient {
     this.onDeferredDeepLink = config.onDeferredDeepLink;
     this.onAttribution = config.onAttribution;
     this.deviceIntegrity = config.deviceIntegrity;
+    this.consumableProductIds = config.consumableProductIds ?? [];
     this.readYourWritesDelaysMs =
       config.readYourWritesDelaysMs ?? [250, 500, 1000, 2000];
     this.customerIdPromise = this.loadCustomerId(config.customerId);
@@ -351,11 +381,12 @@ export class RevnixClient {
     if (config.advertisingId) this.reportAdvertisingId(config.advertisingId);
     const store = getStoreAdapter();
     if (store) {
-      this.stopStoreObserver = store.observe((tx) =>
+      this.stopStoreObserver = store.observe((tx) => {
+        if (tx.acknowledged && !this.isConsumable(tx)) return;
         void this.registerStoreTransaction(store, tx).catch((err) =>
           this.diag("storeObserver", err)
-        )
-      );
+        );
+      });
     }
     // REV-157: warm the placement cache at launch, so the first paywall of the
     // session can render offline. Fire-and-forget; a failed key just stays on
@@ -547,6 +578,12 @@ export class RevnixClient {
     const customerId = await this.customerIdPromise;
     const tx = await store.purchase(productId, { customerId });
     if (!tx) return null;
+    if (tx.alreadyOwned && this.isConsumable(tx)) {
+      await this.registerStoreTransaction(store, tx, opts);
+      throw new PurchaseAlreadyOwnedError(
+        `Revnix: an earlier purchase of ${productId} was still owned and has been registered; buy again`
+      );
+    }
     return this.registerStoreTransaction(store, tx, opts);
   }
 
@@ -566,6 +603,10 @@ export class RevnixClient {
     return restored;
   }
 
+  private isConsumable(tx: StoreTransaction): boolean {
+    return tx.store === "google" && this.consumableProductIds.includes(tx.productId);
+  }
+
   private requireStore(): StoreAdapter {
     const store = getStoreAdapter();
     if (!store) {
@@ -582,9 +623,9 @@ export class RevnixClient {
     opts?: Pick<RegisterPurchaseInput, "viewId" | "paywallId" | "placementKey">,
     finish = true
   ): Promise<RegisterPurchaseResult> {
-    const finishTx = () =>
+    const finishTx = (consume = false) =>
       finish
-        ? store.finish(tx.transactionId).catch((err) => this.diag("storeFinish", err))
+        ? store.finish(tx.transactionId, consume).catch((err) => this.diag("storeFinish", err))
         : undefined;
     try {
       const result = await this.registerPurchase({
@@ -597,7 +638,7 @@ export class RevnixClient {
         signedTransactionInfo: tx.signedTransactionInfo,
         ...opts,
       });
-      await finishTx();
+      await finishTx(this.isConsumable(tx));
       return result;
     } catch (err) {
       if (!(err instanceof PurchaseBlockedError)) await finishTx();
@@ -1400,7 +1441,7 @@ export class RevnixClient {
       return;
     }
     void this.rememberDeepLink(url);
-    const extra = { url: url.slice(0, 1024) };
+    const extra = { url: attributionOnlyUrl(url).slice(0, 1024) };
     const batch = this.launchBatch;
     if (batch === null) {
       this.fireImplicit("deeplink_open", extra);

package/src/errors.ts

@@ -24,6 +24,16 @@ export class PurchaseBlockedError extends RevnixError {
   }
 }
 
+/** purchase() found an earlier Google Play consumable of this product still
+ *  owned. It was registered and consumed instead of charging again; ask the
+ *  customer to buy again. */
+export class PurchaseAlreadyOwnedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "PurchaseAlreadyOwnedError";
+  }
+}
+
 /** C7: the request didn't complete within the configured timeout (default
  *  10s). `fetch` has no default timeout on React Native / browsers, so without
  *  this a slow or dead backend would hang the app until the OS TCP timeout. */

package/src/index.ts

@@ -4,6 +4,7 @@ import type { RevnixConfig } from "./types.js";
 
 export { RevnixClient } from "./client.js";
 export {
+  PurchaseAlreadyOwnedError,
   PurchaseBlockedError,
   RevnixAuthError,
   RevnixError,

package/src/store/index.ts

@@ -10,7 +10,7 @@ import type { IntegrityEvidence, RevnixConfig } from "../types.js";
 interface NativeRevnixStore {
   purchase(productId: string, customerId: string): Promise<StoreTransaction | null>;
   restore(): Promise<StoreTransaction[]>;
-  finish(transactionId: string): Promise<void>;
+  finish(transactionId: string, consume: boolean): Promise<void>;
   deviceIntegrity?(customerId: string): Promise<IntegrityEvidence | null>;
   advertisingId?(): Promise<string | null>;
 }
@@ -28,7 +28,7 @@ export const RevnixStore: StoreAdapter = native
   ? {
       purchase: (productId, { customerId }) => native.purchase(productId, customerId),
       restore: () => native.restore(),
-      finish: (transactionId) => native.finish(transactionId),
+      finish: (transactionId, consume) => native.finish(transactionId, consume === true),
       observe(onTransaction) {
         const sub = new NativeEventEmitter(NativeModules.RevnixStore).addListener(
           "revnixStoreTransaction",

package/src/store.ts

@@ -13,6 +13,11 @@ export interface StoreTransaction {
   expiresAt?: number;
   /** Apple only: the StoreKit 2 JWS. */
   signedTransactionInfo?: string;
+  /** Google only: already acknowledged in Play. */
+  acknowledged?: boolean;
+  /** Google only: purchase() answered with an earlier purchase Play reported
+   *  as already owned, not a new charge. */
+  alreadyOwned?: boolean;
 }
 
 export interface StoreAdapter {
@@ -22,7 +27,8 @@ export interface StoreAdapter {
     opts: { customerId: string }
   ): Promise<StoreTransaction | null>;
   restore(): Promise<StoreTransaction[]>;
-  finish(transactionId: string): Promise<void>;
+  /** `consume`: Google only, consume instead of acknowledge. */
+  finish(transactionId: string, consume?: boolean): Promise<void>;
   /** Transactions arriving outside purchase(): renewals, other devices, Ask
    *  to Buy, refunds. Returns an unsubscribe. */
   observe(onTransaction: (tx: StoreTransaction) => void): () => void;

package/src/types.ts

@@ -161,6 +161,9 @@ export interface RevnixConfig {
    *  read. A null answer deletes a previously stored `gps_adid`; a
    *  rejection changes nothing and reports `op: "advertisingId"`. */
   advertisingId?: () => Promise<string | null | undefined>;
+  /** Google Play product ids sold as consumables. A registered purchase of
+   *  one is consumed instead of acknowledged so it can be bought again. */
+  consumableProductIds?: string[];
 }
 
 /** Device integrity evidence for `POST /v1/installs` and `/v1/attribution`.

package/src/ui/RevnixBlockPaywall.tsx

@@ -74,6 +74,9 @@ import type { SelectionContext } from "../blocks/selection.js";
 import {
   DESIGN_CANVAS,
   hasCloseAction,
+  onboardingScreen,
+  stepScreen,
+  type BlockAction,
   type BlockStyle,
   type PaywallBlock,
   type PaywallBlockDoc,
@@ -600,6 +603,7 @@ interface RenderContext {
   onTerms?: () => void;
   onPrivacy?: () => void;
   onClose?: () => void;
+  navigate: (action: BlockAction | undefined) => (() => void) | undefined;
   footer?: { termsUrl?: string; privacyUrl?: string };
   heroImageUrl?: string;
   gradient?: RevnixGradientComponent;
@@ -622,13 +626,14 @@ function BlockText({
   ctx,
   inherited,
   onPress,
+  pressLabel,
 }: {
   text: string;
   style: BlockStyle | undefined;
   ctx: RenderContext;
   inherited: InheritedText;
-  /** Set when the design marks this element as the close (REV-252). */
   onPress?: () => void;
+  pressLabel?: string;
 }) {
   const styleCtx = { ...ctx.style, fontSize: inherited.fontSize };
   // The block's own typography is folded into the inherited set first, so
@@ -661,7 +666,7 @@ function BlockText({
     return (
       <Pressable
         accessibilityRole="button"
-        accessibilityLabel="Close"
+        accessibilityLabel={pressLabel}
         hitSlop={8}
         onPress={onPress}
         style={toViewStyle(style, styleCtx)}
@@ -745,46 +750,67 @@ function Carousel({
         ))}
       </ScrollView>
       {pages.length > 1 ? (
+        <Dots count={pages.length} active={page} doc={doc} style={{ bottom: 8 }} />
+      ) : null}
+    </View>
+  );
+}
+
+function Dots({
+  count,
+  active,
+  doc,
+  style,
+}: {
+  count: number;
+  active: number;
+  doc: PaywallBlockDoc;
+  style: ViewStyle;
+}) {
+  return (
+    <View
+      pointerEvents="none"
+      style={[
+        {
+          position: "absolute",
+          left: 0,
+          right: 0,
+          flexDirection: "row",
+          justifyContent: "center",
+          gap: 6,
+        },
+        style,
+      ]}
+    >
+      {Array.from({ length: count }, (_, i) => (
         <View
-          pointerEvents="none"
+          key={i}
           style={{
-            position: "absolute",
-            bottom: 8,
-            left: 0,
-            right: 0,
-            flexDirection: "row",
-            justifyContent: "center",
-            gap: 6,
+            width: 6,
+            height: 6,
+            borderRadius: 3,
+            backgroundColor:
+              i === active ? doc.accent : withAlpha(doc.textColor, 0.3),
           }}
-        >
-          {pages.map((_, i) => (
-            <View
-              key={i}
-              style={{
-                width: 6,
-                height: 6,
-                borderRadius: 3,
-                backgroundColor:
-                  i === page ? doc.accent : withAlpha(doc.textColor, 0.3),
-              }}
-            />
-          ))}
-        </View>
-      ) : null}
+        />
+      ))}
     </View>
   );
 }
 
-/** The press handler for a block the design marks as the close, or undefined
- *  when it is not one (or the host wired no dismissal). One helper so text,
- *  image and button blocks cannot drift on what "action: close" means. */
-function closePress(
-  block: { action?: "close" },
+function actionPress(
+  block: { action?: BlockAction },
   ctx: RenderContext
 ): (() => void) | undefined {
-  return block.action === "close" && ctx.onClose ? ctx.onClose : undefined;
+  return block.action === "close" ? ctx.onClose : ctx.navigate(block.action);
 }
 
+const ACTION_LABEL: Record<BlockAction, string> = {
+  close: "Close",
+  next: "Next",
+  back: "Back",
+};
+
 /** Typography that is NOT inherited (decoration) — everything else already
  *  arrives through the inherited set. */
 function textOnly(s: BlockStyle | undefined, ctx: StyleContext) {
@@ -983,7 +1009,8 @@ function Block({
           style={style}
           ctx={ctx}
           inherited={inherited}
-          onPress={closePress(block, ctx)}
+          onPress={actionPress(block, ctx)}
+          pressLabel={block.action === "close" ? "Close" : undefined}
         />
       );
 
@@ -1039,17 +1066,17 @@ function Block({
           s.aspectRatio !== undefined ||
           (s.top !== undefined && s.bottom !== undefined) ||
           s.flex !== undefined);
-      // An icon the design marks as the close (REV-252). Same rule as text:
-      // the whole box is the target, and the style lands on the Pressable so
-      // a pinned icon keeps its offsets.
-      const closeImage = image ? closePress(block, ctx) : undefined;
-      const ImageBox = closeImage ? Pressable : View;
+      const action = block.type === "image" ? block.action : undefined;
+      const imagePress = actionPress({ action }, ctx);
+      const ImageBox = imagePress ? Pressable : View;
       return (
         <ImageBox
-          accessibilityRole={closeImage ? "button" : undefined}
-          accessibilityLabel={closeImage ? "Close" : undefined}
-          hitSlop={closeImage ? 8 : undefined}
-          onPress={closeImage}
+          accessibilityRole={imagePress ? "button" : undefined}
+          accessibilityLabel={
+            imagePress && action ? ACTION_LABEL[action] : undefined
+          }
+          hitSlop={imagePress ? 8 : undefined}
+          onPress={imagePress}
           style={[
             sized ? null : { height: 160 },
             { borderRadius: round ? 9999 : sized ? 0 : 16, overflow: "hidden", flexShrink: 0 },
@@ -1130,17 +1157,18 @@ function Block({
       // A button the design marks as the close dismisses instead of buying,
       // and takes no accent fill: the CTA must stay the one accented thing on
       // the screen, or a "Not now" competes with "Subscribe" for the eye.
-      const close = closePress(block, ctx);
+      const close = block.action === "close" ? ctx.onClose : undefined;
+      const navigates = block.action === "next" || block.action === "back";
       // A purchase in flight: the button keeps its box and fill, loses its
       // label to a spinner in the ink colour, and ignores taps. A close
       // button is never blocked — the user can always leave.
-      const busy = !close && ctx.loading;
+      const busy = !close && !navigates && ctx.loading;
       return (
         <Pressable
           accessibilityRole="button"
           accessibilityState={{ disabled: busy, busy }}
           disabled={busy}
-          onPress={close ?? ctx.onPurchase}
+          onPress={navigates ? actionPress(block, ctx) : (close ?? ctx.onPurchase)}
           style={({ pressed }) => [
             {
               backgroundColor: close ? "transparent" : doc.accent,
@@ -1408,6 +1436,13 @@ export function RevnixBlockPaywall(props: RevnixBlockPaywallProps) {
     string | undefined
   >(undefined);
   const [shownAt] = React.useState(Date.now);
+  const [screenIndex, setScreenIndex] = React.useState(0);
+  const [screenDoc, setScreenDoc] = React.useState(props.doc);
+  if (screenDoc !== props.doc) {
+    setScreenDoc(props.doc);
+    setScreenIndex(0);
+  }
+  const screen = onboardingScreen(doc, screenIndex);
   // Contract §1: host → own tap → design highlight → first package, each
   // only when the offering carries it.
   const selectedId = selectedPackageId(
@@ -1451,6 +1486,10 @@ export function RevnixBlockPaywall(props: RevnixBlockPaywallProps) {
     onTerms: props.onTerms,
     onPrivacy: props.onPrivacy,
     onClose: props.onClose,
+    navigate: (action) => {
+      const to = stepScreen(doc, screenIndex, action);
+      return to === undefined ? undefined : () => setScreenIndex(to);
+    },
     footer: props.footer,
     heroImageUrl: props.heroImageUrl,
     gradient: props.gradient,
@@ -1460,7 +1499,7 @@ export function RevnixBlockPaywall(props: RevnixBlockPaywallProps) {
     shownAt,
   };
 
-  const children = doc.blocks.map((block) => (
+  const children = screen.blocks.map((block) => (
     <Block
       key={block.id}
       block={block}
@@ -1478,7 +1517,7 @@ export function RevnixBlockPaywall(props: RevnixBlockPaywallProps) {
     props.safeAreaTop ??
     (Platform.OS === "android" ? (StatusBar.currentHeight ?? 0) : 0);
   const fallbackClose =
-    props.onClose && !hasCloseAction(doc.blocks) ? (
+    props.onClose && !hasCloseAction(screen.blocks) ? (
       <FallbackClose
         doc={doc}
         onPress={props.onClose}
@@ -1518,6 +1557,7 @@ export function RevnixBlockPaywall(props: RevnixBlockPaywallProps) {
         style={[{ flex: 1 }, props.style]}
       >
         <ScrollView
+          key={screenIndex}
           contentContainerStyle={{ height: canvasHeight }}
           // A designed screen never shows a scrollbar — the web preview has
           // none, and in an RTL app the indicator lands on the left edge of
@@ -1554,6 +1594,14 @@ export function RevnixBlockPaywall(props: RevnixBlockPaywallProps) {
               }}
             >
               {children}
+              {screen.dots ? (
+                <Dots
+                  count={screen.dots.count}
+                  active={screen.dots.active}
+                  doc={doc}
+                  style={{ top: 20, zIndex: 50 }}
+                />
+              ) : null}
             </View>
           </View>
         </ScrollView>
@@ -1571,6 +1619,7 @@ export function RevnixBlockPaywall(props: RevnixBlockPaywallProps) {
       style={[{ flex: 1 }, props.style]}
     >
       <ScrollView
+        key={screenIndex}
         contentContainerStyle={{
           gap: 12,
           paddingHorizontal: 20,
@@ -1583,6 +1632,14 @@ export function RevnixBlockPaywall(props: RevnixBlockPaywallProps) {
       >
         {children}
       </ScrollView>
+      {screen.dots ? (
+        <Dots
+          count={screen.dots.count}
+          active={screen.dots.active}
+          doc={doc}
+          style={{ top: 20 + safeAreaTop, zIndex: 50 }}
+        />
+      ) : null}
       {fallbackClose}
     </ScreenBackground>
   );

package/src/ui/RevnixPaywall.tsx

@@ -65,7 +65,16 @@ function asBlockDoc(value: unknown): PaywallBlockDoc | null {
     typeof doc.textColor === "string" &&
     typeof doc.accent === "string" &&
     typeof doc.accentInk === "string"
-    ? (doc as PaywallBlockDoc)
+    ? {
+        ...(doc as PaywallBlockDoc),
+        ...(doc.screens !== undefined
+          ? {
+              screens: Array.isArray(doc.screens)
+                ? doc.screens.filter((s) => Array.isArray(s) && s.length > 0)
+                : [],
+            }
+          : {}),
+      }
     : null;
 }
 
@@ -480,7 +489,7 @@ export function RevnixPaywall(props: RevnixPaywallProps) {
   // arrives after a placeholder (or is swapped by an A/B assignment) would
   // otherwise crash on "rendered more hooks than during the previous render".
   const { config } = props;
-  const blocks = asBlockDoc(config.blocks);
+  const blocks = React.useMemo(() => asBlockDoc(config.blocks), [config.blocks]);
   // Both sinks fire when both are wired; nil when neither is, which is what
   // stops the renderer building a message nobody will read.
   const renderDiagnostic =

package/src/version.ts

@@ -1,4 +1,4 @@
 // L3: the single source of the SDK version inside src/. Must match
 // package.json "version" — version.test.ts fails the build when they drift
 // (they had: client.ts said 0.7.0 while the package shipped 0.9.0).
-export const SDK_VERSION = "1.7.0";
+export const SDK_VERSION = "1.9.0";