API Reference

This document describes the IPC API exposed by Peeka2 for communication between the main and renderer processes.

Overview

Peeka2 uses Electron's IPC (Inter-Process Communication) for secure communication between processes. All APIs are type-safe and accessed through the window.electronAPI object.

File System API

readDirectory

Reads the contents of a directory.

readDirectory(dirPath: string): Promise<{
  name: string;
  path: string;
  isDirectory: boolean;
  isFile: boolean;
}[]>

Parameters:

• dirPath: Absolute path to directory

Returns:

• Array of file/directory entries

Example:

const files = await window.electronAPI.readDirectory('/home/user/Documents');

readFile

Reads the contents of a file as text.

readFile(filePath: string): Promise<string>

Parameters:

• filePath: Absolute path to file

Returns:

• File contents as string

Example:

const content = await window.electronAPI.readFile('/home/user/file.txt');

getHomeDirectory

Gets the user's home directory path.

getHomeDirectory(): Promise<string>

Returns:

• Home directory path

Example:

const homePath = await window.electronAPI.getHomeDirectory();

Dialog API

showOpenDialog

Shows native file/folder selection dialog.

showOpenDialog(options: {
  properties?: Array<'openFile' | 'openDirectory' | 'multiSelections'>;
  filters?: Array<{
    name: string;
    extensions: string[];
  }>;
  defaultPath?: string;
}): Promise<{
  canceled: boolean;
  filePaths: string[];
}>

Parameters:

• options: Dialog configuration
  • properties: Dialog behavior flags
  • filters: File type filters
  • defaultPath: Initial directory

Returns:

• canceled: Whether dialog was canceled
• filePaths: Selected paths

Example:

const result = await window.electronAPI.showOpenDialog({
  properties: ['openFile'],
  filters: [
    { name: 'Markdown', extensions: ['md'] },
    { name: 'All Files', extensions: ['*'] }
  ]
});

File Watching API

watchFile

Watches a file for changes.

watchFile(filePath: string): void

Parameters:

• filePath: Path to watch

Events:

• file-changed: Emitted when file changes
• file-deleted: Emitted when file is deleted

Example:

window.electronAPI.watchFile('/path/to/file.txt');
window.electronAPI.onFileChange((event, path, changeType) => {
  console.log(`File ${changeType}: ${path}`);
});

watchDirectory

Watches a directory for changes.

watchDirectory(dirPath: string): void

Parameters:

• dirPath: Directory to watch

Events:

• directory-changed: Emitted on changes

Example:

window.electronAPI.watchDirectory('/path/to/dir');
window.electronAPI.onDirectoryChange((event, path, changeType) => {
  console.log(`Directory ${changeType}: ${path}`);
});

stopWatching

Stops all file watchers.

stopWatching(): void

Example:

window.electronAPI.stopWatching();

Event Listeners

onFileChange

Listens for file change events.

onFileChange(callback: (
  event: IpcRendererEvent,
  filePath: string,
  changeType: 'change' | 'unlink'
) => void): void

onDirectoryChange

Listens for directory change events.

onDirectoryChange(callback: (
  event: IpcRendererEvent,
  dirPath: string,
  changeType: string,
  affectedPath?: string
) => void): void

removeAllListeners

Removes all event listeners.

removeAllListeners(channel: string): void

Type Definitions

FileEntry

interface FileEntry {
  name: string;
  path: string;
  isDirectory: boolean;
  isFile: boolean;
}

DialogOptions

interface DialogOptions {
  properties?: Array<'openFile' | 'openDirectory' | 'multiSelections'>;
  filters?: Array<{
    name: string;
    extensions: string[];
  }>;
  defaultPath?: string;
}

DialogResult

interface DialogResult {
  canceled: boolean;
  filePaths: string[];
}

Error Handling

All API methods return promises that may reject with errors:

try {
  const content = await window.electronAPI.readFile('/path/to/file');
} catch (error) {
  console.error('Failed to read file:', error.message);
}

Common errors:

• ENOENT: File not found
• EACCES: Permission denied
• EISDIR: Is a directory
• EMFILE: Too many open files

Security Notes

1. Path Validation: All paths are validated in the main process
2. Sandboxing: Renderer is sandboxed by default
3. Context Isolation: No direct Node.js access
4. Limited Scope: Only exposed APIs available

Future APIs

Planned additions:

• File operations (copy, move, delete)
• Search functionality
• Metadata retrieval
• Thumbnail generation
• Archive handling