@cosmoops/connect-sdk 0.32.0 → 0.34.0

package/dist/cjs/server/resources/visitor.js

@@ -0,0 +1,227 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VisitorKnowledgeResource = exports.VisitorResource = void 0;
+const http_js_1 = require("../http.js");
+/**
+ * The header a bridge forwards the visitor's own address on.
+ *
+ * It exists because `x-forwarded-for` cannot do this job here: by the time your
+ * backend calls Connect, that header describes the hop from *your server*, and
+ * the address Connect's per-visitor limiter needs is the one on the hop before
+ * it - which only your bridge has seen.
+ *
+ * **What it is and is not trusted for.** It partitions your own application's
+ * budget fairly between visitors; it does not grant anything. A caller sending a
+ * fresh value per request defeats only the per-visitor limiter and is still
+ * bounded by the per-key burst limit and the per-application daily ceiling -
+ * which are the two that actually cap spending, and neither is client-supplied.
+ * Omit it and every visitor shares one bucket, which is a stricter limit rather
+ * than an exemption.
+ */
+const VISITOR_IP_HEADER = "x-connect-visitor-ip";
+function visitorHeaders(options) {
+    return options?.visitorIp ? { [VISITOR_IP_HEADER]: options.visitorIp } : {};
+}
+/**
+ * The public chat bubble on your own marketing site.
+ *
+ * The one resource here whose caller is **not** one of your users. There is no
+ * `asUser`, no `workspaceId` and no session anywhere in it: the counterpart is a
+ * stranger who has no account, and everything the assistant may say or do is
+ * configuration a platform admin set on your application record.
+ *
+ * That is why none of these methods takes an id naming anything. The workspace a
+ * call books into, the event type it books, the knowledge it answers from and the
+ * daily budget it spends are all read from your application - so nothing a
+ * visitor types, and nothing an injection attempt in your own chat window
+ * achieves, reaches a different tenant.
+ *
+ * **Never call these from a browser.** They take your API key, like every other
+ * resource on this client. `createConnectHandler` already exposes them on your
+ * own origin for `<ConnectVisitorChat>` to use, which is how the credential stays
+ * server-side.
+ */
+class VisitorResource {
+    transport;
+    /**
+     * The knowledge base behind the assistant - see `VisitorKnowledgeResource`.
+     *
+     * Nested rather than a top-level resource, because it is meaningless on its
+     * own: it exists to decide what *this* assistant may say.
+     */
+    knowledge;
+    constructor(transport) {
+        this.transport = transport;
+        this.knowledge = new VisitorKnowledgeResource(transport);
+    }
+    /**
+     * Open a conversation, or reopen one.
+     *
+     * Generates nothing - the greeting and the suggested questions come off the
+     * application record - so this is the one call in the flow that is always fast,
+     * which is what lets a bubble paint real copy instead of a spinner.
+     *
+     * Pass `resume` with a `sessionId` you kept and the transcript comes back with
+     * it. A `resume` that is expired, unknown or another application's silently
+     * starts a fresh conversation rather than failing: the token is the only thing
+     * being offered and it is being rejected, so there is nothing for the visitor
+     * to do about an error.
+     */
+    startSession(input, options = {}) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: "/visitor/session",
+            json: {
+                workspaceId: input.workspaceId,
+                page: input.page ?? null,
+                resume: input.resume ?? null,
+            },
+            headers: visitorHeaders(options),
+            signal: options.signal,
+        });
+    }
+    /**
+     * One turn, streamed.
+     *
+     * Returns the raw `Response` rather than a parsed body, the same way
+     * `ai.chat` does: this answers server-sent events, and buffering them here
+     * would throw away the only reason to stream. The events are `delta`
+     * (`{text}`), `done` (`VisitorTurnDone`) and `error` (`{message}`).
+     *
+     * **The transcript is not a parameter**, which is the security property this
+     * endpoint is built around: the caller is ultimately a browser on a public
+     * page, and a client that can supply its own transcript can supply one in
+     * which anything has already been established. Only the conversation id and
+     * the new message travel.
+     */
+    chat(input, options = {}) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: "/visitor/chat",
+            json: input,
+            headers: visitorHeaders(options),
+            raw: true,
+            signal: options.signal,
+        });
+    }
+    /**
+     * Book the call a visitor chose.
+     *
+     * `startAt` must be a time the turn's own slot lookup returned - an arbitrary
+     * instant is refused. That, plus a name and phone collected in real fields,
+     * is what makes it impossible to book an appointment at a time nobody offered
+     * or with a phone number a model parsed out of prose.
+     *
+     * A conversation books at most one appointment; a second call answers `409`.
+     */
+    book(input, options = {}) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: "/visitor/book",
+            headers: visitorHeaders(options),
+            signal: options.signal,
+            json: {
+                ...input,
+                startAt: input.startAt instanceof Date ? input.startAt.toISOString() : input.startAt,
+                email: input.email ?? null,
+                notes: input.notes ?? null,
+            },
+        });
+    }
+}
+exports.VisitorResource = VisitorResource;
+/**
+ * A subscribing workspace's **public** knowledge base - what their website chat
+ * may tell strangers.
+ *
+ * ## It is deliberately not their Context Index
+ *
+ * `ai.chat` answers from a workspace's Drive-fed corpus, for a signed-in member
+ * of that workspace. This is a separate store that holds only what somebody
+ * explicitly published, and the separation is the reason a publishable widget
+ * credential is safe to publish: everything the widget can reach was already
+ * meant for the public.
+ *
+ * Do not try to fill it by uploading to Drive. Nothing reaches this store as a
+ * side effect of anything else - that is the invariant, not an inconvenience.
+ *
+ * ## Publishing is its own call
+ *
+ * `save` always writes a draft. `publish` is what makes text readable by
+ * strangers, so no edit can do it by accident, and `unpublish` can fail - which
+ * means the item is **still live**, not that the call was pointless.
+ */
+class VisitorKnowledgeResource {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /** Everything, drafts included - the list a customer audits. */
+    list(workspaceId) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "GET",
+            path: "/visitor/knowledge",
+            query: { workspaceId },
+        });
+    }
+    /**
+     * Create or edit a draft.
+     *
+     * A body over the cap is **refused rather than truncated** - split a long page
+     * into sections, which is also what makes retrieval work.
+     */
+    async save(input) {
+        const result = await (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: "/visitor/knowledge",
+            json: {
+                ...input,
+                itemId: input.itemId ?? null,
+                sourceRef: input.sourceRef ?? null,
+            },
+        });
+        return result.item;
+    }
+    /**
+     * Make one item readable by strangers.
+     *
+     * May be slow: the publish that outgrows the prompt provisions a retrieval
+     * corpus and indexes everything published so far. An indexing failure still
+     * publishes and comes back with `indexState: "failed"` and `indexError` set,
+     * so a provider hiccup never makes your button look broken.
+     */
+    async publish(input) {
+        const result = await (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: "/visitor/knowledge/publish",
+            json: input,
+        });
+        return result.item;
+    }
+    /**
+     * Take one item out of what strangers can read.
+     *
+     * **A failure means it is still live.** The retrievable copy is removed before
+     * the record is flipped, so a provider that refuses the delete aborts rather
+     * than leaving an item your screen shows as withdrawn that the widget goes on
+     * quoting. Surface the error and let them retry; do not grey the row out
+     * optimistically.
+     */
+    async unpublish(input) {
+        const result = await (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: "/visitor/knowledge/unpublish",
+            json: input,
+        });
+        return result.item;
+    }
+    /** Remove it entirely. A published item is unpublished first. */
+    async delete(input) {
+        await (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: "/visitor/knowledge/delete",
+            json: input,
+        });
+    }
+}
+exports.VisitorKnowledgeResource = VisitorKnowledgeResource;

package/dist/esm/client/components/access-gate.js

@@ -1,6 +1,6 @@
 "use client";
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useState } from "react";
+import { useEffect, useState } from "react";
 import { Ban, AlertTriangle, Building2, Clock, CreditCard, ExternalLink, User, X } from "lucide-react";
 import { Button, Card } from "@heroui/react";
 import { blockingBlockers } from "../../helpers.js";
@@ -36,7 +36,19 @@ function formatDate(iso) {
  */
 export function useConnectAccessGate() {
     const { session, isLoading: sessionLoading } = useConnect();
-    const { data, isLoading: entitlementsLoading } = useConnectEntitlements();
+    const { data, isLoading: entitlementsLoading, refetch } = useConnectEntitlements();
+    return { ...decideAccess(session, sessionLoading, data, entitlementsLoading), refresh: refetch };
+}
+/**
+ * The priority ordering, with the reads lifted out.
+ *
+ * Split from the hook so the twelve verdicts stay one `return` each and none
+ * of them has to carry `refresh` - a field that is the same function in every
+ * branch and says nothing about which branch it is. Pure, like
+ * `rbac/policy.ts` and `evaluateSignInRisk`, and for the same reason: a
+ * decision spread across its inputs cannot be tested.
+ */
+function decideAccess(session, sessionLoading, data, entitlementsLoading) {
     if (sessionLoading) {
         return { state: "loading", blocker: null, paymentRetry: null };
     }
@@ -147,6 +159,49 @@ export function useConnectAccessGate() {
  */
 export function ConnectAccessGate({ children, fallback, loading, className }) {
     const gate = useConnectAccessGate();
+    const isBlocked = gate.state !== "loading" &&
+        gate.state !== "signed_out" &&
+        gate.state !== "clear" &&
+        gate.state !== "payment_retry";
+    /**
+     * A blocked gate re-checks when the tab comes back.
+     *
+     * Every blocker this component draws is resolved **somewhere else** - on
+     * Connect, in another tab, by an admin, on a phone - and none of that
+     * reaches this tab. The resolve button used to open Connect in a new tab,
+     * so the overwhelmingly common path was: subscribe over there, switch back,
+     * and find the same "Choose a plan to continue" card, with a reload the
+     * only way out. It read as the purchase not having worked.
+     *
+     * The button is a same-tab navigation now (see `GateCard`), which handles
+     * the common case on its own. This covers the rest: a second tab, a
+     * colleague with the admin rights, a payment settled on a phone.
+     *
+     * Only while blocked, deliberately. A `clear` gate re-reading entitlements
+     * on every tab focus would put a request on the critical path of
+     * alt-tabbing back into an application that is working fine, for every
+     * workspace, all day. Nothing is gained by it: the gate has nothing to
+     * show, and losing access mid-session is what the server-side check before
+     * each action is for.
+     */
+    useEffect(() => {
+        if (!isBlocked || typeof document === "undefined")
+            return;
+        const recheck = () => {
+            if (document.visibilityState === "visible")
+                gate.refresh();
+        };
+        document.addEventListener("visibilitychange", recheck);
+        window.addEventListener("focus", recheck);
+        return () => {
+            document.removeEventListener("visibilitychange", recheck);
+            window.removeEventListener("focus", recheck);
+        };
+        // `gate.refresh` is stable per render of the provider and re-subscribing
+        // on it would churn the listeners; `isBlocked` is the only thing that
+        // should add or remove them.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [isBlocked]);
     // `children`, unless the host explicitly asked for a placeholder. See the
     // doc comment - this is the branch that decides whether a partner's page
     // can stream.
@@ -215,9 +270,27 @@ function AccessGateFallback({ state, blocker, className, }) {
  * so "see plans" landing back on the same blocked screen never gets anyone
  * to a choice they can act on. Sending them to Connect's own subscribe page
  * always resolves.
+ *
+ * ### Same tab, and it carries the way back
+ *
+ * It used to `window.open(resolveUrl, "_blank")`. A new tab is the wrong
+ * shape for a step you have to finish before you can continue: the customer
+ * subscribes over there, is left on Connect's billing page with nothing
+ * pointing home, and the tab they started in is still showing this card. The
+ * most common ending was two open tabs and the belief that the payment had
+ * not worked.
+ *
+ * So: a same-tab navigation carrying `?next=` back to the page they are
+ * standing on, which Connect honours after a subscribe once the origin
+ * matches one registered for this application's client
+ * (`resolveApplicationReturnUrl`). An unregistered origin costs the return
+ * trip and nothing else - they still reach Connect, still resolve the
+ * blocker, and `ConnectAccessGate`'s focus re-check catches them on the way
+ * back. Partners should register their app's origin; the fallback is a
+ * degraded path, not a broken one.
  */
 function GateCard({ icon: Icon, iconClassName, title, message, actionLabel, resolveUrl, className, }) {
-    return (_jsx(MotionProvider, { children: _jsx(m.div, { initial: { opacity: 0, y: -6 }, animate: { opacity: 1, y: 0 }, transition: ENTER, children: _jsxs(Card, { className: className, children: [_jsxs(Card.Header, { children: [_jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Icon, { className: `size-5 shrink-0 ${iconClassName}`, "aria-hidden": "true" }), _jsx(Card.Title, { children: title })] }), _jsx(Card.Description, { children: message })] }), resolveUrl && (_jsx(Card.Footer, { children: _jsxs(Button, { variant: "primary", onPress: () => window.open(resolveUrl, "_blank", "noopener,noreferrer"), children: [actionLabel ?? "Resolve on Connect", _jsx(ExternalLink, { className: "size-3.5" })] }) }))] }) }) }));
+    return (_jsx(MotionProvider, { children: _jsx(m.div, { initial: { opacity: 0, y: -6 }, animate: { opacity: 1, y: 0 }, transition: ENTER, children: _jsxs(Card, { className: className, children: [_jsxs(Card.Header, { children: [_jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Icon, { className: `size-5 shrink-0 ${iconClassName}`, "aria-hidden": "true" }), _jsx(Card.Title, { children: title })] }), _jsx(Card.Description, { children: message })] }), resolveUrl && (_jsx(Card.Footer, { children: _jsxs(Button, { variant: "primary", onPress: () => window.location.assign(withReturnTo(resolveUrl)), children: [actionLabel ?? "Resolve on Connect", _jsx(ExternalLink, { className: "size-3.5" })] }) }))] }) }) }));
 }
 /**
  * The skippable payment-due warning. Dismissal is scoped to this specific
@@ -236,3 +309,26 @@ function PaymentRetryBanner({ blocker, className, }) {
                                     window.localStorage.setItem(dismissKey, "1");
                             }, children: _jsx(X, { className: "size-4" }) })] })] }) }));
 }
+/**
+ * `resolveUrl` with `?next=` pointing at the page the customer is standing
+ * on, so Connect can hand them back once the blocker is gone.
+ *
+ * Returns the URL untouched if anything is off - no `window`, an unparseable
+ * `resolveUrl`, a `next` already set by the server. Getting back is a
+ * courtesy on top of resolving the blocker, and it must never be the reason
+ * somebody cannot reach the screen that resolves it.
+ */
+function withReturnTo(resolveUrl) {
+    if (typeof window === "undefined")
+        return resolveUrl;
+    try {
+        const url = new URL(resolveUrl);
+        if (url.searchParams.has("next"))
+            return resolveUrl;
+        url.searchParams.set("next", window.location.href);
+        return url.toString();
+    }
+    catch {
+        return resolveUrl;
+    }
+}