@modulus-learning/lms-canvas 0.0.0-stage → 0.11.1

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * `@modulus-learning/lms-canvas` — the Canvas LMS adapter for Modulus. Pass
+ * `canvasAdapter()` to the host's server configuration.
+ */
+export { canvasAdapter } from './adapter.js';
+export { HttpLtiAgsClient } from './ags-client.js';
+export { CANVAS_CUSTOM_LAUNCH_FIELDS } from './deep-link-fields.js';
+export { classifyScoreSubmissionResponse } from './error-classifier.js';
+export { QuotaGovernor } from './quota-governor.js';
+export { canvasRegistrationConfig, canvasRegistrationEndpoints } from './registration.js';
+export { INSTRUCTOR_LTI_ROLES, isInstructor } from './roles.js';
+export { inspectCanvasTerm, normalizeCanvasTerm } from './term.js';

package/dist/quota-governor.d.ts

@@ -0,0 +1,47 @@
+import type { RateLimitReading } from './types.js';
+/**
+ * Per-platform concurrency governor driven by Canvas's rate-limit quota headers.
+ *
+ * It maps observed quota into an allowed concurrency in `[1, maxConcurrency]`:
+ * roughly "how many requests fit in the remaining quota, minus a reserve". The
+ * quota bucket is shared per developer key, and each `remaining` reading already
+ * reflects the *global* bucket level, so reacting to it implicitly responds to
+ * pressure from other processes too (though independent governors can still
+ * collectively over-target — cross-process coordination is out of scope).
+ *
+ * Design points:
+ * - **Cold start at 1** and ramp up as ample quota is observed.
+ * - **Conservative aggregation**: target off the *minimum* `remaining` and the
+ *   *maximum* `cost` seen in a recent window, since concurrent readings race.
+ * - **Fast down, slow up**: drop to the computed target immediately when quota
+ *   tightens, but raise the effective target by at most +1 per ramp interval.
+ * - **Reset on rate-limit**: a 403 returns the governor to cold start so it
+ *   re-earns concurrency conservatively.
+ *
+ * Pure and synchronous — unit-testable by passing explicit `now` values.
+ */
+export declare class QuotaGovernor {
+    private readonly maxConcurrency;
+    private readonly reserveRequests;
+    private readonly windowMs;
+    private readonly rampIntervalMs;
+    private window;
+    private currentTarget;
+    private lastRaiseAt;
+    constructor(maxConcurrency: number, reserveRequests: number, windowMs: number, rampIntervalMs: number, now?: number);
+    /** Record a quota reading from a submission response. */
+    record(reading: RateLimitReading): void;
+    /** Return the governor to cold start (concurrency 1, no history). */
+    reset(now?: number): void;
+    /** The currently allowed concurrency, in `[1, maxConcurrency]`. */
+    target(now?: number): number;
+    private reconcile;
+    private prune;
+    /**
+     * The concurrency the current readings support, or `undefined` if we can't yet
+     * tell (no readings, or no cost observed). Uses the worst recent `remaining`
+     * and the priciest recent `cost` for safety.
+     */
+    private computedTarget;
+}
+//# sourceMappingURL=quota-governor.d.ts.map

package/dist/quota-governor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quota-governor.d.ts","sourceRoot":"","sources":["../src/quota-governor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAElD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,aAAa;IAMtB,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,cAAc;IARjC,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,aAAa,CAAI;IACzB,OAAO,CAAC,WAAW,CAAQ;IAE3B,YACmB,cAAc,EAAE,MAAM,EACtB,eAAe,EAAE,MAAM,EACvB,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,EACvC,GAAG,GAAE,MAAmB,EAGzB;IAED,yDAAyD;IACzD,MAAM,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAGtC;IAED,qEAAqE;IACrE,KAAK,CAAC,GAAG,GAAE,MAAmB,GAAG,IAAI,CAIpC;IAED,mEAAmE;IACnE,MAAM,CAAC,GAAG,GAAE,MAAmB,GAAG,MAAM,CAGvC;IAED,OAAO,CAAC,SAAS;IAmBjB,OAAO,CAAC,KAAK;IAOb;;;;OAIG;IACH,OAAO,CAAC,cAAc;CAuBvB"}

package/dist/quota-governor.js

@@ -0,0 +1,101 @@
+/**
+ * Per-platform concurrency governor driven by Canvas's rate-limit quota headers.
+ *
+ * It maps observed quota into an allowed concurrency in `[1, maxConcurrency]`:
+ * roughly "how many requests fit in the remaining quota, minus a reserve". The
+ * quota bucket is shared per developer key, and each `remaining` reading already
+ * reflects the *global* bucket level, so reacting to it implicitly responds to
+ * pressure from other processes too (though independent governors can still
+ * collectively over-target — cross-process coordination is out of scope).
+ *
+ * Design points:
+ * - **Cold start at 1** and ramp up as ample quota is observed.
+ * - **Conservative aggregation**: target off the *minimum* `remaining` and the
+ *   *maximum* `cost` seen in a recent window, since concurrent readings race.
+ * - **Fast down, slow up**: drop to the computed target immediately when quota
+ *   tightens, but raise the effective target by at most +1 per ramp interval.
+ * - **Reset on rate-limit**: a 403 returns the governor to cold start so it
+ *   re-earns concurrency conservatively.
+ *
+ * Pure and synchronous — unit-testable by passing explicit `now` values.
+ */
+export class QuotaGovernor {
+    maxConcurrency;
+    reserveRequests;
+    windowMs;
+    rampIntervalMs;
+    window = [];
+    currentTarget = 1;
+    lastRaiseAt;
+    constructor(maxConcurrency, reserveRequests, windowMs, rampIntervalMs, now = Date.now()) {
+        this.maxConcurrency = maxConcurrency;
+        this.reserveRequests = reserveRequests;
+        this.windowMs = windowMs;
+        this.rampIntervalMs = rampIntervalMs;
+        this.lastRaiseAt = now;
+    }
+    /** Record a quota reading from a submission response. */
+    record(reading) {
+        this.window.push(reading);
+        this.reconcile(reading.at);
+    }
+    /** Return the governor to cold start (concurrency 1, no history). */
+    reset(now = Date.now()) {
+        this.window = [];
+        this.currentTarget = 1;
+        this.lastRaiseAt = now;
+    }
+    /** The currently allowed concurrency, in `[1, maxConcurrency]`. */
+    target(now = Date.now()) {
+        this.reconcile(now);
+        return this.currentTarget;
+    }
+    reconcile(now) {
+        this.prune(now);
+        const computed = this.computedTarget();
+        if (computed == null) {
+            // No usable readings (cold start, or window aged out): hold steady.
+            return;
+        }
+        if (computed < this.currentTarget) {
+            // Fast down: tighten immediately.
+            this.currentTarget = computed;
+        }
+        else if (computed > this.currentTarget && now - this.lastRaiseAt >= this.rampIntervalMs) {
+            // Slow up: at most +1 per ramp interval.
+            this.currentTarget += 1;
+            this.lastRaiseAt = now;
+        }
+    }
+    prune(now) {
+        // Readings can arrive slightly out of order under concurrency, so filter the
+        // whole (small) window rather than assuming the head is oldest.
+        const cutoff = now - this.windowMs;
+        this.window = this.window.filter((reading) => reading.at >= cutoff);
+    }
+    /**
+     * The concurrency the current readings support, or `undefined` if we can't yet
+     * tell (no readings, or no cost observed). Uses the worst recent `remaining`
+     * and the priciest recent `cost` for safety.
+     */
+    computedTarget() {
+        if (this.window.length === 0) {
+            return undefined;
+        }
+        let minRemaining = Number.POSITIVE_INFINITY;
+        let maxCost = 0;
+        for (const reading of this.window) {
+            if (reading.remaining < minRemaining) {
+                minRemaining = reading.remaining;
+            }
+            if (reading.cost != null && reading.cost > maxCost) {
+                maxCost = reading.cost;
+            }
+        }
+        if (maxCost <= 0) {
+            return undefined;
+        }
+        const capacity = Math.floor(minRemaining / maxCost) - this.reserveRequests;
+        return Math.min(this.maxConcurrency, Math.max(1, capacity));
+    }
+}

package/dist/registration.d.ts

@@ -0,0 +1,8 @@
+import type { RegistrationConfigInput, RegistrationEndpoints } from '@modulus-learning/lti';
+/**
+ * Canvas registration: the standard Canvas endpoints for an issuer, and the
+ * developer-key configuration an administrator pastes into Canvas.
+ */
+export declare const canvasRegistrationEndpoints: (issuer: string) => RegistrationEndpoints;
+export declare const canvasRegistrationConfig: (input: RegistrationConfigInput) => string;
+//# sourceMappingURL=registration.d.ts.map

package/dist/registration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration.d.ts","sourceRoot":"","sources":["../src/registration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAE3F;;;GAGG;AAEH,eAAO,MAAM,2BAA2B,WAAY,MAAM,KAAG,qBAK3D,CAAA;AAEF,eAAO,MAAM,wBAAwB,UAAW,uBAAuB,KAAG,MAmGzE,CAAA"}

package/dist/registration.js

@@ -0,0 +1,103 @@
+/**
+ * Canvas registration: the standard Canvas endpoints for an issuer, and the
+ * developer-key configuration an administrator pastes into Canvas.
+ */
+export const canvasRegistrationEndpoints = (issuer) => ({
+    authorization_endpoint: new URL('/api/lti/authorize_redirect', issuer).href,
+    authorization_server: new URL('/login/oauth2/token', issuer).href,
+    token_endpoint: new URL('/login/oauth2/token', issuer).href,
+    jwks_uri: new URL('/api/lti/security/jwks', issuer).href,
+});
+export const canvasRegistrationConfig = (input) => {
+    const { title = 'Modulus', description = 'Open Educational Learning', tool_id = 'modulus', platform = 'canvas.instructure.com', } = input;
+    const baseUrl = new URL(input.baseUrl);
+    const config = {
+        title,
+        description,
+        target_link_uri: new URL('/routes/lti/launch', baseUrl).toString(),
+        oidc_initiation_url: new URL('/routes/lti/login', baseUrl).toString(),
+        public_jwk: input.publicJwk,
+        custom_fields: {},
+        scopes: [
+            'https://purl.imsglobal.org/spec/lti-ags/scope/lineitem',
+            'https://purl.imsglobal.org/spec/lti-ags/scope/lineitem.readonly',
+            'https://purl.imsglobal.org/spec/lti-ags/scope/result.readonly',
+            'https://purl.imsglobal.org/spec/lti-ags/scope/score',
+            // 'https://purl.imsglobal.org/spec/lti-nrps/scope/contextmembership.readonly',
+            // 'https://canvas.instructure.com/lti/account_lookup/scope/show',
+            // 'https://canvas.instructure.com/lti-ags/progress/scope/show',
+            // 'https://canvas.instructure.com/lti/page_content/show',
+        ],
+        extensions: [
+            {
+                domain: input.host,
+                tool_id,
+                privacy_level: 'public',
+                platform,
+                settings: {
+                    placements: [
+                        {
+                            text: 'Create a Modulus Assignment',
+                            placement: 'assignment_selection',
+                            message_type: 'LtiDeepLinkingRequest',
+                            custom_fields: {
+                                context_id: '$Context.id',
+                                context_title: '$Context.title',
+                                canvas_course_id: '$Canvas.course.id',
+                                canvas_course_name: '$Canvas.course.name',
+                                modulus_launch_type: 'deep-link',
+                                modulus_deep_link_context: 'assignment',
+                                com_instructure_context_uuid: '$com.instructure.Context.uuid',
+                                com_instructure_context_label: '$com.instructure.contextLabel',
+                                com_instructure_assignment_lti_id: '$com.instructure.Assignment.lti.id',
+                            },
+                            target_link_uri: new URL('/lti/deep-link', baseUrl).toString(),
+                        },
+                        // {
+                        //   text: 'Link to a Modulus activity',
+                        //   placement: 'link_selection',
+                        //   message_type: 'LtiDeepLinkingRequest',
+                        //   custom_fields: {
+                        //     context_id: '$Context.id',
+                        //     context_title: '$Context.title',
+                        //     canvas_course_id: '$Canvas.course.id',
+                        //     canvas_course_name: '$Canvas.course.name',
+                        //     modulus_launch_type: 'deep-link',
+                        //     modulus_deep_link_context: 'standalone',
+                        //     com_instructure_context_label: '$com.instructure.contextLabel',
+                        //   },
+                        //   target_link_uri: new URL('/lti/deep-link', baseUrl).toString(),
+                        // },
+                        // {
+                        //   text: 'Link to a Modulus activity',
+                        //   placement: 'editor_button',
+                        //   message_type: 'LtiDeepLinkingRequest',
+                        //   custom_fields: {
+                        //     context_id: '$Context.id',
+                        //     context_title: '$Context.title',
+                        //     canvas_course_id: '$Canvas.course.id',
+                        //     canvas_course_name: '$Canvas.course.name',
+                        //     modulus_launch_type: 'deep-link',
+                        //     modulus_deep_link_context: 'standalone',
+                        //     com_instructure_context_label: '$com.instructure.contextLabel',
+                        //   },
+                        //   target_link_uri: new URL('/lti/deep-link', baseUrl).toString(),
+                        // },
+                        {
+                            text: 'Modulus Dashboard',
+                            placement: 'course_navigation',
+                            message_type: 'LtiResourceLinkRequest',
+                            windowTarget: '_blank',
+                            custom_fields: {
+                                modulus_launch_type: 'view-dashboard',
+                            },
+                            target_link_uri: new URL('/dashboard', baseUrl).toString(),
+                            required_permissions: 'manage_students',
+                        },
+                    ],
+                },
+            },
+        ],
+    };
+    return JSON.stringify(config, null, 2);
+};

package/dist/roles.d.ts

@@ -0,0 +1,3 @@
+export declare const INSTRUCTOR_LTI_ROLES: string[];
+export declare const isInstructor: (ltiRoles: string[]) => boolean;
+//# sourceMappingURL=roles.d.ts.map

package/dist/roles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.d.ts","sourceRoot":"","sources":["../src/roles.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,oBAAoB,UAkBhC,CAAA;AAED,eAAO,MAAM,YAAY,aAAc,MAAM,EAAE,KAAG,OAQjD,CAAA"}

package/dist/roles.js

@@ -0,0 +1,26 @@
+// LTI roles that should indicate the user is an instructor for our purposes.
+// The LTI spec defines a number of roles without specifying their meaning, so
+// for now this list just includes roles that Canvas appears to use.  See:
+// https://www.imsglobal.org/spec/lti/v1p3/#role-vocabularies
+// https://developerdocs.instructure.com/services/canvas/external-tools/file.canvas_roles
+export const INSTRUCTOR_LTI_ROLES = [
+    // A system / site admin.
+    'http://purl.imsglobal.org/vocab/lis/v2/system/person#SysAdmin',
+    // Not used by Canvas, but maybe appropriate for other platforms?
+    //'http://purl.imsglobal.org/vocab/lis/v2/system/person#Administrator',
+    // An instructor within the overal institution / organization.
+    'http://purl.imsglobal.org/vocab/lis/v2/institution/person#Instructor',
+    // An administrator within the overall institution / organization.
+    'http://purl.imsglobal.org/vocab/lis/v2/institution/person#Administrator',
+    // An instructor within the context (course / assignment) the user launched from.
+    'http://purl.imsglobal.org/vocab/lis/v2/membership#Instructor',
+    // A content developer / designer within the context the user launched from.
+    'http://purl.imsglobal.org/vocab/lis/v2/membership#ContentDeveloper',
+];
+export const isInstructor = (ltiRoles) => {
+    const ltiRoleSet = new Set(ltiRoles);
+    // TODO: Should we also look for the TestUser role?  In Canvas, it indicates
+    // that a Canvas instructor / admin is using the 'view as student' feature.
+    // const isTestUser = ltiRoleSet.has('http://purl.imsglobal.org/vocab/lis/v2/system/person#TestUser')
+    return INSTRUCTOR_LTI_ROLES.some((role) => ltiRoleSet.has(role));
+};

package/dist/term.d.ts

@@ -0,0 +1,11 @@
+import type { CLAIM_CUSTOM, NormalizedTerm, PlatformMessage, TermInspection } from '@modulus-learning/lti';
+/**
+ * Canvas term metadata: the `Canvas.term.*` substitution variables a Modulus
+ * resource link requests (see `deep-link-fields.ts`), inspected with a quality
+ * per field so a fallback can say why it happened.
+ */
+type CustomFields = PlatformMessage[typeof CLAIM_CUSTOM];
+export declare const inspectCanvasTerm: (custom: CustomFields) => TermInspection;
+export declare const normalizeCanvasTerm: (custom: CustomFields) => NormalizedTerm | undefined;
+export {};
+//# sourceMappingURL=term.d.ts.map

package/dist/term.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"term.d.ts","sourceRoot":"","sources":["../src/term.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EAEZ,cAAc,EACd,eAAe,EACf,cAAc,EACf,MAAM,uBAAuB,CAAA;AAG9B;;;;GAIG;AAEH,KAAK,YAAY,GAAG,eAAe,CAAC,OAAO,YAAY,CAAC,CAAA;AAyCxD,eAAO,MAAM,iBAAiB,WAAY,YAAY,KAAG,cAyBxD,CAAA;AAED,eAAO,MAAM,mBAAmB,WAAY,YAAY,KAAG,cAAc,GAAG,SAC5C,CAAA"}

package/dist/term.js

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+const canvasTermDateSchema = z.iso.datetime({ offset: true });
+const inspectCanvasString = (custom, key) => {
+    const value = custom[key];
+    if (value == null) {
+        return { quality: 'missing' };
+    }
+    if (typeof value !== 'string') {
+        return { quality: 'malformed' };
+    }
+    const normalized = value.trim();
+    if (normalized.length === 0) {
+        return { quality: 'empty' };
+    }
+    if (normalized === `$${key}`) {
+        return { quality: 'unexpanded' };
+    }
+    return { value: normalized, quality: 'usable' };
+};
+const inspectCanvasDate = (custom, key) => {
+    const inspected = inspectCanvasString(custom, key);
+    if (inspected.value == null) {
+        return { quality: inspected.quality };
+    }
+    if (!canvasTermDateSchema.safeParse(inspected.value).success) {
+        return { quality: 'malformed' };
+    }
+    return { value: new Date(inspected.value), quality: 'usable' };
+};
+export const inspectCanvasTerm = (custom) => {
+    const externalId = inspectCanvasString(custom, 'Canvas.term.id');
+    const name = inspectCanvasString(custom, 'Canvas.term.name');
+    const startsAt = inspectCanvasDate(custom, 'Canvas.term.startAt');
+    const endsAt = inspectCanvasDate(custom, 'Canvas.term.endAt');
+    const quality = {
+        term_id: externalId.quality,
+        name: name.quality,
+        starts_at: startsAt.quality,
+        ends_at: endsAt.quality,
+    };
+    if (externalId.value == null) {
+        return { quality };
+    }
+    return {
+        term: {
+            external_id: externalId.value,
+            name: name.value,
+            starts_at: startsAt.value,
+            ends_at: endsAt.value,
+        },
+        quality,
+    };
+};
+export const normalizeCanvasTerm = (custom) => inspectCanvasTerm(custom).term;

package/dist/types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A reading of Canvas's rate-limit quota headers, captured from a submission
+ * response. `remaining` is `X-Rate-Limit-Remaining`; `cost` is `X-Request-Cost`
+ * (absent on some responses). `at` is when it was observed (ms epoch). Feeds
+ * the `QuotaGovernor`; core passes it through as an opaque scheduling signal.
+ */
+export type RateLimitReading = {
+    remaining: number;
+    cost?: number;
+    at: number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,EAAE,EAAE,MAAM,CAAA;CACX,CAAA"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@modulus-learning/lms-canvas",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.11.1",
+  "private": false,
+  "description": "The Canvas LMS adapter for Modulus",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "homepage": "https://github.com/Modulus-Learning/app.modulus-learning.org",
+  "bugs": {
+    "url": "https://github.com/Modulus-Learning/app.modulus-learning.org/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Modulus-Learning/app.modulus-learning.org.git",
+    "directory": "packages/lms-canvas"
+  },
+  "engines": {
+    "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@modulus-learning/lti": "0.11.1",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.6.4",
+    "@types/node": "^26.6.6",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "rm -rf node_modules dist .turbo",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "lint": "biome check --write --diagnostic-level=error",
+    "typecheck": "tsc --noEmit",
+    "test": "LOG_LEVEL=off tsx --test $(find src -name \"*.test.ts\")"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.