@hasna/connectors 0.0.1

package/connectors/connect-maropost/src/api/campaigns.ts

@@ -0,0 +1,129 @@
+import type { MaropostClient } from './client';
+import type {
+  Campaign,
+  CampaignListResponse,
+  CampaignReportResponse,
+  PaginationParams,
+} from '../types';
+
+export interface CampaignReportOptions extends PaginationParams {
+  unique?: boolean;
+}
+
+/**
+ * Campaigns API module for Maropost
+ * Manages email campaigns and retrieves campaign reports
+ */
+export class CampaignsApi {
+  constructor(private readonly client: MaropostClient) {}
+
+  /**
+   * List all campaigns with pagination
+   */
+  async list(options?: PaginationParams): Promise<CampaignListResponse> {
+    return this.client.get<CampaignListResponse>('/campaigns.json', {
+      page: options?.page,
+      per: options?.per,
+    });
+  }
+
+  /**
+   * Get a single campaign by ID
+   */
+  async get(id: number): Promise<Campaign> {
+    return this.client.get<Campaign>(`/campaigns/${id}.json`);
+  }
+
+  /**
+   * Get bounce report for a campaign
+   */
+  async getBounceReport(campaignId: number, options?: PaginationParams): Promise<CampaignReportResponse> {
+    return this.client.get<CampaignReportResponse>(`/campaigns/${campaignId}/bounce_report.json`, {
+      page: options?.page,
+      per: options?.per,
+    });
+  }
+
+  /**
+   * Get click report for a campaign
+   */
+  async getClickReport(campaignId: number, options?: CampaignReportOptions): Promise<CampaignReportResponse> {
+    return this.client.get<CampaignReportResponse>(`/campaigns/${campaignId}/click_report.json`, {
+      page: options?.page,
+      per: options?.per,
+      unique: options?.unique,
+    });
+  }
+
+  /**
+   * Get complaint report for a campaign
+   */
+  async getComplaintReport(campaignId: number, options?: PaginationParams): Promise<CampaignReportResponse> {
+    return this.client.get<CampaignReportResponse>(`/campaigns/${campaignId}/complaint_report.json`, {
+      page: options?.page,
+      per: options?.per,
+    });
+  }
+
+  /**
+   * Get delivered report for a campaign
+   */
+  async getDeliveredReport(campaignId: number, options?: PaginationParams): Promise<CampaignReportResponse> {
+    return this.client.get<CampaignReportResponse>(`/campaigns/${campaignId}/delivered_report.json`, {
+      page: options?.page,
+      per: options?.per,
+    });
+  }
+
+  /**
+   * Get hard bounce report for a campaign
+   */
+  async getHardBounceReport(campaignId: number, options?: PaginationParams): Promise<CampaignReportResponse> {
+    return this.client.get<CampaignReportResponse>(`/campaigns/${campaignId}/hard_bounce_report.json`, {
+      page: options?.page,
+      per: options?.per,
+    });
+  }
+
+  /**
+   * Get link report for a campaign
+   */
+  async getLinkReport(campaignId: number, options?: CampaignReportOptions): Promise<CampaignReportResponse> {
+    return this.client.get<CampaignReportResponse>(`/campaigns/${campaignId}/link_report.json`, {
+      page: options?.page,
+      per: options?.per,
+      unique: options?.unique,
+    });
+  }
+
+  /**
+   * Get open report for a campaign
+   */
+  async getOpenReport(campaignId: number, options?: CampaignReportOptions): Promise<CampaignReportResponse> {
+    return this.client.get<CampaignReportResponse>(`/campaigns/${campaignId}/open_report.json`, {
+      page: options?.page,
+      per: options?.per,
+      unique: options?.unique,
+    });
+  }
+
+  /**
+   * Get soft bounce report for a campaign
+   */
+  async getSoftBounceReport(campaignId: number, options?: PaginationParams): Promise<CampaignReportResponse> {
+    return this.client.get<CampaignReportResponse>(`/campaigns/${campaignId}/soft_bounce_report.json`, {
+      page: options?.page,
+      per: options?.per,
+    });
+  }
+
+  /**
+   * Get unsubscribe report for a campaign
+   */
+  async getUnsubscribeReport(campaignId: number, options?: PaginationParams): Promise<CampaignReportResponse> {
+    return this.client.get<CampaignReportResponse>(`/campaigns/${campaignId}/unsubscribe_report.json`, {
+      page: options?.page,
+      per: options?.per,
+    });
+  }
+}

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

@@ -0,0 +1,162 @@
+import type { MaropostConfig, OutputFormat } from '../types';
+import { MaropostApiError } from '../types';
+
+const DEFAULT_BASE_URL = 'https://api.maropost.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;
+}
+
+export class MaropostClient {
+  private readonly apiKey: string;
+  private readonly accountId: number;
+  private readonly baseUrl: string;
+
+  constructor(config: MaropostConfig) {
+    if (!config.apiKey) {
+      throw new Error('API key (auth_token) is required');
+    }
+    if (!config.accountId) {
+      throw new Error('Account ID is required');
+    }
+    this.apiKey = config.apiKey;
+    this.accountId = config.accountId;
+    this.baseUrl = config.baseUrl || DEFAULT_BASE_URL;
+  }
+
+  /**
+   * Get the account-scoped base path
+   */
+  private getAccountPath(): string {
+    return `/accounts/${this.accountId}`;
+  }
+
+  /**
+   * Build URL with auth_token query parameter
+   * Maropost uses auth_token as query param for all requests
+   */
+  private buildUrl(path: string, params?: Record<string, string | number | boolean | undefined>): string {
+    // Ensure path starts with /accounts/{accountId}
+    const fullPath = path.startsWith('/accounts/') ? path : `${this.getAccountPath()}${path}`;
+    const url = new URL(`${this.baseUrl}${fullPath}`);
+
+    // Always add auth_token as query parameter
+    url.searchParams.append('auth_token', this.apiKey);
+
+    if (params) {
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null && value !== '') {
+          url.searchParams.append(key, String(value));
+        }
+      });
+    }
+
+    return url.toString();
+  }
+
+  /**
+   * Make an authenticated request to the Maropost API
+   * Authentication is via auth_token query parameter
+   */
+  async request<T>(path: string, options: RequestOptions = {}): Promise<T> {
+    const { method = 'GET', params, body, headers = {} } = options;
+
+    const url = this.buildUrl(path, params);
+
+    const requestHeaders: Record<string, string> = {
+      '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);
+    }
+
+    const response = await fetch(url, fetchOptions);
+
+    // Handle 204 No Content
+    if (response.status === 204) {
+      return {} as T;
+    }
+
+    // Parse response
+    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();
+    }
+
+    // Handle errors
+    if (!response.ok) {
+      const errorMessage = typeof data === 'object' && data !== null
+        ? JSON.stringify(data)
+        : String(data || response.statusText);
+      throw new MaropostApiError(errorMessage, response.status);
+    }
+
+    return data as T;
+  }
+
+  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 });
+  }
+
+  /**
+   * Get the account ID
+   */
+  getAccountId(): number {
+    return this.accountId;
+  }
+
+  /**
+   * Get a preview of the API key (for display/debugging)
+   */
+  getApiKeyPreview(): string {
+    if (this.apiKey.length > 10) {
+      return `${this.apiKey.substring(0, 6)}...${this.apiKey.substring(this.apiKey.length - 4)}`;
+    }
+    return '***';
+  }
+}
+
+// Alias for backward compatibility
+export const ConnectorClient = MaropostClient;

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

@@ -0,0 +1,128 @@
+import type { MaropostClient } from './client';
+import type {
+  Contact,
+  ContactListResponse,
+  CreateContactParams,
+  UpdateContactParams,
+  PaginationParams,
+  OpenReport,
+  ClickReport,
+  ReportListResponse,
+} from '../types';
+
+/**
+ * Contacts API module for Maropost
+ * Manages contact records, tags, and list memberships
+ */
+export class ContactsApi {
+  constructor(private readonly client: MaropostClient) {}
+
+  /**
+   * Get a contact by email address
+   */
+  async getByEmail(email: string): Promise<Contact> {
+    return this.client.get<Contact>(`/contacts/${encodeURIComponent(email)}.json`);
+  }
+
+  /**
+   * Create a new contact
+   */
+  async create(params: CreateContactParams): Promise<Contact> {
+    return this.client.post<Contact>('/contacts.json', { contact: params });
+  }
+
+  /**
+   * Update an existing contact by ID
+   */
+  async update(id: number, params: UpdateContactParams): Promise<Contact> {
+    return this.client.put<Contact>(`/contacts/${id}.json`, { contact: params });
+  }
+
+  /**
+   * Delete a contact by ID
+   */
+  async delete(id: number): Promise<void> {
+    await this.client.delete(`/contacts/${id}.json`);
+  }
+
+  /**
+   * Delete a contact by UID
+   */
+  async deleteByUid(uid: string): Promise<void> {
+    await this.client.delete('/contacts/uid.json', { uid });
+  }
+
+  /**
+   * Get contacts in a specific list
+   */
+  async listInList(listId: number, options?: PaginationParams): Promise<ContactListResponse> {
+    return this.client.get<ContactListResponse>(`/lists/${listId}/contacts.json`, {
+      page: options?.page,
+      per: options?.per,
+    });
+  }
+
+  /**
+   * Create a contact in a specific list
+   */
+  async createInList(listId: number, params: CreateContactParams): Promise<Contact> {
+    return this.client.post<Contact>(`/lists/${listId}/contacts.json`, { contact: params });
+  }
+
+  /**
+   * Update a contact in a specific list
+   */
+  async updateInList(listId: number, contactId: number, params: UpdateContactParams): Promise<Contact> {
+    return this.client.put<Contact>(`/lists/${listId}/contacts/${contactId}.json`, { contact: params });
+  }
+
+  /**
+   * Delete a contact from a specific list
+   */
+  async deleteFromList(listId: number, contactId: number): Promise<void> {
+    await this.client.delete(`/lists/${listId}/contacts/${contactId}.json`);
+  }
+
+  /**
+   * Delete a contact from a list by UID
+   */
+  async deleteFromListByUid(listId: number, uid: string): Promise<void> {
+    await this.client.delete(`/lists/${listId}/contacts/uid.json`, { uid });
+  }
+
+  /**
+   * Get open report for a specific contact
+   */
+  async getOpenReport(contactId: number, options?: PaginationParams): Promise<ReportListResponse<OpenReport>> {
+    return this.client.get<ReportListResponse<OpenReport>>(`/contacts/${contactId}/open_report.json`, {
+      page: options?.page,
+      per: options?.per,
+    });
+  }
+
+  /**
+   * Get click report for a specific contact
+   */
+  async getClickReport(contactId: number, options?: PaginationParams): Promise<ReportListResponse<ClickReport>> {
+    return this.client.get<ReportListResponse<ClickReport>>(`/contacts/${contactId}/click_report.json`, {
+      page: options?.page,
+      per: options?.per,
+    });
+  }
+
+  /**
+   * Add tags to a contact
+   */
+  async addTags(email: string, tags: string[]): Promise<Contact> {
+    const contact = await this.getByEmail(email);
+    return this.update(contact.id, { tags });
+  }
+
+  /**
+   * Remove tags from a contact
+   */
+  async removeTags(email: string, tags: string[]): Promise<Contact> {
+    const contact = await this.getByEmail(email);
+    return this.update(contact.id, { remove_tags: tags });
+  }
+}

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

@@ -0,0 +1,91 @@
+import type { MaropostConfig } from '../types';
+import { MaropostClient } from './client';
+import { ContactsApi } from './contacts';
+import { ListsApi } from './lists';
+import { CampaignsApi } from './campaigns';
+import { ReportsApi } from './reports';
+import { JourneysApi } from './journeys';
+import { TransactionalApi } from './transactional';
+
+/**
+ * Main Maropost API class
+ * Provides access to all Maropost Marketing Cloud API modules
+ */
+export class Maropost {
+  private readonly client: MaropostClient;
+
+  // API modules
+  public readonly contacts: ContactsApi;
+  public readonly lists: ListsApi;
+  public readonly campaigns: CampaignsApi;
+  public readonly reports: ReportsApi;
+  public readonly journeys: JourneysApi;
+  public readonly transactional: TransactionalApi;
+
+  constructor(config: MaropostConfig) {
+    this.client = new MaropostClient(config);
+    this.contacts = new ContactsApi(this.client);
+    this.lists = new ListsApi(this.client);
+    this.campaigns = new CampaignsApi(this.client);
+    this.reports = new ReportsApi(this.client);
+    this.journeys = new JourneysApi(this.client);
+    this.transactional = new TransactionalApi(config.apiKey);
+  }
+
+  /**
+   * Create a client from environment variables
+   * Looks for MAROPOST_API_KEY and MAROPOST_ACCOUNT_ID
+   */
+  static fromEnv(): Maropost {
+    const apiKey = process.env.MAROPOST_API_KEY;
+    const accountIdStr = process.env.MAROPOST_ACCOUNT_ID;
+    const baseUrl = process.env.MAROPOST_BASE_URL;
+
+    if (!apiKey) {
+      throw new Error('MAROPOST_API_KEY environment variable is required');
+    }
+    if (!accountIdStr) {
+      throw new Error('MAROPOST_ACCOUNT_ID environment variable is required');
+    }
+
+    const accountId = parseInt(accountIdStr, 10);
+    if (isNaN(accountId)) {
+      throw new Error('MAROPOST_ACCOUNT_ID must be a valid number');
+    }
+
+    return new Maropost({ apiKey, accountId, baseUrl });
+  }
+
+  /**
+   * Get a preview of the API key (for debugging)
+   */
+  getApiKeyPreview(): string {
+    return this.client.getApiKeyPreview();
+  }
+
+  /**
+   * Get the account ID
+   */
+  getAccountId(): number {
+    return this.client.getAccountId();
+  }
+
+  /**
+   * Get the underlying client for direct API access
+   */
+  getClient(): MaropostClient {
+    return this.client;
+  }
+}
+
+// Alias for backward compatibility
+export const Connector = Maropost;
+
+// Export all modules
+export { MaropostClient, ConnectorClient } from './client';
+export { ContactsApi } from './contacts';
+export { ListsApi } from './lists';
+export { CampaignsApi } from './campaigns';
+export { ReportsApi } from './reports';
+export { JourneysApi } from './journeys';
+export { TransactionalApi } from './transactional';

package/connectors/connect-maropost/src/api/journeys.ts

@@ -0,0 +1,60 @@
+import type { MaropostClient } from './client';
+import type {
+  Journey,
+  JourneyResponse,
+  JourneyContact,
+  PaginationParams,
+} from '../types';
+
+/**
+ * Journeys API module for Maropost
+ * Manages automated email workflows/journeys
+ */
+export class JourneysApi {
+  constructor(private readonly client: MaropostClient) {}
+
+  /**
+   * List all journeys with pagination
+   */
+  async list(options?: PaginationParams): Promise<JourneyResponse> {
+    return this.client.get<JourneyResponse>('/journeys.json', {
+      page: options?.page,
+      per: options?.per,
+    });
+  }
+
+  /**
+   * Get a single journey by ID
+   */
+  async get(id: number): Promise<Journey> {
+    return this.client.get<Journey>(`/journeys/${id}.json`);
+  }
+
+  /**
+   * Pause a journey for a specific contact
+   */
+  async pauseForContact(journeyId: number, contactId: number): Promise<JourneyContact> {
+    return this.client.post<JourneyContact>(`/journeys/${journeyId}/stop/${contactId}.json`);
+  }
+
+  /**
+   * Resume a journey for a specific contact
+   */
+  async resumeForContact(journeyId: number, contactId: number): Promise<JourneyContact> {
+    return this.client.post<JourneyContact>(`/journeys/${journeyId}/start/${contactId}.json`);
+  }
+
+  /**
+   * Reset a contact's position in a journey
+   */
+  async resetForContact(journeyId: number, contactId: number): Promise<JourneyContact> {
+    return this.client.post<JourneyContact>(`/journeys/${journeyId}/reset/${contactId}.json`);
+  }
+
+  /**
+   * Add a contact to a journey by email
+   */
+  async addContact(journeyId: number, email: string): Promise<JourneyContact> {
+    return this.client.post<JourneyContact>(`/journeys/${journeyId}/contacts.json`, { email });
+  }
+}

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

@@ -0,0 +1,80 @@
+import type { MaropostClient } from './client';
+import type {
+  List,
+  ListResponse,
+  CreateListParams,
+  UpdateListParams,
+  PaginationParams,
+  Contact,
+  ContactListResponse,
+} from '../types';
+
+/**
+ * Lists API module for Maropost
+ * Manages contact lists and list membership
+ */
+export class ListsApi {
+  constructor(private readonly client: MaropostClient) {}
+
+  /**
+   * List all lists with pagination
+   */
+  async list(options?: PaginationParams): Promise<ListResponse> {
+    return this.client.get<ListResponse>('/lists.json', {
+      page: options?.page,
+      per: options?.per,
+    });
+  }
+
+  /**
+   * Get a single list by ID
+   */
+  async get(id: number): Promise<List> {
+    return this.client.get<List>(`/lists/${id}.json`);
+  }
+
+  /**
+   * Create a new list
+   */
+  async create(params: CreateListParams): Promise<List> {
+    return this.client.post<List>('/lists.json', { list: params });
+  }
+
+  /**
+   * Update an existing list
+   */
+  async update(id: number, params: UpdateListParams): Promise<List> {
+    return this.client.put<List>(`/lists/${id}.json`, { list: params });
+  }
+
+  /**
+   * Delete a list
+   */
+  async delete(id: number): Promise<void> {
+    await this.client.delete(`/lists/${id}.json`);
+  }
+
+  /**
+   * Get contacts in a list
+   */
+  async getContacts(listId: number, options?: PaginationParams): Promise<ContactListResponse> {
+    return this.client.get<ContactListResponse>(`/lists/${listId}/contacts.json`, {
+      page: options?.page,
+      per: options?.per,
+    });
+  }
+
+  /**
+   * Add a contact to a list
+   */
+  async addContact(listId: number, contact: { email: string; first_name?: string; last_name?: string }): Promise<Contact> {
+    return this.client.post<Contact>(`/lists/${listId}/contacts.json`, { contact });
+  }
+
+  /**
+   * Remove a contact from a list
+   */
+  async removeContact(listId: number, contactId: number): Promise<void> {
+    await this.client.delete(`/lists/${listId}/contacts/${contactId}.json`);
+  }
+}