@mrrocket/sdk 0.16.0 → 0.18.0

package/dist/onboarding-state.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/onboarding-state.ts"],"sourcesContent":["/**\n * 0.18.0: `useOnboarding(id)` for an onboarding item the app draws itself (\"Shown by: your code\" in MRRocket): its\n * content and the person's progress, and the calls that report what they did. Shared by the Next.js provider and React\n * Native (only React here). The SDK draws nothing for such an item and never starts it; what the app reports still\n * reaches MRRocket (who saw it, who finished it, the answers on the contact), and the item after it follows as usual.\n *\n *     const { item, steps, done, complete, dismiss, answer } = useOnboarding(\"flow_123\");\n *     if (!item || done) return null;\n *     return steps.map((s) => <Task key={s.id} title={s.title} done={s.done} onPress={() => complete(s.id)} />);\n */\nimport { useEffect, useMemo, useState } from \"react\";\nimport type { FlowsController, OnboardingFlow, OnboardingItemState } from \"./flows\";\n\nexport interface UseOnboarding {\n    /** The item as MRRocket published it, or null while the config is loading, or when it is not live. */\n    item: OnboardingFlow | null;\n    /** Its steps (a tour's steps, a checklist's tasks, the questions), each with `done` (and a question's `answer`). */\n    steps: OnboardingItemState[\"steps\"];\n    /** Every step is done. */\n    done: boolean;\n    /** The person closed it. */\n    dismissed: boolean;\n    /** Its moment has come for this person (the trigger MRRocket set, and who it is for). */\n    eligible: boolean;\n    /** Marks a step done (a tour step, a task). */\n    complete(stepId: string): void;\n    /** The person closed it; the item after it follows. */\n    dismiss(): void;\n    /** Answers a question (its step id or its key) with an option's id or a text; it is kept on the contact. */\n    answer(question: string, value: string): void;\n    /** Starts an item the SDK draws (the first live one without an id). */\n    start(id?: string): boolean;\n}\n\nconst none: OnboardingItemState[\"steps\"] = [];\n\n/** The hook behind `useOnboarding` on both platforms. */\nexport const useOnboardingItem = (flows: FlowsController | null | undefined, id: string | undefined, start: (id?: string) => boolean): UseOnboarding => {\n    const [state, setState] = useState<OnboardingItemState | null>(() => (flows && id ? flows.onboarding.item(id) : null));\n    useEffect(() => {\n        if (!flows || !id) {\n            setState(null);\n            return;\n        }\n        const up = () => {\n            const s = flows.onboarding.item(id);\n            setState(s);\n            // Asked for by the app: counted as seen (started, and its first open steps), once per page.\n            if (s && !s.done && !s.dismissed) flows.onboarding.seen(id);\n        };\n        up();\n        return flows.subscribe(up);\n    }, [flows, id]);\n    return useMemo(\n        () => ({\n            item: state?.item ?? null,\n            steps: state?.steps ?? none,\n            done: !!state?.done,\n            dismissed: !!state?.dismissed,\n            eligible: !!state?.eligible,\n            complete: (stepId: string) => {\n                if (flows && id) flows.onboarding.complete(id, stepId);\n            },\n            dismiss: () => {\n                if (flows && id) flows.onboarding.dismissItem(id);\n            },\n            answer: (question: string, value: string) => {\n                if (flows && id) flows.onboarding.answerItem(id, question, value);\n            },\n            start,\n        }),\n        [state, flows, id, start],\n    );\n};\n"],"mappings":";AAUA,SAAS,WAAW,SAAS,gBAAgB;AAwB7C,IAAM,OAAqC,CAAC;AAGrC,IAAM,oBAAoB,CAAC,OAA2C,IAAwB,UAAmD;AACpJ,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAqC,MAAO,SAAS,KAAK,MAAM,WAAW,KAAK,EAAE,IAAI,IAAK;AACrH,YAAU,MAAM;AACZ,QAAI,CAAC,SAAS,CAAC,IAAI;AACf,eAAS,IAAI;AACb;AAAA,IACJ;AACA,UAAM,KAAK,MAAM;AACb,YAAM,IAAI,MAAM,WAAW,KAAK,EAAE;AAClC,eAAS,CAAC;AAEV,UAAI,KAAK,CAAC,EAAE,QAAQ,CAAC,EAAE,UAAW,OAAM,WAAW,KAAK,EAAE;AAAA,IAC9D;AACA,OAAG;AACH,WAAO,MAAM,UAAU,EAAE;AAAA,EAC7B,GAAG,CAAC,OAAO,EAAE,CAAC;AACd,SAAO;AAAA,IACH,OAAO;AAAA,MACH,MAAM,OAAO,QAAQ;AAAA,MACrB,OAAO,OAAO,SAAS;AAAA,MACvB,MAAM,CAAC,CAAC,OAAO;AAAA,MACf,WAAW,CAAC,CAAC,OAAO;AAAA,MACpB,UAAU,CAAC,CAAC,OAAO;AAAA,MACnB,UAAU,CAAC,WAAmB;AAC1B,YAAI,SAAS,GAAI,OAAM,WAAW,SAAS,IAAI,MAAM;AAAA,MACzD;AAAA,MACA,SAAS,MAAM;AACX,YAAI,SAAS,GAAI,OAAM,WAAW,YAAY,EAAE;AAAA,MACpD;AAAA,MACA,QAAQ,CAAC,UAAkB,UAAkB;AACzC,YAAI,SAAS,GAAI,OAAM,WAAW,WAAW,IAAI,UAAU,KAAK;AAAA,MACpE;AAAA,MACA;AAAA,IACJ;AAAA,IACA,CAAC,OAAO,OAAO,IAAI,KAAK;AAAA,EAC5B;AACJ;","names":[]}

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

@@ -176,8 +176,14 @@ interface MessengerLook {
     header?: "plain" | "color";
     /** "Powered by MRRocket" at the bottom; the server sends false only on plans that may hide it (from 0.15). */
     branding?: boolean;
-    /** The product's icon (its favicon) at the top left of Home; without it the title's first letter. */
+    /** The logo at the top left of Home: the one uploaded in MRRocket, else the product's favicon; without it the title's first letter. */
     logo?: string;
+    /** The product's favicon, the round mark in the chat's head (from 0.17; without it the title's first letter). */
+    icon?: string;
+    /** The AI agent's name on its answers (from 0.17; empty or left out: "AI agent"). */
+    agentName?: string;
+    /** The AI agent's picture beside its answers (from 0.17). */
+    agentPhoto?: string;
 }
 /** The visitor's newest chat (open or closed) and its messages. */
 interface ChatThread {
@@ -274,7 +280,10 @@ type Api = ReturnType<typeof createApi>;
  *   `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.
  */
 
@@ -343,7 +352,65 @@ interface CancelFlowConfig {
      */
     offersFor: "business";
 }
-type OnboardingStepKind = "tour" | "checklist" | "modal";
+/** "question" (0.18.0): one question of a Questions item, a slide of its window. */
+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)`.
+ */
+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)).
+ */
+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. */
+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. */
+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. */
+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).
+ */
+interface FlowMedia {
+    kind: "image" | "video";
+    url: string;
+    alt?: string;
+}
 interface OnboardingStep {
     id: string;
     kind: OnboardingStepKind;
@@ -354,6 +421,20 @@ 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. */
 interface OnboardingWait {
@@ -379,11 +460,40 @@ type OnboardingNode = OnboardingStep | OnboardingWait | OnboardingCondition;
 /** A live onboarding flow's in-app steps (MRRocket › Conversion › Onboarding); its emails go out from MRRocket. */
 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[];
 }
@@ -453,19 +563,31 @@ 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";
@@ -493,15 +615,54 @@ 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. */
+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;
 }
 
 /**
@@ -621,7 +782,7 @@ interface PaywallHost {
 
 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.16.0";
+declare const SDK_VERSION = "0.18.0";
 /** One variant of an experiment. `changes` replaces texts that the page marks with `<Text id>`. */
 interface VariantConfig {
     id: VariantId;
@@ -674,6 +835,8 @@ interface CockpitConfig {
     cancelFlow?: CancelFlowConfig;
     /** The in-app steps of live onboarding flows (tours, checklists, modals). SDK 0.7.0+. */
     onboarding?: OnboardingFlow[];
+    /** The product's brand color ("#rrggbb") for the onboarding dialogs when the app passes no accent. SDK 0.18.0+. */
+    onboardingAccent?: string;
     /** 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+. */
@@ -822,6 +985,14 @@ interface MRRocketOptions {
     debug?: boolean;
     /** Onboarding flows start on their own when the person does their trigger (default true). False: only `startOnboarding()`. */
     onboarding?: boolean;
+    /**
+     * 0.18.0: opens what a checklist task's "Opens: page or screen" names: a screen name or a path for your navigator
+     * (`(target) => router.push(target)`). Without it only a deep link or an address (`myapp://…`, `https://…`) opens,
+     * through `Linking`.
+     */
+    onNavigate?: (target: string) => void;
+    /** 0.18.0: a checklist task set to "Opens: your code" was tapped: `(taskId, item) => …`. */
+    onTask?: (taskId: string, item: OnboardingFlow) => void;
     /** Taps go to Heatmaps as clicks on the screen they happened on (default true; `MRRocketProvider` captures them). */
     heatmaps?: boolean;
     /**
@@ -966,15 +1137,37 @@ 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 UseOnboarding {
+    /** The item as MRRocket published it, or null while the config is loading, or when it is not live. */
+    item: OnboardingFlow | null;
+    /** Its steps (a tour's steps, a checklist's tasks, the questions), each with `done` (and a question's `answer`). */
+    steps: OnboardingItemState["steps"];
+    /** 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). */
+    eligible: boolean;
+    /** Marks a step done (a tour step, a task). */
+    complete(stepId: string): void;
+    /** The person closed it; the item after it follows. */
+    dismiss(): void;
+    /** Answers a question (its step id or its key) with an option's id or a text; it is kept on the contact. */
+    answer(question: string, value: string): void;
+    /** Starts an item the SDK draws (the first live one without an id). */
+    start(id?: string): boolean;
+}
+
 interface NativeAppearance {
     theme?: "light" | "dark" | "auto";
     accent?: string;
 }
-declare const MRRocketFlows: ({ flows, paywall, appearance }: {
+/** The dialogs, and (0.18.0) the finish animation over the app when someone just finished an item. */
+declare const MRRocketFlows: (props: {
     flows: FlowsController;
     paywall?: PaywallHost;
     appearance?: NativeAppearance;
-}) => react.FunctionComponentElement<Record<string, unknown>> | null;
+}) => react.FunctionComponentElement<react.FragmentProps>;
 
 interface Palette {
     accent: string;
@@ -1039,8 +1232,10 @@ interface NativeMessengerOptions {
     corners?: MessengerCorners;
     /** Home's top: plain like the rest (default), or in the accent color with raised cards. */
     header?: "plain" | "color";
-    /** The product's icon at the top left of Home (MRRocket sends the product's favicon). */
+    /** The logo at the top left of Home (MRRocket sends the uploaded logo, else the product's favicon). */
     logo?: string;
+    /** The AI agent's name on its answers (default "AI agent"). */
+    agentName?: string;
     /** Ask people the app did not identify with an email for an email (optional for them). Default true. */
     askEmail?: boolean;
     /** The Help tab with your published help articles (default true; hidden while there are none). */
@@ -1170,10 +1365,16 @@ declare const usePaywall: () => {
 declare const useReview: () => {
     request: MRRocketClient["requestReview"];
 };
-/** Starts an onboarding flow now (the first live one without an id), whatever its trigger. */
-declare const useOnboarding: () => {
-    start: (id?: string) => boolean;
-};
+/**
+ * `start(id?)` starts an onboarding flow now (the first live one without an id), whatever its trigger. 0.18.0: with an
+ * id, also the item you draw yourself ("Shown by: your code" in MRRocket): `item`, `steps` (each with `done`), `done`,
+ * `complete(stepId)`, `dismiss()` and `answer(question, value)`; MRRocket still counts it and keeps the answers on the
+ * contact.
+ *
+ *     const { item, steps, done, complete } = useOnboarding("flow_123");
+ *     if (!item || done) return null;
+ */
+declare const useOnboarding: (id?: string) => UseOnboarding;
 /** 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. */
@@ -1208,4 +1409,4 @@ declare const useExpoRouterTracking: () => void;
  */
 declare const useNavigationTracking: () => (state: unknown) => void;
 
-export { type AppContext, type CancelFlowConfig, type CancelFlowOptions, type CancelFlowResult, type CancelOffer, type ChatMessage, type ChatThread, type CockpitConfig, type FeedbackPost, type FlagConfig, type FlowView, type IdentifyOptions, type InAppMessage, type KeyValueStorage, type MRRocketClient, MRRocketFeedback, MRRocketFlows, MRRocketMask, MRRocketMessenger, type MRRocketOptions, MRRocketProvider, type MRRocketProviderProps, MRRocketSurveys, type NativeAppearance, type NativeConsent, type NativeFeedbackOptions, type NativeMessengerOptions, type NativePushResult, type NativePushStatus, type NativeReviewResult, type OnboardingFlow, type OnboardingStep, type PaywallConfig, type PaywallOptions, type PaywallPage, type PaywallPlan, type PaywallResult, type RegisterForPushOptions, SDK_VERSION, type SurveyDefinition, type VariantId, activeRouteName, createMRRocket, getMRRocket, useCancelFlow, useExpoRouterTracking, useFeedback, useFlag, useFlagVariant, useMRRocket, useMessenger, useNavigationTracking, useOnboarding, usePaywall, usePush, useReview, useText, useVariant };
+export { type AppContext, type CancelFlowConfig, type CancelFlowOptions, type CancelFlowResult, type CancelOffer, type ChatMessage, type ChatThread, type CockpitConfig, type FeedbackPost, type FinishAnimation, type FlagConfig, type FlowIcon, type FlowMedia, type FlowView, type IdentifyOptions, type InAppMessage, type KeyValueStorage, type MRRocketClient, MRRocketFeedback, MRRocketFlows, MRRocketMask, MRRocketMessenger, type MRRocketOptions, MRRocketProvider, type MRRocketProviderProps, MRRocketSurveys, type NativeAppearance, type NativeConsent, type NativeFeedbackOptions, type NativeMessengerOptions, type NativePushResult, type NativePushStatus, type NativeReviewResult, type OnboardingFlow, type OnboardingItemState, type OnboardingQuestion, type OnboardingStep, type PaywallConfig, type PaywallOptions, type PaywallPage, type PaywallPlan, type PaywallResult, type RegisterForPushOptions, SDK_VERSION, type SurveyDefinition, type TaskOpens, type TourPlacement, type UseOnboarding, type VariantId, activeRouteName, createMRRocket, getMRRocket, useCancelFlow, useExpoRouterTracking, useFeedback, useFlag, useFlagVariant, useMRRocket, useMessenger, useNavigationTracking, useOnboarding, usePaywall, usePush, useReview, useText, useVariant };