@vepler/sdk 3.3.0 → 5.28.1

package/src/funcs/schoolsFrameworksList.ts

@@ -25,12 +25,10 @@ import { APICall, APIPromise } from "../sdk/types/async.js";
 import { Result } from "../sdk/types/fp.js";
 
 /**
- * List all framework catalog entries
+ * List all framework catalogue entries
  *
  * @remarks
- * Returns every framework registered against the Schools API — performance, destinations, census, finance, admissions and inspections — grouped by country and publishing authority. AI agents fetch this once per session and use it to interpret metric codes that appear inside per-school responses without inlining self-documentation on every payload.
- *
- * Cache aggressively: `Cache-Control: public, max-age=86400, immutable`. Changes are mirrored to `/v1/schools/changelog`.
+ * Lists every framework the Schools API publishes figures under, covering performance, destinations, census, finance, admissions and inspections. Each entry names the country, the authority that publishes it and the metric codes it carries, so metric codes seen in a school response can be interpreted without asking for definitions on every call. An entry with an empty `metricCodes` list is registered but not yet loaded. Responses are cacheable for 24 hours, and any change is mirrored to `/v1/schools/changelog`.
  */
 export function schoolsFrameworksList(
   client: SDKCore,

package/src/funcs/schoolsGetGeographicAggregation.ts

@@ -30,7 +30,7 @@ import { Result } from "../sdk/types/fp.js";
  * Aggregate a metric across geography
  *
  * @remarks
- * Aggregate a single metric across local authorities, regions, or nationally. Optional `schoolTypes` filter (comma-separated) limits the contributing schools. Capped at 1000 area rows.
+ * Summarises one metric across areas rather than schools, giving the mean, minimum, maximum and standard deviation for each area along with how many schools contributed. Group by local authority, by region, or into a single national row. `schoolTypes` narrows which schools count towards the totals. Rows come back most-contributing first, and at most 1000 of them.
  */
 export function schoolsGetGeographicAggregation(
   client: SDKCore,

package/src/funcs/schoolsGetMetrics.ts

@@ -30,7 +30,7 @@ import { Result } from "../sdk/types/fp.js";
  * Get school metrics
  *
  * @remarks
- * Retrieve metrics for specified schools using metric codes or predefined profiles. Supports both point-in-time and time series queries.
+ * Returns published figures for one or more schools: results, attendance, finance, pupil characteristics and destinations. Name the figures either with `metricCodes` or with a `profile`, never both. By default the response covers a single academic year; set `timeseries=true` with `startYear` and `endYear` for a value per year instead. `includeDefinitions` returns what each code means and `includeComparisons` returns national, regional and similar-school averages beside it.
  */
 export function schoolsGetMetrics(
   client: SDKCore,

package/src/funcs/schoolsGetSchoolById.ts

@@ -30,7 +30,7 @@ import { Result } from "../sdk/types/fp.js";
  * Get school by id
  *
  * @remarks
- * Retrieve a single school by its internal identifier.
+ * Returns one school by its identifier in this API. Use `attributes` to add aggregate blocks such as `inspections`, or to trim the response to the fields you need.
  */
 export function schoolsGetSchoolById(
   client: SDKCore,

package/src/funcs/schoolsGetSchoolBySource.ts

@@ -30,7 +30,7 @@ import { Result } from "../sdk/types/fp.js";
  * Get school by provider and key
  *
  * @remarks
- * Retrieve a single school by its source register identifier. Provider codes: `dfe` (England + Wales URNs), `welshgov` (Wales School Number), `seed` (Scottish SEED), `deni` (NI DE Reference), `dept_edu_ie` (Irish Roll Number).
+ * Returns one school by the identifier its own national register uses, for callers holding a register key rather than an identifier from this API. The registers are `dfe` for England and cross-border Welsh URNs, `welshgov` for the Welsh Government school number, `seed` for the Scottish SEED code, `deni` for the Northern Ireland reference and `dept_edu_ie` for the Irish roll number. Use `attributes` to add aggregate blocks or trim the fields returned.
  */
 export function schoolsGetSchoolBySource(
   client: SDKCore,

package/src/funcs/schoolsListProfiles.ts

@@ -27,7 +27,7 @@ import { Result } from "../sdk/types/fp.js";
  * List metric profiles
  *
  * @remarks
- * Get a list of all available metric profiles with their descriptions and metric counts
+ * Lists the metric profiles accepted by the `profile` parameter on `/v1/schools/metrics`, with what each one covers and how many metric codes it expands to. Read this first to avoid naming codes by hand.
  */
 export function schoolsListProfiles(
   client: SDKCore,

package/src/funcs/schoolsQuerySchools.ts

@@ -30,9 +30,7 @@ import { Result } from "../sdk/types/fp.js";
  * Query schools with filters and optional catchment enrichment
  *
  * @remarks
- * Search for schools by country/region, type, status, rating, authority, postcode, free-text, or geography (radius via `near` or bounding box via `within`). Supports pagination via `limit`/`offset` and ordering via `orderBy`/`order`.
- *
- * **Catchment enrichment.** Set `catchmentReference` (with either `uprn` or `point`) to embed a five-tier catchment match per school. Each school gains an inline `catchment` block (`matchBasis` + `verdict`) and the response gains a `meta.catchment` block describing which tiers were applied / skipped and any coverage warnings. When `catchmentReference` is supplied with `uprn` but no `near` or `within`, the server defaults `near` to the property point with a 10 km radius.
+ * Searches schools by country and region, by type, status, rating, authority, postcode or free text, or by geography with `near` for a radius and `within` for a bounding box. Page through the results with `limit` and `offset`, up to 100 schools per page. Supplying `catchmentReference`, with either a `uprn` or a `point`, also tests every returned school against that property: each one gains a `catchment` block saying why it matched and how firmly, and the response gains a `meta.catchment` block saying which kinds of evidence were used, which were not and why. When `catchmentReference` is supplied without `near` or `within`, the search is centred on the property with a 10 km radius.
  */
 export function schoolsQuerySchools(
   client: SDKCore,

package/src/funcs/schoolsQuerySchoolsBySource.ts

@@ -30,7 +30,7 @@ import { Result } from "../sdk/types/fp.js";
  * Batch fetch schools by provider keys
  *
  * @remarks
- * Retrieve multiple schools from a single source register by their provider-scoped keys. Maximum 500 keys per request. Keys that do not match are silently omitted.
+ * Looks up several schools in one national register in a single call, by the keys that register uses. At most 500 keys per request. Keys that match no school are left out of the response rather than reported as errors, so compare the results against what was sent.
  */
 export function schoolsQuerySchoolsBySource(
   client: SDKCore,

package/src/funcs/searchSearchSuggest.ts

@@ -28,18 +28,10 @@ import { APICall, APIPromise } from "../sdk/types/async.js";
 import { Result } from "../sdk/types/fp.js";
 
 /**
- * Autocomplete search for UK addresses and locations
+ * Autocomplete UK addresses and locations
  *
  * @remarks
- * Simple autocomplete for UK properties and locations. Searches across Address and Location sources with fuzzy matching. Automatically detects query type (postcode, address, place name) and returns suggestions.
- *
- * Optionally accepts a geographic centre point (`lat`, `lng`) to make results proximity-aware:
- * - `geo_mode=bias` (default): soft preference. The best textual matches near the point rank higher, but distant matches are still returned.
- * - `geo_mode=restrict`: hard cutoff. Only address results within `radius_meters` of the point are returned.
- *
- * Proximity shapes the RANKING (bias) and membership (restrict) of the address results; pair it with `source=address` for the most predictable proximity behaviour. Suggest returns a discovery projection only — address rows carry the label, UPRN and match highlights, never coordinates, distance or classification. Retrieve a chosen suggestion (`GET /search/retrieve`) for the full record including coordinates.
- *
- * Candidate-set sessions: once a query narrows to a small exact match set, the response carries a `search_id` and slim address rows (label + UPRN + match highlights). Pass `search_id` back on subsequent keystrokes to narrow within that set without a new data fetch; when `set_complete` is true the response already contains the complete match set, so further narrowing can happen client-side. Suggest responses are not charged — charging applies when a full record is retrieved.
+ * Type-ahead search over UK addresses and locations, with fuzzy matching. It works out for itself whether the query is a postcode, an address or a place name, and returns suggestions in one list. Supplying a centre point (`lat` and `lng`) makes address results proximity-aware: `geo_mode=bias`, the default, is a soft preference that ranks nearby matches higher while still returning distant ones, and `geo_mode=restrict` is a hard cutoff that returns only results within `radius_meters` of the point. Proximity therefore changes the order of address results under `bias` and which ones appear at all under `restrict`; pair it with `source=address` for the most predictable behaviour. Suggestions are a discovery view: an address row carries its label, its UPRN and the match highlights, and never coordinates, distance or classification. Look the chosen UPRN up with `GET /v1/address/uprn/{uprn}` for the full record. Once a query narrows to a small exact match set the response also carries a `search_id`. Send it back on the next keystroke to narrow within that set rather than fetching again, and when `set_complete` is true the response already holds every match, so further narrowing can happen in the client. Suggest responses are not charged per request: each search session settles one small flat charge, and full-record lookups are charged by the address endpoints.
  */
 export function searchSearchSuggest(
   client: SDKCore,

package/src/funcs/sitesAggregate.ts

@@ -30,13 +30,7 @@ import { Result } from "../sdk/types/fp.js";
  * Aggregate sites
  *
  * @remarks
- * Run aggregations (analytics) on the sites index with optional filters and geographic area filters.
- *
- * Supports 14 aggregation types including terms, stats, histogram, date_histogram, percentiles, and geotile_grid. Up to 10 aggregations per request with up to 2 levels of nesting (sub-aggregations).
- *
- * The response `aggregations` object is keyed by the `name` you provide in each aggregation definition. The result shape depends on the aggregation type — see the AggregationResult schema for details.
- *
- * Filter interaction is the same as the search endpoint: `filters` AND `query` AND any `area` filter.
+ * Summarise sites in bulk rather than listing them: counts by tenure, area statistics, distributions over time, map-tile groupings, and so on. The same filters and geographic areas as the search endpoint decide which sites are counted. There are 14 aggregation types, and a request may carry up to 10 aggregations, each nested up to two levels deep. Results come back keyed by the `name` given in each definition, so pick names that are unique within the request.
  */
 export function sitesAggregate(
   client: SDKCore,

package/src/funcs/sitesFindByIds.ts

@@ -30,7 +30,7 @@ import { Result } from "../sdk/types/fp.js";
  * Batch lookup sites by IDs
  *
  * @remarks
- * Retrieve multiple sites by their composite identifiers in a single request (max 100). IDs that do not match any site are silently omitted from the response — check `total_count` against your input length to detect missing sites. Supports attribute selection to control which fields are returned.
+ * Retrieve up to 100 sites by identifier in a single request, choosing which fields come back with `attributes`. Identifiers that match nothing are left out of the response rather than raising an error, so compare `total_count` against the number of identifiers sent to spot the ones that were not found.
  */
 export function sitesFindByIds(
   client: SDKCore,

package/src/funcs/sitesFindByPoint.ts

@@ -31,7 +31,7 @@ import { Result } from "../sdk/types/fp.js";
  * Find sites by point
  *
  * @remarks
- * Find land titles whose boundary polygon contains the given WGS84 (EPSG:4326) coordinate. This is a point-in-polygon spatial query — returns all titles at that location. Multiple overlapping titles are common (e.g. a freehold and leasehold at the same address). Returns up to 50 matching sites. Returns an empty list (not a 404) if no titles contain the point.
+ * Find every registered title whose boundary encloses a single coordinate, given as latitude and longitude in WGS84 decimal degrees. Overlapping titles at one spot are common, such as a freehold and a leasehold over the same building. Up to 50 sites come back, and a point inside no title returns an empty list rather than a 404.
  */
 export function sitesFindByPoint(
   client: SDKCore,

package/src/funcs/sitesFindByProperty.ts

@@ -31,7 +31,7 @@ import { Result } from "../sdk/types/fp.js";
  * Find sites by property
  *
  * @remarks
- * Find land titles that contain a specific property UPRN (Unique Property Reference Number). A property can belong to multiple titles (e.g. a flat in a freehold building will match both the leasehold and freehold titles). Returns up to 50 matching sites.
+ * Find the registered titles that cover a single addressable location. One location often sits under several titles at once, so a flat in a freehold block matches both its leasehold title and the freehold above it. Up to 50 sites come back, and a location with no titles returns an empty list rather than a 404.
  */
 export function sitesFindByProperty(
   client: SDKCore,

package/src/funcs/sitesGet.ts

@@ -31,7 +31,7 @@ import { Result } from "../sdk/types/fp.js";
  * Get site by ID
  *
  * @remarks
- * Retrieve a single site by its composite identifier in `{country}:{registry}:{titleRef}` format (e.g. `GB:NPS:AGL123456`). Returns the full site object including boundary geometry, property statistics, planning data, scores, and area metrics. Requires a valid API key passed via the `Authorization: Bearer <key>` header.
+ * Retrieve one registered title by its identifier, which joins the country, the registry and the title number with colons, as in `GB:NPS:AGL123456`. This endpoint returns every attribute, including the boundary geometry, ownership, property statistics, planning statistics and area metrics.
  */
 export function sitesGet(
   client: SDKCore,

package/src/funcs/sitesGetProperties.ts

@@ -31,7 +31,7 @@ import { Result } from "../sdk/types/fp.js";
  * Get properties in site
  *
  * @remarks
- * Get all UPRNs (Unique Property Reference Numbers) linked to a specific site via spatial intersection with the Ordnance Survey AddressBase dataset. Returns an array of UPRN strings and the total count. Use these UPRNs with the Property API to fetch full property details.
+ * List the addressable locations that fall within one registered title, matched against the Ordnance Survey AddressBase dataset. The response carries the identifiers and how many there are; pass them to the Property API to fetch the full property records.
  */
 export function sitesGetProperties(
   client: SDKCore,

package/src/funcs/sitesGetTiles.ts

@@ -31,15 +31,7 @@ import { Result } from "../sdk/types/fp.js";
  * Get site boundary tiles
  *
  * @remarks
- * Retrieve site boundaries as Mapbox Vector Tiles (MVT / application/x-protobuf) for map visualisation.
- *
- * Returns actual polygon geometries rendered from the `boundary` geo_shape field — not simplified or clustered points. Each feature in the tile includes properties specified by the `fields` parameter (defaults to siteId, titleRef, tenureType, status, areaSqm, locationCount, areaMetrics.prosperityDecile).
- *
- * **Zoom constraint:** Only available at zoom level 12 and above. Requests below zoom 12 return a 400 error — site polygons are too small and dense to render meaningfully at lower zoom levels.
- *
- * **Filtering:** Supports the same filter, query, and area parameters as the search endpoint, passed as JSON-encoded query parameters. Maximum 10,000 features per tile.
- *
- * **Caching:** Responses include `Cache-Control: public, max-age=30, s-maxage=60` headers. Suitable for use with Mapbox GL JS, MapLibre GL JS, or any MVT-compatible map renderer.
+ * Draw title boundaries on a map. Each tile comes back as a Mapbox Vector Tile (`application/x-protobuf`) carrying the real boundary polygons, not simplified shapes or clustered points, ready for MapLibre GL JS, Mapbox GL JS or any renderer that reads vector tiles. Tiles are served from zoom 12 upwards; below that the polygons are too small and too densely packed to draw usefully, and the request fails. A tile carries at most 10,000 features, and the same filter, query and area parameters as the search endpoint narrow what it holds. Responses carry `Cache-Control: public, max-age=30, s-maxage=60`, so a shared cache or CDN can serve repeat views.
  */
 export function sitesGetTiles(
   client: SDKCore,

package/src/funcs/sitesSearch.ts

@@ -30,18 +30,7 @@ import { Result } from "../sdk/types/fp.js";
  * Search sites
  *
  * @remarks
- * Search sites with advanced filters, geographic area filters, sorting, and pagination.
- *
- * **Filter interaction logic:**
- * - `filters` (convenience) and `query` (advanced) are combined with AND logic — a site must match both.
- * - Multiple `area` filters are combined with OR logic — a site matches if it satisfies any area filter.
- * - Area filters are combined with AND against the other filters.
- *
- * **Spatial queries:** Supports polygon, multi-polygon, point+radius, containsPoint, and bounding box area types.
- *
- * **Attribute selection:** By default, the heavy `boundary` geometry is excluded. Pass `attributes: ["boundary"]` to include it.
- *
- * Requires a valid API key via `Authorization: Bearer <key>` header.
+ * Search registered titles by their attributes, by geographic area, or by both, with sorting and pagination. Area filters accept a polygon, a multi-polygon, a point with a radius, a point the boundary must enclose, or a bounding box; a site matches the area clause if it satisfies any one of the filters supplied, and that has to hold on top of `filters` and `query`. The `boundary` geometry is left out by default because of its size, so pass `attributes: ["boundary"]` to get site polygons back. Up to 1000 sites come back per request, from an offset of at most 100000.
  */
 export function sitesSearch(
   client: SDKCore,

package/src/funcs/streetsSearchStreets.ts

@@ -27,10 +27,10 @@ import { APICall, APIPromise } from "../sdk/types/async.js";
 import { Result } from "../sdk/types/fp.js";
 
 /**
- * Query streets with flexible identifiers
+ * Query streets by any identifier
  *
  * @remarks
- * Query streets using USRN, UPRN, coordinates, name, or postcode. Optionally include properties and statistics.
+ * Returns the streets picked out by one of five identifiers: a USRN, a UPRN, a coordinate and radius, a name search, or a postcode. Each street comes back with its reference number, the coordinates of its start and end, and its name in each language it is recorded in. When an identifier matches no street, the response is an empty list with a `message` explaining which one missed.
  */
 export function streetsSearchStreets(
   client: SDKCore,

package/src/funcs/systemCheckAVMHealth.ts

@@ -27,7 +27,7 @@ import { Result } from "../sdk/types/fp.js";
  * AVM service health check
  *
  * @remarks
- * Check if the AVM service is operational
+ * Check whether the valuation service is operating.
  */
 export function systemCheckAVMHealth(
   client: SDKCore,

package/src/funcs/systemCheckAreaReferenceHealth.ts

@@ -24,10 +24,10 @@ import { APICall, APIPromise } from "../sdk/types/async.js";
 import { Result } from "../sdk/types/fp.js";
 
 /**
- * Area reference service health check
+ * Check area reference service health
  *
  * @remarks
- * Check if the area reference proxy service is operational
+ * Reports whether the area reference endpoints are serving requests.
  */
 export function systemCheckAreaReferenceHealth(
   client: SDKCore,

package/src/funcs/systemCheckCensusHealth.ts

@@ -24,10 +24,10 @@ import { APICall, APIPromise } from "../sdk/types/async.js";
 import { Result } from "../sdk/types/fp.js";
 
 /**
- * Census service health check
+ * Check census service health
  *
  * @remarks
- * Check if the census service is operational.
+ * Reports whether the census service is answering requests.
  */
 export function systemCheckCensusHealth(
   client: SDKCore,

package/src/funcs/systemCheckCompaniesHealth.ts

@@ -24,10 +24,10 @@ import { APICall, APIPromise } from "../sdk/types/async.js";
 import { Result } from "../sdk/types/fp.js";
 
 /**
- * Companies House service health check
+ * Check Companies House service health
  *
  * @remarks
- * Check if the Companies House service is operational
+ * Reports whether the Companies House endpoints are operational. Returns no company data.
  */
 export function systemCheckCompaniesHealth(
   client: SDKCore,

package/src/funcs/systemCheckListingsHealth.ts

@@ -27,7 +27,7 @@ import { Result } from "../sdk/types/fp.js";
  * Listings service health check
  *
  * @remarks
- * Check if the listings service is operational
+ * Reports whether the listings service is answering requests.
  */
 export function systemCheckListingsHealth(
   client: SDKCore,

package/src/funcs/systemCheckLocationHealth.ts

@@ -24,10 +24,10 @@ import { APICall, APIPromise } from "../sdk/types/async.js";
 import { Result } from "../sdk/types/fp.js";
 
 /**
- * Location service health check
+ * Check location service health
  *
  * @remarks
- * Check if the location service is operational
+ * Reports whether the location service is running. Use it as a liveness check.
  */
 export function systemCheckLocationHealth(
   client: SDKCore,

package/src/funcs/systemCheckPlanningHealth.ts

@@ -24,10 +24,10 @@ import { APICall, APIPromise } from "../sdk/types/async.js";
 import { Result } from "../sdk/types/fp.js";
 
 /**
- * Planning service health check
+ * Check planning service health
  *
  * @remarks
- * Check if the planning service is operational
+ * Confirms that the planning endpoints are reachable. The check does not read any planning data, so a healthy response says nothing about whether that data is available.
  */
 export function systemCheckPlanningHealth(
   client: SDKCore,

package/src/funcs/systemCheckPropertyHealth.ts

@@ -24,10 +24,10 @@ import { APICall, APIPromise } from "../sdk/types/async.js";
 import { Result } from "../sdk/types/fp.js";
 
 /**
- * Property service health check
+ * Check property service health
  *
  * @remarks
- * Check if the property service is operational
+ * Reports whether the property service is answering requests. It takes no parameters.
  */
 export function systemCheckPropertyHealth(
   client: SDKCore,

package/src/funcs/systemCheckSchoolsHealth.ts

@@ -27,7 +27,7 @@ import { Result } from "../sdk/types/fp.js";
  * Schools service health check
  *
  * @remarks
- * Check if the schools service is operational
+ * Reports whether the schools endpoints are answering. Returns no school data.
  */
 export function systemCheckSchoolsHealth(
   client: SDKCore,

package/src/funcs/systemCheckSearchHealth.ts

@@ -24,10 +24,10 @@ import { APICall, APIPromise } from "../sdk/types/async.js";
 import { Result } from "../sdk/types/fp.js";
 
 /**
- * Search service health check
+ * Check search service health
  *
  * @remarks
- * Check if the search service is operational
+ * Reports whether the search service is running. Use it as a liveness check.
  */
 export function systemCheckSearchHealth(
   client: SDKCore,

package/src/funcs/systemGetSafetyHealth.ts

@@ -27,7 +27,7 @@ import { Result } from "../sdk/types/fp.js";
  * Safety service health check
  *
  * @remarks
- * Check if the safety service is operational.
+ * Check whether the safety service is operating.
  */
 export function systemGetSafetyHealth(
   client: SDKCore,

package/src/funcs/titleDeedsGetV1TitleDeedsTitleNumber.ts

@@ -28,10 +28,10 @@ import { APICall, APIPromise } from "../sdk/types/async.js";
 import { Result } from "../sdk/types/fp.js";
 
 /**
- * Poll for the enriched title deed extraction
+ * Get the structured extraction for a title deed
  *
  * @remarks
- * Returns the current state of the async extraction pipeline for this title. Status progresses through pending → analysing → complete. When complete, the response includes the full UI-ready extraction payload. Tenant-gated by prior purchase.
+ * Returns the structured reading of the register for a title purchased through the asynchronous route. Status moves from `pending` to `analysing` to `complete`, and the extraction payload is present only once it is complete. The title must already have been purchased on this account.
  */
 export function titleDeedsGetV1TitleDeedsTitleNumber(
   client: SDKCore,

package/src/funcs/titleDeedsGetV1TitleDeedsTitleNumberDocuments.ts

@@ -31,7 +31,7 @@ import { Result } from "../sdk/types/fp.js";
  * List documents for a purchased title deed
  *
  * @remarks
- * Returns all documents associated with a title deed, including their processing status (pending, uploaded, or failed).
+ * Lists the documents held for a title, each with the status that says whether it can be downloaded yet. The title must already have been purchased on this account.
  */
 export function titleDeedsGetV1TitleDeedsTitleNumberDocuments(
   client: SDKCore,

package/src/funcs/titleDeedsGetV1TitleDeedsTitleNumberDocumentsDocumentType.ts

@@ -28,10 +28,10 @@ import { APICall, APIPromise } from "../sdk/types/async.js";
 import { Result } from "../sdk/types/fp.js";
 
 /**
- * Download a specific document for a purchased title deed
+ * Download a document for a purchased title deed
  *
  * @remarks
- * Downloads a PDF document by type. Only available for documents with status 'uploaded'.
+ * Downloads one of the title's documents as a PDF. Only documents whose status is `uploaded` can be downloaded, and the title must already have been purchased on this account.
  */
 export function titleDeedsGetV1TitleDeedsTitleNumberDocumentsDocumentType(
   client: SDKCore,

package/src/funcs/{searchSearchRetrieve.ts → titleDeedsGetV1TitleDeedsTitleNumberPurchaseStatus.ts}

@@ -3,7 +3,7 @@
  */
 
 import { SDKCore } from "../core.js";
-import { encodeFormQuery } from "../lib/encodings.js";
+import { encodeSimple } from "../lib/encodings.js";
 import { matchStatusCode } from "../lib/http.js";
 import * as M from "../lib/matchers.js";
 import { compactMap } from "../lib/primitives.js";
@@ -23,30 +23,26 @@ import { ResponseValidationError } from "../sdk/models/errors/responsevalidation
 import { SDKBaseError } from "../sdk/models/errors/sdkbaseerror.js";
 import { SDKValidationError } from "../sdk/models/errors/sdkvalidationerror.js";
 import * as operations from "../sdk/models/operations/index.js";
-import * as shared from "../sdk/models/shared/index.js";
 import { APICall, APIPromise } from "../sdk/types/async.js";
 import { Result } from "../sdk/types/fp.js";
 
 /**
- * Retrieve the full address record for a selected suggestion
+ * Check the purchase status of a title deed
  *
  * @remarks
- * The selection step of the candidate-set search flow. Suggest responses are free and carry only a discovery projection (label + UPRN + match highlights); pass the chosen suggestion's `uprn` here to receive the full address record — address lines, postcode, coordinates and classification.
- *
- * Include the `search_id` from the suggest response to complete that search session; the retrieval is then recorded against it. Without a `search_id` (or with one that has expired or is unknown) the endpoint still works as a direct resolve and is recorded as its own transaction.
- *
- * This endpoint is charged per retrieved record. Repeat retrievals of the same UPRN within a billing window are charged once — see the `X-Already-Charged` response header.
+ * Reports what this account has been charged for a title, without buying it. Use this before retrying a purchase whose result is uncertain, or to check whether an already-owned title can be fetched without charging a second time. Where the outcome is not implied by the status code, the body states it as `money_state`, so a caller never has to infer it.
  */
-export function searchSearchRetrieve(
+export function titleDeedsGetV1TitleDeedsTitleNumberPurchaseStatus(
   client: SDKCore,
-  request: operations.SearchRetrieveRequest,
+  request: operations.GetV1TitleDeedsTitleNumberPurchaseStatusRequest,
   options?: RequestOptions,
 ): APIPromise<
   Result<
-    shared.SearchRetrieveResponse,
-    | errors.SearchRetrieveResponseBody
-    | errors.SearchRetrieveSearchResponseBody
-    | errors.SearchRetrieveSearchResponseResponseBody
+    operations.GetV1TitleDeedsTitleNumberPurchaseStatusResponse,
+    | errors.GetV1TitleDeedsTitleNumberPurchaseStatusResponseBody
+    | errors.GetV1TitleDeedsTitleNumberPurchaseStatusTitleDeedsResponseBody
+    | errors.TitleDeedPurchaseNotFound
+    | errors.TitleDeedPurchaseError
     | SDKBaseError
     | ResponseValidationError
     | ConnectionError
@@ -66,15 +62,16 @@ export function searchSearchRetrieve(
 
 async function $do(
   client: SDKCore,
-  request: operations.SearchRetrieveRequest,
+  request: operations.GetV1TitleDeedsTitleNumberPurchaseStatusRequest,
   options?: RequestOptions,
 ): Promise<
   [
     Result<
-      shared.SearchRetrieveResponse,
-      | errors.SearchRetrieveResponseBody
-      | errors.SearchRetrieveSearchResponseBody
-      | errors.SearchRetrieveSearchResponseResponseBody
+      operations.GetV1TitleDeedsTitleNumberPurchaseStatusResponse,
+      | errors.GetV1TitleDeedsTitleNumberPurchaseStatusResponseBody
+      | errors.GetV1TitleDeedsTitleNumberPurchaseStatusTitleDeedsResponseBody
+      | errors.TitleDeedPurchaseNotFound
+      | errors.TitleDeedPurchaseError
       | SDKBaseError
       | ResponseValidationError
       | ConnectionError
@@ -89,7 +86,9 @@ async function $do(
 > {
   const parsed = safeParse(
     request,
-    (value) => operations.SearchRetrieveRequest$outboundSchema.parse(value),
+    (value) =>
+      operations.GetV1TitleDeedsTitleNumberPurchaseStatusRequest$outboundSchema
+        .parse(value),
     "Input validation failed",
   );
   if (!parsed.ok) {
@@ -98,12 +97,15 @@ async function $do(
   const payload = parsed.value;
   const body = null;
 
-  const path = pathToFunc("/v1/search/retrieve")();
-
-  const query = encodeFormQuery({
-    "search_id": payload.search_id,
-    "uprn": payload.uprn,
-  });
+  const pathParams = {
+    titleNumber: encodeSimple("titleNumber", payload.titleNumber, {
+      explode: false,
+      charEncoding: "percent",
+    }),
+  };
+  const path = pathToFunc("/v1/title-deeds/{titleNumber}/purchase-status")(
+    pathParams,
+  );
 
   const headers = new Headers(compactMap({
     Accept: "application/json",
@@ -116,7 +118,7 @@ async function $do(
   const context = {
     options: client._options,
     baseURL: options?.serverURL ?? client._baseURL ?? "",
-    operationID: "searchRetrieve",
+    operationID: "get_/v1/title-deeds/{titleNumber}/purchase-status",
     oAuth2Scopes: null,
 
     resolvedSecurity: requestSecurity,
@@ -134,7 +136,6 @@ async function $do(
     baseURL: options?.serverURL,
     path: path,
     headers: headers,
-    query: query,
     body: body,
     userAgent: client._options.userAgent,
     timeoutMs: options?.timeoutMs || client._options.timeoutMs || -1,
@@ -161,10 +162,11 @@ async function $do(
   };
 
   const [result] = await M.match<
-    shared.SearchRetrieveResponse,
-    | errors.SearchRetrieveResponseBody
-    | errors.SearchRetrieveSearchResponseBody
-    | errors.SearchRetrieveSearchResponseResponseBody
+    operations.GetV1TitleDeedsTitleNumberPurchaseStatusResponse,
+    | errors.GetV1TitleDeedsTitleNumberPurchaseStatusResponseBody
+    | errors.GetV1TitleDeedsTitleNumberPurchaseStatusTitleDeedsResponseBody
+    | errors.TitleDeedPurchaseNotFound
+    | errors.TitleDeedPurchaseError
     | SDKBaseError
     | ResponseValidationError
     | ConnectionError
@@ -174,13 +176,25 @@ async function $do(
     | UnexpectedClientError
     | SDKValidationError
   >(
-    M.json(200, shared.SearchRetrieveResponse$inboundSchema),
-    M.jsonErr(400, errors.SearchRetrieveResponseBody$inboundSchema),
-    M.jsonErr(404, errors.SearchRetrieveSearchResponseBody$inboundSchema),
+    M.json(
+      200,
+      operations.GetV1TitleDeedsTitleNumberPurchaseStatusResponse$inboundSchema,
+    ),
+    M.json(
+      202,
+      operations.GetV1TitleDeedsTitleNumberPurchaseStatusResponse$inboundSchema,
+    ),
+    M.jsonErr(
+      400,
+      errors.GetV1TitleDeedsTitleNumberPurchaseStatusResponseBody$inboundSchema,
+    ),
     M.jsonErr(
-      500,
-      errors.SearchRetrieveSearchResponseResponseBody$inboundSchema,
+      401,
+      errors
+        .GetV1TitleDeedsTitleNumberPurchaseStatusTitleDeedsResponseBody$inboundSchema,
     ),
+    M.jsonErr(404, errors.TitleDeedPurchaseNotFound$inboundSchema),
+    M.jsonErr(500, errors.TitleDeedPurchaseError$inboundSchema),
     M.fail("4XX"),
     M.fail("5XX"),
   )(response, req, { extraFields: responseFields });