uvpdftool 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UV ResearchLabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# uvpdftool
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The [UV pdfTool API](https://uvpdftool.com/developers) from Node.js 18 and later: compress,
+convert, OCR and check PDFs on UV pdfTool's servers. No dependencies; ES modules; types
+included.
+
+```sh
+npm install uvpdftool
+```
+
+```js
+import { readFile, writeFile } from 'node:fs/promises';
+import { UvPdfTool, JobFailedError } from 'uvpdftool';
+
+const client = new UvPdfTool({ apiKey: process.env.UVPDF_KEY });
+
+// Creates the job, uploads the file, starts it and waits for it.
+const job = await client.run({
+  tool: 'compress',
+  options: { method: 'ghostscript', preset: 'ebook' },
+  files: [
+    { name: 'report.pdf', data: await readFile('report.pdf'), contentType: 'application/pdf' },
+  ],
+});
+
+for (const output of job.outputs) {
+  await writeFile(output.name, await client.download(output));
+}
+```
+
+Make a key on the [API keys page](https://uvpdftool.com/developers/keys); a test key is free
+and marks its results. Keep the key on your server, never in a browser or an app.
+
+## What it does
+
+| Call                                                                              | Does                                                                                    |
+| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `new UvPdfTool({ apiKey, baseUrl? })`                                             | The client.                                                                             |
+| `client.run({ tool, options?, files, retentionHours?, onProgress?, timeoutMs? })` | Create, upload, start, wait; resolves with the finished job or throws `JobFailedError`. |
+| `client.download(output)`                                                         | The bytes of one output of a finished job.                                              |
+| `client.jobs.create(request)`                                                     | `POST /jobs`: the job and an upload link per file.                                      |
+| `client.jobs.upload(upload, data)`                                                | `PUT` the bytes to one link.                                                            |
+| `client.jobs.start(id)`, `.get(id)`, `.cancel(id)`                                | The three job calls.                                                                    |
+| `client.jobs.wait(id, { intervalMs?, timeoutMs?, onProgress?, signal? })`         | Polls until the job ends.                                                               |
+| `client.tools()`, `client.account()`                                              | `GET /tools`, `GET /account`.                                                           |
+| `verifyWebhook(rawBody, signatureHeader, secret)`                                 | True when a webhook delivery is genuine and fresh.                                      |
+
+A refused request throws `ApiError` (`status`, `code`, `message`, `details`,
+`retryAfterSeconds`); a job that fails or is cancelled throws `JobFailedError` (`job`,
+with `job.error`). A file is `{ name, data, contentType }` where `data` is a `Buffer`,
+`Uint8Array`, `ArrayBuffer`, `Blob` or a `ReadableStream` with `size`.
+
+The tools, their options and the errors are documented at
+<https://uvpdftool.com/developers>.

package/dist/index.d.ts

@@ -0,0 +1,159 @@
+/**
+ * The UV pdfTool API from Node.js 18 and later, with nothing to install besides this
+ * package: create a job, upload the files, start it, wait for it, download the result, or
+ * do all of that with one call. Documentation: https://uvpdftool.com/developers
+ */
+export declare const DEFAULT_BASE_URL = "https://uvpdftool.com/api/v1";
+export type JobState = 'created' | 'queued' | 'running' | 'done' | 'failed' | 'cancelled';
+export interface JobError {
+    code: string;
+    message: string;
+}
+export interface JobOutput {
+    name: string;
+    size: number;
+    contentType: string;
+    /** A download link, present once the job is done; good for fifteen minutes. */
+    url?: string;
+}
+export interface Job {
+    id: string;
+    tool: string;
+    mode: 'live' | 'test';
+    state: JobState;
+    progress: number | null;
+    error: JobError | null;
+    outputs: JobOutput[];
+    createdAt: string;
+    expiresAt: string;
+}
+export interface Upload {
+    name: string;
+    method: 'PUT';
+    url: string;
+    headers: Record<string, string>;
+}
+export interface FileDeclaration {
+    name: string;
+    size: number;
+    contentType: string;
+}
+/** A file to send: its bytes (or a stream of them, with the size), its name and type. */
+export interface FileInput {
+    name: string;
+    data: Uint8Array | ArrayBuffer | Blob | ReadableStream<Uint8Array>;
+    contentType: string;
+    /** Needed for a stream; read from the bytes otherwise. */
+    size?: number;
+}
+export interface CreateJobRequest {
+    tool: string;
+    options?: Record<string, unknown>;
+    files: FileDeclaration[];
+    /** How long the files and results are kept once the job has run, 1 to 24 hours (default 2). */
+    retentionHours?: number;
+}
+export interface RunRequest {
+    tool: string;
+    options?: Record<string, unknown>;
+    files: FileInput[];
+    retentionHours?: number;
+    /** Called with the job's progress, 0 to 1, while it runs. */
+    onProgress?: (fraction: number, job: Job) => void;
+    /** Give up waiting after this long; the job itself goes on. */
+    timeoutMs?: number;
+}
+export interface WaitOptions {
+    /** Between two reads of the job; default 2 seconds, growing to 5 after a minute. */
+    intervalMs?: number;
+    timeoutMs?: number;
+    onProgress?: (fraction: number, job: Job) => void;
+    signal?: AbortSignal;
+}
+export interface ToolInfo {
+    id: string;
+    accepts: string[];
+    produces: string;
+    maxFiles: number;
+    maxBytes: {
+        live: number;
+        test: number;
+    };
+    timeoutMinutes: number;
+    options: Record<string, unknown>;
+}
+export interface Account {
+    key: {
+        name: string;
+        mode: 'live' | 'test';
+        prefix: string;
+        scopes: string[];
+    };
+    tasks: number;
+    test: {
+        left: number;
+        perDay: number;
+    };
+}
+export interface ClientOptions {
+    /** uvp_live_… or uvp_test_… */
+    apiKey: string;
+    /** Another API address, for tests. */
+    baseUrl?: string;
+    /** Another fetch, for tests or a proxy. */
+    fetch?: typeof fetch;
+    /** Sent as the User-Agent after the library's own name. */
+    userAgent?: string;
+}
+/** A refused request: the status, the code to switch on, the message to show. */
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details: Record<string, unknown>;
+    /** From the Retry-After header of a 429, in seconds. */
+    readonly retryAfterSeconds: number | null;
+    constructor(status: number, code: string, message: string, details?: Record<string, unknown>, retryAfterSeconds?: number | null);
+}
+/** A job that ended failed or cancelled; `job.error` says why. */
+export declare class JobFailedError extends Error {
+    readonly job: Job;
+    constructor(job: Job);
+}
+export declare class UvPdfTool {
+    readonly jobs: {
+        create: (request: CreateJobRequest) => Promise<{
+            job: Job;
+            uploads: Upload[];
+        }>;
+        upload: (upload: Upload, data: FileInput['data']) => Promise<void>;
+        start: (id: string) => Promise<Job>;
+        get: (id: string) => Promise<Job>;
+        cancel: (id: string) => Promise<Job>;
+        wait: (id: string, options?: WaitOptions) => Promise<Job>;
+    };
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchFn;
+    private readonly userAgent;
+    constructor(options: ClientOptions);
+    /** The tools the API offers, with their limits and options. */
+    tools(): Promise<ToolInfo[]>;
+    /** The key in use, the API tasks left, and today's test jobs. */
+    account(): Promise<Account>;
+    /**
+     * Creates the job, uploads every file, starts it and waits for it. Resolves with the
+     * finished job, whose outputs carry download links; throws JobFailedError otherwise.
+     */
+    run(request: RunRequest): Promise<Job>;
+    /** The bytes of one output of a finished job. */
+    download(output: JobOutput): Promise<Uint8Array>;
+    private wait;
+    /** PUTs the bytes to the upload link, as they are, trying three times on a passing fault. */
+    private upload;
+    private request;
+}
+/**
+ * True when a webhook body came from UV pdfTool, unchanged, within `toleranceSeconds` of
+ * now. Check the raw body as it arrived, before parsing it.
+ */
+export declare function verifyWebhook(rawBody: string | Uint8Array, signatureHeader: string, secret: string, toleranceSeconds?: number, now?: number): boolean;

package/dist/index.js

@@ -0,0 +1,240 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+/**
+ * The UV pdfTool API from Node.js 18 and later, with nothing to install besides this
+ * package: create a job, upload the files, start it, wait for it, download the result, or
+ * do all of that with one call. Documentation: https://uvpdftool.com/developers
+ */
+export const DEFAULT_BASE_URL = 'https://uvpdftool.com/api/v1';
+/** A refused request: the status, the code to switch on, the message to show. */
+export class ApiError extends Error {
+    status;
+    code;
+    details;
+    /** From the Retry-After header of a 429, in seconds. */
+    retryAfterSeconds;
+    constructor(status, code, message, details = {}, retryAfterSeconds = null) {
+        super(`${code}: ${message}`);
+        this.name = 'ApiError';
+        this.status = status;
+        this.code = code;
+        this.details = details;
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
+/** A job that ended failed or cancelled; `job.error` says why. */
+export class JobFailedError extends Error {
+    job;
+    constructor(job) {
+        super(job.error
+            ? `${job.error.code}: ${job.error.message}`
+            : `The job ended ${job.state} without a result.`);
+        this.name = 'JobFailedError';
+        this.job = job;
+    }
+}
+const ENDED = ['done', 'failed', 'cancelled'];
+const VERSION = '0.1.0';
+const sleep = (ms, signal) => new Promise((resolve, reject) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener('abort', () => {
+        clearTimeout(timer);
+        reject(signal.reason instanceof Error ? signal.reason : new Error('Aborted'));
+    }, { once: true });
+});
+function sizeOf(file) {
+    if (file.data instanceof Uint8Array || file.data instanceof ArrayBuffer) {
+        return file.data.byteLength;
+    }
+    if (file.data instanceof Blob)
+        return file.data.size;
+    if (file.size === undefined)
+        throw new TypeError(`${file.name}: a stream needs its size.`);
+    return file.size;
+}
+function bodyOf(data) {
+    if (data instanceof Uint8Array) {
+        // A view over a plain buffer goes as it is; one over a shared buffer is copied, as fetch asks.
+        return data.buffer instanceof ArrayBuffer
+            ? data
+            : new Uint8Array(data);
+    }
+    return data;
+}
+export class UvPdfTool {
+    jobs;
+    apiKey;
+    baseUrl;
+    fetchFn;
+    userAgent;
+    constructor(options) {
+        if (!options.apiKey)
+            throw new TypeError('An API key is needed: uvp_live_… or uvp_test_…');
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/u, '');
+        this.fetchFn = options.fetch ?? globalThis.fetch;
+        this.userAgent = `uvpdftool-node/${VERSION}${options.userAgent ? ` ${options.userAgent}` : ''}`;
+        this.jobs = {
+            create: (request) => this.request('POST', '/jobs', request),
+            upload: (upload, data) => this.upload(upload, data),
+            start: async (id) => (await this.request('POST', `/jobs/${id}/start`)).job,
+            get: async (id) => (await this.request('GET', `/jobs/${id}`)).job,
+            cancel: async (id) => (await this.request('DELETE', `/jobs/${id}`)).job,
+            wait: (id, options) => this.wait(id, options),
+        };
+    }
+    /** The tools the API offers, with their limits and options. */
+    async tools() {
+        return (await this.request('GET', '/tools')).tools;
+    }
+    /** The key in use, the API tasks left, and today's test jobs. */
+    account() {
+        return this.request('GET', '/account');
+    }
+    /**
+     * Creates the job, uploads every file, starts it and waits for it. Resolves with the
+     * finished job, whose outputs carry download links; throws JobFailedError otherwise.
+     */
+    async run(request) {
+        const files = request.files.map((file) => ({
+            name: file.name,
+            size: sizeOf(file),
+            contentType: file.contentType,
+        }));
+        const { job, uploads } = await this.jobs.create({
+            tool: request.tool,
+            ...(request.options ? { options: request.options } : {}),
+            files,
+            ...(request.retentionHours !== undefined ? { retentionHours: request.retentionHours } : {}),
+        });
+        try {
+            await Promise.all(uploads.map((upload, index) => {
+                const file = request.files[index];
+                if (!file)
+                    throw new Error(`No file for upload ${upload.name}`);
+                return this.upload(upload, file.data);
+            }));
+            await this.jobs.start(job.id);
+        }
+        catch (error) {
+            // A job without its files would wait twenty minutes for them; end it now, task returned.
+            await this.jobs.cancel(job.id).catch(() => undefined);
+            throw error;
+        }
+        return this.wait(job.id, {
+            ...(request.onProgress ? { onProgress: request.onProgress } : {}),
+            ...(request.timeoutMs !== undefined ? { timeoutMs: request.timeoutMs } : {}),
+        });
+    }
+    /** The bytes of one output of a finished job. */
+    async download(output) {
+        if (!output.url)
+            throw new TypeError(`${output.name} has no download link yet.`);
+        const response = await this.fetchFn(output.url);
+        if (!response.ok) {
+            throw new ApiError(response.status, 'DOWNLOAD_FAILED', `The download answered ${String(response.status)}.`);
+        }
+        return new Uint8Array(await response.arrayBuffer());
+    }
+    async wait(id, options = {}) {
+        const started = Date.now();
+        let interval = options.intervalMs ?? 2000;
+        let last = -1;
+        for (;;) {
+            const job = await this.jobs.get(id);
+            if (job.progress !== null && job.progress !== last && options.onProgress) {
+                last = job.progress;
+                options.onProgress(job.progress, job);
+            }
+            if (job.state === 'done')
+                return job;
+            if (ENDED.includes(job.state))
+                throw new JobFailedError(job);
+            const waited = Date.now() - started;
+            if (options.timeoutMs !== undefined && waited > options.timeoutMs) {
+                throw new Error(`Still ${job.state} after ${String(Math.round(waited / 1000))} s.`);
+            }
+            if (options.intervalMs === undefined && waited > 60_000)
+                interval = 5000;
+            await sleep(interval, options.signal);
+        }
+    }
+    /** PUTs the bytes to the upload link, as they are, trying three times on a passing fault. */
+    async upload(upload, data) {
+        const stream = data instanceof ReadableStream;
+        for (let attempt = 1;; attempt += 1) {
+            try {
+                const response = await this.fetchFn(upload.url, {
+                    method: upload.method,
+                    headers: upload.headers,
+                    body: bodyOf(data),
+                    ...(stream ? { duplex: 'half' } : {}),
+                });
+                if (response.ok)
+                    return;
+                if (response.status < 500 || attempt === 3 || stream) {
+                    throw new ApiError(response.status, 'UPLOAD_FAILED', `The upload of ${upload.name} answered ${String(response.status)}.`);
+                }
+            }
+            catch (error) {
+                if (error instanceof ApiError || attempt === 3 || stream)
+                    throw error;
+            }
+            await sleep(500 * attempt);
+        }
+    }
+    async request(method, path, body) {
+        for (let attempt = 1;; attempt += 1) {
+            const response = await this.fetchFn(`${this.baseUrl}${path}`, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    Accept: 'application/json',
+                    'User-Agent': this.userAgent,
+                    ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+                },
+                ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+            });
+            const text = await response.text();
+            let parsed;
+            try {
+                parsed = text ? JSON.parse(text) : null;
+            }
+            catch {
+                parsed = null;
+            }
+            if (response.ok)
+                return parsed;
+            const problem = parsed?.error;
+            const retryAfter = Number(response.headers.get('retry-after'));
+            const error = new ApiError(response.status, problem?.code ?? 'HTTP_ERROR', problem?.message ?? `The API answered ${String(response.status)}.`, problem?.details ?? {}, Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : null);
+            // One minute's worth of requests spent: wait what the API asks, once, then go on.
+            if (error.code === 'TOO_MANY_REQUESTS' && attempt === 1 && error.retryAfterSeconds !== null) {
+                await sleep(Math.min(error.retryAfterSeconds, 60) * 1000);
+                continue;
+            }
+            throw error;
+        }
+    }
+}
+/**
+ * True when a webhook body came from UV pdfTool, unchanged, within `toleranceSeconds` of
+ * now. Check the raw body as it arrived, before parsing it.
+ */
+export function verifyWebhook(rawBody, signatureHeader, secret, toleranceSeconds = 300, now = Date.now()) {
+    const parts = new Map();
+    for (const part of signatureHeader.split(',')) {
+        const at = part.indexOf('=');
+        if (at > 0)
+            parts.set(part.slice(0, at).trim(), part.slice(at + 1).trim());
+    }
+    const t = Number(parts.get('t'));
+    if (!Number.isInteger(t) || Math.abs(now / 1000 - t) > toleranceSeconds)
+        return false;
+    const body = typeof rawBody === 'string' ? Buffer.from(rawBody, 'utf8') : Buffer.from(rawBody);
+    const expected = createHmac('sha256', secret)
+        .update(`${String(t)}.`)
+        .update(body)
+        .digest('hex');
+    const given = parts.get('v1') ?? '';
+    return (given.length === expected.length && timingSafeEqual(Buffer.from(given), Buffer.from(expected)));
+}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "uvpdftool",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The UV pdfTool API from Node.js: compress, convert, OCR and check PDFs on UV pdfTool's servers.",
+  "license": "MIT",
+  "author": "UV ResearchLabs",
+  "homepage": "https://uvpdftool.com/developers",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/uvresearchlab/UV-pdfTool",
+    "directory": "packages/sdk-node"
+  },
+  "keywords": [
+    "pdf",
+    "compress",
+    "ocr",
+    "convert",
+    "pdfa",
+    "api",
+    "uvpdftool"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.13.6",
+    "eslint": "^10.11.0",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "^8.70.0",
+    "vitest": "^4.1.12"
+  }
+}