@openstax/ts-utils 1.40.2 → 1.41.2

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

@@ -1,4 +1,3 @@
-import * as queryString from 'query-string';
 import { once } from '../..';
 import { assertDefined } from '../../assertions';
 import { resolveConfigValue } from '../../config';
@@ -8,6 +7,7 @@ import { ifDefined } from '../../guards';
 import { retryWithDelay } from '../../misc/helpers';
 import { METHOD } from '../../routing';
 import { addStatementDefaultFields } from './addStatementDefaultFields';
+import { RequestBatcher } from './batching';
 export const lrsGateway = (initializer) => (configProvider) => {
     const config = configProvider[ifDefined(initializer.configSpace, 'lrs')];
     const lrsHost = once(() => resolveConfigValue(config.lrsHost));
@@ -19,20 +19,51 @@ export const lrsGateway = (initializer) => (configProvider) => {
             wait: 1000,
             status: [502]
         });
+        // Initialize request batcher if batching is enabled
+        const enableBatching = initializer.enableBatching !== false;
+        const batcher = new RequestBatcher(fetcher, {
+            batchEndpoint: '/api/batch',
+            getAuthHeader: lrsAuthorization,
+            getHost: lrsHost,
+        });
+        /**
+         * Makes a fetch request, optionally through the request batcher.
+         * Automatically batches concurrent requests when batching is enabled.
+         */
+        const makeFetch = async (options) => {
+            return enableBatching ? batcher.queueRequest(options) : batcher.singleRequest(options);
+        };
+        /**
+         * Formats an agent parameter into a full XapiAgent object.
+         * Accepts either a UUID string or a full XapiAgent object.
+         */
+        const formatAgent = (agent) => {
+            if (typeof agent === 'string') {
+                return {
+                    objectType: 'Agent',
+                    account: {
+                        homePage: 'https://openstax.org',
+                        name: agent,
+                    },
+                };
+            }
+            return agent;
+        };
         // Note: This method actually uses POST
         const putXapiStatements = async (statements, user) => {
             const userObj = user
                 ? { uuid: user }
                 : assertDefined(await authProvider.getUser(), new UnauthorizedError);
             const statementsWithDefaults = statements.map(statement => addStatementDefaultFields(statement, userObj));
-            const response = await fetcher((await lrsHost()).replace(/\/+$/, '') + '/data/xAPI/statements', {
-                body: JSON.stringify(statementsWithDefaults),
+            const response = await makeFetch({
+                path: '/data/xAPI/statements',
+                method: METHOD.POST,
                 headers: {
                     Authorization: await lrsAuthorization(),
                     'Content-Type': 'application/json',
                     'X-Experience-API-Version': '1.0.0',
                 },
-                method: METHOD.POST,
+                body: JSON.stringify(statementsWithDefaults),
             });
             if (![200, 201].includes(response.status)) {
                 throw new Error(`Unexpected LRS POST statements response code ${response.status} with body:
@@ -52,29 +83,51 @@ ${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({
+        const getMoreXapiStatements = async (more) => {
+            // 'more' is a full path with query string, so we don't use makeFetch batching here
+            const host = await lrsHost();
+            return fetcher(host.replace(/\/+$/, '') + more, {
+                headers: {
+                    Authorization: await lrsAuthorization(),
+                    'X-Experience-API-Version': '1.0.0',
+                },
+            }).then(formatGetXapiStatementsResponse);
+        };
+        const fetchXapiStatements = async ({ user, anyUser, ...options }) => {
+            const queryParams = {};
+            // Add filter params
+            if (options.verb)
+                queryParams.verb = options.verb;
+            if (options.activity)
+                queryParams.activity = options.activity;
+            if (options.registration)
+                queryParams.registration = options.registration;
+            if (options.related_activities !== undefined)
+                queryParams.related_activities = String(options.related_activities);
+            if (options.since)
+                queryParams.since = options.since;
+            if (options.until)
+                queryParams.until = options.until;
+            // Add agent unless anyUser is true
+            if (anyUser !== true) {
+                queryParams.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',
-            },
-        });
+                });
+            }
+            return makeFetch({
+                path: '/data/xAPI/statements',
+                method: METHOD.GET,
+                queryParams,
+                headers: {
+                    Authorization: await lrsAuthorization(),
+                    'X-Experience-API-Version': '1.0.0',
+                },
+            });
+        };
         const getXapiStatements = async (params) => {
             const { ensureSync, ...fetchParams } = params;
             if (ensureSync) {
@@ -103,11 +156,87 @@ ${await response.text()}`);
             };
             return loadRemaining(await getXapiStatements(params));
         };
+        /**
+         * Get a single state document from the xAPI State API.
+         *
+         * @param activityId - The activity ID
+         * @param agent - The agent (UUID string or full XapiAgent object)
+         * @param stateId - The state document identifier
+         * @param registration - Optional registration UUID
+         * @returns The state document as a JSON object, or null if not found
+         */
+        const getState = async (activityId, agent, stateId, registration) => {
+            const agentObj = formatAgent(agent);
+            const queryParams = {
+                activityId,
+                agent: JSON.stringify(agentObj),
+                stateId,
+            };
+            if (registration) {
+                queryParams.registration = registration;
+            }
+            const response = await makeFetch({
+                path: '/data/xAPI/activities/state',
+                method: METHOD.GET,
+                queryParams,
+                headers: {
+                    Authorization: await lrsAuthorization(),
+                    'X-Experience-API-Version': '1.0.0',
+                },
+            });
+            if (response.status === 404) {
+                return null;
+            }
+            if (response.status !== 200) {
+                throw new Error(`Unexpected LRS GET state response code ${response.status} with body:
+
+${await response.text()}`);
+            }
+            return response.json();
+        };
+        /**
+         * Create or update a state document in the xAPI State API.
+         *
+         * @param activityId - The activity ID
+         * @param agent - The agent (UUID string or full XapiAgent object)
+         * @param stateId - The state document identifier
+         * @param body - The state document content (JSON object)
+         * @param registration - Optional registration UUID
+         */
+        const setState = async (activityId, agent, stateId, body, registration) => {
+            const agentObj = formatAgent(agent);
+            const queryParams = {
+                activityId,
+                agent: JSON.stringify(agentObj),
+                stateId,
+            };
+            if (registration) {
+                queryParams.registration = registration;
+            }
+            const response = await makeFetch({
+                path: '/data/xAPI/activities/state',
+                method: METHOD.PUT,
+                queryParams,
+                headers: {
+                    Authorization: await lrsAuthorization(),
+                    'Content-Type': 'application/json',
+                    'X-Experience-API-Version': '1.0.0',
+                },
+                body: JSON.stringify(body),
+            });
+            if (response.status !== 204) {
+                throw new Error(`Unexpected LRS PUT state response code ${response.status} with body:
+
+${await response.text()}`);
+            }
+        };
         return {
             putXapiStatements,
             getXapiStatements,
             getMoreXapiStatements,
             getAllXapiStatements,
+            getState,
+            setState,
         };
     };
 };