pterodactyl-api-wrapper/src/class/source/app/users/listUsers.ts

[](https://npmjs.com/package/pterodactyl-api-wrapper) [](LICENSE)

import ApplicationAPICall from "../../../../functions/createAppCall";

export interface Response {
    object: string,
    data: {
        object: string,
        attributes: {
            id: number,
            external_id: string | null,
            uuid: string,
            username: string,
            email: string,
            first_name: string,
            last_name: string,
            language: string,
            root_admin: boolean,
            "2fa": boolean,
            created_at: string,
            updated_at: string
        }
    }[],
    meta: {
        pagination: {
            total: number,
            count: number,
            per_page: number,
            current_page: number,
            total_page: number,
            links: object
        }
    }
}

/**
 * Retrieves a list of users from the Pterodactyl panel API, with optional filters and sorting.
 * This function makes a `GET` request and includes the request body if required.
 *
 * @param {Object} options - Configuration options for the API call.
 * @param {string} options.apiKey - The API key for authentication.
 * @param {string} options.panel - The base URL of the Pterodactyl panel.
 * @param {boolean} [options.showLinkedServers=false] - Whether to include linked servers in the response.
 * @param {Object} [options.filters] - Filters to apply when retrieving users.
 * @param {string} [options.filters.email] - Filter users by their email address.
 * @param {string} [options.filters.uuid] - Filter users by their UUID.
 * @param {string} [options.filters.username] - Filter users by their username.
 * @param {string} [options.filters.external_id] - Filter users by their external ID.
 * @param {Object} [options.sortBy] - Sorting preferences for the response.
 * @param {boolean} [options.sortBy.id=false] - Sort users by ID.
 * @param {boolean} [options.sortBy.uuid=false] - Sort users by UUID.
 * @returns {Promise<Response>} - A Promise resolving to the API response.
 *
 * @throws {Error} - Throws an error if the API request fails.
 */

export default async function listUsers(options: { 
    apiKey: string, 
    panel: string, 
    showLinkedServers?: boolean, 
    filters?: { 
        email?: string, 
        uuid?: string, 
        username?: string, 
        external_id?: string
    },
    sortBy?: {
        id?: boolean,
        uuid?: boolean
    }
}): Promise<Response> {
    const body = {
        servers: options.showLinkedServers ?? false,
        filters: {
            email: options.filters?.email ?? null,
            uuid: options.filters?.uuid ?? null,
            username: options.filters?.username ?? null,
            external_id: options.filters?.external_id ?? null
        },
        sortBy: {
            id: options.sortBy?.id ?? false,
            uuid: options.sortBy?.uuid ?? false
        }
    };

    return ApplicationAPICall({
        panel: options.panel,
        apiKey: options.apiKey,
        endpoint: "users",
        method: "GET",
        body: JSON.stringify(body) 
    });
}