Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 26 additions & 14 deletions ARCHITECTURE.md

Large diffs are not rendered by default.

8 changes: 4 additions & 4 deletions CLAUDE.md

Large diffs are not rendered by default.

5 changes: 5 additions & 0 deletions openoutfind/core/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,11 @@ class SiteConfig:
# paid email lookup behind `--emails`.
bettercontact_api_key: str = ""

# FullEnrich's key powers the paid email lookup behind `--emails` and nothing else.
# Discovery stays on BetterContact's Lead Finder, so a FullEnrich-only install can
# resolve an address but cannot search (core/readiness.py: REQUIRED_DISCOVERY_FIELDS).
fullenrich_api_key: str = ""

# The operator's own ISO-3166 alpha-2 jurisdiction — not to be confused with
# `Lead.country_code`, the per-lead target country an ICP search surfaced someone
# under. Optional: an EEA/UK/CH country turns the contacts-store give-back off
Expand Down
20 changes: 15 additions & 5 deletions openoutfind/core/status.py
Original file line number Diff line number Diff line change
Expand Up @@ -170,7 +170,12 @@ def _credits() -> dict:
return {"balance": finder.credit_balance(), "provider": finder.NAME, "error": None}
except provider.ProviderUnavailable as exc:
logger.debug("Could not read the credit balance: %s", exc)
return {"balance": None, "error": exc.error_type, "detail": str(exc)}
return {
"balance": None,
"provider": finder.NAME,
"error": exc.error_type,
"detail": str(exc),
}


def _signup_url() -> str:
Expand Down Expand Up @@ -203,25 +208,30 @@ def _blocked(config: dict, credits: dict, totals: dict) -> list[dict]:
"message": "this run was not given: " + ", ".join(config["missing"]),
})

# The finder that actually ran is the one an operator has to act on. When no key is
# set there is no finder to name, so the sentence describes the missing piece instead
# of picking a vendor the install never configured.
finder = credits.get("provider") or "the email finder"

if credits["error"] == ErrorType.NO_CREDENTIAL:
blocked.append({
"type": ErrorType.NO_CREDENTIAL,
"message": "no BetterContact key — discovery and email finding are both off",
"message": "no email-finder key set: discovery and email finding are both off",
})
elif credits["error"] == ErrorType.PROVIDER_AUTH:
blocked.append({
"type": ErrorType.PROVIDER_AUTH,
"message": "BetterContact rejected the API key",
"message": f"{finder} rejected the API key",
})
elif credits["error"] == ErrorType.PROVIDER_OUT_OF_CREDITS:
blocked.append({
"type": ErrorType.PROVIDER_OUT_OF_CREDITS,
"message": "BetterContact reports the credits are exhausted",
"message": f"{finder} reports the credits are exhausted",
})
elif credits["error"] == ErrorType.PROVIDER_RATE_LIMITED:
blocked.append({
"type": ErrorType.PROVIDER_RATE_LIMITED,
"message": "BetterContact is rate-limiting this client — the run is backing off",
"message": f"{finder} is rate-limiting this client, the run is backing off",
})
elif credits["balance"] == 0 and totals["ranked_for_lookup"]:
blocked.append({
Expand Down
22 changes: 20 additions & 2 deletions openoutfind/enrichment/bettercontact.py
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,14 @@
REQUESTS_PER_MINUTE = 15
_BUDGET_WINDOW_S = 60.0

# **What one credit costs on the entry plan, used only to rank finders against each
# other.** Starter is $15 for 200 credits, so $0.075 a hit; the rate falls as the plan
# grows (their ladder runs to $0.02 at volume), and a bigger plan reorders the waterfall.
# So this is an anchor for the cheapest paid tier, not a measurement of what an
# operator's own account charges — the seam picks the cheapest *listed* finder and the
# prices are re-checked when a plan changes.
UNIT_COST_USD = 0.075

# **A 429 is backed off, never retried at speed** — their docs warn that a client which
# keeps firing through one can get the *account* blocked, which costs the operator far
# more than the throttled call was worth. urllib3 already does this correctly: waits of
Expand Down Expand Up @@ -108,11 +116,19 @@ class RequestBudget:
spend about 12, a later round's one about 3, so a run rarely waits.
"""

def __init__(self, limit: int, window: float, clock=time.monotonic, sleep=time.sleep):
def __init__(
self,
limit: int,
window: float,
clock=time.monotonic,
sleep=time.sleep,
label: str = NAME,
):
self._limit = limit
self._window = window
self._clock = clock
self._sleep = sleep
self._label = label
self._sent: deque[float] = deque()
self._lock = threading.Lock()

Expand All @@ -126,7 +142,9 @@ def take(self) -> None:
self._sent.append(now)
return
wait = self._window - (now - self._sent[0])
logger.debug("bettercontact: request budget full — waiting %.1fs", wait)
logger.debug(
"%s: request budget full, waiting %.1fs", self._label, wait
)
self._sleep(wait)


Expand Down
Loading