@honua/react 0.0.20-alpha.0

package/contract/jobs.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Canonical async-operation surface. `IJobRun` is the protocol-neutral
+ * vocabulary every long-running operation in the SDK speaks. It is the
+ * receipt returned from operations that complete asynchronously on the
+ * server (OGC API Processes execution, future GeoServices async export
+ * tickets, OData function imports, etc.).
+ *
+ * Per the ticket constraint, OGC Processes specifically must surface
+ * through this shared interface — there is no `OgcJobRun` top-level
+ * type. The implementation in `src/core/ogc-processes.ts` returns
+ * `IJobRun<T>` directly.
+ *
+ * @module
+ */
+/**
+ * Coarse-grained job lifecycle. The OGC API Processes 1.0 status values
+ * (`accepted`, `running`, `successful`, `failed`, `dismissed`) are the
+ * canonical vocabulary; adapters for protocols that report a narrower or
+ * wider set must map onto these.
+ */
+export type JobStatus = "accepted" | "running" | "successful" | "failed" | "dismissed";
+/** Human-meaningful job-progress signal. Optional; servers may omit fields. */
+export interface JobProgress {
+    /** 0..100. Omitted when the server does not report a numeric estimate. */
+    percent?: number;
+    /** Human-readable status message for the current step. */
+    message?: string;
+    /** ISO-8601 timestamp of when the server last updated the progress. */
+    updatedAt?: string;
+}
+/**
+ * Snapshot of a job's state. Returned from `IJobRun.poll()` and emitted
+ * to `IJobRun.watch` listeners. The result/error fields are filled only
+ * for terminal states.
+ */
+export interface JobSnapshot<T = unknown> {
+    status: JobStatus;
+    progress?: JobProgress;
+    /** Payload returned for terminal `successful` snapshots only. */
+    result?: JobResult<T>;
+    /** Error envelope returned for terminal `failed` snapshots. */
+    error?: JobError;
+}
+/**
+ * Server-side error envelope for a failed job. Mirrors the OGC API
+ * Processes "exception" shape; adapters for other protocols translate
+ * onto this surface so callers can branch on `code` without protocol
+ * knowledge.
+ */
+export interface JobError {
+    /** Stable machine code (e.g. `"InvalidParameterValue"`). */
+    code: string;
+    /** Human-readable explanation. */
+    message: string;
+    /** Optional details payload as returned by the server. */
+    details?: unknown;
+}
+/**
+ * Job-result document. `outputs` is a map of output-id → value; the SDK
+ * does not parse the value further (it may be a GeoJSON feature
+ * collection, a download URL, a binary asset, etc., depending on the
+ * process). Adapters narrow `T` for typed access.
+ */
+export interface JobResult<T = unknown> {
+    outputs: Record<string, T>;
+}
+/** Listener function invoked on every observed snapshot transition. */
+export type JobSnapshotListener<T = unknown> = (snapshot: JobSnapshot<T>) => void;
+/**
+ * Bounds for {@link IJobRun.results}. Without any bound a hung or never-terminal
+ * status endpoint polls forever with no caller cancellation. Implementations
+ * pass {@link signal} through to the underlying status request, stop polling
+ * when the signal aborts or a deadline / attempt cap is reached, and use capped
+ * exponential backoff between polls.
+ */
+export interface JobResultsOptions {
+    /** Abort the poll loop (and the in-flight status request) when this fires. */
+    readonly signal?: AbortSignal;
+    /** Wall-clock budget in ms for reaching a terminal state. */
+    readonly deadlineMs?: number;
+    /** Maximum number of status polls before giving up. */
+    readonly maxAttempts?: number;
+    /** Base poll interval in ms (defaults to the adapter's cadence). */
+    readonly pollIntervalMs?: number;
+    /** Cap for the exponential backoff interval in ms. */
+    readonly maxPollIntervalMs?: number;
+}
+/**
+ * Canonical async-operation handle. Methods are intentionally narrow so
+ * downstream tickets that submit jobs (operator workflows, manifest
+ * apply, etc.) can speak one vocabulary across protocols.
+ */
+export interface IJobRun<T = unknown> {
+    /** Stable identifier assigned by the server when the job was accepted. */
+    readonly id: string;
+    /** Process / operation identifier, e.g. an OGC processId. */
+    readonly type: string;
+    /**
+     * Last-observed status. Backed by the most recent `poll()` /
+     * `status()` / `watch()` snapshot; reads are synchronous.
+     */
+    readonly status: JobStatus;
+    /** Last-observed progress, if the server reported any. */
+    readonly progress: JobProgress | undefined;
+    /** Force a fresh server poll and return the resulting snapshot. */
+    poll(): Promise<JobSnapshot<T>>;
+    /**
+     * Subscribe to snapshot transitions. The callback fires on every
+     * observed status / progress change, and again on the terminal
+     * snapshot. Returns an unsubscribe handle.
+     */
+    watch(listener: JobSnapshotListener<T>): () => void;
+    /**
+     * Wait for the job to reach a terminal state and resolve with the
+     * outputs. Rejects with `HonuaJobFailedError` for `failed` /
+     * `dismissed` terminal states, or `HonuaJobPollTimeoutError` when the
+     * optional {@link JobResultsOptions} deadline / attempt cap is reached or
+     * the supplied signal aborts. Implementations poll on a configurable
+     * interval (capped exponential backoff); the default cadence is left to
+     * the adapter.
+     */
+    results(options?: JobResultsOptions): Promise<JobResult<T>>;
+    /**
+     * Cancel / dismiss the job. Idempotent. Returns the resulting status
+     * (typically `dismissed`, but the server may have raced to a terminal
+     * state already, in which case the original terminal status is
+     * returned).
+     */
+    cancel(): Promise<JobStatus>;
+}
+/**
+ * `true` when the snapshot status is one of the terminal values
+ * (`successful`, `failed`, `dismissed`). Useful for stop conditions in
+ * watchers and tests.
+ */
+export declare function isJobTerminal(status: JobStatus): boolean;
+/**
+ * Thrown by {@link IJobRun.results} when the poll loop is cancelled or exhausted
+ * before the job reached a terminal state — i.e. the {@link JobResultsOptions}
+ * signal aborted, the deadline elapsed, or the attempt cap was hit. `reason`
+ * distinguishes the three so callers can branch (e.g. retry vs surface).
+ */
+export declare class HonuaJobPollTimeoutError extends Error {
+    readonly reason: "aborted" | "deadline" | "max-attempts";
+    readonly jobId: string;
+    readonly lastStatus: JobStatus;
+    constructor(message: string, reason: "aborted" | "deadline" | "max-attempts", jobId: string, lastStatus: JobStatus);
+}
+//# sourceMappingURL=jobs.d.ts.map

package/contract/jobs.d.ts.map

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

package/contract/jobs.js

@@ -0,0 +1,40 @@
+/**
+ * Canonical async-operation surface. `IJobRun` is the protocol-neutral
+ * vocabulary every long-running operation in the SDK speaks. It is the
+ * receipt returned from operations that complete asynchronously on the
+ * server (OGC API Processes execution, future GeoServices async export
+ * tickets, OData function imports, etc.).
+ *
+ * Per the ticket constraint, OGC Processes specifically must surface
+ * through this shared interface — there is no `OgcJobRun` top-level
+ * type. The implementation in `src/core/ogc-processes.ts` returns
+ * `IJobRun<T>` directly.
+ *
+ * @module
+ */
+/**
+ * `true` when the snapshot status is one of the terminal values
+ * (`successful`, `failed`, `dismissed`). Useful for stop conditions in
+ * watchers and tests.
+ */
+export function isJobTerminal(status) {
+    return status === "successful" || status === "failed" || status === "dismissed";
+}
+/**
+ * Thrown by {@link IJobRun.results} when the poll loop is cancelled or exhausted
+ * before the job reached a terminal state — i.e. the {@link JobResultsOptions}
+ * signal aborted, the deadline elapsed, or the attempt cap was hit. `reason`
+ * distinguishes the three so callers can branch (e.g. retry vs surface).
+ */
+export class HonuaJobPollTimeoutError extends Error {
+    reason;
+    jobId;
+    lastStatus;
+    constructor(message, reason, jobId, lastStatus) {
+        super(message);
+        this.name = "HonuaJobPollTimeoutError";
+        this.reason = reason;
+        this.jobId = jobId;
+        this.lastStatus = lastStatus;
+    }
+}

package/contract/source.d.ts

@@ -0,0 +1,423 @@
+/**
+ * Built-in `Source` adapters that wrap the runtime classes in
+ * `src/core/surfaces.ts` (`HonuaFeatureLayer`, `HonuaMapLayer`,
+ * `HonuaOgcFeatureCollection`) and the OGC / STAC / WFS / WMS / OData
+ * adapters in `src/core/`. Consumers register adapters for any other
+ * protocol (MapLibre-native sources, etc.) via
+ * `CreateDatasetOptions.resolveSource`.
+ *
+ * These adapters do not reimplement query logic — they translate the
+ * canonical `Query` / `Result` envelope to and from the existing per-class
+ * request and response shapes.
+ *
+ * @module
+ */
+import type { HonuaClient } from "../core/client.js";
+import { HonuaOdataEntitySet } from "../core/odata.js";
+import { HonuaOgcCollectionMap, HonuaOgcMaps } from "../core/ogc-maps.js";
+import type { HonuaOgcProcesses } from "../core/ogc-processes.js";
+import { HonuaOgcRecordCollection } from "../core/ogc-records.js";
+import { HonuaOgcTiles, HonuaOgcTileset } from "../core/ogc-tiles.js";
+import { HonuaStacSearch } from "../core/stac.js";
+import { HonuaFeatureLayer, HonuaGeometryService, HonuaGeoprocessingService, HonuaImageService, HonuaMapLayer, HonuaMapService, HonuaOgcFeatureCollection } from "../core/surfaces.js";
+import { HonuaWfsFeatureType } from "../core/wfs.js";
+import { HonuaWms, HonuaWmsLayer } from "../core/wms.js";
+import { HonuaWmts, HonuaWmtsLayer, HonuaWmtsTileset } from "../core/wmts.js";
+import { type Capability, type CapabilityPolicy, type CreateDatasetOptions, type Dataset, type Protocol, type Source, type SourceDescriptor } from "./types.js";
+/**
+ * Construct a protocol-neutral `Dataset` over a `HonuaClient`.
+ *
+ * A `Dataset` groups one or more `Source`s. Each `Source` accepts a protocol-neutral
+ * `Query` and returns a protocol-neutral `Result`. The dataset is the cross-protocol
+ * unit of work: a single `Dataset` can mix GeoServices FeatureServer, OGC API Features,
+ * WFS, STAC, and OData sources under one capability policy.
+ *
+ * `Source` handles are constructed lazily, server compatibility is checked once per
+ * dataset (and cached on the underlying client), and capability gaps surface as
+ * {@link HonuaCapabilityNotSupportedError} under the default `"strict"` policy rather
+ * than silently returning empty results.
+ *
+ * Operations the canonical surface does not cover stay reachable through the typed
+ * `source.protocol(...)` escape hatch (e.g. ImageServer `exportImage`, GeometryServer
+ * `project`, GPServer `submitJob`, WFS `LockFeature`).
+ *
+ * @param options - The dataset id, the `HonuaClient` to talk to, the list of
+ *   `SourceDescriptor`s, and (optionally) `capabilityPolicy` and a custom
+ *   `resolveSource` factory.
+ *
+ * @example
+ * ```ts
+ * import { createDataset, PROTOCOL_DEFAULT_CAPABILITIES } from "@honua/sdk-js/contract";
+ * import { HonuaClient } from "@honua/sdk-js/honua";
+ *
+ * const client = new HonuaClient({ baseUrl: "https://your-honua-server.example" });
+ *
+ * const dataset = createDataset({
+ *   id: "parcels",
+ *   client,
+ *   sources: [
+ *     {
+ *       id: "parcels-fs",
+ *       protocol: "geoservices-feature-service",
+ *       locator: { url: "https://your-honua-server.example", serviceId: "parcels", layerId: 0 },
+ *       capabilities: PROTOCOL_DEFAULT_CAPABILITIES["geoservices-feature-service"],
+ *     },
+ *   ],
+ * });
+ *
+ * const parcels = dataset.source("parcels-fs")!;
+ * const result = await parcels.queryAll({
+ *   where: "STATUS = 'ACTIVE'",
+ *   outFields: ["OBJECTID", "NAME"],
+ *   returnGeometry: true,
+ *   pagination: { limit: 500 },
+ * });
+ *
+ * console.log(`Loaded ${result.features.length} features`);
+ * ```
+ */
+export declare function createDataset(options: CreateDatasetOptions): Dataset;
+/**
+ * Adapter factory for a GeoServices FeatureServer layer.
+ *
+ * Used internally by {@link createDataset} when it sees a descriptor with
+ * `protocol: "geoservices-feature-service"`. Calling it directly is rarely
+ * necessary; pass the descriptor to `createDataset` instead.
+ *
+ * @example
+ * ```ts
+ * const dataset = createDataset({
+ *   id: "parcels",
+ *   client,
+ *   sources: [{
+ *     id: "parcels-fs",
+ *     protocol: "geoservices-feature-service",
+ *     locator: { url: "https://your-honua-server.example", serviceId: "parcels", layerId: 0 },
+ *     capabilities: PROTOCOL_DEFAULT_CAPABILITIES["geoservices-feature-service"],
+ *   }],
+ * });
+ * const result = await dataset.source("parcels-fs")!.queryAll({
+ *   where: "STATUS = 'ACTIVE'",
+ *   outFields: ["OBJECTID", "NAME"],
+ * });
+ * ```
+ */
+export declare function geoServicesFeatureSource<T>(descriptor: SourceDescriptor, client: HonuaClient, policy: CapabilityPolicy): Source<T>;
+/**
+ * Adapter factory for a GeoServices MapServer layer.
+ *
+ * Reach `Source.protocol("geoservices-map-service")` for raw `exportImage` /
+ * `identify` / `find` access; the canonical `query()` runs against a single
+ * sublayer via the MapServer query endpoint.
+ *
+ * @example
+ * ```ts
+ * const dataset = createDataset({
+ *   id: "basemap",
+ *   client,
+ *   sources: [{
+ *     id: "states-mapserver",
+ *     protocol: "geoservices-map-service",
+ *     locator: { url: "https://your-honua-server.example", serviceId: "states", layerId: 0 },
+ *     capabilities: PROTOCOL_DEFAULT_CAPABILITIES["geoservices-map-service"],
+ *   }],
+ * });
+ * ```
+ */
+export declare function geoServicesMapServiceSource<T>(descriptor: SourceDescriptor, client: HonuaClient, policy: CapabilityPolicy): Source<T>;
+/**
+ * Adapter factory for an OGC API Features collection.
+ *
+ * @example
+ * ```ts
+ * const dataset = createDataset({
+ *   id: "addresses",
+ *   client,
+ *   sources: [{
+ *     id: "addresses-ogc",
+ *     protocol: "ogc-features",
+ *     locator: { url: "https://your-honua-server.example", collectionId: "addresses" },
+ *     capabilities: PROTOCOL_DEFAULT_CAPABILITIES["ogc-features"],
+ *   }],
+ * });
+ * const result = await dataset.source("addresses-ogc")!.queryAll({
+ *   where: "city = 'Honolulu'",
+ *   pagination: { limit: 200 },
+ * });
+ * ```
+ */
+export declare function ogcFeaturesSource<T>(descriptor: SourceDescriptor, client: HonuaClient, policy: CapabilityPolicy): Source<T>;
+/**
+ * Build a `Source` over an Esri-style ImageServer endpoint. The query
+ * surface drives the raster catalog (each row is a raster with footprint
+ * geometry); image export, identify, and tile operations live behind
+ * `Source.protocol("geoservices-image-service")`.
+ *
+ * @example
+ * ```ts
+ * const dataset = createDataset({
+ *   id: "imagery",
+ *   client,
+ *   sources: [{
+ *     id: "naip",
+ *     protocol: "geoservices-image-service",
+ *     locator: { url: "https://your-honua-server.example", serviceId: "naip" },
+ *     capabilities: PROTOCOL_DEFAULT_CAPABILITIES["geoservices-image-service"],
+ *   }],
+ * });
+ * const img = dataset.source("naip")!.protocol("geoservices-image-service");
+ * const png = await img?.exportImage({ bbox: [-158.5, 21.2, -157.6, 21.7], size: [512, 512] });
+ * ```
+ */
+export declare function geoServicesImageSource<T>(descriptor: SourceDescriptor, client: HonuaClient, policy: CapabilityPolicy): Source<T>;
+/**
+ * Build a `Source` over an Esri-style Geometry Service endpoint. Geometry
+ * Service is a stateless utility — it does not host features — so the
+ * query family throws `HonuaCapabilityNotSupportedError` and operations
+ * (buffer, project, simplify, etc.) live behind
+ * `Source.protocol("geoservices-geometry-service")`.
+ *
+ * @example
+ * ```ts
+ * const geom = dataset.source("geom")!.protocol("geoservices-geometry-service");
+ * const projected = await geom?.project({
+ *   inSr: 4326,
+ *   outSr: 3857,
+ *   geometries: [{ x: -158, y: 21 }],
+ * });
+ * ```
+ */
+export declare function geoServicesGeometryServiceSource<T>(descriptor: SourceDescriptor, client: HonuaClient, policy: CapabilityPolicy): Source<T>;
+/**
+ * Build a `Source` over an Esri-style GP (geoprocessing) service. GP
+ * services run async tasks rather than hosting features; the canonical
+ * feature surface throws and task submission / status / result lookup
+ * live behind `Source.protocol("geoservices-gp-service")`.
+ *
+ * @example
+ * ```ts
+ * const gp = dataset.source("buffer-task")!.protocol("geoservices-gp-service");
+ * const job = await gp!.submitJob({ inputs: { distance: 500 } });
+ * const result = await gp!.awaitJobResult(job.jobId);
+ * ```
+ */
+export declare function geoServicesGPServiceSource<T>(descriptor: SourceDescriptor, client: HonuaClient, policy: CapabilityPolicy): Source<T>;
+/**
+ * Render-only Source adapter for OGC API Tiles. The query family throws
+ * `HonuaCapabilityNotSupportedError` (the conformance class is
+ * tile-fetch, not feature-query); rendering integrations consume the
+ * tileset through `Source.protocol("ogc-tiles")` to reach the underlying
+ * runtime class.
+ *
+ * @example
+ * ```ts
+ * const tiles = dataset.source("ogc-tileset")!.protocol("ogc-tiles");
+ * const bytes = await tiles!.tile({ tileMatrix: "WebMercatorQuad", tileRow: 5, tileCol: 8 });
+ * ```
+ */
+export declare function ogcTilesSource<T>(descriptor: SourceDescriptor, client: HonuaClient, policy: CapabilityPolicy): Source<T>;
+/**
+ * Render-only Source adapter for OGC API Maps. Same shape as the Tiles
+ * adapter — `Source.protocol("ogc-maps")` exposes the runtime class for
+ * server-rendered map images; the canonical query family throws.
+ *
+ * @example
+ * ```ts
+ * const maps = dataset.source("ogc-map")!.protocol("ogc-maps");
+ * const png = await maps!.map({ bbox: [-158, 21, -157, 22], width: 512, height: 512 });
+ * ```
+ */
+export declare function ogcMapsSource<T>(descriptor: SourceDescriptor, client: HonuaClient, policy: CapabilityPolicy): Source<T>;
+/**
+ * Metadata-catalog Source adapter for OGC API Records. The canonical query
+ * family searches one catalog (`locator.collectionId`, the Records
+ * collection/catalog id) and returns record documents as typed features.
+ * Records-specific search affordances (`q`, `type`, `externalIds`,
+ * `profile`, raw HTML/JSON access) live on `Source.protocol("ogc-records")`.
+ *
+ * @example
+ * ```ts
+ * const records = dataset.source("catalog")!;
+ * const result = await records.query({ where: "type = 'dataset' AND q = 'parcels'" });
+ * ```
+ */
+export declare function ogcRecordsSource<T>(descriptor: SourceDescriptor, client: HonuaClient, policy: CapabilityPolicy): Source<T>;
+/**
+ * `Source` adapter for first-party WMS 1.3.0 services. The render path
+ * routes through `HonuaWms` / `HonuaWmsLayer` (both of which sit
+ * behind the canonical `Source.protocol("wms" | "wms-layer")` escape
+ * hatch); `Source.query()` translates a point spatial filter into a
+ * `GetFeatureInfo` call. Non-point queries throw
+ * `HonuaCapabilityNotSupportedError` so the canonical query envelope
+ * stays honest — multi-pixel feature info lives on
+ * `Source.protocol("wms").featureInfo()`.
+ */
+/**
+ * Adapter factory for a WMS 1.3.0 endpoint.
+ *
+ * The canonical `Source.query()` is implemented through point-only
+ * `GetFeatureInfo`. Reach `Source.protocol("wms")` for raw `GetMap` /
+ * `GetLegendGraphic` access (with TIME / ELEVATION dimension handling and
+ * CRS axis-order swap per WMS 1.3 §6.7.3.2).
+ *
+ * @example
+ * ```ts
+ * const wms = dataset.source("usgs-imagery")!.protocol("wms");
+ * const png = await wms!.getMap({
+ *   layers: ["topo"], bbox: [-158, 21, -157, 22], crs: "EPSG:4326",
+ *   width: 512, height: 512,
+ * });
+ * ```
+ */
+export declare function wmsSource<T>(descriptor: SourceDescriptor, client: HonuaClient, policy: CapabilityPolicy): Source<T>;
+/**
+ * Render-only `Source` adapter for first-party WMTS 1.0.0 services.
+ * `Source.query()` throws because WMTS GetFeatureInfo is keyed on tile
+ * pixels (not a canonical spatial filter); raw access lives on
+ * `Source.protocol("wmts" | "wmts-layer" | "wmts-tileset")`.
+ */
+/**
+ * Adapter factory for a WMTS 1.0.0 endpoint. Render-only; `Source.query()`
+ * throws `HonuaCapabilityNotSupportedError`. Reach `Source.protocol("wmts")`
+ * for RESTful + KVP tile fetch and capabilities.
+ *
+ * @example
+ * ```ts
+ * const wmts = dataset.source("basemap-tiles")!.protocol("wmts");
+ * const tile = await wmts!.tile({ tileMatrixSet: "WebMercatorQuad", tileMatrix: "8", tileRow: 5, tileCol: 8 });
+ * ```
+ */
+export declare function wmtsSource<T>(descriptor: SourceDescriptor, client: HonuaClient, policy: CapabilityPolicy): Source<T>;
+/**
+ * Adapter factory for a STAC API search endpoint.
+ *
+ * The canonical `Source.query()` runs a `POST /search` against the STAC root,
+ * with `Query.spatialFilter` (e.g. an `envelope(...)` bounding box) and
+ * `Query.where` translated into STAC's `bbox` / `datetime` / `filter`
+ * parameters.
+ *
+ * @example
+ * ```ts
+ * import { envelope } from "@honua/sdk-js";
+ *
+ * const dataset = createDataset({
+ *   id: "imagery",
+ *   client,
+ *   sources: [{
+ *     id: "stac-search",
+ *     protocol: "stac",
+ *     locator: { url: "https://your-honua-server.example/stac" },
+ *     capabilities: PROTOCOL_DEFAULT_CAPABILITIES.stac,
+ *   }],
+ * });
+ * const result = await dataset.source("stac-search")!.query({
+ *   where: "collections IN ('landsat-c2-l2')",
+ *   spatialFilter: envelope(-158.5, 21.2, -157.6, 21.7),
+ * });
+ * ```
+ */
+export declare function stacSearchSource<T>(descriptor: SourceDescriptor, client: HonuaClient, policy: CapabilityPolicy): Source<T>;
+/**
+ * Adapter factory for a WFS 2.0 endpoint.
+ *
+ * `Query.where` and `Query.spatialFilter` compile to FES 2.0; GeoJSON is
+ * preferred over GML via `OperationsMetadata` negotiation. `applyEdits()`
+ * builds `<wfs:Transaction>` bodies. Reach `Source.protocol("wfs")` for raw
+ * GML / `LockFeature` / stored-query access.
+ *
+ * @example
+ * ```ts
+ * const dataset = createDataset({
+ *   id: "wfs-parcels",
+ *   client,
+ *   sources: [{
+ *     id: "parcels",
+ *     protocol: "wfs",
+ *     locator: { url: "https://your-honua-server.example/wfs", typeName: "ns:Parcels" },
+ *     capabilities: PROTOCOL_DEFAULT_CAPABILITIES.wfs,
+ *   }],
+ * });
+ * const result = await dataset.source("parcels")!.queryAll({
+ *   where: "STATUS = 'ACTIVE'",
+ *   pagination: { limit: 500 },
+ * });
+ * ```
+ */
+export declare function wfsSource<T>(descriptor: SourceDescriptor, client: HonuaClient, policy: CapabilityPolicy): Source<T>;
+/**
+ * Build a `Source` over an OData v4 entity set. The `Query` translation
+ * lowers `where` / `outFields` / `orderBy` / pagination / spatial filter
+ * onto OData's `$`-prefixed query options. Dialect-specific operations
+ * (`$batch`, `$apply`, `$search`, `$deltatoken`) live behind
+ * `Source.protocol("odata")` on the returned `HonuaOdataEntitySet`.
+ *
+ * `$metadata` is fetched lazily on the first call that needs it and
+ * cached on the entity-set instance. The fetched capability annotations
+ * are intersected with the descriptor's declared `Capabilities` set the
+ * first time a capability-gated method is invoked — this is the
+ * precedent for the metadata-driven downgrade pattern referenced in
+ * `docs/shared-client-contract.md`.
+ */
+/**
+ * Adapter factory for an OData v4 entity set.
+ *
+ * `Query.where` compiles to OData `$filter`, `Query.outFields` becomes
+ * `$select`, `Query.orderBy` becomes `$orderby`, and `Query.pagination`
+ * becomes `$top`/`$skip`. Geospatial filters translate to OData's
+ * `geo.intersects` / `geo.distance` family.
+ *
+ * @example
+ * ```ts
+ * const dataset = createDataset({
+ *   id: "incidents",
+ *   client,
+ *   sources: [{
+ *     id: "incidents",
+ *     protocol: "odata",
+ *     locator: { url: "https://your-honua-server.example/odata", entitySet: "Incidents" },
+ *     capabilities: PROTOCOL_DEFAULT_CAPABILITIES.odata,
+ *   }],
+ * });
+ * const result = await dataset.source("incidents")!.queryAll({
+ *   where: "Severity ge 3",
+ *   orderBy: [{ field: "ReportedAt", direction: "desc" }],
+ *   pagination: { limit: 100 },
+ * });
+ * ```
+ */
+export declare function odataSource<T>(descriptor: SourceDescriptor, client: HonuaClient, policy: CapabilityPolicy): Source<T>;
+/**
+ * Declare the shipped adapter → runtime-class bindings so
+ * `Source.adapter("geoservices-feature-service")` et al. narrow to the
+ * right class instead of collapsing to `unknown`. Downstream adapter
+ * tickets that ship outside this module add their own augmentations in
+ * their own modules.
+ */
+declare module "./types.js" {
+    interface AdapterTypeMap {
+        "geoservices-feature-service": HonuaFeatureLayer;
+        "geoservices-map-service": HonuaMapService;
+        "geoservices-map-layer": HonuaMapLayer;
+        "geoservices-image-service": HonuaImageService;
+        "geoservices-geometry-service": HonuaGeometryService;
+        "geoservices-gp-service": HonuaGeoprocessingService;
+        "ogc-features": HonuaOgcFeatureCollection;
+        "ogc-tiles": HonuaOgcTileset | HonuaOgcTiles;
+        "ogc-maps": HonuaOgcMaps | HonuaOgcCollectionMap;
+        "ogc-records": HonuaOgcRecordCollection;
+        "ogc-processes": HonuaOgcProcesses;
+        stac: HonuaStacSearch;
+        wfs: HonuaWfsFeatureType;
+        wms: HonuaWms;
+        "wms-layer": HonuaWmsLayer;
+        wmts: HonuaWmts;
+        "wmts-layer": HonuaWmtsLayer;
+        "wmts-tileset": HonuaWmtsTileset;
+        odata: HonuaOdataEntitySet;
+    }
+}
+/** Sentinel: `Capabilities` set that contains every defined capability. */
+export declare const ALL_CAPABILITIES: ReadonlySet<Capability>;
+/** Tag a `Protocol` as "first-party-supported by this build". */
+export declare const FIRST_PARTY_PROTOCOLS: ReadonlySet<Protocol>;
+//# sourceMappingURL=source.d.ts.map

package/contract/source.d.ts.map

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