openapi: "3.0.0"
info:
  title: "Server API"
  version: "1.0.0"
servers:
  - url: "https://example.com"
    description: "Primary server (update with actual URL)"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    cookieAuth:
      type: apiKey
      in: cookie
      name: refreshToken
  schemas:
    ContactResponse:
      type: string
      example: "contact: lifegame2021team@gmail.com"
    AdsTxtResponse:
      type: string
      example: "ADS TXT content from configuration"
    TokenResponse:
      type: object
      properties:
        accessToken:
          type: string
          example: "eyJhbGciOiJIUzI1NiIsInR..."
    GenericResponse:
      type: object
      additionalProperties: true
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
paths:
  /:
    get:
      tags:
        - Root
      summary: "Get root contact info"
      responses:
        "200":
          description: "Contact information"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactResponse"

  /ads.txt:
    get:
      tags:
        - Root
      summary: "Get ads.txt content"
      responses:
        "200":
          description: "ADS TXT content"
          content:
            text/plain:
              schema:
                $ref: "#/components/schemas/AdsTxtResponse"

  /auth/access-token:
    get:
      tags:
        - Auth
      summary: "Obtain a new access token using a valid refresh token"
      security:
        - cookieAuth: []
      responses:
        "200":
          description: "Access token generated successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenResponse"
        "401":
          description: "Unauthorized – invalid or missing credentials"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /auth/logout:
    post:
      tags:
        - Auth
      summary: "Logout user (POST)"
      security:
        - cookieAuth: []
      responses:
        "200":
          description: "User successfully logged out"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericResponse"
    get:
      tags:
        - Auth
      summary: "Logout user (GET)"
      security:
        - cookieAuth: []
      responses:
        "200":
          description: "User successfully logged out"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericResponse"

  /auth/google-oauth/{web}:
    get:
      tags:
        - Auth
      summary: "Authenticate user with Google OAuth"
      parameters:
        - in: path
          name: web
          required: true
          schema:
            type: string
          description: "A dynamic segment representing the web redirect path"
        - in: query
          name: code
          required: true
          schema:
            type: string
          description: "The OAuth authorization code returned by Google"
      responses:
        "200":
          description: "Google OAuth callback response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericResponse"
        "400":
          description: "Bad Request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /temp-signup:
    post:
      tags:
        - Temp Signup
      summary: "Temporarily sign up a new user with hCaptcha verification"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                hCaptchaSuccessToken:
                  type: string
                username:
                  type: string
                countryCode3:
                  type: string
              required:
                - hCaptchaSuccessToken
                - username
                - countryCode3
      responses:
        "200":
          description: "Temporary signup successful"
          content:
            application/json:
              schema:
                type: boolean
                example: true
        "400":
          description: "Bad Request – invalid hCaptcha token or missing fields"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /land-events:
    get:
      tags:
        - Land Events
      summary: "Retrieve a list of recent land events"
      parameters:
        - in: header
          name: timezone
          schema:
            type: string
          required: false
          description: "Timezone identifier (e.g., 'Asia/Seoul')"
      security:
        - bearerAuth: []
      responses:
        "200":
          description: "A list of land event summaries"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/GenericResponse"
        "401":
          description: "Unauthorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /dice-toss:
    post:
      tags:
        - Dice Toss
      summary: "Toss dice and receive a gaming response message"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
              required:
                - userId
      security:
        - bearerAuth: []
      responses:
        "200":
          description: "Dice toss result with game data"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericResponse"
        "400":
          description: "Bad Request – invalid input"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /profile/me:
    get:
      tags:
        - Profile
      summary: "Retrieve the authenticated user's profile information"
      security:
        - bearerAuth: []
      responses:
        "200":
          description: "User profile data"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericResponse"
        "401":
          description: "Unauthorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    patch:
      tags:
        - Profile
      summary: "Update the authenticated user's profile"
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                countryCode3:
                  type: string
              required:
                - username
                - countryCode3
      responses:
        "200":
          description: "Profile updated successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericResponse"
        "400":
          description: "Bad Request – validation errors"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /profile/others:
    get:
      tags:
        - Profile
      summary: "Retrieve profiles of other users"
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: limit
          required: false
          schema:
            type: integer
          description: "Maximum number of profiles to return"
        - in: query
          name: page
          required: false
          schema:
            type: integer
          description: "Page number for pagination"
        - in: query
          name: updatedAfter
          required: false
          schema:
            type: string
            format: date-time
          description: "Filter profiles updated after this datetime"
      responses:
        "200":
          description: "List of other user profiles"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/GenericResponse"
        "401":
          description: "Unauthorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /profile/complete-signup:
    post:
      tags:
        - Profile
      summary: "Complete the authenticated user's signup process"
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                countryCode3:
                  type: string
                username:
                  type: string
              required:
                - countryCode3
                - username
      responses:
        "200":
          description: "Signup completed successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericResponse"
        "400":
          description: "Bad Request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /profile:
    delete:
      tags:
        - Profile
      summary: "Terminate (delete) the authenticated user's account"
      security:
        - bearerAuth: []
      responses:
        "200":
          description: "User account terminated successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericResponse"
        "401":
          description: "Unauthorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /recent-skill-logs:
    get:
      tags:
        - Skill Logs
      summary: "Retrieve recent skill logs for the authenticated user"
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: limit
          required: false
          schema:
            type: integer
          description: "The maximum number of logs to retrieve"
      responses:
        "200":
          description: "A list of recent skill logs"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/GenericResponse"
        "401":
          description: "Unauthorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /land-comments:
    post:
      tags:
        - Land Comments
      summary: "Register a comment on a land (game event)"
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
                comment:
                  type: string
              required:
                - userId
                - comment
      responses:
        "200":
          description: "Comment registered successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericResponse"
        "400":
          description: "Bad Request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /scenarios/d1/map:
    get:
      tags:
        - Scenarios
      summary: "Retrieve skill group aliases for scenario D1"
      security:
        - bearerAuth: []
      responses:
        "200":
          description: "A mapping of skill groups and their aliases"
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /user-interaction-web:
    post:
      tags:
        - User Interaction
      summary: "Perform a user interaction call to trigger a skill"
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                callingSkillRoute:
                  type: string
                callingSkillParam:
                  type: object
              required:
                - callingSkillRoute
      responses:
        "200":
          description: "Response from the user interaction call"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericResponse"
        "400":
          description: "Bad Request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /health/detail:
    get:
      tags:
        - Health
      summary: "Detailed health check"
      responses:
        "200":
          description: "Detailed health status"
          content:
            application/json:
              schema:
                type: string
                example: "OK"

  /health:
    get:
      tags:
        - Health
      summary: "Simple health check"
      responses:
        "200":
          description: "Simple health status"
          content:
            application/json:
              schema:
                type: string
                example: "m"
security:
  - bearerAuth: []
