manifest-api 0.1.0__py3-none-any.whl

manifest_api/__init__.py

@@ -0,0 +1,28 @@
+"""manifest-api — Python SDK for the Manifest API."""
+
+from .client import (
+    Action,
+    APIError,
+    AsyncManifestClient,
+    AuthenticationError,
+    Manifest,
+    ManifestClient,
+    ManifestError,
+    NavLink,
+    RateLimitError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "ManifestClient",
+    "AsyncManifestClient",
+    "Manifest",
+    "Action",
+    "NavLink",
+    "ManifestError",
+    "AuthenticationError",
+    "RateLimitError",
+    "APIError",
+]

manifest_api/client.py

@@ -0,0 +1,237 @@
+"""Manifest API client — sync and async."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+import httpx
+
+_BASE_URL = "https://manifest.omfang.io"
+_DEFAULT_TIMEOUT = 30.0
+
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+class ManifestError(Exception):
+    """Base exception for all Manifest API errors."""
+
+
+class AuthenticationError(ManifestError):
+    """Missing or invalid API key."""
+
+
+class RateLimitError(ManifestError):
+    """Rate limit exceeded (429)."""
+
+
+class APIError(ManifestError):
+    """Unexpected API error (5xx or other)."""
+    def __init__(self, message: str, status_code: int) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+# ---------------------------------------------------------------------------
+# Data models
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Action:
+    id: str
+    label: str
+    type: str
+    description: str
+    required: bool
+
+    @classmethod
+    def _from_dict(cls, d: dict) -> "Action":
+        return cls(
+            id=d["id"],
+            label=d["label"],
+            type=d["type"],
+            description=d.get("description", ""),
+            required=d.get("required", False),
+        )
+
+
+@dataclass
+class NavLink:
+    label: str
+    url: str
+
+    @classmethod
+    def _from_dict(cls, d: dict) -> "NavLink":
+        return cls(label=d["label"], url=d["url"])
+
+
+@dataclass
+class Manifest:
+    url: str
+    authenticated_user: Optional[str]
+    current_page_state: str
+    actions: List[Action] = field(default_factory=list)
+    navigation: List[NavLink] = field(default_factory=list)
+
+    @classmethod
+    def _from_dict(cls, d: dict) -> "Manifest":
+        return cls(
+            url=d["url"],
+            authenticated_user=d.get("authenticated_user"),
+            current_page_state=d.get("current_page_state", ""),
+            actions=[Action._from_dict(a) for a in d.get("actions", [])],
+            navigation=[NavLink._from_dict(n) for n in d.get("navigation", [])],
+        )
+
+    def action(self, id: str) -> Optional[Action]:
+        """Return the action with the given id, or None."""
+        return next((a for a in self.actions if a.id == id), None)
+
+    def actions_of_type(self, type: str) -> List[Action]:
+        """Return all actions matching the given type."""
+        return [a for a in self.actions if a.type == type]
+
+    @property
+    def required_actions(self) -> List[Action]:
+        """Return all actions where required=True."""
+        return [a for a in self.actions if a.required]
+
+
+# ---------------------------------------------------------------------------
+# Shared helpers
+# ---------------------------------------------------------------------------
+
+def _resolve_api_key(api_key: Optional[str]) -> str:
+    key = api_key or os.environ.get("MANIFEST_API_KEY", "")
+    if not key:
+        raise AuthenticationError(
+            "No API key provided. Pass api_key= or set MANIFEST_API_KEY."
+        )
+    return key
+
+
+def _headers(api_key: str) -> dict:
+    return {"X-API-Key": api_key, "Content-Type": "application/json"}
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    if response.status_code == 401:
+        raise AuthenticationError("Invalid or missing API key (401).")
+    if response.status_code == 429:
+        raise RateLimitError("Rate limit exceeded (429). Slow down requests.")
+    if response.status_code >= 500:
+        raise APIError(
+            f"Server error: {response.text}", status_code=response.status_code
+        )
+    if response.status_code >= 400:
+        raise APIError(
+            f"Client error {response.status_code}: {response.text}",
+            status_code=response.status_code,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Sync client
+# ---------------------------------------------------------------------------
+
+class ManifestClient:
+    """Synchronous Manifest API client."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = _BASE_URL,
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        self._api_key = _resolve_api_key(api_key)
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.Client(timeout=timeout)
+
+    def get(self, url: str) -> Manifest:
+        """Fetch an action manifest for the given URL."""
+        response = self._client.post(
+            f"{self._base_url}/manifest",
+            json={"url": url},
+            headers=_headers(self._api_key),
+        )
+        _raise_for_status(response)
+        return Manifest._from_dict(response.json())
+
+    def health(self) -> dict:
+        """Check API health. Returns the raw JSON response."""
+        response = self._client.get(f"{self._base_url}/health")
+        _raise_for_status(response)
+        return response.json()
+
+    def session_valid(self) -> bool:
+        """Return True if the current session cookie is still valid."""
+        response = self._client.get(
+            f"{self._base_url}/session-status",
+            headers=_headers(self._api_key),
+        )
+        _raise_for_status(response)
+        return response.json().get("valid", False)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "ManifestClient":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+# ---------------------------------------------------------------------------
+# Async client
+# ---------------------------------------------------------------------------
+
+class AsyncManifestClient:
+    """Asynchronous Manifest API client."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = _BASE_URL,
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        self._api_key = _resolve_api_key(api_key)
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.AsyncClient(timeout=timeout)
+
+    async def get(self, url: str) -> Manifest:
+        """Fetch an action manifest for the given URL."""
+        response = await self._client.post(
+            f"{self._base_url}/manifest",
+            json={"url": url},
+            headers=_headers(self._api_key),
+        )
+        _raise_for_status(response)
+        return Manifest._from_dict(response.json())
+
+    async def health(self) -> dict:
+        """Check API health. Returns the raw JSON response."""
+        response = await self._client.get(f"{self._base_url}/health")
+        _raise_for_status(response)
+        return response.json()
+
+    async def session_valid(self) -> bool:
+        """Return True if the current session cookie is still valid."""
+        response = await self._client.get(
+            f"{self._base_url}/session-status",
+            headers=_headers(self._api_key),
+        )
+        _raise_for_status(response)
+        return response.json().get("valid", False)
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncManifestClient":
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.close()

manifest_api-0.1.0.dist-info/METADATA

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: manifest-api
+Version: 0.1.0
+Summary: Python SDK for the Manifest API — structured action manifests for AI agents
+Project-URL: Homepage, https://omfang.io/docs
+Project-URL: Repository, https://github.com/omfang/manifest-api
+Project-URL: Bug Tracker, https://github.com/omfang/manifest-api/issues
+Author-email: Omfang AB <hello@omfang.io>
+License: MIT
+Keywords: agents,ai,automation,browser,manifest,web
+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.9
+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: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# manifest-api
+
+Python SDK for the [Manifest API](https://omfang.io/docs) — extracts structured action manifests from web pages so AI agents know *what they can do*, not just what's on screen.
+
+## Install
+
+```bash
+pip install manifest-api
+```
+
+## Quickstart
+
+### Sync
+
+```python
+from manifest_api import ManifestClient
+
+client = ManifestClient(api_key="your-key")  # or set MANIFEST_API_KEY env var
+manifest = client.get("https://example.com")
+
+print(manifest.current_page_state)
+print(manifest.actions)
+
+# Convenience helpers
+action = manifest.action("submit-form")
+inputs = manifest.actions_of_type("input")
+required = manifest.required_actions
+```
+
+### Async
+
+```python
+import asyncio
+from manifest_api import AsyncManifestClient
+
+async def main():
+    async with AsyncManifestClient(api_key="your-key") as client:
+        manifest = await client.get("https://example.com")
+        print(manifest.current_page_state)
+
+asyncio.run(main())
+```
+
+## All methods
+
+```python
+# Both ManifestClient and AsyncManifestClient expose:
+manifest = client.get("https://example.com")   # POST /manifest → Manifest
+health   = client.health()                      # GET  /health → dict
+valid    = client.session_valid()               # GET  /session-status → bool
+```
+
+## Manifest helpers
+
+```python
+manifest.action("id")              # → Action | None
+manifest.actions_of_type("input")  # → list[Action]
+manifest.required_actions          # → list[Action]
+```
+
+## Action types
+
+`button` · `input` · `textarea` · `select` · `checkbox` · `radio` · `other`
+
+## Error handling
+
+```python
+from manifest_api import AuthenticationError, RateLimitError, APIError
+
+try:
+    manifest = client.get("https://example.com")
+except AuthenticationError:
+    print("Check your API key")
+except RateLimitError:
+    print("Slow down — rate limit hit")
+except APIError as e:
+    print(f"Server error {e.status_code}")
+```
+
+## Docs
+
+[https://omfang.io/docs](https://omfang.io/docs)

manifest_api-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+manifest_api/__init__.py,sha256=iXoIEdeApwl1H7KCSo4VoVBGPK-8IyL7UjxBPkNqmcg,480
+manifest_api/client.py,sha256=MpTr-dxBcWlmFKfoVKZAQ-pk2sfUJSRj5Q-543ZWyuc,7323
+manifest_api-0.1.0.dist-info/METADATA,sha256=7wEIulFMPCYjxVAKHrcIwg5AU_3pJNVb-GCqstqvys8,3233
+manifest_api-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+manifest_api-0.1.0.dist-info/RECORD,,

manifest_api-0.1.0.dist-info/WHEEL

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