@hasna/connectors 0.7.2 → 0.8.0

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

@@ -0,0 +1,189 @@
+import type { ConnectorConfig, OutputFormat } from '../types';
+import { ConnectorApiError, parseApiError } from '../types';
+
+export interface RequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  params?: Record<string, string | number | boolean | undefined>;
+  body?: Record<string, unknown> | unknown[] | string;
+  headers?: Record<string, string>;
+  format?: OutputFormat;
+  retries?: number;
+  timeout?: number;
+}
+
+export class ConnectorClient {
+  private readonly apiKey: string;
+  private readonly email: string;
+  private readonly apiSecret?: string;
+  private readonly baseUrl: string;
+
+  constructor(config: ConnectorConfig) {
+    const key = config.apiKey || config.token || config.accessToken;
+    if (!key) {
+      throw new Error('API key is required');
+    }
+    if (!config.email && !config.domain) {
+      throw new Error('Email and domain are required for Agile CRM authentication');
+    }
+    this.apiKey = key;
+    this.email = config.email || '';
+    this.apiSecret = config.apiSecret;
+
+    if (config.baseUrl) {
+      this.baseUrl = config.baseUrl;
+    } else if (config.domain) {
+      this.baseUrl = `https://${config.domain}.agilecrm.com/dev/api`;
+    } else {
+      throw new Error('Domain or baseUrl is required');
+    }
+  }
+
+  private buildUrl(path: string, params?: Record<string, string | number | boolean | undefined>): string {
+    const url = new URL(`${this.baseUrl}${path}`);
+
+    if (params) {
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null && value !== '') {
+          url.searchParams.append(key, String(value));
+        }
+      });
+    }
+
+    return url.toString();
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  private getRetryDelay(attempt: number, baseDelay: number = 1000): number {
+    return baseDelay * Math.pow(2, attempt) + Math.random() * 1000;
+  }
+
+  private isRetryableStatus(status: number): boolean {
+    return status === 429 || (status >= 500 && status < 600);
+  }
+
+  async request<T>(path: string, options: RequestOptions = {}): Promise<T> {
+    const { method = 'GET', params, body, headers = {}, retries = 3, timeout = 30000 } = options;
+
+    const url = this.buildUrl(path, params);
+
+    // Agile CRM uses HTTP Basic Auth: email:apiKey
+    const credentials = Buffer.from(`${this.email}:${this.apiKey}`).toString('base64');
+    const requestHeaders: Record<string, string> = {
+      'Authorization': `Basic ${credentials}`,
+      'Accept': 'application/json',
+      ...headers,
+    };
+
+    if (body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+      requestHeaders['Content-Type'] = 'application/json';
+    }
+
+    const fetchOptions: RequestInit = {
+      method,
+      headers: requestHeaders,
+    };
+
+    if (body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+      fetchOptions.body = typeof body === 'string' ? body : JSON.stringify(body);
+    }
+
+    let lastError: Error | null = null;
+    let lastStatus: number = 0;
+
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+        const response = await fetch(url, {
+          ...fetchOptions,
+          signal: controller.signal,
+        });
+
+        clearTimeout(timeoutId);
+        lastStatus = response.status;
+
+        if (response.status === 204) {
+          return {} as T;
+        }
+
+        let data: unknown;
+        const contentType = response.headers.get('content-type') || '';
+
+        if (contentType.includes('application/json')) {
+          const text = await response.text();
+          if (text) {
+            try {
+              data = JSON.parse(text);
+            } catch {
+              data = text;
+            }
+          }
+        } else {
+          data = await response.text();
+        }
+
+        if (!response.ok) {
+          if (this.isRetryableStatus(response.status) && attempt < retries) {
+            const retryAfter = response.headers.get('retry-after');
+            const delay = retryAfter
+              ? parseInt(retryAfter, 10) * 1000
+              : this.getRetryDelay(attempt);
+
+            await this.sleep(delay);
+            continue;
+          }
+
+          throw parseApiError(data, response.status);
+        }
+
+        return data as T;
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+
+        if (lastError.name === 'AbortError') {
+          lastError = new Error(`Request timeout after ${timeout}ms`);
+        }
+
+        if (attempt < retries && !(err instanceof ConnectorApiError)) {
+          await this.sleep(this.getRetryDelay(attempt));
+          continue;
+        }
+
+        throw err;
+      }
+    }
+
+    throw lastError || new ConnectorApiError('Request failed', lastStatus);
+  }
+
+  async get<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'GET', params });
+  }
+
+  async post<T>(path: string, body?: Record<string, unknown> | unknown[] | string | object, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'POST', body: body as Record<string, unknown>, params });
+  }
+
+  async put<T>(path: string, body?: Record<string, unknown> | object, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'PUT', body: body as Record<string, unknown>, params });
+  }
+
+  async patch<T>(path: string, body?: Record<string, unknown> | object, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'PATCH', body: body as Record<string, unknown>, params });
+  }
+
+  async delete<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'DELETE', params });
+  }
+
+  getApiKeyPreview(): string {
+    if (this.apiKey.length > 10) {
+      return `${this.apiKey.substring(0, 6)}...${this.apiKey.substring(this.apiKey.length - 4)}`;
+    }
+    return '***';
+  }
+}

package/connectors/connect-agilecrm/src/api/contacts.ts

@@ -0,0 +1,84 @@
+import type { ConnectorClient } from './client';
+import type {
+  Contact,
+  ContactCreateParams,
+  ContactUpdateParams,
+  ContactListParams,
+} from '../types';
+
+export class ContactsApi {
+  constructor(private readonly client: ConnectorClient) {}
+
+  async list(params?: ContactListParams): Promise<Contact[]> {
+    return this.client.get<Contact[]>('/contacts', {
+      page_size: params?.page_size,
+      cursor: params?.cursor,
+    });
+  }
+
+  async get(id: number): Promise<Contact> {
+    return this.client.get<Contact>(`/contacts/${id}`);
+  }
+
+  async getByEmail(email: string): Promise<Contact> {
+    return this.client.get<Contact>(`/contacts/search/email/${encodeURIComponent(email)}`);
+  }
+
+  async getByPhone(phone: string): Promise<Contact> {
+    return this.client.get<Contact>(`/contacts/search/phonenumber/${encodeURIComponent(phone)}`);
+  }
+
+  async create(data: ContactCreateParams): Promise<Contact> {
+    return this.client.post<Contact>('/contacts', {
+      ...data,
+      type: data.type || 'PERSON',
+    });
+  }
+
+  async update(data: ContactUpdateParams): Promise<Contact> {
+    return this.client.put<Contact>('/contacts/edit-properties', data);
+  }
+
+  async delete(id: number): Promise<void> {
+    await this.client.delete(`/contacts/${id}`);
+  }
+
+  async addTags(id: number, tags: string[]): Promise<Contact> {
+    return this.client.put<Contact>('/contacts/edit/tags', {
+      id,
+      tags,
+    });
+  }
+
+  async removeTags(id: number, tags: string[]): Promise<Contact> {
+    return this.client.put<Contact>('/contacts/delete/tags', {
+      id,
+      tags,
+    });
+  }
+
+  async updateLeadScore(id: number, score: number): Promise<Contact> {
+    return this.client.put<Contact>('/contacts/edit/lead-score', {
+      id,
+      lead_score: score,
+    });
+  }
+
+  async updateStarValue(id: number, starValue: number): Promise<Contact> {
+    return this.client.put<Contact>('/contacts/edit/star', {
+      id,
+      star_value: starValue,
+    });
+  }
+
+  async search(query: string): Promise<Contact[]> {
+    return this.client.post<Contact[]>('/search', {
+      q: query,
+      type: 'PERSON',
+    });
+  }
+
+  async listCompanies(): Promise<Contact[]> {
+    return this.client.get<Contact[]>('/contacts/companies/list');
+  }
+}

package/connectors/connect-agilecrm/src/api/deals.ts

@@ -0,0 +1,56 @@
+import type { ConnectorClient } from './client';
+import type {
+  Deal,
+  DealCreateParams,
+  DealUpdateParams,
+  DealListParams,
+} from '../types';
+
+export class DealsApi {
+  constructor(private readonly client: ConnectorClient) {}
+
+  async list(params?: DealListParams): Promise<Deal[]> {
+    return this.client.get<Deal[]>('/opportunity', {
+      page_size: params?.page_size,
+      cursor: params?.cursor,
+    });
+  }
+
+  async get(id: number): Promise<Deal> {
+    return this.client.get<Deal>(`/opportunity/${id}`);
+  }
+
+  async create(data: DealCreateParams): Promise<Deal> {
+    return this.client.post<Deal>('/opportunity', {
+      name: data.name,
+      description: data.description,
+      expected_value: data.expected_value,
+      probability: data.probability,
+      milestone: data.milestone,
+      close_date: data.close_date,
+      contact_ids: data.contact_ids,
+      custom_data: data.custom_data,
+      pipeline_id: data.pipeline_id,
+    });
+  }
+
+  async update(data: DealUpdateParams): Promise<Deal> {
+    return this.client.put<Deal>('/opportunity/partial-update', data);
+  }
+
+  async delete(id: number): Promise<void> {
+    await this.client.delete(`/opportunity/${id}`);
+  }
+
+  async getByContact(contactId: number): Promise<Deal[]> {
+    return this.client.get<Deal[]>(`/contacts/${contactId}/deals`);
+  }
+
+  async getByMilestone(milestone: string): Promise<Deal[]> {
+    return this.client.get<Deal[]>('/opportunity/byMilestone', { milestone });
+  }
+
+  async getMyDeals(): Promise<Deal[]> {
+    return this.client.get<Deal[]>('/opportunity/my/deals');
+  }
+}

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

@@ -0,0 +1,54 @@
+import type { ConnectorConfig } from '../types';
+import { ConnectorClient } from './client';
+import { ContactsApi } from './contacts';
+import { DealsApi } from './deals';
+import { TasksApi } from './tasks';
+import { NotesApi } from './notes';
+
+export class Connector {
+  private readonly client: ConnectorClient;
+
+  public readonly contacts: ContactsApi;
+  public readonly deals: DealsApi;
+  public readonly tasks: TasksApi;
+  public readonly notes: NotesApi;
+
+  constructor(config: ConnectorConfig) {
+    this.client = new ConnectorClient(config);
+    this.contacts = new ContactsApi(this.client);
+    this.deals = new DealsApi(this.client);
+    this.tasks = new TasksApi(this.client);
+    this.notes = new NotesApi(this.client);
+  }
+
+  static fromEnv(): Connector {
+    const apiKey = process.env.AGILECRM_API_KEY;
+    const email = process.env.AGILECRM_EMAIL;
+    const domain = process.env.AGILECRM_DOMAIN;
+
+    if (!apiKey) {
+      throw new Error('AGILECRM_API_KEY environment variable is required');
+    }
+    if (!email) {
+      throw new Error('AGILECRM_EMAIL environment variable is required');
+    }
+    if (!domain) {
+      throw new Error('AGILECRM_DOMAIN environment variable is required');
+    }
+    return new Connector({ apiKey, email, domain });
+  }
+
+  getApiKeyPreview(): string {
+    return this.client.getApiKeyPreview();
+  }
+
+  getClient(): ConnectorClient {
+    return this.client;
+  }
+}
+
+export { ConnectorClient } from './client';
+export { ContactsApi } from './contacts';
+export { DealsApi } from './deals';
+export { TasksApi } from './tasks';
+export { NotesApi } from './notes';

package/connectors/connect-agilecrm/src/api/notes.ts

@@ -0,0 +1,26 @@
+import type { ConnectorClient } from './client';
+import type { Note, NoteCreateParams } from '../types';
+
+export class NotesApi {
+  constructor(private readonly client: ConnectorClient) {}
+
+  async getByContact(contactId: number): Promise<Note[]> {
+    return this.client.get<Note[]>(`/contacts/${contactId}/notes`);
+  }
+
+  async create(data: NoteCreateParams): Promise<Note> {
+    return this.client.post<Note>('/notes', data);
+  }
+
+  async deleteFromContact(contactId: number, noteId: number): Promise<void> {
+    await this.client.delete(`/contacts/${contactId}/notes/${noteId}`);
+  }
+
+  async getByDeal(dealId: number): Promise<Note[]> {
+    return this.client.get<Note[]>(`/opportunity/${dealId}/notes`);
+  }
+
+  async createForDeal(data: NoteCreateParams): Promise<Note> {
+    return this.client.post<Note>('/opportunity/deals/notes', data);
+  }
+}

package/connectors/connect-agilecrm/src/api/tasks.ts

@@ -0,0 +1,38 @@
+import type { ConnectorClient } from './client';
+import type {
+  Task,
+  TaskCreateParams,
+  TaskUpdateParams,
+} from '../types';
+
+export class TasksApi {
+  constructor(private readonly client: ConnectorClient) {}
+
+  async list(): Promise<Task[]> {
+    return this.client.get<Task[]>('/tasks');
+  }
+
+  async get(id: number): Promise<Task> {
+    return this.client.get<Task>(`/tasks/${id}`);
+  }
+
+  async create(data: TaskCreateParams): Promise<Task> {
+    return this.client.post<Task>('/tasks', data);
+  }
+
+  async update(data: TaskUpdateParams): Promise<Task> {
+    return this.client.put<Task>('/tasks/partial-update', data);
+  }
+
+  async delete(id: number): Promise<void> {
+    await this.client.delete(`/tasks/${id}`);
+  }
+
+  async getPending(numDays: number): Promise<Task[]> {
+    return this.client.get<Task[]>(`/tasks/pending/${numDays}`);
+  }
+
+  async getByContact(contactId: number): Promise<Task[]> {
+    return this.client.get<Task[]>(`/contacts/${contactId}/tasks/sort`);
+  }
+}