wirebox 0.1.0__py3-none-any.whl

wirebox/__init__.py

@@ -0,0 +1,90 @@
+"""Wirebox — Real-world identity, communication, and context execution layer for AI agents.
+
+Official Python SDK providing synchronous and asynchronous interfaces to equip autonomous
+agents with dedicated phone numbers, email inboxes, network tunnels, and webhooks.
+"""
+
+from wirebox._version import __version__
+from wirebox.async_client import AsyncWirebox
+from wirebox.client import Wirebox
+from wirebox.exceptions import (
+    AuthenticationError,
+    FreeTierLimitExceededError,
+    HandleAlreadyTakenError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+    WireboxAPIError,
+    WireboxConnectionError,
+    WireboxError,
+)
+from wirebox.identity import AgentIdentity, AsyncAgentIdentity
+from wirebox.tunnels import TunnelSession
+from wirebox.types import (
+    EmailMessage,
+    IdentityData,
+    IdentityTunnelSummary,
+    MailboxSummary,
+    MessageAttachmentSummary,
+    MessageSummary,
+    SendEmailAttachment,
+    SendEmailResult,
+    Tunnel,
+    TunnelClientTelemetry,
+    Webhook,
+    WebhookCreateResult,
+    WebhookEventType,
+    WebhookRotateSecretResult,
+    WebhookStatus,
+    WebhookTestResult,
+    WhoamiApiKey,
+    WhoamiOrganization,
+    WhoamiResult,
+)
+from wirebox.verify_webhook import verify_webhook
+
+# Canonical aliases for cross-SDK naming consistency
+WireboxClient = Wirebox
+AsyncWireboxClient = AsyncWirebox
+
+__all__ = [
+    "__version__",
+    "Wirebox",
+    "WireboxClient",
+    "AsyncWirebox",
+    "AsyncWireboxClient",
+    "AgentIdentity",
+    "AsyncAgentIdentity",
+    "TunnelSession",
+    "verify_webhook",
+    # Exceptions
+    "WireboxError",
+    "WireboxAPIError",
+    "AuthenticationError",
+    "NotFoundError",
+    "RateLimitError",
+    "HandleAlreadyTakenError",
+    "FreeTierLimitExceededError",
+    "WireboxConnectionError",
+    "ValidationError",
+    # Types
+    "IdentityData",
+    "IdentityTunnelSummary",
+    "MailboxSummary",
+    "SendEmailAttachment",
+    "SendEmailResult",
+    "MessageAttachmentSummary",
+    "MessageSummary",
+    "EmailMessage",
+    "Tunnel",
+    "TunnelClientTelemetry",
+    "Webhook",
+    "WebhookCreateResult",
+    "WebhookTestResult",
+    "WebhookRotateSecretResult",
+    "WebhookEventType",
+    "WebhookStatus",
+    "WhoamiOrganization",
+    "WhoamiApiKey",
+    "WhoamiResult",
+]

wirebox/_http.py

@@ -0,0 +1,204 @@
+"""Wirebox Python SDK — HTTP Transport Layer.
+
+Provides unified synchronous and asynchronous HTTP transports built on httpx,
+handling authentication, connection pooling, timeouts, and error normalization.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from wirebox._version import __version__
+from wirebox.exceptions import WireboxConnectionError, parse_api_error
+
+DEFAULT_BASE_URL = "https://api.wirebox.sh"
+DEFAULT_TIMEOUT_SECONDS = 30.0
+
+
+def _build_headers(
+    api_key: str | None, custom_headers: Mapping[str, str] | None = None
+) -> dict[str, str]:
+    headers = {
+        "Accept": "application/json",
+        "User-Agent": f"wirebox-python/{__version__}",
+    }
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    if custom_headers:
+        headers.update(custom_headers)
+    return headers
+
+
+def _clean_params(params: Mapping[str, Any] | None) -> dict[str, Any] | None:
+    if not params:
+        return None
+    return {k: v for k, v in params.items() if v is not None}
+
+
+def _handle_response(resp: httpx.Response) -> Any:
+    request_id = resp.headers.get("x-wirebox-request-id") or resp.headers.get("x-request-id")
+
+    if resp.status_code == 204:
+        return None
+
+    content_type = resp.headers.get("content-type", "")
+    data: Any
+    if "application/json" in content_type:
+        try:
+            data = resp.json()
+        except Exception:
+            data = resp.text
+    else:
+        data = resp.text
+
+    if not resp.is_success:
+        raise parse_api_error(resp.status_code, data, request_id)
+
+    return data
+
+
+class SyncHttpTransport:
+    """Synchronous HTTP transport for Wirebox API communication."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        client: httpx.Client | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+        self._external_client = client is not None
+        self._client = client or httpx.Client(
+            base_url=self.base_url,
+            headers=_build_headers(api_key),
+            timeout=timeout,
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any = None,
+        headers: Mapping[str, str] | None = None,
+        timeout: float | None = None,
+    ) -> Any:
+        url = path if path.startswith("/") else f"/{path}"
+        try:
+            resp = self._client.request(
+                method,
+                url,
+                params=_clean_params(params),
+                json=json,
+                headers=dict(headers) if headers else None,
+                timeout=timeout or self.timeout,
+            )
+            return _handle_response(resp)
+        except httpx.TimeoutException as exc:
+            raise WireboxConnectionError(
+                f"Request timed out after {timeout or self.timeout}s: {exc}", exc
+            ) from exc
+        except httpx.NetworkError as exc:
+            raise WireboxConnectionError(f"Network connection failed: {exc}", exc) from exc
+
+    def get(self, path: str, *, params: Mapping[str, Any] | None = None, **kwargs: Any) -> Any:
+        return self.request("GET", path, params=params, **kwargs)
+
+    def post(self, path: str, *, json: Any = None, **kwargs: Any) -> Any:
+        return self.request("POST", path, json=json, **kwargs)
+
+    def patch(self, path: str, *, json: Any = None, **kwargs: Any) -> Any:
+        return self.request("PATCH", path, json=json, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> Any:
+        return self.request("DELETE", path, **kwargs)
+
+    def close(self) -> None:
+        if not self._external_client:
+            self._client.close()
+
+    def __enter__(self) -> SyncHttpTransport:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+class AsyncHttpTransport:
+    """Asynchronous HTTP transport for Wirebox API communication."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+        self._external_client = client is not None
+        self._client = client or httpx.AsyncClient(
+            base_url=self.base_url,
+            headers=_build_headers(api_key),
+            timeout=timeout,
+        )
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any = None,
+        headers: Mapping[str, str] | None = None,
+        timeout: float | None = None,
+    ) -> Any:
+        url = path if path.startswith("/") else f"/{path}"
+        try:
+            resp = await self._client.request(
+                method,
+                url,
+                params=_clean_params(params),
+                json=json,
+                headers=dict(headers) if headers else None,
+                timeout=timeout or self.timeout,
+            )
+            return _handle_response(resp)
+        except httpx.TimeoutException as exc:
+            raise WireboxConnectionError(
+                f"Request timed out after {timeout or self.timeout}s: {exc}", exc
+            ) from exc
+        except httpx.NetworkError as exc:
+            raise WireboxConnectionError(f"Network connection failed: {exc}", exc) from exc
+
+    async def get(
+        self, path: str, *, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.request("GET", path, params=params, **kwargs)
+
+    async def post(self, path: str, *, json: Any = None, **kwargs: Any) -> Any:
+        return await self.request("POST", path, json=json, **kwargs)
+
+    async def patch(self, path: str, *, json: Any = None, **kwargs: Any) -> Any:
+        return await self.request("PATCH", path, json=json, **kwargs)
+
+    async def delete(self, path: str, **kwargs: Any) -> Any:
+        return await self.request("DELETE", path, **kwargs)
+
+    async def aclose(self) -> None:
+        if not self._external_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncHttpTransport:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.aclose()

wirebox/_version.py

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

wirebox/async_client.py

@@ -0,0 +1,138 @@
+"""Wirebox Python SDK — Asynchronous Client.
+
+Main asynchronous entry point for interacting with the Wirebox Edge Core API.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Literal
+from urllib.parse import quote
+
+import httpx
+
+from wirebox._http import DEFAULT_BASE_URL, DEFAULT_TIMEOUT_SECONDS, AsyncHttpTransport
+from wirebox.identity import AsyncAgentIdentity
+from wirebox.mail import AsyncMailClient
+from wirebox.tunnels import AsyncTunnelsClient
+from wirebox.types import IdentityData, WhoamiResult
+from wirebox.webhooks import AsyncWebhooksClient
+
+
+class AsyncWirebox:
+    """Asynchronous client for the Wirebox API.
+
+    Example:
+        >>> from wirebox import AsyncWirebox
+        >>> async with AsyncWirebox(api_key="wb_live_...") as client:
+        ...     agent = await client.create_identity("sales-bot", display_name="Sales Bot")
+        ...     await agent.send_email(to="customer@example.com", subject="Hi", text="Hello!")
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        resolved_key = api_key or os.environ.get("WIREBOX_API_KEY")
+        resolved_url = base_url or os.environ.get("WIREBOX_BASE_URL") or DEFAULT_BASE_URL
+
+        self._api_key = resolved_key
+        self._base_url = resolved_url
+
+        self._transport = AsyncHttpTransport(
+            api_key=resolved_key,
+            base_url=resolved_url,
+            timeout=timeout,
+            client=http_client,
+        )
+
+        self.mail = AsyncMailClient(self._transport)
+        self.tunnels = AsyncTunnelsClient(self._transport, resolved_key, resolved_url)
+        self.webhooks = AsyncWebhooksClient(self._transport)
+
+    async def create_identity(
+        self,
+        agent_handle: str,
+        *,
+        display_name: str | None = None,
+        description: str | None = None,
+    ) -> AsyncAgentIdentity:
+        """Provisions a new agent identity with an atomic dedicated mailbox and network tunnel."""
+        payload: dict[str, Any] = {
+            "agent_handle": agent_handle.strip().lstrip("@").lower(),
+        }
+        if display_name is not None:
+            payload["display_name"] = display_name
+        if description is not None:
+            payload["description"] = description
+
+        data = await self._transport.post("/v1/identities", json=payload)
+        return AsyncAgentIdentity(
+            IdentityData.from_dict(data),
+            self._transport,
+            self._api_key,
+            self._base_url,
+        )
+
+    async def get_identity(self, handle_or_id: str) -> AsyncAgentIdentity:
+        """Retrieves an existing agent identity by handle or ID."""
+        clean_handle = handle_or_id.strip().lstrip("@").lower()
+        data = await self._transport.get(f"/v1/identities/{quote(clean_handle)}")
+        return AsyncAgentIdentity(
+            IdentityData.from_dict(data),
+            self._transport,
+            self._api_key,
+            self._base_url,
+        )
+
+    async def list_identities(
+        self,
+        *,
+        limit: int | None = None,
+        offset: int | None = None,
+        status: Literal["active", "archived", "deleted"] | None = None,
+    ) -> list[AsyncAgentIdentity]:
+        """Lists agent identities in the organization."""
+        params: dict[str, Any] = {}
+        if limit is not None:
+            params["limit"] = limit
+        if offset is not None:
+            params["offset"] = offset
+        if status is not None:
+            params["status"] = status
+
+        data = await self._transport.get("/v1/identities", params=params)
+        if isinstance(data, list):
+            raw_items = data
+        elif isinstance(data, dict):
+            raw_items = data.get("identities", [])
+        else:
+            raw_items = []
+        return [
+            AsyncAgentIdentity(
+                IdentityData.from_dict(item),
+                self._transport,
+                self._api_key,
+                self._base_url,
+            )
+            for item in raw_items
+        ]
+
+    async def whoami(self) -> WhoamiResult:
+        """Inspects the active API key and organization authentication context."""
+        data = await self._transport.get("/v1/whoami")
+        return WhoamiResult.from_dict(data)
+
+    async def aclose(self) -> None:
+        """Closes underlying HTTP connections."""
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> AsyncWirebox:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.aclose()

wirebox/client.py

@@ -0,0 +1,117 @@
+"""Wirebox Python SDK — Synchronous Client.
+
+Main synchronous entry point for interacting with the Wirebox Edge Core API.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Literal
+from urllib.parse import quote
+
+import httpx
+
+from wirebox._http import DEFAULT_BASE_URL, DEFAULT_TIMEOUT_SECONDS, SyncHttpTransport
+from wirebox.identity import AgentIdentity
+from wirebox.mail import MailClient
+from wirebox.tunnels import TunnelsClient
+from wirebox.types import IdentityData, WhoamiResult
+from wirebox.webhooks import WebhooksClient
+
+
+class Wirebox:
+    """Synchronous client for the Wirebox API.
+
+    Example:
+        >>> from wirebox import Wirebox
+        >>> client = Wirebox(api_key="wb_live_...")
+        >>> agent = client.create_identity("sales-bot", display_name="Sales Bot")
+        >>> agent.send_email(to="customer@example.com", subject="Hi", text="Hello!")
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        resolved_key = api_key or os.environ.get("WIREBOX_API_KEY")
+        resolved_url = base_url or os.environ.get("WIREBOX_BASE_URL") or DEFAULT_BASE_URL
+
+        self._transport = SyncHttpTransport(
+            api_key=resolved_key,
+            base_url=resolved_url,
+            timeout=timeout,
+            client=http_client,
+        )
+
+        self.mail = MailClient(self._transport)
+        self.tunnels = TunnelsClient(self._transport)
+        self.webhooks = WebhooksClient(self._transport)
+
+    def create_identity(
+        self,
+        agent_handle: str,
+        *,
+        display_name: str | None = None,
+        description: str | None = None,
+    ) -> AgentIdentity:
+        """Provisions a new agent identity with an atomic dedicated mailbox and network tunnel."""
+        payload: dict[str, Any] = {
+            "agent_handle": agent_handle.strip().lstrip("@").lower(),
+        }
+        if display_name is not None:
+            payload["display_name"] = display_name
+        if description is not None:
+            payload["description"] = description
+
+        data = self._transport.post("/v1/identities", json=payload)
+        return AgentIdentity(IdentityData.from_dict(data), self._transport)
+
+    def get_identity(self, handle_or_id: str) -> AgentIdentity:
+        """Retrieves an existing agent identity by handle or ID."""
+        clean_handle = handle_or_id.strip().lstrip("@").lower()
+        data = self._transport.get(f"/v1/identities/{quote(clean_handle)}")
+        return AgentIdentity(IdentityData.from_dict(data), self._transport)
+
+    def list_identities(
+        self,
+        *,
+        limit: int | None = None,
+        offset: int | None = None,
+        status: Literal["active", "archived", "deleted"] | None = None,
+    ) -> list[AgentIdentity]:
+        """Lists agent identities in the organization."""
+        params: dict[str, Any] = {}
+        if limit is not None:
+            params["limit"] = limit
+        if offset is not None:
+            params["offset"] = offset
+        if status is not None:
+            params["status"] = status
+
+        data = self._transport.get("/v1/identities", params=params)
+        if isinstance(data, list):
+            raw_items = data
+        elif isinstance(data, dict):
+            raw_items = data.get("identities", [])
+        else:
+            raw_items = []
+        return [AgentIdentity(IdentityData.from_dict(item), self._transport) for item in raw_items]
+
+    def whoami(self) -> WhoamiResult:
+        """Inspects the active API key and organization authentication context."""
+        data = self._transport.get("/v1/whoami")
+        return WhoamiResult.from_dict(data)
+
+    def close(self) -> None:
+        """Closes underlying HTTP connections."""
+        self._transport.close()
+
+    def __enter__(self) -> Wirebox:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()

wirebox/exceptions.py

@@ -0,0 +1,118 @@
+"""Wirebox Python SDK — Exception Hierarchy.
+
+Provides structured, typed exceptions for network, authentication, validation,
+and API error conditions with full request ID tracing.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class WireboxError(Exception):
+    """Base exception for all Wirebox SDK errors."""
+
+
+class WireboxConnectionError(WireboxError):
+    """Raised when an HTTP or WebSocket connection fails or times out."""
+
+    def __init__(self, message: str, original_error: Exception | None = None) -> None:
+        super().__init__(message)
+        self.original_error = original_error
+
+
+class ValidationError(WireboxError):
+    """Raised when client-side parameter validation fails before sending a request."""
+
+
+class WireboxAPIError(WireboxError):
+    """Raised when the Wirebox Edge Core API returns a non-2xx response.
+
+    Attributes:
+        status: HTTP response status code (e.g. 400, 401, 404, 429, 500).
+        code: Machine-readable error code (e.g. 'handle_already_taken', 'unauthorized').
+        message: Human-readable error message explaining the failure.
+        request_id: Optional Wirebox request ID (x-wirebox-request-id) for tracing.
+        details: Optional structured details dictionary from the server.
+    """
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        message: str,
+        request_id: str | None = None,
+        details: Any = None,
+    ) -> None:
+        super().__init__(
+            f"[{status} {code}] {message}"
+            if request_id is None
+            else f"[{status} {code}] {message} (request_id: {request_id})"
+        )
+        self.status = status
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+        self.details = details
+
+
+class AuthenticationError(WireboxAPIError):
+    """Raised on HTTP 401 or 403 when the provided API key is missing, invalid, or lacks permissions."""
+
+
+class NotFoundError(WireboxAPIError):
+    """Raised on HTTP 404 when the requested identity, mailbox, message, tunnel, or webhook does not exist."""
+
+
+class RateLimitError(WireboxAPIError):
+    """Raised on HTTP 429 when API rate limits are exceeded."""
+
+
+class HandleAlreadyTakenError(WireboxAPIError):
+    """Raised on HTTP 409 when attempting to create an identity with an agent_handle that is already claimed."""
+
+
+class FreeTierLimitExceededError(WireboxAPIError):
+    """Raised when an organization attempts to provision resources beyond their free tier allowance."""
+
+
+def parse_api_error(status: int, data: Any, request_id: str | None = None) -> WireboxAPIError:
+    """Parses a response status and body into the appropriate WireboxAPIError subclass."""
+    code = "unknown_error"
+    message = f"Request failed with HTTP status {status}"
+    details: Any = None
+
+    if isinstance(data, dict):
+        if "error" in data:
+            err = data["error"]
+            if isinstance(err, dict):
+                code = str(err.get("code", code))
+                message = str(err.get("message", message))
+                details = err.get("details", data)
+            elif isinstance(err, str):
+                message = err
+        elif "message" in data:
+            message = str(data["message"])
+            if "code" in data:
+                code = str(data["code"])
+        details = data
+
+    clean_code = code.lower()
+
+    if status in (401, 403):
+        if "free_tier" in clean_code or "quota" in clean_code:
+            return FreeTierLimitExceededError(status, code, message, request_id, details)
+        return AuthenticationError(status, code, message, request_id, details)
+
+    if status == 404:
+        return NotFoundError(status, code, message, request_id, details)
+
+    if status == 409 or clean_code in ("handle_already_taken", "conflict"):
+        return HandleAlreadyTakenError(status, code, message, request_id, details)
+
+    if status == 429:
+        if "free_tier" in clean_code:
+            return FreeTierLimitExceededError(status, code, message, request_id, details)
+        return RateLimitError(status, code, message, request_id, details)
+
+    return WireboxAPIError(status, code, message, request_id, details)