@lpdfio/lpdf 0.30.0 → 0.31.0

package/dist/browser.js

@@ -11,10 +11,17 @@ var LpdfEngine = class {
     wasm.__wbg_lpdfengine_free(ptr, 0);
   }
   /**
-   * Remove any previously configured encryption.
+   * Register the bytes of a file a document carries, for the `<file>` of its `<attachments>` whose `ref`, or with
+   * no ref whose name, is `name`. The PDF carries them as they are.
+   * @param {string} name
+   * @param {Uint8Array} bytes
    */
-  clear_encryption() {
-    wasm.lpdfengine_clear_encryption(this.__wbg_ptr);
+  load_file(name, bytes) {
+    const ptr0 = passStringToWasm0(name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passArray8ToWasm0(bytes, wasm.__wbindgen_malloc);
+    const len1 = WASM_VECTOR_LEN;
+    wasm.lpdfengine_load_file(this.__wbg_ptr, ptr0, len0, ptr1, len1);
   }
   /**
    * Register raw font bytes (TTF/OTF) for a custom font name.
@@ -97,22 +104,38 @@ var LpdfEngine = class {
    * `json_data` is an optional JSON string used to resolve `data-*`
    * attributes in the template.  Pass `None` (or `null` / `undefined` from
    * JavaScript) to render the template with its inline fallback content.
+   *
+   * The rest is for a document that asks for encryption in its `<output>`, which sets the cipher and
+   * the permissions: the passwords, which the template never holds, and `entropy`, at least 32 random
+   * bytes from the host's secure generator for AES-256. A document that asks for encryption needs an
+   * owner password, or `skip_encryption` to render it unencrypted, as a preview does; passwords for a
+   * document that doesn't ask for it are an error, and so are passwords with `skip_encryption`.
    * @param {string} xml
-   * @param {string | null} [json_data]
+   * @param {string | null | undefined} json_data
+   * @param {string | null | undefined} user_password
+   * @param {string | null | undefined} owner_password
+   * @param {boolean} skip_encryption
+   * @param {Uint8Array} entropy
    * @returns {Uint8Array}
    */
-  render_pdf(xml, json_data) {
+  render_pdf(xml, json_data, user_password, owner_password, skip_encryption, entropy) {
     const ptr0 = passStringToWasm0(xml, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
     const len0 = WASM_VECTOR_LEN;
     var ptr1 = isLikeNone(json_data) ? 0 : passStringToWasm0(json_data, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
     var len1 = WASM_VECTOR_LEN;
-    const ret = wasm.lpdfengine_render_pdf(this.__wbg_ptr, ptr0, len0, ptr1, len1);
+    var ptr2 = isLikeNone(user_password) ? 0 : passStringToWasm0(user_password, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    var len2 = WASM_VECTOR_LEN;
+    var ptr3 = isLikeNone(owner_password) ? 0 : passStringToWasm0(owner_password, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    var len3 = WASM_VECTOR_LEN;
+    const ptr4 = passArray8ToWasm0(entropy, wasm.__wbindgen_malloc);
+    const len4 = WASM_VECTOR_LEN;
+    const ret = wasm.lpdfengine_render_pdf(this.__wbg_ptr, ptr0, len0, ptr1, len1, ptr2, len2, ptr3, len3, skip_encryption, ptr4, len4);
     if (ret[3]) {
       throw takeFromExternrefTable0(ret[2]);
     }
-    var v3 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+    var v6 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
     wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
-    return v3;
+    return v6;
   }
   /**
    * @param {string} json
@@ -139,23 +162,37 @@ var LpdfEngine = class {
    * when an `LpdfDocument` Kit tree is passed to `renderPdf()`, avoiding an
    * intermediate XML serialisation step. PHP, Python, and .NET adapters also
    * use this entry point.
+   *
+   * The passwords, `skip_encryption` and `entropy` are those of `render_pdf`, for a document whose
+   * `output` asks for encryption.
    * @param {string} json
+   * @param {string | null | undefined} user_password
+   * @param {string | null | undefined} owner_password
+   * @param {boolean} skip_encryption
+   * @param {Uint8Array} entropy
    * @returns {Uint8Array}
    */
-  render_tree_pdf(json) {
+  render_tree_pdf(json, user_password, owner_password, skip_encryption, entropy) {
     const ptr0 = passStringToWasm0(json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.lpdfengine_render_tree_pdf(this.__wbg_ptr, ptr0, len0);
+    var ptr1 = isLikeNone(user_password) ? 0 : passStringToWasm0(user_password, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    var len1 = WASM_VECTOR_LEN;
+    var ptr2 = isLikeNone(owner_password) ? 0 : passStringToWasm0(owner_password, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    var len2 = WASM_VECTOR_LEN;
+    const ptr3 = passArray8ToWasm0(entropy, wasm.__wbindgen_malloc);
+    const len3 = WASM_VECTOR_LEN;
+    const ret = wasm.lpdfengine_render_tree_pdf(this.__wbg_ptr, ptr0, len0, ptr1, len1, ptr2, len2, skip_encryption, ptr3, len3);
     if (ret[3]) {
       throw takeFromExternrefTable0(ret[2]);
     }
-    var v2 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+    var v5 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
     wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
-    return v2;
+    return v5;
   }
   /**
-   * Set an optional ISO 8601 creation timestamp (e.g. `"2024-06-01T12:00:00"`).
-   * When provided, written as `/CreationDate` in the PDF info dictionary.
+   * Set an optional ISO 8601 creation timestamp (e.g. `"2024-06-01T12:00:00"`, `"2024-06-01T12:00:00.000Z"` or
+   * `"2024-06-01T12:00:00+01:00"`). When provided, written as `/CreationDate` in the PDF info dictionary, with
+   * the precision and the time zone it was given in; a value that is not a date makes the render an error.
    * Omitting this keeps builds reproducible (no embedded timestamp).
    * @param {string} iso
    */
@@ -164,42 +201,6 @@ var LpdfEngine = class {
     const len0 = WASM_VECTOR_LEN;
     wasm.lpdfengine_set_created_on(this.__wbg_ptr, ptr0, len0);
   }
-  /**
-   * Configure encryption applied to every subsequent `render_pdf` call.
-   *
-   * `permissions_json` is a JSON object with boolean fields matching the
-   * `Permissions` struct (`print`, `modify`, `copy`, `annotate`, `fill_forms`,
-   * `accessibility`, `assemble`, `print_hq`). Omitted fields default to `true`.
-   *
-   * `algorithm` is `"aes-256"` or `"rc4-128"`. AES-256 needs `entropy`: at least 32
-   * random bytes from the host's secure generator, from which the core cuts the file
-   * key, salts and IVs. RC4-128 ignores it. Fails when the algorithm is unknown or
-   * AES-256 gets too little entropy.
-   *
-   * To apply permissions without an open password, pass an empty `user_password`
-   * and a non-empty `owner_password`.
-   * @param {string} user_password
-   * @param {string} owner_password
-   * @param {string} permissions_json
-   * @param {string} algorithm
-   * @param {Uint8Array} entropy
-   */
-  set_encryption(user_password, owner_password, permissions_json, algorithm, entropy) {
-    const ptr0 = passStringToWasm0(user_password, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-    const len0 = WASM_VECTOR_LEN;
-    const ptr1 = passStringToWasm0(owner_password, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-    const len1 = WASM_VECTOR_LEN;
-    const ptr2 = passStringToWasm0(permissions_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-    const len2 = WASM_VECTOR_LEN;
-    const ptr3 = passStringToWasm0(algorithm, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-    const len3 = WASM_VECTOR_LEN;
-    const ptr4 = passArray8ToWasm0(entropy, wasm.__wbindgen_malloc);
-    const len4 = WASM_VECTOR_LEN;
-    const ret = wasm.lpdfengine_set_encryption(this.__wbg_ptr, ptr0, len0, ptr1, len1, ptr2, len2, ptr3, len3, ptr4, len4);
-    if (ret[1]) {
-      throw takeFromExternrefTable0(ret[0]);
-    }
-  }
   /**
    * Inject glyph advance-width tables for custom fonts.
    *
@@ -420,6 +421,18 @@ async function __wbg_init(module_or_path) {
   return __wbg_finalize_init(instance, module);
 }
 
+// src/_shared.ts
+var ENTROPY_BYTES = 32;
+function encryptionArguments(options, randomBytes) {
+  const hasPassword = options.userPassword !== void 0 || options.ownerPassword !== void 0;
+  return [
+    options.userPassword ?? null,
+    options.ownerPassword ?? null,
+    options.skipEncryption ?? false,
+    hasPassword ? randomBytes(ENTROPY_BYTES) : new Uint8Array(0)
+  ];
+}
+
 // src/constants.ts
 var FieldType = {
   Text: "text",
@@ -446,6 +459,27 @@ var FootnoteCounter = {
   Section: "section",
   Document: "document"
 };
+var Cipher = {
+  Aes256: "aes-256",
+  Rc4128: "rc4-128"
+};
+var Permission = {
+  All: "all",
+  Print: "print",
+  Modify: "modify",
+  Copy: "copy",
+  Annotate: "annotate",
+  FillForms: "fill-forms",
+  Accessibility: "accessibility",
+  Assemble: "assemble"
+};
+var FileRelationship = {
+  Source: "source",
+  Data: "data",
+  Alternative: "alternative",
+  Supplement: "supplement",
+  Unspecified: "unspecified"
+};
 var BuiltinFont = {
   Courier: "Courier",
   CourierBold: "Courier-Bold",
@@ -475,10 +509,14 @@ var NoAttr = null;
 function nowUnix() {
   return BigInt(Math.floor(Date.now() / 1e3));
 }
+function secureRandomBytes(count) {
+  return crypto.getRandomValues(new Uint8Array(count));
+}
 async function initLpdf(wasmSource, licenseKey = "") {
   await __wbg_init(wasmSource);
   const fontMap = /* @__PURE__ */ new Map();
   const imageMap = /* @__PURE__ */ new Map();
+  const fileMap = /* @__PURE__ */ new Map();
   const markdownStyles = /* @__PURE__ */ new Map();
   return {
     loadFont(name, bytes) {
@@ -487,6 +525,9 @@ async function initLpdf(wasmSource, licenseKey = "") {
     loadImage(name, bytes) {
       imageMap.set(name, bytes);
     },
+    loadFile(name, bytes) {
+      fileMap.set(name, bytes);
+    },
     loadMarkdownStyles(src, text) {
       markdownStyles.set(src, text);
     },
@@ -502,38 +543,41 @@ async function initLpdf(wasmSource, licenseKey = "") {
       for (const [name, bytes] of imageMap) {
         engine.load_image(name, bytes);
       }
+      for (const [name, bytes] of fileMap) {
+        engine.load_file(name, bytes);
+      }
       for (const [src, text] of markdownStyles) {
         engine.load_markdown_styles(src, text);
       }
       if (callOptions.createdOn) {
         engine.set_created_on(callOptions.createdOn);
       }
+      const encryption = encryptionArguments(callOptions, secureRandomBytes);
       let pdf;
-      if (typeof input === "string") {
-        const dataJson = callOptions.data != null ? JSON.stringify(callOptions.data) : null;
-        pdf = engine.render_pdf(input, dataJson);
-      } else {
-        const wasmExt = engine;
-        if (typeof wasmExt.render_tree_pdf === "function") {
-          pdf = wasmExt.render_tree_pdf(JSON.stringify(input));
+      try {
+        if (typeof input === "string") {
+          const dataJson = callOptions.data != null ? JSON.stringify(callOptions.data) : null;
+          pdf = engine.render_pdf(input, dataJson, ...encryption);
         } else {
-          const mod = engine;
-          const xml = mod.constructor.kit_to_xml?.(JSON.stringify(input)) ?? "";
-          pdf = engine.render_pdf(xml, null);
+          pdf = engine.render_tree_pdf(JSON.stringify(input), ...encryption);
         }
+      } finally {
+        engine.free();
       }
-      engine.free();
       return pdf;
     }
   };
 }
 export {
   BuiltinFont,
+  Cipher,
   FieldType,
+  FileRelationship,
   FootnoteCounter,
   NoAttr,
   Orientation,
   PageScope,
+  Permission,
   Pin,
   SectionType,
   initLpdf

package/dist/canvas.d.ts

@@ -1,5 +1,6 @@
 import type { RectAttr, CircleAttr, EllipseAttr, LineAttr, PathAttr, TextAtAttr, ImgAtAttr, BarcodeAtAttr, LayerAttr } from './attrs';
 import type { LpdfSpanNode, LpdfCodeSpanNode } from './layout';
+import { type AttrValue } from './_shared';
 /**
  * Builds the `transform` string of a layer. `String(CanvasTransform.rotate(45))` is
  * `matrix(...)`, which a layer's `transform` attribute accepts like `rotate(45)`.
@@ -23,41 +24,41 @@ export declare class CanvasTransform {
 }
 export interface LpdfCanvasRectNode {
     type: 'rect';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
 }
 export interface LpdfCanvasLineNode {
     type: 'line';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
 }
 export interface LpdfCanvasEllipseNode {
     type: 'ellipse';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
 }
 export interface LpdfCanvasCircleNode {
     type: 'circle';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
 }
 export interface LpdfCanvasPathNode {
     type: 'path';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
 }
 export interface LpdfCanvasTextAtNode {
     type: 'text-at';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
     nodes: (string | LpdfSpanNode | LpdfCodeSpanNode)[];
 }
 export interface LpdfCanvasImgAtNode {
     type: 'img-at';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
 }
 export interface LpdfCanvasBarcodeAtNode {
     type: 'barcode-at';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
 }
 export type LpdfCanvasPrimitiveNode = LpdfCanvasRectNode | LpdfCanvasLineNode | LpdfCanvasEllipseNode | LpdfCanvasCircleNode | LpdfCanvasPathNode | LpdfCanvasTextAtNode | LpdfCanvasImgAtNode | LpdfCanvasBarcodeAtNode;
 export interface LpdfCanvasLayerNode {
     type: 'layer';
-    attrs: Record<string, string>;
+    attrs: Record<string, AttrValue>;
     nodes: LpdfCanvasPrimitiveNode[];
 }
 declare function rect(attrs: RectAttr): LpdfCanvasRectNode;

package/dist/constants.d.ts

@@ -33,6 +33,33 @@ export declare const FootnoteCounter: {
     readonly Document: "document";
 };
 export type FootnoteCounter = (typeof FootnoteCounter)[keyof typeof FootnoteCounter];
+/** The values of the `encrypt` attribute of the output: the cipher the PDF is encrypted with. */
+export declare const Cipher: {
+    readonly Aes256: "aes-256";
+    readonly Rc4128: "rc4-128";
+};
+export type Cipher = (typeof Cipher)[keyof typeof Cipher];
+/** The words of the `allow` attribute of the output, separated by spaces: what a reader of an encrypted PDF may do. */
+export declare const Permission: {
+    readonly All: "all";
+    readonly Print: "print";
+    readonly Modify: "modify";
+    readonly Copy: "copy";
+    readonly Annotate: "annotate";
+    readonly FillForms: "fill-forms";
+    readonly Accessibility: "accessibility";
+    readonly Assemble: "assemble";
+};
+export type Permission = (typeof Permission)[keyof typeof Permission];
+/** The values of the `relationship` attribute of a file the PDF carries: how it relates to the document. */
+export declare const FileRelationship: {
+    readonly Source: "source";
+    readonly Data: "data";
+    readonly Alternative: "alternative";
+    readonly Supplement: "supplement";
+    readonly Unspecified: "unspecified";
+};
+export type FileRelationship = (typeof FileRelationship)[keyof typeof FileRelationship];
 /** The values of the `core` attribute of a font: the built-in PDF fonts, which need no file. */
 export declare const BuiltinFont: {
     readonly Courier: "Courier";

package/dist/constants.js

@@ -2,7 +2,7 @@
 // Generated from lpdf.xsd by scripts/gen-sdk-api.mjs.
 // Do not edit: change the schema and run `make gen-sdk-api`.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PageScope = exports.BuiltinFont = exports.FootnoteCounter = exports.SectionType = exports.Orientation = exports.Pin = exports.FieldType = void 0;
+exports.PageScope = exports.BuiltinFont = exports.FileRelationship = exports.Permission = exports.Cipher = exports.FootnoteCounter = exports.SectionType = exports.Orientation = exports.Pin = exports.FieldType = void 0;
 /** The values of the `type` attribute of a field. */
 exports.FieldType = {
     Text: 'text',
@@ -33,6 +33,30 @@ exports.FootnoteCounter = {
     Section: 'section',
     Document: 'document',
 };
+/** The values of the `encrypt` attribute of the output: the cipher the PDF is encrypted with. */
+exports.Cipher = {
+    Aes256: 'aes-256',
+    Rc4128: 'rc4-128',
+};
+/** The words of the `allow` attribute of the output, separated by spaces: what a reader of an encrypted PDF may do. */
+exports.Permission = {
+    All: 'all',
+    Print: 'print',
+    Modify: 'modify',
+    Copy: 'copy',
+    Annotate: 'annotate',
+    FillForms: 'fill-forms',
+    Accessibility: 'accessibility',
+    Assemble: 'assemble',
+};
+/** The values of the `relationship` attribute of a file the PDF carries: how it relates to the document. */
+exports.FileRelationship = {
+    Source: 'source',
+    Data: 'data',
+    Alternative: 'alternative',
+    Supplement: 'supplement',
+    Unspecified: 'unspecified',
+};
 /** The values of the `core` attribute of a font: the built-in PDF fonts, which need no file. */
 exports.BuiltinFont = {
     Courier: 'Courier',

package/dist/engine.d.ts

@@ -1,4 +1,4 @@
-import type { RenderOptions } from './_shared';
+import { type RenderOptions } from './_shared';
 import type { PdfDocument } from './kit';
 /** How a license key stands with this build of the engine. */
 export type LicenseStatus = 'licensed' | 'no_key' | 'expired' | 'version_mismatch' | 'wrong_product' | 'unknown_key' | 'bad_signature' | 'malformed';
@@ -26,43 +26,13 @@ export interface LicenseCheck {
 export declare class LpdfRenderError extends Error {
     constructor(message: string);
 }
-/** PDF permission flags. All flags default to `true` (allowed). */
-export interface EncryptPermissions {
-    print?: boolean;
-    modify?: boolean;
-    copy?: boolean;
-    annotate?: boolean;
-    fill_forms?: boolean;
-    accessibility?: boolean;
-    assemble?: boolean;
-    print_hq?: boolean;
-}
-/**
- * The cipher a PDF is encrypted with. `'aes-256'` is the default. `'rc4-128'` is deprecated by
- * PDF 2.0; use it only for readers that cannot open AES-256.
- */
-export type EncryptAlgorithm = 'aes-256' | 'rc4-128';
-/** Encryption options passed to {@link PdfEngine.setEncryption}. */
-export interface EncryptOptions {
-    /** Open password shown to readers. Empty string = no open password required. */
-    userPassword: string;
-    /** Owner (permissions) password. Required; must be non-empty. */
-    ownerPassword: string;
-    /** Permission flags applied to the document. Omitted flags default to `true`. */
-    permissions?: EncryptPermissions;
-    /**
-     * The cipher. Defaults to `'aes-256'`, which makes every render of the same document differ
-     * in its bytes, since each one gets a fresh random key.
-     */
-    algorithm?: EncryptAlgorithm;
-}
 export declare class PdfEngine {
     private _licenseKey;
     private readonly _fonts;
     private readonly _images;
+    private readonly _files;
     private readonly _markdownStyles;
     private _disposed;
-    private _encrypt;
     constructor();
     /**
      * Set the license key. Returns `this` for chaining.
@@ -90,21 +60,16 @@ export declare class PdfEngine {
      * Call before `render`. Returns `this` for chaining.
      */
     loadImage(name: string, bytes: Uint8Array): this;
+    /**
+     * Register the bytes of a file the document carries, for the `<file>` of its `<attachments>` whose `ref`, or with
+     * no ref whose name, is `name`. The PDF carries them as they are. Call before `render`. Returns `this` for chaining.
+     */
+    loadFile(name: string, bytes: Uint8Array): this;
     /**
      * Register the text of a file of Markdown rules, the root of which is a `<markdown-styles>`, for the `src` that
      * names it, as `<markdown-styles src="…">` does. Call before `render`. Returns `this` for chaining.
      */
     loadMarkdownStyles(src: string, text: string): this;
-    /**
-     * Configure encryption for all subsequent `render` calls: AES-256 unless
-     * `options.algorithm` says `'rc4-128'`. Returns `this` for chaining.
-     */
-    setEncryption(options: EncryptOptions): this;
-    /**
-     * Remove any previously configured encryption.
-     * Returns `this` for chaining.
-     */
-    clearEncryption(): this;
     /**
      * Release held resources. Idempotent. Subsequent `render` / `loadFont`
      * calls after disposal will throw.
@@ -116,6 +81,11 @@ export declare class PdfEngine {
      * their `src`. A file that can't be read is left for the engine to report, naming the `src`.
      */
     private _loadMarkdownStyles;
+    /**
+     * Hand the engine the files the document carries: the ones loaded here, and the ones read from the `src` of a file
+     * that wasn't. A `src` that can't be read is an error that names the file and the path.
+     */
+    private _loadFiles;
     private _throwIfDisposed;
     /**
      * Render an lpdf XML string to PDF bytes (Node.js).