google-ads-api 17.1.0 → 19.0.0-rest-beta

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-v16.1.0-009688.svg?style=flat-square">
+    <img src="https://img.shields.io/badge/google%20ads-v17.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">
@@ -350,7 +350,7 @@ const operations: MutateOperation<
       advertising_channel_type: enums.AdvertisingChannelType.SEARCH,
       status: enums.CampaignStatus.PAUSED,
       manual_cpc: {
-        enhanced_cpc_enabled: true,
+        enhanced_cpc_enabled: false,
       },
       // Use the temporary resource id which will be created in the previous operation
       campaign_budget: budgetResourceName,
@@ -385,7 +385,7 @@ const keyword = "24 hour locksmith harlem";
 
 const operations: MutateOperation<
   resources.IAdGroupCriterion & {
-    exempt_policy_violation_keys?: google.ads.googleads.v16.common.IPolicyViolationKey[];
+    exempt_policy_violation_keys?: google.ads.googleads.v17.common.IPolicyViolationKey[];
   }
 >[] = [
   {
@@ -443,7 +443,9 @@ If a summary row is requested in the `report` method, it will be included as the
 const [summaryRow, ...response] = await customer.report({
   entity: "campaign",
   metrics: ["metrics.clicks", "metrics.all_conversions"],
-  summary_row_setting: enums.SummaryRowSetting.SUMMARY_ROW_WITH_RESULTS,
+  search_settings: {
+    return_summary_row: enums.SummaryRowSetting.SUMMARY_ROW_WITH_RESULTS,
+  },
 });
 ```
 
@@ -453,7 +455,9 @@ If a summery row is requested in the `reportStream` method, it will be included
 const stream = customer.reportStream({
   entity: "campaign",
   metrics: ["metrics.clicks", "metrics.all_conversions"],
-  summary_row_setting: enums.SummaryRowSetting.SUMMARY_ROW_WITH_RESULTS,
+  search_settings: {
+    return_summary_row: enums.SummaryRowSetting.SUMMARY_ROW_WITH_RESULTS,
+  },
 });
 
 const accumulator = [];
@@ -685,7 +689,7 @@ try {
     // Get the first one and explicitly check for a certain error type
     const [firstError] = err.errors;
     if (
-      firstError.error_code ===
+      firstError.error_code.query_error ===
       errors.QueryErrorEnum.QueryError.UNRECOGNIZED_FIELD
     ) {
       console.log(
@@ -701,15 +705,11 @@ try {
 1. Update google-ads-node & publish to NPM. Check that package for instructions.
 2. Update google-ads-node & google-gax in package.json. google-gax must be the same version as google-ads-node,
    Otherwise you are likely to get a `TypeError: Channel credentials must be a ChannelCredentials object` error.
-3. Update the version in this file
-4. Update the versions in src/protos/index.ts
-5. Run `yarn compile` to update the generated files.
-   The `tsc` command might fail -- if so, temporarily add @ts-nocheck
-   to the top of problematic files so that the compile script can continue.
-   After the compile script has run, those @ts-nocheck lines should no longer be required.
-   The compile step depends on some environment variables being set (see scripts/fields.ts), so make sure to set those.
+3. Update the version in `version.ts`.
+4. Update the versions in `src/protos/index.ts`.
+5. Run `yarn compile` to update the generated files. The `tsc` command might fail -- if so, temporarily add @ts-nocheck to the top of problematic files so that the compile script can continue. After the compile script has run, those @ts-nocheck lines should no longer be required. The compile step depends on some environment variables being set (see scripts/fields.ts), so make sure to set those.
 6. Prettify the generated files so the the diffs are easier to read.
 7. Check that the diffs are expected and that the generated files are correct. New Gads versions will often add new services, fields, and enums.
-8. Test with `yarn test`
+8. Test with `yarn test`.
 9. Test by linking to a real project and making some real requests.
 10. Once confident, bump the major version & publish to NPM.

package/build/src/client.d.ts

@@ -7,6 +7,7 @@ export interface ClientOptions {
     client_secret: string;
     developer_token: string;
     disable_parsing?: boolean;
+    max_reporting_rows?: number;
 }
 export declare class Client {
     private readonly options;

package/build/src/client.js

@@ -4,6 +4,7 @@ exports.Client = void 0;
 const customer_1 = require("./customer");
 const service_1 = require("./service");
 class Client {
+    options;
     constructor(options) {
         this.options = options;
     }

package/build/src/customer.d.ts

@@ -52,8 +52,10 @@ export declare class Customer extends ServiceFactory {
     reportStreamRaw(reportOptions: Readonly<ReportOptions>): Promise<CancellableStream | void>;
     private search;
     private paginatedSearch;
+    private useStreamToImitateRegularSearch;
     private querier;
     private streamer;
+    private handleStreamError;
     /**
      * @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
@@ -62,4 +64,8 @@ export declare class Customer extends ServiceFactory {
      */
     mutateResources<T>(mutations: MutateOperation<T>[], mutateOptions?: MutateOptions): Promise<services.MutateGoogleAdsResponse>;
     private get googleAdsFields();
+    private prepareGoogleAdsServicePostRequestArgs;
+    private decamelizeKeysIfNeeded;
+    private gaqlQueryStringIncludesLimit;
+    private generateTooManyRowsError;
 }

package/build/src/customer.js

@@ -4,13 +4,19 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Customer = void 0;
-const parser_1 = require("./parser");
+const axios_1 = __importDefault(require("axios"));
+const stream_chain_1 = require("stream-chain");
+const stream_json_1 = require("stream-json");
+const StreamArray_1 = require("stream-json/streamers/StreamArray");
+const parserRest_1 = require("./parserRest");
+const protos_1 = require("./protos");
 const serviceFactory_1 = __importDefault(require("./protos/autogen/serviceFactory"));
 const query_1 = require("./query");
-const utils_1 = require("./utils");
+const version_1 = require("./version");
+const ROWS_PER_STREAMED_CHUNK = 10_000; // From experience, this is what can be expected from the API.
 class Customer extends serviceFactory_1.default {
     constructor(clientOptions, customerOptions, hooks) {
-        super(clientOptions, customerOptions, hooks !== null && hooks !== void 0 ? hooks : {});
+        super(clientOptions, customerOptions, hooks ?? {});
     }
     /**
       @description Single query using a raw GAQL string.
@@ -50,8 +56,8 @@ class Customer extends serviceFactory_1.default {
     */
     async reportCount(options) {
         const { gaqlQuery, requestOptions } = (0, query_1.buildQuery)({ ...options, limit: 1 }); // must get at least one row
-        // @ts-expect-error we do not allow this field in reportOptions, however it is still a valid request option
-        requestOptions.return_total_results_count = true;
+        // We do not allow this field in reportOptions, however it is still a valid request option
+        requestOptions.search_settings = { return_total_results_count: true };
         const useHooks = false; // to avoid cacheing conflicts
         const { totalResultsCount } = await this.querier(gaqlQuery, requestOptions, options, useHooks);
         return totalResultsCount;
@@ -111,39 +117,123 @@ class Customer extends serviceFactory_1.default {
         });
     }
     async search(gaqlQuery, requestOptions) {
-        const { service, request } = this.buildSearchRequestAndService(gaqlQuery, requestOptions);
-        const searchResponse = await service.search(request, {
-            otherArgs: { headers: this.callHeaders },
-            autoPaginate: false, // autoPaginate doesn't work
-        });
-        const response = searchResponse[0];
-        const summaryRow = searchResponse[2].summary_row;
-        const nextPageToken = searchResponse[2].next_page_token;
-        const totalResultsCount = searchResponse[2].total_results_count
-            ? +searchResponse[2].total_results_count
-            : undefined;
-        if (summaryRow) {
-            response.unshift(summaryRow);
+        const accessToken = await this.getAccessToken();
+        try {
+            const rawResponse = await (0, axios_1.default)(this.prepareGoogleAdsServicePostRequestArgs("search", accessToken, {
+                data: {
+                    query: gaqlQuery,
+                    ...requestOptions,
+                },
+            }));
+            const searchResponse = rawResponse.data;
+            const results = searchResponse.results ?? [];
+            const response = results.map((row) => this.decamelizeKeysIfNeeded(row));
+            const summaryRow = this.decamelizeKeysIfNeeded(searchResponse.summaryRow);
+            const nextPageToken = searchResponse.nextPageToken;
+            const totalResultsCount = searchResponse.totalResultsCount
+                ? +searchResponse.totalResultsCount
+                : undefined;
+            return { response, nextPageToken, totalResultsCount, summaryRow };
+        }
+        catch (e) {
+            if (e.response?.data.error.details[0]) {
+                throw new protos_1.errors.GoogleAdsFailure(this.decamelizeKeysIfNeeded(e.response.data.error.details[0]));
+            }
+            throw e;
         }
-        return { response, nextPageToken, totalResultsCount };
     }
-    async paginatedSearch(gaqlQuery, requestOptions, parser) {
+    async paginatedSearch(gaqlQuery, requestOptions) {
+        /*
+          When possible, use the searchStream method to avoid the overhead of pagination.
+        */
+        if (requestOptions.page_size === undefined &&
+            requestOptions.search_settings?.return_total_results_count === undefined) {
+            // If no pagination or summary options are set, we can use the non-paginated search method.
+            const { response } = await this.useStreamToImitateRegularSearch(gaqlQuery, requestOptions);
+            return { response };
+        }
         const response = [];
         let nextPageToken = undefined;
         const initialSearch = await this.search(gaqlQuery, requestOptions);
-        const totalResultsCount = initialSearch.totalResultsCount;
-        response.push(...parser(initialSearch.response));
+        let totalResultsCount = initialSearch.totalResultsCount;
+        // Sometimes (when no results?) the totalResultsCount field is not included in the response.
+        // In this case, we set it to 0.
+        if (requestOptions.search_settings?.return_total_results_count &&
+            initialSearch.totalResultsCount === undefined) {
+            totalResultsCount = 0;
+        }
+        let summaryRow = initialSearch.summaryRow;
+        response.push(...initialSearch.response);
         nextPageToken = initialSearch.nextPageToken;
         while (nextPageToken) {
             const nextSearch = await this.search(gaqlQuery, {
                 ...requestOptions,
                 page_token: nextPageToken,
             });
-            response.push(...parser(nextSearch.response));
+            response.push(...nextSearch.response);
             nextPageToken = nextSearch.nextPageToken;
+            if (nextSearch.summaryRow) {
+                summaryRow = nextSearch.summaryRow;
+            }
+        }
+        if (summaryRow) {
+            response.unshift(summaryRow);
         }
         return { response, totalResultsCount };
     }
+    // Google's searchStream method is faster than search, but it does not support all features.
+    // When report() is called, we use searchStream if possible, otherwise we use paginatedSearch.
+    // Note that just like `paginatedSearch`, this method accumulates results in memory. Use
+    // `reportStream` for a more memory-efficient alternative (at the cost of more CPU usage).
+    async useStreamToImitateRegularSearch(gaqlQuery, requestOptions) {
+        const accessToken = await this.getAccessToken();
+        try {
+            const args = this.prepareGoogleAdsServicePostRequestArgs("searchStream", accessToken, {
+                responseType: "stream",
+                data: {
+                    query: gaqlQuery,
+                    ...requestOptions,
+                },
+            });
+            const response = await (0, axios_1.default)(args);
+            const stream = response.data;
+            const buffers = [];
+            let rowCount = -ROWS_PER_STREAMED_CHUNK;
+            for await (const data of stream) {
+                if (this.clientOptions.max_reporting_rows &&
+                    !this.gaqlQueryStringIncludesLimit(gaqlQuery)) {
+                    // This is a quick-and-dirty way to count rows, but it's good enough for our purposes.
+                    // We want to avoid using a proper JSON streamer here for performance reasons.
+                    if (data.toString("utf-8").includes(`results":`)) {
+                        rowCount += ROWS_PER_STREAMED_CHUNK;
+                    }
+                    if (rowCount > this.clientOptions.max_reporting_rows) {
+                        throw this.generateTooManyRowsError();
+                    }
+                }
+                buffers.push(data);
+            }
+            const asString = Buffer.concat(buffers).toString("utf-8");
+            const accumulator = [];
+            let foundSummaryRow;
+            for (const { results, summaryRow } of JSON.parse(asString)) {
+                if (summaryRow) {
+                    foundSummaryRow = this.decamelizeKeysIfNeeded(summaryRow);
+                }
+                accumulator.push(...(results ?? []).map((row) => {
+                    return this.decamelizeKeysIfNeeded(row);
+                }));
+                if (foundSummaryRow) {
+                    accumulator.unshift(foundSummaryRow);
+                }
+            }
+            return { response: accumulator };
+        }
+        catch (e) {
+            await this.handleStreamError(e);
+            throw e; // The line above should always throw.
+        }
+    }
     async querier(gaqlQuery, requestOptions = {}, reportOptions, useHooks = true) {
         const baseHookArguments = {
             credentials: this.credentials,
@@ -170,14 +260,7 @@ class Customer extends serviceFactory_1.default {
             }
         }
         try {
-            const parsingWapper = (rows) => {
-                return this.clientOptions.disable_parsing
-                    ? rows
-                    : reportOptions
-                        ? (0, parser_1.parse)({ results: rows, reportOptions })
-                        : (0, parser_1.parse)({ results: rows, gaqlString: gaqlQuery });
-            };
-            const { response, totalResultsCount } = await this.paginatedSearch(gaqlQuery, requestOptions, parsingWapper);
+            const { response, totalResultsCount } = await this.paginatedSearch(gaqlQuery, requestOptions);
             if (this.hooks.onQueryEnd && useHooks) {
                 const queryResolution = { resolved: false };
                 await this.hooks.onQueryEnd({
@@ -229,58 +312,79 @@ class Customer extends serviceFactory_1.default {
                 return;
             }
         }
-        const { service, request } = this.buildSearchStreamRequestAndService(gaqlQuery, requestOptions);
-        const stream = service.searchStream(request, {
-            otherArgs: { headers: this.callHeaders },
-        });
-        let streamFinished = false;
-        const accumulator = [];
-        let nextChunk = (0, utils_1.createNextChunkArrivedPromise)();
-        stream.on("data", (chunk) => {
-            const results = chunk.summary_row ? [chunk.summary_row] : chunk.results;
-            const parsedResponse = this.clientOptions.disable_parsing
-                ? results
-                : reportOptions
-                    ? (0, parser_1.parse)({ results, reportOptions })
-                    : (0, parser_1.parse)({ results, gaqlString: gaqlQuery });
-            accumulator.push(...parsedResponse);
-            nextChunk.resolve();
-            nextChunk = (0, utils_1.createNextChunkArrivedPromise)();
-        });
-        stream.on("error", (searchError) => {
-            nextChunk.reject(searchError);
-        });
-        stream.on("end", () => {
-            streamFinished = true;
-            nextChunk.resolve();
-        });
         try {
-            while (!streamFinished || accumulator.length) {
-                if (accumulator.length > 0) {
-                    const item = accumulator.shift();
-                    if (item === undefined) {
-                        throw new Error("UNDEFINED_STREAM_ERROR");
-                    }
-                    yield item;
+            const accessToken = await this.getAccessToken();
+            const args = this.prepareGoogleAdsServicePostRequestArgs("searchStream", accessToken, {
+                responseType: "stream",
+                data: {
+                    query: gaqlQuery,
+                    ...requestOptions,
+                },
+            });
+            const response = await (0, axios_1.default)(args);
+            const stream = response.data;
+            // The options below help to make the stream less CPU intensive.
+            const parser = new stream_json_1.Parser({
+                streamValues: false,
+                streamKeys: false,
+                packValues: true,
+                packKeys: true,
+            });
+            const pipeline = (0, stream_chain_1.chain)([stream, parser, (0, StreamArray_1.streamArray)()]);
+            let count = 0;
+            for await (const data of pipeline) {
+                const results = data.value.results ?? [data.value.summaryRow];
+                count += results.length;
+                if (this.clientOptions.max_reporting_rows &&
+                    count > this.clientOptions.max_reporting_rows &&
+                    !this.gaqlQueryStringIncludesLimit(gaqlQuery)) {
+                    throw this.generateTooManyRowsError();
                 }
-                else {
-                    await nextChunk.newPromise;
+                for (const row of results) {
+                    const parsed = this.decamelizeKeysIfNeeded(row);
+                    yield parsed;
                 }
             }
+            return;
         }
-        catch (searchError) {
-            const googleAdsError = this.getGoogleAdsError(searchError);
-            if (this.hooks.onStreamError) {
-                await this.hooks.onStreamError({
-                    ...baseHookArguments,
-                    error: googleAdsError,
-                });
+        catch (e) {
+            try {
+                await this.handleStreamError(e);
+            }
+            catch (_e) {
+                if (this.hooks.onStreamError) {
+                    await this.hooks.onStreamError({
+                        ...baseHookArguments,
+                        error: _e,
+                    });
+                }
+                throw _e;
             }
-            throw googleAdsError;
         }
-        finally {
-            stream.destroy();
+    }
+    async handleStreamError(e) {
+        if (!e?.response?.data) {
+            throw e;
         }
+        // The error is a stream, so some effort is required to parse it.
+        const stream = e.response.data;
+        const pipeline = (0, stream_chain_1.chain)([stream, (0, stream_json_1.parser)(), (0, StreamArray_1.streamArray)()]);
+        const defaultErrorMessage = "Unknown GoogleAdsFailure";
+        let googleAdsFailure = new Error(defaultErrorMessage);
+        // Only throw the first error.
+        pipeline.once("data", (data) => {
+            if (data?.value?.error?.details?.[0]) {
+                googleAdsFailure = new protos_1.errors.GoogleAdsFailure(this.decamelizeKeysIfNeeded(data.value.error.details[0]));
+            }
+            else {
+                googleAdsFailure = new Error(data?.value?.error?.message ?? defaultErrorMessage, { cause: data?.value?.error ?? data?.value });
+            }
+        });
+        // Must always reject.
+        await new Promise((_, reject) => {
+            pipeline.on("end", () => reject(googleAdsFailure));
+            pipeline.on("error", (err) => reject(err));
+        });
     }
     /**
      * @description Creates, updates, or removes resources. This method supports atomic transactions
@@ -360,5 +464,28 @@ class Customer extends serviceFactory_1.default {
             },
         };
     }
+    prepareGoogleAdsServicePostRequestArgs(functionName, accessToken, extra) {
+        return {
+            method: "POST",
+            url: `https://googleads.googleapis.com/${version_1.googleAdsVersion}/customers/${this.customerOptions.customer_id}/googleAds:${functionName}`,
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+                ...this.callHeaders,
+            },
+            ...extra,
+        };
+    }
+    decamelizeKeysIfNeeded(input) {
+        if (this.clientOptions.disable_parsing) {
+            return input;
+        }
+        return (0, parserRest_1.decamelizeKeys)(input);
+    }
+    gaqlQueryStringIncludesLimit(gaqlQuery) {
+        return gaqlQuery.toLowerCase().includes("limit ");
+    }
+    generateTooManyRowsError() {
+        return new Error(`Exceeded the maximum number of rows set by "max_reporting_rows" (${this.clientOptions.max_reporting_rows}).`);
+    }
 }
 exports.Customer = Customer;

package/build/src/parserRest.d.ts

@@ -0,0 +1,4 @@
+/**
+ * JSON Rest parsing
+ */
+export declare const decamelizeKeys: (input: any) => any;

package/build/src/parserRest.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * JSON Rest parsing
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decamelizeKeys = void 0;
+const map_obj_1 = __importDefault(require("map-obj"));
+const circ_json_1 = require("circ-json");
+const utils_1 = require("./utils");
+const fields_1 = require("./protos/autogen/fields");
+const enums_1 = require("./protos/autogen/enums");
+const fieldDataTypes = (0, circ_json_1.parse)(fields_1.fieldDataTypes);
+const decamelizeCache = new Map();
+const fieldTypeCache = new Map();
+const isObject = (value) => typeof value === "object" && value !== null;
+const decamelizeKeys = (input) => {
+    if (!isObject(input)) {
+        return input;
+    }
+    const makeMapper = (parentPath) => (key, value) => {
+        key = cachedDecamelize(key);
+        if (isObject(value)) {
+            const path = parentPath === undefined ? key : `${parentPath}.${key}`;
+            // @ts-ignore
+            value = (0, map_obj_1.default)(value, makeMapper(path));
+        }
+        else {
+            value = cachedValueParser(key, parentPath, value);
+        }
+        return [key, value];
+    };
+    // @ts-ignore
+    return (0, map_obj_1.default)(input, makeMapper());
+};
+exports.decamelizeKeys = decamelizeKeys;
+const cachedDecamelize = (key) => {
+    const cachedResult = decamelizeCache.get(key);
+    if (cachedResult) {
+        return cachedResult;
+    }
+    const newKey = (0, utils_1.toSnakeCase)(key);
+    decamelizeCache.set(key, newKey);
+    return newKey;
+};
+const cachedValueParser = (key, parentPath, value) => {
+    let newValue = value;
+    const fullPath = parentPath ? `${parentPath}.${key}` : key;
+    const megaDataType = getTypeFromPath(fullPath);
+    if (megaDataType === undefined && !fullPath.startsWith("@")) {
+        console.warn(`No data type found for ${fullPath}`);
+    }
+    else if (typeof megaDataType === "object") {
+        newValue = megaDataType[value];
+    }
+    else if (megaDataType === "INT64") {
+        newValue = Number(value);
+    }
+    else if (megaDataType === "ENUM") {
+        // Some enums aren't embedded in megaDataType, so we need this fallback.
+        // @ts-expect-error typescript doesn't like accessing items in a namespace with a string
+        newValue = enums_1.enums[fields_1.fields.enumFields[fullPath]][value]; // e.g. enums['CampaignStatus'][ENABLED] = "2"
+    }
+    return newValue;
+};
+const getTypeFromPath = (path) => {
+    const cachedResult = fieldTypeCache.get(path);
+    if (cachedResult) {
+        return cachedResult;
+    }
+    const t = get(fieldDataTypes, path);
+    fieldTypeCache.set(path, t);
+    return t;
+};
+// Copied from youmightnotneed.com
+const get = (obj, path) => {
+    if (!path)
+        return undefined;
+    // Check if path is string or array. Regex : ensure that we do not have '.' and brackets.
+    // Regex explained: https://regexr.com/58j0k
+    const pathArray = path.match(/([^[.\]])+/g);
+    if (!pathArray)
+        return undefined;
+    // Find value
+    return pathArray.reduce((prevObj, key) => prevObj && prevObj[key], obj);
+};