@klevu/core
Version:
Typescript SDK that simplifies development on Klevu backend. Klevu provides advanced AI-powered search and discovery solutions for online retailers.
279 lines (278 loc) • 10.9 kB
TypeScript
import type { KlevuAnyTypeOfRecord, KlevuRecordFields, KlevuTypeOfSearch } from ".";
import type { KlevuSearchSorting } from "./KlevuSearchSorting.js";
import type { KlevuSearchPreference } from "./KlevuSearchPreference.js";
import type { KlevuBaseQuerySettingsQuery } from "./KlevuBaseQuerySettingsQuery.js";
import type { KlevuGroupConditions } from "./KlevuGroupConditions.js";
export type KlevuBaseQuerySettings = {
query?: KlevuBaseQuerySettingsQuery;
/**
* The groupBy parameter takes the name of a field indexed in the Klevu
* Search backend and ensures that there is only one record for each unique
* value of this field in the search results.
*
* By default, the groupBy operation is performed on the itemGroupId field.
* When querying for KLEVU_CATEGORY or KLEVU_CMS records, it is recommended
* to use name as the groupBy parameter value.
*/
groupBy?: "id" | "name";
/**
* In addition to Products, Categories and CMS Pages, Klevu APIv2 allows you
* to search for custom entities.
*
* For example if you want to display results for recipes, articles or
* physical stores within your search you can do so by utilising the
* typeOfRecords parameter.
*/
typeOfRecords?: KlevuAnyTypeOfRecord[];
/**
*
*/
fields?: KlevuRecordFields[];
/**
* The default sorting of results is RELEVANCE, which uses Klevu A.I. to
* determine the order. There are various other options available which you
* can provide to your customers as required.
*/
sort?: KlevuSearchSorting;
/**
* If sort has been set to ADVANCED_SORT then following object is used to define sorting
*/
advancedSorting?: Array<{
type: "FIELD";
key: string;
order: AdvancedSortingDiretion;
}>;
/**
* Specify the number of record you would like to display per page.
*/
limit?: number;
/**
* Specify the index at which to start counting the number of results from.
*
* The index of the first record in a result set is 0. Thus, if you want to
* start from the 6th result, use an offset of 5.
*/
offset?: number;
/**
* The typeOfSearch parameter defines the behaviour when identifying matches
* for a searched term. For example, whether all or just one of the entered
* words must be matched, whether to allow spelling mistakes, etc.
*/
typeOfSearch?: KlevuTypeOfSearch;
/**
* There are a number of preferences available for fine-tuning your queries.
* For example you can control whether or not to allow fuzzy search for
* spelling mistakes on a query by query basis. The available searchPrefs
* are detailed below.
*/
searchPrefs?: KlevuSearchPreference[];
/**
* The ID of another query which should be fired if the current query yields
* too few results.
*/
fallbackQueryId?: string;
/**
* Use this parameter to specify the criteria for when a fallback query will
* be fired. For example, if you would like a fallback query to fire when
* you have two results or less, specify a value of '3'.
*/
fallbackWhenCountLessThan?: number;
/**
* Specify any records which should always be displayed at the top of the
* result set. You can specify a record id to control this at variant level,
* or a itemGroupId to control this at compound item level.
*
* Note that this is only applicable when the sort order is by 'RELEVANCE'.
*/
topIds?: Array<{
key: string;
value: string;
}>;
/**
* Specify any records which should be included with the results, even if
* the Klevu search query did not match them. You can specify a record id to
* control this at variant level, or a itemGroupId to control this at
* compound item level.
*/
includeIds?: Array<{
key: string;
value: string;
}>;
/**
* Use this field to exclude certain records from the search results. You
* can specify a record id to control this at variant level, or an
* itemGroupId to control this at compound level.
*/
excludeIds?: Array<{
key: string;
value: string;
}>;
/**
* The custom query you would like to fire, which Klevu automatically
* converts into an appropriate query to be included with the request. Use a
* - character before the parenthesis to exclude records matching the
* contained condition.
*
* This is advanced usage of our API and you may need some help with
* building these queries, so when you need support please reach out to us
* via the Community Forum.
*/
customANDQuery?: string;
/**
* When a customer enters a physical shop, they may express their
* preferences to an in-store assistant by highlighting the colours they
* like, the brands they prefer and what they have purchased before.
*
* The in-store assistant would then use this information to show the
* customer products they are most likely interested in first, before
* showing them any others that still may be suitable.
*
* Klevu A.I. is your online assistant.
*
* This personalisation can be provided in two ways:
*
* including some information about the customer's browsing history with
* each request defining your own boosting rules based on information you
* already know about the customer You can read more about how this works in
* our [Personalisation Guide](https://help.klevu.com/support/solutions/articles/5000871361-do-you-offer-apis-for-personalisation-).
*/
personalisation?: {
/**
* This must be set to 'true' for enabling personalisation on a particular
* request. If set to 'false', the recent objects within the context
* object will be ignored
*/
enablePersonalisation: true;
/**
* This is an optional field. By default, Klevu will analyse all
* attributes of the records the customer has interacted with, in order to
* determine the common patterns. If you prefer to focus on particular
* aspects, for example brand or price, specify those attributes within
* this object.
*/
fields?: KlevuRecordFields[];
};
context?: {
/**
* @TODO: Rewrite this doc. Describe how personalisation works
*
* Use this object to specify the records (e.g. products, categories,
* etc.) that were recently interacted with by a customer.
*
* Please only specify one recentObject object per record type, one for
* all KLEVU_PRODUCT entries, another for all KLEVU_CMS pages visited,
* etc.
*
* Each recentObject object may contain multiple record objects (e.g. 5
* recently viewed products). The most recently clicked record should be
* the first element in the array.
*/
recentObjects?: Array<{
/**
* Type of visited record
*/
typeOfRecord: KlevuAnyTypeOfRecord;
/**
* Id's of records
*/
records: Array<{
id: string;
}>;
}>;
/**
* Used with visually similar recommendation search
*/
sourceObjects?: Array<{
/**
* Type of visited record
*/
typeOfRecord: KlevuAnyTypeOfRecord;
/**
* Id's of records
*/
records: Array<{
itemGroupId: string;
} | {
id: string;
} | {
url: string;
}>;
}>;
};
/**
* If you have multiple currency support enabled for your store, this
* parameter can be used to retrieve prices for a specific currency. For
* example, if the data you have indexed with Klevu includes prices for a base
* currency GBP and an additional currency USD, a value of 'GBP' or 'USD' here
* will display the relevant currency values for your records.
*/
priceFieldSuffix?: string;
/**
* A common B2B requirement is different product visibility and prices based
* on a customer group. With Klevu APIv2 you can specify parameters to filter
* out products which a particular customer should not see, and also show
* them specific prices if they differ from the base price.
*
* When specifying a value for priceFieldSuffix, the following fields in your
* response data will be replaced with the value indexed with Klevu for the
* corresponding currency and group:
*
* price, salePrice, currency
*
* When specifying a value for visibilityGroupID, any records that do not
* belong to that group will be excluded from the results.
*
* In the example to the right, the same product is indexed with data for
* currencies 'GBP' and 'USD'. It's visibility is set to groups 'my_group_1'
* and 'my_group_3', but not 'my_group_2'.
*/
visibilityGroupID?: string;
/**
* In KMC the user is able to create campaigns for collections; which are specific
* rules that are tied to a start and end date. This allows a user to create rules
* that assist in promoting or demoting products during a sale, event, season, etc.
* This parameter allows a user to pass in the ID of a campaign into a search.
*
* The implementation can be handled any way the user chooses: URL paramters, cookie,
* localStorage, session, DB, etc.
*/
campaignForCatNav?: string;
/**
* The groupCondition object can be used for applying the advance filtering conditions so your customers can fine-tune
* their results based on relevant attributes.
*
* @example
* Here is an example of how to use the groupCondition object.
* ```
* "groupCondition": {
* "groupOperator": "ANY_OF",
* "conditions": [
* {
* "key": "klevu_price",
* "valueOperator": "INCLUDE",
* "singleSelect": true,
* "excludeValuesInResult": true,
* "values": ["20 - 25"]
* },
* {
* "key": "itemGroupId",
* "valueOperator": "EXCLUDE",
* "singleSelect": false,
* "values": ["4384028262462"]
* },
* {
* "key": "size",
* "valueOperator": "EXCLUDE",
* "singleSelect": false,
* "values": ["Small", "Large"]
* }
* ]
* }
* ```
*/
groupCondition?: KlevuGroupConditions;
};
export declare enum AdvancedSortingDiretion {
Ascending = "ASC",
Descending = "DESC"
}