# 09. Attom Data Solutions API for Property Record Snapshots

meta:
  id: core-services-09
  feature: core-services-implementation
  priority: P2
  depends_on: [core-services-01]
  tags: [hometitle, attom, property-records, api-integration, real-estate]

objective:
- Replace the `fetchCountyRecords()` stub that returns `{ ownerName: "Unknown Owner" }` with a real property data API integration using Attom Data Solutions, enabling actual property snapshot and change detection.

deliverables:
- Attom API client for property search, owner info, and tax/assessment data
- Property snapshot creation and storage in database
- Change detection pipeline wired to real data (your detector logic already works)
- Alert generation for ownership changes, liens, and tax status changes

steps:
1. Sign up for Attom Data API at https://attomdata.com (pricing: ~$0.05–$0.10/record, enterprise plans available)
2. Add `ATTOM_API_KEY` to `.env.example` and validate in `env.ts`
3. Create `hometitle/attom.client.ts`:
   - `searchProperty(address)` — find property by address, return parcel ID and metadata
   - `getPropertyProfile(parcelId)` — full property record: owner, deed date, tax info, liens
   - `getPropertyHistory(parcelId)` — historical ownership and transaction records
   - `getTaxInfo(parcelId)` — tax amount, delinquency status, exemptions
4. Replace `fetchCountyRecords()` in `scanner.ts` with Attom API call:
   - Use geocoding result (Google Maps API, already works) to get normalized address
   - Query Attom by address → get parcel ID → fetch full property profile
   - Parse response into `CountyRecord` / `SnapshotData` schema
5. Implement snapshot storage:
   - Store initial snapshot in `propertySnapshots` table
   - On re-scan, fetch new snapshot → compare with last → detect changes
6. Wire change detection (your `change.detector.ts` is already implemented):
   - `ownership_transfer`: owner name changed → critical alert
   - `lien_filing`: lien count increased → warning/critical alert
   - `tax_change`: tax amount changed → info alert
   - `deed_change`: deed date changed → critical alert
7. Implement tier limits:
   - Guard: 1 property monitored
   - Fortress: 3 properties monitored
   - Family: 5 properties monitored
8. Add cost tracking: ~$0.05–$0.10 per property lookup, track per-user usage

tests:
- Unit: Mock Attom API responses, verify parsing and snapshot creation
- Integration: Test with real Attom API using known property address
- E2E: Add property to watchlist → trigger scan → verify snapshot created → simulate change → verify alert

acceptance_criteria:
- [ ] `fetchCountyRecords()` makes real HTTP request to Attom API (not returning mock data)
- [ ] Property snapshots contain real owner name, deed date, tax amount, lien count
- [ ] Change detection compares real snapshots and identifies actual changes
- [ ] Ownership transfer creates critical alert with property address in message
- [ ] Lien filing creates warning or critical alert depending on lien amount
- [ ] Alert severity matches existing `severityForChange()` logic
- [ ] Geocoding → Attom search → snapshot pipeline works end-to-end
- [ ] Cost tracking records each Attom API call for billing analytics
- [ ] Tier limits enforced: Guard = 1 property, Fortress = 3, Family = 5
- [ ] Graceful fallback: if Attom API fails, retry once, then alert user of monitoring gap

validation:
- Run `vitest run hometitle.test.ts` — all tests pass with real Attom mock
- Manual: Add real property address, trigger scan, verify snapshot in database
- Simulate change: Update snapshot in database with different owner, trigger detector, verify alert
- Check cost: Database shows Attom API usage per user per month

notes:
- Attom covers ~150M US properties but not all counties equally — some rural areas may have gaps
- For counties not covered by Attom, Phase 3 (task 10) implements county recorder web scrapers
- Property fraud is a real and growing problem: FTC reports $1B+ in losses annually
- This is a unique differentiator — no major identity protection competitor offers property monitoring
- Consider partnership with title insurance companies for added credibility
- The existing Google Maps geocoding already works — verify `GEOCODING_API_KEY` is set