@cosmoops/connect-sdk 0.30.1 → 0.33.0

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.flattenNav = exports.normalizeNav = 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.resolveAction = 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 = 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 = 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; } });
@@ -104,6 +107,13 @@ Object.defineProperty(exports, "ConnectSidebarNav", { enumerable: true, get: fun
 Object.defineProperty(exports, "ConnectSideNav", { enumerable: true, get: function () { return side_nav_js_1.ConnectSideNav; } });
 var use_active_path_js_1 = require("./use-active-path.js");
 Object.defineProperty(exports, "useActivePath", { enumerable: true, get: function () { return use_active_path_js_1.useActivePath; } });
+/**
+ * Web Push. The hook owns the browser half - permission, the worker, the
+ * subscription - and Connect owns the keys, the devices and the member's
+ * preferences. Sending is server-side, through `connect.push.send`.
+ */
+var use_push_js_1 = require("./use-push.js");
+Object.defineProperty(exports, "useConnectPush", { enumerable: true, get: function () { return use_push_js_1.useConnectPush; } });
 // The nav model is plain data and pure functions - a host generating its nav
 // from its own route table needs the types, and `resolveActivePath` is the
 // same longest-prefix rule the sidebar highlights with, so a breadcrumb or a
@@ -119,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;

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

@@ -0,0 +1,139 @@
+"use client";
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useConnectPush = useConnectPush;
+const react_1 = require("react");
+const provider_js_1 = require("./provider.js");
+/**
+ * Read the browser's own permission as external state.
+ *
+ * Not `useState` in an effect: the permission belongs to the browser, it can
+ * change from the address bar while the page is open, and it does not exist
+ * during a server render. `useSyncExternalStore` is the primitive for exactly
+ * that - a server snapshot of `"checking"` and a live client one.
+ */
+function subscribeToPermission(onChange) {
+    let status = null;
+    let cancelled = false;
+    // Absent on some Safari builds, and throws on others. Neither is fatal:
+    // without the subscription the snapshot is still correct on every render, it
+    // simply will not update by itself.
+    navigator.permissions
+        ?.query({ name: "notifications" })
+        .then((result) => {
+        if (cancelled)
+            return;
+        status = result;
+        result.addEventListener("change", onChange);
+    })
+        .catch(() => { });
+    return () => {
+        cancelled = true;
+        status?.removeEventListener("change", onChange);
+    };
+}
+function permissionSnapshot() {
+    if (typeof navigator === "undefined" ||
+        !("serviceWorker" in navigator) ||
+        typeof window === "undefined" ||
+        !("PushManager" in window) ||
+        !("Notification" in window)) {
+        return "unsupported";
+    }
+    if (Notification.permission === "denied")
+        return "denied";
+    return Notification.permission === "granted" ? "granted" : "prompt";
+}
+const serverSnapshot = () => "checking";
+/**
+ * Register this browser for the platform's notifications.
+ *
+ * The subscription is **Connect's, not your application's**: a member who
+ * turns notifications on in one app has turned them on for the platform, and
+ * the same device receives every other app's notifications and Connect's own.
+ * That is the point of centralising it - one browser prompt instead of one per
+ * app, and one place to turn everything off.
+ *
+ * Your application needs a service worker at its own origin that handles the
+ * `push` event; the SDK does not install one, because a worker is a
+ * site-wide concern with caching implications only the host can decide.
+ *
+ * @param serviceWorkerUrl Where your worker lives. Root-scoped by convention.
+ */
+function useConnectPush(serviceWorkerUrl = "/sw.js") {
+    const { fetchResource, mutateResource } = (0, provider_js_1.useConnect)();
+    const permission = (0, react_1.useSyncExternalStore)(subscribeToPermission, permissionSnapshot, serverSnapshot);
+    const [isEnabling, setIsEnabling] = (0, react_1.useState)(false);
+    const [error, setError] = (0, react_1.useState)(null);
+    const [unconfigured, setUnconfigured] = (0, react_1.useState)(false);
+    const enable = (0, react_1.useCallback)(async () => {
+        setError(null);
+        setIsEnabling(true);
+        try {
+            /*
+             * The key first, and the order matters: if the platform cannot send,
+             * asking for permission spends the member's one prompt on a feature
+             * that will never deliver - and a denial cannot be re-asked.
+             */
+            const key = await fetchResource("/push/key");
+            if (!key.configured || !key.publicKey) {
+                setUnconfigured(true);
+                return null;
+            }
+            if ((await Notification.requestPermission()) !== "granted")
+                return null;
+            const registration = await navigator.serviceWorker.register(serviceWorkerUrl);
+            // `ready` rather than the registration itself: one that is still
+            // installing has no `pushManager`, and subscribing against it throws in
+            // a way that reads as a permission problem.
+            await navigator.serviceWorker.ready;
+            const subscription = await registration.pushManager.subscribe({
+                // Required, and it may not be false - a silent push is reserved for
+                // sites with a far higher engagement bar, and asking for one here has
+                // the browser refuse the subscription outright.
+                userVisibleOnly: true,
+                applicationServerKey: base64UrlToBytes(key.publicKey),
+            });
+            const json = subscription.toJSON();
+            const registered = await mutateResource("/push/subscribe", {
+                endpoint: json.endpoint,
+                keys: { p256dh: json.keys?.p256dh, auth: json.keys?.auth },
+            });
+            return registered.id;
+        }
+        catch {
+            setError("This browser would not register for notifications. Reload the page and try again.");
+            return null;
+        }
+        finally {
+            setIsEnabling(false);
+        }
+    }, [fetchResource, mutateResource, serviceWorkerUrl]);
+    const disable = (0, react_1.useCallback)(async (deviceId) => {
+        await mutateResource("/push/unsubscribe", { id: deviceId });
+    }, [mutateResource]);
+    return {
+        status: unconfigured && permission !== "denied" ? "unconfigured" : permission,
+        isEnabling,
+        error,
+        enable,
+        disable,
+    };
+}
+/**
+ * The VAPID public key as the bytes `pushManager.subscribe()` wants.
+ *
+ * It travels base64url and the API takes a `BufferSource`. Spelled out rather
+ * than inlined because getting it wrong produces an `InvalidAccessError` that
+ * reads as a permissions fault rather than an encoding one - and the explicit
+ * `ArrayBuffer` matters too: `Uint8Array.from` widens to `ArrayBufferLike`,
+ * which `applicationServerKey` will not accept.
+ */
+function base64UrlToBytes(base64) {
+    const padded = base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), "=");
+    const raw = atob(padded.replace(/-/g, "+").replace(/_/g, "/"));
+    const bytes = new Uint8Array(new ArrayBuffer(raw.length));
+    for (let index = 0; index < raw.length; index += 1)
+        bytes[index] = raw.charCodeAt(index);
+    return bytes;
+}

package/dist/cjs/server/client.js

@@ -23,6 +23,8 @@ const analytics_js_1 = require("./resources/analytics.js");
 const otp_js_1 = require("./resources/otp.js");
 const sessions_js_1 = require("./resources/sessions.js");
 const platform_js_1 = require("./resources/platform.js");
+const visitor_js_1 = require("./resources/visitor.js");
+const push_js_1 = require("./resources/push.js");
 exports.DEFAULT_BASE_URL = "https://connect.cosmoops.com";
 const APPLICATION_API_PREFIX = "/api/v1/application";
 /**
@@ -114,8 +116,18 @@ 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;
+    /**
+     * Web Push. Connect holds the VAPID keys, the devices and the member's own
+     * preferences; you supply a title, a body and a URL. See `PushResource`.
+     */
+    push;
     /**
      * Relays one `/data/*` or `/kv/*` request verbatim - `createConnectHandler`'s
      * store route and nothing else. See `storePassthrough`.
@@ -159,10 +171,12 @@ class ConnectClient {
         this.sessions = new sessions_js_1.SessionsResource(transport, options.clientId ?? null);
         this.integrations = new integrations_js_1.IntegrationsResource(transport);
         this.workspaces = new workspaces_js_1.WorkspacesResource(transport);
+        this.visitor = new visitor_js_1.VisitorResource(transport);
         this.platform = new platform_js_1.PlatformResource(transport);
+        this.push = new push_js_1.PushResource(transport);
         this.storeRelay = (spec) => (0, data_js_1.storePassthrough)(transport, spec);
     }
 }
 exports.ConnectClient = ConnectClient;
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-exports.SDK_VERSION = "0.30.1";
+exports.SDK_VERSION = "0.32.0";

package/dist/cjs/server/handler.js

@@ -99,6 +99,24 @@ function redirect(location, cookies = []) {
  * workspace it is not signed into, and a client-supplied `workspaceId`
  * is exactly that hole.
  */
+/**
+ * The visitor's own address, for Connect's per-visitor limiter.
+ *
+ * **Left-most `x-forwarded-for` entry**, which is the same precedence Connect's
+ * own `/api/book` and `/api/auth/session` use, and the same caveat applies: the
+ * left-most entry is the client as the first proxy saw it, and a client can
+ * prepend to that header. That makes it unsuitable for authorization and fine
+ * for this - it partitions your application's own budget between visitors, and
+ * the ceilings that actually cap spending are per key and per application.
+ *
+ * `null` where nothing forwarded one - a local dev server, or a platform that
+ * does not set it. Connect then counts every visitor in one shared bucket,
+ * which is a stricter limit rather than an exemption.
+ */
+function visitorIpOf(request) {
+    const forwarded = request.headers.get("x-forwarded-for")?.split(",")[0]?.trim();
+    return forwarded || request.headers.get("x-real-ip") || null;
+}
 function createConnectHandler(options) {
     const basePath = (options.basePath ?? "/api/connect").replace(/\/+$/, "");
     const { client, session } = options;
@@ -330,6 +348,130 @@ function createConnectHandler(options) {
             return json({ readiness, subscription });
         },
         "GET /plans": async () => json(await client.billing.listPlans()),
+        /* ---------------------------------------------------------------------- */
+        /* The visitor assistant - the only routes here with no session at all     */
+        /* ---------------------------------------------------------------------- */
+        /**
+         * `POST /visitor/session`, `/visitor/chat`, `/visitor/book`.
+         *
+         * Three routes that take **no session**, which makes them the exception to
+         * the rule every other route here follows. That is not a hole: the caller
+         * is a stranger on a public page, and there is no account for a session to
+         * identify. The question "whose data is this" has a different answer here -
+         * it is the *application's*, and the application is the one thing this
+         * bridge does hold a credential for.
+         *
+         * So the scoping that `requireWorkspace` provides elsewhere is provided
+         * here by Connect's own configuration: the workspace a call books into and
+         * the knowledge it answers from come from the application record, and no
+         * field in any of these bodies names a tenant. A browser cannot widen that
+         * by asking, because there is nothing to ask with.
+         *
+         * **`GET /company-profile` is the precedent and the limit of it.** That one
+         * is unauthenticated because the answer is identical for every caller.
+         * These are unauthenticated because the *caller* has no identity - but the
+         * answer is still per application, and spending is still per application.
+         * Which is why they are the only routes here that pass the visitor's own
+         * address along: the limiters on the far side count a visitor, and this
+         * bridge is the only thing that knows which one.
+         */
+        "POST /visitor/session": async (request) => {
+            const body = (await request.json().catch(() => null));
+            /*
+             * **The workspace is the browser's claim here, and that is the one thing
+             * this bridge must not simply relay.** Every other route on this bridge
+             * resolves the tenant from the caller's session; a visitor has none, so
+             * the widget names the customer whose site it is on - and a page can name
+             * any of them.
+             *
+             * Connect checks the workspace against your 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 an
+             * application serving several customers should resolve the workspace from
+             * its own widget record - by the embed token in the snippet, say - rather
+             * than trusting this field. The SDK cannot do that for you: it does not
+             * know what your widgets are keyed by.
+             */
+            if (typeof body?.workspaceId !== "string") {
+                throw new errors_js_1.ConnectError({
+                    status: 400,
+                    code: "validation_error",
+                    message: "workspaceId is required",
+                    endpoint: "POST /visitor/session",
+                });
+            }
+            return json(await client.visitor.startSession({
+                workspaceId: body.workspaceId,
+                page: typeof body.page === "string" ? body.page : null,
+                resume: typeof body.resume === "string" ? body.resume : null,
+            }, { visitorIp: visitorIpOf(request) }));
+        },
+        "POST /visitor/chat": async (request) => {
+            const body = (await request.json().catch(() => null));
+            if (typeof body?.sessionId !== "string" ||
+                typeof body?.workspaceId !== "string" ||
+                typeof body?.message !== "string") {
+                throw new errors_js_1.ConnectError({
+                    status: 400,
+                    code: "validation_error",
+                    message: "sessionId, workspaceId and message are required",
+                    endpoint: "POST /visitor/chat",
+                });
+            }
+            const upstream = await client.visitor.chat({
+                sessionId: body.sessionId,
+                workspaceId: body.workspaceId,
+                message: body.message,
+                ...(typeof body.assistantName === "string"
+                    ? { assistantName: body.assistantName }
+                    : {}),
+                ...(typeof body.bookingEventTypeSlug === "string"
+                    ? { bookingEventTypeSlug: body.bookingEventTypeSlug }
+                    : {}),
+            }, { visitorIp: visitorIpOf(request) });
+            /*
+             * Piped, never buffered - awaiting the body would collect the whole reply
+             * server-side and deliver it in one lump, which is the only thing
+             * streaming was for. The browser hanging up propagates down this pipe and
+             * stops generation upstream, which on this surface also stops the
+             * spending.
+             */
+            return new Response(upstream.body, {
+                status: upstream.status,
+                headers: {
+                    "content-type": upstream.headers.get("content-type") ?? "text/event-stream",
+                    "cache-control": "no-store",
+                    // Without this a proxy in front of your app may buffer the whole
+                    // stream to inspect it, which undoes the streaming end to end.
+                    "x-accel-buffering": "no",
+                    "x-content-type-options": "nosniff",
+                },
+            });
+        },
+        "POST /visitor/book": async (request) => {
+            const body = (await request.json().catch(() => null));
+            if (typeof body?.sessionId !== "string" ||
+                typeof body?.workspaceId !== "string" ||
+                typeof body?.eventTypeSlug !== "string" ||
+                typeof body?.startAt !== "string") {
+                throw new errors_js_1.ConnectError({
+                    status: 400,
+                    code: "validation_error",
+                    message: "sessionId, workspaceId, eventTypeSlug and startAt are required",
+                    endpoint: "POST /visitor/book",
+                });
+            }
+            return json(await client.visitor.book({
+                sessionId: body.sessionId,
+                workspaceId: body.workspaceId,
+                eventTypeSlug: body.eventTypeSlug,
+                startAt: body.startAt,
+                name: typeof body.name === "string" ? body.name : "",
+                phone: typeof body.phone === "string" ? body.phone : "",
+                email: typeof body.email === "string" ? body.email : null,
+                notes: typeof body.notes === "string" ? body.notes : null,
+            }, { visitorIp: visitorIpOf(request) }));
+        },
         /**
          * The platform's legal identity and grievance channel.
          *
@@ -516,6 +658,60 @@ function createConnectHandler(options) {
          * switching is simply absent for them rather than half-working - the same
          * treatment `/signin` and `/callback` already get.
          */
+        /*
+         * Push notifications - the browser half, and deliberately only that half.
+         *
+         * **There is no `POST /push` here**, and its absence is the design: a
+         * notification anybody can trigger from a devtools console is one an
+         * attacker can trigger from a compromised page, wearing the styling of an
+         * app the person trusts. Sending is a server-to-server act with your API
+         * key; Connect's own route refuses the session-token path outright.
+         *
+         * What a browser legitimately does is register itself, because
+         * `pushManager.subscribe()` produces a subscription no server can make on
+         * its behalf. All three routes resolve the member from their session, so
+         * there is no `userId` anywhere on this surface - a page cannot register a
+         * device against somebody else's account, nor list theirs.
+         */
+        "GET /push/key": async (request) => json(await client.push.key({ asUser: await requireToken(request) })),
+        "POST /push/subscribe": async (request) => {
+            const token = await requireToken(request);
+            const body = (await request.json().catch(() => null));
+            // Shape-checked here rather than relayed blindly, so a malformed
+            // subscription fails with a sentence naming what is missing instead of
+            // a Zod message from a server the page cannot see.
+            if (typeof body?.endpoint !== "string" ||
+                typeof body.keys?.p256dh !== "string" ||
+                typeof body.keys?.auth !== "string") {
+                throw new errors_js_1.ConnectError({
+                    status: 400,
+                    code: "validation_error",
+                    message: "endpoint and keys.p256dh/keys.auth are required",
+                    endpoint: "POST /push/subscribe",
+                });
+            }
+            return json(await client.push.registerDevice({
+                endpoint: body.endpoint,
+                keys: { p256dh: body.keys.p256dh, auth: body.keys.auth },
+                // Taken from the request rather than the body: a page can put
+                // anything in a field, and this one is shown back on a device
+                // list where a spoofed entry would be the point of spoofing it.
+                userAgent: (request.headers.get("user-agent") ?? "").slice(0, 512),
+            }, { asUser: token }));
+        },
+        "POST /push/unsubscribe": async (request) => {
+            const token = await requireToken(request);
+            const body = (await request.json().catch(() => null));
+            if (typeof body?.id !== "string") {
+                throw new errors_js_1.ConnectError({
+                    status: 400,
+                    code: "validation_error",
+                    message: "id is required",
+                    endpoint: "POST /push/unsubscribe",
+                });
+            }
+            return json(await client.push.revokeDevice(body.id, { asUser: token }));
+        },
         "GET /workspaces": async (request) => json({ workspaces: await client.workspaces.list({ asUser: await requireToken(request) }) }),
         "GET /workspaces/members": async (request) => json({ members: await client.workspaces.members({ asUser: await requireToken(request) }) }),
         "POST /workspaces/switch": async (request) => {