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

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

@@ -4,7 +4,29 @@ 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.3.0...HEAD)
+## [Unreleased](https://github.com/alexdlaird/amazon-orders/compare/4.4.0...HEAD)
+
+## [4.4.0](https://github.com/alexdlaird/amazon-orders/compare/4.3.1...4.4.0) - 2026-06-12
+
+### Added
+
+- `PlaywrightAcicForm` now solves visual grid Puzzles (e.g. "Choose all the buckets") automatically when a WAF solver extra is configured. Puzzles are detected and solved in a loop alongside the existing WAF token challenge, handling any combination Amazon presents.
+- `AwsWafForm._solve_visual_captcha()` subclass hook for Puzzle classification. `CapSolverWafForm` implements this via the `AwsWafClassification` task type.
+- `browser_timeout` config key (defaults to 30s) controlling how long the browser waits for challenge elements to appear.
+- `retry_failures` input on the integration test workflow for fail-fast CI runs.
+- Build and stability improvements.
+
+## [4.3.1](https://github.com/alexdlaird/amazon-orders/compare/4.3.0...4.3.1) - 2026-06-07
+
+### Added
+
+- `AmazonOrders.get_invoice()` to fetch an Order's print-friendly invoice page, returning the response (including its parsed HTML) for rendering or printing.
+- `AmazonTransactions.get_transactions()` `order_id` parameter to scope results to a single Order server-side via Amazon's `transactionTag` filter, bypassing the `days` window.
+
+### Added
+
+- `AmazonOrders.get_invoice()` to fetch an Order's print-friendly invoice page, returning the response (including its parsed HTML) for rendering or printing.
+- `AmazonTransactions.get_transactions()` `order_id` parameter to scope results to a single Order server-side via Amazon's `transactionTag` filter, bypassing the `days` window.
 
 ## [4.3.0](https://github.com/alexdlaird/amazon-orders/compare/4.2.2...4.3.0) - 2026-06-07
 
@@ -22,6 +44,15 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - 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.
 
+### 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 WAF is present, it delegates automatically to any configured WAF solver extra.
+  - `PlaywrightJSAuthForm` is a best-effort handler for the JS bot-detection page.
+  - `PlaywrightManualWafForm` opens a **visible** browser window for you to solve the challenge yourself, suitable when a display is available.
+- `browser` config key and `AMAZON_BROWSER` environment variable to select between `chromium` (default) and `firefox` browser user agents.
+- `Transaction.payment_method_last_4`, the masked card digits parsed from `payment_method`, mirroring the existing field on `Order`.
+
 ## [4.2.2](https://github.com/alexdlaird/amazon-orders/compare/4.2.1...4.2.2) - 2026-06-06
 
 ### Fixed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: amazon-orders
-Version: 4.3.0
+Version: 4.4.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>
@@ -35,18 +35,18 @@ Requires-Dist: beautifulsoup4>=4.12
 Requires-Dist: PyYAML>=6.0.3
 Requires-Dist: python-dateutil>=2.9.0.post0
 Requires-Dist: pyotp>=2.9
-Provides-Extra: captcha
-Requires-Dist: amazoncaptcha>=0.4; extra == "captcha"
+Provides-Extra: browser
+Requires-Dist: playwright>=1.47.0; extra == "browser"
 Provides-Extra: capsolver
 Requires-Dist: capsolver; extra == "capsolver"
 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: captcha
+Requires-Dist: amazoncaptcha>=0.4; extra == "captcha"
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: coverage[toml]; extra == "dev"
@@ -55,7 +55,6 @@ Requires-Dist: flake8-pyproject; extra == "dev"
 Requires-Dist: pep8-naming; extra == "dev"
 Requires-Dist: responses; extra == "dev"
 Requires-Dist: lxml; extra == "dev"
-Requires-Dist: amazoncaptcha>=0.4; python_version < "3.13" and extra == "dev"
 Provides-Extra: integration
 Requires-Dist: pytest-rerunfailures; extra == "integration"
 Requires-Dist: parameterized; extra == "integration"
@@ -103,7 +102,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.3.*`, not `==4.2.1`) to
+If pinning, be sure to use a wildcard for the [minor version](https://semver.org/) (ex. `==4.4.*`, not `==4.2.1`) to
 ensure you always get the latest stable release.
 
 ## Basic Usage
@@ -182,15 +181,13 @@ 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:
+For **legacy Captcha auto-solve** on Python <=3.12, install with `captcha` extra:
 
 ```sh
 pip install amazon-orders[captcha]
 ```
 
-Without this extra, Captcha challenges fall back to manual entry. `amazoncaptcha` is not available on Python 3.13+; see
-[Login Challenges](https://amazon-orders.readthedocs.io/troubleshooting.html#login-challenges) for details.
+See [Login Challenges](https://amazon-orders.readthedocs.io/troubleshooting.html#login-challenges) for details.
 
 ## Documentation
 

{amazon_orders-4.3.0 → amazon_orders-4.4.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.3.*`, not `==4.2.1`) to
+If pinning, be sure to use a wildcard for the [minor version](https://semver.org/) (ex. `==4.4.*`, not `==4.2.1`) to
 ensure you always get the latest stable release.
 
 ## Basic Usage
@@ -107,15 +107,13 @@ 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:
+For **legacy Captcha auto-solve** on Python <=3.12, install with `captcha` extra:
 
 ```sh
 pip install amazon-orders[captcha]
 ```
 
-Without this extra, Captcha challenges fall back to manual entry. `amazoncaptcha` is not available on Python 3.13+; see
-[Login Challenges](https://amazon-orders.readthedocs.io/troubleshooting.html#login-challenges) for details.
+See [Login Challenges](https://amazon-orders.readthedocs.io/troubleshooting.html#login-challenges) for details.
 
 ## Documentation
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: amazon-orders
-Version: 4.3.0
+Version: 4.4.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>
@@ -35,18 +35,18 @@ Requires-Dist: beautifulsoup4>=4.12
 Requires-Dist: PyYAML>=6.0.3
 Requires-Dist: python-dateutil>=2.9.0.post0
 Requires-Dist: pyotp>=2.9
-Provides-Extra: captcha
-Requires-Dist: amazoncaptcha>=0.4; extra == "captcha"
+Provides-Extra: browser
+Requires-Dist: playwright>=1.47.0; extra == "browser"
 Provides-Extra: capsolver
 Requires-Dist: capsolver; extra == "capsolver"
 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: captcha
+Requires-Dist: amazoncaptcha>=0.4; extra == "captcha"
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: coverage[toml]; extra == "dev"
@@ -55,7 +55,6 @@ Requires-Dist: flake8-pyproject; extra == "dev"
 Requires-Dist: pep8-naming; extra == "dev"
 Requires-Dist: responses; extra == "dev"
 Requires-Dist: lxml; extra == "dev"
-Requires-Dist: amazoncaptcha>=0.4; python_version < "3.13" and extra == "dev"
 Provides-Extra: integration
 Requires-Dist: pytest-rerunfailures; extra == "integration"
 Requires-Dist: parameterized; extra == "integration"
@@ -103,7 +102,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.3.*`, not `==4.2.1`) to
+If pinning, be sure to use a wildcard for the [minor version](https://semver.org/) (ex. `==4.4.*`, not `==4.2.1`) to
 ensure you always get the latest stable release.
 
 ## Basic Usage
@@ -182,15 +181,13 @@ 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:
+For **legacy Captcha auto-solve** on Python <=3.12, install with `captcha` extra:
 
 ```sh
 pip install amazon-orders[captcha]
 ```
 
-Without this extra, Captcha challenges fall back to manual entry. `amazoncaptcha` is not available on Python 3.13+; see
-[Login Challenges](https://amazon-orders.readthedocs.io/troubleshooting.html#login-challenges) for details.
+See [Login Challenges](https://amazon-orders.readthedocs.io/troubleshooting.html#login-challenges) for details.
 
 ## Documentation
 

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

@@ -30,9 +30,6 @@ pep8-naming
 responses
 lxml
 
-[dev:python_version < "3.13"]
-amazoncaptcha>=0.4
-
 [docs]
 Sphinx
 sphinx-notfound-page

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

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

{amazon_orders-4.3.0 → amazon_orders-4.4.0}/amazonorders/conf.py

@@ -58,6 +58,8 @@ class AmazonOrdersConfig:
             "item_class": "amazonorders.entity.item.Item",
             "bs4_parser": "html.parser",
             "auth_forms_classes": [],
+            # Timeout in seconds for browser-based challenge detection and resolution
+            "browser_timeout": 30,
             "thread_pool_size": (os.cpu_count() or 1) * 4,
             "connection_pool_size": thread_pool_size * 2,
             # The maximum number of failed attempts to allow before failing CLI authentication

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

@@ -110,6 +110,7 @@ class Constants:
 
     ORDER_HISTORY_URL = f"{BASE_URL}/your-orders/orders"
     ORDER_DETAILS_URL = f"{BASE_URL}/gp/your-account/order-details"
+    ORDER_INVOICE_URL = f"{BASE_URL}/gp/css/summary/print.html"
     HISTORY_FILTER_QUERY_PARAM = "timeFilter"
 
     ##########################################################################
@@ -147,6 +148,8 @@ class Constants:
 
     COOKIES_SET_WHEN_AUTHENTICATED = ["x-main"]
     JS_ROBOT_TEXT_REGEX = r"[.\s\S]*verify that you're not a robot[.\s\S]*Enable JavaScript[.\s\S]*"
+    GOKU_PROPS_REGEX = r"window\.gokuProps\s*=\s*(\{.*?\});"
+    ACIC_CHALLENGE_PATH = "/ax/aaut/verify/ap/challenge"
 
     ##########################################################################
     # Currency
@@ -215,6 +218,7 @@ class Constants:
         self.SIGN_OUT_URL = f"{base_url}/gp/flex/sign-out.html"
         self.ORDER_HISTORY_URL = f"{base_url}/your-orders/orders"
         self.ORDER_DETAILS_URL = f"{base_url}/gp/your-account/order-details"
+        self.ORDER_INVOICE_URL = f"{base_url}/gp/css/summary/print.html"
         self.TRANSACTION_HISTORY_URL = f"{base_url}{self.TRANSACTION_HISTORY_ROUTE}"
 
         host = urlparse(base_url).netloc.lower().split(":")[0]

{amazon_orders-4.3.0 → amazon_orders-4.4.0}/amazonorders/contrib/browser/playwright.py

@@ -1,6 +1,7 @@
 __copyright__ = "Copyright (c) 2024-2025 Alex Laird"
 __license__ = "MIT"
 
+import base64
 import json
 import logging
 import os
@@ -13,7 +14,6 @@ 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
@@ -81,8 +81,6 @@ class PlaywrightAuthForm(AuthForm):
             ) 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)
@@ -113,7 +111,7 @@ class PlaywrightAuthForm(AuthForm):
             try:
                 page.wait_for_url(
                     lambda url: not self._is_challenge_url(url, original_url),
-                    timeout=30000
+                    timeout=self.config.browser_timeout * 1000
                 )
             except PlaywrightTimeoutError as e:
                 logger.debug(f"Browser timed out at URL: {page.url}")
@@ -137,7 +135,7 @@ class PlaywrightAuthForm(AuthForm):
         """
         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).
+        subclasses to take additional action (e.g. solving an embedded Puzzle).
 
         :param page: The Playwright ``Page`` currently on the challenge URL.
         :param context: The Playwright ``BrowserContext``.
@@ -226,10 +224,20 @@ class PlaywrightAcicForm(PlaywrightAuthForm):
         :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"))
+        return bool(parsed.select_one(self.config.selectors.ACIC_CHALLENGE_SELECTOR))
 
     def _on_challenge_page(self, page: Any, context: Any, output_dir: Optional[str]) -> None:
-        self._try_solve_embedded_waf(page, context, output_dir)
+        max_solves = self.config.max_auth_attempts
+        solves = 0
+        while solves < max_solves:
+            if not self._is_challenge_url(page.url, page.url):
+                break
+            if self._try_solve_embedded_waf(page, context, output_dir):
+                solves += 1
+            elif self._try_solve_visual_captcha(page, context, output_dir):
+                solves += 1
+            else:
+                break
 
     def _try_solve_embedded_waf(self, page: Any, context: Any, output_dir: Optional[str]) -> bool:
         """
@@ -249,9 +257,12 @@ class PlaywrightAcicForm(PlaywrightAuthForm):
             return False  # pragma: no cover
 
         try:
-            page.wait_for_function("() => typeof window.gokuProps !== 'undefined'", timeout=8000)
+            page.wait_for_function(
+                "() => typeof window.gokuProps !== 'undefined'",
+                timeout=self.config.browser_timeout * 1000
+            )
         except PlaywrightTimeoutError:
-            logger.debug("No window.gokuProps in ACIC page — no embedded WAF challenge to solve.")
+            logger.debug("No window.gokuProps detected in ACIC page.")
             return False
 
         try:
@@ -265,7 +276,6 @@ class PlaywrightAcicForm(PlaywrightAuthForm):
             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:
@@ -277,13 +287,13 @@ class PlaywrightAcicForm(PlaywrightAuthForm):
             None,
         )
         if not waf_form:
-            logger.debug("Embedded WAF challenge found but no AwsWafForm configured — skipping solve.")
+            logger.debug("No AwsWafForm configured, skipping WAF challenge.")
             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)
+            logger.info("WAF solver failed to solve embedded WAF challenge.", exc_info=True)
             return False
 
         message = f"Info: Solved embedded WAF challenge via {waf_form.PROVIDER_NAME}."
@@ -298,12 +308,129 @@ class PlaywrightAcicForm(PlaywrightAuthForm):
             "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 _try_solve_visual_captcha(self, page: Any, context: Any, output_dir: Optional[str]) -> bool:
+        """
+        If the ACIC challenge page contains a visual grid Puzzle rendered by
+        ``CaptchaScript.renderCaptcha``, extract the challenge images and question,
+        solve it via the configured :class:`~amazonorders.contrib.waf.base.AwsWafForm`,
+        and submit the answer.
+
+        :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 the Puzzle was solved and submitted, ``False`` otherwise.
+        """
+        try:
+            from playwright.sync_api import TimeoutError as PlaywrightTimeoutError  # type: ignore[import-not-found]
+        except ImportError:
+            return False  # pragma: no cover
+
+        canvas_selector = self.config.selectors.ACIC_VISUAL_CAPTCHA_CANVAS_SELECTOR
+        try:
+            page.wait_for_selector(canvas_selector, state="attached",
+                                   timeout=self.config.browser_timeout * 1000)
+        except PlaywrightTimeoutError:
+            logger.debug("No Puzzle canvas detected on ACIC page.")
+            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("No AwsWafForm configured, skipping Puzzle.")
+            return False
+
+        question_selector = self.config.selectors.ACIC_VISUAL_CAPTCHA_QUESTION_SELECTOR
+        try:
+            canvas_locator = page.locator(canvas_selector).first
+            box = canvas_locator.bounding_box()
+            cols, rows = 3, 3
+            tw = box["width"] / cols
+            th = box["height"] / rows
+            challenge_images = []
+            for r in range(rows):
+                for c in range(cols):
+                    tile_bytes = page.screenshot(
+                        clip={"x": box["x"] + c * tw, "y": box["y"] + r * th,
+                              "width": tw, "height": th}
+                    )
+                    challenge_images.append(base64.b64encode(tile_bytes).decode())
+
+            question = page.evaluate(
+                "(sel) => {"
+                "  const el = document.querySelector(sel);"
+                "  return el ? el.textContent.trim() : null;"
+                "}",
+                question_selector,
+            )
+        except Exception:
+            logger.debug("Failed to extract Puzzle data from page.", exc_info=True)
+            return False
+
+        if not challenge_images or not question:
+            return False
+
+        try:
+            answer = waf_form._solve_visual_captcha(page.url, challenge_images, question)
+        except Exception:
+            logger.info("WAF solver failed to solve Puzzle.", exc_info=True)
+            return False
+
+        if answer is None:
+            logger.info(f"{waf_form.PROVIDER_NAME} does not support Puzzle solving.")
+            return False
+
+        message = f"Info: Puzzle solved via {waf_form.PROVIDER_NAME}."
+        logger.info(message)
+        self.amazon_session.io.echo(message)
+
+        verify_selector = self.config.selectors.ACIC_VISUAL_CAPTCHA_VERIFY_SELECTOR
+        try:
+            indices = answer if isinstance(answer[0], int) else [
+                i for i, v in enumerate(answer) if v]
+
+            page.evaluate(
+                "([sel, indices]) => {"
+                "  const canvas = document.querySelector(sel);"
+                "  if (!canvas) return;"
+                "  const rect = canvas.getBoundingClientRect();"
+                "  const cols = 3, rows = 3;"
+                "  const tw = rect.width / cols, th = rect.height / rows;"
+                "  indices.forEach(idx => {"
+                "    const r = Math.floor(idx / cols), c = idx % cols;"
+                "    const x = c * tw + tw / 2, y = r * th + th / 2;"
+                "    const evt = new MouseEvent('click', {"
+                "      bubbles: true, clientX: rect.left + x, clientY: rect.top + y"
+                "    });"
+                "    canvas.dispatchEvent(evt);"
+                "  });"
+                "}",
+                [canvas_selector, indices],
+            )
+
+            page.locator(verify_selector).click()
+        except Exception:
+            logger.debug("Failed to submit Puzzle answer.", exc_info=True)
+            return False
+
+        try:
+            page.wait_for_load_state("load", timeout=10000)
+        except PlaywrightTimeoutError:
+            pass
+
+        self._save_debug_snapshot(page, output_dir, "browser-visual-captcha-solved")
+        return True
+
     def _is_challenge_url(self, url: str, original_url: str) -> bool:
-        return "/ax/aaut/verify/ap/challenge" in url
+        return self.config.constants.ACIC_CHALLENGE_PATH in url
 
 
 class PlaywrightJSAuthForm(PlaywrightAuthForm):
@@ -350,7 +477,7 @@ class PlaywrightJSAuthForm(PlaywrightAuthForm):
 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
+    window so the user can solve the Puzzle manually. Once the challenge
     resolves and the browser navigates away, cookies are harvested back into the
     session automatically.
 
@@ -389,7 +516,8 @@ class PlaywrightManualWafForm(PlaywrightAuthForm):
         """
         self.amazon_session = amazon_session
 
-        match = _GOKU_PROPS_RE.search(str(parsed))
+        goku_re = re.compile(self.config.constants.GOKU_PROPS_REGEX, re.DOTALL)
+        match = goku_re.search(str(parsed))
         if not match:
             return False
         try:
@@ -397,12 +525,12 @@ class PlaywrightManualWafForm(PlaywrightAuthForm):
         except (json.JSONDecodeError, ValueError):
             return False
 
-        challenge_tag = parsed.select_one('script[src*="awswaf.com"]')
+        challenge_tag = parsed.select_one(self.config.selectors.AWS_WAF_CHALLENGE_SCRIPT_SELECTOR)
         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."
+            "Info: A browser window has opened — solve the Puzzle, then return here when done."
         )
         logger.info(message)
         if self.amazon_session:

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

@@ -36,7 +36,7 @@ class AntiCaptchaWafForm(AwsWafForm):
             not installed, or if Anti-Captcha returns no token.
         """
         try:
-            from anticaptchaofficial.amazonproxyless import amazonProxyless  # type: ignore[import-untyped]
+            from anticaptchaofficial.amazonproxyless import amazonProxyless
         except ImportError as e:
             raise AmazonOrdersError(
                 "AntiCaptchaWafForm requires the 'anticaptchaofficial' package. "

{amazon_orders-4.3.0 → amazon_orders-4.4.0}/amazonorders/contrib/waf/base.py

@@ -21,8 +21,6 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
-_GOKU_PROPS_RE = re.compile(r"window\.gokuProps\s*=\s*(\{.*?\});", re.DOTALL)
-
 
 class AwsWafForm(AuthForm):
     """
@@ -77,7 +75,8 @@ class AwsWafForm(AuthForm):
         """
         self.amazon_session = amazon_session
 
-        match = _GOKU_PROPS_RE.search(str(parsed))
+        goku_re = re.compile(self.config.constants.GOKU_PROPS_REGEX, re.DOTALL)
+        match = goku_re.search(str(parsed))
         if not match:
             return False
         try:
@@ -85,7 +84,7 @@ class AwsWafForm(AuthForm):
         except json.JSONDecodeError:
             return False
 
-        challenge_tag = parsed.select_one('script[src*="awswaf.com"]')
+        challenge_tag = parsed.select_one(self.config.selectors.AWS_WAF_CHALLENGE_SCRIPT_SELECTOR)
         if not challenge_tag:
             return False
         src = challenge_tag.get("src")
@@ -147,3 +146,19 @@ class AwsWafForm(AuthForm):
         :raises NotImplementedError: if a subclass does not override this method.
         """
         raise NotImplementedError
+
+    def _solve_visual_captcha(self,
+                              url: str,
+                              image_data: list,
+                              question: str) -> Optional[list]:
+        """
+        Subclass hook. Solve a visual grid Puzzle (e.g. "Choose all the buckets")
+        and return the indices of the correct grid cells.
+
+        :param url: The URL of the page containing the Puzzle.
+        :param image_data: List of base64-encoded data URLs, one per grid tile.
+        :param question: The object to identify (e.g. ``"the buckets"``).
+        :return: A list of zero-based grid cell indices to select, or ``None`` if
+            this solver does not support Puzzle classification.
+        """
+        return None

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

@@ -1,7 +1,7 @@
 __copyright__ = "Copyright (c) 2024-2025 Alex Laird"
 __license__ = "MIT"
 
-from typing import Any, Dict
+from typing import Any, Dict, List, Optional
 
 from amazonorders.contrib.waf.base import AwsWafForm
 from amazonorders.exception import AmazonOrdersError
@@ -36,7 +36,7 @@ class CapSolverWafForm(AwsWafForm):
             ``cookie`` field.
         """
         try:
-            import capsolver  # type: ignore[import-untyped]
+            import capsolver
         except ImportError as e:
             raise AmazonOrdersError(
                 "CapSolverWafForm requires the 'capsolver' package. "
@@ -65,3 +65,53 @@ class CapSolverWafForm(AwsWafForm):
             raise AmazonOrdersError(
                 f"Unexpected CapSolver response (missing 'cookie'): {solution!r}"
             ) from e
+
+    def _solve_visual_captcha(self,
+                              url: str,
+                              image_data: List[str],
+                              question: str) -> Optional[List[int]]:
+        """
+        Solve a visual grid Puzzle via CapSolver's ``AwsWafClassification`` task
+        type and return the indices of the correct grid cells.
+
+        :param url: The URL of the page containing the Puzzle.
+        :param image_data: List of base64-encoded data URLs, one per grid tile.
+        :param question: The object to identify (e.g. ``"the buckets"``).
+        :return: A list of zero-based grid cell indices to select.
+        :raises AmazonOrdersError: if the ``capsolver`` package is not installed,
+            or if CapSolver's response does not contain the expected fields.
+        """
+        try:
+            import capsolver
+        except ImportError as e:
+            raise AmazonOrdersError(
+                "CapSolverWafForm requires the 'capsolver' package. "
+                "Install it with: `pip install amazon-orders[capsolver]`"
+            ) from e
+
+        capsolver.api_key = self.api_key
+
+        images_b64 = []
+        for img in image_data:
+            images_b64.append(img.split(",", 1)[1] if "," in img else img)
+
+        question_id = f"aws:grid:{question.replace('the ', '').rstrip('s')}"
+
+        try:
+            solution = capsolver.solve({
+                "type": "AwsWafClassification",
+                "websiteURL": url,
+                "images": images_b64,
+                "question": question_id,
+            })
+        except Exception as e:
+            raise AmazonOrdersError(
+                f"CapSolver failed to solve Puzzle: {e}"
+            ) from e
+
+        try:
+            return solution["objects"]
+        except (KeyError, TypeError) as e:
+            raise AmazonOrdersError(
+                f"Unexpected CapSolver Puzzle response (missing 'objects'): {solution!r}"
+            ) from e

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

@@ -39,7 +39,7 @@ class TwoCaptchaWafForm(AwsWafForm):
             expected ``existing_token`` field.
         """
         try:
-            from twocaptcha import TwoCaptcha  # type: ignore[import-untyped]
+            from twocaptcha import TwoCaptcha
         except ImportError as e:
             raise AmazonOrdersError(
                 "TwoCaptchaWafForm requires the '2captcha-python' package. "

{amazon_orders-4.3.0 → amazon_orders-4.4.0}/amazonorders/entity/order.py

@@ -40,7 +40,7 @@ class Order(Parsable):
         #: If the Orders full details were populated from its details page.
         self.full_details: bool = full_details
 
-        #: Where the Order appeared in the history when it was queried. This will inevitably change (ex. when a new
+        #: Where the Order appeared in the history when it was queried. This will inevitably change (e.g. when a new
         #: Order is placed, all indexes will then be off by one), but is still captured as it may be applicable in
         #: various use-cases. Populated when the Order was fetched through
         #: :func:`~amazonorders.orders.AmazonOrders.get_order_history` (use ``start_index`` to correlate), or when

{amazon_orders-4.3.0 → amazon_orders-4.4.0}/amazonorders/orders.py

@@ -77,6 +77,27 @@ class AmazonOrders:
 
         return order
 
+    def get_invoice(self,
+                    order_id: str) -> util.AmazonSessionResponse:
+        """
+        Get the print-friendly invoice page for a given Amazon Order ID, returning the response
+        (including its parsed HTML) so callers can render or print the page.
+
+        :param order_id: The Amazon Order ID to lookup.
+        :return: The invoice page response.
+        """
+        if not self.amazon_session.is_authenticated:
+            raise AmazonOrdersError("Call AmazonSession.login() to authenticate first.")
+
+        invoice_response = self.amazon_session.get(
+            f"{self.config.constants.ORDER_INVOICE_URL}?orderID={order_id}")
+        self.amazon_session.check_response(invoice_response)
+
+        if not invoice_response.response.url.startswith(self.config.constants.ORDER_INVOICE_URL):
+            raise AmazonOrdersNotFoundError(f"Amazon redirected, which likely means Order {order_id} was not found.")
+
+        return invoice_response
+
     def get_order_history(self,
                           year: Optional[int] = None,
                           start_index: Optional[int] = None,

{amazon_orders-4.3.0 → amazon_orders-4.4.0}/amazonorders/selectors.py

@@ -44,6 +44,13 @@ class Selectors:
     # CSS selectors for AuthForms
     ##########################################################################
 
+    ACIC_CHALLENGE_SELECTOR = "#aa-challenge-page-captcha-container"
+    ACIC_VISUAL_CAPTCHA_MODAL_SELECTOR = ".amzn-captcha-modal"
+    ACIC_VISUAL_CAPTCHA_CANVAS_SELECTOR = ".amzn-captcha-modal canvas"
+    ACIC_VISUAL_CAPTCHA_QUESTION_SELECTOR = ".amzn-captcha-modal em"
+    ACIC_VISUAL_CAPTCHA_VERIFY_SELECTOR = "#amzn-btn-verify-internal"
+    AWS_WAF_CHALLENGE_SCRIPT_SELECTOR = 'script[src*="awswaf.com"]'
+
     SIGN_IN_FORM_SELECTOR = "form[name='signIn']"
     CLAIM_FORM_SELECTOR = "form[name='signIn'].auth-validate-form"
     INTENT_FORM_SELECTOR = "form#intent-confirmation-form"

{amazon_orders-4.3.0 → amazon_orders-4.4.0}/amazonorders/transactions.py

@@ -85,28 +85,34 @@ class AmazonTransactions:
     def get_transactions(self,
                          days: int = 365,
                          next_page_data: Optional[Dict[str, Any]] = None,
-                         keep_paging: bool = True) -> List[Transaction]:
+                         keep_paging: bool = True,
+                         order_id: Optional[str] = None) -> List[Transaction]:
         """
-        Get Amazon Transaction history for a given number of days.
+        Get Amazon Transaction history for a given number of days, or for a single Order.
 
-        :param days: The number of days worth of Transactions to get.
+        :param days: The number of days worth of Transactions to get. Ignored when ``order_id`` is given.
         :param next_page_data: If a call to this method previously errored out, passing the exception's
             :attr:`~amazonorders.exception.AmazonOrdersError.meta` will continue paging where it left off.
         :param keep_paging: ``False`` if only one page should be fetched.
+        :param order_id: If given, only Transactions for this Amazon Order ID are returned, scoped
+            server-side via Amazon's ``transactionTag`` filter (the ``days`` window does not apply).
         :return: A list of the requested Transactions.
         """
         if not self.amazon_session.is_authenticated:
             raise AmazonOrdersError("Call AmazonSession.login() to authenticate first.")
 
-        min_date = datetime.date.today() - datetime.timedelta(days=days)
+        url = self.config.constants.TRANSACTION_HISTORY_URL
+        if order_id:
+            url = f"{url}?transactionTag={order_id}"
+        else:
+            min_date = datetime.date.today() - datetime.timedelta(days=days)
 
         transactions: List[Transaction] = []
         first_page = True
         while first_page or keep_paging:
             first_page = False
 
-            page_response = self.amazon_session.post(self.config.constants.TRANSACTION_HISTORY_URL,
-                                                     data=next_page_data)
+            page_response = self.amazon_session.post(url, data=next_page_data)
             self.amazon_session.check_response(page_response, meta=next_page_data)
 
             form_tag = util.select_one(page_response.parsed,
@@ -125,7 +131,7 @@ class AmazonTransactions:
             )
 
             for transaction in loaded_transactions:
-                if transaction.completed_date >= min_date:
+                if order_id or transaction.completed_date >= min_date:
                     transactions.append(transaction)
                 else:
                     next_page_data = None

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

@@ -36,8 +36,8 @@ classifiers = [
 ]
 
 [project.optional-dependencies]
-captcha = [
-    "amazoncaptcha>=0.4",
+browser = [
+    "playwright>=1.47.0",
 ]
 capsolver = [
     "capsolver",
@@ -48,12 +48,12 @@ anticaptcha = [
 2captcha = [
     "2captcha-python",
 ]
-browser = [
-    "playwright>=1.47.0",
-]
 lxml = [
     "lxml",
 ]
+captcha = [
+    "amazoncaptcha>=0.4",
+]
 dev = [
     "pytest",
     "coverage[toml]",
@@ -62,7 +62,6 @@ dev = [
     "pep8-naming",
     "responses",
     "lxml",
-    "amazoncaptcha>=0.4; python_version < '3.13'",
 ]
 integration = [
     "pytest-rerunfailures",
@@ -143,3 +142,15 @@ exclude = "scripts/*,docs/*,venv/*,build/*,dist/*,.egg-info/*,.mypy_cache/*"
 [[tool.mypy.overrides]]
 module = "amazoncaptcha.*"
 ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "capsolver.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "twocaptcha.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "anticaptchaofficial.*"
+ignore_missing_imports = true