wok-api 1.2.0__tar.gz

wok_api-1.2.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: wok-api
+Version: 1.2.0
+Summary: Dependency-free synchronous client for the WOK Steam API
+Author: WOK API
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://woksteamapi.com
+Project-URL: Documentation, https://woksteamapi.com/docs
+Keywords: wok-api,steam,steam-api,steam-inventory-api,steamwebapi,cs2,inventory,faceit
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# WOK API client for Python
+
+Dependency-free synchronous client for the
+[WOK Steam API](https://woksteamapi.com/docs). It is distributed as the single
+`wok_api` module and uses only the Python standard library at runtime.
+
+## Requirements
+
+- Python 3.10 or newer
+- A WOK API key
+
+For development, the Free Developer plan provides 1,000 requests per calendar
+month, a 100-request daily guard and 30 requests per minute. Create a key at
+<https://woksteamapi.com/pricing>.
+
+Keep the API key in a server-side environment variable or secret store. Do not
+commit it to source control or send it to browser clients.
+
+## Install
+
+```sh
+python -m pip install wok-api
+```
+
+## Usage
+
+```python
+import os
+
+from wok_api import WokApi, WokApiError
+
+client = WokApi(os.environ["WOK_API_KEY"])
+steam_id = os.environ["STEAM_ID"]
+
+try:
+    inventory = client.inventory(
+        steam_id,
+        game="cs2",
+        top=25,
+    )
+    print(inventory)
+except WokApiError as error:
+    print(error.status, error, error.retry_after)
+```
+
+The client also exposes methods for profiles, friends, catalog prices, price
+history, CS2 inspection, crawl jobs, FACEIT data, and service health. See the
+[API reference](https://woksteamapi.com/docs) for request and response shapes.
+
+Render a modern CS2 inspect certificate as PNG bytes:
+
+```python
+png = client.cs2_screenshot(
+    certificate=os.environ["CS2_INSPECT_CERTIFICATE"],
+    theme="wok",
+    item_name="AK-47 | Redline (Field-Tested)",
+)
+with open("wok-cs2-inspect.png", "wb") as output:
+    output.write(png)
+```
+
+`WokApiError` provides `status`, `payload`, `retry_after`, `rate_limit`,
+`rate_remaining`, and `rate_reset`. Wait at least `retry_after` seconds after
+HTTP 429. Network failures use status `0`.
+
+The default timeout is 35 seconds so the 25-second synchronous inventory batch
+can finish. Do not configure `/v1/inventories` with a timeout below 30 seconds.
+
+For testing or a compatible deployment, pass `base_url`, `timeout`, or a custom
+`transport` to the constructor.
+
+## Build the package
+
+```sh
+python -m build
+```
+
+The command creates both an sdist and a wheel under `dist/`.

wok_api-1.2.0/README.md

@@ -0,0 +1,78 @@
+# WOK API client for Python
+
+Dependency-free synchronous client for the
+[WOK Steam API](https://woksteamapi.com/docs). It is distributed as the single
+`wok_api` module and uses only the Python standard library at runtime.
+
+## Requirements
+
+- Python 3.10 or newer
+- A WOK API key
+
+For development, the Free Developer plan provides 1,000 requests per calendar
+month, a 100-request daily guard and 30 requests per minute. Create a key at
+<https://woksteamapi.com/pricing>.
+
+Keep the API key in a server-side environment variable or secret store. Do not
+commit it to source control or send it to browser clients.
+
+## Install
+
+```sh
+python -m pip install wok-api
+```
+
+## Usage
+
+```python
+import os
+
+from wok_api import WokApi, WokApiError
+
+client = WokApi(os.environ["WOK_API_KEY"])
+steam_id = os.environ["STEAM_ID"]
+
+try:
+    inventory = client.inventory(
+        steam_id,
+        game="cs2",
+        top=25,
+    )
+    print(inventory)
+except WokApiError as error:
+    print(error.status, error, error.retry_after)
+```
+
+The client also exposes methods for profiles, friends, catalog prices, price
+history, CS2 inspection, crawl jobs, FACEIT data, and service health. See the
+[API reference](https://woksteamapi.com/docs) for request and response shapes.
+
+Render a modern CS2 inspect certificate as PNG bytes:
+
+```python
+png = client.cs2_screenshot(
+    certificate=os.environ["CS2_INSPECT_CERTIFICATE"],
+    theme="wok",
+    item_name="AK-47 | Redline (Field-Tested)",
+)
+with open("wok-cs2-inspect.png", "wb") as output:
+    output.write(png)
+```
+
+`WokApiError` provides `status`, `payload`, `retry_after`, `rate_limit`,
+`rate_remaining`, and `rate_reset`. Wait at least `retry_after` seconds after
+HTTP 429. Network failures use status `0`.
+
+The default timeout is 35 seconds so the 25-second synchronous inventory batch
+can finish. Do not configure `/v1/inventories` with a timeout below 30 seconds.
+
+For testing or a compatible deployment, pass `base_url`, `timeout`, or a custom
+`transport` to the constructor.
+
+## Build the package
+
+```sh
+python -m build
+```
+
+The command creates both an sdist and a wheel under `dist/`.

wok_api-1.2.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wok-api"
+version = "1.2.0"
+description = "Dependency-free synchronous client for the WOK Steam API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "LicenseRef-Proprietary"
+authors = [
+  { name = "WOK API" },
+]
+keywords = [
+  "wok-api",
+  "steam",
+  "steam-api",
+  "steam-inventory-api",
+  "steamwebapi",
+  "cs2",
+  "inventory",
+  "faceit",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://woksteamapi.com"
+Documentation = "https://woksteamapi.com/docs"
+
+[tool.setuptools]
+py-modules = ["wok_api"]
+include-package-data = false

wok_api-1.2.0/setup.cfg

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

wok_api-1.2.0/wok_api.egg-info/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: wok-api
+Version: 1.2.0
+Summary: Dependency-free synchronous client for the WOK Steam API
+Author: WOK API
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://woksteamapi.com
+Project-URL: Documentation, https://woksteamapi.com/docs
+Keywords: wok-api,steam,steam-api,steam-inventory-api,steamwebapi,cs2,inventory,faceit
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# WOK API client for Python
+
+Dependency-free synchronous client for the
+[WOK Steam API](https://woksteamapi.com/docs). It is distributed as the single
+`wok_api` module and uses only the Python standard library at runtime.
+
+## Requirements
+
+- Python 3.10 or newer
+- A WOK API key
+
+For development, the Free Developer plan provides 1,000 requests per calendar
+month, a 100-request daily guard and 30 requests per minute. Create a key at
+<https://woksteamapi.com/pricing>.
+
+Keep the API key in a server-side environment variable or secret store. Do not
+commit it to source control or send it to browser clients.
+
+## Install
+
+```sh
+python -m pip install wok-api
+```
+
+## Usage
+
+```python
+import os
+
+from wok_api import WokApi, WokApiError
+
+client = WokApi(os.environ["WOK_API_KEY"])
+steam_id = os.environ["STEAM_ID"]
+
+try:
+    inventory = client.inventory(
+        steam_id,
+        game="cs2",
+        top=25,
+    )
+    print(inventory)
+except WokApiError as error:
+    print(error.status, error, error.retry_after)
+```
+
+The client also exposes methods for profiles, friends, catalog prices, price
+history, CS2 inspection, crawl jobs, FACEIT data, and service health. See the
+[API reference](https://woksteamapi.com/docs) for request and response shapes.
+
+Render a modern CS2 inspect certificate as PNG bytes:
+
+```python
+png = client.cs2_screenshot(
+    certificate=os.environ["CS2_INSPECT_CERTIFICATE"],
+    theme="wok",
+    item_name="AK-47 | Redline (Field-Tested)",
+)
+with open("wok-cs2-inspect.png", "wb") as output:
+    output.write(png)
+```
+
+`WokApiError` provides `status`, `payload`, `retry_after`, `rate_limit`,
+`rate_remaining`, and `rate_reset`. Wait at least `retry_after` seconds after
+HTTP 429. Network failures use status `0`.
+
+The default timeout is 35 seconds so the 25-second synchronous inventory batch
+can finish. Do not configure `/v1/inventories` with a timeout below 30 seconds.
+
+For testing or a compatible deployment, pass `base_url`, `timeout`, or a custom
+`transport` to the constructor.
+
+## Build the package
+
+```sh
+python -m build
+```
+
+The command creates both an sdist and a wheel under `dist/`.

wok_api-1.2.0/wok_api.egg-info/SOURCES.txt

@@ -0,0 +1,7 @@
+README.md
+pyproject.toml
+wok_api.py
+wok_api.egg-info/PKG-INFO
+wok_api.egg-info/SOURCES.txt
+wok_api.egg-info/dependency_links.txt
+wok_api.egg-info/top_level.txt

wok_api-1.2.0/wok_api.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

wok_api-1.2.0/wok_api.egg-info/top_level.txt

@@ -0,0 +1 @@
+wok_api

wok_api-1.2.0/wok_api.py

@@ -0,0 +1,325 @@
+"""Небольшой синхронный клиент WOK без сторонних зависимостей."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Callable, Iterable
+from urllib.error import HTTPError, URLError
+from urllib.parse import quote, urlencode, urlparse
+from urllib.request import Request, urlopen
+
+
+class WokApiError(RuntimeError):
+    """Ошибка API с сохранёнными кодом ответа и безопасным JSON-телом."""
+
+    def __init__(self, status: int, message: str, *,
+                 payload: Any = None, retry_after: str | None = None,
+                 rate_limit: str | None = None,
+                 rate_remaining: str | None = None,
+                 rate_reset: str | None = None):
+        super().__init__(message)
+        self.status = status
+        self.payload = payload
+        self.retry_after = retry_after
+        self.rate_limit = rate_limit
+        self.rate_remaining = rate_remaining
+        self.rate_reset = rate_reset
+
+
+Transport = Callable[[Request, float], Any]
+
+
+class WokApi:
+    """Клиент публичных маршрутов WOK Steam API."""
+
+    def __init__(self, api_key: str, *,
+                 base_url: str = "https://woksteamapi.com",
+                 timeout: float = 35.0,
+                 transport: Transport | None = None):
+        parsed = urlparse(base_url)
+        if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+            raise ValueError("base_url должен быть абсолютным HTTP(S) URL")
+        if not isinstance(api_key, str) or not api_key.strip():
+            raise ValueError("api_key не должен быть пустым")
+        if timeout <= 0:
+            raise ValueError("timeout должен быть больше нуля")
+        self.base_url = base_url.rstrip("/")
+        self.timeout = float(timeout)
+        self._api_key = api_key.strip()
+        self._transport = transport or self._open
+
+    @staticmethod
+    def _open(request: Request, timeout: float):
+        return urlopen(request, timeout=timeout)
+
+    @staticmethod
+    def _decode(raw: bytes) -> Any:
+        if not raw:
+            return None
+        try:
+            return json.loads(raw.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError):
+            return {"error": "invalid_json_response"}
+
+    @staticmethod
+    def _error_message(payload: Any) -> str:
+        """Извлечь сообщение и из простого, и из структурного error."""
+        if not isinstance(payload, dict):
+            return "API request failed"
+        message = payload.get("message")
+        if isinstance(message, str) and message:
+            return message
+        error = payload.get("error")
+        if isinstance(error, str) and error:
+            return error
+        if isinstance(error, dict):
+            for field in ("message", "code"):
+                value = error.get(field)
+                if isinstance(value, str) and value:
+                    return value
+        return "API request failed"
+
+    def _request(self, method: str, path: str, *,
+                 query: dict[str, Any] | None = None,
+                 body: dict[str, Any] | None = None,
+                 authenticated: bool = True) -> Any:
+        if not path.startswith("/"):
+            raise ValueError("path должен начинаться с /")
+        clean_query = {
+            key: value for key, value in (query or {}).items()
+            if value is not None and value != ""
+        }
+        suffix = f"?{urlencode(clean_query, doseq=True)}" if clean_query else ""
+        raw_body = (json.dumps(body, separators=(",", ":")).encode("utf-8")
+                    if body is not None else None)
+        headers = {
+            "Accept": "application/json",
+            "User-Agent": "wok-api-python/1.2.0",
+        }
+        if authenticated:
+            headers["Authorization"] = f"Bearer {self._api_key}"
+        if raw_body is not None:
+            headers["Content-Type"] = "application/json"
+        request = Request(
+            f"{self.base_url}{path}{suffix}", data=raw_body,
+            headers=headers, method=method,
+        )
+        try:
+            with self._transport(request, self.timeout) as response:
+                return self._decode(response.read())
+        except HTTPError as exc:
+            payload = self._decode(exc.read())
+            raise WokApiError(
+                int(exc.code), self._error_message(payload), payload=payload,
+                retry_after=exc.headers.get("Retry-After"),
+                rate_limit=exc.headers.get("X-RateLimit-Limit"),
+                rate_remaining=exc.headers.get("X-RateLimit-Remaining"),
+                rate_reset=exc.headers.get("X-RateLimit-Reset"),
+            ) from exc
+        except URLError as exc:
+            raise WokApiError(0, "Network request failed") from exc
+
+    def _request_bytes(self, method: str, path: str, *,
+                       body: dict[str, Any]) -> bytes:
+        """Request a bounded binary API response while preserving JSON errors."""
+        raw_body = json.dumps(body, separators=(",", ":")).encode("utf-8")
+        request = Request(
+            f"{self.base_url}{path}", data=raw_body,
+            headers={
+                "Accept": "image/png",
+                "Authorization": f"Bearer {self._api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": "wok-api-python/1.2.0",
+            },
+            method=method,
+        )
+        try:
+            with self._transport(request, self.timeout) as response:
+                return response.read()
+        except HTTPError as exc:
+            payload = self._decode(exc.read())
+            raise WokApiError(
+                int(exc.code), self._error_message(payload), payload=payload,
+                retry_after=exc.headers.get("Retry-After"),
+                rate_limit=exc.headers.get("X-RateLimit-Limit"),
+                rate_remaining=exc.headers.get("X-RateLimit-Remaining"),
+                rate_reset=exc.headers.get("X-RateLimit-Reset"),
+            ) from exc
+        except URLError as exc:
+            raise WokApiError(0, "Network request failed") from exc
+
+    @staticmethod
+    def _values(values: Iterable[str], name: str) -> list[str]:
+        if isinstance(values, (str, bytes)):
+            raise ValueError(f"{name} должен быть списком")
+        result = [str(value) for value in values]
+        if not result or any(not value for value in result):
+            raise ValueError(f"{name} не должен быть пустым")
+        return result
+
+    def inventory(self, steam_id: str, *, game: str = "cs2",
+                  no_cache: bool = False, top: int = 10,
+                  include_inspect: bool = False,
+                  refresh_prices: bool = False,
+                  price_source: str | None = None,
+                  strict: bool = False) -> dict[str, Any]:
+        return self._request("GET", "/v1/inventory", query={
+            "steam_id": steam_id, "game": game,
+            "no_cache": int(no_cache), "top": top,
+            "include_inspect": int(include_inspect),
+            "refresh_prices": 1 if refresh_prices else None,
+            "price_source": price_source,
+            "strict": int(strict),
+        })
+
+    def refresh_inventory_prices(self, steam_id: str, *, game: str = "cs2",
+                                 top: int = 10,
+                                 include_inspect: bool = False,
+                                 price_source: str | None = None,
+                                 strict: bool = False) -> dict[str, Any]:
+        """Refresh prices from the local cache without fetching Steam inventory."""
+        body = {
+            "steam_id": steam_id,
+            "game": game,
+            "top": int(top),
+            "include_inspect": bool(include_inspect),
+            "strict": bool(strict),
+        }
+        if price_source is not None:
+            body["price_source"] = price_source
+        return self._request("POST", "/v1/inventory/refresh-prices", body=body)
+
+    def inventories(self, steamids: Iterable[str], *,
+                    games: Iterable[str] = ("cs2",),
+                    no_cache: bool = False, top: int = 10,
+                    include_inspect: bool = False) -> dict[str, Any]:
+        return self._request("POST", "/v1/inventories", body={
+            "steamids": self._values(steamids, "steamids"),
+            "games": self._values(games, "games"),
+            "no_cache": bool(no_cache), "top": int(top),
+            "include_inspect": bool(include_inspect),
+        })
+
+    def compatibility_inventory(self, steam_id: str, *, game: str = "cs2",
+                                no_cache: bool = False,
+                                grouped: bool = True,
+                                refresh_prices: bool = False,
+                                price_source: str | None = None,
+                                strict: bool = False) -> list[dict[str, Any]]:
+        return self._request("GET", "/steam/api/inventory", query={
+            "steam_id": steam_id, "game": game, "currency": "USD",
+            "no_cache": int(no_cache), "group": int(grouped),
+            "refresh_prices": 1 if refresh_prices else None,
+            "price_source": price_source,
+            "strict": int(strict),
+        })
+
+    def compatibility_profile(self, steam_id: str) -> dict[str, Any]:
+        return self._request("GET", "/steam/api/profile", query={
+            "steam_id": steam_id,
+        })
+
+    def profile(self, steam_id: str) -> dict[str, Any]:
+        return self._request("GET", "/v1/profile", query={"steam_id": steam_id})
+
+    def profiles(self, steamids: Iterable[str]) -> dict[str, dict[str, Any]]:
+        return self._request("POST", "/v1/profiles", body={
+            "steamids": self._values(steamids, "steamids"),
+        })
+
+    def player_security(self, steam_id: str) -> dict[str, Any]:
+        return self._request("GET", "/v1/player-security", query={
+            "steam_id": steam_id,
+        })
+
+    def friends(self, steam_id: str, *, limit: int = 100,
+                cursor: str | None = None) -> dict[str, Any]:
+        return self._request("GET", "/v1/friends", query={
+            "steam_id": steam_id, "limit": limit, "cursor": cursor,
+        })
+
+    def price(self, game: str, name: str) -> dict[str, Any]:
+        return self._request("GET", "/v1/price", query={
+            "game": game, "name": name,
+        })
+
+    def prices(self, game: str, names: Iterable[str]) -> dict[str, Any]:
+        return self._request("POST", "/v1/prices", body={
+            "game": game, "names": self._values(names, "names"),
+        })
+
+    def items(self, *, game: str = "cs2", query: str | None = None,
+              source: str | None = None, limit: int = 50,
+              cursor: str | None = None) -> dict[str, Any]:
+        return self._request("GET", "/v1/items", query={
+            "game": game, "q": query, "source": source,
+            "limit": limit, "cursor": cursor,
+        })
+
+    def price_history(self, game: str, name: str, *, days: int = 30,
+                      source: str | None = None) -> dict[str, Any]:
+        return self._request("GET", "/v1/price-history", query={
+            "game": game, "name": name, "days": days, "source": source,
+        })
+
+    def inspect_cs2(self, inspect_link: str) -> dict[str, Any]:
+        """float_value читать по float, paint_seed и paint_index по их флагам."""
+        return self._request("POST", "/v1/cs2/inspect", body={
+            "inspect_link": inspect_link,
+        })
+
+    def cs2_screenshot(self, inspect_link: str | None = None, *,
+                       certificate: str | None = None,
+                       theme: str = "wok",
+                       item_name: str | None = None,
+                       download: bool = False) -> bytes:
+        """Render the modern inspect certificate locally on WOK as PNG."""
+        if bool(inspect_link) == bool(certificate):
+            raise ValueError(
+                "передайте ровно одно поле: inspect_link или certificate")
+        body: dict[str, Any] = {
+            "theme": theme,
+            "download": bool(download),
+        }
+        if inspect_link:
+            body["inspect_link"] = inspect_link
+        if certificate:
+            body["certificate"] = certificate
+        if item_name:
+            body["item_name"] = item_name
+        return self._request_bytes("POST", "/v1/cs2/screenshot", body=body)
+
+    def create_crawl(self, steamids: Iterable[str], *,
+                     games: Iterable[str] = ("cs2",)) -> dict[str, Any]:
+        return self._request("POST", "/v1/crawl", body={
+            "steamids": self._values(steamids, "steamids"),
+            "games": self._values(games, "games"),
+        })
+
+    def crawl_status(self, batch_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/v1/crawl/{quote(batch_id, safe='')}")
+
+    def faceit_player(self, steam_id: str, *, game: str = "cs2") -> dict[str, Any]:
+        return self._request("GET", "/faceit/data/v4/players", query={
+            "game": game, "game_player_id": steam_id,
+        })
+
+    def faceit_stats(self, player_id: str, *, game: str = "cs2") -> dict[str, Any]:
+        player = quote(player_id, safe="")
+        game_name = quote(game, safe="")
+        return self._request(
+            "GET", f"/faceit/data/v4/players/{player}/stats/{game_name}")
+
+    def faceit_history(self, player_id: str, *, game: str = "cs2",
+                       limit: int = 5) -> dict[str, Any]:
+        player = quote(player_id, safe="")
+        return self._request(
+            "GET", f"/faceit/data/v4/players/{player}/history",
+            query={"game": game, "limit": limit},
+        )
+
+    def health(self) -> dict[str, Any]:
+        return self._request("GET", "/healthz", authenticated=False)
+
+
+__all__ = ["WokApi", "WokApiError"]