@hasna/connectors 0.8.2 → 0.9.1

package/connectors/connect-contactout/scripts/publish.ts

@@ -0,0 +1,210 @@
+#!/usr/bin/env bun
+/**
+ * Auto-versioning publish script
+ * - Fetches current npm version
+ * - Auto-bumps patch version if local version <= npm version
+ * - Creates git tag
+ * - Publishes to npm
+ */
+
+import { $ } from 'bun';
+import { readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+interface PackageJson {
+  name: string;
+  version: string;
+  [key: string]: unknown;
+}
+
+type BumpType = 'patch' | 'minor' | 'major';
+
+function parseVersion(version: string): { major: number; minor: number; patch: number } {
+  const [major, minor, patch] = version.split('.').map(Number);
+  return { major, minor, patch };
+}
+
+function bumpVersion(version: string, type: BumpType = 'patch'): string {
+  const { major, minor, patch } = parseVersion(version);
+
+  switch (type) {
+    case 'major':
+      return `${major + 1}.0.0`;
+    case 'minor':
+      return `${major}.${minor + 1}.0`;
+    case 'patch':
+    default:
+      return `${major}.${minor}.${patch + 1}`;
+  }
+}
+
+function compareVersions(a: string, b: string): number {
+  const vA = parseVersion(a);
+  const vB = parseVersion(b);
+
+  if (vA.major !== vB.major) return vA.major - vB.major;
+  if (vA.minor !== vB.minor) return vA.minor - vB.minor;
+  return vA.patch - vB.patch;
+}
+
+async function getNpmVersion(packageName: string): Promise<string | null> {
+  try {
+    const result = await $`npm view ${packageName} version 2>/dev/null`.text();
+    return result.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+async function hasUncommittedChanges(): Promise<boolean> {
+  try {
+    const result = await $`git status --porcelain`.text();
+    return result.trim().length > 0;
+  } catch {
+    return false;
+  }
+}
+
+async function isGitRepo(): Promise<boolean> {
+  try {
+    await $`git rev-parse --git-dir 2>/dev/null`.text();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function createGitTag(version: string, packageName: string): Promise<boolean> {
+  const tagName = `${packageName}@${version}`;
+
+  try {
+    // Check if tag already exists
+    const existingTags = await $`git tag -l ${tagName}`.text();
+    if (existingTags.trim()) {
+      console.log(`⚠️  Tag ${tagName} already exists, skipping tag creation`);
+      return true;
+    }
+
+    await $`git tag -a ${tagName} -m "Release ${tagName}"`;
+    console.log(`✅ Created git tag: ${tagName}`);
+    return true;
+  } catch (error) {
+    console.error(`❌ Failed to create git tag: ${error}`);
+    return false;
+  }
+}
+
+async function commitVersionBump(version: string, packageName: string): Promise<boolean> {
+  try {
+    await $`git add package.json`;
+    await $`git commit -m "chore(${packageName}): bump version to ${version}"`;
+    console.log(`✅ Committed version bump`);
+    return true;
+  } catch (error) {
+    console.error(`❌ Failed to commit: ${error}`);
+    return false;
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const bumpType = (args.find(a => ['patch', 'minor', 'major'].includes(a)) || 'patch') as BumpType;
+  const skipGit = args.includes('--skip-git');
+  const dryRun = args.includes('--dry-run');
+  const force = args.includes('--force');
+
+  // Read package.json
+  const pkgPath = join(process.cwd(), 'package.json');
+  const pkg: PackageJson = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+
+  console.log(`\n📦 Publishing ${pkg.name}\n`);
+
+  // Get current npm version
+  const npmVersion = await getNpmVersion(pkg.name);
+  let newVersion = pkg.version;
+
+  if (npmVersion) {
+    console.log(`📌 Current npm version: ${npmVersion}`);
+    console.log(`📌 Local version: ${pkg.version}`);
+
+    // Check if we need to bump
+    if (compareVersions(pkg.version, npmVersion) <= 0) {
+      newVersion = bumpVersion(npmVersion, bumpType);
+      console.log(`🔄 Auto-bumping to: ${newVersion}`);
+    } else {
+      console.log(`✅ Local version is ahead, using: ${pkg.version}`);
+    }
+  } else {
+    console.log(`📌 Package not yet published to npm`);
+    console.log(`📌 Using local version: ${pkg.version}`);
+  }
+
+  // Update package.json if version changed
+  if (newVersion !== pkg.version) {
+    if (dryRun) {
+      console.log(`\n🧪 DRY RUN: Would update version to ${newVersion}`);
+    } else {
+      pkg.version = newVersion;
+      writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+      console.log(`✅ Updated package.json to version ${newVersion}`);
+    }
+  }
+
+  // Git operations
+  const isGit = await isGitRepo();
+
+  if (isGit && !skipGit) {
+    const hasChanges = await hasUncommittedChanges();
+
+    if (hasChanges && newVersion !== pkg.version) {
+      if (dryRun) {
+        console.log(`🧪 DRY RUN: Would commit version bump`);
+      } else {
+        await commitVersionBump(newVersion, pkg.name.replace('@hasna/', ''));
+      }
+    }
+
+    if (dryRun) {
+      console.log(`🧪 DRY RUN: Would create tag ${pkg.name}@${newVersion}`);
+    } else {
+      await createGitTag(newVersion, pkg.name.replace('@hasna/', ''));
+    }
+  }
+
+  // Build
+  console.log(`\n🔨 Building...`);
+  if (!dryRun) {
+    await $`bun run build`;
+  } else {
+    console.log(`🧪 DRY RUN: Would run build`);
+  }
+
+  // Publish
+  console.log(`\n🚀 Publishing to npm...`);
+  if (dryRun) {
+    console.log(`🧪 DRY RUN: Would publish ${pkg.name}@${newVersion}`);
+  } else {
+    try {
+      await $`npm publish`;
+      console.log(`\n✅ Successfully published ${pkg.name}@${newVersion}`);
+    } catch (error) {
+      console.error(`\n❌ Publish failed: ${error}`);
+      process.exit(1);
+    }
+  }
+
+  // Push tags
+  if (isGit && !skipGit && !dryRun) {
+    console.log(`\n📤 Pushing tags to remote...`);
+    try {
+      await $`git push --tags`;
+      console.log(`✅ Pushed tags to remote`);
+    } catch {
+      console.log(`⚠️  Could not push tags (no remote or not configured)`);
+    }
+  }
+
+  console.log(`\n✨ Done!\n`);
+}
+
+main().catch(console.error);

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

@@ -0,0 +1,133 @@
+import type { ContactOutConfig, OutputFormat } from '../types';
+import { ContactOutApiError } from '../types';
+
+const DEFAULT_BASE_URL = 'https://api.contactout.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 ContactOutClient {
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+
+  constructor(config: ContactOutConfig) {
+    if (!config.apiKey) {
+      throw new Error('API key is required');
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl || DEFAULT_BASE_URL;
+  }
+
+  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();
+  }
+
+  /**
+   * Make an authenticated request to the ContactOut API
+   * Uses token header authentication as per ContactOut API docs
+   */
+  async request<T>(path: string, options: RequestOptions = {}): Promise<T> {
+    const { method = 'GET', params, body, headers = {} } = options;
+
+    const url = this.buildUrl(path, params);
+
+    // ContactOut uses token header for authentication
+    const requestHeaders: Record<string, string> = {
+      '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);
+    }
+
+    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 ContactOutApiError(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 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 '***';
+  }
+}

package/connectors/connect-contactout/src/api/company.ts

@@ -0,0 +1,60 @@
+import type { ContactOutClient } from './client';
+import type {
+  CompanySearchParams,
+  CompanySearchResponse,
+  DomainEnrichParams,
+  DomainEnrichResponse,
+} from '../types';
+
+/**
+ * Company API - Search and enrich company profiles
+ */
+export class CompanyApi {
+  constructor(private readonly client: ContactOutClient) {}
+
+  /**
+   * Search for companies matching criteria
+   * @param params - Search filters including name, domain, size, location, industry, revenue, etc.
+   * @returns Paginated list of matching companies
+   * @cost 1 search credit per company
+   */
+  async search(params: CompanySearchParams): Promise<CompanySearchResponse> {
+    return this.client.post<CompanySearchResponse>('/v1/company/search', {
+      name: params.name,
+      domain: params.domain,
+      size: params.size,
+      location: params.location,
+      industry: params.industry,
+      min_revenue: params.min_revenue,
+      max_revenue: params.max_revenue,
+      year_founded_from: params.year_founded_from,
+      year_founded_to: params.year_founded_to,
+      page: params.page,
+      hq_only: params.hq_only,
+    });
+  }
+
+  /**
+   * Enrich company information from domains
+   * @param params.domains - Array of domain names (max 30)
+   * @returns Company details for each domain
+   * @cost No credits consumed
+   */
+  async enrichFromDomains(params: DomainEnrichParams): Promise<DomainEnrichResponse> {
+    if (params.domains.length > 30) {
+      throw new Error('Maximum 30 domains allowed per request');
+    }
+    return this.client.post<DomainEnrichResponse>('/v1/domain/enrich', {
+      domains: params.domains,
+    });
+  }
+
+  /**
+   * Get company by domain (convenience method for single domain)
+   * @param domain - Company domain
+   * @returns Company profile
+   */
+  async getByDomain(domain: string): Promise<DomainEnrichResponse> {
+    return this.enrichFromDomains({ domains: [domain] });
+  }
+}

package/connectors/connect-contactout/src/api/email.ts

@@ -0,0 +1,81 @@
+import type { ContactOutClient } from './client';
+import type {
+  EmailEnrichParams,
+  EmailEnrichResponse,
+  EmailVerifyResponse,
+  BatchEmailVerifyParams,
+  BatchEmailVerifyResponse,
+  BatchEmailVerifyJobResponse,
+  EmailToLinkedInResponse,
+} from '../types';
+
+/**
+ * Email API - Enrich profiles from email, verify emails, find LinkedIn from email
+ */
+export class EmailApi {
+  constructor(private readonly client: ContactOutClient) {}
+
+  /**
+   * Enrich a profile from an email address
+   * @param params.email - Email address to lookup
+   * @param params.include - Optional: include work_email in response
+   * @returns Full profile data mapped to email
+   * @cost 1 email/phone credit per match
+   */
+  async enrich(params: EmailEnrichParams): Promise<EmailEnrichResponse> {
+    return this.client.get<EmailEnrichResponse>('/v1/email/enrich', {
+      email: params.email,
+      include: params.include,
+    });
+  }
+
+  /**
+   * Verify a single email address
+   * @param email - Email address to verify
+   * @returns Verification status: valid, invalid, accept_all, disposable, or unknown
+   * @cost 1 verifier credit if result is valid/invalid/accept_all
+   */
+  async verify(email: string): Promise<EmailVerifyResponse> {
+    return this.client.get<EmailVerifyResponse>('/v1/email/verify', {
+      email,
+    });
+  }
+
+  /**
+   * Batch verify multiple email addresses (asynchronous)
+   * @param params.emails - Array of email addresses (max 1000)
+   * @param params.callback_url - Optional webhook URL for completion notification
+   * @returns Job ID for polling
+   * @cost 1 verifier credit per email (valid/invalid/accept_all results)
+   */
+  async batchVerify(params: BatchEmailVerifyParams): Promise<BatchEmailVerifyResponse> {
+    if (params.emails.length > 1000) {
+      throw new Error('Maximum 1000 emails allowed per batch');
+    }
+    return this.client.post<BatchEmailVerifyResponse>('/v1/email/verify/batch', {
+      emails: params.emails,
+      callback_url: params.callback_url,
+    });
+  }
+
+  /**
+   * Get batch verification job status and results
+   * @param jobId - Job UUID from batchVerify
+   * @returns Job status and results when complete
+   */
+  async getBatchVerifyJob(jobId: string): Promise<BatchEmailVerifyJobResponse> {
+    return this.client.get<BatchEmailVerifyJobResponse>(`/v1/email/verify/batch/${jobId}`);
+  }
+
+  /**
+   * Find LinkedIn profile URL from an email address
+   * @param email - Email address to lookup
+   * @returns LinkedIn profile URL if found
+   * @cost 1 email credit if found
+   */
+  async toLinkedIn(email: string): Promise<EmailToLinkedInResponse> {
+    return this.client.get<EmailToLinkedInResponse>('/v1/people/person', {
+      email,
+    });
+  }
+}

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

@@ -0,0 +1,65 @@
+import type { ContactOutConfig } from '../types';
+import { ContactOutClient } from './client';
+import { LinkedInApi } from './linkedin';
+import { PeopleApi } from './people';
+import { CompanyApi } from './company';
+import { EmailApi } from './email';
+import { StatsApi } from './stats';
+
+/**
+ * ContactOut API Client
+ * Find emails, phone numbers, and enrich LinkedIn profiles
+ */
+export class ContactOut {
+  private readonly client: ContactOutClient;
+
+  // API modules
+  public readonly linkedin: LinkedInApi;
+  public readonly people: PeopleApi;
+  public readonly company: CompanyApi;
+  public readonly email: EmailApi;
+  public readonly stats: StatsApi;
+
+  constructor(config: ContactOutConfig) {
+    this.client = new ContactOutClient(config);
+    this.linkedin = new LinkedInApi(this.client);
+    this.people = new PeopleApi(this.client);
+    this.company = new CompanyApi(this.client);
+    this.email = new EmailApi(this.client);
+    this.stats = new StatsApi(this.client);
+  }
+
+  /**
+   * Create a client from environment variables
+   * Looks for CONTACTOUT_API_KEY
+   */
+  static fromEnv(): ContactOut {
+    const apiKey = process.env.CONTACTOUT_API_KEY;
+
+    if (!apiKey) {
+      throw new Error('CONTACTOUT_API_KEY environment variable is required');
+    }
+    return new ContactOut({ apiKey });
+  }
+
+  /**
+   * Get a preview of the API key (for debugging)
+   */
+  getApiKeyPreview(): string {
+    return this.client.getApiKeyPreview();
+  }
+
+  /**
+   * Get the underlying client for direct API access
+   */
+  getClient(): ContactOutClient {
+    return this.client;
+  }
+}
+
+export { ContactOutClient } from './client';
+export { LinkedInApi } from './linkedin';
+export { PeopleApi } from './people';
+export { CompanyApi } from './company';
+export { EmailApi } from './email';
+export { StatsApi } from './stats';

package/connectors/connect-contactout/src/api/linkedin.ts

@@ -0,0 +1,131 @@
+import type { ContactOutClient } from './client';
+import type {
+  LinkedInEnrichParams,
+  LinkedInEnrichResponse,
+  ContactInfoParams,
+  ContactInfoResponse,
+  BatchContactParams,
+  BatchContactResponse,
+  BatchJobResponse,
+  EmailStatusResponse,
+  PhoneStatusResponse,
+} from '../types';
+
+/**
+ * LinkedIn Profile API - Enrich and get contact info from LinkedIn profiles
+ */
+export class LinkedInApi {
+  constructor(private readonly client: ContactOutClient) {}
+
+  /**
+   * Enrich a LinkedIn profile - get full profile data including contact info
+   * @param params.profile - LinkedIn profile URL
+   * @param params.profile_only - If true, returns profile without contact info
+   * @returns Profile data with emails and phones
+   * @cost 1 email/phone credit per match; 1 search credit if profile_only
+   */
+  async enrich(params: LinkedInEnrichParams): Promise<LinkedInEnrichResponse> {
+    return this.client.get<LinkedInEnrichResponse>('/v1/linkedin/enrich', {
+      profile: params.profile,
+      profile_only: params.profile_only,
+    });
+  }
+
+  /**
+   * Get contact info for a single LinkedIn profile
+   * @param params.profile - LinkedIn profile URL
+   * @param params.include_phone - Include phone numbers in response
+   * @param params.email_type - Type of email to return: personal, work, personal,work, or none
+   * @returns Email addresses and phone numbers
+   * @cost 1 email/phone credit per match
+   */
+  async getContactInfo(params: ContactInfoParams): Promise<ContactInfoResponse> {
+    return this.client.get<ContactInfoResponse>('/v1/people/linkedin', {
+      profile: params.profile,
+      include_phone: params.include_phone,
+      email_type: params.email_type,
+    });
+  }
+
+  /**
+   * Batch get contact info for up to 30 LinkedIn profiles (synchronous)
+   * @param params.profiles - Array of LinkedIn profile URLs (max 30)
+   * @returns Map of LinkedIn URLs to email arrays
+   * @cost 1 email credit per profile with match
+   */
+  async batchContactInfo(params: BatchContactParams): Promise<BatchContactResponse> {
+    if (params.profiles.length > 30) {
+      throw new Error('V1 batch endpoint supports maximum 30 profiles. Use batchContactInfoAsync for larger batches.');
+    }
+    return this.client.post<BatchContactResponse>('/v1/people/linkedin/batch', {
+      profiles: params.profiles,
+    });
+  }
+
+  /**
+   * Batch get contact info for up to 1000 LinkedIn profiles (asynchronous)
+   * @param params.profiles - Array of LinkedIn profile URLs (max 1000)
+   * @param params.callback_url - Optional webhook URL for completion notification
+   * @param params.include_phone - Include phone numbers in response
+   * @returns Job ID for polling
+   * @cost 1 email credit per profile with match
+   */
+  async batchContactInfoAsync(params: BatchContactParams): Promise<BatchContactResponse> {
+    if (params.profiles.length > 1000) {
+      throw new Error('V2 batch endpoint supports maximum 1000 profiles');
+    }
+    return this.client.post<BatchContactResponse>('/v2/people/linkedin/batch', {
+      profiles: params.profiles,
+      callback_url: params.callback_url,
+      include_phone: params.include_phone,
+    });
+  }
+
+  /**
+   * Get batch job status and results
+   * @param jobId - Job UUID from batchContactInfoAsync
+   * @returns Job status and results when complete
+   */
+  async getBatchJob(jobId: string): Promise<BatchJobResponse> {
+    return this.client.get<BatchJobResponse>(`/v2/people/linkedin/batch/${jobId}`);
+  }
+
+  /**
+   * Check if personal email is available for a LinkedIn profile
+   * @param profile - LinkedIn profile URL
+   * @returns Boolean indicating if personal email is available
+   * @cost No credits consumed
+   * @access Paid users only
+   */
+  async checkPersonalEmailStatus(profile: string): Promise<EmailStatusResponse> {
+    return this.client.get<EmailStatusResponse>('/v1/people/linkedin/personal_email_status', {
+      profile,
+    });
+  }
+
+  /**
+   * Check if work email is available for a LinkedIn profile
+   * @param profile - LinkedIn profile URL
+   * @returns Email availability and verification status
+   * @cost No credits consumed
+   * @access Paid users only
+   */
+  async checkWorkEmailStatus(profile: string): Promise<EmailStatusResponse> {
+    return this.client.get<EmailStatusResponse>('/v1/people/linkedin/work_email_status', {
+      profile,
+    });
+  }
+
+  /**
+   * Check if phone number is available for a LinkedIn profile
+   * @param profile - LinkedIn profile URL
+   * @returns Boolean indicating if phone is available
+   * @cost No credits consumed
+   * @access Paid users only
+   */
+  async checkPhoneStatus(profile: string): Promise<PhoneStatusResponse> {
+    return this.client.get<PhoneStatusResponse>('/v1/people/linkedin/phone_status', {
+      profile,
+    });
+  }
+}