@vepler/sdk 3.3.0 → 6.0.0

package/src/sdk/models/shared/councilmetadata.ts

@@ -10,26 +10,26 @@ import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 export type CouncilMetadata = {
   alternativeNames?: Array<string> | undefined;
   /**
-   * Area in square kilometres
+   * Size of the council's area, in square kilometres.
    */
   areaSquareKm?: number | undefined;
   localAuthorityId?: number | undefined;
   planningAuthorityAlternatives?: Array<string> | undefined;
   planningAuthorityName?: string | undefined;
   /**
-   * Estimated population
+   * Estimated number of people living in the council's area.
    */
   population?: number | undefined;
   /**
-   * Geographic region
+   * Region the council's area sits in.
    */
   region?: string | undefined;
   /**
-   * Tags for categorisation
+   * Labels that categorise the council.
    */
   tags?: Array<string> | undefined;
   /**
-   * Council website URL
+   * URL of the council's website.
    */
   website?: string | undefined;
   wikipediaUrl?: string | undefined;

package/src/sdk/models/shared/councilserviceurls.ts

@@ -17,11 +17,11 @@ export type CouncilServiceUrls = {
   parking?: string | undefined;
   planningDocuments?: string | undefined;
   /**
-   * URL to planning applications portal
+   * URL of the council's planning applications portal.
    */
   planningPortal?: string | undefined;
   /**
-   * URL to planning search page
+   * URL of the council's planning application search page.
    */
   planningSearch?: string | undefined;
   waste?: string | undefined;

package/src/sdk/models/shared/counciltaxbanddetails.ts

@@ -9,23 +9,23 @@ import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 
 export type CouncilTaxBandDetails = {
   /**
-   * Annual amount in pence for this period
+   * Charge for the whole tax year, in pence.
    */
   annualAmount?: number | null | undefined;
   /**
-   * Effective from date
+   * When this band and amount took effect, as an ISO 8601 date.
    */
   effectiveFrom?: string | null | undefined;
   /**
-   * Effective to date (null if current)
+   * When this band and amount stopped applying, as an ISO 8601 date. Null while it still applies.
    */
   effectiveTo?: string | null | undefined;
   /**
-   * Record ID
+   * Identifier of this council tax record.
    */
   id?: number | null | undefined;
   /**
-   * Tax year
+   * Tax year the charge applies to.
    */
   taxYear?: string | null | undefined;
 };

package/src/sdk/models/shared/counciltaxdata.ts

@@ -14,7 +14,7 @@ import {
 } from "./counciltaxbanddetails.js";
 
 /**
- * Council tax band
+ * Valuation band the property is assessed in for council tax.
  */
 export const TaxBand = {
   A: "A",
@@ -28,37 +28,37 @@ export const TaxBand = {
   I: "I",
 } as const;
 /**
- * Council tax band
+ * Valuation band the property is assessed in for council tax.
  */
 export type TaxBand = OpenEnum<typeof TaxBand>;
 
 export type CouncilTaxData = {
   /**
-   * Council identifier
+   * Identifier of the council that bills this property.
    */
   councilId?: string | null | undefined;
   /**
-   * Current annual council tax charge in pence
+   * Charge for the current tax year, in pence.
    */
   currentAnnualAmount?: number | null | undefined;
   /**
-   * Current tax year
+   * Tax year the current charge applies to.
    */
   currentTaxYear?: string | null | undefined;
   /**
-   * Whether amount is estimated
+   * True when the amount is an estimate rather than a charge taken from the council.
    */
   isEstimated?: boolean | undefined;
   /**
-   * Council tax record status
+   * Status the council holds against this council tax record.
    */
   status?: string | null | undefined;
   /**
-   * Council tax band
+   * Valuation band the property is assessed in for council tax.
    */
   taxBand?: TaxBand | null | undefined;
   /**
-   * Historical council tax band records
+   * The band and charge recorded for each period, including periods that have ended.
    */
   taxBandDetails?: Array<CouncilTaxBandDetails> | undefined;
 };

package/src/sdk/models/shared/coveragecell.ts

@@ -18,7 +18,7 @@ import {
 } from "./schoolframeworkcode.js";
 
 /**
- * Top-level School aggregate block this framework feeds.
+ * Which top-level block of a School response this framework feeds.
  */
 export const Domain = {
   Performance: "performance",
@@ -31,25 +31,25 @@ export const Domain = {
   Catchment: "catchment",
 } as const;
 /**
- * Top-level School aggregate block this framework feeds.
+ * Which top-level block of a School response this framework feeds.
  */
 export type Domain = OpenEnum<typeof Domain>;
 
 export type CoverageCell = {
   countryCode: string;
   /**
-   * Top-level School aggregate block this framework feeds.
+   * Which top-level block of a School response this framework feeds.
    */
   domain: Domain;
   /**
-   * Opaque tier identifier required to access this block. Commercial owns the namespace.
+   * Identifier of the plan needed to access this block. The set of names is not fixed by this schema, so display the string as given rather than matching on it.
    */
   entitlementRequired: string;
   framework: SchoolFrameworkCode;
   notes?: string | null | undefined;
   quality: CoverageQuality;
   /**
-   * Where this framework's data appears (e.g. `performance.ks4`).
+   * Where this framework's data appears in a School response, for example `performance.ks4`.
    */
   schoolBlockPath: string;
 };

package/src/sdk/models/shared/coveragematrix.ts

@@ -19,7 +19,7 @@ export const CoverageMatrixObject = {
 export type CoverageMatrixObject = ClosedEnum<typeof CoverageMatrixObject>;
 
 /**
- * Top-line totals for quick scan.
+ * Totals across the whole matrix.
  */
 export type CoverageMatrixSummary = {
   countriesCovered: Array<string>;
@@ -29,17 +29,17 @@ export type CoverageMatrixSummary = {
 
 export type CoverageMatrix = {
   /**
-   * One row per (country, framework). Sorted by country, framework.
+   * One row per territory and framework, ordered by territory then framework.
    */
   cells: Array<CoverageCell>;
   object: CoverageMatrixObject;
   /**
-   * Schema version this coverage report was generated under.
+   * Dated shape version this report was generated under.
    */
   objectVersion: string;
   snapshotAt: Date;
   /**
-   * Top-line totals for quick scan.
+   * Totals across the whole matrix.
    */
   summary: CoverageMatrixSummary;
 };

package/src/sdk/models/shared/coveragequality.ts

@@ -21,7 +21,7 @@ export type Cadence = OpenEnum<typeof Cadence>;
 export type CoverageQuality = {
   cadence: Cadence;
   /**
-   * Percentage = (schoolsCovered / schoolsExpected) × 100. Researchers cite this.
+   * `schoolsCovered` as a percentage of `schoolsExpected`. Minimum 0, maximum 100.
    */
   coveragePct: number;
   earliestAcademicYear: string | null;
@@ -29,15 +29,15 @@ export type CoverageQuality = {
   latestAcademicYear: string | null;
   nextRefreshExpectedAt: Date | null;
   /**
-   * Number of schools for which this framework's data is loaded.
+   * Number of schools that have data from this framework.
    */
   schoolsCovered: number;
   /**
-   * Number of schools expected to have this framework's data (denominator for coverage %).
+   * Number of schools expected to have data from this framework. It is the denominator of `coveragePct`.
    */
   schoolsExpected: number;
   /**
-   * Count of distinct academic years held.
+   * Number of distinct academic years held.
    */
   yearsLoaded: number;
 };

package/src/sdk/models/shared/crimecatalogbycountryresponse.ts

@@ -14,13 +14,13 @@ import {
 } from "./crimecatalogentry.js";
 
 /**
- * String representing the object type
+ * Object type discriminator. Always `list`.
  */
 export const CrimeCatalogByCountryResponseObject = {
   List: "list",
 } as const;
 /**
- * String representing the object type
+ * Object type discriminator. Always `list`.
  */
 export type CrimeCatalogByCountryResponseObject = ClosedEnum<
   typeof CrimeCatalogByCountryResponseObject
@@ -28,23 +28,23 @@ export type CrimeCatalogByCountryResponseObject = ClosedEnum<
 
 export type CrimeCatalogByCountryResponse = {
   /**
-   * Catalog entries for the requested country, newest period first.
+   * One entry per period held for the requested country, newest period first.
    */
   data: Array<CrimeCatalogEntry>;
   /**
-   * Whether more results exist
+   * True when more results exist than were returned. The safety endpoints are not paged, so it is false.
    */
   hasMore: boolean;
   /**
-   * String representing the object type
+   * Object type discriminator. Always `list`.
    */
   object: CrimeCatalogByCountryResponseObject;
   /**
-   * Total number of results in the response.
+   * Number of results in `data`.
    */
   totalCount?: number | undefined;
   /**
-   * URL of the request
+   * Path this list was requested from.
    */
   url: string;
 };

package/src/sdk/models/shared/crimecatalogcountriesresponse.ts

@@ -13,7 +13,7 @@ import {
 
 export type CrimeCatalogCountriesResponse = {
   /**
-   * Map of country identifier to the available period buckets (`yearly` and `monthly`).
+   * Periods held for each country, keyed by country identifier and split into yearly and monthly.
    */
   countries: { [k: string]: CrimeCatalogPeriodsByCountry };
 };

package/src/sdk/models/shared/crimecatalogentry.ts

@@ -10,33 +10,32 @@ import { Result as SafeParseResult } from "../../types/fp.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 
 /**
- * Granularity of the period.
+ * Granularity of `period`. Only monthly periods are published today.
  */
 export const PeriodType = {
   Monthly: "monthly",
-  Quarterly: "quarterly",
   Yearly: "yearly",
 } as const;
 /**
- * Granularity of the period.
+ * Granularity of `period`. Only monthly periods are published today.
  */
 export type PeriodType = OpenEnum<typeof PeriodType>;
 
 export type CrimeCatalogEntry = {
   /**
-   * Country identifier the entry applies to.
+   * Country the entry covers: `england` or `wales`.
    */
   country: string;
   /**
-   * True when this period's data has been successfully ingested and is queryable.
+   * True when this period has been published and can be queried.
    */
   isAvailable: boolean;
   /**
-   * Period the entry applies to. Yearly entries use `YYYY`; monthly entries use `YYYY-MM`.
+   * Period the entry covers. Yearly entries use `YYYY`, monthly entries use `YYYY-MM`.
    */
   period: string;
   /**
-   * Granularity of the period.
+   * Granularity of `period`. Only monthly periods are published today.
    */
   periodType: PeriodType;
 };

package/src/sdk/models/shared/crimecatalogperiodsbycountry.ts

@@ -9,11 +9,11 @@ import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 
 export type CrimeCatalogPeriodsByCountry = {
   /**
-   * Available monthly periods (`YYYY-MM`), most recent first.
+   * Monthly periods (`YYYY-MM`) held for the country, most recent first.
    */
   monthly: Array<string>;
   /**
-   * Available yearly periods (`YYYY`), most recent first.
+   * Yearly periods (`YYYY`) held for the country, most recent first. Empty today.
    */
   yearly: Array<string>;
 };

package/src/sdk/models/shared/crimeconfidenceinterval.ts

@@ -8,19 +8,19 @@ import { Result as SafeParseResult } from "../../types/fp.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 
 /**
- * Confidence interval around `crimeScore`. Null when the score is null.
+ * 95% confidence interval around `crimeScore`, reflecting sampling only. Null when areas are merged and when no interval was computed.
  */
 export type CrimeConfidenceInterval = {
   /**
-   * Confidence level (0-1).
+   * Confidence level the interval was computed at, from 0 to 1.
    */
   confidence: number;
   /**
-   * Lower bound of the confidence interval.
+   * Lower bound of the interval around the score.
    */
   lower: number;
   /**
-   * Upper bound of the confidence interval.
+   * Upper bound of the interval around the score.
    */
   upper: number;
 };

package/src/sdk/models/shared/crimeincident.ts

@@ -13,27 +13,31 @@ export type CrimeIncident = {
    */
   category: string;
   /**
-   * `[longitude, latitude]` of the anonymised reporting point (WGS84). Snapped by the provider to a nearby map point — accurate to ~150m. Null for records that have no recorded geometry.
+   * Position of the anonymised reporting point: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order). The source snaps each incident to a nearby map point, so the position is accurate to roughly 150m. Null for records published without a position.
    */
   coordinates: Array<number | null> | null;
   /**
-   * ISO 8601 datetime the incident was recorded. The upstream provider publishes monthly resolution.
+   * Month the incident was recorded in, as an ISO 8601 timestamp on the first day of that month. The source publishes incidents by month, not by day.
    */
   crimeDate: string;
   /**
-   * Stable identifier issued by the upstream UK police data feed. Null for older or anonymised records.
+   * Identifier issued for the incident by the police data source. Null for anti-social behaviour, which is published without one.
    */
   crimeId: string | null;
   /**
-   * Free-text location label as published by the upstream provider. Often references a street or landmark near the anonymised map point, not the exact incident address.
+   * Location label for the incident. The current data source publishes no location text, so this is null; use `coordinates` to place the incident.
    */
   crimeLocation: string | null;
   /**
-   * Human-readable label for the crime category, when available.
+   * Human-readable name for the crime category.
    */
   label: string | null;
   /**
-   * Police force that reported the incident.
+   * Last recorded outcome for the incident, as published by the police data source. Null for anti-social behaviour and for incidents with no outcome yet.
+   */
+  outcome: string | null;
+  /**
+   * Identifier of the police force that recorded the incident, in lower-case hyphenated form.
    */
   reportedBy: string | null;
 };
@@ -50,6 +54,7 @@ export const CrimeIncident$inboundSchema: z.ZodType<
   crimeId: z.nullable(z.string()),
   crimeLocation: z.nullable(z.string()),
   label: z.nullable(z.string()),
+  outcome: z.nullable(z.string()),
   reportedBy: z.nullable(z.string()),
 });
 

package/src/sdk/models/shared/crimeincidentslistresponse.ts

@@ -15,13 +15,13 @@ import {
 } from "./crimeincidentssummary.js";
 
 /**
- * String representing the object type
+ * Object type discriminator. Always `list`.
  */
 export const CrimeIncidentsListResponseObject = {
   List: "list",
 } as const;
 /**
- * String representing the object type
+ * Object type discriminator. Always `list`.
  */
 export type CrimeIncidentsListResponseObject = ClosedEnum<
   typeof CrimeIncidentsListResponseObject
@@ -29,24 +29,24 @@ export type CrimeIncidentsListResponseObject = ClosedEnum<
 
 export type CrimeIncidentsListResponse = {
   /**
-   * Crime incidents in the requested radius and date window.
+   * The crime incidents inside the requested radius and date window, most recent month first.
    */
   data: Array<CrimeIncident>;
   /**
-   * Whether more results exist
+   * True when more results exist than were returned. The safety endpoints are not paged, so it is false.
    */
   hasMore: boolean;
   /**
-   * String representing the object type
+   * Object type discriminator. Always `list`.
    */
   object: CrimeIncidentsListResponseObject;
   summary: CrimeIncidentsSummary;
   /**
-   * Total number of results in the response.
+   * Number of results in `data`.
    */
   totalCount?: number | undefined;
   /**
-   * URL of the request
+   * Path this list was requested from.
    */
   url: string;
 };

package/src/sdk/models/shared/crimeincidentssummary.ts

@@ -9,19 +9,19 @@ import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 
 export type CrimeIncidentsSummary = {
   /**
-   * Incident count per crime category in the returned batch.
+   * Number of incidents in each crime category across the returned set.
    */
   byCategory: { [k: string]: number };
   /**
-   * Anchor month for the response in YYYY-MM format. When the request supplied `date`, this reflects the resolved month (which may differ from the requested month if no significant data was available there).
+   * Anchor month for the window, in `YYYY-MM` form. When the request supplies `date` this is that month, or the most recent month with significant reporting in the area if that is earlier; otherwise it is the most recent month with significant reporting in the area.
    */
   period: string;
   /**
-   * Search radius used, in metres.
+   * Search radius that was applied, in metres.
    */
   radius: number;
   /**
-   * True when the underlying query hit the per-request incident cap and the response was truncated. Narrow the radius or date window when this happens.
+   * True when the search hit the cap of 5,000 incidents and the returned set is incomplete. Narrow the radius or the date window to see the rest.
    */
   truncated: boolean;
 };

package/src/sdk/models/shared/crimeperioddetails.ts

@@ -11,13 +11,25 @@ import { Result as SafeParseResult } from "../../types/fp.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 
 /**
- * Window length and sample size used to compute the category score.
+ * The trailing window behind this category's numbers. Null when areas are merged.
  */
 export type CrimePeriodDetails = {
+  /**
+   * How many months of the window had usable data. Null when not known.
+   */
+  coveredPeriods: number | null;
+  /**
+   * Last month of the window, in `YYYY-MM` form.
+   */
+  end: string;
   /**
    * Number of incidents in the analysis window.
    */
   sampleSize: number;
+  /**
+   * First month of the window, in `YYYY-MM` form.
+   */
+  start: string;
   /**
    * Length of the analysis window, in months.
    */
@@ -32,7 +44,10 @@ export const CrimePeriodDetails$inboundSchema: z.ZodType<
   unknown
 > = collectExtraKeys$(
   z.object({
+    coveredPeriods: z.nullable(z.number()),
+    end: z.string(),
     sampleSize: z.number(),
+    start: z.string(),
     windowMonths: z.number(),
   }).catchall(z.any()),
   "additionalProperties",

package/src/sdk/models/shared/datasourceref.ts

@@ -8,47 +8,47 @@ import { Result as SafeParseResult } from "../../types/fp.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 
 /**
- * Reference to a single upstream data source
+ * One upstream source that contributed to this response.
  */
 export type DataSourceRef = {
   /**
-   * Organisation responsible for publishing the source
+   * Organisation that publishes and maintains the source.
    */
   custodian?: string | undefined;
   /**
-   * ISO datetime — when Vepler ingested this version
+   * When this version of the source was ingested, as an ISO 8601 timestamp.
    */
   fetchedAt?: string | undefined;
   /**
-   * Machine code for the source (e.g. 'ea_aqma_register')
+   * Stable machine code identifying the source, safe to match on.
    */
   id?: string | undefined;
   /**
-   * ISO 3166-1 alpha-2 codes (optionally with subdivision) covered by this source
+   * Territories the source covers, as ISO 3166-1 alpha-2 codes, each optionally carrying a subdivision such as `GB-ENG`.
    */
   jurisdiction?: Array<string> | undefined;
   /**
-   * Licence identifier — e.g. 'OGL_v3.0', 'INSPIRE', 'CC_BY_4.0', 'proprietary'
+   * Identifier of the licence this source is published under, for example 'OGL_v3.0', 'INSPIRE', 'CC_BY_4.0' or 'proprietary'.
    */
   licence?: string | undefined;
   /**
-   * Human-readable name for the source
+   * Full name of the source dataset.
    */
   name?: string | undefined;
   /**
-   * ISO date — when the custodian published this version
+   * When the custodian published this version of the source, as an ISO 8601 date.
    */
   releaseDate?: string | undefined;
   /**
-   * SHA-256 hash of the raw fetched artefact for integrity verification
+   * SHA-256 hash of the raw file as fetched, so the exact input can be verified.
    */
   sha256?: string | undefined;
   /**
-   * Canonical URL where the source is published
+   * Canonical address at which the custodian publishes the source.
    */
   url?: string | undefined;
   /**
-   * Source-side version when the custodian provides one
+   * Version the custodian assigns to this release, where they publish one.
    */
   version?: string | undefined;
 };

package/src/sdk/models/shared/designationbboxarea.ts

@@ -6,11 +6,11 @@ import * as z from "zod/v3";
 
 export type DesignationBboxArea = {
   /**
-   * [latitude, longitude] of the top-right corner
+   * The north-east corner: latitude first, then longitude, in WGS84 decimal degrees.
    */
   northEast: Array<number>;
   /**
-   * [latitude, longitude] of the bottom-left corner
+   * The south-west corner: latitude first, then longitude, in WGS84 decimal degrees. This is the reverse of the GeoJSON order used by geometry fields.
    */
   southWest: Array<number>;
   type: "boundingBox";

package/src/sdk/models/shared/designationboundary.ts

@@ -16,7 +16,7 @@ export type DesignationBoundaryType = ClosedEnum<
 >;
 
 /**
- * The full EPSG:4326 MultiPolygon — opt-in via `attributes: ['geometry']` (can exceed 100 KB).
+ * The full boundary, as a MultiPolygon in WGS84. Returned only when the request asks for `geometry` in `attributes`, since it can run well past 100 KB.
  */
 export type DesignationBoundary = {
   coordinates: Array<Array<Array<Array<number>>>>;

package/src/sdk/models/shared/designationcentroid.ts

@@ -16,11 +16,11 @@ export type DesignationCentroidType = ClosedEnum<
 >;
 
 /**
- * Always present — the representative point.
+ * A single point representing the designation. Always present.
  */
 export type DesignationCentroid = {
   /**
-   * [longitude, latitude] in WGS84 — GeoJSON-spec order.
+   * Longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order).
    */
   coordinates: Array<number>;
   type: DesignationCentroidType;