// 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';

/**
 * (Labs) Tool router endpoints
 */
export class Files extends APIResource {
  /**
   * Lists files in a workbench session storage mount with cursor-based pagination.
   * Use the download_url endpoint with the returned mount_relative_path to get a
   * presigned download URL.
   *
   * @example
   * ```ts
   * const files = await client.toolRouter.session.files.list(
   *   'files',
   *   { session_id: 'trs_1a2b3c4d5e6f' },
   * );
   * ```
   */
  list(mountID: string, params: FileListParams, options?: RequestOptions): APIPromise<FileListResponse> {
    const { session_id, ...query } = params;
    return this._client.get(path`/api/v3.1/tool_router/session/${session_id}/mounts/${mountID}/items`, {
      query,
      ...options,
    });
  }

  /**
   * Deletes a file from a workbench session storage mount. S3 delete is idempotent —
   * deleting a non-existent file succeeds silently.
   *
   * @example
   * ```ts
   * const file = await client.toolRouter.session.files.delete(
   *   'files',
   *   {
   *     session_id: 'trs_1a2b3c4d5e6f',
   *     mount_relative_path: 'report.pdf',
   *   },
   * );
   * ```
   */
  delete(
    mountID: string,
    params: FileDeleteParams,
    options?: RequestOptions,
  ): APIPromise<FileDeleteResponse> {
    const { session_id, ...body } = params;
    return this._client.post(path`/api/v3.1/tool_router/session/${session_id}/mounts/${mountID}/delete`, {
      body,
      ...options,
    });
  }

  /**
   * Generates a presigned download URL for a file in a workbench session mount.
   * Accepts a relative path within the mount.
   *
   * @example
   * ```ts
   * const response =
   *   await client.toolRouter.session.files.createDownloadURL(
   *     'files',
   *     {
   *       session_id: 'trs_1a2b3c4d5e6f',
   *       mount_relative_path: 'report.pdf',
   *     },
   *   );
   * ```
   */
  createDownloadURL(
    mountID: string,
    params: FileCreateDownloadURLParams,
    options?: RequestOptions,
  ): APIPromise<FileCreateDownloadURLResponse> {
    const { session_id, ...body } = params;
    return this._client.post(
      path`/api/v3.1/tool_router/session/${session_id}/mounts/${mountID}/download_url`,
      { body, ...options },
    );
  }

  /**
   * Generates a presigned upload URL for uploading a file to a workbench session
   * mount. The caller should PUT the file content directly to the returned URL.
   *
   * @example
   * ```ts
   * const response =
   *   await client.toolRouter.session.files.createUploadURL(
   *     'files',
   *     {
   *       session_id: 'trs_1a2b3c4d5e6f',
   *       mount_relative_path: 'report.pdf',
   *     },
   *   );
   * ```
   */
  createUploadURL(
    mountID: string,
    params: FileCreateUploadURLParams,
    options?: RequestOptions,
  ): APIPromise<FileCreateUploadURLResponse> {
    const { session_id, ...body } = params;
    return this._client.post(path`/api/v3.1/tool_router/session/${session_id}/mounts/${mountID}/upload_url`, {
      body,
      ...options,
    });
  }
}

export interface FileListResponse {
  /**
   * List of files in the mount
   */
  items: Array<FileListResponse.Item>;

  /**
   * Cursor for the next page of results. If absent, there are no more pages.
   */
  next_cursor?: string;
}

export namespace FileListResponse {
  export interface Item {
    /**
     * ISO 8601 timestamp of last modification
     */
    last_modified: string;

    /**
     * Relative file path within the mount (e.g. "report.pdf")
     */
    mount_relative_path: string;

    /**
     * Absolute mount path inside the sandbox (e.g. /mnt/files)
     */
    sandbox_mount_prefix: string;

    /**
     * File size in bytes
     */
    size: number;
  }
}

export interface FileDeleteResponse {
  /**
   * Relative file path that was deleted
   */
  mount_relative_path: string;

  /**
   * Absolute mount path inside the sandbox (e.g. /mnt/files)
   */
  sandbox_mount_prefix: string;
}

export interface FileCreateDownloadURLResponse {
  /**
   * Presigned download URL for the file
   */
  download_url: string;

  /**
   * ISO 8601 timestamp when the download URL expires
   */
  expires_at: string;

  /**
   * Relative file path within the mount (e.g. "report.pdf")
   */
  mount_relative_path: string;

  /**
   * Absolute mount path inside the sandbox (e.g. /mnt/files)
   */
  sandbox_mount_prefix: string;
}

export interface FileCreateUploadURLResponse {
  /**
   * ISO 8601 timestamp when the upload URL expires
   */
  expires_at: string;

  /**
   * Relative file path within the mount (e.g. "report.pdf")
   */
  mount_relative_path: string;

  /**
   * Absolute mount path inside the sandbox (e.g. /mnt/files)
   */
  sandbox_mount_prefix: string;

  /**
   * Presigned upload URL — PUT the file content here
   */
  upload_url: string;
}

export interface FileListParams {
  /**
   * Path param: The unique identifier of the tool router session
   */
  session_id: string;

  /**
   * Query param: Pagination cursor from the previous response next_cursor field
   */
  cursor?: string;

  /**
   * Query param: Maximum number of files to return per page (1-500)
   */
  limit?: number;

  /**
   * Query param: Relative path prefix within the mount for filtering
   */
  mount_relative_prefix?: string;
}

export interface FileDeleteParams {
  /**
   * Path param: The unique identifier of the tool router session
   */
  session_id: string;

  /**
   * Body param: Relative file path within the mount
   */
  mount_relative_path: string;
}

export interface FileCreateDownloadURLParams {
  /**
   * Path param: The unique identifier of the tool router session
   */
  session_id: string;

  /**
   * Body param: Relative file path within the mount
   */
  mount_relative_path: string;
}

export interface FileCreateUploadURLParams {
  /**
   * Path param: The unique identifier of the tool router session
   */
  session_id: string;

  /**
   * Body param: Supports subdirectories (e.g. "data/output.csv",
   * "images/charts/chart.png")
   */
  mount_relative_path: string;

  /**
   * Body param: MIME type of the file being uploaded
   */
  mimetype?: string;
}

export declare namespace Files {
  export {
    type FileListResponse as FileListResponse,
    type FileDeleteResponse as FileDeleteResponse,
    type FileCreateDownloadURLResponse as FileCreateDownloadURLResponse,
    type FileCreateUploadURLResponse as FileCreateUploadURLResponse,
    type FileListParams as FileListParams,
    type FileDeleteParams as FileDeleteParams,
    type FileCreateDownloadURLParams as FileCreateDownloadURLParams,
    type FileCreateUploadURLParams as FileCreateUploadURLParams,
  };
}