@memberjunction/storage 2.39.0 → 2.41.0

package/dist/drivers/BoxFileStorage.js

@@ -31,18 +31,90 @@ var __importStar = (this && this.__importStar) || function (mod) {
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BoxFileStorage = void 0;
 const global_1 = require("@memberjunction/global");
 const env = __importStar(require("env-var"));
 const mime = __importStar(require("mime-types"));
 const FileStorageBase_1 = require("../generic/FileStorageBase");
+const box_node_sdk_1 = __importDefault(require("box-node-sdk"));
+const https = __importStar(require("https"));
+/**
+ * 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 +129,53 @@ 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();
         }
+        await this._setClient();
+    }
+    /**
+     * Initializes the Box client instance
+     *
+     * This method creates a new Box SDK client using the current credentials
+     * and access token, making it ready for API operations.
+     *
+     * @private
+     * @returns A Promise that resolves when the client is initialized
+     */
+    async _setClient() {
+        const sdk = await new box_node_sdk_1.default({
+            clientID: this._clientId,
+            clientSecret: this._clientSecret
+        });
+        this._client = await sdk.getBasicClient(this._accessToken);
     }
+    /**
+     * 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 +205,55 @@ let BoxFileStorage = class BoxFileStorage extends FileStorageBase_1.FileStorageB
         }
     }
     /**
-     * Ensures we have a valid access token
+     * Returns the current Box API access token
+     *
+     * This method ensures a valid token is available before returning it,
+     * refreshing or generating a new token if necessary.
+     *
+     * @returns A Promise that resolves to a valid access token string
+     *
+     * @example
+     * ```typescript
+     * // Get a valid Box access token
+     * const token = await storage.AccessToken();
+     * console.log(`Using access token: ${token}`);
+     * ```
+     */
+    async AccessToken() {
+        await this._ensureValidToken();
+        return this._accessToken;
+    }
+    /**
+     * Returns the current Box client instance
+     *
+     * This method ensures a valid token is available before returning the client,
+     * refreshing or generating a new token if necessary.
+     *
+     * @returns A Promise that resolves to the authenticated Box client instance
+     *
+     * @example
+     * ```typescript
+     * // Get the Box client for direct API access
+     * const client = await storage.BoxClient();
+     *
+     * // Use the client for Box SDK operations
+     * const user = await client.users.get('me');
+     * console.log(`Current user: ${user.name}`);
+     * ```
+     */
+    async BoxClient() {
+        await this._ensureValidToken();
+        return this._client;
+    }
+    /**
+     * 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
@@ -123,6 +282,7 @@ let BoxFileStorage = class BoxFileStorage extends FileStorageBase_1.FileStorageB
                 this._accessToken = data.access_token;
                 this._refreshToken = data.refresh_token || this._refreshToken;
                 this._tokenExpiresAt = Date.now() + (data.expires_in * 1000) - 60000; // Subtract 1 minute for safety
+                await this._setClient();
                 return this._accessToken;
             }
             catch (error) {
@@ -134,6 +294,7 @@ let BoxFileStorage = class BoxFileStorage extends FileStorageBase_1.FileStorageB
         if (this._clientId && this._clientSecret && this._enterpriseId) {
             try {
                 await this._setAccessToken();
+                await this._setClient();
                 return this._accessToken;
             }
             catch (error) {
@@ -149,7 +310,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 +355,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,35 +386,73 @@ 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);
-        // If we already have the ID, return it
-        if (parsedPath.id) {
-            return parsedPath.id;
-        }
-        // If it's the root, return the root folder ID
-        if (!parsedPath.name) {
-            return this._rootFolderId;
-        }
-        // Get the parent folder ID
-        let parentId = this._rootFolderId;
-        if (parsedPath.parent) {
-            parentId = await this._getIdFromPath(parsedPath.parent);
-        }
-        // Search for the item in the parent folder
-        const result = await this._apiRequest(`/folders/${parentId}/items`, 'GET', null, {
-            'fields': 'id,name,type'
-        });
-        const item = result.entries.find(entry => entry.name === parsedPath.name);
-        if (!item) {
-            throw new Error(`Item not found: ${path}`);
+        try {
+            // Parse the path
+            const parsedPath = this._parsePath(path);
+            // If the id is already in the path, return it
+            if (parsedPath.id) {
+                return parsedPath.id;
+            }
+            // If it's root, return root folder id
+            if (!parsedPath.name) {
+                return this._rootFolderId;
+            }
+            // First, find the parent folder ID
+            let parentFolderId = this._rootFolderId;
+            if (parsedPath.parent) {
+                parentFolderId = await this._findFolderIdByPath(parsedPath.parent);
+            }
+            // Search for the item with pagination support
+            let offset = 0;
+            let hasMoreItems = true;
+            const LIMIT = 1000;
+            while (hasMoreItems) {
+                await this._ensureValidToken();
+                const items = await this._client.folders.getItems(parentFolderId, {
+                    fields: 'name,type,id',
+                    limit: LIMIT,
+                    offset: offset
+                });
+                // Look for the item by name
+                const item = items.entries.find((i) => i.name === parsedPath.name);
+                if (item) {
+                    return item.id;
+                }
+                // Update pagination variables
+                offset += items.entries.length;
+                // Check if we've processed all items
+                hasMoreItems = items.entries.length === LIMIT && offset < items.total_count;
+            }
+            // If we get here, the item was not found
+            console.log(`Item not found: ${parsedPath.name}`);
+            return null;
+        }
+        catch (error) {
+            console.error('Error in _getIdFromPath', { path, error });
+            return null;
         }
-        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 +478,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 +550,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 +600,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 +661,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 +715,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,49 +783,228 @@ 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 {
+            // Root directory always exists
+            if (!directoryPath || directoryPath === '/' || directoryPath === '') {
+                return true;
+            }
             // Remove trailing slash if present
             const normalizedPath = directoryPath.endsWith('/')
                 ? directoryPath.substring(0, directoryPath.length - 1)
                 : directoryPath;
-            // Check if directory already exists
+            // First check if directory already exists
             try {
-                await this._getIdFromPath(normalizedPath);
-                return true; // Directory already exists
+                if (await this.DirectoryExists(normalizedPath)) {
+                    return true;
+                }
             }
             catch (error) {
-                // Directory doesn't exist, create it
+                // Ignore error, we'll try to create it anyway
             }
-            // Get parent folder info
-            const parsedPath = this._parsePath(normalizedPath);
-            let parentId = this._rootFolderId;
-            if (parsedPath.parent) {
+            // Parse the path to get parent folder and name
+            const lastSlashIndex = normalizedPath.lastIndexOf('/');
+            const parentPath = lastSlashIndex > 0 ? normalizedPath.substring(0, lastSlashIndex) : '';
+            const folderName = lastSlashIndex > 0 ? normalizedPath.substring(lastSlashIndex + 1) : normalizedPath;
+            // Make sure parent folder exists
+            let parentFolderId = '0'; // Default to root
+            if (parentPath) {
                 try {
-                    parentId = await this._getIdFromPath(parsedPath.parent);
+                    // Recursive call to ensure parent directory exists
+                    const parentDirExists = await this.CreateDirectory(parentPath);
+                    if (!parentDirExists) {
+                        console.log(`Failed to create parent directory: ${parentPath}`);
+                        return false;
+                    }
+                    // Get the parent folder ID
+                    parentFolderId = await this._findFolderIdByPath(parentPath);
                 }
                 catch (error) {
-                    // Create parent directory recursively
-                    await this.CreateDirectory(parsedPath.parent);
-                    parentId = await this._getIdFromPath(parsedPath.parent);
+                    console.error(`Error ensuring parent folder exists: ${error.message}`);
+                    return false;
                 }
             }
             // Create the folder
-            await this._apiRequest('/folders', 'POST', {
-                name: parsedPath.name,
-                parent: { id: parentId }
-            });
-            return true;
+            try {
+                await this._ensureValidToken();
+                await this._client.folders.create(parentFolderId, folderName);
+                console.log(`✅ Folder created successfully: ${normalizedPath}`);
+                return true;
+            }
+            catch (error) {
+                // Handle conflicts - if the folder already exists, that's a success
+                if (error.statusCode === 409 ||
+                    (error.message && error.message.includes('item_name_in_use'))) {
+                    console.log(`Folder already exists (conflict): ${normalizedPath}`);
+                    return true;
+                }
+                console.error(`Error creating folder: ${error.message || JSON.stringify(error)}`);
+                return false;
+            }
         }
         catch (error) {
             console.error('Error creating directory', { directoryPath, error });
             return false;
         }
     }
+    ;
+    /**
+     * Gets file representation information for a Box file
+     *
+     * This method retrieves information about available representations
+     * (such as thumbnails, previews, or other formats) for a specific file.
+     *
+     * @param fileId - The Box file ID to get representations for
+     * @param repHints - The representation hints string (format and options)
+     * @returns A Promise that resolves to a JSON object containing representations data
+     * @throws Error if the request fails
+     *
+     * @remarks
+     * - Requires a valid file ID (not a path)
+     * - The repHints parameter controls what type of representations are returned
+     * - Common representation types include thumbnails, preview images, and text extractions
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   // Get a high-resolution PNG representation of a file
+     *   const fileId = '12345';
+     *   const representations = await storage.GetFileRepresentations(
+     *     fileId,
+     *     'png?dimensions=2048x2048'
+     *   );
+     *
+     *   // Process the representation information
+     *   console.log('Available representations:', representations);
+     * } catch (error) {
+     *   console.error('Error getting representations:', error.message);
+     * }
+     * ```
+     */
+    async GetFileRepresentations(fileId, repHints = 'png?dimensions=2048x2048') {
+        try {
+            await this._ensureValidToken();
+            // Set up the request options with X-Rep-Hints header
+            const options = {
+                hostname: 'api.box.com',
+                port: 443,
+                path: `/2.0/files/${fileId}?fields=representations`,
+                method: 'GET',
+                headers: {
+                    'Authorization': `Bearer ${this._accessToken}`,
+                    'Content-Type': 'application/json',
+                    'X-Rep-Hints': repHints
+                }
+            };
+            // Make the request using our existing makeRequest function
+            const responseData = await this._makeRequest(options);
+            return JSON.parse(responseData);
+        }
+        catch (error) {
+            console.error('Error getting file representations:', error);
+            throw error;
+        }
+    }
+    ;
     /**
-     * Delete a directory
+     * Helper function for making HTTP requests
+     *
+     * This method provides a Promise-based wrapper around Node.js https requests,
+     * simplifying the process of making API calls to the Box API.
+     *
+     * @private
+     * @param options - The HTTPS request options (URL, method, headers, etc.)
+     * @param data - Optional string data to send with the request
+     * @returns A Promise that resolves to the response data as a string
+     * @throws Error if the request fails or returns a non-2xx status code
+     */
+    async _makeRequest(options, data) {
+        return new Promise((resolve, reject) => {
+            const req = https.request(options, (res) => {
+                let responseData = '';
+                res.on('data', (chunk) => {
+                    responseData += chunk;
+                });
+                res.on('end', () => {
+                    if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
+                        resolve(responseData);
+                    }
+                    else {
+                        reject(new Error(`Request failed with status code ${res.statusCode}: ${responseData}`));
+                    }
+                });
+            });
+            req.on('error', (error) => {
+                reject(error);
+            });
+            if (data) {
+                req.write(data);
+            }
+            req.end();
+        });
+    }
+    /**
+     * 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 +1046,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,108 +1095,235 @@ 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 {
-            const fileId = await this._getIdFromPath(objectName);
-            // Download the file
-            const response = await this._apiRequest(`/files/${fileId}/content`, 'GET');
-            // Convert response to buffer
-            const arrayBuffer = await response.arrayBuffer();
-            return Buffer.from(arrayBuffer);
+            // Extract directory path and filename
+            const lastSlashIndex = objectName.lastIndexOf('/');
+            if (lastSlashIndex === -1) {
+                throw new Error('Invalid path format, expected directory/filename');
+            }
+            const directoryPath = objectName.substring(0, lastSlashIndex);
+            const fileName = objectName.substring(lastSlashIndex + 1);
+            // Find folder ID for the directory using the approach from check_file.ts
+            try {
+                const folderId = await this._findFolderIdByPath(directoryPath);
+                // Use pagination to handle large folders
+                let file = null;
+                let offset = 0;
+                let hasMoreItems = true;
+                const LIMIT = 1000;
+                while (hasMoreItems && !file) {
+                    await this._ensureValidToken();
+                    const folderItems = await this._client.folders.getItems(folderId, {
+                        fields: 'name,type,size,created_at,modified_at',
+                        limit: LIMIT,
+                        offset: offset
+                    });
+                    // Look for the file
+                    file = folderItems.entries.find((item) => item.type === 'file' && item.name === fileName);
+                    // If file is found, break out of pagination loop
+                    if (file) {
+                        break;
+                    }
+                    // Update pagination variables
+                    offset += folderItems.entries.length;
+                    // Check if we've processed all items
+                    hasMoreItems = folderItems.entries.length === LIMIT && offset < folderItems.total_count;
+                }
+                if (file) {
+                    console.log(`✅ File found: ${file.name} (${file.id})`);
+                    // Use the file ID to get the content
+                    await this._ensureValidToken();
+                    const stream = await this._client.files.getReadStream(file.id);
+                    // Convert stream to buffer
+                    return new Promise((resolve, reject) => {
+                        const chunks = [];
+                        stream.on('data', (chunk) => chunks.push(chunk));
+                        stream.on('error', reject);
+                        stream.on('end', () => resolve(Buffer.concat(chunks)));
+                    });
+                }
+                else {
+                    console.log(`❌ File not found in directory`);
+                    throw new Error(`File not found: ${fileName}`);
+                }
+            }
+            catch (error) {
+                console.log(`❌ Error finding file: ${error}`);
+                throw error;
+            }
         }
         catch (error) {
             console.error('Error getting object', { objectName, error });
             throw new Error(`Failed to get object: ${objectName}`);
         }
     }
+    ;
     /**
-     * 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 {
+            console.log(`PutObject: ${objectName}`);
             // Get the parent folder ID and file name
             const parsedPath = this._parsePath(objectName);
             let parentId = this._rootFolderId;
             if (parsedPath.parent) {
                 try {
-                    parentId = await this._getIdFromPath(parsedPath.parent);
+                    // First ensure the parent directory exists (create it if needed)
+                    const parentDirExists = await this.CreateDirectory(parsedPath.parent);
+                    if (!parentDirExists) {
+                        console.error(`Failed to ensure parent directory exists: ${parsedPath.parent}`);
+                        return false;
+                    }
+                    // Find folder ID using our improved path resolution from check_file.ts
+                    parentId = await this._findFolderIdByPath(parsedPath.parent);
                 }
                 catch (error) {
-                    // If parent folder doesn't exist, create it recursively
-                    await this.CreateDirectory(parsedPath.parent);
-                    parentId = await this._getIdFromPath(parsedPath.parent);
+                    console.error(`Error resolving parent folder: ${error.message}`);
+                    return false;
                 }
             }
             // Check if file already exists
-            let fileId = null;
-            try {
-                fileId = await this._getIdFromPath(objectName);
+            const fileId = await this._getIdFromPath(objectName);
+            if (fileId) {
+                console.log(`File already exists with ID: ${fileId}`);
             }
-            catch (error) {
-                // File doesn't exist, will create new
-            }
-            // Use multipart upload for small files (<50MB)
-            if (data.length < 50 * 1024 * 1024) {
-                const formData = new FormData();
-                // Add file metadata
-                const fileMetadata = {
-                    name: parsedPath.name,
-                    parent: { id: parentId }
-                };
-                formData.append('attributes', JSON.stringify(fileMetadata));
-                // Create a file blob with the correct content type
-                const fileBlob = new Blob([data], { type: contentType || 'application/octet-stream' });
-                formData.append('file', fileBlob, parsedPath.name);
-                // Upload the file
-                const endpoint = fileId ? `/files/${fileId}/content` : '/files/content';
+            else {
+                console.log(`File doesn't exist yet, will create new file: ${parsedPath.name}`);
+            }
+            const formData = new FormData();
+            // Add file metadata
+            const fileMetadata = {
+                name: parsedPath.name,
+                parent: { id: parentId }
+            };
+            formData.append('attributes', JSON.stringify(fileMetadata));
+            // Create a file blob with the correct content type
+            const fileBlob = new Blob([data], { type: contentType || 'application/octet-stream' });
+            formData.append('file', fileBlob, parsedPath.name);
+            // Upload the file
+            const endpoint = fileId ? `/files/${fileId}/content` : '/files/content';
+            console.log(`Uploading file using endpoint: ${endpoint}`);
+            try {
                 await this._apiRequest(endpoint, 'POST', formData, {}, this._uploadApiUrl);
+                console.log(`✅ File uploaded successfully: ${objectName}`);
+                return true;
             }
-            else {
-                // Use chunked upload for larger files
-                // Create upload session
-                const session = await this._apiRequest('/files/upload_sessions', 'POST', {
-                    folder_id: parentId,
-                    file_name: parsedPath.name,
-                    file_size: data.length
-                }, {}, this._uploadApiUrl);
-                const sessionId = session.id;
-                const CHUNK_SIZE = 8 * 1024 * 1024; // 8MB chunks
-                let offset = 0;
-                const totalSize = data.length;
-                const parts = [];
-                // Upload chunks
-                while (offset < totalSize) {
-                    const chunkEnd = Math.min(offset + CHUNK_SIZE, totalSize);
-                    const chunkSize = chunkEnd - offset;
-                    const chunk = data.slice(offset, chunkEnd);
-                    const headers = {
-                        'Content-Type': 'application/octet-stream',
-                        'Digest': `sha=1234`, // Replace with actual SHA-1 digest
-                        'Content-Range': `bytes ${offset}-${chunkEnd - 1}/${totalSize}`
-                    };
-                    const uploadResponse = await this._apiRequest(`/files/upload_sessions/${sessionId}`, 'PUT', chunk, headers, this._uploadApiUrl);
-                    parts.push({
-                        part_id: uploadResponse.part.part_id,
-                        offset,
-                        size: chunkSize,
-                        sha1: uploadResponse.part.sha1
-                    });
-                    offset = chunkEnd;
+            catch (uploadError) {
+                console.error(`Error uploading file: ${uploadError.message}`);
+                if (uploadError.message.includes('item_name_in_use')) {
+                    console.log(`File already exists (conflict): ${objectName}`);
+                    return false;
                 }
-                // Commit the upload session
-                await this._apiRequest(`/files/upload_sessions/${sessionId}/commit`, 'POST', { parts }, { 'Content-Type': 'application/json' }, this._uploadApiUrl);
+                return false;
             }
-            return true;
         }
         catch (error) {
             console.error('Error putting object', { objectName, error });
             return false;
         }
     }
+    ;
     /**
-     * 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 +1359,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,22 +1390,130 @@ 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 {
+            // Root directory always exists
+            if (!directoryPath || directoryPath === '/' || directoryPath === '') {
+                return true;
+            }
             // Remove trailing slash if present
             const normalizedPath = directoryPath.endsWith('/')
                 ? directoryPath.substring(0, directoryPath.length - 1)
                 : directoryPath;
-            const itemId = await this._getIdFromPath(normalizedPath);
-            const itemInfo = await this._apiRequest(`/folders/${itemId}`);
-            return itemInfo.type === 'folder';
+            try {
+                const folderId = await this._findFolderIdByPath(normalizedPath);
+                console.log(`✅ Directory ${normalizedPath} exists with ID: ${folderId}`);
+                // Make a direct call to verify it's a folder
+                try {
+                    await this._ensureValidToken();
+                    await this._client.folders.get(folderId);
+                    return true;
+                }
+                catch (error) {
+                    // If we can't get the folder info, it's not a valid folder
+                    console.log(`Item with ID ${folderId} exists but is not a folder`);
+                    return false;
+                }
+            }
+            catch (error) {
+                console.log(`❌ Directory ${normalizedPath} does not exist`);
+                return false;
+            }
         }
         catch (error) {
+            console.error('Error checking directory exists', { directoryPath, error });
             return false;
         }
     }
+    /**
+     * Finds a Box folder ID by traversing a path string
+     *
+     * This helper method navigates through the Box folder hierarchy,
+     * following each segment of the path to find the ID of the target folder.
+     * It uses pagination to handle large folders efficiently.
+     *
+     * @private
+     * @param path - The path string to resolve (e.g., 'documents/reports/2023')
+     * @returns A Promise that resolves to the Box folder ID
+     * @throws Error if any segment of the path cannot be found
+     */
+    async _findFolderIdByPath(path) {
+        try {
+            // Split the path into segments
+            const pathSegments = path.split('/').filter(segment => segment.length > 0);
+            // Handle "All Files" special case - it's not an actual folder name in the API
+            if (pathSegments.length > 0 && pathSegments[0] === 'All Files') {
+                pathSegments.shift(); // Remove "All Files" from the path
+            }
+            let currentFolderId = '0'; // Start from root
+            if (pathSegments.length === 0) {
+                return currentFolderId; // Return root folder ID if path is empty
+            }
+            // Traverse the path
+            for (const segment of pathSegments) {
+                // Use pagination to handle large folders
+                let folder = null;
+                let offset = 0;
+                let hasMoreItems = true;
+                const LIMIT = 1000;
+                while (hasMoreItems && !folder) {
+                    await this._ensureValidToken();
+                    const items = await this._client.folders.getItems(currentFolderId, {
+                        fields: 'name,type',
+                        limit: LIMIT,
+                        offset: offset
+                    });
+                    // Filter to only folders
+                    const folders = items.entries.filter((item) => item.type === 'folder');
+                    // Look for the target folder
+                    folder = folders.find((item) => item.name === segment);
+                    // If folder is found, break out of pagination loop
+                    if (folder) {
+                        break;
+                    }
+                    // Update pagination variables
+                    offset += items.entries.length;
+                    // Check if we've processed all items
+                    hasMoreItems = items.entries.length === LIMIT && offset < items.total_count;
+                }
+                if (!folder) {
+                    throw new Error(`Folder not found: ${segment}`);
+                }
+                currentFolderId = folder.id;
+            }
+            return currentFolderId;
+        }
+        catch (error) {
+            console.error('Error finding folder by path:', error);
+            throw error;
+        }
+    }
 };
 exports.BoxFileStorage = BoxFileStorage;
 exports.BoxFileStorage = BoxFileStorage = __decorate([