@apteva/integrations 0.2.3 → 0.3.1

package/src/apps/google-ads.json

@@ -0,0 +1,270 @@
+{
+  "slug": "google-ads",
+  "name": "Google Ads",
+  "description": "Google Ads API v23 — manage campaigns, ad groups, ads, keywords, budgets, and run performance reports via GAQL queries",
+  "logo": "https://www.google.com/s2/favicons?domain=ads.google.com&sz=128",
+  "categories": [
+    "advertising",
+    "marketing",
+    "ppc",
+    "campaigns",
+    "google",
+    "search-ads",
+    "display-ads"
+  ],
+  "base_url": "https://googleads.googleapis.com/v23",
+  "auth": {
+    "types": [
+      "bearer",
+      "oauth2"
+    ],
+    "headers": {
+      "Authorization": "Bearer {{token}}"
+    },
+    "credential_fields": [
+      {
+        "name": "token",
+        "label": "access_token"
+      },
+      {
+        "name": "developer_token",
+        "label": "developer_token"
+      }
+    ],
+    "oauth2": {
+      "authorize_url": "https://accounts.google.com/o/oauth2/v2/auth",
+      "token_url": "https://oauth2.googleapis.com/token",
+      "scopes": [
+        "https://www.googleapis.com/auth/adwords"
+      ],
+      "client_id_required": true,
+      "pkce": false
+    }
+  },
+  "tools": [
+    {
+      "name": "list_accounts",
+      "description": "List all Google Ads customer accounts accessible to the authenticated user. Returns customer IDs and descriptive names. Use this first to find the customer_id needed for all other tools.",
+      "method": "GET",
+      "path": "/customers:listAccessibleCustomers",
+      "input_schema": {
+        "type": "object",
+        "properties": {}
+      }
+    },
+    {
+      "name": "search",
+      "description": "Run a Google Ads Query Language (GAQL) query to search for campaigns, ad groups, ads, keywords, or pull performance metrics. Examples:\n- List campaigns: SELECT campaign.id, campaign.name, campaign.status FROM campaign\n- Campaign performance: SELECT campaign.name, metrics.impressions, metrics.clicks, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_30_DAYS\n- Ad group performance: SELECT ad_group.name, metrics.clicks, metrics.conversions FROM ad_group WHERE campaign.id = 123\n- Keywords: SELECT ad_group_criterion.keyword.text, metrics.clicks FROM keyword_view WHERE segments.date DURING LAST_7_DAYS\n- Search terms: SELECT search_term_view.search_term, metrics.clicks FROM search_term_view WHERE segments.date DURING LAST_7_DAYS\n- Ads: SELECT ad_group_ad.ad.id, ad_group_ad.ad.responsive_search_ad.headlines FROM ad_group_ad",
+      "method": "POST",
+      "path": "/customers/%7B%7Bcustomer_id%7D%7D/googleAds:search",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "customer_id": {
+            "type": "string",
+            "description": "Google Ads customer ID (without hyphens, e.g. '1234567890')"
+          },
+          "query": {
+            "type": "string",
+            "description": "GAQL query string. Example: SELECT campaign.name, metrics.clicks FROM campaign WHERE segments.date DURING LAST_7_DAYS"
+          },
+          "page_size": {
+            "type": "integer",
+            "description": "Max results per page (default 10000, max 10000)"
+          },
+          "page_token": {
+            "type": "string",
+            "description": "Token for fetching next page of results"
+          }
+        },
+        "required": [
+          "customer_id",
+          "query"
+        ]
+      }
+    },
+    {
+      "name": "search_stream",
+      "description": "Run a GAQL query using streaming — returns all results at once without pagination. Better for large result sets. Same query syntax as google-ads-search.",
+      "method": "POST",
+      "path": "/customers/%7B%7Bcustomer_id%7D%7D/googleAds:searchStream",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "customer_id": {
+            "type": "string",
+            "description": "Google Ads customer ID (without hyphens)"
+          },
+          "query": {
+            "type": "string",
+            "description": "GAQL query string"
+          }
+        },
+        "required": [
+          "customer_id",
+          "query"
+        ]
+      }
+    },
+    {
+      "name": "campaign_mutate",
+      "description": "Create, update, or remove campaigns. Operations is an array where each item has one of: 'create' (new campaign object), 'update' (campaign object with resourceName) + 'updateMask', or 'remove' (resource name string).\n\nCreate example: {\"create\": {\"name\": \"My Campaign\", \"status\": \"PAUSED\", \"advertisingChannelType\": \"SEARCH\", \"campaignBudget\": \"customers/1234/campaignBudgets/5678\"}}\n\nUpdate example: {\"update\": {\"resourceName\": \"customers/1234/campaigns/5678\", \"status\": \"ENABLED\"}, \"updateMask\": \"status\"}\n\nRemove example: {\"remove\": \"customers/1234/campaigns/5678\"}",
+      "method": "POST",
+      "path": "/customers/%7B%7Bcustomer_id%7D%7D/campaigns:mutate",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "customer_id": {
+            "type": "string",
+            "description": "Google Ads customer ID (without hyphens)"
+          },
+          "operations": {
+            "type": "array",
+            "description": "Array of campaign operations (create/update/remove)",
+            "items": {
+              "type": "object"
+            }
+          }
+        },
+        "required": [
+          "customer_id",
+          "operations"
+        ]
+      }
+    },
+    {
+      "name": "ad_group_mutate",
+      "description": "Create, update, or remove ad groups.\n\nCreate example: {\"create\": {\"name\": \"My Ad Group\", \"campaign\": \"customers/1234/campaigns/5678\", \"status\": \"ENABLED\", \"cpcBidMicros\": \"1000000\"}}\n\nUpdate example: {\"update\": {\"resourceName\": \"customers/1234/adGroups/9012\", \"cpcBidMicros\": \"1500000\"}, \"updateMask\": \"cpcBidMicros\"}\n\nRemove example: {\"remove\": \"customers/1234/adGroups/9012\"}",
+      "method": "POST",
+      "path": "/customers/%7B%7Bcustomer_id%7D%7D/adGroups:mutate",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "customer_id": {
+            "type": "string",
+            "description": "Google Ads customer ID (without hyphens)"
+          },
+          "operations": {
+            "type": "array",
+            "description": "Array of ad group operations (create/update/remove)",
+            "items": {
+              "type": "object"
+            }
+          }
+        },
+        "required": [
+          "customer_id",
+          "operations"
+        ]
+      }
+    },
+    {
+      "name": "ad_mutate",
+      "description": "Create, update, or remove ads (ad group ads).\n\nCreate responsive search ad example: {\"create\": {\"adGroup\": \"customers/1234/adGroups/5678\", \"status\": \"ENABLED\", \"ad\": {\"responsiveSearchAd\": {\"headlines\": [{\"text\": \"Headline 1\"}, {\"text\": \"Headline 2\"}, {\"text\": \"Headline 3\"}], \"descriptions\": [{\"text\": \"Description 1\"}, {\"text\": \"Description 2\"}]}, \"finalUrls\": [\"https://example.com\"]}}}\n\nRemove example: {\"remove\": \"customers/1234/adGroupAds/5678~9012\"}",
+      "method": "POST",
+      "path": "/customers/%7B%7Bcustomer_id%7D%7D/adGroupAds:mutate",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "customer_id": {
+            "type": "string",
+            "description": "Google Ads customer ID (without hyphens)"
+          },
+          "operations": {
+            "type": "array",
+            "description": "Array of ad operations (create/update/remove)",
+            "items": {
+              "type": "object"
+            }
+          }
+        },
+        "required": [
+          "customer_id",
+          "operations"
+        ]
+      }
+    },
+    {
+      "name": "keyword_mutate",
+      "description": "Create, update, or remove keywords (ad group criteria).\n\nCreate keyword example: {\"create\": {\"adGroup\": \"customers/1234/adGroups/5678\", \"keyword\": {\"text\": \"buy running shoes\", \"matchType\": \"PHRASE\"}, \"status\": \"ENABLED\", \"cpcBidMicros\": \"500000\"}}\n\nRemove example: {\"remove\": \"customers/1234/adGroupCriteria/5678~9012\"}",
+      "method": "POST",
+      "path": "/customers/%7B%7Bcustomer_id%7D%7D/adGroupCriteria:mutate",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "customer_id": {
+            "type": "string",
+            "description": "Google Ads customer ID (without hyphens)"
+          },
+          "operations": {
+            "type": "array",
+            "description": "Array of keyword/criterion operations (create/update/remove)",
+            "items": {
+              "type": "object"
+            }
+          }
+        },
+        "required": [
+          "customer_id",
+          "operations"
+        ]
+      }
+    },
+    {
+      "name": "budget_mutate",
+      "description": "Create, update, or remove campaign budgets. Amounts are in micros (1 USD = 1,000,000 micros).\n\nCreate example: {\"create\": {\"name\": \"Daily Budget $50\", \"amountMicros\": \"50000000\", \"deliveryMethod\": \"STANDARD\"}}\n\nUpdate example: {\"update\": {\"resourceName\": \"customers/1234/campaignBudgets/5678\", \"amountMicros\": \"75000000\"}, \"updateMask\": \"amountMicros\"}",
+      "method": "POST",
+      "path": "/customers/%7B%7Bcustomer_id%7D%7D/campaignBudgets:mutate",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "customer_id": {
+            "type": "string",
+            "description": "Google Ads customer ID (without hyphens)"
+          },
+          "operations": {
+            "type": "array",
+            "description": "Array of budget operations (create/update/remove)",
+            "items": {
+              "type": "object"
+            }
+          }
+        },
+        "required": [
+          "customer_id",
+          "operations"
+        ]
+      }
+    },
+    {
+      "name": "bulk_mutate",
+      "description": "Create or modify multiple resource types in a single atomic request — budgets, campaigns, ad groups, and ads together. Uses temporary resource IDs (negative numbers) to reference resources created in the same request.\n\nExample creating a full campaign:\n{\"mutateOperations\": [{\"campaignBudgetOperation\": {\"create\": {\"resourceName\": \"customers/1234/campaignBudgets/-1\", \"name\": \"Budget\", \"amountMicros\": \"50000000\"}}}, {\"campaignOperation\": {\"create\": {\"resourceName\": \"customers/1234/campaigns/-2\", \"name\": \"My Campaign\", \"campaignBudget\": \"customers/1234/campaignBudgets/-1\", \"advertisingChannelType\": \"SEARCH\", \"status\": \"PAUSED\"}}}, {\"adGroupOperation\": {\"create\": {\"campaign\": \"customers/1234/campaigns/-2\", \"name\": \"Ad Group 1\"}}}]}",
+      "method": "POST",
+      "path": "/customers/%7B%7Bcustomer_id%7D%7D/googleAds:mutate",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "customer_id": {
+            "type": "string",
+            "description": "Google Ads customer ID (without hyphens)"
+          },
+          "mutateOperations": {
+            "type": "array",
+            "description": "Array of typed operations (campaignBudgetOperation, campaignOperation, adGroupOperation, adGroupAdOperation, adGroupCriterionOperation, etc.)",
+            "items": {
+              "type": "object"
+            }
+          },
+          "partialFailure": {
+            "type": "boolean",
+            "description": "If true, allows partial success. If false (default), all operations fail if any one fails."
+          }
+        },
+        "required": [
+          "customer_id",
+          "mutateOperations"
+        ]
+      }
+    }
+  ]
+}