@pipedream/google_ads 0.4.0 → 0.6.0

package/README.md

@@ -21,7 +21,7 @@ campaigns, such as campaign stats, keyword stats, and ad performance.
 
 ## Customizing API requests from within the Pipedream workflow builder
 
-The Pipedream components interact with Google Ads API through an interal proxy service, which protects Pipedream's developer token.
+The Pipedream components interact with Google Ads API through an internal proxy service, which protects Pipedream's developer token.
 
 The component accepts a standard Google Ads API request object with the following structure:
 

package/actions/add-contact-to-list-by-email/add-contact-to-list-by-email.mjs

@@ -7,7 +7,7 @@ export default {
   key: "google_ads-add-contact-to-list-by-email",
   name: "Add Contact to Customer List by Email",
   description: "Adds a contact to a specific customer list in Google Ads. Lists typically update in 6 to 12 hours after operation. [See the documentation](https://developers.google.com/google-ads/api/docs/remarketing/audience-segments/customer-match/get-started)",
-  version: "0.1.6",
+  version: "0.1.7",
   annotations: {
     destructiveHint: true,
     openWorldHint: true,

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

@@ -0,0 +1,16 @@
+import { adGroup } from "../../common/resources/adGroup.mjs";
+import { createReportComponent } from "../../common/common-report.mjs";
+
+export default {
+  ...createReportComponent(adGroup),
+  key: "google_ads-create-ad-group-report",
+  name: "Create Ad Group Report",
+  description: "Creates a report for the Ad Group resource. [See the documentation](https://developers.google.com/google-ads/api/reference/rpc/v21/GoogleAdsService/Search?transport=rest)",
+  version: "0.0.1",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  type: "action",
+};

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

@@ -0,0 +1,16 @@
+import { ad } from "../../common/resources/ad.mjs";
+import { createReportComponent } from "../../common/common-report.mjs";
+
+export default {
+  ...createReportComponent(ad),
+  key: "google_ads-create-ad-report",
+  name: "Create Ad Report",
+  description: "Creates a report for the Ad resource. [See the documentation](https://developers.google.com/google-ads/api/reference/rpc/v21/GoogleAdsService/Search?transport=rest)",
+  version: "0.0.1",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  type: "action",
+};

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

@@ -0,0 +1,16 @@
+import { campaign } from "../../common/resources/campaign.mjs";
+import { createReportComponent } from "../../common/common-report.mjs";
+
+export default {
+  ...createReportComponent(campaign),
+  key: "google_ads-create-campaign-report",
+  name: "Create Campaign Report",
+  description: "Creates a report for the Campaign resource. [See the documentation](https://developers.google.com/google-ads/api/reference/rpc/v21/GoogleAdsService/Search?transport=rest)",
+  version: "0.0.1",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  type: "action",
+};

package/actions/create-customer-list/create-customer-list.mjs

@@ -15,7 +15,7 @@ export default {
   key: "google_ads-create-customer-list",
   name: "Create Customer List",
   description: "Create a new customer list in Google Ads. [See the documentation](https://developers.google.com/google-ads/api/reference/rpc/v21/UserList)",
-  version: "0.0.7",
+  version: "0.0.8",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

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

@@ -0,0 +1,16 @@
+import { customer } from "../../common/resources/customer.mjs";
+import { createReportComponent } from "../../common/common-report.mjs";
+
+export default {
+  ...createReportComponent(customer),
+  key: "google_ads-create-customer-report",
+  name: "Create Customer Report",
+  description: "Creates a report for the Customer resource. [See the documentation](https://developers.google.com/google-ads/api/reference/rpc/v21/GoogleAdsService/Search?transport=rest)",
+  version: "0.0.1",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  type: "action",
+};

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

@@ -4,7 +4,7 @@ import { ad } from "../../common/resources/ad.mjs";
 import { campaign } from "../../common/resources/campaign.mjs";
 import { customer } from "../../common/resources/customer.mjs";
 import { ConfigurationError } from "@pipedream/platform";
-import { DATE_RANGE_OPTIONS } from "./common-constants.mjs";
+import { DATE_RANGE_OPTIONS } from "../../common/constants.mjs";
 import { checkPrefix } from "../../common/utils.mjs";
 
 const RESOURCES = [
@@ -14,16 +14,17 @@ const RESOURCES = [
   customer,
 ];
 
+// Action kept for backwards compatibility - prefer the individual resource-specific actions
 export default {
   ...common,
   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.5",
+  version: "0.1.6",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,
-    readOnlyHint: false,
+    readOnlyHint: true,
   },
   type: "action",
   props: {

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.1",
+  version: "0.0.2",
   type: "action",
   annotations: {
     destructiveHint: false,

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

@@ -0,0 +1,24 @@
+import google_ads from "../../google_ads.app.mjs";
+
+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",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  props: {
+    google_ads,
+  },
+  async run({ $ }) {
+    const options = await google_ads.propDefinitions.accountId.options.call(this.google_ads);
+    $.export("$summary", `Successfully retrieved ${options.length} option${options.length === 1
+      ? ""
+      : "s"}`);
+    return options;
+  },
+};

package/actions/send-offline-conversion/send-offline-conversion.mjs

@@ -8,7 +8,7 @@ export default {
   key: "google_ads-send-offline-conversion",
   name: "Send Offline Conversion",
   description: "Send an event to Google Ads to track offline conversions. [See the documentation](https://developers.google.com/google-ads/api/reference/rpc/v21/ConversionAction)",
-  version: "0.0.7",
+  version: "0.0.8",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

package/common/common-report.mjs

@@ -0,0 +1,193 @@
+import { ConfigurationError } from "@pipedream/platform";
+import googleAds from "../google_ads.app.mjs";
+import props from "./props.mjs";
+import {
+  CORE_DATE_SEGMENTS, DATE_RANGE_OPTIONS,
+} from "./constants.mjs";
+import { checkPrefix } from "./utils.mjs";
+
+export function createReportComponent(resource) {
+  const {
+    label, value,
+  } = resource.resourceOption;
+
+  return {
+    props: {
+      ...props,
+      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: {
+        propDefinition: [
+          googleAds,
+          "reportResourceFilter",
+          ({
+            accountId, customerClientId,
+          }) => ({
+            accountId,
+            customerClientId,
+            resource: value,
+          }),
+        ],
+        label: `${label}(s)`,
+        description: `Select the ${label}(s) to generate a report for (or leave blank for all ${label}s)`,
+      },
+      dateRange: {
+        type: "string",
+        label: "Date Range",
+        description: "Select a date range for the report",
+        options: DATE_RANGE_OPTIONS,
+        optional: true,
+      },
+      startDate: {
+        type: "string",
+        label: "Custom Start Date",
+        description: "If using a custom date range, this is the start date in `YYYY-MM-DD` format",
+        optional: true,
+      },
+      endDate: {
+        type: "string",
+        label: "Custom End Date",
+        description: "If using a custom date range, this is the end date in `YYYY-MM-DD` format",
+        optional: true,
+      },
+      fields: {
+        type: "string[]",
+        label: `${label} Fields`,
+        description: `Select the ${label} fields to include in the report`,
+        options: resource.fields,
+        optional: true,
+      },
+      segments: {
+        type: "string[]",
+        label: "Segments",
+        description: "Select any segments to include in the report. See the documentation [here](https://developers.google.com/google-ads/api/reference/rpc/v21/Segments)",
+        options: resource.segments,
+        default: [
+          "segments.date",
+        ],
+        optional: true,
+      },
+      metrics: {
+        type: "string[]",
+        label: "Metrics",
+        description: "Select any metrics to include in the report. See the documentation [here](https://developers.google.com/google-ads/api/reference/rpc/v21/Metrics)",
+        options: resource.metrics,
+        optional: true,
+      },
+      orderBy: {
+        propDefinition: [
+          googleAds,
+          "reportOrderBy",
+          ({
+            fields, segments, metrics, dateRange,
+          }) => ({
+            fields,
+            segments,
+            metrics,
+            dateRange,
+          }),
+        ],
+      },
+      direction: {
+        type: "string",
+        label: "Direction",
+        description: "If **Order By** is specified, this is the direction to order the results by",
+        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: {
+      buildQuery() {
+        const {
+          fields, segments, metrics, limit, orderBy, direction, objectFilter, dateRange,
+        } = this;
+
+        const filteredSegments = dateRange
+          ? segments
+          : segments?.filter((s) => !CORE_DATE_SEGMENTS.includes(s));
+
+        const selection = [
+          ...checkPrefix(fields, value),
+          ...checkPrefix(filteredSegments, "segments"),
+          ...checkPrefix(metrics, "metrics"),
+        ];
+
+        if (!selection.length) {
+          throw new ConfigurationError("Select at least one field, segment or metric.");
+        }
+
+        if (dateRange === "CUSTOM" && (!this.startDate || !this.endDate)) {
+          throw new ConfigurationError("Both **Custom Start Date** and **Custom End Date** are required when using a custom date range.");
+        }
+
+        if (!dateRange && orderBy && CORE_DATE_SEGMENTS.includes(orderBy)) {
+          throw new ConfigurationError(`Cannot order by "${orderBy}" without a date range. Either select a **Date Range** or choose a different **Order By** field.`);
+        }
+
+        let query = `SELECT ${selection.join(", ")} FROM ${value}`;
+        if (objectFilter?.length) {
+          query += ` WHERE ${value === "ad_group_ad"
+            ? "ad_group_ad.ad"
+            : value}.id IN (${objectFilter.join?.(", ") ?? objectFilter})`;
+        }
+        if (dateRange) {
+          const dateClause = dateRange === "CUSTOM"
+            ? `BETWEEN '${this.startDate}' AND '${this.endDate}'`
+            : `DURING ${dateRange}`;
+          query += ` ${objectFilter
+            ? "AND"
+            : "WHERE"} segments.date ${dateClause}`;
+        }
+
+        if (orderBy && direction) {
+          query += ` ORDER BY ${orderBy} ${direction}`;
+        }
+        if (limit) {
+          query += ` LIMIT ${limit}`;
+        }
+
+        return query;
+      },
+    },
+    async run({ $ }) {
+      const query = this.buildQuery();
+      const results = (await this.googleAds.createReport({
+        $,
+        accountId: this.accountId,
+        customerClientId: this.customerClientId,
+        data: {
+          query,
+        },
+      })) ?? [];
+
+      const { length } = results;
+
+      $.export("$summary", `Successfully obtained ${length} result${length === 1
+        ? ""
+        : "s"}`);
+      return {
+        query,
+        results,
+      };
+    },
+  };
+}

package/{actions/create-report/common-constants.mjs → common/constants.mjs}

@@ -1,3 +1,11 @@
+export const CORE_DATE_SEGMENTS = [
+  "segments.date",
+  "segments.week",
+  "segments.month",
+  "segments.quarter",
+  "segments.year",
+];
+
 export const DATE_RANGE_OPTIONS = [
   {
     value: "CUSTOM",

package/common/utils.mjs

@@ -38,6 +38,36 @@ export function getOption(label, prefix) {
   };
 }
 
+export function getResourceOption(item, resource) {
+  let label, value;
+  switch (resource) {
+  case "campaign":
+    label = item.campaign.name;
+    value = item.campaign.id;
+    break;
+
+  case "customer":
+    label = item.customer.descriptiveName;
+    value = item.customer.id;
+    break;
+
+  case "ad_group":
+    label = item.adGroup.name;
+    value = item.adGroup.id;
+    break;
+
+  case "ad_group_ad":
+    label = item.adGroupAd.ad.name;
+    value = item.adGroupAd.ad.id;
+    break;
+  }
+
+  return {
+    label,
+    value,
+  };
+}
+
 export function checkPrefix(value, prefix) {
   const checkStr = (s) => s && (s?.startsWith?.(prefix)
     ? s

package/google_ads.app.mjs

@@ -1,5 +1,7 @@
 import { axios } from "@pipedream/platform";
+import { CORE_DATE_SEGMENTS } from "./common/constants.mjs";
 import { QUERIES } from "./common/queries.mjs";
+import { getResourceOption } from "./common/utils.mjs";
 
 export default {
   type: "app",
@@ -68,6 +70,60 @@ export default {
         })).filter(({ value }) => value !== accountId);
       },
     },
+    reportResourceFilter: {
+      type: "string[]",
+      label: "Filter by Resources",
+      description: "Select the resources to generate a report for (or leave blank for all)",
+      optional: true,
+      useQuery: true,
+      async options({
+        accountId, customerClientId, resource, query, prevContext,
+      }) {
+        const pageToken = prevContext?.nextPageToken;
+        const {
+          results, nextPageToken,
+        } = await this.listResources({
+          accountId,
+          customerClientId,
+          resource,
+          query,
+          pageToken,
+        });
+        const options = results?.map?.((item) => this.getResourceOption(item, resource));
+        return {
+          options,
+          context: {
+            nextPageToken,
+          },
+        };
+      },
+    },
+    reportOrderBy: {
+      type: "string",
+      label: "Order By",
+      description: "The field to order the results by",
+      optional: true,
+      options({
+        fields, segments, metrics, dateRange,
+      }) {
+        return [
+          fields,
+          segments,
+          metrics,
+        ].filter((v) => v).flatMap((value) => {
+          let returnValue = value;
+          if (typeof value === "string") {
+            try {
+              returnValue = JSON.parse(value);
+            } catch (err) {
+              returnValue = value.split(",");
+            }
+          }
+          return returnValue?.map?.((str) => str.trim());
+        })
+          .filter((v) => dateRange || !CORE_DATE_SEGMENTS.includes(v));
+      },
+    },
     leadFormId: {
       type: "string",
       label: "Lead Form ID",
@@ -93,6 +149,7 @@ export default {
     },
   },
   methods: {
+    getResourceOption,
     _baseUrl() {
       return "https://googleads.m.pipedream.net";
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipedream/google_ads",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Pipedream Google Ads Components",
   "main": "google_ads.app.mjs",
   "keywords": [

package/sources/new-campaign-created/new-campaign-created.mjs

@@ -7,7 +7,7 @@ export default {
   key: "google_ads-new-campaign-created",
   name: "New Campaign Created",
   description: "Emit new event when a new campaign is created. [See the documentation](https://developers.google.com/google-ads/api/reference/rpc/v21/GoogleAdsService/Search?transport=rest)",
-  version: "0.0.6",
+  version: "0.0.7",
   type: "source",
   dedupe: "unique",
   sampleEmit,

package/sources/new-lead-form-entry/new-lead-form-entry.mjs

@@ -8,7 +8,7 @@ export default {
   key: "google_ads-new-lead-form-entry",
   name: "New Lead Form Entry",
   description: "Emit new event for new leads on a Lead Form. [See the documentation](https://developers.google.com/google-ads/api/reference/rpc/v21/GoogleAdsService/Search?transport=rest)",
-  version: "0.0.6",
+  version: "0.0.7",
   type: "source",
   dedupe: "unique",
   sampleEmit,