vertodigital 0.2.0__tar.gz

vertodigital-0.2.0/LICENSE.txt

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

vertodigital-0.2.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: vertodigital
+Version: 0.2.0
+Summary: Python client for VertoDigital's public agent API.
+Author-email: VertoDigital <team@vertodigital.com>
+License-Expression: MIT
+Project-URL: Homepage, https://vertodigital.com
+Project-URL: Documentation, https://vertodigital.com/developers
+Project-URL: Changelog, https://pypi.org/project/vertodigital/#history
+Keywords: vertodigital,api,sdk,agent,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Dynamic: license-file
+
+# vertodigital
+
+Official Python client for [VertoDigital's public agent API](https://vertodigital.com/developers). Every endpoint is anonymous, so there's no API key to set up. No runtime dependencies, just the Python standard library.
+
+## Install
+
+```
+pip install vertodigital
+```
+
+## Usage
+
+```python
+from vertodigital import Client
+
+client = Client()
+
+client.health()
+# {'status': 'ok', 'service': 'vertodigital-agent-api', ...}
+
+# One page of case studies
+page = client.case_studies(limit=10)
+for cs in page["items"]:
+    print(f'{cs["name"]}: {cs["stat"]}')
+
+# Or every case study, paginated for you
+urls = [cs["url"] for cs in client.iter_case_studies()]
+
+# Any page on vertodigital.com as markdown
+print(client.page("about"))
+print(client.llms_txt())
+
+# The OpenAPI 3.1 spec
+list(client.openapi()["paths"])
+
+# Submit a contact enquiry on behalf of a user
+client.contact(
+    from_name="Ada Lovelace",
+    from_email="ada@example.com",
+    organization="Analytical Engines Ltd",
+    topic="services",  # assessment, services, partnership, press, careers, general
+    message="We'd like to discuss a marketing analytics engagement.",
+)
+```
+
+`contact` sends an `Idempotency-Key` automatically. If you retry after a timeout, pass the same `idempotency_key=` again so the enquiry is only recorded once.
+
+Requests go to the pinned `/agent/v1/*` paths by default. Pass `api_version=None` to use the unversioned `/agent/*` paths.
+
+## Errors
+
+- `vertodigital.APIError` for any non-2xx response. It carries `status` and `body`.
+- `vertodigital.RateLimitError` (a subclass) on 429. It adds `retry_after` in seconds.
+- `vertodigital.ValidationError` when input fails validation before a request is sent.
+
+All three inherit from `vertodigital.VertoDigitalError`. Rate limits and the full API reference are at [vertodigital.com/developers](https://vertodigital.com/developers).
+
+## Changelog
+
+- **0.2.0** - Requires Python 3.11 or later (3.8, 3.9 and 3.10 have reached end of life). No API changes.
+- **0.1.0** - First release: `health`, `case_studies` / `iter_case_studies`, `contact`, `openapi`, `llms_txt`, `page`.
+
+## Publishing (maintainers)
+
+From this directory:
+
+```
+python3 -m pip install --upgrade build twine
+python3 -m build
+python3 -m twine upload dist/*
+```
+
+Bump `__version__` in `src/vertodigital/_version.py` and add a changelog entry on every release. Upload with a PyPI API token (username `__token__`).

vertodigital-0.2.0/README.md

@@ -0,0 +1,73 @@
+# vertodigital
+
+Official Python client for [VertoDigital's public agent API](https://vertodigital.com/developers). Every endpoint is anonymous, so there's no API key to set up. No runtime dependencies, just the Python standard library.
+
+## Install
+
+```
+pip install vertodigital
+```
+
+## Usage
+
+```python
+from vertodigital import Client
+
+client = Client()
+
+client.health()
+# {'status': 'ok', 'service': 'vertodigital-agent-api', ...}
+
+# One page of case studies
+page = client.case_studies(limit=10)
+for cs in page["items"]:
+    print(f'{cs["name"]}: {cs["stat"]}')
+
+# Or every case study, paginated for you
+urls = [cs["url"] for cs in client.iter_case_studies()]
+
+# Any page on vertodigital.com as markdown
+print(client.page("about"))
+print(client.llms_txt())
+
+# The OpenAPI 3.1 spec
+list(client.openapi()["paths"])
+
+# Submit a contact enquiry on behalf of a user
+client.contact(
+    from_name="Ada Lovelace",
+    from_email="ada@example.com",
+    organization="Analytical Engines Ltd",
+    topic="services",  # assessment, services, partnership, press, careers, general
+    message="We'd like to discuss a marketing analytics engagement.",
+)
+```
+
+`contact` sends an `Idempotency-Key` automatically. If you retry after a timeout, pass the same `idempotency_key=` again so the enquiry is only recorded once.
+
+Requests go to the pinned `/agent/v1/*` paths by default. Pass `api_version=None` to use the unversioned `/agent/*` paths.
+
+## Errors
+
+- `vertodigital.APIError` for any non-2xx response. It carries `status` and `body`.
+- `vertodigital.RateLimitError` (a subclass) on 429. It adds `retry_after` in seconds.
+- `vertodigital.ValidationError` when input fails validation before a request is sent.
+
+All three inherit from `vertodigital.VertoDigitalError`. Rate limits and the full API reference are at [vertodigital.com/developers](https://vertodigital.com/developers).
+
+## Changelog
+
+- **0.2.0** - Requires Python 3.11 or later (3.8, 3.9 and 3.10 have reached end of life). No API changes.
+- **0.1.0** - First release: `health`, `case_studies` / `iter_case_studies`, `contact`, `openapi`, `llms_txt`, `page`.
+
+## Publishing (maintainers)
+
+From this directory:
+
+```
+python3 -m pip install --upgrade build twine
+python3 -m build
+python3 -m twine upload dist/*
+```
+
+Bump `__version__` in `src/vertodigital/_version.py` and add a changelog entry on every release. Upload with a PyPI API token (username `__token__`).

vertodigital-0.2.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vertodigital"
+dynamic = ["version"]
+description = "Python client for VertoDigital's public agent API."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE.txt"]
+authors = [{ name = "VertoDigital", email = "team@vertodigital.com" }]
+requires-python = ">=3.11"
+keywords = ["vertodigital", "api", "sdk", "agent", "mcp"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://vertodigital.com"
+Documentation = "https://vertodigital.com/developers"
+Changelog = "https://pypi.org/project/vertodigital/#history"
+
+[tool.setuptools.dynamic]
+version = { attr = "vertodigital._version.__version__" }
+
+[tool.setuptools.package-data]
+vertodigital = ["py.typed"]

vertodigital-0.2.0/setup.cfg

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

vertodigital-0.2.0/src/vertodigital/__init__.py

@@ -0,0 +1,7 @@
+"""Python client for VertoDigital's public agent API. See https://vertodigital.com/developers."""
+
+from ._version import __version__
+from .client import Client
+from .errors import APIError, RateLimitError, ValidationError, VertoDigitalError
+
+__all__ = ["Client", "APIError", "RateLimitError", "ValidationError", "VertoDigitalError", "__version__"]

vertodigital-0.2.0/src/vertodigital/_version.py

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

vertodigital-0.2.0/src/vertodigital/client.py

@@ -0,0 +1,158 @@
+"""Client for VertoDigital's public agent API (https://vertodigital.com/developers).
+
+Every endpoint is anonymous - no API key needed.
+"""
+
+import json
+import re
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from typing import Any, Dict, Iterator, Optional
+
+from ._version import __version__
+from .errors import APIError, RateLimitError, ValidationError
+
+DEFAULT_BASE_URL = "https://vertodigital.com"
+TOPICS = ("assessment", "services", "partnership", "press", "careers", "general")
+
+
+class Client:
+    """VertoDigital agent API client.
+
+    base_url    - override for testing against a staging deploy.
+    timeout     - request timeout in seconds.
+    api_version - "v1" pins requests to /agent/v1/*; None uses the unversioned /agent/* paths.
+    """
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 15,
+        api_version: Optional[str] = "v1",
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._prefix = f"/agent/{api_version}" if api_version else "/agent"
+
+    def health(self) -> Dict[str, Any]:
+        """GET /agent/v1/health - service status and endpoint map."""
+        return self._request("GET", f"{self._prefix}/health")
+
+    def case_studies(self, limit: Optional[int] = None, cursor: Optional[str] = None) -> Dict[str, Any]:
+        """GET /agent/v1/case-studies - one page of case studies.
+
+        Returns the raw page: {"items": [...], "count", "total", "has_more", "next_cursor"}.
+        """
+        query = {}
+        if limit is not None:
+            query["limit"] = limit
+        if cursor is not None:
+            query["cursor"] = cursor
+        return self._request("GET", f"{self._prefix}/case-studies", query=query)
+
+    def iter_case_studies(self, limit: int = 50) -> Iterator[Dict[str, Any]]:
+        """Yield every case study across all pages."""
+        cursor = None
+        while True:
+            page = self.case_studies(limit=limit, cursor=cursor)
+            yield from page.get("items", [])
+            if not (page.get("has_more") and page.get("next_cursor")):
+                return
+            cursor = page["next_cursor"]
+
+    def contact(
+        self,
+        from_name: str,
+        from_email: str,
+        message: str,
+        organization: Optional[str] = None,
+        topic: str = "general",
+        agent_id: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """POST /agent/v1/contact - submit a contact enquiry on behalf of a user.
+
+        A fresh Idempotency-Key is generated unless you pass one; reuse the same
+        key when retrying so a timeout never produces a duplicate enquiry.
+        """
+        if topic not in TOPICS:
+            raise ValidationError(f"topic must be one of: {', '.join(TOPICS)}")
+        if len(message.strip()) < 10:
+            raise ValidationError("message must be at least 10 characters")
+
+        body: Dict[str, Any] = {
+            "fromName": from_name,
+            "fromEmail": from_email,
+            "message": message,
+            "topic": topic,
+        }
+        if organization is not None:
+            body["organization"] = organization
+        if agent_id is not None:
+            body["agentId"] = agent_id
+        return self._request(
+            "POST",
+            f"{self._prefix}/contact",
+            body=body,
+            headers={"Idempotency-Key": idempotency_key or str(uuid.uuid4())},
+        )
+
+    def openapi(self) -> Dict[str, Any]:
+        """The OpenAPI 3.1 spec, parsed."""
+        return self._request("GET", "/agent/openapi.json")
+
+    def llms_txt(self) -> str:
+        """/llms.txt - the site's page index, as markdown text."""
+        return self._request("GET", "/llms.txt", raw=True)
+
+    def page(self, slug: str) -> str:
+        """Any page's markdown mirror, e.g. page("about") or page("case-studies/cloudflare-enterprise")."""
+        clean = re.sub(r"\.md$", "", slug.lstrip("/"))
+        if not clean:
+            raise ValidationError("slug is required")
+        return self._request("GET", f"/markdown/{clean}.md", raw=True)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        query: Optional[Dict[str, Any]] = None,
+        body: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        raw: bool = False,
+    ) -> Any:
+        url = f"{self.base_url}{path}"
+        if query:
+            url = f"{url}?{urllib.parse.urlencode(query)}"
+
+        req = urllib.request.Request(url, method=method)
+        req.add_header("User-Agent", f"vertodigital-python/{__version__}")
+        req.add_header("Accept", "text/markdown, text/plain" if raw else "application/json")
+        for key, value in (headers or {}).items():
+            req.add_header(key, value)
+        data = None
+        if body is not None:
+            req.add_header("Content-Type", "application/json")
+            data = json.dumps(body).encode("utf-8")
+
+        try:
+            with urllib.request.urlopen(req, data=data, timeout=self.timeout) as res:
+                text = res.read().decode("utf-8")
+        except urllib.error.HTTPError as err:
+            text = err.read().decode("utf-8", errors="replace")
+            try:
+                parsed: Any = json.loads(text)
+            except ValueError:
+                parsed = text
+            if err.code == 429:
+                retry_after = err.headers.get("Retry-After")
+                raise RateLimitError(
+                    err.code, parsed, path, int(retry_after) if retry_after and retry_after.isdigit() else None
+                ) from None
+            raise APIError(err.code, parsed, path) from None
+
+        if raw:
+            return text
+        return json.loads(text) if text else {}

vertodigital-0.2.0/src/vertodigital/errors.py

@@ -0,0 +1,40 @@
+"""Exceptions raised by the vertodigital client."""
+
+from typing import Any, Optional
+
+
+class VertoDigitalError(Exception):
+    """Base class for everything this package raises."""
+
+
+class ValidationError(VertoDigitalError, ValueError):
+    """An argument failed validation before any request was sent."""
+
+
+class APIError(VertoDigitalError):
+    """Any non-2xx response.
+
+    ``status`` is the HTTP status code; ``body`` is the parsed JSON error body
+    when there is one, otherwise the raw text.
+    """
+
+    def __init__(self, status: int, body: Any, path: str) -> None:
+        self.status = status
+        self.body = body
+        self.path = path
+        detail = ""
+        if isinstance(body, dict):
+            message = body.get("error") or body.get("message")
+            if isinstance(message, dict):
+                message = message.get("message", message)
+            if message:
+                detail = f": {message}"
+        super().__init__(f"{status} from {path}{detail}")
+
+
+class RateLimitError(APIError):
+    """A 429 response. ``retry_after`` is the wait in seconds, when the API sends Retry-After."""
+
+    def __init__(self, status: int, body: Any, path: str, retry_after: Optional[int]) -> None:
+        self.retry_after = retry_after
+        super().__init__(status, body, path)

vertodigital-0.2.0/src/vertodigital.egg-info/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: vertodigital
+Version: 0.2.0
+Summary: Python client for VertoDigital's public agent API.
+Author-email: VertoDigital <team@vertodigital.com>
+License-Expression: MIT
+Project-URL: Homepage, https://vertodigital.com
+Project-URL: Documentation, https://vertodigital.com/developers
+Project-URL: Changelog, https://pypi.org/project/vertodigital/#history
+Keywords: vertodigital,api,sdk,agent,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Dynamic: license-file
+
+# vertodigital
+
+Official Python client for [VertoDigital's public agent API](https://vertodigital.com/developers). Every endpoint is anonymous, so there's no API key to set up. No runtime dependencies, just the Python standard library.
+
+## Install
+
+```
+pip install vertodigital
+```
+
+## Usage
+
+```python
+from vertodigital import Client
+
+client = Client()
+
+client.health()
+# {'status': 'ok', 'service': 'vertodigital-agent-api', ...}
+
+# One page of case studies
+page = client.case_studies(limit=10)
+for cs in page["items"]:
+    print(f'{cs["name"]}: {cs["stat"]}')
+
+# Or every case study, paginated for you
+urls = [cs["url"] for cs in client.iter_case_studies()]
+
+# Any page on vertodigital.com as markdown
+print(client.page("about"))
+print(client.llms_txt())
+
+# The OpenAPI 3.1 spec
+list(client.openapi()["paths"])
+
+# Submit a contact enquiry on behalf of a user
+client.contact(
+    from_name="Ada Lovelace",
+    from_email="ada@example.com",
+    organization="Analytical Engines Ltd",
+    topic="services",  # assessment, services, partnership, press, careers, general
+    message="We'd like to discuss a marketing analytics engagement.",
+)
+```
+
+`contact` sends an `Idempotency-Key` automatically. If you retry after a timeout, pass the same `idempotency_key=` again so the enquiry is only recorded once.
+
+Requests go to the pinned `/agent/v1/*` paths by default. Pass `api_version=None` to use the unversioned `/agent/*` paths.
+
+## Errors
+
+- `vertodigital.APIError` for any non-2xx response. It carries `status` and `body`.
+- `vertodigital.RateLimitError` (a subclass) on 429. It adds `retry_after` in seconds.
+- `vertodigital.ValidationError` when input fails validation before a request is sent.
+
+All three inherit from `vertodigital.VertoDigitalError`. Rate limits and the full API reference are at [vertodigital.com/developers](https://vertodigital.com/developers).
+
+## Changelog
+
+- **0.2.0** - Requires Python 3.11 or later (3.8, 3.9 and 3.10 have reached end of life). No API changes.
+- **0.1.0** - First release: `health`, `case_studies` / `iter_case_studies`, `contact`, `openapi`, `llms_txt`, `page`.
+
+## Publishing (maintainers)
+
+From this directory:
+
+```
+python3 -m pip install --upgrade build twine
+python3 -m build
+python3 -m twine upload dist/*
+```
+
+Bump `__version__` in `src/vertodigital/_version.py` and add a changelog entry on every release. Upload with a PyPI API token (username `__token__`).

vertodigital-0.2.0/src/vertodigital.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE.txt
+README.md
+pyproject.toml
+src/vertodigital/__init__.py
+src/vertodigital/_version.py
+src/vertodigital/client.py
+src/vertodigital/errors.py
+src/vertodigital/py.typed
+src/vertodigital.egg-info/PKG-INFO
+src/vertodigital.egg-info/SOURCES.txt
+src/vertodigital.egg-info/dependency_links.txt
+src/vertodigital.egg-info/top_level.txt

vertodigital-0.2.0/src/vertodigital.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

vertodigital-0.2.0/src/vertodigital.egg-info/top_level.txt

@@ -0,0 +1 @@
+vertodigital