@formio/uag 2.0.0-rc.1 → 2.0.0-rc.10

package/lib/documents/converters.d.ts

@@ -0,0 +1,28 @@
+import type { Converter } from './types';
+/** unpdf, loaded on first use: it is an ES module, and carries a PDF.js build. */
+export declare function loadUnpdf(): Promise<typeof import('unpdf')>;
+/** pdf-text: a PDF's text layer, page by page, with unpdf. */
+export declare const pdfTextConverter: Converter;
+/** Decode text: UTF-16 with a byte order mark, else UTF-8 (without its BOM), else Windows-1252 (a superset of Latin-1). */
+export declare function decodeText(buffer: Buffer): string;
+/** text: plain text, Markdown, CSV, JSON, HTML (as Markdown) and XML. */
+export declare const textConverter: Converter;
+/**
+ * The most pixels of a PNG image-pdf takes (50 megapixels, about 200 MB once
+ * decoded). A PNG is decoded whole, in memory and synchronously, so its pixel
+ * count is checked from its header first: a small, highly compressed file can
+ * describe an image far larger than its size suggests. JPEGs are embedded
+ * without being decoded. The converter's `maxPixels` setting changes it
+ * (config.plugins.settings.converter['image-pdf'].maxPixels, or
+ * DOCUMENTS_MAX_IMAGE_PIXELS).
+ */
+export declare const MAX_IMAGE_PIXELS = 50000000;
+/** A PNG's width and height, from its IHDR header; undefined when it has none. */
+export declare function pngSize(buffer: Buffer): {
+    width: number;
+    height: number;
+} | undefined;
+/** image-pdf: PNG and JPEG images into a PDF, one page per image, scaled to fit and never resampled. */
+export declare const imagePdfConverter: Converter;
+/** The converters every UAG has. None needs a system binary. */
+export declare const BUILT_IN_CONVERTERS: Converter[];

package/lib/documents/converters.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUILT_IN_CONVERTERS = exports.imagePdfConverter = exports.MAX_IMAGE_PIXELS = exports.textConverter = exports.pdfTextConverter = void 0;
+exports.loadUnpdf = loadUnpdf;
+exports.decodeText = decodeText;
+exports.pngSize = pngSize;
+const node_html_markdown_1 = require("node-html-markdown");
+const mime_1 = require("./mime");
+const convert_1 = require("./convert");
+const version_1 = require("../version");
+/**
+ * A real dynamic import: TypeScript compiles `import()` in a CommonJS build to
+ * `require()`, which cannot load an ES module before Node 22.12.
+ */
+const esmImport = new Function('specifier', 'return import(specifier)');
+/** unpdf, loaded on first use: it is an ES module, and carries a PDF.js build. */
+function loadUnpdf() {
+    return esmImport('unpdf');
+}
+/** pdf-text: a PDF's text layer, page by page, with unpdf. */
+exports.pdfTextConverter = {
+    type: 'converter',
+    name: 'pdf-text',
+    title: 'PDF text',
+    description: 'The text layer of a PDF, page by page. A PDF without one (a scan) yields empty text and a warning.',
+    version: version_1.UAG_VERSION,
+    apiVersion: 1,
+    accepts: [{ type: mime_1.MIME.pdf, ext: ['.pdf'] }],
+    produces: ['text'],
+    async convert(input, options) {
+        options.signal.throwIfAborted();
+        const { extractText, getDocumentProxy } = await loadUnpdf();
+        const document = await getDocumentProxy(new Uint8Array(input.buffer));
+        const { totalPages, text } = await extractText(document, { mergePages: false });
+        const pages = text.map((pageText, i) => ({ page: i + 1, text: String(pageText || '').trim() }));
+        const all = pages.map((page) => page.text).join('\n\n').trim();
+        return {
+            text: all,
+            textFormat: 'plain',
+            pages,
+            ...(!all && { warnings: [`"${input.name}" has no text layer (${totalPages} page${totalPages === 1 ? '' : 's'}): it may be a scan.`] })
+        };
+    }
+};
+/** Decode text: UTF-16 with a byte order mark, else UTF-8 (without its BOM), else Windows-1252 (a superset of Latin-1). */
+function decodeText(buffer) {
+    if (buffer[0] === 0xff && buffer[1] === 0xfe)
+        return new TextDecoder('utf-16le').decode(buffer.subarray(2));
+    if (buffer[0] === 0xfe && buffer[1] === 0xff)
+        return new TextDecoder('utf-16be').decode(buffer.subarray(2));
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(buffer).replace(/^\uFEFF/, '');
+    }
+    catch {
+        return new TextDecoder('windows-1252').decode(buffer);
+    }
+}
+const TEXT_FORMATS = {
+    [mime_1.MIME.markdown]: 'markdown',
+    [mime_1.MIME.html]: 'markdown',
+    [mime_1.MIME.csv]: 'csv'
+};
+/** text: plain text, Markdown, CSV, JSON, HTML (as Markdown) and XML. */
+exports.textConverter = {
+    type: 'converter',
+    name: 'text',
+    title: 'Text',
+    description: 'Text files as they are; HTML as Markdown.',
+    version: version_1.UAG_VERSION,
+    apiVersion: 1,
+    accepts: [
+        { type: mime_1.MIME.text, ext: ['.txt'] },
+        { type: mime_1.MIME.markdown, ext: ['.md', '.markdown'] },
+        { type: mime_1.MIME.csv, ext: ['.csv'] },
+        { type: mime_1.MIME.json, ext: ['.json'] },
+        { type: mime_1.MIME.html, ext: ['.html', '.htm'] },
+        { type: mime_1.MIME.xml, ext: ['.xml'] }
+    ],
+    produces: ['text'],
+    async convert(input, options) {
+        options.signal.throwIfAborted();
+        const decoded = decodeText(input.buffer);
+        const text = input.type === mime_1.MIME.html ? node_html_markdown_1.NodeHtmlMarkdown.translate(decoded) : decoded;
+        return { text, textFormat: TEXT_FORMATS[input.type] || 'plain' };
+    }
+};
+/** A4 portrait, in points. */
+const PAGE = { width: 595.28, height: 841.89, margin: 36 };
+/**
+ * The most pixels of a PNG image-pdf takes (50 megapixels, about 200 MB once
+ * decoded). A PNG is decoded whole, in memory and synchronously, so its pixel
+ * count is checked from its header first: a small, highly compressed file can
+ * describe an image far larger than its size suggests. JPEGs are embedded
+ * without being decoded. The converter's `maxPixels` setting changes it
+ * (config.plugins.settings.converter['image-pdf'].maxPixels, or
+ * DOCUMENTS_MAX_IMAGE_PIXELS).
+ */
+exports.MAX_IMAGE_PIXELS = 50000000;
+/** A PNG's width and height, from its IHDR header; undefined when it has none. */
+function pngSize(buffer) {
+    if (buffer.length < 24 || buffer.toString('latin1', 12, 16) !== 'IHDR')
+        return undefined;
+    return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
+}
+/** image-pdf: PNG and JPEG images into a PDF, one page per image, scaled to fit and never resampled. */
+exports.imagePdfConverter = {
+    type: 'converter',
+    name: 'image-pdf',
+    title: 'Image to PDF',
+    description: 'A PNG or JPEG image as a one-page PDF, scaled to fit the page.',
+    version: version_1.UAG_VERSION,
+    apiVersion: 1,
+    accepts: [{ type: mime_1.MIME.png, ext: ['.png'] }, { type: mime_1.MIME.jpeg, ext: ['.jpg', '.jpeg'] }],
+    produces: ['pdf'],
+    settings: {
+        maxPixels: {
+            type: 'number',
+            env: 'DOCUMENTS_MAX_IMAGE_PIXELS',
+            default: exports.MAX_IMAGE_PIXELS,
+            description: 'The largest PNG, in pixels (width × height), converted; a larger one is refused before it is decoded.'
+        }
+    },
+    async convert(input, options) {
+        options.signal.throwIfAborted();
+        if (input.type === mime_1.MIME.png) {
+            const size = pngSize(input.buffer);
+            if (!size)
+                throw new convert_1.ConversionError(`"${input.name}" is not a PNG image the image-pdf converter can read.`);
+            const maxPixels = Number(options.settings?.maxPixels) > 0 ? Number(options.settings.maxPixels) : exports.MAX_IMAGE_PIXELS;
+            if (size.width * size.height > maxPixels) {
+                throw new convert_1.ConversionError(`"${input.name}" is ${size.width}×${size.height} pixels, more than the image-pdf converter takes (${maxPixels} pixels).`);
+            }
+        }
+        const { PDFDocument } = require('pdf-lib');
+        const pdf = await PDFDocument.create();
+        const image = input.type === mime_1.MIME.png ? await pdf.embedPng(input.buffer) : await pdf.embedJpg(input.buffer);
+        const landscape = image.width > image.height;
+        const width = landscape ? PAGE.height : PAGE.width;
+        const height = landscape ? PAGE.width : PAGE.height;
+        const scale = Math.min(1, (width - 2 * PAGE.margin) / image.width, (height - 2 * PAGE.margin) / image.height);
+        const page = pdf.addPage([width, height]);
+        const drawn = { width: image.width * scale, height: image.height * scale };
+        // The image is embedded as it is and only drawn smaller: its pixels are never resampled.
+        page.drawImage(image, { x: (width - drawn.width) / 2, y: (height - drawn.height) / 2, ...drawn });
+        return { pdf: Buffer.from(await pdf.save()), pages: 1 };
+    }
+};
+/** The converters every UAG has. None needs a system binary. */
+exports.BUILT_IN_CONVERTERS = [exports.pdfTextConverter, exports.textConverter, exports.imagePdfConverter];

package/lib/documents/detect.d.ts

@@ -0,0 +1,31 @@
+import type { Converter } from './types';
+/** A file refused for what its bytes are. The message names the file, never its content. */
+export declare class DetectionError extends Error {
+    constructor(message: string);
+}
+/**
+ * The names in a ZIP archive's central directory, read from the end of the
+ * buffer only: no entry is ever inflated. Undefined when it is not a readable
+ * ZIP archive.
+ */
+export declare function zipEntryNames(buffer: Buffer): string[] | undefined;
+/** Whether a buffer is valid UTF-8 (or UTF-16 with a byte order mark) without NUL bytes. */
+export declare function isText(buffer: Buffer): boolean;
+/**
+ * Whether a buffer is text in a legacy 8-bit encoding (Latin-1, Windows-1252):
+ * no NUL bytes and no control characters other than tab, line breaks, form feed
+ * and the DOS end-of-file mark. Spreadsheet and editor exports still write these.
+ */
+export declare function isLegacyText(buffer: Buffer): boolean;
+/**
+ * Identify a file's type from its bytes. The name and the client's MIME type
+ * are hints only: known signatures first, then each converter's `detect`, then
+ * text (typed by extension). A detected type that contradicts the family the
+ * extension promises is refused.
+ */
+export declare function identify(buffer: Buffer, hint: {
+    name: string;
+    type?: string;
+}, converters?: Converter[]): string;
+/** The extensions known for a type, from the converters that accept it and the usual ones. */
+export declare function extensionsOf(type: string, converters?: Converter[]): string[];

package/lib/documents/detect.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DetectionError = void 0;
+exports.zipEntryNames = zipEntryNames;
+exports.isText = isText;
+exports.isLegacyText = isLegacyText;
+exports.identify = identify;
+exports.extensionsOf = extensionsOf;
+const mime_1 = require("./mime");
+/** A file refused for what its bytes are. The message names the file, never its content. */
+class DetectionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DetectionError';
+    }
+}
+exports.DetectionError = DetectionError;
+const startsWith = (buffer, bytes, offset = 0) => {
+    const expected = typeof bytes === 'string' ? Buffer.from(bytes, 'latin1') : Buffer.from(bytes);
+    return buffer.length >= offset + expected.length && buffer.subarray(offset, offset + expected.length).equals(expected);
+};
+/**
+ * The names in a ZIP archive's central directory, read from the end of the
+ * buffer only: no entry is ever inflated. Undefined when it is not a readable
+ * ZIP archive.
+ */
+function zipEntryNames(buffer) {
+    // End of central directory: 22 bytes, plus a comment of up to 65535.
+    const start = Math.max(0, buffer.length - 22 - 0xffff);
+    let end = -1;
+    for (let i = buffer.length - 22; i >= start; i--) {
+        if (buffer.readUInt32LE(i) === 0x06054b50) {
+            end = i;
+            break;
+        }
+    }
+    if (end < 0)
+        return undefined;
+    const count = buffer.readUInt16LE(end + 10);
+    const size = buffer.readUInt32LE(end + 12);
+    let offset = buffer.readUInt32LE(end + 16);
+    if (offset + size > end)
+        return undefined;
+    const names = [];
+    for (let i = 0; i < count && offset + 46 <= end; i++) {
+        if (buffer.readUInt32LE(offset) !== 0x02014b50)
+            return undefined;
+        const nameLength = buffer.readUInt16LE(offset + 28);
+        const extraLength = buffer.readUInt16LE(offset + 30);
+        const commentLength = buffer.readUInt16LE(offset + 32);
+        names.push(buffer.subarray(offset + 46, offset + 46 + nameLength).toString('utf8'));
+        offset += 46 + nameLength + extraLength + commentLength;
+    }
+    return names;
+}
+/** An ODF document's type, from its `mimetype` entry when stored uncompressed first, as ODF requires. */
+function odfType(buffer) {
+    if (buffer.readUInt32LE(0) !== 0x04034b50)
+        return undefined;
+    const method = buffer.readUInt16LE(8);
+    const size = buffer.readUInt32LE(18);
+    const nameLength = buffer.readUInt16LE(26);
+    const extraLength = buffer.readUInt16LE(28);
+    const name = buffer.subarray(30, 30 + nameLength).toString('utf8');
+    if (method !== 0 || name !== 'mimetype' || size > 200)
+        return undefined;
+    const type = buffer.subarray(30 + nameLength + extraLength, 30 + nameLength + extraLength + size).toString('ascii').trim();
+    return /^application\/vnd\.oasis\.opendocument\.[a-z.-]+$/.test(type) ? type : undefined;
+}
+function zipType(buffer) {
+    const names = zipEntryNames(buffer);
+    if (!names)
+        return mime_1.MIME.zip;
+    const has = new Set(names);
+    if (has.has('word/document.xml'))
+        return mime_1.MIME.docx;
+    if (has.has('xl/workbook.xml'))
+        return mime_1.MIME.xlsx;
+    if (has.has('ppt/presentation.xml'))
+        return mime_1.MIME.pptx;
+    if (has.has('mimetype'))
+        return odfType(buffer) || mime_1.MIME.zip;
+    return mime_1.MIME.zip;
+}
+/** Whether a buffer is valid UTF-8 (or UTF-16 with a byte order mark) without NUL bytes. */
+function isText(buffer) {
+    if (startsWith(buffer, [0xff, 0xfe]) || startsWith(buffer, [0xfe, 0xff])) {
+        return buffer.length % 2 === 0;
+    }
+    if (buffer.includes(0))
+        return false;
+    try {
+        new TextDecoder('utf-8', { fatal: true }).decode(buffer);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether a buffer is text in a legacy 8-bit encoding (Latin-1, Windows-1252):
+ * no NUL bytes and no control characters other than tab, line breaks, form feed
+ * and the DOS end-of-file mark. Spreadsheet and editor exports still write these.
+ */
+function isLegacyText(buffer) {
+    for (const byte of buffer) {
+        if (byte < 0x20 && byte !== 0x09 && byte !== 0x0a && byte !== 0x0d && byte !== 0x0c && byte !== 0x1a)
+            return false;
+    }
+    return true;
+}
+/** The type the shared detection gives the bytes, or undefined when it does not know them. */
+function signatureType(buffer, ext) {
+    if (startsWith(buffer, '%PDF-'))
+        return mime_1.MIME.pdf;
+    if (startsWith(buffer, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))
+        return mime_1.MIME.png;
+    if (startsWith(buffer, [0xff, 0xd8, 0xff]))
+        return mime_1.MIME.jpeg;
+    if (startsWith(buffer, 'GIF87a') || startsWith(buffer, 'GIF89a'))
+        return mime_1.MIME.gif;
+    if (startsWith(buffer, 'RIFF') && startsWith(buffer, 'WEBP', 8))
+        return mime_1.MIME.webp;
+    if (startsWith(buffer, [0x50, 0x4b, 0x03, 0x04]) || startsWith(buffer, [0x50, 0x4b, 0x05, 0x06]))
+        return zipType(buffer);
+    if (startsWith(buffer, [0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1])) {
+        return { '.doc': mime_1.MIME.doc, '.xls': mime_1.MIME.xls, '.ppt': mime_1.MIME.ppt }[ext] || mime_1.MIME.ole;
+    }
+    if (startsWith(buffer, '{\\rtf'))
+        return mime_1.MIME.rtf;
+    return undefined;
+}
+/**
+ * Identify a file's type from its bytes. The name and the client's MIME type
+ * are hints only: known signatures first, then each converter's `detect`, then
+ * text (typed by extension). A detected type that contradicts the family the
+ * extension promises is refused.
+ */
+function identify(buffer, hint, converters = []) {
+    const ext = (0, mime_1.extensionOf)(hint.name);
+    let type = signatureType(buffer, ext);
+    if (!type) {
+        const head = buffer.subarray(0, 4096);
+        for (const converter of converters) {
+            if (typeof converter.detect !== 'function')
+                continue;
+            const detected = converter.detect(head, { name: hint.name, type: hint.type || '' });
+            if (typeof detected === 'string' && detected) {
+                type = detected;
+                break;
+            }
+        }
+    }
+    if (!type) {
+        // Text named as text may also be in a legacy 8-bit encoding; decodeText reads it as Windows-1252.
+        const text = isText(buffer) || (!!mime_1.TEXT_BY_EXTENSION[ext] && isLegacyText(buffer));
+        type = text ? (mime_1.TEXT_BY_EXTENSION[ext] || mime_1.MIME.text) : mime_1.MIME.binary;
+    }
+    const promised = mime_1.FAMILY_BY_EXTENSION[ext];
+    if (promised && promised !== (0, mime_1.familyOf)(type)) {
+        throw new DetectionError(`"${hint.name}" is named ${ext} but its content is not a ${ext.slice(1).toUpperCase()} file; it was refused.`);
+    }
+    return type;
+}
+/** The extensions known for a type, from the converters that accept it and the usual ones. */
+function extensionsOf(type, converters = []) {
+    const fromConverters = converters.flatMap((converter) => converter.accepts.filter((accept) => accept.type === type).flatMap((accept) => accept.ext || []));
+    return [...new Set([...fromConverters, ...(mime_1.EXTENSIONS[type] || [])].map((ext) => ext.toLowerCase()))];
+}

package/lib/documents/index.d.ts

@@ -0,0 +1,9 @@
+export * from './types';
+export { MIME } from './mime';
+export { identify, DetectionError, zipEntryNames } from './detect';
+export { runConverter, ConversionError, CONVERTER_DEFAULTS } from './convert';
+export { BUILT_IN_CONVERTERS, pdfTextConverter, textConverter, imagePdfConverter } from './converters';
+export { ConverterRoutes, stepName } from './routes';
+export type { FileRoute, AcceptEntry, Pins } from './routes';
+export { converterPluginType, registerDocuments, documentsOf } from './plugins';
+export { converterFileReader, readAsText } from './readers';

package/lib/documents/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.readAsText = exports.converterFileReader = exports.documentsOf = exports.registerDocuments = exports.converterPluginType = exports.stepName = exports.ConverterRoutes = exports.imagePdfConverter = exports.textConverter = exports.pdfTextConverter = exports.BUILT_IN_CONVERTERS = exports.CONVERTER_DEFAULTS = exports.ConversionError = exports.runConverter = exports.zipEntryNames = exports.DetectionError = exports.identify = exports.MIME = void 0;
+__exportStar(require("./types"), exports);
+var mime_1 = require("./mime");
+Object.defineProperty(exports, "MIME", { enumerable: true, get: function () { return mime_1.MIME; } });
+var detect_1 = require("./detect");
+Object.defineProperty(exports, "identify", { enumerable: true, get: function () { return detect_1.identify; } });
+Object.defineProperty(exports, "DetectionError", { enumerable: true, get: function () { return detect_1.DetectionError; } });
+Object.defineProperty(exports, "zipEntryNames", { enumerable: true, get: function () { return detect_1.zipEntryNames; } });
+var convert_1 = require("./convert");
+Object.defineProperty(exports, "runConverter", { enumerable: true, get: function () { return convert_1.runConverter; } });
+Object.defineProperty(exports, "ConversionError", { enumerable: true, get: function () { return convert_1.ConversionError; } });
+Object.defineProperty(exports, "CONVERTER_DEFAULTS", { enumerable: true, get: function () { return convert_1.CONVERTER_DEFAULTS; } });
+var converters_1 = require("./converters");
+Object.defineProperty(exports, "BUILT_IN_CONVERTERS", { enumerable: true, get: function () { return converters_1.BUILT_IN_CONVERTERS; } });
+Object.defineProperty(exports, "pdfTextConverter", { enumerable: true, get: function () { return converters_1.pdfTextConverter; } });
+Object.defineProperty(exports, "textConverter", { enumerable: true, get: function () { return converters_1.textConverter; } });
+Object.defineProperty(exports, "imagePdfConverter", { enumerable: true, get: function () { return converters_1.imagePdfConverter; } });
+var routes_1 = require("./routes");
+Object.defineProperty(exports, "ConverterRoutes", { enumerable: true, get: function () { return routes_1.ConverterRoutes; } });
+Object.defineProperty(exports, "stepName", { enumerable: true, get: function () { return routes_1.stepName; } });
+var plugins_1 = require("./plugins");
+Object.defineProperty(exports, "converterPluginType", { enumerable: true, get: function () { return plugins_1.converterPluginType; } });
+Object.defineProperty(exports, "registerDocuments", { enumerable: true, get: function () { return plugins_1.registerDocuments; } });
+Object.defineProperty(exports, "documentsOf", { enumerable: true, get: function () { return plugins_1.documentsOf; } });
+var readers_1 = require("./readers");
+Object.defineProperty(exports, "converterFileReader", { enumerable: true, get: function () { return readers_1.converterFileReader; } });
+Object.defineProperty(exports, "readAsText", { enumerable: true, get: function () { return readers_1.readAsText; } });

package/lib/documents/mime.d.ts

@@ -0,0 +1,39 @@
+/** Canonical MIME types the UAG identifies, and the extensions that go with them. */
+export declare const MIME: {
+    readonly pdf: 'application/pdf';
+    readonly png: 'image/png';
+    readonly jpeg: 'image/jpeg';
+    readonly gif: 'image/gif';
+    readonly webp: 'image/webp';
+    readonly docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document';
+    readonly xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
+    readonly pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation';
+    readonly doc: 'application/msword';
+    readonly xls: 'application/vnd.ms-excel';
+    readonly ppt: 'application/vnd.ms-powerpoint';
+    readonly rtf: 'application/rtf';
+    readonly zip: 'application/zip';
+    readonly ole: 'application/x-ole-storage';
+    readonly text: 'text/plain';
+    readonly markdown: 'text/markdown';
+    readonly csv: 'text/csv';
+    readonly json: 'application/json';
+    readonly html: 'text/html';
+    readonly xml: 'application/xml';
+    readonly binary: 'application/octet-stream';
+};
+/** Text types, by extension. */
+export declare const TEXT_BY_EXTENSION: Record<string, string>;
+/** The usual extensions of each type, for the builder's file picker. */
+export declare const EXTENSIONS: Record<string, string[]>;
+/**
+ * The family of content an extension promises. A file whose detected content
+ * belongs to another family is refused: a disguised file.
+ */
+export declare const FAMILY_BY_EXTENSION: Record<string, string>;
+/** The family of a detected type. */
+export declare function familyOf(type: string): string;
+/** A file name's extension, lower-case with its dot ('' when it has none). */
+export declare function extensionOf(name: string | undefined): string;
+/** Whether a type is one the built-in text converter reads. */
+export declare const TEXT_TYPES: string[];

package/lib/documents/mime.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TEXT_TYPES = exports.FAMILY_BY_EXTENSION = exports.EXTENSIONS = exports.TEXT_BY_EXTENSION = exports.MIME = void 0;
+exports.familyOf = familyOf;
+exports.extensionOf = extensionOf;
+/** Canonical MIME types the UAG identifies, and the extensions that go with them. */
+exports.MIME = {
+    pdf: 'application/pdf',
+    png: 'image/png',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    doc: 'application/msword',
+    xls: 'application/vnd.ms-excel',
+    ppt: 'application/vnd.ms-powerpoint',
+    rtf: 'application/rtf',
+    zip: 'application/zip',
+    ole: 'application/x-ole-storage',
+    text: 'text/plain',
+    markdown: 'text/markdown',
+    csv: 'text/csv',
+    json: 'application/json',
+    html: 'text/html',
+    xml: 'application/xml',
+    binary: 'application/octet-stream'
+};
+/** Text types, by extension. */
+exports.TEXT_BY_EXTENSION = {
+    '.txt': exports.MIME.text,
+    '.text': exports.MIME.text,
+    '.md': exports.MIME.markdown,
+    '.markdown': exports.MIME.markdown,
+    '.csv': exports.MIME.csv,
+    '.json': exports.MIME.json,
+    '.html': exports.MIME.html,
+    '.htm': exports.MIME.html,
+    '.xml': exports.MIME.xml
+};
+/** The usual extensions of each type, for the builder's file picker. */
+exports.EXTENSIONS = {
+    [exports.MIME.pdf]: ['.pdf'],
+    [exports.MIME.png]: ['.png'],
+    [exports.MIME.jpeg]: ['.jpg', '.jpeg'],
+    [exports.MIME.gif]: ['.gif'],
+    [exports.MIME.webp]: ['.webp'],
+    [exports.MIME.docx]: ['.docx'],
+    [exports.MIME.xlsx]: ['.xlsx'],
+    [exports.MIME.pptx]: ['.pptx'],
+    [exports.MIME.doc]: ['.doc'],
+    [exports.MIME.xls]: ['.xls'],
+    [exports.MIME.ppt]: ['.ppt'],
+    [exports.MIME.rtf]: ['.rtf'],
+    [exports.MIME.text]: ['.txt'],
+    [exports.MIME.markdown]: ['.md', '.markdown'],
+    [exports.MIME.csv]: ['.csv'],
+    [exports.MIME.json]: ['.json'],
+    [exports.MIME.html]: ['.html', '.htm'],
+    [exports.MIME.xml]: ['.xml'],
+    'application/vnd.oasis.opendocument.text': ['.odt'],
+    'application/vnd.oasis.opendocument.spreadsheet': ['.ods'],
+    'application/vnd.oasis.opendocument.presentation': ['.odp']
+};
+/**
+ * The family of content an extension promises. A file whose detected content
+ * belongs to another family is refused: a disguised file.
+ */
+exports.FAMILY_BY_EXTENSION = {
+    '.pdf': 'pdf',
+    '.png': 'image', '.jpg': 'image', '.jpeg': 'image', '.gif': 'image', '.webp': 'image',
+    '.docx': 'zip', '.xlsx': 'zip', '.pptx': 'zip', '.odt': 'zip', '.ods': 'zip', '.odp': 'zip', '.zip': 'zip',
+    '.doc': 'ole', '.xls': 'ole', '.ppt': 'ole',
+    '.rtf': 'rtf',
+    ...Object.fromEntries(Object.keys(exports.TEXT_BY_EXTENSION).map((ext) => [ext, 'text']))
+};
+/** The family of a detected type. */
+function familyOf(type) {
+    if (type === exports.MIME.pdf)
+        return 'pdf';
+    if (type.startsWith('image/'))
+        return 'image';
+    if ([exports.MIME.docx, exports.MIME.xlsx, exports.MIME.pptx, exports.MIME.zip].includes(type) || type.startsWith('application/vnd.oasis.opendocument.'))
+        return 'zip';
+    if ([exports.MIME.doc, exports.MIME.xls, exports.MIME.ppt, exports.MIME.ole].includes(type))
+        return 'ole';
+    if (type === exports.MIME.rtf)
+        return 'rtf';
+    if (type.startsWith('text/') || type === exports.MIME.json || type === exports.MIME.xml)
+        return 'text';
+    return 'other';
+}
+/** A file name's extension, lower-case with its dot ('' when it has none). */
+function extensionOf(name) {
+    const match = /(\.[A-Za-z0-9]+)$/.exec(String(name || ''));
+    return match ? match[1].toLowerCase() : '';
+}
+/** Whether a type is one the built-in text converter reads. */
+exports.TEXT_TYPES = [exports.MIME.text, exports.MIME.markdown, exports.MIME.csv, exports.MIME.json, exports.MIME.html, exports.MIME.xml];

package/lib/documents/plugins.d.ts

@@ -0,0 +1,18 @@
+import type { PluginRegistry, PluginType } from '@formio/appserver';
+import { AcceptEntry, ConverterRoutes } from './routes';
+/** Per registry: the converter routes (with `documents.prefer`), once the converters are set up. */
+type DocumentsState = {
+    routes: ConverterRoutes;
+    accept: Map<string, AcceptEntry[]>;
+};
+/** The routes over the enabled converters, and each document plugin's `accept`, once the registry has started. */
+export declare function documentsOf(registry: PluginRegistry): DocumentsState;
+/** Plugin type `converter`: a file into a PDF or text. Chosen automatically by file type. Experimental in 2.0. */
+export declare const converterPluginType: PluginType;
+/**
+ * Register the converter type and the built-in converters, as the server's
+ * own. The `document` type comes with the AI Document module
+ * (@formio/uag-extras/modules/ai-document).
+ */
+export declare function registerDocuments(registry: PluginRegistry): void;
+export {};

package/lib/documents/plugins.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.converterPluginType = void 0;
+exports.documentsOf = documentsOf;
+exports.registerDocuments = registerDocuments;
+const converters_1 = require("./converters");
+const routes_1 = require("./routes");
+const REPRESENTATIONS = ['pdf', 'text'];
+const isObject = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const states = new WeakMap();
+/** The routes over the enabled converters, and each document plugin's `accept`, once the registry has started. */
+function documentsOf(registry) {
+    let state = states.get(registry);
+    if (!state) {
+        state = { routes: new routes_1.ConverterRoutes(registry.list('converter')), accept: new Map() };
+        states.set(registry, state);
+    }
+    return state;
+}
+/** Plugin type `converter`: a file into a PDF or text. Chosen automatically by file type. Experimental in 2.0. */
+exports.converterPluginType = {
+    type: 'converter',
+    title: 'Converter',
+    apiVersions: [1],
+    editForm: 'none',
+    unavailable: 'disable',
+    stability: 'experimental',
+    validate(plugin) {
+        const problems = [];
+        if (!Array.isArray(plugin.accepts) || !plugin.accepts.length || !plugin.accepts.every((accept) => isObject(accept) && typeof accept.type === 'string' && /^[a-z]+\/[a-z0-9.+-]+$/i.test(accept.type) &&
+            (accept.ext === undefined || (Array.isArray(accept.ext) && accept.ext.every((ext) => typeof ext === 'string' && /^\.[a-z0-9]+$/i.test(ext)))))) {
+            problems.push('"accepts" must list { type, ext? } entries: MIME types, and extensions such as ".docx"');
+        }
+        if (!Array.isArray(plugin.produces) || !plugin.produces.length || !plugin.produces.every((kind) => REPRESENTATIONS.includes(kind))) {
+            problems.push('"produces" must list "pdf", "text" or both');
+        }
+        if (typeof plugin.convert !== 'function')
+            problems.push('"convert" must be a function');
+        if (plugin.detect !== undefined && typeof plugin.detect !== 'function')
+            problems.push('"detect" must be a function');
+        if (plugin.rank !== undefined && !Number.isFinite(plugin.rank))
+            problems.push('"rank" must be a number');
+        if (plugin.limits !== undefined) {
+            if (!isObject(plugin.limits) || !Object.entries(plugin.limits).every(([key, value]) => ['maxBytes', 'timeoutMs', 'concurrency'].includes(key) && Number.isFinite(value) && value > 0)) {
+                problems.push('"limits" may hold positive maxBytes, timeoutMs and concurrency');
+            }
+        }
+        return problems;
+    },
+    /** Once every converter is set up: the routes between file types, with `documents.prefer`. */
+    initialize(registry, context) {
+        const prefer = context.server?.config?.documents?.prefer || {};
+        states.set(registry, { routes: new routes_1.ConverterRoutes(registry.list('converter'), prefer), accept: new Map() });
+    },
+    manifest: (plugin) => ({ accepts: plugin.accepts, produces: plugin.produces })
+};
+/**
+ * Register the converter type and the built-in converters, as the server's
+ * own. The `document` type comes with the AI Document module
+ * (@formio/uag-extras/modules/ai-document).
+ */
+function registerDocuments(registry) {
+    registry.addType(exports.converterPluginType, '@formio/uag');
+    registry.add(converters_1.BUILT_IN_CONVERTERS, '@formio/uag', { server: true });
+}