From 7023ca6966ccaddc1bfc413608e186f8210077ac Mon Sep 17 00:00:00 2001 From: Frank Hassanabad Date: Tue, 12 Apr 2022 15:29:29 -0600 Subject: [PATCH] [Security Solutions] Adds API docs for value lists (#129962) ## Summary Adds API docs for value lists ### Checklist - [x] [Documentation](https://www.elastic.co/guide/en/kibana/master/development-documentation.html) was added for features that require explanation or tutorials --- .../server/services/lists/list_client.ts | 285 +++++++++++++++++- .../services/lists/list_client_types.ts | 157 +++++++++- 2 files changed, 435 insertions(+), 7 deletions(-) diff --git a/x-pack/plugins/lists/server/services/lists/list_client.ts b/x-pack/plugins/lists/server/services/lists/list_client.ts index 107bc31f2baea8..602c1c796a0e07 100644 --- a/x-pack/plugins/lists/server/services/lists/list_client.ts +++ b/x-pack/plugins/lists/server/services/lists/list_client.ts @@ -5,7 +5,7 @@ * 2.0. */ -import { ElasticsearchClient } from 'kibana/server'; +import type { ElasticsearchClient } from 'kibana/server'; import { createBootstrapIndex, deleteAllIndex, @@ -26,7 +26,7 @@ import type { SearchListItemArraySchema, } from '@kbn/securitysolution-io-ts-list-types'; -import { ConfigType } from '../../config'; +import type { ConfigType } from '../../config'; import { createList, deleteList, @@ -54,7 +54,7 @@ import { import listsItemsPolicy from '../items/list_item_policy.json'; import listPolicy from './list_policy.json'; -import { +import type { ConstructorOptions, CreateListIfItDoesNotExistOptions, CreateListItemOptions, @@ -76,12 +76,31 @@ import { } from './list_client_types'; import { createListIfItDoesNotExist } from './create_list_if_it_does_not_exist'; +/** + * Class for use for value lists are are associated with exception lists. + * See {@link https://www.elastic.co/guide/en/security/current/lists-api-create-container.html} + */ export class ListClient { + /** Kibana space id the value lists are part of */ private readonly spaceId: string; + + /** User creating, modifying, deleting, or updating a value list */ private readonly user: string; + + /** Configuration for determining things such as maximum sizes */ private readonly config: ConfigType; + + /** The elastic search client to do the queries with */ private readonly esClient: ElasticsearchClient; + /** + * Constructs the value list + * @param options + * @param options.spaceId Kibana space id the value lists are part of + * @param options.user The user associated with the value list + * @param options.config Configuration for determining things such as maximum sizes + * @param options.esClient The elastic search client to do the queries with + */ constructor({ spaceId, user, config, esClient }: ConstructorOptions) { this.spaceId = spaceId; this.user = user; @@ -89,6 +108,10 @@ export class ListClient { this.esClient = esClient; } + /** + * Returns the list index name + * @returns The list index name + */ public getListIndex = (): string => { const { spaceId, @@ -97,6 +120,10 @@ export class ListClient { return getListIndex({ listsIndexName, spaceId }); }; + /** + * Returns the list item index name + * @returns The list item index name + */ public getListItemIndex = (): string => { const { spaceId, @@ -105,12 +132,34 @@ export class ListClient { return getListItemIndex({ listsItemsIndexName, spaceId }); }; + /** + * Given a list id, this will return the list container + * @param options + * @param options.id The id of the list + * @returns The List container if found, otherwise null + */ public getList = async ({ id }: GetListOptions): Promise => { const { esClient } = this; const listIndex = this.getListIndex(); return getList({ esClient, id, listIndex }); }; + /** + * Creates a list, if given at least the "name", "description", "type", and "version" + * See {@link https://www.elastic.co/guide/en/security/current/lists-api-create-container.html} + * for more information around formats of the deserializer and serializer + * @param options + * @param options.id The id of the list to create or "undefined" if you want an "id" to be auto-created for you + * @param options.deserializer A custom deserializer for the list. Optionally, you an define this as handle bars. See online docs for more information. + * @param options.immutable Set this to true if this is a list that is "immutable"/"pre-packaged". + * @param options.serializer Determines how uploaded list item values are parsed. By default, list items are parsed using named regex groups. See online docs for more information. + * @param options.name The name of the list + * @param options.description The description of the list + * @param options.type The type of list such as "boolean", "double", "text", "keyword", etc... + * @param options.meta Additional meta data to associate with the list as an object of "key/value" pairs + * @param options.version Version number of the list, typically this should be 1 unless you are re-creating a list you deleted or something unusual. + * @returns The list created + */ public createList = async ({ id, deserializer, @@ -140,6 +189,24 @@ export class ListClient { }); }; + /** + * Creates a list, if given at least the "name", "description", "type", and "version" + * See {@link https://www.elastic.co/guide/en/security/current/lists-api-create-container.html} + * for more information around formats of the deserializer and serializer. + * This will create the list if it does not exist. If the list exists, this will ignore creating + * anything and just return the existing list. + * @param options + * @param options.id The id of the list to create or "undefined" if you want an "id" to be auto-created for you + * @param options.deserializer A custom deserializer for the list. Optionally, you an define this as handle bars. See online docs for more information. + * @param options.immutable Set this to true if this is a list that is "immutable"/"pre-packaged". + * @param options.serializer Determines how uploaded list item values are parsed. By default, list items are parsed using named regex groups. See online docs for more information. + * @param options.name The name of the list + * @param options.description The description of the list + * @param options.type The type of list such as "boolean", "double", "text", "keyword", etc... + * @param options.meta Additional meta data to associate with the list as an object of "key/value" pairs + * @param options.version Version number of the list, typically this should be 1 unless you are re-creating a list you deleted or something unusual. + * @returns The list created + */ public createListIfItDoesNotExist = async ({ id, deserializer, @@ -169,64 +236,108 @@ export class ListClient { }); }; + /** + * True if the list index exists, otherwise false + * @returns True if the list index exists, otherwise false + */ public getListIndexExists = async (): Promise => { const { esClient } = this; const listIndex = this.getListIndex(); return getIndexExists(esClient, listIndex); }; + /** + * True if the list index item exists, otherwise false + * @returns True if the list item index exists, otherwise false + */ public getListItemIndexExists = async (): Promise => { const { esClient } = this; const listItemIndex = this.getListItemIndex(); return getIndexExists(esClient, listItemIndex); }; + /** + * Creates the list boot strap index for ILM policies. + * @returns The contents of the bootstrap response from Elasticsearch + */ public createListBootStrapIndex = async (): Promise => { const { esClient } = this; const listIndex = this.getListIndex(); return createBootstrapIndex(esClient, listIndex); }; + /** + * Creates the list item boot strap index for ILM policies. + * @returns The contents of the bootstrap response from Elasticsearch + */ public createListItemBootStrapIndex = async (): Promise => { const { esClient } = this; const listItemIndex = this.getListItemIndex(); return createBootstrapIndex(esClient, listItemIndex); }; + /** + * Returns true if the list policy for ILM exists, otherwise false + * @returns True if the list policy for ILM exists, otherwise false. + */ public getListPolicyExists = async (): Promise => { const { esClient } = this; const listIndex = this.getListIndex(); return getPolicyExists(esClient, listIndex); }; + /** + * Returns true if the list item policy for ILM exists, otherwise false + * @returns True if the list item policy for ILM exists, otherwise false. + */ public getListItemPolicyExists = async (): Promise => { const { esClient } = this; const listsItemIndex = this.getListItemIndex(); return getPolicyExists(esClient, listsItemIndex); }; + /** + * Returns true if the list template for ILM exists, otherwise false + * @returns True if the list template for ILM exists, otherwise false. + */ public getListTemplateExists = async (): Promise => { const { esClient } = this; const listIndex = this.getListIndex(); return getTemplateExists(esClient, listIndex); }; + /** + * Returns true if the list item template for ILM exists, otherwise false + * @returns True if the list item template for ILM exists, otherwise false. + */ public getListItemTemplateExists = async (): Promise => { const { esClient } = this; const listItemIndex = this.getListItemIndex(); return getTemplateExists(esClient, listItemIndex); }; + /** + * Returns the list template for ILM. + * @returns The contents of the list template for ILM. + */ public getListTemplate = (): Record => { const listIndex = this.getListIndex(); return getListTemplate(listIndex); }; + /** + * Returns the list item template for ILM. + * @returns The contents of the list item template for ILM. + */ public getListItemTemplate = (): Record => { const listItemIndex = this.getListItemIndex(); return getListItemTemplate(listItemIndex); }; + /** + * Sets the list template for ILM. + * @returns The contents of the list template for ILM. + */ public setListTemplate = async (): Promise => { const { esClient } = this; const template = this.getListTemplate(); @@ -234,6 +345,10 @@ export class ListClient { return setTemplate(esClient, listIndex, template); }; + /** + * Sets the list item template for ILM. + * @returns The contents of the list item template for ILM. + */ public setListItemTemplate = async (): Promise => { const { esClient } = this; const template = this.getListItemTemplate(); @@ -241,60 +356,104 @@ export class ListClient { return setTemplate(esClient, listItemIndex, template); }; + /** + * Sets the list policy + * @returns The contents of the list policy set + */ public setListPolicy = async (): Promise => { const { esClient } = this; const listIndex = this.getListIndex(); return setPolicy(esClient, listIndex, listPolicy); }; + /** + * Sets the list item policy + * @returns The contents of the list policy set + */ public setListItemPolicy = async (): Promise => { const { esClient } = this; const listItemIndex = this.getListItemIndex(); return setPolicy(esClient, listItemIndex, listsItemsPolicy); }; + /** + * Deletes the list index + * @returns True if the list index was deleted, otherwise false + */ public deleteListIndex = async (): Promise => { const { esClient } = this; const listIndex = this.getListIndex(); return deleteAllIndex(esClient, `${listIndex}-*`); }; + /** + * Deletes the list item index + * @returns True if the list item index was deleted, otherwise false + */ public deleteListItemIndex = async (): Promise => { const { esClient } = this; const listItemIndex = this.getListItemIndex(); return deleteAllIndex(esClient, `${listItemIndex}-*`); }; + /** + * Deletes the list policy + * @returns The contents of the list policy + */ public deleteListPolicy = async (): Promise => { const { esClient } = this; const listIndex = this.getListIndex(); return deletePolicy(esClient, listIndex); }; + /** + * Deletes the list item policy + * @returns The contents of the list item policy + */ public deleteListItemPolicy = async (): Promise => { const { esClient } = this; const listItemIndex = this.getListItemIndex(); return deletePolicy(esClient, listItemIndex); }; + /** + * Deletes the list template + * @returns The contents of the list template + */ public deleteListTemplate = async (): Promise => { const { esClient } = this; const listIndex = this.getListIndex(); return deleteTemplate(esClient, listIndex); }; + /** + * Deletes the list item template + * @returns The contents of the list item template + */ public deleteListItemTemplate = async (): Promise => { const { esClient } = this; const listItemIndex = this.getListItemIndex(); return deleteTemplate(esClient, listItemIndex); }; + /** + * Given a list item id, this will delete the single list item + * @returns The list item if found, otherwise null + */ public deleteListItem = async ({ id }: DeleteListItemOptions): Promise => { const { esClient } = this; const listItemIndex = this.getListItemIndex(); return deleteListItem({ esClient, id, listItemIndex }); }; + /** + * Given a list value, this will delete all list items that have that value + * @param options + * @param options.listId The "list_id"/list container to delete from + * @param options.value The value to delete the list items by + * @param options.type The type of list such as "boolean", "double", "text", "keyword", etc... + * @returns The list items deleted. + */ public deleteListItemByValue = async ({ listId, value, @@ -311,6 +470,12 @@ export class ListClient { }); }; + /** + * Given a list id, this will delete the list from the id + * @param options + * @param options.id The id of the list to delete + * @returns The list deleted if found, otherwise null + */ public deleteList = async ({ id }: DeleteListOptions): Promise => { const { esClient } = this; const listIndex = this.getListIndex(); @@ -323,6 +488,13 @@ export class ListClient { }); }; + /** + * Exports list items to a stream + * @param options + * @param options.stringToAppend Optional string to append at the end of each item such as a newline "\n". If undefined is passed, no string is appended. + * @param options.listId The list id to export all the item from + * @param options.stream The stream to push the export into + */ public exportListItemsToStream = ({ stringToAppend, listId, @@ -339,6 +511,19 @@ export class ListClient { }); }; + /** + * Imports list items to a stream. If the list already exists, this will append the list items to the existing list. + * If the list does not exist, this will auto-create the list and then add the items to that list. + * See {@link https://www.elastic.co/guide/en/security/current/lists-api-create-container.html} + * for more information around formats of the deserializer and serializer. + * @param options + * @param options.deserializer A custom deserializer for the list. Optionally, you an define this as handle bars. See online docs for more information. + * @param options.serializer Determines how uploaded list item values are parsed. By default, list items are parsed using named regex groups. See online docs for more information. + * @param options.type The type of list such as "boolean", "double", "text", "keyword", etc... + * @param options.stream The stream to pull the import from + * @param options.meta Additional meta data to associate with the list items as an object of "key/value" pairs. You can set this to "undefined" for no meta values. + * @param options.version Version number of the list, typically this should be 1 unless you are re-creating a list you deleted or something unusual. + */ public importListItemsToStream = async ({ deserializer, serializer, @@ -367,6 +552,14 @@ export class ListClient { }); }; + /** + * Returns all list items found by value. + * @param options + * @param options.listId The list id to search for the list item by value. + * @param options.value The list value to find the list item by. + * @param options.type The type of list such as "boolean", "double", "text", "keyword", etc... + * @returns The list items by value found. + */ public getListItemByValue = async ({ listId, value, @@ -383,6 +576,20 @@ export class ListClient { }); }; + /** + * Creates a list item given at least "value", "type", and a "listId" where "listId" is the parent container that this list + * item belongs to. + * See {@link https://www.elastic.co/guide/en/security/current/lists-api-create-container.html} + * for more information around formats of the deserializer and serializer. + * @param options + * @param options.id Optional Elasticsearch id, if none is given an autogenerated one will be used. + * @param options.deserializer A custom deserializer for the list. Optionally, you an define this as handle bars. See online docs for more information. + * @param options.serializer Determines how uploaded list item values are parsed. By default, list items are parsed using named regex groups. See online docs for more information. + * @param options.listId The "list_id" this list item belongs to. + * @param options.value The value of the list item. + * @param options.type The type of list such as "boolean", "double", "text", "keyword", etc... + * @param options.meta Additional meta data to associate with the list items as an object of "key/value" pairs. You can set this to "undefined" for no meta values. + */ public createListItem = async ({ id, deserializer, @@ -408,6 +615,16 @@ export class ListClient { }); }; + /** + * Updates a list item's value given the id of the list item. + * See {@link https://www.elastic.co/guide/en/elasticsearch/reference/current/optimistic-concurrency-control.html} + * for more information around optimistic concurrency control. + * @param options + * @param options._version This is the version, useful for optimistic concurrency control. + * @param options.id id of the list to replace the list item with. + * @param options.value The value of the list item to replace. + * @param options.meta Additional meta data to associate with the list items as an object of "key/value" pairs. You can set this to "undefined" to not update meta values. + */ public updateListItem = async ({ _version, id, @@ -427,6 +644,18 @@ export class ListClient { }); }; + /** + * Updates a list container's value given the id of the list. + * See {@link https://www.elastic.co/guide/en/elasticsearch/reference/current/optimistic-concurrency-control.html} + * for more information around optimistic concurrency control. + * @param options + * @param options._version This is the version, useful for optimistic concurrency control. + * @param options.id id of the list to replace the list container data with. + * @param options.name The new name, or "undefined" if this should not be updated. + * @param options.description The new description, or "undefined" if this should not be updated. + * @param options.meta Additional meta data to associate with the list items as an object of "key/value" pairs. You can set this to "undefined" to not update meta values. + * @param options.version Updates the version of the list. + */ public updateList = async ({ _version, id, @@ -450,6 +679,12 @@ export class ListClient { }); }; + /** + * Given a list item id, this returns the list item if it exists, otherwise "null". + * @param options + * @param options.id The id of the list item to get. + * @returns The list item found if it exists, otherwise "null". + */ public getListItem = async ({ id }: GetListItemOptions): Promise => { const { esClient } = this; const listItemIndex = this.getListItemIndex(); @@ -460,6 +695,14 @@ export class ListClient { }); }; + /** + * Given a list item value, this returns all list items found with that value. + * @param options + * @param options.type The type of list such as "boolean", "double", "text", "keyword", etc... + * @param options.listId The id of the list container to search for list items. + * @param options.value The value to search for list items based off. + * @returns All list items that match the value sent in. + */ public getListItemByValues = async ({ type, listId, @@ -476,6 +719,14 @@ export class ListClient { }); }; + /** + * Given a list item value, this search for all list items found with that value. + * @param options + * @param options.type The type of list such as "boolean", "double", "text", "keyword", etc... + * @param options.listId The id of the list container to search for list items. + * @param options.value The value to search for list items based off. + * @returns All list items that match the value sent in. + */ public searchListItemByValues = async ({ type, listId, @@ -492,6 +743,19 @@ export class ListClient { }); }; + /** + * Finds lists based on a filter passed in. This is a bit complicated as it existed before + * PIT (Point in Time) and other mechanisms. This uses an older way of doing "hops" and + * accepting a "currentIndexPosition" which acts like a pointer to where the search should continue. + * @param options + * @param options.filter A KQL string filter to find lists. + * @param options.currentIndexPosition The current index position to search from. + * @param options.perPage How many per page to return. + * @param options.sortField Which field to sort on, "undefined" for no sort field + * @param options.sortOrder "asc" or "desc" to sort, otherwise "undefined" if there is no sort order + * @param options.searchAfter array of search_after terms, otherwise "undefined" if there is no search_after + * @returns All lists found based on the passed in filter. + */ public findList = async ({ filter, currentIndexPosition, @@ -516,6 +780,21 @@ export class ListClient { }); }; + /** + * Finds list items based on a filter passed in. This is a bit complicated as it existed before + * PIT (Point in Time) and other mechanisms. This uses an older way of doing "hops" and + * accepting a "currentIndexPosition" which acts like a pointer to where the search should continue. + * @param options + * @param options.listId The list id to search for the list items + * @param options.filter A KQL string filter to find list items. + * @param options.currentIndexPosition The current index position to search from. + * @param options.perPage How many per page to return. + * @param options.page The current page number for the current find + * @param options.sortField Which field to sort on, "undefined" for no sort field + * @param options.sortOrder "asc" or "desc" to sort, otherwise "undefined" if there is no sort order + * @param options.searchAfter array of search_after terms, otherwise "undefined" if there is no search_after + * @returns All list items found based on the passed in filter. + */ public findListItem = async ({ listId, filter, diff --git a/x-pack/plugins/lists/server/services/lists/list_client_types.ts b/x-pack/plugins/lists/server/services/lists/list_client_types.ts index 86b69d5469dc47..794d7f2d6da808 100644 --- a/x-pack/plugins/lists/server/services/lists/list_client_types.ts +++ b/x-pack/plugins/lists/server/services/lists/list_client_types.ts @@ -5,9 +5,9 @@ * 2.0. */ -import { PassThrough, Readable } from 'stream'; +import type { PassThrough, Readable } from 'stream'; -import { ElasticsearchClient } from 'kibana/server'; +import type { ElasticsearchClient } from 'kibana/server'; import type { Description, DescriptionOrUndefined, @@ -29,140 +29,289 @@ import type { Type, _VersionOrUndefined, } from '@kbn/securitysolution-io-ts-list-types'; -import { Version, VersionOrUndefined } from '@kbn/securitysolution-io-ts-types'; +import type { Version, VersionOrUndefined } from '@kbn/securitysolution-io-ts-types'; -import { ConfigType } from '../../config'; +import type { ConfigType } from '../../config'; +/** + * Constructor options to {@link ListClient:constructor} + */ export interface ConstructorOptions { + /** The elastic search client to do the queries with */ esClient: ElasticsearchClient; + /** Configuration for determining things such as maximum sizes */ config: ConfigType; + /** Kibana space id the value lists are part of */ spaceId: string; + /** The user associated with the value list */ user: string; } +/** + * ListClient.getList + * {@link ListClient.getList} + */ export interface GetListOptions { + /** The id of the list */ id: Id; } +/** + * ListClient.deleteList + * {@link ListClient.deleteList} + */ export interface DeleteListOptions { + /** The id of the list to delete */ id: Id; } +/** + * ListClient.deleteListItem + * {@link ListClient.deleteListItem} + */ export interface DeleteListItemOptions { + /** The id of the list to delete from */ id: Id; } +/** + * ListClient.createList + * {@link ListClient.createList} + */ export interface CreateListOptions { id: IdOrUndefined; + /** A custom deserializer for the list. Optionally, you an define this as handle bars. See online docs for more information. */ deserializer: DeserializerOrUndefined; + /** Set this to true if this is a list that is "immutable"/"pre-packaged" */ immutable: Immutable; + /** Determines how uploaded list item values are parsed. By default, list items are parsed using named regex groups. See online docs for more information. */ serializer: SerializerOrUndefined; + /** The name of the list */ name: Name; + /** The description of the list */ description: Description; + /** The type of list such as "boolean", "double", "text", "keyword", etc... */ type: Type; + /** Additional meta data to associate with the list as an object of "key/value" pairs */ meta: MetaOrUndefined; + /** Version number of the list, typically this should be 1 unless you are re-creating a list you deleted or something unusual. */ version: Version; } +/** + * ListClient.createListIfItDoesNotExist + * {@link ListClient.createListIfItDoesNotExist} + */ export interface CreateListIfItDoesNotExistOptions { + /** The id of the list to create or "undefined" if you want an "id" to be auto-created for you */ id: Id; + /** A custom deserializer for the list. Optionally, you an define this as handle bars. See online docs for more information. */ deserializer: DeserializerOrUndefined; + /** Determines how uploaded list item values are parsed. By default, list items are parsed using named regex groups. See online docs for more information. */ serializer: SerializerOrUndefined; + /** The name of the list */ name: Name; + /** The description of the list */ description: Description; + /** The type of list such as "boolean", "double", "text", "keyword", etc... */ type: Type; + /** Additional meta data to associate with the list as an object of "key/value" pairs */ meta: MetaOrUndefined; + /** Version number of the list, typically this should be 1 unless you are re-creating a list you deleted or something unusual. */ version: Version; + /** Set this to true if this is a list that is "immutable"/"pre-packaged" */ immutable: Immutable; } +/** + * ListClient.deleteListItemByValue + * {@link ListClient.deleteListItemByValue} + */ export interface DeleteListItemByValueOptions { + /** The "list_id"/list container to delete from */ listId: string; + /** The value to delete the list items by */ value: string; + /** The type of list such as "boolean", "double", "text", "keyword", etc... */ type: Type; } +/** + * ListClient.getListItemByValue + * {@link ListClient.getListItemByValue} + */ export interface GetListItemByValueOptions { + /** The list id to search for the list item by value. */ listId: string; + /** The list value to find the list item by. */ value: string; + /** The type of list such as "boolean", "double", "text", "keyword", etc... */ type: Type; } +/** + * ListClient.exportListItemsToStream + * {@link ListClient.exportListItemsToStream} + */ export interface ExportListItemsToStreamOptions { + /** Optional string to append at the end of each item such as a newline "\n". If undefined is passed, no string is appended. */ stringToAppend: string | null | undefined; + /** The list id to export all the item from */ listId: string; + /** The stream to push the export into */ stream: PassThrough; } +/** + * ListClient.importListItemsToStream + * {@link ListClient.importListItemsToStream} + */ export interface ImportListItemsToStreamOptions { listId: ListIdOrUndefined; + /** A custom deserializer for the list. Optionally, you an define this as handle bars. See online docs for more information. */ deserializer: DeserializerOrUndefined; + /** Determines how uploaded list item values are parsed. By default, list items are parsed using named regex groups. See online docs for more information. */ serializer: SerializerOrUndefined; + /** The type of list such as "boolean", "double", "text", "keyword", etc... */ type: Type; + /** The stream to pull the import from */ stream: Readable; + /** Additional meta data to associate with the list items as an object of "key/value" pairs. You can set this to "undefined" for no meta values. */ meta: MetaOrUndefined; + /** Version number of the list, typically this should be 1 unless you are re-creating a list you deleted or something unusual. */ version: Version; } +/** + * ListClient.createListItem + * {@link ListClient.createListItem} + */ export interface CreateListItemOptions { + /** Optional Elasticsearch id, if none is given an autogenerated one will be used. */ id: IdOrUndefined; + /** A custom deserializer for the list. Optionally, you an define this as handle bars. See online docs for more information. */ deserializer: DeserializerOrUndefined; + /** Determines how uploaded list item values are parsed. By default, list items are parsed using named regex groups. See online docs for more information. */ serializer: SerializerOrUndefined; + /** The "list_id" this list item belongs to. */ listId: string; + /** The type of list such as "boolean", "double", "text", "keyword", etc... */ type: Type; + /** The value of the list item. */ value: string; + /** Additional meta data to associate with the list items as an object of "key/value" pairs. You can set this to "undefined" for no meta values. */ meta: MetaOrUndefined; } +/** + * ListClient.updateListItem + * {@link ListClient.updateListItem} + */ export interface UpdateListItemOptions { + /** This is the version, useful for optimistic concurrency control. */ _version: _VersionOrUndefined; + /** id of the list to replace the list item with. */ id: Id; + /** The value of the list item to replace. */ value: string | null | undefined; + /** Additional meta data to associate with the list items as an object of "key/value" pairs. You can set this to "undefined" to not update meta values. */ meta: MetaOrUndefined; } +/** + * ListClient.updateList + * {@link ListClient.updateList} + */ export interface UpdateListOptions { + /** This is the version, useful for optimistic concurrency control. */ _version: _VersionOrUndefined; + /** id of the list to replace the list container data with. */ id: Id; + /** The new name, or "undefined" if this should not be updated. */ name: NameOrUndefined; + /** The new description, or "undefined" if this should not be updated. */ description: DescriptionOrUndefined; + /** Additional meta data to associate with the list items as an object of "key/value" pairs. You can set this to "undefined" to not update meta values. */ meta: MetaOrUndefined; + /** Updates the version of the list. */ version: VersionOrUndefined; } +/** + * ListClient.getListItem + * {@link ListClient.getListItem} + */ export interface GetListItemOptions { + /** The id of the list item to get. */ id: Id; } +/** + * ListClient.getListItemByValues + * {@link ListClient.getListItemByValues} + */ export interface GetListItemsByValueOptions { + /** The type of list such as "boolean", "double", "text", "keyword", etc... */ type: Type; + /** The id of the list container to search for list items. */ listId: string; + /** The value to search for list items based off. */ value: string[]; } +/** + * ListClient.findList + * {@link ListClient.findListItem} + */ export interface FindListOptions { + /** The current index position to search from. */ currentIndexPosition: number; + /** A KQL string filter to find list items. */ filter: Filter; + /** How many per page to return. */ perPage: PerPage; + /** The current page number for the current find */ page: Page; + /** array of search_after terms, otherwise "undefined" if there is no search_after */ searchAfter: string[] | undefined; + /** Which field to sort on, "undefined" for no sort field */ sortField: SortFieldOrUndefined; + /** "asc" or "desc" to sort, otherwise "undefined" if there is no sort order */ sortOrder: SortOrderOrUndefined; } +/** + * ListClient.findListItem + * {@link ListClient.findListItem} + */ export interface FindListItemOptions { + /** The current index position to search from. */ currentIndexPosition: number; + /** A KQL string filter to find list items. */ filter: Filter; + /** The list id to search for the list items */ listId: ListId; + /** How many per page to return. */ perPage: PerPage; + /** The current page number for the current find */ page: Page; + /** array of search_after terms, otherwise "undefined" if there is no search_after */ searchAfter: string[] | undefined; + /** Which field to sort on, "undefined" for no sort field */ sortField: SortFieldOrUndefined; + /** "asc" or "desc" to sort, otherwise "undefined" if there is no sort order */ sortOrder: SortOrderOrUndefined; } +/** + * ListClient.searchListItemByValues + * {@link ListClient.findListItem} + */ export interface SearchListItemByValuesOptions { + /** The type of list such as "boolean", "double", "text", "keyword", etc... */ type: Type; + /** The id of the list container to search for list items. */ listId: string; + /** The value to search for list items based off. */ value: unknown[]; }