@docsearch/react 4.6.2 → 4.7.0

package/dist/esm/index.d.ts

@@ -1,10 +1,10 @@
+import { UIMessage } from '@ai-sdk/react';
+import { UIDataTypes } from 'ai';
 import { BaseItem, AutocompleteState, AutocompleteContext, AutocompleteInsightsApi, AutocompleteOptions } from '@algolia/autocomplete-core';
 import { InitialAskAiMessage, DocSearchModalShortcuts, DocSearchRef, OnAskAiToggle } from '@docsearch/core';
 export { DocSearchRef } from '@docsearch/core';
 import { Hit, SearchParamsObject, LiteClient } from 'algoliasearch/lite';
 import React, { JSX } from 'react';
-import { UIMessage } from '@ai-sdk/react';
-import { UIDataTypes } from 'ai';
 
 type ContentType = 'askAI' | 'content' | 'lvl0' | 'lvl1' | 'lvl2' | 'lvl3' | 'lvl4' | 'lvl5' | 'lvl6';
 interface DocSearchHitAttributeHighlightResult {
@@ -174,6 +174,98 @@ type SuggestedQuestion = {
 };
 type SuggestedQuestionHit = Hit<SuggestedQuestion>;
 
+type ExchangeWithOptionalAssistant = {
+    assistantMessage: AIMessage | null;
+};
+/**
+ * Pass-through: keep all exchanges when thread depth fails so the last user message stays visible
+ * (there is often no assistant reply for that turn).
+ */
+declare function filterExchangesForThreadDepthError<T extends ExchangeWithOptionalAssistant>(exchanges: T[], _hasThreadDepthError: boolean): T[];
+/**
+ * Whether the error is conversation depth exceeded (AI-217), including JSON-shaped Agent Studio payloads.
+ */
+declare function isThreadDepthError(error?: Error): boolean;
+/**
+ * Whether further prompts should be blocked: thread depth (all backends) or Agent Studio cost controls.
+ */
+declare function isAskAiPromptBlockingError(error: Error | undefined, agentStudio: boolean): boolean;
+/**
+ * Agent Studio stream hit the completion token ceiling (`TokenOutputLimitError`).
+ * This case uses a message-only banner (no “Start a new conversation” row).
+ */
+declare function isAgentStudioTokenOutputLimitError(error?: Error): boolean;
+/**
+ * Whether the blocking banner should include “Start a new conversation … to continue”.
+ * Thread depth and most Agent Studio limits keep it; token output limit and “request blocked for this domain” omit it.
+ */
+declare function showAskAiBlockingBannerNewConversationLink(error: Error | undefined, agentStudio: boolean): boolean;
+/**
+ * Pulls `message` or `error` from Agent Studio JSON payloads, including double-encoded JSON
+ * and objects serialized with escaped quotes (`{\"error\": \"...\"}`).
+ */
+declare function extractAgentStudioErrorFieldMessage(raw: string): string | undefined;
+/**
+ * Prefer the API `message` when the body was JSON; otherwise the thrown message (without a trailing `(AI-xxx)` suffix).
+ * Only meaningful when {@link isAskAiPromptBlockingError} would return true for this error.
+ */
+declare function getAskAiPromptBlockingUserFacingMessage(error?: Error): string | undefined;
+/**
+ * Message shown in the top blocking banner (parsed API text, never raw JSON when avoidable).
+ */
+declare function getAskAiBlockingBannerMessage(error?: Error): string | undefined;
+/**
+ * Prefer the API `message` field when the error body is JSON; otherwise the thrown message string.
+ * Only meaningful when {@link isThreadDepthError} is true.
+ */
+declare function getThreadDepthErrorUserFacingMessage(error?: Error): string | undefined;
+
+/**
+ * Registry of Agent Studio prompt-blocking matchers (cost controls, access, limits).
+ * Add cases here instead of scattering regex across call sites.
+ * Set `showNewConversationLink` to false to omit the “Start a new conversation … to continue” row when starting over does not fix the issue (for example, domain allowlisting).
+ */
+type AgentStudioBlockingMatchContext = {
+    message: string;
+    messageLower: string;
+    parsedJson: Record<string, unknown> | null;
+    extractedCodeUpper: string | undefined;
+};
+type AgentStudioPromptBlockingMatcher = {
+    matches: (ctx: AgentStudioBlockingMatchContext) => boolean;
+    showNewConversationLink?: boolean;
+};
+/** Agent Studio cost / access control codes that block further input. */
+declare const AGENT_STUDIO_PROMPT_BLOCKING_CODES: Set<string>;
+declare function readAgentStudioJsonStringField(o: Record<string, unknown>, key: string): string | undefined;
+declare function extractAiErrorCodeFromMessage(message: string): string | undefined;
+/** Plain-text / stringified JSON heuristic; JSON-shaped payloads still use `isThreadDepthError` in `ai.ts`. */
+declare function matchesThreadDepthLimitError(normalizedMessage: string): boolean;
+/** API copy for domain allowlisting — starting a new conversation does not resolve it. */
+declare function matchesRequestBlockedForThisDomainMessage(normalizedMessage: string): boolean;
+declare function matchesAgentStudioMaxStepsMessage(normalizedMessage: string): boolean;
+declare function matchesAgentStudioRateLimitMessage(normalizedMessage: string): boolean;
+declare function matchesAgentStudioTokenOutputLimitPlainMessage(message: string): boolean;
+declare function matchesAgentStudioWhitelistOrNotAllowedDomainPlainMessage(normalizedMessage: string): boolean;
+declare function matchesAgentStudioContextOrTokenLimitsPlainMessage(normalizedMessage: string): boolean;
+/**
+ * Ordered registry: first match does not win alone — `resolveAgentStudioPromptBlocking`
+ * OR-combines blocking and AND-combines “show new conversation” (any `false` hides the row).
+ */
+declare const agentStudioPromptBlockingMatchers: AgentStudioPromptBlockingMatcher[];
+declare function resolveAgentStudioPromptBlocking(error: Error): {
+    blocking: boolean;
+    showNewConversationLink: boolean;
+};
+/**
+ * Plain-text matchers over `Error.message.toLowerCase()` (callers pass `error.message.toLowerCase()`).
+ * Conversation depth / AI-217: first entry mirrors common plain cases; JSON-shaped payloads still need `isThreadDepthError` in `ai.ts`.
+ *
+ * Blocking UX and “Start new conversation” visibility are driven by `agentStudioPromptBlockingMatchers`.
+ */
+type NewConversationErrorMatcher = (normalizedMessage: string) => boolean;
+declare const newConversationErrorMatchers: NewConversationErrorMatcher[];
+
 type DocSearchTranslations = Partial<{
     button: ButtonTranslations;
     modal: ModalTranslations;
@@ -278,6 +370,8 @@ interface DocSearchProps {
     indices?: Array<DocSearchIndex | string>;
     /**
      * Configuration or assistant id to enable ask ai mode. Pass a string assistant id or a full config object.
+     *
+     * @deprecated Ask AI is being migrated from a standalone DocSearch feature into Algolia's Agent Studio. The `askAi` prop will be removed in DocSearch v5.
      */
     askAi?: DocSearchAskAi | string;
     /**
@@ -457,11 +551,7 @@ type AskAiScreenTranslations = Partial<{
      */
     errorTitleText: string;
     /**
-     * Message shown when thread depth limit is exceeded (AI-217 error).
-     */
-    threadDepthExceededMessage: string;
-    /**
-     * Button text for starting a new conversation after thread depth error.
+     * Button text for starting a new conversation after a blocking Ask AI error.
      */
     startNewConversationButtonText: string;
 }>;
@@ -561,7 +651,7 @@ interface UseDocSearchKeyboardEventsProps {
 }
 declare function useDocSearchKeyboardEvents({ isOpen, onOpen, onClose, isAskAiActive, onAskAiToggle, keyboardShortcuts, }: UseDocSearchKeyboardEventsProps): void;
 
-declare const version = "4.6.2";
+declare const version = "4.7.0";
 
-export { DocSearch, DocSearchButton, DocSearchInner, DocSearchModal, useDocSearchKeyboardEvents, version };
-export type { AgentStudioSearchParameters, AskAiSearchParameters, ButtonTranslations, DocSearchAskAi, DocSearchButtonProps, DocSearchHit, DocSearchIndex, DocSearchModalProps, DocSearchProps, DocSearchState, DocSearchTheme, DocSearchTransformClient, DocSearchTranslations, InternalDocSearchHit, KeyboardShortcuts, ModalTranslations, StoredAskAiMessage, StoredAskAiState, StoredDocSearchHit, SuggestedQuestion, SuggestedQuestionHit, UseDocSearchKeyboardEventsProps };
+export { AGENT_STUDIO_PROMPT_BLOCKING_CODES, DocSearch, DocSearchButton, DocSearchInner, DocSearchModal, agentStudioPromptBlockingMatchers, extractAgentStudioErrorFieldMessage, extractAiErrorCodeFromMessage, filterExchangesForThreadDepthError, getAskAiBlockingBannerMessage, getAskAiPromptBlockingUserFacingMessage, getThreadDepthErrorUserFacingMessage, isAgentStudioTokenOutputLimitError, isAskAiPromptBlockingError, isThreadDepthError, matchesAgentStudioContextOrTokenLimitsPlainMessage, matchesAgentStudioMaxStepsMessage, matchesAgentStudioRateLimitMessage, matchesAgentStudioTokenOutputLimitPlainMessage, matchesAgentStudioWhitelistOrNotAllowedDomainPlainMessage, matchesRequestBlockedForThisDomainMessage, matchesThreadDepthLimitError, newConversationErrorMatchers, readAgentStudioJsonStringField, resolveAgentStudioPromptBlocking, showAskAiBlockingBannerNewConversationLink, useDocSearchKeyboardEvents, version };
+export type { AgentStudioBlockingMatchContext, AgentStudioPromptBlockingMatcher, AgentStudioSearchParameters, AskAiSearchParameters, ButtonTranslations, DocSearchAskAi, DocSearchButtonProps, DocSearchHit, DocSearchIndex, DocSearchModalProps, DocSearchProps, DocSearchState, DocSearchTheme, DocSearchTransformClient, DocSearchTranslations, InternalDocSearchHit, KeyboardShortcuts, ModalTranslations, NewConversationErrorMatcher, StoredAskAiMessage, StoredAskAiState, StoredDocSearchHit, SuggestedQuestion, SuggestedQuestionHit, UseDocSearchKeyboardEventsProps };