@lucqait/sdk-geodata-service

Cliente TypeScript tipado para el backend ms-geo-data-service de LUCQA. Cliente HTTP, hooks React Query y helpers GIS.

Estado: bootstrap inicial (Sprint 1 SCRUM-150). El cliente core está listo, los hooks React y los parsers GIS se completan en sprints siguientes.

Instalación

# .npmrc en tu proyecto consumidor
@lucqa-it:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GHCR_TOKEN}

# GHCR_TOKEN es un Personal Access Token (classic) con scope `read:packages`
# perteneciente a un usuario autorizado en la org lucqa-it. Usamos GHCR_TOKEN
# en lugar del GITHUB_TOKEN automatico de Actions porque GitHub limita el
# acceso del token efimero a paquetes privados cross-repo.

pnpm add @lucqait/sdk-geodata-service

Uso

Core (sin React)

import { createClient, EntityNotFoundError } from "@lucqait/sdk-geodata-service";

const client = createClient({
  baseUrl: "https://api.lucqa.com",
  getToken: () => localStorage.getItem("jwt"),
  getSchema: () => "tenant_demo",
  onUnauthorized: () => { window.location.href = "/login"; },
});

try {
  const { data } = await client.raw.GET("/api/v1/{tenant}/regions", {
    params: { path: { tenant: "tenant_demo" } },
  });
  console.log(data);
} catch (err) {
  if (err instanceof EntityNotFoundError) {
    // ... manejo tipado
  }
}

React (con hooks)

import { LucqaProvider } from "@lucqait/sdk-geodata-service/react";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

const qc = new QueryClient();

export function App() {
  return (
    <QueryClientProvider client={qc}>
      <LucqaProvider
        baseUrl="https://api.lucqa.com"
        getToken={() => localStorage.getItem("jwt")}
        getSchema={() => "tenant_demo"}
      >
        <YourApp />
      </LucqaProvider>
    </QueryClientProvider>
  );
}

GIS

import { haversine, lineLength } from "@lucqait/sdk-geodata-service/gis";

const distMeters = haversine(-12.046, -77.043, -13.531, -71.967);
const cableLength = lineLength([
  [-77.043, -12.046],
  [-77.0, -12.0],
]);

Subpath exports

| Import path | Contenido | |---|---| | @lucqait/sdk-geodata-service | createClient(), errores tipados (EntityNotFoundError, etc.), helpers HTTP. Sin React. | | @lucqait/sdk-geodata-service/react | <LucqaProvider/>, hooks (en sprints siguientes), WebSocket NOC. | | @lucqait/sdk-geodata-service/gis | Helpers de geometría (Haversine, longitud de línea), futuros parsers KMZ/SOR. |

Desarrollo local

# Clonar y entrar al repo
cd D:/lucqa-deno/sdk-geodata-service
pnpm install

# Generar tipos desde el backend en local (requiere ms-geo-data-service corriendo en :8081)
OPENAPI_URL=http://localhost:8081/v3/api-docs pnpm gen

# Build dual ESM/CJS
pnpm build

# Tests
pnpm test
pnpm test:watch

# Lint y typecheck
pnpm lint
pnpm typecheck

Versionado

Usamos changesets. En cada PR que cambie comportamiento:

pnpm changeset
# describe el cambio, marca major/minor/patch
git add .changeset/
git commit -m "chore: changeset"

Al mergear PRs a main, el bot abre un "Version Packages" PR; al mergear ese PR se publica automáticamente a GitHub Packages.

Documentación

• docs/ARCHITECTURE.md — decisiones arquitectónicas.
• docs/PUBLISHING.md — flujo de publicación.
• docs/CONSUMING.md — guía para integradores B2B.

Licencia

Propietario — LUCQA IT.