docs: add comprehensive deep linking documentation

Changes:
- Add detailed JSDoc headers to deep linking files
- Document type system and validation strategy
- Add architecture overview and error handling docs
- Include usage examples and integration points
- Improve code organization comments

This improves maintainability by documenting the deep linking
system's architecture, type safety, and integration points.

docs/DEEP_LINKS.md

@@ -1,4 +1,47 @@
-# TimeSafari Deep Linking
+# TimeSafari Deep Linking Documentation
+
+## Type System Overview
+
+The deep linking system uses a multi-layered type safety approach:
+
+1. **Runtime Validation (Zod Schemas)**
+   - Validates URL structure
+   - Enforces parameter requirements
+   - Sanitizes input data
+   - Provides detailed validation errors
+
+2. **TypeScript Types**
+   - Generated from Zod schemas
+   - Ensures compile-time type safety
+   - Provides IDE autocompletion
+   - Catches type errors during development
+
+3. **Router Integration**
+   - Type-safe parameter passing
+   - Route-specific parameter validation
+   - Query parameter type checking
+
+## Implementation Files
+
+- `src/types/deepLinks.ts`: Type definitions and validation schemas
+- `src/services/deepLinks.ts`: Deep link processing service
+- `src/main.capacitor.ts`: Capacitor integration
+
+## Type Safety Examples
+
+```typescript
+// Parameter type safety
+type ClaimParams = DeepLinkParams["claim"];
+// TypeScript knows this has:
+// - id: string
+// - view?: "details" | "certificate" | "raw"
+// Runtime validation
+const result = deepLinkSchemas.claim.safeParse({
+id: "123",
+view: "details"
+});
+// Validates at runtime with detailed error messages
+```
 
 ## Supported URL Schemes
 

src/main.capacitor.ts

@@ -1,47 +1,31 @@
 /**
- * @file Capacitor Platform Entry Point
+ * @file Capacitor Main Entry Point
- * @description Initializes the application for Capacitor platform (iOS/Android)
  * @author Matthew Raymer
- * @version 0.4.4
+ * 
- *
+ * This file initializes the deep linking system for the TimeSafari app.
- * Process Flow:
+ * It sets up the connection between Capacitor's URL handling and our deep link processor.
- * 1. Initialization
+ * 
- *    - Logs start of initialization
+ * Deep Linking Flow:
- *    - Logs current platform
+ * 1. Capacitor receives URL open event
- *    - Initializes core application via main.common
+ * 2. Event is passed to DeepLinkHandler
- *
+ * 3. URL is validated and processed
- * 2. Error Handling Setup
+ * 4. Router navigates to appropriate view
- *    - Registers global unhandled promise rejection handler
+ * 
- *    - Routes API errors to error handling system
+ * Integration Points:
- *
+ * - Capacitor App plugin for URL handling
- * 3. Deep Linking Configuration
+ * - Vue Router for navigation
- *    - Registers URL scheme handler (timesafari://)
+ * - Error handling system
- *    - Supports 11 parameterized routes:
+ * - Logging system
- *      * claim-add-raw
+ * 
- *      * claim-cert
+ * Type Safety:
- *      * claim
+ * - Uses DeepLinkHandler for type-safe parameter processing
- *      * confirm-gift
+ * - Ensures type safety between Capacitor events and app routing
- *      * contact-edit
+ * - Maintains type checking through the entire deep link flow
- *      * contact-import
+ * 
- *      * did
+ * @example
- *      * invite-one-accept
+ * // URL open event from OS
- *      * offer-details
+ * timesafari://claim/123?view=details
- *      * project
+ * // Processed and routed to appropriate view with type-safe parameters
- *      * userProfile
- *
- * 4. Application Mounting
- *    - Mounts Vue application to DOM
- *    - Logs completion of mounting process
- *
- * Security Measures:
- * - URL validation before processing
- * - Type-safe error handling
- * - Parameterized route pattern matching
- * - Comprehensive error logging
- *
- * @example Deep Link Format
- * timesafari://<route>/<parameter>
- * timesafari://claim/01JMAAFZRNSRTQ0EBSD70A8E1H
  */
 
 import { initializeApp } from "./main.common";
@@ -88,7 +72,9 @@ const handleDeepLink = async (data: { url: string }) => {
     await deepLinkHandler.handleDeepLink(data.url);
   } catch (error) {
     logConsoleAndDb("[DeepLink] Error handling deep link: " + error, true);
-    handleApiError(error, "deep-link");
+    handleApiError({ 
+      message: error instanceof Error ? error.message : String(error)
+    } as AxiosError, "deep-link");
   }
 };
 

src/services/deepLinks.ts

@@ -1,3 +1,33 @@
+/**
+ * @file Deep Link Handler Service
+ * @author Matthew Raymer
+ * 
+ * This service handles the processing and routing of deep links in the TimeSafari app.
+ * It provides a type-safe interface between the raw deep links and the application router.
+ * 
+ * Architecture:
+ * 1. DeepLinkHandler class encapsulates all deep link processing logic
+ * 2. Uses Zod schemas from types/deepLinks for parameter validation
+ * 3. Provides consistent error handling and logging
+ * 4. Maps validated parameters to Vue router calls
+ * 
+ * Error Handling Strategy:
+ * - All errors are wrapped in DeepLinkError interface
+ * - Errors include error codes for systematic handling
+ * - Detailed error information is logged for debugging
+ * - Errors are propagated to the global error handler
+ * 
+ * Validation Strategy:
+ * - URL structure validation
+ * - Route-specific parameter validation using Zod schemas
+ * - Query parameter validation and sanitization
+ * - Type-safe parameter passing to router
+ * 
+ * @example
+ * const handler = new DeepLinkHandler(router);
+ * await handler.handleDeepLink("timesafari://claim/123?view=details");
+ */
+
 import { Router } from "vue-router";
 import { deepLinkSchemas, DeepLinkParams } from "../types/deepLinks";
 import { logConsoleAndDb } from "../db";

src/types/deepLinks.ts

@@ -1,3 +1,30 @@
+/**
+ * @file Deep Link Type Definitions and Validation Schemas
+ * @author Matthew Raymer
+ * 
+ * This file defines the type system and validation schemas for deep linking in the TimeSafari app.
+ * It uses Zod for runtime validation while providing TypeScript types for compile-time checking.
+ * 
+ * Type Strategy:
+ * 1. Define base URL schema to validate the fundamental deep link structure
+ * 2. Define route-specific parameter schemas with exact validation rules
+ * 3. Generate TypeScript types from Zod schemas for type safety
+ * 4. Export both schemas and types for use in deep link handling
+ * 
+ * Usage:
+ * - Import schemas for runtime validation in deep link handlers
+ * - Import types for type-safe parameter handling in components
+ * - Use DeepLinkParams type for type-safe access to route parameters
+ * 
+ * @example
+ * // Runtime validation
+ * const params = deepLinkSchemas.claim.parse({ id: "123", view: "details" });
+ * 
+ * // Type-safe parameter access
+ * function handleClaimParams(params: DeepLinkParams["claim"]) {
+ *   // TypeScript knows params.id exists and params.view is optional
+ * }
+ */
 import { z } from "zod";
 
 // Base URL validation schema