@cntyclub/agent-react 0.1.1 → 0.2.0

package/README.md

@@ -84,6 +84,32 @@ export function DashboardAgent() {
 `pages` + `navigate` power **page-follow**: in popup mode, when the agent uses a tool
 that maps to a page, the host app navigates there while the chat shows the same data.
 
+## API schema (OpenAPI)
+
+The backend publishes a dedicated, scoped OpenAPI document for Agent Mode:
+
+- **Schema**: `GET {API_BASE}/agent-mode/schema/` (YAML)
+- **Swagger UI**: `{API_BASE}/agent-mode/docs/`
+
+This repo vendors that document at [`api-spec/agent-mode-api.yaml`](api-spec/agent-mode-api.yaml)
+and generates TypeScript types from it into `src/api/schema.ts` (committed). All wire
+types in `src/types.ts` derive from the generated schema, so the client cannot drift
+from the backend contract silently.
+
+**Update workflow** when the backend API changes:
+
+```bash
+curl https://api.country.club/agent-mode/schema/ -o api-spec/agent-mode-api.yaml
+pnpm gen:api        # regenerates src/api/schema.ts
+pnpm typecheck      # surfaces any breaking contract changes immediately
+```
+
+Consumers can also import the full typed surface for their own tooling:
+
+```ts
+import type { AgentModePaths, AgentModeComponents, AgentModeOperations } from "@cntyclub/agent-react";
+```
+
 ## Exports
 
 - `AgentWidget` — the complete widget (launcher + popup + fullscreen Agent Mode).

package/dist/index.d.ts

@@ -1,5 +1,357 @@
 import * as React from 'react';
 
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+interface paths {
+    "/agent-mode/approvals/{call_id}/resolve/": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Resolve a pending agent action
+         * @description Approve or decline a pending write-tool call.
+         */
+        post: operations["agent_approval_resolve"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/agent-mode/chat/": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Chat with an agent
+         * @description Sends a user message to the agent identified by client_id. Read-only MCP tools run automatically; write tools come back as pending approvals the user must resolve.
+         */
+        post: operations["agent_chat_send"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/agent-mode/config/": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get agent widget config
+         * @description Widget bootstrap: safe agent display config for the resolved client_id.
+         */
+        get: operations["agent_config_get"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/agent-mode/conversations/": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List my conversations
+         * @description List the calling user's conversations with an agent.
+         */
+        get: operations["agent_conversations_list"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/agent-mode/conversations/{conversation_id}/": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get conversation messages
+         * @description Fetch or delete one of the calling user's conversations.
+         */
+        get: operations["agent_conversation_get"];
+        put?: never;
+        post?: never;
+        /**
+         * Delete a conversation
+         * @description Fetch or delete one of the calling user's conversations.
+         */
+        delete: operations["agent_conversation_delete"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+interface components {
+    schemas: {
+        /** @description One chat message as returned by Agent Mode endpoints (wire format). */
+        AgentChatMessage: {
+            /** Format: uuid */
+            id: string;
+            /**
+             * @description * `user` - user
+             *     * `assistant` - assistant
+             *     * `tool` - tool
+             * @enum {string}
+             */
+            role: "user" | "assistant" | "tool";
+            content: string;
+            /** Format: date-time */
+            created_at: string;
+            /** @description Structured UI blocks. Table blocks: {type:'table', tool_name, columns[], rows[], row_count, truncated?, pagination?}. */
+            blocks?: {
+                [key: string]: unknown;
+            }[];
+            /** @description Assistant messages only: tools the assistant requested ({id, name, arguments}). */
+            tool_calls?: {
+                [key: string]: unknown;
+            }[];
+            tool_name?: string;
+            tool_call_id?: string;
+        };
+        /** @description Response of the chat and approval-resolve endpoints. */
+        AgentChatResponse: {
+            /**
+             * @description * `success` - success
+             *     * `error` - error
+             * @enum {string}
+             */
+            status: "success" | "error";
+            /** @description Human-readable error detail when status=error. */
+            message?: string;
+            /** Format: uuid */
+            conversation_id?: string;
+            /** @description New messages created by this call, in order. */
+            messages?: components["schemas"]["AgentChatMessage"][];
+            pending_approvals?: components["schemas"]["PendingApproval"][];
+        };
+        /** @description Response of GET /agent-mode/conversations/<id>/. */
+        AgentConversationDetailResponse: {
+            conversation: components["schemas"]["ConversationList"];
+            messages: components["schemas"]["AgentChatMessage"][];
+            pending_approvals: components["schemas"]["PendingApproval"][];
+        };
+        /** @description Response of GET /agent-mode/conversations/. */
+        AgentConversationsResponse: {
+            conversations: components["schemas"]["ConversationList"][];
+        };
+        /** @description Widget bootstrap config — safe, non-sensitive fields only. */
+        AgentPublicConfig: {
+            name: string;
+            description: string;
+            has_mcp: boolean;
+            is_public: boolean;
+        };
+        /** @description Input for POST /agent-mode/approvals/<id>/resolve/. */
+        ApprovalRequestRequest: {
+            client_id: string;
+            approve: boolean;
+        };
+        /** @description Input for POST /agent-mode/chat/. */
+        ChatRequestRequest: {
+            client_id: string;
+            message: string;
+            /** Format: uuid */
+            conversation_id?: string | null;
+        };
+        ConversationList: {
+            /** Format: uuid */
+            readonly id?: string;
+            /** @description Derived from the first user message. */
+            title?: string;
+            /** Format: date-time */
+            readonly created_at?: string;
+            /** Format: date-time */
+            readonly updated_at?: string;
+        };
+        /** @description A write-tool call waiting for the user's explicit approval. */
+        PendingApproval: {
+            /** Format: uuid */
+            id: string;
+            tool_name: string;
+            /** @description Stored arguments that will be executed verbatim on approval. */
+            arguments: {
+                [key: string]: unknown;
+            };
+            /** Format: date-time */
+            created_at: string;
+        };
+    };
+    responses: never;
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+interface operations {
+    agent_approval_resolve: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                call_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ApprovalRequestRequest"];
+                "application/x-www-form-urlencoded": components["schemas"]["ApprovalRequestRequest"];
+                "multipart/form-data": components["schemas"]["ApprovalRequestRequest"];
+            };
+        };
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AgentChatResponse"];
+                };
+            };
+        };
+    };
+    agent_chat_send: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ChatRequestRequest"];
+                "application/x-www-form-urlencoded": components["schemas"]["ChatRequestRequest"];
+                "multipart/form-data": components["schemas"]["ChatRequestRequest"];
+            };
+        };
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AgentChatResponse"];
+                };
+            };
+        };
+    };
+    agent_config_get: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AgentPublicConfig"];
+                };
+            };
+        };
+    };
+    agent_conversations_list: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AgentConversationsResponse"];
+                };
+            };
+        };
+    };
+    agent_conversation_get: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                conversation_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AgentConversationDetailResponse"];
+                };
+            };
+        };
+    };
+    agent_conversation_delete: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                conversation_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description No response body */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+}
+
+/**
+ * All wire types derive from the generated OpenAPI schema (src/api/schema.ts,
+ * generated from api-spec/agent-mode-api.yaml — the backend's
+ * /agent-mode/schema/ document). Regenerate with `pnpm gen:api` after updating
+ * the spec; see the README for the full update workflow.
+ */
+type AgentModeSchemas = components["schemas"];
 /** A structured UI block attached to a message (currently: result tables). */
 interface TableBlock {
     type: "table";
@@ -16,41 +368,23 @@ interface ToolCallInfo {
     name?: string;
     arguments?: Record<string, unknown>;
 }
-interface AgentMessage {
-    id: string;
-    role: "user" | "assistant" | "tool";
-    content: string;
-    created_at: string;
+/**
+ * One chat message. Wire shape from the schema; `blocks`/`tool_calls` are
+ * JSON fields on the wire, narrowed here to their documented structures.
+ */
+interface AgentMessage extends Omit<AgentModeSchemas["AgentChatMessage"], "blocks" | "tool_calls"> {
     blocks?: MessageBlock[];
     tool_calls?: ToolCallInfo[];
-    tool_name?: string;
-    tool_call_id?: string;
 }
-interface PendingApproval {
-    id: string;
-    tool_name: string;
-    arguments: Record<string, unknown>;
-    created_at: string;
-}
-interface ConversationSummary {
-    id: string;
-    title: string;
-    created_at: string;
-    updated_at: string;
-}
-interface AgentPublicConfig {
-    name: string;
-    description: string;
-    has_mcp: boolean;
-    is_public: boolean;
-}
-interface ChatResponse {
-    status: "success" | "error";
-    message?: string;
-    conversation_id?: string;
+type PendingApproval = AgentModeSchemas["PendingApproval"];
+type ConversationSummary = Required<AgentModeSchemas["ConversationList"]>;
+type AgentPublicConfig = AgentModeSchemas["AgentPublicConfig"];
+/** Response of the chat and approval-resolve endpoints. */
+interface ChatResponse extends Omit<AgentModeSchemas["AgentChatResponse"], "messages"> {
     messages?: AgentMessage[];
-    pending_approvals?: PendingApproval[];
 }
+type ChatRequest = AgentModeSchemas["ChatRequestRequest"];
+type ApprovalRequest = AgentModeSchemas["ApprovalRequestRequest"];
 /** Maps MCP tools to a page in the host app so the agent can navigate alongside chat. */
 interface AgentPageMapping {
     /** MCP tool names whose execution relates to this page. */
@@ -210,4 +544,4 @@ declare function ToolApprovalCard({ approval, onResolve, resolving }: ToolApprov
  */
 declare function defineAgentConfig(config: AgentConfig): AgentConfig;
 
-export { AgentApiClient, AgentApiError, type AgentChatActions, type AgentChatState, type AgentConfig, type AgentMessage, type AgentPageMapping, AgentPanel, type AgentPanelProps, type AgentPublicConfig, AgentWidget, type AgentWidgetProps, type ChatResponse, type ConversationSummary, type MessageBlock, MessageItem, type PendingApproval, type TableBlock, ToolApprovalCard, type ToolApprovalCardProps, type ToolCallInfo, defineAgentConfig, useAgentChat };
+export { AgentApiClient, AgentApiError, type AgentChatActions, type AgentChatState, type AgentConfig, type AgentMessage, type components as AgentModeComponents, type operations as AgentModeOperations, type paths as AgentModePaths, type AgentModeSchemas, type AgentPageMapping, AgentPanel, type AgentPanelProps, type AgentPublicConfig, AgentWidget, type AgentWidgetProps, type ApprovalRequest, type ChatRequest, type ChatResponse, type ConversationSummary, type MessageBlock, MessageItem, type PendingApproval, type TableBlock, ToolApprovalCard, type ToolApprovalCardProps, type ToolCallInfo, defineAgentConfig, useAgentChat };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cntyclub/agent-react",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Embeddable AI agent chat widget for Country Club dashboards — floating button, popup panel, fullscreen Agent Mode, MCP tool approvals, and paginated result tables. Built exclusively on @cntyclub/ui-react.",
   "type": "module",
   "sideEffects": false,
@@ -32,6 +32,7 @@
     "@cntyclub/ui-react": "link:../DashboardsCountryClub-UIKit/packages/ui-react",
     "@types/react": "^19.2.13",
     "@types/react-dom": "^19.2.3",
+    "openapi-typescript": "^7.13.0",
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
     "tsup": "^8.5.1",
@@ -49,6 +50,7 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist",
+    "gen:api": "openapi-typescript api-spec/agent-mode-api.yaml -o src/api/schema.ts"
   }
 }