@hasna/connectors 0.9.3 → 1.0.0

package/connectors/connect-googleads/src/api/campaigns.ts

@@ -0,0 +1,252 @@
+import { GoogleAdsClient } from './client';
+import type { Campaign, CampaignBudget, SearchResponse, MutateResponse, CampaignStatus } from '../types';
+
+export class CampaignsApi {
+  constructor(private client: GoogleAdsClient) {}
+
+  /**
+   * List all campaigns
+   */
+  async list(options?: { status?: CampaignStatus; limit?: number }): Promise<SearchResponse> {
+    let query = `
+      SELECT
+        campaign.id,
+        campaign.name,
+        campaign.status,
+        campaign.advertising_channel_type,
+        campaign.bidding_strategy_type,
+        campaign.campaign_budget,
+        campaign.start_date,
+        campaign.end_date,
+        metrics.impressions,
+        metrics.clicks,
+        metrics.cost_micros,
+        metrics.conversions,
+        metrics.ctr,
+        metrics.average_cpc
+      FROM campaign
+    `;
+
+    const conditions: string[] = [];
+
+    if (options?.status) {
+      conditions.push(`campaign.status = '${options.status}'`);
+    }
+
+    if (conditions.length > 0) {
+      query += ` WHERE ${conditions.join(' AND ')}`;
+    }
+
+    query += ` ORDER BY campaign.name`;
+
+    if (options?.limit) {
+      query += ` LIMIT ${options.limit}`;
+    }
+
+    return this.client.search(query);
+  }
+
+  /**
+   * Get a specific campaign
+   */
+  async get(campaignId: string): Promise<SearchResponse> {
+    return this.client.search(`
+      SELECT
+        campaign.id,
+        campaign.name,
+        campaign.status,
+        campaign.advertising_channel_type,
+        campaign.advertising_channel_sub_type,
+        campaign.bidding_strategy_type,
+        campaign.campaign_budget,
+        campaign.start_date,
+        campaign.end_date,
+        campaign.target_spend.target_spend_micros,
+        campaign.target_spend.cpc_bid_ceiling_micros,
+        campaign.manual_cpc.enhanced_cpc_enabled,
+        campaign.maximize_conversions.target_cpa_micros,
+        campaign.maximize_conversion_value.target_roas,
+        metrics.impressions,
+        metrics.clicks,
+        metrics.cost_micros,
+        metrics.conversions,
+        metrics.conversions_value,
+        metrics.ctr,
+        metrics.average_cpc
+      FROM campaign
+      WHERE campaign.id = ${campaignId}
+    `);
+  }
+
+  /**
+   * Create a new campaign
+   */
+  async create(
+    name: string,
+    budgetAmountMicros: string,
+    channelType: string,
+    options?: {
+      status?: CampaignStatus;
+      biddingStrategy?: string;
+      startDate?: string;
+      endDate?: string;
+    }
+  ): Promise<MutateResponse> {
+    const customerId = (this.client as any).getCustomerId();
+
+    // First create the budget
+    const budgetResponse = await this.client.mutate('campaignBudgets', [{
+      create: {
+        name: `Budget for ${name}`,
+        amountMicros: budgetAmountMicros,
+        deliveryMethod: 'STANDARD',
+      }
+    }]);
+
+    const budgetResourceName = budgetResponse.results[0].resourceName;
+
+    // Then create the campaign
+    const campaign: Record<string, unknown> = {
+      name,
+      advertisingChannelType: channelType,
+      status: options?.status || 'PAUSED',
+      campaignBudget: budgetResourceName,
+    };
+
+    if (options?.startDate) {
+      campaign.startDate = options.startDate;
+    }
+
+    if (options?.endDate) {
+      campaign.endDate = options.endDate;
+    }
+
+    // Default to maximize clicks if no bidding strategy specified
+    if (!options?.biddingStrategy || options.biddingStrategy === 'MAXIMIZE_CLICKS') {
+      campaign.targetSpend = {};
+    } else if (options.biddingStrategy === 'MANUAL_CPC') {
+      campaign.manualCpc = { enhancedCpcEnabled: false };
+    }
+
+    return this.client.mutate('campaigns', [{ create: campaign }]);
+  }
+
+  /**
+   * Update a campaign
+   */
+  async update(
+    campaignId: string,
+    updates: {
+      name?: string;
+      status?: CampaignStatus;
+      startDate?: string;
+      endDate?: string;
+    }
+  ): Promise<MutateResponse> {
+    const customerId = (this.client as any).getCustomerId();
+    const resourceName = `customers/${customerId}/campaigns/${campaignId}`;
+
+    const campaign: Record<string, unknown> = {
+      resourceName,
+      ...updates,
+    };
+
+    const updateMask = Object.keys(updates).map(k =>
+      k.replace(/([A-Z])/g, '_$1').toLowerCase()
+    ).join(',');
+
+    return this.client.mutate('campaigns', [{
+      update: campaign,
+      updateMask,
+    }]);
+  }
+
+  /**
+   * Pause a campaign
+   */
+  async pause(campaignId: string): Promise<MutateResponse> {
+    return this.update(campaignId, { status: 'PAUSED' });
+  }
+
+  /**
+   * Enable a campaign
+   */
+  async enable(campaignId: string): Promise<MutateResponse> {
+    return this.update(campaignId, { status: 'ENABLED' });
+  }
+
+  /**
+   * Remove a campaign
+   */
+  async remove(campaignId: string): Promise<MutateResponse> {
+    const customerId = (this.client as any).getCustomerId();
+    const resourceName = `customers/${customerId}/campaigns/${campaignId}`;
+
+    return this.client.mutate('campaigns', [{
+      remove: resourceName,
+    }]);
+  }
+
+  /**
+   * Get campaign performance report
+   */
+  async getPerformance(
+    campaignId: string,
+    startDate: string,
+    endDate: string
+  ): Promise<SearchResponse> {
+    return this.client.search(`
+      SELECT
+        segments.date,
+        metrics.impressions,
+        metrics.clicks,
+        metrics.cost_micros,
+        metrics.conversions,
+        metrics.conversions_value,
+        metrics.ctr,
+        metrics.average_cpc,
+        metrics.average_cpm,
+        metrics.search_impression_share,
+        metrics.search_rank_lost_impression_share,
+        metrics.search_budget_lost_impression_share
+      FROM campaign
+      WHERE campaign.id = ${campaignId}
+        AND segments.date BETWEEN '${startDate}' AND '${endDate}'
+      ORDER BY segments.date
+    `);
+  }
+
+  /**
+   * List campaign budgets
+   */
+  async listBudgets(): Promise<SearchResponse> {
+    return this.client.search(`
+      SELECT
+        campaign_budget.id,
+        campaign_budget.name,
+        campaign_budget.amount_micros,
+        campaign_budget.delivery_method,
+        campaign_budget.explicitly_shared,
+        campaign_budget.total_amount_micros,
+        campaign_budget.status
+      FROM campaign_budget
+      ORDER BY campaign_budget.name
+    `);
+  }
+
+  /**
+   * Update campaign budget
+   */
+  async updateBudget(budgetId: string, amountMicros: string): Promise<MutateResponse> {
+    const customerId = (this.client as any).getCustomerId();
+    const resourceName = `customers/${customerId}/campaignBudgets/${budgetId}`;
+
+    return this.client.mutate('campaignBudgets', [{
+      update: {
+        resourceName,
+        amountMicros,
+      },
+      updateMask: 'amount_micros',
+    }]);
+  }
+}

package/connectors/connect-googleads/src/api/client.ts

@@ -0,0 +1,214 @@
+import type { GoogleAdsConfig, SearchResponse, MutateResponse, GoogleAdsError as GoogleAdsErrorType } from '../types';
+import { GoogleAdsError } from '../types';
+
+const DEFAULT_API_VERSION = 'v20';
+const BASE_URL = 'https://googleads.googleapis.com';
+
+export class GoogleAdsClient {
+  private accessToken?: string;
+  private developerToken?: string;
+  private customerId?: string;
+  private loginCustomerId?: string;
+  private apiVersion: string;
+
+  constructor(config: GoogleAdsConfig) {
+    this.accessToken = config.accessToken;
+    this.developerToken = config.developerToken;
+    this.customerId = config.customerId;
+    this.loginCustomerId = config.loginCustomerId;
+    this.apiVersion = config.apiVersion || DEFAULT_API_VERSION;
+  }
+
+  private getHeaders(): Record<string, string> {
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+    };
+
+    if (this.accessToken) {
+      headers['Authorization'] = `Bearer ${this.accessToken}`;
+    }
+
+    if (this.developerToken) {
+      headers['developer-token'] = this.developerToken;
+    }
+
+    if (this.loginCustomerId) {
+      headers['login-customer-id'] = this.loginCustomerId;
+    }
+
+    return headers;
+  }
+
+  private getCustomerId(): string {
+    if (!this.customerId) {
+      throw new Error('Customer ID not set. Use --customer or set default with "connect-googleads config set-customer"');
+    }
+    return this.customerId.replace(/-/g, '');
+  }
+
+  setCustomerId(customerId: string): void {
+    this.customerId = customerId.replace(/-/g, '');
+  }
+
+  private async handleResponse<T>(response: Response): Promise<T> {
+    if (!response.ok) {
+      const errorBody = await response.json().catch(() => ({}));
+
+      if (errorBody.error) {
+        const details = errorBody.error.details?.[0];
+        throw new GoogleAdsError(
+          errorBody.error.message,
+          errorBody.error.code,
+          details?.errors,
+          details?.requestId
+        );
+      }
+
+      throw new GoogleAdsError(
+        `HTTP ${response.status}: ${response.statusText}`,
+        response.status
+      );
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Execute a Google Ads Query Language (GAQL) query
+   */
+  async search(query: string, pageSize = 10000, pageToken?: string): Promise<SearchResponse> {
+    const customerId = this.getCustomerId();
+    const url = `${BASE_URL}/${this.apiVersion}/customers/${customerId}/googleAds:search`;
+
+    const body: Record<string, unknown> = {
+      query,
+      pageSize,
+    };
+
+    if (pageToken) {
+      body.pageToken = pageToken;
+    }
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: this.getHeaders(),
+      body: JSON.stringify(body),
+    });
+
+    return this.handleResponse<SearchResponse>(response);
+  }
+
+  /**
+   * Execute a streaming search query (returns all results)
+   */
+  async searchStream(query: string): Promise<SearchResponse> {
+    const customerId = this.getCustomerId();
+    const url = `${BASE_URL}/${this.apiVersion}/customers/${customerId}/googleAds:searchStream`;
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: this.getHeaders(),
+      body: JSON.stringify({ query }),
+    });
+
+    // searchStream returns an array of responses
+    const results = await this.handleResponse<SearchResponse[]>(response);
+
+    // Combine all results
+    const combined: SearchResponse = {
+      results: [],
+    };
+
+    for (const result of results) {
+      if (result.results) {
+        combined.results.push(...result.results);
+      }
+    }
+
+    return combined;
+  }
+
+  /**
+   * Mutate resources (create, update, delete)
+   */
+  async mutate(
+    resourceType: string,
+    operations: Array<{ create?: unknown; update?: unknown; remove?: string; updateMask?: string }>,
+    options?: { partialFailure?: boolean; validateOnly?: boolean }
+  ): Promise<MutateResponse> {
+    const customerId = this.getCustomerId();
+    const url = `${BASE_URL}/${this.apiVersion}/customers/${customerId}/${resourceType}:mutate`;
+
+    const body: Record<string, unknown> = {
+      operations,
+    };
+
+    if (options?.partialFailure) {
+      body.partialFailure = true;
+    }
+
+    if (options?.validateOnly) {
+      body.validateOnly = true;
+    }
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: this.getHeaders(),
+      body: JSON.stringify(body),
+    });
+
+    return this.handleResponse<MutateResponse>(response);
+  }
+
+  /**
+   * Get customer details
+   */
+  async getCustomer(): Promise<SearchResponse> {
+    return this.search(`
+      SELECT
+        customer.id,
+        customer.descriptive_name,
+        customer.currency_code,
+        customer.time_zone,
+        customer.auto_tagging_enabled,
+        customer.manager,
+        customer.test_account
+      FROM customer
+      LIMIT 1
+    `);
+  }
+
+  /**
+   * List accessible customers (manager accounts)
+   */
+  async listAccessibleCustomers(): Promise<{ resourceNames: string[] }> {
+    const url = `${BASE_URL}/${this.apiVersion}/customers:listAccessibleCustomers`;
+
+    const response = await fetch(url, {
+      method: 'GET',
+      headers: this.getHeaders(),
+    });
+
+    return this.handleResponse<{ resourceNames: string[] }>(response);
+  }
+
+  /**
+   * Get customer client accounts (for manager accounts)
+   */
+  async getCustomerClients(): Promise<SearchResponse> {
+    return this.search(`
+      SELECT
+        customer_client.client_customer,
+        customer_client.level,
+        customer_client.manager,
+        customer_client.descriptive_name,
+        customer_client.currency_code,
+        customer_client.time_zone,
+        customer_client.id,
+        customer_client.test_account,
+        customer_client.hidden
+      FROM customer_client
+      WHERE customer_client.level <= 1
+    `);
+  }
+}

package/connectors/connect-googleads/src/api/index.ts

@@ -0,0 +1,76 @@
+import { GoogleAdsClient } from './client';
+import { CampaignsApi } from './campaigns';
+import { AdGroupsApi } from './adGroups';
+import { AdsApi } from './ads';
+import { KeywordsApi } from './keywords';
+import { ReportsApi } from './reports';
+import type { GoogleAdsConfig, SearchResponse } from '../types';
+
+export class GoogleAds {
+  private client: GoogleAdsClient;
+
+  public campaigns: CampaignsApi;
+  public adGroups: AdGroupsApi;
+  public ads: AdsApi;
+  public keywords: KeywordsApi;
+  public reports: ReportsApi;
+
+  constructor(config: GoogleAdsConfig) {
+    this.client = new GoogleAdsClient(config);
+
+    this.campaigns = new CampaignsApi(this.client);
+    this.adGroups = new AdGroupsApi(this.client);
+    this.ads = new AdsApi(this.client);
+    this.keywords = new KeywordsApi(this.client);
+    this.reports = new ReportsApi(this.client);
+  }
+
+  /**
+   * Set the customer ID for subsequent requests
+   */
+  setCustomerId(customerId: string): void {
+    this.client.setCustomerId(customerId);
+  }
+
+  /**
+   * Execute a raw GAQL query
+   */
+  async query(gaqlQuery: string): Promise<SearchResponse> {
+    return this.client.search(gaqlQuery);
+  }
+
+  /**
+   * Execute a streaming GAQL query for large datasets
+   */
+  async queryStream(gaqlQuery: string): Promise<SearchResponse> {
+    return this.client.searchStream(gaqlQuery);
+  }
+
+  /**
+   * Get customer account info
+   */
+  async getCustomer(): Promise<SearchResponse> {
+    return this.client.getCustomer();
+  }
+
+  /**
+   * List accessible customers (for manager accounts)
+   */
+  async listAccessibleCustomers(): Promise<{ resourceNames: string[] }> {
+    return this.client.listAccessibleCustomers();
+  }
+
+  /**
+   * Get customer client accounts (for manager accounts)
+   */
+  async getCustomerClients(): Promise<SearchResponse> {
+    return this.client.getCustomerClients();
+  }
+}
+
+export { GoogleAdsClient } from './client';
+export { CampaignsApi } from './campaigns';
+export { AdGroupsApi } from './adGroups';
+export { AdsApi } from './ads';
+export { KeywordsApi } from './keywords';
+export { ReportsApi } from './reports';