@iblai/iblai-api 4.316.1-core → 4.317.1-core

package/src/services/AiAnalyticsService.ts

@@ -252,14 +252,23 @@ export class AiAnalyticsService {
     }
     /**
      *
-     * Retrieve a holistic snapshot of a learner across catalog enrollments, mentor
+     * Retrieve a holistic snapshot of a user across catalog enrollments, agent
      * engagement, skills, credentials, and time spent data. The `metrics` query parameter controls
-     * which sections are returned and defaults to `courses` when omitted.
+     * which sections are returned and defaults to `courses` when omitted. A user can call this
+     * endpoint for themselves without passing `username`; admins pass `username` to target a
+     * user in their scope.
+     *
+     * The `mentors` section lists every agent the user has engaged, sourced from both their
+     * sessions and saved agents. Each agent's `interactions` block reports engagement depth
+     * (`session_count`, `conversation_count`, human/AI message counts, `avg_messages_per_session`),
+     * recency and stickiness (`first_interaction`, `latest_interaction`, `active_days`),
+     * affinity (`rating`, `is_starred`), and spend (`cost_usd`, in USD). The user's total
+     * agent spend is `user.total_agent_cost_usd`.
      *
      * Optional `course_id` / `program_id` / `pathway_id` scope the matching section to a
-     * single item (empty list if the learner is not enrolled — never a 404); omitting them
+     * single item (empty list if the user is not enrolled — never a 404); omitting them
      * returns the full list unchanged. When `course_id` is set, the course block is also
-     * enriched with the learner's live edX Progress data under `edx_progress` (completion
+     * enriched with the user's live edX Progress data under `edx_progress` (completion
      * summary, grade, grade summary) unless `include_edx_progress=false`. The edX call is
      * best-effort: on failure `edx_progress` is null and the DM data is still returned.
      * `program_id` / `pathway_id` get scoping only — no edX enrichment.
@@ -268,7 +277,6 @@ export class AiAnalyticsService {
      * @throws ApiError
      */
     public static analyticsLearnerDetailsRetrieve({
-        username,
         courseId,
         dateFilter = 'today',
         endDate,
@@ -281,8 +289,8 @@ export class AiAnalyticsService {
         programId,
         startDate,
         usergroupIds,
+        username,
     }: {
-        username: string,
         /**
          * Scope the `courses` and `time_spent` sections to a single course. When set, also enriches the course with live edX progress (see `include_edx_progress`).
          */
@@ -308,6 +316,9 @@ export class AiAnalyticsService {
          * When `course_id` is set, fold the learner's live edX Progress-page data (completion summary, grade, grade summary) into the course block. Defaults to true; set false to skip the edX round-trip.
          */
         includeEdxProgress?: boolean,
+        /**
+         * Comma-separated sections to return: courses, programs, pathways, agents, skills, credentials, time_spent. `agents` is an alias for the agent (mentor) section. Defaults to courses when omitted.
+         */
         metrics?: string,
         /**
          * Include overtime metrics for time_spent data (default: false)
@@ -327,6 +338,7 @@ export class AiAnalyticsService {
          * Optional list of usergroup IDs to filter results
          */
         usergroupIds?: Array<number> | null,
+        username?: string,
     }): CancelablePromise<LearnerDetailsResponse> {
         return __request(OpenAPI, {
             method: 'GET',
@@ -671,6 +683,121 @@ export class AiAnalyticsService {
                 },
             });
         }
+        /**
+         *
+         * Retrieve a holistic snapshot of a user across catalog enrollments, agent
+         * engagement, skills, credentials, and time spent data. The `metrics` query parameter controls
+         * which sections are returned and defaults to `courses` when omitted. A user can call this
+         * endpoint for themselves without passing `username`; admins pass `username` to target a
+         * user in their scope.
+         *
+         * The `mentors` section lists every agent the user has engaged, sourced from both their
+         * sessions and saved agents. Each agent's `interactions` block reports engagement depth
+         * (`session_count`, `conversation_count`, human/AI message counts, `avg_messages_per_session`),
+         * recency and stickiness (`first_interaction`, `latest_interaction`, `active_days`),
+         * affinity (`rating`, `is_starred`), and spend (`cost_usd`, in USD). The user's total
+         * agent spend is `user.total_agent_cost_usd`.
+         *
+         * Optional `course_id` / `program_id` / `pathway_id` scope the matching section to a
+         * single item (empty list if the user is not enrolled — never a 404); omitting them
+         * returns the full list unchanged. When `course_id` is set, the course block is also
+         * enriched with the user's live edX Progress data under `edx_progress` (completion
+         * summary, grade, grade summary) unless `include_edx_progress=false`. The edX call is
+         * best-effort: on failure `edx_progress` is null and the DM data is still returned.
+         * `program_id` / `pathway_id` get scoping only — no edX enrichment.
+         *
+         * @returns LearnerDetailsResponse Learner profile with requested analytics data
+         * @throws ApiError
+         */
+        public static analyticsUserRetrieve({
+            courseId,
+            dateFilter = 'today',
+            endDate,
+            granularity = 'hour',
+            includeEdxProgress = true,
+            metrics,
+            overtime = false,
+            pathwayId,
+            platformKey,
+            programId,
+            startDate,
+            usergroupIds,
+            username,
+        }: {
+            /**
+             * Scope the `courses` and `time_spent` sections to a single course. When set, also enriches the course with live edX progress (see `include_edx_progress`).
+             */
+            courseId?: string,
+            /**
+             * * `today` - Today only
+             * * `7d` - Last 7 days
+             * * `30d` - Last 30 days
+             * * `90d` - Last 90 days
+             * * `all_time` - All time
+             * * `custom` - Custom date range
+             */
+            dateFilter?: 'today' | '7d' | '30d' | '90d' | 'all_time' | 'custom',
+            endDate?: string,
+            /**
+             * * `day` - day
+             * * `hour` - hour
+             * * `week` - week
+             * * `month` - month
+             */
+            granularity?: 'day' | 'hour' | 'week' | 'month',
+            /**
+             * When `course_id` is set, fold the learner's live edX Progress-page data (completion summary, grade, grade summary) into the course block. Defaults to true; set false to skip the edX round-trip.
+             */
+            includeEdxProgress?: boolean,
+            /**
+             * Comma-separated sections to return: courses, programs, pathways, agents, skills, credentials, time_spent. `agents` is an alias for the agent (mentor) section. Defaults to courses when omitted.
+             */
+            metrics?: string,
+            /**
+             * Include overtime metrics for time_spent data (default: false)
+             */
+            overtime?: boolean,
+            /**
+             * Scope the `pathways` section to a single pathway.
+             */
+            pathwayId?: string,
+            platformKey?: string,
+            /**
+             * Scope the `programs` section to a single program.
+             */
+            programId?: string,
+            startDate?: string,
+            /**
+             * Optional list of usergroup IDs to filter results
+             */
+            usergroupIds?: Array<number> | null,
+            username?: string,
+        }): CancelablePromise<LearnerDetailsResponse> {
+            return __request(OpenAPI, {
+                method: 'GET',
+                url: '/api/analytics/user',
+                query: {
+                    'course_id': courseId,
+                    'date_filter': dateFilter,
+                    'end_date': endDate,
+                    'granularity': granularity,
+                    'include_edx_progress': includeEdxProgress,
+                    'metrics': metrics,
+                    'overtime': overtime,
+                    'pathway_id': pathwayId,
+                    'platform_key': platformKey,
+                    'program_id': programId,
+                    'start_date': startDate,
+                    'usergroup_ids': usergroupIds,
+                    'username': username,
+                },
+                errors: {
+                    400: `Bad Request - Invalid parameters supplied`,
+                    404: `Learner not found`,
+                    500: `Unexpected error`,
+                },
+            });
+        }
         /**
          * Get active user counts over time.
          *