@hasna/connectors 0.6.0 → 0.7.0

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

@@ -0,0 +1,183 @@
+import type { ConnectorConfig, OutputFormat } from '../types';
+import { ConnectorApiError, parseApiError } from '../types';
+
+// ActiveCampaign base URL is account-specific
+// Format: https://<account>.api-us1.com/api/3
+const DEFAULT_BASE_URL = 'https://youraccountname.api-us1.com';
+
+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 apiSecret?: string;
+  private readonly baseUrl: string;
+
+  constructor(config: ConnectorConfig) {
+    const key = config.apiKey || config.token || config.accessToken;
+    if (!key) {
+      throw new Error('API key, token, or accessToken is required');
+    }
+    this.apiKey = key;
+    this.apiSecret = config.apiSecret;
+    // ActiveCampaign requires account-specific base URL
+    const base = config.baseUrl || DEFAULT_BASE_URL;
+    // Ensure /api/3 suffix
+    this.baseUrl = base.endsWith('/api/3') ? base : `${base.replace(/\/+$/, '')}/api/3`;
+  }
+
+  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);
+
+    // ActiveCampaign uses Api-Token header
+    const requestHeaders: Record<string, string> = {
+      'Api-Token': this.apiKey,
+      '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-activecampaign/src/api/contacts.ts

@@ -0,0 +1,64 @@
+import type { ConnectorClient } from './client';
+import type { Contact, ContactCreateParams, ContactUpdateParams, ListParams } from '../types';
+
+export class ContactsApi {
+  constructor(private readonly client: ConnectorClient) {}
+
+  async list(params?: ListParams): Promise<unknown> {
+    const queryParams: Record<string, string | number | boolean | undefined> = {};
+    if (params?.limit) queryParams.limit = params.limit;
+    if (params?.offset) queryParams.offset = params.offset;
+    if (params?.filters) {
+      for (const [key, value] of Object.entries(params.filters)) {
+        queryParams[key] = value;
+      }
+    }
+    return this.client.get<unknown>('/contacts', queryParams);
+  }
+
+  async get(contactId: string): Promise<{ contact: Contact }> {
+    return this.client.get<{ contact: Contact }>(`/contacts/${contactId}`);
+  }
+
+  async create(params: ContactCreateParams): Promise<{ contact: Contact }> {
+    return this.client.post<{ contact: Contact }>('/contacts', { contact: params });
+  }
+
+  async update(contactId: string, params: ContactUpdateParams): Promise<{ contact: Contact }> {
+    return this.client.put<{ contact: Contact }>(`/contacts/${contactId}`, { contact: params });
+  }
+
+  async delete(contactId: string): Promise<void> {
+    await this.client.delete(`/contacts/${contactId}`);
+  }
+
+  async sync(params: ContactCreateParams): Promise<{ contact: Contact }> {
+    return this.client.post<{ contact: Contact }>('/contact/sync', { contact: params });
+  }
+
+  async listAutomations(contactId: string): Promise<unknown> {
+    return this.client.get<unknown>(`/contacts/${contactId}/contactAutomations`);
+  }
+
+  async listTags(contactId: string): Promise<unknown> {
+    return this.client.get<unknown>(`/contacts/${contactId}/contactTags`);
+  }
+
+  async listDeals(contactId: string): Promise<unknown> {
+    return this.client.get<unknown>(`/contacts/${contactId}/deals`);
+  }
+
+  async addTag(contactId: string, tagId: string): Promise<unknown> {
+    return this.client.post<unknown>('/contactTags', { contactTag: { contact: contactId, tag: tagId } });
+  }
+
+  async removeTag(contactTagId: string): Promise<void> {
+    await this.client.delete(`/contactTags/${contactTagId}`);
+  }
+
+  async addToList(contactId: string, listId: string, status: number = 1): Promise<unknown> {
+    return this.client.post<unknown>('/contactLists', {
+      contactList: { list: listId, contact: contactId, status },
+    });
+  }
+}

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

@@ -0,0 +1,58 @@
+import type { ConnectorClient } from './client';
+import type { Deal, DealCreateParams, DealUpdateParams, ListParams } from '../types';
+
+export class DealsApi {
+  constructor(private readonly client: ConnectorClient) {}
+
+  async list(params?: ListParams): Promise<unknown> {
+    const queryParams: Record<string, string | number | boolean | undefined> = {};
+    if (params?.limit) queryParams.limit = params.limit;
+    if (params?.offset) queryParams.offset = params.offset;
+    if (params?.filters) {
+      for (const [key, value] of Object.entries(params.filters)) {
+        queryParams[key] = value;
+      }
+    }
+    return this.client.get<unknown>('/deals', queryParams);
+  }
+
+  async get(dealId: string): Promise<{ deal: Deal }> {
+    return this.client.get<{ deal: Deal }>(`/deals/${dealId}`);
+  }
+
+  async create(params: DealCreateParams): Promise<{ deal: Deal }> {
+    return this.client.post<{ deal: Deal }>('/deals', { deal: params });
+  }
+
+  async update(dealId: string, params: DealUpdateParams): Promise<{ deal: Deal }> {
+    return this.client.put<{ deal: Deal }>(`/deals/${dealId}`, { deal: params });
+  }
+
+  async delete(dealId: string): Promise<void> {
+    await this.client.delete(`/deals/${dealId}`);
+  }
+
+  async listNotes(dealId: string): Promise<unknown> {
+    return this.client.get<unknown>(`/deals/${dealId}/notes`);
+  }
+
+  async createNote(dealId: string, note: string): Promise<unknown> {
+    return this.client.post<unknown>(`/deals/${dealId}/notes`, { note: { note } });
+  }
+
+  async listStages(): Promise<unknown> {
+    return this.client.get<unknown>('/dealStages');
+  }
+
+  async getStage(stageId: string): Promise<unknown> {
+    return this.client.get<unknown>(`/dealStages/${stageId}`);
+  }
+
+  async listPipelines(): Promise<unknown> {
+    return this.client.get<unknown>('/dealGroups');
+  }
+
+  async getPipeline(pipelineId: string): Promise<unknown> {
+    return this.client.get<unknown>(`/dealGroups/${pipelineId}`);
+  }
+}

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

@@ -0,0 +1,70 @@
+import type { ConnectorConfig } from '../types';
+import { ConnectorClient } from './client';
+import { ContactsApi } from './contacts';
+import { DealsApi } from './deals';
+import { AccountsApi } from './accounts';
+import { CampaignsApi } from './campaigns';
+import { TagsApi } from './tags';
+import { ListsApi } from './lists';
+import { AutomationsApi } from './automations';
+import { WebhooksApi } from './webhooks';
+import { NotesApi } from './notes';
+
+export class Connector {
+  private readonly client: ConnectorClient;
+
+  public readonly contacts: ContactsApi;
+  public readonly deals: DealsApi;
+  public readonly accounts: AccountsApi;
+  public readonly campaigns: CampaignsApi;
+  public readonly tags: TagsApi;
+  public readonly lists: ListsApi;
+  public readonly automations: AutomationsApi;
+  public readonly webhooks: WebhooksApi;
+  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.accounts = new AccountsApi(this.client);
+    this.campaigns = new CampaignsApi(this.client);
+    this.tags = new TagsApi(this.client);
+    this.lists = new ListsApi(this.client);
+    this.automations = new AutomationsApi(this.client);
+    this.webhooks = new WebhooksApi(this.client);
+    this.notes = new NotesApi(this.client);
+  }
+
+  static fromEnv(): Connector {
+    const apiKey = process.env.ACTIVECAMPAIGN_API_KEY;
+    const baseUrl = process.env.ACTIVECAMPAIGN_BASE_URL;
+
+    if (!apiKey) {
+      throw new Error('ACTIVECAMPAIGN_API_KEY environment variable is required');
+    }
+    if (!baseUrl) {
+      throw new Error('ACTIVECAMPAIGN_BASE_URL environment variable is required (e.g. https://youraccountname.api-us1.com)');
+    }
+    return new Connector({ apiKey, baseUrl });
+  }
+
+  getApiKeyPreview(): string {
+    return this.client.getApiKeyPreview();
+  }
+
+  getClient(): ConnectorClient {
+    return this.client;
+  }
+}
+
+export { ConnectorClient } from './client';
+export { ContactsApi } from './contacts';
+export { DealsApi } from './deals';
+export { AccountsApi } from './accounts';
+export { CampaignsApi } from './campaigns';
+export { TagsApi } from './tags';
+export { ListsApi } from './lists';
+export { AutomationsApi } from './automations';
+export { WebhooksApi } from './webhooks';
+export { NotesApi } from './notes';

package/connectors/connect-activecampaign/src/api/lists.ts

@@ -0,0 +1,30 @@
+import type { ConnectorClient } from './client';
+import type { ContactList, ListCreateParams, ListParams } from '../types';
+
+export class ListsApi {
+  constructor(private readonly client: ConnectorClient) {}
+
+  async list(params?: ListParams): Promise<unknown> {
+    const queryParams: Record<string, string | number | boolean | undefined> = {};
+    if (params?.limit) queryParams.limit = params.limit;
+    if (params?.offset) queryParams.offset = params.offset;
+    if (params?.filters) {
+      for (const [key, value] of Object.entries(params.filters)) {
+        queryParams[key] = value;
+      }
+    }
+    return this.client.get<unknown>('/lists', queryParams);
+  }
+
+  async get(listId: string): Promise<{ list: ContactList }> {
+    return this.client.get<{ list: ContactList }>(`/lists/${listId}`);
+  }
+
+  async create(params: ListCreateParams): Promise<{ list: ContactList }> {
+    return this.client.post<{ list: ContactList }>('/lists', { list: params });
+  }
+
+  async delete(listId: string): Promise<void> {
+    await this.client.delete(`/lists/${listId}`);
+  }
+}

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

@@ -0,0 +1,22 @@
+import type { ConnectorClient } from './client';
+import type { Note, NoteCreateParams } from '../types';
+
+export class NotesApi {
+  constructor(private readonly client: ConnectorClient) {}
+
+  async get(noteId: string): Promise<{ note: Note }> {
+    return this.client.get<{ note: Note }>(`/notes/${noteId}`);
+  }
+
+  async create(params: NoteCreateParams): Promise<{ note: Note }> {
+    return this.client.post<{ note: Note }>('/notes', { note: params });
+  }
+
+  async update(noteId: string, note: string): Promise<{ note: Note }> {
+    return this.client.put<{ note: Note }>(`/notes/${noteId}`, { note: { note } });
+  }
+
+  async delete(noteId: string): Promise<void> {
+    await this.client.delete(`/notes/${noteId}`);
+  }
+}

package/connectors/connect-activecampaign/src/api/tags.ts

@@ -0,0 +1,34 @@
+import type { ConnectorClient } from './client';
+import type { Tag, TagCreateParams, ListParams } from '../types';
+
+export class TagsApi {
+  constructor(private readonly client: ConnectorClient) {}
+
+  async list(params?: ListParams): Promise<unknown> {
+    const queryParams: Record<string, string | number | boolean | undefined> = {};
+    if (params?.limit) queryParams.limit = params.limit;
+    if (params?.offset) queryParams.offset = params.offset;
+    if (params?.filters) {
+      for (const [key, value] of Object.entries(params.filters)) {
+        queryParams[key] = value;
+      }
+    }
+    return this.client.get<unknown>('/tags', queryParams);
+  }
+
+  async get(tagId: string): Promise<{ tag: Tag }> {
+    return this.client.get<{ tag: Tag }>(`/tags/${tagId}`);
+  }
+
+  async create(params: TagCreateParams): Promise<{ tag: Tag }> {
+    return this.client.post<{ tag: Tag }>('/tags', { tag: params });
+  }
+
+  async update(tagId: string, params: Partial<TagCreateParams>): Promise<{ tag: Tag }> {
+    return this.client.put<{ tag: Tag }>(`/tags/${tagId}`, { tag: params });
+  }
+
+  async delete(tagId: string): Promise<void> {
+    await this.client.delete(`/tags/${tagId}`);
+  }
+}

package/connectors/connect-activecampaign/src/api/webhooks.ts

@@ -0,0 +1,29 @@
+import type { ConnectorClient } from './client';
+import type { Webhook, WebhookCreateParams, ListParams } from '../types';
+
+export class WebhooksApi {
+  constructor(private readonly client: ConnectorClient) {}
+
+  async list(params?: ListParams): Promise<unknown> {
+    const queryParams: Record<string, string | number | boolean | undefined> = {};
+    if (params?.limit) queryParams.limit = params.limit;
+    if (params?.offset) queryParams.offset = params.offset;
+    return this.client.get<unknown>('/webhooks', queryParams);
+  }
+
+  async get(webhookId: string): Promise<{ webhook: Webhook }> {
+    return this.client.get<{ webhook: Webhook }>(`/webhooks/${webhookId}`);
+  }
+
+  async create(params: WebhookCreateParams): Promise<{ webhook: Webhook }> {
+    return this.client.post<{ webhook: Webhook }>('/webhooks', { webhook: params });
+  }
+
+  async update(webhookId: string, params: Partial<WebhookCreateParams>): Promise<{ webhook: Webhook }> {
+    return this.client.put<{ webhook: Webhook }>(`/webhooks/${webhookId}`, { webhook: params });
+  }
+
+  async delete(webhookId: string): Promise<void> {
+    await this.client.delete(`/webhooks/${webhookId}`);
+  }
+}