# Sigfox Manager

A Python library for handling Sigfox API operations with ease.

## Features

Currently supports the following operations:
- Get all contracts on current Token
- Get all devices on selected contract  
- Get device information
- Get messages from device
- Create device
- List device types with automatic pagination
- Resolve device types by id or name
- Provision devices with input validation

## Installation

### From PyPI (when published)
```bash
pip install sigfox-manager
```

### From Source
```bash
git clone https://github.com/Jobenas/sigfox_manager_utility.git
cd sigfox_manager_utility
pip install .
```

### For Development
```bash
git clone https://github.com/Jobenas/sigfox_manager_utility.git
cd sigfox_manager_utility
pip install -e .[dev]
```

## Quick Start

```python
from sigfox_manager import SigfoxManager

# Initialize the manager with your Sigfox API credentials
manager = SigfoxManager(user="your_username", pwd="your_password")

# Get all contracts
contracts = manager.get_contracts()
print(f"Found {len(contracts.data)} contracts")

# Get devices for a contract
if contracts.data:
    contract_id = contracts.data[0].id
    devices = manager.get_devices_by_contract(contract_id)
    print(f"Found {len(devices.data)} devices")

# Get device information
if devices.data:
    device_id = devices.data[0].id
    device_info = manager.get_device_info(device_id)
    print(f"Device: {device_info.name}")
    
    # Get device messages
    messages = manager.get_device_messages(device_id)
    print(f"Found {len(messages.data)} messages")
    
    # Paginate through all messages
    all_messages = []
    response = manager.get_device_messages(device_id)
    all_messages.extend(response.data)
    
    while response.paging.next is not None:
        response = manager.get_device_messages(device_id, paging=response.paging)
        all_messages.extend(response.data)
    
    print(f"Total messages retrieved: {len(all_messages)}")
```

### Device Type Management and Provisioning

```python
from sigfox_manager import SigfoxManager

sm = SigfoxManager("API_LOGIN", "API_PASSWORD")

# List all device types with automatic pagination
dts = sm.get_device_types().data
print([(dt.id, dt.name) for dt in dts])

# Provision a device with input validation
# Device type can be specified by id or name
dev = sm.provision_device(
    dev_id="19C3B",
    pac="1234567890ABCDEF",
    dev_type_ref="Type A",  # Can use device type name or id
    name="field-node-42",
    automatic_renewal=True,
)
print(f"Created device: {dev.id} - {dev.name}")
```

## Device Type Management and Provisioning

The library now includes enhanced features for managing device types and provisioning devices with validation:

```python
from sigfox_manager import SigfoxManager

# Initialize the manager
sm = SigfoxManager("API_LOGIN", "API_PASSWORD")

# List all device types
dts = sm.get_device_types().data
print([(dt.id, dt.name) for dt in dts])

# Provision a new device with validation
# - Validates dev_id format (uppercase hex, 3-16 chars)
# - Validates pac format (16 alphanumeric chars)
# - Resolves device type by id or name
dev = sm.provision_device(
    dev_id="19C3B",
    pac="1234567890ABCDEF",
    dev_type_ref="Type A",  # Can be device type id or name
    name="field-node-42",
    automatic_renewal=True,
)
print(dev.id, dev.name)
```

## API Reference

### SigfoxManager

The main class for interacting with the Sigfox API.

#### Constructor
```python
SigfoxManager(user: str, pwd: str)
```

#### Methods

- `get_contracts(fetch_all_pages: bool = True) -> ContractsResponse`: Get all contracts visible to the user
- `get_devices_by_contract(contract_id: str, fetch_all_pages: bool = True) -> DevicesResponse`: Get all devices for a contract
- `get_device_info(device_id: str) -> Device`: Get detailed information about a specific device
- `get_device_messages(device_id: str, threshold: Optional[int] = None, paging: Optional[Paging] = None) -> DeviceMessagesResponse`: Get messages from a device with optional pagination support
- `get_device_message_number(device_id: str) -> DeviceMessageStats`: Get message metrics for a device
- `create_device(dev_id, pac, dev_type_id, name, ...) -> BaseDevice`: Create a new device
- `get_device_types(fetch_all_pages: bool = True) -> DeviceTypesResponse`: Get all device types with pagination support
- `resolve_device_type_id(ref: str) -> str`: Resolve a device type reference (id or name) to its id
- `provision_device(dev_id: str, pac: str, dev_type_ref: str, name: Optional[str] = None, **kwargs) -> BaseDevice`: Validate inputs and provision a new device

### Exceptions

The library provides custom exceptions for better error handling:

- `SigfoxAPIException`: Base exception for API errors
- `SigfoxDeviceNotFoundError`: Raised when a device is not found
- `SigfoxAuthError`: Raised for authentication errors
- `SigfoxDeviceCreateConflictException`: Raised when trying to create a duplicate device
- `SigfoxDeviceTypeNotFoundException`: Raised when a device type cannot be resolved by id or name

## Development

### Setting up Development Environment

```bash
# Clone the repository
git clone https://github.com/Jobenas/sigfox_manager_utility.git
cd sigfox_manager_utility

# Install in development mode with dev dependencies
pip install -e .[dev]
```

### Running Tests

```bash
pytest tests/
```

### Code Formatting

```bash
black sigfox_manager/
```

### Type Checking

```bash
mypy sigfox_manager/
```

### Building the Package

```bash
python -m build
```

## License

MIT License - see LICENSE file for details.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for your changes
5. Run the test suite
6. Submit a pull request

## Support

For issues and questions, please use the [GitHub Issues](https://github.com/Jobenas/sigfox_manager_utility/issues) page.

