Adopt comprehensive type hints across the codebase (PEP 604, mypy CI)

[bluet]

Goal

Adopt comprehensive Python type hints across the proxybroker codebase (currently ~5% covered) so contributors get accurate IDE autocomplete, static type checking via mypy/pyright, and self-documenting public APIs.

Current state

• Existing helpers added in feat(ipv6): full IPv6 support across the stack (#201) #212 have modern type hints (PEP 604 union syntax): canonicalize_ip, find_proxy_pairs, _format_host_port.
• Rest of the codebase has none. Public API surface (Broker, Proxy, Resolver, Checker, Server) is fully untyped.
• Pyright in default mode flags hundreds of "possibly unbound" / "attribute access" warnings on the existing code, indicating real type ambiguity that hints would resolve.

Scope

Add type hints to all public APIs in:

Module	Public surface to annotate
proxybroker/api.py	Broker.__init__, find, grab, serve, stop
proxybroker/proxy.py	Proxy.__init__, Proxy.create, Proxy.connect, as_text, as_json, properties
proxybroker/resolver.py	Resolver.__init__, host_is_ip, resolve, get_real_ext_ip, get_ip_info
proxybroker/checker.py	Checker, _check_test_response, _get_anonymity_lvl
proxybroker/server.py	Server.__init__, start, stop
proxybroker/judge.py	Judge, get_judges
proxybroker/providers.py	Provider base + concrete impls' public methods
proxybroker/provider_utils.py	Helper classes (already partially typed per PR #208)
proxybroker/negotiators.py	BaseNegotiator.negotiate signatures
proxybroker/utils.py	All public functions (some done in #212)
proxybroker/errors.py	Exception class hierarchies (low priority)

Conventions

• PEP 604 unions (str | None, not Optional[str]) — already adopted in feat(ipv6): full IPv6 support across the stack (#201) #212; project supports Python 3.10+.
• Built-in collections (list[str], dict[str, int]) — same rationale.
• from __future__ import annotations at the top of each module to defer evaluation and avoid runtime cost.
• Protocols over ABCs for callable interfaces (e.g., Negotiator protocol) where it reduces coupling.

Mypy strictness ramp-up

Start with mypy --strict-optional (catches None bugs); progress to --strict after baseline coverage. Add a CI job (matrix dim or separate workflow) that runs mypy and fails on regressions. Don't enable strict mode globally upfront — gradual adoption per-module is the only realistic path.

Acceptance criteria

1. All public APIs (everything not prefixed with _) have type hints.
2. Pyright's reportGeneralTypeIssues count for proxybroker/ drops below 10 (currently ~50+).
3. New CI job: mypy proxybroker/ runs on every PR; fails on regression.
4. Internal types (e.g., _NewcomerProxy) typed where they reduce ambiguity at call sites.
5. README + docs updated to mention type-hint coverage as part of the contributor experience.

Estimated effort

• ~6-10 hours for the full coverage pass (mostly mechanical).
• ~2 hours to set up mypy CI + baseline configuration.
• 1 hour for docs.

Suggest splitting by module into 5-6 PRs of ~1-2 hours each, so each lands cleanly without a giant review burden.

Why this matters

• Refactor confidence: mypy catches "you renamed this method but missed 3 call sites" before runtime.
• Onboarding: new contributors instantly understand def find(types, limit) is def find(types: list[str], limit: int) -> AsyncIterator[Proxy].
• IDE quality: autocomplete + jump-to-definition work correctly. Currently proxy.<TAB> shows everything; with hints it's targeted.
• Future-proof: the Python ecosystem has fully embraced typing; untyped libraries are increasingly the outliers.