@helpai/elements 6.4.9 โ†’ 6.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -46,7 +46,7 @@ interface ClientStorage {
46
46
  /** Removes `key`. No-op if absent. */
47
47
  remove(key: string): void;
48
48
  }
49
- type StringKey = 'launcherOpen' | 'launcherAsk' | 'panelTitle' | 'composerPlaceholder' | 'send' | 'stop' | 'queueMessage' | 'removeQueuedMessage' | 'removeAttachment' | 'suggestedReplies' | 'compactingContext' | 'attach' | 'file' | 'micBlocked' | 'micStart' | 'micStop' | 'expand' | 'collapse' | 'fullscreen' | 'exitFullscreen' | 'popOut' | 'resizeHandle' | 'scrollToBottom' | 'close' | 'moreActions' | 'soundOn' | 'soundOff' | 'language' | 'theme' | 'themeAuto' | 'themeLight' | 'themeDark' | 'textSize' | 'textSizeSmall' | 'textSizeNormal' | 'textSizeLarge' | 'history' | 'historyTitle' | 'historyEmpty' | 'historyLoading' | 'historyBack' | 'historyContinue' | 'loadMoreConversations' | 'conversationLoading' | 'loadPreviousMessages' | 'talkToOperator' | 'connectingOperator' | 'noOperatorAvailable' | 'chattingWithOperator' | 'operatorBadgeTitle' | 'chatNotice' | 'cancelOperatorRequest' | 'loginPrompt' | 'loginAction' | 'loginRequired' | 'loginExpired' | 'loginExpiredGuest' | 'startAsGuest' | 'loggedInAs' | 'loggedIn' | 'dismissLoginPrompt' | 'emailTranscript' | 'emailTranscriptPrompt' | 'emailTranscriptEmailLabel' | 'emailTranscriptSend' | 'emailTranscriptSending' | 'emailTranscriptSent' | 'emailTranscriptAlreadySent' | 'emailTranscriptLimited' | 'emailTranscriptFailed' | 'emailTranscriptNotDelivered' | 'emailTranscriptCancel' | 'emailTranscriptDone' | 'dateToday' | 'dateYesterday' | 'dateLastWeek' | 'dateOlder' | 'newConversation' | 'dropZone' | 'dropZoneRejected' | 'attachmentTooLarge' | 'poweredBy' | 'attachmentTooMany' | 'attachmentMimeRejected' | 'attachmentUploadFailed' | 'errorRetry' | 'errorGeneric' | 'errorRateLimited' | 'errorRateLimitedIn' | 'errorOffline' | 'errorServer' | 'errorOriginNotAllowed' | 'errorMessageTooLong' | 'errorReconnecting' | 'loading' | 'visualPreparing' | 'visualError' | 'visualPartial' | 'visualSoldOut' | 'visualCartEmpty' | 'visualQuantity' | 'visualChoose' | 'thinking' | 'thought' | 'thoughtFor' | 'toolResult' | 'sources' | 'feedbackUp' | 'feedbackDown' | 'feedbackThanks' | 'copy' | 'copied' | 'copyTicketReference' | 'collapseSidebar' | 'expandSidebar' | 'formRequired' | 'formInvalidEmail' | 'formInvalidTel' | 'formInvalidNumber' | 'formOtherPlaceholder' | 'inputRequired' | 'askFallbackQuestion' | 'inputBadge' | 'inputAnswered' | 'inputSkipped' | 'inputSubmit' | 'inputSubmitHint' | 'inputSkip' | 'showOptions' | 'hideOptions' | 'qtypeText' | 'qtypeEmail' | 'qtypePhone' | 'qtypeNumber' | 'qtypeDate' | 'qtypeChooseOne' | 'qtypeChooseAny' | 'qtypeBoolean' | 'confirmYes' | 'confirmNo' | 'approve' | 'reject' | 'approvalPrompt' | 'approvalYourResponse' | 'approvalEditHint' | 'approvalSubmitting' | 'edit' | 'toolParameters' | 'statusAwaiting' | 'statusResponded' | 'statusCompleted' | 'statusDenied' | 'statusAutoApproved' | 'statusAutoDeclined' | 'statusError' | 'statusRunning' | 'statusSuperseded' | 'statusIncomplete' | 'toolStepsFailed' | 'toolStepsNotRun' | 'statusStopped' | 'toolStepsStopped' | 'toolStepsStoppedOne' | 'tabHome' | 'tabConversations' | 'tabHelp' | 'tabNews' | 'modulesEmpty' | 'chatUnavailable' | 'moduleBack' | 'contentLoading' | 'contentHelpful' | 'homeGreeting' | 'homeGreetingNamed' | 'homeGreetingLead' | 'homeSearchPlaceholder' | 'homeAskPlaceholder' | 'homeWhatsNew' | 'homeContentTitle' | 'homeStatus' | 'helpTitle' | 'helpSearchPlaceholder' | 'helpEmpty' | 'helpLoading' | 'helpSearchEmpty' | 'helpShowMore' | 'newsTitle' | 'newsEmpty' | 'newsLoading' | 'newsShowMore' | 'newsUnseen' | 'unread';
49
+ type StringKey = 'launcherOpen' | 'launcherAsk' | 'panelTitle' | 'composerPlaceholder' | 'send' | 'stop' | 'queueMessage' | 'removeQueuedMessage' | 'removeAttachment' | 'suggestedReplies' | 'compactingContext' | 'attach' | 'file' | 'micBlocked' | 'micStart' | 'micStop' | 'expand' | 'collapse' | 'fullscreen' | 'exitFullscreen' | 'popOut' | 'resizeHandle' | 'scrollToBottom' | 'close' | 'moreActions' | 'soundOn' | 'soundOff' | 'language' | 'theme' | 'themeAuto' | 'themeLight' | 'themeDark' | 'textSize' | 'textSizeSmall' | 'textSizeNormal' | 'textSizeLarge' | 'history' | 'historyTitle' | 'historyEmpty' | 'historyLoading' | 'historyBack' | 'historyContinue' | 'loadMoreConversations' | 'conversationLoading' | 'loadPreviousMessages' | 'talkToOperator' | 'connectingOperator' | 'noOperatorAvailable' | 'chattingWithOperator' | 'operatorBadgeTitle' | 'chatNotice' | 'cancelOperatorRequest' | 'loginPrompt' | 'loginAction' | 'loginRequired' | 'loginExpired' | 'loginExpiredGuest' | 'startAsGuest' | 'loggedInAs' | 'loggedIn' | 'dismissLoginPrompt' | 'emailTranscript' | 'emailTranscriptPrompt' | 'emailTranscriptEmailLabel' | 'emailTranscriptSend' | 'emailTranscriptSending' | 'emailTranscriptSent' | 'emailTranscriptAlreadySent' | 'emailTranscriptLimited' | 'emailTranscriptFailed' | 'emailTranscriptNotDelivered' | 'emailTranscriptCancel' | 'emailTranscriptDone' | 'dateToday' | 'dateYesterday' | 'dateLastWeek' | 'dateOlder' | 'newConversation' | 'dropZone' | 'dropZoneRejected' | 'attachmentTooLarge' | 'poweredBy' | 'attachmentTooMany' | 'attachmentMimeRejected' | 'attachmentUploadFailed' | 'errorRetry' | 'errorGeneric' | 'errorRateLimited' | 'errorRateLimitedIn' | 'errorOffline' | 'errorServer' | 'errorOriginNotAllowed' | 'errorMessageTooLong' | 'errorReconnecting' | 'loading' | 'visualPreparing' | 'visualError' | 'visualPartial' | 'visualSoldOut' | 'visualCartEmpty' | 'visualQuantity' | 'visualChoose' | 'thinking' | 'thought' | 'thoughtFor' | 'toolResult' | 'sources' | 'feedbackUp' | 'feedbackDown' | 'feedbackThanks' | 'copy' | 'copied' | 'copyTicketReference' | 'collapseSidebar' | 'expandSidebar' | 'formRequired' | 'formInvalidEmail' | 'formInvalidTel' | 'formInvalidNumber' | 'formOtherPlaceholder' | 'inputRequired' | 'askFallbackQuestion' | 'inputBadge' | 'inputAnswered' | 'inputSkipped' | 'inputSubmit' | 'inputSubmitHint' | 'inputSkip' | 'showOptions' | 'hideOptions' | 'qtypeText' | 'qtypeEmail' | 'qtypePhone' | 'qtypeNumber' | 'qtypeDate' | 'qtypeChooseOne' | 'qtypeChooseAny' | 'qtypeBoolean' | 'confirmYes' | 'confirmNo' | 'approve' | 'decline' | 'changeAnswer' | 'approvalPrompt' | 'approvalEditHint' | 'stepInput' | 'stepWorking' | 'stepWorkingOnIt' | 'stepNeedsYourApproval' | 'stepWaitingForVisitor' | 'stepApproved' | 'stepDeclined' | 'stepReplaced' | 'stepFailed' | 'stepDidNotWork' | 'decidedYouApproved' | 'decidedYouDeclined' | 'decidedVisitorApproved' | 'decidedVisitorDeclined' | 'decidedTeamApproved' | 'decidedTeamDeclined' | 'decidedRulesApproved' | 'decidedRulesDeclined' | 'edit' | 'statusError' | 'toolStepsFailed' | 'statusStopped' | 'toolStepsStopped' | 'toolStepsStoppedOne' | 'tabHome' | 'tabConversations' | 'tabHelp' | 'tabNews' | 'modulesEmpty' | 'chatUnavailable' | 'moduleBack' | 'contentLoading' | 'contentHelpful' | 'homeGreeting' | 'homeGreetingNamed' | 'homeGreetingLead' | 'homeSearchPlaceholder' | 'homeAskPlaceholder' | 'homeWhatsNew' | 'homeContentTitle' | 'homeStatus' | 'helpTitle' | 'helpSearchPlaceholder' | 'helpEmpty' | 'helpLoading' | 'helpSearchEmpty' | 'helpShowMore' | 'newsTitle' | 'newsEmpty' | 'newsLoading' | 'newsShowMore' | 'newsUnseen' | 'unread';
50
50
  /** A partial map for one locale โ€” what overrides look like on the wire. */
51
51
  type LocaleStrings = Partial<Record<StringKey, string>>;
52
52
  /**
@@ -470,6 +470,23 @@ interface PresentationOptions {
470
470
  position?: Position;
471
471
  size?: SizeOptions;
472
472
  }
473
+ /** How a call this page ran (or found cut short) ended, for the `toolResult` event. */
474
+ type PageToolCallStatus = 'completed' | 'failed' | 'interrupted';
475
+ /** A ๐Ÿ‘/๐Ÿ‘Ž reaction on a rateable (assistant/operator) message; `null` clears a prior choice. */
476
+ type FeedbackValue = 'up' | 'down' | null;
477
+ /** The five switches, the same keys on a Deployment (`config.behavior.stepDisplay`) and in a member's Preferences. */
478
+ interface StepDisplay {
479
+ /** Every step appears as one folded line under the reply; off, only the steps that involve the reader do. */
480
+ showSteps: boolean;
481
+ /** Each step opens to its raw input and result. */
482
+ showStepDetails: boolean;
483
+ /** The system that ran a step follows its name: "Ship an order ยท BC Co. back office". */
484
+ showStepSystem: boolean;
485
+ /** Each approval says who decided it, and steps the rules decided show as steps. */
486
+ showDecidedBy: boolean;
487
+ /** A decided approval folds into the steps line; off, it stays in the reply as a card. */
488
+ foldApprovals: boolean;
489
+ }
473
490
  /**
474
491
  * Section: conversation runtime behaviour โ€” auto-open, streaming mode, and the
475
492
  * transcript surface (what renders, how it scrolls, reaction controls).
@@ -481,8 +498,8 @@ interface BehaviorOptions {
481
498
  responseMode?: ResponseMode;
482
499
  /** Show the model's reasoning ("thoughts") as a collapsible block. Default `false`. */
483
500
  showReasoning?: boolean;
484
- /** Show automatic tool/function calls (details + result) in the transcript. Default `false`. */
485
- showToolCalls?: boolean;
501
+ /** How the AI's steps and approvals show; unset keys take the Simple preset. */
502
+ stepDisplay?: Partial<StepDisplay>;
486
503
  /** Show citation sources (web links + document references) in the transcript. Default `false`. */
487
504
  showSources?: boolean;
488
505
  /** Turn OFF the ๐Ÿ‘/๐Ÿ‘Ž feedback controls on rateable (assistant/operator) replies. Unset/`false` = shown (default). */
@@ -719,6 +736,7 @@ interface ToolAnnotations {
719
736
  interface ModelContextTool<TInput = unknown> {
720
737
  /** Letters, digits, `_` and `-` (58 at most; others become `_`). A name registered again replaces the earlier tool. */
721
738
  name: string;
739
+ /** Its name as people read it ("Place your order"): what the visitor's card calls the action. */
722
740
  title?: string;
723
741
  /** When the agent should use it and what it does (1024 characters at most). */
724
742
  description: string;
@@ -729,6 +747,12 @@ interface ModelContextTool<TInput = unknown> {
729
747
  execute(input: TInput, options: {
730
748
  signal: AbortSignal;
731
749
  }): unknown;
750
+ /**
751
+ * For a tool with `consequentialHint`: what the call will do, shown on the visitor's approval card before they decide.
752
+ * Return the cart (`{ lines, totals }`) or order (`{ number, status, items, totals }`) shape the chat's cards draw; it
753
+ * must not change anything. A failed or missing preview leaves the card with the call's own values.
754
+ */
755
+ preview?(input: TInput): unknown;
732
756
  }
733
757
  interface ChatWidgetOptions {
734
758
  /**
@@ -836,6 +860,20 @@ interface ChatWidgetOptions {
836
860
  }
837
861
  /** `true` for any string other than the literal `"false"`. Useful for boolean attrs. */
838
862
  declare function boolAttr(v: string): boolean;
863
+ /** A preset's name (`simple`, `technical`) โ†’ its five step settings; any other value leaves the Deployment's. */
864
+ declare function stepDisplayAttr(v: string): {
865
+ readonly showSteps: false;
866
+ readonly showStepDetails: false;
867
+ readonly showStepSystem: false;
868
+ readonly showDecidedBy: false;
869
+ readonly foldApprovals: true;
870
+ } | {
871
+ readonly showSteps: true;
872
+ readonly showStepDetails: true;
873
+ readonly showStepSystem: true;
874
+ readonly showDecidedBy: true;
875
+ readonly foldApprovals: true;
876
+ } | undefined;
839
877
  /** A whole number of seconds, 0 or more; anything else is left unset so the default applies. */
840
878
  declare function secondsAttr(v: string): number | undefined;
841
879
  /**
@@ -849,11 +887,9 @@ declare const SPECIAL_REACTIVE_ATTRS: readonly ['launcher-label', 'callout-text'
849
887
  * Every flat-attribute table in this file. Single source of truth โ€”
850
888
  * both the runtime parser and `REACTIVE_ATTRS` derive from this list.
851
889
  */
852
- declare const ATTR_TABLES: readonly [readonly [["public-key", "publicKey"], ["ai-agent-deployment-id", "aiAgentDeploymentId"], ["base-url", "baseUrl"], ["agent-api-base-url", "agentApiBaseUrl"], ["data-api-base-url", "dataApiBaseUrl"], ["continue-link", "continueLink"], ["theme", "theme", (v: string) => string]], readonly [["mode", "mode", (v: string) => string], ["position", "position", (v: string) => string]], readonly [["width", "width"], ["height", "height"]], readonly [["response-mode", "responseMode", (v: string) => string], ["start-minimized", "startMinimized", typeof boolAttr], ["show-reasoning", "showReasoning", typeof boolAttr], ["show-tool-calls", "showToolCalls", typeof boolAttr], ["show-sources", "showSources", typeof boolAttr], ["disable-message-feedback", "disableMessageFeedback", typeof boolAttr], ["auto-send-suggestions", "autoSendSuggestions", typeof boolAttr], ["card-answer-wait-seconds", "cardAnswerWaitSeconds", typeof secondsAttr], ["pop-out-url", "popOutUrl"]], readonly [["locale", "locale"]], readonly [["launcher-variant", "variant", (v: string) => string], ["launcher-size", "size", (v: string) => string], ["launcher-icon", "icon"], ["launcher-hidden", "hidden", typeof boolAttr]], readonly [["features-disable-file-upload", "disableFileUpload", typeof boolAttr], ["features-disable-email-transcript", "disableEmailTranscript", typeof boolAttr], ["features-voice", "voice", (v: string) => string]], readonly [["endpoint-upload", "upload"], ["endpoint-transcribe", "transcribe"]], readonly [["user-id", "id"], ["user-email", "email"], ["user-name", "name"]], readonly [["page-area", "area"], ["page-url", "url"], ["page-path", "path"], ["page-title", "title"]]];
890
+ declare const ATTR_TABLES: readonly [readonly [["public-key", "publicKey"], ["ai-agent-deployment-id", "aiAgentDeploymentId"], ["base-url", "baseUrl"], ["agent-api-base-url", "agentApiBaseUrl"], ["data-api-base-url", "dataApiBaseUrl"], ["continue-link", "continueLink"], ["theme", "theme", (v: string) => string]], readonly [["mode", "mode", (v: string) => string], ["position", "position", (v: string) => string]], readonly [["width", "width"], ["height", "height"]], readonly [["response-mode", "responseMode", (v: string) => string], ["start-minimized", "startMinimized", typeof boolAttr], ["show-reasoning", "showReasoning", typeof boolAttr], ["step-display", "stepDisplay", typeof stepDisplayAttr], ["show-sources", "showSources", typeof boolAttr], ["disable-message-feedback", "disableMessageFeedback", typeof boolAttr], ["auto-send-suggestions", "autoSendSuggestions", typeof boolAttr], ["card-answer-wait-seconds", "cardAnswerWaitSeconds", typeof secondsAttr], ["pop-out-url", "popOutUrl"]], readonly [["locale", "locale"]], readonly [["launcher-variant", "variant", (v: string) => string], ["launcher-size", "size", (v: string) => string], ["launcher-icon", "icon"], ["launcher-hidden", "hidden", typeof boolAttr]], readonly [["features-disable-file-upload", "disableFileUpload", typeof boolAttr], ["features-disable-email-transcript", "disableEmailTranscript", typeof boolAttr], ["features-voice", "voice", (v: string) => string]], readonly [["endpoint-upload", "upload"], ["endpoint-transcribe", "transcribe"]], readonly [["user-id", "id"], ["user-email", "email"], ["user-name", "name"]], readonly [["page-area", "area"], ["page-url", "url"], ["page-path", "path"], ["page-title", "title"]]];
853
891
  /** Every attribute `<web-ai-chat>` reads, as written in HTML โ€” the names its JSX typings offer. */
854
892
  type WebAiChatAttributeName = (typeof ATTR_TABLES)[number][number][0] | (typeof SPECIAL_REACTIVE_ATTRS)[number];
855
- /** How a call this page ran (or found cut short) ended, for the `toolResult` event. */
856
- type PageToolCallStatus = 'completed' | 'failed' | 'interrupted';
857
893
  declare const handshakeResponseSchema: z.ZodObject<{
858
894
  deployment: z.ZodObject<{
859
895
  id: z.ZodString;
@@ -923,7 +959,13 @@ declare const handshakeResponseSchema: z.ZodObject<{
923
959
  streaming: "streaming";
924
960
  }>>;
925
961
  showReasoning: z.ZodDefault<z.ZodBoolean>;
926
- showToolCalls: z.ZodDefault<z.ZodBoolean>;
962
+ stepDisplay: z.ZodOptional<z.ZodObject<{
963
+ showSteps: z.ZodOptional<z.ZodBoolean>;
964
+ showStepDetails: z.ZodOptional<z.ZodBoolean>;
965
+ showStepSystem: z.ZodOptional<z.ZodBoolean>;
966
+ showDecidedBy: z.ZodOptional<z.ZodBoolean>;
967
+ foldApprovals: z.ZodOptional<z.ZodBoolean>;
968
+ }, z.core.$strip>>;
927
969
  showSources: z.ZodDefault<z.ZodBoolean>;
928
970
  disableMessageFeedback: z.ZodDefault<z.ZodBoolean>;
929
971
  autoSendSuggestions: z.ZodDefault<z.ZodBoolean>;
@@ -1180,8 +1222,6 @@ declare const handshakeResponseSchema: z.ZodObject<{
1180
1222
  }, z.core.$strict>>;
1181
1223
  }, z.core.$loose>;
1182
1224
  type HandshakeResponse = z.infer<typeof handshakeResponseSchema>;
1183
- /** A ๐Ÿ‘/๐Ÿ‘Ž reaction on a rateable (assistant/operator) message; `null` clears a prior choice. */
1184
- type FeedbackValue = 'up' | 'down' | null;
1185
1225
  /**
1186
1226
  * Payload shape per event. Keyed by event name; use `void` for events that
1187
1227
  * carry no data.