@vepler/sdk 2.164.0 → 3.0.0

package/src/address-search/controller.ts

@@ -0,0 +1,219 @@
+import { LruCache } from "./lru-cache.js";
+import { extendsTriggerPrefix, narrowSuggestions, normaliseQuery } from "./narrow.js";
+import type {
+  AddressSearchController,
+  AddressSearchListener,
+  AddressSearchOptions,
+  AddressSearchState,
+  AddressSearchTimers,
+  AddressSuggestion,
+  BillingMetadata,
+  SuggestResult,
+  TimerHandle,
+} from "./types.js";
+
+const DEFAULT_DEBOUNCE_MS = 250;
+const DEFAULT_MIN_QUERY_LENGTH = 3;
+const DEFAULT_CACHE_SIZE = 50;
+
+const defaultTimers: AddressSearchTimers = {
+  now: (): number => Date.now(),
+  setTimeout: (callback: () => void, ms: number): TimerHandle => setTimeout(callback, ms),
+  clearTimeout: (handle: TimerHandle): void => clearTimeout(handle as ReturnType<typeof setTimeout>),
+};
+
+const INITIAL_STATE: AddressSearchState = {
+  status: "idle",
+  query: "",
+  suggestions: [],
+  searchId: null,
+  setComplete: false,
+  billing: null,
+  error: null,
+};
+
+/** A complete candidate set held client-side, keyed by the prefix that fetched it. */
+interface HeldCandidateSet {
+  readonly searchId: string;
+  readonly triggerPrefix: string;
+  readonly rows: readonly AddressSuggestion[];
+}
+
+/**
+ * Headless address autocomplete controller (SV2-C1). Framework-agnostic: no
+ * DOM access, no framework dependencies — feed keystrokes to `input()`,
+ * render from `subscribe()`/`getState()`, resolve a pick with `select()`.
+ *
+ * The point of the controller is the candidate-set protocol: once a response
+ * arrives with `set_complete: true`, further keystrokes that extend the
+ * fetched prefix narrow the held set locally — no request, no new royalty
+ * transaction. The server is consulted again only when the local narrow
+ * empties (set exhaustion) or the input stops extending the trigger prefix.
+ */
+export function createAddressSearch<TRecord = unknown>(
+  options: AddressSearchOptions<TRecord>,
+): AddressSearchController<TRecord> {
+  const debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+  const minQueryLength = options.minQueryLength ?? DEFAULT_MIN_QUERY_LENGTH;
+  const timers = options.timers ?? defaultTimers;
+  const cache = new LruCache<string, SuggestResult>(options.cacheSize ?? DEFAULT_CACHE_SIZE);
+
+  let state = INITIAL_STATE;
+  const listeners = new Set<AddressSearchListener>();
+  let heldSet: HeldCandidateSet | null = null;
+  let pendingTimer: TimerHandle | null = null;
+  let inFlight: AbortController | null = null;
+  let requestSeq = 0;
+  const selections = new Map<string, Promise<TRecord>>();
+  let disposed = false;
+
+  function setState(patch: Partial<AddressSearchState>): void {
+    state = { ...state, ...patch };
+    for (const listener of listeners) listener(state);
+  }
+
+  function stampBilling(billing: BillingMetadata | null): Partial<AddressSearchState> {
+    return billing === null ? {} : { billing: { ...billing, receivedAt: timers.now() } };
+  }
+
+  function cancelPending(): void {
+    if (pendingTimer !== null) {
+      timers.clearTimeout(pendingTimer);
+      pendingTimer = null;
+    }
+    if (inFlight !== null) {
+      inFlight.abort();
+      inFlight = null;
+    }
+  }
+
+  /** Apply a server (or cached) result; adopt the set when it is complete. */
+  function applyResult(query: string, result: SuggestResult): void {
+    if (result.setComplete && result.searchId !== null) {
+      heldSet = { searchId: result.searchId, triggerPrefix: normaliseQuery(query), rows: result.suggestions };
+    }
+    setState({
+      status: "ready",
+      query,
+      suggestions: result.suggestions,
+      searchId: result.searchId,
+      setComplete: result.setComplete,
+      error: null,
+      ...stampBilling(result.billing),
+    });
+  }
+
+  async function fetchSuggestions(query: string, normalised: string): Promise<void> {
+    inFlight?.abort();
+    const abort = new AbortController();
+    inFlight = abort;
+    const seq = ++requestSeq;
+    setState({ status: "loading", query });
+    try {
+      // Always a fresh query, never a search_id: local narrowing mirrors the
+      // server's, so a server-side narrow of the held set could only return
+      // what we already computed (or less) — the only useful re-query is a
+      // fresh probe, which is the counted path.
+      const result = await options.suggest({ query, searchId: null, signal: abort.signal });
+      if (seq !== requestSeq || abort.signal.aborted) return; // superseded
+      inFlight = null;
+      cache.set(normalised, result);
+      applyResult(query, result);
+    } catch (error) {
+      if (seq !== requestSeq || abort.signal.aborted) return; // superseded or cancelled
+      inFlight = null;
+      setState({ status: "error", query, error: error instanceof Error ? error : new Error(String(error)) });
+    }
+  }
+
+  function input(text: string): void {
+    if (disposed) return;
+    const normalised = normaliseQuery(text);
+
+    // Below the minimum: clear suggestions, never fetch. The held set is kept —
+    // retyping into its prefix resumes local narrowing at zero cost.
+    if (normalised.length < minQueryLength) {
+      cancelPending();
+      setState({ status: "idle", query: text, suggestions: [], searchId: null, setComplete: false, error: null });
+      return;
+    }
+
+    // A query answered before costs nothing to answer again.
+    const cached = cache.get(normalised);
+    if (cached !== undefined) {
+      cancelPending();
+      applyResult(text, cached);
+      return;
+    }
+
+    // Local narrowing: the input extends the held set's trigger prefix, so the
+    // true match set is a subset of what we hold. Served instantly (no
+    // debounce — it is free) and no request leaves the client.
+    if (heldSet !== null && extendsTriggerPrefix(text, heldSet.triggerPrefix)) {
+      const narrowed = narrowSuggestions(heldSet.rows, text);
+      if (narrowed.length > 0) {
+        cancelPending();
+        setState({
+          status: "ready",
+          query: text,
+          suggestions: narrowed,
+          searchId: heldSet.searchId,
+          setComplete: true,
+          error: null,
+        });
+        return;
+      }
+      // Set exhaustion: fall through to a fresh counted fetch (no search_id).
+    }
+
+    cancelPending();
+    setState({ status: "debouncing", query: text });
+    pendingTimer = timers.setTimeout(() => {
+      pendingTimer = null;
+      void fetchSuggestions(text, normalised);
+    }, debounceMs);
+  }
+
+  function select(suggestion: AddressSuggestion): Promise<TRecord> {
+    const searchId = state.searchId;
+    const key = `${searchId ?? ""}::${suggestion.uprn ?? suggestion.id}`;
+    const existing = selections.get(key);
+    if (existing !== undefined) return existing;
+
+    const promise = (async (): Promise<TRecord> => {
+      const result = await options.retrieve({ suggestion, searchId });
+      if (result.billing != null) setState(stampBilling(result.billing));
+      return result.record;
+    })();
+    selections.set(key, promise);
+    // A failed retrieve must not poison the guard — the user may retry.
+    promise.catch((): void => {
+      selections.delete(key);
+    });
+    return promise;
+  }
+
+  function subscribe(listener: AddressSearchListener): () => void {
+    listeners.add(listener);
+    return (): void => {
+      listeners.delete(listener);
+    };
+  }
+
+  function dispose(): void {
+    disposed = true;
+    cancelPending();
+    listeners.clear();
+  }
+
+  return {
+    input,
+    select,
+    subscribe,
+    getState: (): AddressSearchState => state,
+    get billing() {
+      return state.billing;
+    },
+    dispose,
+  };
+}

package/src/address-search/default-transports.ts

@@ -0,0 +1,199 @@
+import type { SDKCore } from "../core.js";
+import { addressLookupUprn } from "../funcs/addressLookupUprn.js";
+import type { UprnLookupResponse } from "../sdk/models/shared/uprnlookupresponse.js";
+import type { Result } from "../sdk/types/fp.js";
+import { AddressSearchError } from "./errors.js";
+import type {
+  AddressSuggestion,
+  BillingMetadata,
+  MatchedSubstring,
+  RetrieveResult,
+  RetrieveTransport,
+  SuggestResult,
+  SuggestTransport,
+} from "./types.js";
+
+const DEFAULT_BASE_URL = "https://api.vepler.com";
+
+/**
+ * Request the full page cap so any candidate set the server forms (at most
+ * 100 rows) arrives complete in one response — `set_complete` is only true
+ * when nothing was paginated away.
+ */
+const CANDIDATE_PAGE_LIMIT = 100;
+
+/** The subset of a fetch Response the suggest transport reads. */
+export interface SuggestHttpResponse {
+  readonly ok: boolean;
+  readonly status: number;
+  readonly headers: { get(name: string): string | null };
+  json(): Promise<unknown>;
+}
+
+/** Injectable fetch — the global `fetch` is assignable. */
+export type FetchLike = (
+  url: string,
+  init: { readonly headers: Record<string, string>; readonly signal: AbortSignal },
+) => Promise<SuggestHttpResponse>;
+
+export interface SuggestTransportConfig {
+  /** API origin. Default `https://api.vepler.com`. */
+  readonly baseUrl?: string;
+  /** API key sent as `x-api-key`. Omit when auth is ambient (proxy, cookie). */
+  readonly apiKey?: string;
+  readonly fetch?: FetchLike;
+  /** Page size requested. Default 100 (the candidate-set cap). */
+  readonly limit?: number;
+}
+
+/** Parse the billing transparency headers; null when none are present. */
+export function parseBillingHeaders(headers: { get(name: string): string | null }): BillingMetadata | null {
+  const charged = headers.get("X-Credits-Charged");
+  const balance = headers.get("X-Credits-Balance");
+  const already = headers.get("X-Already-Charged");
+  if (charged === null && balance === null && already === null) return null;
+  return {
+    creditsCharged: parseNumeric(charged),
+    creditsBalance: parseNumeric(balance),
+    alreadyCharged: already === null ? null : already === "true" || already === "1",
+  };
+}
+
+function parseNumeric(value: string | null): number | null {
+  if (value === null) return null;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+/** Loosely-typed views over the wire shapes — every field is verified before use. */
+interface RawMatchedSubstring {
+  readonly offset?: unknown;
+  readonly length?: unknown;
+}
+
+interface RawSuggestRow {
+  readonly id?: unknown;
+  readonly title?: unknown;
+  readonly main_text?: unknown;
+  readonly uprn?: unknown;
+  readonly source?: unknown;
+  readonly matched_substrings?: unknown;
+}
+
+interface RawSuggestEnvelope {
+  readonly data?: unknown;
+  readonly result?: unknown;
+  readonly search_id?: unknown;
+  readonly set_complete?: unknown;
+}
+
+function parseMatchedSubstrings(value: unknown): MatchedSubstring[] {
+  if (!Array.isArray(value)) return [];
+  const ranges: MatchedSubstring[] = [];
+  for (const entry of value) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const { offset, length } = entry as RawMatchedSubstring;
+    if (typeof offset === "number" && typeof length === "number") ranges.push({ offset, length });
+  }
+  return ranges;
+}
+
+function toSuggestion(row: unknown): AddressSuggestion | null {
+  if (typeof row !== "object" || row === null) return null;
+  const record = row as RawSuggestRow;
+  const title =
+    typeof record.title === "string" ? record.title : typeof record.main_text === "string" ? record.main_text : null;
+  if (title === null) return null;
+  return {
+    id: typeof record.id === "string" ? record.id : title,
+    title,
+    uprn: typeof record.uprn === "string" ? record.uprn : null,
+    source: typeof record.source === "string" ? record.source : "address",
+    matchedSubstrings: parseMatchedSubstrings(record.matched_substrings),
+    raw: row,
+  };
+}
+
+function parseSuggestBody(body: unknown): { rows: AddressSuggestion[]; searchId: string | null; setComplete: boolean } {
+  const envelope: RawSuggestEnvelope = typeof body === "object" && body !== null ? (body as RawSuggestEnvelope) : {};
+  const rawRows: unknown[] = Array.isArray(envelope.data)
+    ? envelope.data
+    : Array.isArray(envelope.result)
+      ? envelope.result
+      : [];
+  const rows: AddressSuggestion[] = [];
+  for (const raw of rawRows) {
+    const suggestion = toSuggestion(raw);
+    if (suggestion !== null) rows.push(suggestion);
+  }
+  return {
+    rows,
+    searchId: typeof envelope.search_id === "string" ? envelope.search_id : null,
+    setComplete: envelope.set_complete === true,
+  };
+}
+
+/**
+ * Default suggest transport: `GET /v1/search/suggest` with the v2 response
+ * envelope, candidate-set fields (`search_id`, `set_complete`) and billing
+ * headers lifted into a `SuggestResult`.
+ */
+export function createSuggestTransport(config: SuggestTransportConfig = {}): SuggestTransport {
+  const baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const fetchFn: FetchLike = config.fetch ?? globalThis.fetch;
+  const limit = config.limit ?? CANDIDATE_PAGE_LIMIT;
+
+  return async ({ query, searchId, signal }): Promise<SuggestResult> => {
+    const params = new URLSearchParams({ q: query, limit: String(limit) });
+    if (searchId !== null) params.set("search_id", searchId);
+    const headers: Record<string, string> = { Accept: "application/json", "X-API-Version": "2" };
+    if (config.apiKey !== undefined) headers["x-api-key"] = config.apiKey;
+
+    const response = await fetchFn(`${baseUrl}/v1/search/suggest?${params.toString()}`, { headers, signal });
+    if (!response.ok) {
+      throw new AddressSearchError(`Suggest request failed with status ${response.status}`);
+    }
+    const { rows, searchId: responseSearchId, setComplete } = parseSuggestBody(await response.json());
+    return {
+      suggestions: rows,
+      searchId: responseSearchId,
+      setComplete,
+      billing: parseBillingHeaders(response.headers),
+    };
+  };
+}
+
+/** The generated UPRN lookup, injectable for tests. */
+export type UprnLookupFn = (
+  client: SDKCore,
+  request: { uprn: string },
+) => PromiseLike<Result<UprnLookupResponse, unknown>>;
+
+/**
+ * Default retrieve transport: resolves a selected suggestion to the full
+ * address record through the SDK's UPRN lookup (`GET /v1/address/uprn/{uprn}`).
+ * Swap it out once the dedicated candidate-set retrieve endpoint ships — the
+ * `searchId` on the request is there for exactly that transport; this one
+ * cannot attribute it, so the lookup opens its own transaction row server-side.
+ */
+export function createUprnRetrieveTransport(
+  client: SDKCore,
+  deps: { readonly lookup?: UprnLookupFn } = {},
+): RetrieveTransport<UprnLookupResponse> {
+  const lookup = deps.lookup ?? addressLookupUprn;
+  return async ({ suggestion }): Promise<RetrieveResult<UprnLookupResponse>> => {
+    if (suggestion.uprn === null) {
+      throw new AddressSearchError(
+        `Cannot retrieve suggestion "${suggestion.id}": it has no UPRN. ` +
+          "Only address rows are retrievable through the default UPRN transport.",
+      );
+    }
+    const result = await lookup(client, { uprn: suggestion.uprn });
+    if (!result.ok) {
+      throw result.error instanceof Error
+        ? result.error
+        : new AddressSearchError(`UPRN lookup failed for "${suggestion.uprn}"`);
+    }
+    return { record: result.value };
+  };
+}

package/src/address-search/errors.ts

@@ -0,0 +1,7 @@
+/** Error raised by the address-search controller and its default transports. */
+export class AddressSearchError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "AddressSearchError";
+  }
+}

package/src/address-search/index.ts

@@ -0,0 +1,54 @@
+/*
+ * Headless address autocomplete (SV2-C1). Hand-written, generator-safe: this
+ * directory is not tracked in .speakeasy/gen.lock, so `speakeasy run` never
+ * touches it (same contract as src/hooks/registration.ts).
+ *
+ * Typical wiring:
+ *
+ * ```ts
+ * import { SDKCore } from "@vepler/sdk/core.js";
+ * import {
+ *   createAddressSearch,
+ *   createSuggestTransport,
+ *   createUprnRetrieveTransport,
+ * } from "@vepler/sdk/address-search";
+ *
+ * const core = new SDKCore({ apiKeyAuth: "..." });
+ * const search = createAddressSearch({
+ *   suggest: createSuggestTransport({ apiKey: "..." }),
+ *   retrieve: createUprnRetrieveTransport(core),
+ * });
+ * const unsubscribe = search.subscribe((state) => render(state));
+ * input.addEventListener("input", () => search.input(input.value));
+ * ```
+ */
+
+export { createAddressSearch } from "./controller.js";
+export type { FetchLike, SuggestHttpResponse, SuggestTransportConfig, UprnLookupFn } from "./default-transports.js";
+export {
+  createSuggestTransport,
+  createUprnRetrieveTransport,
+  parseBillingHeaders,
+} from "./default-transports.js";
+export { AddressSearchError } from "./errors.js";
+export { LruCache } from "./lru-cache.js";
+export { extendsTriggerPrefix, narrowSuggestions, normaliseQuery, tokenise } from "./narrow.js";
+export type {
+  AddressSearchController,
+  AddressSearchListener,
+  AddressSearchOptions,
+  AddressSearchState,
+  AddressSearchStatus,
+  AddressSearchTimers,
+  AddressSuggestion,
+  BillingMetadata,
+  BillingSnapshot,
+  MatchedSubstring,
+  RetrieveRequest,
+  RetrieveResult,
+  RetrieveTransport,
+  SuggestRequest,
+  SuggestResult,
+  SuggestTransport,
+  TimerHandle,
+} from "./types.js";

package/src/address-search/lru-cache.ts

@@ -0,0 +1,34 @@
+/**
+ * Minimal least-recently-used cache over an insertion-ordered Map: reads
+ * refresh recency by re-inserting; writes beyond capacity evict the oldest
+ * entry (the Map's first key).
+ */
+export class LruCache<K, V> {
+  readonly #capacity: number;
+  readonly #entries = new Map<K, V>();
+
+  constructor(capacity: number) {
+    this.#capacity = Math.max(1, Math.floor(capacity));
+  }
+
+  get(key: K): V | undefined {
+    const value = this.#entries.get(key);
+    if (value === undefined) return undefined;
+    this.#entries.delete(key);
+    this.#entries.set(key, value);
+    return value;
+  }
+
+  set(key: K, value: V): void {
+    this.#entries.delete(key);
+    this.#entries.set(key, value);
+    if (this.#entries.size > this.#capacity) {
+      const oldest = this.#entries.keys().next();
+      if (!oldest.done) this.#entries.delete(oldest.value);
+    }
+  }
+
+  get size(): number {
+    return this.#entries.size;
+  }
+}

package/src/address-search/narrow.ts

@@ -0,0 +1,45 @@
+/*
+ * Client-side narrowing for candidate sets. Deliberately mirrors the server's
+ * narrowing semantics — same tokenisation, same every-token-prefix rule — so
+ * client and server always agree on which rows survive a keystroke. Any
+ * divergence here would make the client claim a set is exhausted (an extra
+ * counted fetch) or show rows the server would not.
+ */
+
+/** Lower-case alphanumeric tokens; everything else is a separator. */
+export function tokenise(text: string): string[] {
+  return text
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean);
+}
+
+/**
+ * A row survives when EVERY token of the query is a case-insensitive prefix
+ * of at least one token of the row's title. Order-preserving. An empty query
+ * narrows nothing (the whole set survives).
+ */
+export function narrowSuggestions<T extends { readonly title: string }>(rows: readonly T[], query: string): T[] {
+  const queryTokens = tokenise(query);
+  if (queryTokens.length === 0) return [...rows];
+  return rows.filter((row) => {
+    const titleTokens = tokenise(row.title);
+    return queryTokens.every((queryToken) => titleTokens.some((titleToken) => titleToken.startsWith(queryToken)));
+  });
+}
+
+/** Lower-case, collapse whitespace runs and trim — the cache and prefix key form. */
+export function normaliseQuery(text: string): string {
+  return text.toLowerCase().replace(/\s+/g, " ").trim();
+}
+
+/**
+ * True when `query` still extends the prefix a candidate set was fetched for,
+ * meaning the set is guaranteed to contain every match for `query` and local
+ * narrowing stays sound. Backspacing past the trigger (or editing inside it)
+ * fails this check, which forces a fresh counted fetch — the set no longer
+ * bounds the true match set.
+ */
+export function extendsTriggerPrefix(query: string, triggerPrefix: string): boolean {
+  return normaliseQuery(query).startsWith(normaliseQuery(triggerPrefix));
+}