feat(integrations): hosted API keys for Findymail, Prospeo, and Wiza

[TheodoreSpeaks]

Summary

• Add hosted-key support across all credit-consuming Findymail (9 ops), Prospeo (6 ops), and Wiza ops, so Sim provides the key when a workspace hasn't brought its own; usage is metered per each provider's credit model
• Register findymail / prospeo / wiza as BYOK providers (type union, contract enum, settings UI)
• Consolidate Wiza's two-step start/get individual reveal into a single wiza_individual_reveal op that starts then polls to completion (removes the old two tools)
• Hide the API key field on hosted Sim for hosted ops via the duplicate-apiKey pattern; keep it visible for the balance/account lookups
• Per-provider hosting factories with documented $/credit rates; getCost bills only on success/match

Type of Change

• New feature

Testing

• bunx tsc --noEmit clean; bun run check:api-validation:strict passed; biome clean
• Added tools/enrichment-hosting.test.ts (16 tests, incl. Wiza poll-to-completion); blocks.test.ts (82) passing

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Skipped		May 29, 2026 7:51pm

[cursor]

PR Summary

High Risk
Changes hosted billing, metered credits, and a breaking Wiza tool consolidation; enrichment waterfalls alter which third-party APIs run and when users must supply keys.

Overview
Adds hosted API keys for Findymail, Prospeo, and Wiza: credit-based hosting on paid tools, env prefixes (FINDYMAIL_API_KEY, etc.), and BYOK registration in contracts, types, and workspace settings.

On hosted Sim, API key fields are hidden for billable ops (hideWhenHosted + conditional duplicate apiKey subblocks); credit/account lookups still require a user key.

Wiza replaces Start + Get Individual Reveal with one wiza_individual_reveal that POSTs and polls until finished (with transient error retries).

Work email and phone number enrichments gain multi-provider waterfalls (Hunter/Findymail/Prospeo/Wiza/PDL), optional LinkedIn URL, and optional company domain for work email.

Tests cover hosting pricing and cascade buildParams/mapOutput.

^{Reviewed by Cursor Bugbot for commit b378e88. Bugbot is set up for automated code reviews on this repo. Configure here.}

[greptile-apps]

Greptile Summary

This PR adds hosted API key support for Findymail (9 ops), Prospeo (6 ops), and Wiza, registers all three as BYOK providers, and consolidates Wiza's two-step individual reveal into a single polling op (wiza_individual_reveal). Each provider gets its own billing factory with a per-credit USD rate, and the Wiza poller addresses the transient-error and early-terminal concerns raised in a parallel branch.

• Hosted key infrastructure: Three *hosting.ts factories with documented $/credit rates; getCost is wired to each tool's output shape so billing fires only on successful data returns.
• Wiza individual reveal consolidation: Replaces start_individual_reveal + get_individual_reveal with a single wiza_individual_reveal that starts the reveal, skips polling on cache hits, tolerates up to 3 consecutive transient HTTP errors, and returns an explicit failure after the 120 s window.
• BYOK registry: byok-keys.ts Zod enum, tools/types.ts union, and byok.tsx UI all updated with entries for findymail, prospeo, and wiza; API key visibility correctly uses user-only throughout.

Confidence Score: 5/5

Safe to merge; all changes are additive hosting wiring and the Wiza consolidation is well-tested with no regressions on existing tools.

The PR is purely additive — new billing factories, BYOK registration, and the Wiza individual-reveal consolidation. The polling logic correctly handles the early-terminal and transient-error cases flagged in prior review. The two observations flagged are not reachable through the normal execution path and do not affect correctness in production.

No files require special attention, though bulk_enrich_person.ts and bulk_enrich_company.ts carry a throw inside getCost that is inconsistent with the defensive return-0 pattern used by every other tool in this PR.

Important Files Changed

Filename	Overview
apps/sim/tools/wiza/individual_reveal.ts	New combined start-and-poll tool replacing the two-step reveal pair; previous thread issues (transient error retries, early terminal check) are now addressed; minor: elapsed-time tracking counts sleep intervals only, not HTTP latency
apps/sim/tools/wiza/hosting.ts	New per-credit billing factory for Wiza; documented rate constant, correct env-var prefix pattern, and sane rate-limit config
apps/sim/tools/findymail/hosting.ts	New per-credit billing factory for Findymail; consistent shape with Wiza and Prospeo factories
apps/sim/tools/prospeo/hosting.ts	New per-credit billing factory for Prospeo; consistent with sibling factories
apps/sim/tools/prospeo/bulk_enrich_person.ts	Adds hosting config; getCost throws on missing total_cost (unreachable in practice but inconsistent with findymail sibling pattern)
apps/sim/tools/prospeo/bulk_enrich_company.ts	Adds hosting config; same throw-on-missing-total_cost issue as bulk_enrich_person
apps/sim/lib/api/contracts/byok-keys.ts	Adds findymail, prospeo, and wiza to the Zod enum and corresponding type union; consistent with existing pattern
apps/sim/app/workspace/[workspaceId]/settings/components/byok/byok.tsx	Adds Findymail, Prospeo, and Wiza entries to the PROVIDERS array with correct icons and placeholders; no logic changes
apps/sim/tools/enrichment-hosting.test.ts	Good coverage: 16 tests for pricing across all three providers plus Wiza poll-to-completion, transient error retry, and early-terminal detection
apps/sim/blocks/blocks/wiza.ts	Replaces two-step reveal operations with single wiza_individual_reveal; duplicate-apiKey pattern correctly hides the key for hosted ops while keeping it visible for get_credits

Sequence Diagram

sequenceDiagram
    participant Executor
    participant HostingFramework
    participant WizaAPI

    Executor->>WizaAPI: POST /individual_reveals (start)
    WizaAPI-->>Executor: "{ id, status: queued }"

    alt Already terminal (cache hit)
        Executor-->>Executor: return immediately (no poll)
    else Needs polling
        loop Every 2s (up to 120s)
            Executor->>WizaAPI: "GET /individual_reveals/{id}"
            WizaAPI-->>Executor: "{ status }"
            alt Transient error (up to 3 consecutive)
                Executor-->>Executor: increment error counter, retry
            else Terminal (finished / failed)
                Executor-->>Executor: return result
            else Timeout
                Executor-->>Executor: return failure
            end
        end
    end

    Executor->>HostingFramework: getCost(params, output)
    HostingFramework-->>Executor: credits x $0.025

Loading

_{Reviews (2): Last reviewed commit: "feat(enrichments): add Findymail, Prospe..." | Re-trigger Greptile}

[TheodoreSpeaks]

Addressed the Greptile + Cursor Bugbot review in ad96c6ea6:

• Bugbot (High) — silent incomplete reveal (wiza/individual_reveal.ts): postProcess now returns { success: false, error } on timeout / id-missing / repeated poll errors instead of throwing. Thrown errors were swallowed by the executor and masked as the queued (incomplete) success: true result. Mirrors the Brightdata discover pattern.
• Greptile P1 — transient poll error aborts the window: poll loop now tolerates up to 3 consecutive 5xx/429 responses (retrying within the 120s window) before giving up, so a brief Wiza outage no longer kills an already-billed reveal.
• Greptile P2 — initial response not checked for terminal state: postProcess short-circuits and returns immediately when the initial POST payload is already finished/failed/is_complete (e.g. a cache hit), avoiding a needless 2s poll.
• Greptile P2 — getCost throws on missing array (findymail/find_emails_by_domain.ts, find_employees.ts): now returns 0 when the contacts/employees array is absent (no contacts = no charge) instead of throwing in billing code. Applied both inline suggestions.

Added 3 regression tests in tools/enrichment-hosting.test.ts (initial-terminal short-circuit, transient-retry-then-resolve, repeated-errors-return-failure). tsc, check:api-validation:strict, biome, and the 19-test suite all pass.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit ad96c6e. Configure here.}

[TheodoreSpeaks]

@greptile review