@jasy/pdf 1.0.0-alpha.3 → 1.0.0-alpha.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Florian Heuberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -37,7 +37,7 @@ account, no upload, nothing leaves your machine.
 ## You bring the line items. jasy does the rest.
 
 You never compute a total, a VAT breakdown or a rounding again. You hand jasy the line items - it
-**derives** the document totals and the EN-16931 VAT breakdown, spec-correct. That is *why* the
+**derives** the document totals and the EN-16931 VAT breakdown, spec-correct. That is _why_ the
 invoices validate: the amounts are correct **by construction**, so the single biggest class of
 EN-16931 failures (the BR-CO total checks) simply cannot happen.
 
@@ -48,13 +48,23 @@ const { bytes, xml } = await renderZugferd({
   number: "RE-2026-001",
   issueDate: "2026-06-17",
   currency: "EUR",
-  seller: { name: "Northwind Studio GmbH", vatId: "DE123456789",
-            address: { city: "Berlin", postCode: "10115", country: "DE" } },
-  buyer:  { name: "Globex Corporation Ltd",
-            address: { city: "Munich", postCode: "80331", country: "DE" } },
+  seller: {
+    name: "Northwind Studio GmbH",
+    vatId: "DE123456789",
+    address: { city: "Berlin", postCode: "10115", country: "DE" },
+  },
+  buyer: {
+    name: "Globex Corporation Ltd",
+    address: { city: "Munich", postCode: "80331", country: "DE" },
+  },
   lines: [
-    { name: "Brand identity design", quantity: 2, unit: "HUR", netUnitPrice: 100,
-      vat: { category: "S", ratePercent: 19 } },
+    {
+      name: "Brand identity design",
+      quantity: 2,
+      unit: "HUR",
+      netUnitPrice: 100,
+      vat: { category: "S", ratePercent: 19 },
+    },
   ],
 });
 // bytes -> a valid ZUGFeRD PDF/A-3   ·   xml -> the embedded EN-16931 XML
@@ -123,7 +133,7 @@ verify all of it:
 - **Compression.** Content streams and images are FlateDecode-compressed; the spreadsheets `jasy export`
   writes are real `.xlsx` ZIPs we deflate with our own writer and CRC32, zero dependencies.
 - **Real font metrics.** Text is laid out with the Adobe AFM metrics of the standard-14 fonts - kerning
-  and word-wrap are *computed*, not guessed.
+  and word-wrap are _computed_, not guessed.
 - **PDF/A-3, matched not approximated.** The conformance graph is hand-built and **passes veraPDF**, the
   official ISO 19005 validator.
 - **Byte-exact round-trips.** Generate and parse are inverses: `generate → parse → regenerate` reproduces
@@ -135,11 +145,11 @@ verify all of it:
 
 ## Packages
 
-| Package | What it is |
-| --- | --- |
+| Package                                             | What it is                                                                                     |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
 | **[@jasy/zugferd](https://npmx.dev/@jasy/zugferd)** | ZUGFeRD / XRechnung: your data → PDF/A-3 + EN-16931 XML, with local validation. **The prize.** |
-| **[@jasy/cli](https://npmx.dev/@jasy/cli)** | the `jasy` terminal: read · validate · export, headless **and** interactive |
-| **[@jasy/pdf](https://npmx.dev/@jasy/pdf)** | the declarative, Flutter-style PDF layout engine that powers them |
+| **[@jasy/cli](https://npmx.dev/@jasy/cli)**         | the `jasy` terminal: read · validate · export, headless **and** interactive                    |
+| **[@jasy/pdf](https://npmx.dev/@jasy/pdf)**         | the declarative, Flutter-style PDF layout engine that powers them                              |
 
 ---
 
@@ -158,7 +168,7 @@ verify all of it:
 
 jasy targets the documents that matter here: invoices, reports, quotes, datasheets. It is **not** a
 LaTeX / WeasyPrint replacement - no microtypography, hyphenation or bidi, and arbitrary multi-page flow
-of *any* content is still maturing. For e-invoices (a table, totals, a footer) it is complete - they
+of _any_ content is still maturing. For e-invoices (a table, totals, a footer) it is complete - they
 even paginate. We would rather under-promise and over-deliver in the demo above.
 
 > **Status:** young and pre-1.0. The API can still shift between minor versions. Everything shown here

package/dist/api/structure.d.ts

@@ -4,6 +4,8 @@ import { PDFElement } from "../elements/pdf-element.js";
 import { DefaultTextStyleElement } from "../elements/layout/default-text-style-element.js";
 import type { OverflowPolicy } from "../layout/fragmentation.js";
 import { PageSize } from "../constants/page-sizes.js";
+import { type EncryptOptions } from "../crypto/security-handler.js";
+export type { EncryptOptions, Permissions } from "../crypto/security-handler.js";
 import { StackOptions } from "./layout.js";
 import { Insets } from "./insets.js";
 import { TextDefaults } from "./text.js";
@@ -120,6 +122,9 @@ export interface RenderOptions {
     /** What to do when content is taller than a page and cannot break: `"error"` throws (default),
      *  `"warn"` logs and clips, `"ignore"` clips silently. It is always clipped either way. */
     onOverflow?: OverflowPolicy;
+    /** Encrypt the PDF with a password (AES-256, the newest standard). NOT compatible with PDF/A
+     *  (ZUGFeRD invoices) - encrypting one throws, since PDF/A forbids encryption. */
+    encrypt?: EncryptOptions;
 }
 /** Renders a `Document(...)` tree to the raw PDF string. */
 export declare function renderPdf(doc: PDFDocumentElement, options?: RenderOptions): Promise<string>;

package/dist/api/structure.js

@@ -7,6 +7,7 @@ import { Orientation } from "../renderer/pdf-config.js";
 import { PDFDocument } from "../renderer/pdf-document-class.js";
 import { FontStyle } from "../utils/pdf-object-manager.js";
 import { getArrayBuffer } from "../utils/utf8-to-windows1252-encoder.js";
+import { createSecurityHandler } from "../crypto/security-handler.js";
 import { Column } from "./layout.js";
 import { toEdges } from "./insets.js";
 import { toTextStyleOverride } from "./text.js";
@@ -117,6 +118,11 @@ export async function renderPdf(doc, options) {
         ...options?.fonts,
     };
     const attachments = options?.attachments ?? [];
+    // The security handler's key derivation is async (WebCrypto), so build it here, before the sync
+    // PDFDocument constructor wires it into the object manager.
+    const securityHandler = options?.encrypt
+        ? await createSecurityHandler(options.encrypt)
+        : undefined;
     // A throwaway PDFDocument whose build() yields this tree, reusing the engine's standard
     // font registration + config handling (the constructor does both). Custom fonts are
     // registered here, before layout/render, so both the metrics and the backend see them.
@@ -155,6 +161,8 @@ export async function renderPdf(doc, options) {
                 om.setPdfVersion(options.pdfVersion);
             if (options?.documentId)
                 om.enableDocumentId();
+            if (securityHandler)
+                om.setSecurityHandler(securityHandler);
         }
         build() {
             return doc;