@ahmedramez-org/nexus-chat 1.0.0-beta.1 → 1.0.0-beta.10

package/README.md

@@ -1,39 +1,127 @@
 # @incorta/nexus-chat
 
-NexusChat, the IncortaCopilot chat UI, for any app on any framework. One package holds:
-
-| Import                                     | What                                                        |
-| ------------------------------------------ | ----------------------------------------------------------- |
-| `@incorta/nexus-chat`                      | the connector (`mountNexusChat`, `loadNexusChat`) and types |
-| `@incorta/nexus-chat/react`                | `<NexusChat />` for React 18 and 19 apps                    |
-| `@incorta/nexus-chat/contract`             | the host contract's values (`NEXUS_CHAT_CONTRACT_VERSION`…) |
-| `@incorta/nexus-chat/conformance`          | checks a host bridge against the contract                   |
-| `@incorta/nexus-chat/host`                 | host helpers (`createElementRootAdapter`…)                  |
-| `node_modules/@incorta/nexus-chat/remote/` | the prebuilt chat, for apps that serve a pinned copy        |
-
-The chat always runs as that prebuilt Module Federation bundle with its own React and isolated
+NexusChat, the IncortaCopilot chat UI, for any app on any framework: one `<script>` tag for any
+site, `<NexusChat />` for React, `mountNexusChat()` for everything else.
+
+The chat always runs as a prebuilt Module Federation bundle with its own React and isolated
 styles, never re-compiled by the app's bundler, so it never collides with the app's React, its
-dependencies or its CSS. Importing the connector adds about 2 KB to an app; `remote/` stays on
-disk unless the app serves it.
+dependencies or its CSS. The connector adds about 6 KB gzipped to an app (half of it the Incorta
+Intelligence mark its loading skeleton draws), and the React component about 7 KB more. The chat
+build itself is not in this package: Copilot serves it, and each GitHub Release attaches it as
+`nexus-chat-dist.tar.gz`.
+
+## Any site: one script
+
+```html
+<script src="https://<incorta>/incorta/copilot/nexus-chat/widget.js" defer></script>
+```
+
+Incorta serves this script next to `embed.html`; it is not in this package and needs no build. It
+draws the Incorta Intelligence launcher at the bottom right and opens the embedded chat (below)
+floating, docked or full screen, on the user's Incorta session, so the page holds no token. It is
+one classic script with no imports, so a page on any origin loads it without CORS.
+
+Optional `data-` attributes set it up: `data-theme="dark"`, `data-modes="floating,docked"` (the
+windows allowed, in that order; default all three), `data-default-mode="docked"` (open on load;
+default only the launcher) and `data-locale="fr"`. The page drives it afterwards through
+`window.NexusChatWidget`: `open()`, `close()`, `setMode('docked')`, `setTheme('dark')`.
 
 ## React
 
+Two ways in: **direct**, where the chat mounts into the page and shares its session (Incorta's own
+UIs), and **embedded**, where it runs in an iframe served by Incorta on the user's Incorta session,
+so the app never holds a token (generated apps, other sites).
+
+### Embedded
+
 ```tsx
 import { NexusChat } from '@incorta/nexus-chat/react';
 
+<NexusChat embedUrl={`${incortaUrl}/copilot/nexus-chat/embed.html`} theme="dark" />;
+```
+
+It draws its own window: an Incorta Intelligence launcher at the bottom right opens the chat
+floating (a card lifted off the page, opening out of the launcher, which stays under it to hide
+it) or docked flush on the right (the page makes room). The chat's own top bar switches between
+the windows (Float, Dock to the side, Enter full screen: every allowed one but the current) and
+closes it back to the launcher; nothing sits above the chat. `modes` limits the windows (default
+all three, in that order) and `defaultMode` opens one on load. Below 768px wide the chat covers
+the page. The chat is drawn smaller in a small window, and a skeleton holds the window while the
+chat loads. `theme` is followed live; `locale` is read when the chat first opens.
+
+The Incorta cluster needs `iframe.inclusion.enabled` (and `frame-ancestors` set to the app's
+domains). Where the browser keeps the Incorta session from the iframe (Safari, Firefox, private
+windows), the chat shows Continue with Incorta: the browser asks the user to allow it once, and
+the chat starts on their Incorta session. A user not signed in to Incorta signs in through a small
+Incorta window that closes itself afterwards. No browser setting is needed.
+
+While the user clicks or types in the app, the component tells the chat at most every ten seconds,
+so Incorta's own idle timeout does not end the chat's session while the app is in use. A page that
+places the iframe itself can do the same: `iframe.contentWindow.postMessage({ nexusChat: 'active' },
+'<incorta origin>')`. If the session ends anyway, the chat shows Sign in to Incorta.
+
+### Direct
+
+```ts
+// Copilot answers 400 without the signed-in user's token: read it from Incorta's
+// session, and read it again after a 401 or 403.
+let session;
+const incortaHeaders = () =>
+  (session ??= fetch('/incorta/service/user/isLoggedIn', { credentials: 'include' }).then(
+    async (response) => ({
+      Authorization: `Bearer ${(await response.json()).accessToken}`,
+      'X-XSRF-TOKEN': response.headers.get('X-XSRF-TOKEN') ?? '',
+    }),
+  ));
+```
+
+```tsx
 <NexusChat
-  connection={{ client: 'general', copilotUrl: '/api/ai', credentials: 'same-origin' }}
+  connection={{
+    client: 'general',
+    copilotUrl: '/incorta/copilot',
+    credentials: 'include',
+    headers: incortaHeaders, // read before each request
+    refreshAuth: async () => ((session = undefined), true), // after a 401 or 403: read again, retry
+  }}
   theme="dark"
   user={{ id: user.sub, name: user.name }}
   onLoadError={(error) => setError(error.message)}
-/>;
+/>
 ```
 
-The chat fills the component's box. `theme`, `locale` (default: the browser's), `direction`,
-`tenantId`, `user` and `window` update the running chat; `connection`, `chat`, `actions`, `events`,
-`instanceId`, `assetsUrl` and `timeoutMs` are read once at mount. `window` (`docked`, `canDock`,
-`setDocked`, `close`) hands the chat's window to the app: the chat shows a dock toggle and a close
-button. `onReady` receives the handle (`ask`, `attach`).
+The chat fills the component's box; the app draws any frame around it. Until the chat is mounted, a skeleton holds the box (the embedded window's loading face: the Incorta Intelligence mark and two lines, after 300 ms), and it fades once the chat mounts, or leaves at once when `onLoadError` fires, so the app's own failure takes the box. `theme`, `locale` (default:
+the browser's), `direction`, `tenantId`, `user` and `window` update the running chat;
+`connection`, `chat`, `actions`, `events`, `instanceId`, `assetsUrl` and `timeoutMs` are read once
+at mount. `window` (`docked`, `canDock`, `setDocked`, `close`) hands the chat's window to the app:
+the chat shows a dock toggle and a close button; with `mode`, `modes` and `setMode` (read at
+mount) it shows a button per other mode instead of the toggle. An app that already builds the contract's
+`environment` or `window` passes it as is. `onReady` receives the handle (`ask`, `attach`), and
+`null` once the chat unmounts; `loadedNexusChatVersion()` names the loaded build for error reports.
+
+### Direct, in a window
+
+```tsx
+<NexusChat
+  connection={{
+    client: 'general',
+    copilotUrl: '/incorta/copilot',
+    credentials: 'include',
+    headers: incortaHeaders, // as above
+    refreshAuth: async () => ((session = undefined), true),
+  }}
+  theme="dark"
+  modes={['floating', 'docked', 'fullscreen']}
+  defaultMode="floating"
+/>
+```
+
+`modes` or `defaultMode` instead of `window` gives the direct chat the embedded window: the
+launcher, floating, docked (the page makes room) and full-screen windows, full screen below 768px.
+The chat's own top bar switches windows and closes it to the launcher, where the conversation
+stays. `modes` limits the windows (default all three, in that order); `defaultMode` opens one on
+load, else only the launcher shows. The other props are the direct ones, and an app passing
+`window` keeps drawing its own frame.
 
 ## Any framework
 
@@ -52,38 +140,46 @@ chat.unmount();
 ```
 
 The options are the host contract: `connection` and `environment` are required; `chat`, `actions`,
-`events` and `window` are optional, and the chat hides what a host leaves out. Mount in the browser
-only, never during SSR.
+`events` and `window` are optional, and the chat hides what a host leaves out. The chat fills
+`element`. Until it is mounted the React component's skeleton holds the element (after 300 ms, in
+the `environment`'s theme), and it leaves at once if the chat cannot load, so the app's own failure
+takes its place. Mount in the browser only, never during SSR.
+
+`chat={{ contexts: ['business-view', 'ai-container', 'file'] }}` lets users attach contexts, in
+that menu order: `'file'` uploads, and each other built-in kind (`business-view`, `physical-table`,
+`ai-container`, `knowledge-store`) is loaded by the chat from Incorta through
+`connection.incortaApi` (for example, `{ type: 'bff', baseUrl: '/incorta/bff/v1' }`). Without
+`incortaApi`, a bare kind is left out with a console warning; the public API has no Knowledge
+Stores. A `ContextSource` of a kind replaces the chat's loader for it.
 
 `loadNexusChat(source)` only loads the chat and resolves to its `mount`. It loads once per source,
-retries once, and gives up after `timeoutMs` (default 20 s); a failed load is forgotten so the next
+retries once, and gives up after `timeoutMs` (default 20 s, counted while the page is visible: a
+hidden tab gets a fresh deadline once it shows); a failed load is forgotten so the next
 call tries again. Call it when the page is idle to make the first open instant.
 
 ## Where the chat comes from
 
-| Mode                      | Options                                                                       | UI version                    | App setup                                       |
-| ------------------------- | ----------------------------------------------------------------------------- | ----------------------------- | ----------------------------------------------- |
-| Always updated (default)  | `connection.copilotUrl` only                                                  | what that Copilot runs        | none: Copilot serves `<copilotUrl>/nexus-chat/` |
-| Pinned, served by the app | `assetsUrl: '/nexus-chat/'`                                                   | the installed package version | serve this package's `remote/` at that path     |
-| Pinned, served from a CDN | `assetsUrl: 'https://cdn.jsdelivr.net/npm/@incorta/nexus-chat@1.4.2/remote/'` | the version in the URL        | none; the page's CSP must allow that origin     |
+| Mode                     | Options                      | UI version                | App setup                                                              |
+| ------------------------ | ---------------------------- | ------------------------- | ---------------------------------------------------------------------- |
+| Always updated (default) | `connection.copilotUrl` only | what that Copilot runs    | none: Copilot serves `<copilotUrl>/nexus-chat/`                        |
+| Pinned                   | `assetsUrl: '/nexus-chat/'`  | the release you extracted | serve that release's `nexus-chat-dist.tar.gz`, extracted, at that path |
 
-An app with a server serves `remote/` straight from the installed package:
+A pinned copy serves `remoteEntry.js` with revalidation (`no-cache`) and `assets/` as immutable.
 
-```ts
-import { createRequire } from 'node:module';
-import path from 'node:path';
-
-const remoteDir = path.join(
-  path.dirname(createRequire(import.meta.url).resolve('@incorta/nexus-chat/package.json')),
-  'remote',
-);
-// serve remoteDir at /nexus-chat/: remoteEntry.js revalidates (no-cache), assets/ is immutable
-```
+A pinned UI keeps talking to a Copilot that keeps moving; the default mode keeps the two in step.
 
-A static app copies it instead:
-`"postinstall": "cp -R node_modules/@incorta/nexus-chat/remote public/nexus-chat"`.
+## Everything in the package
 
-A pinned UI keeps talking to a Copilot that keeps moving; the default mode keeps the two in step.
+React and other apps need only the first two imports; the rest serve hosts that federate the chat
+themselves (web-react, Hikari).
+
+| Import                            | What                                                        |
+| --------------------------------- | ----------------------------------------------------------- |
+| `@incorta/nexus-chat`             | the connector (`mountNexusChat`, `loadNexusChat`) and types |
+| `@incorta/nexus-chat/react`       | `<NexusChat />` for React 18 and 19 apps                    |
+| `@incorta/nexus-chat/contract`    | the host contract's values (`NEXUS_CHAT_CONTRACT_VERSION`…) |
+| `@incorta/nexus-chat/conformance` | checks a host bridge against the contract                   |
+| `@incorta/nexus-chat/host`        | host helpers (`createElementRootAdapter`…)                  |
 
 ## Versions
 

package/contract/conformance.js

@@ -1,4 +1,4 @@
-import { NEXUS_CHAT_CONTRACT_VERSION, } from './index.js';
+import { BUILT_IN_CONTEXT_KINDS, NEXUS_CHAT_CONTRACT_VERSION, } from './index.js';
 class CheckCollector {
     results = [];
     async run(id, title, check) {
@@ -255,15 +255,17 @@ export async function checkHostContract(options, checkOptions = {}) {
             ensure(notifications === before, 'unsubscribe did not detach the listener.');
         }
     });
-    await checks.run('chat.contexts', 'each context is "file" or a source with a loader', () => {
+    await checks.run('chat.contexts', 'each context is a built-in kind or a source with a loader', () => {
         const kinds = (chat?.contexts ?? []).map((spec) => {
-            if (spec === 'file')
+            if (typeof spec === 'string') {
+                ensure(BUILT_IN_CONTEXT_KINDS.includes(spec), `unknown context ${JSON.stringify(spec)}; a bare string is one of the built-in kinds: ${BUILT_IN_CONTEXT_KINDS.join(', ')}.`);
                 return spec;
+            }
             ensure(CONTEXT_KINDS.includes(spec.kind), `unknown context kind ${JSON.stringify(spec.kind)}.`);
             ensure(typeof spec.load === 'function', `the ${spec.kind} source has no load().`);
             return spec.kind;
         });
-        ensure(new Set(kinds).size === kinds.length, 'a context kind is listed twice.');
+        ensure(new Set(kinds).size === kinds.length, 'a context kind is listed twice (a source replaces its bare kind: list only the source).');
     });
     await checks.run('chat.triggers', 'each trigger is @ or # with a search', () => {
         const chars = (chat?.triggers ?? []).map((trigger) => {

package/contract/index.d.ts

@@ -22,6 +22,17 @@ export interface NexusChatConnection {
      * Absent: the failure surfaces to the user.
      */
     refreshAuth?(): Promise<boolean>;
+    /**
+     * How the chat reaches the Incorta API for built-in kinds other than `'file'` in
+     * `chat.contexts`, under the headers, credentials and `refreshAuth` above.
+     * - `'bff'`: Incorta's internal BFF (web-react: `baseUrl: '/incorta/bff/v1'`;
+     *   the session headers carry the user).
+     * - `'public'`: the public API v2, rooted at `/api/v2/{tenant}`.
+     */
+    incortaApi?: {
+        type: 'bff' | 'public';
+        baseUrl: string;
+    };
     /** Poll tuning; hosts normally omit both (defaults 1500 ms / 1000 ms). */
     pollIntervalMs?: number;
     initialPollDelayMs?: number;
@@ -80,8 +91,34 @@ export interface ContextSource {
      */
     resolve?(dataset: Readonly<Record<string, unknown>>, signal: AbortSignal): Promise<Readonly<Record<string, unknown>>>;
 }
-/** `'file'` is the chat's own upload browser; every other kind is a host source. */
-export type ContextSpec = 'file' | ContextSource;
+/**
+ * The built-in kinds the chat handles itself: its upload browser and contexts
+ * loaded through `connection.incortaApi`. `'insight'` is not one: insights come
+ * from the dashboard the host has open, so only a host source can list them.
+ */
+export declare const BUILT_IN_CONTEXT_KINDS: readonly ["file", "business-view", "physical-table", "ai-container", "knowledge-store"];
+export type BuiltInContextKind = (typeof BUILT_IN_CONTEXT_KINDS)[number];
+/**
+ * One entry of the add-context menu; `chat.contexts` lists them in menu order.
+ *
+ * - `'file'`: the chat's own upload browser.
+ * - Another built-in kind (`'business-view'`, …): the chat loads it from
+ *   `connection.incortaApi`. Without `incortaApi`, or for a kind its API does not
+ *   offer (`'knowledge-store'` has no public API), the kind is left out of
+ *   the menu with a console warning.
+ * - A `ContextSource`: the host loads the rows. A source of a built-in kind
+ *   replaces the chat's loader for that kind.
+ *
+ * Name each kind once. A host that lists a bare kind and a source of the same
+ * kind fails conformance; the chat still shows the kind once, as the host's
+ * source, in the source's place. Any other string is dropped.
+ *
+ * Migrating: code that told a source apart with `spec === 'file'` no longer
+ * compiles, since a bare string may now be a kind; narrow with
+ * `typeof spec === 'string'`. Pass bare kinds only to a chat that has them
+ * (this release or later): an older chat cannot render them.
+ */
+export type ContextSpec = BuiltInContextKind | ContextSource;
 export interface ColumnSummary {
     id: string;
     name: string;
@@ -346,16 +383,27 @@ export interface NexusChatOptions {
      * The host sizes the mount and owns its window (a page-covering overlay, a
      * docked side panel) and draws its frame. Present: the chat hides its own
      * fullscreen toggle and its edge border, and shows a dock toggle while
-     * `canDock`, and a close button. Absent: the chat's own fullscreen toggle,
-     * and no close button.
+     * `canDock` (or, with `mode`, `modes` and `setMode`, one button per other
+     * mode), and a close button. Absent: the chat's own fullscreen toggle, and
+     * no close button.
      */
     window?: NexusChatWindow;
 }
+/** The windows a host can show the chat in. */
+export type NexusChatWindowMode = 'floating' | 'docked' | 'fullscreen';
 export interface NexusChatWindowState {
     /** The mount is the docked side panel (the toggle shows pressed). */
     docked: boolean;
     /** The host page allows docking now; `false` hides the dock toggle. */
     canDock: boolean;
+    /**
+     * The window shown now. With `modes` and `setMode`, the header offers every
+     * mode in `modes` but this one (float, dock, full screen, in that order)
+     * instead of the dock toggle.
+     */
+    mode?: NexusChatWindowMode;
+    /** The modes the host can switch to now, the current one included. */
+    modes?: readonly NexusChatWindowMode[];
 }
 export interface NexusChatWindow {
     /** May return a fresh object on every call: the chat compares the fields. */
@@ -363,6 +411,8 @@ export interface NexusChatWindow {
     /** Call `onChange` whenever `get` may return something different. */
     subscribe(onChange: () => void): () => void;
     setDocked(docked: boolean): void;
+    /** Shows the chat in another of `modes`; the conversation and draft stay. */
+    setMode?(mode: NexusChatWindowMode): void;
     close(): void;
 }
 /** What `mount` returns: the host's handle on one running chat. */

package/contract/index.js

@@ -1,4 +1,16 @@
 export const NEXUS_CHAT_CONTRACT_VERSION = 2;
+/**
+ * The built-in kinds the chat handles itself: its upload browser and contexts
+ * loaded through `connection.incortaApi`. `'insight'` is not one: insights come
+ * from the dashboard the host has open, so only a host source can list them.
+ */
+export const BUILT_IN_CONTEXT_KINDS = [
+    'file',
+    'business-view',
+    'physical-table',
+    'ai-container',
+    'knowledge-store',
+];
 /**
  * Reads the namespaced-kind convention. Returns null for bare legacy kinds.
  * Framework-free on purpose: hosts use this inside `canRender` to route by

package/index.d.ts

@@ -1,4 +1,9 @@
-import type { NexusChatHandle, NexusChatMount, NexusChatOptions } from './contract/index.js';
+import type {
+  HostTheme,
+  NexusChatHandle,
+  NexusChatMount,
+  NexusChatOptions,
+} from './contract/index.js';
 
 export type * from './contract/index.js';
 
@@ -6,8 +11,8 @@ export interface NexusChatSource {
   /** IncortaCopilot's root as this page reaches it; the chat loads from `<copilotUrl>/nexus-chat/`. */
   copilotUrl?: string;
   /**
-   * Where the chat files are served instead (pinned): the app's own copy of
-   * this package's `remote/` folder, or a CDN URL. Absent: from Copilot.
+   * Where the chat files are served instead (pinned): any URL that serves a
+   * release's extracted `nexus-chat-dist.tar.gz`. Absent: from Copilot.
    */
   assetsUrl?: string;
   /** Deadline for loading the chat, retry included. Default 20 000 ms. */
@@ -24,8 +29,23 @@ export const CONTRACT_VERSION: 2;
 /** Loads the chat once per source (one retry, one deadline) and resolves to its `mount`. */
 export function loadNexusChat(source: NexusChatSource): Promise<NexusChatMount>;
 
+/** Forgets a loaded chat, so the next load fetches it again (after it failed while running). */
+export function forgetNexusChat(source: NexusChatSource): void;
+
+/** The version the last loaded chat reports (for error reports); undefined before a load. */
+export function loadedNexusChatVersion(): string | undefined;
+
 /** Loads the chat and mounts it into `element`. */
 export function mountNexusChat(
   element: HTMLElement,
   options: MountNexusChatOptions,
 ): Promise<NexusChatHandle>;
+
+/**
+ * @internal The skeleton `mountNexusChat` and `<NexusChat>` draw over a box
+ * while the chat loads. Not part of the package's API.
+ */
+export function showNexusChatSkeleton(
+  box: HTMLElement,
+  theme?: HostTheme,
+): { setTheme(theme?: HostTheme): void; done(): void; remove(): void };