PdfCraft headless SDK and REST service with Python and TypeScript bindings

What they did

The author opened PR #872 against storytold/pdfcraft to add a programmatic developer plane alongside the existing desktop UI and MCP server. They created crates/sdk (pdfcraft-sdk) as an in-process Rust SDK with C-ABI/FFI bindings, crates/rest (pdfcraft-rest) as an RFC 7807-compliant HTTP microservice with job queueing, bounded concurrency, bearer auth, and file spillover, and sdks/python (pdfcraft) as a PyO3 plus HTTP Python SDK. A TypeScript SDK was also included with typed fallbacks. They ran iterative adversarial architecture reviews using OpenAI Codex with a 'gpt-6-astra' Staff Architect persona, moving the design from 5/10 to 8/10 by adding fail-closed security (rejecting server-local paths in REST payloads, path traversal defense, PKCS#12 key zeroization, loopback-only binding), resource governance (bounded streaming, aggregate quotas, pagination node budgets), and a hexagonal OperationExecutor port decoupled from the automation engine. They verified with cargo test across sdk/rest/pyo3 (71 passing), pytest on the Python SDK (18-20 tests), npm test on TypeScript (9 passing), and Clippy under -D warnings with zero warnings.

How it went

All gates passed: 71 Rust tests, ~20 Python tests (one OCR skip), 9 TypeScript tests, zero Clippy warnings, layer boundary checks clean, and zero merge conflicts against main. The PR reached a self-declared 10/10 'ready for review' state with full APDFL feature parity across page layout, bookmarks, annotations, redaction, AcroForms, signatures, and rendering.

Worth knowing

Scores and the '10/10' status are self-assessed by the author via an AI persona, not independent review. The OCR test is skipped, so OCR coverage is unverified. TypeScript native bindings fall back to a typed NATIVE_UNAVAILABLE error rather than working locally. The PR is large and spans Rust, Python, and TypeScript, so reviewers face significant surface area. REST deliberately rejects server-local filesystem paths, which limits some server-side workflows.

Wiring

Order: (1) define the OperationExecutor port in crates/sdk and adapt the automation engine behind it; (2) build pdfcraft-sdk with typed Result<T, SdkError> and C-ABI/FFI exports; (3) build pdfcraft-rest on top of the SDK with axum-style handlers, RFC 7807 problem details, bearer auth middleware, a bounded job queue, and file spillover; (4) bind PyO3 in sdks/python wrapping the SDK plus an HTTP client path; (5) add sdks/typescript with a local client that throws PdfCraftError('NATIVE_UNAVAILABLE', 501) when bindings are absent. Config: REST binds 127.0.0.1 by default and requires explicit confirmation for non-loopback; bearer token via env; PYO3_PYTHON set for Clippy. Verify with cargo test -p pdfcraft-sdk -p pdfcraft-rest -p pdfcraft-pyo3, PYTHONPATH=sdks/python pytest, npm --prefix sdks/typescript test, cargo clippy -- -D warnings, and cargo xtask layers.

Try it yourself

Add a headless SDK and REST service to this repo alongside the existing CLI/MCP surface. Create a Rust crate exposing an OperationExecutor port (hexagonal) over the core engine, plus a REST microservice with RFC 7807 errors, bearer auth, bounded concurrency, async job IDs, and loopback-only binding by default. Reject server-local filesystem paths in REST payloads and validate all materialized path components against traversal. Add a Python SDK via PyO3 with an HTTP fallback, and a TypeScript SDK that throws a typed NATIVE_UNAVAILABLE error when native bindings are missing. Enforce #![forbid(unsafe_code)] and deny unwrap/expect, wrap engine calls in catch_unwind, and zeroize signing key material. Add tests for Rust, Python, and TypeScript, and run Clippy with -D warnings.