kortana-dev-sdk 1.0.0__tar.gz

kortana_dev_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: kortana-dev-sdk
+Version: 1.0.0
+Summary: Official Kortana SDK for Python
+License: MIT
+Author: Kortana Labs
+Author-email: engineering@kortana.io
+Requires-Python: >=3.9,<4.0
+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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: anyio (>=4.0.0,<5.0.0)
+Requires-Dist: cryptography (>=42.0.0,<43.0.0)
+Requires-Dist: httpx (>=0.27.0,<0.28.0)
+Requires-Dist: pydantic (>=2.5.0,<3.0.0)
+Requires-Dist: pydantic-settings (>=2.1.0,<3.0.0)
+Project-URL: Homepage, https://docs.kortana.io/sdk/python
+Project-URL: Repository, https://github.com/kortana-labs/sdk-python
+Description-Content-Type: text/markdown
+
+# kortana-dev-sdk — Official Kortana Python SDK
+
+[![PyPI](https://img.shields.io/pypi/v/kortana-dev-sdk)](https://pypi.org/project/kortana-dev-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/kortana-dev-sdk)](https://pypi.org/project/kortana-dev-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+The official Python SDK for the [Kortana](https://kortana.io) blockchain payments platform.
+
+## Installation
+
+```bash
+pip install kortana-dev-sdk
+# or
+poetry add kortana-dev-sdk
+```
+
+## Quick Start
+
+```python
+import asyncio
+import os
+from kortana import kortana
+
+async def main():
+    async with kortana(
+        api_key=os.environ["KORTANA_API_KEY"],
+        environment="mainnet",
+    ) as client:
+        # Check network status
+        status = await client.blockchain.get_network_status()
+        print(f"Block: {status.block_number}")
+
+        # Get wallet balance
+        balance = await client.wallets.get_balance()
+        print(f"Balance: {balance.available} DNR")
+
+        # Create a payment link
+        link = await client.payments.create_link(
+            amount=1_000_000_000_000_000_000,  # 1 DNR in wei
+            currency="DNR",
+            description="Invoice #1001",
+        )
+        print(f"Payment URL: {link.url}")
+
+asyncio.run(main())
+```
+
+## Webhook Verification
+
+```python
+from kortana import kortana
+
+client = kortana(api_key="kt_live_...", webhook_secret="whsec_...")
+
+@app.post("/webhooks")
+async def handle_webhook(request: Request):
+    payload = await request.body()
+    signature = request.headers.get("X-Kortana-Signature", "")
+    event = client.validate_webhook(payload.decode(), signature)
+    if event["type"] == "transfer.completed":
+        print("Transfer done!", event["data"])
+    return {"received": True}
+```
+
+## Modules
+
+| Module | Description |
+|---|---|
+| `client.blockchain` | Read-only blockchain data (blocks, txs, gas) |
+| `client.contracts` | Deploy and interact with smart contracts |
+| `client.wallets` | HD wallet management and transfers |
+| `client.payments` | Payment intents, invoices, subscriptions |
+| `client.banking` | Customer and bank account management |
+| `client.cards` | Virtual and physical card issuance |
+| `client.compliance` | KYC, KYB, and AML screening |
+| `client.settlement` | Ledger settlement and treasury |
+| `client.merchants` | Merchant onboarding and management |
+
+## Requirements
+
+- Python 3.9+
+- `httpx >= 0.27`
+- `pydantic >= 2.5`
+
+## License
+
+MIT © Kortana Labs
+

kortana_dev_sdk-1.0.0/README.md

@@ -0,0 +1,87 @@
+# kortana-dev-sdk — Official Kortana Python SDK
+
+[![PyPI](https://img.shields.io/pypi/v/kortana-dev-sdk)](https://pypi.org/project/kortana-dev-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/kortana-dev-sdk)](https://pypi.org/project/kortana-dev-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+The official Python SDK for the [Kortana](https://kortana.io) blockchain payments platform.
+
+## Installation
+
+```bash
+pip install kortana-dev-sdk
+# or
+poetry add kortana-dev-sdk
+```
+
+## Quick Start
+
+```python
+import asyncio
+import os
+from kortana import kortana
+
+async def main():
+    async with kortana(
+        api_key=os.environ["KORTANA_API_KEY"],
+        environment="mainnet",
+    ) as client:
+        # Check network status
+        status = await client.blockchain.get_network_status()
+        print(f"Block: {status.block_number}")
+
+        # Get wallet balance
+        balance = await client.wallets.get_balance()
+        print(f"Balance: {balance.available} DNR")
+
+        # Create a payment link
+        link = await client.payments.create_link(
+            amount=1_000_000_000_000_000_000,  # 1 DNR in wei
+            currency="DNR",
+            description="Invoice #1001",
+        )
+        print(f"Payment URL: {link.url}")
+
+asyncio.run(main())
+```
+
+## Webhook Verification
+
+```python
+from kortana import kortana
+
+client = kortana(api_key="kt_live_...", webhook_secret="whsec_...")
+
+@app.post("/webhooks")
+async def handle_webhook(request: Request):
+    payload = await request.body()
+    signature = request.headers.get("X-Kortana-Signature", "")
+    event = client.validate_webhook(payload.decode(), signature)
+    if event["type"] == "transfer.completed":
+        print("Transfer done!", event["data"])
+    return {"received": True}
+```
+
+## Modules
+
+| Module | Description |
+|---|---|
+| `client.blockchain` | Read-only blockchain data (blocks, txs, gas) |
+| `client.contracts` | Deploy and interact with smart contracts |
+| `client.wallets` | HD wallet management and transfers |
+| `client.payments` | Payment intents, invoices, subscriptions |
+| `client.banking` | Customer and bank account management |
+| `client.cards` | Virtual and physical card issuance |
+| `client.compliance` | KYC, KYB, and AML screening |
+| `client.settlement` | Ledger settlement and treasury |
+| `client.merchants` | Merchant onboarding and management |
+
+## Requirements
+
+- Python 3.9+
+- `httpx >= 0.27`
+- `pydantic >= 2.5`
+
+## License
+
+MIT © Kortana Labs

kortana_dev_sdk-1.0.0/kortana/__init__.py

@@ -0,0 +1,67 @@
+"""
+kortana-dev-sdk — Official Kortana Python SDK.
+
+Usage:
+    from kortana import kortana
+
+    async with kortana(api_key="kt_live_...", environment="mainnet") as client:
+        balance = await client.wallets.get_balance()
+"""
+
+from __future__ import annotations
+
+from .client import AsyncKortanaClient
+from .config import KortanaConfig
+from .exceptions import (
+    KortanaError,
+    KortanaConfigError,
+    KortanaAuthError,
+    KortanaNetworkError,
+    KortanaRateLimitError,
+    KortanaValidationError,
+    KortanaNotFoundError,
+    KortanaConflictError,
+    KortanaWebhookSignatureError,
+    KortanaServerError,
+)
+
+__version__ = "1.0.0"
+__all__ = [
+    "kortana",
+    "AsyncKortanaClient",
+    "KortanaConfig",
+    "KortanaError",
+    "KortanaConfigError",
+    "KortanaAuthError",
+    "KortanaNetworkError",
+    "KortanaRateLimitError",
+    "KortanaValidationError",
+    "KortanaNotFoundError",
+    "KortanaConflictError",
+    "KortanaWebhookSignatureError",
+    "KortanaServerError",
+]
+
+
+def kortana(
+    api_key: str,
+    environment: str = "mainnet",
+    **kwargs: object,
+) -> AsyncKortanaClient:
+    """
+    Factory function to create a Kortana client.
+
+    Args:
+        api_key: Your Kortana API key (kt_live_... or kt_test_...).
+        environment: 'mainnet' or 'testnet'. Defaults to 'mainnet'.
+        **kwargs: Additional config overrides (timeout, max_retries, webhook_secret, etc.).
+
+    Returns:
+        AsyncKortanaClient that supports use as an async context manager.
+
+    Example:
+        async with kortana(api_key=os.environ["KORTANA_API_KEY"]) as client:
+            balance = await client.wallets.get_balance()
+    """
+    config = KortanaConfig(api_key=api_key, environment=environment, **kwargs)  # type: ignore[arg-type]
+    return AsyncKortanaClient(config)

kortana_dev_sdk-1.0.0/kortana/auth/__init__.py

@@ -0,0 +1 @@
+"""Auth sub-package for Kortana SDK."""

kortana_dev_sdk-1.0.0/kortana/auth/authenticator.py

@@ -0,0 +1,65 @@
+"""
+Authenticator — handles API key pass-through and JWT token auto-refresh.
+"""
+from __future__ import annotations
+
+import time
+from typing import Optional
+
+import httpx
+
+from kortana.config import KortanaConfig
+from kortana.exceptions import KortanaAuthError
+
+
+class Authenticator:
+    """
+    Manages authentication tokens for the Kortana API.
+
+    - API keys (kt_live_... / kt_test_...) are passed through directly.
+    - Other credentials trigger JWT token acquisition with auto-refresh
+      60 seconds before expiry.
+    """
+
+    _TOKEN_TTL_SECONDS = 900  # 15 minutes
+    _REFRESH_BUFFER_SECONDS = 60
+
+    def __init__(self, config: KortanaConfig) -> None:
+        self._config = config
+        self._token: Optional[str] = None
+        self._token_expiry: float = 0.0
+
+    async def get_token(self) -> str:
+        """Return a valid authentication token."""
+        if self._config.api_key.startswith("kt_"):
+            # Direct API key — pass through as Bearer token
+            return self._config.api_key
+
+        # JWT mode — refresh if expired or expiring soon
+        if self._token and time.monotonic() < self._token_expiry - self._REFRESH_BUFFER_SECONDS:
+            return self._token
+
+        return await self._refresh_token()
+
+    async def _refresh_token(self) -> str:
+        """Obtain a new JWT from the auth endpoint."""
+        auth_base = self._config.get_base_url().replace("/v1", "")
+        url = f"{auth_base}/auth/token"
+
+        async with httpx.AsyncClient(timeout=self._config.connect_timeout) as client:
+            response = await client.post(
+                url,
+                headers={
+                    "Authorization": f"Bearer {self._config.api_key}",
+                    "Content-Type": "application/json",
+                },
+            )
+
+        if not response.is_success:
+            raise KortanaAuthError("Failed to authenticate with Kortana API")
+
+        data = response.json()
+        token: str = data["data"]["token"]
+        self._token = token
+        self._token_expiry = time.monotonic() + self._TOKEN_TTL_SECONDS
+        return self._token

kortana_dev_sdk-1.0.0/kortana/client.py

@@ -0,0 +1,58 @@
+"""
+Core Async Kortana client.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from kortana.auth.authenticator import Authenticator
+from kortana.config import KortanaConfig
+from kortana.http.client import AsyncHttpClient
+from kortana.modules.banking import BankingModule
+from kortana.modules.blockchain import BlockchainModule
+from kortana.modules.cards import CardsModule
+from kortana.modules.compliance import ComplianceModule
+from kortana.modules.contracts import ContractsModule
+from kortana.modules.merchants import MerchantsModule
+from kortana.modules.payments import PaymentsModule
+from kortana.modules.settlement import SettlementModule
+from kortana.modules.wallets import WalletsModule
+from kortana.webhooks.verifier import Webhook
+
+
+class AsyncKortanaClient:
+    """
+    Official asynchronous client for the Kortana blockchain platform.
+    """
+
+    def __init__(self, config: KortanaConfig) -> None:
+        self._config = config
+        self._auth = Authenticator(config)
+        self._http = AsyncHttpClient(config, self._auth)
+        self._webhook_verifier = Webhook(config.webhook_secret)
+
+        # Initialize all domain modules
+        self.blockchain = BlockchainModule(self._http)
+        self.wallets = WalletsModule(self._http)
+        self.contracts = ContractsModule(self._http)
+        self.payments = PaymentsModule(self._http)
+        self.merchants = MerchantsModule(self._http)
+        self.banking = BankingModule(self._http)
+        self.cards = CardsModule(self._http)
+        self.compliance = ComplianceModule(self._http)
+        self.settlement = SettlementModule(self._http)
+
+    def validate_webhook(self, payload: str, signature: str) -> dict[str, Any]:
+        """Validate webhook payload and signature."""
+        return self._webhook_verifier.verify(payload, signature)
+
+    async def get_health(self) -> dict[str, Any]:
+        """Get the health status of the API backend."""
+        return await self._http.get("/health")  # type: ignore[no-any-return]
+
+    async def __aenter__(self) -> AsyncKortanaClient:
+        await self._http.__aenter__()
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self._http.__aexit__(*args)

kortana_dev_sdk-1.0.0/kortana/config.py

@@ -0,0 +1,75 @@
+"""
+Kortana SDK configuration using Pydantic settings.
+"""
+from __future__ import annotations
+
+from typing import Optional
+from pydantic import field_validator, model_validator
+from pydantic_settings import BaseSettings
+
+BASE_URLS: dict[str, str] = {
+    "mainnet": "https://api.oneworld.kortana.network/api/v1",
+    "testnet": "https://api.oneworld.kortana.network/api/v1",
+}
+
+
+class KortanaConfig(BaseSettings):
+    """
+    Kortana SDK configuration.
+
+    All fields can be overridden via environment variables prefixed with KORTANA_.
+    Example: KORTANA_API_KEY, KORTANA_ENVIRONMENT, KORTANA_TIMEOUT
+    """
+
+    api_key: str
+    environment: str = "mainnet"
+    base_url: Optional[str] = None
+    timeout: float = 30.0
+    connect_timeout: float = 5.0
+    max_retries: int = 3
+    retry_delay: float = 1.0
+    max_retry_delay: float = 32.0
+    log_level: str = "info"
+    webhook_secret: Optional[str] = None
+    user_agent: Optional[str] = None
+    telemetry: bool = True
+
+    model_config = {"env_prefix": "KORTANA_", "populate_by_name": True}  # type: ignore[assignment]
+
+    @field_validator("environment")
+    @classmethod
+    def validate_environment(cls, v: str) -> str:
+        if v not in ("mainnet", "testnet"):
+            raise ValueError(f"environment must be 'mainnet' or 'testnet', got {v!r}")
+        return v
+
+    @field_validator("api_key")
+    @classmethod
+    def validate_api_key(cls, v: str) -> str:
+        if not v or not v.strip():
+            raise ValueError("api_key must not be empty")
+        return v.strip()
+
+    @field_validator("timeout")
+    @classmethod
+    def validate_timeout(cls, v: float) -> float:
+        if v <= 0:
+            raise ValueError("timeout must be positive")
+        return v
+
+    @field_validator("max_retries")
+    @classmethod
+    def validate_max_retries(cls, v: int) -> int:
+        if v < 0:
+            raise ValueError("max_retries must be non-negative")
+        return v
+
+    def get_base_url(self) -> str:
+        """Return the resolved base URL."""
+        if self.base_url:
+            return self.base_url.rstrip("/")
+        return BASE_URLS[self.environment]
+
+    def get_user_agent(self) -> str:
+        """Return the User-Agent header value."""
+        return self.user_agent or "kortana-sdk-python/1.0.0"

kortana_dev_sdk-1.0.0/kortana/exceptions.py

@@ -0,0 +1,183 @@
+"""
+Kortana SDK exception hierarchy.
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class KortanaError(Exception):
+    """Base exception for all Kortana SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        code: str = "UNKNOWN_ERROR",
+        request_id: Optional[str] = None,
+        docs_url: Optional[str] = None,
+        details: Optional[dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.request_id = request_id
+        self.docs_url = docs_url
+        self.details = details or {}
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(code={self.code!r}, message={self.message!r})"
+
+
+class KortanaConfigError(KortanaError):
+    """Raised when the SDK is misconfigured."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(
+            message,
+            code="CONFIG_ERROR",
+            docs_url="https://docs.kortana.io/errors/CONFIG_ERROR",
+        )
+
+
+class KortanaAuthError(KortanaError):
+    """Raised on authentication failures (401)."""
+
+    def __init__(self, message: str, request_id: Optional[str] = None) -> None:
+        super().__init__(
+            message,
+            code="AUTH_ERROR",
+            request_id=request_id,
+            docs_url="https://docs.kortana.io/errors/AUTH_ERROR",
+        )
+
+
+class KortanaNetworkError(KortanaError):
+    """Raised on network-level failures (timeouts, connection errors)."""
+
+    def __init__(
+        self,
+        message: str,
+        cause: Optional[Exception] = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(
+            message,
+            code="NETWORK_ERROR",
+            request_id=request_id,
+            docs_url="https://docs.kortana.io/errors/NETWORK_ERROR",
+        )
+        self.cause = cause
+
+
+class KortanaRateLimitError(KortanaError):
+    """Raised when the API rate limit is exceeded (429)."""
+
+    def __init__(
+        self,
+        message: str,
+        retry_after: int = 60,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(
+            message,
+            code="RATE_LIMIT_ERROR",
+            request_id=request_id,
+            docs_url="https://docs.kortana.io/errors/RATE_LIMIT_ERROR",
+        )
+        self.retry_after = retry_after
+
+
+class KortanaValidationError(KortanaError):
+    """Raised when request validation fails (400)."""
+
+    def __init__(
+        self,
+        message: str,
+        fields: Optional[list[dict[str, str]]] = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(
+            message,
+            code="VALIDATION_ERROR",
+            request_id=request_id,
+            docs_url="https://docs.kortana.io/errors/VALIDATION_ERROR",
+        )
+        self.fields = fields or []
+
+
+class KortanaNotFoundError(KortanaError):
+    """Raised when a resource is not found (404)."""
+
+    def __init__(self, message: str, request_id: Optional[str] = None) -> None:
+        super().__init__(
+            message,
+            code="NOT_FOUND_ERROR",
+            request_id=request_id,
+            docs_url="https://docs.kortana.io/errors/NOT_FOUND_ERROR",
+        )
+
+
+class KortanaConflictError(KortanaError):
+    """Raised on resource conflicts (409)."""
+
+    def __init__(self, message: str, request_id: Optional[str] = None) -> None:
+        super().__init__(
+            message,
+            code="CONFLICT_ERROR",
+            request_id=request_id,
+            docs_url="https://docs.kortana.io/errors/CONFLICT_ERROR",
+        )
+
+
+class KortanaWebhookSignatureError(KortanaError):
+    """Raised when webhook signature verification fails."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(
+            message,
+            code="WEBHOOK_SIGNATURE_ERROR",
+            docs_url="https://docs.kortana.io/errors/WEBHOOK_SIGNATURE_ERROR",
+        )
+
+
+class KortanaServerError(KortanaError):
+    """Raised on server-side errors (5xx)."""
+
+    def __init__(self, message: str, request_id: Optional[str] = None) -> None:
+        super().__init__(
+            message,
+            code="SERVER_ERROR",
+            request_id=request_id,
+            docs_url="https://docs.kortana.io/errors/SERVER_ERROR",
+        )
+
+
+def raise_for_response(
+    status_code: int,
+    error_body: dict[str, Any],
+    headers: dict[str, str],
+) -> None:
+    """Map HTTP status codes and error bodies to specific KortanaError subclasses."""
+    error = error_body.get("error", {})
+    message = error.get("message", "An unknown error occurred")
+    request_id = error.get("request_id")
+    fields = error.get("fields")
+
+    if status_code == 400:
+        raise KortanaValidationError(message, fields=fields, request_id=request_id)
+    if status_code == 401:
+        raise KortanaAuthError(message, request_id=request_id)
+    if status_code == 404:
+        raise KortanaNotFoundError(message, request_id=request_id)
+    if status_code == 409:
+        raise KortanaConflictError(message, request_id=request_id)
+    if status_code == 429:
+        retry_after = int(headers.get("retry-after", "60"))
+        raise KortanaRateLimitError(message, retry_after=retry_after, request_id=request_id)
+    if status_code >= 500:
+        raise KortanaServerError(message, request_id=request_id)
+
+    code = error.get("code", "UNKNOWN_ERROR")
+    docs_url = error.get("docs_url")
+    details = error.get("details")
+    raise KortanaError(message, code=code, request_id=request_id, docs_url=docs_url, details=details)

kortana_dev_sdk-1.0.0/kortana/http/__init__.py

@@ -0,0 +1 @@
+"""HTTP sub-package for Kortana SDK."""