Metadata-Version: 2.4
Name: geotrack-sdk
Version: 1.0.0
Summary: SDK officiel Python pour GeoTrack Pro — GPS, logistique et géofencing
Project-URL: Homepage, https://geo.lsgrouptogo.com
Project-URL: Repository, https://github.com/geotrack-pro/python-sdk
Author-email: GeoTrack Pro <dev@geo.lsgrouptogo.com>
License: MIT
License-File: LICENSE
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# GeoTrack Pro Python SDK

SDK officiel Python pour l'API [GeoTrack Pro](https://geo.lsgrouptogo.com) — plateforme de géolocalisation de flotte, logistique et géofencing.

[![PyPI version](https://badge.fury.io/py/geotrack-sdk.svg)](https://pypi.org/project/geotrack-sdk/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

## Installation

```bash
pip install geotrack-sdk
```

## Démarrage rapide

```python
import asyncio
from geotrack import GeoTrackClient

async def main():
    async with GeoTrackClient(api_key="gt_votre_cle_api") as client:

        # Lister les véhicules en ligne
        devices = await client.devices.list(is_online=True)
        print(f"{devices.total} véhicules en ligne")

        for device in devices.items:
            print(f"  {device.name} — {device.last_position}")

        # Historique de positions des dernières 24h
        from datetime import datetime, timedelta, timezone
        now = datetime.now(timezone.utc)
        positions = await client.devices.get_positions(
            device_id=devices.items[0].id,
            from_dt=(now - timedelta(hours=24)).isoformat(),
            to_dt=now.isoformat(),
        )
        print(f"{len(positions)} positions récupérées")

asyncio.run(main())
```

## Ressources disponibles

### Devices

```python
# Lister avec filtres
devices = await client.devices.list(page=1, page_size=50, is_online=True)

# Détail d'un device
device = await client.devices.get("uuid-du-device")

# Positions sur une plage
positions = await client.devices.get_positions("uuid", from_dt="...", to_dt="...")

# Résumé de trajets
trips = await client.devices.get_trip_summary("uuid", from_dt="...", to_dt="...")
```

### Alertes

```python
# Lister les alertes récentes
alerts = await client.alerts.list(page=1, alert_type="overspeed")

# Marquer comme lue
await client.alerts.acknowledge("alert-uuid")
```

### Colis (Last-Mile)

```python
# Créer un colis
parcel = await client.parcels.create(
    tracking_code="TRACK-001",
    recipient_name="Jean Dupont",
    recipient_phone="+22891000000",
    destination_address="Lomé, Togo",
)

# Mettre à jour le statut
await client.parcels.update_status(parcel.id, status="out_for_delivery")

# Lister par statut
parcels = await client.parcels.list(status="pending")
```

### Webhooks

```python
from geotrack import WebhookHandler

handler = WebhookHandler(secret="votre_secret_webhook")

# Dans votre endpoint FastAPI / Flask :
@app.post("/webhook/geotrack")
async def handle_webhook(request: Request):
    payload = await request.body()
    signature = request.headers.get("X-GeoTrack-Signature")

    event = handler.parse(payload, signature)
    print(f"Événement : {event.type} — Device : {event.device_id}")
    return {"ok": True}
```

## Gestion des erreurs

```python
from geotrack import GeoTrackError, AuthError, RateLimitError, QuotaError, NotFoundError

try:
    device = await client.devices.get("uuid-invalide")
except NotFoundError:
    print("Device introuvable")
except RateLimitError as e:
    print(f"Rate limit — réessayer dans {e.retry_after}s")
except AuthError:
    print("Clé API invalide ou expirée")
except QuotaError:
    print("Quota mensuel dépassé — mettre à niveau le plan")
except GeoTrackError as e:
    print(f"Erreur API : {e}")
```

## Auto-hébergement

```python
client = GeoTrackClient(
    api_key="gt_...",
    base_url="https://votre-instance.com/api/v1",
)
```

## Générer une clé API

1. Connectez-vous sur [geo.lsgrouptogo.com](https://geo.lsgrouptogo.com)
2. Paramètres → API Keys → Créer une clé
3. Copiez la clé (affichée une seule fois)

## Liens

- [Documentation API](https://geo.lsgrouptogo.com/api/docs)
- [Tableau de bord](https://geo.lsgrouptogo.com)
- [GitHub](https://github.com/akeala5/trackgps-pro)
- [Support](mailto:support@geo.lsgrouptogo.com)

## Licence

MIT — voir [LICENSE](LICENSE)
