@honua/react 0.0.20-alpha.0 → 0.1.0-beta.0

package/core/ogc-endpoint-layout.js

@@ -0,0 +1,173 @@
+/**
+ * OGC API endpoint-layout resolution.
+ *
+ * The SDK's headline claim is one typed contract against ANY standards
+ * server. For OGC API Features / Records that means the client must not
+ * assume a fixed path prefix: a Honua Server mounts the facade at
+ * `/ogc/features/...`, but pygeoapi, ldproxy, and GeoServer's OGC API each
+ * serve the landing page at their own root and advertise their collections
+ * and conformance URLs through the landing page's `links` array
+ * (OGC API - Common Requirement 5).
+ *
+ * This module produces an {@link OgcEndpointLayout} — the concrete set of
+ * resource paths a Features client addresses:
+ *
+ *  - {@link honuaFacadeFeaturesLayout} is the fixed facade layout and the
+ *    default. It performs no network round-trips, so existing callers see
+ *    zero behaviour change.
+ *  - {@link resolveOgcEndpointLayout} discovers the layout from the landing
+ *    page (`ogc-api` mode) or auto-detects the facade first and falls back
+ *    to discovery (`auto` mode).
+ *
+ * Per OGC API - Features Requirement 17 the items resource is always at
+ * `{collections}/{collectionId}/items`, so a single landing-page fetch is
+ * enough to derive every per-collection path from the discovered
+ * collections URL.
+ *
+ * @module
+ */
+import { HonuaCapabilityNotSupportedError } from "./errors.js";
+const DEFAULT_FACADE_BASE = "/ogc/features";
+function enc(id) {
+    return encodeURIComponent(String(id));
+}
+function trimTrailingSlash(url) {
+    let end = url.length;
+    while (end > 0 && url.charCodeAt(end - 1) === 0x2f)
+        end--;
+    return url.slice(0, end);
+}
+/**
+ * The Honua Server facade layout (`/ogc/features/...`). No network access;
+ * this is the default fast path and preserves the pre-existing behaviour of
+ * every OGC Features caller that points at a Honua Server.
+ */
+export function honuaFacadeFeaturesLayout(base = DEFAULT_FACADE_BASE) {
+    const root = trimTrailingSlash(base) || DEFAULT_FACADE_BASE;
+    return {
+        mode: "honua-facade",
+        landing: () => root,
+        conformance: () => `${root}/conformance`,
+        collections: () => `${root}/collections`,
+        collection: (id) => `${root}/collections/${enc(id)}`,
+        queryables: (id) => `${root}/collections/${enc(id)}/queryables`,
+        items: (id) => `${root}/collections/${enc(id)}/items`,
+        item: (id, featureId) => `${root}/collections/${enc(id)}/items/${enc(featureId)}`,
+    };
+}
+/**
+ * A raw OGC API layout built from a discovered (or configured) landing +
+ * collections + conformance URL triple. Per-collection paths are templated
+ * off the collections URL per OGC API - Features Requirement 17.
+ */
+export function ogcApiFeaturesLayout(options) {
+    const landing = trimTrailingSlash(options.landingUrl);
+    const collections = trimTrailingSlash(options.collectionsUrl);
+    const conformance = trimTrailingSlash(options.conformanceUrl);
+    return {
+        mode: "ogc-api",
+        // A bare landing path can be empty (the client baseUrl is the landing
+        // root); the wire layer still appends the `f=` param, producing
+        // `${baseUrl}?f=json`.
+        landing: () => landing,
+        conformance: () => conformance,
+        collections: () => collections,
+        collection: (id) => `${collections}/${enc(id)}`,
+        queryables: (id) => `${collections}/${enc(id)}/queryables`,
+        items: (id) => `${collections}/${enc(id)}/items`,
+        item: (id, featureId) => `${collections}/${enc(id)}/items/${enc(featureId)}`,
+    };
+}
+/**
+ * Resolve a link href to an absolute URL against a base. Absolute hrefs are
+ * returned unchanged; relative hrefs resolve against `${baseUrl}/`.
+ */
+function absolutize(href, baseUrl) {
+    if (/^https?:\/\//i.test(href))
+        return href;
+    const root = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+    try {
+        return new URL(href, root).toString();
+    }
+    catch {
+        return href;
+    }
+}
+/**
+ * Find the first link whose `rel` matches one of `rels` (exact or as the
+ * final path segment of a full OGC relation URI, e.g.
+ * `http://www.opengis.net/def/rel/ogc/1.0/data`).
+ */
+export function findOgcLink(links, ...rels) {
+    if (!links)
+        return undefined;
+    const wanted = new Set(rels.map((r) => r.toLowerCase()));
+    for (const link of links) {
+        if (typeof link.href !== "string" || link.href.length === 0)
+            continue;
+        const rel = (link.rel ?? "").toLowerCase();
+        if (wanted.has(rel))
+            return link.href;
+        const tail = rel.slice(rel.lastIndexOf("/") + 1);
+        if (tail && wanted.has(tail))
+            return link.href;
+    }
+    return undefined;
+}
+/**
+ * Discover an OGC API layout from the landing page. The client `baseUrl`
+ * IS the landing page root; the collections and conformance URLs are read
+ * from the landing `links` (falling back to the mandated relative
+ * `collections` / `conformance` sub-paths when a server omits them).
+ */
+async function discoverOgcApiLayout(transport) {
+    const landing = await transport.requestCachedMetadataJson("ogc-features:layout:landing", "?f=json", {});
+    const baseUrl = trimTrailingSlash(transport.baseUrl);
+    const links = landing?.links;
+    const dataHref = findOgcLink(links, "data");
+    const conformanceHref = findOgcLink(links, "conformance");
+    const collectionsUrl = dataHref ? absolutize(dataHref, baseUrl) : `${baseUrl}/collections`;
+    const conformanceUrl = conformanceHref ? absolutize(conformanceHref, baseUrl) : `${baseUrl}/conformance`;
+    return ogcApiFeaturesLayout({ landingUrl: baseUrl, collectionsUrl, conformanceUrl });
+}
+/**
+ * Probe whether the Honua facade landing (`/ogc/features`) exists. Used by
+ * `auto` mode: a valid OGC landing document there confirms the facade
+ * fast path; anything else falls through to landing-page discovery.
+ */
+async function facadeLandingLooksValid(transport) {
+    try {
+        const landing = await transport.requestCachedMetadataJson("ogc-features:layout:facade-probe", `${DEFAULT_FACADE_BASE}?f=json`, {});
+        return Array.isArray(landing?.links);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the endpoint layout for the requested `mode`:
+ *
+ *  - `honua-facade` (default) — the fixed facade layout, no round-trips.
+ *  - `ogc-api` — discover from the landing page at the client baseUrl.
+ *  - `auto` — probe the facade landing; use it when valid, otherwise
+ *    discover from the root.
+ *
+ * Discovery failures surface as {@link HonuaCapabilityNotSupportedError}
+ * (per the SDK convention of throwing rather than returning empty data).
+ */
+export async function resolveOgcEndpointLayout(transport, mode = "honua-facade") {
+    if (mode === "honua-facade")
+        return honuaFacadeFeaturesLayout();
+    if (mode === "auto") {
+        if (await facadeLandingLooksValid(transport))
+            return honuaFacadeFeaturesLayout();
+    }
+    try {
+        return await discoverOgcApiLayout(transport);
+    }
+    catch (err) {
+        if (err instanceof HonuaCapabilityNotSupportedError)
+            throw err;
+        throw new HonuaCapabilityNotSupportedError("query", "ogc-features", `ogc-api layout discovery failed for ${transport.baseUrl}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}

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

@@ -1 +1 @@
-{"version":3,"file":"ogc-features.d.ts","sourceRoot":"","sources":["../../../src/core/ogc-features.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,KAAK,EACV,0BAA0B,EAC1B,2BAA2B,EAC3B,2BAA2B,EAC3B,iCAAiC,EACjC,uBAAuB,EACvB,uBAAuB,EACvB,0BAA0B,EAC1B,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAGpB,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,sBAAsB,EACjC,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,uBAAuB,CAAC,CAOlC;AAED,wBAAsB,yBAAyB,CAC7C,SAAS,EAAE,sBAAsB,EACjC,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,2BAA2B,CAAC,CAOtC;AAED,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,sBAAsB,EACjC,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,2BAA2B,CAAC,CAOtC;AAED,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,0BAA0B,CAAC,CAQrC;AAED,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,0BAA0B,CAAC,CAQrC;AAED,wBAAsB,YAAY,CAChC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,iCAAiC,CAAC,CAoC5C;AAED,wBAAsB,UAAU,CAC9B,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,uBAAuB,CAAC,CAclC;AAED,wBAAsB,aAAa,CACjC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,uBAAuB,CAAC,CAYlC;AAED,wBAAsB,cAAc,CAClC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,uBAAuB,CAAC,CAiBlC;AAED,wBAAsB,YAAY,CAChC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,uBAAuB,CAAC,CAiBlC;AAED,wBAAsB,aAAa,CAAC,SAAS,EAAE,sBAAsB,EAAE,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CASnH"}
+{"version":3,"file":"ogc-features.d.ts","sourceRoot":"","sources":["../../../src/core/ogc-features.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,KAAK,EACV,0BAA0B,EAC1B,2BAA2B,EAC3B,2BAA2B,EAC3B,iCAAiC,EACjC,uBAAuB,EACvB,uBAAuB,EACvB,0BAA0B,EAC1B,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EAEpB,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAoBpB,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,sBAAsB,EACjC,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,uBAAuB,CAAC,CAQlC;AAED,wBAAsB,yBAAyB,CAC7C,SAAS,EAAE,sBAAsB,EACjC,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,2BAA2B,CAAC,CAQtC;AAED,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,sBAAsB,EACjC,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,2BAA2B,CAAC,CAQtC;AAED,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,0BAA0B,CAAC,CAQrC;AAED,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,0BAA0B,CAAC,CAQrC;AAED,wBAAsB,YAAY,CAChC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,iCAAiC,CAAC,CAoC5C;AAED,wBAAsB,UAAU,CAC9B,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,uBAAuB,CAAC,CAYlC;AAED,wBAAsB,aAAa,CACjC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,uBAAuB,CAAC,CAYlC;AAED,wBAAsB,cAAc,CAClC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,uBAAuB,CAAC,CAelC;AAED,wBAAsB,YAAY,CAChC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,uBAAuB,CAAC,CAelC;AAED,wBAAsB,aAAa,CAAC,SAAS,EAAE,sBAAsB,EAAE,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAOnH"}

package/core/ogc-features.js

@@ -7,28 +7,47 @@
  *
  * @module
  */
+import { honuaFacadeFeaturesLayout } from "./ogc-endpoint-layout.js";
 import { createOgcMetadataParams, mergeHeaders, normalizeCsv } from "./wire-shared.js";
+/**
+ * The endpoint layout to build paths against. Defaults to the Honua facade
+ * fast path (`/ogc/features/...`); backend-agnostic callers thread a
+ * spec-discovered layout onto `request.layout`.
+ */
+function layoutOf(request) {
+    return request.layout ?? honuaFacadeFeaturesLayout();
+}
+/**
+ * A layout key fragment for cache keys so the facade and a discovered raw
+ * layout never collide in the metadata cache.
+ */
+function layoutKey(layout) {
+    return layout.mode === "honua-facade" ? "facade" : layout.collections();
+}
 export async function getOgcFeaturesLanding(transport, request = {}) {
     const params = createOgcMetadataParams(request);
-    return transport.requestCachedMetadataJson(`ogc-features:landing:${params.toString()}`, `/ogc/features?${params.toString()}`, request);
+    const layout = layoutOf(request);
+    return transport.requestCachedMetadataJson(`ogc-features:landing:${layoutKey(layout)}:${params.toString()}`, `${layout.landing()}?${params.toString()}`, request);
 }
 export async function getOgcFeaturesConformance(transport, request = {}) {
     const params = createOgcMetadataParams(request);
-    return transport.requestCachedMetadataJson(`ogc-features:conformance:${params.toString()}`, `/ogc/features/conformance?${params.toString()}`, request);
+    const layout = layoutOf(request);
+    return transport.requestCachedMetadataJson(`ogc-features:conformance:${layoutKey(layout)}:${params.toString()}`, `${layout.conformance()}?${params.toString()}`, request);
 }
 export async function listOgcCollections(transport, request = {}) {
     const params = createOgcMetadataParams(request);
-    return transport.requestCachedMetadataJson(`ogc-features:collections:${params.toString()}`, `/ogc/features/collections?${params.toString()}`, request);
+    const layout = layoutOf(request);
+    return transport.requestCachedMetadataJson(`ogc-features:collections:${layoutKey(layout)}:${params.toString()}`, `${layout.collections()}?${params.toString()}`, request);
 }
 export async function getOgcCollection(transport, request) {
     const params = createOgcMetadataParams(request);
-    const path = `/ogc/features/collections/${encodeURIComponent(String(request.collectionId))}`;
-    return transport.requestCachedMetadataJson(`ogc-features:collection:${request.collectionId}:${params.toString()}`, `${path}?${params.toString()}`, request);
+    const layout = layoutOf(request);
+    return transport.requestCachedMetadataJson(`ogc-features:collection:${layoutKey(layout)}:${request.collectionId}:${params.toString()}`, `${layout.collection(request.collectionId)}?${params.toString()}`, request);
 }
 export async function getOgcQueryables(transport, request) {
     const params = createOgcMetadataParams(request);
-    const path = `/ogc/features/collections/${encodeURIComponent(String(request.collectionId))}/queryables`;
-    return transport.requestCachedMetadataJson(`ogc-features:queryables:${request.collectionId}:${params.toString()}`, `${path}?${params.toString()}`, request);
+    const layout = layoutOf(request);
+    return transport.requestCachedMetadataJson(`ogc-features:queryables:${layoutKey(layout)}:${request.collectionId}:${params.toString()}`, `${layout.queryables(request.collectionId)}?${params.toString()}`, request);
 }
 export async function listOgcItems(transport, request) {
     const params = createOgcMetadataParams(request);
@@ -59,7 +78,7 @@ export async function listOgcItems(transport, request) {
     if (request.crs !== undefined) {
         params.set("crs", request.crs);
     }
-    const path = `/ogc/features/collections/${encodeURIComponent(String(request.collectionId))}/items`;
+    const path = layoutOf(request).items(request.collectionId);
     return transport.requestJson("GET", `${path}?${params.toString()}`, undefined, request.signal);
 }
 export async function getOgcItem(transport, request) {
@@ -67,13 +86,12 @@ export async function getOgcItem(transport, request) {
     if (request.crs !== undefined) {
         params.set("crs", request.crs);
     }
-    const path = `/ogc/features/collections/${encodeURIComponent(String(request.collectionId))}` +
-        `/items/${encodeURIComponent(String(request.featureId))}`;
+    const path = layoutOf(request).item(request.collectionId, request.featureId);
     return transport.requestJson("GET", `${path}?${params.toString()}`, undefined, request.signal);
 }
 export async function createOgcItem(transport, request) {
     const params = createOgcMetadataParams(request);
-    const path = `/ogc/features/collections/${encodeURIComponent(String(request.collectionId))}/items`;
+    const path = layoutOf(request).items(request.collectionId);
     return transport.requestJson("POST", `${path}?${params.toString()}`, {
         headers: mergeHeaders({ "Content-Type": "application/geo+json" }, request.headers),
         body: JSON.stringify(request.feature),
@@ -84,8 +102,7 @@ export async function replaceOgcItem(transport, request) {
     if (request.crs !== undefined) {
         params.set("crs", request.crs);
     }
-    const path = `/ogc/features/collections/${encodeURIComponent(String(request.collectionId))}` +
-        `/items/${encodeURIComponent(String(request.featureId))}`;
+    const path = layoutOf(request).item(request.collectionId, request.featureId);
     return transport.requestJson("PUT", `${path}?${params.toString()}`, {
         headers: mergeHeaders({ "Content-Type": "application/geo+json" }, request.headers),
         body: JSON.stringify(request.feature),
@@ -96,8 +113,7 @@ export async function patchOgcItem(transport, request) {
     if (request.crs !== undefined) {
         params.set("crs", request.crs);
     }
-    const path = `/ogc/features/collections/${encodeURIComponent(String(request.collectionId))}` +
-        `/items/${encodeURIComponent(String(request.featureId))}`;
+    const path = layoutOf(request).item(request.collectionId, request.featureId);
     return transport.requestJson("PATCH", `${path}?${params.toString()}`, {
         headers: mergeHeaders({ "Content-Type": "application/merge-patch+json" }, request.headers),
         body: JSON.stringify(request.patch),
@@ -108,7 +124,6 @@ export async function deleteOgcItem(transport, request) {
     if (request.crs !== undefined) {
         params.set("crs", request.crs);
     }
-    const path = `/ogc/features/collections/${encodeURIComponent(String(request.collectionId))}` +
-        `/items/${encodeURIComponent(String(request.featureId))}`;
+    const path = layoutOf(request).item(request.collectionId, request.featureId);
     await transport.requestJson("DELETE", `${path}?${params.toString()}`, undefined, request.signal);
 }

package/core/stac-static.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Static STAC catalog reader.
+ *
+ * A large share of public STAC catalogs are not API servers — they are
+ * static `catalog.json` / `collection.json` / item trees served from object
+ * storage, with no `/search` endpoint. This reader walks such a tree the
+ * spec-driven way: it follows `rel="child"` links to descend catalogs /
+ * collections and `rel="item"` links to reach STAC Items, resolving every
+ * href against the document it was found in (STAC best-practice relative
+ * links). Filtering (`collections` / `bbox` / `datetime` / `limit`) is
+ * applied client-side and the result is projected onto the same
+ * {@link HonuaStacItemCollectionResponse} envelope the STAC API search path
+ * returns, so the canonical `Source` surface is identical across both
+ * layouts.
+ *
+ * @module
+ */
+import type { HonuaClient } from "./client.js";
+import type { HonuaStacItemCollectionResponse } from "./types.js";
+/** Bounded search parameters for a static catalog traversal. */
+export interface StacStaticSearchParams {
+    collections?: readonly string[];
+    bbox?: readonly [number, number, number, number];
+    datetime?: string;
+    limit?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Reader bound to the URL of a static STAC catalog / collection root. The
+ * URL is the client baseUrl (the transport resolves same-origin absolute
+ * child/item hrefs directly), so `rootUrl` is normally `""` (the baseUrl
+ * itself) but may be an absolute `catalog.json` URL.
+ */
+export declare class HonuaStacStaticCatalog {
+    readonly client: HonuaClient;
+    private readonly rootUrl;
+    constructor(client: HonuaClient, rootUrl?: string);
+    /**
+     * Traverse the catalog tree, collect matching items, and return them in
+     * the STAC search envelope shape.
+     */
+    search(params?: StacStaticSearchParams): Promise<HonuaStacItemCollectionResponse>;
+    private fetchDoc;
+    /**
+     * Breadth-first walk collecting item documents. Descends `rel="child"`
+     * links; a `collections` filter prunes Collection subtrees whose `id`
+     * is not requested. Bounded by {@link MAX_DOCUMENTS} and the item cap.
+     */
+    private collectItems;
+}
+//# sourceMappingURL=stac-static.d.ts.map

package/core/stac-static.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stac-static.d.ts","sourceRoot":"","sources":["../../../src/core/stac-static.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,KAAK,EAAE,+BAA+B,EAAyB,MAAM,YAAY,CAAC;AAEzF,gEAAgE;AAChE,MAAM,WAAW,sBAAsB;IACrC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAeD;;;;;GAKG;AACH,qBAAa,sBAAsB;IACjC,SAAgB,MAAM,EAAE,WAAW,CAAC;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAEd,MAAM,EAAE,WAAW,EAAE,OAAO,SAAK;IAKpD;;;OAGG;IACU,MAAM,CAAC,MAAM,GAAE,sBAA2B,GAAG,OAAO,CAAC,+BAA+B,CAAC;YAcpF,QAAQ;IAMtB;;;;OAIG;YACW,YAAY;CA6D3B"}

package/core/stac-static.js

@@ -0,0 +1,195 @@
+/**
+ * Static STAC catalog reader.
+ *
+ * A large share of public STAC catalogs are not API servers — they are
+ * static `catalog.json` / `collection.json` / item trees served from object
+ * storage, with no `/search` endpoint. This reader walks such a tree the
+ * spec-driven way: it follows `rel="child"` links to descend catalogs /
+ * collections and `rel="item"` links to reach STAC Items, resolving every
+ * href against the document it was found in (STAC best-practice relative
+ * links). Filtering (`collections` / `bbox` / `datetime` / `limit`) is
+ * applied client-side and the result is projected onto the same
+ * {@link HonuaStacItemCollectionResponse} envelope the STAC API search path
+ * returns, so the canonical `Source` surface is identical across both
+ * layouts.
+ *
+ * @module
+ */
+import { HonuaCapabilityNotSupportedError } from "./errors.js";
+/** Guardrails so a malformed / cyclic catalog cannot fan out unbounded. */
+const MAX_DOCUMENTS = 500;
+const DEFAULT_ITEM_CAP = 1000;
+/**
+ * Reader bound to the URL of a static STAC catalog / collection root. The
+ * URL is the client baseUrl (the transport resolves same-origin absolute
+ * child/item hrefs directly), so `rootUrl` is normally `""` (the baseUrl
+ * itself) but may be an absolute `catalog.json` URL.
+ */
+export class HonuaStacStaticCatalog {
+    client;
+    rootUrl;
+    constructor(client, rootUrl = "") {
+        this.client = client;
+        this.rootUrl = rootUrl;
+    }
+    /**
+     * Traverse the catalog tree, collect matching items, and return them in
+     * the STAC search envelope shape.
+     */
+    async search(params = {}) {
+        const items = await this.collectItems(params);
+        const filtered = items.filter((item) => matchesFilters(item, params));
+        const cap = typeof params.limit === "number" && params.limit >= 0 ? params.limit : filtered.length;
+        const sliced = filtered.slice(0, cap);
+        return {
+            type: "FeatureCollection",
+            features: sliced,
+            numberReturned: sliced.length,
+            numberMatched: filtered.length,
+            links: [],
+        };
+    }
+    async fetchDoc(url, signal) {
+        // An empty seed root means "the client baseUrl is the catalog document".
+        const path = url === "" ? this.client.serverBaseUrl : url;
+        return this.client.pipelineRequestJson("GET", path, undefined, signal);
+    }
+    /**
+     * Breadth-first walk collecting item documents. Descends `rel="child"`
+     * links; a `collections` filter prunes Collection subtrees whose `id`
+     * is not requested. Bounded by {@link MAX_DOCUMENTS} and the item cap.
+     */
+    async collectItems(params) {
+        const itemCap = typeof params.limit === "number" && params.limit >= 0 ? Math.max(params.limit, 1) : DEFAULT_ITEM_CAP;
+        const wantedCollections = params.collections ? new Set(params.collections) : undefined;
+        const visited = new Set();
+        const queue = [this.rootUrl];
+        const itemUrls = [];
+        let docCount = 0;
+        while (queue.length > 0 && docCount < MAX_DOCUMENTS) {
+            const url = queue.shift();
+            if (url === undefined || visited.has(url))
+                continue;
+            visited.add(url);
+            docCount += 1;
+            let doc;
+            try {
+                doc = await this.fetchDoc(url, params.signal);
+            }
+            catch (err) {
+                if (url === this.rootUrl) {
+                    throw new HonuaCapabilityNotSupportedError("query", "stac", `static catalog root ${url || "(baseUrl)"} could not be read: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                continue;
+            }
+            // A Collection subtree not in the requested set is pruned entirely.
+            if (wantedCollections &&
+                doc.type === "Collection" &&
+                typeof doc.id === "string" &&
+                !wantedCollections.has(doc.id)) {
+                continue;
+            }
+            const base = absoluteBaseFor(url, this.client.serverBaseUrl);
+            for (const link of doc.links ?? []) {
+                if (typeof link.href !== "string")
+                    continue;
+                const rel = (link.rel ?? "").toLowerCase();
+                const resolved = resolveHref(link.href, base);
+                if (rel === "child") {
+                    if (!visited.has(resolved))
+                        queue.push(resolved);
+                }
+                else if (rel === "item" || rel === "items") {
+                    itemUrls.push(resolved);
+                }
+            }
+        }
+        const items = [];
+        for (const itemUrl of itemUrls) {
+            if (items.length >= itemCap)
+                break;
+            try {
+                const item = (await this.fetchDoc(itemUrl, params.signal));
+                if (item && item.type === "Feature")
+                    items.push(item);
+            }
+            catch {
+                // Skip an unreadable item; the traversal is best-effort per item.
+            }
+        }
+        return items;
+    }
+}
+/**
+ * The base URL a document's relative links resolve against. When the reader
+ * was seeded with a bare `""` root (the client baseUrl IS the catalog), use
+ * the client's server base URL so `./child.json` resolves correctly.
+ */
+function absoluteBaseFor(docUrl, serverBaseUrl) {
+    if (docUrl === "")
+        return serverBaseUrl;
+    if (/^https?:\/\//i.test(docUrl))
+        return docUrl;
+    const root = serverBaseUrl.endsWith("/") ? serverBaseUrl : `${serverBaseUrl}/`;
+    try {
+        return new URL(docUrl, root).toString();
+    }
+    catch {
+        return serverBaseUrl;
+    }
+}
+function resolveHref(href, base) {
+    if (/^https?:\/\//i.test(href))
+        return href;
+    try {
+        return new URL(href, base).toString();
+    }
+    catch {
+        return href;
+    }
+}
+function matchesFilters(item, params) {
+    const doc = item;
+    if (params.collections && params.collections.length > 0) {
+        if (typeof doc.collection !== "string" || !params.collections.includes(doc.collection))
+            return false;
+    }
+    if (params.bbox && Array.isArray(doc.bbox) && doc.bbox.length >= 4) {
+        if (!bboxIntersects(params.bbox, doc.bbox))
+            return false;
+    }
+    if (params.datetime) {
+        if (!datetimeMatches(params.datetime, doc))
+            return false;
+    }
+    return true;
+}
+function bboxIntersects(a, b) {
+    // 2D envelope intersection; ignores any z components.
+    const [axmin, aymin, axmax, aymax] = a;
+    const bxmin = b[0];
+    const bymin = b[1];
+    // A 4- or 6-tuple bbox: max x/y are the second half.
+    const bxmax = b.length >= 6 ? b[3] : b[2];
+    const bymax = b.length >= 6 ? b[4] : b[3];
+    return axmin <= bxmax && axmax >= bxmin && aymin <= bymax && aymax >= bymin;
+}
+function datetimeMatches(query, doc) {
+    const dt = doc.properties?.datetime;
+    // Closed / open interval query per STAC (`start/end`, `../end`, `start/..`).
+    if (query.includes("/")) {
+        const [rawStart, rawEnd] = query.split("/");
+        const start = rawStart && rawStart !== ".." ? Date.parse(rawStart) : Number.NEGATIVE_INFINITY;
+        const end = rawEnd && rawEnd !== ".." ? Date.parse(rawEnd) : Number.POSITIVE_INFINITY;
+        const startProp = doc.properties?.start_datetime ?? dt;
+        const endProp = doc.properties?.end_datetime ?? dt;
+        if (!startProp && !endProp)
+            return false;
+        const itemStart = startProp ? Date.parse(startProp) : Number.NEGATIVE_INFINITY;
+        const itemEnd = endProp ? Date.parse(endProp) : Number.POSITIVE_INFINITY;
+        return itemStart <= end && itemEnd >= start;
+    }
+    if (!dt)
+        return false;
+    return Date.parse(dt) === Date.parse(query);
+}

package/core/stac.d.ts

@@ -11,6 +11,13 @@ import type { HonuaProtocolTransport } from "./protocol-transport.js";
 import type { HonuaOgcCollectionMetadata, HonuaOgcCollectionsResponse, HonuaStacItemCollectionResponse, HonuaStacItemResponse, HonuaStacLandingResponse, OgcCollectionRequest, OgcMetadataRequest, StacSearchRequest } from "./types.js";
 export interface HonuaStacSearchOptions {
     client: HonuaClient;
+    /**
+     * Path prefix the STAC endpoints are mounted under. Defaults to `/stac`
+     * (Honua facade). Pass `""` for a raw STAC API root (e.g. Earth Search
+     * served at `.../v1`), so the search / collection paths resolve directly
+     * under the client baseUrl.
+     */
+    basePath?: string;
 }
 export interface HonuaStacSearchAllRequest extends StacSearchRequest {
     /** Maximum number of items to materialize across pages. */
@@ -25,7 +32,10 @@ export interface HonuaStacSearchAllRequest extends StacSearchRequest {
  */
 export declare class HonuaStacSearch {
     readonly client: HonuaClient;
+    private readonly basePath;
     constructor(options: HonuaStacSearchOptions);
+    /** Inject the configured STAC base path unless the caller already set one. */
+    private withBase;
     landing(request?: OgcMetadataRequest): Promise<HonuaStacLandingResponse>;
     collections(request?: OgcMetadataRequest): Promise<HonuaOgcCollectionsResponse>;
     collection(request: OgcCollectionRequest): Promise<HonuaOgcCollectionMetadata>;
@@ -35,6 +45,7 @@ export declare class HonuaStacSearch {
         signal?: AbortSignal;
         responseFormat?: string;
         extraParams?: Record<string, string | number | boolean>;
+        stacBasePath?: string;
     }): Promise<HonuaStacItemResponse>;
     search(request?: StacSearchRequest): Promise<HonuaStacItemCollectionResponse>;
     searchAll(request?: HonuaStacSearchAllRequest): Promise<HonuaStacItemResponse[]>;
@@ -50,6 +61,7 @@ export declare function getStacItem(transport: HonuaProtocolTransport, request:
     signal?: AbortSignal;
     responseFormat?: string;
     extraParams?: Record<string, string | number | boolean>;
+    stacBasePath?: string;
 }): Promise<HonuaStacItemResponse>;
 export declare function searchStac(transport: HonuaProtocolTransport, request?: StacSearchRequest): Promise<HonuaStacItemCollectionResponse>;
 //# sourceMappingURL=stac.d.ts.map

package/core/stac.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stac.d.ts","sourceRoot":"","sources":["../../../src/core/stac.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,KAAK,EACV,0BAA0B,EAC1B,2BAA2B,EAC3B,+BAA+B,EAC/B,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,WAAW,yBAA0B,SAAQ,iBAAiB;IAClE,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAKD;;;;GAIG;AACH,qBAAa,eAAe;IAC1B,SAAgB,MAAM,EAAE,WAAW,CAAC;gBAEjB,OAAO,EAAE,sBAAsB;IAIrC,OAAO,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,wBAAwB,CAAC;IAI5E,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,2BAA2B,CAAC;IAInF,UAAU,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,0BAA0B,CAAC;IAI9E,IAAI,CAAC,OAAO,EAAE;QACzB,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;QAC9B,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE,WAAW,CAAC;QACrB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;KACzD,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAIrB,MAAM,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,+BAA+B,CAAC;IAIjF,SAAS,CAAC,OAAO,GAAE,yBAA8B,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC;IAyBnF,YAAY,CACxB,OAAO,GAAE,yBAA8B,GACtC,cAAc,CAAC,qBAAqB,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC;CAoB5D;AAkCD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,WAAW,GAAG,eAAe,CAE1E;AAID,wBAAsB,cAAc,CAClC,SAAS,EAAE,sBAAsB,EACjC,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,wBAAwB,CAAC,CAOnC;AAED,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,sBAAsB,EACjC,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,2BAA2B,CAAC,CAOtC;AAED,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,0BAA0B,CAAC,CAOrC;AAED,wBAAsB,WAAW,CAC/B,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE;IACP,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CACzD,GACA,OAAO,CAAC,qBAAqB,CAAC,CAMhC;AAED,wBAAsB,UAAU,CAC9B,SAAS,EAAE,sBAAsB,EACjC,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,+BAA+B,CAAC,CAmB1C"}
+{"version":3,"file":"stac.d.ts","sourceRoot":"","sources":["../../../src/core/stac.ts"],"names":[],"mappings":"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"}