Metadata-Version: 2.4
Name: imbrace
Version: 1.2.1
Summary: Official Python SDK for Imbrace — dual auth (API Key + Access Token)
Project-URL: Homepage, https://imbrace.co
Project-URL: Repository, https://github.com/imbrace/sdk
Project-URL: Documentation, https://docs.imbrace.co/sdk/python
Author-email: Imbrace Team <dev@imbrace.co>
License: MIT
Keywords: api,automation,imbrace,sdk
Classifier: Intended Audience :: Developers
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 :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# Imbrace Python SDK

Official Python client for the Imbrace Gateway. Supports sync and async.

## Installation

```bash
pip install imbrace
```

## Quick Start

### API Key — server-side scripts, Celery tasks

```python
from imbrace import ImbraceClient

client = ImbraceClient(api_key="sk-xxx...")

me = client.platform.get_me()
```

### Access Token — after user login

```python
client = ImbraceClient(access_token="acc_xxxxxxxxxxxxx")
```

### OTP Login Flow

```python
client = ImbraceClient()

client.request_otp("user@example.com")
client.login_with_otp("user@example.com", "123456")

# all subsequent calls are authenticated
me = client.platform.get_me()
```

### Async Client

```python
from imbrace import AsyncImbraceClient

async with AsyncImbraceClient(api_key="sk-xxx...") as client:
    me = await client.platform.get_me()
```

## Error Handling

```python
from imbrace import AuthError, ApiError, NetworkError

try:
    client.platform.get_me()
except AuthError:
    print("Invalid credentials")
except ApiError as e:
    print(f"[{e.status_code}] {e}")
except NetworkError:
    print("Gateway unreachable")
```

## Environment Variables

| Variable | Description |
| --- | --- |
| `IMBRACE_API_KEY` | API key (server-side auth) |
| `IMBRACE_GATEWAY_URL` | Override gateway URL (default: `https://app-gatewayv2.imbrace.co`) |
| `IMBRACE_ENV` | Environment preset: `develop`, `sandbox`, `stable` (default: `stable`) |

## Development

```bash
pip install -e ".[dev]"
pytest                    # unit tests
pytest tests/integration  # integration tests (requires IMBRACE_API_KEY)
```

## Resources

Full resource reference: **[sdk.imbrace.co/python/resources](https://sdk.imbrace.co/python/resources)**
