feat(modules): added gradereport_user_get_grade_items function

src/index.ts

@@ -7,6 +7,7 @@
 import { Client, ClientOptions, HttpOptions } from "./client";
 import AuthModule from "./modules/auth";
 import CoreModule from "./modules/core";
+import GradeReportModule from "./modules/gradereport";
 
 /**
  * The main Joodle client class. Used to make API calls to Moodle's Web Services
@@ -18,6 +19,8 @@ export class Joodle extends Client {
 
   public readonly core: CoreModule;
 
+  public readonly gradereport: GradeReportModule;
+
   /**
    * Initializes a new Joodle client instance for making API calls to Moodle's
    * Web Services API.
@@ -30,5 +33,6 @@ export class Joodle extends Client {
 
     this.auth = new AuthModule(this);
     this.core = new CoreModule(this);
+    this.gradereport = new GradeReportModule(this);
   }
 }

src/modules/gradereport/index.ts

@@ -0,0 +1,21 @@
+/**
+ * @vuepress
+ * ---
+ * title: gradereport
+ * ---
+ */
+import Module from "../../module";
+import UserModule from "./user";
+import { Client } from "../../client";
+
+/**
+ * Functions for grade-related operations.
+ */
+export default class CoreModule extends Module {
+  public readonly user: UserModule;
+
+  public constructor(client: Client) {
+    super(client);
+    this.user = new UserModule(client);
+  }
+}

src/modules/gradereport/user/get-grade-items.ts

@@ -0,0 +1,224 @@
+import { FunctionResponse } from "../../../functions";
+import { Warning } from "../../shared";
+
+export interface Grade {
+  /**
+   * The ID of the grade.
+   */
+  id: number;
+
+  /**
+   * The name of the grade.
+   */
+  itemname: string;
+
+  /**
+   * The type of grade.
+   */
+  itemtype: string;
+
+  /**
+   * The grade's module.
+   */
+  itemmodule: string;
+
+  /**
+   * The ID of the grade's category.
+   */
+  categoryid: number;
+
+  /**
+   * The ID of the grade outcome.
+   */
+  outcomeid: number;
+
+  /**
+   * The ID of the grade scale.
+   */
+  scaleid: number;
+
+  /**
+   * Whether the grade is locked
+   * for the user (true) or not (false).
+   */
+  locked?: boolean;
+
+  /**
+   * The ID of the course module.
+   */
+  cmid?: number;
+
+  /**
+   * The raw weight of the grade.
+   */
+  weightraw?: number;
+
+  /**
+   * The formatted weight of the grade.
+   */
+  weightformatted?: string;
+
+  /**
+   * The status of the grade.
+   */
+  status?: string;
+
+  /**
+   * The raw value of the grade.
+   */
+  graderaw?: number;
+
+  /**
+   * The UNIX timestamp of the time
+   * when the grade was submitted.
+   */
+  gradedatesubmitted?: number;
+
+  /**
+   * The UNIX timestamp of the time
+   * when the grade was graded.
+   */
+  gradedategraded?: number;
+
+  /**
+   * Whether the grade is hidden by
+   * date (true) or not (false).
+   */
+  gradehiddenbydate?: boolean;
+
+  /**
+   * Whether the grade needs an
+   * update (true) or not (false).
+   */
+  gradeneedsupdate?: boolean;
+
+  /**
+   * Whether the grade is hidden
+   * (true) or visible (false).
+   */
+  gradeishidden?: boolean;
+
+  /**
+   * Whether the grade is locked
+   * (true) or unlocked (false).
+   */
+  gradeislocked?: boolean;
+
+  /**
+   * Whether the grade is overriden
+   * (true) or not (false).
+   */
+  gradeisoverriden?: boolean;
+
+  /**
+   * The formatted string of the
+   * grade.
+   */
+  gradeformatted?: string;
+
+  /**
+   * The minimum value for the
+   * grade.
+   */
+  grademin?: number;
+
+  /**
+   * The maximum value for the
+   * grade.
+   */
+  grademax?: number;
+
+  /**
+   * The formatted string of the
+   * grade's range.
+   */
+  rangeformatted?: string;
+
+  /**
+   * The formatted string of the
+   * grade as a percentage.
+   */
+  percentageformatted?: string;
+
+  /**
+   * The formatted string of the
+   * grade as a letter.
+   */
+  lettergradeformatted?: string;
+
+  /**
+   * The rank of this grade within
+   * the course.
+   */
+  rank?: number;
+
+  /**
+   * The number of users in this
+   * course.
+   */
+  numusers?: number;
+
+  /**
+   * The formatted string of the
+   * average grade in this course.
+   */
+  averageformatted?: string;
+
+  /**
+   * Any feedback attached to this
+   * grade.
+   */
+  feedback?: string;
+
+  /**
+   * The grade's feedback format code.
+   *
+   *
+   * `0` - Moodle
+   * `1` - HTML
+   * `2` - plain text
+   * `4` - Markdown
+   */
+  feedbackformat?: number;
+}
+
+export interface UserGrades {
+  /**
+   * The ID of the course that the
+   * grades belong to.
+   */
+  courseid: number;
+
+  /**
+   * The ID of the user that the
+   * grades belong to.
+   */
+  userid: number;
+
+  /**
+   * The full name of the user referenced
+   * by userid.
+   */
+  userfullname: string;
+
+  /**
+   * The table's max depth (needed for
+   * printing it).
+   */
+  maxdepth: number;
+
+  /**
+   * The user's grades.
+   */
+  gradeitems: Grade[];
+}
+
+export interface GetGradeItemsResponse extends FunctionResponse {
+  /**
+   * The user grades obtained from
+   * the request.
+   */
+  usergrades: UserGrades[];
+
+  warnings: Warning[];
+}

src/modules/gradereport/user/index.ts

@@ -0,0 +1,34 @@
+/**
+ * @vuepress
+ * ---
+ * title: gradereport.user
+ * ---
+ */
+import Module from "../../../module";
+import { GetGradeItemsResponse } from "./get-grade-items";
+
+/**
+ * Functions for user grades-related actions.
+ */
+export default class UserModule extends Module {
+  /**
+   * Returns the complete list of grade items for users in a course.
+   *
+   * @param course The ID of the course to obtain grade items for.
+   * @param user The ID of the user to obtain grade items for. Leave
+   * undefined to load the grade items for all course members.
+   * @param group The ID of the group to obtain grade items for. Leave
+   * undefined to load the grade items for all course members.
+   */
+  public async getGradeItems(
+    course: number,
+    user?: number,
+    group?: number
+  ): Promise<GetGradeItemsResponse> {
+    return (await this.get("gradereport_user_get_grade_items", {
+      courseid: course,
+      userid: user === undefined ? 0 : user,
+      groupid: group === undefined ? 0 : group,
+    })) as GetGradeItemsResponse;
+  }
+}

tests/modules/gradereport/user.test.ts

@@ -0,0 +1,80 @@
+import nock from "nock";
+import { Joodle } from "../../../src";
+
+describe("The gradereport.user module", () => {
+  const baseURL = "https://moodle.example.com/";
+  const token = "abc123";
+  let joodle: Joodle;
+
+  beforeAll(() => {
+    joodle = new Joodle({
+      baseURL,
+      token,
+    });
+
+    nock(baseURL)
+      .get(
+        `/webservice/rest/server.php?wsfunction=gradereport_user_get_grade_items&courseid=123&userid=1&groupid=0&wstoken=${token}&moodlewsrestformat=json`
+      )
+      .reply(200, {
+        sitename: "New Site",
+        username: "test",
+        firstname: "Test",
+        lastname: "User",
+        fullname: "Test User",
+        lang: "en",
+        userid: 2,
+        siteurl: baseURL,
+        userpictureurl: `${baseURL}/picture.png`,
+        functions: [
+          {
+            name: "core_webservice_get_site_info",
+            version: "x.y.z",
+          },
+        ],
+        downloadfiles: 1,
+        uploadfiles: 1,
+        release: "a.b.c",
+        version: "x.y.z",
+        mobilecssurl: "",
+        advancedfeatures: [],
+        usercanmanageownfiles: true,
+        userquota: 0,
+        usermaxuploadfilesize: -1,
+        userhomepage: 1,
+        userprivateaccesskey: "abc123",
+        siteid: 1,
+        sitecalendartype: "gregorian",
+        usercalendartype: "gregorian",
+        userissiteadmin: true,
+        theme: "Boost",
+      });
+
+    nock(baseURL)
+      .get(
+        `/webservice/rest/server.php?wsfunction=gradereport_user_get_grade_items&courseid=123&userid=1&groupid=0&wstoken=xyz789&moodlewsrestformat=json`
+      )
+      .reply(200, {
+        exception: "webservice_access_exception",
+        errorcode: "accessexception",
+        message:
+          "Access control exception (Access to the function gradereport_user_get_grade_items() is not allowed.",
+        debuginfo:
+          "Access to the function gradereport_user_get_grade_items() is not allowed.",
+      });
+  });
+
+  describe("the getGradeItems() function", () => {
+    it("should handle successful responses", () => {
+      return expect(
+        joodle.gradereport.user.getGradeItems(123, 1, undefined)
+      ).resolves.toBeDefined();
+    });
+
+    it("should handle erroneous responses", () => {
+      return expect(
+        joodle.gradereport.user.getGradeItems(123, 1, undefined)
+      ).rejects.toBeDefined();
+    });
+  });
+});