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

package/dist/adapter.js

@@ -0,0 +1,45 @@
+import { CLAIM_CUSTOM, CLAIM_ROLES, LMS_CONTRACT_VERSION, } from '@modulus-learning/lti';
+import { HttpLtiAgsClient } from './ags-client.js';
+import { CANVAS_CUSTOM_LAUNCH_FIELDS } from './deep-link-fields.js';
+import { QuotaGovernor } from './quota-governor.js';
+import { canvasRegistrationConfig, canvasRegistrationEndpoints } from './registration.js';
+import { isInstructor } from './roles.js';
+import { inspectCanvasTerm } from './term.js';
+/**
+ * The Canvas LMS adapter. Everything Canvas-specific that core relies on —
+ * role interpretation, term metadata, the assignment lock-date fallback, the
+ * deep-link substitution variables, registration defaults and developer-key
+ * configuration, the AGS transport and Canvas quota pacing — is reached
+ * through this object.
+ */
+export const canvasAdapter = () => ({
+    id: 'canvas',
+    contractVersion: LMS_CONTRACT_VERSION,
+    capabilities: { deepLinking: true, termMetadata: true, registrationConfig: true },
+    interpretLaunch: (launch) => ({
+        isInstructor: isInstructor(launch[CLAIM_ROLES]),
+        term: inspectCanvasTerm(launch[CLAIM_CUSTOM]),
+        cutoffFallback: launch[CLAIM_CUSTOM]['Canvas.assignment.lockAt.iso8601'],
+    }),
+    deepLinkCustomFields: () => ({ ...CANVAS_CUSTOM_LAUNCH_FIELDS }),
+    registrationEndpoints: canvasRegistrationEndpoints,
+    registrationConfig: canvasRegistrationConfig,
+    createScoreClient: ({ registration, accessTokens, logger, settings }) => {
+        // One governor per registration-bound client: no pacing state is shared
+        // between registrations.
+        const governor = new QuotaGovernor(Math.max(1, settings.maxConcurrentSubmissions), settings.quotaReserveRequests, settings.quotaWindowMs, settings.quotaRampIntervalMs);
+        return {
+            client: new HttpLtiAgsClient({
+                logger,
+                registration,
+                accessTokens,
+                requestTimeoutSeconds: settings.requestTimeoutSeconds,
+            }),
+            scheduling: {
+                target: () => governor.target(),
+                record: (signal) => governor.record(signal),
+                reset: () => governor.reset(),
+            },
+        };
+    },
+});

package/dist/ags-client.d.ts

@@ -0,0 +1,26 @@
+import type { AccessTokenSource, LtiAgsClient, LtiLogger, LtiRegistration, PublishScoreInput, PublishScoreOutcome } from '@modulus-learning/lti';
+export type FetchFn = typeof fetch;
+/**
+ * HTTP client for {@link LtiAgsClient}, targeting Canvas's AGS score endpoint.
+ * Owns access-token acquisition (and invalidation on a token-level rejection),
+ * the AGS Score payload, the rate-limit header read, and response
+ * classification -- everything transport/protocol, so core's submitter is left
+ * with pure queue/lease orchestration.
+ */
+export declare class HttpLtiAgsClient implements LtiAgsClient {
+    readonly issuer: string;
+    private logger;
+    private platform;
+    private accessTokenManager;
+    private requestTimeoutSeconds;
+    private fetchFn;
+    constructor(deps: {
+        logger: LtiLogger;
+        registration: LtiRegistration;
+        accessTokens: AccessTokenSource;
+        requestTimeoutSeconds: number;
+        fetchFn?: FetchFn;
+    });
+    publishScore(input: PublishScoreInput): Promise<PublishScoreOutcome>;
+}
+//# sourceMappingURL=ags-client.d.ts.map

package/dist/ags-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ags-client.d.ts","sourceRoot":"","sources":["../src/ags-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,YAAY,EACZ,SAAS,EACT,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,uBAAuB,CAAA;AAO9B,MAAM,MAAM,OAAO,GAAG,OAAO,KAAK,CAAA;AAElC;;;;;;GAMG;AACH,qBAAa,gBAAiB,YAAW,YAAY;IACnD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IAEvB,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,kBAAkB,CAAmB;IAC7C,OAAO,CAAC,qBAAqB,CAAQ;IACrC,OAAO,CAAC,OAAO,CAAS;IAExB,YAAY,IAAI,EAAE;QAChB,MAAM,EAAE,SAAS,CAAA;QACjB,YAAY,EAAE,eAAe,CAAA;QAC7B,YAAY,EAAE,iBAAiB,CAAA;QAC/B,qBAAqB,EAAE,MAAM,CAAA;QAC7B,OAAO,CAAC,EAAE,OAAO,CAAA;KAClB,EAOA;IAEK,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAmEzE;CACF"}

package/dist/ags-client.js

@@ -0,0 +1,99 @@
+import { classifyScoreSubmissionResponse } from './error-classifier.js';
+/**
+ * HTTP client for {@link LtiAgsClient}, targeting Canvas's AGS score endpoint.
+ * Owns access-token acquisition (and invalidation on a token-level rejection),
+ * the AGS Score payload, the rate-limit header read, and response
+ * classification -- everything transport/protocol, so core's submitter is left
+ * with pure queue/lease orchestration.
+ */
+export class HttpLtiAgsClient {
+    issuer;
+    logger;
+    platform;
+    accessTokenManager;
+    requestTimeoutSeconds;
+    fetchFn;
+    constructor(deps) {
+        this.logger = deps.logger;
+        this.platform = deps.registration;
+        this.issuer = deps.registration.issuer;
+        this.accessTokenManager = deps.accessTokens;
+        this.requestTimeoutSeconds = deps.requestTimeoutSeconds;
+        this.fetchFn = deps.fetchFn ?? fetch;
+    }
+    async publishScore(input) {
+        this.logger.debug({
+            issuer: this.issuer,
+            progress: input.scoreGiven,
+        }, 'submitting score');
+        const accessTokenResult = await this.accessTokenManager.getAccessToken(this.platform);
+        if (!accessTokenResult.ok) {
+            return {
+                result: {
+                    ok: false,
+                    category: accessTokenResult.category,
+                    description: accessTokenResult.message,
+                    status: accessTokenResult.status_code,
+                },
+            };
+        }
+        const { accessToken } = accessTokenResult;
+        const headers = new Headers();
+        headers.append('Authorization', `Bearer ${accessToken.token}`);
+        headers.append('Content-Type', 'application/x-www-form-urlencoded');
+        const body = new URLSearchParams({
+            userId: input.ltiUserId,
+            activityProgress: input.scoreGiven < 1 ? 'Submitted' : 'Completed',
+            gradingProgress: 'FullyGraded',
+            timestamp: new Date().toISOString(),
+            scoreGiven: input.scoreGiven.toString(),
+            scoreMaximum: '1',
+        });
+        const response = await this.fetchFn(`${input.lineitemUrl}/scores`, {
+            method: 'POST',
+            headers,
+            body,
+            signal: AbortSignal.timeout(this.requestTimeoutSeconds * 1000),
+        }).catch((err) => {
+            // TODO: Should we handle TimeoutError (from the AbortSignal) differently?
+            this.logger.warn({ err, issuer: this.issuer }, 'network error in LTI score submission');
+            return null;
+        });
+        if (response == null) {
+            return { result: { ok: false, category: 'transient', description: 'network error' } };
+        }
+        const reading = parseRateLimit(response.headers);
+        const status = response.status;
+        const getText = () => response.text().catch((err) => {
+            this.logger.warn({ err, status, issuer: this.issuer }, 'error reading LTI score submission response body');
+            return '';
+        });
+        const result = await classifyScoreSubmissionResponse(status, getText);
+        if (!result.ok && result.category === 'platform_token') {
+            this.accessTokenManager.invalidateAccessToken(this.platform, accessToken);
+        }
+        return { result, reading };
+    }
+}
+/**
+ * Parse Canvas's rate-limit quota headers from a response. Returns `undefined`
+ * when `X-Rate-Limit-Remaining` is absent or unparseable (some low-level errors
+ * and 5xx responses omit them). Header lookup is case-insensitive.
+ */
+function parseRateLimit(headers, at = Date.now()) {
+    const remainingRaw = headers.get('X-Rate-Limit-Remaining');
+    if (remainingRaw == null) {
+        return undefined;
+    }
+    const remaining = Number.parseFloat(remainingRaw);
+    if (Number.isNaN(remaining)) {
+        return undefined;
+    }
+    const costRaw = headers.get('X-Request-Cost');
+    const cost = costRaw == null ? undefined : Number.parseFloat(costRaw);
+    return {
+        remaining,
+        cost: cost != null && !Number.isNaN(cost) ? cost : undefined,
+        at,
+    };
+}

package/dist/deep-link-fields.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The Canvas substitution variables a Modulus deep-link content item asks
+ * Canvas to expand into every later launch's custom claims. Existing resource
+ * links keep the set they were created with, so removing a field affects only
+ * links created afterwards.
+ */
+export declare const CANVAS_CUSTOM_LAUNCH_FIELDS: Record<string, string>;
+//# sourceMappingURL=deep-link-fields.d.ts.map

package/dist/deep-link-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-link-fields.d.ts","sourceRoot":"","sources":["../src/deep-link-fields.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,eAAO,MAAM,2BAA2B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAwE9D,CAAA"}

package/dist/deep-link-fields.js

@@ -0,0 +1,74 @@
+/**
+ * The Canvas substitution variables a Modulus deep-link content item asks
+ * Canvas to expand into every later launch's custom claims. Existing resource
+ * links keep the set they were created with, so removing a field affects only
+ * links created afterwards.
+ */
+// For now, every field that might eventually be useful is listed here;
+// once things settle down, we can remove the ones that aren't being used,
+// and rename the ones we are.
+export const CANVAS_CUSTOM_LAUNCH_FIELDS = {
+    'User.id': '$User.id',
+    'User.username': '$User.username',
+    // Canvas doesn't include the next two
+    'ActualUser.id': '$ActualUser.id',
+    'ActualUser.username': '$ActualUser.username',
+    'Context.id': '$Context.id',
+    'Context.title': '$Context.title',
+    // Canvas doesn't include the next two
+    // 'Context.type': '$Context.type',
+    // 'Context.label': '$Context.label',
+    'ResourceLink.id': '$ResourceLink.id',
+    'ResourceLink.title': '$ResourceLink.title',
+    'ResourceLink.description': '$ResourceLink.description',
+    'ResourceLink.available.startDateTime': '$ResourceLink.available.startDateTime',
+    'ResourceLink.available.endDateTime': '$ResourceLink.available.endDateTime',
+    'ResourceLink.submission.startDateTime': '$ResourceLink.submission.startDateTime',
+    'ResourceLink.submission.endDateTime': '$ResourceLink.submission.endDateTime',
+    // Canvas doesn't include the next four
+    // 'ResourceLink.available.user.startDateTime': '$ResourceLink.available.user.startDateTime',
+    // 'ResourceLink.available.user.endDateTime': '$ResourceLink.available.user.endDateTime',
+    // 'ResourceLink.submission.user.startDateTime': '$ResourceLink.submission.user.startDateTime',
+    // 'ResourceLink.submission.user.endDateTime': '$ResourceLink.submission.user.endDateTime',
+    // Canvas-specific properties
+    'Message.locale': '$Message.locale',
+    'Canvas.account.id': '$Canvas.account.id',
+    'Canvas.account.name': '$Canvas.account.name',
+    'Canvas.user.id': '$Canvas.user.id',
+    'Canvas.user.loginId': '$Canvas.user.loginId',
+    'Canvas.masqueradingUser.id': '$Canvas.masqueradingUser.id',
+    'Canvas.masqueradingUser.userId': '$Canvas.masqueradingUser.userId',
+    'Canvas.course.id': '$Canvas.course.id',
+    'Canvas.course.name': '$Canvas.course.name',
+    'Canvas.course.startAt': '$Canvas.course.startAt',
+    'Canvas.course.endAt': '$Canvas.course.endAt',
+    'Canvas.course.gradePassbackSetting': '$Canvas.course.gradePassbackSetting',
+    'Canvas.term.id': '$Canvas.term.id',
+    'Canvas.term.name': '$Canvas.term.name',
+    'Canvas.term.startAt': '$Canvas.term.startAt',
+    'Canvas.term.endAt': '$Canvas.term.endAt',
+    'Canvas.enrollment.enrollmentState': '$Canvas.enrollment.enrollmentState',
+    'Canvas.module.id': '$Canvas.module.id',
+    'Canvas.moduleItem.id': '$Canvas.moduleItem.id',
+    'Canvas.assignment.id': '$Canvas.assignment.id',
+    'Canvas.assignment.title': '$Canvas.assignment.title',
+    'Canvas.assignment.description': '$Canvas.assignment.description',
+    'Canvas.assignment.published': '$Canvas.assignment.published',
+    'Canvas.assignment.pointsPossible': '$Canvas.assignment.pointsPossible',
+    'Canvas.assignment.unlockAt.iso8601': '$Canvas.assignment.unlockAt.iso8601',
+    'Canvas.assignment.lockAt.iso8601': '$Canvas.assignment.lockAt.iso8601',
+    'Canvas.assignment.dueAt.iso8601': '$Canvas.assignment.dueAt.iso8601',
+    'Canvas.assignment.allowedAttempts': '$Canvas.assignment.allowedAttempts',
+    'Canvas.assignment.submission.studentAttempts': '$Canvas.assignment.submission.studentAttempts',
+    'com.instructure.User.student_view': '$com.instructure.User.student_view',
+    'com.instructure.Assignment.lti.id': '$com.instructure.Assignment.lti.id',
+    'com.instructure.Assignment.description': '$com.instructure.Assignment.description',
+    'com.instructure.Submission.id': '$com.instructure.Submission.id',
+    'com.instructure.Context.globalId': '$com.instructure.Context.globalId',
+    'com.instructure.Context.uuid': '$com.instructure.Context.uuid',
+    'com.instructure.contextLabel': '$com.instructure.contextLabel',
+    'vnd.instructure.Course.uuid': '$vnd.instructure.Course.uuid',
+    'vnd.instructure.User.uuid': '$vnd.instructure.User.uuid',
+    'vnd.instructure.User.current_uuid': '$vnd.instructure.User.current_uuid',
+    'LineItem.resultValue.max': '$LineItem.resultValue.max',
+};

package/dist/error-classifier.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Classifier for error responses from Canvas LMS's AGS score-submission
+ * endpoint (POST /api/lti/courses/:course_id/line_items/:line_item_id/scores).
+ *
+ * Categories (see `SubmissionErrorCategory` in ./types.ts):
+ *   platform_config — the developer key / registration itself is broken (scopes
+ *                     not granted, key inactive at the account level); every AGS
+ *                     submission against this key keeps failing until fixed at
+ *                     the platform level.
+ *   platform_token  — the access token is bad (rejected, insufficient scope,
+ *                     unknown/inactive key); a token-level auth problem.
+ *   lineitem_dead   — the specific line item, course, user, or assignment is
+ *                     the problem (deleted, concluded, not bound to this key);
+ *                     the key is otherwise healthy.  Don't resubmit this line-item.
+ *   malformed       — the request is structurally wrong; almost always a coding
+ *                     bug in the tool.  For now, just back off and retry.
+ *   rate_limit      — 403 quota exhausted or operator-blocked; back off and retry.
+ *   superseded      — Canvas already has a newer score for this line item; the
+ *                     write is stale and can be dropped.
+ *   transient       — 5xx / gateway / temporary; safe to retry with backoff.
+ *   unknown         — unrecognized response; default handling.
+ *
+ * The response body is not read here directly; the caller supplies a `getText`
+ * accessor so this function stays independent of the Response object.
+ */
+import type { SubmissionResult } from '@modulus-learning/lti';
+export declare function classifyScoreSubmissionResponse(status: number, getText: () => Promise<string>): Promise<SubmissionResult>;
+//# sourceMappingURL=error-classifier.d.ts.map

package/dist/error-classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-classifier.d.ts","sourceRoot":"","sources":["../src/error-classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAA2B,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAwTtF,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GAC7B,OAAO,CAAC,gBAAgB,CAAC,CAuC3B"}

package/dist/error-classifier.js

@@ -0,0 +1,346 @@
+/**
+ * Classifier for error responses from Canvas LMS's AGS score-submission
+ * endpoint (POST /api/lti/courses/:course_id/line_items/:line_item_id/scores).
+ *
+ * Categories (see `SubmissionErrorCategory` in ./types.ts):
+ *   platform_config — the developer key / registration itself is broken (scopes
+ *                     not granted, key inactive at the account level); every AGS
+ *                     submission against this key keeps failing until fixed at
+ *                     the platform level.
+ *   platform_token  — the access token is bad (rejected, insufficient scope,
+ *                     unknown/inactive key); a token-level auth problem.
+ *   lineitem_dead   — the specific line item, course, user, or assignment is
+ *                     the problem (deleted, concluded, not bound to this key);
+ *                     the key is otherwise healthy.  Don't resubmit this line-item.
+ *   malformed       — the request is structurally wrong; almost always a coding
+ *                     bug in the tool.  For now, just back off and retry.
+ *   rate_limit      — 403 quota exhausted or operator-blocked; back off and retry.
+ *   superseded      — Canvas already has a newer score for this line item; the
+ *                     write is stale and can be dropped.
+ *   transient       — 5xx / gateway / temporary; safe to retry with backoff.
+ *   unknown         — unrecognized response; default handling.
+ *
+ * The response body is not read here directly; the caller supplies a `getText`
+ * accessor so this function stays independent of the Response object.
+ */
+const has = (...needles) => (msg) => {
+    const lower = msg.toLowerCase();
+    return needles.some((n) => lower.includes(n.toLowerCase()));
+};
+// Order matters: more-specific message matchers must come before generic
+// ones for the same status code (e.g. "Invalid access token signature"
+// before the catch-all "Invalid access token").
+const RULES = [
+    // ---------- 401 (auth / authorization) ----------
+    {
+        status: 401,
+        match: has('Missing access token'),
+        category: 'malformed',
+        description: 'no access token sent on request',
+    },
+    {
+        status: 401,
+        match: has('Invalid access token format'),
+        category: 'platform_token',
+        description: 'access token is not a well-formed JWT',
+    },
+    {
+        status: 401,
+        match: has('Invalid access token signature'),
+        category: 'platform_token',
+        description: 'JWT signature did not verify against the registered JWKs',
+    },
+    {
+        status: 401,
+        match: has('Access token signature algorithm not allowed'),
+        category: 'platform_token',
+        description: 'JWT signing algorithm not permitted by Canvas',
+    },
+    {
+        status: 401,
+        match: has('Access token contains invalid claims'),
+        category: 'platform_token',
+        description: 'JWT claims rejected (audience, expiry, iss, sub, etc.)',
+    },
+    {
+        status: 401,
+        match: has('Expired access token'),
+        category: 'platform_token',
+        description: 'access token expired; obtain a fresh token and retry',
+    },
+    {
+        status: 401,
+        match: has('Revoked access token'),
+        category: 'platform_token',
+        description: 'access token has been revoked',
+    },
+    {
+        status: 401,
+        match: has('Insufficient scopes on access token'),
+        category: 'platform_token',
+        description: 'access token does not carry the AGS score scope',
+    },
+    {
+        status: 401,
+        match: has('Insufficient permissions'),
+        category: 'platform_config',
+        description: 'developer key is not registered with the AGS score scope',
+    },
+    {
+        status: 401,
+        match: has('Unknown or inactive Developer Key'),
+        category: 'platform_token',
+        description: 'developer key is missing, deleted, or inactive',
+    },
+    {
+        status: 401,
+        match: has('Invalid Developer Key'),
+        category: 'lineitem_dead',
+        description: "developer key not enabled in this course's account chain, or registration deactivated",
+    },
+    {
+        status: 401,
+        match: has('Access Token not linked to a Tool associated with this Context'),
+        category: 'lineitem_dead',
+        description: 'no active deployment of this key reachable from this course',
+    },
+    {
+        status: 401,
+        match: has('Invalid access token'),
+        category: 'platform_token',
+        description: 'access token rejected by Canvas',
+    },
+    // ---------- 403 (rate limit / blocklist) ----------
+    {
+        status: 403,
+        category: 'rate_limit',
+        description: 'rate-limit bucket exhausted or operator-blocked; backoff and retry',
+    },
+    // ---------- 404 (context / resource gone) ----------
+    {
+        status: 404,
+        match: has('Context is deleted or not found'),
+        category: 'lineitem_dead',
+        description: 'course context missing or deleted',
+    },
+    {
+        status: 404,
+        match: has('The specified resource does not exist'),
+        category: 'lineitem_dead',
+        description: 'line item, assignment, or course not found',
+    },
+    {
+        status: 404,
+        category: 'lineitem_dead',
+        description: 'resource not found',
+    },
+    // ---------- 412 (precondition) ----------
+    {
+        status: 412,
+        match: has('The specified LTI link ID is not associated with the line item'),
+        category: 'malformed',
+        description: 'resourceLinkId does not match the line item',
+    },
+    {
+        status: 412,
+        match: has('Tool does not have permission to view line_item'),
+        category: 'lineitem_dead',
+        description: 'line item not associated with developer key',
+    },
+    {
+        status: 412,
+        category: 'malformed',
+        description: 'precondition failed',
+    },
+    // ---------- 413 (payload) ----------
+    {
+        status: 413,
+        category: 'malformed',
+        description: 'request payload too large',
+    },
+    // ---------- 400 (validation / bad request) ----------
+    {
+        status: 400,
+        match: has('is missing'),
+        category: 'malformed',
+        description: 'required parameter missing',
+    },
+    {
+        status: 400,
+        match: has('before last updated timestamp'),
+        category: 'superseded',
+        description: 'stale timestamp — Canvas already has a newer score for this line item',
+    },
+    {
+        status: 400,
+        match: has('in the future'),
+        category: 'malformed',
+        description: 'submitted_at is more than a minute in the future',
+    },
+    {
+        status: 400,
+        match: has('not a valid timestamp'),
+        category: 'malformed',
+        description: 'timestamp could not be parsed',
+    },
+    {
+        status: 400,
+        match: has('uploading to file service failed'),
+        category: 'malformed',
+        description: 'Canvas file service rejected the upload as a bad request',
+    },
+    {
+        status: 400,
+        category: 'malformed',
+        description: 'bad request',
+    },
+    // ---------- 422 (unprocessable entity) ----------
+    {
+        status: 422,
+        match: has('This course has concluded'),
+        category: 'lineitem_dead',
+        description: 'course concluded (for this student or globally)',
+    },
+    {
+        status: 422,
+        match: has('User not found in course or is not a student'),
+        category: 'lineitem_dead',
+        description: 'user is not (or no longer) a student in this course',
+    },
+    {
+        status: 422,
+        match: has('This assignment is still unpublished'),
+        category: 'lineitem_dead',
+        description: 'assignment is unpublished',
+    },
+    {
+        status: 422,
+        match: has('Resource link id points to Tool not associated with this Context'),
+        category: 'lineitem_dead',
+        description: 'resourceLinkId points to a tool that no longer matches this context',
+    },
+    {
+        status: 422,
+        match: has('cannot be zero if line item'),
+        category: 'malformed',
+        description: "scoreMaximum is zero but the line item's max is not",
+    },
+    {
+        status: 422,
+        match: has('ScoreMaximum'),
+        category: 'malformed',
+        description: 'invalid scoreMaximum (missing or negative)',
+    },
+    {
+        status: 422,
+        match: has('ScoreGiven must be greater than or equal to 0'),
+        category: 'malformed',
+        description: 'scoreGiven is negative',
+    },
+    {
+        status: 422,
+        match: has("Content items must be provided with submission type 'online_upload'"),
+        category: 'malformed',
+        description: 'online_upload submission type requires content_items',
+    },
+    {
+        status: 422,
+        match: has('maximum number of allowed attempts has been reached'),
+        category: 'lineitem_dead',
+        description: 'user has no submission attempts remaining',
+    },
+    {
+        status: 422,
+        match: has('Student must be enrolled in the course as a student'),
+        category: 'lineitem_dead',
+        description: "user's enrollment does not allow grading",
+    },
+    {
+        status: 422,
+        match: has('Cannot grade this submission at this time'),
+        category: 'lineitem_dead',
+        description: 'submission not gradeable (e.g. moderated grading state)',
+    },
+    {
+        status: 422,
+        match: has('Must provide a valid sub assignment tag'),
+        category: 'lineitem_dead',
+        description: 'checkpointed discussion sub-assignment cannot accept AGS scores',
+    },
+    {
+        status: 422,
+        category: 'unknown',
+        description: 'unprocessable entity (uncategorized validation or grading error)',
+    },
+];
+// function parseBody(text: string): unknown {
+//   try {
+//     return JSON.parse(text)
+//   } catch {
+//     return text
+//   }
+// }
+// function extractMessage(body: unknown): string {
+//   if (body == null) return ''
+//   if (typeof body === 'string') return body
+//   if (typeof body !== 'object') return ''
+//   const errors = (body as Record<string, unknown>).errors
+//   if (errors == null) return ''
+//   // Shape A: { errors: { type, message } }
+//   if (!Array.isArray(errors) && typeof errors === 'object') {
+//     const e = errors as Record<string, unknown>
+//     if (typeof e.message === 'string') return e.message
+//     // Shape C: { errors: { field: [{ message }] } }
+//     for (const key of Object.keys(e)) {
+//       const val = e[key]
+//       if (Array.isArray(val) && val.length > 0) {
+//         const first = val[0] as Record<string, unknown> | undefined
+//         if (first && typeof first.message === 'string') {
+//           return `${key}: ${first.message}`
+//         }
+//       }
+//     }
+//   }
+//   // Shape B: { errors: [{ message }] }
+//   if (Array.isArray(errors) && errors.length > 0) {
+//     const first = errors[0] as Record<string, unknown> | undefined
+//     if (first && typeof first.message === 'string') return first.message
+//   }
+//   return ''
+// }
+export async function classifyScoreSubmissionResponse(status, getText) {
+    if (status >= 200 && status < 300) {
+        return {
+            ok: true,
+        };
+    }
+    const text = await getText();
+    if (status >= 500) {
+        return {
+            ok: false,
+            category: 'transient',
+            description: 'server error',
+            status,
+            text,
+        };
+    }
+    for (const rule of RULES) {
+        // A rule with no matcher is the catch-all for its status code.
+        if (rule.status === status && (rule.match == null || rule.match(text))) {
+            return {
+                ok: false,
+                category: rule.category,
+                description: rule.description,
+                status,
+                text,
+            };
+        }
+    }
+    return {
+        ok: false,
+        category: 'unknown',
+        description: 'unrecognized error',
+        status,
+        text,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `@modulus-learning/lms-canvas` — the Canvas LMS adapter for Modulus. Pass
+ * `canvasAdapter()` to the host's server configuration.
+ */
+export { canvasAdapter } from './adapter.js';
+export { type FetchFn, 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';
+export type { RateLimitReading } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,EAAE,KAAK,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAChE,OAAO,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAA;AACnE,OAAO,EAAE,+BAA+B,EAAE,MAAM,uBAAuB,CAAA;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,wBAAwB,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAA;AACzF,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC/D,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAClE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA"}