@memberjunction/storage 2.39.0 → 2.40.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/drivers/AWSFileStorage.d.ts +360 -4
- package/dist/drivers/AWSFileStorage.d.ts.map +1 -1
- package/dist/drivers/AWSFileStorage.js +357 -4
- package/dist/drivers/AWSFileStorage.js.map +1 -1
- package/dist/drivers/AzureFileStorage.d.ts +362 -2
- package/dist/drivers/AzureFileStorage.d.ts.map +1 -1
- package/dist/drivers/AzureFileStorage.js +357 -2
- package/dist/drivers/AzureFileStorage.js.map +1 -1
- package/dist/drivers/BoxFileStorage.d.ts +539 -20
- package/dist/drivers/BoxFileStorage.d.ts.map +1 -1
- package/dist/drivers/BoxFileStorage.js +521 -20
- package/dist/drivers/BoxFileStorage.js.map +1 -1
- package/dist/drivers/DropboxFileStorage.d.ts +437 -15
- package/dist/drivers/DropboxFileStorage.d.ts.map +1 -1
- package/dist/drivers/DropboxFileStorage.js +431 -15
- package/dist/drivers/DropboxFileStorage.js.map +1 -1
- package/dist/drivers/GoogleDriveFileStorage.d.ts +342 -16
- package/dist/drivers/GoogleDriveFileStorage.d.ts.map +1 -1
- package/dist/drivers/GoogleDriveFileStorage.js +340 -16
- package/dist/drivers/GoogleDriveFileStorage.js.map +1 -1
- package/dist/drivers/GoogleFileStorage.d.ts +358 -2
- package/dist/drivers/GoogleFileStorage.d.ts.map +1 -1
- package/dist/drivers/GoogleFileStorage.js +356 -2
- package/dist/drivers/GoogleFileStorage.js.map +1 -1
- package/dist/drivers/SharePointFileStorage.d.ts +434 -20
- package/dist/drivers/SharePointFileStorage.d.ts.map +1 -1
- package/dist/drivers/SharePointFileStorage.js +453 -22
- package/dist/drivers/SharePointFileStorage.js.map +1 -1
- package/dist/generic/FileStorageBase.d.ts +326 -108
- package/dist/generic/FileStorageBase.d.ts.map +1 -1
- package/dist/generic/FileStorageBase.js +54 -6
- package/dist/generic/FileStorageBase.js.map +1 -1
- package/dist/util.d.ts +125 -18
- package/dist/util.d.ts.map +1 -1
- package/dist/util.js +125 -18
- package/dist/util.js.map +1 -1
- package/package.json +4 -4
- package/readme.md +211 -1
|
@@ -1,93 +1,612 @@
|
|
|
1
1
|
/// <reference types="node" />
|
|
2
2
|
import { CreatePreAuthUploadUrlPayload, FileStorageBase, StorageListResult, StorageObjectMetadata } from '../generic/FileStorageBase';
|
|
3
|
+
/**
|
|
4
|
+
* FileStorageBase implementation for Box.com cloud storage
|
|
5
|
+
*
|
|
6
|
+
* This provider allows working with files stored in Box.com. It supports
|
|
7
|
+
* authentication via access token, refresh token, or client credentials (JWT).
|
|
8
|
+
*
|
|
9
|
+
* @remarks
|
|
10
|
+
* This implementation requires at least one of the following authentication methods:
|
|
11
|
+
*
|
|
12
|
+
* 1. Access Token:
|
|
13
|
+
* - STORAGE_BOX_ACCESS_TOKEN - A valid Box API access token
|
|
14
|
+
*
|
|
15
|
+
* 2. Refresh Token:
|
|
16
|
+
* - STORAGE_BOX_REFRESH_TOKEN - A valid Box API refresh token
|
|
17
|
+
* - STORAGE_BOX_CLIENT_ID - Your Box application client ID
|
|
18
|
+
* - STORAGE_BOX_CLIENT_SECRET - Your Box application client secret
|
|
19
|
+
*
|
|
20
|
+
* 3. Client Credentials (JWT):
|
|
21
|
+
* - STORAGE_BOX_CLIENT_ID - Your Box application client ID
|
|
22
|
+
* - STORAGE_BOX_CLIENT_SECRET - Your Box application client secret
|
|
23
|
+
* - STORAGE_BOX_ENTERPRISE_ID - Your Box enterprise ID
|
|
24
|
+
*
|
|
25
|
+
* Optional configuration:
|
|
26
|
+
* - STORAGE_BOX_ROOT_FOLDER_ID - ID of a Box folder to use as the root (defaults to '0' which is the root)
|
|
27
|
+
*
|
|
28
|
+
* @example
|
|
29
|
+
* ```typescript
|
|
30
|
+
* // Set required environment variables for JWT auth
|
|
31
|
+
* process.env.STORAGE_BOX_CLIENT_ID = 'your-client-id';
|
|
32
|
+
* process.env.STORAGE_BOX_CLIENT_SECRET = 'your-client-secret';
|
|
33
|
+
* process.env.STORAGE_BOX_ENTERPRISE_ID = 'your-enterprise-id';
|
|
34
|
+
*
|
|
35
|
+
* // Create the provider
|
|
36
|
+
* const storage = new BoxFileStorage();
|
|
37
|
+
* await storage.initialize(); // Required for JWT auth
|
|
38
|
+
*
|
|
39
|
+
* // Upload a file
|
|
40
|
+
* const fileContent = Buffer.from('Hello, Box!');
|
|
41
|
+
* await storage.PutObject('documents/hello.txt', fileContent, 'text/plain');
|
|
42
|
+
*
|
|
43
|
+
* // Download a file
|
|
44
|
+
* const downloadedContent = await storage.GetObject('documents/hello.txt');
|
|
45
|
+
*
|
|
46
|
+
* // Get a temporary download URL
|
|
47
|
+
* const downloadUrl = await storage.CreatePreAuthDownloadUrl('documents/hello.txt');
|
|
48
|
+
* ```
|
|
49
|
+
*/
|
|
3
50
|
export declare class BoxFileStorage extends FileStorageBase {
|
|
51
|
+
/**
|
|
52
|
+
* The name of this storage provider
|
|
53
|
+
*/
|
|
4
54
|
protected readonly providerName = "Box";
|
|
55
|
+
/**
|
|
56
|
+
* Box API access token
|
|
57
|
+
*/
|
|
5
58
|
private _accessToken;
|
|
59
|
+
/**
|
|
60
|
+
* Box API refresh token
|
|
61
|
+
*/
|
|
6
62
|
private _refreshToken;
|
|
63
|
+
/**
|
|
64
|
+
* Box application client ID
|
|
65
|
+
*/
|
|
7
66
|
private _clientId;
|
|
67
|
+
/**
|
|
68
|
+
* Box application client secret
|
|
69
|
+
*/
|
|
8
70
|
private _clientSecret;
|
|
71
|
+
/**
|
|
72
|
+
* Timestamp when current access token expires
|
|
73
|
+
*/
|
|
9
74
|
private _tokenExpiresAt;
|
|
75
|
+
/**
|
|
76
|
+
* Base URL for Box API
|
|
77
|
+
*/
|
|
10
78
|
private _baseApiUrl;
|
|
79
|
+
/**
|
|
80
|
+
* Base URL for Box Upload API
|
|
81
|
+
*/
|
|
11
82
|
private _uploadApiUrl;
|
|
83
|
+
/**
|
|
84
|
+
* ID of the Box folder to use as root
|
|
85
|
+
*/
|
|
12
86
|
private _rootFolderId;
|
|
87
|
+
/**
|
|
88
|
+
* Box enterprise ID for JWT auth
|
|
89
|
+
*/
|
|
13
90
|
private _enterpriseId;
|
|
91
|
+
/**
|
|
92
|
+
* Creates a new BoxFileStorage instance
|
|
93
|
+
*
|
|
94
|
+
* This constructor reads the required Box authentication configuration
|
|
95
|
+
* from environment variables.
|
|
96
|
+
*
|
|
97
|
+
* @throws Error if refresh token is provided without client ID and secret
|
|
98
|
+
*/
|
|
14
99
|
constructor();
|
|
15
100
|
/**
|
|
16
|
-
*
|
|
17
|
-
*
|
|
101
|
+
* Initializes the Box storage driver
|
|
102
|
+
*
|
|
103
|
+
* This method must be called after creating a BoxFileStorage instance
|
|
104
|
+
* when using client credentials (JWT) authentication. It obtains the
|
|
105
|
+
* initial access token required for API calls.
|
|
106
|
+
*
|
|
107
|
+
* @returns A Promise that resolves when initialization is complete
|
|
108
|
+
*
|
|
109
|
+
* @example
|
|
110
|
+
* ```typescript
|
|
111
|
+
* const storage = new BoxFileStorage();
|
|
112
|
+
* await storage.initialize();
|
|
113
|
+
* // Now the storage provider is ready to use
|
|
114
|
+
* ```
|
|
18
115
|
*/
|
|
19
116
|
initialize(): Promise<void>;
|
|
117
|
+
/**
|
|
118
|
+
* Obtains an access token using client credentials flow
|
|
119
|
+
*
|
|
120
|
+
* This method requests a new access token using the Box client credentials
|
|
121
|
+
* flow (JWT) with the enterprise as the subject.
|
|
122
|
+
*
|
|
123
|
+
* @private
|
|
124
|
+
* @returns A Promise that resolves when the access token is obtained
|
|
125
|
+
* @throws Error if token acquisition fails
|
|
126
|
+
*/
|
|
20
127
|
private _setAccessToken;
|
|
21
128
|
/**
|
|
22
|
-
* Ensures
|
|
129
|
+
* Ensures a valid access token is available for API requests
|
|
130
|
+
*
|
|
131
|
+
* This method checks if the current token is valid, and if not, attempts
|
|
132
|
+
* to refresh or obtain a new token using the configured authentication method.
|
|
133
|
+
*
|
|
134
|
+
* @private
|
|
135
|
+
* @returns A Promise that resolves to a valid access token
|
|
136
|
+
* @throws Error if no valid token can be obtained
|
|
23
137
|
*/
|
|
24
138
|
private _ensureValidToken;
|
|
25
139
|
/**
|
|
26
|
-
*
|
|
140
|
+
* Makes an authenticated API request to the Box API
|
|
141
|
+
*
|
|
142
|
+
* This helper method handles authentication, request formatting, and
|
|
143
|
+
* response parsing for all Box API calls.
|
|
144
|
+
*
|
|
145
|
+
* @private
|
|
146
|
+
* @param endpoint - The API endpoint to call (e.g., '/files/123')
|
|
147
|
+
* @param method - The HTTP method to use (default: 'GET')
|
|
148
|
+
* @param body - Optional request body (will be serialized as JSON unless it's FormData)
|
|
149
|
+
* @param headers - Optional additional headers
|
|
150
|
+
* @param baseUrl - Base URL to use (defaults to standard API URL)
|
|
151
|
+
* @returns A Promise that resolves to the API response data
|
|
152
|
+
* @throws Error if the API request fails
|
|
27
153
|
*/
|
|
28
154
|
private _apiRequest;
|
|
29
155
|
/**
|
|
30
|
-
*
|
|
156
|
+
* Parses a path string into Box API components
|
|
157
|
+
*
|
|
158
|
+
* This helper method converts a standard path string (e.g., 'documents/reports/file.txt')
|
|
159
|
+
* into components used by the Box API (folder ID, name, parent path).
|
|
160
|
+
*
|
|
161
|
+
* @private
|
|
162
|
+
* @param path - The path to parse
|
|
163
|
+
* @returns An object containing the parsed components: id, name, and parent
|
|
31
164
|
*/
|
|
32
165
|
private _parsePath;
|
|
33
166
|
/**
|
|
34
|
-
*
|
|
167
|
+
* Resolves a path string to a Box item ID
|
|
168
|
+
*
|
|
169
|
+
* This helper method navigates the Box folder hierarchy to find
|
|
170
|
+
* the item at the specified path, returning its Box ID.
|
|
171
|
+
*
|
|
172
|
+
* @private
|
|
173
|
+
* @param path - The path to resolve
|
|
174
|
+
* @returns A Promise that resolves to the Box item ID
|
|
175
|
+
* @throws Error if the item does not exist
|
|
35
176
|
*/
|
|
36
177
|
private _getIdFromPath;
|
|
37
178
|
/**
|
|
38
|
-
*
|
|
179
|
+
* Converts a Box API item to StorageObjectMetadata
|
|
180
|
+
*
|
|
181
|
+
* This helper method transforms a Box API item representation into
|
|
182
|
+
* the standard StorageObjectMetadata format used by FileStorageBase.
|
|
183
|
+
*
|
|
184
|
+
* @private
|
|
185
|
+
* @param item - The Box API item object
|
|
186
|
+
* @param parentPath - The parent path string
|
|
187
|
+
* @returns A StorageObjectMetadata object
|
|
39
188
|
*/
|
|
40
189
|
private _convertToMetadata;
|
|
41
190
|
/**
|
|
42
|
-
*
|
|
191
|
+
* Creates a pre-authenticated upload URL for a file
|
|
192
|
+
*
|
|
193
|
+
* This method creates a Box upload session and returns a URL that can be used
|
|
194
|
+
* to upload file content directly to Box without requiring authentication.
|
|
195
|
+
*
|
|
196
|
+
* @param objectName - Path where the file should be uploaded (e.g., 'documents/report.pdf')
|
|
197
|
+
* @returns A Promise that resolves to an object containing the upload URL and provider key
|
|
198
|
+
* @throws Error if the URL creation fails
|
|
199
|
+
*
|
|
200
|
+
* @remarks
|
|
201
|
+
* - The parent folder structure will be created automatically if it doesn't exist
|
|
202
|
+
* - The returned provider key contains the session ID needed to complete the upload
|
|
203
|
+
* - Box upload sessions expire after a certain period (typically 1 hour)
|
|
204
|
+
*
|
|
205
|
+
* @example
|
|
206
|
+
* ```typescript
|
|
207
|
+
* try {
|
|
208
|
+
* // Generate a pre-authenticated upload URL
|
|
209
|
+
* const uploadInfo = await storage.CreatePreAuthUploadUrl('presentations/quarterly-results.pptx');
|
|
210
|
+
*
|
|
211
|
+
* // The URL can be used to upload content directly
|
|
212
|
+
* console.log(`Upload URL: ${uploadInfo.UploadUrl}`);
|
|
213
|
+
*
|
|
214
|
+
* // Make sure to save the provider key, as it's needed to reference the upload
|
|
215
|
+
* console.log(`Provider Key: ${uploadInfo.ProviderKey}`);
|
|
216
|
+
*
|
|
217
|
+
* // You can use fetch or another HTTP client to upload to this URL
|
|
218
|
+
* await fetch(uploadInfo.UploadUrl, {
|
|
219
|
+
* method: 'PUT',
|
|
220
|
+
* headers: { 'Content-Type': 'application/octet-stream' },
|
|
221
|
+
* body: fileContent
|
|
222
|
+
* });
|
|
223
|
+
* } catch (error) {
|
|
224
|
+
* console.error('Error creating upload URL:', error.message);
|
|
225
|
+
* }
|
|
226
|
+
* ```
|
|
43
227
|
*/
|
|
44
228
|
CreatePreAuthUploadUrl(objectName: string): Promise<CreatePreAuthUploadUrlPayload>;
|
|
45
229
|
/**
|
|
46
|
-
*
|
|
230
|
+
* Creates a pre-authenticated download URL for a file
|
|
231
|
+
*
|
|
232
|
+
* This method generates a time-limited URL that can be used to download
|
|
233
|
+
* a file without authentication. The URL typically expires after 60 minutes.
|
|
234
|
+
*
|
|
235
|
+
* @param objectName - Path to the file to download (e.g., 'documents/report.pdf')
|
|
236
|
+
* @returns A Promise that resolves to the download URL string
|
|
237
|
+
* @throws Error if the file doesn't exist or URL creation fails
|
|
238
|
+
*
|
|
239
|
+
* @remarks
|
|
240
|
+
* - Cannot be used with upload sessions that haven't been completed
|
|
241
|
+
* - Box download URLs typically expire after 60 minutes
|
|
242
|
+
* - Generated URLs can be shared with users who don't have Box access
|
|
243
|
+
*
|
|
244
|
+
* @example
|
|
245
|
+
* ```typescript
|
|
246
|
+
* try {
|
|
247
|
+
* // Generate a pre-authenticated download URL
|
|
248
|
+
* const downloadUrl = await storage.CreatePreAuthDownloadUrl('documents/financial-report.pdf');
|
|
249
|
+
*
|
|
250
|
+
* console.log(`Download the file using this URL: ${downloadUrl}`);
|
|
251
|
+
*
|
|
252
|
+
* // The URL can be shared or used in a browser to download the file
|
|
253
|
+
* // without requiring Box authentication
|
|
254
|
+
* } catch (error) {
|
|
255
|
+
* console.error('Error creating download URL:', error.message);
|
|
256
|
+
* }
|
|
257
|
+
* ```
|
|
47
258
|
*/
|
|
48
259
|
CreatePreAuthDownloadUrl(objectName: string): Promise<string>;
|
|
49
260
|
/**
|
|
50
|
-
*
|
|
261
|
+
* Moves a file or folder from one location to another
|
|
262
|
+
*
|
|
263
|
+
* This method moves a file or folder to a new location in Box storage.
|
|
264
|
+
* It handles both renaming and changing the parent folder.
|
|
265
|
+
*
|
|
266
|
+
* @param oldObjectName - Current path of the object (e.g., 'old-folder/document.docx')
|
|
267
|
+
* @param newObjectName - New path for the object (e.g., 'new-folder/renamed-document.docx')
|
|
268
|
+
* @returns A Promise that resolves to true if successful, false otherwise
|
|
269
|
+
*
|
|
270
|
+
* @remarks
|
|
271
|
+
* - Parent folders will be created automatically if they don't exist
|
|
272
|
+
* - Works with both files and folders
|
|
273
|
+
* - For folders, all contents will move with the folder
|
|
274
|
+
*
|
|
275
|
+
* @example
|
|
276
|
+
* ```typescript
|
|
277
|
+
* // Move a file to a different folder and rename it
|
|
278
|
+
* const moveResult = await storage.MoveObject(
|
|
279
|
+
* 'documents/old-report.pdf',
|
|
280
|
+
* 'archive/2023/annual-report.pdf'
|
|
281
|
+
* );
|
|
282
|
+
*
|
|
283
|
+
* if (moveResult) {
|
|
284
|
+
* console.log('File moved successfully');
|
|
285
|
+
* } else {
|
|
286
|
+
* console.error('Failed to move file');
|
|
287
|
+
* }
|
|
288
|
+
* ```
|
|
51
289
|
*/
|
|
52
290
|
MoveObject(oldObjectName: string, newObjectName: string): Promise<boolean>;
|
|
53
291
|
/**
|
|
54
|
-
*
|
|
292
|
+
* Deletes a file or folder from Box storage
|
|
293
|
+
*
|
|
294
|
+
* This method permanently deletes a file or folder. It can also
|
|
295
|
+
* handle special cases like incomplete upload sessions.
|
|
296
|
+
*
|
|
297
|
+
* @param objectName - Path to the object to delete (e.g., 'documents/old-report.docx')
|
|
298
|
+
* @returns A Promise that resolves to true if successful, false if an error occurs
|
|
299
|
+
*
|
|
300
|
+
* @remarks
|
|
301
|
+
* - Returns true if the object doesn't exist (for idempotency)
|
|
302
|
+
* - Can handle special provider keys like upload sessions
|
|
303
|
+
* - Box puts deleted items in the trash, where they can be recovered for a limited time
|
|
304
|
+
* - To permanently delete folder contents, use DeleteDirectory with recursive=true
|
|
305
|
+
*
|
|
306
|
+
* @example
|
|
307
|
+
* ```typescript
|
|
308
|
+
* // Delete a file
|
|
309
|
+
* const deleteResult = await storage.DeleteObject('temp/draft-document.docx');
|
|
310
|
+
*
|
|
311
|
+
* if (deleteResult) {
|
|
312
|
+
* console.log('File deleted successfully or already didn\'t exist');
|
|
313
|
+
* } else {
|
|
314
|
+
* console.error('Failed to delete file');
|
|
315
|
+
* }
|
|
316
|
+
*
|
|
317
|
+
* // Delete an upload session
|
|
318
|
+
* await storage.DeleteObject('session:1234567890:documents/large-file.zip');
|
|
319
|
+
* ```
|
|
55
320
|
*/
|
|
56
321
|
DeleteObject(objectName: string): Promise<boolean>;
|
|
57
322
|
/**
|
|
58
|
-
*
|
|
323
|
+
* Lists files and folders in a given directory
|
|
324
|
+
*
|
|
325
|
+
* This method retrieves all files and subfolders in the specified directory.
|
|
326
|
+
* It returns both a list of object metadata and a list of directory prefixes.
|
|
327
|
+
*
|
|
328
|
+
* @param prefix - Path to the directory to list (e.g., 'documents/reports')
|
|
329
|
+
* @param delimiter - Optional delimiter character (default: '/')
|
|
330
|
+
* @returns A Promise that resolves to a StorageListResult containing objects and prefixes
|
|
331
|
+
*
|
|
332
|
+
* @remarks
|
|
333
|
+
* - The `objects` array includes both files and folders
|
|
334
|
+
* - The `prefixes` array includes only folder paths (with trailing slashes)
|
|
335
|
+
* - Returns empty arrays if the directory doesn't exist
|
|
336
|
+
* - The delimiter parameter is included for interface compatibility but not used internally
|
|
337
|
+
*
|
|
338
|
+
* @example
|
|
339
|
+
* ```typescript
|
|
340
|
+
* // List all files and folders in the 'documents' directory
|
|
341
|
+
* const result = await storage.ListObjects('documents');
|
|
342
|
+
*
|
|
343
|
+
* // Process files and folders
|
|
344
|
+
* console.log(`Found ${result.objects.length} items:`);
|
|
345
|
+
* for (const obj of result.objects) {
|
|
346
|
+
* console.log(`- ${obj.name} (${obj.isDirectory ? 'Folder' : 'File'}, ${obj.size} bytes)`);
|
|
347
|
+
* }
|
|
348
|
+
*
|
|
349
|
+
* // List subfolders only
|
|
350
|
+
* console.log(`Found ${result.prefixes.length} subfolders:`);
|
|
351
|
+
* for (const prefix of result.prefixes) {
|
|
352
|
+
* console.log(`- ${prefix}`);
|
|
353
|
+
* }
|
|
354
|
+
* ```
|
|
59
355
|
*/
|
|
60
356
|
ListObjects(prefix: string, delimiter?: string): Promise<StorageListResult>;
|
|
61
357
|
/**
|
|
62
|
-
*
|
|
358
|
+
* Creates a new directory (folder) in Box storage
|
|
359
|
+
*
|
|
360
|
+
* This method creates a folder at the specified path, automatically
|
|
361
|
+
* creating any parent folders that don't exist.
|
|
362
|
+
*
|
|
363
|
+
* @param directoryPath - Path where the directory should be created (e.g., 'documents/reports/2023')
|
|
364
|
+
* @returns A Promise that resolves to true if successful, false if an error occurs
|
|
365
|
+
*
|
|
366
|
+
* @remarks
|
|
367
|
+
* - Creates parent directories recursively if they don't exist
|
|
368
|
+
* - Returns true if the directory already exists (idempotent operation)
|
|
369
|
+
* - Trailing slashes in the path are automatically removed
|
|
370
|
+
*
|
|
371
|
+
* @example
|
|
372
|
+
* ```typescript
|
|
373
|
+
* // Create a nested directory structure
|
|
374
|
+
* const createResult = await storage.CreateDirectory('documents/reports/2023/Q1');
|
|
375
|
+
*
|
|
376
|
+
* if (createResult) {
|
|
377
|
+
* console.log('Directory created successfully');
|
|
378
|
+
*
|
|
379
|
+
* // Now we can put files in this directory
|
|
380
|
+
* await storage.PutObject(
|
|
381
|
+
* 'documents/reports/2023/Q1/financial-summary.xlsx',
|
|
382
|
+
* fileContent,
|
|
383
|
+
* 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
|
|
384
|
+
* );
|
|
385
|
+
* } else {
|
|
386
|
+
* console.error('Failed to create directory');
|
|
387
|
+
* }
|
|
388
|
+
* ```
|
|
63
389
|
*/
|
|
64
390
|
CreateDirectory(directoryPath: string): Promise<boolean>;
|
|
65
391
|
/**
|
|
66
|
-
*
|
|
392
|
+
* Deletes a directory from Box storage
|
|
393
|
+
*
|
|
394
|
+
* This method deletes a folder and optionally its contents. By default,
|
|
395
|
+
* it will only delete empty folders unless recursive is set to true.
|
|
396
|
+
*
|
|
397
|
+
* @param directoryPath - Path to the directory to delete (e.g., 'documents/old-reports')
|
|
398
|
+
* @param recursive - If true, delete the directory and all its contents; if false, only delete if empty
|
|
399
|
+
* @returns A Promise that resolves to true if successful, false if an error occurs
|
|
400
|
+
*
|
|
401
|
+
* @remarks
|
|
402
|
+
* - Returns true if the directory doesn't exist (idempotent operation)
|
|
403
|
+
* - If recursive=false and the directory contains files, the operation will fail
|
|
404
|
+
* - Box puts deleted folders in the trash, where they can be recovered for a limited time
|
|
405
|
+
* - Trailing slashes in the path are automatically removed
|
|
406
|
+
*
|
|
407
|
+
* @example
|
|
408
|
+
* ```typescript
|
|
409
|
+
* // Try to delete an empty folder
|
|
410
|
+
* const deleteResult = await storage.DeleteDirectory('temp/empty-folder');
|
|
411
|
+
*
|
|
412
|
+
* // Delete a folder and all its contents
|
|
413
|
+
* const recursiveDeleteResult = await storage.DeleteDirectory('archive/old-data', true);
|
|
414
|
+
*
|
|
415
|
+
* if (recursiveDeleteResult) {
|
|
416
|
+
* console.log('Folder and all its contents deleted successfully');
|
|
417
|
+
* } else {
|
|
418
|
+
* console.error('Failed to delete folder');
|
|
419
|
+
* }
|
|
420
|
+
* ```
|
|
67
421
|
*/
|
|
68
422
|
DeleteDirectory(directoryPath: string, recursive?: boolean): Promise<boolean>;
|
|
69
423
|
/**
|
|
70
|
-
*
|
|
424
|
+
* Gets metadata for a file or folder
|
|
425
|
+
*
|
|
426
|
+
* This method retrieves metadata about a file or folder in Box storage,
|
|
427
|
+
* such as size, type, and modification date.
|
|
428
|
+
*
|
|
429
|
+
* @param objectName - Path to the object to get metadata for (e.g., 'documents/report.pdf')
|
|
430
|
+
* @returns A Promise that resolves to a StorageObjectMetadata object
|
|
431
|
+
* @throws Error if the object doesn't exist or cannot be accessed
|
|
432
|
+
*
|
|
433
|
+
* @example
|
|
434
|
+
* ```typescript
|
|
435
|
+
* try {
|
|
436
|
+
* // Get metadata for a file
|
|
437
|
+
* const metadata = await storage.GetObjectMetadata('presentations/quarterly-update.pptx');
|
|
438
|
+
*
|
|
439
|
+
* console.log(`Name: ${metadata.name}`);
|
|
440
|
+
* console.log(`Path: ${metadata.path}`);
|
|
441
|
+
* console.log(`Size: ${metadata.size} bytes`);
|
|
442
|
+
* console.log(`Content Type: ${metadata.contentType}`);
|
|
443
|
+
* console.log(`Last Modified: ${metadata.lastModified}`);
|
|
444
|
+
* console.log(`Is Directory: ${metadata.isDirectory}`);
|
|
445
|
+
*
|
|
446
|
+
* // Box-specific metadata is available in customMetadata
|
|
447
|
+
* console.log(`Box ID: ${metadata.customMetadata.id}`);
|
|
448
|
+
* } catch (error) {
|
|
449
|
+
* console.error('Error getting metadata:', error.message);
|
|
450
|
+
* }
|
|
451
|
+
* ```
|
|
71
452
|
*/
|
|
72
453
|
GetObjectMetadata(objectName: string): Promise<StorageObjectMetadata>;
|
|
73
454
|
/**
|
|
74
|
-
*
|
|
455
|
+
* Downloads a file's contents
|
|
456
|
+
*
|
|
457
|
+
* This method retrieves the raw content of a file as a Buffer.
|
|
458
|
+
*
|
|
459
|
+
* @param objectName - Path to the file to download (e.g., 'documents/report.pdf')
|
|
460
|
+
* @returns A Promise that resolves to a Buffer containing the file's contents
|
|
461
|
+
* @throws Error if the file doesn't exist or cannot be downloaded
|
|
462
|
+
*
|
|
463
|
+
* @remarks
|
|
464
|
+
* - This method will throw an error if the object is a folder
|
|
465
|
+
* - For large files, consider using CreatePreAuthDownloadUrl instead
|
|
466
|
+
* - For upload sessions that haven't been completed, this method will fail
|
|
467
|
+
*
|
|
468
|
+
* @example
|
|
469
|
+
* ```typescript
|
|
470
|
+
* try {
|
|
471
|
+
* // Download a text file
|
|
472
|
+
* const fileContent = await storage.GetObject('documents/notes.txt');
|
|
473
|
+
*
|
|
474
|
+
* // Convert Buffer to string for text files
|
|
475
|
+
* const textContent = fileContent.toString('utf8');
|
|
476
|
+
* console.log('File content:', textContent);
|
|
477
|
+
*
|
|
478
|
+
* // For binary files, you can write the buffer to disk
|
|
479
|
+
* // or process it as needed
|
|
480
|
+
* } catch (error) {
|
|
481
|
+
* console.error('Error downloading file:', error.message);
|
|
482
|
+
* }
|
|
483
|
+
* ```
|
|
75
484
|
*/
|
|
76
485
|
GetObject(objectName: string): Promise<Buffer>;
|
|
77
486
|
/**
|
|
78
|
-
*
|
|
487
|
+
* Uploads a file to Box storage
|
|
488
|
+
*
|
|
489
|
+
* This method uploads a file to the specified path in Box storage. It automatically
|
|
490
|
+
* determines whether to use a simple upload or chunked upload based on file size.
|
|
491
|
+
*
|
|
492
|
+
* @param objectName - Path where the file should be uploaded (e.g., 'documents/report.pdf')
|
|
493
|
+
* @param data - Buffer containing the file content
|
|
494
|
+
* @param contentType - Optional MIME type of the file (if not provided, it will be guessed from the filename)
|
|
495
|
+
* @param metadata - Optional metadata to associate with the file (not used in Box implementation)
|
|
496
|
+
* @returns A Promise that resolves to true if successful, false if an error occurs
|
|
497
|
+
*
|
|
498
|
+
* @remarks
|
|
499
|
+
* - Automatically creates parent directories if they don't exist
|
|
500
|
+
* - Files smaller than 50MB use a simple upload
|
|
501
|
+
* - Files 50MB or larger use a chunked upload process
|
|
502
|
+
* - If a file with the same name exists, it will be replaced
|
|
503
|
+
*
|
|
504
|
+
* @example
|
|
505
|
+
* ```typescript
|
|
506
|
+
* // Create a simple text file
|
|
507
|
+
* const textContent = Buffer.from('This is a sample document', 'utf8');
|
|
508
|
+
* const uploadResult = await storage.PutObject(
|
|
509
|
+
* 'documents/sample.txt',
|
|
510
|
+
* textContent,
|
|
511
|
+
* 'text/plain'
|
|
512
|
+
* );
|
|
513
|
+
*
|
|
514
|
+
* // Upload a large file using chunked upload
|
|
515
|
+
* const largeFileBuffer = fs.readFileSync('/path/to/large-presentation.pptx');
|
|
516
|
+
* const largeUploadResult = await storage.PutObject(
|
|
517
|
+
* 'presentations/quarterly-results.pptx',
|
|
518
|
+
* largeFileBuffer,
|
|
519
|
+
* 'application/vnd.openxmlformats-officedocument.presentationml.presentation'
|
|
520
|
+
* );
|
|
521
|
+
*
|
|
522
|
+
* if (largeUploadResult) {
|
|
523
|
+
* console.log('Large file uploaded successfully');
|
|
524
|
+
* } else {
|
|
525
|
+
* console.error('Failed to upload large file');
|
|
526
|
+
* }
|
|
527
|
+
* ```
|
|
79
528
|
*/
|
|
80
529
|
PutObject(objectName: string, data: Buffer, contentType?: string, metadata?: Record<string, string>): Promise<boolean>;
|
|
81
530
|
/**
|
|
82
|
-
*
|
|
531
|
+
* Copies a file from one location to another
|
|
532
|
+
*
|
|
533
|
+
* This method creates a copy of a file at a new location. The original file
|
|
534
|
+
* remains unchanged.
|
|
535
|
+
*
|
|
536
|
+
* @param sourceObjectName - Path to the source file (e.g., 'templates/report-template.docx')
|
|
537
|
+
* @param destinationObjectName - Path where the copy should be created (e.g., 'documents/new-report.docx')
|
|
538
|
+
* @returns A Promise that resolves to true if successful, false if an error occurs
|
|
539
|
+
*
|
|
540
|
+
* @remarks
|
|
541
|
+
* - Only files can be copied; folders cannot be copied with this method
|
|
542
|
+
* - Parent directories in the destination path will be created automatically if they don't exist
|
|
543
|
+
* - If a file with the same name exists at the destination, it will be replaced
|
|
544
|
+
*
|
|
545
|
+
* @example
|
|
546
|
+
* ```typescript
|
|
547
|
+
* // Copy a template file to a new location with a different name
|
|
548
|
+
* const copyResult = await storage.CopyObject(
|
|
549
|
+
* 'templates/financial-report.xlsx',
|
|
550
|
+
* 'reports/2023/q1-financial-report.xlsx'
|
|
551
|
+
* );
|
|
552
|
+
*
|
|
553
|
+
* if (copyResult) {
|
|
554
|
+
* console.log('File copied successfully');
|
|
555
|
+
* } else {
|
|
556
|
+
* console.error('Failed to copy file');
|
|
557
|
+
* }
|
|
558
|
+
* ```
|
|
83
559
|
*/
|
|
84
560
|
CopyObject(sourceObjectName: string, destinationObjectName: string): Promise<boolean>;
|
|
85
561
|
/**
|
|
86
|
-
*
|
|
562
|
+
* Checks if a file or folder exists
|
|
563
|
+
*
|
|
564
|
+
* This method verifies whether an object (file or folder) exists at the specified path.
|
|
565
|
+
*
|
|
566
|
+
* @param objectName - Path to check (e.g., 'documents/report.pdf')
|
|
567
|
+
* @returns A Promise that resolves to true if the object exists, false otherwise
|
|
568
|
+
*
|
|
569
|
+
* @example
|
|
570
|
+
* ```typescript
|
|
571
|
+
* // Check if a file exists before attempting to download it
|
|
572
|
+
* const exists = await storage.ObjectExists('presentations/quarterly-update.pptx');
|
|
573
|
+
*
|
|
574
|
+
* if (exists) {
|
|
575
|
+
* // File exists, proceed with download
|
|
576
|
+
* const fileContent = await storage.GetObject('presentations/quarterly-update.pptx');
|
|
577
|
+
* // Process the file...
|
|
578
|
+
* } else {
|
|
579
|
+
* console.log('File does not exist');
|
|
580
|
+
* }
|
|
581
|
+
* ```
|
|
87
582
|
*/
|
|
88
583
|
ObjectExists(objectName: string): Promise<boolean>;
|
|
89
584
|
/**
|
|
90
|
-
*
|
|
585
|
+
* Checks if a directory exists
|
|
586
|
+
*
|
|
587
|
+
* This method verifies whether a folder exists at the specified path.
|
|
588
|
+
* Unlike ObjectExists, this method also checks that the item is a folder.
|
|
589
|
+
*
|
|
590
|
+
* @param directoryPath - Path to check (e.g., 'documents/reports')
|
|
591
|
+
* @returns A Promise that resolves to true if the directory exists, false otherwise
|
|
592
|
+
*
|
|
593
|
+
* @remarks
|
|
594
|
+
* - Returns false if the path exists but points to a file instead of a folder
|
|
595
|
+
* - Trailing slashes in the path are automatically removed
|
|
596
|
+
*
|
|
597
|
+
* @example
|
|
598
|
+
* ```typescript
|
|
599
|
+
* // Check if a directory exists before creating a file in it
|
|
600
|
+
* const dirExists = await storage.DirectoryExists('documents/reports');
|
|
601
|
+
*
|
|
602
|
+
* if (!dirExists) {
|
|
603
|
+
* // Create the directory first
|
|
604
|
+
* await storage.CreateDirectory('documents/reports');
|
|
605
|
+
* }
|
|
606
|
+
*
|
|
607
|
+
* // Now we can safely put a file in this directory
|
|
608
|
+
* await storage.PutObject('documents/reports/annual-summary.pdf', fileContent, 'application/pdf');
|
|
609
|
+
* ```
|
|
91
610
|
*/
|
|
92
611
|
DirectoryExists(directoryPath: string): Promise<boolean>;
|
|
93
612
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"BoxFileStorage.d.ts","sourceRoot":"","sources":["../../src/drivers/BoxFileStorage.ts"],"names":[],"mappings":";AAGA,OAAO,EACL,6BAA6B,EAC7B,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACtB,MAAM,4BAA4B,CAAC;AAEpC,qBACa,cAAe,SAAQ,eAAe;IACjD,SAAS,CAAC,QAAQ,CAAC,YAAY,SAAS;IAExC,OAAO,CAAC,YAAY,CAAS;
|
|
1
|
+
{"version":3,"file":"BoxFileStorage.d.ts","sourceRoot":"","sources":["../../src/drivers/BoxFileStorage.ts"],"names":[],"mappings":"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"}
|