@openstax/ts-utils 1.34.0 → 1.34.1

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

@@ -0,0 +1,148 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lrsGateway = void 0;
+const queryString = __importStar(require("query-string"));
+const __1 = require("../..");
+const assertions_1 = require("../../assertions");
+const config_1 = require("../../config");
+const errors_1 = require("../../errors");
+const fetchStatusRetry_1 = require("../../fetch/fetchStatusRetry");
+const guards_1 = require("../../guards");
+const helpers_1 = require("../../misc/helpers");
+const routing_1 = require("../../routing");
+const addStatementDefaultFields_1 = require("./addStatementDefaultFields");
+const lrsGateway = (initializer) => (configProvider) => {
+    const config = configProvider[(0, guards_1.ifDefined)(initializer.configSpace, 'lrs')];
+    const lrsHost = (0, __1.once)(() => (0, config_1.resolveConfigValue)(config.lrsHost));
+    const lrsAuthorization = (0, __1.once)(() => (0, config_1.resolveConfigValue)(config.lrsAuthorization));
+    return ({ authProvider, logger }) => {
+        const fetcher = (0, fetchStatusRetry_1.fetchStatusRetry)(initializer.fetch, {
+            logger,
+            retries: 2,
+            wait: 1000,
+            status: [502]
+        });
+        // Note: This method actually uses POST
+        const putXapiStatements = async (statements) => {
+            const user = (0, assertions_1.assertDefined)(await authProvider.getUser(), new errors_1.UnauthorizedError);
+            const statementsWithDefaults = statements.map(statement => (0, addStatementDefaultFields_1.addStatementDefaultFields)(statement, user));
+            const response = await fetcher((await lrsHost()).replace(/\/+$/, '') + '/data/xAPI/statements', {
+                body: JSON.stringify(statementsWithDefaults),
+                headers: {
+                    Authorization: await lrsAuthorization(),
+                    'Content-Type': 'application/json',
+                    'X-Experience-API-Version': '1.0.0',
+                },
+                method: routing_1.METHOD.POST,
+            });
+            if (![200, 201].includes(response.status)) {
+                throw new Error(`Unexpected LRS POST statements response code ${response.status} with body:
+
+${await response.text()}`);
+            }
+            await response.json();
+            return statementsWithDefaults;
+        };
+        // Note: This code does not currently handle a single statement response,
+        // which can return 404 if the statement is not found
+        const formatGetXapiStatementsResponse = async (response) => {
+            if (response.status !== 200) {
+                throw new Error(`Unexpected LRS GET statements response code ${response.status} with body:
+
+${await response.text()}`);
+            }
+            return response.json();
+        };
+        const getMoreXapiStatements = async (more) => fetcher((await lrsHost()).replace(/\/+$/, '') + more, {
+            headers: {
+                Authorization: await lrsAuthorization(),
+                'X-Experience-API-Version': '1.0.0',
+            },
+        }).then(formatGetXapiStatementsResponse);
+        const fetchXapiStatements = async ({ user, anyUser, ...options }) => fetcher((await lrsHost()).replace(/\/+$/, '') + '/data/xAPI/statements?' + queryString.stringify({
+            ...options,
+            ...(anyUser === true ? {} : {
+                agent: JSON.stringify({
+                    account: {
+                        homePage: 'https://openstax.org',
+                        name: user || (0, assertions_1.assertDefined)(await authProvider.getUser(), new errors_1.UnauthorizedError()).uuid,
+                    },
+                    objectType: 'Agent',
+                }),
+            })
+        }), {
+            headers: {
+                Authorization: await lrsAuthorization(),
+                'X-Experience-API-Version': '1.0.0',
+            },
+        });
+        const getXapiStatements = async (params) => {
+            const { ensureSync, ...fetchParams } = params;
+            if (ensureSync) {
+                const date = new Date();
+                return (0, helpers_1.retryWithDelay)(async (abort) => {
+                    // this function retries for the consistency, if the fetch errors just abort
+                    const response = await fetchXapiStatements(fetchParams).catch(abort);
+                    const consistentThrough = response.headers.get('X-Experience-API-Consistent-Through');
+                    if (!consistentThrough || new Date(consistentThrough) < date) {
+                        throw new Error(`xAPI consistent through ${consistentThrough}; not in sync with current date ${date.toISOString()}.`);
+                    }
+                    return formatGetXapiStatementsResponse(response);
+                }, { retries: 4, logger });
+            }
+            else {
+                return fetchXapiStatements(fetchParams).then(formatGetXapiStatementsResponse);
+            }
+        };
+        const getAllXapiStatements = async ({ fetchUntil, ...params }) => {
+            const loadRemaining = async (result) => {
+                if (!result.more || (fetchUntil && fetchUntil(result.statements))) {
+                    return result.statements;
+                }
+                const { more, statements } = await getMoreXapiStatements(result.more);
+                return loadRemaining({ more, statements: [...result.statements, ...statements] });
+            };
+            return loadRemaining(await getXapiStatements(params));
+        };
+        return {
+            putXapiStatements,
+            getXapiStatements,
+            getMoreXapiStatements,
+            getAllXapiStatements,
+        };
+    };
+};
+exports.lrsGateway = lrsGateway;

package/dist/cjs/services/lrsGateway/xapiUtils.d.ts

@@ -0,0 +1,71 @@
+import { AccountsGateway, MappedUserInfo } from '../accountsGateway';
+import { AuthProvider } from '../authProvider';
+import { ActivityState } from './attempt-utils';
+import { LrsGateway } from '.';
+export interface Grade {
+    activityProgress: 'Initialized' | 'Started' | 'inProgress' | 'Submitted' | 'Completed';
+    comment?: string;
+    gradingProgress: 'FullyGraded' | 'Pending' | 'PendingManual' | 'Failed' | 'NotReady';
+    scoreGiven: number;
+    scoreMaximum: number;
+    submission?: {
+        startedAt?: string;
+        submittedAt?: string;
+    };
+    userId?: string;
+}
+export declare const getRegistrationAttemptInfo: (lrs: LrsGateway, registration: string, options?: {
+    activity?: string;
+    anyUser?: boolean;
+    currentPreference?: "latest" | "oldest";
+    ensureSync?: boolean;
+    user?: string;
+}) => Promise<{
+    [key: string]: ActivityState;
+}>;
+export declare const getScoreGrade: (score: {
+    scaled?: number;
+    raw?: number;
+    min?: number;
+    max?: number;
+}, options: {
+    maxScore?: number;
+    startedAt?: string;
+    submittedAt?: string;
+    userId?: string;
+}) => Grade;
+export type Progress = {
+    scaled: number;
+    max?: number;
+    raw?: number;
+};
+export type GradeAndProgress = {
+    grade: Grade;
+    progress: Progress;
+    name?: string;
+};
+export type UserActivityInfo = MappedUserInfo<ActivityState>;
+export declare const getCompletedUserInfosGradeAndProgress: (infos: UserActivityInfo[], scoreMaximum?: number, gradePreference?: "current" | "best") => GradeAndProgress[];
+export declare const getCurrentGrade: (services: {
+    lrs: LrsGateway;
+    ltiAuthProvider: AuthProvider;
+}, registration: string, options?: {
+    currentPreference?: "latest" | "oldest";
+    incompleteAttemptCallback?: (info: ActivityState) => Promise<GradeAndProgress>;
+    name?: string;
+    scoreMaximum?: number;
+    userId?: string;
+    gradePreference?: "current" | "best";
+}) => Promise<GradeAndProgress | null>;
+export declare const getAssignmentGrades: (services: {
+    accountsGateway: AccountsGateway;
+    lrs: LrsGateway;
+}, assignmentIRI: string, registration: string, options?: {
+    anyUser?: boolean;
+    currentPreference?: "latest" | "oldest";
+    incompleteAttemptsCallback?: (mappedInfo: UserActivityInfo[]) => Promise<GradeAndProgress[]>;
+    platformId?: string;
+    scoreMaximum?: number;
+    user?: string;
+    gradePreference?: "current" | "best";
+}) => Promise<GradeAndProgress[]>;

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

@@ -0,0 +1,145 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAssignmentGrades = exports.getCurrentGrade = exports.getCompletedUserInfosGradeAndProgress = exports.getScoreGrade = exports.getRegistrationAttemptInfo = void 0;
+const partition_1 = __importDefault(require("lodash/fp/partition"));
+const __1 = require("../..");
+const attempt_utils_1 = require("./attempt-utils");
+const getRegistrationAttemptInfo = async (lrs, registration, options) => {
+    const { currentPreference, ...xapiOptions } = options !== null && options !== void 0 ? options : {};
+    const allStatements = await lrs.getAllXapiStatements({ ...xapiOptions, registration });
+    // Partition statements for each user
+    const statementsPerUser = {};
+    allStatements.forEach((statement) => {
+        var _a;
+        // If we ever support accounts from different statement.actor.account.homePage, this method may need changes
+        // (unless we can guarantee the statement.actor.account.name are unique)
+        statementsPerUser[_a = statement.actor.account.name] || (statementsPerUser[_a] = []);
+        statementsPerUser[statement.actor.account.name].push(statement);
+    });
+    const result = {};
+    for (const [userUuid, userStatements] of Object.entries(statementsPerUser)) {
+        result[userUuid] = (0, attempt_utils_1.resolveAttemptInfo)(userStatements, { currentPreference });
+    }
+    return result;
+};
+exports.getRegistrationAttemptInfo = getRegistrationAttemptInfo;
+// generates a payload that can be sent to the LMS, documentation here:
+// lti: http://www.imsglobal.org/spec/lti-ags/v2p0#score-publish-service
+// ltijs: https://cvmcosta.me/ltijs/#/grading
+// Note: "min" is currently completely ignored
+const getScoreGrade = (score, options) => {
+    const { raw, scaled, max } = score;
+    const { maxScore, startedAt, submittedAt, 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;
+    }
+    return {
+        userId,
+        activityProgress: submittedAt ? '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',
+        scoreMaximum,
+        scoreGiven: (0, __1.roundToPrecision)(scoreGiven, -2),
+        submission,
+    };
+};
+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
+    return {
+        attempt: state.currentAttempt,
+        completed: state.currentAttemptCompleted,
+    };
+};
+const getCompletedActivityStateGradeAndProgress = ({ name, scoreMaximum, state, userId, gradePreference = 'current' }) => {
+    var _a;
+    const { attempt, completed } = pickAttemptAndCompleted(state, gradePreference);
+    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,
+        }),
+        progress: {
+            scaled: completed ? 1 : 0,
+        },
+        name,
+    };
+};
+const getCompletedUserInfosGradeAndProgress = (infos, scoreMaximum, gradePreference) => infos.map(({ data, fullName, platformUserId }) => getCompletedActivityStateGradeAndProgress({
+    name: fullName,
+    scoreMaximum,
+    userId: platformUserId,
+    state: data,
+    gradePreference,
+}));
+exports.getCompletedUserInfosGradeAndProgress = getCompletedUserInfosGradeAndProgress;
+const getCurrentGrade = async (services, registration, options) => {
+    var _a;
+    const user = await services.ltiAuthProvider.getUser();
+    if (!user) {
+        return null;
+    }
+    const userId = (_a = options === null || options === void 0 ? void 0 : options.userId) !== null && _a !== void 0 ? _a : user.uuid;
+    const { currentPreference, incompleteAttemptCallback, name, scoreMaximum, gradePreference, } = options !== null && options !== void 0 ? options : {};
+    const infoPerUser = await (0, exports.getRegistrationAttemptInfo)(services.lrs, registration, { currentPreference });
+    const userInfo = infoPerUser[user.uuid];
+    if (!userInfo) {
+        return getCompletedActivityStateGradeAndProgress({
+            name,
+            scoreMaximum,
+            state: (0, attempt_utils_1.resolveAttemptInfo)([]),
+            userId,
+            gradePreference,
+        });
+    }
+    if (userInfo.currentAttemptCompleted || !incompleteAttemptCallback) {
+        return getCompletedActivityStateGradeAndProgress({
+            name,
+            scoreMaximum,
+            state: userInfo,
+            userId,
+            gradePreference,
+        });
+    }
+    return incompleteAttemptCallback(userInfo);
+};
+exports.getCurrentGrade = getCurrentGrade;
+const getAssignmentGrades = async (services, assignmentIRI, registration, options) => {
+    const { anyUser, currentPreference, incompleteAttemptsCallback, platformId, scoreMaximum, user, gradePreference = 'current', } = options !== null && options !== void 0 ? options : {};
+    const infoPerUserUuid = await (0, exports.getRegistrationAttemptInfo)(services.lrs, registration, { activity: assignmentIRI, anyUser, currentPreference, user });
+    const mappedInfo = await services.accountsGateway.mapUserUuids(infoPerUserUuid, platformId);
+    // If no custom callback, just return graded results based on preference
+    if (!incompleteAttemptsCallback) {
+        return (0, exports.getCompletedUserInfosGradeAndProgress)(mappedInfo, scoreMaximum, gradePreference);
+    }
+    // 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;
+    })(mappedInfo);
+    return (0, exports.getCompletedUserInfosGradeAndProgress)(completedInfo, scoreMaximum, gradePreference).concat(await incompleteAttemptsCallback(incompleteInfo));
+};
+exports.getAssignmentGrades = getAssignmentGrades;

package/dist/cjs/services/postgresConnection/index.d.ts

@@ -0,0 +1,28 @@
+import postgres, { Sql } from 'postgres';
+import { ConfigProviderForConfig } from '../../config';
+import type { Logger } from '../logger';
+type Config = {
+    host: string;
+    readHost: string;
+    port: string;
+    database: string;
+    username: string;
+    password: string;
+};
+interface Initializer<C> {
+    configSpace?: C;
+}
+export declare const postgresConnection: <C extends string = "local">(initializer: Initializer<C>) => (configProvider: { [_key in C]: ConfigProviderForConfig<Config>; }) => (services: {
+    logger: Logger;
+}) => {
+    db: () => Promise<postgres.Sql<{}>>;
+    dbRead: () => Promise<postgres.Sql<{}>>;
+    migrate: (migrations: Migration[]) => Promise<void>;
+    down: () => Promise<void[]>;
+};
+export type PostgresConnection = ReturnType<ReturnType<ReturnType<typeof postgresConnection>>>;
+export interface Migration {
+    name: string;
+    up: (db: Sql) => Promise<void>;
+}
+export {};

package/dist/cjs/services/postgresConnection/index.js

@@ -0,0 +1,65 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.postgresConnection = void 0;
+const postgres_1 = __importDefault(require("postgres"));
+const assertions_1 = require("../../assertions");
+const config_1 = require("../../config");
+const guards_1 = require("../../guards");
+const helpers_1 = require("../../misc/helpers");
+const postgresConnection = (initializer) => (configProvider) => {
+    const config = configProvider[(0, guards_1.ifDefined)(initializer.configSpace, 'local')];
+    const host = (0, helpers_1.once)(() => (0, config_1.resolveConfigValue)(config.host));
+    const readHost = (0, helpers_1.once)(() => (0, config_1.resolveConfigValue)(config.readHost));
+    const connectionOptions = (0, helpers_1.once)(async () => ({
+        port: (0, assertions_1.assertNotNaN)(parseInt(await (0, config_1.resolveConfigValue)(config.port), 10), new Error('port must be a number')),
+        database: await (0, config_1.resolveConfigValue)(config.database),
+        username: await (0, config_1.resolveConfigValue)(config.username),
+        password: await (0, config_1.resolveConfigValue)(config.password),
+        transform: {
+            column: { to: postgres_1.default.fromCamel, from: postgres_1.default.toCamel },
+        },
+    }));
+    const connections = [];
+    const sql = (0, helpers_1.once)(async () => {
+        const options = await connectionOptions();
+        const connection = (0, postgres_1.default)({ ...options, host: await host() });
+        connections.push(connection);
+        return connection;
+    });
+    const sqlRead = (0, helpers_1.once)(async () => {
+        const options = await connectionOptions();
+        const connection = (0, postgres_1.default)({ ...options, host: await readHost() });
+        connections.push(connection);
+        return connection;
+    });
+    return (services) => ({
+        db: sql,
+        dbRead: sqlRead,
+        migrate: async (migrations) => {
+            await migrate(services, await sql(), migrations);
+        },
+        down: () => Promise.all(connections.map(c => c.end()))
+    });
+};
+exports.postgresConnection = postgresConnection;
+async function migrate(services, db, migrations) {
+    await db `
+    CREATE TABLE IF NOT EXISTS migrations (
+      id SERIAL PRIMARY KEY,
+      name TEXT NOT NULL,
+      ran_at TIMESTAMP NOT NULL DEFAULT NOW()
+    )
+  `;
+    const ranMigrations = await db `SELECT name FROM migrations`;
+    for (const migration of migrations) {
+        if (ranMigrations.some(({ name }) => name === migration.name)) {
+            continue;
+        }
+        services.logger.log(`Running migration ${migration.name}`);
+        await migration.up(db);
+        await db `INSERT INTO migrations (name) VALUES (${migration.name})`;
+    }
+}

package/dist/cjs/services/searchProvider/index.d.ts

@@ -0,0 +1,67 @@
+export type FieldType = string | string[] | number | boolean;
+export type ESFilter = {
+    terms: Record<string, FieldType>;
+} | {
+    term: Record<string, FieldType>;
+} | {
+    exists: {
+        field: string;
+    };
+} | {
+    nested: {
+        path: string;
+        query: Filter;
+    };
+} | {
+    bool: BoolFilter;
+};
+export type Filter = {
+    key: string;
+    value: FieldType;
+} | ESFilter;
+export type BoolFilter = {
+    must?: Filter[];
+    must_not?: Filter[];
+    should?: Filter[];
+    filter?: Filter[];
+    minimum_should_match?: number;
+};
+type Field = {
+    key: string;
+    type?: 'text';
+    weight: number;
+} | {
+    key: string;
+    type: 'keyword';
+} | {
+    key: string;
+    type: 'boolean';
+};
+export interface IndexOptions<T> {
+    body: T;
+    id: string;
+}
+export type FieldMapping = {
+    type: 'keyword' | 'text' | 'boolean';
+} | {
+    type: 'date';
+    format?: string;
+} | {
+    type?: 'nested' | 'object';
+    properties: Record<string, FieldMapping>;
+};
+export type FieldMappings = Record<string, FieldMapping>;
+export interface SearchOptions {
+    page?: number;
+    query: string | undefined;
+    fields: Field[];
+    filter?: Filter[];
+    must?: Filter[];
+    must_not?: Filter[];
+    should?: Filter[];
+    sort?: {
+        key: string;
+        order: 'asc' | 'desc';
+    }[];
+}
+export {};

package/dist/cjs/services/searchProvider/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/services/searchProvider/memorySearchTheBadWay.d.ts

@@ -0,0 +1,20 @@
+import { FieldMappings, IndexOptions, SearchOptions } from '.';
+export type Config<T> = {
+    mappings: FieldMappings;
+    store: {
+        loadAllDocumentsTheBadWay: () => Promise<T[]>;
+    };
+};
+export declare const memorySearchTheBadWay: () => <T>({ store, mappings }: Config<T>) => {
+    deleteIndexIfExists: () => Promise<undefined>;
+    ensureIndexCreated: () => Promise<undefined>;
+    index: (_options: IndexOptions<T>) => Promise<undefined>;
+    bulkIndex: (_items: IndexOptions<T>[]) => Promise<undefined>;
+    search: (options: SearchOptions) => Promise<{
+        items: T[];
+        pageSize: number;
+        currentPage: number;
+        totalItems: number;
+        totalPages: number;
+    }>;
+};