amazon-orders 4.2.2__tar.gz → 4.3.0__tar.gz

{amazon_orders-4.2.2 → amazon_orders-4.3.0}/CHANGELOG.md

@@ -4,7 +4,23 @@ All notable changes to this project will be documented in this file.
 
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased](https://github.com/alexdlaird/amazon-orders/compare/4.2.2...HEAD)
+## [Unreleased](https://github.com/alexdlaird/amazon-orders/compare/4.3.0...HEAD)
+
+## [4.3.0](https://github.com/alexdlaird/amazon-orders/compare/4.2.2...4.3.0) - 2026-06-07
+
+### Added
+
+- `[browser]` optional extra (`pip install amazon-orders[browser]`) for handling JavaScript-based authentication challenges via a headless browser. See [the docs](https://amazon-orders.readthedocs.io/browser.html) for setup.
+  - `PlaywrightAcicForm` handles the ACIC challenge page. If an embedded AWS WAF CAPTCHA is present, it delegates automatically to any configured WAF solver extra.
+  - `PlaywrightJSAuthForm` is a best-effort handler for the JS robot-detection page.
+  - `PlaywrightManualWafForm` opens a **visible** browser window for manual WAF CAPTCHA solving — a free alternative to the paid `[waf]` extras for local/interactive use.
+- `browser` config key and `AMAZON_BROWSER` environment variable to select between `chromium` (default) and `firefox` browser fingerprints.
+- `Transaction.payment_method_last_4`, the masked card digits parsed from `payment_method`, mirroring the existing field on `Order`.
+
+### Changed
+
+- JavaScript-based authentication challenge errors now direct users to the `[browser]` extra rather than reporting the challenge as unsolvable.
+- All user-facing error messages that include install commands now wrap those commands in backticks.
 
 ## [4.2.2](https://github.com/alexdlaird/amazon-orders/compare/4.2.1...4.2.2) - 2026-06-06
 

{amazon_orders-4.2.2/amazon_orders.egg-info → amazon_orders-4.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: amazon-orders
-Version: 4.2.2
+Version: 4.3.0
 Summary: A Python library (and CLI) for Amazon order history
 Author-email: Alex Laird <contact@alexlaird.com>
 Maintainer-email: Alex Laird <contact@alexlaird.com>
@@ -43,6 +43,8 @@ Provides-Extra: anticaptcha
 Requires-Dist: anticaptchaofficial; extra == "anticaptcha"
 Provides-Extra: 2captcha
 Requires-Dist: 2captcha-python; extra == "2captcha"
+Provides-Extra: browser
+Requires-Dist: playwright>=1.47.0; extra == "browser"
 Provides-Extra: lxml
 Requires-Dist: lxml; extra == "lxml"
 Provides-Extra: dev
@@ -101,7 +103,7 @@ pip install amazon-orders --upgrade
 
 That's it! `amazon-orders` is now available as a package to your Python projects and from the command line.
 
-If pinning, be sure to use a wildcard for the [minor version](https://semver.org/) (ex. `==4.2.*`, not `==4.2.2`) to
+If pinning, be sure to use a wildcard for the [minor version](https://semver.org/) (ex. `==4.3.*`, not `==4.2.1`) to
 ensure you always get the latest stable release.
 
 ## Basic Usage
@@ -170,6 +172,16 @@ pip install amazon-orders[2captcha]
 
 See [Solving WAF Challenges](https://amazon-orders.readthedocs.io/waf.html) for details.
 
+To enable **browser-based challenge handling** (ACIC and JavaScript bot-detection pages) via
+a headless browser, install with the `browser` extra:
+
+```sh
+pip install amazon-orders[browser]
+playwright install chromium
+```
+
+See [Browser Automation](https://amazon-orders.readthedocs.io/browser.html) for details.
+
 To enable **Captcha auto-solve** on Python <=3.12 (via the optional [`amazoncaptcha`](https://pypi.org/project/amazoncaptcha/)
 dependency), install with the `captcha` extra:
 
@@ -178,7 +190,7 @@ pip install amazon-orders[captcha]
 ```
 
 Without this extra, Captcha challenges fall back to manual entry. `amazoncaptcha` is not available on Python 3.13+; see
-[Captcha Blocking Login](https://amazon-orders.readthedocs.io/troubleshooting.html#captcha-blocking-login) for details.
+[Login Challenges](https://amazon-orders.readthedocs.io/troubleshooting.html#login-challenges) for details.
 
 ## Documentation
 

{amazon_orders-4.2.2 → amazon_orders-4.3.0}/README.md

@@ -28,7 +28,7 @@ pip install amazon-orders --upgrade
 
 That's it! `amazon-orders` is now available as a package to your Python projects and from the command line.
 
-If pinning, be sure to use a wildcard for the [minor version](https://semver.org/) (ex. `==4.2.*`, not `==4.2.2`) to
+If pinning, be sure to use a wildcard for the [minor version](https://semver.org/) (ex. `==4.3.*`, not `==4.2.1`) to
 ensure you always get the latest stable release.
 
 ## Basic Usage
@@ -97,6 +97,16 @@ pip install amazon-orders[2captcha]
 
 See [Solving WAF Challenges](https://amazon-orders.readthedocs.io/waf.html) for details.
 
+To enable **browser-based challenge handling** (ACIC and JavaScript bot-detection pages) via
+a headless browser, install with the `browser` extra:
+
+```sh
+pip install amazon-orders[browser]
+playwright install chromium
+```
+
+See [Browser Automation](https://amazon-orders.readthedocs.io/browser.html) for details.
+
 To enable **Captcha auto-solve** on Python <=3.12 (via the optional [`amazoncaptcha`](https://pypi.org/project/amazoncaptcha/)
 dependency), install with the `captcha` extra:
 
@@ -105,7 +115,7 @@ pip install amazon-orders[captcha]
 ```
 
 Without this extra, Captcha challenges fall back to manual entry. `amazoncaptcha` is not available on Python 3.13+; see
-[Captcha Blocking Login](https://amazon-orders.readthedocs.io/troubleshooting.html#captcha-blocking-login) for details.
+[Login Challenges](https://amazon-orders.readthedocs.io/troubleshooting.html#login-challenges) for details.
 
 ## Documentation
 

{amazon_orders-4.2.2 → amazon_orders-4.3.0/amazon_orders.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: amazon-orders
-Version: 4.2.2
+Version: 4.3.0
 Summary: A Python library (and CLI) for Amazon order history
 Author-email: Alex Laird <contact@alexlaird.com>
 Maintainer-email: Alex Laird <contact@alexlaird.com>
@@ -43,6 +43,8 @@ Provides-Extra: anticaptcha
 Requires-Dist: anticaptchaofficial; extra == "anticaptcha"
 Provides-Extra: 2captcha
 Requires-Dist: 2captcha-python; extra == "2captcha"
+Provides-Extra: browser
+Requires-Dist: playwright>=1.47.0; extra == "browser"
 Provides-Extra: lxml
 Requires-Dist: lxml; extra == "lxml"
 Provides-Extra: dev
@@ -101,7 +103,7 @@ pip install amazon-orders --upgrade
 
 That's it! `amazon-orders` is now available as a package to your Python projects and from the command line.
 
-If pinning, be sure to use a wildcard for the [minor version](https://semver.org/) (ex. `==4.2.*`, not `==4.2.2`) to
+If pinning, be sure to use a wildcard for the [minor version](https://semver.org/) (ex. `==4.3.*`, not `==4.2.1`) to
 ensure you always get the latest stable release.
 
 ## Basic Usage
@@ -170,6 +172,16 @@ pip install amazon-orders[2captcha]
 
 See [Solving WAF Challenges](https://amazon-orders.readthedocs.io/waf.html) for details.
 
+To enable **browser-based challenge handling** (ACIC and JavaScript bot-detection pages) via
+a headless browser, install with the `browser` extra:
+
+```sh
+pip install amazon-orders[browser]
+playwright install chromium
+```
+
+See [Browser Automation](https://amazon-orders.readthedocs.io/browser.html) for details.
+
 To enable **Captcha auto-solve** on Python <=3.12 (via the optional [`amazoncaptcha`](https://pypi.org/project/amazoncaptcha/)
 dependency), install with the `captcha` extra:
 
@@ -178,7 +190,7 @@ pip install amazon-orders[captcha]
 ```
 
 Without this extra, Captcha challenges fall back to manual entry. `amazoncaptcha` is not available on Python 3.13+; see
-[Captcha Blocking Login](https://amazon-orders.readthedocs.io/troubleshooting.html#captcha-blocking-login) for details.
+[Login Challenges](https://amazon-orders.readthedocs.io/troubleshooting.html#login-challenges) for details.
 
 ## Documentation
 

{amazon_orders-4.2.2 → amazon_orders-4.3.0}/amazon_orders.egg-info/SOURCES.txt

@@ -22,6 +22,8 @@ amazonorders/session.py
 amazonorders/transactions.py
 amazonorders/util.py
 amazonorders/contrib/__init__.py
+amazonorders/contrib/browser/__init__.py
+amazonorders/contrib/browser/playwright.py
 amazonorders/contrib/waf/__init__.py
 amazonorders/contrib/waf/anticaptcha.py
 amazonorders/contrib/waf/base.py

{amazon_orders-4.2.2 → amazon_orders-4.3.0}/amazon_orders.egg-info/requires.txt

@@ -12,6 +12,9 @@ pyotp>=2.9
 [anticaptcha]
 anticaptchaofficial
 
+[browser]
+playwright>=1.47.0
+
 [capsolver]
 capsolver
 

{amazon_orders-4.2.2 → amazon_orders-4.3.0}/amazonorders/__init__.py

@@ -1,3 +1,3 @@
 __copyright__ = "Copyright (c) 2024-2025 Alex Laird"
 __license__ = "MIT"
-__version__ = "4.2.2"
+__version__ = "4.3.0"

{amazon_orders-4.2.2 → amazon_orders-4.3.0}/amazonorders/constants.py

@@ -1,13 +1,32 @@
 __copyright__ = "Copyright (c) 2024-2025 Alex Laird"
 __license__ = "MIT"
 
+import logging
 import os
-from typing import Optional, TYPE_CHECKING
+from typing import Dict, Optional, TYPE_CHECKING
 from urllib.parse import urlencode, urlparse
 
 if TYPE_CHECKING:
     from amazonorders.conf import AmazonOrdersConfig
 
+logger = logging.getLogger(__name__)
+
+#: Browser-specific header overrides applied on top of the class-level ``BASE_HEADERS``
+#: (which already reflects the Chromium fingerprint). A ``None`` value removes the key
+#: (used to strip headers absent in that engine). ``Accept-Language`` here is the browser
+#: default; domain-specific TLD overrides still apply on top via :func:`~Constants._apply_domain`.
+_BROWSER_PRESETS: Dict[str, Dict[str, Optional[str]]] = {
+    "chromium": {},  # BASE_HEADERS already reflects the Chromium fingerprint; no overrides needed.
+    "firefox": {
+        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+        "Accept-Language": "en-US,en;q=0.5",
+        "Sec-Ch-Ua": None,
+        "Sec-Ch-Ua-Mobile": None,
+        "Sec-Ch-Ua-Platform": None,
+        "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:146.0) Gecko/20100101 Firefox/146.0",
+    },
+}
+
 #: ``Accept-Language`` values for English-locale Amazon sites, keyed by the TLD suffix that
 #: follows ``amazon.``. Looked up dynamically from the user-supplied domain; unknown TLDs keep
 #: the base ``en-US`` value. This map only governs the ``Accept-Language`` header — it is not
@@ -105,35 +124,21 @@ class Constants:
     ##########################################################################
 
     BASE_HEADERS = {
-        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,"
-                  "application/signed-exchange;v=b3;q=0.7",
+        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7",  # noqa: E501
         "Accept-Encoding": "gzip, deflate, br, zstd",
         "Accept-Language": "en-US,en;q=0.9",
-        "Cache-Control": "max-age=0",
-        "Device-Memory": "8",
-        "Downlink": "10",
-        "Dpr": "2",
-        "Ect": "4g",
-        "Origin": BASE_URL,
         "Host": urlparse(BASE_URL).netloc,
-        "Priority": "u=0, i",
+        "Origin": BASE_URL,
         "Referer": f"{SIGN_IN_URL}?{urlencode(SIGN_IN_QUERY_PARAMS)}",
-        "Rtt": "0",
-        "Sec-Ch-Device-Memory": "8",
-        "Sec-Ch-Dpr": "2",
-        "Sec-Ch-Ua": "Chromium\";v=\"140\", \"Not=A?Brand\";v=\"24\", \"Google Chrome\";v=\"140",
+        "Sec-Ch-Ua": '"Chromium";v="149", "Google Chrome";v="149", "Not.A/Brand";v="24"',
         "Sec-Ch-Ua-Mobile": "?0",
-        "Sec-Ch-Ua-Platform": "macOS",
-        "Sec-Ch-Ua-Platform-Version": "15.6.1",
-        "Sec-Ch-Viewport-Width": "1512",
+        "Sec-Ch-Ua-Platform": '"macOS"',
         "Sec-Fetch-Dest": "document",
         "Sec-Fetch-Mode": "navigate",
         "Sec-Fetch-Site": "none",
         "Sec-Fetch-User": "?1",
         "Upgrade-Insecure-Requests": "1",
-        "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6_1) AppleWebKit/537.36 (KHTML, like Gecko) "
-                      "Chrome/140.0.0.0 Safari/537.36",
-        "Viewport-Width": "1512"
+        "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/149.0.0.0 Safari/537.36",  # noqa: E501
     }
 
     ##########################################################################
@@ -152,13 +157,41 @@ class Constants:
     def __init__(self,
                  config: Optional["AmazonOrdersConfig"] = None) -> None:
         domain = None
+        browser = None
         if config is not None:
             domain = config._data.get("domain")
+            browser = config._data.get("browser")
         if not domain:
             domain = os.environ.get("AMAZON_BASE_URL")
+        if not browser:
+            browser = os.environ.get("AMAZON_BROWSER")
+        self._apply_browser(browser or "chromium")
         if domain:
             self._apply_domain(domain)
 
+    def _apply_browser(self,
+                       browser: str) -> None:
+        """
+        Apply browser-specific header overrides for the given browser engine.
+
+        :param browser: Browser engine name — ``"firefox"`` or ``"chromium"``. Unknown values
+            log a warning and leave ``BASE_HEADERS`` unchanged.
+        """
+        preset = _BROWSER_PRESETS.get(browser)
+        if preset is None:
+            logger.warning(
+                f"Unknown browser value {browser!r}; "
+                f"valid values are: {', '.join(_BROWSER_PRESETS)}. Using default headers."
+            )
+            return
+        headers = dict(type(self).BASE_HEADERS)
+        for key, value in preset.items():
+            if value is None:
+                headers.pop(key, None)
+            else:
+                headers[key] = value
+        self.BASE_HEADERS = headers
+
     def _apply_domain(self,
                       domain: str) -> None:
         """
@@ -168,8 +201,8 @@ class Constants:
         """
         base_url = _normalize_base_url(domain)
 
-        # Read non-URL fields from the class so subclass-level overrides (assoc_handle,
-        # Accept-Language, etc.) are preserved; only rewrite the URL-shaped values.
+        # Build from the instance-level BASE_HEADERS if _apply_browser has already set it;
+        # otherwise fall back to the class-level definition.
         sign_in_query_params = dict(type(self).SIGN_IN_QUERY_PARAMS)
         sign_in_query_params["openid.return_to"] = f"{base_url}/?ref_=nav_custrec_signin"
 
@@ -189,7 +222,7 @@ class Constants:
             host = host[len("www."):]
         tld = host[len("amazon."):] if host.startswith("amazon.") else ""
 
-        headers = dict(type(self).BASE_HEADERS)
+        headers = dict(vars(self).get("BASE_HEADERS", type(self).BASE_HEADERS))
         headers["Origin"] = base_url
         headers["Host"] = urlparse(base_url).netloc
         headers["Referer"] = f"{sign_in_url}?{urlencode(sign_in_query_params)}"

amazon_orders-4.3.0/amazonorders/contrib/browser/playwright.py

@@ -0,0 +1,412 @@
+__copyright__ = "Copyright (c) 2024-2025 Alex Laird"
+__license__ = "MIT"
+
+import json
+import logging
+import os
+import re
+from abc import abstractmethod
+from typing import Any, Dict, Optional, TYPE_CHECKING
+from urllib.parse import urlparse
+
+from bs4 import Tag
+from requests import Response
+
+from amazonorders.conf import AmazonOrdersConfig
+from amazonorders.contrib.waf.base import _GOKU_PROPS_RE
+from amazonorders.exception import AmazonOrdersError
+from amazonorders.forms import AuthForm
+from amazonorders.util import AmazonSessionResponse
+
+if TYPE_CHECKING:
+    from amazonorders.session import AmazonSession
+
+logger = logging.getLogger(__name__)
+
+
+class PlaywrightAuthForm(AuthForm):
+    """
+    Shared base for Playwright-based JavaScript challenge solvers. Subclasses implement
+    :func:`select_form` to detect the challenge page and :func:`_is_challenge_url` to
+    signal when navigation has completed.
+
+    This base class handles the Playwright browser lifecycle, bidirectional cookie bridging
+    between :mod:`requests` and the Playwright browser context, and re-fetching the final
+    URL once the challenge resolves.
+
+    Requires the ``[browser]`` extra: ``pip install amazon-orders[browser]``,
+    then ``playwright install chromium``.
+    """
+
+    def __init__(self,
+                 config: AmazonOrdersConfig) -> None:
+        super().__init__(config, selector=None)
+        #: Whether to launch the browser in headless mode. Defaults to ``True``.
+        #: Set to ``False`` in subclasses that require user interaction.
+        self.headless: bool = True
+
+    def fill_form(self,
+                  additional_attrs: Optional[Dict[str, Any]] = None) -> None:
+        """JavaScript challenge pages have no ``<form>`` to populate; no-op override."""
+        pass
+
+    def submit(self,
+               last_response: Response) -> AmazonSessionResponse:
+        """
+        Launch a headless browser, bridge the current session cookies into it,
+        navigate to the challenge URL, wait for the challenge to resolve, harvest the
+        resulting cookies back into the session, and re-fetch the final URL.
+
+        :param last_response: The response that returned the JavaScript challenge page.
+        :return: The :class:`~amazonorders.util.AmazonSessionResponse` from re-fetching
+            the URL after the challenge resolves.
+        :raises AmazonOrdersError: if the ``playwright`` package is not installed, if
+            :func:`select_form` was not called first, or if the challenge does not resolve
+            within the timeout.
+        """
+        if not self.amazon_session:
+            raise AmazonOrdersError(
+                "Call PlaywrightAuthForm.select_form() first."
+            )  # pragma: no cover
+
+        try:
+            from playwright.sync_api import (  # type: ignore[import-not-found]
+                sync_playwright,
+                TimeoutError as PlaywrightTimeoutError,
+            )
+        except ImportError as e:
+            raise AmazonOrdersError(
+                f"{type(self).__name__} requires the [browser] extra. "
+                "Install it with: `pip install amazon-orders[browser]`, then: `playwright install chromium`"
+            ) from e
+
+        debug = self.amazon_session.debug
+        if debug:
+            logger.setLevel(logging.DEBUG)
+
+        message = "Info: A browser is handling a JavaScript authentication challenge."
+        logger.info(message)
+        self.amazon_session.io.echo(message)
+        output_dir = self.config.output_dir if debug else None
+        original_url = last_response.url
+
+        browser_name = self.config.browser or "chromium"
+        with sync_playwright() as pw:
+            browser_launcher = getattr(pw, browser_name, None)
+            if browser_launcher is None:
+                raise AmazonOrdersError(
+                    f"Unsupported browser: {browser_name!r}. "
+                    f"Valid values: firefox, chromium."
+                )
+            browser = browser_launcher.launch(headless=self.headless)
+            context = browser.new_context()
+
+            self._inject_cookies(context, original_url)
+
+            page = context.new_page()
+            page.goto(original_url)
+            logger.debug(f"Browser navigated to challenge URL: {page.url}")
+
+            self._save_debug_snapshot(page, output_dir, "browser-challenge")
+            self._on_challenge_page(page, context, output_dir)
+
+            try:
+                page.wait_for_url(
+                    lambda url: not self._is_challenge_url(url, original_url),
+                    timeout=30000
+                )
+            except PlaywrightTimeoutError as e:
+                logger.debug(f"Browser timed out at URL: {page.url}")
+                self._save_debug_snapshot(page, output_dir, "browser-timeout")
+                browser.close()
+                raise AmazonOrdersError(
+                    "Browser timed out waiting for the JavaScript challenge to resolve."
+                ) from e
+
+            final_url = page.url
+            logger.debug(f"Browser challenge resolved, final URL: {final_url}")
+            self._save_debug_snapshot(page, output_dir, "browser-resolved")
+            self._harvest_cookies(context)
+            browser.close()
+
+        response = self.amazon_session.get(final_url, persist_cookies=True)
+        self.clear_form()
+        return response
+
+    def _on_challenge_page(self, page: Any, context: Any, output_dir: Optional[str]) -> None:
+        """
+        Hook called after navigating to the challenge page and saving the initial
+        snapshot, but before waiting for the challenge URL to resolve. Override in
+        subclasses to take additional action (e.g. solving an embedded CAPTCHA).
+
+        :param page: The Playwright ``Page`` currently on the challenge URL.
+        :param context: The Playwright ``BrowserContext``.
+        :param output_dir: Directory for debug snapshots, or ``None`` when not in debug mode.
+        """
+        pass
+
+    @abstractmethod
+    def _is_challenge_url(self, url: str, original_url: str) -> bool:
+        """
+        Return ``True`` if ``url`` is still on the challenge page; ``False`` once
+        the challenge has resolved and navigation may stop.
+
+        :param url: The current browser URL.
+        :param original_url: The URL of the page that first showed the challenge.
+        :return: ``True`` while the challenge is active.
+        """
+        raise NotImplementedError  # pragma: no cover
+
+    def _inject_cookies(self, context: Any, url: str) -> None:
+        if not self.amazon_session:
+            return  # pragma: no cover
+        domain = urlparse(url).netloc
+        playwright_cookies = []
+        for cookie in self.amazon_session.session.cookies:
+            playwright_cookies.append({
+                "name": cookie.name,
+                "value": cookie.value or "",
+                "domain": cookie.domain or domain,
+                "path": cookie.path or "/",
+            })
+        if playwright_cookies:
+            context.add_cookies(playwright_cookies)
+
+    def _harvest_cookies(self, context: Any) -> None:
+        if not self.amazon_session:
+            return  # pragma: no cover
+        for pw_cookie in context.cookies():
+            self.amazon_session.session.cookies.set(
+                pw_cookie["name"],
+                pw_cookie["value"],
+                domain=pw_cookie.get("domain"),
+                path=pw_cookie.get("path", "/"),
+            )
+
+    def _save_debug_snapshot(self, page: Any, output_dir: Optional[str], name: str) -> None:
+        if not output_dir:
+            return
+        try:
+            os.makedirs(output_dir, exist_ok=True)
+            page.screenshot(path=os.path.join(output_dir, f"{name}.png"))
+            with open(os.path.join(output_dir, f"{name}.html"), "w", encoding="utf-8") as f:
+                f.write(page.content())
+            logger.debug(f"Debug snapshot saved: {name} (url={page.url})")
+        except Exception:
+            logger.debug(f"Debug snapshot failed to save: {name}", exc_info=True)
+
+
+class PlaywrightAcicForm(PlaywrightAuthForm):
+    """
+    Handles Amazon's ACIC (Amazon Challenge and Identity Component) JavaScript challenge
+    by running it in a headless browser. If an embedded AWS WAF challenge is present on
+    the ACIC page, it will be solved automatically using the first
+    :class:`~amazonorders.contrib.waf.base.AwsWafForm` found in ``auth_forms_classes``.
+
+    Detects the challenge via the ``#aa-challenge-page-captcha-container`` element and
+    waits for navigation away from ``/ax/aaut/verify/ap/challenge``.
+
+    Register via ``auth_forms_classes`` in :class:`~amazonorders.conf.AmazonOrdersConfig`:
+
+    .. code-block:: yaml
+
+        auth_forms_classes:
+          - "amazonorders.contrib.browser.playwright.PlaywrightAcicForm"
+    """
+
+    def select_form(self,
+                    amazon_session: "AmazonSession",
+                    parsed: Tag) -> bool:
+        """
+        Detect an ACIC challenge page by the presence of
+        ``#aa-challenge-page-captcha-container``.
+
+        :param amazon_session: The ``AmazonSession`` on which to submit the form.
+        :param parsed: The ``Tag`` for the page being inspected.
+        :return: ``True`` if an ACIC challenge was detected, ``False`` otherwise.
+        """
+        self.amazon_session = amazon_session
+        return bool(parsed.find(id="aa-challenge-page-captcha-container"))
+
+    def _on_challenge_page(self, page: Any, context: Any, output_dir: Optional[str]) -> None:
+        self._try_solve_embedded_waf(page, context, output_dir)
+
+    def _try_solve_embedded_waf(self, page: Any, context: Any, output_dir: Optional[str]) -> bool:
+        """
+        If the ACIC challenge page contains an embedded AWS WAF challenge, solve it
+        using the first :class:`~amazonorders.contrib.waf.base.AwsWafForm` found in
+        ``amazon_session.auth_forms``, inject the resulting ``aws-waf-token`` cookie
+        into the browser context, and reload the page.
+
+        :param page: The Playwright ``Page`` on the ACIC challenge URL.
+        :param context: The Playwright ``BrowserContext``.
+        :param output_dir: Directory for debug snapshots, or ``None``.
+        :return: ``True`` if a WAF token was obtained and injected, ``False`` otherwise.
+        """
+        try:
+            from playwright.sync_api import TimeoutError as PlaywrightTimeoutError  # type: ignore[import-not-found]
+        except ImportError:
+            return False  # pragma: no cover
+
+        try:
+            page.wait_for_function("() => typeof window.gokuProps !== 'undefined'", timeout=8000)
+        except PlaywrightTimeoutError:
+            logger.debug("No window.gokuProps in ACIC page — no embedded WAF challenge to solve.")
+            return False
+
+        try:
+            goku = page.evaluate("() => window.gokuProps")
+            challenge_script = page.evaluate(
+                "() => (Array.from(document.querySelectorAll('script[src]'))"
+                ".find(s => s.src.includes('awswaf.com')) || {}).src || null"
+            )
+        except Exception:
+            logger.debug("Failed to extract WAF props from ACIC page.", exc_info=True)
+            return False
+
+        if not goku or not challenge_script:
+            logger.debug("Incomplete WAF props in ACIC page — goku=%r, script=%r.", goku, challenge_script)
+            return False
+
+        if not self.amazon_session:
+            return False  # pragma: no cover
+
+        from amazonorders.contrib.waf.base import AwsWafForm
+        waf_form = next(
+            (f for f in self.amazon_session.auth_forms if isinstance(f, AwsWafForm)),
+            None,
+        )
+        if not waf_form:
+            logger.debug("Embedded WAF challenge found but no AwsWafForm configured — skipping solve.")
+            return False
+
+        try:
+            token = waf_form._solve_token(page.url, goku, challenge_script)
+        except Exception:
+            logger.debug("WAF solver raised an exception solving embedded ACIC CAPTCHA.", exc_info=True)
+            return False
+
+        message = f"Info: Solved embedded WAF challenge via {waf_form.PROVIDER_NAME}."
+        logger.info(message)
+        self.amazon_session.io.echo(message)
+
+        domain = urlparse(page.url).netloc
+        context.add_cookies([{
+            "name": "aws-waf-token",
+            "value": token,
+            "domain": f".{domain}",
+            "path": "/",
+        }])
+        page.reload(wait_until="load")
+        logger.debug("Reloaded ACIC page after WAF token injection.")
+        self._save_debug_snapshot(page, output_dir, "browser-waf-injected")
+        return True
+
+    def _is_challenge_url(self, url: str, original_url: str) -> bool:
+        return "/ax/aaut/verify/ap/challenge" in url
+
+
+class PlaywrightJSAuthForm(PlaywrightAuthForm):
+    """
+    Handles Amazon's JavaScript bot-detection challenge page by running it in a
+    headless browser. This is a best-effort form; effectiveness
+    depends on whether the challenge can be resolved by a real browser without a visual puzzle.
+
+    Detects the challenge via :attr:`~amazonorders.constants.Constants.JS_ROBOT_TEXT_REGEX`
+    and waits for navigation away from the original challenge URL path.
+
+    Register via ``auth_forms_classes`` in :class:`~amazonorders.conf.AmazonOrdersConfig`:
+
+    .. code-block:: yaml
+
+        auth_forms_classes:
+          - "amazonorders.contrib.browser.playwright.PlaywrightJSAuthForm"
+    """
+
+    def __init__(self,
+                 config: AmazonOrdersConfig) -> None:
+        super().__init__(config)
+        #: The regex used to detect the JavaScript bot-detection page text.
+        self.regex: str = config.constants.JS_ROBOT_TEXT_REGEX
+
+    def select_form(self,
+                    amazon_session: "AmazonSession",
+                    parsed: Tag) -> bool:
+        """
+        Detect a JavaScript bot-detection page by matching
+        :attr:`~amazonorders.constants.Constants.JS_ROBOT_TEXT_REGEX` against the page text.
+
+        :param amazon_session: The ``AmazonSession`` on which to submit the form.
+        :param parsed: The ``Tag`` for the page being inspected.
+        :return: ``True`` if a JavaScript bot challenge was detected, ``False`` otherwise.
+        """
+        self.amazon_session = amazon_session
+        return bool(re.search(self.regex, parsed.text))
+
+    def _is_challenge_url(self, url: str, original_url: str) -> bool:
+        return url.split("?")[0] == original_url.split("?")[0]
+
+
+class PlaywrightManualWafForm(PlaywrightAuthForm):
+    """
+    Handles Amazon's AWS WAF JavaScript challenge by opening a **visible** browser
+    window so the user can solve the CAPTCHA manually. Once the challenge
+    resolves and the browser navigates away, cookies are harvested back into the
+    session automatically.
+
+    Because it opens a browser window it requires a display and a user at the
+    keyboard, making it suitable for local/interactive use but not for headless
+    servers or CI.
+
+    Detects the challenge via the ``window.gokuProps`` blob and the
+    ``challenge.js`` script tag (same signals as
+    :class:`~amazonorders.contrib.waf.base.AwsWafForm`), and waits for navigation
+    away from the original challenge URL path.
+
+    Register via ``auth_forms_classes`` in :class:`~amazonorders.conf.AmazonOrdersConfig`:
+
+    .. code-block:: yaml
+
+        auth_forms_classes:
+          - amazonorders.contrib.browser.playwright.PlaywrightManualWafForm
+    """
+
+    def __init__(self,
+                 config: AmazonOrdersConfig) -> None:
+        super().__init__(config)
+        self.headless = False
+
+    def select_form(self,
+                    amazon_session: "AmazonSession",
+                    parsed: Tag) -> bool:
+        """
+        Detect an AWS WAF challenge page by matching the ``window.gokuProps``
+        blob and the ``challenge.js`` script tag.
+
+        :param amazon_session: The ``AmazonSession`` on which to submit the form.
+        :param parsed: The ``Tag`` for the page being inspected.
+        :return: ``True`` if a WAF challenge was detected, ``False`` otherwise.
+        """
+        self.amazon_session = amazon_session
+
+        match = _GOKU_PROPS_RE.search(str(parsed))
+        if not match:
+            return False
+        try:
+            json.loads(match.group(1))
+        except (json.JSONDecodeError, ValueError):
+            return False
+
+        challenge_tag = parsed.select_one('script[src*="awswaf.com"]')
+        return challenge_tag is not None and isinstance(challenge_tag.get("src"), str)
+
+    def _on_challenge_page(self, page: Any, context: Any, output_dir: Optional[str]) -> None:
+        message = (
+            "Info: A browser window has opened — solve the CAPTCHA, then return here when done."
+        )
+        logger.info(message)
+        if self.amazon_session:
+            self.amazon_session.io.echo(message)
+
+    def _is_challenge_url(self, url: str, original_url: str) -> bool:
+        return url.split("?")[0] == original_url.split("?")[0]

{amazon_orders-4.2.2 → amazon_orders-4.3.0}/amazonorders/contrib/waf/anticaptcha.py

@@ -40,7 +40,7 @@ class AntiCaptchaWafForm(AwsWafForm):
         except ImportError as e:
             raise AmazonOrdersError(
                 "AntiCaptchaWafForm requires the 'anticaptchaofficial' package. "
-                "Install it with: pip install amazon-orders[anticaptcha]"
+                "Install it with: `pip install amazon-orders[anticaptcha]`"
             ) from e
 
         solver = amazonProxyless()

{amazon_orders-4.2.2 → amazon_orders-4.3.0}/amazonorders/contrib/waf/capsolver.py

@@ -40,7 +40,7 @@ class CapSolverWafForm(AwsWafForm):
         except ImportError as e:
             raise AmazonOrdersError(
                 "CapSolverWafForm requires the 'capsolver' package. "
-                "Install it with: pip install amazon-orders[capsolver]"
+                "Install it with: `pip install amazon-orders[capsolver]`"
             ) from e
 
         capsolver.api_key = self.api_key

{amazon_orders-4.2.2 → amazon_orders-4.3.0}/amazonorders/contrib/waf/twocaptcha.py

@@ -43,7 +43,7 @@ class TwoCaptchaWafForm(AwsWafForm):
         except ImportError as e:
             raise AmazonOrdersError(
                 "TwoCaptchaWafForm requires the '2captcha-python' package. "
-                "Install it with: pip install amazon-orders[2captcha]"
+                "Install it with: `pip install amazon-orders[2captcha]`"
             ) from e
 
         solver = TwoCaptcha(self.api_key)

{amazon_orders-4.2.2 → amazon_orders-4.3.0}/amazonorders/entity/transaction.py

@@ -32,6 +32,9 @@ class Transaction(Parsable):
         self.payment_method: str = self.safe_simple_parse(
             selector=self.config.selectors.FIELD_TRANSACTION_PAYMENT_METHOD_SELECTOR
         )
+        #: The Transaction payment method's last digits, parsed from :attr:`payment_method`.
+        #: ``None`` if no masked digits.
+        self.payment_method_last_4: Optional[str] = self.safe_parse(self._parse_payment_method_last_4)
         #: The Transaction grand total.
         self.grand_total: float = self.safe_parse(self._parse_grand_total)
         #: The Transaction was a refund or not.
@@ -91,3 +94,11 @@ class Transaction(Parsable):
             value = f"{self.config.constants.ORDER_DETAILS_URL}?orderID={self.order_number}"
 
         return value
+
+    def _parse_payment_method_last_4(self) -> Optional[str]:
+        if not self.payment_method:
+            return None
+
+        match = re.search(r"\*+(\d+)$", self.payment_method)
+
+        return match.group(1) if match else None

{amazon_orders-4.2.2 → amazon_orders-4.3.0}/amazonorders/forms.py

@@ -461,8 +461,9 @@ class AcicAuthBlocker(AuthForm):
                     parsed: Tag) -> bool:
         if parsed.find(id="aa-challenge-page-captcha-container"):
             raise AmazonOrdersAuthError(
-                "Amazon returned a JavaScript-based authentication challenge that this library cannot solve. See "
-                "https://amazon-orders.readthedocs.io/troubleshooting.html#captcha-blocking-login for help.")
+                "Amazon returned a JavaScript-based authentication challenge. Install the [browser] extra to "
+                "handle this automatically: `pip install amazon-orders[browser]`, then `playwright install chromium`. "
+                "See https://amazon-orders.readthedocs.io/browser.html for details.")
 
         return False
 
@@ -483,7 +484,8 @@ class JSAuthBlocker(AuthForm):
 
         if re.search(self.regex, parsed.text):
             raise AmazonOrdersAuthError(
-                "Amazon returned a JavaScript-based authentication challenge that this library cannot solve. See "
-                "https://amazon-orders.readthedocs.io/troubleshooting.html#captcha-blocking-login for help.")
+                "Amazon returned a JavaScript-based authentication challenge. Install the [browser] extra to "
+                "handle this automatically: `pip install amazon-orders[browser]`, then `playwright install chromium`. "
+                "See https://amazon-orders.readthedocs.io/browser.html for details.")
 
         return False

{amazon_orders-4.2.2 → amazon_orders-4.3.0}/amazonorders/session.py

@@ -82,6 +82,7 @@ class AmazonSession:
             config.set_domain(domain)
         if not auth_forms:
             auth_forms = AmazonSession.default_auth_forms(config)
+            custom_forms = []
             for path in config.auth_forms_classes or []:
                 try:
                     module_path, class_name = path.rsplit(".", 1)
@@ -97,8 +98,13 @@ class AmazonSession:
                     )
                 # AuthForm subclasses registered via auth_forms_classes are expected to take
                 # only ``config`` (e.g. AwsWafForm subclasses); the base AuthForm signature
-                # additionally requires ``selector``
-                auth_forms.insert(-1, cls(config))  # type: ignore[call-arg]
+                # additionally requires ``selector``.
+                custom_forms.append(cls(config))  # type: ignore[call-arg]
+            # Insert as a block before the blocker pair (AcicAuthBlocker, JSAuthBlocker)
+            # so that solver forms run first while preserving auth_forms_classes order.
+            insert_pos = len(auth_forms) - 2
+            for offset, form_instance in enumerate(custom_forms):
+                auth_forms.insert(insert_pos + offset, form_instance)
 
         #: An Amazon username. Environment variable ``AMAZON_USERNAME`` will override passed in or config value.
         self.username: Optional[str] = os.environ.get("AMAZON_USERNAME") or username or config.username

{amazon_orders-4.2.2 → amazon_orders-4.3.0}/pyproject.toml

@@ -48,6 +48,9 @@ anticaptcha = [
 2captcha = [
     "2captcha-python",
 ]
+browser = [
+    "playwright>=1.47.0",
+]
 lxml = [
     "lxml",
 ]