@google-cloud/nodejs-common 2.2.2 → 2.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@google-cloud/nodejs-common",
-  "version": "2.2.2",
+  "version": "2.3.1",
   "description": "A NodeJs common library for solutions based on Cloud Functions",
   "author": "Google Inc.",
   "license": "Apache-2.0",
@@ -16,28 +16,26 @@
   },
   "homepage": "https://github.com/GoogleCloudPlatform/cloud-for-marketing/blob/master/marketing-analytics/activation/common-libs/nodejs-common/README.md",
   "dependencies": {
-    "@google-cloud/aiplatform": "^3.17.0",
+    "@google-cloud/aiplatform": "^3.25.0",
     "@google-cloud/automl": "^4.0.1",
-    "@google-cloud/bigquery": "^7.5.2",
-    "@google-cloud/datastore": "^8.6.0",
-    "@google-cloud/firestore": "^7.5.0",
+    "@google-cloud/bigquery": "^7.8.0",
+    "@google-cloud/datastore": "^9.1.0",
+    "@google-cloud/firestore": "^7.9.0",
     "@google-cloud/logging-winston": "^6.0.0",
-    "@google-cloud/pubsub": "^4.3.3",
-    "@google-cloud/storage": "^7.9.0",
-    "@google-cloud/scheduler": "^4.1.0",
-    "@google-cloud/secret-manager": "^5.2.0",
-    "gaxios": "^6.3.0",
+    "@google-cloud/pubsub": "^4.5.0",
+    "@google-cloud/storage": "^7.12.0",
+    "@google-cloud/scheduler": "^4.3.0",
+    "@google-cloud/secret-manager": "^5.6.0",
+    "gaxios": "^6.7.0",
     "google-ads-nodejs-client": "16.0.0",
-    "google-ads-api": "^14.1.0",
-    "google-ads-node": "^12.0.2",
-    "google-auth-library": "^9.7.0",
-    "googleapis": "^134.0.0",
-    "winston": "^3.13.0",
-    "@grpc/grpc-js": "^1.10.5",
+    "google-auth-library": "^9.11.0",
+    "googleapis": "^140.0.1",
+    "winston": "^3.13.1",
+    "@grpc/grpc-js": "^1.11.1",
     "lodash": "^4.17.21"
   },
   "devDependencies": {
-    "jasmine": "^5.1.0"
+    "jasmine": "^5.2.0"
   },
   "scripts": {
     "test": "node node_modules/jasmine/bin/jasmine"

package/src/apis/auth_client.js

@@ -48,23 +48,23 @@ const DEFAULT_ENV_KEYFILE = 'API_SERVICE_ACCOUNT';
  *
  * There are two use cases for this authentication helper class:
  * 1. The user only has OAuth access due to some reasons, so ADC can't be used;
- * 2. User-managed service account is requried for external APIs for some
+ * 2. User-managed service account is required for external APIs for some
  * specific considerations, e.g. security. In this case, a file based key file
  * can be used to generate a JWT auth client.
  *
  * To solve these challenges, this class tries to probe the settings from
- * enviroment variables, starts from the name of secret (Secret Manager), OAuth
+ * environment variables, starts from the name of secret (Secret Manager), OAuth
  * token file (deprecated), then service account key file (deprecated). It will
  * fallback to ADC if those probing failed.
- * Note, Secret Manager is the recommanded way to store tokens because it is a
+ * Note, Secret Manager is the recommended way to store tokens because it is a
  * secure and convenient central storage system to manage access across Google
  * Cloud.
  *
  * The recommended environment variable is:
  * SECRET_NAME: the name of secret. The secret can be a oauth token file or a
  * service account key file. This env var is used to offer a global auth for a
- * solution. If different auths are required, the value of passed `env` can be
- * set
+ * solution. If different authentications are required, the value of passed
+ * `env` can be set by the runtime.
  *
  * Alternative environment variable but not recommended for prod environment:
  * OAUTH2_TOKEN_JSON : the oauth token key files, refresh token and proper API
@@ -88,7 +88,7 @@ class AuthClient {
 
   /**
    * Prepares the `oauthToken` object and/or `serviceAccountKey` based on the
-   * settings in enviroment object.
+   * settings in environment object.
    * A secret name is preferred to offer the token of the OAuth or key of a
    * service account.
    * To be compatible, this function also checks the env for oauth token file
@@ -100,10 +100,10 @@ class AuthClient {
       return;
     }
     if (this.env[DEFAULT_ENV_SECRET]) {
-      const secretmanager = new SecretManager({
+      const secretManager = new SecretManager({
         projectId: this.env.GCP_PROJECT,
       });
-      const secret = await secretmanager.access(this.env[DEFAULT_ENV_SECRET]);
+      const secret = await secretManager.access(this.env[DEFAULT_ENV_SECRET]);
       if (secret) {
         const secretObj = JSON.parse(secret);
         if (secretObj.token) this.oauthToken = secretObj;
@@ -127,7 +127,7 @@ class AuthClient {
   }
 
   /**
-   * Factory method to offer a prepared AuthClient intance in an async way.
+   * Factory method to offer a prepared AuthClient instance in an async way.
    * @param {string|!Array<string>|!ReadonlyArray<string>} scopes
    * @param {!Object<string,string>=} env The environment object to hold env
    *     variables.
@@ -163,7 +163,7 @@ class AuthClient {
    * steps:
    * 1. Checks environment variable GOOGLE_APPLICATION_CREDENTIALS to get
    * service account. Returns a JWT if it exists;
-   * 2. Uses default service account of Computer Engine/AppEngige/Cloud
+   * 2. Uses default service account of Computer Engine/AppEngine/Cloud
    * Functions
    * 3. Otherwise, an error occurs.
    * @see https://cloud.google.com/docs/authentication/production#obtaining_and_providing_service_account_credentials_manually

package/src/apis/base/ads_api_common.js

@@ -38,7 +38,7 @@ const END_TAG = '"requestId"';
 
 /**
  * A stream.Transform that can extract properties and convert naming of the
- * reponse of Google/Search Ads report from REST interface.
+ * response of Google/Search Ads report from REST interface.
  */
 class RestSearchStreamTransform extends Transform {
 

package/src/apis/base/google_api_client.js

@@ -16,7 +16,7 @@
  * @fileoverview A base class for Google Api client library class.
  */
 const { google } = require('googleapis');
-const { getLogger, getObjectByPath } = require('../../components/utils.js');
+const { getLogger } = require('../../components/utils.js');
 const { AuthRestfulApi } = require('./auth_restful_api.js');
 
 /**

package/src/apis/doubleclick_bidmanager.js

@@ -94,13 +94,13 @@ class DoubleClickBidManager extends GoogleApiClient {
    * Gets a query metadata.
    * See https://developers.google.com/bid-manager/reference/rest/v2/queries/get
    * @param {number} queryId Id of the query.
-   * @return {!Promise<!QueryMetadata>} Query metadata, see
-   *     https://developers.google.com/bid-manager/reference/rest/v2/queries#QueryMetadata
+   * @return {!Promise<!Query>} Query, see
+   *     https://developers.google.com/bid-manager/reference/rest/v2/queries#Query
    */
   async getQuery(queryId) {
     const doubleclickbidmanager = await this.getApiClient();
     const response = await doubleclickbidmanager.queries.get({ queryId });
-    return response.data.metadata;
+    return response.data;
   }
 
   /**

package/src/apis/gmail.js

@@ -0,0 +1,113 @@
+// Copyright 2024 Google Inc.
+//
+// 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
+//
+//      http://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.
+
+/** @fileoverview Gmail API Client Library. */
+
+'use strict';
+
+const { GoogleApiClient } = require('./base/google_api_client.js');
+
+const API_SCOPES =
+  Object.freeze(['https://www.googleapis.com/auth/gmail.send']);
+const API_VERSION = 'v1';
+
+/**
+ * @typedef {{
+ *     from: string|undefined,
+ *     to: string|Array<string>,
+ *     cc: string|Array<string>|undefined,
+ *     bcc: string|Array<string>|undefined,
+ *     'reply-to': string|Array<string>|undefined,
+ *     subject: string,
+ *     content: string,
+ *     type: 'text/plain'|'text/html'|undefined,
+ * }}
+ */
+let EmailOptions;
+
+/**
+ * Email sending class based on Gmail API.
+ */
+class Gmail extends GoogleApiClient {
+
+  constructor(env = process.env) {
+    super(env);
+    this.googleApi = 'gmail';
+  }
+
+  /** @override */
+  getScope() {
+    return API_SCOPES;
+  }
+
+  /** @override */
+  getVersion() {
+    return API_VERSION;
+  }
+
+  /**
+   * Generates a string for an email in RFC 2822 format.
+   * If 'from' is different from the OAuth token's owner account, it would be
+   * ignored.
+   * @param {!EmailOptions} options
+   * @return {string}
+   * @private
+   */
+  getRawEmail_(options = {}) {
+    const message = [];
+    ['from', 'to', 'cc', 'bcc', 'reply-to', 'subject'].forEach((key) => {
+      if (options[key]) {
+        const value = Array.isArray(options[key])
+          ? options[key].join(',') : options[key];
+        message.push(`${key}: ${value}`);
+      }
+    });
+    if (message.length === 0)
+      throw new Error(`Can not get email from ${options}`);
+    message.push('\n');
+    message.push(options.content);
+    return message.join('\n');
+  }
+
+  /**
+   * Sends a simple email (no attachment).
+   * @see https://developers.google.com/gmail/api/reference/rest/v1/users.messages/send
+   * @param {!EmailOptions} options
+   * @return {!Message}
+   */
+  async sendSimpleEmail(options) {
+    const email = this.getRawEmail_(options);
+
+    const gmail = await this.getApiClient();
+    const message = {
+      userId: 'me',
+      requestBody: { raw: Buffer.from(email).toString('base64') }
+    };
+    try {
+      const response = await gmail.users.messages.send(message);
+      return { responseStatus: response.status };
+    } catch (error) {
+      this.logger.error('Result of sending an email', JSON.stringify(error));
+      return { responseStatus: error.status };
+    }
+  }
+
+}
+
+module.exports = {
+  Gmail,
+  EmailOptions,
+  API_SCOPES,
+  API_VERSION,
+};

package/src/apis/google_ads_api.js

@@ -211,7 +211,7 @@ const MAX_IDENTIFIERS = {
 };
 
 /**
- * Configuration for uploading click conversions, call converions or conversion
+ * Configuration for uploading click conversions, call conversions or conversion
  * adjustments for Google Ads, includes:
  * gclid, conversionAction, conversionDateTime, conversionValue,
  * currencyCode, orderId, externalAttributionData,
@@ -598,7 +598,7 @@ class GoogleAdsApi {
    * e.g. wrong conversion Id, wrong gclid, etc.
    * `Status` has a property `message` that has the general information of the
    * error, however, the detailed information (e.g. the failed conversions and
-   * their reasons) lies in the property named `datails` (an array of
+   * their reasons) lies in the property named `details` (an array of
    * `GoogleAdsFailure`). Each `GoogleAdsFailure` is related to a failed
    * conversion. The function `extraFailedLines_` is used to extract the
    * details.
@@ -612,8 +612,8 @@ class GoogleAdsApi {
    * @param {string} customerId
    * @param {string} loginCustomerId Login customer account ID (Mcc Account id).
    * @param {!ConversionConfig} conversionConfig Default conversion parameters.
-   * @param {string} functionName The name of sending converions function, could
-   *   be `uploadClickConversions`, `uploadCallConversions` or
+   * @param {string} functionName The name of sending conversions function,
+   *   could be `uploadClickConversions`, `uploadCallConversions` or
    *   `uploadConversionAdjustments`.
    * @param {string} propertyForDebug The name of property for debug info.
    * @return {!SendSingleBatch} Function which can send a batch of hits to
@@ -945,8 +945,8 @@ class GoogleAdsApi {
         AND user_list.membership_status = OPEN
         AND user_list.crm_based_user_list.upload_key_type = ${uploadKeyType}
     `;
-    const userlists = await this.getReport(customerId, loginCustomerId, query);
-    return userlists.length === 0 ? undefined : userlists[0].userList.id;
+    const userLists = await this.getReport(customerId, loginCustomerId, query);
+    return userLists.length === 0 ? undefined : userLists[0].userList.id;
   }
 
   /**
@@ -954,8 +954,8 @@ class GoogleAdsApi {
    * Id. The user list would be a CRM_BASED type.
    * Trying to create a list with an used name will fail.
    * The Google Ads service behind this function (UserListService) supports
-   * `partial_failure`. Here, we only create one userlist at one time, so
-   * `partial_failure` is disabled to simplified the error handleing process.
+   * `partial_failure`. Here, we only create one user list at one time, so
+   * `partial_failure` is disabled to simplified the error handling process.
    * @see getUploadConversionFnBase_ for more details of error handling.
    * @param {!CustomerMatchConfig} customerMatchConfig
    * @return {number} The created user list id. Note this is not the resource
@@ -973,7 +973,7 @@ class GoogleAdsApi {
       customerId: getCleanCid(customerId),
       operations: [{ create: userList }],
       validateOnly: this.debugMode, // when true makes no changes
-      partialFailure: false, // Simplify error handling in creating userlist
+      partialFailure: false, // Simplify error handling in creating user list
     });
     const client = await this.getUserListServiceClient_();
     const options = this.getCallOptions_(loginCustomerId);
@@ -984,7 +984,7 @@ class GoogleAdsApi {
        */
       const [response] = await client.mutateUserLists(request, options);
       const { results } = response; // No `partialFailureError` here.
-      this.logger.debug(`Created crm userlist from`, customerMatchConfig);
+      this.logger.debug(`Created crm user list from`, customerMatchConfig);
       if (!results[0]) {
         if (this.debugMode) {
           throw new Error('No UserList was created in DEBUG mode.');
@@ -1139,7 +1139,7 @@ class GoogleAdsApi {
   /**
    * Creates a OfflineUserDataJob and returns resource name.
    * @param {OfflineUserDataJobConfig} offlineUserDataJobConfig
-   * @return {string} The resouce name of the creaed job.
+   * @return {string} The resource name of the created job.
    */
   async createOfflineUserDataJob(offlineUserDataJobConfig) {
     const config = this.getCamelConfig_(offlineUserDataJobConfig);
@@ -1231,7 +1231,7 @@ class GoogleAdsApi {
         this.logger.debug(`Add operation to job batch[${batchId}]`, response);
         const { partialFailureError: failed } = response;
         if (failed) {
-          this.logger.info(`Job[${jobResourceName}] faile:`, failed.message);
+          this.logger.info(`Job[${jobResourceName}] fail:`, failed.message);
           const failures = failed.details.map(
             ({ value }) => GoogleAdsFailure.decode(value));
           this.extraFailedLines_(batchResult, failures, lines, 0);
@@ -1331,7 +1331,7 @@ class GoogleAdsApi {
 
   /**
    * Returns a HTTP header object contains the authentication information for
-   * Google Ads API, include: `developer-token` and `ogin-customer-id`.
+   * Google Ads API, include: `developer-token` and `login-customer-id`.
    * @param {string} loginCustomerId
    * @return {object} The HTTP header object.
    * @private
@@ -1360,7 +1360,7 @@ class GoogleAdsApi {
   }
 
   /**
-   * Prepares the feach data service client instance.
+   * Prepares the fetch data service client instance.
    * @return {!GoogleAdsServiceClient}
    * @private
    */
@@ -1447,8 +1447,8 @@ class GoogleAdsApi {
 }
 
 /**
- * Returns an arrary of UserIdentifier object based the given JSON object.
- * @param {Object} record An object contains user indentifier information.
+ * Returns an array of UserIdentifier object based the given JSON object.
+ * @param {Object} record An object contains user identifier information.
  * @param {!Array<string>} identifierTypes An list of user identifier types that
  *   are supported by the target service.
  * @param {number} maximumNumOfIdentifiers The maximum number of user
@@ -1541,7 +1541,7 @@ const buildConversionJsonList = (lines, config, conversionFields,
     })
 }
 /**
- * Returns an arrary of UserData object based on the given arran of JSON strings.
+ * Returns an array of UserData object based on the given arran of JSON strings.
  * @param {!Array<string>} lines An array of JSON strings of UserData.
  * @param {{
  *   additionalAttributes: (!UserIdentifierSource|undefined)

package/src/apis/index.js

@@ -99,18 +99,6 @@ exports.doubleclickbidmanager = require('./doubleclick_bidmanager.js');
  */
 exports.bigquery = require('./bigquery.js');
 
-/**
- * APIs integration class for Google Ads.
- * @const {{
- *   GoogleAds:!GoogleAds,
- *   ConversionConfig:!ConversionConfig,
- *   CustomerMatchConfig: !CustomerMatchConfig,
- *   CustomerMatchRecord: !CustomerMatchRecord,
- *   ReportQueryConfig:!ReportQueryConfig,
- * }}
- */
-exports.googleads = require('./google_ads.js');
-
 /**
  * APIs integration class for Google Ads with Google API library.
  * @const {{
@@ -146,9 +134,7 @@ exports.measurementprotocolga4 = require('./measurement_protocol_ga4.js');
 /**
  * APIs integration class for YouTube.
  * @const {{
- *   YouTube:!YouTube,
- *   ListChannelsConfig: !ListChannelsConfig,
- *   ListVideosConfig: !ListVideosConfig,
+ *   YouTube:!YouTube
  * }}
  */
 exports.youtube = require('./youtube.js');
@@ -162,3 +148,12 @@ exports.youtube = require('./youtube.js');
 * }}
 */
 exports.sendgrid = require('./sendgrid.js');
+
+/**
+ * APIs integration class for Gmail.
+ * @const {{
+*   Gmail:!Gmail,
+*   API_VERSION: string,
+* }}
+*/
+exports.gmail = require('./gmail.js');

package/src/apis/sendgrid.js

@@ -18,12 +18,33 @@
 
 'use strict';
 
+const { EmailOptions } = require('./gmail.js');
 const { RestfulApiBase } = require('./base/restful_api_base.js');
 const { getLogger } = require('../components/utils.js');
 
 const API_VERSION = 'v3';
 const API_ENDPOINT = 'https://api.sendgrid.com';
 
+/**
+ * Returns a SendGrid email object based on a given RFC 2822 `mailbox` string.
+ * For `mailbox` @see https://www.rfc-editor.org/rfc/rfc2822#page-15
+ * @param {string} mailbox
+ * @return {{name: string, email: string}} A SendGrid email object.
+ */
+function getSendGridEmail(mailbox) {
+  if (typeof mailbox === 'string') {
+    if (mailbox.indexOf('<') > -1) {
+      const name = mailbox.substring(0, mailbox.indexOf('<')).trim();
+      const email =
+        mailbox.substring(mailbox.indexOf('<') + 1, mailbox.indexOf('>'));
+      return { name, email };
+    } else {
+      return { email: mailbox.trim() };
+    }
+  }
+  return mailbox;
+}
+
 /**
  * SendGrid API access class.
  * @see https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api/authentication
@@ -48,11 +69,51 @@ class SendGrid extends RestfulApiBase {
     });
   }
 
+  /**
+   * Generates an email object for Sendgrid.
+   * @param {!EmailOptions} options
+   * @return {object}
+   * @see https://www.twilio.com/docs/sendgrid/api-reference/mail-send/mail-send#reques
+   * @private
+   */
+  getEmail_(options = {}) {
+    const {
+      from,
+      'reply-to': reply_to,
+      subject,
+      content,
+      type = 'text/plain',
+    } = options;
+    const recipientObject = {};
+    ['to', 'cc', 'bcc'].forEach((key) => {
+      if (options[key]) {
+        recipientObject[key] = [options[key]].flat().map(getSendGridEmail);
+      }
+    });
+    const email = {
+      subject,
+      content: [{ type, value: content }],
+      personalizations: [recipientObject],
+    };
+    if (from) email.from = getSendGridEmail(from);
+    //@see https://www.twilio.com/docs/sendgrid/api-reference/mail-send/mail-send#reques
+    if (reply_to) {
+      if (Array.isArray(reply_to)) {
+        email.reply_to_list = reply_to.map(getSendGridEmail);
+      } else {
+        email.reply_to = getSendGridEmail(reply_to);
+      }
+    }
+    return email;
+  }
+
   /**
    * Sends an email.
+   * @param {!EmailOptions} options
    * @see https://docs.sendgrid.com/api-reference/mail-send/mail-send
    */
-  async sendMail(email) {
+  async sendMail(options) {
+    const email = this.getEmail_(options);
     const response = await this.request('mail/send', 'POST', email);
     return response;
   }

package/src/apis/spreadsheets.js

@@ -67,15 +67,19 @@ let DimensionRange;
 class Spreadsheets extends GoogleApiClient {
   /**
    * Init Spreadsheets API client.
-   * @param {string} spreadsheetId
+   * @param {string} spreadsheetIdOrUrl
    * @param {!Object<string,string>=} env The environment object to hold env
    *     variables.
    */
-  constructor(spreadsheetId, env = process.env) {
+  constructor(spreadsheetIdOrUrl, env = process.env) {
     super(env);
     this.googleApi = 'sheets';
     /** @const {string} */
-    this.spreadsheetId = spreadsheetId;
+    if (spreadsheetIdOrUrl.startsWith('https://')) {
+      this.spreadsheetId = /spreadsheets\/d\/([^/]*)/.exec(spreadsheetIdOrUrl)[1];
+    } else {
+      this.spreadsheetId = spreadsheetIdOrUrl;
+    }
     this.logger = getLogger('API.GS');
   }
 
@@ -109,7 +113,7 @@ class Spreadsheets extends GoogleApiClient {
   }
 
   /**
-   * Returns whether the sheet with speicified name exists.
+   * Returns whether the sheet with specified name exists.
    * @param {string} sheetName
    * @return {boolean}
    */
@@ -122,7 +126,7 @@ class Spreadsheets extends GoogleApiClient {
   }
 
   /**
-   * Creates a sheet with the gvien name.
+   * Creates a sheet with the given name.
    *
    * @param {string} sheetName
    */
@@ -137,7 +141,7 @@ class Spreadsheets extends GoogleApiClient {
   }
 
   /**
-   * Deletes a sheet with the gvien name.
+   * Deletes a sheet with the given name.
    *
    * @param {string} sheetName
    */
@@ -289,6 +293,23 @@ class Spreadsheets extends GoogleApiClient {
     }
     return batchResult;
   }
+
+  /**
+   * Gets values of first row of the specified sheet.
+   * @param {string} sheetName
+   * @return {!Array<string>}
+   */
+  async getHeadline(sheetName) {
+    const request = {
+      spreadsheetId: this.spreadsheetId,
+      range: `'${sheetName}'!1:1`,
+    };
+    const sheets = await this.getApiClient();
+    const response = await sheets.spreadsheets.values.get(request);
+    const data = response.data;
+    this.logger.debug(`Get: `, data);
+    return data.values[0];
+  }
 }
 
 module.exports = {