@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.
package/index.d.ts CHANGED
@@ -50,7 +50,7 @@ interface ClientStorage {
50
50
  /** Removes `key`. No-op if absent. */
51
51
  remove(key: string): void;
52
52
  }
53
- 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';
53
+ 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';
54
54
  /** A partial map for one locale โ€” what overrides look like on the wire. */
55
55
  type LocaleStrings = Partial<Record<StringKey, string>>;
56
56
  /**
@@ -516,6 +516,23 @@ interface PresentationOptions {
516
516
  position?: Position;
517
517
  size?: SizeOptions;
518
518
  }
519
+ /** How a call this page ran (or found cut short) ended, for the `toolResult` event. */
520
+ type PageToolCallStatus = 'completed' | 'failed' | 'interrupted';
521
+ /** A ๐Ÿ‘/๐Ÿ‘Ž reaction on a rateable (assistant/operator) message; `null` clears a prior choice. */
522
+ type FeedbackValue = 'up' | 'down' | null;
523
+ /** The five switches, the same keys on a Deployment (`config.behavior.stepDisplay`) and in a member's Preferences. */
524
+ interface StepDisplay {
525
+ /** Every step appears as one folded line under the reply; off, only the steps that involve the reader do. */
526
+ showSteps: boolean;
527
+ /** Each step opens to its raw input and result. */
528
+ showStepDetails: boolean;
529
+ /** The system that ran a step follows its name: "Ship an order ยท BC Co. back office". */
530
+ showStepSystem: boolean;
531
+ /** Each approval says who decided it, and steps the rules decided show as steps. */
532
+ showDecidedBy: boolean;
533
+ /** A decided approval folds into the steps line; off, it stays in the reply as a card. */
534
+ foldApprovals: boolean;
535
+ }
519
536
  /**
520
537
  * Section: conversation runtime behaviour โ€” auto-open, streaming mode, and the
521
538
  * transcript surface (what renders, how it scrolls, reaction controls).
@@ -527,8 +544,8 @@ interface BehaviorOptions {
527
544
  responseMode?: ResponseMode;
528
545
  /** Show the model's reasoning ("thoughts") as a collapsible block. Default `false`. */
529
546
  showReasoning?: boolean;
530
- /** Show automatic tool/function calls (details + result) in the transcript. Default `false`. */
531
- showToolCalls?: boolean;
547
+ /** How the AI's steps and approvals show; unset keys take the Simple preset. */
548
+ stepDisplay?: Partial<StepDisplay>;
532
549
  /** Show citation sources (web links + document references) in the transcript. Default `false`. */
533
550
  showSources?: boolean;
534
551
  /** Turn OFF the ๐Ÿ‘/๐Ÿ‘Ž feedback controls on rateable (assistant/operator) replies. Unset/`false` = shown (default). */
@@ -772,6 +789,7 @@ interface ToolAnnotations {
772
789
  interface ModelContextTool<TInput = unknown> {
773
790
  /** Letters, digits, `_` and `-` (58 at most; others become `_`). A name registered again replaces the earlier tool. */
774
791
  name: string;
792
+ /** Its name as people read it ("Place your order"): what the visitor's card calls the action. */
775
793
  title?: string;
776
794
  /** When the agent should use it and what it does (1024 characters at most). */
777
795
  description: string;
@@ -782,6 +800,12 @@ interface ModelContextTool<TInput = unknown> {
782
800
  execute(input: TInput, options: {
783
801
  signal: AbortSignal;
784
802
  }): unknown;
803
+ /**
804
+ * For a tool with `consequentialHint`: what the call will do, shown on the visitor's approval card before they decide.
805
+ * Return the cart (`{ lines, totals }`) or order (`{ number, status, items, totals }`) shape the chat's cards draw; it
806
+ * must not change anything. A failed or missing preview leaves the card with the call's own values.
807
+ */
808
+ preview?(input: TInput): unknown;
785
809
  }
786
810
  interface ChatWidgetOptions {
787
811
  /**
@@ -912,8 +936,8 @@ interface ResolvedOptions {
912
936
  responseMode: ResponseMode;
913
937
  /** Show reasoning ("thoughts") as a collapsible block. Default `false`. */
914
938
  showReasoning: boolean;
915
- /** Show automatic tool calls (details + result) in the transcript. Default `false`. */
916
- showToolCalls: boolean;
939
+ /** How the AI's steps and approvals show: the Deployment's settings over the Simple preset. */
940
+ stepDisplay: StepDisplay;
917
941
  /** Show citation sources (web links + document references) in the transcript. Default `false`. */
918
942
  showSources: boolean;
919
943
  /** Show ๐Ÿ‘/๐Ÿ‘Ž feedback controls on rateable (assistant/operator) replies. Default `true`. */
@@ -1007,8 +1031,6 @@ interface ResolvedOptions {
1007
1031
  onError?: ChatWidgetOptions['onError'];
1008
1032
  }
1009
1033
  type HostMode = 'page' | 'standalone' | 'inline' | 'modal' | 'drawer' | 'fullscreen' | 'expanded' | 'open' | 'closed';
1010
- /** How a call this page ran (or found cut short) ended, for the `toolResult` event. */
1011
- type PageToolCallStatus = 'completed' | 'failed' | 'interrupted';
1012
1034
  /** A single image asset (logo, hero, icon). */
1013
1035
  declare const assetSchema: z.ZodObject<{
1014
1036
  url: z.ZodString;
@@ -1128,7 +1150,13 @@ declare const widgetSettingsSchema: z.ZodObject<{
1128
1150
  streaming: "streaming";
1129
1151
  }>>;
1130
1152
  showReasoning: z.ZodDefault<z.ZodBoolean>;
1131
- showToolCalls: z.ZodDefault<z.ZodBoolean>;
1153
+ stepDisplay: z.ZodOptional<z.ZodObject<{
1154
+ showSteps: z.ZodOptional<z.ZodBoolean>;
1155
+ showStepDetails: z.ZodOptional<z.ZodBoolean>;
1156
+ showStepSystem: z.ZodOptional<z.ZodBoolean>;
1157
+ showDecidedBy: z.ZodOptional<z.ZodBoolean>;
1158
+ foldApprovals: z.ZodOptional<z.ZodBoolean>;
1159
+ }, z.core.$strip>>;
1132
1160
  showSources: z.ZodDefault<z.ZodBoolean>;
1133
1161
  disableMessageFeedback: z.ZodDefault<z.ZodBoolean>;
1134
1162
  autoSendSuggestions: z.ZodDefault<z.ZodBoolean>;
@@ -1407,7 +1435,13 @@ declare const widgetConfigSchema: z.ZodObject<{
1407
1435
  streaming: "streaming";
1408
1436
  }>>;
1409
1437
  showReasoning: z.ZodDefault<z.ZodBoolean>;
1410
- showToolCalls: z.ZodDefault<z.ZodBoolean>;
1438
+ stepDisplay: z.ZodOptional<z.ZodObject<{
1439
+ showSteps: z.ZodOptional<z.ZodBoolean>;
1440
+ showStepDetails: z.ZodOptional<z.ZodBoolean>;
1441
+ showStepSystem: z.ZodOptional<z.ZodBoolean>;
1442
+ showDecidedBy: z.ZodOptional<z.ZodBoolean>;
1443
+ foldApprovals: z.ZodOptional<z.ZodBoolean>;
1444
+ }, z.core.$strip>>;
1411
1445
  showSources: z.ZodDefault<z.ZodBoolean>;
1412
1446
  disableMessageFeedback: z.ZodDefault<z.ZodBoolean>;
1413
1447
  autoSendSuggestions: z.ZodDefault<z.ZodBoolean>;
@@ -1687,7 +1721,13 @@ declare const widgetConfigPartialSchema: z.ZodObject<{
1687
1721
  streaming: "streaming";
1688
1722
  }>>;
1689
1723
  showReasoning: z.ZodDefault<z.ZodBoolean>;
1690
- showToolCalls: z.ZodDefault<z.ZodBoolean>;
1724
+ stepDisplay: z.ZodOptional<z.ZodObject<{
1725
+ showSteps: z.ZodOptional<z.ZodBoolean>;
1726
+ showStepDetails: z.ZodOptional<z.ZodBoolean>;
1727
+ showStepSystem: z.ZodOptional<z.ZodBoolean>;
1728
+ showDecidedBy: z.ZodOptional<z.ZodBoolean>;
1729
+ foldApprovals: z.ZodOptional<z.ZodBoolean>;
1730
+ }, z.core.$strip>>;
1691
1731
  showSources: z.ZodDefault<z.ZodBoolean>;
1692
1732
  disableMessageFeedback: z.ZodDefault<z.ZodBoolean>;
1693
1733
  autoSendSuggestions: z.ZodDefault<z.ZodBoolean>;
@@ -1929,7 +1969,13 @@ declare const widgetSettingsPartialSchema: z.ZodObject<{
1929
1969
  streaming: "streaming";
1930
1970
  }>>;
1931
1971
  showReasoning: z.ZodDefault<z.ZodBoolean>;
1932
- showToolCalls: z.ZodDefault<z.ZodBoolean>;
1972
+ stepDisplay: z.ZodOptional<z.ZodObject<{
1973
+ showSteps: z.ZodOptional<z.ZodBoolean>;
1974
+ showStepDetails: z.ZodOptional<z.ZodBoolean>;
1975
+ showStepSystem: z.ZodOptional<z.ZodBoolean>;
1976
+ showDecidedBy: z.ZodOptional<z.ZodBoolean>;
1977
+ foldApprovals: z.ZodOptional<z.ZodBoolean>;
1978
+ }, z.core.$strip>>;
1933
1979
  showSources: z.ZodDefault<z.ZodBoolean>;
1934
1980
  disableMessageFeedback: z.ZodDefault<z.ZodBoolean>;
1935
1981
  autoSendSuggestions: z.ZodDefault<z.ZodBoolean>;
@@ -2226,7 +2272,13 @@ declare const serverConfigSchema: z.ZodObject<{
2226
2272
  streaming: "streaming";
2227
2273
  }>>;
2228
2274
  showReasoning: z.ZodDefault<z.ZodBoolean>;
2229
- showToolCalls: z.ZodDefault<z.ZodBoolean>;
2275
+ stepDisplay: z.ZodOptional<z.ZodObject<{
2276
+ showSteps: z.ZodOptional<z.ZodBoolean>;
2277
+ showStepDetails: z.ZodOptional<z.ZodBoolean>;
2278
+ showStepSystem: z.ZodOptional<z.ZodBoolean>;
2279
+ showDecidedBy: z.ZodOptional<z.ZodBoolean>;
2280
+ foldApprovals: z.ZodOptional<z.ZodBoolean>;
2281
+ }, z.core.$strip>>;
2230
2282
  showSources: z.ZodDefault<z.ZodBoolean>;
2231
2283
  disableMessageFeedback: z.ZodDefault<z.ZodBoolean>;
2232
2284
  autoSendSuggestions: z.ZodDefault<z.ZodBoolean>;
@@ -2545,7 +2597,13 @@ declare const handshakeResponseSchema: z.ZodObject<{
2545
2597
  streaming: "streaming";
2546
2598
  }>>;
2547
2599
  showReasoning: z.ZodDefault<z.ZodBoolean>;
2548
- showToolCalls: z.ZodDefault<z.ZodBoolean>;
2600
+ stepDisplay: z.ZodOptional<z.ZodObject<{
2601
+ showSteps: z.ZodOptional<z.ZodBoolean>;
2602
+ showStepDetails: z.ZodOptional<z.ZodBoolean>;
2603
+ showStepSystem: z.ZodOptional<z.ZodBoolean>;
2604
+ showDecidedBy: z.ZodOptional<z.ZodBoolean>;
2605
+ foldApprovals: z.ZodOptional<z.ZodBoolean>;
2606
+ }, z.core.$strip>>;
2549
2607
  showSources: z.ZodDefault<z.ZodBoolean>;
2550
2608
  disableMessageFeedback: z.ZodDefault<z.ZodBoolean>;
2551
2609
  autoSendSuggestions: z.ZodDefault<z.ZodBoolean>;
@@ -2802,8 +2860,6 @@ declare const handshakeResponseSchema: z.ZodObject<{
2802
2860
  }, z.core.$strict>>;
2803
2861
  }, z.core.$loose>;
2804
2862
  type HandshakeResponse = z.infer<typeof handshakeResponseSchema>;
2805
- /** A ๐Ÿ‘/๐Ÿ‘Ž reaction on a rateable (assistant/operator) message; `null` clears a prior choice. */
2806
- type FeedbackValue = 'up' | 'down' | null;
2807
2863
  /**
2808
2864
  * Payload shape per event. Keyed by event name; use `void` for events that
2809
2865
  * carry no data.