chore: import upstream snapshot with attribution

apps/sim/tools/icypeas/find_email.ts

@@ -0,0 +1,195 @@
+import { sleep } from '@sim/utils/helpers'
+import { icypeasHosting } from '@/tools/icypeas/hosting'
+import type {
+  IcypeasFindEmailOutput,
+  IcypeasFindEmailParams,
+  IcypeasFindEmailResponse,
+} from '@/tools/icypeas/types'
+import {
+  ICYPEAS_EMAIL_OUTPUT,
+  ICYPEAS_ITEM_OUTPUT,
+  ICYPEAS_SEARCH_ID_OUTPUT,
+  ICYPEAS_STATUS_OUTPUT,
+} from '@/tools/icypeas/types'
+import type { ToolConfig } from '@/tools/types'
+
+/** Icypeas statuses that indicate the search has finished (success or failure). */
+const TERMINAL_STATUSES = new Set([
+  'FOUND',
+  'DEBITED',
+  'NOT_FOUND',
+  'DEBITED_NOT_FOUND',
+  'BAD_INPUT',
+  'INSUFFICIENT_FUNDS',
+  'ABORTED',
+])
+
+/** Icypeas statuses that indicate a result was actually found. */
+const FOUND_STATUSES = new Set(['FOUND', 'DEBITED'])
+
+const POLL_INTERVAL_MS = 3000
+const MAX_POLL_TIME_MS = 120000
+
+/** Map a raw Icypeas item object to the tool output shape. */
+function mapItem(item: Record<string, unknown>): IcypeasFindEmailOutput {
+  const status = (item.status as string | undefined) ?? null
+  // Results are nested under item.results; emails are in item.results.emails[0].email
+  const results = (item.results as Record<string, unknown> | undefined) ?? {}
+  const emails = Array.isArray(results.emails) ? (results.emails as Record<string, unknown>[]) : []
+  const email = (emails[0]?.email as string | undefined) ?? null
+  const firstname = (results.firstname as string | undefined) ?? null
+  const lastname = (results.lastname as string | undefined) ?? null
+  return {
+    searchId: (item._id as string | undefined) ?? null,
+    status,
+    email,
+    firstname,
+    lastname,
+    item,
+  }
+}
+
+export const icypeasFindEmailTool: ToolConfig<IcypeasFindEmailParams, IcypeasFindEmailResponse> = {
+  id: 'icypeas_find_email',
+  name: 'Icypeas Find Email',
+  description:
+    'Find a professional email address from a first name, last name, and company domain or name. Submits the search and polls until a result is available. Costs 1 credit per found email (https://www.icypeas.com/pricing).',
+  version: '1.0.0',
+
+  hosting: icypeasHosting<IcypeasFindEmailParams>((_params, output) => {
+    const status = output.status as string | undefined
+    // 1 credit charged only when a result is found (FOUND / DEBITED status).
+    return status && FOUND_STATUSES.has(status) ? 1 : 0
+  }),
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Icypeas API key',
+    },
+    firstname: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: "Target person's first name",
+    },
+    lastname: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: "Target person's last name",
+    },
+    domainOrCompany: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Target company domain (e.g. stripe.com) or company name (e.g. Stripe)',
+    },
+  },
+
+  request: {
+    url: 'https://app.icypeas.com/api/email-search',
+    method: 'POST',
+    headers: (params: IcypeasFindEmailParams) => ({
+      Authorization: params.apiKey,
+      'Content-Type': 'application/json',
+    }),
+    body: (params: IcypeasFindEmailParams) => {
+      const body: Record<string, unknown> = {
+        domainOrCompany: params.domainOrCompany,
+      }
+      if (params.firstname) body.firstname = params.firstname
+      if (params.lastname) body.lastname = params.lastname
+      return body
+    },
+  },
+
+  transformResponse: async (response: Response) => {
+    if (!response.ok) {
+      const errorText = await response.text()
+      throw new Error(`Icypeas API error: ${response.status} - ${errorText}`)
+    }
+    const json = (await response.json()) as Record<string, unknown>
+    // Submit response: { success: true, item: { _id: '...', status: 'NONE', ... } }
+    const item = (json.item as Record<string, unknown> | undefined) ?? {}
+    const searchId = (item._id as string | undefined) ?? null
+    if (!searchId) {
+      throw new Error('Icypeas email-search did not return an item _id')
+    }
+    return {
+      success: true,
+      output: mapItem(item),
+    }
+  },
+
+  postProcess: async (result, params) => {
+    if (!result.success) return result
+
+    const searchId = result.output.searchId
+    if (!searchId) {
+      throw new Error('Icypeas find-email result is missing a searchId')
+    }
+
+    // If already terminal (unlikely on submit but defensive), return immediately.
+    if (result.output.status && TERMINAL_STATUSES.has(result.output.status)) {
+      return result
+    }
+
+    let elapsed = 0
+    while (elapsed < MAX_POLL_TIME_MS) {
+      await sleep(POLL_INTERVAL_MS)
+      elapsed += POLL_INTERVAL_MS
+
+      const pollResponse = await fetch('https://app.icypeas.com/api/bulk-single-searchs/read', {
+        method: 'POST',
+        headers: {
+          Authorization: params.apiKey,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ id: searchId }),
+      })
+
+      if (!pollResponse.ok) {
+        const errorText = await pollResponse.text()
+        throw new Error(`Icypeas poll error: ${pollResponse.status} - ${errorText}`)
+      }
+
+      const json = (await pollResponse.json()) as Record<string, unknown>
+      // Poll response: { success: true, item: { _id: '...', status: '...', results: { emails: [...], firstname, lastname } } }
+      const item = (json.item as Record<string, unknown> | undefined) ?? {}
+      const status = (item.status as string | undefined) ?? null
+
+      if (status && TERMINAL_STATUSES.has(status)) {
+        // Any terminal status is a successful run — a clean no-match is not a
+        // failure. The enrichment cascade only calls mapOutput when success is
+        // true, so returning false would skip the verdict and inflate the
+        // runner's error count. A null email signals "not found" downstream.
+        return {
+          success: true,
+          output: mapItem(item),
+        }
+      }
+    }
+
+    throw new Error('Icypeas email-search did not complete within the polling window')
+  },
+
+  outputs: {
+    searchId: ICYPEAS_SEARCH_ID_OUTPUT,
+    status: ICYPEAS_STATUS_OUTPUT,
+    email: ICYPEAS_EMAIL_OUTPUT,
+    firstname: {
+      type: 'string',
+      description: "Found person's first name",
+      optional: true,
+    },
+    lastname: {
+      type: 'string',
+      description: "Found person's last name",
+      optional: true,
+    },
+    item: ICYPEAS_ITEM_OUTPUT,
+  },
+}

apps/sim/tools/icypeas/hosting.ts

@@ -0,0 +1,50 @@
+import type { ToolHostingConfig } from '@/tools/types'
+
+/**
+ * Env var prefix for Icypeas hosted keys. Provide keys as `ICYPEAS_API_KEY_COUNT`
+ * plus `ICYPEAS_API_KEY_1..N`.
+ */
+export const ICYPEAS_API_KEY_PREFIX = 'ICYPEAS_API_KEY'
+
+/**
+ * Dollar cost of a single Icypeas credit.
+ *
+ * Icypeas meters usage in credits at approximately $0.019/credit on the entry
+ * Basic plan (1,000 credits for $19/month). Higher-tier plans reduce cost to as
+ * low as $0.00499/credit. We use the Basic-plan rate as a conservative baseline.
+ *
+ * Credit costs per operation (source: https://www.icypeas.com/pricing):
+ * - Email Finder: 1 credit per found email
+ * - Email Verifier: 0.1 credit per verification
+ * - Domain Scan: 1 credit per domain
+ * - Profile Scraper: 1.5 credits per profile
+ * - Reverse Email Lookup: 10 credits per found profile
+ *
+ * Credits are charged only when a result is returned (FOUND / DEBITED status).
+ */
+export const ICYPEAS_CREDIT_USD = 0.019
+
+/**
+ * Build an Icypeas `hosting` config. `getCredits` returns the number of Icypeas
+ * credits the call consumed, derived from the tool's final output.
+ */
+export function icypeasHosting<P>(
+  getCredits: (params: P, output: Record<string, unknown>) => number
+): ToolHostingConfig<P> {
+  return {
+    envKeyPrefix: ICYPEAS_API_KEY_PREFIX,
+    apiKeyParam: 'apiKey',
+    byokProviderId: 'icypeas',
+    pricing: {
+      type: 'custom',
+      getCost: (params, output) => {
+        const credits = getCredits(params, output)
+        return { cost: credits * ICYPEAS_CREDIT_USD, metadata: { credits } }
+      },
+    },
+    rateLimit: {
+      mode: 'per_request',
+      requestsPerMinute: 60,
+    },
+  }
+}

apps/sim/tools/icypeas/index.ts

@@ -0,0 +1,6 @@
+export * from './types'
+
+import { icypeasFindEmailTool } from '@/tools/icypeas/find_email'
+import { icypeasVerifyEmailTool } from '@/tools/icypeas/verify_email'
+
+export { icypeasFindEmailTool, icypeasVerifyEmailTool }

apps/sim/tools/icypeas/types.ts

@@ -0,0 +1,89 @@
+import type { OutputProperty, ToolResponse } from '@/tools/types'
+
+/** Base params shared by every Icypeas operation. */
+export interface IcypeasBaseParams {
+  apiKey: string
+}
+
+// ---------------------------------------------------------------------------
+// Email Finder (single email discovery)
+// ---------------------------------------------------------------------------
+
+export interface IcypeasFindEmailParams extends IcypeasBaseParams {
+  firstname?: string
+  lastname?: string
+  domainOrCompany: string
+}
+
+export interface IcypeasFindEmailOutput {
+  /** Icypeas internal search ID used to poll the result. */
+  searchId: string | null
+  status: string | null
+  email: string | null
+  firstname: string | null
+  lastname: string | null
+  /** Raw item object from the results endpoint. */
+  item: Record<string, unknown> | null
+}
+
+export interface IcypeasFindEmailResponse extends ToolResponse {
+  output: IcypeasFindEmailOutput
+}
+
+// ---------------------------------------------------------------------------
+// Email Verification
+// ---------------------------------------------------------------------------
+
+export interface IcypeasVerifyEmailParams extends IcypeasBaseParams {
+  email: string
+}
+
+export interface IcypeasVerifyEmailOutput {
+  /** Icypeas internal search ID used to poll the result. */
+  searchId: string | null
+  status: string | null
+  email: string | null
+  /** Whether the email is valid/found. Derived from terminal status. */
+  valid: boolean | null
+  /** Raw item object from the results endpoint. */
+  item: Record<string, unknown> | null
+}
+
+export interface IcypeasVerifyEmailResponse extends ToolResponse {
+  output: IcypeasVerifyEmailOutput
+}
+
+// ---------------------------------------------------------------------------
+// Union response type used by the block
+// ---------------------------------------------------------------------------
+
+export type IcypeasResponse = IcypeasFindEmailResponse | IcypeasVerifyEmailResponse
+
+// ---------------------------------------------------------------------------
+// Shared output property constants
+// ---------------------------------------------------------------------------
+
+export const ICYPEAS_SEARCH_ID_OUTPUT: OutputProperty = {
+  type: 'string',
+  description: 'Icypeas internal search ID',
+  optional: true,
+}
+
+export const ICYPEAS_STATUS_OUTPUT: OutputProperty = {
+  type: 'string',
+  description:
+    'Terminal search status: FOUND | DEBITED | NOT_FOUND | DEBITED_NOT_FOUND | BAD_INPUT | INSUFFICIENT_FUNDS | ABORTED',
+  optional: true,
+}
+
+export const ICYPEAS_EMAIL_OUTPUT: OutputProperty = {
+  type: 'string',
+  description: 'Email address found or verified',
+  optional: true,
+}
+
+export const ICYPEAS_ITEM_OUTPUT: OutputProperty = {
+  type: 'json',
+  description: 'Full raw item object returned by the Icypeas results endpoint',
+  optional: true,
+}

apps/sim/tools/icypeas/verify_email.ts

@@ -0,0 +1,183 @@
+import { sleep } from '@sim/utils/helpers'
+import { icypeasHosting } from '@/tools/icypeas/hosting'
+import type {
+  IcypeasVerifyEmailOutput,
+  IcypeasVerifyEmailParams,
+  IcypeasVerifyEmailResponse,
+} from '@/tools/icypeas/types'
+import {
+  ICYPEAS_EMAIL_OUTPUT,
+  ICYPEAS_ITEM_OUTPUT,
+  ICYPEAS_SEARCH_ID_OUTPUT,
+  ICYPEAS_STATUS_OUTPUT,
+} from '@/tools/icypeas/types'
+import type { ToolConfig } from '@/tools/types'
+
+/** Icypeas statuses that indicate the search has finished (success or failure). */
+const TERMINAL_STATUSES = new Set([
+  'FOUND',
+  'DEBITED',
+  'NOT_FOUND',
+  'DEBITED_NOT_FOUND',
+  'BAD_INPUT',
+  'INSUFFICIENT_FUNDS',
+  'ABORTED',
+])
+
+/** Icypeas statuses that indicate the email address is valid/deliverable. */
+const VALID_STATUSES = new Set(['FOUND', 'DEBITED'])
+
+const POLL_INTERVAL_MS = 3000
+const MAX_POLL_TIME_MS = 120000
+
+/** Map a raw Icypeas item object to the verify-email output shape. */
+function mapItem(item: Record<string, unknown>): IcypeasVerifyEmailOutput {
+  const status = (item.status as string | undefined) ?? null
+  // Verify payloads put the address on item.email; fall back to the nested
+  // results.emails[0].email shape that some responses use.
+  const results = (item.results as Record<string, unknown> | undefined) ?? {}
+  const emails = Array.isArray(results.emails) ? (results.emails as Record<string, unknown>[]) : []
+  const email =
+    (item.email as string | undefined) ?? (emails[0]?.email as string | undefined) ?? null
+  const valid = status !== null ? VALID_STATUSES.has(status) : null
+  return {
+    searchId: (item._id as string | undefined) ?? null,
+    status,
+    email,
+    valid,
+    item,
+  }
+}
+
+export const icypeasVerifyEmailTool: ToolConfig<
+  IcypeasVerifyEmailParams,
+  IcypeasVerifyEmailResponse
+> = {
+  id: 'icypeas_verify_email',
+  name: 'Icypeas Verify Email',
+  description:
+    'Verify whether an email address is valid and deliverable. Submits the verification and polls until a result is available. Costs 0.1 credit per verification (https://www.icypeas.com/pricing).',
+  version: '1.0.0',
+
+  hosting: icypeasHosting<IcypeasVerifyEmailParams>((_params, output) => {
+    // 0.1 credit per verification that consumed credits: FOUND/DEBITED (verdict
+    // delivered) and DEBITED_NOT_FOUND (debited even though unresolved).
+    // BAD_INPUT / INSUFFICIENT_FUNDS / ABORTED / NOT_FOUND are never charged.
+    const status = output.status as string | undefined
+    if (!status) {
+      throw new Error('Icypeas verify-email: cannot determine cost — status is missing')
+    }
+    const billable = status === 'FOUND' || status.includes('DEBITED')
+    // 0.1 credit; express as a fractional number so ICYPEAS_CREDIT_USD math works.
+    return billable ? 0.1 : 0
+  }),
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Icypeas API key',
+    },
+    email: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Email address to verify (e.g. john@stripe.com)',
+    },
+  },
+
+  request: {
+    url: 'https://app.icypeas.com/api/email-verification',
+    method: 'POST',
+    headers: (params: IcypeasVerifyEmailParams) => ({
+      Authorization: params.apiKey,
+      'Content-Type': 'application/json',
+    }),
+    body: (params: IcypeasVerifyEmailParams) => ({
+      email: params.email,
+    }),
+  },
+
+  transformResponse: async (response: Response) => {
+    if (!response.ok) {
+      const errorText = await response.text()
+      throw new Error(`Icypeas API error: ${response.status} - ${errorText}`)
+    }
+    const json = (await response.json()) as Record<string, unknown>
+    // Submit response: { success: true, item: { _id: '...', status: 'NONE', ... } }
+    const item = (json.item as Record<string, unknown> | undefined) ?? {}
+    const searchId = (item._id as string | undefined) ?? null
+    if (!searchId) {
+      throw new Error('Icypeas email-verification did not return an item _id')
+    }
+    return {
+      success: true,
+      output: mapItem(item),
+    }
+  },
+
+  postProcess: async (result, params) => {
+    if (!result.success) return result
+
+    const searchId = result.output.searchId
+    if (!searchId) {
+      throw new Error('Icypeas verify-email result is missing a searchId')
+    }
+
+    // If already terminal, return immediately.
+    if (result.output.status && TERMINAL_STATUSES.has(result.output.status)) {
+      return result
+    }
+
+    let elapsed = 0
+    while (elapsed < MAX_POLL_TIME_MS) {
+      await sleep(POLL_INTERVAL_MS)
+      elapsed += POLL_INTERVAL_MS
+
+      const pollResponse = await fetch('https://app.icypeas.com/api/bulk-single-searchs/read', {
+        method: 'POST',
+        headers: {
+          Authorization: params.apiKey,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ id: searchId }),
+      })
+
+      if (!pollResponse.ok) {
+        const errorText = await pollResponse.text()
+        throw new Error(`Icypeas poll error: ${pollResponse.status} - ${errorText}`)
+      }
+
+      const json = (await pollResponse.json()) as Record<string, unknown>
+      // Poll response: { success: true, item: { _id: '...', status: '...', results: { emails: [...] } } }
+      const item = (json.item as Record<string, unknown> | undefined) ?? {}
+      const status = (item.status as string | undefined) ?? null
+
+      if (status && TERMINAL_STATUSES.has(status)) {
+        // Any terminal status is a successful run — NOT_FOUND/DEBITED_NOT_FOUND are
+        // definitive verdicts, not failures. The enrichment cascade only calls
+        // mapOutput when success is true, so returning false here would skip those
+        // verdicts and inflate the runner's error count. `valid` carries the result.
+        return {
+          success: true,
+          output: mapItem(item),
+        }
+      }
+    }
+
+    throw new Error('Icypeas email-verification did not complete within the polling window')
+  },
+
+  outputs: {
+    searchId: ICYPEAS_SEARCH_ID_OUTPUT,
+    status: ICYPEAS_STATUS_OUTPUT,
+    email: ICYPEAS_EMAIL_OUTPUT,
+    valid: {
+      type: 'boolean',
+      description: 'Whether the email is valid/deliverable (true for FOUND/DEBITED status)',
+      optional: true,
+    },
+    item: ICYPEAS_ITEM_OUTPUT,
+  },
+}