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

export class AudioRecaps extends APIResource {
  /**
   * List audio-recap section feedback for the authenticated organization.
   *
   * @example
   * ```ts
   * const response = await client.v1.audioRecaps.listFeedback({
   *   componentId: 'audio_recap_abc123',
   *   feedbackType: 'thumbsDown',
   * });
   * ```
   */
  listFeedback(
    query: AudioRecapListFeedbackParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<AudioRecapListFeedbackResponse> {
    return this._client.get('/api/v1/audio-recaps/feedback', { query, ...options });
  }

  /**
   * Retrieve the rated section and surrounding section context for a feedback row.
   *
   * @example
   * ```ts
   * const context = await client.v1.audioRecaps.retrieveFeedbackContext('feedback_id');
   * ```
   */
  retrieveFeedbackContext(
    feedbackID: string,
    options?: RequestOptions,
  ): APIPromise<AudioRecapFeedbackContextResponse> {
    return this._client.get(path`/api/v1/audio-recaps/feedback/${feedbackID}/context`, options);
  }

  /**
   * List per-user playback progress for an audio-recap component.
   *
   * @example
   * ```ts
   * const response = await client.v1.audioRecaps.listProgress('audio_recap_abc123', {
   *   groupId: 'class-101',
   * });
   * ```
   */
  listProgress(
    componentID: string,
    query: AudioRecapListProgressParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<AudioRecapListProgressResponse> {
    return this._client.get(path`/api/v1/audio-recaps/progress/${componentID}`, { query, ...options });
  }

  /**
   * Retrieve per-section playback progress for a single user on an audio recap.
   *
   * @example
   * ```ts
   * const response = await client.v1.audioRecaps.retrieveUserProgress(
   *   'audio_recap_abc123',
   *   'student-001',
   * );
   * ```
   */
  retrieveUserProgress(
    componentID: string,
    userID: string,
    options?: RequestOptions,
  ): APIPromise<AudioRecapUserProgressResponse> {
    return this._client.get(path`/api/v1/audio-recaps/progress/${componentID}/users/${userID}`, options);
  }
}

export interface AudioRecapFeedbackItem {
  _id: string;

  componentId: string;

  feedback: 'thumbsUp' | 'thumbsDown';

  reason: string;

  sectionId: string;

  timestamp: string;

  userId: string;

  componentName?: string;

  groupIds?: Array<string>;

  recapId?: string;

  recapTitle?: string;

  sectionOrder?: number;
}

export interface AudioRecapListFeedbackResponse {
  feedback: Array<AudioRecapFeedbackItem>;

  groups: Array<string>;

  stats: AudioRecapListFeedbackResponse.Stats;

  total: number;
}

export namespace AudioRecapListFeedbackResponse {
  export interface Stats {
    thumbsDown: number;

    thumbsUp: number;

    withReason: number;
  }
}

export interface AudioRecapFeedbackContextResponse {
  feedback: AudioRecapFeedbackContextResponse.Feedback;

  section: AudioRecapFeedbackContextResponse.Section | null;

  sections: Array<AudioRecapFeedbackContextResponse.SectionSummary>;
}

export namespace AudioRecapFeedbackContextResponse {
  export interface Feedback {
    _id: string;

    componentId: string;

    feedback: 'thumbsUp' | 'thumbsDown';

    reason: string;

    recapId: string;

    sectionId: string;

    timestamp: string;

    userId: string;

    componentName?: string;

    groupIds?: Array<string>;

    recapTitle?: string;

    sectionOrder?: number;
  }

  export interface Section {
    id: string;

    citations: Array<unknown>;

    order: number;

    script: string;

    audioUrl?: string;

    isUserQuestion?: boolean;

    userQuestion?: string;
  }

  export interface SectionSummary {
    id: string;

    order: number;

    scriptPreview: string;

    audioUrl?: string;

    generated?: boolean;

    isUserQuestion?: boolean;

    userQuestion?: string;
  }
}

export interface AudioRecapListProgressResponse {
  totalSections: number;

  totalUsers: number;

  users: Array<AudioRecapListProgressResponse.User>;
}

export namespace AudioRecapListProgressResponse {
  export interface User {
    completionPct: number;

    groupIds: Array<string>;

    lastActivityAt: string;

    sectionsCompleted: number;

    userId: string;

    currentSection?: User.CurrentSection;
  }

  export namespace User {
    export interface CurrentSection {
      lastPosition: number;

      order: number;
    }
  }
}

export interface AudioRecapUserProgressResponse {
  sections: Array<AudioRecapUserProgressResponse.Section>;

  user: AudioRecapUserProgressResponse.User;
}

export namespace AudioRecapUserProgressResponse {
  export interface Section {
    completed: boolean;

    lastPosition: number;

    order: number;

    scriptPreview: string;

    sectionId: string;

    completedAt?: string;

    isUserQuestion?: boolean;

    updatedAt?: string;
  }

  export interface User {
    completionPct: number;

    groupIds: Array<string>;

    sectionsCompleted: number;

    totalSections: number;

    userId: string;
  }
}

export interface AudioRecapListFeedbackParams {
  /**
   * Filter by component ID.
   */
  componentId?: string;

  /**
   * End date for filtering (ISO 8601).
   */
  endDate?: string;

  /**
   * Filter by feedback type.
   */
  feedbackType?: 'thumbsUp' | 'thumbsDown';

  /**
   * Filter by group ID.
   */
  groupId?: string;

  /**
   * Number of records to return.
   */
  limit?: number;

  /**
   * Filter by audio recap ID.
   */
  recapId?: string;

  /**
   * Number of records to skip.
   */
  skip?: number;

  /**
   * Start date for filtering (ISO 8601).
   */
  startDate?: string;

  /**
   * Filter by user ID.
   */
  userId?: string;
}

export interface AudioRecapListProgressParams {
  /**
   * Filter by group ID.
   */
  groupId?: string;

  /**
   * Number of users to return.
   */
  limit?: number;

  /**
   * Number of users to skip.
   */
  skip?: number;

  /**
   * Filter by user ID.
   */
  userId?: string;
}

export declare namespace AudioRecaps {
  export {
    type AudioRecapFeedbackItem as AudioRecapFeedbackItem,
    type AudioRecapListFeedbackResponse as AudioRecapListFeedbackResponse,
    type AudioRecapFeedbackContextResponse as AudioRecapFeedbackContextResponse,
    type AudioRecapListProgressResponse as AudioRecapListProgressResponse,
    type AudioRecapUserProgressResponse as AudioRecapUserProgressResponse,
    type AudioRecapListFeedbackParams as AudioRecapListFeedbackParams,
    type AudioRecapListProgressParams as AudioRecapListProgressParams,
  };
}