@paymanai/payman-typescript-ask-sdk 4.0.27 → 4.0.28

package/dist/index.d.mts

@@ -241,6 +241,115 @@ type APIConfig = {
     /** API endpoint for resolving RAG image URLs (default derived from stream endpoint) */
     resolveImagesEndpoint?: string;
 };
+/** One row in the sessions list. */
+type ChatSessionSummary = {
+    sessionId: string;
+    title?: string | null;
+    messageCount?: number;
+    lastMessageAt?: string;
+    status?: string;
+};
+/** One turn's worth of raw history, as returned by the messages endpoint. */
+type ChatSessionMessageEntry = {
+    id: string;
+    sessionUserIntent: string;
+    agentResponse?: string | null;
+    status?: string;
+    startTime?: string;
+    endTime?: string;
+    /** Persisted end-user thumbs-up/down; hydrates the feedback buttons on resume. */
+    feedback?: {
+        feedback?: string | null;
+        details?: string | null;
+    } | null;
+};
+/** Overflow-menu ("...") action rendered on a session row by consuming UIs. */
+type ChatSessionAction = {
+    key: string;
+    label: string;
+    destructive?: boolean;
+    onSelect: (session: ChatSessionSummary) => void | Promise<void>;
+};
+type ChatSessionsConfig = {
+    /** Turn on session listing / history loading. Default: false. */
+    enabled?: boolean;
+    /**
+     * Path appended to `api.baseUrl` that returns a page of the current
+     * user's sessions. Reuses `api.headers` / `api.authToken` — the same
+     * credential already configured for streaming, whether that's a JWT
+     * bearer token or a custom API-key header. No separate auth config.
+     * Default: "/api/conversations/sessions".
+     */
+    listEndpoint?: string;
+    /**
+     * Path template for a single session's messages. The literal token
+     * `{sessionId}` is replaced with the selected session's id.
+     * Default: "/api/conversations/sessions/{sessionId}/messages".
+     */
+    messagesEndpoint?: string;
+    /**
+     * Sessions fetched per page. `useChatSessions` sends `page` + `limit`
+     * query params and appends each page via `loadMore`. Default: 20.
+     */
+    pageSize?: number;
+    /**
+     * Messages fetched for a selected session (sent as `limit`). Loaded in
+     * one request; the backend caps this at 100. Default: 100.
+     */
+    messagesPageSize?: number;
+    /** Sidebar header title (UI-facing; a plain string, not markup). Default: "Chats". */
+    title?: string;
+    /** Label for the create-new-session control. Default: "Start New Chat". */
+    newChatLabel?: string;
+    /** Whether a host UI's sessions panel starts open. Default: true. */
+    defaultOpen?: boolean;
+    /**
+     * Parse the list endpoint's JSON body into session rows. Defaults to
+     * reading `{ data: ChatSessionSummary[] }`, matching every
+     * PageResponse-shaped endpoint in this workspace.
+     */
+    parseSessionsResponse?: (json: unknown) => {
+        data: ChatSessionSummary[];
+        total?: number;
+    };
+    /**
+     * Parse the messages endpoint's JSON body into raw entries. Defaults
+     * to reading `{ data: ChatSessionMessageEntry[] }`.
+     */
+    parseMessagesResponse?: (json: unknown) => {
+        data: ChatSessionMessageEntry[];
+    };
+    /** Per-session overflow-menu actions (e.g. rename, delete). Omit to hide the "..." menu in host UIs that render one. */
+    actions?: ChatSessionAction[];
+};
+/**
+ * Why an agent is (un)available. "blocked" = this agent-user is blocked;
+ * "disabled" = the agent itself is off; "unknown" = loading or unreported.
+ * A machine code, not display text — the consumer owns the wording.
+ */
+type AgentAvailabilityStatus = "available" | "disabled" | "blocked" | "unknown";
+/** Config for `useAgentConfig` — the GET /api/agent/config probe. */
+type AgentConfigProbeConfig = {
+    /** Turn on the availability probe. Default: false. */
+    enabled?: boolean;
+    /**
+     * Path appended to `api.baseUrl` returning the agent's `AgentConfigResponse`
+     * (`{ enabled, blocked, ... }` — `blocked` is only populated when the host's
+     * proxy passes `sessionOwnerId` upstream). Reuses `api.headers` /
+     * `api.authToken`. Default: "/api/agent/config".
+     */
+    endpoint?: string;
+    /**
+     * Parse the response into `{ available, status, config }`. Defaults to
+     * reading `{ enabled, blocked }` and deriving `available`/`status` from
+     * them, passing the whole body through as `config`.
+     */
+    parseResponse?: (json: unknown) => {
+        available: boolean;
+        status?: AgentAvailabilityStatus;
+        config?: unknown;
+    };
+};
 type ChatConfig = {
     /** API configuration - required for the library to make calls */
     api: APIConfig;
@@ -314,6 +423,12 @@ type ChatConfig = {
     initialMessages?: MessageDisplay[];
     /** Resume an existing session by providing its ID */
     initialSessionId?: string;
+    /**
+     * Session listing / history loading (list of past sessions + a
+     * selected session's messages). See `useChatSessions` — UI packages
+     * (e.g. `@paymanai/payman-ask-sdk`) build a picker on top of it.
+     */
+    sessions?: ChatSessionsConfig;
 };
 type ChatCallbacks = {
     /** Called when a message is sent (before API call) */
@@ -457,6 +572,84 @@ declare global {
 }
 declare function useVoice(config?: VoiceConfig, callbacks?: VoiceCallbacks): UseVoiceReturn;
 
+type UseChatSessionsOptions = {
+    api: APIConfig;
+    sessions?: ChatSessionsConfig;
+    /** Seed the active session from the host's own config on first mount. */
+    initialSessionId?: string;
+};
+type UseChatSessionsReturn = {
+    enabled: boolean;
+    sessionsList: ChatSessionSummary[];
+    isLoadingList: boolean;
+    listError: string | null;
+    /** Total sessions available server-side, or null if the endpoint omits it. */
+    total: number | null;
+    /** Whether another page can be loaded via `loadMore`. */
+    hasMore: boolean;
+    /** True while a `loadMore` page (page > 0) is in flight. */
+    isLoadingMore: boolean;
+    /** Fetch and append the next page of sessions. No-op when already loading or `!hasMore`. */
+    loadMore: () => void;
+    /**
+     * Optimistically reflect a just-sent message in the list: moves the active
+     * session to the top (bumping its count/timestamp) or prepends a new row.
+     * The next `refetch` reconciles with the server.
+     */
+    noteSentMessage: (text: string) => void;
+    selectedSessionId: string | null;
+    /** The session id the chat should currently be bound to — either the selected history entry or the live draft. */
+    activeSessionId: string;
+    selectSession: (sessionId: string) => void;
+    startNewSession: () => void;
+    selectedMessages: MessageDisplay[];
+    isLoadingMessages: boolean;
+    messagesError: string | null;
+    refetch: () => void;
+};
+/**
+ * Lists the caller's sessions (paginated — call `loadMore` for older
+ * entries) and, once one is picked, its message history. Reuses whatever
+ * `api.headers` / `api.authToken` the host already configured for
+ * streaming — the same credential, JWT or API key, works here too, so
+ * there's nothing extra to authenticate.
+ */
+declare function useChatSessions({ api, sessions, initialSessionId, }: UseChatSessionsOptions): UseChatSessionsReturn;
+
+type UseAgentConfigOptions = {
+    api: APIConfig;
+    availability?: AgentConfigProbeConfig;
+};
+type UseAgentConfigReturn = {
+    /** Whether the probe is turned on. */
+    enabled: boolean;
+    /**
+     * The agent's availability, or `null` while unknown (loading, not yet
+     * fetched, or the probe failed). Callers should only hard-disable on an
+     * explicit `false` — never on `null` — so a flaky probe can't lock a
+     * working agent out.
+     */
+    available: boolean | null;
+    /**
+     * Machine-readable reason: "blocked" (this agent-user) vs "disabled" (the
+     * agent itself), so callers can show state-specific copy. "unknown" while
+     * loading or when the endpoint omits a status. Never a human string —
+     * consumers own the wording.
+     */
+    status: AgentAvailabilityStatus;
+    /** The raw parsed response body (the AgentConfigResponse shape), for hosts that need more than `available`/`status`. */
+    config: unknown;
+    isLoading: boolean;
+    error: string | null;
+    refetch: () => void;
+};
+/**
+ * Probes GET `/api/agent/config` and returns the agent's availability.
+ * Reuses whatever `api.headers` / `api.authToken` the host already
+ * configured for streaming — same credential, JWT or API key.
+ */
+declare function useAgentConfig({ api, availability }: UseAgentConfigOptions): UseAgentConfigReturn;
+
 /**
  * Cross-platform UUID v4 generator
  * Works in both browser and React Native environments
@@ -667,4 +860,4 @@ declare function isUserActionExpired(prompt: ActiveUserAction): boolean;
 
 declare function migrateActiveStream(oldUserId: string, newUserId: string): void;
 
-export { type APIConfig, type ActiveUserAction, type AgentStage, type AnalysisMode, type ChatCallbacks, type ChatConfig, type ChunkDisplay, type FieldWidget, type JsonSchemaField, type JsonSchemaOption, type MessageDisplay, type MessageFeedbackState, type MessageRole, type RequestedSchema, type SendMessageOptions, type SessionParams, type StreamEvent, type StreamOptions, type StreamProgress, type StreamingStep, type UseChatV2Return, type UseVoiceReturn, type UserActionKind, type UserActionRequest, UserActionStaleError, type UserActionState, type UserActionStatus, type UserActionSubAction, type UserNotification, type V2EventProcessorState, type VerificationType, type VoiceCallbacks, type VoiceConfig, type VoicePermissions, type VoiceResult, type VoiceState, buildContent, cancelUserAction, classifyField, classifyUserActionKind, coerceValue, createInitialV2State, defaultValueFor, expireUserAction, generateId, getOptions, getUserActionSecondsLeft, isNestedOrUnsupported, isRequired, isUserActionExpired, migrateActiveStream, processStreamEventV2, renderableFields, resendUserAction, resolveUserActionExpiresAt, streamWorkflowEvents, submitUserAction, useChatV2, useVoice, validateField, validateForm };
+export { type APIConfig, type ActiveUserAction, type AgentAvailabilityStatus, type AgentConfigProbeConfig, type AgentStage, type AnalysisMode, type ChatCallbacks, type ChatConfig, type ChatSessionAction, type ChatSessionMessageEntry, type ChatSessionSummary, type ChatSessionsConfig, type ChunkDisplay, type FieldWidget, type JsonSchemaField, type JsonSchemaOption, type MessageDisplay, type MessageFeedbackState, type MessageRole, type RequestedSchema, type SendMessageOptions, type SessionParams, type StreamEvent, type StreamOptions, type StreamProgress, type StreamingStep, type UseAgentConfigOptions, type UseAgentConfigReturn, type UseChatSessionsOptions, type UseChatSessionsReturn, type UseChatV2Return, type UseVoiceReturn, type UserActionKind, type UserActionRequest, UserActionStaleError, type UserActionState, type UserActionStatus, type UserActionSubAction, type UserNotification, type V2EventProcessorState, type VerificationType, type VoiceCallbacks, type VoiceConfig, type VoicePermissions, type VoiceResult, type VoiceState, buildContent, cancelUserAction, classifyField, classifyUserActionKind, coerceValue, createInitialV2State, defaultValueFor, expireUserAction, generateId, getOptions, getUserActionSecondsLeft, isNestedOrUnsupported, isRequired, isUserActionExpired, migrateActiveStream, processStreamEventV2, renderableFields, resendUserAction, resolveUserActionExpiresAt, streamWorkflowEvents, submitUserAction, useAgentConfig, useChatSessions, useChatV2, useVoice, validateField, validateForm };

package/dist/index.d.ts

@@ -241,6 +241,115 @@ type APIConfig = {
     /** API endpoint for resolving RAG image URLs (default derived from stream endpoint) */
     resolveImagesEndpoint?: string;
 };
+/** One row in the sessions list. */
+type ChatSessionSummary = {
+    sessionId: string;
+    title?: string | null;
+    messageCount?: number;
+    lastMessageAt?: string;
+    status?: string;
+};
+/** One turn's worth of raw history, as returned by the messages endpoint. */
+type ChatSessionMessageEntry = {
+    id: string;
+    sessionUserIntent: string;
+    agentResponse?: string | null;
+    status?: string;
+    startTime?: string;
+    endTime?: string;
+    /** Persisted end-user thumbs-up/down; hydrates the feedback buttons on resume. */
+    feedback?: {
+        feedback?: string | null;
+        details?: string | null;
+    } | null;
+};
+/** Overflow-menu ("...") action rendered on a session row by consuming UIs. */
+type ChatSessionAction = {
+    key: string;
+    label: string;
+    destructive?: boolean;
+    onSelect: (session: ChatSessionSummary) => void | Promise<void>;
+};
+type ChatSessionsConfig = {
+    /** Turn on session listing / history loading. Default: false. */
+    enabled?: boolean;
+    /**
+     * Path appended to `api.baseUrl` that returns a page of the current
+     * user's sessions. Reuses `api.headers` / `api.authToken` — the same
+     * credential already configured for streaming, whether that's a JWT
+     * bearer token or a custom API-key header. No separate auth config.
+     * Default: "/api/conversations/sessions".
+     */
+    listEndpoint?: string;
+    /**
+     * Path template for a single session's messages. The literal token
+     * `{sessionId}` is replaced with the selected session's id.
+     * Default: "/api/conversations/sessions/{sessionId}/messages".
+     */
+    messagesEndpoint?: string;
+    /**
+     * Sessions fetched per page. `useChatSessions` sends `page` + `limit`
+     * query params and appends each page via `loadMore`. Default: 20.
+     */
+    pageSize?: number;
+    /**
+     * Messages fetched for a selected session (sent as `limit`). Loaded in
+     * one request; the backend caps this at 100. Default: 100.
+     */
+    messagesPageSize?: number;
+    /** Sidebar header title (UI-facing; a plain string, not markup). Default: "Chats". */
+    title?: string;
+    /** Label for the create-new-session control. Default: "Start New Chat". */
+    newChatLabel?: string;
+    /** Whether a host UI's sessions panel starts open. Default: true. */
+    defaultOpen?: boolean;
+    /**
+     * Parse the list endpoint's JSON body into session rows. Defaults to
+     * reading `{ data: ChatSessionSummary[] }`, matching every
+     * PageResponse-shaped endpoint in this workspace.
+     */
+    parseSessionsResponse?: (json: unknown) => {
+        data: ChatSessionSummary[];
+        total?: number;
+    };
+    /**
+     * Parse the messages endpoint's JSON body into raw entries. Defaults
+     * to reading `{ data: ChatSessionMessageEntry[] }`.
+     */
+    parseMessagesResponse?: (json: unknown) => {
+        data: ChatSessionMessageEntry[];
+    };
+    /** Per-session overflow-menu actions (e.g. rename, delete). Omit to hide the "..." menu in host UIs that render one. */
+    actions?: ChatSessionAction[];
+};
+/**
+ * Why an agent is (un)available. "blocked" = this agent-user is blocked;
+ * "disabled" = the agent itself is off; "unknown" = loading or unreported.
+ * A machine code, not display text — the consumer owns the wording.
+ */
+type AgentAvailabilityStatus = "available" | "disabled" | "blocked" | "unknown";
+/** Config for `useAgentConfig` — the GET /api/agent/config probe. */
+type AgentConfigProbeConfig = {
+    /** Turn on the availability probe. Default: false. */
+    enabled?: boolean;
+    /**
+     * Path appended to `api.baseUrl` returning the agent's `AgentConfigResponse`
+     * (`{ enabled, blocked, ... }` — `blocked` is only populated when the host's
+     * proxy passes `sessionOwnerId` upstream). Reuses `api.headers` /
+     * `api.authToken`. Default: "/api/agent/config".
+     */
+    endpoint?: string;
+    /**
+     * Parse the response into `{ available, status, config }`. Defaults to
+     * reading `{ enabled, blocked }` and deriving `available`/`status` from
+     * them, passing the whole body through as `config`.
+     */
+    parseResponse?: (json: unknown) => {
+        available: boolean;
+        status?: AgentAvailabilityStatus;
+        config?: unknown;
+    };
+};
 type ChatConfig = {
     /** API configuration - required for the library to make calls */
     api: APIConfig;
@@ -314,6 +423,12 @@ type ChatConfig = {
     initialMessages?: MessageDisplay[];
     /** Resume an existing session by providing its ID */
     initialSessionId?: string;
+    /**
+     * Session listing / history loading (list of past sessions + a
+     * selected session's messages). See `useChatSessions` — UI packages
+     * (e.g. `@paymanai/payman-ask-sdk`) build a picker on top of it.
+     */
+    sessions?: ChatSessionsConfig;
 };
 type ChatCallbacks = {
     /** Called when a message is sent (before API call) */
@@ -457,6 +572,84 @@ declare global {
 }
 declare function useVoice(config?: VoiceConfig, callbacks?: VoiceCallbacks): UseVoiceReturn;
 
+type UseChatSessionsOptions = {
+    api: APIConfig;
+    sessions?: ChatSessionsConfig;
+    /** Seed the active session from the host's own config on first mount. */
+    initialSessionId?: string;
+};
+type UseChatSessionsReturn = {
+    enabled: boolean;
+    sessionsList: ChatSessionSummary[];
+    isLoadingList: boolean;
+    listError: string | null;
+    /** Total sessions available server-side, or null if the endpoint omits it. */
+    total: number | null;
+    /** Whether another page can be loaded via `loadMore`. */
+    hasMore: boolean;
+    /** True while a `loadMore` page (page > 0) is in flight. */
+    isLoadingMore: boolean;
+    /** Fetch and append the next page of sessions. No-op when already loading or `!hasMore`. */
+    loadMore: () => void;
+    /**
+     * Optimistically reflect a just-sent message in the list: moves the active
+     * session to the top (bumping its count/timestamp) or prepends a new row.
+     * The next `refetch` reconciles with the server.
+     */
+    noteSentMessage: (text: string) => void;
+    selectedSessionId: string | null;
+    /** The session id the chat should currently be bound to — either the selected history entry or the live draft. */
+    activeSessionId: string;
+    selectSession: (sessionId: string) => void;
+    startNewSession: () => void;
+    selectedMessages: MessageDisplay[];
+    isLoadingMessages: boolean;
+    messagesError: string | null;
+    refetch: () => void;
+};
+/**
+ * Lists the caller's sessions (paginated — call `loadMore` for older
+ * entries) and, once one is picked, its message history. Reuses whatever
+ * `api.headers` / `api.authToken` the host already configured for
+ * streaming — the same credential, JWT or API key, works here too, so
+ * there's nothing extra to authenticate.
+ */
+declare function useChatSessions({ api, sessions, initialSessionId, }: UseChatSessionsOptions): UseChatSessionsReturn;
+
+type UseAgentConfigOptions = {
+    api: APIConfig;
+    availability?: AgentConfigProbeConfig;
+};
+type UseAgentConfigReturn = {
+    /** Whether the probe is turned on. */
+    enabled: boolean;
+    /**
+     * The agent's availability, or `null` while unknown (loading, not yet
+     * fetched, or the probe failed). Callers should only hard-disable on an
+     * explicit `false` — never on `null` — so a flaky probe can't lock a
+     * working agent out.
+     */
+    available: boolean | null;
+    /**
+     * Machine-readable reason: "blocked" (this agent-user) vs "disabled" (the
+     * agent itself), so callers can show state-specific copy. "unknown" while
+     * loading or when the endpoint omits a status. Never a human string —
+     * consumers own the wording.
+     */
+    status: AgentAvailabilityStatus;
+    /** The raw parsed response body (the AgentConfigResponse shape), for hosts that need more than `available`/`status`. */
+    config: unknown;
+    isLoading: boolean;
+    error: string | null;
+    refetch: () => void;
+};
+/**
+ * Probes GET `/api/agent/config` and returns the agent's availability.
+ * Reuses whatever `api.headers` / `api.authToken` the host already
+ * configured for streaming — same credential, JWT or API key.
+ */
+declare function useAgentConfig({ api, availability }: UseAgentConfigOptions): UseAgentConfigReturn;
+
 /**
  * Cross-platform UUID v4 generator
  * Works in both browser and React Native environments
@@ -667,4 +860,4 @@ declare function isUserActionExpired(prompt: ActiveUserAction): boolean;
 
 declare function migrateActiveStream(oldUserId: string, newUserId: string): void;
 
-export { type APIConfig, type ActiveUserAction, type AgentStage, type AnalysisMode, type ChatCallbacks, type ChatConfig, type ChunkDisplay, type FieldWidget, type JsonSchemaField, type JsonSchemaOption, type MessageDisplay, type MessageFeedbackState, type MessageRole, type RequestedSchema, type SendMessageOptions, type SessionParams, type StreamEvent, type StreamOptions, type StreamProgress, type StreamingStep, type UseChatV2Return, type UseVoiceReturn, type UserActionKind, type UserActionRequest, UserActionStaleError, type UserActionState, type UserActionStatus, type UserActionSubAction, type UserNotification, type V2EventProcessorState, type VerificationType, type VoiceCallbacks, type VoiceConfig, type VoicePermissions, type VoiceResult, type VoiceState, buildContent, cancelUserAction, classifyField, classifyUserActionKind, coerceValue, createInitialV2State, defaultValueFor, expireUserAction, generateId, getOptions, getUserActionSecondsLeft, isNestedOrUnsupported, isRequired, isUserActionExpired, migrateActiveStream, processStreamEventV2, renderableFields, resendUserAction, resolveUserActionExpiresAt, streamWorkflowEvents, submitUserAction, useChatV2, useVoice, validateField, validateForm };
+export { type APIConfig, type ActiveUserAction, type AgentAvailabilityStatus, type AgentConfigProbeConfig, type AgentStage, type AnalysisMode, type ChatCallbacks, type ChatConfig, type ChatSessionAction, type ChatSessionMessageEntry, type ChatSessionSummary, type ChatSessionsConfig, type ChunkDisplay, type FieldWidget, type JsonSchemaField, type JsonSchemaOption, type MessageDisplay, type MessageFeedbackState, type MessageRole, type RequestedSchema, type SendMessageOptions, type SessionParams, type StreamEvent, type StreamOptions, type StreamProgress, type StreamingStep, type UseAgentConfigOptions, type UseAgentConfigReturn, type UseChatSessionsOptions, type UseChatSessionsReturn, type UseChatV2Return, type UseVoiceReturn, type UserActionKind, type UserActionRequest, UserActionStaleError, type UserActionState, type UserActionStatus, type UserActionSubAction, type UserNotification, type V2EventProcessorState, type VerificationType, type VoiceCallbacks, type VoiceConfig, type VoicePermissions, type VoiceResult, type VoiceState, buildContent, cancelUserAction, classifyField, classifyUserActionKind, coerceValue, createInitialV2State, defaultValueFor, expireUserAction, generateId, getOptions, getUserActionSecondsLeft, isNestedOrUnsupported, isRequired, isUserActionExpired, migrateActiveStream, processStreamEventV2, renderableFields, resendUserAction, resolveUserActionExpiresAt, streamWorkflowEvents, submitUserAction, useAgentConfig, useChatSessions, useChatV2, useVoice, validateField, validateForm };