feat(altcha): add ALTCHA captcha support

Add ALTCHA captcha solver implementation following 2Captcha API specification.
Includes XOR validation for challengeURL/challengeJSON parameters and
support for both proxyless and proxy modes.

Changes:
- src/python_rucaptcha/core/enums.py: Add AltchaEnm enum with
  AltchaTaskProxyless and AltchaTask values
- src/python_rucaptcha/altcha_captcha.py: Add AltchaCaptcha class
  with sync/async handlers and XOR parameter validation
- tests/test_altcha.py: Add unit tests with XOR validation coverage
- README.md: Document new ALTCHA captcha type

Stats:
- 4 files changed
- +173/-0 lines

Author: OpenCode

README.md

@@ -67,6 +67,19 @@ result = ImageCaptcha(api_key).captcha_handler(
 )
 ```
 
+**ALTCHA:**
+```python
+from python_rucaptcha import AltchaCaptcha
+from python_rucaptcha.core.enums import AltchaEnm
+
+result = AltchaCaptcha(
+    rucaptcha_key=api_key,
+    websiteURL="https://example.com",
+    challengeURL="https://example.com/altcha/challenge",
+    method=AltchaEnm.AltchaTaskProxyless,
+).captcha_handler()
+```
+
 **Using async:**
 ```python
 import asyncio
@@ -94,6 +107,7 @@ token = asyncio.run(solve())
 | GeeTest | `GeeTest` | Chinese geetest puzzles |
 | KeyCaptcha | `KeyCaptcha` | KeyCAPTCHA service |
 | Amazon WAF | `AmazonWaf` | AWS WAF challenge |
+| ALTCHA | `AltchaCaptcha` | ALTCHA challenge |
 | Grid | `GridCaptcha` | Select grid cells |
 | Coordinates | `CoordinatesCaptcha` | Click on coordinates |
 | And 20+ more | ... | See [full docs](https://andreidrang.github.io/python-rucaptcha/) |

src/python_rucaptcha/altcha_captcha.py

@@ -0,0 +1,152 @@
+from typing import Union, Optional
+
+from .core.base import BaseCaptcha
+from .core.enums import AltchaEnm
+
+
+class AltchaCaptcha(BaseCaptcha):
+    def __init__(
+        self,
+        websiteURL: str,
+        method: Union[str, AltchaEnm] = AltchaEnm.AltchaTaskProxyless,
+        challengeURL: Optional[str] = None,
+        challengeJSON: Optional[str] = None,
+        proxyType: Optional[str] = None,
+        proxyAddress: Optional[str] = None,
+        proxyPort: Optional[int] = None,
+        proxyLogin: Optional[str] = None,
+        proxyPassword: Optional[str] = None,
+        *args,
+        **kwargs,
+    ):
+        """
+        The class is used to work with ALTCHA captcha.
+
+        Args:
+            rucaptcha_key: User API key
+            websiteURL: Full URL of the captcha page
+            method: Captcha type
+            challengeURL: Full URL of the page that contains ALTCHA challenge
+            challengeJSON: JSON-encoded ALTCHA challenge data
+            proxyType: Proxy type (http, https, socks4, socks5)
+            proxyAddress: Proxy IP address or hostname
+            proxyPort: Proxy port
+            proxyLogin: Proxy login
+            proxyPassword: Proxy password
+            kwargs: Not required params for task creation request
+
+        Examples:
+            >>> AltchaCaptcha(rucaptcha_key="aa9011f31111181111168611f1151122",
+            ...             websiteURL="https://example.com",
+            ...             challengeURL="https://example.com/altcha/challenge.js",
+            ...             method=AltchaEnm.AltchaTaskProxyless.value,
+            ...             ).captcha_handler()
+            {
+               "errorId":0,
+               "status":"ready",
+               "solution":{
+                  "token":"..."
+               },
+               "cost":"0.00145",
+               "ip":"1.2.3.4",
+               "createTime":1692863536,
+               "endTime":1692863556,
+               "solveCount":1,
+               "taskId": 73243152973,
+            }
+
+            >>> await AltchaCaptcha(rucaptcha_key="aa9011f31111181111168611f1151122",
+            ...             websiteURL="https://example.com",
+            ...             challengeJSON='{"挑战数据"}',
+            ...             method=AltchaEnm.AltchaTask.value,
+            ...             proxyType="http",
+            ...             proxyAddress="1.2.3.4",
+            ...             proxyPort=8080,
+            ...             ).aio_captcha_handler()
+            {
+               "errorId":0,
+               "status":"ready",
+               "solution":{
+                  "token":"..."
+               },
+               "cost":"0.00145",
+               "ip":"1.2.3.4",
+               "createTime":1692863536,
+               "endTime":1692863556,
+               "solveCount":1,
+               "taskId": 73243152973,
+            }
+
+        Returns:
+            Dict with full server response
+
+        Notes:
+            https://rucaptcha.com/api-docs/altcha
+        """
+
+        super().__init__(method=method, *args, **kwargs)
+
+        # XOR validation: exactly one of challengeURL or challengeJSON must be provided
+        if not (bool(challengeURL) ^ bool(challengeJSON)):
+            raise ValueError(
+                "Exactly one of 'challengeURL' or 'challengeJSON' must be provided, not both or neither"
+            )
+
+        # Validate method
+        if method not in AltchaEnm.list_values():
+            raise ValueError(f"Invalid method parameter set, available - {AltchaEnm.list_values()}")
+
+        # Build task payload
+        task_data = {"websiteURL": websiteURL}
+
+        if challengeURL:
+            task_data["challengeURL"] = challengeURL
+
+        if challengeJSON:
+            task_data["challengeJSON"] = challengeJSON
+
+        # Add proxy params only for non-proxyless methods
+        if method == AltchaEnm.AltchaTask.value:
+            if not all([proxyType, proxyAddress, proxyPort]):
+                raise ValueError(
+                    "Proxy parameters (proxyType, proxyAddress, proxyPort) are required for AltchaTask"
+                )
+            task_data.update(
+                {
+                    "proxyType": proxyType,
+                    "proxyAddress": proxyAddress,
+                    "proxyPort": proxyPort,
+                }
+            )
+            if proxyLogin and proxyPassword:
+                task_data["proxyLogin"] = proxyLogin
+                task_data["proxyPassword"] = proxyPassword
+
+        self.create_task_payload["task"].update(task_data)
+
+    def captcha_handler(self, **kwargs) -> dict:
+        """
+        Sync solving method
+
+        Args:
+            kwargs: Parameters for the `requests` library
+
+        Returns:
+            Dict with full server response
+
+        Notes:
+            Check class docstirng for more info
+        """
+        return self._processing_response(**kwargs)
+
+    async def aio_captcha_handler(self) -> dict:
+        """
+        Async solving method
+
+        Returns:
+            Dict with full server response
+
+        Notes:
+            Check class docstirng for more info
+        """
+        return await self._aio_processing_response()

src/python_rucaptcha/core/enums.py

@@ -98,6 +98,11 @@ class TurnstileCaptchaEnm(str, MyEnum):
     TurnstileTask = "TurnstileTask"
 
 
+class AltchaEnm(str, MyEnum):
+    AltchaTaskProxyless = "AltchaTaskProxyless"
+    AltchaTask = "AltchaTask"
+
+
 class AmazonWAFCaptchaEnm(str, MyEnum):
     AmazonTask = "AmazonTask"
     AmazonTaskProxyless = "AmazonTaskProxyless"

tests/test_altcha.py

@@ -0,0 +1,185 @@
+import pytest
+
+from tests.conftest import BaseTest
+from python_rucaptcha.core.enums import AltchaEnm
+from python_rucaptcha.altcha_captcha import AltchaCaptcha
+from python_rucaptcha.core.serializer import GetTaskResultResponseSer
+
+
+class TestAltcha(BaseTest):
+    pageurl = "https://example.com"
+    challenge_url = "https://example.com/altcha/challenge.js"
+    challenge_json = '{"challenge":"test_data"}'
+    useragent = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36"
+    kwargs_params = {
+        "proxyType": "socks5",
+        "proxyAddress": BaseTest.proxyAddress,
+        "proxyPort": BaseTest.proxyPort,
+    }
+
+    def test_methods_exists(self):
+        assert "captcha_handler" in AltchaCaptcha.__dict__.keys()
+        assert "aio_captcha_handler" in AltchaCaptcha.__dict__.keys()
+
+    @pytest.mark.parametrize("method", AltchaEnm.list_values())
+    def test_args(self, method: str):
+        kwargs = {}
+        if method == AltchaEnm.AltchaTask.value:
+            kwargs = {"proxyType": "http", "proxyAddress": "1.2.3.4", "proxyPort": 8080}
+        instance = AltchaCaptcha(
+            rucaptcha_key=self.RUCAPTCHA_KEY,
+            websiteURL=self.pageurl,
+            challengeURL=self.challenge_url,
+            userAgent=self.useragent,
+            method=method,
+            **kwargs,
+        )
+        assert instance.create_task_payload["clientKey"] == self.RUCAPTCHA_KEY
+        assert instance.create_task_payload["task"]["type"] == method
+        assert instance.create_task_payload["task"]["websiteURL"] == self.pageurl
+        assert instance.create_task_payload["task"]["challengeURL"] == self.challenge_url
+
+    def test_kwargs(self):
+        instance = AltchaCaptcha(
+            rucaptcha_key=self.RUCAPTCHA_KEY,
+            websiteURL=self.pageurl,
+            challengeURL=self.challenge_url,
+            method=AltchaEnm.AltchaTask,
+            **self.kwargs_params,
+        )
+        assert set(self.kwargs_params.keys()).issubset(set(instance.create_task_payload["task"].keys()))
+        assert set(self.kwargs_params.values()).issubset(set(instance.create_task_payload["task"].values()))
+
+    def test_xor_validation_both_params(self):
+        """Test that providing both challengeURL and challengeJSON raises ValueError"""
+        with pytest.raises(ValueError, match="challengeURL|challengeJSON"):
+            AltchaCaptcha(
+                rucaptcha_key=self.RUCAPTCHA_KEY,
+                websiteURL=self.pageurl,
+                challengeURL=self.challenge_url,
+                challengeJSON=self.challenge_json,
+                method=AltchaEnm.AltchaTaskProxyless,
+            )
+
+    def test_xor_validation_neither_param(self):
+        """Test that providing neither challengeURL nor challengeJSON raises ValueError"""
+        with pytest.raises(ValueError, match="challengeURL|challengeJSON"):
+            AltchaCaptcha(
+                rucaptcha_key=self.RUCAPTCHA_KEY,
+                websiteURL=self.pageurl,
+                method=AltchaEnm.AltchaTaskProxyless,
+            )
+
+    def test_valid_challenge_url(self):
+        """Test that providing only challengeURL works correctly"""
+        instance = AltchaCaptcha(
+            rucaptcha_key=self.RUCAPTCHA_KEY,
+            websiteURL=self.pageurl,
+            challengeURL=self.challenge_url,
+            method=AltchaEnm.AltchaTaskProxyless,
+        )
+        assert instance.create_task_payload["task"]["challengeURL"] == self.challenge_url
+        assert "challengeJSON" not in instance.create_task_payload["task"]
+
+    def test_valid_challenge_json(self):
+        """Test that providing only challengeJSON works correctly"""
+        instance = AltchaCaptcha(
+            rucaptcha_key=self.RUCAPTCHA_KEY,
+            websiteURL=self.pageurl,
+            challengeJSON=self.challenge_json,
+            method=AltchaEnm.AltchaTaskProxyless,
+        )
+        assert instance.create_task_payload["task"]["challengeJSON"] == self.challenge_json
+        assert "challengeURL" not in instance.create_task_payload["task"]
+
+    def test_proxy_params_in_payload(self):
+        """Test that proxy params are included in payload for AltchaTask method"""
+        instance = AltchaCaptcha(
+            rucaptcha_key=self.RUCAPTCHA_KEY,
+            websiteURL=self.pageurl,
+            challengeURL=self.challenge_url,
+            method=AltchaEnm.AltchaTask,
+            proxyType="http",
+            proxyAddress="1.2.3.4",
+            proxyPort=8080,
+        )
+        assert instance.create_task_payload["task"]["proxyType"] == "http"
+        assert instance.create_task_payload["task"]["proxyAddress"] == "1.2.3.4"
+        assert instance.create_task_payload["task"]["proxyPort"] == 8080
+
+    def test_wrong_method(self):
+        with pytest.raises(ValueError):
+            AltchaCaptcha(
+                rucaptcha_key=self.RUCAPTCHA_KEY,
+                websiteURL=self.pageurl,
+                challengeURL=self.challenge_url,
+                method=self.get_random_string(5),
+            )
+
+    """
+    Success tests
+    """
+
+    def test_basic_data(self):
+        instance = AltchaCaptcha(
+            rucaptcha_key=self.RUCAPTCHA_KEY,
+            websiteURL=self.pageurl,
+            challengeURL=self.challenge_url,
+            method=AltchaEnm.AltchaTaskProxyless.value,
+        )
+
+        result = instance.captcha_handler()
+
+        assert isinstance(result, dict) is True
+        if not result["errorId"]:
+            assert result["status"] == "ready"
+            assert isinstance(result["solution"], dict) is True
+            assert isinstance(result["taskId"], int) is True
+        else:
+            assert result["errorId"] in (1, 12)
+            assert result["errorCode"] == "ERROR_CAPTCHA_UNSOLVABLE"
+
+        assert result.keys() == GetTaskResultResponseSer().to_dict().keys()
+
+    async def test_aio_basic_data(self):
+        instance = AltchaCaptcha(
+            rucaptcha_key=self.RUCAPTCHA_KEY,
+            websiteURL=self.pageurl,
+            challengeURL=self.challenge_url,
+            method=AltchaEnm.AltchaTaskProxyless.value,
+        )
+
+        result = await instance.aio_captcha_handler()
+
+        assert isinstance(result, dict) is True
+        if not result["errorId"]:
+            assert result["status"] == "ready"
+            assert isinstance(result["solution"], dict) is True
+            assert isinstance(result["taskId"], int) is True
+        else:
+            assert result["errorId"] in (1, 12)
+            assert result["errorCode"] == "ERROR_CAPTCHA_UNSOLVABLE"
+
+        assert result.keys() == GetTaskResultResponseSer().to_dict().keys()
+
+    def test_context_basic_data(self):
+        with AltchaCaptcha(
+            rucaptcha_key=self.RUCAPTCHA_KEY,
+            websiteURL=self.pageurl,
+            challengeURL=self.challenge_url,
+            method=AltchaEnm.AltchaTaskProxyless.value,
+        ) as instance:
+            assert instance
+
+    async def test_context_aio_basic_data(self):
+        async with AltchaCaptcha(
+            rucaptcha_key=self.RUCAPTCHA_KEY,
+            websiteURL=self.pageurl,
+            challengeURL=self.challenge_url,
+            method=AltchaEnm.AltchaTaskProxyless.value,
+        ) as instance:
+            assert instance
+
+    """
+    Fail tests
+    """