# Contingent API Status

## Summary
The contingent API is implemented on `master`. It serves cached availability data from `HotelZimmer_*.xml` files in `var/xmlexportzimmer`, using Flysystem and the tag-aware `bpn.cache` pool. XML sync now covers both travel and contingent datasets, invalidates `xml-sync` tagged cache entries, and logs dataset transfer errors without aborting the command.

## Implemented
- OAuth-protected endpoints:
  - `GET /api/contingents?hotelRef={hotelRef}&dateRef={dateRef}`
  - `GET /api/contingents/rooms?hotelRef={hotelRef}&dateRef={dateRef}&dateFrom={Y-m-d}&dateTo={Y-m-d}`
  - `GET /api/contingents/calendar?hotelRef={hotelRef}&dateFrom={Y-m-d}&dateTo={Y-m-d}`
- `hotelRef` and `dateRef` accept numeric IDs or business codes; date codes are sanitized before lookup.
- Parser/loader/service/controller flow is implemented via `ContingentParser`, `ContingentLoader`, `ContingentDataService`, and `ContingentController`.
- Room responses include per date + room availability, pricing, status, and `bookingUrl`.
- BelKal control-room rows override date status and set room availability to `0` for affected dates.
- Room-level contingent links and one-hop root-level file links are supported.
- `app:bpn:xml-sync` syncs travel and contingents, invalidates `xml-sync` cache tags, and refreshes travel snapshots only when travel data synced.
- `app:bpn:xml-cache-invalidate` checks both travel and contingent local XML exports.

## Config
- `.env` defines `XML_EXPORT_CONTINGENTS_PATH` and `SFTP_XML_EXPORT_CONTINGENTS_*`.
- `config/packages/flysystem.yaml` defines:
  - `xml_export_contingents.storage`
  - `xml_source_contingents.storage`
- `config/services.yaml` wires contingent storage, `bpn.cache`, and `APP_BASE_URL` for booking URL generation.

## Behavior Notes
- Missing contingent XML returns empty data.
- Unknown travel/date or hotel/date mismatches return `404` from the API.
- Invalid date ranges or formats return `400`.
- Dataset transfer failures are shown and logged as warnings, but `app:bpn:xml-sync` still completes with exit code `0`.

## Remaining TODOs
- Decide whether room responses still need travel metadata fields such as `summer`, `servicesIncluded`, and `servicesOptional`; these are not currently implemented.
- If the XML files grow materially or cold-cache parsing becomes slow, revisit whether `ContingentParser` should move from DOM/Crawler parsing to a streaming parser.
- Validate the deployed contingent SFTP environment variables before enabling scheduled sync in production.

## Verification
- Covered by parser, loader, data service, controller, booking URL, XML sync, and cache invalidation tests.
- Current verification command: `php bin/phpunit`.