@paymanai/payman-ask-sdk 1.2.26 → 2.0.1

package/README.md

@@ -1,249 +1,264 @@
-# Payman Ask SDK
+# @paymanai/payman-ask-sdk
 
-A reusable React component library for building chat interfaces powered by Payman workflows.
+React chat component for Payman workflows — streaming, verification, voice, and session history out of the box.
 
-## Features
+> **v2.0 is a clean break from v1.** The configuration API has been nested under `api`, `workflow`, `session`, `availability`, `ui`, and `observability`. See the [Migrating from v1](#migrating-from-v1) section for a translation table.
 
-✅ **Fully Self-Contained** - Handles all API calls, streaming, and state management  
-✅ **Type-Safe** - Built with TypeScript for full type safety  
-✅ **SSE Streaming** - Real-time message streaming with Server-Sent Events  
-✅ **Context API** - Control chat programmatically from parent components  
-✅ **Customizable** - Flexible configuration and custom headers  
-✅ **Execution Tracing** - Built-in support for execution trace data  
-✅ **Session Management** - Automatic session ID generation and tracking  
-✅ **Markdown Support** - Rich message formatting with react-markdown  
-✅ **Animations** - Smooth animations with Framer Motion  
-
-## Installation
+## Install
 
 ```bash
-npm install @paymanai/payman-ask-sdk
-# or
-yarn add @paymanai/payman-ask-sdk
-# or  
-bun add @paymanai/payman-ask-sdk
+npm install @paymanai/payman-ask-sdk @paymanai/payman-typescript-ask-sdk
 ```
 
-## Quick Start
-
-### For Playground/Testing
-
 ```tsx
+import "@paymanai/payman-ask-sdk/styles.css";
 import { PaymanChat } from "@paymanai/payman-ask-sdk";
-
-function MyApp() {
-  return (
-    <PaymanChat
-      config={{
-        api: {
-          baseUrl: "https://api.example.com",
-          authToken: "your-token",
-          streamEndpoint: "/api/playground/ask/stream", // Important!
-        },
-        workflowName: "my-workflow",
-        userId: "user-123", // Required for chatStore and activeStreamStore
-        workflowVersion: 1,
-        stage: "DEV",
-        sessionParams: {
-          id: "user-123",
-          name: "John Doe",
-        },
-      }}
-      callbacks={{
-        onError: (error) => console.error(error),
-      }}
-    />
-  );
-}
 ```
 
-### For Production
+## Minimal example
 
 ```tsx
 <PaymanChat
   config={{
     api: {
-      baseUrl: "https://api.example.com",
-      authToken: "your-api-key", // API key with stage configured
+      baseUrl: "https://api.paymanai.com",
+      headers: { Authorization: `Bearer ${token}` },
+    },
+    workflow: {
+      id: "wf_01H…",          // optional; required for session history
+      name: "my-agent",
+      version: 3,
+      stage: "PROD",
     },
-    workflowName: "my-workflow",
-    userId: "user-123", // Required for chatStore and activeStreamStore
-    stage: "PROD",
-    sessionParams: {
-      id: "user-123",
-      name: "John Doe",
+    session: {
+      userId: "user-42",       // client-side state-scope key
+      owner: { id: "user-42", label: "Alice" },
     },
+    ui: {
+      emptyState: { text: "How can I help?" },
+      input: {
+        placeholder: "Ask anything…",
+        voice: true,
+      },
+      sessionHistory: true,
+    },
+  }}
+  callbacks={{
+    onStreamComplete: (msg) => console.log(msg),
   }}
 />
 ```
 
-## Custom Header
+## Configuration
 
-```tsx
-import { PaymanChat, usePaymanChat } from "@paymanai/payman-ask-sdk";
+The full config is a `BaseChatConfig` (from the core SDK) extended with `availability`, `ui`, and `observability`.
 
-function ChatHeader() {
-  const chat = usePaymanChat();
-
-  return (
-    <div className="header">
-      <h2>My Chat</h2>
-      <button onClick={chat.resetSession}>Reset</button>
-      <button onClick={chat.clearMessages}>Clear</button>
-    </div>
-  );
-}
+```ts
+type ChatConfig = {
+  // ---- Core (shared with payman-typescript-ask-sdk) ------------------------
+  api: {
+    baseUrl: string;
+    apiKey?: string;
+    headers?: Record<string, string | undefined>;
+    streamEndpoint?: string;      // default: "/api/workflows/ask/stream"
+  };
 
-function MyApp() {
-  return (
-    <PaymanChat config={config}>
-      <ChatHeader />
-    </PaymanChat>
-  );
-}
-```
+  workflow: {
+    id?: string;                  // workflow uuid; required when `ui.sessionHistory` is enabled
+    name: string;
+    version?: number;
+    stage?: "DEV" | "SBX" | "PROD";
+  };
 
-## API Reference
-
-### `config` (required)
-
-| Property | Type | Required | Description |
-|----------|------|----------|-------------|
-| `api` | `APIConfig` | ✅ | API configuration |
-| `workflowName` | `string` | ✅ | Workflow name |
-| `userId` | `string` | ✅ | User ID for chatStore and activeStreamStore (context store messages management) |
-| `workflowVersion` | `number` | | Workflow version (default: 1) |
-| `stage` | `WorkflowStage` | | Stage (DEV/SANDBOX/PROD) |
-| `sessionParams` | `SessionParams` | | User session info |
-| `autoGenerateSessionId` | `boolean` | | Auto-generate session ID |
-| `hasAskPermission` | `boolean` | | Show/hide input (default: true) |
-| `uiVersion` | `1 \| 2` | | Render original UI or v2 UI |
-| `showResetSession` | `boolean` | | Show a New Session button in the input bar with a confirmation modal before reset (default: false) |
-| `showAttachmentButton` | `boolean` | | Show/hide the v2 attachment (+) menu button (default: true) |
-| `showUploadImageButton` | `boolean` | | Show/hide the v2 Upload image option (default: true) |
-| `showAttachFileButton` | `boolean` | | Show/hide the v2 Attach file option (default: true) |
-| `enableVoice` | `boolean` | | Show/hide the voice input button in the composer (default: false) |
-| `voiceLang` | `string` | | Speech recognition language (default: `en-US`) |
-| `voiceInterimResults` | `boolean` | | Enable interim voice transcription updates (default: true) |
-| `voiceContinuous` | `boolean` | | Keep listening continuously while recording (default: true) |
-| `messageActions` | `MessageActionsConfig` | | Configure visible actions for `userMessageActions` and `assistantMessageActions` in the v2 UI |
-
-`messageActions` shape:
+  session?: {
+    userId?: string;              // client-side state-scope key (NOT sent to API)
+    owner?: { id: string; label?: string };
+    autoGenerateId?: boolean;     // default: true
+    initialId?: string;
+    initialMessages?: MessageDisplay[];
+  };
 
-```ts
-messageActions: {
-  userMessageActions?: {
-    copy?: boolean;
-    edit?: boolean;
-    retry?: boolean;
+  // ---- React-only ----------------------------------------------------------
+  availability?:
+    | { state: "ready" }
+    | { state: "readOnly" }
+    | { state: "disabled"; reason?: React.ReactNode };
+
+  ui?: {
+    layout?: "centered" | "full-width";
+
+    agent?: { name?: string; showName?: boolean };
+
+    emptyState?: {
+      text?: string;
+      icon?: boolean;
+      content?: React.ReactNode;
+    };
+
+    input?: {
+      placeholder?: string;
+      showResetButton?: boolean;
+      attachments?: boolean | { uploadImage?: boolean; attachFile?: boolean };
+      voice?: boolean | { lang?: string; interimResults?: boolean; continuous?: boolean };
+    };
+
+    messages?: {
+      avatars?: boolean | { user?: boolean; assistant?: boolean };
+      timestamps?: boolean;
+      streamingDot?: boolean;
+      actions?: {
+        userMessageActions?: { copy?: boolean; edit?: boolean; retry?: boolean };
+        assistantMessageActions?: { copy?: boolean; trace?: boolean };
+      };
+    };
+
+    execution?: {
+      showSteps?: boolean;
+      completedLabel?: string;     // default: "Completed in {time}s ({count} steps)"
+      streamingLabel?: string;     // default: "View progress ({count} steps)"
+    };
+
+    /**
+     * `true` — enable with defaults.
+     * object — override width/collapse/page-size/persistKey.
+     */
+    sessionHistory?: boolean | {
+      defaultWidth?: number;       // default: 280 px
+      minWidth?: number;           // default: 240
+      maxWidth?: number;           // default: 480
+      defaultCollapsed?: boolean;  // desktop only; default: false
+      pageSize?: number;           // default: 20
+      persistKey?: string;         // default: `payman-chat-sidebar:${workflow.id}`
+    };
   };
-  assistantMessageActions?: {
-    copy?: boolean;
-    trace?: boolean;
+
+  observability?: {
+    sentryDsn?: string;
   };
-}
+};
 ```
 
-### `APIConfig`
-
-| Property | Type | Required | Description |
-|----------|------|----------|-------------|
-| `baseUrl` | `string` | ✅ | API base URL |
-| `authToken` | `string` | | Auth token |
-| `headers` | `Record<string, string>` | | Custom headers |
-| `streamEndpoint` | `string` | | Stream endpoint path |
-
-### `callbacks` (optional)
-
-| Callback | Type | Description |
-|----------|------|-------------|
-| `onSessionIdChange` | `(sessionId: string) => void` | Session ID changed |
-| `onError` | `(error: Error) => void` | Error occurred |
-| `onMessageSent` | `(message: MessageDisplay) => void` | Message sent |
-| `onStreamStart` | `() => void` | Stream started |
-| `onStreamComplete` | `(message: MessageDisplay) => void` | Stream completed |
-| `onExecutionTraceClick` | `(data: unknown) => void` | Trace button clicked |
-| `onResetSession` | `() => void` | New Session/reset button clicked |
-| `onUploadImageClick` | `() => void` | v2 Upload image option clicked |
-| `onAttachFileClick` | `() => void` | v2 Attach file option clicked |
-
-### Context API: `usePaymanChat()`
-
-| Method | Type | Description |
-|--------|------|-------------|
-| `resetSession()` | `() => void` | Clear messages & reset session |
-| `clearMessages()` | `() => void` | Clear messages only |
-| `cancelStream()` | `() => void` | Cancel current stream |
-| `getSessionId()` | `() => string \| undefined` | Get session ID |
-| `getMessages()` | `() => MessageDisplay[]` | Get all messages |
-| `isWaitingForResponse` | `boolean` | Check if waiting |
-
-## Documentation
-
-- **[USAGE.md](./USAGE.md)** - Comprehensive usage guide
-- **[CONTEXT_API.md](./CONTEXT_API.md)** - Context API reference
-- **[ENDPOINTS.md](./ENDPOINTS.md)** - API endpoints guide
-- **[CHANGELOG.md](./CHANGELOG.md)** - Version history
-- **[docs/](./docs/README.md)** - V2 streaming events, styling, and CSS class reference (`uiVersion: 2`)
-
-## Theming: Shimmer (active step text)
-
-The active-step shimmer uses **full color values** only. Define these CSS variables in your app (e.g. in `:root` or your theme file) so the shimmer matches your theme:
-
-| Variable | Description |
-|----------|-------------|
-| `--payman-shimmer-muted` | Muted color (gradient ends) |
-| `--payman-shimmer-foreground` | Main text color (gradient sides) |
-| `--payman-shimmer-primary` | Accent color (gradient center) |
-
-**Example (hex theme):**
-
-```css
-:root {
-  --payman-shimmer-muted: var(--muted-foreground);
-  --payman-shimmer-foreground: var(--foreground);
-  --payman-shimmer-primary: var(--primary);
-}
-```
+### Safe cosmetic defaults
 
-**Example (HSL-component theme):**
+Leaving the `ui` block out renders a usable ChatGPT-style surface:
 
-```css
-:root {
-  --payman-shimmer-muted: hsl(var(--muted-foreground));
-  --payman-shimmer-foreground: hsl(var(--foreground));
-  --payman-shimmer-primary: hsl(var(--primary));
-}
-```
+- Layout: `full-width`
+- Placeholder: `"Type your message..."`
+- Empty-state text: `"What can I help with?"`
+- Agent name: `"Assistant"` (shown)
+- Streaming dot: on
+- Execution steps: on
+- No avatars, timestamps, or reset button
+- No voice, no session history
 
-If these are not set, the widget falls back to neutral gray/blue.
+Turn features on with booleans, and only reach for the full object form when you need custom labels, widths, or per-option toggles.
 
-## Common Issues
+## Session history
 
-### 401 Error: "Workflow stage is not set"
+Pass `ui.sessionHistory: true` and provide `workflow.id` + `session.owner.id`. `<PaymanChat/>` mounts a resizable, collapsible sidebar on desktop and a hamburger-triggered drawer on mobile. Clicking a row calls `loadSession(sessionId)` — which cancels any in-flight stream, clears the current chat, fetches the conversation history, and renders it with `isHistorical: true` (renderers skip the thinking/step UI for those rows).
 
-Add `streamEndpoint` to your config:
+Need custom chrome? Mount the sidebar yourself:
 
 ```tsx
-api: {
-  baseUrl: "...",
-  authToken: "...",
-  streamEndpoint: "/api/playground/ask/stream", // Add this
+import { SessionHistorySidebar, usePaymanChat } from "@paymanai/payman-ask-sdk";
+
+function MyShell() {
+  const chat = usePaymanChat();
+  return (
+    <SessionHistorySidebar
+      config={config}
+      options={{ defaultWidth: 320 }}
+      onSelectSession={(s) => chat.loadSession(s.sessionId)}
+      mobileOpen={mobileOpen}
+      onMobileOpenChange={setMobileOpen}
+    />
+  );
 }
 ```
 
-See [ENDPOINTS.md](./ENDPOINTS.md) for details.
+## `usePaymanChat()` hook
 
-## Examples
+Call from any descendant of `<PaymanChat/>`:
 
-Check the integration examples:
-- `src/components/Playground/PlaygroundChatColumn/` - Playground integration
-- `src/components/Builder/ChatInterface/` - Builder integration
+```tsx
+const chat = usePaymanChat();
+chat.resetSession();
+chat.loadSession(sessionId);
+chat.cancelStream();
+chat.getSessionId();
+chat.getMessages();
+```
 
-## License
+## Callbacks
 
-MIT
+```ts
+type ChatCallbacks = {
+  onMessageSent?: (text: string) => void;
+  onStreamStart?: () => void;
+  onStreamComplete?: (message: MessageDisplay) => void;
+  onError?: (error: Error) => void;
+  onSessionIdChange?: (sessionId: string) => void;
+  onExecutionTraceClick?: (data: { message; tracingData?; executionId? }) => void;
+  onResetSession?: () => void;
+  onUploadImageClick?: () => void;
+  onAttachFileClick?: () => void;
+  onUserActionRequired?: (req: UserActionRequest) => void;
+  onUserActionEvent?: (eventType, message) => void;
+};
+```
 
-## Support
+## Migrating from v1
+
+**The v2 release removes the old flat config and the `ui.engine = 1` path entirely.** The v1 renderer has been deleted. Translation table:
+
+| v1 (flat)                       | v2 (nested)                                      |
+| ------------------------------- | ------------------------------------------------ |
+| `api`                           | `api` (unchanged)                                |
+| `workflowName`                  | `workflow.name`                                  |
+| `workflowVersion`               | `workflow.version`                               |
+| `stage`                         | `workflow.stage`                                 |
+| `sessionParams`                 | `session.owner`                                  |
+| `userId`                        | `session.userId`                                 |
+| `autoGenerateSessionId`         | `session.autoGenerateId`                         |
+| `initialSessionId`              | `session.initialId`                              |
+| `initialMessages`               | `session.initialMessages`                        |
+| `isChatDisabled` / `disabledComponent` / `hasAskPermission` | `availability: { state: "disabled" \| "readOnly" \| "ready", reason? }` |
+| `sentryDsn`                     | `observability.sentryDsn`                        |
+| `uiVersion`                     | **removed** (v2 only)                            |
+| `enableVoice`, `voiceLang`, `voiceInterimResults`, `voiceContinuous` | `ui.input.voice: boolean \| VoiceOptions`       |
+| `placeholder`                   | `ui.input.placeholder`                           |
+| `emptyStateText` / `showEmptyStateIcon` / `emptyStateComponent` | `ui.emptyState.{ text, icon, content }`          |
+| `showResetSession`              | `ui.input.showResetButton`                       |
+| `showAttachmentButton` / `showUploadImageButton` / `showAttachFileButton` | `ui.input.attachments: boolean \| { uploadImage, attachFile }` |
+| `messageActions`                | `ui.messages.actions`                            |
+| `showAvatars` / `showUserAvatar` / `showAssistantAvatar` | `ui.messages.avatars: boolean \| { user, assistant }` |
+| `showTimestamps`                | `ui.messages.timestamps`                         |
+| `showStreamingDot`              | `ui.messages.streamingDot`                       |
+| `showExecutionSteps`            | `ui.execution.showSteps`                         |
+| `streamingStepsText`            | `ui.execution.streamingLabel`                    |
+| `completedStepsText`            | `ui.execution.completedLabel`                    |
+| `showAgentName` / `agentName`   | `ui.agent.{ showName, name }`                    |
+| `inputStyle` / `animated` / `sidebarBrandName` / `disableInput` | **removed** (dead fields)                        |
+| `showSessionParams` / header `onLoadSession` dropdown | **removed** — use `ui.sessionHistory` sidebar    |
+
+### Deleted APIs
+
+- `useChat` / `UseChatReturn` (v1). Use `useChatV2` / `UseChatV2Return`.
+- `AgentMessage`, `MessageList`, `MessageRow`, `ChatInput`, `StreamingMessage`, `UserMessage`, `MessageRowSkeleton` component re-exports.
+- `ChatConfig.uiVersion`.
+
+### New APIs
+
+- `useChatV2().loadSession(sessionId)` — replace the active chat with history.
+- `usePaymanChat().loadSession` — same, from context.
+- `SessionHistorySidebar` component + `useSessionHistory` hook.
+- `listSessions` / `listConversations` REST helpers (from the core SDK).
+- `buildScopeKey(config)` — compose the client-side state-scope key from `session.userId + workflow.id + workflow.version + workflow.stage`.
+
+## React Native
+
+v2 ships web-only for the moment. `PaymanChat` on React Native renders a placeholder — pin `@paymanai/payman-ask-sdk@^1` if you need the v1 native renderer while the v2 RN rewrite lands.
 
-For issues and questions, please file an issue on GitHub.
+## License
+
+MIT