@yushaw/sanqian-chat 0.1.1 → 0.2.0

package/dist/main/index.d.ts

@@ -1,5 +1,218 @@
-import { BrowserWindow } from 'electron';
+import * as _yushaw_sanqian_sdk from '@yushaw/sanqian-sdk';
 import { SanqianSDK } from '@yushaw/sanqian-sdk';
+import { BrowserWindow } from 'electron';
+
+/**
+ * @yushaw/sanqian-chat Main - Facade Types
+ *
+ * Application-facing types that hide SDK implementation details.
+ * These provide a stable API even as the underlying SDK evolves.
+ */
+/**
+ * Application configuration for connecting to Sanqian
+ */
+interface AppConfig {
+    /** Unique application identifier (e.g., 'sanqian-notes') */
+    appName: string;
+    /** Application version string */
+    appVersion: string;
+    /** Display name shown in Sanqian UI */
+    displayName?: string;
+    /** Command to auto-launch this app */
+    launchCommand?: string;
+    /** Tools provided by this application */
+    tools?: AppToolDefinition[];
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * JSON Schema property definition
+ */
+interface AppJsonSchemaProperty {
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'null';
+    description?: string;
+    enum?: (string | number | boolean)[];
+    items?: AppJsonSchemaProperty;
+    properties?: Record<string, AppJsonSchemaProperty>;
+    required?: string[];
+    default?: unknown;
+}
+/**
+ * Tool definition for application-provided tools
+ */
+interface AppToolDefinition {
+    /** Tool name (without app prefix) */
+    name: string;
+    /** Tool description for LLM */
+    description: string;
+    /** JSON Schema for parameters */
+    parameters: {
+        type: 'object';
+        properties: Record<string, AppJsonSchemaProperty>;
+        required?: string[];
+    };
+    /** Async handler function */
+    handler: (args: Record<string, unknown>) => Promise<unknown>;
+}
+/**
+ * Agent configuration for private agents
+ */
+interface AppAgentConfig {
+    /** Agent ID (unique within this app) */
+    agentId: string;
+    /** Display name */
+    name: string;
+    /** Agent description */
+    description?: string;
+    /** System prompt */
+    systemPrompt?: string;
+    /** Enabled tool names (without app prefix) */
+    tools?: string[];
+}
+/**
+ * Embedding configuration from Sanqian
+ */
+interface AppEmbeddingConfig {
+    /** Whether embedding is available */
+    available: boolean;
+    /** Embedding API URL */
+    apiUrl?: string;
+    /** API key */
+    apiKey?: string;
+    /** Model name */
+    modelName?: string;
+    /** Embedding dimensions */
+    dimensions?: number;
+}
+/**
+ * Events emitted by SanqianAppClient
+ */
+type AppClientEvent = 'connected' | 'registered' | 'disconnected' | 'error' | 'tool_call';
+/**
+ * Event handler types
+ */
+interface AppClientEventHandlers {
+    connected: () => void;
+    registered: () => void;
+    disconnected: (reason: string) => void;
+    error: (error: Error) => void;
+    tool_call: (call: {
+        name: string;
+        arguments: Record<string, unknown>;
+    }) => void;
+}
+
+/**
+ * SanqianAppClient - Application client for connecting to Sanqian
+ *
+ * This is a Facade that wraps the SDK and provides:
+ * - Stable API that doesn't change when SDK internals change
+ * - Application-focused types and methods
+ * - Simplified configuration
+ *
+ * @example
+ * ```typescript
+ * import { SanqianAppClient } from '@yushaw/sanqian-chat/main'
+ *
+ * const client = new SanqianAppClient({
+ *   appName: 'my-app',
+ *   appVersion: '1.0.0',
+ *   tools: [...]
+ * })
+ *
+ * client.on('connected', () => console.log('Connected!'))
+ * await client.connect()
+ * ```
+ */
+declare class SanqianAppClient {
+    private sdk;
+    constructor(config: AppConfig);
+    /**
+     * Connect to Sanqian and register this application
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from Sanqian
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Check if connected to Sanqian
+     */
+    isConnected(): boolean;
+    /**
+     * Ensure SDK is ready (connects if needed, waits for registration)
+     */
+    ensureReady(): Promise<void>;
+    /**
+     * Request persistent connection (enables auto-reconnect)
+     * Call when a component needs the connection to stay alive
+     */
+    acquireReconnect(): void;
+    /**
+     * Release persistent connection request
+     * Call when a component no longer needs the connection
+     */
+    releaseReconnect(): void;
+    /**
+     * Create or update a private agent
+     * @returns The full agent ID (app_name:agent_id)
+     */
+    createAgent(config: AppAgentConfig): Promise<{
+        agentId: string;
+    }>;
+    /**
+     * Get embedding configuration from Sanqian
+     * @returns Embedding config or null if not available
+     */
+    getEmbeddingConfig(): Promise<AppEmbeddingConfig | null>;
+    /**
+     * Subscribe to client events
+     */
+    on<E extends AppClientEvent>(event: E, handler: AppClientEventHandlers[E]): this;
+    /**
+     * Remove all event listeners
+     */
+    removeAllListeners(): void;
+    /**
+     * Stream chat messages
+     */
+    chatStream(agentId: string, messages: Array<{
+        role: 'user' | 'assistant';
+        content: string;
+    }>, options?: {
+        conversationId?: string;
+    }): AsyncGenerator<_yushaw_sanqian_sdk.ChatStreamEvent>;
+    /**
+     * Send HITL (Human-in-the-Loop) response
+     */
+    sendHitlResponse(runId: string, response: _yushaw_sanqian_sdk.HitlResponse): void;
+    /**
+     * List conversations for an agent
+     */
+    listConversations(options: {
+        agentId: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        conversations: Array<_yushaw_sanqian_sdk.ConversationInfo>;
+        total: number;
+    }>;
+    /**
+     * Get conversation details
+     */
+    getConversation(conversationId: string, options?: {
+        messageLimit?: number;
+    }): Promise<_yushaw_sanqian_sdk.ConversationDetail>;
+    /**
+     * Delete a conversation
+     */
+    deleteConversation(conversationId: string): Promise<void>;
+    /**
+     * Get the underlying SDK instance
+     * @internal This is for internal use by other sanqian-chat components
+     */
+    _getSdk(): SanqianSDK;
+}
 
 /**
  * @yushaw/sanqian-chat Core Types
@@ -7,6 +220,69 @@ import { SanqianSDK } from '@yushaw/sanqian-sdk';
  * Re-exports SDK types + chat-specific types
  */
 
+type Locale = 'en' | 'zh';
+interface ChatUiStrings {
+    inputPlaceholder: string;
+    inputSend: string;
+    inputStop: string;
+    chat: string;
+    recentChats: string;
+    newChat: string;
+    selectConversation: string;
+    noHistory: string;
+    loadMore: string;
+    today: string;
+    yesterday: string;
+    delete: string;
+    dismiss: string;
+    close: string;
+    pin: string;
+    unpin: string;
+    conversationUntitled: string;
+    conversationDeleteConfirm: string;
+    messageThinking: string;
+    messageError: string;
+    messageLoading: string;
+    connectionConnecting: string;
+    connectionConnected: string;
+    connectionDisconnected: string;
+    connectionReconnecting: string;
+    connectionError: string;
+    steps: string;
+    executing: string;
+    thinking: string;
+    thinkingStreaming: string;
+    thinkingPaused: string;
+    hitlApprove: string;
+    hitlReject: string;
+    hitlSubmit: string;
+    hitlCancel: string;
+    hitlRememberChoice: string;
+    hitlRequiredField: string;
+    hitlTimeoutIn: string;
+    hitlSeconds: string;
+    hitlExecuteTool: string;
+    hitlToolLabel: string;
+    hitlArgsLabel: string;
+    hitlDefaultPrefix: string;
+    hitlEnterResponse: string;
+    hitlApprovalRequest: string;
+    hitlInputRequest: string;
+    hitlApprovalRequired: string;
+    hitlInputRequired: string;
+}
+type ChatThemeMode = 'light' | 'dark' | 'auto';
+type ChatFontSize = 'small' | 'normal' | 'large' | 'extra-large';
+interface ChatUiConfigSerializable {
+    logo?: string;
+    theme?: ChatThemeMode;
+    /** Font size scale: small (13px), normal (14px), large (16px), extra-large (18px) */
+    fontSize?: ChatFontSize;
+    accentColor?: string;
+    locale?: Locale;
+    strings?: Partial<ChatUiStrings>;
+    alwaysOnTop?: boolean;
+}
 type WindowPosition = 'center' | 'cursor' | 'remember' | {
     x: number;
     y: number;
@@ -16,9 +292,21 @@ interface FloatingWindowConfig {
     position?: WindowPosition;
     width?: number;
     height?: number;
+    /** Minimum window width (default: 320) */
+    minWidth?: number;
+    /** Minimum window height (default: 420) */
+    minHeight?: number;
     alwaysOnTop?: boolean;
     showInTaskbar?: boolean;
     theme?: 'light' | 'dark' | 'system';
+    /** Optional UI config for renderer (serializable) */
+    uiConfig?: ChatUiConfigSerializable;
+    /** Persist size/position across sessions (stored under ~/.sanqian-chat) */
+    rememberWindowState?: boolean;
+    /** Optional storage key to avoid conflicts between apps */
+    windowStateKey?: string;
+    /** Optional full path for window state file */
+    windowStatePath?: string;
 }
 
 /**
@@ -26,8 +314,16 @@ interface FloatingWindowConfig {
  */
 
 interface FloatingWindowOptions extends FloatingWindowConfig {
-    /** SDK instance getter */
-    getSdk: () => SanqianSDK | null;
+    /**
+     * AppClient instance getter (recommended)
+     * Use this instead of getSdk when using the Facade API
+     */
+    getClient?: () => SanqianAppClient | null;
+    /**
+     * SDK instance getter (legacy)
+     * @deprecated Use getClient instead
+     */
+    getSdk?: () => SanqianSDK | null;
     /** Agent ID getter */
     getAgentId: () => string | null;
     /** Path to preload script */
@@ -40,19 +336,38 @@ interface FloatingWindowOptions extends FloatingWindowConfig {
 declare class FloatingWindow {
     private window;
     private options;
-    private savedPosition;
+    private savedState;
+    private stateSaveTimer;
     private activeStreams;
+    private reconnectAcquired;
+    /**
+     * Get SDK instance from either getClient or getSdk
+     */
+    private static getSdkFromOptions;
     constructor(options: FloatingWindowOptions);
     private createWindow;
+    private getInitialBounds;
     private getInitialPosition;
+    private shouldPersistWindowState;
+    private shouldUseSavedState;
+    private getMinSize;
+    private getWindowStatePath;
+    private getResolvedUiConfig;
+    private loadWindowState;
+    private scheduleSaveWindowState;
+    private saveWindowState;
+    private getPercentFromBounds;
+    private getSavedBounds;
     private registerShortcut;
     private setupIpcHandlers;
     show(): void;
     hide(): void;
+    setAlwaysOnTop(alwaysOnTop: boolean): void;
+    isAlwaysOnTop(): boolean;
     toggle(): void;
     isVisible(): boolean;
     destroy(): void;
     getWindow(): BrowserWindow | null;
 }
 
-export { FloatingWindow, type FloatingWindowConfig, type FloatingWindowOptions, type WindowPosition };
+export { type AppAgentConfig, type AppClientEvent, type AppClientEventHandlers, type AppConfig, type AppEmbeddingConfig, type AppJsonSchemaProperty, type AppToolDefinition, type ChatUiConfigSerializable, FloatingWindow, type FloatingWindowConfig, type FloatingWindowOptions, SanqianAppClient, type WindowPosition };