@coldiq/mcp 0.1.12 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coldiq/mcp",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "type": "module",
   "main": "dist/index.js",
   "bin": {

package/src/registry.ts

@@ -109,6 +109,60 @@ export function isoCountryToName(code: string): string {
   }
 }
 
+// Reverse lookup: English country name → ISO 3166-1 alpha-2. Built lazily on first use.
+// Agents routinely pass "Brazil" / "United States" instead of "BR" / "US" — without this
+// coercion, downstream providers that require ISO codes (LeadsFactory, BlitzAPI) silently
+// skip the filter.
+let _nameToCode: Map<string, string> | undefined
+function buildNameToCode(): Map<string, string> {
+  const map = new Map<string, string>()
+  // Iterate all ISO-2 codes A-Z × A-Z; keep those Intl.DisplayNames resolves.
+  for (let a = 65; a <= 90; a++) {
+    for (let b = 65; b <= 90; b++) {
+      const code = String.fromCharCode(a, b)
+      try {
+        const name = _displayNames.of(code)
+        if (name && name !== code) map.set(name.toLowerCase(), code)
+      } catch { /* skip */ }
+    }
+  }
+  // Common aliases not covered by Intl.DisplayNames defaults.
+  map.set('usa', 'US')
+  map.set('uk', 'GB')
+  map.set('south korea', 'KR')
+  map.set('north korea', 'KP')
+  map.set('russia', 'RU')
+  map.set('iran', 'IR')
+  map.set('syria', 'SY')
+  map.set('uae', 'AE')
+  map.set('emirates', 'AE')
+  return map
+}
+
+export function nameToIsoCountry(input: string): string | undefined {
+  if (typeof input !== 'string' || input.length === 0) return undefined
+  if (!_nameToCode) _nameToCode = buildNameToCode()
+  // Check aliases first — "UK" matches the ISO-2 regex but is not a valid code (GB is).
+  const aliased = _nameToCode.get(input.trim().toLowerCase())
+  if (aliased) return aliased
+  if (_ALPHA2_RE.test(input)) {
+    const upper = input.toUpperCase()
+    // Only accept if Intl actually resolves it — rejects "ZZ" etc.
+    try {
+      if (_displayNames.of(upper)) return upper
+    } catch { /* fall through */ }
+  }
+  return undefined
+}
+
+// Coerce a list of strings (mix of ISO-2 codes and country names) into ISO-2 codes.
+// Unrecognized inputs are dropped (rather than passed through) so providers don't
+// receive garbage like { code: "Brazil", name: "Brazil" }.
+export function coerceCountriesToIso(values: readonly string[] | undefined): string[] {
+  if (!values?.length) return []
+  return values.map((v) => nameToIsoCountry(v)).filter((c): c is string => typeof c === 'string')
+}
+
 // ---------------------------------------------------------------------------
 // Strict post-filter helpers
 // ---------------------------------------------------------------------------
@@ -200,9 +254,12 @@ const searchCompaniesProviders: ProviderEntry[] = [
     method: 'POST',
     priority: 1,
     mapParams: (input) => {
-      // CompanyEnrich industries require exact taxonomy matches — free-text values like
-      // "SaaS" produce empty results. Fold industries into keywords for flexible matching.
-      const keywords = [
+      // CompanyEnrich's `keywords` body field is a tag filter that does not match
+      // brand names — sending "wework" returns global defaults instead of WeWork.
+      // Route free-text input through `query` (full-text on company name + domain).
+      // Industries are folded into the same string because CompanyEnrich's `industries`
+      // field requires exact taxonomy matches and rejects free-text like "SaaS".
+      const queryTerms = [
         ...((input.keywords as string[] | undefined) ?? []),
         ...((input.industries as string[] | undefined) ?? []),
       ]
@@ -213,7 +270,7 @@ const searchCompaniesProviders: ProviderEntry[] = [
       return {
         body: {
           countries: input.countries,
-          keywords: keywords.length > 0 ? keywords : undefined,
+          query: queryTerms.length > 0 ? queryTerms.join(' ') : undefined,
           technologies: isNonEmptyArray(input.technologies) ? input.technologies : undefined,
           employees:
             input.min_employees || input.max_employees
@@ -944,6 +1001,14 @@ const findPeopleProviders: ProviderEntry[] = [
           ? [...groups.values()].map((titles) => ({ job_title: titles.join(', ') }))
           : [{ job_title: 'Decision Maker' }]
       const hasLinkedInUrls = isNonEmptyArray(input.company_linkedin_urls)
+      // LF natively scopes contacts by person location via country_codes. Coerce
+      // input.locations (which agents pass as a mix of ISO-2 codes "BR" and country
+      // names "Brazil") to ISO-2 first — LF rejects/ignores anything else and silently
+      // returns unfiltered global results.
+      const isoCodes = coerceCountriesToIso(input.locations as string[] | undefined)
+      const country_codes = isoCodes.length > 0
+        ? isoCodes.map((code) => ({ code, name: isoCountryToName(code) }))
+        : undefined
       return {
         body: {
           ...(hasLinkedInUrls && { company_linkedin_urls: input.company_linkedin_urls }),
@@ -954,6 +1019,7 @@ const findPeopleProviders: ProviderEntry[] = [
           search: {
             max_persona_results: (input.limit as number) ?? 25,
             personas,
+            ...(country_codes && { country_codes }),
           },
         },
       }
@@ -962,7 +1028,7 @@ const findPeopleProviders: ProviderEntry[] = [
       const d = data as Record<string, unknown>
       return (
         isNonEmptyArray(d.companies_personas) ||
-        (d.status === 'SUCCESSFUL' && typeof d.nb_jobs_complete === 'number' && (d.nb_jobs_complete as number) > 0)
+        (d.status === 'SUCCESSFUL' && d.nb_jobs_complete != null && (d.nb_jobs_complete as number) > 0)
       )
     },
     async: {
@@ -975,7 +1041,7 @@ const findPeopleProviders: ProviderEntry[] = [
       isComplete: (data) => {
         const d = data as Record<string, unknown>
         const status = d.status as string | undefined
-        return status === 'SUCCESSFUL' || status === 'FAILED'
+        return status === 'SUCCESSFUL' || status === 'FAILED' || status === 'INVALID_URL'
       },
       extractId: (response) => {
         const d = response as Record<string, unknown>

package/src/tools/find-emails.ts

@@ -1,7 +1,36 @@
 import { z } from 'zod'
 import { callApi } from '../client.js'
+import { executeWithFallback, isExecutionError } from '../executor.js'
 import { resolvePreferredProviders, buildAllFailedError, FIND_EMAILS_PROVIDERS } from '../utils/provider-resolver.js'
 
+// Single-find_email registry providers that the bulk pipeline does NOT already cover.
+// Used as a fallback waterfall for residual misses after Prospeo + FullEnrich + Findymail + Icypeas.
+const SINGLE_ONLY_FIND_EMAIL_PROVIDERS = ['limadata-work-email', 'blitzapi', 'limadata-work-email-linkedin', 'linkupapi'] as const
+
+// Pulls a string email from any of the provider-specific response shapes used in the
+// find_email registry (registry.ts:1228-1413). Keep in sync with the providers covered there.
+function extractEmail(data: unknown): string | null {
+  if (!data || typeof data !== 'object') return null
+  const d = data as Record<string, unknown>
+  if (typeof d.email === 'string' && d.email.includes('@')) return d.email
+  if (Array.isArray(d.emails) && typeof d.emails[0] === 'string' && (d.emails[0] as string).includes('@')) return d.emails[0] as string
+  const person = d.person as Record<string, unknown> | undefined
+  const personEmail = person?.email as Record<string, unknown> | undefined
+  if (typeof personEmail?.email === 'string' && (personEmail.email as string).includes('@')) return personEmail.email as string
+  const nested = d.data
+  if (nested && typeof nested === 'object' && !Array.isArray(nested)) {
+    const inner = (nested as Record<string, unknown>).email
+    if (typeof inner === 'string' && inner.includes('@')) return inner
+  }
+  if (Array.isArray(nested) && nested[0] && typeof nested[0] === 'object') {
+    const first = nested[0] as Record<string, unknown>
+    if (Array.isArray(first.emails) && typeof first.emails[0] === 'string' && (first.emails[0] as string).includes('@')) {
+      return first.emails[0] as string
+    }
+  }
+  return null
+}
+
 export const findEmailsName = 'find_emails'
 
 export const findEmailsDescription =
@@ -221,6 +250,41 @@ export async function findEmailsHandler(input: Record<string, unknown>) {
     if (steps.length > 0) await Promise.allSettled(steps)
   }
 
+  // Step 4 — single-find_email fallback for stragglers.
+  // Bulk covers Prospeo + FullEnrich + FindyMail + IcyPeas. The single-find_email registry
+  // (registry.ts:1228-1413) additionally covers LimaData, BlitzAPI, LimaData-LinkedIn, LinkupAPI.
+  // Without this step, agents would observe bulk return 0 and fall back to N+1 single calls.
+  const stragglers = missesOf(people, results)
+  if (stragglers.length > 0) {
+    const fallbackProviders = isConstrained
+      ? allowedProviders.filter((p) => (SINGLE_ONLY_FIND_EMAIL_PROVIDERS as readonly string[]).includes(p))
+      : [...SINGLE_ONLY_FIND_EMAIL_PROVIDERS]
+    if (fallbackProviders.length > 0) {
+      await Promise.all(
+        stragglers.map(async (person) => {
+          const hit = results.find((r) => r.id === person.id)
+          if (!hit || hit.email) return
+          const singleInput: Record<string, unknown> = {
+            first_name: person.first_name,
+            last_name: person.last_name,
+            domain: person.domain,
+            linkedin_url: person.linkedin_url,
+          }
+          // Per-person 30s ceiling so one slow provider doesn't block the rest.
+          const exec = executeWithFallback('find_email', singleInput, { providers: fallbackProviders })
+          const timeout = new Promise<null>((resolve) => setTimeout(() => resolve(null), 30_000))
+          const raced = await Promise.race([exec, timeout])
+          if (!raced || isExecutionError(raced)) return
+          const email = extractEmail(raced.data)
+          if (email && !hit.email) {
+            hit.email = email
+            hit.provider = raced._meta.provider
+          }
+        }),
+      )
+    }
+  }
+
   const found = results.filter((r) => r.email !== null).length
 
   if (isConstrained && found === 0) {

package/src/tools/find-people.ts

@@ -22,7 +22,7 @@ export const findPeopleSchema = {
   company_domains: z.array(z.string()).optional().describe('Company domains to search (e.g. ["microsoft.com", "google.com"]). Use only when LinkedIn URLs are not available.'),
   job_titles: z.array(z.string()).optional().describe('Target job titles (e.g. ["CEO", "VP of Sales"])'),
   seniorities: z.array(z.string()).optional().describe('Seniority levels (e.g. ["c_suite", "vp", "director"])'),
-  locations: z.array(z.string()).optional().describe('Person or company locations'),
+  locations: z.array(z.string()).optional().describe('Person locations as either ISO-2 country codes ("BR") or English country names ("Brazil") — both are accepted and normalized internally. LeadsFactory uses these to scope contacts to the country; other providers fall back to free-text matching.'),
   keywords: z.array(z.string()).optional().describe('Free-text keyword search terms (e.g. ["growth", "AI"])'),
   limit: z.number().min(1).max(500).default(25).describe('Max results across all companies combined (default: 25, max: 500). For multiple companies multiply: e.g. 10 companies × 5 each = 50.'),
   use_providers: z.array(z.string()).optional().describe(`Optional ordered list of providers to use. Leave empty to let ColdIQ automatically pick the best tool for your inputs — recommended for most use cases. Available providers: ${getProvidersForCapability('find_people').join(', ')}. Provider names are matched fuzzily, so minor typos are tolerated.`),

package/tests/live/companyenrich-async-probe.ts

@@ -0,0 +1,31 @@
+// Probe /companies/search/async body shape — does it want filters flat under `search`
+// or still wrapped under `search.filters`?
+const KEY = process.env.COMPANYENRICH_API_KEY!
+const BASE = 'https://api.companyenrich.com'
+
+async function call(label: string, body: unknown) {
+  const t0 = Date.now()
+  const res = await fetch(`${BASE}/companies/search/async`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(20_000),
+  })
+  let data: any
+  try { data = await res.json() } catch { data = '<non-json>' }
+  console.log(`[${label}]\n  body=${JSON.stringify(body)}\n  status=${res.status} ms=${Date.now() - t0} data=${JSON.stringify(data).slice(0, 300)}\n`)
+}
+
+async function main() {
+  // Use count=1 to minimise credit burn.
+  await call('A: search.filters wrapped (current)', {
+    search: { filters: { query: 'wework' } }, count: 1,
+  })
+  await call('B: search flat (proposed)', {
+    search: { query: 'wework' }, count: 1,
+  })
+  // Some async APIs accept query at the very top too.
+  await call('C: query at top, no search envelope', { query: 'wework', count: 1 })
+}
+
+main()

package/tests/live/companyenrich-fix-validation.ts

@@ -0,0 +1,125 @@
+// Validation suite — confirms the fix direction before committing.
+//
+// What we need to prove:
+//   1. `{filters: {...}}` wrapping is broken across the FOUR search endpoints
+//      (search, preview, count, scroll). If only `/search` is affected, the fix is narrower.
+//   2. Top-level shape works consistently — filter combinations (query + country,
+//      query + employees, etc.) all narrow the result set as expected.
+//   3. The bulk-enrich endpoint is unaffected (the bug is search-specific).
+//   4. Ranges that wrapFilters translates (employees, foundedYear) still need their
+//      translation logic — confirm whether upstream wants employeesFrom/employeesTo top-level
+//      or {employees: {from, to}} or [{from, to}].
+//
+// Run:  COMPANYENRICH_API_KEY=… npx tsx mcp/tests/live/companyenrich-fix-validation.ts
+
+const KEY = process.env.COMPANYENRICH_API_KEY
+if (!KEY) { console.error('COMPANYENRICH_API_KEY required'); process.exit(1) }
+const BASE = 'https://api.companyenrich.com'
+
+async function callRaw(path: string, body: unknown) {
+  const t0 = Date.now()
+  try {
+    const res = await fetch(`${BASE}${path}`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(30_000),
+    })
+    let data: any
+    try { data = await res.json() } catch { data = '<non-json>' }
+    return { ok: res.ok, status: res.status, ms: Date.now() - t0, data }
+  } catch (err) {
+    return { ok: false, status: 0, ms: Date.now() - t0, data: { error: String(err) } }
+  }
+}
+
+function summarize(r: any) {
+  const items = (r.data?.items ?? []).slice(0, 3).map((c: any) => `${c.name}/${c.country ?? '?'}`)
+  return `status=${r.status} ms=${r.ms} count=${r.data?.items?.length ?? r.data?.count ?? '?'} top=${JSON.stringify(items)}`
+}
+
+function header(s: string) { console.log(`\n${'═'.repeat(78)}\n${s}\n${'═'.repeat(78)}`) }
+function sub(s: string) { console.log(`\n— ${s}`) }
+
+async function main() {
+  // ============================================================================
+  header('PART 1 — Confirm the wrap-vs-top-level bug on EACH of 4 search endpoints')
+  // ============================================================================
+
+  const wrapped = { pageSize: 5, filters: { query: 'wework' } }
+  const flat    = { pageSize: 5, query: 'wework' }
+
+  for (const path of ['/companies/search', '/companies/search/preview', '/companies/search/scroll']) {
+    sub(`${path}  wrapped (current)`)
+    console.log('  ', summarize(await callRaw(path, wrapped)))
+    sub(`${path}  flat  (proposed)`)
+    console.log('  ', summarize(await callRaw(path, flat)))
+  }
+
+  // count endpoint returns a count not items
+  sub('/companies/search/count  wrapped (current)')
+  let r = await callRaw('/companies/search/count', { filters: { query: 'wework' } })
+  console.log(`  status=${r.status} ms=${r.ms} data=${JSON.stringify(r.data).slice(0, 200)}`)
+  sub('/companies/search/count  flat (proposed)')
+  r = await callRaw('/companies/search/count', { query: 'wework' })
+  console.log(`  status=${r.status} ms=${r.ms} data=${JSON.stringify(r.data).slice(0, 200)}`)
+
+  // ============================================================================
+  header('PART 2 — Confirm flat-shape combinations actually narrow results')
+  // ============================================================================
+
+  sub('flat: query="wework" + countries=["BR"]')
+  console.log('  ', summarize(await callRaw('/companies/search', { pageSize: 5, query: 'wework', countries: ['BR'] })))
+
+  sub('flat: query="wework" + countries=["US"]')
+  console.log('  ', summarize(await callRaw('/companies/search', { pageSize: 5, query: 'wework', countries: ['US'] })))
+
+  sub('flat: countries=["BR"] + keywords=["fintech"]')
+  console.log('  ', summarize(await callRaw('/companies/search', { pageSize: 5, countries: ['BR'], keywords: ['fintech'] })))
+
+  sub('flat: keywords=["SaaS"]  (does keywords field do anything at top level?)')
+  console.log('  ', summarize(await callRaw('/companies/search', { pageSize: 5, keywords: ['SaaS'] })))
+
+  sub('flat: industries=["Software"]  (does industries field do anything?)')
+  console.log('  ', summarize(await callRaw('/companies/search', { pageSize: 5, industries: ['Software'] })))
+
+  // ============================================================================
+  header('PART 3 — Confirm range shape (employees, foundedYear) works at top level')
+  // ============================================================================
+
+  sub('flat: employees=[{from:1000, to:5000}]')
+  console.log('  ', summarize(await callRaw('/companies/search', { pageSize: 5, employees: [{ from: 1000, to: 5000 }] })))
+
+  sub('flat: employeesFrom=1000 + employeesTo=5000 (the wrapFilters translation target)')
+  console.log('  ', summarize(await callRaw('/companies/search', { pageSize: 5, employeesFrom: 1000, employeesTo: 5000 })))
+
+  sub('flat: foundedYear={from:2015, to:2020}')
+  console.log('  ', summarize(await callRaw('/companies/search', { pageSize: 5, foundedYear: { from: 2015, to: 2020 } })))
+
+  sub('flat: foundedFrom=2015 + foundedTo=2020 (translated form)')
+  console.log('  ', summarize(await callRaw('/companies/search', { pageSize: 5, foundedFrom: 2015, foundedTo: 2020 })))
+
+  // ============================================================================
+  header('PART 4 — Confirm bulk-enrich endpoint is unaffected (no wrapFilters there)')
+  // ============================================================================
+
+  sub('POST /companies/enrich?domain=wework.com (single enrich, GET-like)')
+  // Single enrich uses query params, not wrapFilters — should be unaffected.
+  try {
+    const er = await fetch(`${BASE}/companies/enrich?domain=wework.com`, {
+      method: 'GET',
+      headers: { Authorization: `Bearer ${KEY}` },
+      signal: AbortSignal.timeout(20_000),
+    })
+    const ed = await er.json()
+    console.log(`  status=${er.status} name=${(ed as any)?.name} domain=${(ed as any)?.domain}`)
+  } catch (err) {
+    console.log(`  failed: ${err}`)
+  }
+
+  // ============================================================================
+  header('DONE')
+  // ============================================================================
+}
+
+main().catch((e) => { console.error('FATAL', e); process.exit(1) })

package/tests/live/companyenrich-hybrid-probe.ts

@@ -0,0 +1,54 @@
+// Hybrid: scalars top-level, ranges wrapped? Or ranges with a special shape?
+const KEY = process.env.COMPANYENRICH_API_KEY!
+const BASE = 'https://api.companyenrich.com'
+
+async function count(label: string, body: unknown) {
+  const t0 = Date.now()
+  const res = await fetch(`${BASE}/companies/search/count`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(20_000),
+  })
+  const data: any = await res.json().catch(() => ({}))
+  console.log(`[${label}]\n  body=${JSON.stringify(body)}\n  status=${res.status} ms=${Date.now() - t0} count=${data?.count} total=${data?.total}\n`)
+}
+
+async function main() {
+  // Hypothesis A: maybe ranges need `filters: {}` wrapping (hybrid model)
+  await count('A1: countries top-level + filters.employees', {
+    countries: ['US'], filters: { employees: { from: 1000, to: 5000 } },
+  })
+  await count('A2: countries top-level + filters.employeesFrom/To', {
+    countries: ['US'], filters: { employeesFrom: 1000, employeesTo: 5000 },
+  })
+
+  // Hypothesis B: everything inside filters (back to old shape)
+  await count('B: filters.countries + filters.employees array', {
+    filters: { countries: ['US'], employees: [{ from: 1000, to: 5000 }] },
+  })
+
+  // Hypothesis C: maybe a different field name (size, headcount_range, employee_range)
+  await count('C1: size {from,to}', { size: { from: 1000, to: 5000 } })
+  await count('C2: headcountRange {min,max}', { headcountRange: { min: 1000, max: 5000 } })
+  await count('C3: employeesRange', { employeesRange: { from: 1000, to: 5000 } })
+
+  // Hypothesis D: maybe array of buckets like ["1001-5000"] or letter codes
+  await count('D1: employees ["1001-5000"]', { employees: ['1001-5000'] })
+  await count('D2: employees ["F"]', { employees: ['F'] }) // LimaData uses letter buckets, just in case
+
+  // Hypothesis E: snake_case field name
+  await count('E: employees_from/employees_to', { employees_from: 1000, employees_to: 5000 })
+
+  // Hypothesis F: revenue & funding to triangulate — do ANY ranges work?
+  await count('F1: revenueFrom/revenueTo', { revenueFrom: 1000000, revenueTo: 10000000 })
+  await count('F2: filters.revenueFrom/revenueTo', { filters: { revenueFrom: 1000000, revenueTo: 10000000 } })
+
+  // Hypothesis G: lookup an actual reference-data endpoint for valid bucket IDs (CompanyEnrich does have one)
+  // Skipping — adds latency; do if all of the above fail.
+
+  // Sanity check
+  await count('sanity: countries=DE alone', { countries: ['DE'] })
+}
+
+main()

package/tests/live/companyenrich-query-probe.ts

@@ -0,0 +1,49 @@
+// Probe CompanyEnrich /companies/search to find the correct field name for brand-name lookup.
+// We hit our marketplace endpoint with different request shapes and observe what comes back.
+const API_URL = process.env.COLDIQ_API_URL ?? 'https://api.coldiq.com'
+const API_KEY = process.env.COLDIQ_API_KEY!
+
+async function call(body: unknown) {
+  const t0 = Date.now()
+  const res = await fetch(`${API_URL}/v1/companyenrich/companies/search`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(30_000),
+  })
+  let data: any
+  try { data = await res.json() } catch { data = '<non-json>' }
+  return { ok: res.ok, status: res.status, ms: Date.now() - t0, data }
+}
+
+function summarize(r: any) {
+  const items = (r.data?.items ?? []).slice(0, 5).map((c: any) => `${c.name} (${c.domain})`)
+  return `status=${r.status} ms=${r.ms} items=${items.length} top5=${JSON.stringify(items)}`
+}
+
+async function main() {
+  console.log('=== Probe: how to find WeWork in CompanyEnrich ===\n')
+
+  console.log('1) query="wework"')
+  console.log('  ', summarize(await call({ query: 'wework', pageSize: 5 })))
+
+  console.log('\n2) names=["WeWork"]')
+  console.log('  ', summarize(await call({ names: ['WeWork'], pageSize: 5 })))
+
+  console.log('\n3) domains=["wework.com"]')
+  console.log('  ', summarize(await call({ domains: ['wework.com'], pageSize: 5 })))
+
+  console.log('\n4) query="wework" + countries=["US"]')
+  console.log('  ', summarize(await call({ query: 'wework', countries: ['US'], pageSize: 5 })))
+
+  console.log('\n5) semanticQuery="WeWork coworking"')
+  console.log('  ', summarize(await call({ semanticQuery: 'WeWork coworking', pageSize: 5 })))
+
+  console.log('\n6) names=["wework"] (lowercase)')
+  console.log('  ', summarize(await call({ names: ['wework'], pageSize: 5 })))
+
+  console.log('\n7) only countries=["BR"] (baseline — what does no name filter return?)')
+  console.log('  ', summarize(await call({ countries: ['BR'], pageSize: 5 })))
+}
+
+main().catch(console.error)

package/tests/live/companyenrich-ranges-probe.ts

@@ -0,0 +1,49 @@
+// Probe the range-filter shape. We use /companies/search/count because it gives a
+// definitive "did the filter narrow?" signal — full-DB count is ~20.4M, so anything
+// less means the filter applied.
+const KEY = process.env.COMPANYENRICH_API_KEY!
+const BASE = 'https://api.companyenrich.com'
+
+async function count(label: string, body: unknown) {
+  const t0 = Date.now()
+  const res = await fetch(`${BASE}/companies/search/count`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(20_000),
+  })
+  const data: any = await res.json().catch(() => ({}))
+  const ms = Date.now() - t0
+  console.log(`[${label}]`)
+  console.log(`  body=${JSON.stringify(body)}`)
+  console.log(`  status=${res.status} ms=${ms} count=${data?.count} total=${data?.total}\n`)
+}
+
+async function main() {
+  // Baselines
+  await count('baseline empty', {})
+  await count('baseline countries=US', { countries: ['US'] })
+
+  // Range candidates — try every shape
+  await count('flat employeesFrom/employeesTo', { employeesFrom: 1000, employeesTo: 5000 })
+  await count('flat employees array [{from,to}]', { employees: [{ from: 1000, to: 5000 }] })
+  await count('flat employees object {from,to}', { employees: { from: 1000, to: 5000 } })
+  await count('flat employees scalar {min,max}', { employees: { min: 1000, max: 5000 } })
+  await count('flat employeesMin/employeesMax', { employeesMin: 1000, employeesMax: 5000 })
+  await count('flat headcount', { headcount: { from: 1000, to: 5000 } })
+  await count('flat employee_count', { employee_count: { from: 1000, to: 5000 } })
+
+  // Ranges combined with a primary filter (in case they need company narrowing first)
+  await count('countries=US + employeesFrom/To', { countries: ['US'], employeesFrom: 1000, employeesTo: 5000 })
+  await count('countries=US + employees array', { countries: ['US'], employees: [{ from: 1000, to: 5000 }] })
+
+  // Founded year shapes
+  await count('foundedFrom/foundedTo', { foundedFrom: 2015, foundedTo: 2020 })
+  await count('foundedYear {from,to}', { foundedYear: { from: 2015, to: 2020 } })
+  await count('foundedYearFrom/foundedYearTo', { foundedYearFrom: 2015, foundedYearTo: 2020 })
+
+  // Sanity — does a known-working filter still narrow alongside ranges?
+  await count('countries=BR (sanity)', { countries: ['BR'] })
+}
+
+main()

package/tests/live/companyenrich-upstream-probe.ts

@@ -0,0 +1,72 @@
+// Direct upstream probe — bypasses the marketplace proxy.
+// Goal: figure out whether CompanyEnrich's /companies/search wants filters wrapped
+// under { filters: {...} } (current behavior) or at the top level, and whether ANY
+// filter shape narrows results away from their default top-5.
+//
+// Run:  COMPANYENRICH_API_KEY=… npx tsx mcp/tests/live/companyenrich-upstream-probe.ts
+
+const KEY = process.env.COMPANYENRICH_API_KEY
+if (!KEY) {
+  console.error('COMPANYENRICH_API_KEY required')
+  process.exit(1)
+}
+
+const BASE = 'https://api.companyenrich.com'
+
+async function call(body: unknown, label: string) {
+  const t0 = Date.now()
+  let res: Response
+  try {
+    res = await fetch(`${BASE}/companies/search`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(30_000),
+    })
+  } catch (err) {
+    console.log(`\n[${label}] body=${JSON.stringify(body)}`)
+    console.log(`  fetch-failed: ${err instanceof Error ? err.message : String(err)}`)
+    return
+  }
+  let data: any
+  try { data = await res.json() } catch { data = '<non-json>' }
+  const items = (data?.items ?? []).slice(0, 5).map((c: any) => `${c.name} (${c.domain})`)
+  console.log(`\n[${label}] body=${JSON.stringify(body)}`)
+  console.log(`  status=${res.status} ms=${Date.now() - t0} count=${data?.items?.length ?? 0}`)
+  console.log(`  top5=${JSON.stringify(items)}`)
+  if (!res.ok) console.log(`  raw=${JSON.stringify(data).slice(0, 400)}`)
+}
+
+async function main() {
+  console.log('=== CompanyEnrich /companies/search direct upstream probe ===')
+  console.log(`BASE=${BASE}`)
+
+  // A. What our marketplace currently sends
+  await call({ pageSize: 5, filters: { query: 'wework' } }, 'A. filters.query="wework" (our current shape)')
+
+  // B. Try query at top level
+  await call({ query: 'wework', pageSize: 5 }, 'B. top-level query="wework"')
+
+  // C. Try an exact identifier wrapped
+  await call({ pageSize: 5, filters: { domains: ['wework.com'] } }, 'C. filters.domains=["wework.com"]')
+
+  // D. Try an exact identifier top-level
+  await call({ domains: ['wework.com'], pageSize: 5 }, 'D. top-level domains=["wework.com"]')
+
+  // E. Try names wrapped
+  await call({ pageSize: 5, filters: { names: ['WeWork'] } }, 'E. filters.names=["WeWork"]')
+
+  // F. Country filter only (baseline narrowing)
+  await call({ pageSize: 5, filters: { countries: ['BR'] } }, 'F. filters.countries=["BR"] (baseline)')
+
+  // G. Country top-level
+  await call({ countries: ['BR'], pageSize: 5 }, 'G. top-level countries=["BR"]')
+
+  // H. Empty body — what does no filter return?
+  await call({ pageSize: 5 }, 'H. {pageSize:5} — empty body')
+
+  // I. semanticQuery (alternative full-text path)
+  await call({ pageSize: 5, filters: { semanticQuery: 'WeWork coworking real estate' } }, 'I. filters.semanticQuery="WeWork coworking real estate"')
+}
+
+main().catch((err) => { console.error('FATAL:', err); process.exit(1) })

package/tests/live/wework-brazil-trace.ts

@@ -0,0 +1,200 @@
+// Live prod trace for the "C-suite of WeWork Brazil" agent flow.
+// Pinpoints which calls misbehave so we can fix find_people / find_emails / search_companies
+// before re-running and measuring improvement.
+//
+// Run: COLDIQ_API_KEY=ciq_test_xxx tsx mcp/tests/live/wework-brazil-trace.ts
+
+const API_URL = process.env.COLDIQ_API_URL ?? 'https://api.coldiq.com'
+const API_KEY = process.env.COLDIQ_API_KEY
+if (!API_KEY) {
+  console.error('COLDIQ_API_KEY required')
+  process.exit(1)
+}
+
+type Result = { ok: boolean; status: number; data: unknown; ms: number }
+
+async function call(method: 'GET' | 'POST', path: string, body?: unknown): Promise<Result> {
+  const t0 = Date.now()
+  try {
+    const res = await fetch(`${API_URL}/v1${path}`, {
+      method,
+      headers: {
+        Authorization: `Bearer ${API_KEY}`,
+        ...(body ? { 'Content-Type': 'application/json' } : {}),
+      },
+      body: body ? JSON.stringify(body) : undefined,
+      signal: AbortSignal.timeout(120_000),
+    })
+    let data: unknown
+    try { data = await res.json() } catch { data = '<non-json>' }
+    return { ok: res.ok, status: res.status, data, ms: Date.now() - t0 }
+  } catch (err) {
+    return {
+      ok: false,
+      status: 0,
+      data: { error: 'fetch-failed', message: err instanceof Error ? err.message : String(err) },
+      ms: Date.now() - t0,
+    }
+  }
+}
+
+function shortJson(v: unknown, max = 400): string {
+  const s = typeof v === 'string' ? v : JSON.stringify(v)
+  return s.length > max ? s.slice(0, max) + '…' : s
+}
+
+function header(s: string) { console.log(`\n${'='.repeat(78)}\n${s}\n${'='.repeat(78)}`) }
+function step(s: string) { console.log(`\n— ${s} —`) }
+
+async function main() {
+  header('WeWork Brazil — live trace')
+  console.log(`API: ${API_URL}`)
+
+  // ---------------------------------------------------------------
+  // 1. search_companies — does the corrected `query` field surface WeWork?
+  //    Compares the buggy `keywords` shape (before-fix) with the fixed `query` shape (after-fix).
+  // ---------------------------------------------------------------
+  for (const kw of ['wework', 'wework brazil', 'WeWork']) {
+    step(`BEFORE-FIX companyenrich/companies/search keywords=[${kw}]`)
+    let r = await call('POST', '/companyenrich/companies/search', { keywords: [kw], pageSize: 5 })
+    console.log(`  status=${r.status} ms=${r.ms} top=${(((r.data as any)?.items ?? [])[0]?.name) ?? '<none>'}`)
+
+    step(`AFTER-FIX  companyenrich/companies/search query="${kw}"`)
+    r = await call('POST', '/companyenrich/companies/search', { query: kw, pageSize: 5 })
+    const top3 = (((r.data as any)?.items ?? []) as any[]).slice(0, 3).map((c: any) => c.name)
+    console.log(`  status=${r.status} ms=${r.ms} top3=${JSON.stringify(top3)}`)
+  }
+
+  step('fullenrich/company/search keywords=[wework]')
+  let r = await call('POST', '/fullenrich/company/search', {
+    keywords: [{ value: 'wework' }],
+    limit: 5,
+  })
+  console.log(`  status=${r.status} ms=${r.ms} data=${shortJson(r.data, 400)}`)
+
+  step('signalbase/companies search=wework')
+  r = await call('GET', `/signalbase/companies?search=${encodeURIComponent('wework')}&limit=5`)
+  console.log(`  status=${r.status} ms=${r.ms} data=${shortJson(r.data, 400)}`)
+
+  // ---------------------------------------------------------------
+  // 2. enrich_company — confirm wework.com
+  // ---------------------------------------------------------------
+  step('enrich_company domain=wework.com')
+  r = await call('POST', '/companyenrich/companies/enrich', { domain: 'wework.com' })
+  console.log(`  status=${r.status} ms=${r.ms}`)
+  console.log(`  data=${shortJson(r.data, 400)}`)
+
+  // ---------------------------------------------------------------
+  // 3. find_people — LeadsFactory WITHOUT country filter (current behavior)
+  // ---------------------------------------------------------------
+  step('LF contact-finder — wework.com, no country filter')
+  const lfNoCountry = await call('POST', '/leadsfactory/contact-finder/searches', {
+    company_domains: ['wework.com'],
+    search: {
+      max_persona_results: 10,
+      personas: [
+        { job_title: 'CEO, Chief Executive Officer' },
+        { job_title: 'Head of Sales, VP Sales' },
+        { job_title: 'Country Manager, Managing Director' },
+      ],
+    },
+  })
+  console.log(`  status=${lfNoCountry.status} ms=${lfNoCountry.ms}`)
+  console.log(`  data=${shortJson(lfNoCountry.data, 400)}`)
+
+  // ---------------------------------------------------------------
+  // 4. find_people — LeadsFactory WITH country filter (proposed fix)
+  // ---------------------------------------------------------------
+  step('LF contact-finder — wework.com + country_codes BR')
+  const lfBr = await call('POST', '/leadsfactory/contact-finder/searches', {
+    company_domains: ['wework.com'],
+    search: {
+      max_persona_results: 10,
+      personas: [
+        { job_title: 'CEO, Chief Executive Officer' },
+        { job_title: 'Head of Sales, VP Sales' },
+        { job_title: 'Country Manager, Managing Director' },
+      ],
+      country_codes: [{ code: 'BR', name: 'Brazil' }],
+    },
+  })
+  console.log(`  status=${lfBr.status} ms=${lfBr.ms}`)
+  console.log(`  data=${shortJson(lfBr.data, 600)}`)
+
+  // Poll one of them if async
+  function extractId(d: unknown): string | undefined {
+    const o = d as Record<string, unknown>
+    return (o?._id as string) ?? (o?.search_id as string)
+  }
+  const lfId = extractId(lfBr.data)
+  if (lfId) {
+    step(`Polling LF search ${lfId} (up to 90s)…`)
+    const deadline = Date.now() + 90_000
+    let attempt = 0
+    while (Date.now() < deadline) {
+      attempt++
+      const wait = attempt === 1 ? 2000 : attempt === 2 ? 5000 : 12000
+      await new Promise((r) => setTimeout(r, wait))
+      const pr = await call('GET', `/leadsfactory/contact-finder/searches/${lfId}`)
+      const d = pr.data as Record<string, unknown>
+      console.log(`  attempt=${attempt} status=${d?.status} complete=${d?.nb_jobs_complete}/${d?.nb_jobs_total} (${pr.ms}ms)`)
+      if (d?.status === 'SUCCESSFUL' || d?.status === 'FAILED' || d?.status === 'INVALID_URL') {
+        console.log(`  final=${shortJson(d, 1200)}`)
+        break
+      }
+    }
+  }
+
+  // ---------------------------------------------------------------
+  // 5. find_emails (bulk) vs find_email (single) on the same people
+  //    Use realistic test people from a public source — Estefania Barbosa @ wework.com
+  // ---------------------------------------------------------------
+  const testPeople = [
+    { id: 'estefania', first_name: 'Estefania', last_name: 'Barbosa', domain: 'wework.com' },
+    { id: 'marcelo',   first_name: 'Marcelo',   last_name: 'Russo',   domain: 'wework.com' },
+    { id: 'marina',    first_name: 'Marina',    last_name: 'Soares',  domain: 'wework.com' },
+  ]
+
+  step('Prospeo bulk (the bulk-find_emails Step 1)')
+  const prospeoBulk = await call('POST', '/prospeo/bulk-enrich-person', {
+    data: testPeople.map((p) => ({
+      identifier: p.id, first_name: p.first_name, last_name: p.last_name, company_name: p.domain,
+    })),
+  })
+  console.log(`  status=${prospeoBulk.status} ms=${prospeoBulk.ms}`)
+  console.log(`  data=${shortJson(prospeoBulk.data, 800)}`)
+
+  step('Findymail single — each person, in parallel')
+  const findyResults = await Promise.all(
+    testPeople.map(async (p) => {
+      const fr = await call('POST', '/findymail/search/name', {
+        name: `${p.first_name} ${p.last_name}`,
+        domain: p.domain,
+      })
+      return { id: p.id, status: fr.status, ms: fr.ms, data: fr.data }
+    }),
+  )
+  for (const f of findyResults) {
+    console.log(`  ${f.id}: status=${f.status} ms=${f.ms} → ${shortJson(f.data, 200)}`)
+  }
+
+  step('Icypeas single — each person, in parallel')
+  const icyResults = await Promise.all(
+    testPeople.map(async (p) => {
+      const ir = await call('POST', '/icypeas/email-search', {
+        firstname: p.first_name, lastname: p.last_name, domainOrCompany: p.domain,
+      })
+      return { id: p.id, status: ir.status, ms: ir.ms, data: ir.data }
+    }),
+  )
+  for (const f of icyResults) {
+    console.log(`  ${f.id}: status=${f.status} ms=${f.ms} → ${shortJson(f.data, 200)}`)
+  }
+
+  header('Done')
+}
+
+main().catch((err) => {
+  console.error('FATAL:', err)
+  process.exit(1)
+})

package/tests/registry-find-people.test.ts

@@ -430,6 +430,77 @@ describe('leadsfactory (find_people)', () => {
     })
   })
 
+  it('locations are forwarded as ISO country_codes pairs', () => {
+    const result = p().mapParams({
+      company_domains: ['wework.com'],
+      job_titles: ['CEO'],
+      locations: ['BR', 'US'],
+      limit: 10,
+    })
+    const search = (result.body as Record<string, unknown>).search as Record<string, unknown>
+    expect(search.country_codes).toEqual([
+      { code: 'BR', name: 'Brazil' },
+      { code: 'US', name: 'United States' },
+    ])
+  })
+
+  it('country names are coerced to ISO-2 (agents commonly pass "Brazil" instead of "BR")', () => {
+    const result = p().mapParams({
+      company_domains: ['wework.com'],
+      job_titles: ['CEO'],
+      locations: ['Brazil', 'United States'],
+      limit: 10,
+    })
+    const search = (result.body as Record<string, unknown>).search as Record<string, unknown>
+    expect(search.country_codes).toEqual([
+      { code: 'BR', name: 'Brazil' },
+      { code: 'US', name: 'United States' },
+    ])
+  })
+
+  it('common aliases (USA, UK) and case-insensitive names are coerced', () => {
+    const result = p().mapParams({
+      company_domains: ['x.com'],
+      job_titles: ['CEO'],
+      locations: ['usa', 'UK', 'south korea'],
+      limit: 5,
+    })
+    const search = (result.body as Record<string, unknown>).search as Record<string, unknown>
+    expect(search.country_codes).toEqual([
+      { code: 'US', name: 'United States' },
+      { code: 'GB', name: 'United Kingdom' },
+      { code: 'KR', name: 'South Korea' },
+    ])
+  })
+
+  it('unrecognized location strings are dropped rather than forwarded as garbage', () => {
+    const result = p().mapParams({
+      company_domains: ['x.com'],
+      job_titles: ['CEO'],
+      locations: ['Atlantis', 'BR'],
+      limit: 5,
+    })
+    const search = (result.body as Record<string, unknown>).search as Record<string, unknown>
+    expect(search.country_codes).toEqual([{ code: 'BR', name: 'Brazil' }])
+  })
+
+  it('country_codes is omitted when locations is not provided', () => {
+    const result = p().mapParams({ company_domains: ['coldiq.com'], job_titles: ['CEO'], limit: 5 })
+    const search = (result.body as Record<string, unknown>).search as Record<string, unknown>
+    expect(search.country_codes).toBeUndefined()
+  })
+
+  it('country_codes is omitted when locations is provided but no value coerces (all unrecognized)', () => {
+    const result = p().mapParams({
+      company_domains: ['x.com'],
+      job_titles: ['CEO'],
+      locations: ['Atlantis', 'Narnia'],
+      limit: 5,
+    })
+    const search = (result.body as Record<string, unknown>).search as Record<string, unknown>
+    expect(search.country_codes).toBeUndefined()
+  })
+
   it('seniorities and keywords are not forwarded', () => {
     const result = p().mapParams({
       company_domains: ['coldiq.com'],
@@ -442,6 +513,46 @@ describe('leadsfactory (find_people)', () => {
     expect(body.seniorities).toBeUndefined()
     expect(body.keywords).toBeUndefined()
   })
+
+  it('hasResult: true when companies_personas is non-empty', () => {
+    expect(p().hasResult({ companies_personas: [{ company: 'ColdIQ' }] })).toBe(true)
+  })
+
+  it('hasResult: false when companies_personas is empty array', () => {
+    expect(p().hasResult({ companies_personas: [] })).toBe(false)
+  })
+
+  it('hasResult: true when SUCCESSFUL + nb_jobs_complete > 0 (no companies_personas in response)', () => {
+    expect(p().hasResult({ status: 'SUCCESSFUL', nb_jobs_complete: 3 })).toBe(true)
+  })
+
+  it('hasResult: false when SUCCESSFUL + nb_jobs_complete is null (no results)', () => {
+    expect(p().hasResult({ status: 'SUCCESSFUL', nb_jobs_complete: null })).toBe(false)
+  })
+
+  it('hasResult: false when SUCCESSFUL + nb_jobs_complete is 0', () => {
+    expect(p().hasResult({ status: 'SUCCESSFUL', nb_jobs_complete: 0 })).toBe(false)
+  })
+
+  it('isComplete: true for SUCCESSFUL', () => {
+    expect(p().async!.isComplete({ status: 'SUCCESSFUL' })).toBe(true)
+  })
+
+  it('isComplete: true for FAILED', () => {
+    expect(p().async!.isComplete({ status: 'FAILED' })).toBe(true)
+  })
+
+  it('isComplete: true for INVALID_URL (terminal error state)', () => {
+    expect(p().async!.isComplete({ status: 'INVALID_URL' })).toBe(true)
+  })
+
+  it('isComplete: false for RUNNING', () => {
+    expect(p().async!.isComplete({ status: 'RUNNING' })).toBe(false)
+  })
+
+  it('isComplete: false for PAUSED', () => {
+    expect(p().async!.isComplete({ status: 'PAUSED' })).toBe(false)
+  })
 })
 
 // ---------------------------------------------------------------------------

package/tests/registry.test.ts

@@ -48,7 +48,7 @@ describe('registry', () => {
   })
 
   describe('search_companies mapParams', () => {
-    it('CompanyEnrich maps correctly and folds industries into keywords', () => {
+    it('CompanyEnrich routes keywords + industries into the `query` full-text field (not the tag-filter `keywords` field)', () => {
       const providers = getProviders('search_companies')
       const ce = providers.find((p) => p.id === 'companyenrich')!
       const result = ce.mapParams({
@@ -59,13 +59,30 @@ describe('registry', () => {
         max_employees: 200,
         limit: 25,
       })
-      expect(result.body).toEqual({
-        keywords: ['SaaS', 'Software'],
-        countries: ['US'],
-        employees: [{ from: 10, to: 200 }],
-        foundedYear: undefined,
-        pageSize: 25,
-      })
+      const body = result.body as Record<string, unknown>
+      expect(body.query).toBe('SaaS Software')
+      expect(body.keywords).toBeUndefined()
+      expect(body.countries).toEqual(['US'])
+      expect(body.employees).toEqual([{ from: 10, to: 200 }])
+      expect(body.pageSize).toBe(25)
+    })
+
+    it('CompanyEnrich brand-name keyword goes to `query` (the WeWork regression)', () => {
+      const providers = getProviders('search_companies')
+      const ce = providers.find((p) => p.id === 'companyenrich')!
+      const result = ce.mapParams({ keywords: ['wework'], limit: 5 })
+      const body = result.body as Record<string, unknown>
+      expect(body.query).toBe('wework')
+      expect(body.keywords).toBeUndefined()
+    })
+
+    it('CompanyEnrich omits `query` when no keywords/industries provided', () => {
+      const providers = getProviders('search_companies')
+      const ce = providers.find((p) => p.id === 'companyenrich')!
+      const result = ce.mapParams({ countries: ['US'], limit: 5 })
+      const body = result.body as Record<string, unknown>
+      expect(body.query).toBeUndefined()
+      expect(body.keywords).toBeUndefined()
     })
 
     it('Apollo maps correctly, translating ISO country codes to English names', () => {
@@ -1255,7 +1272,7 @@ describe('registry', () => {
       })
       expect(result.body).toEqual({
         countries: ['US'],
-        keywords: ['SaaS'],
+        query: 'SaaS',
         technologies: ['Salesforce', 'HubSpot'],
         employees: undefined,
         foundedYear: undefined,

package/tests/tools/find-emails.test.ts

@@ -454,4 +454,57 @@ describe('find_emails handler — resilience', () => {
     expect(parsed.data.found).toBe(1)
     expect(parsed.data.results[0]).toMatchObject({ id: 'p1', email: 'alice@example.com', provider: 'findymail' })
   })
+
+  it('falls back to single find_email waterfall when bulk providers all miss (covers limadata/blitzapi/linkupapi gap)', async () => {
+    // Bulk path: Prospeo + FullEnrich + Findymail + Icypeas all miss.
+    // Single-only providers (limadata-work-email, blitzapi, limadata-work-email-linkedin, linkupapi)
+    // should be tried; blitzapi finds the email.
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const u = url.toString()
+      if (u.includes('/prospeo/bulk-enrich-person')) {
+        return new Response(
+          JSON.stringify({ error: false, results: [{ identifier: 'p1', error: true, person: null }], total_cost: 0 }),
+          { status: 200 },
+        )
+      }
+      if (u.includes('/fullenrich/contact/enrich/bulk')) {
+        // No enrichment_id returned → fullEnrichStep exits early without polling
+        return new Response(JSON.stringify({}), { status: 200 })
+      }
+      if (u.includes('/findymail/search/name')) {
+        return new Response(JSON.stringify({ email: null }), { status: 200 })
+      }
+      if (u.includes('/icypeas/email-search')) {
+        return new Response(JSON.stringify({ email: null }), { status: 200 })
+      }
+      // Single-only providers — limadata first (per priority), then blitzapi.
+      if (u.includes('/coldiq/find/work-email-linkedin')) {
+        return new Response(JSON.stringify({ email: null }), { status: 200 })
+      }
+      if (u.includes('/coldiq/find/work-email')) {
+        return new Response(JSON.stringify({ email: null }), { status: 200 })
+      }
+      if (u.includes('/blitzapi/enrichment/find-work-email')) {
+        return new Response(JSON.stringify({ email: 'alice@example.com' }), { status: 200 })
+      }
+      if (u.includes('/linkupapi/data/mail/finder')) {
+        return new Response(JSON.stringify({ email: null }), { status: 200 })
+      }
+      return new Response(JSON.stringify({ error: 'unexpected', url: u }), { status: 500 })
+    }) as typeof fetch
+
+    const result = await findEmailsHandler({
+      people: [{
+        id: 'p1',
+        first_name: 'Alice',
+        last_name: 'Smith',
+        domain: 'example.com',
+        linkedin_url: 'https://linkedin.com/in/alice',
+      }],
+    })
+
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed.data.found).toBe(1)
+    expect(parsed.data.results[0]).toMatchObject({ id: 'p1', email: 'alice@example.com', provider: 'blitzapi' })
+  })
 })