openapi: 3.0.4
info:
  title: Evolution Foundation - Auth Service - User Tours
  description: |
    Tracks the completion state of in-app onboarding tours per user.
    Each tour is identified by a free-form `tour_key` chosen by the frontend.

    Available starting `v1.0.0-rc3`.
  version: 1.0.0
servers:
- url: https://app.evochat.ai
- url: http://localhost:3001
paths:
  /api/v1/user_tours:
    get:
      operationId: list-user-tours
      summary: List User Tours
      description: Returns all tours the current user has interacted with, ordered by completion timestamp ascending.
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Tours retrieved
          content:
            application/json:
              schema:
                type: object
                required: [success, data, message]
                properties:
                  success: { type: boolean, example: true }
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/UserTour' }
                  message: { type: string }
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: save-user-tour
      summary: Save Tour Status
      description: |
        Saves the completion state of a tour for the current user.
        Idempotent — if a tour with the same `tour_key` exists, it is updated;
        otherwise a new entry is created.
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [tour]
              properties:
                tour:
                  type: object
                  required: [tour_key]
                  properties:
                    tour_key:
                      type: string
                      description: Free-form identifier for the tour
                      example: "agents-walkthrough"
                    completed_at:
                      type: string
                      format: date-time
                      description: When the tour was finished (defaults to now)
                    status:
                      type: string
                      enum: [completed, skipped, in_progress]
                      default: completed
                      description: Tour completion state (unknown values fall back to 'completed')
      responses:
        '200':
          description: Tour saved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean, example: true }
                  data: { $ref: '#/components/schemas/UserTour' }
                  message: { type: string, example: "Tour saved successfully" }
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'

  /api/v1/user_tours/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema: { type: string }
      description: |
        The tour_key (not the database id) of the tour to reset.
    delete:
      operationId: reset-user-tour
      summary: Reset Tour
      description: Removes the user's record for the given tour_key, effectively resetting it so it can show again.
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Tour reset successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean, example: true }
                  data: { type: object }
                  message: { type: string, example: "Tour reset successfully" }
        '404':
          description: Tour not found for this user
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean, example: false }
                  message: { type: string, example: "Tour not found" }

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    UserTour:
      type: object
      properties:
        id: { type: string, format: uuid }
        tour_key: { type: string, example: "agents-walkthrough" }
        completed_at: { type: string, format: date-time }
        status:
          type: string
          enum: [completed, skipped, in_progress]
          example: "completed"
  responses:
    Unauthorized:
      description: Missing or invalid bearer token
      content:
        application/json:
          schema:
            type: object
            properties:
              success: { type: boolean, example: false }
              message: { type: string, example: "Unauthorized" }
    ValidationError:
      description: Validation failed
      content:
        application/json:
          schema:
            type: object
            properties:
              success: { type: boolean, example: false }
              message: { type: string }
              errors:
                type: object
                additionalProperties:
                  type: array
                  items: { type: string }