@formio/uag 2.0.0-rc.5 → 2.0.0-rc.7

package/lib/documents/routes.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConverterRoutes = exports.stepName = void 0;
+const mime_1 = require("./mime");
+const detect_1 = require("./detect");
+/** A converter as `name@version`, as results record routes. */
+const stepName = (converter) => `${converter.name}@${converter.version}`;
+exports.stepName = stepName;
+/**
+ * Routes from source types to representations over a set of converters.
+ * When several converters can do a step, the component's pin wins, then the
+ * operator's `documents.prefer`, then the highest rank, then the name.
+ */
+class ConverterRoutes {
+    constructor(converters, prefer = {}) {
+        this.converters = converters;
+        this.prefer = prefer;
+    }
+    /** The converter for one step from `source` to `target`, or undefined when none can do it. */
+    choose(source, target, pins = {}) {
+        const candidates = this.converters.filter((converter) => converter.produces.includes(target) && converter.accepts.some((accept) => accept.type === source));
+        if (!candidates.length)
+            return undefined;
+        for (const preferred of [pins[source], this.prefer[source]]) {
+            const found = preferred && candidates.find((converter) => converter.name === preferred);
+            if (found)
+                return found;
+        }
+        return [...candidates].sort((a, b) => ((b.rank || 0) - (a.rank || 0)) || a.name.localeCompare(b.name))[0];
+    }
+    /** The steps from `source` to a PDF: [] for a PDF, one converter otherwise, or null. */
+    toPdf(source, pins = {}) {
+        if (source === mime_1.MIME.pdf)
+            return [];
+        const converter = this.choose(source, 'pdf', pins);
+        return converter ? [converter] : null;
+    }
+    /** The steps from `source` to text: one converter, or to a PDF and then its text; null when none. */
+    toText(source, pins = {}) {
+        const direct = this.choose(source, 'text', pins);
+        if (direct)
+            return [direct];
+        const pdf = this.toPdf(source, pins);
+        const fromPdf = pdf && this.choose(mime_1.MIME.pdf, 'text', pins);
+        return pdf && fromPdf ? [...pdf, fromPdf] : null;
+    }
+    /**
+     * The first of a plugin's input sets every representation of which the
+     * file can reach. With both PDF and text, the text is always that same
+     * PDF's text, so content made from the PDF is checked against it.
+     */
+    route(source, inputs, pins = {}) {
+        for (const set of inputs) {
+            if (set.includes('pdf')) {
+                const pdf = this.toPdf(source, pins);
+                if (!pdf)
+                    continue;
+                if (!set.includes('text'))
+                    return { inputs: set, pdf };
+                const fromPdf = this.choose(mime_1.MIME.pdf, 'text', pins);
+                if (!fromPdf)
+                    continue;
+                return { inputs: set, pdf, text: [...pdf, fromPdf] };
+            }
+            if (set.includes('text')) {
+                const text = this.toText(source, pins);
+                if (text)
+                    return { inputs: set, text };
+            }
+        }
+        return null;
+    }
+    /** Every source type a converter reads, and PDF. */
+    sourceTypes() {
+        return [...new Set([mime_1.MIME.pdf, ...mime_1.TEXT_TYPES.filter((type) => this.converters.some((c) => c.accepts.some((a) => a.type === type))),
+                ...this.converters.flatMap((converter) => converter.accepts.map((accept) => accept.type))])];
+    }
+    /** The source types a plugin with these inputs can take, with their routes: its manifest's `accept`. */
+    accept(inputs) {
+        const entries = [];
+        for (const type of this.sourceTypes()) {
+            const route = this.route(type, inputs);
+            if (!route)
+                continue;
+            entries.push({
+                type,
+                ext: (0, detect_1.extensionsOf)(type, this.converters),
+                routes: {
+                    inputs: route.inputs,
+                    ...(route.pdf && { pdf: route.pdf.map((c) => c.name) }),
+                    ...(route.text && { text: route.text.map((c) => c.name) })
+                },
+                converters: this.converters.filter((c) => c.accepts.some((a) => a.type === type)).map((c) => c.name)
+            });
+        }
+        return entries;
+    }
+}
+exports.ConverterRoutes = ConverterRoutes;

package/lib/documents/types.d.ts

@@ -0,0 +1,126 @@
+import type { Plugin, PluginContext } from '@formio/appserver';
+import type { GenerateRequest, GenerateResponse } from '@formio/uag-sdk';
+export type Representation = 'pdf' | 'text';
+export type TextFormat = 'plain' | 'markdown' | 'csv';
+/** Plugin type `converter` (apiVersion 1, experimental): a file into a PDF or text. */
+export interface Converter extends Plugin {
+    type: 'converter';
+    /** MIME types (canonical) and extensions it reads. */
+    accepts: Array<{
+        type: string;
+        ext?: string[];
+    }>;
+    produces: Representation[];
+    /** Default 0; the higher wins when several converters can do a step. */
+    rank?: number;
+    /** A canonical type for formats the shared detection does not know, or null. */
+    detect?(head: Buffer, hint: {
+        name: string;
+        type: string;
+    }): string | null;
+    /** Defaults: 25 MB, 120000 ms, 2 at a time. */
+    limits?: {
+        maxBytes?: number;
+        timeoutMs?: number;
+        concurrency?: number;
+    };
+    convert(input: {
+        buffer: Buffer;
+        type: string;
+        name: string;
+    }, options: {
+        to: Representation;
+        settings: Record<string, any>;
+        signal: AbortSignal;
+        tmpdir: string;
+        log: PluginContext['log'];
+    }): Promise<ConverterOutput>;
+}
+export type ConverterOutput = {
+    pdf: Buffer;
+    pages?: number;
+    warnings?: string[];
+} | {
+    text: string;
+    textFormat: TextFormat;
+    pages?: Array<{
+        page: number;
+        text: string;
+    }>;
+    warnings?: string[];
+};
+export type DocumentFile = {
+    name: string;
+    type: string;
+    size: number;
+    sha256: string;
+    document: {
+        pdf?: Buffer;
+        pages?: number;
+        text?: string;
+        textFormat?: string;
+        textPages?: Array<{
+            page: number;
+            text: string;
+        }>;
+    };
+    /** The converters it went through, as name@version. */
+    route: string[];
+    original(): Promise<Buffer>;
+};
+export type DocumentContext = {
+    files: DocumentFile[];
+    /** Markdown. */
+    instructions: string;
+    /** This component's plugin settings, defaults applied. */
+    settings: Record<string, any>;
+    /** Operator settings. */
+    config: Record<string, any>;
+    form: {
+        id: string;
+        path: string;
+        title: string;
+    };
+    component: {
+        key: string;
+        path: string;
+        label: string;
+    };
+    /** Submission data sent with the request: context only, untrusted. */
+    data: Record<string, any>;
+    agent: {
+        generate(request: Omit<GenerateRequest, 'signal'>): Promise<GenerateResponse>;
+    };
+    progress(fraction: number, message?: string): void;
+    signal: AbortSignal;
+    log: PluginContext['log'];
+};
+export type Issue = {
+    kind: string;
+    message: string;
+    output?: string;
+    document?: string;
+    page?: number;
+    file?: string;
+};
+export type DocumentResult = {
+    content: string;
+    status: 'ok' | 'flagged';
+    issues?: Issue[];
+    summary?: string;
+};
+/** Plugin type `document` (apiVersion 1, experimental): files and instructions into content. */
+export interface DocumentPlugin extends Plugin {
+    type: 'document';
+    /** Acceptable representation sets, in order of preference. */
+    inputs: Representation[][];
+    /** JSON only; keys are relative to the plugin's settings object. */
+    editForm?: any[];
+    defaults?: Record<string, any>;
+    /** May people edit the content? Default false. */
+    editable?: boolean;
+    /** Default 'markdown'. */
+    output?: 'markdown' | 'text';
+    validateSettings?(settings: Record<string, any>): string[];
+    process(ctx: DocumentContext): Promise<DocumentResult>;
+}

package/lib/documents/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/documents/uagJs.d.ts

@@ -0,0 +1,17 @@
+import { Router } from 'express';
+import type { PluginRegistry, ServedComponent } from '@formio/appserver';
+/**
+ * `@formio/uag-js` from the UAG's own installation, at stable URLs (never a
+ * version in the path: the portal remembers its one-time prompt by URL):
+ *
+ * - `/uag-js/uag.use.js`: the bundle, registering itself with this UAG's URL and the manifest;
+ * - `/uag-js/portal.js`: the same in portal mode (the component only), then `?chain=` (https only);
+ * - `/uag-js/portal.css`: the stylesheet, after `@import url(<chain>)` when `?chain=` is given;
+ * - `/uag-js/uag-js.css`: the stylesheet.
+ *
+ * The modules' components come after: each script after the registration in
+ * `uag.use.js` and `portal.js`, each stylesheet after `uag-js.css` (and in
+ * `portal.css`), and each on its own at `/uag-js/components/<type>.js|css`.
+ * They are read on every request, as the bundle is, so the ETag follows them.
+ */
+export declare function uagJsRouter(registry: () => PluginRegistry | undefined, components?: () => ServedComponent[]): Router;

package/lib/documents/uagJs.js

@@ -0,0 +1,157 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uagJsRouter = uagJsRouter;
+const fs_1 = __importDefault(require("fs"));
+const vm_1 = __importDefault(require("vm"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = require("crypto");
+const express_1 = require("express");
+/** Where @formio/uag-js is installed: as a package, or the UAG's own workspace copy. */
+function uagJsDirectory() {
+    try {
+        return path_1.default.dirname(require.resolve('@formio/uag-js/package.json'));
+    }
+    catch {
+        const local = path_1.default.resolve(__dirname, '..', '..', 'packages', 'uag-js');
+        return fs_1.default.existsSync(path_1.default.join(local, 'index.js')) ? local : undefined;
+    }
+}
+const read = (file) => fs_1.default.readFileSync(path_1.default.join(uagJsDirectory() || '', file), 'utf8');
+/** A chained script or stylesheet URL from `?chain=`, when it is an absolute URL of the allowed schemes. */
+function chainOf(req, schemes) {
+    const chain = typeof req.query.chain === 'string' ? req.query.chain : '';
+    if (!chain)
+        return undefined;
+    try {
+        const url = new URL(chain);
+        return schemes.includes(url.protocol) ? url.href : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The script that registers the bundle once formio.js is on the page: with
+ * this UAG's URL (from the script's own src) and the manifest, and in portal
+ * mode for the portal script, then loads the chained script over https only.
+ */
+function registration(manifest, options) {
+    return `
+;(function () {
+    var manifest = ${JSON.stringify(manifest).replace(/</g, '\\u003c')};
+    var script = document.currentScript;
+    var src = script && script.src ? new URL(script.src, location.href) : null;
+    var uagUrl = src ? src.href.slice(0, src.href.indexOf('/uag-js/')) : location.origin;
+    function register() {
+        var Formio = window.Formio;
+        var lib = window.FormioUAG;
+        if (!Formio || !lib || typeof Formio.use !== 'function') return false;
+        Formio.use(lib.UAG(uagUrl, { ${options.portal ? 'portal: true, ' : ''}manifest: manifest }));
+        return true;
+    }
+    if (!register()) {
+        var tries = 0;
+        var timer = setInterval(function () { if (register() || ++tries > 600) clearInterval(timer); }, 50);
+    }
+    ${options.chain ? `var chain = document.createElement('script');
+    chain.src = ${JSON.stringify(options.chain)};
+    document.head.appendChild(chain);` : ''}
+})();
+`;
+}
+/** Whether each component script parses as a classic browser script, by its content (checked once per content). */
+const parsed = new Map();
+function parsesAsScript(file, source) {
+    const hash = (0, crypto_1.createHash)('sha256').update(source).digest('base64url');
+    const known = parsed.get(file);
+    if (known?.hash === hash)
+        return known.ok;
+    let ok = true;
+    try {
+        // Compiled only, never run. Wrapped as the bundle wraps it, so the check matches what the browser parses.
+        new vm_1.default.Script(`try {\n${source}\n} catch (err) {}`, { filename: file });
+    }
+    catch {
+        ok = false;
+        console.warn(`[formio-uag] The component script ${file} is not a browser script (an ES module, or a syntax error); it is left out of uag.use.js and portal.js.`);
+    }
+    parsed.set(file, { hash, ok });
+    return ok;
+}
+/** Serve one file: public, revalidated every time (no-cache), with an ETag from its content and the manifest. */
+function serve(req, res, type, body) {
+    const etag = `"${(0, crypto_1.createHash)('sha256').update(body).digest('base64url')}"`;
+    res.set({ 'Content-Type': `${type}; charset=utf-8`, 'Cache-Control': 'no-cache', ETag: etag, 'Access-Control-Allow-Origin': '*' });
+    if (req.headers['if-none-match'] === etag)
+        return res.status(304).end();
+    res.status(200).send(body);
+}
+/**
+ * `@formio/uag-js` from the UAG's own installation, at stable URLs (never a
+ * version in the path: the portal remembers its one-time prompt by URL):
+ *
+ * - `/uag-js/uag.use.js`: the bundle, registering itself with this UAG's URL and the manifest;
+ * - `/uag-js/portal.js`: the same in portal mode (the component only), then `?chain=` (https only);
+ * - `/uag-js/portal.css`: the stylesheet, after `@import url(<chain>)` when `?chain=` is given;
+ * - `/uag-js/uag-js.css`: the stylesheet.
+ *
+ * The modules' components come after: each script after the registration in
+ * `uag.use.js` and `portal.js`, each stylesheet after `uag-js.css` (and in
+ * `portal.css`), and each on its own at `/uag-js/components/<type>.js|css`.
+ * They are read on every request, as the bundle is, so the ETag follows them.
+ */
+function uagJsRouter(registry, components = () => []) {
+    const router = (0, express_1.Router)();
+    const manifest = () => {
+        const plugins = registry();
+        // Every plugin the modules' components may read (document, converter, module, and types
+        // modules define): not the UAG's own engines, tools and actions, which /plugins lists.
+        return plugins ? plugins.manifest().filter((plugin) => !['engine', 'tool', 'action'].includes(plugin.type)) : [];
+    };
+    // Each component's script in its own try/catch, so one that fails when it runs does not stop the others.
+    // A script that does not parse would break the whole bundle, which try/catch cannot stop: it is left out.
+    const scripts = () => components().map((component) => {
+        const label = `The ${component.type} component of the ${component.module} module`;
+        const source = fs_1.default.readFileSync(component.scriptPath, 'utf8');
+        if (!parsesAsScript(component.scriptPath, source)) {
+            return `\n;/* ${component.module}: ${component.type} */\nconsole.error(${JSON.stringify(`[uag-js] ${label} is not a browser script (an ES module, or a syntax error), so it was left out.`)});\n`;
+        }
+        return `\n;/* ${component.module}: ${component.type} */\ntry {\n${source}\n} catch (err) { console.error(${JSON.stringify(`[uag-js] ${label} could not load:`)}, err); }\n`;
+    }).join('');
+    const styles = () => components().filter((component) => component.stylePath).map((component) => `\n/* ${component.module}: ${component.type} */\n${fs_1.default.readFileSync(component.stylePath, 'utf8')}`).join('');
+    const component = (type) => components().find((candidate) => candidate.type === type);
+    router.get('/uag-js/components/:file', (req, res) => {
+        const match = /^([a-z][a-z0-9]*)\.(js|css)$/.exec(String(req.params.file));
+        const found = match ? component(match[1]) : undefined;
+        const file = found && (match[2] === 'js' ? found.scriptPath : found.stylePath);
+        if (!file)
+            return res.status(404).type('text/plain').send('No module of this UAG has that component.');
+        serve(req, res, match[2] === 'js' ? 'application/javascript' : 'text/css', fs_1.default.readFileSync(file, 'utf8'));
+    });
+    const missing = (res) => res.status(404).type('text/plain').send('@formio/uag-js is not installed with this UAG.');
+    router.get('/uag-js/uag.use.js', (req, res) => {
+        if (!uagJsDirectory())
+            return missing(res);
+        serve(req, res, 'application/javascript', read('index.js') + registration(manifest(), { portal: false }) + scripts());
+    });
+    router.get('/uag-js/portal.js', (req, res) => {
+        if (!uagJsDirectory())
+            return missing(res);
+        serve(req, res, 'application/javascript', read('index.js') + registration(manifest(), { portal: true, chain: chainOf(req, ['https:']) }) + scripts());
+    });
+    router.get('/uag-js/portal.css', (req, res) => {
+        if (!uagJsDirectory())
+            return missing(res);
+        const chain = chainOf(req, ['https:', 'http:']);
+        serve(req, res, 'text/css', (chain ? `@import url(${JSON.stringify(chain)});\n` : '') + read('uag-js.css') + styles());
+    });
+    router.get('/uag-js/uag-js.css', (req, res) => {
+        if (!uagJsDirectory())
+            return missing(res);
+        serve(req, res, 'text/css', read('uag-js.css') + styles());
+    });
+    return router;
+}

package/lib/formflow.d.ts

@@ -4,7 +4,7 @@ import { Formflow } from '@formio/appserver';
  * assertSingleCore), under the names the UAG uses. Internal to the UAG:
  * applications reach Formflow as `Formflow` from this package's exports.
  */
-export declare const EngineConfigError: typeof Formflow.EngineConfigError, EngineRegistry: typeof Formflow.EngineRegistry, FormflowError: typeof Formflow.FormflowError, FormflowService: typeof Formflow.FormflowService, RateLimitError: typeof Formflow.RateLimitError, ScopedTokenError: typeof Formflow.ScopedTokenError, bearerOf: typeof Formflow.bearerOf, engineRegistry: typeof Formflow.engineRegistry, formflow: typeof Formflow.formflow, formflowAuthenticate: typeof Formflow.formflowAuthenticate, identityOf: typeof Formflow.identityOf, issueScopedToken: typeof Formflow.issueScopedToken, isScopedToken: typeof Formflow.isScopedToken, readScopedToken: typeof Formflow.readScopedToken, resultEvent: typeof Formflow.resultEvent, withoutOwnedValues: typeof Formflow.withoutOwnedValues, stubAgentEngine: typeof Formflow.stubAgentEngine, stubDecisionEngine: typeof Formflow.stubDecisionEngine, toolsForScope: typeof Formflow.toolsForScope, EngineError: typeof Formflow.EngineError, formatReport: typeof Formflow.formatReport, flagOn: typeof Formflow.flagOn, flagOff: typeof Formflow.flagOff, ruleWithConstraints: typeof Formflow.ruleWithConstraints;
+export declare const EngineConfigError: typeof Formflow.EngineConfigError, EngineRegistry: typeof Formflow.EngineRegistry, FormflowError: typeof Formflow.FormflowError, FormflowService: typeof Formflow.FormflowService, RateLimitError: typeof Formflow.RateLimitError, ScopedTokenError: typeof Formflow.ScopedTokenError, bearerOf: typeof Formflow.bearerOf, engineRegistry: typeof Formflow.engineRegistry, formflow: typeof Formflow.formflow, formflowAuthenticate: typeof Formflow.formflowAuthenticate, identityOf: typeof Formflow.identityOf, issueScopedToken: typeof Formflow.issueScopedToken, isScopedToken: typeof Formflow.isScopedToken, readScopedToken: typeof Formflow.readScopedToken, resultEvent: typeof Formflow.resultEvent, withoutOwnedValues: typeof Formflow.withoutOwnedValues, callerKey: typeof Formflow.callerKey, stubAgentEngine: typeof Formflow.stubAgentEngine, stubDecisionEngine: typeof Formflow.stubDecisionEngine, toolsForScope: typeof Formflow.toolsForScope, EngineError: typeof Formflow.EngineError, formatReport: typeof Formflow.formatReport, flagOn: typeof Formflow.flagOn, flagOff: typeof Formflow.flagOff, ruleWithConstraints: typeof Formflow.ruleWithConstraints, describeBinary: typeof Formflow.describeBinary, isBinaryComponent: typeof Formflow.isBinaryComponent, fileMeta: typeof Formflow.fileMeta, plainTextReader: Formflow.FormflowFileReader;
 export type AgentEngine = Formflow.AgentEngine;
 export type CallerIdentity = Formflow.CallerIdentity;
 export type DecisionEngine = Formflow.DecisionEngine;
@@ -25,6 +25,9 @@ export type FormflowRoutingConfig = Formflow.FormflowRoutingConfig;
 export type FormflowService = Formflow.FormflowService;
 export type FormflowTask = Formflow.FormflowTask;
 export type FormflowTool = Formflow.FormflowTool;
+export type FormflowFileReader = Formflow.FormflowFileReader;
+export type FormflowFileMeta = Formflow.FormflowFileMeta;
+export type FormflowFileContent = Formflow.FormflowFileContent;
 export type OperationContext = Formflow.OperationContext;
 export type OperationResult = Formflow.OperationResult;
 export type ScopedTokenClaims = Formflow.ScopedTokenClaims;

package/lib/formflow.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ruleWithConstraints = exports.flagOff = exports.flagOn = exports.formatReport = exports.EngineError = exports.toolsForScope = exports.stubDecisionEngine = exports.stubAgentEngine = exports.withoutOwnedValues = exports.resultEvent = exports.readScopedToken = exports.isScopedToken = exports.issueScopedToken = exports.identityOf = exports.formflowAuthenticate = exports.formflow = exports.engineRegistry = exports.bearerOf = exports.ScopedTokenError = exports.RateLimitError = exports.FormflowService = exports.FormflowError = exports.EngineRegistry = exports.EngineConfigError = void 0;
+exports.plainTextReader = exports.fileMeta = exports.isBinaryComponent = exports.describeBinary = exports.ruleWithConstraints = exports.flagOff = exports.flagOn = exports.formatReport = exports.EngineError = exports.toolsForScope = exports.stubDecisionEngine = exports.stubAgentEngine = exports.callerKey = exports.withoutOwnedValues = exports.resultEvent = exports.readScopedToken = exports.isScopedToken = exports.issueScopedToken = exports.identityOf = exports.formflowAuthenticate = exports.formflow = exports.engineRegistry = exports.bearerOf = exports.ScopedTokenError = exports.RateLimitError = exports.FormflowService = exports.FormflowError = exports.EngineRegistry = exports.EngineConfigError = void 0;
 exports.callerIdentity = callerIdentity;
 const appserver_1 = require("@formio/appserver");
 /**
@@ -8,7 +8,7 @@ const appserver_1 = require("@formio/appserver");
  * assertSingleCore), under the names the UAG uses. Internal to the UAG:
  * applications reach Formflow as `Formflow` from this package's exports.
  */
-({ EngineConfigError: exports.EngineConfigError, EngineRegistry: exports.EngineRegistry, FormflowError: exports.FormflowError, FormflowService: exports.FormflowService, RateLimitError: exports.RateLimitError, ScopedTokenError: exports.ScopedTokenError, bearerOf: exports.bearerOf, engineRegistry: exports.engineRegistry, formflow: exports.formflow, formflowAuthenticate: exports.formflowAuthenticate, identityOf: exports.identityOf, issueScopedToken: exports.issueScopedToken, isScopedToken: exports.isScopedToken, readScopedToken: exports.readScopedToken, resultEvent: exports.resultEvent, withoutOwnedValues: exports.withoutOwnedValues, stubAgentEngine: exports.stubAgentEngine, stubDecisionEngine: exports.stubDecisionEngine, toolsForScope: exports.toolsForScope, EngineError: exports.EngineError, formatReport: exports.formatReport, flagOn: exports.flagOn, flagOff: exports.flagOff, ruleWithConstraints: exports.ruleWithConstraints } = appserver_1.Formflow);
+({ EngineConfigError: exports.EngineConfigError, EngineRegistry: exports.EngineRegistry, FormflowError: exports.FormflowError, FormflowService: exports.FormflowService, RateLimitError: exports.RateLimitError, ScopedTokenError: exports.ScopedTokenError, bearerOf: exports.bearerOf, engineRegistry: exports.engineRegistry, formflow: exports.formflow, formflowAuthenticate: exports.formflowAuthenticate, identityOf: exports.identityOf, issueScopedToken: exports.issueScopedToken, isScopedToken: exports.isScopedToken, readScopedToken: exports.readScopedToken, resultEvent: exports.resultEvent, withoutOwnedValues: exports.withoutOwnedValues, callerKey: exports.callerKey, stubAgentEngine: exports.stubAgentEngine, stubDecisionEngine: exports.stubDecisionEngine, toolsForScope: exports.toolsForScope, EngineError: exports.EngineError, formatReport: exports.formatReport, flagOn: exports.flagOn, flagOff: exports.flagOff, ruleWithConstraints: exports.ruleWithConstraints, describeBinary: exports.describeBinary, isBinaryComponent: exports.isBinaryComponent, fileMeta: exports.fileMeta, plainTextReader: exports.plainTextReader } = appserver_1.Formflow);
 /**
  * Who an operation's research acts as: core's `identityOf`, and for a caller
  * signed in with a Form.io token (`x-jwt-token`), that token, so a scoped token

package/lib/index.d.ts

@@ -1,18 +1,20 @@
 import { Server, ServerModule } from '@formio/appserver';
+import type { LoadedModule, ModuleApi, ModuleRoute, ModuleRouteHandlers, ProjectInterface } from '@formio/appserver';
 import { Request, Response, Router } from 'express';
 import { UAGProjectInterface } from './UAGProjectInterface';
 import { UAGFormInterface } from './UAGFormInterface';
 import { UAGConfig } from './config';
 import { UAGDatabase } from './database';
-export type UAGModule = ServerModule & {
+import type { UAGModuleApi } from './modules';
+export type UAGModule = ServerModule<UAGModuleApi> & {
     config?: UAGConfig;
 };
 /**
- * Agentic Formflow keeps its license state inside @formio/appserver-core. The UAG
- * loads it only through @formio/appserver, so the two always share one copy,
- * which must be 2.25.2 or later. An older @formio/appserver, or an old lockfile,
- * can still resolve an older one, which would fail in confusing ways; say what
- * to do instead.
+ * Agentic Formflow keeps its license state inside @formio/appserver-core, and
+ * modules are built on its module framework. The UAG loads it only through
+ * @formio/appserver, so the two always share one copy, which must be 2.26.0 or
+ * later. An older @formio/appserver, or an old lockfile, can still resolve an
+ * older one, which would fail in confusing ways; say what to do instead.
  */
 export declare function assertSingleCore(version?: string): void;
 /**
@@ -27,6 +29,23 @@ export declare class UAGServer extends Server {
     database?: UAGDatabase;
     /** The database between connecting and the license check. */
     private pendingDatabase?;
+    /**
+     * Use a module, or a list of modules (each in turn). A module used twice (by
+     * its `name`) is used once. `config.tools` adds up across modules; an MCP
+     * tool or engine type that two modules define stops startup, naming both.
+     * A route's `rateLimit` is the default for its name, unless the operator set one.
+     */
+    use(module: any, source?: string): void;
+    /** MCP tools and engine types, which only one module may define. */
+    protected moduleClaims(definition: Record<string, any>): string[];
+    /**
+     * MCP tools add up across modules (lodash would merge them index by index),
+     * and a named module's tools get its API as `extra.module`. Its routes'
+     * `rateLimit`s become the defaults for their names.
+     */
+    protected mergeModuleConfig(config: any, module?: LoadedModule): void;
+    /** Route rate-limit defaults, for the names the operator left unset. */
+    private routeRateLimits;
     constructor(config?: UAGConfig);
     /**
      * Connect the UAG's own database before the project loads, and check it
@@ -49,6 +68,8 @@ export declare class UAGServer extends Server {
      * route keeps Form.io's plain-text answer.
      */
     protected sendError(req: Request, res: Response, status: number, message: string, err?: any): void;
+    /** Whether a request is for a module's form route: its method, and a path ending in the route's. */
+    private isModuleRouteRequest;
     /** Browsers reading Agent API responses need the request id too. */
     get exposedHeaders(): string[];
     /** The loaded UAG project, once the project router has been built. */
@@ -60,12 +81,35 @@ export declare class UAGServer extends Server {
      * on the form's own routes.
      */
     protected extendRouter(router: Router): Promise<void>;
+    /**
+     * List the UAG's engines and MCP tools in the plugin registry, beside
+     * appserver-core's form actions. They keep loading their own way.
+     */
+    protected listPlugins(): Promise<void>;
+    /** A form's own route segments, which module routes may not use: appserver's, and the agent operations. */
+    protected get reservedFormPaths(): string[];
+    /** Module routes may not take the names of the UAG's own rate-limited operations. */
+    protected get reservedRouteNames(): string[];
+    protected get hostName(): string;
+    protected get hostVersion(): string;
+    /** The module API: appserver's, with the UAG's license check, engines, converters and helpers. */
+    protected createModuleApi(module: LoadedModule): ModuleApi;
+    /** Module routes run behind what the agent operations run behind: the caller check, body limit, request id, rate limits and error shape. */
+    protected moduleRouteHandlers(project: ProjectInterface, route: ModuleRoute<any>, module: LoadedModule): ModuleRouteHandlers;
+    protected moduleErrorBody(req: Request, err: unknown): Record<string, any> & {
+        status: number;
+    };
     router(): Promise<any>;
 }
 export * from '@formio/appserver';
 export * from './config';
 export * from './agent';
 export * from './tools';
+export * from './documents';
+export * from './modules';
+export { sanitizeMarkdown } from './markdown';
+export { usePluginFiles, pluginsFile, DEFAULT_PLUGINS_FILE } from './pluginFiles';
 export * from './router';
 export * from './template';
+export { sanitizeRichText, isRichText, RICH_TEXT_TAGS, RICH_TEXT_RULE } from './richText';
 export { UAGProjectInterface, UAGFormInterface };