@oceanum/oceanumlab 4.7.1 → 4.7.2

package/lib/DatameshWidget.js

@@ -9,9 +9,10 @@ import { Signal } from '@lumino/signaling';
 import React from 'react';
 import { marked } from 'marked';
 import { DatasourceItem } from './DatasourceItem';
+import { startSignIn } from './auth/startSignIn';
 import { StoredNotebooks } from './StoredNotebooks';
 import { Tabs } from './Tabs';
-import { SIGN_IN_COMMAND, aiBackendUrl, aiCredentialSource, canSignIn, pastedToken, resolveAiCredential, signInToken } from './aiBackend';
+import { SIGN_IN_COMMAND, aiBackendUrl, aiCredentialSource, canSignIn, isSignedIn, pastedToken, resolveAiCredential, signInToken } from './aiBackend';
 import { isDatameshUiMessage } from './datameshUiUrl';
 import { describeProgress, onProgress } from './progress';
 // Configure marked for safe rendering
@@ -292,6 +293,7 @@ function readAiAccess(commands, settings) {
         source: aiCredentialSource(datameshToken, commands),
         pasted: pastedToken(datameshToken),
         canSignIn: canSignIn(commands),
+        signedIn: isSignedIn(commands),
         backend: aiBackendUrl(settings.aiBackendUrl())
     };
 }
@@ -609,7 +611,7 @@ function AIChatPanel({ commands, settings }) {
  * credential to work with — otherwise it would open on the same nothing the panel
  * rendered before there were tabs, except now with a label promising otherwise.
  */
-function PanelTabs({ auth, commands, settings, renderDatamesh, selected, onSelect }) {
+function PanelTabs({ auth, commands, settings, renderDatamesh, openStoredNotebook, selected, onSelect }) {
     const access = useAiAccess(commands, settings);
     const tabs = [
         {
@@ -618,11 +620,18 @@ function PanelTabs({ auth, commands, settings, renderDatamesh, selected, onSelec
             render: () => 
             // An auth with no environment is a provider that has nothing to sign in to (the
             // server has sign-in turned off). Asking the user to sign in would be a dead end.
-            (auth === null || auth === void 0 ? void 0 : auth.environment) ? (React.createElement(StoredNotebooks, { auth: auth })) : (React.createElement("div", { className: "oceanum-text-empty" }, "Oceanum.io sign-in is not configured for this host."))
+            (auth === null || auth === void 0 ? void 0 : auth.environment) ? (React.createElement(StoredNotebooks, { auth: auth, onOpen: openStoredNotebook && (item => openStoredNotebook(item.id)), onSignIn: () => {
+                    startSignIn(commands, auth).catch(error => {
+                        console.warn('Oceanum.io sign-in could not start.', error);
+                    });
+                } })) : (React.createElement("div", { className: "oceanum-text-empty" }, "Oceanum.io sign-in is not configured for this host."))
         },
         { id: 'datamesh', label: 'Datamesh', render: renderDatamesh }
     ];
-    if (access.source) {
+    // Signed in, not merely holding a credential: a Datamesh token pasted into the
+    // settings would reach the backend, but the tab stays out of the way until someone
+    // has signed in to Oceanum.io.
+    if (access.signedIn) {
         tabs.push({
             id: 'ai',
             label: 'Oceanum AI',
@@ -684,7 +693,7 @@ export class DatameshConnectWidget extends ReactWidget {
                 React.createElement("span", { className: "oceanum-sidebar-title" }, "Oceanum.io")),
             React.createElement(UseSignal, { signal: this.tabChanged, initialArgs: this.selectedTab }, () => {
                 var _a;
-                return (React.createElement(PanelTabs, { auth: (_a = this.props.auth) !== null && _a !== void 0 ? _a : null, commands: this.props.commands, settings: this.props, renderDatamesh: () => this.renderDatamesh(), selected: this.selectedTab, onSelect: id => this.selectTab(id) }));
+                return (React.createElement(PanelTabs, { auth: (_a = this.props.auth) !== null && _a !== void 0 ? _a : null, commands: this.props.commands, settings: this.props, renderDatamesh: () => this.renderDatamesh(), openStoredNotebook: this.props.openStoredNotebook, selected: this.selectedTab, onSelect: id => this.selectTab(id) }));
             })));
     }
     /**

package/lib/StoredNotebooks.d.ts

@@ -1,16 +1,20 @@
 import * as React from 'react';
 import { IOceanumAuth } from './auth/tokens';
-import { ISpecSummary } from './specStore';
+import { ISpecSummary } from './share/notebook';
 export interface IStoredNotebooksProps {
     auth: IOceanumAuth;
     /**
-     * Open a stored notebook, when this host can. Undefined where nothing has registered
-     * a way to open one — today that is native JupyterLab, which has no spec store drive
-     * until OCE-182. The list then reads rather than offering an action that does nothing.
+     * Open a stored notebook. Undefined where nothing has registered a way to open one;
+     * the list then reads rather than offering a click that does nothing.
      */
     onOpen?: (item: ISpecSummary) => void;
+    /**
+     * Start signing in the way this host shows it; without it the auth's own `signIn()`
+     * is used, which on a JupyterLab server shows no code dialog.
+     */
+    onSignIn?: () => void;
 }
 /**
  * The notebooks this user has stored on Oceanum.io, theirs and those shared with them.
  */
-export declare function StoredNotebooks({ auth, onOpen }: IStoredNotebooksProps): React.ReactElement;
+export declare function StoredNotebooks({ auth, onOpen, onSignIn }: IStoredNotebooksProps): React.ReactElement;

package/lib/StoredNotebooks.js

@@ -1,30 +1,45 @@
 import * as React from 'react';
-import { listNotebooks, partitionNotebooks } from './specStore';
+import { SpecStoreClient } from './share/client';
+import { notebooksChanged } from './share/events';
+import { partitionSummaries } from './share/notebook';
+import { SPEC_ID_ATTRIBUTE } from './share/plugin';
 function Section({ title, items, empty, onOpen }) {
+    // Each row carries its record id so the share plugin's context menu (Open, Rename,
+    // Share, Delete) can tell which one was clicked.
+    const rowAttributes = (item) => {
+        var _a;
+        return ({
+            [SPEC_ID_ATTRIBUTE]: item.id,
+            title: (_a = item.description) !== null && _a !== void 0 ? _a : undefined
+        });
+    };
     return (React.createElement("div", { className: "oceanum-notebooks-section" },
         React.createElement("div", { className: "oceanum-notebooks-heading" },
             title,
             React.createElement("span", { className: "oceanum-notebooks-count" }, items.length)),
-        items.length === 0 ? (React.createElement("div", { className: "oceanum-text-empty" }, empty)) : (React.createElement("ul", { className: "oceanum-notebooks-list" }, items.map(item => {
-            var _a, _b;
-            return (React.createElement("li", { key: item.id }, onOpen ? (React.createElement("button", { type: "button", className: "oceanum-notebooks-item", onClick: () => onOpen(item), title: (_a = item.description) !== null && _a !== void 0 ? _a : undefined },
-                React.createElement("span", { className: "oceanum-notebooks-name" }, item.name || 'Untitled'))) : (React.createElement("div", { className: "oceanum-notebooks-item oceanum-notebooks-item-static", title: (_b = item.description) !== null && _b !== void 0 ? _b : undefined },
-                React.createElement("span", { className: "oceanum-notebooks-name" }, item.name || 'Untitled')))));
-        })))));
+        items.length === 0 ? (React.createElement("div", { className: "oceanum-text-empty" }, empty)) : (React.createElement("ul", { className: "oceanum-notebooks-list" }, items.map(item => (React.createElement("li", { key: item.id }, onOpen ? (React.createElement("button", { type: "button", className: "oceanum-notebooks-item", onClick: () => onOpen(item), ...rowAttributes(item) },
+            React.createElement("span", { className: "oceanum-notebooks-name" }, item.name || 'Untitled'))) : (React.createElement("div", { className: "oceanum-notebooks-item oceanum-notebooks-item-static", ...rowAttributes(item) },
+            React.createElement("span", { className: "oceanum-notebooks-name" }, item.name || 'Untitled'))))))))));
 }
 /**
  * The notebooks this user has stored on Oceanum.io, theirs and those shared with them.
  */
-export function StoredNotebooks({ auth, onOpen }) {
+export function StoredNotebooks({ auth, onOpen, onSignIn }) {
     const [load, setLoad] = React.useState({ state: 'loading' });
     const [user, setUser] = React.useState(auth.user);
+    // Bumped whenever the store changes, so the list is fetched again.
+    const [version, setVersion] = React.useState(0);
     // Reload whenever the signed-in user changes, so signing in or out does not leave a
-    // stale list from the previous session on screen.
+    // stale list from the previous session on screen; and whenever this extension has
+    // created, renamed or deleted a record.
     React.useEffect(() => {
         const onUser = () => setUser(auth.user);
+        const onChanged = () => setVersion(v => v + 1);
         auth.userChanged.connect(onUser);
+        notebooksChanged.connect(onChanged);
         return () => {
             auth.userChanged.disconnect(onUser);
+            notebooksChanged.disconnect(onChanged);
         };
     }, [auth]);
     React.useEffect(() => {
@@ -38,15 +53,11 @@ export function StoredNotebooks({ auth, onOpen }) {
         setLoad({ state: 'loading' });
         void (async () => {
             try {
-                const token = await auth.getAccessToken();
-                if (cancelled) {
-                    return;
-                }
-                if (!token) {
-                    setLoad({ state: 'ready', items: [] });
-                    return;
-                }
-                const items = await listNotebooks(specs, token);
+                const client = new SpecStoreClient({
+                    specsUrl: specs,
+                    getAccessToken: () => auth.getAccessToken()
+                });
+                const items = await client.list();
                 if (!cancelled) {
                     setLoad({ state: 'ready', items });
                 }
@@ -65,9 +76,26 @@ export function StoredNotebooks({ auth, onOpen }) {
         return () => {
             cancelled = true;
         };
-    }, [auth, user]);
+    }, [auth, user, version]);
     if (!user) {
-        return (React.createElement("div", { className: "oceanum-text-empty" }, "Sign in to Oceanum.io to see your notebooks."));
+        const signIn = () => {
+            if (onSignIn) {
+                onSignIn();
+                return;
+            }
+            auth.signIn().catch(error => {
+                console.warn('Oceanum.io sign-in could not start.', error);
+            });
+        };
+        return (React.createElement("div", { className: "oceanum-text-empty" },
+            React.createElement("a", { role: "button", tabIndex: 0, onClick: signIn, onKeyDown: event => {
+                    if (event.key === 'Enter' || event.key === ' ') {
+                        event.preventDefault();
+                        signIn();
+                    }
+                } }, "Sign in"),
+            ' ',
+            "to Oceanum.io to see your notebooks."));
     }
     if (load.state === 'loading') {
         return React.createElement("div", { className: "oceanum-text-empty" }, "Loading\u2026");
@@ -77,7 +105,7 @@ export function StoredNotebooks({ auth, onOpen }) {
         // the account has no notebooks when the load simply failed.
         return React.createElement("div", { className: "oceanum-text-error" }, load.message);
     }
-    const { mine, shared } = partitionNotebooks(load.items, user.email);
+    const { mine, shared } = partitionSummaries(load.items, user.email);
     return (React.createElement("div", { className: "oceanum-notebooks" },
         React.createElement(Section, { title: "My notebooks", items: mine, empty: "You have not saved any notebooks yet.", onOpen: onOpen }),
         React.createElement(Section, { title: "Shared with me", items: shared, empty: "No notebooks have been shared with you.", onOpen: onOpen })));

package/lib/auth/serverAuth.js

@@ -81,6 +81,7 @@ export function readServerAuthOption(option, hostname) {
         clientId: config.clientId,
         oceanumDomain: typeof config.oceanumDomain === 'string' ? config.oceanumDomain : '',
         signInRedirect: false,
+        fileManagement: config.fileManagement === 'oceanum' ? 'oceanum' : 'local',
         urls
     };
 }

package/lib/auth/startSignIn.d.ts

@@ -0,0 +1,11 @@
+import type { CommandRegistry } from '@lumino/commands';
+import type { IOceanumAuth } from './tokens';
+/**
+ * Start signing in the way this host shows it.
+ *
+ * On a JupyterLab server the device sign-in command both starts the flow and shows the
+ * code dialog; `auth.signIn()` alone starts the flow and shows nothing, so the user is
+ * left with a "Signing in…" top bar and no code. notebook.oceanum.io disables that
+ * command and provides an auth whose `signIn()` opens the Oceanum sign-in itself.
+ */
+export declare function startSignIn(commands: CommandRegistry, auth: IOceanumAuth): Promise<void>;

package/lib/auth/startSignIn.js

@@ -0,0 +1,16 @@
+import { CommandIDs } from './accountWidget';
+/**
+ * Start signing in the way this host shows it.
+ *
+ * On a JupyterLab server the device sign-in command both starts the flow and shows the
+ * code dialog; `auth.signIn()` alone starts the flow and shows nothing, so the user is
+ * left with a "Signing in…" top bar and no code. notebook.oceanum.io disables that
+ * command and provides an auth whose `signIn()` opens the Oceanum sign-in itself.
+ */
+export async function startSignIn(commands, auth) {
+    if (commands.hasCommand(CommandIDs.signIn)) {
+        await commands.execute(CommandIDs.signIn);
+        return;
+    }
+    await auth.signIn();
+}

package/lib/auth/tokens.d.ts

@@ -24,6 +24,13 @@ export interface IOceanumEnvironment {
      * 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 {

package/lib/index.d.ts

@@ -19,5 +19,5 @@ export declare const oceanum_ai_extension: JupyterFrontEndPlugin<void>;
  * JupyterLab shares `@oceanum/oceanumlab` between extensions as a singleton module.
  */
 export * from './auth/tokens';
-declare const _default: (JupyterFrontEndPlugin<IOceanumAuth> | JupyterFrontEndPlugin<void>)[];
+declare const _default: (JupyterFrontEndPlugin<void> | JupyterFrontEndPlugin<IOceanumAuth>)[];
 export default _default;

package/lib/index.js

@@ -14,6 +14,7 @@ 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';
@@ -111,12 +112,12 @@ export const datamesh_connect_extension = {
             settingsChanged,
             commands: app.commands,
             getCurrentWidget,
-            auth
-            // No `openStoredNotebook`: nothing can open a spec store record by id yet.
-            // share-oceanum has `oceanum-share:open`, but it takes no arguments — it opens
-            // its own picker — so there is nothing to hand an id to. Opening arrives with
-            // the drive in OCE-182, where the contents API makes it the ordinary path.
-            // Until then the list reads rather than offering a click that does nothing.
+            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;
@@ -327,6 +328,7 @@ export const oceanum_ai_extension = {
 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;
+}

package/lib/share/client.js

@@ -0,0 +1,205 @@
+import { isSpecId } from './notebook';
+const MESSAGES = {
+    'signed-out': 'Sign in to Oceanum.io to continue.',
+    expired: 'Your Oceanum session has expired, sign in again.',
+    forbidden: 'You have no access to this notebook. It may not exist, or was created under another organisation.',
+    'not-found': 'This notebook no longer exists on Oceanum.io.',
+    'too-large': 'The notebook is too large for Oceanum.io (32 MiB limit).',
+    network: 'Could not reach Oceanum.io. Check your connection; very large notebooks can also fail this way.',
+    invalid: 'Oceanum.io returned an unexpected response.',
+    unsupported: 'This Oceanum.io service does not offer that operation yet.'
+};
+/** A spec store failure with a message that is safe to show to the user. */
+export class SpecStoreError extends Error {
+    constructor(kind, status = null) {
+        super(kind === 'server'
+            ? `Oceanum.io returned an error (HTTP ${status}).`
+            : MESSAGES[kind]);
+        this.kind = kind;
+        this.status = status;
+        this.name = 'SpecStoreError';
+    }
+}
+/** Map a failed HTTP status to an error. */
+export function errorForStatus(status) {
+    switch (status) {
+        // The spec store's authentication middleware answers a bad or expired token with 400.
+        case 400:
+            return new SpecStoreError('expired', status);
+        // Casbin answers 403 both for no access and for a record that does not exist.
+        case 403:
+            return new SpecStoreError('forbidden', status);
+        case 404:
+            return new SpecStoreError('not-found', status);
+        case 405:
+            // The route is there but not this method: a store from before it had PATCH.
+            return new SpecStoreError('unsupported', status);
+        case 413:
+            return new SpecStoreError('too-large', status);
+        default:
+            return new SpecStoreError('server', status);
+    }
+}
+function isSummary(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const v = value;
+    return (isSpecId(v.id) &&
+        typeof v.name === 'string' &&
+        typeof v.modified === 'string');
+}
+function isRecord(value) {
+    return isSummary(value) && 'spec' in value;
+}
+/** Client for the `notebook` spec type of the Oceanum spec store. */
+export class SpecStoreClient {
+    constructor(options) {
+        var _a;
+        this._base = `${options.specsUrl.replace(/\/+$/, '')}/specs/notebook`;
+        this._getAccessToken = options.getAccessToken;
+        this._fetch = (_a = options.fetch) !== null && _a !== void 0 ? _a : ((input, init) => fetch(input, init));
+    }
+    /** Every notebook the user may read, including public ones. */
+    async list() {
+        const data = await this._request('GET', this._base, { auth: 'required' });
+        if (!Array.isArray(data) || !data.every(isSummary)) {
+            throw new SpecStoreError('invalid');
+        }
+        return data;
+    }
+    /** Read a record, anonymously when signed out. */
+    async get(id) {
+        return this._record(await this._request('GET', this._url(id), { auth: 'optional' }));
+    }
+    /** Create a record. The server mints the id: use the returned record's. */
+    async create(body) {
+        return this._record(await this._request('POST', this._base, {
+            auth: 'required',
+            body: pick(body)
+        }));
+    }
+    /** Replace a record's name, description and notebook. */
+    async update(id, body) {
+        return this._record(await this._request('PUT', this._url(id), {
+            auth: 'required',
+            body: pick(body)
+        }));
+    }
+    /**
+     * 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.
+     */
+    async patch(id, changes) {
+        if (Object.keys(changes).length === 0) {
+            // The store answers an empty patch with 400; there is nothing to send anyway.
+            throw new SpecStoreError('invalid');
+        }
+        return this._record(await this._request('PATCH', this._url(id), {
+            auth: 'required',
+            body: changes
+        }));
+    }
+    /**
+     * 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.
+     */
+    async rename(id, name) {
+        try {
+            return await this.patch(id, { name });
+        }
+        catch (error) {
+            if (!(error instanceof SpecStoreError) || error.kind !== 'unsupported') {
+                throw error;
+            }
+            const record = await this.get(id);
+            return this.update(id, {
+                name,
+                description: record.description,
+                spec: record.spec
+            });
+        }
+    }
+    /** Delete a record (requires admin access to it). */
+    async remove(id) {
+        await this._request('DELETE', this._url(id), { auth: 'required' });
+    }
+    /** Grant a permission on a record (requires admin access to it). */
+    async addPermission(id, grant) {
+        await this._request('POST', `${this._url(id)}/permissions`, {
+            auth: 'required',
+            body: {
+                type: grant.type,
+                entity: grant.entity,
+                permission: grant.permission
+            }
+        });
+    }
+    /**
+     * Remove a permission (requires admin access). The server matches the exact grant and
+     * answers 404 when there is no such permission.
+     */
+    async removePermission(id, grant) {
+        await this._request('DELETE', `${this._url(id)}/permissions`, {
+            auth: 'required',
+            body: {
+                type: grant.type,
+                entity: grant.entity,
+                permission: grant.permission
+            }
+        });
+    }
+    _url(id) {
+        if (!isSpecId(id)) {
+            throw new SpecStoreError('invalid');
+        }
+        return `${this._base}/${id}`;
+    }
+    _record(data) {
+        if (!isRecord(data)) {
+            throw new SpecStoreError('invalid');
+        }
+        return data;
+    }
+    async _request(method, url, options) {
+        const token = await this._getAccessToken();
+        if (token === null && options.auth === 'required') {
+            throw new SpecStoreError('signed-out');
+        }
+        const headers = {};
+        if (token !== null) {
+            headers['Authorization'] = `Bearer ${token}`;
+        }
+        const init = { method, headers };
+        if (options.body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+            init.body = JSON.stringify(options.body);
+        }
+        let response;
+        try {
+            response = await this._fetch(url, init);
+        }
+        catch (_a) {
+            throw new SpecStoreError('network');
+        }
+        if (!response.ok) {
+            throw errorForStatus(response.status);
+        }
+        if (response.status === 204) {
+            return null;
+        }
+        try {
+            return await response.json();
+        }
+        catch (_b) {
+            throw new SpecStoreError('invalid');
+        }
+    }
+}
+/** Only the fields the server accepts; in particular never send an `id`. */
+function pick(body) {
+    return { name: body.name, description: body.description, spec: body.spec };
+}

package/lib/share/events.d.ts

@@ -0,0 +1,7 @@
+import { Signal } from '@lumino/signaling';
+/**
+ * Emits after this extension creates, renames or deletes a notebook record, so the
+ * Notebooks tab can list again. A plain module-level signal: the tab and the commands
+ * live in different plugins, and the change is the only thing they need to share.
+ */
+export declare const notebooksChanged: Signal<object, void>;

package/lib/share/events.js

@@ -0,0 +1,9 @@
+import { Signal } from '@lumino/signaling';
+/**
+ * Emits after this extension creates, renames or deletes a notebook record, so the
+ * Notebooks tab can list again. A plain module-level signal: the tab and the commands
+ * live in different plugins, and the change is the only thing they need to share.
+ */
+// The sender is a throwaway object, not null: Lumino keys its receivers by sender in a
+// WeakMap, which refuses null.
+export const notebooksChanged = new Signal({});