@searchcraft/react-sdk 0.13.3 → 0.15.0

package/dist/server/index.d.ts

@@ -369,11 +369,11 @@ export interface SearchcraftConfig {
 	 */
 	searchResultsPerPage?: number;
 	/**
-	 * The URL pointing towards Searchcraft Cloud's semantic search and RAG summary processing layer. When using a `searchcraft-summary-box` component, this value must be specified.
+	 * @deprecated Summary requests now use `endpointURL` and `indexName`. This field is ignored by current SDK summary requests.
 	 */
 	cortexURL?: string;
 	/**
-	 * Instructions provided to the LLM when creating search result summaries.
+	 * @deprecated Summary prompt instructions are configured server-side on the index. This field is ignored by the engine summary endpoint.
 	 */
 	summaryInstructionsPrompt?: string;
 	/**
@@ -653,8 +653,16 @@ declare class SummaryClient {
 	private get;
 	private abortController;
 	private timeout;
+	private hasWarnedAboutDeprecatedCortexURL;
 	constructor(get: SearchcraftStore["getState"], set: SearchcraftStore["setState"]);
-	streamSummaryData(): void;
+	streamSummaryData(requestProperties: SearchClientRequestProperties | string): void;
+	private setSummaryUnavailable;
+	private warnIfUsingDeprecatedCortexURL;
+	private buildSearchClientRequest;
+	private formatParamsForRequest;
+	private processSseBuffer;
+	private handleSseFrame;
+	private parseSseFrame;
 }
 /**
  * Callable functions made available by the SearchcraftStore.
@@ -715,6 +723,7 @@ export interface SearchcraftStateValues {
 	orderByField: string | undefined | null;
 	sortType: "asc" | "desc" | undefined | null;
 	summary: string;
+	summaryErrorMessage: string;
 	hasSummaryBox: boolean;
 	isSummaryLoading: boolean;
 	summaryClient?: SummaryClient;
@@ -1054,6 +1063,11 @@ export namespace Components {
 	 * ```
 	 */
 	interface SearchcraftPagination {
+		/**
+		  * The URL query string parameter name used to track the current page. When a user navigates to a URL that contains this parameter, the pagination component will automatically navigate to that page.
+		  * @default "p"
+		 */
+		"pageQueryParam": string;
 		/**
 		  * Whether to scroll to the top of the search results when pagination buttons are clicked.
 		  * @default true
@@ -1063,6 +1077,11 @@ export namespace Components {
 		  * The id of the Searchcraft instance that this component should use.
 		 */
 		"searchcraftId"?: string;
+		/**
+		  * Whether to use a query string parameter to track and restore the current page. Set to `false` to disable query string synchronisation entirely.
+		  * @default true
+		 */
+		"usePageQueryParam": boolean;
 	}
 	/**
 	 * Renders a button which, when clicked, turns on popover visibility.
@@ -1116,16 +1135,29 @@ export namespace Components {
 		/**
 		  * The type of popover button to render.
 		 */
-		"type"?: "skeuomorphic";
+		"type"?: "skeuomorphic" | "magnifying-glass";
 	}
 	/**
 	 * Renders the footer for the searchcraft-popover-form.
 	 */
 	interface SearchcraftPopoverFooter {
+		/**
+		  * The SDK variant used to render this component. Used for UTM attribution. This isn't exposed for developer consumption, it's set automatically.
+		  * @default 'js'
+		 */
+		"sdkVariant"?: "js" | "react" | "vue";
 		/**
 		  * The id of the Searchcraft instance that this component should use.
 		 */
 		"searchcraftId"?: string;
+		/**
+		  * Optional href for the "View all" button.
+		 */
+		"viewAllResultsHref"?: string;
+		/**
+		  * Optional label for the "View all" button.
+		 */
+		"viewAllResultsLabel"?: string;
 	}
 	/**
 	 * This web component is designed to display search results in a popover container that dynamically appears when the user interacts with a search input field, or when a popover-button is pressed.
@@ -1175,15 +1207,33 @@ export namespace Components {
 		  * Formats the content rendered for each result.
 		 */
 		"popoverResultMappings"?: PopoverResultMappings;
+		/**
+		  * The SDK variant used to render this component. Used for UTM attribution on the footer link.
+		  * @default 'js'
+		 */
+		"sdkVariant"?: "js" | "react" | "vue";
 		/**
 		  * The id of the Searchcraft instance that this component should use.
 		 */
 		"searchcraftId"?: string;
+		/**
+		  * Whether to display the AI generative summary box before the search results. NOTE: This requires the usage of a read key that has "SUMMARY" permissions and either a subscription to Searchcraft Cloud with AI features enabled or a self-hosted model connected.
+		  * @default false
+		 */
+		"showSummaryBox"?: boolean;
 		/**
 		  * The type of popover form to render. - `inline` - Renders inline with the rest of the content on the page. The search results pop over the page content. - `fullscreen` - Renders in fullscreen view. Used together with the `searchcraft-popover-button` component. - `modal` - Renders in a modal view. Used together with the `searchcraft-popover-button` component.
 		  * @default 'inline'
 		 */
 		"type"?: "inline" | "fullscreen" | "modal";
+		/**
+		  * Base URL for the "View all" footer link. The current search term will be appended (URL encoded).  For example, in a CMS-backed site you might set this to `/?s=` so the final URL becomes `/?s=<search-term>`.
+		 */
+		"viewAllResultsBaseUrl"?: string;
+		/**
+		  * Optional label for the "View All" footer button. Defaults to "View All".
+		 */
+		"viewAllResultsLabel"?: string;
 	}
 	/**
 	 * A single list item rendered in a searchcraft-popover-list-view.
@@ -1269,6 +1319,33 @@ export namespace Components {
 		 */
 		"template"?: ResultsInfoTemplate;
 	}
+	/**
+	 * This component renders a results summary for RAG search result summaries.
+	 * When the user makes a search, a network call is made to retrieve the summary content, which is then
+	 * rendered in this box.
+	 * NOTE: This component requires the usage of a read key that has "SUMMARY" permissions.
+	 * @react-import ```jsx
+	 * import { SearchcraftResultsSummary } from "@searchcraft/react-sdk";
+	 * ```
+	 * @vue-import ```ts
+	 * import { SearchcraftResultsSummary } from "@searchcraft/vue-sdk";
+	 * ```
+	 * @js-example ```html
+	 * <searchcraft-results-summary />
+	 * ```
+	 * @react-example ```jsx
+	 * <SearchcraftResultsSummary />
+	 * ```
+	 * @vue-example ```jsx
+	 * <SearchcraftResultsSummary />
+	 * ```
+	 */
+	interface SearchcraftResultsSummary {
+		/**
+		  * The id of the Searchcraft instance that this component should use.
+		 */
+		"searchcraftId"?: string;
+	}
 	/**
 	 * This web component is designed to display detailed information for a single search result. Once a query is submitted, the component formats and presents the result.
 	 */
@@ -1450,6 +1527,9 @@ export namespace Components {
 		"step": number;
 	}
 	/**
+	 * @deprecated Use `searchcraft-results-summary` instead.
+	 * This component is deprecated and will be removed in a future version.
+	 * Please update to use `searchcraft-results-summary` which has the same functionality.
 	 * This component renders a summary box for RAG search result summaries.
 	 * When the user makes a search, a network call is made to retrieve the summary content, which is then
 	 * rendered in this box.
@@ -1894,6 +1974,33 @@ declare global {
 		prototype: HTMLSearchcraftResultsInfoElement;
 		new (): HTMLSearchcraftResultsInfoElement;
 	};
+	/**
+	 * This component renders a results summary for RAG search result summaries.
+	 * When the user makes a search, a network call is made to retrieve the summary content, which is then
+	 * rendered in this box.
+	 * NOTE: This component requires the usage of a read key that has "SUMMARY" permissions.
+	 * @react-import ```jsx
+	 * import { SearchcraftResultsSummary } from "@searchcraft/react-sdk";
+	 * ```
+	 * @vue-import ```ts
+	 * import { SearchcraftResultsSummary } from "@searchcraft/vue-sdk";
+	 * ```
+	 * @js-example ```html
+	 * <searchcraft-results-summary />
+	 * ```
+	 * @react-example ```jsx
+	 * <SearchcraftResultsSummary />
+	 * ```
+	 * @vue-example ```jsx
+	 * <SearchcraftResultsSummary />
+	 * ```
+	 */
+	interface HTMLSearchcraftResultsSummaryElement extends Components.SearchcraftResultsSummary, HTMLStencilElement {
+	}
+	var HTMLSearchcraftResultsSummaryElement: {
+		prototype: HTMLSearchcraftResultsSummaryElement;
+		new (): HTMLSearchcraftResultsSummaryElement;
+	};
 	/**
 	 * This web component is designed to display detailed information for a single search result. Once a query is submitted, the component formats and presents the result.
 	 */
@@ -2024,6 +2131,9 @@ declare global {
 		new (): HTMLSearchcraftSliderElement;
 	};
 	/**
+	 * @deprecated Use `searchcraft-results-summary` instead.
+	 * This component is deprecated and will be removed in a future version.
+	 * Please update to use `searchcraft-results-summary` which has the same functionality.
 	 * This component renders a summary box for RAG search result summaries.
 	 * When the user makes a search, a network call is made to retrieve the summary content, which is then
 	 * rendered in this box.
@@ -2110,6 +2220,7 @@ declare global {
 		"searchcraft-popover-list-item": HTMLSearchcraftPopoverListItemElement;
 		"searchcraft-popover-list-view": HTMLSearchcraftPopoverListViewElement;
 		"searchcraft-results-info": HTMLSearchcraftResultsInfoElement;
+		"searchcraft-results-summary": HTMLSearchcraftResultsSummaryElement;
 		"searchcraft-search-result": HTMLSearchcraftSearchResultElement;
 		"searchcraft-search-results": HTMLSearchcraftSearchResultsElement;
 		"searchcraft-search-results-per-page": HTMLSearchcraftSearchResultsPerPageElement;
@@ -2411,6 +2522,11 @@ declare namespace LocalJSX {
 	 * ```
 	 */
 	interface SearchcraftPagination {
+		/**
+		  * The URL query string parameter name used to track the current page. When a user navigates to a URL that contains this parameter, the pagination component will automatically navigate to that page.
+		  * @default "p"
+		 */
+		"pageQueryParam"?: string;
 		/**
 		  * Whether to scroll to the top of the search results when pagination buttons are clicked.
 		  * @default true
@@ -2420,6 +2536,11 @@ declare namespace LocalJSX {
 		  * The id of the Searchcraft instance that this component should use.
 		 */
 		"searchcraftId"?: string;
+		/**
+		  * Whether to use a query string parameter to track and restore the current page. Set to `false` to disable query string synchronisation entirely.
+		  * @default true
+		 */
+		"usePageQueryParam"?: boolean;
 	}
 	/**
 	 * Renders a button which, when clicked, turns on popover visibility.
@@ -2473,16 +2594,29 @@ declare namespace LocalJSX {
 		/**
 		  * The type of popover button to render.
 		 */
-		"type"?: "skeuomorphic";
+		"type"?: "skeuomorphic" | "magnifying-glass";
 	}
 	/**
 	 * Renders the footer for the searchcraft-popover-form.
 	 */
 	interface SearchcraftPopoverFooter {
+		/**
+		  * The SDK variant used to render this component. Used for UTM attribution. This isn't exposed for developer consumption, it's set automatically.
+		  * @default 'js'
+		 */
+		"sdkVariant"?: "js" | "react" | "vue";
 		/**
 		  * The id of the Searchcraft instance that this component should use.
 		 */
 		"searchcraftId"?: string;
+		/**
+		  * Optional href for the "View all" button.
+		 */
+		"viewAllResultsHref"?: string;
+		/**
+		  * Optional label for the "View all" button.
+		 */
+		"viewAllResultsLabel"?: string;
 	}
 	/**
 	 * This web component is designed to display search results in a popover container that dynamically appears when the user interacts with a search input field, or when a popover-button is pressed.
@@ -2532,15 +2666,33 @@ declare namespace LocalJSX {
 		  * Formats the content rendered for each result.
 		 */
 		"popoverResultMappings"?: PopoverResultMappings;
+		/**
+		  * The SDK variant used to render this component. Used for UTM attribution on the footer link.
+		  * @default 'js'
+		 */
+		"sdkVariant"?: "js" | "react" | "vue";
 		/**
 		  * The id of the Searchcraft instance that this component should use.
 		 */
 		"searchcraftId"?: string;
+		/**
+		  * Whether to display the AI generative summary box before the search results. NOTE: This requires the usage of a read key that has "SUMMARY" permissions and either a subscription to Searchcraft Cloud with AI features enabled or a self-hosted model connected.
+		  * @default false
+		 */
+		"showSummaryBox"?: boolean;
 		/**
 		  * The type of popover form to render. - `inline` - Renders inline with the rest of the content on the page. The search results pop over the page content. - `fullscreen` - Renders in fullscreen view. Used together with the `searchcraft-popover-button` component. - `modal` - Renders in a modal view. Used together with the `searchcraft-popover-button` component.
 		  * @default 'inline'
 		 */
 		"type"?: "inline" | "fullscreen" | "modal";
+		/**
+		  * Base URL for the "View all" footer link. The current search term will be appended (URL encoded).  For example, in a CMS-backed site you might set this to `/?s=` so the final URL becomes `/?s=<search-term>`.
+		 */
+		"viewAllResultsBaseUrl"?: string;
+		/**
+		  * Optional label for the "View All" footer button. Defaults to "View All".
+		 */
+		"viewAllResultsLabel"?: string;
 	}
 	/**
 	 * A single list item rendered in a searchcraft-popover-list-view.
@@ -2626,6 +2778,33 @@ declare namespace LocalJSX {
 		 */
 		"template"?: ResultsInfoTemplate;
 	}
+	/**
+	 * This component renders a results summary for RAG search result summaries.
+	 * When the user makes a search, a network call is made to retrieve the summary content, which is then
+	 * rendered in this box.
+	 * NOTE: This component requires the usage of a read key that has "SUMMARY" permissions.
+	 * @react-import ```jsx
+	 * import { SearchcraftResultsSummary } from "@searchcraft/react-sdk";
+	 * ```
+	 * @vue-import ```ts
+	 * import { SearchcraftResultsSummary } from "@searchcraft/vue-sdk";
+	 * ```
+	 * @js-example ```html
+	 * <searchcraft-results-summary />
+	 * ```
+	 * @react-example ```jsx
+	 * <SearchcraftResultsSummary />
+	 * ```
+	 * @vue-example ```jsx
+	 * <SearchcraftResultsSummary />
+	 * ```
+	 */
+	interface SearchcraftResultsSummary {
+		/**
+		  * The id of the Searchcraft instance that this component should use.
+		 */
+		"searchcraftId"?: string;
+	}
 	/**
 	 * This web component is designed to display detailed information for a single search result. Once a query is submitted, the component formats and presents the result.
 	 */
@@ -2815,6 +2994,9 @@ declare namespace LocalJSX {
 		"step"?: number;
 	}
 	/**
+	 * @deprecated Use `searchcraft-results-summary` instead.
+	 * This component is deprecated and will be removed in a future version.
+	 * Please update to use `searchcraft-results-summary` which has the same functionality.
 	 * This component renders a summary box for RAG search result summaries.
 	 * When the user makes a search, a network call is made to retrieve the summary content, which is then
 	 * rendered in this box.
@@ -2899,6 +3081,7 @@ declare namespace LocalJSX {
 		"searchcraft-popover-list-item": SearchcraftPopoverListItem;
 		"searchcraft-popover-list-view": SearchcraftPopoverListView;
 		"searchcraft-results-info": SearchcraftResultsInfo;
+		"searchcraft-results-summary": SearchcraftResultsSummary;
 		"searchcraft-search-result": SearchcraftSearchResult;
 		"searchcraft-search-results": SearchcraftSearchResults;
 		"searchcraft-search-results-per-page": SearchcraftSearchResultsPerPage;
@@ -3154,6 +3337,28 @@ declare module "@stencil/core" {
 			 * ```
 			 */
 			"searchcraft-results-info": LocalJSX.SearchcraftResultsInfo & JSXBase.HTMLAttributes<HTMLSearchcraftResultsInfoElement>;
+			/**
+			 * This component renders a results summary for RAG search result summaries.
+			 * When the user makes a search, a network call is made to retrieve the summary content, which is then
+			 * rendered in this box.
+			 * NOTE: This component requires the usage of a read key that has "SUMMARY" permissions.
+			 * @react-import ```jsx
+			 * import { SearchcraftResultsSummary } from "@searchcraft/react-sdk";
+			 * ```
+			 * @vue-import ```ts
+			 * import { SearchcraftResultsSummary } from "@searchcraft/vue-sdk";
+			 * ```
+			 * @js-example ```html
+			 * <searchcraft-results-summary />
+			 * ```
+			 * @react-example ```jsx
+			 * <SearchcraftResultsSummary />
+			 * ```
+			 * @vue-example ```jsx
+			 * <SearchcraftResultsSummary />
+			 * ```
+			 */
+			"searchcraft-results-summary": LocalJSX.SearchcraftResultsSummary & JSXBase.HTMLAttributes<HTMLSearchcraftResultsSummaryElement>;
 			/**
 			 * This web component is designed to display detailed information for a single search result. Once a query is submitted, the component formats and presents the result.
 			 */
@@ -3237,6 +3442,9 @@ declare module "@stencil/core" {
 			 */
 			"searchcraft-slider": LocalJSX.SearchcraftSlider & JSXBase.HTMLAttributes<HTMLSearchcraftSliderElement>;
 			/**
+			 * @deprecated Use `searchcraft-results-summary` instead.
+			 * This component is deprecated and will be removed in a future version.
+			 * Please update to use `searchcraft-results-summary` which has the same functionality.
 			 * This component renders a summary box for RAG search result summaries.
 			 * When the user makes a search, a network call is made to retrieve the summary content, which is then
 			 * rendered in this box.
@@ -3285,15 +3493,6 @@ declare module "@stencil/core" {
 	}
 }
 export declare const defineCustomElements: () => void;
-/**
- * The props for the SearchcraftSearchResults server component.
- */
-export interface SearchcraftSearchResultsProps extends Components.SearchcraftSearchResults {
-}
-/**
- * A react server component that renders a list of search results with customizable styles, layout, and link behavior.
- */
-export declare function SearchcraftSearchResults(props: SearchcraftSearchResultsProps): Promise<import("react/jsx-runtime").JSX.Element>;
 /**
  * The props for the SearchcraftFilterPanel.
  */
@@ -3314,6 +3513,16 @@ export interface SearchcraftInputFormProps extends Components.SearchcraftInputFo
  * of index-based searching, making it accessible to users of all technical levels.
  */
 export declare function SearchcraftInputForm(props: SearchcraftInputFormProps): Promise<import("react/jsx-runtime").JSX.Element>;
+/**
+ * The props for the SearchcraftPagination component.
+ */
+export interface SearchcraftPaginationProps extends Components.SearchcraftPagination {
+}
+/**
+ * This React server component is designed to facilitate pagination of search results.
+ * Once a query is submitted, calculates the number for pages.
+ */
+export declare function SearchcraftPagination(props: SearchcraftPaginationProps): Promise<import("react/jsx-runtime").JSX.Element>;
 /**
  * The props for the SearchcraftPopoverButton.
  */
@@ -3343,25 +3552,23 @@ export interface SearchcraftResultsInfoProps extends Components.SearchcraftResul
  */
 export declare function SearchcraftResultsInfo(props: SearchcraftResultsInfoProps): Promise<import("react/jsx-runtime").JSX.Element>;
 /**
- * The Props for the SearchcraftTheme component.
+ * The Props for the SearchcraftResultsSummary component.
  */
-export interface SearchcraftThemeProps extends Components.SearchcraftTheme {
+export interface SearchcraftResultsSummaryProps extends Components.SearchcraftResultsSummary {
 }
 /**
- * A react server component that applies Searchcraft's built-in CSS theme to your page.
- * It does not render anything visible—its only function is to manage the CSS styles on the page.
+ * This React component displays an ai-generated results summary of the given search term.
  */
-export declare function SearchcraftTheme(props: SearchcraftThemeProps): Promise<import("react/jsx-runtime").JSX.Element>;
+export declare function SearchcraftResultsSummary(props: SearchcraftResultsSummaryProps): Promise<import("react/jsx-runtime").JSX.Element>;
 /**
- * The props for the SearchcraftPagination component.
+ * The props for the SearchcraftSearchResults server component.
  */
-export interface SearchcraftPaginationProps extends Components.SearchcraftPagination {
+export interface SearchcraftSearchResultsProps extends Components.SearchcraftSearchResults {
 }
 /**
- * This React server component is designed to facilitate pagination of search results.
- * Once a query is submitted, calculates the number for pages.
+ * A react server component that renders a list of search results with customizable styles, layout, and link behavior.
  */
-export declare function SearchcraftPagination(props: SearchcraftPaginationProps): Promise<import("react/jsx-runtime").JSX.Element>;
+export declare function SearchcraftSearchResults(props: SearchcraftSearchResultsProps): Promise<import("react/jsx-runtime").JSX.Element>;
 /**
  * The Props for the SearchcraftSearchResultsPerPage component.
  */
@@ -3372,14 +3579,29 @@ export interface SearchcraftSearchResultsPerPageProps extends Components.Searchc
  */
 export declare function SearchcraftSearchResultsPerPage(props: SearchcraftSearchResultsPerPageProps): Promise<import("react/jsx-runtime").JSX.Element>;
 /**
+ * @deprecated Use `SearchcraftResultsSummary` instead.
+ * This component is deprecated and will be removed in a future version.
+ * Please update to use `SearchcraftResultsSummary` which has the same functionality.
+ *
  * The Props for the SearchcraftSummaryBox component.
  */
 export interface SearchcraftSummaryBoxProps extends Components.SearchcraftSummaryBox {
 }
 /**
  * This React component displays an ai-generated summary of the given search term.
+ * @deprecated Use `SearchcraftResultsSummary` instead.
  */
 export declare function SearchcraftSummaryBox(props: SearchcraftSummaryBoxProps): Promise<import("react/jsx-runtime").JSX.Element>;
+/**
+ * The Props for the SearchcraftTheme component.
+ */
+export interface SearchcraftThemeProps extends Components.SearchcraftTheme {
+}
+/**
+ * A react server component that applies Searchcraft's built-in CSS theme to your page.
+ * It does not render anything visible—its only function is to manage the CSS styles on the page.
+ */
+export declare function SearchcraftTheme(props: SearchcraftThemeProps): Promise<import("react/jsx-runtime").JSX.Element>;
 /**
  * The consumer-facing Searchcraft class.
  */