@accurix/centrinfo-widget 4.0.0 → 5.1.0

package/dist/{types-1ZJJY7Da.d.mts → types-CYFMH8yg.d.cts}

@@ -1,7 +1,362 @@
-import "preact";
+import * as preact0 from "preact";
 
-//#region src/i18n.d.ts
+//#region ../centrinfo-results/src/analytics-explanation.d.ts
 
+/**
+ * Framework-agnostic analytics explanation core.
+ *
+ * Every surface (Liveboard SDK vanilla DOM, the Preact widget and full-page
+ * chat app, and the React dashboard) renders an explanation from the SAME
+ * display model built here, so wording, order and value-status rules never
+ * drift between surfaces. Renderers only map this model onto their own markup
+ * and theme tokens.
+ *
+ * Step-by-step order (fixed):
+ *   1. lead        plain business answer (headline + summary)
+ *   2. comparison  each compared period with its value + status chip
+ *   3. conclusions what the data supports
+ *   4. limits      in-progress / unconfirmed zero / missing period / caveats
+ *   5. checked     "Times in <tz> · Checked <time>"
+ *   6. investigate causes, recommendations, outlook, follow-ups (optional
+ *                  disclosure, collapsed by default)
+ *
+ * Zero is only "confirmed" when the source says so. An empty bucket or an
+ * unconfirmed zero reads as "no records yet" and never produces a % change.
+ *
+ * Pure TypeScript, no DOM or framework imports: safe for every SDK bundle.
+ */
+type AnalyticsExplanationValueStatus = 'observed' | 'confirmed_zero' | 'empty_bucket' | 'unconfirmed_zero' | 'missing';
+interface AnalyticsExplanationPeriodRangeInput {
+  label: string;
+  start?: string;
+  end?: string;
+  timezone?: string;
+}
+interface AnalyticsExplanationEvidenceItemInput {
+  id: string;
+  text: string;
+  kind?: string;
+  metric?: string;
+  period?: AnalyticsExplanationPeriodRangeInput;
+  filters?: string[];
+  value?: number;
+  valueStatus?: AnalyticsExplanationValueStatus | string;
+  statusReason?: string;
+  source?: {
+    kind?: 'card' | 'supporting_query' | string;
+    insightId?: string;
+    queryRunId?: string;
+    liveboardTileId?: string;
+  };
+  checkedAt?: string;
+}
+interface AnalyticsExplanationPeriodInput {
+  evidenceId?: string;
+  label: string;
+  start?: string;
+  end?: string;
+  timezone?: string;
+  current?: boolean;
+  inProgress?: boolean;
+  value?: number;
+  valueText?: string;
+  valueStatus?: AnalyticsExplanationValueStatus | string;
+  statusReason?: string;
+  source?: string;
+}
+interface AnalyticsExplanationMissingInput {
+  evidenceId?: string;
+  label: string;
+  period?: AnalyticsExplanationPeriodRangeInput;
+  reason: string;
+}
+interface AnalyticsExplanationFreshnessInput {
+  status?: string;
+  dataAsOf?: string;
+  expectedThrough?: string;
+  lagDays?: number;
+  checkedAt?: string;
+  timezone?: string;
+}
+/** Structural explanation shape every surface's DTO satisfies. */
+interface AnalyticsExplanationInput {
+  explanationId?: string;
+  conversationalPreface?: string;
+  headline?: string;
+  summary?: string;
+  evidence?: string[];
+  headlineEvidenceIds?: string[];
+  summaryEvidenceIds?: string[];
+  businessMeaningEvidenceIds?: string[];
+  evidenceStatements?: Array<{
+    text: string;
+    evidenceIds?: string[];
+  }>;
+  evidenceItems?: AnalyticsExplanationEvidenceItemInput[];
+  periods?: AnalyticsExplanationPeriodInput[];
+  missing?: AnalyticsExplanationMissingInput[];
+  timezone?: string;
+  checkedAt?: string;
+  currentPeriodInProgress?: boolean;
+  cached?: boolean;
+  dataFreshness?: AnalyticsExplanationFreshnessInput;
+  businessMeaning?: string;
+  possibleDrivers?: Array<{
+    hypothesis: string;
+    howToCheck: string;
+    evidenceIds?: string[];
+  }>;
+  recommendations?: Array<{
+    action: string;
+    why: string;
+    successMetric?: string;
+    evidenceIds?: string[];
+  }>;
+  forecast?: {
+    text: string;
+    qualityStatus?: string;
+    limitations?: string;
+    horizon?: string;
+  };
+  limitations?: string[];
+  followUps?: string[];
+  source?: string;
+  /** "basic" = the free explanation built from the facts; "detailed" = checked AI wording. */
+  level?: 'basic' | 'detailed' | string;
+  /** The detailed AI explanation that loads separately (poll by explanationId). */
+  aiExplanation?: AnalyticsAIExplanationInput | null;
+}
+/** State of the detailed AI explanation, as returned by every surface. */
+type AnalyticsAIExplanationStatus = 'pending' | 'ready' | 'failed' | 'not_requested';
+interface AnalyticsAIExplanationInput {
+  status: AnalyticsAIExplanationStatus | string;
+  explanationId?: string;
+  retryAvailable?: boolean;
+}
+declare const ANALYTICS_EXPLANATION_COPY: {
+  readonly eyebrow: "Answer from your data";
+  readonly provenanceAI: "AI-assisted · evidence checked";
+  readonly provenanceGoverned: "Based on current values";
+  readonly comparison: "Comparison";
+  readonly conclusions: "What we can conclude";
+  readonly whyItMatters: "Why it matters";
+  readonly limits: "Important limits";
+  readonly investigate: "Investigate further";
+  readonly evidenceList: "Evidence checked";
+  readonly causes: "Possible causes";
+  readonly causesHint: "Not proven causes";
+  readonly howToCheck: "How to check:";
+  readonly recommendations: "Recommended next steps";
+  readonly watch: "Watch:";
+  readonly outlook: "Outlook";
+  readonly followUps: "Ask a follow-up";
+  readonly sourceNoteAI: "AI-assisted wording, checked against the live values shown here.";
+  readonly sourceNoteGoverned: "Based only on the live values shown here.";
+  readonly evidence: "Evidence";
+  readonly evidenceMetric: "Metric";
+  readonly evidencePeriod: "Period";
+  readonly evidenceTimezone: "Timezone";
+  readonly evidenceFilters: "Filters";
+  readonly evidenceValue: "Value";
+  readonly evidenceStatus: "Status";
+  readonly evidenceSource: "Source";
+  readonly evidenceChecked: "Checked";
+  readonly openSource: "Open source";
+  readonly closeEvidence: "Close evidence details";
+  readonly citationLabel: "Show evidence";
+  readonly sourceCard: "This card";
+  readonly sourceSupportingQuery: "Supporting query";
+  readonly feedbackPrompt: "Was this explanation helpful?";
+  readonly feedbackHelpful: "Helpful explanation";
+  readonly feedbackNotHelpful: "Unhelpful explanation";
+  readonly feedbackReasonsPrompt: "What went wrong? (optional)";
+  readonly feedbackCommentPlaceholder: "Anything else? (optional)";
+  readonly feedbackSubmit: "Send feedback";
+  readonly feedbackThanks: "Thanks for the feedback.";
+  readonly feedbackUndo: "Undo";
+  readonly feedbackError: "Feedback could not be saved. Try again.";
+  readonly notComparable: "Not comparable yet";
+  readonly basicExplanation: "Basic explanation";
+  readonly preparingDetailed: "Preparing a detailed explanation…";
+  readonly detailedReady: "Detailed explanation ready.";
+  readonly detailedUnavailable: "A detailed explanation is not available right now.";
+  readonly detailedRetry: "Try again";
+  readonly region: "Explanation";
+  readonly inProgress: "in progress";
+  readonly expand: "Expand explanation";
+  readonly collapse: "Collapse explanation";
+  readonly reasonWrongNumbers: "Wrong numbers";
+  readonly reasonMissingComparison: "Missing comparison";
+  readonly reasonUnclear: "Unclear";
+  readonly reasonTooLong: "Too long";
+};
+/** The explanation panel's copy with a host's overrides on top. */
+type AnalyticsExplanationCopyOverrides = Partial<{ -readonly [K in keyof typeof ANALYTICS_EXPLANATION_COPY]: string }>;
+type AnalyticsComparisonBasis = 'complete' | 'like_for_like' | 'current_in_progress_no_time' | 'not_comparable';
+interface AnalyticsComparisonPeriod {
+  label: string;
+  start?: string;
+  end?: string;
+  fullEnd?: string;
+  inProgress?: boolean;
+  toDate?: boolean;
+}
+/** Backend `periodComparison` (reader-safe projection). */
+interface AnalyticsPeriodComparison {
+  comparisonBasis: AnalyticsComparisonBasis | string;
+  reason?: string;
+  grain?: string;
+  measureField?: string;
+  seriesField?: string;
+  currentPeriod?: AnalyticsComparisonPeriod;
+  previousPeriod?: AnalyticsComparisonPeriod;
+  currentValue?: number;
+  previousToDateValue?: number;
+  previousFullValue?: number;
+  cutoffAt?: string;
+  cutoffSource?: 'now' | 'data_as_of' | string;
+  timezone?: string;
+  series?: Array<{
+    key: string;
+    currentValue?: number;
+    previousToDateValue?: number;
+    previousFullValue?: number;
+  }>;
+}
+interface AnalyticsComparisonDisplay {
+  basis: AnalyticsComparisonBasis | string;
+  kind: 'change' | 'neutral';
+  /** Set only for like-for-like (or complete) changes: red/green allowed. */
+  percent?: number;
+  tone: 'positive' | 'negative' | 'neutral';
+  /** Badge text: "↑ 50.0%", "Up from 0", "Today so far: 6 · Yesterday: 26 (full day)". */
+  label: string;
+  /** "vs yesterday at this time" / "vs same point last week". */
+  copy: string;
+  /** "Yesterday full day: 26". */
+  secondary?: string;
+  /** Compact one-line form for KPI cards: "Full day: 26". */
+  compactSecondary?: string;
+  /** Hover text with the cutoff time. */
+  title?: string;
+  reason?: string;
+}
+interface AnalyticsGroupComparisonPoint {
+  side: 'current' | 'previous';
+  basis: string;
+  /** Value to plot: previous-to-date on a like-for-like previous bucket. */
+  plotValue?: number;
+  /** Previous bucket: the full previous value (tooltip). */
+  fullValue?: number;
+  /** Previous bucket plotted at the same point (label "Yesterday at this time"). */
+  toDate: boolean;
+  /** Current bucket: this group's change, following the KPI basis rules. */
+  display?: AnalyticsComparisonDisplay;
+}
+/**
+ * Poll response for a detailed AI explanation. `explanation` is set only when
+ * `status` is "ready" and is the CHECKED explanation (never raw model text).
+ */
+interface AnalyticsAIExplanationJob<E extends AnalyticsExplanationInput> {
+  status: AnalyticsAIExplanationStatus | string;
+  explanationId?: string;
+  retryAvailable?: boolean;
+  explanation?: E | null;
+  /**
+   * The free basic explanation as updated by the background job (it gains the
+   * baseline sentence, e.g. "within the recent range of 22–28"). Present while
+   * the AI explanation is pending or after it failed.
+   */
+  basic?: E | null;
+}
+interface AnalyticsAIExplanationTransport<E extends AnalyticsExplanationInput> {
+  /** GET the job by id with the surface's own credentials. */
+  poll: (explanationId: string, signal?: AbortSignal) => Promise<AnalyticsAIExplanationJob<E>>;
+  /** "Try again": re-request with the retry flag. Omit when retry is impossible. */
+  retry?: (explanationId: string, signal?: AbortSignal) => Promise<AnalyticsAIExplanationJob<E>>;
+  /** The job reached a final status: let the surface remember it (status only, not the payload). */
+  settled?: (explanationId: string, status: 'ready' | 'failed' | 'not_requested') => void;
+}
+//#endregion
+//#region ../centrinfo-results/src/labels.d.ts
+type AnalyticsExplanationCopy = Required<AnalyticsExplanationCopyOverrides>;
+/** Every string the shared result renderer shows. Hosts override any subset. */
+interface ResultLabels {
+  resultDetails: string;
+  liveMetric: string;
+  currentValue: string;
+  noMatchTitle: string;
+  noMatchBody: string;
+  chartType: string;
+  chooseChartType: string;
+  aggregate: string;
+  aggregateTitle: string;
+  aggregateCharge: string;
+  chartFallback: string;
+  chartLine: string;
+  chartBar: string;
+  chartStackedBar: string;
+  chartLineHint: string;
+  chartBarHint: string;
+  chartStackedBarHint: string;
+  aggregationSum: string;
+  aggregationAvg: string;
+  aggregationMin: string;
+  aggregationMax: string;
+  aggregationCount: string;
+  aggregationCountDistinct: string;
+  download: string;
+  downloadData: string;
+  expandTable: string;
+  expandChart: string;
+  restoreView: string;
+  aboutResult: string;
+  aboutPeriod: string;
+  aboutResults: string;
+  aboutChecked: string;
+  aboutTimezone: string;
+  aboutSourceData: string;
+  aboutFilters: string;
+  /** `{count}` placeholder. */
+  rowOne: string;
+  rowMany: string;
+  filtersOne: string;
+  filtersMany: string;
+  filtersApplied: string;
+  notSet: string;
+  noValue: string;
+  yes: string;
+  no: string;
+  chartValues: string;
+  /** `{measure}`, `{dimension}`. */
+  chartTitle: string;
+  seriesLimited: string;
+  summaryLatest: string;
+  summaryNoTrend: string;
+  summaryHighest: string;
+  summaryNoComparison: string;
+  zoomControls: string;
+  zoomIn: string;
+  zoomOut: string;
+  zoomReset: string;
+  zoomResetShort: string;
+  zoomNone: string;
+  zoomAllOne: string;
+  zoomAllMany: string;
+  zoomRange: string;
+  inProgress: string;
+  newContent: string;
+  updatedAt: string;
+  liveData: string;
+  viewData: string;
+  hideData: string;
+  inProgressLegend: string;
+  /** Overrides for the explanation panel copy. */
+  explanation?: Partial<AnalyticsExplanationCopy>;
+  governedResult: string;
+}
+//#endregion
+//#region src/i18n.d.ts
 /**
  * Every user-visible chrome string in one place. The widget ships English
  * defaults; a host localises by passing `labels` to `Centrinfo.init()` —
@@ -11,6 +366,12 @@ import "preact";
  * never produces.
  */
 interface WidgetStrings {
+  /**
+   * Labels for analytics answers (KPI, chart, table, details, explanation).
+   * Any subset overrides the English defaults; `explanation` holds the
+   * explanation panel's wording.
+   */
+  analytics?: Partial<ResultLabels>;
   /** Optional full-page labels. Older integrations use the core labels as fallbacks. */
   fullPageNewConversation?: string;
   fullPageHistory?: string;
@@ -36,6 +397,10 @@ interface WidgetStrings {
   /** Header presence line when bootstrap was loaded with `offline`. */
   statusOffline: string;
   liveSupport: string;
+  /** Button on the "teammate left, the AI is back" notice. */
+  reconnectSupport: string;
+  /** Message that opens the live-support form again after reconnecting. */
+  reconnectPrompt: string;
   waitingForTeam: string;
   assistantName: string;
   chatName: string;
@@ -59,6 +424,8 @@ interface WidgetStrings {
   reopenVoiceChat: string;
   voiceConnecting: string;
   voiceListening: string;
+  voiceHearing: string;
+  voiceUnavailable: string;
   voiceProcessing: string;
   voiceSpeaking: string;
   voiceNoise: string;
@@ -95,6 +462,7 @@ interface WidgetStrings {
   /** Per-message 👍/👎 feedback. */
   feedbackHelpful: string;
   feedbackNotHelpful: string;
+  feedbackAnswerPrompt: string;
   feedbackThanks: string;
   /** End-of-chat CSAT prompt. */
   csatPrompt: string;
@@ -110,10 +478,23 @@ interface WidgetStrings {
   emptyReply: string;
   errorGeneric: string;
   errorRateLimit: string;
+  /** Shown in place of an analytics result that is not kept in local storage. */
+  resultExpired: string;
   attaching: string;
   attachTooLarge: string;
   attachFailed: string;
+  attachPreviewTitle: string;
+  attachOpen: string;
+  attachDownload: string;
+  attachPreviewClose: string;
+  attachPreviewLoading: string;
+  attachPreviewFailed: string;
+  attachPreviewUnsupported: string;
+  attachAnalysisFailed: string;
   removeAttachment: string;
+  attachLimit: string;
+  attachedFiles: string;
+  removeAttachmentNamed: string;
   dropFileHere: string;
   clearDeviceData: string;
   clearDeviceDataBody: string;
@@ -129,6 +510,8 @@ interface WidgetStrings {
   /** Generic action-form success fallback + error. */
   formThanks: string;
   formError: string;
+  /** Case number appended to a confirmation. `{reference}` is the case number. */
+  caseReference: string;
   /** Public action drawer chrome. Action-specific copy remains descriptor data. */
   actionContactOptions: string;
   actionGetInTouch: string;
@@ -146,6 +529,7 @@ interface WidgetStrings {
   bookingPickDay: string;
   bookingPickTimeLabel: string;
   bookingDuration: string;
+  bookingCallbackDuration: string;
   bookingTimezone: string;
   bookingSchedulerFallback: string;
   bookingCheckingAvailability: string;
@@ -157,6 +541,11 @@ interface WidgetStrings {
   bookingNotOffered: string;
   /** Confirmation after requesting a demo. `{when}` = the chosen slot. */
   bookingRequested: string;
+  /** The request was retained but the calendar provider did not confirm it. */
+  bookingVerificationPending: string;
+  /** Confirmation after requesting a callback. `{when}` = the chosen slot. */
+  bookingCallbackRequested: string;
+  bookingCallbackConfirmed: string;
   /** Confirmation when a real calendar event was created. `{when}` = slot. */
   bookingConfirmed: string;
   /** Shown when the chosen slot was just taken by someone else. */
@@ -166,12 +555,22 @@ interface WidgetStrings {
   bookingViaProvider: string;
   bookingOpenScheduler: string;
   bookingLinkOpened: string;
+  bookingScheduled: string;
+  bookingBackToChat: string;
+  bookingOpenNewTab: string;
+  bookingCloseScheduler: string;
+  bookingLoadingScheduler: string;
   bookingMeetingLink: string;
+  bookingManageLink: string;
+  bookingCheckingDetails: string;
+  bookingDetailsUnavailable: string;
+  bookingRetryDetails: string;
   /** Preview mode (data-preview): canned reply, action note, top banner. */
   previewReply: string;
   previewActionNote: string;
   previewBanner: string;
 }
+declare const StringsProvider: preact0.Provider<WidgetStrings>;
 //#endregion
 //#region src/api/types.d.ts
 /** The result metadata that arrives with (or after) an answer. */
@@ -208,6 +607,9 @@ interface PublicChatAction {
   submitLabel: string;
   fields: PublicChatActionField[];
   delivery: string;
+  /** True when submitting brings a teammate into this chat; false for a
+   *  follow-up by email or phone. Several actions share an endpoint. */
+  liveHandoff?: boolean;
   prompt: string;
   shortLabel: string;
   enabled: boolean;
@@ -217,7 +619,17 @@ interface PublicChatAction {
   /** Client-only compatibility marker. Never emitted by the production catalogue. */
   legacyFallback?: boolean;
 }
+interface LiveAudioSegment {
+  seq: number;
+  /** Empty when the server could not voice the piece; speak `text` instead. */
+  audioBase64: string;
+  mimeType?: string;
+  /** The piece as spoken (no links or markdown). */
+  text?: string;
+}
 interface TurnResult {
+  /** True when the reply was spoken in live pieces (onAudioSegment). */
+  liveAudio?: boolean;
   answer: string;
   sources: Source[];
   suggestedReplies: string[];
@@ -248,6 +660,7 @@ interface AnalyticsVisualizationColumn {
   dataType: 'text' | 'number' | 'currency' | 'percent' | 'boolean' | 'date' | 'datetime';
   semanticRole: 'identifier' | 'dimension' | 'measure' | 'date' | 'geography' | 'boolean';
   aggregation?: 'none' | 'sum' | 'avg' | 'count' | 'count_distinct' | 'min' | 'max';
+  allowedAggregations?: Array<'none' | 'sum' | 'avg' | 'count' | 'count_distinct' | 'min' | 'max'>;
   formatPattern?: string;
   currencyCode?: string;
   description?: string;
@@ -265,21 +678,101 @@ interface AnalyticsVisualizationRecommendation {
   reason?: string;
   confidence?: number;
 }
+type AnalyticsValueStatus = 'observed' | 'confirmed_zero' | 'empty_bucket' | 'unconfirmed_zero' | 'missing';
+interface AnalyticsEvidencePeriod {
+  label: string;
+  start?: string;
+  end?: string;
+  timezone?: string;
+}
+interface AnalyticsExplanationEvidenceItem {
+  id: string;
+  text: string;
+  kind?: string;
+  metric?: string;
+  period?: AnalyticsEvidencePeriod;
+  filters?: string[];
+  value?: number;
+  valueStatus: AnalyticsValueStatus | string;
+  statusReason?: string;
+  source: {
+    kind: 'card' | 'supporting_query' | string;
+    insightId?: string;
+    queryRunId?: string;
+    liveboardTileId?: string;
+  };
+  checkedAt?: string;
+}
+interface AnalyticsExplanationPeriod {
+  evidenceId?: string;
+  label: string;
+  start?: string;
+  end?: string;
+  timezone?: string;
+  current?: boolean;
+  inProgress?: boolean;
+  value?: number;
+  valueText?: string;
+  valueStatus: AnalyticsValueStatus | string;
+  statusReason?: string;
+  source?: 'card' | 'supporting_query' | string;
+}
+interface AnalyticsExplanationMissing {
+  evidenceId?: string;
+  label: string;
+  period?: AnalyticsEvidencePeriod;
+  reason: string;
+}
+interface AnalyticsExplanationDataFreshness {
+  status: string;
+  dataAsOf?: string;
+  expectedThrough?: string;
+  lagDays?: number;
+  checkedAt?: string;
+  timezone?: string;
+}
+interface AnalyticsValueProvenance {
+  rowIndex: number;
+  field: string;
+  period?: string;
+  filled: 'empty_bucket' | string;
+  status: 'empty_bucket' | 'confirmed_zero' | 'unconfirmed_zero' | string;
+  reason?: string;
+}
 interface AnalyticsVisualizationExplanation {
+  /** Stable opaque id; used only for "Was this helpful?" feedback. */
+  explanationId?: string;
   conversationalPreface?: string;
   metricReference?: string;
   headline: string;
   summary: string;
   evidence?: string[];
+  headlineEvidenceIds?: string[];
+  summaryEvidenceIds?: string[];
+  businessMeaningEvidenceIds?: string[];
+  evidenceStatements?: Array<{
+    text: string;
+    evidenceIds?: string[];
+  }>;
+  evidenceItems?: AnalyticsExplanationEvidenceItem[];
+  periods?: AnalyticsExplanationPeriod[];
+  missing?: AnalyticsExplanationMissing[];
+  timezone?: string;
+  checkedAt?: string;
+  currentPeriodInProgress?: boolean;
+  cached?: boolean;
+  dataFreshness?: AnalyticsExplanationDataFreshness;
   businessMeaning?: string;
   possibleDrivers?: Array<{
     hypothesis: string;
     howToCheck: string;
+    evidenceIds?: string[];
   }>;
   recommendations?: Array<{
     action: string;
     why: string;
     successMetric?: string;
+    evidenceIds?: string[];
   }>;
   forecast?: {
     text: string;
@@ -290,6 +783,12 @@ interface AnalyticsVisualizationExplanation {
   limitations?: string[];
   followUps?: string[];
   source: 'governed_result' | 'ai_grounded' | 'rag_deterministic_analysis' | 'analysis_contract' | string;
+  /** The detailed AI explanation that loads separately (poll by explanationId). */
+  aiExplanation?: {
+    status: string;
+    explanationId?: string;
+    retryAvailable?: boolean;
+  } | null;
 }
 interface AnalyticsVisualizationAnalysis {
   summary: string;
@@ -419,6 +918,7 @@ interface AnalyticsVisualization {
   tableAvailable?: boolean;
   downloadAvailable?: boolean;
   explanation?: AnalyticsVisualizationExplanation;
+  valueProvenance?: AnalyticsValueProvenance[];
 }
 interface SpeechResult {
   providerReady: boolean;
@@ -433,6 +933,9 @@ interface LiveEvent {
   content: string;
   authorName?: string;
   createdAt: string;
+  /** On an ai_handback notice: the visitor had asked for a person, so offer
+   *  to bring one back. */
+  reconnectOffered?: boolean;
 }
 interface LiveEventsResult {
   mode: 'ai' | 'queued' | 'human';
@@ -448,6 +951,8 @@ interface AuthenticatedHistoryMessage {
   content: string;
   authorName?: string;
   messageType?: string;
+  /** On an ai_handback notice: the visitor had asked for a person. */
+  reconnectOffered?: boolean;
   sources?: Array<{
     title?: string;
     url?: string;
@@ -470,9 +975,22 @@ interface AuthenticatedHistoryResult {
 interface StreamCallbacks {
   /** Called with each incremental text chunk. */
   onChunk: (text: string) => void;
+  /** The answer text and metadata have arrived; optional reply audio may follow. */
+  onTextReady?: () => void;
+  /** Live answers: what was streamed so far is replaced by a newer answer. */
+  onReset?: () => void;
+  /** Live answers: one spoken piece of the reply, in order, while it is still
+   *  being written. Older backends send a single whole-reply clip instead. */
+  onAudioSegment?: (segment: LiveAudioSegment) => void;
   signal?: AbortSignal;
   /** True only for turns sent from the active Speak-with-AI call. */
   voicePlaybackRequested?: boolean;
+  /** Stable id of the visitor's message. A retry sends the same id, so the
+   *  backend answers and bills the turn once. */
+  clientMessageId?: string;
+  attachmentId?: string;
+  /** Every stored file sent with this message. */
+  attachmentIds?: string[];
 }
 interface ActionResult {
   ok: boolean;
@@ -481,15 +999,33 @@ interface ActionResult {
    * a real calendar event was created (event mode) or a Calendly link was
    * resolved (link mode). Absent when it fell back to a staff-follow-up request. */
   booking?: DemoBooking;
+  /** Case number for a request staff will follow up on (support, demo, callback). */
+  caseReference?: string;
+  /** Inquiry receiving this booking receipt; used to confirm hosted Calendly completion. */
+  inquiryId?: string;
 }
 /** Outcome of a live book-a-demo (mirrors backend services.PublicDemoBooking). */
 interface DemoBooking {
   mode: 'event' | 'link';
   provider: string;
   confirmed?: boolean;
+  /** The request and slot were retained, but the provider outcome could not be verified. */
+  verificationPending?: boolean;
   eventLink?: string;
   meetingUrl?: string;
   schedulingLink?: string;
+  cancelUrl?: string;
+  rescheduleUrl?: string;
+  startAt?: string;
+  endAt?: string;
+  timezone?: string;
+  title?: string;
+}
+interface HostedBookingConfirmation {
+  sessionId: string;
+  inquiryId: string;
+  eventUri: string;
+  inviteeUri: string;
 }
 /** A 👍/👎 a visitor left on one assistant reply (POST /public-chat/feedback). */
 interface FeedbackInput {
@@ -503,6 +1039,31 @@ interface FeedbackInput {
   question?: string;
   answer?: string;
 }
+/** "Was this helpful?" vote on one analytics explanation
+ * (POST /public-chat/explanation-feedback). One vote per visitor session per
+ * explanation; `clear` removes it. Never billed. */
+interface ExplanationFeedbackInput {
+  sessionId: string;
+  explanationId: string;
+  rating: 'up' | 'down' | 'clear';
+  reasons?: Array<'wrong_numbers' | 'missing_comparison' | 'unclear' | 'too_long'>;
+  comment?: string;
+  modelId?: string;
+  modelVersion?: number;
+  /** Which public surface showed the explanation. */
+  surface?: 'widget' | 'chat_app';
+}
+/** Detailed AI explanation job for an analytics answer
+ * (GET /public-chat/analytics-explanations/:id). `explanation` is set only
+ * when ready and is the checked, public-safe explanation. */
+interface ExplanationJob {
+  status: 'pending' | 'ready' | 'failed' | 'not_requested' | string;
+  explanationId?: string;
+  retryAvailable?: boolean;
+  explanation?: Record<string, unknown> | null;
+  /** The free basic explanation as updated by the job (gains the baseline sentence). */
+  basic?: Record<string, unknown> | null;
+}
 /** A [start, end) window the org's calendar is busy. */
 interface BusyRange {
   start: string;
@@ -541,21 +1102,24 @@ interface Transport {
   stream(question: string, sessionId: string, cb: StreamCallbacks): Promise<TurnResult>;
   /** Poll for staff/system events after a timestamp during live handoff. */
   liveEvents(sessionId: string, after: string): Promise<LiveEventsResult>;
+  /** Short-lived signal that this chat is open in a visible browser tab. */
+  presence(sessionId: string): Promise<void>;
   /** Soft visitor typing hint for the staff console. */
   typing(sessionId: string, isTyping: boolean): Promise<void>;
   action(type: string, payload: Record<string, unknown>, endpointOverride?: string): Promise<ActionResult>;
+  confirmHostedBooking?(input: HostedBookingConfirmation): Promise<DemoBooking>;
   /** Synthesize short widget UI prompts through the token's configured TTS voice. */
   speak(text: string): Promise<SpeechResult>;
   transcribe(audioBase64: string, mimeType: string, languageHint?: string, durationSeconds?: number): Promise<string>;
   /** Preferred binary voice upload. Optional for backward-compatible custom transports. */
+  /** A file the visitor attached to this conversation, for preview. */
+  fetchAttachment?(attachmentId: string, sessionId: string): Promise<Blob>;
   transcribeAudio?(audio: Blob, mimeType: string, languageHint?: string, durationSeconds?: number): Promise<string>;
-  /**
-   * Extract text from a visitor-attached image / PDF via the backend's
-   * multimodal endpoint (`POST /public-chat/extract`). The returned text is
-   * prepended to the visitor's next message so the AI can answer about it.
-   * Resolves to '' when extraction is unavailable / fails.
-   */
-  extract(fileBase64: string, mimeType: string, filename?: string): Promise<string>;
+  uploadAttachment?(fileBase64: string, mimeType: string, filename: string, sessionId: string, analyze: boolean): Promise<{
+    id: string;
+    text: string;
+    analysisFailed: boolean;
+  }>;
   /** Search GIFs (Tenor). Returns [] when no key is configured. */
   searchGifs(query: string): Promise<GifResult[]>;
   /**
@@ -577,6 +1141,13 @@ interface Transport {
   /** Record a 👍/👎 on an assistant reply (`POST /public-chat/feedback`).
    * Best-effort — a failed rating never disrupts the chat. */
   sendFeedback(input: FeedbackInput): Promise<void>;
+  /** Record a vote on an analytics explanation. Rejects on failure so the UI
+   * can offer a retry (unlike `sendFeedback`). Optional for custom transports. */
+  sendExplanationFeedback?(input: ExplanationFeedbackInput): Promise<void>;
+  /** Poll the detailed AI explanation of an analytics answer. Optional. */
+  fetchExplanation?(explanationId: string, sessionId: string, surface?: 'widget' | 'chat_app', signal?: AbortSignal): Promise<ExplanationJob>;
+  /** "Try again" on a failed detailed AI explanation. Optional. */
+  retryExplanation?(explanationId: string, sessionId: string, surface?: 'widget' | 'chat_app'): Promise<ExplanationJob>;
 }
 //#endregion
 //#region src/types.d.ts
@@ -649,6 +1220,11 @@ interface WidgetConfig {
   labels?: Partial<WidgetStrings>;
   /** Locale used to select a translation bundle. Defaults to browser locale. */
   locale?: string;
+  /**
+   * Text direction. `auto` (default) follows the locale: Arabic, Hebrew,
+   * Persian, Urdu and similar scripts render right-to-left.
+   */
+  dir?: 'ltr' | 'rtl' | 'auto';
   /**
    * Translation data keyed by locale (`fr`, `fr-CA`, `yo`, ...). Exact locale
    * wins, then its base language. Explicit `labels` still wins over the pack.
@@ -748,6 +1324,14 @@ interface WidgetConfig {
     role: 'user' | 'assistant';
     content: string;
   }) => void;
+  /** Called only for a server-cited source in a signed analytics answer.
+   * The host should open it through its authorized analytics client. */
+  onOpenAnalyticsSource?: (source: {
+    kind: 'liveboard_tile' | 'insight';
+    id: string;
+    /** Result filters for a host to validate against the destination board. */
+    appliedFilters?: AnalyticsVisualization['appliedFilters'];
+  }) => void;
   onAction?: (action: string) => void;
   onHandoff?: () => void;
 }
@@ -848,7 +1432,7 @@ interface WidgetHandle {
 }
 /** A rendered chat message. */
 interface ChatArtifact {
-  type: 'image' | 'resource_link' | 'visualization';
+  type: 'image' | 'video' | 'resource_link' | 'visualization';
   name?: string;
   title?: string;
   caption?: string;
@@ -860,6 +1444,12 @@ interface ChatArtifact {
   /** Local compatibility bridge for the existing governed analytics result. */
   visualization?: AnalyticsVisualization;
 }
+/** A file sent with a visitor message. */
+interface MessageAttachment {
+  /** The stored attachment, when it was uploaded. */
+  id?: string;
+  name: string;
+}
 interface ChatMessage {
   id: string;
   role: 'user' | 'assistant' | 'system';
@@ -868,12 +1458,21 @@ interface ChatMessage {
   authorName?: string;
   /** Live handoff event type from the backend, e.g. agent_joined. */
   liveEventType?: string;
+  /** An ai_handback notice that may offer "Reconnect to support". */
+  offerReconnect?: boolean;
+  /** Local assistant message opened by "Reconnect to support". */
+  reconnectOffer?: boolean;
   /** ISO timestamp for server-originated live events. */
   createdAt?: string;
   /** Inline image (e.g. a GIF the visitor sent). Rendered in the bubble. */
   imageUrl?: string;
   /** Name of a file the visitor attached (rendered as a chip on their bubble). */
   attachmentName?: string;
+  /** The stored attachment behind attachmentName, for preview. */
+  attachmentId?: string;
+  /** Every file sent with this message (newer messages; older ones use
+   * attachmentName / attachmentId). */
+  attachments?: MessageAttachment[];
   sources?: Source[];
   suggestedReplies?: string[];
   availableActions?: string[];
@@ -896,6 +1495,10 @@ interface ChatMessage {
   feedback?: 'up' | 'down';
   visualization?: AnalyticsVisualization;
   artifacts?: ChatArtifact[];
+  /** Set on a restored message whose analytics result was not kept in local storage. */
+  resultExpired?: {
+    title?: string;
+  };
 }
 interface Source {
   title?: string;
@@ -959,7 +1562,7 @@ interface BootstrapInfo {
   offline?: boolean;
   /** Book-a-demo scheduler status (present only when book-a-demo is enabled).
    * Drives the demo UX: event-mode → in-widget slot picker that creates a real
-   * calendar event; link-mode → a "Book on Calendly" link; absent/!connected →
+   * calendar event or Calendly invitee; link-mode → a hosted scheduler; absent/!connected →
    * slot picker that just files a request for staff to confirm. */
   scheduler?: SchedulerInfo;
 }
@@ -984,4 +1587,4 @@ interface SchedulerInfo {
   };
 }
 //#endregion
-export { PublicChatActionField as _, Source as a, WidgetConfig as c, WidgetUser as d, ActionResult as f, PublicChatAction as g, GifResult as h, FeaturedLink as i, WidgetHandle as l, DemoSlotsResult as m, ChatArtifact as n, Visitor as o, AnalyticsVisualization as p, ChatMessage as r, WidgetActionTranslation as s, BootstrapInfo as t, WidgetThemeTokens as u, Transport as v, WidgetStrings as y };
+export { StringsProvider as C, AnalyticsExplanationInput as D, AnalyticsAIExplanationTransport as E, AnalyticsGroupComparisonPoint as O, Transport as S, ResultLabels as T, DemoSlotsResult as _, MessageAttachment as a, PublicChatAction as b, Visitor as c, WidgetHandle as d, WidgetThemeTokens as f, DemoBooking as g, AnalyticsVisualization as h, FeaturedLink as i, AnalyticsPeriodComparison as k, WidgetActionTranslation as l, ActionResult as m, ChatArtifact as n, SchedulerInfo as o, WidgetUser as p, ChatMessage as r, Source as s, BootstrapInfo as t, WidgetConfig as u, ExplanationFeedbackInput as v, WidgetStrings as w, PublicChatActionField as x, GifResult as y };