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

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+### Upcoming Breaking Changes
+
+From v20 onwards this library will use the REST api for report, reportStream, search and searchStream. This will result in minor breaking changes to reporting calls:
+
+- Fields with the enum value `0` will now be `undefined` instead
+- Array-fields (such as `final_urls`) with the value `[]` will now be `undefined` instead
+
+While these changes are inconvenient, the performance of the REST api is significantly better than the gRPC api, particularly for responses with many rows.
+
+To prepare for this change, we recommend you use the install the `19.0.0-rest-beta` version of this library and test your application with it.
+
+## 19.0.1
+
+- Fix issue with type interface for search_settings not showing any valid fields.
+
+## 19.0.0
+
+### Version Upgrade
+
+- Upgraded google-ads-api version to v19. Refer to Google ads release notes [here](https://developers.google.com/google-ads/api/docs/release-notes) for changes.
+
+### Library Changes
+
+- We currently do not support `return_total_results_count` on search_settings for SearchGoogleAdsRequest. Please use `reportCount()` instead. This has been reflected in the `RequestOptions` type:
+
+```ts
+export type RequestOptions = Omit<
+  services.ISearchGoogleAdsRequest,
+  "customer_id" | "query" | "search_settings"
+> & {
+  search_settings?: Omit<
+    services.ISearchSettings,
+    "return_total_results_count"
+  >;
+};
+```
+
+For more information please see the `SearchSettings` reference on the Google document [here](https://developers.google.com/google-ads/api/reference/rpc/v19/SearchSettings).

package/build/src/client.d.ts

@@ -7,7 +7,6 @@ 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,7 +4,6 @@ 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,10 +52,8 @@ 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
@@ -64,8 +62,4 @@ 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,19 +4,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Customer = void 0;
-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 parser_1 = require("./parser");
 const serviceFactory_1 = __importDefault(require("./protos/autogen/serviceFactory"));
 const query_1 = require("./query");
-const version_1 = require("./version");
-const ROWS_PER_STREAMED_CHUNK = 10_000; // From experience, this is what can be expected from the API.
+const utils_1 = require("./utils");
 class Customer extends serviceFactory_1.default {
     constructor(clientOptions, customerOptions, hooks) {
-        super(clientOptions, customerOptions, hooks ?? {});
+        super(clientOptions, customerOptions, hooks !== null && hooks !== void 0 ? hooks : {});
     }
     /**
       @description Single query using a raw GAQL string.
@@ -56,8 +50,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
-        // We do not allow this field in reportOptions, however it is still a valid request option
-        requestOptions.search_settings = { return_total_results_count: true };
+        // @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;
         const useHooks = false; // to avoid cacheing conflicts
         const { totalResultsCount } = await this.querier(gaqlQuery, requestOptions, options, useHooks);
         return totalResultsCount;
@@ -117,123 +111,39 @@ class Customer extends serviceFactory_1.default {
         });
     }
     async search(gaqlQuery, requestOptions) {
-        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;
+        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);
         }
+        return { response, nextPageToken, totalResultsCount };
     }
-    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 };
-        }
+    async paginatedSearch(gaqlQuery, requestOptions, parser) {
         const response = [];
         let nextPageToken = undefined;
         const initialSearch = await this.search(gaqlQuery, requestOptions);
-        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);
+        const totalResultsCount = initialSearch.totalResultsCount;
+        response.push(...parser(initialSearch.response));
         nextPageToken = initialSearch.nextPageToken;
         while (nextPageToken) {
             const nextSearch = await this.search(gaqlQuery, {
                 ...requestOptions,
                 page_token: nextPageToken,
             });
-            response.push(...nextSearch.response);
+            response.push(...parser(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,
@@ -260,7 +170,14 @@ class Customer extends serviceFactory_1.default {
             }
         }
         try {
-            const { response, totalResultsCount } = await this.paginatedSearch(gaqlQuery, requestOptions);
+            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);
             if (this.hooks.onQueryEnd && useHooks) {
                 const queryResolution = { resolved: false };
                 await this.hooks.onQueryEnd({
@@ -312,79 +229,58 @@ 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 {
-            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();
+            while (!streamFinished || accumulator.length) {
+                if (accumulator.length > 0) {
+                    const item = accumulator.shift();
+                    if (item === undefined) {
+                        throw new Error("UNDEFINED_STREAM_ERROR");
+                    }
+                    yield item;
                 }
-                for (const row of results) {
-                    const parsed = this.decamelizeKeysIfNeeded(row);
-                    yield parsed;
+                else {
+                    await nextChunk.newPromise;
                 }
             }
-            return;
         }
-        catch (e) {
-            try {
-                await this.handleStreamError(e);
-            }
-            catch (_e) {
-                if (this.hooks.onStreamError) {
-                    await this.hooks.onStreamError({
-                        ...baseHookArguments,
-                        error: _e,
-                    });
-                }
-                throw _e;
+        catch (searchError) {
+            const googleAdsError = this.getGoogleAdsError(searchError);
+            if (this.hooks.onStreamError) {
+                await this.hooks.onStreamError({
+                    ...baseHookArguments,
+                    error: googleAdsError,
+                });
             }
+            throw googleAdsError;
         }
-    }
-    async handleStreamError(e) {
-        if (!e?.response?.data) {
-            throw e;
+        finally {
+            stream.destroy();
         }
-        // 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
@@ -464,28 +360,5 @@ 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;