docs: add comprehensive JSDoc documentation to service layer

Add detailed TypeScript JSDoc documentation to core service modules:
- api.ts: Document error handling utilities and platform-specific logging
- plan.ts: Document plan/claim loading with retry mechanism
- deepLinks.ts: Document URL parsing and routing functionality
- Platform services:
  - CapacitorPlatformService: Document mobile platform capabilities
  - ElectronPlatformService: Document desktop placeholder implementation
  - PyWebViewPlatformService: Document Python bridge placeholder
  - WebPlatformService: Document web platform limitations and features

Key improvements:
- Add detailed @remarks sections explaining implementation details
- Include usage examples with TypeScript code snippets
- Document error handling and platform-specific behaviors
- Add @todo tags for unimplemented features
- Fix PlanResponse interface to include headers property

This documentation enhances code maintainability and developer experience
by providing clear guidance on service layer functionality and usage.

src/services/platforms/ElectronPlatformService.ts

@@ -1,49 +1,122 @@
 import { ImageResult, PlatformService } from "../PlatformService";
 import { logger } from "../../utils/logger";
 
+/**
+ * Platform service implementation for Electron (desktop) platform.
+ * Note: This is a placeholder implementation with most methods currently unimplemented.
+ * Implements the PlatformService interface but throws "Not implemented" errors for most operations.
+ * 
+ * @remarks
+ * This service is intended for desktop application functionality through Electron.
+ * Future implementations should provide:
+ * - Native file system access
+ * - Desktop camera integration
+ * - System-level features
+ */
 export class ElectronPlatformService implements PlatformService {
+  /**
+   * Reads a file from the filesystem.
+   * @param _path - Path to the file to read
+   * @returns Promise that should resolve to file contents
+   * @throws Error with "Not implemented" message
+   * @todo Implement file reading using Electron's file system API
+   */
   async readFile(_path: string): Promise<string> {
     throw new Error("Not implemented");
   }
 
+  /**
+   * Writes content to a file.
+   * @param _path - Path where to write the file
+   * @param _content - Content to write to the file
+   * @throws Error with "Not implemented" message
+   * @todo Implement file writing using Electron's file system API
+   */
   async writeFile(_path: string, _content: string): Promise<void> {
     throw new Error("Not implemented");
   }
 
+  /**
+   * Deletes a file from the filesystem.
+   * @param _path - Path to the file to delete
+   * @throws Error with "Not implemented" message
+   * @todo Implement file deletion using Electron's file system API
+   */
   async deleteFile(_path: string): Promise<void> {
     throw new Error("Not implemented");
   }
 
+  /**
+   * Lists files in the specified directory.
+   * @param _directory - Path to the directory to list
+   * @returns Promise that should resolve to array of filenames
+   * @throws Error with "Not implemented" message
+   * @todo Implement directory listing using Electron's file system API
+   */
   async listFiles(_directory: string): Promise<string[]> {
     throw new Error("Not implemented");
   }
 
+  /**
+   * Should open system camera to take a picture.
+   * @returns Promise that should resolve to captured image data
+   * @throws Error with "Not implemented" message
+   * @todo Implement camera access using Electron's media APIs
+   */
   async takePicture(): Promise<ImageResult> {
     logger.error("takePicture not implemented in Electron platform");
     throw new Error("Not implemented");
   }
 
+  /**
+   * Should open system file picker for selecting an image.
+   * @returns Promise that should resolve to selected image data
+   * @throws Error with "Not implemented" message
+   * @todo Implement file picker using Electron's dialog API
+   */
   async pickImage(): Promise<ImageResult> {
     logger.error("pickImage not implemented in Electron platform");
     throw new Error("Not implemented");
   }
 
+  /**
+   * Checks if running on Capacitor platform.
+   * @returns false, as this is not Capacitor
+   */
   isCapacitor(): boolean {
     return false;
   }
 
+  /**
+   * Checks if running on Electron platform.
+   * @returns true, as this is the Electron implementation
+   */
   isElectron(): boolean {
     return true;
   }
 
+  /**
+   * Checks if running on PyWebView platform.
+   * @returns false, as this is not PyWebView
+   */
   isPyWebView(): boolean {
     return false;
   }
 
+  /**
+   * Checks if running on web platform.
+   * @returns false, as this is not web
+   */
   isWeb(): boolean {
     return false;
   }
 
+  /**
+   * Should handle deep link URLs for the desktop application.
+   * @param _url - The deep link URL to handle
+   * @throws Error with "Not implemented" message
+   * @todo Implement deep link handling using Electron's protocol handler
+   */
   async handleDeepLink(_url: string): Promise<void> {
     logger.error("handleDeepLink not implemented in Electron platform");
     throw new Error("Not implemented");