fix: add explicit return types for public client APIs

[miachillgood]

Summary

• annotate public module-level helpers and matching Client methods with their concrete return types
• return None explicitly from capture_exception when exception capture itself fails so the annotation stays accurate
• make the shutdown/flush/join public APIs clearer for static type checkers

Validation

• python -m compileall posthog
• python -m pytest -q (local environment is missing the repo's optional test dependencies, so full pytest collection could not complete here)

[greptile-apps]

_{Reviews (1): Last reviewed commit: "fix: add explicit return types for publi..." | Re-trigger Greptile}

[marandaneto]

pr is a bit outdated
also see #685