@mrrocket/sdk 0.8.0 → 0.10.0

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

@@ -1,6 +1,218 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
 
+/**
+ * The SDK's fetch client and the shapes it reads, without React, so the script tag's widgets (src/script) use it too.
+ * `./api` re-exports all of it with the `useApi` hook.
+ */
+type PostStatus = "review" | "planned" | "progress" | "shipped";
+interface FeedbackBoardInfo {
+    id: string;
+    label: string;
+}
+interface FeedbackPost {
+    id: string;
+    title: string;
+    body: string;
+    board: string;
+    status: PostStatus;
+    votes: number;
+    comments: number;
+    voted: boolean;
+    createdAt: string;
+    /** "Lena K.", "Anonymous" or "Team". Missing from servers before SDK 0.6. */
+    author?: string;
+}
+/** The product's public face for the board's header. */
+interface FeedbackProduct {
+    name: string;
+    logo: string | null;
+    /** The domain's favicon, tried when `logo` does not load. Older servers leave it out. */
+    logoFallback?: string | null;
+}
+interface FeedbackList {
+    boards: FeedbackBoardInfo[];
+    posts: FeedbackPost[];
+    product?: FeedbackProduct;
+}
+interface FeedbackRoadmap {
+    /** `review` (Backlog) comes from servers of SDK 0.6 on. */
+    columns: {
+        review?: FeedbackPost[];
+        planned: FeedbackPost[];
+        progress: FeedbackPost[];
+        shipped: FeedbackPost[];
+    };
+}
+interface ChangelogEntry {
+    id: string;
+    title: string;
+    body: string;
+    publishedAt: string;
+}
+interface FeedbackComment {
+    id: string;
+    body: string;
+    author: string;
+    isTeam: boolean;
+    postedAt: string;
+}
+type SurveyQuestionKind = "nps" | "rating" | "single" | "multi" | "text";
+interface SurveyQuestion {
+    key: string;
+    kind: SurveyQuestionKind;
+    title: string;
+    description?: string;
+    required: boolean;
+    options?: string[];
+    scale?: number;
+    low?: string;
+    high?: string;
+    placeholder?: string;
+}
+interface SurveyDefinition {
+    id: string;
+    name: string;
+    type: string;
+    thanks: string;
+    questions: SurveyQuestion[];
+}
+type SurveyAnswer = number | string | string[];
+/** One message of the messenger's chat. "visitor" is the person on the site; the rest come from the product's team. */
+interface ChatMessage {
+    id: string;
+    from: "visitor" | "team" | "ai" | "auto";
+    body: string;
+    at: string;
+    /** Help articles an answer drew on (servers from SDK 0.9 on). */
+    articles?: {
+        id: string;
+        title: string;
+    }[];
+}
+/** A published help article in a list (the messenger's Help tab). */
+interface ArticleSummary {
+    id: string;
+    title: string;
+    collection: string;
+    excerpt: string;
+    updatedAt: string;
+}
+/** A run of text inside an article block. Links are http(s), mailto or tel only. */
+interface ArticleSpan {
+    text: string;
+    href?: string;
+    bold?: boolean;
+    italic?: boolean;
+    code?: boolean;
+}
+/** An article's content as blocks, written with textContent (never parsed as HTML). */
+type ArticleBlock = {
+    type: "h2" | "h3" | "p" | "quote";
+    spans: ArticleSpan[];
+} | {
+    type: "ul" | "ol";
+    items: ArticleSpan[][];
+} | {
+    type: "code";
+    text: string;
+} | {
+    type: "hr";
+};
+interface Article {
+    id: string;
+    title: string;
+    collection: string;
+    updatedAt: string;
+    blocks: ArticleBlock[];
+}
+/** The messenger's look and texts as set in MRRocket › Support › Messenger (servers from SDK 0.9 on). */
+interface MessengerLook {
+    accent: string;
+    theme: "light" | "dark" | "auto";
+    position: "bottom-right" | "bottom-left";
+    title: string;
+    greeting: string;
+    label: string;
+    /** How soon the team usually answers (MRRocket from 0.10; older servers leave it out). */
+    replyTime?: "minutes" | "hours" | "day";
+    /** A round chat button in the app (React Native) too. */
+    appLauncher?: boolean;
+    help: boolean;
+    sound: boolean;
+    preview: boolean;
+    askEmail: boolean;
+}
+/** The visitor's newest chat (open or closed) and its messages. */
+interface ChatThread {
+    conversation: {
+        id: string;
+        status: "open" | "solved";
+    } | null;
+    messages: ChatMessage[];
+    /** The visitor gave an email already: the messenger stops asking. */
+    hasEmail: boolean;
+}
+interface Conn {
+    host: string;
+    apiKey: string;
+    distinctId: string;
+    user?: {
+        id?: string;
+        [key: string]: unknown;
+    };
+}
+/** The small fetch client behind the widgets. Every read takes an AbortSignal so unmounting cancels it. */
+declare const createApi: (c: Conn) => {
+    list: (o: {
+        board?: string;
+        sort?: "top" | "new";
+        q?: string;
+    }, signal?: AbortSignal) => Promise<FeedbackList>;
+    post: (id: string, signal?: AbortSignal) => Promise<FeedbackPost>;
+    roadmap: (signal?: AbortSignal) => Promise<FeedbackRoadmap>;
+    changelog: (signal?: AbortSignal) => Promise<{
+        entries: ChangelogEntry[];
+    }>;
+    submit: (p: {
+        title: string;
+        body?: string;
+        board: string;
+    }) => Promise<FeedbackPost>;
+    vote: (id: string) => Promise<{
+        voted: boolean;
+        votes: number;
+    }>;
+    comments: (id: string, signal?: AbortSignal) => Promise<{
+        comments: FeedbackComment[];
+    }>;
+    comment: (id: string, body: string) => Promise<FeedbackComment>;
+    survey: (url: string, signal?: AbortSignal) => Promise<{
+        survey: SurveyDefinition | null;
+    }>;
+    seen: (id: string) => Promise<unknown>;
+    respond: (id: string, r: {
+        answers: Record<string, SurveyAnswer>;
+        completed: boolean;
+        seconds: number;
+    }) => Promise<unknown>;
+    chat: (signal?: AbortSignal) => Promise<ChatThread>;
+    sendChat: (m: {
+        body: string;
+        email?: string;
+        url?: string;
+    }) => Promise<ChatThread>;
+    articles: (q?: string, signal?: AbortSignal) => Promise<{
+        articles: ArticleSummary[];
+    }>;
+    article: (id: string, signal?: AbortSignal) => Promise<Article>;
+    messengerLook: (signal?: AbortSignal) => Promise<MessengerLook>;
+    rateArticle: (id: string, helpful: boolean) => Promise<{
+        counted: boolean;
+    }>;
+};
+type Api = ReturnType<typeof createApi>;
+
 /**
  * The cancel flow, onboarding and in-app messages (SDK 0.7.0): what MRRocket's config and `GET /api/sdk/inapp` serve,
  * and one controller that decides what shows when and records what the person did. No DOM and no React: the web
@@ -183,7 +395,7 @@ interface FlowsController {
 
 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.8.0";
+declare const SDK_VERSION = "0.10.0";
 /** One variant of an experiment. `changes` replaces texts that the page marks with `<Text id>`. */
 interface VariantConfig {
     id: VariantId;
@@ -322,6 +534,14 @@ interface AppContext {
     locale?: string;
 }
 
+/**
+ * The React Native client without React: the event queue (batched, persisted for offline use, retried with backoff),
+ * the app lifecycle (`$app_open`, `$app_background`, a new session after 30 minutes away), screens, identity and
+ * consent, the cached config for flags and experiments, install attribution from the first open's deep link, and error
+ * capture. Everything the platform gives (storage, AppState, ErrorUtils, device info, fetch) comes in as `deps`, so
+ * it runs in tests without React Native; `platform.ts` builds the real ones.
+ */
+
 /**
  * What the app may send and store.
  * - "anonymous" (default): no id is stored on the device. Events go without a person id until `identify()` (MRRocket
@@ -353,6 +573,14 @@ interface MRRocketOptions {
     debug?: boolean;
     /** Onboarding flows start on their own when the person does their trigger (default true). False: only `startOnboarding()`. */
     onboarding?: boolean;
+    /** Taps go to Heatmaps as clicks on the screen they happened on (default true; `MRRocketProvider` captures them). */
+    heatmaps?: boolean;
+    /**
+     * The person agreed to session recordings (default false; ask them first). Needs `react-native-view-shot` and the
+     * product's recordings switched on in MRRocket. No frame while the keyboard is open; wrap private views in
+     * `<MRRocketMask>`. Change it later with `setReplay`.
+     */
+    replay?: boolean;
 }
 /** AsyncStorage's shape. */
 interface KeyValueStorage {
@@ -379,6 +607,10 @@ interface MRRocketClient {
     track(event: string, props?: Record<string, unknown>): void;
     /** A screen view: a route name ("Settings") or an Expo Router path ("/settings"). */
     screen(name: string, props?: Record<string, unknown>): void;
+    /** A tap at screen points (x, y) for Heatmaps, on the current screen; `MRRocketProvider` calls it. */
+    tap(x: number, y: number): void;
+    /** The person's answer to session recordings (`replay` in the options); false stops and forgets what was not sent. */
+    setReplay(on: boolean): void;
     identify(id: string, props?: Record<string, unknown>): void;
     /** Forgets the signed-in person (sign-out): a new anonymous id and a new session. */
     reset(): void;
@@ -428,6 +660,23 @@ interface MRRocketClient {
     isReady(): boolean;
     getDistinctId(): string;
     getConsent(): NativeConsent;
+    /**
+     * The client of the SDK's widget API (surveys, feedback, the messenger) for the person now: their id, and the name and
+     * email given to identify (or `as`, typed into a widget). Null while the consent is off or without a key.
+     */
+    api(as?: {
+        name?: string;
+        email?: string;
+    }): Api | null;
+    /** The signed-in person (identify): their id, and the name and email given there. Undefined before identify. */
+    getUser(): {
+        id: string;
+        name?: string;
+        email?: string;
+    } | undefined;
+    /** Surveys answered or closed on this device: not shown again (kept on the device only with "persistent"). */
+    isSurveyDone(id: string): boolean;
+    markSurveyDone(id: string): void;
     getConfig(): CockpitConfig | null;
     /** For React: called after every change flags, variants or the consent depend on. Returns the unsubscribe. */
     subscribe(listener: () => void): () => void;
@@ -450,6 +699,90 @@ declare const MRRocketFlows: ({ flows, appearance }: {
     appearance?: NativeAppearance;
 }) => react.FunctionComponentElement<Record<string, unknown>> | null;
 
+interface Palette {
+    accent: string;
+    bg: string;
+    fg: string;
+    muted: string;
+    soft: string;
+    line: string;
+    danger: string;
+}
+/** Asks the person the survey MRRocket picks for them, a few seconds after start and again for a new person. */
+declare const MRRocketSurveys: ({ client, appearance }: {
+    client: MRRocketClient;
+    appearance?: NativeAppearance;
+}) => react.FunctionComponentElement<{
+    survey: SurveyDefinition;
+    api: Api;
+    p: Palette;
+    onDone: () => void;
+}> | null;
+/** Opens the feedback sheet: the top requests with votes, and a form to suggest one. */
+declare const useFeedback: () => {
+    open: () => void;
+    close: () => void;
+};
+interface NativeFeedbackOptions {
+    /** The sheet's title. Default "Feedback". */
+    title?: string;
+}
+declare const MRRocketFeedback: ({ client, appearance, options }: {
+    client: MRRocketClient;
+    appearance?: NativeAppearance;
+    options?: NativeFeedbackOptions;
+}) => react.FunctionComponentElement<{
+    client: MRRocketClient;
+    p: Palette;
+    title: string;
+}> | null;
+type MsgView = "home" | "messages" | "help" | {
+    article: string;
+};
+/** Opens (on Home, a tab or `{ article: id }`), closes or toggles the messenger. */
+declare const useMessenger: () => {
+    open: (view?: MsgView) => void;
+    close: () => void;
+    toggle: () => void;
+};
+interface NativeMessengerOptions {
+    /** A round chat button (default false: open it with `useMessenger().open()` from your own button). */
+    launcher?: boolean;
+    /** Where the chat button sits (default bottom right). */
+    position?: "bottom-right" | "bottom-left";
+    /** Text beside the chat button's icon; empty: the round button. */
+    label?: string;
+    title?: string;
+    /** The big line on Home and the first line of an empty chat. */
+    greeting?: string;
+    /** How soon the team usually answers, said under "Send us a message" and in the chat's head. */
+    replyTime?: "minutes" | "hours" | "day";
+    /** 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). */
+    help?: boolean;
+    /** A banner at the top when an answer arrives while the messenger is closed (default true). */
+    preview?: boolean;
+    /** A light haptic when an answer arrives (default true; needs expo-haptics). */
+    haptics?: boolean;
+}
+declare const MRRocketMessenger: ({ client, appearance, options: given }: {
+    client: MRRocketClient;
+    appearance?: NativeAppearance;
+    options?: NativeMessengerOptions;
+}) => react.FunctionComponentElement<Record<string, unknown>> | null;
+
+/**
+ * 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
+ * while the keyboard is open.
+ *
+ *     <MRRocketMask><Text>{iban}</Text></MRRocketMask>
+ */
+declare const MRRocketMask: ({ children, style }: {
+    children?: ReactNode;
+    style?: unknown;
+}) => react.FunctionComponentElement<Record<string, unknown>>;
 /**
  * The SDK's client outside React (a background task, a store, an API layer): the one the provider made, or a new one.
  * One client per app; a second call returns the first.
@@ -471,8 +804,19 @@ interface MRRocketProviderProps extends Partial<MRRocketOptions> {
      * place `<MRRocketFlows flows={client.flows} />` where you want it.
      */
     flows?: boolean;
-    /** The look of those dialogs: `{ theme: "light" | "dark" | "auto", accent: "#0f766e" }`. */
+    /** The look of those dialogs and the widgets: `{ theme: "light" | "dark" | "auto", accent: "#0f766e" }`. */
     appearance?: NativeAppearance;
+    /** Show the live in-app survey MRRocket picks for the person, a few seconds after start (default true). */
+    surveys?: boolean;
+    /** The chat with your team, opened with `useMessenger().open()`; `{ launcher: true }` adds a round button. False: none. */
+    messenger?: NativeMessengerOptions | false;
+    /** The feedback sheet opened with `useFeedback().open()` (`{ title }`). False: none. */
+    feedback?: NativeFeedbackOptions | false;
+    /**
+     * Taps for Heatmaps (default true). The provider then wraps the app in one `View` with `flex: 1` to see them; false
+     * leaves the app as it is.
+     */
+    heatmaps?: boolean;
     children?: ReactNode;
 }
 /**
@@ -480,7 +824,7 @@ interface MRRocketProviderProps extends Partial<MRRocketOptions> {
  * starts the SDK: lifecycle events, the event queue, flags and experiments, error capture. Changing `consent` later
  * calls setConsent.
  */
-declare const MRRocketProvider: ({ client: given, children, consent, flows, appearance, ...options }: MRRocketProviderProps) => react.FunctionComponentElement<react.ProviderProps<MRRocketClient | null>>;
+declare const MRRocketProvider: ({ client: given, children, consent, flows, appearance, surveys, messenger, feedback, heatmaps, ...options }: MRRocketProviderProps) => react.FunctionComponentElement<react.ProviderProps<MRRocketClient | null>>;
 /**
  * `track`, `screen`, `identify`, `reset`, `setConsent`, `captureError`, `flush`, the visitor id, the consent and whether
  * flags and experiments have loaded.
@@ -491,6 +835,7 @@ declare const useMRRocket: () => {
     identify: (id: string, props?: Record<string, unknown>) => void;
     reset: () => void;
     setConsent: (consent: NativeConsent) => void;
+    setReplay: (on: boolean) => void;
     captureError: (error: unknown) => void;
     flush: () => Promise<void>;
     distinctId: string;
@@ -558,4 +903,4 @@ declare const useExpoRouterTracking: () => void;
  */
 declare const useNavigationTracking: () => (state: unknown) => void;
 
-export { type AppContext, type CancelFlowConfig, type CancelFlowOptions, type CancelFlowResult, type CancelOffer, type CockpitConfig, type FlagConfig, type FlowView, type InAppMessage, type KeyValueStorage, type MRRocketClient, MRRocketFlows, type MRRocketOptions, MRRocketProvider, type MRRocketProviderProps, type NativeAppearance, type NativeConsent, type NativePushResult, type NativePushStatus, type OnboardingFlow, type OnboardingStep, type RegisterForPushOptions, SDK_VERSION, type VariantId, activeRouteName, createMRRocket, getMRRocket, useCancelFlow, useExpoRouterTracking, useFlag, useFlagVariant, useMRRocket, useNavigationTracking, useOnboarding, usePush, useText, useVariant };
+export { type AppContext, type CancelFlowConfig, type CancelFlowOptions, type CancelFlowResult, type CancelOffer, type ChatMessage, type ChatThread, type CockpitConfig, type FeedbackPost, type FlagConfig, type FlowView, 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 OnboardingFlow, type OnboardingStep, type RegisterForPushOptions, SDK_VERSION, type SurveyDefinition, type VariantId, activeRouteName, createMRRocket, getMRRocket, useCancelFlow, useExpoRouterTracking, useFeedback, useFlag, useFlagVariant, useMRRocket, useMessenger, useNavigationTracking, useOnboarding, usePush, useText, useVariant };