google-spreadsheet 3.0.12 → 3.2.0

package/.eslintrc.js

@@ -33,6 +33,7 @@ module.exports = {
       exports: 'always-multiline',
       functions: 'never', // this breaks
     }],
+    'no-multiple-empty-lines': 0, // sometimes helpful to break up sections of code
   },
   overrides: [
     { // extra jest related rules for tests

package/Changelog.md

@@ -0,0 +1,10 @@
+# Changelog
+
+TODO: set this up to be automated and pulled from git commits... for now just going to leave some notes manually!
+
+### 3.2.0 (2021-11-07)
+
+- Added `insertDimension` functionality
+- Added custom header row index for row-based API
+- Bumped dependency versions
+- Readme/docs cleanup

package/README.md

@@ -0,0 +1,153 @@
+# google-spreadsheet
+> The most popular [Google Sheets API](https://developers.google.com/sheets/api/reference/rest) wrapper for javascript
+
+[![NPM version](https://img.shields.io/npm/v/google-spreadsheet)](https://www.npmjs.com/package/google-spreadsheet)
+[![CircleCI](https://circleci.com/gh/theoephraim/node-google-spreadsheet.svg?style=shield)](https://circleci.com/gh/theoephraim/node-google-spreadsheet)
+[![Known Vulnerabilities](https://snyk.io/test/github/theoephraim/node-google-spreadsheet/badge.svg?targetFile=package.json)](https://snyk.io/test/github/theoephraim/node-google-spreadsheet?targetFile=package.json)
+[![NPM](https://img.shields.io/npm/dw/google-spreadsheet)](https://www.npmtrends.com/google-spreadsheet)
+
+- multiple auth options - service account (w/ optional impersonation), OAuth 2.0, API key (read-only)
+- cell-based API - read, write, bulk-updates, formatting
+- row-based API - read, update, delete (based on the old v3 row-based calls)
+- managing worksheets - add, remove, resize, change title, formatting
+
+**Docs site -**
+Full docs available at [https://theoephraim.github.io/node-google-spreadsheet](https://theoephraim.github.io/node-google-spreadsheet)
+
+> **🚨 Google Deprecation Warning - affects older version (v2) of this module 🚨**
+>
+> Google is [phasing out their old v3 api](https://cloud.google.com/blog/products/g-suite/migrate-your-apps-use-latest-sheets-api), which the older version of this module used. Originally they were going to shut it down on March 3rd 2020, but have pushed that date back to June 2021.
+
+
+**Regardless, please upgrade to the latest version of this module (v3) which uses the newer sheets v4 API**
+
+-------------
+
+> 🌈 **Installation** - `npm i google-spreadsheet --save` or `yarn add google-spreadsheet`
+
+## Examples
+_the following examples are meant to give you an idea of just some of the things you can do_
+
+> **IMPORTANT NOTE** - To keep the examples concise, I'm calling await [at the top level](https://v8.dev/features/top-level-await) which is not allowed by default in most versions of node. If you need to call await in a script at the root level, you must instead wrap it in an async function like so:
+
+```javascript
+(async function() {
+  await someAsyncFunction();
+}());
+```
+
+
+### The Basics
+```javascript
+const { GoogleSpreadsheet } = require('google-spreadsheet');
+
+// Initialize the sheet - doc ID is the long id in the sheets URL
+const doc = new GoogleSpreadsheet('<the sheet ID from the url>');
+
+// Initialize Auth - see https://theoephraim.github.io/node-google-spreadsheet/#/getting-started/authentication
+await doc.useServiceAccountAuth({
+  // env var values are copied from service account credentials generated by google
+  // see "Authentication" section in docs for more info
+  client_email: process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL,
+  private_key: process.env.GOOGLE_PRIVATE_KEY,
+});
+
+await doc.loadInfo(); // loads document properties and worksheets
+console.log(doc.title);
+await doc.updateProperties({ title: 'renamed doc' });
+
+const sheet = doc.sheetsByIndex[0]; // or use doc.sheetsById[id] or doc.sheetsByTitle[title]
+console.log(sheet.title);
+console.log(sheet.rowCount);
+
+// adding / removing sheets
+const newSheet = await doc.addSheet({ title: 'hot new sheet!' });
+await newSheet.delete();
+```
+More info:
+- [GoogleSpreadsheet](https://theoephraim.github.io/node-google-spreadsheet/#/classes/google-spreadsheet)
+- [GoogleSpreadsheetWorksheet](https://theoephraim.github.io/node-google-spreadsheet/#/classes/google-spreadsheet-worksheet)
+- [Authentication](https://theoephraim.github.io/node-google-spreadsheet/#/getting-started/authentication)
+
+
+
+### Working with rows
+```javascript
+// create a sheet and set the header row
+const sheet = await doc.addSheet({ headerValues: ['name', 'email'] });
+
+// append rows
+const larryRow = await sheet.addRow({ name: 'Larry Page', email: 'larry@google.com' });
+const moreRows = await sheet.addRows([
+  { name: 'Sergey Brin', email: 'sergey@google.com' },
+  { name: 'Eric Schmidt', email: 'eric@google.com' },
+]);
+
+// read rows
+const rows = await sheet.getRows(); // can pass in { limit, offset }
+
+// read/write row values
+console.log(rows[0].name); // 'Larry Page'
+rows[1].email = 'sergey@abc.xyz'; // update a value
+await rows[1].save(); // save updates
+await rows[1].delete(); // delete a row
+```
+More info:
+- [GoogleSpreadsheetWorksheet > Working With Rows](https://theoephraim.github.io/node-google-spreadsheet/#/classes/google-spreadsheet-worksheet#working-with-rows)
+- [GoogleSpreadsheetRow](https://theoephraim.github.io/node-google-spreadsheet/#/classes/google-spreadsheet-row)
+
+
+
+### Working with cells
+```javascript
+await sheet.loadCells('A1:E10'); // loads a range of cells
+console.log(sheet.cellStats); // total cells, loaded, how many non-empty
+const a1 = sheet.getCell(0, 0); // access cells using a zero-based index
+const c6 = sheet.getCellByA1('C6'); // or A1 style notation
+// access everything about the cell
+console.log(a1.value);
+console.log(a1.formula);
+console.log(a1.formattedValue);
+// update the cell contents and formatting
+a1.value = 123.456;
+c6.formula = '=A1';
+a1.textFormat = { bold: true };
+c6.note = 'This is a note!';
+await sheet.saveUpdatedCells(); // save all updates in one call
+```
+More info:
+- [GoogleSpreadsheetWorksheet > Working With Cells](https://theoephraim.github.io/node-google-spreadsheet/#/classes/google-spreadsheet-worksheet#working-with-cells)
+- [GoogleSpreadsheetCell](https://theoephraim.github.io/node-google-spreadsheet/#/classes/google-spreadsheet-cell)
+
+
+
+## Why?
+> **This module provides an intuitive wrapper around Google's API to simplify common interactions**
+
+While Google's v4 sheets api is much easier to use than v3 was, the official [googleapis npm module](https://www.npmjs.com/package/googleapis) is a giant meta-tool that handles _every Google product_. The module and the API itself are awkward and the docs are pretty terrible, at least to get started.
+
+**In what situation should you use Google's API directly?**<br>
+This module makes trade-offs for simplicity of the interface.
+Google's API provides a mechanism to make many requests in parallel, so if speed and efficiency is extremely important to your use case, you may want to use their API directly. There are also several features of their API that are not implemented here yet.
+
+
+## Support & Contributions
+
+This module was written and is actively maintained by [Theo Ephraim](https://theoephraim.com).
+
+**Are you actively using this module for a commercial project? Want to help support it?**<br>
+[Buy Theo a beer](https://paypal.me/theoephraim)
+
+#### Sponsors
+
+None yet - get in touch!
+
+#### Contributing
+
+Contributions are welcome, but please follow the existing conventions, use the linter, add relevant tests, add relevant documentation.
+
+The docs site is generated using [docsify](https://docsify.js.org). To preview and run locally so you can make edits, run `npm run docs:preview` and head to http://localhost:3000
+The content lives in markdown files in the docs folder.
+
+## License
+This is free and unencumbered public domain software. For more info, see https://unlicense.org.

package/TODO

@@ -0,0 +1,73 @@
+- support more cell functionality
+  - data validation rules - https://github.com/theoephraim/node-google-spreadsheet/issues/487
+
+- dont explode if sheet contains charts - https://github.com/theoephraim/node-google-spreadsheet/issues/444
+- add row.toJSON()
+  https://github.com/theoephraim/node-google-spreadsheet/issues/247
+- google auth - Application Default Creds
+  https://github.com/theoephraim/node-google-spreadsheet/issues/215
+  https://github.com/theoephraim/node-google-spreadsheet/issues/345
+
+- escape issues for strings starting with = `'=not a formula`
+  https://github.com/theoephraim/node-google-spreadsheet/issues/323
+
+
+
+- browser/react native, older ES support
+  https://github.com/theoephraim/node-google-spreadsheet/issues/339
+  https://github.com/theoephraim/node-google-spreadsheet/issues/382
+  https://github.com/theoephraim/node-google-spreadsheet/issues/406
+  https://github.com/theoephraim/node-google-spreadsheet/issues/404
+
+
+- nice tips here - https://github.com/mikro-orm/mikro-orm/issues/12
+- start using semantic release? or similar https://semantic-release.gitbook.io/semantic-release/
+- better commit messages to autogenerate changelog
+  - commitizen - https://github.com/commitizen/cz-cli
+    - https://gist.github.com/brianclements/841ea7bffdb01346392c
+  - commitlint checks - https://github.com/conventional-changelog/commitlint
+  - https://github.com/conventional-changelog/conventional-changelog
+
+
+
+
+
+BUGS
+- fetching single row via GRO has issues
+  https://github.com/theoephraim/node-google-spreadsheet/issues/347
+
+
+MISSING FUNCTIONS
+
+- support batchGet
+  https://github.com/theoephraim/node-google-spreadsheet/issues/326
+
+- update filters
+  https://github.com/theoephraim/node-google-spreadsheet/issues/328
+- insertDimension
+  https://github.com/theoephraim/node-google-spreadsheet/issues/366
+- conditional formatting
+  https://github.com/theoephraim/node-google-spreadsheet/issues/410
+
+
+OTHER
+- row to cell interface
+  https://github.com/theoephraim/node-google-spreadsheet/issues/343
+- reading from draftValue
+  https://github.com/theoephraim/node-google-spreadsheet/issues/350
+  https://github.com/theoephraim/node-google-spreadsheet/issues/402
+- heroku config docs
+  https://github.com/theoephraim/node-google-spreadsheet/issues/354
+- document metadata from drive api
+  https://github.com/theoephraim/node-google-spreadsheet/issues/364
+- date formatting, escaping issues
+  https://github.com/theoephraim/node-google-spreadsheet/issues/367
+  https://github.com/theoephraim/node-google-spreadsheet/issues/363
+- release notes
+  https://github.com/theoephraim/node-google-spreadsheet/issues/384
+- delete rows from google forms
+  https://github.com/theoephraim/node-google-spreadsheet/issues/393
+- better handling of merged cells
+  https://github.com/theoephraim/node-google-spreadsheet/issues/400
+- specify header row
+  https://github.com/theoephraim/node-google-spreadsheet/issues/407

package/lib/GoogleSpreadsheet.js

@@ -20,6 +20,7 @@ const AUTH_MODES = {
   JWT: 'JWT',
   API_KEY: 'API_KEY',
   RAW_ACCESS_TOKEN: 'RAW_ACCESS_TOKEN',
+  OAUTH: 'OAUTH',
 };
 
 class GoogleSpreadsheet {
@@ -31,7 +32,7 @@ class GoogleSpreadsheet {
 
     // create an axios instance with sheet root URL and interceptors to handle auth
     this.axios = Axios.create({
-      baseURL: `https://sheets.googleapis.com/v4/spreadsheets/${sheetId}`,
+      baseURL: `https://sheets.googleapis.com/v4/spreadsheets/${sheetId || ''}`,
       // send arrays in params with duplicate keys - ie `?thing=1&thing=2` vs `?thing[]=1...`
       // solution taken from https://github.com/axios/axios/issues/604
       paramsSerializer(params) {
@@ -59,6 +60,23 @@ class GoogleSpreadsheet {
     return this;
   }
 
+  // CREATE NEW DOC ////////////////////////////////////////////////////////////////////////////////
+  async createNewSpreadsheetDocument(properties) {
+    // see updateProperties for more info about available properties
+
+    if (this.spreadsheetId) {
+      throw new Error('Only call `createNewSpreadsheetDocument()` on a GoogleSpreadsheet object that has no spreadsheetId set');
+    }
+    const response = await this.axios.post(this.url, {
+      properties,
+    });
+    this.spreadsheetId = response.data.spreadsheetId;
+    this.axios.defaults.baseURL += this.spreadsheetId;
+
+    this._rawProperties = response.data.properties;
+    _.each(response.data.sheets, (s) => this._updateOrCreateSheet(s));
+  }
+
   // AUTH RELATED FUNCTIONS ////////////////////////////////////////////////////////////////////////
   async useApiKey(key) {
     this.authMode = AUTH_MODES.API_KEY;
@@ -71,6 +89,11 @@ class GoogleSpreadsheet {
     this.accessToken = token;
   }
 
+  async useOAuth2Client(oAuth2Client) {
+    this.authMode = AUTH_MODES.OAUTH;
+    this.oAuth2Client = oAuth2Client;
+  }
+
   // creds should be an object obtained by loading the json file google gives you
   // impersonateAs is an email of any user in the G Suite domain
   // (only works if service account has domain-wide delegation enabled)
@@ -116,6 +139,9 @@ class GoogleSpreadsheet {
       if (!this.apiKey) throw new Error('Please set API key');
       config.params = config.params || {};
       config.params.key = this.apiKey;
+    } else if (this.authMode === AUTH_MODES.OAUTH) {
+      const credentials = await this.oAuth2Client.getAccessToken();
+      config.headers.Authorization = `Bearer ${credentials.token}`;
     } else {
       throw new Error('You must initialize some kind of auth before making any requests');
     }
@@ -172,7 +198,7 @@ class GoogleSpreadsheet {
   }
 
   _ensureInfoLoaded() {
-    if (!this._rawProperties) throw new Error('You must call `sheet.loadInfo()` before accessing this property');
+    if (!this._rawProperties) throw new Error('You must call `doc.loadInfo()` before accessing this property');
   }
 
   _updateRawProperties(newProperties) { this._rawProperties = newProperties; }
@@ -273,15 +299,16 @@ class GoogleSpreadsheet {
     // https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#AddSheetRequest
 
     const response = await this._makeSingleUpdateRequest('addSheet', {
-      properties: _.omit(properties, 'headers', 'headerValues'),
+      properties: _.omit(properties, 'headers', 'headerValues', 'headerRowIndex'),
     });
     // _makeSingleUpdateRequest already adds the sheet
     const newSheetId = response.properties.sheetId;
     const newSheet = this.sheetsById[newSheetId];
 
     // allow it to work with `.headers` but `.headerValues` is the real prop
-    if (properties.headerValues || properties.headers) {
-      await newSheet.setHeaderRow(properties.headerValues || properties.headers);
+    const headers = properties.headerValues || properties.headers;
+    if (headers) {
+      await newSheet.setHeaderRow(headers, properties.headerRowIndex);
     }
 
     return newSheet;

package/lib/GoogleSpreadsheetCell.js

@@ -202,7 +202,6 @@ class GoogleSpreadsheetCell {
       delete (format.backgroundColorStyle);
     }
 
-
     return {
       updateCells: {
         rows: [{

package/lib/GoogleSpreadsheetWorksheet.js

@@ -20,6 +20,8 @@ class GoogleSpreadsheetWorksheet {
   constructor(parentSpreadsheet, { properties, data }) {
     this._spreadsheet = parentSpreadsheet; // the parent GoogleSpreadsheet instance
 
+    this._headerRowIndex = 1; // assume "header row" (for row-based calls) is in first row
+
     // basic properties
     this._rawProperties = properties;
 
@@ -51,6 +53,7 @@ class GoogleSpreadsheetWorksheet {
   resetLocalCache(dataOnly) {
     if (!dataOnly) this._rawProperties = null;
     this.headerValues = null;
+    this._headerRowIndex = 1;
     this._cells = [];
   }
 
@@ -174,7 +177,6 @@ class GoogleSpreadsheetWorksheet {
     return this._cells[rowIndex][columnIndex];
   }
 
-
   async loadCells(sheetFilters) {
     // load the whole sheet
     if (!sheetFilters) return this._spreadsheet.loadCells(this.a1SheetName);
@@ -283,11 +285,11 @@ class GoogleSpreadsheetWorksheet {
   //   });
   // }
 
-
   // ROW BASED FUNCTIONS ///////////////////////////////////////////////////////////////////////////
 
-  async loadHeaderRow() {
-    const rows = await this.getCellsInRange(`A1:${this.lastColumnLetter}1`);
+  async loadHeaderRow(headerRowIndex) {
+    if (headerRowIndex !== undefined) this._headerRowIndex = headerRowIndex;
+    const rows = await this.getCellsInRange(`A${this._headerRowIndex}:${this.lastColumnLetter}${this._headerRowIndex}`);
     if (!rows) {
       throw new Error('No values in the header row - fill the first row with header values before trying to interact with rows');
     }
@@ -298,7 +300,7 @@ class GoogleSpreadsheetWorksheet {
     checkForDuplicateHeaders(this.headerValues);
   }
 
-  async setHeaderRow(headerValues) {
+  async setHeaderRow(headerValues, headerRowIndex) {
     if (!headerValues) return;
     if (headerValues.length > this.columnCount) {
       throw new Error(`Sheet is not large enough to fit ${headerValues.length} columns. Resize the sheet first.`);
@@ -310,15 +312,17 @@ class GoogleSpreadsheetWorksheet {
       throw new Error('All your header cells are blank -');
     }
 
+    if (headerRowIndex) this._headerRowIndex = headerRowIndex;
+
     const response = await this._spreadsheet.axios.request({
       method: 'put',
-      url: `/values/${this.encodedA1SheetName}!1:1`,
+      url: `/values/${this.encodedA1SheetName}!${this._headerRowIndex}:${this._headerRowIndex}`,
       params: {
         valueInputOption: 'USER_ENTERED', // other option is RAW
         includeValuesInResponse: true,
       },
       data: {
-        range: `${this.a1SheetName}!1:1`,
+        range: `${this.a1SheetName}!${this._headerRowIndex}:${this._headerRowIndex}`,
         majorDimension: 'ROWS',
         values: [[
           ...trimmedHeaderValues,
@@ -369,7 +373,7 @@ class GoogleSpreadsheetWorksheet {
 
     const response = await this._spreadsheet.axios.request({
       method: 'post',
-      url: `/values/${this.encodedA1SheetName}!A1:append`,
+      url: `/values/${this.encodedA1SheetName}!A${this._headerRowIndex}:append`,
       params: {
         valueInputOption: options.raw ? 'RAW' : 'USER_ENTERED',
         insertDataOption: options.insert ? 'INSERT_ROWS' : 'OVERWRITE',
@@ -423,7 +427,7 @@ class GoogleSpreadsheetWorksheet {
 
     if (!this.headerValues) await this.loadHeaderRow();
 
-    const firstRow = 2 + options.offset; // skip first row AND not zero indexed
+    const firstRow = 1 + this._headerRowIndex + options.offset;
     const lastRow = firstRow + options.limit - 1; // inclusive so we subtract 1
     const lastColumn = columnToLetter(this.headerValues.length);
     const rawRows = await this.getCellsInRange(
@@ -553,14 +557,33 @@ class GoogleSpreadsheetWorksheet {
     // https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#CopyPasteRequest
   }
 
-  async mergeCells() {
+  async mergeCells(range, mergeType = 'MERGE_ALL') {
     // Request type = `mergeCells`
     // https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#MergeCellsRequest
+    if (range.sheetId && range.sheetId !== this.sheetId) {
+      throw new Error('Leave sheet ID blank or set to matching ID of this sheet');
+    }
+    await this._makeSingleUpdateRequest('mergeCells', {
+      mergeType,
+      range: {
+        ...range,
+        sheetId: this.sheetId,
+      },
+    });
   }
 
-  async unmergeCells() {
+  async unmergeCells(range) {
     // Request type = `unmergeCells`
     // https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#UnmergeCellsRequest
+    if (range.sheetId && range.sheetId !== this.sheetId) {
+      throw new Error('Leave sheet ID blank or set to matching ID of this sheet');
+    }
+    await this._makeSingleUpdateRequest('unmergeCells', {
+      range: {
+        ...range,
+        sheetId: this.sheetId,
+      },
+    });
   }
 
   async updateBorders() {
@@ -613,9 +636,35 @@ class GoogleSpreadsheetWorksheet {
     // https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#FindReplaceRequest
   }
 
-  async insertDimension() {
+  async insertDimension(columnsOrRows, range, inheritFromBefore = null) {
     // Request type = `insertDimension`
     // https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#InsertDimensionRequest
+
+    if (!columnsOrRows) throw new Error('You need to specify a dimension. i.e. COLUMNS|ROWS');
+    if (!_.isObject(range)) throw new Error('`range` must be an object containing `startIndex` and `endIndex`');
+    if (!_.isInteger(range.startIndex) || range.startIndex < 0) throw new Error('range.startIndex must be an integer >=0');
+    if (!_.isInteger(range.endIndex) || range.endIndex < 0) throw new Error('range.endIndex must be an integer >=0');
+    if (range.endIndex <= range.startIndex) throw new Error('range.endIndex must be greater than range.startIndex');
+
+    // default inheritFromBefore to true - unless inserting in the first row/column
+    if (inheritFromBefore === null) {
+      inheritFromBefore = range.startIndex > 0;
+    }
+
+    // do not allow inheritFromBefore if inserting at first row/column
+    if (inheritFromBefore && range.startIndex === 0) {
+      throw new Error('Cannot set inheritFromBefore to true if inserting in first row/column');
+    }
+
+    return this._makeSingleUpdateRequest('insertDimension', {
+      range: {
+        sheetId: this.sheetId,
+        dimension: columnsOrRows,
+        startIndex: range.startIndex,
+        endIndex: range.endIndex,
+      },
+      inheritFromBefore,
+    });
   }
 
   async insertRange() {

package/package.json

@@ -2,7 +2,7 @@
   "author": "Theo Ephraim <theozero@gmail.com> (https://theoephraim.com)",
   "name": "google-spreadsheet",
   "description": "Google Sheets API (v4) -- simple interface to read/write data and manage sheets",
-  "version": "3.0.12",
+  "version": "3.2.0",
   "license": "Unlicense",
   "keywords": [
     "google spreadsheets",
@@ -26,9 +26,9 @@
     "node": ">=0.8.0"
   },
   "dependencies": {
-    "axios": "^0.19.2",
-    "google-auth-library": "^6.0.6",
-    "lodash": "^4.17.20"
+    "axios": "^0.21.4",
+    "google-auth-library": "^6.1.3",
+    "lodash": "^4.17.21"
   },
   "devDependencies": {
     "delay": "^4.3.0",
@@ -46,7 +46,8 @@
     "test": "jest --runInBand",
     "lint": "eslint ./",
     "lint:fix": "eslint ./ --fix",
-    "docs:preview": "docsify serve docs"
+    "docs:preview": "docsify serve docs",
+    "readme:copy": "echo \"<!-- DO NOT EDIT THIS FILE, EDIT MAIN README.md AND RUN \\`npm readme:copy\\` instead -->\n\n_Welcome to the docs site for_\n\" | cat - README.md > docs/README.md"
   },
   "husky": {
     "hooks": {