@mediansh/widget 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -79,6 +79,18 @@ type MedianSupportOptions = {
      * first reply asking. Pass `false` and none of it is read at all.
      */
     telemetry?: boolean;
+    /**
+     * Whether the agent may take a picture of this page when it asks to see
+     * it. Drawn from the page itself rather than recorded off the screen, so
+     * nobody is asked for permission to share anything, and only when the
+     * agent asks: it says it is taking a look, and the picture lands in the
+     * thread where the visitor can see what was sent. On by default. Pass
+     * `false` on a page showing somebody else's data and the agent is told no
+     * picture is coming.
+     *
+     * Never the panel itself or anything else Median renders.
+     */
+    screenshot?: boolean;
     /**
      * Take questions from signed in people only.
      *
@@ -134,6 +146,17 @@ type MedianSupportOptions = {
      * either side saying no is enough to keep the card away.
      */
     messagePreview?: boolean;
+    /**
+     * Put the unread count in the tab's title, as `(1) Your page`, while a
+     * reply is waiting. On by default: it is the one part of your page a
+     * visitor can see from another tab. Your own title is kept and put back
+     * once the reply has been read.
+     *
+     *   <MedianSupport apiKey="median_pk_..." titleCount={false} />
+     *
+     * Pass `false` and the title is never touched.
+     */
+    titleCount?: boolean;
     /**
      * Watch what goes wrong on the page, so a bug report arrives with the
      * error already attached instead of after four messages of asking.
@@ -260,19 +283,26 @@ type MedianSupportProps = MedianSupportOptions & ({
 declare function MedianSupport(props: MedianSupportProps): react.JSX.Element;
 
 /**
- * What a mounted widget hands back: the two things a host without React has
- * no re-render to do for them. Everything else goes through `medianSupport`,
- * same as anywhere.
+ * What a mounted component hands back: the two things a host without React
+ * has no re-render to do for them. Everything else goes through the
+ * component's own control, same as anywhere.
  */
-type MedianSupportInstance = {
+type MedianMountInstance<Options> = {
     /**
      * Change any option after mount. Only the keys passed change, so
      * `update({ user })` when somebody signs in leaves the rest alone.
      */
-    update: (options: Partial<MedianSupportProps>) => void;
-    /** Take the widget off the page: panel, launcher, connection, all of it. */
+    update: (options: Partial<Options>) => void;
+    /** Take it off the page: the component, its container, its connection. */
     unmount: () => void;
 };
+
+/**
+ * What a mounted widget hands back: the two things a host without React has
+ * no re-render to do for them. Everything else goes through `medianSupport`,
+ * same as anywhere.
+ */
+type MedianSupportInstance = MedianMountInstance<MedianSupportProps>;
 /**
  * The same widget, for a page that has never heard of React: Vue, Svelte,
  * Rails, a script on plain HTML. One call puts the launcher in the corner,
@@ -293,6 +323,43 @@ type MedianSupportInstance = {
  */
 declare function mountMedianSupport(options: MedianSupportProps): MedianSupportInstance;
 
+/**
+ * Every prop the widget takes, unchanged. The modal is the widget in a
+ * different place, not a different widget.
+ */
+type MedianSupportModalProps = MedianSupportProps;
+/**
+ * The support widget as a modal: the same button in the corner, and a panel
+ * that opens in the middle of the screen over a scrim rather than out of
+ * the corner.
+ *
+ *   <MedianSupportModal apiKey="median_pk_..." />
+ *
+ * Everything else is the widget's. Same props, same thread, same inbox on
+ * the other side, same `useMedianSupport()` to open it from your own nav,
+ * same sheet on a phone. Pick this for a site where a conversation deserves
+ * the room, or where a panel floating over the page would be in the way of
+ * the page.
+ *
+ * One or the other. Mounting both shares one open state, and the console
+ * says so.
+ */
+declare function MedianSupportModal(props: MedianSupportModalProps): react.JSX.Element;
+
+type MedianSupportModalInstance = MedianMountInstance<MedianSupportModalProps>;
+/**
+ * The modal, for a page that has never heard of React: Vue, Svelte, Rails,
+ * a script on plain HTML.
+ *
+ *   const support = mountMedianSupportModal({ apiKey: "median_pk_..." });
+ *
+ * It takes the component's props as one options object, and the rest of the
+ * SDK does not know the difference: `medianSupport.open()` opens this modal
+ * exactly as it opens the component. `update` and `unmount` are the same two
+ * `mountMedianSupport` hands back.
+ */
+declare function mountMedianSupportModal(options: MedianSupportModalProps): MedianSupportModalInstance;
+
 /**
  * Filing the crash the visitor is looking at.
  *
@@ -334,6 +401,12 @@ type MedianErrorReportOptions = {
     attach?: Record<string, unknown>;
     /** Whether the report carries what the browser knows. On by default. */
     telemetry?: boolean;
+    /**
+     * Whether the report carries a picture of the screen it was filed from. On
+     * by default: what a crash screen actually looks like is the one thing the
+     * stack does not say. Pass `false` and no picture is taken.
+     */
+    screenshot?: boolean;
 };
 /** Where the report went, or why it did not go. */
 type MedianErrorReportOutcome = {
@@ -358,12 +431,14 @@ declare function useCanReportError(): boolean;
 /**
  * The widget from anywhere, React or not: the same shape the hook hands
  * back, for a plain `onclick` or a shortcut listener that never sees a
- * component. `isOpen` reads live but does not re-render anything; the hook
- * is for that.
+ * component. `isOpen` and `unreadCount` read live but do not re-render
+ * anything; the hook is for that.
  */
 declare const medianSupport: {
     /** What the panel is doing right now. */
     readonly isOpen: boolean;
+    /** Replies the visitor has not read. Zero while nothing is mounted. */
+    readonly unreadCount: number;
     open(): void;
     close(): void;
     toggle(): void;
@@ -396,6 +471,13 @@ declare const medianSupport: {
 type MedianSupportControl = {
     /** Whether the panel is open. */
     isOpen: boolean;
+    /**
+     * Replies the visitor has not read: the same count the closed button
+     * wears and the tab's title carries. For a badge on a button of your own,
+     * on a page where the launcher is hidden. Zero while the panel is open,
+     * once it has been looked at, and whenever no panel is mounted.
+     */
+    unreadCount: number;
     open: () => void;
     close: () => void;
     toggle: () => void;
@@ -411,10 +493,15 @@ type MedianSupportControl = {
  *
  *   const support = useMedianSupport();
  *
- *   <button onClick={support.open}>Contact us</button>
+ *   <button onClick={support.open}>
+ *     Contact us
+ *     {support.unreadCount > 0 && <span>{support.unreadCount}</span>}
+ *   </button>
  *
  * `isOpen` follows the panel however it was opened, so a trigger can render
  * itself as pressed, or step out of the way while the panel is up.
+ * `unreadCount` follows the thread, so the trigger can say a reply is
+ * waiting where the corner button would have.
  */
 declare function useMedianSupport(): MedianSupportControl;
 
@@ -459,6 +546,17 @@ type MedianFeedbackOptions = {
      * read at all.
      */
     telemetry?: boolean;
+    /**
+     * Whether a note carries a picture of the page it was written on, drawn
+     * from the page itself rather than recorded off the screen, so nobody is
+     * asked for permission to share anything. On by default: a bug report with
+     * the screen on it is one nobody has to describe. Pass `false` and no
+     * picture is taken.
+     *
+     * The panel itself is never in the picture, and neither is anything else
+     * Median renders.
+     */
+    screenshot?: boolean;
     /**
      * Watch what goes wrong on the page, so a bug filed from a note arrives
      * with the error already attached. The same switch `<MedianSupport>`
@@ -522,8 +620,8 @@ type MedianFeedbackMountOptions = Omit<MedianFeedbackOptions, "children"> & ({
  *     <MenuItem>Share feedback</MenuItem>
  *   </MedianFeedback>
  *
- * The page they were on rides along on its own, which the line under the
- * title says plainly.
+ * The page they were on rides along on its own, and so does a picture of it.
+ * `screenshot={false}` leaves the picture behind.
  *
  * It brings its own connection, so it works on pages that have never heard
  * of Convex, and it is independent of `<MedianSupport>`: mount either, both,
@@ -537,15 +635,7 @@ declare function MedianFeedback(props: MedianFeedbackProps): react.JSX.Element;
  * no re-render to do for them. Opening and closing go through
  * `medianFeedback`, same as anywhere.
  */
-type MedianFeedbackInstance = {
-    /**
-     * Change any option after mount. Only the keys passed change, so
-     * `update({ user })` when somebody signs in leaves the rest alone.
-     */
-    update: (options: Partial<MedianFeedbackProps>) => void;
-    /** Take the panel off the page. */
-    unmount: () => void;
-};
+type MedianFeedbackInstance = MedianMountInstance<MedianFeedbackProps>;
 /**
  * The same panel, for a page that has never heard of React: Vue, Svelte,
  * Rails, a script on plain HTML.
@@ -587,4 +677,300 @@ type MedianFeedbackControl = {
  */
 declare function useMedianFeedback(): MedianFeedbackControl;
 
-export { type MedianDiagnostics, type MedianErrorReportOptions, type MedianErrorReportOutcome, MedianFeedback, type MedianFeedbackControl, type MedianFeedbackInstance, type MedianFeedbackProps, MedianSupport, type MedianSupportControl, type MedianSupportInstance, type MedianSupportProps, type MedianUser, type MedianDiagnostics as PortalDiagnostics, type MedianErrorReportOptions as PortalErrorReportOptions, type MedianErrorReportOutcome as PortalErrorReportOutcome, MedianFeedback as PortalFeedback, type MedianFeedbackControl as PortalFeedbackControl, type MedianFeedbackInstance as PortalFeedbackInstance, type MedianFeedbackProps as PortalFeedbackProps, MedianSupport as PortalSupport, type MedianSupportControl as PortalSupportControl, type MedianSupportInstance as PortalSupportInstance, type MedianSupportProps as PortalSupportProps, type MedianUser as PortalUser, type SupportLauncherKind, medianFeedback, medianSupport, mountMedianFeedback, mountMedianSupport, mountMedianFeedback as mountPortalFeedback, mountMedianSupport as mountPortalSupport, medianFeedback as portalFeedback, medianSupport as portalSupport, reportError, useCanReportError, useMedianFeedback, useMedianSupport, useMedianFeedback as usePortalFeedback, useMedianSupport as usePortalSupport };
+/**
+ * What a host can put on the contact form, and what the form always has.
+ *
+ * Two fields are on every form whatever the host says: an email, because a
+ * message nobody can reply to is a message nobody sent, and the message
+ * itself. Everything else is the host's to add: a name, a topic, an order
+ * number, whatever their team wants to know before they read.
+ */
+/** A line, a paragraph, or one of a list. */
+type MedianContactFieldKind = "text" | "textarea" | "select";
+/**
+ * One field a host adds to the form.
+ *
+ *   { name: "topic", label: "Topic", type: "select", options: ["Billing", "A bug"] }
+ *
+ * Three names are reserved. `email` and `message` are the two the form always
+ * has, and naming either here only changes its label and placeholder. `name`
+ * lands on the customer record beside the email rather than in the message,
+ * so the team sees who wrote rather than a line saying so.
+ */
+type MedianContactField = {
+    /** Its key. Rides the message as the label on its line. */
+    name: string;
+    /** Shown above the box. Made from `name` when left out. */
+    label?: string;
+    /** `text` by default. Ignored on `email` and `message`, which know their shape. */
+    type?: MedianContactFieldKind;
+    /** What a `select` offers. A select with none falls back to a text box. */
+    options?: string[];
+    placeholder?: string;
+    /** Off by default. `email` and `message` are required whatever this says. */
+    required?: boolean;
+};
+
+type MedianContactFormOptions = {
+    /**
+     * What the form asks, beyond an email and a message, which it always asks:
+     *
+     *   <MedianContactForm
+     *     apiKey="median_pk_..."
+     *     fields={[
+     *       { name: "name", label: "Name", required: true },
+     *       { name: "topic", type: "select", options: ["Billing", "A bug", "Something else"] },
+     *     ]}
+     *   />
+     *
+     * Shown in this order. Email goes first, or right after a `name` field,
+     * and the message goes last, unless either is placed here by name. A
+     * `name` field lands on the customer record; every other answer goes
+     * above the message as a line of its own.
+     */
+    fields?: MedianContactField[];
+    /**
+     * Who is signed in on your site, if anyone. Their email and name fill the
+     * boxes in, and the rest is shown to your team.
+     */
+    user?: MedianUser;
+    /**
+     * Whether the message carries what the browser already knows: time zone,
+     * language, browser, OS, device, screen, and the page it was sent from.
+     * On by default. Pass `false` and none of it is read at all.
+     */
+    telemetry?: boolean;
+    /**
+     * Watch what goes wrong on the page, so a bug report filed from the
+     * message arrives with the error already attached. The same switch
+     * `<MedianSupport>` takes, and the same buffer behind it.
+     */
+    diagnostics?: MedianDiagnostics;
+    /**
+     * Anything about your own app worth having next to a bug report: a build,
+     * a route, a flag. Read when the form is sent.
+     */
+    appState?: Record<string, string | number | boolean>;
+    /** The heading, for a page that calls this something else. */
+    title?: string;
+    /** The line under it. */
+    description?: string;
+    /**
+     * The message landed. For whatever your page does next: a thank-you of its
+     * own, a redirect, an event. The form has already said thank you itself.
+     */
+    onSent?: () => void;
+};
+/**
+ * Two ways in, the same two `<MedianSupport>` takes.
+ *
+ * `apiKey` is the publishable id on its own. `identity` is the path to a
+ * route built with `medianIdentity`, which answers with the key and with
+ * whoever is signed in, already signed. Pass both and the form is up on the
+ * key from the prop while the route is still answering.
+ */
+type MedianContactFormProps = MedianContactFormOptions & ({
+    apiKey: string;
+    identity?: string;
+} | {
+    apiKey?: string;
+    identity: string;
+});
+/**
+ * A contact form, for the page where a chat panel is the wrong shape.
+ *
+ *   <MedianContactForm apiKey="median_pk_..." />
+ *
+ * An email and a message, on a card the shape of the support panel, with
+ * whatever else your team wants asked first. What is sent starts a
+ * conversation in your inbox exactly as the widget would: the agent answers
+ * first, your team picks it up, and the reply goes to the email given.
+ *
+ * Built on `useMedianContact`, which is also what a form of your own uses.
+ * It needs no connection of its own, and it is independent of
+ * `<MedianSupport>`: mount either, both, or neither. Mounted together they
+ * share a visitor, so somebody who writes here and later opens the widget
+ * finds the same thread.
+ */
+declare function MedianContactForm(props: MedianContactFormProps): react.JSX.Element;
+
+/**
+ * The component's props, plus where on the page the form goes.
+ *
+ * Spelled out rather than `Omit`ped off the props, because omitting a key
+ * from a union of two shapes flattens it into one and loses the "either,
+ * but not neither" the union is there to say.
+ */
+type MedianContactFormMountOptions = MedianContactFormProps & {
+    /**
+     * The element the form is rendered into, or a selector for it:
+     *
+     *   mountMedianContactForm({ target: "#contact", apiKey: "median_pk_..." });
+     *
+     * Unlike the widget, a form has no corner to go to, so this is required.
+     */
+    target: string | Element;
+};
+type MedianContactFormInstance = MedianMountInstance<MedianContactFormProps>;
+/**
+ * The same form, for a page that has never heard of React: Vue, Svelte,
+ * Rails, a script on plain HTML.
+ *
+ *   const form = mountMedianContactForm({
+ *     target: "#contact",
+ *     apiKey: "median_pk_...",
+ *     fields: [{ name: "name", label: "Name" }],
+ *   });
+ *
+ * It takes the component's props as one options object, plus `target`, and
+ * renders into a container of its own inside that element with the
+ * package's copy of React. Whatever else the element holds is left alone.
+ */
+declare function mountMedianContactForm({ target, ...options }: MedianContactFormMountOptions): MedianContactFormInstance;
+
+/**
+ * What a contact form hands over, ours or a host's own.
+ *
+ * The shape is deliberately small: the two things a message needs to be
+ * answered, who wrote it if they said, and whatever else the form asked as
+ * label to answer. Building one from a `<form>` of your own is a few lines.
+ */
+type MedianContactMessage = {
+    /** Where the reply goes. */
+    email: string;
+    /** What they wrote. */
+    message: string;
+    /** Lands on the customer record beside the email. */
+    name?: string;
+    /**
+     * Everything else the form asked, as label to answer. Each goes above the
+     * message as a line of its own, so the team reads the form the way it was
+     * filled in:
+     *
+     *   { Topic: "Billing", "Order number": "4821" }
+     *
+     * Empty answers are left off.
+     */
+    fields?: Record<string, string>;
+};
+
+/**
+ * Sending a contact message, for a form of the host's own.
+ *
+ * The same door the widget's composer uses, on the same session token, so
+ * what a host's form sends starts the thread the corner would have started:
+ * the team answers it from the inbox, the agent goes first, and with no
+ * panel open to watch, the reply goes to the email given. Somebody who
+ * writes here and later opens the widget finds their own conversation.
+ *
+ * A stateless HTTP client rather than the subscribing one, because nothing
+ * is read back: a form is a thing you hand over, not a thread you watch.
+ */
+/** What a send is told about who is sending and from where. */
+type MedianContactOptions = {
+    /** The browser-safe median_pk_ id. */
+    apiKey: string;
+    /**
+     * Who is signed in on your site, if anyone. What the form says about the
+     * email and the name wins over this; the rest is shown to your team.
+     */
+    user?: MedianUser;
+    /**
+     * Whether the message carries what the browser already knows: time zone,
+     * language, browser, OS, device, screen, and the page it was sent from.
+     * On by default. Pass `false` and none of it is read at all.
+     */
+    telemetry?: boolean;
+};
+/**
+ * Send a contact message from a form of your own, on any page in the
+ * browser:
+ *
+ *   await sendMedianContact(
+ *     { apiKey: "median_pk_..." },
+ *     { email, message, name, fields: { Topic: topic } },
+ *   );
+ *
+ * It resolves once the message is in your inbox and rejects with an `Error`
+ * whose `message` is worth showing above your button. Nothing about the
+ * form is ours: any `<form>`, any framework, any styling.
+ *
+ * In React, `useMedianContact()` is the same call with `isSending` and
+ * `error` kept for you, and an identity route resolved.
+ */
+declare function sendMedianContact(options: MedianContactOptions, message: MedianContactMessage): Promise<void>;
+
+type MedianContactHookOptions = {
+    /** Who is signed in on your site, if anyone. */
+    user?: MedianUser;
+    /** Browser context on the message. On by default. */
+    telemetry?: boolean;
+    /**
+     * Watch what goes wrong on the page, so a bug report filed from the
+     * message arrives with the error already attached. The same switch
+     * `<MedianSupport>` takes, and the same buffer behind it.
+     */
+    diagnostics?: MedianDiagnostics;
+    /** Anything about your own app worth having next to a bug report. */
+    appState?: Record<string, string | number | boolean>;
+};
+/**
+ * Two ways in, the same two every component takes: the publishable key, or
+ * the path of a route built with `medianIdentity`, which answers with the
+ * key and whoever is signed in.
+ */
+type UseMedianContactOptions = MedianContactHookOptions & ({
+    apiKey: string;
+    identity?: string;
+} | {
+    apiKey?: string;
+    identity: string;
+});
+/** What the hook hands back: one call, and the state around it. */
+type MedianContactControl = {
+    showBranding: boolean;
+    /**
+     * Send what the form holds. Resolves once the message is in the inbox.
+     * Rejects with an `Error` whose `message` is worth showing, and `error`
+     * holds the same words until the next send.
+     */
+    send: (message: MedianContactMessage) => Promise<void>;
+    /** A send is in flight. Hold the button. */
+    isSending: boolean;
+    /** Why the last send failed, or null. Cleared by the next send. */
+    error: string | null;
+    /**
+     * Whether a send has somewhere to go. False on the server, and for the
+     * beat before an identity route has answered with the key.
+     */
+    isReady: boolean;
+    /**
+     * Who is typing, as far as the page knows: what you passed, what the
+     * identity route said, and the email the widget's own question was
+     * answered with on this browser. For filling the boxes in.
+     */
+    user: MedianUser | undefined;
+};
+/**
+ * A contact form of your own, on Median's inbox:
+ *
+ *   const contact = useMedianContact({ apiKey: "median_pk_..." });
+ *
+ *   <form
+ *     onSubmit={async (event) => {
+ *       event.preventDefault();
+ *       await contact.send({ email, message });
+ *     }}
+ *   >
+ *     ...
+ *     {contact.error && <p>{contact.error}</p>}
+ *     <button disabled={contact.isSending}>Send</button>
+ *   </form>
+ *
+ * Everything about the form is yours. What is sent starts a conversation in
+ * your inbox exactly as `<MedianContactForm>` and the widget do, and the
+ * reply goes to the email given. No provider, no connection to manage.
+ */
+declare function useMedianContact(options: UseMedianContactOptions): MedianContactControl;
+
+export { type MedianContactControl, type MedianContactField, type MedianContactFieldKind, MedianContactForm, type MedianContactFormInstance, type MedianContactFormMountOptions, type MedianContactFormProps, type MedianContactMessage, type MedianContactOptions, type MedianDiagnostics, type MedianErrorReportOptions, type MedianErrorReportOutcome, MedianFeedback, type MedianFeedbackControl, type MedianFeedbackInstance, type MedianFeedbackProps, MedianSupport, type MedianSupportControl, type MedianSupportInstance, MedianSupportModal, type MedianSupportModalInstance, type MedianSupportModalProps, type MedianSupportProps, type MedianUser, type MedianDiagnostics as PortalDiagnostics, type MedianErrorReportOptions as PortalErrorReportOptions, type MedianErrorReportOutcome as PortalErrorReportOutcome, MedianFeedback as PortalFeedback, type MedianFeedbackControl as PortalFeedbackControl, type MedianFeedbackInstance as PortalFeedbackInstance, type MedianFeedbackProps as PortalFeedbackProps, MedianSupport as PortalSupport, type MedianSupportControl as PortalSupportControl, type MedianSupportInstance as PortalSupportInstance, type MedianSupportProps as PortalSupportProps, type MedianUser as PortalUser, type SupportLauncherKind, type UseMedianContactOptions, medianFeedback, medianSupport, mountMedianContactForm, mountMedianFeedback, mountMedianSupport, mountMedianSupportModal, mountMedianFeedback as mountPortalFeedback, mountMedianSupport as mountPortalSupport, medianFeedback as portalFeedback, medianSupport as portalSupport, reportError, sendMedianContact, useCanReportError, useMedianContact, useMedianFeedback, useMedianSupport, useMedianFeedback as usePortalFeedback, useMedianSupport as usePortalSupport };