@openstax/ts-utils 1.33.0 → 1.34.0

package/packages/utils/src/services/exercisesGateway/index.spec.ts

@@ -0,0 +1,326 @@
+import {v4 as newUuid} from 'uuid';
+import { Config, exercisesGateway } from '.';
+
+const exercises_search_digest = '97ba6c8b5017cdec25dd2911e58586884571d155eb30018afca03f556822943e';
+
+afterEach(() => {
+  jest.clearAllMocks();
+});
+
+describe('exercisesGateway', () => {
+  let fetchSpy: jest.SpyInstance;
+  const config = {
+    exercises: {
+      exercisesHost: 'exercisesHostString',
+      exercisesAuthToken: 'exercisesAuthTokenString',
+    } as Config
+  };
+
+  const exercises = () => exercisesGateway({fetch: fetchSpy as any})(config)({});
+
+  beforeEach(() => {
+    fetchSpy = jest.fn();
+  });
+
+  describe('searchDigest', () => {
+    it('returns the exercises search digest', async() => {
+      fetchSpy.mockReturnValue(Promise.resolve(
+        {
+          headers: {
+            get: (name: string) => {
+              expect(name).toBe('X-Digest');
+              return exercises_search_digest;
+            }
+          }
+        }
+      ));
+      const result = await exercises().searchDigest('content:"everything"');
+      expect(fetchSpy.mock.calls[0]).toMatchInlineSnapshot(`
+[
+  "exercisesHostString/api/exercises?page=1&per_page=100&query=content%3A%22everything%22",
+  {
+    "headers": {
+      "Authorization": "Bearer exercisesAuthTokenString",
+    },
+    "method": "HEAD",
+  },
+]
+`);
+      expect(result).toEqual(exercises_search_digest);
+    });
+  });
+
+  describe('search', () => {
+    it('returns exercises matching the query string', async() => {
+      const items = [{
+        images: [],
+        tags: [],
+        uuid: newUuid(),
+        group_uuid: newUuid(),
+        number: 1,
+        version: 1,
+        uid: '1@1',
+        published_at: new Date().toISOString(),
+        solutions_are_public: true,
+        authors: [],
+        copyright_holders: [],
+        derived_from: [],
+        is_vocab: false,
+        questions: [
+          {
+            id: 1,
+            is_answer_order_important: false,
+            stimulus_html: 'Some background info',
+            stem_html: 'What is the meaning of life, the universe, and everything?',
+            answers: [
+              {
+                id: 1,
+                content_html: '42',
+                correctness: '1.0',
+                feedback_html: 'Correct',
+              },
+              {
+                id: 2,
+                content_html: '21',
+                correctness: '0.0',
+                feedback_html: 'Try again',
+              }
+            ],
+            hints: [],
+            formats: ['multiple-choice', 'free-response'],
+            combo_choices: [],
+            collaborator_solutions: [],
+            community_solutions: [],
+          }
+        ],
+        delegations: [],
+        versions: [1],
+      }];
+      fetchSpy.mockReturnValue(Promise.resolve(
+        {
+          headers: {
+            get: (name: string) => {
+              expect(name).toBe('X-Digest');
+              return exercises_search_digest;
+            }
+          },
+          json: () => ({total_count: 1, items})
+        }
+      ));
+      const result = await exercises().search('content:"everything"');
+      expect(fetchSpy.mock.calls[0]).toMatchInlineSnapshot(`
+[
+  "exercisesHostString/api/exercises?page=1&per_page=100&query=content%3A%22everything%22",
+  {
+    "headers": {
+      "Authorization": "Bearer exercisesAuthTokenString",
+    },
+    "method": "GET",
+  },
+]
+`);
+      expect(result).toEqual({digest: exercises_search_digest, items, total_count: 1});
+    });
+  });
+
+  describe('get', () => {
+    const uuid = '3211b45b-14d9-4d44-9054-654f90798dc9';
+
+    it('returns a single exercise matching the uuid', async() => {
+      const exercise = {
+        images: [],
+        tags: [],
+        uuid,
+        group_uuid: newUuid(),
+        number: 1,
+        version: 1,
+        uid: '1@1',
+        published_at: new Date().toISOString(),
+        solutions_are_public: true,
+        authors: [],
+        copyright_holders: [],
+        derived_from: [],
+        is_vocab: false,
+        questions: [
+          {
+            id: 1,
+            is_answer_order_important: false,
+            stimulus_html: 'Some background info',
+            stem_html: 'What is the meaning of life, the universe, and everything?',
+            answers: [
+              {
+                id: 1,
+                content_html: '42',
+                correctness: '1.0',
+                feedback_html: 'Correct',
+              },
+              {
+                id: 2,
+                content_html: '21',
+                correctness: '0.0',
+                feedback_html: 'Try again',
+              }
+            ],
+            hints: [],
+            formats: ['multiple-choice', 'free-response'],
+            combo_choices: [],
+            collaborator_solutions: [],
+            community_solutions: [],
+          }
+        ],
+        delegations: [],
+        versions: [1],
+      };
+      fetchSpy.mockReturnValue(Promise.resolve({status: 200, json: () => Promise.resolve(exercise)}));
+      const result = await exercises().get(uuid);
+      expect(fetchSpy.mock.calls[0]).toMatchInlineSnapshot(`
+[
+  "exercisesHostString/api/exercises/3211b45b-14d9-4d44-9054-654f90798dc9",
+  {
+    "headers": {
+      "Authorization": "Bearer exercisesAuthTokenString",
+    },
+    "method": "GET",
+  },
+]
+`);
+      expect(result).toEqual(exercise);
+    });
+
+    it('default correctness does nothing if correctness info is present', async() => {
+      const exercise = {
+        images: [],
+        tags: [],
+        uuid,
+        group_uuid: newUuid(),
+        number: 1,
+        version: 1,
+        uid: '1@1',
+        published_at: new Date().toISOString(),
+        solutions_are_public: true,
+        authors: [],
+        copyright_holders: [],
+        derived_from: [],
+        is_vocab: false,
+        questions: [
+          {
+            id: 1,
+            is_answer_order_important: false,
+            stimulus_html: 'Some background info',
+            stem_html: 'What is the meaning of life, the universe, and everything?',
+            answers: [
+              {
+                id: 1,
+                content_html: '42',
+                correctness: '1.0',
+                feedback_html: 'Correct',
+              },
+              {
+                id: 2,
+                content_html: '21',
+                correctness: '0.0',
+                feedback_html: 'Try again',
+              }
+            ],
+            hints: [],
+            formats: ['multiple-choice', 'free-response'],
+            combo_choices: [],
+            collaborator_solutions: [],
+            community_solutions: [],
+          }
+        ],
+        delegations: [],
+        versions: [1],
+      };
+      config.exercises.defaultCorrectness = 'true';
+      fetchSpy.mockReturnValue(Promise.resolve({status: 200, json: () => Promise.resolve(exercise)}));
+      const result = await exercises().get(uuid);
+      expect(result).toEqual(exercise);
+    });
+
+    it('adds default correctness', async() => {
+      const exercise = {
+        images: [],
+        tags: [],
+        uuid,
+        group_uuid: newUuid(),
+        number: 1,
+        version: 1,
+        uid: '1@1',
+        published_at: new Date().toISOString(),
+        solutions_are_public: true,
+        authors: [],
+        copyright_holders: [],
+        derived_from: [],
+        is_vocab: false,
+        questions: [
+          {
+            id: 1,
+            is_answer_order_important: false,
+            stimulus_html: 'Some background info',
+            stem_html: 'What is the meaning of life, the universe, and everything?',
+            answers: [
+              {
+                id: 1,
+                content_html: '42',
+                feedback_html: 'Correct',
+              },
+              {
+                id: 2,
+                content_html: '21',
+                feedback_html: 'Try again',
+              }
+            ],
+            hints: [],
+            formats: ['multiple-choice', 'free-response'],
+            combo_choices: [],
+            collaborator_solutions: [],
+            community_solutions: [],
+          }
+        ],
+        delegations: [],
+        versions: [1],
+      };
+      config.exercises.defaultCorrectness = 'true';
+      fetchSpy.mockReturnValue(Promise.resolve({status: 200, json: () => Promise.resolve(exercise)}));
+      const result = await exercises().get(uuid);
+      expect(result?.questions[0].stem_html).toMatchInlineSnapshot(`
+"What is the meaning of life, the universe, and everything?
+<br><em>random default: the correct answer is 2: 21</em>"
+`);
+      expect(result?.questions[0].answers).toMatchInlineSnapshot(`
+[
+  {
+    "content_html": "42",
+    "correctness": "0.0",
+    "feedback_html": "<em>random default: the correct answer is 2: 21</em>",
+    "id": 1,
+  },
+  {
+    "content_html": "21",
+    "correctness": "1.0",
+    "feedback_html": "This is the good one!",
+    "id": 2,
+  },
+]
+`);
+    });
+
+    it('returns returns undefined on 404 error', async() => {
+      fetchSpy.mockReturnValue(Promise.resolve({status: 404, json: () => {return {};}}));
+      const result = await exercises().get(uuid);
+      expect(fetchSpy.mock.calls[0]).toMatchInlineSnapshot(`
+[
+  "exercisesHostString/api/exercises/3211b45b-14d9-4d44-9054-654f90798dc9",
+  {
+    "headers": {
+      "Authorization": "Bearer exercisesAuthTokenString",
+    },
+    "method": "GET",
+  },
+]
+`);
+      expect(result).toBeUndefined();
+    });
+  });
+});

package/packages/utils/src/services/exercisesGateway/index.ts

@@ -0,0 +1,163 @@
+import * as queryString from 'query-string';
+import { once } from '../..';
+import { assertString } from '../../assertions';
+import { ConfigProviderForConfig, resolveConfigValue } from '../../config';
+import { GenericFetch } from '../../fetch';
+import { ifDefined } from '../../guards';
+import { METHOD } from '../../routing';
+
+export type Config = {
+  defaultCorrectness?: string;
+  exercisesHost: string;
+  exercisesAuthToken: string;
+};
+interface Initializer<C> {
+  configSpace?: C;
+  fetch: GenericFetch;
+}
+
+// These types are slightly different from the frontend types
+// Object types that I don't expect us to use have been left as any[]
+export type Answer = {
+  id: number;
+  content_html: string;
+  correctness?: string;
+  feedback_html?: string;
+};
+
+export type Solution = {
+  images: any[];
+  solution_type: string;
+  content_html: string;
+};
+
+export type Question = {
+  id: number;
+  is_answer_order_important: boolean;
+  stimulus_html: string;
+  stem_html: string;
+  answers: Answer[];
+  hints: string[];
+  formats: string[];
+  combo_choices: any[];
+  collaborator_solutions?: Solution[];
+  community_solutions?: Solution[];
+};
+
+export type Exercise = {
+  images: any[];
+  tags: string[];
+  uuid: string;
+  group_uuid: string;
+  number: number;
+  version: number;
+  uid: string;
+  published_at: string;
+  solutions_are_public: boolean;
+  authors: any[];
+  copyright_holders: any[];
+  derived_from: any[];
+  is_vocab: boolean;
+  questions: Question[];
+  delegations: any[];
+  versions: number[];
+  stimulus_html: string;
+};
+
+// Note that total_count can be more than the number of Exercises in items due to pagination
+// The maximum number of items returned by the API is limited to 100 to prevent timeouts
+export type ExercisesSearchResults = {
+  total_count: number;
+  items: Exercise[];
+};
+
+export type ExercisesSearchResultsWithDigest = ExercisesSearchResults & { digest: string };
+
+export const exercisesGateway = <C extends string = 'exercises'>(initializer: Initializer<C>) => (configProvider: {[_key in C]: ConfigProviderForConfig<Config>}) => {
+  const config = configProvider[ifDefined(initializer.configSpace, 'exercises' as C)];
+  const exercisesHost = once(() => resolveConfigValue(config.exercisesHost));
+  const exercisesAuthToken = once(() => resolveConfigValue(config.exercisesAuthToken));
+  const defaultCorrectness = once(() => resolveConfigValue(config.defaultCorrectness || ''));
+
+  const doDefaultCorrectness = async(exercise: Exercise) => {
+    if (await defaultCorrectness() !== 'true') {
+      return exercise;
+    }
+
+    for (const question of exercise.questions) {
+      const existingCorrect = question.answers.find(answer => answer.correctness !== undefined);
+
+      if (question.answers.length < 1 || existingCorrect) {
+        continue;
+      }
+
+      const defaultCorrectIndex = question.id % question.answers.length;
+      const defaultCorrect = question.answers[defaultCorrectIndex];
+      const defaultHint = `<em>random default: the correct answer is ${defaultCorrect.id}: ${defaultCorrect.content_html.slice(0, 20)}</em>`;
+      question.stem_html += `\n<br>${defaultHint}`;
+
+      question.collaborator_solutions = [
+        {solution_type: 'detailed', images: [], content_html: defaultHint}
+      ];
+
+      for (let index = 0; index < question.answers.length; index++) {
+        const answer = question.answers[index];
+        answer.correctness = defaultCorrectIndex === index ? '1.0' : '0.0';
+        answer.feedback_html = defaultCorrectIndex === index ? 'This is the good one!' : defaultHint;
+      }
+    }
+
+    return exercise;
+  };
+
+  return (_: {}) => {
+    const request = async(method: METHOD, path: string, query: object | undefined = undefined) => {
+      const host = (await exercisesHost()).replace(/\/+$/, '');
+      const baseUrl = `${host}/api/${path}`;
+      const url = query ? `${baseUrl}?${queryString.stringify(query)}` : baseUrl;
+      return initializer.fetch(url, {
+        headers: {
+          Authorization: `Bearer ${await exercisesAuthToken()}`,
+        },
+        method,
+      });
+    };
+
+    const searchDigest = async(query: string, page = 1, per_page = 100) => {
+      const response = await request(METHOD.HEAD, 'exercises', { query, page, per_page });
+      return assertString(
+        response.headers.get('X-Digest'),
+        'OpenStax Exercises search endpoint HEAD did not return an X-Digest header'
+      );
+    };
+
+    const search = async(
+      query: string, page = 1, per_page = 100
+    ): Promise<ExercisesSearchResultsWithDigest> => {
+      const response = await request(METHOD.GET, 'exercises', { query, page, per_page });
+      const digest = assertString(
+        response.headers.get('X-Digest'),
+        'OpenStax Exercises search endpoint GET did not return an X-Digest header'
+      );
+      const { items, total_count } = await response.json() as ExercisesSearchResults;
+
+      return { digest, items: await Promise.all(items.map(doDefaultCorrectness)), total_count };
+    };
+
+    const get = async(uuid: string) => {
+      const response = await request(METHOD.GET, `exercises/${uuid}`);
+      return response.status === 404
+        ? undefined
+        : (response.json() as Promise<Exercise>).then(doDefaultCorrectness)
+      ;
+    };
+
+    return {
+      searchDigest,
+      get,
+      search,
+    };
+  };
+};
+
+export type ExercisesGateway = ReturnType<ReturnType<ReturnType<typeof exercisesGateway>>>;

package/packages/utils/src/services/fileServer/index.spec.ts

@@ -0,0 +1,88 @@
+import { isFileOrFolder, isFileValue, isFolderValue } from '.';
+
+const fileValue = {
+  dataType: 'file',
+  mimeType: 'text/html',
+  path: '/build/index.html',
+  label: 'index.html',
+};
+
+const folderValue = {
+  dataType: 'folder',
+  files: [ fileValue ],
+};
+
+describe('isFileValue', () => {
+  it('returns true for file values', () => {
+    expect(isFileValue(fileValue)).toBe(true);
+  });
+
+  it('returns false for non-objects', () => {
+    expect(isFileValue('index.html')).toBe(false);
+  });
+
+  it('returns false for objects with the wrong dataType', () => {
+    expect(isFileValue({
+      ...fileValue,
+      dataType: 'folder',
+    })).toBe(false);
+  });
+
+  it('returns false for objects with the missing keys', () => {
+    expect(isFileValue({
+      dataType: 'file',
+      path: '/build/index.html',
+    })).toBe(false);
+  });
+
+  it('returns false for objects with extra keys', () => {
+    expect(isFileValue({
+      ...fileValue,
+      extra: true,
+    })).toBe(false);
+  });
+});
+
+describe('isFolderValue', () => {
+  it('returns true for folder values', () => {
+    expect(isFolderValue(folderValue)).toBe(true);
+  });
+
+  it('returns false for non-objects', () => {
+    expect(isFolderValue('folder')).toBe(false);
+  });
+
+  it('returns false for objects with the wrong dataType', () => {
+    expect(isFolderValue({
+      ...folderValue,
+      dataType: 'file',
+    })).toBe(false);
+  });
+
+  it('returns false for objects with the missing keys', () => {
+    expect(isFolderValue({
+      dataType: 'folder',
+    })).toBe(false);
+  });
+
+  it('returns false for objects with extra keys', () => {
+    expect(isFolderValue({
+      ...folderValue,
+      extra: true,
+    })).toBe(false);
+  });
+});
+
+describe('isFileOrFolder', () => {
+  it('returns true for files', () => {
+    expect(isFileOrFolder(fileValue)).toBe(true);
+  });
+
+  it('returns true for folders', () => {
+    expect(isFileOrFolder(folderValue)).toBe(true);
+  });
+
+  it('returns false for neither', () => {
+    expect(isFileOrFolder('file')).toBe(false);
+  });
+});

package/packages/utils/src/services/fileServer/index.ts

@@ -0,0 +1,43 @@
+import { isPlainObject } from '../../guards';
+
+export type FileValue = {
+  dataType: 'file';
+  mimeType: string;
+  path: string;
+  label: string;
+};
+
+export type FolderValue = {
+  dataType: 'folder';
+  files: FileValue[];
+};
+
+export const isFileValue = (thing: any): thing is FileValue => isPlainObject(thing)
+  && Object.keys(thing).every(key => ['dataType', 'path', 'label', 'mimeType'].includes(key))
+  && thing.dataType === 'file'
+  && typeof thing.mimeType === 'string'
+  && typeof thing.path === 'string'
+  && typeof thing.label === 'string'
+;
+
+export const isFolderValue = (thing: any): thing is FolderValue => isPlainObject(thing)
+  && Object.keys(thing).every(key => ['dataType', 'files'].includes(key))
+  && thing.dataType === 'folder'
+  && thing.files instanceof Array
+  && thing.files.every(isFileValue)
+;
+
+export interface FileServerAdapter {
+  putFileContent: (source: FileValue, content: string) => Promise<FileValue>;
+  getSignedViewerUrl: (source: FileValue) => Promise<string>;
+  getPublicViewerUrl: (source: FileValue) => Promise<string>;
+  getFileContent: (source: FileValue) => Promise<Buffer>;
+  getSignedFileUploadConfig: () => Promise<{url: string; payload: {[key: string]: string}}>;
+  copyFileTo: (source: FileValue, destinationPath: string) => Promise<FileValue>;
+  copyFileToDirectory: (source: FileValue, destinationDirectory: string) => Promise<FileValue>;
+  isTemporaryUpload: (source: FileValue) => boolean;
+  getFileChecksum: (source: FileValue) => Promise<string>;
+  filesEqual: (sourceA: FileValue, sourceB: FileValue) => Promise<boolean>;
+}
+
+export const isFileOrFolder = (thing: any): thing is FileValue | FolderValue => isFileValue(thing) || isFolderValue(thing);