@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.
Files changed (38) hide show
  1. package/dist/drivers/AWSFileStorage.d.ts +360 -4
  2. package/dist/drivers/AWSFileStorage.d.ts.map +1 -1
  3. package/dist/drivers/AWSFileStorage.js +357 -4
  4. package/dist/drivers/AWSFileStorage.js.map +1 -1
  5. package/dist/drivers/AzureFileStorage.d.ts +362 -2
  6. package/dist/drivers/AzureFileStorage.d.ts.map +1 -1
  7. package/dist/drivers/AzureFileStorage.js +357 -2
  8. package/dist/drivers/AzureFileStorage.js.map +1 -1
  9. package/dist/drivers/BoxFileStorage.d.ts +539 -20
  10. package/dist/drivers/BoxFileStorage.d.ts.map +1 -1
  11. package/dist/drivers/BoxFileStorage.js +521 -20
  12. package/dist/drivers/BoxFileStorage.js.map +1 -1
  13. package/dist/drivers/DropboxFileStorage.d.ts +437 -15
  14. package/dist/drivers/DropboxFileStorage.d.ts.map +1 -1
  15. package/dist/drivers/DropboxFileStorage.js +431 -15
  16. package/dist/drivers/DropboxFileStorage.js.map +1 -1
  17. package/dist/drivers/GoogleDriveFileStorage.d.ts +342 -16
  18. package/dist/drivers/GoogleDriveFileStorage.d.ts.map +1 -1
  19. package/dist/drivers/GoogleDriveFileStorage.js +340 -16
  20. package/dist/drivers/GoogleDriveFileStorage.js.map +1 -1
  21. package/dist/drivers/GoogleFileStorage.d.ts +358 -2
  22. package/dist/drivers/GoogleFileStorage.d.ts.map +1 -1
  23. package/dist/drivers/GoogleFileStorage.js +356 -2
  24. package/dist/drivers/GoogleFileStorage.js.map +1 -1
  25. package/dist/drivers/SharePointFileStorage.d.ts +434 -20
  26. package/dist/drivers/SharePointFileStorage.d.ts.map +1 -1
  27. package/dist/drivers/SharePointFileStorage.js +453 -22
  28. package/dist/drivers/SharePointFileStorage.js.map +1 -1
  29. package/dist/generic/FileStorageBase.d.ts +326 -108
  30. package/dist/generic/FileStorageBase.d.ts.map +1 -1
  31. package/dist/generic/FileStorageBase.js +54 -6
  32. package/dist/generic/FileStorageBase.js.map +1 -1
  33. package/dist/util.d.ts +125 -18
  34. package/dist/util.d.ts.map +1 -1
  35. package/dist/util.js +125 -18
  36. package/dist/util.js.map +1 -1
  37. package/package.json +4 -4
  38. 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
- * Initialize the storage driver by setting up the access token
17
- * This should be called after construction
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 we have a valid access token
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
- * Make an authenticated API request to Box
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
- * Parse a Box API path into folder ID and name components
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
- * Get item ID by path
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
- * Convert Box item to StorageObjectMetadata
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
- * Create a pre-authenticated upload URL
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
- * Create a pre-authenticated download URL
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
- * Move an object
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
- * Delete an object
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
- * List objects in a directory
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
- * Create a directory
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
- * Delete a directory
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
- * Get object metadata
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
- * Get an object's contents
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
- * Upload an object
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
- * Copy an object
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
- * Check if an object exists
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
- * Check if a directory exists
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;IAC7B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,eAAe,CAAa;IACpC,OAAO,CAAC,WAAW,CAAqC;IACxD,OAAO,CAAC,aAAa,CAA4C;IACjE,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,aAAa,CAAS;;IAoB9B;;;OAGG;IACU,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;YAM1B,eAAe;IA+B7B;;OAEG;YACW,iBAAiB;IA0D/B;;OAEG;YACW,WAAW;IA6CzB;;OAEG;IACH,OAAO,CAAC,UAAU;IA0BlB;;OAEG;YACW,cAAc;IAgC5B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA0B1B;;OAEG;IACU,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,6BAA6B,CAAC;IAoC/F;;OAEG;IACU,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAwB1E;;OAEG;IACU,UAAU,CAAC,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAkCvF;;OAEG;IACU,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA4B/D;;OAEG;IACU,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,SAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAuCrF;;OAEG;IACU,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA0CrE;;OAEG;IACU,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,UAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IA4CxF;;OAEG;IACU,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAuBlF;;OAEG;IACU,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAgB3D;;OAEG;IACU,SAAS,CACpB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,MAAM,EACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,OAAO,CAAC,OAAO,CAAC;IAyGnB;;OAEG;IACU,UAAU,CAAC,gBAAgB,EAAE,MAAM,EAAE,qBAAqB,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAqClG;;OAEG;IACU,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAS/D;;OAEG;IACU,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAetE"}
1
+ {"version":3,"file":"BoxFileStorage.d.ts","sourceRoot":"","sources":["../../src/drivers/BoxFileStorage.ts"],"names":[],"mappings":"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"}