onin-sdk 1.3.0

package/README.md

@@ -0,0 +1,117 @@
+# Onin Plugin SDK
+
+Onin 插件开发 SDK，提供完整的 API 支持。
+
+## 安装
+
+```bash
+npm install onin-plugin-sdk
+```
+
+## 快速开始
+
+```typescript
+import { command, notification, storage } from 'onin-plugin-sdk';
+
+// 注册动态命令
+await command.register({
+  code: 'hello-world',
+  name: 'Hello World',
+  keywords: [{ name: 'hello' }],
+});
+
+// 处理命令执行
+await command.handle((code, args) => {
+  if (code === 'hello-world') {
+    notification.show({
+      title: 'Hello!',
+      body: 'Welcome to Onin Plugin SDK',
+    });
+  }
+});
+```
+
+## API 概览
+
+### Command API
+
+```typescript
+// 动态注册命令
+await command.register({
+  code: 'my-command',
+  name: '我的命令',
+  keywords: [{ name: '关键词' }],
+  matches: [{ type: 'text', name: '文本匹配', min: 1 }],
+});
+
+// 处理命令执行
+await command.handle((code, args) => {
+  console.log('收到命令:', code, args);
+});
+
+// 移除动态命令
+await command.remove('my-command');
+```
+
+### Notification API
+
+```typescript
+await notification.show({
+  title: '标题',
+  body: '内容',
+});
+```
+
+### Storage API
+
+```typescript
+await storage.setItem('key', { data: 'value' });
+const value = await storage.getItem('key');
+await storage.removeItem('key');
+```
+
+### HTTP API
+
+```typescript
+const response = await http.get('https://api.example.com/data');
+const data = await http.post('https://api.example.com/create', {
+  body: JSON.stringify({ name: 'test' }),
+});
+```
+
+### File System API
+
+```typescript
+await fs.writeFile('data.json', JSON.stringify(data));
+const content = await fs.readFile('data.json');
+const exists = await fs.exists('data.json');
+```
+
+### Dialog API
+
+```typescript
+const result = await dialog.confirm({
+  title: '确认',
+  message: '是否继续？',
+});
+
+const files = await dialog.open({
+  multiple: true,
+  filters: [{ name: 'Images', extensions: ['png', 'jpg'] }],
+});
+```
+
+### Clipboard API
+
+```typescript
+const text = await clipboard.readText();
+await clipboard.writeText('Hello');
+```
+
+## 类型定义
+
+所有 API 都有完整的 TypeScript 类型定义，编辑器会自动提供智能提示。
+
+## 更多文档
+
+查看 [完整 API 文档](./docs) 获取更多信息。

package/dist/api/__tests__/clipboard-metadata.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Test for clipboard metadata API v2 (Enhanced)
+ */
+export {};

package/dist/api/__tests__/lifecycle.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Lifecycle API Tests
+ */
+export {};

package/dist/api/ai.d.ts

@@ -0,0 +1,124 @@
+export type MessageContent = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image_url';
+    image_url: {
+        url: string;
+        detail?: 'auto' | 'low' | 'high';
+    };
+} | {
+    type: 'image_base64';
+    image_base64: string;
+    media_type?: string;
+};
+export interface ChatMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: MessageContent[];
+}
+export interface ChatRequest {
+    model?: string;
+    messages: ChatMessage[];
+    temperature?: number;
+    max_tokens?: number;
+    stream?: boolean;
+}
+export interface AIProvider {
+    id: string;
+    provider_type: string;
+    name: string;
+    display_name?: string | null;
+    base_url: string;
+    default_model: string | null;
+}
+export interface AICapabilities {
+    /** Whether the provider supports image inputs (both URL and base64) */
+    supports_images: boolean;
+    /** Whether the provider supports streaming responses */
+    supports_streaming: boolean;
+    /** Whether the provider supports function calling */
+    supports_function_calling: boolean;
+    /** Maximum context window in tokens */
+    max_context_tokens?: number;
+    /** Maximum number of images allowed per message (undefined = unlimited) */
+    max_images_per_message?: number;
+}
+export interface ModelInfo {
+    id: string;
+    name: string;
+    description?: string;
+    context_window?: number;
+}
+export interface ValidationResult {
+    valid: boolean;
+    message?: string;
+    models_count?: number;
+}
+export declare function createTextMessage(role: 'system' | 'user' | 'assistant', text: string): ChatMessage;
+export declare function createImageMessage(text: string, images: Array<string | {
+    url: string;
+    detail?: 'auto' | 'low' | 'high';
+}>): ChatMessage;
+/**
+ * Send a chat request to the configured AI provider.
+ * @param prompt - The user prompt or conversation history
+ * @param options - Additional options like model override
+ * @returns The AI response text
+ */
+declare function ask(prompt: string | ChatMessage[], options?: Partial<ChatRequest>): Promise<string>;
+/**
+ * Stream a chat response from the configured AI provider.
+ * @param prompt - The user prompt
+ * @param onChunk - Callback for each text chunk
+ * @param options - Additional options
+ * @returns Promise that resolves when stream is complete
+ */
+declare function stream(prompt: string | ChatMessage[], onChunk: (chunk: string) => void, options?: Partial<ChatRequest>): Promise<void>;
+/**
+ * Check if AI functionality is available (provider configured)
+ */
+declare function isAvailable(): Promise<boolean>;
+/**
+ * Get capabilities of the current active provider
+ */
+declare function getCapabilities(): Promise<AICapabilities | null>;
+/**
+ * List available models from the current active provider
+ */
+declare function listModels(): Promise<ModelInfo[]>;
+/**
+ * Validate a provider configuration.
+ * Note: Mainly for settings UI, generic plugins might not need this.
+ * @internal
+ */
+declare function validateProvider(baseUrl: string, apiKey?: string): Promise<ValidationResult>;
+/**
+ * Create a conversation manager for handling multi-turn chats
+ */
+declare function createConversation(systemPrompt?: string): Conversation;
+/**
+ * Helper class to manage conversation history
+ */
+export declare class Conversation {
+    private messages;
+    constructor(systemPrompt?: string);
+    addMessage(message: ChatMessage): void;
+    ask(prompt: string | ChatMessage, options?: Partial<ChatRequest>): Promise<string>;
+    stream(prompt: string | ChatMessage, onChunk: (chunk: string) => void, options?: Partial<ChatRequest>): Promise<void>;
+    getHistory(): ChatMessage[];
+    clear(): void;
+    getLastResponse(): string | null;
+}
+/**
+ * AI namespace for interacting with configured AI providers.
+ */
+export declare const ai: {
+    ask: typeof ask;
+    stream: typeof stream;
+    isAvailable: typeof isAvailable;
+    getCapabilities: typeof getCapabilities;
+    listModels: typeof listModels;
+    validateProvider: typeof validateProvider;
+    createConversation: typeof createConversation;
+};
+export {};

package/dist/api/clipboard.d.ts

@@ -0,0 +1,346 @@
+import { parseClipboardError } from '../utils/error-parser';
+/**
+ * Reads text content from the clipboard.
+ * @returns Promise that resolves to the text in the clipboard, or null if the clipboard is empty or doesn't contain text.
+ * @throws {PluginError} With code `CLIPBOARD_UNAVAILABLE` when clipboard is not accessible
+ * @throws {PluginError} With code `CLIPBOARD_ACCESS_DENIED` when permission is denied
+ * @throws {PluginError} With code `PERMISSION_DENIED` for general permission issues
+ * @example
+ * ```typescript
+ * async function getClipboardText() {
+ *   try {
+ *     const text = await clipboard.readText();
+ *     if (text) {
+ *       console.log('Clipboard text:', text);
+ *     } else {
+ *       console.log('Clipboard is empty or does not contain text.');
+ *     }
+ *   } catch (error) {
+ *     if (errorUtils.isErrorCode(error, 'CLIPBOARD_ACCESS_DENIED')) {
+ *       console.error('Clipboard access denied');
+ *     }
+ *   }
+ * }
+ * ```
+ * @since 0.1.0
+ * @group API
+ */
+export declare function readText(): Promise<string | null>;
+/**
+ * Writes the specified text to the clipboard.
+ * @param text - The text to write to the clipboard.
+ * @returns Promise that resolves when the operation is complete.
+ * @throws {PluginError} With code `CLIPBOARD_UNAVAILABLE` when clipboard is not accessible
+ * @throws {PluginError} With code `CLIPBOARD_ACCESS_DENIED` when permission is denied
+ * @throws {PluginError} With code `PERMISSION_DENIED` for general permission issues
+ * @example
+ * ```typescript
+ * async function setClipboardText() {
+ *   try {
+ *     await clipboard.writeText('Hello from the plugin!');
+ *     console.log('Text written to clipboard.');
+ *   } catch (error) {
+ *     console.error('Failed to write to clipboard:', error.message);
+ *   }
+ * }
+ * ```
+ * @since 0.1.0
+ * @group API
+ */
+export declare function writeText(text: string): Promise<void>;
+/**
+ * Reads image data from the clipboard and returns it as a Base64 string.
+ * @returns Promise that resolves to the Base64 encoded string of the image, or null if the clipboard is empty or doesn't contain an image.
+ * @throws {PluginError} With code `CLIPBOARD_FORMAT_UNSUPPORTED` when image format is not supported
+ * @throws {PluginError} With code `CLIPBOARD_UNAVAILABLE` when clipboard is not accessible
+ * @throws {PluginError} With code `CLIPBOARD_ACCESS_DENIED` when permission is denied
+ * @example
+ * ```typescript
+ * async function getClipboardImage() {
+ *   try {
+ *     const imageBase64 = await clipboard.readImage();
+ *     if (imageBase64) {
+ *       const imgElement = document.createElement('img');
+ *       imgElement.src = `data:image/png;base64,${imageBase64}`;
+ *       document.body.appendChild(imgElement);
+ *     } else {
+ *       console.log('Clipboard does not contain an image.');
+ *     }
+ *   } catch (error) {
+ *     if (errorUtils.isErrorCode(error, 'CLIPBOARD_FORMAT_UNSUPPORTED')) {
+ *       console.error('Image format not supported');
+ *     }
+ *   }
+ * }
+ * ```
+ * @since 0.1.0
+ * @group API
+ */
+export declare function readImage(): Promise<string | null>;
+/**
+ * Writes image data to the clipboard.
+ * @param imageData - The image's Base64 encoded string or Uint8Array data.
+ * @returns Promise that resolves when the operation is complete.
+ * @throws {PluginError} With code `CLIPBOARD_FORMAT_UNSUPPORTED` when image format is not supported
+ * @throws {PluginError} With code `CLIPBOARD_UNAVAILABLE` when clipboard is not accessible
+ * @throws {PluginError} With code `CLIPBOARD_ACCESS_DENIED` when permission is denied
+ * @example
+ * ```typescript
+ * async function setClipboardImage(base64Data: string) {
+ *   try {
+ *     await clipboard.writeImage(base64Data);
+ *     console.log('Image written to clipboard.');
+ *   } catch (error) {
+ *     console.error('Failed to write image to clipboard:', error.message);
+ *   }
+ * }
+ * ```
+ * @since 0.1.0
+ * @group API
+ */
+export declare function writeImage(imageData: string | Uint8Array): Promise<void>;
+/**
+ * Clears all content from the clipboard.
+ * @returns Promise that resolves when the operation is complete.
+ * @throws {PluginError} With code `CLIPBOARD_UNAVAILABLE` when clipboard is not accessible
+ * @throws {PluginError} With code `CLIPBOARD_ACCESS_DENIED` when permission is denied
+ * @example
+ * ```typescript
+ * async function clearClipboard() {
+ *   try {
+ *     await clipboard.clear();
+ *     console.log('Clipboard cleared.');
+ *   } catch (error) {
+ *     console.error('Failed to clear clipboard:', error.message);
+ *   }
+ * }
+ * ```
+ * @since 0.1.0
+ * @group API
+ */
+export declare function clear(): Promise<void>;
+/**
+ * Checks if the clipboard currently contains text content.
+ * @returns Promise that resolves to true if the clipboard contains text, false otherwise.
+ * @throws {PluginError} Same error conditions as {@link readText}
+ * @example
+ * ```typescript
+ * async function checkText() {
+ *   try {
+ *     if (await clipboard.hasText()) {
+ *       console.log('Clipboard has text.');
+ *       const text = await clipboard.readText();
+ *       console.log('Text content:', text);
+ *     } else {
+ *       console.log('Clipboard does not have text.');
+ *     }
+ *   } catch (error) {
+ *     console.error('Failed to check clipboard text:', error.message);
+ *   }
+ * }
+ * ```
+ * @since 0.1.0
+ * @group API
+ */
+export declare function hasText(): Promise<boolean>;
+/**
+ * Checks if the clipboard currently contains image content.
+ * @returns Promise that resolves to true if the clipboard contains an image, false otherwise.
+ * @throws {PluginError} Same error conditions as {@link readImage}
+ * @example
+ * ```typescript
+ * async function checkImage() {
+ *   try {
+ *     if (await clipboard.hasImage()) {
+ *       console.log('Clipboard has an image.');
+ *       const imageData = await clipboard.readImage();
+ *       console.log('Image data available:', !!imageData);
+ *     } else {
+ *       console.log('Clipboard does not have an image.');
+ *     }
+ *   } catch (error) {
+ *     console.error('Failed to check clipboard image:', error.message);
+ *   }
+ * }
+ * ```
+ * @since 0.1.0
+ * @group API
+ */
+export declare function hasImage(): Promise<boolean>;
+/**
+ * Copies text to the clipboard, alias for `writeText`.
+ * @param text - The text to copy.
+ * @returns Promise that resolves when the operation is complete.
+ * @throws {PluginError} Same error conditions as {@link writeText}
+ * @see {@link writeText} - For detailed error information
+ * @since 0.1.0
+ * @group API
+ */
+export declare function copy(text: string): Promise<void>;
+/**
+ * Pastes text content from the clipboard, alias for `readText`.
+ * @returns Promise that resolves to the text in the clipboard, or null if empty.
+ * @throws {PluginError} Same error conditions as {@link readText}
+ * @see {@link readText} - For detailed error information
+ * @since 0.1.0
+ * @group API
+ */
+export declare function paste(): Promise<string | null>;
+/**
+ * Clipboard content type enumeration
+ * @since 0.1.0
+ * @group Types
+ */
+export type ClipboardContentType = 'text' | 'image' | 'files' | 'empty';
+/**
+ * File information in clipboard
+ * @interface ClipboardFile
+ * @since 0.1.0
+ * @group Types
+ */
+export interface ClipboardFile {
+    /** Full file path */
+    path: string;
+    /** File name */
+    name: string;
+    /** Whether this is a directory */
+    is_directory: boolean;
+}
+/**
+ * Enhanced metadata about clipboard content including type, timestamp, and age information
+ * @interface ClipboardMetadata
+ * @since 0.1.0
+ * @group Types
+ */
+export interface ClipboardMetadata {
+    /** The text content in the clipboard, or null if no text */
+    text: string | null;
+    /** List of file paths if clipboard contains files, or null if no files */
+    files: ClipboardFile[] | null;
+    /** The type of content in the clipboard */
+    contentType: ClipboardContentType;
+    /**
+     * Unix timestamp (in seconds) when the clipboard content was last updated.
+     *
+     * Note: This timestamp is independent from the app's auto_clear_time_limit setting.
+     * Even if the app clears its internal state, this timestamp will still reflect
+     * when the system clipboard was actually modified.
+     *
+     * May be null only if:
+     * - Clipboard monitoring hasn't started yet
+     * - The clipboard has never been modified since app start
+     */
+    timestamp: number | null;
+    /**
+     * Age of the clipboard content in seconds (time since it was copied).
+     * Calculated as: current_time - timestamp.
+     * Will be null if timestamp is null.
+     */
+    age: number | null;
+}
+/**
+ * Gets comprehensive clipboard metadata including content type, timestamp, and age.
+ * This enhanced API provides detailed information about clipboard content:
+ * - Content type detection (text, image, files, or empty)
+ * - Text content (if available)
+ * - Image detection
+ * - File paths (if files were copied)
+ * - Timestamp when content was copied
+ * - Age in seconds (automatically calculated)
+ *
+ * @returns Promise that resolves to comprehensive clipboard metadata
+ * @throws {PluginError} Same error conditions as {@link readText}
+ * @example
+ * ```typescript
+ * // Basic usage - check content type and age
+ * const metadata = await clipboard.getMetadata();
+ * console.log('Content type:', metadata.contentType);
+ * console.log('Age:', metadata.age, 'seconds');
+ *
+ * // Handle different content types
+ * switch (metadata.contentType) {
+ *   case 'text':
+ *     console.log('Text:', metadata.text);
+ *     break;
+ *   case 'image':
+ *     console.log('Clipboard contains an image');
+ *     break;
+ *   case 'files':
+ *     console.log('Files:', metadata.files?.map(f => f.name));
+ *     break;
+ *   case 'empty':
+ *     console.log('Clipboard is empty');
+ *     break;
+ * }
+ *
+ * // Time-based filtering using age
+ * if (metadata.age !== null && metadata.age < 10) {
+ *   console.log('Content is fresh (less than 10 seconds old)');
+ *   await processContent(metadata);
+ * }
+ *
+ * // Check for image
+ * if (metadata.contentType === 'image') {
+ *   console.log('Image detected in clipboard');
+ * }
+ *
+ * if (metadata.files && metadata.files.length > 0) {
+ *   console.log('Files copied:', metadata.files.length);
+ *   metadata.files.forEach(file => {
+ *     console.log(`- ${file.name} (${file.is_directory ? 'dir' : 'file'})`);
+ *   });
+ * }
+ * ```
+ * @since 0.1.0
+ * @group API
+ */
+export declare function getMetadata(): Promise<ClipboardMetadata>;
+/**
+ * Clipboard API namespace - provides functions for interacting with the system clipboard
+ *
+ * Supports reading and writing text and image data to/from the system clipboard.
+ * All operations require appropriate permissions and handle various clipboard states gracefully.
+ *
+ * @namespace clipboard
+ * @version 0.1.0
+ * @since 0.1.0
+ * @group API
+ * @see {@link parseClipboardError} - For error handling utilities
+ * @example
+ * ```typescript
+ * import { clipboard } from 'onin-plugin-sdk';
+ *
+ * // Read text from clipboard
+ * const text = await clipboard.readText();
+ *
+ * // Write text to clipboard
+ * await clipboard.writeText('Hello World');
+ *
+ * // Check if clipboard has content
+ * if (await clipboard.hasText()) {
+ *   console.log('Clipboard has text content');
+ * }
+ *
+ * // Get metadata with timestamp
+ * const metadata = await clipboard.getMetadata();
+ * console.log('Content age:', Date.now() / 1000 - metadata.timestamp);
+ * ```
+ */
+export declare const clipboard: {
+    /** Core methods */
+    readText: typeof readText;
+    writeText: typeof writeText;
+    readImage: typeof readImage;
+    writeImage: typeof writeImage;
+    clear: typeof clear;
+    /** Check methods */
+    hasText: typeof hasText;
+    hasImage: typeof hasImage;
+    /** Metadata methods */
+    getMetadata: typeof getMetadata;
+    /** Convenience methods */
+    copy: typeof copy;
+    paste: typeof paste;
+    /** Error handling tools */
+    parseClipboardError: typeof parseClipboardError;
+};