@elevasis/core 0.1.0

package/src/execution/engine/tools/integration/server/adapters/millionverifier/fetch/check-credits/index.ts

@@ -0,0 +1,59 @@
+import { ToolingError } from '../../../../../../types'
+import { withRetry, DEFAULT_RETRY_POLICY } from '../../../../../../../../../platform/resilience'
+import type { ExecutionContext } from '../../../../../../../base/types'
+import type { MillionVerifierCheckCreditsResult } from '../../../../../types/millionverifier'
+
+interface MillionVerifierCredentials {
+  apiKey: string
+}
+
+const MV_CREDITS_URL = 'https://api.millionverifier.com/api/v3/credits'
+
+/**
+ * Check remaining MillionVerifier credits
+ *
+ * @param credentials - MillionVerifier API key
+ * @param context - Execution context for logging
+ * @returns Credit balance breakdown
+ */
+export async function checkCredits(
+  credentials: MillionVerifierCredentials,
+  context?: ExecutionContext
+): Promise<MillionVerifierCheckCreditsResult> {
+  const { apiKey } = credentials
+
+  if (context?.logger) {
+    context.logger.info(
+      `[MillionVerifierAdapter] checkCredits: organizationId=${context.organizationId} executionId=${context.executionId}`
+    )
+  }
+
+  const url = new URL(MV_CREDITS_URL)
+  url.searchParams.set('api', apiKey)
+
+  const response = await withRetry(async () => {
+    const res = await fetch(url.toString(), {
+      method: 'GET',
+      signal: AbortSignal.timeout(30_000)
+    })
+
+    if (!res.ok) {
+      throw new ToolingError('api_error', `MillionVerifier credits API returned HTTP ${res.status}`, {
+        integration: 'millionverifier',
+        method: 'checkCredits',
+        organizationId: context?.organizationId
+      })
+    }
+
+    return res.json() as Promise<Record<string, unknown>>
+  }, DEFAULT_RETRY_POLICY)
+
+  const data = response as Record<string, unknown>
+
+  return {
+    credits: (data.credits as number) ?? 0,
+    bulkCredits: (data.bulk_credits as number) ?? 0,
+    renewingCredits: (data.renewing_credits as number) ?? 0,
+    plan: (data.plan as number) ?? 0
+  }
+}

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

@@ -0,0 +1,102 @@
+import { ToolingError } from '../../../../../../types'
+import { withRetry, DEFAULT_RETRY_POLICY } from '../../../../../../../../../platform/resilience'
+import type { ExecutionContext } from '../../../../../../../base/types'
+import type { MillionVerifierVerifyEmailResult } from '../../../../../types/millionverifier'
+
+interface MillionVerifierCredentials {
+  apiKey: string
+}
+
+export interface VerifyEmailParams {
+  email: string
+}
+
+const MV_API_BASE = 'https://api.millionverifier.com/api/v3/'
+
+/**
+ * Verify an email address via MillionVerifier
+ *
+ * Calls the MillionVerifier single-verification endpoint. The API always returns
+ * HTTP 200 -- errors are signalled by result === 'error' and a non-empty error field.
+ *
+ * Credits are deducted for ok/invalid/disposable results; catch_all and unknown are free.
+ *
+ * @param credentials - MillionVerifier API key
+ * @param params - Email address to verify
+ * @param context - Execution context for logging
+ * @returns Normalized verification result in camelCase
+ */
+export async function verifyEmail(
+  credentials: MillionVerifierCredentials,
+  params: VerifyEmailParams,
+  context?: ExecutionContext
+): Promise<MillionVerifierVerifyEmailResult> {
+  const { apiKey } = credentials
+  const { email } = params
+
+  if (!email) {
+    throw new ToolingError('validation_error', 'Missing required parameter: email', {
+      integration: 'millionverifier',
+      method: 'verifyEmail'
+    })
+  }
+
+  if (context?.logger) {
+    context.logger.info(
+      `[MillionVerifierAdapter] verifyEmail: email=${email} organizationId=${context.organizationId} executionId=${context.executionId}`
+    )
+  }
+
+  const url = new URL(MV_API_BASE)
+  url.searchParams.set('api', apiKey)
+  url.searchParams.set('email', email)
+
+  const response = await withRetry(async () => {
+    const res = await fetch(url.toString(), {
+      method: 'GET',
+      signal: AbortSignal.timeout(60_000)
+    })
+
+    if (!res.ok) {
+      throw new ToolingError('api_error', `MillionVerifier API returned HTTP ${res.status}`, {
+        integration: 'millionverifier',
+        method: 'verifyEmail',
+        organizationId: context?.organizationId
+      })
+    }
+
+    return res.json() as Promise<Record<string, unknown>>
+  }, DEFAULT_RETRY_POLICY)
+
+  const data = response as Record<string, unknown>
+
+  // The API signals errors via result === 'error' with a non-empty error field
+  if (data.result === 'error' && data.error) {
+    throw new ToolingError('api_error', `MillionVerifier error: ${data.error as string}`, {
+      integration: 'millionverifier',
+      method: 'verifyEmail',
+      organizationId: context?.organizationId
+    })
+  }
+
+  if (context?.logger) {
+    context.logger.info(
+      `[MillionVerifierAdapter] verifyEmail complete: email=${email} result=${data.result ?? ''} quality=${data.quality ?? ''} organizationId=${context.organizationId}`
+    )
+  }
+
+  return {
+    email: (data.email as string) ?? email,
+    quality: (data.quality as MillionVerifierVerifyEmailResult['quality']) ?? '',
+    result: (data.result as MillionVerifierVerifyEmailResult['result']) ?? 'unknown',
+    resultCode: (data.resultcode as MillionVerifierVerifyEmailResult['resultCode']) ?? 3,
+    subresult: (data.subresult as string) ?? '',
+    free: (data.free as boolean) ?? false,
+    role: (data.role as boolean) ?? false,
+    didYouMean: (data.didyoumean as string) ?? '',
+    credits: (data.credits as number) ?? 0,
+    executionTime: (data.executiontime as number) ?? 0,
+    error: (data.error as string) ?? '',
+    liveMode: (data.livemode as boolean) ?? false
+  }
+}

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

@@ -0,0 +1,17 @@
+/**
+ * MillionVerifier Integration - Barrel Export
+ *
+ * Exports MillionVerifier adapter and tool factory functions.
+ */
+
+// ============================================================================
+// MILLIONVERIFIER ADAPTER
+// ============================================================================
+
+export { MillionVerifierAdapter } from './millionverifier-adapter'
+
+// ============================================================================
+// MILLIONVERIFIER TOOLS
+// ============================================================================
+
+export { createMillionVerifierVerifyEmailTool, createMillionVerifierCheckCreditsTool } from './millionverifier-tools'

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

@@ -0,0 +1,80 @@
+import type { BaseIntegrationAdapter } from '../../../base-integration-adapter'
+import { ToolingError } from '../../../../types'
+import type { ExecutionContext } from '../../../../../base/types'
+import { verifyEmail } from './fetch/verify-email/index'
+import type { VerifyEmailParams } from './fetch/verify-email/index'
+import { checkCredits } from './fetch/check-credits/index'
+
+/**
+ * MillionVerifier credentials format
+ * Stored in credentials table, encrypted
+ */
+interface MillionVerifierCredentials {
+  apiKey: string
+}
+
+/**
+ * MillionVerifier integration adapter
+ *
+ * Provides access to the MillionVerifier email verification API for validating
+ * email deliverability before campaigns. Uses API key as a query parameter.
+ *
+ * Credits are deducted for ok/invalid/disposable results; catch_all and unknown are free.
+ *
+ * @example
+ * ```typescript
+ * const adapter = new MillionVerifierAdapter()
+ * const result = await adapter.call(
+ *   'verifyEmail',
+ *   { email: 'john@example.com' },
+ *   { apiKey: 'your-api-key' },
+ *   context
+ * )
+ * ```
+ */
+export class MillionVerifierAdapter implements BaseIntegrationAdapter {
+  readonly name = 'millionverifier'
+
+  /**
+   * Call MillionVerifier API method
+   */
+  async call(
+    method: string,
+    params: unknown,
+    credentials: Record<string, unknown>,
+    context?: ExecutionContext
+  ): Promise<unknown> {
+    // Validate credentials first
+    if (!this.validateCredentials(credentials)) {
+      throw new ToolingError('credentials_invalid', 'Invalid MillionVerifier credentials', {
+        integration: this.name,
+        organizationId: context?.organizationId
+      })
+    }
+
+    // Safe to cast after validation confirms apiKey exists and is valid
+    const creds = credentials as unknown as MillionVerifierCredentials
+
+    // Route to method handler - delegate to fetch functions
+    switch (method) {
+      case 'verifyEmail':
+        return verifyEmail(creds, params as VerifyEmailParams, context)
+      case 'checkCredits':
+        return checkCredits(creds, context)
+      default:
+        throw new ToolingError('method_not_found', `Unknown MillionVerifier method: ${method}`, {
+          integration: this.name,
+          method,
+          organizationId: context?.organizationId
+        })
+    }
+  }
+
+  /**
+   * Validate MillionVerifier credentials
+   */
+  validateCredentials(credentials: Record<string, unknown>): boolean {
+    const creds = credentials as unknown as MillionVerifierCredentials
+    return !!creds.apiKey && typeof creds.apiKey === 'string' && creds.apiKey.length > 0
+  }
+}

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

@@ -0,0 +1,102 @@
+import { z } from 'zod'
+import type { Tool } from '../../../../types'
+import { createIntegrationTool } from '../../../tool'
+
+/**
+ * Create a tool that verifies email addresses via MillionVerifier
+ *
+ * @param credentialName - Name of the MillionVerifier credential to use
+ * @returns Tool instance
+ *
+ * @example
+ * ```typescript
+ * const tool = createMillionVerifierVerifyEmailTool('elevasis-millionverifier')
+ * const result = await tool.execute({
+ *   email: 'john@example.com'
+ * }, context)
+ * // result.result: 'ok' | 'catch_all' | 'unknown' | 'error' | 'disposable' | 'invalid'
+ * // result.quality: 'good' | 'bad' | 'risky' | ''
+ * ```
+ */
+export function createMillionVerifierVerifyEmailTool(credentialName: string): Tool {
+  return createIntegrationTool({
+    name: 'millionverifier_verify_email',
+    description: `Verify email address deliverability using MillionVerifier.
+
+Use this tool to validate if an email address is real and can receive emails before
+adding it to a campaign. MillionVerifier is highly accurate and fast (160 req/s).
+
+Result codes:
+- ok (1): Email is valid and deliverable
+- catch_all (2): Domain accepts all email (cannot confirm individual mailbox) - FREE
+- unknown (3): Result could not be determined - FREE
+- error (4): Verification error
+- disposable (5): Disposable/temporary email address
+- invalid (6): Email address is invalid
+
+Quality signals:
+- good: Safe to send
+- risky: May bounce or flag spam filter
+- bad: Do not send
+
+Credits are only deducted for ok, invalid, and disposable results.
+
+Returns full verification details including free/role detection and suggested correction.`,
+    inputSchema: z.object({
+      email: z.string().email().describe('Email address to verify')
+    }),
+    outputSchema: z.object({
+      email: z.string().describe('Verified email address'),
+      quality: z.enum(['', 'good', 'bad', 'risky']).describe('Quality signal for sending decision'),
+      result: z.enum(['ok', 'catch_all', 'unknown', 'error', 'disposable', 'invalid']).describe('Verification result'),
+      resultCode: z
+        .number()
+        .describe('Numeric result code (1=ok, 2=catch_all, 3=unknown, 4=error, 5=disposable, 6=invalid)'),
+      subresult: z.string().describe('Detailed sub-result (e.g., ok, no_mailbox, dns_no_mx)'),
+      free: z.boolean().describe('Whether this is a free email provider (Gmail, Yahoo, etc.)'),
+      role: z.boolean().describe('Whether this is a role-based address (info@, support@, etc.)'),
+      didYouMean: z.string().describe('Suggested correction if email looks like a typo (empty if none)'),
+      credits: z.number().describe('Remaining credits after this verification'),
+      executionTime: z.number().describe('Time taken to verify in milliseconds'),
+      error: z.string().describe('Error message when result is error (empty otherwise)'),
+      liveMode: z.boolean().describe('Whether the verification was performed in live mode')
+    }),
+    integration: 'millionverifier' as const,
+    method: 'verifyEmail' as const,
+    credentialName
+  })
+}
+
+/**
+ * Create a tool that checks remaining MillionVerifier credits
+ *
+ * @param credentialName - Name of the MillionVerifier credential to use
+ * @returns Tool instance
+ *
+ * @example
+ * ```typescript
+ * const tool = createMillionVerifierCheckCreditsTool('elevasis-millionverifier')
+ * const result = await tool.execute({}, context)
+ * // result.credits: 5000
+ * ```
+ */
+export function createMillionVerifierCheckCreditsTool(credentialName: string): Tool {
+  return createIntegrationTool({
+    name: 'millionverifier_check_credits',
+    description: `Check remaining MillionVerifier verification credits.
+
+Use this tool to monitor credit balance before running large verification batches.
+
+Returns current credits, bulk credits, renewing credits, and plan tier.`,
+    inputSchema: z.object({}),
+    outputSchema: z.object({
+      credits: z.number().describe('Remaining single-verification credits'),
+      bulkCredits: z.number().describe('Remaining bulk verification credits'),
+      renewingCredits: z.number().describe('Credits that will renew on next billing cycle'),
+      plan: z.number().describe('Current plan tier')
+    }),
+    integration: 'millionverifier' as const,
+    method: 'checkCredits' as const,
+    credentialName
+  })
+}

package/src/execution/engine/tools/integration/server/adapters/resend/fetch/get-email/index.ts

@@ -0,0 +1,102 @@
+import { ToolingError } from '../../../../../../types'
+import type { ExecutionContext } from '../../../../../../../base/types'
+import { withRetry, createHttpError, DEFAULT_RETRY_POLICY } from '../../../../../../../../../platform/resilience'
+import type { ResendCredentials, GetEmailParams, GetEmailResult, ResendGetEmailResponse } from '../utils/types'
+
+/**
+ * Get email status from Resend API
+ *
+ * @param credentials - Resend API credentials (apiKey)
+ * @param params - Email ID to retrieve
+ * @param context - Execution context for logging
+ * @returns Email details including delivery status
+ * @throws ToolingError if retrieval fails
+ *
+ * @example
+ * const result = await getEmail(
+ *   { apiKey: 're_xxx' },
+ *   { emailId: '49a3999c-0ce1-4ea6-ab68-afcd6dc2e794' },
+ *   context
+ * )
+ * // result.lastEvent: 'sent', 'delivered', 'bounced', 'complained', 'failed'
+ */
+export async function getEmail(
+  credentials: ResendCredentials,
+  params: GetEmailParams,
+  context?: ExecutionContext
+): Promise<GetEmailResult> {
+  const { apiKey } = credentials
+  const { emailId } = params
+
+  // Validate required parameters
+  if (!apiKey) {
+    throw new ToolingError('credentials_invalid', 'Resend API credentials must include apiKey', {
+      integration: 'resend',
+      method: 'getEmail'
+    })
+  }
+
+  if (!emailId) {
+    throw new ToolingError('validation_error', 'Email ID is required', { integration: 'resend', method: 'getEmail' })
+  }
+
+  // Build URL
+  const url = `https://api.resend.com/emails/${encodeURIComponent(emailId)}`
+
+  try {
+    // Execute with retry logic
+    const response = await withRetry(async () => {
+      const res = await fetch(url, {
+        method: 'GET',
+        headers: {
+          Authorization: `Bearer ${apiKey}`
+        }
+      })
+
+      // Handle HTTP errors
+      if (!res.ok) {
+        throw await createHttpError(res, {
+          integration: 'resend',
+          method: 'getEmail',
+          organizationId: context?.organizationId
+        })
+      }
+
+      return res
+    }, DEFAULT_RETRY_POLICY)
+
+    // Parse response
+    const result = (await response.json()) as ResendGetEmailResponse
+
+    // Log success
+    if (context?.logger) {
+      context.logger.info(
+        `[ResendAdapter] Email retrieved: organizationId=${context.organizationId} executionId=${context.executionId} emailId=${result.id} lastEvent=${result.last_event}`
+      )
+    }
+
+    // Return standardized result (camelCase)
+    return {
+      id: result.id,
+      to: result.to,
+      from: result.from,
+      subject: result.subject,
+      lastEvent: result.last_event,
+      createdAt: result.created_at
+    }
+  } catch (error) {
+    // Re-throw ToolingError as-is
+    if (error instanceof ToolingError) {
+      throw error
+    }
+
+    // Wrap unknown errors
+    throw new ToolingError('api_error', `Failed to get email from Resend: ${(error as Error).message}`, {
+      integration: 'resend',
+      method: 'getEmail',
+      organizationId: context?.organizationId,
+      emailId,
+      originalError: error
+    })
+  }
+}

package/src/execution/engine/tools/integration/server/adapters/resend/fetch/send-email/index.ts

@@ -0,0 +1,134 @@
+import { ToolingError } from '../../../../../../types'
+import type { ExecutionContext } from '../../../../../../../base/types'
+import { withRetry, createHttpError, DEFAULT_RETRY_POLICY } from '../../../../../../../../../platform/resilience'
+import type { ResendCredentials, SendEmailParams, SendEmailResult, ResendSendEmailResponse } from '../utils/types'
+
+/**
+ * Send an email using Resend API
+ *
+ * @param credentials - Resend API credentials (apiKey)
+ * @param params - Email parameters (from, to, subject, html/text, etc.)
+ * @param context - Execution context for logging
+ * @returns Email ID and success status
+ * @throws ToolingError if email sending fails
+ *
+ * @example
+ * // Send a simple email
+ * const result = await sendEmail(
+ *   { apiKey: 're_xxx' },
+ *   {
+ *     from: 'Alex <alexl@elevasis.io>',
+ *     to: 'john@example.com',
+ *     subject: 'Discovery Call Reminder',
+ *     html: '<p>Your call is tomorrow...</p>',
+ *     headers: {
+ *       'List-Unsubscribe': '<https://elevasis.io/api/unsubscribe?email=...>',
+ *       'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click'
+ *     }
+ *   },
+ *   context
+ * )
+ */
+export async function sendEmail(
+  credentials: ResendCredentials,
+  params: SendEmailParams,
+  context?: ExecutionContext
+): Promise<SendEmailResult> {
+  const { apiKey } = credentials
+  const { from, to, subject, html, text, replyTo, cc, bcc, headers, tags } = params
+
+  // Validate required parameters
+  if (!apiKey) {
+    throw new ToolingError('credentials_invalid', 'Resend API credentials must include apiKey', {
+      integration: 'resend',
+      method: 'sendEmail'
+    })
+  }
+
+  if (!from || !to || !subject) {
+    throw new ToolingError('validation_error', 'From, to, and subject are required', {
+      integration: 'resend',
+      method: 'sendEmail',
+      params: { from, to, subject }
+    })
+  }
+
+  if (!html && !text) {
+    throw new ToolingError('validation_error', 'Either html or text content is required', {
+      integration: 'resend',
+      method: 'sendEmail'
+    })
+  }
+
+  // Build URL
+  const url = 'https://api.resend.com/emails'
+
+  // Build request body
+  const requestBody: Record<string, unknown> = {
+    from,
+    to: Array.isArray(to) ? to : [to],
+    subject
+  }
+
+  if (html) requestBody.html = html
+  if (text) requestBody.text = text
+  if (replyTo) requestBody.reply_to = replyTo
+  if (cc) requestBody.cc = Array.isArray(cc) ? cc : [cc]
+  if (bcc) requestBody.bcc = Array.isArray(bcc) ? bcc : [bcc]
+  if (headers) requestBody.headers = headers
+  if (tags) requestBody.tags = tags
+
+  try {
+    // Execute with retry logic
+    const response = await withRetry(async () => {
+      const res = await fetch(url, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(requestBody)
+      })
+
+      // Handle HTTP errors
+      if (!res.ok) {
+        throw await createHttpError(res, {
+          integration: 'resend',
+          method: 'sendEmail',
+          organizationId: context?.organizationId
+        })
+      }
+
+      return res
+    }, DEFAULT_RETRY_POLICY)
+
+    // Parse response
+    const result = (await response.json()) as ResendSendEmailResponse
+
+    // Log success
+    if (context?.logger) {
+      context.logger.info(
+        `[ResendAdapter] Email sent: organizationId=${context.organizationId} executionId=${context.executionId} emailId=${result.id} to=${Array.isArray(to) ? to.join(',') : to}`
+      )
+    }
+
+    // Return standardized result
+    return {
+      id: result.id,
+      success: true
+    }
+  } catch (error) {
+    // Re-throw ToolingError as-is
+    if (error instanceof ToolingError) {
+      throw error
+    }
+
+    // Wrap unknown errors
+    throw new ToolingError('api_error', `Failed to send email via Resend: ${(error as Error).message}`, {
+      integration: 'resend',
+      method: 'sendEmail',
+      organizationId: context?.organizationId,
+      originalError: error
+    })
+  }
+}

package/src/execution/engine/tools/integration/server/adapters/resend/fetch/utils/types.ts

@@ -0,0 +1,75 @@
+/**
+ * Resend API Types
+ *
+ * Type definitions for Resend email API operations.
+ */
+
+/**
+ * Resend credentials format
+ * Stored in credentials table, encrypted
+ */
+export interface ResendCredentials {
+  apiKey: string // API key (re_xxxxxxxxx)
+}
+
+/**
+ * Send email parameters
+ */
+export interface SendEmailParams {
+  from: string // "Name <sender@domain.com>"
+  to: string | string[] // Recipients (max 50)
+  subject: string // Email subject
+  html?: string // HTML content
+  text?: string // Plain text (auto-generated from HTML if omitted)
+  replyTo?: string | string[] // Reply-to address
+  cc?: string | string[] // CC recipients
+  bcc?: string | string[] // BCC recipients
+  headers?: Record<string, string> // Custom headers (for unsubscribe)
+  tags?: Array<{ name: string; value: string }> // Key-value metadata
+}
+
+/**
+ * Send email result
+ */
+export interface SendEmailResult {
+  id: string // Email ID
+  success: boolean
+}
+
+/**
+ * Get email parameters
+ */
+export interface GetEmailParams {
+  emailId: string // Email ID to retrieve
+}
+
+/**
+ * Get email result
+ */
+export interface GetEmailResult {
+  id: string
+  to: string[]
+  from: string
+  subject: string
+  lastEvent: string // 'sent', 'delivered', 'bounced', 'complained', 'failed'
+  createdAt: string
+}
+
+/**
+ * Resend API response for send email
+ */
+export interface ResendSendEmailResponse {
+  id: string
+}
+
+/**
+ * Resend API response for get email
+ */
+export interface ResendGetEmailResponse {
+  id: string
+  to: string[]
+  from: string
+  subject: string
+  last_event: string
+  created_at: string
+}