@teodorruskvi/chat-core 0.1.2

package/dist/types/api.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Legacy API types - re-exported from concrete modules for convenience.
+ */
+export * from "./api/auth";
+export * from "./api/runs";
+export * from "./api/files";
+export * from "./api/common";

package/dist/types/core/context.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Legacy context types - re-exported from new structure
+ * TODO: Update imports to use new structure
+ */
+export * from '../core';

package/dist/types/core/models.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Legacy model types - re-exported from new structure.
+ * Keeps downstream imports working while the codebase migrates.
+ */
+export * from "../core";
+export type { PendingInterrupt, PregelTask, HydratedCheckpointSnapshot } from "../domain/persistence";

package/dist/types/core.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Core Context Types
+ * Infrastructure and context provider types
+ */
+import type { ChatMessage, GraphCommand, MessagePart } from "./domain/chat";
+import type { ProjectInfo, ThreadSummary } from "./api/runs";
+import type { PendingInterrupt } from "./domain/persistence";
+import type { ActiveRunContext, StreamEvent } from "./domain/streaming";
+export interface Envelope<T = unknown> {
+    data: T;
+}
+export type TokenListener = (token: string | null) => void;
+export declare function isEnvelope(x: unknown): x is Envelope<unknown>;
+export interface ApiContextValue {
+    token: string | null;
+    setToken: (token: string | null) => void;
+    chatApi: any;
+    authApi: any;
+    fileApi: any;
+    baseUrl: string;
+}
+export interface ApiConfig {
+    baseUrl?: string;
+    authBaseUrl?: string;
+    chatBaseUrl?: string;
+    apiKey?: string;
+    headers?: Record<string, string>;
+    getToken?: () => string | null;
+    uploadPath?: string;
+}
+export interface StreamSubmitPayload {
+    threadId?: string;
+    content?: string | ChatMessage;
+    attachments?: File[];
+    text?: string;
+    payload?: Record<string, unknown>;
+    contentParts?: MessagePart[];
+    edit?: boolean;
+    editingMessageId?: string | null;
+    originalMessageId?: string;
+    checkpointId?: string;
+    checkpointNs?: string | null;
+    config?: Record<string, unknown>;
+    project?: ProjectInfo | null;
+    command?: GraphCommand;
+}
+export interface StreamCallbacks {
+    onEvent?: (event: StreamEvent) => void;
+}
+export type PushUserOptions = {
+    attachments?: File[];
+    editingMessageId?: string | null;
+};
+export interface StreamContextValue {
+    submit: (input: StreamSubmitPayload, callbacks?: StreamCallbacks) => Promise<void>;
+    interrupt: ((value: unknown) => Promise<void>) | PendingInterrupt;
+    resume: (value?: unknown) => Promise<void>;
+    goto: (node: string, value?: unknown) => Promise<void>;
+    stop: () => void;
+    isStreaming: boolean;
+    error: string | null;
+    messages: ChatMessage[];
+    activeMessageId: string | null;
+    connectionState?: "idle" | "connecting" | "connected" | "reconnecting" | "error";
+    clearError: () => void;
+}
+export interface ThreadsContextValue {
+    threads: ThreadSummary[];
+    loading: boolean;
+    error: string | null;
+    createThread: (title?: string) => Promise<ThreadSummary>;
+    deleteThread: (threadId: string) => Promise<void>;
+    updateThread: (threadId: string, updates: Partial<ThreadSummary>) => Promise<void>;
+    refreshThreads: () => Promise<void>;
+    refreshSharedThreads: () => Promise<void>;
+    shareThread: (threadId: string, sharedWithUserId: string) => Promise<void>;
+    unshareThread: (threadId: string, shareId: string) => Promise<void>;
+    shareInFlight: boolean;
+    shareStatus: string | null;
+    clearShareStatus: () => void;
+}
+export interface ThreadStateContextValue {
+    threadId: string | null;
+    messages: ChatMessage[];
+    loading: boolean;
+    error: string | null;
+    metadata: ThreadStateMetadata;
+    pushUser: (content: string | ChatMessage) => ChatMessage;
+    reset: () => void;
+    clearError: () => void;
+}
+export interface ThreadStateMetadata {
+    assemblingMessageId: string | null;
+    checkpointId: string | null;
+    pendingInterrupts: PendingInterrupt[];
+    activeRun: ActiveRunContext | null;
+}

package/dist/types/domain/artifacts.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Artifact Domain Types
+ *
+ * Centralized type definitions for all artifact-related functionality.
+ * This is the single source of truth for artifact types across the application.
+ */
+import type { ReactNode } from "react";
+import type { ChatMessage } from "./chat";
+import type { TemporalMetadata, ProgressMetadata } from "./primitives";
+/**
+ * Base artifact interface attached to messages
+ */
+export interface MessageArtifact {
+    type: string;
+    index: number;
+    name?: string;
+    url?: string;
+    plots?: PlotData[];
+    [key: string]: unknown;
+}
+/**
+ * Metadata for artifact lifecycle tracking
+ */
+export interface ArtifactMetadata extends TemporalMetadata, ProgressMetadata {
+    id: string;
+    type: string;
+}
+/**
+ * Artifact with metadata attached (used during streaming)
+ */
+export interface ArtifactWithMetadata extends MessageArtifact {
+    metadata: ArtifactMetadata;
+}
+/**
+ * Plot-specific artifact data (charts, graphs, visualizations)
+ */
+export interface PlotData {
+    plotId?: string;
+    artifactId?: string;
+    contentBase64?: string;
+    url?: string;
+    format?: string;
+    mimeType?: string;
+}
+/**
+ * Preview data for rendering artifacts (images, plots, etc.)
+ */
+export interface ArtifactPreview {
+    src: string;
+    alt: string;
+    label?: string;
+}
+/**
+ * Props for artifact renderer components
+ */
+export interface ArtifactRendererProps {
+    artifact: MessageArtifact | null | undefined;
+    idx?: number;
+}
+/**
+ * Context for tool payload rendering
+ */
+export interface ToolPayloadBase {
+    value: unknown;
+    event: Record<string, unknown> | null;
+}
+export interface ToolDictPayload extends ToolPayloadBase {
+    kind: "dict";
+    data: Record<string, unknown>;
+}
+export interface ToolGenericPayload extends ToolPayloadBase {
+    kind: "generic";
+}
+export type ToolPayloadResult = ToolDictPayload | ToolGenericPayload;
+/**
+ * Context passed to tool artifact renderers
+ */
+export interface ToolArtifactRendererContext {
+    artifact: MessageArtifact | null;
+    message: ChatMessage;
+    toolPayload: ToolPayloadResult | null;
+    isStreaming: boolean;
+}
+/**
+ * Function signature for custom tool artifact renderers
+ */
+export type ToolArtifactRenderer = (ctx: ToolArtifactRendererContext) => ReactNode | null;
+/**
+ * Map of artifact type to custom renderer
+ */
+export type ToolArtifactRendererMap = {
+    default?: ToolArtifactRenderer;
+    [key: string]: ToolArtifactRenderer | undefined;
+};

package/dist/types/domain/chat.d.ts

@@ -0,0 +1,80 @@
+import { TemporalMetadata, Role } from "./primitives";
+/**
+ * Content Block Types (Aligned with backend/LangChain)
+ */
+export type MessagePartType = "text" | "image_url" | "file" | "tool_call";
+export interface TextPart {
+    type: "text";
+    text: string;
+}
+export interface ImagePart {
+    type: "image_url";
+    image_url: {
+        url: string;
+    };
+}
+export interface FilePart {
+    type: "file";
+    url?: string;
+    base64?: string;
+    mimeType?: string;
+    name?: string;
+    size?: number;
+}
+export interface ToolCall {
+    id: string;
+    name: string;
+    args: Record<string, any>;
+    artifact?: any;
+    status?: "running" | "completed" | "failed";
+    content?: string;
+}
+export interface InterruptAlternative {
+    id: string;
+    label: string;
+    value?: any;
+}
+export type MessagePart = TextPart | ImagePart | FilePart;
+/**
+ * Message object (Unified structure)
+ */
+export interface ChatMessage extends TemporalMetadata {
+    id: string;
+    role: Role;
+    content: MessagePart[];
+    name?: string;
+    model?: string;
+    toolCallId?: string;
+    toolCalls?: ToolCall[];
+    checkpointId?: string | null;
+    checkpointNs?: string | null;
+    toolStreaming?: boolean;
+    artifact?: any;
+    additionalKwargs?: Record<string, any>;
+    responseMetadata?: Record<string, any>;
+}
+/**
+ * Feature-specific request/command types
+ */
+export interface ChatRequest {
+    text?: string;
+    threadId?: string;
+    checkpointId?: string;
+    checkpointNs?: string;
+    attachments?: File[];
+    payload?: Record<string, any>;
+    config?: Record<string, any>;
+    command?: GraphCommand;
+    edit?: boolean;
+}
+export interface GraphCommand {
+    kind: "resume" | "goto";
+    value?: any;
+    node?: string;
+}
+export type StreamCommand = {
+    type: "stop";
+} | {
+    type: "submit";
+    request: ChatRequest;
+};

package/dist/types/domain/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Domain barrel
+ * Re-export domain models and primitives from a single entry point.
+ */
+export * from "./primitives";
+export * from "./chat";
+export * from "./artifacts";
+export * from "./streaming";
+export * from "./persistence";
+export * from "./tools";

package/dist/types/domain/messages.d.ts

@@ -0,0 +1,54 @@
+import type { ChatMessage, PendingInterrupt, StreamEvent } from "@/types";
+export interface MessagesState {
+    messages: ChatMessage[];
+    assemblingId: string | null;
+    lastCheckpointId: string | null;
+    lastCheckpointNs: string | null;
+    pendingInterrupt: PendingInterrupt;
+    messagesStreamMeta?: Record<string, {
+        lastSeq?: number | null;
+        lastText?: string;
+    }>;
+    values: Record<string, unknown>;
+}
+export type MessagesAction = {
+    type: "reset";
+    payload?: {
+        messages?: ChatMessage[];
+    };
+} | {
+    type: "seed";
+    payload: {
+        messages: ChatMessage[];
+        checkpointId?: string | null;
+        checkpointNs?: string | null;
+        pendingInterrupt?: PendingInterrupt;
+        values?: Record<string, unknown>;
+    };
+} | {
+    type: "prepend";
+    payload: {
+        messages: ChatMessage[];
+    };
+} | {
+    type: "user_message";
+    payload: {
+        message: ChatMessage;
+        editingMessageId?: string | null;
+    };
+} | {
+    type: "event";
+    payload: {
+        ev: StreamEvent;
+    };
+} | {
+    type: "batch";
+    payload: {
+        events: StreamEvent[];
+    };
+} | {
+    type: "interrupt_response";
+    payload: {
+        interruptId: string;
+    };
+};

package/dist/types/domain/persistence.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Persistence Domain Types
+ * Checkpoints, history, and data persistence
+ */
+import type { ChatMessage, InterruptAlternative } from "./chat";
+export interface HydratedCheckpointSnapshot {
+    checkpointId: string | null;
+    checkpointNs?: string | null;
+    threadId?: string | null;
+    messages?: ChatMessage[];
+    parentId?: string | null;
+    pendingWrites?: unknown[];
+    metadata?: {
+        step?: number;
+        source?: string | null;
+        [key: string]: unknown;
+    } | null;
+    createdAt: string;
+    interrupt?: PendingInterrupt;
+    tasks?: PregelTask[] | null;
+    next?: string | string[] | null;
+    parentConfig?: Record<string, unknown> | null;
+    values?: {
+        interrupts?: PendingInterrupt[];
+        [key: string]: unknown;
+    };
+    config?: {
+        stream_mode?: string[];
+        [key: string]: unknown;
+    } | null;
+}
+export interface PregelTask {
+    id?: string;
+    name?: string;
+    path?: string[];
+    parents?: string[];
+    interrupts?: PendingInterrupt[];
+    state?: unknown;
+    result?: unknown;
+    error?: string;
+    [key: string]: unknown;
+}
+export type PendingInterrupt = {
+    id: string;
+    value: unknown;
+    alternatives?: InterruptAlternative[];
+} | null;
+/**
+ * Interrupt Response Types
+ */
+export interface RespondToInterruptPayload {
+    approved: boolean;
+    value?: unknown;
+    id?: string;
+}
+export interface RespondToInterruptOptions {
+    threadId?: string;
+    checkpointId?: string;
+    checkpointNs?: string;
+    payload?: Record<string, unknown>;
+}
+export interface CheckpointIndex {
+    threadId: string;
+    checkpoints: Map<string, HydratedCheckpointSnapshot>;
+    currentIndex: number | null;
+    hydratedSnapshots: Map<string, HydratedCheckpointSnapshot>;
+}

package/dist/types/domain/primitives.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Domain Primitives
+ *
+ * Shared atoms used across chat, artifacts, and tools.
+ */
+/**
+ * ISO-8601 timestamp string
+ */
+export type Timestamp = string;
+/**
+ * Common message roles used across chat and tool events
+ */
+export type Role = "user" | "assistant" | "system" | "tool";
+/**
+ * Standard lifecycle states for streaming or long-running entities
+ */
+export type LifecycleStatus = "pending" | "in_progress" | "completed" | "failed";
+/**
+ * Timestamps attached to persisted entities
+ */
+export interface TemporalMetadata {
+    createdAt: Timestamp;
+    updatedAt?: Timestamp;
+}
+/**
+ * Progress/status metadata shared by artifacts and tool executions
+ */
+export interface ProgressMetadata {
+    status?: LifecycleStatus;
+    progress?: number;
+    error?: string;
+}
+/**
+ * Shared view modes for tool rendering
+ */
+export type ToolViewMode = "preview" | "expanded";
+/**
+ * Common identifiers attached to tool events
+ */

package/dist/types/domain/streaming.d.ts

@@ -0,0 +1,231 @@
+/**
+ * Streaming Domain Types
+ * Real-time streaming events and state (LangGraph-compatible).
+ */
+import type { ChatMessage, StreamSubmitPayload, StreamCallbacks } from "@/types";
+import type { HistoryPayload, ProjectInfo } from "../api/runs";
+export type UseChatStreamOptions = {
+    baseUrl?: string;
+    streamPath?: string;
+    token?: string;
+    headers?: Record<string, string>;
+    credentials?: RequestCredentials;
+    autoAppendAssistant?: boolean;
+    onEvent?: (event: StreamEvent) => void;
+    onError?: (error: Error) => void;
+    onAuthError?: (error: string) => void;
+    onConnectionError?: (error: string) => void;
+    onFinish?: (info: StreamFinishInfo) => void;
+    onThreadInfo?: (event: ThreadInfoEvent) => void;
+    onMetadataEvent?: (event: Extract<StreamEvent, {
+        type: "metadata";
+    }>) => void;
+    onCustomEvent?: (event: StreamEvent) => void;
+    onUpdateEvent?: (event: Extract<StreamEvent, {
+        type: "updates";
+    }>) => void;
+    onToolEnd?: (event: ToolEndEvent) => void;
+    onToolStart?: (event: ToolStartEvent) => void;
+    handleStateHistoryEvent?: (event: StateHistoryEvent) => void;
+    onHeartbeat?: (event: HeartbeatEvent) => void;
+    onToken?: (token: string) => void;
+};
+export interface UseStreamApi {
+    isStreaming: boolean;
+    error: string | null;
+    assistantText: string;
+    activeMessageId: string | null;
+    streamedMessages: Record<string, ChatMessage>;
+    lastCheckpointId: string | null;
+    lastSeq: number;
+    connected: boolean;
+    stream: (input: StreamSubmitPayload, callbacks?: StreamCallbacks) => Promise<void>;
+    stop: () => void;
+    clear: () => void;
+    setToken: (token: string | null) => void;
+    values: Record<string, unknown>;
+    interrupt: () => Promise<void>;
+    resume: () => Promise<void>;
+    goto: () => Promise<void>;
+    connectionState: "idle" | "connecting" | "connected" | "reconnecting" | "error";
+    messages: ChatMessage[];
+    submit: (input: StreamSubmitPayload, callbacks?: StreamCallbacks) => Promise<void>;
+}
+export type ActiveRunContext = {
+    runId?: string;
+    nodeId?: string;
+    threadId?: string | null;
+    isStreaming: boolean;
+    headers?: Record<string, string>;
+};
+export type StreamFinishInfo = {
+    lastSeq: number;
+    lastCheckpointId: string | null;
+    lastCheckpointNs: string | null;
+    lastStateHistory: HistoryPayload | null;
+};
+export type ToolEventIdentity = {
+    id?: string;
+    callId?: string;
+};
+export type ToolStartEvent = {
+    type: "tool.start";
+    args: Record<string, unknown>;
+    name?: string;
+    tool?: string;
+    seq?: number;
+    additionalKwargs?: Record<string, unknown>;
+} & ToolEventIdentity;
+export type ToolEndEvent = {
+    type: "tool.end";
+    content: string;
+    artifact?: unknown;
+    error?: string;
+    name?: string;
+    tool?: string;
+    seq?: number;
+    additionalKwargs?: Record<string, unknown>;
+} & ToolEventIdentity;
+export type ToolProgressEvent = {
+    type: "tool.progress";
+    content?: string;
+    id?: string;
+    callId?: string;
+    status?: string;
+    step?: string;
+    metadata?: Record<string, unknown>;
+    idx?: number;
+    seq?: number;
+    [key: string]: unknown;
+};
+export type ArtifactUpdateEvent = {
+    type: "artifact.update";
+    artifact_id: string;
+    partial_data?: Record<string, unknown>;
+    progress?: number;
+    status?: "pending" | "in_progress" | "completed" | "failed";
+    error?: string;
+};
+export type ToolStreamEvent = ToolStartEvent | ToolEndEvent | ArtifactUpdateEvent;
+export type MessageStreamEvent = ToolProgressEvent | {
+    type: "messages/partial";
+    messages: Array<{
+        content: string;
+        id: string;
+        type: string;
+        response_metadata?: Record<string, unknown>;
+    }>;
+};
+export type ThreadStreamEvent = {
+    type: "thread_info";
+    threadId: string;
+    title: string;
+    project?: ProjectInfo | null;
+    createdAt: string;
+    updatedAt: string;
+    messageCount: number;
+    lastMessage?: string | null;
+    created?: boolean | null;
+    ready?: boolean | null;
+    seq?: number | null;
+} | {
+    type: "checkpoint";
+    checkpointId: string;
+    checkpointNs?: string | null;
+};
+export type ThreadInfoEvent = Extract<ThreadStreamEvent, {
+    type: "thread_info";
+}>;
+export type SystemStreamEvent = {
+    type: "error";
+    message: string;
+    error_type?: string;
+    code?: string;
+} | {
+    type: "interrupt";
+    id: string;
+    value: any;
+    seq: number;
+} | {
+    type: "heartbeat";
+    timestamp: number;
+    seq: number;
+} | {
+    type: "cancelled";
+    reason?: string;
+    seq?: number;
+} | {
+    type: "custom";
+    data: unknown;
+    name?: string;
+    seq?: number;
+} | ({
+    type: "state_history";
+    seq?: number;
+} & HistoryPayload) | {
+    type: "metadata";
+    threadId?: string;
+    status?: string;
+    runId?: string;
+} | {
+    type: "updates";
+    tools?: Record<string, unknown>;
+    [key: string]: unknown;
+} | {
+    type: "values";
+    [key: string]: unknown;
+} | {
+    type: "token";
+    token: string;
+};
+export type HeartbeatEvent = Extract<SystemStreamEvent, {
+    type: "heartbeat";
+}>;
+export type StateHistoryEvent = Extract<SystemStreamEvent, {
+    type: "state_history";
+}>;
+export type StreamEvent = MessageStreamEvent | ToolStreamEvent | ThreadStreamEvent | SystemStreamEvent;
+export interface StreamEventHandlers {
+    onConnectionError?: (error: string) => void;
+    onError?: (error: string) => void;
+    onOpen?: (data: {
+        threadId: string | null;
+        created: boolean;
+    }) => void;
+    onGap?: (gap: {
+        from: number;
+        to: number;
+    }) => void;
+    onUpdateEvent?: (event: Extract<StreamEvent, {
+        type: "updates";
+    }>) => void;
+    onCustomEvent?: (event: Extract<StreamEvent, {
+        type: "custom";
+    }>) => void;
+    onMetadataEvent?: (event: Extract<StreamEvent, {
+        type: "metadata";
+    }>) => void;
+    onClosed?: (info: {
+        reason: "complete" | "aborted" | "error";
+        lastSeq: number;
+        lastCheckpointId: string | null;
+        lastCheckpointNs: string | null;
+        lastStateHistory: HistoryPayload | null;
+        error?: string | null;
+    }) => void;
+    onFinish?: (info: StreamFinishInfo) => void;
+    onAuthError?: (error: string) => void;
+    onHeartbeat?: (event: HeartbeatEvent) => void;
+    onToolStart?: (event: ToolStartEvent) => void;
+    onToolEnd?: (event: ToolEndEvent) => void;
+    onToken?: (token: string) => void;
+    onThreadInfo?: (event: ThreadInfoEvent) => void;
+}
+export declare function isStreamEvent(obj: any): obj is StreamEvent;
+export declare function isToolEvent(obj: any): obj is ToolStreamEvent;
+export declare function isToolStartEvent(obj: any): obj is ToolStartEvent;
+export declare function isToolEndEvent(obj: any): obj is ToolEndEvent;
+export declare function isArtifactUpdateEvent(obj: any): obj is ArtifactUpdateEvent;
+export declare function isMessageStreamEvent(obj: any): obj is MessageStreamEvent;
+export declare function isThreadStreamEvent(obj: any): obj is ThreadStreamEvent;
+export declare function isSystemStreamEvent(obj: any): obj is SystemStreamEvent;