@pipedream/google_ads 0.7.0 → 1.0.0

package/actions/create-or-update-ad-group/create-or-update-ad-group.mjs

@@ -0,0 +1,315 @@
+import { ConfigurationError } from "@pipedream/platform";
+import googleAds from "../../google_ads.app.mjs";
+import {
+  AD_GROUP_STATUSES,
+  AD_GROUP_TYPES,
+  AD_ROTATION_MODES,
+  CAMPAIGN_OPERATION_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/AdGroupService/MutateAdGroups?transport=rest";
+
+export default {
+  key: "google_ads-create-or-update-ad-group",
+  name: "Create or Update Ad Group",
+  description: `Creates or updates an ad group. [See the documentation](${docLink})`,
+  version: "0.1.0",
+  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 an ad group.",
+      options: CAMPAIGN_OPERATION_TYPES,
+    },
+    adGroupId: {
+      propDefinition: [
+        googleAds,
+        "adGroupId",
+        ({
+          accountId, customerClientId,
+        }) => ({
+          accountId,
+          customerClientId,
+        }),
+      ],
+      description: "The ad group to update or remove. Required for **Update** and **Remove** operations.",
+      optional: true,
+    },
+    campaignId: {
+      propDefinition: [
+        googleAds,
+        "campaignId",
+        ({
+          accountId, customerClientId,
+        }) => ({
+          accountId,
+          customerClientId,
+        }),
+      ],
+      description: "The campaign this ad group belongs to. Required for **Create** operations.",
+      optional: true,
+    },
+    updateMask: {
+      type: "string",
+      label: "Update Mask",
+      description: "Comma-separated list of fields to update (e.g., `name,status`). Required for **Update** operations.",
+      optional: true,
+    },
+    name: {
+      type: "string",
+      label: "Name",
+      description: "The name of the ad group. Required for **Create** operations.",
+      optional: true,
+    },
+    type: {
+      type: "string",
+      label: "Type",
+      description: "The type of the ad group. Immutable after creation — only used for **Create** operations.",
+      options: AD_GROUP_TYPES,
+      optional: true,
+    },
+    status: {
+      type: "string",
+      label: "Status",
+      description: "The status of the ad group.",
+      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,
+    },
+    cpmBidMicros: {
+      type: "integer",
+      label: "CPM Bid (Micros)",
+      description: "The maximum CPM (cost-per-thousand impressions) bid in micros.",
+      optional: true,
+    },
+    cpvBidMicros: {
+      type: "integer",
+      label: "CPV Bid (Micros)",
+      description: "The maximum CPV (cost-per-view) bid in micros.",
+      optional: true,
+    },
+    targetCpaMicros: {
+      type: "integer",
+      label: "Target CPA (Micros)",
+      description: "The target CPA (cost-per-acquisition) in micros.",
+      optional: true,
+    },
+    targetCpmMicros: {
+      type: "integer",
+      label: "Target CPM (Micros)",
+      description: "The target CPM (cost-per-thousand impressions) in micros.",
+      optional: true,
+    },
+    targetRoas: {
+      type: "string",
+      label: "Target ROAS",
+      description: "The target ROAS (return on ad spend) as a decimal (e.g., `3.5` for 350%).",
+      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 used to append query parameters to landing page URLs.",
+      optional: true,
+    },
+    adRotationMode: {
+      type: "string",
+      label: "Ad Rotation Mode",
+      description: "How ads within the ad group are served relative to one another.",
+      options: AD_ROTATION_MODES,
+      optional: true,
+    },
+    additionalFields: getAdditionalFields(docLink),
+  },
+  async run({ $ }) {
+    const {
+      googleAds,
+      accountId,
+      customerClientId,
+      operationType,
+      adGroupId,
+      campaignId,
+      updateMask,
+      name,
+      type,
+      status,
+      cpcBidMicros,
+      cpmBidMicros,
+      cpvBidMicros,
+      targetCpaMicros,
+      targetCpmMicros,
+      targetRoas,
+      trackingUrlTemplate,
+      finalUrlSuffix,
+      adRotationMode,
+      additionalFields,
+    } = this;
+
+    if ((operationType === "update" || operationType === "remove") && !adGroupId) {
+      throw new ConfigurationError(
+        "**Ad Group** 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 (!campaignId) {
+        throw new ConfigurationError(
+          "**Campaign** is required for Create operations.",
+        );
+      }
+    }
+
+    const customerId = customerClientId ?? accountId;
+    const resourceName = adGroupId
+      ? `customers/${customerId}/adGroups/${adGroupId}`
+      : undefined;
+    const campaign = campaignId
+      ? `customers/${customerId}/campaigns/${campaignId}`
+      : undefined;
+
+    let parsedTargetRoas;
+    if (targetRoas !== undefined) {
+      parsedTargetRoas = parseFloat(targetRoas);
+      if (!Number.isFinite(parsedTargetRoas)) {
+        throw new ConfigurationError(
+          `**Target ROAS** must be a valid decimal number (e.g., \`3.5\`), got: \`${targetRoas}\`.`,
+        );
+      }
+    }
+
+    let operation;
+
+    if (operationType === "remove") {
+      operation = {
+        remove: resourceName,
+      };
+    } else {
+      const adGroupData = {
+        ...(resourceName && {
+          resourceName,
+        }),
+        ...(campaign && {
+          campaign,
+        }),
+        ...(name && {
+          name,
+        }),
+        ...(type && {
+          type,
+        }),
+        ...(status && {
+          status,
+        }),
+        ...(cpcBidMicros !== undefined && {
+          cpcBidMicros,
+        }),
+        ...(cpmBidMicros !== undefined && {
+          cpmBidMicros,
+        }),
+        ...(cpvBidMicros !== undefined && {
+          cpvBidMicros,
+        }),
+        ...(targetCpaMicros !== undefined && {
+          targetCpaMicros,
+        }),
+        ...(targetCpmMicros !== undefined && {
+          targetCpmMicros,
+        }),
+        ...(parsedTargetRoas !== undefined && {
+          targetRoas: parsedTargetRoas,
+        }),
+        ...(trackingUrlTemplate && {
+          trackingUrlTemplate,
+        }),
+        ...(finalUrlSuffix && {
+          finalUrlSuffix,
+        }),
+        ...(adRotationMode && {
+          adRotationMode,
+        }),
+        ...parseObject(additionalFields),
+      };
+
+      if (operationType === "update") {
+        operation = {
+          update: adGroupData,
+          updateMask,
+        };
+      } else {
+        operation = {
+          create: adGroupData,
+        };
+      }
+    }
+
+    const response = await googleAds.mutateAdGroup({
+      $,
+      accountId,
+      customerClientId,
+      data: {
+        operations: [
+          operation,
+        ],
+      },
+    });
+
+    const result = response?.results?.[0];
+    const id = result?.resourceName?.split("/").pop();
+
+    $.export(
+      "$summary",
+      `Successfully ${operationType}d ad group${id
+        ? ` with ID \`${id}\``
+        : ""}.`,
+    );
+    return response;
+  },
+};

package/actions/create-or-update-ad-group-ad/create-or-update-ad-group-ad.mjs

@@ -0,0 +1,203 @@
+import { ConfigurationError } from "@pipedream/platform";
+import googleAds from "../../google_ads.app.mjs";
+import {
+  AD_GROUP_STATUSES, CAMPAIGN_OPERATION_TYPES,
+} from "../../common/constants.mjs";
+import {
+  parseObject, parseStringObject,
+} from "../../common/utils.mjs";
+import { getAdditionalFields } from "../common/props.mjs";
+
+const docLink =
+  "https://developers.google.com/google-ads/api/reference/rpc/v25/AdGroupAdService/MutateAdGroupAds?transport=rest";
+
+export default {
+  key: "google_ads-create-or-update-ad-group-ad",
+  name: "Create, Update, or Remove Ad Group Ad",
+  description: `Creates, updates, or removes an ad group ad. [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 an ad group ad.",
+      options: CAMPAIGN_OPERATION_TYPES,
+    },
+    adGroupAdId: {
+      propDefinition: [
+        googleAds,
+        "adGroupAdId",
+        ({
+          accountId, customerClientId,
+        }) => ({
+          accountId,
+          customerClientId,
+        }),
+      ],
+      description: "The ad 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 ad 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,ad.finalUrls`). Required for **Update** operations.",
+      optional: true,
+    },
+    status: {
+      type: "string",
+      label: "Status",
+      description: "The status of the ad group ad.",
+      options: AD_GROUP_STATUSES,
+      optional: true,
+    },
+    ad: {
+      type: "string",
+      label: "Ad",
+      description: "JSON object specifying the ad content. Required for **Create** operations. For creates, include the ad type-specific fields and `finalUrls` — e.g., `{\"responsiveSearchAd\": {\"headlines\": [{\"text\": \"Headline\"}], \"descriptions\": [{\"text\": \"Desc\"}]}, \"finalUrls\": [\"https://example.com\"]}`. For updates, only include mutable fields — e.g., `{\"finalUrls\": [\"https://example.com\"], \"trackingUrlTemplate\": \"https://tracker.com?url={lpurl}\"}`.",
+      optional: true,
+    },
+    additionalFields: getAdditionalFields(docLink),
+  },
+  async run({ $ }) {
+    const {
+      googleAds,
+      accountId,
+      customerClientId,
+      operationType,
+      adGroupAdId,
+      adGroupId,
+      updateMask,
+      status,
+      ad,
+      additionalFields,
+    } = this;
+
+    if ((operationType === "update" || operationType === "remove") && !adGroupAdId) {
+      throw new ConfigurationError(
+        "**Ad Group Ad** 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 (!ad) {
+        throw new ConfigurationError(
+          "**Ad** is required for Create operations.",
+        );
+      }
+    }
+
+    const customerId = customerClientId ?? accountId;
+    const adGroup = adGroupId
+      ? `customers/${customerId}/adGroups/${adGroupId}`
+      : undefined;
+
+    let operation;
+
+    if (operationType === "remove") {
+      operation = {
+        remove: adGroupAdId,
+      };
+    } else {
+      const parsedAd = ad
+        ? parseStringObject(ad)
+        : undefined;
+
+      const adGroupAdData = {
+        ...(adGroupAdId && {
+          resourceName: adGroupAdId,
+        }),
+        ...(adGroup && {
+          adGroup,
+        }),
+        ...(status && {
+          status,
+        }),
+        ...(parsedAd && {
+          ad: parsedAd,
+        }),
+        ...parseObject(additionalFields),
+      };
+
+      if (operationType === "update") {
+        operation = {
+          update: adGroupAdData,
+          updateMask,
+        };
+      } else {
+        operation = {
+          create: adGroupAdData,
+        };
+      }
+    }
+
+    const response = await googleAds.mutateAdGroupAd({
+      $,
+      accountId,
+      customerClientId,
+      data: {
+        operations: [
+          operation,
+        ],
+      },
+    });
+
+    const result = response?.results?.[0];
+    const id = result?.resourceName?.split("/").pop();
+
+    $.export(
+      "$summary",
+      `Successfully ${operationType}d ad group ad${id
+        ? ` with ID \`${id}\``
+        : ""}.`,
+    );
+    return response;
+  },
+};

package/actions/create-or-update-bidding-strategy/create-or-update-bidding-strategy.mjs

@@ -0,0 +1,185 @@
+import { ConfigurationError } from "@pipedream/platform";
+import googleAds from "../../google_ads.app.mjs";
+import {
+  CAMPAIGN_OPERATION_TYPES,
+  PORTFOLIO_BIDDING_STRATEGY_TYPES,
+} from "../../common/constants.mjs";
+import { parseObject } from "../../common/utils.mjs";
+import { getAdditionalFields } from "../common/props.mjs";
+import {
+  buildBiddingScheme, getSchemeProps, PORTFOLIO_BIDDING_SCHEMES,
+} from "../common/bidding.mjs";
+
+const docLink =
+  "https://developers.google.com/google-ads/api/reference/rpc/v25/BiddingStrategyService/MutateBiddingStrategies?transport=rest";
+
+export default {
+  key: "google_ads-create-or-update-bidding-strategy",
+  name: "Create or Update Bidding Strategy",
+  description: `Creates, updates, or removes a portfolio bidding strategy. [See the documentation](${docLink})`,
+  version: "1.0.0",
+  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 bidding strategy.",
+      options: CAMPAIGN_OPERATION_TYPES,
+    },
+    biddingStrategyId: {
+      propDefinition: [
+        googleAds,
+        "biddingStrategyId",
+        ({
+          accountId, customerClientId,
+        }) => ({
+          accountId,
+          customerClientId,
+        }),
+      ],
+      description: "The bidding strategy 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 bidding strategy. Required for **Create** operations.",
+      optional: true,
+    },
+    type: {
+      type: "string",
+      label: "Type",
+      description: "The type of the bidding strategy. Required for **Create** operations. Immutable after creation.",
+      options: PORTFOLIO_BIDDING_STRATEGY_TYPES,
+      optional: true,
+    },
+    ...getSchemeProps(PORTFOLIO_BIDDING_SCHEMES),
+    additionalFields: getAdditionalFields(docLink),
+  },
+  async run({ $ }) {
+    const {
+      googleAds,
+      accountId,
+      customerClientId,
+      operationType,
+      biddingStrategyId,
+      updateMask,
+      name,
+      type,
+      additionalFields,
+    } = this;
+
+    if ((operationType === "update" || operationType === "remove") && !biddingStrategyId) {
+      throw new ConfigurationError(
+        "**Bidding Strategy** 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 = biddingStrategyId
+      ? `customers/${customerId}/biddingStrategies/${biddingStrategyId}`
+      : undefined;
+
+    let operation;
+
+    if (operationType === "remove") {
+      operation = {
+        remove: resourceName,
+      };
+    } else {
+      const strategyData = {
+        ...(resourceName && {
+          resourceName,
+        }),
+        ...(name && {
+          name,
+        }),
+        ...(type && {
+          type,
+        }),
+        ...buildBiddingScheme(PORTFOLIO_BIDDING_SCHEMES, type, this),
+        ...parseObject(additionalFields),
+      };
+
+      if (operationType === "update") {
+        operation = {
+          update: strategyData,
+          updateMask,
+        };
+      } else {
+        operation = {
+          create: strategyData,
+        };
+      }
+    }
+
+    const response = await googleAds.mutateBiddingStrategies({
+      $,
+      accountId,
+      customerClientId,
+      data: {
+        operations: [
+          operation,
+        ],
+      },
+    });
+
+    const result = response?.results?.[0];
+    const id = result?.resourceName?.split("/").pop();
+
+    $.export(
+      "$summary",
+      `Successfully ${operationType}d bidding strategy${id
+        ? ` with ID \`${id}\``
+        : ""}.`,
+    );
+    return response;
+  },
+};