@hasna/connectors 1.3.22 → 1.3.24

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

@@ -0,0 +1,354 @@
+import type { GoogleAdsClient } from './client';
+import type { MutateResponse } from '../types';
+
+// ============================================
+// Bulk Operation Types
+// ============================================
+
+export interface BulkOperationOptions {
+  /** Maximum concurrent API calls (default: 10) */
+  concurrency?: number;
+  /** Dry run - don't actually modify */
+  dryRun?: boolean;
+  /** Progress callback */
+  onProgress?: (current: number, total: number, item: unknown) => void;
+  /** Error callback */
+  onError?: (error: Error, item: unknown) => void;
+}
+
+// --- Status Change Bulk Operations ---
+
+export interface StatusChangeEntry {
+  resourceId: string;
+  /** The resource path segment, e.g. 'campaigns', 'adGroups', 'adGroupAds', 'adGroupCriteria' */
+  resourceType: 'campaign' | 'adGroup' | 'ad' | 'keyword';
+  /** Additional identifiers for composite resources */
+  parentId?: string;
+}
+
+export interface BulkStatusChangeOptions extends BulkOperationOptions {
+  /** Entries to update */
+  entries: StatusChangeEntry[];
+  /** Target status */
+  status: 'ENABLED' | 'PAUSED' | 'REMOVED';
+}
+
+export interface BulkStatusChangeResult {
+  total: number;
+  success: number;
+  failed: number;
+  errors: Array<{ resourceId: string; error: string }>;
+  results: Array<{ resourceId: string; response: MutateResponse }>;
+}
+
+// --- Campaign Bulk Operations ---
+
+export interface BulkCampaignOptions extends BulkOperationOptions {
+  campaignIds: string[];
+  status: 'ENABLED' | 'PAUSED' | 'REMOVED';
+}
+
+export interface BulkCampaignResult {
+  total: number;
+  success: number;
+  failed: number;
+  errors: Array<{ campaignId: string; error: string }>;
+  results: Array<{ campaignId: string; response: MutateResponse }>;
+}
+
+// --- Ad Group Bulk Operations ---
+
+export interface BulkAdGroupOptions extends BulkOperationOptions {
+  adGroupIds: string[];
+  status: 'ENABLED' | 'PAUSED';
+}
+
+export interface BulkAdGroupResult {
+  total: number;
+  success: number;
+  failed: number;
+  errors: Array<{ adGroupId: string; error: string }>;
+  results: Array<{ adGroupId: string; response: MutateResponse }>;
+}
+
+// --- Ad Bulk Operations ---
+
+export interface BulkAdOptions extends BulkOperationOptions {
+  /** Entries with adGroupId and adId pairs */
+  entries: Array<{ adGroupId: string; adId: string }>;
+  status: 'ENABLED' | 'PAUSED' | 'REMOVED';
+}
+
+export interface BulkAdResult {
+  total: number;
+  success: number;
+  failed: number;
+  errors: Array<{ adGroupId: string; adId: string; error: string }>;
+  results: Array<{ adGroupId: string; adId: string; response: MutateResponse }>;
+}
+
+// --- Keyword Bulk Operations ---
+
+export interface BulkKeywordOptions extends BulkOperationOptions {
+  /** Entries with adGroupId and criterionId pairs */
+  entries: Array<{ adGroupId: string; criterionId: string }>;
+  status: 'ENABLED' | 'PAUSED' | 'REMOVED';
+}
+
+export interface BulkKeywordResult {
+  total: number;
+  success: number;
+  failed: number;
+  errors: Array<{ adGroupId: string; criterionId: string; error: string }>;
+  results: Array<{ adGroupId: string; criterionId: string; response: MutateResponse }>;
+}
+
+// ============================================
+// Bulk Operations API
+// ============================================
+
+export class BulkApi {
+  private readonly client: GoogleAdsClient;
+
+  constructor(client: GoogleAdsClient) {
+    this.client = client;
+  }
+
+  // ============================================
+  // Bulk Campaign Status Changes
+  // ============================================
+
+  async campaigns(options: BulkCampaignOptions): Promise<BulkCampaignResult> {
+    const { campaignIds, status, concurrency = 10, dryRun = false, onProgress, onError } = options;
+
+    const result: BulkCampaignResult = {
+      total: campaignIds.length,
+      success: 0,
+      failed: 0,
+      errors: [],
+      results: [],
+    };
+
+    if (campaignIds.length === 0) return result;
+
+    const chunks = this.chunkArray(campaignIds, concurrency);
+
+    for (const chunk of chunks) {
+      await Promise.all(
+        chunk.map(async (campaignId) => {
+          try {
+            if (dryRun) {
+              result.success++;
+            } else {
+              const operation = status === 'REMOVED'
+                ? { remove: `customers/${this.client.getCustomerId()}/campaigns/${campaignId}` }
+                : {
+                    update: {
+                      resourceName: `customers/${this.client.getCustomerId()}/campaigns/${campaignId}`,
+                      status,
+                    },
+                    updateMask: 'status',
+                  };
+
+              const response = await this.client.mutate('campaigns', [operation]);
+              result.success++;
+              result.results.push({ campaignId, response });
+            }
+
+            if (onProgress) onProgress(result.success + result.failed, result.total, campaignId);
+          } catch (err) {
+            result.failed++;
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            result.errors.push({ campaignId, error: errorMessage });
+            if (onError) onError(err instanceof Error ? err : new Error(errorMessage), campaignId);
+          }
+        })
+      );
+    }
+
+    return result;
+  }
+
+  // ============================================
+  // Bulk Ad Group Status Changes
+  // ============================================
+
+  async adGroups(options: BulkAdGroupOptions): Promise<BulkAdGroupResult> {
+    const { adGroupIds, status, concurrency = 10, dryRun = false, onProgress, onError } = options;
+
+    const result: BulkAdGroupResult = {
+      total: adGroupIds.length,
+      success: 0,
+      failed: 0,
+      errors: [],
+      results: [],
+    };
+
+    if (adGroupIds.length === 0) return result;
+
+    const chunks = this.chunkArray(adGroupIds, concurrency);
+
+    for (const chunk of chunks) {
+      await Promise.all(
+        chunk.map(async (adGroupId) => {
+          try {
+            if (dryRun) {
+              result.success++;
+            } else {
+              const operation = {
+                update: {
+                  resourceName: `customers/${this.client.getCustomerId()}/adGroups/${adGroupId}`,
+                  status,
+                },
+                updateMask: 'status',
+              };
+
+              const response = await this.client.mutate('adGroups', [operation]);
+              result.success++;
+              result.results.push({ adGroupId, response });
+            }
+
+            if (onProgress) onProgress(result.success + result.failed, result.total, adGroupId);
+          } catch (err) {
+            result.failed++;
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            result.errors.push({ adGroupId, error: errorMessage });
+            if (onError) onError(err instanceof Error ? err : new Error(errorMessage), adGroupId);
+          }
+        })
+      );
+    }
+
+    return result;
+  }
+
+  // ============================================
+  // Bulk Ad Status Changes
+  // ============================================
+
+  async ads(options: BulkAdOptions): Promise<BulkAdResult> {
+    const { entries, status, concurrency = 10, dryRun = false, onProgress, onError } = options;
+
+    const result: BulkAdResult = {
+      total: entries.length,
+      success: 0,
+      failed: 0,
+      errors: [],
+      results: [],
+    };
+
+    if (entries.length === 0) return result;
+
+    const chunks = this.chunkArray(entries, concurrency);
+
+    for (const chunk of chunks) {
+      await Promise.all(
+        chunk.map(async (entry) => {
+          try {
+            if (dryRun) {
+              result.success++;
+            } else {
+              const operation = status === 'REMOVED'
+                ? { remove: `customers/${this.client.getCustomerId()}/adGroupAds/${entry.adGroupId}~${entry.adId}` }
+                : {
+                    update: {
+                      resourceName: `customers/${this.client.getCustomerId()}/adGroupAds/${entry.adGroupId}~${entry.adId}`,
+                      status,
+                    },
+                    updateMask: 'status',
+                  };
+
+              const response = await this.client.mutate('adGroupAds', [operation]);
+              result.success++;
+              result.results.push({ adGroupId: entry.adGroupId, adId: entry.adId, response });
+            }
+
+            if (onProgress) onProgress(result.success + result.failed, result.total, entry);
+          } catch (err) {
+            result.failed++;
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            result.errors.push({
+              adGroupId: entry.adGroupId,
+              adId: entry.adId,
+              error: errorMessage,
+            });
+            if (onError) onError(err instanceof Error ? err : new Error(errorMessage), entry);
+          }
+        })
+      );
+    }
+
+    return result;
+  }
+
+  // ============================================
+  // Bulk Keyword Status Changes
+  // ============================================
+
+  async keywords(options: BulkKeywordOptions): Promise<BulkKeywordResult> {
+    const { entries, status, concurrency = 10, dryRun = false, onProgress, onError } = options;
+
+    const result: BulkKeywordResult = {
+      total: entries.length,
+      success: 0,
+      failed: 0,
+      errors: [],
+      results: [],
+    };
+
+    if (entries.length === 0) return result;
+
+    const chunks = this.chunkArray(entries, concurrency);
+
+    for (const chunk of chunks) {
+      await Promise.all(
+        chunk.map(async (entry) => {
+          try {
+            if (dryRun) {
+              result.success++;
+            } else {
+              const operation = status === 'REMOVED'
+                ? { remove: `customers/${this.client.getCustomerId()}/adGroupCriteria/${entry.adGroupId}~${entry.criterionId}` }
+                : {
+                    update: {
+                      resourceName: `customers/${this.client.getCustomerId()}/adGroupCriteria/${entry.adGroupId}~${entry.criterionId}`,
+                      status,
+                    },
+                    updateMask: 'status',
+                  };
+
+              const response = await this.client.mutate('adGroupCriteria', [operation]);
+              result.success++;
+              result.results.push({ adGroupId: entry.adGroupId, criterionId: entry.criterionId, response });
+            }
+
+            if (onProgress) onProgress(result.success + result.failed, result.total, entry);
+          } catch (err) {
+            result.failed++;
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            result.errors.push({
+              adGroupId: entry.adGroupId,
+              criterionId: entry.criterionId,
+              error: errorMessage,
+            });
+            if (onError) onError(err instanceof Error ? err : new Error(errorMessage), entry);
+          }
+        })
+      );
+    }
+
+    return result;
+  }
+
+  // ============================================
+  // Helper Methods
+  // ============================================
+
+  private chunkArray<T>(array: T[], size: number): T[][] {
+    const chunks: T[][] = [];
+    for (let i = 0; i < array.length; i += size) {
+      chunks.push(array.slice(i, i + size));
+    }
+    return chunks;
+  }
+}

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

@@ -4,6 +4,7 @@ import { AdGroupsApi } from './adGroups';
 import { AdsApi } from './ads';
 import { KeywordsApi } from './keywords';
 import { ReportsApi } from './reports';
+import { BulkApi } from './bulk';
 import type { GoogleAdsConfig, SearchResponse } from '../types';
 
 export class GoogleAds {
@@ -14,6 +15,7 @@ export class GoogleAds {
   public ads: AdsApi;
   public keywords: KeywordsApi;
   public reports: ReportsApi;
+  public bulk: BulkApi;
 
   constructor(config: GoogleAdsConfig) {
     this.client = new GoogleAdsClient(config);
@@ -23,6 +25,7 @@ export class GoogleAds {
     this.ads = new AdsApi(this.client);
     this.keywords = new KeywordsApi(this.client);
     this.reports = new ReportsApi(this.client);
+    this.bulk = new BulkApi(this.client);
   }
 
   /**
@@ -74,3 +77,4 @@ export { AdGroupsApi } from './adGroups';
 export { AdsApi } from './ads';
 export { KeywordsApi } from './keywords';
 export { ReportsApi } from './reports';
+export { BulkApi } from './bulk';

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

@@ -1252,6 +1252,198 @@ reports
     }
   });
 
+// ============================================
+// Bulk Commands
+// ============================================
+
+const bulk = program.command('bulk').description('Bulk operations');
+
+bulk
+  .command('campaigns')
+  .description('Bulk update campaign status')
+  .requiredOption('--ids <ids>', 'Comma-separated campaign IDs')
+  .requiredOption('--status <status>', 'Target status (ENABLED, PAUSED, REMOVED)')
+  .option('--concurrency <number>', 'Max concurrent requests', '10')
+  .option('--dry-run', 'Preview without making changes')
+  .action(async (opts) => {
+    const campaignIds = opts.ids.split(',').map((id: string) => id.trim()).filter(Boolean);
+    const concurrency = parseInt(opts.concurrency, 10);
+
+    if (campaignIds.length === 0) {
+      error('No campaign IDs provided');
+      process.exit(1);
+    }
+
+    const client = await getClient(program.opts().customer);
+    info(`Updating ${campaignIds.length} campaign(s) to ${opts.status}...`);
+    if (opts.dryRun) info('(dry run)');
+
+    const result = await client.bulk.campaigns({
+      campaignIds,
+      status: opts.status,
+      concurrency,
+      dryRun: opts.dryRun,
+      onProgress: (current, total) => {
+        process.stdout.write(`\rProgress: ${current}/${total}`);
+      },
+      onError: (err, id) => {
+        console.error(`\n  Failed: ${id} - ${err.message}`);
+      },
+    });
+
+    console.log();
+    success(`Done: ${result.success} updated, ${result.failed} failed`);
+    if (result.errors.length > 0) {
+      warn('Errors:');
+      for (const e of result.errors) {
+        console.log(`  - ${e.campaignId}: ${e.error}`);
+      }
+    }
+  });
+
+bulk
+  .command('adgroups')
+  .description('Bulk update ad group status')
+  .requiredOption('--ids <ids>', 'Comma-separated ad group IDs')
+  .requiredOption('--status <status>', 'Target status (ENABLED, PAUSED)')
+  .option('--concurrency <number>', 'Max concurrent requests', '10')
+  .option('--dry-run', 'Preview without making changes')
+  .action(async (opts) => {
+    const adGroupIds = opts.ids.split(',').map((id: string) => id.trim()).filter(Boolean);
+    const concurrency = parseInt(opts.concurrency, 10);
+
+    if (adGroupIds.length === 0) {
+      error('No ad group IDs provided');
+      process.exit(1);
+    }
+
+    const client = await getClient(program.opts().customer);
+    info(`Updating ${adGroupIds.length} ad group(s) to ${opts.status}...`);
+    if (opts.dryRun) info('(dry run)');
+
+    const result = await client.bulk.adGroups({
+      adGroupIds,
+      status: opts.status,
+      concurrency,
+      dryRun: opts.dryRun,
+      onProgress: (current, total) => {
+        process.stdout.write(`\rProgress: ${current}/${total}`);
+      },
+      onError: (err, id) => {
+        console.error(`\n  Failed: ${id} - ${err.message}`);
+      },
+    });
+
+    console.log();
+    success(`Done: ${result.success} updated, ${result.failed} failed`);
+    if (result.errors.length > 0) {
+      warn('Errors:');
+      for (const e of result.errors) {
+        console.log(`  - ${e.adGroupId}: ${e.error}`);
+      }
+    }
+  });
+
+bulk
+  .command('ads')
+  .description('Bulk update ad status')
+  .requiredOption('--entries <entries>', 'JSON array of {adGroupId, adId}')
+  .requiredOption('--status <status>', 'Target status (ENABLED, PAUSED, REMOVED)')
+  .option('--concurrency <number>', 'Max concurrent requests', '10')
+  .option('--dry-run', 'Preview without making changes')
+  .action(async (opts) => {
+    let entries: Array<{ adGroupId: string; adId: string }>;
+    try {
+      entries = JSON.parse(opts.entries) as Array<{ adGroupId: string; adId: string }>;
+    } catch {
+      error('Invalid JSON for --entries');
+      process.exit(1);
+    }
+
+    if (entries.length === 0) {
+      error('No entries provided');
+      process.exit(1);
+    }
+
+    const client = await getClient(program.opts().customer);
+    const concurrency = parseInt(opts.concurrency, 10);
+    info(`Updating ${entries.length} ad(s)...`);
+    if (opts.dryRun) info('(dry run)');
+
+    const result = await client.bulk.ads({
+      entries,
+      status: opts.status,
+      concurrency,
+      dryRun: opts.dryRun,
+      onProgress: (current, total) => {
+        process.stdout.write(`\rProgress: ${current}/${total}`);
+      },
+      onError: (err, entry) => {
+        const e = entry as { adGroupId: string; adId: string };
+        console.error(`\n  Failed: ${e.adGroupId}/${e.adId} - ${err.message}`);
+      },
+    });
+
+    console.log();
+    success(`Done: ${result.success} updated, ${result.failed} failed`);
+    if (result.errors.length > 0) {
+      warn('Errors:');
+      for (const e of result.errors) {
+        console.log(`  - ${e.adGroupId}/${e.adId}: ${e.error}`);
+      }
+    }
+  });
+
+bulk
+  .command('keywords')
+  .description('Bulk update keyword status')
+  .requiredOption('--entries <entries>', 'JSON array of {adGroupId, criterionId}')
+  .requiredOption('--status <status>', 'Target status (ENABLED, PAUSED, REMOVED)')
+  .option('--concurrency <number>', 'Max concurrent requests', '10')
+  .option('--dry-run', 'Preview without making changes')
+  .action(async (opts) => {
+    let entries: Array<{ adGroupId: string; criterionId: string }>;
+    try {
+      entries = JSON.parse(opts.entries) as Array<{ adGroupId: string; criterionId: string }>;
+    } catch {
+      error('Invalid JSON for --entries');
+      process.exit(1);
+    }
+
+    if (entries.length === 0) {
+      error('No entries provided');
+      process.exit(1);
+    }
+
+    const client = await getClient(program.opts().customer);
+    const concurrency = parseInt(opts.concurrency, 10);
+    info(`Updating ${entries.length} keyword(s)...`);
+    if (opts.dryRun) info('(dry run)');
+
+    const result = await client.bulk.keywords({
+      entries,
+      status: opts.status,
+      concurrency,
+      dryRun: opts.dryRun,
+      onProgress: (current, total) => {
+        process.stdout.write(`\rProgress: ${current}/${total}`);
+      },
+      onError: (err, entry) => {
+        const e = entry as { adGroupId: string; criterionId: string };
+        console.error(`\n  Failed: ${e.adGroupId}/${e.criterionId} - ${err.message}`);
+      },
+    });
+
+    console.log();
+    success(`Done: ${result.success} updated, ${result.failed} failed`);
+    if (result.errors.length > 0) {
+      warn('Errors:');
+      for (const e of result.errors) {
+        console.log(`  - ${e.adGroupId}/${e.criterionId}: ${e.error}`);
+      }
+    }
+  });
+
 // ============================================
 // Parse and Execute
 // ============================================

package/connectors/connect-googlecalendar/src/api/acl.ts

@@ -0,0 +1,66 @@
+import type { GoogleCalendarClient } from './client';
+import type { CalendarAcl, CalendarAclListResponse, CalendarAclInsert } from '../types';
+
+/**
+ * Calendar ACL API module - manage calendar access control lists
+ */
+export class AclApi {
+  constructor(private readonly client: GoogleCalendarClient) {}
+
+  /**
+   * List ACL rules for a calendar
+   */
+  async list(calendarId: string, options: { maxResults?: number; pageToken?: string } = {}): Promise<CalendarAclListResponse> {
+    const params: Record<string, number | string | undefined> = {};
+    if (options.maxResults) params.maxResults = options.maxResults;
+    if (options.pageToken) params.pageToken = options.pageToken;
+    return this.client.get<CalendarAclListResponse>(`/calendars/${encodeURIComponent(calendarId)}/acl`, params);
+  }
+
+  /**
+   * Iterate over all ACL rules (handles pagination)
+   */
+  async *listAll(calendarId: string): AsyncGenerator<CalendarAcl> {
+    let nextPageToken: string | undefined;
+    do {
+      const result = await this.list(calendarId, { pageToken: nextPageToken });
+      for (const rule of result.items) {
+        yield rule;
+      }
+      nextPageToken = result.nextPageToken;
+    } while (nextPageToken);
+  }
+
+  /**
+   * Get a specific ACL rule
+   */
+  async get(calendarId: string, ruleId: string): Promise<CalendarAcl> {
+    return this.client.get<CalendarAcl>(`/calendars/${encodeURIComponent(calendarId)}/acl/${encodeURIComponent(ruleId)}`);
+  }
+
+  /**
+   * Insert a new ACL rule
+   */
+  async insert(calendarId: string, rule: CalendarAclInsert): Promise<CalendarAcl> {
+    return this.client.post<CalendarAcl>(`/calendars/${encodeURIComponent(calendarId)}/acl`, {
+      role: rule.role,
+      scope: rule.scope,
+    });
+  }
+
+  /**
+   * Delete an ACL rule
+   */
+  async delete(calendarId: string, ruleId: string): Promise<void> {
+    await this.client.delete<void>(`/calendars/${encodeURIComponent(calendarId)}/acl/${encodeURIComponent(ruleId)}`);
+  }
+
+  /**
+   * Update an ACL rule
+   */
+  async update(calendarId: string, ruleId: string, role: CalendarAclInsert['role']): Promise<CalendarAcl> {
+    return this.client.patch<CalendarAcl>(`/calendars/${encodeURIComponent(calendarId)}/acl/${encodeURIComponent(ruleId)}`, {
+      role,
+    });
+  }
+}