@ensembleapp/client-sdk 0.0.53 → 0.0.55

package/README.md

@@ -63,6 +63,80 @@ function CustomChat() {
 }
 ```
 
+### Reading token usage
+
+The server streams token/usage stats as a `data-usage` part. You can read them
+three ways.
+
+**1. `<ChatWidget>`: the `onUsage` callback**
+
+```tsx
+import { ChatWidget, type ChatUsageData } from '@ensembleapp/client-sdk'
+
+<ChatWidget
+  api={{ baseUrl: '/api', token: 'your-jwt-token' }}
+  agentId="agent-234"
+  threadId="user-123"
+  onUsage={(usage: ChatUsageData) => {
+    console.log(usage.inputTokens, usage.outputTokens)
+    console.log(usage.totalMessageCount, usage.messageHistoryLimit)
+  }}
+/>
+```
+
+Or, to render the built-in counter (`↑ N in · ↓ N out`) above the input without
+writing any code, set `showTokenUsage`:
+
+```tsx
+<ChatWidget api={/* ... */} agentId="..." threadId="..." showTokenUsage />
+```
+
+**2. `useChat` hook: the `usage` return value**
+
+`usage` is reactive state (the latest turn), so it's the simplest way to render:
+
+```tsx
+import { useChat, type ChatUsageData } from '@ensembleapp/client-sdk'
+
+function CustomChat() {
+  const { messages, sendMessage, usage } = useChat({ /* ...config */ })
+  //                              ^^^^^ ChatUsageData | null
+
+  return <div>{usage && `${usage.inputTokens} in / ${usage.outputTokens} out`}</div>
+}
+```
+
+You can also pass `onUsage` to the hook if you prefer the event style.
+
+**3. `extractUsageData`: for custom stream handling**
+
+If you handle the stream at a lower level (e.g. via `onData`), pull usage out of
+any data part:
+
+```tsx
+import { extractUsageData } from '@ensembleapp/client-sdk'
+
+onData: (dataPart) => {
+  const usage = extractUsageData(dataPart) // ChatUsageData | null
+  if (usage) { /* ... */ }
+}
+```
+
+**`ChatUsageData` shape**
+
+```ts
+interface ChatUsageData {
+  inputTokens: number
+  outputTokens: number
+  maxInputTokens?: number
+  maxOutputTokens?: number
+  inputTokensPercent?: number
+  outputTokensPercent?: number
+  totalMessageCount?: number
+  messageHistoryLimit?: number
+}
+```
+
 ## API Reference
 
 ### ChatWidget Props
@@ -72,6 +146,9 @@ function CustomChat() {
 - `onMessage?` (function): Callback when a new message is received
 - `onError?` (function): Callback when an error occurs
 - `onFinish?` (function): Callback when a conversation finishes
+- `onUsage?` ((usage: ChatUsageData) => void): Callback with token/usage stats as they stream
+- `onData?` ((dataPart) => void): Callback for every raw stream data part
+- `showTokenUsage?` (boolean): Show the built-in input/output token counter above the input (default: false)
 - `className?` (string): Additional CSS classes
 - `placeholder?` (string): Input placeholder text
 - `welcomeMessage?` (string): Initial welcome message
@@ -81,10 +158,10 @@ function CustomChat() {
 ```tsx
 const {
   messages,      // Array of chat messages
-  isLoading,     // Boolean indicating if request is in progress
-  isError,       // Boolean indicating if there's an error
+  status,        // Current request status
   sendMessage,   // Function to send a message
   stop,          // Function to stop current request
   setMessages,   // Function to manually set messages
+  usage,         // ChatUsageData | null (latest token/usage stats)
 } = useChat(config)
 ```

package/dist/index.d.ts

@@ -63,6 +63,29 @@ interface ApiConfig {
 /** Agent version selector: 'latest' (default), 'published', or a specific version number */
 type AgentVersion = 'latest' | 'published' | number;
 type StructuredMessagePayload = Record<string, unknown>;
+/**
+ * Usage stats emitted by the server as a `data-usage` stream part and delivered
+ * to the {@link UseChatConfig.onUsage} callback.
+ */
+interface ChatUsageData {
+    inputTokens: number;
+    outputTokens: number;
+    maxInputTokens?: number;
+    maxOutputTokens?: number;
+    inputTokensPercent?: number;
+    outputTokensPercent?: number;
+    /** Total number of messages in the conversation so far */
+    totalMessageCount?: number;
+    /** Maximum number of messages allowed in conversation history */
+    messageHistoryLimit?: number;
+}
+/**
+ * Extract usage stats from a stream data part. The server wraps usage as
+ * `{ type: 'data-usage', data: { ...ChatUsageData } }`; returns the full inner
+ * payload (including totalMessageCount / messageHistoryLimit) or null if the
+ * part is not a usage part.
+ */
+declare function extractUsageData(dataPart: unknown): ChatUsageData | null;
 type UseChatConfig = DeprecatedChatConfig & {
     /** The server API configuration */
     api: ApiConfig;
@@ -80,15 +103,8 @@ type UseChatConfig = DeprecatedChatConfig & {
     onFinish?: (message: any) => void;
     onData?: (data: any) => void;
     onMessage?: (message: UIMessage) => void;
-    /** Called when usage data is received (input/output token counts and percentages) */
-    onUsage?: (usage: {
-        inputTokens: number;
-        outputTokens: number;
-        maxInputTokens?: number;
-        maxOutputTokens?: number;
-        inputTokensPercent?: number;
-        outputTokensPercent?: number;
-    }) => void;
+    /** Called when usage data is received (token counts/percentages and message-history stats) */
+    onUsage?: (usage: ChatUsageData) => void;
 };
 declare function useChat({ api, threadId, agentId, agentVersion, agentExecutionId, dataContext, onError, onAuthError, onFinish, onData, onMessage, onUsage, }: UseChatConfig): {
     messages: ChatMessage[];
@@ -121,6 +137,7 @@ declare function useChat({ api, threadId, agentId, agentVersion, agentExecutionI
     addToolApprovalResponse: ai.ChatAddToolApproveResponseFunction;
     pendingToolOutput: PendingToolOutput | null;
     pendingToolApproval: PendingToolApproval | null;
+    usage: ChatUsageData | null;
 };
 
 /** Matches POST /api/tools/:toolId/invoke request body */
@@ -324,7 +341,7 @@ declare const createWidget: <TEnriched extends EnrichedResults = EnrichedResults
     render(payload: any, enriched: TEnriched, options: WidgetRenderOptions): unknown;
 }) => UIWidgetDefinition<FlexibleSchema, TEnriched>;
 
-type DisplayMode = 'full' | 'brief';
+type DisplayMode = 'full' | 'brief' | 'hide-tools';
 
 interface ChatWidgetStyles {
     /**
@@ -405,7 +422,7 @@ interface ChatWidgetConfig extends UseChatConfig {
     initialUserMessage?: string;
     /** Placeholder text for the input box */
     inputPlaceholder?: string;
-    /** Display mode: 'brief' (default) collapses previous steps, 'full' shows everything */
+    /** Display mode: 'brief' (default) collapses previous steps, 'full' shows everything, 'hide-tools' omits tool calls */
     displayMode?: DisplayMode;
     className?: string;
     styles?: ChatWidgetStyles;
@@ -414,6 +431,8 @@ interface ChatWidgetConfig extends UseChatConfig {
     widgets?: AnyUIWidgetDefinition[];
     /** Feedback options for assistant messages. Enabled by default. */
     feedback?: ChatWidgetFeedbackOptions;
+    /** Show a compact input/output token counter (from the server's usage data). Default: false. */
+    showTokenUsage?: boolean;
 }
 declare const ChatWidget: React.ForwardRefExoticComponent<ChatWidgetConfig & React.RefAttributes<ChatWidgetHandle>>;
 
@@ -537,8 +556,8 @@ interface MessageRendererProps {
     widgets?: AnyUIWidgetDefinition[];
     /** Readonly mode - disables all widget interactions */
     readonly?: boolean;
-    /** Display mode: 'brief' collapses previous steps, 'full' shows everything */
-    displayMode?: 'brief' | 'full';
+    /** Display mode: 'brief' collapses previous steps, 'full' shows everything, 'hide-tools' omits tool calls */
+    displayMode?: 'brief' | 'full' | 'hide-tools';
     /** Tag expansion state and handler */
     tagExpansion?: {
         state: Map<string, boolean>;
@@ -590,6 +609,11 @@ declare function BriefDisplayMode({ sections, messageId, renderPart, renderGroup
  */
 declare function FullDisplayMode({ sections, messageId, renderPart, renderGroup, }: DisplayModeProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * Hide-tools display mode - shows all text and widgets while omitting tool-call rows.
+ */
+declare function HideToolsDisplayMode({ sections, messageId, renderPart, renderGroup, }: DisplayModeProps): react_jsx_runtime.JSX.Element;
+
 type RegisterChatWidgetsParams = {
     api: ApiConfig;
     threadId: string;
@@ -637,4 +661,4 @@ declare const getVendorCardsWidget: (isProd?: boolean) => SDKUIWidgetDefinition[
 
 declare function cn(...inputs: ClassValue[]): string;
 
-export { type AgentVersion, type AnyUIWidgetDefinition, type ApiConfig, type ApprovalUIConfig, BriefDisplayMode, BriefDisplayMode as BriefRenderer, type ChatMessage, type ChatMessageSection, ChatWidget, type ChatWidgetFeedbackOptions, type ChatWidgetHandle, type ChatWidgetConfig as ChatWidgetProps, type ChatWidgetSpeechToTextOptions, type ChatWidgetStyles, type ChatWidgetVoiceOptions, type CustomerReactDOM, type DisplayMode, type DisplayModeProps, type EmbeddableChatWidgetConfig, type EnrichedResults, type FeedbackConfig, type FeedbackHandlers, type FetchApprovalConfigOptions, FullDisplayMode, FullDisplayMode as FullRenderer, type InvokeTool, type MessageContext, MessageRenderer, type MessageRendererProps, type PendingToolApproval, type PendingToolOutput, type PopupAnchorConfig, PopupChatWidget, type PopupChatWidgetProps, type DisplayModeProps as RendererProps, type SDKUIWidgetDefinition, SDK_WIDGET_MARKER, type StructuredMessagePayload, type SubmitFeedbackParams, TagGroupDisplay, type TagGroupDisplayProps, ToolCallDisplay, type ToolCallDisplayProps, type ToolInvokeRequest, type ToolInvokeResult, type ToolPart, type UIMessagePart, type UIWidgetDefinition, type UseChatConfig, type UseFeedbackConfig, type WidgetRenderOptions, cn, createSDKWidget, createWidget, defaultChatWidgets, fetchApprovalConfig, getVendorCardsWidget, isSDKWidget, registerChatWidgets, transformMessage, useChat, useFeedback };
+export { type AgentVersion, type AnyUIWidgetDefinition, type ApiConfig, type ApprovalUIConfig, BriefDisplayMode, BriefDisplayMode as BriefRenderer, type ChatMessage, type ChatMessageSection, type ChatUsageData, ChatWidget, type ChatWidgetFeedbackOptions, type ChatWidgetHandle, type ChatWidgetConfig as ChatWidgetProps, type ChatWidgetSpeechToTextOptions, type ChatWidgetStyles, type ChatWidgetVoiceOptions, type CustomerReactDOM, type DisplayMode, type DisplayModeProps, type EmbeddableChatWidgetConfig, type EnrichedResults, type FeedbackConfig, type FeedbackHandlers, type FetchApprovalConfigOptions, FullDisplayMode, FullDisplayMode as FullRenderer, HideToolsDisplayMode, HideToolsDisplayMode as HideToolsRenderer, type InvokeTool, type MessageContext, MessageRenderer, type MessageRendererProps, type PendingToolApproval, type PendingToolOutput, type PopupAnchorConfig, PopupChatWidget, type PopupChatWidgetProps, type DisplayModeProps as RendererProps, type SDKUIWidgetDefinition, SDK_WIDGET_MARKER, type StructuredMessagePayload, type SubmitFeedbackParams, TagGroupDisplay, type TagGroupDisplayProps, ToolCallDisplay, type ToolCallDisplayProps, type ToolInvokeRequest, type ToolInvokeResult, type ToolPart, type UIMessagePart, type UIWidgetDefinition, type UseChatConfig, type UseFeedbackConfig, type WidgetRenderOptions, cn, createSDKWidget, createWidget, defaultChatWidgets, extractUsageData, fetchApprovalConfig, getVendorCardsWidget, isSDKWidget, registerChatWidgets, transformMessage, useChat, useFeedback };