@coldiq/mcp 0.1.0

package/src/tools/search-jobs.ts

@@ -0,0 +1,73 @@
+import { z } from 'zod'
+import { executeWithFallback, isExecutionError } from '../executor.js'
+
+const _CAREER_SITE_ONLY = ['ats_slugs', 'exclude_ats_slugs', 'company_domains', 'exclude_company_domains']
+const _LINKEDIN_ONLY = ['seniority_levels', 'industries', 'organization_slugs', 'exclude_organization_slugs', 'min_employees', 'max_employees', 'easy_apply_only', 'exclude_easy_apply']
+
+function _isFilterSet(input: Record<string, unknown>, keys: string[]): boolean {
+  return keys.some((k) => {
+    const v = input[k]
+    return !!v && (!Array.isArray(v) || v.length > 0)
+  })
+}
+
+export const searchJobsName = 'search_jobs'
+
+export const searchJobsDescription =
+  'Search live job postings as a GTM buying signal — find companies hiring for specific roles, on specific ATS platforms, in specific regions. Filter routing is automatic: ATS slugs and company-domain filters route to broad career-site coverage (175k+ company sites, 54 ATS platforms); LinkedIn-only filters (seniority, industry, employee count, easy apply) route to LinkedIn. Shared filters (title, location, description, work arrangement, employment type, taxonomies) work everywhere. For aggregated hiring activity at the company level (e.g. "X is hiring fast"), use find_signals(signal_type="hiring") instead. Default limit: 25.'
+
+export const searchJobsSchema = {
+  // --- shared filters ---
+  title_keywords: z.array(z.string()).optional().describe('Job title terms to match (supports prefix matching, e.g. "engineer:*"). OR-joined across terms.'),
+  exclude_title_keywords: z.array(z.string()).optional().describe('Title terms to exclude.'),
+  locations: z.array(z.string()).optional().describe('Locations in "City, State/Region, Country" format (English), e.g. ["Austin, Texas, United States"].'),
+  exclude_locations: z.array(z.string()).optional(),
+  description_keywords: z.array(z.string()).optional().describe('Free-text terms to search in job descriptions.'),
+  exclude_description_keywords: z.array(z.string()).optional(),
+  companies: z.array(z.string()).optional().describe('Company names to include.'),
+  exclude_companies: z.array(z.string()).optional(),
+  remote: z.boolean().optional().describe('Include remote jobs only.'),
+  exclude_agencies: z.boolean().optional().describe('Filter out staffing agencies and job boards.'),
+  posted_after: z.string().optional().describe('Only return jobs posted after this date, e.g. "2026-01-01" or ISO datetime.'),
+  time_range: z.enum(['1h', '24h', '7d', '6m']).optional().default('7d').describe('Recency window for the search.'),
+  include_description: z.boolean().optional().default(false).describe('Include full job description text in results (slower, more tokens).'),
+  employment_types: z.array(z.enum(['FULL_TIME', 'PART_TIME', 'CONTRACTOR', 'TEMPORARY', 'INTERN', 'VOLUNTEER', 'PER_DIEM', 'OTHER'])).optional(),
+  work_arrangements: z.array(z.enum(['On-site', 'Hybrid', 'Remote OK', 'Remote Solely'])).optional(),
+  experience_levels: z.array(z.enum(['0-2', '2-5', '5-10', '10+'])).optional().describe('AI-inferred years-of-experience bands.'),
+  has_salary: z.boolean().optional().describe('Only return postings that include salary information.'),
+  has_visa_sponsorship: z.boolean().optional(),
+  taxonomies: z.array(z.string()).optional().describe('AI-inferred industry taxonomies, e.g. ["Technology", "Healthcare"].'),
+  limit: z.number().int().min(10).max(500).default(25).describe('Max jobs to return (10–500, default 25).'),
+
+  // --- Career-site-only routing filters ---
+  ats_slugs: z.array(z.string()).optional().describe('Return only jobs from these ATS platforms, e.g. ["greenhouse", "workday", "ashby", "lever"]. Routes to career-site source; LinkedIn is skipped.'),
+  exclude_ats_slugs: z.array(z.string()).optional(),
+  company_domains: z.array(z.string()).optional().describe('Restrict to jobs posted by companies with these domains (exact match). Routes to career-site source.'),
+  exclude_company_domains: z.array(z.string()).optional(),
+
+  // --- LinkedIn-only routing filters ---
+  seniority_levels: z.array(z.enum(['Entry level', 'Associate', 'Mid-Senior level', 'Director', 'Executive', 'Internship', 'Not Applicable'])).optional().describe('LinkedIn seniority filter. Routes to LinkedIn source; career-site is skipped.'),
+  industries: z.array(z.string()).optional().describe('LinkedIn industry names (exact match). Routes to LinkedIn source.'),
+  organization_slugs: z.array(z.string()).optional().describe('LinkedIn company slugs to include. Routes to LinkedIn source.'),
+  exclude_organization_slugs: z.array(z.string()).optional(),
+  min_employees: z.number().int().min(1).optional().describe('Minimum company employee count (≥1). Routes to LinkedIn source.'),
+  max_employees: z.number().int().min(1).optional(),
+  easy_apply_only: z.boolean().optional().describe('Only LinkedIn Easy Apply jobs. Routes to LinkedIn source.'),
+  exclude_easy_apply: z.boolean().optional().describe('Exclude LinkedIn Easy Apply jobs. Routes to LinkedIn source.'),
+}
+
+export async function searchJobsHandler(input: Record<string, unknown>) {
+  if (_isFilterSet(input, _CAREER_SITE_ONLY) && _isFilterSet(input, _LINKEDIN_ONLY)) {
+    const err = {
+      error:
+        'Contradictory filters: ATS/domain filters (ats_slugs, company_domains) are Career Site only, ' +
+        'while seniority/industry/employee filters are LinkedIn only. Remove one set.',
+    }
+    return { content: [{ type: 'text' as const, text: JSON.stringify(err, null, 2) }], isError: true }
+  }
+  const result = await executeWithFallback('search_jobs', input)
+  if (isExecutionError(result)) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
+  }
+  return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] }
+}

package/src/tools/search-places.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod'
+import { executeWithFallback, isExecutionError } from '../executor.js'
+
+export const searchPlacesName = 'search_places'
+
+export const searchPlacesDescription =
+  'Search local businesses and places via 2 providers (Openmart Search, Google Maps Scraper) — useful for territory mapping, local-services prospecting, restaurant/retail/vertical research. Routes by input: structured filters or country in {US,CA,AU,PR,NZ} → Openmart (sync, ~1s) first, then Google Maps Scraper (async, ~30–120s) as fallback or for global coverage. Use provider="openmart"|"google_maps" to pin to one. Cost: 1 credit per place returned (both providers).'
+
+export const searchPlacesSchema = {
+  query: z.string().optional().describe('Free-text query (e.g. "coffee shops in Brooklyn", "law firm New York"). Used by both providers.'),
+  country: z.string().optional().describe('ISO country code. Openmart accepts US/CA/AU/PR/NZ only — outside this set, routes to Google Maps. Auto-cased per provider.'),
+  city: z.string().optional().describe('City name. Used by both providers.'),
+  limit: z.number().int().min(1).max(200).default(25).describe('Max places per provider call (1–200). Openmart caps at 500 internally; Google Maps at 200. Default 25.'),
+  provider: z.enum(['openmart', 'google_maps']).optional().describe('Pin to one provider; skips the other. Useful for explicit cross-provider comparison via separate calls.'),
+
+  state: z.string().optional().describe('Openmart only. State name or 2-letter code.'),
+  zip_code: z.string().optional().describe('Openmart only.'),
+  lat: z.number().optional().describe('Openmart only. Latitude for radius search.'),
+  long: z.number().optional().describe('Openmart only. Longitude for radius search.'),
+  geo_radius: z.number().int().positive().optional().describe('Openmart only. Search radius in meters around lat/long.'),
+
+  tags: z.array(z.string()).max(100).optional().describe('Openmart only. Category tags (mutually exclusive with query upstream — query is ignored if tags non-empty).'),
+
+  min_overall_rating: z.number().min(0).max(5).optional().describe('Openmart only.'),
+  max_overall_rating: z.number().min(0).max(5).optional().describe('Openmart only.'),
+  min_total_reviews: z.number().int().min(0).optional().describe('Openmart only.'),
+  max_total_reviews: z.number().int().min(0).optional().describe('Openmart only.'),
+
+  ownership_type: z.enum(['INDEPENDENT', 'FAMILY', 'FRANCHISE', 'CHAIN']).optional().describe('Openmart only.'),
+  has_website: z.boolean().optional().describe('Openmart only.'),
+  has_valid_website: z.boolean().optional().describe('Openmart only.'),
+  has_contact_info: z.boolean().optional().describe('Openmart only.'),
+  min_price_tier: z.number().int().optional().describe('Openmart only. 1–4 (1=$, 4=$$$$).'),
+  max_price_tier: z.number().int().optional().describe('Openmart only.'),
+
+  include_keywords: z.array(z.string()).max(64).optional().describe('Openmart only. Free-text terms that must appear in result fields.'),
+  exclude_keywords: z.array(z.string()).max(64).optional().describe('Openmart only.'),
+  exclude_root_domains: z.array(z.string()).max(10000).optional().describe('Openmart only. Skip results whose website root domain is in this list.'),
+
+  start_urls: z.array(z.string().url()).max(10).optional().describe('Google Maps only. Pre-built google.com/maps URLs (place/search/reviews). Routes to Google Maps only. 1–10 URLs.'),
+  include_opening_hours: z.boolean().optional().describe('Google Maps only. Routes to Google Maps only when set.'),
+  include_additional_info: z.boolean().optional().describe('Google Maps only. Adds amenities/accessibility fields. Routes to Google Maps only when set.'),
+  language: z.string().optional().describe('Google Maps only. ISO 639-1 (e.g. "en", "fr"). Routes to Google Maps only when set.'),
+}
+
+export async function searchPlacesHandler(input: Record<string, unknown>) {
+  const result = await executeWithFallback('search_places', input)
+  if (isExecutionError(result)) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
+  }
+  return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] }
+}

package/src/tools/search-reddit.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod'
+import { executeWithFallback, isExecutionError } from '../executor.js'
+
+export const searchRedditName = 'search_reddit'
+
+export const searchRedditDescription =
+  'Scrape Reddit posts and comments via 1 provider (Reddit Scraper). Requires at least one subreddit or post URL. Optionally filter by keyword query within those URLs. Supports sorting, time filters, comment inclusion. Async (~30–120s). Cost: 1 credit per item returned.'
+
+export const searchRedditSchema = {
+  start_urls: z.array(z.string().url()).min(1).max(25)
+    .describe('Reddit URLs to scrape (subreddit, post, or search URL). At least 1 required. Up to 25. Example: ["https://www.reddit.com/r/sales/"]'),
+  query: z.string().optional()
+    .describe('Optional keyword filter applied within the provided URLs e.g. "best CRM for startups".'),
+  type: z.enum(['posts', 'comments']).default('posts')
+    .describe('Scrape posts or comments.'),
+  sort: z.enum(['relevance', 'hot', 'top', 'new', 'comments']).optional()
+    .describe('Sort order for results.'),
+  time: z.enum(['hour', 'day', 'week', 'month', 'year', 'all']).optional()
+    .describe('Time filter.'),
+  limit: z.number().int().min(1).max(200).default(10)
+    .describe('Max items to return (1–200). 1 credit per item.'),
+  max_comments_per_post: z.number().int().min(1).max(1000).optional()
+    .describe('Max comments per post when type=comments.'),
+  include_comments: z.boolean().optional()
+    .describe('Include comments alongside posts.'),
+}
+
+export async function searchRedditHandler(input: Record<string, unknown>) {
+  const result = await executeWithFallback('search_reddit', input)
+  if (isExecutionError(result)) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
+  }
+  return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] }
+}

package/src/tools/search-seo.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod'
+import { executeWithFallback, isExecutionError } from '../executor.js'
+
+export const searchSeoName = 'search_seo'
+
+export const searchSeoDescription =
+  'Search SEO data — 6 categories. Pick category + required fields:\n' +
+  '• keywords: pass keywords[] — search volume or trends\n' +
+  '• serp: pass keyword (single string) — Google/Bing/YouTube organic results\n' +
+  '• backlinks: pass target (domain or URL) — summary, links, referring domains\n' +
+  '• domain: pass target + action ("technologies" | "whois")\n' +
+  '• labs: pass target for rank-overview/competitors/ranked-keywords; OR pass keywords[] for keyword-ideas\n' +
+  '• page: pass url + page_action ("lighthouse" | "content")\n' +
+  'Optional shared: location, language, limit. All sync. Cost varies by endpoint.'
+
+export const searchSeoSchema = {
+  category: z.enum(['keywords', 'serp', 'backlinks', 'domain', 'labs', 'page'])
+    .describe('Which SEO category to use. Required.'),
+
+  target: z.string().optional()
+    .describe('Domain or URL. Required for: backlinks, domain, labs.'),
+  keyword: z.string().optional()
+    .describe('Single keyword. Required for: serp.'),
+  keywords: z.array(z.string()).optional()
+    .describe('Keyword list. Required for: keywords/search-volume, labs/keyword-ideas.'),
+  location: z.string().optional()
+    .describe('Location name e.g. "United States", "London,England,United Kingdom".'),
+  language: z.string().optional()
+    .describe('Language code e.g. "en".'),
+  limit: z.number().int().min(1).max(700).default(10),
+
+  date_from: z.string().optional().describe('YYYY-MM-DD. keywords/trends.'),
+  date_to: z.string().optional().describe('YYYY-MM-DD. keywords/trends.'),
+  time_range: z.string().optional().describe('keywords/trends: "past_7_days", "past_30_days", etc.'),
+
+  engine: z.enum(['google', 'bing', 'youtube']).default('google'),
+  device: z.enum(['desktop', 'mobile']).optional(),
+
+  action: z.enum(['technologies', 'whois']).optional()
+    .describe('domain: "technologies" (tech stack) or "whois". Default: technologies.'),
+
+  lab_action: z.enum(['ranked-keywords', 'competitors', 'keyword-ideas', 'rank-overview']).optional()
+    .describe('labs action. Default: rank-overview when target set; keyword-ideas when keywords[] set.'),
+
+  url: z.string().url().optional()
+    .describe('Full URL to analyze. Required for page category.'),
+  page_action: z.enum(['lighthouse', 'content']).default('lighthouse')
+    .describe('page: "lighthouse" (Core Web Vitals audit) or "content" (parse page text).'),
+  enable_javascript: z.boolean().optional(),
+  full_data: z.boolean().optional().describe('Lighthouse only: include full audit data.'),
+}
+
+export async function searchSeoHandler(input: Record<string, unknown>) {
+  const result = await executeWithFallback('search_seo', input)
+  if (isExecutionError(result)) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
+  }
+  return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] }
+}

package/src/tools/search-web.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod'
+import { executeWithFallback, isExecutionError } from '../executor.js'
+
+export const searchWebName = 'search_web'
+
+export const searchWebDescription =
+  'Search the web for market research, company news, or general lookups. Supports Google search (default) and neural/semantic search via Exa. ' +
+  'NEVER use this to find, verify, or look up people, contacts, LinkedIn profiles, or executives — even as a fallback when find_people returns uncertain results. ' +
+  'find_people is the only tool for people lookups; do not supplement or replace it with web search.'
+
+export const searchWebSchema = {
+  query: z.string().describe('Search query'),
+  num_results: z.number().min(1).max(100).default(10).describe('Number of results (default: 10, max: 100)'),
+  country: z.string().optional().describe('Country code for geo-targeting (e.g. "us", "fr")'),
+  search_type: z.enum(['general', 'neural']).default('general').describe('"general" for Google search (default), "neural" for semantic search via Exa'),
+}
+
+export async function searchWebHandler(input: Record<string, unknown>) {
+  const result = await executeWithFallback('search_web', input)
+  if (isExecutionError(result)) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
+  }
+  return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] }
+}

package/src/tools/verify-email.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod'
+import { executeWithFallback, isExecutionError } from '../executor.js'
+
+export const verifyEmailName = 'verify_email'
+
+export const verifyEmailDescription =
+  'Check whether an email address is valid and deliverable. Returns verification status (valid, invalid, catch-all, unknown). Use before cold outreach to protect sender reputation.'
+
+export const verifyEmailSchema = {
+  email: z.string().email().describe('Email address to verify'),
+}
+
+export async function verifyEmailHandler(input: Record<string, unknown>) {
+  const result = await executeWithFallback('verify_email', input)
+  if (isExecutionError(result)) {
+    return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }], isError: true }
+  }
+  return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] }
+}

package/test-ads-live.ts

@@ -0,0 +1,77 @@
+import { initClient } from './src/client.js'
+import { searchAdsHandler } from './src/tools/search-ads.js'
+
+const API_URL = 'https://api.coldiq.com'
+const API_KEY = 'ciq_test_3797d4ddc5542ceb'
+
+initClient(API_URL, API_KEY)
+
+async function run(label: string, input: Record<string, unknown>) {
+  console.log(`\n${'─'.repeat(60)}`)
+  console.log(`TEST: ${label}`)
+  console.log(`INPUT: ${JSON.stringify(input)}`)
+  const result = await searchAdsHandler(input)
+  const parsed = JSON.parse(result.content[0].text)
+  if (result.isError) {
+    console.log(`RESULT: ERROR — ${parsed.error}`)
+    if (parsed.providers_tried?.length) {
+      console.log(`PROVIDERS TRIED: ${parsed.providers_tried.map((p: { id: string }) => p.id).join(' → ')}`)
+    }
+    return
+  }
+  const meta = parsed._meta
+  const ads = (parsed.data as { ads?: Array<Record<string, unknown>> }).ads ?? []
+  console.log(`RESULT: provider=${meta.provider} latency=${meta.latencyMs}ms ads=${ads.length}`)
+  for (const a of ads.slice(0, 3)) {
+    console.log(`  • ${a.advertiserName ?? a.advertiser ?? a.page_name ?? '-'} — ${a.title ?? a.headline ?? '-'}`)
+  }
+}
+
+async function main() {
+  // Test 1: Domain → Google only
+  await run('Domain lookup (Google expected)', {
+    domains: ['salesforce.com'],
+    max_results: 10,
+  })
+
+  // Test 2: LinkedIn URL → LinkedIn only
+  await run('LinkedIn URL (LinkedIn expected)', {
+    search_urls: ['https://www.linkedin.com/ad-library/search?accountOwner=salesforce'],
+    max_results: 10,
+  })
+
+  // Test 3: Pin platform=meta with keyword
+  await run('Meta pinned (keyword)', {
+    query: 'HubSpot',
+    platform: 'meta',
+    max_results: 10,
+  })
+
+  // Test 4: Pin platform=twitter with keyword
+  await run('Twitter pinned (keyword)', {
+    query: 'ColdIQ',
+    platform: 'twitter',
+    max_results: 10,
+  })
+
+  // Test 5: Pin platform=reddit with industry filter
+  await run('Reddit pinned (TECH_B2B)', {
+    platform: 'reddit',
+    industry: 'TECH_B2B',
+    query: 'sales automation',
+  })
+
+  // Test 6: Bare query — runs Google → Meta → Twitter → Reddit waterfall
+  await run('Bare query waterfall (Google→Meta→Twitter→Reddit)', {
+    query: 'Stripe',
+    max_results: 10,
+  })
+
+  // Test 7: platform=linkedin without search_urls — no provider applicable
+  await run('LinkedIn pin without URLs (expect failure)', {
+    platform: 'linkedin',
+    query: 'Salesforce',
+  })
+}
+
+main().catch(console.error)

package/test-company-live.ts

@@ -0,0 +1,91 @@
+import { initClient } from './src/client.js'
+import { enrichCompanyHandler } from './src/tools/enrich-company.js'
+
+const API_URL = 'https://api.coldiq.com'
+const API_KEY = 'ciq_test_3797d4ddc5542ceb'
+
+initClient(API_URL, API_KEY)
+
+async function run(label: string, input: Record<string, unknown>) {
+  console.log(`\n${'─'.repeat(60)}`)
+  console.log(`TEST: ${label}`)
+  console.log(`INPUT: ${JSON.stringify(input)}`)
+  const result = await enrichCompanyHandler(input)
+  const parsed = JSON.parse(result.content[0].text)
+  if (result.isError) {
+    console.log(`RESULT: ERROR — ${parsed.error}`)
+    if (parsed.providers_tried?.length) {
+      console.log(`PROVIDERS TRIED: ${parsed.providers_tried.map((p: { id: string }) => p.id).join(' → ')}`)
+    }
+  } else {
+    const meta = parsed._meta
+    const data = parsed.data as Record<string, unknown>
+    console.log(`RESULT: provider=${meta.provider} latency=${meta.latencyMs}ms`)
+    const name = data?.name ?? data?.display_name ?? (data as { organization?: { name?: string } })?.organization?.name ?? '-'
+    const domain = data?.domain ?? data?.website ?? '-'
+    const industry = data?.industry ?? data?.industries ?? '-'
+    const employees = data?.employee_count ?? data?.employees ?? data?.size ?? data?.estimated_num_employees ?? '-'
+    const countryRaw = data?.country ?? data?.hq_country ?? (data?.location as Record<string, unknown>)?.country ?? '-'
+    const country = typeof countryRaw === 'object' && countryRaw !== null
+      ? ((countryRaw as Record<string, unknown>).name ?? JSON.stringify(countryRaw))
+      : countryRaw
+    console.log(`  name=${name} | domain=${domain} | industry=${industry} | employees=${employees} | country=${country}`)
+  }
+}
+
+async function main() {
+  // Test 1: Well-known company by domain — should hit CompanyEnrich first
+  await run('Well-known domain (stripe.com)', {
+    domain: 'stripe.com',
+  })
+
+  // Test 2: Small company by domain — exercises later fallbacks
+  await run('Small company domain (coldiq.com)', {
+    domain: 'coldiq.com',
+  })
+
+  // Test 3: LinkedIn URL only — skips CompanyEnrich GET and Apollo
+  await run('LinkedIn URL only (stripe)', {
+    linkedin_url: 'https://www.linkedin.com/company/stripe',
+  })
+
+  // Test 4: Company name only — only PDL / Findymail / Prospeo / CompanyEnrich POST eligible
+  await run('Name only (Stripe)', {
+    name: 'Stripe',
+  })
+
+  // Test 5: Domain + LinkedIn URL together — best-case identifier set
+  await run('Domain + LinkedIn URL (Stripe)', {
+    domain: 'stripe.com',
+    linkedin_url: 'https://www.linkedin.com/company/stripe',
+  })
+
+  // Test 6: All three identifiers
+  await run('All three identifiers (Stripe)', {
+    domain: 'stripe.com',
+    linkedin_url: 'https://www.linkedin.com/company/stripe',
+    name: 'Stripe',
+  })
+
+  // Test 7: Bogus domain — should exhaust the applicable waterfall
+  await run('Bogus domain (should fail all providers)', {
+    domain: 'zzznotreal-fake-domain-12345.example',
+  })
+
+  // Test 8: BuiltWith fallback — small domain that top providers may not index,
+  // but BuiltWith scrapes any live site. Check _meta.provider in output.
+  await run('BuiltWith fallback candidate (plotly.com)', {
+    domain: 'plotly.com',
+  })
+
+  // Test 9: Openmart fallback — retail/SMB brand Openmart specializes in.
+  // Check _meta.provider to see if Openmart is reached or an earlier provider wins.
+  await run('Openmart fallback candidate (allbirds.com)', {
+    domain: 'allbirds.com',
+  })
+
+  // Test 10: No identifiers — should return guard error before any provider is tried
+  await run('No identifiers (expect guard error)', {})
+}
+
+main().catch(console.error)

package/test-email-live.ts

@@ -0,0 +1,171 @@
+import { initClient } from './src/client.js'
+import { enrichEmailHandler } from './src/tools/enrich-email.js'
+import { enrichEmailsHandler } from './src/tools/enrich-emails.js'
+import { verifyEmailHandler } from './src/tools/verify-email.js'
+
+const API_URL = 'https://api.coldiq.com'
+const API_KEY = 'ciq_test_3797d4ddc5542ceb'
+
+initClient(API_URL, API_KEY)
+
+type Handler = (input: Record<string, unknown>) => Promise<{
+  content: Array<{ type: string; text: string }>
+  isError?: boolean
+}>
+
+function pickEmail(data: unknown): string | null {
+  if (!data || typeof data !== 'object') return null
+  const d = data as Record<string, unknown>
+  if (typeof d.email === 'string' && d.email.includes('@')) return d.email
+  if (Array.isArray(d.emails) && typeof d.emails[0] === 'string' && d.emails[0].includes('@')) return d.emails[0] as string
+  const person = d.person as Record<string, unknown> | undefined
+  const emailObj = person?.email as Record<string, unknown> | undefined
+  if (typeof emailObj?.email === 'string' && emailObj.email.includes('@')) return emailObj.email as string
+  const inner = d.data as unknown
+  if (Array.isArray(inner) && inner[0]) {
+    const emails = (inner[0] as Record<string, unknown>).emails
+    if (Array.isArray(emails) && typeof emails[0] === 'string') return emails[0] as string
+  }
+  return null
+}
+
+async function run(label: string, handler: Handler, input: Record<string, unknown>) {
+  console.log(`\n${'─'.repeat(60)}`)
+  console.log(`TEST: ${label}`)
+  console.log(`INPUT: ${JSON.stringify(input)}`)
+  const result = await handler(input)
+  const parsed = JSON.parse(result.content[0].text)
+
+  if (result.isError) {
+    console.log(`RESULT: ERROR — ${parsed.error}`)
+    if (Array.isArray(parsed.providers_tried)) {
+      console.log(`PROVIDERS TRIED (${parsed.providers_tried.length}):`)
+      for (const p of parsed.providers_tried) {
+        console.log(`  • ${p.id}: status=${p.status ?? '?'} error=${p.error ?? '-'}`)
+      }
+    }
+    return
+  }
+
+  const meta = parsed._meta
+  if (meta) {
+    console.log(`RESULT: provider=${meta.provider} latency=${meta.latencyMs}ms`)
+    const email = pickEmail(parsed.data)
+    if (email) {
+      console.log(`EMAIL: ${email}`)
+    } else {
+      const d = parsed.data as Record<string, unknown>
+      const status = d.status ?? d.result ?? d.valid ?? d.state
+      if (status !== undefined) console.log(`STATUS: ${JSON.stringify(status)}`)
+    }
+  } else {
+    // enrich_emails batch — no _meta
+    const { results, found, total } = parsed.data
+    console.log(`RESULT: found=${found}/${total}`)
+    for (const r of results) {
+      console.log(`  • ${r.id}: email=${r.email ?? 'null'} provider=${r.provider ?? 'null'}`)
+    }
+  }
+}
+
+async function main() {
+  // ── enrich_email: 8-provider waterfall ────────────────────────────────────
+
+  // Test 1: Happy path — name + domain
+  // Expected: findymail (priority 1) wins. blitzapi + limadata-work-email-linkedin skipped (no linkedin_url).
+  await run('enrich_email — happy path (name + domain)', enrichEmailHandler, {
+    first_name: 'Michel',
+    last_name: 'Lieben',
+    domain: 'coldiq.com',
+  })
+
+  // Test 2: Name + company_name, no domain
+  // Expected: limadata-work-email skipped (requires domain). icypeas (priority 2) likely wins via company_name.
+  await run('enrich_email — name + company_name, no domain (Satya Nadella / Microsoft)', enrichEmailHandler, {
+    first_name: 'Satya',
+    last_name: 'Nadella',
+    company_name: 'Microsoft',
+  })
+
+  // Test 3: LinkedIn URL + name, no domain
+  // Expected: limadata-work-email skipped (no domain). prospeo (priority 4) likely wins via linkedin_url.
+  // blitzapi + limadata-work-email-linkedin are now eligible (have linkedin_url).
+  await run('enrich_email — linkedin_url + name, no domain', enrichEmailHandler, {
+    first_name: 'Michel',
+    last_name: 'Lieben',
+    linkedin_url: 'https://www.linkedin.com/in/michel-lieben',
+  })
+
+  // Test 4: Full input — all 8 providers eligible
+  // Expected: findymail wins. Debug trace shows 0 skips.
+  await run('enrich_email — full input (all 8 providers eligible)', enrichEmailHandler, {
+    first_name: 'Michel',
+    last_name: 'Lieben',
+    domain: 'coldiq.com',
+    company_name: 'ColdIQ',
+    linkedin_url: 'https://www.linkedin.com/in/michel-lieben',
+  })
+
+  // Test 5: Forced fallthrough — fake name at real domain
+  // Expected: providers 1-3 miss (no such person), waterfall marches to prospeo/fullenrich/linkupapi.
+  // Most important scenario for confirming priority order. fullenrich may add 5-10s (async poll).
+  await run('enrich_email — forced fallthrough (fake name at coldiq.com)', enrichEmailHandler, {
+    first_name: 'Zerphus',
+    last_name: 'Mclaren',
+    domain: 'coldiq.com',
+  })
+
+  // Test 6: Total failure — fabricated person + nonexistent domain
+  // Expected: isError=true, providers_tried.length === 6 (skips blitzapi + limadata-work-email-linkedin).
+  await run('enrich_email — total failure (fake person + nonexistent domain)', enrichEmailHandler, {
+    first_name: 'Zerphus',
+    last_name: 'Mclaren',
+    domain: 'this-domain-does-not-exist-zxcv.io',
+  })
+
+  // ── enrich_emails: 3-stage batch waterfall ────────────────────────────────
+
+  // Test 7: Mixed batch — all 3 stages
+  // michel: Prospeo stage 1 via linkedin_url (most likely)
+  // satya: FullEnrich stage 2 or FindyMail stage 3 (no linkedin_url)
+  // fake-person: provider=null expected
+  await run('enrich_emails — mixed batch (Prospeo → FullEnrich → FindyMail/IcyPeas)', enrichEmailsHandler, {
+    people: [
+      {
+        id: 'michel',
+        first_name: 'Michel',
+        last_name: 'Lieben',
+        domain: 'coldiq.com',
+        linkedin_url: 'https://www.linkedin.com/in/michel-lieben',
+      },
+      {
+        id: 'satya',
+        first_name: 'Satya',
+        last_name: 'Nadella',
+        domain: 'microsoft.com',
+      },
+      {
+        id: 'fake-person',
+        first_name: 'Zerphus',
+        last_name: 'Mclaren',
+        domain: 'coldiq.com',
+      },
+    ],
+  })
+
+  // ── verify_email: findymail → icypeas waterfall ───────────────────────────
+
+  // Test 8: Known-valid email
+  // Expected: findymail wins; response has a status/result/valid field.
+  await run('verify_email — valid email (michel@coldiq.com)', verifyEmailHandler, {
+    email: 'michel@coldiq.com',
+  })
+
+  // Test 9: Nonexistent email
+  // Expected: findymail returns an invalid status (still counts as hasResult → wins immediately).
+  await run('verify_email — invalid email (noreply-zzz-9999@coldiq.com)', verifyEmailHandler, {
+    email: 'noreply-zzz-9999@coldiq.com',
+  })
+}
+
+main().catch(console.error)