convez.ai
MCP Server
honua-io

honua-sdk-js

honua-io/honua-sdk-js

Ver no GitHub
InicialPluginScore · de 0 a 100

JavaScript SDKs for Honua (core SDK + MCP server).

Instalação

$npx convez-ai honua-io/honua-sdk-js

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
6
Forks
1
Acompanhando
0
Saúde
62%
Último commit
há 1 dia
Versão
mcp-server-v0.6.1
Issues abertas
88
Contribuidores
8

README

A tradução para o português deste README ainda está na fila.

Honua JS SDK

OpenSSF Scorecard

npm types license node

One geospatial client for GeoServices, OGC APIs, WMS/WMTS/WFS, STAC, and OData — with first-class TypeScript, a MapLibre runtime, and a drop-in ArcGIS migration path.

@honua/sdk-js is the JavaScript / TypeScript client for the Honua geospatial platform. It speaks the open protocols your data already uses (Esri GeoServices, OGC API Features / Tiles / Maps / Processes, STAC, WMS, WMTS, WFS 2.0, OData v4), exposes a single protocol-neutral Dataset → Source → Query → Result contract on top of them, and ships a MapLibre-first map runtime plus an Esri compatibility layer so existing ArcGIS apps can migrate file-by-file.

  • Protocol-neutral. One Source.query(...) call works against GeoServices, OGC, WFS, OData and friends. Capability misses throw HonuaCapabilityNotSupportedError instead of returning empty results.
  • TypeScript first. strict + verbatimModuleSyntax, exported types for every public symbol, declaration maps, and JSDoc on the public client surface.
  • Migrate, don't rewrite. FeatureLayerCompat, MapImageLayerCompat, MapViewCompat, SceneViewCompat, WebMapCompat, and a safe codemod (honua-migrate) keep existing ArcGIS code running while you cut over.
  • Open runtime. loadMapPackage(...) + HonuaMapRuntime render a Honua MapPackage on MapLibre GL JS. Cesium, kepler.gl, and OGC web-map sources are first-class.

When to reach for @honua/sdk-js. Pick this SDK when you need one typed client across the GeoServices / OGC / WFS / WMS / STAC / OData stack, an ArcGIS migration path you can run file-by-file, or a MapLibre runtime that loads a server-authored MapPackage. Pick esri-leaflet / arcgis-rest-js when you only ever talk to GeoServices; pick openlayers / maplibre-gl directly when you're not migrating from ArcGIS and don't need a shared cross-protocol contract.

npm install @honua/sdk-js

Build-less / CDN usage

For static sites, prototypes, or CSP-strict pages that can't run a bundler, a prebuilt browser bundle is published under dist/browser/. Drop in the minified IIFE build and use the global window.HonuaSDK:

<script src="https://cdn.jsdelivr.net/npm/@honua/sdk-js/dist/browser/honua-sdk.min.js"></script>
<script>
  const client = new HonuaSDK.HonuaClient({ baseUrl: "https://your-honua-server.example" });
  // window.HonuaSDK exposes the same public API as `import ... from "@honua/sdk-js"`.
</script>

Or, for native ES module imports via an ESM CDN:

<script type="module">
  import { HonuaClient } from "https://esm.sh/@honua/sdk-js/browser";
  const client = new HonuaClient({ baseUrl: "https://your-honua-server.example" });
</script>

The runtime peers (maplibre-gl, cesium, @bufbuild/*, @connectrpc/*) are kept external — load them yourself when you need map rendering or gRPC transport. See docs/browser-bundle.md for details.

60-second quickstart

The canonical surface is protocol-neutral: build a Dataset over one or more Sources, then call queryAll() (or query() / stream()). The same code works against GeoServices, OGC API Features, WFS, OData, and STAC.

import { createDataset, PROTOCOL_DEFAULT_CAPABILITIES } from "@honua/sdk-js/contract";
import { HonuaClient } from "@honua/sdk-js/honua";

const client = new HonuaClient({ baseUrl: "https://your-honua-server.example" });

const dataset = createDataset({
  id: "parcels",
  client,
  sources: [
    {
      id: "parcels-fs",
      protocol: "geoservices-feature-service",
      locator: { url: "https://your-honua-server.example", serviceId: "parcels", layerId: 0 },
      capabilities: PROTOCOL_DEFAULT_CAPABILITIES["geoservices-feature-service"],
    },
  ],
});

const parcels = dataset.source("parcels-fs")!;
const result = await parcels.queryAll({
  where: "STATUS = 'ACTIVE'",
  outFields: ["OBJECTID", "NAME"],
  returnGeometry: true,
  pagination: { limit: 500 },
});

console.log(`Loaded ${result.features.length} features`);

Prefer the raw GeoServices shape (e.g. for an ArcGIS migration)? HonuaClient still ships the protocol-specific call as a typed escape hatch:

const { features } = await client.queryFeatures({
  serviceId: "natural-earth",
  layerId: 0,
  where: "1=1",
  outFields: ["*"],
  returnGeometry: true,
  resultRecordCount: 25,
});

For production code, gate on client.checkCompatibility() so the SDK fails loudly when the server is older than the SDK's tested floor:

const { supported, reasons } = await client.checkCompatibility();
if (!supported) throw new Error(`Unsupported Honua server: ${reasons.join("; ")}`);

Want to run a complete app locally? Clone this repo and:

npm install
npm run demo:quickstart:mock   # serves examples/maplibre-quickstart against a deterministic fixture

The demo:quickstart:mock script prints quickstartMockUrl=http://127.0.0.1:PORT; open that URL to see the same code rendering live on MapLibre.

See docs/quickstart.md for the guided walkthrough, docs/quickstart-troubleshooting.md for common failure modes, and examples/maplibre-quickstart/ for the committed source.

What you can build

DemoWhat it shows
maplibre-quickstartMapLibre map + Honua FeatureServer query + popup inspection
storytelling-25d-map2.5D MapLibre storytelling, OGC overlays, route replay
kepler-analyticskepler.gl analytics replay over fixture GeoJSON + KPIs
imagery-cog-quickstartWMS GetMap, COG ImageServer tiles, exportImage previews
spatial-analytics-workbenchHonua Cloud AOI jobs + linked map/table/chart workbench
edit-workflow-demoOptimistic create/update/delete with conflicts & attachments
geocoding-quickstartForward / reverse / typeahead via HonuaGeocodingClient
terrain-rgb-elevationTerrain-RGB DEM tiles, point elevation, profile lookup
unified-ops-workspaceComposed incident-command + analysis workspace shell
cesium-route-playbackCesium 3D route playback over one bounded Honua query

Each example documents its own env surface, mock + live lanes, browser telemetry hooks, and Playwright smoke coverage. The 10 above are the flagship walkthroughs; another 11 runnable demos cover specialized workflows:

DemoWhat it shows
service-explorerCatalog/service browse + linked-view explore over fixtures
migration-workbenchInteractive Esri → Honua migration with honua-migrate
ai-spatial-app-builderLLM-driven spatial app builder using agent-tools
mcp-gis-assistantMCP server exposing Honua tools to assistants
runtime-parity-showcaseParity matrix demo across MapLibre / kepler / Cesium runtimes
realtime-incident-dashboardSSE-backed realtime ops dashboard
geoprocessing-job-runnerAsync GP job submit / poll / cancel
stac-imagery-browserSTAC search + COG preview
node-backend-quickstartServer-side Honua client (Node)
app-bootstrap-basicMinimal @honua/sdk-js/app bootstrap helper
web-components-basicCustom-element gallery
arcgis-source-appDrop-in ArcGIS migration target

Mental model: Dataset → Source → Query → Result

Every Honua SDK — JavaScript, Python, .NET — speaks the same canonical vocabulary. A Dataset groups one or more Sources. Each Source accepts a protocol-neutral Query and returns a protocol-neutral Result. Operations the canonical surface does not cover stay reachable through the typed source.protocol(...) escape hatch. Method casing differs by language (queryAll() / query_all() / QueryAllAsync()), the semantics do not.

Capability misses throw HonuaCapabilityNotSupportedError (under the default strict policy) rather than silently returning empty results. See the 60-second quickstart above for the runnable shape; the cross-language semantics, protocol/capability identifiers, language-binding tables, and backwards-compatibility policy live in:

Documentation

Stability and versioning

  • The SDK follows Semantic Versioning. The public contract is the set of symbols reachable from the documented subpath entrypoints in INSTALL.md.
  • Symbols marked @experimental in JSDoc may change in any minor release. The full table of stable and experimental subpaths lives in INSTALL.md. The short version:
    • Stable (semver-protected): @honua/sdk-js, @honua/sdk-js/honua, @honua/sdk-js/contract, @honua/sdk-js/esri-compat, @honua/sdk-js/migration, @honua/sdk-js/runtime, @honua/sdk-js/expr, @honua/sdk-js/webmap, @honua/sdk-js/geocoding, @honua/sdk-js/exploration, @honua/sdk-js/interactions, @honua/sdk-js/filter-registry, @honua/sdk-js/style, @honua/sdk-js/map.
    • Experimental (subpath-only — not re-exported from the root barrels): /app, /app-controller, /app-workspace, /scene-workspace, /collaboration, /control-plane, /controls, /generated-app, /studio, /agent-tools, /realtime, /web-components, /operator, /operator/*.

More guides

Long-form reference material now lives in docs/guide.md:

  • Demo apps in depth (each example's env contract, browser hooks, run lanes)
  • Server compatibility baseline + checkCompatibility() contract
  • Subpath entrypoints and the @experimental tier
  • Protocol cookbooks — OGC Features / Tiles / Maps / Processes / STAC, WMS / WMTS, WFS 2.0, OData v4
  • Mixed Esri + OGC composition, streaming pagination, event lifecycle
  • MapLibre MapPackage runtime + Generated App preview runtime
  • Request/Auth bridge (interceptors, ArcGIS token + esri-request interop)
  • honua-migrate CLI, admin scanner, parity matrix, sample-corpus harness

Protocol-specific deep dives also live alongside the guide: see docs/wfs.md, docs/ogc-api.md, docs/maplibre-runtime.md, docs/webmap-json-compatibility.md, docs/protocol-capability-matrix.md, and docs/migration-punch-list.md.

Contributing

This SDK ships from a single repository. The shipping package is @honua/sdk-js; all subpath entrypoints in INSTALL.md live under that name. See AGENTS.md for contributor instructions and the Specifica issue format used for backlog items.

License

Apache 2.0

Ver o original no GitHub

Bom para

Relacionados