@openstax/ts-utils 1.21.11 → 1.23.0

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

@@ -0,0 +1,138 @@
+"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 (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __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,61 @@
+import { AccountsGateway, MappedUserInfo } from '../accountsGateway';
+import { AuthProvider } from '../authProvider';
+import { Logger } from '../logger';
+import { ActivityState } from './attempt-utils';
+import { LrsGateway } from '.';
+export interface Grade {
+    scoreGiven: number;
+    scoreMaximum: number;
+    comment?: string;
+    activityProgress: 'Initialized' | 'Started' | 'inProgress' | 'Submitted' | 'Completed';
+    gradingProgress: 'FullyGraded' | 'Pending' | 'PendingManual' | 'Failed' | 'NotReady';
+    userId?: string;
+}
+export declare const getRegistrationAttemptInfo: (lrs: LrsGateway, registration: string, options?: {
+    activity?: string | undefined;
+    anyUser?: boolean | undefined;
+    currentPreference?: "latest" | "oldest" | undefined;
+    ensureSync?: boolean | undefined;
+    user?: string | undefined;
+} | undefined) => Promise<{
+    [key: string]: ActivityState;
+}>;
+export declare const getScoreGrade: (score: {
+    scaled?: number;
+    raw?: number;
+    min?: number;
+    max?: number;
+}, completed: boolean, userId?: string | undefined, maxScore?: number | undefined) => Grade;
+export declare type Progress = {
+    scaled: number;
+    max?: number;
+    raw?: number;
+};
+export declare type GradeAndProgress = {
+    grade: Grade;
+    progress: Progress;
+    name?: string;
+};
+export declare const getCurrentGrade: (services: {
+    lrs: LrsGateway;
+    ltiAuthProvider: AuthProvider;
+}, registration: string, options?: {
+    currentPreference?: "latest" | "oldest" | undefined;
+    incompleteAttemptCallback?: ((info: ActivityState) => Promise<GradeAndProgress>) | undefined;
+    name?: string | undefined;
+    scoreMaximum?: number | undefined;
+    userId?: string | undefined;
+} | undefined) => Promise<GradeAndProgress | null>;
+export declare type UserActivityInfo = MappedUserInfo<ActivityState>;
+export declare const getAssignmentGrades: (services: {
+    accountsGateway: AccountsGateway;
+    lrs: LrsGateway;
+    logger: Logger;
+}, assignmentIRI: string, registration: string, options?: {
+    anyUser?: boolean | undefined;
+    currentPreference?: "latest" | "oldest" | undefined;
+    incompleteAttemptsCallback?: ((mappedInfo: UserActivityInfo[]) => Promise<GradeAndProgress[]>) | undefined;
+    platformId?: string | undefined;
+    scoreMaximum?: number | undefined;
+    user?: string | undefined;
+} | undefined) => Promise<GradeAndProgress[]>;

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

@@ -0,0 +1,94 @@
+"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.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
+const getScoreGrade = (score, completed, userId, maxScore) => {
+    const { raw, scaled, max } = score;
+    const scoreMaximum = maxScore !== null && maxScore !== void 0 ? maxScore : 100;
+    const scoreGiven = raw && max
+        ? scoreMaximum / max * raw
+        : scaled
+            ? scaled * scoreMaximum
+            : 0;
+    return {
+        userId,
+        activityProgress: 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',
+        scoreMaximum,
+        scoreGiven: (0, __1.roundToPrecision)(scoreGiven, -2),
+    };
+};
+exports.getScoreGrade = getScoreGrade;
+// These methods assign 0's to incomplete activities
+const getCompletedActivityStateGradeAndProgress = ({ name, scoreMaximum, state, userId }) => {
+    var _a, _b;
+    return ({
+        grade: (0, exports.getScoreGrade)(((_b = (_a = state.currentAttemptCompleted) === null || _a === void 0 ? void 0 : _a.result) === null || _b === void 0 ? void 0 : _b.score) || {}, !!state.currentAttemptCompleted, userId, scoreMaximum),
+        progress: {
+            scaled: state.currentAttemptCompleted ? 1 : 0,
+        },
+        name,
+    });
+};
+const getCompletedUserInfosGradeAndProgress = (infos, scoreMaximum) => infos.map(({ data, fullName, platformUserId }) => getCompletedActivityStateGradeAndProgress({
+    name: fullName, scoreMaximum, userId: platformUserId, state: data
+}));
+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 } = 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 });
+    }
+    if (userInfo.currentAttemptCompleted || !incompleteAttemptCallback) {
+        return getCompletedActivityStateGradeAndProgress({ name, scoreMaximum, state: userInfo, userId });
+    }
+    return incompleteAttemptCallback(userInfo);
+};
+exports.getCurrentGrade = getCurrentGrade;
+const getAssignmentGrades = async (services, assignmentIRI, registration, options) => {
+    const { anyUser, currentPreference, incompleteAttemptsCallback, platformId, scoreMaximum, user } = 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, services.logger, platformId);
+    if (!incompleteAttemptsCallback) {
+        return getCompletedUserInfosGradeAndProgress(mappedInfo, scoreMaximum);
+    }
+    const [incompleteInfo, completedInfo] = (0, partition_1.default)((info) => info.data.currentAttemptCompleted === undefined)(mappedInfo);
+    return getCompletedUserInfosGradeAndProgress(completedInfo, scoreMaximum).concat(await incompleteAttemptsCallback(incompleteInfo));
+};
+exports.getAssignmentGrades = getAssignmentGrades;

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

@@ -0,0 +1,35 @@
+import postgres, { Sql } from 'postgres';
+import { ConfigProviderForConfig } from '../../config';
+import type { Logger } from '../logger';
+declare 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]: {
+    host: import("../../config").ConfigValueProvider<string>;
+    readHost: import("../../config").ConfigValueProvider<string>;
+    port: import("../../config").ConfigValueProvider<string>;
+    database: import("../../config").ConfigValueProvider<string>;
+    username: import("../../config").ConfigValueProvider<string>;
+    password: import("../../config").ConfigValueProvider<string>;
+}; }) => (services: {
+    logger: Logger;
+}) => {
+    db: () => Promise<postgres.Sql<{}>>;
+    dbRead: () => Promise<postgres.Sql<{}>>;
+    migrate: (migrations: Migration[]) => Promise<void>;
+    down: () => Promise<void[]>;
+};
+export declare 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,63 @@
+"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: postgres_1.default.camel,
+    }));
+    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,31 @@
+export declare type Filter = {
+    key: string;
+    value: string | string[] | boolean;
+};
+declare 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 interface SearchOptions {
+    page?: number;
+    query: string | undefined;
+    fields: Field[];
+    /**
+     * @deprecated use `must` instead
+     */
+    filter?: Filter[];
+    must?: Filter[];
+    must_not?: Filter[];
+}
+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,14 @@
+import { IndexOptions, SearchOptions } from '.';
+export declare const memorySearchTheBadWay: <T>({ loadAllDocumentsTheBadWay }: {
+    loadAllDocumentsTheBadWay: () => Promise<T[]>;
+}) => {
+    ensureIndexCreated: () => Promise<undefined>;
+    index: (_options: IndexOptions<T>) => Promise<undefined>;
+    search: (options: SearchOptions) => Promise<{
+        items: T[];
+        pageSize: number;
+        currentPage: number;
+        totalItems: number;
+        totalPages: number;
+    }>;
+};

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

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.memorySearchTheBadWay = void 0;
+const __1 = require("../..");
+const errors_1 = require("../../errors");
+const guards_1 = require("../../guards");
+const MIN_MATCH = 0.5;
+const MAX_RESULTS = 10;
+var MatchType;
+(function (MatchType) {
+    MatchType[MatchType["Must"] = 0] = "Must";
+    MatchType[MatchType["MustNot"] = 1] = "MustNot";
+})(MatchType || (MatchType = {}));
+const resolveField = (document, field) => field.key.toString().split('.').reduce((result, key) => result[key], document);
+const memorySearchTheBadWay = ({ loadAllDocumentsTheBadWay }) => {
+    return {
+        ensureIndexCreated: async () => undefined,
+        index: async (_options) => undefined,
+        search: async (options) => {
+            const getFieldType = (field) => { var _a; return (_a = options.fields.find(f => f.key == field.key)) === null || _a === void 0 ? void 0 : _a.type; };
+            const results = (await loadAllDocumentsTheBadWay())
+                .map(document => {
+                let weight = 0;
+                const matchFilters = (filters, mustMatch) => {
+                    for (const field of filters) {
+                        const docValues = (0, __1.coerceArray)(resolveField(document, field));
+                        const coerceValue = getFieldType(field) === 'boolean'
+                            ? (input) => {
+                                if ([true, 'true', '1', 1].includes(input)) {
+                                    return true;
+                                }
+                                if ([false, 'false', '0', 0, ''].includes(input)) {
+                                    return false;
+                                }
+                                throw new errors_1.InvalidRequestError('input is not a valid boolean filter');
+                            }
+                            : (x) => x;
+                        const hasMatch = (0, __1.coerceArray)(field.value).map(coerceValue).some(v => docValues.includes(v));
+                        if ((mustMatch === MatchType.Must && !hasMatch) || (mustMatch === MatchType.MustNot && hasMatch)) {
+                            return false;
+                        }
+                    }
+                    return true;
+                };
+                if (options.query !== undefined) {
+                    for (const field of options.fields) {
+                        if (field.type !== undefined && field.type !== 'text') {
+                            continue;
+                        }
+                        const value = resolveField(document, field);
+                        if (value === undefined || value === null) {
+                            continue;
+                        }
+                        if (typeof value === 'string') {
+                            if (value.toUpperCase().indexOf(options.query.toUpperCase()) !== -1) {
+                                weight += (1 * field.weight);
+                            }
+                        }
+                        else {
+                            throw new Error(`invalid value type when searching in field ${field.key.toString()}`);
+                        }
+                    }
+                }
+                const { must_not } = options;
+                const must = 'filter' in options ? options.filter : options.must;
+                if ((must === null || must === void 0 ? void 0 : must.length) && !matchFilters(must, MatchType.Must)) {
+                    return undefined;
+                }
+                if ((must_not === null || must_not === void 0 ? void 0 : must_not.length) && !matchFilters(must_not, MatchType.MustNot)) {
+                    return undefined;
+                }
+                return { document, weight };
+            })
+                .filter(guards_1.isDefined)
+                .filter(r => !options.query || r.weight >= MIN_MATCH);
+            results.sort((a, b) => b.weight - a.weight);
+            const page = options.page || 1;
+            const offset = (page - 1) * MAX_RESULTS;
+            return {
+                items: results.slice(offset, offset + MAX_RESULTS).map(r => r.document),
+                pageSize: MAX_RESULTS,
+                currentPage: page,
+                totalItems: results.length,
+                totalPages: Math.ceil(results.length / MAX_RESULTS)
+            };
+        },
+    };
+};
+exports.memorySearchTheBadWay = memorySearchTheBadWay;