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

import { APIResource } from '../../../core/resource';
import * as BulkAPI from './bulk';
import { Bulk, BulkMoveParams, BulkMoveResponse } from './bulk';
import * as UploadAPI from './upload';
import {
  Upload,
  UploadCompleteUploadParams,
  UploadGetPresignedURLParams,
  UploadGetPresignedURLResponse,
  UploadUploadFileAndProcessParams,
  UploadUploadFileParams,
  UploadUploadFromURLAndProcessParams,
  UploadUploadFromURLParams,
} from './upload';
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 Materials extends APIResource {
  upload: UploadAPI.Upload = new UploadAPI.Upload(this._client);
  bulk: BulkAPI.Bulk = new BulkAPI.Bulk(this._client);

  /**
   * Create a new material
   *
   * @example
   * ```ts
   * const materialResponse = await client.v1.materials.create({
   *   content: { type: 'text' },
   *   name: 'Chapter 1 - Introduction',
   * });
   * ```
   */
  create(body: MaterialCreateParams, options?: RequestOptions): APIPromise<MaterialResponse> {
    return this._client.post('/api/v1/materials', { body, ...options });
  }

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

  /**
   * Update a material
   *
   * @example
   * ```ts
   * const materialResponse = await client.v1.materials.update(
   *   'id',
   * );
   * ```
   */
  update(id: string, body: MaterialUpdateParams, options?: RequestOptions): APIPromise<MaterialResponse> {
    return this._client.patch(path`/api/v1/materials/${id}`, { body, ...options });
  }

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

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

  /**
   * Attempts to cancel a currently running PDF processing job
   *
   * @example
   * ```ts
   * const response = await client.v1.materials.cancelJob('id');
   * ```
   */
  cancelJob(id: string, options?: RequestOptions): APIPromise<MaterialCancelJobResponse> {
    return this._client.post(path`/api/v1/materials/${id}/cancel-job`, options);
  }

  /**
   * Creates a material and waits for processing to finish before returning. Useful
   * for synchronous API usage.
   *
   * @example
   * ```ts
   * const materialResponse =
   *   await client.v1.materials.createAndProcess({
   *     content: { type: 'text' },
   *     name: 'Chapter 1 - Introduction',
   *   });
   * ```
   */
  createAndProcess(
    body: MaterialCreateAndProcessParams,
    options?: RequestOptions,
  ): APIPromise<MaterialResponse> {
    return this._client.post('/api/v1/materials/upload-and-process', { body, ...options });
  }

  /**
   * Create batch upload URLs for multiple materials
   *
   * @example
   * ```ts
   * const response =
   *   await client.v1.materials.createBatchUploadURLs({
   *     materials: [
   *       {
   *         contentType: 'application/pdf',
   *         filename: 'document.pdf',
   *         name: 'Chapter 1',
   *       },
   *     ],
   *   });
   * ```
   */
  createBatchUploadURLs(
    body: MaterialCreateBatchUploadURLsParams,
    options?: RequestOptions,
  ): APIPromise<MaterialCreateBatchUploadURLsResponse> {
    return this._client.post('/api/v1/materials/batch', { body, ...options });
  }

  /**
   * Uses AI to generate study materials like outlines, notes, summaries, etc. from a
   * given topic. Returns immediately without waiting for processing.
   *
   * @example
   * ```ts
   * const generatedMaterialResponse =
   *   await client.v1.materials.generate({
   *     name: 'Photosynthesis Study Plan',
   *     topic: 'Photosynthesis in plants',
   *     type: 'notes',
   *   });
   * ```
   */
  generate(body: MaterialGenerateParams, options?: RequestOptions): APIPromise<GeneratedMaterialResponse> {
    return this._client.post('/api/v1/materials/generate', { body, ...options });
  }

  /**
   * Uses AI to generate study materials like outlines, notes, summaries, etc. from a
   * given topic and waits for processing to complete
   *
   * @example
   * ```ts
   * const generatedMaterialResponse =
   *   await client.v1.materials.generateAndProcess({
   *     name: 'Photosynthesis Study Plan',
   *     topic: 'Photosynthesis in plants',
   *     type: 'notes',
   *   });
   * ```
   */
  generateAndProcess(
    body: MaterialGenerateAndProcessParams,
    options?: RequestOptions,
  ): APIPromise<GeneratedMaterialResponse> {
    return this._client.post('/api/v1/materials/generate-and-process', { body, ...options });
  }

  /**
   * Get debug information for a material including extracted content
   *
   * @example
   * ```ts
   * const response = await client.v1.materials.getDebugInfo(
   *   'id',
   * );
   * ```
   */
  getDebugInfo(id: string, options?: RequestOptions): APIPromise<MaterialGetDebugInfoResponse> {
    return this._client.get(path`/api/v1/materials/${id}/debug`, options);
  }

  /**
   * Get temporary download URL for material
   *
   * @example
   * ```ts
   * const response = await client.v1.materials.getDownloadURL(
   *   'id',
   * );
   * ```
   */
  getDownloadURL(
    id: string,
    query: MaterialGetDownloadURLParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<MaterialGetDownloadURLResponse> {
    return this._client.get(path`/api/v1/materials/${id}/download-url`, { query, ...options });
  }

  /**
   * Returns the current status of a PDF processing job including progress
   * information
   *
   * @example
   * ```ts
   * const response = await client.v1.materials.getJobStatus(
   *   'id',
   * );
   * ```
   */
  getJobStatus(id: string, options?: RequestOptions): APIPromise<MaterialGetJobStatusResponse> {
    return this._client.get(path`/api/v1/materials/${id}/job-status`, options);
  }

  /**
   * Move material to a different folder
   *
   * @example
   * ```ts
   * const materialResponse = await client.v1.materials.move(
   *   'id',
   *   { folderId: 'folderId' },
   * );
   * ```
   */
  move(id: string, body: MaterialMoveParams, options?: RequestOptions): APIPromise<MaterialResponse> {
    return this._client.post(path`/api/v1/materials/${id}/move`, { body, ...options });
  }

  /**
   * Rename a material
   *
   * @example
   * ```ts
   * const materialResponse = await client.v1.materials.rename(
   *   'id',
   *   { name: 'New Material Name' },
   * );
   * ```
   */
  rename(id: string, body: MaterialRenameParams, options?: RequestOptions): APIPromise<MaterialResponse> {
    return this._client.post(path`/api/v1/materials/${id}/rename`, { body, ...options });
  }

  /**
   * Reprocess material to regenerate embeddings and extract content
   *
   * @example
   * ```ts
   * const materialResponse =
   *   await client.v1.materials.reprocess('id');
   * ```
   */
  reprocess(id: string, options?: RequestOptions): APIPromise<MaterialResponse> {
    return this._client.post(path`/api/v1/materials/${id}/reprocess`, options);
  }

  /**
   * Search materials using RAG (Retrieval-Augmented Generation)
   *
   * @example
   * ```ts
   * const response = await client.v1.materials.search({
   *   query: 'What is photosynthesis?',
   * });
   * ```
   */
  search(body: MaterialSearchParams, options?: RequestOptions): APIPromise<MaterialSearchResponse> {
    return this._client.post('/api/v1/materials/search', { body, ...options });
  }
}

export interface Content {
  /**
   * Type of content
   */
  type: 'text' | 'pdf' | 'video' | 'audio' | 'url';

  /**
   * URL to fetch content from
   */
  sourceUrl?: string;

  /**
   * Text content (for text type)
   */
  text?: string;

  /**
   * URL to the content (for url type)
   */
  url?: string;
}

export interface GeneratedMaterialResponse {
  /**
   * Material ID
   */
  _id: string;

  /**
   * Material content
   */
  content: GeneratedMaterialResponse.Content;

  /**
   * Content type
   */
  contentType: 'text' | 'pdf' | 'video' | 'audio' | 'image' | 'epub';

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

  /**
   * Folder ID
   */
  folderId: string | null;

  /**
   * Material name
   */
  name: string;

  /**
   * Organization ID
   */
  organizationId: string;

  /**
   * Material status
   */
  status: 'active' | 'processing' | 'pending_upload' | 'error' | 'deleted';

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

  /**
   * Generation metadata
   */
  generationMetadata?: unknown;

  /**
   * Material metadata
   */
  metadata?: unknown;

  /**
   * References that this material cites
   */
  references?: Array<Reference>;

  /**
   * Usage information
   */
  usage?: unknown;
}

export namespace GeneratedMaterialResponse {
  /**
   * Material content
   */
  export interface Content {
    filename?: string;

    fileSize?: number;

    mimeType?: string;

    s3Key?: string;

    s3Url?: string;

    text?: string;

    url?: string;
  }
}

export interface MaterialResponse {
  /**
   * Material ID
   */
  _id: string;

  /**
   * Material content
   */
  content: MaterialResponse.Content;

  /**
   * Content type
   */
  contentType: 'text' | 'pdf' | 'video' | 'audio' | 'image' | 'epub';

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

  /**
   * Folder ID
   */
  folderId: string | null;

  /**
   * Material name
   */
  name: string;

  /**
   * Organization ID
   */
  organizationId: string;

  /**
   * Material status
   */
  status: 'active' | 'processing' | 'pending_upload' | 'error' | 'deleted';

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

  /**
   * Material metadata
   */
  metadata?: unknown;

  /**
   * References that this material cites
   */
  references?: Array<Reference>;

  /**
   * Usage information
   */
  usage?: unknown;
}

export namespace MaterialResponse {
  /**
   * Material content
   */
  export interface Content {
    filename?: string;

    fileSize?: number;

    mimeType?: string;

    s3Key?: string;

    s3Url?: string;

    text?: string;

    url?: string;
  }
}

export interface Reference {
  /**
   * Reference title
   */
  title: string;

  /**
   * Reference URL
   */
  url?: string;
}

export interface MaterialListResponse {
  materials?: Array<MaterialResponse>;

  page?: number;

  totalCount?: number;

  totalPages?: number;
}

export interface MaterialCancelJobResponse {
  message?: string;

  success?: boolean;
}

export type MaterialCreateBatchUploadURLsResponse =
  Array<MaterialCreateBatchUploadURLsResponse.MaterialCreateBatchUploadURLsResponseItem>;

export namespace MaterialCreateBatchUploadURLsResponse {
  export interface MaterialCreateBatchUploadURLsResponseItem {
    /**
     * Material ID
     */
    materialId: string;

    /**
     * Material name
     */
    name: string;

    /**
     * S3 key
     */
    s3Key: string;

    /**
     * Presigned upload URL
     */
    uploadUrl: string;
  }
}

export interface MaterialGetDebugInfoResponse {
  /**
   * Content details
   */
  content: unknown;

  /**
   * Content type
   */
  contentType: string;

  /**
   * Processed images
   */
  images: Array<MaterialGetDebugInfoResponse.Image>;

  /**
   * Material ID
   */
  materialId: string;

  /**
   * Material metadata
   */
  metadata: unknown;

  /**
   * Material name
   */
  name: string;

  /**
   * Processing status
   */
  status: string;

  /**
   * Transcript structure for videos
   */
  transcriptStructure: unknown | null;
}

export namespace MaterialGetDebugInfoResponse {
  export interface Image {
    id?: string;

    description?: string;

    pageIndex?: number;

    s3Key?: string;

    s3Url?: string;
  }
}

export interface MaterialGetDownloadURLResponse {
  /**
   * Temporary download URL
   */
  downloadUrl: string;
}

export interface MaterialGetJobStatusResponse {
  /**
   * Job completion time
   */
  completedAt?: string;

  /**
   * Error message if job failed
   */
  error?: string;

  /**
   * Unique job identifier
   */
  jobId?: string;

  progress?: MaterialGetJobStatusResponse.Progress;

  resultSummary?: MaterialGetJobStatusResponse.ResultSummary;

  /**
   * Job start time
   */
  startedAt?: string;

  /**
   * Current job status
   */
  status?: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
}

export namespace MaterialGetJobStatusResponse {
  export interface Progress {
    /**
     * Current batch being processed
     */
    currentBatch?: number;

    /**
     * Completion percentage (0-100)
     */
    percentage?: number;

    /**
     * Images processed so far
     */
    processedImages?: number;

    /**
     * Total number of batches
     */
    totalBatches?: number;

    /**
     * Total images to process
     */
    totalImages?: number;
  }

  export interface ResultSummary {
    /**
     * Number of images processed
     */
    imagesProcessed?: number;

    /**
     * Total processing time in milliseconds
     */
    processingTimeMs?: number;

    /**
     * Whether text was extracted
     */
    textExtracted?: boolean;

    /**
     * Length of extracted text
     */
    textLength?: number;
  }
}

export interface MaterialSearchResponse {
  /**
   * Whether results were filtered by scope
   */
  filtered: boolean;

  /**
   * Original search query
   */
  query: string;

  /**
   * Search results
   */
  results: Array<MaterialSearchResponse.Result>;

  /**
   * Search scope
   */
  scope: MaterialSearchResponse.Scope;

  /**
   * Total number of results
   */
  totalResults: number;
}

export namespace MaterialSearchResponse {
  export interface Result {
    /**
     * Chunk index within the material
     */
    chunkIndex: number;

    /**
     * Material information
     */
    material: Result.Material | null;

    /**
     * Relevance score (0-1)
     */
    score: number;

    /**
     * Matched text chunk
     */
    text: string;
  }

  export namespace Result {
    /**
     * Material information
     */
    export interface Material {
      id?: string;

      contentType?: string;

      name?: string;
    }
  }

  /**
   * Search scope
   */
  export interface Scope {
    folderIds?: Array<string>;

    materialIds?: Array<string>;
  }
}

export interface MaterialCreateParams {
  /**
   * Content details
   */
  content: Content;

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

  /**
   * Folder ID to place the material in
   */
  folderId?: string;

  /**
   * References that this material cites
   */
  references?: Array<Reference>;
}

export interface MaterialUpdateParams {
  /**
   * Array of references to update (optional)
   */
  references?: Array<MaterialUpdateParams.Reference>;
}

export namespace MaterialUpdateParams {
  export interface Reference {
    /**
     * Reference title
     */
    title: string;

    /**
     * Reference URL (optional)
     */
    url?: string;
  }
}

export interface MaterialListParams {
  /**
   * Filter by folder ID
   */
  folderId?: string;

  /**
   * Number of items per page (default: 20, max: 200)
   */
  limit?: string;

  /**
   * Page number (default: 1)
   */
  page?: string;

  /**
   * Search materials by name
   */
  search?: string;
}

export interface MaterialCreateAndProcessParams {
  /**
   * Content details
   */
  content: Content;

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

  /**
   * Folder ID to place the material in
   */
  folderId?: string;

  /**
   * Polling interval in milliseconds (default: 2 seconds)
   */
  pollIntervalMs?: number;

  /**
   * References that this material cites
   */
  references?: Array<Reference>;

  /**
   * Maximum time to wait for processing in milliseconds (default: 5 minutes)
   */
  timeoutMs?: number;
}

export interface MaterialCreateBatchUploadURLsParams {
  /**
   * Array of materials to create
   */
  materials: Array<MaterialCreateBatchUploadURLsParams.Material>;
}

export namespace MaterialCreateBatchUploadURLsParams {
  export interface Material {
    /**
     * MIME type
     */
    contentType: string;

    /**
     * Filename
     */
    filename: string;

    /**
     * Material name
     */
    name: string;

    /**
     * Folder ID
     */
    folderId?: string;
  }
}

export interface MaterialGenerateParams {
  /**
   * Name for the generated material
   */
  name: string;

  /**
   * Topic or context to generate material from
   */
  topic: string;

  /**
   * Type of material to generate
   */
  type: 'outline' | 'overview' | 'notes' | 'summary';

  /**
   * Additional context or details about the topic
   */
  context?: string;

  /**
   * Target folder ID
   */
  folderId?: string;

  /**
   * Length of the generated content
   */
  length?: 'short' | 'medium' | 'long';

  /**
   * Target education level
   */
  level?: 'high_school' | 'college' | 'professional';

  /**
   * References that this material cites
   */
  references?: Array<Reference>;
}

export interface MaterialGenerateAndProcessParams {
  /**
   * Name for the generated material
   */
  name: string;

  /**
   * Topic or context to generate material from
   */
  topic: string;

  /**
   * Type of material to generate
   */
  type: 'outline' | 'overview' | 'notes' | 'summary';

  /**
   * Additional context or details about the topic
   */
  context?: string;

  /**
   * Target folder ID
   */
  folderId?: string;

  /**
   * Length of the generated content
   */
  length?: 'short' | 'medium' | 'long';

  /**
   * Target education level
   */
  level?: 'high_school' | 'college' | 'professional';

  /**
   * Polling interval in milliseconds (default: 2 seconds)
   */
  pollIntervalMs?: number;

  /**
   * References that this material cites
   */
  references?: Array<Reference>;

  /**
   * Maximum time to wait for processing in milliseconds (default: 5 minutes)
   */
  timeoutMs?: number;
}

export interface MaterialGetDownloadURLParams {
  /**
   * URL expiration time in seconds (default: 3600)
   */
  expiresIn?: number;
}

export interface MaterialMoveParams {
  /**
   * Target folder ID (null for root)
   */
  folderId: string | null;
}

export interface MaterialRenameParams {
  /**
   * New name for the material
   */
  name: string;
}

export interface MaterialSearchParams {
  /**
   * Search query
   */
  query: string;

  /**
   * Limit search to materials within specific folders (includes subfolders)
   */
  folderIds?: Array<string>;

  /**
   * Limit search to specific material IDs
   */
  materialIds?: Array<string>;

  /**
   * Number of results to return
   */
  topK?: number;
}

Materials.Upload = Upload;
Materials.Bulk = Bulk;

export declare namespace Materials {
  export {
    type Content as Content,
    type GeneratedMaterialResponse as GeneratedMaterialResponse,
    type MaterialResponse as MaterialResponse,
    type Reference as Reference,
    type MaterialListResponse as MaterialListResponse,
    type MaterialCancelJobResponse as MaterialCancelJobResponse,
    type MaterialCreateBatchUploadURLsResponse as MaterialCreateBatchUploadURLsResponse,
    type MaterialGetDebugInfoResponse as MaterialGetDebugInfoResponse,
    type MaterialGetDownloadURLResponse as MaterialGetDownloadURLResponse,
    type MaterialGetJobStatusResponse as MaterialGetJobStatusResponse,
    type MaterialSearchResponse as MaterialSearchResponse,
    type MaterialCreateParams as MaterialCreateParams,
    type MaterialUpdateParams as MaterialUpdateParams,
    type MaterialListParams as MaterialListParams,
    type MaterialCreateAndProcessParams as MaterialCreateAndProcessParams,
    type MaterialCreateBatchUploadURLsParams as MaterialCreateBatchUploadURLsParams,
    type MaterialGenerateParams as MaterialGenerateParams,
    type MaterialGenerateAndProcessParams as MaterialGenerateAndProcessParams,
    type MaterialGetDownloadURLParams as MaterialGetDownloadURLParams,
    type MaterialMoveParams as MaterialMoveParams,
    type MaterialRenameParams as MaterialRenameParams,
    type MaterialSearchParams as MaterialSearchParams,
  };

  export {
    Upload as Upload,
    type UploadGetPresignedURLResponse as UploadGetPresignedURLResponse,
    type UploadCompleteUploadParams as UploadCompleteUploadParams,
    type UploadGetPresignedURLParams as UploadGetPresignedURLParams,
    type UploadUploadFileParams as UploadUploadFileParams,
    type UploadUploadFileAndProcessParams as UploadUploadFileAndProcessParams,
    type UploadUploadFromURLParams as UploadUploadFromURLParams,
    type UploadUploadFromURLAndProcessParams as UploadUploadFromURLAndProcessParams,
  };

  export { Bulk as Bulk, type BulkMoveResponse as BulkMoveResponse, type BulkMoveParams as BulkMoveParams };
}