Class SharePointFileStorage

Creates a new SharePointFileStorage instance

This constructor reads required configuration from environment variables and initializes the Microsoft Graph client.

Throws

Error if required environment variables are missing

Checks if SharePoint provider is properly configured. Returns true if all required Microsoft Graph credentials are present.

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

• The parent folder of the destination must exist
• Both files and folders can be copied
• The operation is asynchronous in SharePoint and may not complete immediately

Example

// Copy a file to a new location with a different name
const copyResult = await storage.CopyObject(
  'templates/financial-report.xlsx',
  'reports/2024/q1-financial-report.xlsx'
);

if (copyResult) {
  console.log('File copied successfully');
} else {
  console.error('Failed to copy file');
}
Copy

Creates a directory (folder) in SharePoint

This method creates a new folder at the specified path. The parent directory must already exist.

Remarks

• If a folder with the same name already exists, the operation will fail
• The parent directory must exist for the operation to succeed
• Trailing slashes in the path are automatically removed

Example

// Create a new folder
const createResult = await storage.CreateDirectory('documents/2024-reports');

if (createResult) {
  console.log('Folder created successfully');
  
  // Now we can put files in this folder
  await storage.PutObject(
    'documents/2024-reports/q1-results.xlsx',
    fileContent,
    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
  );
} else {
  console.error('Failed to create folder');
}
Copy

Creates a pre-authenticated download URL for an object

This method generates a time-limited, publicly accessible URL that can be used to download a file without authentication. The URL expires after 10 minutes.

Throws

Error if the object doesn't exist or the URL creation fails

Example

// Generate a pre-authenticated download URL that will work for 10 minutes
const downloadUrl = await storage.CreatePreAuthDownloadUrl('presentations/quarterly-update.pptx');
console.log(`Download the file using this URL: ${downloadUrl}`);

// You can share this URL with users who don't have SharePoint access
// The URL will expire after 10 minutes
Copy

Creates a pre-authenticated upload URL (not supported in SharePoint)

This method is not supported for SharePoint storage as SharePoint doesn't provide a way to generate pre-authenticated upload URLs like object storage services. Instead, use the PutObject method for file uploads.

Throws

UnsupportedOperationError always, as this operation is not supported

Example

// This will throw an UnsupportedOperationError
try {
  await storage.CreatePreAuthUploadUrl('documents/report.docx');
} catch (error) {
  if (error instanceof UnsupportedOperationError) {
    console.log('Pre-authenticated upload URLs are not supported in SharePoint.');
    // Use PutObject instead
    await storage.PutObject('documents/report.docx', fileContent, 'application/vnd.openxmlformats-officedocument.wordprocessingml.document');
  }
}
Copy

Deletes a directory (folder) and optionally its contents

This method deletes a folder from SharePoint. By default, it will only delete empty folders unless the recursive parameter is set to true.

Remarks

• If recursive=false and the directory contains files, the operation will fail
• SharePoint deleted items may be recoverable from the recycle bin depending on site settings
• Trailing slashes in the path are automatically removed

Example

// Attempt 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 an object (file) from SharePoint

This method permanently deletes a file from SharePoint storage. Note that deleted files may be recoverable from the SharePoint recycle bin depending on your SharePoint configuration.

Remarks

• Returns true if the object doesn't exist (for idempotency)
• Handles 404 errors by returning true since the end result is the same

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

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 uses the Graph API's download URL to retrieve the file contents
• The method will throw an error if the object is a folder
• For large files, consider using CreatePreAuthDownloadUrl instead

Example

try {
  // Fast path: Use objectId (SharePoint item ID)
  const fileContent = await storage.GetObject({ objectId: '01BYE5RZ6QN3VYRVNHHFDK2QJODWDDFR4E' });

  // Slow path: Use path
  const fileContent2 = await storage.GetObject({ fullPath: '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 a local file
  // 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 information about a file or folder, such as its name, size, content type, and last modified date.

Throws

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

Example

try {
  // Fast path: Use objectId (SharePoint item ID)
  const metadata = await storage.GetObjectMetadata({ objectId: '01BYE5RZ6QN3VYRVNHHFDK2QJODWDDFR4E' });

  // Slow path: Use path
  const metadata2 = await storage.GetObjectMetadata({ fullPath: 'presentations/quarterly-update.pptx' });

  console.log(`Name: ${metadata.name}`);
  console.log(`Size: ${metadata.size} bytes`);
  console.log(`Content Type: ${metadata.contentType}`);
  console.log(`Last Modified: ${metadata.lastModified}`);
  console.log(`Is Directory: ${metadata.isDirectory}`);
} catch (error) {
  console.error('Error getting metadata:', error.message);
}
Copy

Lists objects in a given directory (folder)

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 in the result includes both files and folders
• The prefixes array includes only folder paths (with trailing slashes)
• Returns empty arrays if the directory doesn't exist or an error occurs

Example

// List all files and folders in the 'documents' directory
const result = await storage.ListObjects('documents');

// Process files
for (const obj of result.objects) {
  console.log(`Name: ${obj.name}, Size: ${obj.size}, Type: ${obj.isDirectory ? 'Folder' : 'File'}`);
}

// Process subfolders
for (const prefix of result.prefixes) {
  console.log(`Subfolder: ${prefix}`);
}
Copy

Moves an object from one location to another

This method moves a file or folder from one location in SharePoint to another. It handles both renaming and changing the parent folder.

Example

// Move a file to a different folder
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 SharePoint

This method uploads a file to SharePoint at the specified path. It automatically determines whether to use a simple upload or a chunked upload based on file size.

Remarks

• Files smaller than 4MB use a simple upload
• Files 4MB or larger use a chunked upload session for better reliability
• Automatically creates the parent folder structure if it doesn't exist
• If a file with the same name exists, it will be replaced

Example

// Create a 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 SharePoint using Microsoft Graph Search API.

This method provides powerful search capabilities using KQL (Keyword Query Language), SharePoint's native query language. The search can target file names, metadata, and optionally file contents.

Remarks

KQL Query Syntax Examples:

• Simple text: "quarterly report" - searches for files containing these terms
• Boolean operators: "budget AND 2024", "draft OR final", "report NOT internal"
• Wildcards: "proj*" matches "project", "projection", etc.
• Property filters: "FileType:pdf", "Author:John Smith", "Size>1000000"
• Date filters: "Created>=2024-01-01", "LastModifiedTime<2024-12-31"
• Proximity: "project NEAR report" - finds terms near each other
• Exact phrases: "\"annual budget report\"" - exact phrase match

Additional Filtering: The method automatically adds KQL filters based on the provided options:

• fileTypes: Adds FileType filters (e.g., FileType:pdf OR FileType:docx)
• modifiedAfter/modifiedBefore: Adds LastModifiedTime filters
• pathPrefix: Adds Path filter to restrict search to a directory
• searchContent: When false, restricts search to filename only

Example

// Simple text search in filenames
const results = await storage.SearchFiles('quarterly report', {
  maxResults: 20
});

// Search for PDFs only
const pdfResults = await storage.SearchFiles('budget', {
  fileTypes: ['pdf'],
  maxResults: 50
});

// Search with date range
const recentResults = await storage.SearchFiles('meeting notes', {
  modifiedAfter: new Date('2024-01-01'),
  modifiedBefore: new Date('2024-12-31'),
  searchContent: true
});

// Search within specific directory
const folderResults = await storage.SearchFiles('presentation', {
  pathPrefix: 'documents/reports',
  fileTypes: ['pptx', 'pdf']
});

// Advanced KQL query
const advancedResults = await storage.SearchFiles(
  'FileType:xlsx AND Created>=2024-01-01 AND Author:"John Smith"',
  { maxResults: 100 }
);
Copy