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

package/src/tools/manage-campaigns.ts

@@ -0,0 +1,275 @@
+import { SlateTool } from 'slates';
+import { googleAdsActionScopes } from '../scopes';
+import { spec } from '../spec';
+import { createClient } from '../lib/helpers';
+import { z } from 'zod';
+
+let campaignStatusEnum = z.enum(['ENABLED', 'PAUSED', 'REMOVED']).describe('Campaign status');
+
+let campaignTypeEnum = z
+  .enum([
+    'SEARCH',
+    'DISPLAY',
+    'SHOPPING',
+    'VIDEO',
+    'PERFORMANCE_MAX',
+    'MULTI_CHANNEL',
+    'LOCAL',
+    'SMART',
+    'HOTEL',
+    'LOCAL_SERVICES',
+    'DISCOVERY',
+    'TRAVEL',
+    'DEMAND_GEN'
+  ])
+  .describe('Campaign advertising channel type');
+
+export let manageCampaigns = SlateTool.create(spec, {
+  name: 'Manage Campaigns',
+  key: 'manage_campaigns',
+  description: `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 \`dailyBudgetMicros\` is provided. For updating, only the specified fields are modified.`,
+  instructions: [
+    'Monetary values use micros (1 currency unit = 1,000,000 micros). For example, $5.00 = 5000000 micros.',
+    'When removing a campaign, only the campaignId is required.',
+    'Campaign resource names follow the format: customers/{customerId}/campaigns/{campaignId}'
+  ],
+  constraints: ['Campaign type cannot be changed after creation.']
+})
+  .scopes(googleAdsActionScopes.manageCampaigns)
+  .input(
+    z.object({
+      customerId: z.string().describe('The Google Ads customer account ID (without hyphens)'),
+      operation: z.enum(['create', 'update', 'remove']).describe('The operation to perform'),
+      campaignId: z.string().optional().describe('Campaign ID (required for update/remove)'),
+      name: z.string().optional().describe('Campaign name (required for create)'),
+      status: campaignStatusEnum.optional(),
+      advertisingChannelType: campaignTypeEnum
+        .optional()
+        .describe('Campaign type (required for create)'),
+      dailyBudgetMicros: z
+        .string()
+        .optional()
+        .describe(
+          'Daily budget in micros (e.g., "5000000" for $5.00). A budget resource is created automatically for new campaigns.'
+        ),
+      existingBudgetResourceName: z
+        .string()
+        .optional()
+        .describe(
+          'Resource name of an existing campaign budget to use instead of creating one'
+        ),
+      startDate: z.string().optional().describe('Campaign start date in YYYY-MM-DD format'),
+      endDate: z.string().optional().describe('Campaign end date in YYYY-MM-DD format'),
+      biddingStrategyType: z
+        .string()
+        .optional()
+        .describe(
+          'Bidding strategy type, e.g., MANUAL_CPC, MAXIMIZE_CONVERSIONS, TARGET_CPA, TARGET_ROAS'
+        ),
+      targetCpaMicros: z
+        .string()
+        .optional()
+        .describe('Target CPA in micros (for TARGET_CPA bidding)'),
+      targetRoas: z
+        .number()
+        .optional()
+        .describe('Target ROAS value (for TARGET_ROAS bidding, e.g., 3.5 for 350% ROAS)'),
+      networkSettings: z
+        .object({
+          targetGoogleSearch: z.boolean().optional(),
+          targetSearchNetwork: z.boolean().optional(),
+          targetContentNetwork: z.boolean().optional(),
+          targetPartnerSearchNetwork: z.boolean().optional()
+        })
+        .optional()
+        .describe('Network targeting settings')
+    })
+  )
+  .output(
+    z.object({
+      campaignResourceName: z
+        .string()
+        .optional()
+        .describe('Resource name of the created/updated campaign'),
+      budgetResourceName: z
+        .string()
+        .optional()
+        .describe('Resource name of the created budget (if applicable)'),
+      mutateResults: z.any().optional().describe('Raw API mutate 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.campaignId)
+        throw new Error('campaignId is required for remove operation');
+      let result = await client.mutateCampaigns(cid, [
+        {
+          remove: `customers/${cid}/campaigns/${ctx.input.campaignId}`
+        }
+      ]);
+      return {
+        output: {
+          campaignResourceName: `customers/${cid}/campaigns/${ctx.input.campaignId}`,
+          mutateResults: result
+        },
+        message: `Campaign **${ctx.input.campaignId}** has been removed.`
+      };
+    }
+
+    if (operation === 'create') {
+      let budgetResourceName = ctx.input.existingBudgetResourceName;
+
+      if (!budgetResourceName && ctx.input.dailyBudgetMicros) {
+        let budgetResult = await client.mutateCampaignBudgets(cid, [
+          {
+            create: {
+              amountMicros: ctx.input.dailyBudgetMicros,
+              deliveryMethod: 'STANDARD',
+              explicitlyShared: false
+            }
+          }
+        ]);
+        budgetResourceName = budgetResult.results?.[0]?.resourceName;
+      }
+
+      let campaignData: Record<string, any> = {
+        name: ctx.input.name,
+        advertisingChannelType: ctx.input.advertisingChannelType,
+        status: ctx.input.status || 'PAUSED'
+      };
+
+      if (budgetResourceName) campaignData.campaignBudget = budgetResourceName;
+      if (ctx.input.startDate) campaignData.startDate = ctx.input.startDate;
+      if (ctx.input.endDate) campaignData.endDate = ctx.input.endDate;
+      if (ctx.input.networkSettings) campaignData.networkSettings = ctx.input.networkSettings;
+
+      if (ctx.input.biddingStrategyType) {
+        switch (ctx.input.biddingStrategyType) {
+          case 'MANUAL_CPC':
+            campaignData.manualCpc = {};
+            break;
+          case 'MANUAL_CPM':
+            campaignData.manualCpm = {};
+            break;
+          case 'MAXIMIZE_CONVERSIONS':
+            campaignData.maximizeConversions = ctx.input.targetCpaMicros
+              ? { targetCpaMicros: ctx.input.targetCpaMicros }
+              : {};
+            break;
+          case 'MAXIMIZE_CONVERSION_VALUE':
+            campaignData.maximizeConversionValue = ctx.input.targetRoas
+              ? { targetRoas: ctx.input.targetRoas }
+              : {};
+            break;
+          case 'TARGET_CPA':
+            campaignData.targetCpa = { targetCpaMicros: ctx.input.targetCpaMicros };
+            break;
+          case 'TARGET_ROAS':
+            campaignData.targetRoas = { targetRoas: ctx.input.targetRoas };
+            break;
+          case 'TARGET_SPEND':
+            campaignData.targetSpend = {};
+            break;
+        }
+      }
+
+      let result = await client.mutateCampaigns(cid, [{ create: campaignData }]);
+      let campaignResourceName = result.results?.[0]?.resourceName;
+
+      return {
+        output: {
+          campaignResourceName,
+          budgetResourceName,
+          mutateResults: result
+        },
+        message: `Campaign **${ctx.input.name}** created successfully.`
+      };
+    }
+
+    // Update
+    if (!ctx.input.campaignId) throw new Error('campaignId is required for update operation');
+
+    let resourceName = `customers/${cid}/campaigns/${ctx.input.campaignId}`;
+    let updateData: Record<string, any> = { resourceName };
+    let updateMaskFields: string[] = [];
+
+    if (ctx.input.name !== undefined) {
+      updateData.name = ctx.input.name;
+      updateMaskFields.push('name');
+    }
+    if (ctx.input.status !== undefined) {
+      updateData.status = ctx.input.status;
+      updateMaskFields.push('status');
+    }
+    if (ctx.input.startDate !== undefined) {
+      updateData.startDate = ctx.input.startDate;
+      updateMaskFields.push('startDate');
+    }
+    if (ctx.input.endDate !== undefined) {
+      updateData.endDate = ctx.input.endDate;
+      updateMaskFields.push('endDate');
+    }
+    if (ctx.input.networkSettings !== undefined) {
+      updateData.networkSettings = ctx.input.networkSettings;
+      updateMaskFields.push('networkSettings');
+    }
+    if (ctx.input.existingBudgetResourceName !== undefined) {
+      updateData.campaignBudget = ctx.input.existingBudgetResourceName;
+      updateMaskFields.push('campaignBudget');
+    }
+
+    if (ctx.input.biddingStrategyType) {
+      switch (ctx.input.biddingStrategyType) {
+        case 'MANUAL_CPC':
+          updateData.manualCpc = {};
+          updateMaskFields.push('manualCpc');
+          break;
+        case 'MAXIMIZE_CONVERSIONS':
+          updateData.maximizeConversions = ctx.input.targetCpaMicros
+            ? { targetCpaMicros: ctx.input.targetCpaMicros }
+            : {};
+          updateMaskFields.push('maximizeConversions');
+          break;
+        case 'MAXIMIZE_CONVERSION_VALUE':
+          updateData.maximizeConversionValue = ctx.input.targetRoas
+            ? { targetRoas: ctx.input.targetRoas }
+            : {};
+          updateMaskFields.push('maximizeConversionValue');
+          break;
+        case 'TARGET_CPA':
+          updateData.targetCpa = { targetCpaMicros: ctx.input.targetCpaMicros };
+          updateMaskFields.push('targetCpa');
+          break;
+        case 'TARGET_ROAS':
+          updateData.targetRoas = { targetRoas: ctx.input.targetRoas };
+          updateMaskFields.push('targetRoas');
+          break;
+        case 'TARGET_SPEND':
+          updateData.targetSpend = {};
+          updateMaskFields.push('targetSpend');
+          break;
+      }
+    }
+
+    let result = await client.mutateCampaigns(cid, [
+      {
+        update: updateData,
+        updateMask: updateMaskFields.join(',')
+      }
+    ]);
+
+    return {
+      output: {
+        campaignResourceName: resourceName,
+        mutateResults: result
+      },
+      message: `Campaign **${ctx.input.campaignId}** updated (fields: ${updateMaskFields.join(', ')}).`
+    };
+  })
+  .build();

package/src/tools/manage-conversion-actions.ts

@@ -0,0 +1,224 @@
+import { SlateTool } from 'slates';
+import { googleAdsActionScopes } from '../scopes';
+import { spec } from '../spec';
+import { createClient } from '../lib/helpers';
+import { z } from 'zod';
+
+export let manageConversionActions = SlateTool.create(spec, {
+  name: 'Manage Conversion Actions',
+  key: 'manage_conversion_actions',
+  description: `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.`,
+  instructions: [
+    'Common conversion types: PURCHASE, SIGNUP, LEAD, PAGE_VIEW, DOWNLOAD, OTHER',
+    'Categories: DEFAULT, PAGE_VIEW, PURCHASE, SIGNUP, LEAD, DOWNLOAD, ADD_TO_CART, BEGIN_CHECKOUT, SUBSCRIBE_PAID, PHONE_CALL_LEAD, IMPORTED_LEAD, SUBMIT_LEAD_FORM, BOOK_APPOINTMENT, REQUEST_QUOTE, GET_DIRECTIONS, OUTBOUND_CLICK, CONTACT, ENGAGEMENT, STORE_VISIT, STORE_SALE'
+  ]
+})
+  .scopes(googleAdsActionScopes.manageConversionActions)
+  .input(
+    z.object({
+      customerId: z.string().describe('The Google Ads customer account ID'),
+      operation: z.enum(['create', 'update', 'remove']).describe('The operation to perform'),
+      conversionActionId: z
+        .string()
+        .optional()
+        .describe('Conversion action ID (required for update/remove)'),
+      name: z.string().optional().describe('Name of the conversion action'),
+      type: z
+        .enum([
+          'AD_CALL',
+          'CLICK_TO_CALL',
+          'GOOGLE_PLAY_DOWNLOAD',
+          'GOOGLE_PLAY_IN_APP_PURCHASE',
+          'UPLOAD',
+          'UPLOAD_CALLS',
+          'WEBPAGE',
+          'WEBSITE_CALL',
+          'STORE_SALES_DIRECT_UPLOAD',
+          'STORE_SALES',
+          'FIREBASE_ANDROID_FIRST_OPEN',
+          'FIREBASE_ANDROID_IN_APP_PURCHASE',
+          'FIREBASE_IOS_FIRST_OPEN',
+          'FIREBASE_IOS_IN_APP_PURCHASE',
+          'GOOGLE_HOSTED',
+          'LEAD_FORM_SUBMIT',
+          'SALESFORCE',
+          'SEARCH_ADS_360',
+          'SMART_CAMPAIGN_AD_CLICKS_TO_CALL',
+          'SMART_CAMPAIGN_MAP_CLICKS_TO_CALL',
+          'SMART_CAMPAIGN_MAP_DIRECTIONS',
+          'SMART_CAMPAIGN_TRACKED_CALLS',
+          'STORE_VISITS',
+          'WEBPAGE_CODELESS'
+        ])
+        .optional()
+        .describe('Conversion action type (required for create)'),
+      category: z.string().optional().describe('Conversion category'),
+      status: z
+        .enum(['ENABLED', 'REMOVED', 'HIDDEN'])
+        .optional()
+        .describe('Conversion action status'),
+      countingType: z
+        .enum(['ONE_PER_CLICK', 'MANY_PER_CLICK'])
+        .optional()
+        .describe('How conversions are counted'),
+      defaultValue: z.number().optional().describe('Default conversion value'),
+      alwaysUseDefaultValue: z
+        .boolean()
+        .optional()
+        .describe('Whether to always use the default value'),
+      clickThroughLookbackWindowDays: z
+        .number()
+        .optional()
+        .describe('Click-through conversion window in days (1-90)'),
+      viewThroughLookbackWindowDays: z
+        .number()
+        .optional()
+        .describe('View-through conversion window in days (1-90)'),
+      attributionModel: z
+        .enum([
+          'EXTERNAL',
+          'GOOGLE_ADS_LAST_CLICK',
+          'GOOGLE_SEARCH_ATTRIBUTION_FIRST_CLICK',
+          'GOOGLE_SEARCH_ATTRIBUTION_LINEAR',
+          'GOOGLE_SEARCH_ATTRIBUTION_TIME_DECAY',
+          'GOOGLE_SEARCH_ATTRIBUTION_POSITION_BASED',
+          'GOOGLE_SEARCH_ATTRIBUTION_DATA_DRIVEN'
+        ])
+        .optional()
+        .describe('Attribution model'),
+      includeInConversionsMetric: z
+        .boolean()
+        .optional()
+        .describe('Whether to include in the "Conversions" column')
+    })
+  )
+  .output(
+    z.object({
+      conversionActionResourceName: z
+        .string()
+        .optional()
+        .describe('Resource name of the conversion action'),
+      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.conversionActionId) throw new Error('conversionActionId required');
+      let result = await client.mutateConversionActions(cid, [
+        {
+          remove: `customers/${cid}/conversionActions/${ctx.input.conversionActionId}`
+        }
+      ]);
+      return {
+        output: { mutateResults: result },
+        message: `Conversion action **${ctx.input.conversionActionId}** removed.`
+      };
+    }
+
+    if (operation === 'create') {
+      let actionData: Record<string, any> = {
+        name: ctx.input.name,
+        type: ctx.input.type,
+        status: ctx.input.status || 'ENABLED'
+      };
+      if (ctx.input.category) actionData.category = ctx.input.category;
+      if (ctx.input.countingType) actionData.countingType = ctx.input.countingType;
+      if (
+        ctx.input.defaultValue !== undefined ||
+        ctx.input.alwaysUseDefaultValue !== undefined
+      ) {
+        actionData.valueSettings = {};
+        if (ctx.input.defaultValue !== undefined)
+          actionData.valueSettings.defaultValue = ctx.input.defaultValue;
+        if (ctx.input.alwaysUseDefaultValue !== undefined)
+          actionData.valueSettings.alwaysUseDefaultValue = ctx.input.alwaysUseDefaultValue;
+      }
+      if (ctx.input.clickThroughLookbackWindowDays)
+        actionData.clickThroughLookbackWindowDays = ctx.input.clickThroughLookbackWindowDays;
+      if (ctx.input.viewThroughLookbackWindowDays)
+        actionData.viewThroughLookbackWindowDays = ctx.input.viewThroughLookbackWindowDays;
+      if (ctx.input.attributionModel) {
+        actionData.attributionModelSettings = { attributionModel: ctx.input.attributionModel };
+      }
+      if (ctx.input.includeInConversionsMetric !== undefined)
+        actionData.includeInConversionsMetric = ctx.input.includeInConversionsMetric;
+
+      let result = await client.mutateConversionActions(cid, [{ create: actionData }]);
+      return {
+        output: {
+          conversionActionResourceName: result.results?.[0]?.resourceName,
+          mutateResults: result
+        },
+        message: `Conversion action **${ctx.input.name}** created.`
+      };
+    }
+
+    // Update
+    if (!ctx.input.conversionActionId) throw new Error('conversionActionId required');
+    let resourceName = `customers/${cid}/conversionActions/${ctx.input.conversionActionId}`;
+    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.category !== undefined) {
+      updateData.category = ctx.input.category;
+      maskFields.push('category');
+    }
+    if (ctx.input.countingType !== undefined) {
+      updateData.countingType = ctx.input.countingType;
+      maskFields.push('countingType');
+    }
+    if (
+      ctx.input.defaultValue !== undefined ||
+      ctx.input.alwaysUseDefaultValue !== undefined
+    ) {
+      updateData.valueSettings = {};
+      if (ctx.input.defaultValue !== undefined)
+        updateData.valueSettings.defaultValue = ctx.input.defaultValue;
+      if (ctx.input.alwaysUseDefaultValue !== undefined)
+        updateData.valueSettings.alwaysUseDefaultValue = ctx.input.alwaysUseDefaultValue;
+      maskFields.push('valueSettings');
+    }
+    if (ctx.input.clickThroughLookbackWindowDays !== undefined) {
+      updateData.clickThroughLookbackWindowDays = ctx.input.clickThroughLookbackWindowDays;
+      maskFields.push('clickThroughLookbackWindowDays');
+    }
+    if (ctx.input.viewThroughLookbackWindowDays !== undefined) {
+      updateData.viewThroughLookbackWindowDays = ctx.input.viewThroughLookbackWindowDays;
+      maskFields.push('viewThroughLookbackWindowDays');
+    }
+    if (ctx.input.attributionModel !== undefined) {
+      updateData.attributionModelSettings = { attributionModel: ctx.input.attributionModel };
+      maskFields.push('attributionModelSettings');
+    }
+    if (ctx.input.includeInConversionsMetric !== undefined) {
+      updateData.includeInConversionsMetric = ctx.input.includeInConversionsMetric;
+      maskFields.push('includeInConversionsMetric');
+    }
+
+    let result = await client.mutateConversionActions(cid, [
+      {
+        update: updateData,
+        updateMask: maskFields.join(',')
+      }
+    ]);
+
+    return {
+      output: { conversionActionResourceName: resourceName, mutateResults: result },
+      message: `Conversion action **${ctx.input.conversionActionId}** updated (fields: ${maskFields.join(', ')}).`
+    };
+  })
+  .build();

package/src/tools/manage-keywords.ts

@@ -0,0 +1,167 @@
+import { SlateTool } from 'slates';
+import { googleAdsActionScopes } from '../scopes';
+import { spec } from '../spec';
+import { createClient } from '../lib/helpers';
+import { z } from 'zod';
+
+export let manageKeywords = SlateTool.create(spec, {
+  name: 'Manage Keywords',
+  key: 'manage_keywords',
+  description: `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.`,
+  instructions: [
+    'Match types: EXACT (most restrictive), PHRASE (moderate), BROAD (widest reach).',
+    'Use negative keywords to prevent ads from showing for irrelevant searches.',
+    'Set isNegative to true and provide campaignId (for campaign-level) or adGroupId (for ad group-level) negative keywords.'
+  ]
+})
+  .scopes(googleAdsActionScopes.manageKeywords)
+  .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 ad group keywords)'),
+      campaignId: z
+        .string()
+        .optional()
+        .describe('Campaign ID (required for campaign-level negative keywords)'),
+      criterionId: z.string().optional().describe('Criterion ID (required for update/remove)'),
+      keyword: z.string().optional().describe('The keyword text'),
+      matchType: z
+        .enum(['EXACT', 'PHRASE', 'BROAD'])
+        .optional()
+        .describe('Keyword match type'),
+      isNegative: z.boolean().optional().describe('If true, creates a negative keyword'),
+      cpcBidMicros: z.string().optional().describe('Keyword-level CPC bid in micros'),
+      status: z.enum(['ENABLED', 'PAUSED', 'REMOVED']).optional().describe('Keyword status'),
+      finalUrls: z.array(z.string()).optional().describe('Final URLs for the keyword')
+    })
+  )
+  .output(
+    z.object({
+      criterionResourceName: z
+        .string()
+        .optional()
+        .describe('Resource name of the keyword criterion'),
+      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, '');
+
+    // Campaign-level negative keywords
+    if (ctx.input.isNegative && ctx.input.campaignId) {
+      if (operation === 'remove') {
+        if (!ctx.input.criterionId) throw new Error('criterionId required for remove');
+        let result = await client.mutateCampaignCriteria(cid, [
+          {
+            remove: `customers/${cid}/campaignCriteria/${ctx.input.campaignId}~${ctx.input.criterionId}`
+          }
+        ]);
+        return {
+          output: { mutateResults: result },
+          message: `Campaign negative keyword removed.`
+        };
+      }
+
+      if (operation === 'create') {
+        let criterionData: Record<string, any> = {
+          campaign: `customers/${cid}/campaigns/${ctx.input.campaignId}`,
+          negative: true,
+          keyword: {
+            text: ctx.input.keyword,
+            matchType: ctx.input.matchType || 'BROAD'
+          }
+        };
+        let result = await client.mutateCampaignCriteria(cid, [{ create: criterionData }]);
+        return {
+          output: {
+            criterionResourceName: result.results?.[0]?.resourceName,
+            mutateResults: result
+          },
+          message: `Campaign-level negative keyword **"${ctx.input.keyword}"** added.`
+        };
+      }
+    }
+
+    // Ad group keywords
+    if (operation === 'remove') {
+      if (!ctx.input.adGroupId || !ctx.input.criterionId)
+        throw new Error('adGroupId and criterionId required for remove');
+      let result = await client.mutateAdGroupCriteria(cid, [
+        {
+          remove: `customers/${cid}/adGroupCriteria/${ctx.input.adGroupId}~${ctx.input.criterionId}`
+        }
+      ]);
+      return {
+        output: {
+          criterionResourceName: `customers/${cid}/adGroupCriteria/${ctx.input.adGroupId}~${ctx.input.criterionId}`,
+          mutateResults: result
+        },
+        message: `Keyword criterion removed.`
+      };
+    }
+
+    if (operation === 'create') {
+      if (!ctx.input.adGroupId) throw new Error('adGroupId is required for create');
+      let criterionData: Record<string, any> = {
+        adGroup: `customers/${cid}/adGroups/${ctx.input.adGroupId}`,
+        status: ctx.input.status || 'ENABLED',
+        keyword: {
+          text: ctx.input.keyword,
+          matchType: ctx.input.matchType || 'BROAD'
+        }
+      };
+      if (ctx.input.isNegative) criterionData.negative = true;
+      if (ctx.input.cpcBidMicros) criterionData.cpcBidMicros = ctx.input.cpcBidMicros;
+      if (ctx.input.finalUrls) criterionData.finalUrls = ctx.input.finalUrls;
+
+      let result = await client.mutateAdGroupCriteria(cid, [{ create: criterionData }]);
+      return {
+        output: {
+          criterionResourceName: result.results?.[0]?.resourceName,
+          mutateResults: result
+        },
+        message: `Keyword **"${ctx.input.keyword}"** (${ctx.input.matchType || 'BROAD'}) added to ad group.`
+      };
+    }
+
+    // Update
+    if (!ctx.input.adGroupId || !ctx.input.criterionId)
+      throw new Error('adGroupId and criterionId required for update');
+    let resourceName = `customers/${cid}/adGroupCriteria/${ctx.input.adGroupId}~${ctx.input.criterionId}`;
+    let updateData: Record<string, any> = { resourceName };
+    let maskFields: string[] = [];
+
+    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');
+    }
+    if (ctx.input.finalUrls !== undefined) {
+      updateData.finalUrls = ctx.input.finalUrls;
+      maskFields.push('finalUrls');
+    }
+
+    let result = await client.mutateAdGroupCriteria(cid, [
+      {
+        update: updateData,
+        updateMask: maskFields.join(',')
+      }
+    ]);
+
+    return {
+      output: { criterionResourceName: resourceName, mutateResults: result },
+      message: `Keyword criterion updated (fields: ${maskFields.join(', ')}).`
+    };
+  })
+  .build();