feat(enrichments): provider fallback cascade + hosted-key usage source

Replace each enrichment's single enrich() with an ordered providers[]
fallback cascade. Providers are plain data ({ id, label, toolId,
buildParams, mapOutput }) so the catalog stays client-safe; the
server-only runner (run.ts) calls executeTool per provider, first
non-empty result wins, misses/errors fall through, all-miss = blank cell.

Wire four enrichments on the hosted-safe providers (Hunter, PDL):
- Work Email (fullName, companyDomain): Hunter -> PDL
- Phone Number (fullName, companyDomain): PDL
- Company Domain (companyName): PDL
- Company Info (domain): PDL -> Hunter

Person enrichments take a single canonical fullName (Clay-style); Hunter
gets first/last via splitName(), PDL takes name directly.

Add 'enrichment' to usage_log_source enum (+ migration) so hosted-key
tool cost from these per-row calls can be billed to the table owner.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: TheodoreSpeaks

apps/sim/background/workflow-column-execution.ts

@@ -118,6 +118,7 @@ async function runWorkflowAndWriteTerminal(
     // workflow, reusing the same pickup → run → terminal-write status flow.
     if (group.type === 'enrichment') {
       const { getEnrichment } = await import('@/enrichments/registry')
+      const { runEnrichment } = await import('@/enrichments/run')
       const enrichment = getEnrichment(group.enrichmentId)
       // `tableRowExecutions.workflowId` is an opaque id for status; use the
       // enrichment id for enrichment cells.
@@ -173,7 +174,7 @@ async function runWorkflowAndWriteTerminal(
 
       try {
         if (signal?.aborted) return 'error'
-        const result = await enrichment.enrich(enrichInputs, {
+        const result = await runEnrichment(enrichment, enrichInputs, {
           tableId,
           rowId,
           workspaceId,

apps/sim/enrichments/company-domain/company-domain.ts

@@ -0,0 +1,33 @@
+import { Globe } from 'lucide-react'
+import { normalizeDomain, str, toolProvider } from '@/enrichments/providers'
+import type { EnrichmentConfig } from '@/enrichments/types'
+
+/**
+ * Company Domain enrichment. Resolves a company's website domain from its name
+ * via a People Data Labs company match.
+ */
+export const companyDomainEnrichment: EnrichmentConfig = {
+  id: 'company-domain',
+  name: 'Company Domain',
+  description: "Find a company's website domain from its name.",
+  icon: Globe,
+  inputs: [{ id: 'companyName', name: 'Company name', type: 'string', required: true }],
+  outputs: [{ id: 'domain', name: 'domain', type: 'string' }],
+  providers: [
+    toolProvider({
+      id: 'pdl',
+      label: 'People Data Labs',
+      toolId: 'pdl_company_enrich',
+      buildParams: (inputs) => {
+        const name = str(inputs.companyName)
+        if (!name) return null
+        return { name }
+      },
+      mapOutput: (output) => {
+        const company = output.company as Record<string, unknown> | undefined
+        const domain = normalizeDomain(company?.website)
+        return domain ? { domain } : null
+      },
+    }),
+  ],
+}

apps/sim/enrichments/company-domain/index.ts

@@ -0,0 +1 @@
+export { companyDomainEnrichment } from './company-domain'

apps/sim/enrichments/company-info/company-info.ts

@@ -0,0 +1,67 @@
+import { filterUndefined } from '@sim/utils/object'
+import { Building2 } from 'lucide-react'
+import { normalizeDomain, str, toolProvider } from '@/enrichments/providers'
+import type { EnrichmentConfig } from '@/enrichments/types'
+
+/** Returns the value when it's a finite number, else `undefined`. */
+function num(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined
+}
+
+/**
+ * Company Info enrichment. Looks up firmographics for a company domain, trying
+ * People Data Labs first (richest record, incl. employee count) then Hunter as
+ * a fallback.
+ */
+export const companyInfoEnrichment: EnrichmentConfig = {
+  id: 'company-info',
+  name: 'Company Info',
+  description:
+    "Look up a company's industry, size, founding year, and description from its domain.",
+  icon: Building2,
+  inputs: [{ id: 'domain', name: 'Company domain', type: 'string', required: true }],
+  outputs: [
+    { id: 'industry', name: 'industry', type: 'string' },
+    { id: 'employeeCount', name: 'employee count', type: 'number' },
+    { id: 'foundedYear', name: 'founded year', type: 'number' },
+    { id: 'description', name: 'description', type: 'string' },
+  ],
+  providers: [
+    toolProvider({
+      id: 'pdl',
+      label: 'People Data Labs',
+      toolId: 'pdl_company_enrich',
+      buildParams: (inputs) => {
+        const website = normalizeDomain(inputs.domain)
+        if (!website) return null
+        return { website }
+      },
+      mapOutput: (output) => {
+        const company = output.company as Record<string, unknown> | undefined
+        return filterUndefined({
+          industry: str(company?.industry) || undefined,
+          employeeCount: num(company?.employee_count),
+          foundedYear: num(company?.founded),
+          description: str(company?.summary) || undefined,
+        })
+      },
+    }),
+    toolProvider({
+      id: 'hunter',
+      label: 'Hunter',
+      toolId: 'hunter_companies_find',
+      buildParams: (inputs) => {
+        const domain = normalizeDomain(inputs.domain)
+        if (!domain) return null
+        return { domain }
+      },
+      mapOutput: (output) => {
+        return filterUndefined({
+          industry: str(output.industry) || undefined,
+          foundedYear: num(output.founded_year),
+          description: str(output.description) || undefined,
+        })
+      },
+    }),
+  ],
+}

apps/sim/enrichments/company-info/index.ts

@@ -0,0 +1 @@
+export { companyInfoEnrichment } from './company-info'

apps/sim/enrichments/index.ts

@@ -3,6 +3,7 @@ export type {
   EnrichmentConfig,
   EnrichmentInputField,
   EnrichmentOutputField,
+  EnrichmentProvider,
   EnrichmentRegistry,
   EnrichmentRunContext,
 } from './types'

apps/sim/enrichments/phone-number/phone-number.ts

@@ -1,10 +1,11 @@
+import { filterUndefined } from '@sim/utils/object'
 import { Phone } from 'lucide-react'
+import { firstNonEmpty, normalizeDomain, str, toolProvider } from '@/enrichments/providers'
 import type { EnrichmentConfig } from '@/enrichments/types'
 
 /**
- * Phone Number enrichment. v1 is a stub returning no number (the value resolves
- * empty) — wiring a real data provider (with credentials) is a follow-up. The
- * inputs/outputs contract is in place so the pipeline + UI work end to end.
+ * Phone Number enrichment. Finds a contact's phone number from their full name
+ * and (optionally) company domain via a People Data Labs person match.
  */
 export const phoneNumberEnrichment: EnrichmentConfig = {
   id: 'phone-number',
@@ -16,12 +17,25 @@ export const phoneNumberEnrichment: EnrichmentConfig = {
     { id: 'companyDomain', name: 'Company domain', type: 'string' },
   ],
   outputs: [{ id: 'phone', name: 'phone', type: 'string' }],
-  async enrich(inputs) {
-    const fullName = String(inputs.fullName ?? '').trim()
-    if (!fullName) {
-      throw new Error('Full name is required')
-    }
-    // TODO: call a real phone-lookup provider via ctx; returns empty for now.
-    return { phone: '' }
-  },
+  providers: [
+    toolProvider({
+      id: 'pdl',
+      label: 'People Data Labs',
+      toolId: 'pdl_person_enrich',
+      buildParams: (inputs) => {
+        const name = str(inputs.fullName)
+        if (!name) return null
+        return filterUndefined({
+          name,
+          company: normalizeDomain(inputs.companyDomain) || undefined,
+          min_likelihood: 6,
+        })
+      },
+      mapOutput: (output) => {
+        const person = output.person as Record<string, unknown> | undefined
+        const phone = firstNonEmpty(person?.phone_numbers) ?? str(person?.mobile_phone)
+        return phone ? { phone } : null
+      },
+    }),
+  ],
 }

apps/sim/enrichments/providers.ts

@@ -0,0 +1,47 @@
+import type { EnrichmentProvider } from '@/enrichments/types'
+
+/** Coerces an unknown input value to a trimmed string (`''` when nullish). */
+export function str(value: unknown): string {
+  return String(value ?? '').trim()
+}
+
+/** Strips protocol / path / leading `www.` from a domain-ish input. */
+export function normalizeDomain(value: unknown): string {
+  return str(value)
+    .toLowerCase()
+    .replace(/^https?:\/\//, '')
+    .replace(/^www\./, '')
+    .replace(/\/.*$/, '')
+}
+
+/** Returns the first non-empty string in an array (or `undefined`). */
+export function firstNonEmpty(value: unknown): string | undefined {
+  if (!Array.isArray(value)) return undefined
+  for (const item of value) {
+    const s = str(item)
+    if (s) return s
+  }
+  return undefined
+}
+
+/**
+ * Splits a full name into first / last for providers whose API requires both
+ * (e.g. Hunter). Returns `null` when the name has fewer than two parts, so the
+ * provider falls through to one that accepts a single name string.
+ */
+export function splitName(fullName: unknown): { firstName: string; lastName: string } | null {
+  const parts = str(fullName).split(/\s+/).filter(Boolean)
+  if (parts.length < 2) return null
+  return { firstName: parts[0], lastName: parts.slice(1).join(' ') }
+}
+
+/**
+ * Declares a tool-backed enrichment provider as plain data. Keeping this free of
+ * any `@/tools` reference (the cascade runner does the `executeTool` call) means
+ * the enrichment catalog stays client-safe — the table UI imports it only for
+ * metadata. Workspace scope and BYOK / hosted-key injection are handled by the
+ * runner when it executes `toolId`.
+ */
+export function toolProvider(provider: EnrichmentProvider): EnrichmentProvider {
+  return provider
+}

apps/sim/enrichments/registry.ts

@@ -1,10 +1,14 @@
+import { companyDomainEnrichment } from '@/enrichments/company-domain'
+import { companyInfoEnrichment } from '@/enrichments/company-info'
 import { phoneNumberEnrichment } from '@/enrichments/phone-number'
 import type { EnrichmentConfig, EnrichmentRegistry } from '@/enrichments/types'
 import { workEmailEnrichment } from '@/enrichments/work-email'
 
 export const ENRICHMENT_REGISTRY: EnrichmentRegistry = {
   [workEmailEnrichment.id]: workEmailEnrichment,
   [phoneNumberEnrichment.id]: phoneNumberEnrichment,
+  [companyDomainEnrichment.id]: companyDomainEnrichment,
+  [companyInfoEnrichment.id]: companyInfoEnrichment,
 }
 
 /** All enrichments, in catalog order. */

apps/sim/enrichments/run.ts

@@ -0,0 +1,55 @@
+import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
+import type { EnrichmentConfig, EnrichmentRunContext } from '@/enrichments/types'
+import { executeTool } from '@/tools'
+
+const logger = createLogger('Enrichments')
+
+/** True when at least one output value in the result is non-empty. */
+function hasResult(result: Record<string, unknown>): boolean {
+  return Object.values(result).some((v) => v !== undefined && v !== null && v !== '')
+}
+
+/**
+ * Runs an enrichment's provider cascade for one row. Tries providers in order;
+ * the first that returns a non-empty result wins and is returned. A provider is
+ * skipped when its `buildParams` returns `null` (insufficient inputs); a tool
+ * failure or empty mapped result falls through to the next. When every provider
+ * misses, returns `{}` — the caller writes a blank (not errored) cell.
+ *
+ * Server-only: imports `executeTool`, which pulls in DB / mailer code. Only the
+ * background cell executor imports this module (dynamically).
+ */
+export async function runEnrichment(
+  enrichment: EnrichmentConfig,
+  inputs: Record<string, unknown>,
+  ctx: EnrichmentRunContext
+): Promise<Record<string, unknown>> {
+  for (const provider of enrichment.providers) {
+    if (ctx.signal?.aborted) break
+    const params = provider.buildParams(inputs)
+    if (!params) continue
+    try {
+      const response = await executeTool(
+        provider.toolId,
+        { ...params, _context: { workspaceId: ctx.workspaceId } },
+        { signal: ctx.signal }
+      )
+      if (!response.success) {
+        throw new Error(response.error ?? `${provider.toolId} failed`)
+      }
+      const result = provider.mapOutput(response.output)
+      if (result && hasResult(result)) {
+        logger.info('Enrichment hit', { enrichmentId: enrichment.id, provider: provider.id })
+        return result
+      }
+    } catch (err) {
+      logger.warn('Enrichment provider failed; trying next', {
+        enrichmentId: enrichment.id,
+        provider: provider.id,
+        error: getErrorMessage(err),
+      })
+    }
+  }
+  return {}
+}