google-ads-api 10.0.1 → 11.1.0

package/README.md

@@ -7,7 +7,7 @@
 </p>
 <p align="center">
   <a href="https://developers.google.com/google-ads/api/docs/release-notes">
-    <img src="https://img.shields.io/badge/google%20ads-v10.0.0-009688.svg?style=flat-square">
+    <img src="https://img.shields.io/badge/google%20ads-v11.1.0-009688.svg?style=flat-square">
   </a>
   <a href="https://www.npmjs.com/package/google-ads-api">
     <img src="https://img.shields.io/npm/v/google-ads-api.svg?style=flat-square">
@@ -15,14 +15,11 @@
   <a>
     <img src="https://img.shields.io/npm/dm/google-ads-api.svg?style=flat-square">
     </a>
-  <a>
-    <img src="https://img.shields.io/david/opteo/google-ads-api.svg?style=flat-square">
-  </a>
 </p>
 
 <p align="center">
   <a href="https://opteo.com">
-    <img src="https://app.opteo.com/icons/logo.svg">
+    <img src="https://app.opteo.com/favicon.png" width="90" height="90">
   </a>
 </p>
 
@@ -102,7 +99,7 @@ const customer = client.Customer({
 
 ## List accessible customers
 
-This is a special client method for listing the accessible customers for a given refresh token, and is equivalent to [CustomerService.listAccessibleCustomers](https://developers.google.com/google-ads/api/reference/rpc/v10/CustomerService#listaccessiblecustomers). It returns the resource names of available customer accounts.
+This is a special client method for listing the accessible customers for a given refresh token, and is equivalent to [CustomerService.listAccessibleCustomers](https://developers.google.com/google-ads/api/reference/rpc/v11/CustomerService#listaccessiblecustomers). It returns the resource names of available customer accounts.
 
 ```ts
 const client = new GoogleAdsApi({
@@ -111,7 +108,7 @@ const client = new GoogleAdsApi({
   developer_token: "<DEVELOPER-TOKEN>",
 });
 
-const refreshToken = "<REFRESH-TOKEN">
+const refreshToken = "<REFRESH-TOKEN>";
 
 const customers = await client.listAccessibleCustomers(refreshToken);
 ```
@@ -160,7 +157,7 @@ const campaigns = await customer.query(`
     metrics.cost_micros,
     metrics.clicks,
     metrics.impressions,
-    metrics.all_conversions,
+    metrics.all_conversions
   FROM 
     campaign
   WHERE
@@ -197,7 +194,6 @@ const campaigns = await customer.report({
 Calls searchStream internally but returns the rows one by one in an async iterator.
 
 <!-- prettier-ignore-start -->
-
 ```ts
 import { enums } from "google-ads-api";
 
@@ -222,6 +218,30 @@ for await (const row of stream) {
 ```
 <!-- prettier-ignore-end -->
 
+Or use a GAQL query.
+
+<!-- prettier-ignore-start -->
+```ts
+const stream = customer.queryStream(`
+  SELECT
+    ad_group_criterion.keyword.text,
+    ad_group_criterion.status
+  FROM
+    ad_group_criterion
+  WHERE
+    ad_group_criterion.type = "KEYWORD"
+`);
+
+// Rows are streamed in one by one
+for await (const row of stream) {
+    // Break the loop to stop streaming
+    if (someLogic) {
+        break
+    }
+}
+```
+<!-- prettier-ignore-end -->
+
 ---
 
 ## Retrieve Keywords with a raw stream
@@ -353,6 +373,27 @@ const result = await customer.mutateResources(operations);
 
 ---
 
+## Uploading Click Conversions
+
+```ts
+const clickConversion = {
+  gclid: "<GOOGLE-CLICK-ID>",
+  conversion_action: "customers/1234567890/conversionActions/111222333",
+  conversion_date_time: "2022-01-11 00:00:00",
+  conversion_value: 123,
+  currency_code: "GBP",
+};
+
+const request = new services.UploadClickConversionsRequest({
+  customer_id: customerId,
+  conversions: [clickConversion],
+});
+
+await customer.conversionUploads.uploadClickConversions(request);
+```
+
+---
+
 ## Summary Row
 
 If a summary row is requested in the `report` method, it will be included as the **first** row of the results.
@@ -487,13 +528,24 @@ These hooks have access to the `customerCredentials` argument, containing the `c
 
 These hooks also have access to the `method` argument, containing the mutation method as a string.
 
+### Service hooks:
+
+- `onServiceStart`
+- `onServiceError`
+- `onServiceEnd`
+
+These hooks have access to the `customerCredentials` argument, containing the `customer_id`, `login_customer_id` and `linked_customer_id`.
+
+These hooks also have access to the `method` argument, containing the mutation method as a string.
+
 ### Pre-request hooks:
 
 - `onQueryStart` - `query` and `report`
 - `onStreamStart` - `reportStream` and `reportStreamRaw`
 - `onMutationStart`
+- `onServiceStart`
 
-These hooks are executed **before** a query/stream/mutation.
+These hooks are executed **before** a query/stream/mutation/service.
 
 These hooks have access to the `cancel` method, which can cancel the action before it is done. The query and mutation pre-request hooks allow an optional argument to be passed into the `cancel` method, which will be used as an alternative return value for the query/mutation. A good use case for this method would be to cancel with a cached result.
 
@@ -513,9 +565,10 @@ const onQueryStart: OnQueryStart = async ({ cancel, editOptions }) => {
 
 const customer = client.Customer({
   clientOptions,
-  customerOptions,
-  hooks: { onQueryStart },
-});
+  customerOptions
+},
+  { onQueryStart }
+);
 ```
 
 ### On error hooks:
@@ -523,8 +576,9 @@ const customer = client.Customer({
 - `onQueryError` - `query` and `report`
 - `onStreamError` - `reportStream` (but **not** `reportStreamRaw`)
 - `onMutationError`
+- `onServiceStart`
 
-These hooks are executed when a query/stream/mutation throws an error. If the error is a Google Ads failure then it will be converted to a `GoogleAdsFailure` first. The error can be accessed in these hooks with the `error` argument. Note that the `onStreamError` hook will not work with the `reportStreamRaw` method to avoid blocking the thread.
+These hooks are executed when a query/stream/mutation/service throws an error. If the error is a Google Ads failure then it will be converted to a `GoogleAdsFailure` first. The error can be accessed in these hooks with the `error` argument. Note that the `onStreamError` hook will not work with the `reportStreamRaw` method to avoid blocking the thread.
 
 ```ts
 import { OnQueryError } from "google-ads-api";
@@ -535,17 +589,19 @@ const onQueryError: OnQueryError = async ({ error }) => {
 
 const customer = client.Customer({
   clientOptions,
-  customerOptions,
-  hooks: { onQueryError },
-});
+  customerOptions
+},
+  { onQueryError }
+);
 ```
 
 ### Post-request hooks:
 
 - `onQueryEnd` - `query` and `report`
 - `onMutationEnd`
+- `onServiceEnd`
 
-These hooks are executed **after** a query or mutation. This library does not contain an `onStreamEnd` hook to avoid accumulating the results of streams, and also so that we don't block the thread by waiting for the end event to be emitted.
+These hooks are executed **after** a query, mutation or service. This library does not contain an `onStreamEnd` hook to avoid accumulating the results of streams, and also so that we don't block the thread by waiting for the end event to be emitted.
 
 ```ts
 import { OnQueryEnd } from "google-ads-api";
@@ -557,18 +613,19 @@ const onQueryEnd: OnQueryEnd = async ({ response, resolve }) => {
 
 const customer = client.Customer({
   clientOptions,
-  customerOptions,
-  hooks: { onQueryEnd },
-});
+  customerOptions
+},
+  { onQueryEnd }
+);
 ```
 
 ---
 
 ## Error handling
 
-All errors, apart from GRPC specific cases (such as a connection problem or timeout, [see more here](https://github.com/grpc/grpc/blob/master/doc/statuscodes.md)), are instances of a [GoogleAdsFailure](https://developers.google.com/google-ads/api/reference/rpc/v10/GoogleAdsFailure).
+All errors, apart from GRPC specific cases (such as a connection problem or timeout, [see more here](https://github.com/grpc/grpc/blob/master/doc/statuscodes.md)), are instances of a [GoogleAdsFailure](https://developers.google.com/google-ads/api/reference/rpc/v11/GoogleAdsFailure).
 
-You can find a list of all error types for a specific version in [the official documentation](https://developers.google.com/google-ads/api/reference/rpc/v10/AccessInvitationErrorEnum.AccessInvitationError), as well as more information about [handling errors here](https://developers.google.com/google-ads/api/docs/best-practices/error-types).
+You can find a list of all error types for a specific version in [the official documentation](https://developers.google.com/google-ads/api/reference/rpc/v11/AccessInvitationErrorEnum.AccessInvitationError), as well as more information about [handling errors here](https://developers.google.com/google-ads/api/docs/best-practices/error-types).
 
 ```ts
 import { errors } from "google-ads-api";

package/build/src/client.js

@@ -1,88 +1,39 @@
 "use strict";
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-var __generator = (this && this.__generator) || function (thisArg, body) {
-    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
-    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
-    function verb(n) { return function (v) { return step([n, v]); }; }
-    function step(op) {
-        if (f) throw new TypeError("Generator is already executing.");
-        while (_) try {
-            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
-            if (y = 0, t) op = [op[0] & 2, t.value];
-            switch (op[0]) {
-                case 0: case 1: t = op; break;
-                case 4: _.label++; return { value: op[1], done: false };
-                case 5: _.label++; y = op[1]; op = [0]; continue;
-                case 7: op = _.ops.pop(); _.trys.pop(); continue;
-                default:
-                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
-                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
-                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
-                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
-                    if (t[2]) _.ops.pop();
-                    _.trys.pop(); continue;
-            }
-            op = body.call(thisArg, _);
-        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
-        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
-    }
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Client = void 0;
-var customer_1 = require("./customer");
-var service_1 = require("./service");
-var Client = /** @class */ (function () {
-    function Client(options) {
+const customer_1 = require("./customer");
+const service_1 = require("./service");
+class Client {
+    constructor(options) {
         this.options = options;
     }
-    Client.prototype.Customer = function (customerOptions, hooks) {
-        var cus = new customer_1.Customer(this.options, customerOptions, hooks);
+    Customer(customerOptions, hooks) {
+        const cus = new customer_1.Customer(this.options, customerOptions, hooks);
         return cus;
-    };
-    Client.prototype.listAccessibleCustomers = function (refreshToken) {
-        return __awaiter(this, void 0, void 0, function () {
-            var service, customerService, response, err_1;
-            return __generator(this, function (_a) {
-                switch (_a.label) {
-                    case 0:
-                        service = new service_1.Service(this.options, {
-                            customer_id: "",
-                            refresh_token: refreshToken,
-                        });
-                        return [4 /*yield*/, service.loadService("CustomerServiceClient")];
-                    case 1:
-                        customerService = _a.sent();
-                        _a.label = 2;
-                    case 2:
-                        _a.trys.push([2, 4, , 5]);
-                        return [4 /*yield*/, customerService.listAccessibleCustomers({}, {
-                                // @ts-expect-error Field not included in type definitions
-                                otherArgs: {
-                                    // @ts-expect-error Protected usage is fine here
-                                    headers: service.callHeaders,
-                                },
-                            })];
-                    case 3:
-                        response = (_a.sent())[0];
-                        return [2 /*return*/, response];
-                    case 4:
-                        err_1 = _a.sent();
-                        console.log(err_1);
-                        // @ts-expect-error Protected usage is fine here
-                        throw service.getGoogleAdsError(err_1);
-                    case 5: return [2 /*return*/];
-                }
-            });
+    }
+    async listAccessibleCustomers(refreshToken) {
+        const service = new service_1.Service(this.options, {
+            customer_id: "",
+            refresh_token: refreshToken,
         });
-    };
-    return Client;
-}());
+        // @ts-expect-error Protected usage is fine here
+        const customerService = await service.loadService("CustomerServiceClient");
+        try {
+            // @ts-expect-error Type definition is incorrect, response is an array
+            const [response] = await customerService.listAccessibleCustomers({}, {
+                // @ts-expect-error Field not included in type definitions
+                otherArgs: {
+                    // @ts-expect-error Protected usage is fine here
+                    headers: service.callHeaders,
+                },
+            });
+            return response;
+        }
+        catch (err) {
+            console.log(err);
+            // @ts-expect-error Protected usage is fine here
+            throw service.getGoogleAdsError(err);
+        }
+    }
+}
 exports.Client = Client;

package/build/src/customer.d.ts

@@ -11,6 +11,15 @@ export declare class Customer extends ServiceFactory {
       @hooks onQueryStart, onQueryError, onQueryEnd
     */
     query<T = services.IGoogleAdsRow[]>(gaqlQuery: string, requestOptions?: RequestOptions): Promise<T>;
+    /**
+      @description Stream query using a raw GAQL string. If a generic type is provided, it must be the type of a single row.
+      If a summary row is requested then this will be the last emitted row of the stream.
+      @hooks onStreamStart, onStreamError
+      @example
+      const stream = queryStream<T>(gaqlQuery)
+      for await (const row of stream) { ... }
+    */
+    queryStream<T = services.IGoogleAdsRow>(gaqlQuery: string, requestOptions?: RequestOptions): AsyncGenerator<T>;
     /**
       @description Single query using ReportOptions.
       If a summary row is requested then this will be the first row of the results.
@@ -44,6 +53,7 @@ export declare class Customer extends ServiceFactory {
     private search;
     private paginatedSearch;
     private querier;
+    private streamer;
     /**
      * @description Creates, updates, or removes resources. This method supports atomic transactions
      * with multiple types of resources. For example, you can atomically create a campaign and a