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

package/src/lib/client.ts

@@ -0,0 +1,245 @@
+import { createAxios } from 'slates';
+import type { AxiosInstance } from 'axios';
+
+let API_VERSION = 'v19';
+let BASE_URL = `https://googleads.googleapis.com/${API_VERSION}`;
+
+export interface GoogleAdsClientConfig {
+  token: string;
+  developerToken: string;
+  loginCustomerId?: string;
+}
+
+export interface MutateOperation {
+  create?: Record<string, any>;
+  update?: Record<string, any>;
+  remove?: string;
+  updateMask?: string;
+}
+
+export interface SearchResponse {
+  results: Record<string, any>[];
+  totalResultsCount?: string;
+  nextPageToken?: string;
+  fieldMask?: string;
+}
+
+export class GoogleAdsClient {
+  private http: AxiosInstance;
+
+  constructor(config: GoogleAdsClientConfig) {
+    let headers: Record<string, string> = {
+      Authorization: `Bearer ${config.token}`,
+      'developer-token': config.developerToken,
+      'Content-Type': 'application/json'
+    };
+
+    if (config.loginCustomerId) {
+      headers['login-customer-id'] = config.loginCustomerId.replace(/-/g, '');
+    }
+
+    this.http = createAxios({
+      baseURL: BASE_URL,
+      headers
+    });
+  }
+
+  // Account Management
+
+  async listAccessibleCustomers(): Promise<string[]> {
+    let response = await this.http.get('/customers:listAccessibleCustomers');
+    return response.data.resourceNames || [];
+  }
+
+  async getCustomer(customerId: string): Promise<Record<string, any>> {
+    let cid = customerId.replace(/-/g, '');
+    let response = await this.http.post(`/customers/${cid}/googleAds:search`, {
+      query: `SELECT customer.id, customer.descriptive_name, customer.currency_code, customer.time_zone, customer.manager, customer.status FROM customer LIMIT 1`
+    });
+    let results = response.data.results || [];
+    return results[0]?.customer || {};
+  }
+
+  // GAQL Search
+
+  async search(
+    customerId: string,
+    query: string,
+    pageSize?: number,
+    pageToken?: string
+  ): Promise<SearchResponse> {
+    let cid = customerId.replace(/-/g, '');
+    let body: Record<string, any> = { query };
+    if (pageSize) body.pageSize = pageSize;
+    if (pageToken) body.pageToken = pageToken;
+
+    let response = await this.http.post(`/customers/${cid}/googleAds:search`, body);
+    return response.data;
+  }
+
+  async searchStream(customerId: string, query: string): Promise<Record<string, any>[]> {
+    let cid = customerId.replace(/-/g, '');
+    let response = await this.http.post(`/customers/${cid}/googleAds:searchStream`, { query });
+    let results: Record<string, any>[] = [];
+    if (Array.isArray(response.data)) {
+      for (let batch of response.data) {
+        if (batch.results) {
+          results.push(...batch.results);
+        }
+      }
+    }
+    return results;
+  }
+
+  // Campaign Management
+
+  async mutateCampaigns(
+    customerId: string,
+    operations: MutateOperation[]
+  ): Promise<Record<string, any>> {
+    let cid = customerId.replace(/-/g, '');
+    let response = await this.http.post(`/customers/${cid}/campaigns:mutate`, {
+      operations
+    });
+    return response.data;
+  }
+
+  // Campaign Budget Management
+
+  async mutateCampaignBudgets(
+    customerId: string,
+    operations: MutateOperation[]
+  ): Promise<Record<string, any>> {
+    let cid = customerId.replace(/-/g, '');
+    let response = await this.http.post(`/customers/${cid}/campaignBudgets:mutate`, {
+      operations
+    });
+    return response.data;
+  }
+
+  // Ad Group Management
+
+  async mutateAdGroups(
+    customerId: string,
+    operations: MutateOperation[]
+  ): Promise<Record<string, any>> {
+    let cid = customerId.replace(/-/g, '');
+    let response = await this.http.post(`/customers/${cid}/adGroups:mutate`, {
+      operations
+    });
+    return response.data;
+  }
+
+  // Ad Group Ad Management
+
+  async mutateAdGroupAds(
+    customerId: string,
+    operations: MutateOperation[]
+  ): Promise<Record<string, any>> {
+    let cid = customerId.replace(/-/g, '');
+    let response = await this.http.post(`/customers/${cid}/adGroupAds:mutate`, {
+      operations
+    });
+    return response.data;
+  }
+
+  // Ad Group Criterion (Keywords) Management
+
+  async mutateAdGroupCriteria(
+    customerId: string,
+    operations: MutateOperation[]
+  ): Promise<Record<string, any>> {
+    let cid = customerId.replace(/-/g, '');
+    let response = await this.http.post(`/customers/${cid}/adGroupCriteria:mutate`, {
+      operations
+    });
+    return response.data;
+  }
+
+  // Campaign Criterion (Negative Keywords, Targeting) Management
+
+  async mutateCampaignCriteria(
+    customerId: string,
+    operations: MutateOperation[]
+  ): Promise<Record<string, any>> {
+    let cid = customerId.replace(/-/g, '');
+    let response = await this.http.post(`/customers/${cid}/campaignCriteria:mutate`, {
+      operations
+    });
+    return response.data;
+  }
+
+  // Bidding Strategy Management
+
+  async mutateBiddingStrategies(
+    customerId: string,
+    operations: MutateOperation[]
+  ): Promise<Record<string, any>> {
+    let cid = customerId.replace(/-/g, '');
+    let response = await this.http.post(`/customers/${cid}/biddingStrategies:mutate`, {
+      operations
+    });
+    return response.data;
+  }
+
+  // Conversion Action Management
+
+  async mutateConversionActions(
+    customerId: string,
+    operations: MutateOperation[]
+  ): Promise<Record<string, any>> {
+    let cid = customerId.replace(/-/g, '');
+    let response = await this.http.post(`/customers/${cid}/conversionActions:mutate`, {
+      operations
+    });
+    return response.data;
+  }
+
+  // Keyword Planning
+
+  async generateKeywordIdeas(
+    customerId: string,
+    params: {
+      language?: string;
+      geoTargetConstants?: string[];
+      keywordSeed?: { keywords: string[] };
+      urlSeed?: { url: string };
+      keywordAndUrlSeed?: { keywords: string[]; url: string };
+      includeAdultKeywords?: boolean;
+      pageSize?: number;
+      pageToken?: string;
+    }
+  ): Promise<Record<string, any>> {
+    let cid = customerId.replace(/-/g, '');
+    let response = await this.http.post(`/customers/${cid}:generateKeywordIdeas`, params);
+    return response.data;
+  }
+
+  // Offline Conversion Upload
+
+  async uploadClickConversions(
+    customerId: string,
+    conversions: Record<string, any>[],
+    partialFailure?: boolean
+  ): Promise<Record<string, any>> {
+    let cid = customerId.replace(/-/g, '');
+    let response = await this.http.post(`/customers/${cid}:uploadClickConversions`, {
+      conversions,
+      partialFailure: partialFailure ?? true
+    });
+    return response.data;
+  }
+
+  // Audience / User List Management
+
+  async mutateUserLists(
+    customerId: string,
+    operations: MutateOperation[]
+  ): Promise<Record<string, any>> {
+    let cid = customerId.replace(/-/g, '');
+    let response = await this.http.post(`/customers/${cid}/userLists:mutate`, {
+      operations
+    });
+    return response.data;
+  }
+}

package/src/lib/helpers.ts

@@ -0,0 +1,20 @@
+import { GoogleAdsClient } from './client';
+
+export interface AuthOutput {
+  token: string;
+  refreshToken?: string;
+  expiresAt?: string;
+  developerToken: string;
+}
+
+export interface ConfigOutput {
+  loginCustomerId?: string;
+}
+
+export let createClient = (auth: AuthOutput, config: ConfigOutput): GoogleAdsClient => {
+  return new GoogleAdsClient({
+    token: auth.token,
+    developerToken: auth.developerToken,
+    loginCustomerId: config.loginCustomerId
+  });
+};

package/src/provider.contract.test.ts

@@ -0,0 +1,75 @@
+import { createLocalSlateTestClient, expectSlateContract } from '@slates/test';
+import { describe, expect, it } from 'vitest';
+import { provider } from './index';
+import { googleAdsActionScopes } from './scopes';
+
+describe('google-ads provider contract', () => {
+  it('exposes the expected provider, tool, trigger, and auth surface', async () => {
+    let client = createLocalSlateTestClient({ slate: provider as any });
+    let contract = await expectSlateContract({
+      client,
+      provider: {
+        id: 'google-ads',
+        name: 'Google Ads',
+        description:
+          'Google Ads integration for managing campaigns, ad groups, ads, keywords, bidding strategies, conversion tracking, audience targeting, and reporting across Google Search, Display, Video, and Shopping networks.'
+      },
+      toolIds: [
+        'list_accounts',
+        'search_reports',
+        'manage_campaigns',
+        'manage_ad_groups',
+        'manage_ads',
+        'manage_keywords',
+        'manage_bidding_strategies',
+        'manage_conversion_actions',
+        'generate_keyword_ideas',
+        'upload_offline_conversions',
+        'manage_audience_lists'
+      ],
+      triggerIds: ['lead_form_submit'],
+      authMethodIds: ['google_oauth'],
+      tools: [
+        { id: 'list_accounts', readOnly: true, destructive: false },
+        { id: 'search_reports', readOnly: true, destructive: false },
+        { id: 'manage_campaigns', readOnly: false, destructive: false },
+        { id: 'manage_ad_groups', readOnly: false, destructive: false },
+        { id: 'manage_ads', readOnly: false, destructive: false },
+        { id: 'manage_keywords', readOnly: false, destructive: false },
+        { id: 'manage_bidding_strategies', readOnly: false, destructive: false },
+        { id: 'manage_conversion_actions', readOnly: false, destructive: false },
+        { id: 'generate_keyword_ideas', readOnly: true, destructive: false },
+        { id: 'upload_offline_conversions', readOnly: false, destructive: false },
+        { id: 'manage_audience_lists', readOnly: false, destructive: false }
+      ],
+      triggers: [{ id: 'lead_form_submit', invocationType: 'webhook' }]
+    });
+
+    expect(contract.actions).toHaveLength(12);
+    expect(Object.keys(contract.configSchema.properties ?? {})).toEqual(['loginCustomerId']);
+
+    let expectedScopes = {
+      list_accounts: googleAdsActionScopes.listAccounts,
+      search_reports: googleAdsActionScopes.searchReports,
+      manage_campaigns: googleAdsActionScopes.manageCampaigns,
+      manage_ad_groups: googleAdsActionScopes.manageAdGroups,
+      manage_ads: googleAdsActionScopes.manageAds,
+      manage_keywords: googleAdsActionScopes.manageKeywords,
+      manage_bidding_strategies: googleAdsActionScopes.manageBiddingStrategies,
+      manage_conversion_actions: googleAdsActionScopes.manageConversionActions,
+      generate_keyword_ideas: googleAdsActionScopes.generateKeywordIdeas,
+      upload_offline_conversions: googleAdsActionScopes.uploadOfflineConversions,
+      manage_audience_lists: googleAdsActionScopes.manageAudienceLists,
+      lead_form_submit: googleAdsActionScopes.leadFormSubmit
+    };
+
+    for (let [actionId, scopes] of Object.entries(expectedScopes)) {
+      expect(contract.actions.find(action => action.id === actionId)?.scopes).toEqual(scopes);
+    }
+
+    let oauth = await client.getAuthMethod('google_oauth');
+    expect(oauth.authenticationMethod.type).toBe('auth.oauth');
+    expect(oauth.authenticationMethod.capabilities.handleTokenRefresh?.enabled).toBe(true);
+    expect(oauth.authenticationMethod.capabilities.getProfile?.enabled).toBe(true);
+  });
+});

package/src/scopes.ts

@@ -0,0 +1,22 @@
+import { anyOf } from 'slates';
+
+export let googleAdsScopes = {
+  adwords: 'https://www.googleapis.com/auth/adwords'
+} as const;
+
+let adwordsAccess = anyOf(googleAdsScopes.adwords);
+
+export let googleAdsActionScopes = {
+  listAccounts: adwordsAccess,
+  searchReports: adwordsAccess,
+  manageCampaigns: adwordsAccess,
+  manageAdGroups: adwordsAccess,
+  manageAds: adwordsAccess,
+  manageKeywords: adwordsAccess,
+  manageBiddingStrategies: adwordsAccess,
+  manageConversionActions: adwordsAccess,
+  generateKeywordIdeas: adwordsAccess,
+  uploadOfflineConversions: adwordsAccess,
+  manageAudienceLists: adwordsAccess,
+  leadFormSubmit: adwordsAccess
+} as const;

package/src/spec.ts

@@ -0,0 +1,13 @@
+import { SlateSpecification } from 'slates';
+import { auth } from './auth';
+import { config } from './config';
+
+export let spec = SlateSpecification.create({
+  key: 'google-ads',
+  name: 'Google Ads',
+  description:
+    'Google Ads integration for managing campaigns, ad groups, ads, keywords, bidding strategies, conversion tracking, audience targeting, and reporting across Google Search, Display, Video, and Shopping networks.',
+  metadata: {},
+  config,
+  auth
+});

package/src/tools/generate-keyword-ideas.ts

@@ -0,0 +1,114 @@
+import { SlateTool } from 'slates';
+import { googleAdsActionScopes } from '../scopes';
+import { spec } from '../spec';
+import { createClient } from '../lib/helpers';
+import { z } from 'zod';
+
+export let generateKeywordIdeas = SlateTool.create(spec, {
+  name: 'Generate Keyword Ideas',
+  key: 'generate_keyword_ideas',
+  description: `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.`,
+  instructions: [
+    'Provide at least one of: seed keywords or a URL to generate ideas from.',
+    'Language and geo target constants use resource name format, e.g., "languageConstants/1000" for English, "geoTargetConstants/2840" for United States.'
+  ],
+  tags: {
+    readOnly: true
+  }
+})
+  .scopes(googleAdsActionScopes.generateKeywordIdeas)
+  .input(
+    z.object({
+      customerId: z.string().describe('The Google Ads customer account ID'),
+      seedKeywords: z
+        .array(z.string())
+        .optional()
+        .describe('Seed keywords to generate ideas from'),
+      url: z.string().optional().describe('URL to extract keyword ideas from'),
+      language: z
+        .string()
+        .optional()
+        .describe('Language resource name (e.g., "languageConstants/1000" for English)'),
+      geoTargetConstants: z
+        .array(z.string())
+        .optional()
+        .describe('Geo target resource names (e.g., ["geoTargetConstants/2840"] for US)'),
+      includeAdultKeywords: z
+        .boolean()
+        .optional()
+        .describe('Whether to include adult keywords'),
+      pageSize: z.number().optional().describe('Maximum number of keyword ideas to return'),
+      pageToken: z.string().optional().describe('Page token for pagination')
+    })
+  )
+  .output(
+    z.object({
+      keywordIdeas: z
+        .array(
+          z.object({
+            text: z.string().optional().describe('The keyword text'),
+            avgMonthlySearches: z.string().optional().describe('Average monthly searches'),
+            competition: z
+              .string()
+              .optional()
+              .describe('Competition level (LOW, MEDIUM, HIGH)'),
+            competitionIndex: z.number().optional().describe('Competition index 0-100'),
+            lowTopOfPageBidMicros: z
+              .string()
+              .optional()
+              .describe('Low range of top-of-page bid in micros'),
+            highTopOfPageBidMicros: z
+              .string()
+              .optional()
+              .describe('High range of top-of-page bid in micros')
+          })
+        )
+        .describe('List of keyword ideas with metrics'),
+      nextPageToken: z.string().optional().describe('Token for the next page of results'),
+      totalSize: z.string().optional().describe('Total number of keyword ideas available')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = createClient(ctx.auth, ctx.config);
+    let { customerId } = ctx.input;
+
+    let params: Record<string, any> = {};
+
+    if (ctx.input.language) params.language = ctx.input.language;
+    if (ctx.input.geoTargetConstants) params.geoTargetConstants = ctx.input.geoTargetConstants;
+    if (ctx.input.includeAdultKeywords)
+      params.includeAdultKeywords = ctx.input.includeAdultKeywords;
+    if (ctx.input.pageSize) params.pageSize = ctx.input.pageSize;
+    if (ctx.input.pageToken) params.pageToken = ctx.input.pageToken;
+
+    if (ctx.input.seedKeywords && ctx.input.url) {
+      params.keywordAndUrlSeed = { keywords: ctx.input.seedKeywords, url: ctx.input.url };
+    } else if (ctx.input.seedKeywords) {
+      params.keywordSeed = { keywords: ctx.input.seedKeywords };
+    } else if (ctx.input.url) {
+      params.urlSeed = { url: ctx.input.url };
+    }
+
+    let response = await client.generateKeywordIdeas(customerId, params);
+
+    let keywordIdeas = (response.results || []).map((idea: any) => ({
+      text: idea.text,
+      avgMonthlySearches: idea.keywordIdeaMetrics?.avgMonthlySearches?.toString(),
+      competition: idea.keywordIdeaMetrics?.competition,
+      competitionIndex: idea.keywordIdeaMetrics?.competitionIndex,
+      lowTopOfPageBidMicros: idea.keywordIdeaMetrics?.lowTopOfPageBidMicros?.toString(),
+      highTopOfPageBidMicros: idea.keywordIdeaMetrics?.highTopOfPageBidMicros?.toString()
+    }));
+
+    return {
+      output: {
+        keywordIdeas,
+        nextPageToken: response.nextPageToken,
+        totalSize: response.totalSize?.toString()
+      },
+      message: `Generated **${keywordIdeas.length}** keyword idea(s).`
+    };
+  })
+  .build();

package/src/tools/index.ts

@@ -0,0 +1,11 @@
+export * from './list-accounts';
+export * from './search-reports';
+export * from './manage-campaigns';
+export * from './manage-ad-groups';
+export * from './manage-ads';
+export * from './manage-keywords';
+export * from './manage-bidding-strategies';
+export * from './manage-conversion-actions';
+export * from './generate-keyword-ideas';
+export * from './upload-offline-conversions';
+export * from './manage-audience-lists';

package/src/tools/list-accounts.ts

@@ -0,0 +1,90 @@
+import { SlateTool } from 'slates';
+import { googleAdsActionScopes } from '../scopes';
+import { spec } from '../spec';
+import { createClient } from '../lib/helpers';
+import { z } from 'zod';
+
+export let listAccounts = SlateTool.create(spec, {
+  name: 'List Accounts',
+  key: 'list_accounts',
+  description: `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.`,
+  tags: {
+    readOnly: true
+  }
+})
+  .scopes(googleAdsActionScopes.listAccounts)
+  .input(
+    z.object({
+      includeDetails: z
+        .boolean()
+        .optional()
+        .describe(
+          'If true, fetches detailed information (name, currency, timezone) for each account. If false, returns only resource names.'
+        )
+    })
+  )
+  .output(
+    z.object({
+      accounts: z
+        .array(
+          z.object({
+            resourceName: z
+              .string()
+              .describe('Resource name in format customers/{customer_id}'),
+            customerId: z.string().optional().describe('The customer account ID'),
+            name: z.string().optional().describe('Descriptive name of the account'),
+            currencyCode: z.string().optional().describe('Currency code (e.g., USD, EUR)'),
+            timeZone: z.string().optional().describe('Account timezone'),
+            isManager: z.boolean().optional().describe('Whether this is a manager account'),
+            status: z.string().optional().describe('Account status')
+          })
+        )
+        .describe('List of accessible accounts')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = createClient(ctx.auth, ctx.config);
+
+    let resourceNames = await client.listAccessibleCustomers();
+
+    let accounts: {
+      resourceName: string;
+      customerId?: string;
+      name?: string;
+      currencyCode?: string;
+      timeZone?: string;
+      isManager?: boolean;
+      status?: string;
+    }[] = [];
+
+    if (ctx.input.includeDetails) {
+      for (let resourceName of resourceNames) {
+        let customerId = resourceName.replace('customers/', '');
+        try {
+          let customer = await client.getCustomer(customerId);
+          accounts.push({
+            resourceName,
+            customerId: customer.id?.toString(),
+            name: customer.descriptiveName,
+            currencyCode: customer.currencyCode,
+            timeZone: customer.timeZone,
+            isManager: customer.manager,
+            status: customer.status
+          });
+        } catch {
+          accounts.push({ resourceName, customerId });
+        }
+      }
+    } else {
+      accounts = resourceNames.map(rn => ({
+        resourceName: rn,
+        customerId: rn.replace('customers/', '')
+      }));
+    }
+
+    return {
+      output: { accounts },
+      message: `Found **${accounts.length}** accessible Google Ads account(s).`
+    };
+  })
+  .build();