@vepler/sdk 2.167.0 → 3.0.0

package/dist/esm/address-search/controller.js

@@ -0,0 +1,187 @@
+import { LruCache } from "./lru-cache.js";
+import { extendsTriggerPrefix, narrowSuggestions, normaliseQuery } from "./narrow.js";
+const DEFAULT_DEBOUNCE_MS = 250;
+const DEFAULT_MIN_QUERY_LENGTH = 3;
+const DEFAULT_CACHE_SIZE = 50;
+const defaultTimers = {
+    now: () => Date.now(),
+    setTimeout: (callback, ms) => setTimeout(callback, ms),
+    clearTimeout: (handle) => clearTimeout(handle),
+};
+const INITIAL_STATE = {
+    status: "idle",
+    query: "",
+    suggestions: [],
+    searchId: null,
+    setComplete: false,
+    billing: null,
+    error: null,
+};
+/**
+ * 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(options) {
+    const debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+    const minQueryLength = options.minQueryLength ?? DEFAULT_MIN_QUERY_LENGTH;
+    const timers = options.timers ?? defaultTimers;
+    const cache = new LruCache(options.cacheSize ?? DEFAULT_CACHE_SIZE);
+    let state = INITIAL_STATE;
+    const listeners = new Set();
+    let heldSet = null;
+    let pendingTimer = null;
+    let inFlight = null;
+    let requestSeq = 0;
+    const selections = new Map();
+    let disposed = false;
+    function setState(patch) {
+        state = { ...state, ...patch };
+        for (const listener of listeners)
+            listener(state);
+    }
+    function stampBilling(billing) {
+        return billing === null ? {} : { billing: { ...billing, receivedAt: timers.now() } };
+    }
+    function cancelPending() {
+        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, result) {
+        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, normalised) {
+        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) {
+        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) {
+        const searchId = state.searchId;
+        const key = `${searchId ?? ""}::${suggestion.uprn ?? suggestion.id}`;
+        const existing = selections.get(key);
+        if (existing !== undefined)
+            return existing;
+        const promise = (async () => {
+            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(() => {
+            selections.delete(key);
+        });
+        return promise;
+    }
+    function subscribe(listener) {
+        listeners.add(listener);
+        return () => {
+            listeners.delete(listener);
+        };
+    }
+    function dispose() {
+        disposed = true;
+        cancelPending();
+        listeners.clear();
+    }
+    return {
+        input,
+        select,
+        subscribe,
+        getState: () => state,
+        get billing() {
+            return state.billing;
+        },
+        dispose,
+    };
+}
+//# sourceMappingURL=controller.js.map

package/dist/esm/address-search/controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.js","sourceRoot":"","sources":["../../../src/address-search/controller.ts"],"names":[],"mappings":"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"}

package/dist/esm/address-search/default-transports.d.ts

@@ -0,0 +1,52 @@
+import type { SDKCore } from "../core.js";
+import type { UprnLookupResponse } from "../sdk/models/shared/uprnlookupresponse.js";
+import type { Result } from "../sdk/types/fp.js";
+import type { BillingMetadata, RetrieveTransport, SuggestTransport } from "./types.js";
+/** 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 declare function parseBillingHeaders(headers: {
+    get(name: string): string | null;
+}): BillingMetadata | null;
+/**
+ * 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 declare function createSuggestTransport(config?: SuggestTransportConfig): SuggestTransport;
+/** 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 declare function createUprnRetrieveTransport(client: SDKCore, deps?: {
+    readonly lookup?: UprnLookupFn;
+}): RetrieveTransport<UprnLookupResponse>;
+//# sourceMappingURL=default-transports.d.ts.map

package/dist/esm/address-search/default-transports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-transports.d.ts","sourceRoot":"","sources":["../../../src/address-search/default-transports.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4CAA4C,CAAC;AACrF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,KAAK,EAEV,eAAe,EAGf,iBAAiB,EAEjB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAWpB,kEAAkE;AAClE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE;QAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IACvD,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1B;AAED,2DAA2D;AAC3D,MAAM,MAAM,SAAS,GAAG,CACtB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAAE,KAC7E,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAElC,MAAM,WAAW,sBAAsB;IACrC,oDAAoD;IACpD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;IAC3B,gEAAgE;IAChE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAAC,OAAO,EAAE;IAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,eAAe,GAAG,IAAI,CAUzG;AA4ED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,GAAE,sBAA2B,GAAG,gBAAgB,CAuB5F;AAED,uDAAuD;AACvD,MAAM,MAAM,YAAY,GAAG,CACzB,MAAM,EAAE,OAAO,EACf,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,KACtB,WAAW,CAAC,MAAM,CAAC,kBAAkB,EAAE,OAAO,CAAC,CAAC,CAAC;AAEtD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,OAAO,EACf,IAAI,GAAE;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAA;CAAO,GAC5C,iBAAiB,CAAC,kBAAkB,CAAC,CAiBvC"}

package/dist/esm/address-search/default-transports.js

@@ -0,0 +1,129 @@
+import { addressLookupUprn } from "../funcs/addressLookupUprn.js";
+import { AddressSearchError } from "./errors.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;
+/** Parse the billing transparency headers; null when none are present. */
+export function parseBillingHeaders(headers) {
+    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) {
+    if (value === null)
+        return null;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function parseMatchedSubstrings(value) {
+    if (!Array.isArray(value))
+        return [];
+    const ranges = [];
+    for (const entry of value) {
+        if (typeof entry !== "object" || entry === null)
+            continue;
+        const { offset, length } = entry;
+        if (typeof offset === "number" && typeof length === "number")
+            ranges.push({ offset, length });
+    }
+    return ranges;
+}
+function toSuggestion(row) {
+    if (typeof row !== "object" || row === null)
+        return null;
+    const record = row;
+    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) {
+    const envelope = typeof body === "object" && body !== null ? body : {};
+    const rawRows = Array.isArray(envelope.data)
+        ? envelope.data
+        : Array.isArray(envelope.result)
+            ? envelope.result
+            : [];
+    const rows = [];
+    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 = {}) {
+    const baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    const fetchFn = config.fetch ?? globalThis.fetch;
+    const limit = config.limit ?? CANDIDATE_PAGE_LIMIT;
+    return async ({ query, searchId, signal }) => {
+        const params = new URLSearchParams({ q: query, limit: String(limit) });
+        if (searchId !== null)
+            params.set("search_id", searchId);
+        const headers = { 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),
+        };
+    };
+}
+/**
+ * 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, deps = {}) {
+    const lookup = deps.lookup ?? addressLookupUprn;
+    return async ({ suggestion }) => {
+        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 };
+    };
+}
+//# sourceMappingURL=default-transports.js.map

package/dist/esm/address-search/default-transports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-transports.js","sourceRoot":"","sources":["../../../src/address-search/default-transports.ts"],"names":[],"mappings":"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"}

package/dist/esm/address-search/errors.d.ts

@@ -0,0 +1,5 @@
+/** Error raised by the address-search controller and its default transports. */
+export declare class AddressSearchError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/esm/address-search/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/address-search/errors.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B"}

package/dist/esm/address-search/errors.js

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

package/dist/esm/address-search/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/address-search/errors.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF"}

package/dist/esm/address-search/index.d.ts

@@ -0,0 +1,8 @@
+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";
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/address-search/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/address-search/index.ts"],"names":[],"mappings":"AAyBA,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,YAAY,EAAE,SAAS,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACpH,OAAO,EACL,sBAAsB,EACtB,2BAA2B,EAC3B,mBAAmB,GACpB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAChG,YAAY,EACV,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/esm/address-search/index.js

@@ -0,0 +1,30 @@
+/*
+ * 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 { 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";
+//# sourceMappingURL=index.js.map

package/dist/esm/address-search/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/address-search/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEtD,OAAO,EACL,sBAAsB,EACtB,2BAA2B,EAC3B,mBAAmB,GACpB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC"}

package/dist/esm/address-search/lru-cache.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 declare class LruCache<K, V> {
+    #private;
+    constructor(capacity: number);
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    get size(): number;
+}
+//# sourceMappingURL=lru-cache.d.ts.map

package/dist/esm/address-search/lru-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lru-cache.d.ts","sourceRoot":"","sources":["../../../src/address-search/lru-cache.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,QAAQ,CAAC,CAAC,EAAE,CAAC;;gBAIZ,QAAQ,EAAE,MAAM;IAI5B,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAQ1B,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAS3B,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/esm/address-search/lru-cache.js

@@ -0,0 +1,46 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _LruCache_capacity, _LruCache_entries;
+/**
+ * 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 {
+    constructor(capacity) {
+        _LruCache_capacity.set(this, void 0);
+        _LruCache_entries.set(this, new Map());
+        __classPrivateFieldSet(this, _LruCache_capacity, Math.max(1, Math.floor(capacity)), "f");
+    }
+    get(key) {
+        const value = __classPrivateFieldGet(this, _LruCache_entries, "f").get(key);
+        if (value === undefined)
+            return undefined;
+        __classPrivateFieldGet(this, _LruCache_entries, "f").delete(key);
+        __classPrivateFieldGet(this, _LruCache_entries, "f").set(key, value);
+        return value;
+    }
+    set(key, value) {
+        __classPrivateFieldGet(this, _LruCache_entries, "f").delete(key);
+        __classPrivateFieldGet(this, _LruCache_entries, "f").set(key, value);
+        if (__classPrivateFieldGet(this, _LruCache_entries, "f").size > __classPrivateFieldGet(this, _LruCache_capacity, "f")) {
+            const oldest = __classPrivateFieldGet(this, _LruCache_entries, "f").keys().next();
+            if (!oldest.done)
+                __classPrivateFieldGet(this, _LruCache_entries, "f").delete(oldest.value);
+        }
+    }
+    get size() {
+        return __classPrivateFieldGet(this, _LruCache_entries, "f").size;
+    }
+}
+_LruCache_capacity = new WeakMap(), _LruCache_entries = new WeakMap();
+//# sourceMappingURL=lru-cache.js.map

package/dist/esm/address-search/lru-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lru-cache.js","sourceRoot":"","sources":["../../../src/address-search/lru-cache.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA;;;;GAIG;AACH,MAAM,OAAO,QAAQ;IAInB,YAAY,QAAgB;QAHnB,qCAAkB;QAClB,4BAAW,IAAI,GAAG,EAAQ,EAAC;QAGlC,uBAAA,IAAI,sBAAa,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,MAAA,CAAC;IACrD,CAAC;IAED,GAAG,CAAC,GAAM;QACR,MAAM,KAAK,GAAG,uBAAA,IAAI,yBAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACrC,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAC1C,uBAAA,IAAI,yBAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC1B,uBAAA,IAAI,yBAAS,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC9B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,GAAG,CAAC,GAAM,EAAE,KAAQ;QAClB,uBAAA,IAAI,yBAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC1B,uBAAA,IAAI,yBAAS,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC9B,IAAI,uBAAA,IAAI,yBAAS,CAAC,IAAI,GAAG,uBAAA,IAAI,0BAAU,EAAE,CAAC;YACxC,MAAM,MAAM,GAAG,uBAAA,IAAI,yBAAS,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;YAC3C,IAAI,CAAC,MAAM,CAAC,IAAI;gBAAE,uBAAA,IAAI,yBAAS,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;IAED,IAAI,IAAI;QACN,OAAO,uBAAA,IAAI,yBAAS,CAAC,IAAI,CAAC;IAC5B,CAAC;CACF"}

package/dist/esm/address-search/narrow.d.ts

@@ -0,0 +1,21 @@
+/** Lower-case alphanumeric tokens; everything else is a separator. */
+export declare function tokenise(text: string): string[];
+/**
+ * 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 declare function narrowSuggestions<T extends {
+    readonly title: string;
+}>(rows: readonly T[], query: string): T[];
+/** Lower-case, collapse whitespace runs and trim — the cache and prefix key form. */
+export declare function normaliseQuery(text: string): string;
+/**
+ * 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 declare function extendsTriggerPrefix(query: string, triggerPrefix: string): boolean;
+//# sourceMappingURL=narrow.d.ts.map

package/dist/esm/address-search/narrow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"narrow.d.ts","sourceRoot":"","sources":["../../../src/address-search/narrow.ts"],"names":[],"mappings":"AAQA,sEAAsE;AACtE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAK/C;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,EAAE,CAO9G;AAED,qFAAqF;AACrF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAElF"}

package/dist/esm/address-search/narrow.js

@@ -0,0 +1,43 @@
+/*
+ * 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) {
+    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(rows, query) {
+    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) {
+    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, triggerPrefix) {
+    return normaliseQuery(query).startsWith(normaliseQuery(triggerPrefix));
+}
+//# sourceMappingURL=narrow.js.map

package/dist/esm/address-search/narrow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"narrow.js","sourceRoot":"","sources":["../../../src/address-search/narrow.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,sEAAsE;AACtE,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,OAAO,IAAI;SACR,WAAW,EAAE;SACb,KAAK,CAAC,YAAY,CAAC;SACnB,MAAM,CAAC,OAAO,CAAC,CAAC;AACrB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAuC,IAAkB,EAAE,KAAa;IACvG,MAAM,WAAW,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IACpC,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IAC/C,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE;QACzB,MAAM,WAAW,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACxC,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAChH,CAAC,CAAC,CAAC;AACL,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AACxD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAa,EAAE,aAAqB;IACvE,OAAO,cAAc,CAAC,KAAK,CAAC,CAAC,UAAU,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC,CAAC;AACzE,CAAC"}