@vepler/sdk 3.0.0 → 5.28.1

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 });

package/src/funcs/titleDeedsPostV1TitleDeedsTitleNumberPurchase.ts

@@ -23,7 +23,6 @@ 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";
 
@@ -31,7 +30,7 @@ import { Result } from "../sdk/types/fp.js";
  * Purchase a title deed
  *
  * @remarks
- * Purchase title deed data by title number. Costs 7 credits per title. Previously purchased titles are returned at no additional cost.
+ * Buys the registered title for a title number and returns its property details, proprietors and documents. Each title costs a fixed number of credits, deducted when the purchase succeeds. A title already purchased on this account is returned again at no charge. Every documented error body states whether this account has been charged as `money_state`. Read that rather than inferring it from the status code, because a 202 means the purchase succeeded and is still being delivered, and must not be refunded.
  */
 export function titleDeedsPostV1TitleDeedsTitleNumberPurchase(
   client: SDKCore,
@@ -39,13 +38,11 @@ export function titleDeedsPostV1TitleDeedsTitleNumberPurchase(
   options?: RequestOptions,
 ): APIPromise<
   Result<
-    shared.TitleDeedPurchaseResponse,
+    operations.PostV1TitleDeedsTitleNumberPurchaseResponse,
     | errors.PostV1TitleDeedsTitleNumberPurchaseResponseBody
     | errors.PostV1TitleDeedsTitleNumberPurchaseTitleDeedsResponseBody
     | errors.InsufficientCreditsError
-    | errors.PostV1TitleDeedsTitleNumberPurchaseTitleDeedsResponseResponseBody
-    | errors.PostV1TitleDeedsTitleNumberPurchaseTitleDeedsResponse500ResponseBody
-    | errors.PostV1TitleDeedsTitleNumberPurchaseTitleDeedsResponse502ResponseBody
+    | errors.TitleDeedPurchaseError
     | SDKBaseError
     | ResponseValidationError
     | ConnectionError
@@ -70,13 +67,11 @@ async function $do(
 ): Promise<
   [
     Result<
-      shared.TitleDeedPurchaseResponse,
+      operations.PostV1TitleDeedsTitleNumberPurchaseResponse,
       | errors.PostV1TitleDeedsTitleNumberPurchaseResponseBody
       | errors.PostV1TitleDeedsTitleNumberPurchaseTitleDeedsResponseBody
       | errors.InsufficientCreditsError
-      | errors.PostV1TitleDeedsTitleNumberPurchaseTitleDeedsResponseResponseBody
-      | errors.PostV1TitleDeedsTitleNumberPurchaseTitleDeedsResponse500ResponseBody
-      | errors.PostV1TitleDeedsTitleNumberPurchaseTitleDeedsResponse502ResponseBody
+      | errors.TitleDeedPurchaseError
       | SDKBaseError
       | ResponseValidationError
       | ConnectionError
@@ -165,13 +160,11 @@ async function $do(
   };
 
   const [result] = await M.match<
-    shared.TitleDeedPurchaseResponse,
+    operations.PostV1TitleDeedsTitleNumberPurchaseResponse,
     | errors.PostV1TitleDeedsTitleNumberPurchaseResponseBody
     | errors.PostV1TitleDeedsTitleNumberPurchaseTitleDeedsResponseBody
     | errors.InsufficientCreditsError
-    | errors.PostV1TitleDeedsTitleNumberPurchaseTitleDeedsResponseResponseBody
-    | errors.PostV1TitleDeedsTitleNumberPurchaseTitleDeedsResponse500ResponseBody
-    | errors.PostV1TitleDeedsTitleNumberPurchaseTitleDeedsResponse502ResponseBody
+    | errors.TitleDeedPurchaseError
     | SDKBaseError
     | ResponseValidationError
     | ConnectionError
@@ -181,7 +174,14 @@ async function $do(
     | UnexpectedClientError
     | SDKValidationError
   >(
-    M.json(200, shared.TitleDeedPurchaseResponse$inboundSchema),
+    M.json(
+      200,
+      operations.PostV1TitleDeedsTitleNumberPurchaseResponse$inboundSchema,
+    ),
+    M.json(
+      202,
+      operations.PostV1TitleDeedsTitleNumberPurchaseResponse$inboundSchema,
+    ),
     M.jsonErr(
       400,
       errors.PostV1TitleDeedsTitleNumberPurchaseResponseBody$inboundSchema,
@@ -192,21 +192,8 @@ async function $do(
         .PostV1TitleDeedsTitleNumberPurchaseTitleDeedsResponseBody$inboundSchema,
     ),
     M.jsonErr(402, errors.InsufficientCreditsError$inboundSchema),
-    M.jsonErr(
-      404,
-      errors
-        .PostV1TitleDeedsTitleNumberPurchaseTitleDeedsResponseResponseBody$inboundSchema,
-    ),
-    M.jsonErr(
-      500,
-      errors
-        .PostV1TitleDeedsTitleNumberPurchaseTitleDeedsResponse500ResponseBody$inboundSchema,
-    ),
-    M.jsonErr(
-      502,
-      errors
-        .PostV1TitleDeedsTitleNumberPurchaseTitleDeedsResponse502ResponseBody$inboundSchema,
-    ),
+    M.jsonErr(404, errors.TitleDeedPurchaseError$inboundSchema),
+    M.jsonErr([500, 502, 503], errors.TitleDeedPurchaseError$inboundSchema),
     M.fail("4XX"),
     M.fail("5XX"),
   )(response, req, { extraFields: responseFields });

package/src/funcs/titleDeedsPostV1TitleDeedsTitleNumberPurchaseAsync.ts

@@ -28,10 +28,10 @@ import { APICall, APIPromise } from "../sdk/types/async.js";
 import { Result } from "../sdk/types/fp.js";
 
 /**
- * Start an async title deed purchase with AI extraction
+ * Start a title deed purchase with structured extraction
  *
  * @remarks
- * Kicks off the async purchase + Qwen extraction pipeline. Returns immediately with a status hint. Poll GET /v1/title-deeds/{titleNumber} to retrieve the enriched extraction once complete. Idempotent per (tenant, titleNumber) — a second call for a title the tenant already owns does not charge credits again.
+ * Starts a purchase that also reads the register into structured detail, and returns straight away with the current status. Poll `GET /v1/title-deeds/{titleNumber}` for the result. Calling it twice for the same title on the same account does not charge a second time.
  */
 export function titleDeedsPostV1TitleDeedsTitleNumberPurchaseAsync(
   client: SDKCore,
@@ -44,6 +44,7 @@ export function titleDeedsPostV1TitleDeedsTitleNumberPurchaseAsync(
     | errors.PostV1TitleDeedsTitleNumberPurchaseAsyncTitleDeedsResponseBody
     | errors.InsufficientCreditsError
     | errors.PostV1TitleDeedsTitleNumberPurchaseAsyncTitleDeedsResponseResponseBody
+    | errors.PostV1TitleDeedsTitleNumberPurchaseAsyncTitleDeedsResponse503ResponseBody
     | SDKBaseError
     | ResponseValidationError
     | ConnectionError
@@ -73,6 +74,7 @@ async function $do(
       | errors.PostV1TitleDeedsTitleNumberPurchaseAsyncTitleDeedsResponseBody
       | errors.InsufficientCreditsError
       | errors.PostV1TitleDeedsTitleNumberPurchaseAsyncTitleDeedsResponseResponseBody
+      | errors.PostV1TitleDeedsTitleNumberPurchaseAsyncTitleDeedsResponse503ResponseBody
       | SDKBaseError
       | ResponseValidationError
       | ConnectionError
@@ -168,6 +170,7 @@ async function $do(
     | errors.PostV1TitleDeedsTitleNumberPurchaseAsyncTitleDeedsResponseBody
     | errors.InsufficientCreditsError
     | errors.PostV1TitleDeedsTitleNumberPurchaseAsyncTitleDeedsResponseResponseBody
+    | errors.PostV1TitleDeedsTitleNumberPurchaseAsyncTitleDeedsResponse503ResponseBody
     | SDKBaseError
     | ResponseValidationError
     | ConnectionError
@@ -193,6 +196,11 @@ async function $do(
       errors
         .PostV1TitleDeedsTitleNumberPurchaseAsyncTitleDeedsResponseResponseBody$inboundSchema,
     ),
+    M.jsonErr(
+      503,
+      errors
+        .PostV1TitleDeedsTitleNumberPurchaseAsyncTitleDeedsResponse503ResponseBody$inboundSchema,
+    ),
     M.fail("4XX"),
     M.fail("5XX"),
   )(response, req, { extraFields: responseFields });

package/src/funcs/transactionsGetTransactionById.ts

@@ -28,10 +28,10 @@ import { APICall, APIPromise } from "../sdk/types/async.js";
 import { Result } from "../sdk/types/fp.js";
 
 /**
- * Get transaction by id
+ * Get a transaction by id
  *
  * @remarks
- * Retrieve a single transaction by its opaque composite id ({country}:{provider}:{externalId}).
+ * Returns one transaction by the composite id that search results carry. An id whose provider segment names a source that is not currently served returns a 404.
  */
 export function transactionsGetTransactionById(
   client: SDKCore,

package/src/funcs/transactionsGetTransactionsByUprn.ts

@@ -28,10 +28,10 @@ import { APICall, APIPromise } from "../sdk/types/async.js";
 import { Result } from "../sdk/types/fp.js";
 
 /**
- * Get transactions by UPRN
+ * Get transactions for a UPRN
  *
  * @remarks
- * Retrieve all transactions matched to a UPRN, newest first, cursor-paginated.
+ * Returns the transactions matched to one addressable location, newest first. Results are cursor-paginated, up to 100 per page.
  */
 export function transactionsGetTransactionsByUprn(
   client: SDKCore,

package/src/funcs/transactionsQueryTransactions.ts

@@ -27,10 +27,10 @@ import { APICall, APIPromise } from "../sdk/types/async.js";
 import { Result } from "../sdk/types/fp.js";
 
 /**
- * Advanced transaction search
+ * Search property transactions
  *
  * @remarks
- * Search standardised property transactions (completed sales and lease grants) with a structured field query, geographic area filters, sorting and sparse fieldsets. Cursor-paginated. All monetary values are in minor currency units (e.g. pence for GBP).
+ * Searches completed sales and lease grants by geographic area, structured field conditions and sort order, narrowing each record to the fields named in `attributes` when one is given. Results are cursor-paginated, up to 100 per page. Monetary values are in the minor unit of their currency, so pence for GBP.
  */
 export function transactionsQueryTransactions(
   client: SDKCore,

package/src/lib/config.ts

@@ -60,8 +60,8 @@ export function serverURLFromOptions(options: SDKOptions): URL | null {
 
 export const SDK_METADATA = {
   language: "typescript",
-  openapiDocVersion: "3.0.0",
-  sdkVersion: "0.11.0",
-  genVersion: "2.916.2",
-  userAgent: "speakeasy-sdk/typescript 0.11.0 2.916.2 3.0.0 @vepler/sdk",
+  openapiDocVersion: "5.28.1",
+  sdkVersion: "0.12.0",
+  genVersion: "2.932.9",
+  userAgent: "speakeasy-sdk/typescript 0.12.0 2.932.9 5.28.1 @vepler/sdk",
 } as const;

package/src/lib/http.ts

@@ -45,8 +45,10 @@ export class HTTPClient {
   private requestHooks: BeforeRequestHook[] = [];
   private requestErrorHooks: RequestErrorHook[] = [];
   private responseHooks: ResponseHook[] = [];
+  private options: HTTPClientOptions;
 
-  constructor(private options: HTTPClientOptions = {}) {
+  constructor(options: HTTPClientOptions = {}) {
+    this.options = options;
     this.fetcher = options.fetcher || DEFAULT_FETCHER;
   }
 

package/src/lib/security.ts

@@ -12,17 +12,22 @@ type OAuth2PasswordFlow = {
   tokenURL: string;
 };
 
-export enum SecurityErrorCode {
-  Incomplete = "incomplete",
-  UnrecognisedSecurityType = "unrecognized_security_type",
-}
+export const SecurityErrorCode = {
+  Incomplete: "incomplete",
+  UnrecognisedSecurityType: "unrecognized_security_type",
+} as const;
+export type SecurityErrorCode =
+  (typeof SecurityErrorCode)[keyof typeof SecurityErrorCode];
 
 export class SecurityError extends Error {
+  public code: SecurityErrorCode;
+
   constructor(
-    public code: SecurityErrorCode,
+    code: SecurityErrorCode,
     message: string,
   ) {
     super(message);
+    this.code = code;
     this.name = "SecurityError";
   }
 

package/src/sdk/address.ts

@@ -12,16 +12,22 @@ import { addressResolveAddress } from "../funcs/addressResolveAddress.js";
 import { addressReverseGeocode } from "../funcs/addressReverseGeocode.js";
 import { addressValidatePostcode } from "../funcs/addressValidatePostcode.js";
 import { ClientSDK, RequestOptions } from "../lib/sdks.js";
+import { Changelog } from "./changelog.js";
 import * as operations from "./models/operations/index.js";
 import * as shared from "./models/shared/index.js";
 import { unwrapAsync } from "./types/fp.js";
 
 export class Address extends ClientSDK {
+  private _changelog?: Changelog;
+  get changelog(): Changelog {
+    return (this._changelog ??= new Changelog(this._options));
+  }
+
   /**
-   * Batch postcode lookup
+   * Look up many postcodes at once
    *
    * @remarks
-   * Look up addresses for up to 100 postcodes in a single request. Results are returned keyed by formatted postcode.
+   * Looks up addresses for up to 100 postcodes in one request. Results come back keyed by formatted postcode, each carrying its own status, so a postcode that cannot be resolved does not fail the rest of the batch.
    */
   async bulkLookupPostcodes(
     request?: shared.BulkPostcodeLookupRequest | undefined,
@@ -35,10 +41,10 @@ export class Address extends ClientSDK {
   }
 
   /**
-   * Batch address cleansing and verification
+   * Cleanse and verify addresses in bulk
    *
    * @remarks
-   * Verifies and cleanses up to 25 raw address strings against the national address database. Returns match status, confidence scores, and corrected fields.
+   * Matches up to 25 raw address strings against the national address register and returns the cleansed address for each, with a confidence score, a quality grade and the fields that changed. Use it to tidy an existing address list before loading it.
    */
   async cleanseAddresses(
     request?: shared.AddressCleanseRequest | undefined,
@@ -55,7 +61,7 @@ export class Address extends ClientSDK {
    * Find nearest postcodes
    *
    * @remarks
-   * Returns postcodes near the specified postcode, sorted by distance.
+   * Returns the postcodes closest to a given postcode's centroid, nearest first, with the distance to each in metres.
    */
   async getNearestPostcodes(
     request: operations.GetNearestPostcodesRequest,
@@ -69,10 +75,10 @@ export class Address extends ClientSDK {
   }
 
   /**
-   * Look up outcode area
+   * Look up an outward code
    *
    * @remarks
-   * Returns metadata for an outward code (e.g. SW1A, E1, M1) including centroid, country, region, and postcode count.
+   * Returns what is known about an outward code, the first part of a postcode such as `SW1A`, `E1` or `M1`: a representative point, the country, region and local authority it sits in, and how many postcodes it holds. Add `include=postcodes` for the postcodes themselves.
    */
   async lookupOutcode(
     request: operations.LookupOutcodeRequest,
@@ -89,7 +95,7 @@ export class Address extends ClientSDK {
    * Look up addresses by postcode
    *
    * @remarks
-   * Returns all addresses at a given UK postcode, sorted by house number. Supports pagination and optional geographic context enrichment.
+   * Returns every address at a UK postcode, ordered by house number. Page through them with `limit` and `offset`, and add the administrative and statistical geography for the postcode with `include=geography`.
    */
   async lookupPostcode(
     request: operations.LookupPostcodeRequest,
@@ -103,10 +109,10 @@ export class Address extends ClientSDK {
   }
 
   /**
-   * Look up address by UPRN
+   * Look up an address by UPRN
    *
    * @remarks
-   * Returns a single address by its Unique Property Reference Number (UPRN).
+   * Returns the single address held for a Unique Property Reference Number, with its postal form alongside when the UPRN has a Royal Mail delivery point. Add `include=geography` for the administrative and statistical areas the address falls in.
    */
   async lookupUprn(
     request: operations.LookupUprnRequest,
@@ -120,12 +126,10 @@ export class Address extends ClientSDK {
   }
 
   /**
-   * Resolve addresses to UPRNs with AI
+   * Resolve an address to UPRNs
    *
    * @remarks
-   * AI-powered address resolution that converts address strings to UPRNs (Unique Property Reference Numbers). Uses advanced LLM parsing to handle complex multi-unit addresses, ranges, incomplete addresses, and various formatting styles. Combines Elasticsearch search with intelligent postcode-based fallback for maximum accuracy.
-   *
-   * By default, only residential addresses are matched. Pass `classification: 'commercial'` to match commercial premises, or `classification: 'all'` to match all address types.
+   * Resolves a free-text address to one or more Unique Property Reference Numbers, each with a confidence score and a recommended action. It copes with multi-unit addresses, house-number ranges, incomplete addresses and inconsistent formatting, and falls back to postcode-level matching when the primary match is weak or absent. Only residential addresses are matched by default; pass `classification: 'commercial'` for commercial premises or `classification: 'all'` for every address type.
    */
   async resolveAddress(
     request?: shared.AddressResolveRequest | undefined,
@@ -139,10 +143,10 @@ export class Address extends ClientSDK {
   }
 
   /**
-   * Reverse geocode (coordinates to addresses)
+   * Find addresses near a coordinate
    *
    * @remarks
-   * Returns addresses near the specified coordinates, sorted by distance.
+   * Returns the addresses closest to a coordinate, nearest first, with the distance to each in metres. Both `lat` and `lng` are required.
    */
   async reverseGeocode(
     request: operations.ReverseGeocodeRequest,
@@ -159,7 +163,7 @@ export class Address extends ClientSDK {
    * Validate a UK postcode
    *
    * @remarks
-   * Validates whether a UK postcode exists and is active. Always returns 200 — the `valid` field indicates the result. Includes centroid coordinates and area codes when valid.
+   * Checks whether a UK postcode exists and is in use. The answer is always a 200 response: read the `valid` field for it. A valid postcode also returns its centroid and its statistical area codes.
    */
   async validatePostcode(
     request: operations.ValidatePostcodeRequest,

package/src/sdk/airquality.ts

@@ -10,14 +10,10 @@ import { unwrapAsync } from "./types/fp.js";
 
 export class AirQuality extends ClientSDK {
   /**
-   * Coordinate-exact air quality with property-decay overlay
+   * Get air quality at an exact coordinate
    *
    * @remarks
-   * Returns property-exact air-quality data for a single (lat, lon) coordinate. Reads the 1km cell substrate, then overlays exact distances to nearest road, nearest motorway, nearby installations, and regulatory zones. A versioned decay model (Karner-2010 exponential, AURN-calibrated) adjusts pollutant concentrations from the cell-level PCM background to the property point.
-   *
-   * Use `/point` for property-level decisions (valuation, mortgage, insurance). Use `/query` for bulk neighbourhood-scale lookups (bbox, postcode, outcode). Both return the same envelope shape; `/point` adds `coordinate`, `cellId`, and `decay` blocks.
-   *
-   * Premium attributes (`nearestRoad`, `nearestMotorway`, `installations`) and the explain-mode calculation trail (`decay.calculation`) require the `air-quality:premium` permission.
+   * Returns air quality at one latitude and longitude. It reads the 1 km cell the point falls in, then measures the exact distances to the nearest road, the nearest motorway, nearby regulated installations and the regulatory zones, and applies a versioned decay model so the pollutant concentrations reflect the point rather than the whole cell. Reach for this route for decisions about a single property, and for `/v1/air-quality/query` for neighbourhood-scale lookups. The response is the same shape as that route's, plus `coordinate`, `cellId` and `decay`. `nearestRoad`, `nearestMotorway`, `installations` and the calculation trail in `decay.calculation` are returned only on licences carrying the `airQualityPremium` permission.
    */
   async point(
     request?: shared.AirQualityPointRequest | undefined,
@@ -34,9 +30,7 @@ export class AirQuality extends ClientSDK {
    * Query air quality at one or more locations
    *
    * @remarks
-   * Retrieve air-quality data for one or more geographic areas. Supports nearest-cell lookup (single point with radius 0), radius search, postcode lookup, outcode lookup, bounding-box and polygon area filters. Multiple areas can be combined in a single request — up to 10 areas, results are OR-combined and deduplicated by `airQualityId`.
-   *
-   * Each response cell carries the air-quality summary (platform 0-100 score, band, dominant source), per-pollutant concentrations with framework-tagged compliance checks (UK AQS 2010, WHO AQG 2021), official indices (DAQI), regulator-defined zone memberships (AQMA, CAZ, ULEZ, LEZ, smoke control), and provenance. Premium attributes (`nearestRoad`, `nearestMotorway`, `installations`) require the `air-quality:premium` permission.
+   * Returns air quality for one or more areas, given as a point (with a radius, or radius 0 for the nearest 1 km cell only), a postcode, an outward code, a bounding box or a polygon. Up to ten areas can be combined in one request, and their results are deduplicated by `airQualityId`. Every cell carries the score and band, the pollutant concentrations with their compliance against each standard, the published indices, the regulator-defined zones containing it, and provenance. `nearestRoad`, `nearestMotorway` and `installations` are returned only on licences carrying the `airQualityPremium` permission. For a single property, use `/v1/air-quality/point` instead.
    */
   async query(
     request?: shared.AirQualityQueryRequest | undefined,