@iblai/data-layer 1.20.0 → 1.21.0

package/dist/index.js

@@ -43735,6 +43735,187 @@ const perLearnerApiSlice = react.createApi({
 });
 const { useGetPerLearnerActivityQuery, useLazyGetPerLearnerActivityQuery, useGetPerLearnerInfoQuery, useLazyGetPerLearnerInfoQuery, useGetOverTimeActivityQuery, useLazyGetOverTimeActivityQuery, } = perLearnerApiSlice;
 
+const LEARNER_COMPLETION_PATH = '/api/catalog/enrollment/courses/completion/';
+const LEARNER_IDENTIFIER_KEYS = ['username', 'user_id', 'email'];
+const isPresent = (value) => value !== undefined && value !== null && String(value).trim() !== '';
+/**
+ * Checks the args carry exactly one learner identifier plus `course_id` and
+ * `platform_key`. Returns a reason string when they don't.
+ */
+function validateLearnerCompletionArgs(args) {
+    const identifiers = LEARNER_IDENTIFIER_KEYS.filter((key) => isPresent(args[key]));
+    if (identifiers.length !== 1) {
+        return 'Exactly one of username, user_id or email is required.';
+    }
+    if (!isPresent(args.course_id))
+        return 'course_id is required.';
+    if (!isPresent(args.platform_key))
+        return 'platform_key is required.';
+    return null;
+}
+/**
+ * Builds the completion URL for one `endpoint` selector. Only the learner
+ * identifier, `course_id` and `platform_key` are sent; the DM forwards
+ * nothing else to edX.
+ */
+function buildLearnerCompletionUrl(args, endpoint) {
+    const params = new URLSearchParams();
+    const record = args;
+    for (const key of [...LEARNER_IDENTIFIER_KEYS, 'platform_key', 'course_id']) {
+        if (isPresent(record[key]))
+            params.set(key, String(record[key]));
+    }
+    params.set('endpoint', endpoint);
+    return `${LEARNER_COMPLETION_PATH}?${params.toString()}`;
+}
+// 404 means "course not on tenant / learner not enrolled"; retrying won't
+// change that, and the outline call is heavy. 5xx keeps the default retries.
+const LEARNER_COMPLETION_MAX_RETRIES = 3;
+const learnerCompletionExtraOptions = {
+    retryCondition: (error, _args, { attempt }) => attempt <= LEARNER_COMPLETION_MAX_RETRIES && (error === null || error === void 0 ? void 0 : error.status) !== 404,
+};
+/**
+ * One completion request through `iblFetchBaseQuery` (DM token, token
+ * refresh, registered error handlers). `iblFetchBaseQuery` throws on HTTP
+ * errors, which RTK would turn into a SerializedError without the status;
+ * catching here keeps `{ status, data }` so the UI can tell 403/404/502 apart.
+ */
+async function fetchLearnerCompletion(args, endpoint, api, extraOptions = {}) {
+    const invalid = validateLearnerCompletionArgs(args);
+    if (invalid) {
+        return {
+            error: {
+                status: 'CUSTOM_ERROR',
+                error: invalid,
+                data: { kind: 'invalid_request', error: invalid },
+            },
+        };
+    }
+    try {
+        const result = await iblFetchBaseQuery({
+            url: buildLearnerCompletionUrl(args, endpoint),
+            service: exports.SERVICES.DM,
+            method: 'GET',
+        }, api, { ...learnerCompletionExtraOptions, ...extraOptions });
+        if ('error' in result && result.error) {
+            return { error: result.error };
+        }
+        return { data: result.data };
+    }
+    catch (error) {
+        return { error: error };
+    }
+}
+const completionError = (kind, status) => ({ kind, status, retryable: kind === 'unavailable' });
+/**
+ * Maps a failed completion query onto the states the UI shows. 403 and 404
+ * are deliberately coarse on the backend (one body for every hidden case),
+ * so don't try to read more into them.
+ */
+function normalizeLearnerCompletionError(error) {
+    if (error === undefined || error === null)
+        return null;
+    if (typeof error !== 'object')
+        return completionError('unknown');
+    const { status, data } = error;
+    if (status === 'CUSTOM_ERROR') {
+        const kind = data === null || data === void 0 ? void 0 : data.kind;
+        return completionError(kind === 'invalid_request' ? 'invalid_request' : 'unknown', status);
+    }
+    if (status === 'FETCH_ERROR' || status === 'TIMEOUT_ERROR') {
+        return completionError('unavailable', status);
+    }
+    if (typeof status === 'number') {
+        if (status === 400)
+            return completionError('invalid_request', status);
+        if (status === 401)
+            return completionError('unauthorized', status);
+        if (status === 403)
+            return completionError('forbidden', status);
+        if (status === 404)
+            return completionError('not_enrolled', status);
+        if (status === 502 || status === 503 || status === 504) {
+            return completionError('unavailable', status);
+        }
+        return completionError('unknown', status);
+    }
+    return completionError('unknown');
+}
+/* ------------------------------------------------------------------------ */
+/* Outline helpers                                                           */
+/* ------------------------------------------------------------------------ */
+/** Fills the fields edX omits: `children ?? []`, `complete`/`resume_block ?? false`. */
+function normalizeOutline(block) {
+    var _a, _b, _c;
+    return {
+        ...block,
+        children: ((_a = block.children) !== null && _a !== void 0 ? _a : []).map(normalizeOutline),
+        complete: (_b = block.complete) !== null && _b !== void 0 ? _b : false,
+        resume_block: (_c = block.resume_block) !== null && _c !== void 0 ? _c : false,
+    };
+}
+/** Depth-first, course order. The root has depth 0 and `parentId` null. */
+function flattenOutline(root) {
+    const entries = [];
+    const visit = (block, depth, parentId, parentPath) => {
+        var _a;
+        const path = [...parentPath, block.display_name];
+        entries.push({ block, depth, parentId, path });
+        for (const child of (_a = block.children) !== null && _a !== void 0 ? _a : [])
+            visit(child, depth + 1, block.id, path);
+    };
+    visit(root, 0, null, []);
+    return entries;
+}
+/**
+ * Follows `resume_block: true` from the root to the deepest marked node (the
+ * last-visited leaf). Returns null when the learner hasn't visited anything.
+ */
+function findResumeBlock(root) {
+    var _a, _b;
+    // The root may or may not carry the flag itself; either way descend from it.
+    let current = root.resume_block ? root : null;
+    let candidates = (_a = root.children) !== null && _a !== void 0 ? _a : [];
+    for (;;) {
+        const next = candidates.find((block) => block.resume_block);
+        if (!next)
+            return current;
+        current = next;
+        candidates = (_b = next.children) !== null && _b !== void 0 ? _b : [];
+    }
+}
+/** Counts leaves (blocks without children) by `type`. */
+function countByType(root) {
+    var _a;
+    const counts = {};
+    for (const { block, depth } of flattenOutline(root)) {
+        if (depth === 0 || block.children !== undefined)
+            continue;
+        // Childless containers (an empty vertical) aren't content.
+        if (block.type === 'chapter' || block.type === 'sequential' || block.type === 'vertical') {
+            continue;
+        }
+        counts[block.type] = ((_a = counts[block.type]) !== null && _a !== void 0 ? _a : 0) + 1;
+    }
+    return counts;
+}
+/** Top-level sections (chapters) for a summary view, in course order. */
+function getSections(root) {
+    var _a;
+    return ((_a = root.children) !== null && _a !== void 0 ? _a : [])
+        .filter((block) => block.type === 'chapter')
+        .map((block) => {
+        var _a;
+        return ({
+            id: block.id,
+            display_name: block.display_name,
+            completion_percentage: block.completion_percentage,
+            complete: (_a = block.complete) !== null && _a !== void 0 ? _a : false,
+            block,
+        });
+    });
+}
+
 const coursesApiSlice = react.createApi({
     reducerPath: 'coursesApiSlice',
     baseQuery: iblFetchBaseQuery,
@@ -43776,9 +43957,20 @@ const coursesApiSlice = react.createApi({
             },
             providesTags: ['user-assigned-courses'],
         }),
+        /**
+         * Per-learner course outline with block-level completion. Name the learner
+         * with exactly one of `username` / `user_id` / `email`, even for one's own
+         * data. Errors keep their HTTP status; map them with
+         * `normalizeLearnerCompletionError`.
+         */
+        getLearnerCourseOutline: builder.query({
+            queryFn: (args, api, extraOptions) => fetchLearnerCompletion(args, 'outline', api, extraOptions),
+            // The outline is heavy on large courses; keep it around briefly.
+            keepUnusedDataFor: 120,
+        }),
     }),
 });
-const { useGetUserEnrolledCoursesQuery, useLazyGetUserEnrolledCoursesQuery, useGetUserAssignedCoursesQuery, useLazyGetUserAssignedCoursesQuery, } = coursesApiSlice;
+const { useGetUserEnrolledCoursesQuery, useLazyGetUserEnrolledCoursesQuery, useGetUserAssignedCoursesQuery, useLazyGetUserAssignedCoursesQuery, useGetLearnerCourseOutlineQuery, useLazyGetLearnerCourseOutlineQuery, } = coursesApiSlice;
 
 const courseMetadataApiSlice = react.createApi({
     reducerPath: 'courseMetadataApiSlice',
@@ -49211,6 +49403,7 @@ exports.HOSTING_ENDPOINTS = HOSTING_ENDPOINTS;
 exports.HOSTING_QUERY_KEYS = HOSTING_QUERY_KEYS;
 exports.HOSTING_REDUCER_PATH = HOSTING_REDUCER_PATH;
 exports.IblDataLayer = IblDataLayer;
+exports.LEARNER_COMPLETION_PATH = LEARNER_COMPLETION_PATH;
 exports.LOGO_ENDPOINTS = LOGO_ENDPOINTS;
 exports.MCP_ENDPOINTS = MCP_ENDPOINTS;
 exports.MCP_REDUCER_PATH = MCP_REDUCER_PATH;
@@ -49293,6 +49486,7 @@ exports.authApiSlice = authApiSlice;
 exports.billingApiSlice = billingApiSlice;
 exports.billingCustomSlice = billingCustomSlice;
 exports.buildGlobalSearchUrl = buildGlobalSearchUrl;
+exports.buildLearnerCompletionUrl = buildLearnerCompletionUrl;
 exports.buildRecentMessagesUrl = buildRecentMessagesUrl;
 exports.buildSessionRetrieveUrl = buildSessionRetrieveUrl;
 exports.buildSharedSessionRetrieveUrl = buildSharedSessionRetrieveUrl;
@@ -49309,6 +49503,7 @@ exports.clawApiSlice = clawApiSlice;
 exports.coreApiSlice = coreApiSlice;
 exports.coreCustomApiSlice = coreCustomApiSlice;
 exports.coreFakeCustomPublicImageAssetApiSlice = coreFakeCustomPublicImageAssetApiSlice;
+exports.countByType = countByType;
 exports.courseMetadataApiSlice = courseMetadataApiSlice;
 exports.coursesApiSlice = coursesApiSlice;
 exports.credentialsApiSlice = credentialsApiSlice;
@@ -49323,12 +49518,16 @@ exports.evalTotalPages = evalTotalPages;
 exports.evaluationsApiSlice = evaluationsApiSlice;
 exports.fakeBaseQueryWithLogging = fakeBaseQueryWithLogging;
 exports.featureTags = featureTags;
+exports.fetchLearnerCompletion = fetchLearnerCompletion;
 exports.fetchUserLlmUsage = fetchUserLlmUsage;
 exports.filterCourseUserRoles = filterCourseUserRoles;
 exports.filterGlobalUserRoles = filterGlobalUserRoles;
 exports.filterOrgUserRoles = filterOrgUserRoles;
 exports.filterSlashSkills = filterSlashSkills;
+exports.findResumeBlock = findResumeBlock;
+exports.flattenOutline = flattenOutline;
 exports.getNextRecentMessagesPageParam = getNextRecentMessagesPageParam;
+exports.getSections = getSections;
 exports.getSpendCapExceededError = getSpendCapExceededError;
 exports.getUserRoleScope = getUserRoleScope;
 exports.gradingApiSlice = gradingApiSlice;
@@ -49352,6 +49551,8 @@ exports.mentorReducer = mentorReducer;
 exports.moderationLogsApiReducer = moderationLogsApiReducer;
 exports.moderationLogsApiSlice = moderationLogsApiSlice;
 exports.monetizationApiSlice = monetizationApiSlice;
+exports.normalizeLearnerCompletionError = normalizeLearnerCompletionError;
+exports.normalizeOutline = normalizeOutline;
 exports.normalizeUserLlmUsageError = normalizeUserLlmUsageError;
 exports.notificationsApiSlice = notificationsApiSlice;
 exports.notificationsCustomApiSlice = notificationsCustomApiSlice;
@@ -49646,6 +49847,7 @@ exports.useGetIntegrationCredentialsSchemaQuery = useGetIntegrationCredentialsSc
 exports.useGetIssuersQuery = useGetIssuersQuery;
 exports.useGetItemSubscriptionQuery = useGetItemSubscriptionQuery;
 exports.useGetLLMCredentialsQuery = useGetLLMCredentialsQuery;
+exports.useGetLearnerCourseOutlineQuery = useGetLearnerCourseOutlineQuery;
 exports.useGetLearnerDetailsQuery = useGetLearnerDetailsQuery;
 exports.useGetLlmUsageMetricsQuery = useGetLlmUsageMetricsQuery;
 exports.useGetLlmUsageObservationsQuery = useGetLlmUsageObservationsQuery;
@@ -49911,6 +50113,7 @@ exports.useLazyGetIntegrationCredentialsSchemaQuery = useLazyGetIntegrationCrede
 exports.useLazyGetIssuersQuery = useLazyGetIssuersQuery;
 exports.useLazyGetItemSubscriptionQuery = useLazyGetItemSubscriptionQuery;
 exports.useLazyGetLLMCredentialsQuery = useLazyGetLLMCredentialsQuery;
+exports.useLazyGetLearnerCourseOutlineQuery = useLazyGetLearnerCourseOutlineQuery;
 exports.useLazyGetLlmsQuery = useLazyGetLlmsQuery;
 exports.useLazyGetLtiKeyDetailQuery = useLazyGetLtiKeyDetailQuery;
 exports.useLazyGetMCPServerQuery = useLazyGetMCPServerQuery;
@@ -50234,6 +50437,7 @@ exports.userApiSlice = userApiSlice;
 exports.userChatHistoryApiSlice = userChatHistoryApiSlice;
 exports.userInvitationsApiSlice = userInvitationsApiSlice;
 exports.userLlmUsageApiSlice = userLlmUsageApiSlice;
+exports.validateLearnerCompletionArgs = validateLearnerCompletionArgs;
 exports.validateUserLlmUsageParams = validateUserLlmUsageParams;
 exports.watchedGroupsApiSlice = watchedGroupsApiSlice;
 exports.workflowsApiSlice = workflowsApiSlice;