honua-sdk-js
honua-io/honua-sdk-js
JavaScript SDKs for Honua (core SDK + MCP server).
Instalação
npx convez-ai honua-io/honua-sdk-js1 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
README
A tradução para o português deste README ainda está na fila.
Honua JS SDK
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 throwHonuaCapabilityNotSupportedErrorinstead 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(...)+HonuaMapRuntimerender a HonuaMapPackageon 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-authoredMapPackage. Pickesri-leaflet/arcgis-rest-jswhen you only ever talk to GeoServices; pickopenlayers/maplibre-gldirectly 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
| Demo | What it shows |
|---|---|
maplibre-quickstart | MapLibre map + Honua FeatureServer query + popup inspection |
storytelling-25d-map | 2.5D MapLibre storytelling, OGC overlays, route replay |
kepler-analytics | kepler.gl analytics replay over fixture GeoJSON + KPIs |
imagery-cog-quickstart | WMS GetMap, COG ImageServer tiles, exportImage previews |
spatial-analytics-workbench | Honua Cloud AOI jobs + linked map/table/chart workbench |
edit-workflow-demo | Optimistic create/update/delete with conflicts & attachments |
geocoding-quickstart | Forward / reverse / typeahead via HonuaGeocodingClient |
terrain-rgb-elevation | Terrain-RGB DEM tiles, point elevation, profile lookup |
unified-ops-workspace | Composed incident-command + analysis workspace shell |
cesium-route-playback | Cesium 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:
| Demo | What it shows |
|---|---|
service-explorer | Catalog/service browse + linked-view explore over fixtures |
migration-workbench | Interactive Esri → Honua migration with honua-migrate |
ai-spatial-app-builder | LLM-driven spatial app builder using agent-tools |
mcp-gis-assistant | MCP server exposing Honua tools to assistants |
runtime-parity-showcase | Parity matrix demo across MapLibre / kepler / Cesium runtimes |
realtime-incident-dashboard | SSE-backed realtime ops dashboard |
geoprocessing-job-runner | Async GP job submit / poll / cancel |
stac-imagery-browser | STAC search + COG preview |
node-backend-quickstart | Server-side Honua client (Node) |
app-bootstrap-basic | Minimal @honua/sdk-js/app bootstrap helper |
web-components-basic | Custom-element gallery |
arcgis-source-app | Drop-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:
docs/sdk-surface-alignment.md— cross-language naming + semverdocs/shared-client-contract.md— contract designdocs/protocol-capability-matrix.md— what each protocol supports
Documentation
docs/quickstart.md— guided quickstart walkthroughdocs/guide.md— long-form reference (server compatibility, subpath entrypoints, OGC / WFS / OData cookbooks, MapLibre runtime, migration CLI, request/auth bridge)docs/errors.md— error class reference + retry policydocs/shared-client-contract.md—Dataset/Source/Query/Resultdesigndocs/protocol-capability-matrix.md— what each protocol supportsdocs/sdk-surface-alignment.md— cross-language naming & semver policydocs/maplibre-runtime.md—loadMapPackage()/HonuaMapRuntimedocs/studio-package-contracts.md— Studio package-family projections, validation envelope, capability manifest (@honua/sdk-js/studio)docs/features/README.md— capability snapshotINSTALL.md— install + subpath entrypoint table
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
@experimentalin JSDoc may change in any minor release. The full table of stable and experimental subpaths lives inINSTALL.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/*.
- Stable (semver-protected):
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
@experimentaltier - Protocol cookbooks — OGC Features / Tiles / Maps / Processes / STAC, WMS / WMTS, WFS 2.0, OData v4
- Mixed Esri + OGC composition, streaming pagination, event lifecycle
- MapLibre
MapPackageruntime + Generated App preview runtime - Request/Auth bridge (interceptors, ArcGIS token + esri-request interop)
honua-migrateCLI, 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.