@vepler/sdk 3.3.0 → 5.28.1

package/dist/esm/sdk/models/shared/siteaggregationinput.d.ts

@@ -8,7 +8,7 @@ export declare const SiteAggregationInputOrder: {
 };
 export type SiteAggregationInputOrder = ClosedEnum<typeof SiteAggregationInputOrder>;
 /**
- * Type of aggregation
+ * How the matching sites are aggregated. Each type takes its own parameters and returns its own result shape.
  */
 export declare const SiteAggregationInputType: {
     readonly Terms: "terms";
@@ -27,66 +27,66 @@ export declare const SiteAggregationInputType: {
     readonly GeotileGrid: "geotile_grid";
 };
 /**
- * Type of aggregation
+ * How the matching sites are aggregated. Each type takes its own parameters and returns its own result shape.
  */
 export type SiteAggregationInputType = ClosedEnum<typeof SiteAggregationInputType>;
 export type SiteAggregationInput = {
     /**
-     * Nested sub-aggregations (max 5, up to 2 levels deep)
+     * Sub-aggregations run inside each bucket of this one. Up to 5, and they may nest one level further, giving two levels below the top.
      */
     aggs?: Array<SiteNestedAggregation> | undefined;
     /**
-     * Calendar-aware interval for date_histogram. Values: 1m (minute), 1h (hour), 1d (day), 1w (week), 1M (month), 1q (quarter), 1y (year). Mutually exclusive with fixedInterval — provide one or the other, not both.
+     * Calendar-aware bucket width for a date aggregation: 1m (minute), 1h (hour), 1d (day), 1w (week), 1M (month), 1q (quarter) or 1y (year). Mutually exclusive with `fixedInterval`, so supply one or the other, never both.
      */
     calendarInterval?: string | undefined;
     /**
-     * Field to aggregate on. Must be a field allowed by the dataset's aggregation whitelist.
+     * Field to aggregate over. Each dataset allows a fixed set of fields, and each of those supports only certain aggregation types; a field or type outside that set is rejected.
      */
     field: string;
     /**
-     * Fixed-duration interval for date_histogram. Values: any combination of number + unit (ms, s, m, h, d). Examples: "30m", "1h", "7d". Unlike calendarInterval, does not account for daylight saving or month lengths. Mutually exclusive with calendarInterval — provide one or the other, not both.
+     * Fixed-duration bucket width for a date aggregation, written as a number and a unit (ms, s, m, h, d), for example "30m", "1h" or "7d". Unlike `calendarInterval` it takes no account of daylight saving or of months having different lengths. Mutually exclusive with `calendarInterval`, so supply one or the other, never both.
      */
     fixedInterval?: string | undefined;
     /**
-     * Date format string for date_histogram bucket keys. Uses Elasticsearch date format patterns (e.g. "yyyy-MM-dd").
+     * Pattern used to render `key_as_string` on each date bucket, for example "yyyy-MM-dd".
      */
     format?: string | undefined;
     /**
-     * Bucket width for histogram aggregation. Required when type is "histogram".
+     * Width of each bucket for a `histogram` aggregation, in the units of the field. Must be greater than zero. Some datasets reject a `histogram` aggregation that omits it rather than applying a default.
      */
     interval?: number | undefined;
     /**
-     * Minimum document count for a bucket to be included in the result. Applies to: terms, histogram, date_histogram. Default is 1.
+     * Smallest number of matching records a bucket must hold to appear in the result. Set it to 0 to keep buckets that matched nothing. Only the bucketing types honour it; single-value metric types ignore it.
      */
     minDocCount?: number | undefined;
     /**
-     * Unique name for this aggregation. Used as the key in the response `aggregations` object.
+     * Name for this aggregation. It is the key its result appears under in the response `aggregations` object, so it must be unique within the request. Between 1 and 50 characters.
      */
     name: string;
     /**
-     * Sort order for terms buckets. Key is the sort field ("_count", "_key", or a sub-aggregation name), value is direction.
+     * Order the buckets of a `terms` aggregation. The key is what to sort on, either `_count`, `_key`, or the name of one of this aggregation's sub-aggregations; the value is the direction.
      */
     order?: {
         [k: string]: SiteAggregationInputOrder;
     } | undefined;
     /**
-     * Percentile values to calculate (0-100). Required when type is "percentiles".
+     * The percentiles to compute, each between 0 and 100. Used by the `percentiles` type.
      */
     percents?: Array<number> | undefined;
     /**
-     * Custom numeric ranges for range aggregation. Required when type is "range". Each range has an inclusive `from` and exclusive `to`.
+     * The ranges a `range` aggregation groups into. At least one is needed, and each covers `from` inclusive up to `to` exclusive.
      */
     ranges?: Array<RangeDefinition> | undefined;
     /**
-     * Maximum number of buckets to return. Applies to: terms (default 20), geotile_grid (precision level). Ignored by metric aggregations (stats, min, max, etc.).
+     * Maximum number of buckets a grouping aggregation returns, between 1 and 100. The single-value metric types ignore it. For the map-tile grouping type it sets the tile precision rather than a bucket count. When omitted, the default depends on the dataset and the field.
      */
     size?: number | undefined;
     /**
-     * IANA timezone for date_histogram bucketing (e.g. "Europe/London", "UTC"). Defaults to UTC.
+     * IANA time zone that date bucket boundaries are aligned to, for example "Europe/London".
      */
     timeZone?: string | undefined;
     /**
-     * Type of aggregation
+     * How the matching sites are aggregated. Each type takes its own parameters and returns its own result shape.
      */
     type: SiteAggregationInputType;
 };

package/dist/esm/sdk/models/shared/siteaggregationinput.js

@@ -9,7 +9,7 @@ export const SiteAggregationInputOrder = {
     Desc: "desc",
 };
 /**
- * Type of aggregation
+ * How the matching sites are aggregated. Each type takes its own parameters and returns its own result shape.
  */
 export const SiteAggregationInputType = {
     Terms: "terms",

package/dist/esm/sdk/models/shared/siteareametrics.d.ts

@@ -2,27 +2,27 @@ import * as z from "zod/v3";
 import { Result as SafeParseResult } from "../../types/fp.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 /**
- * Area-level metrics from the LSOA (Lower Layer Super Output Area) containing the site centroid. Includes crime, deprivation, connectivity, and prosperity indices. Null when the centroid cannot be matched to an LSOA (e.g. sites outside England and Wales).
+ * Area-level measures for the LSOA containing the site centroid, covering crime, deprivation, connectivity and prosperity. Null when none of those measures are available for the site.
  */
 export type SiteAreaMetrics = {
     /**
-     * Broadband and mobile connectivity score
+     * Broadband and mobile connectivity score for the local area containing the site.
      */
     connectivityScore?: number | undefined;
     /**
-     * Crime safety score from the site's LSOA (0-100)
+     * Crime safety score for the Lower Layer Super Output Area (LSOA) containing the site, from 0 to 100, where higher is safer.
      */
     crimeScore?: number | undefined;
     /**
-     * Index of Multiple Deprivation decile (1-10)
+     * Index of Multiple Deprivation for the local area containing the site.
      */
     deprivationIndex?: number | undefined;
     /**
-     * Prosperity decile (1-10)
+     * National prosperity decile for the LSOA containing the site, from 1 to 10, where 10 is the most prosperous.
      */
     prosperityDecile?: number | undefined;
     /**
-     * Vepler Prosperity Index score
+     * Prosperity Index score for the LSOA containing the site, from 0 to 100.
      */
     prosperityScore?: number | undefined;
 };

package/dist/esm/sdk/models/shared/sitebatchidsrequest.d.ts

@@ -1,15 +1,15 @@
 import * as z from "zod/v3";
 /**
- * Fields to return
+ * Fields to return, in the same form as the search request.
  */
 export type SiteBatchIdsRequestAttributes = string | Array<string>;
 export type SiteBatchIdsRequest = {
     /**
-     * Fields to return
+     * Fields to return, in the same form as the search request.
      */
     attributes?: string | Array<string> | undefined;
     /**
-     * Array of site IDs to look up
+     * The site identifiers to look up. At least one, and no more than 100 per request.
      */
     siteIds: Array<string>;
 };

package/dist/esm/sdk/models/shared/siteboundingboxareafilter.d.ts

@@ -1,40 +1,40 @@
 import * as z from "zod/v3";
 /**
- * South-east corner of the bounding box
+ * South-east corner of the box.
  */
 export type SiteBoundingBoxAreaFilterBottomRight = {
     /**
-     * South latitude
+     * Latitude of the southern edge.
      */
     lat: number;
     /**
-     * East longitude
+     * Longitude of the eastern edge.
      */
     lon: number;
 };
 /**
- * North-west corner of the bounding box
+ * North-west corner of the box.
  */
 export type SiteBoundingBoxAreaFilterTopLeft = {
     /**
-     * North latitude
+     * Latitude of the northern edge.
      */
     lat: number;
     /**
-     * West longitude
+     * Longitude of the western edge.
      */
     lon: number;
 };
 /**
- * Filter sites whose centroid falls within a rectangular bounding box. Useful for map viewport queries.
+ * Match sites whose centroid falls inside a rectangular box. Useful for map viewport queries.
  */
 export type SiteBoundingBoxAreaFilter = {
     /**
-     * South-east corner of the bounding box
+     * South-east corner of the box.
      */
     bottomRight: SiteBoundingBoxAreaFilterBottomRight;
     /**
-     * North-west corner of the bounding box
+     * North-west corner of the box.
      */
     topLeft: SiteBoundingBoxAreaFilterTopLeft;
     type: "boundingBox";

package/dist/esm/sdk/models/shared/sitecontainspointareafilter.d.ts

@@ -1,14 +1,14 @@
 import * as z from "zod/v3";
 /**
- * Find sites whose boundary polygon contains this point. Equivalent to a point-in-polygon query.
+ * Match sites whose boundary encloses this point, a point-in-polygon test.
  */
 export type SiteContainsPointAreaFilter = {
     /**
-     * Latitude in decimal degrees (WGS84)
+     * Latitude of the point, in WGS84 decimal degrees.
      */
     lat: number;
     /**
-     * Longitude in decimal degrees (WGS84)
+     * Longitude of the point, in WGS84 decimal degrees.
      */
     lon: number;
     type: "containsPoint";

package/dist/esm/sdk/models/shared/sitefilters.d.ts

@@ -7,80 +7,80 @@ export declare const SiteFiltersStatus: {
 };
 export type SiteFiltersStatus = ClosedEnum<typeof SiteFiltersStatus>;
 /**
- * Filter by boolean tags. Set a tag to `true` to require it, or `false` to exclude it.
+ * Filter on the derived tags. Set a tag to `true` to require it, or `false` to exclude it.
  */
 export type Tags = {
     /**
-     * Filter for agricultural land
+     * Match sites whose land use includes agricultural land.
      */
     agricultural?: boolean | undefined;
     /**
-     * Filter for sites on brownfield land
+     * Match sites on brownfield land.
      */
     brownfield?: boolean | undefined;
     /**
-     * Filter for sites with development potential
+     * Match sites flagged as having development potential.
      */
     developmentPotential?: boolean | undefined;
     /**
-     * Filter for sites with multiple linked properties
+     * Match sites with more than one linked property.
      */
     multipleProperties?: boolean | undefined;
     /**
-     * Filter for sites with zero linked properties
+     * Match sites with no linked properties.
      */
     noProperties?: boolean | undefined;
     /**
-     * Filter for sites with no linked properties
+     * Match sites where more than half of the linked properties are vacant.
      */
     vacant?: boolean | undefined;
 };
 /**
- * Convenience filters
+ * Convenience filters narrowing which sites are aggregated.
  */
 export type SiteFilters = {
     /**
-     * Maximum site area in square metres (inclusive)
+     * Largest site area to include, in square metres, inclusive.
      */
     areaSqmMax?: number | undefined;
     /**
-     * Minimum site area in square metres (inclusive)
+     * Smallest site area to include, in square metres, inclusive.
      */
     areaSqmMin?: number | undefined;
     /**
-     * Filter by HM Land Registry class of title codes. Freehold: AF, QF, PF, SF. Leasehold: AL, GL, QL, PL, SL. Other: CF, CL, AR, PR, QR, CN.
+     * Return only titles carrying one of these HM Land Registry class of title codes. The freehold codes are `AF`, `QF`, `PF` and `SF`; the leasehold codes are `AL`, `GL`, `QL`, `PL` and `SL`; `CF`, `CL` and `CN` cover cautions and `AR`, `PR` and `QR` cover rentcharges.
      */
     classTitleCode?: Array<string> | undefined;
     /**
-     * Filter by company registration number
+     * Return only titles whose primary proprietor has this company registration number.
      */
     companyNumber?: string | undefined;
     /**
-     * Filter by ISO 3166-1 alpha-2 country code
+     * Return only titles registered in this country, as an ISO 3166-1 alpha-2 code.
      */
     country?: string | undefined;
     /**
-     * Filter sites that intersect specific spatial overlays (e.g. flood zones, conservation areas)
+     * Return only sites carrying one of these overlay codes.
      */
     overlays?: Array<string> | undefined;
     /**
-     * Filter by owner name (partial match)
+     * Return only titles whose primary proprietor's name contains this text, matched case-sensitively.
      */
     ownerName?: string | undefined;
     /**
-     * Filter by ownership category: company, corporate, government, individual
+     * Return only titles whose primary proprietor falls into one of these categories: `company`, `corporate`, `government`, `individual` or `unknown`.
      */
     ownershipCategory?: Array<string> | undefined;
     /**
-     * Filter by site status. active: current titles. pending: awaiting registration. closed: no longer active.
+     * Return only titles whose record status is one of these.
      */
     status?: Array<SiteFiltersStatus> | undefined;
     /**
-     * Filter by boolean tags. Set a tag to `true` to require it, or `false` to exclude it.
+     * Filter on the derived tags. Set a tag to `true` to require it, or `false` to exclude it.
      */
     tags?: Tags | undefined;
     /**
-     * Filter by tenure types. Allowed values: freehold, leasehold, commonhold, rentcharge, caution, other.
+     * Return only titles whose tenure is one of these: `freehold`, `leasehold`, `commonhold`, `rentcharge`, `caution` or `other`.
      */
     tenureType?: Array<string> | undefined;
 };

package/dist/esm/sdk/models/shared/siteleafaggregation.d.ts

@@ -7,7 +7,7 @@ export declare const SiteLeafAggregationOrder: {
 };
 export type SiteLeafAggregationOrder = ClosedEnum<typeof SiteLeafAggregationOrder>;
 /**
- * Type of aggregation
+ * How the matching sites are aggregated. Each type takes its own parameters and returns its own result shape.
  */
 export declare const SiteLeafAggregationType: {
     readonly Terms: "terms";
@@ -26,62 +26,62 @@ export declare const SiteLeafAggregationType: {
     readonly GeotileGrid: "geotile_grid";
 };
 /**
- * Type of aggregation
+ * How the matching sites are aggregated. Each type takes its own parameters and returns its own result shape.
  */
 export type SiteLeafAggregationType = ClosedEnum<typeof SiteLeafAggregationType>;
 export type SiteLeafAggregation = {
     /**
-     * Calendar-aware interval for date_histogram. Values: 1m (minute), 1h (hour), 1d (day), 1w (week), 1M (month), 1q (quarter), 1y (year). Mutually exclusive with fixedInterval — provide one or the other, not both.
+     * Calendar-aware bucket width for a date aggregation: 1m (minute), 1h (hour), 1d (day), 1w (week), 1M (month), 1q (quarter) or 1y (year). Mutually exclusive with `fixedInterval`, so supply one or the other, never both.
      */
     calendarInterval?: string | undefined;
     /**
-     * Field to aggregate on. Must be a field allowed by the dataset's aggregation whitelist.
+     * Field to aggregate over. Each dataset allows a fixed set of fields, and each of those supports only certain aggregation types; a field or type outside that set is rejected.
      */
     field: string;
     /**
-     * Fixed-duration interval for date_histogram. Values: any combination of number + unit (ms, s, m, h, d). Examples: "30m", "1h", "7d". Unlike calendarInterval, does not account for daylight saving or month lengths. Mutually exclusive with calendarInterval — provide one or the other, not both.
+     * Fixed-duration bucket width for a date aggregation, written as a number and a unit (ms, s, m, h, d), for example "30m", "1h" or "7d". Unlike `calendarInterval` it takes no account of daylight saving or of months having different lengths. Mutually exclusive with `calendarInterval`, so supply one or the other, never both.
      */
     fixedInterval?: string | undefined;
     /**
-     * Date format string for date_histogram bucket keys. Uses Elasticsearch date format patterns (e.g. "yyyy-MM-dd").
+     * Pattern used to render `key_as_string` on each date bucket, for example "yyyy-MM-dd".
      */
     format?: string | undefined;
     /**
-     * Bucket width for histogram aggregation. Required when type is "histogram".
+     * Width of each bucket for a `histogram` aggregation, in the units of the field. Must be greater than zero. Some datasets reject a `histogram` aggregation that omits it rather than applying a default.
      */
     interval?: number | undefined;
     /**
-     * Minimum document count for a bucket to be included in the result. Applies to: terms, histogram, date_histogram. Default is 1.
+     * Smallest number of matching records a bucket must hold to appear in the result. Set it to 0 to keep buckets that matched nothing. Only the bucketing types honour it; single-value metric types ignore it.
      */
     minDocCount?: number | undefined;
     /**
-     * Unique name for this aggregation. Used as the key in the response `aggregations` object.
+     * Name for this aggregation. It is the key its result appears under in the response `aggregations` object, so it must be unique within the request. Between 1 and 50 characters.
      */
     name: string;
     /**
-     * Sort order for terms buckets. Key is the sort field ("_count", "_key", or a sub-aggregation name), value is direction.
+     * Order the buckets of a `terms` aggregation. The key is what to sort on, either `_count`, `_key`, or the name of one of this aggregation's sub-aggregations; the value is the direction.
      */
     order?: {
         [k: string]: SiteLeafAggregationOrder;
     } | undefined;
     /**
-     * Percentile values to calculate (0-100). Required when type is "percentiles".
+     * The percentiles to compute, each between 0 and 100. Used by the `percentiles` type.
      */
     percents?: Array<number> | undefined;
     /**
-     * Custom numeric ranges for range aggregation. Required when type is "range". Each range has an inclusive `from` and exclusive `to`.
+     * The ranges a `range` aggregation groups into. At least one is needed, and each covers `from` inclusive up to `to` exclusive.
      */
     ranges?: Array<RangeDefinition> | undefined;
     /**
-     * Maximum number of buckets to return. Applies to: terms (default 20), geotile_grid (precision level). Ignored by metric aggregations (stats, min, max, etc.).
+     * Maximum number of buckets a grouping aggregation returns, between 1 and 100. The single-value metric types ignore it. For the map-tile grouping type it sets the tile precision rather than a bucket count. When omitted, the default depends on the dataset and the field.
      */
     size?: number | undefined;
     /**
-     * IANA timezone for date_histogram bucketing (e.g. "Europe/London", "UTC"). Defaults to UTC.
+     * IANA time zone that date bucket boundaries are aligned to, for example "Europe/London".
      */
     timeZone?: string | undefined;
     /**
-     * Type of aggregation
+     * How the matching sites are aggregated. Each type takes its own parameters and returns its own result shape.
      */
     type: SiteLeafAggregationType;
 };

package/dist/esm/sdk/models/shared/siteleafaggregation.js

@@ -8,7 +8,7 @@ export const SiteLeafAggregationOrder = {
     Desc: "desc",
 };
 /**
- * Type of aggregation
+ * How the matching sites are aggregated. Each type takes its own parameters and returns its own result shape.
  */
 export const SiteLeafAggregationType = {
     Terms: "terms",

package/dist/esm/sdk/models/shared/sitelistresponse.d.ts

@@ -4,37 +4,37 @@ import { Result as SafeParseResult } from "../../types/fp.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 import { Site } from "./site.js";
 /**
- * Object type identifier
+ * Object type discriminator. Always `list`.
  */
 export declare const SiteListResponseObject: {
     readonly List: "list";
 };
 /**
- * Object type identifier
+ * Object type discriminator. Always `list`.
  */
 export type SiteListResponseObject = ClosedEnum<typeof SiteListResponseObject>;
 /**
- * Paginated list response
+ * One page of results, with the metadata needed to fetch the rest.
  */
 export type SiteListResponse = {
     /**
-     * Array of items
+     * The items on this page.
      */
     data: Array<Site>;
     /**
-     * Whether more items exist
+     * True when further items exist beyond this page.
      */
     hasMore: boolean;
     /**
-     * Object type identifier
+     * Object type discriminator. Always `list`.
      */
     object: SiteListResponseObject;
     /**
-     * Total number of items available
+     * Total number of items matching the request across all pages.
      */
     totalCount?: number | undefined;
     /**
-     * URL of the request
+     * Path this list was requested from.
      */
     url: string;
 };

package/dist/esm/sdk/models/shared/sitelistresponse.js

@@ -6,7 +6,7 @@ import { remap as remap$ } from "../../../lib/primitives.js";
 import { safeParse } from "../../../lib/schemas.js";
 import { Site$inboundSchema } from "./site.js";
 /**
- * Object type identifier
+ * Object type discriminator. Always `list`.
  */
 export const SiteListResponseObject = {
     List: "list",

package/dist/esm/sdk/models/shared/sitemultipolygonareafilter.d.ts

@@ -1,7 +1,7 @@
 import * as z from "zod/v3";
 import { ClosedEnum } from "../../types/enums.js";
 /**
- * Spatial relation between the site boundary and this multi-polygon. Defaults to "intersects". See SitePolygonAreaFilter for relation definitions.
+ * How the site boundary must relate to the polygons, using the same options as the polygon filter. Defaults to `intersects`.
  */
 export declare const SiteMultiPolygonAreaFilterRelation: {
     readonly Intersects: "intersects";
@@ -9,16 +9,16 @@ export declare const SiteMultiPolygonAreaFilterRelation: {
     readonly Contains: "contains";
 };
 /**
- * Spatial relation between the site boundary and this multi-polygon. Defaults to "intersects". See SitePolygonAreaFilter for relation definitions.
+ * How the site boundary must relate to the polygons, using the same options as the polygon filter. Defaults to `intersects`.
  */
 export type SiteMultiPolygonAreaFilterRelation = ClosedEnum<typeof SiteMultiPolygonAreaFilterRelation>;
 export type SiteMultiPolygonAreaFilter = {
     /**
-     * GeoJSON MultiPolygon coordinates in [longitude, latitude] order (EPSG:4326). An array of polygon coordinate arrays.
+     * One entry per polygon to search within, each holding that polygon's rings in the same form as the polygon filter. Positions are longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order).
      */
     coordinates: Array<Array<Array<Array<number>>>>;
     /**
-     * Spatial relation between the site boundary and this multi-polygon. Defaults to "intersects". See SitePolygonAreaFilter for relation definitions.
+     * How the site boundary must relate to the polygons, using the same options as the polygon filter. Defaults to `intersects`.
      */
     relation?: SiteMultiPolygonAreaFilterRelation | undefined;
     type: "multipolygon";

package/dist/esm/sdk/models/shared/sitemultipolygonareafilter.js

@@ -3,7 +3,7 @@
  */
 import * as z from "zod/v3";
 /**
- * Spatial relation between the site boundary and this multi-polygon. Defaults to "intersects". See SitePolygonAreaFilter for relation definitions.
+ * How the site boundary must relate to the polygons, using the same options as the polygon filter. Defaults to `intersects`.
  */
 export const SiteMultiPolygonAreaFilterRelation = {
     Intersects: "intersects",