@helpai/elements 1.4.1 → 1.5.4

package/index.d.ts

@@ -41,7 +41,7 @@ interface ClientStorage {
  * populated {@link Strings} map. UI components then read `strings.send` as a
  * normal property access — no per-render lookup, no per-render allocation.
  */
-type StringKey = 'launcherOpen' | 'launcherLabel' | 'panelTitle' | 'composerPlaceholder' | 'send' | 'stop' | 'queueMessage' | 'removeQueuedMessage' | 'compactingContext' | 'attach' | 'micStart' | 'micStop' | 'micUnsupported' | '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' | 'conversationClosed' | 'startNewConversation' | 'talkToOperator' | 'connectingOperator' | 'noOperatorAvailable' | 'chattingWithOperator' | 'cancelOperatorRequest' | 'dateToday' | 'dateYesterday' | 'dateLastWeek' | 'dateOlder' | 'newConversation' | 'dropZone' | 'attachmentTooLarge' | 'attachmentTooMany' | 'attachmentMimeRejected' | 'errorRetry' | 'errorGeneric' | 'errorRateLimited' | 'loading' | 'visualPreparing' | 'visualError' | 'thinking' | 'thoughts' | 'toolResult' | 'sources' | 'feedbackUp' | 'feedbackDown' | 'feedbackThanks' | 'copy' | 'copied' | 'collapseSidebar' | 'expandSidebar' | 'formSubmit' | 'formSkip' | 'formSubmitted' | 'formSkipped' | 'formFillOut' | 'formRequired' | 'formInvalidEmail' | 'formInvalidTel' | 'formInvalidUrl' | 'formInvalidNumber' | 'formTooShort' | 'formTooLong' | 'formNumberTooSmall' | 'formNumberTooLarge' | 'formPatternMismatch' | 'formChooseAtLeast' | 'formChooseAtMost' | 'formOther' | 'formOtherPlaceholder' | 'inputRequired' | 'inputBadge' | 'inputAnswered' | 'inputSkipped' | 'inputSubmit' | 'inputSubmitHint' | 'inputSkip' | 'showOptions' | 'hideOptions' | 'qtypeText' | 'qtypeEmail' | 'qtypePhone' | 'qtypeNumber' | 'qtypeDate' | 'qtypeChooseOne' | 'qtypeChooseAny' | 'qtypeBoolean' | 'confirmYes' | 'confirmNo' | 'approve' | 'reject' | 'approvalPrompt' | 'approvalBody' | 'approvalYourResponse' | 'approvalEditHint' | 'approvalSubmitting' | 'edit' | 'toolParameters' | 'statusAwaiting' | 'statusResponded' | 'statusCompleted' | 'statusDenied' | 'statusError' | 'statusRunning' | 'statusSuperseded' | 'tabHome' | 'tabConversations' | 'tabHelp' | 'tabNews' | 'modulesEmpty' | 'moduleBack' | 'contentLoading' | 'homeGreeting' | 'homeGreetingNamed' | 'homeGreetingLead' | 'homeSearchPlaceholder' | 'homeContentTitle' | 'homeStatus' | 'helpTitle' | 'helpSearchPlaceholder' | 'helpEmpty' | 'helpLoading' | 'helpSearchEmpty' | 'newsTitle' | 'newsEmpty' | 'newsLoading' | 'newsBack' | 'newsPublishedAt';
+type StringKey = 'launcherOpen' | 'launcherLabel' | 'panelTitle' | 'composerPlaceholder' | 'send' | 'stop' | 'queueMessage' | 'removeQueuedMessage' | 'compactingContext' | 'attach' | 'micStart' | 'micStop' | 'micUnsupported' | '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' | 'conversationClosed' | 'startNewConversation' | 'talkToOperator' | 'connectingOperator' | 'noOperatorAvailable' | 'chattingWithOperator' | 'cancelOperatorRequest' | 'dateToday' | 'dateYesterday' | 'dateLastWeek' | 'dateOlder' | 'newConversation' | 'dropZone' | 'attachmentTooLarge' | 'attachmentTooMany' | 'attachmentMimeRejected' | 'errorRetry' | 'errorGeneric' | 'errorRateLimited' | 'loading' | 'visualPreparing' | 'visualError' | 'visualPartial' | 'thinking' | 'thoughts' | 'toolResult' | 'sources' | 'feedbackUp' | 'feedbackDown' | 'feedbackThanks' | 'copy' | 'copied' | 'collapseSidebar' | 'expandSidebar' | 'formSubmit' | 'formSkip' | 'formSubmitted' | 'formSkipped' | 'formFillOut' | 'formRequired' | 'formInvalidEmail' | 'formInvalidTel' | 'formInvalidUrl' | 'formInvalidNumber' | 'formTooShort' | 'formTooLong' | 'formNumberTooSmall' | 'formNumberTooLarge' | 'formPatternMismatch' | 'formChooseAtLeast' | 'formChooseAtMost' | 'formOther' | 'formOtherPlaceholder' | 'inputRequired' | 'inputBadge' | 'inputAnswered' | 'inputSkipped' | 'inputSubmit' | 'inputSubmitHint' | 'inputSkip' | 'showOptions' | 'hideOptions' | 'qtypeText' | 'qtypeEmail' | 'qtypePhone' | 'qtypeNumber' | 'qtypeDate' | 'qtypeChooseOne' | 'qtypeChooseAny' | 'qtypeBoolean' | 'confirmYes' | 'confirmNo' | 'approve' | 'reject' | 'approvalPrompt' | 'approvalBody' | 'approvalYourResponse' | 'approvalEditHint' | 'approvalSubmitting' | 'edit' | 'toolParameters' | 'statusAwaiting' | 'statusResponded' | 'statusCompleted' | 'statusDenied' | 'statusError' | 'statusRunning' | 'statusSuperseded' | 'tabHome' | 'tabConversations' | 'tabHelp' | 'tabNews' | 'modulesEmpty' | 'moduleBack' | 'contentLoading' | 'contentHelpful' | 'homeGreeting' | 'homeGreetingNamed' | 'homeGreetingLead' | 'homeSearchPlaceholder' | 'homeContentTitle' | 'homeStatus' | 'helpTitle' | 'helpSearchPlaceholder' | 'helpEmpty' | 'helpLoading' | 'helpSearchEmpty' | 'newsTitle' | 'newsEmpty' | 'newsLoading' | 'newsBack' | 'newsPublishedAt';
 /** A partial map for one locale — what overrides look like on the wire. */
 type LocaleStrings = Partial<Record<StringKey, string>>;
 /**
@@ -167,7 +167,7 @@ interface FeatureFlags {
    */
   disableFileUpload?: boolean;
   /**
-   * Opt IN operator control — exposes the "Talk to an operator" affordance + connected-to-operator
+   * Opt IN operator control — exposes the "Talk to a person" affordance + connected-to-operator
    * states. Positive opt-in (unlike the `disable*` flags) for a new capability; default off.
    */
   enableOperatorRequest?: boolean;
@@ -400,7 +400,7 @@ interface FormDef {
  *
  * The data module trims `FormDef.translations` to the requested `?locale=` (≤1
  * entry) on read; the widget overlays that entry onto the default fields. Mirror
- * of `module-data-api` `DynamicFormTranslation`.
+ * of `module-data-api` `FormTranslation`.
  */
 interface FieldOptionTranslation {
   /** The canonical option `value` this localizes. */
@@ -525,9 +525,9 @@ interface LauncherOptions {
  * `src/schema/widget/modules.ts`. The IIFE runtime path has no Zod, so
  * these plain interfaces are what the resolver + UI consume.
  *
- * `modules` is an ordered list of tabs; each picks a UI `layout`, optional
- * content `contentTags` (the scope passed as the `tags` filter to
- * `GET /content`), and a translatable `label`.
+ * `modules` is an ordered list of tabs; each picks a UI `layout`, the content
+ * collections it shows (`contentCollectionIds` — the filter on `GET /pai/content`),
+ * and a translatable `label`.
  */
 /** The UI layouts a tab can render with. `chat` is the conversation; the rest render content. */
 type ModuleLayout = 'chat' | 'home' | 'help' | 'news';
@@ -557,7 +557,8 @@ interface ModuleStatus {
 /**
  * `home` layout config — flat feature flags (no block authoring). The Home tab
  * is assembled from these in a fixed order: greeting → search → recent conversation
- * → status → a content list (from the tab's `contentTags`, titled `contentBlockTitle`).
+ * → status → a content list (the pinned items of the tab's `contentCollectionIds`,
+ * titled `contentBlockTitle`).
  */
 interface HomeConfig {
   brandName?: string;
@@ -573,8 +574,8 @@ interface HomeConfig {
 interface ModuleOptions extends HomeConfig {
   label: string;
   layout: ModuleLayout;
-  /** Content tags to scope this tab to (matches content tagged with ANY of them). */
-  contentTags?: string[];
+  /** Content collections this tab shows, in order (max 20). */
+  contentCollectionIds?: string[];
   id?: string;
 }
 /** The `modules` block is an ordered list of tabs (max 4). */
@@ -585,13 +586,13 @@ type ModulesOptions = ModuleOptions[];
  * `hide*` once, so no render site does `!hide…`. Present only for `home` tabs.
  */
 interface ResolvedModule extends Omit<HomeConfig, 'hideGreeting' | 'hideSearchBar' | 'hideRecentConversations'> {
-  /** Stable id for nav + last-tab persistence (`id` ?? first `contentTags` ?? `layout`, deduped). */
+  /** Stable id for nav + last-tab persistence (`id` ?? first `contentCollectionIds` ?? `layout`, deduped). */
   id: string;
   /** i18n key or literal — resolved at render via the i18n strings. */
   label: string;
   layout: ModuleLayout;
-  /** Content tag scope — the `tags` filter (omitted for `chat`). */
-  contentTags?: string[];
+  /** The collections this tab shows, in order — the `contentCollectionIds` filter (omitted for `chat`). */
+  contentCollectionIds?: string[];
   showGreeting?: boolean;
   showSearchBar?: boolean;
   showRecentConversations?: boolean;
@@ -1109,39 +1110,8 @@ interface ResolvedOptions {
   onError?: ChatWidgetOptions['onError'];
 }
 //#endregion
-//#region src/core/logger.d.ts
-/**
- * Comprehensive logger for the widget runtime.
- *
- * Designed for "I have a customer reporting a weird bug on their
- * site, I want every relevant detail without rebuilding" debugging:
- *
- *   • Five levels (off / error / warn / info / debug / trace) that
- *     gate output. Default `warn` — errors + warnings always go
- *     through, info / debug / trace stay silent until opted in.
- *   • Scoped child loggers — `logger.scope("transport")` returns a
- *     logger that tags every line `[helpai:transport] …`. Every
- *     subsystem has its own scope so the console transcript reads
- *     like a flight recorder.
- *   • Structured payloads — every call accepts an object as the
- *     second arg; the browser console renders it inline, expandable.
- *   • Remote toggle — `chat.setDebug("trace")`, `HelpAI.setDebug(…)`,
- *     `?helpai-debug=trace`, or the `options.debug` mount param all
- *     converge on the same internal level. Persisted to
- *     `localStorage["helpai.debug"]` so a refresh keeps visibility.
- *   • Co-hosted safety — every signal (query, global key, log tag) is
- *     brand-prefixed so two widgets on the same page don't fight over
- *     flags or pollute each other's transcripts.
- */
-type LogLevel = 'off' | 'error' | 'warn' | 'info' | 'debug' | 'trace';
-/** One structured line, as forwarded to an external {@link setLogSink} sink. */
-interface LogEntry {
-  level: LogLevel;
-  /** Subsystem tag, e.g. `"transport"` or `"core:hooks"`. */
-  scope: string;
-  message: string;
-  payload?: unknown;
-}
+//#region src/ui/host-mode.d.ts
+type HostMode = 'page' | 'standalone' | 'inline' | 'modal' | 'drawer' | 'fullscreen' | 'expanded' | 'open' | 'closed';
 //#endregion
 //#region src/schema/primitives.d.ts
 /** A single image asset (logo, hero, icon). */
@@ -1482,7 +1452,7 @@ declare const widgetSettingsSchema: z.ZodObject<{
       home: "home";
       news: "news";
     }>;
-    contentTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    contentCollectionIds: z.ZodOptional<z.ZodArray<z.ZodUUID>>;
     id: z.ZodOptional<z.ZodString>;
     brandName: z.ZodOptional<z.ZodString>;
     hideGreeting: z.ZodOptional<z.ZodBoolean>;
@@ -1817,7 +1787,7 @@ declare const widgetConfigSchema: z.ZodObject<{
       home: "home";
       news: "news";
     }>;
-    contentTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    contentCollectionIds: z.ZodOptional<z.ZodArray<z.ZodUUID>>;
     id: z.ZodOptional<z.ZodString>;
     brandName: z.ZodOptional<z.ZodString>;
     hideGreeting: z.ZodOptional<z.ZodBoolean>;
@@ -2153,7 +2123,7 @@ declare const widgetConfigPartialSchema: z.ZodObject<{
       home: "home";
       news: "news";
     }>;
-    contentTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    contentCollectionIds: z.ZodOptional<z.ZodArray<z.ZodUUID>>;
     id: z.ZodOptional<z.ZodString>;
     brandName: z.ZodOptional<z.ZodString>;
     hideGreeting: z.ZodOptional<z.ZodBoolean>;
@@ -2451,7 +2421,7 @@ declare const widgetSettingsPartialSchema: z.ZodObject<{
       home: "home";
       news: "news";
     }>;
-    contentTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    contentCollectionIds: z.ZodOptional<z.ZodArray<z.ZodUUID>>;
     id: z.ZodOptional<z.ZodString>;
     brandName: z.ZodOptional<z.ZodString>;
     hideGreeting: z.ZodOptional<z.ZodBoolean>;
@@ -2728,7 +2698,7 @@ declare const serverConfigSchema: z.ZodObject<{
       home: "home";
       news: "news";
     }>;
-    contentTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    contentCollectionIds: z.ZodOptional<z.ZodArray<z.ZodUUID>>;
     id: z.ZodOptional<z.ZodString>;
     brandName: z.ZodOptional<z.ZodString>;
     hideGreeting: z.ZodOptional<z.ZodBoolean>;
@@ -3016,7 +2986,7 @@ declare const handshakeResponseSchema: z.ZodObject<{
         home: "home";
         news: "news";
       }>;
-      contentTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+      contentCollectionIds: z.ZodOptional<z.ZodArray<z.ZodUUID>>;
       id: z.ZodOptional<z.ZodString>;
       brandName: z.ZodOptional<z.ZodString>;
       hideGreeting: z.ZodOptional<z.ZodBoolean>;
@@ -3177,13 +3147,12 @@ interface EventMap {
   /** A content list (news / help / home block) rendered. */
   contentView: {
     section: string;
-    tags?: string;
     count: number;
   };
-  /** An article / content item was opened. */
+  /** An article / content item was opened — with the collection it belongs to. */
   contentOpen: {
     contentId: string;
-    tags?: string;
+    contentCollectionId: string;
   };
   /** The help search ran. Length + hit count only — never the query text. */
   contentSearch: {
@@ -3243,9 +3212,6 @@ interface EventMap {
 }
 type EventName = keyof EventMap;
 //#endregion
-//#region src/ui/host-mode.d.ts
-type HostMode = 'page' | 'standalone' | 'inline' | 'modal' | 'drawer' | 'fullscreen' | 'expanded' | 'open' | 'closed';
-//#endregion
 //#region src/boot.d.ts
 /**
  * Determine what `data-mode` the host should start at — matching what App's
@@ -3278,6 +3244,40 @@ export declare const HOOK_WILDCARD = "*";
  */
 type HookListener = (instance: ChatWidgetInstance, event: EventName, data: unknown) => void;
 //#endregion
+//#region src/core/logger.d.ts
+/**
+ * Comprehensive logger for the widget runtime.
+ *
+ * Designed for "I have a customer reporting a weird bug on their
+ * site, I want every relevant detail without rebuilding" debugging:
+ *
+ *   • Five levels (off / error / warn / info / debug / trace) that
+ *     gate output. Default `warn` — errors + warnings always go
+ *     through, info / debug / trace stay silent until opted in.
+ *   • Scoped child loggers — `logger.scope("transport")` returns a
+ *     logger that tags every line `[helpai:transport] …`. Every
+ *     subsystem has its own scope so the console transcript reads
+ *     like a flight recorder.
+ *   • Structured payloads — every call accepts an object as the
+ *     second arg; the browser console renders it inline, expandable.
+ *   • Remote toggle — `chat.setDebug("trace")`, `HelpAI.setDebug(…)`,
+ *     `?helpai-debug=trace`, or the `options.debug` mount param all
+ *     converge on the same internal level. Persisted to
+ *     `localStorage["helpai.debug"]` so a refresh keeps visibility.
+ *   • Co-hosted safety — every signal (query, global key, log tag) is
+ *     brand-prefixed so two widgets on the same page don't fight over
+ *     flags or pollute each other's transcripts.
+ */
+type LogLevel = 'off' | 'error' | 'warn' | 'info' | 'debug' | 'trace';
+/** One structured line, as forwarded to an external {@link setLogSink} sink. */
+interface LogEntry {
+  level: LogLevel;
+  /** Subsystem tag, e.g. `"transport"` or `"core:hooks"`. */
+  scope: string;
+  message: string;
+  payload?: unknown;
+}
+//#endregion
 //#region src/index.d.ts
 /**
  * Handle returned by {@link mount} / {@link init}. All methods are safe to call