@honua/react 0.1.7-beta.0 → 0.1.10-beta.0

package/core/errors.d.ts

@@ -30,7 +30,17 @@
  *
  * @packageDocumentation
  */
-import { type HonuaErrorMetadata, type HonuaErrorOptions, HonuaSdkError } from "./error-envelope.js";
+import { type HonuaErrorMetadata, type HonuaErrorOptions, type HonuaFailureKind, type HonuaFieldFailure, type HonuaProtocolMetadata, HonuaSdkError, type HonuaTerminalFailureReceipt } from "./error-envelope.js";
+export type { HonuaFailureKind, HonuaFieldFailure, HonuaProtocolMetadata, HonuaTerminalFailureReceipt };
+export interface HonuaHttpErrorOptions extends HonuaErrorOptions {
+    readonly responseHeaders?: Pick<Headers, "entries" | "get"> | Readonly<Record<string, string | readonly string[]>>;
+    readonly protocolCode?: number | string;
+    readonly transportStatus?: number;
+}
+export interface HonuaGrpcErrorOptions extends HonuaErrorOptions {
+    readonly initialMetadata?: unknown;
+    readonly trailingMetadata?: unknown;
+}
 export type HonuaDiscoveryErrorCode = "ambiguous-protocol" | "ambiguous-source" | "invalid-cloud-native-input" | "invalid-cloud-native-manifest" | "invalid-endpoint" | "invalid-cache-identity" | "invalid-discovery-cache" | "invalid-capability" | "cloud-native-operation-unavailable" | "unsupported-protocol" | "protocol-mismatch";
 /** Discovery input, metadata, or cache identity is invalid or inconsistent. */
 export declare class HonuaDiscoveryError extends HonuaSdkError {
@@ -60,7 +70,8 @@ export declare class HonuaGeometryError extends HonuaSdkError {
 export declare class HonuaHttpError extends HonuaSdkError {
     readonly statusCode: number;
     readonly body: unknown;
-    constructor(statusCode: number, message: string, body: unknown, options?: HonuaErrorOptions);
+    readonly receipt: HonuaTerminalFailureReceipt;
+    constructor(statusCode: number, message: string, body: unknown, options?: HonuaHttpErrorOptions);
 }
 /** Thrown when a request exceeds the configured timeout. */
 export declare class HonuaTimeoutError extends HonuaSdkError {
@@ -80,7 +91,8 @@ export declare class HonuaAbortError extends HonuaSdkError {
 export declare class HonuaGrpcError extends HonuaSdkError {
     readonly code: number;
     readonly details: unknown;
-    constructor(code: number, message: string, details?: unknown, options?: HonuaErrorOptions);
+    readonly receipt: HonuaTerminalFailureReceipt;
+    constructor(code: number, message: string, details?: unknown, options?: HonuaGrpcErrorOptions);
 }
 /**
  * Thrown when a `Source` is asked to perform an operation that the underlying

package/core/errors.d.ts.map

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

package/core/errors.js

@@ -73,14 +73,19 @@ export class HonuaGeometryError extends HonuaSdkError {
 export class HonuaHttpError extends HonuaSdkError {
     statusCode;
     body;
+    receipt;
     constructor(statusCode, message, body, options = {}) {
-        super(HTTP_RETRYABLE_STATUSES.has(statusCode) ? "core.http.transient" : "core.http.rejected", `HTTP ${statusCode}: ${message}`, {
+        const receipt = httpFailureReceipt(statusCode, body, options);
+        super(receipt.retryable ? "core.http.transient" : "core.http.rejected", `HTTP ${statusCode}: ${message}`, {
             ...options,
+            requestId: options.requestId ?? receipt.correlationId,
+            terminalReceipt: receipt,
             context: mergeHonuaErrorContext(options.context, { statusCode }),
         });
         this.name = "HonuaHttpError";
         this.statusCode = statusCode;
         this.body = body;
+        this.receipt = receipt;
     }
 }
 /** Thrown when a request exceeds the configured timeout. */
@@ -115,14 +120,19 @@ export class HonuaAbortError extends HonuaSdkError {
 export class HonuaGrpcError extends HonuaSdkError {
     code;
     details;
+    receipt;
     constructor(code, message, details, options = {}) {
-        super(GRPC_RETRYABLE_CODES.has(code) ? "core.grpc.transient" : "core.grpc.rejected", message, {
+        const receipt = grpcFailureReceipt(code, details, options);
+        super(receipt.retryable ? "core.grpc.transient" : "core.grpc.rejected", message, {
             ...options,
+            requestId: options.requestId ?? receipt.correlationId,
+            terminalReceipt: receipt,
             context: mergeHonuaErrorContext(options.context, { grpcCode: code }),
         });
         this.code = code;
         this.name = "HonuaGrpcError";
         this.details = details;
+        this.receipt = receipt;
     }
 }
 /**
@@ -221,3 +231,245 @@ const AUTH_ERROR_CODES = {
     refresh_failed: "core.auth.refresh-failed",
     invalid_grant: "core.auth.invalid-grant",
 };
+function httpFailureReceipt(statusCode, body, options) {
+    const root = isObject(body) ? body : undefined;
+    const protocolError = root && isObject(root.error) ? root.error : undefined;
+    const source = protocolError ?? root;
+    const protocolCode = options.protocolCode ?? scalarCode(protocolError?.code);
+    const classificationCode = typeof protocolCode === "number" ? protocolCode : statusCode;
+    const metadata = metadataRecord(options.responseHeaders);
+    const bodyKind = stringValue(source?.kind);
+    const kind = isFailureKind(bodyKind) ? bodyKind : failureKindForHttp(classificationCode, statusCode);
+    const code = stringValue(source?.machineCode) ?? stringValue(source?.code) ?? stringValue(root?.code) ?? defaultCode(kind);
+    const explicitRetryable = booleanValue(source?.retryable) ?? booleanValue(root?.retryable);
+    const retryAfterSeconds = numberValue(source?.retryAfterSeconds) ?? numberValue(root?.retryAfterSeconds);
+    const headerDelay = parseRetryAfter(metadataGetter(options.responseHeaders));
+    const correlationId = stringValue(source?.correlationId) ??
+        stringValue(root?.correlationId) ??
+        firstMetadata(metadata, "x-correlation-id", "honua-request-id", "x-request-id", "honua-correlation-id");
+    const fieldErrors = parseFieldFailures(source?.errors ?? root?.errors);
+    return freezeReceipt({
+        transportStatus: options.transportStatus ?? statusCode,
+        ...(protocolCode !== undefined ? { protocolCode } : {}),
+        kind,
+        ...(code ? { code } : {}),
+        retryable: explicitRetryable ??
+            (HTTP_RETRYABLE_STATUSES.has(classificationCode) ||
+                HTTP_RETRYABLE_STATUSES.has(options.transportStatus ?? statusCode)),
+        ...(retryAfterSeconds !== undefined
+            ? { retryAfterMs: Math.max(0, retryAfterSeconds * 1_000) }
+            : headerDelay !== undefined
+                ? { retryAfterMs: headerDelay }
+                : {}),
+        ...(correlationId ? { correlationId } : {}),
+        fieldErrors,
+        protocolMetadata: { initial: metadata, trailing: emptyMetadata() },
+    });
+}
+function grpcFailureReceipt(code, details, options) {
+    const initial = metadataRecord(options.initialMetadata);
+    const trailing = metadataRecord(options.trailingMetadata);
+    const declaredMachineCode = firstMetadata(trailing, "honua-error-code") ?? firstMetadata(initial, "honua-error-code");
+    const declaredKind = firstMetadata(trailing, "honua-error-kind") ?? firstMetadata(initial, "honua-error-kind");
+    const kind = isFailureKind(declaredKind) ? declaredKind : failureKindForGrpc(code);
+    const machineCode = declaredMachineCode ?? defaultCode(kind);
+    const declaredRetryable = firstMetadata(trailing, "honua-retryable", "honua-error-retryable") ??
+        firstMetadata(initial, "honua-retryable", "honua-error-retryable");
+    const retryAfterMs = parseRetryAfter(metadataGetterFromRecords(trailing, initial));
+    const correlationId = firstMetadata(trailing, "x-correlation-id", "honua-request-id", "x-request-id", "honua-correlation-id") ??
+        firstMetadata(initial, "x-correlation-id", "honua-request-id", "x-request-id", "honua-correlation-id");
+    const encodedErrors = firstMetadata(trailing, "honua-error-details") ?? firstMetadata(initial, "honua-error-details");
+    return freezeReceipt({
+        protocolCode: code,
+        kind,
+        code: machineCode,
+        retryable: parseBoolean(declaredRetryable) ?? GRPC_RETRYABLE_CODES.has(code),
+        ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+        ...(correlationId ? { correlationId } : {}),
+        fieldErrors: parseEncodedFieldFailures(encodedErrors, details),
+        protocolMetadata: { initial, trailing },
+    });
+}
+function failureKindForHttp(code, transportStatus) {
+    if (code === 401 || code === 498 || code === 499)
+        return "authentication";
+    if (code === 403)
+        return "authorization";
+    if (code === 404)
+        return "not-found";
+    if (code === 400 || code === 422)
+        return "validation";
+    if (code === 409 || code === 412 || code === 428)
+        return "conflict";
+    if (code === 429)
+        return "throttled";
+    if (HTTP_RETRYABLE_STATUSES.has(code) || transportStatus >= 500)
+        return "unavailable";
+    return "unknown";
+}
+function failureKindForGrpc(code) {
+    if (code === 16)
+        return "authentication";
+    if (code === 7)
+        return "authorization";
+    if (code === 5)
+        return "not-found";
+    if (code === 3)
+        return "validation";
+    if (code === 10 || code === 6)
+        return "conflict";
+    if (code === 8)
+        return "throttled";
+    if (GRPC_RETRYABLE_CODES.has(code))
+        return "unavailable";
+    return "unknown";
+}
+function defaultCode(kind) {
+    return {
+        authentication: "authentication_required",
+        authorization: "permission_denied",
+        "not-found": "resource_not_found",
+        validation: "validation_failed",
+        conflict: "resource_conflict",
+        throttled: "rate_limit_exceeded",
+        unavailable: "service_unavailable",
+        unknown: "unknown_failure",
+    }[kind];
+}
+function metadataRecord(value) {
+    const result = Object.create(null);
+    const add = (key, item) => {
+        const normalized = key.toLowerCase();
+        if (SENSITIVE_METADATA_KEYS.has(normalized))
+            return;
+        const values = Array.isArray(item)
+            ? item.filter((entry) => typeof entry === "string")
+            : [String(item)];
+        if (values.length > 0)
+            result[normalized] = Object.freeze(values.slice(0, 20));
+    };
+    if (value && typeof value.entries === "function") {
+        for (const [key, item] of value.entries())
+            add(key, item);
+    }
+    else if (isObject(value)) {
+        for (const [key, item] of Object.entries(value))
+            add(key, item);
+    }
+    return Object.freeze(result);
+}
+function metadataGetter(value) {
+    if (value && typeof value.get === "function")
+        return value;
+    return metadataGetterFromRecords(metadataRecord(value));
+}
+function metadataGetterFromRecords(...records) {
+    return {
+        get(name) {
+            for (const record of records) {
+                const value = firstMetadata(record, name);
+                if (value)
+                    return value;
+            }
+            return null;
+        },
+    };
+}
+function firstMetadata(record, ...keys) {
+    for (const key of keys) {
+        const value = record[key.toLowerCase()]?.[0];
+        if (value)
+            return value;
+    }
+    return undefined;
+}
+function parseRetryAfter(headers) {
+    const value = headers.get("retry-after");
+    if (!value)
+        return undefined;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return seconds * 1_000;
+    const target = Date.parse(value);
+    return Number.isFinite(target) ? Math.max(0, target - Date.now()) : undefined;
+}
+function parseEncodedFieldFailures(encoded, details) {
+    if (encoded) {
+        try {
+            return parseFieldFailures(JSON.parse(encoded));
+        }
+        catch {
+            return [];
+        }
+    }
+    return parseFieldFailures(details);
+}
+function parseFieldFailures(value) {
+    if (!Array.isArray(value))
+        return Object.freeze([]);
+    return Object.freeze(value.filter(isObject).map((item) => {
+        const code = stringValue(item.code);
+        const severity = stringValue(item.severity);
+        const path = stringValue(item.path);
+        const fieldId = stringValue(item.fieldId);
+        const itemIndex = numberValue(item.itemIndex);
+        const message = stringValue(item.message);
+        return Object.freeze({
+            ...(code ? { code } : {}),
+            ...(severity ? { severity } : {}),
+            ...(path ? { path } : {}),
+            ...(fieldId ? { fieldId } : {}),
+            ...(itemIndex !== undefined ? { itemIndex } : {}),
+            ...(message ? { message } : {}),
+        });
+    }));
+}
+function freezeReceipt(receipt) {
+    return Object.freeze({
+        ...receipt,
+        fieldErrors: Object.freeze([...receipt.fieldErrors]),
+        protocolMetadata: Object.freeze({
+            initial: receipt.protocolMetadata.initial,
+            trailing: receipt.protocolMetadata.trailing,
+        }),
+    });
+}
+function emptyMetadata() {
+    return Object.freeze(Object.create(null));
+}
+function scalarCode(value) {
+    return typeof value === "number" || typeof value === "string" ? value : undefined;
+}
+function stringValue(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function booleanValue(value) {
+    return typeof value === "boolean" ? value : undefined;
+}
+function parseBoolean(value) {
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    return undefined;
+}
+function numberValue(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function isFailureKind(value) {
+    return value !== undefined && FAILURE_KINDS.has(value);
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const FAILURE_KINDS = new Set([
+    "authentication",
+    "authorization",
+    "not-found",
+    "validation",
+    "conflict",
+    "throttled",
+    "unavailable",
+    "unknown",
+]);
+const SENSITIVE_METADATA_KEYS = new Set(["authorization", "cookie", "set-cookie", "x-api-key"]);

package/core/geometry-input-sr.d.ts

@@ -0,0 +1,3 @@
+/** GeoServices query geometry defaults to WGS84, never the target layer CRS. */
+export declare function geometryInputSpatialReference(geometry: unknown): string | number;
+//# sourceMappingURL=geometry-input-sr.d.ts.map

package/core/geometry-input-sr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geometry-input-sr.d.ts","sourceRoot":"","sources":["../../../src/core/geometry-input-sr.ts"],"names":[],"mappings":"AAEA,gFAAgF;AAChF,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAqBhF"}

package/core/geometry-input-sr.js

@@ -0,0 +1,28 @@
+import { HonuaGeometryError } from "./errors.js";
+/** GeoServices query geometry defaults to WGS84, never the target layer CRS. */
+export function geometryInputSpatialReference(geometry) {
+    if (typeof geometry === "string") {
+        try {
+            geometry = JSON.parse(geometry);
+        }
+        catch {
+            // GeoServices also accepts comma-separated coordinate strings.
+            return 4326;
+        }
+    }
+    if (typeof geometry !== "object" || geometry === null || !("spatialReference" in geometry))
+        return 4326;
+    const sr = geometry.spatialReference;
+    if (typeof sr === "object" && sr !== null) {
+        if ("wkt" in sr && typeof sr.wkt === "string" && sr.wkt.trim())
+            return JSON.stringify(sr);
+        if ("latestWkid" in sr && typeof sr.latestWkid === "number" && Number.isInteger(sr.latestWkid) && sr.latestWkid > 0)
+            return sr.latestWkid;
+        if ("wkid" in sr && typeof sr.wkid === "number" && Number.isInteger(sr.wkid) && sr.wkid > 0)
+            return sr.wkid;
+    }
+    throw new HonuaGeometryError("malformed-geometry", "Query geometry has an invalid spatialReference", {
+        operation: "query-input-spatial-reference",
+        reason: "invalid-spatial-reference",
+    });
+}

package/core/geoservices.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"geoservices.d.ts","sourceRoot":"","sources":["../../../src/core/geoservices.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAEpE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,EACtB,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,2BAA2B,EAC3B,oBAAoB,EACpB,qBAAqB,EACrB,cAAc,EACd,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAChB,wBAAwB,EACxB,oBAAoB,EAEpB,0BAA0B,EAC3B,MAAM,YAAY,CAAC;AAIpB,wBAAsB,YAAY,CAChC,SAAS,EAAE,sBAAsB,EACjC,MAAM,EAAE,MAAM,GAAG,OAAO,EACxB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,qBAAqB,CAAC,CAIhC;AAED,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,sBAAsB,EACjC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,kBAAkB,CAAC,CAQ7B;AAED,wBAAsB,yBAAyB,CAC7C,SAAS,EAAE,sBAAsB,EACjC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,oBAAoB,CAAC,CAQ/B;AAED,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,sBAAsB,EACjC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,oBAAoB,CAAC,CAQ/B;AAED,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,sBAAsB,EACjC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,kBAAkB,CAAC,CAQ7B;AAID;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,oBAAoB,EAC7B,YAAY,EAAE,OAAO,GACpB,OAAO,CAAC,kBAAkB,CAAC,CAsC7B;AAED,wBAAsB,aAAa,CACjC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,kBAAkB,CAAC,CA2B7B;AAED,wBAAsB,UAAU,CAC9B,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,uBAAuB,CAAC,CA0BlC;AAED,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,2BAA2B,CAAC,CAyCtC;AAED,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,2BAA2B,CAAC,CAwCtC;AAED,wBAAsB,SAAS,CAC7B,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,sBAAsB,CAAC,CA6CjC;AAED,wBAAsB,YAAY,CAChC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,mBAAmB,CAAC,CAiB9B;AAED,wBAAsB,WAAW,CAC/B,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,qBAAqB,CAAC,CA8ChC;AAED,wBAAsB,OAAO,CAAC,SAAS,EAAE,sBAAsB,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA2DpH"}
+{"version":3,"file":"geoservices.d.ts","sourceRoot":"","sources":["../../../src/core/geoservices.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAGpE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,EACtB,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,2BAA2B,EAC3B,oBAAoB,EACpB,qBAAqB,EACrB,cAAc,EACd,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAChB,wBAAwB,EACxB,oBAAoB,EAEpB,0BAA0B,EAC3B,MAAM,YAAY,CAAC;AAIpB,wBAAsB,YAAY,CAChC,SAAS,EAAE,sBAAsB,EACjC,MAAM,EAAE,MAAM,GAAG,OAAO,EACxB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,qBAAqB,CAAC,CAIhC;AAED,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,sBAAsB,EACjC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,kBAAkB,CAAC,CAQ7B;AAED,wBAAsB,yBAAyB,CAC7C,SAAS,EAAE,sBAAsB,EACjC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,oBAAoB,CAAC,CAQ/B;AAED,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,sBAAsB,EACjC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,oBAAoB,CAAC,CAQ/B;AAED,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,sBAAsB,EACjC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,kBAAkB,CAAC,CAQ7B;AAoBD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,oBAAoB,EAC7B,YAAY,EAAE,OAAO,GACpB,OAAO,CAAC,kBAAkB,CAAC,CAwC7B;AAED,wBAAsB,aAAa,CACjC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,kBAAkB,CAAC,CA4B7B;AAED,wBAAsB,UAAU,CAC9B,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,uBAAuB,CAAC,CA0BlC;AAED,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,2BAA2B,CAAC,CAyCtC;AAED,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,2BAA2B,CAAC,CAwCtC;AAED,wBAAsB,SAAS,CAC7B,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,sBAAsB,CAAC,CA6CjC;AAED,wBAAsB,YAAY,CAChC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,mBAAmB,CAAC,CAiB9B;AAED,wBAAsB,WAAW,CAC/B,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,qBAAqB,CAAC,CA8ChC;AAED,wBAAsB,OAAO,CAAC,SAAS,EAAE,sBAAsB,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA2DpH"}

package/core/geoservices.js

@@ -8,6 +8,7 @@
  *
  * @module
  */
+import { geometryInputSpatialReference } from "./geometry-input-sr.js";
 import { encodeServiceIdPath } from "./path-utils.js";
 // ── Metadata ────────────────────────────────────────────────────
 export async function listServices(transport, format, options = {}) {
@@ -36,6 +37,17 @@ export async function getMapLayerMetadata(transport, serviceId, layerId, options
     return transport.requestCachedMetadataJson(`geoservices-map:${serviceId}:${layerId}`, path, options);
 }
 // ── FeatureServer / MapServer operations ────────────────────────
+// A conservative request-target budget avoids common browser/proxy URL limits.
+// Measure encoded parameters plus the configured base path: Unicode, polygon
+// coordinates, and a deployment prefix (e.g. `/honua`) can all expand the
+// actual request target that `resolveRequestUrl` sends. Explicit caller
+// choices remain authoritative.
+function queryMethod(method, path, params, baseUrl) {
+    if (method !== undefined)
+        return method;
+    const url = new URL(`${baseUrl}${path}?${params.toString()}`, globalThis.location?.href ?? "https://honua.invalid");
+    return url.pathname.length + url.search.length > 2_000 ? "POST" : "GET";
+}
 /**
  * REST portion of `client.queryFeatures` (the gRPC-web fast path is
  * orchestrated by the client). Maps directly to the FeatureServer `query`
@@ -43,16 +55,18 @@ export async function getMapLayerMetadata(transport, serviceId, layerId, options
  * `preferBinary` is set.
  */
 export async function queryFeaturesRest(transport, request, preferBinary) {
-    const method = request.method ?? "GET";
-    const usePbf = preferBinary && method === "GET";
     const params = new URLSearchParams();
-    params.set("f", usePbf ? "pbf" : "json");
+    params.set("f", preferBinary && (request.method === undefined || request.method === "GET") ? "pbf" : "json");
     params.set("where", request.where ?? "1=1");
     params.set("outFields", normalizeOutFields(request.outFields));
     params.set("returnGeometry", String(request.returnGeometry ?? true));
     serializeQueryParams(params, request);
     appendQueryExtraParams(params, request);
     const path = `/rest/services/${encodeServiceIdPath(request.serviceId)}/FeatureServer/${request.layerId}/query`;
+    const method = queryMethod(request.method, path, params, transport.baseUrl);
+    const usePbf = preferBinary && method === "GET";
+    if (request.method === undefined && method === "POST" && params.get("f") === "pbf")
+        params.set("f", "json");
     if (usePbf) {
         return transport.requestBinaryWithJsonFallback("GET", `${path}?${params.toString()}`, params, request.signal);
     }
@@ -64,10 +78,9 @@ export async function queryFeaturesRest(transport, request, preferBinary) {
             "Content-Type": "application/x-www-form-urlencoded",
         },
         body: params.toString(),
-    }, request.signal);
+    }, request.signal, request.method === undefined ? { readOnlyQuery: true } : undefined);
 }
 export async function queryMapLayer(transport, request) {
-    const method = request.method ?? "GET";
     const params = new URLSearchParams();
     params.set("f", "json");
     params.set("where", request.where ?? "1=1");
@@ -76,6 +89,7 @@ export async function queryMapLayer(transport, request) {
     serializeQueryParams(params, request);
     appendQueryExtraParams(params, request);
     const path = `/rest/services/${encodeServiceIdPath(request.serviceId)}/MapServer/${request.layerId}/query`;
+    const method = queryMethod(request.method, path, params, transport.baseUrl);
     if (method === "GET") {
         return transport.requestJson("GET", `${path}?${params.toString()}`, undefined, request.signal);
     }
@@ -84,7 +98,7 @@ export async function queryMapLayer(transport, request) {
             "Content-Type": "application/x-www-form-urlencoded",
         },
         body: params.toString(),
-    }, request.signal);
+    }, request.signal, request.method === undefined ? { readOnlyQuery: true } : undefined);
 }
 export async function applyEdits(transport, request) {
     const path = `/rest/services/${encodeServiceIdPath(request.serviceId)}/FeatureServer/${request.layerId}/applyEdits`;
@@ -392,6 +406,7 @@ function serializeQueryParams(params, request) {
         params.set("objectIds", Array.isArray(request.objectIds) ? request.objectIds.join(",") : String(request.objectIds));
     }
     if (request.geometry !== undefined) {
+        params.set("inSR", String(request.extraParams?.inSR ?? geometryInputSpatialReference(request.geometry)));
         params.set("geometry", typeof request.geometry === "object" && request.geometry !== null
             ? JSON.stringify(request.geometry)
             : String(request.geometry));
@@ -402,6 +417,18 @@ function serializeQueryParams(params, request) {
     if (request.spatialRel !== undefined) {
         params.set("spatialRel", request.spatialRel);
     }
+    if (request.distance !== undefined) {
+        params.set("distance", String(request.distance));
+    }
+    if (request.units !== undefined) {
+        params.set("units", request.units);
+    }
+    if (request.nearestCount !== undefined) {
+        params.set("nearestCount", String(request.nearestCount));
+    }
+    if (request.returnDistance !== undefined) {
+        params.set("returnDistance", String(request.returnDistance));
+    }
     if (request.returnDistinctValues !== undefined) {
         params.set("returnDistinctValues", String(request.returnDistinctValues));
     }

package/core/grpc-adapter.d.ts

@@ -1,9 +1,9 @@
-import { type FeaturePage, type QueryFeaturesResponse } from "../gen/honua/v1/feature_service_pb.js";
+import { type FeaturePage, type QueryFeaturesResponse } from "../gen/geospatial/v1/index.js";
 import type { HonuaCountResponse, HonuaExtentResponse, HonuaFeature, HonuaObjectIdsResponse, HonuaQueryResponse, QueryFeaturesRequest } from "./types.js";
 /**
  * Converts a SDK QueryFeaturesRequest into a proto QueryFeaturesRequest message.
  */
-export declare function toProtoQueryRequest(request: QueryFeaturesRequest): import("../gen/honua/v1/feature_service_pb.js").QueryFeaturesRequest;
+export declare function toProtoQueryRequest(request: QueryFeaturesRequest): import("../gen/geospatial/v1/feature_service_pb.js").QueryFeaturesRequest;
 /**
  * Converts a proto QueryFeaturesResponse into the JSON-compatible shape
  * matching the `f=json` response format.

package/core/grpc-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grpc-adapter.d.ts","sourceRoot":"","sources":["../../../src/core/grpc-adapter.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,KAAK,WAAW,EAWhB,KAAK,qBAAqB,EAM3B,MAAM,uCAAuC,CAAC;AAE/C,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EAEZ,sBAAsB,EACtB,kBAAkB,EAElB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAwFpB;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,wEAoIhE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,qBAAqB,GAC9B,kBAAkB,GAAG,kBAAkB,GAAG,sBAAsB,GAAG,mBAAmB,CAkDxF;AA0UD;;;;GAIG;AACH,wBAAuB,gBAAgB,CACrC,MAAM,EAAE,aAAa,CAAC,WAAW,CAAC,GACjC,cAAc,CAAC,YAAY,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC,CAiBjD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAYtD"}
+{"version":3,"file":"grpc-adapter.d.ts","sourceRoot":"","sources":["../../../src/core/grpc-adapter.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,KAAK,WAAW,EAWhB,KAAK,qBAAqB,EAM3B,MAAM,+BAA+B,CAAC;AAGvC,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EAEZ,sBAAsB,EACtB,kBAAkB,EAElB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AA6GpB;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,6EA6IhE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,qBAAqB,GAC9B,kBAAkB,GAAG,kBAAkB,GAAG,sBAAsB,GAAG,mBAAmB,CAkDxF;AA0UD;;;;GAIG;AACH,wBAAuB,gBAAgB,CACrC,MAAM,EAAE,aAAa,CAAC,WAAW,CAAC,GACjC,cAAc,CAAC,YAAY,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC,CAiBjD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAiBtD"}

package/core/grpc-adapter.js

@@ -1,6 +1,7 @@
 import { create } from "@bufbuild/protobuf";
-import { CoordinateSchema, CoordinateSequenceSchema, DistanceUnit, FieldType, GeometrySchema, GeometryType, MultiPointGeometrySchema, PointGeometrySchema, PolygonGeometrySchema, PolylineGeometrySchema, QueryFeaturesRequestSchema, SpatialFilterSchema, SpatialReferenceSchema, SpatialRelationship, StatisticDefinitionSchema, StatisticType, } from "../gen/honua/v1/feature_service_pb.js";
+import { CoordinateSchema, CoordinateSequenceSchema, DistanceUnit, FieldType, GeometrySchema, GeometryType, MultiPointGeometrySchema, PointGeometrySchema, PolygonGeometrySchema, PolylineGeometrySchema, QueryFeaturesRequestSchema, SpatialFilterSchema, SpatialReferenceSchema, SpatialRelationship, StatisticDefinitionSchema, StatisticType, } from "../gen/geospatial/v1/index.js";
 import { HonuaGrpcError } from "./errors.js";
+import { geometryInputSpatialReference } from "./geometry-input-sr.js";
 /**
  * Maps proto FieldType enum values to Esri-style field type strings
  * used in the JSON response shape.
@@ -81,6 +82,25 @@ const STATISTIC_TYPE_MAP = {
 };
 const MAX_SAFE_INTEGER_BIGINT = BigInt(Number.MAX_SAFE_INTEGER);
 const MIN_SAFE_INTEGER_BIGINT = BigInt(Number.MIN_SAFE_INTEGER);
+const MIN_PROTO_INT64 = -(1n << 63n);
+const MAX_PROTO_INT64 = (1n << 63n) - 1n;
+function toProtoObjectId(value) {
+    const token = value.trim();
+    if (!/^(?:0|-?[1-9][0-9]*)$/.test(token)) {
+        throw new RangeError("string objectIds must contain canonical decimal int64 values");
+    }
+    const parsed = BigInt(token);
+    if (parsed < MIN_PROTO_INT64 || parsed > MAX_PROTO_INT64) {
+        throw new RangeError("string objectIds must remain within the signed int64 range");
+    }
+    return parsed;
+}
+function toProtoPageInt64(field, value) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RangeError(`${field} must be a non-negative safe integer for the gRPC int64 contract`);
+    }
+    return BigInt(value);
+}
 /**
  * Converts a SDK QueryFeaturesRequest into a proto QueryFeaturesRequest message.
  */
@@ -107,15 +127,20 @@ export function toProtoQueryRequest(request) {
     }
     if (request.objectIds !== undefined) {
         const ids = typeof request.objectIds === "string"
-            ? request.objectIds.split(",").map((id) => BigInt(id.trim()))
-            : request.objectIds.map((id) => BigInt(id));
+            ? request.objectIds.split(",").map(toProtoObjectId)
+            : request.objectIds.map((id) => {
+                if (!Number.isSafeInteger(id)) {
+                    throw new RangeError("objectIds must contain only safe integers for the gRPC int64 contract");
+                }
+                return BigInt(id);
+            });
         msg.objectIds = ids;
     }
     if (request.resultOffset !== undefined) {
-        msg.resultOffset = request.resultOffset;
+        msg.resultOffsetLong = toProtoPageInt64("resultOffset", request.resultOffset);
     }
     if (request.resultRecordCount !== undefined) {
-        msg.resultRecordCount = request.resultRecordCount;
+        msg.resultRecordCountLong = toProtoPageInt64("resultRecordCount", request.resultRecordCount);
     }
     if (request.orderByFields !== undefined) {
         msg.orderBy = request.orderByFields;
@@ -146,8 +171,11 @@ export function toProtoQueryRequest(request) {
         else {
             filter.spatialRelationship = SpatialRelationship.INTERSECTS;
         }
-        if (spatialReference) {
-            filter.spatialReference = spatialReference;
+        const inputSpatialReference = spatialReference ??
+            toProtoSpatialReference(request.extraParams?.inSR) ??
+            toProtoSpatialReference(geometryInputSpatialReference(request.geometry));
+        if (inputSpatialReference) {
+            filter.spatialReference = inputSpatialReference;
         }
         const distance = request.distance ?? parseExtraNumber(request.extraParams ?? {}, "distance");
         if (distance !== undefined) {
@@ -553,7 +581,11 @@ export async function* streamProtoPages(stream) {
  */
 export function wrapConnectError(error) {
     if (error instanceof Error && "code" in error && typeof error.code === "number") {
-        return new HonuaGrpcError(error.code, error.message, "rawMessage" in error ? error.rawMessage : undefined);
+        const candidate = error;
+        return new HonuaGrpcError(candidate.code, error.message, "rawMessage" in error ? candidate.rawMessage : undefined, {
+            initialMetadata: candidate.headers ?? candidate.initialMetadata,
+            trailingMetadata: candidate.trailers ?? candidate.trailer ?? candidate.metadata,
+        });
     }
     if (error instanceof Error) {
         return error;
@@ -577,7 +609,7 @@ function convertField(field) {
     return {
         name: field.name,
         type: FIELD_TYPE_MAP[field.fieldType] ?? "esriFieldTypeString",
-        alias: field.name,
+        alias: field.alias || field.name,
         length: field.length || undefined,
         nullable: field.nullable,
     };

package/core/job-run-errors.d.ts

@@ -0,0 +1,10 @@
+import type { JobStatus } from "../contract/jobs.js";
+import { HonuaSdkError } from "./error-envelope.js";
+/** Error thrown when `IJobRun.results()` observes a non-success terminal. */
+export declare class HonuaJobFailedError extends HonuaSdkError {
+    readonly status: JobStatus;
+    readonly errorCode: string | undefined;
+    readonly details: unknown;
+    constructor(message: string, status: JobStatus, errorCode?: string, details?: unknown);
+}
+//# sourceMappingURL=job-run-errors.d.ts.map

package/core/job-run-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-run-errors.d.ts","sourceRoot":"","sources":["../../../src/core/job-run-errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,6EAA6E;AAC7E,qBAAa,mBAAoB,SAAQ,aAAa;IACpD,SAAgB,MAAM,EAAE,SAAS,CAAC;IAClC,SAAgB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,SAAgB,OAAO,EAAE,OAAO,CAAC;gBAEd,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAO7F"}

package/core/job-run-errors.js

@@ -0,0 +1,14 @@
+import { HonuaSdkError } from "./error-envelope.js";
+/** Error thrown when `IJobRun.results()` observes a non-success terminal. */
+export class HonuaJobFailedError extends HonuaSdkError {
+    status;
+    errorCode;
+    details;
+    constructor(message, status, errorCode, details) {
+        super("core.job-failed", message, { context: { status, errorCode } });
+        this.name = "HonuaJobFailedError";
+        this.status = status;
+        this.errorCode = errorCode;
+        this.details = details;
+    }
+}