@hasna/connectors 1.3.22 → 1.3.24

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

@@ -4,6 +4,8 @@ import chalk from 'chalk';
 import { createServer } from 'http';
 import { GoogleContacts } from '../api';
 import { ContactsApi } from '../api/contacts';
+import { BulkApi } from '../api/bulk';
+import type { ContactSummary } from '../api/bulk';
 import {
   getClientId,
   setClientId,
@@ -675,5 +677,343 @@ contactsCmd
     }
   });
 
+// ============================================
+// Groups Commands — CRUD + membership
+// ============================================
+const groupsCmd = program
+  .command('groups')
+  .description('Manage contact groups (CRUD + membership)');
+
+groupsCmd
+  .command('list')
+  .description('List contact groups')
+  .option('-n, --max <number>', 'Maximum results', '100')
+  .option('--page-token <token>', 'Page token for pagination')
+  .action(async (opts) => {
+    try {
+      const client = await getClient();
+      const result = await client.groups.list({
+        pageSize: parseInt(opts.max),
+        pageToken: opts.pageToken,
+      });
+      print(result, getFormat(groupsCmd));
+      if ((result as any).nextPageToken) {
+        info(`More results available. Use --page-token ${(result as any).nextPageToken}`);
+      }
+    } catch (err) {
+      error(String(err));
+      process.exit(1);
+    }
+  });
+
+groupsCmd
+  .command('get <groupResourceName>')
+  .description('Get a contact group')
+  .action(async (groupResourceName: string) => {
+    try {
+      const client = await getClient();
+      const group = await client.groups.get(groupResourceName);
+      print(group, getFormat(groupsCmd));
+    } catch (err) {
+      error(String(err));
+      process.exit(1);
+    }
+  });
+
+groupsCmd
+  .command('create')
+  .description('Create a new contact group')
+  .requiredOption('--name <name>', 'Group name')
+  .action(async (opts) => {
+    try {
+      const client = await getClient();
+      const group = await client.groups.create({ name: opts.name });
+      success(`Group created: ${group.resourceName}`);
+      print(group, getFormat(groupsCmd));
+    } catch (err) {
+      error(String(err));
+      process.exit(1);
+    }
+  });
+
+groupsCmd
+  .command('update <groupResourceName>')
+  .description('Update a contact group')
+  .requiredOption('--name <name>', 'New group name')
+  .action(async (groupResourceName: string, opts) => {
+    try {
+      const client = await getClient();
+      const group = await client.groups.update(groupResourceName, { name: opts.name });
+      success(`Group updated: ${group.resourceName}`);
+      print(group, getFormat(groupsCmd));
+    } catch (err) {
+      error(String(err));
+      process.exit(1);
+    }
+  });
+
+groupsCmd
+  .command('delete <groupResourceName>')
+  .description('Delete a contact group')
+  .action(async (groupResourceName: string) => {
+    try {
+      const client = await getClient();
+      await client.groups.delete(groupResourceName);
+      success(`Group ${groupResourceName} deleted`);
+    } catch (err) {
+      error(String(err));
+      process.exit(1);
+    }
+  });
+
+groupsCmd
+  .command('members <groupResourceName>')
+  .description('List members of a contact group')
+  .option('-n, --max <number>', 'Maximum results', '100')
+  .option('--page-token <token>', 'Page token for pagination')
+  .action(async (groupResourceName: string, opts) => {
+    try {
+      const client = await getClient();
+      const result = await client.groups.getMembers(groupResourceName, {
+        pageSize: parseInt(opts.max),
+        pageToken: opts.pageToken,
+      });
+      print(result, getFormat(groupsCmd));
+      if (result.nextPageToken) {
+        info(`More results available. Use --page-token ${result.nextPageToken}`);
+      }
+    } catch (err) {
+      error(String(err));
+      process.exit(1);
+    }
+  });
+
+groupsCmd
+  .command('add-member <groupResourceName> <contactResourceName>')
+  .description('Add a contact to a group')
+  .action(async (groupResourceName: string, contactResourceName: string) => {
+    try {
+      const client = await getClient();
+      await client.groups.addMember(groupResourceName, contactResourceName);
+      success(`Contact ${contactResourceName} added to group ${groupResourceName}`);
+    } catch (err) {
+      error(String(err));
+      process.exit(1);
+    }
+  });
+
+groupsCmd
+  .command('remove-member <groupResourceName> <contactResourceName>')
+  .description('Remove a contact from a group')
+  .action(async (groupResourceName: string, contactResourceName: string) => {
+    try {
+      const client = await getClient();
+      await client.groups.removeMember(groupResourceName, contactResourceName);
+      success(`Contact ${contactResourceName} removed from group ${groupResourceName}`);
+    } catch (err) {
+      error(String(err));
+      process.exit(1);
+    }
+  });
+
+// ============================================
+// Bulk Commands
+// ============================================
+const bulkCmd = program
+  .command('bulk')
+  .description('Bulk operations on contacts');
+
+function makeProgress(total: number) {
+  let last = 0;
+  return (current: number) => {
+    if (current !== last) {
+      process.stdout.write(`\r  Progress: ${current}/${total}`);
+      last = current;
+    }
+  };
+}
+
+bulkCmd
+  .command('preview')
+  .description('Preview contacts matching a query')
+  .option('-q, --query <query>', 'Search query')
+  .option('-n, --max <number>', 'Maximum results', '50')
+  .action(async (opts) => {
+    try {
+      const client = await getClient();
+      const bulk = new BulkApi(client.getClient());
+      const result = await bulk.preview({ query: opts.query, maxResults: parseInt(opts.max) });
+      success(`Found ${result.total} contact(s):`);
+      print(result.contacts, getFormat(bulkCmd));
+    } catch (err) {
+      error(String(err));
+      process.exit(1);
+    }
+  });
+
+bulkCmd
+  .command('delete')
+  .description('Bulk delete contacts matching a query')
+  .option('-q, --query <query>', 'Search query')
+  .option('-n, --max <number>', 'Maximum results', '100')
+  .option('--concurrency <number>', 'Max concurrent operations', '10')
+  .option('--dry-run', 'Preview without deleting')
+  .option('--confirm', 'Confirm deletion')
+  .action(async (opts) => {
+    if (!opts.confirm && !opts.dryRun) {
+      warn('This will delete contacts. Use --dry-run to preview or --confirm to proceed.');
+      process.exit(1);
+    }
+    try {
+      const client = await getClient();
+      const bulk = new BulkApi(client.getClient());
+      const progress = makeProgress(0);
+      const result = await bulk.delete({
+        query: opts.query,
+        maxResults: parseInt(opts.max),
+        concurrency: parseInt(opts.concurrency),
+        dryRun: opts.dryRun || false,
+        onProgress: (cur, total) => { progress(total); progress(cur); },
+        onError: (err, contact) => { warn(`Failed: ${contact.displayName} - ${err.message}`); },
+      });
+      process.stdout.write('\n');
+      if (opts.dryRun) {
+        info(`Dry run: would delete ${result.success} contact(s)`);
+      } else {
+        success(`Deleted ${result.success} contact(s), ${result.failed} failed`);
+      }
+      if (result.errors.length > 0) {
+        print(result.errors, 'pretty');
+      }
+    } catch (err) {
+      error(String(err));
+      process.exit(1);
+    }
+  });
+
+bulkCmd
+  .command('update')
+  .description('Bulk update contacts matching a query')
+  .option('-q, --query <query>', 'Search query')
+  .option('-n, --max <number>', 'Maximum results', '100')
+  .option('--concurrency <number>', 'Max concurrent operations', '10')
+  .option('--dry-run', 'Preview without updating')
+  .option('--given-name <name>', 'New given name')
+  .option('--family-name <name>', 'New family name')
+  .option('--organization <org>', 'New organization')
+  .option('--title <title>', 'New job title')
+  .action(async (opts) => {
+    if (!opts.givenName && !opts.familyName && !opts.organization && !opts.title) {
+      error('At least one update field is required (--given-name, --family-name, --organization, --title)');
+      process.exit(1);
+    }
+    try {
+      const client = await getClient();
+      const bulk = new BulkApi(client.getClient());
+      const result = await bulk.update({
+        query: opts.query,
+        maxResults: parseInt(opts.max),
+        concurrency: parseInt(opts.concurrency),
+        dryRun: opts.dryRun || false,
+        updates: {
+          givenName: opts.givenName,
+          familyName: opts.familyName,
+          organization: opts.organization || opts.title ? {
+            name: opts.organization,
+            title: opts.title,
+          } : undefined,
+        },
+        onProgress: (cur, total) => { process.stdout.write(`\r  Progress: ${cur}/${total}`); },
+        onError: (err, contact) => { warn(`Failed: ${contact.displayName} - ${err.message}`); },
+      });
+      process.stdout.write('\n');
+      if (opts.dryRun) {
+        info(`Dry run: would update ${result.success} contact(s)`);
+      } else {
+        success(`Updated ${result.success} contact(s), ${result.failed} failed`);
+      }
+      if (result.errors.length > 0) {
+        print(result.errors, 'pretty');
+      }
+    } catch (err) {
+      error(String(err));
+      process.exit(1);
+    }
+  });
+
+bulkCmd
+  .command('add-to-group <groupResourceName>')
+  .description('Bulk add contacts to a group')
+  .option('-q, --query <query>', 'Search query')
+  .option('--contact-names <names>', 'Comma-separated contact resource names')
+  .option('-n, --max <number>', 'Maximum results', '100')
+  .option('--concurrency <number>', 'Max concurrent operations', '10')
+  .option('--dry-run', 'Preview without adding')
+  .action(async (groupResourceName: string, opts) => {
+    try {
+      const client = await getClient();
+      const bulk = new BulkApi(client.getClient());
+      const contactNames = opts.contactNames ? opts.contactNames.split(',') : undefined;
+      const result = await bulk.addToGroup(groupResourceName, {
+        contactNames,
+        query: opts.query,
+        maxResults: parseInt(opts.max),
+        concurrency: parseInt(opts.concurrency),
+        dryRun: opts.dryRun || false,
+        onProgress: (cur, total) => { process.stdout.write(`\r  Progress: ${cur}/${total}`); },
+        onError: (err, contact) => { warn(`Failed: ${contact.displayName} - ${err.message}`); },
+      });
+      process.stdout.write('\n');
+      if (opts.dryRun) {
+        info(`Dry run: would add ${result.success} contact(s) to group`);
+      } else {
+        success(`Added ${result.success} contact(s) to group, ${result.failed} failed`);
+      }
+      if (result.errors.length > 0) {
+        print(result.errors, 'pretty');
+      }
+    } catch (err) {
+      error(String(err));
+      process.exit(1);
+    }
+  });
+
+bulkCmd
+  .command('remove-from-group <groupResourceName>')
+  .description('Bulk remove contacts from a group')
+  .option('-q, --query <query>', 'Search query')
+  .option('--contact-names <names>', 'Comma-separated contact resource names')
+  .option('-n, --max <number>', 'Maximum results', '100')
+  .option('--concurrency <number>', 'Max concurrent operations', '10')
+  .option('--dry-run', 'Preview without removing')
+  .action(async (groupResourceName: string, opts) => {
+    try {
+      const client = await getClient();
+      const bulk = new BulkApi(client.getClient());
+      const contactNames = opts.contactNames ? opts.contactNames.split(',') : undefined;
+      const result = await bulk.removeFromGroup(groupResourceName, {
+        contactNames,
+        query: opts.query,
+        maxResults: parseInt(opts.max),
+        concurrency: parseInt(opts.concurrency),
+        dryRun: opts.dryRun || false,
+        onProgress: (cur, total) => { process.stdout.write(`\r  Progress: ${cur}/${total}`); },
+        onError: (err, contact) => { warn(`Failed: ${contact.displayName} - ${err.message}`); },
+      });
+      process.stdout.write('\n');
+      if (opts.dryRun) {
+        info(`Dry run: would remove ${result.success} contact(s) from group`);
+      } else {
+        success(`Removed ${result.success} contact(s) from group, ${result.failed} failed`);
+      }
+      if (result.errors.length > 0) {
+        print(result.errors, 'pretty');
+      }
+    } catch (err) {
+      error(String(err));
+      process.exit(1);
+    }
+  });
+
 // Parse and execute
 program.parse();

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

@@ -0,0 +1,301 @@
+import type { GoogleDocsClient } from './client';
+import type { Document, Request, BatchUpdateResponse } from '../types';
+
+// ============================================
+// Bulk Operation Types
+// ============================================
+
+export interface DocumentSummary {
+  documentId: string;
+  title: string;
+}
+
+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;
+}
+
+export interface BulkCreateDocumentsOptions extends BulkOperationOptions {
+  /** Document titles to create */
+  titles: string[];
+}
+
+export interface BulkCreateDocumentsResult {
+  total: number;
+  success: number;
+  failed: number;
+  errors: Array<{ title: string; error: string }>;
+  createdDocuments: DocumentSummary[];
+}
+
+export interface FindReplaceEntry {
+  documentId: string;
+  find: string;
+  replace: string;
+  matchCase?: boolean;
+}
+
+export interface BulkFindReplaceOptions extends BulkOperationOptions {
+  /** Find/replace entries per document */
+  entries: FindReplaceEntry[];
+}
+
+export interface FindReplaceResult {
+  documentId: string;
+  occurrencesChanged: number;
+  find: string;
+  replace: string;
+}
+
+export interface BulkFindReplaceResult {
+  total: number;
+  success: number;
+  failed: number;
+  errors: Array<{ documentId: string; find: string; error: string }>;
+  results: FindReplaceResult[];
+}
+
+export interface BulkOperationEntry {
+  documentId: string;
+  requests: Request[];
+}
+
+export interface BulkBatchUpdateOptions extends BulkOperationOptions {
+  /** Batch update entries */
+  entries: BulkOperationEntry[];
+}
+
+export interface BulkBatchUpdateResult {
+  total: number;
+  success: number;
+  failed: number;
+  errors: Array<{ documentId: string; error: string }>;
+  results: Array<{ documentId: string; response: BatchUpdateResponse }>;
+}
+
+// ============================================
+// Bulk Operations API
+// ============================================
+
+export class BulkApi {
+  private readonly client: GoogleDocsClient;
+
+  constructor(client: GoogleDocsClient) {
+    this.client = client;
+  }
+
+  // ============================================
+  // Create Documents
+  // ============================================
+
+  /**
+   * Bulk create documents from a list of titles
+   */
+  async createDocuments(
+    options: BulkCreateDocumentsOptions
+  ): Promise<BulkCreateDocumentsResult> {
+    const { titles, concurrency = 10, dryRun = false, onProgress, onError } = options;
+
+    const result: BulkCreateDocumentsResult = {
+      total: titles.length,
+      success: 0,
+      failed: 0,
+      errors: [],
+      createdDocuments: [],
+    };
+
+    if (titles.length === 0) return result;
+
+    const chunks = this.chunkArray(titles, concurrency);
+
+    for (const chunk of chunks) {
+      await Promise.all(
+        chunk.map(async (title) => {
+          try {
+            if (dryRun) {
+              result.success++;
+            } else {
+              const doc = await this.client.post<Document>('/documents', { title });
+              result.success++;
+              result.createdDocuments.push({
+                documentId: doc.documentId,
+                title: doc.title,
+              });
+            }
+
+            if (onProgress) onProgress(result.success + result.failed, result.total, title);
+          } catch (err) {
+            result.failed++;
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            result.errors.push({ title, error: errorMessage });
+            if (onError) onError(err instanceof Error ? err : new Error(errorMessage), title);
+          }
+        })
+      );
+    }
+
+    return result;
+  }
+
+  // ============================================
+  // Find/Replace
+  // ============================================
+
+  /**
+   * Bulk find and replace across multiple documents
+   */
+  async findReplace(
+    options: BulkFindReplaceOptions
+  ): Promise<BulkFindReplaceResult> {
+    const { entries, concurrency = 10, dryRun = false, onProgress, onError } = options;
+
+    const result: BulkFindReplaceResult = {
+      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++;
+              result.results.push({
+                documentId: entry.documentId,
+                occurrencesChanged: 0,
+                find: entry.find,
+                replace: entry.replace,
+              });
+            } else {
+              const requests: Request[] = [
+                {
+                  replaceAllText: {
+                    containsText: {
+                      text: entry.find,
+                      matchCase: entry.matchCase || false,
+                    },
+                    replaceText: entry.replace,
+                  },
+                },
+              ];
+
+              const response = await this.client.post<BatchUpdateResponse>(
+                `/documents/${entry.documentId}:batchUpdate`,
+                { requests }
+              );
+
+              const occurrencesChanged =
+                response.replies?.find((r) => r.replaceAllText)?.replaceAllText?.occurrencesChanged || 0;
+
+              result.success++;
+              result.results.push({
+                documentId: entry.documentId,
+                occurrencesChanged,
+                find: entry.find,
+                replace: entry.replace,
+              });
+            }
+
+            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({
+              documentId: entry.documentId,
+              find: entry.find,
+              error: errorMessage,
+            });
+            if (onError) onError(err instanceof Error ? err : new Error(errorMessage), entry);
+          }
+        })
+      );
+    }
+
+    return result;
+  }
+
+  // ============================================
+  // Batch Update (generic)
+  // ============================================
+
+  /**
+   * Bulk batch updates across multiple documents
+   * Each entry specifies a document ID and an array of requests
+   */
+  async batchUpdate(
+    options: BulkBatchUpdateOptions
+  ): Promise<BulkBatchUpdateResult> {
+    const { entries, concurrency = 10, dryRun = false, onProgress, onError } = options;
+
+    const result: BulkBatchUpdateResult = {
+      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 response = await this.client.post<BatchUpdateResponse>(
+                `/documents/${entry.documentId}:batchUpdate`,
+                { requests: entry.requests }
+              );
+              result.success++;
+              result.results.push({
+                documentId: entry.documentId,
+                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({
+              documentId: entry.documentId,
+              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-googledocs/src/api/index.ts

@@ -3,6 +3,7 @@ import { GoogleDocsClient } from './client';
 import { DocumentsApi } from './documents';
 import { ContentApi } from './content';
 import { StylesApi } from './styles';
+import { BulkApi } from './bulk';
 
 /**
  * Google Docs API client
@@ -15,12 +16,14 @@ export class GoogleDocs {
   public readonly documents: DocumentsApi;
   public readonly content: ContentApi;
   public readonly styles: StylesApi;
+  public readonly bulk: BulkApi;
 
   constructor(config: GoogleDocsConfig) {
     this.client = new GoogleDocsClient(config);
     this.documents = new DocumentsApi(this.client);
     this.content = new ContentApi(this.client);
     this.styles = new StylesApi(this.client);
+    this.bulk = new BulkApi(this.client);
   }
 
   /**
@@ -63,3 +66,4 @@ export { GoogleDocsClient } from './client';
 export { DocumentsApi } from './documents';
 export { ContentApi } from './content';
 export { StylesApi } from './styles';
+export { BulkApi } from './bulk';