@elevasis/core 0.1.0

package/src/execution/engine/tools/integration/server/adapters/anymailfinder/anymailfinder-adapter.ts

@@ -0,0 +1,73 @@
+import type { BaseIntegrationAdapter } from '../../../base-integration-adapter'
+import { ToolingError } from '../../../../types'
+import type { ExecutionContext } from '../../../../../base/types'
+
+import { findCompanyEmail } from './fetch/find-company-email/index'
+import type { FindCompanyEmailParams } from './fetch/find-company-email/index'
+import { findPersonEmail } from './fetch/find-person-email/index'
+import type { FindPersonEmailParams } from './fetch/find-person-email/index'
+import { findDecisionMakerEmail } from './fetch/find-decision-maker-email/index'
+import type { FindDecisionMakerEmailParams } from './fetch/find-decision-maker-email/index'
+import { verifyEmail } from './fetch/verify-email/index'
+import type { VerifyEmailParams } from './fetch/verify-email/index'
+
+interface AnymailfinderCredentials {
+  apiKey: string
+}
+
+/**
+ * Anymailfinder integration adapter
+ *
+ * Provides access to the Anymailfinder email discovery API for finding and
+ * verifying email addresses by company domain, person name, or decision maker role.
+ *
+ * @example
+ * const adapter = new AnymailfinderAdapter()
+ * const result = await adapter.call(
+ *   'findCompanyEmail',
+ *   { domain: 'example.com' },
+ *   { apiKey: 'anymailfinder_api_...' },
+ *   context
+ * )
+ */
+export class AnymailfinderAdapter implements BaseIntegrationAdapter {
+  readonly name = 'anymailfinder'
+
+  async call(
+    method: string,
+    params: unknown,
+    credentials: Record<string, unknown>,
+    context?: ExecutionContext
+  ): Promise<unknown> {
+    if (!this.validateCredentials(credentials)) {
+      throw new ToolingError('credentials_invalid', 'Invalid Anymailfinder credentials', {
+        integration: this.name,
+        organizationId: context?.organizationId
+      })
+    }
+
+    const creds = credentials as unknown as AnymailfinderCredentials
+
+    switch (method) {
+      case 'findCompanyEmail':
+        return findCompanyEmail(creds, params as FindCompanyEmailParams, context)
+      case 'findPersonEmail':
+        return findPersonEmail(creds, params as FindPersonEmailParams, context)
+      case 'findDecisionMakerEmail':
+        return findDecisionMakerEmail(creds, params as FindDecisionMakerEmailParams, context)
+      case 'verifyEmail':
+        return verifyEmail(creds, params as VerifyEmailParams, context)
+      default:
+        throw new ToolingError('method_not_found', `Unknown Anymailfinder method: ${method}`, {
+          integration: this.name,
+          method,
+          organizationId: context?.organizationId
+        })
+    }
+  }
+
+  validateCredentials(credentials: Record<string, unknown>): boolean {
+    const creds = credentials as unknown as AnymailfinderCredentials
+    return !!creds.apiKey && typeof creds.apiKey === 'string' && creds.apiKey.length > 0
+  }
+}

package/src/execution/engine/tools/integration/server/adapters/anymailfinder/anymailfinder-tools.ts

@@ -0,0 +1,209 @@
+import { z } from 'zod'
+import { createIntegrationTool } from '../../../tool'
+import type { Tool } from '../../../../types'
+
+/**
+ * Create Anymailfinder find company email tool
+ *
+ * Discovers all email addresses at a company domain.
+ *
+ * @param credentialName - Name of credential in credentials table
+ * @returns Tool that finds company emails via Anymailfinder
+ *
+ * @example
+ * const findCompanyEmail = createAnymailfinderFindCompanyEmailTool('anymailfinder-elevasis')
+ */
+export function createAnymailfinderFindCompanyEmailTool(credentialName: string): Tool {
+  return createIntegrationTool({
+    name: 'anymailfinder_find_company_email',
+    description: `Find all email addresses at a company domain using Anymailfinder.
+
+USE CASES:
+- Discover all emails at a domain (up to 20)
+- Filter by email type (personal, generic, or all)
+
+REQUIRED PARAMETERS (at least one):
+- domain: Company domain (e.g., "example.com")
+- company_name: Company name (e.g., "Example Inc")
+
+OPTIONAL PARAMETERS:
+- email_type: "personal", "generic", or "all" (default: "all")
+
+OUTPUT:
+{
+  "email_status": "valid",
+  "emails": ["john@example.com", "info@example.com"],
+  "valid_emails": ["john@example.com"]
+}`,
+    inputSchema: z.object({
+      domain: z.string().optional().describe('Company domain (e.g., "example.com")'),
+      company_name: z.string().optional().describe('Company name (e.g., "Example Inc")'),
+      email_type: z.enum(['personal', 'generic', 'all']).optional().describe('Filter by email type (default: "all")')
+    }),
+    outputSchema: z.object({
+      email_status: z.string().describe('Overall status of the email search'),
+      emails: z.array(z.string()).describe('All emails found at the domain'),
+      valid_emails: z.array(z.string()).describe('Subset of emails that passed validation')
+    }),
+    integration: 'anymailfinder' as const,
+    method: 'findCompanyEmail' as const,
+    credentialName
+  })
+}
+
+/**
+ * Create Anymailfinder find person email tool
+ *
+ * Finds an individual's work email by name and company.
+ *
+ * @param credentialName - Name of credential in credentials table
+ * @returns Tool that finds a person's email via Anymailfinder
+ *
+ * @example
+ * const findPersonEmail = createAnymailfinderFindPersonEmailTool('anymailfinder-elevasis')
+ */
+export function createAnymailfinderFindPersonEmailTool(credentialName: string): Tool {
+  return createIntegrationTool({
+    name: 'anymailfinder_find_person_email',
+    description: `Find an individual's email address using their name and company domain.
+
+USE CASES:
+- Find email for a specific person when you have their name and company domain
+- Verify a person's work email
+
+REQUIRED PARAMETERS:
+- domain or company_name (at least one)
+- full_name or (first_name + last_name)
+
+OPTIONAL PARAMETERS:
+- domain: Company domain
+- company_name: Company name
+- full_name: Person's full name
+- first_name: First name
+- last_name: Last name
+
+OUTPUT:
+{
+  "email": "john@example.com",
+  "email_status": "valid",
+  "valid_email": "john@example.com"
+}`,
+    inputSchema: z.object({
+      domain: z.string().optional().describe('Company domain'),
+      company_name: z.string().optional().describe('Company name'),
+      full_name: z.string().optional().describe("Person's full name"),
+      first_name: z.string().optional().describe('First name'),
+      last_name: z.string().optional().describe('Last name')
+    }),
+    outputSchema: z.object({
+      email: z.string().describe('Found email address (empty string if not found)'),
+      email_status: z.string().describe('Validation status of the email'),
+      valid_email: z.string().describe('Email if valid, empty string otherwise')
+    }),
+    integration: 'anymailfinder' as const,
+    method: 'findPersonEmail' as const,
+    credentialName
+  })
+}
+
+/**
+ * Create Anymailfinder find decision maker email tool
+ *
+ * Finds a decision maker's email at a company by role category.
+ *
+ * @param credentialName - Name of credential in credentials table
+ * @returns Tool that finds decision maker emails via Anymailfinder
+ *
+ * @example
+ * const findDecisionMaker = createAnymailfinderFindDecisionMakerEmailTool('anymailfinder-elevasis')
+ */
+export function createAnymailfinderFindDecisionMakerEmailTool(credentialName: string): Tool {
+  return createIntegrationTool({
+    name: 'anymailfinder_find_decision_maker_email',
+    description: `Find a decision maker's email at a company by role category.
+
+USE CASES:
+- Find the owner/CEO email at a business
+- Find operations manager email
+- Find key decision makers when you don't have specific names
+
+REQUIRED PARAMETERS:
+- domain or company_name (at least one)
+- decision_maker_category: Array of role categories
+
+CATEGORIES: "ceo" (Owner/President/Founder), "operations", "marketing", "sales", "finance", "hr", "engineering", "it", "logistics", "buyer"
+
+OUTPUT:
+{
+  "email": "owner@example.com",
+  "email_status": "valid",
+  "valid_email": "owner@example.com",
+  "person_full_name": "Jane Smith",
+  "person_job_title": "Owner",
+  "person_linkedin_url": "https://linkedin.com/in/...",
+  "decision_maker_category": "ceo"
+}`,
+    inputSchema: z.object({
+      domain: z.string().optional().describe('Company domain'),
+      company_name: z.string().optional().describe('Company name'),
+      decision_maker_category: z
+        .array(z.string())
+        .describe(
+          'Role categories to search: "ceo", "operations", "marketing", "sales", "finance", "hr", "engineering", "it", "logistics", "buyer"'
+        )
+    }),
+    outputSchema: z.object({
+      email: z.string().describe('Found email address (empty string if not found)'),
+      email_status: z.string().describe('Validation status of the email'),
+      valid_email: z.string().describe('Email if valid, empty string otherwise'),
+      person_full_name: z.string().describe("Decision maker's full name"),
+      person_job_title: z.string().describe("Decision maker's job title"),
+      person_linkedin_url: z.string().describe("Decision maker's LinkedIn URL"),
+      decision_maker_category: z.string().describe('Matched role category')
+    }),
+    integration: 'anymailfinder' as const,
+    method: 'findDecisionMakerEmail' as const,
+    credentialName
+  })
+}
+
+/**
+ * Create Anymailfinder verify email tool
+ *
+ * Verifies whether an email address is deliverable.
+ *
+ * @param credentialName - Name of credential in credentials table
+ * @returns Tool that verifies email addresses via Anymailfinder
+ *
+ * @example
+ * const verifyEmail = createAnymailfinderVerifyEmailTool('anymailfinder-elevasis')
+ */
+export function createAnymailfinderVerifyEmailTool(credentialName: string): Tool {
+  return createIntegrationTool({
+    name: 'anymailfinder_verify_email',
+    description: `Verify if an email address is valid using Anymailfinder.
+
+USE CASES:
+- Verify an email before sending outreach
+- Check if a found email is deliverable
+
+REQUIRED PARAMETERS:
+- email: Email address to verify
+
+OUTPUT:
+{
+  "email_status": "valid"
+}
+
+Status values: "valid", "risky", "not_found", "blacklisted"`,
+    inputSchema: z.object({
+      email: z.string().describe('Email address to verify')
+    }),
+    outputSchema: z.object({
+      email_status: z.string().describe('Verification result: "valid", "risky", "not_found", or "blacklisted"')
+    }),
+    integration: 'anymailfinder' as const,
+    method: 'verifyEmail' as const,
+    credentialName
+  })
+}

package/src/execution/engine/tools/integration/server/adapters/anymailfinder/fetch/find-company-email/index.ts

@@ -0,0 +1,82 @@
+import { withRetry, createHttpError, DEFAULT_RETRY_POLICY } from '../../../../../../../../../platform/resilience'
+import type { ExecutionContext } from '../../../../../../../base/types'
+
+interface AnymailfinderCredentials {
+  apiKey: string
+}
+
+export interface FindCompanyEmailParams {
+  domain: string
+  company_name?: string
+  email_type?: 'personal' | 'generic' | 'all'
+}
+
+export interface FindCompanyEmailResult {
+  email_status: 'valid' | 'risky' | 'not_found' | 'blacklisted'
+  emails: string[]
+  valid_emails: string[]
+}
+
+const ANYMAILFINDER_API_BASE = 'https://api.anymailfinder.com/v5.1'
+
+/**
+ * Find email addresses for a company via Anymailfinder
+ *
+ * Searches for company-level email addresses by domain or company name.
+ * Returns all found emails plus the subset that passed validation.
+ *
+ * @param credentials - Anymailfinder API key
+ * @param params - Domain or company name and optional email type filter
+ * @param context - Execution context for logging
+ * @returns Email status, all emails found, and valid emails only
+ */
+export async function findCompanyEmail(
+  credentials: AnymailfinderCredentials,
+  params: FindCompanyEmailParams,
+  context?: ExecutionContext
+): Promise<FindCompanyEmailResult> {
+  const { apiKey } = credentials
+
+  if (!params.domain && !params.company_name) {
+    throw new Error('Either domain or company_name is required for findCompanyEmail')
+  }
+
+  if (context?.logger) {
+    context.logger.info(
+      `[AnymailfinderAdapter] findCompanyEmail: organizationId=${context.organizationId} executionId=${context.executionId} domain=${params.domain} company_name=${params.company_name}`
+    )
+  }
+
+  const response = await withRetry(async () => {
+    const res = await fetch(`${ANYMAILFINDER_API_BASE}/find-email/company`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: apiKey
+      },
+      body: JSON.stringify(params)
+    })
+
+    if (!res.ok) {
+      throw await createHttpError(res, {
+        integration: 'anymailfinder',
+        method: 'findCompanyEmail',
+        organizationId: context?.organizationId
+      })
+    }
+
+    return res.json()
+  }, DEFAULT_RETRY_POLICY)
+
+  if (context?.logger) {
+    context.logger.info(
+      `[AnymailfinderAdapter] findCompanyEmail complete: organizationId=${context.organizationId} email_status=${response.email_status} emailCount=${response.emails?.length ?? 0} validCount=${response.valid_emails?.length ?? 0}`
+    )
+  }
+
+  return {
+    email_status: response.email_status ?? 'not_found',
+    emails: response.emails ?? [],
+    valid_emails: response.valid_emails ?? []
+  }
+}

package/src/execution/engine/tools/integration/server/adapters/anymailfinder/fetch/find-decision-maker-email/index.ts

@@ -0,0 +1,122 @@
+import { ToolingError } from '../../../../../../types'
+import { withRetry, createHttpError, DEFAULT_RETRY_POLICY } from '../../../../../../../../../platform/resilience'
+import type { ExecutionContext } from '../../../../../../../base/types'
+
+interface AnymailfinderCredentials {
+  apiKey: string
+}
+
+export interface FindDecisionMakerEmailParams {
+  domain?: string
+  company_name?: string
+  decision_maker_category: string[]
+}
+
+export interface FindDecisionMakerEmailResult {
+  email: string
+  email_status: 'valid' | 'risky' | 'not_found' | 'blacklisted'
+  valid_email: string
+  person_full_name: string
+  person_job_title: string
+  person_linkedin_url: string
+  decision_maker_category: string
+}
+
+const ANYMAILFINDER_API_BASE = 'https://api.anymailfinder.com/v5.1'
+
+const _VALID_CATEGORIES = [
+  'ceo',
+  'operations',
+  'marketing',
+  'sales',
+  'finance',
+  'hr',
+  'engineering',
+  'it',
+  'logistics',
+  'buyer'
+] as const
+
+/**
+ * Find a decision maker email via Anymailfinder
+ *
+ * Searches for the email address of a decision maker at a company, identified
+ * by domain or company name, filtered by one or more role categories.
+ *
+ * @param credentials - Anymailfinder API key
+ * @param params - Company identifier (domain or name) and decision maker categories
+ * @param context - Execution context for logging
+ * @returns Email address, status, and person details for the matched decision maker
+ */
+export async function findDecisionMakerEmail(
+  credentials: AnymailfinderCredentials,
+  params: FindDecisionMakerEmailParams,
+  context?: ExecutionContext
+): Promise<FindDecisionMakerEmailResult> {
+  const { apiKey } = credentials
+  const { domain, company_name, decision_maker_category } = params
+
+  if (!domain && !company_name) {
+    throw new ToolingError('validation_error', 'Either domain or company_name is required', {
+      integration: 'anymailfinder',
+      method: 'findDecisionMakerEmail'
+    })
+  }
+
+  if (!decision_maker_category || decision_maker_category.length === 0) {
+    throw new ToolingError('validation_error', 'decision_maker_category is required and must be non-empty', {
+      integration: 'anymailfinder',
+      method: 'findDecisionMakerEmail'
+    })
+  }
+
+  const findUrl = `${ANYMAILFINDER_API_BASE}/find-email/decision-maker`
+
+  if (context?.logger) {
+    context.logger.info(
+      `[AnymailfinderAdapter] Finding decision maker email: organizationId=${context.organizationId} executionId=${context.executionId} domain=${domain || 'none'} company_name=${company_name || 'none'} categories=${decision_maker_category.join(',')}`
+    )
+  }
+
+  const response = await withRetry(async () => {
+    const res = await fetch(findUrl, {
+      method: 'POST',
+      headers: {
+        Authorization: apiKey,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({
+        ...(domain ? { domain } : {}),
+        ...(company_name ? { company_name } : {}),
+        decision_maker_category
+      }),
+      signal: AbortSignal.timeout(180_000)
+    })
+
+    if (!res.ok) {
+      throw await createHttpError(res, {
+        integration: 'anymailfinder',
+        method: 'findDecisionMakerEmail',
+        organizationId: context?.organizationId
+      })
+    }
+
+    return res.json()
+  }, DEFAULT_RETRY_POLICY)
+
+  if (context?.logger) {
+    context.logger.info(
+      `[AnymailfinderAdapter] Decision maker email fetched: organizationId=${context.organizationId} executionId=${context.executionId} email_status=${response.email_status ?? 'not_found'} category=${response.decision_maker_category ?? ''}`
+    )
+  }
+
+  return {
+    email: response.email ?? '',
+    email_status: response.email_status ?? 'not_found',
+    valid_email: response.valid_email ?? '',
+    person_full_name: response.person_full_name ?? '',
+    person_job_title: response.person_job_title ?? '',
+    person_linkedin_url: response.person_linkedin_url ?? '',
+    decision_maker_category: response.decision_maker_category ?? ''
+  }
+}

package/src/execution/engine/tools/integration/server/adapters/anymailfinder/fetch/find-person-email/index.ts

@@ -0,0 +1,89 @@
+import { withRetry, createHttpError, DEFAULT_RETRY_POLICY } from '../../../../../../../../../platform/resilience'
+import type { ExecutionContext } from '../../../../../../../base/types'
+
+interface AnymailfinderCredentials {
+  apiKey: string
+}
+
+export interface FindPersonEmailParams {
+  domain: string
+  company_name?: string
+  full_name?: string
+  first_name?: string
+  last_name?: string
+}
+
+export interface FindPersonEmailResult {
+  email: string
+  email_status: 'valid' | 'risky' | 'not_found' | 'blacklisted'
+  valid_email: string
+}
+
+const ANYMAILFINDER_API_BASE = 'https://api.anymailfinder.com/v5.1'
+
+/**
+ * Find a person's email address via Anymailfinder
+ *
+ * Searches for a specific person's email by combining their name with a
+ * company domain or name. Requires either full_name or first_name+last_name,
+ * and either domain or company_name.
+ *
+ * @param credentials - Anymailfinder API key
+ * @param params - Person name and company domain or name
+ * @param context - Execution context for logging
+ * @returns Email address, status, and validated email if available
+ */
+export async function findPersonEmail(
+  credentials: AnymailfinderCredentials,
+  params: FindPersonEmailParams,
+  context?: ExecutionContext
+): Promise<FindPersonEmailResult> {
+  const { apiKey } = credentials
+
+  if (!params.domain && !params.company_name) {
+    throw new Error('Either domain or company_name is required for findPersonEmail')
+  }
+
+  if (!params.full_name && !(params.first_name && params.last_name)) {
+    throw new Error('Either full_name or both first_name and last_name are required for findPersonEmail')
+  }
+
+  if (context?.logger) {
+    context.logger.info(
+      `[AnymailfinderAdapter] findPersonEmail: organizationId=${context.organizationId} executionId=${context.executionId} domain=${params.domain} company_name=${params.company_name} full_name=${params.full_name} first_name=${params.first_name} last_name=${params.last_name}`
+    )
+  }
+
+  const response = await withRetry(async () => {
+    const res = await fetch(`${ANYMAILFINDER_API_BASE}/find-email/person`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: apiKey
+      },
+      body: JSON.stringify(params)
+    })
+
+    if (!res.ok) {
+      throw await createHttpError(res, {
+        integration: 'anymailfinder',
+        method: 'findPersonEmail',
+        organizationId: context?.organizationId
+      })
+    }
+
+    return res.json()
+  }, DEFAULT_RETRY_POLICY)
+
+  if (context?.logger) {
+    context.logger.info(
+      `[AnymailfinderAdapter] findPersonEmail complete: organizationId=${context.organizationId} email_status=${response.email_status} email=${response.email ? '[found]' : '[not found]'}`
+    )
+  }
+
+  return {
+    email: response.email ?? '',
+    email_status: response.email_status ?? 'not_found',
+    valid_email: response.valid_email ?? ''
+  }
+}

package/src/execution/engine/tools/integration/server/adapters/anymailfinder/fetch/verify-email/index.ts

@@ -0,0 +1,84 @@
+import { ToolingError } from '../../../../../../types'
+import { withRetry, createHttpError, DEFAULT_RETRY_POLICY } from '../../../../../../../../../platform/resilience'
+import type { ExecutionContext } from '../../../../../../../base/types'
+
+interface AnymailfinderCredentials {
+  apiKey: string
+}
+
+export interface VerifyEmailParams {
+  email: string
+}
+
+export interface VerifyEmailResult {
+  email_status: 'valid' | 'risky' | 'not_found' | 'blacklisted'
+}
+
+const ANYMAILFINDER_API_BASE = 'https://api.anymailfinder.com/v5.1'
+
+/**
+ * Verify an email address via Anymailfinder
+ *
+ * Checks whether the given email address is valid, risky, not found, or
+ * blacklisted. Costs 0.2 credits per valid result.
+ *
+ * @param credentials - Anymailfinder API key
+ * @param params - Email address to verify
+ * @param context - Execution context for logging
+ * @returns Email status classification
+ */
+export async function verifyEmail(
+  credentials: AnymailfinderCredentials,
+  params: VerifyEmailParams,
+  context?: ExecutionContext
+): Promise<VerifyEmailResult> {
+  const { apiKey } = credentials
+  const { email } = params
+
+  if (!email) {
+    throw new ToolingError('validation_error', 'Missing required parameter: email', {
+      integration: 'anymailfinder',
+      method: 'verifyEmail'
+    })
+  }
+
+  const verifyUrl = `${ANYMAILFINDER_API_BASE}/verify-email`
+
+  if (context?.logger) {
+    context.logger.info(
+      `[AnymailfinderAdapter] Verifying email: organizationId=${context.organizationId} executionId=${context.executionId} email=${email}`
+    )
+  }
+
+  const response = await withRetry(async () => {
+    const res = await fetch(verifyUrl, {
+      method: 'POST',
+      headers: {
+        Authorization: apiKey,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({ email }),
+      signal: AbortSignal.timeout(180_000)
+    })
+
+    if (!res.ok) {
+      throw await createHttpError(res, {
+        integration: 'anymailfinder',
+        method: 'verifyEmail',
+        organizationId: context?.organizationId
+      })
+    }
+
+    return res.json()
+  }, DEFAULT_RETRY_POLICY)
+
+  if (context?.logger) {
+    context.logger.info(
+      `[AnymailfinderAdapter] Email verification complete: organizationId=${context.organizationId} executionId=${context.executionId} email=${email} email_status=${response.email_status ?? 'not_found'}`
+    )
+  }
+
+  return {
+    email_status: response.email_status ?? 'not_found'
+  }
+}

package/src/execution/engine/tools/integration/server/adapters/anymailfinder/index.ts

@@ -0,0 +1,16 @@
+// ============================================================================
+// ANYMAILFINDER ADAPTER
+// ============================================================================
+
+export { AnymailfinderAdapter } from './anymailfinder-adapter'
+
+// ============================================================================
+// ANYMAILFINDER TOOLS
+// ============================================================================
+
+export {
+  createAnymailfinderFindCompanyEmailTool,
+  createAnymailfinderFindPersonEmailTool,
+  createAnymailfinderFindDecisionMakerEmailTool,
+  createAnymailfinderVerifyEmailTool
+} from './anymailfinder-tools'