@cosmoops/connect-sdk 0.32.0 → 0.33.0

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

@@ -0,0 +1,384 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useCallback, useEffect, useId, useRef, useState } from "react";
+import { Button, Input, Label, TextField } from "@heroui/react";
+import { CalendarCheck, MessageCircle, Send, X } from "lucide-react";
+import { cn } from "../../cn.js";
+import { useConnectOptional } from "../provider.js";
+import { readVisitorStream, visitorSlotOfferFrom } from "./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.
+ */
+export 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 = useConnectOptional();
+    const root = basePath ?? "/api/connect";
+    const [isOpen, setIsOpen] = useState(defaultOpen);
+    const [session, setSession] = useState(null);
+    const [messages, setMessages] = useState([]);
+    const [field, setField] = useState("message");
+    const [input, setInput] = useState("");
+    const [streaming, setStreaming] = useState("");
+    const [isBusy, setIsBusy] = useState(false);
+    const [error, setError] = useState(null);
+    const [offer, setOffer] = useState(null);
+    const [chosen, setChosen] = useState(null);
+    const [booked, setBooked] = useState(null);
+    const [turnsRemaining, setTurnsRemaining] = useState(1);
+    const abortRef = useRef(null);
+    const bottomRef = useRef(null);
+    const headingId = 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 = 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 = 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.
+     */
+    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]);
+    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.
+    useEffect(() => () => abortRef.current?.abort(), []);
+    const send = 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 readVisitorStream(response, {
+                onDelta: (delta) => {
+                    answer += delta;
+                    setStreaming(answer);
+                },
+                onDone: (done) => {
+                    setField(done.field);
+                    setTurnsRemaining(done.turnsRemaining);
+                    setOffer(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 = 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 (_jsxs(_Fragment, { children: [!isOpen && (_jsx(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: _jsx(MessageCircle, { className: "size-6 sm:size-5" }) })), isOpen && (_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: 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: [_jsxs("div", { className: "flex shrink-0 items-center gap-2 border-b border-border px-4 py-3", children: [_jsx("span", { id: headingId, className: "flex-1 truncate text-sm font-semibold", children: assistantName?.trim() || title }), _jsx(Button, { isIconOnly: true, size: "sm", variant: "tertiary", "aria-label": "Close", onPress: () => setIsOpen(false), children: _jsx(X, { className: "size-4" }) })] }), _jsxs("div", { className: "min-h-0 min-w-0 flex-1 space-y-3 overflow-y-auto p-4", children: [session && messages.length === 0 && (_jsx("p", { className: "text-sm text-muted", children: greeting })), messages.map((message, index) => (_jsx(Bubble, { role: message.role, text: message.text }, `${message.at}-${index}`))), streaming && _jsx(Bubble, { role: "assistant", text: streaming }), isBusy && !streaming && !chosen && (_jsx("p", { className: "text-xs text-muted", "aria-live": "polite", children: "Typing..." })), session && messages.length === 0 && suggestions.length > 0 && (_jsx("div", { className: "flex flex-wrap gap-2 pt-1", children: suggestions.map((suggestion) => (_jsx(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 && (_jsx(SlotPicker, { offer: offer, onChoose: setChosen, isDisabled: isBusy })), chosen && !booked && (_jsx(AttendeeForm, { slotLabel: chosen.label, isBusy: isBusy, onCancel: () => setChosen(null), onSubmit: bookChosenSlot })), booked && (_jsxs("div", { className: "flex items-start gap-2 rounded-lg border border-border bg-accent/5 p-3 text-sm", children: [_jsx(CalendarCheck, { className: "mt-0.5 size-4 shrink-0 text-accent" }), _jsxs("span", { children: ["Booked - ", booked.label] })] })), error && (_jsx("p", { className: "text-xs text-content-danger", role: "alert", children: error })), exhausted && (_jsx("p", { className: "text-xs text-muted", children: "This conversation has reached its limit. Reload the page to start a new one." })), _jsx("div", { ref: bottomRef })] }), _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: [_jsxs(TextField, { variant: "secondary", className: "min-w-0 flex-1", children: [_jsx(Label, { className: "sr-only", children: FIELD_LABEL[field] }), _jsx(Input, { ...FIELD_INPUT[field], placeholder: FIELD_LABEL[field], value: input, onChange: (event) => setInput(event.currentTarget.value), disabled: composerDisabled })] }), _jsx(Button, { type: "submit", isIconOnly: true, variant: "primary", "aria-label": "Send", className: "size-11 shrink-0 sm:size-10", isDisabled: composerDisabled || !input.trim(), children: _jsx(Send, { className: "size-4" }) })] })] }))] }));
+}
+function Bubble({ role, text }) {
+    const isVisitor = role === "visitor";
+    return (_jsx("div", { className: cn("flex", isVisitor ? "justify-end" : "justify-start"), children: _jsx("p", { className: 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 (_jsxs("div", { className: "space-y-2 rounded-lg border border-border p-3", children: [_jsxs("p", { className: "text-xs text-muted", children: [offer.eventType, " \u00B7 ", offer.durationMinutes, " min \u00B7 times shown in ", offer.timezone] }), _jsx("div", { className: "flex flex-wrap gap-2", children: offer.slots.map((slot) => (_jsx(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] = useState("");
+    const [phone, setPhone] = useState("");
+    const [email, setEmail] = useState("");
+    const ready = name.trim().length > 0 && phone.trim().length >= 3;
+    return (_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: [_jsxs("p", { className: "text-xs text-muted", children: ["Booking ", slotLabel] }), _jsxs(TextField, { variant: "secondary", children: [_jsx(Label, { className: "text-xs", children: "Your name" }), _jsx(Input, { autoComplete: "name", value: name, onChange: (event) => setName(event.currentTarget.value), disabled: isBusy })] }), _jsxs(TextField, { variant: "secondary", children: [_jsx(Label, { className: "text-xs", children: "Phone" }), _jsx(Input, { type: "tel", inputMode: "tel", autoComplete: "tel", value: phone, onChange: (event) => setPhone(event.currentTarget.value), disabled: isBusy })] }), _jsxs(TextField, { variant: "secondary", children: [_jsx(Label, { className: "text-xs", children: "Email (optional)" }), _jsx(Input, { type: "email", inputMode: "email", autoComplete: "email", value: email, onChange: (event) => setEmail(event.currentTarget.value), disabled: isBusy })] }), _jsxs("div", { className: "flex gap-2 pt-1", children: [_jsx(Button, { type: "submit", variant: "primary", className: "min-h-11 flex-1 sm:min-h-9", isDisabled: !ready || isBusy, children: "Confirm" }), _jsx(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/esm/client/components/visitor-stream.js

@@ -0,0 +1,120 @@
+export 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.
+ */
+export 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/esm/client/index.js

@@ -11,7 +11,10 @@
  * whatever theme the host application platform already configured, and one theme
  * change lands identically in all of them.
  */
-export { ConnectProvider, useConnect, useConnectUser, useConnectWorkspaceType, useConnectAudience, useConnectPlatformAccess, useConnectEntitlements, useConnectPlans, useConnectApps, useConnectCompanyProfile, useConnectAddonUsage, useConnectSessions, useConnectIntegrations, useConnectResource, CONNECT_APP_URL, } from "./provider.js";
+export { ConnectProvider, useConnect, 
+// For a component that must render on a page with no provider - see its own
+// note. `<ConnectVisitorChat>` is the case it exists for.
+useConnectOptional, useConnectUser, useConnectWorkspaceType, useConnectAudience, useConnectPlatformAccess, useConnectEntitlements, useConnectPlans, useConnectApps, useConnectCompanyProfile, useConnectAddonUsage, useConnectSessions, useConnectIntegrations, useConnectResource, CONNECT_APP_URL, } from "./provider.js";
 // Re-exported from the root entry rather than kept there alone: it is a pure
 // helper, but every caller is UI code, and making a component file reach two
 // entry points for one function is friction with nothing behind it.
@@ -64,6 +67,13 @@ export { useConnectPush } from "./use-push.js";
 // page title derived from it cannot disagree with the rail.
 export { normalizeNav, flattenNav, normalizePath, resolveActivePath, isNavItemActive, gateExemptPaths, filterNavForAudience, } from "./components/nav.js";
 export { matchConnectScreen, isLinkableConnectScreen, } from "./components/ai-screens.js";
+/*
+ * 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.
+ */
+export { ConnectVisitorChat } from "./components/visitor-chat.js";
+export { readVisitorStream, visitorSlotOfferFrom } from "./components/visitor-stream.js";
 export { ConnectAppsGrid } from "./components/apps-grid.js";
 // `AppShell askAi` mounts this; exported for an app that wants the panel
 // without the frame, or wants it somewhere other than the shell's flex row

package/dist/esm/client/provider.js

@@ -332,6 +332,29 @@ export 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.
+ */
+export function useConnectOptional() {
+    return useContext(ConnectContext);
+}
 /** The signed-in user, or `null`. Sugar over `useConnect().session`. */
 export function useConnectUser() {
     return useConnect().session?.user ?? null;

package/dist/esm/server/client.js

@@ -20,6 +20,7 @@ import { AnalyticsResource } from "./resources/analytics.js";
 import { OtpResource } from "./resources/otp.js";
 import { SessionsResource } from "./resources/sessions.js";
 import { PlatformResource } from "./resources/platform.js";
+import { VisitorResource } from "./resources/visitor.js";
 import { PushResource } from "./resources/push.js";
 export const DEFAULT_BASE_URL = "https://connect.cosmoops.com";
 const APPLICATION_API_PREFIX = "/api/v1/application";
@@ -112,6 +113,11 @@ export class ConnectClient {
     integrations;
     /** Which workspaces the signed-in user belongs to, switching between them, and the team - see `WorkspacesResource`. */
     workspaces;
+    /**
+     * The public chat bubble on your own site - see `VisitorResource`. The one
+     * resource here whose caller is not one of your users.
+     */
+    visitor;
     /** The platform's own legal identity and DPDP grievance channel - see `PlatformResource`. */
     platform;
     /**
@@ -162,6 +168,7 @@ export class ConnectClient {
         this.sessions = new SessionsResource(transport, options.clientId ?? null);
         this.integrations = new IntegrationsResource(transport);
         this.workspaces = new WorkspacesResource(transport);
+        this.visitor = new VisitorResource(transport);
         this.platform = new PlatformResource(transport);
         this.push = new PushResource(transport);
         this.storeRelay = (spec) => storePassthrough(transport, spec);