@honua/app-platform 0.0.20-alpha.0

package/core/ogc-records.d.ts

@@ -0,0 +1,75 @@
+/**
+ * OGC API Records surface. Records are catalog metadata documents about
+ * resources (services, collections, maps, scenes, STAC collections, source
+ * descriptors), not STAC imagery items and not protocol-native service
+ * metadata. The wire calls live on `HonuaClient`; this class is the
+ * request-shaping layer on top.
+ *
+ * @module
+ */
+import type { HonuaClient } from "./client.js";
+import type { HonuaProtocolTransport } from "./protocol-transport.js";
+import type { HonuaOgcCollectionMetadata, HonuaOgcCollectionsResponse, HonuaOgcConformanceResponse, HonuaOgcLandingResponse, HonuaOgcRecordResponse, HonuaOgcRecordsResponse, OgcCollectionRequest, OgcMetadataRequest, OgcRecordItemRequest, OgcRecordRawItemRequest, OgcRecordsRawSearchRequest, OgcRecordsSearchRequest } from "./types.js";
+export interface HonuaOgcRecordsOptions {
+    client: HonuaClient;
+}
+export interface HonuaOgcRecordCollectionOptions {
+    client: HonuaClient;
+    collectionId: string | number;
+}
+export interface HonuaOgcRecordsSearchAllRequest extends OgcRecordsSearchRequest {
+    /** Maximum number of records to request per page. */
+    pageSize?: number;
+    /** Hard cap on the number of pages to fetch (defaults to 100). */
+    maxPages?: number;
+}
+export type HonuaOgcRecordCollectionSearchRequest = Omit<OgcRecordsSearchRequest, "collectionId">;
+export type HonuaOgcRecordCollectionSearchAllRequest = HonuaOgcRecordCollectionSearchRequest & {
+    pageSize?: number;
+    maxPages?: number;
+};
+export type HonuaOgcRecordCollectionItemRequest = Omit<OgcRecordItemRequest, "collectionId">;
+export type HonuaOgcRecordCollectionRawSearchRequest = Omit<OgcRecordsRawSearchRequest, "collectionId">;
+export type HonuaOgcRecordCollectionRawItemRequest = Omit<OgcRecordRawItemRequest, "collectionId">;
+/** Top-level OGC API Records handle. */
+export declare class HonuaOgcRecords {
+    readonly client: HonuaClient;
+    constructor(options: HonuaOgcRecordsOptions);
+    collection(collectionId: string | number): HonuaOgcRecordCollection;
+    landing(request?: OgcMetadataRequest): Promise<HonuaOgcLandingResponse>;
+    conformance(request?: OgcMetadataRequest): Promise<HonuaOgcConformanceResponse>;
+    collections(request?: OgcMetadataRequest): Promise<HonuaOgcCollectionsResponse>;
+    collectionMetadata(request: OgcCollectionRequest): Promise<HonuaOgcCollectionMetadata>;
+    search(request: OgcRecordsSearchRequest): Promise<HonuaOgcRecordsResponse>;
+    record(request: OgcRecordItemRequest): Promise<HonuaOgcRecordResponse>;
+    rawSearch(request: OgcRecordsRawSearchRequest): Promise<Response>;
+    rawRecord(request: OgcRecordRawItemRequest): Promise<Response>;
+    searchAll(request: HonuaOgcRecordsSearchAllRequest): Promise<HonuaOgcRecordResponse[]>;
+    searchStream(request: HonuaOgcRecordsSearchAllRequest): AsyncGenerator<HonuaOgcRecordResponse[], void, undefined>;
+}
+/**
+ * Bound handle for one Records catalog (`/collections/{catalogId}`). Drops
+ * the routing discriminator from per-call requests.
+ */
+export declare class HonuaOgcRecordCollection {
+    readonly client: HonuaClient;
+    readonly collectionId: string | number;
+    constructor(options: HonuaOgcRecordCollectionOptions);
+    metadata(request?: OgcMetadataRequest): Promise<HonuaOgcCollectionMetadata>;
+    search(request?: HonuaOgcRecordCollectionSearchRequest): Promise<HonuaOgcRecordsResponse>;
+    record(request: HonuaOgcRecordCollectionItemRequest): Promise<HonuaOgcRecordResponse>;
+    rawSearch(request?: HonuaOgcRecordCollectionRawSearchRequest): Promise<Response>;
+    rawRecord(request: HonuaOgcRecordCollectionRawItemRequest): Promise<Response>;
+    searchAll(request?: HonuaOgcRecordCollectionSearchAllRequest): Promise<HonuaOgcRecordResponse[]>;
+    searchStream(request?: HonuaOgcRecordCollectionSearchAllRequest): AsyncGenerator<HonuaOgcRecordResponse[], void, undefined>;
+}
+export declare function createHonuaOgcRecords(client: HonuaClient): HonuaOgcRecords;
+export declare function getOgcRecordsLanding(transport: HonuaProtocolTransport, request?: OgcMetadataRequest): Promise<HonuaOgcLandingResponse>;
+export declare function getOgcRecordsConformance(transport: HonuaProtocolTransport, request?: OgcMetadataRequest): Promise<HonuaOgcConformanceResponse>;
+export declare function listOgcRecordCollections(transport: HonuaProtocolTransport, request?: OgcMetadataRequest): Promise<HonuaOgcCollectionsResponse>;
+export declare function getOgcRecordCollection(transport: HonuaProtocolTransport, request: OgcCollectionRequest): Promise<HonuaOgcCollectionMetadata>;
+export declare function searchOgcRecords(transport: HonuaProtocolTransport, request: OgcRecordsSearchRequest): Promise<HonuaOgcRecordsResponse>;
+export declare function getOgcRecord(transport: HonuaProtocolTransport, request: OgcRecordItemRequest): Promise<HonuaOgcRecordResponse>;
+export declare function fetchOgcRecordsRaw(transport: HonuaProtocolTransport, request: OgcRecordsRawSearchRequest): Promise<Response>;
+export declare function fetchOgcRecordRaw(transport: HonuaProtocolTransport, request: OgcRecordRawItemRequest): Promise<Response>;
+//# sourceMappingURL=ogc-records.d.ts.map

package/core/ogc-records.d.ts.map

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

package/core/ogc-records.js

@@ -0,0 +1,251 @@
+/**
+ * OGC API Records surface. Records are catalog metadata documents about
+ * resources (services, collections, maps, scenes, STAC collections, source
+ * descriptors), not STAC imagery items and not protocol-native service
+ * metadata. The wire calls live on `HonuaClient`; this class is the
+ * request-shaping layer on top.
+ *
+ * @module
+ */
+import { createOgcMetadataParams, mergeHeaders, normalizeCsv, normalizeStringCsv } from "./wire-shared.js";
+const DEFAULT_RECORDS_PAGE_SIZE = 100;
+const DEFAULT_RECORDS_MAX_PAGES = 100;
+/** Top-level OGC API Records handle. */
+export class HonuaOgcRecords {
+    client;
+    constructor(options) {
+        this.client = options.client;
+    }
+    collection(collectionId) {
+        return new HonuaOgcRecordCollection({ client: this.client, collectionId });
+    }
+    async landing(request = {}) {
+        return this.client.getOgcRecordsLanding(request);
+    }
+    async conformance(request = {}) {
+        return this.client.getOgcRecordsConformance(request);
+    }
+    async collections(request = {}) {
+        return this.client.listOgcRecordCollections(request);
+    }
+    async collectionMetadata(request) {
+        return this.client.getOgcRecordCollection(request);
+    }
+    async search(request) {
+        return this.client.searchOgcRecords(request);
+    }
+    async record(request) {
+        return this.client.getOgcRecord(request);
+    }
+    async rawSearch(request) {
+        return this.client.fetchOgcRecordsRaw(request);
+    }
+    async rawRecord(request) {
+        return this.client.fetchOgcRecordRaw(request);
+    }
+    async searchAll(request) {
+        const pageSize = request.pageSize ?? request.limit ?? DEFAULT_RECORDS_PAGE_SIZE;
+        const maxPages = request.maxPages ?? DEFAULT_RECORDS_MAX_PAGES;
+        const records = [];
+        let cursor = { offset: request.offset };
+        for (let page = 0; page < maxPages; page += 1) {
+            const response = await this.client.searchOgcRecords({
+                ...request,
+                limit: pageSize,
+                offset: cursor.offset,
+            });
+            const pageRecords = response.features ?? [];
+            if (pageRecords.length === 0)
+                break;
+            records.push(...pageRecords);
+            cursor = nextRecordsCursor(response.links);
+            // Continuation is driven solely by the next-link cursor (and the
+            // maxPages cap). OGC API Records/Features permits a server to return
+            // fewer than `limit` records on a non-final page while still
+            // advertising a `rel=next` link, so a short page must not stop paging.
+            if (cursor.offset === undefined)
+                break;
+        }
+        return records;
+    }
+    async *searchStream(request) {
+        const pageSize = request.pageSize ?? request.limit ?? DEFAULT_RECORDS_PAGE_SIZE;
+        const maxPages = request.maxPages ?? DEFAULT_RECORDS_MAX_PAGES;
+        let cursor = { offset: request.offset };
+        for (let page = 0; page < maxPages; page += 1) {
+            const response = await this.client.searchOgcRecords({
+                ...request,
+                limit: pageSize,
+                offset: cursor.offset,
+            });
+            const pageRecords = response.features ?? [];
+            if (pageRecords.length === 0)
+                break;
+            yield pageRecords;
+            cursor = nextRecordsCursor(response.links);
+            // See searchAll: a short page is not a termination signal; rely on the
+            // next-link cursor and the maxPages cap.
+            if (cursor.offset === undefined)
+                break;
+        }
+    }
+}
+/**
+ * Bound handle for one Records catalog (`/collections/{catalogId}`). Drops
+ * the routing discriminator from per-call requests.
+ */
+export class HonuaOgcRecordCollection {
+    client;
+    collectionId;
+    constructor(options) {
+        this.client = options.client;
+        this.collectionId = options.collectionId;
+    }
+    async metadata(request = {}) {
+        return this.client.getOgcRecordCollection({ ...request, collectionId: this.collectionId });
+    }
+    async search(request = {}) {
+        return this.client.searchOgcRecords({ ...request, collectionId: this.collectionId });
+    }
+    async record(request) {
+        return this.client.getOgcRecord({ ...request, collectionId: this.collectionId });
+    }
+    async rawSearch(request = {}) {
+        return this.client.fetchOgcRecordsRaw({ ...request, collectionId: this.collectionId });
+    }
+    async rawRecord(request) {
+        return this.client.fetchOgcRecordRaw({ ...request, collectionId: this.collectionId });
+    }
+    async searchAll(request = {}) {
+        const root = new HonuaOgcRecords({ client: this.client });
+        return root.searchAll({ ...request, collectionId: this.collectionId });
+    }
+    searchStream(request = {}) {
+        const root = new HonuaOgcRecords({ client: this.client });
+        return root.searchStream({ ...request, collectionId: this.collectionId });
+    }
+}
+/**
+ * Query-param names that may carry the next-page start offset on an OGC API
+ * `rel:"next"` link. `offset` is Honua Server's spelling; `startindex` is the
+ * OGC API – Features / Records standard name (servers also vary the casing).
+ */
+const RECORDS_OFFSET_PARAM_NAMES = ["offset", "startindex", "startIndex"];
+function nextRecordsCursor(links) {
+    if (!links)
+        return {};
+    for (const link of links) {
+        if (link.rel !== "next" || typeof link.href !== "string")
+            continue;
+        try {
+            const url = new URL(link.href, "https://placeholder.test");
+            // Standards-conformant servers commonly express the next page with
+            // `startindex` rather than `offset`; honor whichever the server sent so
+            // pagination doesn't silently stop after the first page.
+            const offsetParam = readFirstParam(url.searchParams, RECORDS_OFFSET_PARAM_NAMES);
+            if (offsetParam === null)
+                continue;
+            const offset = Number(offsetParam);
+            if (Number.isFinite(offset))
+                return { offset };
+        }
+        catch {
+            // Ignore unparsable hrefs; keep scanning for a usable next link.
+        }
+    }
+    return {};
+}
+/** Return the first non-null value among `names` from the query string. */
+function readFirstParam(params, names) {
+    for (const name of names) {
+        const value = params.get(name);
+        if (value !== null)
+            return value;
+    }
+    return null;
+}
+export function createHonuaOgcRecords(client) {
+    return new HonuaOgcRecords({ client });
+}
+// ── OGC API Records wire methods ────────────────────────────────
+export async function getOgcRecordsLanding(transport, request = {}) {
+    const params = createOgcMetadataParams(request);
+    return transport.requestCachedMetadataJson(`ogc-records:landing:${params.toString()}`, `/ogc/records?${params.toString()}`, request);
+}
+export async function getOgcRecordsConformance(transport, request = {}) {
+    const params = createOgcMetadataParams(request);
+    return transport.requestCachedMetadataJson(`ogc-records:conformance:${params.toString()}`, `/ogc/records/conformance?${params.toString()}`, request);
+}
+export async function listOgcRecordCollections(transport, request = {}) {
+    const params = createOgcMetadataParams(request);
+    return transport.requestCachedMetadataJson(`ogc-records:collections:${params.toString()}`, `/ogc/records/collections?${params.toString()}`, request);
+}
+export async function getOgcRecordCollection(transport, request) {
+    const params = createOgcMetadataParams(request);
+    const path = `/ogc/records/collections/${encodeURIComponent(String(request.collectionId))}`;
+    return transport.requestCachedMetadataJson(`ogc-records:collection:${request.collectionId}:${params.toString()}`, `${path}?${params.toString()}`, request);
+}
+export async function searchOgcRecords(transport, request) {
+    return transport.requestJson("GET", buildOgcRecordsSearchPath(request), undefined, request.signal);
+}
+export async function getOgcRecord(transport, request) {
+    return transport.requestJson("GET", buildOgcRecordPath(request), undefined, request.signal);
+}
+export async function fetchOgcRecordsRaw(transport, request) {
+    return transport.pipelineFetch("GET", buildOgcRecordsSearchPath(request), {
+        headers: mergeHeaders({ Accept: request.accept ?? "application/geo+json, application/json;q=0.9" }, request.headers),
+    }, request.signal);
+}
+export async function fetchOgcRecordRaw(transport, request) {
+    return transport.pipelineFetch("GET", buildOgcRecordPath(request), {
+        headers: mergeHeaders({ Accept: request.accept ?? "application/geo+json, application/json;q=0.9" }, request.headers),
+    }, request.signal);
+}
+function normalizeRecordsBbox(value) {
+    return Array.isArray(value) ? value.join(",") : String(value);
+}
+function buildOgcRecordsSearchPath(request) {
+    const collection = encodeURIComponent(String(request.collectionId));
+    const params = serializeOgcRecordsSearchParams(request);
+    return `/ogc/records/collections/${collection}/items?${params.toString()}`;
+}
+function buildOgcRecordPath(request) {
+    const collection = encodeURIComponent(String(request.collectionId));
+    const record = encodeURIComponent(String(request.recordId));
+    const params = createOgcMetadataParams(request);
+    if (request.profile !== undefined)
+        params.set("profile", normalizeStringCsv(request.profile));
+    return `/ogc/records/collections/${collection}/items/${record}?${params.toString()}`;
+}
+function serializeOgcRecordsSearchParams(request) {
+    const params = createOgcMetadataParams(request);
+    if (request.limit !== undefined)
+        params.set("limit", String(request.limit));
+    if (request.offset !== undefined)
+        params.set("offset", String(request.offset));
+    if (request.bbox !== undefined)
+        params.set("bbox", normalizeRecordsBbox(request.bbox));
+    if (request.datetime !== undefined)
+        params.set("datetime", request.datetime);
+    if (request.q !== undefined)
+        params.set("q", normalizeStringCsv(request.q));
+    if (request.ids !== undefined)
+        params.set("ids", normalizeCsv(request.ids));
+    if (request.type !== undefined)
+        params.set("type", normalizeStringCsv(request.type));
+    if (request.externalIds !== undefined)
+        params.set("externalIds", normalizeStringCsv(request.externalIds));
+    if (request.filter !== undefined)
+        params.set("filter", request.filter);
+    if (request.filterLang !== undefined)
+        params.set("filter-lang", request.filterLang);
+    if (request.filterCrs !== undefined)
+        params.set("filter-crs", request.filterCrs);
+    if (request.properties !== undefined)
+        params.set("properties", normalizeStringCsv(request.properties));
+    if (request.sortby !== undefined)
+        params.set("sortby", request.sortby);
+    if (request.profile !== undefined)
+        params.set("profile", normalizeStringCsv(request.profile));
+    return params;
+}

package/core/ogc-tiles.d.ts

@@ -0,0 +1,125 @@
+/**
+ * OGC API Tiles surface. Wraps the wire methods on `HonuaClient` with a
+ * tileset-discovery friendly API and a single-tile fetch helper. The
+ * conformance class identifiers are kept internal — callers see
+ * tilesets, tile-matrix-sets, and styled-tile access through the shared
+ * vocabulary, never an `OgcApiTilesPart2DatasetMap` typename.
+ *
+ * @module
+ */
+import type { HonuaMetadataRequestOptions } from "./cache-state.js";
+import type { HonuaClient } from "./client.js";
+import type { HonuaProtocolTransport } from "./protocol-transport.js";
+import type { HonuaOgcConformanceResponse, HonuaOgcLandingResponse, HonuaOgcTileMatrixSet, HonuaOgcTileMatrixSetsResponse, HonuaOgcTileResponse, HonuaOgcTilesetMetadata, HonuaOgcTilesetsResponse, OgcMetadataRequest, OgcTileMatrixSetId, OgcTileRequest, OgcTilesetRequest, OgcTilesetsRequest } from "./types.js";
+/** Default OGC tile-matrix-set used when none is specified (Web Mercator XYZ). */
+export declare const DEFAULT_OGC_TILE_MATRIX_SET: OgcTileMatrixSetId;
+export interface HonuaOgcTilesOptions {
+    client: HonuaClient;
+}
+/**
+ * Structural shape of a MapLibre `VectorSourceSpecification` for tiled
+ * vector data. Declared locally so the SDK does not take a runtime or type
+ * dependency on `maplibre-gl` (a peer); the object is assignable to
+ * MapLibre's `VectorSourceSpecification`.
+ */
+export interface MapLibreVectorSourceSpec {
+    type: "vector";
+    tiles: string[];
+    minzoom?: number;
+    maxzoom?: number;
+    scheme?: "xyz";
+}
+/** Options for {@link HonuaOgcTiles.getMapLibreVectorSource}. */
+export interface HonuaMapLibreVectorSourceOptions {
+    /** Tile-matrix-set to template against. Defaults to `WebMercatorQuad`. */
+    tileMatrixSetId?: OgcTileMatrixSetId;
+    /** Override the `minzoom` of the produced source. */
+    minzoom?: number;
+    /** Override the `maxzoom` of the produced source. */
+    maxzoom?: number;
+}
+/** Result of {@link HonuaOgcTiles.getMapLibreConfig}. */
+export interface HonuaMapLibreTilesConfig {
+    source: MapLibreVectorSourceSpec;
+    sourceLayer: string;
+}
+export interface HonuaOgcTilesetOptions {
+    client: HonuaClient;
+    collectionId: string | number;
+    tileMatrixSetId: string;
+}
+export type HonuaOgcCollectionTilesetRequest = Omit<OgcTilesetRequest, "collectionId" | "tileMatrixSetId">;
+export type HonuaOgcCollectionTilesetsRequest = Omit<OgcTilesetsRequest, "collectionId">;
+export type HonuaOgcCollectionTileRequest = Omit<OgcTileRequest, "collectionId" | "tileMatrixSetId">;
+/**
+ * Top-level OGC API Tiles handle. Mirrors `HonuaOgcFeatures` for the
+ * tiles conformance classes.
+ */
+export declare class HonuaOgcTiles {
+    readonly client: HonuaClient;
+    constructor(options: HonuaOgcTilesOptions);
+    tileset(collectionId: string | number, tileMatrixSetId: string): HonuaOgcTileset;
+    landing(request?: OgcMetadataRequest): Promise<HonuaOgcLandingResponse>;
+    conformance(request?: OgcMetadataRequest): Promise<HonuaOgcConformanceResponse>;
+    tileMatrixSets(request?: OgcMetadataRequest): Promise<HonuaOgcTileMatrixSetsResponse>;
+    tileMatrixSet(tileMatrixSetId: string, request?: OgcMetadataRequest): Promise<HonuaOgcTileMatrixSet>;
+    tilesets(request: OgcTilesetsRequest): Promise<HonuaOgcTilesetsResponse>;
+    tilesetMetadata(request: OgcTilesetRequest): Promise<HonuaOgcTilesetMetadata>;
+    tile(request: OgcTileRequest): Promise<HonuaOgcTileResponse>;
+    /**
+     * Build a MapLibre-ready vector source definition for a tiled collection.
+     *
+     * Produces a `{ type: "vector", tiles: ["…/{z}/{y}/{x}"] }` object whose
+     * tile URL points at the canonical OGC API Tiles collection-tile route on
+     * the SDK's configured `baseUrl`. The MapLibre `{z}/{y}/{x}` placeholders
+     * are kept literal (the braces are not percent-encoded) while the
+     * collection / service identifier is encoded per path segment so
+     * folder-prefixed identifiers like `myFolder/parcels` serialize correctly.
+     *
+     * No network request is made; this is a pure URL-template builder. Pass
+     * `minzoom` / `maxzoom` to constrain the source, otherwise MapLibre's
+     * defaults apply.
+     */
+    getMapLibreVectorSource(serviceId: string, options?: HonuaMapLibreVectorSourceOptions): MapLibreVectorSourceSpec;
+    /**
+     * Resolve the `source-layer` name to use in a MapLibre layer that renders
+     * the collection's vector tiles. The Honua server names the MVT layer after
+     * the collection identifier; for folder-prefixed identifiers the trailing
+     * segment is the layer name (the folder is a routing prefix, not part of
+     * the layer name baked into the tile).
+     */
+    getDefaultSourceLayer(serviceId: string): string;
+    /**
+     * Convenience wrapper returning both the MapLibre vector {@link source}
+     * object and the {@link sourceLayer} name to wire into a layer definition.
+     */
+    getMapLibreConfig(serviceId: string, options?: HonuaMapLibreVectorSourceOptions): HonuaMapLibreTilesConfig;
+}
+/**
+ * Bound handle for one (collection × tile-matrix-set) tileset. Drops the
+ * discovery params from the per-call surface so callers focus on tile
+ * coordinates. Styled-tile access (the OGC `/styles/{styleId}` route) is
+ * not exposed here because the Honua server does not currently implement
+ * that route; the tile path is the canonical collection tile route.
+ */
+export declare class HonuaOgcTileset {
+    readonly client: HonuaClient;
+    readonly collectionId: string | number;
+    readonly tileMatrixSetId: string;
+    constructor(options: HonuaOgcTilesetOptions);
+    metadata(request?: HonuaOgcCollectionTilesetRequest): Promise<HonuaOgcTilesetMetadata>;
+    tile(request: HonuaOgcCollectionTileRequest): Promise<HonuaOgcTileResponse>;
+}
+export declare function createHonuaOgcTiles(client: HonuaClient): HonuaOgcTiles;
+export declare function getOgcTilesLanding(transport: HonuaProtocolTransport, request?: OgcMetadataRequest): Promise<HonuaOgcLandingResponse>;
+export declare function getOgcTilesConformance(transport: HonuaProtocolTransport, request?: OgcMetadataRequest): Promise<HonuaOgcConformanceResponse>;
+export declare function listOgcTileMatrixSets(transport: HonuaProtocolTransport, request?: OgcMetadataRequest): Promise<HonuaOgcTileMatrixSetsResponse>;
+export declare function getOgcTileMatrixSet(transport: HonuaProtocolTransport, request: {
+    tileMatrixSetId: string;
+    responseFormat?: string;
+    extraParams?: Record<string, string | number | boolean>;
+} & HonuaMetadataRequestOptions): Promise<HonuaOgcTileMatrixSet>;
+export declare function listOgcCollectionTilesets(transport: HonuaProtocolTransport, request: OgcTilesetsRequest): Promise<HonuaOgcTilesetsResponse>;
+export declare function getOgcCollectionTileset(transport: HonuaProtocolTransport, request: OgcTilesetRequest): Promise<HonuaOgcTilesetMetadata>;
+export declare function fetchOgcTile(transport: HonuaProtocolTransport, request: OgcTileRequest): Promise<HonuaOgcTileResponse>;
+//# sourceMappingURL=ogc-tiles.d.ts.map

package/core/ogc-tiles.d.ts.map

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

package/core/ogc-tiles.js

@@ -0,0 +1,183 @@
+/**
+ * OGC API Tiles surface. Wraps the wire methods on `HonuaClient` with a
+ * tileset-discovery friendly API and a single-tile fetch helper. The
+ * conformance class identifiers are kept internal — callers see
+ * tilesets, tile-matrix-sets, and styled-tile access through the shared
+ * vocabulary, never an `OgcApiTilesPart2DatasetMap` typename.
+ *
+ * @module
+ */
+import { encodePathSegments, trimTrailingSlashes } from "./path-utils.js";
+import { createOgcMetadataParams } from "./wire-shared.js";
+/** Default OGC tile-matrix-set used when none is specified (Web Mercator XYZ). */
+export const DEFAULT_OGC_TILE_MATRIX_SET = "WebMercatorQuad";
+/**
+ * Top-level OGC API Tiles handle. Mirrors `HonuaOgcFeatures` for the
+ * tiles conformance classes.
+ */
+export class HonuaOgcTiles {
+    client;
+    constructor(options) {
+        this.client = options.client;
+    }
+    tileset(collectionId, tileMatrixSetId) {
+        return new HonuaOgcTileset({
+            client: this.client,
+            collectionId,
+            tileMatrixSetId,
+        });
+    }
+    async landing(request = {}) {
+        return this.client.getOgcTilesLanding(request);
+    }
+    async conformance(request = {}) {
+        return this.client.getOgcTilesConformance(request);
+    }
+    async tileMatrixSets(request = {}) {
+        return this.client.listOgcTileMatrixSets(request);
+    }
+    async tileMatrixSet(tileMatrixSetId, request = {}) {
+        return this.client.getOgcTileMatrixSet({ ...request, tileMatrixSetId });
+    }
+    async tilesets(request) {
+        return this.client.listOgcCollectionTilesets(request);
+    }
+    async tilesetMetadata(request) {
+        return this.client.getOgcCollectionTileset(request);
+    }
+    async tile(request) {
+        return this.client.fetchOgcTile(request);
+    }
+    /**
+     * Build a MapLibre-ready vector source definition for a tiled collection.
+     *
+     * Produces a `{ type: "vector", tiles: ["…/{z}/{y}/{x}"] }` object whose
+     * tile URL points at the canonical OGC API Tiles collection-tile route on
+     * the SDK's configured `baseUrl`. The MapLibre `{z}/{y}/{x}` placeholders
+     * are kept literal (the braces are not percent-encoded) while the
+     * collection / service identifier is encoded per path segment so
+     * folder-prefixed identifiers like `myFolder/parcels` serialize correctly.
+     *
+     * No network request is made; this is a pure URL-template builder. Pass
+     * `minzoom` / `maxzoom` to constrain the source, otherwise MapLibre's
+     * defaults apply.
+     */
+    getMapLibreVectorSource(serviceId, options = {}) {
+        const tileMatrixSetId = options.tileMatrixSetId ?? DEFAULT_OGC_TILE_MATRIX_SET;
+        const baseUrl = trimTrailingSlashes(this.client.serverBaseUrl);
+        const collection = encodePathSegments(serviceId);
+        const matrixSet = encodeURIComponent(tileMatrixSetId);
+        const template = `${baseUrl}/ogc/tiles/collections/${collection}/tiles/${matrixSet}/{z}/{y}/{x}`;
+        const source = {
+            type: "vector",
+            tiles: [template],
+            scheme: "xyz",
+        };
+        if (options.minzoom !== undefined)
+            source.minzoom = options.minzoom;
+        if (options.maxzoom !== undefined)
+            source.maxzoom = options.maxzoom;
+        return source;
+    }
+    /**
+     * Resolve the `source-layer` name to use in a MapLibre layer that renders
+     * the collection's vector tiles. The Honua server names the MVT layer after
+     * the collection identifier; for folder-prefixed identifiers the trailing
+     * segment is the layer name (the folder is a routing prefix, not part of
+     * the layer name baked into the tile).
+     */
+    getDefaultSourceLayer(serviceId) {
+        const segments = serviceId.split("/");
+        return segments[segments.length - 1] ?? serviceId;
+    }
+    /**
+     * Convenience wrapper returning both the MapLibre vector {@link source}
+     * object and the {@link sourceLayer} name to wire into a layer definition.
+     */
+    getMapLibreConfig(serviceId, options = {}) {
+        return {
+            source: this.getMapLibreVectorSource(serviceId, options),
+            sourceLayer: this.getDefaultSourceLayer(serviceId),
+        };
+    }
+}
+/**
+ * Bound handle for one (collection × tile-matrix-set) tileset. Drops the
+ * discovery params from the per-call surface so callers focus on tile
+ * coordinates. Styled-tile access (the OGC `/styles/{styleId}` route) is
+ * not exposed here because the Honua server does not currently implement
+ * that route; the tile path is the canonical collection tile route.
+ */
+export class HonuaOgcTileset {
+    client;
+    collectionId;
+    tileMatrixSetId;
+    constructor(options) {
+        this.client = options.client;
+        this.collectionId = options.collectionId;
+        this.tileMatrixSetId = options.tileMatrixSetId;
+    }
+    async metadata(request = {}) {
+        return this.client.getOgcCollectionTileset({
+            ...request,
+            collectionId: this.collectionId,
+            tileMatrixSetId: this.tileMatrixSetId,
+        });
+    }
+    async tile(request) {
+        return this.client.fetchOgcTile({
+            ...request,
+            collectionId: this.collectionId,
+            tileMatrixSetId: this.tileMatrixSetId,
+        });
+    }
+}
+export function createHonuaOgcTiles(client) {
+    return new HonuaOgcTiles({ client });
+}
+// ── OGC API Tiles wire methods ──────────────────────────────────
+//
+// Concrete URL-building / param-serialization / response-handling for the
+// OGC API Tiles endpoints, invoked against an injected transport. The client
+// exposes thin `get*/list*/fetch*` delegators that call these.
+export async function getOgcTilesLanding(transport, request = {}) {
+    const params = createOgcMetadataParams(request);
+    return transport.requestCachedMetadataJson(`ogc-tiles:landing:${params.toString()}`, `/ogc/tiles?${params.toString()}`, request);
+}
+export async function getOgcTilesConformance(transport, request = {}) {
+    const params = createOgcMetadataParams(request);
+    return transport.requestCachedMetadataJson(`ogc-tiles:conformance:${params.toString()}`, `/ogc/tiles/conformance?${params.toString()}`, request);
+}
+export async function listOgcTileMatrixSets(transport, request = {}) {
+    const params = createOgcMetadataParams(request);
+    return transport.requestCachedMetadataJson(`ogc-tiles:tile-matrix-sets:${params.toString()}`, `/ogc/tiles/tileMatrixSets?${params.toString()}`, request);
+}
+export async function getOgcTileMatrixSet(transport, request) {
+    const params = createOgcMetadataParams(request);
+    return transport.requestCachedMetadataJson(`ogc-tiles:tile-matrix-set:${request.tileMatrixSetId}:${params.toString()}`, `/ogc/tiles/tileMatrixSets/${encodeURIComponent(request.tileMatrixSetId)}?${params.toString()}`, request);
+}
+export async function listOgcCollectionTilesets(transport, request) {
+    const params = createOgcMetadataParams(request);
+    const path = `/ogc/tiles/collections/${encodeURIComponent(String(request.collectionId))}/tiles`;
+    return transport.requestCachedMetadataJson(`ogc-tiles:tilesets:${request.collectionId}:${params.toString()}`, `${path}?${params.toString()}`, request);
+}
+export async function getOgcCollectionTileset(transport, request) {
+    const params = createOgcMetadataParams(request);
+    const path = `/ogc/tiles/collections/${encodeURIComponent(String(request.collectionId))}` +
+        `/tiles/${encodeURIComponent(request.tileMatrixSetId)}`;
+    return transport.requestCachedMetadataJson(`ogc-tiles:tileset:${request.collectionId}:${request.tileMatrixSetId}:${params.toString()}`, `${path}?${params.toString()}`, request);
+}
+export async function fetchOgcTile(transport, request) {
+    const params = new URLSearchParams();
+    if (request.extraParams) {
+        for (const [key, value] of Object.entries(request.extraParams)) {
+            params.set(key, String(value));
+        }
+    }
+    const collection = encodeURIComponent(String(request.collectionId));
+    const matrixSet = encodeURIComponent(request.tileMatrixSetId);
+    const matrix = encodeURIComponent(String(request.tileMatrix));
+    const query = params.size > 0 ? `?${params.toString()}` : "";
+    const path = `/ogc/tiles/collections/${collection}/tiles/${matrixSet}/${matrix}/${request.tileRow}/${request.tileCol}${query}`;
+    return transport.requestBytes("GET", path, request.accept, undefined, request.signal);
+}