@cube-nl/dmp-sdk 1.0.0-rc.4 → 1.1.0-rc.2

package/dist/app.js

@@ -2,34 +2,171 @@ import { createOAuth, memoryTokenStore, } from './auth.js';
 import { createClient } from './client.js';
 import { DmpError } from './errors.js';
 import { PreviewStore } from './preview.js';
+import { schemaFromCapability } from './ui/schema.js';
+import { PREVIEW_USER_NAME } from './ui/texts.js';
+import { resolveTheme, setTheme } from './ui/theme.js';
+import { trialConfig } from './trial.js';
 import { MANIFEST_SDK, VERSION } from './version.js';
+import { mixedResource, readGaps, simulatedWrites, withGaps } from './wireframe.js';
 const CONFIG_FILE = './cube-app.config.json';
 const MOCK_FILE = './cube-mock.json';
 const MANIFEST_FILE = './cube-app.json';
-const PREVIEW_USER = { id: 'preview', name: 'Voorbeeldgebruiker', scopes: [] };
+const THEME_FILE = './cube-theme.json';
+const PREVIEW_USER = { id: 'preview', name: PREVIEW_USER_NAME, scopes: [] };
 let registeredMock = null;
+let registeredTheme = null;
+let pageSession = null;
+/** The session `ready()` connected with the defaults, while it is the page session. */
+let fallbackSession = null;
+/** A `ready()` waiting for the page to load before it connects with the defaults. */
+let waitingSession = null;
+/** Counts start-ups: only the newest may apply its theme, so a slower, replaced one cannot overwrite it. */
+let starts = 0;
 /**
  * Starts the app. Reads `./cube-app.config.json` next to the page: absent, the app runs in the
  * preview on mock data and makes no request to any DMP; present, it signs the end user in with
  * OAuth (authorization code + PKCE) and talks to the DMP's REST face. The app's code is the same.
  */
-async function connect(options = {}) {
+function connect(options = {}) {
+    const replacesFallback = pageSession !== null && pageSession === fallbackSession;
+    const generation = ++starts;
+    const session = start(options, () => generation === starts);
+    pageSession = session;
+    fallbackSession = null;
+    // A failed start is not the page session: a later ready() tries again.
+    session.then(() => {
+        // Blocks took the default session already: tell them to take the app's own.
+        if (replacesFallback && pageSession === session)
+            announceSessionChange();
+    }, () => {
+        if (pageSession === session) {
+            pageSession = null;
+        }
+    });
+    return session;
+}
+/**
+ * The session `connect()` made for this page, or one with the defaults when the app never connected. The default one
+ * starts only once the page has loaded (and one task later), so an app that awaits something before it calls
+ * `connect()` still gets there first and the page signs in once.
+ */
+function ready() {
+    if (pageSession !== null) {
+        return pageSession;
+    }
+    waitingSession ??= pageLoaded().then(() => {
+        waitingSession = null;
+        if (pageSession !== null) {
+            return pageSession;
+        }
+        const session = connect();
+        fallbackSession = session;
+        return session;
+    });
+    return waitingSession;
+}
+/** Resolves one task after the window's `load` (right away outside a page). */
+function pageLoaded() {
+    const page = globalThis;
+    return new Promise((resolve) => {
+        const later = () => {
+            setTimeout(resolve, 0);
+        };
+        const loaded = page.document === undefined || page.document.readyState === 'complete';
+        if (loaded || page.addEventListener === undefined) {
+            later();
+        }
+        else {
+            page.addEventListener('load', later, { once: true });
+        }
+    });
+}
+function announceSessionChange() {
+    const doc = globalThis.document;
+    if (doc === undefined) {
+        return;
+    }
+    const View = doc.defaultView?.CustomEvent ?? CustomEvent;
+    doc.dispatchEvent(new View('cube-session-change'));
+}
+async function start(options, isCurrent) {
     const doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
     const pageUrl = options.pageUrl ?? currentPage();
-    const config = await readJson(doFetch, resolve(CONFIG_FILE, pageUrl));
+    // A trial page never has cube-app.config.json and never signs in with OAuth: the DMP wrote the token into it.
+    const trial = trialConfig();
+    const [config, theme] = await Promise.all([
+        trial === null ? readJson(doFetch, resolve(CONFIG_FILE, pageUrl)) : null,
+        loadTheme(options, doFetch, pageUrl),
+    ]);
+    if (isCurrent()) {
+        setTheme(theme);
+    }
+    if (trial !== null) {
+        return trialSession(trial, options, doFetch, pageUrl);
+    }
     if (config === null) {
         return preview(options, doFetch, pageUrl);
     }
     return live(asConfig(config), options, doFetch, pageUrl);
 }
-async function preview(options, doFetch, pageUrl) {
-    const mock = options.mock ?? registeredMock ?? (await readJson(doFetch, resolve(MOCK_FILE, pageUrl))) ?? {};
+/** Never rejects: a broken theme file must not stop the app, it only costs the house style. */
+async function loadTheme(options, doFetch, pageUrl) {
+    try {
+        if (options.theme === false) {
+            return resolveTheme(null, pageUrl);
+        }
+        const given = options.theme ?? registeredTheme;
+        if (given !== null) {
+            return resolveTheme(given, pageUrl);
+        }
+        const file = await readJson(doFetch, resolve(THEME_FILE, pageUrl));
+        if (file !== null && (file.theme !== 1 || typeof file.source !== 'object' || file.source === null)) {
+            throw new TypeError('cube-theme.json is not a theme file.');
+        }
+        return resolveTheme(file, pageUrl);
+    }
+    catch (error) {
+        console.warn(`cube-theme.json could not be used, the neutral theme applies: ${String(error)}`);
+        return resolveTheme(null, pageUrl);
+    }
+}
+/** The mock data and the manifest, from the options, `CubeApp.mock()` or the files next to the page. */
+async function appFiles(options, doFetch, pageUrl) {
+    const mock = options.mock
+        ?? registeredMock
+        ?? (await readJson(doFetch, resolve(MOCK_FILE, pageUrl)))
+        ?? {};
     const manifest = options.manifest === false
         ? null
         : options.manifest ?? (await readJson(doFetch, resolve(MANIFEST_FILE, pageUrl)));
+    return [mock, manifest];
+}
+/** Only a wireframe has gaps: any other app marks nothing, whatever its manifest lists. */
+function marks(soort, manifest) {
+    const wireframe = soort === 'wireframe';
+    const gaps = wireframe ? readGaps(manifest?.ontbreekt) : [];
+    return {
+        soort: soort ?? null,
+        gaps,
+        simulatesWrites: wireframe,
+        isExample: (resource, field) => gaps.some((gap) => gap.resource === resource && (gap.veld === undefined || gap.veld === field)),
+    };
+}
+/** A wireframe answers every write in the browser: one simulating client per resource, kept as long as the session. */
+function writes(on, open) {
+    const clients = new Map();
+    const simulating = (name) => {
+        const client = clients.get(name) ?? simulatedWrites(open(name), name);
+        clients.set(name, client);
+        return client;
+    };
+    return (on ? simulating : open);
+}
+async function preview(options, doFetch, pageUrl) {
+    const [mock, manifest] = await appFiles(options, doFetch, pageUrl);
     let signedIn = true;
     // Signed out, the preview refuses as the API refuses a request without a token.
-    const store = new PreviewStore(mock, manifest, () => {
+    const guard = () => {
         if (!signedIn) {
             throw new DmpError(401, new Headers({ 'Content-Type': 'application/problem+json' }), {
                 type: 'https://docs.cube.nl/dmp-api/problems/token_invalid',
@@ -39,8 +176,14 @@ async function preview(options, doFetch, pageUrl) {
                 detail: 'Unauthenticated.',
             });
         }
-    });
+    };
+    const marked = marks(manifest?.soort, manifest);
+    const ceiling = new PreviewStore(mock, manifest, guard);
+    // As live: a resource the DMP does not have yet is not in `uses`, so its rows come without that ceiling.
+    const examples = new PreviewStore(mock, null, guard);
+    const store = (name) => (marked.isExample(name) ? examples : ceiling);
     return {
+        ...marked,
         mode: 'preview',
         signInError: null,
         user: () => (signedIn ? { ...PREVIEW_USER } : null),
@@ -50,7 +193,56 @@ async function preview(options, doFetch, pageUrl) {
         async signOut() {
             signedIn = false;
         },
-        resource: (name) => store.resource(name),
+        resource: writes(marked.simulatesWrites, (name) => {
+            const own = store(name);
+            const client = own.resource(name);
+            const known = own.describe(name)?.fields ?? [];
+            // A missing field the mock data does not hold either is invented, as live: naming it would be a 422.
+            const absent = marked.gaps.filter(({ resource, veld }) => resource === name && veld !== undefined && !known.some((field) => field.name === veld));
+            return absent.length > 0 ? mixedResource(client, absent, examples, examples.rows(name)) : client;
+        }),
+        schema: async (name) => withGaps(store(name).describe(name), marked.gaps),
+    };
+}
+/** A wireframe's marks and its mock data. Only a wireframe reads the mock: an ordinary app never fetches it. */
+async function wireframeParts(soort, options, doFetch, pageUrl) {
+    const [mock, manifest] = soort === 'wireframe' ? await appFiles(options, doFetch, pageUrl) : [{}, null];
+    // The manifest's ceiling is the live client's: a missing resource is not in it, so the store checks none.
+    return { marked: marks(soort, manifest), examples: new PreviewStore(mock) };
+}
+/** The session on the DMP, live or trial: a wireframe mixes in its gaps, everything else goes to the client. */
+function onDmp(connection, { marked, examples }) {
+    const { client } = connection;
+    let capabilities = null;
+    return {
+        ...marked,
+        mode: connection.mode,
+        get signInError() {
+            return connection.signInError();
+        },
+        user: connection.user,
+        signIn: connection.signIn,
+        signOut: connection.signOut,
+        resource: writes(marked.simulatesWrites, (name) => marked.isExample(name)
+            ? examples.resource(name)
+            : marked.gaps.some((gap) => gap.resource === name)
+                ? mixedResource(client.resources(name), marked.gaps, examples, examples.rows(name))
+                : client.resources(name)),
+        async schema(name) {
+            if (marked.isExample(name)) {
+                return withGaps(examples.describe(name), marked.gaps);
+            }
+            capabilities ??= client.capabilities();
+            try {
+                const found = (await capabilities).resources.find((resource) => resource.name === name);
+                return found === undefined ? null : withGaps(schemaFromCapability(found), marked.gaps);
+            }
+            catch (error) {
+                // A failed call (signed out, offline) must not stay cached for the whole session.
+                capabilities = null;
+                throw error;
+            }
+        },
     };
 }
 async function live(config, options, doFetch, pageUrl) {
@@ -70,6 +262,7 @@ async function live(config, options, doFetch, pageUrl) {
     });
     const client = createClient({ baseUrl: config.apiUrl ?? `${dmpUrl}/apps/api/v1`, auth: oauth, fetch: doFetch });
     let signInError = null;
+    const parts = await wireframeParts(config.soort, options, doFetch, pageUrl);
     tokens = await store.get();
     try {
         await oauth.handleCallback();
@@ -81,11 +274,10 @@ async function live(config, options, doFetch, pageUrl) {
     if (tokens === null && signInError === null && options.autoSignIn === true) {
         await oauth.signIn();
     }
-    return {
+    return onDmp({
         mode: 'live',
-        get signInError() {
-            return signInError;
-        },
+        client,
+        signInError: () => signInError,
         user: () => (tokens === null ? null : userFrom(tokens)),
         async signIn() {
             signInError = null;
@@ -94,9 +286,44 @@ async function live(config, options, doFetch, pageUrl) {
         async signOut() {
             await oauth.signOut();
         },
-        resource: (name) => client.resources(name),
+    }, parts);
+}
+/**
+ * A trial reads only. A write never leaves the page (the browser would block it at the CORS preflight and the app would
+ * see a TypeError): it answers the 403 the DMP would, so it surfaces as a DmpError like any refusal.
+ */
+function readOnly(doFetch) {
+    return async (input, init) => {
+        const method = (init?.method ?? 'GET').toUpperCase();
+        if (method === 'GET' || method === 'HEAD') {
+            return doFetch(input, init);
+        }
+        return new Response(JSON.stringify({ status: 403, code: 'insufficient_scope' }), {
+            status: 403,
+            headers: { 'Content-Type': 'application/problem+json' },
+        });
     };
 }
+/** The live session with the injected token instead of OAuth: no discovery, no callback, no storage. */
+async function trialSession(config, options, doFetch, pageUrl) {
+    let token = config.token;
+    // Read on every request: once signed out no token goes out, so the DMP answers 401.
+    const client = createClient({ baseUrl: config.apiUrl, auth: () => token, fetch: readOnly(doFetch) });
+    const parts = await wireframeParts(config.soort ?? undefined, options, doFetch, pageUrl);
+    return onDmp({
+        mode: 'trial',
+        client,
+        signInError: () => null,
+        user: () => (token === null ? null : { id: config.userId, name: null, scopes: ['api:read'] }),
+        // The DMP writes a token into the page on every load: a reload is the sign-in.
+        async signIn() {
+            globalThis.location?.reload();
+        },
+        async signOut() {
+            token = null;
+        },
+    }, parts);
+}
 /**
  * Who the token belongs to, read from the access token itself (cube/oauth-server issues JWTs).
  * For display only: the DMP checks the token on every request, this SDK does not verify it.
@@ -234,11 +461,22 @@ function resolve(path, pageUrl) {
 function mock(data) {
     registeredMock = data;
 }
+/**
+ * Registers the house style before `connect()`, for an app that holds it in code instead of shipping
+ * `cube-theme.json`, and applies it right away. `null` forgets it again (neutral).
+ */
+function theme(input) {
+    registeredTheme = input;
+    setTheme(resolveTheme(input, currentPage()));
+}
 /** What `cube-sdk.js` puts on `window`, and what this package exports as `CubeApp`. */
 export const CubeApp = Object.freeze({
     connect,
+    /** The session the app connected, or one connected with the defaults. What blocks use. */
+    ready,
     mock,
-    /** This SDK's version, e.g. `'1.0.0-rc.4'`. */
+    theme,
+    /** This SDK's version, e.g. `'1.1.0-rc.2'`. */
     version: VERSION,
     /** The manifest `"sdk"` value this build serves. */
     sdk: MANIFEST_SDK,

package/dist/browser.js

@@ -1,3 +1,16 @@
-import { CubeApp } from './app.js';
+import { CubeApp as Core } from './app.js';
+import { trialConfig } from './trial.js';
+import { defineBlocks } from './ui/define.js';
+import { showTrialBanner } from './ui/trial-banner.js';
 // The entry of dist/cube-sdk.js: one classic script, no imports, `window.CubeApp` for a page without a build step.
+const CubeApp = Object.freeze({ ...Core, defineBlocks });
 globalThis.CubeApp = CubeApp;
+// An engine without custom elements (an old browser, a script run outside a page) keeps the plain CubeApp.
+if (typeof customElements !== 'undefined')
+    defineBlocks();
+// A trial page (the config was read when trial.ts evaluated): say so at the top, and follow the trial's status.
+const trial = trialConfig();
+const page = globalThis;
+if (trial !== null && page.document !== undefined && page.CSSStyleSheet !== undefined) {
+    showTrialBanner(page, trial);
+}

package/dist/client.d.ts

@@ -37,6 +37,8 @@ export interface CreateOptions {
 export interface WriteOptions {
     /** A `recordVersion` from an earlier response (never the ETag). A stale one answers 409 `conflict`. */
     ifMatch?: string;
+    /** One key per save attempt (`newIdempotencyKey()`); send it again only to retry that same body. */
+    idempotencyKey?: string;
     fields?: readonly string[];
 }
 export interface OperationOptions {

package/dist/client.js

@@ -99,7 +99,11 @@ export function createClient(options) {
                 body: input ?? {},
                 headers: writeHeaders(opts),
             });
-            return { ...response, data: response.status === 204 ? null : response.data, accepted: response.status === 202 };
+            return {
+                ...response,
+                data: response.status === 204 ? null : response.data,
+                accepted: response.status === 202,
+            };
         };
         return {
             name,