@fin.cx/compatibility 2.0.0 → 3.0.0

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@fin.cx/compatibility',
-    version: '2.0.0',
+    version: '3.0.0',
     description: 'Exchange formats of third-party accounting systems: the EXTF Buchungsstapel in Windows-1252 on the rows of @fin.cx/skr, and the document-image archive (document.xml and ZIP)'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx1QkFBdUI7SUFDN0IsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLCtLQUErSztDQUM3TCxDQUFBIn0=

package/dist_ts/belegbilder/index.d.ts

@@ -1,19 +1,39 @@
-/** A document image of the archive, linked to its bookings through the GUID in their Beleglink (field 20). */
+/** The formats a document image can have here: PDF and the picture formats DATEV takes as a File (not WebP, AVIF or HEIC). */
+export type TBelegbildFormat = 'pdf' | 'jpeg' | 'png' | 'gif' | 'tiff' | 'bmp';
+export declare const BELEGBILD_FORMATS: readonly TBelegbildFormat[];
+/** A document of the archive, linked to its bookings through the GUID in their Beleglink (field 20). */
 export interface IBelegbilderDocument {
+    /** RFC 4122, `8-4-4-4-12` hexadecimal digits, as DATEV takes it */
     guid: string;
+    /** cut to DATEV's 40 characters; empty, none is written */
     description: string;
+    /** what the file is; a PDF when absent */
+    format?: TBelegbildFormat;
 }
 export interface IBelegbilderEntry extends IBelegbilderDocument {
-    /** the document as PDF */
+    /** the file as it is: the PDF, or the picture in `format` */
     bytes: Uint8Array;
 }
+/** What the archive says of itself. */
+export interface IBelegbilderArchive {
+    /** when the archive was written (DATEV's header `date`, required); its UTC clock time is written, as the Buchungsstapel header writes its own. The package reads no clock. */
+    createdAt: Date;
+    /** the software that wrote it (DATEV's `generatingSystem`, up to 40 characters) */
+    generatingSystem?: string;
+}
 export declare const BELEGBILDER_CONTENT_TYPE = "application/zip";
 /** `DATEV_Belege_<label>.zip`, for example `DATEV_Belege_2026-03.zip`. */
 export declare const belegbilderFilename: (labelArg: string) => string;
+/** The name of a document's file in the archive: its GUID and the extension of its format, for example `<GUID>.jpg`. */
+export declare const belegbildFileName: (guidArg: string, formatArg?: TBelegbildFormat) => string;
 /**
- * The manifest of the archive, `document.xml`: one `<document>` per PDF,
- * named by its GUID. UTF-8, unlike the Buchungsstapel.
+ * The manifest of the archive, `document.xml` after DATEV's `Document_v060.xsd`:
+ * one `<document>` per file, named by its GUID, with its description and one
+ * `File` extension. A GUID listed twice for the same format is one document;
+ * characters XML 1.0 does not allow are left out of the texts. UTF-8, unlike
+ * the Buchungsstapel. Refuses, as a `CompatibilityError` `invalid_documents`,
+ * what DATEV would refuse.
  */
-export declare const buildDocumentXml: (documentsArg: readonly IBelegbilderDocument[]) => string;
-/** `document.xml` and one `<GUID>.pdf` per document, as one ZIP. */
-export declare const createBelegbilderZip: (entriesArg: readonly IBelegbilderEntry[]) => Promise<Uint8Array>;
+export declare const buildDocumentXml: (documentsArg: readonly IBelegbilderDocument[], archiveArg: IBelegbilderArchive) => string;
+/** `document.xml` and each document's file under its name (`belegbildFileName`), as one ZIP: a DATEV Document-Package. */
+export declare const createBelegbilderZip: (entriesArg: readonly IBelegbilderEntry[], archiveArg: IBelegbilderArchive) => Promise<Uint8Array>;

package/dist_ts/belegbilder/index.js

@@ -1,7 +1,23 @@
 import * as plugins from './plugins.js';
+import { CompatibilityError } from '../error.js';
+export const BELEGBILD_FORMATS = ['pdf', 'jpeg', 'png', 'gif', 'tiff', 'bmp'];
+const EXTENSIONS = {
+    pdf: 'pdf',
+    jpeg: 'jpg',
+    png: 'png',
+    gif: 'gif',
+    tiff: 'tif',
+    bmp: 'bmp',
+};
 export const BELEGBILDER_CONTENT_TYPE = 'application/zip';
 /** `DATEV_Belege_<label>.zip`, for example `DATEV_Belege_2026-03.zip`. */
 export const belegbilderFilename = (labelArg) => `DATEV_Belege_${labelArg}.zip`;
+/** The name of a document's file in the archive: its GUID and the extension of its format, for example `<GUID>.jpg`. */
+export const belegbildFileName = (guidArg, formatArg = 'pdf') => `${guidArg}.${EXTENSIONS[formatArg]}`;
+const GUID_PATTERN = /^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$/u;
+/** DATEV's `document` of `content`: 1 to 4999 (`Document_v060.xsd`) */
+const MAX_DOCUMENTS = 4999;
+const MAX_DESCRIPTION = 40;
 const escapeXml = (valueArg) => valueArg
     .replace(/&/gu, '&amp;')
     .replace(/</gu, '&lt;')
@@ -9,23 +25,97 @@ const escapeXml = (valueArg) => valueArg
     .replace(/"/gu, '&quot;')
     .replace(/'/gu, '&apos;');
 /**
- * The manifest of the archive, `document.xml`: one `<document>` per PDF,
- * named by its GUID. UTF-8, unlike the Buchungsstapel.
+ * The characters XML 1.0 does not allow (its production `Char`): C0 controls
+ * other than tab, line feed and carriage return, a surrogate not in a pair,
+ * U+FFFE and U+FFFF. Left out of a text before it is cut.
+ */
+const XML_FORBIDDEN = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\uFFFE\uFFFF]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/gu;
+/** The characters XML allows, at most `maxArg` of them (characters, not UTF-16 units), trimmed. */
+const clip = (valueArg, maxArg) => [...valueArg.replace(XML_FORBIDDEN, '').trim()].slice(0, maxArg).join('').trim();
+const pad = (valueArg) => String(valueArg).padStart(2, '0');
+/** `YYYY-MM-DDThh:mm:ss` of the date's UTC clock time, without a zone, as DATEV's `p10048` takes it. */
+const headerDate = (dateArg) => `${dateArg.getUTCFullYear()}-${pad(dateArg.getUTCMonth() + 1)}-${pad(dateArg.getUTCDate())}`
+    + `T${pad(dateArg.getUTCHours())}:${pad(dateArg.getUTCMinutes())}:${pad(dateArg.getUTCSeconds())}`;
+/**
+ * The documents once each: a GUID names one file, so a document linked by
+ * two bookings is listed once, under its first description; a GUID that names
+ * two different files (another format, or other bytes when `sameFileArg` can
+ * tell) is refused.
+ */
+const distinctDocuments = (documentsArg, sameFileArg = () => true) => {
+    const firstOf = new Map();
+    const distinct = [];
+    documentsArg.forEach((documentArg, indexArg) => {
+        const key = documentArg.guid.toUpperCase();
+        const first = firstOf.get(key);
+        if (!first) {
+            firstOf.set(key, { document: documentArg, index: indexArg });
+            distinct.push(documentArg);
+            return;
+        }
+        if ((first.document.format ?? 'pdf') !== (documentArg.format ?? 'pdf') || !sameFileArg(first.document, documentArg)) {
+            throw new CompatibilityError('invalid_documents', `The GUID "${documentArg.guid}" names two different files (documents ${first.index + 1} and ${indexArg + 1}).`);
+        }
+    });
+    return distinct;
+};
+const sameBytes = (leftArg, rightArg) => leftArg.bytes.length === rightArg.bytes.length && leftArg.bytes.every((byteArg, indexArg) => byteArg === rightArg.bytes[indexArg]);
+/** Refuses what DATEV does not take: no document or too many, a GUID not of the RFC 4122 form, a format it does not take. */
+const checkDocuments = (documentsArg) => {
+    if (documentsArg.length === 0) {
+        throw new CompatibilityError('invalid_documents', 'A document package holds at least one document.');
+    }
+    if (documentsArg.length > MAX_DOCUMENTS) {
+        throw new CompatibilityError('invalid_documents', `A document package holds at most ${MAX_DOCUMENTS} documents, not ${documentsArg.length}.`);
+    }
+    documentsArg.forEach((documentArg, indexArg) => {
+        if (!GUID_PATTERN.test(documentArg.guid)) {
+            throw new CompatibilityError('invalid_documents', `The GUID "${documentArg.guid}" of document ${indexArg + 1} is not the 8-4-4-4-12 hexadecimal form DATEV takes.`);
+        }
+        if (documentArg.format !== undefined && !BELEGBILD_FORMATS.includes(documentArg.format)) {
+            throw new CompatibilityError('invalid_documents', `Document ${indexArg + 1} is in the format "${String(documentArg.format)}", which a DATEV Document-Package does not take.`);
+        }
+    });
+};
+/**
+ * The manifest of the archive, `document.xml` after DATEV's `Document_v060.xsd`:
+ * one `<document>` per file, named by its GUID, with its description and one
+ * `File` extension. A GUID listed twice for the same format is one document;
+ * characters XML 1.0 does not allow are left out of the texts. UTF-8, unlike
+ * the Buchungsstapel. Refuses, as a `CompatibilityError` `invalid_documents`,
+ * what DATEV would refuse.
  */
-export const buildDocumentXml = (documentsArg) => {
-    const lines = ['<?xml version="1.0" encoding="UTF-8"?>', '<archive>', '  <content>'];
-    for (const document of documentsArg) {
-        lines.push(`    <document guid="${escapeXml(document.guid)}">`, '      <extension>PDF</extension>', `      <filename>${escapeXml(document.guid)}.pdf</filename>`, '      <beleg_type>1</beleg_type>', ...(document.description ? [`      <description>${escapeXml(document.description)}</description>`] : []), '    </document>');
+export const buildDocumentXml = (documentsArg, archiveArg) => {
+    checkDocuments(documentsArg);
+    const documents = distinctDocuments(documentsArg);
+    const generatingSystem = archiveArg.generatingSystem === undefined ? '' : clip(archiveArg.generatingSystem, MAX_DESCRIPTION);
+    const lines = [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<archive xmlns="http://xml.datev.de/bedi/tps/document/v06.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"'
+            + ' xsi:schemaLocation="http://xml.datev.de/bedi/tps/document/v06.0 Document_v060.xsd" version="6.0"'
+            + `${generatingSystem ? ` generatingSystem="${escapeXml(generatingSystem)}"` : ''}>`,
+        '  <header>',
+        `    <date>${headerDate(archiveArg.createdAt)}</date>`,
+        '  </header>',
+        '  <content>',
+    ];
+    for (const document of documents) {
+        const description = clip(document.description, MAX_DESCRIPTION);
+        lines.push(`    <document guid="${escapeXml(document.guid)}">`, ...(description ? [`      <description>${escapeXml(description)}</description>`] : []), `      <extension xsi:type="File" name="${escapeXml(belegbildFileName(document.guid, document.format))}"/>`, '    </document>');
     }
     lines.push('  </content>', '</archive>', '');
     return lines.join('\n');
 };
-/** `document.xml` and one `<GUID>.pdf` per document, as one ZIP. */
-export const createBelegbilderZip = async (entriesArg) => {
+/** `document.xml` and each document's file under its name (`belegbildFileName`), as one ZIP: a DATEV Document-Package. */
+export const createBelegbilderZip = async (entriesArg, archiveArg) => {
+    checkDocuments(entriesArg);
+    // one file per GUID: the same document linked by two bookings once, one GUID for two different files refused
+    const entries = distinctDocuments(entriesArg, sameBytes);
+    const manifest = buildDocumentXml(entries, archiveArg);
     const zipTools = new plugins.smartarchiveZip.ZipTools();
     return zipTools.createZip([
-        { archivePath: 'document.xml', content: buildDocumentXml(entriesArg) },
-        ...entriesArg.map((entryArg) => ({ archivePath: `${entryArg.guid}.pdf`, content: entryArg.bytes })),
+        { archivePath: 'document.xml', content: manifest },
+        ...entries.map((entryArg) => ({ archivePath: belegbildFileName(entryArg.guid, entryArg.format), content: entryArg.bytes })),
     ]);
 };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9iZWxlZ2JpbGRlci9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGNBQWMsQ0FBQztBQWF4QyxNQUFNLENBQUMsTUFBTSx3QkFBd0IsR0FBRyxpQkFBaUIsQ0FBQztBQUUxRCwwRUFBMEU7QUFDMUUsTUFBTSxDQUFDLE1BQU0sbUJBQW1CLEdBQUcsQ0FBQyxRQUFnQixFQUFVLEVBQUUsQ0FBQyxnQkFBZ0IsUUFBUSxNQUFNLENBQUM7QUFFaEcsTUFBTSxTQUFTLEdBQUcsQ0FBQyxRQUFnQixFQUFVLEVBQUUsQ0FDN0MsUUFBUTtLQUNMLE9BQU8sQ0FBQyxLQUFLLEVBQUUsT0FBTyxDQUFDO0tBQ3ZCLE9BQU8sQ0FBQyxLQUFLLEVBQUUsTUFBTSxDQUFDO0tBQ3RCLE9BQU8sQ0FBQyxLQUFLLEVBQUUsTUFBTSxDQUFDO0tBQ3RCLE9BQU8sQ0FBQyxLQUFLLEVBQUUsUUFBUSxDQUFDO0tBQ3hCLE9BQU8sQ0FBQyxLQUFLLEVBQUUsUUFBUSxDQUFDLENBQUM7QUFFOUI7OztHQUdHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sZ0JBQWdCLEdBQUcsQ0FBQyxZQUE2QyxFQUFVLEVBQUU7SUFDeEYsTUFBTSxLQUFLLEdBQUcsQ0FBQyx3Q0FBd0MsRUFBRSxXQUFXLEVBQUUsYUFBYSxDQUFDLENBQUM7SUFDckYsS0FBSyxNQUFNLFFBQVEsSUFBSSxZQUFZLEVBQUUsQ0FBQztRQUNwQyxLQUFLLENBQUMsSUFBSSxDQUNSLHVCQUF1QixTQUFTLENBQUMsUUFBUSxDQUFDLElBQUksQ0FBQyxJQUFJLEVBQ25ELGtDQUFrQyxFQUNsQyxtQkFBbUIsU0FBUyxDQUFDLFFBQVEsQ0FBQyxJQUFJLENBQUMsaUJBQWlCLEVBQzVELGtDQUFrQyxFQUNsQyxHQUFHLENBQUMsUUFBUSxDQUFDLFdBQVcsQ0FBQyxDQUFDLENBQUMsQ0FBQyxzQkFBc0IsU0FBUyxDQUFDLFFBQVEsQ0FBQyxXQUFXLENBQUMsZ0JBQWdCLENBQUMsQ0FBQyxDQUFDLENBQUMsRUFBRSxDQUFDLEVBQ3hHLGlCQUFpQixDQUNsQixDQUFDO0lBQ0osQ0FBQztJQUNELEtBQUssQ0FBQyxJQUFJLENBQUMsY0FBYyxFQUFFLFlBQVksRUFBRSxFQUFFLENBQUMsQ0FBQztJQUM3QyxPQUFPLEtBQUssQ0FBQyxJQUFJLENBQUMsSUFBSSxDQUFDLENBQUM7QUFDMUIsQ0FBQyxDQUFDO0FBRUYsb0VBQW9FO0FBQ3BFLE1BQU0sQ0FBQyxNQUFNLG9CQUFvQixHQUFHLEtBQUssRUFBRSxVQUF3QyxFQUF1QixFQUFFO0lBQzFHLE1BQU0sUUFBUSxHQUFHLElBQUksT0FBTyxDQUFDLGVBQWUsQ0FBQyxRQUFRLEVBQUUsQ0FBQztJQUN4RCxPQUFPLFFBQVEsQ0FBQyxTQUFTLENBQUM7UUFDeEIsRUFBRSxXQUFXLEVBQUUsY0FBYyxFQUFFLE9BQU8sRUFBRSxnQkFBZ0IsQ0FBQyxVQUFVLENBQUMsRUFBRTtRQUN0RSxHQUFHLFVBQVUsQ0FBQyxHQUFHLENBQUMsQ0FBQyxRQUFRLEVBQUUsRUFBRSxDQUFDLENBQUMsRUFBRSxXQUFXLEVBQUUsR0FBRyxRQUFRLENBQUMsSUFBSSxNQUFNLEVBQUUsT0FBTyxFQUFFLFFBQVEsQ0FBQyxLQUFLLEVBQUUsQ0FBQyxDQUFDO0tBQ3BHLENBQUMsQ0FBQztBQUNMLENBQUMsQ0FBQyJ9
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9iZWxlZ2JpbGRlci9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGNBQWMsQ0FBQztBQUN4QyxPQUFPLEVBQUUsa0JBQWtCLEVBQUUsTUFBTSxhQUFhLENBQUM7QUFxQmpELE1BQU0sQ0FBQyxNQUFNLGlCQUFpQixHQUFnQyxDQUFDLEtBQUssRUFBRSxNQUFNLEVBQUUsS0FBSyxFQUFFLEtBQUssRUFBRSxNQUFNLEVBQUUsS0FBSyxDQUFDLENBQUM7QUFFM0csTUFBTSxVQUFVLEdBQStDO0lBQzdELEdBQUcsRUFBRSxLQUFLO0lBQ1YsSUFBSSxFQUFFLEtBQUs7SUFDWCxHQUFHLEVBQUUsS0FBSztJQUNWLEdBQUcsRUFBRSxLQUFLO0lBQ1YsSUFBSSxFQUFFLEtBQUs7SUFDWCxHQUFHLEVBQUUsS0FBSztDQUNYLENBQUM7QUF5QkYsTUFBTSxDQUFDLE1BQU0sd0JBQXdCLEdBQUcsaUJBQWlCLENBQUM7QUFFMUQsMEVBQTBFO0FBQzFFLE1BQU0sQ0FBQyxNQUFNLG1CQUFtQixHQUFHLENBQUMsUUFBZ0IsRUFBVSxFQUFFLENBQUMsZ0JBQWdCLFFBQVEsTUFBTSxDQUFDO0FBRWhHLHdIQUF3SDtBQUN4SCxNQUFNLENBQUMsTUFBTSxpQkFBaUIsR0FBRyxDQUFDLE9BQWUsRUFBRSxZQUE4QixLQUFLLEVBQVUsRUFBRSxDQUFDLEdBQUcsT0FBTyxJQUFJLFVBQVUsQ0FBQyxTQUFTLENBQUMsRUFBRSxDQUFDO0FBRXpJLE1BQU0sWUFBWSxHQUFHLGdGQUFnRixDQUFDO0FBQ3RHLHVFQUF1RTtBQUN2RSxNQUFNLGFBQWEsR0FBRyxJQUFJLENBQUM7QUFDM0IsTUFBTSxlQUFlLEdBQUcsRUFBRSxDQUFDO0FBRTNCLE1BQU0sU0FBUyxHQUFHLENBQUMsUUFBZ0IsRUFBVSxFQUFFLENBQzdDLFFBQVE7S0FDTCxPQUFPLENBQUMsS0FB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

package/dist_ts/error.d.ts

@@ -1,9 +1,10 @@
 /**
  * Why an exchange file could not be written:
  * - `invalid_bookings`: a draft the account policy refuses; the message names it;
- * - `export_failed`: the conversion into rows failed.
+ * - `export_failed`: the conversion into rows failed;
+ * - `invalid_documents`: a document of a document-image archive DATEV does not take (its GUID, its format), or none.
  */
-export type TCompatibilityErrorCode = 'invalid_bookings' | 'export_failed';
+export type TCompatibilityErrorCode = 'invalid_bookings' | 'export_failed' | 'invalid_documents';
 export declare class CompatibilityError extends Error {
     readonly code: TCompatibilityErrorCode;
     constructor(codeArg: TCompatibilityErrorCode, messageArg: string);

package/dist_ts/error.js

@@ -5,4 +5,4 @@ export class CompatibilityError extends Error {
         this.code = codeArg;
     }
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXJyb3IuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9lcnJvci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFPQSxNQUFNLE9BQU8sa0JBQW1CLFNBQVEsS0FBSztJQUczQyxZQUFZLE9BQWdDLEVBQUUsVUFBa0I7UUFDOUQsS0FBSyxDQUFDLFVBQVUsQ0FBQyxDQUFDO1FBQ2xCLElBQUksQ0FBQyxJQUFJLEdBQUcsb0JBQW9CLENBQUM7UUFDakMsSUFBSSxDQUFDLElBQUksR0FBRyxPQUFPLENBQUM7SUFDdEIsQ0FBQztDQUNGIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXJyb3IuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9lcnJvci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFRQSxNQUFNLE9BQU8sa0JBQW1CLFNBQVEsS0FBSztJQUczQyxZQUFZLE9BQWdDLEVBQUUsVUFBa0I7UUFDOUQsS0FBSyxDQUFDLFVBQVUsQ0FBQyxDQUFDO1FBQ2xCLElBQUksQ0FBQyxJQUFJLEdBQUcsb0JBQW9CLENBQUM7UUFDakMsSUFBSSxDQUFDLElBQUksR0FBRyxPQUFPLENBQUM7SUFDdEIsQ0FBQztDQUNGIn0=

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fin.cx/compatibility",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "private": false,
   "description": "Exchange formats of third-party accounting systems: the EXTF Buchungsstapel in Windows-1252 on the rows of @fin.cx/skr, and the document-image archive (document.xml and ZIP)",
   "main": "dist_ts/index.js",

package/readme.md

@@ -3,7 +3,7 @@
 Exchange formats of third-party accounting systems: the files a German tax advisor's system imports. The package's name carries no vendor's name; the formats and files keep the names the importing system expects (EXTF, `DATEV_Belege_<label>.zip`, the Datev field names in `@fin.cx/skr`'s rows). Two formats, each on its own entry point:
 
 - `@fin.cx/compatibility/extf`: the **EXTF Buchungsstapel**. The rows and the text come from `@fin.cx/skr` (`journalDraftsToDatevRows`, `writeExtfBuchungsstapel`); this module checks the drafts, writes the file in Windows-1252 and says which characters the encoding could not hold.
-- `@fin.cx/compatibility/belegbilder`: the **document-image archive**, a `document.xml` manifest plus one `<GUID>.pdf` per document, as one ZIP, linked to the bookings through the GUID in their Beleglink (field 20).
+- `@fin.cx/compatibility/belegbilder`: the **document-image archive**, a DATEV Document-Package: `document.xml` after DATEV's `Document_v060.xsd` plus one `<GUID>.<extension>` per document (a PDF or a picture), as one ZIP, linked to the bookings through the GUID in their Beleglink (field 20, `BEDI "GUID"`).
 
 It reads no clock, keeps no state and writes nothing anywhere: files go back to the caller as bytes.
 
@@ -49,15 +49,31 @@ file.replacedCharacters; // [{ offset, character: 'ő', row: 1, field: 14 }, …
 
 - **A draft the account policy refuses** throws `CompatibilityError` with code `invalid_bookings` and a message naming the draft.
 - **A failed conversion** throws code `export_failed`.
+- **A document-image archive DATEV would not take** (no document, a GUID of another form, a format it does not take) throws code `invalid_documents`.
 - **`differingBookingCount(left, right)`** counts the rows two Stapel of one period do not share. It compares each booking's day, amount, side, accounts, BU key and Belegfeld 1, as a multiset, and ignores wording and document links.
 
 ```typescript
 import { belegbilder } from '@fin.cx/compatibility';
 
-const zip = await belegbilder.createBelegbilderZip([{ guid, description: 'Rechnung 7', bytes: pdfBytes }]);
+const zip = await belegbilder.createBelegbilderZip(
+  [
+    { guid, description: 'Rechnung 7', bytes: pdfBytes },
+    { guid: photoGuid, description: 'Kassenbon', bytes: jpegBytes, format: 'jpeg' },
+  ],
+  { createdAt: new Date(), generatingSystem: 'My app' },
+);
 // served as belegbilder.BELEGBILDER_CONTENT_TYPE under belegbilder.belegbilderFilename('2026-03')
 ```
 
+The archive is what DATEV's XML-Schnittstelle online takes as a Document-Package (developer.datev.de, "DATEV XML interface online", format specification and XSD files, read 2026-09-28):
+
+- `document.xml` in the namespace `http://xml.datev.de/bedi/tps/document/v06.0`, `version="6.0"`, with the header's `date` (`createdAt`'s UTC clock time without a zone, as the Buchungsstapel header writes its own; the package reads no clock) and, when given, `generatingSystem` (up to 40 characters).
+- One `<document guid="…">` per entry, its `description` cut to DATEV's 40 characters (none when empty), and one `<extension xsi:type="File" name="<GUID>.<extension>"/>`. The GUID is what DATEV Unternehmen online files the document under and what the Beleglink names; it must have the RFC 4122 form `8-4-4-4-12` hexadecimal digits.
+- `format` is `pdf` (the default), `jpeg`, `png`, `gif`, `tiff` or `bmp` (`BELEGBILD_FORMATS`), written as `.pdf`, `.jpg`, `.png`, `.gif`, `.tif`, `.bmp` (`belegbildFileName`). DATEV takes these among its File types (PDF, XML, TIF, TIFF, BMP, CSV, DOC, DOCX, GIF, JPEG, JPG, ODS, ODT, PKCS7, PNG, RTF, TXT, XLS, XLSX); it does not take WebP, AVIF or HEIC, so a picture in one of them must be converted by the caller first.
+- One file per GUID: a document listed twice (the same document linked by two bookings: the same GUID, format and bytes) is in the archive once, under its first description.
+- Characters XML 1.0 does not allow (C0 controls other than tab, line feed and carriage return, a surrogate not in a pair, U+FFFE, U+FFFF) are left out of a description and of `generatingSystem` before they are cut.
+- Refused with `CompatibilityError` `invalid_documents`: no document, more than 4999 (the schema's bound), a GUID of another form, a format outside `BELEGBILD_FORMATS`, one GUID for two different files (another format, or other bytes).
+
 ## Windows-1252
 
 `encodeWindows1252(text)` follows the WHATWG Encoding Standard. Bytes 0x00–0x7F and 0xA0–0xFF are the code points of the same number, and 0x80–0x9F carry the 27 characters € ‚ ƒ „ … † ‡ ˆ ‰ Š ‹ Œ Ž ‘ ’ “ ” • – — ˜ ™ š › œ ž Ÿ.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@fin.cx/compatibility',
-  version: '2.0.0',
+  version: '3.0.0',
   description: 'Exchange formats of third-party accounting systems: the EXTF Buchungsstapel in Windows-1252 on the rows of @fin.cx/skr, and the document-image archive (document.xml and ZIP)'
 }

package/ts/belegbilder/index.ts

@@ -1,21 +1,72 @@
 import * as plugins from './plugins.js';
+import { CompatibilityError } from '../error.js';
 
-/** A document image of the archive, linked to its bookings through the GUID in their Beleglink (field 20). */
+/*
+ * The document-image archive is a DATEV Document-Package of the DATEV
+ * XML-Schnittstelle online: a ZIP of `document.xml`, written after DATEV's
+ * schema `Document_v060.xsd` (namespace `http://xml.datev.de/bedi/tps/document/v06.0`),
+ * and the files it names. Source: developer.datev.de, "DATEV XML interface
+ * online", format specification and XSD files (read 2026-09-28).
+ * - Each `<document>` carries its GUID (`guid`, RFC 4122, `[0-9A-F]{8}-…-[0-9A-F]{12}`),
+ *   under which DATEV Unternehmen online files the document; a booking's
+ *   Beleglink (EXTF field 20, `BEDI "GUID"`) names it.
+ * - Its file is an `<extension xsi:type="File" name="…"/>`. DATEV takes as a
+ *   File: PDF, XML, TIF, TIFF, BMP, CSV, DOC, DOCX, GIF, JPEG, JPG, ODS, ODT,
+ *   PKCS7, PNG, RTF, TXT, XLS, XLSX; file names in ASCII (the GUID is).
+ * - The header's `date` is a date-time without a zone (`.+T[^Z+-]+`);
+ *   a document's `description` has 1 to 40 characters.
+ */
+
+/** The formats a document image can have here: PDF and the picture formats DATEV takes as a File (not WebP, AVIF or HEIC). */
+export type TBelegbildFormat = 'pdf' | 'jpeg' | 'png' | 'gif' | 'tiff' | 'bmp';
+
+export const BELEGBILD_FORMATS: readonly TBelegbildFormat[] = ['pdf', 'jpeg', 'png', 'gif', 'tiff', 'bmp'];
+
+const EXTENSIONS: Readonly<Record<TBelegbildFormat, string>> = {
+  pdf: 'pdf',
+  jpeg: 'jpg',
+  png: 'png',
+  gif: 'gif',
+  tiff: 'tif',
+  bmp: 'bmp',
+};
+
+/** A document of the archive, linked to its bookings through the GUID in their Beleglink (field 20). */
 export interface IBelegbilderDocument {
+  /** RFC 4122, `8-4-4-4-12` hexadecimal digits, as DATEV takes it */
   guid: string;
+  /** cut to DATEV's 40 characters; empty, none is written */
   description: string;
+  /** what the file is; a PDF when absent */
+  format?: TBelegbildFormat;
 }
 
 export interface IBelegbilderEntry extends IBelegbilderDocument {
-  /** the document as PDF */
+  /** the file as it is: the PDF, or the picture in `format` */
   bytes: Uint8Array;
 }
 
+/** What the archive says of itself. */
+export interface IBelegbilderArchive {
+  /** when the archive was written (DATEV's header `date`, required); its UTC clock time is written, as the Buchungsstapel header writes its own. The package reads no clock. */
+  createdAt: Date;
+  /** the software that wrote it (DATEV's `generatingSystem`, up to 40 characters) */
+  generatingSystem?: string;
+}
+
 export const BELEGBILDER_CONTENT_TYPE = 'application/zip';
 
 /** `DATEV_Belege_<label>.zip`, for example `DATEV_Belege_2026-03.zip`. */
 export const belegbilderFilename = (labelArg: string): string => `DATEV_Belege_${labelArg}.zip`;
 
+/** The name of a document's file in the archive: its GUID and the extension of its format, for example `<GUID>.jpg`. */
+export const belegbildFileName = (guidArg: string, formatArg: TBelegbildFormat = 'pdf'): string => `${guidArg}.${EXTENSIONS[formatArg]}`;
+
+const GUID_PATTERN = /^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$/u;
+/** DATEV's `document` of `content`: 1 to 4999 (`Document_v060.xsd`) */
+const MAX_DOCUMENTS = 4999;
+const MAX_DESCRIPTION = 40;
+
 const escapeXml = (valueArg: string): string =>
   valueArg
     .replace(/&/gu, '&amp;')
@@ -25,18 +76,98 @@ const escapeXml = (valueArg: string): string =>
     .replace(/'/gu, '&apos;');
 
 /**
- * The manifest of the archive, `document.xml`: one `<document>` per PDF,
- * named by its GUID. UTF-8, unlike the Buchungsstapel.
+ * The characters XML 1.0 does not allow (its production `Char`): C0 controls
+ * other than tab, line feed and carriage return, a surrogate not in a pair,
+ * U+FFFE and U+FFFF. Left out of a text before it is cut.
+ */
+const XML_FORBIDDEN = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\uFFFE\uFFFF]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/gu;
+
+/** The characters XML allows, at most `maxArg` of them (characters, not UTF-16 units), trimmed. */
+const clip = (valueArg: string, maxArg: number): string => [...valueArg.replace(XML_FORBIDDEN, '').trim()].slice(0, maxArg).join('').trim();
+
+const pad = (valueArg: number): string => String(valueArg).padStart(2, '0');
+
+/** `YYYY-MM-DDThh:mm:ss` of the date's UTC clock time, without a zone, as DATEV's `p10048` takes it. */
+const headerDate = (dateArg: Date): string =>
+  `${dateArg.getUTCFullYear()}-${pad(dateArg.getUTCMonth() + 1)}-${pad(dateArg.getUTCDate())}`
+  + `T${pad(dateArg.getUTCHours())}:${pad(dateArg.getUTCMinutes())}:${pad(dateArg.getUTCSeconds())}`;
+
+/**
+ * The documents once each: a GUID names one file, so a document linked by
+ * two bookings is listed once, under its first description; a GUID that names
+ * two different files (another format, or other bytes when `sameFileArg` can
+ * tell) is refused.
+ */
+const distinctDocuments = <TDocument extends IBelegbilderDocument>(
+  documentsArg: readonly TDocument[],
+  sameFileArg: (leftArg: TDocument, rightArg: TDocument) => boolean = () => true,
+): TDocument[] => {
+  const firstOf = new Map<string, { document: TDocument; index: number }>();
+  const distinct: TDocument[] = [];
+  documentsArg.forEach((documentArg, indexArg) => {
+    const key = documentArg.guid.toUpperCase();
+    const first = firstOf.get(key);
+    if (!first) {
+      firstOf.set(key, { document: documentArg, index: indexArg });
+      distinct.push(documentArg);
+      return;
+    }
+    if ((first.document.format ?? 'pdf') !== (documentArg.format ?? 'pdf') || !sameFileArg(first.document, documentArg)) {
+      throw new CompatibilityError('invalid_documents', `The GUID "${documentArg.guid}" names two different files (documents ${first.index + 1} and ${indexArg + 1}).`);
+    }
+  });
+  return distinct;
+};
+
+const sameBytes = (leftArg: IBelegbilderEntry, rightArg: IBelegbilderEntry): boolean =>
+  leftArg.bytes.length === rightArg.bytes.length && leftArg.bytes.every((byteArg, indexArg) => byteArg === rightArg.bytes[indexArg]);
+
+/** Refuses what DATEV does not take: no document or too many, a GUID not of the RFC 4122 form, a format it does not take. */
+const checkDocuments = (documentsArg: readonly IBelegbilderDocument[]): void => {
+  if (documentsArg.length === 0) {
+    throw new CompatibilityError('invalid_documents', 'A document package holds at least one document.');
+  }
+  if (documentsArg.length > MAX_DOCUMENTS) {
+    throw new CompatibilityError('invalid_documents', `A document package holds at most ${MAX_DOCUMENTS} documents, not ${documentsArg.length}.`);
+  }
+  documentsArg.forEach((documentArg, indexArg) => {
+    if (!GUID_PATTERN.test(documentArg.guid)) {
+      throw new CompatibilityError('invalid_documents', `The GUID "${documentArg.guid}" of document ${indexArg + 1} is not the 8-4-4-4-12 hexadecimal form DATEV takes.`);
+    }
+    if (documentArg.format !== undefined && !BELEGBILD_FORMATS.includes(documentArg.format)) {
+      throw new CompatibilityError('invalid_documents', `Document ${indexArg + 1} is in the format "${String(documentArg.format)}", which a DATEV Document-Package does not take.`);
+    }
+  });
+};
+
+/**
+ * The manifest of the archive, `document.xml` after DATEV's `Document_v060.xsd`:
+ * one `<document>` per file, named by its GUID, with its description and one
+ * `File` extension. A GUID listed twice for the same format is one document;
+ * characters XML 1.0 does not allow are left out of the texts. UTF-8, unlike
+ * the Buchungsstapel. Refuses, as a `CompatibilityError` `invalid_documents`,
+ * what DATEV would refuse.
  */
-export const buildDocumentXml = (documentsArg: readonly IBelegbilderDocument[]): string => {
-  const lines = ['<?xml version="1.0" encoding="UTF-8"?>', '<archive>', '  <content>'];
-  for (const document of documentsArg) {
+export const buildDocumentXml = (documentsArg: readonly IBelegbilderDocument[], archiveArg: IBelegbilderArchive): string => {
+  checkDocuments(documentsArg);
+  const documents = distinctDocuments(documentsArg);
+  const generatingSystem = archiveArg.generatingSystem === undefined ? '' : clip(archiveArg.generatingSystem, MAX_DESCRIPTION);
+  const lines = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<archive xmlns="http://xml.datev.de/bedi/tps/document/v06.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"'
+      + ' xsi:schemaLocation="http://xml.datev.de/bedi/tps/document/v06.0 Document_v060.xsd" version="6.0"'
+      + `${generatingSystem ? ` generatingSystem="${escapeXml(generatingSystem)}"` : ''}>`,
+    '  <header>',
+    `    <date>${headerDate(archiveArg.createdAt)}</date>`,
+    '  </header>',
+    '  <content>',
+  ];
+  for (const document of documents) {
+    const description = clip(document.description, MAX_DESCRIPTION);
     lines.push(
       `    <document guid="${escapeXml(document.guid)}">`,
-      '      <extension>PDF</extension>',
-      `      <filename>${escapeXml(document.guid)}.pdf</filename>`,
-      '      <beleg_type>1</beleg_type>',
-      ...(document.description ? [`      <description>${escapeXml(document.description)}</description>`] : []),
+      ...(description ? [`      <description>${escapeXml(description)}</description>`] : []),
+      `      <extension xsi:type="File" name="${escapeXml(belegbildFileName(document.guid, document.format))}"/>`,
       '    </document>',
     );
   }
@@ -44,11 +175,15 @@ export const buildDocumentXml = (documentsArg: readonly IBelegbilderDocument[]):
   return lines.join('\n');
 };
 
-/** `document.xml` and one `<GUID>.pdf` per document, as one ZIP. */
-export const createBelegbilderZip = async (entriesArg: readonly IBelegbilderEntry[]): Promise<Uint8Array> => {
+/** `document.xml` and each document's file under its name (`belegbildFileName`), as one ZIP: a DATEV Document-Package. */
+export const createBelegbilderZip = async (entriesArg: readonly IBelegbilderEntry[], archiveArg: IBelegbilderArchive): Promise<Uint8Array> => {
+  checkDocuments(entriesArg);
+  // one file per GUID: the same document linked by two bookings once, one GUID for two different files refused
+  const entries = distinctDocuments(entriesArg, sameBytes);
+  const manifest = buildDocumentXml(entries, archiveArg);
   const zipTools = new plugins.smartarchiveZip.ZipTools();
   return zipTools.createZip([
-    { archivePath: 'document.xml', content: buildDocumentXml(entriesArg) },
-    ...entriesArg.map((entryArg) => ({ archivePath: `${entryArg.guid}.pdf`, content: entryArg.bytes })),
+    { archivePath: 'document.xml', content: manifest },
+    ...entries.map((entryArg) => ({ archivePath: belegbildFileName(entryArg.guid, entryArg.format), content: entryArg.bytes })),
   ]);
 };

package/ts/error.ts

@@ -1,9 +1,10 @@
 /**
  * Why an exchange file could not be written:
  * - `invalid_bookings`: a draft the account policy refuses; the message names it;
- * - `export_failed`: the conversion into rows failed.
+ * - `export_failed`: the conversion into rows failed;
+ * - `invalid_documents`: a document of a document-image archive DATEV does not take (its GUID, its format), or none.
  */
-export type TCompatibilityErrorCode = 'invalid_bookings' | 'export_failed';
+export type TCompatibilityErrorCode = 'invalid_bookings' | 'export_failed' | 'invalid_documents';
 
 export class CompatibilityError extends Error {
   public readonly code: TCompatibilityErrorCode;