wirebox 0.1.0__tar.gz

wirebox-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+env/
+venv/
+ENV/
+
+# Testing & Coverage
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+
+# IDE & Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Environment variables
+.env
+.env.*
+!.env.example
+
+# OS files
+.DS_Store
+Thumbs.db

wirebox-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wirebox (https://wirebox.sh)
+
+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.

wirebox-0.1.0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.5
+Name: wirebox
+Version: 0.1.0
+Summary: Official Python SDK for Wirebox — Real-world identity and communication layer for AI agents
+Project-URL: Homepage, https://wirebox.sh
+Project-URL: Documentation, https://docs.wirebox.sh
+Project-URL: Repository, https://github.com/wirebox-sh/wirebox-python
+Author-email: Wirebox Team <hi@wirebox.sh>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,email,identity,tunnels,webhooks,wirebox
+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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Wirebox Python SDK
+
+Official Python SDK for [Wirebox](https://wirebox.sh) — The real-world identity, communication, and context execution layer for AI agents.
+
+Equips autonomous agents with dedicated email inboxes, network tunnels, and webhooks with first-class synchronous and asynchronous support.
+
+[![PyPI](https://img.shields.io/pypi/v/wirebox.svg)](https://pypi.org/project/wirebox/)
+[![Python Version](https://img.shields.io/pypi/pyversions/wirebox.svg)](https://pypi.org/project/wirebox/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Key Features
+
+- **Dual Engine**: High-performance synchronous `Wirebox` and native asynchronous `AsyncWirebox` clients.
+- **Identity & Mailbox Hub**: Provision autonomous agent personas with atomic dedicated email inboxes (`@wireboxmail.com`).
+- **Zero-Config Network Tunnels**: Expose local agent servers or containers to the public internet (`https://<handle>.tunnel.wirebox.sh`) over secure WebSockets — **no ngrok required**.
+- **Cryptographic Webhook Verification**: Constant-time HMAC-SHA256 signature verification (`verify_webhook`) with anti-replay timestamp validation.
+- **Zero Heavy C Dependencies**: Built cleanly on `httpx` and `websockets` — installs instantly across Linux, macOS, and Windows.
+- **Modern Pythonic Design**: Full Python 3.11+ type hints (PEP 561 `py.typed`), immutable dataclasses, and rich exception hierarchy.
+
+---
+
+## Installation
+
+```bash
+pip install wirebox
+```
+
+Or using modern package managers:
+
+```bash
+# With uv
+uv add wirebox
+
+# With poetry
+poetry add wirebox
+```
+
+---
+
+## Quickstart
+
+### 1. Asynchronous Client (Recommended for AI Agents & FastAPI)
+
+```python
+import asyncio
+from wirebox import AsyncWirebox
+
+
+async def main():
+    async with AsyncWirebox(api_key="wb_live_xxxxxxxx") as client:
+        # 1. Provision an autonomous agent identity
+        agent = await client.create_identity("sales-bot", display_name="Sales Assistant")
+        print(f"Created agent @{agent.agent_handle} with inbox {agent.mailbox.email_address}")
+
+        # 2. Dispatch an outbound email
+        result = await agent.send_email(
+            to="client@example.com",
+            subject="Welcome to Wirebox",
+            text="Hello! This message was dispatched autonomously by an AI agent.",
+        )
+        print(f"Email sent with status: {result.status}")
+
+        # 3. Retrieve and iterate over inbox messages
+        async for msg in agent.iter_messages():
+            print(f"[{msg.direction}] {msg.from_address}: {msg.subject}")
+
+
+asyncio.run(main())
+```
+
+### 2. Synchronous Client (For Scripts, REPL & CLI tools)
+
+```python
+from wirebox import Wirebox
+
+client = Wirebox(api_key="wb_live_xxxxxxxx")
+
+# Provision or fetch existing identity
+agent = client.get_identity("sales-bot")
+
+# Send email
+agent.send_email(
+    to="support@example.com",
+    subject="Agent status update",
+    text="All background jobs running normally.",
+)
+
+# Whoami identity check
+me = client.whoami()
+print(f"Authenticated as org: {me.organization.slug} ({me.api_key.role})")
+```
+
+---
+
+## Webhooks & Cryptographic Signature Verification
+
+Wirebox signs every webhook payload with an HMAC-SHA256 signature to guarantee authenticity and prevent tampering or replay attacks.
+
+Use `verify_webhook` directly in any web framework:
+
+### FastAPI / Starlette Example:
+
+```python
+from fastapi import FastAPI, Request, HTTPException
+from wirebox import verify_webhook
+
+app = FastAPI()
+WEBHOOK_SECRET = "whsec_your_signing_secret"
+
+
+@app.post("/webhook")
+async def webhook_endpoint(request: Request):
+    raw_body = await request.body()
+
+    # Validates signature and checks timestamp within 300-second window
+    if not verify_webhook(payload=raw_body, headers=request.headers, secret=WEBHOOK_SECRET):
+        raise HTTPException(status_code=403, detail="Invalid signature")
+
+    payload = await request.json()
+    event_type = payload.get("event_type")
+    print(f"Received verified event: {event_type}")
+
+    return {"status": "ok"}
+```
+
+---
+
+## Network Tunnels (Local Port Forwarding)
+
+Connect local ports or container services to your agent's public tunnel URL without opening firewall ports or buying static IPs:
+
+```python
+import asyncio
+from wirebox import AsyncWirebox
+
+
+async def main():
+    async with AsyncWirebox(api_key="wb_live_...") as client:
+        agent = await client.get_identity("sales-bot")
+
+        # Reverse-proxy inbound HTTPS traffic from tunnel to local port 3456
+        tunnel = await agent.connect_tunnel(forward_to=3456)
+        print(f"Public tunnel URL: {tunnel.public_url}")
+
+        # Keep proxying until closed
+        await tunnel.wait_closed()
+
+
+asyncio.run(main())
+```
+
+---
+
+## Exception Hierarchy
+
+All SDK exceptions inherit from `WireboxError`:
+
+```text
+WireboxError
+├── WireboxConnectionError         # Network, connection drop, or timeout failures
+├── ValidationError                # Client-side parameter validation failure
+└── WireboxAPIError                # Non-2xx responses from Wirebox API
+    ├── AuthenticationError        # HTTP 401 / 403 (invalid API key or lack of permissions)
+    ├── NotFoundError              # HTTP 404 (identity, mailbox, message, or webhook not found)
+    ├── RateLimitError             # HTTP 429 (rate limits exceeded)
+    ├── HandleAlreadyTakenError    # HTTP 409 (agent_handle already registered)
+    └── FreeTierLimitExceededError # HTTP 403/429 (free tier quota limit reached)
+```
+
+Example handling:
+
+```python
+from wirebox import Wirebox, HandleAlreadyTakenError, WireboxAPIError
+
+client = Wirebox(api_key="wb_live_...")
+
+try:
+    agent = client.create_identity("sales-bot")
+except HandleAlreadyTakenError:
+    print("Handle is already claimed. Fetching existing identity instead...")
+    agent = client.get_identity("sales-bot")
+except WireboxAPIError as e:
+    print(f"API failed with [{e.status} {e.code}]: {e.message} (request_id: {e.request_id})")
+```
+
+---
+
+## License
+
+MIT © [Wirebox](https://wirebox.sh)

wirebox-0.1.0/README.md

@@ -0,0 +1,192 @@
+# Wirebox Python SDK
+
+Official Python SDK for [Wirebox](https://wirebox.sh) — The real-world identity, communication, and context execution layer for AI agents.
+
+Equips autonomous agents with dedicated email inboxes, network tunnels, and webhooks with first-class synchronous and asynchronous support.
+
+[![PyPI](https://img.shields.io/pypi/v/wirebox.svg)](https://pypi.org/project/wirebox/)
+[![Python Version](https://img.shields.io/pypi/pyversions/wirebox.svg)](https://pypi.org/project/wirebox/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Key Features
+
+- **Dual Engine**: High-performance synchronous `Wirebox` and native asynchronous `AsyncWirebox` clients.
+- **Identity & Mailbox Hub**: Provision autonomous agent personas with atomic dedicated email inboxes (`@wireboxmail.com`).
+- **Zero-Config Network Tunnels**: Expose local agent servers or containers to the public internet (`https://<handle>.tunnel.wirebox.sh`) over secure WebSockets — **no ngrok required**.
+- **Cryptographic Webhook Verification**: Constant-time HMAC-SHA256 signature verification (`verify_webhook`) with anti-replay timestamp validation.
+- **Zero Heavy C Dependencies**: Built cleanly on `httpx` and `websockets` — installs instantly across Linux, macOS, and Windows.
+- **Modern Pythonic Design**: Full Python 3.11+ type hints (PEP 561 `py.typed`), immutable dataclasses, and rich exception hierarchy.
+
+---
+
+## Installation
+
+```bash
+pip install wirebox
+```
+
+Or using modern package managers:
+
+```bash
+# With uv
+uv add wirebox
+
+# With poetry
+poetry add wirebox
+```
+
+---
+
+## Quickstart
+
+### 1. Asynchronous Client (Recommended for AI Agents & FastAPI)
+
+```python
+import asyncio
+from wirebox import AsyncWirebox
+
+
+async def main():
+    async with AsyncWirebox(api_key="wb_live_xxxxxxxx") as client:
+        # 1. Provision an autonomous agent identity
+        agent = await client.create_identity("sales-bot", display_name="Sales Assistant")
+        print(f"Created agent @{agent.agent_handle} with inbox {agent.mailbox.email_address}")
+
+        # 2. Dispatch an outbound email
+        result = await agent.send_email(
+            to="client@example.com",
+            subject="Welcome to Wirebox",
+            text="Hello! This message was dispatched autonomously by an AI agent.",
+        )
+        print(f"Email sent with status: {result.status}")
+
+        # 3. Retrieve and iterate over inbox messages
+        async for msg in agent.iter_messages():
+            print(f"[{msg.direction}] {msg.from_address}: {msg.subject}")
+
+
+asyncio.run(main())
+```
+
+### 2. Synchronous Client (For Scripts, REPL & CLI tools)
+
+```python
+from wirebox import Wirebox
+
+client = Wirebox(api_key="wb_live_xxxxxxxx")
+
+# Provision or fetch existing identity
+agent = client.get_identity("sales-bot")
+
+# Send email
+agent.send_email(
+    to="support@example.com",
+    subject="Agent status update",
+    text="All background jobs running normally.",
+)
+
+# Whoami identity check
+me = client.whoami()
+print(f"Authenticated as org: {me.organization.slug} ({me.api_key.role})")
+```
+
+---
+
+## Webhooks & Cryptographic Signature Verification
+
+Wirebox signs every webhook payload with an HMAC-SHA256 signature to guarantee authenticity and prevent tampering or replay attacks.
+
+Use `verify_webhook` directly in any web framework:
+
+### FastAPI / Starlette Example:
+
+```python
+from fastapi import FastAPI, Request, HTTPException
+from wirebox import verify_webhook
+
+app = FastAPI()
+WEBHOOK_SECRET = "whsec_your_signing_secret"
+
+
+@app.post("/webhook")
+async def webhook_endpoint(request: Request):
+    raw_body = await request.body()
+
+    # Validates signature and checks timestamp within 300-second window
+    if not verify_webhook(payload=raw_body, headers=request.headers, secret=WEBHOOK_SECRET):
+        raise HTTPException(status_code=403, detail="Invalid signature")
+
+    payload = await request.json()
+    event_type = payload.get("event_type")
+    print(f"Received verified event: {event_type}")
+
+    return {"status": "ok"}
+```
+
+---
+
+## Network Tunnels (Local Port Forwarding)
+
+Connect local ports or container services to your agent's public tunnel URL without opening firewall ports or buying static IPs:
+
+```python
+import asyncio
+from wirebox import AsyncWirebox
+
+
+async def main():
+    async with AsyncWirebox(api_key="wb_live_...") as client:
+        agent = await client.get_identity("sales-bot")
+
+        # Reverse-proxy inbound HTTPS traffic from tunnel to local port 3456
+        tunnel = await agent.connect_tunnel(forward_to=3456)
+        print(f"Public tunnel URL: {tunnel.public_url}")
+
+        # Keep proxying until closed
+        await tunnel.wait_closed()
+
+
+asyncio.run(main())
+```
+
+---
+
+## Exception Hierarchy
+
+All SDK exceptions inherit from `WireboxError`:
+
+```text
+WireboxError
+├── WireboxConnectionError         # Network, connection drop, or timeout failures
+├── ValidationError                # Client-side parameter validation failure
+└── WireboxAPIError                # Non-2xx responses from Wirebox API
+    ├── AuthenticationError        # HTTP 401 / 403 (invalid API key or lack of permissions)
+    ├── NotFoundError              # HTTP 404 (identity, mailbox, message, or webhook not found)
+    ├── RateLimitError             # HTTP 429 (rate limits exceeded)
+    ├── HandleAlreadyTakenError    # HTTP 409 (agent_handle already registered)
+    └── FreeTierLimitExceededError # HTTP 403/429 (free tier quota limit reached)
+```
+
+Example handling:
+
+```python
+from wirebox import Wirebox, HandleAlreadyTakenError, WireboxAPIError
+
+client = Wirebox(api_key="wb_live_...")
+
+try:
+    agent = client.create_identity("sales-bot")
+except HandleAlreadyTakenError:
+    print("Handle is already claimed. Fetching existing identity instead...")
+    agent = client.get_identity("sales-bot")
+except WireboxAPIError as e:
+    print(f"API failed with [{e.status} {e.code}]: {e.message} (request_id: {e.request_id})")
+```
+
+---
+
+## License
+
+MIT © [Wirebox](https://wirebox.sh)

wirebox-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "wirebox"
+version = "0.1.0"
+description = "Official Python SDK for Wirebox — Real-world identity and communication layer for AI agents"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Wirebox Team", email = "hi@wirebox.sh" }
+]
+keywords = [
+    "wirebox",
+    "ai",
+    "agents",
+    "email",
+    "webhooks",
+    "tunnels",
+    "identity"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27.0",
+    "websockets>=12.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-cov>=5.0.0",
+    "ruff>=0.4.0",
+]
+
+[project.urls]
+Homepage = "https://wirebox.sh"
+Documentation = "https://docs.wirebox.sh"
+Repository = "https://github.com/wirebox-sh/wirebox-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/wirebox"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM"]
+ignore = ["E501"]

wirebox-0.1.0/src/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",
+]