agenitry 0.1.0__tar.gz

agenitry-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+.gitnexus

agenitry-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: agenitry
+Version: 0.1.0
+Summary: Official Python SDK for the Agenitry audit-trail API — log AI agent actions, query events, and pull stats in two lines of code.
+Project-URL: Homepage, https://agenitry.com
+Project-URL: Documentation, https://github.com/concya/agenitry#readme
+Project-URL: Repository, https://github.com/concya/agenitry
+Author-email: Agenitry <ola@agenitry.com>
+License-Expression: MIT
+Keywords: agenitry,ai-agents,audit,compliance,ledger,observability
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Agenitry Python SDK
+
+> The event ledger for AI agents. One line to log, one URL to verify.
+
+## The problem
+
+Your AI agent takes actions — reservations, orders, comps, price changes — but nobody can see what happened or why. You're flying blind.
+
+**Agenitry** gives every agent action a permanent, verifiable record. Log an event in one line. Share a URL. Done.
+
+## Install
+
+```bash
+pip install agenitry
+```
+
+Zero dependencies. Python 3.9+.
+
+## Quick start
+
+```python
+from agenitry import Agenitry
+
+agent = Agenitry(api_key="ag_your_key", venue_id="nobo-downtown")
+
+# Log an event — fire and forget by default
+agent.log(action="order_captured", amount=42.50, direction="inbound")
+
+# Await confirmation if you need the event ID
+event = agent.log(action="reservation_booked", amount=0, direction="inbound", await_confirmation=True)
+print(event["id"])  # evt_abc123
+
+# Query events
+result = agent.events(action="order_captured", limit=10)
+for e in result["events"]:
+    print(e["action"], e["amount"])
+
+# Get stats
+stats = agent.stats(period="7d")
+print(stats["total_inbound"], stats["event_count"])
+```
+
+## Verify URL
+
+Every event gets a permanent, shareable URL:
+
+```
+https://api.agenitry.com/v1/verify/{venue_id}/{event_id}
+```
+
+No login required. No dashboard needed. Just share the link and anyone can verify what happened.
+
+## API Reference
+
+### `Agenitry(api_key, venue_id, *, agent_id=None, base_url=None, max_retries=3, retry_base_delay=0.5)`
+
+Create a new Agenitry client.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `api_key` | `str` | required | Your venue API key (`ag_...`) |
+| `venue_id` | `str` | required | Your venue identifier |
+| `agent_id` | `str` | `None` | Default agent ID for all events |
+| `base_url` | `str` | `https://api.agenitry.com` | API base URL |
+| `max_retries` | `int` | `3` | Max retry attempts on 429/5xx |
+| `retry_base_delay` | `float` | `0.5` | Base delay in seconds (exponential backoff) |
+
+### `agent.log(*, action, amount=None, direction=None, agent_id=None, context=None, await_confirmation=False)`
+
+Log an event.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `action` | `str` | required | Event action (see below) |
+| `amount` | `float` | `None` | Dollar amount |
+| `direction` | `str` | `None` | `inbound`, `outbound`, or `internal` |
+| `agent_id` | `str` | constructor default | Agent that performed the action |
+| `context` | `dict` | `None` | Arbitrary JSONB context data |
+| `await_confirmation` | `bool` | `False` | If `True`, waits for server response |
+
+**Fire and forget** (default): `log()` returns immediately with `{id: "", status: "logged"}`. If the request fails, it's silently swallowed. Perfect for non-critical logging.
+
+**Await confirmation**: `log()` waits for the server response and raises `AgenitryError` on failure. Use when you need the event ID or need to know it was persisted.
+
+### Event Actions
+
+| Action | Description | Direction | Example |
+|--------|-------------|-----------|---------|
+| `order_captured` | Agent captured an order | `inbound` | Voice agent took a $42.50 takeout order |
+| `reservation_booked` | Agent booked a reservation | `inbound` | Chatbot reserved table 7 for 8pm |
+| `price_changed` | Agent changed a price | `internal` | Agent updated happy hour draft from $6 to $7 |
+| `item_86d` | Agent marked an item as unavailable | `internal` | Agent 86'd the tuna special |
+| `comp_issued` | Agent issued a comp | `outbound` | Agent comped dessert for a regular |
+| `purchase_order` | Agent placed a purchase order | `outbound` | Agent ordered 50 lbs of salmon |
+
+### `agent.events(*, agent_id=None, action=None, direction=None, limit=None, offset=None, context=None)`
+
+Query events for the venue.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `agent_id` | `str` | `None` | Filter by agent |
+| `action` | `str` | `None` | Filter by action type |
+| `direction` | `str` | `None` | Filter by direction |
+| `limit` | `int` | `50` | Max events to return |
+| `offset` | `int` | `0` | Pagination offset |
+| `context` | `dict` | `None` | JSONB contains filter |
+
+Returns a dict with `total`, `limit`, `offset`, `has_more`, and `events` list.
+
+### `agent.stats(*, period=None)`
+
+Get aggregate stats for the venue.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `period` | `str` | `today` | `today`, `7d`, `30d`, or `90d` |
+
+Returns a dict with `total_inbound`, `total_outbound`, `event_count`, and `by_agent` breakdown.
+
+### `AgenitryError`
+
+Raised on API errors. Attributes:
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `status` | `int` or `None` | HTTP status code (if available) |
+| `body` | `dict` or `None` | Parsed response body (if JSON) |
+| `code` | `str` | Error code: `NETWORK`, `HTTP`, or `PARSE` |
+
+### `create_agenitry(api_key, venue_id, **kwargs)`
+
+Factory function. Returns an `Agenitry` instance. Same arguments as the constructor.
+
+## Type Aliases
+
+```python
+EventAction = Literal[
+    "order_captured", "reservation_booked", "price_changed",
+    "item_86d", "comp_issued", "purchase_order"
+]
+
+EventDirection = Literal["inbound", "outbound", "internal"]
+
+StatsPeriod = Literal["today", "7d", "30d", "90d"]
+```
+
+## License
+
+MIT

agenitry-0.1.0/README.md

@@ -0,0 +1,150 @@
+# Agenitry Python SDK
+
+> The event ledger for AI agents. One line to log, one URL to verify.
+
+## The problem
+
+Your AI agent takes actions — reservations, orders, comps, price changes — but nobody can see what happened or why. You're flying blind.
+
+**Agenitry** gives every agent action a permanent, verifiable record. Log an event in one line. Share a URL. Done.
+
+## Install
+
+```bash
+pip install agenitry
+```
+
+Zero dependencies. Python 3.9+.
+
+## Quick start
+
+```python
+from agenitry import Agenitry
+
+agent = Agenitry(api_key="ag_your_key", venue_id="nobo-downtown")
+
+# Log an event — fire and forget by default
+agent.log(action="order_captured", amount=42.50, direction="inbound")
+
+# Await confirmation if you need the event ID
+event = agent.log(action="reservation_booked", amount=0, direction="inbound", await_confirmation=True)
+print(event["id"])  # evt_abc123
+
+# Query events
+result = agent.events(action="order_captured", limit=10)
+for e in result["events"]:
+    print(e["action"], e["amount"])
+
+# Get stats
+stats = agent.stats(period="7d")
+print(stats["total_inbound"], stats["event_count"])
+```
+
+## Verify URL
+
+Every event gets a permanent, shareable URL:
+
+```
+https://api.agenitry.com/v1/verify/{venue_id}/{event_id}
+```
+
+No login required. No dashboard needed. Just share the link and anyone can verify what happened.
+
+## API Reference
+
+### `Agenitry(api_key, venue_id, *, agent_id=None, base_url=None, max_retries=3, retry_base_delay=0.5)`
+
+Create a new Agenitry client.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `api_key` | `str` | required | Your venue API key (`ag_...`) |
+| `venue_id` | `str` | required | Your venue identifier |
+| `agent_id` | `str` | `None` | Default agent ID for all events |
+| `base_url` | `str` | `https://api.agenitry.com` | API base URL |
+| `max_retries` | `int` | `3` | Max retry attempts on 429/5xx |
+| `retry_base_delay` | `float` | `0.5` | Base delay in seconds (exponential backoff) |
+
+### `agent.log(*, action, amount=None, direction=None, agent_id=None, context=None, await_confirmation=False)`
+
+Log an event.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `action` | `str` | required | Event action (see below) |
+| `amount` | `float` | `None` | Dollar amount |
+| `direction` | `str` | `None` | `inbound`, `outbound`, or `internal` |
+| `agent_id` | `str` | constructor default | Agent that performed the action |
+| `context` | `dict` | `None` | Arbitrary JSONB context data |
+| `await_confirmation` | `bool` | `False` | If `True`, waits for server response |
+
+**Fire and forget** (default): `log()` returns immediately with `{id: "", status: "logged"}`. If the request fails, it's silently swallowed. Perfect for non-critical logging.
+
+**Await confirmation**: `log()` waits for the server response and raises `AgenitryError` on failure. Use when you need the event ID or need to know it was persisted.
+
+### Event Actions
+
+| Action | Description | Direction | Example |
+|--------|-------------|-----------|---------|
+| `order_captured` | Agent captured an order | `inbound` | Voice agent took a $42.50 takeout order |
+| `reservation_booked` | Agent booked a reservation | `inbound` | Chatbot reserved table 7 for 8pm |
+| `price_changed` | Agent changed a price | `internal` | Agent updated happy hour draft from $6 to $7 |
+| `item_86d` | Agent marked an item as unavailable | `internal` | Agent 86'd the tuna special |
+| `comp_issued` | Agent issued a comp | `outbound` | Agent comped dessert for a regular |
+| `purchase_order` | Agent placed a purchase order | `outbound` | Agent ordered 50 lbs of salmon |
+
+### `agent.events(*, agent_id=None, action=None, direction=None, limit=None, offset=None, context=None)`
+
+Query events for the venue.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `agent_id` | `str` | `None` | Filter by agent |
+| `action` | `str` | `None` | Filter by action type |
+| `direction` | `str` | `None` | Filter by direction |
+| `limit` | `int` | `50` | Max events to return |
+| `offset` | `int` | `0` | Pagination offset |
+| `context` | `dict` | `None` | JSONB contains filter |
+
+Returns a dict with `total`, `limit`, `offset`, `has_more`, and `events` list.
+
+### `agent.stats(*, period=None)`
+
+Get aggregate stats for the venue.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `period` | `str` | `today` | `today`, `7d`, `30d`, or `90d` |
+
+Returns a dict with `total_inbound`, `total_outbound`, `event_count`, and `by_agent` breakdown.
+
+### `AgenitryError`
+
+Raised on API errors. Attributes:
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `status` | `int` or `None` | HTTP status code (if available) |
+| `body` | `dict` or `None` | Parsed response body (if JSON) |
+| `code` | `str` | Error code: `NETWORK`, `HTTP`, or `PARSE` |
+
+### `create_agenitry(api_key, venue_id, **kwargs)`
+
+Factory function. Returns an `Agenitry` instance. Same arguments as the constructor.
+
+## Type Aliases
+
+```python
+EventAction = Literal[
+    "order_captured", "reservation_booked", "price_changed",
+    "item_86d", "comp_issued", "purchase_order"
+]
+
+EventDirection = Literal["inbound", "outbound", "internal"]
+
+StatsPeriod = Literal["today", "7d", "30d", "90d"]
+```
+
+## License
+
+MIT

agenitry-0.1.0/agenitry/__init__.py

@@ -0,0 +1,354 @@
+"""
+Agenitry SDK — Official Python client for the Agenitry audit-trail API.
+
+Usage:
+    from agenitry import Agenitry
+
+    agent = Agenitry(api_key="ag_your_key", venue_id="my-venue")
+
+    # Fire-and-forget — never blocks, never raises
+    agent.log(action="order_captured", amount=42.50)
+
+    # Query events
+    result = agent.events(limit=10)
+
+    # Pull stats
+    stats = agent.stats(period="7d")
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import Any, Literal, Optional
+from urllib.request import Request, urlopen
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode, quote
+
+# ---------------------------------------------------------------------------
+# Types
+# ---------------------------------------------------------------------------
+
+EventAction = Literal[
+    "order_captured",
+    "reservation_booked",
+    "price_changed",
+    "item_86d",
+    "comp_issued",
+    "purchase_order",
+]
+
+EventDirection = Literal["inbound", "outbound", "internal"]
+
+StatsPeriod = Literal["today", "7d", "30d", "all"]
+
+
+# ---------------------------------------------------------------------------
+# Error
+# ---------------------------------------------------------------------------
+
+class AgenitryError(Exception):
+    """Error thrown by the Agenitry SDK.
+
+    Attributes:
+        status: HTTP status code (0 if no response was received).
+        body: Parsed response body (if available).
+        code: Machine-readable error code ('NETWORK', 'TIMEOUT', 'API').
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status: int = 0,
+        body: Any = None,
+        code: Literal["NETWORK", "TIMEOUT", "API"] = "API",
+    ):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+        self.code = code
+
+    def __repr__(self) -> str:
+        return f"AgenitryError(status={self.status}, code={self.code}, message={self.args[0]!r})"
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+_DEFAULT_BASE_URL = "https://api.agenitry.com"
+_DEFAULT_MAX_RETRIES = 2
+_DEFAULT_RETRY_BASE_DELAY = 0.5  # seconds
+
+
+def _is_retryable(status: int) -> bool:
+    return status == 429 or status >= 500
+
+
+# ---------------------------------------------------------------------------
+# Client
+# ---------------------------------------------------------------------------
+
+class Agenitry:
+    """Agenitry client — the main entry point for the SDK.
+
+    Usage:
+        from agenitry import Agenitry
+
+        agent = Agenitry(api_key="ag_xxx", venue_id="my-venue")
+        agent.log(action="order_captured", amount=42.5)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        venue_id: str,
+        *,
+        base_url: str = _DEFAULT_BASE_URL,
+        agent_id: str = "default",
+        max_retries: int = _DEFAULT_MAX_RETRIES,
+        retry_base_delay: float = _DEFAULT_RETRY_BASE_DELAY,
+    ):
+        if not api_key:
+            raise AgenitryError("Agenitry: `api_key` is required", code="API")
+        if not venue_id:
+            raise AgenitryError("Agenitry: `venue_id` is required", code="API")
+
+        self.api_key = api_key
+        self.venue_id = venue_id
+        self.base_url = base_url.rstrip("/")
+        self.agent_id = agent_id
+        self.max_retries = max_retries
+        self.retry_base_delay = retry_base_delay
+
+    # -------------------------------------------------------------------
+    # log() — fire-and-forget event logging
+    # -------------------------------------------------------------------
+
+    def log(
+        self,
+        action: EventAction,
+        *,
+        amount: Optional[float] = None,
+        currency: Optional[str] = None,
+        direction: Optional[EventDirection] = None,
+        context: Optional[dict[str, Any]] = None,
+        reason: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        await_confirmation: bool = False,
+    ) -> dict[str, Any]:
+        """Log an event to the audit trail.
+
+        This method is **fire-and-forget** by default — it never raises.
+        If you need confirmation, set ``await_confirmation=True``.
+
+        Args:
+            action: What happened. One of the six canonical actions.
+            amount: Dollar amount associated with the event.
+            currency: ISO-4217 currency code. Defaults to "USD".
+            direction: Direction of flow.
+            context: Arbitrary JSON context (metadata, order details, etc.).
+            reason: Human-readable reason for the event.
+            agent_id: Override the default agent_id for this event.
+            await_confirmation: If True, raise on errors instead of swallowing.
+
+        Returns:
+            dict with id, status, created_at (empty on fire-and-forget failure).
+        """
+        body: dict[str, Any] = {
+            "venue_id": self.venue_id,
+            "agent_id": agent_id or self.agent_id,
+            "action": action,
+        }
+        if amount is not None:
+            body["amount"] = amount
+        if currency is not None:
+            body["currency"] = currency
+        if direction is not None:
+            body["direction"] = direction
+        if context is not None:
+            body["context"] = context
+        if reason is not None:
+            body["reason"] = reason
+
+        try:
+            return self._request("POST", "/v1/events", body=body)
+        except AgenitryError:
+            if await_confirmation:
+                raise
+            # Fire-and-forget: swallow the error
+            return {
+                "id": "",
+                "status": "logged",
+                "created_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            }
+
+    # -------------------------------------------------------------------
+    # events() — query the audit trail
+    # -------------------------------------------------------------------
+
+    def events(
+        self,
+        *,
+        agent_id: Optional[str] = None,
+        action: Optional[EventAction] = None,
+        context: Optional[dict[str, Any]] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> dict[str, Any]:
+        """Fetch events for the venue.
+
+        Args:
+            agent_id: Filter by agent_id.
+            action: Filter by action type.
+            context: Filter by context (JSONB contains).
+            limit: Max events to return (1-200).
+            offset: Pagination offset.
+
+        Returns:
+            dict with venue_id, total, limit, offset, has_more, events.
+        """
+        params: dict[str, str] = {
+            "limit": str(limit),
+            "offset": str(offset),
+        }
+        if agent_id is not None:
+            params["agent_id"] = agent_id
+        if action is not None:
+            params["action"] = action
+        if context is not None:
+            params["context"] = json.dumps(context)
+
+        path = f"/v1/events/{quote(self.venue_id, safe='')}"
+        return self._request("GET", path, params=params)
+
+    # -------------------------------------------------------------------
+    # stats() — aggregated statistics
+    # -------------------------------------------------------------------
+
+    def stats(
+        self,
+        *,
+        period: StatsPeriod = "today",
+    ) -> dict[str, Any]:
+        """Fetch aggregated stats for the venue.
+
+        Args:
+            period: Aggregation period. One of "today", "7d", "30d", "all".
+
+        Returns:
+            dict with venue_id, period, total_inbound, total_outbound,
+            event_count, by_agent.
+        """
+        path = f"/v1/events/{quote(self.venue_id, safe='')}/stats"
+        return self._request("GET", path, params={"period": period})
+
+    # -------------------------------------------------------------------
+    # Internal HTTP helper with retry
+    # -------------------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Optional[dict[str, Any]] = None,
+        params: Optional[dict[str, str]] = None,
+    ) -> dict[str, Any]:
+        url = f"{self.base_url}{path}"
+        if params:
+            url = f"{url}?{urlencode(params)}"
+
+        data = json.dumps(body).encode("utf-8") if body else None
+
+        last_error: AgenitryError | None = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                req = Request(url, data=data, method=method)
+                req.add_header("Content-Type", "application/json")
+                req.add_header("Authorization", f"Bearer {self.api_key}")
+
+                with urlopen(req, timeout=30) as resp:
+                    return json.loads(resp.read().decode("utf-8"))
+
+            except HTTPError as e:
+                status = e.code
+                try:
+                    resp_body = json.loads(e.read().decode("utf-8"))
+                except Exception:
+                    resp_body = None
+
+                if not _is_retryable(status):
+                    raise AgenitryError(
+                        message=f"Agenitry API error: {status} {e.reason}",
+                        status=status,
+                        body=resp_body,
+                    )
+
+                last_error = AgenitryError(
+                    message=f"Agenitry API error (retryable): {status} {e.reason}",
+                    status=status,
+                )
+
+            except URLError as e:
+                raise AgenitryError(
+                    message=f"Agenitry network error: {e.reason}",
+                    code="NETWORK",
+                )
+
+            except Exception as e:
+                raise AgenitryError(
+                    message=f"Agenitry error: {e}",
+                    code="API",
+                )
+
+            # Exponential backoff before retry
+            if attempt < self.max_retries:
+                delay = self.retry_base_delay * (2 ** attempt)
+                time.sleep(delay)
+
+        raise last_error or AgenitryError("Agenitry: all retries exhausted")
+
+
+# ---------------------------------------------------------------------------
+# Convenience factory
+# ---------------------------------------------------------------------------
+
+def create_agenitry(
+    api_key: str,
+    venue_id: str,
+    *,
+    base_url: str = _DEFAULT_BASE_URL,
+    agent_id: str = "default",
+    max_retries: int = _DEFAULT_MAX_RETRIES,
+    retry_base_delay: float = _DEFAULT_RETRY_BASE_DELAY,
+) -> Agenitry:
+    """Create an Agenitry client in one line.
+
+    Usage:
+        from agenitry import create_agenitry
+        agent = create_agenitry(api_key="ag_xxx", venue_id="my-venue")
+    """
+    return Agenitry(
+        api_key=api_key,
+        venue_id=venue_id,
+        base_url=base_url,
+        agent_id=agent_id,
+        max_retries=max_retries,
+        retry_base_delay=retry_base_delay,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+__all__ = [
+    "Agenitry",
+    "AgenitryError",
+    "create_agenitry",
+    "EventAction",
+    "EventDirection",
+    "StatsPeriod",
+]

agenitry-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agenitry"
+version = "0.1.0"
+description = "Official Python SDK for the Agenitry audit-trail API — log AI agent actions, query events, and pull stats in two lines of code."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "Agenitry", email = "ola@agenitry.com" },
+]
+keywords = ["agenitry", "audit", "ai-agents", "ledger", "compliance", "observability"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://agenitry.com"
+Documentation = "https://github.com/concya/agenitry#readme"
+Repository = "https://github.com/concya/agenitry"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

agenitry-0.1.0/tests/test_agenitry.py

@@ -0,0 +1,309 @@
+"""Tests for the Agenitry Python SDK — mirrors the TypeScript SDK test suite."""
+
+import json
+from unittest.mock import patch, MagicMock
+from urllib.error import HTTPError, URLError
+from io import BytesIO
+
+import pytest
+
+from agenitry import Agenitry, AgenitryError, create_agenitry
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def make_response(data, status=200):
+    """Create a mock response object for urlopen."""
+    resp = MagicMock()
+    resp.read.return_value = json.dumps(data).encode("utf-8")
+    resp.__enter__ = MagicMock(return_value=resp)
+    resp.__exit__ = MagicMock(return_value=False)
+    return resp
+
+
+def make_http_error(status, reason="Error", body=None):
+    """Create an HTTPError for testing."""
+    error_body = json.dumps(body or {}).encode("utf-8") if body else b""
+    return HTTPError(
+        url="https://api.agenitry.com/v1/events",
+        code=status,
+        msg=reason,
+        hdrs={},
+        fp=BytesIO(error_body),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Constructor tests
+# ---------------------------------------------------------------------------
+
+class TestConstructor:
+    def test_requires_api_key(self):
+        with pytest.raises(AgenitryError, match="api_key"):
+            Agenitry(api_key="", venue_id="my-venue")
+
+    def test_requires_venue_id(self):
+        with pytest.raises(AgenitryError, match="venue_id"):
+            Agenitry(api_key="ag_xxx", venue_id="")
+
+    def test_uses_default_base_url(self):
+        agent = Agenitry(api_key="ag_xxx", venue_id="my-venue")
+        assert agent.base_url == "https://api.agenitry.com"
+
+    def test_strips_trailing_slashes(self):
+        agent = Agenitry(api_key="ag_xxx", venue_id="my-venue", base_url="https://api.agenitry.com///")
+        assert agent.base_url == "https://api.agenitry.com"
+
+
+# ---------------------------------------------------------------------------
+# create_agenitry factory
+# ---------------------------------------------------------------------------
+
+class TestCreateAgenitry:
+    def test_returns_agenitry_instance(self):
+        agent = create_agenitry(api_key="ag_xxx", venue_id="my-venue")
+        assert isinstance(agent, Agenitry)
+
+
+# ---------------------------------------------------------------------------
+# log() tests
+# ---------------------------------------------------------------------------
+
+class TestLog:
+    @patch("agenitry.urlopen")
+    def test_sends_post_to_events(self, mock_urlopen):
+        mock_urlopen.return_value = make_response(
+            {"id": "evt_123", "status": "logged", "created_at": "2025-01-01T00:00:00Z"}
+        )
+        agent = Agenitry(api_key="ag_test", venue_id="my-venue")
+        result = agent.log(action="order_captured", amount=42.5, await_confirmation=True)
+
+        assert result["id"] == "evt_123"
+        assert result["status"] == "logged"
+        call_args = mock_urlopen.call_args
+        req = call_args[0][0]
+        assert req.method == "POST"
+        assert req.full_url == "https://api.agenitry.com/v1/events"
+
+    @patch("agenitry.urlopen")
+    def test_uses_agent_id_from_payload(self, mock_urlopen):
+        mock_urlopen.return_value = make_response(
+            {"id": "evt_123", "status": "logged", "created_at": "2025-01-01T00:00:00Z"}
+        )
+        agent = Agenitry(api_key="ag_test", venue_id="my-venue", agent_id="default-agent")
+        agent.log(action="order_captured", agent_id="custom-agent", await_confirmation=True)
+
+        body = json.loads(mock_urlopen.call_args[0][0].data)
+        assert body["agent_id"] == "custom-agent"
+
+    @patch("agenitry.urlopen")
+    def test_sends_authorization_header(self, mock_urlopen):
+        mock_urlopen.return_value = make_response(
+            {"id": "evt_123", "status": "logged", "created_at": "2025-01-01T00:00:00Z"}
+        )
+        agent = Agenitry(api_key="ag_test", venue_id="my-venue")
+        agent.log(action="order_captured", await_confirmation=True)
+
+        req = mock_urlopen.call_args[0][0]
+        assert req.get_header("Authorization") == "Bearer ag_test"
+
+    @patch("agenitry.urlopen")
+    def test_fire_and_forget_swallows_errors(self, mock_urlopen):
+        mock_urlopen.side_effect = URLError("Connection refused")
+        agent = Agenitry(api_key="ag_test", venue_id="my-venue")
+        result = agent.log(action="order_captured")  # should NOT raise
+        assert result["status"] == "logged"
+        assert result["id"] == ""
+
+    @patch("agenitry.urlopen")
+    def test_await_mode_propagates_errors(self, mock_urlopen):
+        mock_urlopen.side_effect = URLError("Connection refused")
+        agent = Agenitry(api_key="ag_test", venue_id="my-venue")
+        with pytest.raises(AgenitryError, match="network error"):
+            agent.log(action="order_captured", await_confirmation=True)
+
+    @patch("agenitry.urlopen")
+    def test_retries_on_429(self, mock_urlopen):
+        mock_urlopen.side_effect = [
+            make_http_error(429, "Too Many Requests"),
+            make_response({"id": "evt_123", "status": "logged", "created_at": "2025-01-01T00:00:00Z"}),
+        ]
+        agent = Agenitry(api_key="ag_test", venue_id="my-venue", max_retries=2, retry_base_delay=0.01)
+        result = agent.log(action="order_captured", await_confirmation=True)
+        assert result["id"] == "evt_123"
+
+    @patch("agenitry.urlopen")
+    def test_retries_on_500(self, mock_urlopen):
+        mock_urlopen.side_effect = [
+            make_http_error(500, "Internal Server Error"),
+            make_response({"id": "evt_123", "status": "logged", "created_at": "2025-01-01T00:00:00Z"}),
+        ]
+        agent = Agenitry(api_key="ag_test", venue_id="my-venue", max_retries=2, retry_base_delay=0.01)
+        result = agent.log(action="order_captured", await_confirmation=True)
+        assert result["id"] == "evt_123"
+
+    @patch("agenitry.urlopen")
+    def test_does_not_retry_on_400(self, mock_urlopen):
+        mock_urlopen.side_effect = make_http_error(400, "Bad Request", {"error": "Invalid action"})
+        agent = Agenitry(api_key="ag_test", venue_id="my-venue", max_retries=2, retry_base_delay=0.01)
+        with pytest.raises(AgenitryError) as exc_info:
+            agent.log(action="order_captured", await_confirmation=True)
+        assert exc_info.value.status == 400
+
+    @patch("agenitry.urlopen")
+    def test_throws_agenitry_error_with_status_and_body(self, mock_urlopen):
+        mock_urlopen.side_effect = make_http_error(401, "Unauthorized", {"error": "Invalid API key"})
+        agent = Agenitry(api_key="ag_test", venue_id="my-venue")
+        with pytest.raises(AgenitryError) as exc_info:
+            agent.log(action="order_captured", await_confirmation=True)
+        assert exc_info.value.status == 401
+        assert exc_info.value.body == {"error": "Invalid API key"}
+
+    @patch("agenitry.urlopen")
+    def test_throws_network_error_on_url_error(self, mock_urlopen):
+        mock_urlopen.side_effect = URLError("Connection refused")
+        agent = Agenitry(api_key="ag_test", venue_id="my-venue")
+        with pytest.raises(AgenitryError) as exc_info:
+            agent.log(action="order_captured", await_confirmation=True)
+        assert exc_info.value.code == "NETWORK"
+
+
+# ---------------------------------------------------------------------------
+# events() tests
+# ---------------------------------------------------------------------------
+
+class TestEvents:
+    @patch("agenitry.urlopen")
+    def test_fetches_events_with_default_params(self, mock_urlopen):
+        mock_urlopen.return_value = make_response(
+            {"venue_id": "my-venue", "total": 1, "limit": 50, "offset": 0, "has_more": False, "events": []}
+        )
+        agent = Agenitry(api_key="ag_test", venue_id="my-venue")
+        result = agent.events()
+        assert result["venue_id"] == "my-venue"
+
+    @patch("agenitry.urlopen")
+    def test_passes_query_parameters(self, mock_urlopen):
+        mock_urlopen.return_value = make_response(
+            {"venue_id": "my-venue", "total": 0, "limit": 10, "offset": 0, "has_more": False, "events": []}
+        )
+        agent = Agenitry(api_key="ag_test", venue_id="my-venue")
+        agent.events(agent_id="voice-agent", action="order_captured", limit=10)
+        req = mock_urlopen.call_args[0][0]
+        assert "agent_id=voice-agent" in req.full_url
+        assert "action=order_captured" in req.full_url
+        assert "limit=10" in req.full_url
+
+    @patch("agenitry.urlopen")
+    def test_url_encodes_venue_ids(self, mock_urlopen):
+        mock_urlopen.return_value = make_response(
+            {"venue_id": "my venue", "total": 0, "limit": 50, "offset": 0, "has_more": False, "events": []}
+        )
+        agent = Agenitry(api_key="ag_test", venue_id="my venue")
+        agent.events()
+        req = mock_urlopen.call_args[0][0]
+        assert "my%20venue" in req.full_url
+
+
+# ---------------------------------------------------------------------------
+# stats() tests
+# ---------------------------------------------------------------------------
+
+class TestStats:
+    @patch("agenitry.urlopen")
+    def test_fetches_stats_with_default_period(self, mock_urlopen):
+        mock_urlopen.return_value = make_response(
+            {"venue_id": "my-venue", "period": "today", "total_inbound": 0, "total_outbound": 0, "event_count": 0, "by_agent": {}}
+        )
+        agent = Agenitry(api_key="ag_test", venue_id="my-venue")
+        result = agent.stats()
+        assert result["period"] == "today"
+
+    @patch("agenitry.urlopen")
+    def test_passes_period_parameter(self, mock_urlopen):
+        mock_urlopen.return_value = make_response(
+            {"venue_id": "my-venue", "period": "7d", "total_inbound": 0, "total_outbound": 0, "event_count": 0, "by_agent": {}}
+        )
+        agent = Agenitry(api_key="ag_test", venue_id="my-venue")
+        agent.stats(period="7d")
+        req = mock_urlopen.call_args[0][0]
+        assert "period=7d" in req.full_url
+
+    @patch("agenitry.urlopen")
+    def test_returns_by_agent_breakdown(self, mock_urlopen):
+        mock_urlopen.return_value = make_response(
+            {"venue_id": "my-venue", "period": "7d", "total_inbound": 100, "total_outbound": 50, "event_count": 10, "by_agent": {"agent-1": {"events": 10, "inbound": 100, "outbound": 50}}}
+        )
+        agent = Agenitry(api_key="ag_test", venue_id="my-venue")
+        result = agent.stats(period="7d")
+        assert "agent-1" in result["by_agent"]
+
+
+# ---------------------------------------------------------------------------
+# All 6 event actions
+# ---------------------------------------------------------------------------
+
+class TestEventActions:
+    @patch("agenitry.urlopen")
+    def test_logs_action_order_captured(self, mock_urlopen):
+        _test_action(mock_urlopen, "order_captured")
+
+    @patch("agenitry.urlopen")
+    def test_logs_action_reservation_booked(self, mock_urlopen):
+        _test_action(mock_urlopen, "reservation_booked")
+
+    @patch("agenitry.urlopen")
+    def test_logs_action_price_changed(self, mock_urlopen):
+        _test_action(mock_urlopen, "price_changed")
+
+    @patch("agenitry.urlopen")
+    def test_logs_action_item_86d(self, mock_urlopen):
+        _test_action(mock_urlopen, "item_86d")
+
+    @patch("agenitry.urlopen")
+    def test_logs_action_comp_issued(self, mock_urlopen):
+        _test_action(mock_urlopen, "comp_issued")
+
+    @patch("agenitry.urlopen")
+    def test_logs_action_purchase_order(self, mock_urlopen):
+        _test_action(mock_urlopen, "purchase_order")
+
+
+def _test_action(mock_urlopen, action):
+    mock_urlopen.return_value = make_response(
+        {"id": "evt_123", "status": "logged", "created_at": "2025-01-01T00:00:00Z"}
+    )
+    agent = Agenitry(api_key="ag_test", venue_id="my-venue")
+    result = agent.log(action=action, await_confirmation=True)
+    body = json.loads(mock_urlopen.call_args[0][0].data)
+    assert body["action"] == action
+
+
+# ---------------------------------------------------------------------------
+# All 3 event directions
+# ---------------------------------------------------------------------------
+
+class TestEventDirections:
+    @patch("agenitry.urlopen")
+    def test_logs_direction_inbound(self, mock_urlopen):
+        _test_direction(mock_urlopen, "inbound")
+
+    @patch("agenitry.urlopen")
+    def test_logs_direction_outbound(self, mock_urlopen):
+        _test_direction(mock_urlopen, "outbound")
+
+    @patch("agenitry.urlopen")
+    def test_logs_direction_internal(self, mock_urlopen):
+        _test_direction(mock_urlopen, "internal")
+
+
+def _test_direction(mock_urlopen, direction):
+    mock_urlopen.return_value = make_response(
+        {"id": "evt_123", "status": "logged", "created_at": "2025-01-01T00:00:00Z"}
+    )
+    agent = Agenitry(api_key="ag_test", venue_id="my-venue")
+    agent.log(action="order_captured", direction=direction, await_confirmation=True)
+    body = json.loads(mock_urlopen.call_args[0][0].data)
+    assert body["direction"] == direction