@vepler/sdk 2.167.0 → 3.0.0

package/src/address-search/types.ts

@@ -0,0 +1,147 @@
+/*
+ * Hand-written companion to the generated SDK (SV2-C1). This directory is NOT
+ * managed by the code generator (it is absent from .speakeasy/gen.lock), so
+ * regeneration leaves it untouched — the same preservation contract as
+ * src/hooks/registration.ts.
+ */
+
+/** A highlight range of the query within a suggestion's title. */
+export interface MatchedSubstring {
+  readonly offset: number;
+  readonly length: number;
+}
+
+/**
+ * One autocomplete suggestion under the discovery projection: display label,
+ * UPRN (when the row is an address) and match highlights. `raw` carries the
+ * untouched server row for consumers that render extra fields.
+ */
+export interface AddressSuggestion {
+  readonly id: string;
+  readonly title: string;
+  readonly uprn: string | null;
+  readonly source: string;
+  readonly matchedSubstrings: readonly MatchedSubstring[];
+  readonly raw: unknown;
+}
+
+/**
+ * Billing transparency metadata parsed from the `X-Credits-Charged`,
+ * `X-Credits-Balance` and `X-Already-Charged` response headers. Any header the
+ * API omits parses to `null`.
+ */
+export interface BillingMetadata {
+  readonly creditsCharged: number | null;
+  readonly creditsBalance: number | null;
+  readonly alreadyCharged: boolean | null;
+}
+
+/** The latest billing metadata held by the controller, stamped with `timers.now()`. */
+export interface BillingSnapshot extends BillingMetadata {
+  readonly receivedAt: number;
+}
+
+/** A suggest call the controller wants made. */
+export interface SuggestRequest {
+  readonly query: string;
+  /**
+   * Candidate-set session id to narrow within server-side. The controller
+   * always sends `null` (it narrows locally and both re-query cases need a
+   * fresh probe), but the transport supports it so thin integrations can
+   * drive the server-side narrowing path directly.
+   */
+  readonly searchId: string | null;
+  /** Aborted when a newer keystroke supersedes this request. */
+  readonly signal: AbortSignal;
+}
+
+/** A suggest response, already lifted out of the HTTP envelope. */
+export interface SuggestResult {
+  readonly suggestions: readonly AddressSuggestion[];
+  /** Server-issued candidate-set session id, or null when no set was formed. */
+  readonly searchId: string | null;
+  /** True when `suggestions` IS the complete match set for the query. */
+  readonly setComplete: boolean;
+  readonly billing: BillingMetadata | null;
+}
+
+/** Pluggable suggest call. `createSuggestTransport` builds the default. */
+export type SuggestTransport = (request: SuggestRequest) => Promise<SuggestResult>;
+
+/** A retrieve call for one selected suggestion. */
+export interface RetrieveRequest {
+  readonly suggestion: AddressSuggestion;
+  /** The session the selection belongs to, for transaction attribution. */
+  readonly searchId: string | null;
+}
+
+/** The retrieved record plus any billing metadata the transport surfaced. */
+export interface RetrieveResult<TRecord> {
+  readonly record: TRecord;
+  readonly billing?: BillingMetadata | null;
+}
+
+/**
+ * Pluggable retrieval call fired by `select()`. The retrieve endpoint is where
+ * the charge happens, so integrators can swap this for their own resolver;
+ * `createUprnRetrieveTransport` builds the default (UPRN lookup).
+ */
+export type RetrieveTransport<TRecord> = (request: RetrieveRequest) => Promise<RetrieveResult<TRecord>>;
+
+export type AddressSearchStatus = "idle" | "debouncing" | "loading" | "ready" | "error";
+
+/** The controller's observable state — one immutable snapshot per change. */
+export interface AddressSearchState {
+  readonly status: AddressSearchStatus;
+  readonly query: string;
+  readonly suggestions: readonly AddressSuggestion[];
+  /** The active candidate-set session id, passed to `select()` for attribution. */
+  readonly searchId: string | null;
+  /** True when `suggestions` is the complete match set for `query`. */
+  readonly setComplete: boolean;
+  readonly billing: BillingSnapshot | null;
+  readonly error: Error | null;
+}
+
+export type AddressSearchListener = (state: AddressSearchState) => void;
+
+/** Opaque token returned by an injected `setTimeout`. */
+export type TimerHandle = unknown;
+
+/** Injectable clock and timer functions, so tests never wait on real time. */
+export interface AddressSearchTimers {
+  now(): number;
+  setTimeout(callback: () => void, ms: number): TimerHandle;
+  clearTimeout(handle: TimerHandle): void;
+}
+
+export interface AddressSearchOptions<TRecord> {
+  readonly suggest: SuggestTransport;
+  readonly retrieve: RetrieveTransport<TRecord>;
+  /** Debounce for network fetches. Local narrowing is never debounced. Default 250. */
+  readonly debounceMs?: number;
+  /** Minimum normalised query length before any fetch. Default 3. */
+  readonly minQueryLength?: number;
+  /** Entries kept in the per-query result cache. Default 50. */
+  readonly cacheSize?: number;
+  readonly timers?: AddressSearchTimers;
+}
+
+export interface AddressSearchController<TRecord> {
+  /** Feed the current input value on every keystroke. */
+  input(text: string): void;
+  /**
+   * Retrieve the full record for a suggestion. Idempotent per suggestion and
+   * session: repeat calls return the same promise while one retrieve is
+   * in flight or has succeeded; a failed retrieve may be retried.
+   */
+  select(suggestion: AddressSuggestion): Promise<TRecord>;
+  /** Subscribe to state changes. Returns the unsubscribe function. */
+  subscribe(listener: AddressSearchListener): () => void;
+  /** The current state snapshot. */
+  getState(): AddressSearchState;
+  /** The latest billing metadata seen on any suggest or retrieve response. */
+  readonly billing: BillingSnapshot | null;
+  /** Cancel timers, abort in-flight work and drop all listeners. */
+  dispose(): void;
+}

package/src/address-search.ts

@@ -0,0 +1,40 @@
+/*
+ * Entry point for `@vepler/sdk/address-search` via the package's `./*`
+ * subpath export. Hand-written; not tracked by the code generator.
+ */
+
+export type {
+  AddressSearchController,
+  AddressSearchListener,
+  AddressSearchOptions,
+  AddressSearchState,
+  AddressSearchStatus,
+  AddressSearchTimers,
+  AddressSuggestion,
+  BillingMetadata,
+  BillingSnapshot,
+  FetchLike,
+  MatchedSubstring,
+  RetrieveRequest,
+  RetrieveResult,
+  RetrieveTransport,
+  SuggestHttpResponse,
+  SuggestRequest,
+  SuggestResult,
+  SuggestTransport,
+  SuggestTransportConfig,
+  TimerHandle,
+  UprnLookupFn,
+} from "./address-search/index.js";
+export {
+  AddressSearchError,
+  createAddressSearch,
+  createSuggestTransport,
+  createUprnRetrieveTransport,
+  extendsTriggerPrefix,
+  LruCache,
+  narrowSuggestions,
+  normaliseQuery,
+  parseBillingHeaders,
+  tokenise,
+} from "./address-search/index.js";

package/src/funcs/avmPredictPropertyValue.ts

@@ -42,6 +42,7 @@ export function avmPredictPropertyValue(
     | errors.PredictPropertyValueResponseBody
     | errors.PredictPropertyValueAVMResponseBody
     | errors.PredictPropertyValueAVMResponseResponseBody
+    | errors.PredictPropertyValueAVMResponse500ResponseBody
     | SDKBaseError
     | ResponseValidationError
     | ConnectionError
@@ -70,6 +71,7 @@ async function $do(
       | errors.PredictPropertyValueResponseBody
       | errors.PredictPropertyValueAVMResponseBody
       | errors.PredictPropertyValueAVMResponseResponseBody
+      | errors.PredictPropertyValueAVMResponse500ResponseBody
       | SDKBaseError
       | ResponseValidationError
       | ConnectionError
@@ -155,6 +157,7 @@ async function $do(
     | errors.PredictPropertyValueResponseBody
     | errors.PredictPropertyValueAVMResponseBody
     | errors.PredictPropertyValueAVMResponseResponseBody
+    | errors.PredictPropertyValueAVMResponse500ResponseBody
     | SDKBaseError
     | ResponseValidationError
     | ConnectionError
@@ -166,11 +169,15 @@ async function $do(
   >(
     M.json(200, shared.AVMPredictResponse$inboundSchema),
     M.jsonErr(400, errors.PredictPropertyValueResponseBody$inboundSchema),
-    M.jsonErr(422, errors.PredictPropertyValueAVMResponseBody$inboundSchema),
+    M.jsonErr(404, errors.PredictPropertyValueAVMResponseBody$inboundSchema),
     M.jsonErr(
-      500,
+      422,
       errors.PredictPropertyValueAVMResponseResponseBody$inboundSchema,
     ),
+    M.jsonErr(
+      500,
+      errors.PredictPropertyValueAVMResponse500ResponseBody$inboundSchema,
+    ),
     M.fail("4XX"),
     M.fail("5XX"),
   )(response, req, { extraFields: responseFields });

package/src/funcs/propertyGetProperties.ts

@@ -102,6 +102,7 @@ async function $do(
 
   const query = encodeFormQuery({
     "attributes": payload.attributes,
+    "countryCode": payload.countryCode,
     "limit": payload.limit,
     "offset": payload.offset,
   });

package/src/funcs/propertyGetPropertiesByLocation.ts

@@ -103,6 +103,7 @@ async function $do(
 
   const query = encodeFormQuery({
     "attributes": payload.attributes,
+    "countryCode": payload.countryCode,
     "limit": payload.limit,
     "offset": payload.offset,
   });

package/src/funcs/propertyGetPropertiesBySource.ts

@@ -103,6 +103,7 @@ async function $do(
 
   const query = encodeFormQuery({
     "attributes": payload.attributes,
+    "countryCode": payload.countryCode,
     "limit": payload.limit,
     "offset": payload.offset,
   });

package/src/funcs/searchSearchRetrieve.ts

@@ -0,0 +1,192 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { SDKCore } from "../core.js";
+import { encodeFormQuery } from "../lib/encodings.js";
+import { matchStatusCode } from "../lib/http.js";
+import * as M from "../lib/matchers.js";
+import { compactMap } from "../lib/primitives.js";
+import { safeParse } from "../lib/schemas.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
+import { pathToFunc } from "../lib/url.js";
+import {
+  ConnectionError,
+  InvalidRequestError,
+  RequestAbortedError,
+  RequestTimeoutError,
+  UnexpectedClientError,
+} from "../sdk/models/errors/httpclienterrors.js";
+import * as errors from "../sdk/models/errors/index.js";
+import { ResponseValidationError } from "../sdk/models/errors/responsevalidationerror.js";
+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
+ *
+ * @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.
+ */
+export function searchSearchRetrieve(
+  client: SDKCore,
+  request: operations.SearchRetrieveRequest,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    shared.SearchRetrieveResponse,
+    | errors.SearchRetrieveResponseBody
+    | errors.SearchRetrieveSearchResponseBody
+    | errors.SearchRetrieveSearchResponseResponseBody
+    | SDKBaseError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >
+> {
+  return new APIPromise($do(
+    client,
+    request,
+    options,
+  ));
+}
+
+async function $do(
+  client: SDKCore,
+  request: operations.SearchRetrieveRequest,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      shared.SearchRetrieveResponse,
+      | errors.SearchRetrieveResponseBody
+      | errors.SearchRetrieveSearchResponseBody
+      | errors.SearchRetrieveSearchResponseResponseBody
+      | SDKBaseError
+      | ResponseValidationError
+      | ConnectionError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | InvalidRequestError
+      | UnexpectedClientError
+      | SDKValidationError
+    >,
+    APICall,
+  ]
+> {
+  const parsed = safeParse(
+    request,
+    (value) => operations.SearchRetrieveRequest$outboundSchema.parse(value),
+    "Input validation failed",
+  );
+  if (!parsed.ok) {
+    return [parsed, { status: "invalid" }];
+  }
+  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 headers = new Headers(compactMap({
+    Accept: "application/json",
+  }));
+
+  const secConfig = await extractSecurity(client._options.apiKeyAuth);
+  const securityInput = secConfig == null ? {} : { apiKeyAuth: secConfig };
+  const requestSecurity = resolveGlobalSecurity(securityInput);
+
+  const context = {
+    options: client._options,
+    baseURL: options?.serverURL ?? client._baseURL ?? "",
+    operationID: "searchRetrieve",
+    oAuth2Scopes: null,
+
+    resolvedSecurity: requestSecurity,
+
+    securitySource: client._options.apiKeyAuth,
+    retryConfig: options?.retries
+      || client._options.retryConfig
+      || { strategy: "none" },
+    retryCodes: options?.retryCodes || ["429", "500", "502", "503", "504"],
+  };
+
+  const requestRes = client._createRequest(context, {
+    security: requestSecurity,
+    method: "GET",
+    baseURL: options?.serverURL,
+    path: path,
+    headers: headers,
+    query: query,
+    body: body,
+    userAgent: client._options.userAgent,
+    timeoutMs: options?.timeoutMs || client._options.timeoutMs || -1,
+  }, options);
+  if (!requestRes.ok) {
+    return [requestRes, { status: "invalid" }];
+  }
+  const req = requestRes.value;
+
+  const doResult = await client._do(req, {
+    context,
+    isErrorStatusCode: (statusCode: number) =>
+      matchStatusCode({ status: statusCode } as Response, ["4XX", "5XX"]),
+    retryConfig: context.retryConfig,
+    retryCodes: context.retryCodes,
+  });
+  if (!doResult.ok) {
+    return [doResult, { status: "request-error", request: req }];
+  }
+  const response = doResult.value;
+
+  const responseFields = {
+    HttpMeta: { Response: response, Request: req },
+  };
+
+  const [result] = await M.match<
+    shared.SearchRetrieveResponse,
+    | errors.SearchRetrieveResponseBody
+    | errors.SearchRetrieveSearchResponseBody
+    | errors.SearchRetrieveSearchResponseResponseBody
+    | SDKBaseError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >(
+    M.json(200, shared.SearchRetrieveResponse$inboundSchema),
+    M.jsonErr(400, errors.SearchRetrieveResponseBody$inboundSchema),
+    M.jsonErr(404, errors.SearchRetrieveSearchResponseBody$inboundSchema),
+    M.jsonErr(
+      500,
+      errors.SearchRetrieveSearchResponseResponseBody$inboundSchema,
+    ),
+    M.fail("4XX"),
+    M.fail("5XX"),
+  )(response, req, { extraFields: responseFields });
+  if (!result.ok) {
+    return [result, { status: "complete", request: req, response }];
+  }
+
+  return [result, { status: "complete", request: req, response }];
+}

package/src/funcs/searchSearchSuggest.ts

@@ -37,7 +37,9 @@ import { Result } from "../sdk/types/fp.js";
  * - `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.
  *
- * When a centre point is supplied, address results include a `distance` (metres from the point). Geographic ranking applies to the address source, so pair it with `source=address` for the most predictable proximity results.
+ * 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.
  */
 export function searchSearchSuggest(
   client: SDKCore,
@@ -104,12 +106,14 @@ async function $do(
     "addressable_only": payload.addressable_only,
     "classification": payload.classification,
     "geo_mode": payload.geo_mode,
+    "granularity": payload.granularity,
     "lat": payload.lat,
     "limit": payload.limit,
     "lng": payload.lng,
     "offset": payload.offset,
     "q": payload.q,
     "radius_meters": payload.radius_meters,
+    "search_id": payload.search_id,
     "source": payload.source,
   });
 

package/src/lib/config.ts

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

package/src/sdk/models/errors/index.ts

@@ -140,6 +140,7 @@ export * from "./searchconnectionqueue.js";
 export * from "./searchecr.js";
 export * from "./searchplanningapplications.js";
 export * from "./searchproperties.js";
+export * from "./searchretrieve.js";
 export * from "./searchsites.js";
 export * from "./searchstreets.js";
 export * from "./searchsubstations.js";

package/src/sdk/models/errors/predictpropertyvalue.ts

@@ -11,6 +11,81 @@ import { Result as SafeParseResult } from "../../types/fp.js";
 import { SDKBaseError } from "./sdkbaseerror.js";
 import { SDKValidationError } from "./sdkvalidationerror.js";
 
+/**
+ * Error type category
+ */
+export const PredictPropertyValueAVMResponse500Type = {
+  ApiError: "api_error",
+  InvalidRequestError: "invalid_request_error",
+  AuthenticationError: "authentication_error",
+  RateLimitError: "rate_limit_error",
+} as const;
+/**
+ * Error type category
+ */
+export type PredictPropertyValueAVMResponse500Type = OpenEnum<
+  typeof PredictPropertyValueAVMResponse500Type
+>;
+
+export type PredictPropertyValueAVMResponse500Error = {
+  /**
+   * Machine-readable error code
+   */
+  code?: string | undefined;
+  /**
+   * URL to relevant documentation
+   */
+  docUrl?: string | undefined;
+  /**
+   * Human-readable error message
+   */
+  message: string;
+  /**
+   * Parameter that caused the error
+   */
+  param?: string | undefined;
+  /**
+   * Suggested corrections (e.g. postcode typo suggestions)
+   */
+  suggestions?: Array<string> | undefined;
+  /**
+   * Error type category
+   */
+  type: PredictPropertyValueAVMResponse500Type;
+};
+
+/**
+ * Error response
+ */
+export type PredictPropertyValueAVMResponse500ResponseBodyData = {
+  error: PredictPropertyValueAVMResponse500Error;
+};
+
+/**
+ * Error response
+ */
+export class PredictPropertyValueAVMResponse500ResponseBody
+  extends SDKBaseError
+{
+  error: PredictPropertyValueAVMResponse500Error;
+
+  /** The original data that was passed to this error instance. */
+  data$: PredictPropertyValueAVMResponse500ResponseBodyData;
+
+  constructor(
+    err: PredictPropertyValueAVMResponse500ResponseBodyData,
+    httpMeta: { response: Response; request: Request; body: string },
+  ) {
+    const message = err.error?.message
+      || `API error occurred: ${JSON.stringify(err)}`;
+    super(message, httpMeta);
+    this.data$ = err;
+    this.error = err.error;
+
+    this.name = "PredictPropertyValueAVMResponse500ResponseBody";
+  }
+}
+
 /**
  * Error type category
  */
@@ -230,6 +305,67 @@ export class PredictPropertyValueResponseBody extends SDKBaseError {
   }
 }
 
+/** @internal */
+export const PredictPropertyValueAVMResponse500Type$inboundSchema: z.ZodType<
+  PredictPropertyValueAVMResponse500Type,
+  z.ZodTypeDef,
+  unknown
+> = openEnums.inboundSchema(PredictPropertyValueAVMResponse500Type);
+
+/** @internal */
+export const PredictPropertyValueAVMResponse500Error$inboundSchema: z.ZodType<
+  PredictPropertyValueAVMResponse500Error,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  code: z.string().optional(),
+  doc_url: z.string().optional(),
+  message: z.string(),
+  param: z.string().optional(),
+  suggestions: z.array(z.string()).optional(),
+  type: PredictPropertyValueAVMResponse500Type$inboundSchema,
+}).transform((v) => {
+  return remap$(v, {
+    "doc_url": "docUrl",
+  });
+});
+
+export function predictPropertyValueAVMResponse500ErrorFromJSON(
+  jsonString: string,
+): SafeParseResult<
+  PredictPropertyValueAVMResponse500Error,
+  SDKValidationError
+> {
+  return safeParse(
+    jsonString,
+    (x) =>
+      PredictPropertyValueAVMResponse500Error$inboundSchema.parse(
+        JSON.parse(x),
+      ),
+    `Failed to parse 'PredictPropertyValueAVMResponse500Error' from JSON`,
+  );
+}
+
+/** @internal */
+export const PredictPropertyValueAVMResponse500ResponseBody$inboundSchema:
+  z.ZodType<
+    PredictPropertyValueAVMResponse500ResponseBody,
+    z.ZodTypeDef,
+    unknown
+  > = z.object({
+    error: z.lazy(() => PredictPropertyValueAVMResponse500Error$inboundSchema),
+    request$: z.instanceof(Request),
+    response$: z.instanceof(Response),
+    body$: z.string(),
+  })
+    .transform((v) => {
+      return new PredictPropertyValueAVMResponse500ResponseBody(v, {
+        request: v.request$,
+        response: v.response$,
+        body: v.body$,
+      });
+    });
+
 /** @internal */
 export const PredictPropertyValueAVMResponseType$inboundSchema: z.ZodType<
   PredictPropertyValueAVMResponseType,