openapi: 3.0.3
info:
  title: PolyLAN AAndT Bot API
  description: >-
    Endpoints protected by the `aandt_apitoken_required` decorator
    (Plamingo/pAAndT/views.py). Intended for external "apibot" integrations
    that manage a single AAndT (animation/tournament) identified by the JWT
    bearer token, so no per-request AAndT id is otherwise needed.
    This spec was written by hand as a one-off snapshot of the current
    behaviour, not generated automatically — re-check it if the views change.
  version: "1.0.0"
servers:
  - url: /Plamingo/aandt/api/aandt

security:
  - bearerAuth: []

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        `Authorization: Bearer <token>` header. The token is a JWT signed
        with `settings.JWT_SECRET_KEY` (HS256), issuer `PolyLAN:AAndT`, and
        must carry an `aandt_pk` claim identifying the target AAndT. Obtained
        via `AAndT.generate_token()` (see `aandt_apibot` admin view).

  responses:
    Unauthorized:
      description: Missing/invalid Authorization header or token
      content:
        text/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: "No Authorization header"
    NotFound:
      description: The AAndT (or nested match) referenced by the token/path does not exist
      content:
        text/html:
          schema:
            type: string

  schemas:
    AAndTInfos:
      type: object
      properties:
        name:
          type: string
        status:
          type: string
          enum: [0prep, 1publ, 3insc, 5inscdone, 7inprog, 9done, 11reviewed]
        status_display:
          type: string
          example: "Matchs en cours"
        use_teams:
          type: boolean
        max_entities:
          type: integer

    MemberUser:
      type: object
      properties:
        id:
          type: integer
        username:
          type: string
        tournois_alias:
          type: string
          nullable: true

    MemberTeam:
      type: object
      properties:
        name:
          type: string
        leader:
          type: integer
          nullable: true
          description: pk of the leader's user, null if no leader
        members:
          type: array
          items:
            $ref: "#/components/schemas/MemberUser"

    Member:
      type: object
      properties:
        id:
          type: integer
          description: AAndTHasUserOrTeam pk
        score:
          type: number
        done_all_matches:
          type: boolean
        user:
          allOf:
            - $ref: "#/components/schemas/MemberUser"
          description: present only when the AAndT does not use teams
        team:
          allOf:
            - $ref: "#/components/schemas/MemberTeam"
          description: present only when the AAndT uses teams

    MatchRoundResult:
      type: object
      properties:
        score:
          type: number
        player_id:
          type: integer
          description: AAndTHasUserOrTeam pk

    MatchRound:
      type: object
      properties:
        round_id:
          type: integer
        results:
          type: array
          items:
            $ref: "#/components/schemas/MatchRoundResult"

    MatchMultiroundModes:
      type: string
      enum: [PA, PS, AP]

    Match:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        internal_id:
          type: string
        status:
          type: string
          enum: [waitPlayer, needConfirm, playing, done]
        status_display:
          type: string
        rounds_count:
          type: integer
        use_points:
          type: boolean
        points_are_positions:
          type: boolean
        multiround_modes:
          allOf:
            - $ref: "#/components/schemas/MatchMultiroundModes"
          nullable: true
        multiround_modes_display:
          type: string
          nullable: true
        creation_date:
          type: string
          example: "2026-08-01 10:00:00+00:00"
        playing_date:
          type: string
        done_date:
          type: string
        current_round:
          type: integer
        players:
          type: object
          description: map of AAndTHasUserOrTeam pk (string key) -> MatschHasPlayerOrTeam pk
          additionalProperties:
            type: integer
        rounds:
          type: array
          items:
            $ref: "#/components/schemas/MatchRound"

    Metadata:
      type: object
      description: Arbitrary JSON metadata stored by the bot
      additionalProperties: true

    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean

paths:
  /:
    get:
      operationId: aandt_api_infos
      summary: Get general information about the AAndT
      description: Read-only. AAndT is resolved from the bearer token.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  aandt:
                    $ref: "#/components/schemas/AAndTInfos"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /members:
    get:
      operationId: aandt_api_members
      summary: List the AAndT's registered members (users or teams)
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  members:
                    type: array
                    items:
                      $ref: "#/components/schemas/Member"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /matches:
    get:
      operationId: aandt_api_matches
      summary: List all matches of the AAndT with their rounds/results
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  matches:
                    type: array
                    items:
                      $ref: "#/components/schemas/Match"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /metadata:
    get:
      operationId: aandt_api_metadata_get
      summary: Get the AAndT's bot metadata
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  metadata:
                    $ref: "#/components/schemas/Metadata"
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      operationId: aandt_api_metadata_set
      summary: Set the AAndT's bot metadata
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                metadata:
                  $ref: "#/components/schemas/Metadata"
      responses:
        "200":
          description: Saved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /apibot:
    get:
      operationId: aandt_api_apibot_get
      summary: Get the AAndT's apibot activation state and display name
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  activated:
                    type: boolean
                  name:
                    type: string
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      operationId: aandt_api_apibot_set
      summary: Set the AAndT's apibot activation state and/or display name
      description: Broadcasts the update over Zuperpush after saving.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                activated:
                  type: boolean
                name:
                  type: string
      responses:
        "200":
          description: Saved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /message:
    get:
      operationId: aandt_api_message_get
      summary: Get the AAndT's apibot page message
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    nullable: true
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      operationId: aandt_api_message_set
      summary: Set the AAndT's apibot page message
      description: Broadcasts the update over Zuperpush after saving.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
      responses:
        "200":
          description: Saved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /log:
    post:
      operationId: aandt_api_log
      summary: Add a log entry to the AAndT's log (prefixed with "API:")
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [type, message]
              properties:
                type:
                  type: string
                  description: AAndTLog type, e.g. "info", "error"
                message:
                  type: string
      responses:
        "200":
          description: >-
            Always HTTP 200. `success` is false when the request is not a
            POST, or when `type`/`message` are missing from the body.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /match/{pk}/metadata:
    parameters:
      - name: pk
        in: path
        required: true
        schema:
          type: integer
        description: Matsch pk (must belong to the token's AAndT)
    get:
      operationId: aandt_api_match_metadata_get
      summary: Get a match's bot metadata
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  metadata:
                    $ref: "#/components/schemas/Metadata"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
    post:
      operationId: aandt_api_match_metadata_set
      summary: Set a match's bot metadata
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                metadata:
                  $ref: "#/components/schemas/Metadata"
      responses:
        "200":
          description: Saved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"

  /match/{pk}/messages:
    parameters:
      - name: pk
        in: path
        required: true
        schema:
          type: integer
        description: Matsch pk (must belong to the token's AAndT)
    get:
      operationId: aandt_api_match_messages_get
      summary: Get a match's bot messages (all/players/admin)
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  all:
                    type: string
                    nullable: true
                  players:
                    type: string
                    nullable: true
                  admin:
                    type: string
                    nullable: true
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
    post:
      operationId: aandt_api_match_messages_set
      summary: Set one or more of a match's bot messages
      description: >-
        Any of `all`, `players`, `admin` may be omitted; only the keys
        present in the body are updated. Triggers a Zuperpush update.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                all:
                  type: string
                players:
                  type: string
                admin:
                  type: string
      responses:
        "200":
          description: Saved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"

  /match/{pk}/sumbit_results:
    parameters:
      - name: pk
        in: path
        required: true
        schema:
          type: integer
        description: >-
          Matsch pk. Must belong to the token's AAndT and currently have
          status "playing", otherwise the request 404s.
    post:
      operationId: aandt_api_match_submit_results
      summary: Submit results for the match's current round
      description: >-
        `round` must equal the match's current round (`Matsch.cRound()`),
        otherwise the request is rejected. `results` maps a
        MatschHasPlayerOrTeam pk (string key) to that participant's score
        for the round (omitted participants default to 0 if `usePoints`,
        else 1). Advances/finishes the match and pushes live updates.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [round, results]
              properties:
                round:
                  type: integer
                results:
                  type: object
                  description: map of MatschHasPlayerOrTeam pk (string) -> score (int)
                  additionalProperties:
                    type: integer
      responses:
        "200":
          description: >-
            Always HTTP 200. `success` is false with a `message` when the
            request is not a POST, is missing `round`/`results`, or `round`
            does not match the match's current round.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                    enum: ["Missing parameters", "Wrong round"]
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"