@iblai/iblai-api 4.6.2-dev1-ai-plus → 4.6.2-dev2-ai

package/dist/types/services/AiAnalyticsService.d.ts

@@ -5,6 +5,7 @@ import type { AnalyticsOverview } from '../models/AnalyticsOverview';
 import type { Average } from '../models/Average';
 import type { AverageOvertime } from '../models/AverageOvertime';
 import type { AvgCourseGradeWithCutoff } from '../models/AvgCourseGradeWithCutoff';
+import type { BaseFinanceResponse } from '../models/BaseFinanceResponse';
 import type { ChatHistoryFilterData } from '../models/ChatHistoryFilterData';
 import type { ConversationMessage } from '../models/ConversationMessage';
 import type { Conversations } from '../models/Conversations';
@@ -21,6 +22,7 @@ import type { DetailedGradeView } from '../models/DetailedGradeView';
 import type { EngagementPerCourse } from '../models/EngagementPerCourse';
 import type { Enrollments } from '../models/Enrollments';
 import type { EnrollmentsPerUser } from '../models/EnrollmentsPerUser';
+import type { FinanceDetailsResponse } from '../models/FinanceDetailsResponse';
 import type { GradingPerUser } from '../models/GradingPerUser';
 import type { GroupList } from '../models/GroupList';
 import type { LearnerInformationAPI } from '../models/LearnerInformationAPI';
@@ -3977,6 +3979,234 @@ export declare class AiAnalyticsService {
          */
         startDate?: string;
     }): CancelablePromise<GroupList>;
+    /**
+     * Financial Analytics API - Get comprehensive cost metrics with comparison analysis.
+     *
+     * This endpoint provides period-based cost analysis (not cumulative) with support for:
+     * - Multiple time granularities and metrics
+     * - Cross-dimensional filtering
+     * - Percentage change vs comparison periods
+     * - Forward-filled time series
+     *
+     * **Examples:**
+     *
+     * **Basic Weekly Costs:**
+     * ```
+     * GET /api/v2/analytics/financial/?metric=weekly_costs&comparison_days=10
+     * ```
+     *
+     * **Platform & Mentor Filtered:**
+     * ```
+     * # Get total costs for a specific platform and mentor
+     * GET /api/v2/analytics/financial/?metric=total_costs&platform_key=web-app&mentor_unique_id=mentor-123&comparison_days=14
+     * ```
+     *
+     * **Monthly Costs by Provider:**
+     * ```
+     * GET /api/v2/analytics/financial/?metric=monthly_costs&provider=openai&granularity=month&comparison_days=30
+     * ```
+     *
+     * **Daily Costs for Specific User:**
+     * ```
+     * GET /api/v2/analytics/financial/?metric=total_costs&username=user-456&granularity=day&start_date=2025-01-15&end_date=2025-01-21&comparison_days=7
+     * ```
+     *
+     *
+     * **Response Structure:**
+     * ```json
+     * {
+         * "metric": "weekly_costs",
+         * "value": 12.47,
+         * "percentage_change": 8.5,
+         * "overtime": [
+             * {"date": "2025-01-06", "value": 2.89},
+             * {"date": "2025-01-13", "value": 3.12}
+             * ],
+             * "period_info": {
+                 * "start_date": "2025-01-01",
+                 * "end_date": "2025-01-31",
+                 * "period_days": 31
+                 * },
+                 * "comparison_info": {
+                     * "previous_period_value": 11.50,
+                     * ...
+                     * }
+                     * }
+                     * ```
+                     * @returns BaseFinanceResponse Successful financial metrics response with period-based cost data
+                     * @throws ApiError
+                     */
+    static analyticsFinancialRetrieve({ metric, allTime, comparisonDays, endDate, fillMethod, granularity, llmModel, mentorUniqueId, platformKey, provider, showOvertime, startDate, username, }: {
+        /**
+         * Type of financial metric to retrieve
+         *
+         * * `total_costs` - Total costs for selected timeframe
+         * * `weekly_costs` - Costs for current/selected week
+         * * `monthly_costs` - Costs for current/selected month
+         */
+        metric: 'total_costs' | 'weekly_costs' | 'monthly_costs';
+        /**
+         * calculate from platform inception (ignores date filters)
+         */
+        allTime?: boolean;
+        /**
+         * Number of days for comparison period to calculate percentage change (e.g., 10 for 10-day comparison)
+         */
+        comparisonDays?: number;
+        /**
+         * End date for analysis (YYYY-MM-DD). Defaults to today.
+         */
+        endDate?: string;
+        /**
+         * Method for filling missing time periods in overtime data
+         *
+         * * `zero` - Fill missing periods with zero
+         * * `previous` - Fill missing periods with previous value
+         */
+        fillMethod?: 'zero' | 'previous';
+        /**
+         * Time granularity for overtime series data
+         *
+         * * `day` - Daily data points
+         * * `week` - Weekly data points
+         * * `month` - Monthly data points
+         */
+        granularity?: 'day' | 'week' | 'month';
+        /**
+         * Filter by specific LLM model (e.g., gpt-4o, claude-3-5-sonnet)
+         */
+        llmModel?: string;
+        /**
+         * Filter by specific mentor ID
+         */
+        mentorUniqueId?: string;
+        /**
+         * Filter by specific platform key
+         */
+        platformKey?: string;
+        /**
+         * Filter by AI provider
+         *
+         * * `openai` - OpenAI
+         * * `anthropic` - Anthropic
+         * * `azure` - Azure
+         * * `google` - Google
+         * * `meta` - Meta
+         * * `other` - Other
+         */
+        provider?: 'openai' | 'anthropic' | 'azure' | 'google' | 'meta' | 'other';
+        /**
+         * Whether to include overtime series data in response
+         */
+        showOvertime?: boolean;
+        /**
+         * Start date for analysis (YYYY-MM-DD). Defaults to 30 days ago.
+         */
+        startDate?: string;
+        /**
+         * Filter by specific username - returns costs for this user only
+         */
+        username?: string;
+    }): CancelablePromise<BaseFinanceResponse>;
+    /**
+     * Financial Details Analytics API – paginated cost tables with flexible grouping.
+     *
+     * This endpoint returns tabular cost metrics aggregated by the dimension
+     * specified via the `group_by` query parameter.  One or more KPI columns
+     * can be requested through the comma-separated `metrics` list while
+     * typical filters (date range, provider, platform_key, user, etc.) narrow the
+     * dataset.  Results are paginated with `page` / `limit`.
+     *
+     * **Required query parameters**
+     * - group_by – provider | llm_model | username | user_id | date | session_id
+     * - metrics – csv list of KPI names, e.g. total_cost, sessions, cost_per_session
+     *
+     * **Shared optional filters**
+     * - start_date, end_date   – ISO yyyy-mm-dd (ignored when all_time=true)
+     * - platform_key           – tenant isolation
+     * - mentor_unique_id       – filter to one mentor
+     * - username / user_id     – filter to a learner
+     * - provider / llm_model   – filter to LLM provider / model
+     * - all_time               – true → lifetime totals
+     * - page (default 1), limit (default 50)
+     *
+     * **Examples**
+     * --------
+     * 1. Cost by provider for the last week
+     * ```
+     * GET /api/v2/analytics/financial/details?
+     * group_by=provider&
+     * metrics=total_cost&
+     * start_date=2025-01-01&
+     * end_date=2025-01-07&
+     * page=1&limit=10
+     * ```
+     *
+     * 2. Lifetime cost per user with extra KPIs
+     * ```
+     * GET /api/v2/analytics/financial/details?
+     * group_by=username&
+     * metrics=total_cost,sessions,cost_per_session&
+     * all_time=true&page=1&limit=50
+     * ```
+     * 3. Cost by LLM model with tenant filter
+     * ```
+     * GET /api/v2/analytics/financial/details?
+     * group_by=llm_model&
+     * metrics=total_cost&
+     * platform_key=web-app&
+     * start_date=2025-01-01&end_date=2025-01-31
+     * ```
+     * Response structure
+     * -------------------
+     * ```
+     * {
+         * "page": 1,
+         * "limit": 10,
+         * "total_pages": 1,
+         * "total_records": 3,
+         * "rows": [
+             * {"provider": "openai", "total_cost": 2.5},
+             * {"provider": "anthropic", "total_cost": 1.0},
+             * {"provider": "azure",    "total_cost": 0.5}
+             * ],
+             * "metrics": [
+                 * {
+                     * "name": "total_cost",
+                     * "unit": "$",
+                     * "description": "Cost for this entity in period"
+                     * }
+                     * ],
+                     * "total_cost": 4.0   // optional grand-total when available
+                     * }
+                     * ``
+                     * @returns FinanceDetailsResponse
+                     * @throws ApiError
+                     */
+    static analyticsFinancialDetailsRetrieve({ groupBy, allTime, endDate, limit, llmModel, mentorUniqueId, metrics, page, platformKey, provider, startDate, username, }: {
+        /**
+         * Dimension to group by
+         *
+         * * `provider` - Group by provider
+         * * `llm_model` - Group by LLM model
+         * * `username` - Group by username
+         */
+        groupBy: 'provider' | 'llm_model' | 'username';
+        allTime?: boolean;
+        endDate?: string;
+        limit?: number;
+        llmModel?: string;
+        mentorUniqueId?: string;
+        /**
+         * Comma-separated list of metrics (e.g. total_cost,sessions, last_active)
+         */
+        metrics?: string;
+        page?: number;
+        platformKey?: string;
+        provider?: string;
+        startDate?: string;
+        username?: string;
+    }): CancelablePromise<FinanceDetailsResponse>;
     /**
      * Update time spent tracking data from client-side events.
      *

package/dist/types/services/AnalyticsService.d.ts

@@ -0,0 +1,233 @@
+import type { BaseFinanceResponse } from '../models/BaseFinanceResponse';
+import type { FinanceDetailsResponse } from '../models/FinanceDetailsResponse';
+import type { CancelablePromise } from '../core/CancelablePromise';
+export declare class AnalyticsService {
+    /**
+     * Financial Analytics API - Get comprehensive cost metrics with comparison analysis.
+     *
+     * This endpoint provides period-based cost analysis (not cumulative) with support for:
+     * - Multiple time granularities and metrics
+     * - Cross-dimensional filtering
+     * - Percentage change vs comparison periods
+     * - Forward-filled time series
+     *
+     * **Examples:**
+     *
+     * **Basic Weekly Costs:**
+     * ```
+     * GET /api/v2/analytics/financial/?metric=weekly_costs&comparison_days=10
+     * ```
+     *
+     * **Platform & Mentor Filtered:**
+     * ```
+     * # Get total costs for a specific platform and mentor
+     * GET /api/v2/analytics/financial/?metric=total_costs&platform_key=web-app&mentor_unique_id=mentor-123&comparison_days=14
+     * ```
+     *
+     * **Monthly Costs by Provider:**
+     * ```
+     * GET /api/v2/analytics/financial/?metric=monthly_costs&provider=openai&granularity=month&comparison_days=30
+     * ```
+     *
+     * **Daily Costs for Specific User:**
+     * ```
+     * GET /api/v2/analytics/financial/?metric=total_costs&username=user-456&granularity=day&start_date=2025-01-15&end_date=2025-01-21&comparison_days=7
+     * ```
+     *
+     *
+     * **Response Structure:**
+     * ```json
+     * {
+         * "metric": "weekly_costs",
+         * "value": 12.47,
+         * "percentage_change": 8.5,
+         * "overtime": [
+             * {"date": "2025-01-06", "value": 2.89},
+             * {"date": "2025-01-13", "value": 3.12}
+             * ],
+             * "period_info": {
+                 * "start_date": "2025-01-01",
+                 * "end_date": "2025-01-31",
+                 * "period_days": 31
+                 * },
+                 * "comparison_info": {
+                     * "previous_period_value": 11.50,
+                     * ...
+                     * }
+                     * }
+                     * ```
+                     * @returns BaseFinanceResponse Successful financial metrics response with period-based cost data
+                     * @throws ApiError
+                     */
+    static analyticsFinancialRetrieve({ metric, allTime, comparisonDays, endDate, fillMethod, granularity, llmModel, mentorUniqueId, platformKey, provider, showOvertime, startDate, username, }: {
+        /**
+         * Type of financial metric to retrieve
+         *
+         * * `total_costs` - Total costs for selected timeframe
+         * * `weekly_costs` - Costs for current/selected week
+         * * `monthly_costs` - Costs for current/selected month
+         */
+        metric: 'total_costs' | 'weekly_costs' | 'monthly_costs';
+        /**
+         * calculate from platform inception (ignores date filters)
+         */
+        allTime?: boolean;
+        /**
+         * Number of days for comparison period to calculate percentage change (e.g., 10 for 10-day comparison)
+         */
+        comparisonDays?: number;
+        /**
+         * End date for analysis (YYYY-MM-DD). Defaults to today.
+         */
+        endDate?: string;
+        /**
+         * Method for filling missing time periods in overtime data
+         *
+         * * `zero` - Fill missing periods with zero
+         * * `previous` - Fill missing periods with previous value
+         */
+        fillMethod?: 'zero' | 'previous';
+        /**
+         * Time granularity for overtime series data
+         *
+         * * `day` - Daily data points
+         * * `week` - Weekly data points
+         * * `month` - Monthly data points
+         */
+        granularity?: 'day' | 'week' | 'month';
+        /**
+         * Filter by specific LLM model (e.g., gpt-4o, claude-3-5-sonnet)
+         */
+        llmModel?: string;
+        /**
+         * Filter by specific mentor ID
+         */
+        mentorUniqueId?: string;
+        /**
+         * Filter by specific platform key
+         */
+        platformKey?: string;
+        /**
+         * Filter by AI provider
+         *
+         * * `openai` - OpenAI
+         * * `anthropic` - Anthropic
+         * * `azure` - Azure
+         * * `google` - Google
+         * * `meta` - Meta
+         * * `other` - Other
+         */
+        provider?: 'openai' | 'anthropic' | 'azure' | 'google' | 'meta' | 'other';
+        /**
+         * Whether to include overtime series data in response
+         */
+        showOvertime?: boolean;
+        /**
+         * Start date for analysis (YYYY-MM-DD). Defaults to 30 days ago.
+         */
+        startDate?: string;
+        /**
+         * Filter by specific username - returns costs for this user only
+         */
+        username?: string;
+    }): CancelablePromise<BaseFinanceResponse>;
+    /**
+     * Financial Details Analytics API – paginated cost tables with flexible grouping.
+     *
+     * This endpoint returns tabular cost metrics aggregated by the dimension
+     * specified via the `group_by` query parameter.  One or more KPI columns
+     * can be requested through the comma-separated `metrics` list while
+     * typical filters (date range, provider, platform_key, user, etc.) narrow the
+     * dataset.  Results are paginated with `page` / `limit`.
+     *
+     * **Required query parameters**
+     * - group_by – provider | llm_model | username | user_id | date | session_id
+     * - metrics – csv list of KPI names, e.g. total_cost, sessions, cost_per_session
+     *
+     * **Shared optional filters**
+     * - start_date, end_date   – ISO yyyy-mm-dd (ignored when all_time=true)
+     * - platform_key           – tenant isolation
+     * - mentor_unique_id       – filter to one mentor
+     * - username / user_id     – filter to a learner
+     * - provider / llm_model   – filter to LLM provider / model
+     * - all_time               – true → lifetime totals
+     * - page (default 1), limit (default 50)
+     *
+     * **Examples**
+     * --------
+     * 1. Cost by provider for the last week
+     * ```
+     * GET /api/v2/analytics/financial/details?
+     * group_by=provider&
+     * metrics=total_cost&
+     * start_date=2025-01-01&
+     * end_date=2025-01-07&
+     * page=1&limit=10
+     * ```
+     *
+     * 2. Lifetime cost per user with extra KPIs
+     * ```
+     * GET /api/v2/analytics/financial/details?
+     * group_by=username&
+     * metrics=total_cost,sessions,cost_per_session&
+     * all_time=true&page=1&limit=50
+     * ```
+     * 3. Cost by LLM model with tenant filter
+     * ```
+     * GET /api/v2/analytics/financial/details?
+     * group_by=llm_model&
+     * metrics=total_cost&
+     * platform_key=web-app&
+     * start_date=2025-01-01&end_date=2025-01-31
+     * ```
+     * Response structure
+     * -------------------
+     * ```
+     * {
+         * "page": 1,
+         * "limit": 10,
+         * "total_pages": 1,
+         * "total_records": 3,
+         * "rows": [
+             * {"provider": "openai", "total_cost": 2.5},
+             * {"provider": "anthropic", "total_cost": 1.0},
+             * {"provider": "azure",    "total_cost": 0.5}
+             * ],
+             * "metrics": [
+                 * {
+                     * "name": "total_cost",
+                     * "unit": "$",
+                     * "description": "Cost for this entity in period"
+                     * }
+                     * ],
+                     * "total_cost": 4.0   // optional grand-total when available
+                     * }
+                     * ``
+                     * @returns FinanceDetailsResponse
+                     * @throws ApiError
+                     */
+    static analyticsFinancialDetailsRetrieve({ groupBy, allTime, endDate, limit, llmModel, mentorUniqueId, metrics, page, platformKey, provider, startDate, username, }: {
+        /**
+         * Dimension to group by
+         *
+         * * `provider` - Group by provider
+         * * `llm_model` - Group by LLM model
+         * * `username` - Group by username
+         */
+        groupBy: 'provider' | 'llm_model' | 'username';
+        allTime?: boolean;
+        endDate?: string;
+        limit?: number;
+        llmModel?: string;
+        mentorUniqueId?: string;
+        /**
+         * Comma-separated list of metrics (e.g. total_cost,sessions, last_active)
+         */
+        metrics?: string;
+        page?: number;
+        platformKey?: string;
+        provider?: string;
+        startDate?: string;
+        username?: string;
+    }): CancelablePromise<FinanceDetailsResponse>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iblai/iblai-api",
-  "version": "4.6.2-dev1-ai-plus",
+  "version": "4.6.2-dev2-ai",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",
   "type": "module",

package/src/core/OpenAPI.ts

@@ -21,7 +21,7 @@ export type OpenAPIConfig = {
 
 export const OpenAPI: OpenAPIConfig = {
     BASE: 'https://base.manager.iblai.app',
-    VERSION: '4.6.2-ai-plus',
+    VERSION: '4.6.2-dev-ai',
     WITH_CREDENTIALS: false,
     CREDENTIALS: 'include',
     TOKEN: undefined,