Remove Availability resources, consolidate field names, and introduce MeetingPoint schema to enhance consistency and clarity

Author: damianbl

README.md

@@ -79,8 +79,8 @@ curl -s -H 'Authorization: Bearer demo-token' \
   -H 'Content-Type: application/json' \
   -d '{
     "productId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
-    "localDate": "2026-07-15",
-    "localTime": "10:00",
+    "date": "2026-07-15",
+    "time": "10:00",
     "numberOfAdults": 2,
     "mainGuest": {
       "firstName": "Anna",
@@ -131,7 +131,7 @@ No Prism mock is deployed; `yarn mock` is for local development only.
 - Every 4xx response references the shared `Error` envelope under
   `components/responses/`.
 - Field semantics that differ from a partner's likely default expectation are
-  documented inline on the field itself (see `AvailabilitySlot.capacity`,
+  documented inline on the field itself (see `CalendarDay.vacancies`,
   `Money`, `BookingStatus`).
 
 ## Status

components/parameters/IdempotencyKey.yaml

@@ -3,8 +3,7 @@ in: header
 required: false
 description: |
   Client-generated key making the request safe to retry. Repeated requests with
-  the same key return the original response. **Enforcement is phased (Phase 3);
-  the header is accepted from day one — supply it now to future-proof retries.**
+  the same key return the original response.
 schema:
   type: string
   maxLength: 255

components/responses/BadRequest.yaml

@@ -4,5 +4,5 @@ content:
     schema: { $ref: "../schemas/Error.yaml" }
     example:
       error: BAD_REQUEST
-      errorMessage: "`localDate` is required."
+      errorMessage: "`date` is required."
       requestId: "req_7c2b18d2"

components/schemas/AmendRequest.yaml

@@ -4,10 +4,10 @@ description: |
   unspecified fields are left unchanged. Subject to
   `Trip.canBePartnerRescheduled` server-side.
 properties:
-  localDate: { type: string, format: date }
-  localTime:
+  date: { type: string, format: date }
+  time:
     type: string
     pattern: "^[0-2][0-9]:[0-5][0-9]$"
   numberOfAdults: { type: integer, minimum: 1 }
   numberOfChildren: { type: integer, minimum: 0 }
-  netPrice: { $ref: "./Money.yaml" }
+  supplierPrice: { $ref: "./Money.yaml" }

components/schemas/Availability.yaml

@@ -2,45 +2,64 @@ type: object
 description: |
   A partner booking. Returned by create, amend, cancel, and read.
 
-  Fields present depend on `status`:
-
-    - `CONFIRMED` → `mainGuest` and full guest details set.
-    - `CANCELLED` → `cancellationReason` set; record persists for partner
-      refund logic.
-required: [id, status, productId, localDate, localTime]
+  When `status=CANCELLED`, `cancellationReason` is set and the record persists
+  for partner refund handling.
+required: [id, status, productId, title, date, time, timeZone, createdAt]
 properties:
   id:
     type: string
     format: uuid
     description: Withlocals booking id.
-  status: { $ref: "./BookingStatus.yaml" }
-  cancellationReason:
-    type: string
-    enum: [guest, host, no_show, admin, other]
-    description: Present when `status=CANCELLED`. Kept separate from the status enum.
-  resellerReference:
+  partnerReference:
     type: string
     description: Partner's own booking id (internally `external_id`).
     example: "GYG-2026-XYZ-001"
+
   productId: { type: string, format: uuid }
-  localDate: { type: string, format: date, example: "2026-07-15" }
-  localTime:
+  title:
+    type: string
+    description: Denormalized product title at the time of booking.
+    example: "A Relaxed Morning at Hyakumanben Craft Market"
+
+  date: { type: string, format: date, example: "2027-10-15" }
+  time:
     type: string
     pattern: "^[0-2][0-9]:[0-5][0-9]$"
-    example: "10:00"
-  guests:
-    type: object
-    properties:
-      numberOfAdults: { type: integer, minimum: 1, example: 2 }
-      numberOfChildren: { type: integer, minimum: 0, example: 0 }
-  mainGuest: { $ref: "./Guest.yaml" }
-  otherGuests:
-    type: array
-    items: { $ref: "./Guest.yaml" }
-  netPrice: { $ref: "./Money.yaml" }
-  meetingPoint: { type: string }
-  specialRequest: { type: string }
+    description: Local clock time at the experience location.
+    example: "09:00"
+  timeZone:
+    type: string
+    description: IANA time zone for `date` / `time`.
+    example: "Asia/Tokyo"
+
+  status: { $ref: "./BookingStatus.yaml" }
+  cancellationReason:
+    type: string
+    enum: [guest, host, no_show, admin, other]
+    description: Present when `status=CANCELLED`.
+  cancellationDeadline:
+    type: string
+    format: date-time
+    description: Latest moment the booking can be cancelled for a full refund.
+    example: "2027-10-08T09:00:00Z"
+  createdAt:
+    type: string
+    format: date-time
+    description: When the booking was created.
+    example: "2026-05-24T17:11:17Z"
+
+  meetingPoint: { $ref: "./MeetingPoint.yaml" }
   tourLanguage:
     type: string
-    description: ISO-639-1 language code (e.g. `en`).
+    description: ISO-639-1 language code.
     example: "en"
+  specialRequest:
+    type: string
+    description: Free-text note from the guest, forwarded to the host.
+
+  host:
+    type: object
+    required: [firstName]
+    description: Minimal host details for day-of identification.
+    properties:
+      firstName: { type: string, example: "Ren" }

components/schemas/AvailabilitySlot.yaml

@@ -1,12 +1,29 @@
 type: object
 description: One day in the availability calendar.
-required: [localDate, status]
+required: [date, status, vacancies, startingTimes]
 properties:
-  localDate: { type: string, format: date, example: "2026-07-15" }
+  date: { type: string, format: date, example: "2026-07-15" }
   status:
     type: string
     enum: [AVAILABLE, SOLD_OUT, CLOSED]
     description: |
       - `AVAILABLE` — at least one start time has capacity.
       - `SOLD_OUT` — start times exist but none has capacity.
       - `CLOSED` — no start times configured for this day.
+  vacancies:
+    type: integer
+    minimum: 0
+    description: |
+      Total remaining bookable spots across all start times on this day.
+      `0` when `status` is `SOLD_OUT` or `CLOSED`.
+    example: 20
+  startingTimes:
+    type: array
+    items:
+      type: string
+      pattern: "^[0-2][0-9]:[0-5][0-9]$"
+    description: |
+      Local-time start times configured for this day (`HH:MM`, 24h).
+      Empty when `status` is `CLOSED`. Populated for `AVAILABLE` and
+      `SOLD_OUT` — distinguishing "no times at all" from "times exist but full".
+    example: ["10:00", "14:00"]

components/schemas/Booking.yaml

@@ -1,13 +1,11 @@
 type: object
 description: |
-  Body of `POST /bookings` — creates a `CONFIRMED` booking in a single call.
-  Guest details are supplied upfront; there is no separate confirmation step
-  in v1.
-required: [productId, localDate, localTime, numberOfAdults, mainGuest]
+  Body of `POST /bookings` — creates a `CONFIRMED` booking.
+required: [productId, date, time, numberOfAdults, mainGuest]
 properties:
   productId: { type: string, format: uuid }
-  localDate: { type: string, format: date, example: "2026-07-15" }
-  localTime:
+  date: { type: string, format: date, example: "2026-07-15" }
+  time:
     type: string
     pattern: "^[0-2][0-9]:[0-5][0-9]$"
     example: "10:00"
@@ -23,7 +21,7 @@ properties:
   otherGuests:
     type: array
     items: { $ref: "./Guest.yaml" }
-  resellerReference:
+  partnerReference:
     type: string
     description: Partner's own booking id; stored as `external_id`. Recommended for traceability.
     example: "GYG-2026-XYZ-001"
@@ -34,4 +32,4 @@ properties:
     type: string
     description: ISO-639-1 language code.
     example: "en"
-  netPrice: { $ref: "./Money.yaml" }
+  supplierPrice: { $ref: "./Money.yaml" }

components/schemas/CalendarDay.yaml

@@ -0,0 +1,25 @@
+type: object
+description: Where the experience starts.
+required: [name]
+properties:
+  name:
+    type: string
+    description: Short human-readable name.
+    example: "Hyakumanben Chion-ji Temple"
+  address:
+    type: string
+    description: Formatted address line.
+    example: "Japan, 〒600-8012 Kyoto, Shimogyo Ward, 四条大橋西詰"
+  lat:
+    type: number
+    format: double
+    description: Latitude in decimal degrees (WGS84).
+    example: 35.0298797
+  lon:
+    type: number
+    format: double
+    description: Longitude in decimal degrees (WGS84).
+    example: 135.7807599
+  instructions:
+    type: string
+    description: Free-text guidance for finding the meeting spot.