solvegate 1.0.0__tar.gz

solvegate-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SolveGate
+
+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.

solvegate-1.0.0/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: solvegate
+Version: 1.0.0
+Summary: Official Python SDK for the SolveGate API (Cloudflare Turnstile + WAF solving).
+License: MIT
+Project-URL: Homepage, https://solvegate.io
+Keywords: solvegate,captcha,turnstile,cloudflare,waf
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# solvegate — Python SDK
+
+Official client for the [SolveGate API](https://solvegate.io) — clear Cloudflare
+Turnstile + WAF challenges and get a token back. **Zero dependencies** (stdlib only);
+wraps auth, the error envelope, `429` backoff, and async polling.
+
+```bash
+pip install solvegate
+```
+
+```python
+import os
+from solvegate import SolveGate
+
+sg = SolveGate(os.environ["SOLVEGATE_KEY"])  # sg_live_… or a free sg_test_… sandbox key
+
+# Synchronous — blocks until solved (or raises on timeout):
+res = sg.solve(gate="turnstile", sitekey="0x4AAAAAAAAA_target", url="https://app.example.com")
+print(res.token, res.solve_ms)
+
+# Asynchronous — return immediately, then poll:
+pending = sg.solve(gate="turnstile", sitekey=sitekey, url=url, async_=True)
+solved = sg.wait(pending.id)
+if solved.status == "solved":
+    use(solved.token)
+
+# Retrieve any solve by id:
+s = sg.retrieve("slv_8Kd2aF9")
+```
+
+## API
+
+| Method | Description |
+|---|---|
+| `SolveGate(api_key, base_url=…, timeout=60, max_retries=3)` | construct a client |
+| `sg.solve(gate, sitekey, url, action=None, async_=False, proxy=None, idempotency_key=None)` | → `Solve` |
+| `sg.retrieve(id)` | → `Solve` (never billed) |
+| `sg.wait(id, interval=1.0, timeout=60.0)` | poll an async solve until it leaves `pending` |
+
+`Solve` has `.id .status .gate .token .solve_ms .expires_at .billed`. Errors raise
+`SolveGateError` with `.code` / `.status` / `.billed` (e.g. `balance_empty`,
+`rate_limited`, `solve_timeout`). Note `async_` (trailing underscore) maps to the
+API's `async` field. You're only billed for a successful solve.

solvegate-1.0.0/README.md

@@ -0,0 +1,43 @@
+# solvegate — Python SDK
+
+Official client for the [SolveGate API](https://solvegate.io) — clear Cloudflare
+Turnstile + WAF challenges and get a token back. **Zero dependencies** (stdlib only);
+wraps auth, the error envelope, `429` backoff, and async polling.
+
+```bash
+pip install solvegate
+```
+
+```python
+import os
+from solvegate import SolveGate
+
+sg = SolveGate(os.environ["SOLVEGATE_KEY"])  # sg_live_… or a free sg_test_… sandbox key
+
+# Synchronous — blocks until solved (or raises on timeout):
+res = sg.solve(gate="turnstile", sitekey="0x4AAAAAAAAA_target", url="https://app.example.com")
+print(res.token, res.solve_ms)
+
+# Asynchronous — return immediately, then poll:
+pending = sg.solve(gate="turnstile", sitekey=sitekey, url=url, async_=True)
+solved = sg.wait(pending.id)
+if solved.status == "solved":
+    use(solved.token)
+
+# Retrieve any solve by id:
+s = sg.retrieve("slv_8Kd2aF9")
+```
+
+## API
+
+| Method | Description |
+|---|---|
+| `SolveGate(api_key, base_url=…, timeout=60, max_retries=3)` | construct a client |
+| `sg.solve(gate, sitekey, url, action=None, async_=False, proxy=None, idempotency_key=None)` | → `Solve` |
+| `sg.retrieve(id)` | → `Solve` (never billed) |
+| `sg.wait(id, interval=1.0, timeout=60.0)` | poll an async solve until it leaves `pending` |
+
+`Solve` has `.id .status .gate .token .solve_ms .expires_at .billed`. Errors raise
+`SolveGateError` with `.code` / `.status` / `.billed` (e.g. `balance_empty`,
+`rate_limited`, `solve_timeout`). Note `async_` (trailing underscore) maps to the
+API's `async` field. You're only billed for a successful solve.

solvegate-1.0.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "solvegate"
+version = "1.0.0"
+description = "Official Python SDK for the SolveGate API (Cloudflare Turnstile + WAF solving)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["solvegate", "captcha", "turnstile", "cloudflare", "waf"]
+dependencies = []  # zero runtime dependencies — stdlib only
+
+[project.urls]
+Homepage = "https://solvegate.io"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["solvegate*"]

solvegate-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

solvegate-1.0.0/solvegate/__init__.py

@@ -0,0 +1,148 @@
+"""Official SolveGate Python SDK.
+
+A tiny, zero-dependency client (stdlib only) over the public HTTPS+JSON API.
+Wraps auth, the documented error envelope, ``429`` backoff, and async polling.
+
+    from solvegate import SolveGate
+
+    sg = SolveGate(os.environ["SOLVEGATE_KEY"])  # sg_live_… or a free sg_test_… key
+    res = sg.solve(gate="turnstile", sitekey="0x4AAAAAAAAA_target", url="https://app.example.com")
+    print(res.token)
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Optional
+
+__all__ = ["SolveGate", "Solve", "SolveGateError"]
+__version__ = "1.0.0"
+
+
+@dataclass
+class Solve:
+    """A solve attempt. ``token`` is populated once ``status == 'solved'``."""
+
+    id: str
+    status: str  # "pending" | "solved" | "failed"
+    gate: str
+    token: Optional[str]
+    solve_ms: Optional[int]
+    expires_at: Optional[int]
+    billed: bool
+
+    @classmethod
+    def _from(cls, d: dict) -> "Solve":
+        return cls(
+            id=d.get("id"),
+            status=d.get("status"),
+            gate=d.get("gate"),
+            token=d.get("token"),
+            solve_ms=d.get("solve_ms"),
+            expires_at=d.get("expires_at"),
+            billed=bool(d.get("billed", False)),
+        )
+
+
+class SolveGateError(Exception):
+    """Raised on any non-2xx response, carrying the documented error envelope."""
+
+    def __init__(self, status: int, code: str, message: str, billed: bool = False):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.billed = billed
+
+
+class SolveGate:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.solvegate.io",
+        timeout: float = 60.0,
+        max_retries: int = 3,
+    ):
+        if not api_key:
+            raise ValueError("SolveGate: an API key is required.")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+    def solve(
+        self,
+        gate: str,
+        sitekey: str,
+        url: str,
+        action: Optional[str] = None,
+        async_: bool = False,
+        proxy: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Solve:
+        """Solve a challenge. Blocks until solved unless ``async_=True``."""
+        body = {"gate": gate, "sitekey": sitekey, "url": url, "async": async_}
+        if action is not None:
+            body["action"] = action
+        if proxy is not None:
+            body["proxy"] = proxy
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else {}
+        return self._request("POST", "/v1/solve", body=body, headers=headers)
+
+    def retrieve(self, id: str) -> Solve:
+        """Retrieve a solve by id. Never billed."""
+        return self._request("GET", "/v1/solve/" + urllib.parse.quote(id, safe=""))
+
+    def wait(self, id: str, interval: float = 1.0, timeout: float = 60.0) -> Solve:
+        """Poll ``retrieve(id)`` until the solve leaves ``pending`` (for async solves)."""
+        deadline = time.monotonic() + timeout
+        while True:
+            s = self.retrieve(id)
+            if s.status != "pending" or time.monotonic() >= deadline:
+                return s
+            time.sleep(interval)
+
+    # -- internals ----------------------------------------------------------
+    def _request(self, method: str, path: str, body: Optional[dict] = None, headers: Optional[dict] = None) -> Solve:
+        data = json.dumps(body).encode() if body is not None else None
+        attempt = 0
+        while True:
+            req = urllib.request.Request(self.base_url + path, data=data, method=method)
+            req.add_header("Authorization", "Bearer " + self.api_key)
+            if data is not None:
+                req.add_header("Content-Type", "application/json")
+            for k, v in (headers or {}).items():
+                req.add_header(k, v)
+            try:
+                with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                    return Solve._from(json.loads(resp.read().decode()))
+            except urllib.error.HTTPError as e:
+                payload = self._read_json(e)
+                if e.code == 429 and attempt < self.max_retries:
+                    retry_after = e.headers.get("Retry-After")
+                    time.sleep(float(retry_after) if retry_after and retry_after.isdigit() else self._backoff(attempt))
+                    attempt += 1
+                    continue
+                err = (payload or {}).get("error", {})
+                raise SolveGateError(e.code, err.get("code", "error"), err.get("message", str(e)), err.get("billed", False))
+            except urllib.error.URLError as e:
+                if attempt < self.max_retries:
+                    time.sleep(self._backoff(attempt))
+                    attempt += 1
+                    continue
+                raise SolveGateError(0, "network_error", str(e.reason))
+
+    @staticmethod
+    def _read_json(e: "urllib.error.HTTPError") -> Optional[dict]:
+        try:
+            return json.loads(e.read().decode())
+        except Exception:
+            return None
+
+    @staticmethod
+    def _backoff(attempt: int) -> float:
+        return min(8.0, 0.5 * (2 ** attempt))  # 0.5s, 1s, 2s, 4s … capped 8s

solvegate-1.0.0/solvegate.egg-info/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: solvegate
+Version: 1.0.0
+Summary: Official Python SDK for the SolveGate API (Cloudflare Turnstile + WAF solving).
+License: MIT
+Project-URL: Homepage, https://solvegate.io
+Keywords: solvegate,captcha,turnstile,cloudflare,waf
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# solvegate — Python SDK
+
+Official client for the [SolveGate API](https://solvegate.io) — clear Cloudflare
+Turnstile + WAF challenges and get a token back. **Zero dependencies** (stdlib only);
+wraps auth, the error envelope, `429` backoff, and async polling.
+
+```bash
+pip install solvegate
+```
+
+```python
+import os
+from solvegate import SolveGate
+
+sg = SolveGate(os.environ["SOLVEGATE_KEY"])  # sg_live_… or a free sg_test_… sandbox key
+
+# Synchronous — blocks until solved (or raises on timeout):
+res = sg.solve(gate="turnstile", sitekey="0x4AAAAAAAAA_target", url="https://app.example.com")
+print(res.token, res.solve_ms)
+
+# Asynchronous — return immediately, then poll:
+pending = sg.solve(gate="turnstile", sitekey=sitekey, url=url, async_=True)
+solved = sg.wait(pending.id)
+if solved.status == "solved":
+    use(solved.token)
+
+# Retrieve any solve by id:
+s = sg.retrieve("slv_8Kd2aF9")
+```
+
+## API
+
+| Method | Description |
+|---|---|
+| `SolveGate(api_key, base_url=…, timeout=60, max_retries=3)` | construct a client |
+| `sg.solve(gate, sitekey, url, action=None, async_=False, proxy=None, idempotency_key=None)` | → `Solve` |
+| `sg.retrieve(id)` | → `Solve` (never billed) |
+| `sg.wait(id, interval=1.0, timeout=60.0)` | poll an async solve until it leaves `pending` |
+
+`Solve` has `.id .status .gate .token .solve_ms .expires_at .billed`. Errors raise
+`SolveGateError` with `.code` / `.status` / `.billed` (e.g. `balance_empty`,
+`rate_limited`, `solve_timeout`). Note `async_` (trailing underscore) maps to the
+API's `async` field. You're only billed for a successful solve.

solvegate-1.0.0/solvegate.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+LICENSE
+README.md
+pyproject.toml
+solvegate/__init__.py
+solvegate.egg-info/PKG-INFO
+solvegate.egg-info/SOURCES.txt
+solvegate.egg-info/dependency_links.txt
+solvegate.egg-info/top_level.txt

solvegate-1.0.0/solvegate.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

solvegate-1.0.0/solvegate.egg-info/top_level.txt

@@ -0,0 +1 @@
+solvegate