@coldiq/mcp 0.1.19 → 0.2.4

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

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
 import { initClient } from '../../src/client.js'
-import { findEmailsHandler } from '../../src/tools/find-emails.js'
+import { findEmailsHandler, FIND_EMAILS_CHUNK_SIZE } from '../../src/tools/find-emails.js'
 
 describe('find_emails handler (bulk)', () => {
   const originalFetch = globalThis.fetch
@@ -399,6 +399,73 @@ describe('find_emails handler — use_providers', () => {
     expect(parsed.data.results[0]).toMatchObject({ provider: 'findymail', email: 'alice@example.com' })
     expect(icypeasCalled).toBe(false)
   })
+
+  it('pinning a single-only provider (limadata-work-email) routes through Step 4 and succeeds', async () => {
+    // Regression: previously FIND_EMAILS_PROVIDERS only listed the 4 bulk providers,
+    // so pinning a Step 4 provider was rejected as "unrecognized". Now all 8 are exposed.
+    let prospeoCalled = false
+    let limadataCalled = false
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const u = url.toString()
+      if (u.includes('/prospeo/bulk-enrich-person')) {
+        prospeoCalled = true
+        return new Response(JSON.stringify({ error: 'unexpected' }), { status: 500 })
+      }
+      if (u.includes('/coldiq/find/work-email')) {
+        limadataCalled = true
+        return new Response(JSON.stringify({ email: 'alice@example.com' }), { 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' }],
+      use_providers: ['limadata-work-email'],
+    })
+
+    expect(result.isError).toBeUndefined()
+    expect(prospeoCalled).toBe(false)
+    expect(limadataCalled).toBe(true)
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed.data.results[0]).toMatchObject({ provider: 'limadata-work-email', email: 'alice@example.com' })
+  })
+
+  it('all-failed error after pinning bulk-only providers surfaces single-only providers as remaining options', async () => {
+    // Regression: with only 4 providers exposed, after the user pinned all 4 bulk providers
+    // and they missed, available_providers was [] — falsely implying no more options existed.
+    // Now the error must point them at the single-only providers they could retry with.
+    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: [] }), { status: 200 })
+      }
+      if (u.includes('/fullenrich/contact/enrich/bulk')) {
+        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 })
+      }
+      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' }],
+      use_providers: ['prospeo', 'fullenrich', 'findymail', 'icypeas'],
+    })
+
+    expect(result.isError).toBe(true)
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed.available_providers).toEqual([
+      'limadata-work-email',
+      'blitzapi',
+      'limadata-work-email-linkedin',
+      'linkupapi',
+    ])
+    expect(parsed.error).toContain('limadata-work-email')
+  })
 })
 
 describe('find_emails handler — resilience', () => {
@@ -508,3 +575,202 @@ describe('find_emails handler — resilience', () => {
     expect(parsed.data.results[0]).toMatchObject({ id: 'p1', email: 'alice@example.com', provider: 'blitzapi' })
   })
 })
+
+describe('find_emails handler — chunking', () => {
+  const originalFetch = globalThis.fetch
+
+  beforeEach(() => {
+    initClient('http://test-api.local', 'test-key')
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  function makePeople(n: number): Array<{ id: string; first_name: string; last_name: string; domain: string }> {
+    return Array.from({ length: n }, (_, i) => ({
+      id: `p${i + 1}`,
+      first_name: `First${i + 1}`,
+      last_name: `Last${i + 1}`,
+      domain: 'example.com',
+    }))
+  }
+
+  it('splits 25 people into 3 chunks of ≤10 and issues one Prospeo bulk per chunk', async () => {
+    const bulkBodies: Array<{ data: Array<{ identifier: string }> }> = []
+
+    globalThis.fetch = vi.fn(async (url: string | URL | Request, init?: RequestInit) => {
+      const u = url.toString()
+      if (u.includes('/prospeo/bulk-enrich-person')) {
+        const body = JSON.parse(init!.body as string) as { data: Array<{ identifier: string }> }
+        bulkBodies.push(body)
+        return new Response(
+          JSON.stringify({
+            error: false,
+            results: body.data.map((d) => ({
+              identifier: d.identifier,
+              error: false,
+              person: { email: { email: `${d.identifier}@example.com` } },
+            })),
+            total_cost: body.data.length,
+          }),
+          { status: 200 },
+        )
+      }
+      return new Response(JSON.stringify({ error: 'unexpected' }), { status: 500 })
+    }) as typeof fetch
+
+    const result = await findEmailsHandler({ people: makePeople(25) })
+    const parsed = JSON.parse(result.content[0].text)
+
+    expect(bulkBodies.length).toBe(3)
+    expect(bulkBodies[0]!.data.length).toBeLessThanOrEqual(FIND_EMAILS_CHUNK_SIZE)
+    expect(bulkBodies[1]!.data.length).toBeLessThanOrEqual(FIND_EMAILS_CHUNK_SIZE)
+    expect(bulkBodies[2]!.data.length).toBeLessThanOrEqual(FIND_EMAILS_CHUNK_SIZE)
+    expect(bulkBodies.flatMap((b) => b.data.map((d) => d.identifier)).sort()).toEqual(
+      makePeople(25).map((p) => p.id).sort(),
+    )
+
+    expect(parsed.data.found).toBe(25)
+    expect(parsed.data.total).toBe(25)
+    expect(parsed._meta.batch_status).toBe('complete')
+    expect(parsed._meta.chunk_count).toBe(3)
+    expect(parsed._meta.chunk_size).toBe(FIND_EMAILS_CHUNK_SIZE)
+    expect(parsed._meta.providers.prospeo).toEqual({ attempted: 3, failed: 0 })
+    expect(result.isError).toBeUndefined()
+  })
+
+  it('one chunk Prospeo network failure → batch_status="partial" + isError absent when others succeed', async () => {
+    // First Prospeo bulk call simulates a network failure (status 0 via a fetch throw).
+    // Remaining chunks succeed. FindyMail picks up the failed chunk's misses.
+    let bulkCallCount = 0
+    globalThis.fetch = vi.fn(async (url: string | URL | Request, init?: RequestInit) => {
+      const u = url.toString()
+      if (u.includes('/prospeo/bulk-enrich-person')) {
+        bulkCallCount++
+        if (bulkCallCount === 1) {
+          // Simulate network failure → client returns { ok: false, status: 0 }
+          throw new Error('socket hang up')
+        }
+        const body = JSON.parse(init!.body as string) as { data: Array<{ identifier: string }> }
+        return new Response(
+          JSON.stringify({
+            error: false,
+            results: body.data.map((d) => ({
+              identifier: d.identifier,
+              error: false,
+              person: { email: { email: `${d.identifier}@example.com` } },
+            })),
+            total_cost: body.data.length,
+          }),
+          { status: 200 },
+        )
+      }
+      // FullEnrich create call for the failed chunk's misses — no enrichment_id so it bails fast.
+      if (u.includes('/fullenrich/contact/enrich/bulk')) {
+        return new Response(JSON.stringify({}), { status: 200 })
+      }
+      if (u.includes('/findymail/search/name')) {
+        return new Response(JSON.stringify({ email: 'recovered@example.com' }), { status: 200 })
+      }
+      return new Response(JSON.stringify({ error: 'unexpected' }), { status: 500 })
+    }) as typeof fetch
+
+    const result = await findEmailsHandler({ people: makePeople(25) })
+    const parsed = JSON.parse(result.content[0].text)
+
+    expect(parsed._meta.providers.prospeo.attempted).toBe(3)
+    expect(parsed._meta.providers.prospeo.failed).toBe(1)
+    expect(parsed._meta.batch_status).toBe('partial')
+    expect(parsed.data.found).toBeGreaterThan(0)
+    expect(result.isError).toBeUndefined()
+  })
+
+  it('every chunk fails → batch_status="failed" and isError:true even unconstrained', async () => {
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const u = url.toString()
+      if (u.includes('/prospeo/bulk-enrich-person')) {
+        // 502 → counted as a network-level failure
+        return new Response(JSON.stringify({ error: 'upstream down' }), { status: 502 })
+      }
+      if (u.includes('/fullenrich/contact/enrich/bulk')) {
+        return new Response(JSON.stringify({ error: 'down' }), { status: 502 })
+      }
+      if (u.includes('/findymail/search/name')) {
+        return new Response(JSON.stringify({ error: 'down' }), { status: 502 })
+      }
+      if (u.includes('/icypeas/email-search')) {
+        return new Response(JSON.stringify({ error: 'down' }), { status: 502 })
+      }
+      // Single-only fallbacks: all return 502 so executeWithFallback yields an error.
+      return new Response(JSON.stringify({ error: 'down' }), { status: 502 })
+    }) as typeof fetch
+
+    const result = await findEmailsHandler({ people: makePeople(15) })
+    const parsed = JSON.parse(result.content[0].text)
+
+    expect(parsed.data.found).toBe(0)
+    expect(parsed._meta.batch_status).toBe('failed')
+    expect(parsed._meta.providers.prospeo.failed).toBeGreaterThan(0)
+    expect(result.isError).toBe(true)
+  })
+
+  it('legitimate "no coverage" (every provider 200s with no email) stays batch_status="complete" and is NOT an error', async () => {
+    // Distinguishing failure from no-coverage: providers respond cleanly but find no 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: [], total_cost: 0 }),
+          { status: 200 },
+        )
+      }
+      if (u.includes('/fullenrich/contact/enrich/bulk')) {
+        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 })
+      }
+      return new Response(JSON.stringify({ email: null }), { status: 200 })
+    }) as typeof fetch
+
+    const result = await findEmailsHandler({ people: makePeople(12) })
+    const parsed = JSON.parse(result.content[0].text)
+
+    expect(parsed.data.found).toBe(0)
+    expect(parsed._meta.batch_status).toBe('complete')
+    expect(parsed._meta.providers.prospeo.failed).toBe(0)
+    expect(parsed._meta.providers.findymail.failed).toBe(0)
+    expect(result.isError).toBeUndefined()
+  })
+
+  it('small input (≤10) still works and emits _meta without chunking overhead', async () => {
+    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: false, person: { email: { email: 'alice@example.com' } } }],
+            total_cost: 1,
+          }),
+          { status: 200 },
+        )
+      }
+      return new Response(JSON.stringify({ error: 'unexpected' }), { status: 500 })
+    }) as typeof fetch
+
+    const result = await findEmailsHandler({
+      people: [{ id: 'p1', first_name: 'Alice', domain: 'example.com' }],
+    })
+    const parsed = JSON.parse(result.content[0].text)
+
+    expect(parsed._meta.chunk_count).toBe(1)
+    expect(parsed._meta.batch_status).toBe('complete')
+    expect(parsed._meta.providers.prospeo).toEqual({ attempted: 1, failed: 0 })
+    expect(result.isError).toBeUndefined()
+  })
+})

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

@@ -108,9 +108,59 @@ describe('find_people handler', () => {
         limit: 5,
       })
 
+      const parsed = JSON.parse(result.content[0].text)
+      expect(parsed._meta.provider).toBe('leadsfactory')
+      // Compact-by-default: raw `companies_personas` is normalized into `people[]`.
+      expect(parsed.data.people).toHaveLength(1)
+      expect(parsed.data.people[0]).toMatchObject({
+        full_name: 'Michel Lieben',
+        first_name: 'Michel',
+        last_name: 'Lieben',
+        title: 'CEO',
+      })
+      expect(parsed.data.companies_personas).toBeUndefined()
+    } finally {
+      lf.async!.timeoutMs = originalTimeout
+      lf.async!.pollIntervalMs = originalInterval
+    }
+  })
+
+  it('fields=verbose returns the raw LeadsFactory passthrough (companies_personas) unchanged', async () => {
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const urlStr = url.toString()
+      if (urlStr.includes('/leadsfactory/contact-finder/searches') && !urlStr.includes('abc123')) {
+        return new Response(JSON.stringify({ id: 'abc123', nb_jobs_total: 1, progress_percentage: 0 }), { status: 201 })
+      }
+      if (urlStr.includes('/leadsfactory/contact-finder/searches/abc123')) {
+        return new Response(JSON.stringify({
+          id: 'abc123', status: 'SUCCESSFUL', nb_jobs_total: 1, nb_jobs_complete: 1,
+          companies_personas: [
+            { company: 'ColdIQ', personas: [[{ contact: { first_name: 'Michel', last_name: 'Lieben', title: 'CEO' } }]] },
+          ],
+        }), { status: 200 })
+      }
+      return new Response(JSON.stringify({ error: 'Not found' }), { status: 404 })
+    }) as typeof fetch
+
+    const { getProviders } = await import('../../src/registry.js')
+    const lf = getProviders('find_people').find((p) => p.id === 'leadsfactory')!
+    const originalTimeout = lf.async!.timeoutMs
+    const originalInterval = lf.async!.pollIntervalMs
+
+    try {
+      lf.async!.timeoutMs = 500
+      lf.async!.pollIntervalMs = 20
+      const result = await findPeopleHandler({
+        company_domains: ['coldiq.com'],
+        job_titles: ['CEO'],
+        limit: 5,
+        fields: 'verbose',
+      })
+
       const parsed = JSON.parse(result.content[0].text)
       expect(parsed._meta.provider).toBe('leadsfactory')
       expect(parsed.data.companies_personas).toHaveLength(1)
+      expect(parsed.data.people).toBeUndefined()
     } finally {
       lf.async!.timeoutMs = originalTimeout
       lf.async!.pollIntervalMs = originalInterval
@@ -169,10 +219,13 @@ describe('find_people handler', () => {
 
       const parsed = JSON.parse(result.content[0].text)
       expect(parsed._meta.provider).toBe('leadsfactory')
-      expect(parsed.data.companies_personas).toHaveLength(1)
-      expect(parsed.data.gap_fill.provider).toBe('apollo')
-      expect(parsed.data.gap_fill.domains).toEqual(['folk.app'])
-      expect(parsed.data.gap_fill.people).toHaveLength(1)
+      // Compact-by-default: LF + Apollo gap-fill records are merged into one people[]
+      // and the gap-fill source is surfaced via gap_fill_provider.
+      expect(parsed.data.people).toHaveLength(2)
+      expect(parsed.data.people.map((p: { full_name: string }) => p.full_name)).toEqual(['Michel Lieben', 'Thibaud Elziere'])
+      expect(parsed.data.gap_fill_provider).toBe('apollo')
+      expect(parsed.data.companies_personas).toBeUndefined()
+      expect(parsed.data.gap_fill).toBeUndefined()
     } finally {
       lf.async!.timeoutMs = originalTimeout
       lf.async!.pollIntervalMs = originalInterval
@@ -224,7 +277,7 @@ describe('find_people handler', () => {
 
       const parsed = JSON.parse(result.content[0].text)
       expect(parsed._meta.provider).toBe('leadsfactory')
-      expect(parsed.data.gap_fill).toBeUndefined()
+      expect(parsed.data.gap_fill_provider).toBeUndefined()
       expect(apolloCalled).toBe(false)
     } finally {
       lf.async!.timeoutMs = originalTimeout
@@ -353,5 +406,216 @@ describe('find_people handler', () => {
     const parsed = JSON.parse(result.content[0].text)
     expect(parsed._meta.provider).toBe('apollo')
     expect(parsed.data.people).toHaveLength(1)
+    expect(parsed.data.people[0]).toMatchObject({
+      full_name: 'Michel Lieben',
+      company_domain: 'coldiq.com',
+    })
+  })
+
+  it('reveal=true follows obfuscated Apollo search with bulk-match in chunks of 10', async () => {
+    const bulkMatchCalls: Array<{ url: string; body: Record<string, unknown> }> = []
+    const obfuscated = (id: string, n: number) => ({
+      id,
+      first_name: `Person${n}`,
+      last_name: `Ar***t${n}`,
+      organization: { website_url: 'coldiq.com' },
+    })
+    const revealed = (id: string, n: number) => ({
+      id,
+      first_name: `Person${n}`,
+      last_name: `Argent${n}`,
+      email: `person${n}@coldiq.com`,
+      linkedin_url: `https://linkedin.com/in/person${n}`,
+      organization: { website_url: 'coldiq.com' },
+    })
+
+    globalThis.fetch = vi.fn(async (url: string | URL | Request, opts?: RequestInit) => {
+      const urlStr = url.toString()
+
+      if (urlStr.includes('/apollo/people/search')) {
+        return new Response(
+          JSON.stringify({ people: Array.from({ length: 12 }, (_, i) => obfuscated(`id_${i}`, i)) }),
+          { status: 200 },
+        )
+      }
+
+      if (urlStr.includes('/apollo/people/bulk-match')) {
+        const body = JSON.parse((opts?.body as string) ?? '{}') as { details: Array<{ id: string }> }
+        bulkMatchCalls.push({ url: urlStr, body })
+        return new Response(
+          JSON.stringify({
+            matches: body.details.map((d, idx) => revealed(d.id, parseInt(d.id.replace('id_', ''), 10) || idx)),
+          }),
+          { status: 200 },
+        )
+      }
+
+      // Skip LeadsFactory entirely by pinning apollo via use_providers below.
+      return new Response(JSON.stringify({ error: 'Not found' }), { status: 404 })
+    }) as typeof fetch
+
+    const result = await findPeopleHandler({
+      company_domains: ['coldiq.com'],
+      job_titles: ['CEO'],
+      limit: 12,
+      reveal: true,
+      use_providers: ['apollo'],
+    })
+
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed._meta.provider).toBe('apollo')
+    expect(parsed.data.revealed).toBe(true)
+    expect(parsed.data.people).toHaveLength(12)
+    // Chunked at 10 per bulk-match call: 12 IDs → 2 calls (10 + 2)
+    expect(bulkMatchCalls).toHaveLength(2)
+    expect(bulkMatchCalls[0].body.details).toHaveLength(10)
+    expect(bulkMatchCalls[1].body.details).toHaveLength(2)
+    // Revealed payload (compacted) carries email + full last name
+    expect(parsed.data.people[0].email).toBe('person0@coldiq.com')
+    expect(parsed.data.people[0].last_name).toBe('Argent0')
+    // reveal_personal_emails flag forwarded
+    expect(bulkMatchCalls[0].body.reveal_personal_emails).toBe(true)
+  })
+
+  it('reveal=true does NOT set revealed:true when bulk-match returns only some IDs (partial reveal)', async () => {
+    // Apollo's bulk-match can return matches for a subset of submitted IDs (e.g. some
+    // people aren't in their database). Setting `revealed: true` in that case would
+    // mislead callers — entries still obfuscated would look revealed at the top level.
+    globalThis.fetch = vi.fn(async (url: string | URL | Request, opts?: RequestInit) => {
+      const urlStr = url.toString()
+
+      if (urlStr.includes('/apollo/people/search')) {
+        return new Response(
+          JSON.stringify({
+            people: [
+              { id: 'id_0', first_name: 'A', last_name: 'A***A', organization: { website_url: 'coldiq.com' } },
+              { id: 'id_1', first_name: 'B', last_name: 'B***B', organization: { website_url: 'coldiq.com' } },
+              { id: 'id_2', first_name: 'C', last_name: 'C***C', organization: { website_url: 'coldiq.com' } },
+            ],
+          }),
+          { status: 200 },
+        )
+      }
+
+      if (urlStr.includes('/apollo/people/bulk-match')) {
+        const body = JSON.parse((opts?.body as string) ?? '{}') as { details: Array<{ id: string }> }
+        // Only return a match for id_0 — id_1 and id_2 stay obfuscated.
+        const onlyFirst = body.details
+          .filter((d) => d.id === 'id_0')
+          .map((d) => ({ id: d.id, first_name: 'A', last_name: 'AlphaReal', email: 'a@coldiq.com', linkedin_url: 'https://linkedin.com/in/a', organization: { website_url: 'coldiq.com' } }))
+        return new Response(JSON.stringify({ matches: onlyFirst }), { status: 200 })
+      }
+
+      return new Response(JSON.stringify({ error: 'Not found' }), { status: 404 })
+    }) as typeof fetch
+
+    const result = await findPeopleHandler({
+      company_domains: ['coldiq.com'],
+      job_titles: ['CEO'],
+      limit: 3,
+      reveal: true,
+      use_providers: ['apollo'],
+    })
+
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed._meta.provider).toBe('apollo')
+    // Partial reveal: flag must be omitted (compactPayload only includes revealed when === true).
+    expect(parsed.data.revealed).toBeUndefined()
+    expect(parsed.data.people).toHaveLength(3)
+    // id_0 came back revealed; id_1/id_2 stayed obfuscated.
+    expect(parsed.data.people[0].last_name).toBe('AlphaReal')
+    expect(parsed.data.people[0].email).toBe('a@coldiq.com')
+    expect(parsed.data.people[1].last_name).toBe('B***B')
+    expect(parsed.data.people[2].last_name).toBe('C***C')
+  })
+
+  it('reveal=false (default) skips bulk-match and returns obfuscated Apollo data unchanged', async () => {
+    let bulkMatchCalled = false
+
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const urlStr = url.toString()
+
+      if (urlStr.includes('/apollo/people/search')) {
+        return new Response(
+          JSON.stringify({
+            people: [{ id: 'id_0', first_name: 'Michel', last_name: 'Li***n', organization: { website_url: 'coldiq.com' } }],
+          }),
+          { status: 200 },
+        )
+      }
+
+      if (urlStr.includes('/apollo/people/bulk-match')) {
+        bulkMatchCalled = true
+        return new Response(JSON.stringify({ matches: [] }), { status: 200 })
+      }
+
+      return new Response(JSON.stringify({ error: 'Not found' }), { status: 404 })
+    }) as typeof fetch
+
+    const result = await findPeopleHandler({
+      company_domains: ['coldiq.com'],
+      job_titles: ['CEO'],
+      limit: 5,
+      use_providers: ['apollo'],
+    })
+
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed._meta.provider).toBe('apollo')
+    expect(parsed.data.revealed).toBeUndefined()
+    // Obfuscated last name from /apollo/people/search is preserved through compaction.
+    expect(parsed.data.people[0].last_name).toBe('Li***n')
+    expect(bulkMatchCalled).toBe(false)
+  })
+
+  it('reveal=true is a no-op when the matched provider is not Apollo', async () => {
+    let bulkMatchCalled = false
+
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const urlStr = url.toString()
+
+      if (urlStr.includes('/leadsfactory/contact-finder/searches') && !urlStr.includes('abc123')) {
+        return new Response(JSON.stringify({ id: 'abc123', nb_jobs_total: 1, progress_percentage: 0 }), { status: 201 })
+      }
+
+      if (urlStr.includes('/leadsfactory/contact-finder/searches/abc123')) {
+        return new Response(JSON.stringify({
+          id: 'abc123', status: 'SUCCESSFUL', nb_jobs_total: 1, nb_jobs_complete: 1,
+          companies_personas: [
+            { company: 'ColdIQ', personas: [[{ contact: { first_name: 'Michel', last_name: 'Lieben' } }]] },
+          ],
+        }), { status: 200 })
+      }
+
+      if (urlStr.includes('/apollo/people/bulk-match')) {
+        bulkMatchCalled = true
+        return new Response(JSON.stringify({ matches: [] }), { status: 200 })
+      }
+
+      return new Response(JSON.stringify({ error: 'Not found' }), { status: 404 })
+    }) as typeof fetch
+
+    const { getProviders } = await import('../../src/registry.js')
+    const lf = getProviders('find_people').find((p) => p.id === 'leadsfactory')!
+    const originalTimeout = lf.async!.timeoutMs
+    const originalInterval = lf.async!.pollIntervalMs
+
+    try {
+      lf.async!.timeoutMs = 500
+      lf.async!.pollIntervalMs = 20
+
+      const result = await findPeopleHandler({
+        company_domains: ['coldiq.com'],
+        job_titles: ['CEO'],
+        limit: 5,
+        reveal: true,
+      })
+
+      const parsed = JSON.parse(result.content[0].text)
+      expect(parsed._meta.provider).toBe('leadsfactory')
+      expect(bulkMatchCalled).toBe(false)
+    } finally {
+      lf.async!.timeoutMs = originalTimeout
+      lf.async!.pollIntervalMs = originalInterval
+    }
   })
 })

package/tests/tools/get-credit-balance.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { initClient } from '../../src/client.js'
+import { getCreditBalanceHandler } from '../../src/tools/get-credit-balance.js'
+
+describe('get_credit_balance handler', () => {
+  const originalFetch = globalThis.fetch
+
+  beforeEach(() => {
+    initClient('http://test-api.local', 'test-key')
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  it('returns the balance payload on success', async () => {
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const u = url.toString()
+      if (u.endsWith('/v1/me/credits')) {
+        return new Response(JSON.stringify({ balance: 250, usedThisMonth: 47 }), { status: 200 })
+      }
+      return new Response(JSON.stringify({ error: 'unexpected' }), { status: 500 })
+    }) as typeof fetch
+
+    const result = await getCreditBalanceHandler({})
+
+    expect(result.isError).toBeFalsy()
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed.data).toEqual({ balance: 250, usedThisMonth: 47 })
+  })
+
+  it('sends the API key as a bearer token', async () => {
+    let capturedAuth: string | null = null
+    globalThis.fetch = vi.fn(async (_url: string | URL | Request, opts?: RequestInit) => {
+      const headers = (opts?.headers ?? {}) as Record<string, string>
+      capturedAuth = headers.Authorization ?? null
+      return new Response(JSON.stringify({ balance: 0, usedThisMonth: 0 }), { status: 200 })
+    }) as typeof fetch
+
+    await getCreditBalanceHandler({})
+    expect(capturedAuth).toBe('Bearer test-key')
+  })
+
+  it('returns isError when the API responds with non-2xx', async () => {
+    globalThis.fetch = vi.fn(async () => {
+      return new Response(JSON.stringify({ error: 'Invalid API key' }), { status: 401 })
+    }) as typeof fetch
+
+    const result = await getCreditBalanceHandler({})
+
+    expect(result.isError).toBe(true)
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed.status).toBe(401)
+    expect(parsed.error).toBe('Failed to fetch credit balance')
+  })
+})