@love-moon/app-sdk 0.3.2

package/dist/react/index.d.ts

@@ -0,0 +1,364 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * Message: one entry in a task's chat transcript.
+ *
+ * Roles:
+ *  - 'user'      — message sent by the user (or the SDK on their behalf).
+ *  - 'sdk'       — message sent by an SDK / CLI / app integration (still
+ *                  appears in the chat as a user-side bubble).
+ *  - 'assistant' — AI reply.
+ *  - 'system'    — system-emitted notice (rare; renders muted).
+ *
+ * `role` is intentionally open-vocabulary; new backend roles render as
+ * a generic bubble.
+ */
+interface Message {
+    id: string;
+    taskId: string;
+    role: MessageRole | string;
+    content: string;
+    metadata: Record<string, unknown> | null;
+    attachments: Attachment[];
+    createdAt: string;
+}
+type MessageRole = 'user' | 'sdk' | 'assistant' | 'system';
+interface Attachment {
+    id: string;
+    filename: string;
+    mimeType: string;
+    sizeBytes: number;
+    /** Resolvable URL or relative path the host must turn into a fetchable URL. */
+    url: string;
+}
+interface SendMessageInput {
+    content: string;
+    /** Idempotency key. When omitted, the SDK auto-generates a UUID. */
+    clientRequestId?: string;
+    metadata?: Record<string, unknown>;
+    /** Optional attachments to include with this message; must be pre-uploaded. */
+    attachmentIds?: string[];
+    /** Role override; defaults to 'sdk'. */
+    role?: MessageRole;
+}
+
+/**
+ * Runtime status pushed by the daemon while a task is in progress.
+ * Mirrors `task_runtime_status` envelope on /ws/app.
+ */
+interface RuntimeStatus {
+    taskId: string;
+    /** High-level phase: 'idle' | 'thinking' | 'tool_call' | 'awaiting_user' | 'done'. */
+    state: RuntimeState;
+    phase?: string | null;
+    source?: string | null;
+    /** Short status line shown next to the AI avatar ("Reading file X..."). */
+    statusLine?: string | null;
+    /** Final status line shown when the reply finishes. */
+    statusDoneLine?: string | null;
+    replyPreview?: string | null;
+    replyTo?: string | null;
+    replyInProgress?: boolean;
+    backend?: string | null;
+    threadId?: string | null;
+    daemon?: string | null;
+    pid?: number | null;
+    sessionId?: string | null;
+    sessionFilePath?: string | null;
+    tokenUsagePercent?: number | null;
+    contextUsagePercent?: number | null;
+    createdAt?: string | null;
+}
+type RuntimeState = 'idle' | 'thinking' | 'tool_call' | 'awaiting_user' | 'done' | string;
+
+/**
+ * ChatEvent: the minimal set of events the chat widget needs to render.
+ *
+ * This is intentionally a small union — the widget should not have to
+ * pattern-match dozens of envelope types. The default REST/WS adapter
+ * funnels raw `/ws/app` envelopes into ChatEvents; custom adapters can do the
+ * same translation against any wire format.
+ */
+/**
+ * Error shape carried inside `task_failed` ChatEvents and `error`
+ * StreamReplyDeltas.
+ *
+ * `details` and `cause` are optional, free-form passthroughs of the original
+ * SDK error's structured fields — useful for surfacing request IDs / server
+ * payloads in host UIs without depending on the SDK error class directly.
+ */
+interface ChatEventError {
+    code: string;
+    message: string;
+    details?: unknown;
+    cause?: unknown;
+}
+type ChatEvent = {
+    type: 'message_appended';
+    message: Message;
+} | {
+    type: 'message_updated';
+    message: Message;
+} | {
+    type: 'runtime_status';
+    status: RuntimeStatus;
+} | {
+    type: 'task_finished';
+    taskId: string;
+} | {
+    type: 'task_failed';
+    taskId: string;
+    error: ChatEventError;
+} | {
+    type: 'connection_state';
+    state: 'connected' | 'reconnecting' | 'offline';
+};
+
+/**
+ * ChatAdapter: the contract between the React widget and *something* that
+ * can talk to a Conductor-shaped backend. The widget calls these methods;
+ * implementations decide how to translate to HTTP / WS / GraphQL / in-process
+ * calls.
+ *
+ * The default implementation `createRestAdapter` (in `/react`) talks to a
+ * BFF that mirrors Conductor's REST shape. Hosts using a custom wire format
+ * just implement this interface directly.
+ */
+interface ChatAdapter {
+    fetchHistory(taskId: string, opts?: {
+        beforeId?: string;
+        limit?: number;
+        signal?: AbortSignal;
+    }): Promise<{
+        messages: Message[];
+        hasMoreBefore: boolean;
+        oldestMessageId: string | null;
+    }>;
+    subscribe(taskId: string, handler: (event: ChatEvent) => void): {
+        unsubscribe(): void;
+    };
+    sendMessage(taskId: string, input: SendMessageInput): Promise<Message>;
+    interrupt(taskId: string, opts: {
+        targetReplyTo: string;
+    }): Promise<void>;
+    /** Optional. Adapters that don't support attachments may omit. */
+    uploadAttachment?(taskId: string, file: File | Blob, opts?: {
+        signal?: AbortSignal;
+        filename?: string;
+    }): Promise<{
+        id: string;
+        url: string;
+    }>;
+}
+
+interface ChatViewProps {
+    taskId: string;
+    adapter: ChatAdapter;
+    /** i18n strings; falls back to English. */
+    labels?: Partial<ChatViewLabels>;
+    /** Inline theme overrides. Maps to CSS variables on the root element. */
+    theme?: ChatViewTheme;
+    /** Force layout regardless of viewport. Default 'auto'. */
+    layout?: 'desktop' | 'mobile' | 'auto';
+    /**
+     * Whether to show "via {appDisplayName}" chip on bubbles with audit origin.
+     * Default `false`. The main Conductor app, which renders other users'
+     * app-created messages, sets this to `true`. Third-party hosts embedding
+     * the widget in their own app should leave it `false` to avoid the
+     * "via <self>" self-reference loop.
+     */
+    showAppOriginChip?: boolean;
+    onError?: (error: unknown) => void;
+    /** Extra className applied to the root container. */
+    className?: string;
+    /** Disable send/interact (e.g. when task is read-only). */
+    readOnly?: boolean;
+}
+interface ChatViewLabels {
+    statusThinking: string;
+    statusToolCall: string;
+    statusAwaitingUser: string;
+    statusDone: string;
+    inputPlaceholder: string;
+    send: string;
+    interrupt: string;
+    restart: string;
+    loadEarlier: string;
+}
+interface ChatViewTheme {
+    accent?: string;
+    background?: string;
+    bubbleUser?: string;
+    bubbleAssistant?: string;
+    /** Arbitrary CSS variable override (key without `--` prefix). */
+    [cssVarKey: string]: string | undefined;
+}
+declare function ChatView(props: ChatViewProps): react_jsx_runtime.JSX.Element;
+
+interface MessageListProps {
+    labels: ChatViewLabels;
+}
+declare function MessageList({ labels }: MessageListProps): react_jsx_runtime.JSX.Element;
+
+interface MessageInputProps {
+    labels: ChatViewLabels;
+    /** Disable the send button (useful while a turn is in progress). */
+    disabled?: boolean;
+}
+declare function MessageInput({ labels, disabled }: MessageInputProps): react_jsx_runtime.JSX.Element;
+
+interface RuntimeStatusBarProps {
+    labels: ChatViewLabels;
+}
+declare function RuntimeStatusBar({ labels }: RuntimeStatusBarProps): react_jsx_runtime.JSX.Element;
+
+interface ChatState {
+    messages: Message[];
+    /** Optimistically inserted, awaiting server echo. Keyed by clientRequestId. */
+    pendingByClientId: Record<string, Message>;
+    runtime: RuntimeStatus | null;
+    connectionState: 'connected' | 'reconnecting' | 'offline';
+    hasMoreBefore: boolean;
+    oldestMessageId: string | null;
+    loadingHistory: boolean;
+    error: ChatError | null;
+    /** ID of the latest assistant reply, used for interrupt targeting. */
+    latestReplyId: string | null;
+}
+/**
+ * Error captured into chat state. Carries the structured fields from
+ * `ConductorAppError` and from `ChatEventError` (task_failed envelopes) so
+ * the host UI can surface request IDs, server payloads, and the original
+ * cause without depending on the SDK error class directly.
+ *
+ * `cause` is also carried for parity with `ChatEventError` — terminal errors
+ * surfaced via WS (e.g. iterator-synthesised task_failed) include an `Error`
+ * instance in `cause` so callers walking the cause chain recover the stack.
+ */
+interface ChatError {
+    code: string;
+    message: string;
+    status?: number;
+    requestId?: string;
+    details?: unknown;
+    cause?: unknown;
+}
+interface ChatContextValue {
+    state: ChatState;
+    taskId: string;
+    adapter: ChatAdapter;
+    send: (content: string, opts?: {
+        metadata?: Record<string, unknown>;
+    }) => Promise<void>;
+    interrupt: () => Promise<void>;
+    loadEarlier: () => Promise<void>;
+}
+declare function useChat(): ChatContextValue;
+interface ChatProviderProps {
+    taskId: string;
+    adapter: ChatAdapter;
+    onError?: (error: unknown) => void;
+    children: ReactNode;
+}
+declare function ChatProvider(props: ChatProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * createRestAdapter: default `ChatAdapter` that talks to a host BFF exposing
+ * Conductor-shaped REST endpoints + an SSE event stream.
+ *
+ * Expected BFF surface (all relative to `baseUrl`, all returning JSON):
+ *
+ *   GET  /tasks/:taskId/messages?pagination=1&limit=N&before_id=...
+ *        → { messages, pagination: { has_more_before, oldest_message_id } }
+ *   POST /tasks/:taskId/messages
+ *        body: { content, role?, clientRequestId?, metadata? }
+ *        → Message
+ *   POST /tasks/:taskId/interrupt
+ *        body: { target_reply_to }
+ *        → 200
+ *   GET  /tasks/:taskId/events
+ *        → text/event-stream emitting `data: <ChatEvent JSON>\n\n`
+ *
+ * Auth: optionally a Bearer token via `authToken` (string or async fn) sent
+ * on REST calls. Cookies are honored by default via `credentials: 'include'`
+ * (configurable). EventSource doesn't support custom headers in the
+ * standard browser API — for token-based SSE auth, hosts should put the
+ * token in the URL or rely on cookies.
+ */
+
+interface RestAdapterOptions {
+    /** BFF base URL (relative or absolute), e.g. `/api/conductor`. */
+    baseUrl: string;
+    /** Bearer token (string or async provider). Optional — omit for cookie-based auth. */
+    authToken?: string | (() => Promise<string>);
+    /**
+     * Whether to send credentials (cookies) for REST + SSE. Defaults to
+     * 'include' (assume same-origin BFF or CORS configured to allow creds).
+     */
+    credentials?: RequestCredentials;
+    /** Override fetch (SSR, testing). Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Override EventSource constructor. Lets hosts inject `eventsource` polyfill
+     * for environments without native EventSource (Node-side rendering).
+     * Defaults to `globalThis.EventSource`.
+     */
+    eventSource?: typeof globalThis.EventSource;
+    /** Per-request timeout in ms. Default 30_000. */
+    timeoutMs?: number;
+}
+declare function createRestAdapter(options: RestAdapterOptions): ChatAdapter;
+
+/**
+ * Task: a single AI conversation within a project.
+ *
+ * Mirrors the shape returned by Conductor's `/api/tasks/[taskId]` REST endpoint
+ * (camelCase normalized). All fields are present after a successful read; the
+ * `null`-able fields reflect cases where the backend hasn't populated them yet
+ * (e.g. a task created via SDK before its daemon picks it up).
+ */
+interface Task {
+    id: string;
+    projectId: string;
+    title: string;
+    status: TaskStatus;
+    /** Backend execution engine ("claude_code" / "codex" / etc.) or null when not selected yet. */
+    backendType: string | null;
+    /** AI session id assigned by the daemon; null until the daemon attaches. */
+    sessionId: string | null;
+    sessionFilePath: string | null;
+    /** ISO 8601 timestamps. Always present after the task is persisted. */
+    createdAt: string;
+    updatedAt: string;
+}
+type TaskStatus = 'pending' | 'running' | 'finished' | 'failed' | 'cancelled' | string;
+
+/**
+ * ConductorAppError: every error thrown out of the SDK is one of these.
+ * Callers can `if (err instanceof ConductorAppError) switch (err.code)`.
+ *
+ * `code` is open-vocabulary for forward compat; the SDK promises to never
+ * remove existing codes, only add new ones, and to bump the minor version
+ * when a new code is introduced.
+ */
+declare class ConductorAppError extends Error {
+    readonly name = "ConductorAppError";
+    readonly code: ConductorErrorCode | string;
+    readonly status?: number;
+    readonly details?: unknown;
+    readonly requestId?: string;
+    constructor(args: {
+        code: ConductorErrorCode | string;
+        message: string;
+        status?: number;
+        details?: unknown;
+        requestId?: string;
+        cause?: unknown;
+    });
+}
+type ConductorErrorCode = 'unauthorized' | 'forbidden' | 'token_revoked' | 'invalid_input' | 'project_not_found' | 'task_not_found' | 'message_not_found' | 'daemon_offline' | 'workspace_path_conflict' | 'binding_validation_failed' | 'task_not_running' | 'task_type_not_messageable' | 'task_type_not_interruptible' | 'task_fire_owner_offline' | 'network_error' | 'timeout' | 'rate_limited' | 'server_error' | 'subscribe_failed' | 'stream_aborted';
+/** Helper: type-guard for callers that don't want `instanceof`. */
+declare function isConductorAppError(error: unknown): error is ConductorAppError;
+
+export { type Attachment, type ChatAdapter, type ChatEvent, ChatProvider, type ChatState, ChatView, type ChatViewLabels, type ChatViewProps, type ChatViewTheme, ConductorAppError, type Message, MessageInput, MessageList, type MessageRole, type RestAdapterOptions, type RuntimeState, type RuntimeStatus, RuntimeStatusBar, type SendMessageInput, type Task, type TaskStatus, createRestAdapter, isConductorAppError, useChat };