@ivanbard/dd2l 0.0.0-stage → 0.1.1

package/src/assignment-workspace.mjs

@@ -0,0 +1,128 @@
+import { htmlContent } from './documents.mjs';
+
+const numeric = value => /^\d+$/.test(String(value ?? ''));
+const visible = value => value && !value.IsHidden && !value.IsLocked && !value.IsDeleted && value.IsPublished !== false;
+const readable = row => row?.data != null && !['denied', 'not_configured'].includes(row.outcome);
+const normalize = value => String(value).toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').trim();
+const date = value => Number.isFinite(Date.parse(value)) ? value : null;
+const fields = new Set(['Name', 'Title', 'Description', 'Instructions', 'Text', 'Html', 'text',
+  'Criteria', 'CriteriaGroups', 'Levels', 'Rubrics', 'Feedback', 'FeedbackText', 'Points', 'MaxPoints', 'Score', 'OutOf']);
+
+// Project only coursework fields: never expose raw responses, retained bytes, or credentials.
+function courseworkText(value, depth = 0) {
+  if (depth > 10 || value == null) return '';
+  if (typeof value === 'string' || typeof value === 'number') return String(value);
+  if (Array.isArray(value)) return value.map(item => courseworkText(item, depth + 1)).filter(Boolean).join('\n');
+  if (!visible(value)) return '';
+  if (value.Html) return htmlContent(value.Html).text;
+  return Object.entries(value).filter(([key]) => fields.has(key))
+    .map(([key, item]) => `${['Points', 'MaxPoints', 'Score', 'OutOf'].includes(key) ? `${key}: ` : ''}${courseworkText(item, depth + 1)}`)
+    .filter(Boolean).join('\n');
+}
+
+function state(row) {
+  if (!row) return 'missing';
+  if (row.outcome === 'denied') return 'inaccessible';
+  if (row.outcome === 'not_configured') return 'not_configured';
+  return readable(row) ? row.outcome === 'available' ? 'available' : 'stale' : 'missing';
+}
+
+export function projectAssignments(rows, courses, origin) {
+  const assignments = [];
+  for (const course of courses) {
+    const scoped = rows.filter(row => String(row.course) === course.id);
+    const listing = scoped.find(row => row.category === 'assignments');
+    if (!readable(listing) || !Array.isArray(listing.data)) continue;
+    for (const folder of listing.data.filter(item => numeric(item.Id) && visible(item))) {
+      const id = String(folder.Id);
+      const related = scoped.filter(row => {
+        const path = row.key || '';
+        return path.match(/\/dropbox\/folders\/(\d+)(?:\/|$)/)?.[1] === id ||
+          (row.category === 'rubrics' && new URL(path, origin).searchParams.get('objectId') === id);
+      });
+      const detail = related.find(row => row.category === 'assignment_detail');
+      if (readable(detail) && !visible(detail.data)) continue;
+      const data = { ...folder, ...(readable(detail) ? detail.data : {}) };
+      const url = `${origin}/d2l/lms/dropbox/user/folder_submit_files.d2l?db=${id}&ou=${course.id}`;
+      const record = (kind, title, row, text = readable(row) ? courseworkText(row.data) : '') => ({
+        id: `${course.id}:${id}:${kind}:${row?.key || title}`, resourceKey: row?.key || null, course: course.id, courseName: course.name,
+        category: kind, title, text: text.length > 100_000 ? `${text.slice(0, 100_000)}\n[Excerpt truncated. Open Brightspace for the full source.]` : text, status: state(row),
+        stale: state(row) === 'stale', lastSuccess: row?.last_success || null, checkedAt: row?.checked_at || null, url,
+      });
+      const instructions = courseworkText(data.Instructions) || courseworkText(data.Description);
+      const records = [record('instructions', 'Instructions and deliverables', readable(detail) ? detail : listing, instructions)];
+      const rubric = related.find(row => row.category === 'rubrics');
+      const embedded = data.Assessment?.Rubrics;
+      records.push(rubric ? record('rubric', 'Rubric', rubric) : embedded?.length
+        ? record('rubric', 'Rubric', readable(detail) ? detail : listing, courseworkText(embedded))
+        : record('rubric', 'Rubric', null));
+      const submissions = related.find(row => row.category === 'own_submissions');
+      // A complete empty response establishes no submissions; a missing read does not.
+      let submissionStatus = 'Submission status not retrieved';
+      if (readable(submissions) && Array.isArray(submissions.data)) {
+        const count = submissions.data
+          .reduce((total, entity) => total + (entity.Submissions?.length || 0), 0);
+        submissionStatus = count ? `${count} cached submission${count === 1 ? '' : 's'}` : 'No submissions in the cached response';
+        if (state(submissions) === 'stale') submissionStatus += ' · stale';
+      } else if (state(submissions) === 'inaccessible') submissionStatus = 'Submission status inaccessible';
+      const feedback = related.find(row => row.category === 'own_feedback');
+      records.push(record('feedback', 'Your feedback', feedback));
+      for (const attachment of data.Attachments || []) {
+        if (!numeric(attachment.FileId) || !visible(attachment)) continue;
+        const file = related.find(row => row.category === 'assignment_file' && row.key.endsWith(`/attachments/${attachment.FileId}`));
+        records.push(record('attachment', attachment.FileName || attachment.Name || `Attachment ${attachment.FileId}`, file));
+      }
+      assignments.push({ id, course: course.id, courseName: course.name, title: data.Name || `Assignment ${id}`,
+        dueDate: date(data.DueDate), startDate: date(data.Availability?.StartDate || data.StartDate),
+        endDate: date(data.Availability?.EndDate || data.EndDate), submissionStatus, url,
+        stale: state(listing) === 'stale' || state(detail) === 'stale', lastSuccess: (readable(detail) ? detail : listing).last_success || null,
+        records });
+    }
+  }
+  return assignments;
+}
+
+export function assignmentWorkspace(inventory, query, course = '', assignmentId = '') {
+  const normalized = normalize(query);
+  const number = normalized.match(/\b(?:assignment|assign|a|hw|homework)\s*0*(\d+)\b/)?.[1];
+  const courseMatches = inventory.courses.filter(item => {
+    const codes = [...normalize(item.name).matchAll(/\b([a-z]{2,})\s*(\d{3,4})\b/g)];
+    return codes.some(code => new RegExp(`\\b${code[1]}\\s*${code[2]}\\b`).test(normalized));
+  });
+  // An explicitly named course takes precedence over context from the previous request.
+  const namedCourses = courseMatches.map(item => item.id);
+  const unknownCourse = !namedCourses.length && /\b(?!assignment\b|homework\b)[a-z]{2,}\s*\d{3,4}\b/.test(normalized);
+  let candidates = (inventory.assignments || []).filter(item => namedCourses.length ? namedCourses.includes(item.course) : !course || item.course === course);
+  if (unknownCourse && number) candidates = [];
+  if (number) candidates = candidates.filter(item => normalize(item.title).match(/\b(?:assignment|assign|a|hw|homework)\s*0*(\d+)\b/)?.[1] === number);
+  else {
+    const titles = candidates.filter(item => normalized.includes(normalize(item.title)));
+    if (titles.length) candidates = titles;
+    else if (assignmentId && !namedCourses.length && !/\b(?:assignment|homework|quiz|test|exam)\b/.test(normalized)) candidates = candidates.filter(item => item.id === assignmentId);
+    else if (!/\b(?:assignment|homework)\b/.test(normalized)) return null;
+  }
+  if (candidates.length > 1 && assignmentId && course) {
+    const selected = candidates.filter(item => item.id === assignmentId && item.course === course);
+    if (selected.length) candidates = selected;
+  }
+  const choices = candidates.map(({ id, course, courseName, title }) => ({ id, course, courseName, title }));
+  if (candidates.length !== 1) return { status: candidates.length ? 'choose' : 'missing', choices };
+  const target = candidates[0];
+  const title = normalize(target.title);
+  const shortTitle = title.match(/\b(?:assignment|homework|hw)\s*\d+\b/)?.[0] || title;
+  const instructions = normalize(target.records.find(record => record.category === 'instructions')?.text || '');
+  const supporting = inventory.sources.filter(source => source.course === target.course &&
+    ['content', 'content_file', 'linked_content', 'syllabus_source', 'announcements'].includes(source.category))
+    .map(source => {
+      const name = normalize(source.title), body = normalize(source.text);
+      const mentions = value => (` ${value} `).includes(` ${shortTitle} `);
+      const reason = mentions(name) || mentions(body) ? 'Mentions this assignment'
+        : name.length > 8 && instructions.includes(name) ? 'Referenced in the assignment instructions'
+          : source.category === 'syllabus_source' ? 'Course policy reference' : '';
+      return { ...source, status: source.stale ? 'stale' : 'available', reason };
+    }).filter(source => source.reason).sort((a, b) => (a.reason === 'Course policy reference') - (b.reason === 'Course policy reference')).slice(0, 6);
+  const submitting = /\b(submit|submission|ready|hand in)\b/.test(normalized);
+  const order = submitting || /\b(rubric|criterion|criteria)\b/.test(normalized) ? ['rubric', 'instructions', 'attachment', 'feedback'] : ['instructions', 'attachment', 'rubric', 'feedback'];
+  const records = [...target.records].sort((a, b) => order.indexOf(a.category) - order.indexOf(b.category));
+  return { status: 'resolved', ...target, records, supporting, intent: submitting ? 'submit' : 'work' };
+}

package/src/canvas.mjs

@@ -0,0 +1,17 @@
+import { randomBytes } from 'node:crypto';
+import { canvasRuntime } from '../ui/canvas-runtime.js';
+import { validCanvasState } from '../ui/canvas-contract.js';
+
+export function canvasDocument() {
+  const nonce = randomBytes(24).toString('base64');
+  return {
+    policy: `sandbox allow-scripts; default-src 'none'; script-src 'nonce-${nonce}' 'unsafe-eval'; worker-src blob:; style-src 'unsafe-inline'; img-src data:; connect-src 'none'; frame-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'self'`,
+    html: `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><style>
+      :root { color-scheme: dark; font-family: system-ui,sans-serif; color:#e8e9e6; background:#222; }
+      * { box-sizing:border-box; } body { margin:0; overflow-wrap:anywhere; } #canvas { padding:20px; }
+      button,input,select,textarea { font:inherit; } button { cursor:pointer; } :focus-visible { outline:2px solid #9bd1df; outline-offset:3px; }
+      pre { white-space:pre-wrap; } svg { max-width:100%; } input,textarea,select { max-width:100%; }
+      @media(prefers-reduced-motion:reduce) { *,*::before,*::after { animation:none!important; transition:none!important; } }
+      </style><style id="generated-style"></style></head><body><main id="canvas"></main><script nonce="${nonce}">(${canvasRuntime.toString()})(${validCanvasState.toString()});</script></body></html>`,
+  };
+}

package/src/cli-banner.mjs

@@ -0,0 +1,58 @@
+import { styleText } from 'node:util';
+
+const bayer = [
+  [0, 32, 8, 40, 2, 34, 10, 42],
+  [48, 16, 56, 24, 50, 18, 58, 26],
+  [12, 44, 4, 36, 14, 46, 6, 38],
+  [60, 28, 52, 20, 62, 30, 54, 22],
+  [3, 35, 11, 43, 1, 33, 9, 41],
+  [51, 19, 59, 27, 49, 17, 57, 25],
+  [15, 47, 7, 39, 13, 45, 5, 37],
+  [63, 31, 55, 23, 61, 29, 53, 21],
+];
+const dots = [[0, 1, 2, 6], [3, 4, 5, 7]];
+const glyphs = {
+  d: ['00001', '00001', '01111', '10001', '10001', '10001', '01111'],
+  2: ['01110', '10001', '00001', '00010', '00100', '01000', '11111'],
+  l: ['11000', '01000', '01000', '01000', '01000', '01000', '00110'],
+};
+const wordmark = Array.from({ length: 8 }, (_, y) =>
+  [...'dd2l'].map(letter => glyphs[letter][y] ?? '00000').join('0') + '0');
+
+function raster(width, row, pixel) {
+  return Array.from({ length: width }, (_, cell) => {
+    let mask = 0;
+    for (let column = 0; column < 2; column++) {
+      for (let dot = 0; dot < 4; dot++) {
+        if (pixel(cell * 2 + column, row * 4 + dot)) mask |= 1 << dots[column][dot];
+      }
+    }
+    // Keep even the dense areas on the dot grid to avoid a block-to-Braille seam.
+    return String.fromCodePoint(0x2800 + mask);
+  }).join('');
+}
+
+function bar(width, row, mirrored = false) {
+  return raster(width, row, (x, y) => {
+    if (mirrored) x = width * 2 - 1 - x;
+    const t = Math.min(1, (x + 0.5) / (width * 2 * 0.85));
+    const density = t * t * (3 - 2 * t);
+    return density > (bayer[y][x % 8] + 0.5) / 64;
+  });
+}
+
+export function renderBanner(columns = 80) {
+  // Leave the last column free so the terminal doesn't wrap the banner.
+  const width = Math.max(1, columns - 1);
+  if (width < 31) {
+    const title = 'dd2l'.slice(0, width);
+    return ' '.repeat(Math.floor((width - title.length) / 2)) + styleText('bold', title);
+  }
+  const labelWidth = wordmark[0].length / 2;
+  const barWidth = Math.min(20, Math.floor((width - labelWidth - 4) / 2));
+  const padding = ' '.repeat(Math.floor((width - barWidth * 2 - labelWidth - 4) / 2));
+  return [0, 1].map(row => {
+    const label = raster(labelWidth, row, (x, y) => wordmark[y][x] === '1');
+    return `${padding}${styleText('blueBright', bar(barWidth, row))}  ${label}  ${styleText('blueBright', bar(barWidth, row, true))}`;
+  }).join('\n');
+}

package/src/cli.mjs

@@ -0,0 +1,142 @@
+import { mkdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { select, text, isCancel, cancel, log, outro } from '@clack/prompts';
+import { BrightspaceClient, SCHOOL, schoolOrigin } from './client.mjs';
+import { Session, login, atomicWrite } from './session.mjs';
+import { Store, lock } from './store.mjs';
+import { Connector, sync } from './connector.mjs';
+import { runApp } from './app-runner.mjs';
+import { renderBanner } from './cli-banner.mjs';
+
+const help = `dd2l — direct, read-only Brightspace connector (Windows, Node 24+)
+
+dd2l setup                          Guided school sign-in, then open the app and sync
+dd2l start                          Open the app and sync with your saved school session
+dd2l login                          Open Chrome for school sign-in and MFA
+dd2l courses                        List your course IDs and names
+dd2l audit [--course ID]             Audit one course (defaults to an accessible active course)
+dd2l audit --all                    Advance the all-course pass (five courses per run)
+dd2l syllabus [--course ID]          Retrieve syllabus/course-information sources and text
+dd2l sync [--course ID]              Repeat that audit every 15 minutes until Ctrl+C
+dd2l sync --all                     Rotate through all accessible courses in bounded passes
+dd2l status                         Show coverage and last successful reads
+dd2l logout                         Delete dd2l's session and local inventory
+
+Without a global install: npx @ivanbard/dd2l <command>.
+From source: npm start -- <command>, or npm run setup.
+
+audit/sync: --from ISO --to ISO      Calendar window (default: past 30 / next 120 days)
+syllabus: --course ID               Choose the course without changing the sync selection
+
+Data: %LOCALAPPDATA%\\dd2l (session protected for this Windows user; inventory is private local data).
+ChatGPT is optional in the UI; connector commands make no external model calls.`;
+
+async function main() {
+  const { positionals, values } = parseArgs({ allowPositionals: true, options: {
+    course: { type: 'string' }, from: { type: 'string' }, to: { type: 'string' }, all: { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
+  } });
+  const command = positionals[0];
+  if (values.help || !command) { console.log(help); return; }
+  if (positionals.length > 1 || !['setup', 'start', 'login', 'courses', 'audit', 'syllabus', 'sync', 'status', 'logout'].includes(command)) throw new Error('Unknown command. Run dd2l --help.');
+  if (!['audit', 'sync', 'syllabus'].includes(command) && Object.keys(values).length) throw new Error('Date/course options apply only to audit, syllabus and sync.');
+  if (command === 'syllabus' && (values.from || values.to)) throw new Error('Calendar date options apply only to audit and sync.');
+  if (values.all && (!['audit', 'sync'].includes(command) || values.course)) throw new Error('--all applies to audit/sync and cannot be combined with --course.');
+  if (process.platform !== 'win32' || !process.env.LOCALAPPDATA) throw new Error('This first connector requires Windows with LOCALAPPDATA.');
+  const directory = join(process.env.LOCALAPPDATA, 'dd2l');
+  let selectedOrigin;
+  if (['setup', 'start'].includes(command)) console.log(`\n${renderBanner(process.stdout.columns)}\n`);
+  if (command === 'setup') {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) throw new Error('Run dd2l setup in an interactive terminal.');
+    log.info('Read-only access. Coursework is stored unencrypted on this PC.');
+    const school = await select({ message: 'Select your school', options: [
+      { value: SCHOOL, label: 'Queen\'s University', hint: 'onQ · connect and collect coursework' },
+      { value: 'not-listed', label: 'My school isn\'t listed', hint: 'enter a Brightspace URL' },
+    ] });
+    if (isCancel(school)) { cancel('Setup cancelled. No school connection was made.'); return; }
+    if (school === 'not-listed') {
+      const url = await text({ message: 'Your school\'s Brightspace URL', placeholder: 'your-school.brightspace.com',
+        validate: value => { try { schoolOrigin(value); } catch (error) { return error.message; } },
+      });
+      if (isCancel(url)) { cancel('Setup cancelled. No school connection was made.'); return; }
+      selectedOrigin = schoolOrigin(url);
+      log.info('Custom school · compatibility has not been verified.');
+      log.info('Help add your school: open an issue with its name and URL.\nhttps://github.com/ivanbard/dd2l/issues/new');
+    } else selectedOrigin = school;
+  }
+  await mkdir(directory, { recursive: true });
+  // Status is read-only and can inspect a running worker without taking its lock.
+  const release = command === 'status' ? async () => {} : await lock(directory);
+  let store;
+  try {
+    store = new Store(directory);
+    const origin = ['status', 'logout'].includes(command) ? SCHOOL : schoolOrigin(selectedOrigin ?? store.getMeta('school_origin') ?? SCHOOL);
+    const session = new Session(directory, { origin });
+    const client = new BrightspaceClient(session, { origin });
+    const connector = new Connector(client, store);
+    if (command === 'login' || command === 'setup') {
+      if (command === 'setup') {
+        log.step(`Sign in to ${origin === SCHOOL ? 'Queen\'s onQ' : new URL(origin).hostname}`);
+        log.info('Complete sign-in and MFA in Chrome. Your password is never saved.\nSession credentials are encrypted for your Windows account.');
+      }
+      await login(session, client, { expectedAccount: store.getMeta('account'),
+        ...(command === 'setup' ? { onProgress: () => {} } : {}) });
+      store.meta('school_origin', origin);
+      if (command === 'setup') log.success('School connected · identity verified');
+      store.meta('state', { state: 'ready', updatedAt: new Date().toISOString() });
+    }
+    if (command === 'start' || command === 'setup') {
+      if (command === 'setup') log.info(`Coursework and grades will be cached in:\n${directory}`);
+      await runApp(connector, { onUpdate: async summary => {
+        await atomicWrite(join(directory, 'summary.json'), JSON.stringify(summary, null, 2));
+      } });
+      outro('dd2l stopped. Your cached coursework is saved.');
+    } else if (command === 'courses') {
+      const { enrollments } = await connector.courses();
+      console.log(JSON.stringify({ complete: enrollments.complete, courses: enrollments.data.map(item => ({
+        id: item.OrgUnit?.Id, name: item.OrgUnit?.Name, active: item.Access?.IsActive, canAccess: item.Access?.CanAccess,
+      })) }, null, 2));
+    } else if (command === 'syllabus') {
+      const summary = await connector.syllabus(values);
+      await atomicWrite(join(directory, 'syllabus-summary.json'), JSON.stringify(summary, null, 2));
+      console.log(JSON.stringify(summary, null, 2));
+    } else if (command === 'audit' || command === 'sync') {
+      const report = async summary => {
+        await atomicWrite(join(directory, 'summary.json'), JSON.stringify(summary, null, 2));
+        console.log(JSON.stringify(summary, null, 2));
+      };
+      if (command === 'audit') await report(await connector.audit(values));
+      else {
+        const controller = new AbortController();
+        const stop = () => controller.abort();
+        process.on('SIGINT', stop);
+        process.on('SIGTERM', stop);
+        try { await sync(connector, values, { signal: controller.signal, onUpdate: report }); }
+        finally { process.off('SIGINT', stop); process.off('SIGTERM', stop); }
+      }
+    } else if (command === 'status') console.log(JSON.stringify(store.status(), null, 2));
+    else if (command === 'logout') {
+      await rm(session.path, { force: true });
+      await rm(join(directory, 'summary.json'), { force: true });
+      await rm(join(directory, 'syllabus-summary.json'), { force: true });
+      store.clear();
+      store.close();
+      store = null;
+      for (const name of ['inventory.sqlite', 'inventory.sqlite-wal', 'inventory.sqlite-shm']) {
+        await rm(join(directory, name), { force: true });
+      }
+      console.log('dd2l session and inventory removed. School sign-in on other apps is unchanged.');
+    }
+  } catch (error) {
+    if (store && error.code === 'needs_login') store.meta('state', { state: 'needs_login', updatedAt: new Date().toISOString() });
+    if (error.code === 'needs_login' && ['start', 'setup'].includes(command)) error.message += ' Run dd2l setup to sign in and restart.';
+    throw error;
+  } finally { store?.close(); await release(); }
+}
+
+main().catch(error => {
+  const message = `${error.code || 'error'}: ${error.message}`;
+  if (['setup', 'start'].includes(process.argv[2]) && process.stdout.isTTY) log.error(message);
+  else console.error(message);
+  process.exitCode = 1;
+});

package/src/client.mjs

@@ -0,0 +1,150 @@
+export const SCHOOL = 'https://onq.queensu.ca';
+
+export function schoolOrigin(value) {
+  const message = 'Enter a valid Brightspace address (HTTPS only, no embedded username or password).';
+  if (typeof value !== 'string' || /[\u0000-\u0020\u007f\\]/.test(value.trim())) throw new Error(message);
+  const address = value.trim().replace(/^\/\//, '');
+  let url;
+  try { url = new URL(/^[a-z][a-z\d+.-]*:\/\//i.test(address) ? address : `https://${address}`); } catch { throw new Error(message); }
+  if (url.protocol !== 'https:' || url.username || url.password) throw new Error(message);
+  return url.origin;
+}
+
+export class AccessError extends Error {
+  constructor(code, message, { status, retryAfter = 0 } = {}) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.retryAfter = retryAfter;
+  }
+}
+
+// Never attach response bodies, headers, or credential-bearing URLs to errors.
+export async function request(url, options = {}, fetchImpl = fetch) {
+  options.signal?.throwIfAborted();
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      ...options, redirect: 'manual', signal: options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000),
+    });
+  } catch {
+    options.signal?.throwIfAborted();
+    throw new AccessError('retry_wait', 'Network request failed or timed out.');
+  }
+  return checkedResponse(response, url);
+}
+
+export function checkedResponse(response, url) {
+  if (response.status === 401) throw new AccessError('needs_login', 'School sign-in is required.', { status: 401 });
+  if (response.status >= 300 && response.status < 400) {
+    const target = new URL(response.headers.get('location') || '/', url);
+    const login = /\/d2l\/(?:login|lms\/auth)/i.test(target.pathname) || target.hostname === 'login.microsoftonline.com';
+    throw new AccessError(login ? 'needs_login' : 'redirect', login ? 'School sign-in is required.' : 'Unexpected redirect was not followed.', { status: response.status });
+  }
+  if (response.status === 403) throw new AccessError('denied', 'Brightspace denied access to this resource.', { status: 403 });
+  if (response.status === 404) throw new AccessError('unavailable', 'Resource or API route is unavailable; absence is not established.', { status: 404 });
+  if (response.status === 429 || response.status >= 500) {
+    const raw = response.headers.get('retry-after');
+    const seconds = raw && /^\d+$/.test(raw) ? Number(raw) : Math.max(0, (Date.parse(raw) - Date.now()) / 1000);
+    throw new AccessError('retry_wait', `Brightspace returned HTTP ${response.status}.`, {
+      status: response.status, retryAfter: Number.isFinite(seconds) ? seconds * 1000 : 0,
+    });
+  }
+  if (!response.ok) throw new AccessError('failed', `Brightspace returned HTTP ${response.status}.`, { status: response.status });
+  return response;
+}
+
+export async function readJson(response) {
+  const text = await response.text();
+  if (!/\bapplication\/(?:[\w.+-]*\+)?json\b/i.test(response.headers.get('content-type') || '')) {
+    if (text.includes('/d2l/login?sessionExpired=1')) throw new AccessError('needs_login', 'School session has expired.');
+    throw new AccessError('invalid_response', 'Expected JSON; received a different response format.');
+  }
+  try { return JSON.parse(text); }
+  catch { throw new AccessError('invalid_response', 'Brightspace returned invalid JSON.'); }
+}
+
+export function apiUrl(origin, path) {
+  const url = new URL(path, origin);
+  if (url.origin !== origin || url.username || url.password || url.hash || !url.pathname.startsWith('/d2l/api/')) {
+    throw new AccessError('invalid_link', 'Refused a link outside this school’s API.');
+  }
+  return url;
+}
+
+export class BrightspaceClient {
+  constructor(session, { origin = SCHOOL, fetchImpl = fetch, signal } = {}) {
+    this.session = session;
+    this.origin = schoolOrigin(origin);
+    this.fetch = fetchImpl;
+    this.signal = signal;
+  }
+
+  async versions() {
+    const data = await readJson(await request(`${this.origin}/d2l/api/versions/`, { signal: this.signal }, this.fetch));
+    const versions = {};
+    for (const product of ['lp', 'le']) {
+      const value = data?.find?.(item => item.ProductCode === product)?.LatestVersion;
+      if (!/^\d+\.\d+$/.test(value || '')) throw new AccessError('invalid_response', 'Missing supported API versions.');
+      versions[product] = value;
+    }
+    return versions;
+  }
+
+  async response(path) {
+    this.signal?.throwIfAborted();
+    const url = apiUrl(this.origin, path);
+    let token = await this.session.token();
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try {
+        return await request(url, { headers: { authorization: `Bearer ${token}`, accept: 'application/json' }, signal: this.signal }, this.fetch);
+      } catch (error) {
+        if (error.code !== 'needs_login' || attempt) throw error;
+        token = await this.session.token(token);
+      }
+    }
+  }
+
+  async get(path) { return readJson(await this.response(path)); }
+
+  async collection(path) {
+    const data = [];
+    const seen = new Set();
+    let next = apiUrl(this.origin, path);
+    let pages = 0;
+    try {
+      while (next) {
+        if (pages === 200 || seen.has(next.href)) throw new AccessError('partial', 'Pagination stopped at a loop or page limit.');
+        seen.add(next.href);
+        const result = await this.get(next.href);
+        pages++;
+        if (Array.isArray(result)) {
+          data.push(...result);
+          next = null;
+        } else if (Array.isArray(result?.Items) && result.PagingInfo && typeof result.PagingInfo.HasMoreItems === 'boolean') {
+          data.push(...result.Items);
+          if (!result.PagingInfo.HasMoreItems) next = null;
+          else {
+            const bookmark = result.PagingInfo.Bookmark;
+            if (typeof bookmark !== 'string' || !bookmark) throw new AccessError('partial', 'More pages were advertised without a bookmark.');
+            next = apiUrl(this.origin, path);
+            next.searchParams.set('bookmark', bookmark);
+          }
+        } else if (Array.isArray(result?.Objects) && Object.hasOwn(result, 'Next')) {
+          data.push(...result.Objects);
+          if (!result.Next) next = null;
+          else if (typeof result.Next !== 'string') throw new AccessError('invalid_response', 'Invalid next-page marker.');
+          else if (/^(?:https?:|\/)/i.test(result.Next)) next = apiUrl(this.origin, result.Next);
+          else {
+            next = apiUrl(this.origin, path);
+            next.searchParams.set('bookmark', result.Next);
+          }
+        } else throw new AccessError('invalid_response', 'Unrecognized collection response; completeness cannot be established.');
+      }
+      return { data, pages, complete: true };
+    } catch (error) {
+      if (!(error instanceof AccessError) || error.code === 'needs_login' || error.status === 429 || !pages) throw error;
+      return { data, pages, complete: false, error: error.code, message: error.message, retryAfter: error.retryAfter };
+    }
+  }
+}