agentref 1.0.0__py3-none-any.whl

agentref/__init__.py

@@ -0,0 +1,24 @@
+from .client import AgentRef, AsyncAgentRef
+from .errors import (
+    AgentRefError,
+    AuthError,
+    ConflictError,
+    ForbiddenError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+__all__ = [
+    "AgentRef",
+    "AsyncAgentRef",
+    "AgentRefError",
+    "AuthError",
+    "ForbiddenError",
+    "ValidationError",
+    "NotFoundError",
+    "ConflictError",
+    "RateLimitError",
+    "ServerError",
+]

agentref/_http.py

@@ -0,0 +1,252 @@
+from __future__ import annotations
+
+import asyncio
+import importlib.metadata
+import os
+import time
+from email.utils import parsedate_to_datetime
+from typing import Any, Dict, Mapping, Optional, Set, cast
+
+import httpx
+
+from .errors import (
+    AgentRefError,
+    AuthError,
+    ConflictError,
+    ForbiddenError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+_SAFE_METHODS: Set[str] = {"GET", "HEAD"}
+_DEFAULT_BASE_URL = "https://www.agentref.dev/api/v1"
+_DEFAULT_TIMEOUT = 30.0
+_DEFAULT_MAX_RETRIES = 2
+
+
+def _sdk_version() -> str:
+    try:
+        return importlib.metadata.version("agentref")
+    except importlib.metadata.PackageNotFoundError:
+        return "unknown"
+
+
+def _parse_retry_after_seconds(value: Optional[str]) -> int:
+    if not value:
+        return 60
+
+    try:
+        parsed = float(value)
+        if parsed >= 0:
+            return int(parsed) if parsed.is_integer() else int(parsed) + 1
+    except ValueError:
+        pass
+
+    try:
+        parsed_date = parsedate_to_datetime(value)
+        delta = parsed_date.timestamp() - time.time()
+        if delta <= 0:
+            return 0
+        return int(delta) if float(delta).is_integer() else int(delta) + 1
+    except (TypeError, ValueError, OverflowError):
+        return 60
+
+
+def _can_retry(method: str, idempotency_key: Optional[str]) -> bool:
+    upper = method.upper()
+    return upper in _SAFE_METHODS or (upper == "POST" and idempotency_key is not None)
+
+
+def _json_object(response: httpx.Response) -> Dict[str, Any]:
+    try:
+        payload = response.json()
+    except ValueError:
+        return {}
+
+    if isinstance(payload, dict):
+        return cast(Dict[str, Any], payload)
+
+    return {}
+
+
+class _BaseHttpClient:
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = _DEFAULT_TIMEOUT,
+        max_retries: int = _DEFAULT_MAX_RETRIES,
+    ) -> None:
+        resolved_key = api_key or os.environ.get("AGENTREF_API_KEY")
+        if not resolved_key:
+            raise ValueError(
+                "[AgentRef] API key is required. Pass it as api_key or set AGENTREF_API_KEY environment variable."
+            )
+
+        self._api_key = resolved_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._user_agent = f"agentref-python/{_sdk_version()}"
+
+    def _headers(self, method: str, idempotency_key: Optional[str]) -> Dict[str, str]:
+        headers: Dict[str, str] = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Content-Type": "application/json",
+            "User-Agent": self._user_agent,
+        }
+
+        if method.upper() == "POST" and idempotency_key is not None:
+            headers["Idempotency-Key"] = idempotency_key
+
+        return headers
+
+    def _parse_error(self, response: httpx.Response) -> AgentRefError:
+        payload = _json_object(response)
+        raw_error = payload.get("error")
+        raw_meta = payload.get("meta")
+
+        error = raw_error if isinstance(raw_error, dict) else {}
+        meta = raw_meta if isinstance(raw_meta, dict) else {}
+
+        code = cast(str, error.get("code", "UNKNOWN_ERROR"))
+        message = cast(str, error.get("message", response.reason_phrase))
+        request_id = cast(str, meta.get("requestId", ""))
+        details = error.get("details")
+
+        if response.status_code == 400:
+            return ValidationError(message, code, request_id, details)
+        if response.status_code == 401:
+            return AuthError(message, code, request_id)
+        if response.status_code == 403:
+            return ForbiddenError(message, code, request_id)
+        if response.status_code == 404:
+            return NotFoundError(message, code, request_id)
+        if response.status_code == 409:
+            return ConflictError(message, code, request_id)
+        if response.status_code == 429:
+            retry_after = _parse_retry_after_seconds(response.headers.get("Retry-After"))
+            return RateLimitError(message, code, request_id, retry_after)
+
+        return ServerError(message, code, response.status_code, request_id)
+
+    @staticmethod
+    def _is_retryable(status: int) -> bool:
+        return status == 429 or status >= 500
+
+    @staticmethod
+    def _backoff_seconds(attempt: int) -> float:
+        return float(0.5 * (2 ** attempt))
+
+
+class SyncHttpClient(_BaseHttpClient):
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._client = httpx.Client(base_url=self._base_url, timeout=self._timeout)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        can_retry = _can_retry(method, idempotency_key)
+        attempts = self._max_retries + 1 if can_retry else 1
+
+        for attempt in range(attempts):
+            try:
+                response = self._client.request(
+                    method,
+                    path,
+                    params={k: v for k, v in (params or {}).items() if v is not None},
+                    json=json,
+                    headers=self._headers(method, idempotency_key),
+                )
+            except httpx.HTTPError:
+                if can_retry and attempt < attempts - 1:
+                    time.sleep(self._backoff_seconds(attempt))
+                    continue
+                raise
+
+            if response.is_error:
+                parsed = self._parse_error(response)
+                if can_retry and self._is_retryable(response.status_code) and attempt < attempts - 1:
+                    delay = (
+                        float(_parse_retry_after_seconds(response.headers.get("Retry-After")))
+                        if response.status_code == 429
+                        else self._backoff_seconds(attempt)
+                    )
+                    time.sleep(delay)
+                    continue
+                raise parsed
+
+            return _json_object(response)
+
+        raise ServerError("Request failed after retries", "REQUEST_RETRY_EXHAUSTED", 500, "")
+
+
+class AsyncHttpClient(_BaseHttpClient):
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._client = httpx.AsyncClient(base_url=self._base_url, timeout=self._timeout)
+
+    async def __aenter__(self) -> "AsyncHttpClient":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self._client.aclose()
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        can_retry = _can_retry(method, idempotency_key)
+        attempts = self._max_retries + 1 if can_retry else 1
+
+        for attempt in range(attempts):
+            try:
+                response = await self._client.request(
+                    method,
+                    path,
+                    params={k: v for k, v in (params or {}).items() if v is not None},
+                    json=json,
+                    headers=self._headers(method, idempotency_key),
+                )
+            except httpx.HTTPError:
+                if can_retry and attempt < attempts - 1:
+                    await asyncio.sleep(self._backoff_seconds(attempt))
+                    continue
+                raise
+
+            if response.is_error:
+                parsed = self._parse_error(response)
+                if can_retry and self._is_retryable(response.status_code) and attempt < attempts - 1:
+                    delay = (
+                        float(_parse_retry_after_seconds(response.headers.get("Retry-After")))
+                        if response.status_code == 429
+                        else self._backoff_seconds(attempt)
+                    )
+                    await asyncio.sleep(delay)
+                    continue
+                raise parsed
+
+            return _json_object(response)
+
+        raise ServerError("Request failed after retries", "REQUEST_RETRY_EXHAUSTED", 500, "")

agentref/client.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from ._http import AsyncHttpClient, SyncHttpClient
+from .resources import (
+    AffiliatesResource,
+    AsyncAffiliatesResource,
+    AsyncBillingResource,
+    AsyncConversionsResource,
+    AsyncFlagsResource,
+    AsyncMerchantResource,
+    AsyncPayoutsResource,
+    AsyncProgramsResource,
+    BillingResource,
+    ConversionsResource,
+    FlagsResource,
+    MerchantResource,
+    PayoutsResource,
+    ProgramsResource,
+)
+
+
+class AgentRef:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = "https://www.agentref.dev/api/v1",
+        timeout: float = 30.0,
+        max_retries: int = 2,
+    ) -> None:
+        self._http = SyncHttpClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+
+        self.programs = ProgramsResource(self._http)
+        self.affiliates = AffiliatesResource(self._http)
+        self.conversions = ConversionsResource(self._http)
+        self.payouts = PayoutsResource(self._http)
+        self.flags = FlagsResource(self._http)
+        self.billing = BillingResource(self._http)
+        self.merchant = MerchantResource(self._http)
+
+    def close(self) -> None:
+        self._http.close()
+
+
+class AsyncAgentRef:
+    """Async variant — use as async context manager for connection pooling."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = "https://www.agentref.dev/api/v1",
+        timeout: float = 30.0,
+        max_retries: int = 2,
+    ) -> None:
+        self._http = AsyncHttpClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+
+        self.programs = AsyncProgramsResource(self._http)
+        self.affiliates = AsyncAffiliatesResource(self._http)
+        self.conversions = AsyncConversionsResource(self._http)
+        self.payouts = AsyncPayoutsResource(self._http)
+        self.flags = AsyncFlagsResource(self._http)
+        self.billing = AsyncBillingResource(self._http)
+        self.merchant = AsyncMerchantResource(self._http)
+
+    async def __aenter__(self) -> "AsyncAgentRef":
+        await self._http.__aenter__()
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self._http.__aexit__(*args)

agentref/errors.py

@@ -0,0 +1,62 @@
+from typing import Optional
+
+
+class AgentRefError(Exception):
+    code: str
+    status: int
+    request_id: str
+
+    def __init__(self, message: str, code: str, status: int, request_id: str) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status = status
+        self.request_id = request_id
+
+
+class AuthError(AgentRefError):
+    def __init__(self, message: str, code: str, request_id: str) -> None:
+        super().__init__(message, code, 401, request_id)
+
+
+class ForbiddenError(AgentRefError):
+    """403 — authenticated but not authorized: wrong scope, ownerType, or trust level."""
+
+    def __init__(self, message: str, code: str, request_id: str) -> None:
+        super().__init__(message, code, 403, request_id)
+
+
+class ValidationError(AgentRefError):
+    details: Optional[object]
+
+    def __init__(
+        self,
+        message: str,
+        code: str,
+        request_id: str,
+        details: Optional[object] = None,
+    ) -> None:
+        super().__init__(message, code, 400, request_id)
+        self.details = details
+
+
+class NotFoundError(AgentRefError):
+    def __init__(self, message: str, code: str, request_id: str) -> None:
+        super().__init__(message, code, 404, request_id)
+
+
+class ConflictError(AgentRefError):
+    def __init__(self, message: str, code: str, request_id: str) -> None:
+        super().__init__(message, code, 409, request_id)
+
+
+class RateLimitError(AgentRefError):
+    retry_after: int
+
+    def __init__(self, message: str, code: str, request_id: str, retry_after: int) -> None:
+        super().__init__(message, code, 429, request_id)
+        self.retry_after = retry_after
+
+
+class ServerError(AgentRefError):
+    def __init__(self, message: str, code: str, status: int, request_id: str) -> None:
+        super().__init__(message, code, status, request_id)

agentref/resources/__init__.py

@@ -0,0 +1,24 @@
+from .affiliates import AffiliatesResource, AsyncAffiliatesResource
+from .billing import AsyncBillingResource, BillingResource
+from .conversions import AsyncConversionsResource, ConversionsResource
+from .flags import AsyncFlagsResource, FlagsResource
+from .merchant import AsyncMerchantResource, MerchantResource
+from .payouts import AsyncPayoutsResource, PayoutsResource
+from .programs import AsyncProgramsResource, ProgramsResource
+
+__all__ = [
+    "ProgramsResource",
+    "AffiliatesResource",
+    "ConversionsResource",
+    "PayoutsResource",
+    "FlagsResource",
+    "BillingResource",
+    "MerchantResource",
+    "AsyncProgramsResource",
+    "AsyncAffiliatesResource",
+    "AsyncConversionsResource",
+    "AsyncPayoutsResource",
+    "AsyncFlagsResource",
+    "AsyncBillingResource",
+    "AsyncMerchantResource",
+]

agentref/resources/affiliates.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from .._http import AsyncHttpClient, SyncHttpClient
+from ..types.models import Affiliate, PaginatedResponse
+
+
+class AffiliatesResource:
+    def __init__(self, http: SyncHttpClient) -> None:
+        self._http = http
+
+    def list(
+        self,
+        *,
+        program_id: Optional[str] = None,
+        include_blocked: Optional[bool] = None,
+        cursor: Optional[str] = None,
+        limit: Optional[int] = None,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> PaginatedResponse[Affiliate]:
+        envelope = self._http.request(
+            "GET",
+            "/affiliates",
+            params={
+                "programId": program_id,
+                "includeBlocked": include_blocked,
+                "cursor": cursor,
+                "limit": limit,
+                "page": page,
+                "pageSize": page_size,
+                "offset": offset,
+            },
+        )
+        return PaginatedResponse[Affiliate].model_validate(envelope)
+
+    def get(self, id: str) -> Affiliate:
+        envelope = self._http.request("GET", f"/affiliates/{id}")
+        return Affiliate.model_validate(envelope["data"])
+
+    def approve(self, id: str, *, idempotency_key: Optional[str] = None) -> Affiliate:
+        envelope = self._http.request("POST", f"/affiliates/{id}/approve", idempotency_key=idempotency_key)
+        return Affiliate.model_validate(envelope["data"])
+
+    def block(
+        self,
+        id: str,
+        *,
+        reason: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Affiliate:
+        envelope = self._http.request(
+            "POST",
+            f"/affiliates/{id}/block",
+            json={"reason": reason} if reason is not None else None,
+            idempotency_key=idempotency_key,
+        )
+        return Affiliate.model_validate(envelope["data"])
+
+    def unblock(self, id: str, *, idempotency_key: Optional[str] = None) -> Affiliate:
+        envelope = self._http.request("POST", f"/affiliates/{id}/unblock", idempotency_key=idempotency_key)
+        return Affiliate.model_validate(envelope["data"])
+
+
+class AsyncAffiliatesResource:
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def list(
+        self,
+        *,
+        program_id: Optional[str] = None,
+        include_blocked: Optional[bool] = None,
+        cursor: Optional[str] = None,
+        limit: Optional[int] = None,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> PaginatedResponse[Affiliate]:
+        envelope = await self._http.request(
+            "GET",
+            "/affiliates",
+            params={
+                "programId": program_id,
+                "includeBlocked": include_blocked,
+                "cursor": cursor,
+                "limit": limit,
+                "page": page,
+                "pageSize": page_size,
+                "offset": offset,
+            },
+        )
+        return PaginatedResponse[Affiliate].model_validate(envelope)
+
+    async def get(self, id: str) -> Affiliate:
+        envelope = await self._http.request("GET", f"/affiliates/{id}")
+        return Affiliate.model_validate(envelope["data"])
+
+    async def approve(self, id: str, *, idempotency_key: Optional[str] = None) -> Affiliate:
+        envelope = await self._http.request("POST", f"/affiliates/{id}/approve", idempotency_key=idempotency_key)
+        return Affiliate.model_validate(envelope["data"])
+
+    async def block(
+        self,
+        id: str,
+        *,
+        reason: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Affiliate:
+        envelope = await self._http.request(
+            "POST",
+            f"/affiliates/{id}/block",
+            json={"reason": reason} if reason is not None else None,
+            idempotency_key=idempotency_key,
+        )
+        return Affiliate.model_validate(envelope["data"])
+
+    async def unblock(self, id: str, *, idempotency_key: Optional[str] = None) -> Affiliate:
+        envelope = await self._http.request("POST", f"/affiliates/{id}/unblock", idempotency_key=idempotency_key)
+        return Affiliate.model_validate(envelope["data"])

agentref/resources/billing.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from typing import List, Literal, Optional
+
+from .._http import AsyncHttpClient, SyncHttpClient
+from ..types.models import BillingStatus, BillingTier
+
+
+class BillingResource:
+    def __init__(self, http: SyncHttpClient) -> None:
+        self._http = http
+
+    def current(self) -> BillingStatus:
+        envelope = self._http.request("GET", "/billing")
+        return BillingStatus.model_validate(envelope["data"])
+
+    def tiers(self) -> List[BillingTier]:
+        envelope = self._http.request("GET", "/billing/tiers")
+        raw = envelope.get("data", [])
+        if not isinstance(raw, list):
+            return []
+        return [BillingTier.model_validate(item) for item in raw]
+
+    def subscribe(
+        self,
+        *,
+        tier: Literal["starter", "growth", "pro", "scale"],
+        idempotency_key: Optional[str] = None,
+    ) -> BillingStatus:
+        envelope = self._http.request(
+            "POST",
+            "/billing/subscribe",
+            json={"tier": tier},
+            idempotency_key=idempotency_key,
+        )
+        return BillingStatus.model_validate(envelope["data"])
+
+
+class AsyncBillingResource:
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def current(self) -> BillingStatus:
+        envelope = await self._http.request("GET", "/billing")
+        return BillingStatus.model_validate(envelope["data"])
+
+    async def tiers(self) -> List[BillingTier]:
+        envelope = await self._http.request("GET", "/billing/tiers")
+        raw = envelope.get("data", [])
+        if not isinstance(raw, list):
+            return []
+        return [BillingTier.model_validate(item) for item in raw]
+
+    async def subscribe(
+        self,
+        *,
+        tier: Literal["starter", "growth", "pro", "scale"],
+        idempotency_key: Optional[str] = None,
+    ) -> BillingStatus:
+        envelope = await self._http.request(
+            "POST",
+            "/billing/subscribe",
+            json={"tier": tier},
+            idempotency_key=idempotency_key,
+        )
+        return BillingStatus.model_validate(envelope["data"])