{
  "openapi": "3.0.3",
  "info": {
    "title": "Yasha Hotel Direct Booking API",
    "description": "Public API of Yasha Hotel (3-star hotel, 28 rooms, 27 Rue Joseph Junck, L-1839 Luxembourg, 100 m from Luxembourg central station). Allows AI agents and travel tools to check real-time room availability and exact prices, and to create a booking that the human traveler confirms by secure Stripe card payment. Direct bookings are about 10% cheaper than OTAs (Booking.com, Expedia) for the same rooms and dates. Prices are in euro cents (EUR). Maximum stay: 30 nights. Check-in from 13:00, check-out before 11:00, front desk open 24/7.",
    "version": "1.0.0",
    "contact": { "name": "Yasha Hotel", "url": "https://yashahotel.com/", "email": "yashahotel@gmail.com" }
  },
  "servers": [{ "url": "https://yashahotel.com" }],
  "paths": {
    "/api/rooms": {
      "get": {
        "operationId": "list_rooms",
        "summary": "List all bookable room types",
        "description": "Returns every active room type with capacity, bed type, size, amenities and photo URLs. Use these room ids for availability checks and bookings.",
        "responses": {
          "200": {
            "description": "Room catalog",
            "content": { "application/json": { "schema": {
              "type": "object",
              "properties": { "rooms": { "type": "array", "items": { "$ref": "#/components/schemas/Room" } } }
            } } }
          }
        }
      }
    },
    "/api/availability": {
      "post": {
        "operationId": "check_availability",
        "summary": "Check availability and exact total price per room for a date range",
        "description": "Core agent tool. For each room type, returns whether it is available for the given stay, the number of nights, the exact total in euro cents, the average nightly price and a per-night price breakdown. Prices shown already include the direct-booking advantage.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailabilityRequest" } } }
        },
        "responses": {
          "200": {
            "description": "Per-room availability and pricing",
            "content": { "application/json": { "schema": {
              "type": "object",
              "properties": {
                "checkin": { "type": "string", "format": "date" },
                "checkout": { "type": "string", "format": "date" },
                "rooms": { "type": "array", "items": { "$ref": "#/components/schemas/RoomAvailability" } }
              }
            } } }
          },
          "400": { "description": "Invalid dates (format YYYY-MM-DD, checkin < checkout, not in the past, max 30 nights)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/calendar": {
      "get": {
        "operationId": "get_price_calendar",
        "summary": "Daily price and availability for one room over a month",
        "description": "Returns day-by-day nightly price (euro cents) and availability for a room. Useful to suggest cheaper alternative dates to the traveler.",
        "parameters": [
          { "name": "room_id", "in": "query", "required": false, "description": "Room id from /api/rooms. Defaults to the first room type.", "schema": { "type": "integer" } },
          { "name": "month", "in": "query", "required": true, "description": "Month to inspect, format YYYY-MM", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" } }
        ],
        "responses": {
          "200": {
            "description": "Daily prices and availability",
            "content": { "application/json": { "schema": {
              "type": "object",
              "properties": {
                "room_id": { "type": "integer" },
                "room_name": { "type": "string" },
                "month": { "type": "string" },
                "days": { "type": "array", "items": {
                  "type": "object",
                  "properties": {
                    "date": { "type": "string", "format": "date" },
                    "price_cents": { "type": "integer", "nullable": true },
                    "available": { "type": "boolean" }
                  }
                } }
              }
            } } }
          },
          "400": { "description": "month parameter missing or malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/extras": {
      "get": {
        "operationId": "list_extras",
        "summary": "List paid extras (late check-out, parking, baby bed)",
        "description": "Returns the bookable extras with price in euro cents and billing unit (per_stay, per_night, per_person_night). Buffet breakfast is a special option charged per guest per night (see /api/config breakfast_price_cents).",
        "responses": { "200": { "description": "Extras catalog", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/api/promo/validate": {
      "get": {
        "operationId": "validate_promo_code",
        "summary": "Validate a promo code",
        "description": "Checks whether a promo code is currently valid and returns the percentage discount it gives on the room price (extras and breakfast excluded).",
        "parameters": [{ "name": "code", "in": "query", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Validation result", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/api/config": {
      "get": {
        "operationId": "get_hotel_info",
        "summary": "Hotel facts for agents (name, address, contact, direct discount, breakfast price)",
        "description": "Returns canonical hotel information (name, address, phone, email), the direct-booking discount percentage versus OTAs, the breakfast price per guest per night, and the amenity list. Use this to answer traveler questions about the property.",
        "responses": { "200": { "description": "Hotel information", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/api/bookings": {
      "post": {
        "operationId": "create_booking",
        "summary": "Create a booking (human completes payment via secure Stripe link)",
        "description": "Creates the reservation and a Stripe PaymentIntent. AGENT WORKFLOW: 1) call /api/availability to confirm the room is available and get the exact price, 2) collect the traveler's full name and email (plus optional phone, guest count, breakfast, extras, promo code), 3) POST here, 4) hand the human the returned payment details — the safest hand-off is to send the traveler to https://yashahotel.com/ to complete the card payment, or use client_secret with Stripe.js. The booking is only confirmed after successful card payment; unpaid bookings expire automatically. Returns 409 if the room became unavailable.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingRequest" } } }
        },
        "responses": {
          "200": { "description": "Booking created, payment ready", "content": { "application/json": { "schema": {
            "type": "object",
            "properties": {
              "booking_id": { "type": "string", "description": "Public booking reference (also usable in /manage.html)" },
              "client_secret": { "type": "string", "description": "Stripe PaymentIntent client secret for card payment" },
              "publishable_key": { "type": "string" },
              "amount_cents": { "type": "integer" },
              "mode": { "type": "string", "enum": ["live", "test"] }
            }
          } } } },
          "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "409": { "description": "Room no longer available on these dates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/bookings/{id}": {
      "get": {
        "operationId": "get_booking_status",
        "summary": "Get booking/payment status",
        "description": "Returns the status of a booking created via /api/bookings (pending_payment, confirmed, payment_failed...). Poll after the human completes the Stripe payment.",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Booking status", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    }
  },
  "components": {
    "schemas": {
      "Room": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "description": { "type": "string" },
          "capacity": { "type": "integer", "description": "Max guests" },
          "bed_type": { "type": "string" },
          "size_m2": { "type": "number" },
          "amenities": { "type": "array", "items": { "type": "string" } },
          "photos": { "type": "array", "items": { "type": "string", "format": "uri" } }
        }
      },
      "AvailabilityRequest": {
        "type": "object",
        "required": ["checkin", "checkout"],
        "properties": {
          "checkin": { "type": "string", "format": "date", "description": "Arrival date YYYY-MM-DD (check-in from 13:00)" },
          "checkout": { "type": "string", "format": "date", "description": "Departure date YYYY-MM-DD (check-out before 11:00)" }
        }
      },
      "RoomAvailability": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "capacity": { "type": "integer" },
          "available": { "type": "boolean" },
          "nights": { "type": "integer" },
          "total_cents": { "type": "integer", "description": "Exact total for the stay in euro cents, before extras/breakfast/promo" },
          "avg_night_cents": { "type": "integer" },
          "breakdown": { "type": "array", "items": { "type": "object" }, "description": "Per-night price detail" }
        }
      },
      "BookingRequest": {
        "type": "object",
        "required": ["room_id", "checkin", "checkout", "guest_name", "guest_email"],
        "properties": {
          "room_id": { "type": "integer" },
          "checkin": { "type": "string", "format": "date" },
          "checkout": { "type": "string", "format": "date" },
          "guest_name": { "type": "string" },
          "guest_email": { "type": "string", "format": "email" },
          "guest_phone": { "type": "string" },
          "guests": { "type": "integer", "description": "Number of guests, defaults to 1, capped at room capacity" },
          "special_requests": { "type": "string" },
          "breakfast": { "type": "boolean", "description": "Buffet breakfast for all guests and nights" },
          "promo_code": { "type": "string" },
          "extras": { "type": "array", "items": { "type": "integer" }, "description": "Extra ids from /api/extras" }
        }
      },
      "Error": {
        "type": "object",
        "properties": { "error": { "type": "string" } }
      }
    }
  }
}
