google-spreadsheet 5.0.1 → 5.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "google-spreadsheet",
-  "version": "5.0.1",
+  "version": "5.0.3",
   "description": "Google Sheets API -- simple interface to read/write data and manage sheets",
   "keywords": [
     "google spreadsheets",
@@ -39,26 +39,37 @@
     "src/index.ts",
     "src/lib"
   ],
-  "dependencies": {},
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "docs:preview": "docsify serve docs",
+    "lint": "eslint ./ --ext .ts",
+    "lint:fix": "bun run lint --fix",
+    "nodev": "node -v",
+    "readme:copy": "echo \"<!-- DO NOT EDIT THIS FILE, EDIT MAIN README.md AND RUN \\`bun readme:copy\\` instead -->\n\n_Welcome to the docs site for_\n\" | cat - README.md > docs/README.md",
+    "test": "vitest",
+    "test:ci": "vitest run"
+  },
+  "dependencies": {
+    "es-toolkit": "^1.44.0",
+    "ky": "^1.14.3"
+  },
   "devDependencies": {
-    "@changesets/cli": "^2.29.5",
-    "@types/node": "^24.2.0",
+    "@changesets/cli": "^2.29.8",
+    "@types/node": "^25.2.3",
     "@typescript-eslint/eslint-plugin": "^5.59.7",
     "@typescript-eslint/parser": "^5.59.7",
-    "auto-changelog": "^2.4.0",
     "docsify-cli": "^4.4.4",
-    "es-toolkit": "^1.39.8",
     "eslint": "^8.41.0",
     "eslint-config-airbnb-base": "^15.0.0",
     "eslint-config-airbnb-typescript": "^17.0.0",
     "eslint-plugin-import": "^2.27.5",
     "eslint-plugin-no-floating-promise": "^1.0.2",
-    "google-auth-library": "^10.2.1",
-    "ky": "^1.8.2",
-    "tsup": "^8.5.0",
-    "typescript": "^5.5.4",
-    "varlock": "^0.0.7",
-    "vitest": "^3.2.4"
+    "google-auth-library": "^10.5.0",
+    "tsdown": "^0.20.3",
+    "typescript": "^5.9.3",
+    "varlock": "^0.2.2",
+    "vitest": "^4.0.18"
   },
   "peerDependencies": {
     "google-auth-library": ">=8.8.0"
@@ -67,19 +78,5 @@
     "google-auth-library": {
       "optional": true
     }
-  },
-  "volta": {
-    "node": "20.17.0"
-  },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "docs:preview": "docsify serve docs",
-    "lint": "eslint ./ --ext .ts",
-    "lint:fix": "pnpm run lint --fix",
-    "nodev": "node -v",
-    "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",
-    "test": "vitest",
-    "test:ci": "vitest run"
   }
 }

package/src/lib/GoogleSpreadsheet.ts

@@ -3,7 +3,8 @@ import * as _ from './toolkit';
 import { GoogleSpreadsheetWorksheet } from './GoogleSpreadsheetWorksheet';
 import { getFieldMask } from './utils';
 import {
-  DataFilter, GridRange, NamedRangeId, SpreadsheetId, SpreadsheetProperties, WorksheetId, WorksheetProperties,
+  DataFilter, GridRange, NamedRangeId, ProtectedRange,
+  SpreadsheetId, SpreadsheetProperties, WorksheetId, WorksheetProperties,
 } from './types/sheets-types';
 import { PermissionRoles, PermissionsList, PublicPermissionRoles } from './types/drive-types';
 import { RecursivePartial } from './types/util-types';
@@ -125,6 +126,7 @@ export class GoogleSpreadsheet {
     // create a ky instance with sheet root URL and hooks to handle auth
     this.sheetsApi = ky.create({
       prefixUrl: `${SHEETS_API_BASE_URL}/${spreadsheetId}`,
+      timeout: 180_000,
       hooks: {
         beforeRequest: [(r) => this._setAuthRequestHook(r)],
         beforeError: [(e) => this._errorHook(e)],
@@ -143,7 +145,7 @@ export class GoogleSpreadsheet {
   // INTERNAL UTILITY FUNCTIONS ////////////////////////////////////////////////////////////////////
 
   /** @internal */
-  async _setAuthRequestHook(req: Request) {
+  async _setAuthRequestHook(req: Request): Promise<Request> {
     const authConfig = await getRequestAuthConfig(this.auth);
     if (authConfig.headers) {
       Object.entries(authConfig.headers).forEach(([key, val]) => {
@@ -239,13 +241,13 @@ export class GoogleSpreadsheet {
   _updateRawProperties(newProperties: SpreadsheetProperties) { this._rawProperties = newProperties; }
 
   /** @internal */
-  _updateOrCreateSheet(sheetInfo: { properties: WorksheetProperties, data: any }) {
-    const { properties, data } = sheetInfo;
+  _updateOrCreateSheet(sheetInfo: { properties: WorksheetProperties, data: any, protectedRanges?: ProtectedRange[] }) {
+    const { properties, data, protectedRanges } = sheetInfo;
     const { sheetId } = properties;
     if (!this._rawSheets[sheetId]) {
-      this._rawSheets[sheetId] = new GoogleSpreadsheetWorksheet(this, properties, data);
+      this._rawSheets[sheetId] = new GoogleSpreadsheetWorksheet(this, properties, data, protectedRanges);
     } else {
-      this._rawSheets[sheetId].updateRawData(properties, data);
+      this._rawSheets[sheetId].updateRawData(properties, data, protectedRanges);
     }
   }
 
@@ -367,9 +369,11 @@ export class GoogleSpreadsheet {
   ) {
     // TODO: add named range to local cache
     return this._makeSingleUpdateRequest('addNamedRange', {
-      name,
-      namedRangeId,
-      range,
+      namedRange: {
+        name,
+        namedRangeId,
+        range,
+      },
     });
   }
 
@@ -619,6 +623,14 @@ export class GoogleSpreadsheet {
     return shareReq.json();
   }
 
+  /**
+   * delete a permission by its ID
+   * @see https://developers.google.com/drive/api/v3/reference/permissions/delete
+   */
+  async deletePermission(permissionId: string) {
+    await this.driveApi.delete(`permissions/${permissionId}`);
+  }
+
   //
   // CREATE NEW DOC ////////////////////////////////////////////////////////////////////////////////
   static async createNewSpreadsheetDocument(auth: GoogleApiAuth, properties?: Partial<SpreadsheetProperties>) {

package/src/lib/GoogleSpreadsheetWorksheet.ts

@@ -13,6 +13,7 @@ import {
   RowIndex, ColumnIndex, DataFilterWithoutWorksheetId, DataFilter, GetValuesRequestOptions, WorksheetGridProperties,
   WorksheetDimensionProperties, CellDataRange, AddRowOptions, GridRangeWithOptionalWorksheetId,
   DataValidationRule,
+  ProtectedRange, Integer,
 } from './types/sheets-types';
 
 
@@ -29,6 +30,7 @@ export class GoogleSpreadsheetWorksheet {
   private _cells: GoogleSpreadsheetCell[][] = [];
   private _rowMetadata: any[] = [];
   private _columnMetadata: any[] = [];
+  private _protectedRanges: ProtectedRange[] | null = null;
 
   private _headerValues: string[] | undefined;
   get headerValues() {
@@ -42,7 +44,8 @@ export class GoogleSpreadsheetWorksheet {
     /** parent GoogleSpreadsheet instance */
     readonly _spreadsheet: GoogleSpreadsheet,
     rawProperties: WorksheetProperties,
-    rawCellData?: CellDataRange[]
+    rawCellData?: CellDataRange[],
+    protectedRanges?: ProtectedRange[]
   ) {
     this._headerRowIndex = 1;
 
@@ -53,15 +56,17 @@ export class GoogleSpreadsheetWorksheet {
 
     this._rowMetadata = []; // 1d sparse array
     this._columnMetadata = [];
+    if (protectedRanges) this._protectedRanges = protectedRanges;
 
     if (rawCellData) this._fillCellData(rawCellData);
   }
 
   // INTERNAL UTILITY FUNCTIONS ////////////////////////////////////////////////////////////////////
 
-  updateRawData(properties: WorksheetProperties, rawCellData: CellDataRange[]) {
+  updateRawData(properties: WorksheetProperties, rawCellData: CellDataRange[], protectedRanges?: ProtectedRange[]) {
     this._rawProperties = properties;
     this._fillCellData(rawCellData);
+    if (protectedRanges) this._protectedRanges = protectedRanges;
   }
 
   async _makeSingleUpdateRequest(requestType: string, requestParams: any) {
@@ -166,6 +171,7 @@ export class GoogleSpreadsheetWorksheet {
   get hidden() { return this._getProp('hidden'); }
   get tabColor() { return this._getProp('tabColor'); }
   get rightToLeft() { return this._getProp('rightToLeft'); }
+  get protectedRanges() { return this._protectedRanges; }
   private get _headerRange() {
     return `A${this._headerRowIndex}:${this.lastColumnLetter}${this._headerRowIndex}`;
   }
@@ -788,9 +794,20 @@ export class GoogleSpreadsheetWorksheet {
     });
   }
 
-  async insertRange() {
-    // Request type = `insertRange`
-    // https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#InsertRangeRequest
+  /**
+   * insert empty cells in a range, shifting existing cells in the specified direction
+   * @see https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#InsertRangeRequest
+   */
+  async insertRange(
+    /** the range to insert new cells into */
+    range: GridRangeWithOptionalWorksheetId,
+    /** which direction to shift existing cells - ROWS (shift down) or COLUMNS (shift right) */
+    shiftDimension: WorksheetDimension
+  ) {
+    return this._makeSingleUpdateRequest('insertRange', {
+      range: this._addSheetIdToRange(range),
+      shiftDimension,
+    });
   }
 
   async moveDimension() {
@@ -871,24 +888,57 @@ export class GoogleSpreadsheetWorksheet {
     // https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#SetBasicFilterRequest
   }
 
-  async addProtectedRange() {
-    // Request type = `addProtectedRange`
-    // https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#AddProtectedRangeRequest
+  /**
+   * add a new protected range to the sheet
+   * @see https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#AddProtectedRangeRequest
+   */
+  async addProtectedRange(protectedRange: ProtectedRange) {
+    if (!protectedRange.range && !protectedRange.namedRangeId) {
+      throw new Error('No range specified: either range or namedRangeId is required');
+    }
+    return this._makeSingleUpdateRequest('addProtectedRange', {
+      protectedRange,
+    });
   }
 
-  async updateProtectedRange() {
-    // Request type = `updateProtectedRange`
-    // https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#UpdateProtectedRangeRequest
+  /**
+   * update an existing protected range
+   * @see https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#UpdateProtectedRangeRequest
+   */
+  async updateProtectedRange(protectedRangeId: Integer, protectedRange: Partial<ProtectedRange>) {
+    return this._makeSingleUpdateRequest('updateProtectedRange', {
+      protectedRange: { protectedRangeId, ...protectedRange },
+      fields: getFieldMask(protectedRange as Record<string, unknown>),
+    });
   }
 
-  async deleteProtectedRange() {
-    // Request type = `deleteProtectedRange`
-    // https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#DeleteProtectedRangeRequest
+  /**
+   * delete a protected range by ID
+   * @see https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#DeleteProtectedRangeRequest
+   */
+  async deleteProtectedRange(protectedRangeId: Integer) {
+    return this._makeSingleUpdateRequest('deleteProtectedRange', {
+      protectedRangeId,
+    });
   }
 
-  async autoResizeDimensions() {
-    // Request type = `autoResizeDimensions`
-    // https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#AutoResizeDimensionsRequest
+  /**
+   * auto-resize rows or columns to fit their contents
+   * @see https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#AutoResizeDimensionsRequest
+   */
+  async autoResizeDimensions(
+    /** which dimension to auto-resize */
+    columnsOrRows: WorksheetDimension,
+    /** start and end indexes (optional, defaults to all) */
+    rangeIndexes?: DimensionRangeIndexes
+  ) {
+    return this._makeSingleUpdateRequest('autoResizeDimensions', {
+      dimensions: {
+        sheetId: this.sheetId,
+        dimension: columnsOrRows,
+        ...rangeIndexes,
+      },
+    });
   }
 
   async addChart() {

package/src/lib/types/sheets-types.ts

@@ -413,6 +413,41 @@ export type GridRangeWithOptionalWorksheetId = MakeOptional<GridRange, 'sheetId'
 export type DataFilter = A1Range | GridRange;
 export type DataFilterWithoutWorksheetId = A1Range | GridRangeWithoutWorksheetId;
 
+/**
+ * object describing the editors of a protected range
+ * @see https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/sheets#Editors
+ * */
+export type Editors = {
+  /** The email addresses of users with edit access to the protected range. */
+  users?: string[],
+  /** The email addresses of groups with edit access to the protected range. */
+  groups?: string[],
+  /** True if anyone in the document's domain has edit access to the protected range. */
+  domainUsersCanEdit?: boolean
+};
+
+/**
+ * object describing a protected range in a sheet
+ * @see https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/sheets#ProtectedRange
+ * */
+export type ProtectedRange = {
+  /** The ID of the protected range - read-only, auto-assigned */
+  protectedRangeId?: Integer,
+  /** The range that is being protected - mutually exclusive with namedRangeId */
+  range?: GridRange,
+  /** The named range this protected range is backed by - mutually exclusive with range */
+  namedRangeId?: NamedRangeId,
+  /** The description of this protected range */
+  description?: string,
+  /** True if this protected range will show a warning when editing. When true, editors is ignored. */
+  warningOnly?: boolean,
+  /** True if the user who requested this protected range can edit the protected area - read-only */
+  requestingUserCanEdit?: boolean,
+  /** The list of unprotected ranges within a protected sheet. Only supported on protected sheets. */
+  unprotectedRanges?: GridRange[],
+  /** The users and groups with edit access to the protected range. Not supported with warningOnly. */
+  editors?: Editors
+};
 
 /** @see https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/other#colorstyle */
 export type ColorStyle = { rgbColor: Color } | { themeColor: ThemeColorType };