@broadpaper/server 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,343 @@
+import { ReportData, Theme, ReportTemplate, AnyVersionTemplate, DataSource, BlockDefinition } from '@broadpaper/core';
+import { LicenseState, Entitlement } from '@broadpaper/license';
+export { BroadPaper, BroadPaperConfig, Entitlement, LicenseState, LicenseStatus, configure, resolveLicenseStatus } from '@broadpaper/license';
+import { IncomingMessage, ServerResponse, Server } from 'node:http';
+
+/**
+ * The wire protocol of the render service.
+ *
+ * This file is the contract between the service, the browser client and the
+ * .NET client under `dotnet/`. Every field here is JSON — a template, a theme
+ * and a data set are all host-defined documents — so the same shapes are
+ * expressible in any language, and the .NET types mirror these names exactly.
+ *
+ * Anything added here must be optional, because a client is always older than
+ * the service it is talking to.
+ */
+
+/** Which engine draws the pages. BroadPaper decides the pages either way. */
+type RenderBackend = "forme" | "chromium";
+interface RenderMetadata {
+    title?: string;
+    author?: string;
+    subject?: string;
+    keywords?: string[];
+    /** Document language, e.g. "en-GB". Required for PDF/UA. */
+    lang?: string;
+}
+/** A font to embed. Without one the engine falls back to its standard faces. */
+interface RenderFont {
+    family: string;
+    /** A path the service can read, a `data:` URI, or base64 in `bytes`. */
+    src?: string;
+    /** Base64-encoded TTF/OTF. Use this from a client that cannot share a filesystem. */
+    bytes?: string;
+    weight?: number;
+    style?: "normal" | "italic";
+}
+interface RenderRequest {
+    /** The saved template. Older schema versions are migrated on the way in. */
+    template: ReportTemplate | AnyVersionTemplate;
+    /** Runtime data, keyed by data source id. */
+    data?: ReportData;
+    theme?: Partial<Theme>;
+    dataSources?: DataSource[];
+    /** ISO-8601. Fixes the clock, which is one of the conditions for byte-identical output. */
+    now?: string;
+    locale?: string;
+    currency?: string;
+    timeZone?: string;
+    metadata?: RenderMetadata;
+    /** Overrides the service default, when the service permits it. */
+    backend?: RenderBackend;
+    fonts?: RenderFont[];
+    /** Tagged (accessible) PDF. */
+    tagged?: boolean;
+    /** PDF/UA-1 conformance. Needs an embeddable font. */
+    pdfUa?: boolean;
+    /** PDF/A conformance level. Needs an embeddable font. */
+    pdfA?: "2b" | "2u" | "2a" | "3b" | "3u" | "3a";
+    /** Hosts remote assets may be fetched from. May narrow the service's list, never widen it. */
+    network?: {
+        allowedHosts?: string[];
+    };
+    /** "pdf" returns the bytes; "json" returns {@link RenderJsonResponse}. Default "pdf". */
+    format?: "pdf" | "json";
+}
+/** One entry of a batch: the same template rendered against different data. */
+interface BatchItem {
+    /** Echoed back on the result, so a caller can match them up. */
+    id: string;
+    data?: ReportData;
+    theme?: Partial<Theme>;
+    metadata?: RenderMetadata;
+    now?: string;
+    locale?: string;
+    currency?: string;
+    timeZone?: string;
+}
+interface BatchRequest extends Omit<RenderRequest, "data" | "format"> {
+    items: BatchItem[];
+}
+interface RenderJsonResponse {
+    pdfBase64: string;
+    pages: number;
+    warnings: string[];
+    durationMs: number;
+    backend: RenderBackend;
+}
+interface BatchResponse {
+    results: Array<{
+        id: string;
+        ok: true;
+        pdfBase64: string;
+        pages: number;
+        warnings: string[];
+        durationMs: number;
+    } | {
+        id: string;
+        ok: false;
+        error: string;
+        code: RenderErrorCode;
+    }>;
+    backend: RenderBackend;
+    durationMs: number;
+}
+interface HealthResponse {
+    ok: boolean;
+    /** Backends this service can actually use right now. */
+    backends: RenderBackend[];
+    defaultBackend: RenderBackend;
+    active: number;
+    queued: number;
+    version: string;
+    /** The protocol revision, so a client can refuse a service it does not understand. */
+    protocol: number;
+    /**
+     * What this service's PDFs will come out as.
+     *
+     * Reported because the alternative is an operator discovering the answer in a
+     * finance report a customer has already been sent. `state: "unlicensed"` is a
+     * perfectly good answer in a development environment and a serious one in
+     * production, and only the operator can tell which they are looking at.
+     */
+    license?: {
+        state: LicenseState;
+        /** Null unless the licence is being honoured. */
+        entitlement: Entitlement | null;
+        /** ISO 8601, when a licence was readable. */
+        expiresAt: string | null;
+    };
+}
+type RenderErrorCode = "BAD_REQUEST" | "UNAUTHORISED" | "PAYLOAD_TOO_LARGE" | "BACKEND_UNAVAILABLE" | "TIMEOUT" | "TOO_MANY_PAGES" | "BUSY" | "RENDER_FAILED";
+interface ErrorResponse {
+    error: string;
+    code: RenderErrorCode;
+}
+/** Bumped when a change would break an older client. */
+declare const PROTOCOL_VERSION = 1;
+/** Response headers a client can read without parsing the body. */
+declare const HEADERS: {
+    readonly pages: "x-broadpaper-pages";
+    readonly warnings: "x-broadpaper-warnings";
+    readonly backend: "x-broadpaper-backend";
+    readonly durationMs: "x-broadpaper-duration-ms";
+};
+
+declare class RenderError extends Error {
+    readonly code: RenderErrorCode;
+    readonly status: number;
+    constructor(message: string, code: RenderErrorCode, status: number);
+}
+/**
+ * What a Chromium backend has to provide.
+ *
+ * Injected rather than imported, so this package never depends on Playwright
+ * and a service that only wants the browserless engine does not drag a browser
+ * into its image.
+ */
+interface ChromiumBackend {
+    render(opts: {
+        template: unknown;
+        data?: unknown;
+        theme?: unknown;
+        dataSources?: unknown;
+        now?: Date;
+        locale?: string;
+        currency?: string;
+        timeZone?: string;
+        metadata?: unknown;
+        network?: {
+            allowedHosts?: string[];
+            blockPrivateNetworks?: boolean;
+        };
+        customBlocksScript?: string;
+        timeoutMs?: number;
+        maxPages?: number;
+    }): Promise<{
+        pdf: Uint8Array;
+        pages: number;
+        warnings: Array<string | {
+            message: string;
+        }>;
+        durationMs: number;
+    }>;
+    close?(): Promise<void>;
+}
+interface RenderServiceOptions {
+    /** Which backend to use when a request does not name one. Default "forme". */
+    defaultBackend?: RenderBackend;
+    /**
+     * Backends a request may ask for. Defaults to whatever is available. Narrow
+     * it when you do not want callers choosing the expensive one.
+     */
+    allowedBackends?: RenderBackend[];
+    /** Custom blocks for the browserless backend: the host's own code, in process. */
+    blocks?: Array<BlockDefinition<never>>;
+    /** Custom blocks bundle for Chromium (an IIFE calling `BroadPaper.registerBlocks`). */
+    customBlocksScript?: string;
+    /** Fonts embedded in every render. A request may add to these, never replace them. */
+    fonts?: RenderFont[];
+    /** Chromium backend. Without one, only the browserless backend is available. */
+    chromium?: ChromiumBackend;
+    /** Concurrent renders. Default 4. */
+    concurrency?: number;
+    /** How long a request may wait for a slot before being refused. Default 30s. */
+    queueTimeoutMs?: number;
+    /** Per-render timeout. Default 60s. */
+    timeoutMs?: number;
+    /** Refuse documents longer than this. Default 500 pages. */
+    maxPages?: number;
+    /** Hosts remote assets may be fetched from. A request may narrow this, never widen it. */
+    allowedHosts?: string[];
+    /** Injected Forme entry point, so a host can pick the node, browser or worker build. */
+    renderer?: (doc: Record<string, unknown>) => Promise<{
+        pdf: Uint8Array;
+        layout?: unknown;
+        warnings?: string[];
+    }>;
+    log?: (message: string, detail?: Record<string, unknown>) => void;
+}
+interface RenderOutcome {
+    pdf: Uint8Array;
+    pages: number;
+    warnings: string[];
+    durationMs: number;
+    backend: RenderBackend;
+}
+declare class RenderService {
+    private readonly registry;
+    private readonly opts;
+    private active;
+    private readonly waiting;
+    constructor(options?: RenderServiceOptions);
+    /** Backends this service can actually use, in preference order. */
+    get backends(): RenderBackend[];
+    get defaultBackend(): RenderBackend;
+    get load(): {
+        active: number;
+        queued: number;
+    };
+    /**
+     * Renders one document.
+     *
+     * Throws {@link RenderError} for anything a caller can act on — a backend
+     * they may not use, a queue that never cleared, a document longer than the
+     * service permits — carrying the code and status the wire protocol names.
+     */
+    render(request: RenderRequest): Promise<RenderOutcome>;
+    /**
+     * Renders one template against many data sets — a monthly run, a mail merge.
+     *
+     * One failure does not fail the batch: each result carries its own outcome,
+     * because a caller sending five hundred clients wants the four hundred and
+     * ninety-nine that worked and a list of the one that did not.
+     */
+    renderBatch(request: BatchRequest): Promise<BatchResponse>;
+    close(): Promise<void>;
+    /**
+     * Migrates and validates the incoming template.
+     *
+     * A service takes JSON from over the wire — hand-written, generated, saved by
+     * a version of the designer nobody here has seen. Handing that straight to
+     * the renderer turns a missing `styles` block into "Cannot read properties of
+     * undefined (reading 'height')", which tells the caller nothing at all.
+     * Parsing first fills in every default the schema declares and names the
+     * field when it cannot.
+     */
+    private parse;
+    private pickBackend;
+    /**
+     * Narrows the network policy. A request may restrict what a render fetches;
+     * it may not reach anywhere the service was not already willing to go.
+     */
+    private allowedHosts;
+    private fonts;
+    private renderForme;
+    private renderChromium;
+    private withTimeout;
+    /**
+     * Waits for a slot, but not forever. An unbounded queue turns one busy minute
+     * into a pile of work whose callers have all given up, and then does it
+     * anyway.
+     */
+    private acquire;
+    private release;
+}
+
+/**
+ * HTTP in front of the render service.
+ *
+ * Two layers, on purpose. `createRenderHandler` is a plain Node
+ * `(req, res) => Promise<boolean>` that returns whether it handled the request,
+ * so it drops into an existing Express, Fastify, Connect or raw `http` app —
+ * most teams already have a service and do not want a second one to deploy.
+ * `createRenderServer` is that handler with a listener around it, for the teams
+ * that do.
+ *
+ * The routes are the whole API surface:
+ *
+ *   POST /render        → PDF bytes, or JSON with `format: "json"`
+ *   POST /render/batch  → one template, many data sets, JSON
+ *   GET  /health        → readiness, backends, load, protocol version
+ */
+
+interface RenderHandlerOptions extends RenderServiceOptions {
+    /** Shared-secret bearer token. Strongly recommended anywhere but a laptop. */
+    token?: string;
+    /** Maximum request body size in bytes. Default 25 MB. */
+    maxBodyBytes?: number;
+    /**
+     * Origins allowed to call this from a browser. `"*"` is the default because
+     * the token is what actually guards the endpoint; set it when you want the
+     * browser to enforce an origin too.
+     */
+    cors?: string | false;
+    /** Mount point, e.g. "/api/pdf". Default "". */
+    basePath?: string;
+    /** Reported by `/health`, so an operator can see what is deployed. */
+    version?: string;
+}
+interface RenderHandler {
+    (req: IncomingMessage, res: ServerResponse): Promise<boolean>;
+    service: RenderService;
+    close(): Promise<void>;
+}
+/**
+ * Builds the request handler. Returns `false` when the request was not one of
+ * ours, so a host can fall through to its own routes.
+ */
+declare function createRenderHandler(options?: RenderHandlerOptions): RenderHandler;
+interface RenderServer {
+    server: Server;
+    port: number;
+    service: RenderService;
+    close(): Promise<void>;
+}
+/** The handler, with a listener around it. */
+declare function createRenderServer(options?: RenderHandlerOptions & {
+    port?: number;
+    host?: string;
+}): Promise<RenderServer>;
+
+export { type BatchItem, type BatchRequest, type BatchResponse, type ChromiumBackend, type ErrorResponse, HEADERS, type HealthResponse, PROTOCOL_VERSION, type RenderBackend, RenderError, type RenderErrorCode, type RenderFont, type RenderHandler, type RenderHandlerOptions, type RenderJsonResponse, type RenderMetadata, type RenderOutcome, type RenderRequest, type RenderServer, RenderService, type RenderServiceOptions, createRenderHandler, createRenderServer };

package/dist/index.js

@@ -0,0 +1,23 @@
+import {
+  HEADERS,
+  PROTOCOL_VERSION,
+  RenderError,
+  RenderService,
+  createRenderHandler,
+  createRenderServer
+} from "./chunk-5GQOM7MG.js";
+
+// src/index.ts
+import { BroadPaper, configure, resolveLicenseStatus } from "@broadpaper/license";
+export {
+  BroadPaper,
+  HEADERS,
+  PROTOCOL_VERSION,
+  RenderError,
+  RenderService,
+  configure,
+  createRenderHandler,
+  createRenderServer,
+  resolveLicenseStatus
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @broadpaper/server — render BroadPaper templates to PDF on a server.\n *\n * The browserless engine by default, so this runs in a plain Node image with\n * no browser to install; Chromium is available by injecting it, for the cases\n * that want the browser's own text shaping.\n *\n *   import { createRenderServer } from \"@broadpaper/server\";\n *   const server = await createRenderServer({ token: process.env.TOKEN });\n *\n * Or mounted inside an app you already have:\n *\n *   const render = createRenderHandler({ basePath: \"/api/pdf\" });\n *   http.createServer(async (req, res) => { if (!(await render(req, res))) myApp(req, res); });\n */\nexport { RenderService, RenderError } from \"./service.js\";\nexport type { RenderServiceOptions, RenderOutcome, ChromiumBackend } from \"./service.js\";\nexport { createRenderHandler, createRenderServer } from \"./http.js\";\nexport type { RenderHandler, RenderHandlerOptions, RenderServer } from \"./http.js\";\nexport { PROTOCOL_VERSION, HEADERS } from \"./protocol.js\";\nexport type {\n  RenderBackend,\n  RenderRequest,\n  RenderMetadata,\n  RenderFont,\n  RenderJsonResponse,\n  BatchItem,\n  BatchRequest,\n  BatchResponse,\n  HealthResponse,\n  ErrorResponse,\n  RenderErrorCode\n} from \"./protocol.js\";\n\n/**\n * Licensing.\n *\n * A render service renders under *its own* licence, set once at startup from\n * `BROADPAPER_LICENSE` or here in code. A licence is deliberately not part of\n * the render request: the service decides what its output is, not its callers.\n */\nexport { BroadPaper, configure, resolveLicenseStatus } from \"@broadpaper/license\";\nexport type { BroadPaperConfig, Entitlement, LicenseState, LicenseStatus } from \"@broadpaper/license\";\n"],"mappings":";;;;;;;;;;AAyCA,SAAS,YAAY,WAAW,4BAA4B;","names":[]}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@broadpaper/server",
+  "version": "0.1.1",
+  "description": "Server-side PDF rendering for BroadPaper: an HTTP render service and a mountable handler, browserless by default.",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "Dockerfile",
+    "LICENSE",
+    "THIRD-PARTY-NOTICES.md"
+  ],
+  "bin": {
+    "broadpaper-server": "./dist/cli.js"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@broadpaper/blocks": "0.1.1",
+    "@broadpaper/core": "0.1.1",
+    "@broadpaper/license": "0.1.1",
+    "@broadpaper/forme": "0.1.1"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/cli.ts --format esm --dts --sourcemap --clean --external @broadpaper/core --external @broadpaper/blocks --external @broadpaper/forme --external @broadpaper/license --external @formepdf/core",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "serve": "node dist/cli.js"
+  }
+}