politeshop 0.0.1

package/README.md

@@ -0,0 +1,33 @@
+# POLITEShop library
+
+JS/TS library for interacting with reverse-engineered [POLITEMall](https://politemall.polite.edu.sg/) APIs (`*.polite.edu.sg` and `*.api.brightspace.com`). Made for the [POLITEShop browser extension](https://github.com/haziq21/politeshop).
+
+```typescript
+import { POLITEShop } from "politeshop";
+
+const ps = new POLITEShop({
+  d2lSessionVal: "sNtnzd...",
+  d2lSecureSessionVal: "eqoLoG...",
+  domain: "nplms",
+});
+
+// { id: '490586', name: 'HAZIQ DANISH BIN HAIRIL RIZAL' }
+const user = await ps.getUser();
+
+// [{ id: '803172', name: 'DATA STRUCTURES & ALGORITHMS (2_DSA_011791)', code: '25S2-2_DSA_011791' }, ...]
+const modules = await ps.getModules();
+
+const content = await ps.getModuleContent(modules[0].id);
+```
+
+## Terminology
+
+There are some differences in terminology between Singapore's Polytechnics / ITE and the underlying APIs. This library follows Polytechnic / ITE terminology.
+
+| POLITEShop                | Underlying APIs              | Definition                                                   |
+| ------------------------- | ---------------------------- | ------------------------------------------------------------ |
+| Course                    | Course                       | A course of study (e.g. Information Technology). A student can only be in one course. |
+| Module                    | Enrollment / Course offering | A timetabled subject studied, e.g. Data Structures & Algorithms. |
+| Activity                  | Activity / Topic             | An individual POLITEMall page containing text, media embeds, submission dropboxes, interactive activities, etc. |
+| Top-level activity folder | Module                       | A "root" group of POLITEMall content. By definition, these are not nested. |
+| Activity folder           | Unit                         | A group of POLITEMall content. These can be nested.          |

package/dist/clients/brightspace.d.ts

@@ -0,0 +1,75 @@
+import { type SirenEntity } from "../schema/siren";
+/**
+ * Client for `*.api.brightspace.com`.
+ */
+export declare class Brightspace {
+    #private;
+    userId: string;
+    /** The Brightspace tenant ID (a UUID). */
+    tenantId: string;
+    /** The expiration date of the current `d2lFetchToken`. */
+    tokenExpiry: Date;
+    constructor(config: {
+        /** Short-lived JWT for Brightspace API authentication. */
+        d2lFetchToken: string;
+    });
+    /**
+     * GET /{moduleId}/activity/{topicId}?filterOnDatesAndDepth=0
+     *
+     * Fetches a Siren entity representing a single activity (topic) in a module.
+     * Used for document-embed activities to discover the preview PDF URL.
+     */
+    getActivity({ moduleId, topicId, }: {
+        moduleId: string;
+        topicId: string | number;
+    }): Promise<SirenEntity>;
+    /**
+     * GET /old/activities/{orgId}_2000_{dropboxId}/usages/{moduleId}/users/{userId}
+     *
+     * Fetches submission information for a dropbox that is **closed** (past its
+     * availability end date). The POLITE API returns HTTP 403 for closed
+     * dropboxes, so this endpoint is used as a fallback.
+     *
+     * The constant `2000` in the path is the tool ID for dropbox activities.
+     */
+    getClosedDropboxSubmissions({ orgId, dropboxId, moduleId, }: {
+        orgId: string;
+        dropboxId: string;
+        moduleId: string;
+    }): Promise<SirenEntity>;
+    /**
+     * Fetch a submission entity from an **absolute** Brightspace URL.
+     *
+     * The href values surfaced by {@link getClosedDropboxSubmissions} point to
+     * the `assignments.api.brightspace.com` subdomain (or similar). Pass them
+     * here directly without modification.
+     */
+    getSubmissionDetails({ href }: {
+        href: string;
+    }): Promise<SirenEntity>;
+    /**
+     * GET /topics/{moduleId}/{activityId}
+     *
+     * Fetches thumbnail metadata for a ContentService topic (typically a video).
+     * The returned entity contains a `thumbnail` sub-entity whose `properties.src`
+     * is a time-limited thumbnail image URL.
+     */
+    getTopicThumbnail({ moduleId, activityId, }: {
+        moduleId: string;
+        activityId: string;
+    }): Promise<SirenEntity>;
+    /**
+     * GET /topics/{moduleId}/{activityId}/media
+     *
+     * Fetches media metadata for a ContentService topic (typically a video).
+     * The returned entity's `properties.src` is a time-limited URL for the
+     * video file itself.
+     */
+    getTopicMedia({ moduleId, activityId, }: {
+        moduleId: string;
+        activityId: string;
+    }): Promise<SirenEntity>;
+    /** Abort all in-flight requests made by this client. */
+    abort(): void;
+}
+//# sourceMappingURL=brightspace.d.ts.map

package/dist/clients/brightspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brightspace.d.ts","sourceRoot":"","sources":["../../clients/brightspace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAIhE;;GAEG;AACH,qBAAa,WAAW;;IACtB,MAAM,EAAE,MAAM,CAAC;IAEf,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IAEjB,0DAA0D;IAC1D,WAAW,EAAE,IAAI,CAAC;gBAKN,MAAM,EAAE;QAClB,0DAA0D;QAC1D,aAAa,EAAE,MAAM,CAAC;KACvB;IAiBD;;;;;OAKG;IACG,WAAW,CAAC,EAChB,QAAQ,EACR,OAAO,GACR,EAAE;QACD,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;KAC1B,GAAG,OAAO,CAAC,WAAW,CAAC;IASxB;;;;;;;;OAQG;IACG,2BAA2B,CAAC,EAChC,KAAK,EACL,SAAS,EACT,QAAQ,GACT,EAAE;QACD,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO,CAAC,WAAW,CAAC;IAOxB;;;;;;OAMG;IACG,oBAAoB,CAAC,EAAE,IAAI,EAAE,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IAM5E;;;;;;OAMG;IACG,iBAAiB,CAAC,EACtB,QAAQ,EACR,UAAU,GACX,EAAE;QACD,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,WAAW,CAAC;IAOxB;;;;;;OAMG;IACG,aAAa,CAAC,EAClB,QAAQ,EACR,UAAU,GACX,EAAE;QACD,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,WAAW,CAAC;IASxB,wDAAwD;IACxD,KAAK,IAAI,IAAI;CAsCd"}

package/dist/clients/brightspace.js

@@ -0,0 +1,104 @@
+import { sirenEntity } from "../schema/siren";
+import { decodeJwt } from "jose";
+import z from "zod";
+/**
+ * Client for `*.api.brightspace.com`.
+ */
+export class Brightspace {
+    userId;
+    /** The Brightspace tenant ID (a UUID). */
+    tenantId;
+    /** The expiration date of the current `d2lFetchToken`. */
+    tokenExpiry;
+    #d2lFetchToken;
+    #abortController = new AbortController();
+    constructor(config) {
+        this.#d2lFetchToken = config.d2lFetchToken;
+        const { sub, exp, tenantid } = z
+            .object({
+            tenantid: z.string(),
+            sub: z.string(),
+            exp: z.date({ coerce: true }),
+        })
+            .parse(decodeJwt(this.#d2lFetchToken));
+        this.userId = sub;
+        this.tokenExpiry = exp;
+        this.tenantId = tenantid;
+    }
+    // ── Sequences API (sequences.api.brightspace.com) ────────────────────────────
+    /**
+     * GET /{moduleId}/activity/{topicId}?filterOnDatesAndDepth=0
+     *
+     * Fetches a Siren entity representing a single activity (topic) in a module.
+     * Used for document-embed activities to discover the preview PDF URL.
+     */
+    async getActivity({ moduleId, topicId, }) {
+        return this.#fetchSiren(`/${moduleId}/activity/${topicId}?filterOnDatesAndDepth=0`, "sequences");
+    }
+    // ── Activities API (activities.api.brightspace.com) ──────────────────────────
+    /**
+     * GET /old/activities/{orgId}_2000_{dropboxId}/usages/{moduleId}/users/{userId}
+     *
+     * Fetches submission information for a dropbox that is **closed** (past its
+     * availability end date). The POLITE API returns HTTP 403 for closed
+     * dropboxes, so this endpoint is used as a fallback.
+     *
+     * The constant `2000` in the path is the tool ID for dropbox activities.
+     */
+    async getClosedDropboxSubmissions({ orgId, dropboxId, moduleId, }) {
+        return this.#fetchSiren(`/old/activities/${orgId}_2000_${dropboxId}/usages/${moduleId}/users/${this.userId}`, "activities");
+    }
+    /**
+     * Fetch a submission entity from an **absolute** Brightspace URL.
+     *
+     * The href values surfaced by {@link getClosedDropboxSubmissions} point to
+     * the `assignments.api.brightspace.com` subdomain (or similar). Pass them
+     * here directly without modification.
+     */
+    async getSubmissionDetails({ href }) {
+        return this.#fetchSiren(href);
+    }
+    // ── Content Service API (content-service.api.brightspace.com) ────────────────
+    /**
+     * GET /topics/{moduleId}/{activityId}
+     *
+     * Fetches thumbnail metadata for a ContentService topic (typically a video).
+     * The returned entity contains a `thumbnail` sub-entity whose `properties.src`
+     * is a time-limited thumbnail image URL.
+     */
+    async getTopicThumbnail({ moduleId, activityId, }) {
+        return this.#fetchSiren(`/topics/${moduleId}/${activityId}`, "content-service");
+    }
+    /**
+     * GET /topics/{moduleId}/{activityId}/media
+     *
+     * Fetches media metadata for a ContentService topic (typically a video).
+     * The returned entity's `properties.src` is a time-limited URL for the
+     * video file itself.
+     */
+    async getTopicMedia({ moduleId, activityId, }) {
+        return this.#fetchSiren(`/topics/${moduleId}/${activityId}/media`, "content-service");
+    }
+    // ── Lifecycle ─────────────────────────────────────────────────────────────────
+    /** Abort all in-flight requests made by this client. */
+    abort() {
+        this.#abortController.abort();
+    }
+    async #fetchSiren(pathOrURL, api) {
+        const url = api
+            ? new URL(pathOrURL, `https://${this.tenantId}.${api}.api.brightspace.com`)
+            : new URL(pathOrURL);
+        const res = await fetch(url, {
+            headers: { Authorization: `Bearer ${this.#d2lFetchToken}` },
+            signal: this.#abortController.signal,
+        });
+        if (!res.ok) {
+            const body = res.headers.get("content-type")?.includes("json")
+                ? JSON.stringify(await res.json())
+                : await res.text();
+            throw new Error(`Brightspace API error ${res.status} at ${url}: ${body}`);
+        }
+        return sirenEntity.parse(await res.json());
+    }
+}
+//# sourceMappingURL=brightspace.js.map

package/dist/clients/brightspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brightspace.js","sourceRoot":"","sources":["../../clients/brightspace.ts"],"names":[],"mappings":"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"}

package/dist/clients/polite.d.ts

@@ -0,0 +1,117 @@
+import * as schema from "../schema/polite";
+/**
+ * Low-level client for the POLITE API (`*.polite.edu.sg`).
+ *
+ * Handles authentication via D2L session cookies and exposes one method per
+ * API endpoint. All response bodies are validated with Zod schemas before
+ * being returned, so callers receive fully-typed data.
+ */
+export declare class POLITE {
+    #private;
+    constructor(config: {
+        /** `d2lSessionVal` cookie value. */
+        d2lSessionVal: string;
+        /** `d2lSecureSessionVal` cookie value. */
+        d2lSecureSessionVal: string;
+        /** Subdomain of the POLITEMall site (e.g. `"nplms"`). */
+        domain: string;
+    });
+    get baseURL(): string;
+    /**
+     * GET /d2l/lp/auth/oauth2/token
+     *
+     * Exchanges the current D2L session cookies for a short-lived Brightspace
+     * JWT that can be used with the `*.api.brightspace.com` APIs.
+     */
+    getNewFetchToken(): Promise<schema.BrightspaceToken>;
+    /**
+     * GET /d2l/api/lp/1.0/users/whoami
+     *
+     * Returns basic information about the currently authenticated user.
+     */
+    whoAmI(): Promise<schema.WhoAmIUser>;
+    /**
+     * GET /d2l/api/lp/1.46/organization/info
+     *
+     * Returns information about the organisation (institution).
+     */
+    getOrganizationInfo(): Promise<schema.Organization>;
+    /**
+     * GET /d2l/api/lp/1.46/enrollments/myenrollments/
+     *
+     * Returns one page of the authenticated user's org-unit enrollments.
+     * Pass `bookmark` to fetch subsequent pages.
+     */
+    getMyEnrollments({ bookmark }?: {
+        bookmark?: string;
+    }): Promise<schema.PagedResultSet<schema.MyOrgUnitInfo>>;
+    /**
+     * GET /d2l/api/lp/1.46/courses/parentorgunits?orgUnitIdsCSV=…
+     *
+     * Returns semester/department parent information for up to 25 course-offering
+     * org units at a time.
+     */
+    getParentOrgUnits({ orgUnitIdsCSV, }: {
+        orgUnitIdsCSV: string;
+    }): Promise<schema.CourseParent[]>;
+    /**
+     * GET /d2l/api/le/1.75/{moduleId}/content/toc
+     *
+     * Returns the table of contents for a module, including all nested folders
+     * (Modules) and topics (Activities).
+     */
+    getModuleTOC({ moduleId, }: {
+        moduleId: string;
+    }): Promise<schema.TableOfContents>;
+    /**
+     * Fetch a content URL as raw text (used for HTML-type activities).
+     *
+     * `urlOrPath` may be either an absolute URL or a path relative to
+     * `this.baseURL`.
+     */
+    getContentHTML({ urlOrPath }: {
+        urlOrPath: string;
+    }): Promise<string>;
+    /**
+     * Return the image URL for a module or organisation.
+     */
+    getImageURL(id: string, dim?: {
+        width: number;
+        height: number;
+    }): string;
+    /**
+     * GET /d2l/api/le/1.75/{moduleId}/dropbox/folders/
+     *
+     * Returns all submission dropbox folders in a module.
+     */
+    getDropboxFolders({ moduleId, }: {
+        moduleId: string;
+    }): Promise<schema.DropboxFolder[]>;
+    /**
+     * GET /d2l/api/le/1.75/{moduleId}/dropbox/folders/{dropboxId}/submissions/
+     *
+     * Returns the current user's submissions for a dropbox. Returns at most one
+     * `EntityDropbox` object (the user's own entry).
+     *
+     * > **Note:** This endpoint returns HTTP 403 for dropboxes whose availability
+     * > window has closed. In that case, use the Brightspace Activities API
+     * > instead (`Brightspace.getClosedDropboxSubmissions`).
+     */
+    getDropboxSubmissions({ moduleId, dropboxId, }: {
+        moduleId: string;
+        dropboxId: string;
+    }): Promise<schema.EntityDropbox[]>;
+    /**
+     * Fetch one page of quizzes from the given URL or path.
+     *
+     * For the first page, pass `/d2l/api/le/1.75/{moduleId}/quizzes/`.
+     * The `Next` field of the returned object is the URL for the next page
+     * (or `null` if there are no more pages).
+     */
+    getQuizzesPage({ urlOrPath, }: {
+        urlOrPath: string;
+    }): Promise<schema.ObjectListPage<schema.QuizReadData>>;
+    /** Abort all in-flight requests made by this client. */
+    abort(): void;
+}
+//# sourceMappingURL=polite.d.ts.map

package/dist/clients/polite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"polite.d.ts","sourceRoot":"","sources":["../../clients/polite.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAM3C;;;;;;GAMG;AACH,qBAAa,MAAM;;gBAML,MAAM,EAAE;QAClB,oCAAoC;QACpC,aAAa,EAAE,MAAM,CAAC;QACtB,0CAA0C;QAC1C,mBAAmB,EAAE,MAAM,CAAC;QAC5B,yDAAyD;QACzD,MAAM,EAAE,MAAM,CAAC;KAChB;IAMD,IAAI,OAAO,IAAI,MAAM,CAEpB;IAID;;;;;OAKG;IACG,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC;IAqB1D;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC;IAQ1C;;;;OAIG;IACG,mBAAmB,IAAI,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC;IAQzD;;;;;OAKG;IACG,gBAAgB,CAAC,EAAE,QAAQ,EAAE,GAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CACvE,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,aAAa,CAAC,CAC5C;IAQD;;;;;OAKG;IACG,iBAAiB,CAAC,EACtB,aAAa,GACd,EAAE;QACD,aAAa,EAAE,MAAM,CAAC;KACvB,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;IASlC;;;;;OAKG;IACG,YAAY,CAAC,EACjB,QAAQ,GACT,EAAE;QACD,QAAQ,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO,CAAC,MAAM,CAAC,eAAe,CAAC;IAMnC;;;;;OAKG;IACG,cAAc,CAAC,EAAE,SAAS,EAAE,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAI3E;;OAEG;IACH,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM;IAOxE;;;;OAIG;IACG,iBAAiB,CAAC,EACtB,QAAQ,GACT,EAAE;QACD,QAAQ,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC;IAMnC;;;;;;;;;OASG;IACG,qBAAqB,CAAC,EAC1B,QAAQ,EACR,SAAS,GACV,EAAE;QACD,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC;IASnC;;;;;;OAMG;IACG,cAAc,CAAC,EACnB,SAAS,GACV,EAAE;QACD,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAQvD,wDAAwD;IACxD,KAAK,IAAI,IAAI;CA4Dd"}

package/dist/clients/polite.js

@@ -0,0 +1,191 @@
+import * as schema from "../schema/polite";
+import { defaultToBaseURL } from "../utils/url";
+import { UnexpectedResponseError } from "../errors";
+// TODO: /d2l/api/le/manageCourses/courses-searches/490586/BySemester
+/**
+ * Low-level client for the POLITE API (`*.polite.edu.sg`).
+ *
+ * Handles authentication via D2L session cookies and exposes one method per
+ * API endpoint. All response bodies are validated with Zod schemas before
+ * being returned, so callers receive fully-typed data.
+ */
+export class POLITE {
+    #d2lSessionVal;
+    #d2lSecureSessionVal;
+    #domain;
+    #abortController = new AbortController();
+    constructor(config) {
+        this.#domain = config.domain;
+        this.#d2lSessionVal = config.d2lSessionVal;
+        this.#d2lSecureSessionVal = config.d2lSecureSessionVal;
+    }
+    get baseURL() {
+        return `https://${this.#domain}.polite.edu.sg`;
+    }
+    // ── Auth ────────────────────────────────────────────────────────────────────
+    /**
+     * GET /d2l/lp/auth/oauth2/token
+     *
+     * Exchanges the current D2L session cookies for a short-lived Brightspace
+     * JWT that can be used with the `*.api.brightspace.com` APIs.
+     */
+    async getNewFetchToken() {
+        // Fetch the homepage HTML to extract the XSRF token from it
+        const homepage = await this.#fetchText("/d2l/home");
+        const xsrfToken = homepage.match(/\.setItem\(['"]XSRF.Token['"],\s*['"](.+?)['"]\)/)?.[1];
+        if (!xsrfToken) {
+            throw new UnexpectedResponseError("No XSRF token found in homepage");
+        }
+        return this.#fetchJSON("/d2l/lp/auth/oauth2/token", {
+            method: "POST",
+            headers: { "X-Csrf-Token": xsrfToken },
+            body: new URLSearchParams({ scope: "*:*:*" }),
+            schema: schema.brightspaceToken,
+        });
+    }
+    // ── Users ───────────────────────────────────────────────────────────────────
+    /**
+     * GET /d2l/api/lp/1.0/users/whoami
+     *
+     * Returns basic information about the currently authenticated user.
+     */
+    async whoAmI() {
+        return this.#fetchJSON("/d2l/api/lp/1.0/users/whoami", {
+            schema: schema.whoAmIUser,
+        });
+    }
+    // ── Organization ────────────────────────────────────────────────────────────
+    /**
+     * GET /d2l/api/lp/1.46/organization/info
+     *
+     * Returns information about the organisation (institution).
+     */
+    async getOrganizationInfo() {
+        return this.#fetchJSON("/d2l/api/lp/1.46/organization/info", {
+            schema: schema.organization,
+        });
+    }
+    // ── Enrollments ─────────────────────────────────────────────────────────────
+    /**
+     * GET /d2l/api/lp/1.46/enrollments/myenrollments/
+     *
+     * Returns one page of the authenticated user's org-unit enrollments.
+     * Pass `bookmark` to fetch subsequent pages.
+     */
+    async getMyEnrollments({ bookmark } = {}) {
+        const query = bookmark ? `?bookmark=${encodeURIComponent(bookmark)}` : "";
+        return this.#fetchJSON(`/d2l/api/lp/1.46/enrollments/myenrollments/${query}`, { schema: schema.pagedResultSet(schema.myOrgUnitInfo) });
+    }
+    /**
+     * GET /d2l/api/lp/1.46/courses/parentorgunits?orgUnitIdsCSV=…
+     *
+     * Returns semester/department parent information for up to 25 course-offering
+     * org units at a time.
+     */
+    async getParentOrgUnits({ orgUnitIdsCSV, }) {
+        return this.#fetchJSON(`/d2l/api/lp/1.46/courses/parentorgunits?orgUnitIdsCSV=${encodeURIComponent(orgUnitIdsCSV)}`, { schema: schema.courseParent.array() });
+    }
+    // ── Content ─────────────────────────────────────────────────────────────────
+    /**
+     * GET /d2l/api/le/1.75/{moduleId}/content/toc
+     *
+     * Returns the table of contents for a module, including all nested folders
+     * (Modules) and topics (Activities).
+     */
+    async getModuleTOC({ moduleId, }) {
+        return this.#fetchJSON(`/d2l/api/le/1.75/${moduleId}/content/toc`, {
+            schema: schema.tableOfContents,
+        });
+    }
+    /**
+     * Fetch a content URL as raw text (used for HTML-type activities).
+     *
+     * `urlOrPath` may be either an absolute URL or a path relative to
+     * `this.baseURL`.
+     */
+    async getContentHTML({ urlOrPath }) {
+        return this.#fetchText(urlOrPath);
+    }
+    /**
+     * Return the image URL for a module or organisation.
+     */
+    getImageURL(id, dim) {
+        const query = dim ? `?width=${dim.width}&height=${dim.height}` : "";
+        return `${this.baseURL}/d2l/api/lp/1.46/courses/${id}/image${query}`;
+    }
+    // ── Dropbox / Submissions ────────────────────────────────────────────────────
+    /**
+     * GET /d2l/api/le/1.75/{moduleId}/dropbox/folders/
+     *
+     * Returns all submission dropbox folders in a module.
+     */
+    async getDropboxFolders({ moduleId, }) {
+        return this.#fetchJSON(`/d2l/api/le/1.75/${moduleId}/dropbox/folders/`, {
+            schema: schema.dropboxFolder.array(),
+        });
+    }
+    /**
+     * GET /d2l/api/le/1.75/{moduleId}/dropbox/folders/{dropboxId}/submissions/
+     *
+     * Returns the current user's submissions for a dropbox. Returns at most one
+     * `EntityDropbox` object (the user's own entry).
+     *
+     * > **Note:** This endpoint returns HTTP 403 for dropboxes whose availability
+     * > window has closed. In that case, use the Brightspace Activities API
+     * > instead (`Brightspace.getClosedDropboxSubmissions`).
+     */
+    async getDropboxSubmissions({ moduleId, dropboxId, }) {
+        return this.#fetchJSON(`/d2l/api/le/1.75/${moduleId}/dropbox/folders/${dropboxId}/submissions/`, { schema: schema.entityDropbox.array().max(1) });
+    }
+    // ── Quizzes ──────────────────────────────────────────────────────────────────
+    /**
+     * Fetch one page of quizzes from the given URL or path.
+     *
+     * For the first page, pass `/d2l/api/le/1.75/{moduleId}/quizzes/`.
+     * The `Next` field of the returned object is the URL for the next page
+     * (or `null` if there are no more pages).
+     */
+    async getQuizzesPage({ urlOrPath, }) {
+        return this.#fetchJSON(urlOrPath, {
+            schema: schema.objectListPage(schema.quizReadData),
+        });
+    }
+    // ── Lifecycle ────────────────────────────────────────────────────────────────
+    /** Abort all in-flight requests made by this client. */
+    abort() {
+        this.#abortController.abort();
+    }
+    async #fetchJSON(input, init) {
+        const res = await this.#fetch(input, init);
+        if (!res.ok) {
+            throw new UnexpectedResponseError(`Received ${res.status} for ${defaultToBaseURL(input, this.baseURL)}`, { response: res });
+        }
+        const data = await res.json();
+        if (init?.schema) {
+            return init.schema.parse(data);
+        }
+        return data;
+    }
+    async #fetchText(urlOrPath) {
+        const res = await this.#fetch(urlOrPath);
+        if (!res.ok) {
+            throw new Error(`POLITE API error ${res.status} at ${urlOrPath}`);
+        }
+        return res.text();
+    }
+    /**
+     * {@link fetch} wrapper that:
+     * - Defaults to {@link baseURL} as the base URL.
+     * - Adds authentication cookies.
+     */
+    async #fetch(input, init) {
+        const headers = new Headers(init?.headers);
+        headers.set("Cookie", `d2lSessionVal=${this.#d2lSessionVal}; d2lSecureSessionVal=${this.#d2lSecureSessionVal}`);
+        return fetch(defaultToBaseURL(input, this.baseURL), {
+            ...init,
+            headers,
+            signal: this.#abortController.signal,
+        });
+    }
+}
+//# sourceMappingURL=polite.js.map

package/dist/clients/polite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"polite.js","sourceRoot":"","sources":["../../clients/polite.ts"],"names":[],"mappings":"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"}

package/dist/clients/politeshop.d.ts

@@ -0,0 +1,119 @@
+import type { ActivityFolder, Module, Institution, Quiz, Semester, SubmissionDropbox, User, Submission } from "../types";
+import { Brightspace } from "./brightspace";
+import { POLITE } from "./polite";
+/**
+ * High-level POLITEMall client.
+ *
+ * Composes {@link POLITE} (for `*.polite.edu.sg` APIs) and {@link Brightspace}
+ * (for `*.api.brightspace.com` APIs) into a single, convenient interface.
+ *
+ * Both lower-level clients are accessible so callers can reach endpoints not
+ * covered by the high-level methods.
+ */
+export declare class POLITEShop {
+    #private;
+    /** Client for `*.polite.edu.sg` APIs. */
+    readonly polite: POLITE;
+    /**
+     * Initialize the underlying {@link POLITE} client. If `d2lFetchToken` is
+     * provided, the {@link Brightspace} client is also initialized immediately.
+     * Otherwise, it is initialized lazily via the {@link brightspace} getter.
+     */
+    constructor(config: {
+        /** `d2lSessionVal` cookie value. */
+        d2lSessionVal: string;
+        /** `d2lSecureSessionVal` cookie value. */
+        d2lSecureSessionVal: string;
+        /** Subdomain of the POLITEMall site (e.g. `"nplms"`). */
+        domain: string;
+        /**
+         * Brightspace JWT found in localStorage. If not provided,
+         * it will be fetched automatically the first time it is needed.
+         */
+        d2lFetchToken?: string;
+    });
+    /**
+     * Returns the initialized {@link Brightspace} client, fetching or refreshing
+     * the `d2lFetchToken` automatically when needed.
+     *
+     * Implemented as a Promise-returning getter rather than a plain `Brightspace`
+     * property because the token may be unavailable or expired at access time,
+     * requiring an asynchronous network request to obtain a fresh one.
+     */
+    get brightspace(): Promise<Brightspace>;
+    /** Fetch the user's ID and display name. */
+    getUser(): Promise<User>;
+    /** Fetch information about the educational institution the user is in. */
+    getInstitution(): Promise<Institution>;
+    /**
+     * Return the URL of the institution's image. The institution's ID is needed to
+     * construct the URL, so if not provided, this calls {@link getInstitution}.
+     * The URL construction itself is synchronous. */
+    getInstitutionImageURL(config: {
+        width: number;
+        height: number;
+    }): Promise<string>;
+    getInstitutionImageURL(config: {
+        width: number;
+        height: number;
+        institutionId: string;
+    }): string;
+    /**
+     * Fetch the modules the user is enrolled in.
+     */
+    getModules(): Promise<Module[]>;
+    /**
+     * Fetch all modules the user is enrolled in, together with the associated semesters.
+     */
+    getModulesAndSemesters(): Promise<{
+        modules: (Module & {
+            semesterId: string;
+        })[];
+        semesters: Semester[];
+    }>;
+    /**
+     * Fetch all activity folders and activities for a module.
+     *
+     * Retrieves the table of contents then recursively parses every folder and
+     * topic, making additional requests as needed to resolve activity details.
+     */
+    getModuleContent({ moduleId, }: {
+        moduleId: string;
+    }): Promise<ActivityFolder[]>;
+    /** Fetch all submission dropbox folders in a module. */
+    getSubmissionDropboxes({ moduleId, }: {
+        moduleId: string;
+    }): Promise<SubmissionDropbox[]>;
+    /**
+     * Fetch the authenticated user's submissions for a given dropbox.
+     *
+     * Two strategies are attempted in order:
+     *
+     * 1. **POLITE API** — A single request returns all submissions. This is the
+     *    preferred path but returns HTTP 403 for dropboxes whose availability
+     *    window has closed.
+     * 2. **Brightspace Activities API** — Used as a fallback when the POLITE API
+     *    fails. Requires one additional request per submission. If `organizationId`
+     *    is not provided, it is fetched automatically via {@link getInstitution}.
+     *
+     * @param params.moduleId - The module (course offering) ID.
+     * @param params.dropboxId - The dropbox folder ID.
+     * @param params.organizationId - The organisation ID, used by the Brightspace
+     *   Activities API path. If omitted and the fallback is needed, it is fetched
+     *   automatically via {@link getInstitution}.
+     */
+    getSubmissions({ moduleId, dropboxId, organizationId, }: {
+        moduleId: string;
+        dropboxId: string;
+        organizationId?: string;
+    }): Promise<Submission[]>;
+    /**
+     * Fetch all quizzes in a module.
+     */
+    getQuizzes({ moduleId }: {
+        moduleId: string;
+    }): Promise<Quiz[]>;
+    /** Abort all in-flight requests on both the POLITE and Brightspace clients. */
+    abort(): void;
+}
+//# sourceMappingURL=politeshop.d.ts.map