openapi: 3.1.1
info:
  title: Opal User Service - User State
  version: "0.0.1"
paths:
  /v2/users/{id}/state:
    get:
      operationId: getUserStateV2
      summary: Get User State (v2)
      description: >
        Returns the authenticated user's state (v2).
        The path ID must be `0`; any non-zero value is rejected.
        V2 payload includes `domains`, optional `fines`, and `business_unit_users`.
      tags:
        - Users State
      parameters:
        - name: id
          in: path
          required: true
          description: User identifier. Must be `0` for the authenticated user.
          schema:
            type: integer
            format: int64
            minimum: 0
            maximum: 0
        - name: X-New-Login
          in: header
          required: true
          description: |
            Indicates whether this request is immediately following a login.
            - true: request immediately after login
            - false: standard refresh of user state.
          schema:
            type: boolean
      responses:
        '200':
          description: Successful retrieval of user state (v2)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserStateResponseV2'
        '400':
          description: Invalid request (for example, non-zero user id)
          content:
            application/json+problem:
              schema:
                $ref: './common.yaml#/components/schemas/ProblemDetail'
        '404':
          description: User not found
          content:
            application/json+problem:
              schema:
                $ref: './common.yaml#/components/schemas/ProblemDetail'

components:
  schemas:
    # ---------------------------
    # V2 response (expanded)
    # ---------------------------
    UserStateResponseV2:
      type: object
      required:
        - cache_name
        - user_id
        - username
        - status
        - version
        - domains
      properties:
        cache_name:
          type: string
          description: The cache key that the user state has been stored under.
        user_id:
          type: integer
          format: int64
          description: users.user_id
        username:
          type: string
          description: users.username
        name:
          type: string
          description: Obtained from access token until persisted in DB (applies when id = 0).
        status:
          type: string
          description: Derived user status.
          enum:
            - PENDING
            - ACTIVE
            - SUSPENDED
            - DEACTIVATED
        version:
          type: integer
          description: users.version
        domains:
          $ref: '#/components/schemas/Domains'

    Domains:
      type: object
      required:
        - fines
      properties:
        fines:
          $ref: '#/components/schemas/Domain'

    Domain:
      type: object
      description: Domain object
      required:
        - business_unit_users
      properties:
        business_unit_users:
          minItems: 0
          type: array
          items:
            $ref: './common.yaml#/components/schemas/BusinessUnitUser'