Skip to content

feat: add Hunter.io integration (closes #14)#71

Open
jackulau wants to merge 1 commit into
wespreadjam:mainfrom
jackulau:14
Open

feat: add Hunter.io integration (closes #14)#71
jackulau wants to merge 1 commit into
wespreadjam:mainfrom
jackulau:14

Conversation

@jackulau

@jackulau jackulau commented Apr 10, 2026

Copy link
Copy Markdown

Summary

Adds the Hunter.io integration to @jam-nodes/nodes with three operations for email discovery and verification, plus an API key credential definition. Follows the established defineNode() pattern used by existing integrations (Airtable, Slack, Apollo).

Operations

  • hunterDomainSearchNode — searches all email addresses associated with a domain. Supports optional filters for limit (1-100), type (personal/generic), seniority (junior/senior/executive), and department (sales/marketing/hr/it/finance/executive). Calls GET https://api.hunter.io/v2/domain-search.
  • hunterEmailFinderNode — finds the email address of a specific person at a domain given their first and last name. Returns email, confidence score, position, and company. Calls GET https://api.hunter.io/v2/email-finder.
  • hunterEmailVerifierNode — verifies the deliverability of an email address. Returns status, score, and 8 boolean verification fields (regexp, gibberish, disposable, webmail, mxRecords, smtpServer, smtpCheck, acceptAll). Calls GET https://api.hunter.io/v2/email-verifier.

Design

  • API key authentication via query parameter (?api_key=...), using defineApiKeyCredential with authenticate.type: 'query'
  • URLSearchParams for all query string construction (handles URL-encoding of special characters in names like O'Brien)
  • Snake_case API response fields mapped to camelCase outputs per-field (e.g., first_namefirstName, mx_recordsmxRecords, extracted_onextractedOn)
  • Zod z.enum() validation on constrained input fields (type, seniority, department) to catch invalid values before calling the API
  • Structured error returns ({ success: false, error }) consistent with other integrations — never lets HTTP failures propagate silently

Closes #14

Files Changed

New files (7):

  • packages/nodes/src/integrations/hunter/credentials.tshunterCredential definition with query-param auth and testRequest pointing to /account
  • packages/nodes/src/integrations/hunter/schemas.ts — Zod input/output schemas and inferred types for all 3 operations
  • packages/nodes/src/integrations/hunter/hunter-domain-search.ts — domain search node implementation with full email/source camelCase mapping
  • packages/nodes/src/integrations/hunter/hunter-email-finder.ts — email finder node implementation
  • packages/nodes/src/integrations/hunter/hunter-email-verifier.ts — email verifier node implementation with all 10 fields mapped
  • packages/nodes/src/integrations/hunter/index.ts — barrel export for all nodes, schemas, types, and credential
  • packages/nodes/src/integrations/hunter/__tests__/hunter.test.ts — 47 tests (credentials, schemas, all 3 nodes, integration flow)

Modified files (3):

  • packages/core/src/types/node.ts — added hunter?: { apiKey: string } to the NodeCredentials interface
  • packages/nodes/src/integrations/index.ts — re-exports Hunter nodes, schemas, types, and credential from the integrations barrel
  • packages/nodes/src/index.ts — adds Hunter exports to the main package index and includes the 3 nodes in the builtInNodes array

Acceptance Criteria

  • Credential definition with Zod schema
  • All 3 operations implemented
  • Zod schemas for inputs/outputs
  • Unit tests
  • Error handling

Test Plan

  • 47 new Hunter tests (credentials, schemas, all 3 nodes, integration flow)
  • Happy path for each operation with mocked Hunter.io responses
  • Error paths: 401, 429, 5xx, network errors, missing credentials
  • URL parameter verification (api_key in query, snake_case params, URL-encoding of special chars)
  • snake_case -> camelCase output mapping verified
  • Empty results handling
  • Integration test: domain search -> email finder -> email verifier flow
  • All 278 tests pass (231 baseline + 47 new, zero regressions)
  • Typecheck passes for Hunter files

Add Hunter.io email finder and verifier integration (issue wespreadjam#14):
- hunterDomainSearchNode: search emails by domain with filters
- hunterEmailFinderNode: find email for person at domain
- hunterEmailVerifierNode: verify email deliverability
- hunterCredential: API key auth via query parameter
- 47 tests covering all operations, errors, and edge cases

Spec: tasks/hunter-io-integration/spec.md
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Integration] Hunter.io - Email finder and verifier

1 participant