@mrrocket/sdk 0.4.0 → 0.8.0

package/dist/react-native/index.d.ts

@@ -1,19 +1,200 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
 
+/**
+ * The cancel flow, onboarding and in-app messages (SDK 0.7.0): what MRRocket's config and `GET /api/sdk/inapp` serve,
+ * and one controller that decides what shows when and records what the person did. No DOM and no React: the web
+ * renderer (flows-ui.ts, loaded only when something shows) and the React Native one (native/flows-view.ts) draw
+ * `view()` and call the actions.
+ *
+ * What it records, as normal events under the SDK's analytics consent (nothing with consent "off"):
+ * - `$cancel_flow` `{action: "shown" | "answered" | "offer" | "finished", run, version, …}`. MRRocket turns a
+ *   `finished` with `outcome: "saved"` into a save and with `outcome: "cancelled"` into a cancellation on the Churn page.
+ *   MRRocket never changes a subscription: an accepted offer goes to the app's `onSave`, a confirmed cancel to its
+ *   `onCancel`, and only after they succeed is the outcome recorded.
+ * - `$onboarding` `{flow, step?, action: "started" | "shown" | "completed" | "dismissed"}`.
+ * - `$inapp` `{message, journey, action: "shown" | "clicked" | "dismissed"}`; the journey moves the person on.
+ */
+
+type CancelOfferKind = "discount" | "pause" | "downgrade" | "contact";
+/** What one answer of the survey offers before the confirmation. An answer without one goes straight to it. */
+interface CancelOffer {
+    kind: CancelOfferKind;
+    headline: string;
+    /** Discount: percent off. */
+    percent?: number;
+    /** Discount: for how many months; pause: up to how many months. */
+    months?: number;
+    /** Downgrade: the plan to switch to, as MRRocket knows it from the payment provider. */
+    plan?: string;
+    planName?: string;
+}
+/** The product's live cancel flow (MRRocket › Churn › Cancel flow). */
+interface CancelFlowConfig {
+    /** Grows with every publish. */
+    version: number;
+    question: string;
+    /** The survey's answers, in order. */
+    reasons: {
+        id: string;
+        label: string;
+    }[];
+    /** The offer per answer id. */
+    offers: Record<string, CancelOffer>;
+    confirm: {
+        title: string;
+        body: string;
+        button: string;
+    };
+    /**
+     * Who gets the survey and the offers: business customers only. Anyone else (a consumer, or a customer the app does
+     * not say) gets the plain confirmation, with nothing in the way of cancelling (§ 312k BGB).
+     */
+    offersFor: "business";
+}
+type OnboardingStepKind = "tour" | "checklist" | "modal";
+interface OnboardingStep {
+    id: string;
+    kind: OnboardingStepKind;
+    title: string;
+    body?: string;
+    button?: string;
+    /** Tour steps: the element they point at, marked `data-ck-target="<target>"` in the app. Without it: a card. */
+    target?: string;
+    /** Checklist items: the event that ticks them (`track("<event>")`). Without it the person ticks it themselves. */
+    event?: string;
+}
+/** A live onboarding flow's in-app steps (MRRocket › Conversion › Onboarding); its emails go out from MRRocket. */
+interface OnboardingFlow {
+    id: string;
+    name: string;
+    /** When it starts: an event's words ("Signed up", "First export"), or "First launch" / "First visit". */
+    trigger: string;
+    steps: OnboardingStep[];
+}
+/** An in-app message a Lifecycle journey has for this person. */
+interface InAppMessage {
+    id: string;
+    journey?: string;
+    title: string;
+    body?: string;
+    button?: string;
+    /** Where the button goes (http(s) or a path of the app). */
+    url?: string;
+    style: "banner" | "modal";
+}
+interface CancelFlowResult {
+    /** "cancelled": confirmed; "saved": took the offer; "kept": closed the dialog without cancelling. */
+    outcome: "cancelled" | "saved" | "kept";
+    reason?: string;
+    reasonLabel?: string;
+    offer?: CancelOffer;
+    /** What the customer wrote on the confirmation, if anything. */
+    comment?: string;
+    /** This run's id, the same as in the events. */
+    run: string;
+}
+interface CancelFlowOptions {
+    /**
+     * "business" shows the survey and the offers; anything else (the default) only the plain confirmation, so a
+     * consumer can always cancel in one step (§ 312k BGB).
+     */
+    customer?: "business" | "consumer";
+    /** The customer's current price, to show what a discount costs (`{ amount: 29, currency: "EUR" }`). */
+    price?: {
+        amount: number;
+        currency: string;
+        interval?: "month" | "year";
+    };
+    /** The customer confirmed: cancel the subscription in your code. Throwing keeps the dialog open with an error. */
+    onCancel?: (result: CancelFlowResult) => unknown;
+    /** The customer took an offer: apply it in your code (coupon, pause, plan change). Throwing keeps the dialog open. */
+    onSave?: (result: CancelFlowResult) => unknown;
+    /** Closed without cancelling or taking an offer. */
+    onClose?: (result: CancelFlowResult) => void;
+}
+/** What a renderer draws. */
+type FlowView = {
+    type: "cancel";
+    screen: "survey" | "offer" | "confirm";
+    flow: CancelFlowConfig;
+    /** The answer picked on the survey. */
+    reason?: string;
+    offer?: CancelOffer;
+    price?: CancelFlowOptions["price"];
+    busy: boolean;
+    error?: string;
+    /** The step for the dots, 1 to `steps`. */
+    step: number;
+    steps: number;
+} | {
+    type: "step";
+    flow: OnboardingFlow;
+    step: OnboardingStep;
+    index: number;
+    total: number;
+    last: boolean;
+} | {
+    type: "checklist";
+    flow: OnboardingFlow;
+    items: {
+        step: OnboardingStep;
+        done: boolean;
+    }[];
+} | {
+    type: "message";
+    message: InAppMessage;
+};
+interface FlowsController {
+    setConfig(config: CockpitConfig | null): void;
+    /** The person changed (identify, reset, consent): loads their messages and onboarding progress. */
+    refresh(): Promise<void>;
+    /** An event the app recorded: starts flows whose trigger it is and ticks checklist items. */
+    onEvent(name: string): void;
+    openCancelFlow(options?: CancelFlowOptions): Promise<CancelFlowResult>;
+    /** Starts an onboarding flow now (the first live one without an id). False when there is none to start. */
+    startOnboarding(id?: string): boolean;
+    view(): FlowView | null;
+    subscribe(listener: () => void): () => void;
+    /** `accept(comment)`: a "Talk to us" offer sends what the customer wrote with it. */
+    cancel: {
+        pick(reason: string): void;
+        next(): void;
+        accept(comment?: string): void;
+        decline(): void;
+        confirm(comment?: string): void;
+        close(): void;
+    };
+    onboarding: {
+        next(): void;
+        check(stepId: string): void;
+        dismiss(): void;
+    };
+    message: {
+        click(): void;
+        dismiss(): void;
+    };
+}
+
 /**
  * The part of the SDK that runs anywhere: experiment config, variant assignment, preview links and event shapes.
  * No React, no browser APIs, so the server helper, the proxy helper and the client share it.
  */
+
 type VariantId = string;
 /** This build of the SDK. Sent with the config request so MRRocket knows what the site runs (error tracking, flags). */
-declare const SDK_VERSION = "0.4.0";
+declare const SDK_VERSION = "0.8.0";
 /** One variant of an experiment. `changes` replaces texts that the page marks with `<Text id>`. */
 interface VariantConfig {
     id: VariantId;
     /** Share of traffic, 0 to 1. The weights of an experiment add up to 1. */
     weight: number;
     changes?: Record<string, string>;
+    /**
+     * A redirect test: where this variant sends the visitor instead of the test's page (a path like "/pricing-b" or a
+     * full address). Control has none and stays. SDK 0.7.0+.
+     */
+    url?: string;
 }
 interface ExperimentConfig {
     /** The experiment's key, the same as in Cockpit. */
@@ -23,6 +204,15 @@ interface ExperimentConfig {
     variants: VariantConfig[];
     /** A winner that shipped: everyone gets it, and nobody is assigned anymore. */
     winner?: VariantId;
+    /** A redirect test: the path of the page it runs on ("/pricing"). Visitors there are sent to their variant's `url`. */
+    path?: string;
+}
+/** A page redirect set in MRRocket (Conversion › Landing pages › Redirect): everyone on `from` goes to `to`. SDK 0.7.0+. */
+interface RedirectConfig {
+    /** A path of the site, like "/old-pricing". */
+    from: string;
+    /** A path or a full address. */
+    to: string;
 }
 interface CockpitConfig {
     /** The product the public key belongs to. */
@@ -36,6 +226,20 @@ interface CockpitConfig {
     replay?: ReplayConfig;
     /** Feature flags of the product in Production (MRRocket › Build › Feature flags), evaluated by `useFlag` and `getFlag`. */
     flags?: FlagConfig[];
+    /**
+     * Published copy for texts the site marks (`<Text id>`, `data-ck-text`): a landing page's headline, subheadline and
+     * button (`pricing.headline` …) and a paywall's (`paywall.<placement>.headline` …) as published in MRRocket. A
+     * running test's variant changes them on top. Missing when nothing is published. SDK 0.5.0+.
+     */
+    texts?: Record<string, string>;
+    /** The product's live cancel flow (MRRocket › Churn › Cancel flow), for `cancelFlow.open()`. SDK 0.7.0+. */
+    cancelFlow?: CancelFlowConfig;
+    /** The in-app steps of live onboarding flows (tours, checklists, modals). SDK 0.7.0+. */
+    onboarding?: OnboardingFlow[];
+    /** A live Lifecycle journey has in-app messages: signed-in people ask `/api/sdk/inapp` for theirs. SDK 0.7.0+. */
+    messages?: boolean;
+    /** Page redirects set in MRRocket; the SDK sends visitors on before the page shows (`redirectFor`). SDK 0.7.0+. */
+    redirects?: RedirectConfig[];
 }
 /** One condition of a flag's audience, on a property of the person (`identify(id, props)`), the id or the page. */
 interface FlagCondition {
@@ -147,6 +351,8 @@ interface MRRocketOptions {
     maxQueue?: number;
     /** Log what the SDK does to the console. */
     debug?: boolean;
+    /** Onboarding flows start on their own when the person does their trigger (default true). False: only `startOnboarding()`. */
+    onboarding?: boolean;
 }
 /** AsyncStorage's shape. */
 interface KeyValueStorage {
@@ -154,6 +360,20 @@ interface KeyValueStorage {
     setItem(key: string, value: string): Promise<void>;
     removeItem(key: string): Promise<void>;
 }
+interface RegisterForPushOptions {
+    /** Ask for the permission when it was not decided yet (default true). False: only register when already allowed. */
+    ask?: boolean;
+    /** Your EAS project id; default: the one in your app config (`expo-constants`). */
+    projectId?: string;
+}
+type NativePushStatus = "registered" | "denied" | "not-asked" | "unavailable" | "not-signed-in" | "error";
+interface NativePushResult {
+    status: NativePushStatus;
+    /** The Expo push token, once registered. */
+    token?: string;
+    /** Why it is unavailable or failed. */
+    reason?: string;
+}
 /** What the app (and the React hooks) use. */
 interface MRRocketClient {
     track(event: string, props?: Record<string, unknown>): void;
@@ -172,6 +392,35 @@ interface MRRocketClient {
     peekVariant(key: string): VariantId;
     /** Records that the person saw `variant` of `key`, once per screen. */
     expose(key: string, variant: VariantId): void;
+    /**
+     * The copy for text `id` as published in MRRocket (a paywall's `paywall.<placement>.headline`, an onboarding title …)
+     * with this person's experiment variant applied on top, the same rules as `<Text id>` on the web; `fallback` (your
+     * own words) while nothing is published or the config is unknown. Records the exposure to every test that changes
+     * `id`, once per screen.
+     */
+    getText(id: string, fallback: string): string;
+    /** The text without recording anything (render code); undefined when MRRocket has none. Pair it with `exposeText`. */
+    peekText(id: string): string | undefined;
+    /** Records that the person saw text `id`: an exposure to each test that changes it, once per screen. */
+    exposeText(id: string): void;
+    /**
+     * Shows the cancel flow built in MRRocket › Churn (drawn by `<MRRocketProvider>`), resolves with what the customer
+     * did. MRRocket never changes the subscription: your `onCancel` and `onSave` do.
+     */
+    openCancelFlow(options?: CancelFlowOptions): Promise<CancelFlowResult>;
+    /** Starts an onboarding flow now (the first live one without an id). False when there is none. */
+    startOnboarding(id?: string): boolean;
+    /**
+     * Push notifications from your Lifecycle journeys for the signed-in person (call `identify` first). Asks the
+     * permission (unless `ask: false`), gets the Expo push token and sends it to MRRocket. Needs `expo-notifications`.
+     * Safe to call on every start: an existing token is sent again without asking. Opens of MRRocket's notifications
+     * are counted from then on.
+     */
+    registerForPush(options?: RegisterForPushOptions): Promise<NativePushResult>;
+    /** Removes this device's token for the signed-in person (sign-out does it on its own in `reset`). */
+    unregisterForPush(): Promise<boolean>;
+    /** The cancel flow, onboarding and messages for a renderer (the provider's, or your own). */
+    flows: FlowsController;
     /** Sends what is queued now. */
     flush(): Promise<void>;
     /** Resolves once stored state and the config (cached or fetched) are known. */
@@ -192,6 +441,15 @@ interface MRRocketClient {
 /** The name of the screen a React Navigation state shows: the focused route, followed into nested navigators. */
 declare const activeRouteName: (state: unknown) => string | undefined;
 
+interface NativeAppearance {
+    theme?: "light" | "dark" | "auto";
+    accent?: string;
+}
+declare const MRRocketFlows: ({ flows, appearance }: {
+    flows: FlowsController;
+    appearance?: NativeAppearance;
+}) => react.FunctionComponentElement<Record<string, unknown>> | null;
+
 /**
  * The SDK's client outside React (a background task, a store, an API layer): the one the provider made, or a new one.
  * One client per app; a second call returns the first.
@@ -208,6 +466,13 @@ interface MRRocketProviderProps extends Partial<MRRocketOptions> {
     storage?: KeyValueStorage | null;
     /** A client you made with createMRRocket; the other props are then ignored. */
     client?: MRRocketClient;
+    /**
+     * Draw the cancel flow, onboarding and in-app messages (default true). False: draw `client.flows` yourself, or
+     * place `<MRRocketFlows flows={client.flows} />` where you want it.
+     */
+    flows?: boolean;
+    /** The look of those dialogs: `{ theme: "light" | "dark" | "auto", accent: "#0f766e" }`. */
+    appearance?: NativeAppearance;
     children?: ReactNode;
 }
 /**
@@ -215,7 +480,7 @@ interface MRRocketProviderProps extends Partial<MRRocketOptions> {
  * starts the SDK: lifecycle events, the event queue, flags and experiments, error capture. Changing `consent` later
  * calls setConsent.
  */
-declare const MRRocketProvider: ({ client: given, children, consent, ...options }: MRRocketProviderProps) => react.FunctionComponentElement<react.ProviderProps<MRRocketClient | null>>;
+declare const MRRocketProvider: ({ client: given, children, consent, flows, appearance, ...options }: MRRocketProviderProps) => react.FunctionComponentElement<react.ProviderProps<MRRocketClient | null>>;
 /**
  * `track`, `screen`, `identify`, `reset`, `setConsent`, `captureError`, `flush`, the visitor id, the consent and whether
  * flags and experiments have loaded.
@@ -232,6 +497,33 @@ declare const useMRRocket: () => {
     consent: NativeConsent;
     ready: boolean;
 };
+/**
+ * The cancel flow built in MRRocket › Churn › Cancel flow. Call `open` from your Cancel button; the provider draws it.
+ * MRRocket never changes the subscription: your `onCancel` and `onSave` do (RevenueCat, your server, the store's
+ * subscription page).
+ *
+ *     const cancelFlow = useCancelFlow();
+ *     <Button title="Cancel subscription" onPress={() => cancelFlow.open({ customer: "consumer", onCancel: openStoreSubscriptions })} />
+ */
+declare const useCancelFlow: () => {
+    open: (options?: CancelFlowOptions) => Promise<CancelFlowResult>;
+};
+/**
+ * Push notifications from your Lifecycle journeys (needs `expo-notifications`). After sign-in (`identify`), call
+ * `register()`: it asks the permission, gets the Expo push token and sends it to MRRocket. Sign-out (`reset`) takes the
+ * token back on its own.
+ *
+ *     const push = usePush();
+ *     useEffect(() => { if (user) void push.register(); }, [user]);
+ */
+declare const usePush: () => {
+    register: MRRocketClient["registerForPush"];
+    unregister: MRRocketClient["unregisterForPush"];
+};
+/** Starts an onboarding flow now (the first live one without an id), whatever its trigger. */
+declare const useOnboarding: () => {
+    start: (id?: string) => boolean;
+};
 /** A feature flag from MRRocket › Build › Feature flags: true while it is on for this person; false while off, unknown or loading. */
 declare const useFlag: (key: string) => boolean;
 /** The variant of a multivariate flag ("control", "test" …), or null while it is off. */
@@ -241,6 +533,16 @@ declare const useFlagVariant: (key: string) => string | null;
  * cold start, so the first screen is already stable). Records the exposure once per screen.
  */
 declare const useVariant: (key: string) => VariantId;
+/**
+ * Copy MRRocket can change without an app update: the text published for `id` (a paywall's
+ * `paywall.<placement>.headline`, `.body`, `.cta`), with this person's variant of a running text test on top,
+ * the same rules as `<Text id>` on the web. Write your own words as `fallback`: they show while nothing is published
+ * and on a first start before the config arrives. Records the exposure to every test that changes `id`, once per screen.
+ *
+ *     const headline = useText("paywall.onboarding.headline", "Unlock everything");
+ *     <Text style={styles.title}>{headline}</Text>
+ */
+declare const useText: (id: string, fallback: string) => string;
 /**
  * Screen views for Expo Router: one `$screen` per path ("/settings", "/product/[id]" as its real path). Call it in a
  * component inside both the router and MRRocketProvider, for example the root layout's child.
@@ -256,4 +558,4 @@ declare const useExpoRouterTracking: () => void;
  */
 declare const useNavigationTracking: () => (state: unknown) => void;
 
-export { type AppContext, type CockpitConfig, type FlagConfig, type KeyValueStorage, type MRRocketClient, type MRRocketOptions, MRRocketProvider, type MRRocketProviderProps, type NativeConsent, SDK_VERSION, type VariantId, activeRouteName, createMRRocket, getMRRocket, useExpoRouterTracking, useFlag, useFlagVariant, useMRRocket, useNavigationTracking, useVariant };
+export { type AppContext, type CancelFlowConfig, type CancelFlowOptions, type CancelFlowResult, type CancelOffer, type CockpitConfig, type FlagConfig, type FlowView, type InAppMessage, type KeyValueStorage, type MRRocketClient, MRRocketFlows, type MRRocketOptions, MRRocketProvider, type MRRocketProviderProps, type NativeAppearance, type NativeConsent, type NativePushResult, type NativePushStatus, type OnboardingFlow, type OnboardingStep, type RegisterForPushOptions, SDK_VERSION, type VariantId, activeRouteName, createMRRocket, getMRRocket, useCancelFlow, useExpoRouterTracking, useFlag, useFlagVariant, useMRRocket, useNavigationTracking, useOnboarding, usePush, useText, useVariant };