Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

14.9 KB
Raw Blame
import { telemetry } from '../telemetry/Telemetry';
import { Composio as ComposioClient } from '@composio/client';
import {
  FileDeleteResponse,
  FileDeleteResponseSchema,
  FileListResponse,
  FileListResponseSchema,
  RemoteFileDataSchema,
  ToolRouterSessionFilesMountDeleteOptions,
  ToolRouterSessionFilesMountDeleteOptionsSchema,
  ToolRouterSessionFilesMountDownloadOptions,
  ToolRouterSessionFilesMountDownloadOptionsSchema,
  ToolRouterSessionFilesMountListOptions,
  ToolRouterSessionFilesMountListOptionsSchema,
  ToolRouterSessionFilesMountUploadOptions,
  ToolRouterSessionFilesMountUploadOptionsSchema,
} from '../types/ToolRouterSessionFilesMount.types';
import { RemoteFile } from './RemoteFile';
import { ValidationError } from '../errors';
import { platform } from '#platform';
import { ssrfSafeFetch, ssrfSafeFetchWhereSupported } from '#ssrf_guard';
import { getExtensionFromMimeType } from '../utils/mime';
import { readResponseBodyWithLimit } from '../utils/readResponseBody';
import { getRandomShortId } from '../utils/uuid';

/**
 * File mount for a Composio session, reached via `session.experimental.files`
 * on a session created with `composio.sessions.create(...)`. Upload, list,
 * download, and delete files scoped to a single session.
 */
export class ToolRouterSessionFilesMount {
  private readonly sessionId: string;
  private readonly client: ComposioClient;

  constructor(client: ComposioClient, sessionId: string) {
    this.client = client;
    this.sessionId = sessionId;
    telemetry.instrument(this, 'ToolRouterSessionFiles');
  }

  /**
   * Lists files and directories at the specified path on the session's file mount.
   *
   * Use this to browse the virtual filesystem attached to the tool router session.
   * The path is relative to the mount root (e.g., `"/"` for root, `"/documents"` for a subdirectory).
   * Supports cursor-based pagination via `cursor` and `limit` options.
   *
   * @param options - Optional configuration for the list operation.
   * @param options.path - The directory path to list. Use `"/"` for the mount root.
   * @param options.mountId - The ID of the file mount to operate on. Defaults to `"files"` when omitted.
   * @param options.cursor - Pagination cursor from the previous response's nextCursor field.
   * @param options.limit - Maximum number of files to return per page (1-500).
   * @returns List of files with nextCursor for pagination.
   *
   * @example
   * ```typescript
   * const session = await composio.toolRouter.use('session_123');
   * const { items, nextCursor } = await session.experimental.files.list({ path: '/' });
   * ```
   *
   * @example
   * ```typescript
   * // Paginated listing
   * let result = await session.experimental.files.list({ path: '/', limit: 10 });
   * while (result.nextCursor) {
   *   result = await session.experimental.files.list({ path: '/', cursor: result.nextCursor, limit: 10 });
   * }
   * ```
   */
  async list(options?: ToolRouterSessionFilesMountListOptions): Promise<FileListResponse> {
    const listOptions = ToolRouterSessionFilesMountListOptionsSchema.safeParse(options ?? {});

    if (!listOptions.success) {
      throw new ValidationError('Failed to parse tool router session files mount list options', {
        cause: listOptions.error,
      });
    }

    // API requires: no leading slash, min 1 char when provided. Omit for root.
    const rawPath = listOptions.data.path;
    const mountRelativePrefix =
      rawPath === undefined || rawPath === '' || rawPath === '/'
        ? undefined
        : rawPath.startsWith('/')
          ? rawPath.slice(1)
          : rawPath;

    const response = await this.client.toolRouter.session.files.list(listOptions.data.mountId, {
      session_id: this.sessionId,
      mount_relative_prefix: mountRelativePrefix,
      cursor: listOptions.data.cursor,
      limit: listOptions.data.limit,
    });

    const data =
      typeof response === 'object' && 'body' in response
        ? (response as { body: unknown }).body
        : response;

    const parsed = FileListResponseSchema.safeParse(data);
    if (!parsed.success) {
      throw new ValidationError('Failed to parse file list response', {
        cause: parsed.error,
      });
    }
    return parsed.data;
  }

  private async normalizeUploadInput(
    input: string | File | ArrayBuffer | Uint8Array,
    options: { remotePath?: string; mimetype?: string }
  ): Promise<{ fileToUpload: File; remotePath: string; mimetype: string }> {
    if (typeof input === 'string') {
      if (input.startsWith('http://') || input.startsWith('https://')) {
        const response = await ssrfSafeFetch(input);
        if (!response.ok) {
          // The error path never reads the body, so release it explicitly (mirrors
          // `readResponseBodyWithLimit`) instead of leaving it to the garbage collector.
          await response.body?.cancel().catch(() => undefined);
          throw new Error(`Failed to fetch file from URL: ${response.statusText}`);
        }
        const content = await readResponseBodyWithLimit(response);
        const rawContentType = response.headers.get('content-type') || 'application/octet-stream';
        const mimeType = rawContentType.split(';')[0].trim();
        const url = new URL(input);
        const pathname = url.pathname;
        const segments = pathname.split('/').filter(Boolean);
        let filename = segments.length > 0 ? segments[segments.length - 1] : '';
        if (!filename || !filename.includes('.')) {
          const extension = getExtensionFromMimeType(mimeType);
          filename = `${getRandomShortId()}.${extension}`;
        }
        const file = new File([content as BlobPart], filename, { type: mimeType });
        return {
          fileToUpload: file,
          remotePath: options.remotePath ?? filename,
          mimetype: mimeType,
        };
      }
      const content = platform.readFileSync(input);
      const buffer =
        content instanceof Uint8Array
          ? new Uint8Array(content)
          : new TextEncoder().encode(content as string);
      const filename = platform.basename(input);
      const mimetype = options.mimetype ?? 'application/octet-stream';
      const file = new File([buffer], filename, { type: mimetype });
      return {
        fileToUpload: file,
        remotePath: options.remotePath ?? filename,
        mimetype,
      };
    }

    if (input instanceof File) {
      return {
        fileToUpload: input,
        remotePath: options.remotePath ?? (input.name || `upload-${getRandomShortId()}.bin`),
        mimetype: input.type || 'application/octet-stream',
      };
    }

    const buffer = input instanceof ArrayBuffer ? new Uint8Array(input) : input;
    if (!options.mimetype && !options.remotePath) {
      throw new Error(
        'When passing a buffer, either mimetype or remotePath (filename) is required. ' +
          'Example: files.upload(buffer, { remotePath: "data.json", mimetype: "application/json" })'
      );
    }
    const mimetype = options.mimetype ?? 'application/octet-stream';
    const ext = getExtensionFromMimeType(mimetype);
    const remotePath = options.remotePath ?? `upload-${getRandomShortId()}.${ext}`;
    const file = new File([buffer as BlobPart], remotePath, { type: mimetype });
    return {
      fileToUpload: file,
      remotePath,
      mimetype,
    };
  }

  /**
   * Uploads a file to the session's file mount.
   *
   * Accepts a file path (local or URL), a native File object, or a raw buffer.
   * The file is stored in the virtual filesystem associated with the tool router session.
   * URL inputs require a Node.js or Bun runtime so the destination can be DNS-validated;
   * edge runtimes must fetch the file themselves and pass a File or ArrayBuffer.
   *
   * @param input - File path (string), native File, or raw buffer (ArrayBuffer | Uint8Array).
   * @param options - Optional configuration. When passing a buffer, remotePath is required.
   * @returns Metadata about the uploaded file.
   *
   * @example
   * ```typescript
   * // From file path (local or URL)
   * await session.experimental.files.upload('/path/to/report.pdf');
   * await session.experimental.files.upload('https://example.com/file.pdf');
   * ```
   *
   * @example
   * ```typescript
   * // From native File (e.g. from input[type=file])
   * await session.experimental.files.upload(fileInput.files[0]);
   * ```
   *
   * @example
   * ```typescript
   * // From raw buffer
   * await session.experimental.files.upload(buffer, { remotePath: 'data.json', mimetype: 'application/json' });
   * ```
   */
  async upload(
    input: string | File | ArrayBuffer | Uint8Array,
    options?: ToolRouterSessionFilesMountUploadOptions
  ): Promise<RemoteFile> {
    const uploadOptions = ToolRouterSessionFilesMountUploadOptionsSchema.safeParse(options ?? {});

    if (!uploadOptions.success) {
      throw new ValidationError('Failed to parse tool router session files mount upload options', {
        cause: uploadOptions.error,
      });
    }

    const { fileToUpload, remotePath, mimetype } = await this.normalizeUploadInput(
      input,
      uploadOptions.data
    );

    const createUploadURLResponse = await this.client.toolRouter.session.files.createUploadURL(
      uploadOptions.data.mountId,
      {
        session_id: this.sessionId,
        mount_relative_path: remotePath,
        mimetype,
      }
    );

    const uploadURLData =
      typeof createUploadURLResponse === 'object' && 'body' in createUploadURLResponse
        ? (createUploadURLResponse as { body: unknown }).body
        : createUploadURLResponse;

    // SSRF guard: `upload_url` comes from the API response, so the target is
    // validated before the file's bytes are sent to it — the same treatment the
    // user-supplied URL above already gets. See ssrfGuard.node.ts.
    const uploadResponse = await ssrfSafeFetchWhereSupported(
      (uploadURLData as { upload_url: string }).upload_url,
      {
        method: 'PUT',
        body: await fileToUpload.arrayBuffer(),
        headers: {
          'Content-Type': mimetype,
        },
      }
    );

    if (!uploadResponse.ok) {
      throw new Error(`Failed to upload file: ${uploadResponse.statusText}`);
    }

    const createDownloadURLResponse = await this.client.toolRouter.session.files.createDownloadURL(
      uploadOptions.data.mountId,
      {
        session_id: this.sessionId,
        mount_relative_path: (uploadURLData as { mount_relative_path: string }).mount_relative_path,
      }
    );

    const downloadData =
      typeof createDownloadURLResponse === 'object' && 'body' in createDownloadURLResponse
        ? (createDownloadURLResponse as { body: unknown }).body
        : createDownloadURLResponse;

    const parsed = RemoteFileDataSchema.safeParse(downloadData);
    if (!parsed.success) {
      throw new ValidationError('Failed to parse remote file properties', {
        cause: parsed.error,
      });
    }

    return new RemoteFile(parsed.data);
  }

  /**
   * Downloads a file from the session's file mount to the local filesystem.
   *
   * Retrieves a file stored in the session's virtual filesystem (e.g., one produced
   * by a tool or previously uploaded) and saves it to the specified local path.
   *
   * @param filePath - The path of the file on the mount to download, or the local path where the file should be saved (implementation-specific).
   * @param options - Optional configuration for the download.
   * @param options.mountId - The ID of the file mount to download from. Defaults to `"files"` when omitted.
   * @returns The downloaded file data or path (implementation-specific).
   *
   * @example
   * ```typescript
   * const session = await composio.toolRouter.use('session_123');
   * const result = await session.experimental.files.download('/output/report.pdf');
   * ```
   *
   * @example
   * ```typescript
   * // Download from a custom mount
   * await session.experimental.files.download('/exports/data.json', {
   *   mountId: 'custom-mount',
   * });
   * ```
   */
  async download(
    filePath: string,
    options?: ToolRouterSessionFilesMountDownloadOptions
  ): Promise<RemoteFile> {
    const downloadOptions = ToolRouterSessionFilesMountDownloadOptionsSchema.safeParse(
      options ?? {}
    );

    if (!downloadOptions.success) {
      throw new ValidationError(
        'Failed to parse tool router session files mount download options',
        {
          cause: downloadOptions.error,
        }
      );
    }

    const createDownloadURLResponse = await this.client.toolRouter.session.files.createDownloadURL(
      downloadOptions.data.mountId,
      {
        session_id: this.sessionId,
        mount_relative_path: filePath,
      }
    );

    const downloadURLData =
      typeof createDownloadURLResponse === 'object' && 'body' in createDownloadURLResponse
        ? (createDownloadURLResponse as { body: unknown }).body
        : createDownloadURLResponse;

    const parsed = RemoteFileDataSchema.safeParse(downloadURLData);
    if (!parsed.success) {
      throw new ValidationError('Failed to parse remote file properties', {
        cause: parsed.error,
      });
    }
    return new RemoteFile(parsed.data);
  }

  /**
   * Deletes a file or directory at the specified path on the session's file mount.
   *
   * Removes the file or directory from the virtual filesystem. Use with caution:
   * deletion is typically irreversible. Ensure the path exists and is intended for removal.
   *
   * @param remotePath - The path of the file or directory to delete on the mount.
   * @param options - Optional configuration for the delete operation.
   * @param options.mountId - The ID of the file mount to operate on. Defaults to `"files"` when omitted.
   * @returns Confirmation of deletion (implementation-specific).
   *
   * @example
   * ```typescript
   * const session = await composio.toolRouter.use('session_123');
   * await session.experimental.files.delete('/temp/cache.json');
   * ```
   *
   * @example
   * ```typescript
   * // Delete from a custom mount
   * await session.experimental.files.delete('/old-backup', {
   *   mountId: 'custom-mount',
   * });
   * ```
   *
   * @warning This operation is destructive. Deleted files cannot be recovered.
   */
  async delete(
    remotePath: string,
    options?: ToolRouterSessionFilesMountDeleteOptions
  ): Promise<FileDeleteResponse> {
    const deleteOptions = ToolRouterSessionFilesMountDeleteOptionsSchema.safeParse(options ?? {});

    if (!deleteOptions.success) {
      throw new ValidationError('Failed to parse tool router session files mount delete options', {
        cause: deleteOptions.error,
      });
    }

    const deleteResponse = await this.client.toolRouter.session.files.delete(
      deleteOptions.data.mountId,
      {
        session_id: this.sessionId,
        mount_relative_path: remotePath,
      }
    );
    const fileDeleteResponse = FileDeleteResponseSchema.safeParse(deleteResponse);
    if (!fileDeleteResponse.success) {
      throw new ValidationError('Failed to parse file delete response', {
        cause: fileDeleteResponse.error,
      });
    }
    return fileDeleteResponse.data;
  }
}