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

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

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"