geo-engine-python 0.1.3__py3-none-any.whl → 0.2.0__py3-none-any.whl

geo_engine_python-0.2.0.dist-info/METADATA

@@ -0,0 +1,278 @@
+Metadata-Version: 2.4
+Name: geo-engine-python
+Version: 0.2.0
+Summary: SDK oficial para Geo-Engine: rastreo, geocercas, validación espacial, usuarios y GeoIdentity
+Home-page: https://github.com/AlexG695/geo-engine-python
+Author: AlexG695
+Author-email: AlexG <alexg@geoengine.dev>
+Project-URL: Homepage, https://geoengine.dev
+Project-URL: Bug Tracker, https://github.com/AlexG695/geo-engine/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Dynamic: author
+Dynamic: home-page
+Dynamic: requires-python
+
+# 🐍 Geo-Engine Python SDK
+
+> *Read this in Spanish: [README.es.md](./README.es.md)*
+
+Official **Python** client for the **Geo-Engine** platform.
+Send real-time locations, manage geofences, validate points, administer organization members, and define GeoIdentity access rules from **Django**, **Flask**, **FastAPI**, scripts, or **Data Science** environments.
+
+Feature parity with the official Go SDK (`v2.1.0`), except for gRPC transport.
+
+---
+
+## ✨ Features
+
+- 📍 **Real-time Ingestion:** Coordinate ingestion via HTTP REST.
+- 🗺️ **Spatial Module:** Point-in-polygon validation against a single geofence or against all geofences.
+- 👥 **Users Module:** Organization members, roles, and email invitations.
+- 🛡️ **GeoIdentity Module:** Access rules (IP blacklists, geographic boundaries, Tor/datacenter blocking) assignable to users or to the entire organization.
+- 🚧 **Geofences:** Creation with automatic GeoJSON polygon normalization.
+- 🔄 **AsyncIngester:** Background queue with auto-flush by batch size and time interval.
+- 🔐 **Security:** HMAC-SHA256 signature (`X-Signature`) with anti-replay timestamp and JWT Bearer token support.
+- 🧯 **Typed Errors** for every business case.
+
+---
+
+## 🚀 Installation
+
+```bash
+pip install geo-engine-python
+```
+
+---
+
+## ⚡ Quick Start
+
+```python
+from geoengine import GeoEngine
+
+# Connects to production environment by default
+client = GeoEngine(api_key="geo_live_123456")
+
+try:
+    res = client.send_location(device_id="truck-01", lat=19.4326, lng=-99.1332)
+    print(f"✅ Sent: {res}")
+except Exception as e:
+    print(f"❌ Error: {e}")
+finally:
+    client.close()
+```
+
+Also works as a context manager: `with GeoEngine("geo_live_...") as client: ...`
+
+---
+
+## 🗺️ Spatial Module
+
+```python
+from geoengine import GeofenceNotFoundError
+
+# Against a specific geofence
+try:
+    res = client.spatial.validate_point("geofence_123", 19.4326, -99.1332)
+    if res.is_inside():
+        print(f"Inside {res.geofence_name} ({res.geofence_id})")
+    print(res)  # [INSIDE] geofence=geofence_123 (Downtown) at (19.432600, -99.133200)
+except GeofenceNotFoundError:
+    print("The geofence does not exist")
+
+# Against all active geofences in the organization
+res = client.spatial.validate_general(19.4326, -99.1332)
+if res.has_matches():
+    print(res.total_matches, res.geofence_names())
+    print(res.contains_geofence("CDMX Downtown"), res.find_match("CDMX Downtown"))
+
+# Fluent query builder
+single = client.spatial.check(19.4326, -99.1332).in_geofence("geofence_123").execute()
+general = client.spatial.check(19.4326, -99.1332).in_all_geofences().execute()
+```
+
+---
+
+## 👥 Users Module
+
+`client.users` manages members of the organization that owns the API key:
+
+```python
+from geoengine import Roles, InvitationPendingError, LastAdminError
+
+# List members and available roles
+users = client.users.list()
+roles = client.users.list_roles()
+user = client.users.get("user_123")
+
+# Invite a new member (GeoEngine sends the invitation email)
+try:
+    inv = client.users.invite("ana@acme.com", Roles.VIEWER, lang="en")  # "es" (default) | "en" | "pt"
+    print("Invitation link:", inv.invite_url)
+except InvitationPendingError:
+    print("There is already a pending invitation for this email")
+
+# Update a member's role or revoke their access
+try:
+    client.users.update_role("user_123", Roles.DISPATCHER)
+    client.users.remove("user_123")
+except LastAdminError:
+    print("The organization must retain at least one administrator")
+```
+
+---
+
+## 🛡️ GeoIdentity Module
+
+`client.geoidentity` creates access rules and assigns them to a user or to the entire organization:
+
+```python
+from geoengine import RuleAction, SubjectAssignment, SubjectType, polygon_from_lat_lng
+
+area = polygon_from_lat_lng([
+    [19.40, -99.20], [19.40, -99.10], [19.50, -99.10],  # [lat, lng]
+])
+
+rule = client.geoidentity.create_rule(
+    "CDMX Only",
+    action=RuleAction.BLOCK,
+    black_ip_list=["203.0.113.0/24"],
+    block_tor=True,
+    geo_limit=area,
+    assigned_subjects=[SubjectAssignment(SubjectType.USER, "user_123")],
+)
+
+# Query, update, and delete
+rules = client.geoidentity.list_rules(is_active=True)
+detail = client.geoidentity.get_rule(rule.id)  # includes assigned_subjects
+client.geoidentity.update_rule(rule.id, is_active=False, geo_limit=None)  # None removes the geographic boundary
+client.geoidentity.delete_rule(rule.id)
+
+# Assign or unassign the rule
+client.geoidentity.assign_to_user(rule.id, "user_456")
+client.geoidentity.assign_to_organization(rule.id)
+client.geoidentity.unassign_from_user(rule.id, "user_456")
+
+# Rules that apply to a user (direct, by role, or organization-wide)
+user_rules = client.geoidentity.list_user_rules("user_123")
+```
+
+> A rule created without `assigned_subjects` applies to the entire organization. A rule must always retain at least one subject: removing the last one raises `LastSubjectError` (deactivate or delete the rule instead).
+>
+> `update_rule` only sends the parameters you provide; unspecified parameters remain unchanged.
+
+---
+
+## 🚧 Geofences
+
+The SDK takes `[latitude, longitude]` pairs, converts them to GeoJSON, and closes the polygon:
+
+```python
+client.create_geofence(
+    "North Logistics Park",
+    [[19.4326, -99.1332], [19.4426, -99.1332], [19.4426, -99.1232]],
+    webhook_url="https://my-api.com/webhooks/geofences",  # optional
+)
+```
+
+---
+
+## 🔄 Asynchronous Ingestion (`AsyncIngester`)
+
+```python
+from geoengine import LocationPing
+
+# 5000 pings queue; flushes every 100 items or every 0.5 s
+ingester = client.create_async_ingester(buffer_size=5000, batch_size=100, flush_interval=0.5)
+
+ok = ingester.enqueue(LocationPing("truck-45", 19.4326, -99.1332))
+if not ok:
+    print("Queue full or ingester stopped")
+
+# On service shutdown: flushes pending items and stops the background thread
+ingester.stop()
+client.close()
+```
+
+Background sending errors are silently dropped.
+
+---
+
+## 🔧 Advanced Configuration
+
+```python
+client = GeoEngine(
+    api_key="sk_test_...",
+    environment="test",                 # "live" (default) | "test"
+    jwt_token="my.jwt.token",           # optional
+    timeout=5,                          # seconds
+    ingest_url="http://localhost:8080",
+    management_url="http://localhost:8081",
+    api_service_url="http://localhost:8082",  # Spatial, Users, and GeoIdentity
+    # or a single URL for all three (local tests / mocks):
+    # base_url="http://localhost:8080",
+)
+```
+
+---
+
+## 🧯 Errors
+
+All errors inherit from `GeoEngineError`.
+
+| Error | When it occurs |
+| :--- | :--- |
+| `ValidationError` (also `ValueError`) and subclasses: `DeviceIDRequiredError`, `GeofenceIDRequiredError`, `InvalidLatitudeError`, `InvalidLongitudeError`, `InvalidCoordinatesError`, `UserIDRequiredError`, `RuleIDRequiredError`, `RuleNameRequiredError`, `EmailRequiredError`, `RoleRequiredError` | Invalid parameter; API is not called |
+| `APIError` | Ingestion or management HTTP error (`status_code`, `api_message`) |
+| `APIServiceError` | API service error; adds `code` and `details` |
+| `GeofenceNotFoundError` | Geofence does not exist (Spatial, 204/404) |
+| `UserNotFoundError` | `USER_NOT_FOUND`, `USER_REVOKED` |
+| `RuleNotFoundError` | `RULE_NOT_FOUND` |
+| `UserAlreadyExistsError` | `USER_ALREADY_EXISTS` |
+| `InvitationPendingError` | `INVITATION_PENDING` |
+| `LastAdminError` | `LAST_ADMIN` |
+| `LastSubjectError` | `LAST_SUBJECT` |
+| `AuthenticationError` / `ForbiddenError` / `QuotaExceededError` | 401 / 403 / 402 |
+| `NetworkError`, `RequestTimeoutError` | Network failure or request timeout |
+| `ClientClosedError` | Client used after calling `close()` |
+
+The SDK does not automatically retry requests.
+
+---
+
+## 🔐 Authentication
+
+The SDK authenticates using **API Keys** and signs each request.
+Keep them secret and **never expose them in frontend applications**.
+
+---
+
+## 🧪 Testing
+
+```bash
+python -m unittest discover -s tests -t .
+```
+
+---
+
+## 🧩 Compatibility
+
+* Python **3.7+**
+* Django, Flask, FastAPI, CLI scripts, Jupyter / Data Science
+
+---
+
+## 📄 License
+
+MIT © Geo-Engine
+
+---
+
+## 🤝 Support
+
+Have questions or suggestions?
+Open an issue or contact us at **[support@geoengine.dev](mailto:support@geoengine.dev)**

geo_engine_python-0.2.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+geoengine/__init__.py,sha256=nvhIaAET6ecVpm22TANQZXPLpOIhAehLSM9gsjsS8uQ,1383
+geoengine/_http.py,sha256=UGKjyBSQbpGph--7ZMDtfkvlmk6lg5UMeojXFvTs-SY,6930
+geoengine/_version.py,sha256=Zn1KFblwuFHiDRdRAiRnDBRkbPttWh44jKa5zG2ov0E,22
+geoengine/client.py,sha256=unvB7HWci9VL2WkPzRIzhk8hIi7GrfJJVX4nfdSw64s,5164
+geoengine/errors.py,sha256=Mq3j-9dtD4VXpjMGlTITK0QFcm8eUEXTdY6iZnyxlSo,4523
+geoengine/geoidentity.py,sha256=r8lv1kfw_cbVfJUrx0JRJgezqHz_9kwgUpRz-4D1xq8,7456
+geoengine/ingester.py,sha256=MDsyOyFNTSOECTkGoN1JsLaFeNkuCbAOMT8g4k37bEk,2500
+geoengine/models.py,sha256=9cggYlZysHUei5OeYitx3uuXN8AC7UgJbVBi2I2gmUk,5993
+geoengine/spatial.py,sha256=huBL4C7YgofICk7q_gQWbX16bPGMJkkzRPqO_zmmSKw,2876
+geoengine/users.py,sha256=BV2ixzfBjiFNxIyxgJntUDDaHC6oGOhVBg7aaX2_4Js,2936
+geoengine/validation.py,sha256=xDwuFqcNVtW9lMwAJa9D0iEVVu5MszMQpMZSSw-aO00,1815
+geo_engine_python-0.2.0.dist-info/METADATA,sha256=IxEq5eBTY8-kdymVoKUb0-JY4OBXGU6Nbqkw619KYdI,8906
+geo_engine_python-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+geo_engine_python-0.2.0.dist-info/top_level.txt,sha256=bqE5zIDfI6saPEFHhCIwqCBOhsiQ998LGjP_srSIg9E,10
+geo_engine_python-0.2.0.dist-info/RECORD,,

{geo_engine_python-0.1.3.dist-info → geo_engine_python-0.2.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (78.1.1)
+Generator: setuptools (84.2.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

geoengine/__init__.py

@@ -1 +1,55 @@
-from .client import GeoEngine, GeoEngineError
+"""SDK oficial de Python para la plataforma Geo-Engine."""
+from ._http import generate_hmac_signature
+from ._version import __version__
+from .client import GeoEngine
+from .errors import (
+    APIError,
+    APIServiceError,
+    AuthenticationError,
+    ClientClosedError,
+    DeviceIDRequiredError,
+    EmailRequiredError,
+    ForbiddenError,
+    GeoEngineError,
+    GeofenceIDRequiredError,
+    GeofenceNotFoundError,
+    InvalidCoordinatesError,
+    InvalidLatitudeError,
+    InvalidLongitudeError,
+    InvitationPendingError,
+    LastAdminError,
+    LastSubjectError,
+    NetworkError,
+    QuotaExceededError,
+    RequestTimeoutError,
+    RoleRequiredError,
+    RuleIDRequiredError,
+    RuleNameRequiredError,
+    RuleNotFoundError,
+    UserAlreadyExistsError,
+    UserIDRequiredError,
+    UserNotFoundError,
+    ValidationError,
+)
+from .geoidentity import UNSET, GeoIdentityService, polygon_from_lat_lng
+from .ingester import AsyncIngester
+from .models import (
+    GeofenceMatch,
+    Invitation,
+    LocationPing,
+    Role,
+    Roles,
+    Rule,
+    RuleAction,
+    SpatialGeneralResult,
+    SpatialValidationResult,
+    SubjectAssignment,
+    SubjectType,
+    User,
+    UserStatus,
+)
+from .spatial import SpatialService
+from .users import UsersService
+from .validation import validate_coordinates
+
+__all__ = [name for name in dir() if not name.startswith("_")] + ["__version__"]

geoengine/_http.py

@@ -0,0 +1,208 @@
+"""Transporte HTTP interno: cabeceras firmadas, envelope del api-service y errores tipados."""
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, Optional
+
+import requests
+
+from ._version import __version__
+from .errors import (
+    APIError,
+    APIServiceError,
+    AuthenticationError,
+    ClientClosedError,
+    ForbiddenError,
+    GeoEngineError,
+    GeofenceNotFoundError,
+    InvitationPendingError,
+    LastAdminError,
+    LastSubjectError,
+    NetworkError,
+    QuotaExceededError,
+    RequestTimeoutError,
+    RuleNotFoundError,
+    UserAlreadyExistsError,
+    UserNotFoundError,
+)
+
+USER_AGENT = f"GeoEnginePythonSDK/{__version__}"
+
+# Tipos de endpoint: definen cómo se interpretan la respuesta y los errores.
+PLAIN = "plain"  # ingesta / gestión: JSON tal cual, errores como APIError
+SPATIAL = "spatial"  # api-service spatial: envelope {success, data}; 204/404 = geocerca inexistente
+API_SERVICE = "api_service"  # api-service users / geoidentity: envelope {success, data}
+
+_CODE_ERRORS = {
+    "USER_NOT_FOUND": UserNotFoundError,
+    "USER_REVOKED": UserNotFoundError,
+    "RULE_NOT_FOUND": RuleNotFoundError,
+    "USER_ALREADY_EXISTS": UserAlreadyExistsError,
+    "INVITATION_PENDING": InvitationPendingError,
+    "LAST_ADMIN": LastAdminError,
+    "LAST_SUBJECT": LastSubjectError,
+    "QUOTA_EXCEEDED": QuotaExceededError,
+    "MISSING_API_KEY": AuthenticationError,
+    "MISSING_ORGANIZATION": AuthenticationError,
+}
+
+_STATUS_ERRORS = {
+    401: AuthenticationError,
+    402: QuotaExceededError,
+    403: ForbiddenError,
+}
+
+
+def generate_hmac_signature(key: str, timestamp_ms: int) -> str:
+    """Firma HMAC-SHA256 (hex) del timestamp en milisegundos usando la API key como secreto."""
+    if not key:
+        return ""
+    return hmac.new(key.encode("utf-8"), str(timestamp_ms).encode("utf-8"), hashlib.sha256).hexdigest()
+
+
+def parse_api_service_error(status_code: int, body_text: str, spatial: bool = False) -> APIServiceError:
+    """Convierte el cuerpo de error del api-service en la excepción tipada correspondiente."""
+    code = ""
+    message = ""
+    details = []
+
+    container = None
+    try:
+        parsed = json.loads(body_text)
+        if isinstance(parsed, dict) and isinstance(parsed.get("error"), dict):
+            container = parsed["error"]
+    except ValueError:
+        pass
+
+    if container is not None:
+        code = container.get("status") or ""
+        message = container.get("message") or ""
+        raw_details = container.get("details")
+        if isinstance(raw_details, list):
+            details = [d for d in raw_details if isinstance(d, dict)]
+        for detail in details:
+            if detail.get("reason"):
+                code = detail["reason"]
+                break
+    else:
+        message = (body_text or "").strip()
+
+    if not message:
+        message = f"HTTP {status_code}"
+
+    error_class = _CODE_ERRORS.get(code)
+    if error_class is None and spatial and (status_code in (204, 404) or code == "NOT_FOUND"):
+        error_class = GeofenceNotFoundError
+        code = code or "NOT_FOUND"
+    if error_class is None:
+        error_class = _STATUS_ERRORS.get(status_code, APIServiceError)
+
+    return error_class(status_code, code, message, details)
+
+
+class Transport:
+    """Envía peticiones autenticadas. Seguro para usarse desde varios hilos."""
+
+    def __init__(
+        self,
+        api_key: str,
+        jwt_token: Optional[str],
+        environment: str,
+        timeout: float,
+        session: Optional[requests.Session] = None,
+    ):
+        self.api_key = api_key
+        self.jwt_token = jwt_token
+        self.environment = environment
+        self.timeout = timeout
+        self.session = session or requests.Session()
+        self._owns_session = session is None
+        self.closed = False
+
+    def close(self) -> None:
+        if not self.closed:
+            self.closed = True
+            if self._owns_session:
+                self.session.close()
+
+    def headers(self, has_body: bool) -> dict:
+        now = int(time.time() * 1000)
+        headers = {
+            "Accept": "application/json",
+            "X-API-Key": self.api_key,
+            "X-Geo-Environment": self.environment,
+            "X-Request-Time": str(now),
+            "X-Signature": generate_hmac_signature(self.api_key, now),
+            "User-Agent": USER_AGENT,
+        }
+        if has_body:
+            headers["Content-Type"] = "application/json"
+        if self.jwt_token:
+            headers["Authorization"] = f"Bearer {self.jwt_token}"
+        return headers
+
+    def request(self, method: str, url: str, body: Any = None, kind: str = PLAIN) -> Any:
+        if self.closed:
+            raise ClientClosedError()
+
+        has_body = body is not None
+        try:
+            response = self.session.request(
+                method,
+                url,
+                data=json.dumps(body).encode("utf-8") if has_body else None,
+                headers=self.headers(has_body),
+                timeout=self.timeout,
+            )
+        except requests.exceptions.Timeout as exc:
+            raise RequestTimeoutError(
+                f"geoengine: request exceeded the timeout limit of {self.timeout}s"
+            ) from exc
+        except requests.exceptions.RequestException as exc:
+            raise NetworkError(f"geoengine: network error: {exc}") from exc
+
+        status = response.status_code
+        text = response.text or ""
+
+        if status == 204:
+            if kind == SPATIAL:
+                raise GeofenceNotFoundError(204, "NOT_FOUND", "geofence not found")
+            return None
+
+        if status >= 400:
+            if kind == PLAIN:
+                raise APIError(status, _plain_error_message(text) or f"HTTP {status}")
+            raise parse_api_service_error(status, text, spatial=kind == SPATIAL)
+
+        if not text.strip():
+            return None
+
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            raise GeoEngineError("geoengine: failed to parse response JSON") from exc
+
+        if kind != PLAIN and isinstance(payload, dict) and "success" in payload:
+            if not payload["success"]:
+                raise parse_api_service_error(status, text, spatial=kind == SPATIAL)
+            return payload.get("data")
+
+        return payload
+
+
+def _plain_error_message(text: str) -> str:
+    """Extrae el mensaje del servidor ({"error": "..."}) o devuelve el cuerpo tal cual."""
+    try:
+        parsed = json.loads(text)
+    except ValueError:
+        return text.strip()
+    if isinstance(parsed, dict):
+        error = parsed.get("error")
+        if isinstance(error, str) and error:
+            return error
+        if isinstance(error, dict) and error.get("message"):
+            return str(error["message"])
+        if isinstance(parsed.get("message"), str) and parsed["message"]:
+            return parsed["message"]
+    return text.strip()

geoengine/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

geoengine/client.py

@@ -0,0 +1,122 @@
+"""Cliente principal de GeoEngine."""
+import time
+from typing import Any, Dict, Optional, Sequence
+
+import requests
+
+from ._http import PLAIN, Transport
+from .errors import ValidationError
+from .geoidentity import GeoIdentityService
+from .ingester import AsyncIngester
+from .models import SpatialGeneralResult, SpatialValidationResult
+from .spatial import SpatialService
+from .users import UsersService
+from .validation import normalize_polygon, validate_device_id
+
+
+class GeoEngine:
+    """Cliente de las APIs de GeoEngine. Seguro para usarse desde varios hilos.
+
+    Módulos: ``spatial`` (validación de puntos), ``users`` (miembros, roles e invitaciones)
+    y ``geoidentity`` (reglas de acceso).
+    """
+
+    DEFAULT_MANAGEMENT_URL = "https://management.geoengine.dev"
+    DEFAULT_INGEST_URL = "https://ingest.geoengine.dev"
+    DEFAULT_API_SERVICE_URL = "https://api.geoengine.dev"
+
+    def __init__(
+        self,
+        api_key: str,
+        management_url: Optional[str] = None,
+        ingest_url: Optional[str] = None,
+        timeout: float = 10,
+        *,
+        api_service_url: Optional[str] = None,
+        base_url: Optional[str] = None,
+        environment: str = "live",
+        jwt_token: Optional[str] = None,
+        session: Optional[requests.Session] = None,
+    ):
+        """
+        Inicializa el cliente de GeoEngine.
+
+        :param api_key: Tu clave secreta de API.
+        :param management_url: URL base para gestión de geocercas (opcional).
+        :param ingest_url: URL base para ingestión (opcional).
+        :param timeout: Tiempo de espera en segundos para requests (default: 10).
+        :param api_service_url: URL base del api-service: Spatial, Users y GeoIdentity (opcional).
+        :param base_url: Sobrescribe las tres URLs a la vez; útil para pruebas locales.
+        :param environment: "live" (default) o "test"; se envía como X-Geo-Environment.
+        :param jwt_token: Token Bearer para operaciones autenticadas (opcional).
+        :param session: requests.Session propia (opcional); el cliente no la cierra.
+        """
+        if not isinstance(api_key, str) or not api_key.strip():
+            raise ValidationError("GeoEngine: API Key es requerida")
+
+        self.api_key = api_key
+        self.management_url = (base_url or management_url or self.DEFAULT_MANAGEMENT_URL).rstrip("/")
+        self.ingest_url = (base_url or ingest_url or self.DEFAULT_INGEST_URL).rstrip("/")
+        self.api_service_url = (base_url or api_service_url or self.DEFAULT_API_SERVICE_URL).rstrip("/")
+        self.environment = environment
+        self.timeout = timeout
+
+        self._transport = Transport(api_key, jwt_token, environment, timeout, session)
+        self.spatial = SpatialService(self._transport, self.api_service_url)
+        self.users = UsersService(self._transport, self.api_service_url)
+        self.geoidentity = GeoIdentityService(self._transport, self.api_service_url)
+
+    # --- Ingesta y geocercas ---
+
+    def send_location(self, device_id: str, lat: float, lng: float) -> Optional[Dict[str, Any]]:
+        """Envía la ubicación de un dispositivo. Devuelve la respuesta de la API."""
+        payload = {
+            "device_id": validate_device_id(device_id),
+            "latitude": float(lat),
+            "longitude": float(lng),
+            "timestamp": int(time.time()),
+        }
+        return self._transport.request("POST", f"{self.ingest_url}/ingest", payload, PLAIN)
+
+    def create_geofence(
+        self,
+        name: str,
+        coordinates: Sequence[Sequence[float]],
+        webhook_url: Optional[str] = None,
+    ) -> Optional[Dict[str, Any]]:
+        """Crea una geocerca a partir de pares [lat, lng] (mínimo 3). El polígono se cierra solo."""
+        if not isinstance(name, str) or not name.strip():
+            raise ValidationError("geoengine: name is required")
+        payload: Dict[str, Any] = {
+            "name": name.strip(),
+            "geojson": {"type": "Polygon", "coordinates": [normalize_polygon(coordinates)]},
+        }
+        if webhook_url:
+            payload["webhook_url"] = webhook_url
+        return self._transport.request("POST", f"{self.management_url}/geofences", payload, PLAIN)
+
+    def create_async_ingester(
+        self, buffer_size: int = 5000, batch_size: int = 100, flush_interval: float = 0.5
+    ) -> AsyncIngester:
+        """Crea una cola de ingesta en segundo plano (flush_interval en segundos)."""
+        return AsyncIngester(self, buffer_size, batch_size, flush_interval)
+
+    # --- Atajos de Spatial ---
+
+    def validate_spatial_point(self, geofence_id: str, lat: float, lng: float) -> SpatialValidationResult:
+        return self.spatial.validate_point(geofence_id, lat, lng)
+
+    def validate_spatial_general(self, lat: float, lng: float) -> SpatialGeneralResult:
+        return self.spatial.validate_general(lat, lng)
+
+    # --- Ciclo de vida ---
+
+    def close(self) -> None:
+        """Cierra el cliente. Las llamadas posteriores lanzan ClientClosedError."""
+        self._transport.close()
+
+    def __enter__(self) -> "GeoEngine":
+        return self
+
+    def __exit__(self, *exc_info) -> None:
+        self.close()