@paymanai/payman-ask-sdk 1.0.0

package/README.md

@@ -0,0 +1,184 @@
+# 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",
+        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",
+    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 |
+| `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
+
+## 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.

package/dist/index.d.mts

@@ -0,0 +1,388 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React from 'react';
+import React__default from 'react';
+import { ClassValue } from 'clsx';
+export { StreamEvent, StreamOptions, generateId, streamWorkflowEvents, useChat } from '@paymanai/payman-typescript-ask-sdk';
+
+type MessageRole = "user" | "assistant" | "system";
+type StreamProgress = "started" | "processing" | "completed" | "error";
+type WorkflowStage = "DEV" | "SANDBOX" | "PROD" | "ARCHIVED";
+type StreamingStep = {
+    id: string;
+    eventType: string;
+    message: string;
+    status: "in_progress" | "completed" | "error" | "pending";
+    timestamp: number;
+    elapsedMs?: number;
+};
+type ChunkDisplay = {
+    id?: string;
+    text?: string;
+    similarityScore?: number;
+    rrfScore?: number;
+};
+type MessageDisplay = {
+    id: string;
+    sessionId?: string;
+    role: MessageRole;
+    content: string;
+    timestamp: string;
+    isError?: boolean;
+    errorDetails?: string;
+    chunks?: ChunkDisplay[];
+    tracingData?: unknown;
+    executionId?: string;
+    isStreaming?: boolean;
+    streamingContent?: string;
+    currentWorker?: string;
+    currentMessage?: string;
+    streamProgress?: StreamProgress;
+    steps?: StreamingStep[];
+    isCancelled?: boolean;
+    currentExecutingStepId?: string;
+};
+type SessionParams = {
+    id?: string;
+    name?: string;
+    attributes?: Record<string, string>;
+};
+type APIConfig = {
+    /** Base API URL */
+    baseUrl: string;
+    /** Auth token */
+    authToken?: string;
+    /** Custom headers */
+    headers?: Record<string, string>;
+    /** API endpoint for streaming (default: /api/workflows/ask/stream) */
+    streamEndpoint?: string;
+};
+type ChatConfig = {
+    /** API configuration - required for the library to make calls */
+    api: APIConfig;
+    /** Workflow name */
+    workflowName: string;
+    /** Workflow version */
+    workflowVersion?: number;
+    /** Stage/Environment */
+    stage?: WorkflowStage;
+    /** Session params */
+    sessionParams?: SessionParams;
+    /** Custom placeholder text */
+    placeholder?: string;
+    /** Empty state text */
+    emptyStateText?: string;
+    /** Show icon in empty state */
+    showEmptyStateIcon?: boolean;
+    /** Show agent name */
+    showAgentName?: boolean;
+    /** Agent name */
+    agentName?: string;
+    /** Show avatars for user and assistant messages */
+    showAvatars?: boolean;
+    /** Show user avatar only (overrides showAvatars for user messages) */
+    showUserAvatar?: boolean;
+    /** Show assistant avatar only (overrides showAvatars for assistant messages) */
+    showAssistantAvatar?: boolean;
+    /** Show execution steps section with "Completed in X.Xs" */
+    showExecutionSteps?: boolean;
+    /** Show animated dot indicator during streaming */
+    showStreamingDot?: boolean;
+    /** Custom text format for streaming steps button. Use {count} for step count. Default: "View progress ({count} steps)" */
+    streamingStepsText?: string;
+    /** Custom text format for completed steps button. Use {count} for step count, {time} for elapsed time. Default: "Completed in {time}s ({count} steps)" */
+    completedStepsText?: string;
+    /** Input style variant: "rounded" (yaak style) or "flat" (paygent-central style). Default: "rounded" */
+    inputStyle?: "rounded" | "flat";
+    /** Layout style: "centered" (durango style) or "full-width" (default). Default: "full-width" */
+    layout?: "centered" | "full-width";
+    /** Show timestamps on messages */
+    showTimestamps?: boolean;
+    /** Enable animations */
+    animated?: boolean;
+    /** Disable input */
+    disableInput?: boolean;
+    /** Has permission to ask */
+    hasAskPermission?: boolean;
+    /** Auto-generate session ID */
+    autoGenerateSessionId?: boolean;
+    /** Disable the entire chat and show disabled state */
+    isChatDisabled?: boolean;
+    /** Custom component to render when chat is disabled. If not provided, default disabled UI will be shown */
+    disabledComponent?: React__default.ReactNode;
+};
+type ChatCallbacks = {
+    /** Called when a message is sent (before API call) */
+    onMessageSent?: (message: string) => void;
+    /** Called when streaming starts */
+    onStreamStart?: () => void;
+    /** Called when streaming completes */
+    onStreamComplete?: (message: MessageDisplay) => void;
+    /** Called when an error occurs */
+    onError?: (error: Error) => void;
+    /** Called when execution trace is clicked - provides data instead of UI */
+    onExecutionTraceClick?: (data: {
+        message: MessageDisplay;
+        tracingData?: unknown;
+        executionId?: string;
+    }) => void;
+    /** Called when session ID changes */
+    onSessionIdChange?: (sessionId: string) => void;
+};
+type PaymanChatProps = {
+    /** Chat configuration - includes API config */
+    config: ChatConfig;
+    /** Callbacks for events */
+    callbacks?: ChatCallbacks;
+    /** Custom class name */
+    className?: string;
+    /** Custom style */
+    style?: React__default.CSSProperties;
+    /** Custom children to render (e.g., header) */
+    children?: React__default.ReactNode;
+};
+type ChatInputProps = {
+    /** Input value */
+    value: string;
+    /** On change handler */
+    onChange: (value: string) => void;
+    /** On send handler */
+    onSend: () => void;
+    /** On pause/cancel handler */
+    onPause?: () => void;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Is waiting for response */
+    isWaitingForResponse?: boolean;
+    /** Has selected session */
+    hasSelectedSession?: boolean;
+    /** Is session params configured */
+    isSessionParamsConfigured?: boolean;
+    /** On input click handler */
+    onClick?: () => void;
+    /** Input style variant */
+    inputStyle?: "rounded" | "flat";
+    /** Layout style */
+    layout?: "centered" | "full-width";
+    /** Custom class name */
+    className?: string;
+};
+type MessageListProps = {
+    /** Messages to display */
+    messages: MessageDisplay[];
+    /** Loading state */
+    isLoading?: boolean;
+    /** Empty state text */
+    emptyStateText?: string;
+    /** Show icon in empty state */
+    showEmptyStateIcon?: boolean;
+    /** Layout style */
+    layout?: "centered" | "full-width";
+    /** Show timestamps on messages */
+    showTimestamps?: boolean;
+    /** Stage */
+    stage?: WorkflowStage;
+    /** Animated */
+    animated?: boolean;
+    /** Show agent name */
+    showAgentName?: boolean;
+    /** Agent name */
+    agentName?: string;
+    /** Show avatars */
+    showAvatars?: boolean;
+    /** Show user avatar only (overrides showAvatars) */
+    showUserAvatar?: boolean;
+    /** Show assistant avatar only (overrides showAvatars) */
+    showAssistantAvatar?: boolean;
+    /** Show execution steps */
+    showExecutionSteps?: boolean;
+    /** Show streaming dot */
+    showStreamingDot?: boolean;
+    /** Custom streaming steps text */
+    streamingStepsText?: string;
+    /** Custom completed steps text */
+    completedStepsText?: string;
+    /** On execution trace click */
+    onExecutionTraceClick?: (data: {
+        message: MessageDisplay;
+        tracingData?: unknown;
+        executionId?: string;
+    }) => void;
+    /** Custom class name */
+    className?: string;
+};
+type MessageRowProps = {
+    /** Message to display */
+    message: MessageDisplay;
+    /** Stage */
+    stage?: WorkflowStage;
+    /** Animated */
+    animated?: boolean;
+    /** Show agent name */
+    showAgentName?: boolean;
+    /** Agent name */
+    agentName?: string;
+    /** Show avatars */
+    showAvatars?: boolean;
+    /** Show user avatar only (overrides showAvatars) */
+    showUserAvatar?: boolean;
+    /** Show assistant avatar only (overrides showAvatars) */
+    showAssistantAvatar?: boolean;
+    /** Show execution steps */
+    showExecutionSteps?: boolean;
+    /** Show streaming dot */
+    showStreamingDot?: boolean;
+    /** Custom streaming steps text */
+    streamingStepsText?: string;
+    /** Custom completed steps text */
+    completedStepsText?: string;
+    /** On execution trace click */
+    onExecutionTraceClick?: (data: {
+        message: MessageDisplay;
+        tracingData?: unknown;
+        executionId?: string;
+    }) => void;
+};
+type UserMessageProps = {
+    /** Message to display */
+    message: MessageDisplay;
+    /** Animated */
+    animated?: boolean;
+    /** Show avatar */
+    showAvatar?: boolean;
+};
+type AgentMessageProps = {
+    /** Message to display */
+    message: MessageDisplay;
+    /** Stage */
+    stage?: WorkflowStage;
+    /** Animated */
+    animated?: boolean;
+    /** Show agent name */
+    showAgentName?: boolean;
+    /** Agent name */
+    agentName?: string;
+    /** Show avatar */
+    showAvatar?: boolean;
+    /** Layout style */
+    layout?: "centered" | "full-width";
+    /** Show timestamp */
+    showTimestamp?: boolean;
+    /** Show execution steps */
+    showExecutionSteps?: boolean;
+    /** Show streaming dot */
+    showStreamingDot?: boolean;
+    /** Custom streaming steps text */
+    streamingStepsText?: string;
+    /** Custom completed steps text */
+    completedStepsText?: string;
+    /** On execution trace click */
+    onExecutionTraceClick?: (data: {
+        message: MessageDisplay;
+        tracingData?: unknown;
+        executionId?: string;
+    }) => void;
+};
+type StreamingMessageProps = {
+    /** Streaming content */
+    content: string;
+    /** Is currently streaming */
+    isStreaming: boolean;
+    /** Current worker */
+    currentWorker?: string;
+    /** Current message */
+    currentMessage?: string;
+    /** Stream progress */
+    streamProgress: StreamProgress;
+    /** Error message */
+    error?: string;
+    /** Streaming steps */
+    steps?: StreamingStep[];
+};
+type ChatHeaderProps = {
+    /** Session ID */
+    sessionId?: string;
+    /** On copy session ID */
+    onCopySessionId?: (sessionId: string) => void;
+    /** On load session click */
+    onLoadSession?: () => void;
+    /** On new session click */
+    onNewSession?: () => void;
+    /** On session params click */
+    onSessionParamsClick?: () => void;
+    /** Show load session button */
+    showLoadSession?: boolean;
+    /** Show reset session button */
+    showResetSession?: boolean;
+    /** Show session params button */
+    showSessionParams?: boolean;
+    /** Show session params tooltip */
+    showSessionParamsTooltip?: boolean;
+    /** Session params button ref */
+    sessionParamsButtonRef?: React__default.RefObject<HTMLButtonElement | null> | undefined;
+    /** Custom children */
+    children?: React__default.ReactNode;
+    /** Custom class name */
+    className?: string;
+};
+
+declare function PaymanChat({ config, callbacks, className, style, children, }: PaymanChatProps): react_jsx_runtime.JSX.Element;
+
+interface PaymanChatContextValue {
+    /**
+     * Clear all messages and reset the chat
+     */
+    resetSession: () => void;
+    /**
+     * Clear all messages without resetting session ID
+     */
+    clearMessages: () => void;
+    /**
+     * Cancel current streaming operation
+     */
+    cancelStream: () => void;
+    /**
+     * Get current session ID
+     */
+    getSessionId: () => string | undefined;
+    /**
+     * Get all messages
+     */
+    getMessages: () => MessageDisplay[];
+    /**
+     * Check if currently waiting for response
+     */
+    isWaitingForResponse: boolean;
+}
+declare const PaymanChatContext: React.Context<PaymanChatContextValue | undefined>;
+/**
+ * Hook to access PaymanChat controls from parent components
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const chat = usePaymanChat();
+ *
+ *   return (
+ *     <>
+ *       <button onClick={chat.resetSession}>Reset</button>
+ *       <button onClick={chat.clearMessages}>Clear</button>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+declare function usePaymanChat(): PaymanChatContextValue;
+
+/**
+ * Utility function to merge Tailwind CSS classes
+ */
+declare function cn(...inputs: ClassValue[]): string;
+
+/**
+ * Format a timestamp to a readable date/time string
+ */
+declare function formatDate(timestamp: string | Date): string;
+
+export { type APIConfig, type AgentMessageProps, type ChatCallbacks, type ChatConfig, type ChatHeaderProps, type ChatInputProps, type ChunkDisplay, type MessageDisplay, type MessageListProps, type MessageRole, type MessageRowProps, PaymanChat, PaymanChatContext, type PaymanChatContextValue, type PaymanChatProps, type SessionParams, type StreamProgress, type StreamingMessageProps, type StreamingStep, type UserMessageProps, type WorkflowStage, cn, formatDate, usePaymanChat };