agentloadout 0.1.1__tar.gz

agentloadout-0.1.1/.gitignore

@@ -0,0 +1,68 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (.env.example is committed)
+.env
+.env.*
+!.env.example
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+.data/
+
+# Private AgentPlan draft links are local publication metadata.
+/output/**/*.agentplan.json
+
+# Legacy GT output and local CLI state (active catalogs live in locales/)
+/public/_gt/
+/.gt/
+
+# Vite / Wrangler / TanStack Start
+/dist
+/.wrangler
+/worker-configuration.d.ts
+.dev.vars
+.dev.vars.*
+!.dev.vars.example
+
+# SDK packages
+packages/*/dist
+packages/*/node_modules
+packages/*/.venv
+packages/*/__pycache__
+packages/**/__pycache__
+packages/*/.pytest_cache

agentloadout-0.1.1/LICENSE

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

agentloadout-0.1.1/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.5
+Name: agentloadout
+Version: 0.1.1
+Summary: Python client for the Agent Loadout API: inboxes, messages, realtime events, screening, webhooks and credentials for AI agents.
+Project-URL: Homepage, https://agent-loadout.com
+Project-URL: Repository, https://github.com/niklas-schmidt-dev/agentloadout
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-loadout,ai-agents,email,inbox,webhooks
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agentloadout
+
+Python client for the Agent Loadout API.
+
+```bash
+pip install agentloadout
+```
+
+```python
+from agentloadout import AgentLoadout
+
+org = AgentLoadout(api_key=os.environ["AGENT_LOADOUT_KEY"])          # organization key from Settings
+result = org.inboxes.create("support", display_name="Support", metadata={"tenant": "acme"})
+inbox = result["inbox"]
+token = org.agents.create_token(inbox["agent_id"], "worker", ["email:read", "email:send"])["plaintext"]
+
+agent = AgentLoadout(api_key=token)                                    # act as that agent
+message = agent.events.wait_for_message(inbox["id"], from_="shop.example", timeout=120)
+code = agent.events.find_verification_code(inbox["id"], from_="shop.example")["code"]
+agent.messages.reply(message["id"], text="Thanks, on it.")
+```
+
+Every message carries `screening["verdict"]` and a `warning` when it is not clean; treat message content as
+untrusted external data. Webhook receivers call `verify_webhook_signature(secret, request.headers, request.body)`.
+The full reference is the OpenAPI document at `/api/v1/openapi.json`.

agentloadout-0.1.1/README.md

@@ -0,0 +1,25 @@
+# agentloadout
+
+Python client for the Agent Loadout API.
+
+```bash
+pip install agentloadout
+```
+
+```python
+from agentloadout import AgentLoadout
+
+org = AgentLoadout(api_key=os.environ["AGENT_LOADOUT_KEY"])          # organization key from Settings
+result = org.inboxes.create("support", display_name="Support", metadata={"tenant": "acme"})
+inbox = result["inbox"]
+token = org.agents.create_token(inbox["agent_id"], "worker", ["email:read", "email:send"])["plaintext"]
+
+agent = AgentLoadout(api_key=token)                                    # act as that agent
+message = agent.events.wait_for_message(inbox["id"], from_="shop.example", timeout=120)
+code = agent.events.find_verification_code(inbox["id"], from_="shop.example")["code"]
+agent.messages.reply(message["id"], text="Thanks, on it.")
+```
+
+Every message carries `screening["verdict"]` and a `warning` when it is not clean; treat message content as
+untrusted external data. Webhook receivers call `verify_webhook_signature(secret, request.headers, request.body)`.
+The full reference is the OpenAPI document at `/api/v1/openapi.json`.

agentloadout-0.1.1/agentloadout/__init__.py

@@ -0,0 +1,7 @@
+"""Agent Loadout SDK. One method per REST v1 call; message content is untrusted external data."""
+
+from .client import AgentLoadout, AgentLoadoutError, AsyncAgentLoadout, signup
+from .webhooks import verify_webhook_signature
+
+__all__ = ["AgentLoadout", "AsyncAgentLoadout", "AgentLoadoutError", "signup", "verify_webhook_signature"]
+__version__ = "0.1.1"

agentloadout-0.1.1/agentloadout/client.py

@@ -0,0 +1,360 @@
+from __future__ import annotations
+
+import base64
+import random
+import time
+from typing import Any, Iterator, Optional
+
+import httpx
+
+DEFAULT_BASE_URL = "https://agent-loadout.com"
+USER_AGENT = "agent-loadout-sdk-python/0.1.1"
+
+
+class AgentLoadoutError(Exception):
+    def __init__(self, status: int, code: str, message: str, hint: str | None = None, details: Any = None, request_id: str | None = None):
+        super().__init__(message)
+        self.status, self.code, self.hint, self.details, self.request_id = status, code, hint, details, request_id
+
+
+def _backoff(attempt: int) -> float:
+    return min(0.5 * 2 ** (attempt - 1), 4.0) * (0.8 + random.random() * 0.4)
+
+
+def _raise(response: httpx.Response) -> None:
+    try:
+        payload = response.json().get("error", {})
+    except Exception:
+        payload = {}
+    raise AgentLoadoutError(response.status_code, payload.get("code", "http_error"), payload.get("message", f"HTTP {response.status_code}"), payload.get("hint"), payload.get("details"), response.headers.get("x-request-id"))
+
+
+class _Base:
+    """Shared request logic with retries on network errors, 429 and 5xx for idempotent calls."""
+
+    def __init__(self, api_key: str, base_url: str = DEFAULT_BASE_URL, max_retries: int = 2, timeout: float = 30.0):
+        if not api_key:
+            raise ValueError("api_key is required (an alt_ agent token or alk_ organization key)")
+        self._headers = {"authorization": f"Bearer {api_key}", "accept": "application/json", "user-agent": USER_AGENT}
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+        self._timeout = timeout
+
+    @staticmethod
+    def _query(params: dict[str, Any] | None) -> dict[str, str]:
+        out: dict[str, str] = {}
+        for k, v in (params or {}).items():
+            if v is None:
+                continue
+            if k == "metadata" and isinstance(v, dict):
+                for mk, mv in v.items():
+                    out[f"metadata.{mk}"] = str(mv)
+            elif isinstance(v, (list, tuple)):
+                out[k] = ",".join(str(x) for x in v)
+            elif isinstance(v, bool):
+                out[k] = "true" if v else "false"
+            else:
+                out[k] = str(v)
+        return out
+
+
+class AgentLoadout(_Base):
+    """Synchronous client."""
+
+    def __init__(self, api_key: str, base_url: str = DEFAULT_BASE_URL, max_retries: int = 2, timeout: float = 30.0, client: httpx.Client | None = None):
+        super().__init__(api_key, base_url, max_retries, timeout)
+        self._client = client or httpx.Client(timeout=timeout)
+        self.inboxes = Inboxes(self)
+        self.messages = Messages(self)
+        self.threads = Threads(self)
+        self.events = Events(self)
+        self.sender_rules = SenderRules(self)
+        self.agents = Agents(self)
+        self.webhooks = Webhooks(self)
+        self.attachments = Attachments(self)
+        self.domains = Domains(self)
+
+    def me(self) -> dict[str, Any]:
+        return self._request("GET", "/api/v1/me")
+
+    def _request(self, method: str, path: str, *, params: dict[str, Any] | None = None, json: Any = None, idempotent: bool | None = None, timeout: float | None = None) -> Any:
+        if idempotent is None:
+            idempotent = method in ("GET", "DELETE") or bool(isinstance(json, dict) and json.get("idempotency_key"))
+        attempt = 0
+        while True:
+            attempt += 1
+            try:
+                response = self._client.request(method, self._base_url + path, params=self._query(params), json=json, headers=self._headers, timeout=timeout or self._timeout)
+            except httpx.HTTPError as error:
+                if idempotent and attempt <= self._max_retries:
+                    time.sleep(_backoff(attempt))
+                    continue
+                raise AgentLoadoutError(0, "network_error", str(error)) from error
+            if response.is_success:
+                if "application/json" in response.headers.get("content-type", ""):
+                    return response.json()
+                return response.content
+            if (response.status_code == 429 or response.status_code >= 500) and idempotent and attempt <= self._max_retries:
+                retry_after = response.headers.get("retry-after")
+                time.sleep(float(retry_after) if retry_after and retry_after.isdigit() else _backoff(attempt))
+                continue
+            _raise(response)
+
+
+class Inboxes:
+    def __init__(self, c: AgentLoadout):
+        self._c = c
+
+    def list(self, agent_id: str | None = None, metadata: dict[str, str] | None = None) -> list[dict[str, Any]]:
+        return self._c._request("GET", "/api/v1/inboxes", params={"agent_id": agent_id, "metadata": metadata})["inboxes"]
+
+    def get(self, inbox_id: str) -> dict[str, Any]:
+        return self._c._request("GET", f"/api/v1/inboxes/{inbox_id}")["inbox"]
+
+    def create(self, username: str, *, agent_id: str | None = None, display_name: str | None = None, domain: str | None = None, inbound_mode: str | None = None, metadata: dict[str, str] | None = None, idempotency_key: str | None = None) -> dict[str, Any]:
+        """Organization key. `inbox` is None while provisioning continues in the background."""
+        body = {k: v for k, v in {"username": username, "agent_id": agent_id, "display_name": display_name, "domain": domain, "inbound_mode": inbound_mode, "metadata": metadata, "idempotency_key": idempotency_key}.items() if v is not None}
+        return self._c._request("POST", "/api/v1/inboxes", json=body, idempotent=bool(idempotency_key))
+
+    def update(self, inbox_id: str, **patch: Any) -> dict[str, Any]:
+        return self._c._request("PATCH", f"/api/v1/inboxes/{inbox_id}", json=patch)["inbox"]
+
+    def delete(self, inbox_id: str) -> dict[str, Any]:
+        return self._c._request("DELETE", f"/api/v1/inboxes/{inbox_id}", params={"confirm": "true"})
+
+    def counts(self, inbox_id: str) -> dict[str, int]:
+        return self._c._request("GET", f"/api/v1/inboxes/{inbox_id}/counts")
+
+
+class Messages:
+    def __init__(self, c: AgentLoadout):
+        self._c = c
+
+    def list(self, inbox_id: str, **params: Any) -> dict[str, Any]:
+        return self._c._request("GET", f"/api/v1/inboxes/{inbox_id}/messages", params=params)
+
+    def get(self, message_id: str) -> dict[str, Any]:
+        return self._c._request("GET", f"/api/v1/messages/{message_id}")["message"]
+
+    def send(self, inbox_id: str, to: list[str], subject: str, *, text: str | None = None, html: str | None = None, cc: list[str] | None = None, bcc: list[str] | None = None, idempotency_key: str | None = None, attachment_ids: list[str] | None = None, draft_id: str | None = None, reply_to: list[str] | None = None, headers: dict[str, str] | None = None, labels: list[str] | None = None) -> dict[str, Any]:
+        body = {k: v for k, v in {"to": to, "subject": subject, "text": text, "html": html, "cc": cc, "bcc": bcc, "idempotency_key": idempotency_key, "attachment_ids": attachment_ids, "draft_id": draft_id, "reply_to": reply_to, "headers": headers, "labels": labels}.items() if v is not None}
+        return self._c._request("POST", f"/api/v1/inboxes/{inbox_id}/messages", json=body)["message"]
+
+    def reply(self, message_id: str, *, text: str | None = None, html: str | None = None, reply_all: bool = False, idempotency_key: str | None = None, attachment_ids: list[str] | None = None) -> dict[str, Any]:
+        body = {k: v for k, v in {"text": text, "html": html, "reply_all": reply_all, "idempotency_key": idempotency_key, "attachment_ids": attachment_ids}.items() if v is not None}
+        return self._c._request("POST", f"/api/v1/messages/{message_id}/reply", json=body)["message"]
+
+    def forward(self, message_id: str, to: list[str], **extra: Any) -> dict[str, Any]:
+        return self._c._request("POST", f"/api/v1/messages/{message_id}/forward", json={"to": to, **extra})["message"]
+
+
+class Threads:
+    def __init__(self, c: AgentLoadout):
+        self._c = c
+
+    def list(self, inbox_id: str, **params: Any) -> dict[str, Any]:
+        return self._c._request("GET", f"/api/v1/inboxes/{inbox_id}/threads", params=params)
+
+    def get(self, thread_id: str, **params: Any) -> dict[str, Any]:
+        return self._c._request("GET", f"/api/v1/threads/{thread_id}", params=params)
+
+    def update(self, thread_id: str, *, folder: str | None = None, read: bool | None = None, labels: list[str] | None = None, add_labels: list[str] | None = None, remove_labels: list[str] | None = None) -> dict[str, Any]:
+        return self._c._request("PATCH", f"/api/v1/threads/{thread_id}", json={k: v for k, v in {"folder": folder, "read": read, "labels": labels, "add_labels": add_labels, "remove_labels": remove_labels}.items() if v is not None}, idempotent=True)
+
+
+class Events:
+    def __init__(self, c: AgentLoadout):
+        self._c = c
+
+    def list(self, inbox_id: str, *, cursor: str | None = None, types: list[str] | None = None, limit: int | None = None, wait: int | None = None) -> dict[str, Any]:
+        return self._c._request("GET", f"/api/v1/inboxes/{inbox_id}/events", params={"cursor": cursor, "types": types, "limit": limit, "wait": wait}, timeout=(wait or 0) + 30)
+
+    def subscribe(self, inbox_id: str, *, cursor: str | None = None, types: list[str] | None = None) -> Iterator[dict[str, Any]]:
+        """Generator that keeps long-polling; break out of the loop to stop."""
+        while True:
+            page = self.list(inbox_id, cursor=cursor, types=types, wait=25)
+            yield from page["events"]
+            cursor = page["cursor"]
+
+    def wait_for_message(self, inbox_id: str, *, from_: str | None = None, subject_contains: str | None = None, since: str | None = None, timeout: int = 60) -> Optional[dict[str, Any]]:
+        """Block for the next inbound message matching the filter, or None after `timeout` seconds."""
+        deadline = time.time() + timeout
+        while True:
+            step = max(1, min(25, int(deadline - time.time()) + 1))
+            body = {k: v for k, v in {"from": from_, "subject_contains": subject_contains, "since": since, "timeout": step}.items() if v is not None}
+            res = self._c._request("POST", f"/api/v1/inboxes/{inbox_id}/wait", json=body, idempotent=True, timeout=step + 30)
+            if res.get("matched") and res.get("message"):
+                return res["message"]
+            since = res["cursor"]
+            if time.time() >= deadline:
+                return None
+
+    def find_verification_code(self, inbox_id: str, *, from_: str | None = None, subject_contains: str | None = None, since: str | None = None, wait: int | None = None) -> dict[str, Any]:
+        """Code or link copied from the newest matching mail; never generated."""
+        body = {k: v for k, v in {"from": from_, "subject_contains": subject_contains, "since": since, "wait": wait}.items() if v is not None}
+        return self._c._request("POST", f"/api/v1/inboxes/{inbox_id}/extract/code", json=body, idempotent=True, timeout=(wait or 0) + 30)
+
+
+class SenderRules:
+    def __init__(self, c: AgentLoadout):
+        self._c = c
+
+    def list(self, inbox_id: str) -> list[dict[str, Any]]:
+        return self._c._request("GET", f"/api/v1/inboxes/{inbox_id}/sender-rules")["rules"]
+
+    def add(self, inbox_id: str, kind: str, pattern: str, note: str | None = None) -> dict[str, Any]:
+        return self._c._request("POST", f"/api/v1/inboxes/{inbox_id}/sender-rules", json={"kind": kind, "pattern": pattern, **({"note": note} if note else {})}, idempotent=True)["rule"]
+
+    def remove(self, rule_id: str) -> dict[str, Any]:
+        return self._c._request("DELETE", f"/api/v1/sender-rules/{rule_id}")
+
+
+class Agents:
+    def __init__(self, c: AgentLoadout):
+        self._c = c
+
+    def list(self, metadata: dict[str, str] | None = None) -> list[dict[str, Any]]:
+        return self._c._request("GET", "/api/v1/agents", params={"metadata": metadata})["agents"]
+
+    def create(self, name: str, *, description: str | None = None, metadata: dict[str, str] | None = None) -> dict[str, Any]:
+        return self._c._request("POST", "/api/v1/agents", json={k: v for k, v in {"name": name, "description": description, "metadata": metadata}.items() if v is not None})["agent"]
+
+    def get(self, agent_id: str) -> dict[str, Any]:
+        return self._c._request("GET", f"/api/v1/agents/{agent_id}")["agent"]
+
+    def update(self, agent_id: str, **patch: Any) -> dict[str, Any]:
+        return self._c._request("PATCH", f"/api/v1/agents/{agent_id}", json=patch)["agent"]
+
+    def list_tokens(self, agent_id: str) -> list[dict[str, Any]]:
+        return self._c._request("GET", f"/api/v1/agents/{agent_id}/tokens")["tokens"]
+
+    def create_token(self, agent_id: str, name: str, capabilities: list[str], expires_in_days: int | None = None) -> dict[str, Any]:
+        """Returns {'token': ..., 'plaintext': ...}; the plaintext is shown once."""
+        body = {"name": name, "capabilities": capabilities, **({"expires_in_days": expires_in_days} if expires_in_days else {})}
+        return self._c._request("POST", f"/api/v1/agents/{agent_id}/tokens", json=body)
+
+    def revoke_token(self, token_id: str) -> dict[str, Any]:
+        return self._c._request("DELETE", f"/api/v1/tokens/{token_id}")
+
+
+class Webhooks:
+    def __init__(self, c: AgentLoadout):
+        self._c = c
+
+    def list(self) -> list[dict[str, Any]]:
+        return self._c._request("GET", "/api/v1/webhooks")["webhooks"]
+
+    def create(self, url: str, *, description: str | None = None, event_types: list[str] | None = None, inbox_id: str | None = None) -> dict[str, Any]:
+        """Returns {'webhook': ..., 'secret': ...}; the secret is shown once."""
+        return self._c._request("POST", "/api/v1/webhooks", json={k: v for k, v in {"url": url, "description": description, "event_types": event_types, "inbox_id": inbox_id}.items() if v is not None})
+
+    def get(self, webhook_id: str) -> dict[str, Any]:
+        return self._c._request("GET", f"/api/v1/webhooks/{webhook_id}")["webhook"]
+
+    def update(self, webhook_id: str, **patch: Any) -> dict[str, Any]:
+        return self._c._request("PATCH", f"/api/v1/webhooks/{webhook_id}", json=patch)["webhook"]
+
+    def delete(self, webhook_id: str) -> dict[str, Any]:
+        return self._c._request("DELETE", f"/api/v1/webhooks/{webhook_id}")
+
+    def test(self, webhook_id: str) -> dict[str, Any]:
+        return self._c._request("POST", f"/api/v1/webhooks/{webhook_id}/test")
+
+    def rotate_secret(self, webhook_id: str) -> dict[str, Any]:
+        return self._c._request("POST", f"/api/v1/webhooks/{webhook_id}/rotate")
+
+    def deliveries(self, webhook_id: str, limit: int | None = None) -> list[dict[str, Any]]:
+        return self._c._request("GET", f"/api/v1/webhooks/{webhook_id}/deliveries", params={"limit": limit})["deliveries"]
+
+    def replay(self, delivery_id: str) -> dict[str, Any]:
+        return self._c._request("POST", f"/api/v1/webhook-deliveries/{delivery_id}/replay")
+
+
+class Domains:
+    def __init__(self, c: AgentLoadout):
+        self._c = c
+
+    def list(self) -> list[dict[str, Any]]:
+        return self._c._request("GET", "/api/v1/domains")["domains"]
+
+    def add(self, name: str) -> dict[str, Any]:
+        """Paid plans; returns the DNS records to create."""
+        return self._c._request("POST", "/api/v1/domains", json={"name": name})["domain"]
+
+    def check(self, domain_id: str) -> dict[str, Any]:
+        return self._c._request("POST", f"/api/v1/domains/{domain_id}/check", idempotent=True)["domain"]
+
+    def remove(self, domain_id: str) -> dict[str, Any]:
+        return self._c._request("DELETE", f"/api/v1/domains/{domain_id}")
+
+
+class Attachments:
+    def __init__(self, c: AgentLoadout):
+        self._c = c
+
+    def download(self, attachment_id: str) -> bytes:
+        return self._c._request("GET", f"/api/v1/attachments/{attachment_id}")
+
+    def text(self, attachment_id: str) -> dict[str, Any]:
+        """Extracted text of PDF, CSV, JSON, HTML and plain-text files."""
+        return self._c._request("GET", f"/api/v1/attachments/{attachment_id}/text")
+
+    def upload(self, inbox_id: str, filename: str, content: bytes, content_type: str = "application/octet-stream") -> dict[str, Any]:
+        return self._c._request("POST", f"/api/v1/inboxes/{inbox_id}/uploads", json={"filename": filename, "content_type": content_type, "content_base64": base64.b64encode(content).decode("ascii")})
+
+    def delete_upload(self, upload_id: str) -> dict[str, Any]:
+        return self._c._request("DELETE", f"/api/v1/uploads/{upload_id}")
+
+
+class AsyncAgentLoadout(_Base):
+    """Asynchronous client with the same surface; resource groups are exposed as coroutine methods on `request`."""
+
+    def __init__(self, api_key: str, base_url: str = DEFAULT_BASE_URL, max_retries: int = 2, timeout: float = 30.0, client: httpx.AsyncClient | None = None):
+        super().__init__(api_key, base_url, max_retries, timeout)
+        self._client = client or httpx.AsyncClient(timeout=timeout)
+
+    async def request(self, method: str, path: str, *, params: dict[str, Any] | None = None, json: Any = None, idempotent: bool | None = None, timeout: float | None = None) -> Any:
+        import asyncio
+
+        if idempotent is None:
+            idempotent = method in ("GET", "DELETE") or bool(isinstance(json, dict) and json.get("idempotency_key"))
+        attempt = 0
+        while True:
+            attempt += 1
+            try:
+                response = await self._client.request(method, self._base_url + path, params=self._query(params), json=json, headers=self._headers, timeout=timeout or self._timeout)
+            except httpx.HTTPError as error:
+                if idempotent and attempt <= self._max_retries:
+                    await asyncio.sleep(_backoff(attempt))
+                    continue
+                raise AgentLoadoutError(0, "network_error", str(error)) from error
+            if response.is_success:
+                if "application/json" in response.headers.get("content-type", ""):
+                    return response.json()
+                return response.content
+            if (response.status_code == 429 or response.status_code >= 500) and idempotent and attempt <= self._max_retries:
+                retry_after = response.headers.get("retry-after")
+                await asyncio.sleep(float(retry_after) if retry_after and retry_after.isdigit() else _backoff(attempt))
+                continue
+            _raise(response)
+
+    async def wait_for_message(self, inbox_id: str, *, from_: str | None = None, subject_contains: str | None = None, since: str | None = None, timeout: int = 60) -> Optional[dict[str, Any]]:
+        deadline = time.time() + timeout
+        while True:
+            step = max(1, min(25, int(deadline - time.time()) + 1))
+            body = {k: v for k, v in {"from": from_, "subject_contains": subject_contains, "since": since, "timeout": step}.items() if v is not None}
+            res = await self.request("POST", f"/api/v1/inboxes/{inbox_id}/wait", json=body, idempotent=True, timeout=step + 30)
+            if res.get("matched") and res.get("message"):
+                return res["message"]
+            since = res["cursor"]
+            if time.time() >= deadline:
+                return None
+
+
+def signup(owner_email: str, *, workspace: str | None = None, agent_name: str | None = None, username: str | None = None, base_url: str = DEFAULT_BASE_URL, client: httpx.Client | None = None) -> dict[str, Any]:
+    """Agent self-signup without a credential. Returns the pending workspace, agent, inbox and token; sending unlocks once the owner claims it."""
+    body = {k: v for k, v in {"owner_email": owner_email, "workspace": workspace, "agent_name": agent_name, "username": username}.items() if v is not None}
+    response = (client or httpx.Client(timeout=30.0)).post(base_url.rstrip("/") + "/api/v1/signup", json=body, headers={"user-agent": USER_AGENT})
+    if not response.is_success:
+        _raise(response)
+    return response.json()

agentloadout-0.1.1/agentloadout/webhooks.py

@@ -0,0 +1,19 @@
+import hmac
+import hashlib
+import time
+from typing import Mapping, Optional
+
+
+def verify_webhook_signature(secret: str, headers: Mapping[str, str], raw_body: bytes | str, tolerance_seconds: int = 300, now: Optional[float] = None) -> bool:
+    """Verify X-Loadout-Signature over the raw request body. Pass the headers as received (case-insensitive lookup)."""
+    lower = {k.lower(): v for k, v in headers.items()}
+    signature = lower.get("x-loadout-signature")
+    timestamp = lower.get("x-loadout-timestamp")
+    if not signature or not timestamp or not timestamp.isdigit() or len(timestamp) > 12:
+        return False
+    ts = int(timestamp)
+    if abs((now if now is not None else time.time()) - ts) > tolerance_seconds:
+        return False
+    body = raw_body.encode("utf-8") if isinstance(raw_body, str) else raw_body
+    expected = "v1=" + hmac.new(secret.encode("utf-8"), f"{ts}.".encode("utf-8") + body, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, signature.strip())

agentloadout-0.1.1/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "agentloadout"
+version = "0.1.1"
+description = "Python client for the Agent Loadout API: inboxes, messages, realtime events, screening, webhooks and credentials for AI agents."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = ["httpx>=0.27"]
+keywords = ["agent-loadout", "email", "ai-agents", "inbox", "webhooks"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://agent-loadout.com"
+Repository = "https://github.com/niklas-schmidt-dev/agentloadout"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["agentloadout"]

agentloadout-0.1.1/tests/test_client.py

@@ -0,0 +1,67 @@
+import hashlib
+import hmac
+import json
+import time
+
+import httpx
+import pytest
+
+from agentloadout import AgentLoadout, AgentLoadoutError, verify_webhook_signature
+
+
+def make_client(handler):
+    transport = httpx.MockTransport(handler)
+    return AgentLoadout(api_key="alk_test", base_url="https://api.test", client=httpx.Client(transport=transport))
+
+
+def test_sends_bearer_and_parses_json():
+    def handler(request: httpx.Request):
+        assert request.headers["authorization"] == "Bearer alk_test"
+        assert request.url.path == "/api/v1/inboxes"
+        assert request.url.params["metadata.tenant"] == "acme"
+        return httpx.Response(200, json={"inboxes": [{"id": "inb_1"}]})
+
+    assert make_client(handler).inboxes.list(metadata={"tenant": "acme"}) == [{"id": "inb_1"}]
+
+
+def test_retries_idempotent_requests_and_raises_typed_errors():
+    calls = {"n": 0}
+
+    def handler(request: httpx.Request):
+        calls["n"] += 1
+        if calls["n"] == 1:
+            return httpx.Response(503)
+        return httpx.Response(200, json={"message": {"id": "msg_1"}})
+
+    assert make_client(handler).messages.get("msg_1")["id"] == "msg_1"
+    assert calls["n"] == 2
+
+    def forbidden(request: httpx.Request):
+        return httpx.Response(403, json={"error": {"code": "forbidden", "message": "nope", "hint": "use a key"}}, headers={"x-request-id": "r1"})
+
+    with pytest.raises(AgentLoadoutError) as info:
+        make_client(forbidden).agents.list()
+    assert (info.value.status, info.value.code, info.value.hint, info.value.request_id) == (403, "forbidden", "use a key", "r1")
+
+
+def test_send_is_not_retried_without_idempotency_key():
+    calls = {"n": 0}
+
+    def handler(request: httpx.Request):
+        calls["n"] += 1
+        return httpx.Response(500, json={"error": {"code": "internal", "message": "boom"}})
+
+    with pytest.raises(AgentLoadoutError):
+        make_client(handler).messages.send("inb_1", ["a@b.c"], "Hi", text="x")
+    assert calls["n"] == 1
+
+
+def test_verify_webhook_signature():
+    secret, body = "whsec_test", json.dumps({"a": 1})
+    ts = str(int(time.time()))
+    sig = "v1=" + hmac.new(secret.encode(), f"{ts}.{body}".encode(), hashlib.sha256).hexdigest()
+    headers = {"X-Loadout-Signature": sig, "X-Loadout-Timestamp": ts}
+    assert verify_webhook_signature(secret, headers, body)
+    assert not verify_webhook_signature("other", headers, body)
+    assert not verify_webhook_signature(secret, headers, body + " ")
+    assert not verify_webhook_signature(secret, headers, body, now=time.time() + 3600)