@deepdesk/deepdesk-sdk 19.6.2-beta.12 → 19.6.2-beta.13

package/dist/index.d.mts

@@ -2161,6 +2161,28 @@ interface KnowledgeAssistOptions {
     };
 }
 type OpenAdminFeedbackHandler = (feedbackPath: string) => void | Promise<void>;
+/**
+ * Options for {@link DeepdeskSDK.reloadConversationContext} and
+ * {@link DeepdeskSDK.syncHostConversation}.
+ */
+type ReloadConversationContextOptions = {
+    /** Conversation payload from the host (same shape as {@link DeepdeskSDK.upsertConversation}). */
+    conversation: CreateConversation;
+    /** Optional visitor fields to apply when refreshing metadata on the same session. */
+    visitorInfo?: Partial<VisitorInfo>;
+    /**
+     * When `true`, clears on-screen assistant output after upsert (typical same-conversation refresh).
+     * Visitor info is applied after the clear so it is not wiped with suggestion UI state.
+     */
+    clearDisplayedUi?: boolean;
+};
+/**
+ * Options for {@link DeepdeskSDK.syncHostConversation}: metadata reload plus transcript publish.
+ */
+type SyncHostConversationOptions = ReloadConversationContextOptions & {
+    /** Host-built transcript; forwarded to {@link DeepdeskSDK.publishConversationTranscript}. */
+    messages: ConversationMessage[];
+};
 interface WidgetOptions {
     customStyles?: WidgetCustomStyles;
     showImages?: boolean;
@@ -2696,6 +2718,127 @@ declare class DeepdeskSDK {
      * ```
      */
     resetConversation(): void;
+    /**
+     * Clears on-screen assistant answers and related suggestion UI for the loaded
+     * conversation without unloading it from the store.
+     *
+     * **Preserved:** `conversation.current` (including `id`, `externalId`, and `metadata`),
+     * visitor info, profile configuration, and active handling-time tracking.
+     *
+     * **Reset:** assistant panels, text/style/search/pinned suggestions, entities, and input
+     * fields tied to displayed answers (same slices as after {@link resetConversation}, except
+     * `conversation.current` and handling-time state stay set).
+     *
+     * Does not re-fetch CRM data or post transcript messages. For a host-driven refresh,
+     * use {@link reloadConversationContext} with `clearDisplayedUi: true` and then
+     * {@link publishConversationTranscript}, or {@link syncHostConversation} when no host
+     * logic is needed between those steps.
+     *
+     * **Integrators:** do not dispatch private store actions (for example
+     * `conversation/upsert/fulfilled`) to simulate a refresh; use the public methods above.
+     *
+     * No-op when no conversation is loaded.
+     *
+     * @example
+     * ```typescript
+     * // Same session, only wipe stale suggestions before reposting messages
+     * sdk.clearDisplayedAnswers();
+     * await sdk.publishConversationTranscript(messagesFromCrm);
+     * ```
+     */
+    clearDisplayedAnswers(): void;
+    /**
+     * Applies host-fetched conversation metadata to the current SDK session.
+     *
+     * Upserts via {@link upsertConversation} and optionally clears on-screen assistant UI.
+     * The host must fetch CRM (or other) data itself; this method does not load emails or
+     * transcript text. Call {@link publishConversationTranscript} afterward to push messages
+     * and refresh the conversation query.
+     *
+     * When `clearDisplayedUi` is `true`, {@link clearDisplayedAnswers} runs after the upsert.
+     * If `visitorInfo` is provided, it is applied after upsert (and after the UI clear when
+     * requested) so visitor fields survive reset paths—use this for same-conversation refresh flows.
+     *
+     * When switching to a different conversation, prefer {@link resetConversation} first,
+     * then load or upsert the new conversation.
+     *
+     * @param options - Host conversation payload and optional visitor / UI flags.
+     * @param options.conversation - Metadata to upsert (external id, platform, metadata, etc.).
+     * @param options.visitorInfo - Visitor fields to merge when refreshing the same session.
+     * @param options.clearDisplayedUi - Clear assistant/suggestion UI after upsert (default `false`).
+     *
+     * @example
+     * ```typescript
+     * const conversation = await fetchConversationFromCrm(caseId);
+     * const messages = await fetchEmailsFromCrm(caseId);
+     *
+     * await sdk.reloadConversationContext({
+     *   conversation,
+     *   visitorInfo: { visitorId: contactId, visitorName: contactName },
+     *   clearDisplayedUi: true,
+     * });
+     *
+     * // Optional: host-only widget state (assistant input, etc.)
+     * updateWidgetAssistantInput(...);
+     *
+     * await sdk.publishConversationTranscript(messages);
+     * ```
+     */
+    reloadConversationContext({ conversation, visitorInfo, clearDisplayedUi, }: ReloadConversationContextOptions): Promise<void>;
+    /**
+     * Publishes a host-built transcript for the current conversation.
+     *
+     * Sets the dynamic conversation query to the given messages and, when the array is
+     * non-empty, posts them through {@link postMessages}. Use after
+     * {@link reloadConversationContext} when the host already fetched the latest thread
+     * from an external system.
+     *
+     * @param messages - Transcript lines (`source`, `text`, and other {@link ConversationMessage} fields).
+     *
+     * @example
+     * ```typescript
+     * await sdk.publishConversationTranscript([
+     *   {
+     *     externalId: 'msg-1',
+     *     time: '2024-01-01T12:00:00Z',
+     *     source: 'visitor',
+     *     authorId: 'visitor-1',
+     *     text: 'Hello',
+     *     metadata: null,
+     *   },
+     *   {
+     *     externalId: 'msg-2',
+     *     time: '2024-01-01T12:01:00Z',
+     *     source: 'agent',
+     *     authorId: 'agent-1',
+     *     text: 'Hi, how can I help?',
+     *     metadata: null,
+     *   },
+     * ]);
+     * ```
+     */
+    publishConversationTranscript(messages: ConversationMessage[]): Promise<void>;
+    /**
+     * Convenience wrapper: {@link reloadConversationContext} then {@link publishConversationTranscript}
+     * in one call.
+     *
+     * Use {@link reloadConversationContext} and {@link publishConversationTranscript} separately
+     * when the host must update widget-only state (for example assistant input) or run other
+     * logic between metadata upsert and transcript publish.
+     *
+     * @param options - Same as {@link reloadConversationContext} plus `messages` for the transcript.
+     *
+     * @example
+     * ```typescript
+     * await sdk.syncHostConversation({
+     *   conversation: crmConversation,
+     *   visitorInfo: { visitorId: 'visitor-1', visitorName: 'Jane Doe' },
+     *   clearDisplayedUi: true,
+     *   messages: crmMessages,
+     * });
+     * ```
+     */
+    syncHostConversation({ conversation, messages, visitorInfo, clearDisplayedUi, }: SyncHostConversationOptions): Promise<void>;
     /**
      * Updates SDK configuration settings.
      *
@@ -3728,4 +3871,4 @@ declare function logEvent<T extends keyof SendEventArgumentMap>(event: LogEvent<
 type CSSModule = Record<string, string>;
 declare function useStyles<TStyles extends CSSModule>(componentName: string, defaultStyles: TStyles): TStyles;
 
-export { type AgentInfo, Card, ContentEditableInput, type Conversation, type ConversationAssistantResult, type ConversationMessage, DeepdeskAPI, DeepdeskSDK, type EvaluationAttachment, HTTPClient, InputMediator, type InputOverlayCustomStyles, InputType, KeyboardHint, Label, Locale, type Logger, type MountOptions, type OpenAdminFeedbackHandler, type PinnedMessage, type PlatformConfig, type RootState, Section, SectionList, type SelectionRange, Sources, Suggestion, type SuggestionEventMetrics, SuggestionList, type SuggestionMetrics, TextAreaInput, type TextSuggestion, ToggleButton, type UrlSuggestion, type VisitorInfo, type WidgetCustomStyles, type WidgetOptions, attachFile, authenticateWithKey, createFullRange, createOverlayContainer, createRangeFromOffsets, escapeHTML, formatTextMarkup, getRangeOffsets, getRangeText, insertCKEditor, isHTML, isSupportedInputElement, logEvent, updateContentEditable, updateTextArea, useClickOutsideRoot, useStyles, waitForElementVisibilityChange };
+export { type AgentInfo, Card, ContentEditableInput, type Conversation, type ConversationAssistantResult, type ConversationMessage, DeepdeskAPI, DeepdeskSDK, type EvaluationAttachment, HTTPClient, InputMediator, type InputOverlayCustomStyles, InputType, KeyboardHint, Label, Locale, type Logger, type MountOptions, type OpenAdminFeedbackHandler, type PinnedMessage, type PlatformConfig, type ReloadConversationContextOptions, type RootState, Section, SectionList, type SelectionRange, Sources, Suggestion, type SuggestionEventMetrics, SuggestionList, type SuggestionMetrics, type SyncHostConversationOptions, TextAreaInput, type TextSuggestion, ToggleButton, type UrlSuggestion, type VisitorInfo, type WidgetCustomStyles, type WidgetOptions, attachFile, authenticateWithKey, createFullRange, createOverlayContainer, createRangeFromOffsets, escapeHTML, formatTextMarkup, getRangeOffsets, getRangeText, insertCKEditor, isHTML, isSupportedInputElement, logEvent, updateContentEditable, updateTextArea, useClickOutsideRoot, useStyles, waitForElementVisibilityChange };

package/dist/index.d.ts

@@ -2161,6 +2161,28 @@ interface KnowledgeAssistOptions {
     };
 }
 type OpenAdminFeedbackHandler = (feedbackPath: string) => void | Promise<void>;
+/**
+ * Options for {@link DeepdeskSDK.reloadConversationContext} and
+ * {@link DeepdeskSDK.syncHostConversation}.
+ */
+type ReloadConversationContextOptions = {
+    /** Conversation payload from the host (same shape as {@link DeepdeskSDK.upsertConversation}). */
+    conversation: CreateConversation;
+    /** Optional visitor fields to apply when refreshing metadata on the same session. */
+    visitorInfo?: Partial<VisitorInfo>;
+    /**
+     * When `true`, clears on-screen assistant output after upsert (typical same-conversation refresh).
+     * Visitor info is applied after the clear so it is not wiped with suggestion UI state.
+     */
+    clearDisplayedUi?: boolean;
+};
+/**
+ * Options for {@link DeepdeskSDK.syncHostConversation}: metadata reload plus transcript publish.
+ */
+type SyncHostConversationOptions = ReloadConversationContextOptions & {
+    /** Host-built transcript; forwarded to {@link DeepdeskSDK.publishConversationTranscript}. */
+    messages: ConversationMessage[];
+};
 interface WidgetOptions {
     customStyles?: WidgetCustomStyles;
     showImages?: boolean;
@@ -2696,6 +2718,127 @@ declare class DeepdeskSDK {
      * ```
      */
     resetConversation(): void;
+    /**
+     * Clears on-screen assistant answers and related suggestion UI for the loaded
+     * conversation without unloading it from the store.
+     *
+     * **Preserved:** `conversation.current` (including `id`, `externalId`, and `metadata`),
+     * visitor info, profile configuration, and active handling-time tracking.
+     *
+     * **Reset:** assistant panels, text/style/search/pinned suggestions, entities, and input
+     * fields tied to displayed answers (same slices as after {@link resetConversation}, except
+     * `conversation.current` and handling-time state stay set).
+     *
+     * Does not re-fetch CRM data or post transcript messages. For a host-driven refresh,
+     * use {@link reloadConversationContext} with `clearDisplayedUi: true` and then
+     * {@link publishConversationTranscript}, or {@link syncHostConversation} when no host
+     * logic is needed between those steps.
+     *
+     * **Integrators:** do not dispatch private store actions (for example
+     * `conversation/upsert/fulfilled`) to simulate a refresh; use the public methods above.
+     *
+     * No-op when no conversation is loaded.
+     *
+     * @example
+     * ```typescript
+     * // Same session, only wipe stale suggestions before reposting messages
+     * sdk.clearDisplayedAnswers();
+     * await sdk.publishConversationTranscript(messagesFromCrm);
+     * ```
+     */
+    clearDisplayedAnswers(): void;
+    /**
+     * Applies host-fetched conversation metadata to the current SDK session.
+     *
+     * Upserts via {@link upsertConversation} and optionally clears on-screen assistant UI.
+     * The host must fetch CRM (or other) data itself; this method does not load emails or
+     * transcript text. Call {@link publishConversationTranscript} afterward to push messages
+     * and refresh the conversation query.
+     *
+     * When `clearDisplayedUi` is `true`, {@link clearDisplayedAnswers} runs after the upsert.
+     * If `visitorInfo` is provided, it is applied after upsert (and after the UI clear when
+     * requested) so visitor fields survive reset paths—use this for same-conversation refresh flows.
+     *
+     * When switching to a different conversation, prefer {@link resetConversation} first,
+     * then load or upsert the new conversation.
+     *
+     * @param options - Host conversation payload and optional visitor / UI flags.
+     * @param options.conversation - Metadata to upsert (external id, platform, metadata, etc.).
+     * @param options.visitorInfo - Visitor fields to merge when refreshing the same session.
+     * @param options.clearDisplayedUi - Clear assistant/suggestion UI after upsert (default `false`).
+     *
+     * @example
+     * ```typescript
+     * const conversation = await fetchConversationFromCrm(caseId);
+     * const messages = await fetchEmailsFromCrm(caseId);
+     *
+     * await sdk.reloadConversationContext({
+     *   conversation,
+     *   visitorInfo: { visitorId: contactId, visitorName: contactName },
+     *   clearDisplayedUi: true,
+     * });
+     *
+     * // Optional: host-only widget state (assistant input, etc.)
+     * updateWidgetAssistantInput(...);
+     *
+     * await sdk.publishConversationTranscript(messages);
+     * ```
+     */
+    reloadConversationContext({ conversation, visitorInfo, clearDisplayedUi, }: ReloadConversationContextOptions): Promise<void>;
+    /**
+     * Publishes a host-built transcript for the current conversation.
+     *
+     * Sets the dynamic conversation query to the given messages and, when the array is
+     * non-empty, posts them through {@link postMessages}. Use after
+     * {@link reloadConversationContext} when the host already fetched the latest thread
+     * from an external system.
+     *
+     * @param messages - Transcript lines (`source`, `text`, and other {@link ConversationMessage} fields).
+     *
+     * @example
+     * ```typescript
+     * await sdk.publishConversationTranscript([
+     *   {
+     *     externalId: 'msg-1',
+     *     time: '2024-01-01T12:00:00Z',
+     *     source: 'visitor',
+     *     authorId: 'visitor-1',
+     *     text: 'Hello',
+     *     metadata: null,
+     *   },
+     *   {
+     *     externalId: 'msg-2',
+     *     time: '2024-01-01T12:01:00Z',
+     *     source: 'agent',
+     *     authorId: 'agent-1',
+     *     text: 'Hi, how can I help?',
+     *     metadata: null,
+     *   },
+     * ]);
+     * ```
+     */
+    publishConversationTranscript(messages: ConversationMessage[]): Promise<void>;
+    /**
+     * Convenience wrapper: {@link reloadConversationContext} then {@link publishConversationTranscript}
+     * in one call.
+     *
+     * Use {@link reloadConversationContext} and {@link publishConversationTranscript} separately
+     * when the host must update widget-only state (for example assistant input) or run other
+     * logic between metadata upsert and transcript publish.
+     *
+     * @param options - Same as {@link reloadConversationContext} plus `messages` for the transcript.
+     *
+     * @example
+     * ```typescript
+     * await sdk.syncHostConversation({
+     *   conversation: crmConversation,
+     *   visitorInfo: { visitorId: 'visitor-1', visitorName: 'Jane Doe' },
+     *   clearDisplayedUi: true,
+     *   messages: crmMessages,
+     * });
+     * ```
+     */
+    syncHostConversation({ conversation, messages, visitorInfo, clearDisplayedUi, }: SyncHostConversationOptions): Promise<void>;
     /**
      * Updates SDK configuration settings.
      *
@@ -3728,4 +3871,4 @@ declare function logEvent<T extends keyof SendEventArgumentMap>(event: LogEvent<
 type CSSModule = Record<string, string>;
 declare function useStyles<TStyles extends CSSModule>(componentName: string, defaultStyles: TStyles): TStyles;
 
-export { type AgentInfo, Card, ContentEditableInput, type Conversation, type ConversationAssistantResult, type ConversationMessage, DeepdeskAPI, DeepdeskSDK, type EvaluationAttachment, HTTPClient, InputMediator, type InputOverlayCustomStyles, InputType, KeyboardHint, Label, Locale, type Logger, type MountOptions, type OpenAdminFeedbackHandler, type PinnedMessage, type PlatformConfig, type RootState, Section, SectionList, type SelectionRange, Sources, Suggestion, type SuggestionEventMetrics, SuggestionList, type SuggestionMetrics, TextAreaInput, type TextSuggestion, ToggleButton, type UrlSuggestion, type VisitorInfo, type WidgetCustomStyles, type WidgetOptions, attachFile, authenticateWithKey, createFullRange, createOverlayContainer, createRangeFromOffsets, escapeHTML, formatTextMarkup, getRangeOffsets, getRangeText, insertCKEditor, isHTML, isSupportedInputElement, logEvent, updateContentEditable, updateTextArea, useClickOutsideRoot, useStyles, waitForElementVisibilityChange };
+export { type AgentInfo, Card, ContentEditableInput, type Conversation, type ConversationAssistantResult, type ConversationMessage, DeepdeskAPI, DeepdeskSDK, type EvaluationAttachment, HTTPClient, InputMediator, type InputOverlayCustomStyles, InputType, KeyboardHint, Label, Locale, type Logger, type MountOptions, type OpenAdminFeedbackHandler, type PinnedMessage, type PlatformConfig, type ReloadConversationContextOptions, type RootState, Section, SectionList, type SelectionRange, Sources, Suggestion, type SuggestionEventMetrics, SuggestionList, type SuggestionMetrics, type SyncHostConversationOptions, TextAreaInput, type TextSuggestion, ToggleButton, type UrlSuggestion, type VisitorInfo, type WidgetCustomStyles, type WidgetOptions, attachFile, authenticateWithKey, createFullRange, createOverlayContainer, createRangeFromOffsets, escapeHTML, formatTextMarkup, getRangeOffsets, getRangeText, insertCKEditor, isHTML, isSupportedInputElement, logEvent, updateContentEditable, updateTextArea, useClickOutsideRoot, useStyles, waitForElementVisibilityChange };