paths:
  /admin/ip-whitelist:
    get:
      summary: List all Admin IP Whitelists
      description: Retrieve all IP addresses approved for SuperAdmin access. SuperAdmin only.
      tags: [Admin]
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: page
          schema: { type: integer, default: 1 }
        - in: query
          name: limit
          schema: { type: integer, default: 50 }
        - in: query
          name: status
          schema:
            type: string
            enum: [active, inactive]
      responses:
        '200':
          description: List of whitelisted IP addresses
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  total:
                    type: integer
                    example: 3
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AdminIpWhitelist'
        '403':
          description: Forbidden - SuperAdmin only

    post:
      summary: Add a new IP Address to the Admin Whitelist
      description: |
        Registers an IP address as an approved access point for SuperAdmin operations.
        Once at least one IP is in the database, ALL SuperAdmin routes will be restricted to only those IPs.
        **SuperAdmin only.**
      tags: [Admin]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [ipAddress]
              properties:
                ipAddress:
                  type: string
                  description: The static IPv4 or IPv6 address to whitelist
                  example: "102.89.83.63"
                description:
                  type: string
                  description: A label/note for this IP (e.g. "Main Office IP")
                  example: "Super Admin - Primary Office IP"
      responses:
        '201':
          description: IP Address whitelisted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "IP Address whitelisted successfully"
                  data:
                    $ref: '#/components/schemas/AdminIpWhitelist'
        '400':
          description: IP Address already exists or missing required field
        '403':
          description: Forbidden - SuperAdmin only

  /admin/ip-whitelist/{id}:
    patch:
      summary: Update an Admin IP Whitelist entry
      description: Update the status (active/inactive) or description of a whitelisted IP. SuperAdmin only.
      tags: [Admin]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
            example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum: [active, inactive]
                  example: "inactive"
                description:
                  type: string
                  example: "Temporary office IP — deactivated"
      responses:
        '200':
          description: IP Address updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "IP Address updated successfully"
                  data:
                    $ref: '#/components/schemas/AdminIpWhitelist'
        '404':
          description: IP Address not found
        '403':
          description: Forbidden - SuperAdmin only

    delete:
      summary: Remove an IP from the Admin Whitelist
      description: Deletes an IP address from the SuperAdmin whitelist. SuperAdmin only.
      tags: [Admin]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
            example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      responses:
        '200':
          description: IP Address removed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "IP Address removed successfully"
        '404':
          description: IP Address not found
        '403':
          description: Forbidden - SuperAdmin only

components:
  schemas:
    AdminIpWhitelist:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        ipAddress:
          type: string
          example: "102.89.83.63"
        description:
          type: string
          example: "Super Admin - Primary Office IP"
        status:
          type: string
          enum: [active, inactive]
          example: "active"
        addedBy:
          type: string
          format: uuid
          nullable: true
          example: "admin-uuid-here"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
