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

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

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

<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

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 - Comprehensive usage guide
• CONTEXT_API.md - Context API reference
• ENDPOINTS.md - API endpoints guide
• 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):

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

Example (HSL-component theme):

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

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

See 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.