@coldiq/mcp 0.1.19 → 0.2.5

package/src/utils/compact-people.ts

@@ -0,0 +1,323 @@
+// 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} }`
+//   - Prospeo wraps in `{ person: {...person fields including current_job_title}, ... }`
+//   - 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>)
+  }
+  if (r.person && typeof r.person === 'object' && !Array.isArray(r.person)) {
+    Object.assign(merged, r.person 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',
+    'current_job_title',
+    '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

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/registry-find-people.test.ts

@@ -115,10 +115,10 @@ describe('prospeo-search-person', () => {
     })).toEqual({
       body: {
         filters: {
-          job_title: { include: ['CEO', 'CTO'] },
+          person_job_title: { include: ['CEO', 'CTO'] },
           person_seniority: { include: ['C-Level'] },
           company: { websites: { include: ['coldiq.com'] } },
-          person_location: { include: ['Belgium'] },
+          person_location_search: { include: ['Belgium'] },
         },
       },
     })
@@ -129,21 +129,25 @@ describe('prospeo-search-person', () => {
     const filters = (result.body as Record<string, unknown>).filters as Record<string, unknown>
     expect(filters.person_seniority).toBeUndefined()
     expect(filters.company).toBeUndefined()
-    expect(filters.person_location).toBeUndefined()
+    expect(filters.person_location_search).toBeUndefined()
   })
 
-  it('hasResult: true when data array non-empty', () => {
-    expect(p().hasResult({ data: [{ name: 'Michel Lieben' }] })).toBe(true)
+  it('hasResult: true when results array non-empty', () => {
+    expect(p().hasResult({ results: [{ person: { full_name: 'Michel Lieben' } }] })).toBe(true)
   })
 
-  it('hasResult: false when data is empty', () => {
-    expect(p().hasResult({ data: [] })).toBe(false)
+  it('hasResult: false when results is empty', () => {
+    expect(p().hasResult({ results: [] })).toBe(false)
   })
 
   it('hasResult: false on empty object', () => {
     expect(p().hasResult({})).toBe(false)
   })
 
+  it('hasResult: false when only legacy data field is present (real upstream uses results)', () => {
+    expect(p().hasResult({ data: [{ name: 'Stale' }] })).toBe(false)
+  })
+
   it('priority is 7', () => {
     expect(p().priority).toBe(7)
   })
@@ -364,6 +368,18 @@ describe('apollo (find_people)', () => {
     expect(body.q_keywords).toBe('growth AI')
   })
 
+  it('mapParams clamps per_page to 100 when limit exceeds Apollo upstream cap', () => {
+    const result = p().mapParams({ job_titles: ['CEO'], limit: 150 })
+    const body = result.body as Record<string, unknown>
+    expect(body.per_page).toBe(100)
+  })
+
+  it('mapParams passes through per_page when limit is at or below 100', () => {
+    const result = p().mapParams({ job_titles: ['CEO'], limit: 50 })
+    const body = result.body as Record<string, unknown>
+    expect(body.per_page).toBe(50)
+  })
+
   it('mapParams omits q_keywords when keywords absent', () => {
     const result = p().mapParams({ job_titles: ['CEO'], limit: 10 })
     const body = result.body as Record<string, unknown>
@@ -466,6 +482,22 @@ describe('leadsfactory (find_people)', () => {
   const personas = (result: ReturnType<ReturnType<typeof p>['mapParams']>) =>
     ((result.body as Record<string, unknown>).search as Record<string, unknown>).personas as { job_title: string }[]
 
+  it('isApplicable: true with company_domains', () => {
+    expect(p().isApplicable!({ company_domains: ['coldiq.com'], job_titles: ['CEO'] })).toBe(true)
+  })
+
+  it('isApplicable: true with company_linkedin_urls', () => {
+    expect(p().isApplicable!({ company_linkedin_urls: ['https://www.linkedin.com/company/coldiq'], job_titles: ['CEO'] })).toBe(true)
+  })
+
+  it('isApplicable: false without any company identifier (LF upstream 500s on pure prospecting)', () => {
+    expect(p().isApplicable!({ job_titles: ['CEO'], seniorities: ['C-Level'], locations: ['FR'] })).toBe(false)
+  })
+
+  it('isApplicable: false on empty input', () => {
+    expect(p().isApplicable!({})).toBe(false)
+  })
+
   it('same-domain variants collapse to 1 persona with comma-joined titles', () => {
     const result = p().mapParams({ company_domains: ['coldiq.com'], job_titles: ['VP Sales', 'Head of Sales'], limit: 5 })
     expect(personas(result)).toEqual([{ job_title: 'VP Sales, Head of Sales' }])

package/tests/registry-search-companies.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest'
-import { getProviders } from '../src/registry.js'
+import { getProviders, prospeoHeadcountBuckets } from '../src/registry.js'
 
 const providers = () => getProviders('search_companies')
 const get = (id: string) => {
@@ -43,8 +43,8 @@ describe('prospeo-search-company', () => {
         filters: {
           company_keywords: { include: ['sales engagement'] },
           company_industry: { include: ['SaaS'] },
-          company_country: { include: ['Belgium'] },
-          company_headcount_custom: { min: 10, max: 200 },
+          company_location_search: { include: ['Belgium'] },
+          company_headcount_range: ['1-10', '11-20', '21-50', '51-100', '101-200'],
         },
       },
     })
@@ -54,14 +54,17 @@ describe('prospeo-search-company', () => {
     const result = p().mapParams({ keywords: ['outbound'] })
     const filters = (result.body as Record<string, unknown>).filters as Record<string, unknown>
     expect(filters.company_industry).toBeUndefined()
-    expect(filters.company_country).toBeUndefined()
-    expect(filters.company_headcount_custom).toBeUndefined()
+    expect(filters.company_location_search).toBeUndefined()
+    expect(filters.company_headcount_range).toBeUndefined()
   })
 
-  it('mapParams includes headcount when only min is given', () => {
+  it('mapParams includes headcount buckets when only min is given', () => {
     const result = p().mapParams({ keywords: ['crm'], min_employees: 50 })
     const filters = (result.body as Record<string, unknown>).filters as Record<string, unknown>
-    expect(filters.company_headcount_custom).toEqual({ min: 50, max: undefined })
+    expect(filters.company_headcount_range).toEqual([
+      '21-50', '51-100', '101-200', '201-500', '501-1000',
+      '1001-2000', '2001-5000', '5001-10000', '10000+',
+    ])
   })
 
   it('hasResult: true when data array non-empty', () => {
@@ -250,6 +253,42 @@ describe('theirstack search_companies', () => {
   })
 })
 
+// ---------------------------------------------------------------------------
+// prospeoHeadcountBuckets — maps numeric range to Prospeo's fixed buckets
+// ---------------------------------------------------------------------------
+
+describe('prospeoHeadcountBuckets', () => {
+  it('returns all overlapping buckets for a finite range', () => {
+    expect(prospeoHeadcountBuckets(10, 500)).toEqual([
+      '1-10', '11-20', '21-50', '51-100', '101-200', '201-500',
+    ])
+  })
+
+  it('treats undefined min as 0 (open lower bound)', () => {
+    expect(prospeoHeadcountBuckets(undefined, 50)).toEqual(['1-10', '11-20', '21-50'])
+  })
+
+  it('treats undefined max as +Infinity (open upper bound)', () => {
+    expect(prospeoHeadcountBuckets(2001, undefined)).toEqual([
+      '2001-5000', '5001-10000', '10000+',
+    ])
+  })
+
+  it('returns single bucket when min === max within a bucket', () => {
+    expect(prospeoHeadcountBuckets(75, 75)).toEqual(['51-100'])
+  })
+
+  it('includes 10000+ when min is above 10000', () => {
+    expect(prospeoHeadcountBuckets(15000, undefined)).toEqual(['10000+'])
+  })
+
+  it('excludes 10000+ when max is exactly 10000', () => {
+    const buckets = prospeoHeadcountBuckets(5001, 10000)
+    expect(buckets).toEqual(['5001-10000'])
+    expect(buckets).not.toContain('10000+')
+  })
+})
+
 // ---------------------------------------------------------------------------
 // Ordering: search_companies providers sorted correctly
 // ---------------------------------------------------------------------------