@findlane/server 0.33.0 → 0.35.0

package/dist/index.d.cts

@@ -107,6 +107,13 @@ export type IndexSettings = {
     variants?: {
         field: string;
     } | null;
+    /** Facet matches (0.34.0): the facet values a search's query names, such as a category, a brand or a zip, for
+     * searches that ask (`facetMatches` in a search). Each of up to 10 fields is a facet, with its values' names
+     * read from records beside them (`labelPath`, and `labelKey` when the field isn't beside it: categories.name
+     * beside categories.slug), written (`labels`: a value's names, values sharing one matching as one), or the
+     * values themselves; `only: "labelled"` leaves the rest out, `hide` lists values that never match, and `link`
+     * is where a match goes, with `{value}`. `perField` matches per field, 3 by default. Null for none. */
+    facetMatches?: FacetMatchesSetting | null;
     /** When saving: types for fields no record has yet, so settings can come before the records. Records'
      * types win once they have the field. Not returned when reading settings. */
     fieldTypes?: Record<string, "text" | "number" | "boolean" | "text[]" | "number[]" | "boolean[]" | "location">;
@@ -422,6 +429,42 @@ export type SearchRequest = {
      * unless it says, or `true` for that. Up to 5. Their results come back in `subindexes`; the search and its
      * 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`. */
+    facetMatches?: boolean | {
+        fields?: string[];
+    };
+};
+/** The facetMatches setting (0.34.0); see IndexSettings. */
+export type FacetMatchesSetting = {
+    fields: Array<{
+        field: string;
+        labelPath?: string;
+        labelKey?: string;
+        labels?: Record<string, string | string[]>;
+        only?: "labelled";
+        hide?: string[];
+        link?: string;
+    }>;
+    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). */
+export type FacetMatch = {
+    field: string;
+    values: string[];
+    label: string;
+    count: number;
+    match: "exact" | "prefix" | "typo" | "contains";
+    whole: boolean;
+    typed?: [number, number];
+    link?: string;
+    filter: Record<string, {
+        in: Array<string | number | boolean>;
+    }>;
+    applied: boolean;
 };
 /** A subindex whose search failed, such as one the index doesn't have (404). */
 export type SubindexError = {
@@ -589,6 +632,8 @@ export type SearchResponse<T> = {
     };
     /** With `subindexes`: each subindex's results by name, or its error (0.25.0). */
     subindexes?: Record<string, SearchResponse<JsonRecord> | SubindexError>;
+    /** With `facetMatches`: the facet values the query names, best first, at most 10 (0.34.0). */
+    facetMatches?: FacetMatch[];
 };
 /** How a product's recommendations are served (the recommendations add-on). */
 /** One of an index's lists (docs: Lists): a row of products, such as Popular or New arrivals, from a filter and
@@ -810,6 +855,17 @@ export type ServerEvent = {
     query?: string;
     position?: number;
     timestamp?: number;
+}
+/** A facet match was picked: its field, the value picked (one of the match's values), its label, the search's
+ * query, and its place among the rows. */
+ | {
+    type: "facetMatch";
+    field: string;
+    value: string;
+    label?: string;
+    query?: string;
+    position?: number;
+    timestamp?: number;
 };
 /** A category page (a facet field's value, without search words), or a search's exact words. */
 export type MerchandisingTarget = {

package/dist/index.d.ts

@@ -107,6 +107,13 @@ export type IndexSettings = {
     variants?: {
         field: string;
     } | null;
+    /** Facet matches (0.34.0): the facet values a search's query names, such as a category, a brand or a zip, for
+     * searches that ask (`facetMatches` in a search). Each of up to 10 fields is a facet, with its values' names
+     * read from records beside them (`labelPath`, and `labelKey` when the field isn't beside it: categories.name
+     * beside categories.slug), written (`labels`: a value's names, values sharing one matching as one), or the
+     * values themselves; `only: "labelled"` leaves the rest out, `hide` lists values that never match, and `link`
+     * is where a match goes, with `{value}`. `perField` matches per field, 3 by default. Null for none. */
+    facetMatches?: FacetMatchesSetting | null;
     /** When saving: types for fields no record has yet, so settings can come before the records. Records'
      * types win once they have the field. Not returned when reading settings. */
     fieldTypes?: Record<string, "text" | "number" | "boolean" | "text[]" | "number[]" | "boolean[]" | "location">;
@@ -422,6 +429,42 @@ export type SearchRequest = {
      * unless it says, or `true` for that. Up to 5. Their results come back in `subindexes`; the search and its
      * 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`. */
+    facetMatches?: boolean | {
+        fields?: string[];
+    };
+};
+/** The facetMatches setting (0.34.0); see IndexSettings. */
+export type FacetMatchesSetting = {
+    fields: Array<{
+        field: string;
+        labelPath?: string;
+        labelKey?: string;
+        labels?: Record<string, string | string[]>;
+        only?: "labelled";
+        hide?: string[];
+        link?: string;
+    }>;
+    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). */
+export type FacetMatch = {
+    field: string;
+    values: string[];
+    label: string;
+    count: number;
+    match: "exact" | "prefix" | "typo" | "contains";
+    whole: boolean;
+    typed?: [number, number];
+    link?: string;
+    filter: Record<string, {
+        in: Array<string | number | boolean>;
+    }>;
+    applied: boolean;
 };
 /** A subindex whose search failed, such as one the index doesn't have (404). */
 export type SubindexError = {
@@ -589,6 +632,8 @@ export type SearchResponse<T> = {
     };
     /** With `subindexes`: each subindex's results by name, or its error (0.25.0). */
     subindexes?: Record<string, SearchResponse<JsonRecord> | SubindexError>;
+    /** With `facetMatches`: the facet values the query names, best first, at most 10 (0.34.0). */
+    facetMatches?: FacetMatch[];
 };
 /** How a product's recommendations are served (the recommendations add-on). */
 /** One of an index's lists (docs: Lists): a row of products, such as Popular or New arrivals, from a filter and
@@ -810,6 +855,17 @@ export type ServerEvent = {
     query?: string;
     position?: number;
     timestamp?: number;
+}
+/** A facet match was picked: its field, the value picked (one of the match's values), its label, the search's
+ * query, and its place among the rows. */
+ | {
+    type: "facetMatch";
+    field: string;
+    value: string;
+    label?: string;
+    query?: string;
+    position?: number;
+    timestamp?: number;
 };
 /** A category page (a facet field's value, without search words), or a search's exact words. */
 export type MerchandisingTarget = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@findlane/server",
-  "version": "0.33.0",
+  "version": "0.35.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",