Go API

Go API

Everything the CLI does is available as a Go API. pdfcpu2 keeps pdfcpu's four-layer architecture:

pkg/pdfcpu/model   — document model: XRefTable, Context, Configuration, option types
pkg/pdfcpu         — core operations (the pdfcpu package proper)
pkg/api            — high-level entry points (what you should call)
pkg/cli            — command-line plumbing (what the binary calls)

Use pkg/api. It handles reading, validation, optimization-on-write, encryption and error wrapping for you.

The three shapes

Every operation comes in up to three shapes — pick per use case:

Shape	Signature pattern	Use when
Streams	(ctx, rs io.ReadSeeker, w io.Writer, …)	piping, in-memory, network storage
Files	(ctx, inFile, outFile string, …)	simplest; staging handled for you
Incremental	…AsIncrement(ctx, rws io.ReadWriteSeeker, …)	append an update instead of rewriting (annotations)

package main

import (
	"context"
	"os"

	"github.com/huzpsb/pdfcpu2/pkg/api"
	"github.com/huzpsb/pdfcpu2/pkg/pdfcpu/model"
)

func main() {
	ctx := context.Background()

	// 1) In-memory defaults — no config dir involved
	conf := model.NewDefaultConfiguration()

	// 2) Or load the user's config dir (config.yml, fonts, certs)
	conf, err := api.LoadConfiguration(api.ConfigurationOptions{})
	if err != nil {
		panic(err)
	}

	f, err := os.Open("in.pdf")
	if err != nil {
		panic(err)
	}
	defer f.Close()

	out, err := os.Create("out.pdf")
	if err != nil {
		panic(err)
	}
	defer out.Close()

	// Stream shape: any reader/writer pair
	if err := api.Optimize(ctx, f, out, conf, nil); err != nil {
		panic(err)
	}
}

Conventions

• First argument is context.Context — every operation accepts cancellation and honors deadlines. Long batch jobs should pass a cancellable context.
• *model.Configuration carries global settings: passwords (UserPW, OwnerPW), encryption (EncryptUsingAES, EncryptKeyLength, Permissions), validation mode, writer behavior.
• Page selections are []string using the CLI syntax — see Page Selection.
• Description strings ("form:A4, pos:c") are parsed by exported constructors: api.PDFNUpConfig, api.PDFGridConfig, api.PDFBookletConfig, api.Import, api.Box, api.PageBoundaries. CLI and API share one grammar.
• Progress: operations with a *api.ProgressOptions parameter report stage callbacks — useful for UIs over big files.

Low-level pipeline

When you need full control:

ctx, err := api.ReadContextFile(c, "in.pdf")   // parse + validate
if err != nil { panic(err) }

// ...work on ctx.XRefTable / ctx.PageDicts directly...

if err := api.ValidateContext(c, ctx); err != nil { panic(err) }
if err := api.WriteContextFile(c, ctx, "out.pdf"); err != nil { panic(err) }

Error handling

Errors are wrapped with operation context and are safe to present to users. Panics inside core processing are caught at the API boundary (fault.Catch) and returned as errors — your process will not crash on malformed PDFs.

Package index

Need	Package
High-level operations	pkg/api
Option/model types	pkg/pdfcpu/model
Core operations, form types, bookmarks, text extraction types	pkg/pdfcpu
Color, geometry primitives	pkg/pdfcpu/types, pkg/pdfcpu/color
Embedded OCR engine	pkg/ocr (usually via api.OCRFile)
Logging	pkg/log