@rizal_ncc/agent-client 1.4.2 → 1.4.4

package/README.md

@@ -1,8 +1,25 @@
-# @rizal_ncc/agent-client
+[![Node.js Package](https://github.com/rizalNCC/agent-client/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/rizalNCC/agent-client/actions/workflows/npm-publish.yml)
 
-Frontend UI wrapper + typed helpers for `nems/ai_agent`.
+# Agen Client
 
-`backend-documentation.md` is the source-of-truth contract for backend payload and `tool_results` schema.
+A component (for now support react and vanilla) and headless core for AI agent chat interfaces, designed for seamless integration with a compatible backend API. Provides built-in transport logic, flexible layouts, and tool result handling, while allowing full customization through props and custom transport functions.
+
+## Table of Contents
+
+- [Install](#install)
+- [Quick Start (React)](#quick-start-react)
+- [Layouts](#layouts)
+- [AiAgentChat Props](#aiagentchat-props)
+- [Built-in Transport Contract](#built-in-transport-contract)
+- [Headless Core Usage](#headless-core-usage)
+- [Tool Result Helpers](#tool-result-helpers)
+- [Theme and Styling](#theme-and-styling)
+- [Architecture](#architecture)
+- [Testing](#testing)
+- [Development](#development)
+- [Release and Publish](#release-and-publish)
+- [File Map](#file-map)
+- [Known Tradeoffs](#known-tradeoffs)
 
 ## Install
 
@@ -10,7 +27,7 @@ Frontend UI wrapper + typed helpers for `nems/ai_agent`.
 npm install @rizal_ncc/agent-client
 ```
 
-## React Usage
+## Quick Start (React)
 
 ```tsx
 import { AiAgentChat } from "@rizal_ncc/agent-client/react";
@@ -20,7 +37,7 @@ export function App() {
   return (
     <AiAgentChat
       baseURL="https://example.com/api"
-      accessToken="your-access-token-here"
+      accessToken="your-access-token"
       agent="home-assistant"
       primaryColor="#0f766e"
       primaryForeground="#ffffff"
@@ -33,60 +50,102 @@ export function App() {
 }
 ```
 
-Layout examples:
+## Layouts
+
+The component supports three layouts:
+
+- `inline`: always open in page flow.
+- `floating`: fixed toggle button + popover panel.
+- `dropdown`: inline toggle bar + expandable panel.
+
+Examples:
 
 ```tsx
+<AiAgentChat layout="inline" />
 <AiAgentChat layout="floating" defaultOpen={false} />
 <AiAgentChat layout="dropdown" defaultOpen={false} panelHeight="560px" />
 ```
 
-## Chat Component Props (AiAgentChat)
+Open state control:
+
+- Controlled: pass `open` + `onOpenChange`.
+- Uncontrolled: pass `defaultOpen`.
 
-Common props:
+## AiAgentChat Props
 
-- `baseURL: string` backend base URL
-- `accessToken: string | () => string | Promise<string>` bearer token provider
+### Core
+
+- `baseURL?: string` backend base URL (required for built-in transport)
+- `accessToken?: string | () => string | undefined | Promise<string | undefined>` bearer token provider (required for built-in transport)
 - `agent?: string` default `home-assistant`
-- `suggestedMessages?: string[]` clickable prompt chips
-- `headerTitle?: string`
-- `headerDescription?: string`
-- `assistantAvatar?: ReactNode` custom avatar component slot
-- `assistantAvatarUrl?: string` avatar URL override (default `/ai-img.svg`)
-- `initials?: boolean` show/hide assistant and user initials (default `true`)
-- `primaryColor?: string` theme color (default `#1168bb`)
-- `primaryForeground?: string` text color on primary surfaces (default `#ffffff`)
 - `metadata?: { course_id?: number }`
 - `requestHeaders?: HeadersInit`
-- `layout?: "inline" | "floating" | "dropdown"` (default `inline`)
-- `open?: boolean` controlled open state for `floating`/`dropdown`
-- `defaultOpen?: boolean` uncontrolled initial open state
+- `respondPath?: string` endpoint override
+- `generateResponse?: (request) => Promise<{ content: string }>` custom transport override
+
+### UI
+
+- `headerTitle?: string`
+- `headerDescription?: string`
+- `suggestedMessages?: string[]`
+- `assistantAvatar?: ReactNode`
+- `assistantAvatarUrl?: string` default `/ai-img.svg`
+- `assistantInitials?: string` default `AI`
+- `userInitials?: string` default `YOU`
+- `initials?: boolean` default `true`
+- `placeholder?: string` default `Ask the assistant...`
+- `sendLabel?: string` default `Send`
+- `stopLabel?: string` default `Stop`
+- `className?: string`
+
+### Theme
+
+- `primaryColor?: string` default `#1168bb`
+- `primaryForeground?: string` default `#ffffff`
+- `panelHeight?: string` optional CSS height override (uses CSS variable fallback if omitted)
+- `zIndex?: number` default `60`
+
+### Layout control
+
+- `layout?: "inline" | "floating" | "dropdown"` default `inline`
+- `open?: boolean`
+- `defaultOpen?: boolean`
 - `onOpenChange?: (open: boolean) => void`
-- `panelHeight?: string` panel height (default `"620px"`)
-- `floatingPosition?: "bottom-right" | "bottom-left"` (default `bottom-right`)
-- `zIndex?: number` (default `60`)
+- `floatingPosition?: "bottom-right" | "bottom-left"` default `bottom-right`
+- `openLabel?: string` default `Open chat`
+- `closeLabel?: string` default `Close chat`
 
-UX behavior:
+### Events
 
-- Composer uses one combined icon action button:
-- idle state: send icon
-- loading state: stop icon
+- `onMessage?: (message, messages) => void`
+- `onError?: (error, messages) => void`
 
-Advanced:
+## Built-in Transport Contract
 
-- `generateResponse?: (request) => Promise<{ content: string }>` custom transport override
-- `respondPath?: string` manual endpoint override
-- `onMessage?`, `onError?`
+If `generateResponse` is not provided, `AiAgentChat` performs backend requests.
+
+Path resolution:
 
-Path behavior (built-in transport):
+- if `baseURL` ends with `/api` -> `POST /v2/ai-agent/respond/`
+- otherwise -> `POST /api/v2/ai-agent/respond/`
 
-- If `baseURL` ends with `/api` -> uses `/v2/ai-agent/respond/`
-- Otherwise -> uses `/api/v2/ai-agent/respond/`
+Request body:
 
-Recommendation UI behavior:
+- `agent`
+- `message` (latest user message)
+- `metadata`
 
-- `get_course_recommendation` results are rendered as a horizontal carousel card list.
-- If backend returns `next` in recommendation output, a `Load more` button appears below the carousel.
-- Clicking `Load more` fetches the `next` URL automatically (with current bearer token) and appends deduplicated results.
+Expected response shape (minimum):
+
+- `message: string`
+- `tool_results?: ToolResult[]`
+
+Recommendation behavior:
+
+- Renders `get_course_recommendation` results as horizontal cards.
+- Uses `next` for pagination when available.
+- `Load more` appends validated incoming items.
+- Duplicate items are currently allowed by design.
 
 ## Headless Core Usage
 
@@ -101,26 +160,87 @@ await bot.sendMessage("Hi");
 console.log(bot.getState().messages);
 ```
 
-## Backend Tool Helpers
+`ChatbotCore` notes:
+
+- Ignores empty messages.
+- Aborts previous in-flight request on new send.
+- Throws if `generateResponse` returns empty `content`.
+- Exposes `stop()` for manual cancellation.
 
-Helpers for backend `tool_results`:
+## Tool Result Helpers
+
+Helpers exported from core entry:
 
 - `getToolResultsByName(response, toolName)`
+- `getToolErrors(response)`
+- `extractCourseDetail(response)`
 - `extractRecommendationOutput(response)`
 - `extractRecommendationItems(response)`
-- `extractCourseDetail(response)`
-- `getToolErrors(response)`
 
-Tool names follow backend contracts:
+Known backend tool names:
 
 - `get_course_recommendation`
 - `get_course_detail`
 
-## Exports
+## Theme and Styling
+
+Import styles once:
+
+```tsx
+import "@rizal_ncc/agent-client/style.css";
+```
+
+Runtime CSS variables used by component shell:
+
+- `--chat-primary`
+- `--chat-primary-rgb`
+- `--chat-primary-foreground`
+- `--chat-panel-height`
+- `--chat-shell-z-index`
 
-- Core: `@rizal_ncc/agent-client`
-- React adapter: `@rizal_ncc/agent-client/react`
-- Styles: `@rizal_ncc/agent-client/style.css`
+Important:
+
+- Do not redeclare `--chat-primary*` inside `.ai-agent-chat` if you want prop colors to apply.
+
+## Architecture
+
+Primary layers:
+
+1. `ChatbotCore` state engine (`src/core/chatbot.ts`)
+2. React adapter + transport + layout shell (`src/adapters/react.tsx`)
+3. Tool parsing and pagination helpers (`src/lib/tool-results.ts`, `src/lib/recommendation-pagination.ts`)
+4. UI styles and layout animations (`src/style.css`)
+
+Message lifecycle:
+
+1. User input -> user message append (`isLoading = true`)
+2. Transport call (custom or built-in)
+3. Assistant message normalize + append
+4. Optional recommendation pagination update
+5. `isLoading = false`
+
+## Testing
+
+Stack:
+
+- Vitest
+- React Testing Library
+- jsdom
+
+Current coverage includes:
+
+- core behavior/error flow
+- tool helper parsing
+- recommendation merge behavior
+- dropdown/floating open state
+- typing/stop/error UI states
+- load-more append flow
+
+Run tests:
+
+```bash
+npm test
+```
 
 ## Development
 
@@ -131,12 +251,68 @@ npm test
 npm run build
 ```
 
-`npm run dev` starts the root-level Vite playground (`index.html` + `demo/*`).
+`npm run dev` starts Vite playground (`index.html` + `demo/*`).
 
-Demo env:
+Demo env (`.env`):
 
 ```bash
 VITE_API_BASE_URL=http://example.com/
 VITE_AI_AGENT_TOKEN=<access_token>
 VITE_AI_AGENT_AGENT=home-assistant
 ```
+
+## Release and Publish
+
+Pre-release validation:
+
+```bash
+npm run release:check
+```
+
+Manual publish:
+
+```bash
+npm publish --access public
+```
+
+Automated publish (GitHub Actions):
+
+- Workflow: `.github/workflows/npm-publish.yml`
+- Trigger: push tag matching `v*.*.*`
+- Required secret: `NPM_TOKEN` (npm automation token)
+
+Tag-based release flow:
+
+```bash
+npm version patch
+git push --follow-tags
+```
+
+Use `minor` or `major` instead of `patch` when needed.
+
+## File Map
+
+- Core
+  - `src/core/chatbot.ts`
+  - `src/core/types.ts`
+  - `src/core/errors.ts`
+- React
+  - `src/adapters/react.tsx`
+  - `src/react.ts`
+- Helpers
+  - `src/lib/tool-results.ts`
+  - `src/lib/recommendation-pagination.ts`
+- Styles
+  - `src/style.css`
+- Tests
+  - `tests/chatbot-core.test.ts`
+  - `tests/tool-results.test.ts`
+  - `tests/recommendation-pagination.test.ts`
+  - `tests/ai-agent-chat-ui.test.tsx`
+
+## Known Tradeoffs
+
+1. Recommendation dedupe is intentionally disabled.
+2. Built-in transport assumes JSON response (`response.json()`).
+3. Some layout behavior depends on CSS class contracts.
+4. Token refresh strategy is caller-managed when using function token provider.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rizal_ncc/agent-client",
-  "version": "1.4.2",
+  "version": "1.4.4",
   "description": "UI wrapper and helpers for BAWANA AI agent integrations",
   "author": "Rizal Suryawan - (BAWANA Team)",
   "license": "MIT",