agentref 1.0.0__py3-none-any.whl

agentref/resources/programs.py

@@ -0,0 +1,320 @@
+from __future__ import annotations
+
+from typing import Any, AsyncGenerator, Dict, Generator, List, Literal, Optional
+
+from .._http import AsyncHttpClient, SyncHttpClient
+from ..types.models import Affiliate, Coupon, Invite, PaginatedResponse, Program
+
+
+class ProgramsResource:
+    def __init__(self, http: SyncHttpClient) -> None:
+        self._http = http
+
+    def list(
+        self,
+        *,
+        cursor: Optional[str] = None,
+        limit: Optional[int] = None,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> PaginatedResponse[Program]:
+        envelope = self._http.request(
+            "GET",
+            "/programs",
+            params={"cursor": cursor, "limit": limit, "page": page, "pageSize": page_size, "offset": offset},
+        )
+        return PaginatedResponse[Program].model_validate(envelope)
+
+    def list_all(self, *, page_size: int = 100) -> Generator[Program, None, None]:
+        page = 1
+        while True:
+            result = self.list(limit=page_size, page=page)
+            for item in result.data:
+                yield item
+            if not result.meta.has_more:
+                break
+            page += 1
+
+    def get(self, id: str) -> Program:
+        envelope = self._http.request("GET", f"/programs/{id}")
+        return Program.model_validate(envelope["data"])
+
+    def create(
+        self,
+        *,
+        name: str,
+        commission_type: Literal["one_time", "recurring", "recurring_limited"],
+        commission_percent: float,
+        cookie_duration: Optional[int] = None,
+        payout_threshold: Optional[int] = None,
+        auto_approve_affiliates: Optional[bool] = None,
+        description: Optional[str] = None,
+        landing_page_url: Optional[str] = None,
+        commission_limit_months: Optional[int] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Program:
+        body: Dict[str, Any] = {
+            "name": name,
+            "commissionType": commission_type,
+            "commissionPercent": commission_percent,
+            "cookieDuration": cookie_duration,
+            "payoutThreshold": payout_threshold,
+            "autoApproveAffiliates": auto_approve_affiliates,
+            "description": description,
+            "landingPageUrl": landing_page_url,
+            "commissionLimitMonths": commission_limit_months,
+        }
+        envelope = self._http.request(
+            "POST",
+            "/programs",
+            json={k: v for k, v in body.items() if v is not None},
+            idempotency_key=idempotency_key,
+        )
+        return Program.model_validate(envelope["data"])
+
+    def update(self, id: str, **data: Any) -> Program:
+        envelope = self._http.request("PATCH", f"/programs/{id}", json=data)
+        return Program.model_validate(envelope["data"])
+
+    def delete(self, id: str) -> Program:
+        envelope = self._http.request("DELETE", f"/programs/{id}")
+        return Program.model_validate(envelope["data"])
+
+    def stats(self, id: str, *, period: Optional[str] = None) -> Dict[str, Any]:
+        envelope = self._http.request("GET", f"/programs/{id}/stats", params={"period": period})
+        data = envelope.get("data", {})
+        return data if isinstance(data, dict) else {}
+
+    def list_affiliates(
+        self,
+        id: str,
+        *,
+        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",
+            f"/programs/{id}/affiliates",
+            params={
+                "includeBlocked": include_blocked,
+                "cursor": cursor,
+                "limit": limit,
+                "page": page,
+                "pageSize": page_size,
+                "offset": offset,
+            },
+        )
+        return PaginatedResponse[Affiliate].model_validate(envelope)
+
+    def list_coupons(self, id: str) -> List[Coupon]:
+        envelope = self._http.request("GET", f"/programs/{id}/coupons")
+        raw = envelope.get("data", [])
+        if not isinstance(raw, list):
+            return []
+        return [Coupon.model_validate(item) for item in raw]
+
+    def create_coupon(
+        self,
+        id: str,
+        *,
+        affiliate_id: str,
+        code: str,
+        expires_at: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Coupon:
+        body = {"affiliateId": affiliate_id, "code": code, "expiresAt": expires_at}
+        envelope = self._http.request(
+            "POST",
+            f"/programs/{id}/coupons",
+            json={k: v for k, v in body.items() if v is not None},
+            idempotency_key=idempotency_key,
+        )
+        return Coupon.model_validate(envelope["data"])
+
+    def create_invite(
+        self,
+        id: str,
+        *,
+        email: Optional[str] = None,
+        name: Optional[str] = None,
+        is_public: Optional[bool] = None,
+        usage_limit: Optional[int] = None,
+        expires_in_days: Optional[int] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Invite:
+        body = {
+            "email": email,
+            "name": name,
+            "isPublic": is_public,
+            "usageLimit": usage_limit,
+            "expiresInDays": expires_in_days,
+        }
+        envelope = self._http.request(
+            "POST",
+            f"/programs/{id}/invites",
+            json={k: v for k, v in body.items() if v is not None},
+            idempotency_key=idempotency_key,
+        )
+        return Invite.model_validate(envelope["data"])
+
+
+class AsyncProgramsResource:
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def list(
+        self,
+        *,
+        cursor: Optional[str] = None,
+        limit: Optional[int] = None,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> PaginatedResponse[Program]:
+        envelope = await self._http.request(
+            "GET",
+            "/programs",
+            params={"cursor": cursor, "limit": limit, "page": page, "pageSize": page_size, "offset": offset},
+        )
+        return PaginatedResponse[Program].model_validate(envelope)
+
+    async def list_all(self, *, page_size: int = 100) -> AsyncGenerator[Program, None]:
+        page = 1
+        while True:
+            result = await self.list(limit=page_size, page=page)
+            for item in result.data:
+                yield item
+            if not result.meta.has_more:
+                break
+            page += 1
+
+    async def get(self, id: str) -> Program:
+        envelope = await self._http.request("GET", f"/programs/{id}")
+        return Program.model_validate(envelope["data"])
+
+    async def create(
+        self,
+        *,
+        name: str,
+        commission_type: Literal["one_time", "recurring", "recurring_limited"],
+        commission_percent: float,
+        cookie_duration: Optional[int] = None,
+        payout_threshold: Optional[int] = None,
+        auto_approve_affiliates: Optional[bool] = None,
+        description: Optional[str] = None,
+        landing_page_url: Optional[str] = None,
+        commission_limit_months: Optional[int] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Program:
+        body: Dict[str, Any] = {
+            "name": name,
+            "commissionType": commission_type,
+            "commissionPercent": commission_percent,
+            "cookieDuration": cookie_duration,
+            "payoutThreshold": payout_threshold,
+            "autoApproveAffiliates": auto_approve_affiliates,
+            "description": description,
+            "landingPageUrl": landing_page_url,
+            "commissionLimitMonths": commission_limit_months,
+        }
+        envelope = await self._http.request(
+            "POST",
+            "/programs",
+            json={k: v for k, v in body.items() if v is not None},
+            idempotency_key=idempotency_key,
+        )
+        return Program.model_validate(envelope["data"])
+
+    async def update(self, id: str, **data: Any) -> Program:
+        envelope = await self._http.request("PATCH", f"/programs/{id}", json=data)
+        return Program.model_validate(envelope["data"])
+
+    async def delete(self, id: str) -> Program:
+        envelope = await self._http.request("DELETE", f"/programs/{id}")
+        return Program.model_validate(envelope["data"])
+
+    async def stats(self, id: str, *, period: Optional[str] = None) -> Dict[str, Any]:
+        envelope = await self._http.request("GET", f"/programs/{id}/stats", params={"period": period})
+        data = envelope.get("data", {})
+        return data if isinstance(data, dict) else {}
+
+    async def list_affiliates(
+        self,
+        id: str,
+        *,
+        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",
+            f"/programs/{id}/affiliates",
+            params={
+                "includeBlocked": include_blocked,
+                "cursor": cursor,
+                "limit": limit,
+                "page": page,
+                "pageSize": page_size,
+                "offset": offset,
+            },
+        )
+        return PaginatedResponse[Affiliate].model_validate(envelope)
+
+    async def list_coupons(self, id: str) -> List[Coupon]:
+        envelope = await self._http.request("GET", f"/programs/{id}/coupons")
+        raw = envelope.get("data", [])
+        if not isinstance(raw, list):
+            return []
+        return [Coupon.model_validate(item) for item in raw]
+
+    async def create_coupon(
+        self,
+        id: str,
+        *,
+        affiliate_id: str,
+        code: str,
+        expires_at: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Coupon:
+        body = {"affiliateId": affiliate_id, "code": code, "expiresAt": expires_at}
+        envelope = await self._http.request(
+            "POST",
+            f"/programs/{id}/coupons",
+            json={k: v for k, v in body.items() if v is not None},
+            idempotency_key=idempotency_key,
+        )
+        return Coupon.model_validate(envelope["data"])
+
+    async def create_invite(
+        self,
+        id: str,
+        *,
+        email: Optional[str] = None,
+        name: Optional[str] = None,
+        is_public: Optional[bool] = None,
+        usage_limit: Optional[int] = None,
+        expires_in_days: Optional[int] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Invite:
+        body = {
+            "email": email,
+            "name": name,
+            "isPublic": is_public,
+            "usageLimit": usage_limit,
+            "expiresInDays": expires_in_days,
+        }
+        envelope = await self._http.request(
+            "POST",
+            f"/programs/{id}/invites",
+            json={k: v for k, v in body.items() if v is not None},
+            idempotency_key=idempotency_key,
+        )
+        return Invite.model_validate(envelope["data"])

agentref/types/__init__.py

@@ -0,0 +1,39 @@
+from .models import (
+    Affiliate,
+    BillingStatus,
+    BillingTier,
+    Conversion,
+    ConversionStats,
+    Coupon,
+    Flag,
+    FlagStats,
+    Invite,
+    Merchant,
+    PaginatedResponse,
+    PaginationMeta,
+    PendingAffiliate,
+    Payout,
+    PayoutStats,
+    Program,
+    ResolveFlagParams,
+)
+
+__all__ = [
+    "PaginationMeta",
+    "PaginatedResponse",
+    "Program",
+    "Affiliate",
+    "Conversion",
+    "ConversionStats",
+    "Payout",
+    "PendingAffiliate",
+    "PayoutStats",
+    "Flag",
+    "FlagStats",
+    "ResolveFlagParams",
+    "BillingTier",
+    "BillingStatus",
+    "Merchant",
+    "Coupon",
+    "Invite",
+]

agentref/types/models.py

@@ -0,0 +1,210 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Generic, List, Literal, Optional, TypeVar
+
+from pydantic import BaseModel, ConfigDict
+from pydantic.alias_generators import to_camel
+
+T = TypeVar("T")
+
+_API_CONFIG = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+
+
+class PaginationMeta(BaseModel):
+    model_config = _API_CONFIG
+
+    total: int
+    page: int
+    page_size: int
+    has_more: bool
+    next_cursor: Optional[str] = None
+    request_id: str
+
+
+class PaginatedResponse(BaseModel, Generic[T]):
+    model_config = _API_CONFIG
+
+    data: List[T]
+    meta: PaginationMeta
+
+
+class Program(BaseModel):
+    model_config = _API_CONFIG
+
+    id: str
+    name: str
+    commission_type: str
+    commission_percent: float
+    commission_limit_months: Optional[int] = None
+    cookie_duration: int
+    payout_threshold: int
+    auto_approve_affiliates: bool
+    description: Optional[str] = None
+    landing_page_url: Optional[str] = None
+    status: str
+    is_public: Optional[bool] = None
+    merchant_id: Optional[str] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+
+
+class Affiliate(BaseModel):
+    model_config = _API_CONFIG
+
+    id: str
+    user_id: Optional[str] = None
+    program_id: Optional[str] = None
+    code: Optional[str] = None
+    status: Optional[str] = None
+    total_clicks: Optional[int] = None
+    total_conversions: Optional[int] = None
+    total_earnings: Optional[float] = None
+    created_at: Optional[str] = None
+
+
+class Conversion(BaseModel):
+    model_config = _API_CONFIG
+
+    id: str
+    affiliate_id: Optional[str] = None
+    program_id: Optional[str] = None
+    amount: Optional[float] = None
+    commission: Optional[float] = None
+    status: Optional[str] = None
+    method: Optional[str] = None
+    stripe_session_id: Optional[str] = None
+    created_at: Optional[str] = None
+
+
+class ConversionStats(BaseModel):
+    model_config = _API_CONFIG
+
+    total: int = 0
+    pending: int = 0
+    approved: int = 0
+    total_revenue: float = 0
+    total_commissions: float = 0
+
+
+class Payout(BaseModel):
+    model_config = _API_CONFIG
+
+    id: str
+    affiliate_id: Optional[str] = None
+    amount: Optional[float] = None
+    status: Optional[str] = None
+    method: Optional[str] = None
+    created_at: Optional[str] = None
+    completed_at: Optional[str] = None
+
+
+class PendingAffiliate(BaseModel):
+    model_config = _API_CONFIG
+
+    affiliate_id: Optional[str] = None
+    email: Optional[str] = None
+    name: Optional[str] = None
+    code: Optional[str] = None
+    program_id: Optional[str] = None
+    program_name: Optional[str] = None
+    payout_method: Optional[str] = None
+    paypal_email: Optional[str] = None
+    bank_iban: Optional[str] = None
+    pending_amount: Optional[float] = None
+    currency: Optional[str] = None
+    threshold: Optional[float] = None
+    meets_threshold: Optional[bool] = None
+    commission_count: Optional[int] = None
+    has_payout_method: Optional[bool] = None
+
+
+class PayoutStats(BaseModel):
+    model_config = _API_CONFIG
+
+    total_paid: float = 0
+    total_pending: float = 0
+    count: int = 0
+
+
+class Flag(BaseModel):
+    model_config = _API_CONFIG
+
+    id: str
+    affiliate_id: Optional[str] = None
+    type: Optional[str] = None
+    status: Optional[str] = None
+    details: Optional[Dict[str, Any]] = None
+    note: Optional[str] = None
+    created_at: Optional[str] = None
+    resolved_at: Optional[str] = None
+
+
+class FlagStats(BaseModel):
+    model_config = _API_CONFIG
+
+    open: int = 0
+    reviewed: int = 0
+    dismissed: int = 0
+    confirmed: int = 0
+    total: int = 0
+
+
+class ResolveFlagParams(BaseModel):
+    model_config = _API_CONFIG
+
+    status: Literal["reviewed", "dismissed", "confirmed"]
+    note: Optional[str] = None
+    block_affiliate: bool = False
+
+
+class BillingTier(BaseModel):
+    model_config = _API_CONFIG
+
+    id: str
+    name: str
+    price: float
+    max_revenue: Optional[float] = None
+    features: Optional[List[str]] = None
+    bookable: Optional[bool] = None
+
+
+class BillingStatus(BaseModel):
+    model_config = _API_CONFIG
+
+    tier: Optional[str] = None
+    monthly_revenue: Optional[float] = None
+    next_tier: Optional[str] = None
+    stripe_subscription_id: Optional[str] = None
+
+
+class Merchant(BaseModel):
+    model_config = _API_CONFIG
+
+    id: str
+    email: str
+    company_name: Optional[str] = None
+    domain: Optional[str] = None
+    domain_verified: Optional[bool] = None
+    trust_level: Optional[str] = None
+    stripe_connected: Optional[bool] = None
+    created_at: Optional[str] = None
+
+
+class Coupon(BaseModel):
+    model_config = _API_CONFIG
+
+    id: str
+    code: str
+    affiliate_id: Optional[str] = None
+    program_id: Optional[str] = None
+    created_at: Optional[str] = None
+
+
+class Invite(BaseModel):
+    model_config = _API_CONFIG
+
+    token: Optional[str] = None
+    email: Optional[str] = None
+    program_id: Optional[str] = None
+    expires_at: Optional[str] = None
+    created_at: Optional[str] = None

agentref-1.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,17 @@
+agentref/__init__.py,sha256=SWifBKdppFmIhFX8yZx7Bwk5whf4cRJgPi4L-asBFr4,436
+agentref/_http.py,sha256=gesorbeLTSuWGbBJCjwD9BZjROmnY9JiUgGasHPn09s,8445
+agentref/client.py,sha256=-XNvaDIpJPN1vFtf1jSMOcRy3wICQsHefgfb4a3zkZs,2435
+agentref/errors.py,sha256=VCRxtZqnk8GpQ1e3BO3nUiPJjA7PFgS_5OEjvKuL__Y,1837
+agentref/resources/__init__.py,sha256=tJy_JLhJZLksHo7WG4utl24CrgI3-lJ2O0QtOKOMpbg,820
+agentref/resources/affiliates.py,sha256=aXuWCPRJJR58xWZxZDxxzYNMCdrAnvvPngHC5oKaMvs,4329
+agentref/resources/billing.py,sha256=Wq3CBVeD_gzZ80Kvdln_6z_kn2igvngC6DALLXkRKWo,2138
+agentref/resources/conversions.py,sha256=_rnzLDoXwJqwb49GN2AgOnXXJt9pNGhnyomWyHr3NoY,4332
+agentref/resources/flags.py,sha256=1jbJTsm00X-SDeslhkId-7SDdUhagpj8qxsoghv_0P8,3995
+agentref/resources/merchant.py,sha256=G1dM1_sexka3WAPcCrB3IM6lrCizGQHpjLxRF2mgZwA,1118
+agentref/resources/payouts.py,sha256=aVZUc3O_tUWMDREKW-0Jp76_1hMljKWqzY4O3Is4d7c,5013
+agentref/resources/programs.py,sha256=XPrF_07yws33YKPYPbv812o_1s76Zfr66SvnT_85eO4,11370
+agentref/types/__init__.py,sha256=hsnay8Dmow13hk5XPmZS-tRX7EFhgg03rotxAN6vwTI,635
+agentref/types/models.py,sha256=_mLZgiCSU5kNmlIfp9KfCvo62O-88G_G6zZ1iMKwJkA,5019
+agentref-1.0.0.dist-info/METADATA,sha256=0Ci0b_7Fvxz25Tx9vIhIchfaz8zH_RBZTEL1A8X7NSk,2555
+agentref-1.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+agentref-1.0.0.dist-info/RECORD,,

agentref-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any