@cosmoops/connect-sdk 0.37.0 → 0.40.0

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

@@ -31,6 +31,135 @@ export class SchedulingResource {
         // `undefined` past every status check in between.
         return result.eventTypes ?? [];
     }
+    /**
+     * The working-hours templates an appointment type can point at.
+     *
+     * Read this before offering to create one - a workspace that already has
+     * hours set does not need a second "Working hours" from your integration.
+     */
+    async listSchedules(workspaceId, options = {}) {
+        const result = await request(this.transport, {
+            method: "GET",
+            path: "/scheduling/schedules",
+            query: { workspaceId },
+            headers: actingAs(options.asUser),
+        });
+        return result.schedules ?? [];
+    }
+    /**
+     * Gives a workspace its first working hours.
+     *
+     * Narrower than what the workspace's own Calendar settings can do - no date
+     * overrides, and never owned by one person (`ownerMemberId` stays `null`
+     * server-side). Anything beyond that is a Console edit, not a second write
+     * path for your integration to maintain.
+     */
+    createSchedule(input) {
+        return request(this.transport, {
+            method: "POST",
+            path: "/scheduling/schedules",
+            json: {
+                workspaceId: input.workspaceId,
+                name: input.name,
+                timezone: input.timezone,
+                weeklyHours: input.weeklyHours,
+            },
+            headers: actingAs(input.asUser),
+        });
+    }
+    /**
+     * The first thing a workspace can be booked for.
+     *
+     * Needs a schedule - create or pick one with `listSchedules`/`createSchedule`
+     * first. The slug for a future public booking link is derived from `name`
+     * server-side; you cannot choose one.
+     *
+     * Answers the richer *manageable* shape, not `BookableEventType` - you just
+     * created this row and are about to manage it, not book against it.
+     */
+    createEventType(input) {
+        return request(this.transport, {
+            method: "POST",
+            path: "/scheduling/event-types",
+            json: {
+                workspaceId: input.workspaceId,
+                name: input.name,
+                description: input.description ?? null,
+                durationMinutes: input.durationMinutes,
+                bufferBeforeMinutes: input.bufferBeforeMinutes,
+                bufferAfterMinutes: input.bufferAfterMinutes,
+                hostMemberId: input.hostMemberId,
+                scheduleId: input.scheduleId,
+                location: input.location,
+                publicBookingEnabled: input.publicBookingEnabled ?? false,
+            },
+            headers: actingAs(input.asUser),
+        });
+    }
+    /**
+     * The richer read `createEventType`/`updateEventType`'s edit mode needs -
+     * everything `listEventTypes`'s booking catalogue deliberately withholds,
+     * because this is the opposite audience: a member managing their own
+     * calendar, not a widget rendering someone else's. Includes inactive rows,
+     * since an edit screen is exactly where one gets reactivated.
+     */
+    async listManageableEventTypes(workspaceId, options = {}) {
+        const result = await request(this.transport, {
+            method: "GET",
+            path: "/scheduling/event-types/manage",
+            query: { workspaceId },
+            headers: actingAs(options.asUser),
+        });
+        return result.eventTypes ?? [];
+    }
+    /**
+     * Edits an existing availability schedule.
+     *
+     * Narrower than what the workspace's own Calendar settings can do, the
+     * same way `createSchedule` is: `ownerMemberId` and date overrides stay
+     * untouched, since this surface never sets either.
+     */
+    updateSchedule(input) {
+        return request(this.transport, {
+            method: "PUT",
+            path: `/scheduling/schedules/${encodeURIComponent(input.scheduleId)}`,
+            json: {
+                workspaceId: input.workspaceId,
+                name: input.name,
+                timezone: input.timezone,
+                weeklyHours: input.weeklyHours,
+            },
+            headers: actingAs(input.asUser),
+        });
+    }
+    /**
+     * Edits an existing appointment type.
+     *
+     * `hostMemberId` omitted leaves the host untouched, including a *group*
+     * host this surface cannot represent - so an edit that says nothing about
+     * the host can never accidentally overwrite a team assignment made in
+     * Connect.
+     */
+    updateEventType(input) {
+        return request(this.transport, {
+            method: "PUT",
+            path: `/scheduling/event-types/${encodeURIComponent(input.eventTypeId)}`,
+            json: {
+                workspaceId: input.workspaceId,
+                name: input.name,
+                description: input.description,
+                durationMinutes: input.durationMinutes,
+                bufferBeforeMinutes: input.bufferBeforeMinutes,
+                bufferAfterMinutes: input.bufferAfterMinutes,
+                hostMemberId: input.hostMemberId,
+                scheduleId: input.scheduleId,
+                location: input.location,
+                publicBookingEnabled: input.publicBookingEnabled,
+                active: input.active,
+            },
+            headers: actingAs(input.asUser),
+        });
+    }
     /**
      * Free times for one appointment type over one window.
      *

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

@@ -1,4 +1,4 @@
-import { request } from "../http.js";
+import { GENERATION_TIMEOUT_MS, request } from "../http.js";
 /**
  * The header a bridge forwards the visitor's own address on.
  *
@@ -97,6 +97,12 @@ export class VisitorResource {
             path: "/visitor/chat",
             json: input,
             headers: visitorHeaders(options),
+            /*
+             * Matches the route's own `maxDuration`. This endpoint does not send
+             * headers until the model's first token, so the default 20s bound was
+             * aborting any turn that opened with a tool call - see `RequestSpec.timeoutMs`.
+             */
+            timeoutMs: GENERATION_TIMEOUT_MS,
             raw: true,
             signal: options.signal,
         });

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

@@ -1,16 +1,5 @@
 import { actingAs } from "./acting-as.js";
 import { request } from "../http.js";
-/**
- * Which workspaces the signed-in user belongs to, moving between them, who
- * else is on the team, and inviting or granting access to your application.
- *
- * **Every call here needs `asUser`** - the signed-in user's opaque
- * `sessionToken`. There is no application-wide form of any of these: they take
- * no `userId` and no `workspaceId`, and resolve both from the token. That is
- * what makes the whole module safe to reach from a browser through
- * `createConnectHandler`, and it is why a partner cannot enumerate another
- * tenant's team with their own API key.
- */
 export class WorkspacesResource {
     transport;
     constructor(transport) {
@@ -31,6 +20,36 @@ export class WorkspacesResource {
         });
         return result.workspaces;
     }
+    /**
+     * Opens another workspace under the tenant the signed-in user already
+     * owns - a branch office, a second business unit.
+     *
+     * Every guard `CreateWorkspaceUseCase` enforces still applies: only the
+     * tenant's owner may call this, `type: "business"` still needs a non-free
+     * email domain, and the tenant's plan still decides whether it may hold
+     * another workspace at all - a `PreconditionError` surfaces as a thrown
+     * `ConnectError` with a message written to be shown ("Your current plan
+     * covers a single workspace...", "You've used all 3 of the workspaces
+     * your plans include..."). There is no `tenantId` parameter: the caller
+     * names no tenant, same as every other method on this resource names no
+     * workspace.
+     *
+     * `isActive`/`subscribed` on the result are always `false` - this does not
+     * switch the session, and the new workspace has no subscription yet. Chain
+     * `switch({workspaceId: result.workspaceId})` to move into it, but only
+     * when `result.inAudience` - a workspace outside this application's
+     * audience is refused by `switch` the same way `selectable()` in
+     * `<ConnectWorkspaceSwitcher>` already treats it.
+     */
+    async create(input, options) {
+        const result = await request(this.transport, {
+            method: "POST",
+            path: "/workspaces",
+            headers: actingAs(options.asUser),
+            json: input,
+        });
+        return result.workspace;
+    }
     /**
      * Moves this session to another workspace, returning a **new session
      * token**. The one you passed is revoked.

package/dist/types/client/components/availability-form.d.ts

@@ -0,0 +1,33 @@
+import type { AvailabilitySchedule } from "../../types.js";
+export interface ConnectAvailabilityFormModalProps {
+    isOpen: boolean;
+    onOpenChange: (isOpen: boolean) => void;
+    /**
+     * `null` (or omitted) creates a new schedule. A row id from
+     * `useAvailabilitySchedules` edits that one instead - name and hours
+     * prefill from it.
+     */
+    scheduleId?: string | null;
+    /** Called once the schedule is created or saved, before the modal closes. */
+    onSaved?: (schedule: AvailabilitySchedule) => void;
+}
+/**
+ * Creates or edits a workspace's working hours, from inside a host
+ * application rather than a link-out to Connect.
+ *
+ * Deliberately narrower than Connect's own Calendar settings form: one
+ * interval per day (no split shifts), no date overrides, and the timezone is
+ * set once at creation (from the browser's own) and shown but not editable
+ * here afterwards. This is a first-party setup-and-edit surface, not a
+ * second copy of the Console editor - "Manage in Connect" is still where the
+ * rest of what a schedule can do lives.
+ *
+ * **Not optimistic.** The write settles against the server before this
+ * closes, the same posture every write in this package takes - see
+ * `ConnectBookingDialog`.
+ *
+ * This outer component only decides whether the row to edit has loaded yet;
+ * the form itself is `ScheduleFields` below, mounted with
+ * `key={editing?.id}` - see that component's own doc comment for why.
+ */
+export declare function ConnectAvailabilityFormModal({ isOpen, onOpenChange, scheduleId, onSaved, }: Readonly<ConnectAvailabilityFormModalProps>): import("react").JSX.Element;

package/dist/types/client/components/create-workspace-form.d.ts

@@ -0,0 +1,32 @@
+import type { UserWorkspace } from "../../types.js";
+export interface ConnectCreateWorkspaceModalProps {
+    isOpen: boolean;
+    onOpenChange: (isOpen: boolean) => void;
+    /** Called once the workspace is created, before the modal closes. */
+    onCreated?: (workspace: UserWorkspace) => void;
+}
+/**
+ * Opens another workspace under the signed-in user's own tenant - a branch
+ * office, a second business unit - from inside a host application rather
+ * than a link-out to Connect.
+ *
+ * **Only the tenant's owner can use this successfully.** `CreateWorkspaceUseCase`
+ * refuses anyone who merely belongs to a colleague's tenant, with a message
+ * naming that - someone who wants a workspace of their own uses a personal
+ * account instead.
+ *
+ * **The tenant's plan decides how many workspaces it may hold, and this does
+ * not pre-check it.** There is no capacity read to show ahead of time - the
+ * same posture Connect's own "Create workspace" button takes - so a refusal
+ * surfaces here exactly as the server wrote it ("Your current plan covers a
+ * single workspace - subscribe to a plan that includes additional workspaces
+ * to open another.", or "You've used all 3 of the workspaces your plans
+ * include. Upgrade a plan or delete a workspace to open another.").
+ *
+ * **Does not switch the session to the new workspace.** Creating one never
+ * does, on Connect's own screen either - see `useCreateWorkspace`'s doc
+ * comment for how to chain a switch once you have the result, and guard that
+ * chain on `inAudience` the same way `<ConnectWorkspaceSwitcher>` already
+ * does for every other row.
+ */
+export declare function ConnectCreateWorkspaceModal({ isOpen, onOpenChange, onCreated, }: Readonly<ConnectCreateWorkspaceModalProps>): import("react").JSX.Element;

package/dist/types/client/components/event-type-form.d.ts

@@ -0,0 +1,44 @@
+import type { ManageableEventType } from "../../types.js";
+export interface ConnectEventTypeFormModalProps {
+    isOpen: boolean;
+    onOpenChange: (isOpen: boolean) => void;
+    /**
+     * `null` (or omitted) creates a new appointment type. A row id from
+     * `useManageableEventTypes` edits that one instead - name, duration,
+     * buffers, host, schedule, location and `publicBookingEnabled` all prefill
+     * from it.
+     */
+    eventTypeId?: string | null;
+    /** Called once the appointment type is created or saved, before the modal closes. */
+    onSaved?: (eventType: ManageableEventType) => void;
+}
+/**
+ * Creates or edits an appointment type, from inside a host application
+ * rather than a link-out to Connect.
+ *
+ * **Needs a schedule to exist first** - the picker reads `useAvailabilitySchedules`
+ * and renders "Set up availability first" with nothing to submit if none
+ * exists yet. Pair this with `ConnectAvailabilityFormModal` in a setup flow
+ * rather than assuming one.
+ *
+ * **That gate waits for the read, and the order matters.** Both bridge reads
+ * answer `[]` while they are in flight, so testing `schedules.length === 0`
+ * first showed "Set up availability first" to everybody who opened this -
+ * including, for a second or two, somebody pressing Edit on an appointment
+ * type that provably *has* a schedule. A load state wearing an empty state's
+ * words is worse than a spinner: it reads as a verdict, and on a slow
+ * connection it is the only thing the modal ever says. A failed read is named
+ * as a failure for the same reason - it is not the same fact as "none exist".
+ *
+ * **Host is a specific member, never a team.** There is no groups read in
+ * this bridge, so a round-robin team host stays a Console-only capability -
+ * defaults to whoever is signed in on create, with an optional picker from
+ * the workspace's own roster. **Editing a group-hosted row is refused
+ * inline** - the modal shows a notice instead of a form, because this
+ * surface cannot represent (and so cannot safely resend) a team host.
+ *
+ * This outer component only decides *which* message or form to show; the
+ * form itself is `EventTypeFields` below, mounted with `key={editing?.id}` -
+ * see that component's own doc comment for why.
+ */
+export declare function ConnectEventTypeFormModal({ isOpen, onOpenChange, eventTypeId, onSaved, }: Readonly<ConnectEventTypeFormModalProps>): import("react").JSX.Element;

package/dist/types/client/components/workspace-switcher.d.ts

@@ -21,12 +21,12 @@ export interface ConnectWorkspaceSwitcherProps {
      * every other host: an account with one workspace sees nothing, because a
      * switcher offering one option teaches it nothing. Pass `true` on an
      * application that wants a single-workspace account to be able to
-     * discover - and start - creating a second one without leaving its own
-     * chrome. There is deliberately no `workspaces.create()` on the SDK:
-     * creating a workspace is Connect's job, tied to KYC/KYB and a billing
-     * profile, not something an API key should be able to trigger - so turning
-     * this on also adds a "Create workspace" row that opens Connect, rather
-     * than pretending the switcher can do it itself.
+     * discover - and open - a second one without leaving its own chrome. Turning
+     * this on adds a "Create workspace" row that opens
+     * `<ConnectCreateWorkspaceModal>` inline: name, individual-or-business, and
+     * the tenant's own plan decides whether another workspace is allowed at
+     * all - the same guards Connect's own "Create workspace" button runs
+     * through, surfaced as the server wrote them rather than pre-checked here.
      */
     alwaysShow?: boolean;
 }
@@ -44,9 +44,9 @@ export interface ConnectWorkspaceSwitcherProps {
  * a workspace is *created*, so hiding it at one workspace would guarantee
  * nobody ever reached two. `alwaysShow` is the escape hatch for a partner
  * application that wants that same discoverability without becoming Connect:
- * it keeps the dropdown open below two workspaces and adds a row that sends
- * the member to Connect to actually create one, since there is nothing here
- * that can.
+ * it keeps the dropdown open below two workspaces and adds a row that opens
+ * `<ConnectCreateWorkspaceModal>` inline, auto-switching into the result when
+ * that is possible - see `handleCreated` below.
  *
  * **Authorization is the data, not a prop.** The list comes from the caller's
  * own session (`GET /workspaces` takes no user id), so a workspace the user

package/dist/types/client/index.d.ts

@@ -32,6 +32,7 @@ export type { ConnectUserButtonProps, ConnectProfileModalProps } from "./compone
 export { ConnectAccountSessions } from "./components/account-sessions.js";
 export type { ConnectAccountSessionsProps } from "./components/account-sessions.js";
 export type { ConnectUserMenuProps } from "./components/user-menu.js";
+export { connectPortalUrl, useConnectPortalUrl } from "./portal-links.js";
 export { AppShell } from "./components/app-shell.js";
 export type { AppShellProps } from "./components/app-shell.js";
 export { ConnectSidebar, ConnectSidebarHeader, ConnectSidebarBody, ConnectSidebarFooter, ConnectSidebarRow, } from "./components/sidebar.js";
@@ -101,8 +102,16 @@ export type { PlanAction, PlanTier, ComparablePlan } from "./components/plan-pri
 export { ConnectWorkspaceSwitcher } from "./components/workspace-switcher.js";
 export type { ConnectWorkspaceSwitcherProps } from "./components/workspace-switcher.js";
 export { useConnectWorkspaces, useConnectWorkspaceMembers } from "./provider.js";
+export { ConnectCreateWorkspaceModal } from "./components/create-workspace-form.js";
+export type { ConnectCreateWorkspaceModalProps } from "./components/create-workspace-form.js";
+export { useCreateWorkspace } from "./use-workspaces.js";
+export type { WorkspaceActionsState } from "./use-workspaces.js";
 export { ConnectBookingCalendar } from "./components/booking-calendar.js";
 export type { ConnectBookingCalendarProps } from "./components/booking-calendar.js";
 export { ConnectBookingDialog, ConnectBookingDetail } from "./components/booking-dialogs.js";
-export { useBookableEventTypes, useAvailableSlots, useBookings, useBookingActions, type SlotQuery, type BookingsQuery, } from "./use-scheduling.js";
+export { ConnectAvailabilityFormModal } from "./components/availability-form.js";
+export type { ConnectAvailabilityFormModalProps } from "./components/availability-form.js";
+export { ConnectEventTypeFormModal } from "./components/event-type-form.js";
+export type { ConnectEventTypeFormModalProps } from "./components/event-type-form.js";
+export { useBookableEventTypes, useAvailabilitySchedules, useCreateAvailabilitySchedule, useUpdateAvailabilitySchedule, useManageableEventTypes, useCreateEventType, useUpdateEventType, useAvailableSlots, useBookings, useBookingActions, type SlotQuery, type BookingsQuery, } from "./use-scheduling.js";
 export { layoutBookings, dayColumns, zonedInstant, type GridWindow, type PositionedBooking, } from "./components/booking-grid.js";

package/dist/types/client/portal-links.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Any Connect portal page, with the context it needs to offer a way back
+ * here - `connectPortalUrl(appUrl, clientId, "/profile")`,
+ * `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
+ * (`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`
+ * pairing degrades to what linking there did before rather than erroring.
+ *
+ * `window.location.href` rather than a configured home URL: the point is to
+ * come back to the page they left, and only the browser knows which one that
+ * is.
+ */
+export declare function connectPortalUrl(appUrl: string, clientId: string, path: string): string;
+/**
+ * `connectPortalUrl`, with `appUrl`/`clientId` read from the provider instead
+ * of threaded through by every caller.
+ */
+export declare function useConnectPortalUrl(path: string): string;

package/dist/types/client/use-scheduling.d.ts

@@ -1,4 +1,4 @@
-import type { BookableEventType, Booking, BookingAttendee } from "../types.js";
+import type { AvailabilitySchedule, BookableEventType, Booking, BookingAttendee, ManageableEventType, WeeklyHours } from "../types.js";
 /**
  * The bridge's scheduling surface, as hooks.
  *
@@ -14,6 +14,98 @@ export declare function useBookableEventTypes(): {
     isLoading: boolean;
     error: string | null;
 };
+/**
+ * The working-hours templates an appointment type can point at.
+ *
+ * Read this before offering a "set up availability" step - a workspace that
+ * already has one does not need a second "Working hours" from your UI.
+ */
+export declare function useAvailabilitySchedules(): {
+    schedules: AvailabilitySchedule[];
+    isLoading: boolean;
+    error: string | null;
+};
+/**
+ * The richer read `ConnectEventTypeFormModal`'s edit mode needs - everything
+ * `useBookableEventTypes`'s booking catalogue deliberately withholds. See
+ * the bridge route's own doc comment for why this is a separate read rather
+ * than a wider response on that one. Includes inactive rows.
+ */
+export declare function useManageableEventTypes(): {
+    eventTypes: ManageableEventType[];
+    isLoading: boolean;
+    error: string | null;
+    refetch: () => void;
+};
+/**
+ * Gives a workspace its first working hours.
+ *
+ * **Not optimistic** - same posture as `useBookingActions`: this is one of
+ * the two writes a host's first-run setup makes, and a modal that closes on
+ * a failed create is worse than one that stays open with the reason shown.
+ */
+export declare function useCreateAvailabilitySchedule(): BookingActionsState & {
+    createSchedule(input: {
+        name: string;
+        timezone: string;
+        weeklyHours: WeeklyHours;
+    }): Promise<AvailabilitySchedule | null>;
+};
+/** Edits an existing availability schedule. Every field optional - send only what changed. */
+export declare function useUpdateAvailabilitySchedule(): BookingActionsState & {
+    updateSchedule(input: {
+        scheduleId: string;
+        name?: string;
+        timezone?: string;
+        weeklyHours?: WeeklyHours;
+    }): Promise<AvailabilitySchedule | null>;
+};
+/**
+ * Creates the first thing a workspace can be booked for.
+ *
+ * Host is a specific member, never a team - there is no groups read in this
+ * bridge, so a round-robin team host stays a Console-only capability
+ * reachable by following "Manage in Connect".
+ */
+export declare function useCreateEventType(): BookingActionsState & {
+    createEventType(input: {
+        name: string;
+        description?: string | null;
+        durationMinutes: number;
+        bufferBeforeMinutes?: number;
+        bufferAfterMinutes?: number;
+        hostMemberId: string;
+        scheduleId: string;
+        location: {
+            kind: "phone" | "address" | "link";
+            value?: string | null;
+        };
+        publicBookingEnabled?: boolean;
+    }): Promise<ManageableEventType | null>;
+};
+/**
+ * Edits an existing appointment type. Every field optional - send only what
+ * changed. `hostMemberId` omitted leaves the host untouched, including a
+ * *group* host this surface cannot represent.
+ */
+export declare function useUpdateEventType(): BookingActionsState & {
+    updateEventType(input: {
+        eventTypeId: string;
+        name?: string;
+        description?: string | null;
+        durationMinutes?: number;
+        bufferBeforeMinutes?: number;
+        bufferAfterMinutes?: number;
+        hostMemberId?: string;
+        scheduleId?: string;
+        location?: {
+            kind: "phone" | "address" | "link";
+            value?: string | null;
+        };
+        publicBookingEnabled?: boolean;
+        active?: boolean;
+    }): Promise<ManageableEventType | null>;
+};
 export interface SlotQuery {
     eventTypeId: string;
     from: Date;

package/dist/types/client/use-workspaces.d.ts

@@ -0,0 +1,27 @@
+import type { UserWorkspace } from "../types.js";
+export interface WorkspaceActionsState {
+    isPending: boolean;
+    /** The last refusal, written to be shown to the person who clicked - see `CreateWorkspaceUseCase`. */
+    error: string | null;
+    clearError(): void;
+}
+/**
+ * Opens another workspace under the tenant the signed-in user already owns.
+ *
+ * **Not optimistic**, same posture as every write in `use-scheduling.ts`:
+ * whether the tenant's plan still has room for another workspace is a
+ * question only the server can answer, and a modal that closes before that
+ * answer comes back is the lie a two-phase write exists to avoid.
+ *
+ * The result is a `UserWorkspace` row with `isActive`/`subscribed` both
+ * `false` - creating does not switch the session to it, and the workspace has
+ * no subscription yet. Pair with `<ConnectWorkspaceSwitcher>`'s own
+ * `mutateResource("/workspaces/switch", ...)` call to move into it, guarded
+ * on `inAudience` the same way that component's `selectable()` already is.
+ */
+export declare function useCreateWorkspace(): WorkspaceActionsState & {
+    createWorkspace(input: {
+        name: string;
+        type: "individual" | "business";
+    }): Promise<UserWorkspace | null>;
+};

package/dist/types/server/client.d.ts

@@ -138,4 +138,4 @@ export declare class ConnectClient {
     constructor(options: ConnectClientOptions);
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export declare const SDK_VERSION = "0.37.0";
+export declare const SDK_VERSION = "0.40.0";

package/dist/types/server/http.d.ts

@@ -1,4 +1,15 @@
 export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+/**
+ * How long a *generating* endpoint may take to send its headers.
+ *
+ * One number, named once, and it is not a guess: it is what
+ * `POST /visitor/chat` and `POST /ai/chat` declare as their `maxDuration` on
+ * the far side. A client bound shorter than the route's own ceiling cannot be
+ * right - it can only abort work Connect is still allowed to be doing - and
+ * the two numbers drifting apart is exactly how a 20s client came to be
+ * fronting a 60s route.
+ */
+export declare const GENERATION_TIMEOUT_MS = 60000;
 export interface RequestSpec {
     /**
      * `PUT` and `DELETE` were added for the store resources. Both are idempotent
@@ -24,6 +35,30 @@ export interface RequestSpec {
      * Also stops `timeoutMs` from applying to the *body*: see `request`.
      */
     raw?: boolean;
+    /**
+     * Override the client's `timeoutMs` for this one call.
+     *
+     * The transport-wide default bounds how long a request may take to *reach*
+     * Connect, and 20 seconds is generous for every endpoint that answers from a
+     * read. It is the wrong bound for a **generating** endpoint, because of how
+     * those are built on the far side: `POST /visitor/chat` holds its response
+     * open until the first delta arrives, deliberately, so that a refusal is
+     * still an ordinary `{error}` envelope with a status rather than an event
+     * inside a stream nobody can change the status of. So "time to headers"
+     * there is time to the model's first token - after up to four tool-calling
+     * steps - and that route declares `maxDuration = 60` precisely because it
+     * can take that long.
+     *
+     * With one 20s number for everything, the client aborted at 20s, the abort
+     * read as `network_error`, and the bridge returned **502 after exactly
+     * 20.0s** on any conversation whose first token took longer - which is every
+     * conversation that starts with a tool call. It is the only route on the
+     * platform that exceeds the default; every other one declares 15 or 20.
+     *
+     * Set it where the endpoint's own `maxDuration` is larger, and nowhere else.
+     * It does not bound the stream once it has started - see the timer below.
+     */
+    timeoutMs?: number;
     signal?: AbortSignal;
     /**
      * Force this request into the retry path even though it is a `POST`.