feat: add raw contingent availability endpoint

docs/api-consumer-guide.md

@@ -507,6 +507,27 @@ Errors: `400 {"error":"Hotel not found for hotelCode."}`, `400` with violations
 
 `502 {"error":"Failed to fetch contingent data."}` is still returned — with the same body as before — but it now means **"no usable local snapshot for this hotel"** rather than "the upstream call failed": either the hotel has never synced successfully, or its last successful sync is more than 6 hours old. Treat it as before: the data is unavailable, not empty. This matters because the alternative would be a `200` reporting every day as `BLOCKED`, which is indistinguishable from a genuinely fully-booked hotel.
 
+#### `GET /api/contingents/availability?hotelCode=…&dateFrom=…&dateTo=…` — scope `api`
+
+The raw contingent snapshot per day, without prices. Built for the iCal feed that external booking portals import, which blocks only what the contingent itself reports as unavailable.
+
+Parameters are the same as for `calendar`: `hotelCode` is required, `dateFrom` and `dateTo` are optional, `Y-m-d`, inclusive, and must be supplied together (at most 366 days). **Omit both to get every snapshot day from today to the end of the snapshot** (the 24-month sync horizon). Prices play no part in that span.
+
+Each entry, ordered by date:
+
+```json
+{"date": "2027-01-30", "status": "BLOCKED"}
+```
+
+`status` is `OK`, `BLOCKED` or `ON_REQUEST`.
+
+Two differences from `calendar`:
+
+- **No price rule.** A day without a maintained price keeps the status the contingent reports; it is not forced to `BLOCKED`.
+- **Days the snapshot lacks are left out**, not returned as `BLOCKED`. The response is not contiguous: a day without an entry has no availability data, and the feed shows it as free, as it did when it read the upstream service directly.
+
+Errors are the same as for `calendar`: `400 {"error":"Hotel not found for hotelCode."}`, `400` with violations for invalid parameters, and `502 {"error":"Failed to fetch contingent data."}` when there is no usable snapshot. For this endpoint the `502` is the important one: an empty list would show every day as free, so a consumer should answer with an error and let the portals keep their last import.
+
 ---
 
 ### Operating the snapshot (deployment)