@paymanai/payman-typescript-ask-sdk 2.0.3 → 4.0.0

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import React from 'react';
+
 type VoiceState = "idle" | "listening" | "processing" | "error";
 type VoiceConfig = {
     /** Language for speech recognition (default: "en-US") */
@@ -68,7 +70,8 @@ type UseVoiceReturn = {
 
 type MessageRole = "user" | "assistant" | "system";
 type StreamProgress = "started" | "processing" | "completed" | "error";
-type WorkflowStage = "DEV" | "SANDBOX" | "PROD" | "ARCHIVED";
+/** Stage values accepted by the k2 playground API. */
+type AgentStage = "DEVELOPMENT" | "QA" | "PROD";
 type UserActionType = "PAYMENT_APPROVAL" | "PAYEE_APPROVAL";
 type UserActionRequest = {
     userActionId: string;
@@ -87,11 +90,21 @@ type StreamingStep = {
     id: string;
     eventType: string;
     message: string;
-    status: "in_progress" | "completed" | "error" | "pending";
+    status: "in_progress" | "completed" | "error" | "pending" | "skipped";
     timestamp: number;
     elapsedMs?: number;
     thinkingText?: string;
     isThinking?: boolean;
+    /**
+     * Pipeline stage key this step was minted for (e.g. "analyzer",
+     * "execution"). Only set for steps that originated from a K2
+     * STAGE_STARTED event. Used by the STAGE_COMPLETED/FAILED/SKIPPED
+     * handlers to find the matching in-progress step by stage key
+     * rather than by label — the label can be rewritten mid-run when
+     * the server sends a dynamic `message` (e.g. the Analyzer's
+     * LLM-generated status), so label-equality matching breaks.
+     */
+    stage?: string;
 };
 type ChunkDisplay = {
     id?: string;
@@ -118,118 +131,183 @@ type MessageDisplay = {
     steps?: StreamingStep[];
     isCancelled?: boolean;
     currentExecutingStepId?: string;
+    /** Result of user action (OTP approval/rejection) */
     userActionResult?: UserActionResult;
+    /** Current thinking block text (live, resets per block) */
     activeThinkingText?: string;
+    /** All thinking accumulated across blocks (for post-stream display) */
     allThinkingText?: string;
+    /** Pre-formatted thinking text built from steps + allThinkingText (v2 streaming format, matches demo) */
     formattedThinkingText?: string;
+    /** True while RAG image URLs are being resolved after the final response is shown */
     isResolvingImages?: boolean;
-    /** Elapsed thinking time in seconds, captured at stream completion and persisted. */
-    thinkingDurationSec?: number;
-    /** History row loaded via loadSession(). Renderers skip streaming/step UI. */
-    isHistorical?: boolean;
+    /**
+     * Server-computed wall-clock duration of the run. Set from the
+     * RUN_COMPLETED event's `totalTimeMs`. Authoritative — clients
+     * should prefer this over deriving an elapsed value from the
+     * `steps` timestamp/elapsedMs span.
+     */
+    totalElapsedMs?: number;
 };
-type SessionOwner = {
-    /** Sent as sessionOwnerId in the request body. */
+type SessionParams = {
     id?: string;
-    /** Sent as sessionOwnerLabel in the request body. */
     name?: string;
-    /** Sent as sessionAttributes in the request body. */
     attributes?: Record<string, string>;
 };
 type APIConfig = {
+    /** Base API URL */
     baseUrl: string;
+    /** Auth token */
     authToken?: string;
+    /** Custom headers */
     headers?: Record<string, string>;
-    /** Default: /api/workflows/ask/stream */
+    /** API endpoint for streaming (default: /api/playground/ask/stream) */
     streamEndpoint?: string;
-    /** Derived from streamEndpoint when omitted. */
+    /** API endpoint for resolving RAG image URLs (default derived from stream endpoint) */
     resolveImagesEndpoint?: string;
-    /** Default: "stage". Davis overrides to "workflowStage". */
-    stageQueryParam?: string;
 };
-type BaseChatConfig = {
+type ChatConfig = {
+    /** API configuration - required for the library to make calls */
     api: APIConfig;
-    workflow: {
-        /** Workflow uuid. Required when ui.sessionHistory is enabled. Contributes to the state-scope key. */
-        id?: string;
-        name: string;
-        version?: number;
-        stage?: WorkflowStage;
-    };
-    session?: {
-        /** Client-side chatStore scoping (not sent to API). Clear on logout. */
-        userId?: string;
-        owner?: SessionOwner;
-        /** Default true. */
-        autoGenerateId?: boolean;
-        initialId?: string;
-        initialMessages?: MessageDisplay[];
-    };
-};
-type SessionSummary = {
-    userId: string;
-    userLabel: string;
-    sessionId: string;
-    workflowId: string;
-    workflowName: string;
-    workflowVersion: number;
-    lastMessageAt: string;
-    messageCount: number;
-    sessionTitle: string;
-};
-type ConversationEntry = {
-    query: string;
-    response: string;
-    userId: string;
-    userLabel: string;
-    executionId: string;
-    createdAt: string;
-    inputTokens?: number;
-    outputTokens?: number;
-    totalTokens?: number;
-};
-type PageInfo = {
-    page: number;
-    size: number;
-    totalElements: number;
-    totalPages: number;
-    first: boolean;
-    last: boolean;
-    hasNext: boolean;
-    hasPrevious: boolean;
-};
-type SessionListResponse = {
-    success: boolean;
-    message: string;
-    data: SessionSummary[];
-    pageInfo: PageInfo;
-};
-type ConversationListResponse = {
-    success: boolean;
-    message: string;
-    data: ConversationEntry[];
-    pageInfo: PageInfo;
+    /** Agent ID to run against the k2 playground endpoint */
+    agentId: string;
+    /** User ID for chatStore and activeStreamStore — required for context store messages management. Set to undefined on logout to clear stored messages. */
+    userId?: string;
+    /** Stage/Environment */
+    stage?: AgentStage;
+    /** Query param name for stage (default: "stage"). */
+    stageQueryParam?: string;
+    /** 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;
+    /** Pre-populate the chat with messages (e.g. loaded conversation history) */
+    initialMessages?: MessageDisplay[];
+    /** Resume an existing session by providing its ID */
+    initialSessionId?: string;
 };
 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;
+    /** Called when a user action (e.g. OTP) is required */
     onUserActionRequired?: (request: UserActionRequest) => void;
+    /** Called on user action events (SUCCESS, INVALID, EXPIRED, REJECTED, RESENT, FAILED) */
     onUserActionEvent?: (eventType: string, message: string) => void;
+    /**
+     * Fires whenever the current streaming "status message" changes —
+     * the user-facing label for whatever stage is running right now
+     * (e.g. "Understanding your request…", "Pulling those up for you
+     * now.", "Executing…"). Consumers can use this to surface the
+     * status somewhere outside the chat bubble (e.g. a pipeline
+     * sidebar, an agent-avatar label).
+     *
+     * Called with `null` when no run is in flight — use that as the
+     * signal to revert any UI you had tied to the status.
+     */
+    onStatusMessage?: (message: string | null) => void;
+    /**
+     * Fires on every streaming event that updates the steps array —
+     * i.e. whenever a pipeline stage starts, completes, fails, or is
+     * skipped. Gives the host app the full steps snapshot so it can
+     * derive per-stage status (idle / running / completed / error)
+     * for UIs like a pipeline sidebar that animates stage progression.
+     *
+     * Each [StreamingStep] carries a `stage` field with the pipeline
+     * stage key (e.g. "sanitizer", "analyzer", "planner", "execution",
+     * "formatter") and a `status` field ("in_progress", "completed",
+     * "error"). The host derives the visual state by scanning the
+     * array — no reverse label-to-stage mapping required.
+     *
+     * Called with an empty array (`[]`) when the run ends so the host
+     * can reset all stages back to idle.
+     */
+    onStepsUpdate?: (steps: StreamingStep[]) => void;
 };
 
+/**
+ * Latency-vs-precision toggle surfaced in the chat widget. "fast"
+ * (default) lets the server cap list-tool fetches and answer
+ * quickly; "deep" runs a full analytical pass. The value is
+ * forwarded verbatim to the server, which normalizes it — any
+ * other string collapses to "fast" server-side. See
+ * `ExecutionRequest.analysisMode` on the k2 backend for the
+ * authoritative semantics.
+ */
+type AnalysisMode = "fast" | "deep";
+
+type SendMessageOptions = {
+    /**
+     * Latency-vs-precision toggle surfaced in the chat widget.
+     * `"fast"` (default) — the server caps list-tool fetches and
+     * returns a quick, directionally correct answer with a sampling
+     * caveat. `"deep"` — the server runs a full analytical pass,
+     * no row caps, full rankings.
+     *
+     * Undefined / omitted means "don't set — let the server use its
+     * default", which is `"fast"` today. Callers that want explicit
+     * control should always pass this; callers that don't care can
+     * skip it and inherit the server default.
+     */
+    analysisMode?: AnalysisMode;
+};
 type UseChatV2Return = {
     messages: MessageDisplay[];
-    sendMessage: (userMessage: string) => Promise<void>;
+    sendMessage: (userMessage: string, options?: SendMessageOptions) => Promise<void>;
     clearMessages: () => void;
-    /** Prepend older messages (e.g. loaded from history pagination). */
     prependMessages: (messages: MessageDisplay[]) => void;
     cancelStream: () => void;
     resetSession: () => void;
@@ -241,20 +319,8 @@ type UseChatV2Return = {
     approveUserAction: (otp: string) => Promise<void>;
     rejectUserAction: () => Promise<void>;
     resendOtp: () => Promise<void>;
-    /**
-     * Replace the active chat with a prior session's conversation history.
-     * Cancels any in-flight stream, clears current messages, fetches page 0 of
-     * conversations for `sessionId`, and renders them as historical rows.
-     */
-    loadSession: (sessionId: string) => Promise<void>;
-    /**
-     * The session id whose conversation history is currently being fetched
-     * via `loadSession`. `undefined` while idle. Use to render an activity
-     * indicator in the messages area / on the matching sidebar row.
-     */
-    loadingSessionId: string | undefined;
 };
-declare function useChatV2(config: BaseChatConfig, callbacks?: ChatCallbacks): UseChatV2Return;
+declare function useChatV2(config: ChatConfig, callbacks?: ChatCallbacks): UseChatV2Return;
 
 interface SpeechRecognitionEvent extends Event {
     results: SpeechRecognitionResultList;
@@ -308,6 +374,33 @@ type StreamEvent = {
     inputTokens?: number;
     outputTokens?: number;
     elapsedMs?: number;
+    /**
+     * Server-computed wall-clock duration from RunStarted to RunCompleted.
+     * Carried on RUN_COMPLETED only — prefer this over client-side
+     * step-span heuristics when present.
+     */
+    totalTimeMs?: number;
+    /**
+     * User-facing progress label. Attached to:
+     * - TOOL_CALL_STARTED / TOOL_CALL_COMPLETED — derived from the tool
+     *   name and (on completion) the row-count of the result, e.g.
+     *   "Pulling your transactions" / "Got 437 transactions".
+     * - LLM_CALL_STARTED — an in-voice "what's about to happen" line.
+     * - KEEP_ALIVE — a rotating phrase the server sends during silent-
+     *   think gaps so the chat-bubble status changes every few seconds
+     *   instead of staying frozen on "Thinking…".
+     *
+     * Clients should prefer this over raw type identifiers when
+     * rendering a progress row.
+     */
+    description?: string;
+    /**
+     * Carried on `THINKING_DELTA` events — Anthropic extended-thinking
+     * content streamed live from the upstream model. Distinct from
+     * `partialText` (the user-facing answer); routes into a separate
+     * "Thinking…" panel rather than the chat bubble.
+     */
+    text?: string;
     userActionRequest?: {
         userActionId: string;
         userActionType?: string;
@@ -339,11 +432,6 @@ declare function streamWorkflowEvents(url: string, body: Record<string, unknown>
  */
 declare function buildFormattedThinking(steps: StreamingStep[] | undefined, allThinkingText: string): string;
 
-/**
- * Orchestrator completion often includes "Identified N task(s) to execute", which is redundant in the UI.
- */
-declare function workingPhaseDetailForDisplay(raw: string): string;
-
 type V2EventProcessorState = {
     formattedThinkingText: string;
     finalResponse: string;
@@ -360,9 +448,11 @@ type V2EventProcessorState = {
     steps: StreamingStep[];
     stepCounter: number;
     currentExecutingStepId?: string;
+    /** Server-computed wall-clock duration captured from RUN_COMPLETED's `totalTimeMs`. */
+    totalElapsedMs?: number;
 };
 declare function createInitialV2State(): V2EventProcessorState;
-declare function processStreamEventV2(event: StreamEvent, state: V2EventProcessorState): V2EventProcessorState;
+declare function processStreamEventV2(rawEvent: StreamEvent, state: V2EventProcessorState): V2EventProcessorState;
 
 type UserActionResponse = {
     success: boolean;
@@ -371,62 +461,14 @@ type UserActionResponse = {
 /**
  * Submit a user action (e.g. OTP verification)
  */
-declare function submitUserAction(config: BaseChatConfig, userActionId: string, data?: Record<string, unknown>): Promise<UserActionResponse>;
+declare function submitUserAction(config: ChatConfig, userActionId: string, data?: Record<string, unknown>): Promise<UserActionResponse>;
 /**
  * Cancel / reject a user action
  */
-declare function cancelUserAction(config: BaseChatConfig, userActionId: string): Promise<UserActionResponse>;
+declare function cancelUserAction(config: ChatConfig, userActionId: string): Promise<UserActionResponse>;
 /**
  * Resend a user action (e.g. request a new OTP)
  */
-declare function resendUserAction(config: BaseChatConfig, userActionId: string): Promise<UserActionResponse>;
-
-type ListSessionsOptions = {
-    page?: number;
-    size?: number;
-    signal?: AbortSignal;
-};
-type ListConversationsOptions = {
-    sessionId: string;
-    page?: number;
-    size?: number;
-    signal?: AbortSignal;
-};
-/**
- * List the recent sessions for the current `session.owner.id` within a workflow.
- *
- * Two variants, selected by auth mode:
- *
- * 1. Authenticated user (api.authToken present, or any auth mode that isn't
- *    yaak-api-key playground):
- *    GET {baseUrl}/api/workflow-users/{ownerId}/sessions
- *      ?workflowId={workflow.id}&{stageParam}={stage}&page=&size=
- *
- * 2. Playground / yaak-api-key (no authToken, yaak-api-key header present):
- *    GET {baseUrl}/api/workflows/ask/sessions
- *      ?workflowUserId={ownerId}&workflowName={workflow.name}&{stageParam}={stage}&page=&size=
- */
-declare function listSessions(config: BaseChatConfig, opts?: ListSessionsOptions): Promise<SessionListResponse>;
-/**
- * List the conversation history for a single session.
- *
- * Two variants, selected by auth mode (mirrors `listSessions`):
- *
- * 1. Authenticated user (api.authToken present, or no yaak-api-key header):
- *    GET {baseUrl}/api/workflow-users/{ownerId}/conversations
- *      ?sessionId={sessionId}&{stageParam}={stage}&page=&size=
- *
- * 2. Playground / yaak-api-key (no authToken, x-yaak-api-key header present):
- *    GET {baseUrl}/api/workflows/ask/conversations
- *      ?workflowUserId={ownerId}&workflowName={workflow.name}&sessionId={sessionId}
- *      &{stageParam}={stage}&page=&size=
- */
-declare function listConversations(config: BaseChatConfig, opts: ListConversationsOptions): Promise<ConversationListResponse>;
-
-/**
- * Composite scope key for chatStore / activeStreamStore.
- * Same (userId, workflow id, version, stage) → same state across unmount/remount.
- */
-declare function buildScopeKey(config: BaseChatConfig): string;
+declare function resendUserAction(config: ChatConfig, userActionId: string): Promise<UserActionResponse>;
 
-export { type APIConfig, type BaseChatConfig, type ChatCallbacks, type ChunkDisplay, type ConversationEntry, type ConversationListResponse, type MessageDisplay, type MessageRole, type PageInfo, type SessionListResponse, type SessionOwner, type SessionSummary, type StreamEvent, type StreamOptions, type StreamProgress, type StreamingStep, type UseChatV2Return, type UseVoiceReturn, type UserActionRequest, type UserActionResult, type UserActionState, type UserActionType, type V2EventProcessorState, type VoiceCallbacks, type VoiceConfig, type VoicePermissions, type VoiceResult, type VoiceState, type WorkflowStage, buildFormattedThinking, buildScopeKey, cancelUserAction, createInitialV2State, generateId, listConversations, listSessions, processStreamEventV2, resendUserAction, streamWorkflowEvents, submitUserAction, useChatV2, useVoice, workingPhaseDetailForDisplay };
+export { type APIConfig, type AgentStage, type AnalysisMode, type ChatCallbacks, type ChatConfig, type ChunkDisplay, type MessageDisplay, type MessageRole, type SendMessageOptions, type SessionParams, type StreamEvent, type StreamOptions, type StreamProgress, type StreamingStep, type UseChatV2Return, type UseVoiceReturn, type UserActionRequest, type UserActionResult, type UserActionState, type UserActionType, type V2EventProcessorState, type VoiceCallbacks, type VoiceConfig, type VoicePermissions, type VoiceResult, type VoiceState, buildFormattedThinking, cancelUserAction, createInitialV2State, generateId, processStreamEventV2, resendUserAction, streamWorkflowEvents, submitUserAction, useChatV2, useVoice };