chatads-sdk 0.1.0__tar.gz

chatads_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: chatads-sdk
+Version: 0.1.0
+Summary: Lightweight Python client for the ChatAds affiliate scoring API
+Author-email: ChatAds <support@getchatads.com>
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1.0,>=0.27
+Provides-Extra: async
+Requires-Dist: httpx[http2]<1.0,>=0.27; extra == "async"
+
+# ChatAds Python SDK
+
+A tiny, dependency-light wrapper around the ChatAds `/v1/chatads-script` endpoint. It mirrors the response payloads returned by the FastAPI service so you can drop it into CLIs, serverless functions, or orchestration tools.
+
+## Installation
+
+```bash
+pip install .
+```
+
+(Or build/upload to your internal index as needed.)
+
+## Quickstart
+
+```python
+from chatads_sdk import ChatAdsClient, FunctionItemPayload
+
+client = ChatAdsClient(
+    api_key="YOUR_X_API_KEY",
+    base_url="https://<your-chatads-domain>",
+    raise_on_failure=True,        # Treat success=False payloads as exceptions
+    max_retries=2,                # Optional automatic retries for 429/5xx responses
+    retry_backoff_factor=0.75,    # Exponential backoff multiplier
+)
+
+payload = FunctionItemPayload(
+    message="Looking for a CRM to close more deals",
+    ip="1.2.3.4",
+    user_agent="Mozilla/5.0",
+)
+
+result = client.analyze(payload)
+
+if result.success:
+    print(result.data.ad)
+else:
+    print(result.error.code, result.error.message)
+```
+
+## Error Handling
+
+Non-2xx responses raise `ChatAdsAPIError` and include the parsed error payload plus the original HTTP status code so you can branch on quota/validation failures. Set `raise_on_failure=True` if you want 200 responses with `success=false` to raise the same exception class.
+
+## Notes
+
+- Retries are opt-in. Provide `max_retries>0` to automatically retry transport errors and retryable status codes. The client honors `Retry-After` headers and falls back to exponential backoff.
+- `FunctionItemPayload` matches the server-side `FunctionItem` pydantic model. Keyword arguments passed to `ChatAdsClient.analyze_message()` accept either snake_case (`user_agent`) or camelCase (`userAgent`) keys.
+- Reserved payload keys (e.g., `message`, `pageUrl`, `userAgent`) cannot be overridden through `extra_fields`; doing so raises `ValueError` to prevent silent mutations.
+
+## CLI Smoke Test
+
+For a super-quick check, edit the config block at the top of `python_sdk/run_sdk_smoke.py` (or set the
+`CHATADS_*` env vars) and run:
+
+```bash
+PYTHONPATH=python_sdk python python_sdk/run_sdk_smoke.py
+```
+
+It prints the raw JSON response or surfaces a `ChatAdsAPIError` with status/error fields so you can see
+exactly what the API returned.
+
+- `API_KEY` and `MESSAGE` are the only required values. Leave `CALLER_IP`, `USER_AGENT`, or `CHATADS_EXTRA_FIELDS`
+  blank to omit them from the request.

chatads_sdk-0.1.0/README.md

@@ -0,0 +1,63 @@
+# ChatAds Python SDK
+
+A tiny, dependency-light wrapper around the ChatAds `/v1/chatads-script` endpoint. It mirrors the response payloads returned by the FastAPI service so you can drop it into CLIs, serverless functions, or orchestration tools.
+
+## Installation
+
+```bash
+pip install .
+```
+
+(Or build/upload to your internal index as needed.)
+
+## Quickstart
+
+```python
+from chatads_sdk import ChatAdsClient, FunctionItemPayload
+
+client = ChatAdsClient(
+    api_key="YOUR_X_API_KEY",
+    base_url="https://<your-chatads-domain>",
+    raise_on_failure=True,        # Treat success=False payloads as exceptions
+    max_retries=2,                # Optional automatic retries for 429/5xx responses
+    retry_backoff_factor=0.75,    # Exponential backoff multiplier
+)
+
+payload = FunctionItemPayload(
+    message="Looking for a CRM to close more deals",
+    ip="1.2.3.4",
+    user_agent="Mozilla/5.0",
+)
+
+result = client.analyze(payload)
+
+if result.success:
+    print(result.data.ad)
+else:
+    print(result.error.code, result.error.message)
+```
+
+## Error Handling
+
+Non-2xx responses raise `ChatAdsAPIError` and include the parsed error payload plus the original HTTP status code so you can branch on quota/validation failures. Set `raise_on_failure=True` if you want 200 responses with `success=false` to raise the same exception class.
+
+## Notes
+
+- Retries are opt-in. Provide `max_retries>0` to automatically retry transport errors and retryable status codes. The client honors `Retry-After` headers and falls back to exponential backoff.
+- `FunctionItemPayload` matches the server-side `FunctionItem` pydantic model. Keyword arguments passed to `ChatAdsClient.analyze_message()` accept either snake_case (`user_agent`) or camelCase (`userAgent`) keys.
+- Reserved payload keys (e.g., `message`, `pageUrl`, `userAgent`) cannot be overridden through `extra_fields`; doing so raises `ValueError` to prevent silent mutations.
+
+## CLI Smoke Test
+
+For a super-quick check, edit the config block at the top of `python_sdk/run_sdk_smoke.py` (or set the
+`CHATADS_*` env vars) and run:
+
+```bash
+PYTHONPATH=python_sdk python python_sdk/run_sdk_smoke.py
+```
+
+It prints the raw JSON response or surfaces a `ChatAdsAPIError` with status/error fields so you can see
+exactly what the API returned.
+
+- `API_KEY` and `MESSAGE` are the only required values. Leave `CALLER_IP`, `USER_AGENT`, or `CHATADS_EXTRA_FIELDS`
+  blank to omit them from the request.

chatads_sdk-0.1.0/chatads_sdk/__init__.py

@@ -0,0 +1,27 @@
+"""Public exports for the ChatAds Python SDK."""
+
+from .client import ChatAdsClient, AsyncChatAdsClient
+from .models import (
+    ChatAdsAd,
+    ChatAdsData,
+    ChatAdsError,
+    ChatAdsMeta,
+    ChatAdsResponse,
+    FunctionItemPayload,
+    UsageInfo,
+)
+from .exceptions import ChatAdsAPIError, ChatAdsSDKError
+
+__all__ = [
+    "ChatAdsClient",
+    "AsyncChatAdsClient",
+    "ChatAdsAd",
+    "ChatAdsData",
+    "ChatAdsError",
+    "ChatAdsMeta",
+    "ChatAdsResponse",
+    "FunctionItemPayload",
+    "UsageInfo",
+    "ChatAdsAPIError",
+    "ChatAdsSDKError",
+]

chatads_sdk-0.1.0/chatads_sdk/client.py

@@ -0,0 +1,385 @@
+"""HTTP clients for interacting with the ChatAds API."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import time
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from typing import Any, Dict, Iterable, Optional, Set
+
+import httpx
+
+from .exceptions import ChatAdsAPIError, ChatAdsSDKError
+from .models import (
+    ChatAdsResponse,
+    FunctionItemPayload,
+    FUNCTION_ITEM_FIELD_ALIASES,
+    FUNCTION_ITEM_OPTIONAL_FIELDS,
+)
+
+_DEFAULT_ENDPOINT = "/chatads-script"
+_DEFAULT_RETRY_STATUSES = frozenset({408, 429, 500, 502, 503, 504})
+_FUNCTION_ITEM_OPTIONAL_FIELDS = set(FUNCTION_ITEM_OPTIONAL_FIELDS)
+_FIELD_ALIAS_LOOKUP = {alias.lower(): field for alias, field in FUNCTION_ITEM_FIELD_ALIASES.items()}
+
+
+class ChatAdsClient:
+    """Synchronous ChatAds API client."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str,
+        *,
+        endpoint: str = _DEFAULT_ENDPOINT,
+        timeout: float = 10.0,
+        http_client: Optional[httpx.Client] = None,
+        raise_on_failure: bool = False,
+        max_retries: int = 0,
+        retry_backoff_factor: float = 0.5,
+        retry_statuses: Optional[Iterable[int]] = None,
+        logger: Optional[logging.Logger] = None,
+        debug: bool = False,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        if not base_url:
+            raise ValueError("base_url is required")
+
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._endpoint = endpoint if endpoint.startswith("/") else f"/{endpoint}"
+        self._timeout = timeout
+        self._client = http_client or httpx.Client(timeout=timeout)
+        self._owns_client = http_client is None
+        self._raise_on_failure = raise_on_failure
+        self._max_retries = max(0, int(max_retries))
+        self._retry_backoff_factor = max(0.0, float(retry_backoff_factor))
+        self._retry_statuses: Set[int] = (
+            set(retry_statuses) if retry_statuses is not None else set(_DEFAULT_RETRY_STATUSES)
+        )
+        self._logger = logger or logging.getLogger("chatads_sdk")
+        self._debug = debug
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> "ChatAdsClient":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:  # type: ignore[override]
+        self.close()
+
+    def analyze(
+        self,
+        payload: FunctionItemPayload,
+        *,
+        timeout: Optional[float] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> ChatAdsResponse:
+        """Send a FunctionItem payload to the ChatAds endpoint."""
+        body = payload.to_payload()
+        return self._post(body, timeout=timeout, headers=headers)
+
+    def analyze_message(
+        self,
+        message: str,
+        *,
+        timeout: Optional[float] = None,
+        headers: Optional[Dict[str, str]] = None,
+        **extra_fields: Any,
+    ) -> ChatAdsResponse:
+        """
+        Convenience wrapper taking only the message plus optional FunctionItem fields.
+        """
+        payload = _build_payload_from_kwargs(message, extra_fields)
+        return self.analyze(payload, timeout=timeout, headers=headers)
+
+    def _post(
+        self,
+        body: Dict[str, Any],
+        *,
+        timeout: Optional[float],
+        headers: Optional[Dict[str, str]],
+    ) -> ChatAdsResponse:
+        request_headers = {"x-api-key": self._api_key, **(headers or {})}
+        url = f"{self._base_url}{self._endpoint}"
+        attempt = 0
+        while True:
+            try:
+                self._log_request(url, request_headers, body)
+                response = self._client.post(
+                    url,
+                    json=body,
+                    headers=request_headers,
+                    timeout=timeout or self._timeout,
+                )
+            except httpx.RequestError as exc:
+                if attempt >= self._max_retries:
+                    raise ChatAdsSDKError(f"Transport error while calling ChatAds: {exc}") from exc
+                _sleep_sync(
+                    _compute_retry_delay(attempt, self._retry_backoff_factor, None)
+                )
+                attempt += 1
+                continue
+
+            parsed = _parse_response(response)
+            self._log_response(response, parsed)
+            is_error = response.is_error or (self._raise_on_failure and not parsed.success)
+            if not is_error:
+                return parsed
+
+            api_error = ChatAdsAPIError(
+                status_code=response.status_code,
+                payload=parsed.raw,
+                response=parsed,
+                headers=dict(response.headers),
+                request_body=body,
+                url=url,
+            )
+            if attempt < self._max_retries and self._should_retry_status(response.status_code):
+                _sleep_sync(
+                    _compute_retry_delay(attempt, self._retry_backoff_factor, api_error.retry_after)
+                )
+                attempt += 1
+                continue
+            raise api_error
+
+    def _should_retry_status(self, status_code: int) -> bool:
+        return status_code in self._retry_statuses
+
+    def _log_request(self, url: str, headers: Dict[str, str], body: Dict[str, Any]) -> None:
+        if not self._debug:
+            return
+        safe_headers = {k: v for k, v in headers.items() if k.lower() != "x-api-key"}
+        self._logger.info("ChatAds request -> %s", url)
+        self._logger.info("Headers: %s", safe_headers)
+        self._logger.info("Body: %s", json.dumps(body, indent=2))
+
+    def _log_response(self, response: httpx.Response, parsed: ChatAdsResponse) -> None:
+        if not self._debug:
+            return
+        self._logger.info(
+            "ChatAds response <- %s %s (status=%s)",
+            response.request.method if response.request else "POST",
+            response.request.url if response.request else "<unknown>",
+            response.status_code,
+        )
+        self._logger.info("Payload: %s", json.dumps(parsed.raw, indent=2))
+
+
+class AsyncChatAdsClient:
+    """Asynchronous version backed by httpx.AsyncClient."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str,
+        *,
+        endpoint: str = _DEFAULT_ENDPOINT,
+        timeout: float = 10.0,
+        http_client: Optional[httpx.AsyncClient] = None,
+        raise_on_failure: bool = False,
+        max_retries: int = 0,
+        retry_backoff_factor: float = 0.5,
+        retry_statuses: Optional[Iterable[int]] = None,
+        logger: Optional[logging.Logger] = None,
+        debug: bool = False,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        if not base_url:
+            raise ValueError("base_url is required")
+
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._endpoint = endpoint if endpoint.startswith("/") else f"/{endpoint}"
+        self._timeout = timeout
+        self._client = http_client or httpx.AsyncClient(timeout=timeout)
+        self._owns_client = http_client is None
+        self._raise_on_failure = raise_on_failure
+        self._max_retries = max(0, int(max_retries))
+        self._retry_backoff_factor = max(0.0, float(retry_backoff_factor))
+        self._retry_statuses: Set[int] = (
+            set(retry_statuses) if retry_statuses is not None else set(_DEFAULT_RETRY_STATUSES)
+        )
+        self._logger = logger or logging.getLogger("chatads_sdk")
+        self._debug = debug
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncChatAdsClient":
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:  # type: ignore[override]
+        await self.aclose()
+
+    async def analyze(
+        self,
+        payload: FunctionItemPayload,
+        *,
+        timeout: Optional[float] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> ChatAdsResponse:
+        body = payload.to_payload()
+        return await self._post(body, timeout=timeout, headers=headers)
+
+    async def analyze_message(
+        self,
+        message: str,
+        *,
+        timeout: Optional[float] = None,
+        headers: Optional[Dict[str, str]] = None,
+        **extra_fields: Any,
+    ) -> ChatAdsResponse:
+        payload = _build_payload_from_kwargs(message, extra_fields)
+        return await self.analyze(payload, timeout=timeout, headers=headers)
+
+    async def _post(
+        self,
+        body: Dict[str, Any],
+        *,
+        timeout: Optional[float],
+        headers: Optional[Dict[str, str]],
+    ) -> ChatAdsResponse:
+        request_headers = {"x-api-key": self._api_key, **(headers or {})}
+        url = f"{self._base_url}{self._endpoint}"
+        attempt = 0
+        while True:
+            try:
+                self._log_request(url, request_headers, body)
+                response = await self._client.post(
+                    url,
+                    json=body,
+                    headers=request_headers,
+                    timeout=timeout or self._timeout,
+                )
+            except httpx.RequestError as exc:
+                if attempt >= self._max_retries:
+                    raise ChatAdsSDKError(f"Transport error while calling ChatAds: {exc}") from exc
+                await _sleep_async(
+                    _compute_retry_delay(attempt, self._retry_backoff_factor, None)
+                )
+                attempt += 1
+                continue
+
+            parsed = _parse_response(response)
+            self._log_response(response, parsed)
+            is_error = response.is_error or (self._raise_on_failure and not parsed.success)
+            if not is_error:
+                return parsed
+
+            api_error = ChatAdsAPIError(
+                status_code=response.status_code,
+                payload=parsed.raw,
+                response=parsed,
+                headers=dict(response.headers),
+                request_body=body,
+                url=url,
+            )
+            if attempt < self._max_retries and self._should_retry_status(response.status_code):
+                await _sleep_async(
+                    _compute_retry_delay(attempt, self._retry_backoff_factor, api_error.retry_after)
+                )
+                attempt += 1
+                continue
+            raise api_error
+
+    def _should_retry_status(self, status_code: int) -> bool:
+        return status_code in self._retry_statuses
+
+    def _log_request(self, url: str, headers: Dict[str, str], body: Dict[str, Any]) -> None:
+        if not self._debug:
+            return
+        safe_headers = {k: v for k, v in headers.items() if k.lower() != "x-api-key"}
+        self._logger.info("ChatAds request -> %s", url)
+        self._logger.info("Headers: %s", safe_headers)
+        self._logger.info("Body: %s", json.dumps(body, indent=2))
+
+    def _log_response(self, response: httpx.Response, parsed: ChatAdsResponse) -> None:
+        if not self._debug:
+            return
+        self._logger.info(
+            "ChatAds response <- %s %s (status=%s)",
+            response.request.method if response.request else "POST",
+            response.request.url if response.request else "<unknown>",
+            response.status_code,
+        )
+        self._logger.info("Payload: %s", json.dumps(parsed.raw, indent=2))
+
+
+def _parse_response(response: httpx.Response) -> ChatAdsResponse:
+    try:
+        payload = response.json()
+    except ValueError as exc:
+        raise ChatAdsSDKError("ChatAds returned a non-JSON response") from exc
+    return ChatAdsResponse.from_dict(payload)
+
+
+def _build_payload_from_kwargs(message: str, kwargs: Dict[str, Any]) -> FunctionItemPayload:
+    known: Dict[str, Any] = {}
+    extra: Dict[str, Any] = {}
+    for key, value in kwargs.items():
+        normalized = _normalize_field_name(key)
+        if normalized:
+            known[normalized] = value
+        else:
+            extra[key] = value
+    return FunctionItemPayload(message=message, extra_fields=extra, **known)
+
+
+def _normalize_field_name(field: str) -> Optional[str]:
+    if field in _FUNCTION_ITEM_OPTIONAL_FIELDS:
+        return field
+    return _FIELD_ALIAS_LOOKUP.get(field.lower())
+
+
+def _compute_retry_delay(
+    attempt: int,
+    backoff_factor: float,
+    retry_after_header: Optional[str],
+) -> float:
+    header_delay = _parse_retry_after(retry_after_header)
+    if header_delay is not None:
+        return header_delay
+    if backoff_factor <= 0:
+        return 0.0
+    return backoff_factor * (2 ** attempt)
+
+
+def _parse_retry_after(header_value: Optional[str]) -> Optional[float]:
+    if header_value is None:
+        return None
+    header_value = header_value.strip()
+    if not header_value:
+        return None
+    try:
+        return max(0.0, float(header_value))
+    except ValueError:
+        pass
+    try:
+        dt = parsedate_to_datetime(header_value)
+        if dt is None:
+            return None
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        seconds = (dt - datetime.now(timezone.utc)).total_seconds()
+        return max(0.0, seconds)
+    except (TypeError, ValueError, OverflowError):
+        return None
+
+
+def _sleep_sync(delay: float) -> None:
+    if delay > 0:
+        time.sleep(delay)
+
+
+async def _sleep_async(delay: float) -> None:
+    if delay > 0:
+        await asyncio.sleep(delay)

chatads_sdk-0.1.0/chatads_sdk/exceptions.py

@@ -0,0 +1,49 @@
+"""SDK-specific exception hierarchy."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from .models import ChatAdsResponse
+
+
+class ChatAdsSDKError(Exception):
+    """Base class for local SDK issues (serialization, transport, etc.)."""
+
+
+class ChatAdsAPIError(ChatAdsSDKError):
+    """Raised for non-2xx responses returned by the ChatAds API."""
+
+    def __init__(
+        self,
+        status_code: int,
+        payload: Optional[Dict[str, Any]] = None,
+        response: Optional[ChatAdsResponse] = None,
+        headers: Optional[Dict[str, str]] = None,
+        request_body: Optional[Dict[str, Any]] = None,
+        url: Optional[str] = None,
+    ) -> None:
+        self.status_code = status_code
+        self.payload = payload or {}
+        self.response = response
+        self.headers = headers or {}
+        self.request_body = request_body or {}
+        self.url = url
+        message = self._build_message()
+        super().__init__(message)
+
+    def _build_message(self) -> str:
+        if self.response and self.response.error:
+            return (
+                f"ChatAds API error {self.status_code}: "
+                f"{self.response.error.code} - {self.response.error.message}"
+            )
+        return f"ChatAds API error {self.status_code}"
+
+    @property
+    def retry_after(self) -> Optional[str]:
+        """Expose Retry-After header when rate limits are hit."""
+        for key, value in self.headers.items():
+            if key.lower() == "retry-after":
+                return value
+        return None

chatads_sdk-0.1.0/chatads_sdk/models.py

@@ -0,0 +1,227 @@
+"""Dataclasses that mirror the ChatAds FastAPI request/response models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+FUNCTION_ITEM_OPTIONAL_FIELDS = (
+    "page_url",
+    "page_title",
+    "referrer",
+    "address",
+    "email",
+    "type",
+    "domain",
+    "user_agent",
+    "ip",
+    "reason",
+    "company",
+    "name",
+    "country",
+    "language",
+    "website",
+)
+
+_CAMELCASE_ALIASES = {
+    "pageurl": "page_url",
+    "pagetitle": "page_title",
+    "useragent": "user_agent",
+}
+
+FUNCTION_ITEM_FIELD_ALIASES = {
+    **{field: field for field in FUNCTION_ITEM_OPTIONAL_FIELDS},
+    **_CAMELCASE_ALIASES,
+}
+
+_FIELD_TO_PAYLOAD_KEY = {
+    "page_url": "pageUrl",
+    "page_title": "pageTitle",
+    "referrer": "referrer",
+    "address": "address",
+    "email": "email",
+    "type": "type",
+    "domain": "domain",
+    "user_agent": "userAgent",
+    "ip": "ip",
+    "reason": "reason",
+    "company": "company",
+    "name": "name",
+    "country": "country",
+    "language": "language",
+    "website": "website",
+}
+
+RESERVED_PAYLOAD_KEYS = frozenset({"message", *(_FIELD_TO_PAYLOAD_KEY.values())})
+
+
+@dataclass
+class ChatAdsAd:
+    product: str
+    link: str
+    message: str
+    category: str
+
+    @classmethod
+    def from_dict(cls, data: Optional[Dict[str, Any]]) -> Optional["ChatAdsAd"]:
+        if not data:
+            return None
+        return cls(
+            product=data.get("product", ""),
+            link=data.get("link", ""),
+            message=data.get("message", ""),
+            category=data.get("category", ""),
+        )
+
+
+@dataclass
+class ChatAdsData:
+    matched: bool
+    ad: Optional[ChatAdsAd] = None
+    reason: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: Optional[Dict[str, Any]]) -> Optional["ChatAdsData"]:
+        if not data:
+            return None
+        return cls(
+            matched=bool(data.get("matched", False)),
+            ad=ChatAdsAd.from_dict(data.get("ad")),
+            reason=data.get("reason"),
+        )
+
+
+@dataclass
+class ChatAdsError:
+    code: str
+    message: str
+    details: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: Optional[Dict[str, Any]]) -> Optional["ChatAdsError"]:
+        if not data:
+            return None
+        return cls(
+            code=data.get("code", "UNKNOWN"),
+            message=data.get("message", ""),
+            details=data.get("details") or {},
+        )
+
+
+@dataclass
+class UsageInfo:
+    monthly_requests: int
+    free_tier_limit: int
+    free_tier_remaining: int
+    is_free_tier: bool
+    has_credit_card: bool
+    daily_requests: Optional[int] = None
+    daily_limit: Optional[int] = None
+    minute_requests: Optional[int] = None
+    minute_limit: Optional[int] = None
+
+    @classmethod
+    def from_dict(cls, data: Optional[Dict[str, Any]]) -> Optional["UsageInfo"]:
+        if not data:
+            return None
+        return cls(
+            monthly_requests=int(data.get("monthly_requests") or 0),
+            free_tier_limit=int(data.get("free_tier_limit") or 0),
+            free_tier_remaining=int(data.get("free_tier_remaining") or 0),
+            is_free_tier=bool(data.get("is_free_tier", False)),
+            has_credit_card=bool(data.get("has_credit_card", False)),
+            daily_requests=_maybe_int(data.get("daily_requests")),
+            daily_limit=_maybe_int(data.get("daily_limit")),
+            minute_requests=_maybe_int(data.get("minute_requests")),
+            minute_limit=_maybe_int(data.get("minute_limit")),
+        )
+
+
+@dataclass
+class ChatAdsMeta:
+    request_id: str
+    user_id: Optional[str] = None
+    country: Optional[str] = None
+    language: Optional[str] = None
+    processing_time_ms: Optional[float] = None
+    usage: Optional[UsageInfo] = None
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: Optional[Dict[str, Any]]) -> "ChatAdsMeta":
+        data = data or {}
+        return cls(
+            request_id=data.get("request_id", ""),
+            user_id=data.get("user_id"),
+            country=data.get("country"),
+            language=data.get("language"),
+            processing_time_ms=data.get("processing_time_ms"),
+            usage=UsageInfo.from_dict(data.get("usage")),
+            raw=data,
+        )
+
+
+@dataclass
+class ChatAdsResponse:
+    success: bool
+    meta: ChatAdsMeta
+    data: Optional[ChatAdsData] = None
+    error: Optional[ChatAdsError] = None
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ChatAdsResponse":
+        data = data or {}
+        return cls(
+            success=bool(data.get("success", False)),
+            data=ChatAdsData.from_dict(data.get("data")),
+            error=ChatAdsError.from_dict(data.get("error")),
+            meta=ChatAdsMeta.from_dict(data.get("meta")),
+            raw=data,
+        )
+
+
+@dataclass
+class FunctionItemPayload:
+    """Subset of the server's FunctionItem pydantic model."""
+
+    message: str
+    page_url: Optional[str] = None
+    page_title: Optional[str] = None
+    referrer: Optional[str] = None
+    address: Optional[str] = None
+    email: Optional[str] = None
+    type: Optional[str] = None
+    domain: Optional[str] = None
+    user_agent: Optional[str] = None
+    ip: Optional[str] = None
+    reason: Optional[str] = None
+    company: Optional[str] = None
+    name: Optional[str] = None
+    country: Optional[str] = None
+    language: Optional[str] = None
+    website: Optional[str] = None
+    extra_fields: Dict[str, Any] = field(default_factory=dict)
+
+    def to_payload(self) -> Dict[str, Any]:
+        payload = {"message": self.message}
+        for field_name, payload_key in _FIELD_TO_PAYLOAD_KEY.items():
+            value = getattr(self, field_name)
+            if value is not None:
+                payload[payload_key] = value
+
+        conflicts = RESERVED_PAYLOAD_KEYS.intersection(self.extra_fields.keys())
+        if conflicts:
+            conflict_list = ", ".join(sorted(conflicts))
+            raise ValueError(
+                f"extra_fields contains reserved keys that would override core payload data: {conflict_list}"
+            )
+        payload.update(self.extra_fields)
+        return payload
+
+
+def _maybe_int(value: Any) -> Optional[int]:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None

chatads_sdk-0.1.0/chatads_sdk.egg-info/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: chatads-sdk
+Version: 0.1.0
+Summary: Lightweight Python client for the ChatAds affiliate scoring API
+Author-email: ChatAds <support@getchatads.com>
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1.0,>=0.27
+Provides-Extra: async
+Requires-Dist: httpx[http2]<1.0,>=0.27; extra == "async"
+
+# ChatAds Python SDK
+
+A tiny, dependency-light wrapper around the ChatAds `/v1/chatads-script` endpoint. It mirrors the response payloads returned by the FastAPI service so you can drop it into CLIs, serverless functions, or orchestration tools.
+
+## Installation
+
+```bash
+pip install .
+```
+
+(Or build/upload to your internal index as needed.)
+
+## Quickstart
+
+```python
+from chatads_sdk import ChatAdsClient, FunctionItemPayload
+
+client = ChatAdsClient(
+    api_key="YOUR_X_API_KEY",
+    base_url="https://<your-chatads-domain>",
+    raise_on_failure=True,        # Treat success=False payloads as exceptions
+    max_retries=2,                # Optional automatic retries for 429/5xx responses
+    retry_backoff_factor=0.75,    # Exponential backoff multiplier
+)
+
+payload = FunctionItemPayload(
+    message="Looking for a CRM to close more deals",
+    ip="1.2.3.4",
+    user_agent="Mozilla/5.0",
+)
+
+result = client.analyze(payload)
+
+if result.success:
+    print(result.data.ad)
+else:
+    print(result.error.code, result.error.message)
+```
+
+## Error Handling
+
+Non-2xx responses raise `ChatAdsAPIError` and include the parsed error payload plus the original HTTP status code so you can branch on quota/validation failures. Set `raise_on_failure=True` if you want 200 responses with `success=false` to raise the same exception class.
+
+## Notes
+
+- Retries are opt-in. Provide `max_retries>0` to automatically retry transport errors and retryable status codes. The client honors `Retry-After` headers and falls back to exponential backoff.
+- `FunctionItemPayload` matches the server-side `FunctionItem` pydantic model. Keyword arguments passed to `ChatAdsClient.analyze_message()` accept either snake_case (`user_agent`) or camelCase (`userAgent`) keys.
+- Reserved payload keys (e.g., `message`, `pageUrl`, `userAgent`) cannot be overridden through `extra_fields`; doing so raises `ValueError` to prevent silent mutations.
+
+## CLI Smoke Test
+
+For a super-quick check, edit the config block at the top of `python_sdk/run_sdk_smoke.py` (or set the
+`CHATADS_*` env vars) and run:
+
+```bash
+PYTHONPATH=python_sdk python python_sdk/run_sdk_smoke.py
+```
+
+It prints the raw JSON response or surfaces a `ChatAdsAPIError` with status/error fields so you can see
+exactly what the API returned.
+
+- `API_KEY` and `MESSAGE` are the only required values. Leave `CALLER_IP`, `USER_AGENT`, or `CHATADS_EXTRA_FIELDS`
+  blank to omit them from the request.

chatads_sdk-0.1.0/chatads_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+chatads_sdk/__init__.py
+chatads_sdk/client.py
+chatads_sdk/exceptions.py
+chatads_sdk/models.py
+chatads_sdk.egg-info/PKG-INFO
+chatads_sdk.egg-info/SOURCES.txt
+chatads_sdk.egg-info/dependency_links.txt
+chatads_sdk.egg-info/requires.txt
+chatads_sdk.egg-info/top_level.txt

chatads_sdk-0.1.0/chatads_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

chatads_sdk-0.1.0/chatads_sdk.egg-info/requires.txt

@@ -0,0 +1,4 @@
+httpx<1.0,>=0.27
+
+[async]
+httpx[http2]<1.0,>=0.27

chatads_sdk-0.1.0/chatads_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+chatads_sdk

chatads_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "chatads-sdk"
+version = "0.1.0"
+description = "Lightweight Python client for the ChatAds affiliate scoring API"
+authors = [{name = "ChatAds", email = "support@getchatads.com"}]
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+    "httpx>=0.27,<1.0",
+]
+
+[project.optional-dependencies]
+async = ["httpx[http2]>=0.27,<1.0"]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"

chatads_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+