Referência da API Kotlin

A PDF Oxide oferece bindings idiomáticos para Kotlin/JVM (prontos para Android) como uma fachada fina sobre o maduro binding de Java fyi.oxide:pdf-oxide, que é o dono da única ponte nativa via JNI (a crate pdf_oxide_jni). O módulo Kotlin adiciona zero código nativo: ele reexporta os tipos de Java (PdfDocument, Pdf, PdfPage, DocumentEditor, PdfSigner, PdfValidator, AutoExtractor e os tipos de valor de geometria / texto / tabela / busca) e acrescenta açúcar sintático de Kotlin — extensões de Optional<T> para T? e use { } sobre os handles AutoCloseable.

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

A biblioteca nativa JNI (libpdf_oxide_jni) não vem incluída — carregue-a via System.loadLibrary("pdf_oxide_jni") (distribua o .so/.dylib no seu java.library.path, ou em jniLibs/<abi>/ no Android), ou aponte o NativeLoader de Java para ela com -Dfyi.oxide.pdf.lib.path=<path>.

Para a API de Java, veja a Referência da API Java. Para a API de Rust, veja a Referência da API Rust. Para detalhes dos tipos, veja Tipos e 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 os handles (PdfDocument, Pdf, DocumentEditor) implementam AutoCloseable, então o bloco use { } de Kotlin libera a memória nativa de forma determinística. Os erros lançam PdfException (e suas subclasses); veja Exceções.

---

PdfDocument

O ponto de entrada principal, somente leitura, para um PDF — abrir, extrair, converter, renderizar, buscar e inspecionar campos de formulário. As instâncias são donas de memória nativa e precisam ser fechadas; use use { }.

import fyi.oxide.pdf.PdfDocument

Métodos de Fábrica

PdfDocument.open(path: Path): PdfDocument

Abre um PDF a partir de um caminho do sistema de arquivos.

PdfDocument.open(path: String): PdfDocument

Abre um PDF a partir de um caminho em string.

PdfDocument.open(bytes: ByteArray): PdfDocument

Abre um PDF a partir de bytes em memória (por exemplo, baixados do S3 ou recebidos via HTTP).

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

Abre um PDF criptografado a partir de um caminho com a senha de usuário ou de proprietário.

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

Abre um PDF criptografado a partir de um caminho em string com uma senha.

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

Abre um PDF criptografado a partir de bytes com uma senha.

PdfDocument.open(stream: InputStream): PdfDocument

Abre um PDF lendo todos os bytes de um InputStream.

Chamadas Únicas Estáticas

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

Abre, extrai todo o texto e fecha em uma única chamada — para o caso simples em que você não precisa de um handle ativo.

Autenticação

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

Autentica um documento criptografado após abri-lo. Retorna true se a senha for correta.

Informações do Documento

doc.pageCount(): Int

Número de páginas do documento.

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

Metadados /Producer e /Creator do documento. Use as extensões de Kotlin producerOrNull() / creatorOrNull() para acesso baseado em null.

val doc.isOpen: Boolean

Indica se o handle nativo ainda está aberto (propriedade de Kotlin sobre o getter isOpen() de Java).

Extração de Texto

doc.extractText(pageIndex: Int): String

Extrai texto puro de uma única página (índice começando em zero).

doc.extractTextAuto(pageIndex: Int): String

Extrai texto com seleção automática de estratégia (recorre ao OCR para páginas digitalizadas quando o recurso de OCR está disponível).

doc.extractStructured(page: Int): String

Extrai uma representação estruturada (JSON) do texto e do layout da página.

Conversão

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

Converte o documento inteiro ou uma única página para Markdown.

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

Converte o documento inteiro ou uma única página para HTML.

Busca

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

Busca uma string literal no documento. Retorna as correspondências por página com suas bounding boxes.

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

Busca com sensibilidade a maiúsculas/minúsculas, regex e um limite de resultados (maxResults = 0 significa sem limite).

Formulários

doc.formFields(): List<FormField>

Obtém todos os campos AcroForm com seu tipo, valor, limites do widget e índice de página. Veja FormField.

Renderização

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

Renderiza uma página em bytes de imagem PNG no DPI padrão ou em um DPI especificado.

Acesso a Páginas

doc.page(index: Int): PdfPage

Obtém um handle PdfPage preguiçoso (lazy) para o índice indicado (começando em zero).

doc.pages(): List<PdfPage>

Obtém todas as páginas como uma lista.

doc.pagesStream(): Stream<PdfPage>

Obtém todas as páginas como um Stream de Java para processamento fluente.

Ciclo de Vida

doc.close()

Libera a memória nativa. Idempotente — uma segunda chamada não tem efeito. Prefira use { }.

---

PdfPage

Um handle de página preguiçoso (lazy) retornado por PdfDocument.page(), pages() ou pagesStream(). Todos os acessores delegam ao documento pai no momento do acesso.

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

Geometria

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

Documento pai, índice começando em zero, retângulos MediaBox / CropBox, dimensões em pontos PDF e rotação da página em graus.

Extração de Conteúdo

page.text(): String

Extrai todo o texto da página.

page.text(region: BBox): String

Extrai o texto dentro de uma região delimitada por uma bounding box.

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

Texto estruturado nas granularidades de palavra, linha e caractere.

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

Imagens extraídas, tabelas detectadas e anotações da página.

---

Pdf

Cria PDFs a partir de formatos de origem, divide por marcadores (bookmarks) e serializa. Implementa AutoCloseable.

import fyi.oxide.pdf.Pdf

Métodos de Fábrica

Pdf.fromMarkdown(markdown: String): Pdf

Cria um PDF a partir de conteúdo Markdown.

Pdf.fromHtml(html: String): Pdf

Cria um PDF a partir de conteúdo HTML.

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

Cria um PDF de múltiplas páginas a partir de uma lista de arrays de bytes de imagem, uma página por imagem.

Divisão

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

Planeja uma divisão por marcadores do sumário sem produzir a saída — retorna os segmentos (título, intervalo de páginas, nome de arquivo) que seriam criados.

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

Divide em múltiplos PDFs por nível de marcador. Retorna um array de bytes por segmento.

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

Helper estático: conta quantos segmentos uma divisão por marcadores no nível indicado produziria.

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

Helper estático: divide os bytes do PDF de origem por nível de marcador diretamente.

Salvamento

pdf.save(): ByteArray

Serializa o PDF em bytes.

pdf.saveTo(out: Path)

Grava o PDF em um arquivo.

val pdf.isOpen: Boolean
pdf.close()

Ciclo de vida (propriedade isOpen de Kotlin e close()). Prefira use { }.

---

DocumentEditor

Editor mutável para redação, preenchimento de formulários, limpeza de metadados e salvamentos incrementais. Implementa AutoCloseable. Os métodos setter retornam this para encadeamento fluente.

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 um documento para edição a partir de um caminho ou de bytes em memória.

Preenchimento de Formulários

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

Define o valor de um campo de texto/escolha pelo nome totalmente qualificado.

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

Define o estado de um campo checkbox/radio pelo nome.

Redação

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

Enfileira uma redação sobre uma região retangular em uma página.

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

Número de redações enfileiradas em uma página, ou em todo o documento.

editor.applyRedactionsDestructive(): RedactResult

Aplica permanentemente todas as redações enfileiradas, removendo o conteúdo subjacente. Retorna um RedactResult com a contagem aplicada e o status da verificação por oráculo.

Metadados

editor.scrubMetadata(): DocumentEditor

Remove os metadados do documento (dicionário Info, XMP) por privacidade.

Salvamento

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

Serializa o documento editado com uma reescrita completa.

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

Serializa usando uma atualização incremental (anexa as alterações, preservando os bytes originais).

val editor.isOpen: Boolean
editor.close()

Ciclo de vida. Prefira use { }.

---

AutoExtractor

Pipeline de extração adaptativa que classifica páginas (camada de texto vs. digitalizada), aplica OCR onde necessário e emite texto / Markdown / HTML com pontuações de confiança.

import fyi.oxide.pdf.AutoExtractor

Métodos de Fábrica

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

Cria um extrator sobre um documento, opcionalmente com uma AutoExtractConfig personalizada.

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

Configurações predefinidas que equilibram velocidade e fidelidade.

Extração

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

Extração de texto puro para o documento inteiro ou uma única página.

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

Extração adaptativa completa retornando um AutoResult (texto, Markdown/HTML opcionais, motivo, confiança, flag de OCR, regiões).

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

Variantes em modo automático da extração em nível de documento e de página.

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

Extração serializada como uma string JSON.

Classificação

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

Classifica o documento ou uma página, retornando um ClassifyResult (classe por página mais listas de páginas que precisam de OCR, que contêm gráficos ou que estão criptografadas).

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

Obtém a PageClass (TEXT_LAYER / SCANNED / MIXED) para uma página ou todas as páginas.

Acessores

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

O documento encapsulado e a configuração ativa.

---

MarkdownConverter

Conversor sem estado e thread-safe de PdfDocument para Markdown ou 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

Converte o documento inteiro ou uma única página para Markdown / HTML.

---

PdfSigner

Assina digitalmente e verifica PDFs com keystores PKCS#12 (níveis 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

Carrega um assinante a partir de um keystore PKCS#12 em disco ou em memória.

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

Assina os bytes do PDF com as SignOptions fornecidas (nível, motivo, local, contato, URL do TSA). Retorna o PDF assinado.

signer.verify(pdf: ByteArray): Boolean

Verifica todas as assinaturas de um PDF. Retorna true se todas as assinaturas forem criptograficamente válidas.

PdfSigner.classifyLevel(pdf: ByteArray): SignatureLevel

Helper estático: detecta o nível de conformidade PAdES de um PDF já assinado.

---

PdfValidator

Validação sem estado e thread-safe contra os níveis de conformidade PDF/A, PDF/X e PDF/UA.

import fyi.oxide.pdf.PdfValidator

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

Verificações booleanas rápidas de conformidade.

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

Validação completa retornando um ValidationResult com a lista de violações.

---

PdfPolicy

Controles globais de política de segurança que governam quais algoritmos criptográficos são permitidos.

import fyi.oxide.pdf.PdfPolicy

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

Lê ou define o PolicyMode ativo, e obtém os modos embutidos compat / strict / FIPS-strict.

---

Extensões de Kotlin

A única superfície adicionada pela fachada de Kotlin: conversores de Optional<T> para T? e o helper genérico orNull(). Importe de fyi.oxide.pdf.

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

Genérico: um Optional vazio se torna null.

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

/Producer e /Creator do documento, ou null se ausentes.

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

Valor do campo de formulário e bounding box do widget, ou null.

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

/Contents da anotação e URI de destino do link, ou null.

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

Renderização em Markdown / HTML de uma extração automática, ou null se não tiver sido produzida.

fun ValidationViolation.pageIndexOrNull(): Int?

Índice de página a que uma violação se aplica, ou null para regras em nível de documento.

---

Tipos de Geometria

BBox

Bounding box alinhada aos eixos, em pontos PDF.

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

Acessor	Tipo	Descrição
x0(), y0(), x1(), y1()	Double	Coordenadas dos cantos
width()	Double	x1 - x0
height()	Double	y1 - y0

Color

Cor RGBA de 8 bits com as constantes nomeadas Color.BLACK, Color.WHITE, Color.TRANSPARENT.

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

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

Point

Point(x: Double, y: Double)

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

Rect

Retângulo de posição mais tamanho.

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

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

---

Tipos de Texto

TextChar

Um único caractere extraído.

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

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

TextWord

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

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

TextLine

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

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

TextSpan

Uma sequência de texto com estilo idêntico.

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

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

TextStyle

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

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

---

Tipos de Tabela

Table

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

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

TableCell

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

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

---

Tipos de Busca

SearchMatch

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

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

SearchResult

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

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

SearchOptions

Opções imutáveis construídas por meio de um builder fluente. SearchOptions.DEFAULT é a instância padrão.

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

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

Nota: atualmente não está conectado a PdfDocument.search() — use em vez disso a sobrecarga caseInsensitive/regex/maxResults acima.

---

Tipos de Formulário

FormField

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

Acessores: name(): String, type(): FormFieldType, value(): Optional<String>, bbox(): Optional<BBox>, pageIndex(): Int. Use valueOrNull() / bboxOrNull() para acesso baseado em null.

---

Tipos de Anotação

Annotation

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

Acessores: type(): AnnotationType, pageIndex(): Int, bbox(): BBox, contents(): Optional<String>, uri(): Optional<String>. Use contentsOrNull() / uriOrNull() para acesso baseado em null.

---

Tipos de Imagem

ExtractedImage

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

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

---

Tipos de Extração Automática

AutoResult

Resultado de uma extração 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>

Use markdownOrNull() / htmlOrNull() para acesso baseado em null à saída renderizada.

RegionResult

Detalhe de extração por região dentro de um 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

Configuração imutável construída por meio de um builder fluente; AutoExtractConfig.DEFAULT é o padrão. Converta uma configuração existente de volta em um builder com 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()

Os acessores retornam Optional<...> para cada campo: mode(), forceOcrPages(), minOcrConfidence(), ocrLanguages(), passwords(), topMarginFraction(), bottomMarginFraction(), allowSingleColumnTables(), ocrInlineImages(), cancelToken(). Os setters do builder aceitam tanto sobrecargas boxed-nullable quanto primitivas (por exemplo, withMinOcrConfidence(Double?) e withTopMarginFraction(double)), além das formas varargs withOcrLanguages(vararg String) / withPasswords(vararg String).

---

Tipos de Conformidade

ValidationResult

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

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

ValidationViolation

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

Acessores: ruleId(): String, description(): String, pageIndex(): Optional<Int>. Use pageIndexOrNull() para acesso baseado em null.

---

Tipos de Metadados

DocumentInfo

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

Os acessores retornam todos Optional<String>: title(), author(), subject(), keywords(), creator(), producer(), creationDate(), modificationDate().

XmpMetadata

Pacote XMP bruto. XmpMetadata.EMPTY é a instância vazia.

XmpMetadata(xml: String)

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

---

Tipos de Segurança e Redação

SecurityPolicy

Política imutável construída por meio de um builder fluente.

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

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

RedactResult

RedactResult(regionsApplied: Int, oracleVerified: Boolean)

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

---

Tipos de Assinatura

SignOptions

Opções de assinatura imutáveis construídas por meio de um builder fluente.

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

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

---

Tipos de Divisão

BookmarkSegment

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

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

SplitByBookmarksOptions

Opções imutáveis construídas por meio de um builder fluente.

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

Acessores: level(): Int, filenamePrefix(): Optional<String>. Métodos do 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 um expõe code(): Int)
PdfErrorKind	PARSE, ENCRYPTED, PERMISSION, IO, OCR_UNAVAILABLE, SIGNATURE, INVALID_STATE, UNSUPPORTED, OTHER

---

Exceções

Todas as falhas lançam PdfException (uma exceção não verificada) ou uma de suas subclasses específicas por tipo. O acessor kind() retorna um 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

Exceção	Causa
PdfParseException	PDF malformado ou corrompido
PdfEncryptedException	Documento criptografado aberto sem uma senha válida
PdfPermissionException	Operação bloqueada pelas permissões do documento
PdfIoException	Falha de E/S subjacente
PdfOcrUnavailableException	OCR solicitado, mas o recurso ocr não foi compilado
PdfSignatureException	Falha de assinatura ou de verificação de assinatura
PdfInvalidStateException	Operação inválida para o estado atual do handle
PdfUnsupportedException	Recurso ou formato não suportado

---

Exemplo 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}")

    // Search case-insensitively
    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

O PDF Oxide oferece bindings nativos para todos os principais ecossistemas: Rust, Python, Node.js, WASM, C#, Golang, Java, PHP, Ruby, C++, Swift, Dart, R, Julia, Zig, Scala, Clojure, Objective-C e Elixir.

Próximos Passos

• Tipos e Enums — todos os tipos e enums compartilhados
• Referência da API Page — iteração consistente por página entre os bindings
• Primeiros Passos com Kotlin — tutorial