@nucleushq/marqpdf 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,60 @@
-# Temporary Holding Version
+# @nucleushq/marqpdf
 
-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 [MarqPDF API](https://marqpdf.com/developers) from JavaScript: compress PDFs to a target size, OCR scans (English and Arabic), convert to and from Word, Excel and PowerPoint, merge, split, rotate, watermark, protect and extract text.
+
+No dependencies. Node 18+, Deno, Bun.
+
+```sh
+npm install @nucleushq/marqpdf
+```
+
+Create an API key at [marqpdf.com → Account → Developers](https://marqpdf.com/?dev=keys) and set `MARQPDF_API_KEY`.
+
+```js
+import { MarqPDF } from "@nucleushq/marqpdf";
+
+const marq = new MarqPDF(); // reads MARQPDF_API_KEY
+
+// Inputs can be a local path, a URL, bytes, a Blob, or a file id from an earlier step.
+const job = await marq.compress("contract.pdf", { target_mb: 1 });
+await marq.download(job, "contract-small.pdf");
+
+// Steps chain on file ids.
+const scanned = await marq.ocr("scan.pdf");
+const small = await marq.compress(scanned.output.files[0], { target_mb: 2 });
+console.log(small.output.files[0].download_url); // works without a key for an hour
+
+const text = await marq.extractText("https://example.com/statement.pdf");
+console.log(text.output.text);
+
+// AI: fields as JSON, on MarqPDF's model or your own ("anthropic/claude-opus-5-5", …).
+const inv = await marq.extract("invoice.pdf", { fields: ["invoice_number", { name: "total", type: "number" }, { name: "due_date", type: "date" }] });
+console.log(inv.output.data); // { invoice_number: "INV-2041", total: 5136, due_date: "2025-04-13" }
+const a = await marq.ask("lease.pdf", { question: "When can the tenant terminate early?" });
+
+// Workflows: save a chain once, run it on any file.
+const wf = await marq.workflows.create("Scan to small PDF", [{ operation: "ocr" }, { operation: "compress", options: { target_mb: 1 } }]);
+const done = await marq.workflows.run(wf.id, "scan.pdf");
+
+// The agent: a goal in plain words; it picks the operations.
+const job = await marq.agent(["jan.pdf", "feb.pdf"], { goal: "Merge these and get the result under 2 MB" });
+console.log(job.output.text, job.output.steps);
+```
+
+Every operation: `compress`, `merge`, `split`, `rotate`, `organize`, `removePages`, `pageNumbers`, `watermark`, `protect`, `unlock`, `ocr`, `convert`, `imagesToPdf`, `compare`, `extractText`, the AI ones `extract`, `ask` and `agent`, or `run(operation, input, options)`. Each resolves with the finished job and throws `MarqPDFError` (with `status`, `code` and the `job`) if it fails.
+
+Also: `files.upload / list / get / delete / content`, `jobs.get / list / wait`, `workflows.create / list / get / delete / run / runSteps`, `models()`, `usage()`.
+
+## Webhooks
+
+```js
+import { verifyWebhook } from "@nucleushq/marqpdf";
+
+app.post("/hooks/marqpdf", express.raw({ type: "application/json" }), async (req, res) => {
+  if (!(await verifyWebhook(req.body, req.get("MarqPDF-Signature"), process.env.MARQPDF_WEBHOOK_SECRET))) return res.sendStatus(400);
+  const { type, data: job } = JSON.parse(req.body);
+  res.sendStatus(200);
+});
+```
+
+Free accounts include 100 operations a month; a Week Pass, Pro or Team plan is unlimited. Files are deleted after 24 hours. Full reference: https://marqpdf.com/developers

package/marqpdf.d.ts

@@ -0,0 +1,121 @@
+// Types for @nucleushq/marqpdf. The API reference: https://marqpdf.com/developers
+
+export type FileInput = string | { id: string } | ArrayBuffer | ArrayBufferView | Blob;
+
+export interface MarqFile {
+  object: "file";
+  id: string;
+  name: string;
+  size: number;
+  content_type: string;
+  pages?: number;
+  created_at: string;
+  expires_at: string;
+  source: "upload" | "url" | "job";
+  job?: string;
+  /** Works without a key for one hour. */
+  download_url: string;
+}
+
+export interface Job {
+  object: "job";
+  id: string;
+  operation: string;
+  status: "queued" | "running" | "succeeded" | "failed";
+  created_at: string;
+  started_at: string | null;
+  finished_at: string | null;
+  input: { files: string[]; options: Record<string, unknown> };
+  output: { files: MarqFile[]; text?: string; text_truncated?: boolean; note?: string; data?: Record<string, unknown>; model?: string; steps?: Record<string, unknown>[] } | null;
+  error: { code: string; message: string } | null;
+  webhook_url: string | null;
+}
+
+export interface Workflow {
+  object: "workflow";
+  id: string;
+  name: string;
+  steps: { operation: string; options: Record<string, unknown> }[];
+  created_at: string;
+}
+
+export interface Usage {
+  object: "usage";
+  month: string;
+  operations: number;
+  /** null = unlimited. */
+  limit: number | null;
+  plan: "free" | "week" | "pro" | "team";
+}
+
+export interface RunOptions {
+  /** Seconds the request waits before the SDK polls instead (default 60, max 300). */
+  wait?: number;
+  webhook_url?: string;
+  [option: string]: unknown;
+}
+
+export class MarqPDFError extends Error {
+  status?: number;
+  code?: string;
+  job?: Job;
+  body?: unknown;
+}
+
+export const VERSION: string;
+export const OPERATIONS: Record<string, string>;
+
+export class MarqPDF {
+  constructor(opts?: { apiKey?: string; baseUrl?: string; fetch?: typeof fetch; timeoutMs?: number });
+  files: {
+    upload(input: FileInput, opts?: { name?: string }): Promise<MarqFile>;
+    list(opts?: { limit?: number }): Promise<MarqFile[]>;
+    get(id: string): Promise<MarqFile>;
+    delete(id: string): Promise<{ id: string; deleted: true }>;
+    content(id: string): Promise<ArrayBuffer>;
+  };
+  jobs: {
+    get(id: string): Promise<Job>;
+    list(opts?: { limit?: number }): Promise<Job[]>;
+    wait(job: string | Job, opts?: { intervalMs?: number; timeoutMs?: number }): Promise<Job>;
+  };
+  usage(): Promise<Usage>;
+  run(operation: string, input: FileInput | FileInput[], options?: RunOptions): Promise<Job>;
+  download(jobOrFile: Job | MarqFile | string, path?: string): Promise<string>;
+
+  compress(input: FileInput, options?: RunOptions & { target_mb?: number; level?: "screen" | "ebook" | "printer" | "prepress" }): Promise<Job>;
+  merge(inputs: FileInput[], options?: RunOptions): Promise<Job>;
+  split(input: FileInput, options?: RunOptions & { every?: number; ranges?: [number, number][] }): Promise<Job>;
+  rotate(input: FileInput, options: RunOptions & { angle: 90 | 180 | 270; pages?: number[] }): Promise<Job>;
+  organize(input: FileInput, options: RunOptions & { pages: number[] }): Promise<Job>;
+  removePages(input: FileInput, options: RunOptions & { pages: number[] }): Promise<Job>;
+  pageNumbers(input: FileInput, options?: RunOptions & { position?: string }): Promise<Job>;
+  watermark(input: FileInput, options: RunOptions & { text: string }): Promise<Job>;
+  protect(input: FileInput, options: RunOptions & { password: string }): Promise<Job>;
+  unlock(input: FileInput, options?: RunOptions & { password?: string }): Promise<Job>;
+  ocr(input: FileInput, options?: RunOptions): Promise<Job>;
+  convert(input: FileInput, options: RunOptions & { to: "pdf" | "docx" | "xlsx" | "pptx" | "jpg" }): Promise<Job>;
+  imagesToPdf(inputs: FileInput[], options?: RunOptions): Promise<Job>;
+  compare(inputs: [FileInput, FileInput], options?: RunOptions): Promise<Job>;
+  extractText(input: FileInput, options?: RunOptions & { ocr?: "auto" | "always" | "never" }): Promise<Job>;
+  /** AI: the fields you name (or a JSON Schema) as JSON, in job.output.data. */
+  extract(input: FileInput, options: RunOptions & { fields?: (string | { name: string; type?: "string" | "number" | "integer" | "boolean" | "date" | "list"; description?: string })[]; schema?: object; instructions?: string; model?: string }): Promise<Job>;
+  /** AI: an answer from the document, in job.output.text. */
+  ask(input: FileInput, options: RunOptions & { question: string; instructions?: string; model?: string }): Promise<Job>;
+  /** AI: give a goal; the agent picks and runs operations. Summary in job.output.text, trace in job.output.steps. */
+  agent(inputs: FileInput | FileInput[], options: RunOptions & { goal: string; max_steps?: number; model?: string }): Promise<Job>;
+  workflows: {
+    create(name: string, steps: { operation: string; options?: Record<string, unknown> }[]): Promise<Workflow>;
+    list(): Promise<Workflow[]>;
+    get(id: string): Promise<Workflow>;
+    delete(id: string): Promise<{ id: string; deleted: true }>;
+    run(id: string, input: FileInput | FileInput[], options?: RunOptions): Promise<Job>;
+    runSteps(steps: { operation: string; options?: Record<string, unknown> }[], input: FileInput | FileInput[], options?: RunOptions): Promise<Job>;
+  };
+  /** Models this account can name in `model`. */
+  models(): Promise<{ object: "list"; data: object[]; pipelines: Record<string, string> }>;
+}
+
+export function verifyWebhook(rawBody: string | Uint8Array, signatureHeader: string, secret: string, opts?: { toleranceSec?: number }): Promise<boolean>;
+
+export default MarqPDF;

package/marqpdf.js

@@ -0,0 +1,233 @@
+// @nucleushq/marqpdf: the MarqPDF API (https://marqpdf.com/developers) from JavaScript.
+// No dependencies. Node 18+, Deno and Bun; browsers too, though an API key
+// belongs on a server, never in a page.
+
+const DEFAULT_BASE = "https://marqpdf.com";
+export const VERSION = "0.3.0";
+
+/** Every operation: method name → API path. */
+export const OPERATIONS = {
+  compress: "compress",
+  merge: "merge",
+  split: "split",
+  rotate: "rotate",
+  organize: "organize",
+  removePages: "remove-pages",
+  pageNumbers: "page-numbers",
+  watermark: "watermark",
+  protect: "protect",
+  unlock: "unlock",
+  ocr: "ocr",
+  convert: "convert",
+  imagesToPdf: "images-to-pdf",
+  compare: "compare",
+  extractText: "extract-text",
+  extract: "extract",
+  ask: "ask",
+  agent: "agent",
+};
+const MULTI = new Set(["merge", "images-to-pdf", "compare", "agent"]);
+
+export class MarqPDFError extends Error {
+  constructor(message, { status, code, job, body } = {}) {
+    super(message);
+    this.name = "MarqPDFError";
+    this.status = status;
+    this.code = code;
+    this.job = job;
+    this.body = body;
+  }
+}
+
+const isNode = typeof process !== "undefined" && !!process.versions?.node;
+const env = (k) => (isNode ? process.env[k] : undefined);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export class MarqPDF {
+  /**
+   * @param {{apiKey?: string, baseUrl?: string, fetch?: typeof fetch, timeoutMs?: number}} [opts]
+   */
+  constructor({ apiKey = env("MARQPDF_API_KEY"), baseUrl = env("MARQPDF_BASE_URL") || DEFAULT_BASE, fetch: f, timeoutMs = 600_000 } = {}) {
+    if (!apiKey) throw new MarqPDFError("No API key: pass { apiKey } or set MARQPDF_API_KEY. Create one at https://marqpdf.com/?dev=keys");
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this._fetch = f || globalThis.fetch.bind(globalThis);
+    this.timeoutMs = timeoutMs;
+
+    this.files = {
+      /** Upload a local path (Node), a URL, bytes, a Blob/File, or pass a file id through. */
+      upload: (input, opts) => this._upload(input, opts),
+      list: ({ limit } = {}) => this._req("GET", "/v1/files", { query: { limit } }).then((r) => r.data),
+      get: (id) => this._req("GET", `/v1/files/${encodeURIComponent(id)}`),
+      delete: (id) => this._req("DELETE", `/v1/files/${encodeURIComponent(id)}`),
+      /** The file's bytes, as an ArrayBuffer. */
+      content: (id) => this._req("GET", `/v1/files/${encodeURIComponent(id)}/content`, { raw: true }).then((r) => r.arrayBuffer()),
+    };
+    this.jobs = {
+      get: (id) => this._req("GET", `/v1/jobs/${encodeURIComponent(id)}`),
+      list: ({ limit } = {}) => this._req("GET", "/v1/jobs", { query: { limit } }).then((r) => r.data),
+      /** Poll until a job finishes; resolves with it, or throws MarqPDFError if it failed. */
+      wait: (job, opts) => this._wait(job, opts),
+    };
+    this.workflows = {
+      /** Save a chain of steps: [{ operation: "ocr" }, { operation: "compress", options: { target_mb: 1 } }]. */
+      create: (name, steps) => this._req("POST", "/v1/workflows", { json: { name, steps } }),
+      list: () => this._req("GET", "/v1/workflows").then((r) => r.data),
+      get: (id) => this._req("GET", `/v1/workflows/${encodeURIComponent(id)}`),
+      delete: (id) => this._req("DELETE", `/v1/workflows/${encodeURIComponent(id)}`),
+      /** Run a saved workflow on a file (or files); resolves with the finished job. */
+      run: (id, input, options) => this._runAt(`/v1/workflows/${encodeURIComponent(id)}/run`, input, options, false),
+      /** Run steps without saving them. */
+      runSteps: (steps, input, options = {}) => this._runAt("/v1/workflows/run", input, { ...options, steps }, false),
+    };
+    for (const [method, op] of Object.entries(OPERATIONS)) {
+      this[method] = (input, options) => this.run(op, input, options);
+    }
+  }
+
+  /** Models this account can name in `model`, and each pipeline's choice. */
+  models() {
+    return this._req("GET", "/v1/models");
+  }
+
+  /** This month's operations and the plan's limit (null = unlimited). */
+  usage() {
+    return this._req("GET", "/v1/usage");
+  }
+
+  /**
+   * Run an operation and wait for it. `input` is one file (id, path, URL,
+   * bytes, Blob) or, for merge / images-to-pdf / compare, a list of them.
+   * Resolves with the finished job; its `output.files` hold the results.
+   */
+  async run(op, input, options = {}) {
+    return this._runAt(`/v1/${op}`, input, options, MULTI.has(op));
+  }
+
+  async _runAt(path, input, options = {}, multi = false) {
+    const { wait = 60, ...opts } = options;
+    const list = Array.isArray(input) ? input : [input];
+    const ids = [];
+    for (const i of list) ids.push(await this._fileId(i));
+    const body = multi || ids.length > 1 ? { files: ids, ...opts } : { file: ids[0], ...opts };
+    const res = await this._req("POST", path, { json: { ...body, wait }, allowJob: true });
+    return res.status === "succeeded" ? res : this._wait(res);
+  }
+
+  /**
+   * Node: save a job's first output (or a file object / id) to `path`.
+   * With no path, saves under the output's own name in the current directory.
+   * Resolves with the path written.
+   */
+  async download(jobOrFile, path) {
+    if (!isNode) throw new MarqPDFError("download() writes to disk, so it needs Node; use files.content(id) in a browser.");
+    const f = typeof jobOrFile === "string" ? { id: jobOrFile } : jobOrFile?.object === "job" ? jobOrFile.output?.files?.[0] : jobOrFile;
+    if (!f?.id) throw new MarqPDFError("Nothing to download: pass a finished job, a file, or a file id.");
+    const meta = f.name ? f : await this.files.get(f.id);
+    const { writeFile } = await import("node:fs/promises");
+    const out = path || meta.name;
+    await writeFile(out, Buffer.from(await this.files.content(f.id)));
+    return out;
+  }
+
+  // ── internals ──
+
+  async _fileId(input) {
+    if (typeof input === "string" && input.startsWith("file_")) return input;
+    if (input && typeof input === "object" && typeof input.id === "string" && input.id.startsWith("file_")) return input.id;
+    return (await this._upload(input)).id;
+  }
+
+  async _upload(input, { name } = {}) {
+    if (typeof input === "string" && /^https?:\/\//i.test(input)) {
+      return this._req("POST", "/v1/files", { json: { url: input, ...(name ? { name } : {}) } });
+    }
+    let bytes, fname = name;
+    if (typeof input === "string") {
+      if (input.startsWith("file_")) return this.files.get(input);
+      if (!isNode) throw new MarqPDFError("A path can only be read in Node; pass a Blob or bytes instead.");
+      const [{ readFile }, { basename }] = await Promise.all([import("node:fs/promises"), import("node:path")]);
+      bytes = await readFile(input);
+      fname = fname || basename(input);
+    } else if (typeof Blob !== "undefined" && input instanceof Blob) {
+      bytes = input;
+      fname = fname || input.name || "document.pdf";
+    } else if (input instanceof ArrayBuffer || ArrayBuffer.isView(input)) {
+      bytes = input;
+      fname = fname || "document.pdf";
+    } else {
+      throw new MarqPDFError("Can't upload that: pass a file id, a path, a URL, bytes or a Blob.");
+    }
+    return this._req("POST", "/v1/files", { body: bytes, query: { name: fname }, headers: { "Content-Type": "application/octet-stream" } });
+  }
+
+  async _wait(job, { intervalMs = 1500, timeoutMs = 30 * 60_000 } = {}) {
+    const id = typeof job === "string" ? job : job.id;
+    const until = Date.now() + timeoutMs;
+    let j = typeof job === "string" ? await this.jobs.get(id) : job;
+    while (j.status === "queued" || j.status === "running") {
+      if (Date.now() > until) throw new MarqPDFError(`Job ${id} is still ${j.status}; check it later with jobs.get().`, { job: j });
+      await sleep(intervalMs);
+      j = await this.jobs.get(id);
+    }
+    if (j.status === "failed") throw new MarqPDFError(j.error?.message || "The operation failed.", { code: j.error?.code, job: j });
+    return j;
+  }
+
+  async _req(method, path, { json, body, query, headers = {}, raw = false, allowJob = false } = {}) {
+    const url = new URL(this.baseUrl + path);
+    for (const [k, v] of Object.entries(query || {})) if (v !== undefined && v !== null) url.searchParams.set(k, String(v));
+    const h = { Authorization: `Bearer ${this.apiKey}`, "User-Agent": `marqpdf-js/${VERSION}`, ...headers };
+    let payload = body;
+    if (json !== undefined) {
+      h["Content-Type"] = "application/json";
+      payload = JSON.stringify(json);
+    }
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), this.timeoutMs);
+    let res;
+    try {
+      res = await this._fetch(url, { method, headers: h, body: payload, signal: ctrl.signal });
+    } catch (e) {
+      throw new MarqPDFError(`Couldn't reach MarqPDF: ${e.message}`);
+    } finally {
+      clearTimeout(t);
+    }
+    if (raw && res.ok) return res;
+    const text = await res.text();
+    let data;
+    try {
+      data = text ? JSON.parse(text) : {};
+    } catch {
+      data = { error: { message: text } };
+    }
+    if (res.ok || (allowJob && res.status === 202)) return data;
+    const e = data.error || {};
+    throw new MarqPDFError(e.message || `MarqPDF answered ${res.status}`, { status: res.status, code: e.code, job: data.job, body: data });
+  }
+}
+
+/**
+ * Check a webhook's MarqPDF-Signature header. `rawBody` must be the exact
+ * bytes received (a string or Uint8Array), before any JSON parsing.
+ * Resolves true when the signature matches and is fresh.
+ */
+export async function verifyWebhook(rawBody, signatureHeader, secret, { toleranceSec = 300 } = {}) {
+  if (!signatureHeader || !secret) return false;
+  const parts = Object.fromEntries(String(signatureHeader).split(",").map((p) => p.trim().split("=", 2)));
+  const t = Number(parts.t);
+  if (!parts.v1 || !Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
+  const enc = new TextEncoder();
+  const body = typeof rawBody === "string" ? enc.encode(rawBody) : new Uint8Array(rawBody);
+  const msg = new Uint8Array([...enc.encode(`${t}.`), ...body]);
+  const subtle = globalThis.crypto?.subtle || (await import("node:crypto")).webcrypto.subtle;
+  const key = await subtle.importKey("raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const mac = new Uint8Array(await subtle.sign("HMAC", key, msg));
+  const want = [...mac].map((b) => b.toString(16).padStart(2, "0")).join("");
+  if (want.length !== parts.v1.length) return false;
+  let diff = 0;
+  for (let i = 0; i < want.length; i++) diff |= want.charCodeAt(i) ^ parts.v1.charCodeAt(i);
+  return diff === 0;
+}
+
+export default MarqPDF;

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@nucleushq/marqpdf",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "MarqPDF API client: compress, OCR, convert, merge, split and protect PDFs from code.",
+  "type": "module",
+  "main": "marqpdf.js",
+  "types": "marqpdf.d.ts",
+  "exports": {
+    ".": {
+      "types": "./marqpdf.d.ts",
+      "default": "./marqpdf.js"
+    }
+  },
+  "files": [
+    "marqpdf.js",
+    "marqpdf.d.ts",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED",
+  "homepage": "https://marqpdf.com/developers",
+  "keywords": [
+    "pdf",
+    "compress-pdf",
+    "ocr",
+    "pdf-to-word",
+    "merge-pdf",
+    "api",
+    "sdk",
+    "mcp"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}