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

package/lib/agent/stubs.d.ts

@@ -1,3 +1,4 @@
+import type { GenerateRequest } from '@formio/uag-sdk';
 /**
  * Stand-in engines for tests and local development. They answer instantly with
  * predictable values, so the Agent API can be exercised end to end without
@@ -6,7 +7,9 @@
  * any instance name.
  */
 export declare const StubDecisionEngine: Readonly<{
-    type: string;
+    type: "engine";
+    name: string;
+    title: string;
     kinds: "decision"[];
     apiVersion: 1;
     description: string;
@@ -14,8 +17,16 @@ export declare const StubDecisionEngine: Readonly<{
         calls: number;
     };
 }>;
+/** How many generate requests the stub agent engines keep: a UAG running them for a demo never grows without bound. */
+export declare const STUB_GENERATE_REQUESTS_KEPT = 20;
+/** The last generate requests the stub agent engines received (STUB_GENERATE_REQUESTS_KEPT), oldest first, for tests. */
+export declare const stubGenerateRequests: Array<Omit<GenerateRequest, 'signal' | 'onProgress'> & {
+    engine: string;
+}>;
 export declare const StubAgentEngine: Readonly<{
-    type: string;
+    type: "engine";
+    name: string;
+    title: string;
     kinds: "agent"[];
     apiVersion: 1;
     description: string;

package/lib/agent/stubs.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.StubAgentEngine = exports.StubDecisionEngine = void 0;
+exports.StubAgentEngine = exports.stubGenerateRequests = exports.STUB_GENERATE_REQUESTS_KEPT = exports.StubDecisionEngine = void 0;
 const uag_sdk_1 = require("@formio/uag-sdk");
 const formflow_1 = require("../formflow");
 /**
@@ -11,16 +11,29 @@ const formflow_1 = require("../formflow");
  * any instance name.
  */
 exports.StubDecisionEngine = (0, uag_sdk_1.defineEngine)({
-    type: 'stub-decision',
+    type: 'engine',
+    name: 'stub-decision',
+    title: 'Stub decision engine',
     kinds: ['decision'],
     apiVersion: uag_sdk_1.ENGINE_API_VERSION,
     description: 'Answers every decision with a fixed, predictable value. For tests and local development.',
     create: ({ name }) => (0, formflow_1.stubDecisionEngine)({ name }),
 });
+/** How many generate requests the stub agent engines keep: a UAG running them for a demo never grows without bound. */
+exports.STUB_GENERATE_REQUESTS_KEPT = 20;
+/** The last generate requests the stub agent engines received (STUB_GENERATE_REQUESTS_KEPT), oldest first, for tests. */
+exports.stubGenerateRequests = [];
 exports.StubAgentEngine = (0, uag_sdk_1.defineEngine)({
-    type: 'stub-agent',
+    type: 'engine',
+    name: 'stub-agent',
+    title: 'Stub agent engine',
     kinds: ['agent'],
     apiVersion: uag_sdk_1.ENGINE_API_VERSION,
-    description: 'Extracts nothing. For tests and local development.',
-    create: ({ name }) => (0, formflow_1.stubAgentEngine)({ name }),
+    description: 'Extracts nothing; generates a predictable answer from the text it is given. For tests and local development.',
+    // Text only; its generate answer shows what reached it. Observing its requests keeps it a built-in stub.
+    create: ({ name }) => (0, formflow_1.stubAgentEngine)({ name, onGenerate: (request) => {
+            exports.stubGenerateRequests.push({ ...request, engine: name });
+            if (exports.stubGenerateRequests.length > exports.STUB_GENERATE_REQUESTS_KEPT)
+                exports.stubGenerateRequests.splice(0, exports.stubGenerateRequests.length - exports.STUB_GENERATE_REQUESTS_KEPT);
+        } }),
 });

package/lib/agent/tools.d.ts

@@ -1,10 +1,31 @@
 import { FormflowTool } from "../formflow";
+import type { AuthRequest } from "@formio/appserver";
 import type { UAGProjectInterface } from "../UAGProjectInterface";
-import { ToolInfo } from "../tools/utils";
-/** Every tool the UAG serves, including custom tools from configuration. */
+import { ToolEntry, ToolInfo } from "../tools/utils";
+/** Record the module a tool came from: its `execute` gets the module's API as `extra.module`. */
+export declare function setToolModule(entry: object, api: any): void;
+/**
+ * A `config.tools` entry as a tool for the project: a bound tool's static
+ * fields, overlaid with what its `bind(project)` returns. A tool without
+ * `bind` (the 1.x shape) is used as it is.
+ */
+export declare function resolveTool(project: UAGProjectInterface, entry: ToolEntry): Promise<ToolInfo | undefined>;
+/**
+ * Every tool the UAG serves, including custom tools from configuration, each
+ * entry of which is a tool, optionally bound to the project.
+ */
 export declare function allTools(project: UAGProjectInterface): Promise<ToolInfo[]>;
+/**
+ * Run a tool with its arguments and the `ToolExtra` for the project: the same
+ * call on `/mcp` and for Agent API research. `context` is whatever else the
+ * caller has (on `/mcp`, the MCP SDK's request context, with `authInfo`).
+ */
+export declare function runTool(tool: ToolInfo, project: UAGProjectInterface, args: any, context: {
+    authInfo: AuthRequest;
+    [key: string]: any;
+}): any;
 /**
  * An MCP tool as an Agentic Formflow tool: its schema as JSON, its arguments
  * validated with its own schema, and read-only only when annotated so.
  */
-export declare function formflowTool(tool: ToolInfo): FormflowTool;
+export declare function formflowTool(tool: ToolInfo, project: UAGProjectInterface): FormflowTool;

package/lib/agent/tools.js

@@ -3,19 +3,62 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.setToolModule = setToolModule;
+exports.resolveTool = resolveTool;
 exports.allTools = allTools;
+exports.runTool = runTool;
 exports.formflowTool = formflowTool;
 const zod_1 = __importDefault(require("zod"));
 const tools_1 = require("../tools");
-/** Every tool the UAG serves, including custom tools from configuration. */
+const utils_1 = require("../tools/utils");
+/** The module API of the module each `config.tools` entry came from, for its `extra.module`. */
+const toolModules = new WeakMap();
+/** Record the module a tool came from: its `execute` gets the module's API as `extra.module`. */
+function setToolModule(entry, api) {
+    if (entry && typeof entry === 'object')
+        toolModules.set(entry, api);
+}
+/**
+ * A `config.tools` entry as a tool for the project: a bound tool's static
+ * fields, overlaid with what its `bind(project)` returns. A tool without
+ * `bind` (the 1.x shape) is used as it is.
+ */
+async function resolveTool(project, entry) {
+    if (!entry || typeof entry.bind !== 'function')
+        return entry;
+    const { bind, ...fixed } = entry;
+    const tool = { ...fixed, ...((await bind(project)) || {}) };
+    if (toolModules.has(entry))
+        toolModules.set(tool, toolModules.get(entry));
+    return tool;
+}
+/**
+ * Every tool the UAG serves, including custom tools from configuration, each
+ * entry of which is a tool, optionally bound to the project.
+ */
 async function allTools(project) {
-    return [...await (0, tools_1.getTools)(project), ...(project.config?.tools || [])].filter((tool) => !!tool?.name);
+    (0, utils_1.assertToolEntries)(project.config?.tools);
+    const custom = await Promise.all((project.config?.tools || []).map((entry) => resolveTool(project, entry)));
+    return [...await (0, tools_1.getTools)(project), ...custom].filter((tool) => !!tool?.name);
+}
+/**
+ * Run a tool with its arguments and the `ToolExtra` for the project: the same
+ * call on `/mcp` and for Agent API research. `context` is whatever else the
+ * caller has (on `/mcp`, the MCP SDK's request context, with `authInfo`).
+ */
+function runTool(tool, project, args, context) {
+    if (!tool.execute) {
+        return { content: [{ type: 'text', text: `The tool "${tool.name}" has no implementation.` }], isError: true };
+    }
+    const module = toolModules.get(tool);
+    const extra = { ...context, authInfo: context.authInfo, project, ...(module && { module }) };
+    return tool.execute(args ?? {}, extra);
 }
 /**
  * An MCP tool as an Agentic Formflow tool: its schema as JSON, its arguments
  * validated with its own schema, and read-only only when annotated so.
  */
-function formflowTool(tool) {
+function formflowTool(tool, project) {
     const schema = zod_1.default.object(tool.inputSchema || {});
     const inputSchema = zod_1.default.toJSONSchema(schema, { io: 'input', unrepresentable: 'any' });
     delete inputSchema.$schema;
@@ -28,6 +71,6 @@ function formflowTool(tool) {
             const parsed = schema.safeParse(args || {});
             return parsed.success ? { ok: true, value: parsed.data } : { ok: false, error: parsed.error.message };
         },
-        execute: async (args, auth) => tool.execute(args, { authInfo: auth })
+        execute: async (args, auth) => runTool(tool, project, args, { authInfo: auth })
     };
 }

package/lib/config.d.ts

@@ -1,7 +1,7 @@
 import { ServerConfig } from '@formio/appserver';
 import type { FormflowAgentApiConfig, FormflowRateLimit, FormflowRoutingConfig } from './formflow';
 import type { EngineInstanceSpec, EngineTypeDefinition } from '@formio/uag-sdk';
-import { ToolInfo } from './tools/utils';
+import type { ToolEntry, ToolInfo } from './tools/utils';
 import type { UAGDatabaseOptions } from './database';
 export type UAGForm = {
     name: string;
@@ -49,6 +49,30 @@ export type UAGToolOverride = {
     agent_provide?: ToolInfo;
     agent_decide?: ToolInfo;
     fetch_external_data?: ToolInfo;
+    read_document?: ToolInfo;
+};
+/** `config.documents`: limits and choices of the AI Document module (@formio/uag-extras/modules/ai-document). */
+export type UAGDocumentsConfig = {
+    /** Largest uploaded file read, in bytes (25 MB). DOCUMENTS_MAX_FILE_BYTES. */
+    maxFileBytes?: number;
+    /** Most files one component sends (10). */
+    maxFiles?: number;
+    /** Most bytes of one request's files (32 MB, the provider request cap). */
+    maxTotalBytes?: number;
+    /** Most pages once converted (500). DOCUMENTS_MAX_PAGES. */
+    maxPages?: number;
+    /** Most characters of text once converted (2,000,000). */
+    maxTextChars?: number;
+    /** One processing request, in ms (600000). DOCUMENTS_TIMEOUT_MS. */
+    timeoutMs?: number;
+    /** Comment line interval on a streamed response, in ms (15000). */
+    heartbeatMs?: number;
+    /** Concurrent processing requests per identity (3). */
+    perUser?: number;
+    /** The engine instance documents use. Default: the first capable agent engine. DOCUMENTS_ENGINE. */
+    engine?: string;
+    /** Converter name by MIME type, when several can do a step. */
+    prefer?: Record<string, string>;
 };
 /**
  * One engine instance: `"<type>"` or `"<name>:<type>"`, or `{ name, type, options }`, where the
@@ -85,6 +109,8 @@ export interface UAGChatConfig {
 export type UAGAgentApiConfig = FormflowAgentApiConfig & {
     anonymous?: UAGAnonymousConfig;
     chat?: UAGChatConfig;
+    /** The largest request body an agent operation takes, in bytes (AGENT_BODY_LIMIT). Default 5 MB. */
+    bodyLimit?: number;
 };
 /**
  * Express's `trust proxy` from TRUST_PROXY: `true` or `false`, a number of
@@ -98,8 +124,11 @@ export interface UAGConfig extends ServerConfig {
     baseUrl?: string;
     loginForm?: string;
     responseTemplates?: UAGTemplateConfig;
+    /** Limits and choices of the AI Document module. */
+    documents?: UAGDocumentsConfig;
     toolOverrides?: UAGToolOverride;
-    tools?: ToolInfo[];
+    /** Custom MCP tools: each a tool, optionally bound to the project with `bind(project)` (see ToolInfo.bind). */
+    tools?: ToolEntry[];
     /**
      * The engine instances to enable, as in `UAG_ENGINES` (`"jev"`, `"fast:claude"`) or as
      * `{ name, type, options }`. When unset, `UAG_ENGINES` is used; when neither names any, no

package/lib/documents/convert.d.ts

@@ -0,0 +1,38 @@
+import type { PluginContext } from '@formio/appserver';
+import type { Converter, ConverterOutput, Representation } from './types';
+export declare const CONVERTER_DEFAULTS: {
+    maxBytes: number;
+    timeoutMs: number;
+    concurrency: number;
+};
+/** A conversion that did not complete. The message names the converter and the file, never its content. */
+export declare class ConversionError extends Error {
+    constructor(message: string);
+}
+export type ConvertOptions = {
+    to: Representation;
+    settings?: Record<string, any>;
+    signal?: AbortSignal;
+    log: PluginContext['log'];
+};
+/**
+ * Run one conversion: under the converter's size limit, in a temporary
+ * directory made for the call and removed after it, aborted at its timeout,
+ * and queued behind its other conversions beyond its concurrency.
+ */
+export declare function runConverter(converter: Converter, input: {
+    buffer: Buffer;
+    type: string;
+    name: string;
+}, options: ConvertOptions): Promise<ConverterOutput>;
+/**
+ * Run a route: each step's output feeds the next (an intermediate step always
+ * makes a PDF), with each converter's operator settings.
+ */
+export declare function runRoute(steps: Converter[], input: {
+    buffer: Buffer;
+    type: string;
+    name: string;
+}, to: Representation, options: Omit<ConvertOptions, 'to' | 'settings'> & {
+    settingsOf?: (converter: Converter) => Record<string, any> | undefined;
+}): Promise<ConverterOutput>;

package/lib/documents/convert.js

@@ -0,0 +1,151 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConversionError = exports.CONVERTER_DEFAULTS = void 0;
+exports.runConverter = runConverter;
+exports.runRoute = runRoute;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+exports.CONVERTER_DEFAULTS = { maxBytes: 25 * 1024 * 1024, timeoutMs: 120000, concurrency: 2 };
+/** A conversion that did not complete. The message names the converter and the file, never its content. */
+class ConversionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConversionError';
+    }
+}
+exports.ConversionError = ConversionError;
+/**
+ * A queue per converter, so at most `concurrency` of its conversions run at
+ * once. A slot is held until its conversion has actually stopped: a converter
+ * that ignores its signal still counts after its caller has given up on it.
+ */
+class Queue {
+    constructor(limit) {
+        this.limit = limit;
+        this.running = 0;
+        this.waiting = [];
+    }
+    /** Wait for a slot; the returned function frees it (once). */
+    async acquire(signal) {
+        signal?.throwIfAborted();
+        if (this.running < this.limit) {
+            this.running++;
+        }
+        else {
+            // A freed slot passes straight to the next waiter, so no new caller can take it in between.
+            await new Promise((resolve, reject) => {
+                const go = () => { signal?.removeEventListener('abort', cancel); resolve(); };
+                const cancel = () => { this.waiting = this.waiting.filter((entry) => entry !== go); reject(signal.reason ?? new Error('aborted')); };
+                this.waiting.push(go);
+                signal?.addEventListener('abort', cancel, { once: true });
+            });
+        }
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            const next = this.waiting.shift();
+            if (next)
+                next();
+            else
+                this.running--;
+        };
+    }
+}
+const queues = new WeakMap();
+/**
+ * Run one conversion: under the converter's size limit, in a temporary
+ * directory made for the call and removed after it, aborted at its timeout,
+ * and queued behind its other conversions beyond its concurrency.
+ */
+async function runConverter(converter, input, options) {
+    const limits = { ...exports.CONVERTER_DEFAULTS, ...(converter.limits || {}) };
+    if (input.buffer.length > limits.maxBytes) {
+        throw new ConversionError(`"${input.name}" is larger than the ${converter.name} converter takes (${limits.maxBytes} bytes).`);
+    }
+    let queue = queues.get(converter);
+    if (!queue) {
+        queue = new Queue(Math.max(1, limits.concurrency));
+        queues.set(converter, queue);
+    }
+    const release = await queue.acquire(options.signal);
+    let tmpdir;
+    try {
+        options.signal?.throwIfAborted();
+        tmpdir = await fs_1.default.promises.mkdtemp(path_1.default.join(os_1.default.tmpdir(), 'uag-convert-'));
+    }
+    catch (err) {
+        release();
+        throw err;
+    }
+    const controller = new AbortController();
+    const abort = () => controller.abort(options.signal?.reason);
+    options.signal?.addEventListener('abort', abort, { once: true });
+    if (options.signal?.aborted)
+        abort();
+    const work = Promise.resolve().then(() => converter.convert(input, { to: options.to, settings: options.settings || {}, signal: controller.signal, tmpdir, log: options.log }));
+    // The slot and the temporary directory are kept until convert() settles, even after a timeout or an abort.
+    const stopped = work.then(() => undefined, () => undefined).then(async () => {
+        await fs_1.default.promises.rm(tmpdir, { recursive: true, force: true }).catch(() => undefined);
+        release();
+    });
+    let timer;
+    let finished = false;
+    try {
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                const error = new ConversionError(`Converting "${input.name}" with ${converter.name} took longer than ${limits.timeoutMs} ms.`);
+                // Abort first: a converter running a process stops it on its signal.
+                controller.abort(error);
+                reject(error);
+            }, limits.timeoutMs);
+        });
+        const aborted = new Promise((_, reject) => {
+            if (controller.signal.aborted)
+                reject(controller.signal.reason);
+            controller.signal.addEventListener('abort', () => reject(controller.signal.reason), { once: true });
+        });
+        const output = await Promise.race([work.finally(() => { finished = true; }), timeout, aborted]);
+        return checkOutput(converter, input.name, options.to, output);
+    }
+    finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener('abort', abort);
+        // A conversion that completed has its directory removed before its result is used.
+        if (finished)
+            await stopped;
+    }
+}
+function checkOutput(converter, name, to, output) {
+    if (to === 'pdf') {
+        if (!output || !Buffer.isBuffer(output.pdf))
+            throw new ConversionError(`The ${converter.name} converter did not produce a PDF for "${name}".`);
+        return output;
+    }
+    if (!output || typeof output.text !== 'string' || !['plain', 'markdown', 'csv'].includes(output.textFormat)) {
+        throw new ConversionError(`The ${converter.name} converter did not produce text for "${name}".`);
+    }
+    return output;
+}
+/**
+ * Run a route: each step's output feeds the next (an intermediate step always
+ * makes a PDF), with each converter's operator settings.
+ */
+async function runRoute(steps, input, to, options) {
+    let current = input;
+    let output;
+    for (let i = 0; i < steps.length; i++) {
+        const target = i === steps.length - 1 ? to : 'pdf';
+        output = await runConverter(steps[i], current, { ...options, to: target, settings: options.settingsOf?.(steps[i]) });
+        if (target === 'pdf')
+            current = { buffer: output.pdf, type: 'application/pdf', name: input.name };
+    }
+    if (!output)
+        throw new ConversionError(`No converter step for "${input.name}".`);
+    return output;
+}

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[];