@openstax/ts-utils 1.37.1 → 1.38.0-beta

package/dist/cjs/services/lrsGateway/attempt-utils.d.ts

@@ -1,22 +1,27 @@
 import { LrsGateway, UXapiStatement } from '.';
+export declare const EXT_PENDING_SCORING = "https://openstax.org/xapi/extensions/pending-scoring";
+export type AttemptEntry = {
+    attempt: UXapiStatement;
+    completed?: UXapiStatement;
+    scored?: UXapiStatement;
+};
 export type ActivityState = {
     attempts: number;
-    bestCompletedAttempt?: UXapiStatement;
-    bestCompletedAttemptCompleted?: UXapiStatement;
     completedAttempts: number;
-    currentAttempt?: UXapiStatement;
-    currentAttemptCompleted?: UXapiStatement;
     currentAttemptStatements: UXapiStatement[];
-    mostRecentAttemptWithCompleted?: UXapiStatement;
-    mostRecentAttemptWithCompletedCompleted?: UXapiStatement;
+    current?: AttemptEntry;
+    best?: AttemptEntry;
+    mostRecentWithCompleted?: AttemptEntry;
 };
 export declare const matchAttempt: (statement: UXapiStatement) => boolean;
 export declare const matchAttemptCompleted: (attempt: UXapiStatement) => (statement: UXapiStatement) => boolean;
+export declare const matchAttemptScored: (attempt: UXapiStatement) => (statement: UXapiStatement) => boolean;
 export declare const resolveAttempts: (statements: UXapiStatement[], options?: {
     activityIRI?: string;
     parentActivityAttempt?: string;
 }) => UXapiStatement[];
 export declare const resolveCompletedForAttempt: (statements: UXapiStatement[], attempt: UXapiStatement, activityIRI?: string) => UXapiStatement | undefined;
+export declare const resolveScoredForAttempt: (statements: UXapiStatement[], attempt: UXapiStatement, activityIRI?: string) => UXapiStatement | undefined;
 export declare const oldestStatement: (statements: UXapiStatement[]) => UXapiStatement | undefined;
 export declare const mostRecentStatement: (statements: UXapiStatement[]) => UXapiStatement | undefined;
 export declare const resolveAttemptInfo: (statements: UXapiStatement[], options?: {
@@ -70,3 +75,7 @@ export declare const createAttemptActivityStatement: (attemptStatement: UXapiSta
 export declare const putAttemptActivityStatement: (gateway: LrsGateway, attemptStatement: UXapiStatement, verb: UXapiStatement["verb"], result?: UXapiStatement["result"]) => Promise<import(".").EagerXapiStatement>;
 export declare const createCompletedStatement: (attemptStatement: UXapiStatement, result?: UXapiStatement["result"]) => Pick<UXapiStatement, "object" | "verb" | "context" | "result">;
 export declare const putCompletedStatement: (gateway: LrsGateway, attemptStatement: UXapiStatement, result: UXapiStatement["result"]) => Promise<import(".").EagerXapiStatement>;
+export declare const createCompletedPendingScoringStatement: (attemptStatement: UXapiStatement) => Pick<UXapiStatement, "object" | "verb" | "context" | "result">;
+export declare const putCompletedPendingScoringStatement: (gateway: LrsGateway, attemptStatement: UXapiStatement) => Promise<import(".").EagerXapiStatement>;
+export declare const createScoredStatement: (attemptStatement: UXapiStatement, result: UXapiStatement["result"]) => Pick<UXapiStatement, "object" | "verb" | "context" | "result">;
+export declare const putScoredStatement: (gateway: LrsGateway, attemptStatement: UXapiStatement, result: UXapiStatement["result"]) => Promise<import(".").EagerXapiStatement>;

package/dist/cjs/services/lrsGateway/attempt-utils.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.putCompletedStatement = exports.createCompletedStatement = exports.putAttemptActivityStatement = exports.createAttemptActivityStatement = exports.putAttemptStatement = exports.createAttemptStatement = exports.createStatement = exports.loadActivityAttemptInfo = exports.loadStatementsForActivityAndFirstChildren = exports.resolveAttemptInfo = exports.mostRecentStatement = exports.oldestStatement = exports.resolveCompletedForAttempt = exports.resolveAttempts = exports.matchAttemptCompleted = exports.matchAttempt = void 0;
+exports.putScoredStatement = exports.createScoredStatement = exports.putCompletedPendingScoringStatement = exports.createCompletedPendingScoringStatement = exports.putCompletedStatement = exports.createCompletedStatement = exports.putAttemptActivityStatement = exports.createAttemptActivityStatement = exports.putAttemptStatement = exports.createAttemptStatement = exports.createStatement = exports.loadActivityAttemptInfo = exports.loadStatementsForActivityAndFirstChildren = exports.resolveAttemptInfo = exports.mostRecentStatement = exports.oldestStatement = exports.resolveScoredForAttempt = exports.resolveCompletedForAttempt = exports.resolveAttempts = exports.matchAttemptScored = exports.matchAttemptCompleted = exports.matchAttempt = exports.EXT_PENDING_SCORING = void 0;
 /*
  * the structure of xapi statements for handling multiple attempts of an activity
  * including the option of a parent activity/attempt such that a new attempt
@@ -21,7 +21,9 @@ var Verb;
 (function (Verb) {
     Verb["Attempted"] = "http://adlnet.gov/expapi/verbs/attempted";
     Verb["Completed"] = "http://adlnet.gov/expapi/verbs/completed";
+    Verb["Scored"] = "http://adlnet.gov/expapi/verbs/scored";
 })(Verb || (Verb = {}));
+exports.EXT_PENDING_SCORING = 'https://openstax.org/xapi/extensions/pending-scoring';
 const matchAttempt = (statement) => statement.verb.id === Verb.Attempted;
 exports.matchAttempt = matchAttempt;
 const matchAttemptCompleted = (attempt) => (statement) => {
@@ -32,6 +34,14 @@ const matchAttemptCompleted = (attempt) => (statement) => {
         && statement.context.registration === ((_b = attempt.context) === null || _b === void 0 ? void 0 : _b.registration);
 };
 exports.matchAttemptCompleted = matchAttemptCompleted;
+const matchAttemptScored = (attempt) => (statement) => {
+    var _a, _b;
+    return statement.verb.id === Verb.Scored
+        && statement.context !== undefined
+        && ((_a = statement.context.statement) === null || _a === void 0 ? void 0 : _a.id) === attempt.id
+        && statement.context.registration === ((_b = attempt.context) === null || _b === void 0 ? void 0 : _b.registration);
+};
+exports.matchAttemptScored = matchAttemptScored;
 const resolveAttempts = (statements, options) => statements.filter(statement => {
     var _a;
     return (0, exports.matchAttempt)(statement)
@@ -42,6 +52,19 @@ exports.resolveAttempts = resolveAttempts;
 const resolveCompletedForAttempt = (statements, attempt, activityIRI) => statements.find(statement => (0, exports.matchAttemptCompleted)(attempt)(statement)
     && (!activityIRI || statement.object.id === activityIRI));
 exports.resolveCompletedForAttempt = resolveCompletedForAttempt;
+const resolveScoredForAttempt = (statements, attempt, activityIRI) => {
+    // Prefer the most recent Scored
+    const scored = (0, exports.mostRecentStatement)(statements.filter(s => (0, exports.matchAttemptScored)(attempt)(s) && (!activityIRI || s.object.id === activityIRI)));
+    if (scored)
+        return scored;
+    // if no scored found, return most recent Completed with a score for the attempt.
+    const completedWithScore = (0, exports.mostRecentStatement)(statements.filter(s => (0, exports.matchAttemptCompleted)(attempt)(s) &&
+        (!activityIRI || s.object.id === activityIRI) && s.result &&
+        s.result.score &&
+        (s.result.score.scaled !== undefined)));
+    return completedWithScore;
+};
+exports.resolveScoredForAttempt = resolveScoredForAttempt;
 const oldestStatement = (statements) => statements.reduce((result, statement) => result && (0, isBefore_1.default)((0, parseISO_1.default)('stored' in result && result.stored ? result.stored : result.timestamp), (0, parseISO_1.default)(statement.timestamp)) ? result : statement, statements[0]);
 exports.oldestStatement = oldestStatement;
 const mostRecentStatement = (statements) => statements.reduce((result, statement) => result && (0, isAfter_1.default)((0, parseISO_1.default)('stored' in result && result.stored ? result.stored : result.timestamp), (0, parseISO_1.default)(statement.timestamp)) ? result : statement, statements[0]);
@@ -57,55 +80,81 @@ const resolveAttemptInfo = (statements, options) => {
         return acc;
     }, []);
     const completedPairs = resolveAttemptsWithCompleted(statements, attempts, options === null || options === void 0 ? void 0 : options.activityIRI);
-    const completedAttempts = completedPairs.map(p => p.attempt);
+    const completedAttempts = completedPairs.length;
     /* the last attempt sorted by timestamp */
     const currentAttempt = (options === null || options === void 0 ? void 0 : options.currentAttempt)
         ? attempts.find(attempt => attempt.id === options.currentAttempt)
         : (options === null || options === void 0 ? void 0 : options.currentPreference) === 'oldest'
             ? (0, exports.oldestStatement)(attempts)
             : (0, exports.mostRecentStatement)(attempts);
-    /* all statements for the current attempt (doesn't include the attempt or completed statements) */
-    const currentAttemptStatements = currentAttempt ? statements.filter(statement => {
-        var _a;
-        return (!(options === null || options === void 0 ? void 0 : options.activityIRI) || statement.object.id === options.activityIRI)
-            && ((_a = statement.context) === null || _a === void 0 ? void 0 : _a.registration) === currentAttempt.id;
-    }) : [];
-    const currentAttemptCompleted = currentAttempt && (0, exports.resolveCompletedForAttempt)(statements, currentAttempt, options === null || options === void 0 ? void 0 : options.activityIRI);
+    const current = currentAttempt
+        ? {
+            attempt: currentAttempt,
+            completed: (0, exports.resolveCompletedForAttempt)(statements, currentAttempt, options === null || options === void 0 ? void 0 : options.activityIRI),
+            scored: (0, exports.resolveScoredForAttempt)(statements, currentAttempt, options === null || options === void 0 ? void 0 : options.activityIRI),
+        }
+        : undefined;
+    const currentAttemptStatements = currentAttempt
+        ? statements.filter(statement => {
+            var _a;
+            return (!(options === null || options === void 0 ? void 0 : options.activityIRI) || statement.object.id === options.activityIRI) &&
+                ((_a = statement.context) === null || _a === void 0 ? void 0 : _a.registration) === currentAttempt.id;
+        })
+        : [];
     const mostRecentPair = completedPairs.reduce((cur, pair) => {
         if (!cur)
             return pair;
         return (0, isAfter_1.default)((0, parseISO_1.default)(cur.attempt.timestamp), (0, parseISO_1.default)(pair.attempt.timestamp)) ? cur : pair;
     }, undefined);
-    /*
-     * the structure allows for the possibility of multiple incomplete attempts.
-     * the implementation can choose at its discretion to ignore the currentAttempt
-     * and instead make a new one, for instance if the implementation desires
-     * an attempt timeout feature
-     */
-    const hasScaledScore = (p) => {
+    const mostRecentWithCompleted = mostRecentPair
+        ? {
+            attempt: mostRecentPair.attempt,
+            completed: (0, exports.resolveCompletedForAttempt)(statements, mostRecentPair.attempt, options === null || options === void 0 ? void 0 : options.activityIRI),
+            scored: (0, exports.resolveScoredForAttempt)(statements, mostRecentPair.attempt, options === null || options === void 0 ? void 0 : options.activityIRI),
+        }
+        : undefined;
+    const scaledForAttempt = (attempt) => {
         var _a;
-        return p.completed.result !== undefined &&
-            typeof ((_a = p.completed.result.score) === null || _a === void 0 ? void 0 : _a.scaled) === 'number';
+        // resolveScoredForAttempt may return a Scored, or fallback to a Completed that has a score
+        const picked = (0, exports.resolveScoredForAttempt)(statements, attempt, options === null || options === void 0 ? void 0 : options.activityIRI);
+        const score = (_a = picked === null || picked === void 0 ? void 0 : picked.result) === null || _a === void 0 ? void 0 : _a.score;
+        if (!score)
+            return undefined;
+        // Prefer scaled, otherwise normalize raw/max if available
+        if (score.scaled !== undefined)
+            return score.scaled;
+        if (score.raw !== undefined && score.max !== undefined && score.max !== 0) {
+            return score.raw / score.max;
+        }
+        return undefined;
     };
-    // Filter to only scored pairs with scaled.
-    const scoredPairs = completedPairs.filter(hasScaledScore);
-    const bestPair = scoredPairs.reduce((best, pair) => {
-        if (!best)
-            return pair;
-        return pair.completed.result.score.scaled > best.completed.result.score.scaled
-            ? pair
-            : best;
+    let bestAttempt = completedPairs.reduce((best, { attempt }) => {
+        const bScaled = best !== undefined ? scaledForAttempt(best) : undefined;
+        const aScaled = scaledForAttempt(attempt);
+        if (bScaled === undefined)
+            return aScaled === undefined ? best : attempt;
+        if (aScaled === undefined)
+            return best;
+        return aScaled > bScaled ? attempt : best;
     }, undefined);
+    // Fallback if no attempt had a score, use newest completed as best
+    if (!bestAttempt && mostRecentPair) {
+        bestAttempt = mostRecentPair.attempt;
+    }
+    const best = bestAttempt
+        ? {
+            attempt: bestAttempt,
+            completed: (0, exports.resolveCompletedForAttempt)(statements, bestAttempt, options && options.activityIRI),
+            scored: (0, exports.resolveScoredForAttempt)(statements, bestAttempt, options && options.activityIRI),
+        }
+        : undefined;
     return {
         attempts: attempts.length,
-        bestCompletedAttempt: bestPair === null || bestPair === void 0 ? void 0 : bestPair.attempt,
-        bestCompletedAttemptCompleted: bestPair === null || bestPair === void 0 ? void 0 : bestPair.completed,
-        completedAttempts: completedAttempts.length,
-        currentAttempt,
-        currentAttemptCompleted,
+        completedAttempts,
         currentAttemptStatements,
-        mostRecentAttemptWithCompleted: mostRecentPair === null || mostRecentPair === void 0 ? void 0 : mostRecentPair.attempt,
-        mostRecentAttemptWithCompletedCompleted: mostRecentPair === null || mostRecentPair === void 0 ? void 0 : mostRecentPair.completed,
+        current,
+        best,
+        mostRecentWithCompleted,
     };
 };
 exports.resolveAttemptInfo = resolveAttemptInfo;
@@ -281,3 +330,46 @@ const putCompletedStatement = async (gateway, attemptStatement, result) => {
     return (await gateway.putXapiStatements([(0, exports.createCompletedStatement)(attemptStatement, result)]))[0];
 };
 exports.putCompletedStatement = putCompletedStatement;
+// pending score statement for when the open written response has been graded.
+const createCompletedPendingScoringStatement = (attemptStatement) => (0, exports.createCompletedStatement)(attemptStatement, {
+    extensions: { [exports.EXT_PENDING_SCORING]: 'true' },
+});
+exports.createCompletedPendingScoringStatement = createCompletedPendingScoringStatement;
+const putCompletedPendingScoringStatement = async (gateway, attemptStatement) => {
+    return (await gateway.putXapiStatements([
+        (0, exports.createCompletedPendingScoringStatement)(attemptStatement),
+    ]))[0];
+};
+exports.putCompletedPendingScoringStatement = putCompletedPendingScoringStatement;
+// scored statement for when the open written response has been graded.
+const createScoredStatement = (attemptStatement, result) => {
+    var _a, _b;
+    return {
+        context: {
+            ...(((_a = attemptStatement.context) === null || _a === void 0 ? void 0 : _a.contextActivities) ? {
+                contextActivities: attemptStatement.context.contextActivities,
+            } : {}),
+            ...(((_b = attemptStatement.context) === null || _b === void 0 ? void 0 : _b.registration) ? {
+                registration: attemptStatement.context.registration,
+            } : {}),
+            statement: {
+                objectType: 'StatementRef',
+                id: attemptStatement.id,
+            }
+        },
+        object: attemptStatement.object,
+        verb: {
+            display: { 'en-US': 'Scored' },
+            id: Verb.Scored,
+        },
+        result: {
+            // no duration here, we treat Scored as a pure grading event
+            ...result,
+        }
+    };
+};
+exports.createScoredStatement = createScoredStatement;
+const putScoredStatement = async (gateway, attemptStatement, result) => {
+    return (await gateway.putXapiStatements([(0, exports.createScoredStatement)(attemptStatement, result)]))[0];
+};
+exports.putScoredStatement = putScoredStatement;

package/dist/cjs/services/lrsGateway/xapiUtils.js

@@ -59,31 +59,32 @@ const getScoreGrade = (score, options) => {
 };
 exports.getScoreGrade = getScoreGrade;
 // These methods assign 0's to incomplete activities
-const pickAttemptAndCompleted = (state, gradePreference) => {
-    if (gradePreference === 'best' && state.bestCompletedAttempt) {
-        return {
-            attempt: state.bestCompletedAttempt,
-            completed: state.bestCompletedAttemptCompleted,
-        };
-    }
-    // return current attempt if gradePreference is current
+const pickAttemptAndCompletedOrScored = (state, gradePreference) => {
+    var _a;
+    const entry = (gradePreference === 'best' ? state.best : state.current);
     return {
-        attempt: state.currentAttempt,
-        completed: state.currentAttemptCompleted,
+        attempt: entry === null || entry === void 0 ? void 0 : entry.attempt,
+        completedOrScored: (_a = entry === null || entry === void 0 ? void 0 : entry.scored) !== null && _a !== void 0 ? _a : entry === null || entry === void 0 ? void 0 : entry.completed,
+        completed: entry === null || entry === void 0 ? void 0 : entry.completed,
     };
 };
 const getCompletedActivityStateGradeAndProgress = ({ name, scoreMaximum, state, userId, gradePreference = 'current' }) => {
-    var _a;
-    const { attempt, completed } = pickAttemptAndCompleted(state, gradePreference);
+    var _a, _b, _c;
+    const { attempt, completedOrScored, completed } = pickAttemptAndCompletedOrScored(state, gradePreference);
+    const grade = (0, exports.getScoreGrade)(((_a = completedOrScored === null || completedOrScored === void 0 ? void 0 : completedOrScored.result) === null || _a === void 0 ? void 0 : _a.score) || {}, {
+        maxScore: scoreMaximum,
+        startedAt: attempt === null || attempt === void 0 ? void 0 : attempt.timestamp,
+        submittedAt: completed === null || completed === void 0 ? void 0 : completed.timestamp,
+        userId,
+    });
+    // If this Completed is explicitly "pending scoring", surface that in the grade.
+    if (((_c = (_b = completedOrScored === null || completedOrScored === void 0 ? void 0 : completedOrScored.result) === null || _b === void 0 ? void 0 : _b.extensions) === null || _c === void 0 ? void 0 : _c[attempt_utils_1.EXT_PENDING_SCORING]) === 'true') {
+        grade.gradingProgress = 'PendingManual';
+    }
     return {
-        grade: (0, exports.getScoreGrade)(((_a = completed === null || completed === void 0 ? void 0 : completed.result) === null || _a === void 0 ? void 0 : _a.score) || {}, {
-            maxScore: scoreMaximum,
-            startedAt: attempt === null || attempt === void 0 ? void 0 : attempt.timestamp,
-            submittedAt: completed === null || completed === void 0 ? void 0 : completed.timestamp,
-            userId,
-        }),
+        grade,
         progress: {
-            scaled: completed ? 1 : 0,
+            scaled: completedOrScored ? 1 : 0,
         },
         name,
     };
@@ -115,7 +116,7 @@ const getCurrentGrade = async (services, registration, options) => {
             gradePreference,
         });
     }
-    if (userInfo.currentAttemptCompleted || !incompleteAttemptCallback) {
+    if (userInfo.current && userInfo.current.completed || !incompleteAttemptCallback) {
         return getCompletedActivityStateGradeAndProgress({
             name,
             scoreMaximum,
@@ -137,8 +138,8 @@ const getAssignmentGrades = async (services, assignmentIRI, registration, option
     }
     // Partition based on whether the chosen preference has a completed attempt
     const [incompleteInfo, completedInfo] = (0, partition_1.default)((info) => {
-        const { completed } = pickAttemptAndCompleted(info.data, gradePreference);
-        return completed === undefined;
+        const { completedOrScored } = pickAttemptAndCompletedOrScored(info.data, gradePreference);
+        return completedOrScored === undefined;
     })(mappedInfo);
     return (0, exports.getCompletedUserInfosGradeAndProgress)(completedInfo, scoreMaximum, gradePreference).concat(await incompleteAttemptsCallback(incompleteInfo));
 };