google-ads-api 24.1.0 → 25.1.0-beta.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-v23-009688.svg?style=flat-square">
+    <img src="https://img.shields.io/badge/google%20ads-v25.1-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">
@@ -36,6 +36,8 @@
 npm install google-ads-api
 ```
 
+Requires Node.js 22 or newer. Both `import { GoogleAdsApi } from "google-ads-api"` (ES modules) and `require("google-ads-api")` (CommonJS) are supported. `google-ads-api/enums` and `google-ads-api/fields` expose the generated enums and field types without loading the gRPC service clients.
+
 # Usage
 
 - Setup
@@ -70,6 +72,12 @@ const client = new GoogleAdsApi({
 });
 ```
 
+Optional client settings:
+
+- `grpc_channel_options`: [gRPC channel options](https://github.com/grpc/grpc-node/tree/master/packages/grpc-js#supported-channel-options) applied to every service client this instance creates, for example `{ "grpc.keepalive_time_ms": 30000, "grpc.keepalive_timeout_ms": 10000 }`. Service clients are cached per client id and refresh token, so use one `GoogleAdsApi` instance per set of options.
+- `max_reporting_rows`: throw once a report or query returns more rows than this.
+- `disable_parsing`: return raw API responses instead of parsed rows.
+
 ---
 
 ## Create a customer instance

package/build/{src → cjs}/client.d.ts

@@ -1,13 +1,15 @@
-import { Customer } from "./customer";
-import { CustomerOptions } from "./types";
-import { Hooks } from "./hooks";
-import { services } from "./protos";
+import type { grpc } from "google-gax";
+import { Customer } from "./customer.js";
+import { CustomerOptions } from "./types.js";
+import { Hooks } from "./hooks.js";
+import { services } from "./protos/index.js";
 export interface ClientOptions {
     client_id: string;
     client_secret: string;
     developer_token: string;
     disable_parsing?: boolean;
     max_reporting_rows?: number;
+    grpc_channel_options?: grpc.ChannelOptions;
 }
 export declare class Client {
     private readonly options;

package/build/{src → cjs}/client.js

@@ -1,19 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Client = void 0;
-const customer_1 = require("./customer");
-const service_1 = require("./service");
+const customer_js_1 = require("./customer.js");
+const service_js_1 = require("./service.js");
 class Client {
     options;
     constructor(options) {
         this.options = options;
     }
     Customer(customerOptions, hooks) {
-        const cus = new customer_1.Customer(this.options, customerOptions, hooks);
+        const cus = new customer_js_1.Customer(this.options, customerOptions, hooks);
         return cus;
     }
     async listAccessibleCustomers(refreshToken) {
-        const service = new service_1.Service(this.options, {
+        const service = new service_js_1.Service(this.options, {
             customer_id: "",
             refresh_token: refreshToken,
         });

package/build/{src → cjs}/customer.d.ts

@@ -1,9 +1,9 @@
 import { CancellableStream } from "google-gax";
-import { ClientOptions } from "./client";
-import { Hooks } from "./hooks";
-import { services } from "./protos";
-import ServiceFactory from "./protos/autogen/serviceFactory";
-import { CustomerOptions, MutateOperation, MutateOptions, ReportOptions, RequestOptions } from "./types";
+import { ClientOptions } from "./client.js";
+import { Hooks } from "./hooks.js";
+import { services } from "./protos/index.js";
+import ServiceFactory from "./protos/autogen/serviceFactory.js";
+import { CustomerOptions, MutateOperation, MutateOptions, ReportOptions, RequestOptions } from "./types.js";
 export declare class Customer extends ServiceFactory {
     constructor(clientOptions: ClientOptions, customerOptions: CustomerOptions, hooks?: Hooks);
     /**

package/build/{src → cjs}/customer.js

@@ -5,16 +5,16 @@ 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 serviceFactory_1 = __importDefault(require("./protos/autogen/serviceFactory"));
-const query_1 = require("./query");
-const version_1 = require("./version");
+const stream_chain_1 = __importDefault(require("stream-chain"));
+const stream_json_1 = __importDefault(require("stream-json"));
+const StreamArray_js_1 = __importDefault(require("stream-json/streamers/StreamArray.js"));
+const parserRest_js_1 = require("./parserRest.js");
+const index_js_1 = require("./protos/index.js");
+const serviceFactory_js_1 = __importDefault(require("./protos/autogen/serviceFactory.js"));
+const query_js_1 = require("./query.js");
+const version_js_1 = require("./version.js");
 const ROWS_PER_STREAMED_CHUNK = 10_000; // From experience, this is what can be expected from the API.
-class Customer extends serviceFactory_1.default {
+class Customer extends serviceFactory_js_1.default {
     constructor(clientOptions, customerOptions, hooks) {
         super(clientOptions, customerOptions, hooks ?? {});
     }
@@ -46,7 +46,7 @@ class Customer extends serviceFactory_1.default {
       @hooks onQueryStart, onQueryError, onQueryEnd
     */
     async report(options) {
-        const { gaqlQuery, requestOptions } = (0, query_1.buildQuery)(options);
+        const { gaqlQuery, requestOptions } = (0, query_js_1.buildQuery)(options);
         const { response } = await this.querier(gaqlQuery, requestOptions, options);
         return response;
     }
@@ -56,7 +56,7 @@ class Customer extends serviceFactory_1.default {
     */
     async reportCount(options) {
         // must get at least one row
-        const { gaqlQuery, requestOptions } = (0, query_1.buildQuery)({ ...options, limit: 1 });
+        const { gaqlQuery, requestOptions } = (0, query_js_1.buildQuery)({ ...options, limit: 1 });
         // We do not allow this field in reportOptions, however it is still a valid request option
         requestOptions.search_settings = {
             return_total_results_count: true,
@@ -75,7 +75,7 @@ class Customer extends serviceFactory_1.default {
       for await (const row of stream) { ... }
     */
     async *reportStream(reportOptions) {
-        const { gaqlQuery, requestOptions } = (0, query_1.buildQuery)(reportOptions);
+        const { gaqlQuery, requestOptions } = (0, query_js_1.buildQuery)(reportOptions);
         const stream = this.streamer(gaqlQuery, requestOptions, reportOptions);
         for await (const row of stream) {
             yield row;
@@ -91,7 +91,7 @@ class Customer extends serviceFactory_1.default {
       stream.on('end', () => { ... })
     */
     async reportStreamRaw(reportOptions) {
-        const { gaqlQuery, requestOptions } = (0, query_1.buildQuery)(reportOptions);
+        const { gaqlQuery, requestOptions } = (0, query_js_1.buildQuery)(reportOptions);
         const baseHookArguments = {
             credentials: this.credentials,
             query: gaqlQuery,
@@ -141,7 +141,7 @@ class Customer extends serviceFactory_1.default {
         }
         catch (e) {
             if (e.response?.data.error.details[0]) {
-                throw new protos_1.errors.GoogleAdsFailure(this.decamelizeKeysIfNeeded(e.response.data.error.details[0]));
+                throw new index_js_1.errors.GoogleAdsFailure(this.decamelizeKeysIfNeeded(e.response.data.error.details[0]));
             }
             throw e;
         }
@@ -329,13 +329,13 @@ class Customer extends serviceFactory_1.default {
             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({
+            const parser = new stream_json_1.default.Parser({
                 streamValues: false,
                 streamKeys: false,
                 packValues: true,
                 packKeys: true,
             });
-            const pipeline = (0, stream_chain_1.chain)([stream, parser, (0, StreamArray_1.streamArray)()]);
+            const pipeline = stream_chain_1.default.chain([stream, parser, StreamArray_js_1.default.streamArray()]);
             let count = 0;
             try {
                 for await (const data of pipeline) {
@@ -382,13 +382,17 @@ class Customer extends serviceFactory_1.default {
         }
         // 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 pipeline = stream_chain_1.default.chain([
+            stream,
+            stream_json_1.default.parser(),
+            StreamArray_js_1.default.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]));
+                googleAdsFailure = new index_js_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 });
@@ -481,7 +485,7 @@ 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}`,
+            url: `https://googleads.googleapis.com/${version_js_1.googleAdsVersion}/customers/${this.customerOptions.customer_id}/googleAds:${functionName}`,
             headers: {
                 Authorization: `Bearer ${accessToken}`,
                 ...this.callHeaders,
@@ -493,7 +497,7 @@ class Customer extends serviceFactory_1.default {
         if (this.clientOptions.disable_parsing) {
             return input;
         }
-        return (0, parserRest_1.decamelizeKeys)(input);
+        return (0, parserRest_js_1.decamelizeKeys)(input);
     }
     gaqlQueryStringIncludesLimit(gaqlQuery) {
         return gaqlQuery.toLowerCase().includes("limit ");

package/build/{src → cjs}/hooks.d.ts

@@ -1,5 +1,5 @@
-import { errors, services } from "./protos";
-import { CustomerCredentials, MutateOperation, ReportOptions, RequestOptions, MutateOptions } from "./types";
+import { errors, services } from "./protos/index.js";
+import { CustomerCredentials, MutateOperation, ReportOptions, RequestOptions, MutateOptions } from "./types.js";
 export type BaseRequestHookArgs = {
     credentials: CustomerCredentials;
     query: string;

package/build/cjs/index.d.ts

@@ -0,0 +1,9 @@
+export { Client as GoogleAdsApi, ClientOptions } from "./client.js";
+export { common, enums, fields, errors, resources, services, longrunning, protobuf, } from "./protos/index.js";
+export { fromMicros, toMicros } from "./utils.js";
+export { googleAdsVersion } from "./version.js";
+export { parse } from "./parser.js";
+export * as ResourceNames from "./protos/autogen/resourceNames.js";
+export { CustomerOptions, ReportOptions, MutateOperation, Constraint, Constraints, } from "./types.js";
+export { Hooks, OnQueryStart, OnQueryError, OnQueryEnd, OnStreamStart, OnStreamError, OnMutationStart, OnMutationError, OnMutationEnd, OnServiceStart, OnServiceError, OnServiceEnd, } from "./hooks.js";
+export { Customer } from "./customer.js";

package/build/{src → cjs}/index.js

@@ -33,26 +33,28 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Customer = exports.ResourceNames = exports.parse = exports.toMicros = exports.fromMicros = exports.protobuf = exports.longrunning = exports.services = exports.resources = exports.errors = exports.fields = exports.enums = exports.common = exports.GoogleAdsApi = void 0;
+exports.Customer = exports.ResourceNames = exports.parse = exports.googleAdsVersion = exports.toMicros = exports.fromMicros = exports.protobuf = exports.longrunning = exports.services = exports.resources = exports.errors = exports.fields = exports.enums = exports.common = exports.GoogleAdsApi = void 0;
 // Core library client
-var client_1 = require("./client");
-Object.defineProperty(exports, "GoogleAdsApi", { enumerable: true, get: function () { return client_1.Client; } });
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "GoogleAdsApi", { enumerable: true, get: function () { return client_js_1.Client; } });
 // Compiled proto types
-var index_1 = require("./protos/index");
-Object.defineProperty(exports, "common", { enumerable: true, get: function () { return index_1.common; } });
-Object.defineProperty(exports, "enums", { enumerable: true, get: function () { return index_1.enums; } });
-Object.defineProperty(exports, "fields", { enumerable: true, get: function () { return index_1.fields; } });
-Object.defineProperty(exports, "errors", { enumerable: true, get: function () { return index_1.errors; } });
-Object.defineProperty(exports, "resources", { enumerable: true, get: function () { return index_1.resources; } });
-Object.defineProperty(exports, "services", { enumerable: true, get: function () { return index_1.services; } });
-Object.defineProperty(exports, "longrunning", { enumerable: true, get: function () { return index_1.longrunning; } });
-Object.defineProperty(exports, "protobuf", { enumerable: true, get: function () { return index_1.protobuf; } });
+var index_js_1 = require("./protos/index.js");
+Object.defineProperty(exports, "common", { enumerable: true, get: function () { return index_js_1.common; } });
+Object.defineProperty(exports, "enums", { enumerable: true, get: function () { return index_js_1.enums; } });
+Object.defineProperty(exports, "fields", { enumerable: true, get: function () { return index_js_1.fields; } });
+Object.defineProperty(exports, "errors", { enumerable: true, get: function () { return index_js_1.errors; } });
+Object.defineProperty(exports, "resources", { enumerable: true, get: function () { return index_js_1.resources; } });
+Object.defineProperty(exports, "services", { enumerable: true, get: function () { return index_js_1.services; } });
+Object.defineProperty(exports, "longrunning", { enumerable: true, get: function () { return index_js_1.longrunning; } });
+Object.defineProperty(exports, "protobuf", { enumerable: true, get: function () { return index_js_1.protobuf; } });
 // Util functions
-var utils_1 = require("./utils");
-Object.defineProperty(exports, "fromMicros", { enumerable: true, get: function () { return utils_1.fromMicros; } });
-Object.defineProperty(exports, "toMicros", { enumerable: true, get: function () { return utils_1.toMicros; } });
-var parser_1 = require("./parser");
-Object.defineProperty(exports, "parse", { enumerable: true, get: function () { return parser_1.parse; } });
-exports.ResourceNames = __importStar(require("./protos/autogen/resourceNames"));
-var customer_1 = require("./customer");
-Object.defineProperty(exports, "Customer", { enumerable: true, get: function () { return customer_1.Customer; } });
+var utils_js_1 = require("./utils.js");
+Object.defineProperty(exports, "fromMicros", { enumerable: true, get: function () { return utils_js_1.fromMicros; } });
+Object.defineProperty(exports, "toMicros", { enumerable: true, get: function () { return utils_js_1.toMicros; } });
+var version_js_1 = require("./version.js");
+Object.defineProperty(exports, "googleAdsVersion", { enumerable: true, get: function () { return version_js_1.googleAdsVersion; } });
+var parser_js_1 = require("./parser.js");
+Object.defineProperty(exports, "parse", { enumerable: true, get: function () { return parser_js_1.parse; } });
+exports.ResourceNames = __importStar(require("./protos/autogen/resourceNames.js"));
+var customer_js_1 = require("./customer.js");
+Object.defineProperty(exports, "Customer", { enumerable: true, get: function () { return customer_js_1.Customer; } });

package/build/{src → cjs}/parser.d.ts

@@ -1,5 +1,5 @@
-import { ReportOptions } from "./types";
-import { services } from "./protos";
+import { ReportOptions } from "./types.js";
+import { services } from "./protos/index.js";
 export declare const ParsingError: {
     NO_REPORT_OPTIONS_OR_GAQL_QUERY: string;
     NO_FIELDS_IN_GAQL_QUERY: string;

package/build/{src → cjs}/parser.js

@@ -9,8 +9,8 @@ exports.getGAQLFields = getGAQLFields;
 exports.getReportOptionFields = getReportOptionFields;
 exports.parseRows = parseRows;
 const long_1 = __importDefault(require("long"));
-const protos_1 = require("./protos");
-const utils_1 = require("./utils");
+const index_js_1 = require("./protos/index.js");
+const utils_js_1 = require("./utils.js");
 exports.ParsingError = {
     NO_REPORT_OPTIONS_OR_GAQL_QUERY: "Must provided reportOptions or gaqlString to parse results.",
     NO_FIELDS_IN_GAQL_QUERY: "GAQL Query must contain at least one attribute, metric or segment.",
@@ -35,14 +35,14 @@ function parse({ results, reportOptions, gaqlString, }) {
         : getGAQLFields(gaqlString);
     // Add in all relevant resource_name fields, which are always returned by API
     const entities = queryFields.map((field) => field.split(".")[0]);
-    const resourceNameFields = protos_1.fields.resourceNames.filter((resourceNameField) => entities.includes(resourceNameField.split(".")[0]));
+    const resourceNameFields = index_js_1.fields.resourceNames.filter((resourceNameField) => entities.includes(resourceNameField.split(".")[0]));
     const allFields = [...queryFields, ...resourceNameFields];
     return parseRows(results, allFields);
 }
 // This function assumes that a gaql query is of the format "select * * * from * ...".
 // Queries that are not in this format should have thrown an error when called.
 function getGAQLFields(gaqlString) {
-    const normalisedQuery = (0, utils_1.normaliseQuery)(gaqlString);
+    const normalisedQuery = (0, utils_js_1.normaliseQuery)(gaqlString);
     const fields = normalisedQuery
         .toLowerCase()
         .replace(/(^\s*select)|( from .*)|(\s+)/g, "")
@@ -73,7 +73,7 @@ function parseRows(rows, fields) {
     const newRows = [];
     for (let r = 0; r < rows.length; r++) {
         const newRow = {};
-        const originalRow = protos_1.services.GoogleAdsRow.fromObject(rows[r]);
+        const originalRow = index_js_1.services.GoogleAdsRow.fromObject(rows[r]);
         for (const split in fieldsPreSplit) {
             // @ts-expect-error These are the best we can do for these types
             const [parent, ...children] = fieldsPreSplit[split];

package/build/{src → cjs}/parserRest.js

@@ -2,10 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.decamelizeKeys = void 0;
 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 utils_js_1 = require("./utils.js");
+const fields_js_1 = require("./protos/autogen/fields.js");
+const enums_js_1 = require("./protos/autogen/enums.js");
+const fieldDataTypes = (0, circ_json_1.parse)(fields_js_1.fieldDataTypes);
 const decamelizeCache = new Map();
 const fieldTypeCache = new Map();
 const isObject = (value) => typeof value === "object" && value !== null;
@@ -51,7 +51,7 @@ const cachedDecamelize = (key) => {
     if (cachedResult) {
         return cachedResult;
     }
-    const newKey = (0, utils_1.toSnakeCase)(key);
+    const newKey = (0, utils_js_1.toSnakeCase)(key);
     decamelizeCache.set(key, newKey);
     return newKey;
 };
@@ -73,7 +73,7 @@ const cachedValueParser = (key, parentPath, value) => {
                     return p
                         .trim()
                         .split(".")
-                        .map((segment) => (0, utils_1.toSnakeCase)(segment))
+                        .map((segment) => (0, utils_js_1.toSnakeCase)(segment))
                         .join(".");
                 }),
             };
@@ -89,7 +89,7 @@ const cachedValueParser = (key, parentPath, 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"
+        newValue = enums_js_1.enums[fields_js_1.fields.enumFields[fullPath]][value]; // e.g. enums['CampaignStatus'][ENABLED] = "2"
     }
     return newValue;
 };