@hasna/connectors 1.3.22 → 1.3.24

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

@@ -0,0 +1,365 @@
+import type { GoogleContactsClient } from './client';
+import type { Contact, ContactsListResponse } from '../types';
+
+// ============================================
+// Bulk Operation Types
+// ============================================
+
+export interface BulkOperationOptions {
+  /** Search query to match contacts (matches name, email, etc.) */
+  query?: string;
+  /** Maximum contacts to process (default: 100) */
+  maxResults?: number;
+  /** Maximum concurrent API calls (default: 10) */
+  concurrency?: number;
+  /** Dry run - don't actually modify */
+  dryRun?: boolean;
+  /** Progress callback */
+  onProgress?: (current: number, total: number, contact: ContactSummary) => void;
+  /** Error callback */
+  onError?: (error: Error, contact: ContactSummary) => void;
+}
+
+export interface BulkDeleteOptions extends BulkOperationOptions {}
+
+export interface BulkUpdateOptions extends BulkOperationOptions {
+  /** Fields to update on all matching contacts */
+  updates: {
+    givenName?: string;
+    familyName?: string;
+    organization?: { name?: string; title?: string };
+  };
+}
+
+export interface BulkGroupOptions {
+  /** Contact resource names to add */
+  contactNames?: string[];
+  /** Or use a query to select contacts */
+  query?: string;
+  maxResults?: number;
+  concurrency?: number;
+  dryRun?: boolean;
+  onProgress?: (current: number, total: number, contact: ContactSummary) => void;
+  onError?: (error: Error, contact: ContactSummary) => void;
+}
+
+export interface ContactSummary {
+  resourceName: string;
+  displayName: string;
+  emails: string[];
+}
+
+export interface BulkOperationResult {
+  total: number;
+  success: number;
+  failed: number;
+  skipped: number;
+  errors: Array<{ contactName: string; error: string }>;
+  processedContacts: ContactSummary[];
+}
+
+export interface PreviewResult {
+  contacts: ContactSummary[];
+  total: number;
+  query?: string;
+}
+
+// ============================================
+// Bulk Operations API
+// ============================================
+
+export class BulkApi {
+  private readonly client: GoogleContactsClient;
+
+  constructor(client: GoogleContactsClient) {
+    this.client = client;
+  }
+
+  // ============================================
+  // Preview
+  // ============================================
+
+  /**
+   * Preview contacts matching a query
+   */
+  async preview(options?: { query?: string; maxResults?: number }): Promise<PreviewResult> {
+    const contacts = await this.fetchContacts({
+      query: options?.query,
+      maxResults: options?.maxResults || 50,
+    });
+    return { contacts, total: contacts.length, query: options?.query };
+  }
+
+  // ============================================
+  // Delete
+  // ============================================
+
+  /**
+   * Bulk delete contacts matching a query
+   */
+  async delete(options: BulkDeleteOptions): Promise<BulkOperationResult> {
+    const contacts = await this.fetchContacts({
+      query: options.query,
+      maxResults: options.maxResults || 100,
+    });
+
+    return this.executeBatch(contacts, {
+      dryRun: options.dryRun || false,
+      concurrency: options.concurrency || 10,
+      onProgress: options.onProgress,
+      onError: options.onError,
+      operation: async (contact) => {
+        await this.client.delete(`/v1/${contact.resourceName}:deleteContact`);
+      },
+    });
+  }
+
+  // ============================================
+  // Update
+  // ============================================
+
+  /**
+   * Bulk update contacts with partial data
+   */
+  async update(options: BulkUpdateOptions): Promise<BulkOperationResult> {
+    const contacts = await this.fetchContacts({
+      query: options.query,
+      maxResults: options.maxResults || 100,
+    });
+
+    return this.executeBatch(contacts, {
+      dryRun: options.dryRun || false,
+      concurrency: options.concurrency || 10,
+      onProgress: options.onProgress,
+      onError: options.onError,
+      operation: async (contact) => {
+        const updateFields: string[] = [];
+        const body: Record<string, unknown> = {};
+
+        if (options.updates.givenName || options.updates.familyName) {
+          body.names = [{
+            givenName: options.updates.givenName,
+            familyName: options.updates.familyName,
+          }];
+          updateFields.push('names');
+        }
+        if (options.updates.organization) {
+          body.organizations = [{
+            name: options.updates.organization.name,
+            title: options.updates.organization.title,
+          }];
+          updateFields.push('organizations');
+        }
+
+        await this.client.patch<Contact>(`/v1/${contact.resourceName}:updateContact`, body, {
+          updatePersonFields: updateFields.join(','),
+        });
+      },
+    });
+  }
+
+  // ============================================
+  // Add to Group
+  // ============================================
+
+  /**
+   * Bulk add contacts to a contact group
+   */
+  async addToGroup(groupResourceName: string, options: BulkGroupOptions): Promise<BulkOperationResult> {
+    let contactNames = options.contactNames;
+
+    // If no names provided, resolve from query
+    if (!contactNames || contactNames.length === 0) {
+      const contacts = await this.fetchContacts({
+        query: options.query,
+        maxResults: options.maxResults || 100,
+      });
+      contactNames = contacts.map(c => c.resourceName);
+    }
+
+    const summaries = contactNames.map(name => ({
+      resourceName: name,
+      displayName: name,
+      emails: [],
+    }));
+
+    return this.executeBatch(summaries, {
+      dryRun: options.dryRun || false,
+      concurrency: options.concurrency || 10,
+      onProgress: options.onProgress,
+      onError: options.onError,
+      operation: async (contact) => {
+        await this.client.post(`/v1/${groupResourceName}:modifyMembers`, {
+          membersToAdd: [{ contactGroupMembership: { contactGroupResourceName: groupResourceName } }],
+          resourceNames: [contact.resourceName],
+        });
+      },
+    });
+  }
+
+  // ============================================
+  // Remove from Group
+  // ============================================
+
+  /**
+   * Bulk remove contacts from a contact group
+   */
+  async removeFromGroup(groupResourceName: string, options: BulkGroupOptions): Promise<BulkOperationResult> {
+    let contactNames = options.contactNames;
+
+    if (!contactNames || contactNames.length === 0) {
+      const contacts = await this.fetchContacts({
+        query: options.query,
+        maxResults: options.maxResults || 100,
+      });
+      contactNames = contacts.map(c => c.resourceName);
+    }
+
+    const summaries = contactNames.map(name => ({
+      resourceName: name,
+      displayName: name,
+      emails: [],
+    }));
+
+    return this.executeBatch(summaries, {
+      dryRun: options.dryRun || false,
+      concurrency: options.concurrency || 10,
+      onProgress: options.onProgress,
+      onError: options.onError,
+      operation: async (contact) => {
+        await this.client.post(`/v1/${groupResourceName}:modifyMembers`, {
+          membersToDelete: [{ contactId: contact.resourceName.split('/').pop() }],
+        });
+      },
+    });
+  }
+
+  // ============================================
+  // Helper Methods
+  // ============================================
+
+  /**
+   * Fetch contacts matching a query
+   */
+  async fetchContacts(params: { query?: string; maxResults?: number }): Promise<ContactSummary[]> {
+    const contacts: ContactSummary[] = [];
+    let pageToken: string | undefined;
+    const max = params.maxResults || 100;
+    const personFields = 'names,emailAddresses,organizations,memberships';
+
+    while (contacts.length < max) {
+      let response: ContactsListResponse;
+
+      if (params.query) {
+        // Use search endpoint
+        const searchResult = await this.client.get<{
+          results?: Array<{ person: Contact }>;
+          nextPageToken?: string;
+        }>('/v1/people:searchContacts', {
+          query: params.query,
+          pageSize: Math.min(100, max - contacts.length),
+          pageToken,
+          readMask: personFields,
+        });
+
+        if (!searchResult.results || searchResult.results.length === 0) break;
+
+        for (const r of searchResult.results) {
+          const c = r.person;
+          contacts.push(this.toSummary(c));
+        }
+        pageToken = searchResult.nextPageToken;
+      } else {
+        // Use list endpoint
+        response = await this.client.get<ContactsListResponse>('/v1/people/me/connections', {
+          pageSize: Math.min(100, max - contacts.length),
+          pageToken,
+          personFields,
+          sortOrder: 'LAST_MODIFIED_DESCENDING',
+        });
+
+        if (!response.connections || response.connections.length === 0) break;
+
+        for (const c of response.connections) {
+          contacts.push(this.toSummary(c));
+        }
+        pageToken = response.nextPageToken;
+      }
+
+      if (!pageToken) break;
+    }
+
+    return contacts;
+  }
+
+  private toSummary(contact: Contact): ContactSummary {
+    return {
+      resourceName: contact.resourceName,
+      displayName: contact.names?.[0]?.displayName || '(unnamed)',
+      emails: (contact.emailAddresses || []).map(e => e.value).filter(Boolean),
+    };
+  }
+
+  /**
+   * Execute operations in batches with concurrency control
+   */
+  private async executeBatch(
+    contacts: ContactSummary[],
+    options: {
+      dryRun: boolean;
+      concurrency: number;
+      onProgress?: (current: number, total: number, contact: ContactSummary) => void;
+      onError?: (error: Error, contact: ContactSummary) => void;
+      operation: (contact: ContactSummary) => Promise<void>;
+    }
+  ): Promise<BulkOperationResult> {
+    const { dryRun, concurrency, onProgress, onError, operation } = options;
+
+    const result: BulkOperationResult = {
+      total: contacts.length,
+      success: 0,
+      failed: 0,
+      skipped: 0,
+      errors: [],
+      processedContacts: [],
+    };
+
+    if (contacts.length === 0) return result;
+
+    const chunks = this.chunkArray(contacts, concurrency);
+
+    for (const chunk of chunks) {
+      await Promise.all(
+        chunk.map(async (contact) => {
+          try {
+            if (dryRun) {
+              result.success++;
+              result.processedContacts.push(contact);
+            } else {
+              await operation(contact);
+              result.success++;
+              result.processedContacts.push(contact);
+            }
+
+            if (onProgress) onProgress(result.success + result.failed, result.total, contact);
+          } catch (err) {
+            result.failed++;
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            result.errors.push({ contactName: contact.resourceName, error: errorMessage });
+            if (onError) onError(err instanceof Error ? err : new Error(errorMessage), contact);
+          }
+        })
+      );
+    }
+
+    return result;
+  }
+
+  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-googlecontacts/src/api/groups.ts

@@ -0,0 +1,164 @@
+import type { GoogleContactsClient } from './client';
+import type { ContactGroup, ContactGroupsListResponse } from '../types';
+
+// ============================================
+// Group Request/Response Types
+// ============================================
+
+export interface CreateGroupParams {
+  name: string;
+}
+
+export interface UpdateGroupParams {
+  name?: string;
+}
+
+export interface GetGroupMembersOptions {
+  pageSize?: number;
+  pageToken?: string;
+}
+
+export interface GetGroupMembersResponse {
+  connections?: Array<{
+    resourceName: string;
+    etag?: string;
+    names?: Array<{
+      displayName?: string;
+      givenName?: string;
+      familyName?: string;
+    }>;
+    emailAddresses?: Array<{ value: string }>;
+    phoneNumbers?: Array<{ value: string }>;
+  }>;
+  nextPageToken?: string;
+  totalItems?: number;
+}
+
+export interface ModifyMembershipParams {
+  contactResourceName: string;
+}
+
+/**
+ * Groups API module - CRUD and membership management for Google contact groups
+ */
+export class GroupsApi {
+  constructor(private readonly client: GoogleContactsClient) {}
+
+  /**
+   * List contact groups
+   */
+  async list(options: { pageSize?: number; pageToken?: string; groupFields?: string } = {}): Promise<ContactGroupsListResponse> {
+    const { pageSize = 100, pageToken, groupFields } = options;
+    const params: Record<string, string | number> = { pageSize };
+    if (pageToken) params.pageToken = pageToken;
+    if (groupFields) params.groupFields = groupFields;
+    return this.client.get<ContactGroupsListResponse>('/v1/contactGroups', params);
+  }
+
+  /**
+   * Get a specific group by resource name
+   */
+  async get(groupResourceName: string): Promise<ContactGroup> {
+    const name = groupResourceName.startsWith('contactGroups/') ? groupResourceName : `contactGroups/${groupResourceName}`;
+    return this.client.get<ContactGroup>(`/v1/${name}`);
+  }
+
+  /**
+   * Create a new contact group
+   */
+  async create(params: CreateGroupParams): Promise<ContactGroup> {
+    return this.client.post<ContactGroup>('/v1/contactGroups', {
+      contactGroup: {
+        name: params.name,
+      },
+    });
+  }
+
+  /**
+   * Update a contact group's name
+   */
+  async update(groupResourceName: string, params: UpdateGroupParams): Promise<ContactGroup> {
+    const name = groupResourceName.startsWith('contactGroups/') ? groupResourceName : `contactGroups/${groupResourceName}`;
+
+    const body: Record<string, unknown> = {};
+    if (params.name !== undefined) {
+      body.name = params.name;
+    }
+
+    return this.client.put<ContactGroup>(`/v1/${name}`, body, {
+      updateMask: 'name',
+    });
+  }
+
+  /**
+   * Delete a contact group
+   */
+  async delete(groupResourceName: string): Promise<void> {
+    const name = groupResourceName.startsWith('contactGroups/') ? groupResourceName : `contactGroups/${groupResourceName}`;
+    await this.client.delete(`/v1/${name}`);
+  }
+
+  /**
+   * List members of a contact group
+   */
+  async getMembers(groupResourceName: string, options: GetGroupMembersOptions = {}): Promise<GetGroupMembersResponse> {
+    const name = groupResourceName.startsWith('contactGroups/') ? groupResourceName : `contactGroups/${groupResourceName}`;
+    const { pageSize = 100, pageToken } = options;
+    const params: Record<string, string | number> = { pageSize };
+    if (pageToken) params.pageToken = pageToken;
+    return this.client.get<GetGroupMembersResponse>(`/v1/${name}/members`, params);
+  }
+
+  /**
+   * Iterate over all members of a group (handles pagination)
+   */
+  async *listAllMembers(groupResourceName: string, options: Omit<GetGroupMembersOptions, 'pageToken'> = {}): AsyncGenerator<{
+    resourceName: string;
+    displayName?: string;
+    emails?: string[];
+    phones?: string[];
+  }> {
+    let pageToken: string | undefined;
+    do {
+      const response = await this.getMembers(groupResourceName, { ...options, pageToken });
+      const connections = response.connections || [];
+      for (const member of connections) {
+        yield {
+          resourceName: member.resourceName,
+          displayName: member.names?.[0]?.displayName,
+          emails: member.emailAddresses?.map(e => e.value) || [],
+          phones: member.phoneNumbers?.map(p => p.value) || [],
+        };
+      }
+      pageToken = response.nextPageToken;
+    } while (pageToken);
+  }
+
+  /**
+   * Add a contact to a group
+   */
+  async addMember(groupResourceName: string, contactResourceName: string): Promise<void> {
+    const group = groupResourceName.startsWith('contactGroups/') ? groupResourceName : `contactGroups/${groupResourceName}`;
+    const contact = contactResourceName.startsWith('people/') ? contactResourceName : `people/${contactResourceName}`;
+    await this.client.post(`/v1/${group}/members:batchCreate`, {
+      contactMemberships: [
+        {
+          contact: {
+            resourceName: contact,
+          },
+        },
+      ],
+    });
+  }
+
+  /**
+   * Remove a contact from a group
+   */
+  async removeMember(groupResourceName: string, contactResourceName: string): Promise<void> {
+    const group = groupResourceName.startsWith('contactGroups/') ? groupResourceName : `contactGroups/${groupResourceName}`;
+    const contact = contactResourceName.startsWith('people/') ? contactResourceName : `people/${contactResourceName}`;
+    await this.client.post(`/v1/${group}/members:batchDelete`, {
+      contactResourceNames: [contact],
+    });
+  }
+}

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

@@ -1,6 +1,8 @@
 import type { GoogleContactsConfig, OAuthTokens } from '../types';
 import { GoogleContactsClient } from './client';
 import { ContactsApi } from './contacts';
+import { GroupsApi } from './groups';
+import { BulkApi } from './bulk';
 
 /**
  * Main GoogleContacts class - entry point for the API
@@ -10,10 +12,14 @@ export class GoogleContacts {
 
   // API modules
   public readonly contacts: ContactsApi;
+  public readonly groups: GroupsApi;
+  public readonly bulk: BulkApi;
 
   constructor(config: GoogleContactsConfig) {
     this.client = new GoogleContactsClient(config);
     this.contacts = new ContactsApi(this.client);
+    this.groups = new GroupsApi(this.client);
+    this.bulk = new BulkApi(this.client);
   }
 
   /**
@@ -97,3 +103,5 @@ export class GoogleContacts {
 
 export { GoogleContactsClient } from './client';
 export { ContactsApi } from './contacts';
+export { GroupsApi } from './groups';
+export { BulkApi } from './bulk';