@docverse-pdf/server 1.1.1 → 1.1.2

package/dist/gotenberg.d.ts

@@ -0,0 +1,71 @@
+export interface GotenbergOptions {
+    /** Base URL of the Gotenberg service, e.g. `http://localhost:3000`. */
+    url?: string;
+    /** Per-request timeout in ms (default: 60_000). */
+    timeout?: number;
+    /** Optional Basic Auth credentials if Gotenberg is protected. */
+    basicAuth?: {
+        username: string;
+        password: string;
+    };
+    /** Extra headers to attach to every request (e.g. tracing headers). */
+    headers?: Record<string, string>;
+}
+export interface GotenbergConvertOptions {
+    /**
+     * Override the filename sent to Gotenberg. Gotenberg uses the file
+     * extension to decide which LibreOffice filter to apply, so make sure
+     * it matches the actual format (e.g. `input.docx`, `input.pptx`).
+     */
+    filename?: string;
+    /** Produce a PDF/A compliant document. */
+    pdfa?: 'PDF/A-1a' | 'PDF/A-2b' | 'PDF/A-3b';
+    /** Produce a PDF/UA compliant document (accessibility). */
+    pdfua?: boolean;
+    /** Force landscape orientation. */
+    landscape?: boolean;
+    /** LibreOffice native page range, e.g. "1-3,5". */
+    nativePageRanges?: string;
+    /** PDF metadata (title, author, subject, keywords, creator, ...). */
+    metadata?: Record<string, string>;
+    /** Per-call timeout override (ms). Falls back to client-level timeout. */
+    timeout?: number;
+}
+export interface GotenbergFile {
+    buffer: Buffer | Uint8Array;
+    filename: string;
+}
+/**
+ * Thin HTTP client for the Gotenberg document conversion service.
+ *
+ * The client is stateless — there is no `start()` / `stop()`. Instances
+ * are cheap; reuse one across requests to benefit from Node's undici
+ * HTTP keep-alive pool.
+ */
+export declare class GotenbergClient {
+    private readonly url;
+    private readonly timeout;
+    private readonly basicAuth?;
+    private readonly extraHeaders;
+    constructor(options?: GotenbergOptions);
+    /** Returns the normalized base URL (trailing slash stripped). */
+    get baseUrl(): string;
+    /**
+     * Health check against Gotenberg's `/health` endpoint.
+     * Returns `true` on any 2xx, `false` otherwise (including network errors).
+     */
+    ping(timeoutMs?: number): Promise<boolean>;
+    /**
+     * Convert a single document (DOCX, ODT, XLSX, PPTX, RTF, ...) to PDF via
+     * Gotenberg's LibreOffice route. Returns the PDF bytes.
+     */
+    convert(input: Buffer | Uint8Array, filenameOrOptions?: string | GotenbergConvertOptions): Promise<Buffer>;
+    /**
+     * Convert multiple documents in a single request. By default Gotenberg
+     * concatenates them into one PDF (the `merge=true` form field). Pass
+     * `merge: false` via a future option if you ever need zipped output,
+     * but for now we always merge — the common case for batch conversion.
+     */
+    convertMany(files: GotenbergFile[], options?: GotenbergConvertOptions): Promise<Buffer>;
+    private buildHeaders;
+}

package/dist/gotenberg.js

@@ -0,0 +1,142 @@
+// ═══════════════════════════════════════════════
+// GOTENBERG HTTP CLIENT
+// ═══════════════════════════════════════════════
+//
+// Gotenberg (https://gotenberg.dev) is a stateless HTTP API that wraps
+// LibreOffice and Chromium for document→PDF conversion. Running it as a
+// sidecar container lets the server SDK stay a thin HTTP client — no
+// local `soffice` process, no warm-pool management, no port juggling.
+//
+// Minimal docker-compose example:
+//   services:
+//     gotenberg:
+//       image: gotenberg/gotenberg:8
+//       ports: ["3000:3000"]
+//
+// Then on the Node side:
+//   const gotenberg = new GotenbergClient({ url: 'http://gotenberg:3000' });
+//   const pdf = await gotenberg.convert(docxBuffer, 'report.docx');
+/**
+ * Thin HTTP client for the Gotenberg document conversion service.
+ *
+ * The client is stateless — there is no `start()` / `stop()`. Instances
+ * are cheap; reuse one across requests to benefit from Node's undici
+ * HTTP keep-alive pool.
+ */
+export class GotenbergClient {
+    url;
+    timeout;
+    basicAuth;
+    extraHeaders;
+    constructor(options = {}) {
+        const url = (options.url ?? 'http://localhost:3000').replace(/\/+$/, '');
+        this.url = url;
+        this.timeout = options.timeout ?? 60_000;
+        this.basicAuth = options.basicAuth;
+        this.extraHeaders = { ...(options.headers ?? {}) };
+    }
+    /** Returns the normalized base URL (trailing slash stripped). */
+    get baseUrl() {
+        return this.url;
+    }
+    /**
+     * Health check against Gotenberg's `/health` endpoint.
+     * Returns `true` on any 2xx, `false` otherwise (including network errors).
+     */
+    async ping(timeoutMs = 2_000) {
+        try {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            try {
+                const res = await fetch(`${this.url}/health`, {
+                    method: 'GET',
+                    headers: this.buildHeaders(),
+                    signal: controller.signal,
+                });
+                return res.ok;
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Convert a single document (DOCX, ODT, XLSX, PPTX, RTF, ...) to PDF via
+     * Gotenberg's LibreOffice route. Returns the PDF bytes.
+     */
+    async convert(input, filenameOrOptions = 'input.docx') {
+        const opts = typeof filenameOrOptions === 'string'
+            ? { filename: filenameOrOptions }
+            : filenameOrOptions;
+        return this.convertMany([{ buffer: input, filename: opts.filename ?? 'input.docx' }], opts);
+    }
+    /**
+     * Convert multiple documents in a single request. By default Gotenberg
+     * concatenates them into one PDF (the `merge=true` form field). Pass
+     * `merge: false` via a future option if you ever need zipped output,
+     * but for now we always merge — the common case for batch conversion.
+     */
+    async convertMany(files, options = {}) {
+        if (files.length === 0) {
+            throw new Error('GotenbergClient.convertMany: at least one file is required');
+        }
+        const form = new FormData();
+        for (const f of files) {
+            const bytes = Buffer.from(f.buffer);
+            // Wrap in a Blob so FormData streams the raw bytes with no extra
+            // text encoding. Gotenberg inspects the filename's extension to pick
+            // the LibreOffice filter, so it must match the real format.
+            form.append('files', new Blob([bytes]), f.filename);
+        }
+        if (options.pdfa)
+            form.append('pdfa', options.pdfa);
+        if (options.pdfua)
+            form.append('pdfua', 'true');
+        if (options.landscape)
+            form.append('landscape', 'true');
+        if (options.nativePageRanges)
+            form.append('nativePageRanges', options.nativePageRanges);
+        if (files.length > 1)
+            form.append('merge', 'true');
+        if (options.metadata && Object.keys(options.metadata).length > 0) {
+            form.append('metadata', JSON.stringify(options.metadata));
+        }
+        const timeout = options.timeout ?? this.timeout;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeout);
+        try {
+            const res = await fetch(`${this.url}/forms/libreoffice/convert`, {
+                method: 'POST',
+                body: form,
+                headers: this.buildHeaders(),
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                const bodyText = await res.text().catch(() => '');
+                throw new Error(`Gotenberg returned ${res.status} ${res.statusText}: ${bodyText || '(empty body)'}`);
+            }
+            const arrayBuf = await res.arrayBuffer();
+            return Buffer.from(arrayBuf);
+        }
+        catch (err) {
+            if (err.name === 'AbortError') {
+                throw new Error(`Gotenberg request timed out after ${timeout}ms`);
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    buildHeaders() {
+        const headers = { ...this.extraHeaders };
+        if (this.basicAuth) {
+            const token = Buffer.from(`${this.basicAuth.username}:${this.basicAuth.password}`).toString('base64');
+            headers['Authorization'] = `Basic ${token}`;
+        }
+        return headers;
+    }
+}

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { PDFDocument } from './PDFDocument.js';
 export type { PageSize, TextBlock, SearchResult, AnnotationInfo, PageObjectInfo, FormField, Bookmark, RenderOptions, ImageInfo, TextObjectStyle, } from './PDFDocument.js';
 export { flattenXFDF, mergeXFDFIntoPDF } from './flattenXFDF.js';
-export { wordToPDF, LibreOfficePool, stopSharedUnoServer } from './wordToPDF.js';
+export { wordToPDF, LibreOfficePool, resetSharedGotenbergClient } from './wordToPDF.js';
 export type { ConvertOptions, PoolOptions } from './wordToPDF.js';
-export { UnoServer, UnoServerPool } from './unoServer.js';
-export type { UnoServerOptions, UnoServerPoolOptions, UnoServerStats, } from './unoServer.js';
+export { GotenbergClient } from './gotenberg.js';
+export type { GotenbergOptions, GotenbergConvertOptions, GotenbergFile, } from './gotenberg.js';

package/dist/index.js

@@ -1,4 +1,4 @@
 export { PDFDocument } from './PDFDocument.js';
 export { flattenXFDF, mergeXFDFIntoPDF } from './flattenXFDF.js';
-export { wordToPDF, LibreOfficePool, stopSharedUnoServer } from './wordToPDF.js';
-export { UnoServer, UnoServerPool } from './unoServer.js';
+export { wordToPDF, LibreOfficePool, resetSharedGotenbergClient } from './wordToPDF.js';
+export { GotenbergClient } from './gotenberg.js';

package/dist/wordToPDF.d.ts

@@ -1,21 +1,27 @@
-import { UnoServer, UnoServerPool } from './unoServer.js';
-import type { UnoServerOptions } from './unoServer.js';
+import { GotenbergClient } from './gotenberg.js';
+import type { GotenbergOptions, GotenbergConvertOptions } from './gotenberg.js';
 export interface ConvertOptions {
     format?: string;
-    mode?: 'process' | 'socket' | 'pool' | 'unoserver';
+    mode?: 'process' | 'socket' | 'pool' | 'gotenberg';
     socketUrl?: string;
     timeout?: number;
     /**
-     * When `mode: 'unoserver'`, reuse this instance instead of the module-level
-     * shared singleton. Pass a `UnoServer` for a single warm daemon, or a
-     * `UnoServerPool` for concurrent workers.
+     * When `mode: 'gotenberg'`, reuse this client instead of the module-level
+     * shared singleton. Create one `GotenbergClient` at app boot and pass it
+     * here to benefit from HTTP keep-alive.
      */
-    unoServer?: UnoServer | UnoServerPool;
+    gotenbergClient?: GotenbergClient;
     /**
-     * When `mode: 'unoserver'` and no `unoServer` is supplied, these options
-     * are used to lazily construct the shared singleton on the first call.
+     * When `mode: 'gotenberg'` and no `gotenbergClient` is supplied, these
+     * options are used to lazily construct the shared singleton on the first
+     * call (e.g. `{ url: 'http://gotenberg:3000' }`).
      */
-    unoServerOptions?: UnoServerOptions;
+    gotenbergOptions?: GotenbergOptions;
+    /**
+     * Extra per-conversion options forwarded to Gotenberg (pdfa, landscape,
+     * nativePageRanges, metadata, filename, ...).
+     */
+    gotenbergConvertOptions?: GotenbergConvertOptions;
 }
 export interface PoolOptions {
     workers?: number;
@@ -26,11 +32,13 @@ export interface PoolOptions {
 }
 export declare function wordToPDF(wordBuffer: Buffer | Uint8Array, optionsOrFormat?: string | ConvertOptions): Promise<Buffer>;
 /**
- * Stops and clears the shared unoserver singleton created lazily by
- * `wordToPDF(..., { mode: 'unoserver' })`. Safe to call even if nothing
- * was started. Useful in graceful-shutdown hooks.
+ * Clears the module-level Gotenberg client created lazily by
+ * `wordToPDF(..., { mode: 'gotenberg' })`. The client holds no OS
+ * resources (only Node's HTTP keep-alive sockets, which undici cleans up
+ * automatically), so this is only needed if you want the next call to
+ * pick up fresh `gotenbergOptions`.
  */
-export declare function stopSharedUnoServer(): Promise<void>;
+export declare function resetSharedGotenbergClient(): void;
 export declare class LibreOfficePool {
     private workers;
     private queue;

package/dist/wordToPDF.js

@@ -4,7 +4,7 @@ import { writeFileSync, readFileSync, unlinkSync, mkdirSync, existsSync } from '
 import { join } from 'path';
 import { tmpdir } from 'os';
 import { randomBytes } from 'crypto';
-import { UnoServer } from './unoServer.js';
+import { GotenbergClient } from './gotenberg.js';
 // ═══════════════════════════════════════════════
 // SIMPLE CONVERT (backward compatible)
 // ═══════════════════════════════════════════════
@@ -15,8 +15,8 @@ export async function wordToPDF(wordBuffer, optionsOrFormat = 'pdf') {
     const format = opts.format ?? 'pdf';
     const mode = opts.mode ?? 'process';
     const timeout = opts.timeout ?? 30000;
-    if (mode === 'unoserver') {
-        return convertViaUnoServer(wordBuffer, format, opts);
+    if (mode === 'gotenberg') {
+        return convertViaGotenberg(wordBuffer, opts);
     }
     if (mode === 'socket' && opts.socketUrl) {
         return convertViaSocket(wordBuffer, format, opts.socketUrl, timeout);
@@ -24,39 +24,34 @@ export async function wordToPDF(wordBuffer, optionsOrFormat = 'pdf') {
     return convertViaProcess(wordBuffer, format, timeout);
 }
 // ═══════════════════════════════════════════════
-// UNOSERVER MODE (warm LibreOffice, 200–500ms)
+// GOTENBERG MODE (HTTP sidecar service, recommended)
 // ═══════════════════════════════════════════════
-let sharedUnoServer = null;
-let sharedUnoServerStarting = null;
-async function getSharedUnoServer(options) {
-    if (sharedUnoServer && sharedUnoServer.isReady())
-        return sharedUnoServer;
-    if (sharedUnoServerStarting)
-        return sharedUnoServerStarting;
-    sharedUnoServerStarting = (async () => {
-        const server = new UnoServer(options);
-        await server.start();
-        sharedUnoServer = server;
-        sharedUnoServerStarting = null;
-        return server;
-    })();
-    return sharedUnoServerStarting;
+let sharedGotenbergClient = null;
+function getSharedGotenbergClient(options) {
+    if (sharedGotenbergClient)
+        return sharedGotenbergClient;
+    sharedGotenbergClient = new GotenbergClient(options);
+    return sharedGotenbergClient;
 }
 /**
- * Stops and clears the shared unoserver singleton created lazily by
- * `wordToPDF(..., { mode: 'unoserver' })`. Safe to call even if nothing
- * was started. Useful in graceful-shutdown hooks.
+ * Clears the module-level Gotenberg client created lazily by
+ * `wordToPDF(..., { mode: 'gotenberg' })`. The client holds no OS
+ * resources (only Node's HTTP keep-alive sockets, which undici cleans up
+ * automatically), so this is only needed if you want the next call to
+ * pick up fresh `gotenbergOptions`.
  */
-export async function stopSharedUnoServer() {
-    const server = sharedUnoServer;
-    sharedUnoServer = null;
-    sharedUnoServerStarting = null;
-    if (server)
-        await server.stop();
+export function resetSharedGotenbergClient() {
+    sharedGotenbergClient = null;
 }
-async function convertViaUnoServer(wordBuffer, format, opts) {
-    const instance = opts.unoServer ?? (await getSharedUnoServer(opts.unoServerOptions));
-    return instance.convert(wordBuffer, format);
+async function convertViaGotenberg(wordBuffer, opts) {
+    const client = opts.gotenbergClient ?? getSharedGotenbergClient(opts.gotenbergOptions);
+    const convertOpts = {
+        ...(opts.gotenbergConvertOptions ?? {}),
+    };
+    if (opts.timeout !== undefined && convertOpts.timeout === undefined) {
+        convertOpts.timeout = opts.timeout;
+    }
+    return client.convert(wordBuffer, convertOpts);
 }
 // ═══════════════════════════════════════════════
 // PROCESS MODE (original, 3-5s)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@docverse-pdf/server",
-  "version": "1.1.1",
-  "description": "DocVerse Server SDK — server-side PDF processing, XFDF merge, Word to PDF (unoserver + LibreOffice), image extraction",
+  "version": "1.1.2",
+  "description": "DocVerse Server SDK — server-side PDF processing, XFDF merge, Word to PDF (Gotenberg + LibreOffice), image extraction",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/dist/unoServer.d.ts

@@ -1,86 +0,0 @@
-export interface UnoServerOptions {
-    /** TCP port the unoserver daemon listens on for its own RPC (default: 2003). */
-    port?: number;
-    /**
-     * TCP port used by the underlying LibreOffice UNO socket. Must be unique per
-     * daemon — otherwise multiple daemons collide on the default 2002.
-     * (default: undefined = unoserver picks 2002, which only works for one daemon.)
-     */
-    unoPort?: number;
-    /** Host/interface the daemon binds to (default: 127.0.0.1). */
-    host?: string;
-    /** Path to the `unoserver` executable (default: auto-detect). */
-    unoserverPath?: string;
-    /** Path to the `unoconvert` client executable (default: auto-detect). */
-    unoconvertPath?: string;
-    /** Path to the LibreOffice `soffice` binary (passed to unoserver --executable). */
-    libreOfficePath?: string;
-    /**
-     * Dedicated UNO user-profile dir for this daemon (passed to unoserver
-     * --user-installation). **Must be an absolute filesystem path, not a
-     * `file://` URI** — unoserver converts it internally via `Path(...).as_uri()`.
-     */
-    userInstallation?: string;
-    /** Max time (ms) to wait for the daemon to become ready (default: 15000). */
-    startTimeout?: number;
-    /** Max time (ms) to wait for a single conversion (default: 30000). */
-    convertTimeout?: number;
-}
-export interface UnoServerPoolOptions extends Omit<UnoServerOptions, 'port' | 'unoPort' | 'userInstallation'> {
-    /** Number of parallel unoserver daemons (default: 2). */
-    workers?: number;
-    /** First daemon RPC port; each worker gets basePort+i (default: 2003). */
-    basePort?: number;
-    /**
-     * First LibreOffice UNO-socket port; each worker gets unoBasePort+i
-     * (default: 2100). Must be in a non-overlapping range with `basePort`.
-     */
-    unoBasePort?: number;
-    /** Base dir for per-worker user-profile dirs (default: os.tmpdir()/docverse_unoserver). */
-    tempDir?: string;
-}
-export interface UnoServerStats {
-    workers: number;
-    ready: number;
-    busy: number;
-    queued: number;
-}
-/**
- * Wraps a single `unoserver` daemon process and a matching `unoconvert` client.
- *
- * Requires the `unoserver` Python package on the host:
- *   pip install unoserver
- *
- * A single running daemon holds a warm LibreOffice instance, so conversions
- * typically complete in 200–500 ms — roughly 10× faster than cold `soffice
- * --convert-to` invocations.
- */
-export declare class UnoServer {
-    private proc;
-    private readonly opts;
-    private ready;
-    constructor(options?: UnoServerOptions);
-    get port(): number;
-    get host(): string;
-    isReady(): boolean;
-    start(): Promise<void>;
-    convert(input: Buffer | Uint8Array, format?: string): Promise<Buffer>;
-    stop(): Promise<void>;
-}
-/**
- * A pool of warm `unoserver` daemons, each listening on its own port.
- * Use this when you need concurrent conversions — jobs are dispatched
- * to the first idle worker, otherwise queued FIFO.
- */
-export declare class UnoServerPool {
-    private workers;
-    private queue;
-    private readonly opts;
-    private running;
-    constructor(options?: UnoServerPoolOptions);
-    start(): Promise<void>;
-    convert(input: Buffer | Uint8Array, format?: string): Promise<Buffer>;
-    private dispatch;
-    stop(): Promise<void>;
-    getStats(): UnoServerStats;
-}

package/dist/unoServer.js

@@ -1,378 +0,0 @@
-import { spawn, execSync } from 'child_process';
-import { createConnection } from 'net';
-import { resolve as resolvePath } from 'path';
-// ═══════════════════════════════════════════════
-// HELPERS
-// ═══════════════════════════════════════════════
-function which(cmd) {
-    try {
-        const out = execSync(`command -v ${cmd}`, { stdio: ['ignore', 'pipe', 'ignore'] })
-            .toString()
-            .trim();
-        return out || null;
-    }
-    catch {
-        return null;
-    }
-}
-function findUnoserver() {
-    const candidates = [
-        'unoserver',
-        '/usr/local/bin/unoserver',
-        '/usr/bin/unoserver',
-        '/opt/homebrew/bin/unoserver',
-    ];
-    for (const c of candidates) {
-        const resolved = c.startsWith('/') ? c : which(c);
-        if (resolved)
-            return resolved;
-    }
-    return 'unoserver';
-}
-function findUnoconvert() {
-    const candidates = [
-        'unoconvert',
-        '/usr/local/bin/unoconvert',
-        '/usr/bin/unoconvert',
-        '/opt/homebrew/bin/unoconvert',
-    ];
-    for (const c of candidates) {
-        const resolved = c.startsWith('/') ? c : which(c);
-        if (resolved)
-            return resolved;
-    }
-    return 'unoconvert';
-}
-function findSoffice() {
-    const candidates = [
-        '/usr/bin/soffice',
-        '/usr/bin/libreoffice',
-        '/usr/local/bin/soffice',
-        '/Applications/LibreOffice.app/Contents/MacOS/soffice',
-    ];
-    for (const c of candidates) {
-        try {
-            execSync(`${c} --version`, { stdio: 'ignore' });
-            return c;
-        }
-        catch { }
-    }
-    return undefined;
-}
-async function probePort(host, port, timeoutMs = 500) {
-    return new Promise((resolve) => {
-        const sock = createConnection({ host, port });
-        const timer = setTimeout(() => {
-            sock.destroy();
-            resolve(false);
-        }, timeoutMs);
-        sock.once('connect', () => {
-            clearTimeout(timer);
-            sock.end();
-            resolve(true);
-        });
-        sock.once('error', () => {
-            clearTimeout(timer);
-            resolve(false);
-        });
-    });
-}
-async function waitForPort(host, port, deadline) {
-    while (Date.now() < deadline) {
-        if (await probePort(host, port))
-            return;
-        await new Promise((r) => setTimeout(r, 250));
-    }
-    throw new Error(`unoserver did not become ready on ${host}:${port} within the timeout`);
-}
-// ═══════════════════════════════════════════════
-// SINGLE UNOSERVER DAEMON
-// ═══════════════════════════════════════════════
-/**
- * Wraps a single `unoserver` daemon process and a matching `unoconvert` client.
- *
- * Requires the `unoserver` Python package on the host:
- *   pip install unoserver
- *
- * A single running daemon holds a warm LibreOffice instance, so conversions
- * typically complete in 200–500 ms — roughly 10× faster than cold `soffice
- * --convert-to` invocations.
- */
-export class UnoServer {
-    proc = null;
-    opts;
-    ready = false;
-    constructor(options = {}) {
-        this.opts = {
-            port: options.port ?? 2003,
-            unoPort: options.unoPort,
-            host: options.host ?? '127.0.0.1',
-            unoserverPath: options.unoserverPath ?? findUnoserver(),
-            unoconvertPath: options.unoconvertPath ?? findUnoconvert(),
-            libreOfficePath: options.libreOfficePath ?? findSoffice(),
-            userInstallation: options.userInstallation
-                ? resolvePath(options.userInstallation)
-                : undefined,
-            startTimeout: options.startTimeout ?? 15000,
-            convertTimeout: options.convertTimeout ?? 30000,
-        };
-    }
-    get port() {
-        return this.opts.port;
-    }
-    get host() {
-        return this.opts.host;
-    }
-    isReady() {
-        return this.ready;
-    }
-    async start() {
-        if (this.ready)
-            return;
-        const args = ['--interface', this.opts.host, '--port', String(this.opts.port)];
-        if (this.opts.unoPort !== undefined) {
-            args.push('--uno-port', String(this.opts.unoPort));
-        }
-        if (this.opts.libreOfficePath) {
-            args.push('--executable', this.opts.libreOfficePath);
-        }
-        if (this.opts.userInstallation) {
-            args.push('--user-installation', this.opts.userInstallation);
-        }
-        const proc = spawn(this.opts.unoserverPath, args, {
-            stdio: ['ignore', 'pipe', 'pipe'],
-            detached: false,
-        });
-        this.proc = proc;
-        // Capture stderr so startup failures surface the real reason, not just a
-        // generic "did not become ready" timeout.
-        const stderrChunks = [];
-        proc.stderr?.on('data', (c) => stderrChunks.push(c));
-        // Also drain stdout (unoserver is quiet here but we must consume it to
-        // avoid filling the pipe buffer on some platforms).
-        proc.stdout?.on('data', () => { });
-        const collectStderr = () => Buffer.concat(stderrChunks).toString('utf8').trim();
-        let earlyExit = null;
-        const earlyExitPromise = new Promise((_, reject) => {
-            proc.once('exit', (code, signal) => {
-                this.ready = false;
-                this.proc = null;
-                if (earlyExit === null) {
-                    earlyExit = { code, signal };
-                    reject(new Error(`unoserver exited during startup (code=${code}, signal=${signal})\n` +
-                        `stderr:\n${collectStderr() || '(empty)'}`));
-                }
-            });
-        });
-        const spawnErrorPromise = new Promise((_, reject) => {
-            proc.once('error', (err) => {
-                this.ready = false;
-                reject(new Error(`unoserver spawn error: ${err.message}`));
-            });
-        });
-        const deadline = Date.now() + this.opts.startTimeout;
-        try {
-            await Promise.race([
-                waitForPort(this.opts.host, this.opts.port, deadline),
-                earlyExitPromise,
-                spawnErrorPromise,
-            ]);
-        }
-        catch (err) {
-            await this.stop();
-            if (earlyExit !== null) {
-                // Early-exit error is already descriptive; rethrow as-is.
-                throw err;
-            }
-            // Timeout path — attach whatever stderr we collected for debugging.
-            const stderr = collectStderr();
-            const message = `unoserver did not become ready on ${this.opts.host}:${this.opts.port} ` +
-                `within ${this.opts.startTimeout}ms\nstderr:\n${stderr || '(empty)'}`;
-            throw new Error(message);
-        }
-        this.ready = true;
-    }
-    async convert(input, format = 'pdf') {
-        if (!this.ready) {
-            throw new Error('UnoServer not started. Call .start() first.');
-        }
-        return new Promise((resolve, reject) => {
-            const args = [
-                '--host', this.opts.host,
-                '--port', String(this.opts.port),
-                '--convert-to', format,
-                '-', // input: stdin
-                '-', // output: stdout
-            ];
-            const client = spawn(this.opts.unoconvertPath, args, {
-                stdio: ['pipe', 'pipe', 'pipe'],
-            });
-            const chunks = [];
-            const errChunks = [];
-            let settled = false;
-            const timer = setTimeout(() => {
-                if (settled)
-                    return;
-                settled = true;
-                try {
-                    client.kill('SIGKILL');
-                }
-                catch { }
-                reject(new Error(`unoconvert timed out after ${this.opts.convertTimeout}ms`));
-            }, this.opts.convertTimeout);
-            client.stdout.on('data', (c) => chunks.push(c));
-            client.stderr.on('data', (c) => errChunks.push(c));
-            client.on('error', (err) => {
-                if (settled)
-                    return;
-                settled = true;
-                clearTimeout(timer);
-                reject(err);
-            });
-            client.on('close', (code) => {
-                if (settled)
-                    return;
-                settled = true;
-                clearTimeout(timer);
-                if (code === 0) {
-                    resolve(Buffer.concat(chunks));
-                }
-                else {
-                    const stderr = Buffer.concat(errChunks).toString('utf8').trim();
-                    reject(new Error(`unoconvert exited with code ${code}: ${stderr}`));
-                }
-            });
-            client.stdin.on('error', (err) => {
-                if (settled)
-                    return;
-                settled = true;
-                clearTimeout(timer);
-                reject(err);
-            });
-            client.stdin.end(Buffer.from(input));
-        });
-    }
-    async stop() {
-        this.ready = false;
-        const proc = this.proc;
-        this.proc = null;
-        if (!proc)
-            return;
-        try {
-            proc.kill('SIGTERM');
-        }
-        catch { }
-        // Give it a moment to exit cleanly, then force.
-        await new Promise((resolve) => {
-            const killTimer = setTimeout(() => {
-                try {
-                    proc.kill('SIGKILL');
-                }
-                catch { }
-                resolve();
-            }, 2000);
-            proc.once('exit', () => {
-                clearTimeout(killTimer);
-                resolve();
-            });
-        });
-    }
-}
-/**
- * A pool of warm `unoserver` daemons, each listening on its own port.
- * Use this when you need concurrent conversions — jobs are dispatched
- * to the first idle worker, otherwise queued FIFO.
- */
-export class UnoServerPool {
-    workers = [];
-    queue = [];
-    opts;
-    running = false;
-    constructor(options = {}) {
-        this.opts = {
-            workers: options.workers ?? 2,
-            basePort: options.basePort ?? 2003,
-            unoBasePort: options.unoBasePort ?? 2100,
-            tempDir: options.tempDir ?? `${process.env.TMPDIR ?? '/tmp'}/docverse_unoserver`,
-            startTimeout: options.startTimeout ?? 15000,
-            convertTimeout: options.convertTimeout ?? 30000,
-            host: options.host,
-            unoserverPath: options.unoserverPath,
-            unoconvertPath: options.unoconvertPath,
-            libreOfficePath: options.libreOfficePath,
-        };
-    }
-    async start() {
-        if (this.running)
-            return;
-        const { mkdirSync, existsSync } = await import('fs');
-        if (!existsSync(this.opts.tempDir)) {
-            mkdirSync(this.opts.tempDir, { recursive: true });
-        }
-        const servers = [];
-        for (let i = 0; i < this.opts.workers; i++) {
-            // unoserver expects a raw absolute path for --user-installation; passing
-            // a `file://` URI trips its internal `Path(...).as_uri()` and crashes.
-            const userInstallation = resolvePath(this.opts.tempDir, `worker_${i}`);
-            servers.push(new UnoServer({
-                port: this.opts.basePort + i,
-                unoPort: this.opts.unoBasePort + i,
-                host: this.opts.host,
-                unoserverPath: this.opts.unoserverPath,
-                unoconvertPath: this.opts.unoconvertPath,
-                libreOfficePath: this.opts.libreOfficePath,
-                userInstallation,
-                startTimeout: this.opts.startTimeout,
-                convertTimeout: this.opts.convertTimeout,
-            }));
-        }
-        await Promise.all(servers.map((s) => s.start()));
-        this.workers = servers.map((server) => ({ server, busy: false }));
-        this.running = true;
-    }
-    async convert(input, format = 'pdf') {
-        if (!this.running) {
-            throw new Error('UnoServerPool not started. Call .start() first.');
-        }
-        const buf = Buffer.from(input);
-        return new Promise((resolve, reject) => {
-            const idle = this.workers.find((w) => !w.busy);
-            if (idle) {
-                this.dispatch(idle, buf, format, resolve, reject);
-            }
-            else {
-                this.queue.push({ input: buf, format, resolve, reject });
-            }
-        });
-    }
-    dispatch(worker, buf, format, resolve, reject) {
-        worker.busy = true;
-        worker.server
-            .convert(buf, format)
-            .then(resolve, reject)
-            .finally(() => {
-            worker.busy = false;
-            const next = this.queue.shift();
-            if (next) {
-                this.dispatch(worker, next.input, next.format, next.resolve, next.reject);
-            }
-        });
-    }
-    async stop() {
-        this.running = false;
-        const pending = this.queue.splice(0);
-        for (const job of pending) {
-            job.reject(new Error('UnoServerPool stopped before job completed'));
-        }
-        await Promise.all(this.workers.map((w) => w.server.stop()));
-        this.workers = [];
-    }
-    getStats() {
-        return {
-            workers: this.workers.length,
-            ready: this.workers.filter((w) => w.server.isReady()).length,
-            busy: this.workers.filter((w) => w.busy).length,
-            queued: this.queue.length,
-        };
-    }
-}