@oceanum/oceanumlab 4.7.0 → 4.7.2

package/lib/auth/tokens.d.ts

@@ -0,0 +1,102 @@
+import { Token } from '@lumino/coreutils';
+import { ISignal } from '@lumino/signaling';
+/**
+ * One Oceanum deployment (production or development).
+ */
+export interface IOceanumEnvironment {
+    /** Page hostnames served by this environment, e.g. `notebook.oceanum.io`. */
+    readonly hosts: readonly string[];
+    /** Auth0 tenant domain, e.g. `auth.oceanum.io`. */
+    readonly auth0Domain: string;
+    /** Auth0 SPA client id. */
+    readonly clientId: string;
+    /**
+     * The Oceanum apps domain, e.g. `oceanum.io`. The Oceanum nav builds its app, account,
+     * docs and sign-out URLs from it (`https://platform.oceanum.io/account`, ...).
+     */
+    readonly oceanumDomain: string;
+    /** Service base URLs for this environment. */
+    readonly urls: IOceanumServiceUrls;
+    /**
+     * Whether to check for an existing Oceanum.io session with a full-page redirect when the
+     * silent iframe check finds none. Only for a tenant on another site than the notebook
+     * (browsers that block third-party cookies hide the session from the iframe), and only where
+     * the site origin is an allowed callback URL.
+     */
+    readonly signInRedirect: boolean;
+    /**
+     * Whether Oceanum.io is the only file management this host shows, as on
+     * notebook.oceanum.io: the file browser and the File menu's local-file entries go,
+     * and every local save is pushed to the spec store. `'local'` (the default when
+     * absent) keeps JupyterLab's file management alongside the Oceanum commands.
+     */
+    readonly fileManagement?: 'local' | 'oceanum';
+}
+/** Service base URLs for an environment, without trailing slashes. */
+export interface IOceanumServiceUrls {
+    /** Datamesh gateway, e.g. `https://datamesh.oceanum.io`. */
+    readonly datamesh: string;
+    /** Spec store, e.g. `https://specs.oceanum.io`. */
+    readonly specs: string;
+    /** User management service (Auth0 user metadata), e.g. `https://manage.oceanum.io`. */
+    readonly manage: string;
+    /**
+     * Datamesh UI, e.g. `https://ui.datamesh.oceanum.io`, shown by oceanumlab's Datamesh panel.
+     * Optional: without it, Oceanum production applies.
+     */
+    readonly datameshUi?: string;
+    /**
+     * Oceanum AI backend, e.g. `https://ai.oceanum.io`, called by oceanumlab's AI chat.
+     * Optional: without it, Oceanum production applies.
+     */
+    readonly ai?: string;
+}
+export type ColorScheme = 'light' | 'dark' | 'auto';
+/** The signed-in user, from the Auth0 ID token claims. */
+export interface IOceanumUser {
+    readonly sub: string;
+    readonly email: string;
+    readonly name: string | null;
+    /** `https://oceanum.io/active_org`. */
+    readonly activeOrg: string | null;
+    /** `https://oceanum.io/color_scheme`. */
+    readonly colorScheme: ColorScheme | null;
+}
+/**
+ * Oceanum.io sign-in state, shared with other Oceanum Notebook extensions.
+ */
+export interface IOceanumAuth {
+    /** The environment for this page, or `null` if sign-in is not configured for this host. */
+    readonly environment: IOceanumEnvironment | null;
+    /** Service URLs for `environment`, or `null` when it is `null`. */
+    readonly urls: IOceanumServiceUrls | null;
+    /** Resolves once any login redirect has been handled and the session restored. */
+    readonly ready: Promise<void>;
+    /** The signed-in user, or `null`. */
+    readonly user: IOceanumUser | null;
+    /** Emits the new user (or `null`) on sign-in and sign-out. */
+    readonly userChanged: ISignal<IOceanumAuth, IOceanumUser | null>;
+    /** Emits the new access token (or `null`) whenever it changes, including refreshes. */
+    readonly tokenChanged: ISignal<IOceanumAuth, string | null>;
+    /**
+     * Start sign-in without leaving the page, so its kernels survive. Resolves once sign-in has
+     * started, not when it completes; watch `userChanged` for the result. Does nothing while a
+     * user is signed in.
+     */
+    signIn(): Promise<void>;
+    /** Sign out of Oceanum.io and clear the session. */
+    signOut(): Promise<void>;
+    /**
+     * A current access token, refreshed if it is near expiry, or `null` when signed out.
+     * Never cache the result: Auth0 access tokens are short-lived.
+     */
+    getAccessToken(): Promise<string | null>;
+}
+/**
+ * The sign-in contract. oceanumlab owns it and exports it from its package entry, because a
+ * Lumino token is matched by object identity: every extension that provides or consumes it
+ * has to import this one object, which JupyterLab arranges by sharing `@oceanum/oceanumlab`
+ * as a singleton module. On an ordinary JupyterLab oceanumlab's own device sign-in provides
+ * it; on notebook.oceanum.io the notebook's Oceanum widget extension does.
+ */
+export declare const IOceanumAuth: Token<IOceanumAuth>;

package/lib/auth/tokens.js

@@ -0,0 +1,9 @@
+import { Token } from '@lumino/coreutils';
+/**
+ * The sign-in contract. oceanumlab owns it and exports it from its package entry, because a
+ * Lumino token is matched by object identity: every extension that provides or consumes it
+ * has to import this one object, which JupyterLab arranges by sharing `@oceanum/oceanumlab`
+ * as a singleton module. On an ordinary JupyterLab oceanumlab's own device sign-in provides
+ * it; on notebook.oceanum.io the notebook's Oceanum widget extension does.
+ */
+export const IOceanumAuth = new Token('@oceanum/oceanumlab:IOceanumAuth', 'Oceanum.io sign-in state and Datamesh access tokens.');

package/lib/chatRouter.d.ts

@@ -39,6 +39,12 @@ export declare class ChatRouter {
     private _settings;
     private _commands;
     private _notebook;
+    /**
+     * The Oceanum AI backend's address: the signed-in deployment's, or empty for the
+     * production default. Deployment configuration, not a setting -- a user-editable
+     * address is somewhere to send the user's credential.
+     */
+    private _backend;
     /**
      * @param _commands Where the host's Oceanum.io sign-in is asked for, when
      *   there is no pasted Datamesh token.
@@ -47,7 +53,13 @@ export declare class ChatRouter {
      *   every request, so it follows the conversation rather than whichever tab
      *   happens to be active.
      */
-    constructor(_settings: ISettingRegistry.ISettings, _commands: AuthCommands, _notebook: () => Promise<INotebookSnapshot | null>);
+    constructor(_settings: ISettingRegistry.ISettings, _commands: AuthCommands, _notebook: () => Promise<INotebookSnapshot | null>, 
+    /**
+     * The Oceanum AI backend's address: the signed-in deployment's, or empty for the
+     * production default. Deployment configuration, not a setting -- a user-editable
+     * address is somewhere to send the user's credential.
+     */
+    _backend?: () => string);
     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

@@ -38,10 +38,17 @@ export class ChatRouter {
      *   every request, so it follows the conversation rather than whichever tab
      *   happens to be active.
      */
-    constructor(_settings, _commands, _notebook) {
+    constructor(_settings, _commands, _notebook, 
+    /**
+     * The Oceanum AI backend's address: the signed-in deployment's, or empty for the
+     * production default. Deployment configuration, not a setting -- a user-editable
+     * address is somewhere to send the user's credential.
+     */
+    _backend = () => '') {
         this._settings = _settings;
         this._commands = _commands;
         this._notebook = _notebook;
+        this._backend = _backend;
     }
     async route(prompt, chatHistory = [], signal, onProgress) {
         const { payload, isCodeCell, context } = await this._gather(prompt, chatHistory);
@@ -110,7 +117,7 @@ export class ChatRouter {
                 ? '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);
+        const backend = aiBackendUrl(this._backend());
         let response;
         try {
             response = await fetch(`${backend}${path}`, {

package/lib/constants.d.ts

@@ -2,7 +2,7 @@
  * Build-time constants for Oceanum AI integration.
  * These values are compiled into the extension.
  */
-/** Default URL of the Oceanum AI backend service (the `aiBackendUrl` setting) */
+/** Default URL of the Oceanum AI backend service, where the deployment names none. */
 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.
  */
-/** Default URL of the Oceanum AI backend service (the `aiBackendUrl` setting) */
+/** Default URL of the Oceanum AI backend service, where the deployment names none. */
 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

@@ -1,8 +1,8 @@
-/** The Datamesh UI address to use for a `datameshUiUrl` setting value. */
+/** The Datamesh UI address to use for a configured 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.
+ * Oceanum.io navigator. Any query the address already has is kept.
  */
 export declare function datameshUiSrc(url: string | null | undefined): string;
 /**

package/lib/datameshUiUrl.js

@@ -1,20 +1,20 @@
 /**
  * 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`.
+ * The address comes from the deployment's sign-in environment, so a development
+ * deployment can point the panel at its own Datamesh UI. It is still written by a
+ * person in a config file, 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. */
+/** The Datamesh UI address to use for a configured 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.
+ * Oceanum.io navigator. Any query the address already has is kept.
  */
 export function datameshUiSrc(url) {
     const src = validDatameshUiUrl(url);

package/lib/index.d.ts

@@ -1,5 +1,6 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
 import { LabIcon } from '@jupyterlab/ui-components';
+import { IOceanumAuth } from './auth/tokens';
 import '../style/index.css';
 export declare const oceanumIcon: LabIcon;
 /**
@@ -12,5 +13,11 @@ export declare const datamesh_connect_extension: JupyterFrontEndPlugin<void>;
  * `oceanum-ai:submit-prompt` command.
  */
 export declare const oceanum_ai_extension: JupyterFrontEndPlugin<void>;
-declare const _default: JupyterFrontEndPlugin<void>[];
+/**
+ * The sign-in contract, exported so another extension can provide or consume it: a Lumino
+ * token is matched by object identity, so everyone has to import this one object, and
+ * JupyterLab shares `@oceanum/oceanumlab` between extensions as a singleton module.
+ */
+export * from './auth/tokens';
+declare const _default: (JupyterFrontEndPlugin<void> | JupyterFrontEndPlugin<IOceanumAuth>)[];
 export default _default;

package/lib/index.js

@@ -12,6 +12,9 @@ import { requestAPI } from './handler';
 import { ChatRouter, ChatRouterError } from './chatRouter';
 import { reporterFor } from './progress';
 import { ConversationPin } from './conversationPin';
+import { deviceAuthPlugin } from './auth/plugin';
+import { IOceanumAuth } from './auth/tokens';
+import { CommandIDs as ShareCommandIDs, sharePlugin } from './share/plugin';
 import { snapshotFromIpynb, snapshotOf } from './notebookContext';
 import { notebookHost } from './notebookHost';
 import { KernelHandoff } from './kernelHandoff';
@@ -38,13 +41,19 @@ export const datamesh_connect_extension = {
         ISettingRegistry,
         IStateDB
     ],
-    activate: (app, palette, restorer, status, settingRegistry) => {
+    // Optional so the panel still loads on a host with no Oceanum environment; the
+    // Notebooks tab then explains why it is empty instead of the panel failing to start.
+    optional: [IOceanumAuth],
+    activate: (app, palette, restorer, status, settingRegistry, stateDB, auth) => {
+        var _a, _b, _c, _d;
         console.log('Oceanum datamesh connect extension is loaded');
-        // The `datameshUiUrl` setting; the default until the settings load.
-        let datameshUiUrl = DATAMESH_UI_SERVICE;
-        // The `aiBackendUrl` and `datameshToken` settings for the AI chat; the
-        // defaults until the settings load.
-        let aiBackendUrl = OCEANUM_AI_BACKEND_URL;
+        // Where the Datamesh UI and Oceanum AI live is the deployment's business, so it comes
+        // from the sign-in environment (the Jupyter server's configuration, or the notebook
+        // site's) and falls back to production. These were user settings until 4.7.1; a
+        // user-editable service address is somewhere to send the user's credential.
+        const datameshUiUrl = (_b = (_a = auth === null || auth === void 0 ? void 0 : auth.urls) === null || _a === void 0 ? void 0 : _a.datameshUi) !== null && _b !== void 0 ? _b : DATAMESH_UI_SERVICE;
+        const aiBackendUrl = (_d = (_c = auth === null || auth === void 0 ? void 0 : auth.urls) === null || _c === void 0 ? void 0 : _c.ai) !== null && _d !== void 0 ? _d : OCEANUM_AI_BACKEND_URL;
+        // The `datameshToken` setting for the AI chat; empty until the settings load.
         let datameshTokenSetting = '';
         // Tells the sidebar the settings above have changed.
         const settingsChanged = new Signal(app);
@@ -60,14 +69,7 @@ export const datamesh_connect_extension = {
                 }).then(res => console.log(res));
             }
             window.injectToken = set.get('injectToken').user;
-            aiBackendUrl = set.get('aiBackendUrl').composite;
             datameshTokenSetting = set.get('datameshToken').composite;
-            // An open Datamesh UI panel follows a change of address.
-            datameshUiUrl = set.get('datameshUiUrl').composite;
-            const datameshUI = findDatameshUI();
-            if (datameshUI) {
-                datameshUI.url = datameshUiUrl;
-            }
             settingsChanged.emit();
         };
         //Try to get the datamesh token from the envars
@@ -109,14 +111,41 @@ export const datamesh_connect_extension = {
             aiBackendUrl: () => aiBackendUrl,
             settingsChanged,
             commands: app.commands,
-            getCurrentWidget
+            getCurrentWidget,
+            auth,
+            openStoredNotebook: id => {
+                app.commands.execute(ShareCommandIDs.open, { id }).catch(error => {
+                    console.error('Oceanum: could not open the stored notebook.', error);
+                });
+            }
         });
         datameshConnectWidget.id = 'datamesh-connect';
         datameshConnectWidget.title.icon = oceanumIcon;
         datameshConnectWidget.title.caption = 'Datamesh Connect';
         restorer.add(datameshConnectWidget, 'datamesh-connect');
+        // The layout restorer restores the widget's place in the shell, not fields on it,
+        // so the chosen tab is kept here. Restoring is best effort: a missing or unreadable
+        // entry just leaves the default.
+        const TAB_STATE_KEY = `${PLUGIN_ID}:tab`;
+        void stateDB
+            .fetch(TAB_STATE_KEY)
+            .then(value => {
+            if (typeof value === 'string') {
+                datameshConnectWidget.selectTab(value);
+            }
+        })
+            .catch(() => undefined);
+        datameshConnectWidget.tabChanged.connect((_, id) => {
+            void stateDB.save(TAB_STATE_KEY, id);
+        });
         // Rank has been chosen somewhat arbitrarily to give priority to the running
         // sessions widget in the sidebar.
+        //
+        // Oceanum Notebook wants this panel first instead, but that is a property of that
+        // distribution rather than of the extension: in a plain JupyterLab the file browser
+        // is the primary navigation surface and displacing it would be a regression. A
+        // distribution moves it with JupyterLab's own shell user-layout settings, keyed on
+        // this widget's id, rather than this extension hard-coding one host's preference.
         app.shell.add(datameshConnectWidget, 'left', { rank: 900 });
         app.commands.addCommand('datamesh-ui:open', {
             execute: (args) => {
@@ -134,7 +163,8 @@ export const oceanum_ai_extension = {
     id: '@oceanum/oceanumlab:ai-chat',
     autoStart: true,
     requires: [INotebookTracker, ISettingRegistry],
-    activate: (app, notebookTracker, settingRegistry) => {
+    optional: [IOceanumAuth],
+    activate: (app, notebookTracker, settingRegistry, auth) => {
         console.log('Oceanum AI chat extension is loaded');
         const SETTINGS_ID = '@oceanum/oceanumlab:datamesh-connect';
         settingRegistry
@@ -170,7 +200,7 @@ export const oceanum_ai_extension = {
                     // Gone: an answer's cells will go into a new notebook instead.
                     return null;
                 }
-            });
+            }, () => { var _a, _b; return (_b = (_a = auth === null || auth === void 0 ? void 0 : auth.urls) === null || _a === void 0 ? void 0 : _a.ai) !== null && _b !== void 0 ? _b : ''; });
             // Asked only when an answer has blocks to place: brings the
             // conversation's notebook to the front, opening it again if closed.
             const handoff = new KernelHandoff(() => pin.show(), () => readFrom);
@@ -290,4 +320,15 @@ export const oceanum_ai_extension = {
         });
     }
 };
-export default [datamesh_connect_extension, oceanum_ai_extension];
+/**
+ * The sign-in contract, exported so another extension can provide or consume it: a Lumino
+ * token is matched by object identity, so everyone has to import this one object, and
+ * JupyterLab shares `@oceanum/oceanumlab` between extensions as a singleton module.
+ */
+export * from './auth/tokens';
+export default [
+    deviceAuthPlugin,
+    sharePlugin,
+    datamesh_connect_extension,
+    oceanum_ai_extension
+];

package/lib/share/client.d.ts

@@ -0,0 +1,84 @@
+import { ISpecBody, ISpecPatch, ISpecRecord, ISpecSummary } from './notebook';
+export type ErrorKind = 'signed-out' | 'expired' | 'forbidden' | 'not-found' | 'too-large' | 'network' | 'invalid' | 'unsupported' | 'server';
+/** A spec store failure with a message that is safe to show to the user. */
+export declare class SpecStoreError extends Error {
+    readonly kind: ErrorKind;
+    readonly status: number | null;
+    constructor(kind: ErrorKind, status?: number | null);
+}
+/** Map a failed HTTP status to an error. */
+export declare function errorForStatus(status: number): SpecStoreError;
+export type SharePermission = 'read' | 'write';
+/** A permission grant, as accepted by `POST /specs/notebook/{id}/permissions`. */
+export type PermissionGrant = {
+    type: 'user';
+    entity: string;
+    permission: SharePermission;
+} | {
+    type: 'public';
+    entity: '';
+    permission: 'read';
+};
+/**
+ * What the share dialog asks for: add grants, or remove one (e.g. stop public access).
+ *
+ * Granting carries a list because the dialog shares with several people at once, while
+ * the spec store takes one grant per request. `invalid` carries back anything typed that
+ * is not a shareable address, so the caller can name it rather than failing with
+ * "invalid email".
+ */
+export type ShareChoice = {
+    action: 'grant';
+    grants: PermissionGrant[];
+    invalid: string[];
+} | {
+    action: 'revoke';
+    grant: PermissionGrant;
+};
+export interface ISpecStoreClientOptions {
+    /** Spec store base URL, e.g. `https://specs.oceanum.io`. */
+    specsUrl: string;
+    /** Returns a current access token or `null`. Called for every request. */
+    getAccessToken: () => Promise<string | null>;
+    fetch?: typeof fetch;
+}
+/** Client for the `notebook` spec type of the Oceanum spec store. */
+export declare class SpecStoreClient {
+    constructor(options: ISpecStoreClientOptions);
+    /** Every notebook the user may read, including public ones. */
+    list(): Promise<ISpecSummary[]>;
+    /** Read a record, anonymously when signed out. */
+    get(id: string): Promise<ISpecRecord>;
+    /** Create a record. The server mints the id: use the returned record's. */
+    create(body: ISpecBody): Promise<ISpecRecord>;
+    /** Replace a record's name, description and notebook. */
+    update(id: string, body: ISpecBody): Promise<ISpecRecord>;
+    /**
+     * Change some of a record's fields and leave the rest as they are. Needs the same
+     * write access as `update`, which the store enforces a patch as.
+     */
+    patch(id: string, changes: ISpecPatch): Promise<ISpecRecord>;
+    /**
+     * Give a record a new name, without sending the notebook back with it.
+     *
+     * Falls back to reading the record and putting it back where the store has no PATCH
+     * (production had none when this was written). That fallback races another writer's
+     * change to the notebook, which is the whole reason to prefer a patch.
+     */
+    rename(id: string, name: string): Promise<ISpecRecord>;
+    /** Delete a record (requires admin access to it). */
+    remove(id: string): Promise<void>;
+    /** Grant a permission on a record (requires admin access to it). */
+    addPermission(id: string, grant: PermissionGrant): Promise<void>;
+    /**
+     * Remove a permission (requires admin access). The server matches the exact grant and
+     * answers 404 when there is no such permission.
+     */
+    removePermission(id: string, grant: PermissionGrant): Promise<void>;
+    private _url;
+    private _record;
+    private _request;
+    private readonly _base;
+    private readonly _getAccessToken;
+    private readonly _fetch;
+}