google-spreadsheet 3.0.14 → 3.3.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

@@ -6,7 +6,7 @@
 [![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 - API key, service account, oauth
+- 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
@@ -16,7 +16,7 @@ Full docs available at [https://theoephraim.github.io/node-google-spreadsheet](h
 
 > **🚨 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 to use. Originally they were going to shut it down on March 3rd 2020, but have pushed that date back to January 2021.
+> 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**
@@ -28,7 +28,7 @@ Full docs available at [https://theoephraim.github.io/node-google-spreadsheet](h
 ## Examples
 _the following examples are meant to give you an idea of just some of the things you can do_
 
-!> NOTE - To keep the examples more 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:
+> **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() {
@@ -41,20 +41,16 @@ _the following examples are meant to give you an idea of just some of the things
 ```javascript
 const { GoogleSpreadsheet } = require('google-spreadsheet');
 
-// spreadsheet key is the long id in the sheets URL
+// Initialize the sheet - doc ID is the long id in the sheets URL
 const doc = new GoogleSpreadsheet('<the sheet ID from the url>');
 
-// use service account creds
+// 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,
 });
-// OR load directly from json file if not in secure environment
-await doc.useServiceAccountAuth(require('./creds-from-google.json'));
-// OR use service account to impersonate a user (see https://developers.google.com/identity/protocols/oauth2/service-account#delegatingauthority)
-await doc.useServiceAccountAuth(require('./creds-from-google.json'), 'some-user@my-domain.com');
-// OR use API key -- only for read-only access to public sheets
-doc.useApiKey('YOUR-API-KEY');
 
 await doc.loadInfo(); // loads document properties and worksheets
 console.log(doc.title);
@@ -104,7 +100,7 @@ More info:
 
 ### Working with cells
 ```javascript
-await sheet.loadCells('A1:E10'); // loads a range of cells
+await sheet.loadCells('A1:E10'); // loads range of cells into local cache - DOES NOT RETURN THE 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
@@ -150,7 +146,7 @@ None yet - get in touch!
 
 Contributions are welcome, but please follow the existing conventions, use the linter, add relevant tests, add relevant documentation.
 
-These docs are 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 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

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 {
@@ -28,6 +29,7 @@ class GoogleSpreadsheet {
     this.authMode = null;
     this._rawSheets = {};
     this._rawProperties = null;
+    this._spreadsheetUrl = null;
 
     // create an axios instance with sheet root URL and interceptors to handle auth
     this.axios = Axios.create({
@@ -88,6 +90,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)
@@ -133,6 +140,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');
     }
@@ -254,6 +264,7 @@ class GoogleSpreadsheet {
         ...includeCells && { includeGridData: true },
       },
     });
+    this._spreadsheetUrl = response.data.spreadsheetUrl;
     this._rawProperties = response.data.properties;
     _.each(response.data.sheets, (s) => this._updateOrCreateSheet(s));
   }
@@ -290,15 +301,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;
@@ -372,6 +384,43 @@ class GoogleSpreadsheet {
     const { sheets } = result.data;
     _.each(sheets, (sheet) => { this._updateOrCreateSheet(sheet); });
   }
+
+  // EXPORTING /////////////////////////////////////////////////////////////
+  async _downloadAs(fileType, worksheetId, returnStreamInsteadOfBuffer) {
+    // see https://stackoverflow.com/questions/11619805/using-the-google-drive-api-to-download-a-spreadsheet-in-csv-format/51235960#51235960
+
+    if (['html', 'xlsx', 'ods'].includes(fileType)) {
+      if (worksheetId) throw new Error(`Cannot specify worksheetId when exporting as ${fileType}`);
+    } else if (['csv', 'tsv', 'pdf'].includes(fileType)) {
+      if (worksheetId === undefined) throw new Error(`Must specify worksheetId when exporting as ${fileType}`);
+    } else {
+      throw new Error(`unsupported export fileType - ${fileType}`);
+    }
+
+    // google UI shows "html" but passes through "zip"
+    if (fileType === 'html') fileType = 'zip';
+
+    const exportUrl = this._spreadsheetUrl.replace('/edit', '/export');
+    const response = await this.axios.get(exportUrl, {
+      baseUrl: '', // unset baseUrl since we're not hitting the normal sheets API
+      params: {
+        id: this.spreadsheetId,
+        format: fileType,
+        ...worksheetId && { gid: worksheetId },
+      },
+      responseType: returnStreamInsteadOfBuffer ? 'stream' : 'arraybuffer',
+    });
+    return response.data;
+  }
+  async downloadAsHTML(returnStreamInsteadOfBuffer = false) {
+    return this._downloadAs('html', null, returnStreamInsteadOfBuffer);
+  }
+  async downloadAsXLSX(returnStreamInsteadOfBuffer = false) {
+    return this._downloadAs('xlsx', null, returnStreamInsteadOfBuffer);
+  }
+  async downloadAsODS(returnStreamInsteadOfBuffer = false) {
+    return this._downloadAs('ods', null, returnStreamInsteadOfBuffer);
+  }
 }
 
 module.exports = GoogleSpreadsheet;

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(
@@ -440,6 +444,13 @@ class GoogleSpreadsheetWorksheet {
     return rows;
   }
 
+  async clearRows(options = {}) {
+    // default to first row after header
+    const startRowIndex = options.start || this._headerRowIndex + 1;
+    const endRowIndex = options.end || this.rowCount;
+    await this._spreadsheet.axios.post(`/values/${this.encodedA1SheetName}!${startRowIndex}:${endRowIndex}:clear`);
+  }
+
   // BASIC PROPS ///////////////////////////////////////////////////////////////////////////////////
   async updateProperties(properties) {
     // Request type = `updateSheetProperties`
@@ -622,9 +633,17 @@ class GoogleSpreadsheetWorksheet {
     // https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#DuplicateFilterViewRequest
   }
 
-  async duplicateSheet() {
+  async duplicate(options = {}) {
     // Request type = `duplicateSheet`
     // https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#DuplicateSheetRequest
+    const response = await this._makeSingleUpdateRequest('duplicateSheet', {
+      sourceSheetId: this.sheetId,
+      ...options.index !== undefined && { insertSheetIndex: options.index },
+      ...options.id && { newSheetId: options.id },
+      ...options.title && { newSheetName: options.title },
+    });
+    const newSheetId = response.properties.sheetId;
+    return this._spreadsheet.sheetsById[newSheetId];
   }
 
   async findReplace() {
@@ -632,9 +651,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() {
@@ -820,12 +865,22 @@ class GoogleSpreadsheetWorksheet {
     });
   }
 
-  async clear() {
-    // clears all the data in the sheet
+  async clear(a1Range) {
+    // clears data in the sheet - defaults to entire sheet
+    const range = a1Range ? `!${a1Range}` : '';
     // sheet name without ie 'sheet1' rather than 'sheet1'!A1:B5 is all cells
-    await this._spreadsheet.axios.post(`/values/${this.encodedA1SheetName}:clear`);
+    await this._spreadsheet.axios.post(`/values/${this.encodedA1SheetName}${range}:clear`);
     this.resetLocalCache(true);
   }
+  async downloadAsCSV(returnStreamInsteadOfBuffer = false) {
+    return this._spreadsheet._downloadAs('csv', this.sheetId, returnStreamInsteadOfBuffer);
+  }
+  async downloadAsTSV(returnStreamInsteadOfBuffer = false) {
+    return this._spreadsheet._downloadAs('tsv', this.sheetId, returnStreamInsteadOfBuffer);
+  }
+  async downloadAsPDF(returnStreamInsteadOfBuffer = false) {
+    return this._spreadsheet._downloadAs('pdf', this.sheetId, returnStreamInsteadOfBuffer);
+  }
 }
 
 module.exports = GoogleSpreadsheetWorksheet;

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.14",
+  "version": "3.3.0",
   "license": "Unlicense",
   "keywords": [
     "google spreadsheets",
@@ -16,7 +16,7 @@
     "api",
     "googleapis"
   ],
-  "homepage": "https://github.com/theoephraim/node-google-spreadsheet",
+  "homepage": "https://theoephraim.github.io/node-google-spreadsheet",
   "repository": {
     "type": "git",
     "url": "git://github.com/theoephraim/node-google-spreadsheet.git"
@@ -26,13 +26,13 @@
     "node": ">=0.8.0"
   },
   "dependencies": {
-    "axios": "^0.19.2",
+    "axios": "^0.21.4",
     "google-auth-library": "^6.1.3",
-    "lodash": "^4.17.20"
+    "lodash": "^4.17.21"
   },
   "devDependencies": {
     "delay": "^4.3.0",
-    "docsify-cli": "^4.4.0",
+    "docsify-cli": "^4.4.3",
     "eslint": "^6.8.0",
     "eslint-config-airbnb-base": "^14.0.0",
     "eslint-plugin-async-await": "0.0.0",
@@ -47,7 +47,7 @@
     "lint": "eslint ./",
     "lint:fix": "eslint ./ --fix",
     "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\" | cat - README.md > docs/README.md"
+    "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": {