# 18 — MLS Integration

## Context
Fogbreak replaces RealScout's MLS data and ShowingTime's MLS integration. Real-time listing data is the backbone of property alerts, matching, marketing, and showing management.

## What to Build

### 1. RETS/RESO Web API Client
Create `app/api/mls.php`:
- Connect to MLS data feeds via RETS or RESO Web API
- MLS provider and credentials stored per market in `market_configs` table
- Field mapping via `mls_field_mappings` table (market-specific)
- Pull: active listings, pending, sold, withdrawn, expired

### 2. Data Sync Engine
- Full sync on initial connection (all active listings)
- Incremental sync every 15 minutes (new/changed/removed)
- Photo download and storage
- Listing status change detection
- Data normalization to Fogbreak schema

### 3. Event Detection
On each sync, detect and trigger:
- **New listing**: Create property, generate AI description, trigger alerts, auto-generate social/video
- **Price reduction**: Alert interested clients, trigger social post
- **Status change** (active → pending → sold): Update pipeline, notify agents
- **Back on market**: Alert clients who previously viewed
- **Days on market milestones**: 30, 60, 90 days → suggest price adjustment
- **Expired listings**: Lead opportunity for listing agents

### 4. Inventory Analytics
From MLS data, calculate market metrics:
- Active inventory count and trend
- Median days on market
- Median sale price and trend
- List-to-sale price ratio
- Months of supply
- New listings per week
- Price per square foot by area
- Absorption rate

Store in `market_stats` table for dashboard and AI context.

### 5. Multi-MLS Support
Agents may be in multiple MLS systems:
- Support N MLS connections per tenant
- Deduplicate listings across MLSs
- Unified property view regardless of source MLS

### 6. Compliance
- Respect MLS data use policies
- Include required MLS attribution
- Honor photo usage rights
- IDX/VOW compliance for client-facing display

## Endpoints
```
POST /api/mls.php?action=connect           # Add MLS connection
POST /api/mls.php?action=sync              # Trigger manual sync
GET  /api/mls.php?action=status            # Sync status
GET  /api/mls.php?action=stats             # Market statistics
GET  /api/mls.php?action=new_listings      # Recent new listings
GET  /api/mls.php?action=price_changes     # Recent price changes
```

## Cron Jobs
- `mls_sync`: Every 15 min, incremental sync
- `mls_full_sync`: Weekly, full reconciliation
- `mls_stats`: Daily, recalculate market statistics
- `mls_event_triggers`: Process detected events → alerts, social, etc.

## Acceptance Criteria
- [ ] RETS and RESO Web API client
- [ ] Market-specific field mapping from database
- [ ] Incremental sync every 15 minutes
- [ ] Event detection (new, price change, status change, expired)
- [ ] Events trigger alerts, social posts, AI descriptions
- [ ] Inventory analytics dashboard
- [ ] Multi-MLS support with deduplication
- [ ] MLS compliance (attribution, photo rights)