@helpai/elements 6.14.0 → 7.0.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/react.d.ts CHANGED
@@ -4,8 +4,9 @@
4
4
  * it from any component. Safe with server rendering (Next.js): nothing touches the DOM until the component's effect
5
5
  * runs in the browser, and the server renders the initial state.
6
6
  *
7
- * The kit carries the whole widget API (re-exported below), so a React app imports everything from this one path and
8
- * every call reaches the same widget. The build marks the bundle `'use client'`.
7
+ * The widget itself (Preact, its UI) loads on demand when `<HelpAI />` mounts, so it never weighs on the app's own
8
+ * bundle; the hooks, the instance registry and the types are here from the start, so a React app imports everything
9
+ * from this one path and every call reaches the same widget. The build marks the bundle `'use client'`.
9
10
  *
10
11
  * @example
11
12
  * ```tsx
@@ -3175,7 +3176,7 @@ type HostMode = 'page' | 'standalone' | 'inline' | 'modal' | 'drawer' | 'fullscr
3175
3176
  * different initial states, the host resizes between mount and App's first
3176
3177
  * effect (the closed→open→closed flicker this pins against).
3177
3178
  */
3178
- export declare function resolveInitialHostMode(options: ResolvedOptions): HostMode;
3179
+ declare function resolveInitialHostMode(options: ResolvedOptions): HostMode;
3179
3180
  /** Wildcard that matches every widget id / every event name. */
3180
3181
  export declare const HOOK_WILDCARD = "*";
3181
3182
  /**
@@ -3245,6 +3246,13 @@ interface AskOptions {
3245
3246
  }
3246
3247
  /** Flat data about a host event: strings, numbers and booleans only. */
3247
3248
  type HostEventData = Record<string, string | number | boolean>;
3249
+ /**
3250
+ * Look up a live instance by `widgetId` (default: `"default"`). Returns
3251
+ * `null` if nothing is mounted at that slot.
3252
+ */
3253
+ export declare function getInstance(widgetId?: string): ChatWidgetInstance | null;
3254
+ /** All live widget instances on the page. */
3255
+ export declare function getAllInstances(): ChatWidgetInstance[];
3248
3256
  /**
3249
3257
  * Comprehensive logger for the widget runtime.
3250
3258
  *
@@ -3281,7 +3289,7 @@ interface LogEntry {
3281
3289
  * Handle returned by {@link mount} / {@link init}. All methods are safe to call
3282
3290
  * after `destroy()` — they become no-ops rather than throwing.
3283
3291
  */
3284
- export interface ChatWidgetInstance {
3292
+ interface ChatWidgetInstance {
3285
3293
  /** Stable identifier — matches `options.widgetId ?? "default"`. */
3286
3294
  readonly widgetId: string;
3287
3295
  /**
@@ -3453,7 +3461,7 @@ export interface ChatWidgetInstance {
3453
3461
  * mount({ widgetId: 'sales', publicKey: KEY_B, aiAgentDeploymentId: DEPLOYMENT_B, target: salesEl });
3454
3462
  * ```
3455
3463
  */
3456
- export declare function mount(opts: ChatWidgetOptions & {
3464
+ declare function mount(opts: ChatWidgetOptions & {
3457
3465
  aiAgentDeploymentId: string;
3458
3466
  target?: HTMLElement;
3459
3467
  }): ChatWidgetInstance;
@@ -3462,7 +3470,7 @@ export declare function mount(opts: ChatWidgetOptions & {
3462
3470
  * options are merged (via {@link ChatWidgetInstance.update}). Otherwise it
3463
3471
  * behaves like {@link mount}. Safe to call on every route change in an SPA.
3464
3472
  */
3465
- export declare function init(opts: ChatWidgetOptions & {
3473
+ declare function init(opts: ChatWidgetOptions & {
3466
3474
  aiAgentDeploymentId: string;
3467
3475
  target?: HTMLElement;
3468
3476
  }): ChatWidgetInstance;
@@ -3470,29 +3478,48 @@ export declare function init(opts: ChatWidgetOptions & {
3470
3478
  * Destroy a specific instance by `widgetId`, or — when no id is supplied —
3471
3479
  * every live widget on the page.
3472
3480
  */
3473
- export declare function destroy(widgetId?: string): void;
3481
+ declare function destroy(widgetId?: string): void;
3474
3482
  /**
3475
- * Look up a live instance by `widgetId` (default: `"default"`). Returns
3476
- * `null` if nothing is mounted at that slot.
3483
+ * Brand constants, baked in at build time by `scripts/build-brand.mjs`.
3484
+ *
3485
+ * esbuild `define` replaces every `__BRAND_*__` / `__CSS_PREFIX__` reference
3486
+ * with the JSON-encoded value from the brand JSON. We use `typeof … !==
3487
+ * "undefined"` guards so the module still imports cleanly in tooling
3488
+ * contexts (Vitest, the Vite dev server) where defines come from separate
3489
+ * config files.
3477
3490
  */
3478
- export declare function getInstance(widgetId?: string): ChatWidgetInstance | null;
3479
- /** All live widget instances on the page. */
3480
- export declare function getAllInstances(): ChatWidgetInstance[];
3481
- /** Semver of the published `@<brand>/elements` package — build-injected, also
3482
- * sent on every request + analytics hit as `_ev`. */
3483
- export declare const version: string;
3484
- /** Compile-time brand constants inlined at build time (name, CDN URL, theme). */
3485
- export declare const brand: {
3491
+ declare const BRAND: {
3486
3492
  readonly id: string;
3487
3493
  readonly name: string;
3488
3494
  readonly global: string;
3489
3495
  readonly tagName: string;
3490
3496
  readonly cssPrefix: string;
3497
+ /**
3498
+ * MAIN site origin (e.g. `https://help.ai`) — module bases derive from it:
3499
+ * agent API at `${defaultBaseUrl}/api/agent`, data API at
3500
+ * `${defaultBaseUrl}/api/data`.
3501
+ */
3491
3502
  readonly defaultBaseUrl: string;
3503
+ /** Public-facing brand label, e.g. "Help AI". */
3492
3504
  readonly displayName: string;
3505
+ /** Bare host without protocol, e.g. "help.ai". */
3493
3506
  readonly domain: string;
3507
+ /** Full marketing site URL, e.g. "https://help.ai". */
3494
3508
  readonly siteUrl: string;
3495
3509
  };
3510
+ /**
3511
+ * The running widget's own release version (the `@<brand>/elements` package
3512
+ * version), injected at build time from `package.json` via the
3513
+ * `__ELEMENTS_VERSION__` esbuild/vite define (see `scripts/_brand-defines.mjs`).
3514
+ *
3515
+ * Sent on every backend request and analytics hit as the `_ev` ("elements
3516
+ * version") param so the server can correlate behaviour with a release, and
3517
+ * exposed to host pages as the public `version` API field.
3518
+ *
3519
+ * Falls back to `"0.0.0-dev"` when the define is absent (e.g. a raw unit-test
3520
+ * import that doesn't go through the bundler).
3521
+ */
3522
+ declare const ELEMENTS_VERSION: string;
3496
3523
  /** The widget's options as props; `aiAgentDeploymentId` is required, `widgetId` names a second widget on the page. */
3497
3524
  export type HelpAIProps = ChatWidgetOptions & {
3498
3525
  aiAgentDeploymentId: string;
@@ -3531,4 +3558,4 @@ export declare function useHelpAI(widgetId?: string): HelpAIControls;
3531
3558
  * ```
3532
3559
  */
3533
3560
  export declare function useHelpAITool<TInput>(tool: ModelContextTool<TInput>): void;
3534
- export { type AskOptions, type Asset, type BlocksConfig, type ChatWidgetOptions, type ConnectionConfig, type ConnectionConfigPartial, type EventMap, type EventName, type HandshakeResponse, type HookListener, type HostEventData, type Link, type LogEntry, type LogLevel, type ModelContextTool, type OpenTarget, type ResolvedOptions, type ServerConfig, type SiteConfig, type ToolAnnotations, type UserTokenSource, type WidgetConfig, type WidgetConfigPartial, type WidgetSettings, type WidgetSettingsPartial, type WidgetState, registerHook as hook };
3561
+ export { type AskOptions, type Asset, type BlocksConfig, type ChatWidgetInstance, type ChatWidgetOptions, type ConnectionConfig, type ConnectionConfigPartial, type EventMap, type EventName, type HandshakeResponse, type HookListener, type HostEventData, type Link, type LogEntry, type LogLevel, type ModelContextTool, type OpenTarget, type ResolvedOptions, type ServerConfig, type SiteConfig, type ToolAnnotations, type UserTokenSource, type WidgetConfig, type WidgetConfigPartial, type WidgetSettings, type WidgetSettingsPartial, type WidgetState, BRAND as brand, type destroy, registerHook as hook, type init, type mount, type resolveInitialHostMode, ELEMENTS_VERSION as version };