@cosmoops/connect-sdk 0.32.0 → 0.33.0

package/CHANGELOG.md

@@ -3,6 +3,146 @@
 `@cosmoops/connect-sdk` follows semver, with the 0.x convention that **minor
 versions may carry breaking changes** and patch versions never do.
 
+## 0.33.0
+
+Two additions: the public visitor assistant, and `connect.enrichment.presence()`.
+
+### The visitor assistant
+
+A chat bubble for **your customers' own websites**, answered by Connect, for
+people who have no account anywhere. A visitor asks about that business, or
+books a call with them; your application holds no model credential and runs no
+AI infrastructure.
+
+Three calls drive a conversation and five manage what it is allowed to say:
+
+```ts
+const session = await connect.visitor.startSession({
+  workspaceId,          // which of your customers' sites this is
+  page: "/pricing",
+});
+
+const stream = await connect.visitor.chat({
+  sessionId: session.sessionId,
+  workspaceId,
+  message: "do you take walk-ins?",
+});
+```
+
+Needs an API key scoped to **`visitor:chat`**, and **`visitor:knowledge`** to
+manage the knowledge base. Both are workspace-scoped, so they carry the second
+check every workspace-wide scope carries: a live subscription to the workspace
+you name.
+
+**The assistant answers from a knowledge base you publish, and from nothing
+else.** `connect.visitor.knowledge.*` writes to a store that exists only for
+this purpose:
+
+```ts
+const item = await connect.visitor.knowledge.save({
+  workspaceId,
+  title: "Opening hours",
+  body: "Mon-Fri, 9 to 6. Closed on public holidays.",
+  source: "authored",
+});
+await connect.visitor.knowledge.publish({ workspaceId, itemId: item.id });
+```
+
+Five things to know before wiring it in, in the order they will bite you:
+
+**It is not the workspace's Context Index, and must never become it.** The
+corpus behind `ai.chat` is fed by every Drive upload a workspace makes —
+contracts, payroll, customer lists. Pointing a public widget at that would let
+a stranger extract an internal document, helpfully summarised. Nothing reaches
+the visitor store except through an explicit `publish`, and the assistant's
+read path has no route to the other corpus at all. Do not try to fill it by
+uploading to Drive; that is the invariant, not an inconvenience.
+
+**Publishing is its own call, and unpublishing can fail.** `save` always writes
+a draft, so no edit can make text public by accident. `unpublish` removes the
+retrievable copy *before* it flips the record, which means a failure leaves the
+item **still live** — surface the error and let them retry rather than greying
+the row out optimistically. For a retracted price, an item that looks withdrawn
+and is not is the most expensive bug this feature has.
+
+**Record `grounded: false` from the `done` event.** It means nothing published
+covered the question, so the assistant said so and offered a call instead of
+inventing an answer. A run of them is a knowledge base with a gap in it, which
+is the most useful signal this endpoint produces.
+
+**`mode` tells you how the knowledge reaches the model**, and `inline` is the
+good state. Below a size threshold the whole published set is carried in the
+prompt — the model sees every item rather than a top-k slice, with no chunk
+boundaries and no retrieval round trip. `retrieval` only begins once a
+knowledge base has outgrown that, and only then does `indexState` on each item
+matter.
+
+**The workspace is yours to resolve, not the browser's.** Connect checks the
+`workspaceId` you send against your own subscriptions, so the worst case is
+bounded to your own customers rather than the platform's. That is still one
+customer's budget spent from another's page, so if you serve several customers,
+resolve the workspace from your own widget record — the token in the embed
+snippet, say — rather than trusting a field a page supplied.
+
+`<ConnectVisitorChat>` in `./client` is the widget itself: a bubble that
+becomes a full-height sheet on a phone and an anchored panel above `sm`, with
+the composer's input type decided by the server rather than guessed from the
+reply — so an email field brings up a keyboard with an `@` on it and a
+verification code can be offered straight from the notification. It renders on
+a page with **no `ConnectProvider`**, which most marketing pages are, and it
+mints nothing until somebody opens it.
+
+Times offered for a call are drawn from the turn's tool result, never from the
+assistant's sentence, and the appointment is placed by a typed action rather
+than by the model — so it cannot book a time nobody offered, and a phone number
+never arrives parsed out of prose.
+
+### `connect.enrichment.presence()`
+
+`connect.enrichment.presence()` — how visible a business is online, scored out
+of 100.
+
+The third sibling of `company()` and `brand()`: that one answers what a
+business does, the other what it looks like, and this answers how findable it
+is — by a search engine, by a customer, and by the assistants that
+increasingly answer questions about a business before anybody visits its site.
+
+Returns the score, a breakdown across five categories, every check with the
+evidence behind it, every social profile linked from the site, and a
+prioritised list of what to fix.
+
+```ts
+const result = await connect.enrichment.presence({ domain: "acme.com" });
+if (result.status === "scanned") {
+  for (const next of result.scan.recommendations) {
+    console.log(`${next.priority}. ${next.title} — ${next.fix}`);
+  }
+}
+```
+
+Needs an API key scoped to **`enrichment:presence`**.
+
+Three things to know before wiring it in:
+
+**The score is computed, not generated.** Every point comes from a check run
+against something a fetcher actually observed, and every check ships with its
+weight, what was seen and the URL that settles it — so the total is
+reconstructable. A model only orders the recommendations and writes the prose;
+it cannot move the number. That is the whole reason this is worth showing a
+customer: ask a model how good a company's web presence is and it answers 72
+with total confidence for a site it never read.
+
+**`social` is claimed, never verified.** Those are URLs the site itself
+printed. Nothing proves the account belongs to that business — render it as
+"linked from their site". Check `machineReadable` too: `false` means a real
+profile that search engines have to infer from a footer link, which is a
+specific, common and easily fixed finding.
+
+**A low score is a success, not a skip.** Every check failing is the most
+useful report this produces. Only `unreachable` means the site did not answer —
+and `provider_unavailable` means *Connect* did not, which is never something
+to tell your user about their own site.
+
 ## 0.32.0
 
 Push notifications: `connect.push.send()` on the server, `useConnectPush()` in

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;
+}