// 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 { buildHeaders } from '../../internal/headers';
import { RequestOptions } from '../../internal/request-options';
import { path } from '../../internal/utils/path';

export class Components extends APIResource {
  /**
   * Create a new component
   *
   * @example
   * ```ts
   * const componentResponse = await client.v1.components.create(
   *   {
   *     config: { model: 'gpt-4o-mini-2024-07-18' },
   *     name: 'My Study Component',
   *     type: 'chat',
   *   },
   * );
   * ```
   */
  create(body: ComponentCreateParams, options?: RequestOptions): APIPromise<ComponentResponse> {
    return this._client.post('/api/v1/components', { body, ...options });
  }

  /**
   * Get component by ID
   *
   * @example
   * ```ts
   * const componentResponse =
   *   await client.v1.components.retrieve('id');
   * ```
   */
  retrieve(id: string, options?: RequestOptions): APIPromise<ComponentResponse> {
    return this._client.get(path`/api/v1/components/${id}`, options);
  }

  /**
   * Update component
   *
   * @example
   * ```ts
   * const componentResponse = await client.v1.components.update(
   *   'id',
   * );
   * ```
   */
  update(id: string, body: ComponentUpdateParams, options?: RequestOptions): APIPromise<ComponentResponse> {
    return this._client.patch(path`/api/v1/components/${id}`, { body, ...options });
  }

  /**
   * Get all components
   *
   * @example
   * ```ts
   * const componentResponses =
   *   await client.v1.components.list();
   * ```
   */
  list(
    query: ComponentListParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<ComponentListResponse> {
    return this._client.get('/api/v1/components', { query, ...options });
  }

  /**
   * Delete component
   *
   * @example
   * ```ts
   * await client.v1.components.delete('id');
   * ```
   */
  delete(id: string, options?: RequestOptions): APIPromise<void> {
    return this._client.delete(path`/api/v1/components/${id}`, {
      ...options,
      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
    });
  }

  /**
   * @example
   * ```ts
   * await client.v1.components.activate('id');
   * ```
   */
  activate(id: string, options?: RequestOptions): APIPromise<void> {
    return this._client.post(path`/api/v1/components/${id}/activate`, {
      ...options,
      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
    });
  }

  /**
   * @example
   * ```ts
   * await client.v1.components.deactivate('id');
   * ```
   */
  deactivate(id: string, options?: RequestOptions): APIPromise<void> {
    return this._client.post(path`/api/v1/components/${id}/deactivate`, {
      ...options,
      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
    });
  }

  /**
   * Generate embed code for component
   *
   * @example
   * ```ts
   * const response = await client.v1.components.generateEmbed(
   *   'id',
   * );
   * ```
   */
  generateEmbed(
    id: string,
    body: ComponentGenerateEmbedParams,
    options?: RequestOptions,
  ): APIPromise<ComponentGenerateEmbedResponse> {
    return this._client.post(path`/api/v1/components/${id}/embed`, { body, ...options });
  }

  /**
   * @example
   * ```ts
   * await client.v1.components.interact('id');
   * ```
   */
  interact(id: string, options?: RequestOptions): APIPromise<void> {
    return this._client.post(path`/api/v1/components/${id}/interact`, {
      ...options,
      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
    });
  }
}

export interface ComponentResponse {
  /**
   * Component ID (MongoDB ObjectId)
   */
  _id: string;

  /**
   * Unique component identifier
   */
  componentId: string;

  /**
   * Component configuration
   */
  config: unknown;

  /**
   * Creation timestamp
   */
  createdAt: string;

  /**
   * Component name
   */
  name: string;

  /**
   * Organization ID
   */
  organization: string;

  /**
   * Component status
   */
  status: 'active' | 'inactive' | 'draft';

  /**
   * Component type
   */
  type:
    | 'chat'
    | 'data_analyst'
    | 'flashcards'
    | 'scenarios'
    | 'practice_test'
    | 'audio_recap'
    | 'tutor_me'
    | 'explainers'
    | 'uploads'
    | 'chat_analytics'
    | 'performance_insights';

  /**
   * Last update timestamp
   */
  updatedAt: string;

  /**
   * Usage statistics
   */
  usage: unknown;

  /**
   * Component description
   */
  description?: string;
}

export type ComponentListResponse = Array<ComponentResponse>;

export interface ComponentGenerateEmbedResponse {
  /**
   * JWT token for authentication
   */
  token: string;

  /**
   * Component ID
   */
  componentId: string;

  /**
   * Component type
   */
  componentType: string;

  /**
   * The embed URL for iframe integration
   */
  embedUrl: string;

  /**
   * Token expiration timestamp
   */
  expiresAt: string;

  /**
   * Embed options
   */
  options: ComponentGenerateEmbedResponse.Options;
}

export namespace ComponentGenerateEmbedResponse {
  /**
   * Embed options
   */
  export interface Options {
    /**
     * Embed height
     */
    height?: string;

    /**
     * Embed width
     */
    width?: string;
  }
}

export interface ComponentCreateParams {
  /**
   * Component-specific configuration
   */
  config:
    | ComponentCreateParams.ChatConfigDto
    | ComponentCreateParams.DataAnalystConfigDto
    | ComponentCreateParams.FlashcardsConfigDto
    | ComponentCreateParams.PracticeTestConfigDto
    | ComponentCreateParams.AudioRecapConfigDto
    | ComponentCreateParams.ExplainersConfigDto
    | ComponentCreateParams.UploadsConfigDto
    | ComponentCreateParams.TutorMeConfigDto
    | ComponentCreateParams.ChatAnalyticsConfigDto;

  /**
   * Name of the component
   */
  name: string;

  /**
   * Type of component to create
   */
  type:
    | 'chat'
    | 'data_analyst'
    | 'flashcards'
    | 'scenarios'
    | 'practice_test'
    | 'audio_recap'
    | 'tutor_me'
    | 'explainers'
    | 'uploads'
    | 'chat_analytics'
    | 'performance_insights';

  /**
   * Component description
   */
  description?: string;

  /**
   * Additional metadata
   */
  metadata?: unknown;
}

export namespace ComponentCreateParams {
  export interface ChatConfigDto {
    /**
     * AI model to use
     */
    model: string;

    /**
     * Custom HTML to show in empty state instead of default icon and text
     */
    emptyStateHtml?: string;

    /**
     * Enable component creation
     */
    enableComponentCreation?: boolean;

    /**
     * Enable thumbs up/down feedback with reason
     */
    enableFeedback?: boolean;

    /**
     * Enable follow-up questions
     */
    enableFollowUps?: boolean;

    /**
     * Enable guardrails for content moderation
     */
    enableGuardrails?: boolean;

    /**
     * Enable conversation history
     */
    enableHistory?: boolean;

    /**
     * Enable message grading for prompt improvement suggestions
     */
    enableMessageGrading?: boolean;

    /**
     * Enable RAG search
     */
    enableRAGSearch?: boolean;

    /**
     * Enable reference mode - show references instead of source content
     */
    enableReferenceMode?: boolean;

    /**
     * Enable voice interactions
     */
    enableVoice?: boolean;

    /**
     * Enable web search
     */
    enableWebSearch?: boolean;

    /**
     * Folder IDs
     */
    folders?: Array<string>;

    /**
     * Guardrail rules for content moderation
     */
    guardrailRules?: Array<ChatConfigDto.GuardrailRule>;

    /**
     * Hide the default empty state (icon and text)
     */
    hideEmptyState?: boolean;

    /**
     * Hide the chat title and avatar in the embedded component
     */
    hideTitle?: boolean;

    /**
     * Material IDs
     */
    materials?: Array<string>;

    /**
     * Maximum steps for multi-step tool calls
     */
    maxSteps?: number;

    /**
     * Maximum tokens for response
     */
    maxTokens?: number;

    /**
     * System prompt for the chat
     */
    systemPrompt?: string;

    /**
     * Temperature for response generation
     */
    temperature?: number;
  }

  export namespace ChatConfigDto {
    export interface GuardrailRule {
      /**
       * Unique identifier for the rule
       */
      id: string;

      /**
       * Action to take when rule is triggered
       */
      action: 'block' | 'warn' | 'modify';

      /**
       * Condition to check
       */
      condition: string;

      /**
       * Description of the rule
       */
      description: string;

      /**
       * Message to show when rule is triggered
       */
      message?: string;
    }
  }

  export interface DataAnalystConfigDto {
    /**
     * AI model to use
     */
    model: string;

    /**
     * Enable component creation
     */
    enableComponentCreation?: boolean;

    /**
     * Enable follow-up questions
     */
    enableFollowUps?: boolean;

    /**
     * Enable conversation history
     */
    enableHistory?: boolean;

    /**
     * Enable RAG search
     */
    enableRAGSearch?: boolean;

    /**
     * Enable voice interactions
     */
    enableVoice?: boolean;

    /**
     * Enable web search
     */
    enableWebSearch?: boolean;

    /**
     * Folder IDs
     */
    folders?: Array<string>;

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

    /**
     * Material IDs
     */
    materials?: Array<string>;

    /**
     * Maximum steps for multi-step tool calls
     */
    maxSteps?: number;

    /**
     * Maximum tokens for response
     */
    maxTokens?: number;

    /**
     * System prompt for the data analyst
     */
    systemPrompt?: string;

    /**
     * Temperature for response generation
     */
    temperature?: number;
  }

  export interface FlashcardsConfigDto {
    /**
     * Types of flashcards
     */
    cardTypes?: Array<string>;

    /**
     * Difficulty level
     */
    difficulty?: 'easy' | 'medium' | 'hard' | 'mixed';

    /**
     * Folder IDs
     */
    folders?: Array<string>;

    /**
     * Learning steps configuration
     */
    learningSteps?: string;

    /**
     * Material IDs
     */
    materials?: Array<string>;

    /**
     * Maximum review interval in days
     */
    maxReviewInterval?: number;

    /**
     * AI model to use for flashcard generation
     */
    model?: string;

    /**
     * Total number of flashcards to generate
     */
    totalFlashcards?: number;

    /**
     * View mode for flashcards
     */
    viewMode?: 'spaced_repetition' | 'normal';
  }

  export interface ScenariosConfigDto {
    /**
     * Scenario characters
     */
    characters?: Array<ScenariosConfigDto.Character>;

    /**
     * Scenario context
     */
    context?: string;

    /**
     * Authored evaluation criteria. If omitted/empty at create time, the AI will
     * generate criteria.
     */
    criteria?: Array<ScenariosConfigDto.Criterion>;

    /**
     * Enable history
     */
    enableHistory?: boolean;

    /**
     * Enable voice
     */
    enableVoice?: boolean;

    /**
     * Final answer prompt
     */
    finalAnswerPrompt?: string;

    /**
     * Folder IDs
     */
    folders?: Array<string>;

    /**
     * Scenario format
     */
    format?: string;

    /**
     * Scenario goal
     */
    goal?: string;

    /**
     * Character ID for greeting
     */
    greetingCharacterId?: string;

    /**
     * Greeting message
     */
    greetingMessage?: string;

    /**
     * Material IDs
     */
    materials?: Array<string>;

    /**
     * AI model to use for scenario generation
     */
    model?: string;

    /**
     * Placeholder text
     */
    placeholderText?: string;

    /**
     * Requires final answer
     */
    requiresFinalAnswer?: boolean;

    /**
     * Available tools
     */
    tools?: Array<ScenariosConfigDto.Tool>;
  }

  export namespace ScenariosConfigDto {
    export interface Character {
      /**
       * Character ID
       */
      id: string;

      /**
       * Character name
       */
      name: string;

      /**
       * Character role
       */
      role: string;

      /**
       * Character description
       */
      description?: string;
    }

    export interface Criterion {
      /**
       * Stable identifier for this criterion
       */
      id: string;

      /**
       * What this criterion measures
       */
      description: string;

      /**
       * Importance weight 1-10
       */
      weight: number;
    }

    export interface Tool {
      /**
       * Tool ID
       */
      id: string;

      /**
       * Tool name
       */
      name: string;

      /**
       * Tool description (what it does / shows)
       */
      description: string;

      /**
       * Tool type (e.g. Database, Document)
       */
      type: string;

      /**
       * Data format provided by the tool
       */
      dataFormat?: string;
    }
  }

  export interface PracticeTestConfigDto {
    /**
     * Question types
     */
    questionTypes: Array<string>;

    /**
     * AI generation mode
     */
    aiGenerationMode?: 'balanced' | 'comprehensive' | 'focused' | 'adaptive';

    /**
     * Allow retakes
     */
    allowRetakes?: boolean;

    /**
     * Difficulty level
     */
    difficulty?: 'easy' | 'medium' | 'hard' | 'mixed';

    /**
     * Folder IDs
     */
    folders?: Array<string>;

    /**
     * Material IDs
     */
    materials?: Array<string>;

    /**
     * Maximum attempts allowed
     */
    maxAttempts?: number;

    /**
     * AI model to use for question generation and grading
     */
    model?: string;

    /**
     * Passing score percentage
     */
    passingScore?: number;

    /**
     * Distribution of question types
     */
    questionDistribution?: PracticeTestConfigDto.QuestionDistribution;

    /**
     * Number of questions per test
     */
    questionsPerTest?: number;

    /**
     * Randomize answer order
     */
    randomizeAnswers?: boolean;

    /**
     * Randomize question order
     */
    randomizeQuestions?: boolean;

    /**
     * Show correct answers after submission
     */
    showCorrectAnswers?: boolean;

    /**
     * Show explanations for answers
     */
    showExplanations?: boolean;

    /**
     * Time limit in minutes
     */
    timeLimit?: number;
  }

  export namespace PracticeTestConfigDto {
    /**
     * Distribution of question types
     */
    export interface QuestionDistribution {
      /**
       * Number of fill in the blank questions
       */
      fillinblank?: number;

      /**
       * Number of free response questions
       */
      frq?: number;

      /**
       * Number of multiple choice questions
       */
      multiplechoice?: number;

      /**
       * Number of short answer questions
       */
      shortanswer?: number;

      /**
       * Number of true/false questions
       */
      truefalse?: number;
    }
  }

  export interface AudioRecapConfigDto {
    /**
     * Duration of audio recap in minutes
     */
    duration?: number;

    /**
     * Material IDs to exclude when expanding selected folders. Has no effect on
     * materials picked directly via `materials`.
     */
    excludedMaterialIds?: Array<string>;

    /**
     * Folder IDs
     */
    folders?: Array<string>;

    /**
     * Enable multi-voice conversation mode
     */
    isMultiVoice?: boolean;

    /**
     * Material IDs
     */
    materials?: Array<string>;

    /**
     * AI model to use for generation
     */
    model?: string;

    /**
     * Number of parts to split the audio into
     */
    numParts?: number;

    /**
     * Type of audio recap
     */
    recapType?: 'SUMMARY' | 'LECTURE' | 'PODCAST' | 'AUDIO_BOOK';

    /**
     * Theme or style for the audio recap
     */
    theme?: string;

    /**
     * Specific topic to focus on
     */
    topic?: string;

    /**
     * Primary voice for narration
     */
    voice1?: string;

    /**
     * Secondary voice for multi-voice mode
     */
    voice2?: string;
  }

  export interface ExplainersConfigDto {
    /**
     * Folder IDs
     */
    folders?: Array<string>;

    /**
     * Enable image search for visuals
     */
    imageSearch?: boolean;

    /**
     * Material IDs
     */
    materials?: Array<string>;

    /**
     * AI model to use for generation
     */
    model?: string;

    /**
     * Video style
     */
    style?: string;

    /**
     * Target length in seconds
     */
    targetLength?: number;

    /**
     * Video title (defaults to component name if not provided)
     */
    title?: string;

    /**
     * Create vertical video format (9:16)
     */
    verticalVideo?: boolean;

    /**
     * Enable web search for additional content
     */
    webSearch?: boolean;
  }

  export interface UploadsConfigDto {
    /**
     * Folder ID where uploads will be stored
     */
    folderId: string;

    /**
     * Folder IDs
     */
    folders?: Array<string>;

    /**
     * Material IDs
     */
    materials?: Array<string>;
  }

  export interface TutorMeConfigDto {
    /**
     * Enable video
     */
    enableVideo?: boolean;

    /**
     * Enable voice
     */
    enableVoice?: boolean;

    /**
     * Folder IDs
     */
    folders?: Array<string>;

    /**
     * Material IDs
     */
    materials?: Array<string>;

    /**
     * Session duration in minutes
     */
    sessionDuration?: number;

    /**
     * Tutor personality
     */
    tutorPersonality?: string;
  }

  export interface ChatAnalyticsConfigDto {
    /**
     * ID of the chat component to analyze
     */
    chatComponentId: string;

    /**
     * Enable auto-refresh
     */
    autoRefresh?: boolean;

    /**
     * Default date range in days
     */
    dateRange?: number;

    /**
     * Enable CSV export functionality
     */
    enableExport?: boolean;

    /**
     * Refresh interval in minutes
     */
    refreshInterval?: number;

    /**
     * Show summary section
     */
    showSummary?: boolean;

    /**
     * Show top topics
     */
    showTopics?: boolean;

    /**
     * Show user statistics section
     */
    showUserStats?: boolean;
  }
}

export interface ComponentUpdateParams {
  /**
   * Component status
   */
  status?: 'draft' | 'active' | 'inactive' | 'processing' | 'error';
}

export interface ComponentListParams {
  /**
   * Filter by component type
   */
  type?:
    | 'chat'
    | 'data_analyst'
    | 'flashcards'
    | 'scenarios'
    | 'practice_test'
    | 'audio_recap'
    | 'tutor_me'
    | 'explainers'
    | 'uploads'
    | 'chat_analytics'
    | 'performance_insights';
}

export interface ComponentGenerateEmbedParams {
  /**
   * Token expiry time in hours
   */
  expiryHours?: number;

  /**
   * Feature toggles
   */
  features?: ComponentGenerateEmbedParams.Features;

  /**
   * Group IDs for collaboration
   */
  groupIds?: Array<string>;

  /**
   * Embed height (e.g., "400px", "100vh")
   */
  height?: string;

  /**
   * Session ID for continuity
   */
  sessionId?: string;

  /**
   * Student name for display and tracking
   */
  studentName?: string;

  /**
   * Theme customization
   */
  theme?: ComponentGenerateEmbedParams.Theme;

  /**
   * User ID for tracking
   */
  userId?: string;

  /**
   * Embed width (e.g., "100%", "600px")
   */
  width?: string;
}

export namespace ComponentGenerateEmbedParams {
  /**
   * Feature toggles
   */
  export interface Features {
    /**
     * Enable bad words filter
     */
    enableBadWordsFilter: boolean;

    /**
     * Custom HTML to show in empty state instead of default icon and text
     */
    emptyStateHtml?: string;

    /**
     * Enable component creation
     */
    enableComponentCreation?: boolean;

    /**
     * Enable thumbs up/down feedback with reason
     */
    enableFeedback?: boolean;

    /**
     * Enable follow-up questions
     */
    enableFollowUps?: boolean;

    /**
     * Enable guardrails
     */
    enableGuardrails?: boolean;

    /**
     * Enable history
     */
    enableHistory?: boolean;

    /**
     * Enable image sources
     */
    enableImageSources?: boolean;

    /**
     * Enable outline
     */
    enableOutline?: boolean;

    /**
     * Enable prompting quality score
     */
    enablePromptingScore?: boolean;

    /**
     * Enable reference mode - show references instead of source content
     */
    enableReferenceMode?: boolean;

    /**
     * Enable learning responsibility score
     */
    enableResponsibilityScore?: boolean;

    /**
     * Enable transcript
     */
    enableTranscript?: boolean;

    /**
     * Enable voice input
     */
    enableVoice?: boolean;

    /**
     * Enable web search
     */
    enableWebSearch?: boolean;

    /**
     * Enable web search sources
     */
    enableWebSearchSources?: boolean;

    /**
     * Hide the default empty state (icon and text)
     */
    hideEmptyState?: boolean;

    /**
     * Hide the chat title and avatar in the embedded component
     */
    hideTitle?: boolean;

    /**
     * Placeholder text
     */
    placeholderText?: string;
  }

  /**
   * Theme customization
   */
  export interface Theme {
    /**
     * Background color (hex)
     */
    backgroundColor?: string;

    /**
     * Border radius
     */
    borderRadius?: string;

    /**
     * Font family
     */
    fontFamily?: string;

    /**
     * Font size
     */
    fontSize?: string;

    /**
     * Hide branding
     */
    hideBranding?: boolean;

    /**
     * Logo URL
     */
    logoUrl?: string;

    /**
     * Padding
     */
    padding?: string;

    /**
     * Primary color (hex)
     */
    primaryColor?: string;

    /**
     * Secondary color (hex)
     */
    secondaryColor?: string;

    /**
     * Text color (hex)
     */
    textColor?: string;
  }
}

export declare namespace Components {
  export {
    type ComponentResponse as ComponentResponse,
    type ComponentListResponse as ComponentListResponse,
    type ComponentGenerateEmbedResponse as ComponentGenerateEmbedResponse,
    type ComponentCreateParams as ComponentCreateParams,
    type ComponentUpdateParams as ComponentUpdateParams,
    type ComponentListParams as ComponentListParams,
    type ComponentGenerateEmbedParams as ComponentGenerateEmbedParams,
  };
}