post:
  operationId: listClientUsers
  summary: List client users
  description: |
    Permission: **ADMIN, OWNER**

    - Default sort: `created_at DESC`.
    - Sortable: `created_at`.
    - Supports stable cursor pagination with `last_object_id`, ordered by `created_at` and `_id`.
    - Omit `last_object_id` or send an empty string for the first batch.
    - Backend queries `limit + 1`; the extra record determines `has_more`, is dropped, and at most `limit` items are returned.
    - `search` ignores `statuses` and forces the default `created_at DESC` sort when active.
    - Send empty `statuses` to select all statuses, including `locked`.
    - Send empty `client_types` to select all client types (`BUSINESS`, `INDIVIDUAL`).
    - Returns `items: []`, `total: 0` when no data found.
  tags: [staffManagement]
  security:
    - bearerAuth: []
  requestBody:
    required: true
    content:
      application/json:
        schema:
          $ref: "../../components.yaml#/components/schemas/ListClientUsersRequest"
        example:
          search: ""
          statuses: ["active", "inactive"]
          client_types: ["BUSINESS", "INDIVIDUAL"]
          sort_by: "created_at"
          sort_dir: "desc"
          limit: 20
          last_object_id: ""
  responses:
    "200":
      description: Paginated list of client users — DTO returned directly
      content:
        application/json:
          schema:
            $ref: "../../components.yaml#/components/schemas/ListClientUsersResponse"
          example:
            items:
              - user_id: "usr_client_001"
                username: "juan.doe"
                full_name: "Juan Doe García"
                phone: "5219981234567"
                email: "juan.doe@example.com"
                address: "Av. Insurgentes Sur 1234, CDMX"
                client_type: "INDIVIDUAL"
                status: "active"
                created_at: "01/06/2026 09:00"
            total: 1
            limit: 20
            has_more: false
    "400":
      $ref: "../../components.yaml#/components/responses/Failure"
    "403":
      $ref: "../../components.yaml#/components/responses/Failure"