bodevops-features 1.0.0 → 1.0.8

package/dist/cjs/index.js

@@ -1,13 +1,1710 @@
 'use strict';
 
-const test = () => {
-    console.log('test');
-};
+var googleapis = require('googleapis');
+var fs = require('fs');
+var path = require('path');
+
+function _interopNamespaceDefault(e) {
+    var n = Object.create(null);
+    if (e) {
+        Object.keys(e).forEach(function (k) {
+            if (k !== 'default') {
+                var d = Object.getOwnPropertyDescriptor(e, k);
+                Object.defineProperty(n, k, d.get ? d : {
+                    enumerable: true,
+                    get: function () { return e[k]; }
+                });
+            }
+        });
+    }
+    n.default = e;
+    return Object.freeze(n);
+}
+
+var fs__namespace = /*#__PURE__*/_interopNamespaceDefault(fs);
+var path__namespace = /*#__PURE__*/_interopNamespaceDefault(path);
+
+/**
+ * Google Drive Feature Library - Configuration Module
+ * @description Configuration management for Google Drive client initialization and authentication.
+ * @module gg-drive/config
+ */
+/**
+ * Default OAuth scopes required for Google Drive operations.
+ * These scopes provide full access to Drive files.
+ */
+const DEFAULT_DRIVE_SCOPES = [
+    'https://www.googleapis.com/auth/drive',
+    'https://www.googleapis.com/auth/drive.file',
+];
+/**
+ * Google Drive Configuration Manager.
+ * Handles validation and normalization of configuration options for the Google Drive client.
+ *
+ * @example
+ * ```typescript
+ * // Using key file path
+ * const config = new GoogleDriveConfig({
+ *   keyFilePath: './service-account.json'
+ * });
+ *
+ * // Using credentials object
+ * const config = new GoogleDriveConfig({
+ *   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
+ *   }
+ * });
+ * ```
+ */
+class GoogleDriveConfig {
+    /**
+     * Creates a new GoogleDriveConfig instance.
+     *
+     * @param config - Configuration options for Google Drive client
+     * @throws Error if neither keyFilePath nor credentials is provided
+     */
+    constructor({ keyFilePath, credentials, scopes }) {
+        // Validate that at least one authentication method is provided
+        if (!keyFilePath && !credentials) {
+            throw new Error('GoogleDriveConfig: Either keyFilePath or credentials must be provided');
+        }
+        this.keyFilePath = keyFilePath;
+        this.credentials = credentials;
+        this.scopes = scopes || DEFAULT_DRIVE_SCOPES;
+        // Validate credentials structure if provided
+        if (credentials) {
+            this.validateCredentials(credentials);
+        }
+    }
+    /**
+     * Validates that the credentials object contains all required fields.
+     *
+     * @param credentials - The credentials object to validate
+     * @throws Error if required fields are missing
+     */
+    validateCredentials(credentials) {
+        const requiredFields = [
+            'type',
+            'project_id',
+            'private_key',
+            'client_email',
+        ];
+        for (const field of requiredFields) {
+            if (!credentials[field]) {
+                throw new Error(`GoogleDriveConfig: Missing required credential field: ${field}`);
+            }
+        }
+        if (credentials.type !== 'service_account') {
+            throw new Error(`GoogleDriveConfig: Invalid credential type. Expected 'service_account', got '${credentials.type}'`);
+        }
+    }
+    /**
+     * Returns the authentication configuration object suitable for googleapis.
+     *
+     * @returns Authentication options for Google Auth
+     */
+    getAuthOptions() {
+        if (this.keyFilePath) {
+            return {
+                keyFile: this.keyFilePath,
+                scopes: this.scopes,
+            };
+        }
+        return {
+            credentials: this.credentials,
+            scopes: this.scopes,
+        };
+    }
+}
+
+/**
+ * Google Drive Feature Library - Utility Functions
+ * @description Helper functions for file handling, formatting, and validation in Google Drive operations.
+ * @module gg-drive/utils
+ */
+/**
+ * Size units for human-readable byte formatting.
+ */
+const SIZE_UNITS = ['Bytes', 'KB', 'MB', 'GB', 'TB', 'PB'];
+/**
+ * Base value for byte conversions (1024 bytes = 1 KB).
+ */
+const BYTE_BASE = 1024;
+/**
+ * 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"
+ * ```
+ */
+function formatBytes({ bytes }) {
+    if (bytes === 0) {
+        return '0 Bytes';
+    }
+    const exponent = Math.floor(Math.log(bytes) / Math.log(BYTE_BASE));
+    const value = bytes / Math.pow(BYTE_BASE, exponent);
+    const formattedValue = parseFloat(value.toFixed(2));
+    return `${formattedValue} ${SIZE_UNITS[exponent]}`;
+}
+/**
+ * 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)
+ * ```
+ */
+function normalizeFilePath({ filePath }) {
+    // Resolve to absolute path if relative
+    const absolutePath = path__namespace.resolve(filePath);
+    // Normalize path separators for current OS
+    return path__namespace.normalize(absolutePath);
+}
+/**
+ * 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!');
+ * }
+ * ```
+ */
+function validateFileExists({ filePath }) {
+    try {
+        return fs__namespace.existsSync(filePath);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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}`);
+ * }
+ * ```
+ */
+function getFileInfo({ filePath }) {
+    const normalizedPath = normalizeFilePath({ filePath });
+    if (!validateFileExists({ filePath: normalizedPath })) {
+        return null;
+    }
+    const stats = fs__namespace.statSync(normalizedPath);
+    return {
+        name: path__namespace.basename(normalizedPath),
+        extension: path__namespace.extname(normalizedPath).slice(1),
+        directory: path__namespace.dirname(normalizedPath),
+        size: stats.size,
+        sizeFormatted: formatBytes({ bytes: stats.size }),
+    };
+}
+/**
+ * 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: '' });       // []
+ * ```
+ */
+function parseFolderPath({ folderPath }) {
+    if (!folderPath || folderPath === '/' || folderPath === '') {
+        return [];
+    }
+    return folderPath.split('/').filter((folder) => folder.trim() !== '');
+}
+/**
+ * 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
+ * ```
+ */
+function createFileReadStream({ filePath }) {
+    const normalizedPath = normalizeFilePath({ filePath });
+    if (!validateFileExists({ filePath: normalizedPath })) {
+        throw new Error(`File does not exist: ${normalizedPath}`);
+    }
+    return fs__namespace.createReadStream(normalizedPath);
+}
+
+/**
+ * Google Drive Feature Library - Main Client Class
+ * @description A framework-agnostic client for interacting with Google Drive API.
+ * Provides methods for file upload, download, sharing, and storage management.
+ * @module gg-drive/google-drive
+ */
+/**
+ * Google Drive Client for managing files and folders in Google Drive.
+ *
+ * @example
+ * ```typescript
+ * import { GoogleDriveClient } from 'bodevops-features/gg-drive';
+ *
+ * const client = new GoogleDriveClient({
+ *   keyFilePath: './service-account.json'
+ * });
+ *
+ * // Get storage information
+ * const storage = await client.getStorageInfo();
+ * console.log(`Used: ${storage.formattedUsed} of ${storage.formattedTotal}`);
+ *
+ * // Upload a file
+ * const result = await client.uploadFile({
+ *   localFilePath: './document.pdf',
+ *   driveFolder: 'MyFolder/Documents',
+ *   fileName: 'my-document.pdf'
+ * });
+ * console.log(`Uploaded: ${result.webViewLink}`);
+ * ```
+ */
+class GoogleDriveClient {
+    /**
+     * Creates a new GoogleDriveClient instance.
+     *
+     * @param configOptions - Configuration options for the Google Drive client
+     */
+    constructor(configOptions) {
+        this.config = new GoogleDriveConfig(configOptions);
+    }
+    /**
+     * Creates and returns an authenticated Google Drive API client.
+     *
+     * @returns A Promise that resolves to an authenticated Drive API client
+     */
+    async getDriveClient() {
+        const authOptions = this.config.getAuthOptions();
+        const auth = new googleapis.google.auth.GoogleAuth({
+            keyFile: authOptions.keyFile,
+            credentials: authOptions.credentials,
+            scopes: authOptions.scopes,
+        });
+        const authClient = await auth.getClient();
+        return googleapis.google.drive({
+            version: 'v3',
+            auth: authClient,
+        });
+    }
+    /**
+     * Retrieves storage quota information for the Google Drive account.
+     *
+     * @returns A Promise that resolves to storage information including used/total space
+     * @throws Error if unable to retrieve storage information
+     *
+     * @example
+     * ```typescript
+     * const storage = await client.getStorageInfo();
+     * console.log(`Storage: ${storage.formattedUsed} / ${storage.formattedTotal} (${storage.percentage}%)`);
+     * ```
+     */
+    async getStorageInfo() {
+        const driveInstance = await this.getDriveClient();
+        const response = await driveInstance.about.get({
+            fields: 'storageQuota',
+        });
+        const quota = response.data.storageQuota;
+        if (!quota) {
+            throw new Error('Unable to retrieve storage quota information');
+        }
+        const used = parseInt(quota.usage || '0', 10);
+        const total = parseInt(quota.limit || '0', 10);
+        const usedInDrive = parseInt(quota.usageInDrive || '0', 10);
+        const percentage = total > 0 ? (used / total) * 100 : 0;
+        return {
+            used,
+            total,
+            usedInDrive,
+            percentage: parseFloat(percentage.toFixed(2)),
+            formattedUsed: formatBytes({ bytes: used }),
+            formattedTotal: formatBytes({ bytes: total }),
+            formattedUsedInDrive: formatBytes({ bytes: usedInDrive }),
+        };
+    }
+    /**
+     * Gets an existing folder by name or creates it if it doesn't exist.
+     *
+     * @param folderName - The name of the folder to find or create
+     * @param parentId - The ID of the parent folder (default: 'root')
+     * @returns A Promise that resolves to the folder ID
+     */
+    async getOrCreateFolder({ folderName, parentId = 'root', }) {
+        const driveInstance = await this.getDriveClient();
+        // Search for existing folder
+        const query = `name='${folderName}' and mimeType='application/vnd.google-apps.folder' and '${parentId}' in parents and trashed=false`;
+        const response = await driveInstance.files.list({
+            q: query,
+            fields: 'files(id, name)',
+        });
+        const folders = response.data.files || [];
+        if (folders.length > 0 && folders[0].id) {
+            // Folder exists, return its ID
+            return folders[0].id;
+        }
+        // Folder doesn't exist, create it
+        const folderMetadata = {
+            name: folderName,
+            mimeType: 'application/vnd.google-apps.folder',
+            parents: [parentId],
+        };
+        const folder = await driveInstance.files.create({
+            requestBody: folderMetadata,
+            fields: 'id',
+        });
+        if (!folder.data.id) {
+            throw new Error(`Failed to create folder: ${folderName}`);
+        }
+        return folder.data.id;
+    }
+    /**
+     * Creates a folder hierarchy from a path string (e.g., "a/b/c") and returns the ID of the final folder.
+     *
+     * @param folderPath - The folder path to create (e.g., "folder1/folder2/folder3")
+     * @returns A Promise that resolves to the ID of the innermost folder
+     */
+    async createFolderHierarchy({ folderPath }) {
+        const folders = parseFolderPath({ folderPath });
+        if (folders.length === 0) {
+            return 'root';
+        }
+        let currentParentId = 'root';
+        for (const folderName of folders) {
+            currentParentId = await this.getOrCreateFolder({
+                folderName,
+                parentId: currentParentId,
+            });
+        }
+        return currentParentId;
+    }
+    /**
+     * Uploads a file to Google Drive and automatically makes it public.
+     *
+     * @param params - Upload parameters including local file path and destination folder
+     * @returns A Promise that resolves to the upload result containing file ID and links
+     * @throws Error if the local file doesn't exist or upload fails
+     *
+     * @example
+     * ```typescript
+     * const result = await client.uploadFile({
+     *   localFilePath: './document.pdf',
+     *   driveFolder: 'MyFolder/Documents',
+     *   fileName: 'my-document.pdf'  // Optional
+     * });
+     * console.log(`View at: ${result.webViewLink}`);
+     * ```
+     */
+    async uploadFile({ localFilePath, driveFolder, fileName, }) {
+        // Normalize and validate the local file path
+        const normalizedPath = normalizeFilePath({ filePath: localFilePath });
+        if (!validateFileExists({ filePath: normalizedPath })) {
+            throw new Error(`File does not exist: ${normalizedPath}. Please check the file path and ensure the file exists.`);
+        }
+        // Use the local filename if fileName is not provided
+        const finalFileName = fileName || normalizedPath.split(/[\\/]/).pop() || 'unnamed';
+        const driveInstance = await this.getDriveClient();
+        // Create the folder hierarchy and get the ID of the innermost folder
+        const folderId = await this.createFolderHierarchy({ folderPath: driveFolder });
+        // File metadata
+        const fileMetadata = {
+            name: finalFileName,
+            parents: [folderId],
+        };
+        // Create media upload
+        const media = {
+            mimeType: 'application/octet-stream',
+            body: createFileReadStream({ filePath: normalizedPath }),
+        };
+        const file = await driveInstance.files.create({
+            requestBody: fileMetadata,
+            media: media,
+            fields: 'id, name, webViewLink, webContentLink',
+        });
+        const result = {
+            id: file.data.id || '',
+            name: file.data.name || '',
+            webViewLink: file.data.webViewLink || undefined,
+            webContentLink: file.data.webContentLink || undefined,
+        };
+        // Always make file public
+        await this.makeFilePublic({ fileId: result.id });
+        return result;
+    }
+    /**
+     * Uploads a file and shares it with a specified email address.
+     *
+     * @param params - Upload and share parameters
+     * @returns A Promise that resolves to the upload result
+     *
+     * @example
+     * ```typescript
+     * const result = await client.uploadFileAndShare({
+     *   localFilePath: './report.pdf',
+     *   driveFolder: 'SharedReports',
+     *   shareWithEmail: 'colleague@example.com',
+     *   role: 'writer'
+     * });
+     * ```
+     */
+    async uploadFileAndShare({ localFilePath, driveFolder, fileName, shareWithEmail, role = 'reader', }) {
+        // Upload file normally
+        const result = await this.uploadFile({
+            localFilePath,
+            driveFolder,
+            fileName,
+        });
+        // Get folder ID and share it with specified role
+        const folderId = await this.getFolderIdByPath({ folderPath: driveFolder });
+        await this.shareFolderWithEmail({
+            folderId,
+            emailAddress: shareWithEmail,
+            role,
+        });
+        return result;
+    }
+    /**
+     * Deletes a file from Google Drive.
+     * Note: Only the file owner can delete the file.
+     *
+     * @param params - Delete parameters including file ID
+     * @returns A Promise that resolves to true if deletion was successful
+     * @throws Error if deletion fails (e.g., permission denied)
+     *
+     * @example
+     * ```typescript
+     * await client.deleteFile({ fileId: '1abc123def456' });
+     * ```
+     */
+    async deleteFile({ fileId }) {
+        const driveInstance = await this.getDriveClient();
+        await driveInstance.files.delete({
+            fileId: fileId,
+        });
+        return true;
+    }
+    /**
+     * Lists all files and folders in a specified folder.
+     *
+     * @param params - List parameters including folder ID
+     * @returns A Promise that resolves to an array of file information objects
+     *
+     * @example
+     * ```typescript
+     * const files = await client.listFilesInFolder({ folderId: 'root' });
+     * for (const file of files) {
+     *   console.log(`${file.name} (${file.mimeType})`);
+     * }
+     * ```
+     */
+    async listFilesInFolder({ folderId = 'root' } = {}) {
+        const driveInstance = await this.getDriveClient();
+        const query = `'${folderId}' in parents and trashed=false`;
+        const response = await driveInstance.files.list({
+            q: query,
+            fields: 'files(id, name, mimeType, webViewLink, parents)',
+            orderBy: 'name',
+        });
+        const files = response.data.files || [];
+        return files.map((file) => ({
+            id: file.id || '',
+            name: file.name || '',
+            mimeType: file.mimeType || '',
+            webViewLink: file.webViewLink || undefined,
+            parents: file.parents || undefined,
+        }));
+    }
+    /**
+     * Makes a file publicly accessible to anyone with the link.
+     *
+     * @param params - Parameters including file ID
+     * @returns A Promise that resolves to true if successful
+     *
+     * @example
+     * ```typescript
+     * await client.makeFilePublic({ fileId: '1abc123def456' });
+     * // File is now accessible via its webViewLink
+     * ```
+     */
+    async makeFilePublic({ fileId }) {
+        const driveInstance = await this.getDriveClient();
+        await driveInstance.permissions.create({
+            fileId: fileId,
+            requestBody: {
+                role: 'reader',
+                type: 'anyone',
+            },
+        });
+        return true;
+    }
+    /**
+     * Transfers ownership of a file to another user.
+     *
+     * @param params - Transfer parameters including file ID and new owner email
+     * @returns A Promise that resolves to true if successful
+     *
+     * @example
+     * ```typescript
+     * await client.transferFileOwnership({
+     *   fileId: '1abc123def456',
+     *   newOwnerEmail: 'newowner@example.com'
+     * });
+     * ```
+     */
+    async transferFileOwnership({ fileId, newOwnerEmail, role = 'reader', }) {
+        const driveInstance = await this.getDriveClient();
+        await driveInstance.permissions.create({
+            fileId: fileId,
+            requestBody: {
+                role: role,
+                type: 'user',
+                emailAddress: newOwnerEmail,
+            },
+            transferOwnership: true,
+            sendNotificationEmail: true,
+        });
+        return true;
+    }
+    /**
+     * Shares a folder with a specified email address.
+     *
+     * @param params - Share parameters including folder ID, email, and role
+     * @returns A Promise that resolves to true if successful
+     *
+     * @example
+     * ```typescript
+     * await client.shareFolderWithEmail({
+     *   folderId: '1abc123def456',
+     *   emailAddress: 'user@example.com',
+     *   role: 'writer'
+     * });
+     * ```
+     */
+    async shareFolderWithEmail({ folderId, emailAddress, role = 'writer', }) {
+        const driveInstance = await this.getDriveClient();
+        const requestBody = {
+            role: role,
+            type: 'user',
+            emailAddress: emailAddress,
+        };
+        const requestOptions = {
+            fileId: folderId,
+            requestBody: requestBody,
+        };
+        // Configure notification email based on role
+        if (role === 'owner') {
+            requestOptions.transferOwnership = true;
+            requestOptions.sendNotificationEmail = true;
+        }
+        else {
+            requestOptions.sendNotificationEmail = false;
+        }
+        await driveInstance.permissions.create(requestOptions);
+        return true;
+    }
+    /**
+     * Gets a folder ID by its path, creating the folder hierarchy if it doesn't exist.
+     *
+     * @param params - Parameters including folder path
+     * @returns A Promise that resolves to the folder ID
+     *
+     * @example
+     * ```typescript
+     * const folderId = await client.getFolderIdByPath({
+     *   folderPath: 'folder1/folder2/folder3'
+     * });
+     * ```
+     */
+    async getFolderIdByPath({ folderPath }) {
+        return this.createFolderHierarchy({ folderPath });
+    }
+    /**
+     * Checks if a file with the specified name exists in a folder.
+     *
+     * @param params - Parameters including file name and folder ID
+     * @returns A Promise that resolves to the file ID if found, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const fileId = await client.fileExistsInFolder({
+     *   fileName: 'document.pdf',
+     *   folderId: 'root'
+     * });
+     * if (fileId) {
+     *   console.log(`File exists with ID: ${fileId}`);
+     * }
+     * ```
+     */
+    async fileExistsInFolder({ fileName, folderId = 'root', }) {
+        const driveInstance = await this.getDriveClient();
+        const query = `name='${fileName}' and '${folderId}' in parents and trashed=false`;
+        const response = await driveInstance.files.list({
+            q: query,
+            fields: 'files(id, name)',
+        });
+        const files = response.data.files || [];
+        if (files.length > 0 && files[0].id) {
+            return files[0].id;
+        }
+        return null;
+    }
+}
+
+/**
+ * Google Drive Feature Library
+ * @description A framework-agnostic library for interacting with Google Drive API.
+ * Provides easy-to-use methods for file upload, sharing, and storage management.
+ * @module gg-drive
+ *
+ * @example
+ * ```typescript
+ * import { GoogleDriveClient } from 'bodevops-features/gg-drive';
+ *
+ * const client = new GoogleDriveClient({
+ *   keyFilePath: './service-account.json'
+ * });
+ *
+ * // Upload a file
+ * const result = await client.uploadFile({
+ *   localFilePath: './document.pdf',
+ *   driveFolder: 'MyFolder/Documents'
+ * });
+ *
+ * // Get storage info
+ * const storage = await client.getStorageInfo();
+ * console.log(`Used: ${storage.formattedUsed}`);
+ * ```
+ */
+// Export main client class
+
+var index$1 = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    DEFAULT_DRIVE_SCOPES: DEFAULT_DRIVE_SCOPES,
+    GoogleDriveClient: GoogleDriveClient,
+    GoogleDriveConfig: GoogleDriveConfig,
+    createFileReadStream: createFileReadStream,
+    formatBytes: formatBytes,
+    getFileInfo: getFileInfo,
+    normalizeFilePath: normalizeFilePath,
+    parseFolderPath: parseFolderPath,
+    validateFileExists: validateFileExists
+});
+
+/**
+ * Google Sheet Feature Library - Configuration Module
+ * @description Configuration management for Google Sheet client initialization and authentication.
+ * @module gg-sheet/config
+ */
+/**
+ * Default OAuth scope required for Google Sheets operations.
+ */
+const DEFAULT_SHEET_SCOPES = ['https://www.googleapis.com/auth/spreadsheets'];
+/**
+ * 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
+ *   }
+ * });
+ * ```
+ */
+class GoogleSheetConfig {
+    /**
+     * 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 }) {
+        // Validate that at least one authentication method is provided
+        if (!keyFilePath && !credentials) {
+            throw new Error('GoogleSheetConfig: Either keyFilePath or credentials must be provided');
+        }
+        this.keyFilePath = keyFilePath;
+        this.credentials = credentials;
+        this.scopes = scopes || DEFAULT_SHEET_SCOPES;
+        // Validate credentials structure if provided
+        if (credentials) {
+            this.validateCredentials(credentials);
+        }
+    }
+    /**
+     * Validates that the credentials object contains all required fields.
+     *
+     * @param credentials - The credentials object to validate
+     * @throws Error if required fields are missing
+     */
+    validateCredentials(credentials) {
+        const requiredFields = [
+            'type',
+            'project_id',
+            'private_key',
+            'client_email',
+        ];
+        for (const field of requiredFields) {
+            if (!credentials[field]) {
+                throw new Error(`GoogleSheetConfig: Missing required credential field: ${field}`);
+            }
+        }
+        if (credentials.type !== 'service_account') {
+            throw new Error(`GoogleSheetConfig: Invalid credential type. Expected 'service_account', got '${credentials.type}'`);
+        }
+    }
+    /**
+     * Returns the authentication configuration object suitable for googleapis.
+     *
+     * @returns Authentication options for Google Auth
+     */
+    getAuthOptions() {
+        if (this.keyFilePath) {
+            return {
+                keyFile: this.keyFilePath,
+                scopes: this.scopes,
+            };
+        }
+        return {
+            credentials: this.credentials,
+            scopes: this.scopes,
+        };
+    }
+}
+
+/**
+ * Google Sheet Feature Library - Type Definitions
+ * @description Type definitions for Google Sheet operations including reading, writing, and exporting data.
+ * @module gg-sheet/types
+ */
+/**
+ * Export type enumeration for sheet export operations.
+ */
+var ETypeExport;
+(function (ETypeExport) {
+    /** Append data to the end of existing data */
+    ETypeExport["Append"] = "Append";
+    /** Overwrite all existing data starting from row 1 */
+    ETypeExport["Overwrite"] = "Overwrite";
+})(ETypeExport || (ETypeExport = {}));
+
+/**
+ * Google Sheet Feature Library - Utility Functions
+ * @description Helper functions for sheet operations, column conversion, and data transformation.
+ * @module gg-sheet/utils
+ */
+/**
+ * Regular expression pattern to extract spreadsheet ID from a Google Sheets URL.
+ */
+const SPREADSHEET_ID_PATTERN = /\/spreadsheets\/d\/([a-zA-Z0-9-_]+)/;
+/**
+ * Extracts the spreadsheet ID from a Google Sheets URL.
+ *
+ * @param sheetUrl - The full URL of the Google Spreadsheet
+ * @returns The spreadsheet ID or null if not found
+ *
+ * @example
+ * ```typescript
+ * const id = getSheetIdFromUrl({
+ *   sheetUrl: 'https://docs.google.com/spreadsheets/d/1abc123def/edit'
+ * });
+ * // Returns: '1abc123def'
+ * ```
+ */
+function getSheetIdFromUrl({ sheetUrl }) {
+    const match = sheetUrl.match(SPREADSHEET_ID_PATTERN);
+    if (match && match[1]) {
+        return match[1];
+    }
+    return null;
+}
+/**
+ * Converts a 0-based column index to a column letter (e.g., 0 → A, 25 → Z, 26 → AA).
+ *
+ * @param columnIndex - The 0-based column index
+ * @returns The column letter(s) (e.g., "A", "B", "AA", "AB")
+ *
+ * @example
+ * ```typescript
+ * convertIndexToColumnName({ columnIndex: 0 });  // "A"
+ * convertIndexToColumnName({ columnIndex: 25 }); // "Z"
+ * convertIndexToColumnName({ columnIndex: 26 }); // "AA"
+ * convertIndexToColumnName({ columnIndex: 701 }); // "ZZ"
+ * ```
+ */
+function convertIndexToColumnName({ columnIndex }) {
+    let columnName = '';
+    let index = columnIndex;
+    while (index >= 0) {
+        columnName = String.fromCharCode((index % 26) + 'A'.charCodeAt(0)) + columnName;
+        index = Math.floor(index / 26) - 1;
+    }
+    return columnName;
+}
+/**
+ * Converts a column letter to a 0-based column index (e.g., A → 0, Z → 25, AA → 26).
+ *
+ * @param columnName - The column letter(s) (e.g., "A", "B", "AA")
+ * @returns The 0-based column index
+ * @throws Error if the column name contains invalid characters
+ *
+ * @example
+ * ```typescript
+ * convertColumnNameToIndex({ columnName: 'A' });  // 0
+ * convertColumnNameToIndex({ columnName: 'Z' });  // 25
+ * convertColumnNameToIndex({ columnName: 'AA' }); // 26
+ * convertColumnNameToIndex({ columnName: 'ZZ' }); // 701
+ * ```
+ */
+function convertColumnNameToIndex({ columnName }) {
+    // Convert to uppercase to handle both lower and upper case
+    const upperColumnName = columnName.toUpperCase().trim();
+    // Validate input - only accept A-Z characters
+    if (!/^[A-Z]+$/.test(upperColumnName)) {
+        throw new Error(`Invalid column name: '${columnName}'. Only letters A-Z are allowed.`);
+    }
+    let result = 0;
+    for (let i = 0; i < upperColumnName.length; i++) {
+        const charCode = upperColumnName.charCodeAt(i) - 'A'.charCodeAt(0);
+        result = result * 26 + (charCode + 1);
+    }
+    // Convert to 0-based index
+    return result - 1;
+}
+/**
+ * Converts raw sheet values (2D array) into an array of typed objects.
+ * Uses the first row (or row at rowOffset) as keys for the objects.
+ *
+ * @param values - Raw 2D array from sheet
+ * @param rowOffset - Number of rows to skip before the header row (default: 0)
+ * @returns Array of typed objects, or null if values is null/undefined
+ *
+ * @example
+ * ```typescript
+ * const rawData = [
+ *   ['name', 'age', 'email'],
+ *   ['John', '30', 'john@example.com'],
+ *   ['Jane', '25', 'jane@example.com']
+ * ];
+ *
+ * interface Person { name: string; age: string; email: string; }
+ *
+ * const people = convertValueSheet<Person>({ values: rawData });
+ * // Returns: [
+ * //   { name: 'John', age: '30', email: 'john@example.com' },
+ * //   { name: 'Jane', age: '25', email: 'jane@example.com' }
+ * // ]
+ * ```
+ */
+function convertValueSheet({ values, rowOffset = 0, }) {
+    if (!values || values.length === 0) {
+        return null;
+    }
+    // Get header row (keys for the objects)
+    const keys = values[rowOffset];
+    if (!keys || keys.length === 0) {
+        return null;
+    }
+    // Map remaining rows to objects
+    return values.slice(rowOffset + 1).map((row) => {
+        return keys.reduce((acc, key, index) => {
+            acc[key] = row[index] || '';
+            return acc;
+        }, {});
+    });
+}
+/**
+ * Gets the index of a column key in the list of keys.
+ *
+ * @param key - The key to find
+ * @param listKeys - Array of all keys
+ * @returns The index of the key, or -1 if not found
+ *
+ * @example
+ * ```typescript
+ * interface Person { id: string; name: string; email: string; }
+ * const keys: (keyof Person)[] = ['id', 'name', 'email'];
+ *
+ * getIndexCol({ key: 'name', listKeys: keys }); // 1
+ * getIndexCol({ key: 'email', listKeys: keys }); // 2
+ * ```
+ */
+function getIndexCol({ key, listKeys }) {
+    return listKeys.indexOf(key);
+}
+/**
+ * Extracts column headers and data values from a result set for export.
+ * Takes an object mapping field keys to column names and an array of items.
+ *
+ * @param colsForSheet - Object mapping field keys to column header names
+ * @param resultItems - Array of items to export
+ * @returns Object containing listCols (headers) and valsExport (data matrix)
+ *
+ * @example
+ * ```typescript
+ * const colsMapping = { id: 'ID', name: 'Full Name', email: 'Email Address' };
+ * const items = [
+ *   { id: '1', name: 'John Doe', email: 'john@example.com' },
+ *   { id: '2', name: 'Jane Doe', email: 'jane@example.com' }
+ * ];
+ *
+ * const { listCols, valsExport } = getListColsAndValsExport({
+ *   colsForSheet: colsMapping,
+ *   resultItems: items
+ * });
+ * // listCols: ['ID', 'Full Name', 'Email Address']
+ * // valsExport: [['1', 'John Doe', 'john@example.com'], ['2', 'Jane Doe', 'jane@example.com']]
+ * ```
+ */
+function getListColsAndValsExport({ colsForSheet, resultItems, }) {
+    // Extract column headers from the mapping values
+    const listCols = Object.values(colsForSheet);
+    // Extract data rows
+    const valsExport = [];
+    for (const item of resultItems) {
+        const row = [];
+        // Iterate through colsForSheet keys to ensure correct order
+        for (const fieldKey of Object.keys(colsForSheet)) {
+            const fieldValue = item[fieldKey];
+            // Convert value to string, handling different data types
+            let cellValue = '';
+            if (fieldValue === null || fieldValue === undefined) {
+                cellValue = '';
+            }
+            else if (fieldValue instanceof Date) {
+                cellValue = fieldValue.toISOString();
+            }
+            else if (typeof fieldValue === 'object') {
+                // Handle nested objects (like relations)
+                cellValue = JSON.stringify(fieldValue);
+            }
+            else {
+                cellValue = String(fieldValue);
+            }
+            row.push(cellValue);
+        }
+        valsExport.push(row);
+    }
+    return { listCols, valsExport };
+}
+/**
+ * Validates that a sheet URL is in the correct format.
+ *
+ * @param sheetUrl - The URL to validate
+ * @returns True if the URL is valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidSheetUrl({ sheetUrl: 'https://docs.google.com/spreadsheets/d/1abc123/edit' }); // true
+ * isValidSheetUrl({ sheetUrl: 'https://example.com/sheet' }); // false
+ * ```
+ */
+function isValidSheetUrl({ sheetUrl }) {
+    return SPREADSHEET_ID_PATTERN.test(sheetUrl);
+}
+/**
+ * Calculates the actual row index in the sheet based on the data row index and offset.
+ * This accounts for header row(s) and any additional offset rows.
+ *
+ * @param dataRowIndex - The 0-based index in the data (not counting headers)
+ * @param rowOffset - Additional rows to skip after the header (default: 0)
+ * @returns The 1-based row number in the actual sheet
+ *
+ * @example
+ * ```typescript
+ * // With rowOffset=0: header at row 1, data starts at row 2
+ * calculateActualRow({ dataRowIndex: 0, rowOffset: 0 }); // 2 (first data row)
+ * calculateActualRow({ dataRowIndex: 5, rowOffset: 0 }); // 7 (sixth data row)
+ *
+ * // With rowOffset=1: header at row 1, skip row 2, data starts at row 3
+ * calculateActualRow({ dataRowIndex: 0, rowOffset: 1 }); // 3 (first data row)
+ * ```
+ */
+function calculateActualRow({ dataRowIndex, rowOffset = 0, }) {
+    // Row 1 is header, so data starts at row 2
+    // Add 2 for: 0-based to 1-based conversion + header row
+    return dataRowIndex + 2 + rowOffset;
+}
+
+/**
+ * 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
+ */
+/**
+ * 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' }
+ *   ]
+ * });
+ * ```
+ */
+class GoogleSheetClient {
+    /**
+     * Creates a new GoogleSheetClient instance.
+     *
+     * @param configOptions - Configuration options for the Google Sheet client
+     */
+    constructor(configOptions) {
+        this.config = new GoogleSheetConfig(configOptions);
+    }
+    /**
+     * Creates and returns an authenticated Google Sheets API client.
+     *
+     * @returns A Promise that resolves to an authenticated Sheets API client
+     */
+    async getSheetsClient() {
+        const authOptions = this.config.getAuthOptions();
+        const auth = new googleapis.google.auth.GoogleAuth({
+            keyFile: authOptions.keyFile,
+            credentials: authOptions.credentials,
+            scopes: authOptions.scopes,
+        });
+        const authClient = await auth.getClient();
+        return googleapis.google.sheets({
+            version: 'v4',
+            auth: authClient,
+        });
+    }
+    /**
+     * 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
+     */
+    extractSheetId({ sheetUrl }) {
+        const sheetId = getSheetIdFromUrl({ sheetUrl });
+        if (!sheetId) {
+            throw new Error(`Invalid Google Sheet URL: ${sheetUrl}`);
+        }
+        return sheetId;
+    }
+    /**
+     * 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(', ')}`);
+     * ```
+     */
+    async getSheetInfo({ sheetUrl }) {
+        const sheetsInstance = await this.getSheetsClient();
+        const spreadsheetId = this.extractSheetId({ sheetUrl });
+        const response = await sheetsInstance.spreadsheets.get({
+            spreadsheetId,
+            includeGridData: false,
+        });
+        const spreadsheetTitle = response.data.properties?.title || '';
+        const sheets = response.data.sheets?.map((sheet) => ({
+            title: sheet.properties?.title || '',
+            sheetId: sheet.properties?.sheetId || 0,
+            rowCount: sheet.properties?.gridProperties?.rowCount || 0,
+            columnCount: sheet.properties?.gridProperties?.columnCount || 0,
+        })) || [];
+        return {
+            spreadsheetTitle,
+            sheets,
+        };
+    }
+    /**
+     * 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(', '));
+     * }
+     * ```
+     */
+    async getValues({ sheetUrl, sheetName, endRow }) {
+        const sheetsInstance = await this.getSheetsClient();
+        const spreadsheetId = this.extractSheetId({ sheetUrl });
+        // Get sheet info to determine column count
+        const sheetInfo = await this.getSheetInfo({ sheetUrl });
+        const sheet = sheetInfo.sheets.find((s) => s.title === sheetName);
+        if (!sheet) {
+            throw new Error(`Sheet not found: ${sheetName}`);
+        }
+        // Build the range
+        let range = sheetName;
+        if (endRow) {
+            const endCol = convertIndexToColumnName({
+                columnIndex: sheet.columnCount - 1,
+            });
+            range = `${sheetName}!A1:${endCol}${endRow}`;
+        }
+        const result = await sheetsInstance.spreadsheets.values.get({
+            spreadsheetId,
+            range,
+        });
+        return result.data.values || [];
+    }
+    /**
+     * 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}`);
+     * }
+     * ```
+     */
+    async getIdxRow({ sheetUrl, sheetName, colName, value, }) {
+        const sheetsInstance = await this.getSheetsClient();
+        const spreadsheetId = this.extractSheetId({ sheetUrl });
+        // Get sheet info to determine row count
+        const sheetInfo = await this.getSheetInfo({ sheetUrl });
+        const sheet = sheetInfo.sheets.find((s) => s.title === sheetName);
+        if (!sheet) {
+            throw new Error(`Sheet not found: ${sheetName}`);
+        }
+        const range = `${sheetName}!${colName}1:${colName}${sheet.rowCount}`;
+        const result = await sheetsInstance.spreadsheets.values.get({
+            spreadsheetId,
+            range,
+        });
+        const values = result.data.values || [];
+        // Find the index (0-based)
+        const index = values.findIndex((row) => {
+            if (!row || row.length === 0)
+                return false;
+            return row[0] === value;
+        });
+        return index;
+    }
+    /**
+     * 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
+     * });
+     * ```
+     */
+    async export({ sheetUrl, sheetName, listCols, valsExport, typeExport, }) {
+        const sheetsInstance = await this.getSheetsClient();
+        const spreadsheetId = this.extractSheetId({ sheetUrl });
+        if (typeExport === ETypeExport.Overwrite) {
+            return this.executeOverwriteExport({
+                sheetsInstance,
+                spreadsheetId,
+                sheetName,
+                listCols,
+                valsExport,
+            });
+        }
+        else if (typeExport === ETypeExport.Append) {
+            return this.executeAppendExport({
+                sheetsInstance,
+                spreadsheetId,
+                sheetName,
+                listCols,
+                valsExport,
+            });
+        }
+        else {
+            throw new Error(`Invalid export type: ${typeExport}`);
+        }
+    }
+    /**
+     * Executes an overwrite export - writes headers and data from row 1.
+     */
+    async executeOverwriteExport({ sheetsInstance, spreadsheetId, sheetName, listCols, valsExport, }) {
+        // Prepare data matrix: headers + data rows
+        const exportData = [listCols, ...valsExport];
+        const numCols = listCols.length;
+        const numRows = exportData.length;
+        // Calculate range: A1 to [LastCol][LastRow]
+        const endCol = convertIndexToColumnName({ columnIndex: numCols - 1 });
+        const range = `${sheetName}!A1:${endCol}${numRows}`;
+        await sheetsInstance.spreadsheets.values.batchUpdate({
+            spreadsheetId,
+            requestBody: {
+                valueInputOption: 'RAW',
+                data: [
+                    {
+                        range,
+                        values: exportData,
+                    },
+                ],
+            },
+        });
+        return true;
+    }
+    /**
+     * Executes an append export - finds empty rows and appends data.
+     */
+    async executeAppendExport({ sheetsInstance, spreadsheetId, sheetName, listCols, valsExport, }) {
+        // Get sheet info to determine max rows
+        const sheetInfo = await sheetsInstance.spreadsheets.get({
+            spreadsheetId,
+            ranges: [sheetName],
+            includeGridData: false,
+        });
+        const sheet = sheetInfo.data.sheets?.find((s) => s.properties?.title === sheetName);
+        const maxRows = sheet?.properties?.gridProperties?.rowCount || 1000;
+        // Read current data to find the last used row
+        const readRange = `${sheetName}!A1:A${maxRows}`;
+        const readResponse = await sheetsInstance.spreadsheets.values.get({
+            spreadsheetId,
+            range: readRange,
+        });
+        const currentData = readResponse.data.values || [];
+        // Find the first empty row (last row with data + 1)
+        let startRow = 1;
+        if (currentData.length > 0) {
+            let lastUsedRow = 0;
+            for (let i = currentData.length - 1; i >= 0; i--) {
+                if (currentData[i] &&
+                    currentData[i].length > 0 &&
+                    currentData[i][0] &&
+                    String(currentData[i][0]).trim() !== '') {
+                    lastUsedRow = i + 1;
+                    break;
+                }
+            }
+            startRow = lastUsedRow + 1;
+        }
+        // Check if we need to write headers
+        let dataToWrite = valsExport;
+        const writeStartRow = startRow;
+        // If sheet is empty, include headers
+        if (startRow === 1) {
+            dataToWrite = [listCols, ...valsExport];
+        }
+        // Calculate range for writing
+        const numCols = listCols.length;
+        const numRows = dataToWrite.length;
+        const endCol = convertIndexToColumnName({ columnIndex: numCols - 1 });
+        const endRow = writeStartRow + numRows - 1;
+        const writeRange = `${sheetName}!A${writeStartRow}:${endCol}${endRow}`;
+        await sheetsInstance.spreadsheets.values.batchUpdate({
+            spreadsheetId,
+            requestBody: {
+                valueInputOption: 'RAW',
+                data: [
+                    {
+                        range: writeRange,
+                        values: dataToWrite,
+                    },
+                ],
+            },
+        });
+        return true;
+    }
+    /**
+     * 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
+     * });
+     * ```
+     */
+    async updateValuesMultiCells({ sheetUrl, sheetName, cells, rowOffset = 0, }) {
+        if (!cells || cells.length === 0) {
+            throw new Error('No cells provided for update');
+        }
+        const sheetsInstance = await this.getSheetsClient();
+        const spreadsheetId = this.extractSheetId({ sheetUrl });
+        // Create update requests for each cell
+        const requests = cells.map((cell) => {
+            const colName = convertIndexToColumnName({ columnIndex: cell.col });
+            const actualRow = calculateActualRow({
+                dataRowIndex: cell.row,
+                rowOffset,
+            });
+            const sheetRange = `${sheetName}!${colName}${actualRow}`;
+            return {
+                range: sheetRange,
+                values: [[cell.content]],
+            };
+        });
+        await sheetsInstance.spreadsheets.values.batchUpdate({
+            spreadsheetId,
+            requestBody: {
+                valueInputOption: 'RAW',
+                data: requests,
+            },
+        });
+        return true;
+    }
+    /**
+     * 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' }
+     *   ]
+     * });
+     * ```
+     */
+    async updateValuesMultiColsByRow({ sheetUrl, sheetName, row, values, rowOffset = 0, }) {
+        if (!values || values.length === 0) {
+            throw new Error('No values provided for update');
+        }
+        const sheetsInstance = await this.getSheetsClient();
+        const spreadsheetId = this.extractSheetId({ sheetUrl });
+        const actualRow = calculateActualRow({ dataRowIndex: row, rowOffset });
+        const requests = values.map((valPair) => {
+            const colName = convertIndexToColumnName({ columnIndex: valPair.col });
+            const sheetRange = `${sheetName}!${colName}${actualRow}`;
+            return {
+                range: sheetRange,
+                values: [[valPair.content]],
+            };
+        });
+        await sheetsInstance.spreadsheets.values.batchUpdate({
+            spreadsheetId,
+            requestBody: {
+                valueInputOption: 'RAW',
+                data: requests,
+            },
+        });
+        return true;
+    }
+    /**
+     * 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' }
+     *   ]
+     * });
+     * ```
+     */
+    async updateValuesMultiRowsByCol({ sheetUrl, sheetName, col, values, rowOffset = 0, }) {
+        if (!values || values.length === 0) {
+            throw new Error('No values provided for update');
+        }
+        const sheetsInstance = await this.getSheetsClient();
+        const spreadsheetId = this.extractSheetId({ sheetUrl });
+        const colName = convertIndexToColumnName({ columnIndex: col });
+        const requests = values.map((valPair) => {
+            const actualRow = calculateActualRow({
+                dataRowIndex: valPair.row,
+                rowOffset,
+            });
+            const sheetRange = `${sheetName}!${colName}${actualRow}`;
+            return {
+                range: sheetRange,
+                values: [[valPair.content]],
+            };
+        });
+        await sheetsInstance.spreadsheets.values.batchUpdate({
+            spreadsheetId,
+            requestBody: {
+                valueInputOption: 'RAW',
+                data: requests,
+            },
+        });
+        return true;
+    }
+    /**
+     * 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
+     * });
+     * ```
+     */
+    async updateValuesMultiRowsMultiCols({ sheetUrl, sheetName, values, startRow = 0, endRow, startCol = 0, rowOffset = 0, }) {
+        if (!values || values.length === 0 || values[0].length === 0) {
+            throw new Error('Invalid values matrix: no data to update');
+        }
+        const sheetsInstance = await this.getSheetsClient();
+        const spreadsheetId = this.extractSheetId({ sheetUrl });
+        const numRows = values.length;
+        const numCols = values[0].length;
+        const startColName = convertIndexToColumnName({ columnIndex: startCol });
+        const endColName = convertIndexToColumnName({
+            columnIndex: startCol + numCols - 1,
+        });
+        const startRowIndex = calculateActualRow({
+            dataRowIndex: startRow,
+            rowOffset,
+        });
+        let endRowIndex;
+        if (endRow !== undefined) {
+            endRowIndex = calculateActualRow({ dataRowIndex: endRow, rowOffset });
+        }
+        else {
+            endRowIndex = startRowIndex + numRows - 1;
+        }
+        const sheetRange = `${sheetName}!${startColName}${startRowIndex}:${endColName}${endRowIndex}`;
+        await sheetsInstance.spreadsheets.values.batchUpdate({
+            spreadsheetId,
+            requestBody: {
+                valueInputOption: 'RAW',
+                data: [
+                    {
+                        range: sheetRange,
+                        values,
+                    },
+                ],
+            },
+        });
+        return true;
+    }
+    /**
+     * 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
+     * });
+     * ```
+     */
+    async deleteRowSheet({ sheetUrl, sheetName, row, rowOffset = 0, }) {
+        const sheetsInstance = await this.getSheetsClient();
+        const spreadsheetId = this.extractSheetId({ sheetUrl });
+        // Get sheet ID
+        const sheetInfo = await sheetsInstance.spreadsheets.get({
+            spreadsheetId,
+            ranges: [sheetName],
+            includeGridData: false,
+        });
+        const sheet = sheetInfo.data.sheets?.find((s) => s.properties?.title === sheetName);
+        const sheetId = sheet?.properties?.sheetId;
+        if (sheetId === undefined || sheetId === null) {
+            throw new Error(`Sheet not found: ${sheetName}`);
+        }
+        // Calculate actual row index
+        // +1 for header row, +rowOffset
+        const actualRowIndex = row + 1 + rowOffset;
+        const request = {
+            deleteDimension: {
+                range: {
+                    sheetId,
+                    dimension: 'ROWS',
+                    startIndex: actualRowIndex,
+                    endIndex: actualRowIndex + 1,
+                },
+            },
+        };
+        await sheetsInstance.spreadsheets.batchUpdate({
+            spreadsheetId,
+            requestBody: {
+                requests: [request],
+            },
+        });
+        return true;
+    }
+}
+
+/**
+ * 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 main client class
 
 var index = /*#__PURE__*/Object.freeze({
     __proto__: null,
-    test: test
+    DEFAULT_SHEET_SCOPES: DEFAULT_SHEET_SCOPES,
+    get ETypeExport () { return ETypeExport; },
+    GoogleSheetClient: GoogleSheetClient,
+    GoogleSheetConfig: GoogleSheetConfig,
+    calculateActualRow: calculateActualRow,
+    convertColumnNameToIndex: convertColumnNameToIndex,
+    convertIndexToColumnName: convertIndexToColumnName,
+    convertValueSheet: convertValueSheet,
+    getIndexCol: getIndexCol,
+    getListColsAndValsExport: getListColsAndValsExport,
+    getSheetIdFromUrl: getSheetIdFromUrl,
+    isValidSheetUrl: isValidSheetUrl
 });
 
-exports.GGDrive = index;
+exports.GGDrive = index$1;
+exports.GGSheet = index;
 //# sourceMappingURL=index.js.map