definitions:
  data.User:
    properties:
      allow_public:
        type: boolean
      avatar:
        type: string
      bio:
        type: string
      email:
        type: string
      id:
        type: integer
      nickname:
        type: string
      permission_level:
        type: integer
      subtitle:
        type: string
      user_id:
        type: string
      username:
        type: string
      uuid:
        type: string
    type: object
  data.UserSearchDoc:
    properties:
      avatar:
        type: string
      email:
        type: string
      nickname:
        type: string
      subtitle:
        type: string
      type:
        type: string
      user_id:
        type: string
      username:
        type: string
    type: object
  service_auth.ExchangeData:
    properties:
      client_id:
        type: string
      redirect_uri:
        type: string
      state:
        type: string
    type: object
  service_auth.ExchangeResponse:
    properties:
      redirect_uri:
        type: string
    type: object
  service_auth.MagicData:
    properties:
      client_id:
        type: string
      client_ip:
        type: string
      email:
        type: string
      redirect_uri:
        type: string
      state:
        type: string
      turnstile_token:
        type: string
    type: object
  service_auth.MagicResponse:
    properties:
      uri:
        type: string
    type: object
  service_auth.RefreshData:
    properties:
      refresh_token:
        type: string
    type: object
  service_auth.TokenData:
    properties:
      code:
        type: string
    type: object
  service_auth.TokenResponse:
    properties:
      access_token:
        type: string
      refresh_token:
        type: string
    type: object
  service_event.CheckinQueryResponse:
    properties:
      checkin_at:
        type: string
    type: object
  service_event.CheckinResponse:
    properties:
      checkin_code:
        type: string
    type: object
  service_event.CheckinSubmitData:
    properties:
      checkin_code:
        type: string
    type: object
  service_event.InfoResponse:
    properties:
      end_time:
        type: string
      name:
        type: string
      start_time:
        type: string
    type: object
  service_user.UserInfoData:
    properties:
      allow_public:
        type: boolean
      avatar:
        type: string
      bio:
        type: string
      email:
        type: string
      nickname:
        type: string
      permission_level:
        type: integer
      subtitle:
        type: string
      user_id:
        type: string
      username:
        type: string
    type: object
  service_user.UserTableResponse:
    properties:
      user_table:
        items:
          $ref: '#/definitions/data.User'
        type: array
    type: object
  utils.RespStatus:
    properties:
      code:
        type: integer
      data: {}
      error_id:
        type: string
      status:
        type: string
    type: object
info:
  contact: {}
paths:
  /auth/exchange:
    post:
      consumes:
      - application/json
      description: Exchanges client credentials and user session for a specific redirect
        authorization code.
      parameters:
      - description: Exchange Request Credentials
        in: body
        name: payload
        required: true
        schema:
          $ref: '#/definitions/service_auth.ExchangeData'
      produces:
      - application/json
      responses:
        "200":
          description: Successful exchange
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  $ref: '#/definitions/service_auth.ExchangeResponse'
              type: object
        "400":
          description: Invalid Input
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
        "401":
          description: Unauthorized
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
      security:
      - ApiKeyAuth: []
      summary: Exchange Auth Code
      tags:
      - Authentication
  /auth/magic:
    post:
      consumes:
      - application/json
      description: Verifies Turnstile token and sends an authentication link via email.
        Returns the URI directly if debug mode is enabled.
      parameters:
      - description: Magic Link Request Data
        in: body
        name: payload
        required: true
        schema:
          $ref: '#/definitions/service_auth.MagicData'
      produces:
      - application/json
      responses:
        "200":
          description: Successful request
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  $ref: '#/definitions/service_auth.MagicResponse'
              type: object
        "400":
          description: Invalid Input
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
        "403":
          description: Turnstile Verification Failed
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
      summary: Request Magic Link
      tags:
      - Authentication
  /auth/redirect:
    get:
      consumes:
      - application/x-www-form-urlencoded
      description: Verifies the temporary email code, ensures the user exists (or
        creates one), validates the client's redirect URI, and finally performs a
        302 redirect with a new authorization code.
      parameters:
      - description: Client Identifier
        in: query
        name: client_id
        required: true
        type: string
      - description: Target Redirect URI
        in: query
        name: redirect_uri
        required: true
        type: string
      - description: Temporary Verification Code
        in: query
        name: code
        required: true
        type: string
      - description: Opaque state used to maintain state between the request and callback
        in: query
        name: state
        type: string
      produces:
      - application/json
      - text/html
      responses:
        "302":
          description: Redirect to the provided RedirectUri with a new code
          schema:
            type: string
        "400":
          description: Invalid Input / Client Not Found / URI Mismatch
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
        "403":
          description: Invalid or Expired Verification Code
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
      summary: Handle Auth Callback and Redirect
      tags:
      - Authentication
  /auth/refresh:
    post:
      consumes:
      - application/json
      description: Accepts a valid refresh token to issue a new access token and a
        rotated refresh token.
      parameters:
      - description: Refresh Token Body
        in: body
        name: payload
        required: true
        schema:
          $ref: '#/definitions/service_auth.RefreshData'
      produces:
      - application/json
      responses:
        "200":
          description: Successful rotation
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  $ref: '#/definitions/service_auth.TokenResponse'
              type: object
        "400":
          description: Invalid Input
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
        "401":
          description: Invalid Refresh Token
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
      summary: Refresh Access Token
      tags:
      - Authentication
  /auth/token:
    post:
      consumes:
      - application/json
      description: Verifies the provided authorization code and issues a pair of JWT
        tokens (Access and Refresh).
      parameters:
      - description: Token Request Body
        in: body
        name: payload
        required: true
        schema:
          $ref: '#/definitions/service_auth.TokenData'
      produces:
      - application/json
      responses:
        "200":
          description: Successful token issuance
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  $ref: '#/definitions/service_auth.TokenResponse'
              type: object
        "400":
          description: Invalid Input
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
        "403":
          description: Invalid or Expired Code
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
      summary: Exchange Code for Token
      tags:
      - Authentication
  /event/checkin:
    get:
      consumes:
      - application/json
      description: Creates a temporary check-in code for the authenticated user and
        event.
      parameters:
      - description: Event UUID
        in: query
        name: event_id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Successfully generated code
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  $ref: '#/definitions/service_event.CheckinResponse'
              type: object
        "400":
          description: Invalid Input
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
      summary: Generate Check-in Code
      tags:
      - Event
  /event/checkin/query:
    get:
      consumes:
      - application/json
      description: Returns the timestamp of when the user checked in, or null if not
        yet checked in.
      parameters:
      - description: Event UUID
        in: query
        name: event_id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Current attendance status
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  $ref: '#/definitions/service_event.CheckinQueryResponse'
              type: object
        "400":
          description: Invalid Input
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
        "404":
          description: Record Not Found
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
      summary: Query Check-in Status
      tags:
      - Event
  /event/checkin/submit:
    post:
      consumes:
      - application/json
      description: Submits the generated code to mark the user as attended.
      parameters:
      - description: Checkin Code Data
        in: body
        name: payload
        required: true
        schema:
          $ref: '#/definitions/service_event.CheckinSubmitData'
      produces:
      - application/json
      responses:
        "200":
          description: Attendance marked successfully
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
        "400":
          description: Invalid Code or Input
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
      summary: Submit Check-in Code
      tags:
      - Event
  /event/info:
    get:
      consumes:
      - application/json
      description: Fetches the name, start time, and end time of an event using its
        UUID.
      parameters:
      - description: Event UUID
        in: query
        name: event_id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Successful retrieval
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  $ref: '#/definitions/service_event.InfoResponse'
              type: object
        "400":
          description: Invalid Input
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
        "404":
          description: Event Not Found
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
        "500":
          description: Internal Server Error
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
      summary: Get Event Information
      tags:
      - Event
  /user/full:
    get:
      consumes:
      - application/json
      description: Fetches all user records without pagination. This is typically
        used for administrative overview or data export.
      produces:
      - application/json
      responses:
        "200":
          description: Successful retrieval of full user table
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  $ref: '#/definitions/service_user.UserTableResponse'
              type: object
        "500":
          description: Internal Server Error (Database Error)
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
      security:
      - ApiKeyAuth: []
      summary: Get Full User Table
      tags:
      - User
  /user/info:
    get:
      consumes:
      - application/json
      description: Fetches the complete profile data for the user associated with
        the provided session/token.
      produces:
      - application/json
      responses:
        "200":
          description: Successful profile retrieval
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  $ref: '#/definitions/service_user.UserInfoData'
              type: object
        "403":
          description: Missing User ID / Unauthorized
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
        "404":
          description: User Not Found
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
        "500":
          description: Internal Server Error (UUID Parse Failed)
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
      security:
      - ApiKeyAuth: []
      summary: Get My User Information
      tags:
      - User
  /user/list:
    get:
      consumes:
      - application/json
      description: Fetches a list of users with support for pagination via limit and
        offset. Data is sourced from the search engine for high performance.
      parameters:
      - description: Maximum number of users to return (default 0)
        in: query
        name: limit
        type: string
      - description: Number of users to skip
        in: query
        name: offset
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Successful paginated list retrieval
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/data.UserSearchDoc'
                  type: array
              type: object
        "400":
          description: Invalid Input (Format Error)
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
        "500":
          description: Internal Server Error (Search Engine or Missing Offset)
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
      summary: List Users
      tags:
      - User
  /user/update:
    patch:
      consumes:
      - application/json
      description: |-
        Updates specific profile fields such as username, nickname, subtitle, avatar (URL), and bio (Base64).
        Validation: Username (5-255 chars), Nickname (max 24 chars), Subtitle (max 32 chars).
      parameters:
      - description: Updated User Profile Data
        in: body
        name: payload
        required: true
        schema:
          $ref: '#/definitions/service_user.UserInfoData'
      produces:
      - application/json
      responses:
        "200":
          description: Successful profile update
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
        "400":
          description: Invalid Input (Validation Failed)
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
        "403":
          description: Missing User ID / Unauthorized
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
        "500":
          description: Internal Server Error (Database Error / UUID Parse Failed)
          schema:
            allOf:
            - $ref: '#/definitions/utils.RespStatus'
            - properties:
                data:
                  type: object
              type: object
      security:
      - ApiKeyAuth: []
      summary: Update User Information
      tags:
      - User
swagger: "2.0"