# MLS.BH / RESO integration handoff

## Supported baseline

The adapter targets a RESO Web API/OData Property resource using OAuth 2 client credentials, JSON responses, incremental `ModificationTimestamp` filtering, OData pagination and optional Media expansion. Source payloads are retained in `listings.raw_payload` so local-field mappings can be added without losing information.

## Integration points

- `config/services.php`: environment-backed MLS configuration.
- `app/Services/Mls/MlsClient.php`: OAuth, metadata, Property retrieval and Add/Edit transport.
- `app/Services/Mls/PropertyMapper.php`: RESO-to-local mapping.
- `app/Jobs/PullMlsListings.php`: incremental, queued ingestion.
- `app/Jobs/PushMlsListing.php`: guarded Add/Edit delivery.
- `sync_runs`: operational history and cursor storage.

## Developer checklist

1. Confirm the MLS.BH RESO Web API Core and Data Dictionary versions.
2. Retrieve and archive the `$metadata` document.
3. Confirm OAuth token parameters and token lifetime.
4. Confirm whether resource keys use OData parentheses, path segments or another vendor convention.
5. Map MLS.BH local fields and Lookup values in `PropertyMapper`.
6. Confirm whether Media is expandable or must be queried separately.
7. Confirm paging property names and maximum `$top`.
8. Confirm replication requirements, deletion/tombstone handling and permitted sync frequency.
9. Confirm which statuses must disappear publicly and the required timing.
10. Confirm cache, media, attribution, disclaimer, sold-data and retention rules.
11. Keep push disabled unless the syndication agreement explicitly permits Add/Edit.
12. Add contract tests using sanitized MLS.BH fixtures before staging activation.

## Pull behavior

The first run imports from the beginning of the accessible feed. Successful runs store the latest modification cursor. Subsequent runs request records with a later `ModificationTimestamp`. The job prevents overlap, follows `@odata.nextLink`, retries transient HTTP failures, and upserts by `ListingKey`.

For a large initial feed, MLS.BH may require date windows or replication endpoints. Adjust the job before the first production run if advised by the provider.

## Push behavior

Push is separately protected by `MLS_PUSH_ENABLED`. The current command maps a safe Property subset. It is a transport scaffold—not authorization to modify MLS.BH. Field requirements, write permissions, concurrency/ETag rules, validation responses and brokerage ownership must be implemented from the MLS.BH Add/Edit specification.

## Demo-data cutover

1. Back up the database.
2. Test metadata and one-page reads in staging.
3. Run the initial import and compare counts/status distributions.
4. Validate images, attribution and public visibility.
5. Delete records where `sync_source=demo` after approval.
6. Enable the 15-minute schedule.
7. Monitor failed jobs and `sync_runs` for at least 72 hours.