@findlane/server 0.36.0 → 0.38.0

package/dist/index.d.cts

@@ -341,7 +341,7 @@ export type PublicSearchPolicy = {
     sortIds?: string[];
     /** With `sortIds`: the sort browsers get when they ask for none. */
     defaultSort?: string;
-    /** Whether browser search may use `near` and `within`, which show roughly where each record is. */
+    /** Whether browser search may use `near`, `within`, `tile`, `bounds`, `clusters` and `spread`, which show roughly where each record is. */
     location?: boolean;
 };
 export type PublicSearchAccess = {
@@ -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?: ClusterStat[];
+    };
+    /** 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
@@ -499,6 +516,33 @@ 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 number field in clusters' stats, by its name. With `gt`, values at or below it are left out of the stat, such as a price of 0
+ * that means no price. Those records stay in the cluster's `count`. */
+export type ClusterStat = string | {
+    field: string;
+    gt?: number;
+};
+/** 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. `stats` leaves out a field no record has a value of. */
+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
@@ -614,6 +658,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

@@ -341,7 +341,7 @@ export type PublicSearchPolicy = {
     sortIds?: string[];
     /** With `sortIds`: the sort browsers get when they ask for none. */
     defaultSort?: string;
-    /** Whether browser search may use `near` and `within`, which show roughly where each record is. */
+    /** Whether browser search may use `near`, `within`, `tile`, `bounds`, `clusters` and `spread`, which show roughly where each record is. */
     location?: boolean;
 };
 export type PublicSearchAccess = {
@@ -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?: ClusterStat[];
+    };
+    /** 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
@@ -499,6 +516,33 @@ 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 number field in clusters' stats, by its name. With `gt`, values at or below it are left out of the stat, such as a price of 0
+ * that means no price. Those records stay in the cluster's `count`. */
+export type ClusterStat = string | {
+    field: string;
+    gt?: number;
+};
+/** 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. `stats` leaves out a field no record has a value of. */
+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
@@ -614,6 +658,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.36.0",
+  "version": "0.38.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",