@yext/search-headless/dist/search-headless.d.ts

A library for powering UI components for Yext Search integrations

import { Unsubscribe } from '@reduxjs/toolkit';

/**
 * AdditionalHttpHeaders allows users to specify additional values for specific HTTP headers.
 *
 * @public
 **/
export declare interface AdditionalHttpHeaders {
    /** {@inheritDoc ClientSDKHeaderValues} */
    'Client-SDK'?: ClientSDKHeaderValues;
}

/**
 * An interface with address fields to use in {@link BaseFieldValueDirectAnswer.value}.
 *
 * @public
 */
export declare interface Address {
    line1?: string;
    line2?: string;
    line3?: string;
    sublocality?: string;
    city?: string;
    region?: string;
    postalCode?: string;
    extraDescription?: string;
    countryCode: string;
}

/**
 * A {@link BaseFieldValueDirectAnswer} interface with 'address' field type.
 *
 * @public
 */
export declare interface AddressDirectAnswer extends BaseFieldValueDirectAnswer<Address> {
    fieldType: EnumOrLiteral<BuiltInFieldType.Address>;
}

/**
 * Represents all results for the current vertical.
 *
 * @public
 */
export declare interface AllResultsForVertical {
    /**
     * {@inheritDoc FiltersState.facets}
     */
    facets: DisplayableFacet[];
    /**
     * The array of all results for the vertical.
     */
    results: Result[];
    /**
     * The total number of results for the vertical.
     */
    resultsCount: number;
}

/**
 * A direct answer for an android app url field.
 *
 * @public
 */
export declare interface AndroidAppUrlDirectAnswer extends BaseFieldValueDirectAnswer<string> {
    fieldType: EnumOrLiteral<BuiltInFieldType.AndroidAppURL>;
}

/**
 * A filter that the Search API applied to the search.
 *
 * @public
 */
export declare interface AppliedQueryFilter {
    /**
     * The display name of the filter key.
     *
     * @example
     * 'Job Category'
     */
    displayKey: string;
    /**
     * The value used in the filter.
     *
     * @example
     * 'Sales'
     */
    displayValue: string;
    /** The filter applied to the query results. */
    filter: FieldValueFilter;
    /** {@inheritDoc AppliedQueryFilterType} */
    type: AppliedQueryFilterType;
    /** {@inheritDoc LocationFilterDetails} */
    details?: LocationFilterDetails;
}

/**
 * Represents the type of {@link AppliedQueryFilter} applied to a search.
 *
 * @public
 */
export declare enum AppliedQueryFilterType {
    /** Indicates that a field value filter is applied based on the query. */
    FieldValue = "FIELD_VALUE",
    /** Indicates that a location filter is applied based on the query. */
    Place = "PLACE",
    /** Indicates that a search intent filter is applied based on the query. */
    Intent = "INTENT"
}

/**
 * The response of a universal or vertical autocomplete request.
 *
 * @public
 */
export declare interface AutocompleteResponse {
    /** An array of {@link AutocompleteResult}s. */
    results: AutocompleteResult[];
    /** {@inheritDoc SearchIntent} */
    inputIntents: SearchIntent[];
    /** The ID of the search query. */
    queryId?: string;
    /** A unique id which corresponds to the request. */
    uuid: string;
}

/**
 * An autocomplete suggestion.
 *
 * @public
 */
export declare interface AutocompleteResult {
    /** The value of an autocomplete suggestion. */
    value: string;
    /**
     * A filter applied to the autocomplete response.
     *
     * @remarks
     * This property is only defined for filtersearch.
     */
    filter?: FieldValueFilter;
    /**
     * The fieldId which corresponds to the AutocompleteResult value.
     *
     * @remarks
     * This property is only defined for filtersearch.
     */
    key?: string;
    /**
     * An array of substrings which overlap with the autocomplete input.
     *
     * @remarks
     * Offset indicates the index of the match, and the length indicates the number of characters of the match.
     */
    matchedSubstrings?: {
        length: number;
        offset: number;
    }[];
    /**
     * An entity that corresponds to the autocomplete result.
     *
     * @remarks
     * This property is only defined if the corresponding
     * {@link SearchParameterField.fetchEntities} field is true.
     */
    relatedItem?: Result;
    /**
     * Any vertical keys associated with a prompt.
     * This only shows up on universal autocomplete requests.
     **/
    verticalKeys?: string[];
    /**
     * {@link SearchIntent}s corresponding to the autocomplete result.
     */
    inputIntents: SearchIntent[];
}

/**
 * A service for autocomplete requests.
 *
 * @public
 */
export declare interface AutocompleteService {
    /**
     * Retrieves query suggestions for universal.
     */
    universalAutocomplete(request: UniversalAutocompleteRequest): Promise<AutocompleteResponse>;
    /**
     * Retrieves query suggestions for a vertical.
     */
    verticalAutocomplete(request: VerticalAutocompleteRequest): Promise<AutocompleteResponse>;
    /**
     * Retrieves query suggestions for filter search.
     */
    filterSearch(request: FilterSearchRequest): Promise<FilterSearchResponse>;
}

/**
 * A direct answer which was found within a document.
 *
 * @public
 */
export declare interface BaseFeaturedSnippetDirectAnswer<T = unknown> extends DirectAnswer<T> {
    /** {@inheritDoc DirectAnswerType.FeaturedSnippet} */
    type: DirectAnswerType.FeaturedSnippet;
    /** {@inheritDoc DirectAnswer.fieldType} */
    fieldType: EnumOrLiteral<BuiltInFieldType.MultiLineText | BuiltInFieldType.RichText | BuiltInFieldType.RichText_v2 | BuiltInFieldType.Html | BuiltInFieldType.Markdown>;
    /** The snippet where the direct answer was found. */
    snippet: Snippet;
}

/**
 * A direct answer where the answer came from a field from the knowledge graph.
 *
 * @public
 */
export declare interface BaseFieldValueDirectAnswer<T = unknown> extends DirectAnswer<T> {
    /** {@inheritDoc DirectAnswerType.FieldValue} */
    type: DirectAnswerType.FieldValue;
    /** The result of the direct answer. */
    value: T;
    /** The name of the entity that direct answer came from. */
    entityName: string;
    /** The field name of the direct answer. */
    fieldName: string;
    /** The field api name of the direct answer. */
    fieldApiName: string;
}

/**
 * The base configuration options for {@link SearchCore}, which includes the
 * options from {@link ServingConfig}.
 *
 * @public
 */
export declare interface BaseSearchConfig extends ServingConfig {
    /** The experience key of the search experience. */
    experienceKey: string;
    /** The locale of the search experience. */
    locale: string;
    /**
     * The version of the search experience configuration.
     *
     * @remarks
     * May be a configuration label (string) or a configuration version (number).
     *
     * @example
     * Examples: 'PRODUCTION', 42
     */
    experienceVersion?: 'STAGING' | 'PRODUCTION' | string | number;
    /** {@inheritDoc Visitor} */
    visitor?: Visitor;
    /**
     * {@inheritDoc Endpoints}
     *
     * @public
     */
    endpoints?: Endpoints;
    /**
     * Additional query params added on to every request.
     *
     * @public
     */
    additionalQueryParams?: {
        [key: string]: string | number | boolean;
    };
    /**
     * {@inheritDoc Environment}
     *
     * @public
     */
    environment?: Environment;
    /**
     * {@inheritDoc CloudRegion}
     *
     * @public
     */
    cloudRegion?: CloudRegion;
}

/**
 * An interface representing a range of values of type T.
 *
 * @public
 */
export declare interface BoundedRange<T> {
    /**
     * The minimum value bounding the range.
     */
    min?: RangeBoundary<T>;
    /**
     * The maximum value bounding the range.
     */
    max?: RangeBoundary<T>;
}

/**
 * Possible built-in field types for {@link DirectAnswer.fieldType}.
 *
 * @public
 */
export declare enum BuiltInFieldType {
    URL = "url",
    ComplexURL = "complex_url",
    IOSAppURL = "ios_app_url",
    AndroidAppURL = "android_app_url",
    FacebookURL = "facebook_url",
    Email = "email",
    InstagramHandle = "instagram_handle",
    TwitterHandle = "twitter_handle",
    Phone = "phone",
    Address = "address",
    Hours = "hours",
    Decimal = "decimal",
    Integer = "integer",
    SingleLineText = "single_line_text",
    RichText = "rich_text",
    MultiLineText = "multi_line_text",
    RichText_v2 = "rich_text_v2",
    Html = "html",
    Markdown = "markdown"
}

/**
 * Additional agents and their versions used to create the Search experience. The information for these
 * agents is added to the Client-SDK HTTP header along with that of the ANSWERS_CORE agent.
 *
 * @public
 */
export declare interface ClientSDKHeaderValues {
    /** A mapping of the additional agents that are part of the Client-SDK to their versions. */
    [agent: string]: string | undefined;
    /**
     * The ANSWERS_CORE agent should not be supplied. Instead, it will be automatically added to the
     * header and populated with the version of Search Core being used.
     */
    ANSWERS_CORE?: never;
}

/**
 * Defines the cloud choice of the API domains.
 *
 * @public
 */
export declare enum CloudChoice {
    GLOBAL_MULTI = "GLOBAL-MULTI",
    GLOBAL_GCP = "GLOBAL-GCP"
}

/**
 * Defines the cloud region of the API domains.
 *
 * @public
 */
export declare enum CloudRegion {
    US = "us",
    EU = "eu"
}

/**
 * Creates a {@link StaticFilter} by applying the specified {@link FilterCombinator}
 * to the two static filters. Throws an error if an attempt is made to combine a
 * conjunction static filter using {@link FilterCombinator.OR}.
 *
 * @param filterA - The first static filter to be combined
 * @param filterB - The second static filter to be combined
 * @param combinator - Specifies how the two static filters should be joined
 * @returns The newly created {@link StaticFilter}
 *
 * @public
 */
export declare function combineStaticFilters(filterA: StaticFilter, filterB: StaticFilter, combinator: FilterCombinator): StaticFilter;

/**
 * The shape of a {@link BuiltInFieldType.ComplexURL} DirectAnswer value
 *
 * @public
 */
export declare interface ComplexURL {
    url: string;
    displayUrl?: string;
    preferDisplayUrl: boolean;
}

/**
 * A direct answer for a complex url field.
 *
 * @public
 */
export declare interface ComplexUrlDirectAnswer extends BaseFieldValueDirectAnswer<ComplexURL> {
    fieldType: EnumOrLiteral<BuiltInFieldType.ComplexURL>;
}

/**
 * A static filter composed by combining other static filters with the
 * logical AND operator.
 *
 * @public
 */
export declare interface ConjunctionStaticFilter {
    /** {@inheritDoc FieldValueStaticFilter.kind} */
    kind: 'conjunction';
    /** {@inheritDoc FilterCombinator.AND} */
    combinator: FilterCombinator.AND;
    /** {@inheritDoc DisjunctionStaticFilter.filters} */
    filters: StaticFilter[];
}

/**
 * Used to trigger Search
 * {@link https://hitchhikers.yext.com/tracks/answers-advanced/ans302-query-rules/ | Query Rules}.
 *
 * @remarks
 * May be any valid JSON object
 *
 * @public
 */
export declare type Context = any;

/**
 * Creates a {@link StaticFilter} that matches all results where the
 * given field value falls in a specific Date {@link BoundedRange}.
 *
 * @param fieldId - The comparison field's identifier
 * @param range - The acceptable date range
 * @returns The newly created static filter for the field value range
 *
 * @public
 */
export declare function createDateRangeStaticFilter(fieldId: string, range: BoundedRange<Date>): StaticFilter;

/**
 * Creates a {@link FieldValueStaticFilter} that ensures all results will match
 * a specific field value.
 *
 * @param fieldId - The comparison field's identifier
 * @param value - The value to match
 * @returns The newly created {@link FieldValueStaticFilter} for the field value
 *
 * @public
 */
export declare function createEqualsStaticFilter(fieldId: string, value: string | number | boolean): FieldValueStaticFilter;

/**
 * Creates a {@link FieldValueStaticFilter} that matches all results within a certain radius
 * of the given position.
 *
 * @param position - The position and radius
 * @returns The newly created {@link FieldValueStaticFilter} for the radius of the position
 *
 * @public
 */
export declare function createNearMeStaticFilter(position: NearFilterValue): FieldValueStaticFilter;

/**
 * Creates a {@link StaticFilter} that matches all results where the
 * given field value falls in a specific number {@link BoundedRange}.
 *
 * @param fieldId - The comparison field's identifier
 * @param range - The acceptable number range
 * @returns The newly created static filter for the field value range
 *
 * @public
 */
export declare function createNumberRangeStaticFilter(fieldId: string, range: BoundedRange<number>): StaticFilter;

/**
 * An interface for a day's hours to use in {@link BaseFieldValueDirectAnswer.value}.
 *
 * @public
 */
export declare interface DayHour {
    openIntervals?: Interval[];
    isClosed?: boolean;
}

/**
 * A direct answer for a decimal field, which is a number represented using a string.
 *
 * @public
 */
export declare interface DecimalDirectAnswer extends BaseFieldValueDirectAnswer<string | string[]> {
    fieldType: EnumOrLiteral<BuiltInFieldType.Decimal>;
}

/**
 * The headlessId automatically given to the first SearchHeadless instance created.
 *
 * @public
 */
export declare const DEFAULT_HEADLESS_ID = "main";

/**
 * A direct answer to a search.
 *
 * @public
 */
export declare interface DirectAnswer<T = unknown> {
    /** The {@link DirectAnswerType}. */
    type: DirectAnswerType;
    /**
     * The value of the direct answer.
     *
     * @remarks
     * A value will not be present if the {@link DirectAnswer."type"} is 'FEATURED_SNIPPET'
     * and {@link DirectAnswer.fieldType} is 'rich_text', 'markdown', 'html' or 'rich_text_v2'.
     */
    value?: T;
    /** The entity associated with the direct answer. */
    relatedResult: Result;
    /** The vertical key of the direct answer. */
    verticalKey: string;
    /** The field type of the direct answer. */
    fieldType: EnumOrLiteral<BuiltInFieldType> | 'unknown';
}

/**
 * Maintains the direct answer associated with the latest search.
 *
 * @public
 */
export declare interface DirectAnswerState {
    /**
     * The data for the direct answer. The type of the data is determined by the
     * Search API based on whether the answer was found within a document or was a
     * field value in the knowledge graph.
     */
    result?: FeaturedSnippetDirectAnswer | FieldValueDirectAnswer;
}

/**
 * Represents the type of direct answer.
 *
 * @public
 */
export declare enum DirectAnswerType {
    /** Indicates that the DirectAnswer is a {@link FeaturedSnippetDirectAnswer}. */
    FeaturedSnippet = "FEATURED_SNIPPET",
    /** Indicates that the DirectAnswer is a {@link FieldValueDirectAnswer}. */
    FieldValue = "FIELD_VALUE"
}

/**
 * The direction of a sort.
 *
 * @public
 */
export declare enum Direction {
    /**
     *  An ascending sort
     *
     * @remarks
     * For numbers this sort is low to high. For text it is alphabetical. For dates it is chronological order.
     */
    Ascending = "ASC",
    /**
     * A descending soft
     *
     * @remarks
     * For numbers this sort is high to low. For text it is reverse alphabetical. For dates it is reverse
     * chronological order.
     */
    Descending = "DESC"
}

/**
 * A static filter composed by combining filters with the logical OR
 * operator. The combined filters can either be field value filters or
 * other disjunction filters.
 *
 * @public
 */
export declare interface DisjunctionStaticFilter {
    /** {@inheritDoc FieldValueStaticFilter.kind} */
    kind: 'disjunction';
    /** {@inheritDoc FilterCombinator.OR} */
    combinator: FilterCombinator.OR;
    /** The filters to combine together. */
    filters: (DisjunctionStaticFilter | FieldValueStaticFilter)[];
}

/**
 * A {@link Facet} which contains extra fields meant to be displayed to the end user.
 *
 * @public
 */
export declare interface DisplayableFacet extends Facet {
    /** An array of {@link DisplayableFacetOption} */
    options: DisplayableFacetOption[];
    /** The name of the facet which is meant to be displayed to the user. */
    displayName: string;
}

/**
 * A {@link FacetOption} with extra data meant to be displayed to the end user.
 *
 * @public
 */
export declare interface DisplayableFacetOption extends FacetOption {
    /** The name of the facet option which is meant  to be displayed to the end user. */
    displayName: string;
    /** The number of results associated with this facet option. */
    count: number;
    /** Whether or not the filter is selected in the search results. */
    selected: boolean;
}

/**
 * Details about the document and the document search algorithm
 *
 * @public
 */
export declare interface DocumentResult {
    /** The score calculated from whatever document search strategy was used. */
    documentScore: number;
    /** All the relevant segments extracted from the document. */
    segments: Segment[];
}

/**
 * A {@link BaseFieldValueDirectAnswer} interface with 'email' field type.
 *
 * @public
 */
export declare interface EmailDirectAnswer extends BaseFieldValueDirectAnswer<string[]> {
    fieldType: EnumOrLiteral<BuiltInFieldType.Email>;
}

/**
 * Overrides for the URLs which are used when making requests to the Search API.
 *
 * @public
 */
export declare interface Endpoints {
    universalSearch?: string;
    verticalSearch?: string;
    questionSubmission?: string;
    status?: string;
    universalAutocomplete?: string;
    verticalAutocomplete?: string;
    filterSearch?: string;
    generativeDirectAnswer?: string;
}

/**
 * Produces a union type from the enum passed as a generic which consists of the enum values
 * and the string literals of the enum.
 *
 * @public
 */
export declare type EnumOrLiteral<T extends string> = T | `${T}`;

/**
 * Defines the environment of the API domains.
 *
 * @public
 */
export declare enum Environment {
    PROD = "prod",
    SANDBOX = "sbx",
    /** For internal development only */
    QA = "qa",
    /** For internal development only */
    DEV = "dev"
}

/**
 * Identifier for the type of error causing the failure.
 *
 * @public
 */
export declare enum ErrorType {
    /** A timeout error from the server. */
    Timeout = "TIMEOUT",
    /** An internal error from the API backend. */
    BackendError = "BACKEND_ERROR",
    /** An invalid config from the request. */
    InvalidConfig = "INVALID_CONFIG",
    /** An invalid query from the request. */
    InvalidQuery = "INVALID_QUERY"
}

/**
 * A direct answer for a facebook url field.
 *
 * @public
 */
export declare interface FacebookUrlDirectAnswer extends BaseFieldValueDirectAnswer<string> {
    fieldType: EnumOrLiteral<BuiltInFieldType.FacebookURL>;
}

/**
 * Represents dynamic filter options for the Search API.
 *
 * @public
 */
export declare interface Facet {
    /** The associated fieldId. */
    fieldId: string;
    /**
     * An array of {@link FacetOption}
     *
     * @remarks
     * To indicate that a facet should be disabled, supply an empty array
     */
    options: FacetOption[];
}

/**
 * A filter associated with the facet.
 *
 * @public
 */
export declare interface FacetOption extends Omit<FieldValueFilter, 'fieldId'> {
    /**
     * The value to compare.
     *
     * @example
     * 'Sales'
     */
    value: Exclude<FieldValueFilter['value'], NearFilterValue>;
}

/**
 * Error information from when a vertical fails to return results.
 *
 * @public
 */
export declare interface FailedVertical {
    /** The vertical key associated with the failed vertical. */
    verticalKey: string;
    /** {@inheritDoc ErrorType} */
    errorType: ErrorType;
    /** The duration of the query in milliseconds. */
    queryDurationMillis: number;
    /** Detailed information about the error. */
    details: {
        /**
         * An HTTP response status code indicating the completion status of
         * the request.
         */
        responseCode: number;
        /** A message explaining the error. */
        description: string;
    };
}

/**
 * All possible built-in {@link BaseFeaturedSnippetDirectAnswer} interfaces.
 *
 * @public
 */
export declare type FeaturedSnippetDirectAnswer = MultiLineTextSnippetDirectAnswer | RichTextSnippetDirectAnswer | RichTextV2SnippetDirectAnswer | HTMLSnippetDirectAnswer | MarkdownSnippetDirectAnswer;

/**
 * Possible built-in and custom {@link BaseFieldValueDirectAnswer} interfaces.
 *
 * @public
 */
export declare type FieldValueDirectAnswer = UnknownFieldValueDirectAnswer | TextDirectAnswer | UrlDirectAnswer | RichTextDirectAnswer | DecimalDirectAnswer | FacebookUrlDirectAnswer | InstagramHandleDirectAnswer | TwitterHandleDirectAnswer | IosAppUrlDirectAnswer | AndroidAppUrlDirectAnswer | ComplexUrlDirectAnswer | IntegerDirectAnswer | PhoneDirectAnswer | EmailDirectAnswer | AddressDirectAnswer | HoursDirectAnswer;

/**
 * Represents a filter which compares values to a single field.
 *
 * @public
 */
export declare interface FieldValueFilter {
    /**
     * The fieldId to apply the filter against.
     *
     * @example
     * 'c_jobCategory'
     */
    fieldId: string;
    /** {@inheritDoc Matcher} */
    matcher: Matcher;
    /**
     * The value to compare.
     *
     * @example
     * 'Sales'
     */
    value: string | number | boolean | NearFilterValue | NumberRangeValue;
}

/**
 * A {@link FieldValueFilter} with the kind of filter specified
 * to discriminate between static filter types.
 *
 * @public
 */
export declare interface FieldValueStaticFilter extends FieldValueFilter {
    /** The kind of static filter. */
    kind: 'fieldValue';
}

/**
 * Indicates how child filters in a {@link StaticFilter} should be combined.
 *
 * @public
 */
export declare enum FilterCombinator {
    /** Indicates that filters should be combined with a logical AND. */
    AND = "$and",
    /** Indicates that filters should be combined with a logical OR. */
    OR = "$or"
}

/**
 * Options for a filtersearch request.
 *
 * @public
 */
export declare interface FilterSearchRequest extends SearchRequest {
    /** {@inheritDoc UniversalAutocompleteRequest.input} */
    input: string;
    /** {@inheritDoc UniversalAutocompleteRequest.sessionTrackingEnabled} */
    sessionTrackingEnabled?: boolean;
    /** {@inheritDoc VerticalAutocompleteRequest.verticalKey} */
    verticalKey: string;
    /** Determines whether or not the results of the {@link FilterSearchResponse} are separated by field. */
    sectioned: boolean;
    /** An array of {@link SearchParameterField}. */
    fields: SearchParameterField[];
    /** An array of field value filters that should be excluded from filter search results. */
    excluded?: FieldValueFilter[];
}

/**
 * The response of a filtersearch request.
 *
 * @public
 */
export declare interface FilterSearchResponse {
    /**
     * Represents autocomplete results separated by field.
     *
     * @remarks
     * If sectioned is true, the matching filters will be returned in a separate section per field.
     * By default, they are all returned in the same section.
     */
    sections: {
        /** A display label for the field.
         *
         * @remarks
         * When sectioned is false, there's no label since all filters wil be returned in same section.
         */
        label?: string;
        /** An array of {@link AutocompleteResult}s. */
        results: AutocompleteResult[];
    }[];
    /** ID of the account associated with this Search experience. */
    businessId?: string;
    /** {@inheritDoc AutocompleteResponse.queryId} */
    queryId?: string;
    /** A unique id which corresponds to the request. */
    uuid: string;
}

/**
 * Maintains the current state of facets and filters in the application.
 *
 * @public
 */
export declare interface FiltersState {
    /**
     * The collection of possible static filters that can be applied to the
     * search results and whether each of them is currently selected.
     */
    static?: SelectableStaticFilter[];
    /**
     * The dynamic collection of facets that can be applied to filter the search
     * results and whether each of them is currently selected.
     */
    facets?: DisplayableFacet[];
}

/**
 * Options which can be specified for a generative direct answer request.
 *
 * @public
 */
export declare interface GenerativeDirectAnswerRequest extends SearchRequest {
    /** The ID of the search request. */
    searchId: string;
    /** The text of the user-written query that prompted Search results. */
    searchTerm: string;
    /** The complete set of Search Results */
    results: VerticalResults[];
}

/**
 * A representation of a generative direct answer response.
 *
 * @public
 */
export declare interface GenerativeDirectAnswerResponse {
    /** The text of the final generated response. */
    directAnswer: string;
    /** A string representing whether there was a result found within the given invocation. */
    resultStatus: string;
    /** An array of uids from the relevant {@link Result.rawData} that were used to form the directAnswer. */
    citations: string[];
}

/**
 * A service for generative direct answer requests.
 *
 * @public
 */
export declare interface GenerativeDirectAnswerService {
    /**
     * Generates an answer to a search query.
     */
    generateAnswer(request: GenerativeDirectAnswerRequest): Promise<GenerativeDirectAnswerResponse>;
}

/**
 * Maintains the data for the latest generative direct answer.
 *
 * @public
 */
export declare interface GenerativeDirectAnswerState {
    /**
     * Whether the AI generated answer is currently loading or has finished loading.
     */
    isLoading?: boolean;
    /**
     * The generative direct answer response.
     */
    response?: GenerativeDirectAnswerResponse;
}

/**
 * The configuration for a SearchHeadless instance.
 *
 * @public
 */
export declare type HeadlessConfig = SearchConfig & {
    /**
     * The ID of the SearchHeadless instance.
     *
     * @remarks
     * Must be different from {@link DEFAULT_HEADLESS_ID}.
     */
    headlessId?: string;
    /**
     * The verticalKey associated with the vertical to manage. If none is provided,
     * Search Headless will manage universal search.
     */
    verticalKey?: string;
};

/**
 * A mapping of fields to the values emphasized by the Search API.
 *
 * @remarks
 * Only fields that have been marked as highlighted will be present - which may not be
 * all fields of the corresponding {@link Result}'s rawData.
 * Fields that are present will match the rawData's structure and order.
 *
 * @example
 * If a user searches for 'apple', the API will likely match fields that contain
 * the word 'apple'.
 *
 * ```js
 * {
 *   description: {
 *     value: 'likes apple pie and green apples',
 *     matchedSubstrings: [
 *       { offset: 6, length: 5 },
 *       { offset: 26, length: 5 }
 *     ]
 *   },
 *   c_favoriteFruits: [
 *     {
 *       apples: [
 *         {
 *           value: 'Granny Smith',
 *           matchedSubstrings: []
 *         },
 *         {
 *           value: 'Upton Pyne Apple',
 *           matchedSubstrings: [{ offset: 11, length: 5}]
 *         }
 *       ],
 *       pears: [
 *         {
 *           value: 'Callery Pear',
 *           matchedSubstrings: []
 *         }
 *       ]
 *     }
 *   ]
 * }
 * ```
 *
 * @public
 */
export declare type HighlightedFields = {
    /**
     * A mapping of a field to either an array of HighlightedFields, HighlightedFields for
     * this field's subfields, or a {@link HighlightedValue} for the field.
     *
     * @remarks
     * HighlightedFields is an object of arbitrary shape which contains {@link HighlightedValue} objects.
     */
    [fieldId: string]: HighlightedValue | HighlightedValue[] | HighlightedFields | HighlightedFields[];
};

/**
 * A field value and its substring matches as emphasized by the Search API.
 *
 * @public
 */
export declare interface HighlightedValue {
    /**
     * The value of the field which should be highlighted.
     *
     * @remarks
     * No formatting is applied to this value. This is simply the value that
     * the Search API determined should be highlighted.
     */
    value: string;
    /**
     * An array of substring matches which correspond to the highlighting.
     *
     * @remarks
     * Offset indicates the index of the match, and the length indicates the number of characters of the match.
     *
     * @example
     * A user may search for 'Yext', and the result may include the value
     * 'Yext is a search company'. The matched substrings would correspond
     * to 'Yext' and the matchedSubstrings array would be: `[{ length: 4, offset: 0 }]`
     */
    matchedSubstrings: {
        length: number;
        offset: number;
    }[];
}

/**
 * An interface for holiday hours to use in {@link BaseFieldValueDirectAnswer.value}.
 *
 * @public
 */
export declare interface HolidayHours {
    date: string;
    openIntervals?: Interval[];
    isClosed?: boolean;
    isRegularHours?: boolean;
}

/**
 * An interface for hours fields to use in {@link BaseFieldValueDirectAnswer.value}.
 *
 * @public
 */
export declare interface Hours {
    monday?: DayHour;
    tuesday?: DayHour;
    wednesday?: DayHour;
    thursday?: DayHour;
    friday?: DayHour;
    saturday?: DayHour;
    sunday?: DayHour;
    holidayHours?: HolidayHours[];
    reopenDate?: string;
}

/**
 * A {@link BaseFieldValueDirectAnswer} interface with 'hours' field type.
 *
 * @public
 */
export declare interface HoursDirectAnswer extends BaseFieldValueDirectAnswer<Hours | Hours[]> {
    fieldType: EnumOrLiteral<BuiltInFieldType.Hours>;
}

/**
 * A {@link BaseFeaturedSnippetDirectAnswer} with 'html' field type.
 * "value" field is omitted for featured snippet direct answer of this field type.
 *
 * @public
 */
export declare interface HTMLSnippetDirectAnswer extends Omit<BaseFeaturedSnippetDirectAnswer<string>, 'value'> {
    /** {@inheritDoc DirectAnswer.fieldType} */
    fieldType: EnumOrLiteral<BuiltInFieldType.Html>;
}

/**
 * Assigns numeric IDs to every http request and the corresponding response
 * through {@link SearchCore}. This helps track the received order of requests
 * and responses. {@link SearchHeadless} uses it to ensure dispatch events for
 * state updates are triggered with up-to-date responses (e.g. if the newly received
 * response has a higher ID number than the recorded received response).
 */
declare class HttpManager {
    private latestRequestIds;
    private latestResponseIds;
    constructor();
    updateRequestId(requestName: ServiceType): number;
    setResponseId(responseName: ServiceType, responseId: number): void;
    getLatestResponseId(responseName: ServiceType): number;
    /**
     * Update the latest saved response id of the given service type if
     * the given request id is newer than the latest saved response id.
     *
     * @param requestName - the request type.
     * @param requestId - the request id of a received response.
     *
     * @returns Whether the response of the given request id is the latest response.
     */
    processRequestId(requestName: ServiceType, requestId: number): boolean;
}

/**
 * A direct answer for an instagram handle field.
 *
 * @public
 */
export declare interface InstagramHandleDirectAnswer extends BaseFieldValueDirectAnswer<string> {
    fieldType: EnumOrLiteral<BuiltInFieldType.InstagramHandle>;
}

/**
 * A direct answer for an integer field.
 *
 * @remarks
 * `IntegerDirectAnswer`s are only used for built in number fields.
 * Custom number fields use {@link DecimalDirectAnswer} instead.
 *
 * @public
 */
export declare interface IntegerDirectAnswer extends BaseFieldValueDirectAnswer<number> {
    fieldType: EnumOrLiteral<BuiltInFieldType.Integer>;
}

/**
 * An interface for a time interval to use in {@link BaseFieldValueDirectAnswer.value}.
 *
 * @public
 */
export declare interface Interval {
    start?: string;
    end?: string;
}

/**
 * A direct answer for an iOS app url field.
 *
 * @public
 */
export declare interface IosAppUrlDirectAnswer extends BaseFieldValueDirectAnswer<string> {
    fieldType: EnumOrLiteral<BuiltInFieldType.IOSAppURL>;
}

/**
 * Checks if the searchTerm is a case-insensitive, Levenshtein match for the value.
 *
 * @param value - The string to compare against
 * @param searchTerm - The term being searched for
 * @returns Whether or not the searchTerm is a substring of or a close Levenshtein match
 *          for the value
 *
 * @public
 */
declare function isCloseMatch(value: string, searchTerm: string): boolean;

/**
 * The latitude and longitude of the user making the request.
 * Used to bias the results.
 *
 * @remarks
 * If omitted from a request, Yext will attempt to determine the location.
 *
 * @public
 */
export declare interface LatLong {
    /**
     * Latitude formatted as a decimal degree number.
     *
     * @example
     * `40.741895`
     */
    latitude: number;
    /**
     * Longitude formatted as a decimal degree number.
     *
     * @example
     * `-73.989308`
     */
    longitude: number;
}

/**
 * Information about the user's location.
 *
 * @public
 */
export declare interface LocationBias {
    /** The location's latitude. */
    latitude: number;
    /** The location's longitude. */
    longitude: number;
    /**
     * The name of the location.
     *
     * @example
     * Arlington, Virginia.
     */
    displayName: string;
    /** {@inheritDoc LocationBiasMethod} */
    method: LocationBiasMethod;
}

/**
 * The method used to determine the location.
 *
 * @public
 */
export declare enum LocationBiasMethod {
    /** Location was determined by IP address. */
    Ip = "IP",
    /**
     * Location was supplied by the user's device.
     *
     * @remarks
     * This location bias method is set when a location is supplied in search requests.
     * */
    Device = "DEVICE",
    /**
     * Location is unknown.
     */
    Unknown = "UNKNOWN"
}

/**
 * Location boundaries for a filter with "Place" for its {@link AppliedQueryFilterType}.
 * (e.g. boundary for a locality or region specific location filter)
 *
 * @public
 */
export declare interface LocationBoundingBox {
    /** The location's highest latitude degree. */
    maxLatitude: number;
    /** The location's highest longitude degree. */
    maxLongitude: number;
    /** The location's lowest latitude degree. */
    minLatitude: number;
    /** The location's lowest longitude degree. */
    minLongitude: number;
}

/**
 * Additional details relevant to the filter with "PLACE" for its {@link AppliedQueryFilterType}.
 *
 * @public
 */
export declare interface LocationFilterDetails {
    /** The location's latitude. */
    latitude: number;
    /** The location's longitude. */
    longitude: number;
    /** The location's name. */
    placeName: string;
    /** The location's classification (e.g. locality, region, address). */
    featureTypes: string[];
    /** The location's coordinate boundaries. */
    boundingBox?: LocationBoundingBox;
}

/**
 * Maintains the user's location, if given, or the inferred location, that is
 * used to bias search results.
 *
 * @public
 */
export declare interface LocationState {
    /**
     * The geographical location bias used in the search, returned from the
     * Search API.
     */
    locationBias?: LocationBias;
    /**
     * The latitude and longitude of the user making the request. Used to bias
     * the results.
     */
    userLocation?: LatLong;
}

/**
 * The start limit of {@link NumberRangeValue}.
 *
 * @public
 */
export declare interface LowerNumberRangeLimit {
    /** {@link Matcher} for the start limit */
    matcher: Matcher.GreaterThan | Matcher.GreaterThanOrEqualTo;
    /** Value of the limit. */
    value: number;
}

/**
 * A {@link BaseFeaturedSnippetDirectAnswer} with 'markdown' field type.
 * "value" field is omitted for featured snippet direct answer of this field type.
 *
 * @public
 */
export declare interface MarkdownSnippetDirectAnswer extends Omit<BaseFeaturedSnippetDirectAnswer<string>, 'value'> {
    /** {@inheritDoc DirectAnswer.fieldType} */
    fieldType: EnumOrLiteral<BuiltInFieldType.Markdown>;
}

/**
 * A Matcher is a filtering operation.
 *
 * @public
 */
export declare enum Matcher {
    /**
     * An equals comparison.
     *
     * @remarks
     * Compatible with all field types.
     */
    Equals = "$eq",
    /**
     * A not equals comparison.
     *
     * @remarks
     * Compatible with all field types.
     */
    NotEquals = "!$eq",
    /**
     * A less than comparison.
     *
     * @remarks
     * Compatible with integer, float, date, datetime, and time fields.
     */
    LessThan = "$lt",
    /**
     * A less than or equal to comparison.
     *
     * @remarks
     * Compatible with integer, float, date, datetime, and time fields.
     */
    LessThanOrEqualTo = "$le",
    /**
     * A greater than comparison.
     *
     * @remarks
     * Compatible with integer, float, date, datetime, and time fields.
     */
    GreaterThan = "$gt",
    /**
     * A greater than or equal to comparison.
     *
     * @remarks
     * Compatible with integer, float, date, datetime, and time fields.
     */
    GreaterThanOrEqualTo = "$ge",
    /**
     * A comparison of whether an entity is within a certain radius of a certain location.
     *
     * @remarks
     * Only compatible with the builtin.location field.
     */
    Near = "$near",
    /**
     * A limitation of the dataset to a range of values.
     *
     * @remarks
     * Compatible with integer and float.
     */
    Between = "$between"
}

/**
 * Maintains the metadata for Search Headless.
 *
 * @public
 */
export declare interface MetaState {
    /**
     * A JSON object used for passing data to and triggering Search
     * {@link https://hitchhikers.yext.com/tracks/answers-advanced/ans302-query-rules/ | Query Rules}.
     */
    context?: Context;
    /**
     * The URL of the referring page (the page that directed to the current page from
     * which the request was made).
     */
    referrerPageUrl?: string;
    /**
     * A unique id which corresponds to the latest request/response.
     */
    uuid?: string;
    /**
     * Indicates the type of search that Search Headless is managing.
     */
    searchType: SearchType;
    /**
     * Indicates the key of the experience that Search Headless is managing.
     * Should not be adjusted after initialization.
     */
    experienceKey?: string;
    /**
     * Indicates the language of the search that Search Headless is managing.
     * Should not be adjusted after initialization.
     */
    locale?: string;
}

/**
 * A {@link BaseFeaturedSnippetDirectAnswer} with 'multi_line_text' field type.
 *
 * @public
 */
export declare interface MultiLineTextSnippetDirectAnswer extends BaseFeaturedSnippetDirectAnswer<string> {
    /** The value of the direct answer. */
    value: string;
    /** {@inheritDoc DirectAnswer.fieldType} */
    fieldType: EnumOrLiteral<BuiltInFieldType.MultiLineText>;
}

/**
 * A filter value for a filter with a $near {@link Matcher}.
 *
 * @public
 */
export declare interface NearFilterValue {
    /** The radius (in meters) around the latitude and longitude. */
    radius: number;
    /** The latitude of the location. */
    lat: number;
    /** The longitude of the location. */
    lng: number;
}

/**
 * A filter value for a filter with a $between {@link Matcher}.
 *
 * @public
 */
export declare interface NumberRangeValue {
    /** Start limit of the number range value. */
    start?: LowerNumberRangeLimit;
    /** End limit of the number range value. */
    end?: UpperNumberRangeLimit;
}

/**
 * The overall shape of the redux state tree, with each key value pair of
 * headlessId to {@link State} representing a single SearchHeadless instance.
 *
 * @public
 */
export declare interface ParentState {
    /**
     * A mapping of the ID of a SearchHeadless instance to its {@link State}.
     */
    [headlessId: string]: State;
}

/**
 * A {@link BaseFieldValueDirectAnswer} interface with phone value.
 *
 * @public
 */
export declare interface PhoneDirectAnswer extends BaseFieldValueDirectAnswer<string> {
    fieldType: BuiltInFieldType.Phone;
}

/**
 * Supplies a new instance of {@link SearchHeadless}, using the provided configuration.
 *
 * @param config - The apiKey, experienceKey, etc. needed to set up a front-end Search
 *                 experience.
 * @returns The newly created instance of {@link SearchHeadless}
 *
 * @public
 */
export declare function provideHeadless(config: HeadlessConfig): SearchHeadless;

/**
 * Supplies a new instance of {@link SearchHeadless}, using the provided configuration,
 * and accepts additional HTTP headers to pass with API requests.
 *
 * @param config - The apiKey, experienceKey, etc. needed to set up a front-end Search
 *                 experience
 * @param additionalHttpHeaders - Additional value for specific HTTP headers
 * @returns The newly created instance of {@link SearchHeadless}
 *
 * @internal
 */
export declare function provideHeadless(config: HeadlessConfig, additionalHttpHeaders: AdditionalHttpHeaders): SearchHeadless;

/**
 * Data returned from the Search query rules system.
 *
 * @public
 */
export declare interface QueryRulesActionsData {
    /**
     * The unique identifier for this query rule.
     */
    key: string;
    /**
     * The data returned from the query rule.
     */
    data?: Record<string, unknown>;
    /**
     * Any errors returned from the query rule.
     */
    errors?: {
        /**
         * The unique identifier of the function invocation that resulted in this error.
         */
        uuid: string;
        /**
         * The type of the error.
         */
        type: string;
        /**
         * A message describing the error.
         */
        message?: string;
    }[];
}

/**
 * Maintains the data from the triggered query rules.
 *
 * @public
 */
export declare interface QueryRulesState {
    /**
     * Any actions triggered by meeting criteria for query rules.
     */
    actions: QueryRulesActionsData[];
}

/**
 * The source of the search request.
 *
 * @public
 */
export declare enum QuerySource {
    /**
     * Indicates that the query was initiated from a standard Search integration.
     */
    Standard = "STANDARD",
    /**
     * Indicates that the query was initiated from a Search Overlay.
     */
    Overlay = "OVERLAY",
    /**
     * Indicates that the query was initiated from visual autocomplete.
     */
    Autocomplete = "AUTOCOMPLETE"
}

/**
 * Maintains the latest query and its associated data.
 *
 * @public
 */
export declare interface QueryState {
    /**
     * The user input used for the next search query.
     */
    input?: string;
    /**
     * The ID of the query from the latest search.
     */
    queryId?: string;
    /**
     * How the query was triggered (besides user input).
     */
    queryTrigger?: QueryTrigger;
    /**
     * The source of the query (from a standard Search integration, a Search
     * overlay, or from visual autocomplete).
     */
    querySource?: QuerySource;
    /**
     * The query of the most recent search.
     */
    mostRecentSearch?: string;
    /**
     * The computed intents of the mostRecentSearch, as returned by the Search API.
     */
    searchIntents?: SearchIntent[];
    /**
     * Whether the next query represents a pagination - in which case queryId will be maintained
     */
    isPagination?: boolean;
}

/**
 * Describes the ways a search can be executed besides user input.
 *
 * @remarks
 * Used for search analytics. If a user supplied the search query, do not include a QueryTrigger.
 *
 * @example
 * A Search site may be configured to perform a search for 'What services do you offer?' when the page
 * loads. Because that query is a default query rather than a user-supplied query, the Initialize QueryTrigger
 * should be included in the request.
 *
 * @public
 */
export declare enum QueryTrigger {
    /** Indicates that the query was triggered by a default initial search. */
    Initialize = "initialize",
    /** Indicates that the query was suggested by a {@link SpellCheck} response. */
    Suggest = "suggest"
}

/**
 * Options for a QuestionSubmission request.
 *
 * @public
 */
export declare interface QuestionSubmissionRequest extends SearchRequest {
    /** The email of the user that is submitting the question. */
    email: string;
    /** The ID of the entity to associate with the question. */
    entityId: string;
    /** The name of the user. */
    name: string;
    /** The question. */
    questionText: string;
    /** Additional information about the question. */
    questionDescription?: string;
    /** Enables session tracking. */
    sessionTrackingEnabled?: boolean;
}

/**
 * A representation of a question submission response.
 *
 * @public
 */
export declare interface QuestionSubmissionResponse {
    /** A unique id which corresponds to the request. */
    uuid: string;
}

/**
 * Submits a custom question to the Search API.
 *
 * @public
 */
export declare interface QuestionSubmissionService {
    /**
     * Submits a question to be answered.
     *
     * @param request - The question, as well as the contact info of the submitter.
     */
    submitQuestion(request: QuestionSubmissionRequest): Promise<QuestionSubmissionResponse>;
}

/**
 * A boundary for a {@link BoundedRange} of type T.
 *
 * @public
 */
export declare interface RangeBoundary<T> {
    /**
     * The value of the boundary.
     */
    value: T;
    /**
     * Whether or not the range includes the boundary value.
     */
    inclusive: boolean;
}

/**
 * An individual search result.
 *
 * @public
 */
export declare interface Result<T = Record<string, unknown>> {
    /** Raw entity profile data in the shape of key-value pairs, or as an array of key-value pairs. */
    rawData: T;
    /** {@inheritDoc Source} */
    source: Source;
    /** The index of the result among the other results in the search. */
    index?: number;
    /** The name of the result. */
    name?: string;
    /** A description of the result. */
    description?: string;
    /** A hyperlink associated with the result. */
    link?: string;
    /** The result ID which depends on the Result Source. */
    id?: string;
    /** The distance from the user to the result in meters. */
    distance?: number;
    /**
     * The distance from a {@link AppliedQueryFilter} location to the result in meters.
     *
     * @remarks
     * The filter may be an inferred from the search query, or it may be specified
     * explicitly through a facet or static filter on a {@link VerticalSearchRequest}.
     *
     * @example
     * If a user searches for 'Offices in New York' and the VerticalResults contain an
     * `AppliedQueryFilter` for 'New York', the distanceFromFilter value will be from
     * the search result to 'New York'.
     */
    distanceFromFilter?: number;
    /** The {@link HighlightedFields | highlighted fields} emphasized by the api. */
    highlightedFields?: HighlightedFields;
    /** The entity type of the result. */
    entityType?: string;
    /** A relevant segment associated with the result. Present for document verticals grouped by
     * Segment. */
    segment?: Segment;
    /**
     * A relevant document associated with the result. Present for document verticals grouped by
     * Document.
     */
    document?: DocumentResult;
    /**
     * All relevant documents associated with the result. Present for document verticals grouped by
     * Entity.
     */
    documents?: DocumentResult[];
}

/**
 * A direct answer for a rich text field.
 *
 * @public
 */
export declare interface RichTextDirectAnswer extends BaseFieldValueDirectAnswer<string | string[]> {
    fieldType: EnumOrLiteral<BuiltInFieldType.RichText>;
}

/**
 * A {@link BaseFeaturedSnippetDirectAnswer} with 'rich_text' field type.
 * "value" field is omitted for featured snippet direct answer of this field type.
 *
 * @public
 */
export declare interface RichTextSnippetDirectAnswer extends Omit<BaseFeaturedSnippetDirectAnswer<string>