openapi: 3.1.0
info:
  title: Big Blue Van Agent Booking API
  version: 1.0.0
  description: |
    Booking API for AI agents (Meta Muse Connectors and similar).

    **Auth:** `Authorization: Bearer <BBV_AGENT_API_KEY>` or `X-BBV-Agent-Key: <BBV_AGENT_API_KEY>`.

    **Payment:** Oil changes are paid at the time of service (not charged at booking).
    Creating a booking is still a sensitive write — summarize details and obtain user approval first.

    **Region:** Utah County (all cities) plus Herriman and Draper. America/Denver hours:
    Mon–Fri 08:00–20:00, Sat 08:00–12:00, Sun closed.

    **Tool classification (Muse):**
    - Read: service-info, service-area, availability, quotes, get booking
    - Sensitive write: create booking, cancel booking
  contact:
    name: Big Blue Van
    email: bigbluevan.utah@gmail.com
    url: https://bigbluevanmobile.com
  termsOfService: https://bigbluevanmobile.com/terms.html

servers:
  - url: https://cofcdajrcogkectfdmge.supabase.co/functions/v1/agent-booking
    description: Production

security:
  - AgentApiKey: []

paths:
  /v1/service-info:
    get:
      operationId: getServiceInfo
      summary: Business facts, hours, pricing terms
      x-muse-tool-class: read
      responses:
        "200":
          description: Service info
  /v1/service-area:
    get:
      operationId: getServiceArea
      summary: Cities served
      x-muse-tool-class: read
      responses:
        "200":
          description: City list
  /v1/availability:
    get:
      operationId: getAvailability
      summary: Available 1-hour service windows for a city
      x-muse-tool-class: read
      parameters:
        - name: city
          in: query
          required: true
          schema: { type: string }
          description: City name (e.g. Provo, Herriman)
        - name: from
          in: query
          required: false
          schema: { type: string, format: date }
        - name: to
          in: query
          required: false
          schema: { type: string, format: date }
      responses:
        "200":
          description: Available windows
        "400":
          description: City not served or invalid range
  /v1/quotes:
    post:
      operationId: createQuote
      summary: Estimate oil-change pricing and terms
      x-muse-tool-class: read
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                city: { type: string }
                vin: { type: string }
                year: { type: integer }
                make: { type: string }
                model: { type: string }
                engine: { type: string }
      responses:
        "200":
          description: Quote estimate
  /v1/bookings:
    post:
      operationId: createBooking
      summary: Create a confirmed mobile oil-change appointment
      x-muse-tool-class: sensitive_write
      description: |
        Creates a real `fact_service` booking. Payment is due at service.
        Use Idempotency-Key header to prevent duplicates.
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateBookingRequest"
      responses:
        "201":
          description: Booking confirmed
        "409":
          description: Slot unavailable or duplicate
  /v1/bookings/{service_key}:
    get:
      operationId: getBooking
      summary: Fetch booking status
      x-muse-tool-class: read
      parameters:
        - $ref: "#/components/parameters/serviceKey"
        - name: email
          in: query
          required: true
          schema: { type: string, format: email }
      responses:
        "200":
          description: Booking
        "404":
          description: Not found
  /v1/bookings/{service_key}/cancel:
    post:
      operationId: cancelBooking
      summary: Cancel an incomplete booking
      x-muse-tool-class: sensitive_write
      parameters:
        - $ref: "#/components/parameters/serviceKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email: { type: string, format: email }
                reason: { type: string }
      responses:
        "200":
          description: Cancelled
        "404":
          description: Not found
        "409":
          description: Already completed / not cancellable

components:
  securitySchemes:
    AgentApiKey:
      type: http
      scheme: bearer
      description: BBV_AGENT_API_KEY
  parameters:
    serviceKey:
      name: service_key
      in: path
      required: true
      schema: { type: integer }
  schemas:
    CreateBookingRequest:
      type: object
      required: [first_name, last_name, email, phone, address, full_date, window_start]
      properties:
        first_name: { type: string }
        last_name: { type: string }
        email: { type: string, format: email }
        phone: { type: string }
        address:
          type: object
          required: [line1, city, state, zip]
          properties:
            line1: { type: string }
            line2: { type: string }
            city: { type: string }
            state: { type: string, default: UT }
            zip: { type: string }
            address_type: { type: string, enum: [Home, Business, Other], default: Home }
        full_date: { type: string, format: date }
        window_start: { type: string, description: "HH:MM 24h Mountain time" }
        vin: { type: string }
        year: { type: integer }
        make: { type: string }
        model: { type: string }
        engine: { type: string }
        idempotency_key: { type: string }