@oceanum/oceanumlab 4.7.1 → 4.7.2

package/src/__tests__/StoredNotebooks.spec.tsx

@@ -0,0 +1,157 @@
+import { ReactWidget } from '@jupyterlab/ui-components';
+import { Signal } from '@lumino/signaling';
+import { Widget } from '@lumino/widgets';
+import React from 'react';
+
+import { IOceanumAuth, IOceanumUser } from '../auth/tokens';
+import { notebooksChanged } from '../share/events';
+import { StoredNotebooks } from '../StoredNotebooks';
+
+/** A signed-out auth that records whether sign-in was asked for. */
+function signedOut(): IOceanumAuth & { signIns: number } {
+  const auth = {
+    signIns: 0,
+    environment: null as IOceanumAuth['environment'],
+    urls: { specs: 'https://specs.example.com' },
+    ready: Promise.resolve(),
+    user: null as IOceanumUser | null,
+    userChanged: new Signal<IOceanumAuth, IOceanumUser | null>(
+      {} as IOceanumAuth
+    ),
+    tokenChanged: new Signal<IOceanumAuth, string | null>({} as IOceanumAuth),
+    signIn: async (): Promise<void> => {
+      auth.signIns += 1;
+    },
+    signOut: async (): Promise<void> => undefined,
+    getAccessToken: async (): Promise<string | null> => null
+  };
+  return auth as unknown as IOceanumAuth & { signIns: number };
+}
+
+class Harness extends ReactWidget {
+  constructor(
+    private readonly _auth: IOceanumAuth,
+    private readonly _onSignIn?: () => void
+  ) {
+    super();
+  }
+
+  render(): React.ReactElement {
+    return <StoredNotebooks auth={this._auth} onSignIn={this._onSignIn} />;
+  }
+}
+
+async function mount(
+  auth: IOceanumAuth,
+  onSignIn?: () => void
+): Promise<Harness> {
+  const widget = new Harness(auth, onSignIn);
+  Widget.attach(widget, document.body);
+  const deadline = Date.now() + 4000;
+  for (;;) {
+    if (widget.node.querySelector('.oceanum-text-empty')) {
+      return widget;
+    }
+    if (Date.now() > deadline) {
+      throw new Error('StoredNotebooks rendered nothing within 4s');
+    }
+    await new Promise(resolve => setTimeout(resolve, 25));
+  }
+}
+
+describe('the Notebooks tab while signed in', () => {
+  const ID = '6f1c1a52-4b8e-4c0f-9a57-1d2e3f4a5b6c';
+
+  it('lists again when a record is created, renamed or deleted', async () => {
+    const auth = signedOut();
+    (auth as { user: IOceanumUser | null }).user = {
+      sub: 'auth0|1',
+      email: 'me@example.com',
+      name: null,
+      activeOrg: null,
+      colorScheme: null
+    };
+    auth.getAccessToken = async () => 'tok';
+    const fetches: string[] = [];
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      fetches.push(String(input));
+      return {
+        ok: true,
+        status: 200,
+        json: async () => [
+          {
+            id: ID,
+            name: 'Waves',
+            description: null as string | null,
+            modified: '2026-09-12T10:00:00',
+            creator: 'me@example.com'
+          }
+        ]
+      } as unknown as Response;
+    }) as typeof fetch;
+    try {
+      const widget = new Harness(auth);
+      Widget.attach(widget, document.body);
+      const until = async (test: () => boolean): Promise<void> => {
+        const deadline = Date.now() + 4000;
+        while (!test()) {
+          if (Date.now() > deadline) {
+            throw new Error('timed out');
+          }
+          await new Promise(resolve => setTimeout(resolve, 25));
+        }
+      };
+      await until(() => !!widget.node.querySelector('.oceanum-notebooks-item'));
+      expect(fetches).toHaveLength(1);
+      const row = widget.node.querySelector('.oceanum-notebooks-item')!;
+      expect(row.getAttribute('data-spec-id')).toBe(ID);
+
+      notebooksChanged.emit();
+
+      await until(() => fetches.length === 2);
+      widget.dispose();
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
+
+describe('the Notebooks tab while signed out', () => {
+  it('links "Sign in" to starting a sign-in', async () => {
+    const auth = signedOut();
+    const widget = await mount(auth);
+
+    expect(widget.node.textContent).toContain(
+      'Sign in to Oceanum.io to see your notebooks.'
+    );
+    const link = widget.node.querySelector<HTMLAnchorElement>(
+      '.oceanum-text-empty a'
+    );
+    expect(link?.textContent).toBe('Sign in');
+
+    link!.click();
+    expect(auth.signIns).toBe(1);
+
+    widget.dispose();
+  });
+
+  it("prefers the host's own way of signing in when given one", async () => {
+    // On a JupyterLab server that is the device sign-in command, which shows the
+    // code; the auth's signIn() alone would start the flow with nothing to look at.
+    const auth = signedOut();
+    let hostSignIns = 0;
+    const widget = await mount(auth, () => {
+      hostSignIns += 1;
+    });
+
+    widget.node
+      .querySelector<HTMLAnchorElement>('.oceanum-text-empty a')!
+      .click();
+
+    expect(hostSignIns).toBe(1);
+    expect(auth.signIns).toBe(0);
+
+    widget.dispose();
+  });
+});

package/src/__tests__/oceanumOnly.spec.ts

@@ -0,0 +1,193 @@
+import type { INotebookTracker, NotebookPanel } from '@jupyterlab/notebook';
+import { CommandRegistry } from '@lumino/commands';
+import { Signal } from '@lumino/signaling';
+import { Menu, Panel, Widget } from '@lumino/widgets';
+
+import {
+  FILE_BROWSER_ID,
+  hideFileBrowser,
+  LOCAL_FILE_COMMANDS,
+  pruneBeforeEachOpen,
+  pruneFileMenu,
+  routeSaves
+} from '../share/oceanumOnly';
+
+describe('hideFileBrowser', () => {
+  it('closes the file browser without disposing it, and leaves the rest', () => {
+    const left = new Panel();
+    const browser = new Widget();
+    browser.id = FILE_BROWSER_ID;
+    const running = new Widget();
+    running.id = 'jp-running-sessions';
+    left.addWidget(browser);
+    left.addWidget(running);
+
+    expect(hideFileBrowser({ widgets: () => left.widgets })).toBe(true);
+
+    expect(left.widgets).toEqual([running]);
+    // Other extensions still hold it through IDefaultFileBrowser.
+    expect(browser.isDisposed).toBe(false);
+  });
+
+  it('reports when there is none to hide', () => {
+    const left = new Panel();
+    expect(hideFileBrowser({ widgets: () => left.widgets })).toBe(false);
+  });
+});
+
+function fileMenu(commands: string[]): {
+  menu: Menu;
+  registry: CommandRegistry;
+} {
+  const registry = new CommandRegistry();
+  const menu = new Menu({ commands: registry });
+  for (const command of commands) {
+    if (command === '-') {
+      menu.addItem({ type: 'separator' });
+      continue;
+    }
+    registry.addCommand(command, { execute: () => undefined, label: command });
+    menu.addItem({ command });
+  }
+  return { menu, registry };
+}
+
+const menuCommands = (menu: Menu): string[] =>
+  menu.items.map(item => (item.type === 'separator' ? '-' : item.command));
+
+describe('pruneFileMenu', () => {
+  it('drops the local-file entries and keeps Save, Rename and everything else', () => {
+    const { menu } = fileMenu([
+      'filebrowser:open-path',
+      'filebrowser:open-url',
+      '-',
+      'docmanager:save',
+      'docmanager:save-as',
+      'docmanager:save-all',
+      '-',
+      'docmanager:reload',
+      'docmanager:restore-checkpoint',
+      'docmanager:rename',
+      'docmanager:duplicate',
+      '-',
+      'docmanager:download',
+      'oceanum-share:save'
+    ]);
+
+    expect(pruneFileMenu(menu)).toBe(7);
+
+    expect(menuCommands(menu)).toEqual([
+      '-',
+      'docmanager:save',
+      'docmanager:save-all',
+      '-',
+      'docmanager:rename',
+      '-',
+      'oceanum-share:save'
+    ]);
+    // Idempotent: nothing left to remove.
+    expect(pruneFileMenu(menu)).toBe(0);
+  });
+
+  it('drops the Open Recent submenu, which the document manager builds by hand', () => {
+    const { menu, registry } = fileMenu(['docmanager:save']);
+    registry.addCommand('docmanager:clear-recents', {
+      execute: () => undefined,
+      label: 'Clear Recent'
+    });
+    const recents = new Menu({ commands: registry });
+    recents.title.label = 'Open Recent';
+    recents.addItem({ command: 'docmanager:clear-recents' });
+    menu.addItem({ type: 'submenu', submenu: recents });
+    const other = new Menu({ commands: registry });
+    other.title.label = 'New';
+    menu.addItem({ type: 'submenu', submenu: other });
+
+    expect(pruneFileMenu(menu)).toBe(1);
+
+    expect(menu.items.map(item => item.type)).toEqual(['command', 'submenu']);
+    expect(menu.items[1].submenu?.title.label).toBe('New');
+  });
+
+  it('names every entry it prunes, so the list is reviewable', () => {
+    expect(LOCAL_FILE_COMMANDS).toEqual([
+      'filebrowser:open-path',
+      'filebrowser:open-url',
+      'docmanager:save-as',
+      'docmanager:reload',
+      'docmanager:restore-checkpoint',
+      'docmanager:duplicate',
+      'docmanager:download'
+    ]);
+  });
+});
+
+describe('pruneBeforeEachOpen', () => {
+  it('prunes entries that arrive after the first pass, each time the menu opens', () => {
+    const { menu, registry } = fileMenu(['docmanager:save']);
+    pruneBeforeEachOpen(menu);
+    // A plugin's settings schema loads late and adds its entry.
+    registry.addCommand('docmanager:save-as', {
+      execute: () => undefined,
+      label: 'Save As'
+    });
+    menu.addItem({ command: 'docmanager:save-as' });
+    expect(menuCommands(menu)).toEqual([
+      'docmanager:save',
+      'docmanager:save-as'
+    ]);
+
+    menu.open(0, 0);
+    try {
+      expect(menuCommands(menu)).toEqual(['docmanager:save']);
+    } finally {
+      menu.close();
+      menu.dispose();
+    }
+  });
+});
+
+/** Just enough of a notebook tracker and its panels to route saves. */
+function fakeTracker(): {
+  tracker: INotebookTracker;
+  add: () => { panel: NotebookPanel; saveState: Signal<unknown, string> };
+} {
+  const panels: NotebookPanel[] = [];
+  const widgetAdded = new Signal<INotebookTracker, NotebookPanel>(
+    {} as INotebookTracker
+  );
+  const tracker = {
+    forEach: (fn: (panel: NotebookPanel) => void) => panels.forEach(fn),
+    widgetAdded
+  } as unknown as INotebookTracker;
+  const add = () => {
+    const saveState = new Signal<unknown, string>({});
+    const panel = { context: { saveState } } as unknown as NotebookPanel;
+    panels.push(panel);
+    widgetAdded.emit(panel);
+    return { panel, saveState };
+  };
+  return { tracker, add };
+}
+
+describe('routeSaves', () => {
+  it('pushes after every completed save, of notebooks open now and later', () => {
+    const { tracker, add } = fakeTracker();
+    const first = add();
+    const pushed: NotebookPanel[] = [];
+    routeSaves(tracker, async panel => {
+      pushed.push(panel);
+    });
+
+    first.saveState.emit('started');
+    expect(pushed).toEqual([]);
+    first.saveState.emit('completed');
+    expect(pushed).toEqual([first.panel]);
+
+    const second = add();
+    second.saveState.emit('completed');
+    second.saveState.emit('failed');
+    first.saveState.emit('completed');
+    expect(pushed).toEqual([first.panel, second.panel, first.panel]);
+  });
+});

package/src/__tests__/shareClient.spec.ts

@@ -0,0 +1,314 @@
+import type { INotebookContent } from '@jupyterlab/nbformat';
+
+import { SpecStoreClient, SpecStoreError } from '../share/client';
+import type { ISpecBody } from '../share/notebook';
+
+const ID = '6f1c1a52-4b8e-4c0f-9a57-1d2e3f4a5b6c';
+const SERVER_ID = '0b7d9f2e-1111-4a2b-8c3d-9e8f7a6b5c4d';
+
+const notebook: INotebookContent = {
+  nbformat: 4,
+  nbformat_minor: 5,
+  metadata: {},
+  cells: []
+};
+
+function record(id: string = ID) {
+  return {
+    id,
+    name: 'Waves',
+    description: null as string | null,
+    modified: '2026-09-12T10:00:00',
+    creator: 'a@example.com',
+    spec: notebook
+  };
+}
+
+function json(data: unknown, status = 200): Response {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => data
+  } as unknown as Response;
+}
+
+function noContent(): Response {
+  return {
+    ok: true,
+    status: 204,
+    json: async () => {
+      throw new Error('no body');
+    }
+  } as unknown as Response;
+}
+
+function setup(
+  response: () => Response | Promise<Response>,
+  token: string | null = 'tok'
+) {
+  const fetch = jest.fn(
+    async (_input: RequestInfo | URL, _init?: RequestInit) => response()
+  );
+  const client = new SpecStoreClient({
+    specsUrl: 'https://specs.example.com/',
+    getAccessToken: async () => token,
+    fetch: fetch as unknown as typeof globalThis.fetch
+  });
+  const call = (i = 0) => {
+    const [url, init] = fetch.mock.calls[i];
+    return {
+      url: String(url),
+      method: init?.method,
+      headers: (init?.headers ?? {}) as Record<string, string>,
+      body: init?.body === undefined ? undefined : JSON.parse(String(init.body))
+    };
+  };
+  return { client, fetch, call };
+}
+
+const body: ISpecBody = { name: 'Waves', description: null, spec: notebook };
+
+describe('SpecStoreClient', () => {
+  it('lists with the bearer token', async () => {
+    const { client, call } = setup(() => json([record()]));
+    const items = await client.list();
+    expect(items).toHaveLength(1);
+    expect(call()).toEqual({
+      url: 'https://specs.example.com/specs/notebook',
+      method: 'GET',
+      headers: { Authorization: 'Bearer tok' },
+      body: undefined
+    });
+  });
+
+  it('requires sign-in to list, without calling the server', async () => {
+    const { client, fetch } = setup(() => json([]), null);
+    await expect(client.list()).rejects.toMatchObject({ kind: 'signed-out' });
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it('gets a record anonymously when signed out', async () => {
+    const { client, call } = setup(() => json(record()), null);
+    const result = await client.get(ID);
+    expect(result.id).toBe(ID);
+    expect(call().url).toBe(`https://specs.example.com/specs/notebook/${ID}`);
+    expect(call().headers).toEqual({});
+  });
+
+  it('refuses ids that are not UUIDs before building a URL', async () => {
+    const { client, fetch } = setup(() => json(record()));
+    await expect(client.get('../eidos')).rejects.toMatchObject({
+      kind: 'invalid'
+    });
+    await expect(client.update('x/permissions', body)).rejects.toBeInstanceOf(
+      SpecStoreError
+    );
+    await expect(client.remove('x')).rejects.toMatchObject({
+      kind: 'invalid'
+    });
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it('creates with a JSON body, never sends an id, and uses the server id', async () => {
+    const { client, call } = setup(() => json(record(SERVER_ID)));
+    const withId = { ...body, id: ID } as ISpecBody;
+    const result = await client.create(withId);
+    expect(result.id).toBe(SERVER_ID);
+    expect(call()).toEqual({
+      url: 'https://specs.example.com/specs/notebook',
+      method: 'POST',
+      headers: {
+        Authorization: 'Bearer tok',
+        'Content-Type': 'application/json'
+      },
+      body: { name: 'Waves', description: null, spec: notebook }
+    });
+  });
+
+  it('updates with PUT to the record URL', async () => {
+    const { client, call } = setup(() => json(record()));
+    await client.update(ID, body);
+    expect(call().method).toBe('PUT');
+    expect(call().url).toBe(`https://specs.example.com/specs/notebook/${ID}`);
+    expect(call().body).toEqual(body);
+  });
+
+  it('patches only the fields it is given', async () => {
+    const { client, call } = setup(() => json(record()));
+    await client.patch(ID, { name: 'Renamed' });
+    expect(call()).toEqual({
+      url: `https://specs.example.com/specs/notebook/${ID}`,
+      method: 'PATCH',
+      headers: {
+        Authorization: 'Bearer tok',
+        'Content-Type': 'application/json'
+      },
+      body: { name: 'Renamed' }
+    });
+  });
+
+  it('refuses a patch that carries nothing, without calling the server', async () => {
+    // The store answers an empty patch with 400, and there is nothing to send.
+    const { client, fetch } = setup(() => json(record()));
+    await expect(client.patch(ID, {})).rejects.toMatchObject({
+      kind: 'invalid'
+    });
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it('renames with a single patch, leaving the notebook alone', async () => {
+    const { client, call, fetch } = setup(() => json(record()));
+    await client.rename(ID, 'Renamed');
+    expect(fetch).toHaveBeenCalledTimes(1);
+    expect(call().method).toBe('PATCH');
+    expect(call().body).toEqual({ name: 'Renamed' });
+  });
+
+  it('renames by reading and putting back where the store has no PATCH', async () => {
+    // Production served no PATCH when this was written; a store without it answers 405.
+    const responses: Record<string, () => Response> = {
+      PATCH: () => json('Method Not Allowed', 405),
+      GET: () => json({ ...record(), description: 'Wave stats' }),
+      PUT: () => json(record())
+    };
+    const fetch = jest.fn(
+      async (_input: RequestInfo | URL, init?: RequestInit) =>
+        responses[init?.method ?? 'GET']()
+    );
+    const client = new SpecStoreClient({
+      specsUrl: 'https://specs.example.com',
+      getAccessToken: async () => 'tok',
+      fetch: fetch as unknown as typeof globalThis.fetch
+    });
+
+    await client.rename(ID, 'Renamed');
+
+    expect(fetch.mock.calls.map(([, init]) => init?.method)).toEqual([
+      'PATCH',
+      'GET',
+      'PUT'
+    ]);
+    const put = JSON.parse(String(fetch.mock.calls[2][1]?.body));
+    // The name changes; everything else goes back as it was read.
+    expect(put).toEqual({
+      name: 'Renamed',
+      description: 'Wave stats',
+      spec: notebook
+    });
+  });
+
+  it('does not fall back for a failure that is not a missing method', async () => {
+    const { client, fetch } = setup(() => json('Forbidden', 403));
+    await expect(client.rename(ID, 'Renamed')).rejects.toMatchObject({
+      kind: 'forbidden'
+    });
+    expect(fetch).toHaveBeenCalledTimes(1);
+  });
+
+  it('deletes with DELETE to the record URL, and needs sign-in', async () => {
+    const { client, call } = setup(() => noContent());
+    await client.remove(ID);
+    expect(call().method).toBe('DELETE');
+    expect(call().url).toBe(`https://specs.example.com/specs/notebook/${ID}`);
+    expect(call().body).toBeUndefined();
+
+    const signedOut = setup(() => noContent(), null);
+    await expect(signedOut.client.remove(ID)).rejects.toMatchObject({
+      kind: 'signed-out'
+    });
+    expect(signedOut.fetch).not.toHaveBeenCalled();
+  });
+
+  it('posts permission grants', async () => {
+    const { client, call } = setup(() => json([]));
+    await client.addPermission(ID, {
+      type: 'user',
+      entity: 'b@example.com',
+      permission: 'write'
+    });
+    await client.addPermission(ID, {
+      type: 'public',
+      entity: '',
+      permission: 'read'
+    });
+    expect(call(0).url).toBe(
+      `https://specs.example.com/specs/notebook/${ID}/permissions`
+    );
+    expect(call(0).method).toBe('POST');
+    expect(call(0).body).toEqual({
+      type: 'user',
+      entity: 'b@example.com',
+      permission: 'write'
+    });
+    expect(call(1).body).toEqual({
+      type: 'public',
+      entity: '',
+      permission: 'read'
+    });
+  });
+
+  it('deletes a permission by repeating the exact grant', async () => {
+    const { client, call } = setup(() => json([]));
+    await client.removePermission(ID, {
+      type: 'public',
+      entity: '',
+      permission: 'read'
+    });
+    expect(call(0).url).toBe(
+      `https://specs.example.com/specs/notebook/${ID}/permissions`
+    );
+    expect(call(0).method).toBe('DELETE');
+    expect(call(0).body).toEqual({
+      type: 'public',
+      entity: '',
+      permission: 'read'
+    });
+  });
+
+  it.each([
+    [400, 'expired', 'Your Oceanum session has expired, sign in again.'],
+    [403, 'forbidden', /another organisation/],
+    [404, 'not-found', /no longer exists/],
+    [405, 'unsupported', /does not offer that operation/],
+    [413, 'too-large', /too large/],
+    [500, 'server', 'Oceanum.io returned an error (HTTP 500).']
+  ])('maps HTTP %i to %s', async (status, kind, message) => {
+    const { client } = setup(() => json('Forbidden', status as number));
+    const error = await client.get(ID).catch(e => e);
+    expect(error).toBeInstanceOf(SpecStoreError);
+    expect(error.kind).toBe(kind);
+    expect(error.status).toBe(status);
+    expect(error.message).toMatch(message as string | RegExp);
+  });
+
+  it('maps a network failure', async () => {
+    const { client } = setup(() =>
+      Promise.reject(new TypeError('Failed to fetch'))
+    );
+    await expect(client.create(body)).rejects.toMatchObject({
+      kind: 'network',
+      message: expect.stringMatching(/Could not reach Oceanum.io/)
+    });
+  });
+
+  it('rejects malformed responses', async () => {
+    const { client } = setup(() => json({ id: 'nope', name: 1 }));
+    await expect(client.get(ID)).rejects.toMatchObject({ kind: 'invalid' });
+    const list = setup(() => json({ detail: 'x' }));
+    await expect(list.client.list()).rejects.toMatchObject({
+      kind: 'invalid'
+    });
+  });
+
+  it('asks for a fresh token on every request', async () => {
+    const getAccessToken = jest.fn(async () => 'tok');
+    const client = new SpecStoreClient({
+      specsUrl: 'https://specs.example.com',
+      getAccessToken,
+      fetch: async () => json(record())
+    });
+    await client.get(ID);
+    await client.get(ID);
+    expect(getAccessToken).toHaveBeenCalledTimes(2);
+  });
+});