Referencia de la API de Kotlin

PDF Oxide incluye bindings idiomáticos de Kotlin/JVM (listos para Android) como una fachada ligera sobre el maduro binding de Java fyi.oxide:pdf-oxide, que es el propietario del único puente nativo JNI (el crate pdf_oxide_jni). El módulo de Kotlin añade cero código nativo: reexporta los tipos de Java (PdfDocument, Pdf, PdfPage, DocumentEditor, PdfSigner, PdfValidator, AutoExtractor y los tipos de valor de geometría / texto / tablas / búsqueda) y añade azúcar sintáctico de Kotlin: extensiones de Optional<T> a T? y use { } sobre los handles AutoCloseable.

// build.gradle.kts
dependencies {
    implementation("fyi.oxide:pdf-oxide-kotlin:0.3.69")
}

La librería nativa JNI (libpdf_oxide_jni) no viene incluida: cárgala con System.loadLibrary("pdf_oxide_jni") (distribuye el .so/.dylib en tu java.library.path, o en jniLibs/<abi>/ en Android), o indícale al NativeLoader de Java dónde está con -Dfyi.oxide.pdf.lib.path=<path>.

Para la API de Java, consulta la Referencia de la API de Java. Para la API de Rust, consulta la Referencia de la API de Rust. Para los detalles de los tipos, consulta Tipos y Enums.

import fyi.oxide.pdf.Pdf
import fyi.oxide.pdf.PdfDocument
import fyi.oxide.pdf.producerOrNull

Pdf.fromMarkdown("# Hello\n\nbody\n").use { pdf ->
    PdfDocument.open(pdf.save()).use { doc ->
        println(doc.pageCount())
        println(doc.extractText(0))
        println(doc.toMarkdown())
        println(doc.page(0).words().map { it.text() })
        println(doc.producerOrNull() ?: "(no producer)")   // Optional -> nullable
    }
}

Todos los handles (PdfDocument, Pdf, DocumentEditor) implementan AutoCloseable, de modo que el bloque use { } de Kotlin libera la memoria nativa de forma determinista. Los errores lanzan PdfException (y sus subclases); consulta Excepciones.

---

PdfDocument

El punto de entrada principal de solo lectura a un PDF: abre, extrae, convierte, renderiza, busca e inspecciona campos de formulario. Las instancias son propietarias de memoria nativa y deben cerrarse; usa use { }.

import fyi.oxide.pdf.PdfDocument

Métodos de fábrica

PdfDocument.open(path: Path): PdfDocument

Abre un PDF desde una ruta del sistema de archivos.

PdfDocument.open(path: String): PdfDocument

Abre un PDF desde una ruta en forma de cadena.

PdfDocument.open(bytes: ByteArray): PdfDocument

Abre un PDF desde bytes en memoria (por ejemplo, descargado de S3 o recibido por HTTP).

PdfDocument.open(path: Path, password: String): PdfDocument

Abre un PDF cifrado desde una ruta con la contraseña de usuario o de propietario.

PdfDocument.open(path: String, password: String): PdfDocument

Abre un PDF cifrado desde una ruta en forma de cadena con una contraseña.

PdfDocument.open(bytes: ByteArray, password: String): PdfDocument

Abre un PDF cifrado desde bytes con una contraseña.

PdfDocument.open(stream: InputStream): PdfDocument

Abre un PDF leyendo todos los bytes de un InputStream.

Operaciones estáticas de un solo uso

PdfDocument.extractText(path: String): String
PdfDocument.extractText(path: Path): String

Abre, extrae todo el texto y cierra en una sola llamada, para el caso sencillo en el que no necesitas un handle activo.

Autenticación

doc.authenticate(password: String): Boolean
doc.authenticate(password: ByteArray): Boolean

Autentica un documento cifrado después de abrirlo. Devuelve true si la contraseña coincide.

Información del documento

doc.pageCount(): Int

Número de páginas del documento.

doc.producer(): Optional<String>
doc.creator(): Optional<String>

Metadatos /Producer y /Creator del documento. Usa las extensiones de Kotlin producerOrNull() / creatorOrNull() para un acceso basado en null.

val doc.isOpen: Boolean

Indica si el handle nativo sigue abierto (propiedad de Kotlin sobre el getter isOpen() de Java).

Extracción de texto

doc.extractText(pageIndex: Int): String

Extrae texto plano de una sola página indexada desde cero.

doc.extractTextAuto(pageIndex: Int): String

Extrae texto con selección automática de estrategia (recurre al OCR para páginas escaneadas cuando la característica de OCR está disponible).

doc.extractStructured(page: Int): String

Extrae una representación estructurada (JSON) del texto y la disposición de la página.

Conversión

doc.toMarkdown(): String
doc.toMarkdown(pageIndex: Int): String

Convierte todo el documento o una sola página a Markdown.

doc.toHtml(): String
doc.toHtml(pageIndex: Int): String

Convierte todo el documento o una sola página a HTML.

Búsqueda

doc.search(query: String): List<SearchMatch>

Busca una cadena literal en el documento. Devuelve las coincidencias por página con sus cuadros delimitadores.

doc.search(query: String, caseInsensitive: Boolean, regex: Boolean, maxResults: Int): List<SearchMatch>

Busca con sensibilidad a mayúsculas, regex y un límite de resultados (maxResults = 0 significa sin límite).

Formularios

doc.formFields(): List<FormField>

Obtiene todos los campos AcroForm con su tipo, valor, límites del widget e índice de página. Consulta FormField.

Renderizado

doc.render(pageIndex: Int): ByteArray
doc.render(pageIndex: Int, dpi: Int): ByteArray

Renderiza una página a bytes de imagen PNG con el DPI predeterminado o un DPI especificado.

Acceso a las páginas

doc.page(index: Int): PdfPage

Obtiene un handle perezoso PdfPage para el índice indicado (basado en cero).

doc.pages(): List<PdfPage>

Obtiene todas las páginas como una lista.

doc.pagesStream(): Stream<PdfPage>

Obtiene todas las páginas como un Stream de Java para un procesamiento fluido.

Ciclo de vida

doc.close()

Libera la memoria nativa. Idempotente: una segunda llamada no tiene efecto. Prefiere use { }.

---

PdfPage

Un handle perezoso de página devuelto por PdfDocument.page(), pages() o pagesStream(). Todos los accesores delegan en el documento padre al acceder.

PdfDocument.open(bytes).use { doc ->
    val page = doc.page(0)
    val words = page.words()
    val tables = page.tables()
}

Geometría

page.parent(): PdfDocument
page.index(): Int
page.mediaBox(): BBox
page.cropBox(): BBox
page.width(): Double
page.height(): Double
page.rotation(): Int

Documento padre, índice basado en cero, rectángulos MediaBox / CropBox, dimensiones en puntos PDF y rotación de la página en grados.

Extracción de contenido

page.text(): String

Extrae todo el texto de la página.

page.text(region: BBox): String

Extrae el texto dentro de una región delimitada por un cuadro.

page.words(): List<TextWord>
page.lines(): List<TextLine>
page.chars(): List<TextChar>

Texto estructurado con granularidad de palabra, línea y carácter.

page.images(): List<ExtractedImage>
page.tables(): List<Table>
page.annotations(): List<Annotation>

Imágenes extraídas, tablas detectadas y anotaciones de la página.

---

Pdf

Crea PDF a partir de formatos de origen, divídelos por marcadores y serialízalos. Implementa AutoCloseable.

import fyi.oxide.pdf.Pdf

Métodos de fábrica

Pdf.fromMarkdown(markdown: String): Pdf

Crea un PDF a partir de contenido Markdown.

Pdf.fromHtml(html: String): Pdf

Crea un PDF a partir de contenido HTML.

Pdf.fromImages(images: List<ByteArray>): Pdf

Crea un PDF de varias páginas a partir de una lista de arrays de bytes de imágenes, una página por imagen.

División

pdf.planSplitByBookmarks(opts: SplitByBookmarksOptions): List<BookmarkSegment>

Planifica una división por marcadores del esquema sin producir salida: devuelve los segmentos (título, rango de páginas, nombre de archivo) que se crearían.

pdf.splitByBookmarks(opts: SplitByBookmarksOptions): List<ByteArray>

Divide en varios PDF por nivel de marcador. Devuelve un array de bytes por segmento.

Pdf.planSplitByBookmarksCount(sourcePdf: ByteArray, level: Int): Int

Auxiliar estático: cuenta cuántos segmentos produciría una división por marcadores en el nivel indicado.

Pdf.splitByBookmarksFromBytes(sourcePdf: ByteArray, level: Int): Array<ByteArray>

Auxiliar estático: divide directamente los bytes del PDF de origen por nivel de marcador.

Guardado

pdf.save(): ByteArray

Serializa el PDF a bytes.

pdf.saveTo(out: Path)

Escribe el PDF en un archivo.

val pdf.isOpen: Boolean
pdf.close()

Ciclo de vida (propiedad isOpen y close() de Kotlin). Prefiere use { }.

---

DocumentEditor

Editor mutable para redacción, relleno de formularios, depuración de metadatos y guardados incrementales. Implementa AutoCloseable. Los métodos setter devuelven this para encadenarlos de forma fluida.

import fyi.oxide.pdf.DocumentEditor

Métodos de fábrica

DocumentEditor.open(path: Path): DocumentEditor
DocumentEditor.open(path: String): DocumentEditor
DocumentEditor.open(bytes: ByteArray): DocumentEditor

Abre un documento para editarlo desde una ruta o desde bytes en memoria.

Relleno de formularios

editor.setFormField(name: String, value: String): DocumentEditor

Establece el valor de un campo de texto/elección por su nombre completamente cualificado.

editor.setFormField(name: String, checked: Boolean): DocumentEditor

Establece el estado de una casilla de verificación/botón de opción por su nombre.

Redacción

editor.addRedaction(pageIndex: Int, region: BBox): DocumentEditor

Encola una redacción sobre una región rectangular de una página.

editor.redactionCount(pageIndex: Int): Int
editor.redactionCount(): Int

Número de redacciones encoladas en una página, o en todo el documento.

editor.applyRedactionsDestructive(): RedactResult

Aplica permanentemente todas las redacciones encoladas, eliminando el contenido subyacente. Devuelve un RedactResult con el recuento aplicado y el estado de verificación por oráculo.

Metadatos

editor.scrubMetadata(): DocumentEditor

Elimina los metadatos del documento (diccionario Info, XMP) por privacidad.

Guardado

editor.save(): ByteArray
editor.saveTo(out: Path)

Serializa el documento editado con una reescritura completa.

editor.saveIncremental(): ByteArray
editor.saveIncrementalTo(out: Path)

Serializa usando una actualización incremental (añade los cambios al final, preservando los bytes originales).

val editor.isOpen: Boolean
editor.close()

Ciclo de vida. Prefiere use { }.

---

AutoExtractor

Canalización de extracción adaptativa que clasifica las páginas (con capa de texto frente a escaneadas), aplica OCR donde sea necesario y emite texto / Markdown / HTML con puntuaciones de confianza.

import fyi.oxide.pdf.AutoExtractor

Métodos de fábrica

AutoExtractor.of(doc: PdfDocument): AutoExtractor
AutoExtractor.of(doc: PdfDocument, config: AutoExtractConfig): AutoExtractor

Crea un extractor sobre un documento, opcionalmente con una AutoExtractConfig personalizada.

AutoExtractor.fast(doc: PdfDocument): AutoExtractor
AutoExtractor.balanced(doc: PdfDocument): AutoExtractor
AutoExtractor.highFidelity(doc: PdfDocument): AutoExtractor

Configuraciones predefinidas que cambian velocidad por fidelidad.

Extracción

extractor.extractText(): String
extractor.extractTextForPage(pageIndex: Int): String

Extracción de texto plano para todo el documento o una sola página.

extractor.extractDocument(): AutoResult
extractor.extractPage(pageIndex: Int): AutoResult

Extracción adaptativa completa que devuelve un AutoResult (texto, Markdown/HTML opcionales, motivo, confianza, indicador de OCR, regiones).

extractor.extractAutoDocument(): AutoResult
extractor.extractAutoPage(pageIndex: Int): AutoResult

Variantes en modo automático de la extracción a nivel de documento y de página.

extractor.extractDocumentJson(): String
extractor.extractPageJson(pageIndex: Int): String

Extracción serializada como cadena JSON.

Clasificación

extractor.classifyDocument(): ClassifyResult
extractor.classifyPage(pageIndex: Int): ClassifyResult

Clasifica el documento o una página, devolviendo un ClassifyResult (clase por página más listas de páginas que necesitan OCR, que contienen gráficos o que están cifradas).

extractor.classifyPageKind(pageIndex: Int): PageClass
extractor.classifyDocumentKinds(): List<PageClass>

Obtiene la PageClass (TEXT_LAYER / SCANNED / MIXED) de una página o de todas.

Accesores

extractor.document(): PdfDocument
extractor.config(): AutoExtractConfig

El documento envuelto y la configuración activa.

---

MarkdownConverter

Conversor sin estado y seguro para hilos de PdfDocument a Markdown o HTML.

import fyi.oxide.pdf.MarkdownConverter

MarkdownConverter.toMarkdown(doc: PdfDocument): String
MarkdownConverter.toMarkdown(doc: PdfDocument, pageIndex: Int): String
MarkdownConverter.toHtml(doc: PdfDocument): String
MarkdownConverter.toHtml(doc: PdfDocument, pageIndex: Int): String

Convierte todo el documento o una sola página a Markdown / HTML.

---

PdfSigner

Firma y verifica PDF digitalmente con almacenes de claves PKCS#12 (niveles PAdES B-B / B-T / B-LT).

import fyi.oxide.pdf.PdfSigner

PdfSigner.fromPkcs12(keystore: Path, password: String): PdfSigner
PdfSigner.fromPkcs12(keystoreBytes: ByteArray, password: String): PdfSigner

Carga un firmante desde un almacén de claves PKCS#12 en disco o en memoria.

signer.sign(pdf: ByteArray, opts: SignOptions): ByteArray

Firma los bytes del PDF con las SignOptions indicadas (nivel, motivo, ubicación, contacto, URL de TSA). Devuelve el PDF firmado.

signer.verify(pdf: ByteArray): Boolean

Verifica todas las firmas de un PDF. Devuelve true si todas las firmas son criptográficamente válidas.

PdfSigner.classifyLevel(pdf: ByteArray): SignatureLevel

Auxiliar estático: detecta el nivel de conformidad PAdES de un PDF firmado existente.

---

PdfValidator

Validación sin estado y segura para hilos frente a los niveles de conformidad PDF/A, PDF/X y PDF/UA.

import fyi.oxide.pdf.PdfValidator

PdfValidator.isPdfA(doc: PdfDocument, level: PdfALevel): Boolean
PdfValidator.isPdfUa(doc: PdfDocument, level: PdfUaLevel): Boolean

Comprobaciones booleanas rápidas de conformidad.

PdfValidator.validatePdfA(doc: PdfDocument, level: PdfALevel): ValidationResult
PdfValidator.validatePdfX(doc: PdfDocument, level: PdfXLevel): ValidationResult
PdfValidator.validatePdfUa(doc: PdfDocument, level: PdfUaLevel): ValidationResult

Validación completa que devuelve un ValidationResult con la lista de infracciones.

---

PdfPolicy

Controles globales de política de seguridad que rigen qué algoritmos criptográficos están permitidos.

import fyi.oxide.pdf.PdfPolicy

PdfPolicy.current(): PolicyMode
PdfPolicy.set(mode: PolicyMode)
PdfPolicy.compat(): PolicyMode
PdfPolicy.strict(): PolicyMode
PdfPolicy.fipsStrict(): PolicyMode

Lee o establece el PolicyMode activo y obtén los modos integrados compat / strict / FIPS-strict.

---

Extensiones de Kotlin

La única superficie que añade la fachada de Kotlin: conversores de Optional<T> a T? y el auxiliar genérico orNull(). Impórtalos desde fyi.oxide.pdf.

fun <T : Any> Optional<T>.orNull(): T?

Genérico: un Optional vacío se convierte en null.

fun PdfDocument.producerOrNull(): String?
fun PdfDocument.creatorOrNull(): String?

/Producer y /Creator del documento, o null si están ausentes.

fun FormField.valueOrNull(): String?
fun FormField.bboxOrNull(): BBox?

Valor del campo de formulario y cuadro delimitador del widget, o null.

fun Annotation.contentsOrNull(): String?
fun Annotation.uriOrNull(): String?

/Contents de la anotación y URI de destino del enlace, o null.

fun AutoResult.markdownOrNull(): String?
fun AutoResult.htmlOrNull(): String?

Renderizado en Markdown / HTML de una extracción automática, o null si no se ha producido.

fun ValidationViolation.pageIndexOrNull(): Int?

Índice de página al que se aplica una infracción, o null para reglas a nivel de documento.

---

Tipos de geometría

BBox

Cuadro delimitador alineado con los ejes en puntos PDF.

BBox(x0: Double, y0: Double, x1: Double, y1: Double)

Accesor	Tipo	Descripción
x0(), y0(), x1(), y1()	Double	Coordenadas de las esquinas
width()	Double	x1 - x0
height()	Double	y1 - y0

Color

Color RGBA de 8 bits con constantes con nombre Color.BLACK, Color.WHITE, Color.TRANSPARENT.

Color(r: Int, g: Int, b: Int, a: Int)
Color(r: Int, g: Int, b: Int)            // a = 255

Accesores: r(): Int, g(): Int, b(): Int, a(): Int.

Point

Point(x: Double, y: Double)

Accesores: x(): Double, y(): Double.

Rect

Rectángulo de posición más tamaño.

Rect(x: Double, y: Double, width: Double, height: Double)

Accesores: x(), y(), width(), height() (todos Double) y toBBox(): BBox.

---

Tipos de texto

TextChar

Un único carácter extraído.

TextChar(codepoint: Int, bbox: BBox, confidence: Float)

Accesores: codepoint(): Int, bbox(): BBox, confidence(): Float, asString(): String.

TextWord

TextWord(text: String, bbox: BBox, confidence: Float)

Accesores: text(): String, bbox(): BBox, confidence(): Float.

TextLine

TextLine(text: String, bbox: BBox, words: List<TextWord>)

Accesores: text(): String, bbox(): BBox, words(): List<TextWord>.

TextSpan

Una secuencia de texto con un estilo idéntico.

TextSpan(text: String, bbox: BBox, style: TextStyle)

Accesores: text(): String, bbox(): BBox, style(): TextStyle.

TextStyle

TextStyle(font: String?, size: Double, color: Color, bold: Boolean, italic: Boolean)

Accesores: font(): String?, size(): Double, color(): Color, bold(): Boolean, italic(): Boolean.

---

Tipos de tabla

Table

Table(bbox: BBox, rows: Int, cols: Int, cells: List<TableCell>)

Accesores: bbox(): BBox, rows(): Int, cols(): Int, cells(): List<TableCell>.

TableCell

TableCell(text: String, bbox: BBox, row: Int, col: Int, rowSpan: Int, colSpan: Int)

Accesores: text(): String, bbox(): BBox, row(): Int, col(): Int, rowSpan(): Int, colSpan(): Int.

---

Tipos de búsqueda

SearchMatch

SearchMatch(pageIndex: Int, bbox: BBox, text: String)

Accesores: pageIndex(): Int, bbox(): BBox, text(): String.

SearchResult

SearchResult(query: String, matches: List<SearchMatch>)

Accesores: query(): String, matches(): List<SearchMatch>, count(): Int, isEmpty(): Boolean.

SearchOptions

Opciones inmutables construidas mediante un builder fluido. SearchOptions.DEFAULT es la instancia predeterminada.

SearchOptions.builder()
    .withCaseSensitive(true)
    .withWholeWord(true)
    .withRegex(false)
    .withMaxResults(50)
    .build()

Accesores: caseSensitive(): Boolean, wholeWord(): Boolean, regex(): Boolean, maxResults(): Optional<Int>. Métodos del builder: withCaseSensitive(Boolean), withWholeWord(Boolean), withRegex(Boolean), withMaxResults(Int) / withMaxResults(Int?), build().

Nota: actualmente no está conectado a PdfDocument.search() — usa en su lugar la sobrecarga caseInsensitive/regex/maxResults descrita arriba.

---

Tipos de formulario

FormField

FormField(name: String, type: FormFieldType, value: String?, bbox: BBox?, pageIndex: Int)

Accesores: name(): String, type(): FormFieldType, value(): Optional<String>, bbox(): Optional<BBox>, pageIndex(): Int. Usa valueOrNull() / bboxOrNull() para un acceso basado en null.

---

Tipos de anotación

Annotation

Annotation(type: AnnotationType, pageIndex: Int, bbox: BBox, contents: String?, uri: String?)

Accesores: type(): AnnotationType, pageIndex(): Int, bbox(): BBox, contents(): Optional<String>, uri(): Optional<String>. Usa contentsOrNull() / uriOrNull() para un acceso basado en null.

---

Tipos de imagen

ExtractedImage

ExtractedImage(bytes: ByteArray, format: ImageFormat, bbox: BBox, width: Int, height: Int)

Accesores: bytes(): ByteArray, format(): ImageFormat, bbox(): BBox, width(): Int, height(): Int.

---

Tipos de extracción automática

AutoResult

Resultado de una extracción adaptativa.

result.text(): String
result.markdown(): Optional<String>
result.html(): Optional<String>
result.reason(): ExtractReason
result.confidence(): Double
result.ocrUsed(): Boolean
result.regions(): List<RegionResult>
result.pagesNeedingOcr(): List<Int>

Usa markdownOrNull() / htmlOrNull() para un acceso basado en null a la salida renderizada.

RegionResult

Detalle de extracción por región dentro de un AutoResult.

region.pageIndex(): Int
region.bbox(): BBox
region.text(): String
region.reason(): ExtractReason
region.confidence(): Double
region.ocrUsed(): Boolean
region.table(): Optional<Table>

ClassifyResult

result.pages(): List<PageClass>
result.pagesNeedingOcr(): List<Int>
result.pagesWithChart(): List<Int>
result.pagesEncrypted(): List<Int>

AutoExtractConfig

Configuración inmutable construida mediante un builder fluido; AutoExtractConfig.DEFAULT es la predeterminada. Convierte una configuración existente de nuevo en un builder con toBuilder().

AutoExtractConfig.builder()
    .withMode(ExtractMode.AUTO)
    .withForceOcrPages(listOf(2, 5))
    .withMinOcrConfidence(0.6)
    .withOcrLanguages("eng", "deu")
    .withPasswords("secret")
    .withTopMarginFraction(0.05)
    .withBottomMarginFraction(0.05)
    .withAllowSingleColumnTables(true)
    .withOcrInlineImages(false)
    .withCancelToken("token-id")
    .build()

Los accesores devuelven Optional<...> para cada campo: mode(), forceOcrPages(), minOcrConfidence(), ocrLanguages(), passwords(), topMarginFraction(), bottomMarginFraction(), allowSingleColumnTables(), ocrInlineImages(), cancelToken(). Los setters del builder aceptan tanto sobrecargas anulables (boxed) como primitivas (por ejemplo, withMinOcrConfidence(Double?) y withTopMarginFraction(double)), además de las formas varargs withOcrLanguages(vararg String) / withPasswords(vararg String).

---

Tipos de conformidad

ValidationResult

ValidationResult(valid: Boolean, violations: List<ValidationViolation>)

Accesores: valid(): Boolean, violations(): List<ValidationViolation>.

ValidationViolation

ValidationViolation(ruleId: String, description: String, pageIndex: Int?)

Accesores: ruleId(): String, description(): String, pageIndex(): Optional<Int>. Usa pageIndexOrNull() para un acceso basado en null.

---

Tipos de metadatos

DocumentInfo

DocumentInfo(/* title, author, subject, keywords, creator, producer, creationDate, modificationDate */)

Todos los accesores devuelven Optional<String>: title(), author(), subject(), keywords(), creator(), producer(), creationDate(), modificationDate().

XmpMetadata

Paquete XMP en bruto. XmpMetadata.EMPTY es la instancia vacía.

XmpMetadata(xml: String)

Accesores: xml(): String, isEmpty(): Boolean.

---

Tipos de seguridad y redacción

SecurityPolicy

Política inmutable construida mediante un builder fluido.

SecurityPolicy.builder()
    .withMode(PolicyMode.STRICT)
    .allow("algorithm-id")
    .deny("algorithm-id")
    .build()

Accesores: mode(): PolicyMode, additionalAllow(): List<String>, additionalDeny(): List<String>. Métodos del builder: withMode(PolicyMode), allow(String), deny(String), build().

RedactResult

RedactResult(regionsApplied: Int, oracleVerified: Boolean)

Accesores: regionsApplied(): Int, oracleVerified(): Boolean.

---

Tipos de firma

SignOptions

Opciones de firma inmutables construidas mediante un builder fluido.

SignOptions.builder()
    .withLevel(SignatureLevel.B_T)
    .withReason("Approved")
    .withLocation("HQ")
    .withContactInfo("ops@example.com")
    .withTsaUrl("https://freetsa.org/tsr")
    .build()

Accesores: level(): SignatureLevel, reason(): Optional<String>, location(): Optional<String>, contactInfo(): Optional<String>, tsaUrl(): Optional<String>. Métodos del builder: withLevel, withReason, withLocation, withContactInfo, withTsaUrl, build().

---

Tipos de división

BookmarkSegment

BookmarkSegment(title: String, firstPage: Int, lastPage: Int, filename: String)

Accesores: title(): String, firstPage(): Int, lastPage(): Int, filename(): String.

SplitByBookmarksOptions

Opciones inmutables construidas mediante un builder fluido.

SplitByBookmarksOptions.builder()
    .withLevel(1)
    .withFilenamePrefix("chapter-")
    .build()

Accesores: level(): Int, filenamePrefix(): Optional<String>. Métodos del builder: withLevel(Int), withFilenamePrefix(String?), build().

---

Enums

Enum	Valores
FormFieldType	TEXT, CHECKBOX, RADIO, CHOICE
AnnotationType	HIGHLIGHT, TEXT, LINK, STAMP, UNDERLINE, STRIKEOUT, SQUIGGLY, FREE_TEXT, LINE, SQUARE, CIRCLE, FILE_ATTACHMENT
ImageFormat	JPEG, PNG, CCITT, RAW
ExtractMode	TEXT_ONLY, AUTO
ExtractReason	OK, SCANNED_NO_TEXT_LAYER, GLYPH_MAPPING_MISSING, ENCRYPTED_NO_EXTRACT_PERMISSION, IMAGE_TABLE_NO_STRUCTURE, CHART_NOT_TRANSCRIBED, OCR_REQUESTED_BUT_UNAVAILABLE, OCR_LOW_CONFIDENCE, EMPTY
PageClass	TEXT_LAYER, SCANNED, MIXED
PixelFormat	RGBA_8888, RGB_888, GRAY_8, PNG
PolicyMode	COMPAT, STRICT
SignatureLevel	B_B, B_T, B_LT
PdfALevel	A_1B, A_1A, A_2B, A_2A, A_2U, A_3B, A_3A, A_3U, A_4, A_4E, A_4F
PdfXLevel	X_1A_2001, X_1A_2003, X_3_2002, X_3_2003, X_4, X_4P, X_5G, X_5N, X_5PG, X_6, X_6P, X_6N
PdfUaLevel	UA_1, UA_2 (cada uno expone code(): Int)
PdfErrorKind	PARSE, ENCRYPTED, PERMISSION, IO, OCR_UNAVAILABLE, SIGNATURE, INVALID_STATE, UNSUPPORTED, OTHER

---

Excepciones

Todos los fallos lanzan PdfException (una excepción no comprobada) o una de sus subclases específicas por tipo. El accesor kind() devuelve un PdfErrorKind.

import fyi.oxide.pdf.exception.PdfException

try {
    PdfDocument.open(bytes).use { doc ->
        println(doc.extractText(0))
    }
} catch (e: PdfException) {
    println("PDF error [${e.kind()}]: ${e.message}")
}

PdfException(message: String)
PdfException(kind: PdfErrorKind, message: String)
PdfException(kind: PdfErrorKind, message: String, cause: Throwable)

e.kind(): PdfErrorKind

Excepción	Causa
PdfParseException	PDF mal formado o corrupto
PdfEncryptedException	Documento cifrado abierto sin una contraseña válida
PdfPermissionException	Operación bloqueada por los permisos del documento
PdfIoException	Fallo de E/S subyacente
PdfOcrUnavailableException	Se solicitó OCR pero la característica ocr no está compilada
PdfSignatureException	Fallo de firma o de verificación de firma
PdfInvalidStateException	Operación no válida para el estado actual del handle
PdfUnsupportedException	Característica o formato no compatible

---

Ejemplo completo

import fyi.oxide.pdf.AutoExtractor
import fyi.oxide.pdf.DocumentEditor
import fyi.oxide.pdf.Pdf
import fyi.oxide.pdf.PdfDocument
import fyi.oxide.pdf.geometry.BBox
import fyi.oxide.pdf.producerOrNull

// --- Creation ---
val bytes = Pdf.fromMarkdown("# Report\n\nGenerated by PDF Oxide.").use { it.save() }

// --- Extraction ---
PdfDocument.open(bytes).use { doc ->
    println("Pages: ${doc.pageCount()}")
    println("Producer: ${doc.producerOrNull() ?: "(none)"}")

    val page = doc.page(0)
    println("Words: ${page.words().map { it.text() }}")
    println("Tables: ${page.tables().size}")

    // Case-insensitive search
    val matches = doc.search("Report", caseInsensitive = true, regex = false, maxResults = 0)
    matches.forEach { m -> println("p${m.pageIndex()} '${m.text()}' @ ${m.bbox()}") }

    // Adaptive extraction
    val result = AutoExtractor.balanced(doc).extractDocument()
    println("confidence=${result.confidence()} ocr=${result.ocrUsed()}")
}

// --- Editing: redact + fill forms ---
DocumentEditor.open(bytes).use { editor ->
    editor.setFormField("name", "Jane Doe")
        .addRedaction(0, BBox(72.0, 700.0, 272.0, 720.0))
        .scrubMetadata()
    val redaction = editor.applyRedactionsDestructive()
    println("Redacted ${redaction.regionsApplied()} regions")
    val out: ByteArray = editor.save()
}

Other Language Bindings

PDF Oxide ofrece bindings nativos para todos los ecosistemas principales: Rust, Python, Node.js, WASM, C#, Golang, Java, PHP, Ruby, C++, Swift, Dart, R, Julia, Zig, Scala, Clojure, Objective-C y Elixir.

Próximos pasos

• Tipos y enums — todos los tipos y enums compartidos
• Referencia de la API Page — iteración de página consistente entre bindings
• Primeros pasos con Kotlin — tutorial