users:
  get:
    operationId: listUsers
    summary: List users
    description: Returns a paginated list of users with optional search.
    tags:
      - Users
    parameters:
      - name: page
        in: query
        description: Page number (1-based)
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        description: Number of users per page (max 100)
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: search
        in: query
        description: Search by name or email
        schema:
          type: string
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/users.yaml#/ListUsersResponse'
      '500':
        $ref: '../../openapi.yaml#/components/responses/InternalError'

  post:
    operationId: createUser
    summary: Create user
    description: Manually creates a new user in the organization.
    tags:
      - Users
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '../../schemas/management/users.yaml#/CreateUserRequest'
    responses:
      '200':
        description: User created successfully
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/users.yaml#/UserResponse'
      '400':
        $ref: '../../openapi.yaml#/components/responses/BadRequest'
      '409':
        description: User with this email already exists
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/common.yaml#/ErrorResponse'
      '500':
        $ref: '../../openapi.yaml#/components/responses/InternalError'

users-by-id:
  delete:
    operationId: deleteUser
    summary: Delete user
    description: >
      Permanently removes a user from the organization. This cascades to delete
      the user's governance settings (budget/rate limits), team memberships,
      access profiles, and OIDC sessions. Cannot delete yourself.
    tags:
      - Users
    parameters:
      - name: id
        in: path
        required: true
        description: User ID
        schema:
          type: string
    responses:
      '200':
        description: User deleted successfully
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/common.yaml#/MessageResponse'
      '400':
        description: Bad request (e.g. cannot delete yourself)
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/common.yaml#/ErrorResponse'
      '404':
        description: User not found
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/common.yaml#/ErrorResponse'
      '500':
        $ref: '../../openapi.yaml#/components/responses/InternalError'

users-me-permissions:
  get:
    operationId: getCurrentUserPermissions
    summary: Get current user permissions
    description: >
      Returns the RBAC permissions for the authenticated user. When SCIM is not
      enabled, returns full permissions for all resources. Otherwise returns the
      permissions associated with the user's assigned role.
    tags:
      - Users
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/users.yaml#/PermissionsResponse'
      '401':
        description: Unauthorized (user not authenticated)
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/common.yaml#/ErrorResponse'
      '404':
        description: User not found
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/common.yaml#/ErrorResponse'
      '500':
        $ref: '../../openapi.yaml#/components/responses/InternalError'

users-role:
  put:
    operationId: assignUserRole
    summary: Assign role to user
    description: >
      Assigns an RBAC role to a user. This also auto-assigns the default
      access profile for the new role and reloads the RBAC permission cache.
    tags:
      - Users
    parameters:
      - name: id
        in: path
        required: true
        description: User ID
        schema:
          type: string
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '../../schemas/management/users.yaml#/AssignUserRoleRequest'
    responses:
      '200':
        description: Role assigned successfully
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/common.yaml#/MessageResponse'
      '400':
        $ref: '../../openapi.yaml#/components/responses/BadRequest'
      '404':
        description: User or role not found
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/common.yaml#/ErrorResponse'
      '500':
        $ref: '../../openapi.yaml#/components/responses/InternalError'

users-teams:
  get:
    operationId: getUserTeams
    summary: Get user's teams
    description: Returns the list of teams a user belongs to, including the membership source.
    tags:
      - Users
    parameters:
      - name: id
        in: path
        required: true
        description: User ID
        schema:
          type: string
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/users.yaml#/UserTeamsResponse'
      '400':
        $ref: '../../openapi.yaml#/components/responses/BadRequest'
      '404':
        description: User not found
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/common.yaml#/ErrorResponse'
      '500':
        $ref: '../../openapi.yaml#/components/responses/InternalError'

  put:
    operationId: updateUserTeams
    summary: Update user's team assignments
    description: >
      Replaces the user's manual team assignments. Synced team memberships
      (from SCIM providers) are preserved and cannot be removed via this endpoint.
    tags:
      - Users
    parameters:
      - name: id
        in: path
        required: true
        description: User ID
        schema:
          type: string
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '../../schemas/management/users.yaml#/UpdateUserTeamsRequest'
    responses:
      '200':
        description: Teams updated successfully
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/common.yaml#/MessageResponse'
      '400':
        description: Bad request (e.g. team not found)
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/common.yaml#/ErrorResponse'
      '404':
        description: User not found
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/common.yaml#/ErrorResponse'
      '500':
        $ref: '../../openapi.yaml#/components/responses/InternalError'

# ---- Teams ----

teams:
  get:
    operationId: listTeams
    summary: List teams
    description: Returns a paginated list of teams with optional search.
    tags:
      - Teams
    parameters:
      - name: page
        in: query
        description: Page number (1-based)
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        description: Number of teams per page (max 100)
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: search
        in: query
        description: Search by team name
        schema:
          type: string
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/users.yaml#/ListTeamsResponse'
      '500':
        $ref: '../../openapi.yaml#/components/responses/InternalError'

  post:
    operationId: createTeam
    summary: Create team
    description: Creates a new team. The team ID is derived from the name.
    tags:
      - Teams
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '../../schemas/management/users.yaml#/CreateTeamRequest'
    responses:
      '200':
        description: Team created successfully
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/users.yaml#/CreateTeamResponse'
      '400':
        $ref: '../../openapi.yaml#/components/responses/BadRequest'
      '409':
        description: Team with this name already exists
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/common.yaml#/ErrorResponse'
      '500':
        $ref: '../../openapi.yaml#/components/responses/InternalError'

teams-by-id:
  get:
    operationId: getTeam
    summary: Get team
    description: Returns details of a specific team including member count.
    tags:
      - Teams
    parameters:
      - name: id
        in: path
        required: true
        description: Team ID
        schema:
          type: string
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/users.yaml#/TeamObject'
      '404':
        description: Team not found
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/common.yaml#/ErrorResponse'
      '500':
        $ref: '../../openapi.yaml#/components/responses/InternalError'

  put:
    operationId: updateTeam
    summary: Update team
    description: Updates a team. Note that renaming teams is not allowed.
    tags:
      - Teams
    parameters:
      - name: id
        in: path
        required: true
        description: Team ID
        schema:
          type: string
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '../../schemas/management/users.yaml#/UpdateTeamRequest'
    responses:
      '200':
        description: Team updated successfully
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/users.yaml#/CreateTeamResponse'
      '400':
        description: Bad request (e.g. renaming not allowed)
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/common.yaml#/ErrorResponse'
      '404':
        description: Team not found
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/common.yaml#/ErrorResponse'
      '500':
        $ref: '../../openapi.yaml#/components/responses/InternalError'

  delete:
    operationId: deleteTeam
    summary: Delete team
    description: Permanently removes a team.
    tags:
      - Teams
    parameters:
      - name: id
        in: path
        required: true
        description: Team ID
        schema:
          type: string
    responses:
      '200':
        description: Team deleted successfully
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/common.yaml#/MessageResponse'
      '404':
        description: Team not found
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/common.yaml#/ErrorResponse'
      '500':
        $ref: '../../openapi.yaml#/components/responses/InternalError'

# ---- Team Members ----

team-members:
  get:
    operationId: getTeamMembers
    summary: List team members
    description: Returns all members of a team with their user details and membership source.
    tags:
      - Teams
    parameters:
      - name: id
        in: path
        required: true
        description: Team ID
        schema:
          type: string
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/users.yaml#/TeamMembersResponse'
      '400':
        $ref: '../../openapi.yaml#/components/responses/BadRequest'
      '404':
        description: Team not found
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/common.yaml#/ErrorResponse'
      '500':
        $ref: '../../openapi.yaml#/components/responses/InternalError'

  post:
    operationId: addTeamMember
    summary: Add team member
    description: Adds a user to a team. Both the team and user must exist.
    tags:
      - Teams
    parameters:
      - name: id
        in: path
        required: true
        description: Team ID
        schema:
          type: string
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '../../schemas/management/users.yaml#/AddTeamMemberRequest'
    responses:
      '200':
        description: Member added successfully
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/common.yaml#/MessageResponse'
      '404':
        description: Team or user not found
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/common.yaml#/ErrorResponse'
      '409':
        description: User is already a member of this team
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/common.yaml#/ErrorResponse'
      '500':
        $ref: '../../openapi.yaml#/components/responses/InternalError'

team-member-by-id:
  delete:
    operationId: removeTeamMember
    summary: Remove team member
    description: Removes a user from a team.
    tags:
      - Teams
    parameters:
      - name: id
        in: path
        required: true
        description: Team ID
        schema:
          type: string
      - name: userId
        in: path
        required: true
        description: User ID to remove
        schema:
          type: string
    responses:
      '200':
        description: Member removed successfully
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/common.yaml#/MessageResponse'
      '404':
        description: Membership not found
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/common.yaml#/ErrorResponse'
      '500':
        $ref: '../../openapi.yaml#/components/responses/InternalError'