@cosmoops/connect-sdk 0.40.0 → 0.42.0

package/dist/esm/client/index.js

@@ -15,6 +15,7 @@ export { ConnectProvider, useConnect,
 // For a component that must render on a page with no provider - see its own
 // note. `<ConnectVisitorChat>` is the case it exists for.
 useConnectOptional, useConnectUser, useConnectWorkspaceType, useConnectAudience, useConnectPlatformAccess, useConnectEntitlements, useConnectPlans, useConnectApps, useConnectCompanyProfile, useConnectAddonUsage, useConnectSessions, useConnectIntegrations, useConnectResource, CONNECT_APP_URL, } from "./provider.js";
+export { CONNECT_HANDOFF_MESSAGE_TYPE, CONNECT_HANDOFF_RESULT_PARAM } from "./handoff.js";
 // Re-exported from the root entry rather than kept there alone: it is a pure
 // helper, but every caller is UI code, and making a component file reach two
 // entry points for one function is friction with nothing behind it.
@@ -31,10 +32,10 @@ ConnectUserMenu, ConnectManageSubscriptionButton, ConnectInvoicesButton, Connect
 // Built, compiled into `dist/`, and reachable from no entry point until now -
 // `ConnectUserMenu` was the only thing that could render it.
 export { ConnectAccountSessions } from "./components/account-sessions.js";
-// A link to *any* Connect portal page that offers a "Back to <your app>" way
-// home - what `ConnectProfileButton` builds for `/profile` internally, made
-// reusable for a host linking out to a different Connect page (e.g.
-// `/calendar/settings`) on its own.
+// A link to *any* Connect portal page that offers a `"Back to <your app>"` way
+// home, for a host that needs a real `<a href>` (a server-rendered link, a
+// middle-click). For a button, prefer `useConnect().openConnect`, which also
+// brings the visitor back when the task is done.
 export { connectPortalUrl, useConnectPortalUrl } from "./portal-links.js";
 // The frame the rest of these components live inside. Exported next to the
 // pieces it composes rather than in a section of its own - an integration
@@ -152,6 +153,7 @@ export { useConnectWorkspaces, useConnectWorkspaceMembers } from "./provider.js"
 // than a link-out to Connect's own "Create workspace" button.
 export { ConnectCreateWorkspaceModal } from "./components/create-workspace-form.js";
 export { useCreateWorkspace } from "./use-workspaces.js";
+export { ConnectCallProvider, ConnectCallButton, ConnectCallingStatus, useConnectCall, } from "./components/call-button.js";
 export { ConnectBookingCalendar } from "./components/booking-calendar.js";
 export { ConnectBookingDialog, ConnectBookingDetail } from "./components/booking-dialogs.js";
 // The write half of scheduling - a workspace's own first-time setup, not a

package/dist/esm/client/portal-links.js

@@ -6,7 +6,7 @@ import { useConnect } from "./provider.js";
  * `connectPortalUrl(appUrl, clientId, "/calendar/settings")`, and so on.
  *
  * Connect answers any of these paths for a signed-in user on the bare URL -
- * these two params only add the "Back to <your app>" banner
+ * these two params only add the `"Back to <your app>"` banner
  * (`ApplicationReturnBar` on Connect's side). It validates `return_to`
  * against this `client_id`'s registered redirect origins and silently drops
  * the banner if they don't match, so a wrong or stale `appUrl`/`clientId`

package/dist/esm/client/provider.js

@@ -2,6 +2,8 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
 import { clearOneTapSuppression, suppressOneTapAfterSignOut } from "./components/one-tap-state.js";
+import { ConnectError } from "../errors.js";
+import { buildHandoffUrl, readHandoffMessage, takeHandoffResult, } from "./handoff.js";
 export const CONNECT_APP_URL = "https://connect.cosmoops.com";
 const ConnectContext = createContext(null);
 /** Marks that this tab has already spent its one silent attempt - see `ConnectProviderProps.silentSignIn`. */
@@ -20,7 +22,7 @@ const SILENT_ATTEMPT_KEY = "connect_silent_attempted";
  * </ConnectProvider>
  * ```
  */
-export function ConnectProvider({ clientId = "", basePath = "/api/connect", redirectUri, appUrl = CONNECT_APP_URL, fetch: fetchImpl, silentSignIn = false, children, }) {
+export function ConnectProvider({ clientId = "", basePath = "/api/connect", redirectUri, appUrl = CONNECT_APP_URL, fetch: fetchImpl, silentSignIn = false, handoff = "popup", onHandoffResult, children, }) {
     // One state cell, not three. `isLoading` is *derived* from "no result yet"
     // rather than set - a `setIsLoading(true)` at the top of an effect is a
     // synchronous setState inside that effect, which cascades an extra render
@@ -122,7 +124,17 @@ export function ConnectProvider({ clientId = "", basePath = "/api/connect", redi
         });
         if (!response.ok) {
             const envelope = await response.json().catch(() => null);
-            throw new Error(envelope?.error?.message ?? `Connect bridge returned ${response.status}`);
+            // A `ConnectError` rather than a bare `Error`, so a caller can branch
+            // on the status and code - a signed-out 401 and a throttled 429 need
+            // different words in front of a person. Same message as before, so
+            // anything already reading it sees no change.
+            throw new ConnectError({
+                message: envelope?.error?.message ?? `Connect bridge returned ${response.status}`,
+                status: response.status,
+                code: typeof envelope?.error?.code === "string" ? envelope.error.code : "unknown",
+                endpoint: `POST ${path}`,
+                body: envelope,
+            });
         }
         return response;
     }, [basePath, fetchImpl]);
@@ -172,6 +184,61 @@ export function ConnectProvider({ clientId = "", basePath = "/api/connect", redi
         // eslint-disable-next-line react-hooks/set-state-in-effect
         void refresh();
     }, [refresh]);
+    /*
+     * Hand-offs to Connect - see `ConnectContextValue.openConnect`.
+     *
+     * The provider's own `clientId` prop wins; otherwise the bridge's, which is
+     * what makes this work for the common integration that never passes one.
+     */
+    const handoffClientId = clientId || session?.clientId || "";
+    const openConnect = useCallback((target, options = {}) => {
+        const returnTo = window.location.href;
+        if (handoff === "popup") {
+            // Deliberately no `noopener`: with it, `window.open` returns `null`
+            // by specification and Connect gets no `opener` - so it could
+            // neither tell this page it finished nor close itself (a browser
+            // only lets script close a window script opened). The opener it is
+            // handed is this page, and cross-origin that permits navigating it
+            // and posting to it - neither of which Connect does uninvited.
+            const opened = window.open(buildHandoffUrl(target, { appUrl, clientId: handoffClientId, mode: "popup", returnTo }), options.name ?? "_blank", options.features);
+            if (opened)
+                return opened;
+            // Blocked. A same-tab trip still gets them there and back, where a
+            // "your browser blocked the window" note leaves them to sort it out.
+        }
+        window.location.assign(buildHandoffUrl(target, { appUrl, clientId: handoffClientId, mode: "redirect", returnTo }));
+        return null;
+    }, [appUrl, handoff, handoffClientId]);
+    // Latest callback without re-subscribing the listener on every render of a
+    // host that passes an inline function.
+    const onHandoffResultRef = useRef(onHandoffResult);
+    useEffect(() => {
+        onHandoffResultRef.current = onHandoffResult;
+    });
+    useEffect(() => {
+        // Back from a redirect-mode trip. The page is a fresh load, so every read
+        // is already fresh - this only reports the outcome and tidies the URL.
+        // `replaceState` rather than a router call: this package imports no
+        // router, and Next's App Router honours a native `replaceState`.
+        const returned = takeHandoffResult(window.location.href);
+        if (returned) {
+            window.history.replaceState(window.history.state, "", returned.cleaned);
+            onHandoffResultRef.current?.(returned.result);
+        }
+        // A popup reporting in before it closes. `readHandoffMessage` checks the
+        // origin, which is what stops any other window driving this.
+        const onMessage = (event) => {
+            const result = readHandoffMessage(event, appUrl);
+            if (!result)
+                return;
+            // Session-wide: the plan, the readiness, the seat count - whatever the
+            // trip changed, every Connect component on the page re-reads it.
+            void refresh();
+            onHandoffResultRef.current?.(result);
+        };
+        window.addEventListener("message", onMessage);
+        return () => window.removeEventListener("message", onMessage);
+    }, [appUrl, refresh]);
     useEffect(() => {
         // `silentPending` already encodes settled-and-signed-out, no prior
         // attempt, and no bridge error - a failed bridge read says nothing about
@@ -293,8 +360,10 @@ export function ConnectProvider({ clientId = "", basePath = "/api/connect", redi
         }
     }, [fetchImpl, mutateResource, oneTapEndpoints, refresh]);
     const value = useMemo(() => ({
-        clientId,
+        clientId: handoffClientId,
         appUrl,
+        handoffMode: handoff,
+        openConnect,
         session,
         isLoading,
         error,
@@ -308,8 +377,10 @@ export function ConnectProvider({ clientId = "", basePath = "/api/connect", redi
         readOneTapHint,
         oneTapSignIn,
     }), [
-        clientId,
+        handoffClientId,
         appUrl,
+        handoff,
+        openConnect,
         session,
         isLoading,
         error,

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

@@ -1,5 +1,6 @@
 "use client";
 import { useCallback, useEffect, useRef, useState } from "react";
+import { readHandoffMessage } from "./handoff.js";
 import { useConnect } from "./provider.js";
 /** How often `/entitlements` is re-read while a checkout is open. */
 const POLL_INTERVAL_MS = 3_000;
@@ -30,7 +31,7 @@ const CLOSE_GRACE_MS = 12_000;
  * period rather than ending the run.
  */
 export function useConnectCheckout() {
-    const { fetchResource, invalidateResource, refresh } = useConnect();
+    const { appUrl, fetchResource, invalidateResource, refresh, openConnect } = useConnect();
     const [state, setState] = useState({ status: "idle", url: null });
     // Everything the poll loop needs lives in a ref: it runs from a timer, and
     // re-creating the loop whenever a piece of it changed identity would
@@ -51,20 +52,18 @@ export function useConnectCheckout() {
         // an await is what pop-up blockers exist to stop, and it would be
         // blocked in every browser regardless of the user's settings.
         //
-        // No `noopener`: with it set, `window.open` returns `null` by
-        // specification, and this hook would then read every successfully
-        // opened checkout as blocked. The handle is the whole point - it is
-        // how the grace period below knows the customer closed the window.
-        // The window it hands an `opener` to is Connect's own origin, and
-        // cross-origin access is limited to navigating this page, which
-        // Connect does not do.
-        const opened = window.open(url, "connect_checkout", "popup,width=520,height=780");
-        if (!opened) {
-            // Not a failure to report as an error: the customer can still get
-            // there, they just have to click the link themselves.
-            setState({ status: "blocked", url });
+        // Through `openConnect`, which stamps the way back on the URL: Connect
+        // then closes this window itself once the change lands, instead of
+        // leaving the customer on a billing page they have to close by hand.
+        // The handle is still what the grace period below watches.
+        //
+        // `null` means it did not open a window - the provider is in `redirect`
+        // mode, or the popup was blocked and it fell back to one - and this
+        // page is navigating away. Nothing to watch; the trip back is a fresh
+        // load that reads the new entitlement on its own.
+        const opened = openConnect(url, { name: "connect_checkout", features: "popup,width=520,height=780" });
+        if (!opened)
             return;
-        }
         run.current = {
             url,
             isSettled,
@@ -74,7 +73,7 @@ export function useConnectCheckout() {
             generation: generation.current,
         };
         setState({ status: "waiting", url });
-    }, [stop]);
+    }, [openConnect, stop]);
     useEffect(() => {
         // One interval for the hook's whole life rather than one per run: it does
         // nothing while `run.current` is null, and a run that starts from a press
@@ -130,11 +129,19 @@ export function useConnectCheckout() {
                 void poll();
         };
         document.addEventListener("visibilitychange", onVisible);
+        // Connect saying it is done is a stronger hint still - read now, before
+        // the window has even finished closing.
+        const onMessage = (event) => {
+            if (readHandoffMessage(event, appUrl))
+                void poll();
+        };
+        window.addEventListener("message", onMessage);
         return () => {
             clearInterval(interval);
             document.removeEventListener("visibilitychange", onVisible);
+            window.removeEventListener("message", onMessage);
         };
-    }, [fetchResource, invalidateResource, refresh, stop]);
+    }, [appUrl, fetchResource, invalidateResource, refresh, stop]);
     return { ...state, start, reset };
 }
 /**

package/dist/esm/server/client.js

@@ -22,6 +22,7 @@ import { SessionsResource } from "./resources/sessions.js";
 import { PlatformResource } from "./resources/platform.js";
 import { VisitorResource } from "./resources/visitor.js";
 import { PushResource } from "./resources/push.js";
+import { WhatsAppResource } from "./resources/whatsapp.js";
 export const DEFAULT_BASE_URL = "https://connect.cosmoops.com";
 const APPLICATION_API_PREFIX = "/api/v1/application";
 /**
@@ -125,6 +126,8 @@ export class ConnectClient {
      * preferences; you supply a title, a body and a URL. See `PushResource`.
      */
     push;
+    /** Your application's own approved WhatsApp templates, to a workspace's customers. */
+    whatsapp;
     /**
      * Relays one `/data/*` or `/kv/*` request verbatim - `createConnectHandler`'s
      * store route and nothing else. See `storePassthrough`.
@@ -171,8 +174,9 @@ export class ConnectClient {
         this.visitor = new VisitorResource(transport);
         this.platform = new PlatformResource(transport);
         this.push = new PushResource(transport);
+        this.whatsapp = new WhatsAppResource(transport);
         this.storeRelay = (spec) => storePassthrough(transport, spec);
     }
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export const SDK_VERSION = "0.40.0";
+export const SDK_VERSION = "0.42.0";

package/dist/esm/server/handler.js

@@ -408,6 +408,8 @@ export function createConnectHandler(options) {
      * anyone who used it).
      */
     const oneTapEndpoints = session.write ? client.identity.oneTapEndpoints() : null;
+    /** See `IdentityResource.publicClientId` - what lets the browser name this application on a hand-off. */
+    const clientId = client.identity.publicClientId();
     const routes = {
         "GET /session": async (request) => {
             const token = await session.read(request);
@@ -429,9 +431,10 @@ export function createConnectHandler(options) {
                     // whose shape depends on the answer is a response consumers start
                     // testing for key presence instead of value.
                     oneTap: oneTapEndpoints,
+                    clientId,
                 });
             }
-            return json({ ...(await client.identity.getUser(token)), oneTap: oneTapEndpoints });
+            return json({ ...(await client.identity.getUser(token)), oneTap: oneTapEndpoints, clientId });
         },
         "GET /entitlements": async (request) => {
             const { workspaceId } = await requireWorkspace(request);
@@ -1210,6 +1213,67 @@ export function createConnectHandler(options) {
             const items = await client.sessions.list(await requireToken(request));
             return json({ items });
         },
+        /*
+         * Browser calling - `<ConnectCallButton>`. Three fixed writes and no read:
+         * how a call went is your *server's* question (`client.calls.get`), never
+         * the browser's, so a call log can't be written from what a page claims.
+         *
+         * The workspace and the member both come from the session, as everywhere
+         * here; the browser names only the number.
+         */
+        /*
+         * The one calling *read*, and it is about the member, not about a call:
+         * can they ring anybody from here. A refusal means they lack "Make calls"
+         * - which is an answer, not a failure, so it is returned as one and the
+         * button simply is not offered.
+         */
+        "GET /calls/availability": async (request) => {
+            await requireWorkspace(request);
+            const asUser = await requireToken(request);
+            try {
+                return json(await client.calls.getCallingAvailability({ asUser }));
+            }
+            catch (error) {
+                if (error instanceof ConnectError && error.status === 403) {
+                    return json(NO_CALLING_PERMISSION);
+                }
+                throw error;
+            }
+        },
+        "POST /calls/browser-token": async (request) => {
+            await requireWorkspace(request);
+            const asUser = await requireToken(request);
+            return json(await client.calls.getBrowserCallingToken({ asUser }));
+        },
+        "POST /calls/start": async (request) => {
+            await requireWorkspace(request);
+            const asUser = await requireToken(request);
+            const body = (await request.json().catch(() => null));
+            if (typeof body?.phone !== "string") {
+                throw new ConnectError({
+                    status: 400,
+                    code: "validation_error",
+                    message: "phone is required",
+                    endpoint: "/calls/start",
+                });
+            }
+            return json(await client.calls.startBrowserCall({ phone: body.phone, asUser }), 201);
+        },
+        "POST /calls/cancel": async (request) => {
+            await requireWorkspace(request);
+            const asUser = await requireToken(request);
+            const body = (await request.json().catch(() => null));
+            if (typeof body?.callId !== "string") {
+                throw new ConnectError({
+                    status: 400,
+                    code: "validation_error",
+                    message: "callId is required",
+                    endpoint: "/calls/cancel",
+                });
+            }
+            await client.calls.cancelBrowserCall({ callId: body.callId, asUser });
+            return json({ cancelled: true });
+        },
         "POST /sessions/revoke": async (request) => {
             const body = (await request.json().catch(() => null));
             if (!body?.sessionId) {
@@ -1495,6 +1559,18 @@ export function createConnectHandler(options) {
         }
     };
 }
+/** What a member without "Make calls" is told - see `GET /calls/availability`. */
+const NO_CALLING_PERMISSION = {
+    status: "no_permission",
+    number: null,
+    available: 0,
+    availableMinutes: 0,
+    ratePaisePerMinute: 0,
+    lowBalance: false,
+    canTopUp: false,
+    canManageNumber: false,
+    offer: null,
+};
 function json(body, status = 200) {
     return new Response(JSON.stringify(body), {
         status,

package/dist/esm/server/resources/calls.js

@@ -1,4 +1,5 @@
 import { request } from "../http.js";
+import { actingAs } from "./acting-as.js";
 /**
  * Every call that arrived on a channel assigned to your application.
  *
@@ -50,4 +51,61 @@ export class CallsResource {
             path: `/calls/${encodeURIComponent(callId)}`,
         });
     }
+    /*
+     * Browser calling - what `<ConnectCallButton>` runs on, through your bridge.
+     *
+     * All three need the `calls:place` scope **and** a signed-in member
+     * (`asUser`), whose own "Make calls" permission Connect checks. None works
+     * server-to-server: a call is placed by a person, from the workspace's own
+     * number, and is not recorded. Read how one went with `get(callId)`, which
+     * needs `calls:read` - a call your application placed is readable by it.
+     */
+    /**
+     * Whether the member can call, and if not why - what `<ConnectCallButton>`
+     * renders from. Throws `ConnectError` 403 for a member without "Make
+     * calls"; the bridge turns that into `status: "no_permission"`.
+     */
+    getCallingAvailability(input) {
+        return request(this.transport, {
+            method: "GET",
+            path: "/calls/availability",
+            headers: actingAs(input.asUser),
+        });
+    }
+    /** A carrier token the member's browser signs in to the phone network with. */
+    getBrowserCallingToken(input) {
+        return request(this.transport, {
+            method: "POST",
+            path: "/calls/browser-token",
+            json: {},
+            headers: actingAs(input.asUser),
+        });
+    }
+    /**
+     * Approves one call from the member to `phone` (E.164) and records it.
+     *
+     * Throws `ConnectError` with status `412` when the workspace has no active
+     * number, is not allowed to place calls, or the member is already on one -
+     * the message is written to be shown to them.
+     */
+    startBrowserCall(input) {
+        return request(this.transport, {
+            method: "POST",
+            path: "/calls/start",
+            json: { phone: input.phone },
+            headers: actingAs(input.asUser),
+        });
+    }
+    /**
+     * Closes a call the browser never managed to place - recorded as
+     * `unanswered`/`cancelled`. A no-op once the carrier has it.
+     */
+    async cancelBrowserCall(input) {
+        await request(this.transport, {
+            method: "POST",
+            path: "/calls/cancel",
+            json: { callId: input.callId },
+            headers: actingAs(input.asUser),
+        });
+    }
 }

package/dist/esm/server/resources/identity.js

@@ -89,6 +89,18 @@ export class IdentityResource {
         authorize.searchParams.set("client_id", this.clientId);
         return { hintUrl: hint.toString(), authorizeUrl: authorize.toString() };
     }
+    /**
+     * This client's public `client_id`, or `null` when none is configured.
+     *
+     * The bridge hands it to the browser on `/session` so `openConnect` can name
+     * the application on every hand-off without the host passing `clientId` to
+     * `<ConnectProvider>` too - Connect only honours a `return_to` it can match
+     * against *a client's* registered redirect origins. Public by definition:
+     * it already rides on every authorize URL.
+     */
+    publicClientId() {
+        return this.clientId;
+    }
     /** Step 2 - trade the one-time `code` for a session. Server-side only. */
     async exchangeCode(input) {
         const wire = await this.post("/sso/token", {

package/dist/esm/server/resources/whatsapp.js

@@ -0,0 +1,54 @@
+import { request } from "../http.js";
+/**
+ * Your application's own WhatsApp templates, sent to a workspace's customers
+ * through Connect's WhatsApp sender - no WhatsApp Business account of your
+ * own.
+ *
+ * Templates are written and submitted to Meta in Console under your
+ * application; you name them here by slug and Connect resolves
+ * `app_<yourApplicationKey>_<slug>` from your key, so a key can never send
+ * another application's message or one of Connect's own. There is no free
+ * text: outside a customer's 24-hour window WhatsApp permits nothing else.
+ *
+ * Server-to-server only - there is no browser path, by design.
+ */
+export class WhatsAppResource {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * Send one template to one customer.
+     *
+     * Refusals arrive as a `ConnectError` whose `code` says what to tell the
+     * person who pressed Send - `template_not_approved`, `consent_required`,
+     * `opted_out`, `not_found`. None of them is a fault worth retrying.
+     *
+     * An `Idempotency-Key` is always sent, as on `otp.send`: a retried send
+     * without one is a second message on somebody's phone. Pass your own -
+     * derived from what is being sent, e.g. the quote number - to make a
+     * retry from a *later* request safe too.
+     */
+    send(input, options = {}) {
+        return request(this.transport, {
+            method: "POST",
+            path: "/whatsapp/messages",
+            json: input,
+            headers: { "idempotency-key": options.idempotencyKey ?? crypto.randomUUID() },
+        });
+    }
+    /**
+     * Whether a template would send right now, and the values it needs.
+     *
+     * Ask before offering WhatsApp on a screen: Meta's approval takes minutes
+     * to days, and an approved template can be paused later. A `ConnectError`
+     * with `status: 404` means your application has no such template.
+     */
+    template(slug, options = {}) {
+        const language = options.language ? `?language=${encodeURIComponent(options.language)}` : "";
+        return request(this.transport, {
+            method: "GET",
+            path: `/whatsapp/templates/${encodeURIComponent(slug)}${language}`,
+        });
+    }
+}

package/dist/types/client/components/ask-ai-errors.d.ts

@@ -0,0 +1,41 @@
+/**
+ * What Ask AI shows when something fails - a sentence for a person, never the
+ * error itself.
+ *
+ * The raw text is somebody else's diagnostic: `TypeError: Failed to fetch`
+ * from the browser, `Connect bridge returned 502` from the provider, a
+ * validation message naming a request field. None of it tells the person what
+ * happened or what to do, and the last one tells them something about the
+ * API they should not need to know. The real error is still on the console of
+ * whoever is debugging; this module decides only what is on screen.
+ */
+export declare const ASK_AI_GENERIC_FAILURE = "Something went wrong. Please try again.";
+export declare const TOOL_GENERIC_FAILURE = "That step couldn't be completed. Try again in a moment.";
+/**
+ * A failure Connect reported inside the stream, after it had opened.
+ *
+ * Kept apart from a transport failure because its text was written for the
+ * person by Connect's own stream error handler, so it may be shown as it is.
+ */
+export declare class AskAiStreamError extends Error {
+    readonly name = "AskAiStreamError";
+}
+export declare function describeAskAiFailure(cause: unknown): string;
+/**
+ * Whether trying the same question again could help.
+ *
+ * Off for the failures a retry cannot fix - signed out, no access, Ask AI
+ * switched off - so the panel does not offer a button that will fail the same
+ * way every time.
+ */
+export declare function isRetryableAskAiFailure(cause: unknown): boolean;
+/**
+ * The failure a tool's *result* reports, or `null` when it succeeded.
+ *
+ * An application's tool answers `{ isError: true, ... }` rather than throwing,
+ * which is MCP's distinction between "the tool refused" and "the call broke".
+ * Connect puts its own sentence in `error.message` when it could not reach
+ * the application at all; otherwise the application's first text block is its
+ * own refusal ("You don't have permission to ..."), written for its own user.
+ */
+export declare function toolFailureFromOutput(output: unknown): string | null;

package/dist/types/client/components/ask-ai-turns.d.ts

@@ -14,6 +14,11 @@ export type AskAiBlock = {
     id: string;
     name: string;
     input: unknown | null;
+    /**
+     * Set when the step failed - a sentence for the person, never the raw
+     * error. See `toolFailureFromOutput`.
+     */
+    failure?: string;
 };
 export interface AskAiTurn {
     id: string;