lumen-core-client 0.1.0
Python client for Lumen Core API
License: MIT
Requires Python: >=3.8

# File: README.md
# Lumen Core Python Client

A Python client library for interacting with the Lumen Core API, providing a clean and intuitive interface for managing user connections and OAuth integrations.

## Installation

```bash
pip install lumen-core-client
```

## Quick Start

```python
import asyncio
from lumen_core import LumenClient

async def main():
    # Initialize the client
    client = LumenClient(
        base_url="https://053181c1c4d3.ngrok-free.app/api",
        api_key="your-api-key"
    )
    
    # Create a user and connection using fluent API
    result = await client.get_entity("user123").get_connection(app="gmail").create_for_app(
        client_id="your-google-client-id",
        client_secret="your-google-client-secret"
    )
    
    print(f"Connection created: {result['connection_id']}")
    
    await client.close()

# Run the example
asyncio.run(main())
```

## Usage Examples

### Basic Usage

```python
from lumen_core import LumenClient

# Initialize client
client = LumenClient(base_url="https://your-api-url.com/api")
client.set_api_key("your-api-key")

# Create a user
user_response = await client.create_user("user123")

# Get available services for a provider
services = await client.get_available_services("google")
print(services)
```

### Fluent API Usage

The client provides a fluent API for more intuitive usage:

```python
# Create a Gmail connection
result = await client.get_entity("user123").get_connection(app="gmail").create_for_app(
    client_id="google-client-id",
    client_secret="google-client-secret"
)

# Create a multi-provider connection
result = await client.get_entity("user123").get_connection().create({
    "google": {
        "client_id": "google-client-id", 
        "client_secret": "google-client-secret",
        "services": ["gmail", "calendar"]
    },
    "microsoft": {
        "client_id": "microsoft-client-id",
        "client_secret": "microsoft-client-secret", 
        "services": ["outlook", "calendar"]
    }
})
```

### Context Manager Usage

```python
async with LumenClient(base_url="https://your-api.com/api", api_key="key") as client:
    result = await client.get_entity("user123").get_connection(app="gmail").create_for_app(
        client_id="client-id",
        client_secret="client-secret"
    )
    print(result)
```

## API Reference

### LumenClient

Main client class for interacting with the Lumen Core API.

#### Methods

- `get_entity(user_id: str) -> UserEntity`: Get a user entity for fluent operations
- `create_user(user_id: str) -> Dict`: Create or get a user
- `get_available_services(provider: str) -> Dict`: Get available services for a provider
- `create_connection(connection_data: ConnectionCreate) -> Dict`: Create a new connection
- `set_api_key(api_key: str)`: Set the API key for authentication
- `close()`: Close the HTTP client

### UserEntity

Fluent interface for user operations.

#### Methods

- `create() -> Dict`: Create the user
- `get_connection(app: Optional[str] = None) -> ConnectionEntity`: Get connection entity

### ConnectionEntity

Fluent interface for connection operations.

#### Methods

- `create(providers: Dict) -> Dict`: Create connection with multiple providers
- `create_for_app(client_id: str, client_secret: str, services: List[str] = None) -> Dict`: Create connection for specific app

## Supported Apps

The client supports automatic provider mapping for common applications:

- `gmail` → Google provider
- `google` → Google provider  
- `outlook` → Microsoft provider
- `microsoft` → Microsoft provider
- `office365` → Microsoft provider

## Error Handling

The client provides specific exception types:

```python
from lumen_core.exceptions import (
    LumenError,
    AuthenticationError, 
    NotFoundError,
    ValidationError,
    ConnectionError
)

try:
    result = await client.create_connection(connection_data)
except AuthenticationError:
    print("Invalid API key")
except ValidationError as e:
    print(f"Validation error: {e}")
except LumenError as e:
    print(f"General error: {e}")
```

## Development

### Setup

```bash
git clone https://github.com/your-username/lumen-core-client
cd lumen-core-client
pip install -e ".[dev]"
```

### Running Tests

```bash
pytest
```

### Code Formatting

```bash
black lumen_core/
flake8 lumen_core/
mypy lumen_core/
```

## License

MIT License

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request