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

import { APIResource } from '../../core/resource';
import * as FilesAPI from './files';
import * as Shared from '../shared';
import * as CompletionsAPI from '../chat/completions';
import * as ContentAPI from './content';
import { Content, ContentRetrieveParams, ContentRetrieveResponse } from './content';
import { APIPromise } from '../../core/api-promise';
import { CursorPage, type CursorPageParams, PagePromise } from '../../core/pagination';
import { type Uploadable } from '../../core/uploads';
import { buildHeaders } from '../../internal/headers';
import { RequestOptions } from '../../internal/request-options';
import { multipartFormRequestOptions } from '../../internal/uploads';
import { path } from '../../internal/utils/path';

export class Files extends APIResource {
  content: ContentAPI.Content = new ContentAPI.Content(this._client);

  /**
   * Upload a file's bytes directly and create a file record.
   *
   * Send the file as multipart/form-data in the `file` field; the request body
   * carries the raw bytes, unlike cloud_imports which only references blobs that
   * already exist in cloud storage. The upload is rejected if it exceeds 25 MB;
   * larger or direct-to-storage uploads use a separate upload flow. The server
   * detects the content type from the bytes and rejects content that fails the
   * structural validation for that type. Content is deduplicated by checksum and
   * MIME type, so uploading bytes identical to an existing file reuses the
   * already-stored object instead of storing a second copy. Returns the created
   * file's metadata.
   */
  create(params: FileCreateParams, options?: RequestOptions): APIPromise<SGPFile> {
    const { 'x-project-id': xProjectID, ...body } = params;
    return this._client.post(
      '/v5/files',
      multipartFormRequestOptions(
        {
          body,
          ...options,
          headers: buildHeaders([
            { ...(xProjectID != null ? { 'x-project-id': xProjectID } : undefined) },
            options?.headers,
          ]),
        },
        this._client,
      ),
    );
  }

  /**
   * Retrieve a single file's metadata by id.
   *
   * Returns the file record (id, filename, MIME type, size, tags, and related
   * fields) but not the file's bytes; use the content endpoint to download the
   * bytes.
   */
  retrieve(
    fileID: string,
    params: FileRetrieveParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<SGPFile> {
    const { 'x-project-id': xProjectID } = params ?? {};
    return this._client.get(path`/v5/files/${fileID}`, {
      ...options,
      headers: buildHeaders([
        { ...(xProjectID != null ? { 'x-project-id': xProjectID } : undefined) },
        options?.headers,
      ]),
    });
  }

  /**
   * Update a file's mutable metadata by id.
   *
   * Only the file's `tags` can be modified; filename, content, size, and other
   * attributes are immutable through this endpoint. The supplied tags replace the
   * file's existing tags. Returns the updated file metadata.
   */
  update(fileID: string, params: FileUpdateParams, options?: RequestOptions): APIPromise<SGPFile> {
    const { 'x-project-id': xProjectID, ...body } = params;
    return this._client.patch(path`/v5/files/${fileID}`, {
      body,
      ...options,
      headers: buildHeaders([
        { ...(xProjectID != null ? { 'x-project-id': xProjectID } : undefined) },
        options?.headers,
      ]),
    });
  }

  /**
   * List the account's files with pagination.
   *
   * Optionally filter by `filename` (case-insensitive partial match). Results are
   * scoped to the files the caller is authorized to read. Files marked hidden
   * (internal or service-owned artifacts) are excluded from this listing but remain
   * retrievable by id. Returns file metadata only, not content.
   */
  list(
    params: FileListParams | null | undefined = {},
    options?: RequestOptions,
  ): PagePromise<SGPFilesCursorPage, SGPFile> {
    const { 'x-project-id': xProjectID, ...query } = params ?? {};
    return this._client.getAPIList('/v5/files', CursorPage<SGPFile>, {
      query,
      ...options,
      headers: buildHeaders([
        { ...(xProjectID != null ? { 'x-project-id': xProjectID } : undefined) },
        options?.headers,
      ]),
    });
  }

  /**
   * Delete a file by id, removing its database record.
   *
   * This is a hard delete: the file's row is removed from the database, not
   * soft-archived. The underlying stored object is deleted only when no other file
   * record still references the same stored content (identical checksum and MIME
   * type); when another record shares the blob, the blob is retained. If the id
   * refers to an incomplete multipart upload placeholder, its staged parts are
   * aborted instead. Returns a confirmation carrying the deleted file's id.
   */
  delete(
    fileID: string,
    params: FileDeleteParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<FileDeleteResponse> {
    const { 'x-project-id': xProjectID } = params ?? {};
    return this._client.delete(path`/v5/files/${fileID}`, {
      ...options,
      headers: buildHeaders([
        { ...(xProjectID != null ? { 'x-project-id': xProjectID } : undefined) },
        options?.headers,
      ]),
    });
  }

  /**
   * Register files that already exist in cloud blob storage as file records, in one
   * batch.
   *
   * Unlike upload, this transfers no bytes: each entry references an existing object
   * by its container/bucket, filepath, filename, and MIME type, and only a metadata
   * record pointing at that object is created. Files are imported independently and
   * the response reports a per-file status. The response is 200 when every import
   * succeeds and 207 when results are mixed, with each result marked SUCCESS or a
   * failure reason (file does not exist, invalid permissions, or unknown error).
   * Failed entries carry only the submitted filename and MIME type rather than a
   * full file record.
   */
  importFromCloud(
    params: FileImportFromCloudParams,
    options?: RequestOptions,
  ): APIPromise<FileImportFromCloudResponse> {
    const { 'x-project-id': xProjectID, ...body } = params;
    return this._client.post('/v5/files/cloud_imports', {
      body,
      ...options,
      headers: buildHeaders([
        { ...(xProjectID != null ? { 'x-project-id': xProjectID } : undefined) },
        options?.headers,
      ]),
    });
  }
}

export type SGPFilesCursorPage = CursorPage<SGPFile>;

export interface SGPFile {
  /**
   * The unique identifier of the entity.
   */
  id: string;

  /**
   * The date and time when the entity was created in ISO format.
   */
  created_at: string;

  /**
   * The identity that created the entity.
   */
  created_by: Shared.Identity;

  filename: string;

  md5_checksum: string;

  mime_type: string;

  size: number;

  duration_seconds?: number;

  object?: 'file';

  tags?: { [key: string]: unknown };
}

export interface FileDeleteResponse {
  id: string;

  deleted: boolean;

  object?: 'file';
}

export interface FileImportFromCloudResponse {
  /**
   * Results for each file import attempt
   */
  results: Array<FileImportFromCloudResponse.Result>;
}

export namespace FileImportFromCloudResponse {
  export interface Result {
    /**
     * The file object (full File for success, minimal \_FailedFile for failures)
     */
    file: FilesAPI.SGPFile | Result._FailedFile;

    /**
     * The status of the upload attempt
     */
    status: 'SUCCESS' | 'FAILED_FILE_DOES_NOT_EXIST' | 'FAILED_INVALID_PERMISSIONS' | 'FAILED_UNKNOWN_ERROR';
  }

  export namespace Result {
    /**
     * Minimal file representation for failed uploads containing only essential
     * information.
     */
    export interface _FailedFile {
      /**
       * The original filename from the request
       */
      filename: string;

      /**
       * The original MIME type from the request
       */
      mime_type: string;

      object?: 'failed_file';
    }
  }
}

export interface FileCreateParams {
  /**
   * Body param
   */
  file: Uploadable;

  /**
   * Header param
   */
  'x-project-id'?: string;
}

export interface FileRetrieveParams {
  'x-project-id'?: string;
}

export interface FileUpdateParams {
  /**
   * Body param
   */
  tags?: { [key: string]: unknown };

  /**
   * Header param
   */
  'x-project-id'?: string;
}

export interface FileListParams extends CursorPageParams {
  /**
   * Query param: Filter files by filename (case-insensitive partial match)
   */
  filename?: string;

  /**
   * Query param
   */
  sort_by?: string;

  /**
   * Query param
   */
  sort_order?: CompletionsAPI.SortOrder;

  /**
   * Header param
   */
  'x-project-id'?: string;
}

export interface FileDeleteParams {
  'x-project-id'?: string;
}

export interface FileImportFromCloudParams {
  /**
   * Body param: List of files to import from cloud storage
   */
  files: Array<FileImportFromCloudParams.File>;

  /**
   * Header param
   */
  'x-project-id'?: string;
}

export namespace FileImportFromCloudParams {
  export interface File {
    /**
     * The cloud storage container/bucket name
     */
    container: string;

    /**
     * The MIME type of the file
     */
    file_type: string;

    /**
     * The name of the file
     */
    filename: string;

    /**
     * The path to the file within the container
     */
    filepath: string;
  }
}

Files.Content = Content;

export declare namespace Files {
  export {
    type SGPFile as SGPFile,
    type FileDeleteResponse as FileDeleteResponse,
    type FileImportFromCloudResponse as FileImportFromCloudResponse,
    type SGPFilesCursorPage as SGPFilesCursorPage,
    type FileCreateParams as FileCreateParams,
    type FileRetrieveParams as FileRetrieveParams,
    type FileUpdateParams as FileUpdateParams,
    type FileListParams as FileListParams,
    type FileDeleteParams as FileDeleteParams,
    type FileImportFromCloudParams as FileImportFromCloudParams,
  };

  export {
    Content as Content,
    type ContentRetrieveResponse as ContentRetrieveResponse,
    type ContentRetrieveParams as ContentRetrieveParams,
  };
}