@paymanai/payman-ask-sdk 4.0.27 → 4.0.28

package/README.md

@@ -230,6 +230,46 @@ function MyShell() {
 }
 ```
 
+> The example above (`SessionHistorySidebar`, `ui.sessionHistory`, `chat.loadSession()`) documents a config shape that isn't implemented in this package yet. For the sidebar that actually ships today, see **Sessions sidebar** below.
+
+## Sessions sidebar
+
+Set `config.sessions.enabled = true` and `<PaymanChat/>` renders a "continue a chat" sidebar next to the conversation — fetching the list, loading a picked session's messages, and remounting the chat onto it are all handled internally. No extra state, endpoints, or loading/error UI to build in the host app.
+
+```tsx
+<PaymanChat
+  config={{
+    api: { baseUrl, authToken, headers }, // same credential already used for streaming — JWT or API key, doesn't matter
+    agentId,
+    sessionParams,
+    sessions: {
+      enabled: true,
+      // Both default to these paths if omitted:
+      listEndpoint: "/api/ask/sessions",
+      messagesEndpoint: "/api/ask/sessions/{sessionId}/messages",
+      title: "Chats",
+      newChatLabel: "Start New Chat",
+      defaultOpen: true,
+      // Optional per-row "..." menu. Omit `actions` entirely to hide it.
+      actions: [
+        {
+          key: "delete",
+          label: "Delete",
+          destructive: true,
+          onSelect: async (session) => { /* ... */ },
+        },
+      ],
+    },
+  }}
+/>
+```
+
+`listEndpoint` is appended to `api.baseUrl` and expected to return `{ data: ChatSessionSummary[] }` (`sessionId`, `title?`, `messageCount?`, `lastMessageAt?`, `status?`). `messagesEndpoint` (with `{sessionId}` substituted) is expected to return `{ data: ChatSessionMessageEntry[] }` (`id`, `sessionUserIntent`, `agentResponse?`, `status?`, `startTime?`, `endTime?`) — the same `PageResponse<AgentUser...Response>` shape K2's `/conversations/sessions` endpoint already returns. If your backend's JSON looks different, pass `parseSessionsResponse` / `parseMessagesResponse` to adapt it.
+
+Auth is whatever you already pass in `api.headers` / `api.authToken` for streaming — there's no separate sessions-specific credential. `ref.refreshSessions()` force-refetches the list (e.g. after an out-of-band mutation); `onStreamComplete` triggers an automatic refetch after every turn.
+
+Styling: see [`docs/v2-styling-reference.md`](docs/v2-styling-reference.md#sessions-sidebar) for the full `payman-v2-sessions-*` class list and CSS vars.
+
 ## `usePaymanChat()` hook
 
 Call from any descendant of `<PaymanChat/>`:

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import React__default from 'react';
-import { MessageDisplay, AgentStage, ChatCallbacks as ChatCallbacks$1, ChatConfig as ChatConfig$1, ActiveUserAction, UserNotification } from '@paymanai/payman-typescript-ask-sdk';
-export { APIConfig, ActiveUserAction, AgentStage, ChunkDisplay, JsonSchemaField, JsonSchemaOption, MessageDisplay, MessageRole, RequestedSchema, SessionParams, StreamProgress, StreamingStep, UseChatV2Return, UseVoiceReturn, UserActionKind, UserActionRequest, UserActionStaleError, UserActionState, UserActionStatus, UserActionSubAction, UserNotification, VerificationType, VoiceCallbacks, VoiceConfig, VoicePermissions, VoiceResult, VoiceState, cancelUserAction, resendUserAction, submitUserAction, useChatV2, useVoice } from '@paymanai/payman-typescript-ask-sdk';
+import { MessageDisplay, AgentStage, ChatCallbacks as ChatCallbacks$1, ChatConfig as ChatConfig$1, AgentConfigProbeConfig, ActiveUserAction, UserNotification } from '@paymanai/payman-typescript-ask-sdk';
+export { APIConfig, ActiveUserAction, AgentAvailabilityStatus, AgentConfigProbeConfig, AgentStage, ChatSessionAction, ChatSessionMessageEntry, ChatSessionSummary, ChatSessionsConfig, ChunkDisplay, JsonSchemaField, JsonSchemaOption, MessageDisplay, MessageRole, RequestedSchema, SessionParams, StreamProgress, StreamingStep, UseAgentConfigOptions, UseAgentConfigReturn, UseChatV2Return, UseVoiceReturn, UserActionKind, UserActionRequest, UserActionStaleError, UserActionState, UserActionStatus, UserActionSubAction, UserNotification, VerificationType, VoiceCallbacks, VoiceConfig, VoicePermissions, VoiceResult, VoiceState, cancelUserAction, resendUserAction, submitUserAction, useAgentConfig, useChatV2, useVoice } from '@paymanai/payman-typescript-ask-sdk';
 import { ClassValue } from 'clsx';
 
 declare const NEGATIVE_FEEDBACK_REASONS: readonly [{
@@ -74,6 +74,20 @@ type SlashCommandConfig = {
     requiredAnyPermissions?: string[];
 };
 type ChatConfig = ChatConfig$1 & {
+    /**
+     * Availability probe. When `availability.enabled` is set, PaymanChat calls
+     * GET `/api/agent/config` itself and takes over the chat with a friendly,
+     * built-in notice whenever the agent is off or the agent-user is blocked —
+     * so hosts don't have to wire the check by hand. Provide `disabledComponent`
+     * / `blockedComponent` to render your own UI per state. See
+     * `AgentConfigProbeConfig` in @paymanai/payman-typescript-ask-sdk.
+     */
+    availability?: AgentConfigProbeConfig & {
+        /** Custom body shown when the agent itself is disabled. Defaults to a built-in notice. */
+        disabledComponent?: React__default.ReactNode;
+        /** Custom body shown when this agent-user is blocked. Defaults to a built-in notice. */
+        blockedComponent?: React__default.ReactNode;
+    };
     /** Custom React component to render above the empty state text (e.g. logo, illustration). */
     emptyStateComponent?: React__default.ReactNode;
     /** Enable voice input (default: true) */
@@ -198,6 +212,8 @@ type PaymanChatRef = {
     getSessionId: () => string | undefined;
     /** Get all messages */
     getMessages: () => MessageDisplay[];
+    /** Re-fetch the sessions sidebar list (no-op when `config.sessions.enabled` is not set) */
+    refreshSessions: () => void;
 };
 type PaymanChatProps = {
     /** Chat configuration - includes API config */
@@ -480,14 +496,6 @@ type ChatHeaderProps = {
     className?: string;
 };
 
-/**
- * PaymanChat — the public component. Delegates to `PaymanChatInner`
- * with a chat hook instance from `useChatV2`. The `config.uiVersion`
- * prop used to gate an older V1 render path; the V1 code has been
- * removed since nothing in the SDK's current consumers (paygent-studio
- * etc.) opted into it. The `uiVersion` prop is still accepted on
- * `ChatConfig` for type compatibility but is now ignored at runtime.
- */
 declare const PaymanChat: React.ForwardRefExoticComponent<PaymanChatProps & React.RefAttributes<PaymanChatRef>>;
 
 interface PaymanChatContextValue {

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import React__default from 'react';
-import { MessageDisplay, AgentStage, ChatCallbacks as ChatCallbacks$1, ChatConfig as ChatConfig$1, ActiveUserAction, UserNotification } from '@paymanai/payman-typescript-ask-sdk';
-export { APIConfig, ActiveUserAction, AgentStage, ChunkDisplay, JsonSchemaField, JsonSchemaOption, MessageDisplay, MessageRole, RequestedSchema, SessionParams, StreamProgress, StreamingStep, UseChatV2Return, UseVoiceReturn, UserActionKind, UserActionRequest, UserActionStaleError, UserActionState, UserActionStatus, UserActionSubAction, UserNotification, VerificationType, VoiceCallbacks, VoiceConfig, VoicePermissions, VoiceResult, VoiceState, cancelUserAction, resendUserAction, submitUserAction, useChatV2, useVoice } from '@paymanai/payman-typescript-ask-sdk';
+import { MessageDisplay, AgentStage, ChatCallbacks as ChatCallbacks$1, ChatConfig as ChatConfig$1, AgentConfigProbeConfig, ActiveUserAction, UserNotification } from '@paymanai/payman-typescript-ask-sdk';
+export { APIConfig, ActiveUserAction, AgentAvailabilityStatus, AgentConfigProbeConfig, AgentStage, ChatSessionAction, ChatSessionMessageEntry, ChatSessionSummary, ChatSessionsConfig, ChunkDisplay, JsonSchemaField, JsonSchemaOption, MessageDisplay, MessageRole, RequestedSchema, SessionParams, StreamProgress, StreamingStep, UseAgentConfigOptions, UseAgentConfigReturn, UseChatV2Return, UseVoiceReturn, UserActionKind, UserActionRequest, UserActionStaleError, UserActionState, UserActionStatus, UserActionSubAction, UserNotification, VerificationType, VoiceCallbacks, VoiceConfig, VoicePermissions, VoiceResult, VoiceState, cancelUserAction, resendUserAction, submitUserAction, useAgentConfig, useChatV2, useVoice } from '@paymanai/payman-typescript-ask-sdk';
 import { ClassValue } from 'clsx';
 
 declare const NEGATIVE_FEEDBACK_REASONS: readonly [{
@@ -74,6 +74,20 @@ type SlashCommandConfig = {
     requiredAnyPermissions?: string[];
 };
 type ChatConfig = ChatConfig$1 & {
+    /**
+     * Availability probe. When `availability.enabled` is set, PaymanChat calls
+     * GET `/api/agent/config` itself and takes over the chat with a friendly,
+     * built-in notice whenever the agent is off or the agent-user is blocked —
+     * so hosts don't have to wire the check by hand. Provide `disabledComponent`
+     * / `blockedComponent` to render your own UI per state. See
+     * `AgentConfigProbeConfig` in @paymanai/payman-typescript-ask-sdk.
+     */
+    availability?: AgentConfigProbeConfig & {
+        /** Custom body shown when the agent itself is disabled. Defaults to a built-in notice. */
+        disabledComponent?: React__default.ReactNode;
+        /** Custom body shown when this agent-user is blocked. Defaults to a built-in notice. */
+        blockedComponent?: React__default.ReactNode;
+    };
     /** Custom React component to render above the empty state text (e.g. logo, illustration). */
     emptyStateComponent?: React__default.ReactNode;
     /** Enable voice input (default: true) */
@@ -198,6 +212,8 @@ type PaymanChatRef = {
     getSessionId: () => string | undefined;
     /** Get all messages */
     getMessages: () => MessageDisplay[];
+    /** Re-fetch the sessions sidebar list (no-op when `config.sessions.enabled` is not set) */
+    refreshSessions: () => void;
 };
 type PaymanChatProps = {
     /** Chat configuration - includes API config */
@@ -480,14 +496,6 @@ type ChatHeaderProps = {
     className?: string;
 };
 
-/**
- * PaymanChat — the public component. Delegates to `PaymanChatInner`
- * with a chat hook instance from `useChatV2`. The `config.uiVersion`
- * prop used to gate an older V1 render path; the V1 code has been
- * removed since nothing in the SDK's current consumers (paygent-studio
- * etc.) opted into it. The `uiVersion` prop is still accepted on
- * `ChatConfig` for type compatibility but is now ignored at runtime.
- */
 declare const PaymanChat: React.ForwardRefExoticComponent<PaymanChatProps & React.RefAttributes<PaymanChatRef>>;
 
 interface PaymanChatContextValue {