@mrrocket/sdk 0.17.0 → 0.21.0

package/dist/flows.d.ts

@@ -12,7 +12,9 @@
  * - `$onboarding` `{flow, step?, action: "started" | "shown" | "completed" | "dismissed"}`; since 0.11.0 a wait records
  *   "shown" when the person reaches it and "completed" when it is over, a condition `{action: "answered", answer: "yes"
  *   | "no"}` once it is decided; since 0.17.0 a tour a checklist task started records `{action: "started", from}` with
- *   the checklist's id.
+ *   the checklist's id; since 0.18.0 a question records `{kind: "question", action: "completed", question, answer,
+ *   label}` (the question's key, the option's id or the typed text, the option's words), which MRRocket keeps on the
+ *   contact, and a checklist task that opens something `{action: "opened", opens}`.
  * - `$inapp` `{message, journey, action: "shown" | "clicked" | "dismissed"}`; the journey moves the person on.
  */
 import type { CockpitConfig } from "./core.js";
@@ -37,8 +39,10 @@ export interface CancelOffer {
 /** 0.15.0: a second question after an answer ("What would be a fair price?"); no answers means a free text. */
 export interface CancelFollowUp {
     question: string;
-    /** The choices, in order; empty for a free text. */
+    /** The choices, in order; empty for a free text. What is recorded and what rules compare, whatever the language. */
     answers: string[];
+    /** 0.21.0: what each choice says in the visitor's language, parallel to `answers`; shown instead of them. */
+    answerLabels?: string[];
 }
 /**
  * 0.15.0: a different offer for some customers of one answer. Every condition that is set must hold; the first rule
@@ -86,7 +90,71 @@ export interface CancelFlowConfig {
      */
     offersFor: "business";
 }
-export type OnboardingStepKind = "tour" | "checklist" | "modal";
+/** "question" (0.18.0): one question of a Questions item, a slide of its window. */
+export type OnboardingStepKind = "tour" | "checklist" | "modal" | "question";
+/**
+ * 0.18.0: what a checklist task opens. `page`: a path or address on the web, a deep link (`myapp://…`) or a screen name
+ * in an app, handed to the app's `onNavigate` when it passes one; `tour` / `modal`: another item of the config, after
+ * which the checklist comes back; `code`: the app's `onTask(taskId, item)`.
+ */
+export type TaskOpens = {
+    kind: "page";
+    target: string;
+} | {
+    kind: "tour";
+    id: string;
+} | {
+    kind: "modal";
+    id: string;
+} | {
+    kind: "code";
+};
+/**
+ * 0.18.0: a small picture beside a checklist task or above a modal's or the questions' heading: one of the SDK's own
+ * line icons (`FLOW_ICON_NAMES`, icons.ts), an emoji, or a picture (http(s)).
+ */
+export type FlowIcon = {
+    kind: "builtin";
+    name: string;
+} | {
+    kind: "emoji";
+    value: string;
+} | {
+    kind: "image";
+    url: string;
+};
+/** 0.18.0: what plays when someone finishes a checklist, a tour or the questions. */
+export type FinishAnimation = "none" | "confetti" | "fireworks" | "stars";
+/**
+ * 0.18.0: one question of a Questions item: one choice of 2 to 6 options, or a short text. 0.21.0: a number scale, an
+ * "Other" with the person's own words, and a Skip button. An older app shows a scale as a text field, leaves "Other"
+ * out, and offers no Skip (its close button still ends the window).
+ */
+export interface OnboardingQuestion {
+    /** The answer's name on the contact (`onboarding.<key>`) and in "People who answered …". */
+    key: string;
+    type: "choice" | "text" | "scale";
+    /** Choice: the options, in order; `id` is what is stored, `label` what people read. */
+    options?: {
+        id: string;
+        label: string;
+    }[];
+    /** Text: the field's hint. */
+    placeholder?: string;
+    /** 0.21.0, choice: one more option where people type their own words, stored as `other:<words>`. */
+    other?: boolean;
+    /** 0.21.0: the words of that option; "Other" when unset. */
+    otherLabel?: string;
+    /** 0.21.0, scale: the lowest and highest number, and the words under both ends. */
+    min?: number;
+    max?: number;
+    lowLabel?: string;
+    highLabel?: string;
+    /** 0.21.0: people may go on without answering. */
+    optional?: boolean;
+    /** 0.21.0: the words of that button; "Skip" when unset. */
+    skipLabel?: string;
+}
 /** 0.17.0: where a tour bubble sits next to its element; "auto" (and no value) puts it below, else above, as before. */
 export type TourPlacement = "auto" | "top" | "bottom" | "left" | "right";
 /**
@@ -116,6 +184,12 @@ export interface OnboardingStep {
     url?: string;
     /** 0.17.0, checklist items: the id of a tour (another flow) the item starts; finishing the tour ticks the item. */
     startsTour?: string;
+    /** 0.18.0, checklist items: what the task opens (read before `startsTour`, which MRRocket still sends for a tour). */
+    opens?: TaskOpens;
+    /** 0.18.0, checklist items: the task's icon. */
+    icon?: FlowIcon;
+    /** 0.18.0, question steps: the question (the step's `title` is what people read). */
+    question?: OnboardingQuestion;
 }
 /** A pause in a flow (0.11.0): the next step shows this long after the one before was done. */
 export interface OnboardingWait {
@@ -148,10 +222,33 @@ export interface OnboardingFlow {
      * of the app ("/settings", "/projects/*"), or "From a checklist" (only a checklist task starts it).
      */
     trigger: string;
-    /** 0.17.0: "signed_in" starts it on its own only for someone the app identified. */
-    audience?: "signed_in";
+    /**
+     * 0.17.0: "signed_in" starts it on its own only for someone the app identified. 0.18.0: "answered" only for someone
+     * who gave `answered.option` to the question `answered.question` (its key).
+     */
+    audience?: "signed_in" | "answered";
+    /** 0.18.0: with `audience: "answered"`, the question's key and the option's id (or the typed text). */
+    answered?: {
+        question: string;
+        option: string;
+    };
     /** What every version shows: with `nodes`, only the in-app steps before the first wait or condition. */
     steps: OnboardingStep[];
+    /** 0.18.0: the icon above a modal's or the questions' heading. */
+    icon?: FlowIcon;
+    /** 0.18.0: what plays when the person finishes it (a checklist, a tour, the questions). */
+    finish?: FinishAnimation;
+    /**
+     * 0.18.0: "code": the app draws it itself (`useOnboarding(id)`, `mrrocket.onboarding.get(id)`); the SDK draws
+     * nothing for it, never starts it, and still records what the app reports. Such an item's `trigger` is
+     * "From your code" (older versions never start it).
+     */
+    shownBy?: "code";
+    /**
+     * 0.18.0: the item's real moment (read instead of `trigger`, see `momentOf`) when `trigger` is one older versions
+     * never start: "From your code", or `NEEDS_NEWER` for questions and items that follow another or ask for an answer.
+     */
+    when?: string;
     /** 0.11.0+: the whole flow with its waits and conditions. Read instead of `steps` when it is there. */
     nodes?: OnboardingNode[];
 }
@@ -183,6 +280,8 @@ export interface InAppState {
     messages: InAppMessage[];
     /** 0.11.0: the events the flows' conditions ask about that this person did (as `eventSlug`s). */
     events?: string[];
+    /** 0.18.0: the person's answers to onboarding questions, by the question's key (an option's id or the text). */
+    answers?: Record<string, string>;
     /**
      * 0.16.0: a live review request may ask this person now. The React Native client's `requestReview()` opens the
      * store's own rating dialog (expo-store-review) and reports `$review_prompt`; websites have no store dialog.
@@ -247,15 +346,22 @@ export type FlowView = {
     /** The step for the dots, 1 to `steps`. */
     step: number;
     steps: number;
-} | {
+}
+/** `answer` (0.18.0): a question's answer so far (an option's id or the typed text); `back`: an earlier question to go back to. */
+ | {
     type: "step";
     flow: OnboardingFlow;
     step: OnboardingStep;
     index: number;
     total: number;
     last: boolean;
+    answer?: string;
+    back?: boolean;
 }
-/** `tour`: the tour the item starts (0.17.0), when the config has it. */
+/**
+ * `tour`: the tour the item starts (0.17.0), when the config has it. `opens` (0.18.0): what tapping the task opens
+ * (a tour or modal only when the config has it); `target` the item it opens.
+ */
  | {
     type: "checklist";
     flow: OnboardingFlow;
@@ -263,6 +369,8 @@ export type FlowView = {
         step: OnboardingStep;
         done: boolean;
         tour?: OnboardingFlow;
+        opens?: TaskOpens;
+        target?: OnboardingFlow;
     }[];
 } | {
     type: "message";
@@ -286,6 +394,13 @@ export interface FlowsEnv {
     auto?: boolean;
     /** The page the person is on (a path), for "Is on <page>?" conditions; without it they answer no. */
     path?: () => string | undefined;
+    /**
+     * 0.18.0: opens what a checklist task's "page or screen" names (a path, an address, a deep link, a screen name).
+     * The web and React Native clients pass the app's `onNavigate`, else their own default.
+     */
+    navigate?: (target: string) => void;
+    /** 0.18.0: a checklist task that runs the app's own code (`onTask(taskId, item)`). */
+    task?: (taskId: string, item: OnboardingFlow) => void;
     /** The clock, for tests. */
     now?: () => number;
 }
@@ -311,17 +426,56 @@ export interface FlowsController {
         confirm(comment?: string): void;
         close(): void;
     };
-    /** `startTour(stepId)` (0.17.0): the tour a checklist item starts; the checklist comes back when it ends. */
+    /**
+     * `startTour(stepId)` (0.17.0): the tour a checklist item starts; the checklist comes back when it ends.
+     * 0.18.0: `open(stepId)` does what the task opens (a page, a tour, a modal, the app's code); `answer(value)` picks an
+     * option or types the text of the question on screen, `back()` returns to the question before. `item(id)` and the
+     * calls after it are for an item the app draws itself (`shownBy: "code"`).
+     */
     onboarding: {
         next(): void;
         check(stepId: string): void;
         dismiss(): void;
         startTour(stepId: string): boolean;
+        open(stepId: string): boolean;
+        answer(value: string): void;
+        /** 0.21.0: goes on from an optional question without an answer. */
+        skip(): void;
+        back(): void;
+        item(id: string): OnboardingItemState | null;
+        seen(id: string): void;
+        complete(id: string, stepId: string): void;
+        dismissItem(id: string): void;
+        answerItem(id: string, question: string, value: string): void;
     };
     message: {
         click(): void;
         dismiss(): void;
     };
+    /** 0.18.0: the animation to play now that someone finished an item (a new `key` each time), or null. */
+    finale(): {
+        kind: Exclude<FinishAnimation, "none">;
+        key: string;
+    } | null;
+    /** 0.18.0: the product's brand color from MRRocket, for the dialogs when the app passes no accent of its own. */
+    accent(): string | undefined;
+    /** 0.18.0: the person's answers to onboarding questions, by key. */
+    answers(): Record<string, string>;
+}
+/** 0.18.0: an item the app draws itself (`shownBy: "code"`), with the person's progress. */
+export interface OnboardingItemState {
+    item: OnboardingFlow;
+    /** Its steps (a tour's steps, a checklist's tasks, the questions), each with whether the person did it. */
+    steps: (OnboardingStep & {
+        done: boolean;
+        answer?: string;
+    })[];
+    /** Every step is done. */
+    done: boolean;
+    /** The person closed it. */
+    dismissed: boolean;
+    /** Its moment has come for this person (the trigger MRRocket set, and who it is for); your code may ignore it. */
+    eligible: boolean;
 }
 /** The plain confirmation, when the product has no live cancel flow (or MRRocket was not reachable). */
 export declare const PLAIN_CANCEL: CancelFlowConfig;
@@ -335,6 +489,32 @@ export declare const startsOnLoad: (trigger: string) => boolean;
 export declare const FROM_CHECKLIST = "From a checklist";
 /** 0.17.0: a trigger that is a page of the app ("/settings", "/projects/*"): the flow starts when the person opens it. */
 export declare const isPageTrigger: (trigger: string) => boolean;
+/** 0.18.0: the trigger of an item the app draws itself (`shownBy: "code"`); older versions never start it. */
+export declare const FROM_CODE = "From your code";
+/**
+ * 0.18.0: the trigger MRRocket sends for an item older versions could not show right (questions, "After <item> ends",
+ * "People who answered …"), so they never start it; its real moment is in `when`.
+ */
+export declare const NEEDS_NEWER = "Needs tracking code 0.18.0";
+/** An item's moment: `when` (0.18.0) where MRRocket sent one, else its trigger. */
+export declare const momentOf: (f: Pick<OnboardingFlow, "trigger" | "when">) => string;
+/** 0.18.0: the trigger "after:<item id>": the item starts once that item ended (finished or closed). */
+export declare const AFTER_PREFIX = "after:";
+/** The item an "after:<id>" trigger follows, or null. */
+export declare const afterOf: (trigger: string | undefined) => string | null;
+/** 0.18.0: what a task opens; a 0.17.0 `startsTour` reads as opening that tour. */
+export declare const opensOf: (step: Pick<OnboardingStep, "opens" | "startsTour">) => TaskOpens | undefined;
+/** 0.21.0: how a choice answer in the person's own words starts. */
+export declare const OTHER_PREFIX = "other:";
+/** 0.21.0: the numbers of a scale question, low to high. */
+export declare const scaleOf: (q: OnboardingQuestion | undefined) => number[];
+/**
+ * 0.18.0: a usable answer to a question: one of its options' ids, or a text of 1 to 500 characters. 0.21.0: the words
+ * of "Other", or a number of the scale.
+ */
+export declare const answerOk: (q: OnboardingQuestion | undefined, value: string | undefined) => boolean;
+/** The option's words for an answer (a text answer is its own words, "Other" the words typed, a number itself). */
+export declare const answerLabel: (q: OnboardingQuestion | undefined, value: string) => string;
 /**
  * 0.17.0: how a video link plays. YouTube, Vimeo and Loom through their players without tracking cookies
  * (youtube-nocookie.com, Vimeo's `dnt=1`), a file (mp4, webm, mov, or an upload in MRRocket) in a plain video element;
@@ -353,7 +533,11 @@ export declare const discounted: (amount: number, percent: number) => number;
 /** "€20.30" in the customer's own currency, without a library. */
 export declare const money: (amount: number, currency: string) => string;
 /** The button of an offer. */
-export declare const offerButton: (o: CancelOffer) => "Send to the team" | "Pause instead" | "Switch plan" | "Accept offer";
+export declare const offerButton: (o: CancelOffer) => string;
+/** "3 months". */
+export declare const monthsWord: (n: number) => string;
+/** "for 3 months". */
+export declare const forMonths: (n: number) => string;
 /** A link a message may open: http(s), or a path of the app. Nothing else (no `javascript:`). */
 export declare const safeUrl: (url: string | undefined) => string | undefined;
 /** The flow's nodes: the whole tree (0.11.0 config), or the plain steps of an older one. */