onin-sdk 1.3.0

package/dist/api/command.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Command handler function type - defines the signature for handling incoming commands
+ * @param command - The command name to handle
+ * @param args - Arguments passed with the command
+ * @returns The result of the command execution (can be synchronous or asynchronous)
+ * @since 0.1.0
+ * @group Types
+ */
+export type CommandHandler = (command: string, args: any) => any | Promise<any>;
+/**
+ * Command keyword definition
+ * @interface CommandKeyword
+ * @since 0.2.0
+ */
+export interface CommandKeyword {
+    /** Keyword name */
+    name: string;
+    /** Keyword type: "prefix" | "fuzzy" | "exact" */
+    type?: string;
+}
+/**
+ * Command match definition for content-based matching
+ * @interface CommandMatchDefinition
+ * @since 0.2.0
+ */
+export interface CommandMatchDefinition {
+    /** Match type: "text" | "image" | "file" | "folder" */
+    type: 'text' | 'image' | 'file' | 'folder';
+    /** Match name */
+    name: string;
+    /** Match description */
+    description?: string;
+    /** Regular expression for text matching */
+    regexp?: string;
+    /** Minimum count */
+    min?: number;
+    /** Maximum count */
+    max?: number;
+    /** File extensions filter */
+    extensions?: string[];
+}
+/**
+ * Command definition for dynamic registration
+ * @interface CommandDefinition
+ * @since 0.2.0
+ */
+export interface CommandDefinition {
+    /** Unique command code */
+    code: string;
+    /** Display name */
+    name: string;
+    /** Command description */
+    description?: string;
+    /** Trigger keywords */
+    keywords?: CommandKeyword[];
+    /** Content match rules */
+    matches?: CommandMatchDefinition[];
+}
+/**
+ * For testing purposes - reset the registration state
+ * @internal
+ */
+export declare function _resetRegistrationState(): void;
+/**
+ * Registers a command handler to respond to command calls from the main application.
+ * Each plugin instance should call this function only once.
+ *
+ * The registered handler will receive all commands directed to this plugin and should
+ * implement appropriate routing and response logic. Commands are executed asynchronously
+ * and results are automatically sent back to the caller.
+ *
+ * @param handler - A function to handle received commands. It receives `command` and `args` as parameters.
+ * @returns Promise that resolves when the handler is successfully registered.
+ * @throws {Error} When handler registration fails or when called multiple times
+ * @example
+ * ```typescript
+ * import { command } from 'onin-plugin-sdk';
+ *
+ * // Define command handler with routing
+ * await command.handle(async (code, args) => {
+ *   console.log(`Received command: ${code}`, args);
+ *
+ *   switch (code) {
+ *     case 'greet':
+ *       return `Hello, ${args.name || 'World'}!`;
+ *
+ *     case 'calculate':
+ *       const { operation, a, b } = args;
+ *       switch (operation) {
+ *         case 'add': return a + b;
+ *         case 'multiply': return a * b;
+ *         default: throw new Error(`Unknown operation: ${operation}`);
+ *       }
+ *
+ *     default:
+ *       throw new Error(`Unknown command: ${code}`);
+ *   }
+ * });
+ * ```
+ * @since 0.1.0
+ * @group API
+ */
+export declare function handleCommand(handler: CommandHandler): Promise<void>;
+/**
+ * Dynamically register a command for the current plugin.
+ *
+ * This allows plugins to create commands at runtime based on user data,
+ * external APIs, or other dynamic sources. Registered commands are persisted
+ * and will appear in the command list.
+ *
+ * @param definition - The command definition including code, name, keywords, and matches
+ * @returns Promise that resolves when the command is successfully registered
+ * @throws {Error} When command registration fails
+ * @example
+ * ```typescript
+ * import { command } from 'onin-plugin-sdk';
+ *
+ * // Register a dynamic command
+ * await command.register({
+ *   code: 'open-bookmark-1',
+ *   name: 'My Favorite Site',
+ *   keywords: [{ name: 'bookmark' }, { name: 'favorite' }],
+ * });
+ *
+ * // Handle all commands
+ * await command.handle((code, args) => {
+ *   if (code.startsWith('open-bookmark-')) {
+ *     // Open the bookmark
+ *   }
+ * });
+ * ```
+ * @since 0.2.0
+ * @group API
+ */
+export declare function registerCommand(definition: CommandDefinition): Promise<void>;
+/**
+ * Remove a dynamically registered command.
+ *
+ * @param code - The unique command code to remove
+ * @returns Promise that resolves when the command is successfully removed
+ * @throws {Error} When command removal fails or command doesn't exist
+ * @example
+ * ```typescript
+ * import { command } from 'onin-plugin-sdk';
+ *
+ * // Remove a previously registered command
+ * await command.remove('open-bookmark-1');
+ * ```
+ * @since 0.2.0
+ * @group API
+ */
+export declare function removeCommand(code: string): Promise<void>;
+/**
+ * Simplified method name alias for handleCommand
+ * @see {@link handleCommand} - For detailed documentation
+ * @since 0.2.0
+ * @group API
+ */
+export declare const handle: typeof handleCommand;
+/**
+ * Simplified method name alias for registerCommand
+ * @see {@link registerCommand} - For detailed documentation
+ * @since 0.2.0
+ * @group API
+ */
+export declare const register: typeof registerCommand;
+/**
+ * Simplified method name alias for removeCommand
+ * @see {@link removeCommand} - For detailed documentation
+ * @since 0.2.0
+ * @group API
+ */
+export declare const remove: typeof removeCommand;
+/**
+ * Command API namespace - provides command handling functionality for plugins
+ *
+ * Allows plugins to:
+ * - **register**: Dynamically register commands at runtime
+ * - **handle**: Register a handler to process command executions
+ * - **remove**: Remove dynamically registered commands
+ *
+ * @namespace command
+ * @version 0.2.0
+ * @since 0.1.0
+ * @group API
+ * @example
+ * ```typescript
+ * import { command } from 'onin-plugin-sdk';
+ *
+ * // Register dynamic commands
+ * await command.register({
+ *   code: 'search-google',
+ *   name: 'Search Google',
+ *   keywords: [{ name: 'google' }],
+ *   matches: [{ type: 'text', name: 'Search text', min: 1 }]
+ * });
+ *
+ * // Handle command execution
+ * await command.handle(async (code, args) => {
+ *   if (code === 'search-google') {
+ *     window.open(`https://google.com/search?q=${encodeURIComponent(args.text)}`);
+ *   }
+ * });
+ *
+ * // Remove a command when no longer needed
+ * await command.remove('search-google');
+ * ```
+ */
+export declare const command: {
+    register: typeof registerCommand;
+    handle: typeof handleCommand;
+    remove: typeof removeCommand;
+};

package/dist/api/dialog.d.ts

@@ -0,0 +1,285 @@
+import { parseDialogError } from '../utils/error-parser';
+/**
+ * Message dialog options
+ * @interface MessageDialogOptions
+ * @since 0.1.0
+ * @group Types
+ */
+export interface MessageDialogOptions {
+    /** Dialog title */
+    title?: string;
+    /** Main message to display */
+    message: string;
+    /** Dialog type, affects the displayed icon */
+    kind?: 'info' | 'warning' | 'error';
+    /** Custom label for the "OK" button */
+    okLabel?: string;
+}
+/**
+ * Confirmation dialog options
+ * @interface ConfirmDialogOptions
+ * @since 0.1.0
+ * @group Types
+ */
+export interface ConfirmDialogOptions {
+    /** Dialog title */
+    title?: string;
+    /** Main message to display */
+    message: string;
+    /** Dialog type */
+    kind?: 'info' | 'warning' | 'error';
+    /** Custom label for the "OK" button */
+    okLabel?: string;
+    /** Custom label for the "Cancel" button */
+    cancelLabel?: string;
+}
+/**
+ * File type filter for file dialogs
+ * @interface DialogFilter
+ * @since 0.1.0
+ * @group Types
+ */
+export interface DialogFilter {
+    /** Filter name (e.g., "Image Files") */
+    name: string;
+    /** Array of file extensions associated with this filter (e.g., ['png', 'jpg']) */
+    extensions: string[];
+}
+/**
+ * Open file dialog options
+ * @interface OpenDialogOptions
+ * @since 0.1.0
+ * @group Types
+ */
+export interface OpenDialogOptions {
+    /** Dialog title */
+    title?: string;
+    /** Default path that should be displayed when the dialog opens */
+    defaultPath?: string;
+    /** Array of file type filters to apply to file selection */
+    filters?: DialogFilter[];
+    /** Whether to allow selecting multiple files */
+    multiple?: boolean;
+    /** Whether to open a directory selector instead of a file selector */
+    directory?: boolean;
+}
+/**
+ * Save file dialog options
+ * @interface SaveDialogOptions
+ * @since 0.1.0
+ * @group Types
+ */
+export interface SaveDialogOptions {
+    /** Dialog title */
+    title?: string;
+    /** Default suggested file path or name in the dialog */
+    defaultPath?: string;
+    /** Array of file type filters to apply to file saving */
+    filters?: DialogFilter[];
+}
+/**
+ * Shows a standard message dialog.
+ * @param options - Dialog configuration options
+ * @returns Promise that resolves when the dialog is closed
+ * @throws {PluginError} With code `DIALOG_UNAVAILABLE` when dialog system is not available
+ * @throws {PluginError} With code `DIALOG_INVALID_OPTIONS` when options are malformed
+ * @throws {PluginError} With code `PERMISSION_DENIED` when dialog permission is denied
+ * @example
+ * ```typescript
+ * // Simple info message
+ * await dialog.showMessage({
+ *   title: 'Info',
+ *   message: 'This is an informational message.'
+ * });
+ *
+ * // Warning message with custom styling
+ * await dialog.showMessage({
+ *   title: 'Warning',
+ *   message: 'This action cannot be undone.',
+ *   kind: 'warning',
+ *   okLabel: 'I Understand'
+ * });
+ *
+ * // Error message
+ * await dialog.showMessage({
+ *   title: 'Error',
+ *   message: 'An unexpected error occurred.',
+ *   kind: 'error'
+ * });
+ * ```
+ * @since 0.1.0
+ * @group API
+ */
+export declare function showMessage(options: MessageDialogOptions): Promise<void>;
+/**
+ * Shows a confirmation dialog with "OK" and "Cancel" buttons.
+ * @param options - Dialog configuration options
+ * @returns Promise that resolves to true if user clicks "OK", false otherwise
+ * @example
+ * const confirmed = await dialog.showConfirm({
+ *   title: 'Confirm Action',
+ *   message: 'Are you sure you want to proceed?'
+ * });
+ * if (confirmed) {
+ *   console.log('User confirmed.');
+ * }
+ */
+export declare function showConfirm(options: ConfirmDialogOptions): Promise<boolean>;
+/**
+ * Shows an open dialog for selecting files or directories.
+ * @param options - Dialog configuration options
+ * @returns Promise that resolves to the selected file/directory path(s), or null if user cancels
+ * @example
+ * // Select single file
+ * const filePath = await dialog.showOpen({
+ *   filters: [{ name: 'Text Files', extensions: ['txt'] }]
+ * });
+ * if (filePath) {
+ *   console.log('Selected file:', filePath);
+ * }
+ *
+ * // Select multiple files
+ * const filePaths = await dialog.showOpen({ multiple: true });
+ * if (filePaths) {
+ *   console.log('Selected files:', filePaths);
+ * }
+ */
+export declare function showOpen(options?: OpenDialogOptions): Promise<string | string[] | null>;
+/**
+ * Shows a save dialog for selecting a file save path.
+ * @param options - Dialog configuration options
+ * @returns Promise that resolves to the user-selected save path, or null if user cancels
+ * @example
+ * const savePath = await dialog.showSave({
+ *   defaultPath: 'new-file.txt',
+ *   filters: [{ name: 'Text Files', extensions: ['txt'] }]
+ * });
+ * if (savePath) {
+ *   console.log('File will be saved to:', savePath);
+ * }
+ */
+export declare function showSave(options?: SaveDialogOptions): Promise<string | null>;
+/**
+ * Shows an info message
+ * @param message - Message content
+ * @param title - Title (optional)
+ */
+export declare function info(message: string, title?: string): Promise<void>;
+/**
+ * Shows a warning message
+ * @param message - Message content
+ * @param title - Title (optional)
+ */
+export declare function warning(message: string, title?: string): Promise<void>;
+/**
+ * Shows an error message
+ * @param message - Message content
+ * @param title - Title (optional)
+ */
+export declare function error(message: string, title?: string): Promise<void>;
+/**
+ * Shows a confirmation dialog (simplified version)
+ * @param message - Message content
+ * @param title - Title (optional)
+ * @returns Whether the user clicked the confirm button
+ */
+export declare function confirm(message: string, title?: string): Promise<boolean>;
+/**
+ * Selects a single file
+ * @param filters - File filters (optional)
+ * @param defaultPath - Default path (optional)
+ * @returns Selected file path, or null if cancelled
+ */
+export declare function selectFile(filters?: DialogFilter[], defaultPath?: string): Promise<string | null>;
+/**
+ * Selects multiple files
+ * @param filters - File filters (optional)
+ * @param defaultPath - Default path (optional)
+ * @returns Array of selected file paths, or null if cancelled
+ */
+export declare function selectFiles(filters?: DialogFilter[], defaultPath?: string): Promise<string[] | null>;
+/**
+ * Selects a folder
+ * @param defaultPath - Default path (optional)
+ * @returns Selected folder path, or null if cancelled
+ */
+export declare function selectFolder(defaultPath?: string): Promise<string | null>;
+/**
+ * Save file dialog (simplified version)
+ * @param defaultName - Default file name (optional)
+ * @param filters - File filters (optional)
+ * @returns Selected save path, or null if cancelled
+ */
+export declare function saveFile(defaultName?: string, filters?: DialogFilter[]): Promise<string | null>;
+/**
+ * Dialog API namespace - provides native system dialog functionality
+ *
+ * Supports various types of system dialogs including message boxes, file pickers,
+ * and confirmation dialogs. All dialogs are native system dialogs that respect
+ * the user's operating system theme and accessibility settings.
+ *
+ * **Cross-Platform Support**: All dialog functions work consistently across
+ * Windows, macOS, and Linux with platform-appropriate styling.
+ *
+ * **Accessibility**: Native dialogs automatically support screen readers and
+ * keyboard navigation according to system accessibility settings.
+ *
+ * **User Experience**: Dialogs are modal and will block plugin execution until
+ * the user responds, ensuring proper user interaction flow.
+ *
+ * @namespace dialog
+ * @version 0.1.0
+ * @since 0.1.0
+ * @group API
+ * @see {@link parseDialogError} - For dialog error handling utilities
+ * @example
+ * ```typescript
+ * import { dialog } from 'onin-plugin-sdk';
+ *
+ * // Show information message
+ * await dialog.info('Operation completed successfully!');
+ *
+ * // Get user confirmation
+ * const confirmed = await dialog.confirm(
+ *   'Are you sure you want to delete this item?'
+ * );
+ * if (confirmed) {
+ *   // Proceed with deletion
+ * }
+ *
+ * // File selection
+ * const filePath = await dialog.selectFile([
+ *   { name: 'Text Files', extensions: ['txt', 'md'] },
+ *   { name: 'All Files', extensions: ['*'] }
+ * ]);
+ * if (filePath) {
+ *   console.log('Selected file:', filePath);
+ * }
+ *
+ * // Save file dialog
+ * const savePath = await dialog.saveFile('document.txt', [
+ *   { name: 'Text Files', extensions: ['txt'] }
+ * ]);
+ * if (savePath) {
+ *   // Save file to the selected path
+ * }
+ * ```
+ */
+export declare const dialog: {
+    /** Core methods */
+    showMessage: typeof showMessage;
+    showConfirm: typeof showConfirm;
+    showOpen: typeof showOpen;
+    showSave: typeof showSave;
+    /** Convenience methods */
+    info: typeof info;
+    warning: typeof warning;
+    error: typeof error;
+    confirm: typeof confirm;
+    selectFile: typeof selectFile;
+    selectFiles: typeof selectFiles;
+    selectFolder: typeof selectFolder;
+    saveFile: typeof saveFile;
+    /** Error handling tools */
+    parseDialogError: typeof parseDialogError;
+};

package/dist/api/fs.d.ts

@@ -0,0 +1,198 @@
+/**
+ * File or directory metadata
+ * @interface FileInfo
+ * @since 0.1.0
+ * @group Types
+ */
+export interface FileInfo {
+    /** File or directory name */
+    name: string;
+    /** Complete path of the file or directory */
+    path: string;
+    /** True if it's a file */
+    isFile: boolean;
+    /** True if it's a directory */
+    isDirectory: boolean;
+    /** File size in bytes */
+    size: number;
+    /** Last modified time (Unix timestamp) */
+    modifiedTime: number;
+    /** Creation time (Unix timestamp) */
+    createdTime: number;
+}
+/**
+ * Reads the text file content at the specified path with UTF-8 encoding.
+ * @param path - File path relative to the plugin data directory.
+ * @returns Promise that resolves to the file's text content.
+ * @throws {PluginError} With code `FS_FILE_NOT_FOUND` when the file doesn't exist
+ * @throws {PluginError} With code `FS_FILE_ACCESS_DENIED` when permission is denied
+ * @throws {PluginError} With code `FS_INVALID_PATH` when the path is malformed
+ * @throws {PluginError} With code `PERMISSION_DENIED` for general file system permission issues
+ * @example
+ * ```typescript
+ * // Read configuration file
+ * try {
+ *   const content = await fs.readFile('config.json');
+ *   const config = JSON.parse(content);
+ *   console.log('Configuration loaded:', config);
+ * } catch (error) {
+ *   if (errorUtils.isErrorCode(error, 'FS_FILE_NOT_FOUND')) {
+ *     console.log('Config file not found, using defaults');
+ *   } else {
+ *     console.error('Failed to read config:', error.message);
+ *   }
+ * }
+ *
+ * // Read log file
+ * const logContent = await fs.readFile('logs/app.log');
+ * console.log('Recent logs:', logContent.split('\n').slice(-10));
+ * ```
+ * @since 0.1.0
+ * @group API
+ */
+export declare function readFile(path: string): Promise<string>;
+/**
+ * Writes text content to a file at the specified path. Creates the file if it doesn't exist, or overwrites it if it does.
+ * @param path - File path relative to the plugin data directory.
+ * @param content - Text content to write to the file.
+ * @returns Promise that resolves when the file write operation is complete.
+ * @example
+ * await fs.writeFile('log.txt', 'This is a log entry.');
+ */
+export declare function writeFile(path: string, content: string): Promise<void>;
+/**
+ * Checks if a file or directory exists at the specified path.
+ * @param path - Path relative to the plugin data directory.
+ * @returns Promise that resolves to true if the path exists, false otherwise.
+ * @example
+ * if (await fs.exists('config.json')) {
+ *   console.log('Config file exists.');
+ * }
+ */
+export declare function exists(path: string): Promise<boolean>;
+/**
+ * Creates a new directory.
+ * @param path - Directory path relative to the plugin data directory.
+ * @param recursive - Whether to recursively create all non-existing parent directories.
+ * @returns Promise that resolves when the directory creation operation is complete.
+ * @example
+ * await fs.createDir('data/logs', true);
+ */
+export declare function createDir(path: string, recursive?: boolean): Promise<void>;
+/**
+ * Lists all files and subdirectories in the specified directory.
+ * @param path - Directory path relative to the plugin data directory.
+ * @returns Promise that resolves to an array of FileInfo objects containing the directory contents.
+ * @example
+ * const items = await fs.listDir('.');
+ * for (const item of items) {
+ *   console.log(item.name, item.isDirectory ? '(dir)' : '(file)');
+ * }
+ */
+export declare function listDir(path: string): Promise<FileInfo[]>;
+/**
+ * Deletes the file at the specified path.
+ * @param path - File path relative to the plugin data directory.
+ * @returns Promise that resolves when the file deletion operation is complete.
+ * @example
+ * await fs.deleteFile('temp.txt');
+ */
+export declare function deleteFile(path: string): Promise<void>;
+/**
+ * Deletes the directory at the specified path.
+ * @param path - Directory path relative to the plugin data directory.
+ * @param recursive - Whether to recursively delete all contents in the directory. If false and the directory is not empty, the operation will fail.
+ * @returns Promise that resolves when the directory deletion operation is complete.
+ * @example
+ * await fs.deleteDir('old_data', true);
+ */
+export declare function deleteDir(path: string, recursive?: boolean): Promise<void>;
+/**
+ * Gets metadata for the file or directory at the specified path.
+ * @param path - File path relative to the plugin data directory.
+ * @returns Promise that resolves to a FileInfo object for the file or directory.
+ * @example
+ * const info = await fs.getFileInfo('data.txt');
+ * console.log(`Size: ${info.size} bytes`);
+ */
+export declare function getFileInfo(path: string): Promise<FileInfo>;
+/**
+ * Copies a file from source path to destination path.
+ * @param sourcePath - Source file path relative to the plugin data directory.
+ * @param destPath - Destination file path relative to the plugin data directory.
+ * @returns Promise that resolves when the file copy operation is complete.
+ * @example
+ * await fs.copyFile('source.txt', 'destination.txt');
+ */
+export declare function copyFile(sourcePath: string, destPath: string): Promise<void>;
+/**
+ * Moves or renames a file/directory.
+ * @param sourcePath - Source path relative to the plugin data directory.
+ * @param destPath - Destination path relative to the plugin data directory.
+ * @returns Promise that resolves when the move/rename operation is complete.
+ * @example
+ * await fs.moveFile('old-name.txt', 'new-name.txt');
+ */
+export declare function moveFile(sourcePath: string, destPath: string): Promise<void>;
+/**
+ * File system API namespace - provides sandboxed file operations for plugins
+ *
+ * All file operations are restricted to the plugin's data directory for security.
+ * Paths are relative to the plugin's isolated storage space, ensuring data
+ * separation between plugins and preventing access to system files.
+ *
+ * **Security**: All file operations are sandboxed within the plugin's data directory.
+ * Attempts to access files outside this directory will result in errors.
+ *
+ * **Path Handling**: All paths are relative to the plugin data directory.
+ * Use forward slashes (/) for cross-platform compatibility.
+ *
+ * **Encoding**: Text files are read/written using UTF-8 encoding by default.
+ *
+ * **Performance**: For better performance with multiple operations, consider
+ * using batch operations when available.
+ *
+ * @namespace fs
+ * @version 0.1.0
+ * @since 0.1.0
+ * @group API
+ * @see {@link parseFsError} - For file system error handling utilities
+ * @example
+ * ```typescript
+ * import { fs } from 'onin-plugin-sdk';
+ *
+ * // Basic file operations
+ * await fs.writeFile('data.txt', 'Hello World');
+ * const content = await fs.readFile('data.txt');
+ * console.log(content); // 'Hello World'
+ *
+ * // Directory operations
+ * await fs.createDir('backups', true);
+ * const files = await fs.listDir('.');
+ * console.log('Files in plugin directory:', files);
+ *
+ * // File management
+ * await fs.copyFile('data.txt', 'backups/data-backup.txt');
+ * await fs.moveFile('old-name.txt', 'new-name.txt');
+ *
+ * // Check file existence
+ * if (await fs.exists('config.json')) {
+ *   const config = JSON.parse(await fs.readFile('config.json'));
+ * } else {
+ *   console.log('Config file not found, creating default...');
+ *   await fs.writeFile('config.json', JSON.stringify({ version: 1 }));
+ * }
+ * ```
+ */
+export declare const fs: {
+    readFile: typeof readFile;
+    writeFile: typeof writeFile;
+    exists: typeof exists;
+    createDir: typeof createDir;
+    listDir: typeof listDir;
+    deleteFile: typeof deleteFile;
+    deleteDir: typeof deleteDir;
+    getFileInfo: typeof getFileInfo;
+    copyFile: typeof copyFile;
+    moveFile: typeof moveFile;
+};