@paymanai/payman-ask-sdk 2.0.4 → 2.0.6

package/README.md

@@ -93,6 +93,15 @@ type ChatConfig = {
       text?: string;
       icon?: boolean;
       content?: React.ReactNode;
+      suggestions?: {
+        enabled?: boolean;
+        title?: string;
+        categories: Array<{
+          label: string;
+          icon?: React.ReactNode;
+          prompts: string[];
+        }>;
+      };
     };
 
     input?: {
@@ -154,6 +163,48 @@ Leaving the `ui` block out renders a usable ChatGPT-style surface:
 
 Turn features on with booleans, and only reach for the full object form when you need custom labels, widths, or per-option toggles.
 
+## Suggested prompts
+
+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.
+
+```tsx
+const isProd = process.env.NEXT_PUBLIC_ENV === "production";
+const suggestions = {
+  enabled: true,
+  title: "Good evening\nHow can I help you today?",
+  categories: [
+    { label: "ACCOUNTS", prompts: ["Show my account balance"] },
+    { label: "PAYMENTS", prompts: ["Pay Sarah $50", "Transfer money to my savings"] },
+    ...(isProd
+      ? []
+      : [{ label: "SIMULATION TOOLS", prompts: ["Simulate a mid-stream error"] }]),
+  ],
+};
+
+<PaymanChat
+  config={{
+    ...config,
+    ui: {
+      ...config.ui,
+      emptyState: {
+        ...config.ui?.emptyState,
+        suggestions,
+      },
+    },
+  }}
+/>
+```
+
+`enabled: false` hides the bubbles without removing the data. Category and prompt arrays render in the order provided, and empty categories are ignored. Bubbles disappear after the first message because they are part of the empty state.
+
+`title` is optional and falls back to `ui.emptyState.text`. Newlines are preserved, so pass `"Good evening\nHow can I help you today?"` when you want the original two-line empty-state layout. If a single-line greeting like `"Good evening How can I help..."` is provided, the SDK inserts a dash between the greeting and question.
+
+`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.
+
 ## Session history
 
 Pass `ui.sessionHistory: true` and provide `workflow.id` + `session.owner.id`. `<PaymanChat/>` mounts a resizable, collapsible sidebar on desktop and a hamburger-triggered drawer on mobile. Clicking a row calls `loadSession(sessionId)` — which cancels any in-flight stream, clears the current chat, fetches the conversation history, and renders it with `isHistorical: true` (renderers skip the thinking/step UI for those rows).

package/dist/index.d.mts

@@ -55,8 +55,39 @@ type SessionHistoryOptions = {
     /** Show a sidebar "New Session" button wired to the chat reset flow. Default: false */
     showNewSessionButton?: boolean;
 };
+type EmptyStatePromptCategory = {
+    /** Label shown in the category bubble, e.g. "Account". Also used as the accessible name for the prompt group. */
+    label: string;
+    /** Optional icon rendered before the label in the category bubble. */
+    icon?: React__default.ReactNode;
+    /** Prompt strings; clicking sends the string verbatim. Array order is preserved as render order. */
+    prompts: string[];
+};
+type EmptyStateSuggestionsConfig = {
+    /** Default: true. Pass false to hide bubbles without removing data. */
+    enabled?: boolean;
+    /** Optional heading above categories. Falls back to ui.emptyState.text. */
+    title?: string;
+    /**
+     * Categories rendered in array order. Apps that need environment-specific
+     * categories (e.g. internal-only "SIMULATION TOOLS") should filter this
+     * array on the consumer side — the SDK has no notion of dev/prod and will
+     * render exactly what is passed.
+     */
+    categories: EmptyStatePromptCategory[];
+};
 type ChatUIConfig = {
     layout?: "centered" | "full-width";
+    /**
+     * Color scheme for the React Native chat surface.
+     * Web styling continues to follow Tailwind. Default: "light".
+     */
+    theme?: "light" | "dark";
+    /**
+     * Accent / brand color used by the native chat UI (send button, hero,
+     * focused border, etc). Defaults to Payman teal `#00858d`.
+     */
+    accent?: string;
     agent?: {
         /** Default: "Assistant" */
         name?: string;
@@ -66,10 +97,19 @@ type ChatUIConfig = {
     emptyState?: {
         /** Default: "What can I help with?" */
         text?: string;
+        /**
+         * Small line above the main empty-state text (e.g. "Hi, Mike").
+         * Native only — web ignores this for now.
+         */
+        eyebrow?: string;
         /** Default: true */
         icon?: boolean;
         /** Custom React node rendered above the empty-state text */
         content?: React__default.ReactNode;
+        /** Custom logo element rendered in the empty state (native only). Replaces the default HeroMark. */
+        logo?: React__default.ReactNode;
+        /** Optional app-provided prompt bubbles rendered by the SDK. */
+        suggestions?: EmptyStateSuggestionsConfig;
     };
     input?: {
         /** Default: "Type your message..." */
@@ -358,4 +398,4 @@ declare function captureSentryError(error: Error | string, context: ChatSessionC
  */
 declare function formatRelativeTime(iso: string, now?: Date): string;
 
-export { type AssistantMessageActionsConfig, type ChatAvailability, type ChatCallbacks, type ChatConfig, ChatHeader, type ChatHeaderProps, type ChatSessionContext, type ChatUIConfig, FloatingChat, type MessageActionsConfig, type MessageListV2Props, type OtpInputProps, PaymanChat, PaymanChatContext, type PaymanChatContextValue, type PaymanChatProps, type PaymanChatRef, type SessionHistoryOptions, SessionHistorySidebar, type Stage, type StreamingMessageProps, UserActionModal, type UserActionModalProps, type UserMessageActionsConfig, type VoiceOptions, captureSentryError, cn, formatDate, formatRelativeTime, usePaymanChat, useSessionHistory };
+export { type AssistantMessageActionsConfig, type ChatAvailability, type ChatCallbacks, type ChatConfig, ChatHeader, type ChatHeaderProps, type ChatSessionContext, type ChatUIConfig, type EmptyStatePromptCategory, type EmptyStateSuggestionsConfig, FloatingChat, type MessageActionsConfig, type MessageListV2Props, type OtpInputProps, PaymanChat, PaymanChatContext, type PaymanChatContextValue, type PaymanChatProps, type PaymanChatRef, type SessionHistoryOptions, SessionHistorySidebar, type Stage, type StreamingMessageProps, UserActionModal, type UserActionModalProps, type UserMessageActionsConfig, type VoiceOptions, captureSentryError, cn, formatDate, formatRelativeTime, usePaymanChat, useSessionHistory };

package/dist/index.d.ts

@@ -55,8 +55,39 @@ type SessionHistoryOptions = {
     /** Show a sidebar "New Session" button wired to the chat reset flow. Default: false */
     showNewSessionButton?: boolean;
 };
+type EmptyStatePromptCategory = {
+    /** Label shown in the category bubble, e.g. "Account". Also used as the accessible name for the prompt group. */
+    label: string;
+    /** Optional icon rendered before the label in the category bubble. */
+    icon?: React__default.ReactNode;
+    /** Prompt strings; clicking sends the string verbatim. Array order is preserved as render order. */
+    prompts: string[];
+};
+type EmptyStateSuggestionsConfig = {
+    /** Default: true. Pass false to hide bubbles without removing data. */
+    enabled?: boolean;
+    /** Optional heading above categories. Falls back to ui.emptyState.text. */
+    title?: string;
+    /**
+     * Categories rendered in array order. Apps that need environment-specific
+     * categories (e.g. internal-only "SIMULATION TOOLS") should filter this
+     * array on the consumer side — the SDK has no notion of dev/prod and will
+     * render exactly what is passed.
+     */
+    categories: EmptyStatePromptCategory[];
+};
 type ChatUIConfig = {
     layout?: "centered" | "full-width";
+    /**
+     * Color scheme for the React Native chat surface.
+     * Web styling continues to follow Tailwind. Default: "light".
+     */
+    theme?: "light" | "dark";
+    /**
+     * Accent / brand color used by the native chat UI (send button, hero,
+     * focused border, etc). Defaults to Payman teal `#00858d`.
+     */
+    accent?: string;
     agent?: {
         /** Default: "Assistant" */
         name?: string;
@@ -66,10 +97,19 @@ type ChatUIConfig = {
     emptyState?: {
         /** Default: "What can I help with?" */
         text?: string;
+        /**
+         * Small line above the main empty-state text (e.g. "Hi, Mike").
+         * Native only — web ignores this for now.
+         */
+        eyebrow?: string;
         /** Default: true */
         icon?: boolean;
         /** Custom React node rendered above the empty-state text */
         content?: React__default.ReactNode;
+        /** Custom logo element rendered in the empty state (native only). Replaces the default HeroMark. */
+        logo?: React__default.ReactNode;
+        /** Optional app-provided prompt bubbles rendered by the SDK. */
+        suggestions?: EmptyStateSuggestionsConfig;
     };
     input?: {
         /** Default: "Type your message..." */
@@ -358,4 +398,4 @@ declare function captureSentryError(error: Error | string, context: ChatSessionC
  */
 declare function formatRelativeTime(iso: string, now?: Date): string;
 
-export { type AssistantMessageActionsConfig, type ChatAvailability, type ChatCallbacks, type ChatConfig, ChatHeader, type ChatHeaderProps, type ChatSessionContext, type ChatUIConfig, FloatingChat, type MessageActionsConfig, type MessageListV2Props, type OtpInputProps, PaymanChat, PaymanChatContext, type PaymanChatContextValue, type PaymanChatProps, type PaymanChatRef, type SessionHistoryOptions, SessionHistorySidebar, type Stage, type StreamingMessageProps, UserActionModal, type UserActionModalProps, type UserMessageActionsConfig, type VoiceOptions, captureSentryError, cn, formatDate, formatRelativeTime, usePaymanChat, useSessionHistory };
+export { type AssistantMessageActionsConfig, type ChatAvailability, type ChatCallbacks, type ChatConfig, ChatHeader, type ChatHeaderProps, type ChatSessionContext, type ChatUIConfig, type EmptyStatePromptCategory, type EmptyStateSuggestionsConfig, FloatingChat, type MessageActionsConfig, type MessageListV2Props, type OtpInputProps, PaymanChat, PaymanChatContext, type PaymanChatContextValue, type PaymanChatProps, type PaymanChatRef, type SessionHistoryOptions, SessionHistorySidebar, type Stage, type StreamingMessageProps, UserActionModal, type UserActionModalProps, type UserMessageActionsConfig, type VoiceOptions, captureSentryError, cn, formatDate, formatRelativeTime, usePaymanChat, useSessionHistory };

package/dist/index.js

@@ -2523,6 +2523,136 @@ function ImageLightboxV2({ src, alt, onClose }) {
     document.body
   );
 }
+function slugify(value) {
+  const slug = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+  return slug || "category";
+}
+function formatSuggestionTitle(value) {
+  return value.replace(
+    /\b(Good (?:morning|afternoon|evening))[ \t]+(?=how can I help)/i,
+    "$1 - "
+  );
+}
+function CategoryGlyph({ label }) {
+  const normalizedLabel = label.toLowerCase();
+  const icon = normalizedLabel.includes("pay") || normalizedLabel.includes("transfer") ? "arrow" : normalizedLabel.includes("account") ? "card" : normalizedLabel.includes("insight") || normalizedLabel.includes("analytics") ? "chart" : normalizedLabel.includes("product") ? "clock" : "spark";
+  return /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "payman-v2-prompt-category-icon", "aria-hidden": "true", children: [
+    icon === "arrow" && /* @__PURE__ */ jsxRuntime.jsx("svg", { viewBox: "0 0 20 20", focusable: "false", children: /* @__PURE__ */ jsxRuntime.jsx("path", { d: "M4 10h11m0 0-4-4m4 4-4 4" }) }),
+    icon === "card" && /* @__PURE__ */ jsxRuntime.jsxs("svg", { viewBox: "0 0 20 20", focusable: "false", children: [
+      /* @__PURE__ */ jsxRuntime.jsx("rect", { x: "3.5", y: "5.5", width: "13", height: "9", rx: "1.5" }),
+      /* @__PURE__ */ jsxRuntime.jsx("path", { d: "M3.5 8h13" })
+    ] }),
+    icon === "chart" && /* @__PURE__ */ jsxRuntime.jsxs("svg", { viewBox: "0 0 20 20", focusable: "false", children: [
+      /* @__PURE__ */ jsxRuntime.jsx("path", { d: "M4 15.5V4.5" }),
+      /* @__PURE__ */ jsxRuntime.jsx("path", { d: "M4 15.5h12" }),
+      /* @__PURE__ */ jsxRuntime.jsx("path", { d: "m6.5 12 3-3 2 2 3.5-4" })
+    ] }),
+    icon === "clock" && /* @__PURE__ */ jsxRuntime.jsxs("svg", { viewBox: "0 0 20 20", focusable: "false", children: [
+      /* @__PURE__ */ jsxRuntime.jsx("circle", { cx: "10", cy: "10", r: "6" }),
+      /* @__PURE__ */ jsxRuntime.jsx("path", { d: "M10 6.5V10l2.5 1.5" })
+    ] }),
+    icon === "spark" && /* @__PURE__ */ jsxRuntime.jsx("svg", { viewBox: "0 0 20 20", focusable: "false", children: /* @__PURE__ */ jsxRuntime.jsx("path", { d: "M10 3.5 11.5 8l4 2-4 2L10 16.5 8.5 12l-4-2 4-2L10 3.5Z" }) })
+  ] });
+}
+function PromptSuggestionsV2({
+  title,
+  categories,
+  disabled = false,
+  onPromptClick
+}) {
+  const shouldReduceMotion = framerMotion.useReducedMotion();
+  const validCategories = react.useMemo(
+    () => categories.filter((category) => category.prompts.length > 0),
+    [categories]
+  );
+  const [activeCategoryIndex, setActiveCategoryIndex] = react.useState(null);
+  react.useEffect(() => {
+    if (activeCategoryIndex != null && (activeCategoryIndex < 0 || activeCategoryIndex >= validCategories.length)) {
+      setActiveCategoryIndex(null);
+    }
+  }, [activeCategoryIndex, validCategories.length]);
+  if (validCategories.length === 0) return null;
+  const fadeTransition = { duration: 0.18, ease: "easeOut" };
+  const rootMotionProps = shouldReduceMotion ? {} : {
+    initial: { opacity: 0, y: 4 },
+    animate: { opacity: 1, y: 0 },
+    transition: fadeTransition
+  };
+  const getBubbleMotionProps = (index) => shouldReduceMotion ? {} : {
+    initial: { opacity: 0, y: 4 },
+    animate: { opacity: 1, y: 0 },
+    transition: { ...fadeTransition, delay: 0.04 * index }
+  };
+  const activeCategory = activeCategoryIndex == null ? null : validCategories[activeCategoryIndex] ?? null;
+  const activePanelId = activeCategoryIndex == null ? void 0 : `payman-v2-prompt-panel-${slugify(activeCategory?.label ?? "category")}-${activeCategoryIndex}`;
+  const displayTitle = title ? formatSuggestionTitle(title) : void 0;
+  return /* @__PURE__ */ jsxRuntime.jsxs(framerMotion.motion.div, { className: "payman-v2-prompt-root", ...rootMotionProps, children: [
+    displayTitle && /* @__PURE__ */ jsxRuntime.jsx("h2", { className: "payman-v2-prompt-title", children: displayTitle }),
+    /* @__PURE__ */ jsxRuntime.jsx("div", { className: "payman-v2-prompt-category-row", "aria-label": "Prompt categories", children: validCategories.map((category, categoryIndex) => {
+      const isActive = activeCategoryIndex === categoryIndex;
+      const categoryId = `payman-v2-prompt-cat-${slugify(category.label)}-${categoryIndex}`;
+      const panelId = `payman-v2-prompt-panel-${slugify(category.label)}-${categoryIndex}`;
+      return /* @__PURE__ */ jsxRuntime.jsxs(
+        framerMotion.motion.button,
+        {
+          id: categoryId,
+          type: "button",
+          "aria-expanded": isActive,
+          "aria-controls": panelId,
+          onClick: () => setActiveCategoryIndex(
+            (currentIndex) => currentIndex === categoryIndex ? null : categoryIndex
+          ),
+          className: "payman-v2-prompt-category-bubble",
+          "data-active": isActive ? "true" : "false",
+          ...getBubbleMotionProps(categoryIndex),
+          children: [
+            category.icon ?? /* @__PURE__ */ jsxRuntime.jsx(CategoryGlyph, { label: category.label }),
+            /* @__PURE__ */ jsxRuntime.jsx("span", { children: category.label })
+          ]
+        },
+        `${category.label}-${categoryIndex}`
+      );
+    }) }),
+    /* @__PURE__ */ jsxRuntime.jsx(framerMotion.AnimatePresence, { initial: false, mode: "wait", children: activeCategory && activeCategoryIndex != null && /* @__PURE__ */ jsxRuntime.jsx(
+      framerMotion.motion.section,
+      {
+        id: activePanelId,
+        role: "region",
+        "aria-labelledby": `payman-v2-prompt-cat-${slugify(activeCategory.label)}-${activeCategoryIndex}`,
+        className: "payman-v2-prompt-category",
+        initial: shouldReduceMotion ? void 0 : { opacity: 0, y: -2 },
+        animate: shouldReduceMotion ? void 0 : { opacity: 1, y: 0 },
+        exit: shouldReduceMotion ? void 0 : { opacity: 0, y: -2 },
+        transition: fadeTransition,
+        children: /* @__PURE__ */ jsxRuntime.jsx(
+          "div",
+          {
+            className: "payman-v2-prompt-row",
+            role: "group",
+            "aria-label": `${activeCategory.label} prompts`,
+            children: activeCategory.prompts.map((prompt, promptIndex) => /* @__PURE__ */ jsxRuntime.jsxs(
+              framerMotion.motion.button,
+              {
+                type: "button",
+                disabled,
+                onClick: () => onPromptClick(prompt),
+                className: "payman-v2-prompt-bubble",
+                "aria-label": `Use suggested prompt: ${prompt}`,
+                ...getBubbleMotionProps(promptIndex),
+                children: [
+                  /* @__PURE__ */ jsxRuntime.jsx("span", { children: prompt }),
+                  /* @__PURE__ */ jsxRuntime.jsx("span", { className: "payman-v2-prompt-option-arrow", "aria-hidden": "true", children: /* @__PURE__ */ jsxRuntime.jsx("svg", { viewBox: "0 0 20 20", focusable: "false", children: /* @__PURE__ */ jsxRuntime.jsx("path", { d: "M7 13 13 7m0 0H8m5 0v5" }) }) })
+                ]
+              },
+              `${prompt}-${promptIndex}`
+            ))
+          }
+        )
+      },
+      `${activeCategory.label}-${activeCategoryIndex}`
+    ) })
+  ] });
+}
 var DEFAULT_WIDTH = 260;
 var DEFAULT_MIN_WIDTH = 220;
 var DEFAULT_MAX_WIDTH = 440;
@@ -3717,6 +3847,8 @@ var PaymanChat = react.forwardRef(function PaymanChat2({
   const emptyStateText = ui.emptyState?.text ?? DEFAULT_EMPTY_STATE_TEXT;
   const showEmptyStateIcon = ui.emptyState?.icon ?? true;
   const emptyStateComponent = ui.emptyState?.content;
+  const suggestions = ui.emptyState?.suggestions;
+  const showSuggestions = suggestions != null && suggestions.enabled !== false && suggestions.categories.some((category) => category.prompts.length > 0);
   const showResetButton = ui.input?.showResetButton ?? false;
   const attachments = normalizeAttachments(ui.input?.attachments);
   const voice = normalizeVoice(ui.input?.voice);
@@ -3875,13 +4007,13 @@ var PaymanChat = react.forwardRef(function PaymanChat2({
     v2VerificationPending
   ]);
   const hideV2SendDuringVerification = v2UserAction != null && v2UserAction.status !== "approved" && v2UserAction.status !== "rejected";
-  const handleV2Send = (text) => {
+  const handleV2Send = react.useCallback((text) => {
     if (isRecording) stopRecording();
     if (text.trim()) {
       setEditingMessageId(null);
       void sendMessage(text.trim());
     }
-  };
+  }, [isRecording, sendMessage, stopRecording]);
   const handleEditMessageDraft = react.useCallback(
     (messageId) => {
       const targetMessage = messages.find((m) => m.id === messageId);
@@ -4021,7 +4153,10 @@ var PaymanChat = react.forwardRef(function PaymanChat2({
                     {
                       text: emptyStateText,
                       content: emptyStateComponent,
-                      showIcon: showEmptyStateIcon
+                      showIcon: showEmptyStateIcon && !showSuggestions,
+                      suggestions: showSuggestions ? suggestions : void 0,
+                      onPromptClick: handleV2Send,
+                      isStreaming: isWaitingForResponse
                     }
                   ),
                   /* @__PURE__ */ jsxRuntime.jsx(
@@ -4130,7 +4265,10 @@ var PaymanChat = react.forwardRef(function PaymanChat2({
 function EmptyState2({
   text,
   content,
-  showIcon
+  showIcon,
+  suggestions,
+  onPromptClick,
+  isStreaming
 }) {
   return /* @__PURE__ */ jsxRuntime.jsxs(
     "div",
@@ -4147,7 +4285,7 @@ function EmptyState2({
       },
       children: [
         content,
-        showIcon && !content && /* @__PURE__ */ jsxRuntime.jsx(
+        showIcon && !content && !suggestions && /* @__PURE__ */ jsxRuntime.jsx(
           "div",
           {
             "aria-hidden": "true",
@@ -4159,7 +4297,15 @@ function EmptyState2({
             }
           }
         ),
-        /* @__PURE__ */ jsxRuntime.jsx(
+        suggestions && onPromptClick ? /* @__PURE__ */ jsxRuntime.jsx(
+          PromptSuggestionsV2,
+          {
+            title: suggestions.title ?? text,
+            categories: suggestions.categories,
+            disabled: isStreaming,
+            onPromptClick
+          }
+        ) : /* @__PURE__ */ jsxRuntime.jsx(
           "div",
           {
             style: {