@formio/uag-js 2.0.0-rc.6 → 2.0.0-rc.8

package/README.md

@@ -13,8 +13,34 @@ Formio.use(UAG('https://uag.example.com'));
 Formio.createForm(document.getElementById('claim'), 'https://forms.example.com/myproject/claim');
 ```
 
+Without a bundler, load the UAG's own `https://uag.example.com/uag-js/uag.use.js` (and `uag-js.css`) after formio.js: it registers itself with that UAG and its modules' components. See [Or load it from the UAG](https://ai.form.io/developers/renderer#or-load-it-from-the-uag).
+
 Requests to the UAG carry the user's Form.io token (`x-jwt-token`), as formio.js sends it to Form.io; no other token is needed. Routing in the browser is not a security boundary: protect the fields an agent owns on the server, with an agent role, form permissions and `uagAuthoritative`.
 
+## AI Document
+
+The **AI Document** component (`uagdocument`) is a UAG module from [`@formio/uag-extras`](https://github.com/formio/uag-extras) (`npm install @formio/uag-extras@^1`), not from this package. A UAG that uses the module adds the component to its `/uag-js/uag.use.js`; an application with a bundler registers it after this package:
+
+```js
+import aiDocument from '@formio/uag-extras/modules/ai-document/client';
+Formio.use(UAG('https://uag.example.com'));
+Formio.use(aiDocument);
+```
+
+See [AI Document](https://ai.form.io/developers/ai-document).
+
+## For components: `client`
+
+Once the UAG is registered, `client` (also `Formio.uagClient`, `FormioUAG.client` and `UAG.client`) is the browser API that components of UAG modules build on, stable within a major version: the UAG's URL, the user's token and headers, a form's URL on the UAG, the installed plugins, `stream()` for module routes, and Markdown rendering.
+
+```js
+import { client } from '@formio/uag-js';
+await client.ready;
+const done = await client.stream(client.formUrl(form) + '/document/process', { path, files }, { onEvent: (name, data) => {} });
+```
+
+Every member, and how `stream()` resolves and rejects: [For module components: `client`](https://ai.form.io/developers/renderer#for-module-components-client).
+
 ## Chat
 
 Any form tagged `uag` can also be rendered as a chat, the way `Formio.createForm` renders it as a form. A person describes what they need; the chat asks for what is still missing and fills the form behind it, which validates and submits through the UAG once they confirm. Each turn is the form's `{form}/agent/chat` on the UAG, so there is no model code and no server of your own, and it needs no Agentic Formflow license (the UAG needs an agent engine).
@@ -22,7 +48,7 @@ Any form tagged `uag` can also be rendered as a chat, the way `Formio.createForm
 ```js
 Formio.use(UAG('https://uag.example.com'));
 
-const chat = await Formio.createChat(document.getElementById('help'), 'https://forms.example.com/myproject/servicerequest', {
+const chat = await Formio.createChat(document.getElementById('help'), 'https://forms.example.com/myproject/service-request', {
   suggestions: ['My internet is down'],
   markdown: (text) => marked.parse(text)   // optional; the output is sanitized
 });

package/index.d.ts

@@ -189,11 +189,111 @@ export interface ChatForm {
 export interface UAGOptions extends Omit<AttachOptions, 'uagUrl' | 'formUrl'> {
     /** `false` attaches no Agent Input anywhere; submissions of `uag` forms still go to the UAG. */
     agentInput?: boolean;
+    /**
+     * Portal mode, used by the UAG's portal script: registers only the client
+     * and the manifest, for the modules' components. Saves are not routed, and
+     * neither Agent Input nor the chat is registered.
+     */
+    portal?: boolean;
+    /** The installed plugins, as `GET {project}/plugins` describes them. Fetched at registration when not given. */
+    manifest?: PluginManifestEntry[];
+}
+
+/** One installed plugin, as the UAG's manifest describes it. */
+export interface PluginManifestEntry {
+    type: string;
+    name: string;
+    title: string;
+    description?: string;
+    version: string;
+    stability: 'stable' | 'experimental';
+    editForm?: any[];
+    /** Document plugins: the file types the installed converters can bring to it. */
+    accept?: Array<{ type: string; ext: string[]; routes: Record<string, any>; converters: string[] }>;
+    inputs?: Array<Array<'pdf' | 'text'>>;
+    editable?: boolean;
+    output?: 'markdown' | 'text';
+    defaults?: Record<string, any>;
+    [field: string]: any;
 }
 
+/** An AI Document's stored `result`. */
+export interface AIDocumentResult {
+    content: string;
+    format: 'markdown' | 'text';
+    status: 'ok' | 'flagged';
+    issues: Array<{ kind: string; message: string; output?: string; document?: string; page?: number; file?: string }>;
+    summary: string;
+    edited: boolean;
+    meta: { plugin: string; engine: string; model: string; files: Array<{ name: string; route: string[]; pages?: number }> };
+}
+
+/**
+ * Events an AI Document emits on its form: `uagDocumentStart` ({ component, path, files }),
+ * `uagDocumentProgress` ({ component, path, progress, message? }), `uagDocumentResult`
+ * ({ component, path, result }), `uagDocumentError` ({ component, path, error }).
+ */
+export type AIDocumentEvent = 'uagDocumentStart' | 'uagDocumentProgress' | 'uagDocumentResult' | 'uagDocumentError';
+
+/** Render Markdown as the AI Document does: headings, paragraphs, lists, tables, emphasis, code and safe links, all text escaped. */
+export declare function renderMarkdown(markdown: string): string;
+
+/** Options for `client.stream`. */
+export interface ClientStreamOptions {
+    /** Called with every server-sent event, by name. */
+    onEvent?(name: string, data: any): void;
+    signal?: AbortSignal;
+    /** The rendered form, whose Form.io token identifies the user. */
+    form?: any;
+    headers?: Record<string, string>;
+    fetch?: typeof fetch;
+}
+
+/** An error the UAG answered with. */
+export interface UAGClientError extends Error {
+    status?: number;
+    code?: string;
+}
+
+/**
+ * The public browser API that components of UAG modules build on, once
+ * `Formio.use(UAG(url))` has run. Stable within a major version.
+ */
+export interface UAGClient {
+    /** The UAG's URL. */
+    url(): string;
+    /** The user's Form.io token, from the form's own formio or the SDK. */
+    token(form?: any): string | null;
+    /** The headers that identify the user to the UAG. */
+    headers(form?: any): Record<string, string>;
+    /** A form's URL on the UAG, from its definition (or a rendered form). */
+    formUrl(definition: any): string;
+    /** Resolves once the installed plugins are known. */
+    ready: Promise<void>;
+    /** Whether the installed plugins are known yet. */
+    readonly loaded: boolean;
+    /** The installed plugins, of one type or all. */
+    plugins(type?: string): PluginManifestEntry[];
+    plugin(type: string, name: string): PluginManifestEntry | null;
+    /** POST JSON, accepting server-sent events: resolves with the `done` event's data, or the JSON answer. */
+    stream(url: string, body: any, options?: ClientStreamOptions): Promise<any>;
+    renderMarkdown(markdown: string): string;
+    escapeHtml(value: unknown): string;
+    /** The formio.js the UAG was registered with. */
+    readonly Formio: any;
+}
+
+export declare const client: UAGClient;
+
 /** The formio.js module: `Formio.use(UAG('https://uag.example.com'))`. It also registers the `chat` display and `Formio.createChat`. */
 export declare function UAG(uagUrl: string, options?: UAGOptions): (Formio: any) => { fetch: Record<string, any>; displays?: Record<string, any> };
 export declare namespace UAG {
+    /** Resolves once the installed document plugins are known (embedded by the UAG's scripts, or fetched at registration). */
+    const ready: Promise<void>;
+    /** The same as `renderMarkdown`. */
+    function renderMarkdown(markdown: string): string;
+    /** The same as `client`. */
+    const client: UAGClient;
     /** The same as `attach`. */
     function attach(form: any, options?: AttachOptions): AgentInput;
     /** The same as `createChat`. */
@@ -227,5 +327,7 @@ declare const uag: {
     SSEParser: typeof SSEParser;
     isEmpty: typeof isEmpty;
     CHAT_TEMPLATES: typeof CHAT_TEMPLATES;
+    renderMarkdown: typeof renderMarkdown;
+    client: typeof client;
 };
 export default uag;

package/index.js

@@ -734,7 +734,7 @@
      * The chat: a formio.js display that renders a form as a conversation.
      *
      *   Formio.use(UAG('https://uag.example.com'));
-     *   Formio.createChat(element, 'https://forms.example.com/myproject/servicerequest');
+     *   Formio.createChat(element, 'https://forms.example.com/myproject/service-request');
      *
      * Each message the person sends goes to the form's chat on the UAG
      * (`{form}/agent/chat`) with the conversation and the form's data; the
@@ -1424,6 +1424,227 @@
         return wrapper.setForm(src);
     }
 
+
+    // ---------------------------------------------------------------------
+    // The installed plugins (the UAG's manifest), for the modules' components.
+    // ---------------------------------------------------------------------
+
+    /** The installed plugins, as the UAG's manifest describes them. */
+    var manifestState = { manifest: null, resolve: null, promise: null };
+    manifestState.promise = new Promise(function (resolve) { manifestState.resolve = resolve; });
+
+    function setManifest(manifest) {
+        manifestState.manifest = Array.isArray(manifest) ? manifest : [];
+        manifestState.resolve();
+    }
+
+    /** Fetch the manifest from the UAG, with the user's token. Resolves with [] when it cannot. */
+    function fetchManifest(uagUrl, sdk) {
+        var fetchImpl = (registered.options && registered.options.fetch) || (typeof fetch === 'function' ? fetch : null);
+        if (!fetchImpl) return Promise.resolve([]);
+        var headers = { Accept: 'application/json' };
+        try {
+            var token = sdk && typeof sdk.getToken === 'function' ? sdk.getToken() : null;
+            if (token) headers['x-jwt-token'] = token;
+        }
+        catch (err) { /* no token */ }
+        return Promise.resolve().then(function () {
+            return fetchImpl(trimSlash(uagUrl) + '/plugins', { headers: headers });
+        }).then(function (response) {
+            return response && response.ok ? response.json() : [];
+        }).catch(function () { return []; });
+    }
+
+    // --- Markdown, as sanitizeMarkdown keeps it, rendered with every text escaped ---
+
+    function safeHref(href) {
+        return /^(https?:|mailto:)/i.test(String(href || '').trim()) ? String(href).trim() : '';
+    }
+
+    /** Inline Markdown: backslash escapes, code, links (safe targets only), strong, emphasis. Everything else is escaped text. */
+    function inlineMarkdown(text) {
+        var out = '';
+        var rest = String(text || '');
+        var pattern = /(`+)([^`]*?)\1|\[([^\]]*)\]\(\s*<?([^)\s>]*)>?(?:\s+"[^"]*")?\s*\)|<((?:https?:|mailto:)[^>\s]+)>|\*\*([^*]+)\*\*|__([^_]+)__|\*([^*\s][^*]*?)\*|_([^_\s][^_]*?)_|\\([!-\/:-@[-`{-~])/;
+        var match;
+        while ((match = pattern.exec(rest))) {
+            out += escapeHtml(rest.slice(0, match.index));
+            // A backslash escape (sanitizeMarkdown escapes what it shows as text): the character itself.
+            if (match[10]) out += escapeHtml(match[10]);
+            else if (match[1]) out += '<code>' + escapeHtml(match[2]) + '</code>';
+            else if (match[3] !== undefined) {
+                var href = safeHref(match[4]);
+                out += href ? '<a href="' + escapeHtml(href) + '" target="_blank" rel="noopener noreferrer">' + inlineMarkdown(match[3]) + '</a>' : inlineMarkdown(match[3]);
+            }
+            else if (match[5]) out += '<a href="' + escapeHtml(match[5]) + '" target="_blank" rel="noopener noreferrer">' + escapeHtml(match[5]) + '</a>';
+            else if (match[6] || match[7]) out += '<strong>' + inlineMarkdown(match[6] || match[7]) + '</strong>';
+            else out += '<em>' + inlineMarkdown(match[8] || match[9]) + '</em>';
+            rest = rest.slice(match.index + match[0].length);
+        }
+        return out + escapeHtml(rest);
+    }
+
+    function tableRow(line) {
+        return line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map(function (cell) { return cell.trim(); });
+    }
+
+    /**
+     * Render Markdown to HTML: headings, paragraphs, lists, tables, emphasis,
+     * code and http/https/mailto links, nothing else. All text is escaped.
+     */
+    function renderMarkdown(markdown) {
+        var lines = String(markdown || '').replace(/\r\n?/g, '\n').split('\n');
+        var html = [];
+        var i = 0;
+        while (i < lines.length) {
+            var line = lines[i];
+            var fence = /^\s{0,3}(`{3,}|~{3,})/.exec(line);
+            if (fence) {
+                var code = [];
+                i++;
+                while (i < lines.length && !(new RegExp('^\\s{0,3}' + fence[1][0] + '{' + fence[1].length + ',}\\s*$')).test(lines[i])) code.push(lines[i++]);
+                i++;
+                html.push('<pre><code>' + escapeHtml(code.join('\n')) + '</code></pre>');
+                continue;
+            }
+            if (!line.trim()) { i++; continue; }
+            var heading = /^\s{0,3}(#{1,6})\s+(.*?)\s*#*\s*$/.exec(line);
+            if (heading) {
+                html.push('<h' + heading[1].length + '>' + inlineMarkdown(heading[2]) + '</h' + heading[1].length + '>');
+                i++;
+                continue;
+            }
+            if (/^\s*\|/.test(line) && i + 1 < lines.length && /^\s*\|?\s*:?-{1,}:?\s*(\|\s*:?-{1,}:?\s*)*\|?\s*$/.test(lines[i + 1])) {
+                var head = tableRow(line);
+                i += 2;
+                var rows = [];
+                while (i < lines.length && /^\s*\|/.test(lines[i])) rows.push(tableRow(lines[i++]));
+                html.push('<table class="table table-sm"><thead><tr>' + head.map(function (cell) { return '<th>' + inlineMarkdown(cell) + '</th>'; }).join('') + '</tr></thead><tbody>' +
+                    rows.map(function (row) { return '<tr>' + row.map(function (cell) { return '<td>' + inlineMarkdown(cell) + '</td>'; }).join('') + '</tr>'; }).join('') + '</tbody></table>');
+                continue;
+            }
+            var item = /^\s*([-*+]|\d+[.)])\s+(.*)$/.exec(line);
+            if (item) {
+                var ordered = /\d/.test(item[1]);
+                var items = [];
+                while (i < lines.length) {
+                    var next = /^\s*([-*+]|\d+[.)])\s+(.*)$/.exec(lines[i]);
+                    if (!next || /\d/.test(next[1]) !== ordered) break;
+                    items.push('<li>' + inlineMarkdown(next[2]) + '</li>');
+                    i++;
+                }
+                html.push((ordered ? '<ol>' : '<ul>') + items.join('') + (ordered ? '</ol>' : '</ul>'));
+                continue;
+            }
+            var paragraph = [];
+            while (i < lines.length && lines[i].trim() && !/^\s{0,3}(#{1,6}\s|`{3,}|~{3,})/.test(lines[i]) && !/^\s*([-*+]|\d+[.)])\s+/.test(lines[i]) && !/^\s*\|/.test(lines[i])) {
+                paragraph.push(lines[i++].trim());
+            }
+            if (!paragraph.length) { html.push('<p>' + inlineMarkdown(lines[i++]) + '</p>'); continue; }
+            html.push('<p>' + paragraph.map(inlineMarkdown).join('<br>') + '</p>');
+        }
+        return html.join('');
+    }
+
+    // ---------------------------------------------------------------------
+    // client: the public browser API that components of UAG modules build on.
+    // ---------------------------------------------------------------------
+
+    /** The headers that identify the user to the UAG: their Form.io token, and a portal team member's remote token. */
+    function authHeaders(form) {
+        var headers = {};
+        var token = formioToken(form);
+        if (token) headers['x-jwt-token'] = token;
+        try {
+            var sdk = registered.Formio;
+            var remote = sdk && typeof sdk.getRemoteToken === 'function' ? sdk.getRemoteToken() : null;
+            if (remote) headers['x-remote-token'] = remote;
+        }
+        catch (err) { /* no remote token */ }
+        return headers;
+    }
+
+    /** An Error with the UAG's status and code. */
+    function uagError(message, status, code) {
+        var err = new Error(message);
+        if (status) err.status = status;
+        if (code) err.code = code;
+        return err;
+    }
+
+    /**
+     * POST JSON to the UAG, accepting server-sent events. Resolves with the
+     * `done` event's data, or with the JSON answer; rejects with the UAG's
+     * message (and `status`, `code`) for an error answer or a `failed` event.
+     * Every event is passed to `options.onEvent(name, data)`.
+     */
+    function stream(url, body, options) {
+        options = options || {};
+        var fetchImpl = options.fetch || (registered.options && registered.options.fetch) || (typeof fetch === 'function' ? fetch : null);
+        if (!fetchImpl) return Promise.reject(uagError('fetch is not available.'));
+        var headers = Object.assign({ 'Content-Type': 'application/json', Accept: 'text/event-stream' }, authHeaders(options.form), options.headers || {});
+        var done = null;
+        var failure = null;
+        return Promise.resolve().then(function () {
+            return fetchImpl(url, { method: 'POST', headers: headers, body: JSON.stringify(body || {}), signal: options.signal });
+        }).then(function (response) {
+            var type = (response.headers && response.headers.get && response.headers.get('content-type')) || '';
+            if (!response.ok || type.indexOf('text/event-stream') === -1) {
+                return response.json().catch(function () { return {}; }).then(function (answer) {
+                    if (!response.ok) throw uagError((answer && answer.error) || ('The request failed (' + response.status + ').'), response.status, answer && answer.code);
+                    done = answer;
+                });
+            }
+            var parser = new SSEParser(function (name, data) {
+                if (typeof options.onEvent === 'function') options.onEvent(name, data);
+                if (name === 'done') done = data;
+                else if (name === 'failed' || name === 'error') failure = uagError((data && data.error) || 'The request failed.', data && data.status, data && data.code);
+            });
+            if (response.body && response.body.getReader) {
+                var reader = response.body.getReader();
+                var decoder = new TextDecoder();
+                var pump = function () {
+                    return reader.read().then(function (chunk) {
+                        if (chunk.done) return;
+                        parser.push(decoder.decode(chunk.value, { stream: true }));
+                        return pump();
+                    });
+                };
+                return pump();
+            }
+            return response.text().then(function (text) { parser.push(text + '\n\n'); });
+        }).then(function () {
+            if (failure) throw failure;
+            if (done === null) throw uagError('The request ended without an answer.');
+            return done;
+        });
+    }
+
+    /**
+     * The public browser API for components: the UAG's URL, the user's token,
+     * a form's URL on the UAG, the installed plugins, streamed requests, and
+     * Markdown rendering. Stable within a major version of @formio/uag-js.
+     */
+    var client = {
+        url: function () { return registered.uagUrl; },
+        token: function (form) { return formioToken(form); },
+        headers: function (form) { return authHeaders(form); },
+        formUrl: function (definition) { return uagFormUrl(registered.uagUrl, definition && definition.form && definition.form._id ? definition.form : definition); },
+        ready: manifestState.promise,
+        /** Whether the installed plugins are known yet (`ready` has resolved). */
+        get loaded() { return manifestState.manifest !== null; },
+        plugins: function (type) {
+            return (manifestState.manifest || []).filter(function (plugin) { return plugin && (!type || plugin.type === type); });
+        },
+        plugin: function (type, name) {
+            return client.plugins(type).filter(function (plugin) { return plugin.name === name; })[0] || null;
+        },
+        stream: stream,
+        renderMarkdown: function (markdown) { return renderMarkdown(markdown); },
+        escapeHtml: function (value) { return escapeHtml(value); },
+        get Formio() { return registered.Formio; }
+    };
+
     /**
      * The formio.js module: `Formio.use(UAG('https://uag.example.com', options))`.
      * Options: `agentInput` (`false` turns Agent Input off), and Agent Input's
@@ -1432,8 +1653,19 @@
      */
     function UAG(uagUrl, options) {
         if (!uagUrl) throw new Error('UAG(): give the UAG\'s URL, e.g. UAG(\'https://uag.example.com\').');
+        options = options || {};
         return function (Formio) {
-            registered = { uagUrl: trimSlash(uagUrl), Formio: Formio || null, options: options || {} };
+            registered = { uagUrl: trimSlash(uagUrl), Formio: Formio || null, options: options };
+            // Components of UAG modules find the client on the formio.js they are given.
+            if (Formio && (typeof Formio === 'object' || typeof Formio === 'function')) {
+                try { Object.defineProperty(Formio, 'uagClient', { value: client, configurable: true }); }
+                catch (err) { /* a frozen Formio: components use FormioUAG.client */ }
+            }
+            // The installed plugins (the manifest), which components of UAG modules read through `client`.
+            if (options.manifest) setManifest(options.manifest);
+            else if (!manifestState.manifest) fetchManifest(registered.uagUrl, Formio).then(setManifest);
+            // Portal mode: only the manifest and the client, for the modules' components; saves and Agent Input are left alone.
+            if (options.portal) return {};
             var mod = { fetch: { uag: routingPlugin(registered.uagUrl) } };
             var displays = (Formio && Formio.Displays && Formio.Displays.displays) || {};
             mod.displays = {};
@@ -1452,6 +1684,10 @@
     }
     UAG.attach = attach;
     UAG.createChat = createChat;
+    /** Resolves once the installed document plugins are known (embedded, or fetched at registration). */
+    UAG.ready = manifestState.promise;
+    UAG.renderMarkdown = renderMarkdown;
+    UAG.client = client;
 
     return {
         UAG: UAG,
@@ -1462,6 +1698,8 @@
         ExtractionState: ExtractionState,
         SSEParser: SSEParser,
         isEmpty: isEmpty,
-        CHAT_TEMPLATES: CHAT_TEMPLATES
+        CHAT_TEMPLATES: CHAT_TEMPLATES,
+        renderMarkdown: renderMarkdown,
+        client: client
     };
 }));

package/index.mjs

@@ -1,5 +1,5 @@
 // The ES module entry: the same module as index.js, which is CommonJS (and a browser global).
 import uag from './index.js';
 
-export const { UAG, attach, createChat, uagFormUrl, routingPlugin, ExtractionState, SSEParser, isEmpty, CHAT_TEMPLATES } = uag;
+export const { UAG, attach, createChat, uagFormUrl, routingPlugin, ExtractionState, SSEParser, isEmpty, CHAT_TEMPLATES, renderMarkdown, client } = uag;
 export default uag;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formio/uag-js",
-  "version": "2.0.0-rc.6",
+  "version": "2.0.0-rc.8",
   "description": "The Form.io UAG for formio.js applications: register it once, and forms tagged \"uag\" save through the UAG and get Agent Input, without overwriting what the user entered.",
   "keywords": [
     "formio",