brightspace-d2l-mcp 1.0.0

package/build/api/client.js

@@ -0,0 +1,345 @@
+import { DEFAULT_CACHE_TTLS } from "./types.js";
+import { TTLCache } from "./cache.js";
+import { TokenBucket } from "./rate-limiter.js";
+import { discoverVersions } from "./version-discovery.js";
+import { ApiError, RateLimitError, NetworkError } from "./errors.js";
+import { withRetry, isRetryableFailure, retryAfterMsFrom } from "./retry.js";
+import { log } from "../utils/logger.js";
+import { LOGIN_COMMAND } from "../utils/paths.js";
+import { packageVersion } from "../utils/version.js";
+function isExpiredSessionRedirect(body, baseUrl) {
+    const expiredTarget = (target) => {
+        try {
+            const url = new URL(target.replace(/&/gi, "&").replace(/\\\//g, "/"), baseUrl);
+            return url.origin === new URL(baseUrl).origin && url.pathname === "/d2l/login" &&
+                url.searchParams.get("sessionExpired") === "1";
+        }
+        catch {
+            return false;
+        }
+    };
+    for (const script of body.matchAll(/<script\b[^>]*>([\s\S]*?)<\/script\s*>/gi)) {
+        const redirect = /(?:(?:window|document)\s*\.\s*)?location\s*(?:\.\s*(?:replace|assign)\s*\(\s*|(?:\.\s*href\s*)?=\s*)(["'])(.*?)\1/g;
+        for (const match of script[1].matchAll(redirect)) {
+            if (expiredTarget(match[2]))
+                return true;
+        }
+    }
+    for (const meta of body.matchAll(/<meta\b[^>]*>/gi)) {
+        const attributes = new Map([...meta[0].matchAll(/([\w-]+)\s*=\s*(["'])(.*?)\2/g)].map(match => [match[1].toLowerCase(), match[3]]));
+        if (attributes.get("http-equiv")?.toLowerCase() !== "refresh")
+            continue;
+        const target = attributes.get("content")?.match(/^\s*\d+(?:\.\d+)?\s*;\s*url\s*=\s*(.*?)\s*$/i)?.[1];
+        if (target && expiredTarget(target))
+            return true;
+    }
+    return false;
+}
+const LP_VERSION = "{lp}";
+const LE_VERSION = "{le}";
+export class D2LApiClient {
+    baseUrl;
+    tokenManager;
+    cache;
+    rateLimiter;
+    cacheTTLs;
+    timeoutMs;
+    onAuthExpired;
+    retryConfig;
+    versions = null;
+    versionsInFlight = null;
+    constructor(options) {
+        // HTTPS-only enforcement, on a parsed URL rather than a string prefix so
+        // a malformed base cannot slip through as "not http".
+        let parsedBase;
+        try {
+            parsedBase = new URL(options.baseUrl);
+        }
+        catch {
+            throw new Error(`Invalid D2L base URL: ${options.baseUrl}`);
+        }
+        if (parsedBase.protocol !== "https:") {
+            throw new Error("HTTPS is required for D2L API client. HTTP URLs are not allowed for security reasons.");
+        }
+        // Strip trailing slash from baseUrl
+        this.baseUrl = options.baseUrl.replace(/\/$/, "");
+        this.tokenManager = options.tokenManager;
+        this.timeoutMs = options.timeoutMs ?? 30_000;
+        this.onAuthExpired = options.onAuthExpired;
+        this.retryConfig = options.retry ?? {};
+        // Merge user-provided TTLs with defaults
+        this.cacheTTLs = { ...DEFAULT_CACHE_TTLS, ...options.cacheTTLs };
+        // Initialize cache and rate limiter
+        this.cache = new TTLCache();
+        const rateLimitConfig = options.rateLimitConfig ?? {
+            capacity: 10,
+            refillRate: 3,
+        };
+        this.rateLimiter = new TokenBucket(rateLimitConfig.capacity, rateLimitConfig.refillRate);
+        log("DEBUG", `D2LApiClient initialized for ${this.baseUrl}`);
+    }
+    async ensureVersions() {
+        if (this.versions)
+            return this.versions;
+        if (!this.versionsInFlight) {
+            const flow = discoverVersions(this.baseUrl, this.timeoutMs)
+                .then(versions => {
+                this.versions = versions;
+                log("INFO", `D2L API versions discovered: LP ${versions.lp}, LE ${versions.le}`);
+                return versions;
+            })
+                .finally(() => {
+                if (this.versionsInFlight === flow)
+                    this.versionsInFlight = null;
+            });
+            this.versionsInFlight = flow;
+        }
+        return this.versionsInFlight;
+    }
+    async initialize() {
+        await this.ensureVersions();
+    }
+    get apiVersions() {
+        if (!this.versions) {
+            throw new Error("API versions have not been discovered yet. They are fetched on the first request.");
+        }
+        return this.versions;
+    }
+    async resolvePath(path) {
+        if (!path.includes(LP_VERSION) && !path.includes(LE_VERSION))
+            return path;
+        const { lp, le } = await this.ensureVersions();
+        return path.split(LP_VERSION).join(lp).split(LE_VERSION).join(le);
+    }
+    async get(path, options) {
+        // Checked before the path is resolved, and keyed by the path as the caller
+        // wrote it, so a cached read needs neither version discovery nor a token.
+        if (options?.ttl && this.cache.has(path)) {
+            log("DEBUG", `Cache hit: ${path}`);
+            return this.cache.get(path);
+        }
+        const resolved = await this.resolvePath(path);
+        const data = await this.withAuthentication(resolved, token => this.makeRequest(resolved, token));
+        if (options?.ttl) {
+            this.cache.set(path, data, options.ttl);
+            log("DEBUG", `Cached response for ${path} (TTL: ${options.ttl}ms)`);
+        }
+        return data;
+    }
+    async getRaw(path) {
+        const resolved = await this.resolvePath(path);
+        return this.withAuthentication(resolved, token => this.makeRawRequest(resolved, token));
+    }
+    async withAuthentication(path, request) {
+        let token = await this.tokenManager.getToken();
+        let authenticated = false;
+        if (!token) {
+            token = await this.tryAutoReauth(path);
+            authenticated = true;
+        }
+        const send = (current) => this.retrying(() => this.throttled(() => request(current)));
+        try {
+            return await send(token);
+        }
+        catch (error) {
+            if (!(error instanceof ApiError) || error.status !== 401)
+                throw error;
+            if (authenticated)
+                throw error;
+        }
+        const fresh = await this.tokenManager.getToken(token.accessToken);
+        if (fresh && fresh.accessToken !== token.accessToken) {
+            try {
+                return await send(fresh);
+            }
+            catch (error) {
+                if (!(error instanceof ApiError) || error.status !== 401)
+                    throw error;
+            }
+        }
+        const loggedIn = await this.tryAutoReauth(path, fresh?.accessToken ?? token.accessToken);
+        return send(loggedIn);
+    }
+    async throttled(fn) {
+        await this.rateLimiter.consume();
+        return fn();
+    }
+    retrying(fn) {
+        return withRetry(fn, {
+            ...this.retryConfig,
+            shouldRetry: isRetryableFailure,
+            retryAfterMs: retryAfterMsFrom,
+        });
+    }
+    async tryAutoReauth(path, rejectedAccessToken) {
+        if (this.onAuthExpired) {
+            log("INFO", "Attempting auto-reauthentication...");
+            const success = await this.onAuthExpired();
+            if (success) {
+                const freshToken = await this.tokenManager.getToken(rejectedAccessToken);
+                if (freshToken) {
+                    log("INFO", "Auto-reauthentication succeeded, retrying request");
+                    return freshToken;
+                }
+            }
+            log("WARN", "Auto-reauthentication did not produce a valid token");
+        }
+        throw new ApiError(401, path, `Session expired. Please re-authenticate via ${LOGIN_COMMAND}.`);
+    }
+    async makeRequest(path, token) {
+        const url = `${this.baseUrl}${path}`;
+        const headers = this.buildAuthHeaders(token);
+        try {
+            log("DEBUG", `Requesting GET ${path}`);
+            const response = await fetch(url, {
+                method: "GET",
+                headers,
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+            // Preserve cookie material: a 401 only rejects this access token.
+            if (response.status === 401) {
+                throw new ApiError(401, path, "Brightspace rejected the access token.");
+            }
+            // Handle 429 rate limiting
+            if (response.status === 429) {
+                const retryAfter = response.headers.get("Retry-After");
+                const retryAfterSeconds = retryAfter ? parseInt(retryAfter, 10) : undefined;
+                throw new RateLimitError(path, retryAfterSeconds);
+            }
+            // Handle 403 (common for past-semester courses)
+            if (response.status === 403) {
+                const responseText = await response.text();
+                throw new ApiError(403, path, responseText);
+            }
+            // Handle other non-OK responses
+            if (!response.ok) {
+                const responseText = await response.text();
+                throw new ApiError(response.status, path, responseText);
+            }
+            const responseBody = await response.text();
+            let data;
+            try {
+                data = JSON.parse(responseBody);
+            }
+            catch {
+                // Only now consider the stub: a real payload that merely mentions the
+                // marker still parses, so it can never be misread as a dead session.
+                if (isExpiredSessionRedirect(responseBody, this.baseUrl)) {
+                    log("DEBUG", "Response carried the session-expired stub, treating it as a 401");
+                    throw new ApiError(401, path, `Session expired. Please re-authenticate via ${LOGIN_COMMAND}.`);
+                }
+                throw new ApiError(response.status, path, `Expected JSON from ${path} but the body did not parse`);
+            }
+            return data;
+        }
+        catch (error) {
+            // Re-throw our own errors
+            if (error instanceof ApiError ||
+                error instanceof RateLimitError ||
+                error instanceof NetworkError) {
+                throw error;
+            }
+            // Wrap network/fetch errors
+            const message = error instanceof Error ? error.message : String(error);
+            throw new NetworkError(`Request to ${path} failed: ${message}`, error instanceof Error ? error : undefined);
+        }
+    }
+    async makeRawRequest(path, token) {
+        const url = `${this.baseUrl}${path}`;
+        const headers = this.buildAuthHeaders(token);
+        try {
+            log("DEBUG", `Requesting GET ${path} (raw)`);
+            const response = await fetch(url, {
+                method: "GET",
+                headers,
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+            // Preserve cookie material for the shared HTTP refresh path.
+            if (response.status === 401) {
+                throw new ApiError(401, path, "Brightspace rejected the access token.");
+            }
+            // Handle 429 rate limiting
+            if (response.status === 429) {
+                const retryAfter = response.headers.get("Retry-After");
+                const retryAfterSeconds = retryAfter ? parseInt(retryAfter, 10) : undefined;
+                throw new RateLimitError(path, retryAfterSeconds);
+            }
+            // Handle 403 (common for past-semester courses or no access)
+            if (response.status === 403) {
+                const responseText = await response.text();
+                throw new ApiError(403, path, responseText);
+            }
+            // Handle 404 (file not found)
+            if (response.status === 404) {
+                throw new ApiError(404, path, "File not found");
+            }
+            // Handle other non-OK responses
+            if (!response.ok) {
+                const responseText = await response.text();
+                throw new ApiError(response.status, path, responseText);
+            }
+            const contentType = (response.headers.get("content-type") ?? "").toLowerCase();
+            if (contentType.startsWith("text/html")) {
+                const body = await response.text();
+                if (isExpiredSessionRedirect(body, this.baseUrl)) {
+                    log("DEBUG", "File download answered with the session-expired stub, treating it as a 401");
+                    throw new ApiError(401, path, `Session expired. Please re-authenticate via ${LOGIN_COMMAND}.`);
+                }
+                // A legitimate HTML page: hand back an equivalent response with the
+                // body we already consumed.
+                return new Response(body, {
+                    status: response.status,
+                    statusText: response.statusText,
+                    headers: response.headers,
+                });
+            }
+            // Return raw response for caller to process
+            return response;
+        }
+        catch (error) {
+            // Re-throw our own errors
+            if (error instanceof ApiError ||
+                error instanceof RateLimitError ||
+                error instanceof NetworkError) {
+                throw error;
+            }
+            // Wrap network/fetch errors
+            const message = error instanceof Error ? error.message : String(error);
+            throw new NetworkError(`Request to ${path} failed: ${message}`, error instanceof Error ? error : undefined);
+        }
+    }
+    buildAuthHeaders(token) {
+        const headers = {
+            "User-Agent": `brightspace-d2l-mcp/${packageVersion()}`,
+        };
+        // Auto-detect cookie vs Bearer auth based on "cookie:" prefix
+        if (token.accessToken.startsWith("cookie:")) {
+            // Cookie-based auth: strip prefix and set Cookie header
+            headers["Cookie"] = token.accessToken.substring(7);
+            log("DEBUG", "Using cookie-based authentication");
+        }
+        else {
+            // Bearer token auth
+            headers["Authorization"] = `Bearer ${token.accessToken}`;
+            log("DEBUG", "Using Bearer token authentication");
+        }
+        return headers;
+    }
+    lp(path) {
+        return `/d2l/api/lp/${LP_VERSION}${path}`;
+    }
+    le(orgUnitId, path) {
+        return `/d2l/api/le/${LE_VERSION}/${orgUnitId}${path}`;
+    }
+    leGlobal(path) {
+        return `/d2l/api/le/${LE_VERSION}${path}`;
+    }
+    clearCache() {
+        this.cache.clear();
+        log("DEBUG", "Cache cleared");
+    }
+    get cacheSize() {
+        return this.cache.size;
+    }
+}
+//# sourceMappingURL=client.js.map

package/build/api/errors.js

@@ -0,0 +1,48 @@
+import { AuthError } from "../utils/errors.js";
+// Base class for all HTTP API errors
+export class ApiError extends AuthError {
+    status;
+    endpoint;
+    responseBody;
+    constructor(status, endpoint, message, responseBody, cause) {
+        super(`[PBMCP-2001] API error (${status}) at ${endpoint}: ${message}`, cause);
+        this.status = status;
+        this.endpoint = endpoint;
+        this.responseBody = responseBody;
+        this.name = "ApiError";
+    }
+}
+// Generic HTTP error (non-401/429) - semantic alias for ApiError
+export class HttpError extends ApiError {
+    constructor(status, endpoint, message, responseBody, cause) {
+        super(status, endpoint, message, responseBody, cause);
+        this.name = "HttpError";
+    }
+}
+// Rate limit error (429 Too Many Requests)
+export class RateLimitError extends ApiError {
+    retryAfter;
+    constructor(endpoint, retryAfter) {
+        const message = retryAfter
+            ? `[PBMCP-2002] Rate limited, retry after ${retryAfter}s`
+            : "[PBMCP-2002] Rate limited";
+        super(429, endpoint, message);
+        this.retryAfter = retryAfter;
+        this.name = "RateLimitError";
+    }
+}
+// Network-level error (no HTTP status code)
+// For fetch failures, timeouts, DNS errors
+export class NetworkError extends AuthError {
+    constructor(message, cause) {
+        super(`[PBMCP-2003] Network error: ${message}`, cause);
+        this.name = "NetworkError";
+    }
+}
+export class TokenRefreshError extends NetworkError {
+    constructor(detail, cause) {
+        super(`Token refresh is temporarily unavailable: ${detail}. Your saved session was retained. Try again later.`, cause);
+        this.name = "TokenRefreshError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/build/api/index.js

@@ -0,0 +1,12 @@
+// D2L API client and infrastructure - Phase 2 public exports
+// Main client
+export { D2LApiClient } from "./client.js";
+// Version discovery
+export { discoverVersions } from "./version-discovery.js";
+// Cache and rate limiting
+export { TTLCache } from "./cache.js";
+export { TokenBucket } from "./rate-limiter.js";
+// Errors
+export { ApiError, RateLimitError, NetworkError } from "./errors.js";
+export { DEFAULT_CACHE_TTLS } from "./types.js";
+//# sourceMappingURL=index.js.map

package/build/api/paginate.js

@@ -0,0 +1,70 @@
+import { log } from "../utils/logger.js";
+const MAX_PAGES = 200;
+function withBookmark(firstPath, bookmark) {
+    const separator = firstPath.includes("?") ? "&" : "?";
+    return `${firstPath}${separator}bookmark=${encodeURIComponent(bookmark)}`;
+}
+export async function fetchAllItems(apiClient, firstPath, options) {
+    const items = [];
+    const seen = new Set();
+    let path = firstPath;
+    let pages = 0;
+    while (path !== null) {
+        if (pages >= MAX_PAGES) {
+            log("WARN", `Pagination stopped at the ${MAX_PAGES} page ceiling`, { firstPath });
+            break;
+        }
+        const response = await apiClient.get(path, options);
+        pages += 1;
+        items.push(...(response?.Items ?? []));
+        const paging = response?.PagingInfo;
+        const bookmark = paging?.Bookmark;
+        if (!paging?.HasMoreItems || !bookmark)
+            break;
+        if (seen.has(bookmark)) {
+            log("WARN", "Pagination stopped: the server repeated a bookmark", { firstPath });
+            break;
+        }
+        seen.add(bookmark);
+        path = withBookmark(firstPath, bookmark);
+    }
+    return items;
+}
+export async function fetchAllObjects(apiClient, firstPath, options) {
+    const objects = [];
+    const seen = new Set();
+    let path = firstPath;
+    let pages = 0;
+    while (path !== null) {
+        if (pages >= MAX_PAGES) {
+            log("WARN", `Pagination stopped at the ${MAX_PAGES} page ceiling`, { firstPath });
+            break;
+        }
+        const response = await apiClient.get(path, options);
+        pages += 1;
+        objects.push(...(response?.Objects ?? []));
+        const next = response?.Next;
+        if (!next)
+            break;
+        if (seen.has(next)) {
+            log("WARN", "Pagination stopped: the server repeated a next page", { firstPath });
+            break;
+        }
+        seen.add(next);
+        path = nextPath(firstPath, next);
+    }
+    return objects;
+}
+function nextPath(firstPath, next) {
+    if (/^https?:\/\//i.test(next)) {
+        const url = new URL(next);
+        return `${url.pathname}${url.search}`;
+    }
+    // A Next that begins with a slash is already a path, not a bookmark.
+    // Appending it as one would ask for a page that does not exist.
+    if (next.startsWith("/")) {
+        return next;
+    }
+    return withBookmark(firstPath, next);
+}
+//# sourceMappingURL=paginate.js.map

package/build/api/rate-limiter.js

@@ -0,0 +1,52 @@
+// Token bucket rate limiter - allows bursts up to capacity
+// Conservative defaults: capacity 10, refill 3/sec
+export class TokenBucket {
+    tokens;
+    lastRefill;
+    capacity;
+    refillRate; // tokens per second
+    constructor(capacity, refillRate) {
+        this.capacity = capacity;
+        this.refillRate = refillRate;
+        this.tokens = capacity; // Start with full bucket
+        this.lastRefill = Date.now();
+    }
+    refill() {
+        const now = Date.now();
+        const elapsedMs = now - this.lastRefill;
+        const elapsedSeconds = elapsedMs / 1000;
+        // Add tokens based on elapsed time
+        const tokensToAdd = elapsedSeconds * this.refillRate;
+        this.tokens = Math.min(this.capacity, this.tokens + tokensToAdd);
+        this.lastRefill = now;
+    }
+    async consume(count = 1) {
+        this.refill();
+        if (this.tokens >= count) {
+            // Enough tokens available - consume immediately
+            this.tokens -= count;
+            return;
+        }
+        // Not enough tokens - calculate wait time
+        const tokensNeeded = count - this.tokens;
+        const waitTimeMs = (tokensNeeded / this.refillRate) * 1000;
+        // Wait for tokens to refill
+        await new Promise((resolve) => setTimeout(resolve, waitTimeMs));
+        // Refill and consume
+        this.refill();
+        this.tokens -= count;
+    }
+    tryConsume(count = 1) {
+        this.refill();
+        if (this.tokens >= count) {
+            this.tokens -= count;
+            return true;
+        }
+        return false;
+    }
+    get availableTokens() {
+        this.refill();
+        return this.tokens;
+    }
+}
+//# sourceMappingURL=rate-limiter.js.map

package/build/api/retry.js

@@ -0,0 +1,39 @@
+import { ApiError, NetworkError, RateLimitError } from "./errors.js";
+const JITTER_FRACTION = 0.3;
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export async function withRetry(fn, options) {
+    const { maxAttempts = 3, initialMs = 250, maxMs = 5000, sleep = defaultSleep, jitter = Math.random, shouldRetry, retryAfterMs, } = options;
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            if (attempt >= maxAttempts || !shouldRetry(error))
+                throw error;
+            const requested = retryAfterMs?.(error);
+            let delay;
+            if (requested !== undefined) {
+                delay = requested;
+            }
+            else {
+                const base = Math.min(initialMs * 2 ** (attempt - 1), maxMs);
+                delay = Math.round(base + base * JITTER_FRACTION * jitter());
+            }
+            await sleep(delay);
+        }
+    }
+}
+export function isRetryableFailure(error) {
+    if (error instanceof RateLimitError)
+        return true;
+    if (error instanceof ApiError)
+        return error.status >= 500 && error.status <= 599;
+    return error instanceof NetworkError;
+}
+export function retryAfterMsFrom(error) {
+    if (error instanceof RateLimitError && typeof error.retryAfter === "number" && error.retryAfter > 0) {
+        return error.retryAfter * 1000;
+    }
+    return undefined;
+}
+//# sourceMappingURL=retry.js.map

package/build/api/types.js

@@ -0,0 +1,11 @@
+// Default TTL values per user decision
+export const DEFAULT_CACHE_TTLS = {
+    enrollments: 3_600_000,
+    courseContent: 1_800_000,
+    announcements: 300_000,
+    grades: 120_000,
+    assignments: 600_000,
+    roster: 3_600_000,
+    profile: 3_600_000,
+};
+//# sourceMappingURL=types.js.map

package/build/api/version-discovery.js

@@ -0,0 +1,43 @@
+import { NetworkError } from "./errors.js";
+import { log } from "../utils/logger.js";
+export async function discoverVersions(baseUrl, timeoutMs = 15000) {
+    const url = `${baseUrl}/d2l/api/versions/`;
+    try {
+        log("DEBUG", `Discovering API versions from ${url}`);
+        const response = await fetch(url, {
+            signal: AbortSignal.timeout(timeoutMs),
+            headers: {
+                // Browser-like User-Agent for version discovery
+                "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
+            },
+        });
+        if (!response.ok) {
+            throw new NetworkError(`Version discovery failed with status ${response.status}`);
+        }
+        const versions = await response.json();
+        // Find LP (Learning Platform) and LE (Learning Environment) versions
+        const lpEntry = versions.find(v => v.ProductCode === "lp");
+        const leEntry = versions.find(v => v.ProductCode === "le");
+        if (!lpEntry) {
+            throw new NetworkError("LP (Learning Platform) version not found in /d2l/api/versions/ response");
+        }
+        if (!leEntry) {
+            throw new NetworkError("LE (Learning Environment) version not found in /d2l/api/versions/ response");
+        }
+        const result = {
+            lp: lpEntry.LatestVersion,
+            le: leEntry.LatestVersion,
+        };
+        log("INFO", `Discovered API versions: LP ${result.lp}, LE ${result.le}`);
+        return result;
+    }
+    catch (error) {
+        if (error instanceof NetworkError) {
+            throw error;
+        }
+        // Wrap other errors (timeout, network failures, JSON parse errors)
+        const message = error instanceof Error ? error.message : String(error);
+        throw new NetworkError(`Failed to discover API versions: ${message}`, error instanceof Error ? error : undefined);
+    }
+}
+//# sourceMappingURL=version-discovery.js.map