agentvend-sdk 0.0.1__py3-none-any.whl

agentvend_sdk/__init__.py

@@ -0,0 +1,75 @@
+from .agentvend_headers import AgentVendHeaders
+from .hmac_utils import calculate_hmac, calculate_hmac_with_timestamp, constant_time_equals, validate_hmac_signature
+from .verifier import (
+    verify_signature,
+    verify_inbound_hmac,
+    verify_signature_from_headers,
+    verify_inbound_context,
+    verify_signature_from_headers_and_get_user_context,
+    get_user_context,
+    build_gateway_user_context_string,
+    UserContext,
+    SignedUserContext,
+    InboundHmacRequest,
+)
+from .validation_client import validate_agent_key, AgentKeyValidationResult
+from .completion_status import CompletionStatus
+from .usage_client import (
+    DEFAULT_USAGE_PATH_PREFIX,
+    report_completion,
+    report_completion_full,
+    report_completion_with_result,
+    report_progress,
+    report_usage,
+    report_usage_at,
+    UsageReportResponse,
+)
+from .gateway_client import get_request_status, get_request_result, GatewayPollResult
+from .client import (
+    AgentVendClient,
+    DEFAULT_API_URL,
+    DEFAULT_CORE_PATH_PREFIX,
+    DEFAULT_GATEWAY_PATH_PREFIX,
+    ENV_AGENT_ID,
+    ENV_AGENT_SECRET,
+    ENV_API_URL,
+)
+
+__all__ = [
+    "AgentVendHeaders",
+    "calculate_hmac",
+    "calculate_hmac_with_timestamp",
+    "constant_time_equals",
+    "validate_hmac_signature",
+    "verify_signature",
+    "verify_inbound_hmac",
+    "verify_signature_from_headers",
+    "verify_inbound_context",
+    "verify_signature_from_headers_and_get_user_context",
+    "get_user_context",
+    "build_gateway_user_context_string",
+    "UserContext",
+    "SignedUserContext",
+    "InboundHmacRequest",
+    "validate_agent_key",
+    "AgentKeyValidationResult",
+    "CompletionStatus",
+    "report_progress",
+    "report_completion",
+    "report_completion_with_result",
+    "report_completion_full",
+    "report_usage",
+    "report_usage_at",
+    "DEFAULT_USAGE_PATH_PREFIX",
+    "UsageReportResponse",
+    "get_request_status",
+    "get_request_result",
+    "GatewayPollResult",
+    "AgentVendClient",
+    "DEFAULT_API_URL",
+    "ENV_API_URL",
+    "ENV_AGENT_ID",
+    "ENV_AGENT_SECRET",
+    "DEFAULT_CORE_PATH_PREFIX",
+    "DEFAULT_GATEWAY_PATH_PREFIX",
+]

agentvend_sdk/agentvend_headers.py

@@ -0,0 +1,14 @@
+"""Canonical AgentVend HTTP header names."""
+
+
+class AgentVendHeaders:
+    SIGNATURE = "X-AgentVend-Signature"
+    TIMESTAMP = "X-AgentVend-Timestamp"
+    USER_ID = "X-AgentVend-User-ID"
+    PLAN = "X-AgentVend-Plan"
+    ROLES = "X-AgentVend-Roles"
+    QUOTA_REMAINING = "X-AgentVend-Quota-Remaining"
+    SUBSCRIPTION_ACTIVE = "X-AgentVend-Subscription-Active"
+    BILLING_MODEL = "X-AgentVend-Billing-Model"
+    MEASUREMENT_TYPE = "X-AgentVend-Measurement-Type"
+    UNIT_LABEL = "X-AgentVend-Unit-Label"

agentvend_sdk/client.py

@@ -0,0 +1,266 @@
+"""Unified HTTP client: env-based config and URL layout aligned with Java `AgentVendClient`."""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Optional
+
+from .completion_status import CompletionStatus
+from .gateway_client import (
+    DEFAULT_GATEWAY_PATH_PREFIX,
+    GatewayPollResult,
+    get_request_result,
+    get_request_status,
+)
+from .usage_client import (
+    DEFAULT_USAGE_PATH_PREFIX,
+    report_completion,
+    report_completion_full,
+    report_progress,
+    report_usage,
+    report_usage_at,
+    UsageReportResponse,
+)
+from .validation_client import (
+    DEFAULT_CORE_PATH_PREFIX,
+    AgentKeyValidationResult,
+    validate_agent_key,
+)
+
+if TYPE_CHECKING:
+    import requests
+
+ENV_API_URL = "AGENTVEND_API_URL"
+ENV_AGENT_ID = "AGENTVEND_AGENT_ID"
+ENV_AGENT_SECRET = "AGENTVEND_AGENT_SECRET"
+
+# Production API origin; override with `api_url=...` or `AGENTVEND_API_URL` for tests/staging.
+DEFAULT_API_URL = "https://api.agentvend.api"
+
+
+def _trim_trailing_slashes(s: str) -> str:
+    t = s.strip()
+    while t.endswith("/"):
+        t = t[:-1]
+    return t
+
+
+def _join_url(base: str, path: Optional[str]) -> str:
+    b = _trim_trailing_slashes(base)
+    if not path:
+        return b
+    p = path if path.startswith("/") else f"/{path}"
+    return b + p
+
+
+def _first_non_blank(a: Optional[str], b: Optional[str]) -> str:
+    if a is not None and a.strip():
+        return a.strip()
+    if b is not None and b.strip():
+        return b.strip()
+    return ""
+
+
+def _resolve_api_url(api_url: Optional[str]) -> str:
+    if api_url is not None and api_url.strip():
+        return _trim_trailing_slashes(api_url.strip())
+    env = os.environ.get(ENV_API_URL)
+    if env is not None and env.strip():
+        return _trim_trailing_slashes(env.strip())
+    return DEFAULT_API_URL
+
+
+class AgentVendClient:
+    """
+    Single entry point for Core validate, Usage report/progress/complete, and Gateway polling.
+    Explicit constructor arguments override environment variables (same order as Java `Builder`).
+    The API origin defaults to :data:`DEFAULT_API_URL` when neither `api_url` nor ``AGENTVEND_API_URL`` is set.
+    """
+
+    ENV_API_URL = ENV_API_URL
+    ENV_AGENT_ID = ENV_AGENT_ID
+    ENV_AGENT_SECRET = ENV_AGENT_SECRET
+    DEFAULT_API_URL = DEFAULT_API_URL
+    DEFAULT_CORE_PATH_PREFIX = DEFAULT_CORE_PATH_PREFIX
+    DEFAULT_GATEWAY_PATH_PREFIX = DEFAULT_GATEWAY_PATH_PREFIX
+    DEFAULT_USAGE_PATH_PREFIX = DEFAULT_USAGE_PATH_PREFIX
+
+    def __init__(
+        self,
+        *,
+        api_url: Optional[str] = None,
+        core_api_url: Optional[str] = None,
+        gateway_api_url: Optional[str] = None,
+        usage_api_url: Optional[str] = None,
+        core_path_prefix: Optional[str] = None,
+        gateway_path_prefix: Optional[str] = None,
+        usage_path_prefix: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        agent_secret: Optional[str] = None,
+        session: Optional["requests.Session"] = None,
+    ) -> None:
+        resolved = _resolve_api_url(api_url)
+
+        core_base = _trim_trailing_slashes(_first_non_blank(core_api_url, resolved))
+        gw_base = _trim_trailing_slashes(_first_non_blank(gateway_api_url, resolved))
+        usage_base = _trim_trailing_slashes(_first_non_blank(usage_api_url, resolved))
+
+        cp = core_path_prefix if core_path_prefix is not None else DEFAULT_CORE_PATH_PREFIX
+        gp = gateway_path_prefix if gateway_path_prefix is not None else DEFAULT_GATEWAY_PATH_PREFIX
+        up = usage_path_prefix if usage_path_prefix is not None else DEFAULT_USAGE_PATH_PREFIX
+
+        sec = _first_non_blank(agent_secret, os.environ.get(ENV_AGENT_SECRET))
+        if not sec:
+            raise ValueError(
+                f"Agent secret is required: pass agent_secret=... or set environment variable {ENV_AGENT_SECRET}"
+            )
+
+        aid = _first_non_blank(agent_id, os.environ.get(ENV_AGENT_ID))
+        aid_opt: Optional[str] = aid if aid else None
+
+        self._gateway_base_url = gw_base
+        self._gateway_path_prefix = gp
+        self._core_base = core_base
+        self._core_path_prefix = cp
+        self._usage_base = usage_base
+        self._usage_path_prefix = up
+        self._agent_id = aid_opt
+        self._agent_secret = sec
+        self._session = session
+
+    @classmethod
+    def from_env(cls, *, session: Optional["requests.Session"] = None) -> AgentVendClient:
+        """Build from environment (optional `AGENTVEND_API_URL` / agent id / secret). Uses :data:`DEFAULT_API_URL` when unset."""
+        return cls(session=session)
+
+    def validate_agent_key(self, agent_key: str) -> Optional[AgentKeyValidationResult]:
+        return validate_agent_key(
+            self._core_base,
+            agent_key,
+            self._agent_secret,
+            self._agent_id,
+            core_path_prefix=self._core_path_prefix,
+            session=self._session,
+        )
+
+    def report_usage(
+        self,
+        user_id: str,
+        agent_id: str,
+        units_used: float,
+        *,
+        session: Optional["requests.Session"] = None,
+    ) -> UsageReportResponse:
+        return report_usage(
+            self._usage_base,
+            user_id,
+            agent_id,
+            units_used,
+            self._agent_secret,
+            usage_path_prefix=self._usage_path_prefix,
+            session=session or self._session,
+        )
+
+    def report_usage_at(
+        self,
+        user_id: str,
+        agent_id: str,
+        units_used: float,
+        timestamp: Optional[float],
+        *,
+        session: Optional["requests.Session"] = None,
+    ) -> UsageReportResponse:
+        return report_usage_at(
+            self._usage_base,
+            user_id,
+            agent_id,
+            units_used,
+            self._agent_secret,
+            timestamp=timestamp,
+            usage_path_prefix=self._usage_path_prefix,
+            session=session or self._session,
+        )
+
+    def send_progress_update(
+        self,
+        progress_url: str,
+        request_id: str,
+        stage: str,
+        percentage_complete: int,
+        error_message: Optional[str] = None,
+        *,
+        session: Optional["requests.Session"] = None,
+    ) -> bool:
+        return report_progress(
+            progress_url,
+            request_id,
+            stage,
+            percentage_complete,
+            self._agent_secret,
+            error_message,
+            session=session or self._session,
+        )
+
+    def send_completion(
+        self,
+        callback_url: str,
+        request_id: str,
+        status: CompletionStatus,
+        units: float,
+        *,
+        result: Optional[str] = None,
+        result_url: Optional[str] = None,
+        content_type: Optional[str] = None,
+        session: Optional["requests.Session"] = None,
+    ) -> bool:
+        sess = session or self._session
+        if result is not None or result_url is not None or content_type is not None:
+            return report_completion_full(
+                callback_url,
+                request_id,
+                status,
+                self._agent_secret,
+                result=result,
+                result_url=result_url,
+                content_type=content_type,
+                units=units,
+                session=sess,
+            )
+        return report_completion(
+            callback_url,
+            request_id,
+            status,
+            self._agent_secret,
+            units=units,
+            session=sess,
+        )
+
+    def get_request_status(
+        self,
+        request_id: str,
+        agent_key: str,
+        *,
+        session: Optional["requests.Session"] = None,
+    ) -> GatewayPollResult:
+        return get_request_status(
+            self._gateway_base_url,
+            request_id,
+            agent_key,
+            gateway_path_prefix=self._gateway_path_prefix,
+            session=session or self._session,
+        )
+
+    def get_request_result(
+        self,
+        request_id: str,
+        agent_key: str,
+        *,
+        session: Optional["requests.Session"] = None,
+    ) -> GatewayPollResult:
+        return get_request_result(
+            self._gateway_base_url,
+            request_id,
+            agent_key,
+            gateway_path_prefix=self._gateway_path_prefix,
+            session=session or self._session,
+        )

agentvend_sdk/completion_status.py

@@ -0,0 +1,12 @@
+from enum import Enum
+
+
+class CompletionStatus(str, Enum):
+    """Completion status for usage async completion (sdk-api-spec §3.3)."""
+
+    COMPLETED = "COMPLETED"
+    FAILED = "FAILED"
+
+    @property
+    def api_value(self) -> str:
+        return self.value

agentvend_sdk/gateway_client.py

@@ -0,0 +1,71 @@
+"""Caller-side gateway polling (docs/sdk-api-spec.md §1.3–1.4)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    import requests
+
+DEFAULT_GATEWAY_PATH_PREFIX = "/api"
+
+
+def _normalize_base(url: str) -> str:
+    return url.rstrip("/")
+
+
+def _normalize_prefix(prefix: str) -> str:
+    if not prefix:
+        return ""
+    p = prefix if prefix.startswith("/") else f"/{prefix}"
+    return p.rstrip("/")
+
+
+def _build_url(gateway_base_url: str, gateway_path_prefix: str, suffix: str) -> str:
+    return f"{_normalize_base(gateway_base_url)}{_normalize_prefix(gateway_path_prefix)}{suffix}"
+
+
+@dataclass
+class GatewayPollResult:
+    ok: bool
+    status_code: int
+    body: str
+
+
+def get_request_status(
+    base_url: str,
+    request_id: str,
+    agent_key: str,
+    *,
+    gateway_path_prefix: str = DEFAULT_GATEWAY_PATH_PREFIX,
+    session: Optional["requests.Session"] = None,
+) -> GatewayPollResult:
+    """GET .../requests/{request_id}/status with Bearer agent key."""
+    try:
+        import requests
+    except ImportError as e:
+        raise ImportError("get_request_status requires 'requests'. pip install requests") from e
+    url = _build_url(base_url, gateway_path_prefix, f"/requests/{request_id}/status")
+    sess = session or requests.Session()
+    resp = sess.get(url, headers={"Authorization": f"Bearer {agent_key}"}, timeout=60)
+    return GatewayPollResult(ok=resp.ok, status_code=resp.status_code, body=resp.text or "")
+
+
+def get_request_result(
+    base_url: str,
+    request_id: str,
+    agent_key: str,
+    *,
+    gateway_path_prefix: str = DEFAULT_GATEWAY_PATH_PREFIX,
+    session: Optional["requests.Session"] = None,
+) -> GatewayPollResult:
+    """GET .../requests/{request_id}/result with Bearer agent key."""
+    try:
+        import requests
+    except ImportError as e:
+        raise ImportError("get_request_result requires 'requests'. pip install requests") from e
+    url = _build_url(base_url, gateway_path_prefix, f"/requests/{request_id}/result")
+    sess = session or requests.Session()
+    resp = sess.get(url, headers={"Authorization": f"Bearer {agent_key}"}, timeout=60)
+    return GatewayPollResult(ok=resp.ok, status_code=resp.status_code, body=resp.text or "")

agentvend_sdk/hmac_utils.py

@@ -0,0 +1,34 @@
+import base64
+import hmac
+import hashlib
+from typing import Optional
+
+
+def calculate_hmac(data: str, key: str) -> str:
+    """HMAC-SHA256, UTF-8, Base64 (per docs/hmac-spec.md)."""
+    digest = hmac.new(key.encode("utf-8"), data.encode("utf-8"), hashlib.sha256).digest()
+    return base64.b64encode(digest).decode("ascii")
+
+
+def calculate_hmac_with_timestamp(body_string: str, timestamp: str, key: str) -> str:
+    """Outbound: canonical = bodyString + timestamp."""
+    return calculate_hmac(body_string + timestamp, key)
+
+
+def constant_time_equals(a: Optional[str], b: Optional[str]) -> bool:
+    """Constant-time comparison to avoid timing attacks."""
+    if a is None or b is None:
+        return a is b
+    if len(a) != len(b):
+        return False
+    return hmac.compare_digest(a.encode("utf-8"), b.encode("utf-8"))
+
+
+def validate_hmac_signature(signature: str, payload_string: str, key: str) -> bool:
+    if not signature or not key:
+        return False
+    try:
+        expected = calculate_hmac(payload_string, key)
+        return constant_time_equals(expected, signature)
+    except Exception:
+        return False

agentvend_sdk/usage_client.py

@@ -0,0 +1,212 @@
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+from urllib.parse import parse_qs, urlparse
+
+from .agentvend_headers import AgentVendHeaders
+from .completion_status import CompletionStatus
+from .hmac_utils import calculate_hmac_with_timestamp
+
+DEFAULT_USAGE_PATH_PREFIX = "/api/usage"
+
+
+def _usage_report_url(base_url: str, usage_path_prefix: Optional[str]) -> str:
+    base = base_url.rstrip("/")
+    p = (usage_path_prefix or DEFAULT_USAGE_PATH_PREFIX).strip()
+    if not p.startswith("/"):
+        p = "/" + p
+    p = p.rstrip("/")
+    return f"{base}{p}/report"
+
+
+@dataclass
+class UsageReportResponse:
+    status: Optional[str]
+    is_over_limit: bool
+    remaining_requests_per_period: int
+
+
+def _parse_url_params(url: str) -> tuple[str, Optional[str]]:
+    parsed = urlparse(url)
+    base = f"{parsed.scheme}://{parsed.netloc}{parsed.path}" if parsed.scheme else url.split("?")[0]
+    if not parsed.query:
+        return base, None
+    qs = parse_qs(parsed.query)
+    timestamp = (qs.get("timestamp") or [None])[0]
+    return base, timestamp
+
+
+def report_progress(
+    progress_url: str,
+    request_id: str,
+    stage: str,
+    percentage_complete: int,
+    agent_secret: str,
+    error_message: Optional[str] = None,
+    *,
+    session: Optional["requests.Session"] = None,
+) -> bool:
+    """POST progress to usage service. Requires 'requests'."""
+    try:
+        import requests
+    except ImportError:
+        raise ImportError("report_progress requires 'requests'. pip install requests")
+    base_url, timestamp = _parse_url_params(progress_url)
+    if not timestamp:
+        return False
+    body = {"stage": stage, "percentageComplete": percentage_complete, "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")}
+    if error_message is not None:
+        body["errorMessage"] = error_message
+    body_str = json.dumps(body)
+    signature = calculate_hmac_with_timestamp(body_str, timestamp, agent_secret)
+    sess = session or __import__("requests").Session()
+    resp = sess.post(
+        base_url,
+        json=body,
+        headers={AgentVendHeaders.SIGNATURE: signature, AgentVendHeaders.TIMESTAMP: timestamp},
+    )
+    return resp.ok
+
+
+def report_completion(
+    callback_url: str,
+    request_id: str,
+    status: CompletionStatus,
+    agent_secret: str,
+    *,
+    units: float = 0.0,
+    session: Optional["requests.Session"] = None,
+) -> bool:
+    """POST completion with status and units only."""
+    return report_completion_full(
+        callback_url,
+        request_id,
+        status,
+        agent_secret,
+        units=units,
+        session=session,
+    )
+
+
+def report_completion_with_result(
+    callback_url: str,
+    request_id: str,
+    status: CompletionStatus,
+    agent_secret: str,
+    result: str,
+    *,
+    units: float = 0.0,
+    session: Optional["requests.Session"] = None,
+) -> bool:
+    """POST completion with inline result text."""
+    return report_completion_full(
+        callback_url,
+        request_id,
+        status,
+        agent_secret,
+        result=result,
+        units=units,
+        session=session,
+    )
+
+
+def report_completion_full(
+    callback_url: str,
+    request_id: str,
+    status: CompletionStatus,
+    agent_secret: str,
+    *,
+    result: Optional[str] = None,
+    result_url: Optional[str] = None,
+    content_type: Optional[str] = None,
+    units: float = 0.0,
+    session: Optional["requests.Session"] = None,
+) -> bool:
+    try:
+        import requests
+    except ImportError:
+        raise ImportError("report_completion_full requires 'requests'. pip install requests")
+    base_url, timestamp = _parse_url_params(callback_url)
+    if not timestamp:
+        return False
+    body = {
+        "status": status.api_value,
+        "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        "units": units,
+    }
+    if result is not None:
+        body["result"] = result
+    if result_url is not None:
+        body["resultUrl"] = result_url
+    if content_type is not None:
+        body["contentType"] = content_type
+    body_str = json.dumps(body)
+    signature = calculate_hmac_with_timestamp(body_str, timestamp, agent_secret)
+    sess = session or requests.Session()
+    resp = sess.post(
+        base_url,
+        json=body,
+        headers={AgentVendHeaders.SIGNATURE: signature, AgentVendHeaders.TIMESTAMP: timestamp},
+    )
+    return resp.ok
+
+
+def report_usage(
+    base_url: str,
+    user_id: str,
+    agent_id: str,
+    units_used: float,
+    agent_secret: str,
+    *,
+    usage_path_prefix: Optional[str] = None,
+    session: Optional["requests.Session"] = None,
+) -> UsageReportResponse:
+    """Report usage with current time as timestamp."""
+    return report_usage_at(
+        base_url,
+        user_id,
+        agent_id,
+        units_used,
+        agent_secret,
+        timestamp=None,
+        usage_path_prefix=usage_path_prefix,
+        session=session,
+    )
+
+
+def report_usage_at(
+    base_url: str,
+    user_id: str,
+    agent_id: str,
+    units_used: float,
+    agent_secret: str,
+    timestamp: Optional[float] = None,
+    *,
+    usage_path_prefix: Optional[str] = None,
+    session: Optional["requests.Session"] = None,
+) -> UsageReportResponse:
+    try:
+        import requests
+        import time
+    except ImportError:
+        raise ImportError("report_usage requires 'requests'. pip install requests")
+    ts_ms = int((timestamp or time.time()) * 1000)
+    body = {"userId": user_id, "agentId": agent_id, "unitsUsed": units_used, "timestamp": ts_ms}
+    body_str = json.dumps(body)
+    ts_str = str(ts_ms)
+    signature = calculate_hmac_with_timestamp(body_str, ts_str, agent_secret)
+    url = _usage_report_url(base_url, usage_path_prefix)
+    sess = session or requests.Session()
+    resp = sess.post(
+        url,
+        json=body,
+        headers={AgentVendHeaders.SIGNATURE: signature, AgentVendHeaders.TIMESTAMP: ts_str},
+    )
+    resp.raise_for_status()
+    data = resp.json()
+    return UsageReportResponse(
+        status=data.get("status"),
+        is_over_limit=bool(data.get("isOverLimit")),
+        remaining_requests_per_period=int(data.get("remainingRequestsPerPeriod", 0)),
+    )