@mrrocket/sdk 0.14.0 → 0.16.0

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

@@ -1,10 +1,6 @@
 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;
@@ -78,6 +74,28 @@ interface SurveyDefinition {
     questions: SurveyQuestion[];
 }
 type SurveyAnswer = number | string | string[];
+/** A file in the messenger's chat: a screenshot, a photo or a PDF the visitor sent (servers from SDK 0.15 on). */
+interface ChatFile {
+    /** From an upload: the signed id a message sends. In a message: the file's own id (`attachmentUrl` reads it). */
+    id: string;
+    name: string;
+    type: "image/png" | "image/jpeg" | "image/webp" | "image/gif" | "application/pdf";
+    /** Bytes. */
+    size: number;
+}
+/** A file to upload: a Blob or File on the web, the image picker's `{ uri, name, type }` in React Native. */
+type ChatUpload = Blob | {
+    uri: string;
+    name: string;
+    type: string;
+};
+/** The bug context a visitor message carries; the server fills browser and system from the user agent when left out. */
+interface ChatContext {
+    browser?: string;
+    os?: string;
+    /** "1440×900". */
+    viewport?: 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;
@@ -89,6 +107,8 @@ interface ChatMessage {
         id: string;
         title: string;
     }[];
+    /** Files sent with it (servers from SDK 0.15 on). */
+    attachments?: ChatFile[];
 }
 /** A published help article in a list (the messenger's Help tab). */
 interface ArticleSummary {
@@ -126,11 +146,17 @@ interface Article {
     updatedAt: string;
     blocks: ArticleBlock[];
 }
+/** Where the chat button sits: a corner, the middle of the top or bottom edge, or the middle of a side. */
+type MessengerPosition = "top-left" | "top-center" | "top-right" | "middle-left" | "middle-right" | "bottom-left" | "bottom-center" | "bottom-right";
+/** How round the messenger is. */
+type MessengerCorners = "round" | "soft" | "square";
 /** The messenger's look and texts as set in MRRocket › Support › Messenger (servers from SDK 0.9 on). */
 interface MessengerLook {
     accent: string;
+    /** Up to two more colors blended into Home's background glow (MRRocket from 0.16; older servers leave it out). */
+    glow?: string[];
     theme: "light" | "dark" | "auto";
-    position: "bottom-right" | "bottom-left";
+    position: MessengerPosition;
     title: string;
     greeting: string;
     label: string;
@@ -142,6 +168,16 @@ interface MessengerLook {
     sound: boolean;
     preview: boolean;
     askEmail: boolean;
+    /** How round panel, bubbles, cards and fields are (MRRocket from 0.15; older servers leave it out: round). */
+    corners?: MessengerCorners;
+    /** The site's own font (the default) or the system's (web only; from 0.15). */
+    font?: "site" | "system";
+    /** Home's top: plain like the rest, or in the accent color (from 0.15; older servers leave it out: plain). */
+    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. */
+    logo?: string;
 }
 /** The visitor's newest chat (open or closed) and its messages. */
 interface ChatThread {
@@ -161,6 +197,11 @@ interface Conn {
         id?: string;
         [key: string]: unknown;
     };
+    /**
+     * The identity hash of `distinctId` (0.16.0, see identity.ts), sent with every request that names the visitor: a
+     * JSON field next to `distinctId`, a query parameter, a form field. Leave it out for any other id.
+     */
+    userHash?: string;
 }
 /** The small fetch client behind the widgets. Every read takes an AbortSignal so unmounting cancels it. */
 declare const createApi: (c: Conn) => {
@@ -197,11 +238,18 @@ declare const createApi: (c: Conn) => {
         seconds: number;
     }) => Promise<unknown>;
     chat: (signal?: AbortSignal) => Promise<ChatThread>;
+    /** A message; `attachments` are upload ids from `uploadChatFile` (then the body may be empty). */
     sendChat: (m: {
         body: string;
         email?: string;
         url?: string;
+        attachments?: string[];
+        context?: ChatContext;
     }) => Promise<ChatThread>;
+    /** Uploads one picked file for the next message (pictures and PDFs, at most 10 MB); answers its upload id. */
+    uploadChatFile: (file: ChatUpload, signal?: AbortSignal) => Promise<ChatFile>;
+    /** Where a sent file of this visitor's chat is read (an image's src, a PDF's link). */
+    attachmentUrl: (id: string) => string;
     articles: (q?: string, signal?: AbortSignal) => Promise<{
         articles: ArticleSummary[];
     }>;
@@ -243,6 +291,29 @@ interface CancelOffer {
     plan?: string;
     planName?: string;
 }
+/** 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. */
+    answers: string[];
+}
+/**
+ * 0.15.0: a different offer for some customers of one answer. Every condition that is set must hold; the first rule
+ * that matches wins, else the answer's own offer. `offer: null` means no offer (straight to the confirmation).
+ */
+interface CancelRule {
+    when: {
+        /** The follow-up's answer, as written. */
+        answer?: string;
+        /** The customer's plan: its id or name as MRRocket knows it from the payment provider (any of a list). */
+        plan?: string | string[];
+        /** A customer for fewer than this many months. */
+        tenureUnder?: number;
+        /** A customer for at least this many months. */
+        tenureOver?: number;
+    };
+    offer: CancelOffer | null;
+}
 /** The product's live cancel flow (MRRocket › Churn › Cancel flow). */
 interface CancelFlowConfig {
     /** Grows with every publish. */
@@ -255,6 +326,12 @@ interface CancelFlowConfig {
     }[];
     /** The offer per answer id. */
     offers: Record<string, CancelOffer>;
+    /** 0.15.0: the follow-up question per answer id. */
+    followUps?: Record<string, CancelFollowUp>;
+    /** 0.15.0: the rules per answer id, checked in order before its offer. */
+    rules?: Record<string, CancelRule[]>;
+    /** 0.15.0: what one answer offers after its first offer was declined. */
+    second?: Record<string, CancelOffer>;
     confirm: {
         title: string;
         body: string;
@@ -326,6 +403,8 @@ interface CancelFlowResult {
     outcome: "cancelled" | "saved" | "kept";
     reason?: string;
     reasonLabel?: string;
+    /** 0.15.0: the answer to the follow-up question. */
+    answer?: string;
     offer?: CancelOffer;
     /** What the customer wrote on the confirmation, if anything. */
     comment?: string;
@@ -344,6 +423,10 @@ interface CancelFlowOptions {
         currency: string;
         interval?: "month" | "year";
     };
+    /** 0.15.0: the customer's plan (its id or name in your billing), for offers that depend on it. */
+    plan?: string;
+    /** 0.15.0: since when they pay (a date, ISO string or ms), for offers that depend on how long. */
+    customerSince?: Date | string | number;
     /** The customer confirmed: cancel the subscription in your code. Throwing keeps the dialog open with an error. */
     onCancel?: (result: CancelFlowResult) => unknown;
     /** The customer took an offer: apply it in your code (coupon, pause, plan change). Throwing keeps the dialog open. */
@@ -354,11 +437,16 @@ interface CancelFlowOptions {
 /** What a renderer draws. */
 type FlowView = {
     type: "cancel";
-    screen: "survey" | "offer" | "confirm";
+    screen: "survey" | "followup" | "offer" | "confirm";
     flow: CancelFlowConfig;
     /** The answer picked on the survey. */
     reason?: string;
+    /** 0.15.0: the follow-up question on its screen, and its answer so far. */
+    followUp?: CancelFollowUp;
+    answer?: string;
     offer?: CancelOffer;
+    /** 0.15.0: 2 for the offer after a declined one. */
+    round?: 1 | 2;
     price?: CancelFlowOptions["price"];
     busy: boolean;
     error?: string;
@@ -395,8 +483,10 @@ interface FlowsController {
     view(): FlowView | null;
     subscribe(listener: () => void): () => void;
     /** `accept(comment)`: a "Talk to us" offer sends what the customer wrote with it. */
+    /** `answer(text)`: the follow-up's choice or free text (0.15.0); `next()` moves on from the survey and the follow-up. */
     cancel: {
         pick(reason: string): void;
+        answer(text: string): void;
         next(): void;
         accept(comment?: string): void;
         decline(): void;
@@ -531,7 +621,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.14.0";
+declare const SDK_VERSION = "0.16.0";
 /** One variant of an experiment. `changes` replaces texts that the page marks with `<Text id>`. */
 interface VariantConfig {
     id: VariantId;
@@ -672,6 +762,27 @@ interface AppContext {
     locale?: string;
 }
 
+/**
+ * Identity verification (0.16.0), the browser and app side. After `identify(id)` the SDK's id is your app's own user
+ * id, and that id is no secret (a Clerk id shows in URLs and logs), so on its own it proves nothing: anyone who knows it
+ * could read that person's support chat or post as them. Your server signs the id with the product's server key
+ * (`userHash(user.id)` from `@mrrocket/sdk/next/server`) and you hand the result to `identify(id, props, { hash })`.
+ * From then on every request for that id carries it as `userHash` (a JSON field, a query parameter or a form field), and
+ * MRRocket checks it.
+ *
+ * The hash belongs to one id: it is forgotten on `reset()` (sign-out) and when `identify` is called for another id
+ * without a hash, so it never goes out with someone else's id (MRRocket refuses a hash that does not match with 401).
+ * Shared by the Next.js provider, the script tag and React Native: no React, no browser APIs.
+ */
+/** The third argument of `identify`. */
+interface IdentifyOptions {
+    /**
+     * The id signed by your server: `await userHash(user.id)` from `@mrrocket/sdk/next/server` (or the same HMAC in any
+     * language). Needed when MRRocket › Settings › Products › Sign-in › "Only signed users" is on.
+     */
+    hash?: 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
@@ -733,6 +844,13 @@ interface RegisterForPushOptions {
     projectId?: string;
 }
 type NativePushStatus = "registered" | "denied" | "not-asked" | "unavailable" | "not-signed-in" | "error";
+/**
+ * 0.16.0, what `requestReview()` did: "requested" the store's rating dialog was asked for (the store decides whether it
+ * shows; Apple shows it at most three times a year); "not-now" no live review request may ask this person now (not a
+ * customer, asked in the last 120 days, no request live); "unavailable" the device has no dialog or `expo-store-review`
+ * is not installed; "not-signed-in" call `identify` first.
+ */
+type NativeReviewResult = "requested" | "not-now" | "unavailable" | "not-signed-in";
 interface NativePushResult {
     status: NativePushStatus;
     /** The Expo push token, once registered. */
@@ -749,8 +867,14 @@ interface MRRocketClient {
     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. */
+    /**
+     * Who the person is once they sign in. `{ hash }` (0.16.0) is the id signed by your backend (`userHash(id)` from
+     * `@mrrocket/sdk/next/server`, or the same HMAC in any language), fetched after sign-in; sent with every request for
+     * that id so MRRocket knows it is really them. Needed with "Only signed users" (MRRocket › Settings › Products ›
+     * Sign-in). Not stored on the device: call identify with it on every start.
+     */
+    identify(id: string, props?: Record<string, unknown>, options?: IdentifyOptions): void;
+    /** Forgets the signed-in person and their hash (sign-out): a new anonymous id and a new session. */
     reset(): void;
     setConsent(consent: NativeConsent): void;
     captureError(error: unknown): void;
@@ -797,6 +921,12 @@ interface MRRocketClient {
     registerForPush(options?: RegisterForPushOptions): Promise<NativePushResult>;
     /** Removes this device's token for the signed-in person (sign-out does it on its own in `reset`). */
     unregisterForPush(): Promise<boolean>;
+    /**
+     * 0.16.0: asks for a store review at the moment your app picked (the trigger of a review request in MRRocket ›
+     * Reviews › Requests). MRRocket says whether this signed-in person may be asked now; if so the App Store's or Google
+     * Play's own rating dialog opens (needs `expo-store-review`) and MRRocket counts the request. Never filtered by mood.
+     */
+    requestReview(): Promise<NativeReviewResult>;
     /** The cancel flow, onboarding and messages for a renderer (the provider's, or your own). */
     flows: FlowsController;
     /** Sends what is queued now. */
@@ -895,15 +1025,22 @@ declare const useMessenger: () => {
 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";
+    /** Where the chat button sits: a corner, the middle of the top or bottom edge, or the middle of a side (default bottom right). */
+    position?: MessengerPosition;
     /** Text beside the chat button's icon; empty: the round button. */
     label?: string;
+    /** The name beside the team's mark at the top of Home (MRRocket fills in the product's name). */
     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. */
+    /** How soon the team usually answers, said on Home. */
     replyTime?: "minutes" | "hours" | "day";
+    /** How round bubbles, cards and fields are (default round; the sheet itself keeps the system's corners). */
+    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). */
+    logo?: 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). */
@@ -979,7 +1116,7 @@ declare const MRRocketProvider: ({ client: given, children, consent, flows, appe
 declare const useMRRocket: () => {
     track: (event: string, props?: Record<string, unknown>) => void;
     screen: (name: string, props?: Record<string, unknown>) => void;
-    identify: (id: string, props?: Record<string, unknown>) => void;
+    identify: (id: string, props?: Record<string, unknown>, options?: IdentifyOptions) => void;
     reset: () => void;
     setConsent: (consent: NativeConsent) => void;
     setReplay: (on: boolean) => void;
@@ -1022,6 +1159,17 @@ declare const usePush: () => {
 declare const usePaywall: () => {
     open: MRRocketClient["openPaywall"];
 };
+/**
+ * 0.16.0: store reviews from a review request in MRRocket › Reviews › Requests (needs `expo-store-review`). Call
+ * `request()` at the moment the request names (after the third finished challenge, a 7-day streak …): MRRocket says
+ * whether this signed-in person may be asked now, and the App Store's or Google Play's own rating dialog opens.
+ *
+ *     const review = useReview();
+ *     if (challengesDone === 3) void review.request();
+ */
+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;
@@ -1060,4 +1208,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 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 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, 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 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 };