agentref 1.0.0__tar.gz

agentref-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.9', '3.11', '3.12']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e .[dev]
+      - run: mypy agentref
+      - run: pytest -v
+      - run: python -m build

agentref-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e .[dev]
+      - run: mypy agentref
+      - run: pytest -v
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

agentref-1.0.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.mypy_cache/
+.pytest_cache/

agentref-1.0.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 1.0.0
+
+- Initial release.
+- Sync + async clients.
+- Typed resources for merchant-facing REST API v1 surfaces.
+- Retry/idempotency safeguards aligned with API safety model.

agentref-1.0.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: agentref
+Version: 1.0.0
+Summary: Official Python SDK for the AgentRef Affiliate API
+Author-email: AgentRef <hi@agentref.dev>
+License: MIT
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == 'dev'
+Requires-Dist: mypy>=1.9.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# AgentRef Python SDK
+
+Official Python SDK for the AgentRef REST API v1.
+
+## Install
+
+```bash
+pip install agentref
+```
+
+## Quickstart
+
+```python
+from agentref import AgentRef
+
+client = AgentRef(api_key="ak_live_...")
+programs = client.programs.list()
+print(programs.meta.request_id)
+```
+
+## Async quickstart
+
+```python
+from agentref import AsyncAgentRef
+
+async with AsyncAgentRef(api_key="ak_live_...") as client:
+    programs = await client.programs.list()
+```
+
+## Authentication
+
+- Uses `Authorization: Bearer <key>`.
+- Supports `ak_live_*`, `ak_aff_*`, `ak_onb_*`.
+- Provide `api_key` directly or set `AGENTREF_API_KEY`.
+
+## Resources
+
+- `client.programs`: `list`, `list_all`, `get`, `create`, `update`, `delete`, `stats`, `list_affiliates`, `list_coupons`, `create_coupon`, `create_invite`
+- `client.affiliates`: `list`, `get`, `approve`, `block`, `unblock`
+- `client.conversions`: `list`, `stats`, `recent`
+- `client.payouts`: `list`, `list_pending`, `stats`
+- `client.flags`: `list`, `stats`, `resolve`
+- `client.billing`: `current`, `tiers`, `subscribe`
+- `client.merchant`: `get`, `domain_status`
+
+## Pagination
+
+List endpoints return `PaginatedResponse[T]` with:
+
+- `meta.total`
+- `meta.page`
+- `meta.page_size`
+- `meta.has_more`
+- `meta.next_cursor`
+- `meta.request_id`
+
+Auto-pagination (`list_all`) stops on `has_more is False`.
+
+## Idempotency and retry behavior
+
+- GET/HEAD: auto-retry on 429/5xx.
+- POST: auto-retry only when `idempotency_key` is provided.
+- PATCH/DELETE: never auto-retry.
+- `Idempotency-Key` header is sent only for POST requests.
+
+## Error handling
+
+```python
+from agentref import AgentRef
+from agentref.errors import ForbiddenError, NotFoundError, RateLimitError, AgentRefError
+
+client = AgentRef(api_key="ak_live_...")
+
+try:
+    client.programs.get("missing-id")
+except ForbiddenError as e:
+    print(e.code, e.request_id)
+except NotFoundError as e:
+    print(e.request_id)
+except RateLimitError as e:
+    print(e.retry_after)
+except AgentRefError as e:
+    print(e.status)
+```

agentref-1.0.0/README.md

@@ -0,0 +1,84 @@
+# AgentRef Python SDK
+
+Official Python SDK for the AgentRef REST API v1.
+
+## Install
+
+```bash
+pip install agentref
+```
+
+## Quickstart
+
+```python
+from agentref import AgentRef
+
+client = AgentRef(api_key="ak_live_...")
+programs = client.programs.list()
+print(programs.meta.request_id)
+```
+
+## Async quickstart
+
+```python
+from agentref import AsyncAgentRef
+
+async with AsyncAgentRef(api_key="ak_live_...") as client:
+    programs = await client.programs.list()
+```
+
+## Authentication
+
+- Uses `Authorization: Bearer <key>`.
+- Supports `ak_live_*`, `ak_aff_*`, `ak_onb_*`.
+- Provide `api_key` directly or set `AGENTREF_API_KEY`.
+
+## Resources
+
+- `client.programs`: `list`, `list_all`, `get`, `create`, `update`, `delete`, `stats`, `list_affiliates`, `list_coupons`, `create_coupon`, `create_invite`
+- `client.affiliates`: `list`, `get`, `approve`, `block`, `unblock`
+- `client.conversions`: `list`, `stats`, `recent`
+- `client.payouts`: `list`, `list_pending`, `stats`
+- `client.flags`: `list`, `stats`, `resolve`
+- `client.billing`: `current`, `tiers`, `subscribe`
+- `client.merchant`: `get`, `domain_status`
+
+## Pagination
+
+List endpoints return `PaginatedResponse[T]` with:
+
+- `meta.total`
+- `meta.page`
+- `meta.page_size`
+- `meta.has_more`
+- `meta.next_cursor`
+- `meta.request_id`
+
+Auto-pagination (`list_all`) stops on `has_more is False`.
+
+## Idempotency and retry behavior
+
+- GET/HEAD: auto-retry on 429/5xx.
+- POST: auto-retry only when `idempotency_key` is provided.
+- PATCH/DELETE: never auto-retry.
+- `Idempotency-Key` header is sent only for POST requests.
+
+## Error handling
+
+```python
+from agentref import AgentRef
+from agentref.errors import ForbiddenError, NotFoundError, RateLimitError, AgentRefError
+
+client = AgentRef(api_key="ak_live_...")
+
+try:
+    client.programs.get("missing-id")
+except ForbiddenError as e:
+    print(e.code, e.request_id)
+except NotFoundError as e:
+    print(e.request_id)
+except RateLimitError as e:
+    print(e.retry_after)
+except AgentRefError as e:
+    print(e.status)
+```

agentref-1.0.0/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-1.0.0/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-1.0.0/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-1.0.0/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-1.0.0/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",
+]