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)
Digest	(ctx, rs, …, digest func(T) error, conf)	fan results out yourself (extraction, rendering)

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
Page rasterizer	pkg/render (usually via api.RenderPages / api.Solidify)
Embedded OCR engine	pkg/ocr (usually via api.OCRFile)
Logging	pkg/log