@findlane/server 0.35.0 → 0.37.0

package/dist/index.d.cts

@@ -408,6 +408,23 @@ export type SearchRequest = {
     /** Only records inside a box, in degrees, such as a map's visible area. West greater than east crosses the
      * antimeridian. */
     within?: GeoBox;
+    /** Only records on a map tile, instead of `near` or `within`, numbered as web maps number them. A record is on exactly one tile
+     * of a zoom, so tiles add up. Needs the index's location field. */
+    tile?: MapTile;
+    /** Answers with `bounds`, the box around every match rather than only the page. */
+    bounds?: boolean;
+    /** With `tile`: answers with `clusters`, its matches grouped by cell. `stats` takes up to three number fields, as `facetStats` does.
+     * `limit: 0` then gives no hits. */
+    clusters?: {
+        cells: MapCells;
+        stats?: string[];
+    };
+    /** With `tile`: the page is each cell's best records (`perCell`, 1 by default, up to 10) rather than the top of one list. It takes
+     * no `offset`, and `distinct` stays off. */
+    spread?: {
+        cells: MapCells;
+        perCell?: number;
+    };
     /** With the index's `relatedResults` on: false asks for no related results (0.18.0). */
     related?: boolean;
     /** With the index's `distinct` setting: false shows every record, a number 1 to 4 how many of each group's
@@ -430,12 +447,17 @@ export type SearchRequest = {
      * subindexes count as one search (0.25.0). */
     subindexes?: Record<string, Omit<SearchRequest, "subindexes"> | true>;
     /** The facet values the query names (0.34.0): `true` for every field of the index's facetMatches setting, or
-     * `{ fields }` for some of them. They come back in `facetMatches`. */
+     * `{ fields }` for some of them. They come back in `facetMatches`. With the setting's `apply`, a match that names a
+     * value exactly filters this search (`applied`, with `rewrittenQuery`); `apply` chooses for this search instead (0.36.0). */
     facetMatches?: boolean | {
         fields?: string[];
+        apply?: FacetMatchApply;
     };
 };
-/** The facetMatches setting (0.34.0); see IndexSettings. */
+/** When a search that asks applies a facet match's filter (0.36.0): never (the default), when the match is the whole
+ * query, or whenever it names a value exactly, searching the query's other words. */
+export type FacetMatchApply = "never" | "whole" | "exact";
+/** The facetMatches setting (0.34.0); see IndexSettings. A field's `apply` goes over the setting's. */
 export type FacetMatchesSetting = {
     fields: Array<{
         field: string;
@@ -445,13 +467,15 @@ export type FacetMatchesSetting = {
         only?: "labelled";
         hide?: string[];
         link?: string;
+        apply?: FacetMatchApply;
     }>;
+    apply?: FacetMatchApply;
     perField?: number;
 };
 /** A facet value a query names (0.34.0): the field's `values` it stands for (several when values share a label),
  * its `label`, its `count` of records the search's filters allow, how it matched (`match`: exact, prefix, typo,
  * or contains, a later word of the value), whether it took every word (`whole`), where those words are in `q`
- * (`typed`, UTF-16 offsets), its `link`, a `filter` for it, and whether the search applied it (false for now). */
+ * (`typed`, UTF-16 offsets), its `link`, a `filter` for it, and whether the search applied it (`applied`, 0.36.0). */
 export type FacetMatch = {
     field: string;
     values: string[];
@@ -492,6 +516,26 @@ export type GeoBox = {
     east: number;
     west: number;
 };
+/** A map tile, numbered as MapLibre and other web maps number them. */
+export type MapTile = {
+    z: number;
+    x: number;
+    y: number;
+};
+/** Cells a side of a map tile. */
+export type MapCells = 1 | 2 | 4 | 8 | 16;
+/** A group of matches: how many, their average place, and the box around them. A box with no size means every record is at one place. */
+export type Cluster = {
+    count: number;
+    lat: number;
+    lng: number;
+    bounds: GeoBox;
+    stats?: Record<string, {
+        min: number;
+        max: number;
+        avg: number;
+    }>;
+};
 /** How a query word matched: as itself, as the start of a longer word, within its typos, through a synonym,
  * as another form of the word in the index's languages (a plural or another spelling, or with `inflections`
  * an Icelandic case or plural), or, with the
@@ -607,6 +651,10 @@ export type SearchResponse<T> = {
     sort?: string;
     /** With `near`: the point distances are from, or null when the visitor's location isn't known. */
     near?: GeoPoint | null;
+    /** With `bounds`: the box around every match with a place on the map, or null without any. */
+    bounds?: GeoBox | null;
+    /** With `clusters`: one for each cell with matches. */
+    clusters?: Cluster[];
     /** With the index's `didYouMean` setting: the query with the words typo tolerance corrected, when the
      * results matched some words only by typo ("Showing results for …"), else null. */
     didYouMean?: DidYouMean | null;

package/dist/index.d.ts

@@ -408,6 +408,23 @@ export type SearchRequest = {
     /** Only records inside a box, in degrees, such as a map's visible area. West greater than east crosses the
      * antimeridian. */
     within?: GeoBox;
+    /** Only records on a map tile, instead of `near` or `within`, numbered as web maps number them. A record is on exactly one tile
+     * of a zoom, so tiles add up. Needs the index's location field. */
+    tile?: MapTile;
+    /** Answers with `bounds`, the box around every match rather than only the page. */
+    bounds?: boolean;
+    /** With `tile`: answers with `clusters`, its matches grouped by cell. `stats` takes up to three number fields, as `facetStats` does.
+     * `limit: 0` then gives no hits. */
+    clusters?: {
+        cells: MapCells;
+        stats?: string[];
+    };
+    /** With `tile`: the page is each cell's best records (`perCell`, 1 by default, up to 10) rather than the top of one list. It takes
+     * no `offset`, and `distinct` stays off. */
+    spread?: {
+        cells: MapCells;
+        perCell?: number;
+    };
     /** With the index's `relatedResults` on: false asks for no related results (0.18.0). */
     related?: boolean;
     /** With the index's `distinct` setting: false shows every record, a number 1 to 4 how many of each group's
@@ -430,12 +447,17 @@ export type SearchRequest = {
      * subindexes count as one search (0.25.0). */
     subindexes?: Record<string, Omit<SearchRequest, "subindexes"> | true>;
     /** The facet values the query names (0.34.0): `true` for every field of the index's facetMatches setting, or
-     * `{ fields }` for some of them. They come back in `facetMatches`. */
+     * `{ fields }` for some of them. They come back in `facetMatches`. With the setting's `apply`, a match that names a
+     * value exactly filters this search (`applied`, with `rewrittenQuery`); `apply` chooses for this search instead (0.36.0). */
     facetMatches?: boolean | {
         fields?: string[];
+        apply?: FacetMatchApply;
     };
 };
-/** The facetMatches setting (0.34.0); see IndexSettings. */
+/** When a search that asks applies a facet match's filter (0.36.0): never (the default), when the match is the whole
+ * query, or whenever it names a value exactly, searching the query's other words. */
+export type FacetMatchApply = "never" | "whole" | "exact";
+/** The facetMatches setting (0.34.0); see IndexSettings. A field's `apply` goes over the setting's. */
 export type FacetMatchesSetting = {
     fields: Array<{
         field: string;
@@ -445,13 +467,15 @@ export type FacetMatchesSetting = {
         only?: "labelled";
         hide?: string[];
         link?: string;
+        apply?: FacetMatchApply;
     }>;
+    apply?: FacetMatchApply;
     perField?: number;
 };
 /** A facet value a query names (0.34.0): the field's `values` it stands for (several when values share a label),
  * its `label`, its `count` of records the search's filters allow, how it matched (`match`: exact, prefix, typo,
  * or contains, a later word of the value), whether it took every word (`whole`), where those words are in `q`
- * (`typed`, UTF-16 offsets), its `link`, a `filter` for it, and whether the search applied it (false for now). */
+ * (`typed`, UTF-16 offsets), its `link`, a `filter` for it, and whether the search applied it (`applied`, 0.36.0). */
 export type FacetMatch = {
     field: string;
     values: string[];
@@ -492,6 +516,26 @@ export type GeoBox = {
     east: number;
     west: number;
 };
+/** A map tile, numbered as MapLibre and other web maps number them. */
+export type MapTile = {
+    z: number;
+    x: number;
+    y: number;
+};
+/** Cells a side of a map tile. */
+export type MapCells = 1 | 2 | 4 | 8 | 16;
+/** A group of matches: how many, their average place, and the box around them. A box with no size means every record is at one place. */
+export type Cluster = {
+    count: number;
+    lat: number;
+    lng: number;
+    bounds: GeoBox;
+    stats?: Record<string, {
+        min: number;
+        max: number;
+        avg: number;
+    }>;
+};
 /** How a query word matched: as itself, as the start of a longer word, within its typos, through a synonym,
  * as another form of the word in the index's languages (a plural or another spelling, or with `inflections`
  * an Icelandic case or plural), or, with the
@@ -607,6 +651,10 @@ export type SearchResponse<T> = {
     sort?: string;
     /** With `near`: the point distances are from, or null when the visitor's location isn't known. */
     near?: GeoPoint | null;
+    /** With `bounds`: the box around every match with a place on the map, or null without any. */
+    bounds?: GeoBox | null;
+    /** With `clusters`: one for each cell with matches. */
+    clusters?: Cluster[];
     /** With the index's `didYouMean` setting: the query with the words typo tolerance corrected, when the
      * results matched some words only by typo ("Showing results for …"), else null. */
     didYouMean?: DidYouMean | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@findlane/server",
-  "version": "0.35.0",
+  "version": "0.37.0",
   "description": "Findlane server SDK: upload catalogs, manage index settings, and search with a secret workspace API key.",
   "keywords": ["findlane", "search", "full-text search", "typo tolerance", "ecommerce search", "search api", "sdk"],
   "license": "MIT",