Merge #1530

1530: Changes related to the next Meilisearch release (v1.3.0) r=bidoubiwa a=meili-bot

Related to this issue: meilisearch/integration-guides#280

This PR:
- gathers the changes related to the next Meilisearch release (v1.3.0) so that this package is ready when the official release is out.
- should pass the tests against the [latest pre-release of Meilisearch](https://github.com/meilisearch/meilisearch/releases).
- might eventually contain test failures until the Meilisearch v1.3.0 is out.

⚠️ This PR should NOT be merged until the next release of Meilisearch (v1.3.0) is out.

_This PR is auto-generated for the [pre-release week](https://github.com/meilisearch/integration-guides/blob/main/resources/pre-release-week.md) purpose._


Co-authored-by: meili-bot <[email protected]>
Co-authored-by: cvermand <[email protected]>
Co-authored-by: Charlotte Vermandel <[email protected]>

Author: 3 people

README.md

@@ -418,6 +418,14 @@ client.multiSearch(queries?: MultiSearchParams, config?: Partial<Request>): Prom
 
 `multiSearch` uses the `POST` method when performing its request to Meilisearch.
 
+### Search For Facet Values
+
+#### [Search for facet values](#)
+
+```ts
+client.index<T>('myIndex').searchForFacetValues(params: SearchForFacetValuesParams, config?: Partial<Request>): Promise<SearchForFacetValuesResponse>
+```
+
 ### Documents <!-- omit in toc -->
 
 #### [Add or replace multiple documents](https://www.meilisearch.com/docs/reference/api/documents#add-or-replace-documents)

src/indexes.ts

@@ -45,6 +45,8 @@ import {
   ContentType,
   DocumentsIds,
   DocumentsDeletionQuery,
+  SearchForFacetValuesParams,
+  SearchForFacetValuesResponse,
 } from './types'
 import { removeUndefinedFromObject } from './utils'
 import { HttpRequests } from './http-requests'
@@ -137,6 +139,8 @@ class Index<T extends Record<string, any> = Record<string, any>> {
       attributesToRetrieve: options?.attributesToRetrieve?.join(','),
       attributesToCrop: options?.attributesToCrop?.join(','),
       attributesToHighlight: options?.attributesToHighlight?.join(','),
+      vector: options?.vector?.join(','),
+      attributesToSearchOn: options?.attributesToSearchOn?.join(','),
     }
 
     return await this.httpRequest.get<SearchResponse<D, S>>(
@@ -146,6 +150,27 @@ class Index<T extends Record<string, any> = Record<string, any>> {
     )
   }
 
+  /**
+   * Search for facet values
+   *
+   * @param params - Parameters used to search on the facets
+   * @param config - Additional request configuration options
+   * @returns Promise containing the search response
+   */
+  async searchForFacetValues(
+    params: SearchForFacetValuesParams,
+    config?: Partial<Request>
+  ): Promise<SearchForFacetValuesResponse> {
+    const url = `indexes/${this.uid}/facet-search`
+
+    return await this.httpRequest.post(
+      url,
+      removeUndefinedFromObject(params),
+      undefined,
+      config
+    )
+  }
+
   ///
   /// INDEX
   ///

src/types/types.ts

@@ -78,6 +78,22 @@ export type Crop = {
   cropMarker?: string
 }
 
+// `facetName` becomes mandatory when using `searchForFacetValues`
+export type SearchForFacetValuesParams = Omit<SearchParams, 'facetName'> & {
+  facetName: string
+}
+
+export type FacetHit = {
+  value: string
+  count: number
+}
+
+export type SearchForFacetValuesResponse = {
+  facetHits: FacetHit[]
+  facetQuery: string | null
+  processingTimeMs: number
+}
+
 export type SearchParams = Query &
   Pagination &
   Highlight &
@@ -90,6 +106,12 @@ export type SearchParams = Query &
     matchingStrategy?: MatchingStrategies
     hitsPerPage?: number
     page?: number
+    facetName?: string
+    facetQuery?: string
+    vector?: number[] | null
+    showRankingScore?: boolean
+    showRankingScoreDetails?: boolean
+    attributesToSearchOn?: string[] | null
   }
 
 // Search parameters for searches made with the GET method
@@ -105,6 +127,8 @@ export type SearchRequestGET = Pagination &
     attributesToHighlight?: string
     attributesToCrop?: string
     showMatchesPosition?: boolean
+    vector?: string | null
+    attributesToSearchOn?: string | null
   }
 
 export type MultiSearchQuery = SearchParams & { indexUid: string }
@@ -126,6 +150,39 @@ export type MatchesPosition<T> = Partial<
 export type Hit<T = Record<string, any>> = T & {
   _formatted?: Partial<T>
   _matchesPosition?: MatchesPosition<T>
+  _rankingScore?: number
+  _rankingScoreDetails?: RakingScoreDetails
+}
+
+export type RakingScoreDetails = {
+  words?: {
+    order: number
+    matchingWords: number
+    maxMatchingWords: number
+    score: number
+  }
+  typo?: {
+    order: number
+    typoCount: number
+    maxTypoCount: number
+    score: number
+  }
+  proximity?: {
+    order: number
+    score: number
+  }
+  attribute?: {
+    order: number
+    attributes_ranking_order: number
+    attributes_query_word_order: number
+    score: number
+  }
+  exactness?: {
+    order: number
+    matchType: string
+    score: number
+  }
+  [key: string]: Record<string, any> | undefined
 }
 
 export type Hits<T = Record<string, any>> = Array<Hit<T>>
@@ -139,9 +196,10 @@ export type SearchResponse<
 > = {
   hits: Hits<T>
   processingTimeMs: number
-  facetDistribution?: FacetDistribution
   query: string
+  facetDistribution?: FacetDistribution
   facetStats?: FacetStats
+  vector?: number[]
 } & (undefined extends S
   ? Partial<FinitePagination & InfinitePagination>
   : true extends IsFinitePagination<NonNullable<S>>
@@ -255,9 +313,13 @@ export type TypoTolerance = {
   }
 } | null
 
+export type FacetOrder = 'alpha' | 'count'
+
 export type Faceting = {
   maxValuesPerFacet?: number | null
+  sortFacetValuesBy?: Record<string, FacetOrder> | null
 }
+
 export type PaginationSettings = {
   maxTotalHits?: number | null
 }
@@ -399,6 +461,7 @@ type CursorResults<T> = {
   limit: number
   from: number
   next: number
+  total: number
 }
 
 export type TasksResults = CursorResults<Task>
@@ -556,12 +619,15 @@ export const enum ErrorStatusCode {
   /** @see https://www.meilisearch.com/docs/reference/errors/error_codes#invalid_document_offset */
   INVALID_DOCUMENT_OFFSET = 'invalid_document_offset',
 
-  /** @see https://www.meilisearch.com/docs/reference/errors/error_codes#invalid_document_offset */
+  /** @see https://www.meilisearch.com/docs/reference/errors/error_codes#invalid_document_filter */
   INVALID_DOCUMENT_FILTER = 'invalid_document_filter',
 
-  /** @see https://www.meilisearch.com/docs/reference/errors/error_codes#invalid_document_offset */
+  /** @see https://www.meilisearch.com/docs/reference/errors/error_codes#missing_document_filter */
   MISSING_DOCUMENT_FILTER = 'missing_document_filter',
 
+  /** @see https://www.meilisearch.com/docs/reference/errors/error_codes#invalid_document_vectors_field */
+  INVALID_DOCUMENT_VECTORS_FIELD = 'invalid_document_vectors_field',
+
   /** @see https://www.meilisearch.com/docs/reference/errors/error_codes#payload_too_large */
   PAYLOAD_TOO_LARGE = 'payload_too_large',
 
@@ -637,6 +703,12 @@ export const enum ErrorStatusCode {
   /** @see https://www.meilisearch.com/docs/reference/errors/error_codes#invalid_search_matching_strategy */
   INVALID_SEARCH_MATCHING_STRATEGY = 'invalid_search_matching_strategy',
 
+  /** @see https://www.meilisearch.com/docs/reference/errors/error_codes#invalid_search_vector */
+  INVALID_SEARCH_VECTOR = 'invalid_search_vector',
+
+  /** @see https://www.meilisearch.com/docs/reference/errors/error_codes#invalid_search_attributes_to_search_on */
+  INVALID_SEARCH_ATTRIBUTES_TO_SEARCH_ON = 'invalid_search_attributes_to_search_on',
+
   /** @see https://www.meilisearch.com/docs/reference/errors/error_codes#bad_request */
   BAD_REQUEST = 'bad_request',
 
@@ -816,6 +888,15 @@ export const enum ErrorStatusCode {
 
   /** @see https://www.meilisearch.com/docs/reference/errors/error_codes#invalid_api_key_offset */
   INVALID_API_KEY_OFFSET = 'invalid_api_key_offset',
+
+  /** @see https://www.meilisearch.com/docs/reference/errors/error_codes#invalid_facet_search_facet_name */
+  INVALID_FACET_SEARCH_FACET_NAME = 'invalid_facet_search_facet_name',
+
+  /** @see https://www.meilisearch.com/docs/reference/errors/error_codes#missing_facet_search_facet_name */
+  MISSING_FACET_SEARCH_FACET_NAME = 'missing_facet_search_facet_name',
+
+  /** @see https://www.meilisearch.com/docs/reference/errors/error_codes#invalid_facet_search_facet_query */
+  INVALID_FACET_SEARCH_FACET_QUERY = 'invalid_facet_search_facet_query',
 }
 
 export type TokenIndexRules = {