bypass-vuotlink-sdk 0.1.0__tar.gz

bypass_vuotlink_sdk-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.env
+.pytest_cache/
+.ruff_cache/
+.venv/
+.browser-profiles/
+__pycache__/
+*.py[cod]

bypass_vuotlink_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: bypass-vuotlink-sdk
+Version: 0.1.0
+Summary: Python SDK for the bypass-vuotlink API
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.24

bypass_vuotlink_sdk-0.1.0/bypass_vuotlink_sdk/__init__.py

@@ -0,0 +1,15 @@
+from .client import AsyncBypassVuotLink, BypassVuotLink
+from .config import ClientConfig
+from .exceptions import ApiError, BrowserExecutionError, BypassVuotlinkError, UnsafeUrlError
+from .models import ResolveResult
+
+__all__ = [
+    "BypassVuotLink",
+    "AsyncBypassVuotLink",
+    "ClientConfig",
+    "ResolveResult",
+    "BypassVuotlinkError",
+    "UnsafeUrlError",
+    "BrowserExecutionError",
+    "ApiError",
+]

bypass_vuotlink_sdk-0.1.0/bypass_vuotlink_sdk/client.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+from types import TracebackType
+
+import httpx
+
+from .config import ClientConfig
+from .exceptions import ApiError, BrowserExecutionError, UnsafeUrlError
+from .models import ResolveResult
+
+_ENDPOINT = "/api/v1/browser"
+
+
+def _parse_response(response: httpx.Response) -> ResolveResult:
+    if response.status_code == 200:
+        return ResolveResult(**response.json())
+
+    try:
+        detail: str = response.json().get("detail", response.text)
+    except Exception:
+        detail = response.text
+
+    if response.status_code == 400:
+        raise UnsafeUrlError(detail)
+    if response.status_code == 502:
+        raise BrowserExecutionError(detail)
+    raise ApiError(response.status_code, detail)
+
+
+class BypassVuotLink:
+    """Sync client for the bypass-vuotlink API.
+
+    Usage::
+
+        client = BypassVuotLink(base_url="http://localhost:8000")
+        result = client.resolve("https://vuotnhanh.com/...")
+        print(result.final_url)
+        client.close()
+
+        # or as a context manager:
+        with BypassVuotLink(base_url="http://localhost:8000") as client:
+            result = client.resolve("https://vuotnhanh.com/...")
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        timeout: float = ClientConfig.default_timeout,
+        api_key: str | None = None,
+        extra_headers: dict[str, str] | None = None,
+    ) -> None:
+        config = ClientConfig(
+            base_url=base_url,
+            timeout=timeout,
+            api_key=api_key,
+            extra_headers=extra_headers or {},
+        )
+        self._client = httpx.Client(
+            base_url=config.base_url,
+            timeout=config.timeout,
+            headers=config.build_headers(),
+        )
+
+    @classmethod
+    def from_config(cls, config: ClientConfig) -> BypassVuotLink:
+        instance = cls.__new__(cls)
+        instance._client = httpx.Client(
+            base_url=config.base_url,
+            timeout=config.timeout,
+            headers=config.build_headers(),
+        )
+        return instance
+
+    @classmethod
+    def from_env(cls) -> BypassVuotLink:
+        return cls.from_config(ClientConfig.from_env())
+
+    def resolve(self, url: str) -> ResolveResult:
+        response = self._client.post(_ENDPOINT, json={"url": url})
+        return _parse_response(response)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> BypassVuotLink:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+class AsyncBypassVuotLink:
+    """Async client for the bypass-vuotlink API.
+
+    Usage::
+
+        async with AsyncBypassVuotLink(base_url="http://localhost:8000") as client:
+            result = await client.resolve("https://vuotnhanh.com/...")
+            print(result.final_url)
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        timeout: float = ClientConfig.default_timeout,
+        api_key: str | None = None,
+        extra_headers: dict[str, str] | None = None,
+    ) -> None:
+        config = ClientConfig(
+            base_url=base_url,
+            timeout=timeout,
+            api_key=api_key,
+            extra_headers=extra_headers or {},
+        )
+        self._client = httpx.AsyncClient(
+            base_url=config.base_url,
+            timeout=config.timeout,
+            headers=config.build_headers(),
+        )
+
+    @classmethod
+    def from_config(cls, config: ClientConfig) -> AsyncBypassVuotLink:
+        instance = cls.__new__(cls)
+        instance._client = httpx.AsyncClient(
+            base_url=config.base_url,
+            timeout=config.timeout,
+            headers=config.build_headers(),
+        )
+        return instance
+
+    @classmethod
+    def from_env(cls) -> AsyncBypassVuotLink:
+        return cls.from_config(ClientConfig.from_env())
+
+    async def resolve(self, url: str) -> ResolveResult:
+        response = await self._client.post(_ENDPOINT, json={"url": url})
+        return _parse_response(response)
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncBypassVuotLink:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        await self.close()

bypass_vuotlink_sdk-0.1.0/bypass_vuotlink_sdk/config.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import ClassVar
+
+
+@dataclass
+class ClientConfig:
+    """Configuration for BypassVuotLink / AsyncBypassVuotLink.
+
+    Can be constructed directly or loaded from environment variables::
+
+        config = ClientConfig.from_env()
+        # reads BYPASS_BASE_URL, BYPASS_TIMEOUT, BYPASS_API_KEY
+    """
+
+    DEFAULT_TIMEOUT: ClassVar[float] = 60.0
+
+    base_url: str
+    timeout: float = DEFAULT_TIMEOUT
+    api_key: str | None = None
+    extra_headers: dict[str, str] = field(default_factory=dict)
+
+    @classmethod
+    def from_env(cls) -> ClientConfig:
+        base_url = os.environ["BYPASS_BASE_URL"]
+        timeout = float(os.environ.get("BYPASS_TIMEOUT", cls.DEFAULT_TIMEOUT))
+        api_key = os.environ.get("BYPASS_API_KEY")
+        return cls(base_url=base_url, timeout=timeout, api_key=api_key)
+
+    def build_headers(self) -> dict[str, str]:
+        headers = dict(self.extra_headers)
+        if self.api_key:
+            headers["X-API-Key"] = self.api_key
+        return headers

bypass_vuotlink_sdk-0.1.0/bypass_vuotlink_sdk/exceptions.py

@@ -0,0 +1,19 @@
+class BypassVuotlinkError(Exception):
+    """Base exception for all SDK errors."""
+
+
+class UnsafeUrlError(BypassVuotlinkError):
+    """The URL was rejected as unsafe or private (HTTP 400)."""
+
+
+class BrowserExecutionError(BypassVuotlinkError):
+    """The browser workflow failed to execute (HTTP 502)."""
+
+
+class ApiError(BypassVuotlinkError):
+    """Unexpected HTTP error from the server."""
+
+    def __init__(self, status_code: int, detail: str) -> None:
+        super().__init__(f"HTTP {status_code}: {detail}")
+        self.status_code = status_code
+        self.detail = detail

bypass_vuotlink_sdk-0.1.0/bypass_vuotlink_sdk/models.py

@@ -0,0 +1,10 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ResolveResult:
+    requested_url: str
+    final_url: str
+    status_code: int | None
+    title: str
+    workflow: str

bypass_vuotlink_sdk-0.1.0/llms.txt

@@ -0,0 +1,194 @@
+# bypass-vuotlink-sdk
+
+Python SDK for the bypass-vuotlink API — a service that resolves shortlink/safelink URLs
+(e.g. vuotnhanh.com) to their final destination by running a real browser workflow.
+
+## Install
+
+```bash
+pip install bypass-vuotlink-sdk
+```
+
+## Quick start
+
+```python
+from bypass_vuotlink_sdk import BypassVuotLink
+
+# Sync
+with BypassVuotLink(base_url="http://localhost:8000") as client:
+    result = client.resolve("https://vuotnhanh.com/abc123")
+    print(result.final_url)
+
+# Async
+from bypass_vuotlink_sdk import AsyncBypassVuotLink
+
+async with AsyncBypassVuotLink(base_url="http://localhost:8000") as client:
+    result = await client.resolve("https://vuotnhanh.com/abc123")
+    print(result.final_url)
+```
+
+## Classes
+
+### BypassVuotLink (sync)
+
+```python
+class BypassVuotLink:
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        timeout: float = 60.0,       # seconds
+        api_key: str | None = None,  # sent as X-API-Key header
+        extra_headers: dict[str, str] | None = None,
+    ) -> None: ...
+
+    @classmethod
+    def from_config(cls, config: ClientConfig) -> BypassVuotLink: ...
+
+    @classmethod
+    def from_env(cls) -> BypassVuotLink:
+        # reads: BYPASS_BASE_URL, BYPASS_TIMEOUT, BYPASS_API_KEY
+        ...
+
+    def resolve(self, url: str) -> ResolveResult: ...
+    def close(self) -> None: ...
+
+    # context manager
+    def __enter__(self) -> BypassVuotLink: ...
+    def __exit__(self, ...) -> None: ...
+```
+
+### AsyncBypassVuotLink (async)
+
+Same interface as `BypassVuotLink` but all methods are async:
+
+```python
+class AsyncBypassVuotLink:
+    def __init__(self, base_url: str, *, timeout: float = 60.0,
+                 api_key: str | None = None,
+                 extra_headers: dict[str, str] | None = None) -> None: ...
+
+    @classmethod
+    def from_config(cls, config: ClientConfig) -> AsyncBypassVuotLink: ...
+
+    @classmethod
+    def from_env(cls) -> AsyncBypassVuotLink: ...
+
+    async def resolve(self, url: str) -> ResolveResult: ...
+    async def close(self) -> None: ...
+
+    # async context manager
+    async def __aenter__(self) -> AsyncBypassVuotLink: ...
+    async def __aexit__(self, ...) -> None: ...
+```
+
+### ClientConfig
+
+```python
+from dataclasses import dataclass
+from typing import ClassVar
+
+@dataclass
+class ClientConfig:
+    DEFAULT_TIMEOUT: ClassVar[float] = 60.0
+
+    base_url: str
+    timeout: float = 60.0
+    api_key: str | None = None
+    extra_headers: dict[str, str] = field(default_factory=dict)
+
+    @classmethod
+    def from_env(cls) -> ClientConfig:
+        # BYPASS_BASE_URL  (required)
+        # BYPASS_TIMEOUT   (optional, default 60.0)
+        # BYPASS_API_KEY   (optional)
+        ...
+
+    def build_headers(self) -> dict[str, str]: ...
+```
+
+### ResolveResult
+
+```python
+@dataclass(frozen=True)
+class ResolveResult:
+    requested_url: str   # the URL you passed in
+    final_url: str       # the resolved destination URL
+    status_code: int | None
+    title: str           # page title at final_url
+    workflow: str        # which workflow handled it (e.g. "vuotnhanh")
+```
+
+## Exceptions
+
+```
+BypassVuotlinkError          # base — catch this to handle all SDK errors
+├── UnsafeUrlError           # HTTP 400 — URL is private/unsafe
+├── BrowserExecutionError    # HTTP 502 — browser workflow crashed
+└── ApiError                 # any other unexpected HTTP status
+      .status_code: int
+      .detail: str
+```
+
+```python
+from bypass_vuotlink_sdk import (
+    BypassVuotLink,
+    UnsafeUrlError,
+    BrowserExecutionError,
+    BypassVuotlinkError,
+)
+
+try:
+    result = client.resolve(url)
+except UnsafeUrlError:
+    # URL points to a private/reserved address
+    ...
+except BrowserExecutionError:
+    # the browser failed to process the page
+    ...
+except BypassVuotlinkError:
+    # catch-all for any other SDK error
+    ...
+```
+
+## Environment variable config
+
+```bash
+export BYPASS_BASE_URL="http://bypass-api:8000"
+export BYPASS_TIMEOUT="90"
+export BYPASS_API_KEY="secret"
+```
+
+```python
+client = BypassVuotLink.from_env()
+```
+
+## API reference (server)
+
+The SDK wraps a single endpoint:
+
+```
+POST /api/v1/browser
+Content-Type: application/json
+
+{ "url": "https://vuotnhanh.com/abc123" }
+```
+
+Response:
+
+```json
+{
+  "requested_url": "https://vuotnhanh.com/abc123",
+  "final_url": "https://example.com/destination",
+  "status_code": 200,
+  "title": "Example Domain",
+  "workflow": "vuotnhanh"
+}
+```
+
+Errors:
+
+| Status | Meaning |
+|--------|---------|
+| 400    | URL is unsafe or private |
+| 502    | Browser workflow execution failed |

bypass_vuotlink_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "bypass-vuotlink-sdk"
+version = "0.1.0"
+description = "Python SDK for the bypass-vuotlink API"
+requires-python = ">=3.10"
+dependencies = [
+    "httpx>=0.24",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["bypass_vuotlink_sdk"]