openapi: 3.0.3
info:
  title: Session Booker Pro API
  description: >
    Public and authenticated REST API for Session Booker Pro (Alex Moreno Personal Training).
    Provides schedule browsing, session capacity inspection, and client booking management.
    Backs WebMCP browser agents and the Site MCP Server bridge.
  version: 1.0.0
  contact:
    name: Alex Moreno Personal Training
    url: https://www.alexmoreno-demo.site

servers:
  - url: https://www.alexmoreno-demo.site/api
    description: Production API
  - url: http://localhost:8080/api
    description: Local Development Server

paths:
  /sessions:
    get:
      summary: Query scheduled training sessions
      operationId: getAvailableSessions
      description: >
        Returns a list of active scheduled sessions within an optional date window,
        optionally filtered by category. Includes real-time remaining capacity.
      parameters:
        - name: startDate
          in: query
          required: false
          description: Start of the query window (ISO 8601 string)
          schema:
            type: string
            format: date-time
        - name: endDate
          in: query
          required: false
          description: End of the query window (ISO 8601 string)
          schema:
            type: string
            format: date-time
        - name: category
          in: query
          required: false
          description: Filter sessions by category name (e.g., 'Strength Training', 'HIIT & Cardio')
          schema:
            type: string
      responses:
        '200':
          description: List of scheduled sessions matching criteria
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Session'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /sessions/{id}:
    get:
      summary: Get details for a specific session
      operationId: getSessionDetails
      description: Returns full details, coach info, base price, and remaining capacity for a session.
      parameters:
        - name: id
          in: path
          required: true
          description: Unique session UUID
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Session details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /bookings/me:
    get:
      summary: Get current client's bookings
      operationId: getMyBookings
      description: Returns upcoming and past session bookings for the authenticated user.
      security:
        - BearerAuth: []
        - CookieAuth: []
      responses:
        '200':
          description: List of bookings for the authenticated client
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Booking'
        '401':
          description: Unauthorized - missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /bookings:
    post:
      summary: Book a training session
      operationId: bookSession
      description: >
        Reserves a spot in an active session for the authenticated client.
        Verifies capacity and prevents double bookings.
      security:
        - BearerAuth: []
        - CookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - sessionId
              properties:
                sessionId:
                  type: string
                  format: uuid
                  description: The UUID of the session to book
      responses:
        '201':
          description: Booking confirmed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Booking'
        '400':
          description: Bad request (session full or already booked)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Supabase access token
    CookieAuth:
      type: apiKey
      in: cookie
      name: sb-access-token
      description: Supabase session cookie

  schemas:
    Session:
      type: object
      required:
        - id
        - start_date
        - end_date
        - max_slots
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        description:
          type: string
        start_date:
          type: string
          format: date-time
        end_date:
          type: string
          format: date-time
        max_slots:
          type: integer
        price:
          type: number
          nullable: true
        location:
          type: string
          nullable: true
        image_url:
          type: string
          nullable: true
        spots_left:
          type: integer
          description: Real-time calculated remaining capacity
        session_type:
          type: object
          properties:
            name:
              type: string
            description:
              type: string
            base_price:
              type: number
            category:
              type: object
              nullable: true
              properties:
                id:
                  type: string
                name:
                  type: string

    Booking:
      type: object
      required:
        - id
        - session_id
        - user_id
        - status
        - payment_status
        - created_at
      properties:
        id:
          type: string
          format: uuid
        session_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        status:
          type: string
          enum: [pending, confirmed, cancelled, completed]
        payment_status:
          type: string
          enum: [pending, paid, refunded, failed]
        created_at:
          type: string
          format: date-time
        session:
          $ref: '#/components/schemas/Session'

    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
        details:
          type: string
          nullable: true