geo-engine-python 0.1.2__tar.gz → 0.2.0__tar.gz

geo_engine_python-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,259 @@
+# 🐍 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)**