@mrrocket/sdk 0.16.0 → 0.18.0

package/dist/flows.d.ts

@@ -11,7 +11,10 @@
  *   `onCancel`, and only after they succeed is the outcome recorded.
  * - `$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.
+ *   | "no"}` once it is decided; since 0.17.0 a tour a checklist task started records `{action: "started", from}` with
+ *   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";
@@ -85,7 +88,65 @@ 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. */
+export interface OnboardingQuestion {
+    /** The answer's name on the contact (`onboarding.<key>`) and in "People who answered …". */
+    key: string;
+    type: "choice" | "text";
+    /** 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.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";
+/**
+ * 0.17.0: a picture or a video above a tour step's or a modal's text. A video is a YouTube, Vimeo or Loom link (shown
+ * through their privacy-friendly players, see `videoEmbed`) or a video file (mp4, webm).
+ */
+export interface FlowMedia {
+    kind: "image" | "video";
+    url: string;
+    alt?: string;
+}
 export interface OnboardingStep {
     id: string;
     kind: OnboardingStepKind;
@@ -96,6 +157,20 @@ export interface OnboardingStep {
     target?: string;
     /** Checklist items: the event that ticks them (`track("<event>")`). Without it the person ticks it themselves. */
     event?: string;
+    /** 0.17.0, tour steps: which side of the element the bubble takes (flips when there is no room). */
+    placement?: TourPlacement;
+    /** 0.17.0, tour steps and modals: a picture or a video above the text. */
+    media?: FlowMedia;
+    /** 0.17.0, modals: where the button goes (http(s) or a path of the app). */
+    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 {
@@ -121,11 +196,40 @@ export type OnboardingNode = OnboardingStep | OnboardingWait | OnboardingConditi
 /** A live onboarding flow's in-app steps (MRRocket › Conversion › Onboarding); its emails go out from MRRocket. */
 export interface OnboardingFlow {
     id: string;
+    /** A checklist's heading; for tours and modals the name MRRocket knows them by. */
     name: string;
-    /** When it starts: an event's words ("Signed up", "First export"), or "First launch" / "First visit". */
+    /**
+     * When it starts: an event's words ("Signed up", "First export"), "First launch" / "First visit", since 0.17.0 a page
+     * 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. 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[];
 }
@@ -157,6 +261,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.
@@ -221,19 +327,31 @@ 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. `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;
     items: {
         step: OnboardingStep;
         done: boolean;
+        tour?: OnboardingFlow;
+        opens?: TaskOpens;
+        target?: OnboardingFlow;
     }[];
 } | {
     type: "message";
@@ -257,6 +375,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;
 }
@@ -282,15 +407,54 @@ 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.
+     * 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;
+        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;
@@ -300,6 +464,40 @@ export declare const eventSlug: (s: string) => string;
 export declare const matchesTrigger: (trigger: string, event: string) => boolean;
 /** Triggers that mean "the first time the person opens the app": the flow starts on load until it is done. */
 export declare const startsOnLoad: (trigger: string) => boolean;
+/** 0.17.0: the trigger of a tour only a checklist task starts. */
+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.18.0: a usable answer to a question: one of its options' ids, or a text of 1 to 500 characters. */
+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). */
+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;
+ * anything else is not shown. Regular expressions only, so React Native can use it too.
+ */
+export declare const videoEmbed: (url: string | undefined) => {
+    kind: "iframe" | "file";
+    src: string;
+} | null;
+/** 0.17.0: a step's picture or video when the dialogs may load it (http(s), a video they can play), else undefined. */
+export declare const mediaOf: (step: Pick<OnboardingStep, "media">) => FlowMedia | undefined;
 /** A random id for one cancel flow run. */
 export declare const runId: () => string;
 /** The money a discount leaves: `29 EUR` at 30 % → `20.30`. */