crowd-funder-for-time-pwa/docs/DEEP_LINKS.md

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

// 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

All deep links follow the format: timesafari://<route>/<param>?<query>

Claim Routes

• timesafari://claim/:id

  • Query params:
    • view: "details" | "certificate" | "raw"

• timesafari://claim-cert/:id

• timesafari://claim-add-raw/:id

  • Query params:
    • claim: JSON string of claim data
    • claimJwtId: JWT ID for claim

Contact Routes

• timesafari://contact-edit/:did
• timesafari://contact-import/:jwt
  • Query params:
    • contacts: JSON array of contacts

Project Routes

• timesafari://project/:id
  • Query params:
    • view: "details" | "edit"

Invite Routes

• timesafari://invite-one-accept/:jwt
  • Query params:
    • type: "one" | "many"

Gift Routes

• timesafari://confirm-gift/:id
  • Query params:
    • action: "confirm" | "details"

Offer Routes

• timesafari://offer-details/:id
  • Query params:
    • view: "details"