@google/clasp 3.0.6-alpha → 3.1.1

package/build/src/core/project.js

@@ -1,3 +1,19 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// This file defines the `Project` class, which is responsible for managing
+// Google Apps Script project metadata, lifecycle operations (creation, versions,
+// deployments), and local project configuration settings.
 import Debug from 'debug';
 import fs from 'fs/promises';
 import { google } from 'googleapis';
@@ -5,6 +21,12 @@ import { fetchWithPages } from './utils.js';
 import { assertAuthenticated, assertScriptConfigured, handleApiError } from './utils.js';
 import path from 'path';
 const debug = Debug('clasp:core');
+/**
+ * Manages Google Apps Script project settings and interactions with the
+ * Apps Script API for operations like creating projects, versions,
+ * and deployments. It also handles reading and writing the local
+ * `.clasp.json` configuration file and the `appsscript.json` manifest.
+ */
 export class Project {
     constructor(options) {
         this.options = options;
@@ -22,10 +44,23 @@ export class Project {
         return (_a = this.options.project) === null || _a === void 0 ? void 0 : _a.parentId;
     }
     // TODO - Do we need the assertion or can just use accessor?
+    /**
+     * Retrieves the Google Cloud Platform (GCP) project ID associated with the script.
+     * Asserts that the script is configured before returning the ID.
+     * @returns {string | undefined} The GCP project ID, or undefined if not set.
+     * @throws {Error} If the script is not configured.
+     */
     getProjectId() {
         assertScriptConfigured(this.options);
         return this.options.project.projectId;
     }
+    /**
+     * Creates a new standalone Apps Script project.
+     * @param {string} name - The title for the new script project.
+     * @param {string} [parentId] - Optional ID of a Google Drive folder to create the script in.
+     * @returns {Promise<string>} A promise that resolves to the script ID of the newly created project.
+     * @throws {Error} If there's an API error or authentication issues.
+     */
     async createScript(name, parentId) {
         var _a;
         debug('Creating script %s', name);
@@ -56,6 +91,40 @@ export class Project {
             handleApiError(error);
         }
     }
+    /**
+     * Moves the specified Google Drive file to the trash.
+     * @returns {Promise<void>} A promise that resolves when the file is successfully trashed.
+     */
+    async trashScript() {
+        var _a;
+        debug('Deleting script %s', (_a = this.options.project) === null || _a === void 0 ? void 0 : _a.scriptId);
+        assertAuthenticated(this.options);
+        assertScriptConfigured(this.options);
+        const fileId = this.options.project.scriptId;
+        const credentials = this.options.credentials;
+        const drive = google.drive({ version: 'v3', auth: credentials });
+        try {
+            const requestOptions = {
+                fileId,
+                requestBody: {
+                    trashed: true,
+                },
+            };
+            debug('Trashing script with request %O', requestOptions);
+            await drive.files.update(requestOptions);
+        }
+        catch (error) {
+            handleApiError(error);
+        }
+    }
+    /**
+     * Creates a new Google Drive file (e.g., Sheet, Doc) and a bound Apps Script project for it.
+     * @param {string} name - The title for the new Drive file and script project.
+     * @param {string} mimeType - The MIME type of the Drive file to create (e.g., 'application/vnd.google-apps.spreadsheet').
+     * @returns {Promise<{scriptId: string; parentId: string}>} A promise that resolves to an object
+     * containing the script ID and the parent Drive file ID.
+     * @throws {Error} If there's an API error or authentication issues.
+     */
     async createWithContainer(name, mimeType) {
         var _a;
         debug('Creating container bound script %s (%s)', name, mimeType);
@@ -66,6 +135,7 @@ export class Project {
         let parentId;
         const credentials = this.options.credentials;
         const drive = google.drive({ version: 'v3', auth: credentials });
+        // Create the container file (e.g., Google Sheet, Doc) using the Drive API.
         try {
             const requestOptions = {
                 requestBody: {
@@ -75,7 +145,7 @@ export class Project {
             };
             debug('Creating project with request %O', requestOptions);
             const res = await drive.files.create(requestOptions);
-            parentId = res.data.id;
+            parentId = res.data.id; // Get the ID of the newly created container file.
             debug('Created container %s', parentId);
             if (!parentId) {
                 throw new Error('Unexpected error, container ID missing from response.');
@@ -84,12 +154,20 @@ export class Project {
         catch (error) {
             handleApiError(error);
         }
+        // Once the container is created, create an Apps Script project bound to it.
         const scriptId = await this.createScript(name, parentId);
         return {
-            parentId,
+            parentId, // Return the ID of the container.
             scriptId,
         };
     }
+    /**
+     * Lists Apps Script projects accessible by the authenticated user from Google Drive.
+     * @returns {Promise<{results: Script[], partialResults: boolean} | undefined>}
+     * A promise that resolves to an object containing an array of script projects
+     * (with name and ID) and a flag indicating if results are partial, or undefined on error.
+     * @throws {Error} If there's an API error or authentication issues.
+     */
     async listScripts() {
         debug('Fetching scripts');
         assertAuthenticated(this.options);
@@ -116,6 +194,12 @@ export class Project {
             handleApiError(error);
         }
     }
+    /**
+     * Creates a new immutable version of the Apps Script project.
+     * @param {string} [description=''] - An optional description for the new version.
+     * @returns {Promise<number>} A promise that resolves to the newly created version number.
+     * @throws {Error} If there's an API error or authentication/configuration issues.
+     */
     async version(description = '') {
         var _a;
         debug('Creating version: %s', description);
@@ -141,6 +225,13 @@ export class Project {
             handleApiError(error);
         }
     }
+    /**
+     * Lists all immutable versions of the Apps Script project.
+     * @returns {Promise<{results: script_v1.Schema$Version[], partialResults: boolean} | undefined>}
+     * A promise that resolves to an object containing an array of version objects
+     * and a flag indicating if results are partial, or undefined on error.
+     * @throws {Error} If there's an API error or authentication/configuration issues.
+     */
     async listVersions() {
         debug('Fetching versions');
         assertAuthenticated(this.options);
@@ -168,6 +259,13 @@ export class Project {
             handleApiError(error);
         }
     }
+    /**
+     * Lists all deployments for the Apps Script project.
+     * @returns {Promise<{results: script_v1.Schema$Deployment[], partialResults: boolean} | undefined>}
+     * A promise that resolves to an object containing an array of deployment objects
+     * and a flag indicating if results are partial, or undefined on error.
+     * @throws {Error} If there's an API error or authentication/configuration issues.
+     */
     async listDeployments() {
         debug('Listing deployments');
         assertAuthenticated(this.options);
@@ -195,10 +293,21 @@ export class Project {
             handleApiError(error);
         }
     }
+    /**
+     * Creates a new deployment or updates an existing one for the Apps Script project.
+     * If `versionNumber` is not provided, a new script version is created with the given `description`.
+     * @param {string} [description=''] - Description for the new version (if created) or deployment.
+     * @param {string} [deploymentId] - Optional ID of an existing deployment to update. If not provided, a new deployment is created.
+     * @param {number} [versionNumber] - Optional specific script version number to deploy.
+     * @returns {Promise<script_v1.Schema$Deployment>} A promise that resolves to the deployment object.
+     * @throws {Error} If there's an API error or authentication/configuration issues.
+     */
     async deploy(description = '', deploymentId, versionNumber) {
         debug('Deploying project: %s (%s)', description, versionNumber !== null && versionNumber !== void 0 ? versionNumber : 'HEAD');
         assertAuthenticated(this.options);
         assertScriptConfigured(this.options);
+        // If no specific versionNumber is provided for deployment,
+        // create a new version of the script with the given description.
         if (versionNumber === undefined) {
             versionNumber = await this.version(description);
         }
@@ -207,9 +316,10 @@ export class Project {
         const script = google.script({ version: 'v1', auth: credentials });
         try {
             let deployment;
+            // If no deploymentId is provided, create a new deployment.
             if (!deploymentId) {
                 const requestOptions = {
-                    scriptId: scriptId,
+                    scriptId: scriptId, // The scriptId must be provided in the request body for create.
                     requestBody: {
                         description: description !== null && description !== void 0 ? description : '',
                         versionNumber: versionNumber,
@@ -221,14 +331,15 @@ export class Project {
                 deployment = res.data;
             }
             else {
+                // If a deploymentId is provided, update the existing deployment.
                 const requestOptions = {
-                    scriptId: scriptId,
-                    deploymentId: deploymentId,
+                    scriptId: scriptId, // Path parameter for the scriptId.
+                    deploymentId: deploymentId, // Path parameter for the deploymentId to update.
                     requestBody: {
                         deploymentConfig: {
                             description: description !== null && description !== void 0 ? description : '',
                             versionNumber: versionNumber,
-                            scriptId: scriptId,
+                            scriptId: scriptId, // The scriptId also needs to be in the deploymentConfig.
                             manifestFileName: 'appsscript',
                         },
                     },
@@ -237,12 +348,20 @@ export class Project {
                 const res = await script.projects.deployments.update(requestOptions);
                 deployment = res.data;
             }
-            return deployment;
+            return deployment; // Return the created or updated deployment object.
         }
         catch (error) {
             handleApiError(error);
         }
     }
+    /**
+     * Retrieves the entry points for a specific deployment of the Apps Script project.
+     * Entry points define how the script can be executed (e.g., as a web app, API executable).
+     * @param {string} deploymentId - The ID of the deployment.
+     * @returns {Promise<script_v1.Schema$EntryPoint[] | undefined>} A promise that resolves to an array
+     * of entry point objects, or undefined if an error occurs.
+     * @throws {Error} If there's an API error or authentication/configuration issues.
+     */
     async entryPoints(deploymentId) {
         var _a, _b;
         assertAuthenticated(this.options);
@@ -259,6 +378,12 @@ export class Project {
             handleApiError(error);
         }
     }
+    /**
+     * Deletes a specific deployment of the Apps Script project.
+     * @param {string} deploymentId - The ID of the deployment to delete.
+     * @returns {Promise<void>} A promise that resolves when the deployment is deleted.
+     * @throws {Error} If there's an API error or authentication/configuration issues.
+     */
     async undeploy(deploymentId) {
         debug('Deleting deployment %s', deploymentId);
         assertAuthenticated(this.options);
@@ -278,6 +403,12 @@ export class Project {
             handleApiError(error);
         }
     }
+    /**
+     * Writes the current project settings (script ID, root directory, parent ID, project ID,
+     * file extensions, push order, skip subdirectories) to the `.clasp.json` file.
+     * @returns {Promise<void>} A promise that resolves when the settings are written.
+     * @throws {Error} If the script is not configured or there's a file system error.
+     */
     async updateSettings() {
         debug('Updating settings');
         assertScriptConfigured(this.options);
@@ -295,16 +426,32 @@ export class Project {
         };
         await fs.writeFile(this.options.configFilePath, JSON.stringify(settings, null, 2));
     }
+    /**
+     * Sets the Google Cloud Platform (GCP) project ID for the current Apps Script project
+     * and updates the `.clasp.json` file.
+     * @param {string | undefined} projectId - The GCP project ID to set.
+     * @returns {Promise<void>} A promise that resolves when the project ID is set and settings are updated.
+     * @throws {Error} If the script is not configured.
+     */
     async setProjectId(projectId) {
         debug('Setting project ID %s in file %s', projectId, this.options.configFilePath);
         assertScriptConfigured(this.options);
         this.options.project.projectId = projectId;
         this.updateSettings();
     }
+    /**
+     * Checks if a script project is currently configured (i.e., if a script ID is set).
+     * @returns {boolean} True if a script ID is set, false otherwise.
+     */
     exists() {
         var _a;
         return ((_a = this.options.project) === null || _a === void 0 ? void 0 : _a.scriptId) !== undefined;
     }
+    /**
+     * Reads and parses the `appsscript.json` manifest file from the project's content directory.
+     * @returns {Promise<Manifest>} A promise that resolves to the parsed manifest object.
+     * @throws {Error} If the script is not configured or the manifest file cannot be read/parsed.
+     */
     async readManifest() {
         debug('Reading manifest');
         assertScriptConfigured(this.options);

package/build/src/core/services.js

@@ -1,3 +1,19 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// This file defines the `Services` class, which handles the management of
+// Google Cloud Platform (GCP) services and Advanced Google Services for an
+// Apps Script project, including enabling, disabling, and listing services.
 import path from 'path';
 import Debug from 'debug';
 import fs from 'fs/promises';
@@ -6,10 +22,23 @@ import { PUBLIC_ADVANCED_SERVICES } from './apis.js';
 import { assertGcpProjectConfigured, handleApiError } from './utils.js';
 import { fetchWithPages } from './utils.js';
 const debug = Debug('clasp:core');
+/**
+ * Manages the Google Cloud Platform (GCP) services and Advanced Google Services
+ * associated with an Apps Script project. This includes listing available and
+ * enabled services, as well as enabling or disabling services for the project.
+ */
 export class Services {
     constructor(config) {
         this.options = config;
     }
+    /**
+     * Retrieves a list of Google Cloud Platform (GCP) services that are currently
+     * enabled for the associated Apps Script project.
+     * @returns {Promise<Service[] | undefined>} A promise that resolves to an array of enabled
+     * services (with id, name, and description), or undefined if an error occurs.
+     * Filters for services that are also listed as public advanced services.
+     * @throws {Error} If the GCP project is not configured or authentication fails.
+     */
     async getEnabledServices() {
         debug('Fetching enabled services');
         assertGcpProjectConfigured(this.options);
@@ -35,24 +64,31 @@ export class Services {
                 maxResults: 10000,
             });
             // Filter out the disabled ones. Print the enabled ones.
+            // Filter out the disabled ones. Print the enabled ones.
             const truncateName = (name) => {
+                // Service names from API might be like 'sheets.googleapis.com'.
+                // We only want the 'sheets' part for matching with PUBLIC_ADVANCED_SERVICES.
                 const i = name.indexOf('.');
                 if (i !== -1) {
                     return name.slice(0, i);
                 }
                 return name;
             };
+            // Get a list of serviceIds from our known public advanced services.
             const allowedIds = PUBLIC_ADVANCED_SERVICES.map(service => service.serviceId);
+            // Map the raw service list from API to our simplified `Service` type
+            // and filter them to include only those that are known public advanced services.
             return serviceList.results
                 .map(service => {
                 var _a, _b, _c, _d, _e, _f;
                 return ({
-                    id: (_a = service.name) !== null && _a !== void 0 ? _a : '',
-                    name: truncateName((_c = (_b = service.config) === null || _b === void 0 ? void 0 : _b.name) !== null && _c !== void 0 ? _c : 'Unknown name'),
+                    id: (_a = service.name) !== null && _a !== void 0 ? _a : '', // Full name like 'sheets.googleapis.com'
+                    name: truncateName((_c = (_b = service.config) === null || _b === void 0 ? void 0 : _b.name) !== null && _c !== void 0 ? _c : 'Unknown name'), // Short name like 'sheets'
                     description: (_f = (_e = (_d = service.config) === null || _d === void 0 ? void 0 : _d.documentation) === null || _e === void 0 ? void 0 : _e.summary) !== null && _f !== void 0 ? _f : '',
                 });
             })
                 .filter(service => {
+                // Only include services that are in our `PUBLIC_ADVANCED_SERVICES` list.
                 return allowedIds.indexOf(service.name) !== -1;
             });
         }
@@ -60,19 +96,33 @@ export class Services {
             handleApiError(error);
         }
     }
+    /**
+     * Retrieves a list of all publicly available Google Advanced Services that can be
+     * enabled for an Apps Script project.
+     * @returns {Promise<Service[] | undefined>} A promise that resolves to an array of available
+     * services (with id, name, and description), or undefined if an error occurs.
+     * @throws {Error} If there's an API error.
+     */
     async getAvailableServices() {
         var _a;
         debug('Fetching available services');
         const discovery = google.discovery({ version: 'v1' });
         try {
+            // Fetch the list of all discoverable APIs. 'preferred: true' typically gets the recommended versions.
             const { data } = await discovery.apis.list({
                 preferred: true,
             });
+            // Get a list of serviceIds from our known public advanced services for filtering.
             const allowedIds = PUBLIC_ADVANCED_SERVICES.map(service => service.serviceId);
             const allServices = (_a = data.items) !== null && _a !== void 0 ? _a : [];
+            // Type guard to ensure the service item has the properties we expect and is a known advanced service.
             const isValidService = (s) => {
-                return (s.id !== undefined && s.name !== undefined && allowedIds.indexOf(s.name) !== -1 && s.description !== undefined);
+                return (s.id !== undefined &&
+                    s.name !== undefined &&
+                    allowedIds.indexOf(s.name) !== -1 && // Check if the service's short name is in our list
+                    s.description !== undefined);
             };
+            // Filter the list of all discoverable APIs to only include valid, known advanced services.
             const services = allServices.filter(isValidService).sort((a, b) => a.id.localeCompare(b.id));
             debug('Available services: %O', services);
             return services;
@@ -81,6 +131,17 @@ export class Services {
             handleApiError(error);
         }
     }
+    /**
+     * Enables a specified Google Advanced Service for the Apps Script project.
+     * This involves two steps:
+     * 1. Enabling the corresponding service in the Google Cloud Platform (GCP) project.
+     * 2. Updating the `appsscript.json` manifest file to include the service in its dependencies.
+     * @param {string} serviceName - The service ID (e.g., 'sheets', 'docs') of the service to enable.
+     * @returns {Promise<void>} A promise that resolves when the service is enabled.
+     * @throws {Error} If the service name is not provided, the manifest file doesn't exist,
+     * the service is not a valid advanced service, or if there's an API error or
+     * authentication/configuration issue.
+     */
     async enableService(serviceName) {
         var _a;
         debug('Enabling service %s', serviceName);
@@ -94,39 +155,59 @@ export class Services {
         const manifestExists = await hasReadWriteAccess(manifestPath);
         if (!manifestExists) {
             debug('Manifest file at %s does not exist', manifestPath);
-            throw new Error('Manifest file does not exist.');
+            throw new Error('Manifest file does not exist.'); // Prerequisite: manifest must exist.
         }
+        // Find the service details from our list of known public advanced services.
         const advancedService = PUBLIC_ADVANCED_SERVICES.find(service => service.serviceId === serviceName);
         if (!advancedService) {
-            throw new Error('Service is not a valid advanced service.');
+            throw new Error('Service is not a valid advanced service.'); // Ensure it's a known service.
         }
-        // Do not update manifest if not valid advanced service
+        // Update the manifest file to include the new service.
         debug('Service is an advanced service, updating manifest');
         const content = await fs.readFile(manifestPath);
         const manifest = JSON.parse(content.toString());
+        // Ensure the dependencies structure exists and add the service if not already present.
         if ((_a = manifest.dependencies) === null || _a === void 0 ? void 0 : _a.enabledAdvancedServices) {
+            // Check if the service (by its userSymbol) is already in the manifest.
             if (manifest.dependencies.enabledAdvancedServices.findIndex(s => s.userSymbol === advancedService.userSymbol) === -1) {
                 manifest.dependencies.enabledAdvancedServices.push(advancedService);
             }
         }
         else if (manifest.dependencies) {
+            // If 'dependencies' exists but 'enabledAdvancedServices' doesn't, create it.
             manifest.dependencies.enabledAdvancedServices = [advancedService];
         }
         else {
+            // If 'dependencies' itself doesn't exist, create the full structure.
             manifest.dependencies = { enabledAdvancedServices: [advancedService] };
         }
         debug('Updating manifest at %s with %j', manifestPath, manifest);
         await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2));
+        // Enable the corresponding service in the GCP project via the Service Usage API.
         debug('Enabling GCP service %s.googleapis.com', serviceName);
         const serviceUsage = google.serviceusage({ version: 'v1', auth: this.options.credentials });
-        const resourceName = `projects/${projectId}/services/${serviceName}.googleapis.com`;
+        const resourceName = `projects/${projectId}/services/${serviceName}.googleapis.com`; // Construct the service resource name.
         try {
             await serviceUsage.services.enable({ name: resourceName });
         }
         catch (error) {
+            // Note: If this GCP API call fails, the manifest will have been updated,
+            // but the service might not be enabled in GCP. This could lead to an inconsistent state.
+            // More robust error handling might involve reverting manifest changes or providing specific guidance.
             handleApiError(error);
         }
     }
+    /**
+     * Disables a specified Google Advanced Service for the Apps Script project.
+     * This involves two steps:
+     * 1. Disabling the corresponding service in the Google Cloud Platform (GCP) project.
+     * 2. Removing the service from the `appsscript.json` manifest file's dependencies.
+     * @param {string} serviceName - The service ID (e.g., 'sheets', 'docs') of the service to disable.
+     * @returns {Promise<void>} A promise that resolves when the service is disabled.
+     * @throws {Error} If the service name is not provided, the manifest file doesn't exist,
+     * the service is not a valid advanced service, or if there's an API error or
+     * authentication/configuration issue.
+     */
     async disableService(serviceName) {
         var _a;
         debug('Disabling service %s', serviceName);
@@ -140,30 +221,38 @@ export class Services {
         const manifestExists = await hasReadWriteAccess(manifestPath);
         if (!manifestExists) {
             debug('Manifest file at %s does not exist', manifestPath);
-            throw new Error('Manifest file does not exist.');
+            throw new Error('Manifest file does not exist.'); // Prerequisite: manifest must exist.
         }
+        // Find the service details from our list of known public advanced services.
         const advancedService = PUBLIC_ADVANCED_SERVICES.find(service => service.serviceId === serviceName);
         if (!advancedService) {
-            throw new Error('Service is not a valid advanced service.');
+            throw new Error('Service is not a valid advanced service.'); // Ensure it's a known service.
         }
-        // Do not update manifest if not valid advanced service
+        // Update the manifest file to remove the service.
         debug('Service is an advanced service, updating manifest');
         const content = await fs.readFile(manifestPath);
         const manifest = JSON.parse(content.toString());
+        // If dependencies or enabledAdvancedServices array doesn't exist, or service not found, nothing to do for manifest.
         if (!((_a = manifest.dependencies) === null || _a === void 0 ? void 0 : _a.enabledAdvancedServices)) {
-            debug('Service enabled in manifest, skipping manifest update');
-            return;
+            debug('Service not listed as enabled in manifest, skipping manifest update for disabling.');
+            // Continue to attempt disabling at GCP level, as manifest might be out of sync.
         }
-        manifest.dependencies.enabledAdvancedServices = manifest.dependencies.enabledAdvancedServices.filter(service => service.serviceId !== serviceName);
-        debug('Updating manifest at %s with %j', manifestPath, manifest);
-        await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2));
+        else {
+            // Filter out the service to be disabled.
+            manifest.dependencies.enabledAdvancedServices = manifest.dependencies.enabledAdvancedServices.filter(service => service.serviceId !== serviceName);
+            debug('Updating manifest at %s with %j', manifestPath, manifest);
+            await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2));
+        }
+        // Disable the corresponding service in the GCP project via the Service Usage API.
         debug('Disabling GCP service %s.googleapis.com', serviceName);
         const serviceUsage = google.serviceusage({ version: 'v1', auth: this.options.credentials });
-        const resourceName = `projects/${projectId}/services/${serviceName}.googleapis.com`;
+        const resourceName = `projects/${projectId}/services/${serviceName}.googleapis.com`; // Construct the service resource name.
         try {
             await serviceUsage.services.disable({ name: resourceName });
         }
         catch (error) {
+            // Note: Similar to enableService, if this GCP API call fails, the manifest might have been updated,
+            // potentially leading to an inconsistent state (service disabled in manifest but still active in GCP).
             handleApiError(error);
         }
     }

package/build/src/core/utils.js

@@ -1,6 +1,28 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// This file provides utility types, assertion functions, and helper functions
+// (like for API pagination and error handling) used across the core modules
+// of clasp.
 import Debug from 'debug';
 import { GaxiosError } from 'googleapis-common';
 const debug = Debug('clasp:core');
+/**
+ * Asserts that the provided ClaspOptions include credentials.
+ * Throws an error if credentials are not set. This also acts as a type guard.
+ * @param {ClaspOptions} options - The Clasp options to check.
+ * @throws {Error} If `options.credentials` is not set.
+ */
 export function assertAuthenticated(options) {
     if (!options.credentials) {
         debug('Credentials not set in options: %O', options);
@@ -11,6 +33,13 @@ export function assertAuthenticated(options) {
         });
     }
 }
+/**
+ * Asserts that the provided ClaspOptions include essential script project configurations.
+ * Throws an error if `scriptId`, `projectRootDir`, `configFilePath`, or `contentDir` are missing.
+ * This also acts as a type guard.
+ * @param {ClaspOptions} options - The Clasp options to check.
+ * @throws {Error} If essential script configurations are missing.
+ */
 export function assertScriptConfigured(options) {
     var _a;
     if (!((_a = options.project) === null || _a === void 0 ? void 0 : _a.scriptId) ||
@@ -25,6 +54,12 @@ export function assertScriptConfigured(options) {
         });
     }
 }
+/**
+ * Asserts that the provided ClaspOptions include a GCP project ID, in addition to base script configurations.
+ * Throws an error if `projectId` is missing. This also acts as a type guard.
+ * @param {ClaspOptions} options - The Clasp options to check.
+ * @throws {Error} If `options.project.projectId` is not set.
+ */
 export function assertGcpProjectConfigured(options) {
     var _a;
     assertScriptConfigured(options);
@@ -74,6 +109,11 @@ export async function fetchWithPages(fn, options) {
         partialResults: pageToken !== undefined,
     };
 }
+/**
+ * Checks if an error object is a GaxiosError with detailed error information.
+ * @param {unknown} error - The error object to check.
+ * @returns {boolean} True if the error is a GaxiosError with details, false otherwise.
+ */
 function isDetailedError(error) {
     if (!error) {
         return false;
@@ -93,13 +133,20 @@ const ERROR_CODES = {
     403: 'NOT_AUTHORIZED',
     404: 'NOT_FOUND',
 };
+/**
+ * Standardized error handler for Google API errors (GaxiosError).
+ * It extracts a meaningful message and error code, then re-throws a new error.
+ * @param {unknown} error - The error received from a Google API call.
+ * @throws {Error} A new error with a structured cause including the original error,
+ * a clasp-specific error code, and the message.
+ */
 export function handleApiError(error) {
     var _a;
     debug('Handling API error: %O', error);
     if (!(error instanceof GaxiosError)) {
         throw new Error('Unexpected error', {
             cause: {
-                code: 'UNEPECTED_ERROR',
+                code: 'UNEXPECTED_ERROR',
                 message: new String(error),
                 error: error,
             },
@@ -119,6 +166,15 @@ export function handleApiError(error) {
         },
     });
 }
+/**
+ * Ensures that a value is an array of strings.
+ * If the input is a single string, it's wrapped in an array.
+ * If it's already an array of strings, it's returned as is.
+ * If it's an array containing non-string elements, those elements are filtered out.
+ * If the input is neither a string nor an array, an empty array is returned.
+ * @param {string | string[]} value - The value to process.
+ * @returns {string[]} An array of strings.
+ */
 export function ensureStringArray(value) {
     if (typeof value === 'string') {
         return [value];