onceonly-sdk 1.2.0__py3-none-any.whl

onceonly/__init__.py

@@ -0,0 +1,24 @@
+from .client import OnceOnly, create_client
+from .models import CheckLockResult
+from .exceptions import (
+    OnceOnlyError,
+    UnauthorizedError,
+    OverLimitError,
+    RateLimitError,
+    ValidationError,
+    ApiError,
+)
+
+__version__ = "1.2.0"
+
+__all__ = [
+    "OnceOnly",
+    "create_client",
+    "CheckLockResult",
+    "OnceOnlyError",
+    "UnauthorizedError",
+    "OverLimitError",
+    "RateLimitError",
+    "ValidationError",
+    "ApiError",
+]

onceonly/client.py

@@ -0,0 +1,392 @@
+from __future__ import annotations
+
+import logging
+from typing import Optional, Dict, Any, Union, Mapping
+
+import httpx
+
+from .models import CheckLockResult
+from .exceptions import (
+    UnauthorizedError,
+    OverLimitError,
+    RateLimitError,
+    ValidationError,
+    ApiError,
+)
+
+logger = logging.getLogger("onceonly")
+
+
+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
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.onceonly.tech/v1",
+        timeout: float = 5.0,
+        user_agent: str = "onceonly-python-sdk/1.0.0",
+        fail_open: bool = True,
+        sync_client: Optional[httpx.Client] = None,
+        async_client: Optional[httpx.AsyncClient] = None,
+        transport: Optional[httpx.BaseTransport] = None,
+        async_transport: Optional[httpx.AsyncBaseTransport] = None,
+    ):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.fail_open = fail_open
+
+        self.headers = {
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+            "User-Agent": user_agent,
+        }
+
+        self._own_sync = sync_client is None
+        self._own_async = async_client is None
+
+        self._sync_client = sync_client or httpx.Client(
+            base_url=self.base_url,
+            headers=self.headers,
+            timeout=self.timeout,
+            transport=transport,
+        )
+        self._async_client = async_client  # lazy
+        self._async_transport = async_transport
+
+    # ---------- 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,
+        request_id: Optional[str] = None,
+    ) -> CheckLockResult:
+        payload = self._make_payload(key, ttl, meta)
+
+        headers = {}
+        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,
+            )
+
+        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
+
+    async def check_lock_async(
+        self,
+        key: str,
+        ttl: Optional[int] = None,
+        meta: Optional[Dict[str, Any]] = None,
+        request_id: Optional[str] = None,
+    ) -> CheckLockResult:
+        payload = self._make_payload(key, ttl, meta)
+
+        headers = {}
+        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,
+            )
+
+        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:
+            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
+
+    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={})
+
+    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)
+
+    async def usage_async(self) -> Dict[str, Any]:
+        client = await self._get_async_client()
+        resp = await client.get("/usage")
+        return self._parse_json_or_raise(resp)
+
+    def close(self) -> None:
+        if self._own_sync:
+            self._sync_client.close()
+
+    async def aclose(self) -> None:
+        if self._own_async and self._async_client is not None:
+            await self._async_client.aclose()
+            self._async_client = None
+
+    def __enter__(self) -> "OnceOnly":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+    async def __aenter__(self) -> "OnceOnly":
+        await self._get_async_client()
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        await self.aclose()
+
+    # ---------- Internal ----------
+
+    async def _get_async_client(self) -> httpx.AsyncClient:
+        if self._async_client is None:
+            self._async_client = httpx.AsyncClient(
+                base_url=self.base_url,
+                headers=self.headers,
+                timeout=self.timeout,
+                transport=self._async_transport,
+            )
+            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]:
+        payload: Dict[str, Any] = {"key": key}
+        if ttl is not None:
+            payload["ttl"] = int(ttl)
+        if meta is not None:
+            payload["meta"] = meta
+        return payload
+
+    def _maybe_fail_open(
+        self,
+        reason: str,
+        err: Exception,
+        key: str,
+        ttl: int,
+        meta: Optional[Dict[str, Any]] = 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
+        return CheckLockResult(
+            locked=True,
+            duplicate=False,
+            key=key,
+            ttl=ttl,
+            first_seen_at=None,
+            request_id="fail-open",
+            status_code=0,
+            raw=raw,
+        )
+
+    def _parse_check_lock_response(
+        self,
+        response: httpx.Response,
+        fallback_key: str,
+        fallback_ttl: int,
+        fallback_meta: Optional[Dict[str, Any]] = 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)."))
+
+        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 response.status_code == 409:
+            first_seen_at = None
+            d = self._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
+            return CheckLockResult(
+                locked=False,
+                duplicate=True,
+                key=fallback_key,
+                ttl=fallback_ttl,
+                first_seen_at=first_seen_at,
+                request_id=request_id,
+                status_code=response.status_code,
+                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 {},
+            )
+
+        try:
+            data = response.json()
+        except Exception:
+            data = {}
+
+        status = str(data.get("status") or "").strip().lower()
+        success = data.get("success")
+
+        locked = (oo_status == "locked") or (status == "locked") or (success is True)
+        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
+
+        return CheckLockResult(
+            locked=locked,
+            duplicate=duplicate,
+            key=str(data.get("key") or fallback_key),
+            ttl=int(data.get("ttl") or fallback_ttl),
+            first_seen_at=data.get("first_seen_at"),
+            request_id=request_id,
+            status_code=response.status_code,
+            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",
+    fail_open: bool = True,
+) -> OnceOnly:
+    return OnceOnly(
+        api_key=api_key,
+        base_url=base_url,
+        timeout=timeout,
+        user_agent=user_agent,
+        fail_open=fail_open,
+    )

onceonly/decorators.py

@@ -0,0 +1,80 @@
+import functools
+import inspect
+import json
+import hashlib
+from typing import Any, Callable, Optional, TypeVar, Union, Awaitable
+
+T = TypeVar("T")
+
+
+def _default_json(obj: Any) -> str:
+    try:
+        return json.dumps(obj, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+    except Exception:
+        return repr(obj)
+
+
+def _generate_key(func: Callable[..., Any], args: tuple, kwargs: dict) -> str:
+    # canonical payload
+    payload = {
+        "fn": f"{func.__module__}.{func.__qualname__}",
+        "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()
+
+
+def idempotent(
+    client: "OnceOnly",
+    key_prefix: str = "func",
+    ttl: int = 86400,
+    key_func: Optional[Callable[..., 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
+    """
+
+    def decorator(func: Callable[..., Any]):
+        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 is_async:
+            @functools.wraps(func)
+            async def awrapper(*args, **kwargs):
+                full_key = make_full_key(args, kwargs)
+                res = await client.check_lock_async(key=full_key, ttl=ttl)
+                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 await func(*args, **kwargs)
+
+            return awrapper
+
+        @functools.wraps(func)
+        def swrapper(*args, **kwargs):
+            full_key = make_full_key(args, kwargs)
+            res = client.check_lock(key=full_key, ttl=ttl)
+            if res.duplicate:
+                if on_duplicate is not None:
+                    return on_duplicate(*args, **kwargs)
+                return return_value_on_duplicate
+            return func(*args, **kwargs)
+
+        return swrapper
+
+    return decorator

onceonly/exceptions.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+class OnceOnlyError(Exception):
+    """Base exception class for OnceOnly SDK."""
+
+
+class UnauthorizedError(OnceOnlyError):
+    """401/403 Invalid or disabled API key."""
+
+
+class OverLimitError(OnceOnlyError):
+    """402 Free plan limit reached."""
+
+    def __init__(self, message: str, detail: Optional[Dict[str, Any]] = None):
+        super().__init__(message)
+        self.detail = detail or {}
+
+
+class RateLimitError(OnceOnlyError):
+    """429 Rate limit exceeded."""
+
+
+class ValidationError(OnceOnlyError):
+    """422 validation error."""
+
+
+class ApiError(OnceOnlyError):
+    """Non-2xx API errors (except those mapped to typed errors)."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        detail: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(message)
+        self.status_code = status_code
+        self.detail = detail or {}

onceonly/models.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+
+@dataclass(frozen=True)
+class CheckLockResult:
+    locked: bool
+    duplicate: bool
+    key: str
+    ttl: int
+    first_seen_at: Optional[str]
+    request_id: Optional[str]
+    status_code: int
+    raw: Dict[str, Any]

onceonly_sdk-1.2.0.dist-info/METADATA

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: onceonly-sdk
+Version: 1.2.0
+Summary: Python SDK for OnceOnly idempotency API
+Author-email: OnceOnly <support@onceonly.tech>
+License: MIT
+Project-URL: Homepage, https://onceonly.tech/
+Project-URL: Documentation, https://onceonly.tech/docs/
+Project-URL: Repository, https://github.com/mykolademyanov/onceonly-python
+Keywords: idempotency,automation,zapier,make,ai-agents
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.25
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Dynamic: license-file
+
+# OnceOnly Python SDK
+
+**The Idempotency Layer for AI Agents, Webhooks, and Distributed Systems.**
+
+OnceOnly is a high-performance Python SDK designed to ensure **exactly-once execution**.
+It prevents duplicate actions (payments, emails, tool calls) in unstable environments like
+AI agents, webhooks, or background workers.
+
+Website - https://onceonly.tech/ai/
+
+[![PyPI version](https://img.shields.io/pypi/v/onceonly.svg)](https://pypi.org/project/onceonly-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Features
+
+- **Sync + Async Client** — built on httpx for modern Python stacks
+- **Connection Pooling** — high performance under heavy load
+- **Fail-Open Mode** — business logic keeps running even if API is unreachable
+- **Smart Decorator** — automatic idempotency based on function arguments
+- **Typed Results & Exceptions**
+
+---
+
+## Installation
+
+```bash
+pip install onceonly-sdk
+```
+
+---
+
+## Quick Start
+
+```python
+from onceonly import OnceOnly
+
+client = OnceOnly(api_key="once_live_...")
+
+result = client.check_lock(
+    key="order:123",
+    ttl=300, # 300 seconds = 5 minutes (clamped by your plan)
+)
+
+if result.duplicate:
+    print("Duplicate blocked")
+else:
+    print("First execution")
+```
+
+---
+
+## Async Usage
+
+```python
+async def handler():
+    result = await client.check_lock_async("order:123")
+    if result.locked:
+        print("Locked")
+```
+
+---
+
+## TTL Behavior
+
+- TTL is specified in seconds
+- If ttl is not provided, the server applies the plan default TTL
+- If ttl is provided, it is automatically clamped to your plan limits
+
+---
+
+## Metadata
+
+You can optionally attach metadata to each check-lock call.
+Metadata is useful for debugging, tracing, and server-side analytics.
+
+Rules:
+- JSON-serializable only
+- Size-limited
+- Safely logged on the server
+
+---
+
+## Decorator
+
+The SDK provides an optional decorator that automatically generates
+an idempotency key based on the **function name and arguments**.
+
+This allows you to add exactly-once guarantees to existing code
+with zero manual key management.
+
+```python
+from onceonly.decorators import idempotent
+
+@idempotent(client, ttl=3600)
+def process_order(order_id):
+    ...
+```
+
+---
+
+## Fail-Open Mode
+
+Enabled by default.
+
+If a network error, timeout, or server error (5xx) occurs, the SDK returns a locked result
+instead of breaking your application.
+
+Fail-open never triggers for:
+- Authentication errors (401 / 403)
+- Plan limits (402)
+- Validation errors (422)
+- Rate limits (429)
+
+---
+
+## Exceptions
+
+| Exception          | HTTP Status | Description                              |
+|--------------------|------------|------------------------------------------|
+| UnauthorizedError  | 401 / 403  | Invalid or disabled API key               |
+| OverLimitError     | 402        | Plan limit reached                        |
+| RateLimitError     | 429        | Too many requests                         |
+| ValidationError    | 422        | Invalid input                             |
+| ApiError           | 5xx / other| Server or unexpected API error            |
+
+---
+
+## License
+
+MIT

onceonly_sdk-1.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+onceonly/__init__.py,sha256=_SwJ4Y2345WJKfpW2IsOVfgNaUzjZqTSSOnPQBroW-M,452
+onceonly/client.py,sha256=1RMTkGDpalHfx-xEH8DZsn9ZJ3VeGomG6PKAQQjPdZQ,13361
+onceonly/decorators.py,sha256=9eBhRUQDBGTUXVyRYlpYy77y-EHF-udX3ERkrfIt9Kg,2651
+onceonly/exceptions.py,sha256=RP556LUtO54TPFTZybF4dVA9n3TByFn35esz7EbcrpY,994
+onceonly/models.py,sha256=xhPfP1kpyHYfKJNiac2REeXTpPLzrEWJeqn-p6B6taQ,329
+onceonly_sdk-1.2.0.dist-info/licenses/LICENSE,sha256=YQQ8IT_P7hcGmmLFFuOy3eKDZ90e1cqef_okg85oAiQ,129
+onceonly_sdk-1.2.0.dist-info/METADATA,sha256=dvml-Mhrd_n0xFEhk7-rvShxiYfaLcl_Pq2vyGD0XRo,3891
+onceonly_sdk-1.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+onceonly_sdk-1.2.0.dist-info/top_level.txt,sha256=lvz-sHerZcTwlZW-uYoda_wgx62kY07GdtzIdw89hnU,9
+onceonly_sdk-1.2.0.dist-info/RECORD,,

onceonly_sdk-1.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

onceonly_sdk-1.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,5 @@
+MIT License
+
+Copyright (c) 2026 Mykola Demianov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy...

onceonly_sdk-1.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+onceonly