pdf_engine/

api.rs

//! The ideal top-level API facade for the PDFluent SDK.
//!
//! This module defines the intended public surface of the PDFluent library,
//! following the "Zero-Config First Success", "Pit of Success", and "Progressive Disclosure"
//! design principles.

// Copyright (c) 2026 Innovation Trigger B.V.
//
// PDFluent is available under two licences, at your option: the GNU AGPLv3, or
// the PDFluent Commercial Licence. See the LICENSE file in this repository --
// that file travels with the copy you received, which a URL does not.

use std::path::Path;

pub use crate::api_error::Error;

/// Input source for a PDF document — accepts either a filesystem path or
/// in-memory bytes.
pub enum PdfSource<'a> {
    /// Read the PDF from a filesystem path.
    Path(&'a Path),
    /// Read the PDF from an in-memory byte slice.
    Bytes(&'a [u8]),
}

impl<'a> From<&'a str> for PdfSource<'a> {
    fn from(s: &'a str) -> Self {
        PdfSource::Path(Path::new(s))
    }
}

impl<'a> From<&'a Path> for PdfSource<'a> {
    fn from(p: &'a Path) -> Self {
        PdfSource::Path(p)
    }
}

impl<'a> From<&'a [u8]> for PdfSource<'a> {
    fn from(b: &'a [u8]) -> Self {
        PdfSource::Bytes(b)
    }
}

/// Options for reading a PDF.
#[derive(Default, Debug, Clone)]
pub struct ReadOptions {
    pub(crate) password: Option<String>,
    pub(crate) repair: bool,
}

impl ReadOptions {
    /// Construct default `ReadOptions` (no password, no repair).
    pub fn new() -> Self {
        Self::default()
    }

    /// Set a password to attempt when the PDF is encrypted (user or owner
    /// password). Ignored on unencrypted documents.
    pub fn password(&mut self, pw: impl Into<String>) -> &mut Self {
        self.password = Some(pw.into());
        self
    }

    /// Enable best-effort recovery of malformed PDFs (broken xref,
    /// truncated streams). Slower but loads more inputs.
    pub fn repair(&mut self, repair: bool) -> &mut Self {
        self.repair = repair;
        self
    }
}

/// Options for saving a PDF.
#[derive(Default, Debug, Clone)]
pub struct SaveOptions {
    pub(crate) format: Option<PdfFormat>,
    pub(crate) linearize: bool,
}

impl SaveOptions {
    /// Construct default `SaveOptions` (preserve input format, no
    /// linearization).
    pub fn new() -> Self {
        Self::default()
    }

    /// Force the saver to emit a specific PDF or PDF/A version. When unset,
    /// the input document's version is preserved.
    pub fn format(&mut self, format: PdfFormat) -> &mut Self {
        self.format = Some(format);
        self
    }

    /// Linearize the output for "fast web view" — the saver reorders
    /// objects so a viewer can render the first page before the full file
    /// has downloaded.
    pub fn linearize(&mut self, linearize: bool) -> &mut Self {
        self.linearize = linearize;
        self
    }
}

/// PDF or PDF/A target version that the saver should emit. Used by
/// [`SaveOptions::format`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PdfFormat {
    /// PDF 1.4 — broadest reader compatibility, no AES-256.
    Pdf1_4,
    /// PDF 1.7 (ISO 32000-1) — modern baseline.
    Pdf1_7,
    /// PDF 2.0 (ISO 32000-2) — required for AES-256 (`V=5, R=6`).
    Pdf2_0,
    /// PDF/A-1b (ISO 19005-1, level B) — basic archival.
    PdfA1b,
    /// PDF/A-2b (ISO 19005-2, level B) — adds JPEG 2000, transparency.
    PdfA2b,
    /// PDF/A-3b (ISO 19005-3, level B) — adds arbitrary file attachments
    /// (used for ZUGFeRD/Factur-X).
    PdfA3b,
}

/// Options for [`Document::add_watermark`]. Defaults: opaque, unrotated.
#[derive(Default, Debug, Clone)]
pub struct WatermarkOptions {
    /// Opacity, 0.0 (transparent) to 1.0 (opaque). Out-of-range values
    /// clamp at 0.0/1.0.
    pub opacity: f64,
    /// Rotation in degrees around the page center. Positive =
    /// counter-clockwise.
    pub rotation: f64,
}

/// Output format selector for [`Document::to_images`]. PNG for line art /
/// text, JPEG for photographic content.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ImageFormat {
    /// Lossless PNG — preserves text edges and line art.
    Png,
    /// Lossy JPEG — smaller output for photographic pages.
    Jpeg,
}

/// A structured block of text from a PDF, with its bounding box on the
/// page. Returned by [`Document::structured_text`].
pub struct TextBlock {
    /// Block text content in reading order.
    pub text: String,
    /// Bounding box `[llx, lly, urx, ury]` in PDF user-space points
    /// (1/72 inch). Origin is the bottom-left of the page.
    pub bbox: [f64; 4],
}

/// Document-level metadata read from the `/Info` dictionary or XMP. All
/// fields are `None` if absent. Returned by [`Document::metadata`].
pub struct Metadata {
    /// `/Title`. `None` if not set.
    pub title: Option<String>,
    /// `/Author`. `None` if not set.
    pub author: Option<String>,
    /// `/CreationDate` as a PDF date string
    /// (`D:YYYYMMDDHHmmSSOHH'mm'`). May be malformed in legacy
    /// documents — parse defensively.
    pub creation_date: Option<String>,
}

/// An interactive form field as seen by the form-fill API. One entry per
/// terminal field; group fields are flattened. Returned by
/// [`Document::form_fields`].
pub struct FormField {
    /// Fully-qualified field name (`parent.child` notation).
    pub name: String,
    /// Current field value as a string. For checkboxes this is the
    /// "on"-state name (e.g. `"Yes"`, `"Off"`); for choice fields, the
    /// selected option.
    pub value: String,
    /// Field-type discriminator: `"Tx"` (text), `"Btn"` (button),
    /// `"Ch"` (choice), `"Sig"` (signature).
    pub field_type: String,
}

/// A digital signature widget found in the document. Returned by
/// [`Document::signatures`]; cryptographic verification is performed
/// separately by [`Document::verify_signatures`].
pub struct Signature {
    /// Display name from the signature dictionary's `/Name` entry, or
    /// from the certificate's subject if `/Name` is absent.
    pub signer_name: String,
    /// Signing time as a PDF date string. May be the signer's local
    /// time (untrusted) or a TSA timestamp (trusted) depending on the
    /// PAdES profile.
    pub date: String,
    /// `true` if the signature digest matches and the certificate chain
    /// validates. For full validation reports, see
    /// [`Document::verify_signatures`].
    pub is_valid: bool,
}

/// The main entry point for a PDF Document.
pub struct Document {
    // Internal handle to actual implementation would go here
}

impl Document {
    // === TEKST ===

    /// Extracts plain text from all pages.
    pub fn text(&self) -> String {
        unimplemented!("facade")
    }

    /// Accesses a specific page for text extraction and other operations (1-based index).
    pub fn page(&self, page_number: usize) -> Page {
        let _ = page_number;
        unimplemented!("facade")
    }

    /// Extracts structured text blocks with coordinates.
    pub fn structured_text(&self) -> Vec<TextBlock> {
        unimplemented!("facade")
    }

    // === METADATA ===

    /// Returns the total number of pages in the document.
    pub fn page_count(&self) -> usize {
        unimplemented!("facade")
    }

    /// Returns the document's metadata.
    pub fn metadata(&self) -> Metadata {
        unimplemented!("facade")
    }

    // === OPSLAAN ===

    /// Saves the document to a file.
    pub fn save(&self, path: impl AsRef<Path>) -> Result<(), Error> {
        let _ = path;
        unimplemented!("facade")
    }

    /// Saves the document with specific options.
    pub fn save_with<F>(&self, path: impl AsRef<Path>, build_opts: F) -> Result<(), Error>
    where
        F: FnOnce(&mut SaveOptions) -> &mut SaveOptions,
    {
        let _ = path;
        let _ = build_opts;
        unimplemented!("facade")
    }

    // === FORMULIEREN ===

    /// Gets all form fields in the document.
    pub fn form_fields(&self) -> Vec<FormField> {
        unimplemented!("facade")
    }

    /// Fills form fields matching the provided name-value pairs.
    pub fn fill_form(&self, fields: &[(&str, &str)]) -> Result<(), Error> {
        let _ = fields;
        unimplemented!("facade")
    }

    /// Flattens all forms, converting them to static content.
    pub fn flatten_forms(&self) -> Result<(), Error> {
        unimplemented!("facade")
    }

    // === HANDTEKENINGEN ===

    /// Signs the document using the provided certificate and private key.
    pub fn sign(&self, certificate: &[u8], private_key: &[u8]) -> Result<(), Error> {
        let _ = certificate;
        let _ = private_key;
        unimplemented!("facade")
    }

    /// Retrieves all signatures from the document.
    pub fn signatures(&self) -> Vec<Signature> {
        unimplemented!("facade")
    }

    /// Verifies the cryptographic validity of all signatures.
    pub fn verify_signatures(&self) -> Result<bool, Error> {
        unimplemented!("facade")
    }

    // === REDACTIE ===

    /// Redacts all occurrences of the specified text.
    pub fn redact(&self, text: &str) -> Result<(), Error> {
        let _ = text;
        unimplemented!("facade")
    }

    /// Redacts a specific rectangular region on the specified page.
    pub fn redact_region(&self, page: usize, rect: [f64; 4]) -> Result<(), Error> {
        let _ = page;
        let _ = rect;
        unimplemented!("facade")
    }

    // === CONVERSIE ===

    /// Converts the document to a DOCX file.
    pub fn to_docx(&self, path: impl AsRef<Path>) -> Result<(), Error> {
        let _ = path;
        unimplemented!("facade")
    }

    /// Renders the document's pages to images based on a filename pattern.
    pub fn to_images(&self, pattern: &str, format: ImageFormat) -> Result<(), Error> {
        let _ = pattern;
        let _ = format;
        unimplemented!("facade")
    }

    /// Checks if the document is PDF/A compliant.
    pub fn is_pdfa_compliant(&self) -> Result<bool, Error> {
        unimplemented!("facade")
    }

    // === MANIPULATIE ===

    /// Merges another document into this one.
    pub fn merge(&self, other_doc: &Document) -> Result<(), Error> {
        let _ = other_doc;
        unimplemented!("facade")
    }

    /// Splits the document into individual 1-page documents.
    pub fn split_pages(&self) -> Result<Vec<Document>, Error> {
        unimplemented!("facade")
    }

    /// Rotates a specific page by the given angle (in degrees).
    pub fn rotate_page(&self, page: usize, angle: i32) -> Result<(), Error> {
        let _ = page;
        let _ = angle;
        unimplemented!("facade")
    }

    /// Adds a watermark to all pages of the document.
    pub fn add_watermark(&self, text: &str, options: WatermarkOptions) -> Result<(), Error> {
        let _ = text;
        let _ = options;
        unimplemented!("facade")
    }
}

/// Represents a single page within a Document.
pub struct Page {
    // Internal handle to the specific page
}

impl Page {
    /// Extracts plain text from this page only.
    pub fn text(&self) -> String {
        unimplemented!("facade")
    }
}

// === LEZEN (Top-level functions) ===

/// Reads a PDF document from a file path or bytes, using default options.
pub fn read<'a, S: Into<PdfSource<'a>>>(input: S) -> Result<Document, Error> {
    let _ = input;
    unimplemented!("facade")
}

/// Reads a PDF document with custom options (e.g., providing a password).
pub fn read_with<'a, S, F>(input: S, build_opts: F) -> Result<Document, Error>
where
    S: Into<PdfSource<'a>>,
    F: FnOnce(&mut ReadOptions) -> &mut ReadOptions,
{
    let _ = input;
    let _ = build_opts;
    unimplemented!("facade")
}