@memberjunction/storage 2.38.0 → 2.40.0

package/dist/drivers/GoogleDriveFileStorage.d.ts

@@ -1,72 +1,398 @@
 /// <reference types="node" />
 import { CreatePreAuthUploadUrlPayload, FileStorageBase, StorageListResult, StorageObjectMetadata } from '../generic/FileStorageBase';
+/**
+ * Google Drive implementation of the FileStorageBase interface.
+ *
+ * This class provides methods for interacting with Google Drive as a file storage provider.
+ * It implements most of the abstract methods defined in FileStorageBase and handles
+ * Google Drive-specific authentication, authorization, and file operations.
+ *
+ * Unlike other storage providers like S3 or Azure, Google Drive has native concepts of
+ * folders and files with hierarchical paths, which makes some operations more natural
+ * while others (like pre-authenticated upload URLs) are not directly supported.
+ *
+ * It requires one of the following environment variables to be set:
+ * - STORAGE_GDRIVE_KEY_FILE: Path to a service account key file with Drive permissions
+ * - STORAGE_GDRIVE_CREDENTIALS_JSON: A JSON object containing service account credentials
+ *
+ * Optionally, you can set:
+ * - STORAGE_GDRIVE_ROOT_FOLDER_ID: ID of a folder to use as the root (for isolation)
+ *
+ * @example
+ * ```typescript
+ * // Create an instance of GoogleDriveFileStorage
+ * const driveStorage = new GoogleDriveFileStorage();
+ *
+ * // Generate a pre-authenticated download URL
+ * const downloadUrl = await driveStorage.CreatePreAuthDownloadUrl('documents/report.pdf');
+ *
+ * // List files in a directory
+ * const files = await driveStorage.ListObjects('documents/');
+ *
+ * // Upload a file directly
+ * const uploaded = await driveStorage.PutObject('documents/report.pdf', fileData);
+ * ```
+ */
 export declare class GoogleDriveFileStorage extends FileStorageBase {
+    /** The name of this storage provider, used in error messages */
     protected readonly providerName = "Google Drive";
+    /** The Google Drive API client */
     private _drive;
+    /** Optional root folder ID to restrict operations to a specific folder */
     private _rootFolderId?;
+    /**
+     * Creates a new instance of GoogleDriveFileStorage.
+     *
+     * Initializes the connection to Google Drive using either a service account
+     * key file or credentials provided directly in environment variables.
+     * Throws an error if neither authentication method is properly configured.
+     */
     constructor();
     /**
-     * Finds a file or folder by path
+     * Finds a file or folder by path.
+     *
+     * This helper method navigates the Google Drive folder structure to find
+     * a file or folder at the specified path. It starts from the root (or the
+     * configured root folder) and traverses the path components one by one.
+     *
+     * @param path - The path to the file or folder to find
+     * @returns A Promise resolving to the Google Drive file object
+     * @throws Error if the path cannot be found
+     * @private
      */
     private _getItemByPath;
     /**
-     * Finds a parent folder by path and creates it if it doesn't exist
+     * Finds a parent folder by path and creates it if it doesn't exist.
+     *
+     * This helper method is used to ensure a folder path exists before
+     * creating or moving files. It navigates through each path component,
+     * creating folders as needed if they don't exist yet.
+     *
+     * @param path - The path to the folder to find or create
+     * @returns A Promise resolving to the ID of the folder
+     * @private
      */
     private _getOrCreateParentFolder;
     /**
-     * Helper method to convert Google Drive file to StorageObjectMetadata
+     * Helper method to convert Google Drive file objects to StorageObjectMetadata.
+     *
+     * This method transforms the Google Drive API's file representation into
+     * the standardized StorageObjectMetadata format used by the FileStorageBase
+     * interface. It handles special properties like folder detection and paths.
+     *
+     * @param file - The Google Drive file object to convert
+     * @param parentPath - The parent path to use for constructing the full path
+     * @returns A StorageObjectMetadata representation of the file
+     * @private
      */
     private _fileToMetadata;
     /**
-     * PreAuth upload URLs are not directly supported in Google Drive
+     * Creates a pre-authenticated upload URL for an object in Google Drive.
+     *
+     * Google Drive doesn't directly support pre-signed upload URLs in the same
+     * way as other storage providers like S3 or Azure. Instead, uploads
+     * should be performed using the PutObject method.
+     *
+     * @param objectName - The name of the object to upload
+     * @throws UnsupportedOperationError as this operation is not supported
      */
     CreatePreAuthUploadUrl(objectName: string): Promise<CreatePreAuthUploadUrlPayload>;
     /**
-     * Create a pre-authenticated download URL
+     * Creates a pre-authenticated download URL for an object in Google Drive.
+     *
+     * This method creates a temporary, public sharing link for a file that allows
+     * anyone with the link to access the file for a limited time (10 minutes).
+     * It uses Google Drive's permissions system to create a temporary reader
+     * permission for 'anyone' with an expiration time.
+     *
+     * @param objectName - The path to the file to download
+     * @returns A Promise resolving to the download URL
+     * @throws Error if the file cannot be found or the URL creation fails
+     *
+     * @example
+     * ```typescript
+     * // Generate a pre-authenticated download URL for a PDF file
+     * const downloadUrl = await driveStorage.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>;
     /**
-     * Move an object from one location to another
+     * Moves an object from one location to another within Google Drive.
+     *
+     * This method first locates the file to be moved, then gets or creates the
+     * destination folder, and finally updates the file's name and parent folder.
+     * Google Drive has native support for moving files between folders.
+     *
+     * @param oldObjectName - The current path of the object
+     * @param newObjectName - The new path for the object
+     * @returns A Promise resolving to a boolean indicating success
+     *
+     * @example
+     * ```typescript
+     * // Move a file from drafts to published folder
+     * const success = await driveStorage.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>;
     /**
-     * Delete an object
+     * Deletes an object from Google Drive.
+     *
+     * This method locates the specified file by path and deletes it from Google Drive.
+     * By default, this moves the file to the trash rather than permanently deleting it,
+     * unless your Drive settings are configured for immediate permanent deletion.
+     *
+     * @param objectName - The path to the file to delete
+     * @returns A Promise resolving to a boolean indicating success
+     *
+     * @example
+     * ```typescript
+     * // Delete a temporary file
+     * const deleted = await driveStorage.DeleteObject('temp/report-draft.pdf');
+     *
+     * if (deleted) {
+     *   console.log('File successfully deleted');
+     * } else {
+     *   console.log('Failed to delete file');
+     * }
+     * ```
      */
     DeleteObject(objectName: string): Promise<boolean>;
     /**
-     * List objects in a directory
+     * Lists objects in a directory in Google Drive.
+     *
+     * This method retrieves all files and folders directly inside the specified
+     * folder path. It handles Google Drive's native folder structure and converts
+     * the Drive API responses to the standardized StorageListResult format.
+     *
+     * @param prefix - The path to the directory to list
+     * @param delimiter - Delimiter character (unused in Google Drive implementation)
+     * @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 driveStorage.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>;
     /**
-     * Create a directory
+     * Creates a directory in Google Drive.
+     *
+     * This method creates a folder at the specified path, creating parent
+     * folders as needed if they don't exist. Google Drive natively supports
+     * folders as a special file type with the 'application/vnd.google-apps.folder'
+     * MIME type.
+     *
+     * @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 driveStorage.CreateDirectory('documents/reports/annual/');
+     *
+     * if (created) {
+     *   console.log('Directory created successfully');
+     * } else {
+     *   console.log('Failed to create directory');
+     * }
+     * ```
      */
     CreateDirectory(directoryPath: string): Promise<boolean>;
     /**
-     * Delete a directory and optionally its contents
+     * Deletes a directory and optionally its contents from Google Drive.
+     *
+     * This method deletes a folder at the specified path. If recursive is false,
+     * it will fail if the folder has any contents. If recursive is true, it
+     * deletes the folder and all its contents.
+     *
+     * @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 driveStorage.DeleteDirectory('documents/temp/');
+     *
+     * // Delete a directory and all its contents
+     * const recursivelyDeleted = await driveStorage.DeleteDirectory('documents/old_projects/', true);
+     * ```
      */
     DeleteDirectory(directoryPath: string, recursive?: boolean): Promise<boolean>;
     /**
-     * Get object metadata
+     * Retrieves metadata for a specific object in Google Drive.
+     *
+     * This method fetches the file information without downloading its content,
+     * which is more efficient for checking file attributes like size, type,
+     * and last modified date.
+     *
+     * @param objectName - The path to the file to get metadata for
+     * @returns A Promise resolving to a StorageObjectMetadata object
+     * @throws Error if the file doesn't exist or cannot be accessed
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const metadata = await driveStorage.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>;
     /**
-     * Get object contents
+     * Downloads an object's content from Google Drive.
+     *
+     * This method retrieves the full content of a file and returns it
+     * as a Buffer for processing in memory.
+     *
+     * @param objectName - The path to the file to download
+     * @returns A Promise resolving to a Buffer containing the file's data
+     * @throws Error if the file doesn't exist or cannot be downloaded
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const content = await driveStorage.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>;
     /**
-     * Upload an object
+     * Uploads data to an object in Google Drive.
+     *
+     * This method directly uploads a Buffer of data to a file with the specified path.
+     * It will create any necessary parent folders if they don't exist, and will update
+     * the file if it already exists or create a new one if it doesn't.
+     *
+     * @param objectName - The path to the file to upload
+     * @param data - The Buffer containing the data to upload
+     * @param contentType - Optional MIME type for the file (inferred from name if not provided)
+     * @param metadata - Optional key-value pairs of custom metadata (not supported in current implementation)
+     * @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 driveStorage.PutObject(
+     *   'documents/hello.txt',
+     *   content,
+     *   'text/plain'
+     * );
+     *
+     * 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>;
     /**
-     * Copy an object
+     * Copies an object within Google Drive.
+     *
+     * This method creates a copy of a file at a new location without removing the original.
+     * It uses the Google Drive API's native file copying capabilities.
+     *
+     * @param sourceObjectName - The path to the file to copy
+     * @param destinationObjectName - The path where the copy should be created
+     * @returns A Promise resolving to a boolean indicating success
+     *
+     * @example
+     * ```typescript
+     * // Create a backup copy of an important file
+     * const copied = await driveStorage.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>;
     /**
-     * Check if an object exists
+     * Checks if an object exists in Google Drive.
+     *
+     * This method verifies the existence of a file at the specified path
+     * without downloading its content.
+     *
+     * @param objectName - The path to the file to check
+     * @returns A Promise resolving to a boolean indicating if the file exists
+     *
+     * @example
+     * ```typescript
+     * // Check if a file exists before attempting to use it
+     * const exists = await driveStorage.ObjectExists('documents/report.pdf');
+     *
+     * if (exists) {
+     *   console.log('File exists, proceeding with download');
+     *   const content = await driveStorage.GetObject('documents/report.pdf');
+     *   // Process the content...
+     * } else {
+     *   console.log('File does not exist');
+     * }
+     * ```
      */
     ObjectExists(objectName: string): Promise<boolean>;
     /**
-     * Check if a directory exists
+     * Checks if a directory exists in Google Drive.
+     *
+     * This method verifies the existence of a folder at the specified path.
+     * It also checks that the item is actually a folder (has the correct MIME type),
+     * not a file with the same name.
+     *
+     * @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 driveStorage.DirectoryExists('documents/reports/');
+     *
+     * if (!exists) {
+     *   console.log('Directory does not exist, creating it first');
+     *   await driveStorage.CreateDirectory('documents/reports/');
+     * }
+     *
+     * // Now safe to use the directory
+     * await driveStorage.PutObject('documents/reports/new-report.pdf', fileData);
+     * ```
      */
     DirectoryExists(directoryPath: string): Promise<boolean>;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"GoogleDriveFileStorage.d.ts","sourceRoot":"","sources":["../../src/drivers/GoogleDriveFileStorage.ts"],"names":[],"mappings":";AAIA,OAAO,EACL,6BAA6B,EAC7B,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACtB,MAAM,4BAA4B,CAAC;AAEpC,qBACa,sBAAuB,SAAQ,eAAe;IACzD,SAAS,CAAC,QAAQ,CAAC,YAAY,kBAAkB;IACjD,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,aAAa,CAAC,CAAS;;IAkC/B;;OAEG;YACW,cAAc;IAgD5B;;OAEG;YACW,wBAAwB;IA6CtC;;OAEG;IACH,OAAO,CAAC,eAAe;IAmBvB;;OAEG;IACU,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,6BAA6B,CAAC;IAM/F;;OAEG;IACU,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAiC1E;;OAEG;IACU,UAAU,CAAC,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAwCvF;;OAEG;IACU,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA2B/D;;OAEG;IACU,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,SAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA0CrF;;OAEG;IACU,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAkCrE;;OAEG;IACU,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,UAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAwCxF;;OAEG;IACU,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAqBlF;;OAEG;IACU,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAwB3D;;OAEG;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;IAqDnB;;OAEG;IACU,UAAU,CAAC,gBAAgB,EAAE,MAAM,EAAE,qBAAqB,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAiClG;;OAEG;IACU,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAS/D;;OAEG;IACU,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAatE"}
+{"version":3,"file":"GoogleDriveFileStorage.d.ts","sourceRoot":"","sources":["../../src/drivers/GoogleDriveFileStorage.ts"],"names":[],"mappings":";AAIA,OAAO,EACL,6BAA6B,EAC7B,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACtB,MAAM,4BAA4B,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBACa,sBAAuB,SAAQ,eAAe;IACzD,gEAAgE;IAChE,SAAS,CAAC,QAAQ,CAAC,YAAY,kBAAkB;IAEjD,kCAAkC;IAClC,OAAO,CAAC,MAAM,CAAiB;IAE/B,0EAA0E;IAC1E,OAAO,CAAC,aAAa,CAAC,CAAS;IAE/B;;;;;;OAMG;;IAiCH;;;;;;;;;;;OAWG;YACW,cAAc;IAgD5B;;;;;;;;;;OAUG;YACW,wBAAwB;IA6CtC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,eAAe;IAmBvB;;;;;;;;;OASG;IACU,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,6BAA6B,CAAC;IAM/F;;;;;;;;;;;;;;;;;;;;OAoBG;IACU,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAiC1E;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACU,UAAU,CAAC,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAwCvF;;;;;;;;;;;;;;;;;;;;;OAqBG;IACU,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA2B/D;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACU,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,SAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA0CrF;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACU,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAkCrE;;;;;;;;;;;;;;;;;;;OAmBG;IACU,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,UAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAwCxF;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACU,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAqBlF;;;;;;;;;;;;;;;;;;;;;OAqBG;IACU,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAwB3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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;IAqDnB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACU,UAAU,CAAC,gBAAgB,EAAE,MAAM,EAAE,qBAAqB,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAiClG;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACU,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAS/D;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACU,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAatE"}