brightspace-d2l-mcp 1.0.0

package/build/tools/get-syllabus.js

@@ -0,0 +1,154 @@
+import { ApiError, DEFAULT_CACHE_TTLS } from "../api/index.js";
+import { GetSyllabusSchema } from "./schemas.js";
+import { toolResponse, sanitizeError, errorResponse } from "./tool-helpers.js";
+import { convertHtmlToMarkdown } from "../utils/html-converter.js";
+import { secureDownload } from "../utils/download-helpers.js";
+import { MAX_FILE_SIZE } from "../utils/file-validator.js";
+import { extractPdfText } from "../utils/pdf-extractor.js";
+import { log } from "../utils/logger.js";
+import path from "node:path";
+import fs from "node:fs/promises";
+export function registerGetSyllabus(server, apiClient) {
+    server.registerTool("get_syllabus", {
+        title: "Get Course Syllabus",
+        description: "Fetch the syllabus/overview text and optional attachment for a course. Returns the course overview description as markdown. If downloadPath is provided, also downloads the syllabus attachment (e.g. PDF). IMPORTANT: You MUST ask the user where they want to save the file before calling this tool with a downloadPath.",
+        inputSchema: GetSyllabusSchema,
+    }, async (args) => {
+        try {
+            log("DEBUG", "get_syllabus tool called", { args });
+            const { courseId, downloadPath } = GetSyllabusSchema.parse(args);
+            // Validate downloadPath if provided
+            if (downloadPath !== undefined) {
+                if (!path.isAbsolute(downloadPath)) {
+                    return errorResponse("Download path must be an absolute path (e.g., /Users/username/Downloads on Mac or C:\\Users\\username\\Downloads on Windows)");
+                }
+                try {
+                    const stats = await fs.stat(downloadPath);
+                    if (!stats.isDirectory()) {
+                        return errorResponse(`Download path is not a directory: ${downloadPath}`);
+                    }
+                }
+                catch (error) {
+                    if (error?.code === "ENOENT") {
+                        return errorResponse(`Download directory does not exist: ${downloadPath}`);
+                    }
+                    throw error;
+                }
+            }
+            // Fetch overview text
+            let overview = null;
+            try {
+                overview = await apiClient.get(apiClient.le(courseId, "/overview"), { ttl: DEFAULT_CACHE_TTLS.courseContent });
+            }
+            catch (error) {
+                if (error instanceof ApiError && error.status === 404) {
+                    return toolResponse({
+                        courseId,
+                        description: null,
+                        hasAttachment: false,
+                        message: "No syllabus/overview found for this course.",
+                    });
+                }
+                throw error;
+            }
+            // Convert description HTML to markdown
+            const description = overview?.Description?.Html
+                ? convertHtmlToMarkdown(overview.Description.Html)
+                : null;
+            // Always attempt to fetch the attachment so we can extract PDF text
+            let attachmentBuffer = null;
+            let attachmentFilename = "syllabus";
+            let hasAttachment = false;
+            try {
+                const response = await apiClient.getRaw(apiClient.le(courseId, "/overview/attachment"));
+                if (response.ok) {
+                    hasAttachment = true;
+                    // Check Content-Length before downloading body
+                    const contentLength = parseInt(response.headers.get("Content-Length") ?? "0", 10);
+                    if (contentLength > MAX_FILE_SIZE) {
+                        return errorResponse(`Attachment too large (${Math.round(contentLength / 1024 / 1024)}MB). Maximum allowed: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
+                    }
+                    // Get filename from Content-Disposition header
+                    const disposition = response.headers.get("Content-Disposition") ?? "";
+                    const match = disposition.match(/filename[^;=\n]*=((['"]).*?\2|[^;\n]*)/);
+                    if (match?.[1]) {
+                        attachmentFilename = match[1].replace(/['"]/g, "");
+                    }
+                    // Download body as buffer
+                    attachmentBuffer = Buffer.from(await response.arrayBuffer());
+                    if (attachmentBuffer.length > MAX_FILE_SIZE) {
+                        return errorResponse(`Attachment too large (${Math.round(attachmentBuffer.length / 1024 / 1024)}MB). Maximum allowed: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
+                    }
+                }
+            }
+            catch (error) {
+                if (error instanceof ApiError && error.status === 404) {
+                    hasAttachment = false;
+                }
+                else {
+                    log("DEBUG", "Could not fetch syllabus attachment", error);
+                }
+            }
+            // Extract text from PDF attachment if available
+            let syllabusText = null;
+            let totalPages;
+            if (attachmentBuffer && attachmentFilename.toLowerCase().endsWith(".pdf")) {
+                const extracted = await extractPdfText(attachmentBuffer);
+                if (extracted) {
+                    syllabusText = extracted.text;
+                    totalPages = extracted.totalPages;
+                }
+            }
+            // Save to disk if downloadPath provided
+            let download;
+            if (downloadPath && attachmentBuffer) {
+                try {
+                    const result = await secureDownload({
+                        targetDir: downloadPath,
+                        filename: attachmentFilename,
+                        data: attachmentBuffer,
+                    });
+                    log("INFO", `Syllabus attachment downloaded: ${result.path} (${result.size} bytes)`);
+                    download = {
+                        success: true,
+                        filePath: result.path,
+                        fileSize: result.size,
+                        mimeType: result.mime,
+                    };
+                }
+                catch (error) {
+                    log("ERROR", "Failed to save syllabus attachment", error);
+                    download = {
+                        success: false,
+                        error: "Failed to save attachment to disk.",
+                    };
+                }
+            }
+            else if (downloadPath && !attachmentBuffer) {
+                download = {
+                    success: false,
+                    error: "No attachment found for this course's syllabus.",
+                };
+            }
+            log("INFO", `get_syllabus: Retrieved overview for course ${courseId}`);
+            // Build response
+            const result = { courseId, description };
+            if (syllabusText) {
+                result.syllabusText = syllabusText;
+                if (totalPages)
+                    result.totalPages = totalPages;
+            }
+            else {
+                result.hasAttachment = hasAttachment;
+            }
+            if (download) {
+                result.download = download;
+            }
+            return toolResponse(result);
+        }
+        catch (error) {
+            return sanitizeError(error);
+        }
+    });
+}
+//# sourceMappingURL=get-syllabus.js.map

package/build/tools/get-todo.js

@@ -0,0 +1,61 @@
+import { GetTodoSchema } from "./schemas.js";
+import { toolResponse, sanitizeError } from "./tool-helpers.js";
+import { collectDueItems } from "./get-upcoming-due-dates.js";
+const DAY = 86_400_000;
+const DONE = new Set(["submitted", "graded"]);
+const TO_DO = new Set(["not_submitted", "draft"]);
+const LATER = new Set(["not_open_yet"]);
+function hoursUntil(item, now) {
+    return Math.round((new Date(item.dueDate).getTime() - now) / 3_600_000);
+}
+export function buildTodo(unsorted, now = Date.now()) {
+    const annotate = (item) => ({ ...item, hoursUntilDue: hoursUntil(item, now) });
+    const due = (item) => new Date(item.dueDate).getTime();
+    const items = [...unsorted].sort((a, b) => due(a) - due(b));
+    const overdue = items.filter((i) => TO_DO.has(i.submissionStatus) && due(i) < now).map(annotate);
+    const toDo = items.filter((i) => TO_DO.has(i.submissionStatus) && due(i) >= now).map(annotate);
+    const notOpenYet = items.filter((i) => LATER.has(i.submissionStatus)).map(annotate);
+    const checkYourself = items
+        .filter((i) => !DONE.has(i.submissionStatus) && !TO_DO.has(i.submissionStatus) && !LATER.has(i.submissionStatus) && due(i) >= now)
+        .map(annotate);
+    const alreadyDone = items.filter((i) => DONE.has(i.submissionStatus)).map((i) => ({
+        title: i.title,
+        courseName: i.courseName,
+        dueDate: i.dueDate,
+        submissionStatus: i.submissionStatus,
+        submittedDate: i.submittedDate,
+    }));
+    return {
+        generatedAt: new Date(now).toISOString(),
+        guidance: "Recommend from doNow first (soonest due first), then overdue if it can still be submitted. " +
+            "Never recommend alreadyDone items. notOpenYet cannot be submitted until its startDate. " +
+            "checkYourself items (quizzes, restricted dropboxes) have unknown completion; ask the user. Dates are UTC.",
+        doNow: toDo,
+        overdue,
+        notOpenYet,
+        checkYourself,
+        alreadyDone,
+    };
+}
+export function registerGetTodo(server, apiClient, config) {
+    server.registerTool("get_todo", {
+        title: "What To Do Now",
+        description: "Prioritized to-do list across all courses: unfinished work due soon, recently overdue work, " +
+            "work not open yet, items to double-check (quizzes), and work already submitted. " +
+            "Use this first when the user asks what to work on, what's left, or what they should do now.",
+        inputSchema: GetTodoSchema,
+    }, async (args) => {
+        try {
+            const { daysAhead, includeOverdueDays } = GetTodoSchema.parse(args);
+            const items = await collectDueItems(apiClient, config, {
+                fromMs: -includeOverdueDays * DAY,
+                toMs: daysAhead * DAY,
+            });
+            return toolResponse(buildTodo(items));
+        }
+        catch (error) {
+            return sanitizeError(error);
+        }
+    });
+}
+//# sourceMappingURL=get-todo.js.map

package/build/tools/get-upcoming-due-dates.js

@@ -0,0 +1,138 @@
+import { DEFAULT_CACHE_TTLS } from "../api/index.js";
+import { GetUpcomingDueDatesSchema } from "./schemas.js";
+import { toolResponse, sanitizeError } from "./tool-helpers.js";
+import { log } from "../utils/logger.js";
+import { applyCourseFilter } from "../utils/course-filter.js";
+import { assignmentUrl, quizUrl } from "../utils/deep-links.js";
+import { fetchSubmissionStatus } from "./submission-status.js";
+function unwrapList(raw) {
+    return Array.isArray(raw) ? raw : (raw?.Objects ?? []);
+}
+async function resolveCourses(apiClient, config, courseId) {
+    let items = [];
+    try {
+        const response = await apiClient.get(apiClient.lp("/enrollments/myenrollments/?orgUnitTypeId=3&isActive=true"), { ttl: DEFAULT_CACHE_TTLS.enrollments });
+        items = response.Items ?? [];
+    }
+    catch (error) {
+        if (!courseId)
+            throw error;
+        log("DEBUG", "due dates: could not fetch enrollments for course name", error);
+    }
+    if (courseId) {
+        const match = items.find((item) => item.OrgUnit.Id === courseId);
+        return [{ id: courseId, name: match?.OrgUnit.Name ?? null }];
+    }
+    const filtered = applyCourseFilter(items.map((item) => ({
+        id: item.OrgUnit.Id,
+        name: item.OrgUnit.Name,
+        code: item.OrgUnit.Code,
+        isActive: item.Access.IsActive,
+        canAccess: item.Access.CanAccess,
+    })), config.courseFilter);
+    return filtered.map((course) => ({ id: course.id, name: course.name }));
+}
+async function fetchCourseDueItems(apiClient, baseUrl, course) {
+    const [dropboxResult, quizResult] = await Promise.allSettled([
+        apiClient.get(apiClient.le(course.id, "/dropbox/folders/"), { ttl: DEFAULT_CACHE_TTLS.assignments }),
+        apiClient.get(apiClient.le(course.id, "/quizzes/"), { ttl: DEFAULT_CACHE_TTLS.assignments }),
+    ]);
+    const items = [];
+    if (dropboxResult.status === "fulfilled") {
+        for (const folder of unwrapList(dropboxResult.value)) {
+            if (folder.IsHidden === true || !folder.DueDate)
+                continue;
+            items.push({
+                type: "assignment",
+                id: folder.Id,
+                title: folder.Name,
+                courseId: course.id,
+                courseName: course.name,
+                dueDate: folder.DueDate,
+                startDate: folder.Availability?.StartDate ?? null,
+                endDate: folder.Availability?.EndDate ?? null,
+                url: assignmentUrl(baseUrl, course.id, folder.Id),
+                folder,
+            });
+        }
+    }
+    else {
+        // 403 for past courses and similar: keep the other courses.
+        log("DEBUG", `due dates: failed to fetch dropbox folders for course ${course.id}`, dropboxResult.reason);
+    }
+    if (quizResult.status === "fulfilled") {
+        for (const quiz of unwrapList(quizResult.value)) {
+            if (quiz.IsActive === false)
+                continue;
+            // Many instructors set only an End Date, which is the effective deadline.
+            const dueDate = quiz.DueDate ?? quiz.EndDate;
+            if (!dueDate)
+                continue;
+            items.push({
+                type: "quiz",
+                id: quiz.QuizId,
+                title: quiz.Name,
+                courseId: course.id,
+                courseName: course.name,
+                dueDate,
+                startDate: quiz.StartDate ?? null,
+                endDate: quiz.EndDate ?? null,
+                url: quizUrl(baseUrl, course.id, quiz.QuizId),
+            });
+        }
+    }
+    else {
+        log("DEBUG", `due dates: failed to fetch quizzes for course ${course.id}`, quizResult.reason);
+    }
+    return items;
+}
+export async function collectDueItems(apiClient, config, options) {
+    const now = Date.now();
+    const courses = await resolveCourses(apiClient, config, options.courseId);
+    const results = await Promise.allSettled(courses.map((course) => fetchCourseDueItems(apiClient, config.baseUrl, course)));
+    const items = results.flatMap((result) => {
+        if (result.status === "fulfilled")
+            return result.value;
+        log("DEBUG", "due dates: skipping course after fetch failure", result.reason);
+        return [];
+    });
+    const inWindow = items
+        .filter((item) => {
+        const due = new Date(item.dueDate).getTime();
+        return Number.isFinite(due) && due >= now + options.fromMs && due <= now + options.toMs;
+    })
+        .sort((a, b) => new Date(a.dueDate).getTime() - new Date(b.dueDate).getTime());
+    return Promise.all(inWindow.map(async ({ folder, ...item }) => {
+        if (!folder) {
+            return { ...item, submitted: null, submissionStatus: "unknown", statusNote: "Brightspace does not show students their quiz attempts.", submittedDate: null };
+        }
+        const summary = await fetchSubmissionStatus(apiClient, item.courseId, folder);
+        return {
+            ...item,
+            submitted: summary.submitted,
+            submissionStatus: summary.submissionStatus,
+            ...(summary.statusNote ? { statusNote: summary.statusNote } : {}),
+            submittedDate: summary.submission?.submittedDate ?? null,
+        };
+    }));
+}
+export function registerGetUpcomingDueDates(server, apiClient, config) {
+    server.registerTool("get_upcoming_due_dates", {
+        title: "Get Upcoming Due Dates",
+        description: "Upcoming due dates across all courses, with whether each assignment is already submitted " +
+            "(submissionStatus: submitted, graded, draft, not_submitted, not_open_yet, closed, past_due, restricted, unknown). " +
+            "Dates are UTC ISO strings; convert to the user's local time. Use for deadlines and what's due.",
+        inputSchema: GetUpcomingDueDatesSchema,
+    }, async (args) => {
+        try {
+            const { daysAhead, courseId } = GetUpcomingDueDatesSchema.parse(args);
+            const upcoming = await collectDueItems(apiClient, config, { fromMs: 0, toMs: daysAhead * 86_400_000, courseId });
+            log("INFO", `get_upcoming_due_dates: ${upcoming.length} items`);
+            return toolResponse(upcoming);
+        }
+        catch (error) {
+            return sanitizeError(error);
+        }
+    });
+}
+//# sourceMappingURL=get-upcoming-due-dates.js.map

package/build/tools/index.js

@@ -0,0 +1,18 @@
+// Tool registration functions - barrel export
+export { registerGetMyCourses } from "./get-my-courses.js";
+export { registerGetUpcomingDueDates } from "./get-upcoming-due-dates.js";
+export { registerGetMyGrades } from "./get-my-grades.js";
+export { registerGetAnnouncements } from "./get-announcements.js";
+export { registerGetAssignments } from "./get-assignments.js";
+export { registerGetAssignmentFiles } from "./get-assignment-files.js";
+export { registerGetCourseContent } from "./get-course-content.js";
+export { registerDownloadFile } from "./download-file.js";
+export { registerGetClasslistEmails } from "./get-classlist-emails.js";
+export { registerGetRoster } from "./get-roster.js";
+export { registerGetSyllabus } from "./get-syllabus.js";
+export { registerGetDiscussions } from "./get-discussions.js";
+export { registerGetTodo } from "./get-todo.js";
+// Re-export shared helpers and schemas for convenience
+export { toolResponse, errorResponse, sanitizeError } from "./tool-helpers.js";
+export * from "./schemas.js";
+//# sourceMappingURL=index.js.map

package/build/tools/schemas.js

@@ -0,0 +1,91 @@
+import { z } from "zod";
+export const GetMyCoursesSchema = z.object({
+    activeOnly: z
+        .boolean()
+        .optional()
+        .describe("Only return currently active courses. Defaults to the server's configured activeOnly setting (true unless overridden)."),
+});
+export const GetUpcomingDueDatesSchema = z.object({
+    daysAhead: z.coerce.number().int().min(1).max(90).default(7).describe("Number of days ahead to look for due dates"),
+    courseId: z.coerce.number().int().positive().optional().describe("Filter to a specific course ID"),
+});
+export const GetTodoSchema = z.object({
+    daysAhead: z.coerce.number().int().min(1).max(60).default(14).describe("How many days ahead to include"),
+    includeOverdueDays: z.coerce.number().int().min(0).max(30).default(3).describe("Also include unfinished work that was due this many days ago"),
+});
+export const GetMyGradesSchema = z.object({
+    courseId: z.coerce.number().int().positive().optional().describe("Course ID to get grades for. If omitted, returns grades for all enrolled courses."),
+});
+export const GetAnnouncementsSchema = z.object({
+    courseId: z.coerce.number().int().positive().optional().describe("Course ID to get announcements for. If omitted, returns recent announcements across all courses."),
+    count: z.coerce.number().int().min(1).max(50).default(10).describe("Maximum number of announcements to return"),
+});
+export const GetAssignmentsSchema = z.object({
+    courseId: z.coerce.number().int().positive().optional()
+        .describe("Course ID to get assignments for. If omitted, returns assignments for all enrolled courses."),
+});
+export const GetCourseContentSchema = z.object({
+    courseId: z.coerce.number().int().positive()
+        .describe("Course ID to get content tree for."),
+    typeFilter: z.enum(["file", "link", "html", "video", "all"]).default("all").optional()
+        .describe("Optional filter to narrow results by content type."),
+    moduleTitle: z.string().optional()
+        .describe("Case-insensitive substring match on module titles. Only returns modules whose title contains this string (e.g. 'Labs', 'Staff', 'Homeworks'). Children of matching modules are included in full."),
+    maxDepth: z.coerce.number().int().min(1).max(10).optional()
+        .describe("Limit recursive depth of the content tree. Depth 1 returns top-level modules with direct children only. Useful for getting a table of contents without all nested content."),
+});
+export const GetClasslistEmailsSchema = z.object({
+    courseId: z.coerce.number().int().positive()
+        .describe("Course ID to get emails for."),
+});
+export const DownloadFileSchema = z.object({
+    courseId: z.coerce.number().int().positive()
+        .describe("Course ID the file belongs to."),
+    topicId: z.coerce.number().int().positive().optional()
+        .describe("Content topic ID to download (for course content files)."),
+    folderId: z.coerce.number().int().positive().optional()
+        .describe("Dropbox folder ID (for submission/feedback file downloads)."),
+    fileId: z.coerce.number().int().positive().optional()
+        .describe("Specific file ID within a dropbox submission."),
+    downloadPath: z.string().min(1)
+        .describe("Absolute path to the directory where the file should be saved."),
+    customFilename: z.string().max(255).optional()
+        .describe("Custom filename for the downloaded file (include extension). If not provided, uses the original filename from Brightspace."),
+});
+export const GetSyllabusSchema = z.object({
+    courseId: z.coerce.number().int().positive()
+        .describe("Course ID to get syllabus for."),
+    downloadPath: z.string().min(1).optional()
+        .describe("Absolute path to the directory where the attachment should be saved."),
+});
+export const GetDiscussionsSchema = z.object({
+    courseId: z.coerce.number().int().positive()
+        .describe("Course ID to get discussion boards for."),
+    forumId: z.coerce.number().int().positive().optional()
+        .describe("Specific forum ID to get topics and posts for. If omitted, returns all forums."),
+    topicId: z.coerce.number().int().positive().optional()
+        .describe("Specific topic ID to get posts for. Requires forumId."),
+});
+export const GetAssignmentFilesSchema = z.object({
+    courseId: z.coerce.number().int().positive()
+        .describe("Course ID whose assignment attachments to look at."),
+    folderId: z.coerce.number().int().positive().optional()
+        .describe("Assignment (dropbox folder) ID. Omit to list every assignment in the course that has attachments."),
+    fileId: z.coerce.number().int().positive().optional()
+        .describe("Attachment file ID to read. Requires folderId. Omit to list the files without reading them."),
+    extractText: z.boolean().default(true)
+        .describe("Extract readable text from the file. Works for PDF, DOCX, XLSX, PPTX, and plain text."),
+    maxChars: z.coerce.number().int().positive().max(100000).default(12000)
+        .describe("Maximum characters of extracted text to return. The response reports whether it was truncated."),
+});
+export const GetRosterSchema = z.object({
+    courseId: z.coerce.number().int().positive()
+        .describe("Course ID to get roster for."),
+    includeStudents: z.boolean().default(false)
+        .describe("Include students in results. Default is instructors and TAs only."),
+    searchTerm: z.string().max(200).optional()
+        .describe("Optional search term to filter by name."),
+    limit: z.coerce.number().int().positive().max(1000).default(100)
+        .describe("Maximum users to return. Default 100. The response reports the true total and whether it was truncated."),
+});
+//# sourceMappingURL=schemas.js.map

package/build/tools/submission-status.js

@@ -0,0 +1,71 @@
+import { DEFAULT_CACHE_TTLS } from "../api/index.js";
+import { log } from "../utils/logger.js";
+const STATUS_NAMES = {
+    0: "not_submitted",
+    1: "submitted",
+    2: "draft",
+    3: "graded",
+};
+export function summarizeSubmission(raw) {
+    const entries = (Array.isArray(raw) ? raw : raw?.Objects ?? []);
+    const entity = entries[0];
+    // Tolerate a flat submission list as well as the documented EntityDropbox shape.
+    const subs = entity?.Submissions ?? entries.filter((e) => e?.SubmissionDate);
+    const latest = subs.reduce((best, s) => (!best || new Date(s.SubmissionDate ?? 0) > new Date(best.SubmissionDate ?? 0) ? s : best), null);
+    const submitted = subs.length > 0 || entity?.Status === 1 || entity?.Status === 3;
+    const status = entity?.Status !== undefined && entity.Status in STATUS_NAMES
+        ? STATUS_NAMES[entity.Status]
+        : submitted ? "submitted" : "not_submitted";
+    return {
+        submitted: status === "draft" ? false : submitted,
+        submissionStatus: status,
+        submission: latest
+            ? {
+                submittedDate: latest.SubmissionDate ?? null,
+                attemptCount: subs.length,
+                files: latest.Files?.map((f) => ({ name: f.FileName, size: f.Size, fileId: f.FileId })) ?? [],
+                comment: latest.Comment?.Text || null,
+            }
+            : null,
+    };
+}
+export function restrictedStatus(folder, now = Date.now()) {
+    const time = (d) => (d ? new Date(d).getTime() : NaN);
+    const start = time(folder.Availability?.StartDate);
+    const end = time(folder.Availability?.EndDate);
+    const due = time(folder.DueDate);
+    let submissionStatus = "restricted";
+    let statusNote = "Brightspace does not allow viewing this submission (release conditions or special access).";
+    if (start > now) {
+        submissionStatus = "not_open_yet";
+        statusNote = `Not assigned yet: opens ${folder.Availability.StartDate}.`;
+    }
+    else if (end < now) {
+        submissionStatus = "closed";
+        statusNote = `Closed on ${folder.Availability.EndDate}.`;
+    }
+    else if (due < now) {
+        submissionStatus = "past_due";
+        statusNote = `Past the due date (${folder.DueDate}).`;
+    }
+    return { submitted: null, submissionStatus, statusNote, submission: null };
+}
+export async function fetchSubmissionStatus(apiClient, courseId, folder) {
+    try {
+        const raw = await apiClient.get(apiClient.le(courseId, `/dropbox/folders/${folder.Id}/submissions/mysubmissions/`), { ttl: DEFAULT_CACHE_TTLS.assignments });
+        return summarizeSubmission(raw);
+    }
+    catch (error) {
+        const status = error?.status;
+        if (status === 404)
+            return summarizeSubmission([]);
+        if (status === 403)
+            return restrictedStatus(folder);
+        // Session and network failures are not "unknown status": let the tool report them.
+        if (status === 401 || status === undefined)
+            throw error;
+        log("DEBUG", `Failed to fetch submissions for folder ${folder.Id}`, error);
+        return { submitted: null, submissionStatus: "unknown", submission: null };
+    }
+}
+//# sourceMappingURL=submission-status.js.map

package/build/tools/tool-helpers.js

@@ -0,0 +1,62 @@
+import { ZodError } from "zod";
+import { ApiError, RateLimitError, NetworkError } from "../api/index.js";
+import { TokenRefreshError } from "../api/errors.js";
+import { AuthRequiredError } from "../auth/authenticator.js";
+import { log } from "../utils/logger.js";
+import { LOGIN_COMMAND } from "../utils/paths.js";
+import { DownloadError, isSafeDetail, } from "../utils/download-errors.js";
+export function toolResponse(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+export function errorResponse(message) {
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+const DOWNLOAD_FAILURE_GUIDANCE = {
+    unsupportedType: "The file's format is not on the allowed download list. " +
+        "Open it from Brightspace in a browser instead.",
+    undetectableType: "The file's format could not be identified, so it was not saved. " +
+        "This usually means Brightspace returned an error page instead of the file.",
+    badFilename: "The name Brightspace gave this file cannot be used on disk. " +
+        "Pass customFilename to choose one yourself.",
+    pathTraversal: "The name Brightspace gave this file pointed outside the download " +
+        "directory and was refused. Pass customFilename to choose one yourself.",
+};
+export function sanitizeError(error) {
+    log("ERROR", "Tool error", error);
+    if (error instanceof AuthRequiredError) {
+        // Messages are written by this package (authenticator.ts), never copied from a remote response.
+        return errorResponse(error.message);
+    }
+    // Checked before NetworkError, which it extends.
+    if (error instanceof TokenRefreshError) {
+        return errorResponse("Brightspace could not renew your session right now. Your saved login was kept. " +
+            "Try again in a few minutes.");
+    }
+    if (error instanceof DownloadError) {
+        const detail = error.detail && isSafeDetail(error.detail) ? ` (detected type: ${error.detail})` : "";
+        return errorResponse(`Could not save the file.${detail} ${DOWNLOAD_FAILURE_GUIDANCE[error.kind]}`);
+    }
+    if (error instanceof ApiError) {
+        if (error.status === 404) {
+            return errorResponse("Resource not found. The course or item may not exist, or you may not have access.");
+        }
+        if (error.status === 401) {
+            return errorResponse(`Your Brightspace session expired and signing in again did not finish. Run \`${LOGIN_COMMAND}\` in a terminal, then try again.`);
+        }
+        if (error.status === 403) {
+            return errorResponse("Access denied. You may not have permission to access this resource.");
+        }
+    }
+    if (error instanceof RateLimitError) {
+        return errorResponse("Rate limited by Brightspace. Please wait a moment and try again.");
+    }
+    if (error instanceof NetworkError) {
+        return errorResponse("Could not connect to Brightspace. Check your internet connection.");
+    }
+    if (error instanceof ZodError) {
+        const issues = error.issues.map((i) => `${i.path.join(".")}: ${i.message}`);
+        return errorResponse(`Invalid input: ${issues.join(", ")}`);
+    }
+    return errorResponse("An unexpected error occurred. Please try again.");
+}
+//# sourceMappingURL=tool-helpers.js.map

package/build/types/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/build/utils/atomic-write.js

@@ -0,0 +1,66 @@
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as fsSync from "node:fs";
+const TRANSIENT_RENAME_ERRORS = new Set(["EPERM", "EBUSY", "EACCES"]);
+const RENAME_ATTEMPTS = 5;
+const RENAME_BASE_DELAY_MS = 50;
+function tempPathFor(target) {
+    return `${target}.tmp-${randomBytes(6).toString("hex")}`;
+}
+function isTransient(error) {
+    const code = error?.code ?? "";
+    return TRANSIENT_RENAME_ERRORS.has(code);
+}
+export async function writeFileAtomic(target, data, options = {}) {
+    const { mode, renameImpl = (from, to) => fs.rename(from, to), sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), } = options;
+    const tmp = tempPathFor(target);
+    await fs.writeFile(tmp, data, mode === undefined ? {} : { mode });
+    // writeFile's mode is subject to the umask; chmod is not.
+    if (mode !== undefined && process.platform !== "win32") {
+        await fs.chmod(tmp, mode);
+    }
+    try {
+        for (let attempt = 1;; attempt++) {
+            try {
+                await renameImpl(tmp, target);
+                return;
+            }
+            catch (error) {
+                if (!isTransient(error) || attempt >= RENAME_ATTEMPTS)
+                    throw error;
+                await sleep(RENAME_BASE_DELAY_MS * attempt);
+            }
+        }
+    }
+    catch (error) {
+        await fs.rm(tmp, { force: true }).catch(() => { });
+        throw error;
+    }
+}
+export function writeFileAtomicSync(target, data, options = {}) {
+    const { mode } = options;
+    const tmp = tempPathFor(target);
+    fsSync.writeFileSync(tmp, data, mode === undefined ? {} : { mode });
+    if (mode !== undefined && process.platform !== "win32") {
+        fsSync.chmodSync(tmp, mode);
+    }
+    try {
+        for (let attempt = 1;; attempt++) {
+            try {
+                fsSync.renameSync(tmp, target);
+                return;
+            }
+            catch (error) {
+                if (!isTransient(error) || attempt >= RENAME_ATTEMPTS)
+                    throw error;
+                // A short synchronous pause; there is no event loop to yield to here.
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, RENAME_BASE_DELAY_MS * attempt);
+            }
+        }
+    }
+    catch (error) {
+        fsSync.rmSync(tmp, { force: true });
+        throw error;
+    }
+}
+//# sourceMappingURL=atomic-write.js.map