@openstax/ts-utils 1.37.2 → 1.38.0

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

@@ -1,24 +1,34 @@
 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 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 oldestStatement: (statements: UXapiStatement[]) => UXapiStatement | undefined;
-export declare const mostRecentStatement: (statements: UXapiStatement[]) => UXapiStatement | undefined;
+export declare const resolveScoredForAttempt: (statements: UXapiStatement[], attempt: UXapiStatement, activityIRI?: string) => UXapiStatement | undefined;
+export declare const getStatementTimeString: (statement: UXapiStatement) => string;
+export declare const getStatementTime: (statement: UXapiStatement) => Date;
+export declare const oldestStatement: (items: UXapiStatement[]) => UXapiStatement | undefined;
+export declare const mostRecentStatement: (items: UXapiStatement[]) => UXapiStatement | undefined;
+export declare const oldestEntry: (items: AttemptEntry[]) => AttemptEntry | undefined;
+export declare const mostRecentEntry: (items: AttemptEntry[]) => AttemptEntry | undefined;
+export declare const bestEntry: (items: AttemptEntry[]) => AttemptEntry | undefined;
 export declare const resolveAttemptInfo: (statements: UXapiStatement[], options?: {
     activityIRI?: string;
     currentAttempt?: string;
@@ -70,3 +80,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,11 +15,20 @@ 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;
-    return statement.verb.id === Verb.Completed
+    return statement.verb.id === Verb.Completed && attempt.id
+        && 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 matchAttemptScored = (attempt) => (statement) => {
+    var _a, _b;
+    return statement.verb.id === Verb.Scored && attempt.id
         && 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);
@@ -32,78 +41,91 @@ 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 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) => {
-    // TODO optimize. i'm 100% that this could all be done in one iteration but i'm not messing around with that for now.
-    const attempts = resolveAttempts(statements, options);
-    /* attempts that have a completed statement */
-    const resolveAttemptsWithCompleted = (statements, attempts, activityIRI) => attempts.reduce((acc, attempt) => {
-        const completed = resolveCompletedForAttempt(statements, attempt, activityIRI);
-        if (completed)
-            acc.push({ attempt, completed });
-        return acc;
-    }, []);
-    const completedPairs = resolveAttemptsWithCompleted(statements, attempts, options === null || options === void 0 ? void 0 : options.activityIRI);
-    const completedAttempts = completedPairs.map(p => p.attempt);
-    /* 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 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) => {
+export const resolveScoredForAttempt = (statements, attempt, activityIRI) => {
+    // scored or completed statements that contain a score in their
+    // result are 'scoring statements' for our purposes.
+    const scoringStatements = statements.filter(s => {
         var _a;
-        return p.completed.result !== undefined &&
-            typeof ((_a = p.completed.result.score) === null || _a === void 0 ? void 0 : _a.scaled) === 'number';
-    };
-    // Find best scored pair
-    const bestScoredPair = completedPairs
-        .filter(hasScaledScore)
-        .reduce((best, pair) => {
+        return (matchAttemptScored(attempt)(s) || matchAttemptCompleted(attempt)(s))
+            && ((_a = s.result) === null || _a === void 0 ? void 0 : _a.score)
+            && (!activityIRI || s.object.id === activityIRI);
+    });
+    return mostRecentStatement(scoringStatements);
+};
+const resolveAttemptEntries = (statements, attempts, activityIRI) => attempts.reduce((acc, attempt) => {
+    const completed = resolveCompletedForAttempt(statements, attempt, activityIRI);
+    const scored = resolveScoredForAttempt(statements, attempt, activityIRI);
+    acc.push({ attempt, completed, scored });
+    return acc;
+}, []);
+export const getStatementTimeString = (statement) => 'stored' in statement && statement.stored ? statement.stored : statement.timestamp;
+export const getStatementTime = (statement) => parseISO(getStatementTimeString(statement));
+const findByComparator = (comparator, extractor) => (items) => {
+    return items.reduce((best, item) => {
         if (!best)
-            return pair;
-        return pair.completed.result.score.scaled > best.completed.result.score.scaled ? pair : best;
+            return item;
+        return comparator(extractor(best), extractor(item)) ? best : item;
     }, 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)
-        : undefined;
-    const bestPair = bestScoredPair !== null && bestScoredPair !== void 0 ? bestScoredPair : bestDefaultPair;
+};
+export const oldestStatement = findByComparator(isBefore, getStatementTime);
+export const mostRecentStatement = findByComparator(isAfter, getStatementTime);
+export const oldestEntry = findByComparator(isBefore, (entry) => getStatementTime(entry.attempt));
+export const mostRecentEntry = findByComparator(isAfter, (entry) => getStatementTime(entry.attempt));
+const scaledScoreForEntry = (entry) => {
+    var _a;
+    const scoringStatement = entry.scored;
+    const score = (_a = scoringStatement === null || scoringStatement === void 0 ? void 0 : scoringStatement.result) === null || _a === void 0 ? void 0 : _a.score;
+    if (!score)
+        return { score: undefined, entry };
+    // Prefer scaled, otherwise normalize raw/max if available
+    if (score.scaled !== undefined)
+        return { score: score.scaled, entry };
+    if (score.raw !== undefined && score.max !== undefined && score.max !== 0) {
+        return { score: score.raw / score.max, entry };
+    }
+    return { score: undefined, entry };
+};
+/*
+ * the 'best' entry is the one with the highest scaled score.
+ * if two entries have no score, the most recent is considered best.
+ */
+export const bestEntry = findByComparator((a, b) => {
+    // if neither has a score, use the most recent
+    if (a.score === undefined && b.score === undefined) {
+        return isAfter(getStatementTime(a.entry.attempt), getStatementTime(b.entry.attempt));
+    }
+    if (a.score === undefined)
+        return false;
+    if (b.score === undefined)
+        return true;
+    return a.score > b.score;
+}, scaledScoreForEntry);
+export const resolveAttemptInfo = (statements, options) => {
+    // TODO optimize. i'm 100% that this could all be done in one iteration but i'm not messing around with that for now.
+    const attempts = resolveAttempts(statements, options);
+    const attemptEntries = resolveAttemptEntries(statements, attempts, options === null || options === void 0 ? void 0 : options.activityIRI);
+    const completedEntries = attemptEntries.filter((entry) => !!entry.completed);
+    const current = (options === null || options === void 0 ? void 0 : options.currentAttempt)
+        ? attemptEntries.find(({ attempt }) => attempt.id === options.currentAttempt)
+        : (options === null || options === void 0 ? void 0 : options.currentPreference) === 'oldest' /* the attempt sorted by timestamp */
+            ? oldestEntry(attemptEntries)
+            : mostRecentEntry(attemptEntries);
+    const currentAttemptStatements = current
+        ? 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) === current.attempt.id;
+        })
+        : [];
+    const mostRecentWithCompleted = mostRecentEntry(completedEntries);
+    const best = bestEntry(completedEntries);
     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: completedEntries.length,
         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 +291,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.d.ts

@@ -1,6 +1,6 @@
 import { AccountsGateway, MappedUserInfo } from '../accountsGateway';
 import { AuthProvider } from '../authProvider';
-import { ActivityState } from './attempt-utils';
+import { ActivityState, AttemptEntry } from './attempt-utils';
 import { LrsGateway } from '.';
 export interface Grade {
     activityProgress: 'Initialized' | 'Started' | 'inProgress' | 'Submitted' | 'Completed';
@@ -23,15 +23,8 @@ export declare const getRegistrationAttemptInfo: (lrs: LrsGateway, registration:
 }) => Promise<{
     [key: string]: ActivityState;
 }>;
-export declare const getScoreGrade: (score: {
-    scaled?: number;
-    raw?: number;
-    min?: number;
-    max?: number;
-}, options: {
+export declare const getScoreGrade: (entry: Partial<AttemptEntry>, options: {
     maxScore?: number;
-    startedAt?: string;
-    submittedAt?: string;
     userId?: string;
 }) => Grade;
 export type Progress = {

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, getStatementTimeString, 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 });
@@ -23,59 +23,47 @@ export const getRegistrationAttemptInfo = async (lrs, registration, options) =>
 // lti: http://www.imsglobal.org/spec/lti-ags/v2p0#score-publish-service
 // ltijs: https://cvmcosta.me/ltijs/#/grading
 // Note: "min" is currently completely ignored
-export const getScoreGrade = (score, options) => {
-    const { raw, scaled, max } = score;
-    const { maxScore, startedAt, submittedAt, userId } = options;
+export const getScoreGrade = (entry, options) => {
+    var _a, _b, _c, _d, _e;
+    const { raw, scaled, max } = ((_b = (_a = entry.scored) === null || _a === void 0 ? void 0 : _a.result) === null || _b === void 0 ? void 0 : _b.score) || {};
+    const { maxScore, userId } = options;
     const scoreMaximum = maxScore !== null && maxScore !== void 0 ? maxScore : 100;
     const scoreGiven = raw && max
         ? scoreMaximum / max * raw
         : scaled
             ? scaled * scoreMaximum
             : 0;
-    const submission = {};
-    if (startedAt) {
-        submission.startedAt = startedAt;
-    }
-    if (submittedAt) {
-        submission.submittedAt = submittedAt;
-    }
+    const submission = {
+        startedAt: entry.attempt ? getStatementTimeString(entry.attempt) : undefined,
+        submittedAt: entry.completed ? getStatementTimeString(entry.completed) : undefined,
+    };
+    const pendingManual = entry.scored === undefined
+        && ((_e = (_d = (_c = entry.completed) === null || _c === void 0 ? void 0 : _c.result) === null || _d === void 0 ? void 0 : _d.extensions) === null || _e === void 0 ? void 0 : _e[EXT_PENDING_SCORING]) === 'true';
     return {
         userId,
-        activityProgress: submittedAt ? 'Completed' : 'Started',
+        activityProgress: entry.completed ? 'Completed' : 'Started',
         // canvas assumes that anything that isn't 'FullyGraded' requires manual grading and displays a "needs grading" icon.
         // if you warp your mind you can consider the portion of the assignment which is completed to be fully graded.
-        gradingProgress: 'FullyGraded',
+        gradingProgress: pendingManual ? 'PendingManual' : 'FullyGraded',
         scoreMaximum,
         scoreGiven: roundToPrecision(scoreGiven, -2),
         submission,
     };
 };
 // 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
-    return {
-        attempt: state.currentAttempt,
-        completed: state.currentAttemptCompleted,
-    };
+const getGradingAttemptEntry = (state, gradePreference) => {
+    return (gradePreference === 'best' ? state.best : state.current) || {};
 };
 const getCompletedActivityStateGradeAndProgress = ({ name, scoreMaximum, state, userId, gradePreference = 'current' }) => {
-    var _a;
-    const { attempt, completed } = pickAttemptAndCompleted(state, gradePreference);
+    const entry = getGradingAttemptEntry(state, gradePreference);
+    const grade = getScoreGrade(entry, {
+        maxScore: scoreMaximum,
+        userId,
+    });
     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: entry.completed ? 1 : 0,
         },
         name,
     };
@@ -88,7 +76,7 @@ export const getCompletedUserInfosGradeAndProgress = (infos, scoreMaximum, grade
     gradePreference,
 }));
 export const getCurrentGrade = async (services, registration, options) => {
-    var _a;
+    var _a, _b;
     const user = await services.ltiAuthProvider.getUser();
     if (!user) {
         return null;
@@ -106,7 +94,7 @@ export const getCurrentGrade = async (services, registration, options) => {
             gradePreference,
         });
     }
-    if (userInfo.currentAttemptCompleted || !incompleteAttemptCallback) {
+    if (((_b = userInfo.current) === null || _b === void 0 ? void 0 : _b.completed) || !incompleteAttemptCallback) {
         return getCompletedActivityStateGradeAndProgress({
             name,
             scoreMaximum,
@@ -127,7 +115,7 @@ 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);
+        const { completed } = getGradingAttemptEntry(info.data, gradePreference);
         return completed === undefined;
     })(mappedInfo);
     return getCompletedUserInfosGradeAndProgress(completedInfo, scoreMaximum, gradePreference).concat(await incompleteAttemptsCallback(incompleteInfo));