Contacts Module — Overview¶

Modules/Contacts/
├── Models/
│   ├── ContactModel.swift      # Contact struct (id, contactName, isFavorite, lastInteraction)
│   ├── FriendRequest.swift      # FriendRequest struct with date formatting
│   └── FriendAddMode.swift      # Enum: scan | autoImport
├── Services/
│   └── ContactsAPIService.swift # Singleton — all API calls
├── ViewModels/
│   ├── ContactsViewModel.swift      # Shared state: contacts list + badge count
│   ├── AddFriendViewModel.swift     # QR parsing, token validation, send request
│   └── FriendRequestsViewModel.swift
└── Views/
    ├── ContactsView.swift       # Main tab view with search + list
    ├── ContactsListView.swift   # Favorites / All sections
    ├── ContactRow.swift         # Single contact row with call buttons
    ├── AddFriendView.swift      # Add friend modal (scan/import modes)
    ├── QRScannerView.swift      # AVFoundation camera scanner
    ├── FriendRequestsView.swift # Received + Sent tabs
    ├── ReceivedRequestRow.swift
    ├── SentRequestRow.swift
    ├── SelectContactListView.swift
    ├── EmptyStateView.swift
    └── ImagePicker.swift        # Photo library QR import

┌─────────┐   Send Request    ┌──────────┐
│  User A  │ ──────────────►  │  User B   │
│ (sender) │                  │(receiver) │
└─────────┘                  └──────────┘
     │                              │
     │  POST /friend-request/by-id
     │             or
     │  POST /friend-request/by-token
     │                              │
     │                   Push notification (.newFriendRequested)
     │                              │
     │                    ┌─────────▼──────────┐
     │                    │  Accept / Decline   │
     │                    └─────────┬──────────┘
     │                              │
     │              POST /friend-request/accept
     │              or PATCH /friend-request/decline
     │                              │
     │                   Push notification (.acceptFriendRequested)
     │                              │
     ▼                              ▼
  Both users' contact lists reload automatically

User opens QR popup (Settings / Contacts)
    │
    ▼
MyQRCodeViewModel.init()
    └── loadCredentials() → reads userId, displayName from KeyStorage

View.onAppear:
    └── Task { await viewModel.requestAndGenerateQR() }
            │
            ▼
        POST /app/api/share-token   ← bearer token auth
            │  Backend:
            │    ├── Rate limit: 20 tokens/hour/user
            │    ├── crypto/rand 32 bytes → base62 (43 chars)
            │    └── INSERT share_tokens (TTL: 24 hours, Max Uses: 1)
            ▼
        { token: "a8KxR3mFvL2pNqW7..." }
            │
            ▼
        deepLink = AppEnvironment.shareContactURL(token:)
        → https://{domain}/share/contact/{token}
            │
            ▼
        generateQRCode(deepLink) → UIImage (CoreImage/QR)

Scan QR / Import Photo / Universal Link / Deep Link
    │
    ▼
validateAndSetQRPayload(scannedString)
    │
    ├── Extract token from URL
    │     ├── Universal link: https://{domain}/share/contact/{token}
    │     ├── Deep link:      ecall://contact/{token}
    │     └── Numeric:        use raw string as userId directly
    │
    ├── UInt64(token) != nil?
    │   YES → Numeric userId (e.g. Call History)
    │         Use `POST /app/api/friend-request/by-id` directly
    │
    └── NO → Opaque Server Token
          scannedQRPayload = url
          Task { await resolveServerToken(url) }
              │
              ▼
          POST /app/api/share-token/resolve { token }
              │  Backend validates:
              │    ├── exists + not expired (within 24h)
              │    ├── used_count < max_uses
              │    └── resolver ≠ creator (self-resolve guard)
              │  (Note: Token is NOT burned here)
              ▼
          { token: String, displayName: String }
              → resolvedContact set → token/displayName computed props update

    *Note: When sending the friend request, if resolvedContact provides a token, we use `POST /app/api/friend-request/by-token`. If we only have a numeric userId, we use `POST /app/api/friend-request/by-id`.*

.onOpenURL { url in
    guard AppUtils.validUrlApp(url) else { return }
    addFriendVM.importedQRPayload = url.absoluteString
    showAddFriendSheet = true
    // Resolve server tokens async
    Task { await addFriendVM.resolveServerToken(url.absoluteString) }
}

struct ShareTokenResponse: Codable {
    let token: String
}

struct ResolveTokenRequest: Encodable {
    let token: String
}

struct ResolvedContact: Codable {
    let token: String
    let displayName: String
}