@memberjunction/storage 2.38.0 → 2.40.0

package/dist/drivers/GoogleFileStorage.d.ts

@@ -1,30 +1,386 @@
 /// <reference types="node" />
 import { CreatePreAuthUploadUrlPayload, FileStorageBase, StorageListResult, StorageObjectMetadata } from '../generic/FileStorageBase';
+/**
+ * Google Cloud Storage implementation of the FileStorageBase interface.
+ *
+ * This class provides methods for interacting with Google Cloud Storage as a file storage provider.
+ * It implements all the abstract methods defined in FileStorageBase and handles Google-specific
+ * authentication, authorization, and file operations.
+ *
+ * It requires the following environment variables to be set:
+ * - STORAGE_GOOGLE_KEY_JSON: A JSON object containing Google Cloud service account credentials
+ * - STORAGE_GOOGLE_BUCKET_NAME: The GCS bucket name
+ *
+ * @example
+ * ```typescript
+ * // Create an instance of GoogleFileStorage
+ * const gcsStorage = new GoogleFileStorage();
+ *
+ * // Generate a pre-authenticated upload URL
+ * const { UploadUrl } = await gcsStorage.CreatePreAuthUploadUrl('documents/report.pdf');
+ *
+ * // Generate a pre-authenticated download URL
+ * const downloadUrl = await gcsStorage.CreatePreAuthDownloadUrl('documents/report.pdf');
+ *
+ * // List files in a directory
+ * const files = await gcsStorage.ListObjects('documents/');
+ * ```
+ */
 export declare class GoogleFileStorage extends FileStorageBase {
+    /** The name of this storage provider, used in error messages */
     protected readonly providerName = "Google Cloud Storage";
+    /** The GCS bucket name */
     private _bucket;
+    /** The Google Cloud Storage client instance */
     private _client;
+    /**
+     * Creates a new instance of GoogleFileStorage.
+     *
+     * Initializes the connection to Google Cloud Storage using environment variables.
+     * Throws an error if any required environment variables are missing.
+     */
     constructor();
     /**
-     * Normalizes directory paths to ensure they end with a slash
+     * Normalizes directory paths to ensure they end with a slash.
+     *
+     * This is a helper method used internally to ensure consistency in
+     * directory path representation. Google Cloud 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;
     /**
-     * Converts metadata to a string map for consistent handling
+     * Converts metadata to a string map for consistent handling.
+     *
+     * This is a helper method used internally to ensure that all metadata
+     * values are strings, as required by the StorageObjectMetadata type.
+     *
+     * @param metadata - The metadata object to convert
+     * @returns A record with string keys and string values
+     * @private
      */
     private _convertMetadataToStringMap;
+    /**
+     * Creates a pre-authenticated upload URL for an object in Google Cloud Storage.
+     *
+     * This method generates a signed URL that allows for uploading an object
+     * to GCS without needing Google Cloud credentials. The URL is valid for
+     * 10 minutes and includes the content type based on the file extension.
+     *
+     * @param objectName - The name of the object 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 gcsStorage.CreatePreAuthUploadUrl('documents/report.pdf');
+     *
+     * // The URL can be used with fetch or other HTTP clients to upload the file
+     * console.log(UploadUrl);
+     * ```
+     */
     CreatePreAuthUploadUrl(objectName: string): Promise<CreatePreAuthUploadUrlPayload>;
+    /**
+     * Creates a pre-authenticated download URL for an object in Google Cloud Storage.
+     *
+     * This method generates a signed URL that allows for downloading an object
+     * from GCS without needing Google Cloud credentials. The URL is valid for
+     * 10 minutes and can be shared with clients.
+     *
+     * @param objectName - The name of the object 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 gcsStorage.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 an object from one location to another within Google Cloud Storage.
+     *
+     * Unlike some other storage providers, GCS has a native rename operation
+     * that can be used to efficiently move objects without needing to copy
+     * and delete. This method leverages that capability.
+     *
+     * @param oldObjectName - The current name/path of the object
+     * @param newObjectName - The new name/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 gcsStorage.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 an object from Google Cloud Storage.
+     *
+     * This method attempts to delete the specified object. It uses the
+     * ignoreNotFound option to ensure it returns true even if the object
+     * didn't exist.
+     *
+     * @param objectName - The name of the object to delete (including any path/directory)
+     * @returns A Promise resolving to a boolean indicating success
+     *
+     * @example
+     * ```typescript
+     * // Delete a temporary file
+     * const deleted = await gcsStorage.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 objects with the specified prefix in Google Cloud Storage.
+     *
+     * This method returns a list of objects (files) and prefixes (directories)
+     * under the specified path prefix. It uses the GCS getFiles API which
+     * supports delimiter-based hierarchy simulation.
+     *
+     * Note: This implementation fetches metadata for each file, which can be
+     * inefficient for directories with many files. In a production environment,
+     * you might want to optimize this for large directories.
+     *
+     * @param prefix - The path prefix to list objects 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 gcsStorage.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 Google Cloud Storage.
+     *
+     * Since GCS doesn't have a native directory concept, this method creates
+     * a zero-byte object with a trailing slash to simulate a directory.
+     * The object 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 gcsStorage.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 Google Cloud Storage.
+     *
+     * For non-recursive deletion, this method simply deletes the directory
+     * placeholder object. For recursive deletion, it lists all objects with
+     * the directory path as prefix and deletes them in parallel.
+     *
+     * @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 gcsStorage.DeleteDirectory('documents/temp/');
+     *
+     * // Delete a directory and all its contents
+     * const recursivelyDeleted = await gcsStorage.DeleteDirectory('documents/old_projects/', true);
+     * ```
+     */
     DeleteDirectory(directoryPath: string, recursive?: boolean): Promise<boolean>;
+    /**
+     * Retrieves metadata for a specific object in Google Cloud Storage.
+     *
+     * This method fetches the properties of an object 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 object to get metadata for
+     * @returns A Promise resolving to a StorageObjectMetadata object
+     * @throws Error if the object doesn't exist or cannot be accessed
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const metadata = await gcsStorage.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 an object's content from Google Cloud Storage.
+     *
+     * This method retrieves the full content of an object and returns it
+     * as a Buffer for processing in memory.
+     *
+     * @param objectName - The name of the object to download
+     * @returns A Promise resolving to a Buffer containing the object's data
+     * @throws Error if the object doesn't exist or cannot be downloaded
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const content = await gcsStorage.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 an object in Google Cloud Storage.
+     *
+     * This method directly uploads a Buffer of data to an object 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 object
+     * @param data - The Buffer containing the data to upload
+     * @param contentType - Optional MIME type for the object (inferred from name if not provided)
+     * @param metadata - Optional key-value pairs of custom metadata to associate with the object
+     * @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 gcsStorage.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 an object within Google Cloud Storage.
+     *
+     * This method creates a copy of an object at a new location without removing the original.
+     * It uses the GCS copy API, which allows for efficient copying within the same bucket.
+     *
+     * @param sourceObjectName - The name of the object to copy
+     * @param destinationObjectName - The name to assign to the copied object
+     * @returns A Promise resolving to a boolean indicating success
+     *
+     * @example
+     * ```typescript
+     * // Create a backup copy of an important file
+     * const copied = await gcsStorage.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 an object exists in Google Cloud Storage.
+     *
+     * This method verifies the existence of an object without downloading
+     * its content. This is efficient for validation purposes.
+     *
+     * @param objectName - The name of the object to check
+     * @returns A Promise resolving to a boolean indicating if the object exists
+     *
+     * @example
+     * ```typescript
+     * // Check if a file exists before attempting to use it
+     * const exists = await gcsStorage.ObjectExists('documents/report.pdf');
+     *
+     * if (exists) {
+     *   console.log('File exists, proceeding with download');
+     *   const content = await gcsStorage.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 Google Cloud Storage.
+     *
+     * Since GCS doesn't have a native directory concept, this method checks for either:
+     * 1. The existence of a directory placeholder object (zero-byte object with trailing slash)
+     * 2. The existence of any objects 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 gcsStorage.DirectoryExists('documents/reports/');
+     *
+     * if (!exists) {
+     *   console.log('Directory does not exist, creating it first');
+     *   await gcsStorage.CreateDirectory('documents/reports/');
+     * }
+     *
+     * // Now safe to use the directory
+     * await gcsStorage.PutObject('documents/reports/new-report.pdf', fileData);
+     * ```
+     */
     DirectoryExists(directoryPath: string): Promise<boolean>;
 }
 //# sourceMappingURL=GoogleFileStorage.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"GoogleFileStorage.d.ts","sourceRoot":"","sources":["../../src/drivers/GoogleFileStorage.ts"],"names":[],"mappings":";AAIA,OAAO,EACL,6BAA6B,EAC7B,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACtB,MAAM,4BAA4B,CAAC;AAEpC,qBACa,iBAAkB,SAAQ,eAAe;IACpD,SAAS,CAAC,QAAQ,CAAC,YAAY,0BAA0B;IACzD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAU;;IASzB;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAI/B;;OAEG;IACH,OAAO,CAAC,2BAA2B;IAUtB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,6BAA6B,CAAC;IAclF,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAa7D,UAAU,CAAC,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAW1E,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAWlD,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,SAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAkDxE,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAoBxD,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,UAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IA4B3E,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IA4BrE,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAY9C,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;IAsBN,UAAU,CAAC,gBAAgB,EAAE,MAAM,EAAE,qBAAqB,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAkBrF,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAYlD,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAwBtE"}
+{"version":3,"file":"GoogleFileStorage.d.ts","sourceRoot":"","sources":["../../src/drivers/GoogleFileStorage.ts"],"names":[],"mappings":";AAIA,OAAO,EACL,6BAA6B,EAC7B,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACtB,MAAM,4BAA4B,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBACa,iBAAkB,SAAQ,eAAe;IACpD,gEAAgE;IAChE,SAAS,CAAC,QAAQ,CAAC,YAAY,0BAA0B;IAEzD,0BAA0B;IAC1B,OAAO,CAAC,OAAO,CAAS;IAExB,+CAA+C;IAC/C,OAAO,CAAC,OAAO,CAAU;IAEzB;;;;;OAKG;;IAQH;;;;;;;;;;OAUG;IACH,OAAO,CAAC,uBAAuB;IAI/B;;;;;;;;;OASG;IACH,OAAO,CAAC,2BAA2B;IAUnC;;;;;;;;;;;;;;;;;;OAkBG;IACU,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,6BAA6B,CAAC;IAc/F;;;;;;;;;;;;;;;;;;OAkBG;IACU,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAa1E;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACU,UAAU,CAAC,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAWvF;;;;;;;;;;;;;;;;;;;;;OAqBG;IACU,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAW/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACU,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,SAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAkDrF;;;;;;;;;;;;;;;;;;;;;OAqBG;IACU,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAoBrE;;;;;;;;;;;;;;;;;;;OAmBG;IACU,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,UAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IA4BxF;;;;;;;;;;;;;;;;;;;;;;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;IAY3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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;IAsBnB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACU,UAAU,CAAC,gBAAgB,EAAE,MAAM,EAAE,qBAAqB,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAkBlG;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACU,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAY/D;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACU,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAwBtE"}