decane-sdk 0.8.0__py3-none-any.whl

decane/__init__.py

@@ -0,0 +1,45 @@
+"""Decane — Official Python SDK for institutional liquidity rail for crypto settlement."""
+
+from .client import Decane, AsyncDecane
+from .errors import (
+    DecaneError,
+    AuthenticationError,
+    NotFoundError,
+    ValidationError,
+    RateLimitError,
+    ServerError,
+    InvalidSignatureError,
+)
+from .types import (
+    Invoice,
+    InvoiceStatus,
+    Payment,
+    Payout,
+    PayoutStatus,
+    Wallet,
+    SwapQuote,
+    Swap,
+    WebhookEvent,
+)
+
+__version__ = "0.8.0"
+__all__ = [
+    "Decane",
+    "AsyncDecane",
+    "DecaneError",
+    "AuthenticationError",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimitError",
+    "ServerError",
+    "InvalidSignatureError",
+    "Invoice",
+    "InvoiceStatus",
+    "Payment",
+    "Payout",
+    "PayoutStatus",
+    "Wallet",
+    "SwapQuote",
+    "Swap",
+    "WebhookEvent",
+]

decane/_internal/http.py

@@ -0,0 +1,195 @@
+"""HTTP transport layer for Decane SDK."""
+
+from __future__ import annotations
+
+import time
+import uuid
+from typing import Any
+
+import httpx
+
+from ..errors import (
+    AuthenticationError,
+    DecaneError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+DEFAULT_BASE_URL = "https://api.decane.io/api/v1/"
+DEFAULT_TIMEOUT = 30.0
+MAX_RETRIES = 3
+RETRY_STATUSES = {429, 500, 502, 503, 504}
+
+
+def _build_headers(api_key: str, api_secret: str | None = None) -> dict[str, str]:
+    headers = {
+        "X-API-Key": api_key,
+        "Content-Type": "application/json",
+        "User-Agent": "decane-python/0.8.0",
+    }
+    if api_secret:
+        headers["X-API-Secret"] = api_secret
+    return headers
+
+
+def _with_idempotency(kwargs: dict[str, Any], key: str | None) -> dict[str, Any]:
+    """Return kwargs with an Idempotency-Key header (generated if not given)."""
+    headers = dict(kwargs.get("headers") or {})
+    headers["Idempotency-Key"] = key or str(uuid.uuid4())
+    return {**kwargs, "headers": headers}
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    """Raise typed SDK errors from HTTP responses."""
+    if response.status_code < 400:
+        return
+
+    try:
+        body = response.json()
+    except Exception:
+        body = {"detail": response.text}
+
+    message = body.get("detail", body.get("message", body.get("error", str(body))))
+    code = body.get("code")
+
+    if response.status_code == 401:
+        raise AuthenticationError(message)
+    if response.status_code == 404:
+        raise NotFoundError(message)
+    if response.status_code == 422:
+        raise ValidationError(message, errors=body.get("errors"))
+    if response.status_code == 429:
+        retry_after = response.headers.get("Retry-After")
+        raise RateLimitError(message, retry_after=float(retry_after) if retry_after else None)
+    if response.status_code >= 500:
+        raise ServerError(message)
+
+    raise DecaneError(message, code=code, status=response.status_code)
+
+
+class SyncHTTP:
+    """Synchronous HTTP client with retry logic."""
+
+    def __init__(self, api_key: str, base_url: str, timeout: float, api_secret: str | None = None):
+        self._client = httpx.Client(
+            base_url=base_url,
+            headers=_build_headers(api_key, api_secret),
+            timeout=timeout,
+        )
+
+    def request(self, method: str, path: str, **kwargs: Any) -> Any:
+        last_exc: Exception | None = None
+        for attempt in range(MAX_RETRIES):
+            try:
+                response = self._client.request(method, path, **kwargs)
+                if response.status_code in RETRY_STATUSES and attempt < MAX_RETRIES - 1:
+                    wait = (2**attempt) * 0.5
+                    if response.status_code == 429:
+                        retry_after = response.headers.get("Retry-After")
+                        if retry_after:
+                            wait = float(retry_after)
+                    time.sleep(wait)
+                    continue
+                _raise_for_status(response)
+                if response.status_code == 204:
+                    return None
+                return response.json()
+            except (httpx.ConnectError, httpx.TimeoutException) as e:
+                last_exc = e
+                if attempt < MAX_RETRIES - 1:
+                    time.sleep((2**attempt) * 0.5)
+                    continue
+                raise DecaneError(f"Connection error: {e}", code="network_error") from e
+        if last_exc:
+            raise DecaneError(f"Max retries exceeded: {last_exc}", code="network_error") from last_exc
+        raise DecaneError("Unexpected error", code="unknown")
+
+    def get(self, path: str, **kwargs: Any) -> Any:
+        return self.request("GET", path, **kwargs)
+
+    def post(self, path: str, *, idempotency_key: str | None = None, **kwargs: Any) -> Any:
+        if idempotency_key is not None:
+            kwargs = _with_idempotency(kwargs, idempotency_key)
+        return self.request("POST", path, **kwargs)
+
+    def post_idempotent(self, path: str, *, idempotency_key: str | None = None, **kwargs: Any) -> Any:
+        """POST with an Idempotency-Key header (random UUID if none given)."""
+        return self.request("POST", path, **_with_idempotency(kwargs, idempotency_key))
+
+    def put(self, path: str, **kwargs: Any) -> Any:
+        return self.request("PUT", path, **kwargs)
+
+    def patch(self, path: str, **kwargs: Any) -> Any:
+        return self.request("PATCH", path, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> Any:
+        return self.request("DELETE", path, **kwargs)
+
+    def close(self) -> None:
+        self._client.close()
+
+
+class AsyncHTTP:
+    """Async HTTP client with retry logic."""
+
+    def __init__(self, api_key: str, base_url: str, timeout: float, api_secret: str | None = None):
+        self._client = httpx.AsyncClient(
+            base_url=base_url,
+            headers=_build_headers(api_key, api_secret),
+            timeout=timeout,
+        )
+
+    async def request(self, method: str, path: str, **kwargs: Any) -> Any:
+        import asyncio
+
+        last_exc: Exception | None = None
+        for attempt in range(MAX_RETRIES):
+            try:
+                response = await self._client.request(method, path, **kwargs)
+                if response.status_code in RETRY_STATUSES and attempt < MAX_RETRIES - 1:
+                    wait = (2**attempt) * 0.5
+                    if response.status_code == 429:
+                        retry_after = response.headers.get("Retry-After")
+                        if retry_after:
+                            wait = float(retry_after)
+                    await asyncio.sleep(wait)
+                    continue
+                _raise_for_status(response)
+                if response.status_code == 204:
+                    return None
+                return response.json()
+            except (httpx.ConnectError, httpx.TimeoutException) as e:
+                last_exc = e
+                if attempt < MAX_RETRIES - 1:
+                    await asyncio.sleep((2**attempt) * 0.5)
+                    continue
+                raise DecaneError(f"Connection error: {e}", code="network_error") from e
+        if last_exc:
+            raise DecaneError(f"Max retries exceeded: {last_exc}", code="network_error") from last_exc
+        raise DecaneError("Unexpected error", code="unknown")
+
+    async def get(self, path: str, **kwargs: Any) -> Any:
+        return await self.request("GET", path, **kwargs)
+
+    async def post(self, path: str, *, idempotency_key: str | None = None, **kwargs: Any) -> Any:
+        if idempotency_key is not None:
+            kwargs = _with_idempotency(kwargs, idempotency_key)
+        return await self.request("POST", path, **kwargs)
+
+    async def post_idempotent(self, path: str, *, idempotency_key: str | None = None, **kwargs: Any) -> Any:
+        """POST with an Idempotency-Key header (random UUID if none given)."""
+        return await self.request("POST", path, **_with_idempotency(kwargs, idempotency_key))
+
+    async def put(self, path: str, **kwargs: Any) -> Any:
+        return await self.request("PUT", path, **kwargs)
+
+    async def patch(self, path: str, **kwargs: Any) -> Any:
+        return await self.request("PATCH", path, **kwargs)
+
+    async def delete(self, path: str, **kwargs: Any) -> Any:
+        return await self.request("DELETE", path, **kwargs)
+
+    async def close(self) -> None:
+        await self._client.aclose()

decane/client.py

@@ -0,0 +1,122 @@
+"""Decane client — the main entry point for the SDK."""
+
+from __future__ import annotations
+
+from ._internal.http import AsyncHTTP, SyncHTTP, DEFAULT_BASE_URL, DEFAULT_TIMEOUT
+from .resources.invoices import AsyncInvoices, Invoices
+from .resources.payouts import AsyncPayouts, Payouts
+from .resources.swaps import AsyncSwaps, Swaps
+from .resources.wallets import AsyncWallets, Wallets
+from .resources.webhooks import Webhooks
+from .resources.payment_links import AsyncPaymentLinks, PaymentLinks
+from .resources.subscriptions import AsyncSubscriptions, Subscriptions
+
+
+class Decane:
+    """Synchronous Decane client.
+
+    Usage::
+
+        from decane import Decane
+
+        flow = Decane(api_key="gr_...", webhook_secret="gr_whsec_...")
+
+        # Create an invoice
+        invoice = flow.invoices.create(
+            amount=100, currency="USDT", network="tron",
+        )
+        print(invoice.wallet_address)
+
+        # Request a payout
+        payout = flow.payouts.create(
+            amount=50, currency="USDT", network="tron",
+            destination="TXyz...addr",
+        )
+
+        # Verify a webhook
+        event = flow.webhooks.verify(payload, signature)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        api_secret: str | None = None,
+        webhook_secret: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ):
+        if not api_key:
+            raise ValueError("api_key is required")
+
+        self._http = SyncHTTP(api_key=api_key, base_url=base_url, timeout=timeout, api_secret=api_secret)
+
+        self.invoices = Invoices(self._http)
+        self.payouts = Payouts(self._http)
+        self.wallets = Wallets(self._http)
+        self.swaps = Swaps(self._http)
+        self.webhooks = Webhooks(webhook_secret or "")
+        self.payment_links = PaymentLinks(self._http)
+        self.subscriptions = Subscriptions(self._http)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._http.close()
+
+    def __enter__(self) -> Decane:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return "Decane(connected)"
+
+
+class AsyncDecane:
+    """Async Decane client.
+
+    Usage::
+
+        from decane import AsyncDecane
+
+        async with AsyncDecane(api_key="gr_...") as flow:
+            invoice = await flow.invoices.create(
+                amount=100, currency="USDT", network="tron",
+            )
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        api_secret: str | None = None,
+        webhook_secret: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ):
+        if not api_key:
+            raise ValueError("api_key is required")
+
+        self._http = AsyncHTTP(api_key=api_key, base_url=base_url, timeout=timeout, api_secret=api_secret)
+
+        self.invoices = AsyncInvoices(self._http)
+        self.payouts = AsyncPayouts(self._http)
+        self.wallets = AsyncWallets(self._http)
+        self.swaps = AsyncSwaps(self._http)
+        self.webhooks = Webhooks(webhook_secret or "")
+        self.payment_links = AsyncPaymentLinks(self._http)
+        self.subscriptions = AsyncSubscriptions(self._http)
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._http.close()
+
+    async def __aenter__(self) -> AsyncDecane:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()
+
+    def __repr__(self) -> str:
+        return "AsyncDecane(connected)"

decane/errors.py

@@ -0,0 +1,60 @@
+"""Decane SDK error types."""
+
+from __future__ import annotations
+
+
+class DecaneError(Exception):
+    """Base error for all Decane SDK errors."""
+
+    def __init__(self, message: str, code: str | None = None, status: int | None = None):
+        self.message = message
+        self.code = code
+        self.status = status
+        super().__init__(message)
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(message={self.message!r}, code={self.code!r}, status={self.status})"
+
+
+class AuthenticationError(DecaneError):
+    """Invalid or missing API key."""
+
+    def __init__(self, message: str = "Invalid or missing API key"):
+        super().__init__(message, code="authentication_error", status=401)
+
+
+class NotFoundError(DecaneError):
+    """Resource not found."""
+
+    def __init__(self, message: str = "Resource not found"):
+        super().__init__(message, code="not_found", status=404)
+
+
+class ValidationError(DecaneError):
+    """Invalid request parameters."""
+
+    def __init__(self, message: str = "Validation error", errors: list[dict] | None = None):
+        self.errors = errors or []
+        super().__init__(message, code="validation_error", status=422)
+
+
+class RateLimitError(DecaneError):
+    """Too many requests."""
+
+    def __init__(self, message: str = "Rate limit exceeded", retry_after: float | None = None):
+        self.retry_after = retry_after
+        super().__init__(message, code="rate_limit", status=429)
+
+
+class ServerError(DecaneError):
+    """Server-side error."""
+
+    def __init__(self, message: str = "Internal server error"):
+        super().__init__(message, code="server_error", status=500)
+
+
+class InvalidSignatureError(DecaneError):
+    """Webhook signature verification failed."""
+
+    def __init__(self, message: str = "Invalid webhook signature"):
+        super().__init__(message, code="invalid_signature", status=None)

decane/resources/__init__.py

@@ -0,0 +1,17 @@
+from .invoices import Invoices, AsyncInvoices
+from .payouts import Payouts, AsyncPayouts
+from .wallets import Wallets, AsyncWallets
+from .swaps import Swaps, AsyncSwaps
+from .webhooks import Webhooks
+from .payment_links import PaymentLinks, AsyncPaymentLinks
+from .subscriptions import Subscriptions, AsyncSubscriptions
+
+__all__ = [
+    "Invoices", "AsyncInvoices",
+    "Payouts", "AsyncPayouts",
+    "Wallets", "AsyncWallets",
+    "Swaps", "AsyncSwaps",
+    "Webhooks",
+    "PaymentLinks", "AsyncPaymentLinks",
+    "Subscriptions", "AsyncSubscriptions",
+]

decane/resources/invoices.py

@@ -0,0 +1,155 @@
+"""Invoice resource — create and manage payment invoices."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .._internal.http import AsyncHTTP, SyncHTTP
+from ..types import Invoice, PaginatedList
+
+
+class Invoices:
+    """Synchronous invoice operations."""
+
+    def __init__(self, http: SyncHTTP):
+        self._http = http
+
+    def create(
+        self,
+        amount: float,
+        currency: str = "USD",
+        *,
+        network: str | None = None,
+        crypto_currency: str | None = None,
+        merchant_order_id: str | None = None,
+        customer_email: str | None = None,
+        customer_name: str | None = None,
+        callback_url: str | None = None,
+        return_url: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> Invoice:
+        """Create a payment invoice.
+
+        Omit ``network`` and ``crypto_currency`` to create a **flex invoice**
+        where the customer picks their preferred crypto on the payment page.
+        Supply both to lock the rate at creation time (fixed invoice).
+
+        ``idempotency_key`` is sent as the ``Idempotency-Key`` header. If you
+        omit it, a random key is generated so automatic retries cannot create
+        a second invoice. Pass your own key to make retries from your side safe.
+        """
+        payload: dict[str, Any] = {"amount": amount, "currency": currency}
+        if network is not None:
+            payload["network"] = network
+        if crypto_currency is not None:
+            payload["crypto_currency"] = crypto_currency
+        if merchant_order_id is not None:
+            payload["merchant_order_id"] = merchant_order_id
+        if customer_email is not None:
+            payload["customer_email"] = customer_email
+        if customer_name is not None:
+            payload["customer_name"] = customer_name
+        if callback_url is not None:
+            payload["callback_url"] = callback_url
+        if return_url is not None:
+            payload["return_url"] = return_url
+        if metadata is not None:
+            payload["metadata"] = metadata
+
+        data = self._http.post_idempotent("/invoices", json=payload, idempotency_key=idempotency_key)
+        return Invoice.from_dict(data)
+
+    def get(self, invoice_id: str) -> Invoice:
+        """Get an invoice by ID."""
+        data = self._http.get(f"/invoices/{invoice_id}")
+        return Invoice.from_dict(data)
+
+    def list(
+        self,
+        *,
+        status: str | None = None,
+        currency: str | None = None,
+        page: int = 1,
+        limit: int = 50,
+    ) -> PaginatedList:
+        """List invoices with optional filters."""
+        params: dict[str, Any] = {"page": page, "limit": limit}
+        if status:
+            params["status"] = status
+        if currency:
+            params["currency"] = currency
+        data = self._http.get("/invoices", params=params)
+        return PaginatedList.from_dict(data, Invoice)
+
+    def cancel(self, invoice_id: str) -> Invoice:
+        """Cancel a pending invoice."""
+        data = self._http.post(f"/invoices/{invoice_id}/cancel")
+        return Invoice.from_dict(data)
+
+
+class AsyncInvoices:
+    """Async invoice operations."""
+
+    def __init__(self, http: AsyncHTTP):
+        self._http = http
+
+    async def create(
+        self,
+        amount: float,
+        currency: str = "USD",
+        *,
+        network: str | None = None,
+        crypto_currency: str | None = None,
+        merchant_order_id: str | None = None,
+        customer_email: str | None = None,
+        customer_name: str | None = None,
+        callback_url: str | None = None,
+        return_url: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> Invoice:
+        payload: dict[str, Any] = {"amount": amount, "currency": currency}
+        if network is not None:
+            payload["network"] = network
+        if crypto_currency is not None:
+            payload["crypto_currency"] = crypto_currency
+        if merchant_order_id is not None:
+            payload["merchant_order_id"] = merchant_order_id
+        if customer_email is not None:
+            payload["customer_email"] = customer_email
+        if customer_name is not None:
+            payload["customer_name"] = customer_name
+        if callback_url is not None:
+            payload["callback_url"] = callback_url
+        if return_url is not None:
+            payload["return_url"] = return_url
+        if metadata is not None:
+            payload["metadata"] = metadata
+
+        data = await self._http.post_idempotent("/invoices", json=payload, idempotency_key=idempotency_key)
+        return Invoice.from_dict(data)
+
+    async def get(self, invoice_id: str) -> Invoice:
+        data = await self._http.get(f"/invoices/{invoice_id}")
+        return Invoice.from_dict(data)
+
+    async def list(
+        self,
+        *,
+        status: str | None = None,
+        currency: str | None = None,
+        page: int = 1,
+        limit: int = 50,
+    ) -> PaginatedList:
+        params: dict[str, Any] = {"page": page, "limit": limit}
+        if status:
+            params["status"] = status
+        if currency:
+            params["currency"] = currency
+        data = await self._http.get("/invoices", params=params)
+        return PaginatedList.from_dict(data, Invoice)
+
+    async def cancel(self, invoice_id: str) -> Invoice:
+        data = await self._http.post(f"/invoices/{invoice_id}/cancel")
+        return Invoice.from_dict(data)

decane/resources/payment_links.py

@@ -0,0 +1,81 @@
+"""Payment link resource — create and manage hosted payment links."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .._internal.http import AsyncHTTP, SyncHTTP
+
+
+class PaymentLinks:
+    """Synchronous payment link operations."""
+
+    def __init__(self, http: SyncHTTP):
+        self._http = http
+
+    def create(
+        self,
+        amount: float,
+        currency: str,
+        *,
+        title: str | None = None,
+        description: str | None = None,
+        redirect_url: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {"amount": amount, "currency": currency}
+        if title is not None:
+            payload["title"] = title
+        if description is not None:
+            payload["description"] = description
+        if redirect_url is not None:
+            payload["redirect_url"] = redirect_url
+        if metadata is not None:
+            payload["metadata"] = metadata
+        return self._http.post("/merchants/me/payment-links", json=payload)
+
+    def list(self, *, page: int = 1, limit: int = 50) -> list[dict[str, Any]]:
+        return self._http.get("/merchants/me/payment-links", params={"page": page, "limit": limit})
+
+    def update(self, link_id: str, **fields: Any) -> dict[str, Any]:
+        return self._http.patch(f"/merchants/me/payment-links/{link_id}", json=fields)
+
+    def delete(self, link_id: str) -> None:
+        self._http.delete(f"/merchants/me/payment-links/{link_id}")
+
+
+class AsyncPaymentLinks:
+    """Async payment link operations."""
+
+    def __init__(self, http: AsyncHTTP):
+        self._http = http
+
+    async def create(
+        self,
+        amount: float,
+        currency: str,
+        *,
+        title: str | None = None,
+        description: str | None = None,
+        redirect_url: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {"amount": amount, "currency": currency}
+        if title is not None:
+            payload["title"] = title
+        if description is not None:
+            payload["description"] = description
+        if redirect_url is not None:
+            payload["redirect_url"] = redirect_url
+        if metadata is not None:
+            payload["metadata"] = metadata
+        return await self._http.post("/merchants/me/payment-links", json=payload)
+
+    async def list(self, *, page: int = 1, limit: int = 50) -> list[dict[str, Any]]:
+        return await self._http.get("/merchants/me/payment-links", params={"page": page, "limit": limit})
+
+    async def update(self, link_id: str, **fields: Any) -> dict[str, Any]:
+        return await self._http.patch(f"/merchants/me/payment-links/{link_id}", json=fields)
+
+    async def delete(self, link_id: str) -> None:
+        await self._http.delete(f"/merchants/me/payment-links/{link_id}")