zenit-sdk 0.0.1

package/README.md

@@ -0,0 +1,279 @@
+# zenit-sdk
+
+## Introducción
+`zenit-sdk` es una librería en TypeScript para consumir el backend de Zenit de forma sencilla. El core es agnóstico al framework y se enfoca en ofrecer clientes HTTP y helpers de autenticación. Además, incluye un componente React (`ZenitMap`) para integraciones de UI basado en Leaflet.
+
+## Instalación
+```bash
+npm install zenit-sdk
+# o con yarn
+yarn add zenit-sdk
+```
+
+Para usar el componente React instala también sus peer dependencies en tu proyecto:
+```bash
+npm install react react-dom leaflet react-leaflet
+# o con yarn
+yarn add react react-dom leaflet react-leaflet
+```
+
+## Entradas del SDK
+- **Core (Node/HTTP)**: `import { ZenitClient } from 'zenit-sdk';`
+- **React (UI)**: `import { ZenitMap } from 'zenit-sdk/react';`
+
+### Uso básico – Cliente de usuario (core)
+```ts
+import { ZenitClient } from 'zenit-sdk';
+
+const client = new ZenitClient({
+  baseUrl: 'https://mi-zenit.com/api/v1'
+});
+
+async function demo() {
+  const login = await client.auth.login({
+    email: '<EMAIL>',
+    password: '<PASSWORD>'
+  });
+
+  console.log('User:', login.user);
+
+  const me = await client.auth.me();
+  console.log('Me:', me);
+
+  const valid = await client.auth.validate();
+  console.log('Validate:', valid);
+
+  const refreshed = await client.auth.refresh(login.refreshToken);
+  console.log('Refresh:', refreshed);
+}
+```
+
+### Uso básico – SDK Token (core)
+```ts
+import { ZenitClient } from 'zenit-sdk';
+
+const client = new ZenitClient({
+  baseUrl: 'https://mi-zenit.com/api/v1',
+  sdkToken: '<SDK_TOKEN>'
+});
+
+async function demoSdk() {
+  const validation = await client.sdkAuth.validateSdkToken();
+  console.log('SDK token validation:', validation);
+
+  const exchange = await client.sdkAuth.exchangeSdkToken();
+  console.log('SDK exchange:', exchange);
+
+  const me = await client.auth.me();
+  console.log('Me using SDK access token:', me);
+}
+```
+
+### Uso básico – Componente React `ZenitMap`
+```tsx
+import React from 'react';
+import { ZenitClient } from 'zenit-sdk';
+import { ZenitMap } from 'zenit-sdk/react';
+import 'leaflet/dist/leaflet.css';
+
+const client = new ZenitClient({
+  baseUrl: 'https://mi-zenit.com/api/v1',
+  sdkToken: '<SDK_TOKEN>'
+});
+
+export function App() {
+  return (
+    <div>
+      <h1>Demo ZenitMap</h1>
+      <ZenitMap client={client} mapId={123} />
+    </div>
+  );
+}
+```
+Si las capas del mapa incluyen `layer.label`, ZenitMap mostrará marcadores de etiqueta usando esa propiedad de las
+features (respeta visibilidad y opacidad de la capa).
+
+### Chat flotante `FloatingChatBox` (Zenit AI)
+El SDK incluye un chat flotante para conversar con Zenit AI usando los endpoints de mapas. Solo necesitas entregar
+`baseUrl` y `mapId` (el token es opcional, pero se puede inyectar con `accessToken` o `getAccessToken`).
+
+```tsx
+import React from 'react';
+import { FloatingChatBox } from 'zenit-sdk/react';
+
+export function App() {
+  return (
+    <>
+      <FloatingChatBox
+        baseUrl="https://mi-zenit.com/api/v1"
+        mapId={123}
+        filteredLayerIds={[45, 98]}
+        filters={{ CODREGION: 10 }}
+        getAccessToken={() => localStorage.getItem('access_token') ?? ''}
+      />
+    </>
+  );
+}
+```
+
+El chat funciona también en modo guest (`userId` nulo/omitido). Si no hay `mapId`, el componente muestra un estado
+deshabilitado con el mensaje “Selecciona un mapa para usar el asistente”.
+
+### Panel reutilizable de capas y filtros `ZenitLayerManager`
+El SDK incluye un panel listo para usar que administra visibilidad, opacidad y filtros por propiedades usando los endpoints `getLayerFeaturesCatalog` y `filter-multiple`. Puedes combinarlo con `ZenitMap` para mostrar el GeoJSON filtrado como overlay:
+
+```tsx
+import React, { useState } from 'react';
+import { ZenitClient, type FilterMultipleMetadata, type GeoJsonFeatureCollection } from 'zenit-sdk';
+import { ZenitLayerManager, ZenitMap } from 'zenit-sdk/react';
+import 'leaflet/dist/leaflet.css';
+
+const client = new ZenitClient({ baseUrl: 'https://mi-zenit.com/api/v1', sdkToken: '<SDK_TOKEN>' });
+
+export function App() {
+  const [overlay, setOverlay] = useState<GeoJsonFeatureCollection | null>(null);
+  const [metadata, setMetadata] = useState<FilterMultipleMetadata | undefined>();
+  const [layerControls, setLayerControls] = useState<
+    Array<{ layerId: number | string; visible: boolean; opacity: number }>
+  >([]);
+
+  return (
+    <div style={{ display: 'flex', height: 600 }}>
+      <ZenitLayerManager
+        client={client}
+        mapId={11}
+        onFilteredGeojson={(geojson, meta) => {
+          setOverlay(geojson);
+          setMetadata(meta);
+        }}
+        onLayerStatesChange={setLayerControls}
+      />
+      <ZenitMap
+        client={client}
+        mapId={11}
+        showLayerPanel={false}
+        overlayGeojson={overlay}
+        layerControls={layerControls}
+      />
+      <pre>{JSON.stringify(metadata, null, 2)}</pre>
+    </div>
+  );
+}
+```
+
+### API de mapas y capas (core)
+```ts
+import { ZenitClient, getCatalogSupport, ZenitCatalogNotSupportedError } from 'zenit-sdk';
+
+const client = new ZenitClient({ baseUrl: 'https://mi-zenit.com/api/v1', accessToken: '<JWT>' });
+
+// Metadatos de mapa (incluye capas visibles si includeLayers=true)
+const map = await client.maps.getMap(11, true);
+
+// Metadatos de capa (las respuestas usan ApiResponse con `data` y metadata opcional)
+const layer = await client.layers.getLayer(123);
+console.log('Layer:', layer.data);
+
+// GeoJSON completo
+const geojson = await client.layers.getLayerGeoJson(123);
+console.log('GeoJSON features:', geojson.data.features?.length ?? 0);
+
+// GeoJSON limitado por bounding box
+const geojsonBBox = await client.layers.getLayerGeoJsonBBox({
+  id: 123,
+  bbox: {
+    minLon: -58.6,
+    minLat: -34.7,
+    maxLon: -58.3,
+    maxLat: -34.4,
+  },
+});
+console.log('GeoJSON bbox features:', geojsonBBox.data.features?.length ?? 0);
+
+// Intersección con una geometría
+const intersected = await client.layers.getLayerGeoJsonIntersect({ id: 123, geometry, maxFeatures: 5000 });
+console.log('GeoJSON intersected features:', intersected.data.features?.length ?? 0);
+
+// Catálogo de propiedades de features de una capa
+const catalog = await client.layers.getLayerFeaturesCatalog(17);
+console.log('Catalogo de capa', catalog.data);
+
+// Catálogo con validación previa
+const support = getCatalogSupport({ layerType: 'polygon' });
+if (support.supported) {
+  const safeCatalog = await client.layers.getLayerFeaturesCatalog(17, {
+    layerType: 'polygon',
+    strict: true, // fail-fast sin request si la geometría no está soportada
+  });
+  console.log('Catálogo soportado', safeCatalog.data);
+}
+
+// Filtrado simultáneo en múltiples capas multipolygon
+const filtered = await client.layers.filterMultipleLayersFeatures({
+  layerIds: [32, 17],
+  filters: { CODREGION: 10 },
+});
+console.log('filter-multiple data', filtered.data);
+
+// Filtrado resiliente con capas mixtas (multipolygon + otras)
+const mixedFiltered = await client.layers.filterMultipleWithFallback({
+  layerIds: [32, 17, 99],
+  filters: { CODREGION: 10 },
+  layerMetas: [
+    { layerId: 32, layerType: 'multipolygon' },
+    { layerId: 17, layerType: 'polygon' },
+    { layerId: 99, layerType: 'mixed' },
+  ],
+});
+console.log('filter-multiple fallback perLayer', mixedFiltered.perLayer);
+
+// Helper de alto nivel
+const loaded = await client.layers.loadFilteredFeatures({
+  layerIds: [32, 17],
+  filters: { CODREGION: 10 },
+});
+console.log('GeoJSON filtrado', loaded.geojson.features.length, 'elementos');
+```
+
+El endpoint de catálogo solo admite capas `polygon`/`multipolygon`. Usa `getCatalogSupport` para decidir si corresponde
+llamarlo, o pasa `{ strict: true }` a `getLayerFeaturesCatalog` para que el SDK arroje un `ZenitCatalogNotSupportedError`
+antes de hacer la request.
+
+Los métodos expuestos en `client.layers` permiten construir el panel de filtros sin dependencias externas:
+- `getLayerFeaturesCatalog(layerId)` carga el catálogo de propiedades para cada capa.
+- `filterMultipleLayersFeatures({ layerIds, filters })` ejecuta `filter-multiple` y retorna GeoJSON + metadata.
+- `loadFilteredFeatures` es un helper tipado que entrega `geojson`, `metadata` y `totalFeatures` listos para usar.
+
+Notas de filtrado:
+
+- `layerIds` se envía como CSV (`[32,17]` -> `layerIds=32,17`).
+- Los filtros son pares dinámicos `key/value`. Valores en arreglos se serializan como `a,b,c`.
+- Valores `null`/`undefined` o cadenas vacías no se envían en la query.
+
+## Ejecutar ejemplos con `.env` opcional
+Los ejemplos usan `ts-node` y leen variables de entorno. Puedes definirlas en tu shell o en un archivo `.env` (no se publica):
+
+```env
+ZENIT_BASE_URL=http://localhost:3200/api/v1
+ZENIT_EMAIL=<EMAIL>
+ZENIT_PASSWORD=<PASSWORD>
+ZENIT_SDK_TOKEN=<SDK_TOKEN>
+ZENIT_ACCESS_TOKEN=<ACCESS_TOKEN>
+ZENIT_MAP_ID=11
+```
+
+En PowerShell:
+```powershell
+$env:ZENIT_BASE_URL="http://localhost:3200/api/v1"
+$env:ZENIT_EMAIL="user@example.com"
+$env:ZENIT_PASSWORD="secret"
+```
+
+Comandos disponibles:
+```bash
+npm run example:auth
+npm run example:sdk
+npm run example:map
+```
+
+El `baseUrl` por defecto de los ejemplos es `http://localhost:3200/api/v1` si no se especifica.