@mrrocket/sdk 0.17.0 → 0.21.0

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

@@ -61,6 +61,11 @@ interface SurveyQuestion {
     description?: string;
     required: boolean;
     options?: string[];
+    /**
+     * 0.21.0: what each option says in the visitor's language, parallel to `options`. An answer is still recorded as the
+     * `options` value, so rules and numbers do not split by language.
+     */
+    labels?: string[];
     scale?: number;
     low?: string;
     high?: string;
@@ -165,6 +170,8 @@ interface MessengerLook {
     /** A round chat button in the app (React Native) too. */
     appLauncher?: boolean;
     help: boolean;
+    /** The Updates tab with the published changelog (MRRocket from 0.22; older servers leave it out). */
+    updates?: boolean;
     sound: boolean;
     preview: boolean;
     askEmail: boolean;
@@ -185,13 +192,24 @@ interface MessengerLook {
     /** The AI agent's picture beside its answers (from 0.17). */
     agentPhoto?: string;
 }
-/** The visitor's newest chat (open or closed) and its messages. */
+/** One of the visitor's conversations in their list (0.19). */
+interface ChatSummary {
+    id: string;
+    status: "open" | "solved";
+    /** The visitor's first words. */
+    subject: string;
+    /** The newest message, its body cut to a preview. */
+    last: ChatMessage | null;
+}
+/** One chat (the one asked for, else the visitor's newest, open or closed) and its messages. */
 interface ChatThread {
     conversation: {
         id: string;
         status: "open" | "solved";
     } | null;
     messages: ChatMessage[];
+    /** All the visitor's conversations, the latest activity first (0.19). */
+    conversations?: ChatSummary[];
     /** The visitor gave an email already: the messenger stops asking. */
     hasEmail: boolean;
 }
@@ -243,10 +261,15 @@ declare const createApi: (c: Conn) => {
         completed: boolean;
         seconds: number;
     }) => Promise<unknown>;
-    chat: (signal?: AbortSignal) => Promise<ChatThread>;
-    /** A message; `attachments` are upload ids from `uploadChatFile` (then the body may be empty). */
+    /** One chat by id, else the visitor's newest; `conversations` lists them all. */
+    chat: (signal?: AbortSignal, conversation?: string) => Promise<ChatThread>;
+    /**
+     * A message; `attachments` are upload ids from `uploadChatFile` (then the body may be empty). `conversation` is
+     * the chat it answers, or "new" to start one; without it, the running chat or else a new one.
+     */
     sendChat: (m: {
         body: string;
+        conversation?: string;
         email?: string;
         url?: string;
         attachments?: string[];
@@ -281,7 +304,9 @@ type Api = ReturnType<typeof createApi>;
  * - `$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.
  */
 
@@ -301,8 +326,10 @@ interface CancelOffer {
 /** 0.15.0: a second question after an answer ("What would be a fair price?"); no answers means a free text. */
 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
@@ -350,7 +377,71 @@ 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. 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).
+ */
+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. */
 type TourPlacement = "auto" | "top" | "bottom" | "left" | "right";
 /**
@@ -380,6 +471,12 @@ 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. */
 interface OnboardingWait {
@@ -412,10 +509,33 @@ 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[];
 }
@@ -485,15 +605,22 @@ 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;
@@ -501,6 +628,8 @@ type FlowView = {
         step: OnboardingStep;
         done: boolean;
         tour?: OnboardingFlow;
+        opens?: TaskOpens;
+        target?: OnboardingFlow;
     }[];
 } | {
     type: "message";
@@ -528,17 +657,56 @@ 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. */
+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;
 }
 
 /**
@@ -658,7 +826,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.17.0";
+declare const SDK_VERSION = "0.21.0";
 /** One variant of an experiment. `changes` replaces texts that the page marks with `<Text id>`. */
 interface VariantConfig {
     id: VariantId;
@@ -692,6 +860,10 @@ interface RedirectConfig {
 interface CockpitConfig {
     /** The product the public key belongs to. */
     project: string;
+    /** The language the server chose for the words below, like "de" (`lang` on the request). SDK 0.21.0+. */
+    lang?: string;
+    /** The SDK's own words: English source word to translation (see words.ts). Absent for English. SDK 0.21.0+. */
+    words?: Record<string, string>;
     experiments: ExperimentConfig[];
     /** The product's affiliate program: how many days a partner's referral is kept. Missing without a program. */
     referral?: {
@@ -711,6 +883,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+. */
@@ -857,8 +1031,21 @@ interface MRRocketOptions {
     maxQueue?: number;
     /** Log what the SDK does to the console. */
     debug?: boolean;
+    /**
+     * 0.21.0: the language of the SDK's words and of what the server answers, like "de-AT", for an app with its own
+     * language switch. Default: the phone's. `setLocale` does the same from anywhere.
+     */
+    locale?: string;
     /** 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;
     /**
@@ -1003,15 +1190,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;
@@ -1095,6 +1304,11 @@ declare const MRRocketMessenger: ({ client, appearance, options: given }: {
     options?: NativeMessengerOptions;
 }) => react.FunctionComponentElement<Record<string, unknown>> | null;
 
+/** An app with its own language switch says the language here; undefined goes back to the device's. Re-reads the config. */
+declare const setLocale: (locale?: string) => void;
+/** The app's choice, else the phone's (React Native), else the browser's. */
+declare const currentLocale: () => string | undefined;
+
 /**
  * Hides what it wraps in session recordings: its area is painted black on every frame before the frame is stored. Use
  * it for anything private on screen (balances, addresses, messages). Text fields need no wrapper: nothing is recorded
@@ -1209,10 +1423,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. */
@@ -1247,4 +1467,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 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 OnboardingStep, type PaywallConfig, type PaywallOptions, type PaywallPage, type PaywallPlan, type PaywallResult, type RegisterForPushOptions, SDK_VERSION, type SurveyDefinition, type TourPlacement, 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, currentLocale, getMRRocket, setLocale, useCancelFlow, useExpoRouterTracking, useFeedback, useFlag, useFlagVariant, useMRRocket, useMessenger, useNavigationTracking, useOnboarding, usePaywall, usePush, useReview, useText, useVariant };