From 9d04db4a71b67c9ab6687e54ecfebc3ed5fdfc4d Mon Sep 17 00:00:00 2001 From: Matthew Raymer Date: Wed, 26 Feb 2025 09:45:08 +0000 Subject: [PATCH] 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 | 45 +++++++++++++++++++++++- src/main.capacitor.ts | 72 ++++++++++++++++----------------------- src/services/deepLinks.ts | 30 ++++++++++++++++ src/types/deepLinks.ts | 27 +++++++++++++++ 4 files changed, 130 insertions(+), 44 deletions(-) diff --git a/docs/DEEP_LINKS.md b/docs/DEEP_LINKS.md index d998bac..ba6f728 100644 --- a/docs/DEEP_LINKS.md +++ b/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 diff --git a/src/main.capacitor.ts b/src/main.capacitor.ts index 283bc4a..24fbe27 100644 --- a/src/main.capacitor.ts +++ b/src/main.capacitor.ts @@ -1,47 +1,31 @@ /** - * @file Capacitor Platform Entry Point - * @description Initializes the application for Capacitor platform (iOS/Android) + * @file Capacitor Main Entry Point * @author Matthew Raymer - * @version 0.4.4 - * - * Process Flow: - * 1. Initialization - * - Logs start of initialization - * - Logs current platform - * - Initializes core application via main.common - * - * 2. Error Handling Setup - * - Registers global unhandled promise rejection handler - * - Routes API errors to error handling system - * - * 3. Deep Linking Configuration - * - Registers URL scheme handler (timesafari://) - * - Supports 11 parameterized routes: - * * claim-add-raw - * * claim-cert - * * claim - * * confirm-gift - * * contact-edit - * * contact-import - * * did - * * invite-one-accept - * * offer-details - * * project - * * 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:/// - * timesafari://claim/01JMAAFZRNSRTQ0EBSD70A8E1H + * + * This file initializes the deep linking system for the TimeSafari app. + * It sets up the connection between Capacitor's URL handling and our deep link processor. + * + * Deep Linking Flow: + * 1. Capacitor receives URL open event + * 2. Event is passed to DeepLinkHandler + * 3. URL is validated and processed + * 4. Router navigates to appropriate view + * + * Integration Points: + * - Capacitor App plugin for URL handling + * - Vue Router for navigation + * - Error handling system + * - Logging system + * + * Type Safety: + * - Uses DeepLinkHandler for type-safe parameter processing + * - Ensures type safety between Capacitor events and app routing + * - Maintains type checking through the entire deep link flow + * + * @example + * // URL open event from OS + * timesafari://claim/123?view=details + * // Processed and routed to appropriate view with type-safe parameters */ 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"); } }; diff --git a/src/services/deepLinks.ts b/src/services/deepLinks.ts index b6ee52e..19be23c 100644 --- a/src/services/deepLinks.ts +++ b/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"; diff --git a/src/types/deepLinks.ts b/src/types/deepLinks.ts index 4c1d4e7..14e0180 100644 --- a/src/types/deepLinks.ts +++ b/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