npm package: @paymanai/payman-ask-sdk
Description: Reusable chat SDK for Payman workflows with streaming support (Web & React Native)
Author: Payman
Latest version: 1.2.23

# Payman Ask SDK

A reusable React component library for building chat interfaces powered by Payman workflows.

## Features

✅ **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

```bash
npm install @paymanai/payman-ask-sdk
# or
yarn add @paymanai/payman-ask-sdk
# or  
bun add @paymanai/payman-ask-sdk
```

## Quick Start

### For Playground/Testing

```tsx
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

```tsx
<PaymanChat
  config={{
    api: {
      baseUrl: "https://api.example.com",
      authToken: "your-api-key", // API key with stage configured
    },
    workflowName: "my-workflow",
    userId: "user-123", // Required for chatStore and activeStreamStore
    stage: "PROD",
    sessionParams: {
      id: "user-123",
      name: "John Doe",
    },
  }}
/>
```

## Custom Header

```tsx
import { PaymanChat, usePaymanChat } from "@paymanai/payman-ask-sdk";

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>
  );
}

function MyApp() {
  return (
    <PaymanChat config={config}>
      <ChatHeader />
    </PaymanChat>
  );
}
```

## 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) |

### `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 |

### 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

## 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);
}
```

**Example (HSL-component theme):**

```css
:root {
  --payman-shimmer-muted: hsl(var(--muted-foreground));
  --payman-shimmer-foreground: hsl(var(--foreground));
  --payman-shimmer-primary: hsl(var(--primary));
}
```

If these are not set, the widget falls back to neutral gray/blue.

## Common Issues

### 401 Error: "Workflow stage is not set"

Add `streamEndpoint` to your config:

```tsx
api: {
  baseUrl: "...",
  authToken: "...",
  streamEndpoint: "/api/playground/ask/stream", // Add this
}
```

See [ENDPOINTS.md](./ENDPOINTS.md) for details.

## Examples

Check the integration examples:
- `src/components/Playground/PlaygroundChatColumn/` - Playground integration
- `src/components/Builder/ChatInterface/` - Builder integration

## License

MIT

## Support

For issues and questions, please file an issue on GitHub.