@pipedream/google_ads 0.6.0 → 0.8.0

package/actions/create-report/create-report.mjs

@@ -20,7 +20,7 @@ export default {
   key: "google_ads-create-report",
   name: "Create Report",
   description: "Generates a report from your Google Ads data. [See the documentation](https://developers.google.com/google-ads/api/reference/rpc/v21/GoogleAdsService/Search?transport=rest)",
-  version: "0.1.6",
+  version: "0.2.1",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,
@@ -34,106 +34,100 @@ export default {
       label: "Resource",
       description: "The resource to generate a report for.",
       options: RESOURCES.map((r) => r.resourceOption),
-      reloadProps: true,
     },
-  },
-  additionalProps() {
-    const resource = RESOURCES.find((r) => r.resourceOption.value === this.resource);
-    if (!resource) throw new ConfigurationError("Select one of the available resources.");
-
-    const {
-      label, value,
-    } = resource.resourceOption;
-
-    return {
-      docsAlert: {
-        type: "alert",
-        alertType: "info",
-        content: `[See the documentation](https://developers.google.com/google-ads/api/fields/v21/${value}) for more information on available fields, segments and metrics.`,
-      },
-      objectFilter: {
-        type: "string[]",
-        label: `Filter by ${label}s`,
-        description: `Select the ${label}s to generate a report for (or leave blank for all ${label}s)`,
-        optional: true,
-        useQuery: true,
-        options: async ({
-          query, prevContext: { nextPageToken: pageToken },
-        }) => {
-          const {
-            accountId, customerClientId, resource,
-          } = this;
-          const {
-            results, nextPageToken,
-          } = await this.googleAds.listResources({
-            accountId,
-            customerClientId,
-            resource,
-            query,
-            pageToken,
-          });
-          const options = results?.map?.((item) => this.getResourceOption(item, resource));
-          return {
-            options,
-            context: {
-              nextPageToken,
-            },
-          };
-        },
-      },
-      dateRange: {
-        type: "string",
-        label: "Date Range",
-        description: "Select a date range for the report",
-        options: DATE_RANGE_OPTIONS,
-        optional: true,
-        reloadProps: true,
+    objectFilter: {
+      type: "string[]",
+      label: "Filter by Resources",
+      description: "Google Ads resource IDs to limit the report to. Pass a string array of numeric IDs (e.g. `[\"1234567890\", \"9876543210\"]`). Omit to include all resources.",
+      optional: true,
+      useQuery: true,
+      async options({
+        query, prevContext = {},
+      }) {
+        const { nextPageToken: pageToken } = prevContext;
+        const {
+          accountId, customerClientId, resource,
+        } = this;
+        const {
+          results, nextPageToken,
+        } = await this.googleAds.listResources({
+          accountId,
+          customerClientId,
+          resource,
+          query,
+          pageToken,
+        });
+        const options = results?.map?.((item) => this.getResourceOption(item, resource));
+        return {
+          options,
+          context: {
+            nextPageToken,
+          },
+        };
       },
-      ...(this.dateRange === "CUSTOM" && {
-        startDate: {
-          type: "string",
-          label: "Start Date",
-          description: "The start date, in `YYYY-MM-DD` format",
-        },
-        endDate: {
-          type: "string",
-          label: "End Date",
-          description: "The end date, in `YYYY-MM-DD` format",
-        },
-      }),
-      fields: {
-        type: "string[]",
-        label: "Fields",
-        description: "Select any fields you want to include in your report.",
-        options: resource.fields,
-        optional: true,
-        reloadProps: true,
+    },
+    dateRange: {
+      type: "string",
+      label: "Date Range",
+      description: "Predefined Google Ads date range keyword (e.g. `LAST_30_DAYS`, `THIS_MONTH`). For a custom range, use `CUSTOM` with `startDate` and `endDate` in `YYYY-MM-DD` format (e.g. `2024-01-01`, `2024-01-31`).",
+      options: DATE_RANGE_OPTIONS,
+      optional: true,
+    },
+    startDate: {
+      type: "string",
+      label: "Start Date",
+      description: "The start date in `YYYY-MM-DD` format (e.g. `2024-01-01`). Only relevant if `Date Range` is set to `CUSTOM`.",
+      optional: true,
+    },
+    endDate: {
+      type: "string",
+      label: "End Date",
+      description: "The end date in `YYYY-MM-DD` format (e.g. `2024-01-31`). Only relevant if `Date Range` is set to `CUSTOM`.",
+      optional: true,
+    },
+    fields: {
+      type: "string[]",
+      label: "Fields",
+      description: "Resource field names for the GAQL SELECT clause. Pass a string array (e.g. `[\"id\", \"name\"]` or `[\"campaign.id\", \"campaign.name\"]` for campaign reports).",
+      options() {
+        const resource = RESOURCES.find((r) => r.resourceOption.value === this.resource);
+        if (!resource) throw new ConfigurationError("Select one of the available resources.");
+        return resource.fields;
       },
-      segments: {
-        type: "string[]",
-        label: "Segments",
-        description: "Select any segments you want to include in your report. See the documentation [here](https://developers.google.com/google-ads/api/reference/rpc/v21/Segments)",
-        options: resource.segments,
-        default: [
-          "segments.date",
-        ],
-        optional: true,
-        reloadProps: true,
+      optional: true,
+    },
+    segments: {
+      type: "string[]",
+      label: "Segments",
+      description: "Segment field names to include (e.g. `[\"date\"]` or `[\"segments.date\"]`). See the documentation [here](https://developers.google.com/google-ads/api/reference/rpc/v21/Segments).",
+      options() {
+        const resource = RESOURCES.find((r) => r.resourceOption.value === this.resource);
+        if (!resource) throw new ConfigurationError("Select one of the available resources.");
+        return resource.segments;
       },
-      metrics: {
-        type: "string[]",
-        label: "Metrics",
-        description: "Select any metrics you want to include in your report. See the documentation [here](https://developers.google.com/google-ads/api/reference/rpc/v21/Metrics)",
-        options: resource.metrics,
-        optional: true,
-        reloadProps: true,
+      default: [
+        "segments.date",
+      ],
+      optional: true,
+    },
+    metrics: {
+      type: "string[]",
+      label: "Metrics",
+      description: "Metric field names to include (e.g. `[\"impressions\", \"clicks\"]` or `[\"metrics.impressions\", \"metrics.clicks\"]`). See the documentation [here](https://developers.google.com/google-ads/api/reference/rpc/v21/Metrics).",
+      options() {
+        const resource = RESOURCES.find((r) => r.resourceOption.value === this.resource);
+        if (!resource) throw new ConfigurationError("Select one of the available resources.");
+        return resource.metrics;
       },
-      orderBy: {
-        type: "string",
-        label: "Order By",
-        description: "The field to order the results by",
-        optional: true,
-        options: [
+      optional: true,
+    },
+    orderBy: {
+      type: "string",
+      label: "Order By",
+      description: "The field to order the results by",
+      optional: true,
+      options() {
+        return [
           this.fields,
           this.segments,
           this.metrics,
@@ -147,32 +141,32 @@ export default {
             }
           }
           return returnValue?.map?.((str) => str.trim());
-        }),
+        });
       },
-      direction: {
-        type: "string",
-        label: "Direction",
-        description: "The direction to order the results by, if `Order By` is specified",
-        optional: true,
-        options: [
-          {
-            label: "Ascending",
-            value: "ASC",
-          },
-          {
-            label: "Descending",
-            value: "DESC",
-          },
-        ],
-        default: "ASC",
-      },
-      limit: {
-        type: "integer",
-        label: "Limit",
-        description: "The maximum number of results to return",
-        optional: true,
-      },
-    };
+    },
+    direction: {
+      type: "string",
+      label: "Direction",
+      description: "The direction to order the results by, if `Order By` is specified",
+      optional: true,
+      options: [
+        {
+          label: "Ascending",
+          value: "ASC",
+        },
+        {
+          label: "Descending",
+          value: "DESC",
+        },
+      ],
+      default: "ASC",
+    },
+    limit: {
+      type: "integer",
+      label: "Limit",
+      description: "The maximum number of results to return",
+      optional: true,
+    },
   },
   methods: {
     getResourceOption(item, resource) {
@@ -249,6 +243,14 @@ export default {
     },
   },
   async run({ $ }) {
+    if (!RESOURCES.find((r) => r.resourceOption.value === this.resource)) {
+      throw new ConfigurationError("Select one of the available resources.");
+    }
+
+    if (this.dateRange === "CUSTOM" && (!this.startDate || !this.endDate)) {
+      throw new ConfigurationError("Start and end dates are required if using a custom date range.");
+    }
+
     const query = this.buildQuery();
     const results = (await this.googleAds.createReport({
       $,

package/actions/create-responsive-search-ad/create-responsive-search-ad.mjs

@@ -0,0 +1,202 @@
+import { ConfigurationError } from "@pipedream/platform";
+import googleAds from "../../google_ads.app.mjs";
+import { AD_GROUP_STATUSES } from "../../common/constants.mjs";
+
+const docLink =
+  "https://developers.google.com/google-ads/api/docs/ads/ad-types";
+
+function parseAsset(value) {
+  try {
+    const parsed = JSON.parse(value);
+    if (typeof parsed === "object" && parsed !== null) {
+      if (!parsed.text) {
+        throw new ConfigurationError(
+          `Malformed JSON asset: missing required 'text' field in: \`${value}\``,
+        );
+      }
+      return parsed;
+    }
+  } catch (err) {
+    if (err instanceof ConfigurationError) throw err;
+    // not JSON, treat as plain text
+  }
+  return {
+    text: value,
+  };
+}
+
+export default {
+  key: "google_ads-create-responsive-search-ad",
+  name: "Create Responsive Search Ad",
+  description: `Creates a Responsive Search Ad (RSA) in an ad group. RSA copy (headlines, descriptions) cannot be edited in-place after creation — to change ad copy, remove the existing ad and create a new one. URL fields (\`finalUrls\`, \`trackingUrlTemplate\`, etc.) can be updated in-place via the **Create or Update Ad Group Ad** action. [See the documentation](${docLink})`,
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: false,
+  },
+  props: {
+    googleAds,
+    accountId: {
+      propDefinition: [
+        googleAds,
+        "accountId",
+      ],
+    },
+    customerClientId: {
+      propDefinition: [
+        googleAds,
+        "customerClientId",
+        ({ accountId }) => ({
+          accountId,
+        }),
+      ],
+      optional: true,
+    },
+    adGroupId: {
+      propDefinition: [
+        googleAds,
+        "adGroupId",
+        ({
+          accountId, customerClientId,
+        }) => ({
+          accountId,
+          customerClientId,
+        }),
+      ],
+      description: "The ad group to create this ad in.",
+    },
+    status: {
+      type: "string",
+      label: "Status",
+      description: "The initial status of the ad. Defaults to `ENABLED`.",
+      options: AD_GROUP_STATUSES,
+      optional: true,
+    },
+    headlines: {
+      type: "string[]",
+      label: "Headlines",
+      description: "3–15 headline assets. Each value is either plain text (max 30 characters) or a JSON object to pin to a specific slot: `{\"text\": \"Buy Now\", \"pinnedField\": \"HEADLINE_1\"}`. Valid `pinnedField` values: `HEADLINE_1`, `HEADLINE_2`, `HEADLINE_3`.",
+    },
+    descriptions: {
+      type: "string[]",
+      label: "Descriptions",
+      description: "2–4 description assets. Each value is either plain text (max 90 characters) or a JSON object to pin to a specific slot: `{\"text\": \"Shop today\", \"pinnedField\": \"DESCRIPTION_1\"}`. Valid `pinnedField` values: `DESCRIPTION_1`, `DESCRIPTION_2`.",
+    },
+    finalUrls: {
+      type: "string[]",
+      label: "Final URLs",
+      description: "The landing page URL(s). At least one is required.",
+    },
+    finalMobileUrls: {
+      type: "string[]",
+      label: "Final Mobile URLs",
+      description: "The landing page URL(s) for mobile devices.",
+      optional: true,
+    },
+    trackingUrlTemplate: {
+      type: "string",
+      label: "Tracking URL Template",
+      description: "The URL template for constructing a tracking URL.",
+      optional: true,
+    },
+    finalUrlSuffix: {
+      type: "string",
+      label: "Final URL Suffix",
+      description: "The suffix appended to landing page URLs when serving.",
+      optional: true,
+    },
+  },
+  async run({ $ }) {
+    const {
+      googleAds,
+      accountId,
+      customerClientId,
+      adGroupId,
+      status,
+      headlines,
+      descriptions,
+      finalUrls,
+      finalMobileUrls,
+      trackingUrlTemplate,
+      finalUrlSuffix,
+    } = this;
+
+    if (!headlines || headlines.length < 3) {
+      throw new ConfigurationError(
+        "At least 3 **Headlines** are required for a Responsive Search Ad.",
+      );
+    }
+    if (headlines.length > 15) {
+      throw new ConfigurationError(
+        "A Responsive Search Ad supports a maximum of 15 **Headlines**.",
+      );
+    }
+    if (!descriptions || descriptions.length < 2) {
+      throw new ConfigurationError(
+        "At least 2 **Descriptions** are required for a Responsive Search Ad.",
+      );
+    }
+    if (descriptions.length > 4) {
+      throw new ConfigurationError(
+        "A Responsive Search Ad supports a maximum of 4 **Descriptions**.",
+      );
+    }
+    if (!finalUrls || finalUrls.length === 0) {
+      throw new ConfigurationError(
+        "At least one **Final URL** is required.",
+      );
+    }
+
+    const customerId = customerClientId ?? accountId;
+    const adGroup = `customers/${customerId}/adGroups/${adGroupId}`;
+
+    const operation = {
+      create: {
+        adGroup,
+        ...(status && {
+          status,
+        }),
+        ad: {
+          responsiveSearchAd: {
+            headlines: headlines.map(parseAsset),
+            descriptions: descriptions.map(parseAsset),
+          },
+          finalUrls,
+          ...(finalMobileUrls?.length && {
+            finalMobileUrls,
+          }),
+          ...(trackingUrlTemplate && {
+            trackingUrlTemplate,
+          }),
+          ...(finalUrlSuffix && {
+            finalUrlSuffix,
+          }),
+        },
+      },
+    };
+
+    const response = await googleAds.mutateAdGroupAd({
+      $,
+      accountId,
+      customerClientId,
+      data: {
+        operations: [
+          operation,
+        ],
+      },
+    });
+
+    const result = response?.results?.[0];
+    const id = result?.resourceName?.split("/").pop();
+
+    $.export(
+      "$summary",
+      `Successfully created responsive search ad${id
+        ? ` with ID \`${id}\``
+        : ""}.`,
+    );
+    return response;
+  },
+};

package/actions/generate-keyword-ideas/generate-keyword-ideas.mjs

@@ -9,7 +9,7 @@ export default {
   key: "google_ads-generate-keyword-ideas",
   name: "Generate Keyword Ideas",
   description: `Generate keyword ideas using the Google Ads API. [See the documentation](${docLink})`,
-  version: "0.0.2",
+  version: "0.0.4",
   type: "action",
   annotations: {
     destructiveHint: false,

package/actions/get-keyword-quality-scores/get-keyword-quality-scores.mjs

@@ -0,0 +1,107 @@
+import { ConfigurationError } from "@pipedream/platform";
+import googleAds from "../../google_ads.app.mjs";
+import { DATE_RANGE_OPTIONS } from "../../common/constants.mjs";
+
+const docLink =
+  "https://developers.google.com/google-ads/api/fields/v21/keyword_view";
+
+export default {
+  key: "google_ads-get-keyword-quality-scores",
+  name: "Get Keyword Quality Scores",
+  description: `Retrieves current and historical quality score data (Quality Score, Ad Relevance, Landing Page Experience, Expected CTR) for keywords in a customer account. Current scores reflect the latest evaluation; historical scores are averaged over the selected date range. [See the documentation](${docLink})`,
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  props: {
+    googleAds,
+    accountId: {
+      propDefinition: [
+        googleAds,
+        "accountId",
+      ],
+    },
+    customerClientId: {
+      propDefinition: [
+        googleAds,
+        "customerClientId",
+        ({ accountId }) => ({
+          accountId,
+        }),
+      ],
+      optional: true,
+    },
+    campaignId: {
+      propDefinition: [
+        googleAds,
+        "campaignId",
+        ({
+          accountId, customerClientId,
+        }) => ({
+          accountId,
+          customerClientId,
+        }),
+      ],
+      description: "Filter results to a specific campaign. Use the **List Campaigns** action to discover options.",
+      optional: true,
+    },
+    adGroupId: {
+      propDefinition: [
+        googleAds,
+        "adGroupId",
+        ({
+          accountId, customerClientId,
+        }) => ({
+          accountId,
+          customerClientId,
+        }),
+      ],
+      description: "Filter results to a specific ad group. Use the **List Ad Groups** action to discover options.",
+      optional: true,
+    },
+    dateRange: {
+      type: "string",
+      label: "Date Range",
+      description: "The date range for historical quality score metrics (`metrics.historical_*`). Current quality scores (`quality_info.*`) are always the latest values regardless of this setting.",
+      options: DATE_RANGE_OPTIONS.filter(({ value }) => value !== "CUSTOM"),
+      default: "LAST_30_DAYS",
+      optional: true,
+    },
+  },
+  async run({ $ }) {
+    const {
+      accountId,
+      customerClientId,
+      campaignId,
+      adGroupId,
+      dateRange,
+    } = this;
+
+    if (campaignId && adGroupId) {
+      throw new ConfigurationError(
+        "Specify either **Campaign** or **Ad Group** as a filter, not both.",
+      );
+    }
+
+    const { results } = await this.googleAds.listKeywordQualityScores({
+      $,
+      accountId,
+      customerClientId,
+      campaignId,
+      adGroupId,
+      dateRange,
+    });
+
+    const items = results ?? [];
+    $.export(
+      "$summary",
+      `Successfully retrieved quality scores for ${items.length} keyword${items.length === 1
+        ? ""
+        : "s"}.`,
+    );
+    return items;
+  },
+};

package/actions/list-account-id-options/list-account-id-options.mjs

@@ -4,7 +4,7 @@ export default {
   key: "google_ads-list-account-id-options",
   name: "List Account ID Options",
   description: "Retrieves available options for the Account ID field.",
-  version: "0.0.1",
+  version: "0.0.3",
   type: "action",
   annotations: {
     destructiveHint: false,

package/actions/list-ad-group-ads/list-ad-group-ads.mjs

@@ -0,0 +1,55 @@
+import googleAds from "../../google_ads.app.mjs";
+
+export default {
+  key: "google_ads-list-ad-group-ads",
+  name: "List Ad Group Ads",
+  description: "List ads within ad groups for a customer account. [See the documentation](https://developers.google.com/google-ads/api/reference/rpc/v21/GoogleAdsService/Search?transport=rest)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  props: {
+    googleAds,
+    accountId: {
+      propDefinition: [
+        googleAds,
+        "accountId",
+      ],
+    },
+    customerClientId: {
+      propDefinition: [
+        googleAds,
+        "customerClientId",
+        ({ accountId }) => ({
+          accountId,
+        }),
+      ],
+      optional: true,
+    },
+    query: {
+      type: "string",
+      label: "Query",
+      description: "Filter ads by name (partial match).",
+      optional: true,
+    },
+  },
+  async run({ $ }) {
+    const { results } = await this.googleAds.listAllAdGroupAds({
+      $,
+      accountId: this.accountId,
+      customerClientId: this.customerClientId,
+      query: this.query,
+    });
+    const ads = results ?? [];
+    $.export(
+      "$summary",
+      `Successfully retrieved ${ads.length} ad group ad${ads.length === 1
+        ? ""
+        : "s"}.`,
+    );
+    return ads;
+  },
+};