@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/webChat.d.ts

@@ -0,0 +1,1704 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.webChat` (Web Chat): 46 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"add_webchat_handoff_pool_teams_webchat_handoff_pool_teams_post">;
+ *
+ * Reference with examples: webChat.md
+ */
+/* eslint-disable */
+
+/** `g8.api.webChat.<member>` -> the operationId it calls. */
+export interface WebChatMembers {
+  addWebchatHandoffPoolTeams: "add_webchat_handoff_pool_teams_webchat_handoff_pool_teams_post";
+  addWebchatHandoffPoolUsers: "add_webchat_handoff_pool_users_webchat_handoff_pool_users_post";
+  createAssessment: "create_assessment_webchat_assessments_post";
+  createChatBot: "create_chat_bot_webchat_chat_bots_post";
+  createWebchatAgent: "create_webchat_agent_webchat_agents_post";
+  createWebchatBlog: "create_webchat_blog_webchat_blogs_post";
+  createWebchatButton: "create_webchat_button_webchat_buttons_post";
+  createWebchatQuestion: "create_webchat_question_webchat_questions_post";
+  createWebchatSettings: "create_webchat_settings_webchat_settings_post";
+  deleteAssessment: "delete_assessment_webchat_assessments__assessment_id__delete";
+  deleteChatBot: "delete_chat_bot_webchat_chat_bots__bot_id__delete";
+  deleteWebchatAgent: "delete_webchat_agent_webchat_agents__agent_id__delete";
+  deleteWebchatBlog: "delete_webchat_blog_webchat_blogs__blog_id__delete";
+  deleteWebchatButton: "delete_webchat_button_webchat_buttons__button_id__delete";
+  deleteWebchatQuestion: "delete_webchat_question_webchat_questions__question_id__delete";
+  deleteWebchatSettings: "delete_webchat_settings_webchat_settings_delete";
+  fetchWebchatBlogMetadata: "fetch_webchat_blog_metadata_webchat_blogs_fetch_metadata_post";
+  getAssessment: "get_assessment_webchat_assessments__assessment_id__get";
+  getWebchatHandoffPool: "get_webchat_handoff_pool_webchat_handoff_pool_get";
+  getWebchatHandoffPoolStatus: "get_webchat_handoff_pool_status_webchat_handoff_pool_status_get";
+  getWebchatHumanAvailability: "get_webchat_human_availability_webchat_human_availability_get";
+  getWebchatSettings: "get_webchat_settings_webchat_settings_get";
+  getWebchatVisitorFunnel: "get_webchat_visitor_funnel_webchat_visitors_funnel_get";
+  listAssessments: "list_assessments_webchat_assessments_get";
+  listChatBots: "list_chat_bots_webchat_chat_bots_get";
+  listWebchatAgents: "list_webchat_agents_webchat_agents_get";
+  listWebchatBlogs: "list_webchat_blogs_webchat_blogs_get";
+  listWebchatButtons: "list_webchat_buttons_webchat_buttons_get";
+  listWebchatQuestions: "list_webchat_questions_webchat_questions_get";
+  listWebchatTeamEventTypes: "list_webchat_team_event_types_webchat_teams__team_id__event_types_get";
+  listWebchatTeams: "list_webchat_teams_webchat_teams_get";
+  listWebchatVisitors: "list_webchat_visitors_webchat_visitors_get";
+  promoteChatBotToDefault: "promote_chat_bot_to_default_webchat_chat_bots__bot_id__promote_default_post";
+  putWebchatHumanAvailability: "put_webchat_human_availability_webchat_human_availability_put";
+  removeWebchatHandoffPoolTeam: "remove_webchat_handoff_pool_team_webchat_handoff_pool_teams__team_id__delete";
+  removeWebchatHandoffPoolUser: "remove_webchat_handoff_pool_user_webchat_handoff_pool_users__user_id__delete";
+  updateAssessment: "update_assessment_webchat_assessments__assessment_id__patch";
+  updateChatBot: "update_chat_bot_webchat_chat_bots__bot_id__patch";
+  updateWebchatAgent: "update_webchat_agent_webchat_agents__agent_id__patch";
+  updateWebchatBlog: "update_webchat_blog_webchat_blogs__blog_id__patch";
+  updateWebchatButton: "update_webchat_button_webchat_buttons__button_id__patch";
+  updateWebchatHandoffPoolTeamScope: "update_webchat_handoff_pool_team_scope_webchat_handoff_pool_teams__team_id__scope_patch";
+  updateWebchatHandoffPoolUserScope: "update_webchat_handoff_pool_user_scope_webchat_handoff_pool_users__user_id__scope_patch";
+  updateWebchatQuestion: "update_webchat_question_webchat_questions__question_id__patch";
+  updateWebchatSettings: "update_webchat_settings_webchat_settings_patch";
+  uploadWebchatImage: "upload_webchat_image_webchat_images_post";
+}
+
+/** Input and output of every `g8.api.webChat` operation, keyed by operationId. */
+export interface WebChatOperations {
+  /**
+   * POST /webchat/handoff-pool/teams
+   * Add Webchat Handoff Pool Teams
+   * tier: write · scope: inbox:write
+   */
+  add_webchat_handoff_pool_teams_webchat_handoff_pool_teams_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: HandoffPoolTeamsRequest;
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * POST /webchat/handoff-pool/users
+   * Add Webchat Handoff Pool Users
+   * tier: write · scope: inbox:write
+   */
+  add_webchat_handoff_pool_users_webchat_handoff_pool_users_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: HandoffPoolUsersRequest;
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * POST /webchat/assessments
+   * Create Assessment
+   * tier: write · scope: inbox:write
+   */
+  create_assessment_webchat_assessments_post: {
+    input: {
+    query: {
+      /** Owning chat bot id (UUID). */
+      chat_bot_id: string;
+    };
+    headers?: {
+      /** Retry-safety key. Replaying it returns the FIRST result. */
+      "Idempotency-Key"?: string | null;
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: AssessmentCreateRequest;
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * POST /webchat/chat-bots
+   * Create Chat Bot
+   * tier: write · scope: inbox:write
+   */
+  create_chat_bot_webchat_chat_bots_post: {
+    input: {
+    headers?: {
+      /** Retry-safety key for this create. Replaying the same key returns the FIRST result instead of creating a second row. Durability depends on the tenant's migration state, so treat it as best-effort. */
+      "Idempotency-Key"?: string | null;
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ChatBotCreateRequest;
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * POST /webchat/agents
+   * Create Webchat Agent
+   * tier: write · scope: inbox:write
+   */
+  create_webchat_agent_webchat_agents_post: {
+    input: {
+    headers?: {
+      /** Retry-safety key for this create. Replaying the same key returns the FIRST result instead of creating a second row. Durability depends on the tenant's migration state, so treat it as best-effort. */
+      "Idempotency-Key"?: string | null;
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: AgentCreateRequest;
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * POST /webchat/blogs
+   * Create Webchat Blog
+   * tier: write · scope: inbox:write
+   */
+  create_webchat_blog_webchat_blogs_post: {
+    input: {
+    headers?: {
+      /** Retry-safety key for this create. Replaying the same key returns the FIRST result instead of creating a second row. Durability depends on the tenant's migration state, so treat it as best-effort. */
+      "Idempotency-Key"?: string | null;
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: BlogCreateRequest;
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * POST /webchat/buttons
+   * Create Webchat Button
+   * tier: write · scope: inbox:write
+   */
+  create_webchat_button_webchat_buttons_post: {
+    input: {
+    headers?: {
+      /** Retry-safety key for this create. Replaying the same key returns the FIRST result instead of creating a second row. Durability depends on the tenant's migration state, so treat it as best-effort. */
+      "Idempotency-Key"?: string | null;
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ButtonCreateRequest;
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * POST /webchat/questions
+   * Create Webchat Question
+   * tier: write · scope: inbox:write
+   */
+  create_webchat_question_webchat_questions_post: {
+    input: {
+    headers?: {
+      /** Retry-safety key for this create. Replaying the same key returns the FIRST result instead of creating a second row. Durability depends on the tenant's migration state, so treat it as best-effort. */
+      "Idempotency-Key"?: string | null;
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: QuestionCreateRequest;
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * POST /webchat/settings
+   * Create Webchat Settings
+   * tier: write · scope: inbox:write
+   */
+  create_webchat_settings_webchat_settings_post: {
+    input: {
+    headers?: {
+      /** Retry-safety key for this create. Replaying the same key returns the FIRST result instead of creating a second row. Durability depends on the tenant's migration state, so treat it as best-effort. */
+      "Idempotency-Key"?: string | null;
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: SettingsCreateRequest;
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * DELETE /webchat/assessments/{assessment_id}
+   * Delete Assessment
+   * tier: destructive · scope: inbox:delete
+   */
+  delete_assessment_webchat_assessments__assessment_id__delete: {
+    input: {
+    path: {
+      /** Assessment id. */
+      assessment_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * DELETE /webchat/chat-bots/{bot_id}
+   * Delete Chat Bot
+   * tier: destructive · scope: inbox:delete
+   */
+  delete_chat_bot_webchat_chat_bots__bot_id__delete: {
+    input: {
+    path: {
+      /** Chat bot id (UUID). */
+      bot_id: string;
+    };
+    query?: {
+      /** Revision you last read. When given, a concurrent edit is a 409 instead of a silent overwrite. */
+      expected_revision?: number | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * DELETE /webchat/agents/{agent_id}
+   * Delete Webchat Agent
+   * tier: destructive · scope: inbox:delete
+   */
+  delete_webchat_agent_webchat_agents__agent_id__delete: {
+    input: {
+    path: {
+      /** Agent row id. */
+      agent_id: string;
+    };
+    query: {
+      /** Owning chat bot id (UUID). REQUIRED: an org can run several bots and this content belongs to one of them, so it identifies the rows rather than filtering them. */
+      chat_bot_id: string;
+      /** Revision you last read. When given, a concurrent edit is a 409 instead of a silent overwrite. */
+      expected_revision?: number | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * DELETE /webchat/blogs/{blog_id}
+   * Delete Webchat Blog
+   * tier: destructive · scope: inbox:delete
+   */
+  delete_webchat_blog_webchat_blogs__blog_id__delete: {
+    input: {
+    path: {
+      /** Article card id. */
+      blog_id: string;
+    };
+    query: {
+      /** Owning chat bot id (UUID). REQUIRED: an org can run several bots and this content belongs to one of them, so it identifies the rows rather than filtering them. */
+      chat_bot_id: string;
+      /** Revision you last read. When given, a concurrent edit is a 409 instead of a silent overwrite. */
+      expected_revision?: number | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * DELETE /webchat/buttons/{button_id}
+   * Delete Webchat Button
+   * tier: destructive · scope: inbox:delete
+   */
+  delete_webchat_button_webchat_buttons__button_id__delete: {
+    input: {
+    path: {
+      /** Button id. */
+      button_id: string;
+    };
+    query: {
+      /** Owning chat bot id (UUID). REQUIRED: an org can run several bots and this content belongs to one of them, so it identifies the rows rather than filtering them. */
+      chat_bot_id: string;
+      /** Revision you last read. When given, a concurrent edit is a 409 instead of a silent overwrite. */
+      expected_revision?: number | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * DELETE /webchat/questions/{question_id}
+   * Delete Webchat Question
+   * tier: destructive · scope: inbox:delete
+   */
+  delete_webchat_question_webchat_questions__question_id__delete: {
+    input: {
+    path: {
+      /** Question id. */
+      question_id: string;
+    };
+    query: {
+      /** Owning chat bot id (UUID). REQUIRED: an org can run several bots and this content belongs to one of them, so it identifies the rows rather than filtering them. */
+      chat_bot_id: string;
+      /** Revision you last read. When given, a concurrent edit is a 409 instead of a silent overwrite. */
+      expected_revision?: number | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * DELETE /webchat/settings
+   * Delete Webchat Settings
+   * tier: destructive · scope: inbox:delete
+   */
+  delete_webchat_settings_webchat_settings_delete: {
+    input: {
+    query: {
+      /** Owning chat bot id (UUID). REQUIRED: an org can run several bots and this content belongs to one of them, so it identifies the rows rather than filtering them. */
+      chat_bot_id: string;
+      /** Which widget: `external` (the customer-facing embed) or `internal` (graph8's own support widget). Omitted means `external`. */
+      surface?: ("external" | "internal") | null;
+      /** Revision you last read. When given, a concurrent edit is a 409 instead of a silent overwrite. */
+      expected_revision?: number | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * POST /webchat/blogs/fetch-metadata
+   * Fetch Webchat Blog Metadata
+   * tier: write · scope: inbox:write
+   */
+  fetch_webchat_blog_metadata_webchat_blogs_fetch_metadata_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: BlogMetadataRequest;
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * GET /webchat/assessments/{assessment_id}
+   * Get Assessment
+   * tier: read · scope: inbox:read
+   */
+  get_assessment_webchat_assessments__assessment_id__get: {
+    input: {
+    path: {
+      /** Assessment id. */
+      assessment_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * GET /webchat/handoff-pool
+   * Get Webchat Handoff Pool
+   * tier: read · scope: inbox:read
+   */
+  get_webchat_handoff_pool_webchat_handoff_pool_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * GET /webchat/handoff-pool-status
+   * Get Webchat Handoff Pool Status
+   * tier: read · scope: inbox:read
+   */
+  get_webchat_handoff_pool_status_webchat_handoff_pool_status_get: {
+    input: {
+    query?: {
+      /** Chat bot the widget serves; the pool is scoped per bot. */
+      chat_bot_id?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * GET /webchat/human-availability
+   * Get Webchat Human Availability
+   * tier: read · scope: inbox:read
+   */
+  get_webchat_human_availability_webchat_human_availability_get: {
+    input: {
+    query?: {
+      /** Chat bot id. OMIT for the org-wide default schedule. */
+      chat_bot_id?: string | null;
+      /** Which widget: `external` (the customer-facing embed) or `internal` (graph8's own support widget). Omitted means `external`. */
+      surface?: ("external" | "internal") | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * GET /webchat/settings
+   * Get Webchat Settings
+   * tier: read · scope: inbox:read
+   */
+  get_webchat_settings_webchat_settings_get: {
+    input: {
+    query: {
+      /** Owning chat bot id (UUID). REQUIRED: an org can run several bots and this content belongs to one of them, so it identifies the rows rather than filtering them. */
+      chat_bot_id: string;
+      /** Which widget: `external` (the customer-facing embed) or `internal` (graph8's own support widget). Omitted means `external`. */
+      surface?: ("external" | "internal") | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * GET /webchat/visitors/funnel
+   * Get Webchat Visitor Funnel
+   * tier: read · scope: inbox:read
+   */
+  get_webchat_visitor_funnel_webchat_visitors_funnel_get: {
+    input: {
+    query?: {
+      bot_id?: string | null;
+      page_url?: string | null;
+      /** ISO date, inclusive. */
+      date_from?: string | null;
+      /** ISO date, inclusive. */
+      date_to?: string | null;
+      /** Validated and echoed back; not yet applied to any figure. */
+      abandonment_window_minutes?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * GET /webchat/assessments
+   * List Assessments
+   * tier: read · scope: inbox:read
+   */
+  list_assessments_webchat_assessments_get: {
+    input: {
+    query?: {
+      /** Filter to one bot. OPTIONAL here, unlike the other webchat content routes - omitted returns every assessment in the org. */
+      chat_bot_id?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WebchatListPayload_;
+  };
+  /**
+   * GET /webchat/chat-bots
+   * List Chat Bots
+   * tier: read · scope: inbox:read
+   */
+  list_chat_bots_webchat_chat_bots_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WebchatListPayload_;
+  };
+  /**
+   * GET /webchat/agents
+   * List Webchat Agents
+   * tier: read · scope: inbox:read
+   */
+  list_webchat_agents_webchat_agents_get: {
+    input: {
+    query: {
+      /** Owning chat bot id (UUID). REQUIRED: an org can run several bots and this content belongs to one of them, so it identifies the rows rather than filtering them. */
+      chat_bot_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WebchatListPayload_;
+  };
+  /**
+   * GET /webchat/blogs
+   * List Webchat Blogs
+   * tier: read · scope: inbox:read
+   */
+  list_webchat_blogs_webchat_blogs_get: {
+    input: {
+    query: {
+      /** Owning chat bot id (UUID). REQUIRED: an org can run several bots and this content belongs to one of them, so it identifies the rows rather than filtering them. */
+      chat_bot_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WebchatListPayload_;
+  };
+  /**
+   * GET /webchat/buttons
+   * List Webchat Buttons
+   * tier: read · scope: inbox:read
+   */
+  list_webchat_buttons_webchat_buttons_get: {
+    input: {
+    query: {
+      /** Owning chat bot id (UUID). REQUIRED: an org can run several bots and this content belongs to one of them, so it identifies the rows rather than filtering them. */
+      chat_bot_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WebchatListPayload_;
+  };
+  /**
+   * GET /webchat/questions
+   * List Webchat Questions
+   * tier: read · scope: inbox:read
+   */
+  list_webchat_questions_webchat_questions_get: {
+    input: {
+    query: {
+      /** Owning chat bot id (UUID). REQUIRED: an org can run several bots and this content belongs to one of them, so it identifies the rows rather than filtering them. */
+      chat_bot_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WebchatListPayload_;
+  };
+  /**
+   * GET /webchat/teams/{team_id}/event-types
+   * List Webchat Team Event Types
+   * tier: read · scope: inbox:read
+   */
+  list_webchat_team_event_types_webchat_teams__team_id__event_types_get: {
+    input: {
+    path: {
+      /** Scheduling team id. */
+      team_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WebchatListPayload_;
+  };
+  /**
+   * GET /webchat/teams
+   * List Webchat Teams
+   * tier: read · scope: inbox:read
+   */
+  list_webchat_teams_webchat_teams_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WebchatListPayload_;
+  };
+  /**
+   * GET /webchat/visitors
+   * List Webchat Visitors
+   * tier: read · scope: inbox:read
+   */
+  list_webchat_visitors_webchat_visitors_get: {
+    input: {
+    query?: {
+      page?: number;
+      page_size?: number;
+      /** Only visitors the widget managed to identify. */
+      identified_only?: boolean;
+      search?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WebchatListPayload_;
+  };
+  /**
+   * POST /webchat/chat-bots/{bot_id}/promote-default
+   * Promote Chat Bot To Default
+   * tier: write · scope: inbox:write
+   */
+  promote_chat_bot_to_default_webchat_chat_bots__bot_id__promote_default_post: {
+    input: {
+    path: {
+      /** Chat bot id (UUID). */
+      bot_id: string;
+    };
+    query?: {
+      /** Revision you last read. When given, a concurrent edit is a 409 instead of a silent overwrite. */
+      expected_revision?: number | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * PUT /webchat/human-availability
+   * Put Webchat Human Availability
+   * tier: write · scope: inbox:write
+   */
+  put_webchat_human_availability_webchat_human_availability_put: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: HumanAvailabilityRequest;
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * DELETE /webchat/handoff-pool/teams/{team_id}
+   * Remove Webchat Handoff Pool Team
+   * tier: destructive · scope: inbox:delete
+   */
+  remove_webchat_handoff_pool_team_webchat_handoff_pool_teams__team_id__delete: {
+    input: {
+    path: {
+      /** Team id (UUID). */
+      team_id: string;
+    };
+    query?: {
+      /** Only the row in this pool. Omitted removes the person or team from every pool. `internal` is graph8's own support widget. */
+      pool?: ("external" | "internal") | null;
+      /** Only the row scoped to this chat bot. Omitted removes it across every bot. */
+      chat_bot_id?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * DELETE /webchat/handoff-pool/users/{user_id}
+   * Remove Webchat Handoff Pool User
+   * tier: destructive · scope: inbox:delete
+   */
+  remove_webchat_handoff_pool_user_webchat_handoff_pool_users__user_id__delete: {
+    input: {
+    path: {
+      /** Member user id. */
+      user_id: string;
+    };
+    query?: {
+      /** Only the row in this pool. Omitted removes the person or team from every pool. `internal` is graph8's own support widget. */
+      pool?: ("external" | "internal") | null;
+      /** Only the row scoped to this chat bot. Omitted removes it across every bot. */
+      chat_bot_id?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * PATCH /webchat/assessments/{assessment_id}
+   * Update Assessment
+   * tier: write · scope: inbox:write
+   */
+  update_assessment_webchat_assessments__assessment_id__patch: {
+    input: {
+    path: {
+      /** Assessment id. */
+      assessment_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: AssessmentUpdateRequest;
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * PATCH /webchat/chat-bots/{bot_id}
+   * Update Chat Bot
+   * tier: write · scope: inbox:write
+   */
+  update_chat_bot_webchat_chat_bots__bot_id__patch: {
+    input: {
+    path: {
+      /** Chat bot id (UUID). */
+      bot_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ChatBotUpdateRequest;
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * PATCH /webchat/agents/{agent_id}
+   * Update Webchat Agent
+   * tier: write · scope: inbox:write
+   */
+  update_webchat_agent_webchat_agents__agent_id__patch: {
+    input: {
+    path: {
+      /** Agent row id. */
+      agent_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: AgentUpdateRequest;
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * PATCH /webchat/blogs/{blog_id}
+   * Update Webchat Blog
+   * tier: write · scope: inbox:write
+   */
+  update_webchat_blog_webchat_blogs__blog_id__patch: {
+    input: {
+    path: {
+      /** Article card id. */
+      blog_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: BlogUpdateRequest;
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * PATCH /webchat/buttons/{button_id}
+   * Update Webchat Button
+   * tier: write · scope: inbox:write
+   */
+  update_webchat_button_webchat_buttons__button_id__patch: {
+    input: {
+    path: {
+      /** Button id. */
+      button_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ButtonUpdateRequest;
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * PATCH /webchat/handoff-pool/teams/{team_id}/scope
+   * Update Webchat Handoff Pool Team Scope
+   * tier: write · scope: inbox:write
+   */
+  update_webchat_handoff_pool_team_scope_webchat_handoff_pool_teams__team_id__scope_patch: {
+    input: {
+    path: {
+      /** Team id (UUID). */
+      team_id: string;
+    };
+    query?: {
+      /** Pool to re-scope. Only `external` is accepted by the app: the internal pool is not per-bot. */
+      pool?: "external" | "internal";
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: HandoffPoolScopeRequest;
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * PATCH /webchat/handoff-pool/users/{user_id}/scope
+   * Update Webchat Handoff Pool User Scope
+   * tier: write · scope: inbox:write
+   */
+  update_webchat_handoff_pool_user_scope_webchat_handoff_pool_users__user_id__scope_patch: {
+    input: {
+    path: {
+      /** Member user id. */
+      user_id: string;
+    };
+    query?: {
+      /** Pool to re-scope. Only `external` is accepted by the app: the internal pool is not per-bot. */
+      pool?: "external" | "internal";
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: HandoffPoolScopeRequest;
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * PATCH /webchat/questions/{question_id}
+   * Update Webchat Question
+   * tier: write · scope: inbox:write
+   */
+  update_webchat_question_webchat_questions__question_id__patch: {
+    input: {
+    path: {
+      /** Question id. */
+      question_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: QuestionUpdateRequest;
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * PATCH /webchat/settings
+   * Update Webchat Settings
+   * tier: write · scope: inbox:write
+   */
+  update_webchat_settings_webchat_settings_patch: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: SettingsUpdateRequest;
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+  /**
+   * POST /webchat/images
+   * Upload Webchat Image
+   * tier: write · scope: inbox:write
+   */
+  upload_webchat_image_webchat_images_post: {
+    input: {
+    query?: {
+      /** `header` (the widget header image) or `avatar` (the assistant avatar). Only selects where the file is stored. */
+      purpose?: "header" | "avatar";
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WebchatPayload_;
+  };
+}
+
+// 45 schemas referenced above (the same as G8Contract.<Name>).
+
+/** Map an AI agent onto the URLs it should answer on. */
+export interface AgentCreateRequest {
+  active?: boolean;
+  /** Agent id from agent settings. */
+  agent_id?: string | null;
+  agent_name: string;
+  /** Owning chat bot id (UUID). */
+  chat_bot_id: string;
+  /** Used when no URL filter matches. */
+  default?: boolean;
+  surface?: ("external" | "internal") | null;
+  /** URL paths where this agent is active. */
+  url_filter?: Array<string>;
+}
+
+/**
+ * Partial edit of an agent mapping. `chat_bot_id` stays required.
+ *
+ * It is not a field being changed - it is how the app FINDS the row, because
+ * agent ids are unique per bot rather than per org.
+ */
+export interface AgentUpdateRequest {
+  active?: boolean | null;
+  agent_id?: string | null;
+  agent_name?: string | null;
+  /** Owning chat bot id (UUID). */
+  chat_bot_id: string;
+  default?: boolean | null;
+  expected_revision?: number | null;
+  surface?: ("external" | "internal") | null;
+  url_filter?: Array<string> | null;
+}
+
+export interface ApiResponse_WebchatListPayload_ {
+  data: WebchatListPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_WebchatPayload_ {
+  data: WebchatPayload;
+  pagination?: PaginationMeta | null;
+}
+
+/** A single selectable answer within an assessment step. */
+export interface AssessmentAnswerDef {
+  id: string;
+  next_step_id?: string | null;
+  result_id?: string | null;
+  text: string;
+}
+
+/**
+ * A guided question flow the widget can run with a visitor.
+ *
+ * `definition` is the flow itself - a start step, the steps, and the results
+ * they lead to. It is the app's own `AssessmentDefinition`, so a graph that
+ * names a step it does not define is a 422 here rather than a dead end the
+ * visitor walks into.
+ */
+export interface AssessmentCreateRequest {
+  /** The flow: `{start_step_id, steps[], results[]}`. */
+  definition: AssessmentDefinition;
+  description?: string | null;
+  name: string;
+  surface?: ("external" | "internal") | null;
+}
+
+/** Complete branching graph stored as JSONB in chat_assessments.definition. */
+export interface AssessmentDefinition {
+  results?: Array<AssessmentResultDef>;
+  start_step_id: string;
+  steps?: Array<AssessmentStepDef>;
+}
+
+/** A terminal result node — shown when the visitor's path leads here. */
+export interface AssessmentResultDef {
+  body?: string;
+  booking_enabled?: boolean;
+  handoff_enabled?: boolean;
+  id: string;
+  links?: Array<AssessmentResultLink>;
+  title: string;
+}
+
+export interface AssessmentResultLink {
+  label: string;
+  url: string;
+}
+
+/** One question-and-answers step in the assessment flow. */
+export interface AssessmentStepDef {
+  allow_free_text?: boolean;
+  answers?: Array<AssessmentAnswerDef>;
+  id: string;
+  question: string;
+}
+
+/**
+ * Partial edit of an assessment.
+ *
+ * `revision` is this model's optimistic-concurrency field. Note it is spelled
+ * `revision` here and `expected_revision` on every other webchat model - that
+ * is the app's own inconsistency, and it is mirrored rather than tidied,
+ * because renaming it would send the app a field it does not read and the
+ * concurrency check would silently stop happening.
+ */
+export interface AssessmentUpdateRequest {
+  active?: boolean | null;
+  definition?: AssessmentDefinition | null;
+  description?: string | null;
+  name?: string | null;
+  /** Revision you last read. See the note above on the name. */
+  revision?: number | null;
+  surface?: ("external" | "internal") | null;
+}
+
+/** A weekly recurring window. `day` is 0-6 with Monday = 0. */
+export interface AvailabilityInterval {
+  day: number;
+  end: string;
+  start: string;
+}
+
+/**
+ * A single calendar date whose windows REPLACE that weekday's windows.
+ *
+ * An empty `intervals` list means closed all day — that is the whole point of an
+ * override, so it is not treated as "unset". Window `day` values are ignored
+ * here (the date already fixes the day), and a client that sends one has it
+ * dropped by Pydantic's default `extra="ignore"`.
+ */
+export interface AvailabilityOverride {
+  date: string;
+  intervals?: Array<AvailabilityWindow>;
+}
+
+/**
+ * One open window inside a single day, as wall-clock `HH:MM`.
+ *
+ * `end <= start` means the window crosses midnight into the next day; `"24:00"`
+ * is a legal `end` only and means end-of-day.
+ *
+ * Both fields pin an exact LENGTH as well as a pattern, because a container's
+ * `max_length` bounds the element COUNT and never a nested string — the bound on
+ * the string itself has to live here.
+ *
+ * The length pin is redundant against today's engine and kept anyway: pydantic
+ * compiles this pattern with the Rust regex crate, whose `$` matches only at the
+ * end of the haystack, so "09:00\n" is already rejected. Python's `re`, which
+ * pydantic falls back to for patterns the Rust engine cannot compile, matches `$`
+ * BEFORE a trailing newline and would let it through. Five characters cannot hold
+ * a newline either way, so the pin makes the guarantee engine-independent.
+ */
+export interface AvailabilityWindow {
+  end: string;
+  start: string;
+}
+
+/**
+ * An article card in the widget's rail.
+ *
+ * `url` and `image_url` are validated by the app to be http/https; a scheme
+ * it refuses is a 422 here rather than a broken card later.
+ */
+export interface BlogCreateRequest {
+  active?: boolean;
+  /** Owning chat bot id (UUID). */
+  chat_bot_id: string;
+  description?: string | null;
+  /** Lower sorts first; ties break newest-first. */
+  display_order?: number;
+  image_url?: string | null;
+  paths?: Array<string>;
+  surface?: ("external" | "internal") | null;
+  title: string;
+  url: string;
+}
+
+/**
+ * A URL to read Open Graph metadata from.
+ *
+ * Persists NOTHING. It fetches the page and returns its `og:title`,
+ * `og:description` and `og:image` so a caller can pre-fill an article card
+ * instead of typing it - which is why it is tiered a read despite the verb.
+ */
+export interface BlogMetadataRequest {
+  /** Page to read og:title / og:description / og:image from. */
+  url: string;
+}
+
+/** Partial edit of an article card. `chat_bot_id` locates the row. */
+export interface BlogUpdateRequest {
+  active?: boolean | null;
+  /** Owning chat bot id (UUID). */
+  chat_bot_id: string;
+  description?: string | null;
+  display_order?: number | null;
+  expected_revision?: number | null;
+  image_url?: string | null;
+  paths?: Array<string> | null;
+  surface?: ("external" | "internal") | null;
+  title?: string | null;
+  url?: string | null;
+}
+
+/**
+ * A quick-action button in the widget.
+ *
+ * `value` means something different per `action`: a URL for `link`, the
+ * question text for `question`, a calendar slug for `calendar`. Sending the
+ * wrong kind is accepted here and fails at the widget, so it is spelled out
+ * rather than left to be discovered.
+ */
+export interface ButtonCreateRequest {
+  action: "link" | "question" | "calendar";
+  active?: boolean;
+  category: string;
+  /** Owning chat bot id (UUID). */
+  chat_bot_id: string;
+  icon?: string | null;
+  label: string;
+  /** URL paths where the button appears. */
+  paths?: Array<string>;
+  /** NULL shows it on BOTH widgets. */
+  surface?: ("external" | "internal") | null;
+  /** URL for `link`, question text for `question`, slug for `calendar`. */
+  value: string;
+}
+
+/** Partial edit of a button. `chat_bot_id` locates the row. */
+export interface ButtonUpdateRequest {
+  action?: ("link" | "question" | "calendar") | null;
+  active?: boolean | null;
+  category?: string | null;
+  /** Owning chat bot id (UUID). */
+  chat_bot_id: string;
+  expected_revision?: number | null;
+  icon?: string | null;
+  label?: string | null;
+  paths?: Array<string> | null;
+  surface?: ("external" | "internal") | null;
+  value?: string | null;
+}
+
+/**
+ * A new chat bot.
+ *
+ * An org can run several. `chat_bot_id` is REQUIRED on almost every other
+ * call on this surface because the same org's agents, buttons, questions,
+ * blogs and theme are all per-bot - so create one of these first, or read the
+ * org's existing bots from `GET /webchat/chat-bots`.
+ */
+export interface ChatBotCreateRequest {
+  /** Optional voice/text agent id used to seed the new bot's external chat agent. When omitted, no agent row is created. */
+  agent_id?: string | null;
+  /** Display name of the selected agent. Stored on the agent row so the widget shows the AGENT's name, not the bot's. Falls back to the bot name when omitted. */
+  agent_name?: string | null;
+  name: string;
+}
+
+/**
+ * Rename a chat bot.
+ *
+ * `name` is REQUIRED even though this is a PATCH - it is the only mutable
+ * field, and the app's model requires it. `expected_revision` is the
+ * optimistic-concurrency check: send the revision you read, and a concurrent
+ * edit comes back 409 rather than silently overwriting.
+ */
+export interface ChatBotUpdateRequest {
+  /** Revision you last read. Omit to overwrite unconditionally. */
+  expected_revision?: number | null;
+  name: string;
+}
+
+/** Unread launcher-badge colors (hex-validated). */
+export interface DesignTokenBadge {
+  background?: string | null;
+  text?: string | null;
+}
+
+/**
+ * Color slots consumed by the widget's --wcw-* CSS var vocabulary.
+ *
+ * LIGHT-mode and mode-invariant leaves ONLY. Per-mode dark variants live on the
+ * sibling ``DesignTokenColorsDark`` group (``designTokens.colorsDark``), NOT as
+ * ``*Dark`` twins here (Phase G). The ``@field_validator("*")`` hex guard below
+ * is exactly WHY the dark palette must be a sibling group rather than a nested
+ * ``colors.dark`` object — a nested dict would be fed to ``_require_hex_color``
+ * and 422 the save (the same force that made ``DesignTokenHeader`` separate).
+ * A legacy stored ``colors.<name>Dark`` leaf is lifted into ``colorsDark`` at
+ * parse time by ``DesignTokens._lift_legacy_dark_leaves`` — no data migration.
+ */
+export interface DesignTokenColors {
+  /** Quick-action card bg (light) */
+  actionCardBg?: string | null;
+  /** Quick-action card border (light) */
+  actionCardBorder?: string | null;
+  /** Quick-action icon-circle tint (light) */
+  actionCardIconTint?: string | null;
+  /** Quick-action card label (light) */
+  actionCardText?: string | null;
+  /** Human-agent bubble bg (light) */
+  agentBubbleBg?: string | null;
+  /** Human-agent bubble border (light) */
+  agentBubbleBorder?: string | null;
+  /** Human-agent bubble text (light) */
+  agentBubbleText?: string | null;
+  /** Ask-a-question card bg (light) */
+  askCardBg?: string | null;
+  /** Ask-a-question card border (light) */
+  askCardBorder?: string | null;
+  /** Ask-a-question card text (light) */
+  askCardText?: string | null;
+  border?: string | null;
+  bubbleAssistantBg?: string | null;
+  bubbleAssistantText?: string | null;
+  bubbleUserBg?: string | null;
+  bubbleUserText?: string | null;
+  headerGradientFrom?: string | null;
+  headerGradientTo?: string | null;
+  /** Home hero greeting text */
+  heroText?: string | null;
+  /** Home hero subtitle text */
+  heroTextMuted?: string | null;
+  launcherBg?: string | null;
+  launcherIcon?: string | null;
+  link?: string | null;
+  /** Messages search bar bg (light) */
+  messagesSearchBg?: string | null;
+  /** Messages search bar border (opt-in) */
+  messagesSearchBorder?: string | null;
+  /** Messages search text (light) */
+  messagesSearchText?: string | null;
+  /** Messages screen title text */
+  messagesTitleText?: string | null;
+  /** Composer send-button bg */
+  sendButtonBg?: string | null;
+  /** Composer send-button icon */
+  sendButtonIcon?: string | null;
+  /** Slot-picker chip bg (light) */
+  slotChipBg?: string | null;
+  /** Slot-picker chip hover bg (light) */
+  slotChipHoverBg?: string | null;
+  /** Slot-picker chip hover border (light) */
+  slotChipHoverBorder?: string | null;
+  /** Slot-picker chip text (light) */
+  slotChipText?: string | null;
+  /** Widget body bg (light) */
+  surface?: string | null;
+  textPrimary?: string | null;
+  textSecondary?: string | null;
+  /** Typing-indicator dot (light) */
+  typingDot?: string | null;
+}
+
+/**
+ * Per-mode DARK colour overrides (``designTokens.colorsDark``, Phase G).
+ *
+ * A sibling of ``DesignTokenColors`` holding the dark variant of every colour
+ * leaf that renders differently in dark mode. ABSENT ⇒ the widget renders
+ * exactly as it did before this group existed (the dark literal, or — for a
+ * leaf an org set in ``colors`` and that historically painted both modes — that
+ * ``colors`` value). Only leaves with a genuine dark render path live here; a
+ * mode-invariant leaf (launcher, header gradient, send button, hero) has no
+ * entry, so no dead tokens are introduced.
+ *
+ * Field names carry NO ``Dark`` suffix — the group is the mode. The 13 leaves
+ * that previously lived as ``colors.<name>Dark`` twins were migrated here; the
+ * upconverter on ``DesignTokens`` lifts any legacy value so no row regresses.
+ */
+export interface DesignTokenColorsDark {
+  /** Quick-action card bg (dark) */
+  actionCardBg?: string | null;
+  /** Quick-action card border (dark) */
+  actionCardBorder?: string | null;
+  /** Quick-action icon-circle tint (dark) */
+  actionCardIconTint?: string | null;
+  /** Quick-action card label (dark) */
+  actionCardText?: string | null;
+  /** Human-agent bubble bg (dark) */
+  agentBubbleBg?: string | null;
+  /** Human-agent bubble border (dark) */
+  agentBubbleBorder?: string | null;
+  /** Human-agent bubble text (dark) */
+  agentBubbleText?: string | null;
+  /** Ask-a-question card bg (dark) */
+  askCardBg?: string | null;
+  /** Ask-a-question card border (dark) */
+  askCardBorder?: string | null;
+  /** Ask-a-question card text (dark) */
+  askCardText?: string | null;
+  /** Borders & dividers (dark) */
+  border?: string | null;
+  /** Bot bubble bg (dark) */
+  bubbleAssistantBg?: string | null;
+  /** Bot bubble text (dark) */
+  bubbleAssistantText?: string | null;
+  /** Composer emoji-popover bg (dark) */
+  composerPopoverBg?: string | null;
+  /** Composer emoji-popover border (dark) */
+  composerPopoverBorder?: string | null;
+  /** Messages search bar bg (dark) */
+  messagesSearchBg?: string | null;
+  /** Messages search text (dark) */
+  messagesSearchText?: string | null;
+  /** Slot-picker chip bg (dark) */
+  slotChipBg?: string | null;
+  /** Slot-picker chip hover bg (dark) */
+  slotChipHoverBg?: string | null;
+  /** Slot-picker chip hover border (dark) */
+  slotChipHoverBorder?: string | null;
+  /** Slot-picker chip text (dark) */
+  slotChipText?: string | null;
+  /** Widget body bg (dark) */
+  surface?: string | null;
+  /** Message text (dark) */
+  textPrimary?: string | null;
+  /** Timestamps & meta text (dark) */
+  textSecondary?: string | null;
+  /** Typing-indicator dot (dark) */
+  typingDot?: string | null;
+}
+
+/**
+ * RFC Phase E4 — launcher / panel / badge / chip geometry, CLAMPED.
+ *
+ * The most locked-down group in the model, because `chat-script` injects these
+ * into the CUSTOMER's page rather than into the widget iframe (RFC §17.1).
+ * Unclamped geometry on a host page is a defacement vector, so every leaf is
+ * whole-pixel-only and range-bounded — see `_require_px_in_range`.
+ *
+ * Ranges for `launcherSize` / `launcherOffset*` are INHERITED from the ratified
+ * product decision (RFC §19 decision 4: "launcher geometry in scope with
+ * clamped ranges — size ~36-64px, offsets ~8-48px"), not invented here.
+ *
+ * Widget COLLAPSED WIDTH is deliberately absent: it is already plumbed as the
+ * flat `chatWidth` column and read at runtime by the deployed bundle, so a
+ * token would be a second writer for one property.
+ *
+ * ── TWO CLAMPS ARE ONE-DIRECTIONAL (max pinned at today's value) ────────────
+ * `widgetWidthExpanded` (max 640) and `launcherOffsetX` (max 20) may only ever
+ * SHRINK. This is not conservatism, it is a live constraint:
+ *
+ * The expanded panel needs a `widgetWidthExpanded + launcherOffsetX` viewport
+ * to fit, but the mobile veto that hides the expand control is the hardcoded
+ * `MOBILE_BREAKPOINT_PX = 560` (`chat-script/src/components/container.ts`,
+ * mirrored as a literal `@media (max-width: 560px)` in `styles.ts`). Today's
+ * 640 + 20 = 660 already exceeds it, so viewports 561-659px ALREADY render an
+ * overflowing panel — a pre-existing defect (GH #12173). Letting either value
+ * GROW would widen that band onto more real devices.
+ *
+ * A media-query CONDITION cannot read a custom property, so the guard cannot be
+ * derived the way the panel's `bottom` is; correcting it means making
+ * `MOBILE_BREAKPOINT_PX` config-derived across `container.ts` + `expand.ts` +
+ * the emitted media query. That is GH #12173, and it is what lifts these two
+ * ceilings. Until it lands, 640 and 20 are load-bearing — do not raise them.
+ *
+ * THE RULE, so it is applied correctly next time: an axis needs a
+ * one-directional clamp exactly when it has NO viewport clamp. The horizontal
+ * axis has none. The vertical axis has `calc(100dvh - 140px)`, and the worst
+ * case under these ranges is `launcherOffsetY(48) + launcherSize(64) + gap(11)
+ * = 123px`, which stays inside that 140px reserve with 17px to spare at every
+ * viewport height — which is why `launcherOffsetY`, `launcherSize`, `badgeSize`
+ * and `chipGap` are free to grow. Any future range change must preserve
+ * `launcherOffsetY + launcherSize + 11 <= 140`.
+ */
+export interface DesignTokenGeometry {
+  badgeSize?: string | null;
+  chipGap?: string | null;
+  launcherOffsetX?: string | null;
+  launcherOffsetY?: string | null;
+  launcherSize?: string | null;
+  widgetHeight?: string | null;
+  widgetHeightExpanded?: string | null;
+  widgetWidthExpanded?: string | null;
+}
+
+/**
+ * How the header surface is painted — mode + gradient blend point.
+ *
+ * A SEPARATE group, not new `DesignTokenColors` slots, and that is forced:
+ * `DesignTokenColors` hex-validates EVERY field (`@field_validator("*")`), so a
+ * `"solid"` mode or a numeric stop there would 422 the whole save.
+ *
+ * Both leaves are ABSENT by default and absence is meaningful — it means
+ * "render exactly as this org rendered before this group existed":
+ *
+ * * ``mode`` absent  -> gradient (today's only behaviour).
+ * * ``fromStop`` absent -> no interpolation hint is emitted at all, so the CSS
+ *   is byte-identical to the legacy string (see `buildWidgetCssVars`). The
+ *   50/50 default is therefore expressed as ABSENCE, never as a written 50 —
+ *   existing rows keep rendering without relying on hint-equivalence.
+ */
+export interface DesignTokenHeader {
+  angle?: number | null;
+  fromStop?: number | null;
+  mode?: ("solid" | "gradient") | null;
+}
+
+/** Composer input surface colors (hex-validated). */
+export interface DesignTokenInput {
+  background?: string | null;
+  borderColor?: string | null;
+  focusBorderColor?: string | null;
+}
+
+/** Interaction motion — one duration (<time>) + one timing-function. */
+export interface DesignTokenMotion {
+  duration?: string | null;
+  easing?: string | null;
+}
+
+/** Border-radius slots (CSS dimensions; launcher is typically 50%). */
+export interface DesignTokenRadius {
+  bubble?: string | null;
+  control?: string | null;
+  input?: string | null;
+  launcher?: string | null;
+  widget?: string | null;
+}
+
+/** box-shadow slots — charset-restricted, see _require_css_shadow. */
+export interface DesignTokenShadows {
+  bubble?: string | null;
+  launcher?: string | null;
+  launcherHover?: string | null;
+  suggested?: string | null;
+  widget?: string | null;
+}
+
+/** Spacing slots — padding shorthand (1-4 dims) and single-dim gaps. */
+export interface DesignTokenSpacing {
+  bubblePadding?: string | null;
+  sectionGap?: string | null;
+}
+
+/**
+ * RFC Phase E3 — interaction transform SCALES (unitless multipliers).
+ *
+ * Motion *timing* (duration + easing) already shipped as `DesignTokenMotion`;
+ * this is the other half of E3. Every leaf is optional and absence means "the
+ * literal `chat-script/src/styles.ts` ships today", so `transform` absent =
+ * byte-identical rendering.
+ *
+ * Each leaf carries its OWN range because the ranges are semantic, not
+ * cosmetic: a "grow" interaction above ~1.2 reads as a glitch rather than
+ * feedback, and a "press" interaction must stay at or below 1.0 or the element
+ * grows when pushed.
+ *
+ * Rotation is deliberately NOT here. RFC §16 scopes E3 to *scales*, and the
+ * launcher's icon swap uses a ±90deg PAIR that must stay symmetric — one leaf
+ * would invite an asymmetric swap, two would invite a broken one.
+ */
+export interface DesignTokenTransform {
+  chipActive?: string | null;
+  chipHover?: string | null;
+  launcherActive?: string | null;
+  launcherHover?: string | null;
+  rippleFrom?: string | null;
+  rippleTo?: string | null;
+  windowEnter?: string | null;
+}
+
+/** Font family / weights. fontUrl is an optional CSS URL (Google Fonts css2). */
+export interface DesignTokenTypography {
+  bodyWeight?: number | null;
+  fontFamily?: string | null;
+  fontSize?: string | null;
+  fontUrl?: string | null;
+  headingWeight?: number | null;
+  letterSpacing?: string | null;
+  lineHeight?: string | null;
+}
+
+/**
+ * Extended widget theme tokens stored in chat_widget_settings.designTokens.
+ *
+ * Shape is the shared FE/BE contract — the TypeScript twin lives in
+ * frontend/features/webchat/widget-preview/chat-design-settings.ts.
+ */
+export interface DesignTokens {
+  badge?: DesignTokenBadge | null;
+  colors?: DesignTokenColors | null;
+  colorsDark?: DesignTokenColorsDark | null;
+  geometry?: DesignTokenGeometry | null;
+  header?: DesignTokenHeader | null;
+  input?: DesignTokenInput | null;
+  motion?: DesignTokenMotion | null;
+  radius?: DesignTokenRadius | null;
+  shadows?: DesignTokenShadows | null;
+  spacing?: DesignTokenSpacing | null;
+  transform?: DesignTokenTransform | null;
+  typography?: DesignTokenTypography | null;
+  version?: number;
+}
+
+/** The COMPLETE new bot scope. Empty list = every bot; bots left out are dropped. */
+export interface HandoffPoolScopeRequest {
+  chat_bot_ids?: Array<string>;
+}
+
+/** Teams to add to the handoff pool. Same bot-scoping rules as people. */
+export interface HandoffPoolTeamsRequest {
+  chat_bot_ids?: Array<string>;
+  pool?: "external" | "internal";
+  team_ids: Array<string>;
+}
+
+/**
+ * People to add to the handoff pool.
+ *
+ * `chat_bot_ids` empty means EVERY bot. Non-empty is valid only for the
+ * `external` pool - the internal pool is not per-bot, and the app refuses
+ * the combination with a 422. Both lists are capped at 200 by the app to
+ * bound the per-person-per-bot rows one call can write.
+ */
+export interface HandoffPoolUsersRequest {
+  chat_bot_ids?: Array<string>;
+  pool?: "external" | "internal";
+  user_ids: Array<string>;
+}
+
+/**
+ * When a human is available to take a handed-off conversation.
+ *
+ * THIS IS WHAT DECIDES WHETHER A VISITOR IS OFFERED A PERSON. Turning it on
+ * with no reachable interval is worse than leaving it off: the widget offers
+ * a handover nobody answers. The app refuses the unreachable shapes; this
+ * forwards its answer.
+ *
+ * `intervals` and `overrides` use the app's own window models, which reject a
+ * zero-length window and refuse overlapping ones - see the module docstring.
+ */
+export interface HumanAvailabilityRequest {
+  /** Bot this schedule applies to. NULL is the org default. */
+  chat_bot_id?: string | null;
+  enabled?: boolean;
+  /** Weekly windows: `{day: 0-6, start: 'HH:MM', end: 'HH:MM'}`. */
+  intervals?: Array<AvailabilityInterval>;
+  /** Date overrides: `{date: 'YYYY-MM-DD', intervals: [...]}`. */
+  overrides?: Array<AvailabilityOverride>;
+  surface?: ("external" | "internal") | null;
+  /** IANA zone the intervals are expressed in. */
+  timezone?: string;
+}
+
+export interface PaginationMeta {
+  /** Whether there are more pages */
+  has_next: boolean;
+  /** Items per page */
+  limit: number;
+  /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
+  next_cursor?: string | null;
+  /** Current page number (1-indexed) */
+  page: number;
+  /** Total number of items */
+  total: number;
+}
+
+/**
+ * A preset question the widget offers.
+ *
+ * `placements` NULL or empty means ALL placements, not none - the app treats
+ * the absent case as unrestricted, and reading it the other way would hide
+ * every question a caller created without naming one.
+ */
+export interface QuestionCreateRequest {
+  active?: boolean;
+  category?: string | null;
+  /** Owning chat bot id (UUID). */
+  chat_bot_id: string;
+  paths?: Array<string>;
+  /** NULL or [] means every placement. */
+  placements?: (Array<"launcher" | "home" | "conversation">) | null;
+  question: string;
+  /** Order within a placement. NULL sorts last. */
+  sort_order?: number | null;
+  /** NULL shows it on BOTH widgets. */
+  surface?: ("external" | "internal") | null;
+}
+
+/** Partial edit of a preset question. `chat_bot_id` locates the row. */
+export interface QuestionUpdateRequest {
+  active?: boolean | null;
+  category?: string | null;
+  /** Owning chat bot id (UUID). */
+  chat_bot_id: string;
+  expected_revision?: number | null;
+  paths?: Array<string> | null;
+  placements?: (Array<"launcher" | "home" | "conversation">) | null;
+  question?: string | null;
+  sort_order?: number | null;
+  surface?: ("external" | "internal") | null;
+}
+
+/**
+ * The widget's whole appearance and behaviour, for one bot and surface.
+ *
+ * Every colour is validated as a hex value, every dimension as a CSS length,
+ * and two MODEL-level guards reject an illegible text/background pair and an
+ * absurd design-token magnitude. All of those live in the app's model, which
+ * is what this mirrors - see the module docstring on why `designTokens` is
+ * imported rather than re-declared.
+ *
+ * ONE SETTINGS ROW PER (bot, surface). Creating a second is a 409, not a
+ * second row; use `PATCH /webchat/settings` to change one that exists.
+ */
+export interface SettingsCreateRequest {
+  assistantMessageBgColor?: string;
+  assistantMessageTextColor?: string;
+  assistantName?: string;
+  borderRadius?: string;
+  botAvatarCustomUrl?: string | null;
+  botAvatarMode?: "agent" | "preset" | "custom";
+  botAvatarPresetUrl?: string | null;
+  botIconType?: string;
+  chatWidth?: string;
+  /** Owning chat bot id (UUID). */
+  chat_bot_id: string;
+  copyOverrides?: Record<string, string> | null;
+  darkMode?: boolean;
+  /** Design-token tree. The app's own model, so the magnitude guard runs here rather than inside the proxy. */
+  designTokens?: DesignTokens | null;
+  fontFamily?: string;
+  fontSize?: string;
+  headerImageUrlExternal?: string | null;
+  headerImageUrlInternal?: string | null;
+  headerTextColor?: string;
+  primaryColor?: string;
+  robotIconColor?: string;
+  robotIconType?: string;
+  secondaryColor?: string;
+  showHeader?: boolean;
+  showQuickActions?: boolean;
+  showSuggestedQuestions?: boolean;
+  suggestedQuestionsBgColor?: string;
+  suggestedQuestionsSectionBgColor?: string;
+  /** Which widget this theme applies to. Omitted means `external`. `internal` is graph8's own support widget and is refused for any other org. */
+  surface?: ("external" | "internal") | null;
+  themeSource?: "default" | "brand_kit" | "custom";
+  userMessageBgColor?: string;
+  userMessageTextColor?: string;
+}
+
+/**
+ * Partial edit of the widget theme. An unset field is left untouched.
+ *
+ * `themeOverridesRemove` is the only way to DELETE a token override rather
+ * than set it to something - sending `null` for a token would be "unset in
+ * this request", which the partial-update rule reads as "leave it alone".
+ */
+export interface SettingsUpdateRequest {
+  assistantMessageBgColor?: string | null;
+  assistantMessageTextColor?: string | null;
+  assistantName?: string | null;
+  borderRadius?: string | null;
+  botAvatarCustomUrl?: string | null;
+  botAvatarMode?: ("agent" | "preset" | "custom") | null;
+  botAvatarPresetUrl?: string | null;
+  botIconType?: string | null;
+  chatWidth?: string | null;
+  /** Owning chat bot id (UUID). */
+  chat_bot_id: string;
+  conversationQuestionLimit?: number | null;
+  conversationQuestionsAfterFirstMessage?: ("hide" | "remain" | "collapse") | null;
+  copyOverrides?: Record<string, string> | null;
+  darkMode?: boolean | null;
+  designTokens?: DesignTokens | null;
+  expected_revision?: number | null;
+  fontFamily?: string | null;
+  fontSize?: string | null;
+  headerImageUrlExternal?: string | null;
+  headerImageUrlInternal?: string | null;
+  headerTextColor?: string | null;
+  homeQuestionLimit?: number | null;
+  launcherQuestionLimit?: number | null;
+  primaryColor?: string | null;
+  robotIconColor?: string | null;
+  robotIconType?: string | null;
+  secondaryColor?: string | null;
+  showHeader?: boolean | null;
+  showQuickActions?: boolean | null;
+  showSuggestedQuestions?: boolean | null;
+  suggestedQuestionsBgColor?: string | null;
+  suggestedQuestionsSectionBgColor?: string | null;
+  surface?: ("external" | "internal") | null;
+  /** Token paths to REMOVE. Unsetting a token is not the same as this. */
+  themeOverridesRemove?: Array<string> | null;
+  themeSource?: ("default" | "brand_kit" | "custom") | null;
+  userMessageBgColor?: string | null;
+  userMessageTextColor?: string | null;
+}
+
+/** An open envelope for a LIST result, so a bare list keeps its shape. */
+export interface WebchatListPayload {
+  items?: Array<unknown>;
+  [key: string]: unknown;
+}
+
+/**
+ * An open envelope for one webchat object.
+ *
+ * Open because the widget's config grows a field per product decision and a
+ * pinned schema would DROP it. Same choice the desk surface made.
+ */
+export type WebchatPayload = Record<string, unknown>;