@sitecore-cloudsdk/search 0.5.0-rc.0

package/dist/esm/src/lib/request-entities/widgets/interfaces.d.ts

@@ -0,0 +1,372 @@
+import type { ComparisonFacetFilter } from '../filters/facet/comparison-facet-filter';
+import type { ComparisonFacetFilterDTO, ListFacetFilterDTO, LogicalFacetFilterDTO, NotFacetFilterDTO } from '../filters/facet/interfaces';
+import type { ListFacetFilter } from '../filters/facet/list-facet-filter';
+import type { LogicalFacetFilter } from '../filters/facet/logical-facet-filter';
+import type { NotFacetFilter } from '../filters/facet/not-facet-filter';
+import type { ArrayOfAtLeastOne, Filter, FilterDTO, LogicalOperators } from '../filters/interfaces';
+/**
+ * Represents a widget item object that holds the base members in its DTO format.
+ */
+export interface WidgetItemDTO {
+    entity: string;
+    rfk_id: string;
+}
+/**
+ * Represents the content options property of the results widget item.
+ */
+export type ContentOptions = {
+    attributes?: ArrayOfAtLeastOne<string>;
+} | Record<string, never>;
+/**
+ * Represents the content options property of the results widget item in DTO Format.
+ */
+export type ContentOptionsDto = {
+    fields?: ArrayOfAtLeastOne<string>;
+} | Record<string, never>;
+/**
+ * Represents a results widget item object.
+ */
+export interface ResultsOptions {
+    limit?: number;
+    filter?: Filter;
+    groupBy?: string;
+    content?: ContentOptions;
+    rule?: SearchRuleOptions;
+}
+/**
+ * Represents a results widget item object in its DTO format.
+ */
+export interface ResultsItemDTO {
+    limit?: number;
+    filter?: FilterDTO;
+    group_by?: string;
+    content?: ContentOptionsDto;
+    rule?: SearchRuleDTO;
+}
+type FacetSortName = 'text' | 'count';
+type SortingOptions = 'asc' | 'desc';
+export type FacetFilter = ComparisonFacetFilter | NotFacetFilter | LogicalFacetFilter | ListFacetFilter;
+export type FacetFilterDTO = ComparisonFacetFilterDTO | NotFacetFilterDTO | LogicalFacetFilterDTO | ListFacetFilterDTO;
+export type FacetTypeFilter = {
+    type: 'and' | 'or';
+    values: ArrayOfAtLeastOne<string> | ArrayOfAtLeastOne<FacetFilter>;
+};
+export type FacetTypeFilterDTO = {
+    type: 'and' | 'or';
+    values: ArrayOfAtLeastOne<string> | ArrayOfAtLeastOne<FacetFilterDTO>;
+};
+export type FacetSortDTO = Omit<FacetSort, 'after'>;
+type FilteringOptionsDynamicOr = 'Dynamic OR';
+type FilteringOptionsDynamicAnd = 'Dynamic AND';
+type FilteringOptionsStatic = 'Static';
+/**
+ * Represents the type filtering option.
+ *
+ * Manages how other filtering affects this facet, and how filtering in this facet affects other facets.
+ */
+export type FilteringOptions = FilteringOptionsDynamicOr | FilteringOptionsDynamicAnd | FilteringOptionsStatic;
+export type FilteringOptionsDTO = ['hard_filters', 'other_facet_values', 'own_values'] | ['hard_filters', 'other_facet_values'] | ['hard_filters'];
+/**
+ * Represents the type object of the facet object.
+ */
+export interface FacetTypeOptions {
+    name: string;
+    exclude?: ArrayOfAtLeastOne<string>;
+    max?: number;
+    keyphrase?: string;
+    minCount?: number;
+    sort?: FacetSort;
+    filter?: FacetTypeFilter;
+    filteringOptions?: FilteringOptions;
+}
+/**
+ * Represents the facet object of search widget item in its DTO format.
+ */
+export interface FacetTypeDTO {
+    name: string;
+    exclude?: ArrayOfAtLeastOne<string>;
+    max?: number;
+    keyphrase?: string;
+    min_count?: number;
+    sort?: FacetSortDTO;
+    after?: string;
+    filter?: FacetTypeFilterDTO;
+    filtering_options?: FilteringOptionsDTO;
+}
+/**
+ * Represents the facet object of search widget item.
+ */
+export interface FacetOptions {
+    all?: boolean;
+    max?: number;
+    coverage?: boolean;
+    sort?: FacetSort;
+    types?: ArrayOfAtLeastOne<FacetTypeOptions>;
+}
+/**
+ * Represents the sort object of the facet object.
+ */
+export interface FacetSort {
+    name: FacetSortName;
+    order: SortingOptions;
+    after?: string;
+}
+/**
+ * Represents the facet object its DTO format.
+ */
+export interface FacetOptionsDTO {
+    all?: boolean;
+    max?: number;
+    coverage?: boolean;
+    sort?: FacetSort;
+    types?: ArrayOfAtLeastOne<FacetTypeDTO>;
+}
+/**
+ * Represents the query object of search widget item.
+ */
+export interface QueryOptions {
+    keyphrase: string;
+    operator?: Exclude<LogicalOperators, 'not'>;
+}
+/**
+ * Represents the query object of search widget item in its DTO format.
+ */
+export interface QueryOptionsDTO {
+    keyphrase: string;
+    operator?: Exclude<LogicalOperators, 'not'>;
+}
+export interface SearchOptions extends ResultsOptions {
+    facet?: FacetOptions;
+    query?: QueryOptions;
+    offset?: number;
+    sort?: SearchSortOptions;
+    rule?: SearchRuleOptions;
+    suggestion?: ArrayOfAtLeastOne<SearchSuggestionOptions>;
+    ranking?: ArrayOfAtLeastOne<SearchRankingOptions>;
+    personalization?: SearchPersonalizationOptions;
+}
+/**
+ * Represents the search object of the search widget item in its DTO format.
+ */
+export interface SearchDTO extends ResultsItemDTO {
+    facet?: FacetOptionsDTO;
+    query?: QueryOptionsDTO;
+    offset?: number;
+    sort?: SearchSortOptionsDTO;
+    suggestion?: ArrayOfAtLeastOne<SearchSuggestionOptionsDTO>;
+    ranking?: ArrayOfAtLeastOne<SearchRankingOptionsDto>;
+    personalization?: SearchPersonalizationOptionsDto;
+}
+/**
+ * Represents the search widget item object in its DTO format.
+ */
+export interface SearchWidgetItemDTO extends WidgetItemDTO {
+    search?: SearchDTO;
+}
+/**
+ * Represents the search widget item sort param options.
+ */
+export interface SortValue {
+    name: string;
+    order?: SortingOptions;
+}
+/**
+ * Represents the search widget item sort param options in its DTO format.
+ */
+export interface SortValueDTO {
+    name: string;
+    order?: SortingOptions;
+}
+/**
+ * Represents `ranking` property options of the search widget item.
+ */
+export interface SearchRankingOptions {
+    name: string;
+    weight?: number;
+}
+/**
+ * Represents `ranking` property options of the search widget item in DTO format.
+ */
+export interface SearchRankingOptionsDto {
+    name: string;
+    weight?: number;
+}
+/**
+ * Typescript restriction for the `personalization` property.
+ * if `algorithm` = affinity, `ids` should not be present.
+ */
+export type SearchPersonalizationOptions = {
+    attributes: ArrayOfAtLeastOne<string>;
+} & ({
+    algorithm: 'affinity';
+} | {
+    algorithm: 'mlt';
+    ids: ArrayOfAtLeastOne<string>;
+});
+/**
+ * Typescript restriction for the `personalization` property in DTO format.
+ * if `algorithm` = affinity, `ids` should not be present.
+ */
+export type SearchPersonalizationOptionsDto = {
+    fields: ArrayOfAtLeastOne<string>;
+} & ({
+    algorithm: 'affinity';
+} | {
+    algorithm: 'mlt';
+    ids: ArrayOfAtLeastOne<string>;
+});
+/**
+ * Represents the search widget item sort param.
+ */
+export interface SearchSortOptions {
+    choices?: boolean;
+    value?: ArrayOfAtLeastOne<SortValue>;
+}
+/**
+ * Represents the search widget item sort param in its DTO format.
+ */
+export interface SearchSortOptionsDTO {
+    choices?: boolean;
+    value?: ArrayOfAtLeastOne<SortValue>;
+}
+/**
+ * Represents the search widget item suggestion param.
+ */
+export interface SearchSuggestionOptions {
+    exclude?: ArrayOfAtLeastOne<string>;
+    keyphraseFallback?: boolean;
+    max?: number;
+    name: string;
+}
+/**
+ * Represents the search widget item suggestion param in DTO format.
+ */
+export interface SearchSuggestionOptionsDTO {
+    exclude?: ArrayOfAtLeastOne<string>;
+    keyphrase_fallback?: boolean;
+    max?: number;
+    name: string;
+}
+/**
+ * Represents the recipe object of the recommendation widget item.
+ */
+export type Recipe = {
+    id: string;
+    version: number;
+};
+/**
+ * Represents recommendation widget item.
+ */
+export interface Recommendation {
+    recipe?: Recipe;
+}
+/**
+ * Represents a widget item recommendation object.
+ */
+export type RecommendationOptions = ResultsOptions & Recommendation;
+/**
+ * Represents the recommendations object of the recommendation widget item in its DTO format.
+ */
+export interface RecommendationDTO extends ResultsItemDTO {
+    recipe?: Recipe;
+}
+/**
+ * Represents the recommendation widget item object in its DTO format.
+ */
+export interface WidgetItemRecommendationDTO extends WidgetItemDTO {
+    recommendations?: RecommendationDTO;
+}
+/**
+ * Represents a widget object in its DTO format.
+ */
+export interface WidgetDTO {
+    widget: {
+        items: WidgetItemDTO[];
+    };
+}
+type QueryType = 'question' | 'statement' | 'keyword';
+export interface RelatedQuestionsOptions {
+    limit?: number;
+    includeSources?: boolean;
+    filter?: Filter;
+    offset?: number;
+}
+export interface ExactAnswerOptions {
+    includeSources?: boolean;
+    queryTypes?: ArrayOfAtLeastOne<QueryType>;
+}
+export interface QuestionsAnswersOptions {
+    keyphrase: string;
+    exactAnswer?: ExactAnswerOptions;
+    relatedQuestions?: RelatedQuestionsOptions;
+    rule?: SearchRuleOptions;
+}
+export interface QuestionsAnswersWidgetItemDTO extends WidgetItemDTO {
+    questions: {
+        keyphrase: string;
+        exact_answer?: {
+            include_sources?: boolean;
+            query_types?: ArrayOfAtLeastOne<QueryType>;
+        };
+        related_questions?: {
+            filter?: FilterDTO;
+            include_sources?: boolean;
+            limit?: number;
+            offset?: number;
+            rule?: SearchRuleDTO;
+        };
+    };
+}
+interface Boost {
+    filter: Filter;
+    slots?: ArrayOfAtLeastOne<number>;
+    weight?: number;
+}
+interface Include {
+    filter: Filter;
+    slots: ArrayOfAtLeastOne<number>;
+}
+interface PinItem {
+    id: string;
+    slot: number;
+}
+export interface SearchRuleOptions {
+    behaviors?: boolean;
+    blacklist?: {
+        filter: Filter;
+    };
+    boost?: ArrayOfAtLeastOne<Boost>;
+    bury?: {
+        filter: Filter;
+    };
+    include?: ArrayOfAtLeastOne<Include>;
+    pin?: ArrayOfAtLeastOne<PinItem>;
+}
+export interface PinItemDTO {
+    id: string;
+    slot: number;
+}
+export interface BoostRuleDTO {
+    filter: FilterDTO;
+    slots?: ArrayOfAtLeastOne<number>;
+    weight?: number;
+}
+export interface IncludeRuleDTO {
+    filter: FilterDTO;
+    slots: ArrayOfAtLeastOne<number>;
+}
+export interface FilterRuleDTO {
+    filter: FilterDTO;
+}
+export interface SearchRuleDTO {
+    behaviors?: boolean;
+    blacklist?: FilterRuleDTO;
+    boost?: ArrayOfAtLeastOne<BoostRuleDTO>;
+    bury?: FilterRuleDTO;
+    include?: ArrayOfAtLeastOne<IncludeRuleDTO>;
+    pin?: ArrayOfAtLeastOne<PinItemDTO>;
+}
+export interface RuleWidgetItemDTO extends WidgetItemDTO {
+    rule?: SearchRuleDTO;
+}
+export {};

package/dist/esm/src/lib/request-entities/widgets/interfaces.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/src/lib/request-entities/widgets/questions-answers-widget-item.d.ts

@@ -0,0 +1,62 @@
+import type { ExactAnswerOptions, QuestionsAnswersOptions, QuestionsAnswersWidgetItemDTO, RelatedQuestionsOptions } from './interfaces';
+import { RuleWidgetItem } from './rule-widget-item';
+export declare class QuestionsAnswersWidgetItem extends RuleWidgetItem {
+    private _keyphrase;
+    private _exactAnswer?;
+    private _relatedQuestions?;
+    /**
+     * Creates and holds the functionality of a questions answers widget item.
+     * @param entity - The widget's item entity.
+     * @param widgetId - The widget's item id.
+     * @param questionsAnswersOptions - The widget's questions answers options object.
+     */
+    constructor(entity: string, widgetId: string, questionsAnswersOptions: QuestionsAnswersOptions);
+    private _validateRelatedQuestions;
+    /**
+     * Sets the keyphrase for the QuestionsAnswersWidgetItem.
+     * This method updates the `keyphrase` property of the questions answers configuration.
+     *
+     * @param keyphrase - The keyphrase that the visitor enters to search for relevant content.
+     */
+    set keyphrase(keyphrase: string);
+    /**
+     * @returns The keyphrase property of the QuestionsAnswersWidgetItem.
+     */
+    get keyphrase(): string;
+    /**
+     * Sets the exactAnswer for the QuestionsAnswersWidgetItem.
+     * This method updates the `exactAnswer` property of the questions answers configuration.
+     *
+     * @param exactAnswer - The exactAnswer that the visitor enters to search for relevant content.
+     */
+    set exactAnswer(exactAnswer: ExactAnswerOptions);
+    /**
+     * @returns The exactAnswer property of the QuestionsAnswersWidgetItem.
+     */
+    get exactAnswer(): ExactAnswerOptions | undefined;
+    /**
+     * Sets the exactAnswer to undefined
+     */
+    resetExactAnswer(): void;
+    /**
+     * Sets the relatedQuestions for the QuestionsAnswersWidgetItem.
+     * This method updates the `relatedQuestions` property of the questions answers configuration.
+     *
+     * @param relatedQuestions - The relatedQuestions that the visitor enters to search for relevant content.
+     */
+    set relatedQuestions(relatedQuestions: RelatedQuestionsOptions);
+    /**
+     * @returns The relatedQuestions property of the QuestionsAnswersWidgetItem.
+     */
+    get relatedQuestions(): RelatedQuestionsOptions | undefined;
+    /**
+     * Sets the relatedQuestions to undefined
+     */
+    resetRelatedQuestions(): void;
+    private _exactAnswerToDTO;
+    private _relatedQuestionsToDTO;
+    /**
+     * Maps the questions answers widget item to its DTO format.
+     */
+    toDTO(): QuestionsAnswersWidgetItemDTO;
+}

package/dist/esm/src/lib/request-entities/widgets/questions-answers-widget-item.js

@@ -0,0 +1,113 @@
+// © Sitecore Corporation A/S. All rights reserved. Sitecore® is a registered trademark of Sitecore Corporation A/S.
+import { ErrorMessages } from '../../consts';
+import { RuleWidgetItem } from './rule-widget-item';
+export class QuestionsAnswersWidgetItem extends RuleWidgetItem {
+    /**
+     * Creates and holds the functionality of a questions answers widget item.
+     * @param entity - The widget's item entity.
+     * @param widgetId - The widget's item id.
+     * @param questionsAnswersOptions - The widget's questions answers options object.
+     */
+    constructor(entity, widgetId, questionsAnswersOptions) {
+        super(entity, widgetId, questionsAnswersOptions.rule);
+        this._validateStringLengthInRange1To100(ErrorMessages.IV_0009, questionsAnswersOptions.keyphrase);
+        this._keyphrase = questionsAnswersOptions.keyphrase;
+        this._exactAnswer = questionsAnswersOptions.exactAnswer;
+        if (questionsAnswersOptions.relatedQuestions) {
+            this._validateRelatedQuestions(questionsAnswersOptions.relatedQuestions);
+            this._relatedQuestions = questionsAnswersOptions.relatedQuestions;
+        }
+    }
+    _validateRelatedQuestions(relatedQuestions) {
+        this._validateNumberInRange1To100(ErrorMessages.IV_0007, relatedQuestions.limit);
+        this._validatePositiveInteger(ErrorMessages.IV_0008, relatedQuestions.offset);
+    }
+    /**
+     * Sets the keyphrase for the QuestionsAnswersWidgetItem.
+     * This method updates the `keyphrase` property of the questions answers configuration.
+     *
+     * @param keyphrase - The keyphrase that the visitor enters to search for relevant content.
+     */
+    set keyphrase(keyphrase) {
+        this._validateStringLengthInRange1To100(ErrorMessages.IV_0009, keyphrase);
+        this._keyphrase = keyphrase;
+    }
+    /**
+     * @returns The keyphrase property of the QuestionsAnswersWidgetItem.
+     */
+    get keyphrase() {
+        return this._keyphrase;
+    }
+    /**
+     * Sets the exactAnswer for the QuestionsAnswersWidgetItem.
+     * This method updates the `exactAnswer` property of the questions answers configuration.
+     *
+     * @param exactAnswer - The exactAnswer that the visitor enters to search for relevant content.
+     */
+    set exactAnswer(exactAnswer) {
+        this._exactAnswer = exactAnswer;
+    }
+    /**
+     * @returns The exactAnswer property of the QuestionsAnswersWidgetItem.
+     */
+    get exactAnswer() {
+        return this._exactAnswer;
+    }
+    /**
+     * Sets the exactAnswer to undefined
+     */
+    resetExactAnswer() {
+        this._exactAnswer = undefined;
+    }
+    /**
+     * Sets the relatedQuestions for the QuestionsAnswersWidgetItem.
+     * This method updates the `relatedQuestions` property of the questions answers configuration.
+     *
+     * @param relatedQuestions - The relatedQuestions that the visitor enters to search for relevant content.
+     */
+    set relatedQuestions(relatedQuestions) {
+        this._validateRelatedQuestions(relatedQuestions);
+        this._relatedQuestions = relatedQuestions;
+    }
+    /**
+     * @returns The relatedQuestions property of the QuestionsAnswersWidgetItem.
+     */
+    get relatedQuestions() {
+        return this._relatedQuestions;
+    }
+    /**
+     * Sets the relatedQuestions to undefined
+     */
+    resetRelatedQuestions() {
+        this._relatedQuestions = undefined;
+    }
+    _exactAnswerToDTO() {
+        if (!this._exactAnswer)
+            return;
+        return { include_sources: this._exactAnswer.includeSources, query_types: this._exactAnswer.queryTypes };
+    }
+    _relatedQuestionsToDTO() {
+        if (!this._relatedQuestions)
+            return;
+        return {
+            filter: this._relatedQuestions.filter?.toDTO(),
+            include_sources: this._relatedQuestions.includeSources,
+            limit: this._relatedQuestions.limit,
+            offset: this._relatedQuestions.offset,
+            rule: this._ruleToDTO(this._rule)
+        };
+    }
+    /**
+     * Maps the questions answers widget item to its DTO format.
+     */
+    toDTO() {
+        return {
+            ...super.toDTO(),
+            questions: {
+                keyphrase: this._keyphrase,
+                ...{ exact_answer: this._exactAnswerToDTO() },
+                ...{ related_questions: this._relatedQuestionsToDTO() }
+            }
+        };
+    }
+}

package/dist/esm/src/lib/request-entities/widgets/recommendation-widget-item.d.ts

@@ -0,0 +1,39 @@
+import type { Recipe, Recommendation, RecommendationOptions, WidgetItemRecommendationDTO } from './interfaces';
+import { ResultsWidgetItem } from './results-widget-item';
+export declare class RecommendationWidgetItem extends ResultsWidgetItem {
+    protected _recommendation?: Recommendation;
+    /**
+     * Creates and holds the functionality of a recommendation widget item.
+     * @param entity - The widget's item entity.
+     * @param widgetId - The widget's item id.
+     * @param recommendationOptions - The widget's recommendation options object.
+     */
+    constructor(entity: string, widgetId: string, recommendationOptions?: RecommendationOptions);
+    /**
+     * Sets the recommendations to an empty object.
+     */
+    resetRecommendations(): void;
+    /**
+     * Sets the recipe for the RecommendationWidgetItem.
+     * This method updates the `recipe` property of the recommendations configuration.
+     * The recipe is used to specify which recommendation algorithm to use.
+     * If not provided, the API uses the recipe specified in CEC.
+     *
+     * @param recipe - {@link Recipe} The recipe configuration with id and version.
+     * @throws Error If the recipe id is empty or version is less than 1.
+     */
+    set recipe(recipe: Recipe);
+    /**
+     * @returns The recipe property of the RecommendationWidgetItem.
+     */
+    get recipe(): Recipe | undefined;
+    /**
+     * Sets the recipe to undefined
+     */
+    resetRecipe(): void;
+    private _validateRecipe;
+    /**
+     * Maps the recommendation widget item to its DTO format.
+     */
+    toDTO(): WidgetItemRecommendationDTO;
+}

package/dist/esm/src/lib/request-entities/widgets/recommendation-widget-item.js

@@ -0,0 +1,80 @@
+// © Sitecore Corporation A/S. All rights reserved. Sitecore® is a registered trademark of Sitecore Corporation A/S.
+import { ErrorMessages } from '../../consts';
+import { ResultsWidgetItem } from './results-widget-item';
+export class RecommendationWidgetItem extends ResultsWidgetItem {
+    /**
+     * Creates and holds the functionality of a recommendation widget item.
+     * @param entity - The widget's item entity.
+     * @param widgetId - The widget's item id.
+     * @param recommendationOptions - The widget's recommendation options object.
+     */
+    constructor(entity, widgetId, recommendationOptions) {
+        const { recipe, ...rest } = recommendationOptions || {};
+        super(entity, widgetId, rest);
+        if (!recommendationOptions)
+            return;
+        if (!Object.keys(recommendationOptions).length) {
+            this._recommendation = {};
+            return;
+        }
+        this._validateRecipe(recipe);
+        this._recommendation = { recipe };
+    }
+    /**
+     * Sets the recommendations to an empty object.
+     */
+    resetRecommendations() {
+        this._recommendation = {};
+    }
+    /**
+     * Sets the recipe for the RecommendationWidgetItem.
+     * This method updates the `recipe` property of the recommendations configuration.
+     * The recipe is used to specify which recommendation algorithm to use.
+     * If not provided, the API uses the recipe specified in CEC.
+     *
+     * @param recipe - {@link Recipe} The recipe configuration with id and version.
+     * @throws Error If the recipe id is empty or version is less than 1.
+     */
+    set recipe(recipe) {
+        this._validateRecipe(recipe);
+        this._recommendation = {
+            ...this._recommendation,
+            recipe
+        };
+    }
+    /**
+     * @returns The recipe property of the RecommendationWidgetItem.
+     */
+    get recipe() {
+        return this._recommendation?.recipe;
+    }
+    /**
+     * Sets the recipe to undefined
+     */
+    resetRecipe() {
+        this._recommendation = undefined;
+    }
+    _validateRecipe(recipe) {
+        if (!recipe)
+            return;
+        this._validateNonEmptyString(ErrorMessages.IV_0023, recipe.id);
+        if (recipe.version < 1)
+            throw new Error(ErrorMessages.IV_0024);
+    }
+    /**
+     * Maps the recommendation widget item to its DTO format.
+     */
+    toDTO() {
+        const baseDTO = super.toDTO();
+        const resultsDTO = this._resultsToDTO();
+        const recommendationsDTO = {
+            ...(this._recommendation?.recipe && { recipe: this._recommendation.recipe }),
+            ...resultsDTO
+        };
+        const dto = {
+            ...baseDTO,
+            recommendations: Object.values(recommendationsDTO).length || this._recommendation ? recommendationsDTO : undefined
+        };
+        return dto;
+    }
+}