# 13. CallKit Integration for SpamShield

meta:
  id: ios-production-13
  feature: ios-production
  priority: P1
  depends_on: []
  tags: [native-features, spamshield, production]

objective:
- Integrate SpamShield with CallKit to identify and block spam calls at the system level

deliverables:
- CallKit extension for call identification
- Spam database sync
- Real-time caller lookup
- User-managed block list

steps:
1. Create CallKit extension:
   - Add Call Directory Extension target in Xcode
   - Implement CXCallDirectoryProvider
   - Handle reloadExtensionRequests
   - Add to app group for shared data
2. Implement caller identification:
   - Lookup incoming numbers against spam database
   - Display caller ID label ("Spam: Telemarketer")
   - Use local cached database for speed
   - Fall back to API lookup for unknown numbers
3. Implement call blocking:
   - Block known spam numbers
   - Block user-defined patterns
   - Sync block list from app settings
   - Handle block list updates
4. Sync spam database:
   - Download updated spam numbers periodically
   - Store in shared app group container
   - Update Call Directory on sync
   - Respect user privacy (hashed numbers where possible)
5. Add user controls:
   - Settings toggle for call identification
   - Settings toggle for call blocking
   - Manage blocked numbers list
   - Report false positives
6. Handle permissions:
   - Request Call Directory extension enablement
   - Guide user to Settings → Phone → Call Blocking
   - Check extension status on app launch

tests:
- Unit: Test number lookup against spam database
- Integration: Test Call Directory update
- Device: Test with actual spam call (simulated)

acceptance_criteria:
- CallKit extension installed and enabled
- Incoming spam calls identified with label
- Known spam numbers automatically blocked
- Spam database synced daily
- User can enable/disable identification and blocking
- Block list manageable from app settings
- Extension updates without app restart
- False positive reporting mechanism
- Privacy: number lookups local where possible
- App guides users to enable extension in Settings

validation:
- Enable extension in Settings → calls identified
- Receive call from known spam number → blocked/identified
- Update spam database → Call Directory refreshed
- Disable in app → extension stops working
- Report false positive → number removed from block list

notes:
- Call Directory extensions have strict memory limits (17MB)
- Apple reviews CallKit extensions carefully
- Extension runs separately from main app
- Use app groups for sharing data between app and extension
- Users must manually enable extension in Settings