import type { EntityDataset, NearestEntity, TableField } from "@dclimate/tabular/reader";
/**
 * Entity (point-observation) datasets, as opposed to the gridded Zarr datasets
 * `loadDataset` serves.
 *
 * "Entity" is tabular's word for the thing a row belongs to -- a weather station
 * in GHCND, a buoy in NDBC -- and this namespace follows it rather than keeping
 * an older `station` vocabulary the layer beneath no longer uses.
 *
 * The two are different enough underneath -- irregular entities with per-entity
 * time coverage, versus a regular lat/lon/time grid -- that sharing one loader
 * would help nobody. What they do share is how a caller wants to *ask*: degrees,
 * ISO timestamps, chained selections. `EntityDataset` provides that surface, so
 * this namespace stays thin: resolve a root, hand back the dataset.
 *
 * Resolution is by CID only for now. There is no STAC equivalent for entity
 * data yet; when there is, `load` grows a `{ collection, dataset }` form
 * alongside the CID and the rest of this file is unaffected.
 */
export interface EntitiesClientOptions {
    gatewayUrl: string;
    fetch?: typeof globalThis.fetch;
}
export interface LoadEntitiesRequest {
    /** Root CID of a published entity dataset. */
    cid: string;
    /** Override the client's gateway for this dataset only. */
    gatewayUrl?: string;
    /**
     * Map each schema field to the column name queries and results use.
     *
     * A dataset's published column names are a property of its profile, not of
     * the stored blocks: GHCND stores a field named `tmax` and publishes it as
     * `TMAX`, NDBC preserves mixed case like `SwH`. The reader's default is the
     * identity -- the schema's own field names -- so without the dataset's
     * mapping, the published names are unreachable: `elements("TMAX")` is an
     * unknown element even though every GHCND doc names it that way.
     *
     * For GHCND, pass `(field) => field.name.toUpperCase()`.
     */
    columnKey?: (field: TableField) => string;
}
export interface NearestEntityRequest extends LoadEntitiesRequest {
    latitude: number;
    longitude: number;
    /**
     * Only consider stations that actually report every one of these columns.
     *
     * Without it, "nearest" means nearest *station*, not nearest *data* -- a
     * station 40 km away that has never recorded TMAX wins over one 3,000 km away
     * that has. Presence means the station reported the column at some point, not
     * that it reported it recently.
     */
    columns?: readonly string[];
    /** Reject the match when the closest qualifying station is further than this. */
    maxKm?: number;
    /**
     * Narrow `columns` to a time range, so a station qualifies only if it reported
     * them *then*.
     *
     * Without it, presence means "has ever reported": a station whose TMAX ended in
     * 1987 satisfies a 2024 query and then yields nothing but nulls. Real datasets
     * do this -- GHCND's ACW00011647 lists TMAX on the strength of readings that
     * only start in 2025.
     *
     * Resolution is per fragment (whole years, for GHCND), so a range landing
     * anywhere in a year that has the column matches it.
     */
    within?: {
        start: Date | string | number;
        end: Date | string | number;
    };
}
export declare class EntitiesClient {
    private readonly options;
    constructor(options: EntitiesClientOptions);
    /**
     * Open an entity dataset by root CID.
     *
     * Reads go through the IPFS HTTP gateway, so this needs no local daemon and
     * works unchanged in a browser.
     */
    load(request: LoadEntitiesRequest): Promise<EntityDataset>;
    /**
     * The entity nearest a point that actually has the data you asked for.
     *
     * Resolves the dataset and the entity in one call, because "which station
     * should I use for this location" is the question most callers open an entity
     * dataset to ask, and answering it through `load` means knowing that `nearest`
     * needs `columns` to avoid picking a station full of nulls.
     *
     * Returns the distance alongside the entity: a dataset with no coverage near
     * the queried point still has a nearest entity, and the only way to tell that
     * apart from a good match is how far away it is.
     */
    nearest(request: NearestEntityRequest): Promise<NearestEntity>;
}
//# sourceMappingURL=entities-client.d.ts.map