@memberjunction/storage 2.38.0 → 2.40.0

package/dist/drivers/BoxFileStorage.js

@@ -37,12 +37,79 @@ const global_1 = require("@memberjunction/global");
 const env = __importStar(require("env-var"));
 const mime = __importStar(require("mime-types"));
 const FileStorageBase_1 = require("../generic/FileStorageBase");
+/**
+ * FileStorageBase implementation for Box.com cloud storage
+ *
+ * This provider allows working with files stored in Box.com. It supports
+ * authentication via access token, refresh token, or client credentials (JWT).
+ *
+ * @remarks
+ * This implementation requires at least one of the following authentication methods:
+ *
+ * 1. Access Token:
+ *    - STORAGE_BOX_ACCESS_TOKEN - A valid Box API access token
+ *
+ * 2. Refresh Token:
+ *    - STORAGE_BOX_REFRESH_TOKEN - A valid Box API refresh token
+ *    - STORAGE_BOX_CLIENT_ID - Your Box application client ID
+ *    - STORAGE_BOX_CLIENT_SECRET - Your Box application client secret
+ *
+ * 3. Client Credentials (JWT):
+ *    - STORAGE_BOX_CLIENT_ID - Your Box application client ID
+ *    - STORAGE_BOX_CLIENT_SECRET - Your Box application client secret
+ *    - STORAGE_BOX_ENTERPRISE_ID - Your Box enterprise ID
+ *
+ * Optional configuration:
+ * - STORAGE_BOX_ROOT_FOLDER_ID - ID of a Box folder to use as the root (defaults to '0' which is the root)
+ *
+ * @example
+ * ```typescript
+ * // Set required environment variables for JWT auth
+ * process.env.STORAGE_BOX_CLIENT_ID = 'your-client-id';
+ * process.env.STORAGE_BOX_CLIENT_SECRET = 'your-client-secret';
+ * process.env.STORAGE_BOX_ENTERPRISE_ID = 'your-enterprise-id';
+ *
+ * // Create the provider
+ * const storage = new BoxFileStorage();
+ * await storage.initialize(); // Required for JWT auth
+ *
+ * // Upload a file
+ * const fileContent = Buffer.from('Hello, Box!');
+ * await storage.PutObject('documents/hello.txt', fileContent, 'text/plain');
+ *
+ * // Download a file
+ * const downloadedContent = await storage.GetObject('documents/hello.txt');
+ *
+ * // Get a temporary download URL
+ * const downloadUrl = await storage.CreatePreAuthDownloadUrl('documents/hello.txt');
+ * ```
+ */
 let BoxFileStorage = class BoxFileStorage extends FileStorageBase_1.FileStorageBase {
+    /**
+     * Creates a new BoxFileStorage instance
+     *
+     * This constructor reads the required Box authentication configuration
+     * from environment variables.
+     *
+     * @throws Error if refresh token is provided without client ID and secret
+     */
     constructor() {
         super();
+        /**
+         * The name of this storage provider
+         */
         this.providerName = 'Box';
+        /**
+         * Timestamp when current access token expires
+         */
         this._tokenExpiresAt = 0;
+        /**
+         * Base URL for Box API
+         */
         this._baseApiUrl = 'https://api.box.com/2.0';
+        /**
+         * Base URL for Box Upload API
+         */
         this._uploadApiUrl = 'https://upload.box.com/api/2.0';
         // Box auth can be via access token or refresh token
         this._accessToken = env.get('STORAGE_BOX_ACCESS_TOKEN').asString();
@@ -57,14 +124,36 @@ let BoxFileStorage = class BoxFileStorage extends FileStorageBase_1.FileStorageB
         this._rootFolderId = env.get('STORAGE_BOX_ROOT_FOLDER_ID').default('0').asString();
     }
     /**
-     * Initialize the storage driver by setting up the access token
-     * This should be called after construction
+     * Initializes the Box storage driver
+     *
+     * This method must be called after creating a BoxFileStorage instance
+     * when using client credentials (JWT) authentication. It obtains the
+     * initial access token required for API calls.
+     *
+     * @returns A Promise that resolves when initialization is complete
+     *
+     * @example
+     * ```typescript
+     * const storage = new BoxFileStorage();
+     * await storage.initialize();
+     * // Now the storage provider is ready to use
+     * ```
      */
     async initialize() {
         if (!this._accessToken && this._clientId && this._clientSecret && this._enterpriseId) {
             await this._setAccessToken();
         }
     }
+    /**
+     * Obtains an access token using client credentials flow
+     *
+     * This method requests a new access token using the Box client credentials
+     * flow (JWT) with the enterprise as the subject.
+     *
+     * @private
+     * @returns A Promise that resolves when the access token is obtained
+     * @throws Error if token acquisition fails
+     */
     async _setAccessToken() {
         try {
             const response = await fetch('https://api.box.com/oauth2/token', {
@@ -94,7 +183,14 @@ let BoxFileStorage = class BoxFileStorage extends FileStorageBase_1.FileStorageB
         }
     }
     /**
-     * Ensures we have a valid access token
+     * Ensures a valid access token is available for API requests
+     *
+     * This method checks if the current token is valid, and if not, attempts
+     * to refresh or obtain a new token using the configured authentication method.
+     *
+     * @private
+     * @returns A Promise that resolves to a valid access token
+     * @throws Error if no valid token can be obtained
      */
     async _ensureValidToken() {
         // If we have a valid token, use it
@@ -149,7 +245,19 @@ let BoxFileStorage = class BoxFileStorage extends FileStorageBase_1.FileStorageB
         throw new Error('No valid Box access token available and no authentication method configured');
     }
     /**
-     * Make an authenticated API request to Box
+     * Makes an authenticated API request to the Box API
+     *
+     * This helper method handles authentication, request formatting, and
+     * response parsing for all Box API calls.
+     *
+     * @private
+     * @param endpoint - The API endpoint to call (e.g., '/files/123')
+     * @param method - The HTTP method to use (default: 'GET')
+     * @param body - Optional request body (will be serialized as JSON unless it's FormData)
+     * @param headers - Optional additional headers
+     * @param baseUrl - Base URL to use (defaults to standard API URL)
+     * @returns A Promise that resolves to the API response data
+     * @throws Error if the API request fails
      */
     async _apiRequest(endpoint, method = 'GET', body, headers = {}, baseUrl = this._baseApiUrl) {
         const token = await this._ensureValidToken();
@@ -182,7 +290,14 @@ let BoxFileStorage = class BoxFileStorage extends FileStorageBase_1.FileStorageB
         return data;
     }
     /**
-     * Parse a Box API path into folder ID and name components
+     * Parses a path string into Box API components
+     *
+     * This helper method converts a standard path string (e.g., 'documents/reports/file.txt')
+     * into components used by the Box API (folder ID, name, parent path).
+     *
+     * @private
+     * @param path - The path to parse
+     * @returns An object containing the parsed components: id, name, and parent
      */
     _parsePath(path) {
         // Default to root folder
@@ -206,7 +321,15 @@ let BoxFileStorage = class BoxFileStorage extends FileStorageBase_1.FileStorageB
         return { id: '', name, parent };
     }
     /**
-     * Get item ID by path
+     * Resolves a path string to a Box item ID
+     *
+     * This helper method navigates the Box folder hierarchy to find
+     * the item at the specified path, returning its Box ID.
+     *
+     * @private
+     * @param path - The path to resolve
+     * @returns A Promise that resolves to the Box item ID
+     * @throws Error if the item does not exist
      */
     async _getIdFromPath(path) {
         const parsedPath = this._parsePath(path);
@@ -234,7 +357,15 @@ let BoxFileStorage = class BoxFileStorage extends FileStorageBase_1.FileStorageB
         return item.id;
     }
     /**
-     * Convert Box item to StorageObjectMetadata
+     * Converts a Box API item to StorageObjectMetadata
+     *
+     * This helper method transforms a Box API item representation into
+     * the standard StorageObjectMetadata format used by FileStorageBase.
+     *
+     * @private
+     * @param item - The Box API item object
+     * @param parentPath - The parent path string
+     * @returns A StorageObjectMetadata object
      */
     _convertToMetadata(item, parentPath = '') {
         const isDirectory = item.type === 'folder';
@@ -260,7 +391,42 @@ let BoxFileStorage = class BoxFileStorage extends FileStorageBase_1.FileStorageB
         };
     }
     /**
-     * Create a pre-authenticated upload URL
+     * Creates a pre-authenticated upload URL for a file
+     *
+     * This method creates a Box upload session and returns a URL that can be used
+     * to upload file content directly to Box without requiring authentication.
+     *
+     * @param objectName - Path where the file should be uploaded (e.g., 'documents/report.pdf')
+     * @returns A Promise that resolves to an object containing the upload URL and provider key
+     * @throws Error if the URL creation fails
+     *
+     * @remarks
+     * - The parent folder structure will be created automatically if it doesn't exist
+     * - The returned provider key contains the session ID needed to complete the upload
+     * - Box upload sessions expire after a certain period (typically 1 hour)
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   // Generate a pre-authenticated upload URL
+     *   const uploadInfo = await storage.CreatePreAuthUploadUrl('presentations/quarterly-results.pptx');
+     *
+     *   // The URL can be used to upload content directly
+     *   console.log(`Upload URL: ${uploadInfo.UploadUrl}`);
+     *
+     *   // Make sure to save the provider key, as it's needed to reference the upload
+     *   console.log(`Provider Key: ${uploadInfo.ProviderKey}`);
+     *
+     *   // You can use fetch or another HTTP client to upload to this URL
+     *   await fetch(uploadInfo.UploadUrl, {
+     *     method: 'PUT',
+     *     headers: { 'Content-Type': 'application/octet-stream' },
+     *     body: fileContent
+     *   });
+     * } catch (error) {
+     *   console.error('Error creating upload URL:', error.message);
+     * }
+     * ```
      */
     async CreatePreAuthUploadUrl(objectName) {
         try {
@@ -297,7 +463,34 @@ let BoxFileStorage = class BoxFileStorage extends FileStorageBase_1.FileStorageB
         }
     }
     /**
-     * Create a pre-authenticated download URL
+     * Creates a pre-authenticated download URL for a file
+     *
+     * This method generates a time-limited URL that can be used to download
+     * a file without authentication. The URL typically expires after 60 minutes.
+     *
+     * @param objectName - Path to the file to download (e.g., 'documents/report.pdf')
+     * @returns A Promise that resolves to the download URL string
+     * @throws Error if the file doesn't exist or URL creation fails
+     *
+     * @remarks
+     * - Cannot be used with upload sessions that haven't been completed
+     * - Box download URLs typically expire after 60 minutes
+     * - Generated URLs can be shared with users who don't have Box access
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   // Generate a pre-authenticated download URL
+     *   const downloadUrl = await storage.CreatePreAuthDownloadUrl('documents/financial-report.pdf');
+     *
+     *   console.log(`Download the file using this URL: ${downloadUrl}`);
+     *
+     *   // The URL can be shared or used in a browser to download the file
+     *   // without requiring Box authentication
+     * } catch (error) {
+     *   console.error('Error creating download URL:', error.message);
+     * }
+     * ```
      */
     async CreatePreAuthDownloadUrl(objectName) {
         try {
@@ -320,7 +513,34 @@ let BoxFileStorage = class BoxFileStorage extends FileStorageBase_1.FileStorageB
         }
     }
     /**
-     * Move an object
+     * Moves a file or folder from one location to another
+     *
+     * This method moves a file or folder to a new location in Box storage.
+     * It handles both renaming and changing the parent folder.
+     *
+     * @param oldObjectName - Current path of the object (e.g., 'old-folder/document.docx')
+     * @param newObjectName - New path for the object (e.g., 'new-folder/renamed-document.docx')
+     * @returns A Promise that resolves to true if successful, false otherwise
+     *
+     * @remarks
+     * - Parent folders will be created automatically if they don't exist
+     * - Works with both files and folders
+     * - For folders, all contents will move with the folder
+     *
+     * @example
+     * ```typescript
+     * // Move a file to a different folder and rename it
+     * const moveResult = await storage.MoveObject(
+     *   'documents/old-report.pdf',
+     *   'archive/2023/annual-report.pdf'
+     * );
+     *
+     * if (moveResult) {
+     *   console.log('File moved successfully');
+     * } else {
+     *   console.error('Failed to move file');
+     * }
+     * ```
      */
     async MoveObject(oldObjectName, newObjectName) {
         try {
@@ -354,7 +574,34 @@ let BoxFileStorage = class BoxFileStorage extends FileStorageBase_1.FileStorageB
         }
     }
     /**
-     * Delete an object
+     * Deletes a file or folder from Box storage
+     *
+     * This method permanently deletes a file or folder. It can also
+     * handle special cases like incomplete upload sessions.
+     *
+     * @param objectName - Path to the object to delete (e.g., 'documents/old-report.docx')
+     * @returns A Promise that resolves to true if successful, false if an error occurs
+     *
+     * @remarks
+     * - Returns true if the object doesn't exist (for idempotency)
+     * - Can handle special provider keys like upload sessions
+     * - Box puts deleted items in the trash, where they can be recovered for a limited time
+     * - To permanently delete folder contents, use DeleteDirectory with recursive=true
+     *
+     * @example
+     * ```typescript
+     * // Delete a file
+     * const deleteResult = await storage.DeleteObject('temp/draft-document.docx');
+     *
+     * if (deleteResult) {
+     *   console.log('File deleted successfully or already didn\'t exist');
+     * } else {
+     *   console.error('Failed to delete file');
+     * }
+     *
+     * // Delete an upload session
+     * await storage.DeleteObject('session:1234567890:documents/large-file.zip');
+     * ```
      */
     async DeleteObject(objectName) {
         try {
@@ -381,7 +628,38 @@ let BoxFileStorage = class BoxFileStorage extends FileStorageBase_1.FileStorageB
         }
     }
     /**
-     * List objects in a directory
+     * Lists files and folders in a given directory
+     *
+     * This method retrieves all files and subfolders in the specified directory.
+     * It returns both a list of object metadata and a list of directory prefixes.
+     *
+     * @param prefix - Path to the directory to list (e.g., 'documents/reports')
+     * @param delimiter - Optional delimiter character (default: '/')
+     * @returns A Promise that resolves to a StorageListResult containing objects and prefixes
+     *
+     * @remarks
+     * - The `objects` array includes both files and folders
+     * - The `prefixes` array includes only folder paths (with trailing slashes)
+     * - Returns empty arrays if the directory doesn't exist
+     * - The delimiter parameter is included for interface compatibility but not used internally
+     *
+     * @example
+     * ```typescript
+     * // List all files and folders in the 'documents' directory
+     * const result = await storage.ListObjects('documents');
+     *
+     * // Process files and folders
+     * console.log(`Found ${result.objects.length} items:`);
+     * for (const obj of result.objects) {
+     *   console.log(`- ${obj.name} (${obj.isDirectory ? 'Folder' : 'File'}, ${obj.size} bytes)`);
+     * }
+     *
+     * // List subfolders only
+     * console.log(`Found ${result.prefixes.length} subfolders:`);
+     * for (const prefix of result.prefixes) {
+     *   console.log(`- ${prefix}`);
+     * }
+     * ```
      */
     async ListObjects(prefix, delimiter = '/') {
         try {
@@ -418,7 +696,37 @@ let BoxFileStorage = class BoxFileStorage extends FileStorageBase_1.FileStorageB
         }
     }
     /**
-     * Create a directory
+     * Creates a new directory (folder) in Box storage
+     *
+     * This method creates a folder at the specified path, automatically
+     * creating any parent folders that don't exist.
+     *
+     * @param directoryPath - Path where the directory should be created (e.g., 'documents/reports/2023')
+     * @returns A Promise that resolves to true if successful, false if an error occurs
+     *
+     * @remarks
+     * - Creates parent directories recursively if they don't exist
+     * - Returns true if the directory already exists (idempotent operation)
+     * - Trailing slashes in the path are automatically removed
+     *
+     * @example
+     * ```typescript
+     * // Create a nested directory structure
+     * const createResult = await storage.CreateDirectory('documents/reports/2023/Q1');
+     *
+     * if (createResult) {
+     *   console.log('Directory created successfully');
+     *
+     *   // Now we can put files in this directory
+     *   await storage.PutObject(
+     *     'documents/reports/2023/Q1/financial-summary.xlsx',
+     *     fileContent,
+     *     'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
+     *   );
+     * } else {
+     *   console.error('Failed to create directory');
+     * }
+     * ```
      */
     async CreateDirectory(directoryPath) {
         try {
@@ -460,7 +768,35 @@ let BoxFileStorage = class BoxFileStorage extends FileStorageBase_1.FileStorageB
         }
     }
     /**
-     * Delete a directory
+     * Deletes a directory from Box storage
+     *
+     * This method deletes a folder and optionally its contents. By default,
+     * it will only delete empty folders unless recursive is set to true.
+     *
+     * @param directoryPath - Path to the directory to delete (e.g., 'documents/old-reports')
+     * @param recursive - If true, delete the directory and all its contents; if false, only delete if empty
+     * @returns A Promise that resolves to true if successful, false if an error occurs
+     *
+     * @remarks
+     * - Returns true if the directory doesn't exist (idempotent operation)
+     * - If recursive=false and the directory contains files, the operation will fail
+     * - Box puts deleted folders in the trash, where they can be recovered for a limited time
+     * - Trailing slashes in the path are automatically removed
+     *
+     * @example
+     * ```typescript
+     * // Try to delete an empty folder
+     * const deleteResult = await storage.DeleteDirectory('temp/empty-folder');
+     *
+     * // Delete a folder and all its contents
+     * const recursiveDeleteResult = await storage.DeleteDirectory('archive/old-data', true);
+     *
+     * if (recursiveDeleteResult) {
+     *   console.log('Folder and all its contents deleted successfully');
+     * } else {
+     *   console.error('Failed to delete folder');
+     * }
+     * ```
      */
     async DeleteDirectory(directoryPath, recursive = false) {
         try {
@@ -502,7 +838,34 @@ let BoxFileStorage = class BoxFileStorage extends FileStorageBase_1.FileStorageB
         }
     }
     /**
-     * Get object metadata
+     * Gets metadata for a file or folder
+     *
+     * This method retrieves metadata about a file or folder in Box storage,
+     * such as size, type, and modification date.
+     *
+     * @param objectName - Path to the object to get metadata for (e.g., 'documents/report.pdf')
+     * @returns A Promise that resolves to a StorageObjectMetadata object
+     * @throws Error if the object doesn't exist or cannot be accessed
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   // Get metadata for a file
+     *   const metadata = await storage.GetObjectMetadata('presentations/quarterly-update.pptx');
+     *
+     *   console.log(`Name: ${metadata.name}`);
+     *   console.log(`Path: ${metadata.path}`);
+     *   console.log(`Size: ${metadata.size} bytes`);
+     *   console.log(`Content Type: ${metadata.contentType}`);
+     *   console.log(`Last Modified: ${metadata.lastModified}`);
+     *   console.log(`Is Directory: ${metadata.isDirectory}`);
+     *
+     *   // Box-specific metadata is available in customMetadata
+     *   console.log(`Box ID: ${metadata.customMetadata.id}`);
+     * } catch (error) {
+     *   console.error('Error getting metadata:', error.message);
+     * }
+     * ```
      */
     async GetObjectMetadata(objectName) {
         try {
@@ -524,7 +887,35 @@ let BoxFileStorage = class BoxFileStorage extends FileStorageBase_1.FileStorageB
         }
     }
     /**
-     * Get an object's contents
+     * Downloads a file's contents
+     *
+     * This method retrieves the raw content of a file as a Buffer.
+     *
+     * @param objectName - Path to the file to download (e.g., 'documents/report.pdf')
+     * @returns A Promise that resolves to a Buffer containing the file's contents
+     * @throws Error if the file doesn't exist or cannot be downloaded
+     *
+     * @remarks
+     * - This method will throw an error if the object is a folder
+     * - For large files, consider using CreatePreAuthDownloadUrl instead
+     * - For upload sessions that haven't been completed, this method will fail
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   // Download a text file
+     *   const fileContent = await storage.GetObject('documents/notes.txt');
+     *
+     *   // Convert Buffer to string for text files
+     *   const textContent = fileContent.toString('utf8');
+     *   console.log('File content:', textContent);
+     *
+     *   // For binary files, you can write the buffer to disk
+     *   // or process it as needed
+     * } catch (error) {
+     *   console.error('Error downloading file:', error.message);
+     * }
+     * ```
      */
     async GetObject(objectName) {
         try {
@@ -541,7 +932,47 @@ let BoxFileStorage = class BoxFileStorage extends FileStorageBase_1.FileStorageB
         }
     }
     /**
-     * Upload an object
+     * Uploads a file to Box storage
+     *
+     * This method uploads a file to the specified path in Box storage. It automatically
+     * determines whether to use a simple upload or chunked upload based on file size.
+     *
+     * @param objectName - Path where the file should be uploaded (e.g., 'documents/report.pdf')
+     * @param data - Buffer containing the file content
+     * @param contentType - Optional MIME type of the file (if not provided, it will be guessed from the filename)
+     * @param metadata - Optional metadata to associate with the file (not used in Box implementation)
+     * @returns A Promise that resolves to true if successful, false if an error occurs
+     *
+     * @remarks
+     * - Automatically creates parent directories if they don't exist
+     * - Files smaller than 50MB use a simple upload
+     * - Files 50MB or larger use a chunked upload process
+     * - If a file with the same name exists, it will be replaced
+     *
+     * @example
+     * ```typescript
+     * // Create a simple text file
+     * const textContent = Buffer.from('This is a sample document', 'utf8');
+     * const uploadResult = await storage.PutObject(
+     *   'documents/sample.txt',
+     *   textContent,
+     *   'text/plain'
+     * );
+     *
+     * // Upload a large file using chunked upload
+     * const largeFileBuffer = fs.readFileSync('/path/to/large-presentation.pptx');
+     * const largeUploadResult = await storage.PutObject(
+     *   'presentations/quarterly-results.pptx',
+     *   largeFileBuffer,
+     *   'application/vnd.openxmlformats-officedocument.presentationml.presentation'
+     * );
+     *
+     * if (largeUploadResult) {
+     *   console.log('Large file uploaded successfully');
+     * } else {
+     *   console.error('Failed to upload large file');
+     * }
+     * ```
      */
     async PutObject(objectName, data, contentType, metadata) {
         try {
@@ -625,7 +1056,34 @@ let BoxFileStorage = class BoxFileStorage extends FileStorageBase_1.FileStorageB
         }
     }
     /**
-     * Copy an object
+     * Copies a file from one location to another
+     *
+     * This method creates a copy of a file at a new location. The original file
+     * remains unchanged.
+     *
+     * @param sourceObjectName - Path to the source file (e.g., 'templates/report-template.docx')
+     * @param destinationObjectName - Path where the copy should be created (e.g., 'documents/new-report.docx')
+     * @returns A Promise that resolves to true if successful, false if an error occurs
+     *
+     * @remarks
+     * - Only files can be copied; folders cannot be copied with this method
+     * - Parent directories in the destination path will be created automatically if they don't exist
+     * - If a file with the same name exists at the destination, it will be replaced
+     *
+     * @example
+     * ```typescript
+     * // Copy a template file to a new location with a different name
+     * const copyResult = await storage.CopyObject(
+     *   'templates/financial-report.xlsx',
+     *   'reports/2023/q1-financial-report.xlsx'
+     * );
+     *
+     * if (copyResult) {
+     *   console.log('File copied successfully');
+     * } else {
+     *   console.error('Failed to copy file');
+     * }
+     * ```
      */
     async CopyObject(sourceObjectName, destinationObjectName) {
         try {
@@ -661,7 +1119,26 @@ let BoxFileStorage = class BoxFileStorage extends FileStorageBase_1.FileStorageB
         }
     }
     /**
-     * Check if an object exists
+     * Checks if a file or folder exists
+     *
+     * This method verifies whether an object (file or folder) exists at the specified path.
+     *
+     * @param objectName - Path to check (e.g., 'documents/report.pdf')
+     * @returns A Promise that resolves to true if the object exists, false otherwise
+     *
+     * @example
+     * ```typescript
+     * // Check if a file exists before attempting to download it
+     * const exists = await storage.ObjectExists('presentations/quarterly-update.pptx');
+     *
+     * if (exists) {
+     *   // File exists, proceed with download
+     *   const fileContent = await storage.GetObject('presentations/quarterly-update.pptx');
+     *   // Process the file...
+     * } else {
+     *   console.log('File does not exist');
+     * }
+     * ```
      */
     async ObjectExists(objectName) {
         try {
@@ -673,7 +1150,31 @@ let BoxFileStorage = class BoxFileStorage extends FileStorageBase_1.FileStorageB
         }
     }
     /**
-     * Check if a directory exists
+     * Checks if a directory exists
+     *
+     * This method verifies whether a folder exists at the specified path.
+     * Unlike ObjectExists, this method also checks that the item is a folder.
+     *
+     * @param directoryPath - Path to check (e.g., 'documents/reports')
+     * @returns A Promise that resolves to true if the directory exists, false otherwise
+     *
+     * @remarks
+     * - Returns false if the path exists but points to a file instead of a folder
+     * - Trailing slashes in the path are automatically removed
+     *
+     * @example
+     * ```typescript
+     * // Check if a directory exists before creating a file in it
+     * const dirExists = await storage.DirectoryExists('documents/reports');
+     *
+     * if (!dirExists) {
+     *   // Create the directory first
+     *   await storage.CreateDirectory('documents/reports');
+     * }
+     *
+     * // Now we can safely put a file in this directory
+     * await storage.PutObject('documents/reports/annual-summary.pdf', fileContent, 'application/pdf');
+     * ```
      */
     async DirectoryExists(directoryPath) {
         try {