google-sheets-automation 0.1.0

package/README.md

@@ -0,0 +1,85 @@
+
+# google-sheets-automation
+
+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
+
+```js
+## Usage Example
+npm install google-sheets-automation
+import { GoogleSheetProvider } from 'google-sheets-automation';
+
+const provider = new GoogleSheetProvider({
+  serviceAccount: {
+import { GoogleSheetProvider } from 'google-sheets-automation';
+    private_key: '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n',
+  },
+  sheetId: 'your-google-sheet-id',
+});
+
+const headerMap = {
+  Name: 'name',
+  Email: 'email',
+  Message: 'message',
+};
+
+const rows = [
+  { name: 'Alice', email: 'alice@example.com', message: 'Hello!' },
+  { name: 'Bob', email: 'bob@example.com', message: 'Hi!' },
+];
+
+await provider.addRows(rows, headerMap);
+```
+
+## Testing
+Unit tests are written with Jest and mock all Google API calls, so no credentials are required:
+```bash
+npm run test
+```
+
+### Integration Testing
+To run integration tests against the real Google Sheets API, you must:
+- Set up a `.env` file with valid `GOOGLE_SERVICE_ACCOUNT_EMAIL`, `GOOGLE_PRIVATE_KEY`, and `GOOGLE_SHEET_ID`.
+- Ensure the target sheet (e.g. `IntegrationTestSheet`) exists in your Google Spreadsheet before running the test.
+- Run:
+```bash
+npm run test test/providers/googleProvider.integration.test.ts
+```
+Integration tests will use your credentials and make real API calls. Do not run these against production data.
+
+
+## Providers
+- `GoogleSheetProvider` (currently available)
+  - Usage: `new GoogleSheetProvider({ ...credentials })`
+-(Planned) ExcelSheetProvider, AirtableSheetProvider, etc.
+
+## API Functions (ISheetProvider)
+All providers implement the following methods:
+
+ `addRows(options, rows)` — Add rows to the sheet, optionally mapping headers.
+ `updateCells(options)` — Update cells in the sheet (A1 range, 2D values).
+ `readData(options)` — Read data from the sheet (returns array of objects).
+ `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 }`
+
+## Roadmap
+- Support for additional sheet providers (Excel, Airtable, etc.) planned for future releases.
+
+## License
+MIT

package/dist/src/index.d.ts

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

package/dist/src/index.js

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

package/dist/src/providers/google.d.ts

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

package/dist/src/providers/google.js

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

package/dist/src/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/src/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/src/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/src/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/src/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/src/providers/types.js

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

package/dist/src/utils/inputParser.d.ts

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

package/dist/src/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/dist/test/providers/googleProvider.integration.test.d.ts

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

package/dist/test/providers/googleProvider.integration.test.js

@@ -0,0 +1,45 @@
+import dotenv from 'dotenv';
+dotenv.config();
+import { GoogleSheetProvider } from '../../src/providers/googleProvider';
+describe('GoogleSheetProvider (integration)', () => {
+    const credentials = {
+        private_key: process.env.GOOGLE_PRIVATE_KEY?.replace(/\\n/g, '\n'),
+        client_email: process.env.GOOGLE_CLIENT_EMAIL,
+    };
+    const spreadsheetId = process.env.GOOGLE_SHEET_ID;
+    const sheetName = 'IntegrationTestSheet';
+    const addOptions = {
+        spreadsheetId,
+        sheetName,
+        headerMap: { name: 'Name', email: 'Email' }
+    };
+    const rows = [
+        { name: 'Integration Alice', email: 'alice@example.com' },
+        { name: 'Integration Bob', email: 'bob@example.com' }
+    ];
+    it('should add header and data rows to the sheet (real API)', async () => {
+        const provider = new GoogleSheetProvider(credentials);
+        await expect(provider.addRows(addOptions, rows)).resolves.not.toThrow();
+    });
+    it('should update cells in the sheet (real API)', async () => {
+        const provider = new GoogleSheetProvider(credentials);
+        const updateOptions = {
+            spreadsheetId,
+            sheetName,
+            range: `${sheetName}!A2:B2`,
+            values: [['Integration Alice', 'alice@example.com']]
+        };
+        await expect(provider.updateCells(updateOptions)).resolves.not.toThrow();
+    });
+    it('should read data from the sheet (real API)', async () => {
+        const provider = new GoogleSheetProvider(credentials);
+        const readOptions = {
+            spreadsheetId,
+            sheetName
+        };
+        const data = await provider.readData(readOptions);
+        expect(data.length).toBeGreaterThan(0);
+        expect(data[0]).toHaveProperty('Name');
+        expect(data[0]).toHaveProperty('Email');
+    });
+});

package/dist/test/providers/googleProvider.test.d.ts

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

package/dist/test/providers/googleProvider.test.js

@@ -0,0 +1,63 @@
+import { GoogleSheetProvider } from '../../src/providers/googleProvider';
+describe('GoogleSheetProvider', () => {
+    // Mock network and auth
+    beforeAll(() => {
+        jest.spyOn(GoogleSheetProvider.prototype, 'getAccessToken').mockResolvedValue('fake-token');
+        global.fetch = jest.fn().mockImplementation((url, opts) => {
+            // Simulate Google Sheets API responses
+            if (url.includes(':append')) {
+                return Promise.resolve({ ok: true, json: async () => ({}) });
+            }
+            if (opts?.method === 'PUT') {
+                return Promise.resolve({ ok: true, json: async () => ({}) });
+            }
+            if (opts?.method === 'GET') {
+                // Simulate reading data with header and two rows
+                return Promise.resolve({
+                    ok: true,
+                    json: async () => ({ values: [['Name', 'Email'], ['Alice', 'alice@example.com'], ['Bob', 'bob@example.com']] })
+                });
+            }
+            return Promise.resolve({ ok: true, json: async () => ({}) });
+        });
+    });
+    afterAll(() => {
+        jest.restoreAllMocks();
+    });
+    const credentials = { client_email: 'test@example.com', private_key: 'fake-key' };
+    const addOptions = {
+        spreadsheetId: 'fake-sheet-id',
+        sheetName: 'TestSheet',
+        headerMap: { name: 'Name', email: 'Email' }
+    };
+    const rows = [
+        { name: 'Alice', email: 'alice@example.com' },
+        { name: 'Bob', email: 'bob@example.com' }
+    ];
+    it('should add header and data rows to the sheet', async () => {
+        const provider = new GoogleSheetProvider(credentials);
+        await expect(provider.addRows(addOptions, rows)).resolves.not.toThrow();
+    });
+    it('should update cells in the sheet', async () => {
+        const provider = new GoogleSheetProvider(credentials);
+        const updateOptions = {
+            spreadsheetId: 'fake-sheet-id',
+            sheetName: 'TestSheet',
+            range: 'TestSheet!A2:B2',
+            values: [['Alice', 'alice@example.com']]
+        };
+        await expect(provider.updateCells(updateOptions)).resolves.not.toThrow();
+    });
+    it('should read data from the sheet', async () => {
+        const provider = new GoogleSheetProvider(credentials);
+        const readOptions = {
+            spreadsheetId: 'fake-sheet-id',
+            sheetName: 'TestSheet'
+        };
+        const data = await provider.readData(readOptions);
+        expect(data).toEqual([
+            { Name: 'Alice', Email: 'alice@example.com' },
+            { Name: 'Bob', Email: 'bob@example.com' }
+        ]);
+    });
+});

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "google-sheets-automation",
+  "version": "0.1.0",
+  "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",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "node --experimental-vm-modules node_modules/.bin/jest"
+  },
+  "keywords": [
+    "google-sheets",
+    "spreadsheet",
+    "api",
+    "automation",
+     "nodejs",
+    "provider"
+  ],
+  "author": "CaesarSage",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CaesarSage/google-sheets-automation.git"
+  },
+  "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"
+  }
+}