@paymanai/payman-typescript-ask-sdk 1.0.0

package/README.md

@@ -0,0 +1,159 @@
+# Payman TypeScript Ask SDK
+
+**Core TypeScript SDK for Payman workflows - Logic only, no UI components**
+
+This package contains only the business logic for interacting with Payman workflows. Use this if you want to build your own custom UI or integrate Payman into existing applications without including the default UI components.
+
+## Installation
+
+```bash
+npm install @paymanai/payman-typescript-ask-sdk
+# or
+yarn add @paymanai/payman-typescript-ask-sdk
+# or
+bun add @paymanai/payman-typescript-ask-sdk
+```
+
+## Features
+
+- ✅ **`useChat` Hook** - React hook for managing chat state and streaming
+- ✅ **Streaming Client** - Low-level streaming utilities
+- ✅ **TypeScript Types** - Full type definitions
+- ✅ **Cross-Platform** - Works in web and React Native
+- ✅ **Zero UI Dependencies** - No UI libraries included
+
+## Usage
+
+### Basic Example with Custom UI
+
+```typescript
+import { useChat } from '@paymanai/payman-typescript-ask-sdk';
+
+function MyCustomChat() {
+  const {
+    messages,
+    sendMessage,
+    isWaitingForResponse,
+    resetSession,
+  } = useChat({
+    config: {
+      api: {
+        baseUrl: 'https://api.payman.ai',
+        authToken: 'your-api-key',
+      },
+      workflowName: 'my-workflow',
+      stage: 'DEV',
+      sessionParams: {
+        id: 'user-123',
+        name: 'John Doe',
+      },
+    },
+  });
+
+  return (
+    <div>
+      {/* Your custom UI */}
+      {messages.map((msg) => (
+        <div key={msg.id}>{msg.content}</div>
+      ))}
+      
+      <button
+        onClick={() => sendMessage('Hello')}
+        disabled={isWaitingForResponse}
+      >
+        Send
+      </button>
+    </div>
+  );
+}
+```
+
+### Direct Streaming API
+
+```typescript
+import { streamWorkflowEvents } from '@paymanai/payman-typescript-ask-sdk';
+
+await streamWorkflowEvents(
+  'https://api.payman.ai/api/workflows/ask/stream',
+  {
+    workflowName: 'my-workflow',
+    userInput: 'Hello',
+    sessionOwnerId: 'user-123',
+    sessionOwnerLabel: 'John Doe',
+  },
+  {
+    'x-yaak-api-key': 'your-api-key',
+  },
+  {
+    onEvent: (event) => {
+      console.log('Received event:', event);
+    },
+    onComplete: () => {
+      console.log('Stream completed');
+    },
+    onError: (error) => {
+      console.error('Stream error:', error);
+    },
+  }
+);
+```
+
+## API Reference
+
+### `useChat(options)`
+
+React hook for managing chat state.
+
+**Parameters:**
+- `config: ChatConfig` - Configuration object
+  - `api.baseUrl: string` - API base URL
+  - `api.authToken?: string` - Authentication token
+  - `api.headers?: Record<string, string>` - Custom headers
+  - `workflowName: string` - Workflow name
+  - `stage?: WorkflowStage` - Environment stage (DEV, SANDBOX, PROD)
+  - `sessionParams?: SessionParams` - Session owner information
+- `callbacks?: ChatCallbacks` - Event callbacks
+
+**Returns:**
+- `messages: MessageDisplay[]` - Array of messages
+- `sendMessage: (message: string) => Promise<void>` - Send a message
+- `resetSession: () => void` - Reset the session
+- `cancelStream: () => void` - Cancel current stream
+- `isWaitingForResponse: boolean` - Loading state
+
+### `streamWorkflowEvents(url, body, headers, options)`
+
+Low-level streaming function.
+
+**Parameters:**
+- `url: string` - API endpoint URL
+- `body: Record<string, unknown>` - Request body
+- `headers: Record<string, string>` - Request headers
+- `options: StreamOptions` - Streaming options
+  - `onEvent?: (event: StreamEvent) => void` - Event callback
+  - `onComplete?: () => void` - Completion callback
+  - `onError?: (error: Error) => void` - Error callback
+  - `signal?: AbortSignal` - Abort signal
+
+## TypeScript Types
+
+All types are exported:
+
+```typescript
+import type {
+  ChatConfig,
+  ChatCallbacks,
+  MessageDisplay,
+  StreamingStep,
+  WorkflowStage,
+  // ... and more
+} from '@paymanai/payman-typescript-ask-sdk';
+```
+
+## Related Packages
+
+- **[@paymanai/payman-ask-sdk](../payman-ask-sdk)** - Full SDK with UI components (uses this package internally)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,173 @@
+import React from 'react';
+
+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.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;
+};
+
+declare function useChat(config: ChatConfig, callbacks?: ChatCallbacks): {
+    messages: MessageDisplay[];
+    sendMessage: (userMessage: string) => Promise<void>;
+    clearMessages: () => void;
+    cancelStream: () => void;
+    resetSession: () => void;
+    getSessionId: () => string | undefined;
+    getMessages: () => MessageDisplay[];
+    isWaitingForResponse: boolean;
+    sessionId: string | undefined;
+};
+
+/**
+ * Cross-platform UUID v4 generator
+ * Works in both browser and React Native environments
+ */
+declare function generateId(): string;
+
+/**
+ * Streaming client for handling SSE (Server-Sent Events) from the API
+ */
+type StreamEvent = {
+    eventType: string;
+    workerName?: string;
+    message?: string;
+    errorMessage?: string;
+    response?: unknown;
+    executionId?: string;
+    sessionId?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    elapsedMs?: number;
+    [key: string]: unknown;
+};
+type StreamOptions = {
+    signal?: AbortSignal;
+    onEvent?: (event: StreamEvent) => void;
+    onError?: (error: Error) => void;
+    onComplete?: () => void;
+};
+/**
+ * Stream workflow events from the API
+ */
+declare function streamWorkflowEvents(url: string, body: Record<string, unknown>, headers: Record<string, string>, options?: StreamOptions): Promise<void>;
+
+export { type APIConfig, type ChatCallbacks, type ChatConfig, type ChunkDisplay, type MessageDisplay, type MessageRole, type SessionParams, type StreamEvent, type StreamOptions, type StreamProgress, type StreamingStep, type WorkflowStage, generateId, streamWorkflowEvents, useChat };

package/dist/index.d.ts

@@ -0,0 +1,173 @@
+import React from 'react';
+
+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.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;
+};
+
+declare function useChat(config: ChatConfig, callbacks?: ChatCallbacks): {
+    messages: MessageDisplay[];
+    sendMessage: (userMessage: string) => Promise<void>;
+    clearMessages: () => void;
+    cancelStream: () => void;
+    resetSession: () => void;
+    getSessionId: () => string | undefined;
+    getMessages: () => MessageDisplay[];
+    isWaitingForResponse: boolean;
+    sessionId: string | undefined;
+};
+
+/**
+ * Cross-platform UUID v4 generator
+ * Works in both browser and React Native environments
+ */
+declare function generateId(): string;
+
+/**
+ * Streaming client for handling SSE (Server-Sent Events) from the API
+ */
+type StreamEvent = {
+    eventType: string;
+    workerName?: string;
+    message?: string;
+    errorMessage?: string;
+    response?: unknown;
+    executionId?: string;
+    sessionId?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    elapsedMs?: number;
+    [key: string]: unknown;
+};
+type StreamOptions = {
+    signal?: AbortSignal;
+    onEvent?: (event: StreamEvent) => void;
+    onError?: (error: Error) => void;
+    onComplete?: () => void;
+};
+/**
+ * Stream workflow events from the API
+ */
+declare function streamWorkflowEvents(url: string, body: Record<string, unknown>, headers: Record<string, string>, options?: StreamOptions): Promise<void>;
+
+export { type APIConfig, type ChatCallbacks, type ChatConfig, type ChunkDisplay, type MessageDisplay, type MessageRole, type SessionParams, type StreamEvent, type StreamOptions, type StreamProgress, type StreamingStep, type WorkflowStage, generateId, streamWorkflowEvents, useChat };