Create developer metadata on Sheets, Rows and Columns

docs/classes/google-spreadsheet-cell.md

@@ -111,3 +111,19 @@ Property|Type|Description
 
 ?> Usually makes more sense to use `sheet.saveUpdatedCells()` to save many cell updates at once
 
+
+
+### Developer Metadata
+
+### `getDeveloperMetadata()` (async) :id=fn-getDeveloperMetadata
+> Get developer metadata for the current cell's column
+
+#### `createDeveloperMetadata(metadataKey, metadataValue, visibility, metadataId)` (async) :id=fn-createSheetDeveloperMetadata
+> Add a new developer metadata object to the column of the cell
+
+Param|Type|Required|Description
+---|---|---|---
+`metadataKey`|String|✅|The metadata key
+`metadataValue`|String|✅|Data associated with the metadata's key
+`visibility`|String|-|Limits the visibility selected developer metadata<br>_One of (PROJECT or DOCUMENT) - defaults to unspecified_
+`metadataId`|Integer|-|Spreadsheet-scoped unique ID that identifies the metadata<br>_autogenerated by google if empty_

docs/classes/google-spreadsheet-row.md

@@ -94,3 +94,18 @@ Param|Type|Required|Description
 
 _also available as `row.del()`_
 
+
+### Developer Metadata
+
+### `getDeveloperMetadata()` (async) :id=fn-getDeveloperMetadata
+> Get developer metadata for the current row
+
+#### `createDeveloperMetadata(metadataKey, metadataValue, visibility, metadataId)` (async) :id=fn-createSheetDeveloperMetadata
+> Add a new developer metadata object to the row
+
+Param|Type|Required|Description
+---|---|---|---
+`metadataKey`|String|✅|The metadata key
+`metadataValue`|String|✅|Data associated with the metadata's key
+`visibility`|String|-|Limits the visibility selected developer metadata<br>_One of (PROJECT or DOCUMENT) - defaults to unspecified_
+`metadataId`|Integer|-|Spreadsheet-scoped unique ID that identifies the metadata<br>_autogenerated by google if empty_

docs/classes/google-spreadsheet-worksheet.md

@@ -272,6 +272,20 @@ Param|Type|Required|Description
 - ✨ **Side effects** - new row(s) or column(s) are inserted into the sheet
 - 🚨 **Warning** - Does not update cached rows/cells, so be sure to reload rows/cells before trying to make any updates to sheet contents
 
+
+### Developer Metadata
+
+#### `createDeveloperMetadata(metadataKey, metadataValue, visibility, metadataId)` (async) :id=fn-createSheetDeveloperMetadata
+> Add a new developer metadata object to the sheet
+
+Param|Type|Required|Description
+---|---|---|---
+`metadataKey`|String|✅|The metadata key
+`metadataValue`|String|✅|Data associated with the metadata's key
+`visibility`|String|-|Limits the visibility selected developer metadata<br>_One of (PROJECT or DOCUMENT) - defaults to unspecified_
+`metadataId`|Integer|-|Spreadsheet-scoped unique ID that identifies the metadata<br>_autogenerated by google if empty_
+
+
 ### Other
 
 #### `clear()` (async) :id=fn-clear

docs/classes/google-spreadsheet.md

@@ -210,3 +210,43 @@ Param|Type|Required|Description
 `rangeId`|String|✅|ID of the range to remove
 
 
+### Developer Metadata
+
+### `getMetadataById(metadataId)` (async) :id=fn-getMetadataById
+> Get the developer metadata by ID
+
+### `getDeveloperMetadataByA1Range(a1Range)` (async) :id=fn-getDeveloperMetadataByA1Range
+> Get a range of developer metadata by A1Range
+
+Param|Type|Required|Description
+---|---|---|---
+`a1Range`|String|✅|The A1 range to find developer metadata<br>_Must be a single column or a single row_
+
+### `getDeveloperMetadataByGridRange(gridRange)` (async) :id=fn-getDeveloperMetadataByA1Range
+> Get a range of developer metadata by Grid Range
+
+Param|Type|Required|Description
+---|---|---|---
+`gridRange`|Object|✅|The Grid Range to find developer metadata<br>_Must represent a single column or a single row_
+
+#### `createSheetDeveloperMetadata(metadataKey, metadataValue, sheetId, visibility, metadataId)` (async) :id=fn-createSheetDeveloperMetadata
+> Add a new developer metadata object to a specific sheet
+
+Param|Type|Required|Description
+---|---|---|---
+`metadataKey`|String|✅|The metadata key
+`metadataValue`|String|✅|Data associated with the metadata's key
+`sheetId`|String|-|The ID of the sheet to associate the metadata with
+`visibility`|String|-|Limits the visibility selected developer metadata<br>_One of (PROJECT or DOCUMENT) - defaults to unspecified_
+`metadataId`|Integer|-|Spreadsheet-scoped unique ID that identifies the metadata<br>_autogenerated by google if empty_
+
+#### `createRangeDeveloperMetadata(metadataKey, metadataValue, range, visibility, metadataId)` (async) :id=fn-createRangeDeveloperMetadata
+> Add a new developer metadata object to a specific range (COLUMNS or ROWS)
+
+Param|Type|Required|Description
+---|---|---|---
+`metadataKey`|String|✅|The metadata key
+`metadataValue`|String|✅|Data associated with the metadata's key
+`range`|String|✅||The dimensionRange object to associate the metadata with
+`visibility`|String|-|Limits the visibility selected developer metadata<br>_One of (PROJECT or DOCUMENT) - defaults to unspecified_
+`metadataId`|Integer|-|Spreadsheet-scoped unique ID that identifies the metadata<br>_autogenerated by google if empty_

lib/GoogleSpreadsheet.js

@@ -332,6 +332,70 @@ class GoogleSpreadsheet {
     });
   }
 
+  async getMetadataById(metadataId) {
+    // Request type = `developerMetadata`
+    // https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets.developerMetadata/get
+    return this.axios
+      .get(`/developerMetadata/${metadataId}`)
+      .then((response) => response.data);
+  }
+
+  async _createDeveloperMetadata(metadataKey, metadataValue, location, visibility, metadataId) {
+    // Request type = `createDeveloperMetadata`
+    // https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets.developerMetadata#DeveloperMetadata
+    return this._makeSingleUpdateRequest('createDeveloperMetadata', {
+      developerMetadata: {
+        metadataKey,
+        metadataValue,
+        location,
+        visibility: visibility || 'PROJECT',
+        metadataId,
+      },
+    }).then((data) => data.developerMetadata);
+  }
+
+  async createSheetDeveloperMetadata(metadataKey, metadataValue, sheetId, visibility, metadataId) {
+    return this._createDeveloperMetadata(
+      metadataKey,
+      metadataValue,
+      {
+        sheetId: sheetId || 0,
+      },
+      visibility,
+      metadataId
+    );
+  }
+
+  async createRangeDeveloperMetadata(metadataKey, metadataValue, range, visibility, metadataId) {
+    return this._createDeveloperMetadata(
+      metadataKey,
+      metadataValue,
+      {
+        dimensionRange: range,
+      },
+      visibility,
+      metadataId
+    );
+  }
+
+  async _getDeveloperMetadata(dataFilter) {
+    // Request type = `developerMetadata:search`
+    // https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets.developerMetadata/search
+    return this.axios
+      .post('/developerMetadata:search', {
+        dataFilters: [dataFilter],
+      })
+      .then((response) => response.data.matchedDeveloperMetadata);
+  }
+
+  async getDeveloperMetadataByA1Range(a1Range) {
+    return this._getDeveloperMetadata({ a1Range });
+  }
+
+  async getDeveloperMetadataByGridRange(gridRange) {
+    return this._getDeveloperMetadata({ gridRange });
+  }
+
   async deleteNamedRange(namedRangeId) {
     return this._makeSingleUpdateRequest('deleteNamedRange', { namedRangeId });
   }

lib/GoogleSpreadsheetCell.js

@@ -174,6 +174,31 @@ class GoogleSpreadsheetCell {
     await this._sheet.saveUpdatedCells([this]);
   }
 
+  async createDeveloperMetadata(metadataKey, metadataValue, visibility, metadataId) {
+    return this._sheet._spreadsheet.createRangeDeveloperMetadata(
+      metadataKey,
+      metadataValue,
+      {
+        dimension: 'COLUMNS',
+        sheetId: this._sheet.sheetId,
+        startIndex: this._column,
+        endIndex: this._column + 1,
+      },
+      visibility,
+      metadataId
+    );
+  }
+
+  async getDeveloperMetadata() {
+    return this._sheet._spreadsheet.getDeveloperMetadataByGridRange(
+      {
+        sheetId: this._sheet.sheetId,
+        startColumnIndex: this._column,
+        endColumnIndex: this._column + 1,
+      }
+    );
+  }
+
   // used by worksheet when saving cells
   // returns an individual batchUpdate request to update the cell
   _getUpdateRequest() {

lib/GoogleSpreadsheetRow.js

@@ -67,6 +67,31 @@ class GoogleSpreadsheetRow {
     return result;
   }
   async del() { return this.delete(); } // alias to mimic old version of this module
+
+  async createDeveloperMetadata(metadataKey, metadataValue, visibility, metadataId) {
+    return this._sheet._spreadsheet.createRangeDeveloperMetadata(
+      metadataKey,
+      metadataValue,
+      {
+        dimension: 'ROWS',
+        sheetId: this._sheet.sheetId,
+        startIndex: this._rowNumber,
+        endIndex: this._rowNumber + 1,
+      },
+      visibility,
+      metadataId
+    );
+  }
+
+  async getDeveloperMetadata() {
+    return this._sheet._spreadsheet.getDeveloperMetadataByGridRange(
+      {
+        sheetId: this._sheet.sheetId,
+        startRowIndex: this._rowNumber,
+        endRowIndex: this._rowNumber + 1,
+      }
+    );
+  }
 }
 
 module.exports = GoogleSpreadsheetRow;

lib/GoogleSpreadsheetWorksheet.js

@@ -782,9 +782,12 @@ class GoogleSpreadsheetWorksheet {
     // https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#DeleteBandingRequest
   }
 
-  async createDeveloperMetadata() {
+  async createDeveloperMetadata(metadataKey, metadataValue, visibility, metadataId) {
     // Request type = `createDeveloperMetadata`
     // https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#CreateDeveloperMetadataRequest
+    return this._spreadsheet.createSheetDeveloperMetadata(
+      metadataKey, metadataValue, this.sheetId, visibility, metadataId
+    );
   }
 
   async updateDeveloperMetadata() {