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

@@ -4,9 +4,32 @@ import { CapacitorPlatformService } from "./platforms/CapacitorPlatformService";
 import { ElectronPlatformService } from "./platforms/ElectronPlatformService";
 import { PyWebViewPlatformService } from "./platforms/PyWebViewPlatformService";
 
+/**
+ * Factory class for creating platform-specific service implementations.
+ * Implements the Singleton pattern to ensure only one instance of PlatformService exists.
+ * 
+ * The factory determines which platform implementation to use based on the VITE_PLATFORM
+ * environment variable. Supported platforms are:
+ * - capacitor: Mobile platform using Capacitor
+ * - electron: Desktop platform using Electron
+ * - pywebview: Python WebView implementation
+ * - web: Default web platform (fallback)
+ * 
+ * @example
+ * ```typescript
+ * const platformService = PlatformServiceFactory.getInstance();
+ * await platformService.takePicture();
+ * ```
+ */
 export class PlatformServiceFactory {
   private static instance: PlatformService | null = null;
 
+  /**
+   * Gets or creates the singleton instance of PlatformService.
+   * Creates the appropriate platform-specific implementation based on environment.
+   * 
+   * @returns {PlatformService} The singleton instance of PlatformService
+   */
   public static getInstance(): PlatformService {
     if (PlatformServiceFactory.instance) {
       return PlatformServiceFactory.instance;