// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { APIResource } from '../../core/resource';
import { APIPromise } from '../../core/api-promise';
import { type Uploadable } from '../../core/uploads';
import { buildHeaders } from '../../internal/headers';
import { RequestOptions } from '../../internal/request-options';
import { path } from '../../internal/utils/path';

export class ChatAnalytics extends APIResource {
  /**
   * Get chat analytics and user statistics
   *
   * @example
   * ```ts
   * const chatAnalyticsResponse =
   *   await client.v1.chatAnalytics.analyze();
   * ```
   */
  analyze(
    query: ChatAnalyticsAnalyzeParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<ChatAnalyticsResponse> {
    return this._client.get('/api/v1/chat-analytics/analyze', { query, ...options });
  }

  /**
   * Export chat analytics data as CSV
   *
   * @example
   * ```ts
   * const response = await client.v1.chatAnalytics.export();
   * ```
   */
  export(
    query: ChatAnalyticsExportParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<string> {
    return this._client.get('/api/v1/chat-analytics/export', {
      query,
      ...options,
      headers: buildHeaders([{ Accept: 'text/csv' }, options?.headers]),
    });
  }

  /**
   * Get chat analytics for a specific component
   *
   * @example
   * ```ts
   * const chatAnalyticsResponse =
   *   await client.v1.chatAnalytics.getComponent('componentId');
   * ```
   */
  getComponent(
    componentID: string,
    query: ChatAnalyticsGetComponentParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<ChatAnalyticsResponse> {
    return this._client.get(path`/api/v1/chat-analytics/component/${componentID}`, { query, ...options });
  }
}

export interface ChatAnalyticsResponse {
  /**
   * Date when analytics were generated
   */
  generatedAt: string;

  /**
   * Analytics summary
   */
  summary: ChatAnalyticsResponse.Summary;

  /**
   * User statistics
   */
  userStats: Array<ChatAnalyticsResponse.UserStat>;
}

export namespace ChatAnalyticsResponse {
  /**
   * Analytics summary
   */
  export interface Summary {
    /**
     * Average messages per user
     */
    averageMessagesPerUser: number;

    /**
     * Engagement metrics
     */
    engagement: unknown;

    /**
     * Natural language summary of chat usage
     */
    summary: string;

    /**
     * Top topics discussed
     */
    topTopics: Array<string>;

    /**
     * Total messages
     */
    totalMessages: number;

    /**
     * Total chat sessions
     */
    totalSessions: number;

    /**
     * Total unique users
     */
    totalUsers: number;

    /**
     * Overall average prompting score (1-4 scale)
     */
    overallAveragePromptingScore?: number;

    /**
     * Overall average responsibility score (1-4 scale)
     */
    overallAverageResponsibilityScore?: number;

    /**
     * Overall prompting score distribution
     */
    overallPromptingDistribution?: unknown;

    /**
     * Overall responsibility score distribution
     */
    overallResponsibilityDistribution?: unknown;
  }

  export interface UserStat {
    /**
     * Average messages per session
     */
    averageMessagesPerSession: number;

    /**
     * Average session duration in minutes
     */
    averageSessionDuration: number;

    /**
     * First active date
     */
    firstActive: string;

    /**
     * Last active date
     */
    lastActive: string;

    /**
     * Top topics discussed
     */
    topTopics: Array<string>;

    /**
     * Total messages sent by user
     */
    totalMessages: number;

    /**
     * Total chat sessions
     */
    totalSessions: number;

    /**
     * User ID
     */
    userId: string;

    /**
     * Average prompting score (1-4 scale)
     */
    averagePromptingScore?: number;

    /**
     * Average responsibility score (1-4 scale)
     */
    averageResponsibilityScore?: number;

    /**
     * User email
     */
    email?: string;

    /**
     * Group IDs associated with the user
     */
    groupIds?: Array<string>;

    /**
     * User name
     */
    name?: string;

    /**
     * Prompting score distribution
     */
    promptingDistribution?: unknown;

    /**
     * Responsibility score distribution
     */
    responsibilityDistribution?: unknown;

    /**
     * Total messages graded
     */
    totalGradedMessages?: number;
  }
}

export type ChatAnalyticsExportResponse = Uploadable;

export interface ChatAnalyticsAnalyzeParams {
  /**
   * Component ID to analyze
   */
  componentId?: string;

  /**
   * End date for analysis
   */
  endDate?: string;

  /**
   * Group IDs to filter by
   */
  groupIds?: Array<string>;

  /**
   * AI model to use for analysis
   */
  modelKey?: string;

  /**
   * Organization ID to filter by
   */
  organizationId?: string;

  /**
   * Start date for analysis
   */
  startDate?: string;

  /**
   * User ID to filter by
   */
  userId?: string;
}

export interface ChatAnalyticsExportParams {
  /**
   * Component ID to analyze
   */
  componentId?: string;

  /**
   * End date for analysis
   */
  endDate?: string;

  /**
   * Group IDs to filter by
   */
  groupIds?: Array<string>;

  /**
   * AI model to use for analysis
   */
  modelKey?: string;

  /**
   * Organization ID to filter by
   */
  organizationId?: string;

  /**
   * Start date for analysis
   */
  startDate?: string;

  /**
   * User ID to filter by
   */
  userId?: string;
}

export interface ChatAnalyticsGetComponentParams {
  /**
   * End date for analysis
   */
  endDate?: string;

  /**
   * Group IDs to filter by
   */
  groupIds?: Array<string>;

  /**
   * AI model to use for analysis
   */
  modelKey?: string;

  /**
   * Organization ID to filter by
   */
  organizationId?: string;

  /**
   * Start date for analysis
   */
  startDate?: string;

  /**
   * User ID to filter by
   */
  userId?: string;
}

export declare namespace ChatAnalytics {
  export {
    type ChatAnalyticsResponse as ChatAnalyticsResponse,
    type ChatAnalyticsExportResponse as ChatAnalyticsExportResponse,
    type ChatAnalyticsAnalyzeParams as ChatAnalyticsAnalyzeParams,
    type ChatAnalyticsExportParams as ChatAnalyticsExportParams,
    type ChatAnalyticsGetComponentParams as ChatAnalyticsGetComponentParams,
  };
}