@google-cloud/nodejs-common 1.7.9-alpha → 1.8.1-alpha

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@google-cloud/nodejs-common",
-  "version": "1.7.9-alpha",
+  "version": "1.8.1-alpha",
   "description": "A NodeJs common library for solutions based on Cloud Functions",
   "author": "Google Inc.",
   "license": "Apache-2.0",
@@ -27,11 +27,12 @@
     "@google-cloud/scheduler": "^4.0.0",
     "@google-cloud/secret-manager": "^5.0.0",
     "gaxios": "^6.1.0",
-    "google-ads-api": "^13.0.1",
-    "google-ads-node": "^11.0.0",
+    "google-ads-api": "^14.1.0",
+    "google-ads-node": "^12.0.2",
     "google-auth-library": "^9.0.0",
     "googleapis": "^126.0.1",
     "winston": "^3.10.0",
+    "@grpc/grpc-js": "1.9.5",
     "lodash": "^4.17.21"
   },
   "devDependencies": {

package/src/apis/ads_data_hub.js

@@ -18,8 +18,7 @@
 
 'use strict';
 
-const {request, GaxiosOptions} = require('gaxios');
-const AuthClient = require('./auth_client.js');
+const { AuthRestfulApi } = require('./base/auth_restful_api.js');
 
 const API_SCOPES = Object.freeze([
   'https://www.googleapis.com/auth/adsdatahub',
@@ -31,7 +30,7 @@ const API_ENDPOINT = 'https://adsdatahub.googleapis.com';
  * Ads Data Hub (ADH) API connector class based on ADH REST API.
  * @see: https://developers.google.com/ads-data-hub/reference/rest
  */
-class AdsDataHub {
+class AdsDataHub extends AuthRestfulApi {
   /**
    * Constructor.
    *
@@ -41,20 +40,19 @@ class AdsDataHub {
    *     variables.
    */
   constructor(options, customerId = undefined, env = process.env) {
-    this.authClient = new AuthClient(API_SCOPES, env);
+    super(env);
     /** @const{GaxiosOptions} */ this.options = options || {};
     /** @const{string|undefined=} */ this.customerId = customerId;
   }
 
-  /**
-   * Gets the auth object.
-   * @return {!Promise<{!OAuth2Client|!JWT|!Compute}>}
-   */
-  async getAuth_() {
-    if (this.auth) return this.auth;
-    await this.authClient.prepareCredentials();
-    this.auth = this.authClient.getDefaultAuth();
-    return this.auth;
+  /** @override */
+  getScope() {
+    return API_SCOPES;
+  }
+
+  /** @override */
+  getBaseUrl() {
+    return `${API_ENDPOINT}/${API_VERSION}`;
   }
 
   /**
@@ -74,37 +72,6 @@ class AdsDataHub {
     return `customers/${customerId}/analysisQueries/${queryName}`;
   }
 
-  /**
-   * Returns the base Url of API service.
-   * @return {string} Base Url.
-   * @private
-   */
-  getRequestBaseUrl_() {
-    return `${API_ENDPOINT}/${API_VERSION}/`;
-  }
-
-  /**
-   * Sends a request to server and return the response body.
-   * @param {string} path Request relative path.
-   * @param {string=} method HTTP method, default is 'GET'.
-   * @param {Object|undefined=} data HTTP data to send
-   * @return {!Promise<Object>} Response body.
-   * @private
-   */
-  async sendRequestAndReturnResponse_(path, method = 'GET', data = undefined) {
-    const auth = await this.getAuth_();
-    const headers = await auth.getRequestHeaders();
-    const url = this.getRequestBaseUrl_() + path;
-    const response = await request(/** @type {GaxiosOptions} */
-        Object.assign({}, this.options, {
-          url,
-          method,
-          headers,
-          data,
-        }));
-    return response.data;
-  }
-
   /**
    * Retrieves the requested analysis query. If query doesn't exist, it will
    * throw an error.
@@ -116,24 +83,24 @@ class AdsDataHub {
    */
   async getQuery(queryName, customerId = this.customerId) {
     const uniqueQueryName = this.getUniqueQueryName_(queryName, customerId);
-    return this.sendRequestAndReturnResponse_(uniqueQueryName);
+    const response = await this.request(uniqueQueryName);
+    return response.data;
   }
 
   /**
    * Lists the analysis queries owned by the specified customer.
    * @see https://developers.google.com/ads-data-hub/reference/rest/v1/customers.analysisQueries/list
-   * @param {Object=} parameters The query parameter object.
    * @param {string=} customerId
    * @return {!Promise<{
-   *   queries:Array<Object>,
-   *   nextPageToken:string,
-   * }>}
-   */
+  *   queries:Array<Object>,
+  *   nextPageToken:string,
+  * }>}
+  */
   async listQuery(parameters = {}, customerId = this.customerId) {
-    const querystring = this.getQueryString_(parameters);
-    const path = `customers/${customerId}/analysisQueries`
-      + (querystring ? `?${querystring}` : '');
-    return this.sendRequestAndReturnResponse_(path);
+    const querystring = this.getQueryString(parameters);
+    const path = `customers/${customerId}/analysisQueries${querystring}`;
+    const response = await this.request(path);
+    return response.data;
   }
 
   /**
@@ -157,22 +124,8 @@ class AdsDataHub {
   async startTransientQuery(queryText, spec, destTable, customerId = this.customerId) {
     const path = `customers/${customerId}/analysisQueries:startTransient`;
     const data = { query: { queryText }, spec, destTable };
-    return this.sendRequestAndReturnResponse_(path, 'POST', data);
-  }
-
-  /**
-   * Creates a query and returns the unique query name in the form of
-   * 'customers/[customerId]/analysisQueries/[resource_id]'.
-   * @see https://developers.google.com/ads-data-hub/reference/rest/v1/customers.analysisQueries/create
-   * @param {string} title The title of the query.
-   * @param {string} queryText The content of the query
-   * @return {!Promise<string>} Promised unique name of created query.
-   */
-  async createQuery(title, queryText) {
-    const path = `customers/${this.customerId}/analysisQueries`;
-    const data = {title, queryText,};
-    const query = await this.sendRequestAndReturnResponse_(path, 'POST', data);
-    return query.name;
+    const response = await this.request(path, 'POST', data);
+    return response.data;
   }
 
   /**
@@ -198,7 +151,23 @@ class AdsDataHub {
   async startQuery(uniqueQueryName, spec, destTable, customerId = undefined) {
     const path = `${uniqueQueryName}:start`;
     const data = {spec, destTable, customerId};
-    return this.sendRequestAndReturnResponse_(path, 'POST', data);
+    const response = await this.request(path, 'POST', data);
+    return response.data;
+  }
+
+  /**
+   * Creates a query and returns the unique query name in the form of
+   * 'customers/[customerId]/analysisQueries/[resource_id]'.
+   * @see https://developers.google.com/ads-data-hub/reference/rest/v1/customers.analysisQueries/create
+   * @param {string} title The title of the query.
+   * @param {string} queryText The content of the query
+   * @return {!Promise<string>} Promised unique name of created query.
+   */
+  async createQuery(title, queryText) {
+    const path = `customers/${this.customerId}/analysisQueries`;
+    const data = { title, queryText, };
+    const response = await this.request(path, 'POST', data);
+    return response.data.name;
   }
 
   /**
@@ -210,7 +179,8 @@ class AdsDataHub {
    */
   async deleteQuery(queryName, customerId = this.customerId) {
     const uniqueQueryName = this.getUniqueQueryName_(queryName, customerId);
-    return this.sendRequestAndReturnResponse_(uniqueQueryName, 'DELETE');
+    const response = await this.request(uniqueQueryName, 'DELETE');
+    return response.data;
   }
 
   /**
@@ -221,21 +191,14 @@ class AdsDataHub {
    *     @see https://developers.google.com/ads-data-hub/reference/rest/v1/operations#Operation
    */
   async getQueryStatus(operationName) {
-    return this.sendRequestAndReturnResponse_(operationName);
-  }
-
-  /**
-   * Gets the query string of a parameter object.
-   * @param {Object} parameters The object of key-value pairs which will be
-   *   converted into query string format.
-   * @return string
-   * @private
-   */
-  getQueryString_(parameters = {}) {
-    return Object.keys(parameters)
-      .map((key) => key + '=' + encodeURIComponent(parameters[key]))
-      .join('&');
+    const response = await this.request(operationName);
+    return response.data;
   }
 }
 
-exports.AdsDataHub = AdsDataHub;
+module.exports = {
+  AdsDataHub,
+  API_SCOPES,
+  API_VERSION,
+  API_ENDPOINT,
+};

package/src/apis/base/auth_restful_api.js

@@ -0,0 +1,59 @@
+// Copyright 2023 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 A base class for RESTful API with authorization client.
+ */
+
+const { RestfuleApiBase } = require('./restful_api_base');
+const AuthClient = require('../auth_client.js');
+
+/**
+ * A RESTful API class with authorization client.
+ */
+class AuthRestfulApi extends RestfuleApiBase {
+
+  /**
+   * Returns the Api scope for authorization.
+   * @return {!Array<string>}
+   * @abstract
+   */
+  getScope() { }
+
+  /**
+   * Gets the auth object.
+   * @return {!Promise<{!OAuth2Client|!JWT|!Compute}>}
+   */
+  async getAuth() {
+    if (this.auth) return this.auth;
+    this.authClient = new AuthClient(this.getScope(), this.env);
+    await this.authClient.prepareCredentials();
+    this.auth = this.authClient.getDefaultAuth();
+    return this.auth;
+  }
+
+  /**
+   * Returns HTTP headers. By default, it contains access token.
+   * @return {object} HTTP headers.
+   * @override
+   */
+  async getDefaultHeaders() {
+    const auth = await this.getAuth();
+    const headers = await auth.getRequestHeaders();
+    return Object.assign({}, super.getDefaultHeaders(), headers);
+  }
+
+}
+
+module.exports = { AuthRestfulApi };

package/src/apis/base/restful_api_base.js

@@ -0,0 +1,143 @@
+// Copyright 2023 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 A base class for RESTful API based on gaxios.
+ */
+
+const {
+  request: gaxiosRequest,
+  GaxiosResponse,
+  GaxiosOptions,
+} = require('gaxios');
+
+/**
+ * A type for an Api response which is independent to the 'request' library.
+ * @typedef {{
+ *   data:string,
+ *   code:number,
+ * }}
+ */
+let Response;
+
+/**
+ * Base class for RESTful API based on gaxios.
+ * @see https://github.com/googleapis/gaxios
+ */
+class RestfuleApiBase {
+
+  constructor(env = process.env) {
+    this.env = env;
+  }
+
+  /**
+   * Returns the base Url of the Api request.
+   * @return {string}
+   * @abstract
+   */
+  getBaseUrl() { }
+
+  /**
+   * Returns default HTTP headers.
+   * @return {object} HTTP headers.
+   */
+  async getDefaultHeaders() {
+    return {};
+  }
+
+  /**
+   * Gets an object as request options.
+   * @return {Object=}
+   */
+  getRequesterOptions() {
+    return {
+      responseType: 'json',
+    };
+  }
+
+  /**
+   * Gets a response object. Different `request` libraries can be used in
+   * different situations. This function is used to isolate the different
+   * responses from different `request` libraries.
+   * @param {GaxiosResponse} response
+   * @return {!Response}
+   */
+  getResponseProcessor(response) {
+    return {
+      data: response.data,
+      code: response.status,
+    };
+  }
+
+  /**
+   * Sends our a request and returns the response.
+   * @param {string|undefined} uri
+   * @param {string=} method
+   * @param {object|undefined} data
+   * @param {object|undefined} headers
+   * @return {!Response}
+   */
+  async request(uri, method = 'GET', data, headers) {
+    /** @type {GaxiosOptions} */
+    const options = Object.assign(
+      this.getRequesterOptions(),
+      {
+        url: this.getRequestUrl(uri),
+        method,
+        headers: headers || await this.getDefaultHeaders(),
+        data,
+      }
+    );
+    return this.getResponseProcessor(await gaxiosRequest(options));
+  }
+
+  /**
+   * Constructs the fully-qualified URL to the API using the given @param
+   * {requestUri}.
+   * If it is an absolute url, return it directly;
+   * Otherwise append it after base url which is defined in detail API classes.
+   *
+   * @param {string} requestUri The URI of the specific resource to request.
+   * @return {string} representing the fully-qualified API URL.
+   */
+  getRequestUrl(requestUri) {
+    const baseUrl = this.getBaseUrl();
+    if (requestUri) {
+      if (requestUri.toLocaleLowerCase().startsWith('http')) return requestUri;
+      return `${baseUrl}/${requestUri}`;
+    }
+    return baseUrl;
+  }
+
+  /**
+   * Gets the URL encoded querystring from a parameter object.
+   * If a parameter is an array, the parameter will be in the querystring for
+   * multiple times.
+   * @param {object} params.
+   * @return {string} A querystring which starts with '?'.
+   */
+  getQueryString(params) {
+    if (!params || Object.keys(params).length === 0) return '';
+    return '?' + Object.keys(params).map((key) => {
+      if (!Array.isArray(params[key]))
+        return `${key}=${encodeURIComponent(params[key])}`;
+      return params[key].map((v) => `${key}=${encodeURIComponent(v)}`).join('&');
+    }).join('&');
+  }
+}
+
+module.exports = {
+  Response,
+  RestfuleApiBase,
+};

package/src/apis/index.js

@@ -106,7 +106,12 @@ exports.googleads = require('./google_ads.js');
 
 /**
  * APIs integration class for Ads Data Hub.
- * @const {{AdsDataHub:!AdsDataHub}}
+ * @const {{
+ *   AdsDataHub:!AdsDataHub,
+ *   API_SCOPES: !Array<string>,
+ *   API_VERSION: string,
+ *   API_ENDPOINT: string,
+ * }}
  */
 exports.adsdatahub = require('./ads_data_hub.js');
 
@@ -128,3 +133,13 @@ exports.measurementprotocolga4 = require('./measurement_protocol_ga4.js');
  * }}
  */
 exports.youtube = require('./youtube.js');
+
+/**
+ * APIs integration class for SendGrid.
+ * @const {{
+*   SendGrid:!SendGrid,
+*   API_VERSION: string,
+*   API_ENDPOINT: string,
+* }}
+*/
+exports.sendgrid = require('./sendgrid.js');

package/src/apis/sendgrid.js

@@ -0,0 +1,65 @@
+// Copyright 2023 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 SendGrip API class.
+ */
+
+'use strict';
+
+const { RestfuleApiBase } = require('./base/restful_api_base.js');
+const { getLogger } = require('../components/utils.js');
+
+const API_VERSION = 'v3';
+const API_ENDPOINT = 'https://api.sendgrid.com';
+
+/**
+ * SendGrid API access class.
+ * @see https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api/authentication
+ */
+class SendGrid extends RestfuleApiBase {
+
+  constructor(apiKey, env = process.env) {
+    super(env);
+    this.apiKey = apiKey;
+    this.logger = getLogger('SendGrid');
+  }
+
+  /** @override */
+  getBaseUrl() {
+    return `${API_ENDPOINT}/${API_VERSION}`;
+  }
+
+  /** @override */
+  async getDefaultHeaders() {
+    return Object.assign({}, super.getDefaultHeaders(), {
+      Authorization: `Bearer ${this.apiKey}`,
+    });
+  }
+
+  /**
+   * Sends an email.
+   * @see https://docs.sendgrid.com/api-reference/mail-send/mail-send
+   */
+  async sendMail(email) {
+    const response = await this.request('mail/send', 'POST', email);
+    return response;
+  }
+}
+
+module.exports = {
+  SendGrid,
+  API_VERSION,
+  API_ENDPOINT,
+};