markupr 2.1.8 → 2.5.0

package/docs/API.md

@@ -1,514 +0,0 @@
-# API Reference
-
-markupr uses Electron's IPC (Inter-Process Communication) for all communication between the main process and renderer. This document covers the internal API for developers.
-
-## Table of Contents
-
-- [Architecture Overview](#architecture-overview)
-- [IPC Channels](#ipc-channels)
-- [Preload API](#preload-api)
-- [Event System](#event-system)
-- [Plugin Architecture](#plugin-architecture)
-- [Type Definitions](#type-definitions)
-
-## Architecture Overview
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                     Renderer Process                         │
-│  ┌─────────────────────────────────────────────────────┐   │
-│  │                  React Application                    │   │
-│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐            │   │
-│  │  │  App.tsx │  │Components│  │  Hooks  │            │   │
-│  │  └────┬────┘  └────┬────┘  └────┬────┘            │   │
-│  │       │            │            │                   │   │
-│  │       └────────────┴────────────┘                   │   │
-│  │                     │                                │   │
-│  │              window.markupr                     │   │
-│  └─────────────────────┬───────────────────────────────┘   │
-│                        │                                     │
-├────────────────────────┼─────────────────────────────────────┤
-│                   Preload Script                             │
-│              contextBridge.exposeInMainWorld                 │
-├────────────────────────┼─────────────────────────────────────┤
-│                        │                                     │
-│                     ipcMain                                  │
-│                        │                                     │
-│  ┌─────────────────────┴───────────────────────────────┐   │
-│  │                    Main Process                       │   │
-│  │                                                       │   │
-│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐            │   │
-│  │  │ Session  │ │ Capture  │ │Transcript│            │   │
-│  │  │Controller│ │ Service  │ │ Service  │            │   │
-│  │  └──────────┘ └──────────┘ └──────────┘            │   │
-│  │                                                       │   │
-│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐            │   │
-│  │  │  Hotkey  │ │   Tray   │ │ Settings │            │   │
-│  │  │ Manager  │ │ Manager  │ │ Manager  │            │   │
-│  │  └──────────┘ └──────────┘ └──────────┘            │   │
-│  └───────────────────────────────────────────────────────┘   │
-│                     Main Process                             │
-└─────────────────────────────────────────────────────────────┘
-```
-
-## IPC Channels
-
-All IPC channels are defined in `src/shared/types.ts` with the `IPC_CHANNELS` constant.
-
-### Session Channels
-
-#### Renderer to Main
-
-| Channel | Method | Description | Returns |
-|---------|--------|-------------|---------|
-| `markupr:session:start` | invoke | Start recording | `{success, sessionId?, error?}` |
-| `markupr:session:stop` | invoke | Stop recording | `{success, session?, error?}` |
-| `markupr:session:cancel` | invoke | Cancel without saving | `{success}` |
-| `markupr:session:get-status` | invoke | Get current status | `SessionStatusPayload` |
-| `markupr:session:get-current` | invoke | Get session data | `SessionPayload | null` |
-
-#### Main to Renderer
-
-| Channel | Description | Payload |
-|---------|-------------|---------|
-| `markupr:session:state-changed` | State transition | `{state, session}` |
-| `markupr:session:status-update` | Periodic status | `SessionStatusPayload` |
-| `markupr:session:complete` | Session finished | `SessionPayload` |
-| `markupr:session:feedback-item` | New item captured | `FeedbackItemPayload` |
-| `markupr:session:error` | Error occurred | `{message}` |
-
-### Capture Channels
-
-#### Renderer to Main
-
-| Channel | Method | Description | Returns |
-|---------|--------|-------------|---------|
-| `markupr:capture:get-sources` | invoke | List sources | `CaptureSource[]` |
-| `markupr:capture:manual-screenshot` | invoke | Take screenshot | `{success}` |
-
-#### Main to Renderer
-
-| Channel | Description | Payload |
-|---------|-------------|---------|
-| `markupr:capture:screenshot-taken` | Screenshot captured | `ScreenshotCapturedPayload` |
-| `markupr:capture:manual-triggered` | Manual hotkey used | `{timestamp}` |
-
-### Audio Channels
-
-#### Communication Flow
-
-```
-Main Process                    Renderer Process
-     │                               │
-     │ ─── AUDIO_START_CAPTURE ───> │  Start audio capture
-     │                               │
-     │ <── AUDIO_CAPTURE_STARTED ─── │  Confirm started
-     │                               │
-     │ <── AUDIO_CHUNK ──────────── │  Audio data (100ms chunks)
-     │ <── AUDIO_CHUNK ──────────── │
-     │ <── AUDIO_CHUNK ──────────── │
-     │                               │
-     │ ─── AUDIO_STOP_CAPTURE ────> │  Stop capture
-     │                               │
-     │ <── AUDIO_CAPTURE_STOPPED ── │  Confirm stopped
-```
-
-### Settings Channels
-
-| Channel | Method | Description | Returns |
-|---------|--------|-------------|---------|
-| `markupr:settings:get` | invoke | Get single setting | `AppSettings[K]` |
-| `markupr:settings:get-all` | invoke | Get all settings | `AppSettings` |
-| `markupr:settings:set` | invoke | Set single setting | `AppSettings` |
-| `markupr:settings:get-api-key` | invoke | Get API key (secure) | `string | null` |
-| `markupr:settings:set-api-key` | invoke | Set API key (secure) | `boolean` |
-
-### Update Channels
-
-| Channel | Method | Description | Returns |
-|---------|--------|-------------|---------|
-| `markupr:update:check` | invoke | Check for updates | `UpdateInfo` |
-| `markupr:update:download` | invoke | Download update | `void` |
-| `markupr:update:install` | invoke | Install and restart | `void` |
-
-#### Main to Renderer
-
-| Channel | Description | Payload |
-|---------|-------------|---------|
-| `markupr:update:status` | Update status change | `UpdateStatusPayload` |
-
-## Preload API
-
-The preload script (`src/preload/index.ts`) exposes a safe API to the renderer via `window.markupr`.
-
-### Session API
-
-```typescript
-// Start a recording session
-const result = await window.markupr.session.start(sourceId);
-// Returns: { success: boolean; sessionId?: string; error?: string }
-
-// Stop the current session
-const result = await window.markupr.session.stop();
-// Returns: { success: boolean; session?: SessionPayload; error?: string }
-
-// Cancel without saving
-const result = await window.markupr.session.cancel();
-// Returns: { success: boolean }
-
-// Get current status
-const status = await window.markupr.session.getStatus();
-// Returns: SessionStatusPayload
-
-// Get current session data
-const session = await window.markupr.session.getCurrent();
-// Returns: SessionPayload | null
-
-// Subscribe to state changes
-const unsubscribe = window.markupr.session.onStateChange(({ state, session }) => {
-  console.log('State:', state);
-});
-
-// Subscribe to new feedback items
-const unsubscribe = window.markupr.session.onFeedbackItem((item) => {
-  console.log('New item:', item);
-});
-
-// Subscribe to errors
-const unsubscribe = window.markupr.session.onError(({ message }) => {
-  console.error('Error:', message);
-});
-```
-
-### Capture API
-
-```typescript
-// Get available capture sources
-const sources = await window.markupr.capture.getSources();
-// Returns: CaptureSource[]
-
-// Trigger manual screenshot
-await window.markupr.capture.manualScreenshot();
-
-// Subscribe to screenshots
-const unsubscribe = window.markupr.capture.onScreenshot((data) => {
-  console.log('Screenshot:', data.id, data.count);
-});
-```
-
-### Audio API
-
-```typescript
-// Get available devices (enumeration happens in renderer)
-const devices = await window.markupr.audio.getDevices();
-
-// Set preferred device
-await window.markupr.audio.setDevice(deviceId);
-
-// Subscribe to audio level (for visualization)
-const unsubscribe = window.markupr.audio.onLevel((level) => {
-  // level is 0-1 normalized amplitude
-});
-
-// Subscribe to voice activity
-const unsubscribe = window.markupr.audio.onVoiceActivity((isActive) => {
-  // isActive is boolean
-});
-```
-
-### Settings API
-
-```typescript
-// Get a single setting
-const theme = await window.markupr.settings.get('theme');
-
-// Get all settings
-const settings = await window.markupr.settings.getAll();
-
-// Set a setting
-const updated = await window.markupr.settings.set('theme', 'dark');
-
-// Get API key from secure storage
-const apiKey = await window.markupr.settings.getApiKey('openai');
-
-// Set API key in secure storage
-const success = await window.markupr.settings.setApiKey('openai', 'your-key');
-```
-
-### Hotkeys API
-
-```typescript
-// Get current configuration
-const config = await window.markupr.hotkeys.getConfig();
-// Returns: HotkeyConfig
-
-// Update configuration
-const result = await window.markupr.hotkeys.updateConfig({
-  toggleRecording: 'CommandOrControl+Shift+G'
-});
-// Returns: { config: HotkeyConfig; results: RegistrationResult[] }
-
-// Subscribe to hotkey triggers
-const unsubscribe = window.markupr.hotkeys.onTriggered(({ action, accelerator }) => {
-  console.log('Hotkey:', action);
-});
-```
-
-### Output API
-
-```typescript
-// Save current session
-const result = await window.markupr.output.save();
-// Returns: SaveResult
-
-// Copy to clipboard
-const success = await window.markupr.output.copyClipboard();
-
-// Open output folder
-await window.markupr.output.openFolder();
-
-// List saved sessions
-const sessions = await window.markupr.output.listSessions();
-
-// Delete a session
-await window.markupr.output.deleteSession(sessionId);
-
-// Export a session
-await window.markupr.output.exportSession(sessionId, 'pdf');
-```
-
-### Crash Recovery API
-
-```typescript
-// Check for incomplete sessions
-const { hasIncomplete, session } = await window.markupr.crashRecovery.check();
-
-// Recover an incomplete session
-const result = await window.markupr.crashRecovery.recover(sessionId);
-
-// Discard incomplete session
-await window.markupr.crashRecovery.discard();
-
-// Get crash logs
-const logs = await window.markupr.crashRecovery.getLogs(10);
-
-// Subscribe to found incomplete sessions (on startup)
-const unsubscribe = window.markupr.crashRecovery.onIncompleteFound(({ session }) => {
-  // Show recovery dialog
-});
-```
-
-### Updates API
-
-```typescript
-// Check for updates
-await window.markupr.updates.check();
-
-// Download available update
-await window.markupr.updates.download();
-
-// Install and restart
-await window.markupr.updates.install();
-
-// Subscribe to update status
-const unsubscribe = window.markupr.updates.onStatus((status) => {
-  console.log('Update status:', status.status);
-  if (status.percent) {
-    console.log('Progress:', status.percent);
-  }
-});
-```
-
-## Event System
-
-### Event Subscription Pattern
-
-All event subscriptions return an unsubscribe function:
-
-```typescript
-// Subscribe
-const unsubscribe = window.markupr.session.onStateChange((data) => {
-  // Handle event
-});
-
-// Later, clean up
-unsubscribe();
-```
-
-### Using with React
-
-```tsx
-import { useEffect, useState } from 'react';
-
-function useSessionState() {
-  const [state, setState] = useState<SessionState>('idle');
-
-  useEffect(() => {
-    const unsubscribe = window.markupr.session.onStateChange(({ state }) => {
-      setState(state);
-    });
-
-    return unsubscribe; // Clean up on unmount
-  }, []);
-
-  return state;
-}
-```
-
-## Plugin Architecture
-
-markupr is designed to support plugins in future versions.
-
-### Planned Plugin Types
-
-1. **Output Formatters**: Add new export formats
-2. **Transcription Services**: Alternative to OpenAI
-3. **Integrations**: Connect to external services
-4. **Annotation Tools**: Custom drawing tools
-
-### Plugin Interface (Draft)
-
-```typescript
-interface markuprPlugin {
-  name: string;
-  version: string;
-  type: 'formatter' | 'transcription' | 'integration' | 'annotation';
-
-  // Lifecycle hooks
-  onLoad(): Promise<void>;
-  onUnload(): Promise<void>;
-
-  // Type-specific methods
-  // ...
-}
-
-// Example: Custom formatter plugin
-interface FormatterPlugin extends markuprPlugin {
-  type: 'formatter';
-
-  format(session: Session): Promise<{
-    content: string;
-    extension: string;
-    mimeType: string;
-  }>;
-}
-```
-
-## Type Definitions
-
-### Core Types
-
-```typescript
-// Session state machine
-type SessionState = 'idle' | 'recording' | 'processing' | 'complete';
-
-// Session status
-type SessionStatus = 'idle' | 'recording' | 'processing' | 'complete' | 'error';
-
-// Tray icon states
-type TrayState = 'idle' | 'recording' | 'processing' | 'error';
-```
-
-### Payload Types
-
-```typescript
-// Session status (sent during recording)
-interface SessionStatusPayload {
-  state: SessionState;
-  duration: number;
-  feedbackCount: number;
-  screenshotCount: number;
-}
-
-// Feedback item (sent when captured)
-interface FeedbackItemPayload {
-  id: string;
-  timestamp: number;
-  text: string;
-  confidence: number;
-  hasScreenshot: boolean;
-  screenshotId?: string;
-}
-
-// Screenshot captured
-interface ScreenshotCapturedPayload {
-  id: string;
-  timestamp: number;
-  count: number;
-  width?: number;
-  height?: number;
-}
-
-// Transcript chunk
-interface TranscriptChunkPayload {
-  text: string;
-  timestamp: number;
-  confidence: number;
-  isFinal: boolean;
-  words?: Array<{
-    word: string;
-    start: number;
-    end: number;
-    confidence: number;
-  }>;
-}
-```
-
-### Configuration Types
-
-```typescript
-// Hotkey configuration
-interface HotkeyConfig {
-  toggleRecording: string;
-  manualScreenshot: string;
-}
-
-// Application settings
-interface AppSettings {
-  outputDirectory: string;
-  launchAtLogin: boolean;
-  checkForUpdates: boolean;
-  defaultCountdown: 0 | 3 | 5;
-  showTranscriptionPreview: boolean;
-  showAudioWaveform: boolean;
-  pauseThreshold: number;
-  minTimeBetweenCaptures: number;
-  imageFormat: 'png' | 'jpeg';
-  imageQuality: number;
-  maxImageWidth: number;
-  theme: 'dark' | 'light' | 'system';
-  accentColor: string;
-  hotkeys: HotkeyConfig;
-  audioDeviceId: string | null;
-  debugMode: boolean;
-  keepAudioBackups: boolean;
-}
-```
-
-### Capture Types
-
-```typescript
-// Capture source
-interface CaptureSource {
-  id: string;
-  name: string;
-  type: 'screen' | 'window';
-  thumbnail?: string;
-  appIcon?: string;
-  display?: DisplayInfo;
-}
-
-// Display info (multi-monitor)
-interface DisplayInfo {
-  id: number;
-  label: string;
-  bounds: { x: number; y: number; width: number; height: number };
-  workArea: { x: number; y: number; width: number; height: number };
-  scaleFactor: number;
-  isPrimary: boolean;
-  rotation: 0 | 90 | 180 | 270;
-  internal: boolean;
-}
-```
-
-For the complete type definitions, see `src/shared/types.ts`.