bodevops-features 1.0.0 → 1.0.8

package/dist/types/gg-drive/types.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Google Drive Feature Library - Type Definitions
+ * @description Type definitions for Google Drive operations including file upload, download, sharing, and storage management.
+ * @module gg-drive/types
+ */
+/**
+ * Configuration options for Google Drive client initialization.
+ * Supports either a path to a service account key file or a direct credentials object.
+ */
+export interface IGoogleDriveConfig {
+    /** Path to the service account JSON key file */
+    keyFilePath?: string;
+    /** Service account credentials object (alternative to keyFilePath) */
+    credentials?: IGoogleServiceAccountCredentials;
+    /** OAuth scopes for Google Drive API access */
+    scopes?: string[];
+}
+/**
+ * Google Service Account credentials structure.
+ * This matches the structure of the downloaded JSON key file from Google Cloud Console.
+ */
+export interface IGoogleServiceAccountCredentials {
+    /** The type of account, typically "service_account" */
+    type: string;
+    /** The unique identifier for the project */
+    project_id: string;
+    /** The private key identifier */
+    private_key_id: string;
+    /** The private key in PEM format */
+    private_key: string;
+    /** The service account email address */
+    client_email: string;
+    /** The unique client identifier */
+    client_id: string;
+    /** The authentication URI */
+    auth_uri: string;
+    /** The token URI for obtaining access tokens */
+    token_uri: string;
+    /** The authentication provider certificate URL */
+    auth_provider_x509_cert_url: string;
+    /** The client certificate URL */
+    client_x509_cert_url: string;
+}
+/**
+ * Result returned after successfully uploading a file to Google Drive.
+ */
+export interface IUploadFileResult {
+    /** The unique identifier of the uploaded file in Google Drive */
+    id: string;
+    /** The name of the file as stored in Google Drive */
+    name: string;
+    /** URL to view the file in a web browser (optional) */
+    webViewLink?: string;
+    /** URL to directly download the file content (optional) */
+    webContentLink?: string;
+}
+/**
+ * Information about a file or folder in Google Drive.
+ */
+export interface IFileInfo {
+    /** The unique identifier of the file */
+    id: string;
+    /** The name of the file */
+    name: string;
+    /** The MIME type of the file (e.g., "application/pdf", "application/vnd.google-apps.folder") */
+    mimeType: string;
+    /** URL to view the file in a web browser (optional) */
+    webViewLink?: string;
+    /** Array of parent folder IDs (optional) */
+    parents?: string[];
+}
+/**
+ * Storage quota information for Google Drive account.
+ */
+export interface IStorageInfo {
+    /** Total storage used in bytes */
+    used: number;
+    /** Total storage limit in bytes */
+    total: number;
+    /** Storage used specifically by Drive files in bytes */
+    usedInDrive: number;
+    /** Percentage of storage used (0-100) */
+    percentage: number;
+    /** Human-readable format of used storage (e.g., "1.5 GB") */
+    formattedUsed: string;
+    /** Human-readable format of total storage (e.g., "15 GB") */
+    formattedTotal: string;
+    /** Human-readable format of storage used in Drive (e.g., "500 MB") */
+    formattedUsedInDrive: string;
+}
+/**
+ * Available permission roles for sharing files and folders.
+ * - 'reader': Can view files
+ * - 'writer': Can view and edit files
+ * - 'owner': Full ownership with all permissions
+ */
+export type TRoleShare = 'reader' | 'writer' | 'owner';
+/**
+ * Parameters for uploading a file to Google Drive.
+ */
+export interface IUploadFileParams {
+    /** Absolute path to the local file to upload */
+    localFilePath: string;
+    /** Target folder path in Google Drive (e.g., "MyFolder/SubFolder"). Use empty string or "/" for root. */
+    driveFolder: string;
+    /** Optional custom file name. If not provided, the original file name is used. */
+    fileName?: string;
+}
+/**
+ * Parameters for uploading a file and sharing it with another user.
+ */
+export interface IUploadFileAndShareParams extends IUploadFileParams {
+    /** Email address to share the file with */
+    shareWithEmail: string;
+    /** Permission role for the shared user (default: 'reader') */
+    role?: TRoleShare;
+}
+/**
+ * Parameters for listing files in a folder.
+ */
+export interface IListFilesParams {
+    /** The folder ID to list files from. Use 'root' for the root folder. Default: 'root' */
+    folderId?: string;
+}
+/**
+ * Parameters for deleting a file from Google Drive.
+ */
+export interface IDeleteFileParams {
+    /** The unique identifier of the file to delete */
+    fileId: string;
+}
+/**
+ * Parameters for making a file publicly accessible.
+ */
+export interface IMakeFilePublicParams {
+    /** The unique identifier of the file to make public */
+    fileId: string;
+}
+/**
+ * Parameters for transferring file ownership to another user.
+ */
+export interface ITransferOwnershipParams {
+    /** The unique identifier of the file */
+    fileId: string;
+    /** Email address of the new owner */
+    newOwnerEmail: string;
+    /** Permission role to assign (default: 'reader') */
+    role?: TRoleShare;
+}
+/**
+ * Parameters for sharing a folder with another user.
+ */
+export interface IShareFolderParams {
+    /** The unique identifier of the folder */
+    folderId: string;
+    /** Email address to share the folder with */
+    emailAddress: string;
+    /** Permission role for the shared user (default: 'writer') */
+    role?: TRoleShare;
+}
+/**
+ * Parameters for getting folder ID by path.
+ */
+export interface IGetFolderIdParams {
+    /** Folder path (e.g., "folder1/folder2/folder3") */
+    folderPath: string;
+}
+/**
+ * Parameters for checking if a file exists in a folder.
+ */
+export interface IFileExistsParams {
+    /** The name of the file to check */
+    fileName: string;
+    /** The folder ID to search in. Default: 'root' */
+    folderId?: string;
+}

package/dist/types/gg-drive/utils.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Google Drive Feature Library - Utility Functions
+ * @description Helper functions for file handling, formatting, and validation in Google Drive operations.
+ * @module gg-drive/utils
+ */
+import * as fs from 'fs';
+/**
+ * Converts a byte count into a human-readable string format.
+ *
+ * @param bytes - The number of bytes to format
+ * @returns A human-readable string representation (e.g., "1.5 GB")
+ *
+ * @example
+ * ```typescript
+ * formatBytes(0);          // "0 Bytes"
+ * formatBytes(1024);       // "1 KB"
+ * formatBytes(1536);       // "1.5 KB"
+ * formatBytes(1073741824); // "1 GB"
+ * ```
+ */
+export declare function formatBytes({ bytes }: {
+    bytes: number;
+}): string;
+/**
+ * Normalizes a file path to use the correct path separators for the current OS.
+ * Also resolves relative paths to absolute paths.
+ *
+ * @param filePath - The file path to normalize
+ * @returns The normalized absolute file path
+ *
+ * @example
+ * ```typescript
+ * normalizeFilePath({ filePath: './documents/file.pdf' });
+ * // Returns: "D:\\MyFolder\\documents\\file.pdf" (on Windows)
+ * ```
+ */
+export declare function normalizeFilePath({ filePath }: {
+    filePath: string;
+}): string;
+/**
+ * Validates that a file exists at the specified path.
+ *
+ * @param filePath - The absolute path to the file to validate
+ * @returns True if the file exists, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const exists = validateFileExists({ filePath: 'D:\\MyFolder\\file.pdf' });
+ * if (!exists) {
+ *   console.log('File not found!');
+ * }
+ * ```
+ */
+export declare function validateFileExists({ filePath }: {
+    filePath: string;
+}): boolean;
+/**
+ * Gets detailed information about a local file.
+ *
+ * @param filePath - The absolute path to the file
+ * @returns File information object or null if file doesn't exist
+ *
+ * @example
+ * ```typescript
+ * const info = getFileInfo({ filePath: './document.pdf' });
+ * if (info) {
+ *   console.log(`File size: ${info.sizeFormatted}`);
+ * }
+ * ```
+ */
+export declare function getFileInfo({ filePath }: {
+    filePath: string;
+}): {
+    name: string;
+    extension: string;
+    directory: string;
+    size: number;
+    sizeFormatted: string;
+} | null;
+/**
+ * Parses a folder path string into an array of folder names.
+ *
+ * @param folderPath - The folder path to parse (e.g., "folder1/folder2/folder3")
+ * @returns An array of folder names
+ *
+ * @example
+ * ```typescript
+ * parseFolderPath({ folderPath: 'a/b/c' });  // ['a', 'b', 'c']
+ * parseFolderPath({ folderPath: '/' });      // []
+ * parseFolderPath({ folderPath: '' });       // []
+ * ```
+ */
+export declare function parseFolderPath({ folderPath }: {
+    folderPath: string;
+}): string[];
+/**
+ * Creates a readable stream for a local file.
+ *
+ * @param filePath - The absolute path to the file
+ * @returns A readable stream for the file
+ * @throws Error if the file doesn't exist
+ *
+ * @example
+ * ```typescript
+ * const stream = createFileReadStream({ filePath: './document.pdf' });
+ * // Use stream for upload
+ * ```
+ */
+export declare function createFileReadStream({ filePath }: {
+    filePath: string;
+}): fs.ReadStream;

package/dist/types/gg-sheet/config.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Google Sheet Feature Library - Configuration Module
+ * @description Configuration management for Google Sheet client initialization and authentication.
+ * @module gg-sheet/config
+ */
+import { IGoogleSheetConfig, IGoogleServiceAccountCredentials } from './types';
+/**
+ * Default OAuth scope required for Google Sheets operations.
+ */
+export declare const DEFAULT_SHEET_SCOPES: string[];
+/**
+ * Google Sheet Configuration Manager.
+ * Handles validation and normalization of configuration options for the Google Sheet client.
+ *
+ * @example
+ * ```typescript
+ * // Using key file path
+ * const config = new GoogleSheetConfig({
+ *   keyFilePath: './service-account.json'
+ * });
+ *
+ * // Using credentials object
+ * const config = new GoogleSheetConfig({
+ *   credentials: {
+ *     type: 'service_account',
+ *     project_id: 'my-project',
+ *     private_key: '-----BEGIN PRIVATE KEY-----\n...',
+ *     client_email: 'service-account@my-project.iam.gserviceaccount.com',
+ *     // ... other fields
+ *   }
+ * });
+ * ```
+ */
+export declare class GoogleSheetConfig {
+    /** Path to the service account key file */
+    readonly keyFilePath?: string;
+    /** Service account credentials object */
+    readonly credentials?: IGoogleServiceAccountCredentials;
+    /** OAuth scopes for Google Sheets API */
+    readonly scopes: string[];
+    /**
+     * Creates a new GoogleSheetConfig instance.
+     *
+     * @param config - Configuration options for Google Sheet client
+     * @throws Error if neither keyFilePath nor credentials is provided
+     */
+    constructor({ keyFilePath, credentials, scopes }: IGoogleSheetConfig);
+    /**
+     * Validates that the credentials object contains all required fields.
+     *
+     * @param credentials - The credentials object to validate
+     * @throws Error if required fields are missing
+     */
+    private validateCredentials;
+    /**
+     * Returns the authentication configuration object suitable for googleapis.
+     *
+     * @returns Authentication options for Google Auth
+     */
+    getAuthOptions(): {
+        keyFile?: string;
+        credentials?: IGoogleServiceAccountCredentials;
+        scopes: string[];
+    };
+}

package/dist/types/gg-sheet/google-sheet.d.ts

@@ -0,0 +1,255 @@
+/**
+ * Google Sheet Feature Library - Main Client Class
+ * @description A framework-agnostic client for interacting with Google Sheets API.
+ * Provides methods for reading, writing, and managing spreadsheet data.
+ * @module gg-sheet/google-sheet
+ */
+import { IGoogleSheetConfig, ISpreadsheetInfo, IGetSheetInfoParams, IGetValuesParams, IGetIdxRowParams, IExportParams, IUpdateMultiCellsParams, IUpdateMultiColsByRowParams, IUpdateMultiRowsByColParams, IUpdateMultiRowsMultiColsParams, IDeleteRowParams } from './types';
+/**
+ * Google Sheet Client for managing spreadsheet data.
+ *
+ * @example
+ * ```typescript
+ * import { GoogleSheetClient } from 'bodevops-features/gg-sheet';
+ *
+ * const client = new GoogleSheetClient({
+ *   keyFilePath: './service-account.json'
+ * });
+ *
+ * // Read data from a sheet
+ * const data = await client.getValues({
+ *   sheetUrl: 'https://docs.google.com/spreadsheets/d/...',
+ *   sheetName: 'Sheet1'
+ * });
+ *
+ * // Update specific cells
+ * await client.updateValuesMultiCells({
+ *   sheetUrl: 'https://docs.google.com/spreadsheets/d/...',
+ *   sheetName: 'Sheet1',
+ *   cells: [
+ *     { row: 0, col: 0, content: 'Hello' },
+ *     { row: 0, col: 1, content: 'World' }
+ *   ]
+ * });
+ * ```
+ */
+export declare class GoogleSheetClient {
+    private readonly config;
+    /**
+     * Creates a new GoogleSheetClient instance.
+     *
+     * @param configOptions - Configuration options for the Google Sheet client
+     */
+    constructor(configOptions: IGoogleSheetConfig);
+    /**
+     * Creates and returns an authenticated Google Sheets API client.
+     *
+     * @returns A Promise that resolves to an authenticated Sheets API client
+     */
+    private getSheetsClient;
+    /**
+     * Extracts the spreadsheet ID from a URL and validates it.
+     *
+     * @param sheetUrl - The Google Sheets URL
+     * @returns The spreadsheet ID
+     * @throws Error if the URL is invalid
+     */
+    private extractSheetId;
+    /**
+     * Retrieves information about a Google Spreadsheet, including all sheet tabs.
+     *
+     * @param params - Parameters including the sheet URL
+     * @returns A Promise that resolves to spreadsheet information
+     *
+     * @example
+     * ```typescript
+     * const info = await client.getSheetInfo({
+     *   sheetUrl: 'https://docs.google.com/spreadsheets/d/...'
+     * });
+     * console.log(`Spreadsheet: ${info.spreadsheetTitle}`);
+     * console.log(`Sheets: ${info.sheets.map(s => s.title).join(', ')}`);
+     * ```
+     */
+    getSheetInfo({ sheetUrl }: IGetSheetInfoParams): Promise<ISpreadsheetInfo>;
+    /**
+     * Reads all values from a specific sheet tab.
+     *
+     * @param params - Parameters including sheet URL, sheet name, and optional row limit
+     * @returns A Promise that resolves to a 2D array of string values
+     *
+     * @example
+     * ```typescript
+     * const data = await client.getValues({
+     *   sheetUrl: 'https://docs.google.com/spreadsheets/d/...',
+     *   sheetName: 'Sheet1',
+     *   endRow: 100  // Optional: limit to first 100 rows
+     * });
+     *
+     * for (const row of data) {
+     *   console.log(row.join(', '));
+     * }
+     * ```
+     */
+    getValues({ sheetUrl, sheetName, endRow }: IGetValuesParams): Promise<string[][]>;
+    /**
+     * Finds the row index (0-based) where a specific value appears in a column.
+     *
+     * @param params - Parameters including sheet URL, sheet name, column name, and value to find
+     * @returns A Promise that resolves to the row index (0-based), or -1 if not found
+     *
+     * @example
+     * ```typescript
+     * const rowIndex = await client.getIdxRow({
+     *   sheetUrl: 'https://docs.google.com/spreadsheets/d/...',
+     *   sheetName: 'Sheet1',
+     *   colName: 'A',
+     *   value: 'John Doe'
+     * });
+     *
+     * if (rowIndex >= 0) {
+     *   console.log(`Found at row index: ${rowIndex}`);
+     * }
+     * ```
+     */
+    getIdxRow({ sheetUrl, sheetName, colName, value, }: IGetIdxRowParams): Promise<number>;
+    /**
+     * Exports data to a Google Sheet with either Append or Overwrite mode.
+     *
+     * @param params - Export parameters including data and export type
+     * @returns A Promise that resolves to true if successful
+     *
+     * @example
+     * ```typescript
+     * // Overwrite existing data
+     * await client.export({
+     *   sheetUrl: 'https://docs.google.com/spreadsheets/d/...',
+     *   sheetName: 'Sheet1',
+     *   listCols: ['Name', 'Email', 'Age'],
+     *   valsExport: [
+     *     ['John', 'john@example.com', '30'],
+     *     ['Jane', 'jane@example.com', '25']
+     *   ],
+     *   typeExport: ETypeExport.Overwrite
+     * });
+     *
+     * // Append to existing data
+     * await client.export({
+     *   sheetUrl: 'https://docs.google.com/spreadsheets/d/...',
+     *   sheetName: 'Sheet1',
+     *   listCols: ['Name', 'Email', 'Age'],
+     *   valsExport: [['New User', 'new@example.com', '28']],
+     *   typeExport: ETypeExport.Append
+     * });
+     * ```
+     */
+    export({ sheetUrl, sheetName, listCols, valsExport, typeExport, }: IExportParams): Promise<boolean>;
+    /**
+     * Executes an overwrite export - writes headers and data from row 1.
+     */
+    private executeOverwriteExport;
+    /**
+     * Executes an append export - finds empty rows and appends data.
+     */
+    private executeAppendExport;
+    /**
+     * Updates multiple cells at specific row and column positions.
+     *
+     * @param params - Update parameters including cells to update
+     * @returns A Promise that resolves to true if successful
+     *
+     * @example
+     * ```typescript
+     * await client.updateValuesMultiCells({
+     *   sheetUrl: 'https://docs.google.com/spreadsheets/d/...',
+     *   sheetName: 'Sheet1',
+     *   cells: [
+     *     { row: 0, col: 0, content: 'Updated A2' },
+     *     { row: 1, col: 1, content: 'Updated B3' },
+     *     { row: 2, col: 2, content: 'Updated C4' }
+     *   ],
+     *   rowOffset: 0  // Header at row 1, data starts at row 2
+     * });
+     * ```
+     */
+    updateValuesMultiCells({ sheetUrl, sheetName, cells, rowOffset, }: IUpdateMultiCellsParams): Promise<boolean>;
+    /**
+     * Updates multiple columns in a single row.
+     *
+     * @param params - Update parameters including row and column values
+     * @returns A Promise that resolves to true if successful
+     *
+     * @example
+     * ```typescript
+     * await client.updateValuesMultiColsByRow({
+     *   sheetUrl: 'https://docs.google.com/spreadsheets/d/...',
+     *   sheetName: 'Sheet1',
+     *   row: 5,
+     *   values: [
+     *     { col: 0, content: 'Value for A7' },
+     *     { col: 1, content: 'Value for B7' },
+     *     { col: 2, content: 'Value for C7' }
+     *   ]
+     * });
+     * ```
+     */
+    updateValuesMultiColsByRow({ sheetUrl, sheetName, row, values, rowOffset, }: IUpdateMultiColsByRowParams): Promise<boolean>;
+    /**
+     * Updates multiple rows in a single column.
+     *
+     * @param params - Update parameters including column and row values
+     * @returns A Promise that resolves to true if successful
+     *
+     * @example
+     * ```typescript
+     * await client.updateValuesMultiRowsByCol({
+     *   sheetUrl: 'https://docs.google.com/spreadsheets/d/...',
+     *   sheetName: 'Sheet1',
+     *   col: 2,
+     *   values: [
+     *     { row: 0, content: 'Row 1 Col C' },
+     *     { row: 1, content: 'Row 2 Col C' },
+     *     { row: 2, content: 'Row 3 Col C' }
+     *   ]
+     * });
+     * ```
+     */
+    updateValuesMultiRowsByCol({ sheetUrl, sheetName, col, values, rowOffset, }: IUpdateMultiRowsByColParams): Promise<boolean>;
+    /**
+     * Updates a range of multiple rows and columns at once.
+     *
+     * @param params - Update parameters including value matrix
+     * @returns A Promise that resolves to true if successful
+     *
+     * @example
+     * ```typescript
+     * await client.updateValuesMultiRowsMultiCols({
+     *   sheetUrl: 'https://docs.google.com/spreadsheets/d/...',
+     *   sheetName: 'Sheet1',
+     *   values: [
+     *     ['A1', 'B1', 'C1'],
+     *     ['A2', 'B2', 'C2'],
+     *     ['A3', 'B3', 'C3']
+     *   ],
+     *   startRow: 0,
+     *   startCol: 0
+     * });
+     * ```
+     */
+    updateValuesMultiRowsMultiCols({ sheetUrl, sheetName, values, startRow, endRow, startCol, rowOffset, }: IUpdateMultiRowsMultiColsParams): Promise<boolean>;
+    /**
+     * Deletes a row from a sheet.
+     *
+     * @param params - Delete parameters including row index
+     * @returns A Promise that resolves to true if successful
+     *
+     * @example
+     * ```typescript
+     * await client.deleteRowSheet({
+     *   sheetUrl: 'https://docs.google.com/spreadsheets/d/...',
+     *   sheetName: 'Sheet1',
+     *   row: 5  // Delete data row at index 5
+     * });
+     * ```
+     */
+    deleteRowSheet({ sheetUrl, sheetName, row, rowOffset, }: IDeleteRowParams): Promise<boolean>;
+}

package/dist/types/gg-sheet/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Google Sheet Feature Library
+ * @description A framework-agnostic library for interacting with Google Sheets API.
+ * Provides easy-to-use methods for reading, writing, and managing spreadsheet data.
+ * @module gg-sheet
+ *
+ * @example
+ * ```typescript
+ * import { GoogleSheetClient, ETypeExport } from 'bodevops-features/gg-sheet';
+ *
+ * const client = new GoogleSheetClient({
+ *   keyFilePath: './service-account.json'
+ * });
+ *
+ * // Read data from a sheet
+ * const data = await client.getValues({
+ *   sheetUrl: 'https://docs.google.com/spreadsheets/d/...',
+ *   sheetName: 'Sheet1'
+ * });
+ *
+ * // Export data
+ * await client.export({
+ *   sheetUrl: 'https://docs.google.com/spreadsheets/d/...',
+ *   sheetName: 'Sheet1',
+ *   listCols: ['Name', 'Email'],
+ *   valsExport: [['John', 'john@example.com']],
+ *   typeExport: ETypeExport.Append
+ * });
+ * ```
+ */
+export { GoogleSheetClient } from './google-sheet';
+export { GoogleSheetConfig, DEFAULT_SHEET_SCOPES } from './config';
+export type { IGoogleSheetConfig, IGoogleServiceAccountCredentials, ISheetChildrenInfo, ISheetValUpdateCell, ISpreadsheetInfo, IGetSheetInfoParams, IGetValuesParams, IGetIdxRowParams, IExportParams, IUpdateMultiCellsParams, IColValuePair, IUpdateMultiColsByRowParams, IRowValuePair, IUpdateMultiRowsByColParams, IUpdateMultiRowsMultiColsParams, IDeleteRowParams, IConvertValueSheetParams, IListColsAndValsExport, } from './types';
+export { ETypeExport } from './types';
+export { getSheetIdFromUrl, convertIndexToColumnName, convertColumnNameToIndex, convertValueSheet, getIndexCol, getListColsAndValsExport, isValidSheetUrl, calculateActualRow, } from './utils';