@formio/uag 1.3.0

package/lib/UAGFormInterface.js

@@ -0,0 +1,371 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UAGFormInterface = void 0;
+const appserver_1 = require("@formio/appserver");
+const core_1 = require("@formio/core");
+const lodash_1 = require("lodash");
+class UAGFormInterface extends appserver_1.FormInterface {
+    constructor() {
+        super(...arguments);
+        this.uag = null;
+    }
+    getComponentFormat(component) {
+        switch (component.type) {
+            case 'phoneNumber':
+                return component.inputMask || '(999) 999-9999';
+            case 'datetime':
+                return component.widget?.format || 'yyyy-MM-dd hh:mm a';
+            case 'day':
+                return component.dayFirst ? 'dd/MM/yyyy' : 'MM/dd/yyyy';
+            case 'time':
+                return component.format || 'HH:mm';
+            default:
+                return '';
+        }
+    }
+    getComponentInfo(component, path) {
+        const fieldInfo = {
+            path,
+            label: component.label || component.key,
+            type: component.type,
+            format: this.getComponentFormat(component),
+            description: component.description || component.tooltip || '',
+            validation: component.validate || {},
+        };
+        if (component.placeholder) {
+            fieldInfo.prompt = component.placeholder;
+        }
+        if (component.type === 'select' || component.type === 'selectboxes') {
+            if (component.dataSrc === 'url') {
+                fieldInfo.options = [{ label: '** ANY VALUE IS ALLOWED **', value: 'Options are loaded from a URL.' }];
+            }
+            else if (component.dataSrc === 'resource') {
+                fieldInfo.options = [{ label: '** ANY VALUE IS ALLOWED **', value: `Options are loaded from the Form.io resource (${component.data.resource}).` }];
+            }
+            else if (component.dataSrc === 'json') {
+                fieldInfo.options = [{ label: '** ANY VALUE IS ALLOWED **', value: 'Options are not dynamically defined.' }];
+            }
+            else {
+                const values = component.data?.values || component.values;
+                if (!values || !Array.isArray(values)) {
+                    fieldInfo.options = [{ label: '', value: 'No options available' }];
+                }
+                else {
+                    fieldInfo.options = values.reduce((acc, v) => {
+                        acc.push({ label: v.label, value: v.value });
+                        return acc;
+                    }, []);
+                }
+            }
+        }
+        fieldInfo.nested = this.isNestedComponent(component);
+        return fieldInfo;
+    }
+    isMultiple(component) {
+        if (!component)
+            return false;
+        return !!component.multiple || component.type === 'selectboxes' || component.type === 'tags';
+    }
+    getParentToolDescription(parent) {
+        if (!parent)
+            return '';
+        return `To collect data for this component, separately use the \`collect_field_data\` tool with the following set for the \`parent\` parameter: \`parent=${JSON.stringify(parent)}\`. Use the \`get_form_fields\` tool with the same \`parent\` parameter to retrieve all the fields within this parent field. `;
+    }
+    getComponentValueRule(component) {
+        let rule = '';
+        const parent = {
+            type: component.type,
+            label: component.label || component.key,
+            data_path: '<data_path>'
+        };
+        if (component.tree ||
+            component.type === 'datagrid' ||
+            component.type === 'editgrid') {
+            parent.isTable = true;
+            rule += 'The value is a table of rows (array of objects). ' + this.getParentToolDescription(parent) + 'All `data_path`(s) for the components within this table should contain the current row index (e.g. `dataGrid[0].a`, `dataGrid[0].b`, `dataGrid[1].b`, etc.).';
+            return rule;
+        }
+        if (component.type === 'form') {
+            parent.isForm = true;
+            rule += 'The value is a nested form submission in the format `{data: {...}}` where `{...}` is the values for the child components. ' + this.getParentToolDescription(parent) + 'All `data_path`(s) for the components within this nested form should be prefixed with `data` (e.g. `nestedForm.data.exampleField`).';
+            return rule;
+        }
+        if (component.type === 'container') {
+            parent.isContainer = true;
+            rule += 'The value is an object/map of nested component values in the format `{...}`. ' + this.getParentToolDescription(parent) + 'All `data_path`(s) for the components within this container should be prefixed with the container\'s `data_path` (e.g. `container.exampleField`).';
+            return rule;
+        }
+        switch (component.type) {
+            case 'tags':
+                rule += 'The value can be any alphanumeric string, containing letters, numbers, but no white space characters or symbols. Multiple tags should be comma-separated.';
+                break;
+            case 'signature':
+                rule += 'Have the user draw their signature. The value will be a base64-encoded PNG image string of that signature.';
+                break;
+            case 'textfield':
+            case 'textarea':
+            case 'hidden':
+                rule += 'The value can be any alphanumeric string, containing letters, numbers, white space characters, and common symbols.';
+                break;
+            case 'checkbox':
+                rule += 'The value must be either boolean true (checked) or false (unchecked). A checkbox is checked if the user confirms the value. (e.g. "I agree to the terms and conditions" -> true)';
+                break;
+            case 'number':
+                rule += 'The value must be a valid number.';
+                break;
+            case 'currency':
+                rule += 'The value must be a valid currency amount (a number with up to two decimal places).';
+                break;
+            case 'password':
+                rule += 'Do not allow the user to submit passwords.';
+                break;
+            case 'phoneNumber':
+                rule += 'The value must be a valid phone number, containing only numbers, spaces, parentheses, dashes, and must follow the format defined in the "**Format**" section of that component.';
+                break;
+            case 'selectboxes':
+            case 'select':
+            case 'radio':
+                rule += `The value must be ${this.isMultiple(component) ? 'one or more (as comma separated values)' : 'one'} of the following options provided in the "**Options**" section of that component, formatted as " - Label (value)":`;
+                break;
+            case 'datetime':
+                rule += 'The value must be a valid date and time string in the format provided by the **Format** section of that component.';
+                break;
+            case 'day':
+                rule += 'The value must be a valid day string in the format provided by the **Format** section of that component.';
+                break;
+            case 'time':
+                rule += 'The value must be a valid time string in the format provided by the **Format** section of that component.';
+                break;
+            case 'url':
+                rule += 'The value must be a valid URL, starting with http:// or https://';
+                break;
+            case 'email':
+                rule += 'The value must be a valid email address.';
+                break;
+            default:
+                rule += '';
+        }
+        return rule;
+    }
+    /**
+     * Determine if the component is a nested data components. For these components, the UAG treats them as
+     * separate data collection units where the agent will explicitely call out to collect data for these components.
+     *
+     * @import { Component } from "@formio/core";
+     * @param component { Component } - The component to check.
+     * @returns { boolean } - True if the component is a nested data component, false otherwise.
+     */
+    isNestedComponent(component) {
+        if (component.tree ||
+            component.type === 'datagrid' ||
+            component.type === 'editgrid' ||
+            component.type === 'form') {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Determine if the component is a non-input component that should be skipped when collecting fields.
+     *
+     * @import { Component } from "@formio/core";
+     * @param component { Component } - The component to check.
+     * @returns { boolean } - True if the component is an input component, false otherwise.
+     */
+    inputComponent(component) {
+        const modelType = core_1.Utils.getModelType(component);
+        if (component.input === false || component.type === 'button') {
+            return false;
+        }
+        if (!component.type || modelType === 'none' || modelType === 'content') {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Get the relevant fields from the current form. This will return any non-nested input components whose
+     * values have not already been set within the data model. This allows the agent to know what fields still need to be
+     * collected from the user, as well as provides a mechanism to break up large forms into smaller chunks of data collection
+     * using the 'nested' components (datagrid, editgrid, nested form, etc.).
+     *
+     * @import { Submission } from "@formio/core";
+     * @import { AuthRequest } from "@formio/appserver";
+     * @param submission { Submission } - The current submission data model.
+     * @param authInfo { AuthRequest } - The current authentication information.
+     * @param within { string | string[] } - Optional data path or array of data paths to limit the field extraction within.
+     *  - If within is an array, then it works like "includes".
+     *  - If within is a string, then it is a single path to limit components within (non-inclusive).
+     * @returns { Promise<FormFieldInfo> } - The extracted form field information.
+     */
+    async getFields(submission, authInfo, within = '') {
+        const fieldInfo = {
+            rowIndex: -1,
+            total: 0,
+            totalRequired: 0,
+            totalRequiredCollected: 0,
+            errors: [],
+            required: { components: [], rules: {} },
+            optional: { components: [], rules: {} }
+        };
+        const nestedPaths = [];
+        const context = await this.process(submission, authInfo, null, null, null, [
+            ...core_1.Processors,
+            {
+                name: 'getFields',
+                shouldProcess: () => true,
+                process: async (context) => {
+                    const { component, path, value } = context;
+                    if (this.isNestedComponent(component)) {
+                        nestedPaths.push(path);
+                    }
+                },
+                postProcess: async (context) => {
+                    const { component, path, value } = context;
+                    // Get the current nested path (if any).
+                    const nestedPath = nestedPaths?.length ? nestedPaths[nestedPaths.length - 1] : null;
+                    // If the nested path IS the nested component, then pop it off the stack and skip it.
+                    if (nestedPath === path) {
+                        nestedPaths.pop();
+                    }
+                    if (within) {
+                        // If within is an array, then this works like "includes".
+                        if (Array.isArray(within) && !within.includes(path)) {
+                            return;
+                        }
+                        if (typeof within === 'string') {
+                            if (path.startsWith(within) && (path !== within)) {
+                                // Make sure to set the largest index for the nested component.
+                                const indexMatch = path.match(/\[(\d+)\]/);
+                                fieldInfo.rowIndex = indexMatch?.length ? parseInt(indexMatch[indexMatch.length - 1], 10) : 0;
+                            }
+                            else {
+                                return;
+                            }
+                        }
+                        // If within is a string, then it is a single path to limit components within (non-inclusive).
+                        if ((typeof within === 'string') && (!path.startsWith(within) || (path === within))) {
+                            return;
+                        }
+                    }
+                    // If this is a component within the nested path, then skip it...
+                    else if (nestedPath && path.startsWith(nestedPath) && (path !== nestedPath)) {
+                        return;
+                    }
+                    // Skip non-input components and conditionally hidden components.
+                    if (!this.inputComponent(component) || component.scope?.conditionallyHidden) {
+                        return;
+                    }
+                    // Increment the total field count regardless of whether it has a value or not.
+                    fieldInfo.total++;
+                    if (component.validate?.required) {
+                        fieldInfo.totalRequired++;
+                    }
+                    // If the component hass a value, then skip it.
+                    if ((0, core_1.componentHasValue)(component, value)) {
+                        if (component.validate?.required) {
+                            fieldInfo.totalRequiredCollected++;
+                        }
+                        return;
+                    }
+                    // Add the component info to the appropriate list.
+                    const criteria = component.validate?.required ? 'required' : 'optional';
+                    fieldInfo[criteria].rules[component.type] = this.getComponentValueRule(component);
+                    fieldInfo[criteria].components.push(this.getComponentInfo(component, path));
+                }
+            }
+        ]);
+        if (context.scope?.errors?.length) {
+            // Filter the "required" validation since those are added to the fieldInfo separately.
+            context.scope.errors = context.scope.errors.filter((error) => (error.ruleName !== 'required'));
+            if (context.scope.errors?.length) {
+                fieldInfo.errors = this.convertToFormFieldErrors((0, core_1.interpolateErrors)(context.scope.errors));
+            }
+        }
+        return fieldInfo;
+    }
+    /**
+     * Return the component at the specified data path.
+     * @param path { string } - The data path of the component to retrieve.
+     * @returns { Component | undefined } - The component at the specified path, or undefined if not found.
+     */
+    getComponent(path) {
+        return core_1.Utils.getComponent(this.form.components, path);
+    }
+    /**
+     * Convert a list of InterpolatedErrors into FormFieldErrors.
+     * @param errors
+     * @returns
+     */
+    convertToFormFieldErrors(errors) {
+        return errors.map((error) => {
+            return {
+                label: error.context?.label || 'Field',
+                path: error.context?.path,
+                error: error.message || 'Unknown validation error'
+            };
+        });
+    }
+    /**
+     * Perform a validation process on the collected form data.
+     * @param data
+     * @param auth
+     * @returns
+     */
+    async validateData(submission, auth) {
+        return this.convertToFormFieldErrors(await this.validate(submission, auth));
+    }
+    convertToSubmission(data) {
+        const submission = { data: {} };
+        for (let [path, value] of Object.entries(data || {})) {
+            const comp = this.getComponent(path);
+            if (value && comp?.type === 'selectboxes' && typeof value === 'string') {
+                value = value.split(',').reduce((obj, v) => {
+                    obj[v.trim()] = true;
+                    return obj;
+                }, {});
+            }
+            else if (value && this.isMultiple(comp) && typeof value === 'string') {
+                value = value.split(',').map((v) => v.trim());
+            }
+            (0, lodash_1.set)(submission.data, path, value);
+        }
+        return submission;
+    }
+    formatData(data = {}) {
+        const uagData = [];
+        let prefix = '';
+        core_1.Utils.eachComponentData(this.form?.components || [], data, (component, data, row, path) => {
+            let value = (0, lodash_1.get)(data, path);
+            if (this.isNestedComponent(component)) {
+                uagData.push({
+                    prefix,
+                    path,
+                    label: component.label || component.key || path,
+                    value: ''
+                });
+                prefix += '  ';
+            }
+            else if (this.inputComponent(component) && (0, core_1.componentHasValue)(component, value)) {
+                uagData.push({
+                    prefix,
+                    path,
+                    label: component.label || component.key || path,
+                    value: (0, lodash_1.isObjectLike)(value) ? JSON.stringify(value) : value
+                });
+            }
+        }, false, false, undefined, undefined, undefined, (component, data) => {
+            if (this.isNestedComponent(component)) {
+                prefix = prefix.slice(0, -3);
+            }
+        });
+        return uagData;
+    }
+    formatSubmission(submission) {
+        return {
+            _id: submission._id,
+            data: this.formatData(submission.data),
+            created: submission.created,
+            modified: submission.modified
+        };
+    }
+}
+exports.UAGFormInterface = UAGFormInterface;

package/lib/UAGProjectInterface.d.ts

@@ -0,0 +1,26 @@
+import { ProjectInterface, SubmissionRequest } from "@formio/appserver";
+import { UAGConfig } from "./config";
+import { Form } from "@formio/core";
+import { NextFunction, Response } from "express";
+import { UAGFormInterface } from "./UAGFormInterface";
+import { ResponseTemplate, UAGTemplate } from "./template";
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare class UAGProjectInterface extends ProjectInterface {
+    user: any;
+    formNames: string[];
+    uagTemplate: UAGTemplate | null;
+    mcpServer: McpServer;
+    get config(): UAGConfig;
+    constructor(endpoint?: string);
+    initialize(): Promise<void>;
+    addForm(form: Form, key: string): UAGFormInterface | undefined;
+    router(): Promise<any>;
+    authorizeRequest(req: SubmissionRequest, res: Response, next: NextFunction): Promise<Response<any, Record<string, any>> | undefined>;
+    mcpResponse(templateName: ResponseTemplate, data?: object, isError?: boolean): {
+        isError?: boolean | undefined;
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    };
+}

package/lib/UAGProjectInterface.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UAGProjectInterface = void 0;
+const appserver_1 = require("@formio/appserver");
+const tools_1 = require("./tools");
+const router_1 = require("./router");
+const template_1 = require("./template");
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const debug = require('debug')('formio:uag:UAGProjectInterface');
+class UAGProjectInterface extends appserver_1.ProjectInterface {
+    get config() { return appserver_1.ProjectInterface.module?.config || {}; }
+    constructor(endpoint) {
+        super(endpoint);
+        this.user = null;
+        this.formNames = [];
+        this.uagTemplate = null;
+        this.mcpServer = new mcp_js_1.McpServer({ name: 'formio-uag', version: '1.0.0' });
+    }
+    async initialize() {
+        await super.initialize();
+        this.uagTemplate = new template_1.UAGTemplate(this.config?.responseTemplates || {});
+        // Get the standard UAG tools.
+        const tools = await (0, tools_1.getTools)(this);
+        // Add the custom tools from config.
+        if (this.config?.tools?.length) {
+            tools.push(...this.config.tools);
+        }
+        // Iterate and register all the tools.
+        for (const tool of tools) {
+            if (tool?.name) {
+                this.mcpServer.registerTool(tool.name, {
+                    title: tool.title,
+                    description: tool.description,
+                    inputSchema: tool.inputSchema
+                }, tool.execute);
+            }
+        }
+    }
+    addForm(form, key) {
+        const formInterface = super.addForm(form, key);
+        if (!formInterface)
+            return;
+        key = key || formInterface?.form?.key;
+        if (form.tags?.includes('uag')) {
+            debug(`Registering UAG form: ${key}`);
+            formInterface.uag = {
+                machineName: key,
+                name: form.name || form.path || key,
+                title: form.title || form.name || key,
+                description: form.properties?.description || `A form to submit new ${form.title} records.`
+            };
+            this.formNames.push(formInterface.uag.name);
+        }
+        return formInterface;
+    }
+    async router() {
+        const router = await super.router();
+        const uagRouter = (0, router_1.UAGRouter)(this);
+        router.use('/uag', (req, res, next) => this.authorizeRequest(req, res, next), uagRouter);
+        router.use('/mcp', (req, res, next) => this.authorizeRequest(req, res, next), uagRouter);
+        return router;
+    }
+    async authorizeRequest(req, res, next) {
+        try {
+            const pkce = this.provider('auth.pkce');
+            if (!pkce) {
+                throw new Error('No PKCE provider configured');
+            }
+            const auth = await pkce?.authorize(req.get('authorization'));
+            if (!auth || !auth.user) {
+                throw new Error('Unauthorized');
+            }
+            req.auth = auth;
+            next();
+        }
+        catch (err) {
+            return res.status(401).set({
+                'WWW-Authenticate': `Bearer realm="uag-server", resource_metadata="${this.config?.baseUrl}/.well-known/oauth-protected-resource"`
+            }).json({
+                detail: err.message || err
+            });
+        }
+    }
+    mcpResponse(templateName, data = {}, isError = false) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: this.uagTemplate?.renderTemplate(templateName, data) || '',
+                },
+            ],
+            ...(isError && { isError: true }),
+        };
+    }
+}
+exports.UAGProjectInterface = UAGProjectInterface;

package/lib/config.d.ts

@@ -0,0 +1,54 @@
+import { ServerConfig } from '@formio/appserver';
+import { ToolInfo } from './tools/utils';
+export type UAGForm = {
+    name: string;
+    title: string;
+    description?: string;
+    machineName?: string;
+};
+export type UAGTemplateConfig = {
+    collectedData?: string;
+    submittedData?: string;
+    fieldRules?: string;
+    allFieldsCollected?: string;
+    fieldCollectedNext?: string;
+    submitValidationError?: string;
+    formSubmitted?: string;
+    listAvailableForms?: string;
+    confirmFormSubmission?: string;
+    getOptionalFields?: string;
+    formNotFound?: string;
+    noSubmissionsFound?: string;
+    submissionsFound?: string;
+    submissionSearchError?: string;
+    submissionNotFound?: string;
+    updateNotConfirmed?: string;
+    submissionUpdateError?: string;
+    submissionUpdated?: string;
+    submissionPartialIdAmbiguous?: string;
+    submissionPartialIdNotFound?: string;
+    getFormFields?: string;
+    getFormFieldsError?: string;
+    fieldValidationErrors?: string;
+    fields?: string;
+    getAvailableForms?: string;
+    noFormsAvailable?: string;
+    [key: string]: string | undefined;
+};
+export type UAGToolOverride = {
+    get_forms?: ToolInfo;
+    get_form_fields?: ToolInfo;
+    get_field_info?: ToolInfo;
+    collect_field_data?: ToolInfo;
+    confirm_form_submission?: ToolInfo;
+    submit_completed_form?: ToolInfo;
+    submission_update?: ToolInfo;
+    find_submissions?: ToolInfo;
+};
+export interface UAGConfig extends ServerConfig {
+    baseUrl?: string;
+    loginForm?: string;
+    responseTemplates?: UAGTemplateConfig;
+    toolOverrides?: UAGToolOverride;
+    tools?: ToolInfo[];
+}

package/lib/config.js

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

package/lib/index.d.ts

@@ -0,0 +1,16 @@
+import { Server, ServerModule } from '@formio/appserver';
+import { UAGProjectInterface } from './UAGProjectInterface';
+import { UAGFormInterface } from './UAGFormInterface';
+import { UAGConfig } from './config';
+export type UAGModule = ServerModule & {
+    config?: UAGConfig;
+};
+export declare class UAGServer extends Server {
+    constructor(config?: UAGConfig);
+}
+export * from '@formio/appserver';
+export * from './config';
+export * from './tools';
+export * from './router';
+export * from './template';
+export { UAGProjectInterface, UAGFormInterface };

package/lib/index.js

@@ -0,0 +1,43 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UAGFormInterface = exports.UAGProjectInterface = exports.UAGServer = void 0;
+const appserver_1 = require("@formio/appserver");
+const UAGProjectInterface_1 = require("./UAGProjectInterface");
+Object.defineProperty(exports, "UAGProjectInterface", { enumerable: true, get: function () { return UAGProjectInterface_1.UAGProjectInterface; } });
+const UAGFormInterface_1 = require("./UAGFormInterface");
+Object.defineProperty(exports, "UAGFormInterface", { enumerable: true, get: function () { return UAGFormInterface_1.UAGFormInterface; } });
+const lodash_1 = require("lodash");
+class UAGServer extends appserver_1.Server {
+    constructor(config) {
+        super((0, lodash_1.defaultsDeep)(config || {}, {
+            baseUrl: (0, lodash_1.get)(process.env, 'BASE_URL', '').toString(),
+            license: (0, lodash_1.get)(process.env, 'UAG_LICENSE', '').toString(),
+            submissionProxy: true,
+            auth: { pkce: true }
+        }));
+        this.use({
+            ProjectInterface: UAGProjectInterface_1.UAGProjectInterface,
+            FormInterface: UAGFormInterface_1.UAGFormInterface
+        });
+    }
+}
+exports.UAGServer = UAGServer;
+__exportStar(require("@formio/appserver"), exports);
+__exportStar(require("./config"), exports);
+__exportStar(require("./tools"), exports);
+__exportStar(require("./router"), exports);
+__exportStar(require("./template"), exports);

package/lib/router.d.ts

@@ -0,0 +1,3 @@
+import { Router } from 'express';
+import { UAGProjectInterface } from './UAGProjectInterface';
+export declare function UAGRouter(project: UAGProjectInterface): Router;