server4agent 0.1.0__py3-none-any.whl

server4agent/_transport.py

@@ -0,0 +1,115 @@
+"""Transport pieces shared by the sync and async clients.
+
+Only the actual send/await differs between them; URL/header prep, the retry
+policy, JSON decoding, error parsing, and debug logging all live here so the
+two clients stay in lockstep.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import random
+from typing import Any, Mapping, Optional
+from urllib.parse import quote
+
+from ._version import __version__
+from .errors import error_from_status
+
+DEFAULT_BASE_URL = "https://api.server4agent.com"
+DEFAULT_TIMEOUT = 60.0
+DEFAULT_MAX_RETRIES = 2
+
+USER_AGENT = f"server4agent-python/{__version__}"
+
+# Statuses worth retrying at all.
+RETRYABLE_STATUS = frozenset({408, 429, 500, 502, 503, 504})
+# Methods safe to retry on any retryable status (no risk of duplicate writes).
+IDEMPOTENT_METHODS = frozenset({"GET", "HEAD", "PUT", "DELETE", "OPTIONS"})
+# For non-idempotent methods (POST/PATCH) we only retry when the server clearly
+# did not process the request, so a retry can never create a duplicate.
+NON_IDEMPOTENT_RETRY_STATUS = frozenset({408, 429, 503})
+
+_BACKOFF_BASE = 0.5
+_BACKOFF_MAX = 8.0
+
+logger = logging.getLogger("server4agent")
+# Opt-in one-line request logging via SERVER4AGENT_LOG=debug.
+if os.environ.get("SERVER4AGENT_LOG", "").lower() == "debug" and not logger.handlers:
+    _h = logging.StreamHandler()
+    _h.setFormatter(logging.Formatter("[server4agent] %(message)s"))
+    logger.addHandler(_h)
+    logger.setLevel(logging.DEBUG)
+
+
+def default_headers(api_key: str) -> dict:
+    return {
+        "Authorization": f"Bearer {api_key}",
+        "User-Agent": USER_AGENT,
+        "Accept": "application/json",
+    }
+
+
+def quote_segment(value: Any) -> str:
+    """Percent-encode a value for safe use as a single URL path segment, so an id
+    containing "/", "..", "?", or "#" can't redirect the request elsewhere."""
+    return quote(str(value), safe="")
+
+
+def clean_params(query: Optional[Mapping[str, Any]]) -> Optional[dict]:
+    """Drop None values so we never send `?path=None`."""
+    if not query:
+        return None
+    out = {k: v for k, v in query.items() if v is not None}
+    return out or None
+
+
+def decode_json(raw: bytes) -> Any:
+    """Parse a JSON body, tolerating empty or non-JSON responses (proxy HTML, etc.)."""
+    if not raw:
+        return None
+    try:
+        return json.loads(raw)
+    except (json.JSONDecodeError, ValueError):
+        return None
+
+
+def should_retry_status(method: str, status: int, attempt: int, max_retries: int) -> bool:
+    if attempt >= max_retries or status not in RETRYABLE_STATUS:
+        return False
+    if method.upper() in IDEMPOTENT_METHODS:
+        return True
+    return status in NON_IDEMPOTENT_RETRY_STATUS
+
+
+def can_retry_exception(method: str, attempt: int, max_retries: int) -> bool:
+    # A network/timeout error may have been processed server-side, so only retry
+    # methods where a duplicate is harmless.
+    return attempt < max_retries and method.upper() in IDEMPOTENT_METHODS
+
+
+def retry_delay(attempt: int, retry_after: Optional[str]) -> float:
+    """Seconds to wait before the next attempt.
+
+    Honors a numeric ``Retry-After`` header when present; otherwise uses
+    exponential backoff with full jitter to avoid thundering herds.
+    """
+    if retry_after:
+        try:
+            return min(float(retry_after), _BACKOFF_MAX)
+        except ValueError:
+            pass  # HTTP-date form — fall through to backoff
+    ceiling = min(_BACKOFF_MAX, _BACKOFF_BASE * (2 ** attempt))
+    return random.uniform(0, ceiling)
+
+
+def request_id_from(headers: Mapping[str, str]) -> Optional[str]:
+    return headers.get("x-request-id") or headers.get("X-Request-Id")
+
+
+def raise_for_status(status: int, body: Any, headers: Mapping[str, str]) -> None:
+    """Turn a non-2xx response into the right typed error."""
+    parsed = body if isinstance(body, dict) else {}
+    code = parsed.get("error", "unknown_error")
+    message = parsed.get("message") or f"Request failed with status {status}"
+    raise error_from_status(status, code, message, request_id_from(headers))

server4agent/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

server4agent/errors.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from typing import Optional
+
+
+class Server4AgentError(Exception):
+    """Base class for every error raised by this SDK."""
+
+
+class APIConnectionError(Server4AgentError):
+    """The request never reached the API (DNS, TCP, TLS, or a dropped connection)."""
+
+    def __init__(self, message: str = "Could not reach the Server4Agent API.") -> None:
+        super().__init__(message)
+        self.message = message
+
+
+class APITimeoutError(APIConnectionError):
+    """The request timed out before the API responded."""
+
+    def __init__(self, message: str = "Request to the Server4Agent API timed out.") -> None:
+        super().__init__(message)
+
+
+class APIStatusError(Server4AgentError):
+    """The API returned a 4xx/5xx response.
+
+    Prefer catching a specific subclass (``NotFoundError``, ``RateLimitError``,
+    ...). ``code`` is the machine-readable string from the response body and
+    ``request_id`` (when present) is worth quoting to support.
+    """
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        message: str,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}(status={self.status!r}, code={self.code!r}, "
+            f"message={self.message!r}, request_id={self.request_id!r})"
+        )
+
+
+class BadRequestError(APIStatusError):
+    """400 — the request was malformed."""
+
+
+class AuthenticationError(APIStatusError):
+    """401 — the API key is missing, invalid, or revoked."""
+
+
+class PermissionDeniedError(APIStatusError):
+    """403 — the key is valid but not scoped to this resource."""
+
+
+class NotFoundError(APIStatusError):
+    """404 — no such resource."""
+
+
+class ConflictError(APIStatusError):
+    """409 — the request conflicts with the current state (e.g. a cap was hit)."""
+
+
+class UnprocessableEntityError(APIStatusError):
+    """422 — the request was well-formed but semantically invalid."""
+
+
+class RateLimitError(APIStatusError):
+    """429 — too many requests. The SDK retries these automatically; you only see it once retries are exhausted."""
+
+
+class InternalServerError(APIStatusError):
+    """5xx — something went wrong on the API side."""
+
+
+_STATUS_TO_ERROR = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: UnprocessableEntityError,
+    429: RateLimitError,
+}
+
+
+def error_from_status(
+    status: int, code: str, message: str, request_id: Optional[str] = None
+) -> APIStatusError:
+    """Map an HTTP status onto the most specific ``APIStatusError`` subclass."""
+    cls = _STATUS_TO_ERROR.get(status)
+    if cls is None:
+        cls = InternalServerError if status >= 500 else APIStatusError
+    return cls(status, code, message, request_id)

server4agent/webhooks.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+from typing import Optional
+
+# Server4Agent signs webhook deliveries as
+# HMAC-SHA256(secret, f"{unix_ts}.{raw_body}"), sent as the
+# Server4Agent-Signature header: "t=<unix_ts>,v1=<hex digest>".
+
+
+def _sign(secret: str, body: str, timestamp: int) -> str:
+    digest = hmac.new(
+        secret.encode("utf-8"),
+        f"{timestamp}.{body}".encode("utf-8"),
+        hashlib.sha256,
+    ).hexdigest()
+    return f"t={timestamp},v1={digest}"
+
+
+def verify_webhook_signature(
+    secret: str,
+    body: str,
+    header: Optional[str],
+    tolerance_sec: int = 300,
+) -> bool:
+    """Verify a webhook delivery.
+
+    `body` must be the raw request body exactly as received — decoding and
+    re-serializing JSON changes the bytes and breaks the signature. `header`
+    is the `Server4Agent-Signature` header value. Deliveries older than
+    `tolerance_sec` (default 300s) are rejected to limit replay windows.
+    """
+    if not header:
+        return False
+
+    parts = {}
+    for piece in header.split(","):
+        if "=" not in piece:
+            continue
+        k, v = piece.split("=", 1)
+        parts[k] = v
+
+    raw_ts = parts.get("t")
+    v1 = parts.get("v1")
+    if not raw_ts or not v1:
+        return False
+    try:
+        timestamp = int(raw_ts)
+    except ValueError:
+        return False
+
+    if abs(time.time() - timestamp) > tolerance_sec:
+        return False
+
+    expected = _sign(secret, body, timestamp)
+    expected_v1 = expected.split("v1=")[1]
+    return hmac.compare_digest(expected_v1, v1)

server4agent-0.1.0.dist-info/METADATA

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: server4agent
+Version: 0.1.0
+Summary: Python client for the Server4Agent REST API — sync + async, typed, with retries.
+Project-URL: Homepage, https://www.server4agent.com
+Project-URL: Documentation, https://www.server4agent.com/docs/sdks
+Project-URL: Repository, https://github.com/Server4Agent/server4agent-python
+License: MIT
+License-File: LICENSE
+Keywords: agents,mcp,sdk,server4agent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# server4agent
+
+Python client for the [Server4Agent](https://www.server4agent.com) REST API —
+sync **and** async, fully typed, with automatic retries.
+
+This SDK is for the code *around* your agent — your backend, a script, a
+notebook, a webhook receiver. If your agent itself does tool-calling, point it
+at the [MCP server](https://www.server4agent.com/docs/mcp) directly; it doesn't
+need this package.
+
+## Install
+
+```bash
+pip install server4agent
+```
+
+Requires Python 3.9+. Depends only on [`httpx`](https://www.python-httpx.org/).
+
+## Quickstart
+
+```python
+from server4agent import Server4Agent
+
+client = Server4Agent()  # reads SERVER4AGENT_API_KEY from the environment
+
+# create() returns a handle you can act on directly
+server = client.servers.create(tier="small")
+
+# kick off a build and block until it's live
+build = server.builds.start("a FastAPI todo API with a web UI").wait()
+print(build.url)
+
+# run a command right on the server
+print(server.exec("ls -la"))
+```
+
+`api_key` can also be passed explicitly: `Server4Agent(api_key="sk_live_...")`.
+Use it as a context manager to close the connection pool:
+
+```python
+with Server4Agent() as client:
+    ...
+```
+
+## Async
+
+The async client mirrors the sync one method-for-method:
+
+```python
+import asyncio
+from server4agent import AsyncServer4Agent
+
+async def main():
+    async with AsyncServer4Agent() as client:
+        server = await client.servers.create(tier="small")
+        task = await server.tasks.create("Scrape today's HN front page to JSON.")
+        await task.wait()
+        print(task.status, task.result)
+
+asyncio.run(main())
+```
+
+## Handles
+
+`create()` and `get()` return rich handles — data records you can also act on:
+
+```python
+server = client.servers.get("srv_abc")
+server.tasks.create("...")          # sub-resources are scoped to the server
+server.files.write("app.py", "...")
+server.deploy()
+server.refresh()                    # re-fetch in place
+
+project = client.projects.get("prj_xyz")
+project.update(visibility="public")
+```
+
+`task.wait()` / `build.wait()` poll until a terminal state; both accept
+`poll_interval` and `timeout` (seconds).
+
+## Errors
+
+Every failure is a subclass of `Server4AgentError`, so you can catch broadly or
+narrowly:
+
+```python
+from server4agent import NotFoundError, RateLimitError, APIStatusError
+
+try:
+    client.servers.get("srv_missing")
+except NotFoundError:
+    ...                              # 404
+except RateLimitError as e:
+    ...                              # 429 (already retried; quote e.request_id to support)
+except APIStatusError as e:
+    print(e.status, e.code, e.message, e.request_id)
+```
+
+Retryable failures (429, 5xx, network blips) are retried automatically with
+exponential backoff. Tune it per client:
+
+```python
+Server4Agent(timeout=30.0, max_retries=4)
+```
+
+## Verifying webhooks
+
+```python
+import os
+from server4agent import verify_webhook_signature
+
+# request.data must be the raw body — parse it as JSON only after verifying.
+ok = verify_webhook_signature(
+    secret=os.environ["SERVER4AGENT_WEBHOOK_SECRET"],
+    body=request.data.decode("utf-8"),
+    header=request.headers.get("Server4Agent-Signature"),
+)
+if not ok:
+    return "invalid signature", 401
+```
+
+## API surface
+
+`servers`, `projects`, `templates`, `tasks`, `builds`, `files`, `keys`,
+`webhooks` — see the [REST API docs](https://www.server4agent.com/docs/api) for
+the endpoints each method wraps.
+
+Server-side only: this SDK holds your `sk_live_` key. Never embed it in a
+notebook or script you share.

server4agent-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+server4agent/__init__.py,sha256=_D-aXt-Krlyj1yotPeEl2ca3J0w_2ccAR9Cu2GZR4sY,1632
+server4agent/_models.py,sha256=QedyzzguyqYur_gVim7TYTm_VtBAQIUeXee0S9kp7m8,5520
+server4agent/_transport.py,sha256=6UhDhdd74Vpo39Ju2oQJDodshwe8DrySciL01DMdQuI,4088
+server4agent/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+server4agent/errors.py,sha256=gvyF5DyfE76vCMgOZNmVftDaKZUS9RhahhHgolR9MQU,3007
+server4agent/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+server4agent/webhooks.py,sha256=NqSESJ2AeQ2R_4fqwCruA6u93qPNSTmPgHJYLLq-H1g,1589
+server4agent/_async/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+server4agent/_async/client.py,sha256=9nvwd8aCPgi4OK6HISD3FJkKi9WQAiNGwNbi2aZXdIE,20145
+server4agent/_async/transport.py,sha256=8giEr6CA27-4r-AATLuVVdebCwYECx_xKnx2L-o6ZL0,2638
+server4agent/_sync/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+server4agent/_sync/client.py,sha256=1kKRdLiYuRwCOHFOVFBF7684873DhPppU7tBA9SRt1w,19838
+server4agent/_sync/transport.py,sha256=Wbxer1dXRMomeN3l814ZUBdmD9ZWr-zDEKJ7yRVjUpw,2562
+server4agent-0.1.0.dist-info/METADATA,sha256=OGDblXPEsytSRUzgoSqtNs6_7EZkKux0nlAHDJAapSE,4365
+server4agent-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+server4agent-0.1.0.dist-info/licenses/LICENSE,sha256=mn_K4ahqVsYCCH2u2DsU7nUWuhYa2Qza07_TnTqYPSE,1069
+server4agent-0.1.0.dist-info/RECORD,,

server4agent-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

server4agent-0.1.0.dist-info/licenses/LICENSE

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