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

@@ -1,25 +1,94 @@
+/**
+ * Represents the result of an image capture or selection operation.
+ * Contains both the image data as a Blob and the associated filename.
+ */
 export interface ImageResult {
+  /** The image data as a Blob object */
   blob: Blob;
+  /** The filename associated with the image */
   fileName: string;
 }
 
+/**
+ * Platform-agnostic interface for handling platform-specific operations.
+ * Provides a common API for file system operations, camera interactions,
+ * platform detection, and deep linking across different platforms
+ * (web, mobile, desktop).
+ */
 export interface PlatformService {
   // File system operations
+  /**
+   * Reads the contents of a file at the specified path.
+   * @param path - The path to the file to read
+   * @returns Promise resolving to the file contents as a string
+   */
   readFile(path: string): Promise<string>;
+
+  /**
+   * Writes content to a file at the specified path.
+   * @param path - The path where the file should be written
+   * @param content - The content to write to the file
+   * @returns Promise that resolves when the write is complete
+   */
   writeFile(path: string, content: string): Promise<void>;
+
+  /**
+   * Deletes a file at the specified path.
+   * @param path - The path to the file to delete
+   * @returns Promise that resolves when the deletion is complete
+   */
   deleteFile(path: string): Promise<void>;
+
+  /**
+   * Lists all files in the specified directory.
+   * @param directory - The directory path to list
+   * @returns Promise resolving to an array of filenames
+   */
   listFiles(directory: string): Promise<string[]>;
 
   // Camera operations
+  /**
+   * Activates the device camera to take a picture.
+   * @returns Promise resolving to the captured image result
+   */
   takePicture(): Promise<ImageResult>;
+
+  /**
+   * Opens a file picker to select an existing image.
+   * @returns Promise resolving to the selected image result
+   */
   pickImage(): Promise<ImageResult>;
 
   // Platform specific features
+  /**
+   * Checks if the current platform is Capacitor (mobile).
+   * @returns true if running on Capacitor
+   */
   isCapacitor(): boolean;
+
+  /**
+   * Checks if the current platform is Electron (desktop).
+   * @returns true if running on Electron
+   */
   isElectron(): boolean;
+
+  /**
+   * Checks if the current platform is PyWebView.
+   * @returns true if running on PyWebView
+   */
   isPyWebView(): boolean;
+
+  /**
+   * Checks if the current platform is web browser.
+   * @returns true if running in a web browser
+   */
   isWeb(): boolean;
 
   // Deep linking
+  /**
+   * Handles deep link URLs for the application.
+   * @param url - The deep link URL to handle
+   * @returns Promise that resolves when the deep link has been handled
+   */
   handleDeepLink(url: string): Promise<void>;
 }