@openstax/ts-utils 1.33.1 → 1.34.0

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

@@ -0,0 +1,194 @@
+// spell-checker:words Fopenstax
+import { UnauthorizedError } from '../../errors';
+import { stubAuthProvider, User } from '../authProvider';
+import { createCoreLogger } from '../logger';
+import { lrsGateway } from '.';
+
+afterEach(() => {
+  jest.clearAllMocks();
+});
+
+beforeEach(() => {
+  jest.useFakeTimers();
+  jest.setSystemTime(new Date(2020, 1, 1));
+});
+
+describe('lrsGateway', () => {
+  let fetchSpy: jest.SpyInstance;
+  const config = {
+    lrs: {
+      lrsHost: 'lrsHostString',
+      lrsAuthorization: 'lrsAuthorizationString',
+    }
+  };
+  let lrs: ReturnType<ReturnType<typeof lrsGateway>>;
+
+  beforeEach(() => {
+    fetchSpy = jest.fn();
+    lrs = lrsGateway({fetch: fetchSpy as any})(config);
+  });
+
+  describe('putXapiStatements', () => {
+    it('throws without a user', async() => {
+      const logger = createCoreLogger(jest.fn());
+      const authProvider = stubAuthProvider(undefined);
+      await expect(lrs({logger, authProvider}).putXapiStatements([])).rejects.toThrow(UnauthorizedError);
+      expect(fetchSpy).not.toHaveBeenCalled();
+    });
+
+    it('submits statements', async() => {
+      const logger = createCoreLogger(jest.fn());
+      const authProvider = stubAuthProvider({uuid: 'cool uuid'} as unknown as User);
+      fetchSpy.mockReturnValue(Promise.resolve({status: 200, json: () => ['id1', 'id2']}));
+      await lrs({logger, authProvider})
+        .putXapiStatements([{id: 'statement id', object: {objectType: 'Activity' as const, id: 'cool object'}, verb: {id: 'cool verb'}}]);
+      expect(fetchSpy.mock.calls[0]).toMatchInlineSnapshot(`
+[
+  "lrsHostString/data/xAPI/statements",
+  {
+    "body": "[{"id":"statement id","actor":{"account":{"homePage":"https://openstax.org","name":"cool uuid"},"objectType":"Agent"},"timestamp":"2020-02-01T00:00:00Z","object":{"objectType":"Activity","id":"cool object"},"verb":{"id":"cool verb"}}]",
+    "headers": {
+      "Authorization": "lrsAuthorizationString",
+      "Content-Type": "application/json",
+      "X-Experience-API-Version": "1.0.0",
+    },
+    "method": "POST",
+  },
+]
+`);
+    });
+
+    it('throws if the response status code is not 200', async() => {
+      const logger = createCoreLogger(jest.fn());
+      const authProvider = stubAuthProvider({uuid: 'cool uuid'} as unknown as User);
+      fetchSpy.mockReturnValue(Promise.resolve({status: 401, text: () => 'Unauthorized'}));
+      await expect(
+        lrs({logger, authProvider}).putXapiStatements([{object: {objectType: 'Activity' as const, id: 'cool object'}, verb: {id: 'cool verb'}}])
+      ).rejects.toThrow(`Unexpected LRS POST statements response code 401 with body:
+
+Unauthorized`);
+    });
+  });
+
+  describe('getAllXapiStatements', () => {
+    it('throws without a user', async() => {
+      const logger = createCoreLogger(jest.fn());
+      const authProvider = stubAuthProvider(undefined);
+      await expect(lrs({logger, authProvider}).getAllXapiStatements({})).rejects.toThrow(UnauthorizedError);
+      expect(fetchSpy).not.toHaveBeenCalled();
+    });
+
+    it('throws without a user unless anyUser is set', async() => {
+      const logger = createCoreLogger(jest.fn());
+      const authProvider = stubAuthProvider(undefined);
+      fetchSpy.mockReturnValue(Promise.resolve({status: 200, json: () => []}));
+      await expect(lrs({logger, authProvider}).getAllXapiStatements({anyUser: true})).resolves.not.toThrow(UnauthorizedError);
+      expect(fetchSpy).toHaveBeenCalled();
+    });
+
+    it('submits statement query', async() => {
+      const logger = createCoreLogger(jest.fn());
+      const authProvider = stubAuthProvider({uuid: 'cool uuid'} as unknown as User);
+      fetchSpy.mockReturnValue(Promise.resolve({status: 200, json: () => ({more: '', statements: []})}));
+      await lrs({logger, authProvider}).getAllXapiStatements({});
+      expect(fetchSpy.mock.calls[0]).toMatchInlineSnapshot(`
+[
+  "lrsHostString/data/xAPI/statements?agent=%7B%22account%22%3A%7B%22homePage%22%3A%22https%3A%2F%2Fopenstax.org%22%2C%22name%22%3A%22cool%20uuid%22%7D%2C%22objectType%22%3A%22Agent%22%7D",
+  {
+    "headers": {
+      "Authorization": "lrsAuthorizationString",
+      "X-Experience-API-Version": "1.0.0",
+    },
+  },
+]
+`);
+    });
+
+    it('throws if the response status code is not 200', async() => {
+      const logger = createCoreLogger(jest.fn());
+      const authProvider = stubAuthProvider({uuid: 'cool uuid'} as unknown as User);
+      fetchSpy.mockReturnValue(Promise.resolve({status: 401, text: () => 'Unauthorized'}));
+      await expect(
+        lrs({logger, authProvider}).getAllXapiStatements({})
+      ).rejects.toThrow(`Unexpected LRS GET statements response code 401 with body:
+
+Unauthorized`);
+    });
+
+    it('paginates', async() => {
+      const logger = createCoreLogger(jest.fn());
+      const authProvider = stubAuthProvider({uuid: 'cool uuid'} as unknown as User);
+      fetchSpy
+        .mockReturnValueOnce(Promise.resolve({status: 200, json: () => ({more: '/more token 1', statements: ['one', 'two']})}))
+        .mockReturnValueOnce(Promise.resolve({status: 200, json: () => ({more: '/more token 2', statements: ['three', 'four']})}))
+        .mockReturnValueOnce(Promise.resolve({status: 200, json: () => ({more: '', statements: ['five', 'six']})}))
+      ;
+      const result = await lrs({logger, authProvider}).getAllXapiStatements({});
+      expect(fetchSpy.mock.calls).toHaveLength(3);
+      expect(fetchSpy.mock.calls[0][0]).toBe(
+        'lrsHostString/data/xAPI/statements?agent=%7B%22account%22%3A%7B%22homePage%22%3A%22https%3A%2F%2Fopenstax.org%22%2C%22name%22%3A%22cool%20uuid%22%7D%2C%22objectType%22%3A%22Agent%22%7D'
+      );
+      expect(fetchSpy.mock.calls[1][0]).toBe(
+        'lrsHostString/more token 1'
+      );
+      expect(fetchSpy.mock.calls[2][0]).toBe(
+        'lrsHostString/more token 2'
+      );
+      expect(result).toEqual(['one', 'two', 'three', 'four', 'five', 'six']);
+    });
+
+    it('can retry requests until in sync', async() => {
+      const logger = createCoreLogger(jest.fn());
+      const authProvider = stubAuthProvider({uuid: 'cool uuid'} as unknown as User);
+      jest.useRealTimers();
+      const outDated = (new Date(new Date().getTime() - 1000)).toISOString();
+      fetchSpy
+        .mockReturnValueOnce(Promise.resolve({status: 200, headers: { get: () => outDated }, json: () => ({more: '', statements: []})}))
+        .mockReturnValueOnce(Promise.resolve({status: 200, headers: { get: () => (new Date()).toISOString() }, json: () => ({more: '', statements: []})}));
+      await lrs({logger, authProvider}).getAllXapiStatements({ensureSync: true});
+      expect(fetchSpy.mock.calls).toHaveLength(2);
+    });
+
+    it('throws if max retries are exceeded', async() => {
+      const logger = createCoreLogger(jest.fn());
+      const authProvider = stubAuthProvider({uuid: 'cool uuid'} as unknown as User);
+      jest.useRealTimers();
+      const outDated = (new Date(new Date().getTime() - 1000)).toISOString();
+      fetchSpy.mockReturnValue(Promise.resolve({status: 200, headers: { get: () => outDated }, json: () => ({more: '', statements: []})}));
+      await expect(lrs({logger, authProvider}).getAllXapiStatements({ ensureSync: true })).rejects.toThrow('xAPI consistent through');
+      expect(fetchSpy.mock.calls).toHaveLength(5);
+    });
+
+    it('returns early when the fetchUntil predicate is true', async() => {
+      const logger = createCoreLogger(jest.fn());
+      const authProvider = stubAuthProvider({uuid: 'cool uuid'} as unknown as User);
+      fetchSpy
+        .mockReturnValueOnce(Promise.resolve({status: 200, json: () => ({more: '/more token 1', statements: ['one', 'two']})}))
+        .mockReturnValueOnce(Promise.resolve({status: 200, json: () => ({more: '/more token 2', statements: ['three', 'four']})}))
+        .mockReturnValueOnce(Promise.resolve({status: 200, json: () => ({more: '/more token 3', statements: ['five', 'six']})}))
+        .mockReturnValueOnce(Promise.resolve({status: 200, json: () => ({more: '', statements: ['seven', 'eight']})}))
+      ;
+      const result = await lrs({logger, authProvider}).getAllXapiStatements({
+        fetchUntil: (statements: any) => statements.includes('three')
+      });
+      expect(fetchSpy.mock.calls).toHaveLength(2);
+      expect(result).toEqual(['one', 'two', 'three', 'four']);
+    });
+
+    it('includes all results if fetchUntil never matches', async() => {
+      const logger = createCoreLogger(jest.fn());
+      const authProvider = stubAuthProvider({uuid: 'cool uuid'} as unknown as User);
+      fetchSpy
+        .mockReturnValueOnce(Promise.resolve({status: 200, json: () => ({more: '/more token 1', statements: ['one', 'two']})}))
+        .mockReturnValueOnce(Promise.resolve({status: 200, json: () => ({more: '/more token 2', statements: ['three', 'four']})}))
+        .mockReturnValueOnce(Promise.resolve({status: 200, json: () => ({more: '', statements: ['five', 'six']})}))
+      ;
+      const result = await lrs({logger, authProvider}).getAllXapiStatements({
+        fetchUntil: (statements: any) => statements.includes('ten')
+      });
+      expect(fetchSpy.mock.calls).toHaveLength(3);
+      expect(result).toEqual(['one', 'two', 'three', 'four', 'five', 'six']);
+    });
+
+  });
+});

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

@@ -0,0 +1,257 @@
+import * as queryString from 'query-string';
+import { once } from '../..';
+import { assertDefined } from '../../assertions';
+import { ConfigProviderForConfig, resolveConfigValue } from '../../config';
+import { UnauthorizedError } from '../../errors';
+import { GenericFetch, Response } from '../../fetch';
+import { fetchStatusRetry } from '../../fetch/fetchStatusRetry';
+import { ifDefined } from '../../guards';
+import { retryWithDelay } from '../../misc/helpers';
+import { METHOD } from '../../routing';
+import { WithRequired } from '../../types';
+import { AuthProvider } from '../authProvider';
+import { Logger } from '../logger';
+import { addStatementDefaultFields } from './addStatementDefaultFields';
+
+// TODO - add "platform" to config here and auto inject into new statements
+type Config = {
+  lrsHost: string;
+  lrsAuthorization: string;
+};
+interface Initializer<C> {
+  configSpace?: C;
+  fetch: GenericFetch;
+}
+
+// TODO - real type for this
+export interface XapiStatement {
+  actor: {
+    account: {
+      homePage: 'https://openstax.org';
+      name: string;
+    };
+    objectType: 'Agent';
+  };
+  id: string;
+  context?: {
+    contextActivities?: {
+      parent?: [
+        {
+          id: string;
+          objectType: 'Activity';
+        }
+      ];
+    };
+    statement?: {
+      objectType: 'StatementRef';
+      id: string;
+    };
+    registration?: string;
+    platform?: string;
+  };
+  object: {
+    definition?: {
+      extensions?: {[key: string]: string};
+      name: {[key: string]: string};
+      type: string;
+    };
+    id: string;
+    objectType: 'Activity';
+  };
+  result?: {
+    score?: {
+      /*
+       * Decimal number between -1 and 1, inclusive
+       * The score related to the experience as modified by scaling and/or normalization.
+       */
+      scaled?: number;
+
+      /*
+       * Decimal number between min and max (if present, otherwise unrestricted), inclusive
+       * The score achieved by the Actor in the experience described by the Statement. This is not modified by any scaling or normalization.
+       */
+      raw?: number;
+
+      /*
+       * Decimal number less than max (if present)
+       * The lowest possible score for the experience described by the Statement.
+       */
+      min?: number;
+
+      /*
+       * Decimal number greater than min (if present)
+       * The highest possible score for the experience described by the Statement.
+       */
+      max?: number;
+    };
+    success?: boolean; /* Indicates whether or not the attempt on the Activity was successful. */
+    completion?: boolean; /* Indicates whether or not the Activity was completed. */
+    response?: string; /* A response appropriately formatted for the given Activity. */
+    duration?: string; /* (ISO 8601 Duration)  Period of time over which the Statement occurred. */
+    extensions?: {[key: string]: string};
+  };
+  verb: {
+    display?: {[key: string]: string};
+    id: string;
+  };
+  timestamp: string;
+  stored?: string;
+}
+
+export type SavedXapiStatement = WithRequired<XapiStatement, 'stored'>;
+export type EagerXapiStatement = Omit<XapiStatement, 'stored'>;
+export type UXapiStatement = XapiStatement | EagerXapiStatement | SavedXapiStatement;
+
+export type LrsGateway = ReturnType<ReturnType<ReturnType<typeof lrsGateway>>>;
+export type LrsProvider = ReturnType<ReturnType<typeof lrsGateway>>;
+
+export const lrsGateway = <C extends string = 'lrs'>(initializer: Initializer<C>) => (configProvider: {[_key in C]: ConfigProviderForConfig<Config>}) => {
+  const config = configProvider[ifDefined(initializer.configSpace, 'lrs' as C)];
+  const lrsHost = once(() => resolveConfigValue(config.lrsHost));
+  const lrsAuthorization = once(() => resolveConfigValue(config.lrsAuthorization));
+
+  return ({authProvider, logger}: {authProvider: AuthProvider; logger: Logger}) => {
+    const fetcher = fetchStatusRetry(initializer.fetch, {
+      logger,
+      retries: 2,
+      wait: 1000,
+      status: [502]
+    });
+
+    // Note: This method actually uses POST
+    const putXapiStatements = async(
+      statements: Array<(Pick<XapiStatement, 'object' | 'verb' | 'context' | 'result'> & {
+        id?: string;
+      }) | UXapiStatement>
+    ): Promise<EagerXapiStatement[]> => {
+      const user = assertDefined(await authProvider.getUser(), new UnauthorizedError);
+
+      const statementsWithDefaults: EagerXapiStatement[] = statements.map(statement =>
+        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: 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;
+    };
+
+    type getXapiStatementResponse = {more: string; statements: XapiStatement[]};
+
+    // 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: Response): Promise<getXapiStatementResponse> => {
+      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: string
+    ) => fetcher((await lrsHost()).replace(/\/+$/, '') + more, {
+      headers: {
+        Authorization: await lrsAuthorization(),
+        'X-Experience-API-Version': '1.0.0',
+      },
+    }).then(formatGetXapiStatementsResponse);
+
+    type fetchXapiStatementsParams = {
+      verb?: string;
+      activity?: string;
+      registration?: string;
+      related_activities?: boolean;
+      user?: string;
+      anyUser?: boolean;
+      since?: string;
+      until?: string;
+    };
+
+    type getXapiStatementsParams = fetchXapiStatementsParams & { ensureSync?: boolean };
+
+    const fetchXapiStatements = async({user, anyUser, ...options}: fetchXapiStatementsParams) =>
+      fetcher((await lrsHost()).replace(/\/+$/, '') + '/data/xAPI/statements?' + queryString.stringify({
+        ...options,
+        ...(anyUser === true ? {} : {
+          agent: JSON.stringify({
+            account: {
+              homePage: 'https://openstax.org',
+              name: user || assertDefined(await authProvider.getUser(), new UnauthorizedError()).uuid,
+            },
+            objectType: 'Agent',
+          }),
+        })
+      }), {
+        headers: {
+          Authorization: await lrsAuthorization(),
+          'X-Experience-API-Version': '1.0.0',
+        },
+      });
+
+    const getXapiStatements = async(params: getXapiStatementsParams) => {
+      const { ensureSync, ...fetchParams } = params;
+
+      if (ensureSync) {
+        const date = new Date();
+
+        return 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}: getXapiStatementsParams & {
+      fetchUntil?: (statements: XapiStatement[]) => boolean;
+    }) => {
+      const loadRemaining = async(result: {more: string; statements: XapiStatement[]}): Promise<XapiStatement[]> => {
+        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,
+    };
+  };
+};