@pipedream/google_ads 0.7.0 → 1.0.0

package/actions/create-or-update-keywords/create-or-update-keywords.mjs

@@ -0,0 +1,275 @@
+import { ConfigurationError } from "@pipedream/platform";
+import googleAds from "../../google_ads.app.mjs";
+import {
+  AD_GROUP_STATUSES,
+  CAMPAIGN_OPERATION_TYPES,
+  KEYWORD_MATCH_TYPES,
+} from "../../common/constants.mjs";
+import { parseObject } from "../../common/utils.mjs";
+import { getAdditionalFields } from "../common/props.mjs";
+
+const docLink =
+  "https://developers.google.com/google-ads/api/reference/rpc/v25/AdGroupCriterionService/MutateAdGroupCriteria?transport=rest";
+
+export default {
+  key: "google_ads-create-or-update-keywords",
+  name: "Create, Update, or Remove Keywords",
+  description: `Creates, updates, or removes keyword criteria for an ad group. [See the documentation](${docLink})`,
+  version: "0.0.2",
+  type: "action",
+  annotations: {
+    destructiveHint: true,
+    openWorldHint: true,
+    readOnlyHint: false,
+  },
+  props: {
+    googleAds,
+    accountId: {
+      propDefinition: [
+        googleAds,
+        "accountId",
+      ],
+    },
+    customerClientId: {
+      propDefinition: [
+        googleAds,
+        "customerClientId",
+        ({ accountId }) => ({
+          accountId,
+        }),
+      ],
+      optional: true,
+    },
+    operationType: {
+      type: "string",
+      label: "Operation Type",
+      description: "Whether to create, update, or remove a keyword.",
+      options: CAMPAIGN_OPERATION_TYPES,
+    },
+    adGroupCriterionId: {
+      propDefinition: [
+        googleAds,
+        "adGroupCriterionId",
+        ({
+          accountId, customerClientId,
+        }) => ({
+          accountId,
+          customerClientId,
+        }),
+      ],
+      description: "The keyword to update or remove. Required for **Update** and **Remove** operations.",
+      optional: true,
+    },
+    adGroupId: {
+      propDefinition: [
+        googleAds,
+        "adGroupId",
+        ({
+          accountId, customerClientId,
+        }) => ({
+          accountId,
+          customerClientId,
+        }),
+      ],
+      description: "The ad group this keyword belongs to. Required for **Create** operations.",
+      optional: true,
+    },
+    updateMask: {
+      type: "string",
+      label: "Update Mask",
+      description: "Comma-separated list of fields to update (e.g., `status,cpcBidMicros`). Required for **Update** operations.",
+      optional: true,
+    },
+    keywordText: {
+      type: "string",
+      label: "Keyword Text",
+      description: "The keyword text (max 80 characters, max 10 words). Required for **Create** operations.",
+      optional: true,
+    },
+    keywordMatchType: {
+      type: "string",
+      label: "Keyword Match Type",
+      description: "The match type for the keyword. Required for **Create** operations.",
+      options: KEYWORD_MATCH_TYPES,
+      optional: true,
+    },
+    negative: {
+      type: "boolean",
+      label: "Negative Keyword",
+      description: "Whether this is a negative keyword. Immutable after creation.",
+      optional: true,
+    },
+    status: {
+      type: "string",
+      label: "Status",
+      description: "The status of the keyword criterion.",
+      options: AD_GROUP_STATUSES,
+      optional: true,
+    },
+    cpcBidMicros: {
+      type: "integer",
+      label: "CPC Bid (Micros)",
+      description: "The maximum CPC (cost-per-click) bid in micros (e.g., `1000000` = $1.00).",
+      optional: true,
+    },
+    trackingUrlTemplate: {
+      type: "string",
+      label: "Tracking URL Template",
+      description: "The URL template for constructing a tracking URL.",
+      optional: true,
+    },
+    finalUrls: {
+      type: "string[]",
+      label: "Final URLs",
+      description: "The list of final URLs for the keyword.",
+      optional: true,
+    },
+    finalMobileUrls: {
+      type: "string[]",
+      label: "Final Mobile URLs",
+      description: "The list of final mobile URLs for the keyword.",
+      optional: true,
+    },
+    finalUrlSuffix: {
+      type: "string",
+      label: "Final URL Suffix",
+      description: "The suffix used to append query parameters to landing page URLs.",
+      optional: true,
+    },
+    additionalFields: getAdditionalFields(docLink),
+  },
+  async run({ $ }) {
+    const {
+      googleAds,
+      accountId,
+      customerClientId,
+      operationType,
+      adGroupCriterionId,
+      adGroupId,
+      updateMask,
+      keywordText,
+      keywordMatchType,
+      negative,
+      status,
+      cpcBidMicros,
+      trackingUrlTemplate,
+      finalUrls,
+      finalMobileUrls,
+      finalUrlSuffix,
+      additionalFields,
+    } = this;
+
+    if ((operationType === "update" || operationType === "remove") && !adGroupCriterionId) {
+      throw new ConfigurationError(
+        "**Keyword** is required for Update and Remove operations.",
+      );
+    }
+
+    if (operationType === "update" && !updateMask) {
+      throw new ConfigurationError(
+        "**Update Mask** is required for Update operations.",
+      );
+    }
+
+    if (operationType === "create") {
+      if (!adGroupId) {
+        throw new ConfigurationError(
+          "**Ad Group** is required for Create operations.",
+        );
+      }
+      if (!keywordText) {
+        throw new ConfigurationError(
+          "**Keyword Text** is required for Create operations.",
+        );
+      }
+      if (!keywordMatchType) {
+        throw new ConfigurationError(
+          "**Keyword Match Type** is required for Create operations.",
+        );
+      }
+    }
+
+    const customerId = customerClientId ?? accountId;
+    const adGroup = adGroupId
+      ? `customers/${customerId}/adGroups/${adGroupId}`
+      : undefined;
+
+    let operation;
+
+    if (operationType === "remove") {
+      operation = {
+        remove: adGroupCriterionId,
+      };
+    } else {
+      const criterionData = {
+        ...(adGroupCriterionId && {
+          resourceName: adGroupCriterionId,
+        }),
+        ...(adGroup && {
+          adGroup,
+        }),
+        ...(keywordText && keywordMatchType && {
+          keyword: {
+            text: keywordText,
+            matchType: keywordMatchType,
+          },
+        }),
+        ...(negative !== undefined && {
+          negative,
+        }),
+        ...(status && {
+          status,
+        }),
+        ...(cpcBidMicros !== undefined && {
+          cpcBidMicros,
+        }),
+        ...(trackingUrlTemplate && {
+          trackingUrlTemplate,
+        }),
+        ...(finalUrls?.length && {
+          finalUrls,
+        }),
+        ...(finalMobileUrls?.length && {
+          finalMobileUrls,
+        }),
+        ...(finalUrlSuffix && {
+          finalUrlSuffix,
+        }),
+        ...parseObject(additionalFields),
+      };
+
+      if (operationType === "update") {
+        operation = {
+          update: criterionData,
+          updateMask,
+        };
+      } else {
+        operation = {
+          create: criterionData,
+        };
+      }
+    }
+
+    const response = await googleAds.mutateAdGroupCriteria({
+      $,
+      accountId,
+      customerClientId,
+      data: {
+        operations: [
+          operation,
+        ],
+      },
+    });
+
+    const result = response?.results?.[0];
+    const id = result?.resourceName?.split("~").pop();
+
+    $.export(
+      "$summary",
+      `Successfully ${operationType}d keyword${id
+        ? ` with criterion ID \`${id}\``
+        : ""}.`,
+    );
+    return response;
+  },
+};

package/actions/create-or-update-shared-sets/create-or-update-shared-sets.mjs

@@ -0,0 +1,180 @@
+import { ConfigurationError } from "@pipedream/platform";
+import googleAds from "../../google_ads.app.mjs";
+import {
+  CAMPAIGN_OPERATION_TYPES,
+  SHARED_SET_TYPES,
+} from "../../common/constants.mjs";
+import { parseObject } from "../../common/utils.mjs";
+import { getAdditionalFields } from "../common/props.mjs";
+
+const docLink =
+  "https://developers.google.com/google-ads/api/reference/rpc/v25/SharedSetService/MutateSharedSets?transport=rest";
+
+export default {
+  key: "google_ads-create-or-update-shared-sets",
+  name: "Create or Update Shared Sets",
+  description: `Creates or updates shared sets (reusable lists of negative keywords or placements). [See the documentation](${docLink})`,
+  version: "0.0.2",
+  type: "action",
+  annotations: {
+    destructiveHint: true,
+    openWorldHint: true,
+    readOnlyHint: false,
+  },
+  props: {
+    googleAds,
+    accountId: {
+      propDefinition: [
+        googleAds,
+        "accountId",
+      ],
+    },
+    customerClientId: {
+      propDefinition: [
+        googleAds,
+        "customerClientId",
+        ({ accountId }) => ({
+          accountId,
+        }),
+      ],
+      optional: true,
+    },
+    operationType: {
+      type: "string",
+      label: "Operation Type",
+      description: "Whether to create, update, or remove a shared set.",
+      options: CAMPAIGN_OPERATION_TYPES,
+    },
+    sharedSetId: {
+      propDefinition: [
+        googleAds,
+        "sharedSetId",
+        ({
+          accountId, customerClientId,
+        }) => ({
+          accountId,
+          customerClientId,
+        }),
+      ],
+      description: "The shared set to update or remove. Required for **Update** and **Remove** operations.",
+      optional: true,
+    },
+    updateMask: {
+      type: "string",
+      label: "Update Mask",
+      description: "Comma-separated list of fields to update (e.g., `name`). Required for **Update** operations.",
+      optional: true,
+    },
+    name: {
+      type: "string",
+      label: "Name",
+      description: "The name of the shared set. Required for **Create** operations.",
+      optional: true,
+    },
+    type: {
+      type: "string",
+      label: "Type",
+      description: "The type of the shared set. Required for **Create** operations. Immutable after creation.",
+      options: SHARED_SET_TYPES,
+      optional: true,
+    },
+    additionalFields: getAdditionalFields(docLink),
+  },
+  async run({ $ }) {
+    const {
+      googleAds,
+      accountId,
+      customerClientId,
+      operationType,
+      sharedSetId,
+      updateMask,
+      name,
+      type,
+      additionalFields,
+    } = this;
+
+    if ((operationType === "update" || operationType === "remove") && !sharedSetId) {
+      throw new ConfigurationError(
+        "**Shared Set** is required for Update and Remove operations.",
+      );
+    }
+
+    if (operationType === "update" && !updateMask) {
+      throw new ConfigurationError(
+        "**Update Mask** is required for Update operations.",
+      );
+    }
+
+    if (operationType === "create") {
+      if (!name) {
+        throw new ConfigurationError(
+          "**Name** is required for Create operations.",
+        );
+      }
+      if (!type) {
+        throw new ConfigurationError(
+          "**Type** is required for Create operations.",
+        );
+      }
+    }
+
+    const customerId = customerClientId ?? accountId;
+    const resourceName = sharedSetId
+      ? `customers/${customerId}/sharedSets/${sharedSetId}`
+      : undefined;
+
+    let operation;
+
+    if (operationType === "remove") {
+      operation = {
+        remove: resourceName,
+      };
+    } else {
+      const sharedSetData = {
+        ...(resourceName && {
+          resourceName,
+        }),
+        ...(name && {
+          name,
+        }),
+        ...(type && {
+          type,
+        }),
+        ...parseObject(additionalFields),
+      };
+
+      if (operationType === "update") {
+        operation = {
+          update: sharedSetData,
+          updateMask,
+        };
+      } else {
+        operation = {
+          create: sharedSetData,
+        };
+      }
+    }
+
+    const response = await googleAds.mutateSharedSets({
+      $,
+      accountId,
+      customerClientId,
+      data: {
+        operations: [
+          operation,
+        ],
+      },
+    });
+
+    const result = response?.results?.[0];
+    const id = result?.resourceName?.split("/").pop();
+
+    $.export(
+      "$summary",
+      `Successfully ${operationType}d shared set${id
+        ? ` with ID \`${id}\``
+        : ""}.`,
+    );
+    return response;
+  },
+};

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

@@ -19,8 +19,8 @@ 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.2.0",
+  description: "Generates a report from your Google Ads data. [See the documentation](https://developers.google.com/google-ads/api/reference/rpc/v25/GoogleAdsService/Search?transport=rest)",
+  version: "0.3.0",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,
@@ -99,7 +99,7 @@ export default {
     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).",
+      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/v25/Segments).",
       options() {
         const resource = RESOURCES.find((r) => r.resourceOption.value === this.resource);
         if (!resource) throw new ConfigurationError("Select one of the available resources.");
@@ -113,7 +113,7 @@ export default {
     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).",
+      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/v25/Metrics).",
       options() {
         const resource = RESOURCES.find((r) => r.resourceOption.value === this.resource);
         if (!resource) throw new ConfigurationError("Select one of the available resources.");
@@ -256,9 +256,7 @@ export default {
       $,
       accountId: this.accountId,
       customerClientId: this.customerClientId,
-      data: {
-        query,
-      },
+      query,
     })) ?? [];
 
     const { length } = results;

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.2",
+  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;
+  },
+};