openapi: 3.1.0
info:
  title: TableTime API
  version: 1.0.0-draft
  description: Draft OpenAPI for TableTime platform (Phase 0 documentation)

servers:
  - url: https://api.tabletime.example/api/v1
    description: Production
  - url: http://localhost:8000/api/v1
    description: Local dev

tags:
  - name: auth
  - name: sessions
  - name: games
  - name: media

paths:
  /auth/guest:
    post:
      tags: [auth]
      summary: Issue guest token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                display_name:
                  type: string
      responses:
        "200":
          description: Guest token issued
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthTokens"

  /auth/register:
    post:
      tags: [auth]
      summary: Register user
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
                  minLength: 8
      responses:
        "201":
          description: User created

  /auth/login:
    post:
      tags: [auth]
      summary: Login
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email:
                  type: string
                password:
                  type: string
      responses:
        "200":
          description: JWT issued

  /auth/telegram:
    post:
      tags: [auth]
      summary: Verify Telegram Login Widget
      responses:
        "200":
          description: JWT issued

  /sessions:
    post:
      tags: [sessions]
      summary: Create session
      security:
        - bearerAuth: []
        - guestAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                display_name:
                  type: string
                max_players:
                  type: integer
                  default: 4
      responses:
        "201":
          description: Session created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Session"

  /sessions/join:
    post:
      tags: [sessions]
      summary: Join session by invite code
      security:
        - bearerAuth: []
        - guestAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [invite_code]
              properties:
                invite_code:
                  type: string
                channel:
                  type: string
                  enum: [web, telegram]
      responses:
        "200":
          description: Joined

  /sessions/{session_id}:
    get:
      tags: [sessions]
      summary: Get session
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Session details

  /sessions/{session_id}/games:
    post:
      tags: [sessions]
      summary: Start game in session
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [plugin_id]
              properties:
                plugin_id:
                  type: string
                  example: dice_board
      responses:
        "201":
          description: Game started

  /sessions/{session_id}/close:
    post:
      tags: [sessions]
      summary: Close session (host only)
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Closed

  /games/{game_id}/state:
    get:
      tags: [games]
      summary: Get current game state
      parameters:
        - name: game_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Game state

  /games/{game_id}/actions:
    post:
      tags: [games]
      summary: Submit game action
      parameters:
        - name: game_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: Idempotency-Key
          in: header
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GameAction"
      responses:
        "200":
          description: Action applied
        "409":
          description: Invalid phase or action

  /games/{game_id}/audit:
    get:
      tags: [games]
      summary: Get action audit log
      parameters:
        - name: game_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Audit entries

  /media/render/{game_id}:
    get:
      tags: [media]
      summary: Render board image for game
      parameters:
        - name: game_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: format
          in: query
          schema:
            type: string
            enum: [png, webp]
            default: png
      responses:
        "200":
          description: Image URL or binary
          content:
            image/png:
              schema:
                type: string
                format: binary

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    guestAuth:
      type: apiKey
      in: header
      name: Authorization
      description: "Guest <token>"

  schemas:
    AuthTokens:
      type: object
      properties:
        access_token:
          type: string
        refresh_token:
          type: string
        guest_token:
          type: string
        token_type:
          type: string

    Session:
      type: object
      properties:
        id:
          type: string
          format: uuid
        invite_code:
          type: string
        status:
          type: string
          enum: [Lobby, GameSelection, InGame, Paused, Closed]
        participants:
          type: array
          items:
            $ref: "#/components/schemas/Participant"

    Participant:
      type: object
      properties:
        id:
          type: string
          format: uuid
        display_name:
          type: string
        role:
          type: string
          enum: [host, player, spectator]
        presence_web:
          type: boolean
        presence_telegram:
          type: boolean

    GameAction:
      type: object
      required: [action_id, action_type]
      properties:
        action_id:
          type: string
          format: uuid
        action_type:
          type: string
          enum: [roll_dice, choose_cell, pass]
        payload:
          type: object
          additionalProperties: true