@memberjunction/storage 2.38.0 → 2.40.0

package/dist/drivers/AzureFileStorage.d.ts

@@ -1,33 +1,393 @@
 /// <reference types="node" />
 import { CreatePreAuthUploadUrlPayload, FileStorageBase, StorageListResult, StorageObjectMetadata } from '../generic/FileStorageBase';
+/**
+ * Azure Blob Storage implementation of the FileStorageBase interface.
+ *
+ * This class provides methods for interacting with Azure Blob Storage as a file storage provider.
+ * It implements all the abstract methods defined in FileStorageBase and handles Azure-specific
+ * authentication, authorization, and file operations.
+ *
+ * It requires the following environment variables to be set:
+ * - STORAGE_AZURE_CONTAINER: The name of the Azure Storage container
+ * - STORAGE_AZURE_ACCOUNT_NAME: The Azure Storage account name
+ * - STORAGE_AZURE_ACCOUNT_KEY: The Azure Storage account key
+ *
+ * @example
+ * ```typescript
+ * // Create an instance of AzureFileStorage
+ * const azureStorage = new AzureFileStorage();
+ *
+ * // Generate a pre-authenticated upload URL
+ * const { UploadUrl } = await azureStorage.CreatePreAuthUploadUrl('documents/report.pdf');
+ *
+ * // Generate a pre-authenticated download URL
+ * const downloadUrl = await azureStorage.CreatePreAuthDownloadUrl('documents/report.pdf');
+ *
+ * // List files in a directory
+ * const files = await azureStorage.ListObjects('documents/');
+ * ```
+ */
 export declare class AzureFileStorage extends FileStorageBase {
+    /** The name of this storage provider, used in error messages */
     protected readonly providerName = "Azure Blob Storage";
+    /** Azure Storage SharedKeyCredential for authentication */
     private _sharedKeyCredential;
+    /** The Azure Storage container name */
     private _container;
+    /** The Azure Storage account name */
     private _accountName;
+    /** ContainerClient for the specified container */
     private _containerClient;
+    /** BlobServiceClient for the Azure Storage account */
     private _blobServiceClient;
+    /**
+     * Creates a new instance of AzureFileStorage.
+     *
+     * Initializes the connection to Azure Blob Storage using environment variables.
+     * Throws an error if any required environment variables are missing.
+     */
     constructor();
     /**
-     * Creates a BlobClient for the specified object
+     * Creates a BlobClient for the specified object.
+     *
+     * This is a helper method used internally to get a BlobClient instance
+     * for a specific blob (file) in the container.
+     *
+     * @param objectName - The name of the blob for which to create a client
+     * @returns A BlobClient instance for the specified blob
+     * @private
      */
     private _getBlobClient;
     /**
-     * Normalize directory path to ensure it ends with a slash
+     * Normalizes a directory path to ensure it ends with a slash.
+     *
+     * This is a helper method used internally to ensure consistency in
+     * directory path representation. Azure Blob Storage doesn't have actual
+     * directories, so we use a trailing slash to simulate them.
+     *
+     * @param path - The directory path to normalize
+     * @returns The normalized path with a trailing slash
+     * @private
      */
     private _normalizeDirectoryPath;
+    /**
+     * Creates a pre-authenticated upload URL for a blob in Azure Blob Storage.
+     *
+     * This method generates a Shared Access Signature (SAS) URL that allows
+     * for uploading a blob without needing the Azure Storage account credentials.
+     * The URL is valid for 10 minutes and can only be used for writing the specified blob.
+     *
+     * @param objectName - The name of the blob to upload (including any path/directory)
+     * @returns A Promise resolving to an object with the upload URL
+     *
+     * @example
+     * ```typescript
+     * // Generate a pre-authenticated upload URL for a PDF file
+     * const { UploadUrl } = await azureStorage.CreatePreAuthUploadUrl('documents/report.pdf');
+     *
+     * // The URL can be used with tools like curl to upload the file
+     * // curl -H "x-ms-blob-type: BlockBlob" --upload-file report.pdf --url "https://accountname.blob.core.windows.net/container/documents/report.pdf?sastoken"
+     * console.log(UploadUrl);
+     * ```
+     */
     CreatePreAuthUploadUrl(objectName: string): Promise<CreatePreAuthUploadUrlPayload>;
+    /**
+     * Creates a pre-authenticated download URL for a blob in Azure Blob Storage.
+     *
+     * This method generates a Shared Access Signature (SAS) URL that allows
+     * for downloading a blob without needing the Azure Storage account credentials.
+     * The URL is valid for 10 minutes and can only be used for reading the specified blob.
+     *
+     * @param objectName - The name of the blob to download (including any path/directory)
+     * @returns A Promise resolving to the download URL
+     *
+     * @example
+     * ```typescript
+     * // Generate a pre-authenticated download URL for a PDF file
+     * const downloadUrl = await azureStorage.CreatePreAuthDownloadUrl('documents/report.pdf');
+     *
+     * // The URL can be shared with users or used in applications for direct download
+     * console.log(downloadUrl);
+     * ```
+     */
     CreatePreAuthDownloadUrl(objectName: string): Promise<string>;
+    /**
+     * Moves a blob from one location to another within Azure Blob Storage.
+     *
+     * Since Azure Blob Storage doesn't provide a native move operation,
+     * this method implements move as a copy followed by a delete operation.
+     * It first copies the blob to the new location, and if successful,
+     * deletes the blob from the original location.
+     *
+     * @param oldObjectName - The current name/path of the blob
+     * @param newObjectName - The new name/path for the blob
+     * @returns A Promise resolving to a boolean indicating success
+     *
+     * @example
+     * ```typescript
+     * // Move a file from drafts to published folder
+     * const success = await azureStorage.MoveObject(
+     *   'drafts/report.docx',
+     *   'published/final-report.docx'
+     * );
+     *
+     * if (success) {
+     *   console.log('File successfully moved');
+     * } else {
+     *   console.log('Failed to move file');
+     * }
+     * ```
+     */
     MoveObject(oldObjectName: string, newObjectName: string): Promise<boolean>;
+    /**
+     * Deletes a blob from Azure Blob Storage.
+     *
+     * This method attempts to delete the specified blob if it exists.
+     * It returns true if the blob was successfully deleted or if it didn't exist.
+     *
+     * @param objectName - The name of the blob to delete (including any path/directory)
+     * @returns A Promise resolving to a boolean indicating success
+     *
+     * @example
+     * ```typescript
+     * // Delete a temporary file
+     * const deleted = await azureStorage.DeleteObject('temp/report-draft.pdf');
+     *
+     * if (deleted) {
+     *   console.log('File successfully deleted');
+     * } else {
+     *   console.log('Failed to delete file');
+     * }
+     * ```
+     */
     DeleteObject(objectName: string): Promise<boolean>;
+    /**
+     * Lists blobs with the specified prefix in Azure Blob Storage.
+     *
+     * This method returns a list of blobs (files) and virtual directories under the
+     * specified path prefix. Since Azure Blob Storage doesn't have actual directories,
+     * this method simulates directory structure by looking at blob names with common
+     * prefixes and using the delimiter to identify "directory" paths.
+     *
+     * @param prefix - The path prefix to list blobs from (e.g., 'documents/')
+     * @param delimiter - The character used to simulate directory structure, defaults to '/'
+     * @returns A Promise resolving to a StorageListResult containing objects and prefixes
+     *
+     * @example
+     * ```typescript
+     * // List all files and directories in the documents folder
+     * const result = await azureStorage.ListObjects('documents/');
+     *
+     * // Process files
+     * for (const file of result.objects) {
+     *   console.log(`File: ${file.name}, Size: ${file.size}, Type: ${file.contentType}`);
+     * }
+     *
+     * // Process subdirectories
+     * for (const dir of result.prefixes) {
+     *   console.log(`Directory: ${dir}`);
+     * }
+     * ```
+     */
     ListObjects(prefix: string, delimiter?: string): Promise<StorageListResult>;
+    /**
+     * Creates a directory (virtual) in Azure Blob Storage.
+     *
+     * Since Azure Blob Storage doesn't have a native directory concept,
+     * this method creates a zero-byte blob with a trailing slash to
+     * simulate a directory. The blob has a special content type to
+     * indicate it's a directory.
+     *
+     * @param directoryPath - The path of the directory to create
+     * @returns A Promise resolving to a boolean indicating success
+     *
+     * @example
+     * ```typescript
+     * // Create a new directory structure
+     * const created = await azureStorage.CreateDirectory('documents/reports/annual/');
+     *
+     * if (created) {
+     *   console.log('Directory created successfully');
+     * } else {
+     *   console.log('Failed to create directory');
+     * }
+     * ```
+     */
     CreateDirectory(directoryPath: string): Promise<boolean>;
+    /**
+     * Deletes a directory (virtual) and optionally its contents from Azure Blob Storage.
+     *
+     * For non-recursive deletion, this method simply deletes the directory placeholder blob.
+     * For recursive deletion, it lists all blobs with the directory path as prefix
+     * and deletes them all, including the directory placeholder.
+     *
+     * @param directoryPath - The path of the directory to delete
+     * @param recursive - If true, deletes all contents recursively (default: false)
+     * @returns A Promise resolving to a boolean indicating success
+     *
+     * @example
+     * ```typescript
+     * // Delete an empty directory
+     * const deleted = await azureStorage.DeleteDirectory('documents/temp/');
+     *
+     * // Delete a directory and all its contents
+     * const recursivelyDeleted = await azureStorage.DeleteDirectory('documents/old_projects/', true);
+     * ```
+     */
     DeleteDirectory(directoryPath: string, recursive?: boolean): Promise<boolean>;
+    /**
+     * Retrieves metadata for a specific blob in Azure Blob Storage.
+     *
+     * This method fetches the properties of a blob without downloading its content,
+     * which is more efficient for checking file attributes like size, content type,
+     * and last modified date.
+     *
+     * @param objectName - The name of the blob to get metadata for
+     * @returns A Promise resolving to a StorageObjectMetadata object
+     * @throws Error if the blob doesn't exist or cannot be accessed
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const metadata = await azureStorage.GetObjectMetadata('documents/report.pdf');
+     *   console.log(`File: ${metadata.name}`);
+     *   console.log(`Size: ${metadata.size} bytes`);
+     *   console.log(`Last modified: ${metadata.lastModified}`);
+     * } catch (error) {
+     *   console.error('File does not exist or cannot be accessed');
+     * }
+     * ```
+     */
     GetObjectMetadata(objectName: string): Promise<StorageObjectMetadata>;
+    /**
+     * Downloads a blob's content from Azure Blob Storage.
+     *
+     * This method retrieves the full content of a blob and returns it as a Buffer
+     * for processing in memory.
+     *
+     * @param objectName - The name of the blob to download
+     * @returns A Promise resolving to a Buffer containing the blob's data
+     * @throws Error if the blob doesn't exist or cannot be downloaded
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const content = await azureStorage.GetObject('documents/config.json');
+     *   // Parse the JSON content
+     *   const config = JSON.parse(content.toString('utf8'));
+     *   console.log('Configuration loaded:', config);
+     * } catch (error) {
+     *   console.error('Failed to download file:', error.message);
+     * }
+     * ```
+     */
     GetObject(objectName: string): Promise<Buffer>;
+    /**
+     * Uploads data to a blob in Azure Blob Storage.
+     *
+     * This method directly uploads a Buffer of data to a blob with the specified name.
+     * It's useful for server-side operations where you already have the data in memory.
+     *
+     * @param objectName - The name to assign to the uploaded blob
+     * @param data - The Buffer containing the data to upload
+     * @param contentType - Optional MIME type for the blob (inferred from name if not provided)
+     * @param metadata - Optional key-value pairs of custom metadata to associate with the blob
+     * @returns A Promise resolving to a boolean indicating success
+     *
+     * @example
+     * ```typescript
+     * // Upload a text file
+     * const content = Buffer.from('Hello, World!', 'utf8');
+     * const uploaded = await azureStorage.PutObject(
+     *   'documents/hello.txt',
+     *   content,
+     *   'text/plain',
+     *   { author: 'John Doe', department: 'Engineering' }
+     * );
+     *
+     * if (uploaded) {
+     *   console.log('File uploaded successfully');
+     * } else {
+     *   console.log('Failed to upload file');
+     * }
+     * ```
+     */
     PutObject(objectName: string, data: Buffer, contentType?: string, metadata?: Record<string, string>): Promise<boolean>;
+    /**
+     * Copies a blob within Azure Blob Storage.
+     *
+     * This method creates a copy of a blob at a new location without removing the original.
+     * It uses a SAS URL to provide the source blob access for the copy operation.
+     *
+     * @param sourceObjectName - The name of the blob to copy
+     * @param destinationObjectName - The name to assign to the copied blob
+     * @returns A Promise resolving to a boolean indicating success
+     *
+     * @example
+     * ```typescript
+     * // Create a backup copy of an important file
+     * const copied = await azureStorage.CopyObject(
+     *   'documents/contract.pdf',
+     *   'backups/contract_2024-05-16.pdf'
+     * );
+     *
+     * if (copied) {
+     *   console.log('File copied successfully');
+     * } else {
+     *   console.log('Failed to copy file');
+     * }
+     * ```
+     */
     CopyObject(sourceObjectName: string, destinationObjectName: string): Promise<boolean>;
+    /**
+     * Checks if a blob exists in Azure Blob Storage.
+     *
+     * This method verifies the existence of a blob without downloading its content,
+     * which is efficient for validation purposes.
+     *
+     * @param objectName - The name of the blob to check
+     * @returns A Promise resolving to a boolean indicating if the blob exists
+     *
+     * @example
+     * ```typescript
+     * // Check if a file exists before attempting to use it
+     * const exists = await azureStorage.ObjectExists('documents/report.pdf');
+     *
+     * if (exists) {
+     *   console.log('File exists, proceeding with download');
+     *   const content = await azureStorage.GetObject('documents/report.pdf');
+     *   // Process the content...
+     * } else {
+     *   console.log('File does not exist');
+     * }
+     * ```
+     */
     ObjectExists(objectName: string): Promise<boolean>;
+    /**
+     * Checks if a directory (virtual) exists in Azure Blob Storage.
+     *
+     * Since Azure Blob Storage doesn't have a native directory concept,
+     * this method checks for either:
+     * 1. The existence of a directory placeholder blob (zero-byte blob with trailing slash)
+     * 2. The existence of any blobs with the directory path as a prefix
+     *
+     * @param directoryPath - The path of the directory to check
+     * @returns A Promise resolving to a boolean indicating if the directory exists
+     *
+     * @example
+     * ```typescript
+     * // Check if a directory exists before trying to save files to it
+     * const exists = await azureStorage.DirectoryExists('documents/reports/');
+     *
+     * if (!exists) {
+     *   console.log('Directory does not exist, creating it first');
+     *   await azureStorage.CreateDirectory('documents/reports/');
+     * }
+     *
+     * // Now safe to use the directory
+     * await azureStorage.PutObject('documents/reports/new-report.pdf', fileData);
+     * ```
+     */
     DirectoryExists(directoryPath: string): Promise<boolean>;
 }
 //# sourceMappingURL=AzureFileStorage.d.ts.map

package/dist/drivers/AzureFileStorage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AzureFileStorage.d.ts","sourceRoot":"","sources":["../../src/drivers/AzureFileStorage.ts"],"names":[],"mappings":";AAiBA,OAAO,EACL,6BAA6B,EAC7B,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACtB,MAAM,4BAA4B,CAAC;AAEpC,qBACa,gBAAiB,SAAQ,eAAe;IACnD,SAAS,CAAC,QAAQ,CAAC,YAAY,wBAAwB;IACvD,OAAO,CAAC,oBAAoB,CAA6B;IACzD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,gBAAgB,CAAkB;IAC1C,OAAO,CAAC,kBAAkB,CAAoB;;IAoB9C;;OAEG;IACH,OAAO,CAAC,cAAc;IAItB;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAIxB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,6BAA6B,CAAC;IAqBlF,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAkBvD,UAAU,CAAC,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAe1E,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAYlD,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,SAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA6DxE,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAsBxD,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,UAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAiC3E,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IA4BrE,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA2B9C,SAAS,CACpB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,MAAM,EACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,OAAO,CAAC,OAAO,CAAC;IAwBN,UAAU,CAAC,gBAAgB,EAAE,MAAM,EAAE,qBAAqB,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAwBrF,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAWlD,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CA2BtE"}
+{"version":3,"file":"AzureFileStorage.d.ts","sourceRoot":"","sources":["../../src/drivers/AzureFileStorage.ts"],"names":[],"mappings":";AAiBA,OAAO,EACL,6BAA6B,EAC7B,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACtB,MAAM,4BAA4B,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBACa,gBAAiB,SAAQ,eAAe;IACnD,gEAAgE;IAChE,SAAS,CAAC,QAAQ,CAAC,YAAY,wBAAwB;IAEvD,2DAA2D;IAC3D,OAAO,CAAC,oBAAoB,CAA6B;IAEzD,uCAAuC;IACvC,OAAO,CAAC,UAAU,CAAS;IAE3B,qCAAqC;IACrC,OAAO,CAAC,YAAY,CAAS;IAE7B,kDAAkD;IAClD,OAAO,CAAC,gBAAgB,CAAkB;IAE1C,sDAAsD;IACtD,OAAO,CAAC,kBAAkB,CAAoB;IAE9C;;;;;OAKG;;IAmBH;;;;;;;;;OASG;IACH,OAAO,CAAC,cAAc;IAItB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,uBAAuB;IAI/B;;;;;;;;;;;;;;;;;;;OAmBG;IACI,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,6BAA6B,CAAC;IAqBzF;;;;;;;;;;;;;;;;;;OAkBG;IACI,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAkBpE;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACU,UAAU,CAAC,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAevF;;;;;;;;;;;;;;;;;;;;OAoBG;IACU,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAY/D;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACU,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,SAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA6DrF;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACU,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAsBrE;;;;;;;;;;;;;;;;;;;OAmBG;IACU,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,UAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAiCxF;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACU,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IA4BlF;;;;;;;;;;;;;;;;;;;;;OAqBG;IACU,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA2B3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACU,SAAS,CACpB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,MAAM,EACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,OAAO,CAAC,OAAO,CAAC;IAwBnB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACU,UAAU,CAAC,gBAAgB,EAAE,MAAM,EAAE,qBAAqB,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAwBlG;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACU,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAW/D;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACU,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CA2BtE"}