@honua/react 0.0.20-alpha.0

package/core/compatibility.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Server compatibility contract parsing and evaluation. Decodes the
+ * `GET /api/v1/admin/capabilities` envelope into the typed
+ * {@link HonuaServerCompatibility} shape, and evaluates it against this
+ * SDK's supported baseline (minimum server version, control-plane API
+ * major/base-path, and release channel). Pure logic with no transport
+ * coupling; the `HonuaClient` facade owns fetching + caching and delegates
+ * the parse/evaluate steps here.
+ *
+ * @module
+ */
+import type { HonuaServerCompatibility } from "./types.js";
+export declare const HONUA_MINIMUM_SUPPORTED_SERVER_VERSION = "1.0.0";
+export declare const MINIMUM_SUPPORTED_SERVER_RELEASE_CHANNEL = "preview";
+export declare function parseCompatibilityEnvelope(payload: unknown): HonuaServerCompatibility;
+export declare function evaluateCompatibility(compatibility: HonuaServerCompatibility): string[];
+export declare function describeCompatibilityError(error: unknown): string;
+//# sourceMappingURL=compatibility.d.ts.map

package/core/compatibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compatibility.d.ts","sourceRoot":"","sources":["../../../src/core/compatibility.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAE3D,eAAO,MAAM,sCAAsC,UAAU,CAAC;AAC9D,eAAO,MAAM,wCAAwC,YAAY,CAAC;AASlE,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,OAAO,GAAG,wBAAwB,CAerF;AAsFD,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,wBAAwB,GAAG,MAAM,EAAE,CA+CvF;AAyFD,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQjE"}

package/core/compatibility.js

@@ -0,0 +1,245 @@
+/**
+ * Server compatibility contract parsing and evaluation. Decodes the
+ * `GET /api/v1/admin/capabilities` envelope into the typed
+ * {@link HonuaServerCompatibility} shape, and evaluates it against this
+ * SDK's supported baseline (minimum server version, control-plane API
+ * major/base-path, and release channel). Pure logic with no transport
+ * coupling; the `HonuaClient` facade owns fetching + caching and delegates
+ * the parse/evaluate steps here.
+ *
+ * @module
+ */
+import { HonuaHttpError } from "./errors.js";
+import { trimTrailingSlashes } from "./path-utils.js";
+export const HONUA_MINIMUM_SUPPORTED_SERVER_VERSION = "1.0.0";
+export const MINIMUM_SUPPORTED_SERVER_RELEASE_CHANNEL = "preview";
+const SUPPORTED_CONTROL_PLANE_API_MAJOR = 1;
+const SUPPORTED_CONTROL_PLANE_API_BASE_PATH = "/api/v1/admin";
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function parseCompatibilityEnvelope(payload) {
+    if (!isObject(payload)) {
+        throw new TypeError("Server capabilities response must be a JSON object.");
+    }
+    if (payload.success === false) {
+        const message = typeof payload.message === "string" ? payload.message : "Server capabilities request failed.";
+        throw new Error(message);
+    }
+    if (!isObject(payload.data)) {
+        throw new TypeError("Server capabilities response is missing a data object.");
+    }
+    return parseCompatibilityContract(payload.data.compatibility);
+}
+function parseCompatibilityContract(payload) {
+    if (!isObject(payload)) {
+        throw new TypeError("Server capabilities response is missing data.compatibility.");
+    }
+    return {
+        serverVersion: requireNonEmptyString(payload.serverVersion, "data.compatibility.serverVersion"),
+        releaseChannel: requireNonEmptyString(payload.releaseChannel, "data.compatibility.releaseChannel"),
+        controlPlaneApi: parseControlPlaneApi(payload.controlPlaneApi),
+        metadataSchemas: parseMetadataSchemas(payload.metadataSchemas),
+        features: parseCompatibilityFeatures(payload.features),
+    };
+}
+function parseControlPlaneApi(payload) {
+    if (!isObject(payload)) {
+        throw new TypeError("Server capabilities response is missing data.compatibility.controlPlaneApi.");
+    }
+    return {
+        major: requireInteger(payload.major, "data.compatibility.controlPlaneApi.major"),
+        basePath: requireNonEmptyString(payload.basePath, "data.compatibility.controlPlaneApi.basePath"),
+        deprecated: requireBoolean(payload.deprecated, "data.compatibility.controlPlaneApi.deprecated"),
+    };
+}
+function parseMetadataSchemas(payload) {
+    if (!Array.isArray(payload)) {
+        throw new TypeError("Server capabilities response is missing data.compatibility.metadataSchemas.");
+    }
+    return payload.map((entry, index) => {
+        if (!isObject(entry)) {
+            throw new TypeError(`Server capabilities response metadataSchemas[${index}] must be an object.`);
+        }
+        return {
+            version: requireNonEmptyString(entry.version, `data.compatibility.metadataSchemas[${index}].version`),
+            deprecated: requireBoolean(entry.deprecated, `data.compatibility.metadataSchemas[${index}].deprecated`),
+        };
+    });
+}
+function parseCompatibilityFeatures(payload) {
+    if (!isObject(payload)) {
+        throw new TypeError("Server capabilities response is missing data.compatibility.features.");
+    }
+    return {
+        metadataResources: requireBoolean(payload.metadataResources, "data.compatibility.features.metadataResources"),
+        manifestExport: requireBoolean(payload.manifestExport, "data.compatibility.features.manifestExport"),
+        manifestApply: requireBoolean(payload.manifestApply, "data.compatibility.features.manifestApply"),
+        manifestDryRun: requireBoolean(payload.manifestDryRun, "data.compatibility.features.manifestDryRun"),
+        manifestPrune: requireBoolean(payload.manifestPrune, "data.compatibility.features.manifestPrune"),
+    };
+}
+function requireNonEmptyString(value, fieldName) {
+    if (typeof value !== "string") {
+        throw new TypeError(`${fieldName} must be a string.`);
+    }
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        throw new TypeError(`${fieldName} must not be empty.`);
+    }
+    return trimmed;
+}
+function requireBoolean(value, fieldName) {
+    if (typeof value !== "boolean") {
+        throw new TypeError(`${fieldName} must be a boolean.`);
+    }
+    return value;
+}
+function requireInteger(value, fieldName) {
+    if (typeof value !== "number" || !Number.isInteger(value)) {
+        throw new TypeError(`${fieldName} must be an integer.`);
+    }
+    return value;
+}
+export function evaluateCompatibility(compatibility) {
+    const reasons = [];
+    const minimumVersion = parseVersion(HONUA_MINIMUM_SUPPORTED_SERVER_VERSION);
+    const serverVersion = parseVersion(compatibility.serverVersion);
+    if (!minimumVersion) {
+        reasons.push(`SDK minimum supported version '${HONUA_MINIMUM_SUPPORTED_SERVER_VERSION}' is not parseable for compatibility checks.`);
+        return reasons;
+    }
+    if (!serverVersion) {
+        reasons.push(`Server version '${compatibility.serverVersion}' is not parseable for compatibility checks.`);
+    }
+    else if (compareVersions(serverVersion, minimumVersion) < 0) {
+        reasons.push(`Server version ${compatibility.serverVersion} is older than the minimum supported ${HONUA_MINIMUM_SUPPORTED_SERVER_VERSION}.`);
+    }
+    if (compatibility.controlPlaneApi.major !== SUPPORTED_CONTROL_PLANE_API_MAJOR) {
+        reasons.push(`Control-plane API major ${compatibility.controlPlaneApi.major} is unsupported; expected ${SUPPORTED_CONTROL_PLANE_API_MAJOR}.`);
+    }
+    if (normalizePathValue(compatibility.controlPlaneApi.basePath) !== SUPPORTED_CONTROL_PLANE_API_BASE_PATH) {
+        reasons.push(`Control-plane API base path ${compatibility.controlPlaneApi.basePath} is unsupported; expected ${SUPPORTED_CONTROL_PLANE_API_BASE_PATH}.`);
+    }
+    if (compatibility.controlPlaneApi.deprecated) {
+        reasons.push(`Control-plane API major ${compatibility.controlPlaneApi.major} is marked deprecated by the server.`);
+    }
+    const actualReleaseChannelRank = getReleaseChannelRank(compatibility.releaseChannel);
+    const minimumReleaseChannelRank = getReleaseChannelRank(MINIMUM_SUPPORTED_SERVER_RELEASE_CHANNEL) ?? 0;
+    if (actualReleaseChannelRank === undefined) {
+        reasons.push(`Server release channel '${compatibility.releaseChannel}' is not recognized by this SDK baseline.`);
+    }
+    else if (actualReleaseChannelRank < minimumReleaseChannelRank) {
+        reasons.push(`Server release channel '${compatibility.releaseChannel}' is below the minimum supported '${MINIMUM_SUPPORTED_SERVER_RELEASE_CHANNEL}'.`);
+    }
+    return reasons;
+}
+function parseVersion(version) {
+    const normalized = version.trim().replace(/^v/i, "");
+    if (normalized.length === 0) {
+        return undefined;
+    }
+    const coreAndPrerelease = normalized.split("+", 1)[0] ?? normalized;
+    const [core, prerelease = ""] = coreAndPrerelease.split("-", 2);
+    const numbers = core.split(".").map((segment) => Number.parseInt(segment, 10));
+    if (numbers.length === 0 || numbers.some((segment) => !Number.isFinite(segment))) {
+        return undefined;
+    }
+    const prereleaseParts = prerelease.length > 0
+        ? prerelease
+            .split(".")
+            .map((segment) => segment.trim())
+            .filter((segment) => segment.length > 0)
+        : [];
+    return {
+        numbers,
+        prerelease: prereleaseParts,
+    };
+}
+function compareVersions(left, right) {
+    const length = Math.max(left.numbers.length, right.numbers.length);
+    for (let index = 0; index < length; index += 1) {
+        const leftPart = left.numbers[index] ?? 0;
+        const rightPart = right.numbers[index] ?? 0;
+        if (leftPart !== rightPart) {
+            return leftPart < rightPart ? -1 : 1;
+        }
+    }
+    if (left.prerelease.length === 0 && right.prerelease.length === 0) {
+        return 0;
+    }
+    if (left.prerelease.length === 0) {
+        return 1;
+    }
+    if (right.prerelease.length === 0) {
+        return -1;
+    }
+    const prereleaseLength = Math.max(left.prerelease.length, right.prerelease.length);
+    for (let index = 0; index < prereleaseLength; index += 1) {
+        const leftPart = left.prerelease[index];
+        const rightPart = right.prerelease[index];
+        if (leftPart === undefined) {
+            return -1;
+        }
+        if (rightPart === undefined) {
+            return 1;
+        }
+        if (leftPart === rightPart) {
+            continue;
+        }
+        const leftNumeric = Number.parseInt(leftPart, 10);
+        const rightNumeric = Number.parseInt(rightPart, 10);
+        const leftIsNumeric = String(leftNumeric) === leftPart;
+        const rightIsNumeric = String(rightNumeric) === rightPart;
+        if (leftIsNumeric && rightIsNumeric) {
+            return leftNumeric < rightNumeric ? -1 : 1;
+        }
+        if (leftIsNumeric) {
+            return -1;
+        }
+        if (rightIsNumeric) {
+            return 1;
+        }
+        return leftPart < rightPart ? -1 : 1;
+    }
+    return 0;
+}
+export function describeCompatibilityError(error) {
+    if (error instanceof HonuaHttpError && error.statusCode === 404) {
+        return "Server does not expose GET /api/v1/admin/capabilities.";
+    }
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+function normalizePathValue(path) {
+    const trimmed = path.trim();
+    if (trimmed.length === 0) {
+        return "";
+    }
+    const prefixed = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+    return trimTrailingSlashes(prefixed);
+}
+function getReleaseChannelRank(releaseChannel) {
+    switch (releaseChannel.trim().toLowerCase()) {
+        case "nightly":
+            return 0;
+        case "dev":
+            return 1;
+        case "alpha":
+            return 2;
+        case "preview":
+            return 3;
+        case "beta":
+            return 4;
+        case "rc":
+            return 5;
+        case "stable":
+            return 6;
+        case "lts":
+            return 7;
+        default:
+            return undefined;
+    }
+}

package/core/errors.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Honua SDK error hierarchy. Every error thrown by `@honua/sdk-js` is an
+ * instance of one of the classes in this file plus the runtime-type guard
+ * `isHonuaError(error)`. See [`docs/errors.md`](../../docs/errors.md) for the
+ * full reference table including recovery hints and the retry-policy mapping.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   HonuaHttpError,
+ *   HonuaTimeoutError,
+ *   HonuaCapabilityNotSupportedError,
+ *   isHonuaError,
+ * } from "@honua/sdk-js";
+ *
+ * try {
+ *   await dataset.source("parcels")!.queryAll({ where: "1=1" });
+ * } catch (error) {
+ *   if (!isHonuaError(error)) throw error;
+ *   if (error instanceof HonuaCapabilityNotSupportedError) return fallback();
+ *   if (error instanceof HonuaHttpError && error.statusCode === 401) {
+ *     await refreshCredentials();
+ *     return retry();
+ *   }
+ *   if (error instanceof HonuaTimeoutError) return notifyUser("Server slow");
+ *   throw error;
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { HonuaJobFailedError } from "./ogc-processes.js";
+import { HonuaWmsCapabilitiesParseError } from "./wms-capabilities.js";
+import { HonuaWmtsCapabilitiesParseError } from "./wmts-capabilities.js";
+/**
+ * Thrown when the server returns a non-2xx HTTP status. Branch on
+ * `.statusCode` to decide recovery: refresh credentials on 401/403, respect
+ * `Retry-After` on 429, back off on 5xx, etc.
+ *
+ * @see [`docs/errors.md`](../../docs/errors.md)
+ */
+export declare class HonuaHttpError extends Error {
+    readonly statusCode: number;
+    readonly body: unknown;
+    constructor(statusCode: number, message: string, body: unknown);
+}
+/** Thrown when a request exceeds the configured timeout. */
+export declare class HonuaTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+/** Thrown when a network-level failure occurs (DNS, connection refused, etc.). */
+export declare class HonuaNetworkError extends Error {
+    readonly cause: unknown;
+    constructor(message: string, cause: unknown);
+}
+/** Thrown when a request is aborted via a caller-provided AbortSignal. */
+export declare class HonuaAbortError extends Error {
+    constructor(message?: string);
+}
+/** Thrown when a gRPC-Web request fails, wrapping the underlying ConnectError. */
+export declare class HonuaGrpcError extends Error {
+    readonly code: number;
+    readonly details: unknown;
+    constructor(code: number, message: string, details?: unknown);
+}
+/**
+ * Thrown when a `Source` is asked to perform an operation that the underlying
+ * protocol or server does not support and the active capability policy is
+ * `strict`. The `capability` field names the missing capability so callers can
+ * decide whether to swap protocols, fall back to a degraded strategy, or
+ * surface the limitation to the user.
+ */
+export declare class HonuaCapabilityNotSupportedError extends Error {
+    readonly capability: string;
+    readonly protocol: string;
+    readonly sourceId: string | undefined;
+    constructor(capability: string, protocol: string, sourceId?: string);
+}
+/**
+ * Thrown when an `ExplorationContext` operation is invalid — for example,
+ * dispatching an intent against a context that has been disposed, restoring
+ * an incompatible snapshot, or binding a view that requests a slice that is
+ * not exposed by the current dataset.
+ */
+export declare class HonuaExplorationContextError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Thrown when a WFS server replies with an `ows:ExceptionReport`. Carries the
+ * structured exception metadata so callers can distinguish capability misses
+ * (for example `OperationProcessingFailed`, `InvalidParameterValue`) from
+ * transport / timeout failures. The XML payload is consumed by
+ * `src/core/wfs-capabilities.ts`; raw access lives behind the `protocol("wfs")`
+ * escape hatch.
+ */
+export declare class HonuaWfsExceptionError extends Error {
+    readonly exceptionCode: string;
+    readonly locator: string | undefined;
+    constructor(exceptionCode: string, message: string, locator?: string);
+}
+/** All Honua SDK error types that can be discriminated with `instanceof`. */
+export type HonuaError = HonuaHttpError | HonuaTimeoutError | HonuaNetworkError | HonuaAbortError | HonuaGrpcError | HonuaCapabilityNotSupportedError | HonuaExplorationContextError | HonuaWfsExceptionError | HonuaJobFailedError | HonuaWmsCapabilitiesParseError | HonuaWmtsCapabilitiesParseError;
+/** Type guard that narrows any value to one of the Honua SDK error types. */
+export declare function isHonuaError(error: unknown): error is HonuaError;
+//# sourceMappingURL=errors.d.ts.map

package/core/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,8BAA8B,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,EAAE,+BAA+B,EAAE,MAAM,wBAAwB,CAAC;AAEzE;;;;;;GAMG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,IAAI,EAAE,OAAO,CAAC;gBAEX,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO;CAMtE;AAED,4DAA4D;AAC5D,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,SAAgB,SAAS,EAAE,MAAM,CAAC;gBAEf,SAAS,EAAE,MAAM;CAKrC;AAED,kFAAkF;AAClF,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,SAAyB,KAAK,EAAE,OAAO,CAAC;gBAErB,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAKnD;AAED,0EAA0E;AAC1E,qBAAa,eAAgB,SAAQ,KAAK;gBACrB,OAAO,SAAwB;CAInD;AAED,kFAAkF;AAClF,qBAAa,cAAe,SAAQ,KAAK;IACvC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,OAAO,EAAE,OAAO,CAAC;gBAEd,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAMpE;AAED;;;;;;GAMG;AACH,qBAAa,gCAAiC,SAAQ,KAAK;IACzD,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;gBAE1B,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM;CAW3E;AAED;;;;;GAKG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,SAAgB,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAKjD;AAED;;;;;;;GAOG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,SAAgB,aAAa,EAAE,MAAM,CAAC;IACtC,SAAgB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEzB,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAU5E;AAED,6EAA6E;AAC7E,MAAM,MAAM,UAAU,GAClB,cAAc,GACd,iBAAiB,GACjB,iBAAiB,GACjB,eAAe,GACf,cAAc,GACd,gCAAgC,GAChC,4BAA4B,GAC5B,sBAAsB,GACtB,mBAAmB,GACnB,8BAA8B,GAC9B,+BAA+B,CAAC;AAEpC,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAchE"}

package/core/errors.js

@@ -0,0 +1,156 @@
+/**
+ * Honua SDK error hierarchy. Every error thrown by `@honua/sdk-js` is an
+ * instance of one of the classes in this file plus the runtime-type guard
+ * `isHonuaError(error)`. See [`docs/errors.md`](../../docs/errors.md) for the
+ * full reference table including recovery hints and the retry-policy mapping.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   HonuaHttpError,
+ *   HonuaTimeoutError,
+ *   HonuaCapabilityNotSupportedError,
+ *   isHonuaError,
+ * } from "@honua/sdk-js";
+ *
+ * try {
+ *   await dataset.source("parcels")!.queryAll({ where: "1=1" });
+ * } catch (error) {
+ *   if (!isHonuaError(error)) throw error;
+ *   if (error instanceof HonuaCapabilityNotSupportedError) return fallback();
+ *   if (error instanceof HonuaHttpError && error.statusCode === 401) {
+ *     await refreshCredentials();
+ *     return retry();
+ *   }
+ *   if (error instanceof HonuaTimeoutError) return notifyUser("Server slow");
+ *   throw error;
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { HonuaJobFailedError } from "./ogc-processes.js";
+import { HonuaWmsCapabilitiesParseError } from "./wms-capabilities.js";
+import { HonuaWmtsCapabilitiesParseError } from "./wmts-capabilities.js";
+/**
+ * Thrown when the server returns a non-2xx HTTP status. Branch on
+ * `.statusCode` to decide recovery: refresh credentials on 401/403, respect
+ * `Retry-After` on 429, back off on 5xx, etc.
+ *
+ * @see [`docs/errors.md`](../../docs/errors.md)
+ */
+export class HonuaHttpError extends Error {
+    statusCode;
+    body;
+    constructor(statusCode, message, body) {
+        super(`HTTP ${statusCode}: ${message}`);
+        this.name = "HonuaHttpError";
+        this.statusCode = statusCode;
+        this.body = body;
+    }
+}
+/** Thrown when a request exceeds the configured timeout. */
+export class HonuaTimeoutError extends Error {
+    timeoutMs;
+    constructor(timeoutMs) {
+        super(`Request timed out after ${timeoutMs}ms`);
+        this.name = "HonuaTimeoutError";
+        this.timeoutMs = timeoutMs;
+    }
+}
+/** Thrown when a network-level failure occurs (DNS, connection refused, etc.). */
+export class HonuaNetworkError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = "HonuaNetworkError";
+        this.cause = cause;
+    }
+}
+/** Thrown when a request is aborted via a caller-provided AbortSignal. */
+export class HonuaAbortError extends Error {
+    constructor(message = "Request was aborted") {
+        super(message);
+        this.name = "HonuaAbortError";
+    }
+}
+/** Thrown when a gRPC-Web request fails, wrapping the underlying ConnectError. */
+export class HonuaGrpcError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "HonuaGrpcError";
+        this.code = code;
+        this.details = details;
+    }
+}
+/**
+ * Thrown when a `Source` is asked to perform an operation that the underlying
+ * protocol or server does not support and the active capability policy is
+ * `strict`. The `capability` field names the missing capability so callers can
+ * decide whether to swap protocols, fall back to a degraded strategy, or
+ * surface the limitation to the user.
+ */
+export class HonuaCapabilityNotSupportedError extends Error {
+    capability;
+    protocol;
+    sourceId;
+    constructor(capability, protocol, sourceId) {
+        super(sourceId
+            ? `Capability "${capability}" is not supported by protocol "${protocol}" on source "${sourceId}"`
+            : `Capability "${capability}" is not supported by protocol "${protocol}"`);
+        this.name = "HonuaCapabilityNotSupportedError";
+        this.capability = capability;
+        this.protocol = protocol;
+        this.sourceId = sourceId;
+    }
+}
+/**
+ * Thrown when an `ExplorationContext` operation is invalid — for example,
+ * dispatching an intent against a context that has been disposed, restoring
+ * an incompatible snapshot, or binding a view that requests a slice that is
+ * not exposed by the current dataset.
+ */
+export class HonuaExplorationContextError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "HonuaExplorationContextError";
+        this.code = code;
+    }
+}
+/**
+ * Thrown when a WFS server replies with an `ows:ExceptionReport`. Carries the
+ * structured exception metadata so callers can distinguish capability misses
+ * (for example `OperationProcessingFailed`, `InvalidParameterValue`) from
+ * transport / timeout failures. The XML payload is consumed by
+ * `src/core/wfs-capabilities.ts`; raw access lives behind the `protocol("wfs")`
+ * escape hatch.
+ */
+export class HonuaWfsExceptionError extends Error {
+    exceptionCode;
+    locator;
+    constructor(exceptionCode, message, locator) {
+        super(locator
+            ? `WFS ExceptionReport ${exceptionCode} (${locator}): ${message}`
+            : `WFS ExceptionReport ${exceptionCode}: ${message}`);
+        this.name = "HonuaWfsExceptionError";
+        this.exceptionCode = exceptionCode;
+        this.locator = locator;
+    }
+}
+/** Type guard that narrows any value to one of the Honua SDK error types. */
+export function isHonuaError(error) {
+    return (error instanceof HonuaHttpError ||
+        error instanceof HonuaTimeoutError ||
+        error instanceof HonuaNetworkError ||
+        error instanceof HonuaAbortError ||
+        error instanceof HonuaGrpcError ||
+        error instanceof HonuaCapabilityNotSupportedError ||
+        error instanceof HonuaExplorationContextError ||
+        error instanceof HonuaWfsExceptionError ||
+        error instanceof HonuaJobFailedError ||
+        error instanceof HonuaWmsCapabilitiesParseError ||
+        error instanceof HonuaWmtsCapabilitiesParseError);
+}

package/core/esri-geojson.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Convert Esri-JSON geometry (as returned by `queryFeatures` and contract
+ * {@link HonuaFeature} results) into standard GeoJSON geometry.
+ *
+ * Esri encodes geometry as `{ x, y }` points, `{ paths }` polylines,
+ * `{ rings }` polygons, `{ points }` multipoints, and `{ xmin, ymin, xmax,
+ * ymax }` envelopes. GeoJSON consumers (MapLibre, Leaflet, turf, etc.) expect
+ * `Point` / `LineString` / `Polygon` and their `Multi*` variants. This module
+ * provides that translation as a first-class, dependency-free utility.
+ *
+ * Polygon rings are grouped following the Esri convention where clockwise
+ * rings are exterior and counter-clockwise rings are holes, producing `Polygon`
+ * for a single exterior ring and `MultiPolygon` when several exterior rings are
+ * present. The emitted rings are rewound to the GeoJSON RFC 7946 right-hand rule
+ * (counter-clockwise exterior, clockwise holes) so conformant consumers do not
+ * interpret polygons inside-out.
+ *
+ * @module
+ */
+import type { GeoJsonGeometry } from "../expr/expression.js";
+import type { EsriGeometry, GeoJsonFeature, HonuaFeature, HonuaSpatialReference } from "./types.js";
+/**
+ * Convert a single Esri-JSON geometry into a GeoJSON geometry.
+ *
+ * Supports Esri point (`{ x, y }`), multipoint (`{ points }`), polyline
+ * (`{ paths }`), polygon (`{ rings }`), and envelope (`{ xmin, ymin, xmax,
+ * ymax }`) shapes. Returns `null` for `null`/`undefined` input and for
+ * geometries that contain no finite coordinates (e.g. empty `rings`/`paths`).
+ *
+ * @param geometry Esri geometry, the `geometry` field of a {@link HonuaFeature},
+ *   or `null`/`undefined`.
+ * @returns The equivalent GeoJSON geometry, or `null` when the input is empty
+ *   or unrecognized.
+ */
+export declare function esriGeometryToGeoJSON(geometry: EsriGeometry | Record<string, unknown> | null | undefined): GeoJsonGeometry | null;
+/**
+ * Convert a contract {@link HonuaFeature} (Esri attributes + geometry) into a
+ * GeoJSON `Feature`.
+ *
+ * The feature `id` is derived from common Esri identifier attributes
+ * (`OBJECTID`, `objectid`, `id`, `ID`, `FID`) when present, and the geometry is
+ * converted with {@link esriGeometryToGeoJSON} (yielding `null` for missing or
+ * empty geometry).
+ *
+ * @param feature A contract feature with Esri-shaped `attributes` and
+ *   `geometry`.
+ * @returns The equivalent GeoJSON feature.
+ */
+export declare function esriFeatureToGeoJSON(feature: HonuaFeature): GeoJsonFeature;
+/**
+ * Convert a standard GeoJSON geometry back into Esri-JSON geometry, the inverse
+ * of {@link esriGeometryToGeoJSON}. `GeometryCollection` is not representable as
+ * a single Esri geometry and yields `null`.
+ *
+ * Polygon/MultiPolygon rings are rewound to the Esri winding convention
+ * (clockwise exterior, counter-clockwise holes) and MultiPolygons are flattened
+ * into a single `{ rings }` list, matching how Esri encodes multi-part polygons.
+ *
+ * @param geometry A GeoJSON geometry, or `null`/`undefined`.
+ * @param spatialReference Optional spatial reference stamped onto the emitted
+ *   Esri geometry (Esri geometries are CRS-tagged; GeoJSON is implicitly WGS84).
+ * @returns The equivalent Esri geometry, or `null` when the input is empty or
+ *   unrepresentable.
+ */
+export declare function geoJsonToEsriGeometry(geometry: GeoJsonGeometry | null | undefined, spatialReference?: HonuaSpatialReference): EsriGeometry | null;
+//# sourceMappingURL=esri-geojson.d.ts.map

package/core/esri-geojson.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"esri-geojson.d.ts","sourceRoot":"","sources":["../../../src/core/esri-geojson.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EACV,eAAe,EAIhB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EACV,YAAY,EAKZ,cAAc,EACd,YAAY,EACZ,qBAAqB,EACtB,MAAM,YAAY,CAAC;AA0MpB;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAClE,eAAe,GAAG,IAAI,CA0ExB;AAkBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG,cAAc,CAQ1E;AAyBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,EAC5C,gBAAgB,CAAC,EAAE,qBAAqB,GACvC,YAAY,GAAG,IAAI,CAuCrB"}