@ueu/ueu-canvas 0.0.2 → 0.0.4

package/src/enrollments/getEnrollmentGenerator.ts

@@ -1,79 +0,0 @@
-import {getPagedDataGenerator} from "@/fetch/getPagedDataGenerator";
-import {HasUser} from "@/canvasDataDefs";
-import {EnrollmentRole} from "@/enrollments/enrollmentRole";
-import {EnrollmentData, EnrollmentState, EnrollmentType, EnrollmentUserState} from "@/enrollments/EnrollmentTypes";
-
-
-export type EnrollmentInclude = 'avatar_url' |
-    'group_ids' |
-    'locked' |
-    'observed_users' |
-    'can_be_removed' |
-    'uuid' |
-    'current_points'
-
-type EnrollmentGenQueryConfig = {
-    type?: EnrollmentType[],
-    role?: EnrollmentRole[],
-    include?: EnrollmentInclude[],
-    state?: EnrollmentState[],
-    grading_period_id?: number,
-    sis_account_id?: number | number[],
-
-} & ({
-    sis_user_id: number | number[],
-    created_for_sis_user_id: true,
-} | {
-    sis_user_id?: never,
-    created_for_sis_user_id?: false,
-})
-
-
-export type GetEnrollmentSectionGenConfig = {
-    sectionId: number;
-    queryParams: EnrollmentGenQueryConfig & {
-        user_id?: string
-    }
-};
-
-
-export type GetEnrollmentUserGenConfig = {
-    userId: number;
-    queryParams: EnrollmentGenQueryConfig & {
-        state?: EnrollmentUserState;
-        enrollment_term_id?: number;
-    }
-};
-
-export type GetEnrollmentCourseGenConfig = {
-    courseId: number;
-    queryParams: EnrollmentGenQueryConfig & {
-        user_id?: string,
-    }
-}
-
-
-export type GetEnrollmentGenConfig = GetEnrollmentUserGenConfig | GetEnrollmentCourseGenConfig | GetEnrollmentSectionGenConfig;
-
-
-export const getEnrollmentGenerator = ( config: GetEnrollmentGenConfig) => {
-    let url: string;
-
-
-    const { queryParams, ...internalParams } = config;
-    if ('userId' in config) {
-        url = `/api/v1/users/${config.userId}/enrollments`;
-    } else if ('courseId' in config) {
-        url = `/api/v1/courses/${config.courseId}/enrollments`;
-    } else  if ('sectionId' in config) {
-        url = `/api/v1/sections/${config.sectionId}/enrollments`;
-    } else {
-        throw new Error('config type not recognized')
-    }
-
-
-
-    return getPagedDataGenerator<EnrollmentData>(url, {
-        queryParams,
-    });
-}

package/src/enrollments/index.ts

@@ -1,3 +0,0 @@
-export * from "./enrollmentRole";
-export * from './getEnrollmentGenerator'
-export * from './EnrollmentTypes'

package/src/fetch/__mocks__/fetchJson.ts

@@ -1 +0,0 @@
-export const fetchJson = jest.fn((async () => ({ id: 0 })));

package/src/fetch/__mocks__/getPagedDataGenerator.ts

@@ -1,8 +0,0 @@
-import requireActual = jest.requireActual;
-import {mockAsyncGen} from "@/__mocks__/utils";
-
-
-const actual = requireActual('../getPagedDataGenerator');
-export const getPagedDataGenerator = jest.fn(() => mockAsyncGen([]));
-export const getPagedData = jest.fn();
-export const mergePagedDataGenerators = jest.fn(actual.mergedPagedDataGenerators)

package/src/fetch/__mocks__/index.ts

@@ -1,6 +0,0 @@
-const actual = jest.requireActual('../utils');
-
-export const overrideConfig = jest.fn(actual.overrideConfig)
-export const canvasDataFetchGenFunc = jest.fn(actual.canvasDataFetchGenFunc);
-
-export const fetchGetConfig = jest.fn(actual.fetchGetConfig)

package/src/fetch/apiGetConfig.ts

@@ -1,10 +0,0 @@
-import {ICanvasCallConfig, IQueryParams} from "@canvas/canvasUtils";
-import {overrideConfig} from "@canvas/fetch/utils";
-
-export function apiGetConfig(queryParams: IQueryParams, baseConfig?: ICanvasCallConfig) {
-    return overrideConfig({
-        queryParams,
-    }, baseConfig);
-}
-
-export default apiGetConfig;

package/src/fetch/apiWriteConfig.ts

@@ -1,13 +0,0 @@
-import {formDataify, ICanvasCallConfig} from "@canvas/canvasUtils";
-import {overrideConfig} from "@canvas/fetch/utils";
-
-export function apiWriteConfig(method: 'POST' | 'PUT', data: Record<string, any>, baseConfig?: ICanvasCallConfig) {
-    const body = formDataify(data);
-    return overrideConfig({
-        fetchInit: {
-            method,
-            body,
-        }
-    }, baseConfig);
-}
-export default apiWriteConfig;

package/src/fetch/canvasDataFetchGenFunc.ts

@@ -1,20 +0,0 @@
-import {ICanvasCallConfig} from "@/canvasUtils";
-import {CanvasData} from "@/canvasDataDefs";
-import {getPagedDataGenerator} from "@/fetch/getPagedDataGenerator";
-import {overrideConfig} from "@canvas/fetch/utils";
-
-
-type UrlFuncType<UrlParams extends Record<string, any>> = (args: UrlParams, config?: ICanvasCallConfig) => string
-
-export function canvasDataFetchGenFunc<
-    Content extends CanvasData,
-    UrlParams extends Record<string, any>
->(urlFunc: UrlFuncType<UrlParams>, defaultConfig?: ICanvasCallConfig) {
-
-    return function (args: UrlParams, config?: ICanvasCallConfig) {
-        config = overrideConfig(defaultConfig, config);
-        const url = urlFunc(args, config);
-        return getPagedDataGenerator<Content>(url, config);
-    }
-}
-

package/src/fetch/fetchJson.ts

@@ -1,22 +0,0 @@
-import {ICanvasCallConfig} from "@/canvasUtils";
-
-export async function fetchJson<T = Record<string, any>>(
-    url: string, config: ICanvasCallConfig | null = null
-): Promise<T> {
-    const match = url.search(/^(\/|\w+:\/\/)/);
-    if (match < 0) throw new Error("url does not start with / or http")
-    if (config?.queryParams) {
-        url += '?' + new URLSearchParams(config.queryParams);
-    }
-    config ??= {};
-
-
-    const response = await fetch(url, config.fetchInit);
-    const responseJson = await response.json() as (T & { retrieved_at?: string }) | undefined;
-    if(!responseJson) throw new Error("Could not fetch json");
-
-    responseJson.retrieved_at = new Date().toISOString();
-    return responseJson;
-}
-
-

package/src/fetch/getPagedDataGenerator.ts

@@ -1,157 +0,0 @@
-import {CanvasData} from "@/canvasDataDefs";
-import {ICanvasCallConfig, searchParamsFromObject} from "@/canvasUtils";
-
-/**
- * @param url The entire path of the url
- * @param config a configuration object of type ICanvasCallConfig
- * @returns {Promise<Record<string, any>[]>}
- */
-export async function getPagedData<T extends CanvasData = CanvasData>(
-    url: string, config: ICanvasCallConfig | null = null
-): Promise<T[]> {
-
-    const generator = getPagedDataGenerator<T>(url, config);
-
-    const out: T[] = [];
-    for await (const value of generator) {
-        out.push(value);
-    }
-    return out;
-}
-
-/**
- * Merges multiple asynchronous paginated data generators into a single generator.
- *
- * This function combines the results of multiple paginated data generators into a unified stream. Each generator
- * is processed sequentially, and its results are yielded one by one as they become available. This allows for
- * easy handling of multiple paginated API requests or data sources in parallel without needing to collect all
- * results in memory at once.
- *
- * The function is particularly useful when dealing with multiple sources of paginated data (e.g., multiple API
- * endpoints) that need to be processed as one continuous stream of results, without waiting for all pages from one
- * source to finish before beginning to process the next.
- *
- * @template T - A type parameter that extends `CanvasData`, ensuring that the data being yielded is in a format consistent
- *               with Canvas API data structures.
- * @param {AsyncGenerator<T, T[], void>[]} generators - An array of asynchronous generators, each of which yields paginated
- *               results of type `T`. These could represent different paginated data sources that are combined into a single stream.
- *
- * @yields {T} - The function yields items of type `T` as they are retrieved from each generator in sequence.
- *
- * @example
- * // Example usage combining two paginated API responses into a single data stream
- * const generator1 = fetchPagedDataFromSource1();
- * const generator2 = fetchPagedDataFromSource2();
- *
- * for await (const data of mergePagedDataGenerators([generator1, generator2])) {
- *     console.log(data); // Process each item from both generators as a single stream
- * }
- *
- */
-export async function* mergePagedDataGenerators<T extends CanvasData = CanvasData, Return = T[]>(generators: AsyncGenerator<T, Return, void>[]) {
-    for (const generator of generators) {
-        for await (const result of generator) {
-            yield result;
-        }
-    }
-}
-
-
-
-/**
- * Handles the response data from a Canvas API call, normalizing it into an array of `CanvasData` objects.
- *
- * This function accepts various formats of the data (single object, array of objects, or a keyed object containing arrays of objects),
- * and ensures the result is always an array. If no valid array is found, it returns an empty array and logs a warning.
- *
- * @template T - A type that extends `CanvasData`.
- * @param {T | T[] | { [key: string]: T[] }} data - The response data to process. This can be a single object, an array of objects,
- *        or a keyed object where the values are arrays of objects.
- * @param {string} url - The URL from which the data was retrieved, used for logging purposes if no valid data is found.
- * @returns {T[]} An array of `CanvasData` objects, or an empty array if no valid array of data is present.
- */
-function handleResponseData<T extends CanvasData>(data: undefined | null | T | T[] | { [key: string]: T[] }, url: string): T[] {
-    if(typeof data === 'undefined' || data == null) {
-        console.warn(`no data found for ${url}`)
-        return [] as T[]
-    }
-    if (typeof data === 'object' && !Array.isArray(data)) {
-        const values = Array.from(Object.values(data));
-        if (values) {
-            data = values.find((a) => Array.isArray(a)) as T[];
-        }
-    }
-    if (!Array.isArray(data)) {
-        console.warn(`No valid data found for ${url}`);
-        return [] as T[];
-    }
-    return data;
-}
-
-
-/**
- * Async generator function that retrieves paged data from a Canvas API endpoint.
- * It sends HTTP GET requests to the provided URL, processes the results, and iterates
- * through all pages of data, yielding each individual item.
- *
- * The generator automatically handles pagination by examining the 'Link' header
- * returned in each response and fetching the next page as long as a 'next' link is available.
- *
- * @template T - A generic type parameter extending CanvasData to represent the structure of the data.
- * @param {string} url - The full URL for the API request. If the `queryParams` option is provided in the config, it appends the query parameters to the URL.
- * @param {ICanvasCallConfig | null} [config=null] - Optional configuration object for the request, including query parameters and additional fetch options like headers.
- * @yields {T} - Yields individual items of the retrieved data from each page, one at a time.
- *
- * @throws {Error} - If the request fails or the URL contains "undefined", a warning is logged to the console.
- *
- * @example
- * ```
- * const generator = getPagedDataGenerator<MyDataType>('https://canvas.example.com/api/data', config);
- * for await (const item of generator) {
- *     console.log(item);  // Handle each item individually
- * }
- * ```
- */
-export async function* getPagedDataGenerator<T extends CanvasData = CanvasData>(
-    url: string, config: ICanvasCallConfig | null = null
-): AsyncGenerator<T> {
-
-    if (config?.queryParams) {
-        url += '?' + searchParamsFromObject(config.queryParams);
-    }
-
-    if (url.includes('undefined')) {
-        console.warn(url);
-    }
-
-
-    /* Returns a list of data from a GET request, going through multiple pages of data requests as necessary */
-    let response = await fetch(url, config?.fetchInit);
-    const data = handleResponseData<T>(await response.json(), url);
-    if (data.length === 0) return data;
-    for (const value of data) yield value;
-
-    let next_page_link = "!";
-    while (next_page_link.length !== 0 &&
-    response &&
-    response.ok) {
-        const nextLink = getNextLink(response);
-        if (!nextLink) break;
-        next_page_link = nextLink.split(";")[0].split("<")[1].split(">")[0];
-        response = await fetch(next_page_link, config?.fetchInit);
-        const responseData = handleResponseData<T>(await response.json(), url);
-
-
-        for (const value of responseData) {
-            value.retrieved_at = new Date().toISOString();
-            yield value;
-        }
-    }
-}
-
-function getNextLink(response: Response) {
-    const link = response.headers.get("Link");
-    if (!link) return null;
-    const paginationLinks = link.split(",");
-    return paginationLinks.find((link) => link.includes('next'));
-}

package/src/fetch/utils.ts

@@ -1,16 +0,0 @@
-import {deepObjectMerge, ICanvasCallConfig} from "@/canvasUtils";
-
-export function overrideConfig<ConfigType extends ICanvasCallConfig | undefined>(
-    source: ConfigType | undefined,
-    override: ConfigType | undefined
-) {
-
-    return deepObjectMerge(source, override) ?? {} as ConfigType;
-}
-
-export function fetchGetConfig<CallOptions extends Record<string, any>>(options: CallOptions, baseConfig?: ICanvasCallConfig<CallOptions>) {
-    return overrideConfig(baseConfig, {
-        queryParams: options,
-    });
-}
-

package/src/files.ts

@@ -1,60 +0,0 @@
-import {formDataify} from "./canvasUtils";
-import assert from "assert";
-
-export interface IFile {
-    "id": number,
-    "uuid": string,
-    "folder_id": number,
-    "display_name": string,
-    "filename": string,
-    "content-type": string,
-    "url": string,
-    "size": number,
-    "created_at": string,
-    "updated_at": string,
-    "unlock_at"?: string,
-    "locked": boolean,
-    "hidden": boolean,
-    "lock_at"?: string,
-    "hidden_for_user": boolean,
-    "visibility_level"?: "course" | "institution" | "public" | "inherit",
-    "thumbnail_url"?: string | null,
-    "modified_at": string,
-    // simplified content-type mapping
-    "mime_class": string,
-    // identifier for file in third-party transcoding service
-    "media_entry_id"?: string,
-    "locked_for_user": boolean,
-    "lock_info"?: any,
-    "lock_explanation"?: string,
-    "preview_url"?: string
-}
-
-export async function uploadFile(file: File, folderId:number, url:string): Promise<void>
-export async function uploadFile(file: File, path:string, url:string): Promise<void>
-export async function uploadFile(file: File, folder: string|number, url:string) {
-    const initialParams: Record<string, any> = {
-        name: file.name,
-        no_redirect: true,
-        on_duplicate: 'overwrite'
-    }
-
-    if(typeof folder === 'number') initialParams.parent_folder_id = folder;
-    else initialParams.parent_folder_path = folder;
-    let response = await fetch(url, {
-        body: formDataify(initialParams),
-        method: 'POST'
-    });
-    const data = await response.json();
-    const uploadParams = data.upload_params;
-    const uploadFormData = formDataify(uploadParams);
-    uploadFormData.append('file', file);
-
-
-    response = await fetch(data.upload_url, {
-        method: 'POST',
-        body: uploadFormData,
-    })
-    assert(response.ok);
-}
-

package/src/fixes/annotations.ts

@@ -1,105 +0,0 @@
-import {ContentFix, findReplaceFunc, FixFailureResult, notInTest, runReplacements} from "./index";
-
-import {Course} from "../course/Course";
-import {Page} from "@/content/pages/Page";
-
-const removeMediaPlaceholder = {
-    run: findReplaceFunc(/<p>\[Text[^\]]*by SME[^\]]*]<\/p>/, ''),
-    tests: [notInTest(/<p>\[Text[^\]]*by SME[^\]]*]<\/p>/)]
-}
-
-const removeInsertAnnotationForMedia = {
-    run: findReplaceFunc(/\[[iI]nsert annotation for media]/, ''),
-    tests: [notInTest(/\[.*annotation,.*]/)]
-}
-
-const removeSecondaryMediaTitle = {
-    run: findReplaceFunc(/<h3>\[Title for <span style="text-decoration: underline;"> optional <\/span>secondary media element\]<\/h3>/, ''),
-    tests: [notInTest('secondary media element]')]
-}
-
-const removeBlockQuote = {
-    run: function(input: string) {
-        const el = document.createElement('div');
-        el.innerHTML = input;
-        const bqElement = el.querySelector('blockquote');
-        if (bqElement?.innerHTML.includes('SME')) {
-            bqElement.parentElement?.parentElement?.remove();
-        }
-        const output = el.innerHTML;
-        el.remove();
-        return output;
-    },
-    tests: [notInTest(/\[Pull quote -/)]
-}
-
-
-const removeLmNarrativePlaceholder = {
-    run: function(input:string) {
-        const el =  document.createElement('div');
-        el.innerHTML = input;
-        const divs = el.querySelectorAll<HTMLDivElement>('div.cbt-content');
-        const toRemove = Array.from(divs).filter((div) => div.innerHTML.includes('LM Narrative'));
-        for(const element of toRemove) element.remove();
-        const output = el.innerHTML;
-        el.remove();
-        return output;
-    },
-    tests: [
-        notInTest(/LM Narrative/)
-    ]
-}
-
-const contentFixes: ContentFix[] = [
-    removeMediaPlaceholder,
-    removeLmNarrativePlaceholder,
-    removeInsertAnnotationForMedia,
-    removeSecondaryMediaTitle,
-    removeBlockQuote,
-]
-
-
-/**
- * Removes annotation placeholder text from Learning Materials in the course
- * @param course
- */
-async function fixLmAnnotations(course:Course) {
-    const pages = await course.getPages({
-        queryParams: {
-            include: ['body'],
-            search_term: 'learning materials'
-        }
-    });
-    const pendingUpdates: Promise<any>[] = [];
-    const fixedPages: Page[] = [];
-    const unchangedPages: Page[] = [];
-    const failedPages: Page[]  = [];
-    const failedFixes: FixFailureResult<string>[] = [];
-
-    for (const page of pages) {
-        const sourceHtml = page.body;
-        const fix = runReplacements(contentFixes, sourceHtml);
-        const fixedValue = fix.output;
-
-        if(fix.failedFixes.length > 0) {
-            failedPages.push(page);
-            console.log(page);
-            console.log(fix);
-        }
-        if(sourceHtml === fixedValue) {
-            console.log(sourceHtml.length - fixedValue.length)
-            console.log(`Page unchanged ${page.name}`)
-            unchangedPages.push(page);
-        } else {
-            console.log(`fixed ${page.name}`)
-            pendingUpdates.push(page.updateContent(fixedValue));
-            fixedPages.push(page);
-        }
-    }
-
-    await Promise.all(pendingUpdates);
-    return {fixedPages, unchangedPages, failedPages}
-}
-
-
-export { contentFixes, fixLmAnnotations };

package/src/fixes/index.ts

@@ -1,81 +0,0 @@
-export type ContentFix<T = string> = {
-    preflightTests?: ((potentialOutput: T) => boolean)[],
-    tests?: ((potentialOutput: T) => boolean)[],
-    run: (value: T) => T
-}
-
-export type FixFailureResult<T> = {
-    failedFixes: ContentFix<T>[],
-    output: T
-}
-/**
- * Runs through a series of Content Fixes. If all is well, passes the results into the next
- * content fix.
- * Each ContentFix can have tests and preflight tests. Preflight tests are run before the fix is attempted
- * Tests are fun after.
- * If any of these tests fail, that content fix is not run on the text, instead passing the previous value.
- * @param fixes
- * @param source
- */
-export function runReplacements<T extends {toString:()=>string} = string>(fixes: ContentFix<T>[], source: T) {
-const failedFixes: ContentFix<T>[]= [];
-    const output: T = fixes.reduce((accumulator, {run, tests, preflightTests}) => {
-        // run through all preflight tests, if any of them fail, return the pre-transformation value
-        if (preflightTests && preflightTests.map((test) => test(output)).includes(false)) return accumulator;
-        const output = run(accumulator);
-        // run through all tests, if any of them fail, return the pre-transformation value
-        if (tests && tests.map((test) => test(output)).includes(false)) {
-            failedFixes.push({run, tests, preflightTests})
-            return accumulator;
-        }
-        return output;
-    }, source);
-
-    return {failedFixes, output} as FixFailureResult<T>;
-}
-
-export function findReplaceFunc(find:string|RegExp, replace:string) {
-    return (source: string) => {
-        const output = source.replace(find, replace);
-        return output;
-    };
-}
-
-/**
- * Returns a function that returns true if passed a string that contains the find value or matches the find RegEx, false otherwise
- * @param find A regular expression to check the input string against, or a substring to check if the input string contains
- * @param caseSensitive (string find only) whether to match the string case sensitive-ly
- */
-export function inTest(find:string|RegExp, caseSensitive=true) {
-    if(typeof find === "string") {
-        const findValue = caseSensitive ? find : find.toLowerCase();
-        return (source: string) => (caseSensitive ? source : source.toLowerCase()).includes(findValue);
-    } else {
-        return (source:string) => {
-
-
-            return !!source.match(find);
-        }
-    }
-}
-
-/**
- * Returns a function that returns false if passed a string that contains the find value or matches the find RegEx, true otherwise
- * @param find A regular expression to check the input string against, or a substring to check if the input string contains
- * @param caseSensitive (string find only) whether to match the string case sensitive-ly
- */
-export function notInTest(find: string|RegExp, caseSensitive = true) {
-    if(typeof find === "string") {
-        const findValue = caseSensitive ? find : find.toLowerCase();
-        return (source: string) => {
-            return !((caseSensitive ? source : source.toLowerCase()).includes(findValue));
-        }
-    } else {
-        return (source:string) => {
-
-            return !source.match(find);
-        }
-    }
-}
-
-export * from './annotations'