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

package/README.md

@@ -1,39 +1,59 @@
 # @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: `<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. Importing the connector and the component adds about 3 KB to an app. The
+chat build itself is not in this package: Copilot serves it, and each GitHub Release attaches it as
+`nexus-chat-dist.tar.gz`.
 
 ## 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, docked on the right (the page makes room) or fullscreen, switched or minimized back to
+the launcher from the top right. `modes` limits the windows (default all three, in that order);
+`defaultMode` opens one on load. Below 768px wide the chat covers the page. The window takes the
+page's background colour, the chat is drawn smaller when floating or docked, and the launcher icon
+shimmers 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), and the user signed in to Incorta in that browser. The iframe reaches the Incorta
+session only where the browser allows third-party cookies: Chrome by default; Safari ("Prevent
+cross-site tracking" off), Firefox (a cookie exception for the Incorta site) and private windows
+need that setting.
+
+### Direct
+
+```tsx
 <NexusChat
-  connection={{ client: 'general', copilotUrl: '/api/ai', credentials: 'same-origin' }}
+  connection={{ client: 'general', copilotUrl: '/incorta/copilot', credentials: 'include' }}
   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. `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. 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.
 
 ## Any framework
 
@@ -55,35 +75,40 @@ The options are the host contract: `connection` and `environment` are required;
 `events` and `window` are optional, and the chat hides what a host leaves out. 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
 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;

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

@@ -6,8 +6,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,6 +24,12 @@ 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,

package/index.js

@@ -4,9 +4,8 @@
 //
 // - IncortaCopilot (default): `<copilotUrl>/nexus-chat/`, always the version
 //   that Copilot runs, so the UI matches its backend;
-// - this package's own `remote/` folder, served by the app (pinned to the
-//   installed version);
-// - any URL that serves a `remote/` folder, such as a CDN (pinned by its URL).
+// - any URL that serves a release's chat build (`nexus-chat-dist.tar.gz` on
+//   the GitHub Release, extracted), pinned to that release.
 //
 // `assetsUrl` picks the source; without it the chat comes from Copilot.
 // The host contract ships alongside: its types here, its values and helpers
@@ -21,6 +20,9 @@ const DEFAULT_TIMEOUT_MS = 20_000;
 
 const loads = new Map();
 const attempts = new Map();
+/** Stylesheets of the chat that failed to load, reloaded by the next attempt. */
+const failedStylesheets = new Set();
+let loadedVersion;
 
 function entryUrl({ copilotUrl, assetsUrl }) {
   const base = assetsUrl ?? (copilotUrl && `${copilotUrl.replace(/\/+$/, '')}/nexus-chat/`);
@@ -28,11 +30,74 @@ function entryUrl({ copilotUrl, assetsUrl }) {
   return new URL('remoteEntry.js', new URL(base, window.location.href)).href;
 }
 
+// A failed CSS chunk rejects the load, and Vite's preload never asks for a
+// sheet it has seen again. Remember the chat's failed sheets so the next
+// attempt requests them anew. A sheet failing again fails that attempt but is
+// forgotten, so one a deploy removed blocks a single attempt, not every one.
+function captureFailedStylesheets(base) {
+  if (captureFailedStylesheets.installed) return;
+  captureFailedStylesheets.installed = true;
+  window.addEventListener(
+    'error',
+    ({ target }) => {
+      if (!(target instanceof HTMLLinkElement) || target.rel !== 'stylesheet') return;
+      if (target.dataset.nexusChatRetry === undefined && target.href.startsWith(base)) {
+        failedStylesheets.add(target.href);
+      }
+    },
+    true,
+  );
+}
+
+function reloadFailedStylesheets() {
+  const reloads = [...failedStylesheets].map((href) => {
+    failedStylesheets.delete(href);
+    document.querySelectorAll('link[rel="stylesheet"]').forEach((link) => {
+      if (link.href === href) link.remove();
+    });
+    return new Promise((resolve, reject) => {
+      const link = Object.assign(document.createElement('link'), { rel: 'stylesheet', href });
+      link.dataset.nexusChatRetry = '';
+      link.onload = resolve;
+      link.onerror = () => {
+        link.remove();
+        reject(new Error(`NexusChat stylesheet failed to load: ${href}`));
+      };
+      document.head.append(link);
+    });
+  });
+  return Promise.all(reloads);
+}
+
+// A chat served by its Vite dev server ships React Fast Refresh code, which
+// throws unless the page ran @vitejs/plugin-react's preamble. Only a local
+// dev server can be one, so only there is it probed (GET; Vite ignores HEAD).
+async function installReactRefreshPreamble(base) {
+  if (window.__vite_plugin_react_preamble_installed__) return;
+  if (!/^(localhost|127\.0\.0\.1|\[::1\])$|\.localhost$/.test(new URL(base).hostname)) return;
+  try {
+    const url = new URL('@react-refresh', base).href;
+    const probe = await fetch(url, { signal: AbortSignal.timeout(3_000) });
+    if (!probe.ok || !probe.headers.get('content-type')?.includes('javascript')) return;
+    const runtime = await import(/* @vite-ignore */ /* webpackIgnore: true */ url);
+    runtime.default.injectIntoGlobalHook(window);
+    window.$RefreshReg$ = () => {};
+    window.$RefreshSig$ = () => (type) => type;
+    window.__vite_plugin_react_preamble_installed__ = true;
+  } catch {
+    // Not a dev-served chat.
+  }
+}
+
 async function importMount(entry) {
   // The browser remembers a failed import by URL, so every attempt after the
   // first asks for a new one, or it would never reach the network again.
   const attempt = attempts.get(entry) ?? 0;
   attempts.set(entry, attempt + 1);
+  const base = new URL('.', entry).href;
+  captureFailedStylesheets(base);
+  await installReactRefreshPreamble(base);
+  if (attempt) await reloadFailedStylesheets();
   const url = new URL(entry);
   if (attempt) url.searchParams.set('nexus-chat-attempt', String(attempt));
   const remote = await import(/* @vite-ignore */ /* webpackIgnore: true */ url.href);
@@ -42,9 +107,25 @@ async function importMount(entry) {
   if (typeof module?.default !== 'function') {
     throw new Error('NexusChat remote did not expose a mount function.');
   }
+  loadedVersion =
+    typeof module.NEXUS_CHAT_VERSION === 'string' ? module.NEXUS_CHAT_VERSION : undefined;
   return module.default;
 }
 
+/**
+ * Forgets a loaded chat, so the next load fetches it again: after it failed
+ * while running (a redeploy can leave it asking for files that are gone).
+ */
+export function forgetNexusChat(source) {
+  // A source with no URL was never loaded.
+  if (source.copilotUrl || source.assetsUrl) loads.delete(entryUrl(source));
+}
+
+/** The version the last loaded chat reports (for error reports); undefined before a load. */
+export function loadedNexusChatVersion() {
+  return loadedVersion;
+}
+
 /**
  * Loads the chat once per source and resolves to its `mount` function. One
  * retry, since a single failure (a 502 during a rolling restart) is not an

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ahmedramez-org/nexus-chat",
-  "version": "1.0.0-beta.1",
-  "description": "NexusChat for any app: a connector and React component that load the prebuilt chat from IncortaCopilot (or a pinned copy), the host contract types and checks, and the chat bundle itself.",
+  "version": "1.0.0-beta.3",
+  "description": "NexusChat for any app: a connector and React component that load the prebuilt chat from IncortaCopilot (or a pinned copy), and the host contract types and checks.",
   "license": "UNLICENSED",
   "repository": {
     "type": "git",
@@ -31,7 +31,6 @@
       "types": "./contract/host.d.ts",
       "default": "./contract/host.js"
     },
-    "./remote/*": "./remote/*",
     "./package.json": "./package.json"
   },
   "files": [
@@ -40,7 +39,6 @@
     "react.js",
     "react.d.ts",
     "contract",
-    "remote",
     "README.md"
   ],
   "publishConfig": {

package/react.d.ts

@@ -5,38 +5,74 @@ import type {
   HostTheme,
   HostUser,
   MountNexusChatOptions,
+  NexusChatEnvironment,
   NexusChatHandle,
+  NexusChatWindow,
 } from './index.js';
 
-export interface NexusChatProps extends Omit<MountNexusChatOptions, 'environment' | 'window'> {
-  theme: HostTheme;
+/** The chat mounted into this page, sharing its session. It fills its box. */
+export interface DirectNexusChatProps extends Omit<
+  MountNexusChatOptions,
+  'environment' | 'window'
+> {
+  embedUrl?: undefined;
+  /** Required unless `environment` is given. */
+  theme?: HostTheme;
   /** Default: the browser's language. */
   locale?: string;
   /** Absent: follows `locale`. */
   direction?: HostDirection;
   tenantId?: string;
   user?: HostUser;
+  /** The app's own contract environment, used as is instead of the props above. */
+  environment?: NexusChatEnvironment;
   /**
    * The app owns the chat's window (a docked panel, an overlay): the chat
-   * shows a dock toggle while `canDock`, and a close button.
+   * shows a dock toggle while `canDock`, and a close button. A contract
+   * `NexusChatWindow` is used as is.
    */
-  window?: {
-    docked: boolean;
-    canDock: boolean;
-    setDocked(docked: boolean): void;
-    close(): void;
-  };
-  /** The chat is mounted: `ask` and `attach` are available. */
-  onReady?(chat: NexusChatHandle): void;
+  window?:
+    | {
+        docked: boolean;
+        canDock: boolean;
+        setDocked(docked: boolean): void;
+        close(): void;
+      }
+    | NexusChatWindow;
+  /** The chat is mounted (`ask` and `attach` are available); `null` once it unmounts. */
+  onReady?(chat: NexusChatHandle | null): void;
   /** The chat could not load (after its retry and deadline). */
   onLoadError?(error: Error): void;
   className?: string;
   style?: CSSProperties;
 }
 
+export type NexusChatMode = 'floating' | 'docked' | 'fullscreen';
+
+/**
+ * The chat in an <iframe> served by Incorta, on the user's own Incorta
+ * session (the app never holds a token). It draws its window: a launcher
+ * icon that opens the chat floating, docked on the right, or fullscreen.
+ */
+export interface EmbeddedNexusChatProps {
+  /** Incorta's chat page: `<incorta>/copilot/nexus-chat/embed.html`. */
+  embedUrl: string;
+  /** Where the chat may open, in launcher order. Default: all three. */
+  modes?: NexusChatMode[];
+  /** Open on load in this mode. Default: the launcher icon only. */
+  defaultMode?: NexusChatMode;
+  /** Default `'light'`; followed live. */
+  theme?: HostTheme;
+  /** Read once, when the chat first opens. Default: the browser's language. */
+  locale?: string;
+}
+
+export type NexusChatProps = DirectNexusChatProps | EmbeddedNexusChatProps;
+
 /**
- * The chat as a React component. It fills its box. `connection`, `chat`,
- * `actions`, `events`, `instanceId`, `assetsUrl` and `timeoutMs` are read
- * once at mount; the other props update the running chat.
+ * The chat as a React component. Direct: it fills its box; `connection`,
+ * `chat`, `actions`, `events`, `instanceId`, `assetsUrl` and `timeoutMs` are
+ * read once at mount, and the other props update the running chat.
+ * Embedded (`embedUrl`): it draws its own window.
  */
 export function NexusChat(props: NexusChatProps): ReactElement;