@pdfluent/sdk-wasm 1.0.0 → 1.2.0

package/xfa_wasm.d.ts

@@ -1,6 +1,85 @@
 /* tslint:disable */
 /* eslint-disable */
 
+/** A stamp with preset text, size, rotation, opacity and colour (red, 60pt, 45°, 25%). */
+export type WatermarkPreset = "draft" | "confidential" | "approved" | "final" | "copy" | "notForDistribution";
+
+/** Options for `PdfDoc.addWatermark`. Give `text`, `preset`, or both (then `text` wins). */
+export interface WatermarkOptions {
+    text?: string;
+    preset?: WatermarkPreset;
+    /** Points. Default 48 (60 with a preset). */
+    fontSize?: number;
+    /** Degrees counter-clockwise. Default 45. */
+    rotation?: number;
+    /** 0..1. Default 0.3 (0.25 with a preset). */
+    opacity?: number;
+    /** `"#rrggbb"`. Default mid grey (red with a preset). */
+    color?: string;
+    /** `"center"` (default), or a corner / exact point in PDF points. */
+    position?: "center" | { anchor: "topLeft" | "topRight" | "bottomLeft" | "bottomRight" | "exact"; x: number; y: number };
+    /** Default `"foreground"`. */
+    layer?: "foreground" | "background";
+    /** Repeat across the page. `true` = 200pt spacing. */
+    tile?: boolean | { hSpacing?: number; vSpacing?: number };
+    /** `"all"` (default), `"even"`, `"odd"`, 0-based page indices, or an inclusive 0-based range. */
+    pages?: "all" | "even" | "odd" | number[] | { from: number; to: number };
+}
+
+
+
+/** An image exported faithfully. `page` is 0-based: the first page it is used on. */
+export interface ExtractedImage {
+    page: number;
+    width: number;
+    height: number;
+    mime: "image/png" | "image/jpeg";
+    data: Uint8Array;
+}
+
+/** An image left out because it could not be exported without changing how it looks. */
+export interface SkippedImage {
+    page: number;
+    width: number;
+    height: number;
+    reason: "unsupported_filter" | "transparency" | "decode_array" | "cmyk_jpeg" | "color_space" | "bit_depth" | "image_mask" | "undecodable";
+    detail: string;
+}
+
+export interface ImageExtraction {
+    images: ExtractedImage[];
+    skipped: SkippedImage[];
+}
+
+
+
+/** Options for `signPdf`. The signature is a cryptographic (PAdES) signature, not a drawn one. */
+export interface SignPdfOptions {
+    reason?: string;
+    location?: string;
+    contactInfo?: string;
+    /** Default "Signature1". */
+    fieldName?: string;
+    /** Show the signature on a page (0-based) at a rectangle in PDF points. Invisible when absent. */
+    visibleRect?: { page: number; x: number; y: number; width: number; height: number };
+}
+
+
+
+/** What a user who opens the file with the user password may do. Every flag defaults to `true`. */
+export interface EncryptPermissions {
+    print?: boolean;
+    printHighQuality?: boolean;
+    modify?: boolean;
+    copy?: boolean;
+    annotate?: boolean;
+    fillForms?: boolean;
+    accessibility?: boolean;
+    assemble?: boolean;
+}
+
+
+
 /**
  * Chroma subsampling format
  */
@@ -77,8 +156,16 @@ export class PdfDoc {
     /**
      * Apply a diagonal text watermark to every page.
      * `opacity` in 0.0..=1.0. Default rotation 45 deg, default colour gray.
+     *
+     * Kept for compatibility; `addWatermark` takes the full set of options.
      */
     addTextWatermark(text: string, opacity: number): Uint8Array;
+    /**
+     * Apply a text watermark with full control over text or preset, size,
+     * rotation, opacity, colour, position, layer, tiling and pages. Returns
+     * the new PDF bytes. Text only: there is no image watermark.
+     */
+    addWatermark(options: WatermarkOptions): Uint8Array;
     /**
      * Re-encode all content streams with deflate compression. Removes
      * no-op overhead. Returns the optimised PDF as a `Uint8Array`.
@@ -99,6 +186,58 @@ export class PdfDoc {
      * DSS (Document Security Store) info as JSON, or null if absent.
      */
     dssInfo(): string | undefined;
+    /**
+     * The document's blocks as JSON, in reading order (#573).
+     *
+     * Preview: output quality is still improving and the API may change in a minor release.
+     *
+     * `{"blocks": [...]}`, one entry per paragraph, heading, list item, table
+     * cell and running head, each with its kind, page, box, text, spans and
+     * place in the reading order. `docs/STRUCTURED_EXTRACTION.md` is the key
+     * to every field.
+     *
+     * A JSON string and not a structured value, which is what every other
+     * structured reader in this binding hands back: one shape crosses the
+     * boundary, `JSON.parse` is what the caller already does for
+     * `getTextPositions` and the annotations, and a `serde` mirror of the
+     * block model would be a second definition of it to keep in step.
+     *
+     * An XFA form is read from its flattened form, for the reason
+     * `extractMarkdown` above gives.
+     */
+    extractBlocks(first_page?: number | null, page_count?: number | null): string;
+    /**
+     * The document as a Docling `DoclingDocument`, as JSON (#629).
+     *
+     * Preview: output quality is still improving and the API may change in a minor release.
+     *
+     * The schema version the engine pins, which docling-core's
+     * `DoclingDocument.model_validate_json` loads as it is. `name` is
+     * `DoclingDocument.name`, which Docling fills with the file's stem;
+     * absent means `"document"`. An XFA form is read from its flattened form,
+     * for the reason `extractMarkdown` above gives.
+     */
+    extractDocling(first_page?: number | null, page_count?: number | null, name?: string | null): string;
+    /**
+     * The document as markdown, in reading order (#573).
+     *
+     * Preview: output quality is still improving and the API may change in a minor release.
+     *
+     * Headings become `#` to `###`, list items `-` and `1.`, a table a pipe
+     * table or an HTML one where markdown cannot hold its shape, and a change
+     * of page an HTML comment. The running heads a document repeats are not in
+     * it; they are in `extractBlocks`.
+     *
+     * `firstPage` and `pageCount` choose a window of pages; leave both out for
+     * the whole document. The document is read whole whatever the window is,
+     * because what a block IS is decided against the rest of the document.
+     *
+     * AN XFA FORM IS READ FROM ITS FLATTENED FORM, the way `text` and
+     * `getTextPositions` read one: a dynamic XFA document draws its fields
+     * from a template rather than from page content, so the blocks of the
+     * unflattened file are the blocks of an empty page.
+     */
+    extractMarkdown(first_page?: number | null, page_count?: number | null): string;
     /**
      * Extract the listed pages (0-based) into a new document.
      * Used to implement "split" workflows in the browser.
@@ -191,6 +330,10 @@ export class PdfDoc {
     /**
      * Search-and-redact: every match of `query` (literal text, case-sensitive)
      * is permanently removed from every page.
+     *
+     * Throws `E-PARSE-INVALID-PDF` when a page's text could not be read:
+     * that page was not searched, so returning bytes would read as "no
+     * matches there" (#698).
      */
     redactSearch(query: string): Uint8Array;
     /**
@@ -287,6 +430,16 @@ export class PdfDoc {
      * extraction fails.
      */
     text(page_index: number): string;
+    /**
+     * Every text block of the document with its page and enclosing box, as
+     * JSON (#416): `[{"text": "...", "bbox": [xMin, yMin, xMax, yMax], "page": 0}]`.
+     *
+     * `page` is 0-based like every page index in this binding; `bbox` is in PDF
+     * points with the origin at the bottom left (PDF space, not the y-down CSS
+     * space `getTextPositions` returns). An XFA form is read from its flattened
+     * form, as `text` and `getTextPositions` do.
+     */
+    textWithLayout(): string;
     /**
      * Convert this PDF to a Word `.docx` package.
      *
@@ -393,6 +546,15 @@ export class PdfDocMut {
      * `formatted = false`, `bytesChanged = 0`, no error.
      */
     formatTextSpan(page_num: number, run_index: number, font_size?: number | null, color?: string | null): string;
+    /**
+     * The images drawn on a page (0-based `pageIndex`) as JSON, in drawing
+     * order, form-nested and inline images included:
+     * `[{"formPath":[…],"opIndex":n,"kind":"xobject"|"inline","resourceName":…,
+     * "formNames":[…],"ctm":[6],"bbox":[x0,y0,x1,y1],"pixelWidth":…,
+     * "pixelHeight":…,"hasSmask":…}]`. `bbox` is in page space, origin at the
+     * bottom left. An entry is the handle the three edit methods take.
+     */
+    imagePlacements(page_index: number): string;
     /**
      * Open a PDF for editing.
      */
@@ -408,12 +570,26 @@ export class PdfDocMut {
     /**
      * Search-and-redact: every literal match of `query` is permanently
      * removed from every page.
+     *
+     * Throws `E-PARSE-INVALID-PDF` when a page's text could not be read:
+     * that page was not searched, so success would read as "no matches
+     * there" (#698). The document is then left as it was.
      */
     redactSearch(query: string): void;
+    /**
+     * Remove one placed image. The image data leaves the file when nothing
+     * else uses it.
+     */
+    removeImage(page_index: number, handle_json: string): void;
     /**
      * Re-order pages. `new_order` is a permutation of `0..page_count`.
      */
     reorderPages(new_order: Uint32Array): void;
+    /**
+     * Swap the picture of one placed image for JPEG or PNG `data`, fitted
+     * inside the old placement and centred. Returns the new handle as JSON.
+     */
+    replaceImage(page_index: number, handle_json: string, data: Uint8Array): string;
     /**
      * G3 — Replace a text span on a page.
      *
@@ -483,6 +659,13 @@ export class PdfDocMut {
      * `{"field.path": "value", ...}`.
      */
     setFormFields(fields_json: string): void;
+    /**
+     * Move or resize one placed image so its bounding box becomes
+     * `[x0, y0, x1, y1]` in page space. `handleJson` is an entry of
+     * `imagePlacements`. Returns the new handle as JSON. An edit inside a Form
+     * XObject copies the form for this page, so other pages keep the original.
+     */
+    setImageRect(page_index: number, handle_json: string, x0: number, y0: number, x1: number, y1: number): string;
     /**
      * Select multiple options on a multi-select list box.
      *
@@ -661,6 +844,52 @@ export class XfaEngine {
     static version(): string;
 }
 
+/**
+ * Remove the password from a PDF whose password you know, and return the
+ * unprotected bytes; open them with `PdfDoc.open`.
+ *
+ * The owner password always works. The user password works only when the
+ * file has no permission restrictions. Throws `PdfluentError` with
+ * `E-SECURITY-DECRYPTION-FAILED` for a password that does not entitle the
+ * caller, and `E-WASM-INVALID-ARGUMENT` for a PDF without a password.
+ */
+export function decryptPdf(bytes: Uint8Array, password: string): Uint8Array;
+
+/**
+ * Encrypt a PDF with AES-256 and return the encrypted bytes.
+ *
+ * `userPassword` is needed to open the file (may be empty: then anyone can
+ * open it, and the permissions apply); `ownerPassword` lifts the permissions
+ * (empty: the user password serves as both). Refuses a PDF that is already
+ * encrypted. Throws `PdfluentError` with `E-WASM-INVALID-ARGUMENT` or
+ * `E-PARSE-INVALID-PDF`.
+ */
+export function encryptPdf(bytes: Uint8Array, user_password: string, owner_password: string, permissions?: EncryptPermissions | null): Uint8Array;
+
+/**
+ * Extract the images of a PDF as PNG or JPEG files.
+ *
+ * Returns `{ images, skipped }`. An image that could not be exported exactly
+ * as it looks -- JPEG 2000, JBIG2 or fax compression, a transparency mask, a
+ * Decode array, CMYK, an ICC profile other than sRGB -- is listed in `skipped`
+ * with the reason, never emitted wrong. Each image is listed once, on the
+ * first page (0-based) that uses it.
+ */
+export function extractImages(bytes: Uint8Array): ImageExtraction;
+
+/**
+ * Sign a PDF with your own certificate (a .p12/.pfx file and its password)
+ * and return the signed bytes. The private key never leaves the page.
+ *
+ * This is a cryptographic PAdES signature (ETSI.CAdES.detached), appended as
+ * an incremental update so earlier signatures stay valid. Without a
+ * timestamp authority: no TSA or LTV in the browser. A self-signed
+ * certificate verifies, but readers such as Acrobat show its validity as
+ * unknown because they do not trust the issuer. Throws `PdfluentError` with
+ * `E-SECURITY-DECRYPTION-FAILED` for a wrong certificate password.
+ */
+export function signPdf(bytes: Uint8Array, pkcs12: Uint8Array, password: string, options?: SignPdfOptions | null): Uint8Array;
+
 export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
 
 export interface InitOutput {
@@ -669,14 +898,21 @@ export interface InitOutput {
     readonly __wbg_pdfdocmut_free: (a: number, b: number) => void;
     readonly __wbg_texteditor_free: (a: number, b: number) => void;
     readonly __wbg_xfaengine_free: (a: number, b: number) => void;
+    readonly decryptPdf: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly encryptPdf: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
+    readonly extractImages: (a: number, b: number, c: number) => void;
     readonly pdfdoc_addFreeText: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => void;
     readonly pdfdoc_addHighlight: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => void;
     readonly pdfdoc_addStickyNote: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
     readonly pdfdoc_addTextWatermark: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly pdfdoc_addWatermark: (a: number, b: number, c: number) => void;
     readonly pdfdoc_compress: (a: number, b: number) => void;
     readonly pdfdoc_convertToPdfa: (a: number, b: number, c: number, d: number) => void;
     readonly pdfdoc_deletePages: (a: number, b: number, c: number, d: number) => void;
     readonly pdfdoc_dssInfo: (a: number, b: number) => void;
+    readonly pdfdoc_extractBlocks: (a: number, b: number, c: number, d: number) => void;
+    readonly pdfdoc_extractDocling: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+    readonly pdfdoc_extractMarkdown: (a: number, b: number, c: number, d: number) => void;
     readonly pdfdoc_extractPages: (a: number, b: number, c: number, d: number) => void;
     readonly pdfdoc_flattenXfa: (a: number, b: number) => void;
     readonly pdfdoc_getAnnotations: (a: number, b: number, c: number) => void;
@@ -701,6 +937,7 @@ export interface InitOutput {
     readonly pdfdoc_setFormFields: (a: number, b: number, c: number, d: number) => void;
     readonly pdfdoc_signatures: (a: number, b: number) => void;
     readonly pdfdoc_text: (a: number, b: number, c: number) => void;
+    readonly pdfdoc_textWithLayout: (a: number, b: number) => void;
     readonly pdfdoc_toDocx: (a: number, b: number) => void;
     readonly pdfdoc_toPptx: (a: number, b: number) => void;
     readonly pdfdoc_toXlsx: (a: number, b: number) => void;
@@ -716,18 +953,23 @@ export interface InitOutput {
     readonly pdfdocmut_deletePages: (a: number, b: number, c: number, d: number) => void;
     readonly pdfdocmut_extractPages: (a: number, b: number, c: number, d: number) => void;
     readonly pdfdocmut_formatTextSpan: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+    readonly pdfdocmut_imagePlacements: (a: number, b: number, c: number) => void;
     readonly pdfdocmut_open: (a: number, b: number, c: number) => void;
     readonly pdfdocmut_pageCount: (a: number) => number;
     readonly pdfdocmut_redactRegion: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
     readonly pdfdocmut_redactSearch: (a: number, b: number, c: number, d: number) => void;
+    readonly pdfdocmut_removeImage: (a: number, b: number, c: number, d: number, e: number) => void;
     readonly pdfdocmut_reorderPages: (a: number, b: number, c: number, d: number) => void;
+    readonly pdfdocmut_replaceImage: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
     readonly pdfdocmut_replaceTextSpan: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
     readonly pdfdocmut_rotatePage: (a: number, b: number, c: number, d: number) => void;
     readonly pdfdocmut_save: (a: number, b: number) => void;
     readonly pdfdocmut_setFormField: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
     readonly pdfdocmut_setFormFields: (a: number, b: number, c: number, d: number) => void;
+    readonly pdfdocmut_setImageRect: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => void;
     readonly pdfdocmut_setMultiSelect: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
     readonly pdfdocmut_setTextRunStyle: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
+    readonly signPdf: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
     readonly texteditor_findText: (a: number, b: number, c: number, d: number) => void;
     readonly texteditor_open: (a: number, b: number, c: number) => void;
     readonly texteditor_pageCount: (a: number) => number;