stablesea 0.1.0__tar.gz

stablesea-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: stablesea
+Version: 0.1.0
+Summary: Python SDK for the Stable Sea Terminal API
+Author: Stable Sea
+License: MIT
+Project-URL: Homepage, https://stablesea.com
+Project-URL: Documentation, https://docs.stablesea.com
+Project-URL: Repository, https://github.com/stablesea/stablesea-python
+Keywords: stablesea,api,shipping,terminal
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+
+# Stable Sea Python SDK
+
+Official Python client for the [Stable Sea Terminal API](https://stablesea.com), for managing organizations, quotes, orders, and API keys.
+
+## Installation
+
+```bash
+pip install stablesea
+```
+
+Or install from source:
+
+```bash
+pip install /path/to/sdk/python
+```
+
+## Quickstart
+
+```python
+from stablesea import StableseaClient
+
+# Initialize with your API key (sandbox by default)
+client = StableseaClient(api_key="sk_your_api_key")
+
+# List organizations
+organizations = client.organizations.list()
+
+# Create an organization
+org = client.organizations.create(
+    name="Acme Corp",
+    contact={"email": "john@acme.com", "first_name": "John", "last_name": "Doe"},
+    idempotency_key="unique-key-123",
+)
+
+# Create a quote (organization-scoped)
+quote = client.quotes.create(
+    organization_id="org_01k2cm4r59e5z8k5ggrbbxjcwy",
+    offering_id="off_01k4qph5ezfsga7fkvbygsqq93",
+    payin_amount="100",
+    idempotency_key="quote-key-456",
+)
+
+# Create an order from the quote
+order = client.orders.create(
+    organization_id="org_01k2cm4r59e5z8k5ggrbbxjcwy",
+    quote_id=quote["id"],
+    idempotency_key="order-key-789",
+)
+
+# List API keys
+api_keys = client.api_keys.list()
+
+# Create a new API key
+new_key = client.api_keys.create(
+    name="Production API",
+    environment="PRODUCTION",
+    permission_level="STANDARD",
+)
+# Store new_key["api_key"] securely - it's only returned once!
+
+# List liquidity providers
+providers = client.liquidity_providers.list()
+
+# Get exchange rate for a provider
+rate = client.liquidity_providers.get_exchange_rate("ALPHA")
+
+client.close()
+```
+
+## Async Support
+
+For async/await support, use `AsyncStableseaClient`:
+
+```python
+import asyncio
+from stablesea import AsyncStableseaClient
+
+async def main():
+    async with AsyncStableseaClient(api_key="sk_your_api_key") as client:
+        orgs = await client.organizations.list()
+        quote = await client.quotes.create(
+            organization_id="org_...",
+            offering_id="off_...",
+            payin_amount="100",
+            idempotency_key="unique-key",
+        )
+        print(orgs, quote)
+
+asyncio.run(main())
+```
+
+## Configuration
+
+| Parameter   | Default                           | Description                    |
+|------------|------------------------------------|--------------------------------|
+| `api_key`  | (required)                         | Your Stable Sea API key        |
+| `base_url` | `https://api-sandbox.stablesea.com/v1` | API base URL (use production URL for live) |
+| `timeout`  | `30.0`                             | Request timeout in seconds     |
+
+## API Resources
+
+| Resource | Methods |
+|----------|---------|
+| `client.organizations` | `list()`, `create()`, `get()` |
+| `client.quotes` | `create()`, `get()` |
+| `client.orders` | `create()`, `list()`, `get()` |
+| `client.api_keys` | `list()`, `create()`, `rotate()`, `revoke()` |
+| `client.liquidity_providers` | `list()`, `get_exchange_rate()` |
+| `client.offerings` | `create()`, `get()` |
+| `client.external_payment_instruments` | `list()`, `create()`, `get()`, `archive()` |
+
+## Error Handling
+
+```python
+from stablesea import StableseaClient, APIError
+
+client = StableseaClient(api_key="sk_...")
+try:
+    client.organizations.create(...)
+except APIError as e:
+    print(f"API error {e.status_code}: {e.message}")
+```
+
+## License
+
+MIT

stablesea-0.1.0/README.md

@@ -0,0 +1,126 @@
+# Stable Sea Python SDK
+
+Official Python client for the [Stable Sea Terminal API](https://stablesea.com), for managing organizations, quotes, orders, and API keys.
+
+## Installation
+
+```bash
+pip install stablesea
+```
+
+Or install from source:
+
+```bash
+pip install /path/to/sdk/python
+```
+
+## Quickstart
+
+```python
+from stablesea import StableseaClient
+
+# Initialize with your API key (sandbox by default)
+client = StableseaClient(api_key="sk_your_api_key")
+
+# List organizations
+organizations = client.organizations.list()
+
+# Create an organization
+org = client.organizations.create(
+    name="Acme Corp",
+    contact={"email": "john@acme.com", "first_name": "John", "last_name": "Doe"},
+    idempotency_key="unique-key-123",
+)
+
+# Create a quote (organization-scoped)
+quote = client.quotes.create(
+    organization_id="org_01k2cm4r59e5z8k5ggrbbxjcwy",
+    offering_id="off_01k4qph5ezfsga7fkvbygsqq93",
+    payin_amount="100",
+    idempotency_key="quote-key-456",
+)
+
+# Create an order from the quote
+order = client.orders.create(
+    organization_id="org_01k2cm4r59e5z8k5ggrbbxjcwy",
+    quote_id=quote["id"],
+    idempotency_key="order-key-789",
+)
+
+# List API keys
+api_keys = client.api_keys.list()
+
+# Create a new API key
+new_key = client.api_keys.create(
+    name="Production API",
+    environment="PRODUCTION",
+    permission_level="STANDARD",
+)
+# Store new_key["api_key"] securely - it's only returned once!
+
+# List liquidity providers
+providers = client.liquidity_providers.list()
+
+# Get exchange rate for a provider
+rate = client.liquidity_providers.get_exchange_rate("ALPHA")
+
+client.close()
+```
+
+## Async Support
+
+For async/await support, use `AsyncStableseaClient`:
+
+```python
+import asyncio
+from stablesea import AsyncStableseaClient
+
+async def main():
+    async with AsyncStableseaClient(api_key="sk_your_api_key") as client:
+        orgs = await client.organizations.list()
+        quote = await client.quotes.create(
+            organization_id="org_...",
+            offering_id="off_...",
+            payin_amount="100",
+            idempotency_key="unique-key",
+        )
+        print(orgs, quote)
+
+asyncio.run(main())
+```
+
+## Configuration
+
+| Parameter   | Default                           | Description                    |
+|------------|------------------------------------|--------------------------------|
+| `api_key`  | (required)                         | Your Stable Sea API key        |
+| `base_url` | `https://api-sandbox.stablesea.com/v1` | API base URL (use production URL for live) |
+| `timeout`  | `30.0`                             | Request timeout in seconds     |
+
+## API Resources
+
+| Resource | Methods |
+|----------|---------|
+| `client.organizations` | `list()`, `create()`, `get()` |
+| `client.quotes` | `create()`, `get()` |
+| `client.orders` | `create()`, `list()`, `get()` |
+| `client.api_keys` | `list()`, `create()`, `rotate()`, `revoke()` |
+| `client.liquidity_providers` | `list()`, `get_exchange_rate()` |
+| `client.offerings` | `create()`, `get()` |
+| `client.external_payment_instruments` | `list()`, `create()`, `get()`, `archive()` |
+
+## Error Handling
+
+```python
+from stablesea import StableseaClient, APIError
+
+client = StableseaClient(api_key="sk_...")
+try:
+    client.organizations.create(...)
+except APIError as e:
+    print(f"API error {e.status_code}: {e.message}")
+```
+
+## License
+
+MIT

stablesea-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stablesea"
+version = "0.1.0"
+description = "Python SDK for the Stable Sea Terminal API"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.8"
+authors = [
+    { name = "Stable Sea" }
+]
+keywords = ["stablesea", "api", "shipping", "terminal"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "httpx>=0.24.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+]
+
+[project.urls]
+Homepage = "https://stablesea.com"
+Documentation = "https://docs.stablesea.com"
+Repository = "https://github.com/stablesea/stablesea-python"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["stablesea*"]

stablesea-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stablesea-0.1.0/stablesea/__init__.py

@@ -0,0 +1,14 @@
+"""Stable Sea Python SDK."""
+
+from stablesea.async_client import AsyncStableseaClient
+from stablesea.client import StableseaClient
+from stablesea.errors import APIError, StableseaError
+
+__all__ = [
+    "StableseaClient",
+    "AsyncStableseaClient",
+    "StableseaError",
+    "APIError",
+]
+
+__version__ = "0.1.0"

stablesea-0.1.0/stablesea/_http.py

@@ -0,0 +1,155 @@
+"""HTTP client with Bearer auth."""
+
+from typing import Any, Dict, Optional
+
+import httpx
+
+
+class HTTPClient:
+    """Low-level HTTP client with Bearer token authentication."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api-sandbox.stablesea.com/v1",
+        timeout: float = 30.0,
+        http_client: Optional[httpx.Client] = None,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+        self._client = http_client or httpx.Client(
+            base_url=self.base_url,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            },
+            timeout=timeout,
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> Dict[str, Any]:
+        """Make an HTTP request and return parsed JSON."""
+        merged_headers = dict(headers or {})
+        resp = self._client.request(
+            method,
+            path,
+            json=json,
+            params=params,
+            headers=merged_headers or None,
+        )
+        return self._handle_response(resp)
+
+    def _handle_response(self, resp: httpx.Response) -> Dict[str, Any]:
+        from stablesea.errors import APIError
+
+        if resp.status_code >= 400:
+            try:
+                body = resp.json()
+                msg = body.get("message", resp.text or f"HTTP {resp.status_code}")
+                err_code = body.get("error")
+            except Exception:
+                msg = resp.text or f"HTTP {resp.status_code}"
+                err_code = None
+            raise APIError(
+                message=msg,
+                error_code=err_code,
+                status_code=resp.status_code,
+                response=resp,
+            )
+        if resp.status_code in (200, 201) and resp.content:
+            return resp.json()
+        return {}
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> "HTTPClient":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+
+class AsyncHTTPClient:
+    """Async HTTP client with Bearer token authentication."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api-sandbox.stablesea.com/v1",
+        timeout: float = 30.0,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+        self._client = http_client or httpx.AsyncClient(
+            base_url=self.base_url,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            },
+            timeout=timeout,
+        )
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> Dict[str, Any]:
+        """Make an HTTP request and return parsed JSON."""
+        merged_headers = dict(headers or {})
+        resp = await self._client.request(
+            method,
+            path,
+            json=json,
+            params=params,
+            headers=merged_headers or None,
+        )
+        return self._handle_response(resp)
+
+    def _handle_response(self, resp: httpx.Response) -> Dict[str, Any]:
+        from stablesea.errors import APIError
+
+        if resp.status_code >= 400:
+            try:
+                body = resp.json()
+                msg = body.get("message", resp.text or f"HTTP {resp.status_code}")
+                err_code = body.get("error")
+            except Exception:
+                msg = resp.text or f"HTTP {resp.status_code}"
+                err_code = None
+            raise APIError(
+                message=msg,
+                error_code=err_code,
+                status_code=resp.status_code,
+                response=resp,
+            )
+        if resp.status_code in (200, 201) and resp.content:
+            return resp.json()
+        return {}
+
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncHTTPClient":
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()

stablesea-0.1.0/stablesea/async_client.py

@@ -0,0 +1,80 @@
+"""Async Stable Sea API client."""
+
+from stablesea._http import AsyncHTTPClient
+from stablesea.resources.async_resources import (
+    AsyncApiKeysResource,
+    AsyncExternalPaymentInstrumentsResource,
+    AsyncLiquidityProvidersResource,
+    AsyncOfferingsResource,
+    AsyncOrganizationsResource,
+    AsyncOrdersResource,
+    AsyncQuotesResource,
+)
+
+
+class AsyncStableseaClient:
+    """Async Python client for the Stable Sea Terminal API.
+
+    Uses Bearer token authentication. Supports async/await for non-blocking requests.
+
+    Example:
+        >>> async with AsyncStableseaClient(api_key="sk_...") as client:
+        ...     orgs = await client.organizations.list()
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api-sandbox.stablesea.com/v1",
+        timeout: float = 30.0,
+    ):
+        """Initialize the async client.
+
+        Args:
+            api_key: Your Stable Sea API key (Bearer token)
+            base_url: API base URL (default: sandbox)
+            timeout: Request timeout in seconds
+        """
+        self._http = AsyncHTTPClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+        )
+
+    @property
+    def organizations(self) -> AsyncOrganizationsResource:
+        return AsyncOrganizationsResource(self._http)
+
+    @property
+    def quotes(self) -> AsyncQuotesResource:
+        return AsyncQuotesResource(self._http)
+
+    @property
+    def orders(self) -> AsyncOrdersResource:
+        return AsyncOrdersResource(self._http)
+
+    @property
+    def api_keys(self) -> AsyncApiKeysResource:
+        return AsyncApiKeysResource(self._http)
+
+    @property
+    def liquidity_providers(self) -> AsyncLiquidityProvidersResource:
+        return AsyncLiquidityProvidersResource(self._http)
+
+    @property
+    def offerings(self) -> AsyncOfferingsResource:
+        return AsyncOfferingsResource(self._http)
+
+    @property
+    def external_payment_instruments(self) -> AsyncExternalPaymentInstrumentsResource:
+        return AsyncExternalPaymentInstrumentsResource(self._http)
+
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        await self._http.close()
+
+    async def __aenter__(self) -> "AsyncStableseaClient":
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()

stablesea-0.1.0/stablesea/client.py

@@ -0,0 +1,96 @@
+"""Stable Sea API client."""
+
+from typing import Optional
+
+from stablesea._http import HTTPClient
+from stablesea.resources import (
+    ApiKeysResource,
+    ExternalPaymentInstrumentsResource,
+    LiquidityProvidersResource,
+    OfferingsResource,
+    OrganizationsResource,
+    OrdersResource,
+    QuotesResource,
+)
+
+
+class StableseaClient:
+    """Python client for the Stable Sea Terminal API.
+
+    Uses Bearer token authentication. All requests include the API key
+    in the Authorization header.
+
+    Example:
+        >>> client = StableseaClient(api_key="sk_...")
+        >>> orgs = client.organizations.list()
+        >>> quote = client.quotes.create(
+        ...     organization_id="org_...",
+        ...     offering_id="off_...",
+        ...     payin_amount="100",
+        ...     idempotency_key="unique-key-123"
+        ... )
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api-sandbox.stablesea.com/v1",
+        timeout: float = 30.0,
+    ):
+        """Initialize the client.
+
+        Args:
+            api_key: Your Stable Sea API key (Bearer token)
+            base_url: API base URL (default: sandbox)
+            timeout: Request timeout in seconds
+        """
+        self._http = HTTPClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+        )
+
+    @property
+    def organizations(self) -> OrganizationsResource:
+        """Organizations: list, create, get."""
+        return OrganizationsResource(self._http)
+
+    @property
+    def quotes(self) -> QuotesResource:
+        """Quotes: create, get (organization-scoped)."""
+        return QuotesResource(self._http)
+
+    @property
+    def orders(self) -> OrdersResource:
+        """Orders: create, list, get (organization-scoped)."""
+        return OrdersResource(self._http)
+
+    @property
+    def api_keys(self) -> ApiKeysResource:
+        """API Keys: list, create, rotate, revoke."""
+        return ApiKeysResource(self._http)
+
+    @property
+    def liquidity_providers(self) -> LiquidityProvidersResource:
+        """Liquidity providers: list, get exchange rate."""
+        return LiquidityProvidersResource(self._http)
+
+    @property
+    def offerings(self) -> OfferingsResource:
+        """Offerings: create, get (organization-scoped)."""
+        return OfferingsResource(self._http)
+
+    @property
+    def external_payment_instruments(self) -> ExternalPaymentInstrumentsResource:
+        """External payment instruments (organization-scoped)."""
+        return ExternalPaymentInstrumentsResource(self._http)
+
+    def close(self) -> None:
+        """Close the HTTP client and release resources."""
+        self._http.close()
+
+    def __enter__(self) -> "StableseaClient":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()