@formfeed/sdk 0.3.11 → 0.3.13

package/types/lib/client.d.cts

@@ -38,6 +38,10 @@ export interface RenderRequest {
     data?: Record<string, unknown>;
     /** Left out, the template decides: PDF, or an image template's `settings.image.format`. */
     output?: OutputFormat;
+    /**
+     * Merged over the template's settings. `{ pdf: { ua: true } }` makes the file a PDF/UA-1 document
+     * and the render carry the validator's verdict as `accessibility`; see `PdfUaOptions`.
+     */
     settings?: Record<string, unknown>;
     filename?: string;
     expires_in?: number | null;
@@ -151,6 +155,102 @@ export interface PostProcessing {
         owner?: string;
         permissions?: PdfPermission[];
     };
+    /**
+     * Makes the PDF a ZUGFeRD / Factur-X e-invoice, built from the `_invoice` block of `data`. `{}`
+     * takes the defaults; `false` switches off what the template's settings declare. Not together
+     * with `password`. Starter plan and above; one unit on top of the render.
+     */
+    einvoice?: EinvoiceOptions | false;
+}
+/** What kind of e-invoice a render makes; every field has a default. */
+export interface EinvoiceOptions {
+    /** `en16931` (default) carries the whole European standard, `basic` the smallest full invoice. */
+    profile?: 'basic' | 'en16931';
+    /** One specification under two names; decides the name and release the render reports. */
+    flavour?: 'factur-x' | 'zugferd';
+    /** `both` stores the XML as a file of its own beside the PDF (`einvoice.xml_url`). */
+    xml?: 'embedded' | 'both';
+    /** What a value of the XML that the PDF does not show does: a warning, or a failed render. */
+    display_check?: 'warn' | 'strict';
+}
+/** One finding of the validator: a rule of the XML, or a clause of PDF/A. */
+export interface EinvoiceMessage {
+    part: 'xml' | 'pdf';
+    severity: 'error' | 'warning';
+    rule: string | null;
+    message: string;
+    /** An XPath into the XML, or the object of the PDF. */
+    location: string | null;
+}
+/** The e-invoice of a render: what was made, what the validator said, what the PDF shows. */
+export interface Einvoice {
+    profile: 'basic' | 'en16931';
+    flavour: 'factur-x' | 'zugferd';
+    /** The release under the flavour's name: Factur-X `1.09` is ZUGFeRD `2.5`. */
+    spec_version: string;
+    /** A signed link to the XML when the render asked for `xml: "both"`; null otherwise. */
+    xml_url: string | null;
+    validation: {
+        valid: boolean;
+        schematron: string;
+        pdfa: string | null;
+        /** At most 50, errors first. */
+        messages: EinvoiceMessage[];
+        truncated?: boolean;
+    } | null;
+    /** The business terms of the XML looked for in the PDF's text, and those it does not show. */
+    display: {
+        checked: string[];
+        missing: string[];
+    } | null;
+}
+/**
+ * `settings.pdf.ua` as an object; `true` is `{ check: 'strict' }`. `strict` fails a render whose
+ * file does not pass validation (422 `pdfua_validation_failed`) and delivers nothing; `report`
+ * delivers the file without the PDF/UA identifier and says so in `accessibility.conformant`.
+ */
+export interface PdfUaOptions {
+    check?: 'strict' | 'report';
+}
+/** One rule of PDF/UA-1 a file failed. */
+export interface AccessibilityFailure {
+    /** Clause and test number of the rule in veraPDF's PDF/UA-1 profile, `7.4.2-1`. */
+    rule: string;
+    /** What in the template the rule is about (`heading-order`, `image-alt`, …), where that is known. */
+    code?: string;
+    /** How many checks of the rule failed. */
+    count: number;
+    /** What to change in the template, else the validator's own description of the rule. */
+    message: string;
+    /** The start tags of the elements concerned, at most five. */
+    elements: string[];
+}
+/** What a reader will stumble over although no rule fails for it. */
+export interface AccessibilityWarning {
+    code: string;
+    count: number;
+    /** Start tags, or the text itself for `running-text` and `generated-text`. */
+    elements: string[];
+}
+/**
+ * What the validator said about a file as PDF/UA-1: its verdict on the machine-checkable rules of
+ * the standard, and no more than that. A passed check does not make a document accessible.
+ */
+export interface Accessibility {
+    standard: 'PDF/UA-1';
+    check: 'strict' | 'report';
+    /** The file passed every rule the validator checks; only then does it carry the PDF/UA identifier. */
+    conformant: boolean;
+    /** The validator and its version, `veraPDF 1.30.2`. */
+    validator: string;
+    rules: {
+        passed: number;
+        failed: number;
+    };
+    /** At most 20. */
+    failures: AccessibilityFailure[];
+    warnings: AccessibilityWarning[];
+    truncated?: boolean;
 }
 /** Where the result of a PDF tool is stored, as for a render. */
 export interface PdfOutputOptions {
@@ -206,6 +306,17 @@ export interface Render {
     deduplicated: boolean;
     /** The copy in the workspace's own bucket; null when none applies. */
     storage: StorageDelivery | null;
+    /**
+     * The e-invoice the render made, with the validator's report; null when it made none. A failed
+     * render keeps it too, which is where it says why. Absent from renders made before the feature.
+     */
+    einvoice?: Einvoice | null;
+    /**
+     * The validator's verdict on the file as PDF/UA-1; null unless the render set `settings.pdf.ua`.
+     * A strict render that failed keeps it too, which is where it names the rules. Absent from
+     * renders made before the feature.
+     */
+    accessibility?: Accessibility | null;
     timings: Record<string, number> | null;
     error: {
         code?: string;

package/types/lib/client.d.ts

@@ -38,6 +38,10 @@ export interface RenderRequest {
     data?: Record<string, unknown>;
     /** Left out, the template decides: PDF, or an image template's `settings.image.format`. */
     output?: OutputFormat;
+    /**
+     * Merged over the template's settings. `{ pdf: { ua: true } }` makes the file a PDF/UA-1 document
+     * and the render carry the validator's verdict as `accessibility`; see `PdfUaOptions`.
+     */
     settings?: Record<string, unknown>;
     filename?: string;
     expires_in?: number | null;
@@ -151,6 +155,102 @@ export interface PostProcessing {
         owner?: string;
         permissions?: PdfPermission[];
     };
+    /**
+     * Makes the PDF a ZUGFeRD / Factur-X e-invoice, built from the `_invoice` block of `data`. `{}`
+     * takes the defaults; `false` switches off what the template's settings declare. Not together
+     * with `password`. Starter plan and above; one unit on top of the render.
+     */
+    einvoice?: EinvoiceOptions | false;
+}
+/** What kind of e-invoice a render makes; every field has a default. */
+export interface EinvoiceOptions {
+    /** `en16931` (default) carries the whole European standard, `basic` the smallest full invoice. */
+    profile?: 'basic' | 'en16931';
+    /** One specification under two names; decides the name and release the render reports. */
+    flavour?: 'factur-x' | 'zugferd';
+    /** `both` stores the XML as a file of its own beside the PDF (`einvoice.xml_url`). */
+    xml?: 'embedded' | 'both';
+    /** What a value of the XML that the PDF does not show does: a warning, or a failed render. */
+    display_check?: 'warn' | 'strict';
+}
+/** One finding of the validator: a rule of the XML, or a clause of PDF/A. */
+export interface EinvoiceMessage {
+    part: 'xml' | 'pdf';
+    severity: 'error' | 'warning';
+    rule: string | null;
+    message: string;
+    /** An XPath into the XML, or the object of the PDF. */
+    location: string | null;
+}
+/** The e-invoice of a render: what was made, what the validator said, what the PDF shows. */
+export interface Einvoice {
+    profile: 'basic' | 'en16931';
+    flavour: 'factur-x' | 'zugferd';
+    /** The release under the flavour's name: Factur-X `1.09` is ZUGFeRD `2.5`. */
+    spec_version: string;
+    /** A signed link to the XML when the render asked for `xml: "both"`; null otherwise. */
+    xml_url: string | null;
+    validation: {
+        valid: boolean;
+        schematron: string;
+        pdfa: string | null;
+        /** At most 50, errors first. */
+        messages: EinvoiceMessage[];
+        truncated?: boolean;
+    } | null;
+    /** The business terms of the XML looked for in the PDF's text, and those it does not show. */
+    display: {
+        checked: string[];
+        missing: string[];
+    } | null;
+}
+/**
+ * `settings.pdf.ua` as an object; `true` is `{ check: 'strict' }`. `strict` fails a render whose
+ * file does not pass validation (422 `pdfua_validation_failed`) and delivers nothing; `report`
+ * delivers the file without the PDF/UA identifier and says so in `accessibility.conformant`.
+ */
+export interface PdfUaOptions {
+    check?: 'strict' | 'report';
+}
+/** One rule of PDF/UA-1 a file failed. */
+export interface AccessibilityFailure {
+    /** Clause and test number of the rule in veraPDF's PDF/UA-1 profile, `7.4.2-1`. */
+    rule: string;
+    /** What in the template the rule is about (`heading-order`, `image-alt`, …), where that is known. */
+    code?: string;
+    /** How many checks of the rule failed. */
+    count: number;
+    /** What to change in the template, else the validator's own description of the rule. */
+    message: string;
+    /** The start tags of the elements concerned, at most five. */
+    elements: string[];
+}
+/** What a reader will stumble over although no rule fails for it. */
+export interface AccessibilityWarning {
+    code: string;
+    count: number;
+    /** Start tags, or the text itself for `running-text` and `generated-text`. */
+    elements: string[];
+}
+/**
+ * What the validator said about a file as PDF/UA-1: its verdict on the machine-checkable rules of
+ * the standard, and no more than that. A passed check does not make a document accessible.
+ */
+export interface Accessibility {
+    standard: 'PDF/UA-1';
+    check: 'strict' | 'report';
+    /** The file passed every rule the validator checks; only then does it carry the PDF/UA identifier. */
+    conformant: boolean;
+    /** The validator and its version, `veraPDF 1.30.2`. */
+    validator: string;
+    rules: {
+        passed: number;
+        failed: number;
+    };
+    /** At most 20. */
+    failures: AccessibilityFailure[];
+    warnings: AccessibilityWarning[];
+    truncated?: boolean;
 }
 /** Where the result of a PDF tool is stored, as for a render. */
 export interface PdfOutputOptions {
@@ -206,6 +306,17 @@ export interface Render {
     deduplicated: boolean;
     /** The copy in the workspace's own bucket; null when none applies. */
     storage: StorageDelivery | null;
+    /**
+     * The e-invoice the render made, with the validator's report; null when it made none. A failed
+     * render keeps it too, which is where it says why. Absent from renders made before the feature.
+     */
+    einvoice?: Einvoice | null;
+    /**
+     * The validator's verdict on the file as PDF/UA-1; null unless the render set `settings.pdf.ua`.
+     * A strict render that failed keeps it too, which is where it names the rules. Absent from
+     * renders made before the feature.
+     */
+    accessibility?: Accessibility | null;
     timings: Record<string, number> | null;
     error: {
         code?: string;