simen-keyboard-listener 1.1.9 → 1.1.10

package/dist/index.d.ts

@@ -1,3 +1,520 @@
+/**
+ * Type definitions for osascript context information module
+ */
+interface IFrontmostApp {
+    /** Application name */
+    name: string;
+    /** Bundle identifier (e.g., "com.apple.finder") */
+    bundleId: string;
+    /** Whether this is Finder.app */
+    isFinder: boolean;
+    /** Application executable path */
+    path: string;
+}
+interface IFinderItem {
+    /** File or folder name */
+    name: string;
+    /** Absolute POSIX path */
+    path: string;
+    /** Whether this is a folder */
+    isFolder: boolean;
+}
+interface IFinderSelection {
+    /** Array of absolute POSIX paths */
+    paths: string[];
+    /** Number of selected items */
+    count: number;
+    /** Detailed information for each item */
+    items: IFinderItem[];
+}
+interface IFinderWindow {
+    /** Window title/name */
+    name: string;
+    /** Folder path displayed in this window (null for special views) */
+    path: string | null;
+    /** Window index (1-based) */
+    index: number;
+    /** true if this is a special view (Recents, Search results, etc.) */
+    isSpecialView: boolean;
+}
+interface IFileMetadata {
+    /** File or folder name */
+    name: string;
+    /** Absolute POSIX path */
+    path: string;
+    /** File size in bytes (0 for folders) */
+    size: number;
+    /** Whether this is a folder */
+    isFolder: boolean;
+    /** Creation date (ISO string) */
+    createdAt: string;
+    /** Modification date (ISO string) */
+    modifiedAt: string;
+    /** File extension (empty for folders) */
+    extension: string;
+    /** Kind description (e.g., "Folder", "PNG Image") */
+    kind: string;
+}
+interface IClipboardContent {
+    /** Text content if available */
+    text: string | null;
+    /** Whether clipboard contains file references */
+    hasFiles: boolean;
+    /** Array of file paths if clipboard contains files */
+    filePaths: string[];
+    /** Whether clipboard contains image data (screenshot, copied image) */
+    hasImage: boolean;
+}
+interface IDesktopItem {
+    /** File or folder name */
+    name: string;
+    /** Absolute POSIX path */
+    path: string;
+    /** Whether this is a folder */
+    isFolder: boolean;
+}
+interface IRecentFile {
+    /** File name */
+    name: string;
+    /** Absolute POSIX path */
+    path: string;
+    /** Last accessed date (ISO string) */
+    accessedAt: string;
+}
+interface IRunningApp {
+    /** Application name */
+    name: string;
+    /** Bundle identifier */
+    bundleId: string;
+    /** Whether the application is hidden */
+    isHidden: boolean;
+    /** Whether this is the frontmost application */
+    isFrontmost: boolean;
+}
+interface ISystemContext {
+    /** Frontmost application info */
+    frontmostApp: IFrontmostApp;
+    /** Finder selection (null if Finder is not frontmost or no selection) */
+    finderSelection: IFinderSelection | null;
+    /** Current Finder folder path (null if Finder is not open) */
+    finderCurrentFolder: string | null;
+    /** Clipboard content */
+    clipboard: IClipboardContent;
+}
+interface IExecuteOptions {
+    /** Timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+interface IExecuteResult<T = string> {
+    /** Whether execution was successful */
+    success: boolean;
+    /** Result data if successful */
+    data?: T;
+    /** Error message if failed */
+    error?: string;
+    /** Execution time in milliseconds */
+    executionTime?: number;
+}
+
+/** A file or folder item in Finder selection */
+interface ISelectedItem {
+    /** Item name (e.g., "document.pdf") */
+    name: string;
+    /** Absolute POSIX path (e.g., "/Users/xxx/document.pdf") */
+    path: string;
+    /** true if this is a folder */
+    isFolder: boolean;
+    /** File size in bytes (only when includeMetadata is true) */
+    size?: number;
+    /** Modification date ISO string (only when includeMetadata is true) */
+    modifiedAt?: string;
+}
+/** A Finder window */
+interface IFinderWindowInfo {
+    /** Window title */
+    name: string;
+    /** Folder path displayed in window (absolute), or null for special views */
+    path: string | null;
+    /** Window index (1-based) */
+    index: number;
+    /** true if this is a special view (Recents, Search results, etc.) */
+    isSpecialView: boolean;
+}
+/**
+ * Complete Agent context - all information needed for Agent decision-making.
+ */
+interface IAgentContext {
+    /** Frontmost (active) application */
+    frontmostApp: {
+        /** App name (e.g., "Finder", "Safari") */
+        name: string;
+        /** Bundle ID (e.g., "com.apple.finder") */
+        bundleId: string;
+        /** true if Finder is frontmost */
+        isFinder: boolean;
+        /** App path (e.g., "/Applications/Safari.app") */
+        path: string;
+    };
+    /** Finder selected items (up to 50, all absolute paths) */
+    finderSelection: {
+        /** Number of selected items */
+        count: number;
+        /** Detailed item info */
+        items: ISelectedItem[];
+        /** Just the paths (convenience) */
+        paths: string[];
+    };
+    /** Current folder in front Finder window (null if no window) */
+    finderCurrentFolder: string | null;
+    /** All open Finder windows */
+    finderWindows: IFinderWindowInfo[];
+    /** Desktop folder path (e.g., "/Users/xxx/Desktop/") */
+    desktopPath: string;
+    /** Clipboard content */
+    clipboard: {
+        /** Text content (max 2000 chars, null if empty) */
+        text: string | null;
+        /** true if clipboard contains file references */
+        hasFiles: boolean;
+        /** File paths if hasFiles is true */
+        filePaths: string[];
+        /** true if clipboard contains image data (screenshot, copied image) */
+        hasImage: boolean;
+    };
+    /** Unix timestamp when context was captured */
+    timestamp: number;
+}
+/** Options for getAgentContext */
+interface IAgentContextOptions extends IExecuteOptions {
+    /** Include file metadata (size, modifiedAt) for selected items. Slower (~350ms vs ~250ms) */
+    includeMetadata?: boolean;
+}
+/**
+ * Get complete Agent context in ONE osascript call.
+ *
+ * @param opts - Options
+ * @param opts.timeout - Timeout in ms (default: 30000)
+ * @param opts.includeMetadata - Include file size/modifiedAt for selected items (slower)
+ * @returns Agent context, or null if not on macOS or failed
+ *
+ * @example
+ * // Basic usage (~250ms)
+ * const ctx = await getAgentContext();
+ *
+ * // With custom timeout
+ * const ctx = await getAgentContext({ timeout: 5000 });
+ *
+ * // With file metadata (~350ms)
+ * const ctx = await getAgentContext({ includeMetadata: true });
+ */
+declare function getAgentContext(opts?: IAgentContextOptions): Promise<IAgentContext | null>;
+
+/**
+ * Check if osascript is available (macOS only)
+ */
+declare function isOsascriptAvailable(): boolean;
+/**
+ * Execute a single-line AppleScript
+ *
+ * @param script - AppleScript code to execute
+ * @param options - Execution options
+ * @returns Execution result with stdout as data
+ */
+declare function executeAppleScript(script: string, options?: IExecuteOptions): Promise<IExecuteResult<string>>;
+/**
+ * Execute multi-line AppleScript
+ *
+ * @param lines - Array of AppleScript lines
+ * @param options - Execution options
+ * @returns Execution result with stdout as data
+ */
+declare function executeAppleScriptLines(lines: string[], options?: IExecuteOptions): Promise<IExecuteResult<string>>;
+/**
+ * Execute AppleScript and parse the result
+ *
+ * @param script - AppleScript code to execute
+ * @param parser - Function to parse the raw output
+ * @param options - Execution options
+ * @returns Parsed result
+ */
+declare function executeAndParse<T>(script: string, parser: (output: string) => T, options?: IExecuteOptions): Promise<IExecuteResult<T>>;
+/**
+ * Execute multi-line AppleScript and parse the result
+ *
+ * @param lines - Array of AppleScript lines
+ * @param parser - Function to parse the raw output
+ * @param options - Execution options
+ * @returns Parsed result
+ */
+declare function executeMultilineAndParse<T>(lines: string[], parser: (output: string) => T, options?: IExecuteOptions): Promise<IExecuteResult<T>>;
+/**
+ * Escape a string for use in AppleScript
+ * Handles quotes and backslashes
+ */
+declare function escapeForAppleScript(str: string): string;
+
+/**
+ * A Finder window
+ */
+interface IFinderWindowItem {
+    /** Window title (e.g., "Downloads", "Recents") */
+    name: string;
+    /** Folder path (absolute POSIX path), null for special views */
+    path: string | null;
+    /** Window index (1-based, 1 = frontmost) */
+    index: number;
+    /** true if this is a special view (Recents, AirDrop, Search, Tags, etc.) */
+    isSpecialView: boolean;
+}
+/**
+ * Finder context - lightweight info about Finder state
+ */
+interface IFinderContext {
+    /** All open Finder windows (ordered by z-index, front first) */
+    windows: IFinderWindowItem[];
+    /**
+     * Front Finder window info.
+     * - null if Finder is not frontmost (user is in another app)
+     * - null if no Finder windows are open
+     */
+    frontWindow: {
+        name: string;
+        path: string | null;
+        isSpecialView: boolean;
+    } | null;
+    /**
+     * Selected file/folder paths in the front Finder window.
+     * - Empty array if nothing selected
+     * - Empty array if Finder is not frontmost
+     * - Max 100 items for performance
+     */
+    selectedPaths: string[];
+    /** true if Finder.app is the frontmost application */
+    isFinderFrontmost: boolean;
+    /** Number of open Finder windows */
+    windowCount: number;
+}
+/**
+ * Get lightweight Finder context.
+ *
+ * This is optimized for scenarios where you only need Finder-related info,
+ * not the full system context (clipboard, desktop, etc.).
+ *
+ * @param options - Execution options (timeout, etc.)
+ * @returns Finder context, or null if not on macOS or failed
+ *
+ * @example
+ * const ctx = await getFinderContext();
+ * if (ctx?.isFinderFrontmost) {
+ *   console.log('Current folder:', ctx.frontWindow?.path);
+ *   console.log('Selected files:', ctx.selectedPaths);
+ * }
+ *
+ * @example
+ * // List all Finder windows
+ * const ctx = await getFinderContext();
+ * for (const win of ctx?.windows ?? []) {
+ *   if (win.isSpecialView) {
+ *     console.log(`Special view: ${win.name}`);
+ *   } else {
+ *     console.log(`Folder: ${win.path}`);
+ *   }
+ * }
+ */
+declare function getFinderContext(options?: IExecuteOptions): Promise<IFinderContext | null>;
+
+/**
+ * Get information about the frontmost (active) application
+ *
+ * @param options - Execution options
+ * @returns Frontmost application info, or null if failed
+ */
+declare function getFrontmostApp(options?: IExecuteOptions): Promise<IFrontmostApp | null>;
+
+/**
+ * Get the current Finder selection (selected files/folders)
+ *
+ * @param options - Execution options
+ * @returns Finder selection info with absolute paths, or null if failed
+ */
+declare function getFinderSelection(options?: IExecuteOptions): Promise<IFinderSelection | null>;
+/**
+ * Get the current folder displayed in Finder's front window
+ *
+ * @param options - Execution options
+ * @returns Current folder path, or null if no Finder window or failed
+ */
+declare function getFinderCurrentFolder(options?: IExecuteOptions): Promise<string | null>;
+
+/**
+ * Get information about all open Finder windows
+ *
+ * @param options - Execution options
+ * @returns Array of Finder window info, or null if failed
+ */
+declare function getFinderWindows(options?: IExecuteOptions): Promise<IFinderWindow[] | null>;
+
+/**
+ * Get metadata for a file or folder
+ *
+ * @param filePath - Absolute POSIX path to the file/folder
+ * @param options - Execution options
+ * @returns File metadata, or null if failed
+ */
+declare function getFileMetadata(filePath: string, options?: IExecuteOptions): Promise<IFileMetadata | null>;
+/**
+ * Get metadata for multiple files/folders
+ *
+ * @param filePaths - Array of absolute POSIX paths
+ * @param options - Execution options
+ * @returns Array of file metadata (null entries for failed lookups)
+ */
+declare function getFilesMetadata(filePaths: string[], options?: IExecuteOptions): Promise<(IFileMetadata | null)[]>;
+
+/**
+ * Get clipboard content (text and/or file references)
+ *
+ * @param options - Execution options
+ * @returns Clipboard content info, or null if failed
+ */
+declare function getClipboardContent(options?: IExecuteOptions): Promise<IClipboardContent | null>;
+/**
+ * Get clipboard text only (faster if you only need text)
+ *
+ * @param options - Execution options
+ * @returns Clipboard text, or null if no text or failed
+ */
+declare function getClipboardText(options?: IExecuteOptions): Promise<string | null>;
+
+/**
+ * Get all items on the desktop
+ *
+ * @param options - Execution options
+ * @returns Array of desktop items, or null if failed
+ */
+declare function getDesktopItems(options?: IExecuteOptions): Promise<IDesktopItem[] | null>;
+/**
+ * Get the desktop folder path
+ *
+ * @param options - Execution options
+ * @returns Desktop folder path, or null if failed
+ */
+declare function getDesktopPath(options?: IExecuteOptions): Promise<string | null>;
+
+/**
+ * Get recent files from Finder's Recents folder
+ *
+ * @param limit - Maximum number of files to return (default: 20)
+ * @param options - Execution options
+ * @returns Array of recent files, or null if failed
+ */
+declare function getRecentFiles(limit?: number, options?: IExecuteOptions): Promise<IRecentFile[] | null>;
+/**
+ * Get recently modified documents (using mdfind)
+ * This searches for files modified in the last 7 days
+ *
+ * @param options - Execution options
+ * @returns Array of recent files, or null if failed
+ */
+declare function getRecentDocuments(options?: IExecuteOptions): Promise<IRecentFile[] | null>;
+
+/**
+ * Get all running applications
+ *
+ * @param options - Execution options
+ * @returns Array of running apps, or null if failed
+ */
+declare function getRunningApps(options?: IExecuteOptions): Promise<IRunningApp[] | null>;
+/**
+ * Check if a specific application is running
+ *
+ * @param appName - Application name or bundle ID
+ * @param options - Execution options
+ * @returns true if running, false otherwise
+ */
+declare function isAppRunning(appName: string, options?: IExecuteOptions): Promise<boolean>;
+/**
+ * Get the frontmost application from the running apps list
+ *
+ * @param options - Execution options
+ * @returns Frontmost app info, or null if failed
+ */
+declare function getFrontmostFromRunning(options?: IExecuteOptions): Promise<IRunningApp | null>;
+
+/** Result of reading file content */
+interface IFileContent {
+    /** File path that was read */
+    path: string;
+    /** File content as text */
+    content: string;
+    /** File size in bytes */
+    size: number;
+    /** true if read was successful */
+    success: boolean;
+    /** Error message if failed */
+    error?: string;
+}
+/** Options for readFileContent */
+interface IReadFileOptions extends IExecuteOptions {
+    /** Maximum bytes to read (default: 1MB = 1048576) */
+    maxBytes?: number;
+    /** Encoding (default: utf8) */
+    encoding?: 'utf8' | 'utf16';
+}
+/**
+ * Read file content using AppleScript.
+ *
+ * @param filePath - Absolute POSIX path to the file
+ * @param opts - Options
+ * @returns File content, or null if not on macOS
+ *
+ * @example
+ * const result = await readFileContent('/Users/xxx/document.txt');
+ * if (result?.success) {
+ *   console.log(result.content);
+ * }
+ *
+ * @example
+ * // Read with size limit
+ * const result = await readFileContent('/path/to/file.txt', { maxBytes: 10000 });
+ */
+declare function readFileContent(filePath: string, opts?: IReadFileOptions): Promise<IFileContent | null>;
+/**
+ * Read multiple files in parallel.
+ *
+ * @param filePaths - Array of absolute POSIX paths
+ * @param opts - Options
+ * @returns Array of file contents
+ *
+ * @example
+ * const results = await readMultipleFiles(['/path/a.txt', '/path/b.txt']);
+ */
+declare function readMultipleFiles(filePaths: string[], opts?: IReadFileOptions): Promise<IFileContent[]>;
+
+/**
+ * osascript module - macOS system context for Agent decision-making
+ *
+ * RECOMMENDED: Use getAgentContext() for best performance (~250ms).
+ * It retrieves all commonly needed info in a single osascript call.
+ *
+ * Available information:
+ * - Frontmost application (name, bundleId, path)
+ * - Finder selection (files/folders with absolute paths, supports multi-select)
+ * - Finder windows (all open windows with paths)
+ * - Desktop path
+ * - Clipboard content (text and/or file paths)
+ *
+ * Additional APIs for specific use cases:
+ * - File metadata, recent files, running apps, etc.
+ *
+ * Note: macOS only. Returns null on other platforms.
+ */
+
+/**
+ * @deprecated Use getAgentContext() instead for better performance.
+ */
+declare function getSystemContext(options?: IExecuteOptions): Promise<ISystemContext | null>;
+
 type IGlobalKeyState = 'DOWN' | 'UP' | 'PERMISSION_LOST';
 interface IGlobalKeyEvent {
     readonly name: string;
@@ -65,4 +582,4 @@ declare function getSelectedTextSmart(): string | null;
  */
 declare function setBlockSystemHotkeys(block: boolean): void;
 
-export { type IGlobalKeyDownMap, type IGlobalKeyEvent, type IGlobalKeyListener, type IGlobalKeyState, type IGlobalKeyboardListener, type IPermissionLostListener, checkKeyboardPermission, createGlobalKeyboardListener, getContextJSON, getFocusedInputSelectedText, getFocusedInputValue, getGlobalKeyboardListener, getSelectedTextSmart, setBlockSystemHotkeys };
+export { type IAgentContext, type IAgentContextOptions, type IClipboardContent, type IDesktopItem, type IExecuteOptions, type IExecuteResult, type IFileContent, type IFileMetadata, type IFinderContext, type IFinderItem, type IFinderSelection, type IFinderWindow, type IFinderWindowInfo, type IFinderWindowItem, type IFrontmostApp, type IGlobalKeyDownMap, type IGlobalKeyEvent, type IGlobalKeyListener, type IGlobalKeyState, type IGlobalKeyboardListener, type IPermissionLostListener, type IReadFileOptions, type IRecentFile, type IRunningApp, type ISelectedItem, type ISystemContext, checkKeyboardPermission, createGlobalKeyboardListener, escapeForAppleScript, executeAndParse, executeAppleScript, executeAppleScriptLines, executeMultilineAndParse, getAgentContext, getClipboardContent, getClipboardText, getContextJSON, getDesktopItems, getDesktopPath, getFileMetadata, getFilesMetadata, getFinderContext, getFinderCurrentFolder, getFinderSelection, getFinderWindows, getFocusedInputSelectedText, getFocusedInputValue, getFrontmostApp, getFrontmostFromRunning, getGlobalKeyboardListener, getRecentDocuments, getRecentFiles, getRunningApps, getSelectedTextSmart, getSystemContext, isAppRunning, isOsascriptAvailable, readFileContent, readMultipleFiles, setBlockSystemHotkeys };