# Hidden San Diego task: hotel room details before Wikiup checkout

**Listing approval:** every property must have an approved request for the authenticated affiliate, including existing listings and the affiliate's own properties. Pending, denied and never-requested properties are excluded. Blacklist and active-inventory rules still apply. See [Listing partner requests](listing-partner-requests.md) for rollout status and onboarding.

This additive operation lets affiliates build a shareable room page under a hotel
or inn. Rooms can be discovered without dates through the rooms collection,
or by exact option ID returned by availability; it does not create a rental listing or reserve inventory.

## Approved contract and implementation scope

Implement this in Hidden San Diego’s existing lodging flow:

**Hotel page → See Details → Hidden San Diego room page → Reserve → Wikiup checkout.**

The approved endpoint is `GET /api/travel/listings/{listingId}/rooms/{roomId}`.
This is the single room-details route for both named rooms and pooled room types.
Read the response from `room`. Parent availability still returns `options[]`;
that array contains the same IDs as the date-free rooms collection.

Use the exact parent `listingId` and selected availability `options[].id` as
path parameters. For a pooled type, preserve the entire `room-type:TYPE_ID`
value in the path; do not use the nullable `room.roomId` field as its lookup ID.
The consumer uses the same route and response wrapper for both booking models.
Treat `options[].id` as opaque: URL-encode it and pass it unchanged, without
detecting the booking model, parsing prefixes, or choosing a different endpoint.
The guest does not need to know the booking model.
Keep the current rental flow unchanged: this room resource is for hotel/inn parents.

This contract was pushed in Wikiup commit `09cb244884195f651c32c09a757d7f9f7170c03c`.
Deployment and authenticated live room responses were not verified at handoff.
Confirm the target environment serves the route before enabling the consumer flow;
`/api/version` alone is not proof that authenticated room retrieval works.

## Browse every room without dates

`GET /api/travel/listings/{listingId}/rooms?page=1` returns all active advertised
rooms or pooled room types, twelve per page in stable ID order. Occupied rooms
remain included: this is content, not availability. No booking-model branching is
needed. Rental listings do not use this route and return 404.

```sh
curl --get --fail-with-body \
  "$WIKIUP_API_ORIGIN/api/travel/listings/$ENCODED_LISTING_ID/rooms" \
  -H "Authorization: Bearer $WIKIUP_API_KEY" \
  -H 'Accept: application/json' \
  --data-urlencode 'page=1'
```

Illustrative response (every room uses the fields documented below):

```json
{
  "rooms": [{
    "id": "room_example",
    "listingId": "hotel:property_example",
    "propertyId": "property_example",
    "roomId": "room_example",
    "roomTypeId": null,
    "name": "Garden King",
    "description": "A king room with a private terrace.",
    "capacity": 2,
    "amenities": ["Wi-Fi", "Private terrace"],
    "coverImage": {
      "id": "photo_example", "url": "https://images.example.com/garden.jpg",
      "alt": "Private terrace", "width": 1600, "height": 900,
      "variants": [], "group": null
    },
    "gallery": [{
      "id": "photo_example", "url": "https://images.example.com/garden.jpg",
      "alt": "Private terrace", "width": 1600, "height": 900,
      "variants": [], "group": null
    }],
    "galleryGroups": []
  }],
  "meta": {"page": 1, "nextPage": null}
}
```

`page` defaults to 1 and accepts integers 1–999999. No dates, party or other
query parameters are accepted. Follow `meta.nextPage` until null to show all rooms.
Render the property gallery full width, then its description, then room cards
with each room's own gallery. Do not substitute property photos for missing room
photos. Retain loaded pages when a later page fails; show a retry state and retry
that page. Never label a failed load as no rooms. Empty `rooms` on a successful
page means no further active content, not sold out. Catalog changes between page
loads can change membership; de-duplicate by room ID.

The same authorization and no-store rules apply as individual room detail.
Room photo work is bounded to three rooms at a time within a 15-second deadline.
No schema migration is required. This collection addition is implemented locally;
deployment and authenticated live verification are still required.

## One request for either booking model

Set `WIKIUP_API_ORIGIN` to the target API origin. Set `ENCODED_LISTING_ID` to
the parent listing ID and `ENCODED_ROOM_ID` to the selected `options[].id`,
each URL-encoded once as a path segment. Use the same request for every choice:

```sh
curl --fail-with-body \
  "$WIKIUP_API_ORIGIN/api/travel/listings/$ENCODED_LISTING_ID/rooms/$ENCODED_ROOM_ID" \
  -H "Authorization: Bearer $WIKIUP_API_KEY" \
  -H 'Accept: application/json'
```

Use preview origin `https://api-preview.wikiup.app` or production origin
`https://api.wikiup.app` after verifying deployment. Keep the affiliate
API key on your server. Encode each opaque path ID exactly once; for example,
`room-type:king_type` becomes `room-type%3Aking_type`. No dates, party counts,
`fetch`, or other query parameters are accepted. No property header is needed.
The affiliate may browse other owners' eligible properties, including its own.

## Named room response

These are fictional IDs and content illustrating the contract, not live evidence.

```json
{
  "room": {
    "id": "room_example",
    "listingId": "hotel:property_example",
    "propertyId": "property_example",
    "roomId": "room_example",
    "roomTypeId": null,
    "name": "Garden King",
    "description": "<p>A king room with a private terrace.</p>",
    "capacity": 2,
    "amenities": [
      "Wi-Fi",
      "Private terrace"
    ],
    "coverImage": {
      "id": "photo_example",
      "url": "https://images.example.com/rooms/garden-king.jpg",
      "alt": "Garden King private terrace",
      "width": 1600,
      "height": 900,
      "variants": [
        {
          "url": "https://images.example.com/rooms/garden-king-640.webp",
          "width": 640,
          "height": 360,
          "format": "webp"
        }
      ],
      "group": {
        "id": "group:terrace",
        "title": "Terrace"
      }
    },
    "gallery": [
      {
        "id": "photo_example",
        "url": "https://images.example.com/rooms/garden-king.jpg",
        "alt": "Garden King private terrace",
        "width": 1600,
        "height": 900,
        "variants": [
          {
            "url": "https://images.example.com/rooms/garden-king-640.webp",
            "width": 640,
            "height": 360,
            "format": "webp"
          }
        ],
        "group": {
          "id": "group:terrace",
          "title": "Terrace"
        }
      }
    ],
    "galleryGroups": [
      {
        "id": "group:terrace",
        "title": "Terrace",
        "imageIds": [
          "photo_example"
        ]
      }
    ]
  }
}
```

## Pooled room type response

Use the same request above. For the example below, `ENCODED_ROOM_ID` is
`room-type%3Aking_type`. The response still uses `room`; no alternate route
or booking-model selection is required.


```json
{
  "room": {
    "id": "room-type:king_type",
    "listingId": "hotel:property_example",
    "propertyId": "property_example",
    "roomId": null,
    "roomTypeId": "king_type",
    "name": "King Room",
    "description": null,
    "capacity": 2,
    "amenities": [],
    "coverImage": null,
    "gallery": [],
    "galleryGroups": []
  }
}
```

No physical member room is assigned by a content read. Type content comes from
the type's saved public content; missing type details are not copied from a member.
Existing named-room content inheritance follows Wikiup's room configuration.

## Fields

Every field shown above is present. No prices, availability counts, booking URLs,
private check-in instructions, access codes, notes, or guest data are returned.

| Field | Type | Meaning |
| --- | --- | --- |
| `room.id` | string | Exact `options[].id` from parent availability. Stable across dates. |
| `room.listingId` | string | Parent hotel listing ID. Inns use hotel identity too. |
| `room.propertyId` | string | Stable property ID. |
| `room.roomId` | string or null | Named room ID; null for pooled room types. |
| `room.roomTypeId` | string or null | Pooled type ID; null for named rooms. |
| `room.name` | string | Public title, falling back to the saved room/type name. |
| `room.description` | string or null | Full saved public description; may contain HTML. Sanitize before rendering. Missing stays null. |
| `room.capacity` | positive integer or null | Advertised guest capacity; null when unknown. Fresh availability evaluates the actual party. |
| `room.amenities` | string array | Public amenity names; empty when absent. |
| `room.coverImage` | PublicImage or null | First image in this room/type gallery. No property-photo fallback. |
| `room.gallery` | PublicImage array | Ordered public photos belonging to this room/type; empty when absent. |
| `room.galleryGroups` | GalleryGroup array | Ordered group menu with Title Case titles and image IDs. |

Image and group fields use the existing definitions in
[the complete schema](travel-listings.schema.json#/$defs/RoomContentResponse)
and [gallery contract](listing-gallery-groups.md). The rendered API reference
includes a populated image example and all nested image fields. Use returned image
URLs and dimensions unchanged. Missing photos are not evidence of sold-out inventory.

## Hidden San Diego implementation task

1. On each hotel availability option, link **See Details** to a local room page
   containing the parent `listingId`, exact availability `options[].id`, and current dates/party.
   These IDs must survive refresh and sharing without previous browser state.
2. On that page, have your server fetch this content endpoint. Render the room
   name, sanitized description, amenities and grouped gallery. Never substitute
   property content or construct a rental ID from a hotel room.
3. Fetch fresh parent availability for the current dates and party:

```sh
curl --get --fail-with-body \
  'https://api-preview.wikiup.app/api/travel/listings/hotel%3Aproperty_example/availability' \
  -H "Authorization: Bearer $WIKIUP_API_KEY" \
  --data-urlencode 'checkIn=2027-02-09' \
  --data-urlencode 'checkOut=2027-02-12' \
  --data-urlencode 'adults=2' \
  --data-urlencode 'children=0' \
  --data-urlencode 'pets=0'
```

4. Match `options[].id` by exact equality with the requested room ID. Enable
   **Reserve** only when that exact option is returned by a successful complete
   availability response. Other available rooms do not make this room available.
5. Send the visitor to that option's `bookingUrl` unchanged. This preserves the
   exact room/type target, dates, party and signed affiliate attribution. Wikiup
   collects guest details and payment and rechecks inventory. The link is not a hold.
6. When dates or party change, discard old prices and booking links before fetching
   again. A successful response without this option means it cannot be reserved
   for those criteria; retain its content. Provider errors are a retry state,
   never sold-out evidence. Respect the shared account rate limit when sequencing calls.

## Access, errors and limits

Both IDs are checked against current eligible hotel inventory. A previously valid
shared URL can become inaccessible when a room is deactivated or blacklisted.

| Status | Meaning |
| --- | --- |
| 200 | `{ "room": { ... } }`, public content only. |
| 401 | Missing or invalid credentials. |
| 403 | Credential is neither an eligible affiliate API key nor a verified, active affiliate session. Owner/search-only keys cannot use this endpoint. Approval and no suspension are required for the authenticated affiliate. |
| 404 | Missing, wrong-parent, inactive/withdrawn or blacklisted option; also rental parents and physical pooled members. |
| 405 | Use GET. |
| 422 | Malformed IDs, repeated values or unsupported query fields. Invalid URL encoding may return 400 before routing. |
| 429 | Shared affiliate account budget exhausted; honor `Retry-After`. |
| 503 | Provider/data/media failure or timeout; `complete: false`. No empty successful fallback. |

Responses, including errors, have private/no-store and CDN no-store headers.
The shared travel admission limit is one request per account per second.
Content work has a 15-second deadline; gallery work uses the existing bounded
three-image concurrency and 200-photo maximum. Existing inventory bounds apply.

This operation changes no reservation, pricing, availability, attribution, rental
or batch endpoint behavior. It requires no new database fields or configuration.

## Consumer implementation and acceptance checks

- Reuse the existing server-side affiliate proxy and secret configuration. Never
  put credentials in browser requests, HTML, URLs, screenshots or logs.
- Preserve parent listing ID, room lookup ID and selected dates/party in the local
  page URL. Direct navigation, refresh, sharing and Back must work without a
  previous search response held in memory.
- Display content independently of availability. Sanitize description HTML;
  render only the returned room/type photos and amenities. Use gallery group
  titles as supplied, thumbnails at their actual dimensions, and an accessible
  empty-photo state. Do not substitute property photos for missing room photos.
- Sequence content and availability requests through the existing account-wide
  request budget. Honor `Retry-After`; cancel or ignore responses from obsolete
  room/date/party selections. Do not cache completed JSON responses.
- Keep Reserve disabled while availability is unchecked, loading, failed or no
  longer current. Match the exact requested ID in fresh `options[]`; never select
  the first available room as a fallback. Preserve content when this room is sold out.
- Reserve navigates to that exact option’s fresh `bookingUrl` unchanged, without
  adding an API key. Wikiup handles guest details, payment and confirmation.
  No booking-success state may be inferred from clicking Reserve.
- Test a named room and a pooled type, missing photos/content, a direct-page
  reload, dates/party changes, sold-out selection while another room is available,
  wrong-parent/inactive/blacklisted 404, 403, 429 and retryable 503.
- Verify desktop/mobile layouts, keyboard access and gallery behavior. Report
  which checks used live Wikiup responses versus mocks, the deployed revision,
  and any remaining limitations. Use property-local timestamps with timezone.

If this needs additional Wikiup fields or behavior, return a Markdown task for
Wikiup describing the missing provider contract and evidence. Do not call private
owner endpoints, synthesize data, or invent an API contract in Hidden San Diego.
