onceonly-sdk 1.2.0__py3-none-any.whl → 2.0.0__py3-none-any.whl

onceonly/client.py

@@ -1,18 +1,23 @@
 from __future__ import annotations
 
 import logging
-from typing import Optional, Dict, Any, Union, Mapping
+from typing import Optional, Dict, Any
 
 import httpx
 
 from .models import CheckLockResult
-from .exceptions import (
-    UnauthorizedError,
-    OverLimitError,
-    RateLimitError,
-    ValidationError,
-    ApiError,
+from ._http import (
+    parse_json_or_raise,
+    try_extract_detail,
+    error_text,
+    request_with_retries_sync,
+    request_with_retries_async,
+    _parse_retry_after,
 )
+from .exceptions import ApiError, UnauthorizedError, OverLimitError, RateLimitError, ValidationError
+from .ai import AiClient
+from .version import __version__
+from ._util import to_metadata_dict, MetadataLike
 
 logger = logging.getLogger("onceonly")
 
@@ -21,9 +26,12 @@ class OnceOnly:
     """
     OnceOnly API client (sync + async).
 
-    - connection pooling via httpx.Client / httpx.AsyncClient
-    - optional fail-open for network/timeout/5xx
-    - close/aclose + context managers
+    For automation/agents:
+    - check_lock(...) is the idempotency primitive (fast, safe).
+    - ai.run_and_wait(...) is for long-running backend tasks keyed by an idempotency key.
+
+    Rate-limit auto-retry (429):
+    - optional; controlled by max_retries_429 + backoff params.
     """
 
     def __init__(
@@ -31,8 +39,12 @@ class OnceOnly:
         api_key: str,
         base_url: str = "https://api.onceonly.tech/v1",
         timeout: float = 5.0,
-        user_agent: str = "onceonly-python-sdk/1.0.0",
+        user_agent: Optional[str] = None,
         fail_open: bool = True,
+        *,
+        max_retries_429: int = 0,
+        retry_backoff: float = 0.5,
+        retry_max_backoff: float = 5.0,
         sync_client: Optional[httpx.Client] = None,
         async_client: Optional[httpx.AsyncClient] = None,
         transport: Optional[httpx.BaseTransport] = None,
@@ -43,6 +55,13 @@ class OnceOnly:
         self.timeout = timeout
         self.fail_open = fail_open
 
+        self._max_retries_429 = int(max_retries_429)
+        self._retry_backoff = float(retry_backoff)
+        self._retry_max_backoff = float(retry_max_backoff)
+
+        if user_agent is None:
+            user_agent = f"onceonly-python-sdk/{__version__}"
+
         self.headers = {
             "Authorization": f"Bearer {api_key}",
             "Content-Type": "application/json",
@@ -61,36 +80,41 @@ class OnceOnly:
         self._async_client = async_client  # lazy
         self._async_transport = async_transport
 
+        self.ai = AiClient(
+            self._sync_client,
+            self._get_async_client,
+            max_retries_429=self._max_retries_429,
+            retry_backoff=self._retry_backoff,
+            retry_max_backoff=self._retry_max_backoff,
+        )
+
     # ---------- Public API ----------
 
     def check_lock(
         self,
         key: str,
-        ttl: Optional[int] = None,  # IMPORTANT: None => server uses plan default TTL
-        meta: Optional[Dict[str, Any]] = None,
+        ttl: Optional[int] = None,
+        meta: Optional[MetadataLike] = None,
         request_id: Optional[str] = None,
     ) -> CheckLockResult:
         payload = self._make_payload(key, ttl, meta)
-
-        headers = {}
+        headers: Dict[str, str] = {}
         if request_id:
             headers["X-Request-Id"] = request_id
 
         try:
-            resp = self._sync_client.post("/check-lock", json=payload, headers=headers)
-            return self._parse_check_lock_response(
-                resp,
-                fallback_key=key,
-                fallback_ttl=int(ttl or 0),
-                fallback_meta=meta,
+            resp = request_with_retries_sync(
+                lambda: self._sync_client.post("/check-lock", json=payload, headers=headers),
+                max_retries=self._max_retries_429,
+                base_backoff=self._retry_backoff,
+                max_backoff=self._retry_max_backoff,
             )
-
+            return self._parse_check_lock_response(resp, fallback_key=key, fallback_ttl=int(ttl or 0), fallback_meta=meta)
         except httpx.TimeoutException as e:
             return self._maybe_fail_open("timeout", e, key, int(ttl or 0), meta=meta)
         except httpx.RequestError as e:
             return self._maybe_fail_open("request_error", e, key, int(ttl or 0), meta=meta)
         except ApiError as e:
-            # fail-open ONLY for 5xx
             if e.status_code is not None and e.status_code >= 500:
                 return self._maybe_fail_open("api_5xx", e, key, int(ttl or 0), meta=meta)
             raise
@@ -99,25 +123,23 @@ class OnceOnly:
         self,
         key: str,
         ttl: Optional[int] = None,
-        meta: Optional[Dict[str, Any]] = None,
+        meta: Optional[MetadataLike] = None,
         request_id: Optional[str] = None,
     ) -> CheckLockResult:
         payload = self._make_payload(key, ttl, meta)
-
-        headers = {}
+        headers: Dict[str, str] = {}
         if request_id:
             headers["X-Request-Id"] = request_id
 
         client = await self._get_async_client()
         try:
-            resp = await client.post("/check-lock", json=payload, headers=headers)
-            return self._parse_check_lock_response(
-                resp,
-                fallback_key=key,
-                fallback_ttl=int(ttl or 0),
-                fallback_meta=meta,
+            resp = await request_with_retries_async(
+                lambda: client.post("/check-lock", json=payload, headers=headers),
+                max_retries=self._max_retries_429,
+                base_backoff=self._retry_backoff,
+                max_backoff=self._retry_max_backoff,
             )
-
+            return self._parse_check_lock_response(resp, fallback_key=key, fallback_ttl=int(ttl or 0), fallback_meta=meta)
         except httpx.TimeoutException as e:
             return self._maybe_fail_open("timeout", e, key, int(ttl or 0), meta=meta)
         except httpx.RequestError as e:
@@ -127,34 +149,50 @@ class OnceOnly:
                 return self._maybe_fail_open("api_5xx", e, key, int(ttl or 0), meta=meta)
             raise
 
+    # thin wrapper for agent UX
+    def ai_run_and_wait(self, key: str, **kwargs):
+        return self.ai.run_and_wait(key=key, **kwargs)
+
+    async def ai_run_and_wait_async(self, key: str, **kwargs):
+        return await self.ai.run_and_wait_async(key=key, **kwargs)
+
     def me(self) -> Dict[str, Any]:
-        """
-        Get info about the current API key (plan, active status, period end, etc).
-        """
-        try:
-            resp = self._sync_client.get("/me")
-            return self._parse_json_or_raise(resp)
-        except httpx.TimeoutException as e:
-            raise ApiError("Timeout", status_code=None, detail={})
-        except httpx.RequestError as e:
-            raise ApiError(f"Request error: {e}", status_code=None, detail={})
+        resp = request_with_retries_sync(
+            lambda: self._sync_client.get("/me"),
+            max_retries=self._max_retries_429,
+            base_backoff=self._retry_backoff,
+            max_backoff=self._retry_max_backoff,
+        )
+        return parse_json_or_raise(resp)
 
     async def me_async(self) -> Dict[str, Any]:
         client = await self._get_async_client()
-        resp = await client.get("/me")
-        return self._parse_json_or_raise(resp)
-
-    def usage(self) -> Dict[str, Any]:
-        """
-        Get current usage counters and limits for this API key.
-        """
-        resp = self._sync_client.get("/usage")
-        return self._parse_json_or_raise(resp)
+        resp = await request_with_retries_async(
+            lambda: client.get("/me"),
+            max_retries=self._max_retries_429,
+            base_backoff=self._retry_backoff,
+            max_backoff=self._retry_max_backoff,
+        )
+        return parse_json_or_raise(resp)
+
+    def usage(self, kind: str = "make") -> Dict[str, Any]:
+        resp = request_with_retries_sync(
+            lambda: self._sync_client.get("/usage", params={"kind": kind}),
+            max_retries=self._max_retries_429,
+            base_backoff=self._retry_backoff,
+            max_backoff=self._retry_max_backoff,
+        )
+        return parse_json_or_raise(resp)
 
-    async def usage_async(self) -> Dict[str, Any]:
+    async def usage_async(self, kind: str = "make") -> Dict[str, Any]:
         client = await self._get_async_client()
-        resp = await client.get("/usage")
-        return self._parse_json_or_raise(resp)
+        resp = await request_with_retries_async(
+            lambda: client.get("/usage", params={"kind": kind}),
+            max_retries=self._max_retries_429,
+            base_backoff=self._retry_backoff,
+            max_backoff=self._retry_max_backoff,
+        )
+        return parse_json_or_raise(resp)
 
     def close(self) -> None:
         if self._own_sync:
@@ -191,34 +229,25 @@ class OnceOnly:
             self._own_async = True
         return self._async_client
 
-    def _make_payload(
-        self,
-        key: str,
-        ttl: Optional[int],
-        meta: Optional[Dict[str, Any]],
-    ) -> Dict[str, Any]:
+    def _make_payload(self, key: str, ttl: Optional[int], meta: Optional[MetadataLike]) -> Dict[str, Any]:
         payload: Dict[str, Any] = {"key": key}
         if ttl is not None:
             payload["ttl"] = int(ttl)
-        if meta is not None:
-            payload["meta"] = meta
+        md = to_metadata_dict(meta)
+        if md is not None:
+            payload["metadata"] = md
         return payload
 
-    def _maybe_fail_open(
-        self,
-        reason: str,
-        err: Exception,
-        key: str,
-        ttl: int,
-        meta: Optional[Dict[str, Any]] = None,
-    ) -> CheckLockResult:
+    def _maybe_fail_open(self, reason: str, err: Exception, key: str, ttl: int, meta: Optional[MetadataLike] = None) -> CheckLockResult:
         if not self.fail_open:
             raise
 
         logger.warning("onceonly fail-open (%s): %s", reason, err)
-        raw = {"fail_open": True, "reason": reason}
-        if meta is not None:
-            raw["meta"] = meta
+        raw: Dict[str, Any] = {"fail_open": True, "reason": reason}
+        md = to_metadata_dict(meta)
+        if md is not None:
+            raw["metadata"] = md
+
         return CheckLockResult(
             locked=True,
             duplicate=False,
@@ -233,37 +262,45 @@ class OnceOnly:
     def _parse_check_lock_response(
         self,
         response: httpx.Response,
+        *,
         fallback_key: str,
         fallback_ttl: int,
-        fallback_meta: Optional[Dict[str, Any]] = None,
+        fallback_meta: Optional[MetadataLike] = None,
     ) -> CheckLockResult:
         request_id = response.headers.get("X-Request-Id")
         oo_status = (response.headers.get("X-OnceOnly-Status") or "").strip().lower()
 
         if response.status_code in (401, 403):
-            raise UnauthorizedError(self._error_text(response, "Invalid API Key (Unauthorized)."))
+            raise UnauthorizedError(error_text(response, "Invalid API Key (Unauthorized)."))
 
         if response.status_code == 402:
-            detail = self._try_extract_detail(response)
+            detail = try_extract_detail(response)
             raise OverLimitError(
                 "Usage limit reached. Please upgrade your plan.",
                 detail=detail if isinstance(detail, dict) else {},
             )
 
         if response.status_code == 429:
-            raise RateLimitError(self._error_text(response, "Rate limit exceeded. Please slow down."))
+            retry_after = _parse_retry_after(response)
+            raise RateLimitError(
+                error_text(response, "Rate limit exceeded. Please slow down."),
+                retry_after_sec=retry_after,
+            )
 
         if response.status_code == 422:
-            raise ValidationError(self._error_text(response, f"Validation Error: {response.text}"))
+            raise ValidationError(error_text(response, f"Validation Error: {response.text}"))
 
         if response.status_code == 409:
             first_seen_at = None
-            d = self._try_extract_detail(response)
+            d = try_extract_detail(response)
             if isinstance(d, dict):
                 first_seen_at = d.get("first_seen_at")
-            raw = {"detail": d} if d is not None else {}
-            if fallback_meta is not None:
-                raw["meta"] = fallback_meta
+
+            raw: Dict[str, Any] = {"detail": d} if d is not None else {}
+            md = to_metadata_dict(fallback_meta)
+            if md is not None:
+                raw["metadata"] = md
+
             return CheckLockResult(
                 locked=False,
                 duplicate=True,
@@ -275,26 +312,11 @@ class OnceOnly:
                 raw=raw,
             )
 
-        if 500 <= response.status_code <= 599:
-            d = self._try_extract_detail(response)
-            raise ApiError(
-                self._error_text(response, f"Server error ({response.status_code})"),
-                status_code=response.status_code,
-                detail=d if isinstance(d, dict) else {},
-            )
-
         if response.status_code < 200 or response.status_code >= 300:
-            d = self._try_extract_detail(response)
-            raise ApiError(
-                self._error_text(response, f"API Error ({response.status_code}): {response.text}"),
-                status_code=response.status_code,
-                detail=d if isinstance(d, dict) else {},
-            )
+            parse_json_or_raise(response)  # raises typed ApiError/...
+            raise ApiError("Unexpected non-2xx response", status_code=response.status_code)
 
-        try:
-            data = response.json()
-        except Exception:
-            data = {}
+        data = parse_json_or_raise(response)
 
         status = str(data.get("status") or "").strip().lower()
         success = data.get("success")
@@ -303,8 +325,9 @@ class OnceOnly:
         duplicate = (oo_status == "duplicate") or (status == "duplicate") or (success is False)
 
         raw = data if isinstance(data, dict) else {}
-        if fallback_meta is not None and "meta" not in raw:
-            raw["meta"] = fallback_meta
+        md = to_metadata_dict(fallback_meta)
+        if md is not None and "metadata" not in raw:
+            raw["metadata"] = md
 
         return CheckLockResult(
             locked=locked,
@@ -317,71 +340,17 @@ class OnceOnly:
             raw=raw,
         )
 
-    def _try_extract_detail(self, response: httpx.Response) -> Optional[Union[Dict[str, Any], str]]:
-        try:
-            j = response.json()
-            if isinstance(j, dict) and "detail" in j:
-                return j.get("detail")
-            return j
-        except Exception:
-            return None
-
-    def _error_text(self, response: httpx.Response, default: str) -> str:
-        d = self._try_extract_detail(response)
-        if isinstance(d, dict):
-            return d.get("error") or d.get("message") or default
-        if isinstance(d, str) and d.strip():
-            return d
-        return default
-
-    def _parse_json_or_raise(self, response: httpx.Response) -> Dict[str, Any]:
-        # auth / limits
-        if response.status_code in (401, 403):
-            raise UnauthorizedError(self._error_text(response, "Invalid API Key (Unauthorized)."))
-
-        if response.status_code == 402:
-            detail = self._try_extract_detail(response)
-            raise OverLimitError(
-                "Usage limit reached. Please upgrade your plan.",
-                detail=detail if isinstance(detail, dict) else {},
-            )
-
-        if response.status_code == 429:
-            raise RateLimitError(self._error_text(response, "Rate limit exceeded. Please slow down."))
-
-        if response.status_code == 422:
-            raise ValidationError(self._error_text(response, f"Validation Error: {response.text}"))
-
-        if 500 <= response.status_code <= 599:
-            d = self._try_extract_detail(response)
-            raise ApiError(
-                self._error_text(response, f"Server error ({response.status_code})"),
-                status_code=response.status_code,
-                detail=d if isinstance(d, dict) else {},
-            )
-
-        if response.status_code < 200 or response.status_code >= 300:
-            d = self._try_extract_detail(response)
-            raise ApiError(
-                self._error_text(response, f"API Error ({response.status_code}): {response.text}"),
-                status_code=response.status_code,
-                detail=d if isinstance(d, dict) else {},
-            )
-
-        try:
-            data = response.json()
-        except Exception:
-            data = {}
-
-        return data if isinstance(data, dict) else {"data": data}
-
 
 def create_client(
     api_key: str,
     base_url: str = "https://api.onceonly.tech/v1",
     timeout: float = 5.0,
-    user_agent: str = "onceonly-python-sdk/1.0.0",
+    user_agent: Optional[str] = None,
     fail_open: bool = True,
+    *,
+    max_retries_429: int = 0,
+    retry_backoff: float = 0.5,
+    retry_max_backoff: float = 5.0,
 ) -> OnceOnly:
     return OnceOnly(
         api_key=api_key,
@@ -389,4 +358,7 @@ def create_client(
         timeout=timeout,
         user_agent=user_agent,
         fail_open=fail_open,
+        max_retries_429=max_retries_429,
+        retry_backoff=retry_backoff,
+        retry_max_backoff=retry_max_backoff,
     )

onceonly/decorators.py

@@ -1,80 +1,174 @@
+from __future__ import annotations
+
 import functools
 import inspect
 import json
 import hashlib
-from typing import Any, Callable, Optional, TypeVar, Union, Awaitable
+import logging
+from typing import Any, Callable, Optional, TypeVar
+
+from .client import OnceOnly
+
+logger = logging.getLogger("onceonly")
 
 T = TypeVar("T")
 
 
+def _truncate(s: str, max_len: int = 2048) -> str:
+    return s if len(s) <= max_len else (s[:max_len] + "…")
+
+
+def _pydantic_to_json(obj: Any) -> Optional[str]:
+    # Pydantic v2
+    mdj = getattr(obj, "model_dump_json", None)
+    if callable(mdj):
+        try:
+            return mdj()
+        except Exception:
+            return None
+
+    # Pydantic v1
+    j = getattr(obj, "json", None)
+    if callable(j):
+        try:
+            return j()
+        except Exception:
+            return None
+
+    return None
+
+
+def _dataclass_to_json(obj: Any) -> Optional[str]:
+    # Avoid importing dataclasses unless needed
+    if not hasattr(obj, "__dataclass_fields__"):
+        return None
+    try:
+        import dataclasses
+
+        d = dataclasses.asdict(obj)
+        return json.dumps(d, ensure_ascii=False, sort_keys=True, separators=(",", ":"), default=str)
+    except Exception:
+        return None
+
+
 def _default_json(obj: Any) -> str:
+    """
+    Best-effort stable serialization for idempotency key generation.
+
+    Priority:
+      1) Pydantic models (v2/v1)
+      2) dataclasses
+      3) plain JSON types via json.dumps
+      4) fallback to str(obj) (NOT repr) to avoid memory addresses
+    """
+    pj = _pydantic_to_json(obj)
+    if pj is not None:
+        return _truncate(pj)
+
+    dj = _dataclass_to_json(obj)
+    if dj is not None:
+        return _truncate(dj)
+
     try:
-        return json.dumps(obj, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+        return json.dumps(obj, ensure_ascii=False, sort_keys=True, separators=(",", ":"), default=str)
     except Exception:
-        return repr(obj)
+        try:
+            return _truncate(str(obj))
+        except Exception:
+            return _truncate("<unserializable>")
+
 
+def _stable_hash(payload: Any) -> str:
+    raw = json.dumps(payload, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(raw.encode("utf-8")).hexdigest()
 
-def _generate_key(func: Callable[..., Any], args: tuple, kwargs: dict) -> str:
-    # canonical payload
+
+def _generate_key(
+    func: Callable[..., Any],
+    args: tuple,
+    kwargs: dict,
+    *,
+    key_version: str,
+    key_id: Optional[str],
+) -> str:
+    fn_id = key_id or f"{func.__module__}.{func.__qualname__}"
     payload = {
-        "fn": f"{func.__module__}.{func.__qualname__}",
+        "v": str(key_version),
+        "fn": fn_id,
         "args": [_default_json(a) for a in args],
         "kwargs": {k: _default_json(v) for k, v in sorted(kwargs.items())},
     }
-    raw = json.dumps(payload, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
-    return hashlib.sha256(raw.encode("utf-8")).hexdigest()
+    return _stable_hash(payload)
 
 
 def idempotent(
-    client: "OnceOnly",
+    client: OnceOnly,
+    *,
     key_prefix: str = "func",
     ttl: int = 86400,
     key_func: Optional[Callable[..., str]] = None,
+    key_version: str = "v1",
+    key_id: Optional[str] = None,
     on_duplicate: Optional[Callable[..., Any]] = None,
     return_value_on_duplicate: Any = None,
 ):
     """
-    Decorator for sync + async funcs.
-
-    Behavior:
-    - computes full_key = f"{key_prefix}:{key}"
-    - calls OnceOnly check_lock
-    - if duplicate:
-        - if on_duplicate provided -> return on_duplicate(*args, **kwargs)
-        - else return return_value_on_duplicate
+    Idempotency decorator for sync + async functions.
+
+    - Computes deterministic idempotency key
+    - Calls OnceOnly.check_lock / check_lock_async
+    - If duplicate: calls on_duplicate or returns return_value_on_duplicate
     """
 
-    def decorator(func: Callable[..., Any]):
+    def decorator(func: Callable[..., T]) -> Callable[..., T]:
         is_async = inspect.iscoroutinefunction(func)
 
         def make_full_key(args: tuple, kwargs: dict) -> str:
-            k = key_func(*args, **kwargs) if key_func else _generate_key(func, args, kwargs)
-            return f"{key_prefix}:{k}"
+            if key_func:
+                k = key_func(*args, **kwargs)
+            else:
+                k = _generate_key(func, args, kwargs, key_version=key_version, key_id=key_id)
+            full = f"{key_prefix}:{k}"
+            logger.debug(
+                "idempotent key=%s key_prefix=%s key_version=%s key_id=%s",
+                full,
+                key_prefix,
+                key_version,
+                key_id,
+            )
+            return full
 
         if is_async:
+
             @functools.wraps(func)
-            async def awrapper(*args, **kwargs):
+            async def async_wrapper(*args, **kwargs):  # type: ignore[misc]
                 full_key = make_full_key(args, kwargs)
                 res = await client.check_lock_async(key=full_key, ttl=ttl)
+                logger.debug("idempotent async key=%s locked=%s duplicate=%s", full_key, res.locked, res.duplicate)
+
                 if res.duplicate:
                     if on_duplicate is not None:
                         v = on_duplicate(*args, **kwargs)
                         return await v if inspect.isawaitable(v) else v
-                    return return_value_on_duplicate
+                    return return_value_on_duplicate  # type: ignore[return-value]
+
                 return await func(*args, **kwargs)
 
-            return awrapper
+            return async_wrapper  # type: ignore[return-value]
 
         @functools.wraps(func)
-        def swrapper(*args, **kwargs):
+        def sync_wrapper(*args, **kwargs):  # type: ignore[misc]
             full_key = make_full_key(args, kwargs)
             res = client.check_lock(key=full_key, ttl=ttl)
+            logger.debug("idempotent sync key=%s locked=%s duplicate=%s", full_key, res.locked, res.duplicate)
+
             if res.duplicate:
                 if on_duplicate is not None:
                     return on_duplicate(*args, **kwargs)
-                return return_value_on_duplicate
+                return return_value_on_duplicate  # type: ignore[return-value]
+
             return func(*args, **kwargs)
 
-        return swrapper
+        return sync_wrapper  # type: ignore[return-value]
 
     return decorator

onceonly/exceptions.py

@@ -12,7 +12,7 @@ class UnauthorizedError(OnceOnlyError):
 
 
 class OverLimitError(OnceOnlyError):
-    """402 Free plan limit reached."""
+    """402 Plan usage limit reached."""
 
     def __init__(self, message: str, detail: Optional[Dict[str, Any]] = None):
         super().__init__(message)
@@ -22,6 +22,10 @@ class OverLimitError(OnceOnlyError):
 class RateLimitError(OnceOnlyError):
     """429 Rate limit exceeded."""
 
+    def __init__(self, message: str, retry_after_sec: Optional[float] = None):
+        super().__init__(message)
+        self.retry_after_sec = retry_after_sec
+
 
 class ValidationError(OnceOnlyError):
     """422 validation error."""

onceonly/integrations/__init__.py

@@ -0,0 +1 @@
+# optional integrations live here