@oceanum/oceanumlab 4.6.1 → 4.7.0

package/lib/DatameshUI.d.ts

@@ -1,5 +1,15 @@
 import React from 'react';
 import { ReactWidget } from '@jupyterlab/apputils';
 export declare class DatameshUI extends ReactWidget {
+    private _url;
+    /** `url` is the `datameshUiUrl` setting. */
+    constructor(_url: string);
+    /**
+     * Point the panel at the `datameshUiUrl` setting's new value. The iframe
+     * reloads only if its address actually changes.
+     */
+    set url(url: string);
+    /** The iframe's window, for telling its messages apart; `null` if none. */
+    get frame(): Window | null;
     render(): React.ReactElement;
 }

package/lib/DatameshUI.js

@@ -1,8 +1,26 @@
 import React from 'react';
 import { ReactWidget } from '@jupyterlab/apputils';
-import { DATAMESH_UI_SERVICE } from './constants';
+import { datameshUiSrc } from './datameshUiUrl';
 export class DatameshUI extends ReactWidget {
+    /** `url` is the `datameshUiUrl` setting. */
+    constructor(_url) {
+        super();
+        this._url = _url;
+    }
+    /**
+     * Point the panel at the `datameshUiUrl` setting's new value. The iframe
+     * reloads only if its address actually changes.
+     */
+    set url(url) {
+        this._url = url;
+        this.update();
+    }
+    /** The iframe's window, for telling its messages apart; `null` if none. */
+    get frame() {
+        var _a, _b;
+        return (_b = (_a = this.node.querySelector('iframe')) === null || _a === void 0 ? void 0 : _a.contentWindow) !== null && _b !== void 0 ? _b : null;
+    }
     render() {
-        return (React.createElement("iframe", { src: `${DATAMESH_UI_SERVICE}`, className: "datamesh-iframe" }));
+        return (React.createElement("iframe", { src: datameshUiSrc(this._url), className: "datamesh-iframe" }));
     }
 }

package/lib/DatameshWidget.d.ts

@@ -2,7 +2,7 @@ import { JupyterFrontEnd } from '@jupyterlab/application';
 import { ReactWidget } from '@jupyterlab/apputils';
 import { LabIcon } from '@jupyterlab/ui-components';
 import { CommandRegistry } from '@lumino/commands';
-import { Signal } from '@lumino/signaling';
+import { ISignal, Signal } from '@lumino/signaling';
 import { Widget } from '@lumino/widgets';
 import React from 'react';
 export interface IDatasource {
@@ -40,6 +40,16 @@ export interface IDatameshWidgetProps {
     name: string;
     icon: LabIcon;
     openDatameshUI: any;
+    /** The `datameshUiUrl` setting. */
+    datameshUiUrl: () => string;
+    /** The Datamesh UI panel's iframe window; `null` when the panel is closed. */
+    datameshUiFrame: () => Window | null;
+    /** The `datameshToken` setting. */
+    datameshToken: () => string;
+    /** The `aiBackendUrl` setting. */
+    aiBackendUrl: () => string;
+    /** Emitted when the settings change. */
+    settingsChanged: ISignal<unknown, void>;
     commands: CommandRegistry;
     getCurrentWidget: () => Widget;
 }

package/lib/DatameshWidget.js

@@ -9,7 +9,8 @@ import { Signal } from '@lumino/signaling';
 import React from 'react';
 import { marked } from 'marked';
 import { DatasourceItem } from './DatasourceItem';
-import { OCEANUM_AI_BACKEND_URL } from './constants';
+import { SIGN_IN_COMMAND, aiBackendUrl, aiCredentialSource, canSignIn, pastedToken, resolveAiCredential, signInToken } from './aiBackend';
+import { isDatameshUiMessage } from './datameshUiUrl';
 import { describeProgress, onProgress } from './progress';
 // Configure marked for safe rendering
 marked.setOptions({
@@ -283,30 +284,71 @@ class DatameshWorkspaceDisplay extends React.Component {
         });
     }
 }
+function readAiAccess(commands, settings) {
+    const datameshToken = settings.datameshToken();
+    return {
+        source: aiCredentialSource(datameshToken, commands),
+        pasted: pastedToken(datameshToken),
+        canSignIn: canSignIn(commands),
+        backend: aiBackendUrl(settings.aiBackendUrl())
+    };
+}
 /**
- * Shows a message prompting user to configure their Datamesh token.
- * Only renders when no token is set.
+ * How the sidebar can reach Oceanum AI, read again whenever the settings or the
+ * commands change: the host calls `notifyCommandChanged` when the user signs
+ * in or out.
+ *
+ * Only the registry's queries are used, never `execute`, and nothing runs on a
+ * timer: every executed command closes JupyterLab's command palette.
  */
-function TokenConfigMessage({ commands }) {
-    const [hasToken, setHasToken] = React.useState(!!window.datameshToken);
+function useAiAccess(commands, settings) {
+    const [access, setAccess] = React.useState(() => readAiAccess(commands, settings));
     React.useEffect(() => {
-        const checkToken = () => setHasToken(!!window.datameshToken);
-        const interval = setInterval(checkToken, 1000);
-        return () => clearInterval(interval);
-    }, []);
-    if (hasToken) {
+        const update = () => {
+            const next = readAiAccess(commands, settings);
+            // Same content keeps the same object, so nothing downstream re-runs.
+            setAccess(prev => JSON.stringify(prev) === JSON.stringify(next) ? prev : next);
+        };
+        // Anything that changed between the first render and now.
+        update();
+        commands.commandChanged.connect(update);
+        settings.settingsChanged.connect(update);
+        return () => {
+            commands.commandChanged.disconnect(update);
+            settings.settingsChanged.disconnect(update);
+        };
+    }, [commands, settings]);
+    return access;
+}
+/**
+ * Shows a message prompting the user to sign in to Oceanum.io, or to configure
+ * their Datamesh token where the site has no sign-in. Only renders when there
+ * is no credential.
+ */
+function TokenConfigMessage({ commands, settings }) {
+    const access = useAiAccess(commands, settings);
+    if (access.source) {
         return null;
     }
+    const openSettings = () => commands.execute('settingeditor:open', { query: 'Oceanum' });
+    if (access.canSignIn) {
+        const signIn = () => commands.execute(SIGN_IN_COMMAND).catch(() => {
+            console.warn('Oceanum AI: could not start signing in to Oceanum.io.');
+        });
+        return (React.createElement("div", { className: "oceanum-token-config" },
+            React.createElement("a", { onClick: () => void signIn() }, "Sign in to Oceanum.io"),
+            " to use Oceanum AI, or set a ",
+            React.createElement("a", { onClick: openSettings }, "Datamesh token"),
+            "."));
+    }
     return (React.createElement("div", { className: "oceanum-token-config" },
-        "Set your",
-        ' ',
-        React.createElement("a", { onClick: () => commands.execute('settingeditor:open', { query: 'Oceanum' }) }, "Datamesh token"),
-        ' ',
-        "to enable Oceanum.oi services",
+        "Set your ",
+        React.createElement("a", { onClick: openSettings }, "Datamesh token"),
+        " to enable Oceanum.io services",
         ' ',
         React.createElement("a", { href: "https://home.oceanum.io/account", target: "_blank", rel: "noopener noreferrer" }, "Get token here")));
 }
-function AIChatPanel({ commands }) {
+function AIChatPanel({ commands, settings }) {
     const [messages, setMessages] = React.useState([]);
     const [input, setInput] = React.useState('');
     const [loading, setLoading] = React.useState(false);
@@ -321,49 +363,75 @@ function AIChatPanel({ commands }) {
     const [history, setHistory] = React.useState([]);
     const [historyIndex, setHistoryIndex] = React.useState(-1);
     const [tempInput, setTempInput] = React.useState('');
-    // Track the actual token value to detect changes
-    const [token, setToken] = React.useState(window.datameshToken || '');
-    const hasToken = !!token;
+    // Which credential and address the chat has, as the settings and the host
+    // report them.
+    const access = useAiAccess(commands, settings);
+    // What the capabilities depend on: which credential, the pasted token and
+    // the address. Not the sign-in token itself: it refreshes, and finding it out
+    // runs the host's command.
+    const capabilitiesKey = access.source
+        ? JSON.stringify([access.source, access.pasted, access.backend])
+        : '';
     // Check if code capability is enabled (null = loading/unknown)
     const [codeEnabled, setCodeEnabled] = React.useState(null);
-    // Re-check token periodically (settings may change)
+    // The sidebar's one pending access-token request, shared rather than
+    // repeated if the capabilities are asked for again before it answers.
+    const tokenRequest = React.useRef(null);
+    // Fetch capabilities when the credential or the address changes
     React.useEffect(() => {
-        const checkToken = () => {
-            const currentToken = window.datameshToken || '';
-            if (currentToken !== token) {
-                setToken(currentToken);
-            }
-        };
-        const interval = setInterval(checkToken, 1000);
-        return () => clearInterval(interval);
-    }, [token]);
-    // Fetch capabilities when token changes
-    React.useEffect(() => {
-        if (!token) {
+        if (!access.source) {
             setCodeEnabled(null);
             return;
         }
+        // An answer for a credential that has since changed is dropped.
+        let current = true;
+        const signInTokenOnce = () => {
+            if (!tokenRequest.current) {
+                tokenRequest.current = signInToken(commands)().finally(() => {
+                    tokenRequest.current = null;
+                });
+            }
+            return tokenRequest.current;
+        };
         const fetchCapabilities = async () => {
+            const credential = await resolveAiCredential(access.pasted, signInTokenOnce);
+            if (!current) {
+                return;
+            }
+            if (!credential) {
+                // The host says signed in but has no token to give: leave it to a
+                // request to report, rather than hide the chat.
+                setCodeEnabled(null);
+                return;
+            }
             try {
-                const response = await fetch(`${OCEANUM_AI_BACKEND_URL}/api/capabilities`, {
-                    headers: {
-                        'X-Datamesh-Token': token
-                    }
+                const response = await fetch(`${access.backend}/api/capabilities`, {
+                    headers: credential.headers
                 });
+                if (!current) {
+                    return;
+                }
                 if (response.ok) {
                     const data = await response.json();
-                    setCodeEnabled(data.code === true);
+                    if (current) {
+                        setCodeEnabled(data.code === true);
+                    }
                 }
                 else {
                     setCodeEnabled(false);
                 }
             }
             catch (_a) {
-                setCodeEnabled(false);
+                if (current) {
+                    setCodeEnabled(false);
+                }
             }
         };
         void fetchCapabilities();
-    }, [token]);
+        return () => {
+            current = false;
+        };
+    }, [capabilitiesKey]);
     // Auto-scroll to bottom when messages change
     React.useEffect(() => {
         var _a;
@@ -500,8 +568,8 @@ function AIChatPanel({ commands }) {
             return;
         }
     };
-    // Hide AI panel if no token or code capability is not enabled
-    if (!hasToken || codeEnabled === false) {
+    // Hide AI panel if no credential or code capability is not enabled
+    if (!access.source || codeEnabled === false) {
         return null;
     }
     return (React.createElement("div", { className: "oceanum-ai-chat" },
@@ -541,6 +609,11 @@ export class DatameshConnectWidget extends ReactWidget {
         window.addEventListener('message', this.receiveIFrameMessage.bind(this), false);
     }
     receiveIFrameMessage(event) {
+        // Any page or frame can post to this window; only the Datamesh UI panel
+        // may change the workspace.
+        if (!isDatameshUiMessage(event, this.props.datameshUiUrl(), this.props.datameshUiFrame())) {
+            return;
+        }
         if (event.data && event.data.action === 'workspace-modify') {
             this.datameshWorkspaceSpec = {
                 id: event.data.id,
@@ -565,8 +638,8 @@ export class DatameshConnectWidget extends ReactWidget {
                 React.createElement("div", { className: "open-datamesh-ui", onClick: this.props.openDatameshUI, title: "Open Datamesh UI" }, React.createElement(addIcon.react, { height: "20px", verticalAlign: "middle" }))),
             React.createElement("div", { className: "datamesh-connect-workspace" },
                 React.createElement(UseSignal, { signal: this.renderSignal, initialArgs: null }, (_, datameshWorkspace) => this.renderDisplay(datameshWorkspace)),
-                React.createElement(TokenConfigMessage, { commands: this.props.commands })),
+                React.createElement(TokenConfigMessage, { commands: this.props.commands, settings: this.props })),
             React.createElement("div", { className: "datamesh-connect-divider" }),
-            React.createElement(AIChatPanel, { commands: this.props.commands })));
+            React.createElement(AIChatPanel, { commands: this.props.commands, settings: this.props })));
     }
 }

package/lib/aiBackend.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Where the Oceanum AI backend is, and what a request to it is signed with.
+ *
+ * The backend accepts either a Datamesh token (`X-Datamesh-Token`) or an
+ * Oceanum.io access token (`Authorization: Bearer`). A token pasted into the
+ * settings is explicit, so it wins; otherwise a host that signs users in to
+ * Oceanum.io -- Oceanum Notebook -- lends its sign-in through its commands.
+ * Plain JupyterLab has no such commands and needs the pasted token.
+ *
+ * Whether the user is signed in, or can sign in, is read with the registry's
+ * queries (`isVisible`, `isEnabled`), never by running a command: every
+ * `execute` emits `commandExecuted`, which closes JupyterLab's command palette.
+ * The access-token command is run only when a token is actually needed.
+ */
+import type { CommandRegistry } from '@lumino/commands';
+/**
+ * The host's command answering with the current Oceanum.io access token (a
+ * JWT), or null when signed out. The token is cached and refreshed by the
+ * host, so it is asked for on every use rather than kept.
+ */
+export declare const ACCESS_TOKEN_COMMAND = "oceanum-auth:access-token";
+/**
+ * The host's command that starts signing in to Oceanum.io. Enabled only where
+ * sign-in is configured for the site.
+ */
+export declare const SIGN_IN_COMMAND = "oceanum-auth:sign-in";
+/** The host's command that signs out. Visible only while signed in. */
+export declare const SIGN_OUT_COMMAND = "oceanum-auth:sign-out";
+/** The part of the command registry the sign-in is reached through. */
+export type AuthCommands = Pick<CommandRegistry, 'hasCommand' | 'execute' | 'isEnabled' | 'isVisible'>;
+export type AiCredentialSource = 'datamesh-token' | 'sign-in';
+export interface IAiCredential {
+    /** Which credential it is: the 401 message differs. */
+    source: AiCredentialSource;
+    headers: Record<string, string>;
+}
+/**
+ * The backend address for an `aiBackendUrl` setting value, without a trailing
+ * slash so a path can be appended. An invalid value falls back to the default.
+ */
+export declare function aiBackendUrl(value: string | null | undefined): string;
+/** A `datameshToken` setting value, trimmed; '' when there is none. */
+export declare function pastedToken(datameshToken: unknown): string;
+/** Whether the host can sign the user in to Oceanum.io on this site. */
+export declare function canSignIn(commands: AuthCommands): boolean;
+/** Whether the host says the user is signed in to Oceanum.io. */
+export declare function isSignedIn(commands: AuthCommands): boolean;
+/**
+ * Which credential a request would carry, without fetching it: runs no
+ * command, so it is safe to ask whenever something changes.
+ */
+export declare function aiCredentialSource(datameshToken: unknown, commands: AuthCommands): AiCredentialSource | null;
+/**
+ * Asks the host for its Oceanum.io access token; null without the command.
+ * This runs a command: call it only when a token is needed for a request.
+ */
+export declare function signInToken(commands: AuthCommands): () => Promise<unknown>;
+/**
+ * The credential for a request: the pasted Datamesh token if there is one,
+ * otherwise the host's sign-in, otherwise null.
+ *
+ * @param datameshToken The `datameshToken` setting value.
+ * @param getSignInToken Asked only without a pasted token. Anything but a
+ *   non-empty string -- including a rejection -- counts as signed out.
+ */
+export declare function resolveAiCredential(datameshToken: unknown, getSignInToken: () => Promise<unknown>): Promise<IAiCredential | null>;

package/lib/aiBackend.js

@@ -0,0 +1,101 @@
+import { OCEANUM_AI_BACKEND_URL } from './constants';
+import { validHttpUrl } from './httpUrl';
+/**
+ * The host's command answering with the current Oceanum.io access token (a
+ * JWT), or null when signed out. The token is cached and refreshed by the
+ * host, so it is asked for on every use rather than kept.
+ */
+export const ACCESS_TOKEN_COMMAND = 'oceanum-auth:access-token';
+/**
+ * The host's command that starts signing in to Oceanum.io. Enabled only where
+ * sign-in is configured for the site.
+ */
+export const SIGN_IN_COMMAND = 'oceanum-auth:sign-in';
+/** The host's command that signs out. Visible only while signed in. */
+export const SIGN_OUT_COMMAND = 'oceanum-auth:sign-out';
+/**
+ * The backend address for an `aiBackendUrl` setting value, without a trailing
+ * slash so a path can be appended. An invalid value falls back to the default.
+ */
+export function aiBackendUrl(value) {
+    const url = validHttpUrl(value, OCEANUM_AI_BACKEND_URL);
+    return `${url.origin}${url.pathname.replace(/\/+$/, '')}`;
+}
+/** A `datameshToken` setting value, trimmed; '' when there is none. */
+export function pastedToken(datameshToken) {
+    return typeof datameshToken === 'string' ? datameshToken.trim() : '';
+}
+/**
+ * Asks a query of the host's command, treating a missing command, or a query
+ * that throws, as false. Queries never emit `commandExecuted`.
+ */
+function query(commands, id, which) {
+    try {
+        return commands.hasCommand(id) && commands[which](id);
+    }
+    catch (_a) {
+        return false;
+    }
+}
+/** Whether the host can sign the user in to Oceanum.io on this site. */
+export function canSignIn(commands) {
+    return query(commands, SIGN_IN_COMMAND, 'isEnabled');
+}
+/** Whether the host says the user is signed in to Oceanum.io. */
+export function isSignedIn(commands) {
+    return query(commands, SIGN_OUT_COMMAND, 'isVisible');
+}
+/**
+ * Which credential a request would carry, without fetching it: runs no
+ * command, so it is safe to ask whenever something changes.
+ */
+export function aiCredentialSource(datameshToken, commands) {
+    if (pastedToken(datameshToken)) {
+        return 'datamesh-token';
+    }
+    if (commands.hasCommand(ACCESS_TOKEN_COMMAND) && isSignedIn(commands)) {
+        return 'sign-in';
+    }
+    return null;
+}
+/**
+ * Asks the host for its Oceanum.io access token; null without the command.
+ * This runs a command: call it only when a token is needed for a request.
+ */
+export function signInToken(commands) {
+    return async () => commands.hasCommand(ACCESS_TOKEN_COMMAND)
+        ? commands.execute(ACCESS_TOKEN_COMMAND)
+        : null;
+}
+/**
+ * The credential for a request: the pasted Datamesh token if there is one,
+ * otherwise the host's sign-in, otherwise null.
+ *
+ * @param datameshToken The `datameshToken` setting value.
+ * @param getSignInToken Asked only without a pasted token. Anything but a
+ *   non-empty string -- including a rejection -- counts as signed out.
+ */
+export async function resolveAiCredential(datameshToken, getSignInToken) {
+    const pasted = pastedToken(datameshToken);
+    if (pasted) {
+        return {
+            source: 'datamesh-token',
+            headers: { 'X-Datamesh-Token': pasted }
+        };
+    }
+    let token;
+    try {
+        token = await getSignInToken();
+    }
+    catch (_a) {
+        return null;
+    }
+    const signedIn = typeof token === 'string' ? token.trim() : '';
+    if (!signedIn) {
+        return null;
+    }
+    return {
+        source: 'sign-in',
+        headers: { Authorization: `Bearer ${signedIn}` }
+    };
+}

package/lib/chatRouter.d.ts

@@ -1,4 +1,5 @@
 import { ISettingRegistry } from '@jupyterlab/settingregistry';
+import { type AuthCommands } from './aiBackend';
 import type { Progress } from './progress';
 import type { ObservedRun } from './notebookRun';
 import type { INotebookSnapshot } from './notebookContext';
@@ -36,14 +37,17 @@ export declare class ChatRouterError extends Error {
 }
 export declare class ChatRouter {
     private _settings;
+    private _commands;
     private _notebook;
     /**
+     * @param _commands Where the host's Oceanum.io sign-in is asked for, when
+     *   there is no pasted Datamesh token.
      * @param _notebook What the conversation's notebook holds -- the one its
      *   answers are placed in -- or null if there is nothing to send. Asked on
      *   every request, so it follows the conversation rather than whichever tab
      *   happens to be active.
      */
-    constructor(_settings: ISettingRegistry.ISettings, _notebook: () => Promise<INotebookSnapshot | null>);
+    constructor(_settings: ISettingRegistry.ISettings, _commands: AuthCommands, _notebook: () => Promise<INotebookSnapshot | null>);
     route(prompt: string, chatHistory?: ChatMessage[], signal?: AbortSignal, onProgress?: (progress: Progress) => void): Promise<RouteResult>;
     /**
      * The notebook half of the execute loop: the code ran in the user's own

package/lib/chatRouter.js

@@ -1,4 +1,4 @@
-import { OCEANUM_AI_BACKEND_URL } from './constants';
+import { aiBackendUrl, canSignIn, resolveAiCredential, signInToken } from './aiBackend';
 import { readSse } from './sse';
 import { formatNotebookCells } from './notebookContext';
 export class ChatRouterError extends Error {
@@ -31,13 +31,16 @@ function asOceanumResponse(data) {
 }
 export class ChatRouter {
     /**
+     * @param _commands Where the host's Oceanum.io sign-in is asked for, when
+     *   there is no pasted Datamesh token.
      * @param _notebook What the conversation's notebook holds -- the one its
      *   answers are placed in -- or null if there is nothing to send. Asked on
      *   every request, so it follows the conversation rather than whichever tab
      *   happens to be active.
      */
-    constructor(_settings, _notebook) {
+    constructor(_settings, _commands, _notebook) {
         this._settings = _settings;
+        this._commands = _commands;
         this._notebook = _notebook;
     }
     async route(prompt, chatHistory = [], signal, onProgress) {
@@ -99,17 +102,22 @@ export class ChatRouter {
     }
     async _send(path, payload, signal, onProgress) {
         var _a;
-        const token = this._settings.get('datameshToken').composite;
-        if (!token) {
-            throw new ChatRouterError('Datamesh token not configured. Set your token in Settings → Oceanum.io.');
+        // Resolved per request, not once: the sign-in token refreshes, and the
+        // user can sign in, sign out or paste a token between two requests.
+        const credential = await resolveAiCredential(this._settings.get('datameshToken').composite, signInToken(this._commands));
+        if (!credential) {
+            throw new ChatRouterError(canSignIn(this._commands)
+                ? 'Not signed in. Sign in to Oceanum.io to use Oceanum AI, or set a Datamesh token in Settings → Oceanum.io.'
+                : 'Datamesh token not configured. Set your token in Settings → Oceanum.io.');
         }
+        const backend = aiBackendUrl(this._settings.get('aiBackendUrl').composite);
         let response;
         try {
-            response = await fetch(`${OCEANUM_AI_BACKEND_URL}${path}`, {
+            response = await fetch(`${backend}${path}`, {
                 method: 'POST',
                 headers: {
                     'Content-Type': 'application/json',
-                    'X-Datamesh-Token': token,
+                    ...credential.headers,
                     // Ask for the streamed form only when someone is listening. The
                     // server requires the media type to be NAMED -- a wildcard never
                     // selects it -- so omitting this is what keeps the plain JSON path
@@ -126,10 +134,20 @@ export class ChatRouter {
             if (signal === null || signal === void 0 ? void 0 : signal.aborted) {
                 throw err;
             }
-            throw new ChatRouterError(`Could not reach Oceanum AI backend at ${OCEANUM_AI_BACKEND_URL}. Is it running?`);
+            throw new ChatRouterError(`Could not reach Oceanum AI backend at ${backend}. Is it running?`);
         }
         if (response.status === 401) {
-            throw new ChatRouterError('Invalid or expired Datamesh token.', 401);
+            let message = 'Invalid or expired Datamesh token.';
+            if (credential.source === 'sign-in') {
+                message =
+                    'Your Oceanum.io sign-in was not accepted. Sign in to Oceanum.io again.';
+            }
+            else if (canSignIn(this._commands)) {
+                // A pasted token wins over the sign-in, so say how to fall back to it.
+                message +=
+                    ' Update it, or clear it to use your Oceanum.io sign-in, in Settings → Oceanum.io.';
+            }
+            throw new ChatRouterError(message, 401);
         }
         if (!response.ok) {
             let detail = '';

package/lib/constants.d.ts

@@ -2,7 +2,7 @@
  * Build-time constants for Oceanum AI integration.
  * These values are compiled into the extension.
  */
-/** URL of the Oceanum AI backend service */
+/** Default URL of the Oceanum AI backend service (the `aiBackendUrl` setting) */
 export declare const OCEANUM_AI_BACKEND_URL = "https://ai.oceanum.io";
 /** URL of the Datamesh UI embedded in the Datamesh panel */
 export declare const DATAMESH_UI_SERVICE = "https://ui.datamesh.oceanum.io";

package/lib/constants.js

@@ -2,7 +2,7 @@
  * Build-time constants for Oceanum AI integration.
  * These values are compiled into the extension.
  */
-/** URL of the Oceanum AI backend service */
+/** Default URL of the Oceanum AI backend service (the `aiBackendUrl` setting) */
 export const OCEANUM_AI_BACKEND_URL = 'https://ai.oceanum.io';
 /** URL of the Datamesh UI embedded in the Datamesh panel */
 export const DATAMESH_UI_SERVICE = 'https://ui.datamesh.oceanum.io';

package/lib/datameshUiUrl.d.ts

@@ -0,0 +1,15 @@
+/** The Datamesh UI address to use for a `datameshUiUrl` setting value. */
+export declare function validDatameshUiUrl(url: string | null | undefined): URL;
+/**
+ * The panel's iframe `src`: the Datamesh UI in embed mode, which hides the
+ * Oceanum.io navigator. Any query the setting already has is kept.
+ */
+export declare function datameshUiSrc(url: string | null | undefined): string;
+/**
+ * Whether a `message` event was posted by the Datamesh UI panel.
+ *
+ * Any page or frame can post to this window, so a message counts only when it
+ * comes from the panel's iframe (`frame`, its `contentWindow`; `null` when the
+ * panel is not open) and from the configured Datamesh UI's origin.
+ */
+export declare function isDatameshUiMessage(event: Pick<MessageEvent, 'origin' | 'source'>, url: string | null | undefined, frame: Window | null): boolean;

package/lib/datameshUiUrl.js

@@ -0,0 +1,35 @@
+/**
+ * The Datamesh UI panel's address, and which messages may come from it.
+ *
+ * The address is a setting (`datameshUiUrl`), so a deployment can point the
+ * panel at another Datamesh UI -- a dev one, say. A setting is typed in by
+ * hand, so anything that is not an http(s) URL falls back to the default
+ * rather than ending up in an iframe's `src`.
+ */
+import { DATAMESH_UI_SERVICE } from './constants';
+import { validHttpUrl } from './httpUrl';
+/** The Datamesh UI address to use for a `datameshUiUrl` setting value. */
+export function validDatameshUiUrl(url) {
+    return validHttpUrl(url, DATAMESH_UI_SERVICE);
+}
+/**
+ * The panel's iframe `src`: the Datamesh UI in embed mode, which hides the
+ * Oceanum.io navigator. Any query the setting already has is kept.
+ */
+export function datameshUiSrc(url) {
+    const src = validDatameshUiUrl(url);
+    src.searchParams.set('embed', '1');
+    return src.toString();
+}
+/**
+ * Whether a `message` event was posted by the Datamesh UI panel.
+ *
+ * Any page or frame can post to this window, so a message counts only when it
+ * comes from the panel's iframe (`frame`, its `contentWindow`; `null` when the
+ * panel is not open) and from the configured Datamesh UI's origin.
+ */
+export function isDatameshUiMessage(event, url, frame) {
+    return (!!frame &&
+        event.source === frame &&
+        event.origin === validDatameshUiUrl(url).origin);
+}

package/lib/httpUrl.d.ts

@@ -0,0 +1,9 @@
+/**
+ * An address typed into a setting, checked before anything uses it.
+ *
+ * A setting is typed in by hand, so anything that is not an http(s) URL falls
+ * back to the default rather than ending up in an iframe's `src` or a
+ * request's address.
+ */
+/** `value` as an http(s) URL, or `fallback` when it is empty or not one. */
+export declare function validHttpUrl(value: string | null | undefined, fallback: string): URL;