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

package/src/tools/manage-ad-groups.ts

@@ -0,0 +1,125 @@
+import { SlateTool } from 'slates';
+import { googleAdsActionScopes } from '../scopes';
+import { spec } from '../spec';
+import { createClient } from '../lib/helpers';
+import { z } from 'zod';
+
+export let manageAdGroups = SlateTool.create(spec, {
+  name: 'Manage Ad Groups',
+  key: 'manage_ad_groups',
+  description: `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.`,
+  instructions: [
+    'CPC bid values use micros (1 currency unit = 1,000,000 micros).',
+    'Ad group resource names follow: customers/{customerId}/adGroups/{adGroupId}'
+  ]
+})
+  .scopes(googleAdsActionScopes.manageAdGroups)
+  .input(
+    z.object({
+      customerId: z.string().describe('The Google Ads customer account ID'),
+      operation: z.enum(['create', 'update', 'remove']).describe('The operation to perform'),
+      adGroupId: z.string().optional().describe('Ad group ID (required for update/remove)'),
+      campaignId: z.string().optional().describe('Campaign ID (required for create)'),
+      name: z.string().optional().describe('Ad group name'),
+      status: z.enum(['ENABLED', 'PAUSED', 'REMOVED']).optional().describe('Ad group status'),
+      type: z
+        .enum([
+          'SEARCH_STANDARD',
+          'DISPLAY_STANDARD',
+          'SHOPPING_PRODUCT_ADS',
+          'VIDEO_BUMPER',
+          'VIDEO_TRUE_VIEW_IN_STREAM',
+          'VIDEO_NON_SKIPPABLE_IN_STREAM'
+        ])
+        .optional()
+        .describe('Ad group type (required for create)'),
+      cpcBidMicros: z.string().optional().describe('CPC bid in micros'),
+      finalUrls: z.array(z.string()).optional().describe('Final URLs for the ad group')
+    })
+  )
+  .output(
+    z.object({
+      adGroupResourceName: z
+        .string()
+        .optional()
+        .describe('Resource name of the created/updated ad group'),
+      mutateResults: z.any().optional().describe('Raw API response')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = createClient(ctx.auth, ctx.config);
+    let { customerId, operation } = ctx.input;
+    let cid = customerId.replace(/-/g, '');
+
+    if (operation === 'remove') {
+      if (!ctx.input.adGroupId) throw new Error('adGroupId is required for remove operation');
+      let result = await client.mutateAdGroups(cid, [
+        {
+          remove: `customers/${cid}/adGroups/${ctx.input.adGroupId}`
+        }
+      ]);
+      return {
+        output: {
+          adGroupResourceName: `customers/${cid}/adGroups/${ctx.input.adGroupId}`,
+          mutateResults: result
+        },
+        message: `Ad group **${ctx.input.adGroupId}** removed.`
+      };
+    }
+
+    if (operation === 'create') {
+      if (!ctx.input.campaignId)
+        throw new Error('campaignId is required for create operation');
+      let adGroupData: Record<string, any> = {
+        name: ctx.input.name,
+        campaign: `customers/${cid}/campaigns/${ctx.input.campaignId}`,
+        status: ctx.input.status || 'ENABLED'
+      };
+      if (ctx.input.type) adGroupData.type = ctx.input.type;
+      if (ctx.input.cpcBidMicros) adGroupData.cpcBidMicros = ctx.input.cpcBidMicros;
+      if (ctx.input.finalUrls) adGroupData.finalUrls = ctx.input.finalUrls;
+
+      let result = await client.mutateAdGroups(cid, [{ create: adGroupData }]);
+      return {
+        output: {
+          adGroupResourceName: result.results?.[0]?.resourceName,
+          mutateResults: result
+        },
+        message: `Ad group **${ctx.input.name}** created.`
+      };
+    }
+
+    // Update
+    if (!ctx.input.adGroupId) throw new Error('adGroupId is required for update operation');
+    let resourceName = `customers/${cid}/adGroups/${ctx.input.adGroupId}`;
+    let updateData: Record<string, any> = { resourceName };
+    let maskFields: string[] = [];
+
+    if (ctx.input.name !== undefined) {
+      updateData.name = ctx.input.name;
+      maskFields.push('name');
+    }
+    if (ctx.input.status !== undefined) {
+      updateData.status = ctx.input.status;
+      maskFields.push('status');
+    }
+    if (ctx.input.cpcBidMicros !== undefined) {
+      updateData.cpcBidMicros = ctx.input.cpcBidMicros;
+      maskFields.push('cpcBidMicros');
+    }
+
+    let result = await client.mutateAdGroups(cid, [
+      {
+        update: updateData,
+        updateMask: maskFields.join(',')
+      }
+    ]);
+
+    return {
+      output: { adGroupResourceName: resourceName, mutateResults: result },
+      message: `Ad group **${ctx.input.adGroupId}** updated (fields: ${maskFields.join(', ')}).`
+    };
+  })
+  .build();

package/src/tools/manage-ads.ts

@@ -0,0 +1,162 @@
+import { SlateTool } from 'slates';
+import { googleAdsActionScopes } from '../scopes';
+import { spec } from '../spec';
+import { createClient } from '../lib/helpers';
+import { z } from 'zod';
+
+export let manageAds = SlateTool.create(spec, {
+  name: 'Manage Ads',
+  key: 'manage_ads',
+  description: `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.`,
+  instructions: [
+    'Responsive search ads require at least 3 headlines and 2 descriptions.',
+    'You can provide up to 15 headlines and 4 descriptions for responsive search ads.',
+    'Use pinnedField to pin a headline/description to a specific position (HEADLINE_1, HEADLINE_2, HEADLINE_3, DESCRIPTION_1, DESCRIPTION_2).'
+  ]
+})
+  .scopes(googleAdsActionScopes.manageAds)
+  .input(
+    z.object({
+      customerId: z.string().describe('The Google Ads customer account ID'),
+      operation: z.enum(['create', 'update', 'remove']).describe('The operation to perform'),
+      adGroupId: z.string().optional().describe('Ad group ID (required for create)'),
+      adGroupAdResourceName: z
+        .string()
+        .optional()
+        .describe(
+          'Full resource name of the ad group ad (required for update/remove, e.g., customers/{id}/adGroupAds/{adGroupId}~{adId})'
+        ),
+      status: z.enum(['ENABLED', 'PAUSED', 'REMOVED']).optional().describe('Ad status'),
+      adType: z
+        .enum(['RESPONSIVE_SEARCH_AD', 'RESPONSIVE_DISPLAY_AD', 'EXPANDED_TEXT_AD'])
+        .optional()
+        .describe('Type of ad to create'),
+      responsiveSearchAd: z
+        .object({
+          headlines: z
+            .array(
+              z.object({
+                text: z.string().describe('Headline text (max 30 chars)'),
+                pinnedField: z.string().optional().describe('Pin position, e.g., HEADLINE_1')
+              })
+            )
+            .describe('List of headlines'),
+          descriptions: z
+            .array(
+              z.object({
+                text: z.string().describe('Description text (max 90 chars)'),
+                pinnedField: z
+                  .string()
+                  .optional()
+                  .describe('Pin position, e.g., DESCRIPTION_1')
+              })
+            )
+            .describe('List of descriptions'),
+          path1: z.string().optional().describe('First part of display URL path'),
+          path2: z.string().optional().describe('Second part of display URL path')
+        })
+        .optional()
+        .describe('Responsive search ad content'),
+      finalUrls: z.array(z.string()).optional().describe('Landing page URLs'),
+      finalMobileUrls: z.array(z.string()).optional().describe('Mobile landing page URLs'),
+      trackingUrlTemplate: z.string().optional().describe('Tracking URL template')
+    })
+  )
+  .output(
+    z.object({
+      adGroupAdResourceName: z
+        .string()
+        .optional()
+        .describe('Resource name of the ad group ad'),
+      mutateResults: z.any().optional().describe('Raw API response')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = createClient(ctx.auth, ctx.config);
+    let { customerId, operation } = ctx.input;
+    let cid = customerId.replace(/-/g, '');
+
+    if (operation === 'remove') {
+      if (!ctx.input.adGroupAdResourceName)
+        throw new Error('adGroupAdResourceName is required for remove');
+      let result = await client.mutateAdGroupAds(cid, [
+        { remove: ctx.input.adGroupAdResourceName }
+      ]);
+      return {
+        output: {
+          adGroupAdResourceName: ctx.input.adGroupAdResourceName,
+          mutateResults: result
+        },
+        message: `Ad removed successfully.`
+      };
+    }
+
+    if (operation === 'create') {
+      if (!ctx.input.adGroupId) throw new Error('adGroupId is required for create');
+
+      let adData: Record<string, any> = {
+        adGroup: `customers/${cid}/adGroups/${ctx.input.adGroupId}`,
+        status: ctx.input.status || 'ENABLED',
+        ad: {} as Record<string, any>
+      };
+
+      if (ctx.input.finalUrls) adData.ad.finalUrls = ctx.input.finalUrls;
+      if (ctx.input.finalMobileUrls) adData.ad.finalMobileUrls = ctx.input.finalMobileUrls;
+      if (ctx.input.trackingUrlTemplate)
+        adData.ad.trackingUrlTemplate = ctx.input.trackingUrlTemplate;
+
+      if (ctx.input.adType === 'RESPONSIVE_SEARCH_AD' && ctx.input.responsiveSearchAd) {
+        let rsa = ctx.input.responsiveSearchAd;
+        adData.ad.responsiveSearchAd = {
+          headlines: rsa.headlines.map(h => ({
+            text: h.text,
+            ...(h.pinnedField ? { pinnedField: h.pinnedField } : {})
+          })),
+          descriptions: rsa.descriptions.map(d => ({
+            text: d.text,
+            ...(d.pinnedField ? { pinnedField: d.pinnedField } : {})
+          }))
+        };
+        if (rsa.path1) adData.ad.responsiveSearchAd.path1 = rsa.path1;
+        if (rsa.path2) adData.ad.responsiveSearchAd.path2 = rsa.path2;
+      }
+
+      let result = await client.mutateAdGroupAds(cid, [{ create: adData }]);
+      return {
+        output: {
+          adGroupAdResourceName: result.results?.[0]?.resourceName,
+          mutateResults: result
+        },
+        message: `Ad created in ad group **${ctx.input.adGroupId}**.`
+      };
+    }
+
+    // Update
+    if (!ctx.input.adGroupAdResourceName)
+      throw new Error('adGroupAdResourceName is required for update');
+    let updateData: Record<string, any> = { resourceName: ctx.input.adGroupAdResourceName };
+    let maskFields: string[] = [];
+
+    if (ctx.input.status !== undefined) {
+      updateData.status = ctx.input.status;
+      maskFields.push('status');
+    }
+
+    let result = await client.mutateAdGroupAds(cid, [
+      {
+        update: updateData,
+        updateMask: maskFields.join(',')
+      }
+    ]);
+
+    return {
+      output: {
+        adGroupAdResourceName: ctx.input.adGroupAdResourceName,
+        mutateResults: result
+      },
+      message: `Ad updated (fields: ${maskFields.join(', ')}).`
+    };
+  })
+  .build();

package/src/tools/manage-audience-lists.ts

@@ -0,0 +1,134 @@
+import { SlateTool } from 'slates';
+import { googleAdsActionScopes } from '../scopes';
+import { spec } from '../spec';
+import { createClient } from '../lib/helpers';
+import { z } from 'zod';
+
+export let manageAudienceLists = SlateTool.create(spec, {
+  name: 'Manage Audience Lists',
+  key: 'manage_audience_lists',
+  description: `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.`,
+  instructions: [
+    'For CRM-based lists, the membershipLifeSpan is in days (set to 10000 for no expiration).',
+    'Membership status can be OPEN (accepting new members) or CLOSED (not accepting).'
+  ]
+})
+  .scopes(googleAdsActionScopes.manageAudienceLists)
+  .input(
+    z.object({
+      customerId: z.string().describe('The Google Ads customer account ID'),
+      operation: z.enum(['create', 'update', 'remove']).describe('The operation to perform'),
+      userListId: z.string().optional().describe('User list ID (required for update/remove)'),
+      name: z.string().optional().describe('User list name'),
+      description: z.string().optional().describe('User list description'),
+      membershipLifeSpan: z
+        .number()
+        .optional()
+        .describe('Number of days a user stays in the list (set 10000 for unlimited)'),
+      membershipStatus: z
+        .enum(['OPEN', 'CLOSED'])
+        .optional()
+        .describe('Whether the list is open or closed for new members'),
+      listType: z
+        .enum(['CRM_BASED', 'RULE_BASED', 'LOGICAL'])
+        .optional()
+        .describe('Type of user list (required for create)'),
+      crmBasedUserList: z
+        .object({
+          uploadKeyType: z
+            .enum(['CONTACT_INFO', 'CRM_ID', 'MOBILE_ADVERTISING_ID'])
+            .optional()
+            .describe('Type of CRM data'),
+          dataSourceType: z
+            .enum(['FIRST_PARTY', 'THIRD_PARTY_CREDIT_BUREAU', 'THIRD_PARTY_VOTER_FILE'])
+            .optional()
+            .describe('Source of the CRM data')
+        })
+        .optional()
+        .describe('CRM-based user list configuration')
+    })
+  )
+  .output(
+    z.object({
+      userListResourceName: z.string().optional().describe('Resource name of the user list'),
+      mutateResults: z.any().optional().describe('Raw API response')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = createClient(ctx.auth, ctx.config);
+    let { customerId, operation } = ctx.input;
+    let cid = customerId.replace(/-/g, '');
+
+    if (operation === 'remove') {
+      if (!ctx.input.userListId) throw new Error('userListId required');
+      let result = await client.mutateUserLists(cid, [
+        {
+          remove: `customers/${cid}/userLists/${ctx.input.userListId}`
+        }
+      ]);
+      return {
+        output: { mutateResults: result },
+        message: `User list **${ctx.input.userListId}** removed.`
+      };
+    }
+
+    if (operation === 'create') {
+      let listData: Record<string, any> = {
+        name: ctx.input.name,
+        membershipStatus: ctx.input.membershipStatus || 'OPEN'
+      };
+      if (ctx.input.description) listData.description = ctx.input.description;
+      if (ctx.input.membershipLifeSpan)
+        listData.membershipLifeSpan = ctx.input.membershipLifeSpan;
+      if (ctx.input.listType === 'CRM_BASED' && ctx.input.crmBasedUserList) {
+        listData.crmBasedUserList = ctx.input.crmBasedUserList;
+      }
+
+      let result = await client.mutateUserLists(cid, [{ create: listData }]);
+      return {
+        output: {
+          userListResourceName: result.results?.[0]?.resourceName,
+          mutateResults: result
+        },
+        message: `User list **${ctx.input.name}** created.`
+      };
+    }
+
+    // Update
+    if (!ctx.input.userListId) throw new Error('userListId required');
+    let resourceName = `customers/${cid}/userLists/${ctx.input.userListId}`;
+    let updateData: Record<string, any> = { resourceName };
+    let maskFields: string[] = [];
+
+    if (ctx.input.name !== undefined) {
+      updateData.name = ctx.input.name;
+      maskFields.push('name');
+    }
+    if (ctx.input.description !== undefined) {
+      updateData.description = ctx.input.description;
+      maskFields.push('description');
+    }
+    if (ctx.input.membershipLifeSpan !== undefined) {
+      updateData.membershipLifeSpan = ctx.input.membershipLifeSpan;
+      maskFields.push('membershipLifeSpan');
+    }
+    if (ctx.input.membershipStatus !== undefined) {
+      updateData.membershipStatus = ctx.input.membershipStatus;
+      maskFields.push('membershipStatus');
+    }
+
+    let result = await client.mutateUserLists(cid, [
+      {
+        update: updateData,
+        updateMask: maskFields.join(',')
+      }
+    ]);
+
+    return {
+      output: { userListResourceName: resourceName, mutateResults: result },
+      message: `User list **${ctx.input.userListId}** updated.`
+    };
+  })
+  .build();

package/src/tools/manage-bidding-strategies.ts

@@ -0,0 +1,153 @@
+import { SlateTool } from 'slates';
+import { googleAdsActionScopes } from '../scopes';
+import { spec } from '../spec';
+import { createClient } from '../lib/helpers';
+import { z } from 'zod';
+
+export let manageBiddingStrategies = SlateTool.create(spec, {
+  name: 'Manage Bidding Strategies',
+  key: 'manage_bidding_strategies',
+  description: `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.`,
+  instructions: [
+    'Provide exactly one strategy configuration (targetCpa, targetRoas, maximizeConversions, maximizeConversionValue, or targetSpend).',
+    'Monetary values use micros (1 currency unit = 1,000,000 micros).'
+  ]
+})
+  .scopes(googleAdsActionScopes.manageBiddingStrategies)
+  .input(
+    z.object({
+      customerId: z.string().describe('The Google Ads customer account ID'),
+      operation: z.enum(['create', 'update', 'remove']).describe('The operation to perform'),
+      biddingStrategyId: z
+        .string()
+        .optional()
+        .describe('Bidding strategy ID (required for update/remove)'),
+      name: z.string().optional().describe('Name for the bidding strategy'),
+      targetCpa: z
+        .object({
+          targetCpaMicros: z.string().optional().describe('Target CPA in micros')
+        })
+        .optional()
+        .describe('Target CPA strategy configuration'),
+      targetRoas: z
+        .object({
+          targetRoas: z.number().optional().describe('Target ROAS value (e.g., 3.5 for 350%)')
+        })
+        .optional()
+        .describe('Target ROAS strategy configuration'),
+      maximizeConversions: z
+        .object({
+          targetCpaMicros: z.string().optional().describe('Optional target CPA limit')
+        })
+        .optional()
+        .describe('Maximize Conversions strategy configuration'),
+      maximizeConversionValue: z
+        .object({
+          targetRoas: z.number().optional().describe('Optional target ROAS limit')
+        })
+        .optional()
+        .describe('Maximize Conversion Value strategy configuration'),
+      targetSpend: z
+        .object({
+          cpcBidCeilingMicros: z
+            .string()
+            .optional()
+            .describe('Maximum CPC bid limit in micros')
+        })
+        .optional()
+        .describe('Target Spend strategy configuration')
+    })
+  )
+  .output(
+    z.object({
+      biddingStrategyResourceName: z
+        .string()
+        .optional()
+        .describe('Resource name of the bidding strategy'),
+      mutateResults: z.any().optional().describe('Raw API response')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = createClient(ctx.auth, ctx.config);
+    let { customerId, operation } = ctx.input;
+    let cid = customerId.replace(/-/g, '');
+
+    if (operation === 'remove') {
+      if (!ctx.input.biddingStrategyId) throw new Error('biddingStrategyId required');
+      let result = await client.mutateBiddingStrategies(cid, [
+        {
+          remove: `customers/${cid}/biddingStrategies/${ctx.input.biddingStrategyId}`
+        }
+      ]);
+      return {
+        output: { mutateResults: result },
+        message: `Bidding strategy **${ctx.input.biddingStrategyId}** removed.`
+      };
+    }
+
+    if (operation === 'create') {
+      let strategyData: Record<string, any> = { name: ctx.input.name };
+      if (ctx.input.targetCpa) strategyData.targetCpa = ctx.input.targetCpa;
+      if (ctx.input.targetRoas) strategyData.targetRoas = ctx.input.targetRoas;
+      if (ctx.input.maximizeConversions)
+        strategyData.maximizeConversions = ctx.input.maximizeConversions;
+      if (ctx.input.maximizeConversionValue)
+        strategyData.maximizeConversionValue = ctx.input.maximizeConversionValue;
+      if (ctx.input.targetSpend) strategyData.targetSpend = ctx.input.targetSpend;
+
+      let result = await client.mutateBiddingStrategies(cid, [{ create: strategyData }]);
+      return {
+        output: {
+          biddingStrategyResourceName: result.results?.[0]?.resourceName,
+          mutateResults: result
+        },
+        message: `Bidding strategy **${ctx.input.name}** created.`
+      };
+    }
+
+    // Update
+    if (!ctx.input.biddingStrategyId) throw new Error('biddingStrategyId required');
+    let resourceName = `customers/${cid}/biddingStrategies/${ctx.input.biddingStrategyId}`;
+    let updateData: Record<string, any> = { resourceName };
+    let maskFields: string[] = [];
+
+    if (ctx.input.name !== undefined) {
+      updateData.name = ctx.input.name;
+      maskFields.push('name');
+    }
+    if (ctx.input.targetCpa) {
+      updateData.targetCpa = ctx.input.targetCpa;
+      maskFields.push('targetCpa');
+    }
+    if (ctx.input.targetRoas) {
+      updateData.targetRoas = ctx.input.targetRoas;
+      maskFields.push('targetRoas');
+    }
+    if (ctx.input.maximizeConversions) {
+      updateData.maximizeConversions = ctx.input.maximizeConversions;
+      maskFields.push('maximizeConversions');
+    }
+    if (ctx.input.maximizeConversionValue) {
+      updateData.maximizeConversionValue = ctx.input.maximizeConversionValue;
+      maskFields.push('maximizeConversionValue');
+    }
+    if (ctx.input.targetSpend) {
+      updateData.targetSpend = ctx.input.targetSpend;
+      maskFields.push('targetSpend');
+    }
+
+    let result = await client.mutateBiddingStrategies(cid, [
+      {
+        update: updateData,
+        updateMask: maskFields.join(',')
+      }
+    ]);
+
+    return {
+      output: { biddingStrategyResourceName: resourceName, mutateResults: result },
+      message: `Bidding strategy **${ctx.input.biddingStrategyId}** updated.`
+    };
+  })
+  .build();