@laminapdf/wasm 0.2.0-alpha.6 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # `@laminapdf/wasm`
 
-Lamina PDF's WebAssembly modules and their [wasm-bindgen](https://github.com/wasm-bindgen/wasm-bindgen) glue. The package is private: use [`@laminapdf/sdk`](../sdk/README.md), which is built on it. This package is its raw layer.
+Lamina PDF's WebAssembly modules and their [wasm-bindgen](https://github.com/wasm-bindgen/wasm-bindgen) glue. Use [`@laminapdf/sdk`](../sdk/README.md), which is built on it and gives the modules a typed API: create, read, edit and save PDFs and extract their text. This package is its raw layer.
 
 | Export | File | What it has |
 | --- | --- | --- |

package/dist/lamina_pdf_base.d.ts

@@ -14,11 +14,117 @@ export interface Diagnostic {
 }
 
 
+/**
+ * A change a signature's restriction forbids.
+ */
+export interface ViolationJs {
+    /**
+     * The kind of change.
+     */
+    class: ModificationClass;
+    /**
+     * `docMdp`, `fieldMdp`, `usageRights`, `signedBytes` or `signedWidget`.
+     */
+    restriction: string;
+    /**
+     * The certification's `/P` (1, 2 or 3), for a `docMdp` restriction.
+     */
+    permission?: number;
+    /**
+     * The signature that carries the restriction.
+     */
+    signature: SignatureJs;
+    /**
+     * The form field whose widget a page edit deletes or reshows (its ID), for a
+     * `signedWidget` restriction or a `fieldMdp` one that a page edit breaks.
+     */
+    field?: string;
+}
+
+/**
+ * A conformance claim the document's metadata no longer meets.
+ *
+ * Added in 0.2.0.
+ */
+export type ConformanceWarning = { code: "pdfa-one-author"; authors: number } | { code: "pdfua-title-missing" } | { code: "pdfa-info-mismatch"; keys: MetadataKey[] };
+
 /**
  * A conformance profile.
  */
 export type ProfileInit = "PDF/UA-1" | "PDF/A-2b" | "PDF/A-2u" | "PDF/A-3b";
 
+/**
+ * A document's metadata as one record, read from the Info dictionary and the XMP packet.
+ *
+ * When the two disagree, the values come from the XMP packet in a PDF 2.0 file (ISO 32000-2
+ * §14.3.3 deprecates the Info entries) or a file that claims PDF/A (whose packet is
+ * authoritative, ISO 19005-2 §6.6.2.3.1), and otherwise from the side whose modification date
+ * is newer, Info winning a tie. A field the winning side lacks is taken from the other.
+ * [`disagreements`](DocumentMetadata::disagreements) names the fields where the two differ, so
+ * a properties view can say so.
+ *
+ * Added in 0.2.0.
+ */
+export interface DocumentMetadata {
+    /**
+     * The title.
+     */
+    title?: string;
+    /**
+     * The authors, in order (Info's `/Author` split at `;`).
+     */
+    authors: string[];
+    /**
+     * The subject.
+     */
+    subject?: string;
+    /**
+     * The keywords.
+     */
+    keywords?: string;
+    /**
+     * The application the content came from.
+     */
+    creator?: string;
+    /**
+     * The application that wrote the PDF.
+     */
+    producer?: string;
+    /**
+     * The creation date (a PDF date string on the wire).
+     */
+    created?: string;
+    /**
+     * The modification date.
+     */
+    modified?: string;
+    /**
+     * Which side the values come from.
+     */
+    source: MetadataSource;
+    /**
+     * The fields where Info and XMP hold different values.
+     */
+    disagreements: MetadataKey[];
+    /**
+     * What `/Metadata` holds.
+     */
+    packet: PacketStatus;
+    /**
+     * The PDF/A part and conformance the packet claims (`pdfaid:`), e.g. `"2B"`.
+     */
+    pdfa?: string;
+    /**
+     * The PDF/UA part the packet claims (`pdfuaid:part`).
+     */
+    pdfua?: number;
+    /**
+     * In a PDF 2.0 file, the Info entries besides the two dates: deprecated, kept as they
+     * were for older readers, and never written by an edit.
+     */
+    keptInfoKeys: MetadataKey[];
+}
+
 /**
  * A job's progress (`laminapdf::Step::Progress`).
  */
@@ -52,17 +158,56 @@ export interface ProgressJs {
  * ```
  *
  * [ADR 0006]: https://github.com/laudebugs/laminapdf/blob/main/docs/decisions/0006-op-log-and-undo.md
+ *
+ * Added in 0.2.0.
  */
 export interface OpLog {
     v: 1;
     ops: Op[];
 }
 
+/**
+ * A metadata field Lamina PDF keeps in step in the Info dictionary and the XMP packet: what
+ * [`RemoveMetadata`] removes and [`DocumentMetadata::disagreements`] names.
+ *
+ * | Key | Info | XMP |
+ * | --- | --- | --- |
+ * | `title` | `/Title` | `dc:title` |
+ * | `authors` | `/Author` (joined with `; `) | `dc:creator` |
+ * | `subject` | `/Subject` | `dc:description` |
+ * | `keywords` | `/Keywords` | `pdf:Keywords` |
+ * | `creator` | `/Creator` | `xmp:CreatorTool` |
+ * | `producer` | `/Producer` | `pdf:Producer` |
+ * | `created` | `/CreationDate` | `xmp:CreateDate` |
+ * | `modified` | `/ModDate` | `xmp:ModifyDate` |
+ *
+ * Added in 0.2.0.
+ */
+export type MetadataKey = "title" | "authors" | "subject" | "keywords" | "creator" | "producer" | "created" | "modified";
+
 /**
  * A page-label numbering style.
  */
 export type LabelStyleInit = "decimal" | "upperRoman" | "lowerRoman" | "upperLetters" | "lowerLetters";
 
+/**
+ * A signature the planner found.
+ */
+export interface SignatureJs {
+    /**
+     * `approval`, `certification`, `docTimeStamp` or `usageRights`.
+     */
+    kind: string;
+    /**
+     * The signature field's ID, when a field holds it.
+     */
+    field?: string;
+    /**
+     * The 1-based revision the signature closes, when known.
+     */
+    revision?: number;
+}
+
 /**
  * An attached file's options.
  */
@@ -101,8 +246,10 @@ export interface AttachmentInit {
  * ```
  *
  * [ADR 0006]: https://github.com/laudebugs/laminapdf/blob/main/docs/decisions/0006-op-log-and-undo.md
+ *
+ * Added in 0.2.0.
  */
-export type Op = { op: "setInfo"; args: SetInfo } | { op: "rotatePage"; args: RotatePage };
+export type Op = { op: "setInfo"; args: SetInfo } | { op: "rotatePage"; args: RotatePage } | { op: "setMetadata"; args: SetMetadata } | { op: "removeMetadata"; args: RemoveMetadata };
 
 /**
  * Changes to the Info dictionary's text entries. For each field, `None` leaves the entry
@@ -111,6 +258,8 @@ export type Op = { op: "setInfo"; args: SetInfo } | { op: "rotatePage"; args: Ro
  *
  * On the wire an absent field is left alone and `null` clears: `{ "title": "Report",
  * "author": null }`.
+ *
+ * Added in 0.2.0.
  */
 export interface InfoPatch {
     /**
@@ -139,13 +288,75 @@ export interface InfoPatch {
     producer?: string | null;
 }
 
+/**
+ * Changes to the document's metadata. For each field, `None` leaves it alone, `Some(None)`
+ * removes it and `Some(Some(value))` sets it, in Info and XMP alike.
+ *
+ * On the wire an absent field is left alone and `null` removes: `{ "title": "Report",
+ * "authors": ["Ada Lovelace", "Charles Babbage"], "keywords": null }`; dates are PDF date
+ * strings (`"D:20261110093000+01'00'"`).
+ *
+ * ```
+ * use laminapdf_ops::MetadataPatch;
+ *
+ * let patch = MetadataPatch::new().title(Some("Quarterly figures")).authors(&["Ada Lovelace", "Charles Babbage"]);
+ * assert_eq!(patch.authors, Some(Some(vec!["Ada Lovelace".to_owned(), "Charles Babbage".to_owned()])));
+ * assert_eq!(serde_json::to_string(&patch)?, r#"{"title":"Quarterly figures","authors":["Ada Lovelace","Charles Babbage"]}"#);
+ * # Ok::<(), serde_json::Error>(())
+ * ```
+ *
+ * Added in 0.2.0.
+ */
+export interface MetadataPatch {
+    /**
+     * `/Title`, `dc:title`.
+     */
+    title?: string | null;
+    /**
+     * `/Author` (joined with `; `), `dc:creator` (in order). An empty list removes them.
+     */
+    authors?: string[] | null;
+    /**
+     * `/Subject`, `dc:description`.
+     */
+    subject?: string | null;
+    /**
+     * `/Keywords`, `pdf:Keywords`.
+     */
+    keywords?: string | null;
+    /**
+     * `/Creator`, `xmp:CreatorTool`: the application the content came from.
+     */
+    creator?: string | null;
+    /**
+     * `/Producer`, `pdf:Producer`: the application that wrote the PDF.
+     */
+    producer?: string | null;
+    /**
+     * `/CreationDate`, `xmp:CreateDate`.
+     */
+    created?: string | null;
+    /**
+     * `/ModDate`, `xmp:ModifyDate`.
+     */
+    modified?: string | null;
+}
+
 /**
  * Edits the Info dictionary: applies `patch` and, when `at` is given, sets `/ModDate` to it.
+ *
+ * **Deprecated:** use [`SetMetadata`](crate::SetMetadata), which writes authors as a list and
+ * the dates, and edits files whose metadata is in XMP alone. `SetInfo` stays, with its v1 wire
+ * form (`setInfo`) and meaning, so op logs already written still apply (ADR 0006 §6). It now
+ * goes through the same writer, so a document's XMP packet, when it has one, changes with it.
+ * It adds a packet only to a PDF 2.0 file, where the fields other than the dates belong in XMP.
  * The date is part of the op, never read from a clock, so the same op gives the same bytes
  * everywhere (ADR 0006 §1).
  *
  * An Info dictionary written directly in the trailer, or missing, becomes a new indirect
  * object that the trailer's `/Info` points to (the first time the op changes something).
+ *
+ * Added in 0.2.0.
  */
 export interface SetInfo {
     /**
@@ -158,11 +369,106 @@ export interface SetInfo {
     at?: string;
 }
 
+/**
+ * Edits the document's metadata: applies `patch` to the Info dictionary and the XMP packet
+ * together and, when `at` is given, records it as the modification date (`/ModDate`,
+ * `xmp:ModifyDate`) and as `xmp:MetadataDate`, unless the patch sets the modification date
+ * itself. The date is part of the op, never read from a clock (ADR 0006 §1).
+ *
+ * ```
+ * use laminapdf_ops::{MetadataPatch, Op, SetMetadata};
+ *
+ * let op = Op::from(SetMetadata::new(MetadataPatch::new().title(Some("Minutes")), Some("D:20261110093000Z".parse()?)));
+ * assert_eq!(
+ *     serde_json::to_string(&op)?,
+ *     r#"{"op":"setMetadata","args":{"patch":{"title":"Minutes"},"at":"D:20261110093000Z"}}"#
+ * );
+ * # Ok::<(), Box<dyn std::error::Error>>(())
+ * ```
+ *
+ * Added in 0.2.0.
+ */
+export interface SetMetadata {
+    /**
+     * The fields to set or remove.
+     */
+    patch?: MetadataPatch;
+    /**
+     * The modification date the edit writes.
+     */
+    at?: string;
+    /**
+     * Replace an XMP packet that can't be read with a new one, losing whatever it held.
+     * Without it, such a packet makes the op fail with `malformed-xmp`, so nothing is lost
+     * without the user saying so.
+     */
+    replaceMalformed?: boolean;
+}
+
 /**
  * How a destination shows its page (§12.3.2.2).
  */
 export type FitInit = { type: "page" } | { type: "width"; top?: number } | { type: "height"; left?: number } | { type: "xyz"; left?: number; top?: number; zoom?: number } | { type: "rect"; x: number; y: number; width: number; height: number } | { type: "bounds" };
 
+/**
+ * How a save would go (`laminapdf::PlannedSave`).
+ */
+export interface PlannedSaveJs {
+    /**
+     * The mode the save resolves to; absent when it would be refused.
+     */
+    mode?: SaveModeJs;
+    /**
+     * The code the save would be refused with.
+     */
+    refusal?: string;
+    /**
+     * `free`, `appendOnly`, `requiresRewrite` or `conflict`.
+     */
+    constraint: string;
+    /**
+     * Every signature, in the order found.
+     */
+    signatures: SignatureJs[];
+    /**
+     * The certification's `/P` (1, 2 or 3), when the document is certified.
+     */
+    docMdp?: number;
+    /**
+     * Why only a full rewrite is safe: `repairedBase`, `encryptedBase`, `noBase`,
+     * `opRequiresRewrite`.
+     */
+    rewriteReasons: string[];
+    /**
+     * The pending changes a signature's restriction forbids.
+     */
+    violations: ViolationJs[];
+    /**
+     * The signatures the save would invalidate (only with `invalidateSignatures`).
+     */
+    wouldInvalidate: SignatureJs[];
+    /**
+     * Whether the save writes an encrypted document as plaintext.
+     */
+    removesEncryption: boolean;
+    /**
+     * What the save does with the save-time metadata: `none`, `stamp` or `skipped`.
+     */
+    metadata: string;
+    /**
+     * Whether an edit to save rewrote the XMP packet whole.
+     */
+    packetRewritten: boolean;
+    /**
+     * The PDF/A and PDF/UA claims the edited metadata breaks (warnings that never block).
+     */
+    conformanceWarnings: Diagnostic[];
+    /**
+     * The document has no changes.
+     */
+    unchanged: boolean;
+}
+
 /**
  * How a viewer lays pages out.
  */
@@ -370,6 +676,48 @@ export interface SaveOptionsInit {
      * The cross-reference form.
      */
     xref?: XrefJs;
+    /**
+     * When the save happens, as the app's clock reads it: a PDF date (`D:20261110093000Z`)
+     * or an ISO 8601 date-time. A save that writes changes stamps it as the modification and
+     * metadata dates and gives the XMP packet a new instance ID.
+     */
+    metadataDate?: string;
+    /**
+     * The XMP instance ID the save writes, a UUID (`uuid:` optional); without it, one is
+     * derived from the content.
+     */
+    instanceId?: string;
+}
+
+/**
+ * Removes metadata fields from the Info dictionary and the XMP packet; the packet's other
+ * properties stay (J.10).
+ *
+ * The values stay in the file's earlier revisions until a full rewrite: an incremental save
+ * appends the change and keeps the original bytes. When it removed anything, the op's result
+ * says so ([`Applied::still_in_earlier_revisions`](crate::Applied::still_in_earlier_revisions)),
+ * so the caller can offer a full rewrite (on a signed file, the override that removes the
+ * signatures).
+ *
+ * ```
+ * use laminapdf_ops::{MetadataKey, Op, RemoveMetadata};
+ *
+ * let op = Op::from(RemoveMetadata::new(vec![MetadataKey::Authors, MetadataKey::Creator]));
+ * assert_eq!(serde_json::to_string(&op)?, r#"{"op":"removeMetadata","args":{"keys":["authors","creator"]}}"#);
+ * # Ok::<(), serde_json::Error>(())
+ * ```
+ *
+ * Added in 0.2.0.
+ */
+export interface RemoveMetadata {
+    /**
+     * The fields to remove.
+     */
+    keys: MetadataKey[];
+    /**
+     * As [`SetMetadata::replace_malformed`].
+     */
+    replaceMalformed?: boolean;
 }
 
 /**
@@ -384,6 +732,8 @@ export interface SaveOptionsInit {
  * On the wire: `{ "op": "rotatePage", "args": { "page": "p12.0", "rotate": 90 } }`.
  *
  * [ADR 0005]: https://github.com/laudebugs/laminapdf/blob/main/docs/decisions/0005-document-model.md
+ *
+ * Added in 0.2.0.
  */
 export interface RotatePage {
     /**
@@ -479,6 +829,8 @@ export interface MetadataInit {
  * permissions and the document's `SaveConstraint` ([ADR 0007]).
  *
  * [ADR 0007]: https://github.com/laudebugs/laminapdf/blob/main/docs/decisions/0007-save-planner.md
+ *
+ * Added in 0.2.0.
  */
 export type ModificationClass = "metadata" | "formFill" | "annotation" | "signature" | "pageStructure" | "content" | "document";
 
@@ -490,6 +842,15 @@ export interface EditedJs {
      * IDs of the pages whose content or attributes changed.
      */
     touchedPages: string[];
+    /**
+     * A metadata edit rewrote the XMP packet whole (UTF-16, or marked read-only).
+     */
+    packetRewritten: boolean;
+    /**
+     * A metadata edit removed values the file's earlier revisions still hold, which only a
+     * full rewrite drops.
+     */
+    stillInEarlierRevisions: boolean;
     /**
      * Whether the edit changed the document: one that only set values they already had leaves
      * no step to undo.
@@ -535,6 +896,24 @@ export interface SaveReportJs {
      * Whether encryption was removed.
      */
     encryptionRemoved: boolean;
+    /**
+     * Whether the save stamped the save-time metadata (`metadataDate`, `instanceId`).
+     */
+    metadataUpdated: boolean;
+    /**
+     * Whether the options asked for the stamp and the save left it out, because it would have
+     * broken a signature's restriction the saved changes keep.
+     */
+    metadataNotUpdated: boolean;
+    /**
+     * Whether an edit saved here rewrote the XMP packet whole.
+     */
+    packetRewritten: boolean;
+    /**
+     * Whether the save emptied the undo history (a full rewrite, or an incremental save that
+     * freed objects); for a copy, whether adopting it would.
+     */
+    historyCleared: boolean;
 }
 
 /**
@@ -556,11 +935,25 @@ export interface RevertedJs {
     touchedPages: string[];
 }
 
+/**
+ * What the document's `/Metadata` holds.
+ *
+ * Added in 0.2.0.
+ */
+export type PacketStatus = "absent" | "parsed" | "malformed";
+
 /**
  * Where a link or outline item goes.
  */
 export type LinkTargetInit = { type: "uri"; uri: string } | { type: "page"; index: number; fit?: FitInit } | { type: "named"; name: string };
 
+/**
+ * Which side [`DocumentMetadata`]'s values come from.
+ *
+ * Added in 0.2.0.
+ */
+export type MetadataSource = "info" | "xmp";
+
 /**
  * `Limits` with every field optional (ADR 0003 §3; names as in Rust, camelCase).
  */
@@ -715,6 +1108,15 @@ export class WasmDocument {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * Makes `bytes`, the whole output of `saveCopy`, the document's saved file (it rebases onto
+     * them), once they are written where the document lives; `historyCleared` is the copy's
+     * report's.
+     *
+     * # Errors
+     * `nested-transaction`, `saved-not-rebased`; `not-rebased` when `bytes` can't be read.
+     */
+    adoptCopy(bytes: Uint8Array, historyCleared: boolean): void;
     /**
      * Applies an op log (`{ "v": 1, "ops": [ … ] }`) as one transaction.
      *
@@ -745,6 +1147,14 @@ export class WasmDocument {
      * Whether the file is encrypted (it opened with its password, or the empty one).
      */
     isEncrypted(): boolean;
+    /**
+     * The document's metadata, read from Info and XMP together, with the fields where they
+     * disagree.
+     *
+     * # Errors
+     * Reading errors.
+     */
+    metadata(): DocumentMetadata;
     /**
      * Opens a document from its bytes.
      *
@@ -797,6 +1207,13 @@ export class WasmDocument {
      * `page-index-out-of-range`; reading errors.
      */
     page(index: number): WasmPage;
+    /**
+     * How a save with `options` would go, without saving.
+     *
+     * # Errors
+     * `invalid-argument` / `unknown-option` for bad options; reading errors.
+     */
+    plan(options: SaveOptionsInit | undefined): PlannedSaveJs;
     /**
      * Rebases onto `bytes`, the output of a save whose rebase failed (`not-rebased`).
      *
@@ -812,6 +1229,14 @@ export class WasmDocument {
      * As [`WasmDocument::undo`].
      */
     redo(): RevertedJs | undefined;
+    /**
+     * Writes what `save` would and leaves the document as it was: not rebased, its changes
+     * still unsaved, the save-time stamp in the copy only (Save a copy).
+     *
+     * # Errors
+     * As `save`; the document is unchanged either way.
+     */
+    saveCopy(options: SaveOptionsInit | undefined): { bytes: Uint8Array<ArrayBuffer>; report: SaveReportJs };
     /**
      * A save as a job, stepped with a budget of work units (ADR 0028 §3, §4).
      *
@@ -838,6 +1263,13 @@ export class WasmDocument {
      * A cursor over the warnings so far (build warnings first), each as the §1 object.
      */
     warnings(): WasmWarningCursor;
+    /**
+     * The signature restrictions `op` would break if it were applied and saved.
+     *
+     * # Errors
+     * `invalid-argument` for a value that isn't an op; reading errors.
+     */
+    wouldViolate(op: Op): ViolationJs[];
 }
 
 /**
@@ -1205,11 +1637,13 @@ export interface InitOutput {
     readonly wasmbuilder_page: (a: number, b: number, c: number) => number;
     readonly wasmbuilder_pageLabels: (a: number, b: any) => [number, number];
     readonly wasmbuilder_viewerPreferences: (a: number, b: any) => [number, number];
+    readonly wasmdocument_adoptCopy: (a: number, b: number, c: number, d: number) => [number, number];
     readonly wasmdocument_apply: (a: number, b: any) => [number, number, number];
     readonly wasmdocument_applyLog: (a: number, b: number, c: number) => [number, number, number];
     readonly wasmdocument_hasUnsavedChanges: (a: number) => number;
     readonly wasmdocument_info: (a: number) => [number, number, number];
     readonly wasmdocument_isEncrypted: (a: number) => number;
+    readonly wasmdocument_metadata: (a: number) => [number, number, number];
     readonly wasmdocument_openBytes: (a: number, b: number, c: any) => [number, number, number];
     readonly wasmdocument_openSource: (a: number, b: any) => [number, number, number];
     readonly wasmdocument_page: (a: number, b: number) => [number, number, number];
@@ -1217,12 +1651,15 @@ export interface InitOutput {
     readonly wasmdocument_pageCount: (a: number) => [number, number, number];
     readonly wasmdocument_pageInfo: (a: number, b: number) => [number, number, number];
     readonly wasmdocument_pageInfos: (a: number) => [number, number, number];
+    readonly wasmdocument_plan: (a: number, b: any) => [number, number, number];
     readonly wasmdocument_rebase: (a: number, b: number, c: number) => [number, number];
     readonly wasmdocument_redo: (a: number) => [number, number, number];
     readonly wasmdocument_save: (a: number, b: any) => [number, number, number];
+    readonly wasmdocument_saveCopy: (a: number, b: any) => [number, number, number];
     readonly wasmdocument_saveJob: (a: number, b: any) => [number, number, number];
     readonly wasmdocument_undo: (a: number) => [number, number, number];
     readonly wasmdocument_warnings: (a: number) => number;
+    readonly wasmdocument_wouldViolate: (a: number, b: any) => [number, number, number];
     readonly wasmimage_height: (a: number) => number;
     readonly wasmimage_jpeg: (a: number, b: number) => [number, number, number];
     readonly wasmimage_png: (a: number, b: number) => [number, number, number];