geo-engine-node 1.0.0 → 1.1.0

package/Readme.md

@@ -0,0 +1,135 @@
+
+---
+
+# 📦 Geo-Engine Node.js SDK
+
+Cliente oficial para interactuar con la plataforma **Geo-Engine**.
+Permite enviar ubicaciones en tiempo real y gestionar **geocercas** desde tus aplicaciones Node.js.
+
+---
+
+## 🚀 Instalación
+
+```bash
+npm install geo-engine-node
+```
+
+---
+
+## ⚡ Inicio Rápido
+
+Envía la ubicación de un dispositivo en **3 líneas de código**:
+
+```js
+const GeoEngine = require('geo-engine-node');
+
+// Inicializa con tu API Key (consíguela en tu Dashboard)
+const geo = new GeoEngine('sk_test_12345abcdef');
+
+// Envía una coordenada (ID, Latitud, Longitud)
+geo.sendLocation('camion-01', 19.4326, -99.1332)
+  .then(res => console.log('✅ Ubicación enviada:', res))
+  .catch(err => console.error('❌ Error:', err.message));
+```
+
+---
+
+## 📚 Referencia de la API
+
+### `new GeoEngine(apiKey, [options])`
+
+Crea una nueva instancia del cliente.
+
+**Parámetros:**
+
+* `apiKey` (`string`): Tu clave secreta de API.
+* `options` (`object`, opcional):
+
+  * `timeout`: Tiempo de espera en ms *(default: 10000)*.
+  * `ingestUrl`: URL personalizada para ingestión (útil para pruebas locales).
+  * `managementUrl`: URL personalizada para gestión.
+
+---
+
+### `geo.sendLocation(deviceId, lat, lng)`
+
+Envía un punto de rastreo al motor de ingestión.
+El sistema procesará automáticamente si este punto **entra o sale** de alguna geocerca activa.
+
+**Parámetros:**
+
+* `deviceId` (`string`): Identificador único del activo (ej: placa del vehículo, UUID).
+* `lat` (`number`): Latitud decimal.
+* `lng` (`number`): Longitud decimal.
+
+**Retorna:**
+`Promise<Object>` con el estado de la cola (`queued`).
+
+---
+
+### `geo.createGeofence(name, coordinates, webhookUrl)`
+
+Crea programáticamente una nueva zona de interés (geocerca).
+
+**Parámetros:**
+
+* `name` (`string`): Nombre descriptivo (ej: `"Almacén Central"`).
+* `coordinates` (`Array<Array<number>>`):
+  Lista de puntos que forman el polígono
+  `[[lat, lng], [lat, lng], ...]`
+  *(El SDK se encarga de cerrar el polígono si es necesario).*
+* `webhookUrl` (`string`):
+  URL donde Geo-Engine enviará una petición **POST** cuando un dispositivo entre en esta zona.
+
+**Ejemplo:**
+
+```js
+const zona = [
+  [19.42, -99.16],
+  [19.41, -99.16],
+  [19.41, -99.15],
+  [19.42, -99.15]
+];
+
+await geo.createGeofence(
+  'Zona Prohibida 1',
+  zona,
+  'https://mi-api.com/alertas'
+);
+```
+
+---
+
+## 🛡️ Manejo de Errores
+
+El SDK lanza errores descriptivos que puedes capturar fácilmente:
+
+```js
+try {
+  await geo.sendLocation('x', 0, 0);
+} catch (error) {
+  console.error(error.message);
+  // Ej: "GeoEngine API Error (401): Invalid API Key"
+}
+```
+
+---
+
+## 🧪 Desarrollo Local
+
+Si estás ejecutando **Geo-Engine** en tu máquina local, puedes configurar el cliente para que apunte a `localhost`:
+
+```js
+const geo = new GeoEngine('mi-clave-local', {
+  ingestUrl: 'http://localhost:8080',
+  managementUrl: 'http://localhost:8081'
+});
+```
+
+---
+
+## 📄 Licencia
+
+MIT © Geo-Engine Team
+
+---

package/index.js

@@ -1,92 +1,118 @@
-import { create } from 'axios';
-
 const DEFAULTS = {
   managementUrl: 'https://api.geoengine.dev',
-  ingestUrl: 'http://ingest.geoengine.dev',
+  ingestUrl: 'https://ingest.geoengine.dev',
   timeout: 10000
 };
 
 class GeoEngine {
   /**
-   * Inicializa el cliente de Geo-Engine
-   * @param {string} apiKey - Tu API Key (sk_...)
-   * @param {Object} options - Configuración opcional { managementUrl, ingestUrl }
+   * Inicializa el cliente de Geo-Engine.
+   * @param {string} apiKey - Tu API Key.
+   * @param {Object} [options] - Configuración opcional.
    */
   constructor(apiKey, options = {}) {
-    if (!apiKey) throw new Error('GeoEngine: API Key es requerida');
-    
+    if (!apiKey) {
+      throw new Error('GeoEngine: API Key es requerida.');
+    }
+
     this.apiKey = apiKey;
     this.config = { ...DEFAULTS, ...options };
-    
-    this.client = create({
-      timeout: this.config.timeout,
-      headers: {
-        'Content-Type': 'application/json',
-        'X-API-Key': this.apiKey,
-        'User-Agent': 'GeoEngineNode/1.0.0'
-      }
-    });
+    this.userAgent = 'GeoEngineNode/1.0.0';
   }
 
   /**
-   * Envía una ubicación al motor de ingestión
-   * @param {string} deviceId - ID del dispositivo (ej: 'camion-01')
-   * @param {number} lat - Latitud
-   * @param {number} lng - Longitud
+   * Helper privado para hacer peticiones con timeout
    */
-  async sendLocation(deviceId, lat, lng) {
+  async _request(url, method, body) {
+    const controller = new AbortController();
+    const id = setTimeout(() => controller.abort(), this.config.timeout);
+
     try {
-      const payload = {
-        device_id: deviceId,
-        latitude: lat,
-        longitude: lng,
-        timestamp: Math.floor(Date.now() / 1000)
-      };
-
-      const res = await this.client.post(`${this.config.ingestUrl}/ingest`, payload);
-      return res.data;
+      const response = await fetch(url, {
+        method: method,
+        headers: {
+          'Content-Type': 'application/json',
+          'X-API-Key': this.apiKey,
+          'User-Agent': this.userAgent
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+
+      clearTimeout(id);
+
+      if (!response.ok) {
+        // Intentar leer el error en JSON, si falla, leer texto
+        let errorData;
+        try {
+          errorData = await response.json();
+        } catch (e) {
+          errorData = { error: await response.text() };
+        }
+
+        throw new Error(`GeoEngine API Error (${response.status}): ${errorData.error || JSON.stringify(errorData)}`);
+      }
+
+      // Si la respuesta es 204 No Content o vacía, devolver null
+      if (response.status === 204) return null;
+
+      return await response.json();
+
     } catch (error) {
-      this._handleError(error);
+      clearTimeout(id);
+      if (error.name === 'AbortError') {
+        throw new Error(`GeoEngine: La petición excedió el tiempo límite de ${this.config.timeout}ms`);
+      }
+      throw error;
     }
   }
 
   /**
-   * Crea una nueva geocerca
-   * @param {string} name - Nombre de la zona
-   * @param {Array<Array<number>>} coordinates - Array de puntos [[lat, lng], ...]
-   * @param {string} webhookUrl - URL para recibir alertas
+   * Envía una ubicación al motor de ingestión.
    */
-  async createGeofence(name, coordinates, webhookUrl) {
-    try {
-      // Convertir formato simple [[lat,lng]] a GeoJSON
-      // GeoJSON usa [Lng, Lat], invertimos el orden si viene como [Lat, Lng]
-      const polygon = coordinates.map(p => [p[1], p[0]]); 
-      // Cerrar polígono si es necesario
-      if (polygon[0][0] !== polygon[polygon.length-1][0]) {
-        polygon.push(polygon[0]);
-      }
+  async sendLocation(deviceId, lat, lng) {
+    if (!deviceId || lat === undefined || lng === undefined) {
+      throw new Error("GeoEngine: deviceId, lat y lng son obligatorios.");
+    }
 
-      const payload = {
-        name,
-        webhook_url: webhookUrl,
-        geojson: {
-          type: 'Polygon',
-          coordinates: [polygon]
-        }
-      };
+    const payload = {
+      device_id: deviceId,
+      latitude: parseFloat(lat),
+      longitude: parseFloat(lng),
+      timestamp: Math.floor(Date.now() / 1000)
+    };
 
-      const res = await this.client.post(`${this.config.managementUrl}/geofences`, payload);
-      return res.data;
-    } catch (error) {
-      this._handleError(error);
-    }
+    return this._request(`${this.config.ingestUrl}/ingest`, 'POST', payload);
   }
 
-  _handleError(error) {
-    if (error.response) {
-      throw new Error(`GeoEngine API Error: ${error.response.status} - ${JSON.stringify(error.response.data)}`);
+  /**
+   * Crea una nueva geocerca.
+   */
+  async createGeofence(name, coordinates, webhookUrl) {
+    if (!name || !coordinates || coordinates.length < 3) {
+      throw new Error("GeoEngine: Se requiere un nombre y al menos 3 coordenadas.");
+    }
+
+    // Convertir formato simple [[lat,lng]] a GeoJSON [Lng, Lat]
+    const polygon = coordinates.map(p => [p[1], p[0]]);
+
+    // Cerrar polígono automáticamente
+    const first = polygon[0];
+    const last = polygon[polygon.length - 1];
+    if (first[0] !== last[0] || first[1] !== last[1]) {
+      polygon.push(first);
     }
-    throw error;
+
+    const payload = {
+      name,
+      webhook_url: webhookUrl,
+      geojson: {
+        type: 'Polygon',
+        coordinates: [polygon]
+      }
+    };
+
+    return this._request(`${this.config.managementUrl}/geofences`, 'POST', payload);
   }
 }
 

package/package.json

@@ -1,9 +1,25 @@
 {
-    "name": "geo-engine-node",
-    "version": "1.0.0",
-    "description": "SDK Oficial para Geo-Engine",
-    "main": "index.js",
-    "dependencies": {
-      "axios": "^1.6.0"
-    }
-  }
+  "name": "geo-engine-node",
+  "version": "1.1.0",
+  "type": "module",
+  "description": "SDK oficial para Geo-Engine. Rastreo de activos y gestión de geocercas.",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "example": "node examples/simulation.js",
+    "release:patch": "npm version patch && npm publish --access public",
+    "release:minor": "npm version minor && npm publish --access public"
+  },
+  "keywords": [
+    "geofencing",
+    "location",
+    "tracking",
+    "sdk"
+  ],
+  "author": "Geo-Engine Team",
+  "license": "MIT",
+  "dependencies": {},
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}