webuplink 0.1.0__tar.gz

webuplink-0.1.0/.github/logo-dark.svg

@@ -0,0 +1,17 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="360" height="160" viewBox="0 0 360 160">
+  <!-- WebUplink wordmark lockup — mark + text side by side. Dark mode. -->
+  <!-- PageMap 3×3 mark, vertically centered -->
+  <g transform="translate(20, 36)">
+    <rect x="0" y="0" width="24" height="24" rx="3.6" fill="#EDE7D9"/>
+    <rect x="32" y="0" width="24" height="24" rx="3.6" fill="#EDE7D9"/>
+    <rect x="64" y="0" width="24" height="24" rx="3.6" fill="#46999A"/>
+    <rect x="0" y="32" width="24" height="24" rx="3.6" fill="#EDE7D9"/>
+    <rect x="32" y="32" width="24" height="24" rx="3.6" fill="#EDE7D9"/>
+    <rect x="64" y="32" width="24" height="24" rx="3.6" fill="#EDE7D9"/>
+    <rect x="0" y="64" width="24" height="24" rx="3.6" fill="#EDE7D9"/>
+    <rect x="32" y="64" width="24" height="24" rx="3.6" fill="#EDE7D9"/>
+    <rect x="64" y="64" width="24" height="24" rx="3.6" fill="#EDE7D9"/>
+  </g>
+  <!-- Wordmark text, vertically centered alongside mark -->
+  <text x="124" y="89" font-family="Inter, system-ui, -apple-system, sans-serif" font-size="36" font-weight="600" letter-spacing="-0.02em" fill="#EDE7D9">WebUplink</text>
+</svg>

webuplink-0.1.0/.github/logo-light.svg

@@ -0,0 +1,17 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="360" height="160" viewBox="0 0 360 160">
+  <!-- WebUplink wordmark lockup — mark + text side by side. Light mode. -->
+  <!-- PageMap 3×3 mark, vertically centered -->
+  <g transform="translate(20, 36)">
+    <rect x="0" y="0" width="24" height="24" rx="3.6" fill="#1C1B18"/>
+    <rect x="32" y="0" width="24" height="24" rx="3.6" fill="#1C1B18"/>
+    <rect x="64" y="0" width="24" height="24" rx="3.6" fill="#0E6E78"/>
+    <rect x="0" y="32" width="24" height="24" rx="3.6" fill="#1C1B18"/>
+    <rect x="32" y="32" width="24" height="24" rx="3.6" fill="#1C1B18"/>
+    <rect x="64" y="32" width="24" height="24" rx="3.6" fill="#1C1B18"/>
+    <rect x="0" y="64" width="24" height="24" rx="3.6" fill="#1C1B18"/>
+    <rect x="32" y="64" width="24" height="24" rx="3.6" fill="#1C1B18"/>
+    <rect x="64" y="64" width="24" height="24" rx="3.6" fill="#1C1B18"/>
+  </g>
+  <!-- Wordmark text, vertically centered alongside mark -->
+  <text x="124" y="89" font-family="Inter, system-ui, -apple-system, sans-serif" font-size="36" font-weight="600" letter-spacing="-0.02em" fill="#1C1B18">WebUplink</text>
+</svg>

webuplink-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    name: Build & Test
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e '.[dev]'
+      - run: pytest

webuplink-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    name: Publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install build
+      - name: Verify version matches release tag
+        run: |
+          PKG_VERSION=$(python -c "exec(open('src/webuplink/_version.py').read()); print(__version__)")
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
+            echo "::error::_version.py ($PKG_VERSION) does not match release tag ($TAG_VERSION)"
+            exit 1
+          fi
+      - run: pip install -e '.[dev]'
+      - run: pytest
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

webuplink-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+.DS_Store

webuplink-0.1.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.1.0 (2026-06-30)
+
+Initial public release.
+
+### Features
+
+- `browse()` — browse pages and execute tools with string shorthand, `BrowseParams`, or keyword arguments
+- `close_session()` — explicit session cleanup
+- `health()` — API health check with optional deep component checks
+- `get_usage()` — usage and billing information for the authenticated tenant
+- Sync (`WebUplink`) and async (`AsyncWebUplink`) clients with context manager support
+- Idempotency-aware retry with configurable `max_retries`
+- Typed error hierarchy: `WebUplinkError`, `AuthenticationError`, `RateLimitError`, `APIConnectionError`
+- `Usage` metadata from `X-Usage-*` response headers
+- Pydantic v2 models for all request/response types
+- `py.typed` marker for PEP 561 type checker support
+- Custom `httpx.Client` / `httpx.AsyncClient` injection for proxies, mTLS, and logging

webuplink-0.1.0/LICENSE

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

webuplink-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: webuplink
+Version: 0.1.0
+Summary: Official Python SDK for WebUplink — the whole web, as function calls.
+Project-URL: Homepage, https://webuplink.ai
+Project-URL: Documentation, https://webuplink.ai/docs
+Project-URL: Repository, https://github.com/webuplink-dev/webuplink-python
+Author-email: WebUplink <dev@webuplink.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,browser,sdk,web-automation,webuplink
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: pydantic<3.0,>=2.0
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.22; extra == 'dev'
+Requires-Dist: ruff>=0.11; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset=".github/logo-dark.svg">
+  <source media="(prefers-color-scheme: light)" srcset=".github/logo-light.svg">
+  <img alt="WebUplink" src=".github/logo-light.svg" width="200">
+</picture>
+
+### The whole web, as function calls.
+
+[![PyPI version](https://img.shields.io/pypi/v/webuplink.svg)](https://pypi.org/project/webuplink/)
+[![CI](https://github.com/webuplink-dev/webuplink-python/actions/workflows/ci.yml/badge.svg)](https://github.com/webuplink-dev/webuplink-python/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Official Python SDK for [WebUplink](https://webuplink.ai).
+
+## Installation
+
+```bash
+pip install webuplink
+```
+
+## Quickstart
+
+```python
+from webuplink import WebUplink
+
+client = WebUplink()  # reads WEBUPLINK_API_KEY from env
+
+# Browse a page — get back structured, callable tools
+page = client.browse("https://example.com")
+print(page.summary)
+print(page.tools)  # [Tool(name='...', description='...', params=[...]), ...]
+
+# Execute a tool discovered on the page
+tool = page.tools[0]
+result = client.browse(
+    session_id=page.session_id,
+    tool=tool.name,
+    params={tool.params[0].name: "some value"},
+)
+
+# Clean up
+client.close_session(page.session_id)
+```
+
+## Async
+
+```python
+from webuplink import AsyncWebUplink
+
+async with AsyncWebUplink() as client:
+    page = await client.browse("https://example.com")
+    print(page.tools)
+```
+
+## What you can build
+
+- **AI agents that act on the web** — browse any site, get back typed tool definitions, execute actions
+- **No selectors, no scraping** — WebUplink understands pages and generates callable tools automatically
+- **Multi-step workflows** — sessions persist across navigations, so your agent can search → filter → select → checkout
+- **Any website, zero configuration** — works on sites you've never seen before
+
+## Documentation
+
+Full reference at **[webuplink.ai/docs](https://webuplink.ai/docs)**.
+
+## Contributing
+
+```bash
+git clone https://github.com/webuplink-dev/webuplink-python.git
+cd webuplink-python
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

webuplink-0.1.0/README.md

@@ -0,0 +1,77 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset=".github/logo-dark.svg">
+  <source media="(prefers-color-scheme: light)" srcset=".github/logo-light.svg">
+  <img alt="WebUplink" src=".github/logo-light.svg" width="200">
+</picture>
+
+### The whole web, as function calls.
+
+[![PyPI version](https://img.shields.io/pypi/v/webuplink.svg)](https://pypi.org/project/webuplink/)
+[![CI](https://github.com/webuplink-dev/webuplink-python/actions/workflows/ci.yml/badge.svg)](https://github.com/webuplink-dev/webuplink-python/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Official Python SDK for [WebUplink](https://webuplink.ai).
+
+## Installation
+
+```bash
+pip install webuplink
+```
+
+## Quickstart
+
+```python
+from webuplink import WebUplink
+
+client = WebUplink()  # reads WEBUPLINK_API_KEY from env
+
+# Browse a page — get back structured, callable tools
+page = client.browse("https://example.com")
+print(page.summary)
+print(page.tools)  # [Tool(name='...', description='...', params=[...]), ...]
+
+# Execute a tool discovered on the page
+tool = page.tools[0]
+result = client.browse(
+    session_id=page.session_id,
+    tool=tool.name,
+    params={tool.params[0].name: "some value"},
+)
+
+# Clean up
+client.close_session(page.session_id)
+```
+
+## Async
+
+```python
+from webuplink import AsyncWebUplink
+
+async with AsyncWebUplink() as client:
+    page = await client.browse("https://example.com")
+    print(page.tools)
+```
+
+## What you can build
+
+- **AI agents that act on the web** — browse any site, get back typed tool definitions, execute actions
+- **No selectors, no scraping** — WebUplink understands pages and generates callable tools automatically
+- **Multi-step workflows** — sessions persist across navigations, so your agent can search → filter → select → checkout
+- **Any website, zero configuration** — works on sites you've never seen before
+
+## Documentation
+
+Full reference at **[webuplink.ai/docs](https://webuplink.ai/docs)**.
+
+## Contributing
+
+```bash
+git clone https://github.com/webuplink-dev/webuplink-python.git
+cd webuplink-python
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

webuplink-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "webuplink"
+dynamic = ["version"]
+description = "Official Python SDK for WebUplink — the whole web, as function calls."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = [
+    "httpx>=0.27,<1.0",
+    "pydantic>=2.0,<3.0",
+]
+keywords = ["webuplink", "ai-agent", "browser", "web-automation", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Typing :: Typed",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+authors = [
+    { name = "WebUplink", email = "dev@webuplink.ai" },
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=1.0",
+    "respx>=0.22",
+    "ruff>=0.11",
+    "pyright>=1.1",
+]
+
+[project.urls]
+Homepage = "https://webuplink.ai"
+Documentation = "https://webuplink.ai/docs"
+Repository = "https://github.com/webuplink-dev/webuplink-python"
+
+[tool.hatch.version]
+path = "src/webuplink/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/webuplink"]
+
+[tool.pyright]
+typeCheckingMode = "strict"
+pythonVersion = "3.10"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

webuplink-0.1.0/src/webuplink/__init__.py

@@ -0,0 +1,64 @@
+"""webuplink — Official Python SDK for WebUplink.
+
+Browse and interact with any website via structured, typed tool definitions.
+
+Usage::
+
+    from webuplink import WebUplink
+
+    client = WebUplink(api_key="wup_your_api_key")
+    page = client.browse("https://example.com")
+    print(page.tools)
+
+For async usage::
+
+    from webuplink import AsyncWebUplink
+
+    async with AsyncWebUplink() as client:
+        page = await client.browse("https://example.com")
+"""
+
+from webuplink._client import AsyncWebUplink, WebUplink
+from webuplink._errors import (
+    APIConnectionError,
+    AuthenticationError,
+    RateLimitError,
+    WebUplinkError,
+)
+from webuplink._types import (
+    BrowseParams,
+    BrowseResult,
+    ErrorCode,
+    HealthResult,
+    Tool,
+    ToolExecution,
+    ToolParam,
+    ToolResult,
+    Usage,
+    UsageResponse,
+)
+from webuplink._version import __version__
+
+__all__ = [
+    # Clients
+    "WebUplink",
+    "AsyncWebUplink",
+    # Errors
+    "WebUplinkError",
+    "AuthenticationError",
+    "RateLimitError",
+    "APIConnectionError",
+    # Types
+    "BrowseParams",
+    "BrowseResult",
+    "Tool",
+    "ToolParam",
+    "ToolResult",
+    "ToolExecution",
+    "Usage",
+    "UsageResponse",
+    "HealthResult",
+    "ErrorCode",
+    # Version
+    "__version__",
+]

webuplink-0.1.0/src/webuplink/_base_client.py

@@ -0,0 +1,178 @@
+"""
+Shared HTTP logic for both sync and async clients.
+
+This module contains all request construction, response parsing, error
+mapping, usage header extraction, and retry logic.  The ``WebUplink``
+and ``AsyncWebUplink`` classes delegate to these functions so the
+logic exists in exactly one place.
+
+Retry semantics match the TypeScript SDK exactly:
+  - API errors with ``retry_after``: sleep for ``retry_after`` seconds
+  - Connection errors: linear backoff (1s × attempt)
+  - Never retry 429 (amplifies load)
+  - Never retry tool execution (non-idempotent)
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import httpx
+
+from webuplink._constants import USER_AGENT
+from webuplink._errors import (
+    AuthenticationError,
+    RateLimitError,
+    WebUplinkError,
+)
+from webuplink._types import BrowseResult, HealthResult, Usage, UsageResponse
+
+DEFAULT_RETRY_DELAY_S = 5.0
+"""Seconds to wait before retrying when the server omits ``retry_after``."""
+
+# ── Header Construction ──────────────────────────────────────────
+
+
+def make_headers(api_key: str) -> dict[str, str]:
+    """Build the default request headers."""
+    return {
+        "Authorization": f"Bearer {api_key}",
+        "User-Agent": USER_AGENT,
+    }
+
+
+# ── Response Parsing ─────────────────────────────────────────────
+
+
+def parse_browse_response(response: httpx.Response) -> BrowseResult:
+    """Deserialize a successful browse response + usage headers."""
+    data = response.json()
+    usage = _parse_usage_headers(response)
+    return BrowseResult(**data, usage=usage)
+
+
+def parse_health_response(response: httpx.Response) -> HealthResult:
+    """Deserialize a successful health response."""
+    return HealthResult(**response.json())
+
+
+def parse_usage_response(response: httpx.Response) -> UsageResponse:
+    """Deserialize a successful usage response."""
+    return UsageResponse(**response.json())
+
+
+def _parse_usage_headers(response: httpx.Response) -> Usage | None:
+    """Extract ``X-Usage-*`` headers into a ``Usage`` model, or ``None``."""
+    count = response.headers.get("x-usage-action-count")
+    limit = response.headers.get("x-usage-action-limit")
+    period = response.headers.get("x-usage-period-start")
+
+    if not count or not limit or not period:
+        return None
+
+    return Usage(
+        action_count=int(count),
+        action_limit=int(limit),
+        period_start=period,
+    )
+
+
+# ── Error Parsing ────────────────────────────────────────────────
+
+
+def parse_error_response(response: httpx.Response) -> WebUplinkError:
+    """Map a non-2xx ``httpx.Response`` to a ``WebUplinkError`` (or subclass)."""
+    request_id = response.headers.get("x-request-id", "unknown")
+
+    try:
+        data: dict[str, Any] = response.json()
+    except Exception:
+        # Non-JSON body (e.g. 502 from load balancer)
+        return _create_error_from_status(
+            response.status_code,
+            response.reason_phrase or f"HTTP {response.status_code}",
+            code="INTERNAL_ERROR",
+            status_code=response.status_code,
+            request_id=request_id,
+        )
+
+    code = data.get("error", "INTERNAL_ERROR")
+    message = data.get("message", response.reason_phrase or f"HTTP {response.status_code}")
+    retry_after_raw = data.get("retry_after")
+    details = data.get("details")
+
+    # Retryability: the server sets retry_after for transient issues.
+    # 429 (RATE_LIMITED / QUOTA_EXCEEDED) carries retry_after but
+    # auto-retrying a throttle just amplifies load — never retry them.
+    retryable = (
+        response.status_code != 429
+        and retry_after_raw is not None
+        and float(retry_after_raw) > 0
+    )
+
+    return _create_error_from_status(
+        response.status_code,
+        message,
+        code=code,
+        status_code=response.status_code,
+        request_id=request_id,
+        retryable=retryable,
+        retry_after=float(retry_after_raw) if retry_after_raw is not None else None,
+        details=details,
+    )
+
+
+def _create_error_from_status(
+    status: int,
+    message: str,
+    **kwargs: Any,
+) -> WebUplinkError:
+    """Map HTTP status to the most specific error subclass."""
+    if status == 401:
+        return AuthenticationError(message, **kwargs)
+    if status == 429:
+        return RateLimitError(message, **kwargs)
+    return WebUplinkError(message, **kwargs)
+
+
+# ── Retry Logic ──────────────────────────────────────────────────
+
+
+def should_retry(
+    error: WebUplinkError,
+    *,
+    attempt: int,
+    max_retries: int,
+    has_tools: bool,
+) -> bool:
+    """Decide whether a failed request should be retried.
+
+    Rules (matching the TypeScript SDK exactly):
+      1. Must have retries remaining (``attempt < 1 + max_retries``)
+      2. The error must be marked retryable by ``parse_error_response``
+      3. Tool execution is never retried (non-idempotent)
+    """
+    if attempt >= 1 + max_retries:
+        return False
+    if has_tools:
+        return False
+    return error.retryable
+
+
+def get_retry_delay(error: WebUplinkError) -> float:
+    """Return the delay (in seconds) before retrying an API error."""
+    return error.retry_after if error.retry_after is not None else DEFAULT_RETRY_DELAY_S
+
+
+def get_connection_retry_delay(attempt: int) -> float:
+    """Return the delay (in seconds) before retrying a connection error.
+
+    Uses linear backoff: 1s × attempt (matching the TS SDK).
+    """
+    return 1.0 * attempt
+
+
+def sleep_sync(seconds: float) -> None:
+    """Blocking sleep for sync retry loops."""
+    time.sleep(seconds)