@honua/app-platform 0.0.20-alpha.0

package/core/wms-types.js

@@ -0,0 +1,32 @@
+/**
+ * Public request/response envelopes for the WMS / WMTS first-party
+ * adapter. Kept in their own module so the canonical SDK surface
+ * (`src/contract/index.ts`, `src/runtime/index.ts`, `src/index.ts`) can
+ * re-export them without dragging the runtime classes into trees that
+ * never reference WMS.
+ *
+ * @module
+ */
+// ── WMTS wire-format helpers ──────────────────────────────────
+/**
+ * Canonical mapping from WMTS `Format` MIME types to RESTful path
+ * extensions. Shared between the wire client (`getWmtsTile` /
+ * `featureInfo` URL builders in `src/core/client.ts`) and the MapLibre
+ * raster source helper (`buildWmtsRasterSourceSpec` in
+ * `src/runtime/source-bridge.ts`) so a caller-supplied `format` lands on
+ * the same extension regardless of which surface composes the URL.
+ *
+ * The map is intentionally narrow — formats not listed here fall back
+ * to `png` per the conservative WMTS default. Add a new entry only when
+ * honua-server adds first-party support for the encoding.
+ */
+const WMTS_TILE_FORMAT_TO_EXTENSION = new Map([
+    ["image/png", "png"],
+    ["image/jpeg", "jpeg"],
+    ["image/jpg", "jpeg"],
+    ["image/webp", "webp"],
+]);
+/** Resolve the RESTful path extension for a WMTS tile `Format` MIME type. */
+export function wmtsExtensionForFormat(format) {
+    return WMTS_TILE_FORMAT_TO_EXTENSION.get(format.toLowerCase()) ?? "png";
+}

package/core/wms.d.ts

@@ -0,0 +1,144 @@
+/**
+ * First-party WMS 1.3.0 adapter. `HonuaWms` is the service-level handle
+ * returned by `client.wms(serviceId)`; `HonuaWmsLayer` is the bound
+ * handle returned by `HonuaWms.layer(name)` that pre-fills the LAYER and
+ * default STYLE so per-call envelopes can drop the routing fields.
+ *
+ * Wire transport lives on `HonuaClient` (`getWmsCapabilities`,
+ * `getWmsMap`, `getWmsFeatureInfo`, `getWmsLegend`); this class is the
+ * typed surface consumers reach through `Source.protocol("wms")`.
+ *
+ * @module
+ */
+import type { HonuaClient } from "./client.js";
+import type { HonuaProtocolTransport } from "./protocol-transport.js";
+import type { WmsCapabilities, WmsCapabilityLayer, WmsCapabilityStyle } from "./wms-capabilities.js";
+import type { HonuaWmsFeatureInfoResponse, HonuaWmsImageResponse, WmsFeatureInfoRequest, WmsLegendRequest, WmsMapRequest } from "./wms-types.js";
+export interface HonuaWmsOptions {
+    client: HonuaClient;
+    serviceId: string;
+}
+/**
+ * Split a WMS `LAYERS=` value (or `locator.typeName` / `spec.layers` of
+ * the same shape) into the list of non-empty trimmed layer tokens. Used
+ * by the contract WMS adapter and shared style resolver so the
+ * single-layer handle rule stays in one place.
+ */
+export declare function parseWmsLayerNames(value: string | undefined): readonly string[];
+export interface HonuaWmsLayerOptions extends HonuaWmsOptions {
+    /** WMS LAYER name (single layer; multi-layer renders use the parent handle). */
+    layerName: string;
+    /** Default STYLE for renders / feature-info on this layer. */
+    defaultStyleId?: string;
+}
+/**
+ * Service-level WMS handle. Use `layer(name)` to bind a single LAYER and
+ * style; for multi-layer composites (`LAYERS=a,b,c`) call `map()` /
+ * `featureInfo()` directly on this handle.
+ */
+export declare class HonuaWms {
+    readonly client: HonuaClient;
+    readonly serviceId: string;
+    private capabilitiesPromise;
+    constructor(options: HonuaWmsOptions);
+    /** Bind a single named layer for layer-scoped requests. */
+    layer(name: string, defaultStyleId?: string): HonuaWmsLayer;
+    /** Fetch and parse the service `GetCapabilities` document. */
+    capabilities(options?: {
+        signal?: AbortSignal;
+    }): Promise<WmsCapabilities>;
+    /** Render a `GetMap` request across one or more advertised layers. */
+    map(request: WmsMapRequest): Promise<HonuaWmsImageResponse>;
+    /** Issue a `GetFeatureInfo` against one or more advertised layers. */
+    featureInfo<T = Record<string, unknown>>(request: WmsFeatureInfoRequest): Promise<HonuaWmsFeatureInfoResponse<T>>;
+    /**
+     * Fetch a `GetLegendGraphic` image. Always gates on parsed Capabilities:
+     * when the caller does not pre-supply `options.capabilities`, the handle
+     * lazily loads them once via `getWmsCapabilities` and caches the
+     * promise on the instance so repeat calls reuse the same fetch. Throws
+     * `HonuaCapabilityNotSupportedError("legend", "wms", serviceId)` when
+     * the service does not advertise `<GetLegendGraphic>`.
+     */
+    legend(request: WmsLegendRequest, options?: {
+        capabilities?: WmsCapabilities;
+    }): Promise<HonuaWmsImageResponse>;
+    private loadCachedCapabilities;
+}
+/**
+ * Bound layer handle. Drops `layers` / `styles` from per-call requests
+ * and pre-fills the LAYER name. `featureInfo()` carries the same `i`,
+ * `j`, and `bbox` envelope as the service-level handle.
+ */
+export declare class HonuaWmsLayer {
+    readonly client: HonuaClient;
+    readonly serviceId: string;
+    readonly layerName: string;
+    readonly defaultStyleId: string | undefined;
+    private capabilitiesPromise;
+    constructor(options: HonuaWmsLayerOptions);
+    /** Fetch the parent service's `GetCapabilities`. */
+    capabilities(options?: {
+        signal?: AbortSignal;
+    }): Promise<WmsCapabilities>;
+    /** Find this layer in a parsed Capabilities document. */
+    describe(capabilities: WmsCapabilities): WmsCapabilityLayer | undefined;
+    /** Enumerate the styles advertised on this layer. */
+    stylesIn(capabilities: WmsCapabilities): readonly WmsCapabilityStyle[];
+    map(request: Omit<WmsMapRequest, "layers" | "styles"> & {
+        style?: string;
+    }): Promise<HonuaWmsImageResponse>;
+    featureInfo<T = Record<string, unknown>>(request: Omit<WmsFeatureInfoRequest, "layers" | "queryLayers" | "styles"> & {
+        style?: string;
+    }): Promise<HonuaWmsFeatureInfoResponse<T>>;
+    /**
+     * Fetch a `GetLegendGraphic` image scoped to the bound layer + style.
+     * Mirrors `HonuaWms.legend`'s gating: when `options.capabilities` is
+     * not supplied, the handle lazily loads them once via
+     * `getWmsCapabilities` and caches the promise. Throws
+     * `HonuaCapabilityNotSupportedError("legend", "wms", serviceId)` when
+     * the service does not advertise `<GetLegendGraphic>`.
+     */
+    legend(request?: Omit<WmsLegendRequest, "layer" | "style"> & {
+        style?: string;
+    }, options?: {
+        capabilities?: WmsCapabilities;
+    }): Promise<HonuaWmsImageResponse>;
+    private loadCachedCapabilities;
+}
+export declare function createHonuaWms(client: HonuaClient, serviceId: string): HonuaWms;
+/**
+ * Fetch and parse a WMS `GetCapabilities` document for the addressed
+ * service. The XML body decodes through `requestText`; the parsed
+ * shape is the typed `WmsCapabilities` envelope (no XML node leaks
+ * through the public surface).
+ */
+export declare function getWmsCapabilities(transport: HonuaProtocolTransport, request: {
+    serviceId: string;
+    version?: string;
+    signal?: AbortSignal;
+    extraParams?: Record<string, string | number | boolean>;
+}): Promise<WmsCapabilities>;
+/** Render a WMS `GetMap`. Returns the raw image bytes. */
+export declare function getWmsMap(transport: HonuaProtocolTransport, request: {
+    serviceId: string;
+} & WmsMapRequest): Promise<HonuaWmsImageResponse>;
+/**
+ * Issue a WMS `GetFeatureInfo`. When `INFO_FORMAT=application/json`
+ * the JSON body decodes into the canonical `HonuaTypedFeature[]`
+ * shape; non-JSON formats round-trip on `bytes` so callers retain the
+ * raw payload behind the protocol escape hatch.
+ */
+export declare function getWmsFeatureInfo<T = Record<string, unknown>>(transport: HonuaProtocolTransport, request: {
+    serviceId: string;
+} & WmsFeatureInfoRequest): Promise<HonuaWmsFeatureInfoResponse<T>>;
+/**
+ * Fetch a WMS `GetLegendGraphic`. honua-server does not implement
+ * GetLegendGraphic today; callers should branch on
+ * `WmsCapabilities.request.getLegendGraphic` before invoking. When
+ * the wire returns 5xx the underlying `HonuaHttpError` flows through.
+ */
+export declare function getWmsLegend(transport: HonuaProtocolTransport, request: {
+    serviceId: string;
+} & WmsLegendRequest): Promise<HonuaWmsImageResponse>;
+export declare function decodeWmsFeatureInfoResponse<T>(bytes: Uint8Array, contentType: string, requestedFormat: string): HonuaWmsFeatureInfoResponse<T>;
+//# sourceMappingURL=wms.d.ts.map

package/core/wms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wms.d.ts","sourceRoot":"","sources":["../../../src/core/wms.ts"],"names":[],"mappings":"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"}

package/core/wms.js

@@ -0,0 +1,338 @@
+/**
+ * First-party WMS 1.3.0 adapter. `HonuaWms` is the service-level handle
+ * returned by `client.wms(serviceId)`; `HonuaWmsLayer` is the bound
+ * handle returned by `HonuaWms.layer(name)` that pre-fills the LAYER and
+ * default STYLE so per-call envelopes can drop the routing fields.
+ *
+ * Wire transport lives on `HonuaClient` (`getWmsCapabilities`,
+ * `getWmsMap`, `getWmsFeatureInfo`, `getWmsLegend`); this class is the
+ * typed surface consumers reach through `Source.protocol("wms")`.
+ *
+ * @module
+ */
+import { HonuaCapabilityNotSupportedError } from "./errors.js";
+import { encodeServiceIdPath } from "./path-utils.js";
+import { wmsBboxRequiresAxisSwap } from "./wms-axis.js";
+import { findWmsLayer, parseWmsCapabilities } from "./wms-capabilities.js";
+/**
+ * Split a WMS `LAYERS=` value (or `locator.typeName` / `spec.layers` of
+ * the same shape) into the list of non-empty trimmed layer tokens. Used
+ * by the contract WMS adapter and shared style resolver so the
+ * single-layer handle rule stays in one place.
+ */
+export function parseWmsLayerNames(value) {
+    if (typeof value !== "string" || value.length === 0)
+        return [];
+    return value
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/**
+ * Service-level WMS handle. Use `layer(name)` to bind a single LAYER and
+ * style; for multi-layer composites (`LAYERS=a,b,c`) call `map()` /
+ * `featureInfo()` directly on this handle.
+ */
+export class HonuaWms {
+    client;
+    serviceId;
+    capabilitiesPromise;
+    constructor(options) {
+        this.client = options.client;
+        this.serviceId = options.serviceId;
+    }
+    /** Bind a single named layer for layer-scoped requests. */
+    layer(name, defaultStyleId) {
+        const opts = {
+            client: this.client,
+            serviceId: this.serviceId,
+            layerName: name,
+        };
+        if (defaultStyleId !== undefined)
+            opts.defaultStyleId = defaultStyleId;
+        return new HonuaWmsLayer(opts);
+    }
+    /** Fetch and parse the service `GetCapabilities` document. */
+    async capabilities(options) {
+        return this.client.getWmsCapabilities({
+            serviceId: this.serviceId,
+            ...(options?.signal ? { signal: options.signal } : {}),
+        });
+    }
+    /** Render a `GetMap` request across one or more advertised layers. */
+    async map(request) {
+        return this.client.getWmsMap({ serviceId: this.serviceId, ...request });
+    }
+    /** Issue a `GetFeatureInfo` against one or more advertised layers. */
+    async featureInfo(request) {
+        return this.client.getWmsFeatureInfo({ serviceId: this.serviceId, ...request });
+    }
+    /**
+     * Fetch a `GetLegendGraphic` image. Always gates on parsed Capabilities:
+     * when the caller does not pre-supply `options.capabilities`, the handle
+     * lazily loads them once via `getWmsCapabilities` and caches the
+     * promise on the instance so repeat calls reuse the same fetch. Throws
+     * `HonuaCapabilityNotSupportedError("legend", "wms", serviceId)` when
+     * the service does not advertise `<GetLegendGraphic>`.
+     */
+    async legend(request, options) {
+        const caps = options?.capabilities ?? (await this.loadCachedCapabilities());
+        if (!caps.request.getLegendGraphic) {
+            throw new HonuaCapabilityNotSupportedError("legend", "wms", this.serviceId);
+        }
+        return this.client.getWmsLegend({ serviceId: this.serviceId, ...request });
+    }
+    async loadCachedCapabilities() {
+        if (!this.capabilitiesPromise) {
+            this.capabilitiesPromise = this.capabilities().catch((error) => {
+                // Drop the cached promise on failure so the next call retries
+                // instead of permanently surfacing the same error.
+                this.capabilitiesPromise = undefined;
+                throw error;
+            });
+        }
+        return this.capabilitiesPromise;
+    }
+}
+/**
+ * Bound layer handle. Drops `layers` / `styles` from per-call requests
+ * and pre-fills the LAYER name. `featureInfo()` carries the same `i`,
+ * `j`, and `bbox` envelope as the service-level handle.
+ */
+export class HonuaWmsLayer {
+    client;
+    serviceId;
+    layerName;
+    defaultStyleId;
+    capabilitiesPromise;
+    constructor(options) {
+        this.client = options.client;
+        this.serviceId = options.serviceId;
+        this.layerName = options.layerName;
+        this.defaultStyleId = options.defaultStyleId;
+    }
+    /** Fetch the parent service's `GetCapabilities`. */
+    async capabilities(options) {
+        return this.client.getWmsCapabilities({
+            serviceId: this.serviceId,
+            ...(options?.signal ? { signal: options.signal } : {}),
+        });
+    }
+    /** Find this layer in a parsed Capabilities document. */
+    describe(capabilities) {
+        return findWmsLayer(capabilities, this.layerName);
+    }
+    /** Enumerate the styles advertised on this layer. */
+    stylesIn(capabilities) {
+        return this.describe(capabilities)?.styles ?? [];
+    }
+    async map(request) {
+        const { style, ...rest } = request;
+        const styleId = style ?? this.defaultStyleId;
+        return this.client.getWmsMap({
+            serviceId: this.serviceId,
+            layers: [this.layerName],
+            ...(styleId !== undefined ? { styles: [styleId] } : {}),
+            ...rest,
+        });
+    }
+    async featureInfo(request) {
+        const { style, ...rest } = request;
+        const styleId = style ?? this.defaultStyleId;
+        return this.client.getWmsFeatureInfo({
+            serviceId: this.serviceId,
+            layers: [this.layerName],
+            queryLayers: [this.layerName],
+            ...(styleId !== undefined ? { styles: [styleId] } : {}),
+            ...rest,
+        });
+    }
+    /**
+     * Fetch a `GetLegendGraphic` image scoped to the bound layer + style.
+     * Mirrors `HonuaWms.legend`'s gating: when `options.capabilities` is
+     * not supplied, the handle lazily loads them once via
+     * `getWmsCapabilities` and caches the promise. Throws
+     * `HonuaCapabilityNotSupportedError("legend", "wms", serviceId)` when
+     * the service does not advertise `<GetLegendGraphic>`.
+     */
+    async legend(request = {}, options) {
+        const caps = options?.capabilities ?? (await this.loadCachedCapabilities());
+        if (!caps.request.getLegendGraphic) {
+            throw new HonuaCapabilityNotSupportedError("legend", "wms", this.serviceId);
+        }
+        const { style, ...rest } = request;
+        const styleId = style ?? this.defaultStyleId;
+        return this.client.getWmsLegend({
+            serviceId: this.serviceId,
+            layer: this.layerName,
+            ...(styleId !== undefined ? { style: styleId } : {}),
+            ...rest,
+        });
+    }
+    async loadCachedCapabilities() {
+        if (!this.capabilitiesPromise) {
+            this.capabilitiesPromise = this.capabilities().catch((error) => {
+                this.capabilitiesPromise = undefined;
+                throw error;
+            });
+        }
+        return this.capabilitiesPromise;
+    }
+}
+export function createHonuaWms(client, serviceId) {
+    return new HonuaWms({ client, serviceId });
+}
+// ── WMS 1.3 wire methods ────────────────────────────────────────
+/** Canonical WMS endpoint path. honua-server publishes both `/rest/services/{id}/MapServer/WMS` and `/ogc/services/{id}/wms`; the SDK targets the GeoServices-aliased path because every Honua deployment exposes it. */
+function wmsBasePath(serviceId) {
+    return `/rest/services/${encodeServiceIdPath(serviceId)}/MapServer/WMS`;
+}
+/**
+ * Fetch and parse a WMS `GetCapabilities` document for the addressed
+ * service. The XML body decodes through `requestText`; the parsed
+ * shape is the typed `WmsCapabilities` envelope (no XML node leaks
+ * through the public surface).
+ */
+export async function getWmsCapabilities(transport, request) {
+    const params = new URLSearchParams();
+    params.set("SERVICE", "WMS");
+    params.set("REQUEST", "GetCapabilities");
+    params.set("VERSION", request.version ?? "1.3.0");
+    if (request.extraParams) {
+        for (const [key, value] of Object.entries(request.extraParams)) {
+            params.set(key, String(value));
+        }
+    }
+    const path = `${wmsBasePath(request.serviceId)}?${params.toString()}`;
+    const { text: xml } = await transport.requestText("GET", path, {
+        accept: "text/xml,application/xml",
+        signal: request.signal,
+    });
+    return parseWmsCapabilities(xml);
+}
+/** Render a WMS `GetMap`. Returns the raw image bytes. */
+export async function getWmsMap(transport, request) {
+    const params = serializeWmsMapParams(request);
+    params.set("REQUEST", "GetMap");
+    const path = `${wmsBasePath(request.serviceId)}?${params.toString()}`;
+    const accept = request.format ?? "image/png";
+    const response = await transport.requestBytes("GET", path, accept, undefined, request.signal);
+    return { bytes: response.bytes, contentType: response.contentType };
+}
+/**
+ * Issue a WMS `GetFeatureInfo`. When `INFO_FORMAT=application/json`
+ * the JSON body decodes into the canonical `HonuaTypedFeature[]`
+ * shape; non-JSON formats round-trip on `bytes` so callers retain the
+ * raw payload behind the protocol escape hatch.
+ */
+export async function getWmsFeatureInfo(transport, request) {
+    const params = serializeWmsMapParams(request);
+    params.set("REQUEST", "GetFeatureInfo");
+    params.set("QUERY_LAYERS", request.queryLayers.join(","));
+    params.set("I", String(Math.trunc(request.i)));
+    params.set("J", String(Math.trunc(request.j)));
+    const infoFormat = request.infoFormat ?? "application/json";
+    params.set("INFO_FORMAT", infoFormat);
+    if (request.featureCount !== undefined) {
+        params.set("FEATURE_COUNT", String(Math.trunc(request.featureCount)));
+    }
+    const path = `${wmsBasePath(request.serviceId)}?${params.toString()}`;
+    const response = await transport.requestBytes("GET", path, infoFormat, undefined, request.signal);
+    return decodeWmsFeatureInfoResponse(response.bytes, response.contentType, infoFormat);
+}
+/**
+ * Fetch a WMS `GetLegendGraphic`. honua-server does not implement
+ * GetLegendGraphic today; callers should branch on
+ * `WmsCapabilities.request.getLegendGraphic` before invoking. When
+ * the wire returns 5xx the underlying `HonuaHttpError` flows through.
+ */
+export async function getWmsLegend(transport, request) {
+    const params = new URLSearchParams();
+    params.set("SERVICE", "WMS");
+    params.set("VERSION", "1.3.0");
+    params.set("REQUEST", "GetLegendGraphic");
+    params.set("LAYER", request.layer);
+    if (request.style)
+        params.set("STYLE", request.style);
+    const format = request.format ?? "image/png";
+    params.set("FORMAT", format);
+    if (request.width !== undefined)
+        params.set("WIDTH", String(Math.trunc(request.width)));
+    if (request.height !== undefined)
+        params.set("HEIGHT", String(Math.trunc(request.height)));
+    if (request.extraParams) {
+        for (const [key, value] of Object.entries(request.extraParams)) {
+            params.set(key, String(value));
+        }
+    }
+    const path = `${wmsBasePath(request.serviceId)}?${params.toString()}`;
+    const response = await transport.requestBytes("GET", path, format, undefined, request.signal);
+    return { bytes: response.bytes, contentType: response.contentType };
+}
+function serializeWmsMapParams(request) {
+    const params = new URLSearchParams();
+    params.set("SERVICE", "WMS");
+    params.set("VERSION", "1.3.0");
+    params.set("LAYERS", request.layers.join(","));
+    params.set("STYLES", request.styles ? request.styles.join(",") : "");
+    const crs = request.crs ?? "EPSG:3857";
+    params.set("CRS", crs);
+    const [minx, miny, maxx, maxy] = request.bbox;
+    const wireBbox = wmsBboxRequiresAxisSwap(crs) ? [miny, minx, maxy, maxx] : [minx, miny, maxx, maxy];
+    params.set("BBOX", wireBbox.join(","));
+    params.set("WIDTH", String(Math.trunc(request.width)));
+    params.set("HEIGHT", String(Math.trunc(request.height)));
+    params.set("FORMAT", request.format ?? "image/png");
+    params.set("TRANSPARENT", String(request.transparent ?? true).toUpperCase());
+    if (request.bgcolor !== undefined)
+        params.set("BGCOLOR", request.bgcolor);
+    if (request.time !== undefined)
+        params.set("TIME", request.time);
+    if (request.elevation !== undefined)
+        params.set("ELEVATION", request.elevation);
+    if (request.extraParams) {
+        for (const [key, value] of Object.entries(request.extraParams)) {
+            params.set(key, String(value));
+        }
+    }
+    return params;
+}
+export function decodeWmsFeatureInfoResponse(bytes, contentType, requestedFormat) {
+    const isJson = contentType.toLowerCase().includes("application/json") ||
+        requestedFormat.toLowerCase().includes("application/json");
+    if (!isJson) {
+        return { contentType, bytes };
+    }
+    const text = new TextDecoder("utf-8").decode(bytes);
+    if (text.length === 0) {
+        return { contentType, features: [] };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        // Server emitted a non-JSON body despite the JSON Accept; preserve as bytes.
+        return { contentType, bytes };
+    }
+    const features = extractFeatureInfoFeatures(parsed);
+    return { contentType, features };
+}
+function extractFeatureInfoFeatures(parsed) {
+    if (!parsed || typeof parsed !== "object")
+        return [];
+    // honua-server emits `{ type: "FeatureInfoResponse", features: [{ layer, attributes }, ...] }`
+    // and a fallback GeoJSON `{ type: "FeatureCollection", features: [...] }`; both decode here.
+    const obj = parsed;
+    const featuresRaw = Array.isArray(obj.features) ? obj.features : [];
+    const out = [];
+    for (const raw of featuresRaw) {
+        if (!raw || typeof raw !== "object")
+            continue;
+        const feat = raw;
+        const attributes = (feat.attributes ?? feat.properties ?? {});
+        const geometry = feat.geometry ?? null;
+        out.push({ attributes, geometry });
+    }
+    return out;
+}

package/core/wmts-capabilities.d.ts

@@ -0,0 +1,82 @@
+/**
+ * WMTS 1.0.0 Capabilities parser. Hand-rolled, narrow-scope walker over
+ * the `Capabilities` document advertised by honua-server (single
+ * advertised TileMatrixSet today: `WebMercatorQuad`). Yields a typed
+ * `WmtsCapabilities` shape so the SDK can route through the canonical
+ * `Source` surface without leaking XML.
+ *
+ * @module
+ */
+/**
+ * Top-level WMTS Capabilities surface.
+ */
+export interface WmtsCapabilities {
+    /** Protocol version. honua-server advertises `1.0.0`. */
+    version: string;
+    service: WmtsCapabilitiesService;
+    layers: ReadonlyArray<WmtsCapabilityLayer>;
+    tileMatrixSets: ReadonlyArray<WmtsCapabilityTileMatrixSet>;
+}
+export interface WmtsCapabilitiesService {
+    title?: string;
+    abstract?: string;
+}
+export interface WmtsCapabilityLayer {
+    identifier: string;
+    title?: string;
+    abstract?: string;
+    formats: readonly string[];
+    styles: ReadonlyArray<WmtsCapabilityStyle>;
+    /** TileMatrixSet identifiers the layer supports. */
+    tileMatrixSetIds: readonly string[];
+    /** RESTful tile templates (xlink:href) advertised by `ResourceURL@resourceType="tile"`. */
+    resourceTemplates: ReadonlyArray<WmtsCapabilityResourceUrl>;
+    /** RESTful FeatureInfo templates advertised by `ResourceURL@resourceType="FeatureInfo"`. */
+    featureInfoTemplates: ReadonlyArray<WmtsCapabilityResourceUrl>;
+    /** Geographic bounding box (WGS84) when advertised. */
+    bbox?: {
+        west: number;
+        south: number;
+        east: number;
+        north: number;
+    };
+}
+export interface WmtsCapabilityStyle {
+    identifier: string;
+    title?: string;
+    isDefault: boolean;
+    legendUrl?: string;
+}
+export interface WmtsCapabilityResourceUrl {
+    format: string;
+    template: string;
+}
+export interface WmtsCapabilityTileMatrixSet {
+    identifier: string;
+    /** CRS supportedCRS or wellKnownScaleSet href when advertised. */
+    supportedCrs?: string;
+    wellKnownScaleSet?: string;
+    matrices: ReadonlyArray<WmtsCapabilityTileMatrix>;
+}
+export interface WmtsCapabilityTileMatrix {
+    identifier: string;
+    scaleDenominator: number;
+    matrixWidth: number;
+    matrixHeight: number;
+    tileWidth: number;
+    tileHeight: number;
+    topLeftCorner: readonly [number, number];
+}
+export declare class HonuaWmtsCapabilitiesParseError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse a `Capabilities` text body for WMTS 1.0 into the typed
+ * `WmtsCapabilities` shape.
+ */
+export declare function parseWmtsCapabilities(xml: string): WmtsCapabilities;
+/** Find a layer by identifier in a parsed `WmtsCapabilities`. */
+export declare function findWmtsLayer(capabilities: WmtsCapabilities, identifier: string): WmtsCapabilityLayer | undefined;
+/** Find a tile-matrix-set by identifier. */
+export declare function findWmtsTileMatrixSet(capabilities: WmtsCapabilities, identifier: string): WmtsCapabilityTileMatrixSet | undefined;
+//# sourceMappingURL=wmts-capabilities.d.ts.map

package/core/wmts-capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wmts-capabilities.d.ts","sourceRoot":"","sources":["../../../src/core/wmts-capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,uBAAuB,CAAC;IACjC,MAAM,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;IAC3C,cAAc,EAAE,aAAa,CAAC,2BAA2B,CAAC,CAAC;CAC5D;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,MAAM,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;IAC3C,oDAAoD;IACpD,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,2FAA2F;IAC3F,iBAAiB,EAAE,aAAa,CAAC,yBAAyB,CAAC,CAAC;IAC5D,4FAA4F;IAC5F,oBAAoB,EAAE,aAAa,CAAC,yBAAyB,CAAC,CAAC;IAC/D,uDAAuD;IACvD,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACrE;AAED,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,2BAA2B;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,aAAa,CAAC,wBAAwB,CAAC,CAAC;CACnD;AAED,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C;AAED,qBAAa,+BAAgC,SAAQ,KAAK;gBACrC,OAAO,EAAE,MAAM;CAInC;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAcnE;AAgWD,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAEjH;AAED,4CAA4C;AAC5C,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,gBAAgB,EAC9B,UAAU,EAAE,MAAM,GACjB,2BAA2B,GAAG,SAAS,CAEzC"}