NEXUS Hunter.io & Tomba OSINT

Technical summary

NEXUS Hunter.io & Tomba OSINT discovers public emails and job titles for a domain using two independent sources — Hunter.io and Tomba.io — with automatic provider fallback, a simulation mode for staging without spending credits and a 30-day local cache. It ships automatic domain enrichment through the Intelligence Hub (priority 52).

Executed scope

• Plugin registration (registerTab('huntertomba','Hunter & Tomba OSINT','globe',tab.php,'OSINT & Enrichment') + registerDoc + registerJs for assets/huntertomba.js) and huntertomba_install() creating the hunter_tomba_domains table (domain PK, provider, pattern, emails_count, emails_data LONGTEXT, timestamps).
• 5 API actions: huntertomba_stats (cached domains + key status), huntertomba_query (manual domain lookup), huntertomba_delete (cache removal), huntertomba_settings_save (keys + fallback mode + auto_enrich, with a __KEEP__ sentinel to avoid overwriting unchanged keys) and huntertomba_list_cached (paginated cache list).
• Fallback strategy with 3 modes (provider): fallback (recommended — tries Hunter.io first and, if the key is missing/expired/over quota, fails over automatically to Tomba.io), hunter (exclusive) and tomba (exclusive).
• Hunter.io API v2 integration: GET https://api.hunter.io/v2/domain-search?domain=&api_key=, normalizing up to 15 emails (first/last name, title, confidence, up to 2 sources each) plus the estimated email pattern; free plan with 25 searches/month.
• Tomba.io API v1 integration: GET https://api.tomba.io/v1/domain-search with X-Tomba-Key/X-Tomba-Secret headers; same normalized fields; basic plan with 50 requests/month.
• Simulation mode (no keys): test simulation keys or no keys at all generate a realistic mock (huntertomba_generate_mock(): {first}.{last}@domain pattern, people with titles and LinkedIn/site sources) with provider=simulated_mock — ideal for staging without spending credits.
• Smart local cache: successful external queries are persisted to hunter_tomba_domains with a 30-day expiration; cached domains answer in <1ms with zero API quota usage (ON DUPLICATE KEY UPDATE refreshes the record).
• Enrichment (Intelligence Hub): nx_intel_register_enricher('huntertomba', ['domain'], 'huntertomba_intel_enrich', 52) publishes signals with email count/provider/pattern and severity 20; a needs_key signal when no provider is configured; honors the max_live_lookups budget (default 12, slicing at most 3 domains per run) and marks the rest as skipped.
• On-demand only: cronjob.json with jobs: [] (no periodic routine needed); no CLI.
• Fast Responses: fastr.json manifest with /huntertomba <domain> (required arg), huntertomba_query action.
• UI (tab.php, 325 lines, Alpine hunterTombaTab() + assets/huntertomba.js): API Online/Offline badge based on configured keys, Hunter/Tomba status cards, manual lookup with demo shortcuts (stripe.com/netflix.com), settings section with provider selector and password key fields, result with provider/pattern/count and an emails table with titles and sources, plus a local-cache table with load/remove and pagination.

Stack and tools

• PHP 8 backend (no framework) + MySQL 8 (hunter_tomba_domains)
• Hunter.io API v2 (domain-search) + Tomba.io API v1 (domain-search, key/secret headers)
• Alpine.js + Tailwind CSS (tab.php) + helper JS (assets/huntertomba.js)
• Internal Plugin API (PluginManager tabs/actions + fastr.json + enricher)

Operational tags

• Hunter.io
• Tomba.io
• OSINT
• Email
• Domain
• Enrichment
• Fallback
• NEXUS Plugin

Operational result

• Two independent sources: Hunter.io and Tomba.io widen domain email/title coverage and reduce single points of failure.
• Automatic fallback: if the preferred provider fails (missing key, expired or over quota), the lookup flows to the second one with no manual intervention.
• Free staging: simulation mode generates realistic mocks to test the whole flow without spending real credits.
• 30-day cache: repeated queries answer in under 1ms and do not consume API quota.
• Automatic enrichment: domains mentioned in tasks/comments gain email and title signals via the Intelligence Hub.
• Budget control: enrichment honors max_live_lookups and signals needs_key/skipped when needed.