nodriver-proxyhat 0.1.0__tar.gz

nodriver_proxyhat-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: ruff check src/ tests/
+      - run: ruff format --check src/ tests/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      # Tests stub nodriver, so [dev] alone (no Chrome) is enough.
+      - run: pip install -e ".[dev]"
+      - run: pytest -v
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+
+  publish:
+    needs: [lint, test, build]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

nodriver_proxyhat-0.1.0/.github/workflows/compat.yml

@@ -0,0 +1,68 @@
+name: Compat (nodriver latest)
+
+# Autonomy watchdog: weekly (and on demand) it installs the newest nodriver and
+# our newest proxyhat SDK, then runs our tests against them. A red run means
+# upstream shipped a breaking change to the CDP Fetch auth surface we rely on —
+# it opens/updates a tracking issue so we notice before users do. The proactive
+# path is Renovate (renovate.json), which opens a version-bump PR that must pass
+# CI before merging.
+on:
+  schedule:
+    - cron: "0 6 * * 1" # Mondays 06:00 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  compat:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - name: Install latest upstreams
+        run: pip install --upgrade nodriver proxyhat
+      - name: Import the real nodriver CDP auth surface
+        # Fails loudly if nodriver renamed the Fetch/Network CDP auth primitives.
+        run: |
+          python - <<'PY'
+          import inspect
+          import nodriver
+          from nodriver import cdp
+
+          assert hasattr(nodriver, "start"), "nodriver.start is gone"
+          assert "browser_args" in inspect.signature(nodriver.start).parameters, \
+              "nodriver.start no longer accepts browser_args"
+          for attr in ("enable", "continue_with_auth", "continue_request", "AuthRequired", "RequestPaused"):
+              assert hasattr(cdp.fetch, attr), f"nodriver cdp.fetch.{attr} is gone"
+          assert hasattr(cdp.network, "AuthChallengeResponse"), \
+              "nodriver cdp.network.AuthChallengeResponse is gone"
+          print("nodriver CDP auth surface OK")
+          PY
+      - run: pytest -v
+      - name: Open an issue on failure
+        if: failure()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const title = "Compat break: nodriver@latest / proxyhat@latest";
+            const { data: issues } = await github.rest.issues.listForRepo({
+              owner: context.repo.owner, repo: context.repo.repo,
+              state: "open", labels: "compat",
+            });
+            const body = `The weekly compatibility check failed against the latest upstream releases.\n\nRun: ${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
+            if (issues.length === 0) {
+              await github.rest.issues.create({
+                owner: context.repo.owner, repo: context.repo.repo,
+                title, body, labels: ["compat"],
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner, repo: context.repo.repo,
+                issue_number: issues[0].number, body,
+              });
+            }

nodriver_proxyhat-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/

nodriver_proxyhat-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ProxyHat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nodriver_proxyhat-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: nodriver-proxyhat
+Version: 0.1.0
+Summary: ProxyHat residential proxies for nodriver (undetected Chrome) — CDP proxy auth, sticky sessions, geo-targeting, rotation.
+Project-URL: Homepage, https://proxyhat.com
+Project-URL: Documentation, https://docs.proxyhat.com
+Project-URL: Repository, https://github.com/ProxyHatCom/nodriver-proxyhat
+Author-email: ProxyHat <support@proxyhat.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: browser-automation,cdp,nodriver,proxy,proxyhat,residential-proxy,sticky-session,undetected-chromedriver,web-scraping
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: Proxy Servers
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.11
+Requires-Dist: proxyhat>=0.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: nodriver
+Requires-Dist: nodriver>=0.32; extra == 'nodriver'
+Description-Content-Type: text/markdown
+
+# nodriver-proxyhat
+
+Route [nodriver](https://github.com/ultrafunkamsterdam/nodriver) — the successor to undetected-chromedriver — through [ProxyHat](https://proxyhat.com?utm_source=github&utm_medium=readme&utm_campaign=nodriver) residential proxies. **Authenticated** gateway proxies wired straight into nodriver over CDP, plus a sticky residential IP pinned for the whole session, geo-targeting, and rotation.
+
+[![CI](https://github.com/ProxyHatCom/nodriver-proxyhat/actions/workflows/ci.yml/badge.svg)](https://github.com/ProxyHatCom/nodriver-proxyhat/actions/workflows/ci.yml)
+[![Compatible with nodriver latest](https://github.com/ProxyHatCom/nodriver-proxyhat/actions/workflows/compat.yml/badge.svg)](https://github.com/ProxyHatCom/nodriver-proxyhat/actions/workflows/compat.yml)
+[![PyPI](https://img.shields.io/pypi/v/nodriver-proxyhat)](https://pypi.org/project/nodriver-proxyhat/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## Why
+
+Chrome's `--proxy-server` flag **can't carry a username and password**, so pointing an undetected browser at a credentialed residential gateway normally means a manual CDP dance. And running a real browser from a datacenter IP gets flagged, CAPTCHA-walled, and blocked anyway — exactly what you're using nodriver to avoid.
+
+`nodriver-proxyhat` fixes both. It plugs ProxyHat's residential IPs (50M+ across 148+ countries) into nodriver and handles gateway auth the CDP way nodriver is built for: it enables the **Fetch** domain and answers the proxy's `Fetch.authRequired` challenge with your credentials. One pinned residential IP per session by default, so cookies and fingerprint stay consistent while your script works.
+
+## Install
+
+```bash
+pip install nodriver-proxyhat nodriver
+```
+
+`nodriver` is a peer dependency — bring your own version (and its Chrome). The `proxyhat_browser_args()` / `proxyhat_auth()` helpers work without it; `proxyhat_browser()` needs nodriver installed.
+
+## Quick start
+
+```python
+import nodriver as uc
+from nodriver_proxyhat import proxyhat_browser
+
+async def main():
+    # An API key (PROXYHAT_API_KEY) auto-selects an active residential sub-user:
+    browser = await proxyhat_browser(country="us")   # sticky US IP for the whole session
+    page = await browser.get("https://httpbin.org/ip")
+    print(await page.get_content())
+    browser.stop()
+
+uc.loop().run_until_complete(main())
+```
+
+Get an API key at [proxyhat.com](https://proxyhat.com?utm_source=github&utm_medium=readme&utm_campaign=nodriver).
+
+`proxyhat_browser(...)` calls `nodriver.start(...)` for you and forwards any extra keyword arguments (`headless`, `user_data_dir`, `browser_args`, …) unchanged.
+
+## Credentials
+
+Pass them explicitly or via environment variables — options win over env:
+
+| Option | Env var | Notes |
+|---|---|---|
+| `api_key` | `PROXYHAT_API_KEY` | Auto-selects an active sub-user with remaining traffic |
+| `sub_user` | `PROXYHAT_SUBUSER` | Pick a specific sub-user by uuid or name (with an API key) |
+| `username` | `PROXYHAT_USERNAME` | Explicit gateway `proxy_username` (skips the API) |
+| `password` | `PROXYHAT_PASSWORD` | Explicit gateway `proxy_password` |
+
+## Targeting
+
+```python
+await proxyhat_browser(
+    country="us",      # ISO code or "any" (default)
+    region="california",
+    city="new_york",
+    filter="high",     # AI IP-quality tier
+    sticky="30m",      # session lifetime (default); sticky=False rotates every request
+    headless=True,     # any extra kwarg is forwarded to nodriver.start
+)
+```
+
+The same targeting keyword arguments work on `proxyhat_auth(...)`.
+
+### Sticky IP per session (default)
+
+A browser session takes many steps against the same site — logging in, clicking, scrolling. If the exit IP changed mid-session the site would see a user teleporting between cities and block it. So this package is **sticky by default**: one residential IP is pinned for the whole session (`sticky="30m"`, renewed as you work), keeping cookies and fingerprint coherent.
+
+Want a fresh IP on **every** request instead (e.g. many independent one-shot fetches)? Turn stickiness off:
+
+```python
+await proxyhat_browser(country="us", sticky=False)  # rotating residential IP per connection
+```
+
+Set a custom lifetime with `sticky="2h"`.
+
+## How authentication works
+
+nodriver takes the proxy host/port from `--proxy-server=gate.proxyhat.com:8080`, but a residential gateway also needs a username (the ProxyHat targeting string) and password. Since the flag can't carry them, `proxyhat_browser` uses nodriver's raw Chrome DevTools Protocol access instead:
+
+1. it enables the **Fetch** domain on the main tab with `handle_auth_requests=True`;
+2. it registers a `Fetch.authRequired` handler that answers with your targeting username + sub-user password via `Fetch.continueWithAuth` (`ProvideCredentials`);
+3. it resumes every other paused request with `Fetch.continueRequest` (enabling Fetch pauses all requests, so non-auth ones must be continued too).
+
+The targeting username (e.g. `<user>-country-us-sid-<id>-ttl-30m`) is built by the official [`proxyhat`](https://pypi.org/project/proxyhat/) SDK, so a sticky session mints a single session id shared across the run.
+
+This is the **HTTP gateway** (port 8080) — CDP proxy auth answers the HTTP proxy's basic-auth challenge.
+
+## Wiring it yourself
+
+Prefer to drive `nodriver.start()` your way? Grab the launch flag and the resolved credentials and wire the CDP handler yourself:
+
+```python
+import nodriver as uc
+from nodriver import cdp
+from nodriver_proxyhat import proxyhat_auth, proxyhat_browser_args, enable_proxy_auth
+
+async def main():
+    username, password = proxyhat_auth(country="de", sticky="1h")
+
+    browser = await uc.start(browser_args=proxyhat_browser_args() + ["--headless=new"])
+    # enable_proxy_auth does the Fetch.enable + authRequired dance for you:
+    await enable_proxy_auth(browser.main_tab, username, password)
+
+    page = await browser.get("https://httpbin.org/ip")
+    print(await page.get_content())
+    browser.stop()
+
+uc.loop().run_until_complete(main())
+```
+
+`proxyhat_browser_args()` returns `["--proxy-server=gate.proxyhat.com:8080"]`; `proxyhat_auth()` returns the `(username, password)` for a `Fetch.authRequired` handler.
+
+## License
+
+MIT © [ProxyHat](https://proxyhat.com)

nodriver_proxyhat-0.1.0/README.md

@@ -0,0 +1,121 @@
+# nodriver-proxyhat
+
+Route [nodriver](https://github.com/ultrafunkamsterdam/nodriver) — the successor to undetected-chromedriver — through [ProxyHat](https://proxyhat.com?utm_source=github&utm_medium=readme&utm_campaign=nodriver) residential proxies. **Authenticated** gateway proxies wired straight into nodriver over CDP, plus a sticky residential IP pinned for the whole session, geo-targeting, and rotation.
+
+[![CI](https://github.com/ProxyHatCom/nodriver-proxyhat/actions/workflows/ci.yml/badge.svg)](https://github.com/ProxyHatCom/nodriver-proxyhat/actions/workflows/ci.yml)
+[![Compatible with nodriver latest](https://github.com/ProxyHatCom/nodriver-proxyhat/actions/workflows/compat.yml/badge.svg)](https://github.com/ProxyHatCom/nodriver-proxyhat/actions/workflows/compat.yml)
+[![PyPI](https://img.shields.io/pypi/v/nodriver-proxyhat)](https://pypi.org/project/nodriver-proxyhat/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## Why
+
+Chrome's `--proxy-server` flag **can't carry a username and password**, so pointing an undetected browser at a credentialed residential gateway normally means a manual CDP dance. And running a real browser from a datacenter IP gets flagged, CAPTCHA-walled, and blocked anyway — exactly what you're using nodriver to avoid.
+
+`nodriver-proxyhat` fixes both. It plugs ProxyHat's residential IPs (50M+ across 148+ countries) into nodriver and handles gateway auth the CDP way nodriver is built for: it enables the **Fetch** domain and answers the proxy's `Fetch.authRequired` challenge with your credentials. One pinned residential IP per session by default, so cookies and fingerprint stay consistent while your script works.
+
+## Install
+
+```bash
+pip install nodriver-proxyhat nodriver
+```
+
+`nodriver` is a peer dependency — bring your own version (and its Chrome). The `proxyhat_browser_args()` / `proxyhat_auth()` helpers work without it; `proxyhat_browser()` needs nodriver installed.
+
+## Quick start
+
+```python
+import nodriver as uc
+from nodriver_proxyhat import proxyhat_browser
+
+async def main():
+    # An API key (PROXYHAT_API_KEY) auto-selects an active residential sub-user:
+    browser = await proxyhat_browser(country="us")   # sticky US IP for the whole session
+    page = await browser.get("https://httpbin.org/ip")
+    print(await page.get_content())
+    browser.stop()
+
+uc.loop().run_until_complete(main())
+```
+
+Get an API key at [proxyhat.com](https://proxyhat.com?utm_source=github&utm_medium=readme&utm_campaign=nodriver).
+
+`proxyhat_browser(...)` calls `nodriver.start(...)` for you and forwards any extra keyword arguments (`headless`, `user_data_dir`, `browser_args`, …) unchanged.
+
+## Credentials
+
+Pass them explicitly or via environment variables — options win over env:
+
+| Option | Env var | Notes |
+|---|---|---|
+| `api_key` | `PROXYHAT_API_KEY` | Auto-selects an active sub-user with remaining traffic |
+| `sub_user` | `PROXYHAT_SUBUSER` | Pick a specific sub-user by uuid or name (with an API key) |
+| `username` | `PROXYHAT_USERNAME` | Explicit gateway `proxy_username` (skips the API) |
+| `password` | `PROXYHAT_PASSWORD` | Explicit gateway `proxy_password` |
+
+## Targeting
+
+```python
+await proxyhat_browser(
+    country="us",      # ISO code or "any" (default)
+    region="california",
+    city="new_york",
+    filter="high",     # AI IP-quality tier
+    sticky="30m",      # session lifetime (default); sticky=False rotates every request
+    headless=True,     # any extra kwarg is forwarded to nodriver.start
+)
+```
+
+The same targeting keyword arguments work on `proxyhat_auth(...)`.
+
+### Sticky IP per session (default)
+
+A browser session takes many steps against the same site — logging in, clicking, scrolling. If the exit IP changed mid-session the site would see a user teleporting between cities and block it. So this package is **sticky by default**: one residential IP is pinned for the whole session (`sticky="30m"`, renewed as you work), keeping cookies and fingerprint coherent.
+
+Want a fresh IP on **every** request instead (e.g. many independent one-shot fetches)? Turn stickiness off:
+
+```python
+await proxyhat_browser(country="us", sticky=False)  # rotating residential IP per connection
+```
+
+Set a custom lifetime with `sticky="2h"`.
+
+## How authentication works
+
+nodriver takes the proxy host/port from `--proxy-server=gate.proxyhat.com:8080`, but a residential gateway also needs a username (the ProxyHat targeting string) and password. Since the flag can't carry them, `proxyhat_browser` uses nodriver's raw Chrome DevTools Protocol access instead:
+
+1. it enables the **Fetch** domain on the main tab with `handle_auth_requests=True`;
+2. it registers a `Fetch.authRequired` handler that answers with your targeting username + sub-user password via `Fetch.continueWithAuth` (`ProvideCredentials`);
+3. it resumes every other paused request with `Fetch.continueRequest` (enabling Fetch pauses all requests, so non-auth ones must be continued too).
+
+The targeting username (e.g. `<user>-country-us-sid-<id>-ttl-30m`) is built by the official [`proxyhat`](https://pypi.org/project/proxyhat/) SDK, so a sticky session mints a single session id shared across the run.
+
+This is the **HTTP gateway** (port 8080) — CDP proxy auth answers the HTTP proxy's basic-auth challenge.
+
+## Wiring it yourself
+
+Prefer to drive `nodriver.start()` your way? Grab the launch flag and the resolved credentials and wire the CDP handler yourself:
+
+```python
+import nodriver as uc
+from nodriver import cdp
+from nodriver_proxyhat import proxyhat_auth, proxyhat_browser_args, enable_proxy_auth
+
+async def main():
+    username, password = proxyhat_auth(country="de", sticky="1h")
+
+    browser = await uc.start(browser_args=proxyhat_browser_args() + ["--headless=new"])
+    # enable_proxy_auth does the Fetch.enable + authRequired dance for you:
+    await enable_proxy_auth(browser.main_tab, username, password)
+
+    page = await browser.get("https://httpbin.org/ip")
+    print(await page.get_content())
+    browser.stop()
+
+uc.loop().run_until_complete(main())
+```
+
+`proxyhat_browser_args()` returns `["--proxy-server=gate.proxyhat.com:8080"]`; `proxyhat_auth()` returns the `(username, password)` for a `Fetch.authRequired` handler.
+
+## License
+
+MIT © [ProxyHat](https://proxyhat.com)

nodriver_proxyhat-0.1.0/examples/basic.py

@@ -0,0 +1,27 @@
+"""Minimal nodriver + ProxyHat example.
+
+    PROXYHAT_API_KEY=ph_xxx python examples/basic.py
+
+nodriver launches an undetected Chrome routed through a US residential IP, pinned
+for the whole session (sticky by default) so cookies and fingerprint stay
+consistent. Gateway auth is handled over CDP — no extension, no proxy wrapper.
+"""
+
+import nodriver as uc
+
+from nodriver_proxyhat import proxyhat_browser
+
+
+async def main() -> None:
+    # api_key defaults to PROXYHAT_API_KEY; auto-selects an active sub-user.
+    browser = await proxyhat_browser(country="us", headless=False)
+
+    page = await browser.get("https://httpbin.org/ip")
+    print(await page.get_content())
+
+    browser.stop()
+
+
+if __name__ == "__main__":
+    # nodriver ships its own loop helper (asyncio.run never worked reliably for it).
+    uc.loop().run_until_complete(main())

nodriver_proxyhat-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nodriver-proxyhat"
+version = "0.1.0"
+description = "ProxyHat residential proxies for nodriver (undetected Chrome) — CDP proxy auth, sticky sessions, geo-targeting, rotation."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "ProxyHat", email = "support@proxyhat.com" }]
+keywords = [
+    "nodriver",
+    "undetected-chromedriver",
+    "proxy",
+    "residential-proxy",
+    "proxyhat",
+    "browser-automation",
+    "web-scraping",
+    "cdp",
+    "sticky-session",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Internet :: Proxy Servers",
+]
+dependencies = ["proxyhat>=0.2.0"]
+
+[project.urls]
+Homepage = "https://proxyhat.com"
+Documentation = "https://docs.proxyhat.com"
+Repository = "https://github.com/ProxyHatCom/nodriver-proxyhat"
+
+[project.optional-dependencies]
+# nodriver is a peer/optional dependency: install it yourself to launch a real
+# browser. proxyhat_browser_args() and proxyhat_auth() work without it.
+nodriver = ["nodriver>=0.32"]
+dev = ["pytest>=7.0", "ruff>=0.4"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nodriver_proxyhat"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

nodriver_proxyhat-0.1.0/renovate.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["config:recommended", ":semanticCommits"],
+  "labels": ["dependencies"],
+  "schedule": ["before 6am on monday"],
+  "packageRules": [
+    {
+      "description": "Auto-merge dev-dependency and upstream bumps once CI (incl. compat) is green.",
+      "matchDepTypes": ["build-system.requires", "project.dependencies", "project.optional-dependencies"],
+      "automerge": true,
+      "automergeType": "pr"
+    },
+    {
+      "description": "Track the nodriver range but never auto-widen it silently.",
+      "matchPackageNames": ["nodriver"],
+      "automerge": false
+    }
+  ]
+}

nodriver_proxyhat-0.1.0/src/nodriver_proxyhat/__init__.py

@@ -0,0 +1,15 @@
+"""nodriver-proxyhat — route nodriver (undetected Chrome) through ProxyHat residential proxies."""
+
+from nodriver_proxyhat._auth import enable_proxy_auth
+from nodriver_proxyhat._resolve import ProxyHatConfigError, resolve_credentials
+from nodriver_proxyhat.proxy import proxyhat_auth, proxyhat_browser, proxyhat_browser_args
+
+__all__ = [
+    "ProxyHatConfigError",
+    "enable_proxy_auth",
+    "proxyhat_auth",
+    "proxyhat_browser",
+    "proxyhat_browser_args",
+    "resolve_credentials",
+]
+__version__ = "0.1.0"

nodriver_proxyhat-0.1.0/src/nodriver_proxyhat/_auth.py

@@ -0,0 +1,55 @@
+"""Wire ProxyHat gateway authentication onto a nodriver tab over raw CDP.
+
+Chrome's ``--proxy-server`` flag can't carry a username/password, so a credentialed
+residential gateway needs another way to answer the proxy's auth challenge. nodriver
+speaks the Chrome DevTools Protocol directly, so we authenticate the CDP way:
+
+1. enable the ``Fetch`` domain with ``handle_auth_requests=True``,
+2. answer every ``Fetch.authRequired`` with the ProxyHat targeting username +
+   sub-user password via ``Fetch.continueWithAuth`` (``ProvideCredentials``),
+3. resume every other paused request with ``Fetch.continueRequest``.
+
+Enabling ``Fetch`` pauses *every* request (a ``requestPaused`` event), so the
+non-auth requests must be continued too or the page hangs waiting on us.
+
+This is the HTTP gateway path (port 8080) — CDP proxy auth answers the HTTP
+proxy's basic-auth challenge. ``nodriver`` is imported lazily so importing this
+module never requires it.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from nodriver import Tab
+
+
+async def enable_proxy_auth(tab: Tab, username: str, password: str) -> None:
+    """Register the CDP proxy-auth handlers on ``tab`` and enable ``Fetch``.
+
+    Adds a ``Fetch.authRequired`` handler that answers with ``username`` /
+    ``password`` and a ``Fetch.requestPaused`` handler that resumes normal
+    requests, then enables the Fetch domain with auth handling. Call once per tab
+    before navigating so the very first request is authenticated.
+    """
+    from nodriver import cdp
+
+    async def _on_auth_required(event: cdp.fetch.AuthRequired) -> None:
+        await tab.send(
+            cdp.fetch.continue_with_auth(
+                request_id=event.request_id,
+                auth_challenge_response=cdp.network.AuthChallengeResponse(
+                    response="ProvideCredentials",
+                    username=username,
+                    password=password,
+                ),
+            )
+        )
+
+    async def _on_request_paused(event: cdp.fetch.RequestPaused) -> None:
+        await tab.send(cdp.fetch.continue_request(request_id=event.request_id))
+
+    tab.add_handler(cdp.fetch.AuthRequired, _on_auth_required)
+    tab.add_handler(cdp.fetch.RequestPaused, _on_request_paused)
+    await tab.send(cdp.fetch.enable(handle_auth_requests=True))

nodriver_proxyhat-0.1.0/src/nodriver_proxyhat/_resolve.py

@@ -0,0 +1,71 @@
+"""Gateway credential resolution for nodriver-proxyhat.
+
+Mirrors the other ProxyHat integrations: explicit ``username``/``password``
+(or ``PROXYHAT_USERNAME``/``PROXYHAT_PASSWORD``) win; otherwise an API key
+(``PROXYHAT_API_KEY``) looks up your sub-users via the official ``proxyhat`` SDK
+and picks an active one with remaining traffic — or the one named by ``sub_user``.
+Everything here except the sub-user lookup is offline.
+"""
+
+from __future__ import annotations
+
+import os
+
+from proxyhat import ProxyHat
+
+
+class ProxyHatConfigError(RuntimeError):
+    """Raised when ProxyHat credentials cannot be resolved."""
+
+
+def _env(name: str) -> str | None:
+    value = os.environ.get(name)
+    return value.strip() if value and value.strip() else None
+
+
+def resolve_credentials(
+    *,
+    api_key: str | None = None,
+    username: str | None = None,
+    password: str | None = None,
+    sub_user: str | None = None,
+) -> tuple[str, str]:
+    """Resolve a sub-user's ``(proxy_username, proxy_password)``.
+
+    Options win over environment variables. Precedence:
+
+    1. explicit ``username`` + ``password`` (``PROXYHAT_USERNAME`` / ``PROXYHAT_PASSWORD``)
+    2. ``api_key`` (``PROXYHAT_API_KEY``) → auto-pick an active sub-user, or the
+       one named by ``sub_user`` (``PROXYHAT_SUBUSER``).
+    """
+    username = username or _env("PROXYHAT_USERNAME")
+    password = password or _env("PROXYHAT_PASSWORD")
+    if username and password:
+        return username, password
+
+    api_key = api_key or _env("PROXYHAT_API_KEY")
+    if not api_key:
+        raise ProxyHatConfigError(
+            "nodriver-proxyhat: no credentials. Pass api_key (or PROXYHAT_API_KEY), "
+            "or username + password (PROXYHAT_USERNAME / PROXYHAT_PASSWORD)."
+        )
+
+    return _resolve_sub_user(api_key, sub_user or _env("PROXYHAT_SUBUSER"))
+
+
+def _resolve_sub_user(api_key: str, want: str | None) -> tuple[str, str]:
+    users = ProxyHat(api_key=api_key).sub_users.list()
+    usable = [u for u in users if not u.suspended_at and (u.traffic_limit == 0 or u.used_traffic < u.traffic_limit)]
+    if want:
+        chosen = next((u for u in users if u.uuid == want or u.name == want), None)
+    else:
+        chosen = usable[0] if usable else None
+
+    if chosen is None or not chosen.proxy_username or not chosen.proxy_password:
+        raise ProxyHatConfigError(
+            f'nodriver-proxyhat: no sub-user matched "{want}" (or it has no proxy credentials).'
+            if want
+            else "nodriver-proxyhat: no usable sub-user found (all suspended or out of traffic). "
+            "Create one, top up, or pass sub_user."
+        )
+    return chosen.proxy_username, chosen.proxy_password

nodriver_proxyhat-0.1.0/src/nodriver_proxyhat/proxy.py

@@ -0,0 +1,162 @@
+"""Route a nodriver (undetected Chrome) browser through the ProxyHat gateway.
+
+nodriver launches Chrome with ``nodriver.start(browser_args=[...])``, but Chrome's
+``--proxy-server`` flag can't carry a username/password. nodriver gives raw CDP
+access, so the credentialed residential gateway is authenticated the CDP way:
+enable the Fetch domain with ``handle_auth_requests=True`` and answer
+``Fetch.authRequired`` with the ProxyHat targeting username + sub-user password
+(see :mod:`nodriver_proxyhat._auth`).
+
+Three entry points:
+
+- ``proxyhat_browser_args()`` — the ``--proxy-server`` launch flag for the gateway.
+- ``proxyhat_auth()`` — the ``(username, password)`` for wiring the CDP auth
+  handler yourself.
+- ``proxyhat_browser()`` — start Chrome with the flag applied *and* the CDP auth
+  handler already wired.
+
+This is the HTTP gateway (port 8080); CDP proxy auth applies to the HTTP proxy.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from proxyhat import (
+    PROXYHAT_GATEWAY,
+    PROXYHAT_PORT_HTTP,
+    build_proxy_username,
+)
+
+from nodriver_proxyhat._auth import enable_proxy_auth
+from nodriver_proxyhat._resolve import resolve_credentials
+
+if TYPE_CHECKING:
+    from nodriver import Browser
+
+# A browser session takes many steps against the same site, so pin one
+# residential IP for the whole session by default — keeps cookies and
+# fingerprint consistent. sticky=False rotates a fresh IP per connection.
+DEFAULT_STICKY = "30m"
+
+
+def proxyhat_browser_args(**_targeting: Any) -> list[str]:
+    """Return the Chrome launch args pointing nodriver at the ProxyHat gateway.
+
+    Just ``["--proxy-server=gate.proxyhat.com:8080"]`` — the HTTP gateway host and
+    port. Targeting (``country`` / ``region`` / ``city`` / ``sticky`` / ``filter``)
+    is *not* encoded here, because Chrome's ``--proxy-server`` can't carry it: it
+    lives in the CDP auth username built by :func:`proxyhat_auth` and applied by
+    :func:`proxyhat_browser`. Targeting keyword arguments are accepted (so you can
+    splat the same dict you pass to those) but do not change the returned flag.
+
+    Merge the result into your own ``nodriver.start(browser_args=[...])`` call and
+    wire auth yourself with :func:`proxyhat_auth` + ``enable_proxy_auth`` — or just
+    use :func:`proxyhat_browser`, which does both.
+    """
+    return [f"--proxy-server={PROXYHAT_GATEWAY}:{PROXYHAT_PORT_HTTP}"]
+
+
+def proxyhat_auth(
+    *,
+    api_key: str | None = None,
+    username: str | None = None,
+    password: str | None = None,
+    sub_user: str | None = None,
+    country: str | None = None,
+    region: str | None = None,
+    city: str | None = None,
+    sticky: bool | str | None = DEFAULT_STICKY,
+    filter: str | None = None,
+) -> tuple[str, str]:
+    """Resolve the ``(gateway_username, password)`` for the ProxyHat gateway.
+
+    Resolves credentials (``api_key`` / ``PROXYHAT_API_KEY`` auto-picks an active
+    sub-user, or pass explicit ``username`` / ``password``), then builds the
+    targeting username — geo and stickiness reflected — with the official
+    ``proxyhat`` SDK grammar. Feed the pair to a CDP ``Fetch.authRequired`` handler
+    (``ProvideCredentials``) if you're wiring nodriver yourself; otherwise
+    :func:`proxyhat_browser` does it for you.
+
+    Sticky vs rotating:
+
+    - ``sticky="30m"`` (default) or ``sticky=True`` pins one residential IP for
+      the session — recommended for a browser.
+    - ``sticky=False`` (or ``None``) rotates: a fresh residential IP per connection.
+    - ``sticky="2h"`` sets a custom session lifetime.
+
+    Geo/quality targeting: ``country`` (ISO code or ``"any"``), ``region``,
+    ``city``, ``filter`` (AI IP-quality tier).
+    """
+    user, pw = resolve_credentials(
+        api_key=api_key,
+        username=username,
+        password=password,
+        sub_user=sub_user,
+    )
+    # Build the targeting username once so a sticky session mints a single sid
+    # shared by every request the browser makes.
+    gateway_username = build_proxy_username(
+        user,
+        country=country,
+        region=region,
+        city=city,
+        sticky=sticky,
+        filter=filter,
+    )
+    return gateway_username, pw
+
+
+async def proxyhat_browser(
+    *,
+    api_key: str | None = None,
+    username: str | None = None,
+    password: str | None = None,
+    sub_user: str | None = None,
+    country: str | None = None,
+    region: str | None = None,
+    city: str | None = None,
+    sticky: bool | str | None = DEFAULT_STICKY,
+    filter: str | None = None,
+    **start_kwargs: Any,
+) -> Browser:
+    """Start a nodriver Chrome routed through ProxyHat with gateway auth wired.
+
+    Resolves credentials, calls ``nodriver.start(browser_args=[...], **start_kwargs)``
+    with the ``--proxy-server`` flag applied, then enables CDP ``Fetch`` on the
+    browser's main tab and registers a ``Fetch.authRequired`` handler that answers
+    with the ProxyHat targeting username + sub-user password. Returns the started
+    ``Browser`` — navigate with ``await browser.get(url)``.
+
+    Any extra keyword arguments (``headless``, ``user_data_dir``, ``sandbox``, …)
+    are forwarded to ``nodriver.start``; if you pass your own ``browser_args`` they
+    are merged with the ProxyHat flag. Sticky by default (one pinned IP for the
+    whole session); pass ``sticky=False`` for a rotating IP. See :func:`proxyhat_auth`
+    for the full targeting keyword set.
+
+    ``nodriver`` is imported lazily — install it (``pip install nodriver-proxyhat[nodriver]``)
+    to use this helper; :func:`proxyhat_browser_args` and :func:`proxyhat_auth` work
+    without it.
+    """
+    gateway_username, pw = proxyhat_auth(
+        api_key=api_key,
+        username=username,
+        password=password,
+        sub_user=sub_user,
+        country=country,
+        region=region,
+        city=city,
+        sticky=sticky,
+        filter=filter,
+    )
+
+    caller_args = start_kwargs.pop("browser_args", None) or []
+    browser_args = proxyhat_browser_args() + list(caller_args)
+
+    # Imported lazily: nodriver is an optional (peer) dependency, so importing
+    # this module never forces a Chrome/nodriver install.
+    import nodriver
+
+    browser = await nodriver.start(browser_args=browser_args, **start_kwargs)
+    await enable_proxy_auth(browser.main_tab, gateway_username, pw)
+    return browser

nodriver_proxyhat-0.1.0/tests/test_browser.py

@@ -0,0 +1,190 @@
+"""Tests for the CDP auth wiring and proxyhat_browser.
+
+nodriver drives a real Chrome, so instead of installing it we inject a tiny fake
+``nodriver`` module (with a ``cdp.fetch`` / ``cdp.network`` surface) that records
+the CDP commands our code sends. That exercises the actual auth-handler path —
+Fetch.enable, the Fetch.authRequired answer, and request resumption — plus the
+browser_args / start_kwargs wiring, without any browser or network.
+"""
+
+import asyncio
+import sys
+from types import ModuleType, SimpleNamespace
+
+import pytest
+
+from nodriver_proxyhat import enable_proxy_auth, proxyhat_browser
+
+
+def run(coro):
+    return asyncio.run(coro)
+
+
+class FakeTab:
+    def __init__(self):
+        self.handlers = {}
+        self.sent = []
+
+    def add_handler(self, event_type, callback):
+        self.handlers[event_type] = callback
+
+    async def send(self, command):
+        self.sent.append(command)
+
+
+class FakeBrowser:
+    def __init__(self):
+        self.main_tab = FakeTab()
+
+
+class AuthChallengeResponse:
+    def __init__(self, *, response, username=None, password=None):
+        self.response = response
+        self.username = username
+        self.password = password
+
+
+class AuthRequired:
+    """Stand-in for cdp.fetch.AuthRequired event type."""
+
+
+class RequestPaused:
+    """Stand-in for cdp.fetch.RequestPaused event type."""
+
+
+@pytest.fixture
+def fake_nodriver(monkeypatch):
+    """Install a fake ``nodriver`` module and return a handle to inspect it."""
+    captured = {}
+
+    fetch = ModuleType("nodriver.cdp.fetch")
+    fetch.AuthRequired = AuthRequired
+    fetch.RequestPaused = RequestPaused
+    fetch.enable = lambda **kw: ("fetch.enable", kw)
+    fetch.continue_with_auth = lambda **kw: ("fetch.continue_with_auth", kw)
+    fetch.continue_request = lambda **kw: ("fetch.continue_request", kw)
+
+    network = ModuleType("nodriver.cdp.network")
+    network.AuthChallengeResponse = AuthChallengeResponse
+
+    cdp = ModuleType("nodriver.cdp")
+    cdp.fetch = fetch
+    cdp.network = network
+
+    nodriver = ModuleType("nodriver")
+    nodriver.cdp = cdp
+
+    browser = FakeBrowser()
+
+    async def start(**kwargs):
+        captured["start_kwargs"] = kwargs
+        return browser
+
+    nodriver.start = start
+
+    monkeypatch.setitem(sys.modules, "nodriver", nodriver)
+    monkeypatch.setitem(sys.modules, "nodriver.cdp", cdp)
+    monkeypatch.setitem(sys.modules, "nodriver.cdp.fetch", fetch)
+    monkeypatch.setitem(sys.modules, "nodriver.cdp.network", network)
+    return SimpleNamespace(module=nodriver, browser=browser, captured=captured)
+
+
+class TestEnableProxyAuth:
+    def test_registers_handlers_and_enables_fetch(self, fake_nodriver):
+        tab = FakeTab()
+        run(enable_proxy_auth(tab, "ph-1-country-us", "pw"))
+
+        assert AuthRequired in tab.handlers
+        assert RequestPaused in tab.handlers
+        # Fetch enabled with auth handling requested.
+        assert ("fetch.enable", {"handle_auth_requests": True}) in tab.sent
+
+    def test_auth_handler_answers_with_credentials(self, fake_nodriver):
+        tab = FakeTab()
+        run(enable_proxy_auth(tab, "ph-1-country-us-sid-abc-ttl-30m", "s3cr3t"))
+
+        event = SimpleNamespace(request_id="req-1")
+        run(tab.handlers[AuthRequired](event))
+
+        name, kw = tab.sent[-1]
+        assert name == "fetch.continue_with_auth"
+        assert kw["request_id"] == "req-1"
+        acr = kw["auth_challenge_response"]
+        assert acr.response == "ProvideCredentials"
+        assert acr.username == "ph-1-country-us-sid-abc-ttl-30m"
+        assert acr.password == "s3cr3t"
+
+    def test_request_handler_resumes_paused_requests(self, fake_nodriver):
+        tab = FakeTab()
+        run(enable_proxy_auth(tab, "ph-1", "pw"))
+
+        event = SimpleNamespace(request_id="req-2")
+        run(tab.handlers[RequestPaused](event))
+
+        assert ("fetch.continue_request", {"request_id": "req-2"}) in tab.sent
+
+
+class TestProxyhatBrowser:
+    def test_applies_proxy_flag_and_wires_auth(self, fake_nodriver):
+        browser = run(proxyhat_browser(username="ph-1", password="pw", country="us"))
+        assert browser is fake_nodriver.browser
+
+        start_kwargs = fake_nodriver.captured["start_kwargs"]
+        assert "--proxy-server=gate.proxyhat.com:8080" in start_kwargs["browser_args"]
+
+        tab = browser.main_tab
+        # Auth handler was wired and Fetch enabled on the main tab.
+        assert AuthRequired in tab.handlers
+        assert ("fetch.enable", {"handle_auth_requests": True}) in tab.sent
+
+        # The wired handler answers with the sticky, geo-targeted username.
+        run(tab.handlers[AuthRequired](SimpleNamespace(request_id="r")))
+        _, kw = tab.sent[-1]
+        acr = kw["auth_challenge_response"]
+        assert acr.username.startswith("ph-1-country-us")
+        assert "-sid-" in acr.username  # sticky by default
+        assert acr.password == "pw"
+
+    def test_forwards_start_kwargs_and_merges_browser_args(self, fake_nodriver):
+        run(
+            proxyhat_browser(
+                username="ph-1",
+                password="pw",
+                headless=True,
+                browser_args=["--window-size=1920,1080"],
+            )
+        )
+        start_kwargs = fake_nodriver.captured["start_kwargs"]
+        assert start_kwargs["headless"] is True
+        assert "--proxy-server=gate.proxyhat.com:8080" in start_kwargs["browser_args"]
+        assert "--window-size=1920,1080" in start_kwargs["browser_args"]
+
+    def test_rotating_option(self, fake_nodriver):
+        browser = run(proxyhat_browser(username="ph-1", password="pw", sticky=False))
+        tab = browser.main_tab
+        run(tab.handlers[AuthRequired](SimpleNamespace(request_id="r")))
+        _, kw = tab.sent[-1]
+        assert "-sid-" not in kw["auth_challenge_response"].username
+
+    def test_resolves_via_api_key(self, fake_nodriver, monkeypatch):
+        users = [
+            SimpleNamespace(
+                uuid="u",
+                name=None,
+                proxy_username="good",
+                proxy_password="secret",
+                traffic_limit=0,
+                used_traffic=0,
+                suspended_at=None,
+            )
+        ]
+        fake_client = SimpleNamespace(sub_users=SimpleNamespace(list=lambda: users))
+        monkeypatch.setattr("nodriver_proxyhat._resolve.ProxyHat", lambda **kw: fake_client)
+
+        browser = run(proxyhat_browser(api_key="ph_key", country="us", sticky=False))
+        tab = browser.main_tab
+        run(tab.handlers[AuthRequired](SimpleNamespace(request_id="r")))
+        _, kw = tab.sent[-1]
+        acr = kw["auth_challenge_response"]
+        assert acr.username == "good-country-us"
+        assert acr.password == "secret"

nodriver_proxyhat-0.1.0/tests/test_proxy.py

@@ -0,0 +1,117 @@
+"""Offline tests for the proxy-args / auth / credential surface.
+
+No browser is launched and no network call is made: the ProxyHat SDK's
+``sub_users.list()`` is mocked, and we assert the ``--proxy-server`` flag and the
+targeting username (geo + sticky reflected) + password directly.
+"""
+
+from types import SimpleNamespace
+
+import pytest
+
+from nodriver_proxyhat import (
+    ProxyHatConfigError,
+    proxyhat_auth,
+    proxyhat_browser_args,
+    resolve_credentials,
+)
+
+
+def sub_user(**kw):
+    base = dict(
+        uuid="u",
+        name=None,
+        proxy_username="ph-1",
+        proxy_password="pw",
+        traffic_limit=0,
+        used_traffic=0,
+        suspended_at=None,
+    )
+    base.update(kw)
+    return SimpleNamespace(**base)
+
+
+class TestBrowserArgs:
+    def test_sets_http_gateway_proxy_server(self):
+        assert proxyhat_browser_args() == ["--proxy-server=gate.proxyhat.com:8080"]
+
+    def test_targeting_kwargs_do_not_change_the_flag(self):
+        # Targeting lives in the CDP auth username, not the --proxy-server flag.
+        args = proxyhat_browser_args(country="de", sticky=False, filter="high")
+        assert args == ["--proxy-server=gate.proxyhat.com:8080"]
+
+
+class TestAuth:
+    def test_returns_targeting_username_and_password(self):
+        user, pw = proxyhat_auth(username="ph-1", password="pw", country="us")
+        assert user.startswith("ph-1-country-us")
+        assert pw == "pw"
+
+    def test_sticky_default_pins_session(self):
+        user, _ = proxyhat_auth(username="ph-1", password="pw")
+        # Default is sticky: a session id + 30m TTL is present.
+        assert "-sid-" in user
+        assert "-ttl-30m" in user
+
+    def test_sticky_false_is_rotating(self):
+        user, _ = proxyhat_auth(username="ph-1", password="pw", sticky=False)
+        assert "-sid-" not in user
+        assert "-ttl-" not in user
+
+    def test_custom_sticky_ttl(self):
+        user, _ = proxyhat_auth(username="ph-1", password="pw", sticky="2h")
+        assert "-ttl-2h" in user
+
+    def test_geo_targeting(self):
+        user, _ = proxyhat_auth(
+            username="ph-1",
+            password="pw",
+            country="de",
+            region="berlin",
+            city="berlin",
+            filter="high",
+            sticky=False,
+        )
+        assert user == "ph-1-country-de-region-berlin-city-berlin-filter-high"
+
+
+class TestCredentialResolution:
+    def test_explicit_username_password(self):
+        assert resolve_credentials(username="ph-1", password="pw") == ("ph-1", "pw")
+
+    def test_raises_without_credentials(self, monkeypatch):
+        for var in ("PROXYHAT_API_KEY", "PROXYHAT_USERNAME", "PROXYHAT_PASSWORD", "PROXYHAT_SUBUSER"):
+            monkeypatch.delenv(var, raising=False)
+        with pytest.raises(ProxyHatConfigError):
+            resolve_credentials()
+
+    def test_api_key_picks_active_sub_user(self, monkeypatch):
+        users = [
+            sub_user(uuid="s", proxy_username="susp", suspended_at="2026-01-01"),
+            sub_user(uuid="g", proxy_username="good", traffic_limit=100, used_traffic=100),
+            sub_user(uuid="ok", proxy_username="ok", traffic_limit=100, used_traffic=1),
+        ]
+        fake_client = SimpleNamespace(sub_users=SimpleNamespace(list=lambda: users))
+        monkeypatch.setattr("nodriver_proxyhat._resolve.ProxyHat", lambda **kw: fake_client)
+        assert resolve_credentials(api_key="ph_key") == ("ok", "pw")
+
+    def test_api_key_named_sub_user(self, monkeypatch):
+        users = [sub_user(uuid="a", proxy_username="a"), sub_user(uuid="b", name="prod", proxy_username="b")]
+        fake_client = SimpleNamespace(sub_users=SimpleNamespace(list=lambda: users))
+        monkeypatch.setattr("nodriver_proxyhat._resolve.ProxyHat", lambda **kw: fake_client)
+        assert resolve_credentials(api_key="ph_key", sub_user="prod") == ("b", "pw")
+
+    def test_api_key_no_usable_sub_user(self, monkeypatch):
+        users = [sub_user(traffic_limit=100, used_traffic=100)]
+        fake_client = SimpleNamespace(sub_users=SimpleNamespace(list=lambda: users))
+        monkeypatch.setattr("nodriver_proxyhat._resolve.ProxyHat", lambda **kw: fake_client)
+        with pytest.raises(ProxyHatConfigError):
+            resolve_credentials(api_key="ph_key")
+
+    def test_proxyhat_auth_resolves_via_api_key(self, monkeypatch):
+        users = [sub_user(proxy_username="good", proxy_password="secret")]
+        fake_client = SimpleNamespace(sub_users=SimpleNamespace(list=lambda: users))
+        monkeypatch.setattr("nodriver_proxyhat._resolve.ProxyHat", lambda **kw: fake_client)
+        user, pw = proxyhat_auth(api_key="ph_key", country="us", sticky=False)
+        assert user == "good-country-us"
+        assert pw == "secret"