@openstax/ts-utils 1.37.2 → 1.38.0-beta

package/dist/esm/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/esm/services/lrsGateway/attempt-utils.js

@@ -15,7 +15,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 = {}));
+export const EXT_PENDING_SCORING = 'https://openstax.org/xapi/extensions/pending-scoring';
 export const matchAttempt = (statement) => statement.verb.id === Verb.Attempted;
 export const matchAttemptCompleted = (attempt) => (statement) => {
     var _a, _b;
@@ -24,6 +26,13 @@ export const matchAttemptCompleted = (attempt) => (statement) => {
         && ((_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);
 };
+export 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);
+};
 export const resolveAttempts = (statements, options) => statements.filter(statement => {
     var _a;
     return matchAttempt(statement)
@@ -32,6 +41,18 @@ export const resolveAttempts = (statements, options) => statements.filter(statem
 });
 export const resolveCompletedForAttempt = (statements, attempt, activityIRI) => statements.find(statement => matchAttemptCompleted(attempt)(statement)
     && (!activityIRI || statement.object.id === activityIRI));
+export const resolveScoredForAttempt = (statements, attempt, activityIRI) => {
+    // Prefer the most recent Scored
+    const scored = mostRecentStatement(statements.filter(s => 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 = mostRecentStatement(statements.filter(s => matchAttemptCompleted(attempt)(s) &&
+        (!activityIRI || s.object.id === activityIRI) && s.result &&
+        s.result.score &&
+        (s.result.score.scaled !== undefined)));
+    return completedWithScore;
+};
 export const oldestStatement = (statements) => statements.reduce((result, statement) => result && isBefore(parseISO('stored' in result && result.stored ? result.stored : result.timestamp), parseISO(statement.timestamp)) ? result : statement, statements[0]);
 export const mostRecentStatement = (statements) => statements.reduce((result, statement) => result && isAfter(parseISO('stored' in result && result.stored ? result.stored : result.timestamp), parseISO(statement.timestamp)) ? result : statement, statements[0]);
 export const resolveAttemptInfo = (statements, options) => {
@@ -45,65 +66,81 @@ export 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'
             ? oldestStatement(attempts)
             : 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 && resolveCompletedForAttempt(statements, currentAttempt, options === null || options === void 0 ? void 0 : options.activityIRI);
+    const current = currentAttempt
+        ? {
+            attempt: currentAttempt,
+            completed: resolveCompletedForAttempt(statements, currentAttempt, options === null || options === void 0 ? void 0 : options.activityIRI),
+            scored: 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 isAfter(parseISO(cur.attempt.timestamp), parseISO(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: resolveCompletedForAttempt(statements, mostRecentPair.attempt, options === null || options === void 0 ? void 0 : options.activityIRI),
+            scored: 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 = 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;
     };
-    // Find best scored pair
-    const bestScoredPair = completedPairs
-        .filter(hasScaledScore)
-        .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);
-    // if no scored pair get newest completed without a score
-    const bestDefaultPair = !bestScoredPair && completedPairs.length > 0
-        ? completedPairs.reduce((best, pair) => {
-            if (!best)
-                return pair;
-            return isAfter(parseISO(pair.attempt.timestamp), parseISO(best.attempt.timestamp))
-                ? pair
-                : 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: resolveCompletedForAttempt(statements, bestAttempt, options && options.activityIRI),
+            scored: resolveScoredForAttempt(statements, bestAttempt, options && options.activityIRI),
+        }
         : undefined;
-    const bestPair = bestScoredPair !== null && bestScoredPair !== void 0 ? bestScoredPair : bestDefaultPair;
     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,
     };
 };
 /*
@@ -269,3 +306,42 @@ export const createCompletedStatement = (attemptStatement, result) => {
 export const putCompletedStatement = async (gateway, attemptStatement, result) => {
     return (await gateway.putXapiStatements([createCompletedStatement(attemptStatement, result)]))[0];
 };
+// pending score statement for when the open written response has been graded.
+export const createCompletedPendingScoringStatement = (attemptStatement) => createCompletedStatement(attemptStatement, {
+    extensions: { [EXT_PENDING_SCORING]: 'true' },
+});
+export const putCompletedPendingScoringStatement = async (gateway, attemptStatement) => {
+    return (await gateway.putXapiStatements([
+        createCompletedPendingScoringStatement(attemptStatement),
+    ]))[0];
+};
+// scored statement for when the open written response has been graded.
+export 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,
+        }
+    };
+};
+export const putScoredStatement = async (gateway, attemptStatement, result) => {
+    return (await gateway.putXapiStatements([createScoredStatement(attemptStatement, result)]))[0];
+};

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

@@ -1,6 +1,6 @@
 import partition from 'lodash/fp/partition';
 import { roundToPrecision } from '../..';
-import { resolveAttemptInfo } from './attempt-utils';
+import { EXT_PENDING_SCORING, resolveAttemptInfo } from './attempt-utils';
 export const getRegistrationAttemptInfo = async (lrs, registration, options) => {
     const { currentPreference, ...xapiOptions } = options !== null && options !== void 0 ? options : {};
     const allStatements = await lrs.getAllXapiStatements({ ...xapiOptions, registration });
@@ -51,31 +51,32 @@ export const getScoreGrade = (score, options) => {
     };
 };
 // 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 = 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[EXT_PENDING_SCORING]) === 'true') {
+        grade.gradingProgress = 'PendingManual';
+    }
     return {
-        grade: 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,
     };
@@ -106,7 +107,7 @@ export const getCurrentGrade = async (services, registration, options) => {
             gradePreference,
         });
     }
-    if (userInfo.currentAttemptCompleted || !incompleteAttemptCallback) {
+    if (userInfo.current && userInfo.current.completed || !incompleteAttemptCallback) {
         return getCompletedActivityStateGradeAndProgress({
             name,
             scoreMaximum,
@@ -127,8 +128,8 @@ export const getAssignmentGrades = async (services, assignmentIRI, registration,
     }
     // Partition based on whether the chosen preference has a completed attempt
     const [incompleteInfo, completedInfo] = partition((info) => {
-        const { completed } = pickAttemptAndCompleted(info.data, gradePreference);
-        return completed === undefined;
+        const { completedOrScored } = pickAttemptAndCompletedOrScored(info.data, gradePreference);
+        return completedOrScored === undefined;
     })(mappedInfo);
     return getCompletedUserInfosGradeAndProgress(completedInfo, scoreMaximum, gradePreference).concat(await incompleteAttemptsCallback(incompleteInfo));
 };