@paymanai/payman-typescript-ask-sdk 1.2.11 → 2.0.1

package/dist/index.d.mts

@@ -1,5 +1,3 @@
-import React from 'react';
-
 type VoiceState = "idle" | "listening" | "processing" | "error";
 type VoiceConfig = {
     /** Language for speech recognition (default: "en-US") */
@@ -120,146 +118,116 @@ 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;
+    /** History row loaded via loadSession(). Renderers skip streaming/step UI. */
+    isHistorical?: boolean;
 };
-type SessionParams = {
+type SessionOwner = {
+    /** Sent as sessionOwnerId in the request body. */
     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>;
-    /** API endpoint for streaming (default: /api/workflows/ask/stream) */
+    /** Default: /api/workflows/ask/stream */
     streamEndpoint?: string;
-    /** API endpoint for resolving RAG image URLs (default: /api/playground/ask/resolve-image-urls) */
+    /** Derived from streamEndpoint when omitted. */
     resolveImagesEndpoint?: string;
+    /** Default: "stage". Davis overrides to "workflowStage". */
+    stageQueryParam?: string;
 };
-type ChatConfig = {
-    /** API configuration - required for the library to make calls */
+type BaseChatConfig = {
     api: APIConfig;
-    /** Workflow name */
+    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;
-    /** User ID for chatStore and activeStreamStore — required for context store messages management. Set to undefined on logout to clear stored messages. */
-    userId?: string;
-    /** Workflow version */
-    workflowVersion?: number;
-    /** Stage/Environment */
-    stage?: WorkflowStage;
-    /** Query param name for stage (default: "stage"). Use e.g. "workflowStage" if the API expects that name. */
-    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;
+    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;
 };
 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;
 };
 
-type UseChatReturn = {
-    messages: MessageDisplay[];
-    sendMessage: (userMessage: string) => Promise<void>;
-    clearMessages: () => void;
-    /** Prepend older messages to the top of the list (e.g. loaded from history pagination) */
-    prependMessages: (messages: MessageDisplay[]) => void;
-    cancelStream: () => void;
-    resetSession: () => void;
-    getSessionId: () => string | undefined;
-    getMessages: () => MessageDisplay[];
-    isWaitingForResponse: boolean;
-    sessionId: string | undefined;
-    /** User action (OTP) state — always present, inert when workflow has no user actions */
-    userActionState: UserActionState;
-    /** Submit OTP for approval */
-    approveUserAction: (otp: string) => Promise<void>;
-    /** Reject / cancel a user action */
-    rejectUserAction: () => Promise<void>;
-    /** Resend OTP code */
-    resendOtp: () => Promise<void>;
-};
-declare function useChat(config: ChatConfig, callbacks?: ChatCallbacks): UseChatReturn;
-
 type UseChatV2Return = {
     messages: MessageDisplay[];
     sendMessage: (userMessage: string) => Promise<void>;
     clearMessages: () => void;
+    /** Prepend older messages (e.g. loaded from history pagination). */
     prependMessages: (messages: MessageDisplay[]) => void;
     cancelStream: () => void;
     resetSession: () => void;
@@ -271,8 +239,20 @@ 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: ChatConfig, callbacks?: ChatCallbacks): UseChatV2Return;
+declare function useChatV2(config: BaseChatConfig, callbacks?: ChatCallbacks): UseChatV2Return;
 
 interface SpeechRecognitionEvent extends Event {
     results: SpeechRecognitionResultList;
@@ -389,14 +369,62 @@ type UserActionResponse = {
 /**
  * Submit a user action (e.g. OTP verification)
  */
-declare function submitUserAction(config: ChatConfig, userActionId: string, data?: Record<string, unknown>): Promise<UserActionResponse>;
+declare function submitUserAction(config: BaseChatConfig, userActionId: string, data?: Record<string, unknown>): Promise<UserActionResponse>;
 /**
  * Cancel / reject a user action
  */
-declare function cancelUserAction(config: ChatConfig, userActionId: string): Promise<UserActionResponse>;
+declare function cancelUserAction(config: BaseChatConfig, userActionId: string): Promise<UserActionResponse>;
 /**
  * Resend a user action (e.g. request a new OTP)
  */
-declare function resendUserAction(config: ChatConfig, userActionId: string): Promise<UserActionResponse>;
+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;
 
-export { type APIConfig, type ChatCallbacks, type ChatConfig, type ChunkDisplay, type MessageDisplay, type MessageRole, type SessionParams, type StreamEvent, type StreamOptions, type StreamProgress, type StreamingStep, type UseChatReturn, 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, cancelUserAction, createInitialV2State, generateId, processStreamEventV2, resendUserAction, streamWorkflowEvents, submitUserAction, useChat, useChatV2, useVoice, workingPhaseDetailForDisplay };
+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 };

package/dist/index.d.ts

@@ -1,5 +1,3 @@
-import React from 'react';
-
 type VoiceState = "idle" | "listening" | "processing" | "error";
 type VoiceConfig = {
     /** Language for speech recognition (default: "en-US") */
@@ -120,146 +118,116 @@ 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;
+    /** History row loaded via loadSession(). Renderers skip streaming/step UI. */
+    isHistorical?: boolean;
 };
-type SessionParams = {
+type SessionOwner = {
+    /** Sent as sessionOwnerId in the request body. */
     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>;
-    /** API endpoint for streaming (default: /api/workflows/ask/stream) */
+    /** Default: /api/workflows/ask/stream */
     streamEndpoint?: string;
-    /** API endpoint for resolving RAG image URLs (default: /api/playground/ask/resolve-image-urls) */
+    /** Derived from streamEndpoint when omitted. */
     resolveImagesEndpoint?: string;
+    /** Default: "stage". Davis overrides to "workflowStage". */
+    stageQueryParam?: string;
 };
-type ChatConfig = {
-    /** API configuration - required for the library to make calls */
+type BaseChatConfig = {
     api: APIConfig;
-    /** Workflow name */
+    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;
-    /** User ID for chatStore and activeStreamStore — required for context store messages management. Set to undefined on logout to clear stored messages. */
-    userId?: string;
-    /** Workflow version */
-    workflowVersion?: number;
-    /** Stage/Environment */
-    stage?: WorkflowStage;
-    /** Query param name for stage (default: "stage"). Use e.g. "workflowStage" if the API expects that name. */
-    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;
+    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;
 };
 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;
 };
 
-type UseChatReturn = {
-    messages: MessageDisplay[];
-    sendMessage: (userMessage: string) => Promise<void>;
-    clearMessages: () => void;
-    /** Prepend older messages to the top of the list (e.g. loaded from history pagination) */
-    prependMessages: (messages: MessageDisplay[]) => void;
-    cancelStream: () => void;
-    resetSession: () => void;
-    getSessionId: () => string | undefined;
-    getMessages: () => MessageDisplay[];
-    isWaitingForResponse: boolean;
-    sessionId: string | undefined;
-    /** User action (OTP) state — always present, inert when workflow has no user actions */
-    userActionState: UserActionState;
-    /** Submit OTP for approval */
-    approveUserAction: (otp: string) => Promise<void>;
-    /** Reject / cancel a user action */
-    rejectUserAction: () => Promise<void>;
-    /** Resend OTP code */
-    resendOtp: () => Promise<void>;
-};
-declare function useChat(config: ChatConfig, callbacks?: ChatCallbacks): UseChatReturn;
-
 type UseChatV2Return = {
     messages: MessageDisplay[];
     sendMessage: (userMessage: string) => Promise<void>;
     clearMessages: () => void;
+    /** Prepend older messages (e.g. loaded from history pagination). */
     prependMessages: (messages: MessageDisplay[]) => void;
     cancelStream: () => void;
     resetSession: () => void;
@@ -271,8 +239,20 @@ 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: ChatConfig, callbacks?: ChatCallbacks): UseChatV2Return;
+declare function useChatV2(config: BaseChatConfig, callbacks?: ChatCallbacks): UseChatV2Return;
 
 interface SpeechRecognitionEvent extends Event {
     results: SpeechRecognitionResultList;
@@ -389,14 +369,62 @@ type UserActionResponse = {
 /**
  * Submit a user action (e.g. OTP verification)
  */
-declare function submitUserAction(config: ChatConfig, userActionId: string, data?: Record<string, unknown>): Promise<UserActionResponse>;
+declare function submitUserAction(config: BaseChatConfig, userActionId: string, data?: Record<string, unknown>): Promise<UserActionResponse>;
 /**
  * Cancel / reject a user action
  */
-declare function cancelUserAction(config: ChatConfig, userActionId: string): Promise<UserActionResponse>;
+declare function cancelUserAction(config: BaseChatConfig, userActionId: string): Promise<UserActionResponse>;
 /**
  * Resend a user action (e.g. request a new OTP)
  */
-declare function resendUserAction(config: ChatConfig, userActionId: string): Promise<UserActionResponse>;
+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;
 
-export { type APIConfig, type ChatCallbacks, type ChatConfig, type ChunkDisplay, type MessageDisplay, type MessageRole, type SessionParams, type StreamEvent, type StreamOptions, type StreamProgress, type StreamingStep, type UseChatReturn, 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, cancelUserAction, createInitialV2State, generateId, processStreamEventV2, resendUserAction, streamWorkflowEvents, submitUserAction, useChat, useChatV2, useVoice, workingPhaseDetailForDisplay };
+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 };