@b01lers/ctfd-api 1.2.1 → 2.0.0

package/dist/index.js

@@ -1,5 +1,147 @@
 'use strict';
 
+function createChallengesMethods(client) {
+  return {
+    /**
+     * Attempts to submit a flag for the given challenge.
+     * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/challenges/operation/post_challenge_attempt}
+     *
+     * @param id The ID of the challenge to submit a flag for.
+     * @param flag The flag to submit.
+     * @returns The status of the flag submission.
+     */
+    async submitFlag(id, flag) {
+      const { session, nonce } = await client.getAuthedSessionNonce();
+      const res = await (await fetch(`${client.url}/api/v1/challenges/attempt`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Csrf-Token": nonce,
+          cookie: session
+        },
+        body: JSON.stringify({ challenge_id: id, submission: flag })
+      })).json();
+      return res.data;
+    },
+    /**
+     * Fetches the list of all challenges.
+     * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/challenges/operation/get_challenge_list}
+     *
+     * @returns The list of challenges, as a `Challenge[]`.
+     */
+    async get() {
+      return client.callApi("/challenges");
+    },
+    /**
+     * Fetches details for the given challenge.
+     * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/challenges/operation/get_challenge}.
+     *
+     * @param id The ID of the challenge to fetch.
+     * @returns The challenge details.
+     */
+    async getDetails(id) {
+      return client.callApi(`/challenges/${id}`);
+    },
+    /**
+     * Fetches solves for the given challenge.
+     * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/challenges/operation/get_challenge_solves}.
+     *
+     * @param id The ID of the challenge to fetch solves for.
+     * @returns The challenge's solves.
+     */
+    async getSolves(id) {
+      return client.callApi(`/challenges/${id}/solves`);
+    }
+  };
+}
+
+function createScoreboardMethods(client) {
+  return {
+    /**
+     * Fetches the list of scoreboard entries.
+     * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/scoreboard/operation/get_scoreboard_list}
+     *
+     * @returns The scoreboard, as a `ScoreboardEntry[]`.
+     */
+    async get() {
+      return client.callApi("/scoreboard");
+    },
+    /**
+     * Fetches details for the top `n` teams on the scoreboard.
+     * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/scoreboard/operation/get_scoreboard_detail}
+     *
+     * @param count The number of teams to fetch.
+     * @returns The scoreboard details.
+     */
+    async getTop(count) {
+      return client.callApi(`/scoreboard/top/${count}`);
+    }
+  };
+}
+
+function createUsersMethods(client) {
+  return {
+    me: {
+      /**
+       * Retrieves the currently logged-in user.
+       * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/users/operation/get_user_private}
+       * @returns The logged-in user.
+       */
+      async get() {
+        return client.callApi("/users/me");
+      },
+      /**
+       * Retrieves solves for the currently logged-in user.
+       * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/users/operation/get_user_private_solves}
+       *
+       * @returns The logged-in user's solves.
+       */
+      async getSolves() {
+        return client.callApi("/users/me/solves");
+      },
+      /**
+       * Retrieves awards for the currently logged-in user.
+       * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/users/operation/get_user_private_awards}
+       *
+       * @returns The logged-in user's awards.
+       */
+      async getAwards() {
+        return client.callApi("/users/me/awards");
+      }
+    },
+    /**
+     * Retrieves a user by ID.
+     * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/users/operation/get_user_public}
+     *
+     * @param id The ID of the user to retrieve.
+     * @returns The fetched user.
+     */
+    async getById(id) {
+      return client.callApi(`/users/${id}`);
+    },
+    /**
+     * Retrieves solves for a given user.
+     * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/users/operation/get_user_public_solves}
+     *
+     * @param id The ID of the user to retrieve solves for.
+     * @returns The user's solves.
+     */
+    async getSolves(id) {
+      return client.callApi(`/users/${id}/solves`);
+    },
+    /**
+     * Retrieves awards for a given user.
+     * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/users/operation/get_user_public_awards}
+     *
+     * @param id The ID of the user to retrieve awards for.
+     * @returns The user's awards.
+     */
+    async getAwards(id) {
+      return client.callApi(`/users/${id}/awards`);
+    }
+  };
+}
+
 function extractNonce(raw) {
   return raw.match(/'csrfNonce': "(.+?)"/)[1];
 }
@@ -15,40 +157,19 @@ class CTFdClient {
     __publicField(this, "cachedSession", null);
     __publicField(this, "cachedNonce", null);
     __publicField(this, "sessionExpiry", /* @__PURE__ */ new Date());
+    __publicField(this, "challenges");
+    __publicField(this, "scoreboard");
+    __publicField(this, "users");
     this.url = options.url.endsWith("/") ? options.url.slice(0, -1) : options.url;
     this.username = options.username;
     this.password = options.password;
+    this.challenges = createChallengesMethods(this);
+    this.scoreboard = createScoreboardMethods(this);
+    this.users = createUsersMethods(this);
   }
-  async submitFlag(id, flag) {
-    const { session, nonce } = await this.getAuthedSessionNonce();
-    const res = await (await fetch(`${this.url}/api/v1/challenges/attempt`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "Csrf-Token": nonce,
-        cookie: session
-      },
-      body: JSON.stringify({ challenge_id: id, submission: flag })
-    })).json();
-    return res.data;
-  }
-  async getChallenges() {
-    const { session } = await this.getAuthedSessionNonce();
-    const res = await (await fetch(`${this.url}/api/v1/challenges`, {
-      headers: { cookie: session }
-    })).json();
-    return res.data;
-  }
-  async getChallengeDetails(id) {
-    const { session } = await this.getAuthedSessionNonce();
-    const res = await (await fetch(`${this.url}/api/v1/challenges/${id}`, {
-      headers: { cookie: session }
-    })).json();
-    return res.data;
-  }
-  async getScoreboard() {
+  async callApi(endpoint) {
     const { session, nonce } = await this.getAuthedSessionNonce();
-    const res = await (await fetch(`${this.url}/api/v1/scoreboard`, {
+    const res = await (await fetch(`${this.url}/api/v1${endpoint}`, {
       headers: {
         "Csrf-Token": nonce,
         cookie: session
@@ -56,22 +177,23 @@ class CTFdClient {
     })).json();
     return res.data;
   }
+  // TODO
   async getAuthedSessionNonce() {
     if (/* @__PURE__ */ new Date() < this.sessionExpiry && this.cachedSession && this.cachedNonce)
       return { session: this.cachedSession, nonce: this.cachedNonce };
     const res = await fetch(`${this.url}/login`);
     const [session] = res.headers.getSetCookie()[0].split("; ");
     const nonce = extractNonce(await res.text());
-    const formData = new FormData();
-    formData.append("name", this.username);
-    formData.append("password", this.password);
-    formData.append("_submit", "Submit");
-    formData.append("nonce", nonce);
+    const params = new URLSearchParams();
+    params.append("name", this.username);
+    params.append("password", this.password);
+    params.append("_submit", "Submit");
+    params.append("nonce", nonce);
     const loginRes = await fetch(`${this.url}/login`, {
       method: "POST",
       headers: { cookie: session },
       redirect: "manual",
-      body: formData
+      body: params
     });
     const [authedSession, expiresGmt] = loginRes.headers.getSetCookie()[0].split("; ");
     const authedRaw = await (await fetch(`${this.url}/challenges`, {

package/dist/types.d.ts

@@ -1,30 +1,11 @@
-type BaseScoreboardEntry = {
-    pos: number;
+interface Solve {
     account_id: number;
     account_url: string;
-    oauth_id: null;
+    date: string;
     name: string;
-    score: number;
-    bracket_id: number | null;
-    bracket_name: string | null;
-};
-type ScoreboardUserEntry = BaseScoreboardEntry & {
-    account_type: "user";
-};
-type ScoreboardTeamEntry = BaseScoreboardEntry & {
-    account_type: "team";
-    members: {
-        id: number;
-        oauth_id: null;
-        name: string;
-        score: number;
-        bracket_id: null;
-        bracket_name: null;
-    }[];
-};
-type ScoreboardEntry = ScoreboardUserEntry | ScoreboardTeamEntry;
+}
 type ChallengeType = 'standard' | 'multiple_choice' | 'code';
-type ChallengeData = {
+interface Challenge {
     id: number;
     type: ChallengeType;
     name: string;
@@ -35,7 +16,7 @@ type ChallengeData = {
     tags: string[];
     template: string;
     value: number;
-};
+}
 type BaseChallengeDetails = {
     id: number;
     name: string;
@@ -80,19 +61,15 @@ type ProgrammingChallengeDetails = BaseChallengeDetails & {
 };
 type ChallengeDetails = StandardChallengeDetails | ProgrammingChallengeDetails;
 
-type ClientOptions = {
-    url: string;
-    username: string;
-    password: string;
-};
-declare class CTFdClient {
-    private readonly url;
-    private readonly username;
-    private readonly password;
-    private cachedSession;
-    private cachedNonce;
-    private sessionExpiry;
-    constructor(options: ClientOptions);
+declare function createChallengesMethods(client: CTFdClient): {
+    /**
+     * Attempts to submit a flag for the given challenge.
+     * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/challenges/operation/post_challenge_attempt}
+     *
+     * @param id The ID of the challenge to submit a flag for.
+     * @param flag The flag to submit.
+     * @returns The status of the flag submission.
+     */
     submitFlag(id: number, flag: string): Promise<{
         status: "incorrect";
         message: "Incorrect";
@@ -109,10 +86,206 @@ declare class CTFdClient {
         status: "ratelimited";
         message: "You're submitting flags too fast. Slow down.";
     }>;
-    getChallenges(): Promise<ChallengeData[]>;
-    getChallengeDetails(id: number): Promise<ChallengeDetails>;
-    getScoreboard(): Promise<ScoreboardEntry[]>;
-    private getAuthedSessionNonce;
+    /**
+     * Fetches the list of all challenges.
+     * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/challenges/operation/get_challenge_list}
+     *
+     * @returns The list of challenges, as a `Challenge[]`.
+     */
+    get(): Promise<Challenge[]>;
+    /**
+     * Fetches details for the given challenge.
+     * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/challenges/operation/get_challenge}.
+     *
+     * @param id The ID of the challenge to fetch.
+     * @returns The challenge details.
+     */
+    getDetails(id: number): Promise<ChallengeDetails>;
+    /**
+     * Fetches solves for the given challenge.
+     * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/challenges/operation/get_challenge_solves}.
+     *
+     * @param id The ID of the challenge to fetch solves for.
+     * @returns The challenge's solves.
+     */
+    getSolves(id: number): Promise<Solve[]>;
+};
+
+type BaseScoreboardEntry = {
+    pos: number;
+    account_id: number;
+    account_url: string;
+    oauth_id: null;
+    name: string;
+    score: number;
+    bracket_id: number | null;
+    bracket_name: string | null;
+};
+type ScoreboardUserEntry = BaseScoreboardEntry & {
+    account_type: "user";
+};
+type ScoreboardTeamEntry = BaseScoreboardEntry & {
+    account_type: "team";
+    members: {
+        id: number;
+        oauth_id: null;
+        name: string;
+        score: number;
+        bracket_id: null;
+        bracket_name: null;
+    }[];
+};
+type ScoreboardEntry = ScoreboardUserEntry | ScoreboardTeamEntry;
+interface ScoreboardDetails {
+    id: number;
+    account_url: string;
+    name: string;
+    score: number;
+    bracket_id: null;
+    bracket_name: null;
+    solves: {
+        challenge_id: number;
+        account_id: number;
+        team_id: number | null;
+        user_id: number;
+        value: number;
+        date: string;
+    }[];
+}
+
+declare function createScoreboardMethods(client: CTFdClient): {
+    /**
+     * Fetches the list of scoreboard entries.
+     * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/scoreboard/operation/get_scoreboard_list}
+     *
+     * @returns The scoreboard, as a `ScoreboardEntry[]`.
+     */
+    get(): Promise<ScoreboardEntry[]>;
+    /**
+     * Fetches details for the top `n` teams on the scoreboard.
+     * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/scoreboard/operation/get_scoreboard_detail}
+     *
+     * @param count The number of teams to fetch.
+     * @returns The scoreboard details.
+     */
+    getTop(count: number): Promise<ScoreboardDetails[]>;
+};
+
+interface User {
+    id: number;
+    oauth_id: number | null;
+    name: string;
+    email?: string;
+    website: string | null;
+    affiliation: string | null;
+    country: string | null;
+    bracket_id: number | null;
+    language: string | null;
+    team_id: number | null;
+    created: string;
+    fields: [];
+}
+interface Award {
+    description: string | null;
+    date: string;
+    id: number;
+    category: string;
+    user_id: number;
+    team_id: null;
+    name: string;
+    user: number;
+    team: null;
+    value: number;
+    icon: string;
+}
+
+interface UserSolve {
+    user: {
+        name: string;
+        id: number;
+    };
+    date: string;
+    challenge_id: number;
+    challenge: {
+        value: number;
+        name: string;
+        id: number;
+        category: string;
+    };
+    team: number | null;
+    id: number;
+    type: "correct";
+}
+declare function createUsersMethods(client: CTFdClient): {
+    me: {
+        /**
+         * Retrieves the currently logged-in user.
+         * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/users/operation/get_user_private}
+         * @returns The logged-in user.
+         */
+        get(): Promise<User>;
+        /**
+         * Retrieves solves for the currently logged-in user.
+         * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/users/operation/get_user_private_solves}
+         *
+         * @returns The logged-in user's solves.
+         */
+        getSolves(): Promise<UserSolve[]>;
+        /**
+         * Retrieves awards for the currently logged-in user.
+         * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/users/operation/get_user_private_awards}
+         *
+         * @returns The logged-in user's awards.
+         */
+        getAwards(): Promise<Award[]>;
+    };
+    /**
+     * Retrieves a user by ID.
+     * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/users/operation/get_user_public}
+     *
+     * @param id The ID of the user to retrieve.
+     * @returns The fetched user.
+     */
+    getById(id: number): Promise<User>;
+    /**
+     * Retrieves solves for a given user.
+     * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/users/operation/get_user_public_solves}
+     *
+     * @param id The ID of the user to retrieve solves for.
+     * @returns The user's solves.
+     */
+    getSolves(id: number): Promise<UserSolve[]>;
+    /**
+     * Retrieves awards for a given user.
+     * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/users/operation/get_user_public_awards}
+     *
+     * @param id The ID of the user to retrieve awards for.
+     * @returns The user's awards.
+     */
+    getAwards(id: number): Promise<Award[]>;
+};
+
+type ClientOptions = {
+    url: string;
+    username: string;
+    password: string;
+};
+declare class CTFdClient {
+    readonly url: string;
+    private readonly username;
+    private readonly password;
+    private cachedSession;
+    private cachedNonce;
+    private sessionExpiry;
+    readonly challenges: ReturnType<typeof createChallengesMethods>;
+    readonly scoreboard: ReturnType<typeof createScoreboardMethods>;
+    readonly users: ReturnType<typeof createUsersMethods>;
+    constructor(options: ClientOptions);
+    callApi<T>(endpoint: string): Promise<T>;
+    getAuthedSessionNonce(): Promise<{
+        session: string;
+        nonce: string;
+    }>;
 }
 
-export { CTFdClient, type ChallengeData, type ChallengeDetails, type ChallengeType, type ScoreboardEntry };
+export { type Award, CTFdClient, type Challenge, type ChallengeDetails, type ChallengeType, type ScoreboardEntry, type Solve, type User };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b01lers/ctfd-api",
-  "version": "1.2.1",
+  "version": "2.0.0",
   "description": "An API client for CTFd.",
   "main": "dist/index.js",
   "types": "dist/types.d.ts",

package/src/client.ts

@@ -1,10 +1,8 @@
+import { createChallengesMethods } from './endpoints/challenges';
+import { createScoreboardMethods } from './endpoints/scoreboard';
+import { createUsersMethods } from './endpoints/users';
 import { extractNonce } from './util';
-import type {
-    ChallengeDetailsResponse,
-    ChallengesResponse,
-    FlagSubmissionResponse,
-    ScoreboardResponse
-} from './types';
+import type { APISuccess } from './types/api';
 
 
 type ClientOptions = {
@@ -14,7 +12,7 @@ type ClientOptions = {
 }
 
 export class CTFdClient {
-    private readonly url: string;
+    public readonly url: string;
     private readonly username: string;
     private readonly password: string;
 
@@ -22,62 +20,36 @@ export class CTFdClient {
     private cachedNonce: string | null = null;
     private sessionExpiry = new Date();
 
+    public readonly challenges: ReturnType<typeof createChallengesMethods>;
+    public readonly scoreboard: ReturnType<typeof createScoreboardMethods>;
+    public readonly users: ReturnType<typeof createUsersMethods>;
+
     constructor(options: ClientOptions) {
         this.url = options.url.endsWith('/') ? options.url.slice(0, -1) : options.url;
         this.username = options.username;
         this.password = options.password;
-    }
-
-    public async submitFlag(id: number, flag: string) {
-        const { session, nonce } = await this.getAuthedSessionNonce();
 
-        const res = await (await fetch(`${this.url}/api/v1/challenges/attempt`, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                'Csrf-Token': nonce,
-                cookie: session,
-            },
-            body: JSON.stringify({ challenge_id: id, submission: flag }),
-        })).json() as FlagSubmissionResponse;
-
-        return res.data;
-    }
-
-    public async getChallenges() {
-        const { session } = await this.getAuthedSessionNonce();
-
-        const res = await (await fetch(`${this.url}/api/v1/challenges`, {
-            headers: { cookie: session }
-        })).json() as ChallengesResponse;
-
-        return res.data;
-    }
-
-    public async getChallengeDetails(id: number) {
-        const { session } = await this.getAuthedSessionNonce();
-
-        const res = await (await fetch(`${this.url}/api/v1/challenges/${id}`, {
-            headers: { cookie: session }
-        })).json() as ChallengeDetailsResponse;
-
-        return res.data;
+        this.challenges = createChallengesMethods(this);
+        this.scoreboard = createScoreboardMethods(this);
+        this.users = createUsersMethods(this);
     }
 
-    public async getScoreboard() {
+    public async callApi<T>(endpoint: string) {
         const { session, nonce } = await this.getAuthedSessionNonce();
 
-        const res = await (await fetch(`${this.url}/api/v1/scoreboard`, {
+        // TODO: error handling?
+        const res = await (await fetch(`${this.url}/api/v1${endpoint}`, {
             headers: {
                 'Csrf-Token': nonce,
                 cookie: session,
             },
-        })).json() as ScoreboardResponse;
+        })).json() as APISuccess<T>;
 
         return res.data;
     }
 
-    private async getAuthedSessionNonce() {
+    // TODO
+    public async getAuthedSessionNonce() {
         // If we have a cached, non-expired session, use it
         if (new Date() < this.sessionExpiry && this.cachedSession && this.cachedNonce)
             return { session: this.cachedSession, nonce: this.cachedNonce };
@@ -87,17 +59,17 @@ export class CTFdClient {
         const [session] = res.headers.getSetCookie()[0].split('; ');
         const nonce = extractNonce(await res.text());
 
-        const formData = new FormData();
-        formData.append('name', this.username);
-        formData.append('password', this.password);
-        formData.append('_submit', 'Submit');
-        formData.append('nonce', nonce);
+        const params = new URLSearchParams();
+        params.append('name', this.username);
+        params.append('password', this.password);
+        params.append('_submit', 'Submit');
+        params.append('nonce', nonce);
 
         const loginRes = await fetch(`${this.url}/login`, {
             method: 'POST',
             headers: { cookie: session },
             redirect: 'manual',
-            body: formData,
+            body: params,
         });
 
         const [authedSession, expiresGmt] = loginRes.headers.getSetCookie()[0].split('; ');

package/src/endpoints/challenges.ts

@@ -0,0 +1,81 @@
+import type { CTFdClient } from '../client';
+import type { Challenge, ChallengeDetails, Solve } from '../types/challenges';
+import type { APISuccess } from '../types/api';
+
+
+export type FlagSubmissionResponse = APISuccess<{
+    status: 'incorrect',
+    message: 'Incorrect'
+} | {
+    status: 'correct',
+    message: 'Correct'
+} | {
+    status: 'already_solved',
+    message: 'You already solved this'
+} | {
+    status: 'paused',
+    message: `${string} is paused`
+} | {
+    status: 'ratelimited',
+    message: 'You\'re submitting flags too fast. Slow down.'
+}>
+
+export function createChallengesMethods(client: CTFdClient) {
+    return {
+        /**
+         * Attempts to submit a flag for the given challenge.
+         * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/challenges/operation/post_challenge_attempt}
+         *
+         * @param id The ID of the challenge to submit a flag for.
+         * @param flag The flag to submit.
+         * @returns The status of the flag submission.
+         */
+        async submitFlag(id: number, flag: string) {
+            const { session, nonce } = await client.getAuthedSessionNonce();
+
+            const res = await (await fetch(`${client.url}/api/v1/challenges/attempt`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Csrf-Token': nonce,
+                    cookie: session,
+                },
+                body: JSON.stringify({ challenge_id: id, submission: flag }),
+            })).json() as FlagSubmissionResponse;
+
+            return res.data;
+        },
+
+        /**
+         * Fetches the list of all challenges.
+         * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/challenges/operation/get_challenge_list}
+         *
+         * @returns The list of challenges, as a `Challenge[]`.
+         */
+        async get() {
+            return client.callApi<Challenge[]>('/challenges');
+        },
+
+        /**
+         * Fetches details for the given challenge.
+         * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/challenges/operation/get_challenge}.
+         *
+         * @param id The ID of the challenge to fetch.
+         * @returns The challenge details.
+         */
+        async getDetails(id: number) {
+            return client.callApi<ChallengeDetails>(`/challenges/${id}`);
+        },
+
+        /**
+         * Fetches solves for the given challenge.
+         * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/challenges/operation/get_challenge_solves}.
+         *
+         * @param id The ID of the challenge to fetch solves for.
+         * @returns The challenge's solves.
+         */
+        async getSolves(id: number) {
+            return client.callApi<Solve[]>(`/challenges/${id}/solves`);
+        }
+    }
+}

package/src/endpoints/scoreboard.ts

@@ -0,0 +1,28 @@
+import type { CTFdClient } from '../client';
+import type { ScoreboardDetails, ScoreboardEntry } from '../types/scoreboard';
+
+
+export function createScoreboardMethods(client: CTFdClient) {
+    return {
+        /**
+         * Fetches the list of scoreboard entries.
+         * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/scoreboard/operation/get_scoreboard_list}
+         *
+         * @returns The scoreboard, as a `ScoreboardEntry[]`.
+         */
+        async get() {
+            return client.callApi<ScoreboardEntry[]>('/scoreboard');
+        },
+
+        /**
+         * Fetches details for the top `n` teams on the scoreboard.
+         * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/scoreboard/operation/get_scoreboard_detail}
+         *
+         * @param count The number of teams to fetch.
+         * @returns The scoreboard details.
+         */
+        async getTop(count: number) {
+            return client.callApi<ScoreboardDetails[]>(`/scoreboard/top/${count}`);
+        }
+    }
+}

package/src/endpoints/users.ts

@@ -0,0 +1,89 @@
+import type { CTFdClient } from '../client';
+import type { Award, User } from '../types/users';
+
+
+interface UserSolve {
+    user: {
+        name: string,
+        id: number,
+    },
+    date: string, // ISO
+    challenge_id: number,
+    challenge: {
+        value: number,
+        name: string,
+        id: number,
+        category: string,
+    },
+    team: number | null,
+    id: number,
+    type: "correct" // TODO?
+}
+
+export function createUsersMethods(client: CTFdClient) {
+    return {
+        me: {
+            /**
+             * Retrieves the currently logged-in user.
+             * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/users/operation/get_user_private}
+             * @returns The logged-in user.
+             */
+            async get() {
+                return client.callApi<User>('/users/me');
+            },
+
+            /**
+             * Retrieves solves for the currently logged-in user.
+             * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/users/operation/get_user_private_solves}
+             *
+             * @returns The logged-in user's solves.
+             */
+            async getSolves() {
+                return client.callApi<UserSolve[]>('/users/me/solves');
+            },
+
+            /**
+             * Retrieves awards for the currently logged-in user.
+             * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/users/operation/get_user_private_awards}
+             *
+             * @returns The logged-in user's awards.
+             */
+            async getAwards() {
+                return client.callApi<Award[]>('/users/me/awards');
+            }
+        },
+
+        /**
+         * Retrieves a user by ID.
+         * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/users/operation/get_user_public}
+         *
+         * @param id The ID of the user to retrieve.
+         * @returns The fetched user.
+         */
+        async getById(id: number) {
+            return client.callApi<User>(`/users/${id}`);
+        },
+
+        /**
+         * Retrieves solves for a given user.
+         * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/users/operation/get_user_public_solves}
+         *
+         * @param id The ID of the user to retrieve solves for.
+         * @returns The user's solves.
+         */
+        async getSolves(id: number) {
+            return client.callApi<UserSolve[]>(`/users/${id}/solves`);
+        },
+
+        /**
+         * Retrieves awards for a given user.
+         * Ref: {@Link https://docs.ctfd.io/docs/api/redoc#tag/users/operation/get_user_public_awards}
+         *
+         * @param id The ID of the user to retrieve awards for.
+         * @returns The user's awards.
+         */
+        async getAwards(id: number) {
+            return client.callApi<Award[]>(`/users/${id}/awards`);
+        }
+    }
+}

package/src/index.ts

@@ -1,2 +1,5 @@
 export { CTFdClient } from './client';
-export type { ScoreboardEntry, ChallengeType, ChallengeData, ChallengeDetails } from './types';
+
+export type { ChallengeType, Challenge, ChallengeDetails, Solve } from './types/challenges'
+export type { ScoreboardEntry } from './types/scoreboard';
+export type { User, Award } from './types/users';

package/src/types/api.ts

@@ -0,0 +1,4 @@
+export type APISuccess<T> = {
+    success: true,
+    data: T
+}

package/src/{types.ts → types/challenges.ts}

@@ -1,43 +1,12 @@
-type APISuccess<T> = {
-    success: true,
-    data: T
-}
-
-export type ScoreboardResponse = APISuccess<ScoreboardEntry[]>
-
-type BaseScoreboardEntry = {
-    pos: number,
+export interface Solve {
     account_id: number,
     account_url: string,
-    oauth_id: null,
+    date: string,
     name: string,
-    score: number,
-    bracket_id: number | null,
-    bracket_name: string | null  // e.g. "Open Bracket"
 }
 
-type ScoreboardUserEntry = BaseScoreboardEntry & {
-    account_type: "user",
-}
-
-type ScoreboardTeamEntry = BaseScoreboardEntry & {
-    account_type: "team",
-    members: {
-        id: number,
-        oauth_id: null,
-        name: string,
-        score: number,
-        bracket_id: null,
-        bracket_name: null
-    }[]
-}
-
-export type ScoreboardEntry = ScoreboardUserEntry | ScoreboardTeamEntry;
-
-export type ChallengesResponse = APISuccess<ChallengeData[]>
-
 export type ChallengeType = 'standard' | 'multiple_choice' | 'code';
-export type ChallengeData = {
+export interface Challenge {
     id: number,
     type: ChallengeType,
     name: string,
@@ -50,8 +19,6 @@ export type ChallengeData = {
     value: number,
 }
 
-export type ChallengeDetailsResponse = APISuccess<ChallengeDetails>;
-
 type BaseChallengeDetails = {
     id: number,
     name: string,
@@ -90,20 +57,3 @@ type ProgrammingChallengeDetails = BaseChallengeDetails & {
 }
 
 export type ChallengeDetails = StandardChallengeDetails | ProgrammingChallengeDetails;
-
-export type FlagSubmissionResponse = APISuccess<{
-    status: 'incorrect',
-    message: 'Incorrect'
-} | {
-    status: 'correct',
-    message: 'Correct'
-} | {
-    status: 'already_solved',
-    message: 'You already solved this'
-} | {
-    status: 'paused',
-    message: `${string} is paused`
-} | {
-    status: 'ratelimited',
-    message: 'You\'re submitting flags too fast. Slow down.'
-}>

package/src/types/scoreboard.ts

@@ -0,0 +1,45 @@
+type BaseScoreboardEntry = {
+    pos: number,
+    account_id: number,
+    account_url: string,
+    oauth_id: null, // TODO
+    name: string,
+    score: number,
+    bracket_id: number | null,
+    bracket_name: string | null  // e.g. "Open Bracket"
+}
+
+type ScoreboardUserEntry = BaseScoreboardEntry & {
+    account_type: "user",
+}
+
+type ScoreboardTeamEntry = BaseScoreboardEntry & {
+    account_type: "team",
+    members: {
+        id: number,
+        oauth_id: null,
+        name: string,
+        score: number,
+        bracket_id: null,
+        bracket_name: null
+    }[]
+}
+
+export type ScoreboardEntry = ScoreboardUserEntry | ScoreboardTeamEntry;
+
+export interface ScoreboardDetails {
+    id: number,
+    account_url: string,
+    name: string,
+    score: number,
+    bracket_id: null, // TODO
+    bracket_name: null,
+    solves: {
+        challenge_id: number,
+        account_id: number,
+        team_id: number | null,
+        user_id: number,
+        value: number,
+        date: string // ISO
+    }[]
+}

package/src/types/users.ts

@@ -0,0 +1,36 @@
+export interface User {
+    id: number,
+    oauth_id: number | null,
+    name: string,
+    // password: string,
+    email?: string,
+    // type: string,
+    // secret: string,
+    website: string | null,
+    affiliation: string | null,
+    country: string | null,
+    bracket_id: number | null,
+    // hidden: boolean,
+    // banned: boolean,
+    // verified: boolean,
+    language: string | null,
+    // change_password: boolean,
+    team_id: number | null,
+    created: string, // ISO
+
+    fields: [], // TODO
+}
+
+export interface Award {
+    description: string | null,
+    date: string,
+    id: number,
+    category: string,
+    user_id: number,
+    team_id: null, // TODO
+    name: string,
+    user: number,
+    team: null, // TODO
+    value: number,
+    icon: string,
+}

package/tests/demo.ts

@@ -8,16 +8,25 @@ import { CTFdClient } from '../src/client';
         password: 'password',
     });
 
-    const challs = await client.getChallenges();
+    const challs = await client.challenges.get();
     console.log(challs);
 
-    const scoreboard = await client.getScoreboard();
+    const scoreboard = await client.scoreboard.get();
     console.log(scoreboard.slice(0, 5));
 
     const chall = challs.find((c) => c.name === 'The Lost Park')!;
-    const details = await client.getChallengeDetails(chall.id);
+    const details = await client.challenges.getDetails(chall.id);
     console.log(details);
 
-    const res = await client.submitFlag(chall.id, 'Major Mark Park');
+    const res = await client.challenges.submitFlag(chall.id, 'Major Mark Park');
     console.log(res);
+
+    const solves = await client.challenges.getSolves(chall.id);
+    console.log(solves);
+
+    const user = await client.users.me.get();
+    console.log(user);
+
+    // This should be equivalent to the above
+    console.log(await client.users.getById(user.id));
 })()

package/tests/rate-limit.ts

@@ -8,12 +8,12 @@ import { CTFdClient } from '../src/client';
         password: 'password',
     });
 
-    const chall = (await client.getChallenges()).find((c) => c.name === 'Too Many Puppers')!;
+    const chall = (await client.challenges.get()).find((c) => c.name === 'The Lost Park')!;
 
-    const res = await client.submitFlag(chall.id, 'test');
+    const res = await client.challenges.submitFlag(chall.id, 'test');
     console.log(res);
 
     for (let i = 0; i < 20; i++) {
-        console.log(await client.submitFlag(chall.id, 'test'));
+        console.log(await client.challenges.submitFlag(chall.id, 'test'));
     }
 })()