@iblai/data-layer 1.20.0 → 1.21.0

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iblai/data-layer",
-  "version": "1.19.1",
+  "version": "1.20.0",
   "description": "ibl.ai data layer",
   "main": "dist/index.esm.js",
   "types": "dist/index.d.ts",

package/dist/src/features/courses/__tests__/completion.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/features/courses/__tests__/outline-fixture.d.ts

@@ -0,0 +1,10 @@
+import type { CompletionOutlineBlock } from '../types';
+/**
+ * Reduced from the live `endpoint=outline` response for
+ * course-v1:1718796901+C0+2025-09 ("Exam course for baba"). It keeps the
+ * quirks that matter: missing `children` on leaves and empty verticals,
+ * `complete` only on containers or when true, `resume_block` only along the
+ * path to the one completed leaf ("Raw HTML" in Section 3).
+ */
+export declare const COURSE_ID = "course-v1:1718796901+C0+2025-09";
+export declare const outlineFixture: CompletionOutlineBlock;

package/dist/src/features/courses/api-slice.d.ts

@@ -8,6 +8,13 @@ export declare const coursesApiSlice: import("@reduxjs/toolkit/query").Api<impor
         user_id: string | number;
         query?: Record<string, string | number | boolean | undefined>;
     }, import("@reduxjs/toolkit/query").BaseQueryFn<import("../utils").CustomQueryArgs, unknown, import("../utils").ExtendedFetchBaseQueryError, Record<string, unknown>, import("@reduxjs/toolkit/query").FetchBaseQueryMeta>, "user-enrolled-courses" | "user-assigned-courses", EnrolledCourseResponse, "coursesApiSlice", unknown>;
+    /**
+     * 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: import("@reduxjs/toolkit/query").QueryDefinition<import("./types").LearnerCompletionArgs, import("@reduxjs/toolkit/query").BaseQueryFn<import("../utils").CustomQueryArgs, unknown, import("../utils").ExtendedFetchBaseQueryError, Record<string, unknown>, import("@reduxjs/toolkit/query").FetchBaseQueryMeta>, "user-enrolled-courses" | "user-assigned-courses", import("./types").CompletionOutlineBlock, "coursesApiSlice", unknown>;
 }, "coursesApiSlice", "user-enrolled-courses" | "user-assigned-courses", typeof import("@reduxjs/toolkit/query").coreModuleName | typeof import("@reduxjs/toolkit/dist/query/react").reactHooksModuleName>;
 export declare const useGetUserEnrolledCoursesQuery: <R extends Record<string, any> = import("@reduxjs/toolkit/query").TSHelpersId<(Omit<{
     status: import("@reduxjs/toolkit/query").QueryStatus.uninitialized;
@@ -661,4 +668,267 @@ export declare const useGetUserEnrolledCoursesQuery: <R extends Record<string, a
         user_id: string | number;
         query?: Record<string, string | number | boolean | undefined>;
     };
+}], useGetLearnerCourseOutlineQuery: <R extends Record<string, any> = import("@reduxjs/toolkit/query").TSHelpersId<(Omit<{
+    status: import("@reduxjs/toolkit/query").QueryStatus.uninitialized;
+    originalArgs?: undefined | undefined;
+    data?: undefined | undefined;
+    error?: undefined | undefined;
+    requestId?: undefined | undefined;
+    endpointName?: string | undefined;
+    startedTimeStamp?: undefined | undefined;
+    fulfilledTimeStamp?: undefined | undefined;
+} & {
+    currentData?: import("./types").CompletionOutlineBlock | undefined;
+    isUninitialized: false;
+    isLoading: false;
+    isFetching: false;
+    isSuccess: false;
+    isError: false;
+}, "isUninitialized"> & {
+    isUninitialized: true;
+}) | import("@reduxjs/toolkit/query").TSHelpersOverride<import("@reduxjs/toolkit/query").QuerySubState<import("@reduxjs/toolkit/query").QueryDefinition<import("./types").LearnerCompletionArgs, import("@reduxjs/toolkit/query").BaseQueryFn<import("../utils").CustomQueryArgs, unknown, import("../utils").ExtendedFetchBaseQueryError, Record<string, unknown>, import("@reduxjs/toolkit/query").FetchBaseQueryMeta>, "user-enrolled-courses" | "user-assigned-courses", import("./types").CompletionOutlineBlock, "coursesApiSlice", unknown>> & {
+    currentData?: import("./types").CompletionOutlineBlock | undefined;
+    isUninitialized: false;
+    isLoading: false;
+    isFetching: false;
+    isSuccess: false;
+    isError: false;
+}, {
+    isLoading: true;
+    isFetching: boolean;
+    data: undefined;
+} | ({
+    isSuccess: true;
+    isFetching: true;
+    error: undefined;
+} & Required<Pick<import("@reduxjs/toolkit/query").QuerySubState<import("@reduxjs/toolkit/query").QueryDefinition<import("./types").LearnerCompletionArgs, import("@reduxjs/toolkit/query").BaseQueryFn<import("../utils").CustomQueryArgs, unknown, import("../utils").ExtendedFetchBaseQueryError, Record<string, unknown>, import("@reduxjs/toolkit/query").FetchBaseQueryMeta>, "user-enrolled-courses" | "user-assigned-courses", import("./types").CompletionOutlineBlock, "coursesApiSlice", unknown>> & {
+    currentData?: import("./types").CompletionOutlineBlock | undefined;
+    isUninitialized: false;
+    isLoading: false;
+    isFetching: false;
+    isSuccess: false;
+    isError: false;
+}, "data" | "fulfilledTimeStamp">>) | ({
+    isSuccess: true;
+    isFetching: false;
+    error: undefined;
+} & Required<Pick<import("@reduxjs/toolkit/query").QuerySubState<import("@reduxjs/toolkit/query").QueryDefinition<import("./types").LearnerCompletionArgs, import("@reduxjs/toolkit/query").BaseQueryFn<import("../utils").CustomQueryArgs, unknown, import("../utils").ExtendedFetchBaseQueryError, Record<string, unknown>, import("@reduxjs/toolkit/query").FetchBaseQueryMeta>, "user-enrolled-courses" | "user-assigned-courses", import("./types").CompletionOutlineBlock, "coursesApiSlice", unknown>> & {
+    currentData?: import("./types").CompletionOutlineBlock | undefined;
+    isUninitialized: false;
+    isLoading: false;
+    isFetching: false;
+    isSuccess: false;
+    isError: false;
+}, "data" | "fulfilledTimeStamp" | "currentData">>) | ({
+    isError: true;
+} & Required<Pick<import("@reduxjs/toolkit/query").QuerySubState<import("@reduxjs/toolkit/query").QueryDefinition<import("./types").LearnerCompletionArgs, import("@reduxjs/toolkit/query").BaseQueryFn<import("../utils").CustomQueryArgs, unknown, import("../utils").ExtendedFetchBaseQueryError, Record<string, unknown>, import("@reduxjs/toolkit/query").FetchBaseQueryMeta>, "user-enrolled-courses" | "user-assigned-courses", import("./types").CompletionOutlineBlock, "coursesApiSlice", unknown>> & {
+    currentData?: import("./types").CompletionOutlineBlock | undefined;
+    isUninitialized: false;
+    isLoading: false;
+    isFetching: false;
+    isSuccess: false;
+    isError: false;
+}, "error">>)>> & {
+    status: import("@reduxjs/toolkit/query").QueryStatus;
+}>(arg: import("./types").LearnerCompletionArgs | typeof import("@reduxjs/toolkit/query").skipToken, options?: (import("@reduxjs/toolkit/query").SubscriptionOptions & {
+    skip?: boolean;
+    refetchOnMountOrArgChange?: boolean | number;
+} & {
+    skip?: boolean;
+    selectFromResult?: ((state: import("@reduxjs/toolkit/query").TSHelpersId<(Omit<{
+        status: import("@reduxjs/toolkit/query").QueryStatus.uninitialized;
+        originalArgs?: undefined | undefined;
+        data?: undefined | undefined;
+        error?: undefined | undefined;
+        requestId?: undefined | undefined;
+        endpointName?: string | undefined;
+        startedTimeStamp?: undefined | undefined;
+        fulfilledTimeStamp?: undefined | undefined;
+    } & {
+        currentData?: import("./types").CompletionOutlineBlock | undefined;
+        isUninitialized: false;
+        isLoading: false;
+        isFetching: false;
+        isSuccess: false;
+        isError: false;
+    }, "isUninitialized"> & {
+        isUninitialized: true;
+    }) | import("@reduxjs/toolkit/query").TSHelpersOverride<import("@reduxjs/toolkit/query").QuerySubState<import("@reduxjs/toolkit/query").QueryDefinition<import("./types").LearnerCompletionArgs, import("@reduxjs/toolkit/query").BaseQueryFn<import("../utils").CustomQueryArgs, unknown, import("../utils").ExtendedFetchBaseQueryError, Record<string, unknown>, import("@reduxjs/toolkit/query").FetchBaseQueryMeta>, "user-enrolled-courses" | "user-assigned-courses", import("./types").CompletionOutlineBlock, "coursesApiSlice", unknown>> & {
+        currentData?: import("./types").CompletionOutlineBlock | undefined;
+        isUninitialized: false;
+        isLoading: false;
+        isFetching: false;
+        isSuccess: false;
+        isError: false;
+    }, {
+        isLoading: true;
+        isFetching: boolean;
+        data: undefined;
+    } | ({
+        isSuccess: true;
+        isFetching: true;
+        error: undefined;
+    } & Required<Pick<import("@reduxjs/toolkit/query").QuerySubState<import("@reduxjs/toolkit/query").QueryDefinition<import("./types").LearnerCompletionArgs, import("@reduxjs/toolkit/query").BaseQueryFn<import("../utils").CustomQueryArgs, unknown, import("../utils").ExtendedFetchBaseQueryError, Record<string, unknown>, import("@reduxjs/toolkit/query").FetchBaseQueryMeta>, "user-enrolled-courses" | "user-assigned-courses", import("./types").CompletionOutlineBlock, "coursesApiSlice", unknown>> & {
+        currentData?: import("./types").CompletionOutlineBlock | undefined;
+        isUninitialized: false;
+        isLoading: false;
+        isFetching: false;
+        isSuccess: false;
+        isError: false;
+    }, "data" | "fulfilledTimeStamp">>) | ({
+        isSuccess: true;
+        isFetching: false;
+        error: undefined;
+    } & Required<Pick<import("@reduxjs/toolkit/query").QuerySubState<import("@reduxjs/toolkit/query").QueryDefinition<import("./types").LearnerCompletionArgs, import("@reduxjs/toolkit/query").BaseQueryFn<import("../utils").CustomQueryArgs, unknown, import("../utils").ExtendedFetchBaseQueryError, Record<string, unknown>, import("@reduxjs/toolkit/query").FetchBaseQueryMeta>, "user-enrolled-courses" | "user-assigned-courses", import("./types").CompletionOutlineBlock, "coursesApiSlice", unknown>> & {
+        currentData?: import("./types").CompletionOutlineBlock | undefined;
+        isUninitialized: false;
+        isLoading: false;
+        isFetching: false;
+        isSuccess: false;
+        isError: false;
+    }, "data" | "fulfilledTimeStamp" | "currentData">>) | ({
+        isError: true;
+    } & Required<Pick<import("@reduxjs/toolkit/query").QuerySubState<import("@reduxjs/toolkit/query").QueryDefinition<import("./types").LearnerCompletionArgs, import("@reduxjs/toolkit/query").BaseQueryFn<import("../utils").CustomQueryArgs, unknown, import("../utils").ExtendedFetchBaseQueryError, Record<string, unknown>, import("@reduxjs/toolkit/query").FetchBaseQueryMeta>, "user-enrolled-courses" | "user-assigned-courses", import("./types").CompletionOutlineBlock, "coursesApiSlice", unknown>> & {
+        currentData?: import("./types").CompletionOutlineBlock | undefined;
+        isUninitialized: false;
+        isLoading: false;
+        isFetching: false;
+        isSuccess: false;
+        isError: false;
+    }, "error">>)>> & {
+        status: import("@reduxjs/toolkit/query").QueryStatus;
+    }) => R) | undefined;
+}) | undefined) => [R][R extends any ? 0 : never] & {
+    refetch: () => import("@reduxjs/toolkit/query").QueryActionCreatorResult<import("@reduxjs/toolkit/query").QueryDefinition<import("./types").LearnerCompletionArgs, import("@reduxjs/toolkit/query").BaseQueryFn<import("../utils").CustomQueryArgs, unknown, import("../utils").ExtendedFetchBaseQueryError, Record<string, unknown>, import("@reduxjs/toolkit/query").FetchBaseQueryMeta>, "user-enrolled-courses" | "user-assigned-courses", import("./types").CompletionOutlineBlock, "coursesApiSlice", unknown>>;
+}, useLazyGetLearnerCourseOutlineQuery: <R extends Record<string, any> = import("@reduxjs/toolkit/query").TSHelpersId<(Omit<{
+    status: import("@reduxjs/toolkit/query").QueryStatus.uninitialized;
+    originalArgs?: undefined | undefined;
+    data?: undefined | undefined;
+    error?: undefined | undefined;
+    requestId?: undefined | undefined;
+    endpointName?: string | undefined;
+    startedTimeStamp?: undefined | undefined;
+    fulfilledTimeStamp?: undefined | undefined;
+} & {
+    currentData?: import("./types").CompletionOutlineBlock | undefined;
+    isUninitialized: false;
+    isLoading: false;
+    isFetching: false;
+    isSuccess: false;
+    isError: false;
+}, "isUninitialized"> & {
+    isUninitialized: true;
+}) | import("@reduxjs/toolkit/query").TSHelpersOverride<import("@reduxjs/toolkit/query").QuerySubState<import("@reduxjs/toolkit/query").QueryDefinition<import("./types").LearnerCompletionArgs, import("@reduxjs/toolkit/query").BaseQueryFn<import("../utils").CustomQueryArgs, unknown, import("../utils").ExtendedFetchBaseQueryError, Record<string, unknown>, import("@reduxjs/toolkit/query").FetchBaseQueryMeta>, "user-enrolled-courses" | "user-assigned-courses", import("./types").CompletionOutlineBlock, "coursesApiSlice", unknown>> & {
+    currentData?: import("./types").CompletionOutlineBlock | undefined;
+    isUninitialized: false;
+    isLoading: false;
+    isFetching: false;
+    isSuccess: false;
+    isError: false;
+}, {
+    isLoading: true;
+    isFetching: boolean;
+    data: undefined;
+} | ({
+    isSuccess: true;
+    isFetching: true;
+    error: undefined;
+} & Required<Pick<import("@reduxjs/toolkit/query").QuerySubState<import("@reduxjs/toolkit/query").QueryDefinition<import("./types").LearnerCompletionArgs, import("@reduxjs/toolkit/query").BaseQueryFn<import("../utils").CustomQueryArgs, unknown, import("../utils").ExtendedFetchBaseQueryError, Record<string, unknown>, import("@reduxjs/toolkit/query").FetchBaseQueryMeta>, "user-enrolled-courses" | "user-assigned-courses", import("./types").CompletionOutlineBlock, "coursesApiSlice", unknown>> & {
+    currentData?: import("./types").CompletionOutlineBlock | undefined;
+    isUninitialized: false;
+    isLoading: false;
+    isFetching: false;
+    isSuccess: false;
+    isError: false;
+}, "data" | "fulfilledTimeStamp">>) | ({
+    isSuccess: true;
+    isFetching: false;
+    error: undefined;
+} & Required<Pick<import("@reduxjs/toolkit/query").QuerySubState<import("@reduxjs/toolkit/query").QueryDefinition<import("./types").LearnerCompletionArgs, import("@reduxjs/toolkit/query").BaseQueryFn<import("../utils").CustomQueryArgs, unknown, import("../utils").ExtendedFetchBaseQueryError, Record<string, unknown>, import("@reduxjs/toolkit/query").FetchBaseQueryMeta>, "user-enrolled-courses" | "user-assigned-courses", import("./types").CompletionOutlineBlock, "coursesApiSlice", unknown>> & {
+    currentData?: import("./types").CompletionOutlineBlock | undefined;
+    isUninitialized: false;
+    isLoading: false;
+    isFetching: false;
+    isSuccess: false;
+    isError: false;
+}, "data" | "fulfilledTimeStamp" | "currentData">>) | ({
+    isError: true;
+} & Required<Pick<import("@reduxjs/toolkit/query").QuerySubState<import("@reduxjs/toolkit/query").QueryDefinition<import("./types").LearnerCompletionArgs, import("@reduxjs/toolkit/query").BaseQueryFn<import("../utils").CustomQueryArgs, unknown, import("../utils").ExtendedFetchBaseQueryError, Record<string, unknown>, import("@reduxjs/toolkit/query").FetchBaseQueryMeta>, "user-enrolled-courses" | "user-assigned-courses", import("./types").CompletionOutlineBlock, "coursesApiSlice", unknown>> & {
+    currentData?: import("./types").CompletionOutlineBlock | undefined;
+    isUninitialized: false;
+    isLoading: false;
+    isFetching: false;
+    isSuccess: false;
+    isError: false;
+}, "error">>)>> & {
+    status: import("@reduxjs/toolkit/query").QueryStatus;
+}>(options?: (import("@reduxjs/toolkit/query").SubscriptionOptions & Omit<{
+    skip?: boolean;
+    selectFromResult?: ((state: import("@reduxjs/toolkit/query").TSHelpersId<(Omit<{
+        status: import("@reduxjs/toolkit/query").QueryStatus.uninitialized;
+        originalArgs?: undefined | undefined;
+        data?: undefined | undefined;
+        error?: undefined | undefined;
+        requestId?: undefined | undefined;
+        endpointName?: string | undefined;
+        startedTimeStamp?: undefined | undefined;
+        fulfilledTimeStamp?: undefined | undefined;
+    } & {
+        currentData?: import("./types").CompletionOutlineBlock | undefined;
+        isUninitialized: false;
+        isLoading: false;
+        isFetching: false;
+        isSuccess: false;
+        isError: false;
+    }, "isUninitialized"> & {
+        isUninitialized: true;
+    }) | import("@reduxjs/toolkit/query").TSHelpersOverride<import("@reduxjs/toolkit/query").QuerySubState<import("@reduxjs/toolkit/query").QueryDefinition<import("./types").LearnerCompletionArgs, import("@reduxjs/toolkit/query").BaseQueryFn<import("../utils").CustomQueryArgs, unknown, import("../utils").ExtendedFetchBaseQueryError, Record<string, unknown>, import("@reduxjs/toolkit/query").FetchBaseQueryMeta>, "user-enrolled-courses" | "user-assigned-courses", import("./types").CompletionOutlineBlock, "coursesApiSlice", unknown>> & {
+        currentData?: import("./types").CompletionOutlineBlock | undefined;
+        isUninitialized: false;
+        isLoading: false;
+        isFetching: false;
+        isSuccess: false;
+        isError: false;
+    }, {
+        isLoading: true;
+        isFetching: boolean;
+        data: undefined;
+    } | ({
+        isSuccess: true;
+        isFetching: true;
+        error: undefined;
+    } & Required<Pick<import("@reduxjs/toolkit/query").QuerySubState<import("@reduxjs/toolkit/query").QueryDefinition<import("./types").LearnerCompletionArgs, import("@reduxjs/toolkit/query").BaseQueryFn<import("../utils").CustomQueryArgs, unknown, import("../utils").ExtendedFetchBaseQueryError, Record<string, unknown>, import("@reduxjs/toolkit/query").FetchBaseQueryMeta>, "user-enrolled-courses" | "user-assigned-courses", import("./types").CompletionOutlineBlock, "coursesApiSlice", unknown>> & {
+        currentData?: import("./types").CompletionOutlineBlock | undefined;
+        isUninitialized: false;
+        isLoading: false;
+        isFetching: false;
+        isSuccess: false;
+        isError: false;
+    }, "data" | "fulfilledTimeStamp">>) | ({
+        isSuccess: true;
+        isFetching: false;
+        error: undefined;
+    } & Required<Pick<import("@reduxjs/toolkit/query").QuerySubState<import("@reduxjs/toolkit/query").QueryDefinition<import("./types").LearnerCompletionArgs, import("@reduxjs/toolkit/query").BaseQueryFn<import("../utils").CustomQueryArgs, unknown, import("../utils").ExtendedFetchBaseQueryError, Record<string, unknown>, import("@reduxjs/toolkit/query").FetchBaseQueryMeta>, "user-enrolled-courses" | "user-assigned-courses", import("./types").CompletionOutlineBlock, "coursesApiSlice", unknown>> & {
+        currentData?: import("./types").CompletionOutlineBlock | undefined;
+        isUninitialized: false;
+        isLoading: false;
+        isFetching: false;
+        isSuccess: false;
+        isError: false;
+    }, "data" | "fulfilledTimeStamp" | "currentData">>) | ({
+        isError: true;
+    } & Required<Pick<import("@reduxjs/toolkit/query").QuerySubState<import("@reduxjs/toolkit/query").QueryDefinition<import("./types").LearnerCompletionArgs, import("@reduxjs/toolkit/query").BaseQueryFn<import("../utils").CustomQueryArgs, unknown, import("../utils").ExtendedFetchBaseQueryError, Record<string, unknown>, import("@reduxjs/toolkit/query").FetchBaseQueryMeta>, "user-enrolled-courses" | "user-assigned-courses", import("./types").CompletionOutlineBlock, "coursesApiSlice", unknown>> & {
+        currentData?: import("./types").CompletionOutlineBlock | undefined;
+        isUninitialized: false;
+        isLoading: false;
+        isFetching: false;
+        isSuccess: false;
+        isError: false;
+    }, "error">>)>> & {
+        status: import("@reduxjs/toolkit/query").QueryStatus;
+    }) => R) | undefined;
+}, "skip">) | undefined) => [(arg: import("./types").LearnerCompletionArgs, preferCacheValue?: boolean) => import("@reduxjs/toolkit/query").QueryActionCreatorResult<import("@reduxjs/toolkit/query").QueryDefinition<import("./types").LearnerCompletionArgs, import("@reduxjs/toolkit/query").BaseQueryFn<import("../utils").CustomQueryArgs, unknown, import("../utils").ExtendedFetchBaseQueryError, Record<string, unknown>, import("@reduxjs/toolkit/query").FetchBaseQueryMeta>, "user-enrolled-courses" | "user-assigned-courses", import("./types").CompletionOutlineBlock, "coursesApiSlice", unknown>>, [R][R extends any ? 0 : never] & {
+    reset: () => void;
+}, {
+    lastArg: import("./types").LearnerCompletionArgs;
 }];

package/dist/src/features/courses/completion.d.ts

@@ -0,0 +1,47 @@
+import type { BaseQueryApi } from '@reduxjs/toolkit/query';
+import { type ExtendedFetchBaseQueryError } from '../utils';
+import type { CompletionOutlineBlock, CompletionOutlineSection, FlatCompletionOutlineEntry, LearnerCompletionArgs, LearnerCompletionEndpoint, LearnerCompletionError, NormalizedCompletionOutlineBlock } from './types';
+export declare const LEARNER_COMPLETION_PATH = "/api/catalog/enrollment/courses/completion/";
+/**
+ * Checks the args carry exactly one learner identifier plus `course_id` and
+ * `platform_key`. Returns a reason string when they don't.
+ */
+export declare function validateLearnerCompletionArgs(args: LearnerCompletionArgs): string | 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.
+ */
+export declare function buildLearnerCompletionUrl(args: LearnerCompletionArgs, endpoint: LearnerCompletionEndpoint): string;
+type QueryResult<T> = {
+    data: T;
+} | {
+    error: ExtendedFetchBaseQueryError;
+};
+/**
+ * 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.
+ */
+export declare function fetchLearnerCompletion<T>(args: LearnerCompletionArgs, endpoint: LearnerCompletionEndpoint, api: BaseQueryApi, extraOptions?: Record<string, unknown>): Promise<QueryResult<T>>;
+/**
+ * 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.
+ */
+export declare function normalizeLearnerCompletionError(error: unknown): LearnerCompletionError | null;
+/** Fills the fields edX omits: `children ?? []`, `complete`/`resume_block ?? false`. */
+export declare function normalizeOutline(block: CompletionOutlineBlock): NormalizedCompletionOutlineBlock;
+/** Depth-first, course order. The root has depth 0 and `parentId` null. */
+export declare function flattenOutline(root: CompletionOutlineBlock): FlatCompletionOutlineEntry[];
+/**
+ * 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.
+ */
+export declare function findResumeBlock(root: CompletionOutlineBlock): CompletionOutlineBlock | null;
+/** Counts leaves (blocks without children) by `type`. */
+export declare function countByType(root: CompletionOutlineBlock): Record<string, number>;
+/** Top-level sections (chapters) for a summary view, in course order. */
+export declare function getSections(root: CompletionOutlineBlock): CompletionOutlineSection[];
+export {};

package/dist/src/features/courses/types.d.ts

@@ -24,3 +24,97 @@ export interface EnrolledCourseResponse {
     previous_page: number | null;
     results: EnrolledCourse[];
 }
+/**
+ * Learner course completion (DM proxy over Open edX completion).
+ * `GET /api/catalog/enrollment/courses/completion/`
+ *
+ * The learner must always be named explicitly, even when reading one's own
+ * data: edX ignores `username` for non-staff tokens, so the DM resolves the
+ * learner and checks the caller may read them.
+ */
+export type LearnerIdentifier = {
+    username: string;
+    user_id?: never;
+    email?: never;
+} | {
+    user_id: string | number;
+    username?: never;
+    email?: never;
+} | {
+    email: string;
+    username?: never;
+    user_id?: never;
+};
+/**
+ * `endpoint` selector accepted by the DM. Only `outline` is implemented;
+ * the others are listed so sibling queries can reuse the URL builder.
+ */
+export type LearnerCompletionEndpoint = 'status' | 'outline' | 'blocks' | 'progress';
+export type LearnerCompletionArgs = LearnerIdentifier & {
+    course_id: string;
+    platform_key: string;
+};
+export type LearnerCourseOutlineArgs = LearnerCompletionArgs;
+export interface SpecialExamInfo {
+    short_description: string;
+    suggested_icon: string;
+    in_completed_state: boolean;
+}
+export interface CompletionOutlineBlock {
+    /** Full usage key; the only globally unique field. */
+    id: string;
+    block_id: string;
+    /** 'course' | 'chapter' | 'sequential' | 'vertical' | 'problem' | 'video' | 'html' | … */
+    type: string;
+    display_name: string;
+    lms_web_url: string;
+    legacy_web_url: string;
+    student_view_url: string;
+    graded: boolean;
+    start: string;
+    has_score: boolean;
+    scored: boolean;
+    num_graded_problems: number;
+    /** 0–100, computed by the backend. Display as-is; don't recompute. */
+    completion_percentage: number;
+    /** Absent on leaves and on empty containers. */
+    children?: CompletionOutlineBlock[];
+    /** Absent means false (leaves only carry it when true). */
+    complete?: boolean;
+    /** Leaves only; 0–1. */
+    completion?: number;
+    weight?: number;
+    /** Only present (true) along the path to the last-visited leaf. */
+    resume_block?: boolean;
+    special_exam_info?: SpecialExamInfo;
+    /** Root only. */
+    has_scheduled_content?: boolean;
+}
+/** Root node, `type === 'course'`. */
+export type CompletionOutlineResponse = CompletionOutlineBlock;
+export type NormalizedCompletionOutlineBlock = Omit<CompletionOutlineBlock, 'children' | 'complete' | 'resume_block'> & {
+    children: NormalizedCompletionOutlineBlock[];
+    complete: boolean;
+    resume_block: boolean;
+};
+export interface FlatCompletionOutlineEntry {
+    block: CompletionOutlineBlock;
+    depth: number;
+    parentId: string | null;
+    /** Display names from the root down to (and including) this block. */
+    path: string[];
+}
+export interface CompletionOutlineSection {
+    id: string;
+    display_name: string;
+    completion_percentage: number;
+    complete: boolean;
+    block: CompletionOutlineBlock;
+}
+export type LearnerCompletionErrorKind = 'invalid_request' | 'unauthorized' | 'forbidden' | 'not_enrolled' | 'unavailable' | 'unknown';
+export interface LearnerCompletionError {
+    kind: LearnerCompletionErrorKind;
+    status?: number | string;
+    /** Only `unavailable` (502/503/504, network) is worth retrying. */
+    retryable: boolean;
+}

package/dist/src/index.d.ts

@@ -43,6 +43,7 @@ export * from './features/catalog/api-slice';
 export * from './features/per-learner/api-slice';
 export * from './features/courses/api-slice';
 export * from './features/courses/types';
+export * from './features/courses/completion';
 export * from './features/course-metadata/api-slice';
 export * from './features/course-metadata/types';
 export * from './features/edx-sso/api-slice';