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

next
ts 124 lines 4.01 KB
Raw
1 /**
2 * @fileoverview Files class for Composio SDK, used to manage files.
3 *
4 * @author Musthaq Ahamad <musthaq@composio.dev>
5 * @date 2025-06-23
6 * @module Files
7 */
8 import ComposioClient from '@composio/client';
9 import { FileDownloadData, FileUploadData } from '../types/files.types';
10 import { ComposioRequestOptions } from '../types/requestOptions.types';
11 import { downloadFileFromS3, getFileDataAfterUploadingToS3 } from '../utils/fileUtils.node';
12 import { withCancellation } from '../utils/cancellation';
13 import { telemetry } from '../telemetry/Telemetry';
14
15 export class Files {
16 private readonly fileOptions: {
17 sensitiveFileUploadProtection?: boolean;
18 fileUploadPathDenySegments?: string[];
19 fileDownloadDir?: string;
20 };
21
22 constructor(
23 private readonly client: ComposioClient,
24 fileOptions: {
25 sensitiveFileUploadProtection?: boolean;
26 fileUploadPathDenySegments?: string[];
27 fileDownloadDir?: string;
28 } = {}
29 ) {
30 this.fileOptions = fileOptions;
31 telemetry.instrument(this, 'Files');
32 }
33
34 /**
35 * Upload a file and return the file data.
36 *
37 * @param params - The upload parameters.
38 * @param {File | string} params.file - The path to the file to upload, a URL of the file, or a File object.
39 * @param {string} params.toolSlug - The slug of the tool that is uploading the file.
40 * @param {string} params.toolkitSlug - The slug of the toolkit that is uploading the file.
41 * @param {ComposioRequestOptions} [requestOptions] - Optional request options. `signal` cancels
42 * the file read from a URL, the presigned-URL request, and the S3 transfer; the call then
43 * rejects with {@link ComposioRequestCancelledError}.
44 * @returns {Promise<FileUploadData>} The uploaded file data.
45 *
46 * @example
47 *
48 * const fileData = await composio.files.upload(
49 * {
50 * file: 'path/to/file.pdf',
51 * toolSlug: 'google_drive_upload',
52 * toolkitSlug: 'google_drive',
53 * },
54 * { signal: AbortSignal.timeout(30_000) }
55 * );
56 * */
57 async upload(
58 {
59 file,
60 toolSlug,
61 toolkitSlug,
62 }: {
63 file: File | string;
64 toolSlug: string;
65 toolkitSlug: string;
66 },
67 requestOptions?: ComposioRequestOptions
68 ): Promise<FileUploadData> {
69 const signal = requestOptions?.signal;
70 // Note: manual `composio.files.upload()` intentionally skips the
71 // `fileUploadDirs` allowlist. The allowlist only gates *automatic* upload
72 // during tool execution (see FileToolModifier).
73 return withCancellation(
74 () =>
75 getFileDataAfterUploadingToS3(file, {
76 toolSlug,
77 toolkitSlug,
78 client: this.client,
79 sensitiveFileUploadProtection: this.fileOptions.sensitiveFileUploadProtection,
80 fileUploadPathDenySegments: this.fileOptions.fileUploadPathDenySegments,
81 signal,
82 }),
83 signal
84 );
85 }
86
87 /**
88 * Download a file from S3 and return the file data.
89 *
90 * @param params - The download parameters.
91 * @param {string} params.s3Url - The S3 URL of the file to download.
92 * @param {string} params.toolSlug - The slug of the tool the file belongs to, used as the file name prefix.
93 * @param {string} params.mimeType - The MIME type of the file, used to pick the file extension.
94 * @param {ComposioRequestOptions} [requestOptions] - Optional request options. `signal` cancels
95 * the download before the file is written; the call then rejects with
96 * {@link ComposioRequestCancelledError}.
97 * @returns {Promise<FileDownloadData>} The downloaded file data.
98 */
99 async download(
100 {
101 toolSlug,
102 s3Url,
103 mimeType,
104 }: {
105 s3Url: string;
106 toolSlug: string;
107 mimeType: string;
108 },
109 requestOptions?: ComposioRequestOptions
110 ): Promise<FileDownloadData> {
111 const signal = requestOptions?.signal;
112 return withCancellation(
113 () =>
114 downloadFileFromS3({
115 toolSlug,
116 s3Url,
117 mimeType,
118 fileDownloadDir: this.fileOptions.fileDownloadDir,
119 signal,
120 }),
121 signal
122 );
123 }
124 }