uvpdftool 0.0.0-stage → 0.2.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,75 @@
-# 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.3 and later, and from the
+command line: 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 command line
+
+The package installs `uvpdftool`, which uploads the files, runs the tool and saves the results
+beside them:
+
+```sh
+npm install -g uvpdftool
+export UVPDFTOOL_API_KEY=uvp_test_...
+
+uvpdftool compress report.pdf --set method=ghostscript --set preset=ebook
+uvpdftool office-to-pdf proposal.docx contract.docx -o pdfs
+uvpdftool ocr scan.pdf --set 'languages=["eng","hin"]' --json
+uvpdftool tools      # what each tool takes, and its options
+uvpdftool account    # the key in use, and the API tasks left
+```
+
+The key comes from `--key`, `UVPDFTOOL_API_KEY` or `UVPDF_KEY`. Each `--set` is one option of
+the tool, read as JSON where it can be; `--options '{...}'` gives them all at once. A result never
+replaces a file of the same name unless `--force` is given; a number is added instead. The exit
+code is 0 when done, 1 when the API refused or the job failed, and 2 when the command was wrong.
+
+The tools, their options and the errors are documented at
+<https://uvpdftool.com/developers>.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { main } from './command.js';
+// The command line itself: what it does is in command.ts, where the tests reach it.
+void main(process.argv.slice(2), {
+    env: process.env,
+    cwd: process.cwd(),
+    stdout: (text) => process.stdout.write(text),
+    stderr: (text) => process.stderr.write(text),
+}).then((code) => {
+    process.exitCode = code;
+});

package/dist/command.d.ts

@@ -0,0 +1,13 @@
+/** One `--set name=value`: the value as JSON where it parses, as text otherwise. */
+export declare function parseSetting(setting: string): [string, unknown];
+export interface Io {
+    env: Record<string, string | undefined>;
+    cwd: string;
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+    /** Another fetch, for tests. */
+    fetch?: typeof fetch;
+}
+/** Runs the command line; resolves with the exit code: 0 done, 1 refused or failed, 2 misused. */
+export { contentTypeOf, safeName } from './files.js';
+export declare function main(argv: readonly string[], io: Io): Promise<number>;

package/dist/command.js

@@ -0,0 +1,211 @@
+import { createReadStream } from 'node:fs';
+import { mkdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { Readable } from 'node:stream';
+import { parseArgs } from 'node:util';
+import { contentTypeOf, safeName, saveResult } from './files.js';
+import { ApiError, JobFailedError, UvPdfTool, VERSION } from './index.js';
+/**
+ * The UV pdfTool API from the command line: `uvpdftool <tool> <file>...` uploads the files,
+ * runs the tool and saves what it made; `uvpdftool tools` and `uvpdftool account` answer the
+ * two questions a script asks first. Nothing but Node itself and this package.
+ */
+const HELP = `uvpdftool ${VERSION}: the UV pdfTool API from the command line.
+
+Usage:
+  uvpdftool <tool> <file>... [options]   Run a tool on the files and save the results
+  uvpdftool tools                        The tools, what they take and their options
+  uvpdftool account                      The key in use and the tasks left
+
+Options:
+  -k, --key <key>          The API key; or set UVPDFTOOL_API_KEY (or UVPDF_KEY)
+  -o, --out <folder>       Where to save the results (default: the current folder)
+  -s, --set <name=value>   One option of the tool; repeat for more. Values are read as
+                           JSON where they can be: --set preset=ebook --set linearize=true
+      --options <json>     All the tool's options as one JSON object
+      --keep <hours>       Keep the files on the server this long after the job, 1 to 24
+      --force              Overwrite files of the same name instead of adding a number
+      --json               Print the finished job as JSON
+  -q, --quiet              No progress on standard error
+  -h, --help               This help
+  -v, --version            The version
+
+Examples:
+  uvpdftool compress report.pdf --set method=ghostscript --set preset=ebook
+  uvpdftool office-to-pdf proposal.docx -o pdfs
+  uvpdftool ocr scan.pdf --set 'languages=["eng","hin"]'
+
+Tools, options and errors: https://uvpdftool.com/developers
+`;
+/** One `--set name=value`: the value as JSON where it parses, as text otherwise. */
+export function parseSetting(setting) {
+    const at = setting.indexOf('=');
+    if (at < 1)
+        throw new UsageError(`--set needs name=value, not "${setting}".`);
+    const name = setting.slice(0, at).trim();
+    const raw = setting.slice(at + 1);
+    try {
+        return [name, JSON.parse(raw)];
+    }
+    catch {
+        return [name, raw];
+    }
+}
+class UsageError extends Error {
+}
+/** Runs the command line; resolves with the exit code: 0 done, 1 refused or failed, 2 misused. */
+export { contentTypeOf, safeName } from './files.js';
+export async function main(argv, io) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: [...argv],
+            allowPositionals: true,
+            options: {
+                key: { type: 'string', short: 'k' },
+                out: { type: 'string', short: 'o' },
+                set: { type: 'string', short: 's', multiple: true },
+                options: { type: 'string' },
+                keep: { type: 'string' },
+                force: { type: 'boolean' },
+                json: { type: 'boolean' },
+                quiet: { type: 'boolean', short: 'q' },
+                help: { type: 'boolean', short: 'h' },
+                version: { type: 'boolean', short: 'v' },
+                'base-url': { type: 'string' },
+            },
+        });
+    }
+    catch (error) {
+        io.stderr(`${error instanceof Error ? error.message : String(error)}\n\n${HELP}`);
+        return 2;
+    }
+    const { values, positionals } = parsed;
+    if (values.version) {
+        io.stdout(`${VERSION}\n`);
+        return 0;
+    }
+    const [command, ...files] = positionals;
+    if (values.help || command === undefined || command === 'help') {
+        io.stdout(HELP);
+        return command === undefined && !values.help ? 2 : 0;
+    }
+    const apiKey = values.key ?? io.env.UVPDFTOOL_API_KEY ?? io.env.UVPDF_KEY ?? '';
+    if (apiKey === '') {
+        io.stderr('An API key is needed: --key, or UVPDFTOOL_API_KEY. Make one at https://uvpdftool.com/developers/keys\n');
+        return 2;
+    }
+    const client = new UvPdfTool({
+        apiKey,
+        userAgent: 'uvpdftool-cli',
+        ...(values['base-url'] ? { baseUrl: values['base-url'] } : {}),
+        ...(io.fetch ? { fetch: io.fetch } : {}),
+    });
+    try {
+        if (command === 'tools') {
+            const tools = await client.tools();
+            if (values.json)
+                io.stdout(`${JSON.stringify(tools, null, 2)}\n`);
+            else {
+                for (const tool of tools) {
+                    io.stdout(`${tool.id}\n  takes ${tool.accepts.join(', ')}; up to ${String(tool.maxFiles)} files\n`);
+                    const names = Object.keys(tool.options.properties ?? {});
+                    if (names.length > 0)
+                        io.stdout(`  options: ${names.join(', ')}\n`);
+                }
+            }
+            return 0;
+        }
+        if (command === 'account') {
+            const account = await client.account();
+            if (values.json)
+                io.stdout(`${JSON.stringify(account, null, 2)}\n`);
+            else {
+                io.stdout(`${account.key.name} (${account.key.mode}, ${account.key.prefix}…)\n` +
+                    `API tasks left: ${String(account.tasks)}\n` +
+                    `Test jobs left today: ${String(account.test.left)} of ${String(account.test.perDay)}\n`);
+            }
+            return 0;
+        }
+        if (files.length === 0) {
+            // A tool that takes no files (web-to-pdf) runs on its options alone.
+            const known = (await client.tools()).find((tool) => tool.id === command);
+            if (!known || known.accepts.length > 0) {
+                throw new UsageError(`Name the files for ${command}.`);
+            }
+        }
+        const options = {};
+        if (values.options !== undefined) {
+            let given;
+            try {
+                given = JSON.parse(values.options);
+            }
+            catch {
+                throw new UsageError('--options must be a JSON object.');
+            }
+            if (typeof given !== 'object' || given === null || Array.isArray(given)) {
+                throw new UsageError('--options must be a JSON object.');
+            }
+            Object.assign(options, given);
+        }
+        for (const setting of values.set ?? []) {
+            const [name, value] = parseSetting(setting);
+            options[name] = value;
+        }
+        const keep = values.keep === undefined ? undefined : Number(values.keep);
+        if (keep !== undefined && (!Number.isInteger(keep) || keep < 1 || keep > 24)) {
+            throw new UsageError('--keep takes a whole number of hours, 1 to 24.');
+        }
+        const inputs = [];
+        for (const file of files) {
+            const full = path.resolve(io.cwd, file);
+            const info = await stat(full).catch(() => null);
+            if (!info?.isFile())
+                throw new UsageError(`${file}: no such file.`);
+            inputs.push({
+                name: path.basename(full),
+                contentType: contentTypeOf(full),
+                size: info.size,
+                data: Readable.toWeb(createReadStream(full)),
+            });
+        }
+        const quiet = values.quiet === true;
+        if (!quiet)
+            io.stderr(`${command}: uploading ${String(inputs.length)} file(s)…\n`);
+        const job = await client.run({
+            tool: command,
+            files: inputs,
+            ...(Object.keys(options).length > 0 ? { options } : {}),
+            ...(keep !== undefined ? { retentionHours: keep } : {}),
+            onProgress: (fraction) => {
+                if (!quiet)
+                    io.stderr(`${command}: ${String(Math.round(fraction * 100))}%\n`);
+            },
+        });
+        const folder = path.resolve(io.cwd, values.out ?? '.');
+        await mkdir(folder, { recursive: true });
+        const saved = [];
+        for (const [index, output] of job.outputs.entries()) {
+            const data = await client.download(output);
+            saved.push(await saveResult(folder, safeName(output.name, index), data, values.force === true));
+        }
+        if (values.json)
+            io.stdout(`${JSON.stringify({ job, saved }, null, 2)}\n`);
+        else
+            for (const file of saved)
+                io.stdout(`${file}\n`);
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof UsageError) {
+            io.stderr(`${error.message}\n`);
+            return 2;
+        }
+        if (error instanceof JobFailedError || error instanceof ApiError) {
+            io.stderr(`${error.message}\n`);
+            return 1;
+        }
+        io.stderr(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}

package/dist/files.d.ts

@@ -0,0 +1,14 @@
+export declare const contentTypeOf: (file: string) => string;
+/**
+ * A result's name as a file in the output folder: its last part only, with the characters no
+ * system allows in a name replaced, so a name from the server can never reach another folder.
+ */
+export declare function safeName(name: string, index: number): string;
+/** A free path for `name` in `folder`: the name itself, or with " (2)", " (3)"… before the extension. */
+export declare function freePath(folder: string, name: string, force: boolean): Promise<string>;
+/**
+ * Saves a result as `name` in `folder`, under a free name unless `force`, and says where. The file
+ * is created only if nothing is there, so a result saved at the same moment, or a link put at the
+ * name, is never written over or through: the next free name is taken instead.
+ */
+export declare function saveResult(folder: string, name: string, data: Uint8Array, force: boolean): Promise<string>;

package/dist/files.js

@@ -0,0 +1,77 @@
+import { lstat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * Local files and the API: the content type to declare for a file, and a safe, free place to
+ * save a result, for the command line and for the MCP server alike.
+ */
+/** Content types by file extension, for what the tools take. */
+const TYPES = {
+    '.pdf': 'application/pdf',
+    '.doc': 'application/msword',
+    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    '.xls': 'application/vnd.ms-excel',
+    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    '.ppt': 'application/vnd.ms-powerpoint',
+    '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    '.odt': 'application/vnd.oasis.opendocument.text',
+    '.ods': 'application/vnd.oasis.opendocument.spreadsheet',
+    '.odp': 'application/vnd.oasis.opendocument.presentation',
+    '.rtf': 'application/rtf',
+    '.txt': 'text/plain',
+    '.csv': 'text/csv',
+    '.html': 'text/html',
+    '.htm': 'text/html',
+    '.md': 'text/markdown',
+    '.markdown': 'text/markdown',
+    '.epub': 'application/epub+zip',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+};
+export const contentTypeOf = (file) => TYPES[path.extname(file).toLowerCase()] ?? 'application/octet-stream';
+const RESERVED = /^(con|prn|aux|nul|com[0-9]|lpt[0-9])(\..*)?$/iu;
+/**
+ * A result's name as a file in the output folder: its last part only, with the characters no
+ * system allows in a name replaced, so a name from the server can never reach another folder.
+ */
+export function safeName(name, index) {
+    const last = name.split(/[\\/]/u).pop() ?? '';
+    // eslint-disable-next-line no-control-regex -- control characters are what is being removed
+    const cleaned = last.replace(/[<>:"|?*\u0000-\u001f]/gu, '_').replace(/^[.\s]+|[.\s]+$/gu, '');
+    if (cleaned === '')
+        return `result-${String(index + 1)}`;
+    return RESERVED.test(cleaned) ? `_${cleaned}` : cleaned;
+}
+// lstat: a link at the name counts as taken, even one that leads nowhere.
+const exists = async (file) => lstat(file).then(() => true, () => false);
+/** A free path for `name` in `folder`: the name itself, or with " (2)", " (3)"… before the extension. */
+export async function freePath(folder, name, force) {
+    const first = path.join(folder, name);
+    if (force || !(await exists(first)))
+        return first;
+    const extension = path.extname(name);
+    const stem = name.slice(0, name.length - extension.length);
+    for (let count = 2;; count += 1) {
+        const candidate = path.join(folder, `${stem} (${String(count)})${extension}`);
+        if (!(await exists(candidate)))
+            return candidate;
+    }
+}
+/**
+ * Saves a result as `name` in `folder`, under a free name unless `force`, and says where. The file
+ * is created only if nothing is there, so a result saved at the same moment, or a link put at the
+ * name, is never written over or through: the next free name is taken instead.
+ */
+export async function saveResult(folder, name, data, force) {
+    for (;;) {
+        const target = await freePath(folder, name, force);
+        try {
+            await writeFile(target, data, { flag: force ? 'w' : 'wx' });
+            return target;
+        }
+        catch (error) {
+            if (force || error.code !== 'EEXIST')
+                throw error;
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,161 @@
+export { contentTypeOf, freePath, safeName, saveResult } from './files.js';
+/**
+ * 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 const VERSION = "0.2.0";
+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,242 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+export { contentTypeOf, freePath, safeName, saveResult } from './files.js';
+/**
+ * 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'];
+export const VERSION = '0.2.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') ?? '';
+    // Hex only: then both are the same length in bytes, as timingSafeEqual needs.
+    return (/^[0-9a-f]{64}$/u.test(given) && timingSafeEqual(Buffer.from(given), Buffer.from(expected)));
+}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "uvpdftool",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "The UV pdfTool API from Node.js and the command line: 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",
+    "cli",
+    "uvpdftool"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18.3"
+  },
+  "exports": {
+    ".": {
+      "@pdftool/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "uvpdftool": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "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"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "typecheck": "tsc -p tsconfig.json"
+  }
 }