141 lines
3.8 KiB
Markdown
141 lines
3.8 KiB
Markdown
# OpenSpec Change: enterprise-server-pdf
|
|
|
|
- **Change ID**: enterprise-server-pdf
|
|
- **Package**: `@suaveplan/pdf`
|
|
- **Category**: server/services
|
|
- **Target path**: `server/services/pdf`
|
|
- **Status**: PROPOSED
|
|
- **Date**: 2026-04-24
|
|
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/pdf.md`
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Deliver `@suaveplan/pdf` on the genesis branch from scratch at enterprise quality. The package provides server-side PDF generation for receipts, reports, and invoices. It exposes a `PdfBuilder` with a fluent page/section/element composition API and a pluggable `PdfRenderer` interface, shipping two concrete renderers: a `PuppeteerRenderer` (HTML → PDF via headless Chrome) and a `PdfKitRenderer` (pure JS, no browser dependency). Zod-validated options, `@suaveplan/error` codes, OTel spans per render, `@suaveplan/templates` for HTML template rendering, and `AbortSignal` support for long renders.
|
|
|
|
---
|
|
|
|
## Current-state audit (genesis)
|
|
|
|
Does not exist on genesis — fresh build.
|
|
|
|
---
|
|
|
|
## Available workspace deps on genesis
|
|
|
|
| Package | Role |
|
|
|---|---|
|
|
| `@suaveplan/error` (`workspace:^`) | Typed `PDF.*` error codes |
|
|
| `@suaveplan/types` (`workspace:^`) | `LoggerLike` |
|
|
| `@suaveplan/templates` (`workspace:^`) | HTML template rendering |
|
|
| `@suaveplan/logger` (`workspace:^`) | Structured logs |
|
|
| `zod` (`catalog:forms`) | Options validation |
|
|
| `@opentelemetry/api` (`catalog:observability`) | Spans + counters + histograms |
|
|
| `puppeteer-core` (`catalog:services`) | Headless Chrome (optional renderer) |
|
|
| `pdfkit` (`catalog:services`) | Pure-JS PDF generation (optional renderer) |
|
|
| `tslib` (`catalog:build`) | Runtime helpers |
|
|
|
|
---
|
|
|
|
## Public API surface
|
|
|
|
```ts
|
|
interface PdfRenderer {
|
|
render(document: PdfDocument, options?: RenderOptions): Promise<Uint8Array>
|
|
dispose(): Promise<void>
|
|
}
|
|
|
|
class PdfBuilder {
|
|
page(options?: PageOptions): this
|
|
text(content: string, options?: TextOptions): this
|
|
heading(content: string, level?: 1 | 2 | 3): this
|
|
table(data: TableData, options?: TableOptions): this
|
|
image(src: string | Uint8Array, options?: ImageOptions): this
|
|
spacer(height?: number): this
|
|
footer(content: string): this
|
|
header(content: string): this
|
|
build(): PdfDocument
|
|
}
|
|
|
|
function createPdfBuilder(): PdfBuilder
|
|
function createPuppeteerRenderer(options?: PuppeteerRendererOptions): PdfRenderer
|
|
function createPdfKitRenderer(options?: PdfKitRendererOptions): PdfRenderer
|
|
|
|
interface PdfDocument {
|
|
pages: PdfPage[]
|
|
metadata: PdfMetadata
|
|
}
|
|
|
|
interface PdfMetadata {
|
|
title?: string
|
|
author?: string
|
|
subject?: string
|
|
keywords?: string[]
|
|
creator?: string
|
|
}
|
|
|
|
interface RenderOptions {
|
|
signal?: AbortSignal
|
|
format?: 'A4' | 'Letter' | 'Legal'
|
|
landscape?: boolean
|
|
margins?: { top: number; right: number; bottom: number; left: number }
|
|
}
|
|
|
|
type PdfErrorCode =
|
|
| 'PDF_RENDER_FAILED'
|
|
| 'PDF_TIMEOUT'
|
|
| 'PDF_INVALID_CONTENT'
|
|
| 'PDF_RENDERER_UNAVAILABLE'
|
|
|
|
function registerPdfErrorCodes(): void
|
|
```
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
server/services/pdf/
|
|
package.json
|
|
tsconfig.json
|
|
vitest.config.ts
|
|
src/
|
|
index.ts
|
|
error-codes.ts
|
|
constants/index.ts
|
|
types/
|
|
pdf.types.ts
|
|
pdf.types.md
|
|
builder/
|
|
pdf-builder/
|
|
pdf-builder.ts
|
|
pdf-builder.md
|
|
pdf-builder.types.ts
|
|
pdf-builder.test.ts
|
|
index.ts
|
|
renderers/
|
|
puppeteer-renderer/
|
|
puppeteer-renderer.ts
|
|
puppeteer-renderer.md
|
|
puppeteer-renderer.types.ts
|
|
puppeteer-renderer.test.ts
|
|
index.ts
|
|
pdfkit-renderer/
|
|
pdfkit-renderer.ts
|
|
pdfkit-renderer.md
|
|
pdfkit-renderer.types.ts
|
|
pdfkit-renderer.test.ts
|
|
index.ts
|
|
tests/
|
|
integration.test.ts
|
|
```
|
|
|
|
---
|
|
|
|
## Impact
|
|
|
|
Downstream: invoice generation, report exports, document archiving. Server-only.
|
|
|
|
**Prerequisites on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/templates`, `@suaveplan/logger`.
|