@dudousxd/nestjs-agent-react 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,419 @@
+import * as ai from 'ai';
+import { ChatTransport, UIMessage, UIMessageChunk, ToolUIPart, DynamicToolUIPart } from 'ai';
+import { ThreadSummary, ThreadDetail, Persona } from '@dudousxd/nestjs-agent-core';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+
+/** Identity surfaced by the backend's `meta` SSE frame / response headers. */
+interface AgentStreamMeta {
+    runId: string;
+    threadId: string;
+}
+interface AgentChatTransportOptions {
+    /**
+     * Origin + base path the agent endpoints hang off, e.g.
+     * `https://api.example.com`. Endpoints are appended as
+     * `${baseUrl}/agent/chat` etc. Defaults to `''` (same origin).
+     */
+    baseUrl?: string;
+    /** Static headers merged into every request (e.g. a tenant ref). */
+    headers?: Record<string, string>;
+    /**
+     * Resolved at request time — use for short-lived bearer tokens that
+     * must not be captured once at construction. Merged over `headers`.
+     */
+    getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+    /** Forwarded to `fetch` so cookie-based auth/impersonation works. */
+    credentials?: RequestCredentials;
+    /** Named agent to run the turn (backend `agent` field). */
+    agent?: string;
+    /**
+     * Extra body fields evaluated per send — the hook injects `threadId`,
+     * `persona`, and `pageContext` through this. Returned object is spread
+     * into the request body after the SDK's own `body`.
+     */
+    getBody?: () => Record<string, unknown>;
+    /**
+     * The run id to resume on mount, if any. Returning `undefined` makes
+     * `reconnectToStream` resolve to `null` WITHOUT hitting the network —
+     * this is the generalized fix for "useChat fires a doomed GET on mount
+     * and surfaces its 404". Wire this to the thread's `activeStreamId`.
+     */
+    getResumeRunId?: () => string | undefined;
+    /** Fires whenever a stream emits its `meta` frame. */
+    onMeta?: (meta: AgentStreamMeta) => void;
+    /** Injectable for tests / non-browser runtimes. Defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+/**
+ * AI SDK v7 `ChatTransport` for the nestjs-agent backend. POSTs
+ * `/agent/chat`, parses the backend's `meta` + `{delta}` + `done` SSE
+ * frames, and re-emits them as the v7 UI-message chunk stream
+ * (`start` → `text-start` → `text-delta`* → `text-end` → `finish`).
+ *
+ * The backend hydrates prior history from its store, so only the latest
+ * user message text is sent each turn — keeping payloads tiny and
+ * preventing the client from corrupting replayed history.
+ */
+declare class AgentChatTransport implements ChatTransport<UIMessage> {
+    private readonly options;
+    private currentRunId;
+    private currentThreadId;
+    constructor(options?: AgentChatTransportOptions);
+    /** Run id of the most recent stream — HITL approve/reject target this. */
+    get runId(): string | undefined;
+    /** Thread id of the most recent stream. */
+    get threadId(): string | undefined;
+    sendMessages(options: Parameters<ChatTransport<UIMessage>['sendMessages']>[0]): Promise<ReadableStream<UIMessageChunk>>;
+    reconnectToStream(options: Parameters<ChatTransport<UIMessage>['reconnectToStream']>[0]): Promise<ReadableStream<UIMessageChunk> | null>;
+    private fetchImpl;
+    private baseUrl;
+    private resolveHeaders;
+    private captureHeaderMeta;
+    private recordMeta;
+    /**
+     * Parse the backend's SSE byte stream and synthesize a valid v7
+     * UI-message chunk stream. Recognized backend frames:
+     *  - `event: meta`  `data: {"runId","threadId"}`  → records identity
+     *  - `data: {"delta":"..."}`                       → `text-delta`
+     *  - `event: done`  `data: {}`                     → terminates
+     */
+    private toChunkStream;
+}
+
+/** The trimmed persona shape returned by `/agent/threads/personas/catalog`. */
+type PersonaCatalogEntry = Pick<Persona, 'id' | 'label'>;
+/**
+ * Thrown by {@link AgentClient} on a non-2xx response. Carries the HTTP `status` so callers can
+ * branch (e.g. 403 → "not your thread", 429 → quota) instead of string-matching a generic Error.
+ */
+declare class AgentHttpError extends Error {
+    readonly status: number;
+    readonly method: string;
+    readonly path: string;
+    constructor(status: number, method: string, path: string, statusText: string);
+}
+interface QuotaToday {
+    usedTokens: number;
+}
+interface CancelResult {
+    aborted: boolean;
+}
+interface AgentClientOptions {
+    /** Origin + base path, e.g. `https://api.example.com`. Defaults to `''`. */
+    baseUrl?: string;
+    /** Static headers merged into every request. */
+    headers?: Record<string, string>;
+    /** Resolved per request — for short-lived bearer tokens. */
+    getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+    /** Forwarded to fetch so cookie auth works. */
+    credentials?: RequestCredentials;
+    /** Injectable for tests / non-browser runtimes. */
+    fetch?: typeof fetch;
+}
+/**
+ * Framework-agnostic REST client for the nestjs-agent endpoints. Used by
+ * `useAgentChat`, but standalone-usable (vanilla fetch, no React).
+ */
+declare class AgentClient {
+    private readonly options;
+    constructor(options?: AgentClientOptions);
+    listThreads(): Promise<ThreadSummary[]>;
+    getThread(id: string): Promise<ThreadDetail>;
+    deleteThread(id: string): Promise<void>;
+    forkFromMessage(threadId: string, messageId: string): Promise<ThreadSummary>;
+    getPersonaCatalog(): Promise<PersonaCatalogEntry[]>;
+    getQuotaToday(): Promise<QuotaToday>;
+    cancelStream(runId: string): Promise<CancelResult>;
+    approveToolCall(input: {
+        toolCallId: string;
+    }): Promise<void>;
+    rejectToolCall(input: {
+        toolCallId: string;
+        reason?: string;
+    }): Promise<void>;
+    private request;
+}
+
+interface UseAgentChatOptions {
+    /** Origin + base path, e.g. `https://api.example.com`. Defaults to `''`. */
+    baseUrl?: string;
+    /** Static headers merged into every request. */
+    headers?: Record<string, string>;
+    /** Resolved per request — for short-lived bearer tokens. */
+    getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+    /** Forwarded to fetch so cookie auth/impersonation works. */
+    credentials?: RequestCredentials;
+    /** Injectable for tests / non-browser runtimes. */
+    fetch?: typeof fetch;
+    /** Reuse an existing client instead of constructing one. */
+    client?: AgentClient;
+    /** Named agent to run each turn. */
+    agent?: string;
+    /** Thread this chat is bound to. Omitted → backend creates one on send. */
+    threadId?: string;
+    /** Persisted history to seed `useChat` with (consumed on mount only). */
+    initialMessages?: UIMessage[];
+    /**
+     * Run id of a buffered stream to reconnect to on mount — wire this to the thread's
+     * `activeStreamId`. Its presence both gates the SDK's `resume` and names the run, so a normal
+     * mount (no id) never fires a doomed resume GET. Omitted → no resume.
+     */
+    resumeRunId?: string;
+    /** Active persona id sent on every turn. */
+    persona?: string;
+    /** Read at every send to capture a page snapshot for the page-assistant. */
+    getPageContext?: () => Record<string, unknown> | null;
+    /** Fired after each streamed turn finishes (e.g. to refetch the sidebar). */
+    onFinish?: () => void;
+}
+interface AddToolResultArgs {
+    tool: string;
+    toolCallId: string;
+    output: unknown;
+}
+/**
+ * Generalized `useChat` wiring for the nestjs-agent backend. Wraps the
+ * AI SDK v7 hook with `AgentChatTransport`, plus thread list/load/delete/
+ * fork, persona catalog, quota, cancel, and HITL approve/reject — all
+ * driven through `AgentClient`. Mirrors flip's `useAdminChat`, generalized.
+ */
+declare function useAgentChat(options: UseAgentChatOptions): {
+    addToolResult: ({ tool, toolCallId, output }: AddToolResultArgs) => void | PromiseLike<void>;
+    runId: string | undefined;
+    client: AgentClient;
+    threads: ThreadSummary[];
+    loadThreads: () => Promise<ThreadSummary[]>;
+    loadThread: (id: string) => Promise<ThreadDetail>;
+    deleteThread: (id: string) => Promise<void>;
+    forkThread: (threadId: string, messageId: string) => Promise<ThreadSummary>;
+    personaCatalog: PersonaCatalogEntry[];
+    loadPersonaCatalog: () => Promise<PersonaCatalogEntry[]>;
+    quota: QuotaToday | null;
+    loadQuota: () => Promise<QuotaToday>;
+    cancel: () => Promise<void>;
+    approve: ({ toolCallId }: {
+        toolCallId: string;
+    }) => Promise<void>;
+    reject: ({ toolCallId, reason, }: {
+        toolCallId: string;
+        reason?: string;
+    }) => Promise<void>;
+    regenerate: () => void;
+    id: string;
+    setMessages: (messages: UIMessage<unknown, ai.UIDataTypes, ai.UITools>[] | ((messages: UIMessage<unknown, ai.UIDataTypes, ai.UITools>[]) => UIMessage<unknown, ai.UIDataTypes, ai.UITools>[])) => void;
+    error: Error | undefined;
+    stop: () => Promise<void>;
+    messages: UIMessage<unknown, ai.UIDataTypes, ai.UITools>[];
+    status: ai.ChatStatus;
+    sendMessage: (message?: (Omit<UIMessage<unknown, ai.UIDataTypes, ai.UITools>, "id" | "role"> & {
+        id?: string;
+        role?: "system" | "user" | "assistant";
+    } & {
+        text?: never;
+        files?: never;
+        messageId?: string;
+    }) | {
+        text: string;
+        files?: FileList | ai.FileUIPart[];
+        metadata?: unknown;
+        parts?: never;
+        messageId?: string;
+    } | {
+        files: FileList | ai.FileUIPart[];
+        metadata?: unknown;
+        parts?: never;
+        messageId?: string;
+    } | undefined, options?: ai.ChatRequestOptions) => Promise<void>;
+    resumeStream: (options?: ai.ChatRequestOptions) => Promise<void>;
+    addToolOutput: ai.ChatAddToolOutputFunction<UIMessage<unknown, ai.UIDataTypes, ai.UITools>>;
+    addToolApprovalResponse: ai.ChatAddToolApproveResponseFunction;
+    clearError: () => void;
+};
+
+interface ChatInputProps {
+    onSubmit: (text: string) => void;
+    disabled?: boolean;
+    placeholder?: string;
+    rows?: number;
+    /** Enable the dictation mic button (Web Speech API). Default `true`. */
+    enableSpeech?: boolean;
+    /** BCP-47 locale for dictation. Default `en-US`. */
+    speechLang?: string;
+    /** Label/content for the send button. Default `"Send"`. */
+    sendLabel?: React.ReactNode;
+    /** Wrapper class. The component ships no styles of its own. */
+    className?: string;
+    textareaClassName?: string;
+    sendButtonClassName?: string;
+    micButtonClassName?: string;
+    /**
+     * Custom mic affordance. Receives `isListening`; return any node. When
+     * omitted a plain text button ("Speak" / "Stop") is rendered.
+     */
+    renderMic?: (state: {
+        isListening: boolean;
+    }) => React.ReactNode;
+}
+/**
+ * Styling-agnostic chat composer. Enter submits, Shift+Enter inserts a
+ * newline. Optional dictation streams interim transcripts into the draft
+ * and commits finalized chunks. No design-system or icon-library deps —
+ * style it entirely through the `*ClassName` props.
+ */
+declare function ChatInput({ onSubmit, disabled, placeholder, rows, enableSpeech, speechLang, sendLabel, className, textareaClassName, sendButtonClassName, micButtonClassName, renderMic, }: ChatInputProps): react_jsx_runtime.JSX.Element;
+
+/** A tool UI part on a `UIMessage` — a static `tool-*` part or the `dynamic-tool` part. */
+type AnyToolUIPart = ToolUIPart | DynamicToolUIPart;
+type RenderToolPartFn = (part: AnyToolUIPart, key: string) => React.ReactNode;
+/** Render a run of consecutive tool parts as one block (e.g. a collapsible tool group). */
+type RenderToolGroupFn = (parts: AnyToolUIPart[], key: string) => React.ReactNode;
+/** Render a message's text — pass a markdown renderer (e.g. `AgentMarkdown`) here if desired. */
+type RenderTextFn = (text: string, ctx: {
+    isStreaming: boolean;
+}) => React.ReactNode;
+/** Server-aggregated usage for an assistant turn, shown as a small inline line. */
+interface MessageUsageInfo {
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number;
+}
+interface MessageItemClassNames {
+    root?: string;
+    /** Resolved per role so user/assistant/system bubbles can differ. */
+    byRole?: Partial<Record<UIMessage['role'], string>>;
+    text?: string;
+    /** The action row under the bubble (copy / fork / regenerate / usage / timestamp). */
+    actions?: string;
+    actionButton?: string;
+    usage?: string;
+    timestamp?: string;
+    editTextarea?: string;
+    editActions?: string;
+}
+interface MessageItemProps {
+    message: UIMessage;
+    renderToolPart?: RenderToolPartFn;
+    /** Takes precedence over `renderToolPart` for a run of consecutive tool parts. */
+    renderToolGroup?: RenderToolGroupFn;
+    renderText?: RenderTextFn;
+    classNames?: MessageItemClassNames;
+    /** Marks the in-flight assistant bubble (e.g. for a caret animation / deferred markdown render). */
+    isStreaming?: boolean;
+    /** User bubble gets a pencil → inline textarea; submitting calls back with the new text. */
+    editable?: boolean;
+    onEditSubmit?: (newText: string) => void | Promise<void>;
+    /** Assistant bubble gets a "Regenerate" affordance. */
+    regeneratable?: boolean;
+    onRegenerate?: () => void | Promise<void>;
+    /** When provided, a "Fork" affordance calls back with this message's id. */
+    onFork?: (uiMessageId: string) => void | Promise<void>;
+    /** Server-aggregated usage for this assistant turn (cost + tokens line). */
+    usage?: MessageUsageInfo | null;
+    /** ISO timestamp of the persisted message; rendered as a relative-time line when set. */
+    createdAt?: string | null;
+}
+/**
+ * Styling-agnostic renderer for a single v7 `UIMessage`. Ports flip's full chat-item UX —
+ * copy, fork, regenerate, inline edit-and-resubmit, usage line, relative timestamp, and tool
+ * grouping — but with ALL styling left to `classNames` and every action surfaced as a callback,
+ * so no design-system / icon / date library is pulled in (relative time uses Intl.RelativeTimeFormat).
+ */
+declare function MessageItem({ message, renderToolPart, renderToolGroup, renderText, classNames, isStreaming, editable, onEditSubmit, regeneratable, onRegenerate, onFork, usage, createdAt, }: MessageItemProps): react_jsx_runtime.JSX.Element;
+/**
+ * "just now" within ±10s (server `created_at` can land a few ms ahead of the client clock), a
+ * relative phrase up to a week, then a calendar date. Uses Intl.RelativeTimeFormat — no date-fns.
+ */
+declare function formatRelativeTime(date: Date): string;
+
+type ChatStatus = 'ready' | 'submitted' | 'streaming' | 'error';
+interface MessageListClassNames {
+    root?: string;
+    empty?: string;
+    loadEarlier?: string;
+    typing?: string;
+    error?: string;
+    errorRetry?: string;
+    followUps?: string;
+    followUpChip?: string;
+    message?: MessageItemClassNames;
+}
+interface MessageListProps {
+    messages: UIMessage[];
+    status: ChatStatus;
+    renderToolPart?: RenderToolPartFn;
+    renderToolGroup?: RenderToolGroupFn;
+    renderText?: RenderTextFn;
+    /** When set, every message gets a "Fork" affordance calling back with its id. */
+    onFork?: (uiMessageId: string) => void | Promise<void>;
+    /** User messages get an inline edit-and-resubmit affordance. */
+    editable?: boolean;
+    onEditSubmit?: (uiMessageId: string, newText: string) => void | Promise<void>;
+    /** The last assistant message gets a "Regenerate" affordance. */
+    regeneratable?: boolean;
+    onRegenerate?: (uiMessageId: string) => void | Promise<void>;
+    /** Per-message resolvers for the usage line and the persisted timestamp. */
+    getUsage?: (message: UIMessage) => MessageUsageInfo | null;
+    getCreatedAt?: (message: UIMessage) => string | null;
+    /** Shown (with example/follow-up chips) when idle and empty. */
+    emptyState?: React.ReactNode;
+    /** Node rendered while waiting for the first assistant token. */
+    typingIndicator?: React.ReactNode;
+    /** AI-generated follow-up prompts under the last assistant message. */
+    followUps?: string[] | null;
+    onFollowUpClick?: (text: string) => void;
+    /** Last turn's error — paired with `onRetry`, renders a retry banner. */
+    error?: Error | null;
+    onRetry?: () => void | Promise<void>;
+    classNames?: MessageListClassNames;
+}
+/**
+ * Styling-agnostic message list. Keeps the proven UX — windowed render
+ * with "load earlier", a typing indicator, an inline error+retry banner,
+ * and follow-up chips — but ships no styles: drive everything through
+ * `classNames` and the `emptyState`/`typingIndicator` slots.
+ */
+declare function MessageList({ messages, status, renderToolPart, renderToolGroup, renderText, onFork, editable, onEditSubmit, regeneratable, onRegenerate, getUsage, getCreatedAt, emptyState, typingIndicator, followUps, onFollowUpClick, error, onRetry, classNames, }: MessageListProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Languages the dictation mic offers. The Web Speech API expects a
+ * BCP-47 tag and does NOT auto-detect — the engine forces incoming
+ * audio onto the phonemes of whatever `recognition.lang` is set to, so
+ * the host app picks the locale explicitly.
+ */
+interface SpeechLanguage {
+    /** BCP-47 tag fed straight into `SpeechRecognition.lang`. */
+    tag: string;
+    /** Human label for a dropdown. */
+    label: string;
+}
+declare const DEFAULT_SPEECH_LANG = "en-US";
+declare const SPEECH_LANGUAGES: ReadonlyArray<SpeechLanguage>;
+/**
+ * Recover the last picked language from localStorage (sync — safe at
+ * `useState` init). Falls back to the default if nothing's stored or the
+ * stored tag isn't in the offered list.
+ */
+declare function loadStoredSpeechLang(): string;
+declare function persistSpeechLang(tag: string): void;
+
+interface UseSpeechRecognitionOptions {
+    lang?: string;
+    onFinalTranscript: (text: string) => void;
+    onInterimTranscript?: (text: string) => void;
+}
+interface SpeechRecognitionHook {
+    isSupported: boolean;
+    isListening: boolean;
+    start(): void;
+    stop(): void;
+}
+/**
+ * Tiny wrapper around the Web Speech API. `start()` opens the mic and
+ * streams interim transcripts via `onInterimTranscript`; on a finalized
+ * chunk it fires `onFinalTranscript`. `isSupported` is false where the
+ * API is missing (e.g. Firefox) — callers should hide the mic button.
+ */
+declare function useSpeechRecognition({ lang, onFinalTranscript, onInterimTranscript, }: UseSpeechRecognitionOptions): SpeechRecognitionHook;
+
+export { AgentChatTransport, type AgentChatTransportOptions, AgentClient, type AgentClientOptions, AgentHttpError, type AgentStreamMeta, type AnyToolUIPart, type CancelResult, ChatInput, type ChatInputProps, type ChatStatus, DEFAULT_SPEECH_LANG, MessageItem, type MessageItemClassNames, type MessageItemProps, MessageList, type MessageListClassNames, type MessageListProps, type MessageUsageInfo, type PersonaCatalogEntry, type QuotaToday, type RenderTextFn, type RenderToolGroupFn, type RenderToolPartFn, SPEECH_LANGUAGES, type SpeechLanguage, type SpeechRecognitionHook, type UseAgentChatOptions, type UseSpeechRecognitionOptions, formatRelativeTime, loadStoredSpeechLang, persistSpeechLang, useAgentChat, useSpeechRecognition };