chore: import upstream snapshot with attribution

apps/sim/tools/enrow/find_email.ts

@@ -0,0 +1,193 @@
+import { sleep } from '@sim/utils/helpers'
+import { enrowHosting } from '@/tools/enrow/hosting'
+import type {
+  EnrowFindEmailParams,
+  EnrowFindEmailResponse,
+  EnrowFindEmailResult,
+} from '@/tools/enrow/types'
+import {
+  ENROW_EMAIL_OUTPUT,
+  ENROW_ID_OUTPUT,
+  ENROW_QUALIFICATION_OUTPUT,
+} from '@/tools/enrow/types'
+import type { ToolConfig } from '@/tools/types'
+
+const POLL_INTERVAL_MS = 3000
+const MAX_POLL_TIME_MS = 120_000
+
+/** Map a raw Enrow find-email result payload to the typed output shape. */
+function mapFindResult(data: Record<string, unknown>): EnrowFindEmailResult {
+  return {
+    id: (data.id as string) ?? '',
+    email: (data.email as string) ?? null,
+    qualification: (data.qualification as string) ?? null,
+    fullname: (data.fullname as string) ?? null,
+    company_name: (data.company_name as string) ?? null,
+    company_domain: (data.company_domain as string) ?? null,
+    linkedin_url: (data.linkedin_url as string) ?? null,
+  }
+}
+
+/**
+ * Enrow — Find Email (single, async).
+ *
+ * Submits a search via `POST https://api.enrow.io/email/find/single`, receives
+ * a job `id`, then polls `GET https://api.enrow.io/email/find/single?id=<id>`
+ * until HTTP 200 (complete) or the polling window expires. HTTP 202 means the
+ * search is still in progress.
+ *
+ * Pricing: 1 credit per valid email found (charged only on success).
+ * Docs: https://enrow.readme.io/reference/find-single-email
+ */
+export const enrowFindEmailTool: ToolConfig<EnrowFindEmailParams, EnrowFindEmailResponse> = {
+  id: 'enrow_find_email',
+  name: 'Enrow Find Email',
+  description:
+    'Find a verified B2B email address from a full name and company domain or name. Uses the Enrow async finder — submits a search and polls until the result is ready. Costs 1 credit per valid email found. (https://enrow.readme.io/reference/find-single-email)',
+  version: '1.0.0',
+
+  hosting: enrowHosting<EnrowFindEmailParams>((_params, output) => {
+    // 1 credit charged only when a valid email is returned. Compare
+    // case-insensitively so the API's qualifier casing can't zero out billing.
+    return String(output.qualification ?? '').toLowerCase() === 'valid' ? 1 : 0
+  }),
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Enrow API key',
+    },
+    fullname: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Full name of the person (e.g. "John Doe")',
+    },
+    company_domain: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Company domain (e.g. "apple.com"). Preferred over company_name.',
+    },
+    company_name: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Company name (e.g. "Apple"). Used when domain is unavailable.',
+    },
+  },
+
+  request: {
+    url: 'https://api.enrow.io/email/find/single',
+    method: 'POST',
+    headers: (params: EnrowFindEmailParams) => ({
+      'x-api-key': params.apiKey,
+      'Content-Type': 'application/json',
+    }),
+    body: (params: EnrowFindEmailParams) => {
+      const body: Record<string, unknown> = { fullname: params.fullname }
+      if (params.company_domain) body.company_domain = params.company_domain
+      if (params.company_name) body.company_name = params.company_name
+      return body
+    },
+  },
+
+  transformResponse: async (response: Response): Promise<EnrowFindEmailResponse> => {
+    if (!response.ok) {
+      const errorText = await response.text()
+      throw new Error(`Enrow API error: ${response.status} - ${errorText}`)
+    }
+    const json = await response.json()
+    const id = (json.id as string) ?? null
+    if (!id) {
+      throw new Error('Enrow find-email did not return a job id')
+    }
+    return {
+      success: true,
+      output: {
+        id,
+        email: null,
+        qualification: null,
+        fullname: null,
+        company_name: null,
+        company_domain: null,
+        linkedin_url: null,
+      },
+    }
+  },
+
+  postProcess: async (
+    result: EnrowFindEmailResponse,
+    params: EnrowFindEmailParams
+  ): Promise<EnrowFindEmailResponse> => {
+    if (!result.success) return result
+
+    const jobId = result.output.id
+    if (!jobId) {
+      throw new Error('Enrow find-email did not return a job id to poll')
+    }
+
+    let elapsed = 0
+    while (elapsed < MAX_POLL_TIME_MS) {
+      await sleep(POLL_INTERVAL_MS)
+      elapsed += POLL_INTERVAL_MS
+
+      const pollResponse = await fetch(
+        `https://api.enrow.io/email/find/single?id=${encodeURIComponent(jobId)}`,
+        {
+          headers: {
+            'x-api-key': params.apiKey,
+          },
+        }
+      )
+
+      if (pollResponse.status === 202) {
+        // Still in progress — keep polling
+        continue
+      }
+
+      if (!pollResponse.ok) {
+        const errorText = await pollResponse.text()
+        throw new Error(`Enrow find-email poll error: ${pollResponse.status} - ${errorText}`)
+      }
+
+      // HTTP 200 → complete
+      const json = await pollResponse.json()
+      const data = (json as Record<string, unknown>) ?? {}
+      return {
+        success: true,
+        output: mapFindResult({ ...data, id: jobId }),
+      }
+    }
+
+    throw new Error('Enrow find-email did not complete within the polling window')
+  },
+
+  outputs: {
+    id: ENROW_ID_OUTPUT,
+    email: ENROW_EMAIL_OUTPUT,
+    qualification: ENROW_QUALIFICATION_OUTPUT,
+    fullname: {
+      type: 'string',
+      description: 'Full name of the person searched',
+      optional: true,
+    },
+    company_name: {
+      type: 'string',
+      description: 'Company name associated with the result',
+      optional: true,
+    },
+    company_domain: {
+      type: 'string',
+      description: 'Company domain associated with the result',
+      optional: true,
+    },
+    linkedin_url: {
+      type: 'string',
+      description: 'LinkedIn profile URL of the person',
+      optional: true,
+    },
+  },
+}

apps/sim/tools/enrow/hosting.ts

@@ -0,0 +1,44 @@
+import type { ToolHostingConfig } from '@/tools/types'
+
+/**
+ * Env var prefix for Enrow hosted keys. Provide keys as `ENROW_API_KEY_COUNT`
+ * plus `ENROW_API_KEY_1..N`.
+ */
+export const ENROW_API_KEY_PREFIX = 'ENROW_API_KEY'
+
+/**
+ * Dollar cost of a single Enrow credit.
+ *
+ * Enrow's Starter plan is $24/month for 2,000 finder credits/month — $0.012
+ * per credit. The email verifier costs 0.25 credits per verification and the
+ * email finder costs 1 credit per valid result.
+ * Source: https://enrow.io/pricing
+ */
+export const ENROW_CREDIT_USD = 0.012
+
+/**
+ * Build an Enrow `hosting` config. `getCredits` returns the number of Enrow
+ * credits consumed by the call, derived from the tool's final output.
+ */
+export function enrowHosting<P>(
+  getCredits: (params: P, output: Record<string, unknown>) => number
+): ToolHostingConfig<P> {
+  return {
+    envKeyPrefix: ENROW_API_KEY_PREFIX,
+    apiKeyParam: 'apiKey',
+    byokProviderId: 'enrow',
+    pricing: {
+      type: 'custom',
+      getCost: (params, output) => {
+        const credits = getCredits(params, output)
+        return { cost: credits * ENROW_CREDIT_USD, metadata: { credits } }
+      },
+    },
+    rateLimit: {
+      mode: 'per_request',
+      // Enrow rate limit is ~50 req/s; cap at 60 req/min to stay conservative
+      // and avoid bursting into the limit during polling.
+      requestsPerMinute: 60,
+    },
+  }
+}

apps/sim/tools/enrow/index.ts

@@ -0,0 +1,6 @@
+export * from './types'
+
+import { enrowFindEmailTool } from '@/tools/enrow/find_email'
+import { enrowVerifyEmailTool } from '@/tools/enrow/verify_email'
+
+export { enrowFindEmailTool, enrowVerifyEmailTool }

apps/sim/tools/enrow/types.ts

@@ -0,0 +1,82 @@
+import type { OutputProperty, ToolResponse } from '@/tools/types'
+
+/** Common params shared by all Enrow tool operations. */
+export interface EnrowBaseParams {
+  apiKey: string
+}
+
+// ---------------------------------------------------------------------------
+// Email Finder — single
+// ---------------------------------------------------------------------------
+
+export interface EnrowFindEmailParams extends EnrowBaseParams {
+  fullname: string
+  company_domain?: string
+  company_name?: string
+}
+
+export interface EnrowFindEmailResult {
+  /** Job ID returned by the submit call; used to poll for the result. */
+  id: string
+  email: string | null
+  /** Enrow quality qualifier: "valid" | "invalid" | null (if not yet finished). */
+  qualification: string | null
+  fullname: string | null
+  company_name: string | null
+  company_domain: string | null
+  linkedin_url: string | null
+}
+
+export interface EnrowFindEmailResponse extends ToolResponse {
+  output: EnrowFindEmailResult
+}
+
+// ---------------------------------------------------------------------------
+// Email Verifier — single
+// ---------------------------------------------------------------------------
+
+export interface EnrowVerifyEmailParams extends EnrowBaseParams {
+  email: string
+}
+
+export interface EnrowVerifyEmailResult {
+  /** Job ID returned by the submit call; used to poll for the result. */
+  id: string
+  email: string | null
+  /** Enrow quality qualifier: "valid" | "invalid" | null (if not yet finished). */
+  qualification: string | null
+}
+
+export interface EnrowVerifyEmailResponse extends ToolResponse {
+  output: EnrowVerifyEmailResult
+}
+
+// ---------------------------------------------------------------------------
+// Union response type (used in BlockConfig generic)
+// ---------------------------------------------------------------------------
+
+export type EnrowResponse = EnrowFindEmailResponse | EnrowVerifyEmailResponse
+
+// ---------------------------------------------------------------------------
+// Shared output property constants
+// ---------------------------------------------------------------------------
+
+/** Reusable output-property definition for the Enrow job ID. */
+export const ENROW_ID_OUTPUT: OutputProperty = {
+  type: 'string',
+  description: 'Enrow job identifier used for polling',
+}
+
+/** Reusable output-property definition for the returned email address. */
+export const ENROW_EMAIL_OUTPUT: OutputProperty = {
+  type: 'string',
+  description: 'Email address found or verified',
+  optional: true,
+}
+
+/** Reusable output-property definition for the qualification field. */
+export const ENROW_QUALIFICATION_OUTPUT: OutputProperty = {
+  type: 'string',
+  description: 'Enrow quality result: "valid" or "invalid"',
+  optional: true,
+}

apps/sim/tools/enrow/verify_email.ts

@@ -0,0 +1,151 @@
+import { sleep } from '@sim/utils/helpers'
+import { enrowHosting } from '@/tools/enrow/hosting'
+import type {
+  EnrowVerifyEmailParams,
+  EnrowVerifyEmailResponse,
+  EnrowVerifyEmailResult,
+} from '@/tools/enrow/types'
+import {
+  ENROW_EMAIL_OUTPUT,
+  ENROW_ID_OUTPUT,
+  ENROW_QUALIFICATION_OUTPUT,
+} from '@/tools/enrow/types'
+import type { ToolConfig } from '@/tools/types'
+
+const POLL_INTERVAL_MS = 3000
+const MAX_POLL_TIME_MS = 120_000
+
+/** Map a raw Enrow verify-email result payload to the typed output shape. */
+function mapVerifyResult(data: Record<string, unknown>, jobId: string): EnrowVerifyEmailResult {
+  return {
+    id: jobId,
+    email: (data.email as string) ?? null,
+    qualification: (data.qualification as string) ?? null,
+  }
+}
+
+/**
+ * Enrow — Verify Email (single, async).
+ *
+ * Submits a verification via `POST https://api.enrow.io/email/verify/single`,
+ * receives a job `id`, then polls
+ * `GET https://api.enrow.io/email/verify/single?id=<id>` until HTTP 200
+ * (complete) or the polling window expires. HTTP 202 means still in progress.
+ *
+ * Pricing: 0.25 credits per verification (charged per call).
+ * Docs: https://enrow.readme.io/reference/verify-single-email
+ */
+export const enrowVerifyEmailTool: ToolConfig<EnrowVerifyEmailParams, EnrowVerifyEmailResponse> = {
+  id: 'enrow_verify_email',
+  name: 'Enrow Verify Email',
+  description:
+    'Verify the deliverability of an email address using the Enrow async verifier. Submits a verification request and polls until the result is ready. Costs 0.25 credits per verification. (https://enrow.readme.io/reference/verify-single-email)',
+  version: '1.0.0',
+
+  hosting: enrowHosting<EnrowVerifyEmailParams>((_params, output) => {
+    // 0.25 credits per completed verification. Bill only when the job resolved
+    // to a qualification — a fall-back to the initial submit response (poll never
+    // finished) has no qualification and must not be charged.
+    return output.qualification ? 0.25 : 0
+  }),
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Enrow API key',
+    },
+    email: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Email address to verify (e.g. "john@example.com")',
+    },
+  },
+
+  request: {
+    url: 'https://api.enrow.io/email/verify/single',
+    method: 'POST',
+    headers: (params: EnrowVerifyEmailParams) => ({
+      'x-api-key': params.apiKey,
+      'Content-Type': 'application/json',
+    }),
+    body: (params: EnrowVerifyEmailParams) => ({
+      email: params.email,
+    }),
+  },
+
+  transformResponse: async (response: Response): Promise<EnrowVerifyEmailResponse> => {
+    if (!response.ok) {
+      const errorText = await response.text()
+      throw new Error(`Enrow API error: ${response.status} - ${errorText}`)
+    }
+    const json = await response.json()
+    const id = (json.id as string) ?? null
+    if (!id) {
+      throw new Error('Enrow verify-email did not return a job id')
+    }
+    return {
+      success: true,
+      output: {
+        id,
+        email: null,
+        qualification: null,
+      },
+    }
+  },
+
+  postProcess: async (
+    result: EnrowVerifyEmailResponse,
+    params: EnrowVerifyEmailParams
+  ): Promise<EnrowVerifyEmailResponse> => {
+    if (!result.success) return result
+
+    const jobId = result.output.id
+    if (!jobId) {
+      throw new Error('Enrow verify-email did not return a job id to poll')
+    }
+
+    let elapsed = 0
+    while (elapsed < MAX_POLL_TIME_MS) {
+      await sleep(POLL_INTERVAL_MS)
+      elapsed += POLL_INTERVAL_MS
+
+      const pollResponse = await fetch(
+        `https://api.enrow.io/email/verify/single?id=${encodeURIComponent(jobId)}`,
+        {
+          headers: {
+            'x-api-key': params.apiKey,
+          },
+        }
+      )
+
+      if (pollResponse.status === 202) {
+        // Still in progress — keep polling
+        continue
+      }
+
+      if (!pollResponse.ok) {
+        const errorText = await pollResponse.text()
+        throw new Error(`Enrow verify-email poll error: ${pollResponse.status} - ${errorText}`)
+      }
+
+      // HTTP 200 → complete
+      const json = await pollResponse.json()
+      const data = (json as Record<string, unknown>) ?? {}
+      return {
+        success: true,
+        output: mapVerifyResult(data, jobId),
+      }
+    }
+
+    throw new Error('Enrow verify-email did not complete within the polling window')
+  },
+
+  outputs: {
+    id: ENROW_ID_OUTPUT,
+    email: ENROW_EMAIL_OUTPUT,
+    qualification: ENROW_QUALIFICATION_OUTPUT,
+  },
+}