trinity-connect-client 0.2.0__tar.gz

trinity_connect_client-0.2.0/PKG-INFO

@@ -0,0 +1,264 @@
+Metadata-Version: 2.3
+Name: trinity-connect-client
+Version: 0.2.0
+Summary: Official Python library for Trinity IoT Connect API interactions
+Author: Jan Badenhorst, Andries Niemandt
+Author-email: Jan Badenhorst <jan.badenhorst@trintel.co.za>, Andries Niemandt <andries.niemandt@trintel.co.za>
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Dist: requests>=2.32.4
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/trinity-telecomms/connect-py-client
+Project-URL: Issues, https://github.com/trinity-telecomms/connect-py-client/issues
+Description-Content-Type: text/markdown
+
+# Connect Client for Python
+
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Official Python library for interacting with the Trinity IoT Connect API. 
+This library provides a clean interface for accessing the Connect API endpoints 
+with comprehensive error handling, type hints, and good test coverage.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Error Handling](#error-handling)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Installation
+
+### Using uv (recommended)
+
+```bash
+uv add trinity-connect-client
+```
+
+### Using pip
+
+```bash
+pip install trinity-connect-client
+```
+
+### From source
+
+```bash
+uv add git+https://github.com/trinity-telecomms/connect-py-client@v0.2.0
+```
+
+## Quick Start
+
+```python
+from trinity_connect_client import ConnectClient
+from trinity_connect_client.exceptions import ResourceNotFoundError, UnauthorisedError
+
+# Initialize the client
+client = ConnectClient(
+  api_version="v4",
+  base_url="https://capi.trintel.co.za",
+  token="your-service-account-token"
+)
+
+# Get a device by ID (returns dict)
+try:
+    device = client.devices.get(device_id=123)
+    print(f"Device name: {device['name']}")
+except ResourceNotFoundError:
+    print("Device not found")
+except UnauthorisedError:
+    print("Access denied")
+```
+
+## Using Response Models
+
+The library provides type-safe dataclass models for API responses:
+
+```python
+from trinity_connect_client import ConnectClient, Device, Company, Folder
+
+client = ConnectClient(
+    api_version="v4",
+    base_url="https://capi.trintel.co.za",
+    token="your-service-account-token"
+)
+
+# Get device as dict, then convert to model for type safety
+device_dict = client.devices.get(device_id=123)
+device = Device.from_dict(device_dict)
+
+# Now you have full type hints and IDE autocomplete
+print(f"Device: {device.name}")
+print(f"UID: {device.uid}")
+print(f"Status: {device.status}")
+
+# Works with all response types
+company_dict = client.orgs.get(company_id=1)
+company = Company.from_dict(company_dict)
+
+folders_list = client.orgs.get_folders(company_id=1)
+folders = [Folder.from_dict(f) for f in folders_list]
+```
+
+**Available Models:**
+- `Device` - Device information
+- `Company` - Company/organization information
+- `Folder` - Folder information
+- `DeviceData` - Device telemetry data
+- `DeviceEvent` - Device events
+- `DeviceCommand` - Device commands
+
+## Configuration
+
+### Environment Variables
+
+You can set your service account token via environment variables:
+
+```bash
+export CONNECT_API_TOKEN="your-service-account-token"
+export CONNECT_API_BASE_URL="https://capi.trintel.co.za"
+```
+
+```python
+import os
+from trinity_connect_client import ConnectClient
+
+client = ConnectClient(
+    api_version="v4",
+    base_url=os.getenv("CONNECT_API_BASE_URL"),
+    token=os.getenv("CONNECT_API_TOKEN")
+)
+```
+
+## Migration from v0.1.x to v0.2.0
+
+Version 0.2.0 introduces breaking changes to authentication:
+
+### What Changed
+- Credentials-based authentication (email/password) has been removed
+- Service account token authentication is now required
+- Token caching logic has been removed (tokens are long-lived)
+- The `auth` module and login endpoint are no longer available
+
+### Upgrading
+
+**Before (v0.1.x):**
+```python
+client = ConnectClient(
+    base_url="https://capi.trintel.co.za",
+    credentials={
+        "email": "user@example.com",
+        "password": "password"
+    },
+    cache=cache_instance  # Optional
+)
+```
+
+**After (v0.2.0):**
+```python
+client = ConnectClient(
+    base_url="https://capi.trintel.co.za",
+    token="your-service-account-token"
+)
+```
+
+**How to get a service account token:**
+Contact your Trinity IoT administrator to generate a service account token for your application.
+
+## Error Handling
+
+The library raises specific exceptions for different error conditions:
+
+```python
+from trinity_connect_client.exceptions import (
+    ResourceNotFoundError,
+    UnauthorisedError,
+    ConnectAPIError
+)
+
+try:
+    device = client.devices.get(device_id=123)
+except ResourceNotFoundError:
+    print("Device not found (404)")
+except UnauthorisedError:
+    print("Authentication failed (401)")
+except PermissionError:
+    print("Access forbidden (403)")
+except ConnectAPIError as e:
+    print(f"API error: {e}")
+except ValueError as e:
+    print(f"Invalid input: {e}")
+```
+
+## Development
+
+### Setting up Development Environment
+
+```bash
+# Clone the repository
+git clone https://github.com/trinity-telecomms/connect-py-client.git
+cd connect-py-client
+
+# Install dependencies with uv
+uv sync
+
+# Run tests
+uv run pytest
+
+# Run linting
+uv run ruff check .
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run with coverage
+uv run pytest --cov=connect_client
+
+# Run specific test file
+uv run pytest tests/modules/devices/test_devices_api.py
+```
+
+### Building the Package
+
+This project uses the `uv_build` backend for building distributions:
+
+```bash
+# Build both wheel and source distribution
+uv build
+
+# Build only wheel
+uv build --wheel
+
+# Build only source distribution
+uv build --sdist
+
+# Build to a specific directory
+uv build --out-dir dist/
+```
+
+The built distributions will be available in the `dist/` directory.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Add tests for new functionality
+5. Run the test suite (`uv run pytest`)
+6. Commit your changes (`git commit -m 'Add amazing feature'`)
+7. Push to the branch (`git push origin feature/amazing-feature`)
+8. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT Licence - 
+see the [LICENCE](LICENSE) file for details.

trinity_connect_client-0.2.0/README.md

@@ -0,0 +1,249 @@
+# Connect Client for Python
+
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Official Python library for interacting with the Trinity IoT Connect API. 
+This library provides a clean interface for accessing the Connect API endpoints 
+with comprehensive error handling, type hints, and good test coverage.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Error Handling](#error-handling)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Installation
+
+### Using uv (recommended)
+
+```bash
+uv add trinity-connect-client
+```
+
+### Using pip
+
+```bash
+pip install trinity-connect-client
+```
+
+### From source
+
+```bash
+uv add git+https://github.com/trinity-telecomms/connect-py-client@v0.2.0
+```
+
+## Quick Start
+
+```python
+from trinity_connect_client import ConnectClient
+from trinity_connect_client.exceptions import ResourceNotFoundError, UnauthorisedError
+
+# Initialize the client
+client = ConnectClient(
+  api_version="v4",
+  base_url="https://capi.trintel.co.za",
+  token="your-service-account-token"
+)
+
+# Get a device by ID (returns dict)
+try:
+    device = client.devices.get(device_id=123)
+    print(f"Device name: {device['name']}")
+except ResourceNotFoundError:
+    print("Device not found")
+except UnauthorisedError:
+    print("Access denied")
+```
+
+## Using Response Models
+
+The library provides type-safe dataclass models for API responses:
+
+```python
+from trinity_connect_client import ConnectClient, Device, Company, Folder
+
+client = ConnectClient(
+    api_version="v4",
+    base_url="https://capi.trintel.co.za",
+    token="your-service-account-token"
+)
+
+# Get device as dict, then convert to model for type safety
+device_dict = client.devices.get(device_id=123)
+device = Device.from_dict(device_dict)
+
+# Now you have full type hints and IDE autocomplete
+print(f"Device: {device.name}")
+print(f"UID: {device.uid}")
+print(f"Status: {device.status}")
+
+# Works with all response types
+company_dict = client.orgs.get(company_id=1)
+company = Company.from_dict(company_dict)
+
+folders_list = client.orgs.get_folders(company_id=1)
+folders = [Folder.from_dict(f) for f in folders_list]
+```
+
+**Available Models:**
+- `Device` - Device information
+- `Company` - Company/organization information
+- `Folder` - Folder information
+- `DeviceData` - Device telemetry data
+- `DeviceEvent` - Device events
+- `DeviceCommand` - Device commands
+
+## Configuration
+
+### Environment Variables
+
+You can set your service account token via environment variables:
+
+```bash
+export CONNECT_API_TOKEN="your-service-account-token"
+export CONNECT_API_BASE_URL="https://capi.trintel.co.za"
+```
+
+```python
+import os
+from trinity_connect_client import ConnectClient
+
+client = ConnectClient(
+    api_version="v4",
+    base_url=os.getenv("CONNECT_API_BASE_URL"),
+    token=os.getenv("CONNECT_API_TOKEN")
+)
+```
+
+## Migration from v0.1.x to v0.2.0
+
+Version 0.2.0 introduces breaking changes to authentication:
+
+### What Changed
+- Credentials-based authentication (email/password) has been removed
+- Service account token authentication is now required
+- Token caching logic has been removed (tokens are long-lived)
+- The `auth` module and login endpoint are no longer available
+
+### Upgrading
+
+**Before (v0.1.x):**
+```python
+client = ConnectClient(
+    base_url="https://capi.trintel.co.za",
+    credentials={
+        "email": "user@example.com",
+        "password": "password"
+    },
+    cache=cache_instance  # Optional
+)
+```
+
+**After (v0.2.0):**
+```python
+client = ConnectClient(
+    base_url="https://capi.trintel.co.za",
+    token="your-service-account-token"
+)
+```
+
+**How to get a service account token:**
+Contact your Trinity IoT administrator to generate a service account token for your application.
+
+## Error Handling
+
+The library raises specific exceptions for different error conditions:
+
+```python
+from trinity_connect_client.exceptions import (
+    ResourceNotFoundError,
+    UnauthorisedError,
+    ConnectAPIError
+)
+
+try:
+    device = client.devices.get(device_id=123)
+except ResourceNotFoundError:
+    print("Device not found (404)")
+except UnauthorisedError:
+    print("Authentication failed (401)")
+except PermissionError:
+    print("Access forbidden (403)")
+except ConnectAPIError as e:
+    print(f"API error: {e}")
+except ValueError as e:
+    print(f"Invalid input: {e}")
+```
+
+## Development
+
+### Setting up Development Environment
+
+```bash
+# Clone the repository
+git clone https://github.com/trinity-telecomms/connect-py-client.git
+cd connect-py-client
+
+# Install dependencies with uv
+uv sync
+
+# Run tests
+uv run pytest
+
+# Run linting
+uv run ruff check .
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run with coverage
+uv run pytest --cov=connect_client
+
+# Run specific test file
+uv run pytest tests/modules/devices/test_devices_api.py
+```
+
+### Building the Package
+
+This project uses the `uv_build` backend for building distributions:
+
+```bash
+# Build both wheel and source distribution
+uv build
+
+# Build only wheel
+uv build --wheel
+
+# Build only source distribution
+uv build --sdist
+
+# Build to a specific directory
+uv build --out-dir dist/
+```
+
+The built distributions will be available in the `dist/` directory.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Add tests for new functionality
+5. Run the test suite (`uv run pytest`)
+6. Commit your changes (`git commit -m 'Add amazing feature'`)
+7. Push to the branch (`git push origin feature/amazing-feature`)
+8. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT Licence - 
+see the [LICENCE](LICENSE) file for details.

trinity_connect_client-0.2.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "trinity-connect-client"
+version = "0.2.0"
+description = "Official Python library for Trinity IoT Connect API interactions"
+readme = "README.md"
+authors = [
+    { name = "Jan Badenhorst", email = "jan.badenhorst@trintel.co.za" },
+    { name = "Andries Niemandt", email = "andries.niemandt@trintel.co.za" }
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "requests>=2.32.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/trinity-telecomms/connect-py-client"
+Issues = "https://github.com/trinity-telecomms/connect-py-client/issues"
+
+[build-system]
+requires = ["uv_build >= 0.7.19, <0.9.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+lint = [
+    "ruff>=0.12.3",
+]
+test = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+    "pytest-mock>=3.12.0",
+    "responses>=0.24.0",
+]
+
+[tool.coverage.run]
+data_file = ".coverage/.coverage"
+
+[tool.coverage.html]
+directory = ".coverage"

trinity_connect_client-0.2.0/src/trinity_connect_client/__init__.py

@@ -0,0 +1,13 @@
+from .main import ConnectClient
+from .models import Company, Device, DeviceCommand, DeviceData, DeviceEvent, Folder
+
+__all__ = [
+    "ConnectClient",
+    "Company",
+    "Device",
+    "DeviceCommand",
+    "DeviceData",
+    "DeviceEvent",
+    "Folder",
+]
+__version__ = "0.2.0"

trinity_connect_client-0.2.0/src/trinity_connect_client/decorators.py

@@ -0,0 +1,19 @@
+from trinity_connect_client.exceptions import UnauthorisedError, ResourceNotFoundError
+
+
+def handle_exceptions(func):
+    def wrapper(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+        except ValueError:
+            raise
+        except UnauthorisedError:
+            raise
+        except PermissionError:
+            raise
+        except ResourceNotFoundError:
+            raise
+        except Exception:
+            raise
+
+    return wrapper

trinity_connect_client-0.2.0/src/trinity_connect_client/exceptions/__init__.py

@@ -0,0 +1,13 @@
+class ResourceNotFoundError(Exception):
+    def __init__(self, message):
+        super().__init__(message)
+
+
+class ConnectAPIError(Exception):
+    def __init__(self, message):
+        super().__init__(message)
+
+
+class UnauthorisedError(Exception):
+    def __init__(self, message):
+        super().__init__(message)

trinity_connect_client-0.2.0/src/trinity_connect_client/main.py

@@ -0,0 +1,18 @@
+from .modules.devices import DevicesAPI
+from .modules.orgs import OrgsAPI
+
+
+class ConnectClient:
+    def __init__(self, **config):
+        self.api_version = config.get("api_version", "v4")
+        self.api_url = f"{config.get('base_url')}/api/{self.api_version}"
+
+        token = config.get("token")
+        if not token or not isinstance(token, str) or not token.strip():
+            raise ValueError("Token must be provided as a non-empty string")
+
+        self.token = token.strip()
+
+        # Resource Classes
+        self.devices = DevicesAPI(self)
+        self.orgs = OrgsAPI(self)

trinity_connect_client-0.2.0/src/trinity_connect_client/mixins/__init__.py

@@ -0,0 +1,87 @@
+import requests
+
+from trinity_connect_client.exceptions import (
+    ConnectAPIError,
+    ResourceNotFoundError,
+    UnauthorisedError,
+)
+
+
+class ResourceMixin:
+    def __init__(self, client):
+        self.client = client
+
+    def _url(self, path: str) -> str:
+        """
+        Build a full API URL from a path string.
+
+        :param path: The URL path (e.g., "devices/123" or "devices/uid/abc-123")
+        :return: Full URL including base API URL
+        """
+        # Remove leading slash if present for consistency
+        path = path.lstrip("/")
+        return f"{self.client.api_url}/{path}"
+
+    @staticmethod
+    def _get_default_headers():
+        """
+        Constructs the defaults headers required for Connect API requests. The
+        default headers do not include the Authorization header which is required
+        for most endpoints. Use _get_auth_headers() instead.
+        """
+        return {"Content-Type": "application/json", "Accept": "application/json"}
+
+    def _get_auth_headers(self):
+        default_headers = self._get_default_headers()
+        return {
+            **default_headers,
+            "Authorization": f"Bearer {self.client.token}",
+        }
+
+    def make_post_request(self, url, headers=None, json=None):
+        request_headers = self._get_auth_headers() if not headers else headers
+
+        try:
+            response = requests.post(url, headers=request_headers, json=json)
+            return response.status_code, response.json()
+        except Exception:
+            raise ConnectAPIError("Failed to make request to Connect API")
+
+    def make_patch_request(self, url, headers=None, json=None):
+        request_headers = self._get_auth_headers() if not headers else headers
+
+        try:
+            response = requests.patch(url, headers=request_headers, json=json)
+            return response.status_code, response.json()
+        except Exception:
+            raise ConnectAPIError("Failed to make request to Connect API")
+
+    def make_get_request(self, url, headers=None, params=None):
+        request_headers = self._get_auth_headers() if not headers else headers
+
+        try:
+            response = requests.get(url, headers=request_headers, params=params)
+        except Exception:
+            raise ConnectAPIError("Failed to make request to Connect API")
+
+        if response.status_code == 401:
+            raise UnauthorisedError("Authorisation failed")
+        if response.status_code == 403:
+            raise PermissionError("You are not authorised to access this resource")
+        if response.status_code == 404:
+            raise ResourceNotFoundError("Requested resource not found")
+        if response.status_code != 200:
+            raise ConnectAPIError("Connect API returned unexpected status code")
+
+        return response.json()
+
+    def get_linked_resource(self, url):
+        """
+        Helper method to get a linked resource from a previous interaction.
+        Some APIs return URLs in the response for related resources, previous or next
+        pages etc.
+
+        :param url:
+        :return:
+        """
+        return self.make_get_request(url)

trinity_connect_client-0.2.0/src/trinity_connect_client/models/__init__.py

@@ -0,0 +1,17 @@
+"""
+Response models for Connect API endpoints.
+
+These models provide type-safe representations of API responses.
+"""
+
+from .device import Device, DeviceCommand, DeviceData, DeviceEvent
+from .org import Company, Folder
+
+__all__ = [
+    "Company",
+    "Device",
+    "DeviceCommand",
+    "DeviceData",
+    "DeviceEvent",
+    "Folder",
+]

trinity_connect_client-0.2.0/src/trinity_connect_client/models/base.py

@@ -0,0 +1,19 @@
+"""
+Base classes for Connect API models.
+"""
+
+from typing import Any, Dict
+
+
+class BaseModel:
+    """Base class for all Connect API models."""
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "BaseModel":
+        """
+        Create a model instance from a dictionary.
+
+        :param data: Dictionary containing model data
+        :return: Model instance
+        """
+        raise NotImplementedError("Subclasses must implement from_dict")

trinity_connect_client-0.2.0/src/trinity_connect_client/models/device.py

@@ -0,0 +1,157 @@
+"""
+Device-related models for Connect API.
+"""
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+from .base import BaseModel
+
+
+@dataclass
+class Device(BaseModel):
+    """Represents a device from the Connect API."""
+
+    id: int
+    url: str
+    name: str
+    description: str
+    state: int
+    t_type: int
+    tpp_id: Optional[int]
+    company: int
+    folder: int
+    state_display: str
+    t_type_display: str
+    company_name: str
+    folder_name: str
+    company_url: str
+    folder_url: str
+    aux_values_url: str
+    uid: str
+    imei: str
+    imei2: str
+    serial_number: str
+    comm_interval_contract: int
+    comm_state: int
+    comm_state_display: str
+    youngest_comm_timestamp: str
+    command_model: int
+    data_lens: int
+    event_lens: Optional[int]
+    profile: Optional[int]
+    commands_url: str
+    latest_data_url: str
+    events_url: str
+    meta_url: str
+    geo_url: str
+    category_url: str
+    tags_url: str
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Device":
+        """
+        Create a Device instance from a dictionary.
+
+        :param data: Dictionary containing device data
+        :return: Device instance
+        """
+        return cls(
+            id=data["id"],
+            url=data["url"],
+            name=data["name"],
+            description=data["description"],
+            state=data["state"],
+            t_type=data["t_type"],
+            tpp_id=data.get("tpp_id"),
+            company=data["company"],
+            folder=data["folder"],
+            state_display=data["state_display"],
+            t_type_display=data["t_type_display"],
+            company_name=data["company_name"],
+            folder_name=data["folder_name"],
+            company_url=data["company_url"],
+            folder_url=data["folder_url"],
+            aux_values_url=data["aux_values_url"],
+            uid=data["uid"],
+            imei=data["imei"],
+            imei2=data["imei2"],
+            serial_number=data["serial_number"],
+            comm_interval_contract=data["comm_interval_contract"],
+            comm_state=data["comm_state"],
+            comm_state_display=data["comm_state_display"],
+            youngest_comm_timestamp=data["youngest_comm_timestamp"],
+            command_model=data["command_model"],
+            data_lens=data["data_lens"],
+            event_lens=data.get("event_lens"),
+            profile=data.get("profile"),
+            commands_url=data["commands_url"],
+            latest_data_url=data["latest_data_url"],
+            events_url=data["events_url"],
+            meta_url=data["meta_url"],
+            geo_url=data["geo_url"],
+            category_url=data["category_url"],
+            tags_url=data["tags_url"],
+        )
+
+
+@dataclass
+class DeviceData(BaseModel):
+    """Represents device data/telemetry from the Connect API."""
+
+    # Generic structure for device data - can be extended based on actual API response
+    data: Dict[str, Any]
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "DeviceData":
+        """
+        Create a DeviceData instance from a dictionary.
+
+        :param data: Dictionary containing device data
+        :return: DeviceData instance
+        """
+        return cls(data=data)
+
+
+@dataclass
+class DeviceEvent(BaseModel):
+    """Represents a device event from the Connect API."""
+
+    # Generic structure for device events - can be extended based on actual API response
+    events: list[Dict[str, Any]]
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "DeviceEvent":
+        """
+        Create a DeviceEvent instance from a dictionary.
+
+        :param data: Dictionary containing event data
+        :return: DeviceEvent instance
+        """
+        # If data is already a list, wrap it
+        if isinstance(data, list):
+            return cls(events=data)
+        # If data has an 'events' key, use that
+        return cls(events=data.get("events", []))
+
+
+@dataclass
+class DeviceCommand(BaseModel):
+    """Represents a device command from the Connect API."""
+
+    # Generic structure for device commands - can be extended based on actual API response
+    commands: list[Dict[str, Any]]
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "DeviceCommand":
+        """
+        Create a DeviceCommand instance from a dictionary.
+
+        :param data: Dictionary containing command data
+        :return: DeviceCommand instance
+        """
+        # If data is already a list, wrap it
+        if isinstance(data, list):
+            return cls(commands=data)
+        # If data has a 'commands' key, use that
+        return cls(commands=data.get("commands", []))

trinity_connect_client-0.2.0/src/trinity_connect_client/models/org.py

@@ -0,0 +1,94 @@
+"""
+Organisation-related models for Connect API.
+"""
+
+from dataclasses import dataclass
+from typing import Any, Dict
+
+from .base import BaseModel
+
+
+@dataclass
+class Company(BaseModel):
+    """Represents a company from the Connect API."""
+
+    id: int
+    url: str
+    name: str
+    state: int
+    state_display: str
+    is_ee: bool
+    url_profile: str
+    folder_url: str
+    url_folder_tree: str
+    url_sims: str
+    apn_urls: str
+    url_devices: str
+    url_budgets: str
+    url_access: str
+    url_tags: str
+    url_contracts: str
+    url_adaptations: str
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Company":
+        """
+        Create a Company instance from a dictionary.
+
+        :param data: Dictionary containing company data
+        :return: Company instance
+        """
+        return cls(
+            id=data["id"],
+            url=data["url"],
+            name=data["name"],
+            state=data["state"],
+            state_display=data["state_display"],
+            is_ee=data["is_ee"],
+            url_profile=data["url_profile"],
+            folder_url=data["folder_url"],
+            url_folder_tree=data["url_folder_tree"],
+            url_sims=data["url_sims"],
+            apn_urls=data["apn_urls"],
+            url_devices=data["url_devices"],
+            url_budgets=data["url_budgets"],
+            url_access=data["url_access"],
+            url_tags=data["url_tags"],
+            url_contracts=data["url_contracts"],
+            url_adaptations=data["url_adaptations"],
+        )
+
+
+@dataclass
+class Folder(BaseModel):
+    """Represents a folder from the Connect API."""
+
+    id: int
+    url: str
+    name: str
+    path: str
+    human_path: str
+    parent: int
+    url_sims: str
+    url_devices: str
+    tree_id: int
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Folder":
+        """
+        Create a Folder instance from a dictionary.
+
+        :param data: Dictionary containing folder data
+        :return: Folder instance
+        """
+        return cls(
+            id=data["id"],
+            url=data["url"],
+            name=data["name"],
+            path=data["path"],
+            human_path=data["human_path"],
+            parent=data["parent"],
+            url_sims=data["url_sims"],
+            url_devices=data["url_devices"],
+            tree_id=data["tree_id"],
+        )

trinity_connect_client-0.2.0/src/trinity_connect_client/modules/devices/__init__.py

@@ -0,0 +1,209 @@
+from typing import Dict, Any
+
+from trinity_connect_client.decorators import handle_exceptions
+from trinity_connect_client.mixins import ResourceMixin
+from trinity_connect_client.validators import validate_id, validate_uid, validate_command
+
+
+class DevicesAPI(ResourceMixin):
+    @handle_exceptions
+    def get(self, device_id: int) -> Dict[str, Any]:
+        """
+        GET a device by ID.
+
+        :param device_id: The ID of the device to retrieve
+        :return: A Device object as dictionary or error response
+        :raises ValueError: If device_id is not a positive integer
+        """
+        validate_id(device_id)
+        url = self._url(f"devices/{device_id}/")
+        return self.make_get_request(url)
+
+    @handle_exceptions
+    def get_by_uid(self, device_uid: str) -> Dict[str, Any]:
+        """
+        GET a device by UID.
+
+        :param device_uid: The UID of the device to retrieve
+        :return: A Device object as dictionary or error response
+        :raises ValueError: If device_uid is not a valid string
+        """
+        validate_uid(device_uid)
+        url = self._url(f"devices/uid/{device_uid}/")
+        return self.make_get_request(url)
+
+    @handle_exceptions
+    def get_latest_data_by_uid(self, device_uid: str, **filters: str) -> dict[str, Any]:
+        """
+        GET latest data for a device by UID.
+
+        :param device_uid: The UID of the device to retrieve
+        :return: A Device object as dictionary or error response
+        """
+        validate_uid(device_uid)
+        url = self._url(f"devices/uid/{device_uid}/data/latest/")
+        return self.make_get_request(url, params=filters)
+
+    @handle_exceptions
+    def get_events_by_uid(
+        self, device_uid: str, **filters: str
+    ) -> list[dict[str, Any]]:
+        """
+        GET events for a device by UID.
+
+        :param device_uid: The UID of the device to retrieve
+        :return:
+        """
+        validate_uid(device_uid)
+        url = self._url(f"devices/uid/{device_uid}/events/")
+        return self.make_get_request(url, params=filters)
+
+    @handle_exceptions
+    def get_commands_by_uid(
+        self, device_uid: str, **filters: str
+    ) -> list[dict[str, Any]]:
+        """
+        GET commands for a device by UID.
+
+        :param device_uid: The UID of the device to retrieve
+        :return:
+        """
+        validate_uid(device_uid)
+        url = self._url(f"devices/uid/{device_uid}/commands/")
+        return self.make_get_request(url, params=filters)
+
+    @handle_exceptions
+    def list_by_folder(self, folder_id: int, **filters: str) -> list[dict[str, Any]]:
+        """
+        GET list of devices by folder ID.
+
+        :param folder_id:
+        :param filters:
+        :return:
+        """
+        validate_id(folder_id)
+        url = self._url(f"devices/folder/{folder_id}/")
+        return self.make_get_request(url, params=filters)
+
+    @handle_exceptions
+    def list_by_folder_lite(
+        self, folder_id: int, **filters: str
+    ) -> list[dict[str, Any]]:
+        """
+        GET lightweight list of devices by folder ID.
+
+        :param folder_id:
+        :param filters:
+        :return:
+        """
+        validate_id(folder_id)
+        url = self._url(f"devices/folder/{folder_id}/lite/")
+        return self.make_get_request(url, params=filters)
+
+    @handle_exceptions
+    def move_to_folder(self, device_id: int, folder_id: int) -> dict[str, Any]:
+        """
+        Move a device identified by ID to a folder identified by ID.
+
+        :param device_id:
+        :param folder_id:
+        :return:
+        """
+        validate_id(device_id)
+        validate_id(folder_id)
+
+        url = self._url(f"devices/{device_id}/")
+        data = {
+            "folder": folder_id,
+        }
+        return self.make_patch_request(url, json=data)
+
+    @handle_exceptions
+    def move_to_folder_by_uid(self, device_uid: str, folder_id: int) -> dict[str, Any]:
+        """
+        Move a device identified by UID to a folder identified by ID.
+
+        :param device_uid:
+        :param folder_id:
+        :return:
+        """
+        validate_uid(device_uid)
+        validate_id(folder_id)
+
+        url = self._url(f"devices/uid/{device_uid}/")
+        data = {
+            "folder": folder_id,
+        }
+        return self.make_patch_request(url, json=data)
+
+    @handle_exceptions
+    def set_lifecycle(self, device_id: int, target_state: int) -> dict[str, Any]:
+        """
+        Change the lifecycle state of a device by ID.
+
+        :param device_id:
+        :param target_state:
+        :return:
+        """
+        validate_id(device_id)
+        validate_id(target_state)
+
+        url = self._url(f"devices/{device_id}/")
+        data = {
+            "state": target_state,
+        }
+        return self.make_patch_request(url, json=data)
+
+    @handle_exceptions
+    def set_lifecycle_by_uid(
+        self, device_uid: str, target_state: int
+    ) -> dict[str, Any]:
+        """
+        Change the lifecycle state of a device by UID.
+
+        :param device_uid:
+        :param target_state:
+        :return:
+        """
+        validate_uid(device_uid)
+        validate_id(target_state)
+
+        url = self._url(f"devices/uid/{device_uid}/")
+        data = {
+            "state": target_state,
+        }
+        return self.make_patch_request(url, json=data)
+
+    @handle_exceptions
+    def issue_command(self, device_id: int, command: dict) -> dict[str, Any]:
+        """
+        Issue an arbitrary command to a device by ID.
+
+        :param device_id:
+        :param command:
+        :return:
+        """
+        validate_id(device_id)
+        validate_command(command)
+        url = self._url(f"devices/{device_id}/command/send/")
+        data = {
+            **command,
+        }
+        return self.make_post_request(url, json=data)
+
+    @handle_exceptions
+    def issue_command_by_uid(self, device_uid: str, command: dict) -> dict[str, Any]:
+        """
+        Issue an arbitrary command to a device by UID.
+
+        :param device_uid:
+        :param command:
+        :return:
+        """
+        validate_uid(device_uid)
+        validate_command(command)
+        url = self._url(f"devices/uid/{device_uid}/command/send/")
+        data = {
+            **command,
+        }
+        return self.make_post_request(url, json=data)

trinity_connect_client-0.2.0/src/trinity_connect_client/modules/orgs/__init__.py

@@ -0,0 +1,49 @@
+from typing import Dict, List, Any, Union
+
+from trinity_connect_client.decorators import handle_exceptions
+from trinity_connect_client.mixins import ResourceMixin
+from trinity_connect_client.validators import validate_id
+
+
+class OrgsAPI(ResourceMixin):
+    @handle_exceptions
+    def get(self, company_id: int) -> Dict[str, Any]:
+        """
+        GET a company by ID.
+
+        :param company_id: The ID of the company to retrieve
+        :return: A Company object as dictionary or error response
+        """
+        validate_id(company_id)
+        url = self._url(f"orgs/company/{company_id}/")
+        return self.make_get_request(url)
+
+    @handle_exceptions
+    def get_folders(
+        self, company_id: int, **filters
+    ) -> Union[List[Dict[str, Any]], Dict[str, Any]]:
+        """
+        GET company folders for a given company ID.
+
+        :param company_id: The ID of the company whose folders to retrieve
+        :param filters: Optional filters to apply to the request
+        :return: List of folder objects as dictionaries or error response
+        """
+        validate_id(company_id)
+        url = self._url(f"orgs/folders/company/{company_id}/")
+        return self.make_get_request(url, params=filters)
+
+    @handle_exceptions
+    def get_folder(
+        self, folder_id: int, **filters
+    ) -> Union[List[Dict[str, Any]], Dict[str, Any]]:
+        """
+        GET folder for a given folder ID.
+
+        :param folder_id: The ID of the folder to retrieve
+        :param filters: Optional filters to apply to the request
+        :return: List of folder objects as dictionaries or error response
+        """
+        validate_id(folder_id)
+        url = self._url(f"orgs/folder/{folder_id}/")
+        return self.make_get_request(url, params=filters)

trinity_connect_client-0.2.0/src/trinity_connect_client/validators.py

@@ -0,0 +1,33 @@
+def validate_id(i):
+    if not isinstance(i, int) or i <= 0:
+        raise ValueError("ID must be a positive integer")
+
+
+def validate_uid(u):
+    if not isinstance(u, str) or not u.strip():
+        raise ValueError("UID must be a non-empty string")
+
+
+def validate_command(command):
+    if not isinstance(command, dict):
+        raise ValueError("Command must be a dictionary")
+
+    required_fields = {"rpc", "args", "pid", "ttl", "qos"}
+    if not required_fields.issubset(command.keys()):
+        missing = required_fields - command.keys()
+        raise ValueError(f"Command missing required fields: {missing}")
+
+    if not isinstance(command["rpc"], str):
+        raise ValueError("Command 'rpc' must be a string")
+
+    if not isinstance(command["args"], list):
+        raise ValueError("Command 'args' must be a list")
+
+    if not isinstance(command["pid"], (str, int)):
+        raise ValueError("Command 'pid' must be a string or integer")
+
+    if not isinstance(command["ttl"], (int, float)) or command["ttl"] < 0:
+        raise ValueError("Command 'ttl' must be a non-negative number")
+
+    if not isinstance(command["qos"], int) or command["qos"] < 0:
+        raise ValueError("Command 'qos' must be a non-negative integer")