feat(hosted-keys): add Hunter.io and People Data Labs hosted key support (#4742)

* fix(db): disable statement_timeout for migrations

* fix(ci): route migration workflow through guarded migrate.ts

* feat(hosted-keys): add Hunter.io and People Data Labs hosted key support

Author: TheodoreSpeaks

apps/sim/.env.example

@@ -62,6 +62,15 @@ API_ENCRYPTION_KEY=your_api_encryption_key # Use `openssl rand -hex 32` to gener
 # COHERE_API_KEY=                               # Cohere API key for the Knowledge block reranker (rerank-v4.0-pro/-fast, rerank-v3.5). Alternatively set COHERE_API_KEY_1/2/3 for rotation.
 # NEXT_PUBLIC_COHERE_CONFIGURED=true            # Set when COHERE_API_KEY (or rotation keys) are pre-configured above. Hides the Cohere API Key field on the Knowledge block UI.
 
+# Hosted tool API keys (Optional - lets Sim supply the key so users don't have to bring their own).
+# Each provider reads `{PREFIX}_COUNT` then `{PREFIX}_1..N`, distributing requests round-robin across the keys.
+# HUNTER_API_KEY_COUNT=2                         # Number of Hunter.io keys for hosted Hunter blocks
+# HUNTER_API_KEY_1=                              # Hunter.io API key #1
+# HUNTER_API_KEY_2=                              # Hunter.io API key #2
+# PEOPLEDATALABS_API_KEY_COUNT=2                 # Number of People Data Labs keys for hosted PDL blocks
+# PEOPLEDATALABS_API_KEY_1=                      # People Data Labs API key #1
+# PEOPLEDATALABS_API_KEY_2=                      # People Data Labs API key #2
+
 # Admin API (Optional - for self-hosted GitOps)
 # ADMIN_API_KEY=  # Use `openssl rand -hex 32` to generate. Enables admin API for workflow export/import.
                   # Usage: curl -H "x-admin-key: your_key" https://your-instance/api/v1/admin/workspaces

apps/sim/app/workspace/[workspaceId]/settings/components/byok/byok.tsx

@@ -23,12 +23,14 @@ import {
   FireworksIcon,
   GeminiIcon,
   GoogleIcon,
+  HunterIOIcon,
   ImageIcon,
   JinaAIIcon,
   LinkupIcon,
   MistralIcon,
   OpenAIIcon,
   ParallelIcon,
+  PeopleDataLabsIcon,
   PerplexityIcon,
   SerperIcon,
 } from '@/components/icons'
@@ -156,6 +158,20 @@ const PROVIDERS: {
     description: 'Brand assets, logos, colors, and company info',
     placeholder: 'Enter your Brandfetch API key',
   },
+  {
+    id: 'hunter',
+    name: 'Hunter',
+    icon: HunterIOIcon,
+    description: 'Email finder, verification, and domain search',
+    placeholder: 'Enter your Hunter.io API key',
+  },
+  {
+    id: 'peopledatalabs',
+    name: 'People Data Labs',
+    icon: PeopleDataLabsIcon,
+    description: 'Person and company enrichment, search, and identity',
+    placeholder: 'Enter your People Data Labs API key',
+  },
 ]
 
 export function BYOK() {

apps/sim/blocks/blocks/hunter.ts

@@ -256,6 +256,7 @@ Return ONLY the search query text - no explanations.`,
       required: true,
       placeholder: 'Enter your Hunter.io API key',
       password: true,
+      hideWhenHosted: true,
     },
   ],
   tools: {

apps/sim/blocks/blocks/peopledatalabs.ts

@@ -397,6 +397,7 @@ export const PeopleDataLabsBlock: BlockConfig<PdlPersonEnrichResponse> = {
       placeholder: 'Enter your People Data Labs API key',
       password: true,
       required: true,
+      hideWhenHosted: true,
     },
   ],
 

apps/sim/lib/api/contracts/byok-keys.ts

@@ -18,6 +18,8 @@ export const byokProviderIdSchema = z.enum([
   'parallel_ai',
   'brandfetch',
   'cohere',
+  'hunter',
+  'peopledatalabs',
 ])
 
 export const byokKeySchema = z.object({

apps/sim/tools/hunter/companies_find.ts

@@ -1,4 +1,5 @@
 import type { HunterEnrichmentParams, HunterEnrichmentResponse } from '@/tools/hunter/types'
+import { HUNTER_API_KEY_PREFIX } from '@/tools/hunter/types'
 import type { ToolConfig } from '@/tools/types'
 
 export const companiesFindTool: ToolConfig<HunterEnrichmentParams, HunterEnrichmentResponse> = {
@@ -7,6 +8,18 @@ export const companiesFindTool: ToolConfig<HunterEnrichmentParams, HunterEnrichm
   description: 'Enriches company data using domain name.',
   version: '1.0.0',
 
+  hosting: {
+    envKeyPrefix: HUNTER_API_KEY_PREFIX,
+    apiKeyParam: 'apiKey',
+    byokProviderId: 'hunter',
+    // Companies Find (enrichment) is free on Hunter — no credits consumed.
+    pricing: { type: 'per_request', cost: 0 },
+    rateLimit: {
+      mode: 'per_request',
+      requestsPerMinute: 60,
+    },
+  },
+
   params: {
     domain: {
       type: 'string',

apps/sim/tools/hunter/discover.ts

@@ -1,5 +1,5 @@
 import type { HunterDiscoverParams, HunterDiscoverResponse } from '@/tools/hunter/types'
-import { DISCOVER_RESULTS_OUTPUT } from '@/tools/hunter/types'
+import { DISCOVER_RESULTS_OUTPUT, HUNTER_API_KEY_PREFIX } from '@/tools/hunter/types'
 import type { ToolConfig } from '@/tools/types'
 
 export const discoverTool: ToolConfig<HunterDiscoverParams, HunterDiscoverResponse> = {
@@ -8,6 +8,18 @@ export const discoverTool: ToolConfig<HunterDiscoverParams, HunterDiscoverRespon
   description: 'Returns companies matching a set of criteria using Hunter.io AI-powered search.',
   version: '1.0.0',
 
+  hosting: {
+    envKeyPrefix: HUNTER_API_KEY_PREFIX,
+    apiKeyParam: 'apiKey',
+    byokProviderId: 'hunter',
+    // Discover is free on Hunter — no credits consumed.
+    pricing: { type: 'per_request', cost: 0 },
+    rateLimit: {
+      mode: 'per_request',
+      requestsPerMinute: 30,
+    },
+  },
+
   params: {
     query: {
       type: 'string',

apps/sim/tools/hunter/domain_search.ts

@@ -3,7 +3,11 @@ import type {
   HunterDomainSearchResponse,
   HunterEmail,
 } from '@/tools/hunter/types'
-import { EMAILS_OUTPUT } from '@/tools/hunter/types'
+import {
+  EMAILS_OUTPUT,
+  HUNTER_API_KEY_PREFIX,
+  HUNTER_SEARCH_CREDIT_USD,
+} from '@/tools/hunter/types'
 import type { ToolConfig } from '@/tools/types'
 
 export const domainSearchTool: ToolConfig<HunterDomainSearchParams, HunterDomainSearchResponse> = {
@@ -12,6 +16,28 @@ export const domainSearchTool: ToolConfig<HunterDomainSearchParams, HunterDomain
   description: 'Returns all the email addresses found using one given domain name, with sources.',
   version: '1.0.0',
 
+  hosting: {
+    envKeyPrefix: HUNTER_API_KEY_PREFIX,
+    apiKeyParam: 'apiKey',
+    byokProviderId: 'hunter',
+    pricing: {
+      type: 'custom',
+      getCost: (_params, output) => {
+        const emails = output.emails
+        if (!Array.isArray(emails)) {
+          throw new Error('Hunter domain search response missing emails, cannot determine cost')
+        }
+        // Hunter counts one search credit only when a call returns at least one result.
+        const cost = emails.length > 0 ? HUNTER_SEARCH_CREDIT_USD : 0
+        return { cost, metadata: { credits: cost > 0 ? 1 : 0, emails: emails.length } }
+      },
+    },
+    rateLimit: {
+      mode: 'per_request',
+      requestsPerMinute: 60,
+    },
+  },
+
   params: {
     domain: {
       type: 'string',

apps/sim/tools/hunter/email_count.ts

@@ -1,5 +1,5 @@
 import type { HunterEmailCountParams, HunterEmailCountResponse } from '@/tools/hunter/types'
-import { DEPARTMENT_OUTPUT, SENIORITY_OUTPUT } from '@/tools/hunter/types'
+import { DEPARTMENT_OUTPUT, HUNTER_API_KEY_PREFIX, SENIORITY_OUTPUT } from '@/tools/hunter/types'
 import type { ToolConfig } from '@/tools/types'
 
 export const emailCountTool: ToolConfig<HunterEmailCountParams, HunterEmailCountResponse> = {
@@ -8,6 +8,18 @@ export const emailCountTool: ToolConfig<HunterEmailCountParams, HunterEmailCount
   description: 'Returns the total number of email addresses found for a domain or company.',
   version: '1.0.0',
 
+  hosting: {
+    envKeyPrefix: HUNTER_API_KEY_PREFIX,
+    apiKeyParam: 'apiKey',
+    byokProviderId: 'hunter',
+    // Email Count is free on Hunter — no credits consumed.
+    pricing: { type: 'per_request', cost: 0 },
+    rateLimit: {
+      mode: 'per_request',
+      requestsPerMinute: 60,
+    },
+  },
+
   params: {
     domain: {
       type: 'string',

apps/sim/tools/hunter/email_finder.ts

@@ -1,5 +1,10 @@
 import type { HunterEmailFinderParams, HunterEmailFinderResponse } from '@/tools/hunter/types'
-import { SOURCES_OUTPUT, VERIFICATION_OUTPUT } from '@/tools/hunter/types'
+import {
+  HUNTER_API_KEY_PREFIX,
+  HUNTER_SEARCH_CREDIT_USD,
+  SOURCES_OUTPUT,
+  VERIFICATION_OUTPUT,
+} from '@/tools/hunter/types'
 import type { ToolConfig } from '@/tools/types'
 
 export const emailFinderTool: ToolConfig<HunterEmailFinderParams, HunterEmailFinderResponse> = {
@@ -9,6 +14,25 @@ export const emailFinderTool: ToolConfig<HunterEmailFinderParams, HunterEmailFin
     'Finds the most likely email address for a person given their name and company domain.',
   version: '1.0.0',
 
+  hosting: {
+    envKeyPrefix: HUNTER_API_KEY_PREFIX,
+    apiKeyParam: 'apiKey',
+    byokProviderId: 'hunter',
+    pricing: {
+      type: 'custom',
+      getCost: (_params, output) => {
+        // Hunter counts one search credit only when an email is found.
+        const found = typeof output.email === 'string' && output.email.length > 0
+        const cost = found ? HUNTER_SEARCH_CREDIT_USD : 0
+        return { cost, metadata: { credits: found ? 1 : 0 } }
+      },
+    },
+    rateLimit: {
+      mode: 'per_request',
+      requestsPerMinute: 60,
+    },
+  },
+
   params: {
     domain: {
       type: 'string',