carrac-sdk 0.1.0__tar.gz

carrac_sdk-0.1.0/.gitignore

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

carrac_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: carrac-sdk
+Version: 0.1.0
+Summary: Official Python SDK for Carrac — market data, plays, alerts, usage
+Project-URL: Homepage, https://carrac.cc
+Project-URL: Documentation, https://app.carrac.cc/api/docs
+Project-URL: Source, https://github.com/pgyula86/carrac-sdk-python
+Author-email: Carrac <hello@carrac.cc>
+License-Expression: MIT
+Keywords: carrac,crypto,market-data,sdk,trading
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25
+Provides-Extra: dev
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Carrac Python SDK
+
+Official Python client for the [Carrac](https://carrac.cc) API. Use it to fetch market data, manage plays, create alerts, and inspect your API usage from any Python application.
+
+## Install
+
+```bash
+pip install carrac-sdk
+```
+
+Requires Python ≥ 3.9 and a Carrac Premium subscription (API keys require Premium).
+
+## Quick start
+
+```python
+from carrac import Client
+
+cvx = Client(api_key="carrac_k_...")
+
+# Market data
+chart = cvx.charts.get("BTC", timeframe="4h", indicators="CPR,RSI")
+
+# Composite call — everything about an asset in one request
+detail = cvx.composite.asset_detail("BTC", format="compact")
+
+# Create an alert
+cvx.alerts.create(symbol="BTC", alert_type="price", condition="above", price=120000)
+
+# Scanner
+ranked = cvx.scanner.list(direction="long", verdict="STRONG,GOOD")
+
+# Your usage
+usage = cvx.usage.get()
+print(usage["rest"]["usage"])  # [{window:"minute", used:7, limit:240, remaining:233}, ...]
+```
+
+## Authentication
+
+1. Go to **Settings → API & Developer** in the Carrac dashboard.
+2. Click **Create Key**, copy the full key (shown once).
+3. Use it with `Client(api_key=...)` or set `CARRAC_API_KEY` in your environment.
+
+## Features
+
+- Per-user scoped keys — every call is rate-limited against your own Premium budget.
+- Automatic 429 backoff honouring `Retry-After`.
+- Pagination iterators for list endpoints.
+- Works in any Python ≥ 3.9 runtime (CPython, PyPy, Lambda, serverless).
+
+## Docs
+
+Interactive API reference: https://app.carrac.cc/api/docs
+OpenAPI spec: https://app.carrac.cc/api/openapi.json

carrac_sdk-0.1.0/README.md

@@ -0,0 +1,53 @@
+# Carrac Python SDK
+
+Official Python client for the [Carrac](https://carrac.cc) API. Use it to fetch market data, manage plays, create alerts, and inspect your API usage from any Python application.
+
+## Install
+
+```bash
+pip install carrac-sdk
+```
+
+Requires Python ≥ 3.9 and a Carrac Premium subscription (API keys require Premium).
+
+## Quick start
+
+```python
+from carrac import Client
+
+cvx = Client(api_key="carrac_k_...")
+
+# Market data
+chart = cvx.charts.get("BTC", timeframe="4h", indicators="CPR,RSI")
+
+# Composite call — everything about an asset in one request
+detail = cvx.composite.asset_detail("BTC", format="compact")
+
+# Create an alert
+cvx.alerts.create(symbol="BTC", alert_type="price", condition="above", price=120000)
+
+# Scanner
+ranked = cvx.scanner.list(direction="long", verdict="STRONG,GOOD")
+
+# Your usage
+usage = cvx.usage.get()
+print(usage["rest"]["usage"])  # [{window:"minute", used:7, limit:240, remaining:233}, ...]
+```
+
+## Authentication
+
+1. Go to **Settings → API & Developer** in the Carrac dashboard.
+2. Click **Create Key**, copy the full key (shown once).
+3. Use it with `Client(api_key=...)` or set `CARRAC_API_KEY` in your environment.
+
+## Features
+
+- Per-user scoped keys — every call is rate-limited against your own Premium budget.
+- Automatic 429 backoff honouring `Retry-After`.
+- Pagination iterators for list endpoints.
+- Works in any Python ≥ 3.9 runtime (CPython, PyPy, Lambda, serverless).
+
+## Docs
+
+Interactive API reference: https://app.carrac.cc/api/docs
+OpenAPI spec: https://app.carrac.cc/api/openapi.json

carrac_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "carrac-sdk"
+version = "0.1.0"
+description = "Official Python SDK for Carrac — market data, plays, alerts, usage"
+readme = "README.md"
+authors = [{ name = "Carrac", email = "hello@carrac.cc" }]
+license = "MIT"
+requires-python = ">=3.9"
+keywords = ["carrac", "trading", "crypto", "market-data", "sdk"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial :: Investment",
+]
+dependencies = [
+    "httpx>=0.25",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "pytest-httpx>=0.30"]
+
+[project.urls]
+Homepage = "https://carrac.cc"
+Documentation = "https://app.carrac.cc/api/docs"
+Source = "https://github.com/pgyula86/carrac-sdk-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/carrac"]

carrac_sdk-0.1.0/src/carrac/__init__.py

@@ -0,0 +1,34 @@
+"""Carrac Python SDK — trading market data, plays, alerts, usage."""
+
+from .client import Client
+from .errors import (
+    CarracError,
+    AuthError,
+    RateLimitError,
+    NotFoundError,
+    ApiError,
+    # Backward-compat aliases; remove in next major version
+    ConvexityError,
+    ConvexityAuthError,
+    ConvexityNotFoundError,
+    ConvexityRateLimitError,
+    ConvexityApiError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Client",
+    # New names
+    "CarracError",
+    "AuthError",
+    "RateLimitError",
+    "NotFoundError",
+    "ApiError",
+    # Backward-compat aliases; remove in next major version
+    "ConvexityError",
+    "ConvexityAuthError",
+    "ConvexityNotFoundError",
+    "ConvexityRateLimitError",
+    "ConvexityApiError",
+]

carrac_sdk-0.1.0/src/carrac/client.py

@@ -0,0 +1,146 @@
+"""Carrac API client.
+
+Thin wrapper around httpx. Resource namespaces (charts, plays, alerts, ...)
+organize the surface; all I/O goes through Client._request so retries and
+error handling stay in one place.
+"""
+
+import os
+import time
+
+import httpx
+
+from .errors import AuthError, NotFoundError, RateLimitError, ApiError
+
+DEFAULT_BASE_URL = "https://app.carrac.cc"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_USER_AGENT = "carrac-python-sdk/0.1.0"
+
+
+class Client:
+    """HTTP client for the Carrac API.
+
+    Args:
+        api_key: your Carrac API key. Falls back to CARRAC_API_KEY env var.
+            Also accepts the legacy CONVEXITY_API_KEY for backward compatibility.
+        base_url: override for staging / self-hosted deployments.
+        timeout: request timeout in seconds.
+        max_retries: how many times to automatically retry on 429 / 5xx.
+    """
+
+    def __init__(self, api_key=None, base_url=None, timeout=DEFAULT_TIMEOUT,
+                 max_retries=3, user_agent=DEFAULT_USER_AGENT):
+        self.api_key = (
+            api_key
+            or os.environ.get("CARRAC_API_KEY")
+            or os.environ.get("CONVEXITY_API_KEY")  # backward-compat
+        )
+        if not self.api_key:
+            raise ValueError(
+                "No API key provided. Pass api_key=... or set CARRAC_API_KEY."
+            )
+        self.base_url = (
+            base_url
+            or os.environ.get("CARRAC_BASE_URL")
+            or os.environ.get("CONVEXITY_BASE_URL")  # backward-compat
+            or DEFAULT_BASE_URL
+        ).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers={
+                "X-API-Key": self.api_key,
+                "User-Agent": user_agent,
+                "Accept": "application/json",
+            },
+        )
+
+        # Resource namespaces
+        from .resources import Charts, Plays, Alerts, Composite, Scanner, Usage, Keys
+        self.charts = Charts(self)
+        self.plays = Plays(self)
+        self.alerts = Alerts(self)
+        self.composite = Composite(self)
+        self.scanner = Scanner(self)
+        self.usage = Usage(self)
+        self.keys = Keys(self)
+
+    # ── Context manager support ──
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        self.close()
+
+    def close(self):
+        self._http.close()
+
+    # ── Core request ──
+
+    def _request(self, method, path, *, params=None, json=None):
+        attempts = 0
+        while True:
+            attempts += 1
+            try:
+                resp = self._http.request(method, path, params=params, json=json)
+            except httpx.TransportError as exc:
+                if attempts > self.max_retries:
+                    raise ApiError(f"Network error: {exc}") from exc
+                time.sleep(min(2 ** attempts, 10))
+                continue
+
+            if resp.status_code == 429 and attempts <= self.max_retries:
+                retry_after = int(resp.headers.get("Retry-After", "1"))
+                time.sleep(min(retry_after, 30))
+                continue
+
+            if 500 <= resp.status_code < 600 and attempts <= self.max_retries:
+                time.sleep(min(2 ** attempts, 10))
+                continue
+
+            self._raise_for_status(resp)
+
+            if resp.status_code == 204 or not resp.content:
+                return None
+            try:
+                return resp.json()
+            except ValueError as exc:
+                raise ApiError(f"Non-JSON response: {resp.text[:200]}") from exc
+
+    def _raise_for_status(self, resp):
+        if resp.is_success:
+            return
+        body = {}
+        try:
+            body = resp.json()
+        except ValueError:
+            pass
+        message = body.get("error") or resp.text or resp.reason_phrase
+
+        if resp.status_code in (401, 403):
+            raise AuthError(message, status_code=resp.status_code, response=body)
+        if resp.status_code == 404:
+            raise NotFoundError(message, status_code=resp.status_code, response=body)
+        if resp.status_code == 429:
+            raise RateLimitError(
+                message,
+                retry_after=int(resp.headers.get("Retry-After", "0")),
+                status_code=429,
+                response=body,
+            )
+        raise ApiError(message, status_code=resp.status_code, response=body)
+
+    # ── Shortcut methods ──
+    def get(self, path, **params):
+        return self._request("GET", path, params=params or None)
+
+    def post(self, path, json=None, **params):
+        return self._request("POST", path, params=params or None, json=json)
+
+    def put(self, path, json=None, **params):
+        return self._request("PUT", path, params=params or None, json=json)
+
+    def delete(self, path, **params):
+        return self._request("DELETE", path, params=params or None)

carrac_sdk-0.1.0/src/carrac/errors.py

@@ -0,0 +1,46 @@
+"""SDK error hierarchy.
+
+All API failures raise a subclass of CarracError. Callers can catch the
+base class to handle any API failure, or a specific subclass for targeted
+recovery (e.g. retrying on RateLimitError).
+"""
+
+
+class CarracError(Exception):
+    """Base class for all SDK errors."""
+
+    def __init__(self, message, status_code=None, response=None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.response = response
+
+
+class AuthError(CarracError):
+    """401/403 — missing, invalid, or insufficient API key / tier."""
+
+
+class NotFoundError(CarracError):
+    """404 — resource does not exist or is not visible to this key."""
+
+
+class RateLimitError(CarracError):
+    """429 — sliding-window budget exceeded.
+
+    `retry_after` is seconds until the soonest window frees up.
+    """
+
+    def __init__(self, message, retry_after=0, status_code=429, response=None):
+        super().__init__(message, status_code=status_code, response=response)
+        self.retry_after = retry_after
+
+
+class ApiError(CarracError):
+    """5xx or unclassified 4xx — server-side failure, treat as transient."""
+
+
+# Backward-compat aliases; remove in next major version
+ConvexityError = CarracError
+ConvexityAuthError = AuthError
+ConvexityNotFoundError = NotFoundError
+ConvexityRateLimitError = RateLimitError
+ConvexityApiError = ApiError

carrac_sdk-0.1.0/src/carrac/resources.py

@@ -0,0 +1,114 @@
+"""Resource namespaces — thin wrappers that build paths and delegate to the client."""
+
+
+class _Resource:
+    def __init__(self, client):
+        self._client = client
+
+
+class Charts(_Resource):
+    def get(self, symbol, *, timeframe=None, indicators=None):
+        """OHLCV + indicator data for a symbol (see /api/chart-internal)."""
+        params = {}
+        if timeframe:
+            params["timeframe"] = timeframe
+        if indicators:
+            params["indicators"] = indicators
+        return self._client.get(f"/api/chart-internal/{symbol}", **params)
+
+
+class Plays(_Resource):
+    def list(self, *, status=None, asset=None, type=None,
+             include_resolved=False, limit=50, offset=0):
+        params = {"limit": limit, "offset": offset, "include_resolved": str(include_resolved).lower()}
+        if status:
+            params["status"] = status
+        if asset:
+            params["asset"] = asset
+        if type:
+            params["type"] = type
+        return self._client.get("/api/plays", **params)
+
+    def active(self):
+        return self._client.get("/api/plays/active")
+
+    def context(self):
+        """Compact plays context for AI briefings."""
+        return self._client.get("/api/plays/context")
+
+    def get(self, play_id):
+        return self._client.get(f"/api/plays/{play_id}")
+
+    def create(self, **fields):
+        return self._client.post("/api/plays", json=fields)
+
+    def update(self, play_id, **fields):
+        return self._client.put(f"/api/plays/{play_id}", json=fields)
+
+    def delete(self, play_id):
+        return self._client.delete(f"/api/plays/{play_id}")
+
+
+class Alerts(_Resource):
+    def list(self, *, active=True, triggered_since=None):
+        params = {"active": str(active).lower()}
+        if triggered_since:
+            params["triggered_since"] = triggered_since
+        return self._client.get("/api/alerts", **params)
+
+    def create(self, **fields):
+        return self._client.post("/api/alerts", json=fields)
+
+    def delete(self, alert_id):
+        return self._client.delete(f"/api/alerts/{alert_id}")
+
+    def toggle(self, alert_id):
+        return self._client.post(f"/api/alerts/{alert_id}/toggle")
+
+
+class Composite(_Resource):
+    def asset_detail(self, symbol, *, format=None):
+        params = {"format": format} if format else {}
+        return self._client.get(f"/api/asset/{symbol}/detail", **params)
+
+    def live_positions(self, *, asset=None, format=None):
+        params = {}
+        if asset:
+            params["asset"] = asset
+        if format:
+            params["format"] = format
+        return self._client.get("/api/positions/live", **params)
+
+    def batch(self, assets, *, include=None, format=None):
+        if isinstance(assets, (list, tuple, set)):
+            assets = ",".join(assets)
+        params = {"assets": assets}
+        if include:
+            params["include"] = ",".join(include) if not isinstance(include, str) else include
+        if format:
+            params["format"] = format
+        return self._client.get("/api/batch", **params)
+
+
+class Scanner(_Resource):
+    def list(self, *, verdict=None, direction="both"):
+        params = {"direction": direction}
+        if verdict:
+            params["verdict"] = verdict
+        return self._client.get("/api/scanner", **params)
+
+
+class Usage(_Resource):
+    def get(self, *, history=True, days=30):
+        return self._client.get("/api/usage", history=str(history).lower(), days=days)
+
+
+class Keys(_Resource):
+    def list(self):
+        return self._client.get("/api/keys")
+
+    def create(self, name, *, scope="full"):
+        return self._client.post("/api/keys", json={"name": name, "scope": scope})
+
+    def revoke(self, key_id):
+        return self._client.delete(f"/api/keys/{key_id}")

carrac_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,172 @@
+"""Unit tests for the Python SDK (httpx MockTransport — no network)."""
+
+import pytest
+import httpx
+
+from carrac import Client, AuthError, RateLimitError, NotFoundError
+
+
+def _mock_client(handler):
+    """Create a Client backed by a MockTransport handler."""
+    transport = httpx.MockTransport(handler)
+    c = Client(api_key="test-key")
+    c._http = httpx.Client(
+        base_url=c.base_url,
+        transport=transport,
+        headers={"X-API-Key": c.api_key, "Accept": "application/json"},
+    )
+    return c
+
+
+class TestAuth:
+    def test_requires_api_key(self, monkeypatch):
+        monkeypatch.delenv("CARRAC_API_KEY", raising=False)
+        monkeypatch.delenv("CONVEXITY_API_KEY", raising=False)
+        with pytest.raises(ValueError):
+            Client()
+
+    def test_uses_env_var_fallback(self, monkeypatch):
+        monkeypatch.setenv("CARRAC_API_KEY", "carrac_k_fromenv")
+        c = Client()
+        assert c.api_key == "carrac_k_fromenv"
+
+    def test_legacy_env_var_fallback(self, monkeypatch):
+        monkeypatch.delenv("CARRAC_API_KEY", raising=False)
+        monkeypatch.setenv("CONVEXITY_API_KEY", "cvx_k_fromenv")
+        c = Client()
+        assert c.api_key == "cvx_k_fromenv"
+
+
+class TestResources:
+    def test_charts_get_builds_correct_url(self):
+        captured = {}
+
+        def handler(req):
+            captured["url"] = str(req.url)
+            captured["headers"] = dict(req.headers)
+            return httpx.Response(200, json={"candles": [], "symbol": "BTC"})
+
+        c = _mock_client(handler)
+        out = c.charts.get("BTC", timeframe="1h", indicators="CPR,RSI")
+        assert "/api/chart-internal/BTC" in captured["url"]
+        assert "timeframe=1h" in captured["url"]
+        assert "indicators=CPR%2CRSI" in captured["url"]
+        assert captured["headers"]["x-api-key"] == "test-key"
+        assert out["symbol"] == "BTC"
+
+    def test_plays_create_posts_json(self):
+        captured = {}
+
+        def handler(req):
+            captured["method"] = req.method
+            captured["body"] = req.content.decode()
+            return httpx.Response(201, json={"id": 99, "title": "Test"})
+
+        c = _mock_client(handler)
+        out = c.plays.create(title="Test", type="directional", primary_asset="BTC")
+        assert captured["method"] == "POST"
+        assert '"title":"Test"' in captured["body"] or '"title": "Test"' in captured["body"]
+        assert out["id"] == 99
+
+    def test_composite_batch_serializes_list_assets(self):
+        captured = {}
+
+        def handler(req):
+            captured["url"] = str(req.url)
+            return httpx.Response(200, json={"assets": {}})
+
+        c = _mock_client(handler)
+        c.composite.batch(["BTC", "ETH"], include=["market", "scanner"])
+        assert "assets=BTC%2CETH" in captured["url"]
+        assert "include=market%2Cscanner" in captured["url"]
+
+    def test_usage_get_includes_history_param(self):
+        captured = {}
+
+        def handler(req):
+            captured["url"] = str(req.url)
+            return httpx.Response(200, json={"user_id": 1, "rest": {}, "mcp": {}})
+
+        c = _mock_client(handler)
+        c.usage.get(history=False, days=7)
+        assert "history=false" in captured["url"]
+        assert "days=7" in captured["url"]
+
+
+class TestErrorHandling:
+    def test_401_raises_auth_error(self):
+        def handler(req):
+            return httpx.Response(401, json={"error": "bad key"})
+
+        c = _mock_client(handler)
+        c.max_retries = 0
+        with pytest.raises(AuthError) as exc:
+            c.charts.get("BTC")
+        assert exc.value.status_code == 401
+
+    def test_404_raises_notfound(self):
+        def handler(req):
+            return httpx.Response(404, json={"error": "not found"})
+
+        c = _mock_client(handler)
+        c.max_retries = 0
+        with pytest.raises(NotFoundError):
+            c.plays.get(999)
+
+    def test_429_raises_after_retries(self):
+        calls = {"n": 0}
+
+        def handler(req):
+            calls["n"] += 1
+            return httpx.Response(429, headers={"Retry-After": "2"},
+                                  json={"error": "rate limited", "limit": 240,
+                                        "window": "minute", "retry_after": 2})
+
+        c = _mock_client(handler)
+        c.max_retries = 2
+        with pytest.raises(RateLimitError) as exc:
+            c.charts.get("BTC")
+        assert calls["n"] == 3  # initial + 2 retries
+        # retry_after comes from the Retry-After header, not the JSON body.
+        assert exc.value.retry_after == 2
+
+
+class TestPaths:
+    def test_alerts_delete_builds_correct_url(self):
+        captured = {}
+
+        def handler(req):
+            captured["method"] = req.method
+            captured["path"] = req.url.path
+            return httpx.Response(204)
+
+        c = _mock_client(handler)
+        c.alerts.delete(42)
+        assert captured["method"] == "DELETE"
+        assert captured["path"] == "/api/alerts/42"
+
+    def test_alerts_toggle_posts_to_correct_url(self):
+        captured = {}
+
+        def handler(req):
+            captured["method"] = req.method
+            captured["path"] = req.url.path
+            return httpx.Response(200, json={"id": 7, "active": False})
+
+        c = _mock_client(handler)
+        c.alerts.toggle(7)
+        assert captured["method"] == "POST"
+        assert captured["path"] == "/api/alerts/7/toggle"
+
+    def test_keys_revoke_builds_correct_url(self):
+        captured = {}
+
+        def handler(req):
+            captured["method"] = req.method
+            captured["path"] = req.url.path
+            return httpx.Response(200, json={"success": True})
+
+        c = _mock_client(handler)
+        c.keys.revoke(5)
+        assert captured["method"] == "DELETE"
+        assert captured["path"] == "/api/keys/5"