@engenty/wizards-runtime 0.0.0-stage → 0.7.5

package/apps/runtime/dist/documents/parse.js

@@ -0,0 +1,246 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { note } from "@engenty-wizards/shared/run";
+import { generateText, Output } from "ai";
+import PostalMime from "postal-mime";
+import { z } from "zod";
+import { parseCsvMatrix } from "../engenty/csv-import/csv-matrix.js";
+import { readXlsxWorkbook } from "../engenty/csv-import/xlsx-workbook.js";
+import { splitMarkdownByPageBreaks } from "../engenty/doc-converter/page-break.js";
+import { LocalProvider } from "../engenty/doc-converter/providers/local/index.js";
+import { invoiceSchema, receiptSchema } from "../engenty/document-scanner/schemas/index.js";
+import { env } from "../env.js";
+import { NotedError } from "../model-errors.js";
+import { costOf, textModel } from "../models.js";
+import { htmlToMarkdown } from "../render/convert.js";
+export class UnreadableDocument extends NotedError {
+}
+const DOCX = "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+const XLSX = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+const MIME_BY_EXT = {
+    pdf: "application/pdf",
+    docx: DOCX,
+    doc: "application/msword",
+    xlsx: XLSX,
+    csv: "text/csv",
+    tsv: "text/csv",
+    txt: "text/plain",
+    md: "text/markdown",
+    json: "application/json",
+    html: "text/html",
+    htm: "text/html",
+    eml: "message/rfc822",
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    webp: "image/webp",
+    gif: "image/gif",
+    svg: "image/svg+xml",
+    avif: "image/avif",
+    mp4: "video/mp4",
+    mov: "video/quicktime",
+    webm: "video/webm",
+    mp3: "audio/mpeg",
+    wav: "audio/wav",
+    m4a: "audio/mp4",
+    woff2: "font/woff2",
+    woff: "font/woff",
+    ttf: "font/ttf",
+    otf: "font/otf",
+    glb: "model/gltf-binary",
+    gltf: "model/gltf+json",
+};
+/** The type to read a file as: mail servers and browsers often only say "octet-stream". */
+export function documentMime(name, mime) {
+    const declared = mime.split(";")[0].trim().toLowerCase();
+    if (declared && declared !== "application/octet-stream") {
+        return declared;
+    }
+    return MIME_BY_EXT[name.split(".").pop()?.toLowerCase() ?? ""] ?? declared;
+}
+/**
+ * Reads scans and photos with a vision model, as an engenty doc-converter provider. Pages are
+ * marked with the converter's page-break sentinel so paged output looks like any other.
+ */
+class VisionProvider {
+    charge;
+    signal;
+    call;
+    id = "vision";
+    name = "Vision model";
+    supportedTypes = [
+        "application/pdf",
+        "image/png",
+        "image/jpeg",
+        "image/webp",
+        "image/gif",
+    ];
+    constructor(charge, signal, call) {
+        this.charge = charge;
+        this.signal = signal;
+        this.call = call;
+    }
+    canConvert(mimeType) {
+        return this.supportedTypes.includes(mimeType);
+    }
+    async convert(data, filename, mimeType, _options) {
+        // Reads scans and photos: the class it runs on must take PDFs and images.
+        const reader = await textModel("standard", this.call);
+        const result = await generateText({
+            model: reader.model,
+            abortSignal: this.signal,
+            maxOutputTokens: 16_000,
+            system: [
+                "You transcribe documents into clean Markdown, faithfully and completely.",
+                "Keep every number, date, name and amount exactly as printed. Tables become Markdown tables.",
+                "Do not summarise, do not comment, do not wrap the result in a code fence.",
+                'For a PDF with several pages, start each page with this line: <page-break number="N" total="T"></page-break>',
+                "If a part is illegible, write [unleserlich] there.",
+                "A photo that is no document (a room, an object, a damage): describe precisely what it shows instead — what is there, how many, materials, condition, visible defects — without guessing what cannot be seen.",
+            ].join("\n"),
+            messages: [
+                {
+                    role: "user",
+                    content: [
+                        { type: "file", data, mediaType: mimeType, filename: filename || "document" },
+                        { type: "text", text: "Transcribe this document." },
+                    ],
+                },
+            ],
+        });
+        await this.charge?.(costOf(reader, result.usage));
+        const markdown = result.text.trim();
+        return {
+            markdown,
+            metadata: { word_count: markdown.split(/\s+/).filter(Boolean).length },
+            source: { filename, mime_type: mimeType, size_bytes: data.byteLength },
+        };
+    }
+}
+const local = new LocalProvider();
+function tableMarkdown(columns, rows, limit = 400) {
+    const cell = (v) => v.replace(/\|/g, "\\|").replace(/\s+/g, " ").trim();
+    const head = `| ${columns.map(cell).join(" | ")} |\n|${columns.map(() => " --- ").join("|")}|`;
+    const body = rows.slice(0, limit).map((r) => `| ${r.map(cell).join(" | ")} |`);
+    const more = rows.length > limit ? [`\n… ${rows.length - limit} more rows`] : [];
+    return [head, ...body, ...more].join("\n");
+}
+async function parseMail(data) {
+    const mail = await PostalMime.parse(data);
+    const body = mail.text?.trim() || (mail.html ? htmlToMarkdown(mail.html) : "");
+    return [
+        `From: ${mail.from?.address ?? ""}`,
+        `To: ${(mail.to ?? []).map((t) => t.address).join(", ")}`,
+        `Date: ${mail.date ?? ""}`,
+        `Subject: ${mail.subject ?? ""}`,
+        mail.attachments.length
+            ? `Attachments: ${mail.attachments.map((a) => a.filename ?? "unnamed").join(", ")}`
+            : "",
+        "",
+        body,
+    ]
+        .filter((line, i) => line || i === 5)
+        .join("\n");
+}
+const CACHE_DIR = join(env.dataDir, "parsed");
+mkdirSync(CACHE_DIR, { recursive: true });
+/**
+ * Turns a file into Markdown: PDFs and Word files by their own text, scans and photos by a
+ * vision model, spreadsheets and CSV as tables, saved mails with their headers. The result is
+ * kept by content, so a file is read (and paid for) once.
+ */
+export async function parseDocument(input, opts = {}) {
+    const mime = documentMime(input.name, input.mime);
+    return kept(input.data, mime, () => read({ ...input, mime }, opts));
+}
+/** What was made of a file, kept by its content: the same bytes are never worked through twice. */
+async function kept(data, variant, make) {
+    const file = join(CACHE_DIR, `${createHash("sha256").update(data).update(variant).digest("hex")}.json`);
+    if (existsSync(file)) {
+        return JSON.parse(await readFile(file, "utf8"));
+    }
+    const made = await make();
+    await writeFile(file, JSON.stringify(made));
+    return made;
+}
+async function read(input, opts) {
+    const { data, name, mime } = input;
+    const vision = new VisionProvider(opts.charge, opts.signal, opts.call);
+    if (mime.startsWith("image/")) {
+        if (!vision.canConvert(mime)) {
+            throw new UnreadableDocument(note("imageTypeNotReadable", { mime }));
+        }
+        const result = await vision.convert(data, name, mime);
+        return { markdown: result.markdown, pages: 1, via: "vision" };
+    }
+    if (mime === "application/pdf") {
+        const result = await local.convert(data, name, mime);
+        const pages = result.metadata.page_count ?? null;
+        const letters = result.markdown.replace(/<page-break[^>]*><\/page-break>|\s/g, "").length;
+        // Hardly any text per page: the PDF is a scan.
+        if (letters < 60 * Math.max(1, pages ?? 1)) {
+            const seen = await vision.convert(data, name, mime);
+            return {
+                markdown: seen.markdown,
+                pages: pages ?? (splitMarkdownByPageBreaks(seen.markdown).length || null),
+                via: "vision",
+            };
+        }
+        return { markdown: result.markdown, pages, via: "text" };
+    }
+    if (local.canConvert(mime)) {
+        return { markdown: (await local.convert(data, name, mime)).markdown, pages: null, via: "text" };
+    }
+    if (mime === XLSX) {
+        const workbook = await readXlsxWorkbook(data);
+        const sheets = workbook.sheets
+            .filter((s) => s.matrix.rows.length)
+            .map((s) => `## ${s.name}\n\n${tableMarkdown(s.matrix.columns, s.matrix.rows)}`);
+        return { markdown: sheets.join("\n\n"), pages: null, via: "table" };
+    }
+    const text = () => Buffer.from(data).toString("utf8");
+    if (mime === "text/csv") {
+        const matrix = parseCsvMatrix(text());
+        return { markdown: tableMarkdown(matrix.columns, matrix.rows), pages: null, via: "table" };
+    }
+    if (mime === "text/html") {
+        return { markdown: htmlToMarkdown(text()), pages: null, via: "text" };
+    }
+    if (mime === "message/rfc822") {
+        return { markdown: await parseMail(data), pages: null, via: "mail" };
+    }
+    if (mime === "application/json" || mime.startsWith("text/")) {
+        return { markdown: text(), pages: null, via: "text" };
+    }
+    throw new UnreadableDocument(note("fileNotReadable", { name, mime }));
+}
+// --- structured extraction -----------------------------------------------------
+/** The scanner's schemas say nothing about the currency; SaaS invoices come in several. */
+const currency = z
+    .string()
+    .nullable()
+    .describe("ISO 4217 code of the currency the amounts are printed in (EUR, USD, …)");
+const SCHEMAS = {
+    invoice: invoiceSchema.extend({ currency }),
+    receipt: receiptSchema.extend({ currency }),
+};
+/**
+ * Pulls the fields of an invoice or receipt out of a document, with engenty's document-scanner
+ * schemas (their field descriptions are the extraction instructions).
+ */
+export async function scanDocument(input, kind, opts = {}) {
+    const doc = await parseDocument(input, opts);
+    return kept(input.data, `scan:${kind}`, async () => {
+        const extractor = await textModel("classifier", opts.call);
+        const result = await generateText({
+            model: extractor.model,
+            abortSignal: opts.signal,
+            output: Output.object({ schema: SCHEMAS[kind] }),
+            prompt: `Extract the ${kind} from this document. Amounts are numbers in the document's own currency, exactly as printed; never convert or compute them.\n\nFile: ${input.name}\n\n${doc.markdown.slice(0, 30_000)}`,
+        });
+        await opts.charge?.(costOf(extractor, result.usage));
+        return result.output;
+    });
+}

package/apps/runtime/dist/engenty/connections-external/build-connector.js

@@ -0,0 +1,193 @@
+import { decryptToken, defineConnector, } from "../shims/connections-sdk.js";
+import { z } from "zod";
+import { headersFromRequired } from "./import-service.js";
+import { executeHttpAction } from "./invoke/http-invoker.js";
+import { mcpCallTool } from "./invoke/mcp-client.js";
+import { connectionsRedirectUri, registerDynamicClient } from "./oauth-dcr.js";
+/**
+ * Materialize a stored import record into a live `ConnectorDefinition`. From
+ * here on the framework owns everything — per-action operations, policy
+ * defaults by group, approvals, accounts, audit — identical to a hand-written
+ * provider.
+ */
+/**
+ * MCP request headers: the connector's required headers first, then the
+ * credential — auth must win a name collision, never the other way round.
+ */
+export function mcpHeaders(record, accessToken) {
+    const headers = headersFromRequired(record.required_headers);
+    const auth = record.auth_config;
+    if (auth.kind === "oauth2") {
+        return { ...headers, authorization: `Bearer ${accessToken}` };
+    }
+    if (auth.kind === "api_key" && auth.placement.in === "header") {
+        let credentials = {};
+        try {
+            credentials = JSON.parse(accessToken);
+        }
+        catch {
+            return headers;
+        }
+        const value = auth.placement.value_template.replace(/\{\{\s*([a-z0-9_]+)\s*\}\}/giu, (_m, key) => credentials[key] ?? "");
+        return { ...headers, [auth.placement.name]: value };
+    }
+    return headers;
+}
+function inputSchemaToZod(action) {
+    try {
+        const schema = z.fromJSONSchema(action.input_json_schema);
+        return schema instanceof z.ZodObject ? schema : z.object({}).loose();
+    }
+    catch {
+        return null;
+    }
+}
+function buildAction(record, action, live) {
+    const inputSchema = inputSchemaToZod(action);
+    if (!inputSchema) {
+        return null;
+    }
+    const group = action.classification === "read"
+        ? "read"
+        : action.classification === "destructive"
+            ? "destructive"
+            : "write";
+    return {
+        description: action.description.slice(0, 1024),
+        group,
+        handler: (input, ctx) => {
+            // Read the record through the live resolver: refresh updates base_url/
+            // auth without re-binding the already-registered operation closures.
+            const current = live();
+            const args = (input ?? {});
+            if (action.invoke.kind === "mcp") {
+                return mcpCallTool({
+                    args,
+                    endpoint: current.source_url,
+                    headers: mcpHeaders(current, ctx.accessToken),
+                    toolName: action.invoke.tool_name,
+                    transport: current.mcp_transport,
+                });
+            }
+            return executeHttpAction({
+                accessToken: ctx.accessToken,
+                fetchImpl: ctx.fetchImpl,
+                input: args,
+                invoke: action.invoke,
+                record: current,
+            });
+        },
+        id: action.id,
+        inputSchema,
+        summary: action.summary.slice(0, 256),
+    };
+}
+function buildAuth(record, live, persistOAuthClient) {
+    const stored = record.auth_config;
+    if (stored.kind === "oauth2") {
+        const dcr = stored.dcr === true && Boolean(stored.registration_endpoint?.trim());
+        return {
+            kind: "oauth2",
+            oauth2: {
+                authUrl: stored.auth_url,
+                baseScopes: stored.scopes,
+                dynamicClientRegistration: dcr,
+                registerClient: dcr && persistOAuthClient
+                    ? async () => {
+                        const current = live();
+                        // Public DCR clients store only client_id_enc (empty secret).
+                        if (current.client_id_enc) {
+                            return;
+                        }
+                        const endpoint = current.auth_config.kind === "oauth2"
+                            ? current.auth_config.registration_endpoint
+                            : stored.registration_endpoint;
+                        if (!endpoint) {
+                            throw new Error(`imported connector ${current.id} has no OAuth registration endpoint`);
+                        }
+                        const registered = await registerDynamicClient({
+                            clientName: current.name,
+                            redirectUri: connectionsRedirectUri(),
+                            registrationEndpoint: endpoint,
+                            scopes: current.auth_config.kind === "oauth2"
+                                ? current.auth_config.scopes
+                                : stored.scopes,
+                        });
+                        await persistOAuthClient(registered);
+                    }
+                    : undefined,
+                resolveClientCredentials: () => {
+                    const current = live();
+                    if (!current.client_id_enc) {
+                        return Promise.reject(new Error(`imported connector ${current.id} has no OAuth client credentials — set them in the import console`));
+                    }
+                    return Promise.resolve({
+                        clientId: decryptToken(current.client_id_enc),
+                        clientSecret: current.client_secret_enc
+                            ? decryptToken(current.client_secret_enc)
+                            : "",
+                    });
+                },
+                scopeSeparator: stored.scope_separator ?? " ",
+                tokenUrl: stored.token_url,
+            },
+        };
+    }
+    if (stored.kind === "api_key") {
+        return {
+            apiKey: {
+                fields: stored.fields.map((field) => ({
+                    key: field.key,
+                    label: field.label,
+                    required: field.required ?? true,
+                    secret: field.secret ?? true,
+                })),
+                // No live probe on connect: imported specs give no reliable cheap
+                // "whoami" endpoint; a bad key surfaces on first action instead.
+                verify: (credentials) => {
+                    for (const field of stored.fields) {
+                        if ((field.required ?? true) && !credentials[field.key]) {
+                            return Promise.reject(new Error(`missing credential field "${field.key}"`));
+                        }
+                    }
+                    return Promise.resolve({ label: record.domain });
+                },
+            },
+            kind: "api_key",
+        };
+    }
+    // "none": model as api_key with zero fields so connect works without input.
+    return {
+        apiKey: {
+            fields: [],
+            verify: () => Promise.resolve({ label: record.domain }),
+        },
+        kind: "api_key",
+    };
+}
+export function buildImportedConnector(record, resolveLive, persistOAuthClient) {
+    const live = () => resolveLive?.() ?? record;
+    const actions = [];
+    const skippedActions = [];
+    for (const normalized of record.actions) {
+        const action = buildAction(record, normalized, live);
+        if (action) {
+            actions.push(action);
+        }
+        else {
+            skippedActions.push(normalized.id);
+        }
+    }
+    const connector = defineConnector({
+        actions,
+        auth: buildAuth(record, live, persistOAuthClient),
+        description: `${record.name} — imported from ${record.domain} (${record.source_kind})`,
+        icon: "plug",
+        id: record.id,
+        moduleId: "connections-external",
+        name: record.name,
+        tenantId: record.tenant_id,
+        toolPrefix: record.tool_prefix,
+    });
+    return { connector, skippedActions };
+}

package/apps/runtime/dist/engenty/connections-external/errors.js

@@ -0,0 +1,11 @@
+/**
+ * Import-time rejection. Routes answer 422 for this and 502 for everything
+ * else, so anything an admin can fix by choosing a different source, filling a
+ * field, or picking another surface must be raised as this error.
+ */
+export class ImportValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ImportValidationError";
+    }
+}