@paymanai/payman-ask-sdk 4.0.0 → 4.0.2

package/README.md

@@ -167,7 +167,7 @@ Turn features on with booleans, and only reach for the full object form when you
 
 Use `ui.emptyState.suggestions` when an app wants SDK-rendered prompt shortcuts on the first screen. Apps own the content; the SDK owns rendering, accessibility, click handling, responsive layout, and styling.
 
-The SDK renders categories as compact bubbles first. Clicking a category reveals that category's prompts below it; clicking a prompt sends the prompt text verbatim. On narrow screens and React Native, categories become a horizontal touch scroller so the empty state stays compact.
+The SDK renders categories as compact bubbles first. Clicking a category reveals that category's prompts below it; clicking a prompt sends the prompt text verbatim. On narrow screens, categories become a horizontal touch scroller so the empty state stays compact.
 
 ```tsx
 const isProd = process.env.NEXT_PUBLIC_ENV === "production";
@@ -203,7 +203,7 @@ const suggestions = {
 
 `icon` is optional. When omitted, the SDK chooses a small built-in glyph from the category label for common labels like payments, accounts, insights, and products.
 
-Suggested prompts use the same `--payman-v2-*` CSS variables as the rest of the chat surface, so app-level theme overrides automatically apply to bubble background, text, border, hover, radius, and focus states. The React Native renderer uses native `Pressable` and `ScrollView` controls with the same category-first behavior.
+Suggested prompts use the same `--payman-v2-*` CSS variables as the rest of the chat surface, so app-level theme overrides automatically apply to bubble background, text, border, hover, radius, and focus states.
 
 ## Session history
 
@@ -309,10 +309,6 @@ type ChatCallbacks = {
 - `listSessions` / `listConversations` REST helpers (from the core SDK).
 - `buildScopeKey(config)` — compose the client-side state-scope key from `session.userId + workflow.id + workflow.version + workflow.stage`.
 
-## React Native
-
-v2 ships web-only for the moment. `PaymanChat` on React Native renders a placeholder — pin `@paymanai/payman-ask-sdk@^1` if you need the v1 native renderer while the v2 RN rewrite lands.
-
 ## License
 
 MIT

package/dist/index.d.mts

@@ -26,6 +26,16 @@ type MessageActionsConfig = {
     userMessageActions?: UserMessageActionsConfig;
     assistantMessageActions?: AssistantMessageActionsConfig;
 };
+type SlashCommandConfig = {
+    /** Slash command token, including the leading slash. Example: /draft-knowledge */
+    name: string;
+    /** One-line description shown in autocomplete. */
+    description: string;
+    /** Text inserted into the input. Defaults to `${name} `. */
+    insertText?: string;
+    /** Show only when at least one permission is present. */
+    requiredAnyPermissions?: string[];
+};
 type ChatConfig = ChatConfig$1 & {
     /** Custom React component to render above the empty state text (e.g. logo, illustration). */
     emptyStateComponent?: React__default.ReactNode;
@@ -47,6 +57,12 @@ type ChatConfig = ChatConfig$1 & {
     showAttachFileButton?: boolean;
     /** Configure which per-message actions are visible in the v2 UI */
     messageActions?: MessageActionsConfig;
+    /** Enable slash command autocomplete in the chat input. Default: true. */
+    enableSlashCommands?: boolean;
+    /** Optional command list. Defaults to Knowledge Vault's /draft-knowledge command. */
+    slashCommands?: SlashCommandConfig[];
+    /** Current caller permissions used to hide commands they cannot run. */
+    commandPermissions?: string[];
     /** Sentry DSN for error monitoring. */
     sentryDsn?: string;
     /**
@@ -186,8 +202,6 @@ type ChatInputProps = {
     onUploadImageClick?: () => void;
     /** Handler called when the "Attach file" option is clicked */
     onAttachFileClick?: () => void;
-    /** React Native: called when the text input is focused (e.g. to scroll messages above the keyboard). */
-    onInputFocus?: () => void;
 };
 type MessageListProps = {
     /** Messages to display */
@@ -240,10 +254,6 @@ type MessageListProps = {
     isLoadingMoreMessages?: boolean;
     /** Whether there are more messages to load */
     hasMoreMessages?: boolean;
-    /** React Native: while true, keep scrolling to the end as layout updates. */
-    isWaitingForResponse?: boolean;
-    /** React Native: ref to register a no-arg function that scrolls the message list to the end. */
-    scrollToEndHandleRef?: React__default.MutableRefObject<(() => void) | null>;
 };
 type MessageListV2Props = {
     /** Messages to display */
@@ -528,4 +538,4 @@ interface ChatSessionContext {
  */
 declare function captureSentryError(error: Error | string, context: ChatSessionContext): void;
 
-export { type AgentMessageProps, type AssistantMessageActionsConfig, type ChatCallbacks, type ChatConfig, type ChatHeaderProps, type ChatInputProps, type ChatSessionContext, type MessageActionsConfig, type MessageListProps, type MessageListV2Props, type MessageRowProps, type OtpInputProps, PaymanChat, PaymanChatContext, type PaymanChatContextValue, type PaymanChatProps, type PaymanChatRef, type StreamingMessageProps, type UserActionModalProps, type UserMessageActionsConfig, type UserMessageProps, captureSentryError, cn, formatDate, usePaymanChat };
+export { type AgentMessageProps, type AssistantMessageActionsConfig, type ChatCallbacks, type ChatConfig, type ChatHeaderProps, type ChatInputProps, type ChatSessionContext, type MessageActionsConfig, type MessageListProps, type MessageListV2Props, type MessageRowProps, type OtpInputProps, PaymanChat, PaymanChatContext, type PaymanChatContextValue, type PaymanChatProps, type PaymanChatRef, type SlashCommandConfig, type StreamingMessageProps, type UserActionModalProps, type UserMessageActionsConfig, type UserMessageProps, captureSentryError, cn, formatDate, usePaymanChat };

package/dist/index.d.ts

@@ -26,6 +26,16 @@ type MessageActionsConfig = {
     userMessageActions?: UserMessageActionsConfig;
     assistantMessageActions?: AssistantMessageActionsConfig;
 };
+type SlashCommandConfig = {
+    /** Slash command token, including the leading slash. Example: /draft-knowledge */
+    name: string;
+    /** One-line description shown in autocomplete. */
+    description: string;
+    /** Text inserted into the input. Defaults to `${name} `. */
+    insertText?: string;
+    /** Show only when at least one permission is present. */
+    requiredAnyPermissions?: string[];
+};
 type ChatConfig = ChatConfig$1 & {
     /** Custom React component to render above the empty state text (e.g. logo, illustration). */
     emptyStateComponent?: React__default.ReactNode;
@@ -47,6 +57,12 @@ type ChatConfig = ChatConfig$1 & {
     showAttachFileButton?: boolean;
     /** Configure which per-message actions are visible in the v2 UI */
     messageActions?: MessageActionsConfig;
+    /** Enable slash command autocomplete in the chat input. Default: true. */
+    enableSlashCommands?: boolean;
+    /** Optional command list. Defaults to Knowledge Vault's /draft-knowledge command. */
+    slashCommands?: SlashCommandConfig[];
+    /** Current caller permissions used to hide commands they cannot run. */
+    commandPermissions?: string[];
     /** Sentry DSN for error monitoring. */
     sentryDsn?: string;
     /**
@@ -186,8 +202,6 @@ type ChatInputProps = {
     onUploadImageClick?: () => void;
     /** Handler called when the "Attach file" option is clicked */
     onAttachFileClick?: () => void;
-    /** React Native: called when the text input is focused (e.g. to scroll messages above the keyboard). */
-    onInputFocus?: () => void;
 };
 type MessageListProps = {
     /** Messages to display */
@@ -240,10 +254,6 @@ type MessageListProps = {
     isLoadingMoreMessages?: boolean;
     /** Whether there are more messages to load */
     hasMoreMessages?: boolean;
-    /** React Native: while true, keep scrolling to the end as layout updates. */
-    isWaitingForResponse?: boolean;
-    /** React Native: ref to register a no-arg function that scrolls the message list to the end. */
-    scrollToEndHandleRef?: React__default.MutableRefObject<(() => void) | null>;
 };
 type MessageListV2Props = {
     /** Messages to display */
@@ -528,4 +538,4 @@ interface ChatSessionContext {
  */
 declare function captureSentryError(error: Error | string, context: ChatSessionContext): void;
 
-export { type AgentMessageProps, type AssistantMessageActionsConfig, type ChatCallbacks, type ChatConfig, type ChatHeaderProps, type ChatInputProps, type ChatSessionContext, type MessageActionsConfig, type MessageListProps, type MessageListV2Props, type MessageRowProps, type OtpInputProps, PaymanChat, PaymanChatContext, type PaymanChatContextValue, type PaymanChatProps, type PaymanChatRef, type StreamingMessageProps, type UserActionModalProps, type UserMessageActionsConfig, type UserMessageProps, captureSentryError, cn, formatDate, usePaymanChat };
+export { type AgentMessageProps, type AssistantMessageActionsConfig, type ChatCallbacks, type ChatConfig, type ChatHeaderProps, type ChatInputProps, type ChatSessionContext, type MessageActionsConfig, type MessageListProps, type MessageListV2Props, type MessageRowProps, type OtpInputProps, PaymanChat, PaymanChatContext, type PaymanChatContextValue, type PaymanChatProps, type PaymanChatRef, type SlashCommandConfig, type StreamingMessageProps, type UserActionModalProps, type UserMessageActionsConfig, type UserMessageProps, captureSentryError, cn, formatDate, usePaymanChat };

package/dist/index.js

@@ -149,6 +149,36 @@ function subscribeToCfRay(urlPattern, listener) {
   };
 }
 
+// src/utils/slashCommands.ts
+var DEFAULT_SLASH_COMMANDS = [
+  {
+    name: "/draft-knowledge",
+    description: "Create a Knowledge Vault draft for admin review",
+    requiredAnyPermissions: ["vault:author", "vault:publish"]
+  }
+];
+function filterSlashCommands(commands, permissions) {
+  const granted = new Set(permissions ?? []);
+  return commands.filter((command) => {
+    const required = command.requiredAnyPermissions ?? [];
+    return required.length === 0 || required.some((permission) => granted.has(permission));
+  });
+}
+function parseSlashCommand(content) {
+  const trimmedStart = content.trimStart();
+  if (!trimmedStart.startsWith("/")) return null;
+  const match = trimmedStart.match(/^(\/[a-z][a-z0-9-]*)(?:\s+([\s\S]*))?$/i);
+  if (!match) return null;
+  return {
+    command: match[1],
+    body: match[2] ?? ""
+  };
+}
+function slashCommandBodyIsEmpty(content) {
+  const parsed = parseSlashCommand(content);
+  return parsed?.command === "/draft-knowledge" && parsed.body.trim().length === 0;
+}
+
 // src/utils/errorMessages.ts
 var WORKFLOW_FAILED = "WORKFLOW_FAILED";
 var STREAM_NOT_STARTED = "STREAM_NOT_STARTED";
@@ -789,6 +819,7 @@ function UserMessage({
   animated = false,
   showAvatar = false
 }) {
+  const parsedCommand = parseSlashCommand(message.content);
   const content = /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex gap-3 justify-end w-full", children: [
     /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "max-w-[80%] min-w-0 flex flex-col items-end", children: [
       /* @__PURE__ */ jsxRuntime.jsx(
@@ -799,7 +830,10 @@ function UserMessage({
             "bg-primary text-primary-foreground",
             "shadow-sm"
           ),
-          children: /* @__PURE__ */ jsxRuntime.jsx("p", { className: "text-sm leading-relaxed whitespace-pre-wrap break-words", children: message.content })
+          children: parsedCommand ? /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "space-y-2", children: [
+            /* @__PURE__ */ jsxRuntime.jsx("span", { className: "inline-flex rounded-md bg-black/15 px-2 py-0.5 font-mono text-xs", children: parsedCommand.command }),
+            parsedCommand.body.trim() ? /* @__PURE__ */ jsxRuntime.jsx("p", { className: "text-sm leading-relaxed whitespace-pre-wrap break-words", children: parsedCommand.body }) : null
+          ] }) : /* @__PURE__ */ jsxRuntime.jsx("p", { className: "text-sm leading-relaxed whitespace-pre-wrap break-words", children: message.content })
         }
       ),
       /* @__PURE__ */ jsxRuntime.jsx("span", { className: "text-[10px] mt-1.5 mr-1 text-muted-foreground/70 select-none", children: formatDate(message.timestamp) })
@@ -940,7 +974,7 @@ function MessageList({
   messages,
   isLoading = false,
   emptyStateText = "What can I help with?",
-  showEmptyStateIcon = true,
+  showEmptyStateIcon: _showEmptyStateIcon = true,
   emptyStateComponent,
   layout = "full-width",
   showTimestamps = false,
@@ -1315,6 +1349,7 @@ function UserMessageV2({
     }
   };
   const timestamp = formatMessageTime(message.timestamp);
+  const parsedCommand = parseSlashCommand(message.content);
   const hasVisibleActions = showCopyAction || showEditAction && !!onEdit || showRetryAction && !!onRetry;
   const toastPortal = typeof document !== "undefined" ? reactDom.createPortal(
     /* @__PURE__ */ jsxRuntime.jsx(framerMotion.AnimatePresence, { children: toast && /* @__PURE__ */ jsxRuntime.jsx(
@@ -1359,7 +1394,10 @@ function UserMessageV2({
   return /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
     toastPortal,
     /* @__PURE__ */ jsxRuntime.jsx("div", { className: "payman-v2-user-msg payman-v2-fade-in", children: /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "payman-v2-user-msg-group", children: [
-      /* @__PURE__ */ jsxRuntime.jsx("div", { className: "payman-v2-user-msg-bubble", children: /* @__PURE__ */ jsxRuntime.jsx("p", { className: "payman-v2-user-msg-text", children: message.content }) }),
+      /* @__PURE__ */ jsxRuntime.jsx("div", { className: "payman-v2-user-msg-bubble", children: parsedCommand ? /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "payman-v2-user-msg-command", children: [
+        /* @__PURE__ */ jsxRuntime.jsx("span", { className: "payman-v2-user-msg-command-chip", children: parsedCommand.command }),
+        parsedCommand.body.trim() ? /* @__PURE__ */ jsxRuntime.jsx("p", { className: "payman-v2-user-msg-text", children: parsedCommand.body }) : null
+      ] }) : /* @__PURE__ */ jsxRuntime.jsx("p", { className: "payman-v2-user-msg-text", children: message.content }) }),
       message.isError && message.errorDetails && (() => {
         const resolvedError = getConflictErrorMessage(message.errorDetails) ?? message.errorDetails;
         return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "payman-v2-user-msg-error", children: [
@@ -2497,7 +2535,6 @@ var MessageListV2 = react.forwardRef(
 var ChatInputV2 = react.forwardRef(
   function ChatInputV22({
     onSend,
-    onCancel,
     disabled = false,
     isStreaming = false,
     placeholder = "Reply...",
@@ -2516,12 +2553,16 @@ var ChatInputV2 = react.forwardRef(
     editingMessageId = null,
     onClearEditing,
     analysisMode,
-    onAnalysisModeChange
+    onAnalysisModeChange,
+    slashCommands = []
   }, ref) {
     const [value, setValue] = react.useState("");
     const [isFocused, setIsFocused] = react.useState(false);
     const [showActions, setShowActions] = react.useState(false);
     const [showVoiceTooltip, setShowVoiceTooltip] = react.useState(false);
+    const [selectedCommandIndex, setSelectedCommandIndex] = react.useState(0);
+    const [inlineHint, setInlineHint] = react.useState(null);
+    const [commandMenuDismissed, setCommandMenuDismissed] = react.useState(false);
     const textareaRef = react.useRef(null);
     const actionsRef = react.useRef(null);
     const preRecordTextRef = react.useRef("");
@@ -2534,6 +2575,11 @@ var ChatInputV2 = react.forwardRef(
     const showAttachmentMenuButton = showAttachmentButton && hasAttachmentOptions;
     const showVoiceButton = enableVoice && onVoicePress != null;
     const isVoiceButtonDisabled = disabled || !voiceAvailable;
+    const commandQuery = value.startsWith("/") && !value.includes("\n") && !/\s/.test(value) ? value.toLowerCase() : null;
+    const commandSuggestions = commandQuery == null ? [] : slashCommands.filter(
+      (command) => command.name.toLowerCase().startsWith(commandQuery)
+    );
+    const showCommandSuggestions = !commandMenuDismissed && !isRecording && !disabled && commandSuggestions.length > 0;
     react.useEffect(() => {
       if (textareaRef.current) {
         textareaRef.current.style.height = "auto";
@@ -2583,6 +2629,10 @@ var ChatInputV2 = react.forwardRef(
         setShowActions(false);
       }
     }, [showAttachmentMenuButton]);
+    react.useEffect(() => {
+      setSelectedCommandIndex(0);
+      setCommandMenuDismissed(false);
+    }, [commandQuery]);
     react.useEffect(() => {
       return () => {
         if (voiceTooltipTimerRef.current) {
@@ -2598,8 +2648,13 @@ var ChatInputV2 = react.forwardRef(
     }, [isRecording, transcribedText]);
     const handleSend = react.useCallback(() => {
       if (!value.trim() || disabled) return;
+      if (slashCommandBodyIsEmpty(value)) {
+        setInlineHint("Add markdown content below the command line.");
+        return;
+      }
       voiceDraftSyncActiveRef.current = false;
       preRecordTextRef.current = "";
+      setInlineHint(null);
       onClearEditing?.();
       onSend(value.trim());
       setValue("");
@@ -2610,7 +2665,48 @@ var ChatInputV2 = react.forwardRef(
         }
       });
     }, [value, disabled, onClearEditing, onSend]);
+    const selectCommand = react.useCallback(
+      (command) => {
+        const insertText = command.insertText ?? `${command.name} `;
+        setValue(insertText);
+        setInlineHint(null);
+        setShowActions(false);
+        requestAnimationFrame(() => {
+          const textarea = textareaRef.current;
+          if (!textarea) return;
+          textarea.focus();
+          textarea.setSelectionRange(insertText.length, insertText.length);
+        });
+      },
+      []
+    );
     const handleKeyDown = (e) => {
+      if (showCommandSuggestions) {
+        if (e.key === "ArrowDown") {
+          e.preventDefault();
+          setSelectedCommandIndex(
+            (current) => Math.min(current + 1, commandSuggestions.length - 1)
+          );
+          return;
+        }
+        if (e.key === "ArrowUp") {
+          e.preventDefault();
+          setSelectedCommandIndex((current) => Math.max(current - 1, 0));
+          return;
+        }
+        if (e.key === "Enter" || e.key === "Tab") {
+          e.preventDefault();
+          const command = commandSuggestions[selectedCommandIndex];
+          if (command) selectCommand(command);
+          return;
+        }
+        if (e.key === "Escape") {
+          e.preventDefault();
+          setSelectedCommandIndex(0);
+          setCommandMenuDismissed(true);
+          return;
+        }
+      }
       if (e.key === "Enter" && !e.shiftKey) {
         e.preventDefault();
         if (isStreaming) return;
@@ -2655,6 +2751,35 @@ var ChatInputV2 = react.forwardRef(
     const canSend = value.trim().length > 0 && !disabled;
     const sendDisabled = !canSend || isStreaming;
     return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "payman-v2-input-container", children: [
+      /* @__PURE__ */ jsxRuntime.jsx(framerMotion.AnimatePresence, { children: showCommandSuggestions && /* @__PURE__ */ jsxRuntime.jsx(
+        framerMotion.motion.div,
+        {
+          initial: { opacity: 0, y: 6, scale: 0.98 },
+          animate: { opacity: 1, y: 0, scale: 1 },
+          exit: { opacity: 0, y: 6, scale: 0.98 },
+          transition: { duration: 0.12 },
+          className: "payman-v2-command-menu",
+          children: commandSuggestions.map((command, index) => /* @__PURE__ */ jsxRuntime.jsxs(
+            "button",
+            {
+              type: "button",
+              onMouseDown: (event) => {
+                event.preventDefault();
+                selectCommand(command);
+              },
+              className: cn(
+                "payman-v2-command-option",
+                index === selectedCommandIndex && "payman-v2-command-option-active"
+              ),
+              children: [
+                /* @__PURE__ */ jsxRuntime.jsx("span", { className: "payman-v2-command-name", children: command.name }),
+                /* @__PURE__ */ jsxRuntime.jsx("span", { className: "payman-v2-command-description", children: command.description })
+              ]
+            },
+            command.name
+          ))
+        }
+      ) }),
       /* @__PURE__ */ jsxRuntime.jsxs(
         "div",
         {
@@ -2699,6 +2824,8 @@ var ChatInputV2 = react.forwardRef(
                     if (isRecording) return;
                     const nextValue = e.target.value;
                     voiceDraftSyncActiveRef.current = false;
+                    setInlineHint(null);
+                    setCommandMenuDismissed(false);
                     setValue(nextValue);
                     if (editingMessageId && nextValue.length === 0) {
                       onClearEditing?.();
@@ -2913,6 +3040,7 @@ var ChatInputV2 = react.forwardRef(
           ]
         }
       ),
+      inlineHint && /* @__PURE__ */ jsxRuntime.jsx("p", { className: "payman-v2-input-inline-hint", children: inlineHint }),
       /* @__PURE__ */ jsxRuntime.jsx("p", { className: "payman-v2-input-disclaimer", children: "AI can make mistakes. Please double-check responses." })
     ] });
   }
@@ -3379,7 +3507,10 @@ var PaymanChatInner = react.forwardRef(function PaymanChatInner2({
     showAttachmentButton = true,
     showUploadImageButton = true,
     showAttachFileButton = true,
-    messageActions: messageActionsConfig
+    messageActions: messageActionsConfig,
+    enableSlashCommands = true,
+    slashCommands: slashCommandsConfig,
+    commandPermissions
   } = config;
   const messageActions = react.useMemo(
     () => ({
@@ -3397,6 +3528,13 @@ var PaymanChatInner = react.forwardRef(function PaymanChatInner2({
     }),
     [messageActionsConfig]
   );
+  const slashCommands = react.useMemo(
+    () => enableSlashCommands ? filterSlashCommands(
+      slashCommandsConfig ?? DEFAULT_SLASH_COMMANDS,
+      commandPermissions
+    ) : [],
+    [commandPermissions, enableSlashCommands, slashCommandsConfig]
+  );
   const isSessionParamsConfigured = react.useMemo(() => {
     if (!sessionParams) return false;
     return !!(sessionParams.id?.trim() && sessionParams.name?.trim());
@@ -3594,7 +3732,8 @@ var PaymanChatInner = react.forwardRef(function PaymanChatInner2({
                       editingMessageId,
                       onClearEditing: handleClearEditing,
                       analysisMode,
-                      onAnalysisModeChange: setAnalysisMode
+                      onAnalysisModeChange: setAnalysisMode,
+                      slashCommands
                     }
                   )
                 }
@@ -3669,7 +3808,8 @@ var PaymanChatInner = react.forwardRef(function PaymanChatInner2({
                   editingMessageId,
                   onClearEditing: handleClearEditing,
                   analysisMode,
-                  onAnalysisModeChange: setAnalysisMode
+                  onAnalysisModeChange: setAnalysisMode,
+                  slashCommands
                 }
               )
             ]