orchid-ai 2.0.0 → 2.0.1

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "orchid-ai",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Shared Orchid AI chat UI and visualization components",
   "main": "src/index.js",
+  "types": "src/index.d.ts",
   "exports": {
     ".": "./src/index.js",
     "./orchid-ai.css": "./orchid-ai.css",

package/src/hooks/useOrchidAiChat.js

@@ -0,0 +1,135 @@
+import { useState, useCallback, useRef } from 'react';
+
+/**
+ * Default status message strings. Export these so server-side code can import
+ * and reference the same values, making it easy to keep client and server in sync
+ * or swap them out per-app.
+ *
+ * Set showStatus: false on the hook to disable status display entirely.
+ */
+export const ORCHID_AI_DEFAULT_STATUS = {
+  thinking: 'Thinking',
+  compilingResponse: 'Compiling response',
+  lookingUpData: 'Looking up data',
+};
+
+/**
+ * React hook for Orchid AI chat. Handles SSE streaming when the server responds
+ * with Content-Type: text/event-stream, falling back to plain JSON for non-streaming
+ * backends.
+ *
+ * @param {object} opts
+ * @param {string} opts.endpoint - POST endpoint URL
+ * @param {(userMessage: string, history: Array) => object} opts.buildBody - builds the request body
+ * @param {() => object} [opts.getHeaders] - returns extra request headers (e.g. CSRF token)
+ * @param {boolean} [opts.showStatus=true] - set false to suppress status text entirely
+ *
+ * @returns {{ messages, loading, statusText, sendMessage, clearMessages }}
+ */
+export function useOrchidAiChat({ endpoint, buildBody, getHeaders, showStatus = true }) {
+  const [messages, setMessages] = useState([]);
+  const [loading, setLoading] = useState(false);
+  const [statusText, setStatusText] = useState('');
+
+  // Track messages in a ref so sendMessage always reads the latest without needing
+  // messages in its dependency array (avoids capturing stale history).
+  const messagesRef = useRef([]);
+
+  // Keep latest callbacks in refs so sendMessage identity stays stable regardless
+  // of whether the parent re-creates buildBody/getHeaders each render.
+  const buildBodyRef = useRef(buildBody);
+  const getHeadersRef = useRef(getHeaders);
+  buildBodyRef.current = buildBody;
+  getHeadersRef.current = getHeaders;
+
+  const addMessage = useCallback((msg) => {
+    setMessages((prev) => {
+      const next = [...prev, msg];
+      messagesRef.current = next;
+      return next;
+    });
+  }, []);
+
+  const sendMessage = useCallback(
+    async (userMessage) => {
+      const history = messagesRef.current.slice();
+      addMessage({ role: 'user', content: userMessage });
+      setLoading(true);
+      setStatusText('');
+
+      try {
+        const response = await fetch(endpoint, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            ...getHeadersRef.current?.(),
+          },
+          body: JSON.stringify(buildBodyRef.current(userMessage, history)),
+        });
+
+        const contentType = response.headers.get('content-type') ?? '';
+
+        if (contentType.includes('text/event-stream')) {
+          const reader = response.body.getReader();
+          const decoder = new TextDecoder();
+          let buffer = '';
+
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split('\n');
+            buffer = lines.pop() ?? '';
+
+            for (const line of lines) {
+              if (!line.startsWith('data: ')) continue;
+              try {
+                const event = JSON.parse(line.slice(6));
+                if (event.type === 'status' && showStatus) {
+                  setStatusText(event.text);
+                } else if (event.type === 'done') {
+                  addMessage({
+                    role: 'assistant',
+                    content: event.response,
+                    truncated: event.truncated,
+                  });
+                } else if (event.type === 'error') {
+                  addMessage({
+                    role: 'assistant',
+                    content: event.error || 'Something went wrong.',
+                  });
+                }
+              } catch {
+                // ignore malformed SSE lines
+              }
+            }
+          }
+        } else {
+          // Plain JSON fallback for non-streaming backends
+          const data = await response.json();
+          if (response.ok) {
+            addMessage({ role: 'assistant', content: data.response, truncated: data.truncated });
+          } else {
+            addMessage({ role: 'assistant', content: data.error || 'Something went wrong.' });
+          }
+        }
+      } catch {
+        addMessage({
+          role: 'assistant',
+          content: 'Network error. Please check your connection and try again.',
+        });
+      } finally {
+        setLoading(false);
+        setStatusText('');
+      }
+    },
+    [endpoint, showStatus, addMessage]
+  );
+
+  const clearMessages = useCallback(() => {
+    setMessages([]);
+    messagesRef.current = [];
+  }, []);
+
+  return { messages, loading, statusText, sendMessage, clearMessages };
+}

package/src/index.d.ts

@@ -0,0 +1,124 @@
+import * as React from 'react';
+
+// ─── Chat UI ────────────────────────────────────────────────────────────────
+
+export interface ChatMessage {
+  role: 'user' | 'assistant';
+  content: string;
+  truncated?: boolean;
+}
+
+export interface ChatWindowProps {
+  messages: ChatMessage[];
+  loading?: boolean;
+  statusText?: string;
+  onSuggestionClick?: (text: string) => void;
+  aiEnabled?: boolean;
+  organisationName?: string;
+  /** Any extra props are forwarded to the root element */
+  [key: string]: unknown;
+}
+
+export interface ChatInputProps {
+  onSend: (text: string) => void;
+  disabled?: boolean;
+  disabledReason?: string;
+  onDisabledClick?: () => void;
+  [key: string]: unknown;
+}
+
+export interface MessageProps {
+  role: 'user' | 'assistant';
+  content: string;
+  truncated?: boolean;
+}
+
+export const ChatWindow: React.FC<ChatWindowProps>;
+export const ChatInput: React.FC<ChatInputProps>;
+export const Message: React.FC<MessageProps>;
+
+// ─── useOrchidAiChat ─────────────────────────────────────────────────────────
+
+export interface OrchidAiChatOptions {
+  /** POST endpoint that accepts the chat message */
+  endpoint: string;
+  /** Builds the request body from the user message and current history */
+  buildBody: (userMessage: string, history: ChatMessage[]) => Record<string, unknown>;
+  /** Returns extra request headers (e.g. CSRF token) */
+  getHeaders?: () => Record<string, string>;
+  /**
+   * Whether to display status messages during processing.
+   * Set to false to suppress all status text. Defaults to true.
+   */
+  showStatus?: boolean;
+}
+
+export interface OrchidAiChatState {
+  messages: ChatMessage[];
+  loading: boolean;
+  /** Live status text emitted by the server (e.g. "Thinking", "Compiling response") */
+  statusText: string;
+  sendMessage: (userMessage: string) => Promise<void>;
+  clearMessages: () => void;
+}
+
+export function useOrchidAiChat(options: OrchidAiChatOptions): OrchidAiChatState;
+
+/**
+ * Default status message strings used by the Orchid AI backend services.
+ * Import these in server-side code to keep client and server labels in sync,
+ * or to override individual values per app.
+ */
+export const ORCHID_AI_DEFAULT_STATUS: {
+  readonly thinking: string;
+  readonly compilingResponse: string;
+  readonly lookingUpData: string;
+};
+
+// ─── Visualizations ──────────────────────────────────────────────────────────
+
+export const AiVisualization: React.FC<{ data: unknown }>;
+export const BarChart: React.FC<{ data: unknown }>;
+export const LineChart: React.FC<{ data: unknown }>;
+export const DotChart: React.FC<{ data: unknown }>;
+export const ScatterPlot: React.FC<{ data: unknown }>;
+export const HistogramChart: React.FC<{ data: unknown }>;
+export const StackedBarChart: React.FC<{ data: unknown }>;
+export const GroupedBarChart: React.FC<{ data: unknown }>;
+export const DataTable: React.FC<{ data: unknown }>;
+export const StatCards: React.FC<{ data: unknown }>;
+export const Timeline: React.FC<{ data: unknown }>;
+
+// ─── Chart schema utilities ───────────────────────────────────────────────────
+
+export const CHART_BLOCK_LANGUAGE: string;
+export const LEGACY_CHART_BLOCK_LANGUAGE: string;
+export function isChartMarkdownLanguage(lang: string): boolean;
+
+export const DOT_CHART_TYPE: string;
+export const TABLE_TYPE: string;
+export const BAR_CHART_TYPE: string;
+export const STAT_CARDS_TYPE: string;
+export const TIMELINE_TYPE: string;
+export const LINE_CHART_TYPE: string;
+export const STACKED_BAR_CHART_TYPE: string;
+export const GROUPED_BAR_CHART_TYPE: string;
+export const HISTOGRAM_TYPE: string;
+export const SCATTER_PLOT_TYPE: string;
+
+export function validateBarChartPayload(data: unknown): boolean;
+export function validateLineChartPayload(data: unknown): boolean;
+export function validateStackedBarChartPayload(data: unknown): boolean;
+export function validateGroupedBarChartPayload(data: unknown): boolean;
+export function validateHistogramPayload(data: unknown): boolean;
+export function validateScatterPlotPayload(data: unknown): boolean;
+export function validateStatCardsPayload(data: unknown): boolean;
+export function validateTimelinePayload(data: unknown): boolean;
+export function validateTablePayload(data: unknown): boolean;
+
+export function parseChartBlock(block: string): unknown;
+export function resolveChartBlock(block: string): unknown;
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+export const ORCHID_AI_VISUALIZATION_INSTRUCTIONS: string;

package/src/index.js

@@ -1,5 +1,6 @@
 // Chat UI
 export { default as ChatWindow } from './components/ChatWindow';
+export { useOrchidAiChat, ORCHID_AI_DEFAULT_STATUS } from './hooks/useOrchidAiChat';
 export { default as ChatInput } from './components/ChatInput';
 export { default as Message } from './components/Message';