google-sheets-automation 0.1.0 → 0.1.1

package/README.md

@@ -1,26 +1,38 @@
 
-# google-sheets-automation
+<div align="center">
+  <img src="https://www.gstatic.com/images/icons/material/system/2x/sheets_googlegreen_48dp.png" width="64" alt="Google Sheets Logo" />
+  <h1>google-sheets-automation</h1>
+  <p>Automate Google Sheets from Node.js: add, update, and read rows with a simple API.</p>
+</div>
 
-Simplify populating sheets from inputs. Designed to be extensible for multiple sheet providers, but currently only supports Google Sheets. Usable in Node.js projects (backend or CLI).
+---
 
- # google-sheets-automation
-- Add rows, update cells, batch updates
-Automate populating and managing Google Sheets from Node.js. Usable in backend, CLI, or serverless environments.
-- Accepts objects, arrays, or form data
-- Simple, promise-based API
-- Add rows, update cells, batch updates
-- Google Sheets API support
-- Accepts objects, arrays, or form data
-- Simple, promise-based API
+## Overview
 
-```js
-## Usage Example
+`google-sheets-automation` is a Node.js package for programmatically managing Google Sheets. Easily add, update, and read rows using service account credentials. Designed for backend, CLI, and serverless environments.
+
+## Features
+- Add rows with optional header mapping
+- Update cells in bulk (A1 notation)
+- Read sheet data as objects
+- Batch operations
+- Promise-based API
+- Secure authentication via Google service accounts
+
+## Installation
+
+```bash
 npm install google-sheets-automation
+```
+
+## Quick Start
+
+```js
 import { GoogleSheetProvider } from 'google-sheets-automation';
 
 const provider = new GoogleSheetProvider({
   serviceAccount: {
-import { GoogleSheetProvider } from 'google-sheets-automation';
+    client_email: 'your-service-account-email@project.iam.gserviceaccount.com',
     private_key: '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n',
   },
   sheetId: 'your-google-sheet-id',
@@ -37,9 +49,91 @@ const rows = [
   { name: 'Bob', email: 'bob@example.com', message: 'Hi!' },
 ];
 
-await provider.addRows(rows, headerMap);
+await provider.addRows({ spreadsheetId: 'your-google-sheet-id', sheetName: 'Sheet1', headerMap }, rows);
 ```
 
+## Environment Setup
+
+1. **Create a Google Cloud project** and enable the Google Sheets API.
+2. **Create a service account** and download the JSON key.
+3. **Share your target Google Sheet** with the service account email.
+4. Store credentials in your `.env`:
+   ```env
+   GOOGLE_SERVICE_ACCOUNT_EMAIL=your-service-account-email@project.iam.gserviceaccount.com
+   GOOGLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
+   GOOGLE_SHEET_ID=your-google-sheet-id
+   ```
+
+## API Reference
+
+### GoogleSheetProvider
+
+#### `addRows(options, rows)`
+Add rows to a sheet. If `headerMap` is provided and the sheet is empty, headers are added automatically.
+
+#### `updateCells(options)`
+Update cells in a sheet using A1 notation and a 2D array of values.
+
+#### `readData(options)`
+Read all data from a sheet, returned as an array of objects (first row is used as keys).
+
+#### `deleteRows(options)`
+Delete rows by index (not yet implemented).
+
+#### `createSheet(options)`
+Create a new sheet (not yet implemented).
+
+### Types
+
+- `AddRowsOptions`: `{ spreadsheetId, sheetName, headerMap? }`
+- `UpdateCellsOptions`: `{ spreadsheetId, sheetName, range?, values }`
+- `ReadDataOptions`: `{ spreadsheetId, sheetName, range? }`
+- `DeleteRowsOptions`: `{ spreadsheetId, sheetName, rowIndexes }`
+- `CreateSheetOptions`: `{ spreadsheetId, sheetName }`
+
+## Advanced Usage
+
+### Update Cells Example
+```js
+await provider.updateCells({
+  spreadsheetId: 'your-google-sheet-id',
+  sheetName: 'Sheet1',
+  range: 'Sheet1!A2:B2',
+  values: [['Alice', 'alice@example.com']]
+});
+```
+
+### Read Data Example
+```js
+const data = await provider.readData({
+  spreadsheetId: 'your-google-sheet-id',
+  sheetName: 'Sheet1'
+});
+console.log(data);
+```
+
+## Testing
+
+### Unit Tests
+Run all unit tests (mocks Google API calls):
+```bash
+npm run test
+```
+
+### Integration Tests
+Run integration tests against the real Google Sheets API (requires valid `.env` and sheet setup):
+```bash
+npm run test test/providers/googleProvider.integration.test.ts
+```
+
+## Contributing
+
+Pull requests and issues are welcome! Please open an issue for feature requests or bugs.
+
+## License
+
+MIT
+
 ## Testing
 Unit tests are written with Jest and mock all Google API calls, so no credentials are required:
 ```bash

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './providers/google';

package/dist/index.js

@@ -0,0 +1 @@
+export * from './providers/google';

package/dist/providers/google.d.ts

@@ -0,0 +1,2 @@
+export { GoogleSheetProvider, ISheetProvider } from './googleProvider';
+export { SheetClient, ISheetClient } from './sheetClient';

package/dist/providers/google.js

@@ -0,0 +1,2 @@
+export { GoogleSheetProvider } from './googleProvider';
+export { SheetClient } from './sheetClient';

package/dist/providers/googleProvider.d.ts

@@ -0,0 +1,26 @@
+import { SheetRow, AddRowsOptions, UpdateCellsOptions, ReadDataOptions, DeleteRowsOptions, CreateSheetOptions } from './types';
+export interface ISheetProvider {
+    addRows(options: AddRowsOptions, rows: SheetRow[]): Promise<void>;
+    updateCells(options: UpdateCellsOptions): Promise<void>;
+    readData(options: ReadDataOptions): Promise<SheetRow[]>;
+    deleteRows(options: DeleteRowsOptions): Promise<void>;
+    createSheet(options: CreateSheetOptions): Promise<void>;
+}
+export declare class GoogleSheetProvider implements ISheetProvider {
+    private getBaseUrl;
+    private buildUrl;
+    private readonly credentials;
+    private _accessToken;
+    private _tokenExpiry;
+    constructor(credentials: any);
+    /**
+     * Get a valid access token, either from credentials or by generating from service account.
+     */
+    private getAccessToken;
+    addRows(options: AddRowsOptions, rows: SheetRow[]): Promise<void>;
+    updateCells(options: UpdateCellsOptions): Promise<void>;
+    readData(options: ReadDataOptions): Promise<SheetRow[]>;
+    deleteRows(options: DeleteRowsOptions): Promise<void>;
+    createSheet(options: CreateSheetOptions): Promise<void>;
+    static mapHeaders(input: SheetRow, headerMap?: Record<string, string>): SheetRow;
+}

package/dist/providers/googleProvider.js

@@ -0,0 +1,168 @@
+// Only import google-auth-library in Node.js
+let GoogleAuth = undefined;
+if (typeof process !== 'undefined' && process.versions?.node) {
+    try {
+        GoogleAuth = require('google-auth-library').GoogleAuth;
+    }
+    catch { }
+}
+export class GoogleSheetProvider {
+    getBaseUrl() {
+        return 'https://sheets.googleapis.com/v4/spreadsheets';
+    }
+    buildUrl(path, params) {
+        let url = `${this.getBaseUrl()}/${path}`;
+        if (params) {
+            const query = Object.entries(params)
+                .filter(([_, v]) => v !== undefined)
+                .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+                .join('&');
+            if (query)
+                url += `?${query}`;
+        }
+        return url;
+    }
+    constructor(credentials) {
+        this._accessToken = null;
+        this._tokenExpiry = null;
+        this.credentials = credentials;
+    }
+    /**
+     * Get a valid access token, either from credentials or by generating from service account.
+     */
+    async getAccessToken() {
+        if (this.credentials.accessToken) {
+            return this.credentials.accessToken;
+        }
+        // If service account credentials are provided (Node.js only)
+        if (GoogleAuth && this.credentials.private_key && this.credentials.client_email) {
+            if (this._accessToken && this._tokenExpiry && Date.now() < this._tokenExpiry - 60000) {
+                return this._accessToken;
+            }
+            const auth = new GoogleAuth({
+                credentials: this.credentials,
+                scopes: ['https://www.googleapis.com/auth/spreadsheets'],
+            });
+            const client = await auth.getClient();
+            const { token, res } = await client.getAccessToken();
+            let expiry = Date.now() + 50 * 60 * 1000;
+            if (res?.data?.expiry_date) {
+                expiry = res.data.expiry_date;
+            }
+            this._accessToken = token;
+            this._tokenExpiry = expiry;
+            return token;
+        }
+        throw new Error('No valid access token or service account credentials provided.');
+    }
+    async addRows(options, rows) {
+        const { spreadsheetId, sheetName, headerMap } = options;
+        const accessToken = await this.getAccessToken();
+        let values = [];
+        // If headerMap is passed and sheet is empty, add header row first
+        if (headerMap) {
+            // Check if sheet is empty by reading first row
+            const readUrl = this.buildUrl(`${spreadsheetId}/values/${encodeURIComponent(sheetName)}`, { majorDimension: 'ROWS', range: sheetName });
+            const readRes = await fetch(readUrl, {
+                method: 'GET',
+                headers: {
+                    'Authorization': `Bearer ${accessToken}`,
+                },
+            });
+            let sheetIsEmpty = true;
+            if (readRes.ok) {
+                const data = await readRes.json();
+                if (data.values && data.values.length > 0) {
+                    sheetIsEmpty = false;
+                }
+            }
+            if (sheetIsEmpty) {
+                // Add header row
+                values.push(Object.values(headerMap));
+            }
+        }
+        // Map headers if needed
+        const mappedRows = headerMap
+            ? rows.map(row => GoogleSheetProvider.mapHeaders(row, headerMap))
+            : rows;
+        values = values.concat(mappedRows.map(row => Object.values(row)));
+        // Prepare API request
+        const url = this.buildUrl(`${spreadsheetId}/values/${encodeURIComponent(sheetName)}:append`, { valueInputOption: 'USER_ENTERED' });
+        const body = JSON.stringify({ values });
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${accessToken}`,
+                'Content-Type': 'application/json'
+            },
+            body
+        });
+        if (!res.ok) {
+            const err = await res.text();
+            throw new Error(`Google Sheets API error: ${res.status} ${err}`);
+        }
+    }
+    async updateCells(options) {
+        const { spreadsheetId, sheetName, range, values } = options;
+        const accessToken = await this.getAccessToken();
+        // values should be a 2D array matching the range
+        const url = this.buildUrl(`${spreadsheetId}/values/${encodeURIComponent(range || sheetName)}`, { valueInputOption: 'USER_ENTERED' });
+        const body = JSON.stringify({ values });
+        const res = await fetch(url, {
+            method: 'PUT',
+            headers: {
+                'Authorization': `Bearer ${accessToken}`,
+                'Content-Type': 'application/json'
+            },
+            body
+        });
+        if (!res.ok) {
+            const err = await res.text();
+            throw new Error(`Google Sheets API error: ${res.status} ${err}`);
+        }
+    }
+    async readData(options) {
+        const { spreadsheetId, sheetName, range } = options;
+        const accessToken = await this.getAccessToken();
+        const url = this.buildUrl(`${spreadsheetId}/values/${encodeURIComponent(range || sheetName)}`, { majorDimension: 'ROWS' });
+        const res = await fetch(url, {
+            method: 'GET',
+            headers: {
+                'Authorization': `Bearer ${accessToken}`,
+            },
+        });
+        if (!res.ok) {
+            const err = await res.text();
+            throw new Error(`Google Sheets API error: ${res.status} ${err}`);
+        }
+        const data = await res.json();
+        if (!data.values || data.values.length === 0)
+            return [];
+        // Assume first row is header
+        const headers = data.values[0];
+        const rows = [];
+        for (let i = 1; i < data.values.length; i++) {
+            const row = {};
+            for (let j = 0; j < headers.length; j++) {
+                row[headers[j]] = data.values[i][j];
+            }
+            rows.push(row);
+        }
+        return rows;
+    }
+    async deleteRows(options) {
+        // TODO: Implement row deletion logic
+    }
+    async createSheet(options) {
+        // TODO: Implement sheet creation logic
+    }
+    static mapHeaders(input, headerMap) {
+        if (!headerMap)
+            return input;
+        const mapped = {};
+        for (const key in input) {
+            mapped[headerMap[key] || key] = input[key];
+        }
+        return mapped;
+    }
+}

package/dist/providers/sheetClient.d.ts

@@ -0,0 +1,21 @@
+import { SheetRow, AddRowsOptions, UpdateCellsOptions, ReadDataOptions, DeleteRowsOptions, CreateSheetOptions } from './types';
+export interface ISheetClient {
+    addRows(options: AddRowsOptions, rows: SheetRow[]): Promise<void>;
+    updateCells(options: UpdateCellsOptions): Promise<void>;
+    readData(options: ReadDataOptions): Promise<SheetRow[]>;
+    deleteRows(options: DeleteRowsOptions): Promise<void>;
+    createSheet(options: CreateSheetOptions): Promise<void>;
+}
+export declare class SheetClient implements ISheetClient {
+    private readonly provider;
+    constructor(config: {
+        provider: string;
+        credentials: any;
+    });
+    addRows(options: AddRowsOptions, rows: SheetRow[]): Promise<void>;
+    updateCells(options: UpdateCellsOptions): Promise<void>;
+    readData(options: ReadDataOptions): Promise<SheetRow[]>;
+    deleteRows(options: DeleteRowsOptions): Promise<void>;
+    createSheet(options: CreateSheetOptions): Promise<void>;
+    static mapHeaders(input: SheetRow, headerMap?: Record<string, string>): SheetRow;
+}

package/dist/providers/sheetClient.js

@@ -0,0 +1,29 @@
+import { GoogleSheetProvider } from './googleProvider';
+export class SheetClient {
+    constructor(config) {
+        if (config.provider === 'google') {
+            this.provider = new GoogleSheetProvider(config.credentials);
+        }
+        else {
+            throw new Error('Provider not supported');
+        }
+    }
+    addRows(options, rows) {
+        return this.provider.addRows(options, rows);
+    }
+    updateCells(options) {
+        return this.provider.updateCells(options);
+    }
+    readData(options) {
+        return this.provider.readData(options);
+    }
+    deleteRows(options) {
+        return this.provider.deleteRows(options);
+    }
+    createSheet(options) {
+        return this.provider.createSheet(options);
+    }
+    static mapHeaders(input, headerMap) {
+        return GoogleSheetProvider.mapHeaders(input, headerMap);
+    }
+}

package/dist/providers/types.d.ts

@@ -0,0 +1,39 @@
+export interface SheetRow {
+    [key: string]: string | number | boolean | null;
+}
+export interface SheetRange {
+    startRow: number;
+    endRow: number;
+    startCol: number;
+    endCol: number;
+}
+export interface SheetOptions {
+    spreadsheetId: string;
+    sheetName: string;
+}
+export interface AddRowsOptions extends SheetOptions {
+    headerMap?: Record<string, string>;
+}
+export interface UpdateCellsOptions extends SheetOptions {
+    /**
+     * A1 notation range to update, e.g. "Sheet1!A2:B3". If omitted, uses sheetName.
+     */
+    range?: string;
+    /**
+     * 2D array of values to write to the range.
+     */
+    values: (string | number | boolean | null)[][];
+}
+export interface ReadDataOptions extends SheetOptions {
+    /**
+     * A1 notation range to read, e.g. "Sheet1!A2:B3". If omitted, uses sheetName.
+     */
+    range?: string;
+}
+export interface DeleteRowsOptions extends SheetOptions {
+    rowIndexes: number[];
+}
+export interface CreateSheetOptions {
+    spreadsheetId: string;
+    sheetName: string;
+}

package/dist/providers/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/inputParser.d.ts

@@ -0,0 +1 @@
+export declare function parseInput(input: any): any[];

package/dist/utils/inputParser.js

@@ -0,0 +1,9 @@
+// Utility to parse various input formats into rows for sheets
+export function parseInput(input) {
+    if (Array.isArray(input))
+        return input;
+    if (typeof input === 'object')
+        return [input];
+    // Add more parsing logic as needed
+    throw new Error('Unsupported input format');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "google-sheets-automation",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Automate Google Sheets from Node.js: add, update, and read rows with simple API. Supports service accounts, header mapping, and batch operations.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -16,18 +16,32 @@
   ],
   "scripts": {
     "build": "tsc",
-    "test": "node --experimental-vm-modules node_modules/.bin/jest"
+    "test": "node --experimental-vm-modules node_modules/.bin/jest",
+    "test:unit": "npx jest --testPathIgnorePatterns=integration",
+    "test:integration": "npx jest --testPathPattern=integration"
   },
   "keywords": [
     "google-sheets",
     "spreadsheet",
     "api",
     "automation",
-     "nodejs",
+    "nodejs",
     "provider"
   ],
-  "author": "CaesarSage",
+  "author": {
+    "name": "Caesar Sage",
+    "email": "caesarsage@gmail.com",
+    "url": "https://github.com/CaesarSage"
+  },
   "license": "MIT",
+  "homepage": "https://github.com/CaesarSage/google-sheets-automation#readme",
+  "bugs": {
+    "url": "https://github.com/CaesarSage/google-sheets-automation/issues"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/CaesarSage"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/CaesarSage/google-sheets-automation.git"
@@ -35,17 +49,12 @@
   "devDependencies": {
     "@types/jest": "^30.0.0",
     "@types/node": "^25.0.9",
-    "@types/react": "^19.2.9",
-    "@types/react-dom": "^19.2.3",
     "dotenv": "^17.2.3",
     "jest": "^30.2.0",
     "ts-jest": "^29.4.6",
     "typescript": "^5.0.0"
   },
   "dependencies": {
-    "google-auth-library": "^10.5.0",
-    "next": "^16.1.4",
-    "react": "^19.2.3",
-    "react-dom": "^19.2.3"
+    "google-auth-library": "^10.5.0"
   }
 }