uvpdftool 0.1.0 → 0.2.0

package/README.md

@@ -1,8 +1,8 @@
 # uvpdftool
 
-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.
+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
@@ -50,5 +50,26 @@ A refused request throws `ApiError` (`status`, `code`, `message`, `details`,
 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

@@ -1,3 +1,4 @@
+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
@@ -119,6 +120,7 @@ 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<{

package/dist/index.js

@@ -1,4 +1,5 @@
 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
@@ -33,7 +34,7 @@ export class JobFailedError extends Error {
     }
 }
 const ENDED = ['done', 'failed', 'cancelled'];
-const VERSION = '0.1.0';
+export const VERSION = '0.2.0';
 const sleep = (ms, signal) => new Promise((resolve, reject) => {
     const timer = setTimeout(resolve, ms);
     signal?.addEventListener('abort', () => {
@@ -236,5 +237,6 @@ export function verifyWebhook(rawBody, signatureHeader, secret, toleranceSeconds
         .update(body)
         .digest('hex');
     const given = parts.get('v1') ?? '';
-    return (given.length === expected.length && timingSafeEqual(Buffer.from(given), Buffer.from(expected)));
+    // 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,7 +1,7 @@
 {
   "name": "uvpdftool",
-  "version": "0.1.0",
-  "description": "The UV pdfTool API from Node.js: compress, convert, OCR and check PDFs on UV pdfTool's servers.",
+  "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",
@@ -17,32 +17,31 @@
     "convert",
     "pdfa",
     "api",
+    "cli",
     "uvpdftool"
   ],
   "type": "module",
   "sideEffects": false,
   "engines": {
-    "node": ">=18"
+    "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"
   ],
-  "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",
@@ -50,5 +49,11 @@
     "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"
   }
-}
+}