react-native-revnix 1.4.0

package/dist/ui/RevnixPaywall.d.ts

@@ -0,0 +1,148 @@
+import * as React from "react";
+import { type StyleProp, type ViewStyle } from "react-native";
+import type { PaywallConfig, PaywallInteraction, PaywallPurchaseOutcome } from "../types.js";
+import type { FontFamilyMap } from "../blocks/style.js";
+import { type RevnixBlurComponent, type RevnixGradientComponent } from "./RevnixBlockPaywall.js";
+/** One purchasable row. `priceLabel` must come from the store (localized). */
+export interface RevnixPaywallPackage {
+    packageId: string;
+    title: string;
+    priceLabel: string;
+    /** Renewal cycle ("monthly", "annual", …) from the catalog product. Only
+     *  designed (block) paywalls read it, to resolve the {period},
+     *  {period_short}, {price_per_month} and {save_percent} tags — a tag with
+     *  no cycle behind it renders as written rather than guessed. */
+    period?: string;
+    /** Price in minor units, for the same per-month and saving maths. */
+    amountMinor?: number;
+    /** ISO currency of `amountMinor`. */
+    currency?: string;
+    /** REV-263: the catalog product behind this package. Only telemetry reads
+     *  it — a `selected` or `purchase_started` report names the plan the way
+     *  the rest of the ledger does. Optional: without it the interaction is
+     *  still reported, just with no plan attached (the package id would be
+     *  worse — it would look like a product that does not exist). */
+    productId?: string;
+}
+/** Colors the paywall renders with. Defaults mirror the dashboard preview
+ *  chrome (a fixed dark screen) — override to match the host app's theme. */
+export interface RevnixPaywallTheme {
+    background: string;
+    textPrimary: string;
+    textSecondary: string;
+    textFaint: string;
+    border: string;
+    /** Text color on accent-filled surfaces (CTA, badge). */
+    accentInk: string;
+}
+export declare const DEFAULT_PAYWALL_THEME: RevnixPaywallTheme;
+/** Base theme when the dashboard config sets `mode: "light"`. Keep in
+ *  lockstep with the builder preview (PaywallPhonePreview SCREEN_PALETTES). */
+export declare const LIGHT_PAYWALL_THEME: RevnixPaywallTheme;
+export interface RevnixPaywallProps {
+    config: PaywallConfig;
+    packages: RevnixPaywallPackage[];
+    /** Called with the selected packageId when the CTA is pressed.
+     *
+     *  REV-263: passing `client` reports `paywall.purchase_started` the moment
+     *  this fires. The OUTCOME is yours — only the host performs the store
+     *  call — so to have the paywall report it too, return it (or a promise of
+     *  it): `cancelled` becomes `paywall.purchase_abandoned`, `failed` becomes
+     *  `paywall.purchase_failed`, and a promise that REJECTS is reported as a
+     *  failure carrying the error's message. Returning nothing keeps today's
+     *  behavior exactly — the start is reported, the outcome is not, and you
+     *  can still report it yourself with `client.logPaywallEvent`. */
+    onPurchase: (packageId: string) => void | PaywallPurchaseOutcome | Promise<PaywallPurchaseOutcome | void>;
+    /** Controlled selection; omit to let the paywall manage it (initial
+     *  selection is the config's highlight package, else the first package). */
+    selectedPackageId?: string;
+    onSelectPackage?: (packageId: string) => void;
+    /** Renders a spinner in the CTA and disables purchasing. */
+    loading?: boolean;
+    onRestore?: () => void;
+    onTerms?: () => void;
+    onPrivacy?: () => void;
+    /** Called when the customer dismisses the paywall (REV-252) — either by
+     *  tapping an element the design marks as the close, or by the close button
+     *  the renderer supplies when the design authors none.
+     *
+     *  Dismissal is the HOST's to perform: the paywall does not unmount itself,
+     *  because only the host knows whether that means popping a screen, closing
+     *  a modal, or advancing onboarding. Omit it and no close is drawn at all —
+     *  a paywall with a dead close button is worse than one without.
+     *
+     *  Passing `client` as well reports `paywall.closed` against this display's
+     *  own view id, so the close pairs with its paywall.viewed. */
+    onClose?: () => void;
+    theme?: Partial<RevnixPaywallTheme>;
+    style?: StyleProp<ViewStyle>;
+    /** When given, the paywall reports one paywall.viewed per mount (REV-094)
+     *  — the analytics funnel's "Paywall displayed" stage. Structural typing
+     *  keeps this entrypoint free of a hard client import. */
+    client?: {
+        logPaywallShown: (options?: {
+            placementKey?: string;
+            paywallId?: string;
+        }) => string | void;
+        /** Older clients predate close reporting; the paywall still closes. */
+        logPaywallClosed?: (viewId: string, options?: {
+            placementKey?: string;
+            paywallId?: string;
+        }) => void;
+        /** Where a designed paywall reports a paint string it could not read.
+         *  Optional for the same reason: a client that predates it still renders,
+         *  it just reports nothing. */
+        reportRenderDiagnostic?: (message: string) => void;
+        /** REV-263: the interaction vocabulary. Optional so a host on an older
+         *  client still renders and still reports views — it just reports none of
+         *  the six. */
+        logPaywallEvent?: (event: PaywallInteraction, viewId: string, options?: {
+            placementKey?: string;
+            paywallId?: string;
+            productId?: string;
+            code?: string;
+            message?: string;
+            eventId?: string;
+        }) => void;
+    };
+    /** Placement/paywall attribution attached to the view report. */
+    placementKey?: string;
+    paywallId?: string;
+    /** Opt out of the automatic view report while still passing `client`. */
+    disableViewTracking?: boolean;
+    /** Renders the CSS gradients a designed (block) paywall may use. Pass the
+     *  app's own `LinearGradient` (expo-linear-gradient or
+     *  react-native-linear-gradient). Without it a gradient paints as the
+     *  design's ground color. Ignored by the classic layouts. */
+    gradient?: RevnixGradientComponent;
+    /** Renders a blurred background photo on a designed paywall. RN has no
+     *  blur primitive, so pass the app's own (`expo-blur`'s `BlurView`, or
+     *  `@react-native-community/blur`). Without it a blurred background photo
+     *  renders sharp. Ignored by the classic layouts. */
+    blur?: RevnixBlurComponent;
+    /** Design font family → the face(s) the app has registered, for designed
+     *  paywalls. Either one family for every weight, or a weight → family table.
+     *  RN cannot load a font by name at runtime, so an unmapped face renders in
+     *  the system font. */
+    fontFamilyMap?: FontFamilyMap;
+    /** Reports a paint string the designed renderer could not read, or a
+     *  gradient it flattened for want of a `gradient` component.
+     *
+     *  Local only: nothing is sent anywhere. Passing `client` routes the same
+     *  reports to that client's own `onDiagnostic`, so most apps need neither —
+     *  this is for a host that renders a paywall without a client. */
+    onDiagnostic?: (message: string) => void;
+    /** REV-271: which language to draw a DESIGNED paywall's copy in. Omitted,
+     *  the device's own is detected — which is what makes the paywall match the
+     *  rest of the app on a phone with no in-app language switch. Pass one when
+     *  the app HAS such a switch, so the paywall follows the app rather than the
+     *  OS: a user reading the app in Spanish on an English phone must not be
+     *  handed an English paywall. A paywall with no translations ignores this,
+     *  and any string the chosen language does not translate falls back to the
+     *  authored copy rather than rendering blank.
+     *
+     *  Only designed (block) paywalls are localized; the classic template
+     *  layouts below render `config`'s own copy whatever this says. */
+    locale?: string;
+}
+export declare function RevnixPaywall(props: RevnixPaywallProps): React.JSX.Element;