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

@@ -1,5 +1,40 @@
+/**
+ * API error handling utilities for the application.
+ * Provides centralized error handling for API requests with platform-specific logging.
+ * 
+ * @module api
+ */
+
 import { AxiosError } from "axios";
 import { logger } from "../utils/logger";
+
+/**
+ * Handles API errors with platform-specific logging and error processing.
+ * 
+ * @param error - The Axios error object from the failed request
+ * @param endpoint - The API endpoint that was called
+ * @returns null for rate limit errors (400), throws the error otherwise
+ * @throws The original error for non-rate-limit cases
+ * 
+ * @remarks
+ * Special handling includes:
+ * - Enhanced logging for Capacitor platform
+ * - Rate limit detection and handling
+ * - Detailed error information logging including:
+ *   - Error message
+ *   - HTTP status
+ *   - Response data
+ *   - Request configuration (URL, method, headers)
+ * 
+ * @example
+ * ```typescript
+ * try {
+ *   await api.getData();
+ * } catch (error) {
+ *   handleApiError(error as AxiosError, '/api/data');
+ * }
+ * ```
+ */
 export const handleApiError = (error: AxiosError, endpoint: string) => {
   if (process.env.VITE_PLATFORM === "capacitor") {
     logger.error(`[Capacitor API Error] ${endpoint}:`, {