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/PyWebViewPlatformService.ts

@@ -1,49 +1,123 @@
 import { ImageResult, PlatformService } from "../PlatformService";
 import { logger } from "../../utils/logger";
 
+/**
+ * Platform service implementation for PyWebView 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 Python-based desktop applications using pywebview.
+ * Future implementations should provide:
+ * - Integration with Python backend file operations
+ * - System camera access through Python
+ * - Native system dialogs via pywebview
+ * - Python-JavaScript bridge functionality
+ */
 export class PyWebViewPlatformService implements PlatformService {
+  /**
+   * Reads a file using the Python backend.
+   * @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 through pywebview's Python-JavaScript bridge
+   */
   async readFile(_path: string): Promise<string> {
     throw new Error("Not implemented");
   }
 
+  /**
+   * Writes content to a file using the Python backend.
+   * @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 through pywebview's Python-JavaScript bridge
+   */
   async writeFile(_path: string, _content: string): Promise<void> {
     throw new Error("Not implemented");
   }
 
+  /**
+   * Deletes a file using the Python backend.
+   * @param _path - Path to the file to delete
+   * @throws Error with "Not implemented" message
+   * @todo Implement file deletion through pywebview's Python-JavaScript bridge
+   */
   async deleteFile(_path: string): Promise<void> {
     throw new Error("Not implemented");
   }
 
+  /**
+   * Lists files in the specified directory using the Python backend.
+   * @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 through pywebview's Python-JavaScript bridge
+   */
   async listFiles(_directory: string): Promise<string[]> {
     throw new Error("Not implemented");
   }
 
+  /**
+   * Should open system camera through Python backend.
+   * @returns Promise that should resolve to captured image data
+   * @throws Error with "Not implemented" message
+   * @todo Implement camera access using Python's camera libraries
+   */
   async takePicture(): Promise<ImageResult> {
     logger.error("takePicture not implemented in PyWebView platform");
     throw new Error("Not implemented");
   }
 
+  /**
+   * Should open system file picker through pywebview.
+   * @returns Promise that should resolve to selected image data
+   * @throws Error with "Not implemented" message
+   * @todo Implement file picker using pywebview's file dialog API
+   */
   async pickImage(): Promise<ImageResult> {
     logger.error("pickImage not implemented in PyWebView 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 false, as this is not Electron
+   */
   isElectron(): boolean {
     return false;
   }
 
+  /**
+   * Checks if running on PyWebView platform.
+   * @returns true, as this is the PyWebView implementation
+   */
   isPyWebView(): boolean {
     return true;
   }
 
+  /**
+   * Checks if running on web platform.
+   * @returns false, as this is not web
+   */
   isWeb(): boolean {
     return false;
   }
 
+  /**
+   * Should handle deep link URLs through the Python backend.
+   * @param _url - The deep link URL to handle
+   * @throws Error with "Not implemented" message
+   * @todo Implement deep link handling using Python's URL handling capabilities
+   */
   async handleDeepLink(_url: string): Promise<void> {
     logger.error("handleDeepLink not implemented in PyWebView platform");
     throw new Error("Not implemented");