@coldiq/mcp 0.1.0

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

@@ -0,0 +1,110 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+// Mock executeWithFallback so handler tests never hit real providers
+vi.mock('../../src/executor.js', () => ({
+  executeWithFallback: vi.fn().mockResolvedValue({ data: [], _meta: { provider: 'mock' } }),
+  isExecutionError: vi.fn().mockReturnValue(false),
+}))
+
+import { findSignalsHandler } from '../../src/tools/find-signals.js'
+
+beforeEach(() => {
+  vi.clearAllMocks()
+})
+
+// ---------------------------------------------------------------------------
+// intent pre-check: requires companies or domains
+// ---------------------------------------------------------------------------
+
+describe('find_signals handler — intent guard', () => {
+  it('rejects intent with no companies or domains', async () => {
+    const result = await findSignalsHandler({ signal_type: 'intent', limit: 10 })
+    expect(result.isError).toBe(true)
+    const body = JSON.parse(result.content[0].text)
+    expect(body.error).toMatch(/intent signal_type requires/)
+  })
+
+  it('rejects intent with empty companies array', async () => {
+    const result = await findSignalsHandler({ signal_type: 'intent', companies: [], limit: 10 })
+    expect(result.isError).toBe(true)
+  })
+
+  it('rejects intent with empty domains array', async () => {
+    const result = await findSignalsHandler({ signal_type: 'intent', domains: [], limit: 10 })
+    expect(result.isError).toBe(true)
+  })
+
+  it('allows intent with companies present', async () => {
+    const result = await findSignalsHandler({ signal_type: 'intent', companies: ['ColdIQ'], limit: 10 })
+    expect(result.isError).toBeUndefined()
+  })
+
+  it('allows intent with domains present', async () => {
+    const result = await findSignalsHandler({ signal_type: 'intent', domains: ['coldiq.com'], limit: 10 })
+    expect(result.isError).toBeUndefined()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// feed-style pre-check: news and startup_post reject company filters
+// ---------------------------------------------------------------------------
+
+describe('find_signals handler — feed-style guard (news)', () => {
+  it('rejects news with companies filter', async () => {
+    const result = await findSignalsHandler({ signal_type: 'news', companies: ['ColdIQ'] })
+    expect(result.isError).toBe(true)
+    const body = JSON.parse(result.content[0].text)
+    expect(body.error).toMatch(/news and startup_post/)
+  })
+
+  it('rejects news with domains filter', async () => {
+    const result = await findSignalsHandler({ signal_type: 'news', domains: ['coldiq.com'] })
+    expect(result.isError).toBe(true)
+  })
+
+  it('allows news with countries only', async () => {
+    const result = await findSignalsHandler({ signal_type: 'news', countries: ['US'], limit: 10 })
+    expect(result.isError).toBeUndefined()
+  })
+
+  it('allows news with since and limit only', async () => {
+    const result = await findSignalsHandler({ signal_type: 'news', since: '2026-01-01', limit: 5 })
+    expect(result.isError).toBeUndefined()
+  })
+})
+
+describe('find_signals handler — feed-style guard (startup_post)', () => {
+  it('rejects startup_post with companies filter', async () => {
+    const result = await findSignalsHandler({ signal_type: 'startup_post', companies: ['ColdIQ'] })
+    expect(result.isError).toBe(true)
+    const body = JSON.parse(result.content[0].text)
+    expect(body.error).toMatch(/news and startup_post/)
+  })
+
+  it('rejects startup_post with domains filter', async () => {
+    const result = await findSignalsHandler({ signal_type: 'startup_post', domains: ['coldiq.com'] })
+    expect(result.isError).toBe(true)
+  })
+
+  it('allows startup_post with since filter only', async () => {
+    const result = await findSignalsHandler({ signal_type: 'startup_post', since: '2026-01-01', limit: 25 })
+    expect(result.isError).toBeUndefined()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// company-targeted types: no pre-check rejection
+// ---------------------------------------------------------------------------
+
+describe('find_signals handler — company-targeted types pass through', () => {
+  const types = ['funding', 'acquisition', 'hiring', 'job_change'] as const
+
+  for (const signal_type of types) {
+    it(`allows ${signal_type} with or without companies`, async () => {
+      const withCompanies = await findSignalsHandler({ signal_type, companies: ['ColdIQ'] })
+      const withoutCompanies = await findSignalsHandler({ signal_type, limit: 10 })
+      expect(withCompanies.isError).toBeUndefined()
+      expect(withoutCompanies.isError).toBeUndefined()
+    })
+  }
+})

package/tests/tools/search-ads.test.ts

@@ -0,0 +1,182 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { initClient } from '../../src/client.js'
+import { searchAdsHandler } from '../../src/tools/search-ads.js'
+
+describe('search_ads handler', () => {
+  const originalFetch = globalThis.fetch
+
+  beforeEach(() => {
+    initClient('http://test-api.local', 'test-key')
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  it('domains filter — routes to google_ads only', async () => {
+    let metaCalled = false
+    let linkedinCalled = false
+
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const u = url.toString()
+      if (u.includes('/meta-ads/')) metaCalled = true
+      if (u.includes('/linkedin-ad-library/')) linkedinCalled = true
+      if (u.includes('/google-ads/search') && !u.includes('/search/')) {
+        return new Response(JSON.stringify({ jobId: 'ads-1' }), { status: 200 })
+      }
+      if (u.includes('/google-ads/search/ads-1')) {
+        return new Response(JSON.stringify({ jobId: 'ads-1', status: 'done', ads: [{ advertiser: 'Salesforce', headline: 'CRM Leader' }] }), { status: 200 })
+      }
+      return new Response(JSON.stringify({ error: 'unexpected' }), { status: 500 })
+    }) as typeof fetch
+
+    const { getProviders } = await import('../../src/registry.js')
+    const providers = getProviders('search_ads')
+    const ga = providers.find((p) => p.id === 'google_ads')!
+    const orig = { t: ga.async!.timeoutMs, i: ga.async!.pollIntervalMs }
+    ga.async!.timeoutMs = 500
+    ga.async!.pollIntervalMs = 20
+
+    try {
+      const result = await searchAdsHandler({ domains: ['salesforce.com'] })
+
+      expect(result.isError).toBeFalsy()
+      const parsed = JSON.parse(result.content[0].text)
+      expect(parsed._meta.provider).toBe('google_ads')
+      expect(metaCalled).toBe(false)
+      expect(linkedinCalled).toBe(false)
+    } finally {
+      ga.async!.timeoutMs = orig.t
+      ga.async!.pollIntervalMs = orig.i
+    }
+  })
+
+  it('search_urls filter — routes to linkedin_ad_library only', async () => {
+    let googleCalled = false
+
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const u = url.toString()
+      if (u.includes('/google-ads/')) googleCalled = true
+      if (u.includes('/linkedin-ad-library/search') && !u.includes('/search/')) {
+        return new Response(JSON.stringify({ jobId: 'li-1' }), { status: 200 })
+      }
+      if (u.includes('/linkedin-ad-library/search/li-1')) {
+        return new Response(JSON.stringify({ jobId: 'li-1', status: 'done', ads: [{ company: 'ColdIQ', creative: 'B2B ad' }] }), { status: 200 })
+      }
+      return new Response(JSON.stringify({ error: 'unexpected' }), { status: 500 })
+    }) as typeof fetch
+
+    const { getProviders } = await import('../../src/registry.js')
+    const providers = getProviders('search_ads')
+    const li = providers.find((p) => p.id === 'linkedin_ad_library')!
+    const orig = { t: li.async!.timeoutMs, i: li.async!.pollIntervalMs }
+    li.async!.timeoutMs = 500
+    li.async!.pollIntervalMs = 20
+
+    try {
+      const result = await searchAdsHandler({
+        search_urls: ['https://linkedin.com/ad-library/search?companyIds=123'],
+      })
+
+      expect(result.isError).toBeFalsy()
+      const parsed = JSON.parse(result.content[0].text)
+      expect(parsed._meta.provider).toBe('linkedin_ad_library')
+      expect(googleCalled).toBe(false)
+    } finally {
+      li.async!.timeoutMs = orig.t
+      li.async!.pollIntervalMs = orig.i
+    }
+  })
+
+  it('query only — falls through google_ads (no results) → meta_ads wins', async () => {
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const u = url.toString()
+      // google_ads: create returns jobId, poll returns no ads
+      if (u.includes('/google-ads/search') && !u.includes('/search/')) {
+        return new Response(JSON.stringify({ jobId: 'ga-2' }), { status: 200 })
+      }
+      if (u.includes('/google-ads/search/ga-2')) {
+        return new Response(JSON.stringify({ jobId: 'ga-2', status: 'done', ads: [] }), { status: 200 })
+      }
+      // meta_ads: returns results
+      if (u.includes('/meta-ads/search') && !u.includes('/search/')) {
+        return new Response(JSON.stringify({ jobId: 'meta-1' }), { status: 200 })
+      }
+      if (u.includes('/meta-ads/search/meta-1')) {
+        return new Response(JSON.stringify({ jobId: 'meta-1', status: 'done', ads: [{ page_name: 'ColdIQ', body: 'Outbound faster' }] }), { status: 200 })
+      }
+      return new Response(JSON.stringify({ error: 'unexpected' }), { status: 500 })
+    }) as typeof fetch
+
+    const { getProviders } = await import('../../src/registry.js')
+    const providers = getProviders('search_ads')
+    const ga = providers.find((p) => p.id === 'google_ads')!
+    const ma = providers.find((p) => p.id === 'meta_ads')!
+    const origGa = { t: ga.async!.timeoutMs, i: ga.async!.pollIntervalMs }
+    const origMa = { t: ma.async!.timeoutMs, i: ma.async!.pollIntervalMs }
+    ga.async!.timeoutMs = 500
+    ga.async!.pollIntervalMs = 20
+    ma.async!.timeoutMs = 500
+    ma.async!.pollIntervalMs = 20
+
+    try {
+      const result = await searchAdsHandler({ query: 'ColdIQ' })
+
+      expect(result.isError).toBeFalsy()
+      const parsed = JSON.parse(result.content[0].text)
+      expect(parsed._meta.provider).toBe('meta_ads')
+    } finally {
+      ga.async!.timeoutMs = origGa.t
+      ga.async!.pollIntervalMs = origGa.i
+      ma.async!.timeoutMs = origMa.t
+      ma.async!.pollIntervalMs = origMa.i
+    }
+  })
+
+  it('platform=meta pinned — only meta_ads fires', async () => {
+    let googleCalled = false
+
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const u = url.toString()
+      if (u.includes('/google-ads/')) googleCalled = true
+      if (u.includes('/meta-ads/search') && !u.includes('/search/')) {
+        return new Response(JSON.stringify({ jobId: 'meta-2' }), { status: 200 })
+      }
+      if (u.includes('/meta-ads/search/meta-2')) {
+        return new Response(JSON.stringify({ jobId: 'meta-2', status: 'done', ads: [{ page_name: 'ColdIQ' }] }), { status: 200 })
+      }
+      return new Response(JSON.stringify({ error: 'unexpected' }), { status: 500 })
+    }) as typeof fetch
+
+    const { getProviders } = await import('../../src/registry.js')
+    const providers = getProviders('search_ads')
+    const ma = providers.find((p) => p.id === 'meta_ads')!
+    const orig = { t: ma.async!.timeoutMs, i: ma.async!.pollIntervalMs }
+    ma.async!.timeoutMs = 500
+    ma.async!.pollIntervalMs = 20
+
+    try {
+      const result = await searchAdsHandler({ platform: 'meta', query: 'ColdIQ' })
+
+      expect(result.isError).toBeFalsy()
+      const parsed = JSON.parse(result.content[0].text)
+      expect(parsed._meta.provider).toBe('meta_ads')
+      expect(googleCalled).toBe(false)
+    } finally {
+      ma.async!.timeoutMs = orig.t
+      ma.async!.pollIntervalMs = orig.i
+    }
+  })
+
+  it('all providers fail — returns isError', async () => {
+    globalThis.fetch = vi.fn(async () => {
+      return new Response(JSON.stringify({ error: 'down' }), { status: 503 })
+    }) as typeof fetch
+
+    const result = await searchAdsHandler({ query: 'ColdIQ' })
+
+    expect(result.isError).toBe(true)
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed.error).toBeTruthy()
+  })
+})

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

@@ -0,0 +1,58 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { initClient } from '../../src/client.js'
+import { searchCompaniesHandler } from '../../src/tools/search-companies.js'
+
+describe('search_companies handler', () => {
+  const originalFetch = globalThis.fetch
+
+  beforeEach(() => {
+    initClient('http://test-api.local', 'test-key')
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  it('returns results from first successful provider', async () => {
+    globalThis.fetch = vi.fn(async () =>
+      new Response(JSON.stringify({ data: [{ name: 'ColdIQ', domain: 'coldiq.com' }] }), { status: 200 })
+    ) as typeof fetch
+
+    const result = await searchCompaniesHandler({ countries: ['FR'], limit: 5 })
+
+    expect(result.isError).toBeUndefined()
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed._meta.provider).toBe('companyenrich')
+    expect(parsed.data.data).toHaveLength(1)
+  })
+
+  it('falls back to FullEnrich (priority 2) on CompanyEnrich failure', async () => {
+    let callCount = 0
+    globalThis.fetch = vi.fn(async () => {
+      callCount++
+      if (callCount === 1) {
+        return new Response(JSON.stringify({ error: 'Provider error' }), { status: 502 })
+      }
+      return new Response(JSON.stringify({ companies: [{ name: 'ColdIQ' }] }), { status: 200 })
+    }) as typeof fetch
+
+    const result = await searchCompaniesHandler({ countries: ['FR'], limit: 5 })
+
+    expect(result.isError).toBeUndefined()
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed._meta.provider).toBe('fullenrich')
+  })
+
+  it('returns error when all providers fail', async () => {
+    globalThis.fetch = vi.fn(async () =>
+      new Response(JSON.stringify({ error: 'Service down' }), { status: 500 })
+    ) as typeof fetch
+
+    const result = await searchCompaniesHandler({ countries: ['FR'], limit: 5 })
+
+    expect(result.isError).toBe(true)
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed.error).toContain('All')
+    expect(parsed.providers_tried.length).toBeGreaterThan(0)
+  })
+})

package/tests/tools/search-jobs.test.ts

@@ -0,0 +1,210 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { initClient } from '../../src/client.js'
+import { searchJobsHandler } from '../../src/tools/search-jobs.js'
+
+describe('search_jobs handler', () => {
+  const originalFetch = globalThis.fetch
+
+  beforeEach(() => {
+    initClient('http://test-api.local', 'test-key')
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  it('contradictory filters — rejected at handler level before any provider is called', async () => {
+    let fetchCalled = false
+    globalThis.fetch = vi.fn(async () => {
+      fetchCalled = true
+      return new Response(JSON.stringify({}), { status: 200 })
+    }) as typeof fetch
+
+    const result = await searchJobsHandler({
+      ats_slugs: ['greenhouse'],
+      seniority_levels: ['Director'],
+    })
+
+    expect(result.isError).toBe(true)
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed.error).toMatch(/contradictory/i)
+    expect(fetchCalled).toBe(false)
+  })
+
+  it('ats_slugs filter — routes to career_site_jobs only (LinkedIn skipped)', async () => {
+    let linkedinCalled = false
+
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const u = url.toString()
+      if (u.includes('/linkedin-jobs-api/search')) {
+        linkedinCalled = true
+        throw new Error('linkedin_jobs_api should not fire when ats_slugs is set')
+      }
+      if (u.includes('/career-site-jobs/search') && !u.includes('/search/')) {
+        // Async create — returns a jobId
+        return new Response(JSON.stringify({ jobId: 'job-1' }), { status: 200 })
+      }
+      if (u.includes('/career-site-jobs/search/job-1')) {
+        // Poll — done with results
+        return new Response(JSON.stringify({ jobId: 'job-1', status: 'done', jobs: [{ title: 'Software Engineer', company: 'Stripe' }] }), { status: 200 })
+      }
+      return new Response(JSON.stringify({ error: 'unexpected' }), { status: 500 })
+    }) as typeof fetch
+
+    const { getProviders } = await import('../../src/registry.js')
+    const providers = getProviders('search_jobs')
+    const cs = providers.find((p) => p.id === 'career_site_jobs')!
+    const orig = { t: cs.async!.timeoutMs, i: cs.async!.pollIntervalMs }
+    cs.async!.timeoutMs = 500
+    cs.async!.pollIntervalMs = 20
+
+    try {
+      const result = await searchJobsHandler({
+        ats_slugs: ['greenhouse'],
+        title_keywords: ['Engineer'],
+        limit: 10,
+      })
+
+      expect(result.isError).toBeFalsy()
+      const parsed = JSON.parse(result.content[0].text)
+      expect(parsed._meta.provider).toBe('career_site_jobs')
+      expect(linkedinCalled).toBe(false)
+    } finally {
+      cs.async!.timeoutMs = orig.t
+      cs.async!.pollIntervalMs = orig.i
+    }
+  })
+
+  it('seniority_levels filter — routes to linkedin_jobs_api only (career_site_jobs skipped)', async () => {
+    let careerSiteCalled = false
+
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const u = url.toString()
+      if (u.includes('/career-site-jobs/search') && !u.includes('/search/')) {
+        careerSiteCalled = true
+        throw new Error('career_site_jobs should not fire when seniority_levels is set')
+      }
+      if (u.includes('/linkedin-jobs-api/search') && !u.includes('/search/')) {
+        return new Response(JSON.stringify({ jobId: 'job-2' }), { status: 200 })
+      }
+      if (u.includes('/linkedin-jobs-api/search/job-2')) {
+        return new Response(JSON.stringify({ jobId: 'job-2', status: 'done', jobs: [{ title: 'VP of Sales', company: 'HubSpot' }] }), { status: 200 })
+      }
+      return new Response(JSON.stringify({ error: 'unexpected' }), { status: 500 })
+    }) as typeof fetch
+
+    const { getProviders } = await import('../../src/registry.js')
+    const providers = getProviders('search_jobs')
+    const li = providers.find((p) => p.id === 'linkedin_jobs_api')!
+    const orig = { t: li.async!.timeoutMs, i: li.async!.pollIntervalMs }
+    li.async!.timeoutMs = 500
+    li.async!.pollIntervalMs = 20
+
+    try {
+      const result = await searchJobsHandler({
+        seniority_levels: ['Director'],
+        title_keywords: ['VP'],
+        limit: 10,
+      })
+
+      expect(result.isError).toBeFalsy()
+      const parsed = JSON.parse(result.content[0].text)
+      expect(parsed._meta.provider).toBe('linkedin_jobs_api')
+      expect(careerSiteCalled).toBe(false)
+    } finally {
+      li.async!.timeoutMs = orig.t
+      li.async!.pollIntervalMs = orig.i
+    }
+  })
+
+  it('async timeout — career_site_jobs times out, falls back to theirstack-jobs', async () => {
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const u = url.toString()
+      if (u.includes('/career-site-jobs/search') && !u.includes('/search/')) {
+        return new Response(JSON.stringify({ jobId: 'job-3' }), { status: 200 })
+      }
+      if (u.includes('/career-site-jobs/search/job-3')) {
+        // Always running — will cause timeout
+        return new Response(JSON.stringify({ jobId: 'job-3', status: 'running' }), { status: 200 })
+      }
+      if (u.includes('/linkedin-jobs-api/search') && !u.includes('/search/')) {
+        return new Response(JSON.stringify({ jobId: 'job-4' }), { status: 200 })
+      }
+      if (u.includes('/linkedin-jobs-api/search/job-4')) {
+        return new Response(JSON.stringify({ jobId: 'job-4', status: 'running' }), { status: 200 })
+      }
+      if (u.includes('/theirstack/jobs/search')) {
+        return new Response(JSON.stringify({ data: [{ title: 'SDR', company_name: 'ColdIQ' }] }), { status: 200 })
+      }
+      return new Response(JSON.stringify({ error: 'unexpected' }), { status: 500 })
+    }) as typeof fetch
+
+    const { getProviders } = await import('../../src/registry.js')
+    const providers = getProviders('search_jobs')
+    const cs = providers.find((p) => p.id === 'career_site_jobs')!
+    const li = providers.find((p) => p.id === 'linkedin_jobs_api')!
+    const origCs = { t: cs.async!.timeoutMs, i: cs.async!.pollIntervalMs }
+    const origLi = { t: li.async!.timeoutMs, i: li.async!.pollIntervalMs }
+    cs.async!.timeoutMs = 100
+    cs.async!.pollIntervalMs = 20
+    li.async!.timeoutMs = 100
+    li.async!.pollIntervalMs = 20
+
+    try {
+      const result = await searchJobsHandler({
+        title_keywords: ['SDR'],
+        limit: 10,
+      })
+
+      expect(result.isError).toBeFalsy()
+      const parsed = JSON.parse(result.content[0].text)
+      expect(parsed._meta.provider).toBe('theirstack-jobs')
+      expect(parsed.data.data).toHaveLength(1)
+    } finally {
+      cs.async!.timeoutMs = origCs.t
+      cs.async!.pollIntervalMs = origCs.i
+      li.async!.timeoutMs = origLi.t
+      li.async!.pollIntervalMs = origLi.i
+    }
+  })
+
+  it('shared-only filters — both career_site_jobs and linkedin_jobs_api are applicable', async () => {
+    // With only title_keywords and locations (shared filters), career_site_jobs fires first
+    let careerSiteCreate = 0
+
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const u = url.toString()
+      if (u.includes('/career-site-jobs/search') && !u.includes('/search/')) {
+        careerSiteCreate++
+        return new Response(JSON.stringify({ jobId: 'job-5' }), { status: 200 })
+      }
+      if (u.includes('/career-site-jobs/search/job-5')) {
+        return new Response(JSON.stringify({ jobId: 'job-5', status: 'done', jobs: [{ title: 'SDR', company: 'ColdIQ' }] }), { status: 200 })
+      }
+      return new Response(JSON.stringify({ error: 'unexpected' }), { status: 500 })
+    }) as typeof fetch
+
+    const { getProviders } = await import('../../src/registry.js')
+    const providers = getProviders('search_jobs')
+    const cs = providers.find((p) => p.id === 'career_site_jobs')!
+    const orig = { t: cs.async!.timeoutMs, i: cs.async!.pollIntervalMs }
+    cs.async!.timeoutMs = 500
+    cs.async!.pollIntervalMs = 20
+
+    try {
+      const result = await searchJobsHandler({
+        title_keywords: ['SDR'],
+        locations: ['Paris, France'],
+        limit: 10,
+      })
+
+      expect(result.isError).toBeFalsy()
+      const parsed = JSON.parse(result.content[0].text)
+      expect(parsed._meta.provider).toBe('career_site_jobs')
+      expect(careerSiteCreate).toBe(1)
+    } finally {
+      cs.async!.timeoutMs = orig.t
+      cs.async!.pollIntervalMs = orig.i
+    }
+  })
+})

package/tests/tools/search-places.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { initClient } from '../../src/client.js'
+import { searchPlacesHandler } from '../../src/tools/search-places.js'
+
+describe('search_places handler', () => {
+  const originalFetch = globalThis.fetch
+
+  beforeEach(() => {
+    initClient('http://test-api.local', 'test-key')
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  it('US query — openmart wins (sync, highest priority for supported countries)', async () => {
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const u = url.toString()
+      if (u.includes('/openmart/search')) {
+        return new Response(JSON.stringify({ data: [{ name: 'Blue Bottle Coffee', city: 'San Francisco' }] }), { status: 200 })
+      }
+      return new Response(JSON.stringify({ error: 'unexpected' }), { status: 500 })
+    }) as typeof fetch
+
+    const result = await searchPlacesHandler({ query: 'coffee shop', country: 'US', limit: 5 })
+
+    expect(result.isError).toBeFalsy()
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed._meta.provider).toBe('openmart')
+    expect(parsed.data.data).toHaveLength(1)
+  })
+
+  it('non-openmart country — routes to google_maps (openmart skipped)', async () => {
+    let openmartCalled = false
+
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const u = url.toString()
+      if (u.includes('/openmart/search')) { openmartCalled = true }
+      if (u.includes('/google-maps/scraper') && !u.includes('/scraper/')) {
+        return new Response(JSON.stringify({ jobId: 'gm-1' }), { status: 200 })
+      }
+      if (u.includes('/google-maps/scraper/gm-1')) {
+        return new Response(JSON.stringify({ jobId: 'gm-1', status: 'done', places: [{ title: 'Café de Flore', address: 'Paris' }] }), { status: 200 })
+      }
+      return new Response(JSON.stringify({ error: 'unexpected' }), { status: 500 })
+    }) as typeof fetch
+
+    const { getProviders } = await import('../../src/registry.js')
+    const providers = getProviders('search_places')
+    const gm = providers.find((p) => p.id === 'google_maps')!
+    const orig = { t: gm.async!.timeoutMs, i: gm.async!.pollIntervalMs }
+    gm.async!.timeoutMs = 500
+    gm.async!.pollIntervalMs = 20
+
+    try {
+      const result = await searchPlacesHandler({ query: 'café', country: 'FR', limit: 5 })
+
+      expect(result.isError).toBeFalsy()
+      const parsed = JSON.parse(result.content[0].text)
+      expect(parsed._meta.provider).toBe('google_maps')
+      expect(openmartCalled).toBe(false)
+    } finally {
+      gm.async!.timeoutMs = orig.t
+      gm.async!.pollIntervalMs = orig.i
+    }
+  })
+
+  it('provider=google_maps pinned — openmart skipped even for US', async () => {
+    let openmartCalled = false
+
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const u = url.toString()
+      if (u.includes('/openmart/search')) { openmartCalled = true }
+      if (u.includes('/google-maps/scraper') && !u.includes('/scraper/')) {
+        return new Response(JSON.stringify({ jobId: 'gm-2' }), { status: 200 })
+      }
+      if (u.includes('/google-maps/scraper/gm-2')) {
+        return new Response(JSON.stringify({ jobId: 'gm-2', status: 'done', places: [{ title: 'Starbucks' }] }), { status: 200 })
+      }
+      return new Response(JSON.stringify({ error: 'unexpected' }), { status: 500 })
+    }) as typeof fetch
+
+    const { getProviders } = await import('../../src/registry.js')
+    const providers = getProviders('search_places')
+    const gm = providers.find((p) => p.id === 'google_maps')!
+    const orig = { t: gm.async!.timeoutMs, i: gm.async!.pollIntervalMs }
+    gm.async!.timeoutMs = 500
+    gm.async!.pollIntervalMs = 20
+
+    try {
+      const result = await searchPlacesHandler({ query: 'coffee', country: 'US', provider: 'google_maps', limit: 5 })
+
+      expect(result.isError).toBeFalsy()
+      const parsed = JSON.parse(result.content[0].text)
+      expect(parsed._meta.provider).toBe('google_maps')
+      expect(openmartCalled).toBe(false)
+    } finally {
+      gm.async!.timeoutMs = orig.t
+      gm.async!.pollIntervalMs = orig.i
+    }
+  })
+
+  it('all providers fail — returns isError', async () => {
+    globalThis.fetch = vi.fn(async () => {
+      return new Response(JSON.stringify({ error: 'down' }), { status: 503 })
+    }) as typeof fetch
+
+    const result = await searchPlacesHandler({ query: 'coffee', country: 'US' })
+
+    expect(result.isError).toBe(true)
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed.error).toBeTruthy()
+  })
+})