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

package/src/tools/search-reports.ts

@@ -0,0 +1,71 @@
+import { SlateTool } from 'slates';
+import { googleAdsActionScopes } from '../scopes';
+import { spec } from '../spec';
+import { createClient } from '../lib/helpers';
+import { z } from 'zod';
+
+export let searchReports = SlateTool.create(spec, {
+  name: 'Run GAQL Query',
+  key: 'search_reports',
+  description: `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: \`SELECT fields FROM resource WHERE conditions ORDER BY field LIMIT n\`.`,
+  instructions: [
+    'GAQL queries follow the format: SELECT <fields> FROM <resource> [WHERE <conditions>] [ORDER BY <field> [ASC|DESC]] [LIMIT <n>]',
+    'Common resources: campaign, ad_group, ad_group_ad, ad_group_criterion, keyword_view, campaign_budget, bidding_strategy, conversion_action',
+    'Use segments like segments.date to break down metrics by date',
+    'Date ranges can be filtered with segments.date BETWEEN "YYYY-MM-DD" AND "YYYY-MM-DD" or using DURING LAST_30_DAYS, THIS_MONTH, etc.'
+  ],
+  tags: {
+    readOnly: true
+  }
+})
+  .scopes(googleAdsActionScopes.searchReports)
+  .input(
+    z.object({
+      customerId: z.string().describe('The Google Ads customer account ID (without hyphens)'),
+      query: z.string().describe('The GAQL query string to execute'),
+      pageSize: z
+        .number()
+        .optional()
+        .describe('Maximum number of results per page (default: 10000)'),
+      pageToken: z.string().optional().describe('Page token for pagination')
+    })
+  )
+  .output(
+    z.object({
+      results: z
+        .array(z.any())
+        .describe('Array of result rows, each containing the requested fields'),
+      totalResultsCount: z
+        .string()
+        .optional()
+        .describe('Total number of results matching the query'),
+      nextPageToken: z
+        .string()
+        .optional()
+        .describe('Token to retrieve the next page of results')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = createClient(ctx.auth, ctx.config);
+
+    let response = await client.search(
+      ctx.input.customerId,
+      ctx.input.query,
+      ctx.input.pageSize,
+      ctx.input.pageToken
+    );
+
+    let resultCount = response.results?.length ?? 0;
+
+    return {
+      output: {
+        results: response.results || [],
+        totalResultsCount: response.totalResultsCount,
+        nextPageToken: response.nextPageToken
+      },
+      message: `Query returned **${resultCount}** result(s)${response.nextPageToken ? ' (more pages available)' : ''}.`
+    };
+  })
+  .build();

package/src/tools/upload-offline-conversions.ts

@@ -0,0 +1,93 @@
+import { SlateTool } from 'slates';
+import { googleAdsActionScopes } from '../scopes';
+import { spec } from '../spec';
+import { createClient } from '../lib/helpers';
+import { z } from 'zod';
+
+export let uploadOfflineConversions = SlateTool.create(spec, {
+  name: 'Upload Offline Conversions',
+  key: 'upload_offline_conversions',
+  description: `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.`,
+  instructions: [
+    'The gclid is captured when a user clicks on an ad and visits your site. Store it for later upload.',
+    'Conversion date/time should be in the format "yyyy-mm-dd hh:mm:ss+|-hh:mm" (e.g., "2024-01-15 14:30:00-05:00").',
+    'The conversion action resource name must match an existing conversion action in the account.',
+    'Conversions can take up to 3 hours to appear in Google Ads reporting.'
+  ],
+  constraints: [
+    'Click conversions must be uploaded within 90 days of the click.',
+    'Duplicate conversions (same gclid + conversion action + conversion date) are rejected.'
+  ]
+})
+  .scopes(googleAdsActionScopes.uploadOfflineConversions)
+  .input(
+    z.object({
+      customerId: z.string().describe('The Google Ads customer account ID'),
+      conversions: z
+        .array(
+          z.object({
+            gclid: z.string().describe('Google Click ID from the original ad click'),
+            conversionAction: z
+              .string()
+              .describe(
+                'Conversion action resource name (e.g., customers/{id}/conversionActions/{id})'
+              ),
+            conversionDateTime: z
+              .string()
+              .describe('When the conversion occurred, e.g., "2024-01-15 14:30:00-05:00"'),
+            conversionValue: z
+              .number()
+              .optional()
+              .describe('Monetary value of the conversion'),
+            currencyCode: z
+              .string()
+              .optional()
+              .describe('Currency code for the conversion value (e.g., USD)'),
+            orderId: z
+              .string()
+              .optional()
+              .describe('Unique order/transaction ID for deduplication')
+          })
+        )
+        .describe('List of conversions to upload'),
+      partialFailure: z
+        .boolean()
+        .optional()
+        .describe('If true, valid conversions are uploaded even if some fail (default: true)')
+    })
+  )
+  .output(
+    z.object({
+      uploadResults: z.any().describe('Results for each uploaded conversion'),
+      partialFailureError: z.any().optional().describe('Details of any partial failures')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = createClient(ctx.auth, ctx.config);
+
+    let conversions = ctx.input.conversions.map(c => ({
+      gclid: c.gclid,
+      conversionAction: c.conversionAction,
+      conversionDateTime: c.conversionDateTime,
+      conversionValue: c.conversionValue,
+      currencyCode: c.currencyCode,
+      orderId: c.orderId
+    }));
+
+    let result = await client.uploadClickConversions(
+      ctx.input.customerId,
+      conversions,
+      ctx.input.partialFailure
+    );
+
+    return {
+      output: {
+        uploadResults: result.results || result,
+        partialFailureError: result.partialFailureError
+      },
+      message: `Uploaded **${conversions.length}** offline conversion(s).${result.partialFailureError ? ' Some conversions had errors.' : ''}`
+    };
+  })
+  .build();

package/src/triggers/index.ts

@@ -0,0 +1 @@
+export * from './lead-form-submit';

package/src/triggers/lead-form-submit.ts

@@ -0,0 +1,135 @@
+import { SlateTrigger } from 'slates';
+import { googleAdsActionScopes } from '../scopes';
+import { spec } from '../spec';
+import { z } from 'zod';
+
+export let leadFormSubmit = SlateTrigger.create(spec, {
+  name: 'Lead Form Submission',
+  key: 'lead_form_submit',
+  description: `Receives lead form submissions from Google Ads campaigns via webhook. Triggers when a user submits a lead form extension in a Search, Display, YouTube, or Performance Max campaign.
+
+The webhook URL must be configured in the lead form extension settings within Google Ads. Each lead includes the submitted user data, campaign/ad group context, and a Google Click ID.`,
+  instructions: [
+    'Configure the webhook URL in your Google Ads lead form extension settings.',
+    'Use the lead_id for deduplication as Google Ads may retry delivery.',
+    'The is_test field indicates whether the lead was submitted using the "Test" button in Google Ads.'
+  ]
+})
+  .scopes(googleAdsActionScopes.leadFormSubmit)
+  .input(
+    z.object({
+      leadId: z.string().describe('Unique lead identifier for deduplication'),
+      campaignId: z.string().optional().describe('Campaign that generated the lead'),
+      adGroupId: z.string().optional().describe('Ad group that generated the lead'),
+      creativeId: z.string().optional().describe('Creative/ad that generated the lead'),
+      assetGroupId: z
+        .string()
+        .optional()
+        .describe('Asset group ID (only for Performance Max campaigns)'),
+      gclid: z.string().optional().describe('Google Click ID'),
+      isTest: z.boolean().optional().describe('Whether this is a test lead'),
+      userColumnData: z
+        .array(
+          z.object({
+            columnId: z
+              .string()
+              .describe(
+                'Data type identifier (e.g., FULL_NAME, EMAIL, PHONE_NUMBER, POSTAL_CODE, CITY, COUNTRY)'
+              ),
+            stringValue: z.string().describe('The submitted value')
+          })
+        )
+        .optional()
+        .describe('User-submitted form data'),
+      apiVersion: z.string().optional().describe('API version of the webhook payload'),
+      formId: z.string().optional().describe('Lead form ID'),
+      gclidCreatedAt: z.string().optional().describe('Timestamp when the gclid was created')
+    })
+  )
+  .output(
+    z.object({
+      leadId: z.string().describe('Unique lead identifier'),
+      campaignId: z.string().optional().describe('Campaign ID'),
+      adGroupId: z.string().optional().describe('Ad group ID'),
+      creativeId: z.string().optional().describe('Creative/ad ID'),
+      assetGroupId: z.string().optional().describe('Asset group ID (Performance Max only)'),
+      gclid: z.string().optional().describe('Google Click ID for conversion tracking'),
+      isTest: z.boolean().optional().describe('Whether this is a test lead'),
+      formId: z.string().optional().describe('Lead form ID'),
+      userData: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe(
+          'User-submitted data as key-value pairs (e.g., { "FULL_NAME": "John Doe", "EMAIL": "john@example.com" })'
+        )
+    })
+  )
+  .webhook({
+    handleRequest: async ctx => {
+      let data = (await ctx.request.json()) as Record<string, any>;
+
+      let input: {
+        leadId: string;
+        campaignId?: string;
+        adGroupId?: string;
+        creativeId?: string;
+        assetGroupId?: string;
+        gclid?: string;
+        isTest?: boolean;
+        userColumnData?: { columnId: string; stringValue: string }[];
+        apiVersion?: string;
+        formId?: string;
+        gclidCreatedAt?: string;
+      } = {
+        leadId: data.lead_id || data.leadId || '',
+        campaignId: data.campaign_id?.toString() || data.campaignId?.toString(),
+        adGroupId: data.ad_group_id?.toString() || data.adGroupId?.toString(),
+        creativeId: data.creative_id?.toString() || data.creativeId?.toString(),
+        assetGroupId: data.asset_group_id?.toString() || data.assetGroupId?.toString(),
+        gclid: data.gcl_id || data.gclid,
+        isTest: data.is_test ?? data.isTest,
+        apiVersion: data.api_version || data.apiVersion,
+        formId: data.form_id?.toString() || data.formId?.toString(),
+        gclidCreatedAt: data.gclid_created_at || data.gclidCreatedAt
+      };
+
+      if (Array.isArray(data.user_column_data || data.userColumnData)) {
+        input.userColumnData = (data.user_column_data || data.userColumnData).map(
+          (col: any) => ({
+            columnId: col.column_id || col.columnId,
+            stringValue: col.string_value || col.stringValue || ''
+          })
+        );
+      }
+
+      return {
+        inputs: [input]
+      };
+    },
+
+    handleEvent: async ctx => {
+      let userData: Record<string, string> = {};
+      if (ctx.input.userColumnData) {
+        for (let col of ctx.input.userColumnData) {
+          userData[col.columnId] = col.stringValue;
+        }
+      }
+
+      return {
+        type: 'lead_form.submitted',
+        id: ctx.input.leadId,
+        output: {
+          leadId: ctx.input.leadId,
+          campaignId: ctx.input.campaignId,
+          adGroupId: ctx.input.adGroupId,
+          creativeId: ctx.input.creativeId,
+          assetGroupId: ctx.input.assetGroupId,
+          gclid: ctx.input.gclid,
+          isTest: ctx.input.isTest,
+          formId: ctx.input.formId,
+          userData: Object.keys(userData).length > 0 ? userData : undefined
+        }
+      };
+    }
+  })
+  .build();

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "types": ["node"],
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+    "moduleResolution": "bundler",
+
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  },
+  "include": ["src"]
+}

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { createSlatesVitestConfig } from '@slates/test/config';
+
+export default createSlatesVitestConfig({
+  test: {
+    include: ['src/**/*.test.ts', 'src/**/*.e2e.ts']
+  }
+});