@honua/sdk-esri-compat 0.0.6-alpha.0

package/core/ogc-processes.js

@@ -0,0 +1,325 @@
+/**
+ * OGC API Processes surface. Process discovery, execution, and async
+ * job tracking. Per the ticket constraint, async executions return an
+ * `IJobRun` (the canonical async-operation surface) rather than an
+ * OGC-specific job type.
+ *
+ * @module
+ */
+import { isJobTerminal } from "../contract/jobs.js";
+const DEFAULT_POLL_INTERVAL_MS = 1_000;
+/** Top-level OGC API Processes handle. */
+export class HonuaOgcProcesses {
+    client;
+    constructor(options) {
+        this.client = options.client;
+    }
+    async landing(request = {}) {
+        return this.client.getOgcProcessesLanding(request);
+    }
+    async conformance(request = {}) {
+        return this.client.getOgcProcessesConformance(request);
+    }
+    async list(request = {}) {
+        return this.client.listOgcProcesses(request);
+    }
+    async describe(processId, request = {}) {
+        return this.client.getOgcProcess({ ...request, processId });
+    }
+    /**
+     * Submit a process for execution. Always returns an `IJobRun`: honua-server
+     * is async-only (advertises `jobControlOptions: ['async-execute', 'dismiss']`),
+     * so the runner polls for the terminal snapshot regardless of whether
+     * `mode` is `"async"` or `"auto"`.
+     */
+    async execute(request) {
+        const accepted = await this.client.executeOgcProcess(request);
+        return new HonuaOgcProcessJobRun({
+            client: this.client,
+            jobId: accepted.jobID,
+            processId: accepted.processID ?? request.processId,
+            initialStatus: accepted.statusInfo ?? {
+                jobID: accepted.jobID,
+                processID: accepted.processID ?? request.processId,
+                status: accepted.status,
+            },
+        });
+    }
+    /** Adopt an existing job by id (useful when reconnecting after navigation). */
+    job(jobId, options = {}) {
+        return new HonuaOgcProcessJobRun({
+            client: this.client,
+            jobId,
+            processId: options.processId,
+        });
+    }
+}
+/**
+ * `IJobRun` implementation backed by OGC API Processes 1.0 status / result
+ * endpoints. Watchers receive the latest `JobSnapshot` when status,
+ * progress, or terminal result changes; cancel is idempotent and races
+ * the server's `dismissed` response against any concurrent terminal
+ * transition.
+ */
+export class HonuaOgcProcessJobRun {
+    id;
+    type;
+    client;
+    pollIntervalMs;
+    pollFn;
+    currentStatus;
+    currentProgress;
+    terminalSnapshot;
+    terminalPromise;
+    listeners = new Set();
+    constructor(options) {
+        this.client = options.client;
+        this.id = options.jobId;
+        this.type = options.processId ?? options.initialStatus?.processID ?? "unknown";
+        this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        this.pollFn = options.pollFn ?? ((jobId, signal) => options.client.getOgcProcessJob({ jobId, signal }));
+        const initial = options.initialStatus;
+        this.currentStatus = initial?.status ?? "accepted";
+        this.currentProgress = progressFromOgcStatus(initial);
+    }
+    get status() {
+        return this.currentStatus;
+    }
+    get progress() {
+        return this.currentProgress;
+    }
+    async poll() {
+        if (this.terminalSnapshot) {
+            return this.terminalSnapshot;
+        }
+        const ogcStatus = await this.pollFn(this.id);
+        return this.handleOgcStatus(ogcStatus);
+    }
+    watch(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    async results() {
+        if (!this.terminalPromise) {
+            this.terminalPromise = this.runUntilTerminal();
+        }
+        return this.terminalPromise;
+    }
+    async cancel() {
+        if (this.terminalSnapshot) {
+            return this.currentStatus;
+        }
+        try {
+            const cancelled = await this.client.cancelOgcProcessJob({ jobId: this.id });
+            const snapshot = await this.handleOgcStatus(cancelled);
+            return snapshot.status;
+        }
+        catch (error) {
+            const statusCode = error?.statusCode;
+            // `IJobRun.cancel` is documented as idempotent: when the job is
+            // already gone (404), return the cached status. honua-server uses
+            // 409 for three distinct cases — only the terminal-race case is
+            // benign:
+            //   - "Cannot dismiss completed job" → terminal race; poll for the
+            //     authoritative terminal status and return it.
+            //   - "Dismiss could not be confirmed" → backend dismissal request
+            //     was issued but did not confirm; rethrow so callers can retry.
+            //   - "Cancellation not supported" → backend lacks cancel support;
+            //     rethrow so callers can branch.
+            // Any 409 with an unknown title also rethrows. The terminal-race
+            // branch only swallows the 409 when the follow-up poll reaches a
+            // terminal status; a non-terminal poll or a poll failure means the
+            // "completed job" claim cannot be confirmed and the original 409
+            // is the most honest signal.
+            if (statusCode === 404) {
+                return this.currentStatus;
+            }
+            if (statusCode === 409 && isCompletedJobConflict(error)) {
+                let fresh;
+                try {
+                    fresh = await this.pollFn(this.id);
+                }
+                catch {
+                    // Server claimed the job is in a terminal state but the
+                    // follow-up poll could not confirm it. Surface the original
+                    // 409 instead of letting the poll-side error swallow it.
+                    throw error;
+                }
+                const snapshot = await this.handleOgcStatus(fresh);
+                if (!isJobTerminal(snapshot.status)) {
+                    throw error;
+                }
+                return snapshot.status;
+            }
+            throw error;
+        }
+    }
+    async runUntilTerminal() {
+        while (!this.terminalSnapshot) {
+            const ogcStatus = await this.pollFn(this.id);
+            await this.handleOgcStatus(ogcStatus);
+            if (this.terminalSnapshot)
+                break;
+            if (this.pollIntervalMs > 0) {
+                await delay(this.pollIntervalMs);
+            }
+        }
+        if (this.terminalSnapshot.status === "successful" && this.terminalSnapshot.result) {
+            return this.terminalSnapshot.result;
+        }
+        throw makeJobFailedError(this.terminalSnapshot);
+    }
+    /**
+     * Translate an OGC `statusInfo` payload onto the canonical snapshot
+     * surface, fire watchers, and (for `successful` terminals) fetch the
+     * result document inline so the snapshot's `result.outputs` is
+     * populated by the time `runUntilTerminal` / `poll` resolves.
+     */
+    async handleOgcStatus(ogcStatus) {
+        const status = ogcStatus.status ?? "accepted";
+        const progress = progressFromOgcStatus(ogcStatus);
+        this.currentStatus = status;
+        this.currentProgress = progress;
+        if (status === "successful") {
+            try {
+                // Per OGC API Processes §7.11.1 the document-mode result body is the
+                // outputs map itself (honua-server returns `{}` for the canonical
+                // V1 process; populated maps are keyed by output id). Wrap it into
+                // the canonical `JobResult.outputs` envelope.
+                const results = await this.client.getOgcProcessJobResults({ jobId: this.id });
+                const snapshot = {
+                    status: "successful",
+                    progress,
+                    result: { outputs: results },
+                };
+                this.terminalSnapshot = snapshot;
+                this.notify(snapshot);
+                return snapshot;
+            }
+            catch (error) {
+                const failure = {
+                    status: "failed",
+                    progress,
+                    error: {
+                        code: error?.name ?? "ResultsFetchFailed",
+                        message: error instanceof Error ? error.message : String(error),
+                    },
+                };
+                this.currentStatus = "failed";
+                this.terminalSnapshot = failure;
+                this.notify(failure);
+                return failure;
+            }
+        }
+        if (status === "failed" || status === "dismissed") {
+            const error = terminalJobError(status, ogcStatus);
+            const snapshot = {
+                status,
+                progress,
+                ...(error ? { error } : {}),
+            };
+            this.terminalSnapshot = snapshot;
+            this.notify(snapshot);
+            return snapshot;
+        }
+        const snapshot = { status, progress };
+        this.notify(snapshot);
+        return snapshot;
+    }
+    notify(snapshot) {
+        for (const listener of this.listeners) {
+            try {
+                listener(snapshot);
+            }
+            catch {
+                // Listener exceptions must not break the runner; log silently.
+            }
+        }
+    }
+}
+/** Error thrown when `IJobRun.results()` resolves a non-success terminal. */
+export class HonuaJobFailedError extends Error {
+    status;
+    errorCode;
+    details;
+    constructor(message, status, errorCode, details) {
+        super(message);
+        this.name = "HonuaJobFailedError";
+        this.status = status;
+        this.errorCode = errorCode;
+        this.details = details;
+    }
+}
+/**
+ * Honua-server emits problem-details JSON for DELETE /jobs/{id} 409s. The
+ * `title` distinguishes the benign terminal race ("Cannot dismiss
+ * completed job") from non-benign 409s ("Dismiss could not be confirmed",
+ * "Cancellation not supported"). The detail text mirrors the title
+ * ("terminal state '...'") so we accept either as confirmation.
+ */
+function isCompletedJobConflict(error) {
+    const body = error?.body;
+    if (!body || typeof body !== "object")
+        return false;
+    const title = body.title;
+    const detail = body.detail;
+    if (typeof title === "string" && /cannot dismiss completed job/i.test(title)) {
+        return true;
+    }
+    if (typeof detail === "string" && /terminal state/i.test(detail)) {
+        return true;
+    }
+    return false;
+}
+function terminalJobError(status, ogcStatus) {
+    if (ogcStatus.exception) {
+        return { ...ogcStatus.exception };
+    }
+    // honua-server emits failure text as `statusInfo.message` (its
+    // StatusInfo DTO has no `exception` field). Fall back to the progress
+    // message so `HonuaJobFailedError.message` carries the server reason
+    // instead of the generic "non-success terminal state" default.
+    if (typeof ogcStatus.message === "string" && ogcStatus.message.length > 0) {
+        return {
+            code: status === "dismissed" ? "JobDismissed" : "JobFailed",
+            message: ogcStatus.message,
+        };
+    }
+    return undefined;
+}
+function progressFromOgcStatus(ogcStatus) {
+    if (!ogcStatus)
+        return undefined;
+    const out = {};
+    if (typeof ogcStatus.progress === "number" && Number.isFinite(ogcStatus.progress)) {
+        out.percent = clampPercent(ogcStatus.progress);
+    }
+    if (ogcStatus.message !== undefined)
+        out.message = ogcStatus.message;
+    if (ogcStatus.updated !== undefined)
+        out.updatedAt = ogcStatus.updated;
+    if (out.percent === undefined && out.message === undefined && out.updatedAt === undefined) {
+        return undefined;
+    }
+    return out;
+}
+function clampPercent(value) {
+    if (value < 0)
+        return 0;
+    if (value > 100)
+        return 100;
+    return value;
+}
+function makeJobFailedError(snapshot) {
+    const error = snapshot.error;
+    const message = error?.message ?? `Job ended in non-success terminal state: ${snapshot.status}`;
+    return new HonuaJobFailedError(message, snapshot.status, error?.code, error?.details);
+}
+function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+export function createHonuaOgcProcesses(client) {
+    return new HonuaOgcProcesses({ client });
+}

package/core/ogc-tiles.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 { HonuaClient } from "./client.js";
+import type { HonuaOgcConformanceResponse, HonuaOgcLandingResponse, HonuaOgcTileMatrixSet, HonuaOgcTileMatrixSetsResponse, HonuaOgcTileResponse, HonuaOgcTilesetMetadata, HonuaOgcTilesetsResponse, OgcMetadataRequest, OgcTileRequest, OgcTilesetRequest, OgcTilesetsRequest } from "./types.js";
+export interface HonuaOgcTilesOptions {
+    client: HonuaClient;
+}
+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>;
+}
+/**
+ * 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;
+//# 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":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EACV,2BAA2B,EAC3B,uBAAuB,EACvB,qBAAqB,EACrB,8BAA8B,EAC9B,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,WAAW,CAAC;IACpB,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,gCAAgC,GAAG,IAAI,CAAC,iBAAiB,EAAE,cAAc,GAAG,iBAAiB,CAAC,CAAC;AAC3G,MAAM,MAAM,iCAAiC,GAAG,IAAI,CAAC,kBAAkB,EAAE,cAAc,CAAC,CAAC;AACzF,MAAM,MAAM,6BAA6B,GAAG,IAAI,CAAC,cAAc,EAAE,cAAc,GAAG,iBAAiB,CAAC,CAAC;AAErG;;;GAGG;AACH,qBAAa,aAAa;IACxB,SAAgB,MAAM,EAAE,WAAW,CAAC;gBAEjB,OAAO,EAAE,oBAAoB;IAIzC,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,eAAe;IAQ1E,OAAO,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAI3E,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,2BAA2B,CAAC;IAInF,cAAc,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,8BAA8B,CAAC;IAIzF,aAAa,CACxB,eAAe,EAAE,MAAM,EACvB,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,qBAAqB,CAAC;IAIpB,QAAQ,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,wBAAwB,CAAC;IAIxE,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAI7E,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAG1E;AAED;;;;;;GAMG;AACH,qBAAa,eAAe;IAC1B,SAAgB,MAAM,EAAE,WAAW,CAAC;IACpC,SAAgB,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9C,SAAgB,eAAe,EAAE,MAAM,CAAC;gBAErB,OAAO,EAAE,sBAAsB;IAMrC,QAAQ,CAAC,OAAO,GAAE,gCAAqC,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAQ1F,IAAI,CAAC,OAAO,EAAE,6BAA6B,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAOzF;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,GAAG,aAAa,CAEtE"}

package/core/ogc-tiles.js

@@ -0,0 +1,81 @@
+/**
+ * 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
+ */
+/**
+ * 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);
+    }
+}
+/**
+ * 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 });
+}

package/core/pbf-decoder.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Minimal protobuf wire-format reader and Esri PBF query response decoder.
+ *
+ * Decodes `FeatureCollectionPBuffer` responses (from `f=pbf`) into the same
+ * JSON-compatible shape as `f=json`, making the binary format transparent
+ * to callers.
+ *
+ * No external protobuf library dependency. Implements only the subset of
+ * the wire format needed for the Esri PBF query schema.
+ *
+ * @module
+ */
+/**
+ * Decode an Esri FeatureCollectionPBuffer response into a JSON-compatible
+ * query response object.
+ *
+ * The returned object has the same shape as an `f=json` response:
+ * `{ objectIdFieldName, geometryType, spatialReference, fields, features, ... }`
+ *
+ * @param buffer - The raw PBF bytes from a `f=pbf` response.
+ * @returns A JSON-compatible query response object.
+ */
+export declare function decodePbfQueryResponse(buffer: ArrayBuffer | Uint8Array): Record<string, unknown>;
+/**
+ * Check whether a Response has a protobuf content type.
+ */
+export declare function isPbfResponse(response: Response): boolean;
+//# sourceMappingURL=pbf-decoder.d.ts.map

package/core/pbf-decoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pbf-decoder.d.ts","sourceRoot":"","sources":["../../../src/core/pbf-decoder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAmkBH;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,WAAW,GAAG,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiChG;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAGzD"}