V24.1

CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+### 24.1.0
+
+### Version Upgrade
+
+- Upgraded google-ads-api version to v24.1. Refer to Google Ads release notes [here](https://developers.google.com/google-ads/api/docs/release-notes) for changes.
+- Upgraded google-ads-node dependency to v24.1.0
+- Upgraded google-gax dependency to v5.0.7
+- @isaacs/ttlcache now requires ^1.4.0
+
+### New Features
+
+- New services: `ReservationService`, `YouTubeVideoUploadService`
+- New resource names: `AppTopCombinationView`, `CartDataSalesView`, `VideoEnhancement`, `YouTubeVideoUpload`
+- New enums include `ReservationRequestType`, `PreviewType`, and new `ExperimentType` values (`ADOPT_AI_MAX`, `ADOPT_BROAD_MATCH_KEYWORDS`, `OPTIMIZE_ASSETS`, `PMAX_REPLACEMENT_SHOPPING`)
+- New v24.1 fields such as `segments.mobile_device_platform` and `customer_user_access.passkey_enabled`
+
+### Breaking Changes
+
+- `parse()` now returns plain objects for message-typed leaves (e.g. `change_event.old_resource`) instead of protobuf message instances, and converts all nested int64 values from Long objects to JavaScript numbers. Code reading `.low`/`.high` from nested values, or relying on protobuf prototypes, must use the plain values instead. Note that int64 values above `Number.MAX_SAFE_INTEGER` (2^53 - 1) lose precision when converted, consistent with the existing behaviour for directly-selected fields.
+
+### Fixes
+
+- `resource_name` attributes for ten view resources (including `keyword_view` and `paid_organic_search_term_view`) were missing from parsed results due to a code generation bug; they are now included.
+- `getFieldMask()` now throws a descriptive `Error` on objects containing circular references instead of overflowing the stack, and treats typed arrays (`Buffer`, `Uint8Array`) and `Long` values as leaf values. Previously, update masks built from payloads containing `Long` values included invalid `.low`/`.high`/`.unsigned` paths that the API rejected.
+- Report streams now destroy their underlying response stream and JSON parser when consumers exit iteration early
+- Rejected `close()` calls during gRPC service cache eviction are now caught instead of surfacing as unhandled promise rejections (the dispose callback was previously `async` and fire-and-forget)
+- Cached gRPC service clients past their TTL are no longer returned, and expired entries awaiting purge no longer resolve to `undefined`
+- `listAccessibleCustomers()` closes its one-shot `CustomerServiceClient` after the call instead of caching it
+
 ### 23.0.0
 
 ### Version Upgrade

package.json

@@ -1,6 +1,6 @@
 {
   "name": "google-ads-api",
-  "version": "23.0.0",
+  "version": "24.1.0",
   "description": "Google Ads API Client Library for Node.js",
   "repository": "https://github.com/Opteo/google-ads-api",
   "main": "build/src/index.js",
@@ -18,12 +18,12 @@
   "author": "Opteo",
   "license": "MIT",
   "dependencies": {
-    "@isaacs/ttlcache": "^1.2.2",
+    "@isaacs/ttlcache": "^1.4.0",
     "axios": "^1.6.7",
     "circ-json": "^1.0.4",
-    "google-ads-node": "23.0.0",
+    "google-ads-node": "24.1.0",
     "google-auth-library": "^9.15.1",
-    "google-gax": "^5.0.6",
+    "google-gax": "^5.0.7",
     "long": "^4.0.0",
     "stream-json": "^1.8.0"
   },

scripts/fields.spec.ts

@@ -67,6 +67,22 @@ describe("other checkers", () => {
     expect(isResourceName(nonResourceNameField)).toBeFalsy();
   });
 
+  it("isResourceName matches consecutive resource_name fields", () => {
+    // Regression: a stateful /g regex carried lastIndex between calls,
+    // silently dropping resource_name fields tested back-to-back
+    const fields = [
+      "keyword_theme_constant.resource_name",
+      "keyword_view.resource_name",
+      "label.resource_name",
+    ].map((name) => new resources.GoogleAdsField({ name }));
+
+    expect(fields.map((field) => isResourceName(field))).toEqual([
+      true,
+      true,
+      true,
+    ]);
+  });
+
   it("hasEnumDataType", () => {
     const doesHaveEnumDataType = new resources.GoogleAdsField({
       data_type: "ENUM",
@@ -82,12 +98,10 @@ describe("other checkers", () => {
 
   it("getEnumName", () => {
     const attributeEnumField = new resources.GoogleAdsField({
-      type_url:
-        `google.ads.googleads.${googleAdsVersion}.enums.CampaignStatusEnum.CampaignStatus`,
+      type_url: `google.ads.googleads.${googleAdsVersion}.enums.CampaignStatusEnum.CampaignStatus`,
     });
     const metricEnumField = new resources.GoogleAdsField({
-      type_url:
-        `google.ads.googleads.${googleAdsVersion}.enums.QualityScoreBucketEnum.QualityScoreBucket`,
+      type_url: `google.ads.googleads.${googleAdsVersion}.enums.QualityScoreBucketEnum.QualityScoreBucket`,
     });
     const segmentEnumField = new resources.GoogleAdsField({
       type_url: `google.ads.googleads.${googleAdsVersion}.enums.DayOfWeekEnum.DayOfWeek`,

scripts/fields.ts

@@ -194,7 +194,7 @@
 
       See fieldDataTypes in autogen/fields.ts for an idea of the final product.
   */
   let mega: any = {};
   function assembleMega(typeForLookup: string) {
     if (typeForLookup.startsWith("com.")) {
       typeForLookup = typeForLookup.replace("com.", "");
@@ -212,7 +212,7 @@
     }
     const fields = foundMessage.fields;
 
     const o: any = {};
     mega[foundMessage.name] = o;
     for (const fieldKey in fields) {
       const fieldKeyType = fields[fieldKey].type;
@@ -245,13 +245,13 @@
   // Messages are the main challenge here, as they can contain other messages,
   // Sometimes with infite recursion.
   for (const field of fields.filter((field) => field.data_type === "MESSAGE")) {
     _.set(mega, field.name!, assembleMega(field.type_url as string));
   }
   for (const field of fields.filter((field) => field.data_type !== "MESSAGE")) {
     if (!_.get(mega, field.name!)) {
       _.set(
         mega,
         field.name!,
         (field.data_type as string).toUpperCase() as string
       );
     }
@@ -318,7 +318,7 @@
   );
 }
 
-const resourceNameRegex = new RegExp(/^.*\.resource_name$/g);
+const resourceNameRegex = /^.*\.resource_name$/;
 
 export function isResourceName(field: resources.GoogleAdsField): boolean {
   if (isDefinedAndNotNull(field.name)) {

src/client.spec.ts

@@ -0,0 +1,53 @@
+import { Client } from "./client";
+import { Service } from "./service";
+
+describe("listAccessibleCustomers", () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  const newClient = () =>
+    new Client({
+      client_id: "MOCK_CLIENT_ID",
+      client_secret: "MOCK_CLIENT_SECRET",
+      developer_token: "MOCK_DEVELOPER_TOKEN",
+    });
+
+  it("closes the one-shot customer service after the call", async () => {
+    const client = newClient();
+    const close = jest.fn().mockResolvedValue(undefined);
+    const listAccessibleCustomers = jest
+      .fn()
+      .mockResolvedValue([{ resource_names: ["customers/123"] }]);
+
+    const loadServiceSpy = jest
+      .spyOn(Service.prototype as any, "loadService")
+      .mockReturnValue({ listAccessibleCustomers, close });
+
+    const response = await client.listAccessibleCustomers("MOCK_REFRESH_TOKEN");
+
+    expect(response).toEqual({ resource_names: ["customers/123"] });
+    expect(loadServiceSpy).toHaveBeenCalledWith("CustomerServiceClient", {
+      skipCache: true,
+    });
+    expect(close).toHaveBeenCalledTimes(1);
+  });
+
+  it("closes the one-shot customer service when the call fails", async () => {
+    const client = newClient();
+    const close = jest.fn().mockResolvedValue(undefined);
+
+    jest.spyOn(Service.prototype as any, "loadService").mockReturnValue({
+      listAccessibleCustomers: jest
+        .fn()
+        .mockRejectedValue(new Error("rpc failed")),
+      close,
+    });
+    jest.spyOn(console, "log").mockImplementation(() => undefined);
+
+    await expect(
+      client.listAccessibleCustomers("MOCK_REFRESH_TOKEN")
+    ).rejects.toThrow("rpc failed");
+    expect(close).toHaveBeenCalledTimes(1);
+  });
+});

src/client.ts

@@ -32,8 +32,9 @@ export class Client {
       refresh_token: refreshToken,
     });
     // @ts-expect-error Protected usage is fine here
-    const customerService = await service.loadService<services.CustomerService>(
-      "CustomerServiceClient"
+    const customerService = service.loadService<services.CustomerService>(
+      "CustomerServiceClient",
+      { skipCache: true }
     );
     try {
       // @ts-expect-error Type definition is incorrect, response is an array
@@ -52,6 +53,9 @@ export class Client {
       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);
     }
   }
 }

src/customer.spec.ts

@@ -1,4 +1,5 @@
 import { operationsProtos } from "google-gax";
+import { Readable } from "stream";
 import { Hooks } from "./hooks";
 import axios from "axios";
 import MockAdapter from "axios-mock-adapter";
@@ -458,6 +459,26 @@ describe("reportStream", () => {
     expect(acc).toEqual(mockQueryReturnValue);
   });
 
+  it("destroys the response stream when the consumer exits early", async () => {
+    const customer = newCustomer({});
+    mockGetAccessToken(customer);
+
+    const json = JSON.stringify(mockSearchRawResult);
+    const sourceStream = new Readable({ read: jest.fn() });
+    sourceStream.push(json.slice(0, -1));
+
+    axiosMock.onPost().reply(200, sourceStream);
+
+    const stream = customer.reportStream(mockReportOptions);
+
+    for await (const row of stream) {
+      void row;
+      break;
+    }
+
+    expect(sourceStream.destroyed).toBe(true);
+  });
+
   it("skips reportStream parsing if it is disabled in the client options", async () => {
     const disableParsing = true;
     const customer = newCustomer({}, disableParsing);

src/customer.ts

@@ -498,25 +498,31 @@ export class Customer extends ServiceFactory {
       const pipeline = chain([stream, parser, streamArray()]);
       let count = 0;
 
-      for await (const data of pipeline) {
-        const results =
-          data.value.results ??
-          (data.value.summaryRow ? [data.value.summaryRow] : undefined) ??
-          [];
-
-        count += results.length;
-        if (
-          this.clientOptions.max_reporting_rows &&
-          count > this.clientOptions.max_reporting_rows &&
-          !this.gaqlQueryStringIncludesLimit(gaqlQuery)
-        ) {
-          throw this.generateTooManyRowsError();
-        }
+      try {
+        for await (const data of pipeline) {
+          const results =
+            data.value.results ??
+            (data.value.summaryRow ? [data.value.summaryRow] : undefined) ??
+            [];
+
+          count += results.length;
+          if (
+            this.clientOptions.max_reporting_rows &&
+            count > this.clientOptions.max_reporting_rows &&
+            !this.gaqlQueryStringIncludesLimit(gaqlQuery)
+          ) {
+            throw this.generateTooManyRowsError();
+          }
 
-        for (const row of results) {
-          const parsed = this.decamelizeKeysIfNeeded(row);
-          yield parsed as T;
+          for (const row of results) {
+            const parsed = this.decamelizeKeysIfNeeded(row);
+            yield parsed as T;
+          }
         }
+      } finally {
+        pipeline.destroy();
+        parser.destroy();
+        stream.destroy();
       }
 
       return;

src/parser.spec.ts

@@ -408,11 +408,12 @@ describe("parseRows", () => {
       result[0].change_event?.old_resource?.campaign_criterion?.campaign
     ).toBe("customers/4517895542/campaigns/21890334919");
     expect(
-      (
-        result[0].change_event?.old_resource?.campaign_criterion
-          ?.criterion_id as any
-      )?.low
+      result[0].change_event?.old_resource?.campaign_criterion?.criterion_id
     ).toBe(23340370);
+    expect(
+      typeof result[0].change_event?.old_resource?.campaign_criterion
+        ?.criterion_id
+    ).toBe("number");
     expect(
       result[0].change_event?.old_resource?.campaign_criterion?.negative
     ).toBe(true);

src/parser.ts

@@ -127,6 +127,32 @@ export function parseRows(
   return newRows;
 }
 
+function convertLongsToNumbers(value: any): any {
+  const isPrimitive = value === null || typeof value !== "object";
+  if (isPrimitive) {
+    return value;
+  }
+
+  if (long.isLong(value)) {
+    return value.toNumber();
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(convertLongsToNumbers);
+  }
+
+  const isBytesField = ArrayBuffer.isView(value);
+  if (isBytesField) {
+    return value;
+  }
+
+  const converted: Record<string, any> = {};
+  for (const [key, nestedValue] of Object.entries(value)) {
+    converted[key] = convertLongsToNumbers(nestedValue);
+  }
+  return converted;
+}
+
 function parseNestedValues(
   row: services.IGoogleAdsRow,
   data: any,
@@ -137,12 +163,9 @@ function parseNestedValues(
   const [parentField, ...childFields] = paths;
   if (!row) row = {};
   if (childFields.length === 0) {
-    const rawVal = data[parentField];
-    const parsedVal = long.isLong(rawVal)
-      ? new long(rawVal.low, rawVal.high, rawVal.unsigned).toNumber()
-      : rawVal;
-
-    row[parentField as fields.Resource] = parsedVal;
+    row[parentField as fields.Resource] = convertLongsToNumbers(
+      data[parentField]
+    );
     return row;
   }