Class BoxFileStorage

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

Checks if Box provider is properly configured. Returns true if client credentials are present.

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.

Example

// Get a valid Box access token
const token = await storage.AccessToken();
console.log(`Using access token: ${token}`);
Copy

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.

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

// 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');
}
Copy

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.

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

// 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');
}
Copy

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.

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

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);
}
Copy

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.

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

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);
}
Copy

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.

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

// 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');
}
Copy

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.

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

// 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');
Copy

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.

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

// 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');
Copy

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.

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

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);
}
Copy

Downloads a file's contents

This method retrieves the raw content of a file as a Buffer.

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

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);
}
Copy

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.

Throws

Error if the object doesn't exist or cannot be accessed

Example

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);
}
Copy

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.

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

// 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}`);
}
Copy

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.

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

// 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');
}
Copy

Checks if a file or folder exists

This method verifies whether an object (file or folder) exists at the specified path.

Example

// 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');
}
Copy

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.

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

// 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');
}
Copy

Search files in Box using Box Search API.

This method provides full-text search capabilities across file names and content using Box's native search functionality. It supports filtering by file type, date ranges, and path prefixes.

Remarks

• Box searches both file names and content by default
• The searchContent option is provided for interface compatibility but doesn't restrict Box's behavior
• File types can be specified as extensions or MIME types
• Date filters use Box's created_at_range parameter
• Path prefix is implemented by filtering results to ancestor folder IDs
• Results are sorted by relevance when available

Example

// Search for PDF files containing "quarterly report"
const results = await storage.SearchFiles('quarterly report', {
  fileTypes: ['pdf'],
  pathPrefix: 'documents/reports',
  modifiedAfter: new Date('2023-01-01'),
  maxResults: 50
});

console.log(`Found ${results.results.length} matching files`);
for (const file of results.results) {
  console.log(`- ${file.path} (${file.size} bytes, score: ${file.relevance})`);
  if (file.excerpt) {
    console.log(`  Excerpt: ${file.excerpt}`);
  }
}
Copy

Initializes the Box storage driver

This method must be called after creating a BoxFileStorage instance. It initializes the Box SDK and creates the client for API calls.

Example

const storage = new BoxFileStorage();
await storage.initialize();
// Now the storage provider is ready to use
Copy