@geomatika/isigeo_http_api

SDK JavaScript/TypeScript pour communiquer avec les API Isigéo (authentification + accès aux données). Compatible navigateur, Node.js et Cordova.

Installation

Depuis npm

npm install @geomatika/isigeo_http_api

Depuis une source locale (avant publication)

cd http_api
npm run build
npm link
cd /path/to/your/project
npm link @geomatika/isigeo_http_api

Formats disponibles

Le SDK est livré sous plusieurs formats pour s'adapter à tous les contextes :

| Format | Fichier | Usage typique | | ------ | -------------------------------- | ---------------------------------------------------- | | ESM | dist/isigeo_http_api.es.js | Applications Vite / Web modernes | | CJS | dist/isigeo_http_api.cjs.js | Node.js ou outils CommonJS | | IIFE | dist/isigeo_http_api.iife.js | Cordova ou HTML classique (window.IsigeoHttpApi) |

Fonctionnalités

• Authentification
  • par username/password
  • par token permanent
  • gestion automatique du JWT
• Accès aux données (CRUD)
  • lecture (getData) avec pagination (page, limit, offset), colonnes (fields), filtres (eq., like., ilike.…), tri (sortBy), conditions OR (or), filtre spatial (stDistance), Geo-Format (geojson / wkt) et Geo-SRID
  • création (createData, POST)
  • mise à jour (updateData, PUT) avec filtre
  • suppression (deleteData, DELETE) avec filtre
• Configuration admin/expert (deftables, userMod)
  • CRUD sur les tables de configuration deftables et user_mod, réservé aux profils admin / expert (403 sinon)
  • méthodes list (GET), create (POST), update (PUT), remove (DELETE)
  • écriture de toutes les colonnes sauf les colonnes auto-générées (PK serial, ex. id) ; validation de type côté serveur (entier, numérique, tableau PostgreSQL, longueur des varchar) → 400 propre. Les varchar(1) servant de flags n'acceptent que Y/N ('' et null = non renseigné) ; les rares varchar(1) non-booléennes (ex. deftables.style_symbol = T/F/P) ne subissent que le contrôle de longueur
  • chaque appel (lecture comprise) est tracé côté serveur
• Compatible navigateur / Cordova (WebView), Node.js 18+, TypeScript

Utilisation

Exemple complet (ESM)

import { IsigeoApi } from "@geomatika/isigeo_http_api";

const api = new IsigeoApi({
  baseUrl: "https://deploiement.geomatika.fr",
  version: 1,
});

const { token } = await api.auth.authWithPassword("admin", "••••••");

const supports = await api.data.getData(token, "ep_support", {
  page: 1,
  geoFormat: "geojson",
});

console.log("Résultats:", supports);

Authentification

const { token, expires } = await api.auth.authWithPassword("admin", "••••••");
console.log("JWT:", token);
console.log("Expire:", new Date(expires * 1000).toLocaleString());

Ou via token permanent :

const { token } = await api.auth.authWithToken("TOKEN_PERMANENT_GENERE_PAR_ISIGEO");

Requêtes data

Pagination

const rows = await api.data.getData(token, "ep_support", {
  page: 1,
  geoFormat: "geojson",
});

Limit / offset

const rows = await api.data.getData(token, "ep_support", {
  limit: 10,
  offset: 0,
});

Colonnes spécifiques

const rows = await api.data.getData(token, "chiffrage_client_travaux", {
  columns: ["date_obs", "photo1", "photo2", "typ_desor", "obs"],
});

Filtres

const rows = await api.data.getData(token, "support", {
  filter: { idsup: "eq.18294" },
});

Opérateurs supportés (côté serveur) : eq, ne, gt, ge, lt, le, like, ilike, is, isnot, any. Plusieurs filtres se combinent en AND. Pour is/isnot, la valeur attendue est null (ex: { date_pose: "is.null" }).

Tri (sortBy)

Le serveur ne trie que sur une seule colonne. Sans dir, le tri est ascendant.

const rows = await api.data.getData(token, "ep_armoire", {
  sortBy: { field: "nom", dir: "desc" }, // → sort_by=nom.desc
});

Conditions OR (or)

Combine plusieurs conditions en OR (sérialisé en or=(col.op.val,...)).

const rows = await api.data.getData(token, "ep_armoire", {
  or: [
    { column: "secteur", operator: "eq", value: "A" },
    { column: "secteur", operator: "eq", value: "B" },
  ], // → or=(secteur.eq.A,secteur.eq.B)
});

Filtre spatial (stDistance)

lon/lat en EPSG:4326. Avec distance, ne retourne que les objets situés à moins de distance (unité du SRID interne de la table) ; sans distance, ajoute simplement la distance calculée dans la réponse sans filtrer.

// objets à moins de 500 m du point
const rows = await api.data.getData(token, "ep_armoire", {
  stDistance: { lon: 2.35, lat: 48.85, distance: 500 },
});

SRID / format

const rows = await api.data.getData(token, "ep_support", {
  geoFormat: "wkt",
  geoSrid: 2154,
});

Création (POST)

const created = await api.data.createData(token, "support", {
  ref_support: "SUP-001",
  nature_du_support: "Candélabres",
  idnature_du_support: "5",
});

Mise à jour (PUT)

await api.data.updateData(
  token,
  "support",
  { nature_du_support: "Poteau bois", idnature_du_support: "2" },
  { filter: { idsup: "eq.18294" } }
);

Suppression (DELETE)

const res = await api.data.deleteData(token, "support", {
  filter: { idsup: "eq.18294" },
});
// { status: 200, message: "Deleted ( support.18294 )" }

Configuration admin/expert (deftables, userMod)

Accès CRUD aux tables de configuration deftables (définition des tables/couches) et user_mod (droits par utilisateur/table). Réservé aux profils admin / expert côté serveur, et chaque appel — lecture comprise — est tracé.

// Consultation (colonnes réelles de deftables : id, nom, mcd, base, ws_data…)
const tables = await api.deftables.list(token, {
  columns: ["id", "nom", "mcd", "ws_data"],
  filter: { mcd: "eq.urba" },
  sortBy: { field: "nom", dir: "asc" },
  limit: 50,
});

// Droits d'un utilisateur sur une table
const droits = await api.userMod.list(token, {
  filter: { id_table: "eq.42", id_user: "eq.7" },
});

// Modification (le filtre est REQUIS et cible la ligne, le body porte les champs)
await api.userMod.update(token, { consult: "Y", write: "N" }, {
  filter: { id_table: "eq.42", id_user: "eq.7" },
});

// Création (pas de filtre : la ligne est dans le body)
await api.deftables.create(token, { nom: "ma_couche", mcd: "urba", base: "urba", ws_data: "N" });

// Suppression (filtre requis)
await api.userMod.remove(token, {
  filter: { id_table: "eq.42", id_user: "eq.7" },
});

Filtre requis / opération multi-lignes. update et remove exigent un filter non vide (le client lève une erreur sinon, sans appel réseau). Si le filtre touche plusieurs lignes, le serveur répond 400 ; il faut alors confirmer explicitement avec bulk: true. Un filtre ne ciblant aucune ligne répond 404.

await api.deftables.update(token, { ws_data: "Y" }, {
  filter: { mcd: "eq.urba" }, // plusieurs couches
  bulk: true,                 // opt-in multi-lignes → sérialisé bulk=true
});

Formes de réponse (différentes de data — pas d'enveloppe { data }) :

| Méthode | Réponse | |---|---| | list | tableau JSON nu des lignes ([{…}, …]) | | create | 201 + la ligne créée (au moins sa clé primaire) | | update | { status: 200, updated: <n> } | | remove | { status: 200, message: "…" } |

Format de réponse (lecture)

Les appels getData retournent l'enveloppe renvoyée par le serveur :

{
  "metadata": { "total": 1, "sent": 1, "range": { "start": 1, "end": 1 } },
  "data": [ /* lignes */ ]
}

Utilisation dans Cordova

1. Ajouter au npmFileToImport.json

{
  "@geomatika/isigeo_http_api": [
    {
      "from": ["dist", "isigeo_http_api.iife.js"],
      "to": ["js", "extras", "isigeo", "isigeo-http-api.js"]
    }
  ]
}

2. Inclure dans index.html

<script src="js/extras/isigeo/isigeo-http-api.js"></script>
<script>
  document.addEventListener("deviceready", async () => {
    const { IsigeoApi } = window.IsigeoHttpApi;

    const api = new IsigeoApi({
      baseUrl: "https://deploiement.geomatika.fr",
      version: 1,
    });

    const { token } = await api.auth.authWithPassword("admin", "•••••");
    const supports = await api.data.getData(token, "ep_support", { page: 1 });
    console.log(supports);
  });
</script>

window.IsigeoHttpApi est automatiquement défini par le bundle IIFE.

Types TypeScript

Les méthodes sont typées. Tu peux typer les retours pour tes données :

interface Support {
  idsup: number;
  geom: any;
}

const rows = await api.data.getData<Support[]>(token, "support", {
  page: 1,
});

Tests

Tests unitaires (mock fetch, pas de réseau) :

npm test

Tests d'intégration (round-trip réel insert → get → update → get → delete → get contre une instance Isigéo). Skippés automatiquement si les variables ci-dessous ne sont pas définies.

Configuration via .env (recommandé) : copier .env.example en .env (gitignoré) et renseigner les valeurs.

cp .env.example .env
# éditer .env puis :
npm run test:integration

Ou en inline :

ISIGEO_TEST_URL="https://deploiement.geomatika.fr/dev6" \
ISIGEO_TEST_USER="monuser" \
ISIGEO_TEST_PASSWORD="monpass" \
ISIGEO_TEST_TABLE="support" \
npm run test:integration

ISIGEO_TEST_TABLE est optionnel (défaut : support). L'utilisateur doit avoir les droits POST/PUT/DELETE sur la table — chaque run crée puis supprime une ligne marquée ref_support = "npmtest-<timestamp>".

Les scripts scripts/test-auth.js et scripts/test-data.js consomment les mêmes variables d'environnement et ne contiennent aucun secret. Le fichier .env est automatiquement chargé via dotenv.

Build local

# Compilation TS + bundle Vite
npm run build

Produit :

dist/
├── isigeo_http_api.cjs.js
├── isigeo_http_api.es.js
├── isigeo_http_api.iife.js
└── index.d.ts

Publication npm

npm login
npm version patch
npm publish --access public

Vérifie le contenu publié :

npm pack

Exemple d'intégration dans Vite + Cordova

// src/lib/isigeo.ts
import { IsigeoApi } from "@geomatika/isigeo_http_api";

export const isigeo = new IsigeoApi({
  baseUrl: import.meta.env.VITE_ISIGEO_URL,
  version: Number(import.meta.env.VITE_ISIGEO_VERSION ?? 1),
});