@coldiq/mcp 0.1.18 → 0.2.4

package/src/utils/compact-people.ts

@@ -0,0 +1,318 @@
+// Normalize find_people responses into a small, predictable shape.
+//
+// The find_people waterfall fans across 10 providers, each with a different
+// payload shape (data.people[], data.data[], data.companies_personas[].personas[][],
+// data.data.profiles[], data.content[], etc.). Verbose passthrough produces 30KB+
+// per record from FullEnrich alone (full employment history, every company office,
+// company description, specialties, skills, languages). Compact mode keeps only
+// the fields agents actually need to act on a lead.
+
+export interface CompactPerson {
+  full_name?: string
+  first_name?: string
+  last_name?: string
+  title?: string
+  seniority?: string
+  linkedin_url?: string
+  email?: string
+  company_name?: string
+  company_domain?: string
+  company_linkedin_url?: string
+  company_headcount?: number | string
+  location?: string
+}
+
+function getPath(obj: unknown, path: string): unknown {
+  if (obj == null) return undefined
+  let cur: unknown = obj
+  for (const part of path.split('.')) {
+    if (cur == null) return undefined
+    if (Array.isArray(cur)) {
+      const idx = Number(part)
+      if (!Number.isInteger(idx)) return undefined
+      cur = cur[idx]
+    } else if (typeof cur === 'object') {
+      cur = (cur as Record<string, unknown>)[part]
+    } else {
+      return undefined
+    }
+  }
+  return cur
+}
+
+function pick(obj: unknown, paths: string[]): unknown {
+  for (const p of paths) {
+    const v = getPath(obj, p)
+    if (v !== undefined && v !== null && v !== '') return v
+  }
+  return undefined
+}
+
+function asString(v: unknown): string | undefined {
+  if (typeof v === 'string') return v.length > 0 ? v : undefined
+  if (typeof v === 'number') return String(v)
+  return undefined
+}
+
+function flattenDeep(arr: unknown[]): unknown[] {
+  const out: unknown[] = []
+  for (const item of arr) {
+    if (Array.isArray(item)) out.push(...flattenDeep(item))
+    else out.push(item)
+  }
+  return out
+}
+
+// Wrapper-aware extraction. Providers that wrap people in atypical shapes get
+// explicit handling; the rest fall through to common-key probing.
+export function extractPeopleArray(data: unknown, providerId: string): unknown[] {
+  if (data == null) return []
+  if (Array.isArray(data)) return data
+  if (typeof data !== 'object') return []
+  const d = data as Record<string, unknown>
+
+  // LeadsFactory: companies_personas[i].personas is unknown[][] — nested arrays
+  // of personas per company. Flatten to a single contacts array.
+  if (providerId === 'leadsfactory' && Array.isArray(d.companies_personas)) {
+    const out: unknown[] = []
+    for (const group of d.companies_personas as Array<Record<string, unknown>>) {
+      const personas = group.personas
+      if (Array.isArray(personas)) out.push(...flattenDeep(personas))
+    }
+    return out
+  }
+
+  // LinkUp wraps results under data.profiles.
+  if (providerId === 'linkupapi-search-profiles') {
+    const inner = d.data
+    if (inner && typeof inner === 'object') {
+      const profiles = (inner as Record<string, unknown>).profiles
+      if (Array.isArray(profiles)) return profiles
+    }
+    return []
+  }
+
+  for (const key of ['people', 'data', 'results', 'contacts', 'content', 'profiles', 'items']) {
+    const v = d[key]
+    if (Array.isArray(v)) return v
+  }
+  return []
+}
+
+// Providers nest person fields at different depths:
+//   - LeadsFactory wraps in `{ contact: {...person}, company: {...}, persona_index, ... }`
+//   - AI-Ark wraps in `{ id, profile: {...person} }`
+//   - Apollo / PDL / FullEnrich keep person fields at the top level
+// Merging the nested objects into the outer scope lets the candidate-path resolver
+// find person fields regardless of provider. The sibling `company` on LeadsFactory
+// stays at the merged top level so `company.name`, `company.domain` paths resolve.
+function unwrapRecord(record: unknown): Record<string, unknown> | null {
+  if (!record || typeof record !== 'object' || Array.isArray(record)) return null
+  const r = record as Record<string, unknown>
+  const merged: Record<string, unknown> = { ...r }
+  if (r.profile && typeof r.profile === 'object' && !Array.isArray(r.profile)) {
+    Object.assign(merged, r.profile as Record<string, unknown>)
+  }
+  if (r.contact && typeof r.contact === 'object' && !Array.isArray(r.contact)) {
+    Object.assign(merged, r.contact as Record<string, unknown>)
+  }
+  return merged
+}
+
+// Confirm a candidate value really points at LinkedIn before surfacing it as
+// linkedin_url. Some providers (Sumble) keep their own profile URL under a bare
+// `url` key — without this guard, agents pasting linkedin_url into LinkedIn
+// lookups would silently fail. Accept linkedin domains and short canonical forms
+// PDL stores (`linkedin.com/in/x`, no protocol).
+function isLinkedInUrl(v: unknown): v is string {
+  if (typeof v !== 'string' || v.length === 0) return false
+  const lower = v.toLowerCase()
+  return lower.includes('linkedin.com/')
+}
+
+function pickLinkedIn(obj: unknown, paths: string[]): string | undefined {
+  for (const p of paths) {
+    const v = getPath(obj, p)
+    if (isLinkedInUrl(v)) return v
+  }
+  return undefined
+}
+
+export function normalizePerson(record: unknown): CompactPerson | null {
+  const r = unwrapRecord(record)
+  if (!r) return null
+
+  const out: CompactPerson = {}
+
+  const fullName = asString(pick(r, ['full_name', 'fullName', 'name', 'displayName']))
+  const firstName = asString(pick(r, ['first_name', 'firstName', 'given_name']))
+  const lastName = asString(pick(r, ['last_name', 'lastName', 'family_name', 'surname']))
+  if (fullName) out.full_name = fullName
+  if (firstName) out.first_name = firstName
+  if (lastName) out.last_name = lastName
+  if (!out.full_name && (firstName || lastName)) {
+    out.full_name = [firstName, lastName].filter(Boolean).join(' ')
+  }
+
+  const title = asString(pick(r, [
+    'employment.current.title',
+    'title',
+    'job_title',
+    'jobTitle',
+    'position',
+    'current_position.title',
+    'current_position',
+    'headline',
+  ]))
+  if (title) out.title = title
+
+  const seniorityRaw = pick(r, [
+    'employment.current.seniority',
+    'seniority',
+    'job_title_levels.0',
+    'job_level',  // Sumble
+    'level',
+  ])
+  const seniority = asString(seniorityRaw)
+  if (seniority) out.seniority = seniority
+
+  // LinkedIn URL is the one field worth strict-validating: a wrong value here
+  // silently breaks downstream LinkedIn-driven flows. `url`/`profile_url`/`linkedin`
+  // are too ambiguous to trust without the linkedin.com substring check.
+  const linkedin = pickLinkedIn(r, [
+    'linkedin_url',
+    'linkedinUrl',
+    'social_profiles.professional_network.url',
+    'social_profiles.linkedin.url',
+    'profile_url',
+    'linkedin',
+    'url',
+  ])
+  if (linkedin) out.linkedin_url = linkedin
+
+  const email = asString(pick(r, [
+    'email',
+    'work_email',
+    'personal_email',
+    'best_email',
+    'emails.0',
+    'contact.email',
+    'contact.emails.0',
+  ]))
+  if (email) out.email = email
+
+  const country = asString(pick(r, [
+    'location.country',
+    'country',
+    'location_country',
+    'job_company_location_country',
+  ]))
+  const city = asString(pick(r, [
+    'location.city',
+    'city',
+    'location_locality',
+    'job_company_location_locality',
+  ]))
+  const locationCombined = [city, country].filter(Boolean).join(', ')
+  if (locationCombined) out.location = locationCombined
+
+  const companyName = asString(pick(r, [
+    'employment.current.company.name',
+    'organization.name',
+    'company.name',
+    'job_company_name',
+    'current_company.name',
+    'companyName',
+  ]))
+  if (companyName) out.company_name = companyName
+
+  const companyDomain = asString(pick(r, [
+    'employment.current.company.domain',
+    'organization.primary_domain',
+    'organization.website_url',
+    'company.domain',
+    'company.website',
+    'job_company_website',
+  ]))
+  if (companyDomain) out.company_domain = companyDomain
+
+  const companyLinkedIn = asString(pick(r, [
+    'employment.current.company.social_profiles.professional_network.url',
+    'employment.current.company.social_profiles.linkedin.url',
+    'employment.current.company.linkedin_url',
+    'organization.linkedin_url',
+    'company.linkedin_url',
+    'job_company_linkedin_url',
+  ]))
+  if (companyLinkedIn) out.company_linkedin_url = companyLinkedIn
+
+  const headcountRaw = pick(r, [
+    'employment.current.company.headcount',
+    'employment.current.company.headcount_range',
+    'organization.estimated_num_employees',
+    'organization.num_employees',
+    'company.headcount',
+    'company.size',
+    'job_company_size',
+    'job_company_employee_count',
+  ])
+  if (typeof headcountRaw === 'number' || (typeof headcountRaw === 'string' && headcountRaw.length > 0)) {
+    out.company_headcount = headcountRaw
+  }
+
+  // Drop records that resolved to nothing meaningful.
+  if (Object.keys(out).length === 0) return null
+  return out
+}
+
+export interface CompactPayload {
+  people: CompactPerson[]
+  total?: number
+  gap_fill_provider?: string
+  revealed?: true
+}
+
+export function compactPayload(data: unknown, providerId: string): CompactPayload {
+  const mainArr = extractPeopleArray(data, providerId)
+  const main: CompactPerson[] = []
+  for (const r of mainArr) {
+    const p = normalizePerson(r)
+    if (p) main.push(p)
+  }
+
+  let gapFillProvider: string | undefined
+  let gapFillPeople: CompactPerson[] = []
+  if (data && typeof data === 'object' && !Array.isArray(data)) {
+    const gf = (data as Record<string, unknown>).gap_fill
+    if (gf && typeof gf === 'object') {
+      gapFillProvider = asString((gf as Record<string, unknown>).provider)
+      const gfArr = extractPeopleArray(gf, gapFillProvider ?? '')
+      for (const r of gfArr) {
+        const p = normalizePerson(r)
+        if (p) gapFillPeople.push(p)
+      }
+    }
+  }
+
+  // Pull pagination total when present (FullEnrich exposes data.metadata.total).
+  let total: number | undefined
+  if (data && typeof data === 'object' && !Array.isArray(data)) {
+    const meta = (data as Record<string, unknown>).metadata
+    if (meta && typeof meta === 'object') {
+      const t = (meta as Record<string, unknown>).total
+      if (typeof t === 'number') total = t
+    }
+  }
+
+  const out: CompactPayload = { people: [...main, ...gapFillPeople] }
+  if (total !== undefined) out.total = total
+  if (gapFillProvider && gapFillPeople.length > 0) out.gap_fill_provider = gapFillProvider
+  // Preserve the revealed flag the Apollo reveal flow sets — it tells the caller
+  // whether the emails/full names in `people` came from /apollo/people/bulk-match
+  // (paid +1 credit per person) vs the obfuscated /apollo/people/search response.
+  if (data && typeof data === 'object' && !Array.isArray(data) &&
+      (data as Record<string, unknown>).revealed === true) {
+    out.revealed = true
+  }
+  return out
+}

package/src/utils/provider-resolver.ts

@@ -4,7 +4,18 @@ import { fuzzyMatch } from './fuzzy.js'
 
 // find_emails uses a custom waterfall — its providers are not in the registry.
 // Exported so find-emails.ts stays in sync without a second hardcoded list.
-export const FIND_EMAILS_PROVIDERS = ['prospeo', 'fullenrich', 'findymail', 'icypeas']
+// Order = auto-route execution order: bulk providers first (Steps 1-3), then
+// the single-find_email fallback providers used for stragglers (Step 4).
+export const FIND_EMAILS_PROVIDERS = [
+  'prospeo',
+  'fullenrich',
+  'findymail',
+  'icypeas',
+  'limadata-work-email',
+  'blitzapi',
+  'limadata-work-email-linkedin',
+  'linkupapi',
+]
 
 export function getProvidersForCapability(capability: Capability | 'find_emails'): string[] {
   if (capability === 'find_emails') return FIND_EMAILS_PROVIDERS
@@ -198,6 +209,9 @@ const GATED_DESCRIPTIONS: Partial<Record<Capability, Partial<Record<string, Gate
     'prospeo-search-person': { kind: 'requires',         fields: 'job_titles or company_domains' },
     'ai-ark-people':         { kind: 'requires',         fields: 'job_titles, seniorities, or keywords' },
     'findymail-search-employees': { kind: 'requires',    fields: 'company_domains and job_titles' },
+    'fullenrich-people-search': { kind: 'requires',      fields: 'company_domains (upstream does not accept LinkedIn URL filters)' },
+    pdl:                     { kind: 'requires',         fields: 'company_domains, company_linkedin_urls, job_titles, or seniorities' },
+    companyenrich:           { kind: 'incompatible_with', fields: 'company_linkedin_urls without company_domains (upstream supports domain filters only)' },
   },
   // -------------------------------------------------------------------------
   find_email: {

package/tests/executor.test.ts

@@ -734,6 +734,56 @@ describe('executeWithFallback with options.providers', () => {
       expect(result._meta.matchedFrom).toEqual({ prospec: 'prospeo' })
     }
   })
+
+  it('surfaces credits_charged + credits_remaining in success _meta when API emits credit headers', async () => {
+    stubProviders([
+      makeProvider({ id: 'prospeo', priority: 1, hasResult: () => true }),
+    ])
+
+    globalThis.fetch = vi.fn(async () =>
+      new Response(JSON.stringify({ ok: true }), {
+        status: 200,
+        headers: {
+          'X-ColdIQ-Credits-Charged': '3',
+          'X-ColdIQ-Credits-Remaining': '197',
+        },
+      })
+    ) as typeof fetch
+
+    const result = await executeWithFallback(
+      'enrich_company',
+      { domain: 'coldiq.com' },
+      { providers: ['prospeo'] },
+    )
+
+    expect('data' in result).toBe(true)
+    if ('data' in result) {
+      expect(result._meta.credits_charged).toBe(3)
+      expect(result._meta.credits_remaining).toBe(197)
+    }
+  })
+
+  it('omits credit fields from _meta when API does not emit credit headers', async () => {
+    stubProviders([
+      makeProvider({ id: 'prospeo', priority: 1, hasResult: () => true }),
+    ])
+
+    globalThis.fetch = vi.fn(async () =>
+      new Response(JSON.stringify({ ok: true }), { status: 200 })
+    ) as typeof fetch
+
+    const result = await executeWithFallback(
+      'enrich_company',
+      { domain: 'coldiq.com' },
+      { providers: ['prospeo'] },
+    )
+
+    expect('data' in result).toBe(true)
+    if ('data' in result) {
+      expect(result._meta.credits_charged).toBeUndefined()
+      expect(result._meta.credits_remaining).toBeUndefined()
+    }
+  })
 })
 
 // Note: the LeadsFactory backoff *schedule* itself is asserted against the live
@@ -789,3 +839,118 @@ describe('per-provider sync timeout cap', () => {
     expect(elapsed).toBeLessThan(2000)
   })
 })
+
+// ---------------------------------------------------------------------------
+// upstream_error — structured upstream body survives the short-string flatten
+// ---------------------------------------------------------------------------
+
+describe('executor upstream_error propagation', () => {
+  const originalFetch = globalThis.fetch
+
+  beforeEach(() => {
+    initClient('http://test-api.local', 'test-key-123')
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+    vi.restoreAllMocks()
+  })
+
+  it('preserves API `details` passthrough verbatim under providers_tried[i].upstream_error', async () => {
+    stubProviders([makeProvider({ id: 'prospeo', hasResult: () => false })])
+
+    globalThis.fetch = vi.fn(async () =>
+      new Response(
+        JSON.stringify({
+          error: "INVALID_REQUEST: Invalid value '[CMO]' for filter 'job_titles'",
+          details: {
+            error_code: 'INVALID_REQUEST',
+            filter_error: "Invalid value '[CMO]' for filter 'job_titles'",
+          },
+        }),
+        { status: 400 },
+      ),
+    ) as typeof fetch
+
+    const result = await executeWithFallback('find_people', { company_domains: ['coldiq.com'] })
+
+    expect('error' in result).toBe(true)
+    if ('error' in result) {
+      expect(result.providers_tried).toHaveLength(1)
+      const tried = result.providers_tried[0]
+      expect(tried.status).toBe(400)
+      expect(tried.error).toContain('INVALID_REQUEST')
+      expect(tried.upstream_error).toEqual({
+        error_code: 'INVALID_REQUEST',
+        filter_error: "Invalid value '[CMO]' for filter 'job_titles'",
+      })
+    }
+  })
+
+  it('falls back to the full body when API has no `details` field', async () => {
+    stubProviders([makeProvider({ id: 'unmigrated', hasResult: () => false })])
+
+    globalThis.fetch = vi.fn(async () =>
+      new Response(
+        JSON.stringify({ error: true, error_code: 'X', filter_error: 'whatever' }),
+        { status: 400 },
+      ),
+    ) as typeof fetch
+
+    const result = await executeWithFallback('find_people', { company_domains: ['coldiq.com'] })
+
+    expect('error' in result).toBe(true)
+    if ('error' in result) {
+      const tried = result.providers_tried[0]
+      // The short `error` string is the JSON-stringified boolean (the old behavior),
+      // but the structured body now rides along under `upstream_error` so the
+      // caller can still recover the detail.
+      expect(tried.error).toBe('true')
+      expect(tried.upstream_error).toMatchObject({
+        error_code: 'X',
+        filter_error: 'whatever',
+      })
+    }
+  })
+
+  it('defensively caps oversized upstream_error payloads to a 2KB string', async () => {
+    stubProviders([makeProvider({ id: 'noisy', hasResult: () => false })])
+
+    const huge = 'x'.repeat(5000)
+    globalThis.fetch = vi.fn(async () =>
+      new Response(
+        JSON.stringify({ error: 'bad', details: { blob: huge } }),
+        { status: 400 },
+      ),
+    ) as typeof fetch
+
+    const result = await executeWithFallback('find_people', { company_domains: ['coldiq.com'] })
+
+    expect('error' in result).toBe(true)
+    if ('error' in result) {
+      const upstream = result.providers_tried[0].upstream_error
+      expect(typeof upstream).toBe('string')
+      expect((upstream as string).length).toBeLessThanOrEqual(2048)
+    }
+  })
+
+  it('surfaces the synthetic non-JSON envelope as upstream_error', async () => {
+    stubProviders([makeProvider({ id: 'empty', hasResult: () => false })])
+
+    // No JSON body — client.ts synthesizes { error: 'Non-JSON response from API' },
+    // which has no `details` field so the executor falls back to the full envelope.
+    // Surfacing it (rather than dropping to undefined) keeps "upstream returned
+    // garbage" debuggable end-to-end.
+    globalThis.fetch = vi.fn(async () =>
+      new Response('not json', { status: 500 }),
+    ) as typeof fetch
+
+    const result = await executeWithFallback('find_people', { company_domains: ['coldiq.com'] })
+
+    expect('error' in result).toBe(true)
+    if ('error' in result) {
+      const tried = result.providers_tried[0]
+      expect(tried.upstream_error).toEqual({ error: 'Non-JSON response from API' })
+    }
+  })
+})

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

@@ -0,0 +1,55 @@
+// Direct upstream probe — documents what FullEnrich /people/search actually
+// honors as a company filter. The ColdIQ wrapper schema at
+// src/providers/fullenrich/schema.ts declares `current_company_linkedin_urls`,
+// but the live API rejects every shape with `error.filters.empty` (400). Only
+// `current_company_domains` and `current_company_names` actually scope results.
+//
+// This is why the registry mapper for `fullenrich-people-search` is gated
+// behind `company_domains` only — adding the LinkedIn URL field caused the
+// upstream to treat the request as filterless and return a 50k-result global
+// titles-only search, masquerading as company-scoped.
+//
+// Run:  FULLENRICH_API_KEY=… npx tsx mcp/tests/live/fullenrich-upstream-probe.ts
+
+const KEY = process.env.FULLENRICH_API_KEY
+if (!KEY) { console.error('FULLENRICH_API_KEY required'); process.exit(1) }
+const URL = 'https://app.fullenrich.com/api/v2/people/search'
+
+async function call(label: string, body: unknown) {
+  const t0 = Date.now()
+  const res = await fetch(URL, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  })
+  const data: any = await res.json().catch(async () => ({ raw: await res.text() }))
+  const total = data.metadata?.total
+  const ok = res.status === 200
+  console.log(`[${ok ? 'OK ' : 'ERR'}] ${label.padEnd(60)} status=${res.status} ms=${Date.now() - t0} total=${total ?? '-'} ${ok ? '' : 'err=' + JSON.stringify(data).slice(0, 120)}`)
+}
+
+async function main() {
+  console.log('=== FullEnrich /people/search filter compatibility probe ===\n')
+
+  console.log('▸ Known-working filters (should all return 200 with total > 0)')
+  await call('current_company_domains', { current_company_domains: [{ value: 'spendesk.com' }], limit: 1 })
+  await call('current_company_names', { current_company_names: [{ value: 'Spendesk' }], limit: 1 })
+
+  console.log('\n▸ LinkedIn URL variants (declared in ColdIQ schema, NOT honored upstream)')
+  for (const [field, value] of [
+    ['current_company_linkedin_urls', 'https://www.linkedin.com/company/spendesk'],
+    ['current_company_linkedin_url', 'https://www.linkedin.com/company/spendesk'],
+    ['current_company_linkedin_urls (short)', 'linkedin.com/company/spendesk'],
+    ['current_company_linkedin_urls (slug)', 'spendesk'],
+    ['current_company_linkedin_ids', 'spendesk'],
+  ] as const) {
+    const key = field.split(' ')[0]
+    await call(field, { [key]: [{ value }], limit: 1 })
+  }
+
+  console.log('\n▸ No-filter baseline (the buggy path: 50k+ titles-only results)')
+  await call('titles-only, no company', { current_position_titles: [{ value: 'CEO' }], limit: 1 })
+  await call('completely empty (sanity)', { limit: 1 })
+}
+
+main().catch((e) => { console.error('FATAL', e); process.exit(1) })

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

@@ -0,0 +1,83 @@
+// Direct upstream probe — verifies PDL's /person/search accepts
+// `job_company_linkedin_url` as a filterable term, and that the returned people
+// actually work at the company we asked for.
+//
+// PDL's Elasticsearch DSL is permissive: an unknown field name returns 0 hits
+// rather than an error, so a silent miss looks identical to "no data." The
+// probe compares a known-good baseline (job_company_website) against the
+// LinkedIn-URL variant.
+//
+// Run:  PDL_API_KEY=… npx tsx mcp/tests/live/pdl-upstream-probe.ts
+
+const KEY = process.env.PDL_API_KEY
+if (!KEY) { console.error('PDL_API_KEY required'); process.exit(1) }
+const BASE = 'https://api.peopledatalabs.com/v5'
+
+async function search(must: unknown[], size = 3) {
+  const t0 = Date.now()
+  const res = await fetch(`${BASE}/person/search`, {
+    method: 'POST',
+    headers: { 'X-API-Key': KEY!, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ query: { bool: { must } }, size }),
+    signal: AbortSignal.timeout(30_000),
+  })
+  let data: any
+  try { data = await res.json() } catch { data = await res.text() }
+  return { ok: res.ok, status: res.status, ms: Date.now() - t0, data }
+}
+
+function summarize(label: string, r: any) {
+  const data = r.data ?? {}
+  const total = data.total ?? '?'
+  const items = (data.data ?? []) as Array<any>
+  console.log(`\n[${label}] status=${r.status} ms=${r.ms} total=${total} returned=${items.length}`)
+  for (const p of items.slice(0, 5)) {
+    console.log(`  - ${p.full_name} | ${p.job_title} | co=${p.job_company_name} | website=${p.job_company_website} | li=${p.job_company_linkedin_url}`)
+  }
+}
+
+async function main() {
+  console.log('=== PDL upstream probe: verify job_company_linkedin_url ===')
+
+  // Use a well-known mid-sized B2B SaaS for the comparison. Aircall is a good fit:
+  // ~700 employees, indexed by both website and LinkedIn URL in PDL.
+  const TARGET_DOMAIN = 'aircall.io'
+  const TARGET_LINKEDIN = 'linkedin.com/company/aircall'
+
+  // Baseline: search by known-working field (job_company_website)
+  console.log(`\n▸ Baseline: search by job_company_website = ${TARGET_DOMAIN}`)
+  const byDomain = await search([{ terms: { job_company_website: [TARGET_DOMAIN] } }])
+  summarize('job_company_website', byDomain)
+
+  // Test: same search but by LinkedIn URL
+  console.log(`\n▸ Test: search by job_company_linkedin_url = ${TARGET_LINKEDIN}`)
+  const byLinkedIn = await search([{ terms: { job_company_linkedin_url: [TARGET_LINKEDIN] } }])
+  summarize('job_company_linkedin_url', byLinkedIn)
+
+  const baselineTotal = byDomain.data?.total ?? 0
+  const linkedinTotal = byLinkedIn.data?.total ?? 0
+
+  console.log(`\n=== Result ===`)
+  console.log(`baseline (by website):        total=${baselineTotal}`)
+  console.log(`test     (by linkedin_url):   total=${linkedinTotal}`)
+
+  if (linkedinTotal > 0 && baselineTotal > 0) {
+    const ratio = linkedinTotal / baselineTotal
+    console.log(`ratio = ${ratio.toFixed(2)} (1.0 = same company, both filters work)`)
+    if (ratio >= 0.5) {
+      console.log('✅ job_company_linkedin_url WORKS — keep the mapping in registry.ts')
+      process.exit(0)
+    } else {
+      console.log('⚠️  linkedin_url returns far fewer matches than website — investigate')
+      process.exit(2)
+    }
+  } else if (linkedinTotal === 0 && baselineTotal > 0) {
+    console.log('❌ job_company_linkedin_url silently returns 0 — REMOVE the mapping clause for pdl in registry.ts and keep gate-only')
+    process.exit(1)
+  } else {
+    console.log('⚠️  Baseline itself returned 0 — pick a different test company')
+    process.exit(2)
+  }
+}
+
+main().catch((e) => { console.error('FATAL', e); process.exit(1) })