openapi: 3.0.3
info:
  version: v1.0.0
  title: LE-KO Histories API
  license:
    name: private
    url: https://le-ko.deggex.com
  contact:
    email: denis@deggex.awsapps.com
  description: LE-KO Histories API
servers:
  - url: https://booking-{env}.le-ko.deggex.com/{basePath}
    description: Histories API.
    variables:
      basePath:
        default: v1
      env:
        default: dev
security:
  - bearerHttpAuthentication: []
tags:
  - name: Histories
    description: User Activity Histories API
paths:
  /histories/{userId}:
    get:
      summary: Get user history
      operationId: getUserHistory
      description: ✨ Retrieves the activity history of a user, including sessions attended as an athlete and sessions conducted as a coach.
      tags:
        - Histories
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: groupingType
          in: query
          required: false
          schema:
            type: string
            enum:
              - Personal
              - Group
        - name: bookingStatus
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/BookingStatus'
        - name: startTime
          in: query
          required: false
          schema:
            type: string
            format: date-time
        - name: endTime
          in: query
          required: false
          schema:
            type: string
            format: date-time
        - name: sportIds
          in: query
          schema:
            type: array
            items:
              type: string
              format: uuid
          style: form
          explode: false
        - name: participationType
          in: query
          required: false
          schema:
            type: string
            enum:
              - Athlete
              - Coach
          description: Filter history by participation type (Athlete for sessions attended, Coach for sessions conducted)
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: The history of the user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoryResult'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
components:
  securitySchemes:
    bearerHttpAuthentication:
      description: Bearer token using a JWT
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    BookingStatus:
      type: string
      enum:
        - Accepted
        - Rejected
        - Pending
        - Canceled
        - InDispute
        - DisputeDone
    EventStatus:
      type: string
      enum:
        - Scheduled
        - Canceled
        - InProgress
        - Done
    EventCanceledByRole:
      type: string
      enum:
        - Coach
        - System
      description: Role of who canceled the event
    EventCancellationReasonCode:
      type: string
      enum:
        - NotFeelingWell
        - NoTime
        - Other
      description: Reason code for event cancellation
    Event:
      type: object
      properties:
        id:
          type: string
          format: uuid
        timeslotId:
          type: string
          format: uuid
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        status:
          $ref: '#/components/schemas/EventStatus'
          nullable: true
        coachId:
          type: string
          format: uuid
        canceledAt:
          type: string
          format: date-time
          nullable: true
        canceledByRole:
          allOf:
            - $ref: '#/components/schemas/EventCanceledByRole'
          type: string
          nullable: true
        cancellationReasonCode:
          allOf:
            - $ref: '#/components/schemas/EventCancellationReasonCode'
          type: string
          nullable: true
        cancellationReasonText:
          type: string
          nullable: true
      required:
        - id
        - timeslotId
        - startTime
        - endTime
        - status
        - coachId
    BookingCanceledByRole:
      type: string
      description: Who canceled the booking
      enum:
        - Athlete
        - Coach
        - System
    BookingCancellationReasonCode:
      type: string
      description: Reason code for booking cancellation
      enum:
        - NotFeelingWell
        - NoTime
        - Other
    Booking:
      type: object
      properties:
        bookingId:
          type: string
          format: uuid
        orderId:
          type: string
          format: uuid
        userId:
          type: string
          format: uuid
        eventId:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/BookingStatus'
        completed:
          type: boolean
        note:
          type: string
          nullable: true
        canceledAt:
          type: string
          format: date-time
          nullable: true
        canceledByRole:
          allOf:
            - $ref: '#/components/schemas/BookingCanceledByRole'
          type: string
          nullable: true
        cancellationReasonCode:
          allOf:
            - $ref: '#/components/schemas/BookingCancellationReasonCode'
          type: string
          nullable: true
        cancellationReasonText:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
      required:
        - bookingId
        - orderId
        - userId
        - eventId
        - status
        - completed
        - createdAt
    Currency:
      type: string
      enum:
        - RUB
    Timeslot:
      type: object
      properties:
        id:
          type: string
          format: uuid
        sessionId:
          type: string
          format: uuid
        startTime:
          type: string
        endTime:
          type: string
        numberOfParticipants:
          type: integer
        slotType:
          type: string
          nullable: true
        ageStart:
          type: integer
        ageEnd:
          type: integer
        duration:
          type: integer
        price:
          type: integer
        priceCurrency:
          $ref: '#/components/schemas/Currency'
        public:
          type: boolean
          nullable: true
        level:
          type: string
          nullable: true
        eligibility:
          type: string
          nullable: true
        addressId:
          type: string
          format: uuid
          nullable: true
      required:
        - id
        - sessionId
        - startTime
        - endTime
        - numberOfParticipants
        - slotType
        - ageStart
        - ageEnd
        - duration
        - price
        - priceCurrency
        - public
        - level
        - eligibility
        - addressId
    Session:
      type: object
      properties:
        id:
          type: string
          format: uuid
        serviceId:
          type: string
          format: uuid
        startDate:
          type: string
          format: date-time
        repeatDays:
          type: array
          items:
            type: string
        stopDate:
          type: string
          format: date-time
          nullable: true
      required:
        - id
        - serviceId
        - startDate
        - repeatDays
        - stopDate
    Service:
      type: object
      properties:
        id:
          type: string
          format: uuid
        coachId:
          type: string
          format: uuid
        description:
          type: string
        sportId:
          type: string
          format: uuid
        subsportId:
          type: string
          format: uuid
          nullable: true
        isDraft:
          type: boolean
        inventory:
          type: string
          nullable: true
          description: Inventory details for the service
      required:
        - id
        - coachId
        - description
        - sportId
        - subsportId
        - isDraft
    AddressType:
      type: string
      enum:
        - Main
    Address:
      type: object
      properties:
        id:
          type: string
          format: uuid
        userId:
          type: string
          format: uuid
        formattedAddress:
          type: string
        addressType:
          $ref: '#/components/schemas/AddressType'
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
        entrance:
          type: string
        floor:
          type: string
        locationComment:
          type: string
      required:
        - id
        - userId
        - formattedAddress
    AthleteHistoryEntry:
      type: object
      properties:
        event:
          $ref: '#/components/schemas/Event'
        booking:
          $ref: '#/components/schemas/Booking'
        timeslot:
          $ref: '#/components/schemas/Timeslot'
        session:
          $ref: '#/components/schemas/Session'
        service:
          $ref: '#/components/schemas/Service'
        address:
          $ref: '#/components/schemas/Address'
      required:
        - event
        - booking
        - timeslot
        - session
        - service
        - address
    CoachHistoryEntry:
      type: object
      properties:
        event:
          $ref: '#/components/schemas/Event'
        timeslot:
          $ref: '#/components/schemas/Timeslot'
        session:
          $ref: '#/components/schemas/Session'
        service:
          $ref: '#/components/schemas/Service'
        address:
          $ref: '#/components/schemas/Address'
        bookings:
          type: array
          items:
            $ref: '#/components/schemas/Booking'
      required:
        - event
        - timeslot
        - session
        - service
        - address
        - bookings
    CanceledBookingHistoryEntry:
      type: object
      properties:
        event:
          $ref: '#/components/schemas/Event'
        booking:
          $ref: '#/components/schemas/Booking'
        timeslot:
          $ref: '#/components/schemas/Timeslot'
        session:
          $ref: '#/components/schemas/Session'
        service:
          $ref: '#/components/schemas/Service'
        address:
          $ref: '#/components/schemas/Address'
      required:
        - event
        - booking
        - timeslot
        - session
        - service
        - address
    HistoryEntry:
      type: object
      properties:
        athlete:
          $ref: '#/components/schemas/AthleteHistoryEntry'
          nullable: true
          description: Entry for a session the user attended as an athlete
        coach:
          $ref: '#/components/schemas/CoachHistoryEntry'
          nullable: true
          description: Entry for a session the user conducted as a coach
        canceledBooking:
          $ref: '#/components/schemas/CanceledBookingHistoryEntry'
          nullable: true
          description: Entry for a canceled booking for a session the user coached
      description: History entry containing either athlete, coach, or canceled booking participation data. Exactly one of athlete, coach, or canceledBooking will be non-null.
    HistoryResult:
      type: object
      properties:
        entries:
          type: array
          items:
            $ref: '#/components/schemas/HistoryEntry'
        total:
          type: integer
        remainingPages:
          type: integer
      required:
        - entries
        - total
        - remainingPages
    Error:
      type: object
      required:
        - code
        - message
        - endpoint
        - requestId
      properties:
        code:
          type: string
          description: Error unique code
          enum:
            - validation
            - internal
            - oops
            - unexpected
            - tooManyRequests
            - notFound
            - unauthorized
            - forbidden
        message:
          type: string
          description: Error message
        endpoint:
          type: string
        requestId:
          type: string
    Errors:
      type: object
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
  parameters:
    TraceparentHeader:
      name: traceparent
      in: header
      required: false
      description: W3C Trace Context traceparent header for request tracing
      schema:
        type: string
        pattern: ^[0-9a-f]{2}-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$
        example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01