@elevasis/core 0.1.0

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

@@ -0,0 +1,78 @@
+import type { BaseIntegrationAdapter } from '../../../base-integration-adapter'
+import { ToolingError } from '../../../../types'
+import type { ExecutionContext } from '../../../../../base/types'
+
+import { emailFinder } from './fetch/email-finder/index'
+import type { EmailFinderParams } from './fetch/email-finder/index'
+import { domainSearch } from './fetch/domain-search/index'
+import type { DomainSearchParams } from './fetch/domain-search/index'
+import { emailVerifier } from './fetch/email-verifier/index'
+import type { EmailVerifierParams } from './fetch/email-verifier/index'
+
+interface TombaCredentials {
+  apiKey: string
+  apiSecret: string
+}
+
+/**
+ * Tomba integration adapter
+ *
+ * Provides access to the Tomba email discovery API for finding and verifying
+ * email addresses by company domain or person name. Uses dual-header
+ * authentication (X-Tomba-Key + X-Tomba-Secret) on every request.
+ *
+ * @example
+ * const adapter = new TombaAdapter()
+ * const result = await adapter.call(
+ *   'emailFinder',
+ *   { domain: 'example.com', firstName: 'John', lastName: 'Doe' },
+ *   { apiKey: 'ta_xxxx', apiSecret: 'ts_xxxx' },
+ *   context
+ * )
+ */
+export class TombaAdapter implements BaseIntegrationAdapter {
+  readonly name = 'tomba'
+
+  async call(
+    method: string,
+    params: unknown,
+    credentials: Record<string, unknown>,
+    context?: ExecutionContext
+  ): Promise<unknown> {
+    if (!this.validateCredentials(credentials)) {
+      throw new ToolingError('credentials_invalid', 'Invalid Tomba credentials', {
+        integration: this.name,
+        organizationId: context?.organizationId
+      })
+    }
+
+    const creds = credentials as unknown as TombaCredentials
+
+    switch (method) {
+      case 'emailFinder':
+        return emailFinder(creds, params as EmailFinderParams, context)
+      case 'domainSearch':
+        return domainSearch(creds, params as DomainSearchParams, context)
+      case 'emailVerifier':
+        return emailVerifier(creds, params as EmailVerifierParams, context)
+      default:
+        throw new ToolingError('method_not_found', `Unknown Tomba method: ${method}`, {
+          integration: this.name,
+          method,
+          organizationId: context?.organizationId
+        })
+    }
+  }
+
+  validateCredentials(credentials: Record<string, unknown>): boolean {
+    const creds = credentials as unknown as TombaCredentials
+    return (
+      !!creds.apiKey &&
+      typeof creds.apiKey === 'string' &&
+      creds.apiKey.length > 0 &&
+      !!creds.apiSecret &&
+      typeof creds.apiSecret === 'string' &&
+      creds.apiSecret.length > 0
+    )
+  }
+}

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

@@ -0,0 +1,222 @@
+import { z } from 'zod'
+import { createIntegrationTool } from '../../../tool'
+import type { Tool } from '../../../../types'
+
+/**
+ * Create Tomba email finder tool
+ *
+ * Finds a specific person's work email by first name, last name, and domain.
+ *
+ * @param credentialName - Name of credential in credentials table
+ * @returns Tool that finds a person's email via Tomba
+ *
+ * @example
+ * const emailFinder = createTombaEmailFinderTool('elevasis-tomba')
+ */
+export function createTombaEmailFinderTool(credentialName: string): Tool {
+  return createIntegrationTool({
+    name: 'tomba_email_finder',
+    description: `Find a person's work email address using their name and company domain via Tomba.
+
+USE CASES:
+- Find email for a specific person when you have their name and company domain
+- Discover a person's professional email with verification score
+
+REQUIRED PARAMETERS:
+- domain: Company domain (e.g., "stripe.com")
+- firstName: Person's first name
+- lastName: Person's last name
+
+OUTPUT:
+{
+  "email": "john.doe@stripe.com",
+  "firstName": "John",
+  "lastName": "Doe",
+  "fullName": "John Doe",
+  "position": "Engineer",
+  "company": "Stripe",
+  "country": "US",
+  "score": 90,
+  "verificationDate": "2025-01-15",
+  "verificationStatus": "valid",
+  "sources": [...]
+}`,
+    inputSchema: z.object({
+      domain: z.string().describe('Company domain (e.g., "stripe.com")'),
+      firstName: z.string().describe("Person's first name"),
+      lastName: z.string().describe("Person's last name")
+    }),
+    outputSchema: z.object({
+      email: z.string().describe('Found email address (empty string if not found)'),
+      firstName: z.string().describe("Person's first name"),
+      lastName: z.string().describe("Person's last name"),
+      fullName: z.string().describe("Person's full name"),
+      position: z.string().describe("Person's job title or position"),
+      company: z.string().describe('Company name'),
+      country: z.string().describe('Country code'),
+      score: z.number().describe('Confidence score (0-100)'),
+      verificationDate: z.string().describe('Date email was last verified'),
+      verificationStatus: z.string().describe('Verification result (e.g., "valid")'),
+      sources: z
+        .array(
+          z.object({
+            uri: z.string(),
+            extractedOn: z.string(),
+            lastSeenOn: z.string(),
+            stillOnPage: z.boolean()
+          })
+        )
+        .describe('Sources where the email was found')
+    }),
+    integration: 'tomba' as const,
+    method: 'emailFinder' as const,
+    credentialName
+  })
+}
+
+/**
+ * Create Tomba domain search tool
+ *
+ * Finds all email addresses at a company domain.
+ *
+ * @param credentialName - Name of credential in credentials table
+ * @returns Tool that finds all emails at a domain via Tomba
+ *
+ * @example
+ * const domainSearch = createTombaDomainSearchTool('elevasis-tomba')
+ */
+export function createTombaDomainSearchTool(credentialName: string): Tool {
+  return createIntegrationTool({
+    name: 'tomba_domain_search',
+    description: `Find all email addresses at a company domain using Tomba.
+
+USE CASES:
+- Discover all known emails at a company
+- Filter emails by department (e.g., "management", "finance")
+- Get enriched data per email including position and verification
+
+REQUIRED PARAMETERS:
+- domain: Company domain (e.g., "stripe.com")
+
+OPTIONAL PARAMETERS:
+- limit: Maximum number of emails to return
+- department: Filter by department (e.g., "management", "finance", "sales")
+
+OUTPUT:
+{
+  "organizationName": "Stripe",
+  "domain": "stripe.com",
+  "emails": [
+    {
+      "email": "john.doe@stripe.com",
+      "firstName": "John",
+      "lastName": "Doe",
+      "fullName": "John Doe",
+      "position": "Engineer",
+      "department": "engineering",
+      "verificationDate": "2025-01-15",
+      "verificationStatus": "valid",
+      "sources": [...]
+    }
+  ]
+}`,
+    inputSchema: z.object({
+      domain: z.string().describe('Company domain (e.g., "stripe.com")'),
+      limit: z.number().optional().describe('Maximum number of emails to return'),
+      department: z.string().optional().describe('Filter by department (e.g., "management", "finance", "sales")')
+    }),
+    outputSchema: z.object({
+      organizationName: z.string().describe('Organization name'),
+      domain: z.string().describe('Company domain'),
+      emails: z
+        .array(
+          z.object({
+            email: z.string(),
+            firstName: z.string(),
+            lastName: z.string(),
+            fullName: z.string(),
+            position: z.string(),
+            department: z.string(),
+            verificationDate: z.string(),
+            verificationStatus: z.string(),
+            sources: z.array(
+              z.object({
+                uri: z.string(),
+                extractedOn: z.string(),
+                lastSeenOn: z.string(),
+                stillOnPage: z.boolean()
+              })
+            )
+          })
+        )
+        .describe('List of email records found at the domain')
+    }),
+    integration: 'tomba' as const,
+    method: 'domainSearch' as const,
+    credentialName
+  })
+}
+
+/**
+ * Create Tomba email verifier tool
+ *
+ * Verifies whether an email address is deliverable.
+ *
+ * @param credentialName - Name of credential in credentials table
+ * @returns Tool that verifies email addresses via Tomba
+ *
+ * @example
+ * const emailVerifier = createTombaEmailVerifierTool('elevasis-tomba')
+ */
+export function createTombaEmailVerifierTool(credentialName: string): Tool {
+  return createIntegrationTool({
+    name: 'tomba_email_verifier',
+    description: `Verify if an email address is valid and deliverable using Tomba.
+
+USE CASES:
+- Verify an email before sending outreach
+- Check MX records and SMTP server availability
+- Detect disposable or webmail addresses
+
+REQUIRED PARAMETERS:
+- email: Email address to verify
+
+OUTPUT:
+{
+  "email": "john.doe@stripe.com",
+  "result": "deliverable",
+  "status": "valid",
+  "score": 95,
+  "mxRecords": true,
+  "smtpServer": true,
+  "smtpCheck": true,
+  "acceptAll": false,
+  "block": false,
+  "gibberish": false,
+  "disposable": false,
+  "webmail": false,
+  "regex": true
+}`,
+    inputSchema: z.object({
+      email: z.string().describe('Email address to verify')
+    }),
+    outputSchema: z.object({
+      email: z.string().describe('Email address that was verified'),
+      result: z.string().describe('Deliverability result (e.g., "deliverable", "undeliverable")'),
+      status: z.string().describe('Verification status (e.g., "valid", "invalid")'),
+      score: z.number().describe('Confidence score (0-100)'),
+      mxRecords: z.boolean().describe('Whether MX records exist for the domain'),
+      smtpServer: z.boolean().describe('Whether SMTP server is reachable'),
+      smtpCheck: z.boolean().describe('Whether SMTP check passed'),
+      acceptAll: z.boolean().describe('Whether the server accepts all emails (catch-all)'),
+      block: z.boolean().describe('Whether the email is blocked'),
+      gibberish: z.boolean().describe('Whether the email looks like gibberish'),
+      disposable: z.boolean().describe('Whether it is a disposable email address'),
+      webmail: z.boolean().describe('Whether it is a webmail address (Gmail, Yahoo, etc.)'),
+      regex: z.boolean().describe('Whether the email passes regex validation')
+    }),
+    integration: 'tomba' as const,
+    method: 'emailVerifier' as const,
+    credentialName
+  })
+}

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

@@ -0,0 +1,61 @@
+/**
+ * Integration Tool Factories
+ *
+ * Factory functions for creating integration tools that call external APIs.
+ * Each factory creates a tool pre-configured for a specific integration and method.
+ *
+ * Available Factories:
+ * - Gmail: createGmailSendEmailTool, createGmailSendEmailToolNamed
+ * - Attio: createAttioCreateRecordTool, createAttioUpdateRecordTool,
+ *          createAttioListRecordsTool, createAttioGetRecordTool,
+ *          createAttioToolNamed
+ * - Apify: createApifyRunActorTool, createApifyStartActorTool
+ * - Instantly: createInstantlySendReplyTool, createInstantlyRemoveFromSubsequenceTool,
+ *              createInstantlyGetEmailsTool, createInstantlyUpdateInterestStatusTool,
+ *              createInstantlyAddToCampaignTool, createInstantlyListCampaignsTool,
+ *              createInstantlyGetCampaignTool, createInstantlyUpdateCampaignTool,
+ *              createInstantlyPauseCampaignTool, createInstantlyActivateCampaignTool,
+ *              createInstantlyGetCampaignAnalyticsTool, createInstantlyGetStepAnalyticsTool,
+ *              createInstantlyBulkAddLeadsTool, createInstantlyGetAccountHealthTool,
+ *              createInstantlyCreateInboxTestTool
+ *
+ * Future Factories (implement as needed):
+ * - Slack: createSlackPostMessageTool
+ * - GitHub: createGithubCreateIssueTool
+ * - etc.
+ */
+
+export { createGmailSendEmailTool, createGmailSendEmailToolNamed } from './adapters/gmail/gmail-tools'
+export {
+  createAttioCreateRecordTool,
+  createAttioUpdateRecordTool,
+  createAttioListRecordsTool,
+  createAttioGetRecordTool,
+  createAttioToolNamed
+} from './adapters/attio'
+export { createApifyRunActorTool, createApifyStartActorTool } from './adapters/apify'
+export {
+  createInstantlySendReplyTool,
+  createInstantlyRemoveFromSubsequenceTool,
+  createInstantlyGetEmailsTool,
+  createInstantlyUpdateInterestStatusTool,
+  createInstantlyAddToCampaignTool,
+  createInstantlyListCampaignsTool,
+  createInstantlyGetCampaignTool,
+  createInstantlyUpdateCampaignTool,
+  createInstantlyPauseCampaignTool,
+  createInstantlyActivateCampaignTool,
+  createInstantlyGetCampaignAnalyticsTool,
+  createInstantlyGetStepAnalyticsTool,
+  createInstantlyBulkAddLeadsTool,
+  createInstantlyGetAccountHealthTool,
+  createInstantlyCreateInboxTestTool
+} from './adapters/instantly'
+export { createResendSendEmailTool, createResendGetEmailTool, createResendSendEmailToolNamed } from './adapters/resend'
+export {
+  createStripeCreatePaymentLinkTool,
+  createStripeGetPaymentLinkTool,
+  createStripeUpdatePaymentLinkTool,
+  createStripeListPaymentLinksTool,
+  createStripeCheckoutSessionTool
+} from './adapters/stripe'

package/src/execution/engine/tools/integration/service.ts

@@ -0,0 +1,161 @@
+import type { ExecutionContext } from '../../base/types'
+import type { BaseIntegrationAdapter } from './base-integration-adapter'
+import type { RateLimiter, RetryPolicy } from '../../../../platform/resilience'
+import { ToolingError } from '../types'
+import { withRetry, InMemoryRateLimiter, DEFAULT_RETRY_POLICY } from '../../../../platform/resilience'
+import {
+  INTEGRATION_RATE_LIMIT_CAPACITY,
+  INTEGRATION_RATE_LIMIT_WINDOW_MS
+} from '../../../../platform/constants/resilience'
+import { getToolServices } from '../registry'
+
+/**
+ * Integration Service
+ *
+ * Central service for managing integration adapters, rate limiting, and retry.
+ * Credentials accessed via global tool services registry.
+ *
+ * Pattern: Active Record (justified - owns state + behavior)
+ *
+ * @example
+ * const service = new IntegrationService(
+ *   new Map([['gmail', gmailAdapter]])
+ * )
+ *
+ * const result = await service.call('gmail', 'sendEmail', params, 'gmail-cred', context)
+ */
+export class IntegrationService {
+  private readonly rateLimiter: RateLimiter
+  private readonly retryPolicy: RetryPolicy
+
+  constructor(public readonly adapters: Map<string, BaseIntegrationAdapter>) {
+    this.rateLimiter = new InMemoryRateLimiter(INTEGRATION_RATE_LIMIT_CAPACITY, INTEGRATION_RATE_LIMIT_WINDOW_MS)
+    this.retryPolicy = DEFAULT_RETRY_POLICY
+  }
+
+  /**
+   * Call integration method with full orchestration
+   *
+   * Orchestrates the full integration call flow:
+   * 1. Validate execution context
+   * 2. Validate adapter exists
+   * 3. Check rate limit (per organization per integration)
+   * 4. Get credentials from registry
+   * 5. Validate credentials
+   * 6. Call adapter with retry
+   *
+   * @param integration - Integration adapter type (e.g., 'gmail', 'slack')
+   * @param method - Method name (e.g., 'sendEmail', 'postMessage')
+   * @param params - Method parameters
+   * @param credentialName - Credential name from credentials table
+   * @param context - Execution context (required for multi-tenant isolation)
+   * @returns Method result
+   * @throws ToolingError if call fails
+   */
+  async call(
+    integration: string,
+    method: string,
+    params: unknown,
+    credentialName: string,
+    context: ExecutionContext | undefined
+  ): Promise<unknown> {
+    // 1. Validate execution context (required for multi-tenant isolation)
+    if (!context) {
+      throw new ToolingError('validation_error', 'ExecutionContext required for integration calls', {
+        integration,
+        method,
+        credentialName
+      })
+    }
+
+    // 2. Validate adapter exists
+    const adapter = this.adapters.get(integration)
+    if (!adapter) {
+      throw new ToolingError('adapter_not_found', `Integration adapter not found: ${integration}`, {
+        integration,
+        availableAdapters: Array.from(this.adapters.keys())
+      })
+    }
+
+    // 3. Check rate limit (per organization per integration)
+    const rateLimitKey = `${context.organizationId}:${integration}`
+    const allowed = await this.rateLimiter.allow(rateLimitKey)
+    if (!allowed) {
+      const remaining = await this.rateLimiter.remaining(rateLimitKey)
+      throw new ToolingError('rate_limit_exceeded', 'Rate limit exceeded', {
+        integration,
+        organizationId: context.organizationId,
+        remaining
+      })
+    }
+
+    // 4. Get credentials from registry
+    const { credentialsService } = getToolServices()
+    if (!credentialsService) {
+      throw new ToolingError(
+        'service_unavailable',
+        'CredentialsService not initialized. Ensure toolServicesRegistry.initialize() was called in apps/api/src/main.ts',
+        { integration, credentialName }
+      )
+    }
+
+    const credentials = await credentialsService.getCredential(context.organizationId, credentialName)
+    if (!credentials) {
+      throw new ToolingError('credentials_missing', `No credentials found for credential name: ${credentialName}`, {
+        integration,
+        credentialName,
+        organizationId: context.organizationId
+      })
+    }
+
+    // Log credential retrieval for OAuth integrations
+    const isOAuth = !!(credentials as Record<string, unknown>).provider
+    if (isOAuth) {
+      const creds = credentials as Record<string, unknown>
+      context.logger?.debug(
+        `OAuth credential retrieved: integration=${integration}, credentialName=${credentialName}, provider=${creds.provider}, hasRefreshToken=${!!creds.refreshToken}, hasExpiresAt=${!!creds.expiresAt}, expiresAt=${creds.expiresAt}`
+      )
+    }
+
+    // 5. Validate credentials
+    const isValid = adapter.validateCredentials(credentials)
+    if (!isValid) {
+      throw new ToolingError('credentials_invalid', `Invalid credentials for integration: ${integration}`, {
+        integration,
+        organizationId: context.organizationId
+      })
+    }
+
+    // 6. Call adapter with retry (pass credentialName in context for token refresh persistence)
+    const contextWithCredential: ExecutionContext = {
+      ...context,
+      credentialName
+    }
+    return withRetry(() => adapter.call(method, params, credentials, contextWithCredential), this.retryPolicy)
+  }
+
+  /**
+   * Get adapter by name
+   * @param integration - Integration name
+   * @returns Adapter or undefined
+   */
+  getAdapter(integration: string): BaseIntegrationAdapter | undefined {
+    return this.adapters.get(integration)
+  }
+
+  /**
+   * Register adapter
+   * @param adapter - Adapter to register
+   */
+  registerAdapter(adapter: BaseIntegrationAdapter): void {
+    this.adapters.set(adapter.name, adapter)
+  }
+
+  /**
+   * Unregister adapter
+   * @param integration - Integration name to unregister
+   */
+  unregisterAdapter(integration: string): void {
+    this.adapters.delete(integration)
+  }
+}