@mrrocket/sdk 0.15.0 → 0.17.0

package/dist/flows.d.ts

@@ -11,13 +11,16 @@
  *   `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.
  * - `$inapp` `{message, journey, action: "shown" | "clicked" | "dismissed"}`; the journey moves the person on.
  */
 import type { CockpitConfig } from "./core.js";
 export declare const CANCEL_EVENT = "$cancel_flow";
 export declare const ONBOARDING_EVENT = "$onboarding";
 export declare const INAPP_EVENT = "$inapp";
+/** 0.16.0: the app asked the store's rating dialog for a review request (or found none on the device). */
+export declare const REVIEW_EVENT = "$review_prompt";
 export type CancelOfferKind = "discount" | "pause" | "downgrade" | "contact";
 /** What one answer of the survey offers before the confirmation. An answer without one goes straight to it. */
 export interface CancelOffer {
@@ -84,6 +87,17 @@ export interface CancelFlowConfig {
     offersFor: "business";
 }
 export type OnboardingStepKind = "tour" | "checklist" | "modal";
+/** 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;
@@ -94,6 +108,14 @@ 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;
 }
 /** A pause in a flow (0.11.0): the next step shows this long after the one before was done. */
 export interface OnboardingWait {
@@ -119,9 +141,15 @@ 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. */
+    audience?: "signed_in";
     /** What every version shows: with `nodes`, only the in-app steps before the first wait or condition. */
     steps: OnboardingStep[];
     /** 0.11.0+: the whole flow with its waits and conditions. Read instead of `steps` when it is there. */
@@ -155,6 +183,14 @@ 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.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.
+     */
+    review?: {
+        campaign: string;
+        store: string;
+    };
 }
 export interface CancelFlowResult {
     /** "cancelled": confirmed; "saved": took the offer; "kept": closed the dialog without cancelling. */
@@ -218,12 +254,15 @@ export type FlowView = {
     index: number;
     total: number;
     last: boolean;
-} | {
+}
+/** `tour`: the tour the item starts (0.17.0), when the config has it. */
+ | {
     type: "checklist";
     flow: OnboardingFlow;
     items: {
         step: OnboardingStep;
         done: boolean;
+        tour?: OnboardingFlow;
     }[];
 } | {
     type: "message";
@@ -272,10 +311,12 @@ 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. */
     onboarding: {
         next(): void;
         check(stepId: string): void;
         dismiss(): void;
+        startTour(stepId: string): boolean;
     };
     message: {
         click(): void;
@@ -290,6 +331,21 @@ 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.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`. */

package/dist/flows.js

@@ -2,6 +2,7 @@
 var CANCEL_EVENT = "$cancel_flow";
 var ONBOARDING_EVENT = "$onboarding";
 var INAPP_EVENT = "$inapp";
+var REVIEW_EVENT = "$review_prompt";
 var PLAIN_CANCEL = {
   version: 0,
   question: "",
@@ -21,6 +22,26 @@ var matchesTrigger = (trigger, event) => {
   return t === e || SIGNUP.has(t) && SIGNUP.has(e);
 };
 var startsOnLoad = (trigger) => /^(first (launch|visit|open|session|login|sign ?in|app open)|app (opened|launched)|on load|every visit|always)?$/i.test(trigger.trim());
+var FROM_CHECKLIST = "From a checklist";
+var isPageTrigger = (trigger) => trigger.trim().startsWith("/");
+var manual = (trigger) => eventSlug(trigger) === "from_a_checklist";
+var videoEmbed = (url) => {
+  const u = (url ?? "").trim();
+  if (!/^https?:\/\//i.test(u)) return null;
+  let m = u.match(/^https?:\/\/(?:www\.|m\.)?(?:youtube\.com\/(?:watch\?(?:.*&)?v=|embed\/|shorts\/|live\/)|youtu\.be\/|youtube-nocookie\.com\/embed\/)([\w-]{6,20})/i);
+  if (m) return { kind: "iframe", src: `https://www.youtube-nocookie.com/embed/${m[1]}?rel=0` };
+  m = u.match(/^https?:\/\/(?:www\.|player\.)?vimeo\.com\/(?:video\/)?(\d{4,12})/i);
+  if (m) return { kind: "iframe", src: `https://player.vimeo.com/video/${m[1]}?dnt=1` };
+  m = u.match(/^https?:\/\/(?:www\.)?loom\.com\/(?:share|embed)\/([\w-]{8,64})/i);
+  if (m) return { kind: "iframe", src: `https://www.loom.com/embed/${m[1]}` };
+  if (/\.(mp4|webm|mov|m4v)(\?|#|$)/i.test(u) || /\/media\/uploads\//.test(u)) return { kind: "file", src: u };
+  return null;
+};
+var mediaOf = (step) => {
+  const m = step.media;
+  if (!m || m.kind !== "image" && m.kind !== "video" || !/^https?:\/\//i.test(m.url ?? "")) return void 0;
+  return m.kind === "video" && !videoEmbed(m.url) ? void 0 : m;
+};
 var runId = () => `cf_${Math.random().toString(36).slice(2, 10)}${Date.now().toString(36)}`;
 var discounted = (amount, percent) => Math.round(amount * (1 - percent / 100) * 100) / 100;
 var money = (amount, currency) => {
@@ -68,6 +89,7 @@ var createFlows = (env) => {
   const seenEvents = /* @__PURE__ */ new Set();
   const now = () => env.now?.() ?? Date.now();
   let timer = null;
+  let returnTo = null;
   const flows = () => config?.onboarding ?? [];
   const flowById = (id) => id ? flows().find((f) => f.id === id) : void 0;
   const prog = (id) => {
@@ -205,7 +227,14 @@ var createFlows = (env) => {
           shown.add(`s:${i.id}`);
           env.track(ONBOARDING_EVENT, { flow: flow.id, step: i.id, kind: "checklist", action: "shown" });
         }
-      return { type: "checklist", flow, items: items.map((s) => ({ step: s, done: p.done.has(s.id) })) };
+      return {
+        type: "checklist",
+        flow,
+        items: items.map((s) => {
+          const tour = s.startsTour && s.startsTour !== flow.id ? flowById(s.startsTour) : void 0;
+          return { step: s, done: p.done.has(s.id), ...tour && nodesOf(tour).length ? { tour } : {} };
+        })
+      };
     }
     if (!shown.has(`s:${step.id}`)) {
       shown.add(`s:${step.id}`);
@@ -239,7 +268,28 @@ var createFlows = (env) => {
     }
     const ob = onboardingView();
     if (ob) return ob;
-    if (active && !holding) active = null;
+    if (active && !holding) {
+      const back = returnTo;
+      const ended = active;
+      returnTo = null;
+      active = null;
+      const list = back ? flowById(back.flow) : void 0;
+      if (back && list) {
+        const item = stepsIn(nodesOf(list)).find((s) => s.id === back.step);
+        const p = prog(list.id);
+        if (item && !item.event && !progress.get(ended)?.dismissed && !p.done.has(item.id)) {
+          markDone(p, item.id);
+          record({ flow: list.id, step: item.id, kind: "checklist", action: "completed" });
+        }
+        active = list.id;
+        const again = onboardingView();
+        if (again) return again;
+        if (!holding) active = null;
+      } else if (known) {
+        const after = flowById(ended)?.trigger;
+        Promise.resolve().then(() => autoStart(after));
+      }
+    }
     const m = messages.find((x) => !handled.has(x.id));
     return m ? { type: "message", message: m } : null;
   };
@@ -264,10 +314,15 @@ var createFlows = (env) => {
     emit();
     return true;
   };
-  const autoStart = () => {
+  const allowed = (f) => f.audience !== "signed_in" || !!env.personId();
+  const autoStart = (after) => {
     if (!auto || active || !known) return;
     if (!env.personId() && !env.storage?.()) return;
-    const next = flows().find((f) => startsOnLoad(f.trigger) && nodesOf(f).length && !finished(f));
+    const path = env.path?.();
+    const same = after && !manual(after) ? eventSlug(after) : "";
+    const next = flows().find(
+      (f) => (isPageTrigger(f.trigger) ? path !== void 0 && pageMatches(f.trigger, path) : startsOnLoad(f.trigger) || !!same && eventSlug(f.trigger) === same) && allowed(f) && nodesOf(f).length && !finished(f)
+    );
     if (next) start(next);
   };
   const refresh = () => {
@@ -277,6 +332,7 @@ var createFlows = (env) => {
       seenEvents.clear();
       handled.clear();
       active = null;
+      returnTo = null;
       loadedFor = void 0;
     }
     progressFor = pid;
@@ -386,6 +442,7 @@ var createFlows = (env) => {
     },
     refresh,
     onEvent: (name) => {
+      if (name === "$pageview") autoStart();
       if (!name || name.startsWith("$")) return;
       const slug = eventSlug(name);
       const fresh = !!slug && !seenEvents.has(slug);
@@ -406,12 +463,12 @@ var createFlows = (env) => {
         emit();
       } else if (fresh) save();
       if (!auto || !env.personId() && !env.storage?.()) return;
-      const next = flows().find((f) => nodesOf(f).length && matchesTrigger(f.trigger, name) && !finished(f));
+      const next = flows().find((f) => nodesOf(f).length && !manual(f.trigger) && matchesTrigger(f.trigger, name) && allowed(f) && !finished(f));
       if (next) start(next);
     },
     openCancelFlow,
     startOnboarding: (id) => {
-      const f = id ? flowById(id) : flows().find((x) => nodesOf(x).length && !finished(x));
+      const f = id ? flowById(id) : flows().find((x) => nodesOf(x).length && !manual(x.trigger) && !finished(x));
       if (!f || !nodesOf(f).length) return false;
       const p = prog(f.id);
       p.dismissed = false;
@@ -507,6 +564,8 @@ var createFlows = (env) => {
         env.track(ONBOARDING_EVENT, { flow: v.flow.id, step: v.step.id, kind: v.step.kind, action: "completed" });
         save();
         emit();
+        const url = v.step.kind === "modal" ? safeUrl(v.step.url) : void 0;
+        if (url) env.openUrl?.(url);
       },
       check: (stepId) => {
         const v = onboardingView();
@@ -523,9 +582,26 @@ var createFlows = (env) => {
         if (!v || v.type !== "step" && v.type !== "checklist") return;
         prog(v.flow.id).dismissed = true;
         env.track(ONBOARDING_EVENT, { flow: v.flow.id, ...v.type === "step" ? { step: v.step.id } : {}, action: "dismissed" });
-        active = null;
+        active = returnTo && returnTo.flow !== v.flow.id && flowById(returnTo.flow) ? returnTo.flow : null;
+        returnTo = null;
+        save();
+        emit();
+      },
+      startTour: (stepId) => {
+        const v = onboardingView();
+        if (v?.type !== "checklist") return false;
+        const tour = v.items.find((i) => i.step.id === stepId)?.tour;
+        if (!tour) return false;
+        const p = prog(tour.id);
+        p.done.clear();
+        p.at.clear();
+        p.dismissed = false;
+        returnTo = { flow: v.flow.id, step: stepId };
+        active = tour.id;
+        env.track(ONBOARDING_EVENT, { flow: tour.id, action: "started", from: v.flow.id });
         save();
         emit();
+        return true;
       }
     },
     message: {
@@ -551,13 +627,17 @@ var createFlows = (env) => {
 };
 export {
   CANCEL_EVENT,
+  FROM_CHECKLIST,
   INAPP_EVENT,
   ONBOARDING_EVENT,
   PLAIN_CANCEL,
+  REVIEW_EVENT,
   createFlows,
   discounted,
   eventSlug,
+  isPageTrigger,
   matchesTrigger,
+  mediaOf,
   money,
   monthsSince,
   nodesOf,
@@ -567,6 +647,7 @@ export {
   runId,
   safeUrl,
   startsOnLoad,
+  videoEmbed,
   waitMs
 };
 //# sourceMappingURL=flows.js.map