google-ads-api 24.1.0 → 25.1.0-beta.1

package/build/cjs/protos/index.d.ts

@@ -0,0 +1,14 @@
+import allProtos, { protos } from "google-ads-node";
+export declare const VERSION: "v25";
+export import common = protos.google.ads.googleads.v25.common;
+export import errors = protos.google.ads.googleads.v25.errors;
+export import resources = protos.google.ads.googleads.v25.resources;
+export import services = protos.google.ads.googleads.v25.services;
+export import internalEnums = protos.google.ads.googleads.v25.enums;
+export { enums } from "./autogen/enums.js";
+export { fields, fieldDataTypes } from "./autogen/fields.js";
+export { GoogleAdsServiceClient } from "google-ads-node";
+export type AllServices = Omit<typeof allProtos, typeof VERSION>;
+export type ServiceName = keyof Omit<typeof allProtos, typeof VERSION>;
+export import protobuf = protos.google.protobuf;
+export import longrunning = protos.google.longrunning;

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

@@ -2,22 +2,22 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.longrunning = exports.protobuf = exports.GoogleAdsServiceClient = exports.fieldDataTypes = exports.fields = exports.enums = exports.internalEnums = exports.services = exports.resources = exports.errors = exports.common = exports.VERSION = void 0;
 const google_ads_node_1 = require("google-ads-node");
-const version_1 = require("../version");
+const version_js_1 = require("../version.js");
 // "as vN" is required to avoid type issues later on
-exports.VERSION = version_1.googleAdsVersion;
+exports.VERSION = version_js_1.googleAdsVersion;
 // -- Expose the googleads generated types --
 // The namespace path is shortened for ease of use
-exports.common = google_ads_node_1.protos.google.ads.googleads.v24.common;
-exports.errors = google_ads_node_1.protos.google.ads.googleads.v24.errors;
-exports.resources = google_ads_node_1.protos.google.ads.googleads.v24.resources;
-exports.services = google_ads_node_1.protos.google.ads.googleads.v24.services;
+exports.common = google_ads_node_1.protos.google.ads.googleads.v25.common;
+exports.errors = google_ads_node_1.protos.google.ads.googleads.v25.errors;
+exports.resources = google_ads_node_1.protos.google.ads.googleads.v25.resources;
+exports.services = google_ads_node_1.protos.google.ads.googleads.v25.services;
 // We compile enums ourselves, the Google ones should be used internally only
-exports.internalEnums = google_ads_node_1.protos.google.ads.googleads.v24.enums;
-var enums_1 = require("./autogen/enums");
-Object.defineProperty(exports, "enums", { enumerable: true, get: function () { return enums_1.enums; } });
-var fields_1 = require("./autogen/fields");
-Object.defineProperty(exports, "fields", { enumerable: true, get: function () { return fields_1.fields; } });
-Object.defineProperty(exports, "fieldDataTypes", { enumerable: true, get: function () { return fields_1.fieldDataTypes; } });
+exports.internalEnums = google_ads_node_1.protos.google.ads.googleads.v25.enums;
+var enums_js_1 = require("./autogen/enums.js");
+Object.defineProperty(exports, "enums", { enumerable: true, get: function () { return enums_js_1.enums; } });
+var fields_js_1 = require("./autogen/fields.js");
+Object.defineProperty(exports, "fields", { enumerable: true, get: function () { return fields_js_1.fields; } });
+Object.defineProperty(exports, "fieldDataTypes", { enumerable: true, get: function () { return fields_js_1.fieldDataTypes; } });
 // Common service used for report/query methods
 var google_ads_node_2 = require("google-ads-node");
 Object.defineProperty(exports, "GoogleAdsServiceClient", { enumerable: true, get: function () { return google_ads_node_2.GoogleAdsServiceClient; } });

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

@@ -1,5 +1,5 @@
-import { fields } from "./protos";
-import { ConstraintKey, ConstraintOperation, ConstraintValue, ReportOptions, RequestOptions, RequestOptionsWithTotalResults, SortOrder } from "./types";
+import { fields } from "./protos/index.js";
+import { ConstraintKey, ConstraintOperation, ConstraintValue, ReportOptions, RequestOptions, RequestOptionsWithTotalResults, SortOrder } from "./types.js";
 declare enum QueryKeywords {
     SELECT = "SELECT",
     FROM = "FROM",

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

@@ -17,8 +17,8 @@ exports.buildOrderClauseNew = buildOrderClauseNew;
 exports.buildOrderClause = buildOrderClause;
 exports.buildRequestOptions = buildRequestOptions;
 exports.buildQuery = buildQuery;
-const protos_1 = require("./protos");
-const types_1 = require("./types");
+const index_js_1 = require("./protos/index.js");
+const types_js_1 = require("./types.js");
 var QueryKeywords;
 (function (QueryKeywords) {
     QueryKeywords["SELECT"] = "SELECT";
@@ -97,7 +97,7 @@ function validateConstraintKeyAndValue(key, op, val) {
         return { op: "=", val: convertNumericEnumToString(key, val) };
     }
     if (typeof val === "string") {
-        if (types_1.dateConstants.includes(val)) {
+        if (types_js_1.dateConstants.includes(val)) {
             return { op, val };
         }
         return { op: "=", val: formatGaqlString(val) };
@@ -119,9 +119,9 @@ function validateConstraintKeyAndValue(key, op, val) {
 }
 function convertNumericEnumToString(key, val) {
     // @ts-expect-error key does not always match an enum field
-    if (protos_1.fields.enumFields[key] && typeof val === "number") {
+    if (index_js_1.fields.enumFields[key] && typeof val === "number") {
         // @ts-expect-error typescript doesn't like accessing items in a namespace with a string
-        const enumStringValue = protos_1.enums[protos_1.fields.enumFields[key]][val]; // e.g. enums['CampaignStatus'][2] = "ENABLED"
+        const enumStringValue = index_js_1.enums[index_js_1.fields.enumFields[key]][val]; // e.g. enums['CampaignStatus'][2] = "ENABLED"
         if (enumStringValue) {
             return `"${enumStringValue}"`;
         }

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

@@ -1,9 +1,9 @@
-import { ClientOptions } from "./client";
-import { AllServices, errors, GoogleAdsServiceClient, ServiceName, services } from "./protos";
-import { CustomerOptions, CustomerCredentials, RequestOptions, MutateOperation, MutateOptions } from "./types";
-import { Hooks } from "./hooks";
+import { ClientOptions } from "./client.js";
+import { AllServices, errors, GoogleAdsServiceClient, ServiceName, services } from "./protos/index.js";
+import { CustomerOptions, CustomerCredentials, RequestOptions, MutateOperation, MutateOptions } from "./types.js";
+import { Hooks } from "./hooks.js";
 import TTLCache from "@isaacs/ttlcache";
-export declare const FAILURE_KEY = "google.ads.googleads.v24.errors.googleadsfailure-bin";
+export declare const FAILURE_KEY = "google.ads.googleads.v25.errors.googleadsfailure-bin";
 export interface CallHeaders {
     "developer-token": string;
     "login-customer-id"?: string;

package/build/cjs/service.js

@@ -0,0 +1,263 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Service = exports.serviceCache = exports.FAILURE_KEY = void 0;
+exports.disposeService = disposeService;
+const google_gax_1 = require("google-gax");
+const googleAdsNode = __importStar(require("google-ads-node"));
+const google_auth_library_1 = require("google-auth-library");
+const index_js_1 = require("./protos/index.js");
+const utils_js_1 = require("./utils.js");
+const version_js_1 = require("./version.js");
+const ttlcache_1 = __importDefault(require("@isaacs/ttlcache"));
+// Make sure to update this version number when upgrading
+exports.FAILURE_KEY = `google.ads.googleads.${version_js_1.googleAdsVersion}.errors.googleadsfailure-bin`;
+// Close connections when services are removed from the cache
+function disposeService(service) {
+    Promise.resolve()
+        .then(() => service.close())
+        .catch(() => null);
+}
+// A global service cache to avoid re-initialising services
+exports.serviceCache = new ttlcache_1.default({
+    max: 1_000,
+    ttl: 10 * 60 * 1000, // 10 minutes
+    checkAgeOnGet: true,
+    dispose: disposeService,
+});
+// A global access token cache used by REST calls. Issued tokens expire after 1 hour, so we cache them for 50 minutes.
+const accessTokenCache = new ttlcache_1.default({
+    max: 100_000,
+    ttl: 50 * 60 * 1000, // 50 minutes
+});
+class Service {
+    clientOptions;
+    customerOptions;
+    hooks;
+    constructor(clientOptions, customerOptions, hooks) {
+        this.clientOptions = clientOptions;
+        this.customerOptions = customerOptions;
+        this.hooks = hooks ?? {};
+        // @ts-expect-error All fields don't need to be set here
+        this.serviceCache = {};
+    }
+    get credentials() {
+        return {
+            customer_id: this.customerOptions.customer_id,
+            login_customer_id: this.customerOptions.login_customer_id,
+            linked_customer_id: this.customerOptions.linked_customer_id,
+        };
+    }
+    get callHeaders() {
+        const headers = {
+            "developer-token": this.clientOptions.developer_token,
+        };
+        if (this.customerOptions.login_customer_id) {
+            headers["login-customer-id"] = this.customerOptions.login_customer_id;
+        }
+        if (this.customerOptions.linked_customer_id) {
+            headers["linked-customer-id"] = this.customerOptions.linked_customer_id;
+        }
+        return headers;
+    }
+    // Used only by gRPC calls
+    getCredentials() {
+        const sslCreds = google_gax_1.grpc.credentials.createSsl();
+        const authClient = new google_auth_library_1.UserRefreshClient({
+            clientId: this.clientOptions.client_id,
+            clientSecret: this.clientOptions.client_secret,
+            refreshToken: this.customerOptions.refresh_token,
+        });
+        const credentials = google_gax_1.grpc.credentials.combineChannelCredentials(sslCreds, google_gax_1.grpc.credentials.createFromGoogleCredential({
+            getRequestHeaders: async (url) => Object.fromEntries(await authClient.getRequestHeaders(url)),
+        }));
+        return credentials;
+    }
+    // Used only by REST calls
+    async getAccessToken() {
+        const cachedToken = accessTokenCache.get(this.customerOptions.refresh_token);
+        if (cachedToken) {
+            return cachedToken;
+        }
+        const oAuth2Client = new google_auth_library_1.OAuth2Client({
+            clientId: this.clientOptions.client_id,
+            clientSecret: this.clientOptions.client_secret,
+        });
+        oAuth2Client.setCredentials({
+            refresh_token: this.customerOptions.refresh_token,
+        });
+        const { token } = await oAuth2Client.getAccessToken();
+        if (typeof token !== "string") {
+            throw new Error("Failed to retrieve access token");
+        }
+        accessTokenCache.set(this.customerOptions.refresh_token, token);
+        return token;
+    }
+    loadService(service, options) {
+        const serviceCacheKey = `${service}_${this.clientOptions.client_id}_${this.customerOptions.refresh_token}_${JSON.stringify(this.clientOptions.grpc_channel_options ?? null)}`;
+        if (!options?.skipCache) {
+            const cachedService = exports.serviceCache.get(serviceCacheKey);
+            if (cachedService) {
+                return cachedService;
+            }
+        }
+        const protoService = googleAdsNode[service];
+        if (typeof protoService === "undefined") {
+            throw new Error(`Service "${String(service)}" could not be found`);
+        }
+        // Initialising services can take a few ms, so we cache when possible.
+        const client = new protoService({
+            ...this.clientOptions.grpc_channel_options,
+            sslCreds: this.getCredentials(),
+            universeDomain: "googleapis.com",
+        });
+        if (!options?.skipCache) {
+            exports.serviceCache.set(serviceCacheKey, client);
+        }
+        return client;
+    }
+    getGoogleAdsError(error) {
+        const trailer = error?.metadata?.internalRepr?.get?.(exports.FAILURE_KEY);
+        if (typeof trailer?.[0] === "undefined") {
+            return error;
+        }
+        return this.decodeGoogleAdsFailureBuffer(trailer[0]);
+    }
+    decodeGoogleAdsFailureBuffer(buffer) {
+        const googleAdsFailure = index_js_1.errors.GoogleAdsFailure.decode(buffer);
+        return googleAdsFailure;
+    }
+    decodePartialFailureError(response) {
+        if (typeof response?.partial_failure_error === "undefined" ||
+            !response?.partial_failure_error) {
+            return response;
+        }
+        const { details } = response.partial_failure_error;
+        const buffer = details?.find((d) => d.type_url.includes("errors.GoogleAdsFailure"))?.value;
+        if (typeof buffer === "undefined") {
+            return response;
+        }
+        // Update the partial failure field with the decoded error details
+        return {
+            ...response,
+            partial_failure_error: this.decodeGoogleAdsFailureBuffer(buffer),
+        };
+    }
+    buildSearchRequestAndService(gaql, options) {
+        const service = this.loadService("GoogleAdsServiceClient");
+        const request = new index_js_1.services.SearchGoogleAdsRequest({
+            customer_id: this.customerOptions.customer_id,
+            query: gaql,
+            ...options,
+        });
+        return { service, request };
+    }
+    buildSearchStreamRequestAndService(gaql, options) {
+        const service = this.loadService("GoogleAdsServiceClient");
+        const request = new index_js_1.services.SearchGoogleAdsStreamRequest({
+            customer_id: this.customerOptions.customer_id,
+            query: gaql,
+            ...options,
+        });
+        return { service, request };
+    }
+    buildMutationRequestAndService(mutations, options) {
+        const service = this.loadService("GoogleAdsServiceClient");
+        const mutateOperations = mutations.map((mutation) => {
+            const opKey = (0, utils_js_1.toSnakeCase)(`${mutation.entity}Operation`);
+            const operation = {
+                [mutation.operation ?? "create"]: mutation.resource,
+            };
+            if (mutation.operation === "create" &&
+                //@ts-ignore
+                mutation?.exempt_policy_violation_keys?.length) {
+                //@ts-ignore
+                operation.exempt_policy_violation_keys =
+                    mutation.exempt_policy_violation_keys;
+            }
+            else if (mutation.operation === "update") {
+                // @ts-expect-error Resource operations should have updateMask defined
+                operation.update_mask = (0, utils_js_1.getFieldMask)(mutation.resource);
+            }
+            const mutateOperation = new index_js_1.services.MutateOperation({
+                [opKey]: operation,
+            });
+            return mutateOperation;
+        });
+        const request = new index_js_1.services.MutateGoogleAdsRequest({
+            customer_id: this.customerOptions.customer_id,
+            mutate_operations: mutateOperations,
+            ...options,
+        });
+        return { service, request };
+    }
+    buildOperations(type, entities, message) {
+        const ops = entities.map((e) => {
+            const op = {
+                [type]: e,
+                operation: type,
+            };
+            //@ts-ignore
+            if (type === "create" && e?.exempt_policy_violation_keys?.length) {
+                // @ts-expect-error Field required for policy violation exemptions
+                op.exempt_policy_violation_keys = e.exempt_policy_violation_keys;
+                //@ts-ignore
+                delete e.exempt_policy_violation_keys;
+            }
+            else if (type === "update") {
+                // @ts-expect-error Field required for updates
+                op.update_mask = (0, utils_js_1.getFieldMask)(
+                // @ts-expect-error Message types have a toObject method
+                message.toObject(e, {
+                    defaults: false,
+                }));
+            }
+            return op;
+        });
+        return ops;
+    }
+    buildRequest(operations, options) {
+        const request = {
+            customer_id: this.customerOptions.customer_id,
+            operations,
+            ...options,
+        };
+        return request;
+    }
+}
+exports.Service = Service;

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

@@ -1,4 +1,4 @@
-import { services, fields } from "./protos";
+import { services, fields } from "./protos/index.js";
 export interface CustomerOptions {
     customer_id: string;
     refresh_token: string;

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

@@ -1,4 +1,4 @@
-import { protobuf } from "./protos";
+import { protobuf } from "./protos/index.js";
 /**
  * @param micros Money value in micros format
  * @description Converts a micro amount to a normalised value

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

@@ -12,7 +12,7 @@ exports.toSnakeCase = toSnakeCase;
 exports.recursiveFieldMaskSearch = recursiveFieldMaskSearch;
 exports.getFieldMask = getFieldMask;
 const long_1 = __importDefault(require("long"));
-const protos_1 = require("./protos");
+const index_js_1 = require("./protos/index.js");
 /**
  * @param micros Money value in micros format
  * @description Converts a micro amount to a normalised value
@@ -115,7 +115,7 @@ ancestors = new Set()) {
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function getFieldMask(data) {
     const paths = recursiveFieldMaskSearch(data);
-    return new protos_1.protobuf.FieldMask({
+    return new index_js_1.protobuf.FieldMask({
         paths,
     });
 }

package/build/cjs/version.d.ts

@@ -0,0 +1 @@
+export declare const googleAdsVersion = "v25";

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

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.googleAdsVersion = void 0;
-exports.googleAdsVersion = "v24";
+exports.googleAdsVersion = "v25";

package/build/esm/client.d.ts

@@ -0,0 +1,19 @@
+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;
+    constructor(options: ClientOptions);
+    Customer(customerOptions: CustomerOptions, hooks?: Hooks): Customer;
+    listAccessibleCustomers(refreshToken: string): Promise<services.ListAccessibleCustomersResponse>;
+}

package/build/esm/client.js

@@ -0,0 +1,40 @@
+import { Customer } from "./customer.js";
+import { Service } from "./service.js";
+export class Client {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    Customer(customerOptions, hooks) {
+        const cus = new Customer(this.options, customerOptions, hooks);
+        return cus;
+    }
+    async listAccessibleCustomers(refreshToken) {
+        const service = new Service(this.options, {
+            customer_id: "",
+            refresh_token: refreshToken,
+        });
+        // @ts-expect-error Protected usage is fine here
+        const customerService = service.loadService("CustomerServiceClient", { skipCache: true });
+        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);
+        }
+        finally {
+            // @ts-expect-error close() exists on the gax client but not on the proto type
+            await customerService.close().catch(() => null);
+        }
+    }
+}

package/build/esm/customer.d.ts

@@ -0,0 +1,71 @@
+import { CancellableStream } from "google-gax";
+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);
+    /**
+      @description Single query using a raw GAQL string.
+      @hooks onQueryStart, onQueryError, onQueryEnd
+    */
+    query<T = services.IGoogleAdsRow[]>(gaqlQuery: string, requestOptions?: Readonly<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?: Readonly<RequestOptions>): AsyncGenerator<T>;
+    /**
+      @description Single query using ReportOptions.
+      If a summary row is requested then this will be the first row of the results.
+      @hooks onQueryStart, onQueryError, onQueryEnd
+    */
+    report<T = services.IGoogleAdsRow[]>(options: Readonly<ReportOptions>): Promise<T>;
+    /**
+      @description Get the total row count of a report.
+      @hooks none
+    */
+    reportCount(options: Readonly<ReportOptions>): Promise<number | undefined>;
+    /**
+      @description Stream query using ReportOptions. 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 = reportStream<T>(reportOptions)
+      for await (const row of stream) { ... }
+    */
+    reportStream<T = services.IGoogleAdsRow>(reportOptions: Readonly<ReportOptions>): AsyncGenerator<T>;
+    /**
+      @description Retreive the raw stream using ReportOptions.
+      @hooks onStreamStart
+      @example
+      const stream = reportStreamRaw(reportOptions)
+      stream.on('data', (chunk) => { ... }) // a chunk contains up to 10,000 un-parsed rows
+      stream.on('error', (error) => { ... })
+      stream.on('end', () => { ... })
+    */
+    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
+     * campaign budget, or perform up to thousands of mutates atomically.
+     * @hooks onMutationStart, onMutationError, onMutationEnd
+     */
+    mutateResources<T>(mutations: MutateOperation<T>[], mutateOptions?: MutateOptions): Promise<services.MutateGoogleAdsResponse>;
+    private get googleAdsFields();
+    private prepareGoogleAdsServicePostRequestArgs;
+    private decamelizeKeysIfNeeded;
+    private gaqlQueryStringIncludesLimit;
+    private generateTooManyRowsError;
+}