@xinghunm/ai-chat 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,545 @@
+import * as _emotion_react_jsx_runtime from '@emotion/react/jsx-runtime';
+import { ReactNode, MutableRefObject } from 'react';
+import { AxiosInstance } from 'axios';
+import * as zustand_vanilla from 'zustand/vanilla';
+
+/**
+ * Chat role values accepted by the frontend chat domain.
+ */
+declare const CHAT_ROLES: readonly ["user", "assistant", "system"];
+type ChatRole = (typeof CHAT_ROLES)[number];
+/**
+ * Supported message lifecycle states for optimistic UI rendering.
+ */
+declare const CHAT_MESSAGE_STATUSES: readonly ["pending", "streaming", "done", "error", "stopped"];
+type ChatMessageStatus = (typeof CHAT_MESSAGE_STATUSES)[number];
+/**
+ * Supported agent interaction modes exposed by the v2 chat API.
+ */
+declare const CHAT_AGENT_MODES: readonly ["ask", "plan", "agent"];
+type ChatAgentMode = (typeof CHAT_AGENT_MODES)[number];
+/**
+ * Default agent mode used for new sessions and legacy sessions without mode metadata.
+ */
+declare const DEFAULT_CHAT_AGENT_MODE: ChatAgentMode;
+/**
+ * Represents a chat session with its metadata.
+ */
+interface ChatSession {
+    sessionId: string;
+    title: string;
+    createdAt: string;
+    updatedAt: string;
+    model: string;
+    mode?: ChatAgentMode;
+}
+/**
+ * Client-side image attachment metadata kept in chat messages.
+ */
+interface ChatImageAttachment {
+    id: string;
+    name: string;
+    mimeType: string;
+    size: number;
+    previewUrl: string;
+}
+/**
+ * Select option metadata used by plan questionnaires.
+ */
+interface PlanQuestionOption {
+    label: string;
+    value: string;
+}
+/**
+ * The value type for a single questionnaire answer.
+ */
+type PlanQuestionnaireAnswerValue = string | string[] | number | boolean;
+interface PlanQuestionBase {
+    id: string;
+    label: string;
+    required?: boolean;
+}
+/**
+ * Single-choice question shown in a plan questionnaire.
+ */
+interface PlanSingleSelectQuestion extends PlanQuestionBase {
+    kind: 'single_select';
+    allowOther?: boolean;
+    options: PlanQuestionOption[];
+}
+/**
+ * Multiple-choice question shown in a plan questionnaire.
+ */
+interface PlanMultiSelectQuestion extends PlanQuestionBase {
+    kind: 'multi_select';
+    options: PlanQuestionOption[];
+}
+/**
+ * Free-text question shown in a plan questionnaire.
+ */
+interface PlanTextQuestion extends PlanQuestionBase {
+    kind: 'text';
+    placeholder?: string;
+}
+/**
+ * Numeric question shown in a plan questionnaire.
+ */
+interface PlanNumberQuestion extends PlanQuestionBase {
+    kind: 'number';
+    placeholder?: string;
+    unit?: string;
+}
+/**
+ * Boolean question shown in a plan questionnaire.
+ */
+interface PlanBooleanQuestion extends PlanQuestionBase {
+    kind: 'boolean';
+    trueLabel?: string;
+    falseLabel?: string;
+}
+/**
+ * Supported question variants in a plan questionnaire.
+ */
+type PlanQuestion = PlanSingleSelectQuestion | PlanMultiSelectQuestion | PlanTextQuestion | PlanNumberQuestion | PlanBooleanQuestion;
+/**
+ * Structured question form emitted for plan-mode clarification flows.
+ */
+interface PlanQuestionnaire {
+    questionnaireId: string;
+    title?: string;
+    description?: string;
+    submitLabel?: string;
+    questions: PlanQuestion[];
+    answers?: Partial<Record<string, PlanQuestionnaireAnswerValue>>;
+}
+/**
+ * Submission payload emitted by a questionnaire card.
+ */
+interface PlanQuestionnaireSubmission {
+    questionnaireId: string;
+    answers: Record<string, PlanQuestionnaireAnswerValue>;
+    content: string;
+    sourceMessageId?: string;
+}
+/**
+ * Submission payload emitted when a user confirms an execution proposal.
+ */
+interface ExecutionConfirmationSubmission {
+    proposalId: string;
+    content: string;
+    sourceMessageId?: string;
+}
+/**
+ * Summary item used by structured assistant cards to describe parameter changes.
+ */
+interface ChatParameterSummaryItem {
+    label: string;
+    value: string;
+    fieldPath?: string;
+}
+/**
+ * Executable proposal metadata surfaced by structured assistant confirmation cards.
+ */
+interface ExecutionProposal {
+    proposalId: string;
+    equationKey: string;
+    equationName: string;
+    solverName?: string;
+    parameterSummary: ChatParameterSummaryItem[];
+    warnings?: string[];
+    requiresConfirmation: true;
+}
+/**
+ * Structured result summary emitted after a PDE task has started or completed.
+ */
+interface ResultSummary {
+    taskId: string;
+    status: 'completed' | 'failed' | 'running' | 'pending';
+    headline: string;
+    details: string[];
+}
+/**
+ * Structured assistant block variants rendered by the chat thread.
+ */
+type ChatMessageBlock = {
+    type: 'markdown';
+    text: string;
+} | {
+    type: 'notice';
+    tone: 'info' | 'warning' | 'success';
+    text: string;
+} | {
+    type: 'parameter_summary';
+    items: ChatParameterSummaryItem[];
+} | {
+    type: 'confirmation_card';
+    proposal: ExecutionProposal;
+} | {
+    type: 'result_summary';
+    summary: ResultSummary;
+} | {
+    type: 'questionnaire';
+    questionnaire: PlanQuestionnaire;
+} | {
+    type: 'custom';
+    kind: string;
+    data: unknown;
+};
+/**
+ * Chat message stored in the UI state and rendered by the chat thread.
+ */
+interface ChatMessage {
+    id: string;
+    sessionId: string;
+    role: ChatRole;
+    content: string;
+    blocks?: ChatMessageBlock[];
+    attachments?: ChatImageAttachment[];
+    localOnly?: boolean;
+    status?: ChatMessageStatus;
+    createdAt: string;
+}
+/**
+ * Message patch emitted while a streaming response is being assembled.
+ */
+interface ChatStreamMessagePatch {
+    content?: string;
+    blocks?: ChatMessageBlock[];
+}
+/**
+ * Normalized update extracted from a single backend stream packet.
+ */
+interface ChatStreamPacketUpdate {
+    content?: string;
+    contentDelta?: string;
+    blocks?: ChatMessageBlock[];
+}
+/**
+ * Parameters used by a transport implementation when starting a streaming response.
+ */
+interface ChatTransportStartStreamArgs {
+    /** Existing backend session ID. Omit for a brand new conversation. */
+    sessionId?: string;
+    /** Model identifier currently selected in the UI. */
+    model: string;
+    /** Agent mode selected in the UI. */
+    mode: ChatAgentMode;
+    /** User message content that should be sent to the backend. */
+    content: string;
+    /** Abort signal controlled by the chat composer stop action. */
+    signal?: AbortSignal;
+    /** Emits normalized streaming patches that should update the assistant message. */
+    onUpdate: (update: ChatStreamPacketUpdate) => void;
+    /** Emits the definitive backend session ID once the server creates or upgrades one. */
+    onSessionId?: (sessionId: string) => void;
+    /** Called after the stream completes successfully. */
+    onDone?: () => void;
+    /** Called when the stream fails and the UI should surface an error. */
+    onError?: (error: Error) => void;
+}
+/**
+ * Transport interface implemented by host applications to connect chat UI to any backend.
+ */
+interface ChatTransport {
+    /** Loads the model list shown by the composer model selector. */
+    getModels: () => Promise<ChatModelsResponse>;
+    /** Starts a single assistant response stream for the current user message. */
+    startStream: (args: ChatTransportStartStreamArgs) => Promise<void>;
+    /** Requests termination of the active backend stream for a session. */
+    terminateStream: (sessionId?: string) => Promise<ChatTerminateResponse>;
+}
+/**
+ * Arguments passed to custom stream packet transformers.
+ */
+interface ChatStreamPacketTransformArgs {
+    packet: ChatStreamPacket;
+    defaultUpdate: ChatStreamPacketUpdate | null;
+}
+/**
+ * Optional packet transformer supplied by integrators to adapt custom backend envelopes.
+ */
+type TransformChatStreamPacket = (args: ChatStreamPacketTransformArgs) => ChatStreamPacketUpdate | null;
+/**
+ * Arguments passed to custom block renderers.
+ */
+interface ChatMessageBlockRendererProps {
+    block: ChatMessageBlock;
+    index: number;
+    message: ChatMessage;
+    mode: ChatAgentMode;
+    onConfirmationSubmit?: (submission: ExecutionConfirmationSubmission) => void;
+    onQuestionnaireSubmit?: (submission: PlanQuestionnaireSubmission) => void;
+}
+/**
+ * Optional renderer used for custom block variants.
+ */
+type ChatMessageBlockRenderer = (props: ChatMessageBlockRendererProps) => ReactNode;
+interface ChatModel {
+    id: string;
+    object: string;
+}
+interface ChatModelsResponse {
+    data: ChatModel[];
+}
+/**
+ * Response payload returned after a terminate request has been processed.
+ */
+interface ChatTerminateResponse {
+    terminated: boolean;
+}
+interface ChatStreamDelta {
+    role?: ChatRole;
+    content?: string;
+}
+interface ChatStreamPayloadItem {
+    index: number;
+    delta: ChatStreamDelta;
+    finish_reason: string | null;
+}
+interface ChatStreamPacketData {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    payload: ChatStreamPayloadItem[];
+}
+interface ChatStructuredStreamPacketData {
+    message?: string;
+    content?: string;
+    blocks?: ChatMessageBlock[];
+}
+interface ChatStreamPacket {
+    type: 'message_start' | 'delta' | 'message_complete' | 'stream_end' | 'error';
+    data: ChatStreamPacketData | ChatStructuredStreamPacketData | string | {
+        message?: string;
+    };
+}
+/**
+ * Customizable UI label strings used throughout the chat components.
+ */
+interface AiChatLabels {
+    sendButton?: string;
+    stopButton?: string;
+    retryButton?: string;
+    placeholder?: string;
+    modeLabelAsk?: string;
+    modeLabelPlan?: string;
+    modeLabelAgent?: string;
+    newChat?: string;
+    emptyStateTitle?: string;
+    emptyStateSubtitle?: string;
+    attachmentLimitNotice?: string;
+    userRoleLabel?: string;
+    assistantRoleLabel?: string;
+    stoppedResponse?: string;
+    assistantStreamingAriaLabel?: string;
+    networkError?: string;
+    genericError?: string;
+}
+/**
+ * Default English label values used when no labels are provided.
+ */
+declare const DEFAULT_AI_CHAT_LABELS: Required<AiChatLabels>;
+
+interface AiChatProviderBaseProps {
+    /** Initial agent mode for new sessions. */
+    defaultMode?: ChatAgentMode;
+    /** Optional label overrides for UI strings. */
+    labels?: AiChatLabels;
+    /** Optional renderer used to extend message blocks with app-specific UI. */
+    renderMessageBlock?: ChatMessageBlockRenderer;
+    /**
+     * Whether to enable image attachment uploads. Defaults to `true`.
+     * Set to `false` to hide the upload button, disable paste-image handling,
+     * and make programmatic `pickImages`/`pasteImages` calls no-ops.
+     */
+    enableImageAttachments?: boolean;
+    /** Child elements rendered inside the provider. */
+    children: ReactNode;
+}
+interface AiChatProviderDefaultAdapterProps {
+    /** Base URL used by the built-in HTTP transport adapter. */
+    apiBaseUrl: string;
+    /** Authorization header value (e.g. "Bearer <token>") used by the built-in adapter. */
+    authToken: string;
+    /** Optional transformer used to adapt custom backend stream packets. */
+    transformStreamPacket?: TransformChatStreamPacket;
+    transport?: never;
+}
+interface AiChatProviderCustomTransportProps {
+    /** Fully custom transport implementation used by the generic chat shell. */
+    transport: ChatTransport;
+    apiBaseUrl?: never;
+    authToken?: never;
+    transformStreamPacket?: never;
+}
+/**
+ * Props accepted by `AiChatProvider`.
+ *
+ * Recommended:
+ * Inject a `transport` adapter so the chat UI can talk to any backend contract.
+ *
+ * Backward compatibility:
+ * `apiBaseUrl` + `authToken` still create the built-in HTTP adapter.
+ */
+type AiChatProviderProps = AiChatProviderBaseProps & (AiChatProviderDefaultAdapterProps | AiChatProviderCustomTransportProps);
+declare const AiChatProvider: (props: AiChatProviderProps) => _emotion_react_jsx_runtime.JSX.Element;
+
+/**
+ * Props for the all-in-one `AiChat` component.
+ */
+type AiChatProps = Omit<AiChatProviderProps, 'children'> & {
+    /** When true, renders the conversation list sidebar. Defaults to false. */
+    showConversationList?: boolean;
+};
+/**
+ * Top-level AI chat component. Wraps AiChatProvider and composes the full
+ * chat UI: optional conversation sidebar + thread + composer.
+ */
+declare const AiChat: ({ showConversationList, ...providerProps }: AiChatProps) => _emotion_react_jsx_runtime.JSX.Element;
+
+/**
+ * Endpoint overrides for the built-in HTTP transport adapter.
+ */
+interface DefaultChatTransportEndpoints {
+    /** Relative path used to fetch the available model list. */
+    models?: string;
+    /** Relative path used to start a streaming chat completion. */
+    completions?: string;
+    /** Relative path used to request stream termination. */
+    terminate?: string;
+}
+/**
+ * Options for the built-in HTTP transport adapter.
+ */
+interface CreateDefaultChatTransportOptions {
+    /** Base URL of the backend that serves the built-in chat endpoints. */
+    apiBaseUrl: string;
+    /** Authorization header value forwarded to the backend. */
+    authToken: string;
+    /** Optional extra headers appended to each streaming chat completion request. */
+    streamHeaders?: Record<string, string>;
+    /** Optional transformer used to normalize custom stream packets. */
+    transformStreamPacket?: TransformChatStreamPacket;
+    /** Optional endpoint overrides for backends that use different paths. */
+    endpoints?: DefaultChatTransportEndpoints;
+    /** Optional preconfigured axios instance reused for non-streaming requests. */
+    axiosInstance?: AxiosInstance;
+}
+/**
+ * Creates the built-in transport backed by the current HTTP chat API.
+ */
+declare const createDefaultChatTransport: ({ apiBaseUrl, authToken, streamHeaders, transformStreamPacket, endpoints, axiosInstance, }: CreateDefaultChatTransportOptions) => ChatTransport;
+
+declare const ChatThread: () => _emotion_react_jsx_runtime.JSX.Element;
+
+/**
+ * Props for the presentational `ChatComposerView` component.
+ */
+interface ChatComposerViewProps {
+    value: string;
+    placeholder: string;
+    attachments: ChatImageAttachment[];
+    attachmentNotice?: 'limit_reached' | null;
+    attachmentLimitNotice: string;
+    selectedModel: string;
+    selectedMode: ChatAgentMode;
+    availableModels: ChatModel[];
+    isModelsLoading: boolean;
+    isModelsError: boolean;
+    hasModels: boolean;
+    /** Whether a streaming response is currently in progress. */
+    isStreaming: boolean;
+    /** Whether a stop request has been sent but not yet finalized. */
+    isStopping: boolean;
+    /** Whether image attachment uploads are enabled. */
+    enableImageAttachments: boolean;
+    modeLabels: {
+        ask: string;
+        plan: string;
+        agent: string;
+    };
+    onValueChange: (value: string) => void;
+    onPickImages: (files: FileList | File[]) => void;
+    onPasteImages: (files: File[]) => void;
+    onRemoveAttachment: (attachmentId: string) => void;
+    onSelectedModelChange: (value: string) => void;
+    onSelectedModeChange: (value: ChatAgentMode) => void;
+    onReloadModels: () => void;
+    /** Called to abort the active streaming response. */
+    onStop: () => void | Promise<void>;
+    /** Called to send a new user message. */
+    onSend: () => void | Promise<void>;
+}
+declare const ChatComposer: () => _emotion_react_jsx_runtime.JSX.Element;
+
+declare const ChatConversationList: () => _emotion_react_jsx_runtime.JSX.Element;
+
+interface ChatState {
+    activeSessionId: string | null;
+    preferredMode: ChatAgentMode;
+    sessions: ChatSession[];
+    messagesBySession: Record<string, ChatMessage[]>;
+    streamingMessageBySession: Record<string, ChatMessage | undefined>;
+    isStreamingBySession: Record<string, boolean>;
+    isStoppingBySession: Record<string, boolean>;
+    errorBySession: Record<string, string | null>;
+}
+interface ChatActions {
+    createSession: (session: ChatSession) => void;
+    setActiveSession: (sessionId: string | null) => void;
+    replaceSessionId: (previousSessionId: string, nextSessionId: string) => void;
+    setPreferredMode: (mode: ChatAgentMode) => void;
+    setSessionMode: (sessionId: string, mode: ChatAgentMode) => void;
+    appendMessage: (sessionId: string, message: ChatMessage) => void;
+    startStreamingMessage: (sessionId: string, message: ChatMessage) => void;
+    updateStreamingMessage: (sessionId: string, content: string) => void;
+    patchStreamingMessage: (sessionId: string, patch: ChatStreamMessagePatch) => void;
+    completeStreamingMessage: (sessionId: string) => void;
+    requestStopStreaming: (sessionId: string) => void;
+    finalizeStoppedStreamingMessage: (sessionId: string) => void;
+    setSessionError: (sessionId: string, error: string | null) => void;
+    clearSessionError: (sessionId: string) => void;
+    updateQuestionnaireAnswers: (sessionId: string, messageId: string, questionnaireId: string, answers: Record<string, PlanQuestionnaireAnswerValue>) => void;
+}
+type ChatStore = ChatState & ChatActions;
+type ChatStoreInstance = ReturnType<typeof createChatStore>;
+declare const createChatStore: (initialState?: Partial<Pick<ChatState, "preferredMode">>) => zustand_vanilla.StoreApi<ChatStore>;
+
+interface ChatContextValue {
+    store: ChatStoreInstance;
+    transport: ChatTransport;
+    /** Legacy default-adapter axios client. Undefined when a custom transport is injected. */
+    axios?: AxiosInstance;
+    /** Legacy default-adapter base URL. Undefined when a custom transport is injected. */
+    apiBaseUrl?: string;
+    /** Legacy default-adapter authorization header value. Undefined when a custom transport is injected. */
+    authToken?: string;
+    labels: Required<AiChatLabels>;
+    /** Stable ref populated by ChatComposer on mount; allows ChatThread to trigger sends. */
+    sendRef: MutableRefObject<(content: string) => Promise<void>>;
+    /** Stable ref populated by ChatComposer on mount; allows ChatThread to replay the last request. */
+    retryRef: MutableRefObject<() => Promise<void>>;
+    /** Optional block renderer used to extend message rendering with custom block types. */
+    renderMessageBlock?: ChatMessageBlockRenderer;
+    /** Optional packet transformer used by the legacy default adapter. */
+    transformStreamPacket?: TransformChatStreamPacket;
+    /** Whether image attachments are enabled. Defaults to true. */
+    enableImageAttachments: boolean;
+}
+
+/**
+ * Returns the active AI chat context from `AiChatProvider`.
+ *
+ * @throws {Error} When called outside of `AiChatProvider`.
+ */
+declare const useChatContext: () => ChatContextValue;
+/**
+ * Selects a slice from the internal chat Zustand store.
+ *
+ * @param selector Receives the full chat store and returns the desired slice.
+ * @throws {Error} When called outside of `AiChatProvider`.
+ */
+declare const useChatStore: <T>(selector: (state: ChatStore) => T) => T;
+
+export { AiChat, type AiChatLabels, type AiChatProps, AiChatProvider, type AiChatProviderProps, CHAT_AGENT_MODES, type ChatAgentMode, ChatComposer, type ChatComposerViewProps, ChatConversationList, type ChatImageAttachment, type ChatMessage, type ChatMessageBlock, type ChatMessageBlockRenderer, type ChatMessageBlockRendererProps, type ChatMessageStatus, type ChatModel, type ChatRole, type ChatSession, type ChatStreamMessagePatch, type ChatStreamPacketTransformArgs, type ChatStreamPacketUpdate, ChatThread, type ChatTransport, type ChatTransportStartStreamArgs, type CreateDefaultChatTransportOptions, DEFAULT_AI_CHAT_LABELS, DEFAULT_CHAT_AGENT_MODE, type DefaultChatTransportEndpoints, type ExecutionConfirmationSubmission, type ExecutionProposal, type PlanQuestionnaire, type PlanQuestionnaireSubmission, type ResultSummary, type TransformChatStreamPacket, createDefaultChatTransport, useChatContext, useChatStore };