@cosmoops/connect-sdk 0.32.0 → 0.34.0

package/dist/cjs/client/components/visitor-chat.js

@@ -0,0 +1,387 @@
+"use client";
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectVisitorChat = ConnectVisitorChat;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const react_2 = require("@heroui/react");
+const lucide_react_1 = require("lucide-react");
+const cn_js_1 = require("../../cn.js");
+const provider_js_1 = require("../provider.js");
+const visitor_stream_js_1 = require("./visitor-stream.js");
+/**
+ * The public chat bubble: a visitor with no account asks about your product,
+ * books a call, or gets started.
+ *
+ * ## It runs on pages that have no `ConnectProvider`
+ *
+ * Deliberately, and it is the main thing separating this component from every
+ * other one here. A marketing page usually has no session to hold and nothing
+ * on it that needs one, so requiring the provider would mean wrapping a
+ * landing page in an auth context to put a chat bubble on it. It reads the
+ * context through `useConnectOptional` and uses it only for `basePath` and the
+ * injected `fetch`; both have props, and both have defaults.
+ *
+ * ## Nothing happens until somebody opens it
+ *
+ * The conversation is minted on first open, never on mount. On a busy marketing
+ * site mounting would mean one Firestore write and one wasted session row per
+ * *page view*, for a bubble most visitors never touch - and the bubble itself
+ * needs no server state to render. The greeting arrives with that first call
+ * and is stored copy rather than generated, so opening costs one fast round
+ * trip and the visitor is reading real words immediately.
+ *
+ * ## It is built for a phone first
+ *
+ * Open, it is a full-height sheet on a narrow viewport and an anchored panel
+ * from `sm` up - a marketing chat that covers a desktop browser is harder to
+ * use, and one that does not cover a phone has nowhere to put a keyboard.
+ * `h-dvh` rather than `h-screen`, so the sheet tracks the visual viewport when
+ * the keyboard opens; `env(safe-area-inset-bottom)` on the composer, so the
+ * send button is not under a home indicator.
+ *
+ * The composer's input type is **the server's decision**, not a guess from what
+ * the assistant said - see `VisitorField`. That is what puts an `@` on the
+ * keyboard when an email is wanted and lets iOS offer a verification code
+ * straight from the notification.
+ *
+ * ## The times are drawn from the tool result, never the prose
+ *
+ * A turn that looked up availability carries the slots as structured data, and
+ * the buttons come from that. So a time the visitor taps is one the server
+ * offered, which is the property `/visitor/book` relies on and cannot check for
+ * itself.
+ *
+ * ## Replies render as text, not markdown
+ *
+ * `<ConnectAskAi>` lazy-loads a markdown renderer because it answers questions
+ * about a workspace's documents, where tables and code blocks carry meaning.
+ * This answers three-sentence questions about a product on a marketing page.
+ * Shipping 462 KB of renderer to a landing page for prose that is deliberately
+ * kept to a couple of lines is the wrong trade, so line breaks are preserved
+ * and nothing else is parsed.
+ */
+function ConnectVisitorChat({ workspaceId, assistantName, greeting = "Hi - ask me anything, or I can put you in touch with someone.", suggestions = [], bookingEventTypeSlug = null, basePath, page, title = "Chat with us", defaultOpen = false, showWhenSignedIn = false, fetch: fetchProp, }) {
+    const connect = (0, provider_js_1.useConnectOptional)();
+    const root = basePath ?? "/api/connect";
+    const [isOpen, setIsOpen] = (0, react_1.useState)(defaultOpen);
+    const [session, setSession] = (0, react_1.useState)(null);
+    const [messages, setMessages] = (0, react_1.useState)([]);
+    const [field, setField] = (0, react_1.useState)("message");
+    const [input, setInput] = (0, react_1.useState)("");
+    const [streaming, setStreaming] = (0, react_1.useState)("");
+    const [isBusy, setIsBusy] = (0, react_1.useState)(false);
+    const [error, setError] = (0, react_1.useState)(null);
+    const [offer, setOffer] = (0, react_1.useState)(null);
+    const [chosen, setChosen] = (0, react_1.useState)(null);
+    const [booked, setBooked] = (0, react_1.useState)(null);
+    const [turnsRemaining, setTurnsRemaining] = (0, react_1.useState)(1);
+    const abortRef = (0, react_1.useRef)(null);
+    const bottomRef = (0, react_1.useRef)(null);
+    const headingId = (0, react_1.useId)();
+    /*
+     * **Through the provider when there is one, and directly when there is not.**
+     *
+     * `mutateResource` and `streamResource` already prefix the provider's own
+     * `basePath` and go through its injected `fetch` - which is the seam Storybook
+     * and the docs site mount this against, so using them is what makes those two
+     * work with nothing passed. Without a provider there is no seam to inherit and
+     * the `fetch` prop stands in, defaulting to the global.
+     *
+     * Reaching into the context for `basePath` and `fetch` instead would have
+     * meant widening `ConnectContextValue` with two fields nothing else needs, to
+     * re-implement two methods it already has.
+     */
+    const call = (0, react_1.useCallback)(async (path, body) => {
+        if (connect)
+            return connect.mutateResource(path, body);
+        const response = await (fetchProp ?? globalThis.fetch)(`${root}${path}`, {
+            method: "POST",
+            credentials: "same-origin",
+            headers: { accept: "application/json", "content-type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        const payload = await response.json().catch(() => null);
+        if (!response.ok) {
+            throw new Error(payload?.error?.message ?? "Something went wrong. Please try again.");
+        }
+        return payload;
+    }, [connect, root, fetchProp]);
+    const openStream = (0, react_1.useCallback)(async (body, signal) => {
+        if (connect)
+            return connect.streamResource("/visitor/chat", body, { signal });
+        const response = await (fetchProp ?? globalThis.fetch)(`${root}/visitor/chat`, {
+            method: "POST",
+            credentials: "same-origin",
+            headers: { accept: "text/event-stream", "content-type": "application/json" },
+            body: JSON.stringify(body),
+            signal,
+        });
+        if (!response.ok) {
+            const envelope = await response.json().catch(() => null);
+            throw new Error(envelope?.error?.message ?? "Something went wrong. Please try again.");
+        }
+        return response;
+    }, [connect, root, fetchProp]);
+    /*
+     * Minted on first open. `storedSessionId` survives a reload, which is what
+     * lets somebody follow a link out of the chat and come back to it - on a
+     * phone, the most likely thing they will do.
+     */
+    (0, react_1.useEffect)(() => {
+        if (!isOpen || session)
+            return;
+        let cancelled = false;
+        void (async () => {
+            try {
+                const opened = await call("/visitor/session", {
+                    workspaceId,
+                    page: page ?? (typeof location !== "undefined" ? location.pathname : null),
+                    resume: storedSessionId(),
+                });
+                if (cancelled)
+                    return;
+                rememberSessionId(opened.sessionId);
+                setSession(opened);
+                setMessages(opened.messages);
+                setField(opened.field);
+                setTurnsRemaining(opened.turnsRemaining);
+                // Already carries its written-out `label`, so a reopened bubble names
+                // the time without formatting an instant in the visitor's own zone.
+                if (opened.booking)
+                    setBooked(opened.booking);
+            }
+            catch (cause) {
+                if (!cancelled) {
+                    setError(cause instanceof Error ? cause.message : "The assistant is unavailable.");
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [isOpen, session, call, page, workspaceId]);
+    (0, react_1.useEffect)(() => {
+        bottomRef.current?.scrollIntoView({ behavior: "smooth", block: "end" });
+    }, [messages, streaming, offer, booked]);
+    // A conversation left mid-stream stops costing the application the moment the
+    // panel goes away.
+    (0, react_1.useEffect)(() => () => abortRef.current?.abort(), []);
+    const send = (0, react_1.useCallback)(async (text) => {
+        if (!session)
+            return;
+        const controller = new AbortController();
+        abortRef.current = controller;
+        setError(null);
+        setIsBusy(true);
+        setOffer(null);
+        setMessages((current) => [
+            ...current,
+            { role: "visitor", text, at: new Date().toISOString() },
+        ]);
+        let answer = "";
+        try {
+            const response = await openStream({
+                sessionId: session.sessionId,
+                workspaceId,
+                message: text,
+                assistantName: assistantName ?? "",
+                bookingEventTypeSlug,
+            }, controller.signal);
+            await (0, visitor_stream_js_1.readVisitorStream)(response, {
+                onDelta: (delta) => {
+                    answer += delta;
+                    setStreaming(answer);
+                },
+                onDone: (done) => {
+                    setField(done.field);
+                    setTurnsRemaining(done.turnsRemaining);
+                    setOffer((0, visitor_stream_js_1.visitorSlotOfferFrom)(done.toolCalls));
+                },
+                onError: (message) => setError(message),
+            });
+        }
+        catch (cause) {
+            if (!controller.signal.aborted) {
+                setError(cause instanceof Error ? cause.message : "Something went wrong.");
+            }
+        }
+        finally {
+            if (abortRef.current === controller)
+                abortRef.current = null;
+            /*
+             * The streamed text is committed to the transcript here rather than as
+             * it arrives, so there is exactly one copy of the reply on screen at
+             * every moment - `streaming` is what is being written, `messages` is
+             * what has been said.
+             */
+            if (answer.trim()) {
+                setMessages((current) => [
+                    ...current,
+                    { role: "assistant", text: answer.trim(), at: new Date().toISOString() },
+                ]);
+            }
+            setStreaming("");
+            setIsBusy(false);
+        }
+    }, [session, openStream, workspaceId, assistantName, bookingEventTypeSlug]);
+    const bookChosenSlot = (0, react_1.useCallback)(async (details) => {
+        if (!session || !chosen)
+            return;
+        setIsBusy(true);
+        setError(null);
+        try {
+            const appointment = await call("/visitor/book", {
+                sessionId: session.sessionId,
+                workspaceId,
+                eventTypeSlug: bookingEventTypeSlug,
+                startAt: chosen.startAt,
+                name: details.name,
+                phone: details.phone,
+                email: details.email || null,
+            });
+            setBooked(appointment);
+            setChosen(null);
+            setOffer(null);
+            setMessages((current) => [
+                ...current,
+                {
+                    role: "assistant",
+                    text: `You're booked for ${appointment.label}. A confirmation is on its way.`,
+                    at: new Date().toISOString(),
+                },
+            ]);
+        }
+        catch (cause) {
+            setError(cause instanceof Error ? cause.message : "That time could not be booked.");
+        }
+        finally {
+            setIsBusy(false);
+        }
+    }, [session, chosen, call, workspaceId, bookingEventTypeSlug]);
+    /*
+     * A signed-in member has the application's own surfaces, and `<ConnectAskAi>`
+     * occupies this same corner - see `showWhenSignedIn`.
+     */
+    if (!showWhenSignedIn && connect?.session?.user)
+        return null;
+    const exhausted = turnsRemaining <= 0;
+    const composerDisabled = isBusy || !session || exhausted;
+    const handleSubmit = (event) => {
+        event.preventDefault();
+        const text = input.trim();
+        if (!text || composerDisabled)
+            return;
+        setInput("");
+        void send(text);
+    };
+    return ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [!isOpen && ((0, jsx_runtime_1.jsx)(react_2.Button, { isIconOnly: true, variant: "primary", "aria-label": title, onPress: () => setIsOpen(true), 
+                /*
+                 * `size-14` on a phone and `size-12` from `sm` up: 56px is the floor
+                 * for a one-handed thumb target on a surface where this is the only
+                 * interactive element floating over the page.
+                 */
+                className: "fixed end-4 bottom-4 z-30 size-14 rounded-full shadow-lg sm:size-12", style: { marginBottom: "env(safe-area-inset-bottom)" }, children: (0, jsx_runtime_1.jsx)(lucide_react_1.MessageCircle, { className: "size-6 sm:size-5" }) })), isOpen && ((0, jsx_runtime_1.jsxs)("div", { role: "dialog", "aria-modal": "true", "aria-labelledby": headingId, 
+                /*
+                 * A full-height sheet on a phone, an anchored panel from `sm` up.
+                 * `h-dvh` rather than `h-screen`: `vh` is the *largest* viewport on
+                 * iOS, so a `h-screen` sheet puts its composer under the keyboard.
+                 */
+                className: (0, cn_js_1.cn)("fixed inset-0 z-40 flex h-dvh flex-col bg-surface", "sm:inset-auto sm:end-6 sm:bottom-6 sm:h-[min(32rem,calc(100dvh-6rem))] sm:w-[22rem] sm:rounded-2xl sm:border sm:border-border sm:shadow-xl"), children: [(0, jsx_runtime_1.jsxs)("div", { className: "flex shrink-0 items-center gap-2 border-b border-border px-4 py-3", children: [(0, jsx_runtime_1.jsx)("span", { id: headingId, className: "flex-1 truncate text-sm font-semibold", children: assistantName?.trim() || title }), (0, jsx_runtime_1.jsx)(react_2.Button, { isIconOnly: true, size: "sm", variant: "tertiary", "aria-label": "Close", onPress: () => setIsOpen(false), children: (0, jsx_runtime_1.jsx)(lucide_react_1.X, { className: "size-4" }) })] }), (0, jsx_runtime_1.jsxs)("div", { className: "min-h-0 min-w-0 flex-1 space-y-3 overflow-y-auto p-4", children: [session && messages.length === 0 && ((0, jsx_runtime_1.jsx)("p", { className: "text-sm text-muted", children: greeting })), messages.map((message, index) => ((0, jsx_runtime_1.jsx)(Bubble, { role: message.role, text: message.text }, `${message.at}-${index}`))), streaming && (0, jsx_runtime_1.jsx)(Bubble, { role: "assistant", text: streaming }), isBusy && !streaming && !chosen && ((0, jsx_runtime_1.jsx)("p", { className: "text-xs text-muted", "aria-live": "polite", children: "Typing..." })), session && messages.length === 0 && suggestions.length > 0 && ((0, jsx_runtime_1.jsx)("div", { className: "flex flex-wrap gap-2 pt-1", children: suggestions.map((suggestion) => ((0, jsx_runtime_1.jsx)(react_2.Button, { size: "sm", variant: "secondary", className: "h-auto min-h-11 whitespace-normal py-2 text-start sm:min-h-9", isDisabled: composerDisabled, onPress: () => void send(suggestion), children: suggestion }, suggestion))) })), offer && !chosen && !booked && ((0, jsx_runtime_1.jsx)(SlotPicker, { offer: offer, onChoose: setChosen, isDisabled: isBusy })), chosen && !booked && ((0, jsx_runtime_1.jsx)(AttendeeForm, { slotLabel: chosen.label, isBusy: isBusy, onCancel: () => setChosen(null), onSubmit: bookChosenSlot })), booked && ((0, jsx_runtime_1.jsxs)("div", { className: "flex items-start gap-2 rounded-lg border border-border bg-accent/5 p-3 text-sm", children: [(0, jsx_runtime_1.jsx)(lucide_react_1.CalendarCheck, { className: "mt-0.5 size-4 shrink-0 text-accent" }), (0, jsx_runtime_1.jsxs)("span", { children: ["Booked - ", booked.label] })] })), error && ((0, jsx_runtime_1.jsx)("p", { className: "text-xs text-content-danger", role: "alert", children: error })), exhausted && ((0, jsx_runtime_1.jsx)("p", { className: "text-xs text-muted", children: "This conversation has reached its limit. Reload the page to start a new one." })), (0, jsx_runtime_1.jsx)("div", { ref: bottomRef })] }), (0, jsx_runtime_1.jsxs)("form", { onSubmit: handleSubmit, className: "flex shrink-0 gap-2 border-t border-border p-3", 
+                        // So the send button is not under a home indicator.
+                        style: { paddingBottom: "max(0.75rem, env(safe-area-inset-bottom))" }, children: [(0, jsx_runtime_1.jsxs)(react_2.TextField, { variant: "secondary", className: "min-w-0 flex-1", children: [(0, jsx_runtime_1.jsx)(react_2.Label, { className: "sr-only", children: FIELD_LABEL[field] }), (0, jsx_runtime_1.jsx)(react_2.Input, { ...FIELD_INPUT[field], placeholder: FIELD_LABEL[field], value: input, onChange: (event) => setInput(event.currentTarget.value), disabled: composerDisabled })] }), (0, jsx_runtime_1.jsx)(react_2.Button, { type: "submit", isIconOnly: true, variant: "primary", "aria-label": "Send", className: "size-11 shrink-0 sm:size-10", isDisabled: composerDisabled || !input.trim(), children: (0, jsx_runtime_1.jsx)(lucide_react_1.Send, { className: "size-4" }) })] })] }))] }));
+}
+function Bubble({ role, text }) {
+    const isVisitor = role === "visitor";
+    return ((0, jsx_runtime_1.jsx)("div", { className: (0, cn_js_1.cn)("flex", isVisitor ? "justify-end" : "justify-start"), children: (0, jsx_runtime_1.jsx)("p", { className: (0, cn_js_1.cn)(
+            // `max-w-[85%]` rather than a fixed width: a one-word reply should not
+            // be a full-width slab, and a long one still has to wrap.
+            "max-w-[85%] rounded-2xl px-3 py-2 text-sm whitespace-pre-wrap", isVisitor ? "bg-accent text-accent-foreground" : "bg-default"), children: text }) }));
+}
+/**
+ * The times, as buttons.
+ *
+ * Every one of them came from the server in this turn - see
+ * `visitorSlotOfferFrom`. `min-h-11` is the 44px touch floor; a row of times is
+ * exactly the control people mis-tap when it is sized for a mouse.
+ */
+function SlotPicker({ offer, onChoose, isDisabled, }) {
+    return ((0, jsx_runtime_1.jsxs)("div", { className: "space-y-2 rounded-lg border border-border p-3", children: [(0, jsx_runtime_1.jsxs)("p", { className: "text-xs text-muted", children: [offer.eventType, " \u00B7 ", offer.durationMinutes, " min \u00B7 times shown in ", offer.timezone] }), (0, jsx_runtime_1.jsx)("div", { className: "flex flex-wrap gap-2", children: offer.slots.map((slot) => ((0, jsx_runtime_1.jsx)(react_2.Button, { size: "sm", variant: "secondary", className: "min-h-11 sm:min-h-9", isDisabled: isDisabled, onPress: () => onChoose(slot), children: slot.label }, slot.startAt))) })] }));
+}
+/**
+ * Name, phone and optionally email, in real fields.
+ *
+ * The reason the assistant does not ask for these in prose: a phone number
+ * typed into a chat composer arrives as whatever the autocorrect did to it,
+ * where `type="tel" inputmode="tel" autocomplete="tel"` brings up a keypad and
+ * offers the number the browser already has.
+ *
+ * Phone is required because Connect's booking requires it - a host with no way
+ * to reach the attendee has an appointment with a stranger.
+ */
+function AttendeeForm({ slotLabel, isBusy, onCancel, onSubmit, }) {
+    const [name, setName] = (0, react_1.useState)("");
+    const [phone, setPhone] = (0, react_1.useState)("");
+    const [email, setEmail] = (0, react_1.useState)("");
+    const ready = name.trim().length > 0 && phone.trim().length >= 3;
+    return ((0, jsx_runtime_1.jsxs)("form", { className: "space-y-2 rounded-lg border border-border p-3", onSubmit: (event) => {
+            event.preventDefault();
+            if (ready && !isBusy)
+                onSubmit({ name: name.trim(), phone: phone.trim(), email: email.trim() });
+        }, children: [(0, jsx_runtime_1.jsxs)("p", { className: "text-xs text-muted", children: ["Booking ", slotLabel] }), (0, jsx_runtime_1.jsxs)(react_2.TextField, { variant: "secondary", children: [(0, jsx_runtime_1.jsx)(react_2.Label, { className: "text-xs", children: "Your name" }), (0, jsx_runtime_1.jsx)(react_2.Input, { autoComplete: "name", value: name, onChange: (event) => setName(event.currentTarget.value), disabled: isBusy })] }), (0, jsx_runtime_1.jsxs)(react_2.TextField, { variant: "secondary", children: [(0, jsx_runtime_1.jsx)(react_2.Label, { className: "text-xs", children: "Phone" }), (0, jsx_runtime_1.jsx)(react_2.Input, { type: "tel", inputMode: "tel", autoComplete: "tel", value: phone, onChange: (event) => setPhone(event.currentTarget.value), disabled: isBusy })] }), (0, jsx_runtime_1.jsxs)(react_2.TextField, { variant: "secondary", children: [(0, jsx_runtime_1.jsx)(react_2.Label, { className: "text-xs", children: "Email (optional)" }), (0, jsx_runtime_1.jsx)(react_2.Input, { type: "email", inputMode: "email", autoComplete: "email", value: email, onChange: (event) => setEmail(event.currentTarget.value), disabled: isBusy })] }), (0, jsx_runtime_1.jsxs)("div", { className: "flex gap-2 pt-1", children: [(0, jsx_runtime_1.jsx)(react_2.Button, { type: "submit", variant: "primary", className: "min-h-11 flex-1 sm:min-h-9", isDisabled: !ready || isBusy, children: "Confirm" }), (0, jsx_runtime_1.jsx)(react_2.Button, { type: "button", variant: "tertiary", className: "min-h-11 sm:min-h-9", isDisabled: isBusy, onPress: onCancel, children: "Back" })] })] }));
+}
+/**
+ * The composer's label and input attributes, per field Connect asked for.
+ *
+ * Total `Record`s over `VisitorField`, so a field added to the union fails the
+ * build here rather than silently rendering a plain text box - which is the
+ * whole failure this mechanism exists to prevent, since a plain text box is
+ * exactly what the wrong keyboard looks like.
+ */
+const FIELD_LABEL = {
+    message: "Type a message...",
+    email: "Your email address",
+    code: "6-digit code",
+    name: "Your full name",
+};
+const FIELD_INPUT = {
+    message: {},
+    email: { type: "email", inputMode: "email", autoComplete: "email" },
+    /*
+     * `autocomplete="one-time-code"` is what lets iOS offer the code from the
+     * notification without the visitor leaving the chat, and `inputmode="numeric"`
+     * brings up a keypad rather than a keyboard.
+     */
+    code: { inputMode: "numeric", autoComplete: "one-time-code", maxLength: 6 },
+    name: { autoComplete: "name" },
+};
+/**
+ * The conversation token, in `sessionStorage`.
+ *
+ * `sessionStorage` rather than a cookie or `localStorage`, and each half of that
+ * is deliberate: it survives a reload, which is what makes "follow a link out of
+ * the chat and come back" work; it does not travel to another tab or outlive the
+ * visit, which is right for a bearer token whose only job is to continue one
+ * conversation.
+ *
+ * Every access is wrapped: storage throws outright in some privacy modes, and a
+ * chat bubble that fails to open because a visitor has blocked site data is a
+ * worse outcome than one that forgets a conversation.
+ */
+const STORAGE_KEY = "connect.visitor.session";
+function storedSessionId() {
+    try {
+        return sessionStorage.getItem(STORAGE_KEY);
+    }
+    catch {
+        return null;
+    }
+}
+function rememberSessionId(id) {
+    try {
+        sessionStorage.setItem(STORAGE_KEY, id);
+    }
+    catch {
+        /* private mode, or site data blocked - the conversation still works, it just will not resume */
+    }
+}

package/dist/cjs/client/components/visitor-stream.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readVisitorStream = readVisitorStream;
+exports.visitorSlotOfferFrom = visitorSlotOfferFrom;
+async function readVisitorStream(response, handlers) {
+    const body = response.body;
+    if (!body)
+        throw new Error("The assistant returned no reply.");
+    const reader = body.pipeThrough(new TextDecoderStream()).getReader();
+    let buffer = "";
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buffer += value;
+        /*
+         * Frames are separated by a blank line, so everything before the last one is
+         * complete and whatever follows waits for the next read. Splitting on single
+         * newlines would hand a half-received `data:` line to `JSON.parse`, which on
+         * a slow connection is most frames.
+         */
+        const frames = buffer.split("\n\n");
+        buffer = frames.pop() ?? "";
+        for (const frame of frames)
+            dispatch(frame, handlers);
+    }
+    // A stream that ends mid-frame has nothing complete left in the buffer; one
+    // that ends on a frame boundary with no trailing blank line still has its
+    // last frame there, which is the shape a server that closes immediately
+    // after `done` produces.
+    if (buffer.trim())
+        dispatch(buffer, handlers);
+}
+function dispatch(frame, handlers) {
+    let event = "";
+    let data = "";
+    for (const line of frame.split("\n")) {
+        if (line.startsWith("event:"))
+            event = line.slice(6).trim();
+        else if (line.startsWith("data:"))
+            data += line.slice(5).trim();
+    }
+    if (!event || !data)
+        return;
+    let payload;
+    try {
+        payload = JSON.parse(data);
+    }
+    catch {
+        /*
+         * A frame that cannot be parsed is a frame that cannot be rendered. Dropping
+         * it keeps the rest of the reply flowing, which is strictly better than
+         * failing a whole turn - already paid for - over one malformed chunk.
+         */
+        return;
+    }
+    const record = payload;
+    switch (event) {
+        case "delta":
+            if (typeof record.text === "string")
+                handlers.onDelta(record.text);
+            return;
+        case "done":
+            handlers.onDone({
+                toolCalls: Array.isArray(record.toolCalls) ? record.toolCalls : [],
+                field: record.field === "email" || record.field === "code" || record.field === "name"
+                    ? record.field
+                    : "message",
+                turnsRemaining: typeof record.turnsRemaining === "number" ? record.turnsRemaining : 0,
+                // Defaults to `true` on an older server that does not send it: claiming
+                // a reply was ungrounded when it may not have been would put a false
+                // gap in somebody's knowledge-base report.
+                grounded: record.grounded !== false,
+            });
+            return;
+        case "error":
+            handlers.onError(typeof record.message === "string"
+                ? record.message
+                : "Sorry - something went wrong. Please try again.");
+            return;
+        default:
+            // An event this version does not know about. Ignored rather than treated
+            // as an error, so Connect can add one without breaking a pinned SDK.
+            return;
+    }
+}
+/**
+ * The times a turn looked up, lifted out of its tool calls.
+ *
+ * **This is what the buttons are drawn from, never the assistant's sentence.** A
+ * time the visitor taps is then one the server offered, which is what makes it
+ * impossible to book an appointment at a time nobody gave - the property
+ * `/visitor/book` depends on and cannot check for itself.
+ *
+ * `null` when the turn looked nothing up, and also when the lookup *refused* -
+ * a tool answering `ok: false` is the assistant being told there is nothing
+ * available, and it says so in prose. Rendering an empty slot list under that
+ * would be a second, emptier way of saying the same thing.
+ */
+function visitorSlotOfferFrom(toolCalls) {
+    // The last one wins: a turn that looked twice - a wider window after an empty
+    // first answer - should offer what it found, not what it did not.
+    for (let index = toolCalls.length - 1; index >= 0; index -= 1) {
+        const call = toolCalls[index];
+        if (!call || call.name !== "find_slots")
+            continue;
+        const result = call.result;
+        if (!result || result.ok !== true || !Array.isArray(result.slots))
+            continue;
+        const slots = result.slots
+            .map((slot) => slot)
+            .filter((slot) => typeof slot.startAt === "string" && typeof slot.label === "string")
+            .map((slot) => ({ startAt: slot.startAt, label: slot.label }));
+        if (slots.length === 0)
+            return null;
+        return {
+            eventType: typeof result.eventType === "string" ? result.eventType : "Call",
+            durationMinutes: typeof result.durationMinutes === "number" ? result.durationMinutes : 30,
+            timezone: typeof result.timezone === "string" ? result.timezone : "UTC",
+            slots,
+        };
+    }
+    return null;
+}

package/dist/cjs/client/index.js

@@ -1,9 +1,9 @@
 "use client";
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.normalizeNav = exports.useConnectPush = exports.useActivePath = exports.ConnectSideNav = exports.ConnectSidebarNav = exports.RAIL_EXPANDED = exports.RAIL_COLLAPSED = exports.sidebarRowClass = exports.useConnectShell = exports.ConnectShellProvider = exports.ConnectSidebarRow = exports.ConnectSidebarFooter = exports.ConnectSidebarBody = exports.ConnectSidebarHeader = exports.ConnectSidebar = exports.AppShell = exports.ConnectAccountSessions = exports.ConnectSignOutButton = exports.ConnectHomeButton = exports.ConnectProfileButton = exports.ConnectInvoicesButton = exports.ConnectManageSubscriptionButton = exports.ConnectUserMenu = exports.ConnectProfileModal = exports.ConnectUserButton = exports.ConnectOneTap = exports.ConnectRegisterButton = exports.ConnectLoginButton = exports.ConnectLogo = exports.ConnectMark = exports.ConnectGrievanceNotice = exports.isConnectError = exports.ConnectError = exports.normalizePlanFeatures = exports.blockingBlockers = exports.CONNECT_APP_URL = exports.useConnectResource = exports.useConnectIntegrations = exports.useConnectSessions = exports.useConnectAddonUsage = exports.useConnectCompanyProfile = exports.useConnectApps = exports.useConnectPlans = exports.useConnectEntitlements = exports.useConnectPlatformAccess = exports.useConnectAudience = exports.useConnectWorkspaceType = exports.useConnectUser = exports.useConnect = exports.ConnectProvider = void 0;
-exports.monthlyOf = exports.formatPrice = exports.buildCheckoutUrl = exports.useConnectCheckout = exports.ConnectFilterTabs = exports.ConnectCursorPagination = exports.ConnectConfirmDialog = exports.ConnectLinkButton = exports.ConnectPlansPage = exports.ConnectUsageMeter = exports.ConnectPlatformGate = exports.ConnectWorkspaceTypeGate = exports.useConnectFeature = exports.ConnectFeatureGate = exports.useConnectAccessGate = exports.ConnectAccessGate = exports.ConnectReadinessGate = exports.ConnectReadinessBanner = exports.resolveSubscriptionState = exports.ConnectSeatUsage = exports.ConnectTrialBanner = exports.ConnectSubscriptionCard = exports.ConnectNoSubscriptionCard = exports.ConnectSubscriptionGate = exports.ConnectSubscribeDialog = exports.ConnectPlans = exports.ConnectIntegrationsModal = exports.AI_TONE_DOT = exports.AI_TONE_CHIP = exports.AI_EMPTY_VALUE = exports.aiStatusTone = exports.isNumericAiFormat = exports.formatAiValue = exports.AiSources = exports.AiSteps = exports.AiDetails = exports.AiTimeline = exports.AiMetrics = exports.AiChart = exports.AiTable = exports.ConnectAskAi = exports.ConnectAppsGrid = exports.isLinkableConnectScreen = exports.matchConnectScreen = exports.filterNavForAudience = exports.gateExemptPaths = exports.isNavItemActive = exports.resolveActivePath = exports.normalizePath = exports.flattenNav = void 0;
-exports.zonedInstant = exports.dayColumns = exports.layoutBookings = exports.useBookingActions = exports.useBookings = exports.useAvailableSlots = exports.useBookableEventTypes = exports.ConnectBookingDetail = exports.ConnectBookingDialog = exports.ConnectBookingCalendar = exports.useConnectWorkspaceMembers = exports.useConnectWorkspaces = exports.ConnectWorkspaceSwitcher = exports.resolvePlanGroup = exports.groupPlansByTier = exports.isFreePlan = exports.ACTION_LABEL = exports.discountLabel = exports.annualSaving = exports.checkoutSubscriptionId = exports.resolveAction = void 0;
+exports.useConnectPush = exports.useActivePath = exports.ConnectSideNav = exports.ConnectSidebarNav = exports.RAIL_EXPANDED = exports.RAIL_COLLAPSED = exports.sidebarRowClass = exports.useConnectShell = exports.ConnectShellProvider = exports.ConnectSidebarRow = exports.ConnectSidebarFooter = exports.ConnectSidebarBody = exports.ConnectSidebarHeader = exports.ConnectSidebar = exports.AppShell = exports.ConnectAccountSessions = exports.ConnectSignOutButton = exports.ConnectHomeButton = exports.ConnectProfileButton = exports.ConnectInvoicesButton = exports.ConnectManageSubscriptionButton = exports.ConnectUserMenu = exports.ConnectProfileModal = exports.ConnectUserButton = exports.ConnectOneTap = exports.ConnectRegisterButton = exports.ConnectLoginButton = exports.ConnectLogo = exports.ConnectMark = exports.ConnectGrievanceNotice = exports.isConnectError = exports.ConnectError = exports.normalizePlanFeatures = exports.blockingBlockers = exports.CONNECT_APP_URL = exports.useConnectResource = exports.useConnectIntegrations = exports.useConnectSessions = exports.useConnectAddonUsage = exports.useConnectCompanyProfile = exports.useConnectApps = exports.useConnectPlans = exports.useConnectEntitlements = exports.useConnectPlatformAccess = exports.useConnectAudience = exports.useConnectWorkspaceType = exports.useConnectUser = exports.useConnectOptional = exports.useConnect = exports.ConnectProvider = void 0;
+exports.ConnectFilterTabs = exports.ConnectCursorPagination = exports.ConnectConfirmDialog = exports.ConnectLinkButton = exports.ConnectPlansPage = exports.ConnectUsageMeter = exports.ConnectPlatformGate = exports.ConnectWorkspaceTypeGate = exports.useConnectFeature = exports.ConnectFeatureGate = exports.useConnectAccessGate = exports.ConnectAccessGate = exports.ConnectReadinessGate = exports.ConnectReadinessBanner = exports.resolveSubscriptionState = exports.ConnectSeatUsage = exports.ConnectTrialBanner = exports.ConnectSubscriptionCard = exports.ConnectNoSubscriptionCard = exports.ConnectSubscriptionGate = exports.ConnectSubscribeDialog = exports.ConnectPlans = exports.ConnectIntegrationsModal = exports.AI_TONE_DOT = exports.AI_TONE_CHIP = exports.AI_EMPTY_VALUE = exports.aiStatusTone = exports.isNumericAiFormat = exports.formatAiValue = exports.AiSources = exports.AiSteps = exports.AiDetails = exports.AiTimeline = exports.AiMetrics = exports.AiChart = exports.AiTable = exports.ConnectAskAi = exports.ConnectAppsGrid = exports.visitorSlotOfferFrom = exports.readVisitorStream = exports.ConnectVisitorChat = exports.isLinkableConnectScreen = exports.matchConnectScreen = exports.filterNavForAudience = exports.gateExemptPaths = exports.isNavItemActive = exports.resolveActivePath = exports.normalizePath = exports.flattenNav = exports.normalizeNav = void 0;
+exports.zonedInstant = exports.dayColumns = exports.layoutBookings = exports.useBookingActions = exports.useBookings = exports.useAvailableSlots = exports.useBookableEventTypes = exports.ConnectBookingDetail = exports.ConnectBookingDialog = exports.ConnectBookingCalendar = exports.useConnectWorkspaceMembers = exports.useConnectWorkspaces = exports.ConnectWorkspaceSwitcher = exports.resolvePlanGroup = exports.groupPlansByTier = exports.isFreePlan = exports.ACTION_LABEL = exports.discountLabel = exports.annualSaving = exports.checkoutSubscriptionId = exports.resolveAction = exports.monthlyOf = exports.formatPrice = exports.buildCheckoutUrl = exports.useConnectCheckout = void 0;
 /**
  * Browser half of `@cosmoops/connect-sdk` - React components and hooks.
  *
@@ -19,6 +19,9 @@ exports.zonedInstant = exports.dayColumns = exports.layoutBookings = exports.use
 var provider_js_1 = require("./provider.js");
 Object.defineProperty(exports, "ConnectProvider", { enumerable: true, get: function () { return provider_js_1.ConnectProvider; } });
 Object.defineProperty(exports, "useConnect", { enumerable: true, get: function () { return provider_js_1.useConnect; } });
+// For a component that must render on a page with no provider - see its own
+// note. `<ConnectVisitorChat>` is the case it exists for.
+Object.defineProperty(exports, "useConnectOptional", { enumerable: true, get: function () { return provider_js_1.useConnectOptional; } });
 Object.defineProperty(exports, "useConnectUser", { enumerable: true, get: function () { return provider_js_1.useConnectUser; } });
 Object.defineProperty(exports, "useConnectWorkspaceType", { enumerable: true, get: function () { return provider_js_1.useConnectWorkspaceType; } });
 Object.defineProperty(exports, "useConnectAudience", { enumerable: true, get: function () { return provider_js_1.useConnectAudience; } });
@@ -126,6 +129,16 @@ Object.defineProperty(exports, "filterNavForAudience", { enumerable: true, get:
 var ai_screens_js_1 = require("./components/ai-screens.js");
 Object.defineProperty(exports, "matchConnectScreen", { enumerable: true, get: function () { return ai_screens_js_1.matchConnectScreen; } });
 Object.defineProperty(exports, "isLinkableConnectScreen", { enumerable: true, get: function () { return ai_screens_js_1.isLinkableConnectScreen; } });
+/*
+ * The public chat bubble. Unlike every other component here it renders for a
+ * visitor with **no account**, and works on a page with no `ConnectProvider`
+ * at all - which is most marketing pages.
+ */
+var visitor_chat_js_1 = require("./components/visitor-chat.js");
+Object.defineProperty(exports, "ConnectVisitorChat", { enumerable: true, get: function () { return visitor_chat_js_1.ConnectVisitorChat; } });
+var visitor_stream_js_1 = require("./components/visitor-stream.js");
+Object.defineProperty(exports, "readVisitorStream", { enumerable: true, get: function () { return visitor_stream_js_1.readVisitorStream; } });
+Object.defineProperty(exports, "visitorSlotOfferFrom", { enumerable: true, get: function () { return visitor_stream_js_1.visitorSlotOfferFrom; } });
 var apps_grid_js_1 = require("./components/apps-grid.js");
 Object.defineProperty(exports, "ConnectAppsGrid", { enumerable: true, get: function () { return apps_grid_js_1.ConnectAppsGrid; } });
 // `AppShell askAi` mounts this; exported for an app that wants the panel

package/dist/cjs/client/provider.js

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CONNECT_APP_URL = void 0;
 exports.ConnectProvider = ConnectProvider;
 exports.useConnect = useConnect;
+exports.useConnectOptional = useConnectOptional;
 exports.useConnectUser = useConnectUser;
 exports.useConnectWorkspaceType = useConnectWorkspaceType;
 exports.useConnectAudience = useConnectAudience;
@@ -351,6 +352,29 @@ function useConnect() {
     }
     return value;
 }
+/**
+ * The context when there is one, `null` when there is not.
+ *
+ * **For a component that must work on a page with no provider**, which is a
+ * real case rather than defensive coding: `<ConnectVisitorChat>` goes on a
+ * public marketing page, and those pages frequently have no `ConnectProvider`
+ * anywhere near them - there is no session to hold and nothing on the page that
+ * needs one. `useConnect()` throwing is right for every component that reads a
+ * session; it is wrong for one whose whole purpose is the visitor who has none.
+ *
+ * What inheriting the context buys such a component, when it is inside one, is
+ * `basePath` and the injected `fetch` - so the same component renders against
+ * Storybook's mock bridge and the docs site's canned fetch without either of
+ * them having to pass anything.
+ *
+ * Do not reach for this to make an ordinary component tolerant of a missing
+ * provider. A session-reading component that silently renders a signed-out
+ * state because somebody forgot to wrap their app is a bug that looks like a
+ * product decision.
+ */
+function useConnectOptional() {
+    return (0, react_1.useContext)(ConnectContext);
+}
 /** The signed-in user, or `null`. Sugar over `useConnect().session`. */
 function useConnectUser() {
     return useConnect().session?.user ?? null;
@@ -479,7 +503,7 @@ function useConnectSessions() {
  */
 function useConnectResource(path, options) {
     const requiresSession = options?.requiresSession ?? true;
-    const { fetchResource, session, isLoading: sessionLoading } = useConnect();
+    const { fetchResource, invalidateResource, session, isLoading: sessionLoading } = useConnect();
     // Stamped with the `path` it belongs to, so switching paths reports loading
     // without a synchronous `setIsLoading(true)` - and, more usefully, so a
     // resolved response for a previous path can never be read as this one's.
@@ -519,6 +543,9 @@ function useConnectResource(path, options) {
         // should render its signed-out state, not skeletons forever.
         isLoading: !signedOut && !loaded,
         error: loaded?.error ?? null,
-        refetch: () => setVersion((v) => v + 1),
+        refetch: () => {
+            invalidateResource(path);
+            setVersion((v) => v + 1);
+        },
     };
 }

package/dist/cjs/client/use-checkout.js

@@ -166,12 +166,14 @@ function buildCancelUrl({ appUrl, subscriptionId }) {
  * prefix that has never served this page. Building the other one is what
  * sent every first-time subscriber from a partner's pricing page to a 404.
  */
-function buildCheckoutUrl({ appUrl, applicationId, planId, subscriptionId, coupon, }) {
+function buildCheckoutUrl({ appUrl, applicationId, planId, subscriptionId, coupon, next, }) {
     const path = subscriptionId
         ? `/billing/subscriptions/${encodeURIComponent(subscriptionId)}/change-plan/${encodeURIComponent(planId)}`
         : `/apps/${encodeURIComponent(applicationId)}/subscribe/${encodeURIComponent(planId)}`;
     const url = new URL(path, appUrl);
     if (coupon?.trim())
         url.searchParams.set("coupon", coupon.trim());
+    if (next?.trim())
+        url.searchParams.set("next", next.trim());
     return url.toString();
 }