@slates-integrations/google-ads 0.2.0-rc.2

package/README.md

@@ -0,0 +1,57 @@
+# <img src="https://provider-logos.metorial-cdn.com/googleads.png" height="20"> Google Ads
+
+Create, manage, and optimize advertising campaigns across Google Search, Display Network, YouTube, and Shopping. Configure ad groups, keywords, bidding strategies, audience targeting, and geographic targeting. Track and import conversions including offline and enhanced conversions. Generate reporting and analytics using Google Ads Query Language (GAQL). Plan keywords with historical metrics and forecasts. Manage account hierarchies and multi-account operations. Receive lead form webhook data from campaigns.
+
+## Tools
+
+### Generate Keyword Ideas
+
+Generates keyword suggestions based on seed keywords, a URL, or both. Returns keyword ideas with historical metrics including average monthly searches, competition level, and suggested bid ranges. Similar to the Keyword Planner tool in the Google Ads UI. Useful for keyword research, discovering new targeting opportunities, and estimating traffic potential.
+
+### List Accounts
+
+Lists all Google Ads customer accounts accessible to the authenticated user. Returns account IDs, names, currency, timezone, and status for each account. Useful for discovering which accounts can be managed and obtaining customer IDs needed for other operations.
+
+### Manage Ad Groups
+
+Create, update, or remove ad groups within a Google Ads campaign. Ad groups organize ads and keywords within a campaign. Supports setting the ad group name, status, type, CPC bid, and targeting URL.
+
+### Manage Ads
+
+Create, update, or remove ads within an ad group. Supports responsive search ads, expanded text ads, responsive display ads, and other ad formats. For responsive search ads, provide headlines and descriptions. Google will automatically test combinations. Pin headlines/descriptions to specific positions if needed.
+
+### Manage Audience Lists
+
+Create, update, or remove user lists (audience segments) for targeting. Supports CRM-based customer lists, rule-based lists, and remarketing lists. User lists can be applied to campaigns or ad groups for audience targeting, bid adjustments, or exclusions.
+
+### Manage Bidding Strategies
+
+Create, update, or remove portfolio bidding strategies that can be shared across multiple campaigns. Portfolio strategies centralize bid management and enable cross-campaign optimization. For campaign-level bidding, use the Manage Campaigns tool instead. This tool is specifically for shared/portfolio bidding strategies.
+
+### Manage Campaigns
+
+Create, update, or remove Google Ads campaigns. Supports setting campaign name, status, type, budget, start/end dates, bidding strategy, and network settings. When creating a campaign, a campaign budget is automatically created if \
+
+### Manage Conversion Actions
+
+Create, update, or remove conversion actions for tracking valuable customer actions. Conversion actions track events like purchases, sign-ups, phone calls, or app installs. Supports configuring conversion counting, attribution models, value settings, and conversion windows.
+
+### Manage Keywords
+
+Add, update, or remove keywords in an ad group. Also supports managing negative keywords at both the ad group and campaign levels. Keywords determine when ads are shown based on user search queries. Each keyword has a match type controlling how broadly it matches search terms.
+
+### Run GAQL Query
+
+Executes a Google Ads Query Language (GAQL) query to retrieve reporting data, resource details, or metrics from a Google Ads account. Supports querying any resource type including campaigns, ad groups, ads, keywords, conversions, and more. Use this tool to build custom reports, fetch performance metrics, or look up specific resources. The query follows the GAQL syntax: \
+
+### Upload Offline Conversions
+
+Upload offline click conversions to Google Ads. Imports real-world transaction data like in-store purchases, qualified phone leads, or CRM events to measure full-funnel conversion impact. Each conversion requires a Google Click ID (gclid) to link the offline event back to the original ad click.
+
+## License
+
+This integration is licensed under the [FSL-1.1](https://github.com/metorial/metorial-platform/blob/dev/LICENSE).
+
+<div align="center">
+  <sub>Built with ❤️ by <a href="https://metorial.com">Metorial</a></sub>
+</div>

package/docs/SPEC.md

@@ -0,0 +1,98 @@
+# Slates Specification for Google Ads
+
+## Overview
+
+Google Ads is Google's online advertising platform that allows advertisers to create and manage ad campaigns across Google Search, Display Network, YouTube, and other Google properties. The Google Ads API enables programmatic management of advertising accounts, campaigns, ads, keywords, bidding strategies, audience targeting, conversion tracking, and reporting.
+
+## Authentication
+
+Google Ads API utilizes the OAuth 2.0 protocol for authentication and authorization, allowing your app to access user accounts without handling login information. In addition to OAuth 2.0 credentials, a developer token is also required to make Google Ads API calls.
+
+### Prerequisites
+
+1. **Developer Token**: A developer token is a 22-character alphanumeric string obtained from the API Center page of your Google Ads manager account. Each developer token has an access level (Test, Basic, or Standard) which determines the number of API calls and the environment (test or production) it can be used in. You need a Google Ads manager account to obtain a developer token.
+
+2. **Google Cloud Project**: Enable the Google Ads API in your Google Cloud Console project and create OAuth 2.0 client IDs under "API & Services" > "Credentials".
+
+### OAuth 2.0 Flows
+
+The API supports two main OAuth 2.0 flows:
+
+- **Web/Desktop Application Flow**: For apps that allow users to sign in and authorize your app to manage their Google Ads accounts on their behalf. Your app builds and manages the OAuth 2.0 user credentials using a Client ID, Client Secret, and Refresh Token along with the Developer Token and Login Customer ID.
+
+- **Service Account Flow**: For workflows that don't require human interaction. This requires a configuration step where the user adds a service account to their Google Ads account, and the app can then use the service account's credentials to manage the user's Google Ads account.
+
+### OAuth 2.0 Scope
+
+The scope for the Google Ads API is `https://www.googleapis.com/auth/adwords`.
+
+### Required Headers
+
+When calling the Google Ads API, you need both OAuth 2.0 application credentials and a developer token. If making API calls with a Google Ads manager account, you must specify a `login-customer-id` header.
+
+### Token Endpoint
+
+Refresh tokens can be exchanged for access tokens at: `https://www.googleapis.com/oauth2/v3/token`
+
+### Important Notes
+
+- The Google Ads API does not support simultaneous sign-in with data access request (hybrid) or domain-wide delegation of authority (2LO).
+- Your developer token needs approval to work with production Google Ads accounts but can be used immediately with a test manager account.
+
+## Features
+
+### Campaign Management
+
+Create, update, pause, and remove advertising campaigns across multiple campaign types including Search, Display, Video, Shopping, Performance Max, and App campaigns. Configure campaign-level settings such as budgets, start/end dates, geographic targeting, language targeting, and ad scheduling.
+
+### Ad Group and Ad Management
+
+Automatically generate keywords, ad text, landing pages, and custom reports. Create and manage ad groups within campaigns, and configure ads of various formats including text ads, responsive ads, image ads, and video ads. Update ad copy in real-time based on business data.
+
+### Keyword Management
+
+Add, update, and remove keywords within ad groups. Configure match types (broad, phrase, exact) and set keyword-level bids. Manage negative keywords at both campaign and ad group levels.
+
+### Bidding Strategy Management
+
+The Google Ads API offers a range of customizable bidding strategies that allow you to automate your bidding process and achieve your campaign goals. Available strategies include Manual CPC, Manual CPM, Enhanced CPC, Maximize Conversions, Maximize Conversion Value, Target CPA, Target ROAS, and more.
+
+### Keyword Planning
+
+Keyword Planning is a process for getting keyword metrics and forecasts as well as searching for new keywords to add to campaigns. The functionality is similar to the Keyword Planner tool in the Google Ads UI. Historical metrics provide data on how keywords have previously performed on Google Search. Forecast metrics provide a more exact estimate of future campaign performance.
+
+### Audience Targeting
+
+The API provides tools to implement sophisticated targeting strategies. One method is "Audience segments", also known as user lists, which are groups of people with specific interests, intents, or demographic information. Supports CRM-based user lists, rule-based user lists, remarketing lists, and similar audiences. Also supports geo-targeting and location-based targeting.
+
+### Conversion Tracking and Management
+
+The Google Ads API allows for programmatic management of the entire conversion management workflow, covering creating, importing, adjusting, monitoring, and grouping conversion actions. Import offline conversions to measure real-world transactions such as qualified leads over the phone or in-office payments. Enhanced conversions for web can improve the accuracy of your conversion measurement by supplementing existing conversion data with hashed first-party customer data in a privacy-safe way.
+
+### Reporting and Analytics
+
+Report on conversions by retrieving data about specific conversion actions or retrieving conversion metrics for other resources like campaigns, ad groups, and ads. Use Google Ads Query Language (GAQL) to build custom queries across all resource types. Compile your Google Ads data to use with other systems like inventories, generate regular reports, and make campaign adjustments in bulk.
+
+### Account Management
+
+Using a manager account, you can control client accounts and run operations without logging into each account separately. List accessible customer accounts, manage account hierarchies, and handle multi-account operations.
+
+### Reach and Frequency Forecasting
+
+Plan video and display campaigns by generating reach and frequency forecasts. Developer tokens must be allowlisted specifically for the ReachPlanService, even if approved for other Google Ads API services.
+
+## Events
+
+Webhook is not supported in the Google Ads API for general account or campaign changes.
+
+However, Google Ads does support one specific webhook mechanism:
+
+### Lead Form Webhook
+
+POST requests to the webhook are sent in JSON format, adhering to a specific schema for user lead data. The JSON payload includes fields for lead identification, user-submitted data, form and campaign details, and verification keys. User-submitted data is contained within `user_column_data`, using `column_id` and `string_value` to represent the data type and its value.
+
+- Configured per lead form extension within Google Ads campaigns.
+- Requires a webhook URL and a verification key.
+- Lead handlers should use the `lead_id` for deduplication and respond with specific HTTP codes indicating success or different types of errors.
+- The `asset_group_id` field is only populated for Performance Max campaigns.
+- Payload includes campaign ID, ad group ID, creative ID, click ID (gclid), and a test lead indicator.

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@slates-integrations/google-ads",
+  "main": "src/index.ts",
+  "type": "module",
+  "scripts": {
+    "build": "bunx @vercel/ncc build src/index.ts -o dist -m -s",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@types/node": "^20",
+    "slates": "1.0.0-rc.9",
+    "zod": "^4.2"
+  },
+  "devDependencies": {
+    "@slates/test": "1.0.0-rc.4",
+    "typescript": "^5",
+    "vitest": "^3.1.2"
+  },
+  "version": "0.2.0-rc.2"
+}

package/slate.json

@@ -0,0 +1,21 @@
+{
+  "name": "@google/google-ads",
+  "description": "Create, manage, and optimize advertising campaigns across Google Search, Display Network, YouTube, and Shopping. Configure ad groups, keywords, bidding strategies, audience targeting, and geographic targeting. Track and import conversions including offline and enhanced conversions. Generate reporting and analytics using Google Ads Query Language (GAQL). Plan keywords with historical metrics and forecasts. Manage account hierarchies and multi-account operations. Receive lead form webhook data from campaigns.",
+  "categories": [
+    "apis-and-http-requests",
+    "crm-and-sales-tools"
+  ],
+  "skills": [
+    "manage ad campaigns",
+    "configure keyword targeting",
+    "set bidding strategies",
+    "track conversions",
+    "generate ad reports",
+    "manage audience targeting",
+    "plan keyword forecasts",
+    "manage ad groups and ads",
+    "import offline conversions",
+    "manage account hierarchies"
+  ],
+  "logoUrl": "https://provider-logos.metorial-cdn.com/googleads.png"
+}

package/src/auth.contract.test.ts

@@ -0,0 +1,174 @@
+import { createLocalSlateTestClient, expectSlateError } from '@slates/test';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { googleAdsScopes } from './scopes';
+
+let oauthPost = vi.fn();
+let profileGet = vi.fn();
+
+let loadProviderClient = async () => {
+  vi.resetModules();
+  oauthPost.mockReset();
+  profileGet.mockReset();
+
+  vi.doMock('slates', async () => {
+    let actual = await vi.importActual<typeof import('slates')>('slates');
+
+    return {
+      ...actual,
+      createAxios: vi.fn((config?: { baseURL?: string }) => {
+        if (config?.baseURL === 'https://oauth2.googleapis.com') {
+          return {
+            post: oauthPost
+          };
+        }
+
+        if (config?.baseURL === 'https://www.googleapis.com') {
+          return {
+            get: profileGet
+          };
+        }
+
+        return actual.createAxios(config);
+      })
+    };
+  });
+
+  let { provider } = await import('./index');
+  return createLocalSlateTestClient({ slate: provider as any });
+};
+
+afterEach(() => {
+  vi.doUnmock('slates');
+  vi.resetModules();
+});
+
+describe('google-ads auth contract', () => {
+  it('builds the expected OAuth authorization URL', async () => {
+    let client = await loadProviderClient();
+    let result = await client.getAuthorizationUrl({
+      authenticationMethodId: 'google_oauth',
+      redirectUri: 'https://example.com/callback',
+      state: 'state-123',
+      input: { developerToken: 'dev-token-22charslong00' },
+      clientId: 'client-id',
+      clientSecret: 'client-secret',
+      scopes: [googleAdsScopes.adwords]
+    });
+
+    let url = new URL(result.authorizationUrl);
+    expect(`${url.origin}${url.pathname}`).toBe(
+      'https://accounts.google.com/o/oauth2/v2/auth'
+    );
+    expect(url.searchParams.get('scope')).toBe(googleAdsScopes.adwords);
+    expect(result.input).toEqual({ developerToken: 'dev-token-22charslong00' });
+  });
+
+  it('maps callback and refresh token responses into the stored auth shape', async () => {
+    let client = await loadProviderClient();
+
+    oauthPost.mockResolvedValueOnce({
+      data: {
+        access_token: 'access-token',
+        refresh_token: 'refresh-token',
+        expires_in: 3600,
+        scope: `${googleAdsScopes.adwords} openid`
+      }
+    });
+
+    let callbackResult = await client.handleAuthorizationCallback({
+      authenticationMethodId: 'google_oauth',
+      code: 'auth-code',
+      state: 'state-123',
+      redirectUri: 'https://example.com/callback',
+      input: { developerToken: 'dev-token-22charslong00' },
+      clientId: 'client-id',
+      clientSecret: 'client-secret',
+      scopes: [googleAdsScopes.adwords]
+    });
+
+    expect(callbackResult.output).toMatchObject({
+      token: 'access-token',
+      refreshToken: 'refresh-token',
+      developerToken: 'dev-token-22charslong00'
+    });
+    expect(callbackResult.scopes).toEqual([googleAdsScopes.adwords, 'openid']);
+    expect(Date.parse(String(callbackResult.output.expiresAt))).toBeGreaterThan(Date.now());
+
+    oauthPost.mockResolvedValueOnce({
+      data: {
+        access_token: 'refreshed-token',
+        expires_in: 1800
+      }
+    });
+
+    let refreshResult = await client.refreshToken({
+      authenticationMethodId: 'google_oauth',
+      output: {
+        token: 'stale-token',
+        refreshToken: 'refresh-token',
+        developerToken: 'dev-token-22charslong00'
+      },
+      input: { developerToken: 'dev-token-22charslong00' },
+      clientId: 'client-id',
+      clientSecret: 'client-secret',
+      scopes: [googleAdsScopes.adwords]
+    });
+
+    expect(refreshResult.output).toMatchObject({
+      token: 'refreshed-token',
+      refreshToken: 'refresh-token',
+      developerToken: 'dev-token-22charslong00'
+    });
+    expect(Date.parse(String(refreshResult.output.expiresAt))).toBeGreaterThan(Date.now());
+  });
+
+  it('fails refreshes cleanly when no refresh token is stored', async () => {
+    let client = await loadProviderClient();
+
+    await expectSlateError(
+      () =>
+        client.refreshToken({
+          authenticationMethodId: 'google_oauth',
+          output: {
+            token: 'stale-token',
+            developerToken: 'dev-token-22charslong00'
+          },
+          input: { developerToken: 'dev-token-22charslong00' },
+          clientId: 'client-id',
+          clientSecret: 'client-secret',
+          scopes: [googleAdsScopes.adwords]
+        }),
+      { code: 'internal.unexpected', kind: 'internal', status: 500 }
+    );
+  });
+
+  it('maps the Google profile payload into the Slate profile shape', async () => {
+    let client = await loadProviderClient();
+
+    profileGet.mockResolvedValueOnce({
+      data: {
+        id: 'user-123',
+        email: 'ads-test@example.com',
+        name: 'Ads Test User',
+        picture: 'https://example.com/avatar.png'
+      }
+    });
+
+    let result = await client.getAuthProfile({
+      authenticationMethodId: 'google_oauth',
+      output: {
+        token: 'profile-token',
+        developerToken: 'dev-token-22charslong00'
+      },
+      input: { developerToken: 'dev-token-22charslong00' },
+      scopes: [googleAdsScopes.adwords]
+    });
+
+    expect(result.profile).toEqual({
+      id: 'user-123',
+      email: 'ads-test@example.com',
+      name: 'Ads Test User',
+      imageUrl: 'https://example.com/avatar.png'
+    });
+  });
+});

package/src/auth.ts

@@ -0,0 +1,150 @@
+import { SlateAuth, createAxios } from 'slates';
+import { z } from 'zod';
+import { googleAdsScopes } from './scopes';
+
+let googleOAuthAxios = createAxios({
+  baseURL: 'https://oauth2.googleapis.com'
+});
+
+let profileAxios = createAxios({
+  baseURL: 'https://www.googleapis.com'
+});
+
+export let auth = SlateAuth.create()
+  .output(
+    z.object({
+      token: z.string(),
+      refreshToken: z.string().optional(),
+      expiresAt: z.string().optional(),
+      developerToken: z.string()
+    })
+  )
+  .addOauth({
+    type: 'auth.oauth',
+    name: 'Google OAuth',
+    key: 'google_oauth',
+
+    scopes: [
+      {
+        title: 'Google Ads',
+        description:
+          'Full access to manage Google Ads accounts, campaigns, ads, and reporting',
+        scope: googleAdsScopes.adwords
+      }
+    ],
+
+    inputSchema: z.object({
+      developerToken: z
+        .string()
+        .describe(
+          'Your Google Ads API developer token (22-character alphanumeric string from the API Center in your manager account)'
+        )
+    }),
+
+    getAuthorizationUrl: async ctx => {
+      let params = new URLSearchParams({
+        client_id: ctx.clientId,
+        redirect_uri: ctx.redirectUri,
+        response_type: 'code',
+        scope: ctx.scopes.join(' '),
+        access_type: 'offline',
+        prompt: 'consent',
+        state: ctx.state
+      });
+
+      return {
+        url: `https://accounts.google.com/o/oauth2/v2/auth?${params.toString()}`,
+        input: ctx.input
+      };
+    },
+
+    handleCallback: async ctx => {
+      let response = await googleOAuthAxios.post(
+        '/token',
+        new URLSearchParams({
+          code: ctx.code,
+          client_id: ctx.clientId,
+          client_secret: ctx.clientSecret,
+          redirect_uri: ctx.redirectUri,
+          grant_type: 'authorization_code'
+        }).toString(),
+        {
+          headers: { 'Content-Type': 'application/x-www-form-urlencoded' }
+        }
+      );
+
+      let data = response.data;
+      let expiresAt = data.expires_in
+        ? new Date(Date.now() + data.expires_in * 1000).toISOString()
+        : undefined;
+      let grantedScopes =
+        typeof data.scope === 'string' ? data.scope.split(' ').filter(Boolean) : undefined;
+
+      return {
+        output: {
+          token: data.access_token,
+          refreshToken: data.refresh_token,
+          expiresAt,
+          developerToken: ctx.input.developerToken
+        },
+        input: ctx.input,
+        scopes: grantedScopes
+      };
+    },
+
+    handleTokenRefresh: async ctx => {
+      if (!ctx.output.refreshToken) {
+        throw new Error('No refresh token available');
+      }
+
+      let response = await googleOAuthAxios.post(
+        '/token',
+        new URLSearchParams({
+          refresh_token: ctx.output.refreshToken,
+          client_id: ctx.clientId,
+          client_secret: ctx.clientSecret,
+          grant_type: 'refresh_token'
+        }).toString(),
+        {
+          headers: { 'Content-Type': 'application/x-www-form-urlencoded' }
+        }
+      );
+
+      let data = response.data;
+      let expiresAt = data.expires_in
+        ? new Date(Date.now() + data.expires_in * 1000).toISOString()
+        : undefined;
+
+      return {
+        output: {
+          token: data.access_token,
+          refreshToken: ctx.output.refreshToken,
+          expiresAt,
+          developerToken: ctx.output.developerToken
+        }
+      };
+    },
+
+    getProfile: async (ctx: {
+      output: { token: string; refreshToken?: string; expiresAt?: string; developerToken: string };
+      input: { developerToken: string };
+      scopes: string[];
+    }) => {
+      let response = await profileAxios.get('/oauth2/v2/userinfo', {
+        headers: {
+          Authorization: `Bearer ${ctx.output.token}`
+        }
+      });
+
+      let data = response.data;
+
+      return {
+        profile: {
+          id: data.id,
+          email: data.email,
+          name: data.name,
+          imageUrl: data.picture
+        }
+      };
+    }
+  });

package/src/config.ts

@@ -0,0 +1,13 @@
+import { SlateConfig } from 'slates';
+import { z } from 'zod';
+
+export let config = SlateConfig.create(
+  z.object({
+    loginCustomerId: z
+      .string()
+      .optional()
+      .describe(
+        'The Google Ads manager account ID (without hyphens) used when making API calls on behalf of a client account. Required when using a manager account.'
+      )
+  })
+);

package/src/index.ts

@@ -0,0 +1,34 @@
+import { Slate } from 'slates';
+import { spec } from './spec';
+import {
+  listAccounts,
+  searchReports,
+  manageCampaigns,
+  manageAdGroups,
+  manageAds,
+  manageKeywords,
+  manageBiddingStrategies,
+  manageConversionActions,
+  generateKeywordIdeas,
+  uploadOfflineConversions,
+  manageAudienceLists
+} from './tools';
+import { leadFormSubmit } from './triggers';
+
+export let provider = Slate.create({
+  spec,
+  tools: [
+    listAccounts,
+    searchReports,
+    manageCampaigns,
+    manageAdGroups,
+    manageAds,
+    manageKeywords,
+    manageBiddingStrategies,
+    manageConversionActions,
+    generateKeywordIdeas,
+    uploadOfflineConversions,
+    manageAudienceLists
+  ] as any,
+  triggers: [leadFormSubmit] as any
+});