papermark 0.9.0 → 0.10.1

package/dist/index.js

@@ -94,6 +94,86 @@ function getRuntime() {
   return current;
 }
 
+// package.json
+var package_default = {
+  name: "papermark",
+  version: "0.10.1",
+  description: "Command-line interface for Papermark \u2014 share documents, create data rooms, generate access links, and read analytics.",
+  license: "MIT",
+  homepage: "https://www.papermark.com",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/papermark/papermark-cli.git"
+  },
+  bugs: {
+    url: "https://github.com/papermark/papermark-cli/issues"
+  },
+  keywords: [
+    "papermark",
+    "dataroom",
+    "datarooms",
+    "data room",
+    "virtual data room",
+    "document sharing",
+    "secure file sharing",
+    "access links",
+    "analytics",
+    "cli"
+  ],
+  type: "module",
+  bin: {
+    papermark: "dist/index.js"
+  },
+  files: [
+    "dist",
+    "docs",
+    "skills",
+    "openai.yaml",
+    "README.md",
+    "LICENSE"
+  ],
+  engines: {
+    node: ">=24"
+  },
+  scripts: {
+    build: "tsup",
+    dev: "tsx src/index.ts",
+    typecheck: "tsc --noEmit",
+    test: "vitest run",
+    "test:watch": "vitest",
+    changeset: "changeset",
+    version: "changeset version",
+    release: "npm run build && changeset publish",
+    prepublishOnly: "npm run build"
+  },
+  dependencies: {
+    chalk: "^5.3.0",
+    commander: "^14.0.3",
+    conf: "^13.0.1",
+    "mime-types": "^3.0.2",
+    oauth4webapi: "^3.8.5",
+    open: "^11.0.0",
+    ora: "^9.4.0",
+    prompts: "^2.4.2"
+  },
+  devDependencies: {
+    "@changesets/changelog-github": "^0.6.0",
+    "@changesets/cli": "^2.31.0",
+    "@types/mime-types": "^3.0.1",
+    "@types/node": "^22.13.5",
+    "@types/prompts": "^2.4.9",
+    tsup: "^8.3.5",
+    tsx: "^4.21.0",
+    typescript: "^5.7.2",
+    vitest: "^4.1.5"
+  }
+};
+
+// src/version.ts
+var VERSION = package_default.version;
+var CLIENT_ID = "cli";
+var USER_AGENT = `papermark-cli/${VERSION} (node ${process.version}; ${process.platform} ${process.arch})`;
+
 // src/client.ts
 var ApiError = class extends Error {
   code;
@@ -161,7 +241,15 @@ function buildUrl(path, query) {
 async function request(path, opts = {}) {
   const headers = {
     Accept: "application/json",
-    ...opts.headers ?? {}
+    ...opts.headers ?? {},
+    // Identify the caller so the API can attribute usage to the CLI (vs the
+    // MCP server or raw HTTP) and the client version. Dedicated headers keep
+    // server-side parsing unambiguous; the User-Agent mirrors them for
+    // proxy/access logs. Set last so attribution can't be spoofed or dropped
+    // by caller-supplied headers.
+    "User-Agent": USER_AGENT,
+    "x-papermark-client": CLIENT_ID,
+    "x-papermark-client-version": VERSION
   };
   if (!opts.anonymous) {
     const token = getToken();
@@ -205,7 +293,8 @@ async function request(path, opts = {}) {
     debug("http", "network error after", `${Date.now() - started}ms`, String(err));
     throw new NetworkError(url, err);
   }
-  debug("http", method, url, `\u2192 ${res.status}`, `(${Date.now() - started}ms)`);
+  const requestId = res.headers.get("x-request-id") ?? "";
+  debug("http", method, url, `\u2192 ${res.status}`, requestId, `(${Date.now() - started}ms)`);
   if (res.status === 204) return void 0;
   const text = await res.text();
   const parsed = text ? safeParseJson(text) : null;
@@ -656,7 +745,7 @@ import ora from "ora";
 // src/oauth.ts
 import * as oauth from "oauth4webapi";
 import open from "open";
-var CLIENT_ID = "papermark-cli";
+var CLIENT_ID2 = "papermark-cli";
 var DEFAULT_SCOPES = [
   "openid",
   "offline_access",
@@ -697,7 +786,7 @@ async function requestDeviceAuthorization(as, scopes) {
     );
   }
   const body = new URLSearchParams({
-    client_id: CLIENT_ID,
+    client_id: CLIENT_ID2,
     scope: scopes.join(" ")
   });
   const json2 = await postFormJson(
@@ -765,7 +854,7 @@ async function pollForToken(as, deviceCode, {
     const body = new URLSearchParams({
       grant_type: "urn:ietf:params:oauth:grant-type:device_code",
       device_code: deviceCode,
-      client_id: CLIENT_ID
+      client_id: CLIENT_ID2
     });
     let parsed;
     try {
@@ -790,6 +879,28 @@ async function tryOpenBrowser(url) {
   } catch {
   }
 }
+async function revokeToken(token) {
+  try {
+    const issuer = deriveIssuer();
+    const as = await discover(issuer);
+    if (!as.revocation_endpoint) return "unsupported";
+    const res = await fetch(as.revocation_endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json"
+      },
+      body: new URLSearchParams({
+        token,
+        token_type_hint: "access_token",
+        client_id: CLIENT_ID2
+      })
+    });
+    return res.ok ? "revoked" : "failed";
+  } catch {
+    return "failed";
+  }
+}
 
 // src/commands/auth.ts
 function registerAuthCommands(program2) {
@@ -814,9 +925,24 @@ function registerAuthCommands(program2) {
       }
     }
   );
-  program2.command("logout").description("Remove the stored API token").action(() => {
+  program2.command("logout").description("Remove the stored API token").action(async () => {
+    const token = getToken();
+    const source = getTokenSource();
+    const revocation = token && source === "config" ? await revokeToken(token) : "skipped";
     clearToken();
-    emit({ removed: true }, () => chalk3.green("\u2713") + " Token removed.");
+    if (revocation === "skipped" && (source === "env" || source === "credentials-file")) {
+      process.stderr.write(
+        chalk3.dim(`Note: token comes from ${source}; not revoked server-side.`) + "\n"
+      );
+    } else if (revocation === "failed") {
+      process.stderr.write(
+        chalk3.yellow("! ") + "Could not revoke the token server-side; it remains valid until expiry.\n"
+      );
+    }
+    emit(
+      { removed: true, revocation },
+      () => revocation === "revoked" ? chalk3.green("\u2713") + " Token revoked and removed." : chalk3.green("\u2713") + " Token removed."
+    );
   });
   program2.command("whoami").description("Show the active token and API URL").action(() => {
     const token = getToken();
@@ -1203,6 +1329,18 @@ function parsePermissionEntries(opts) {
   );
 }
 
+// src/validate.ts
+function parseLimit(value) {
+  if (value === void 0) return void 0;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1 || n > 100) {
+    throw new ValidationError(
+      `Invalid --limit ${JSON.stringify(value)}. Expected an integer 1-100.`
+    );
+  }
+  return n;
+}
+
 // src/commands/datarooms.ts
 function registerDataroomsCommands(program2) {
   const dr = program2.command("datarooms").alias("dr").description("Manage datarooms");
@@ -1211,7 +1349,7 @@ function registerDataroomsCommands(program2) {
       if (opts.json) setRuntime({ json: true });
       try {
         const res = await api.listDatarooms({
-          limit: opts.limit ? Number(opts.limit) : void 0,
+          limit: parseLimit(opts.limit),
           cursor: opts.cursor,
           query: opts.query
         });
@@ -1280,14 +1418,14 @@ More results: --cursor ${res.next_cursor}`) : out;
           const norm = v.toLowerCase();
           if (norm === "on") return true;
           if (norm === "off") return false;
-          throw new Error(
+          throw new ValidationError(
             `Invalid value for ${flag}: ${JSON.stringify(v)} (expected "on" or "off").`
           );
         };
         const bulk = tri(opts.bulkDownload, "--bulk-download");
         if (bulk !== void 0) body.allow_bulk_download = bulk;
         if (Object.keys(body).length === 0) {
-          throw new Error(
+          throw new ValidationError(
             "Pass at least one field to update (e.g. --name, --description, --bulk-download off)."
           );
         }
@@ -1310,7 +1448,7 @@ More results: --cursor ${res.next_cursor}`) : out;
       try {
         const res = await api.listLinks({
           dataroom_id: id,
-          limit: opts.limit ? Number(opts.limit) : void 0,
+          limit: parseLimit(opts.limit),
           cursor: opts.cursor
         });
         emit(res, () => {
@@ -1339,7 +1477,7 @@ More results: --cursor ${res.next_cursor}`) : out;
       try {
         const res = await api.listVisitors({
           dataroom_id: id,
-          limit: opts.limit ? Number(opts.limit) : void 0,
+          limit: parseLimit(opts.limit),
           cursor: opts.cursor,
           email: opts.email
         });
@@ -1454,12 +1592,12 @@ More results: --cursor ${res.next_cursor}`) : out;
       try {
         const folderIsRoot = opts.folderId === "" || opts.folderId === "root";
         if (opts.root && opts.folderId !== void 0 && !folderIsRoot) {
-          throw new Error(
+          throw new ValidationError(
             "Pass either --root or --folder-id <fid>, not both."
           );
         }
         if (!opts.root && opts.folderId === void 0) {
-          throw new Error(
+          throw new ValidationError(
             'Pass --folder-id <fid>, or --root (or --folder-id "") to move to the dataroom root.'
           );
         }
@@ -1727,7 +1865,7 @@ More results: --cursor ${res.next_cursor}`) : out;
       if (opts.json) setRuntime({ json: true });
       try {
         const res = await api.listDataroomFolders(id, {
-          limit: opts.limit ? Number(opts.limit) : void 0,
+          limit: parseLimit(opts.limit),
           cursor: opts.cursor,
           parent_id: opts.parent
         });
@@ -1786,7 +1924,7 @@ More results: --cursor ${res.next_cursor}`) : out;
         if (opts.color !== void 0)
           body.color = opts.color === "" ? null : opts.color;
         if (Object.keys(body).length === 0) {
-          throw new Error(
+          throw new ValidationError(
             "Pass at least one of --name, --icon, --color to update."
           );
         }
@@ -1827,7 +1965,7 @@ More results: --cursor ${res.next_cursor}`) : out;
     async (id, fid, opts) => {
       try {
         if (opts.parent === void 0) {
-          throw new Error(
+          throw new ValidationError(
             "Pass --parent <fid> (use empty string to move to the root)."
           );
         }
@@ -1850,7 +1988,7 @@ More results: --cursor ${res.next_cursor}`) : out;
       if (opts.json) setRuntime({ json: true });
       try {
         const res = await api.listDataroomDocuments(id, {
-          limit: opts.limit ? Number(opts.limit) : void 0,
+          limit: parseLimit(opts.limit),
           cursor: opts.cursor,
           folder_id: opts.folder
         });
@@ -1986,7 +2124,7 @@ function registerDocumentsCommands(program2) {
     if (opts.json) setRuntime({ json: true });
     try {
       const res = await api.listDocuments({
-        limit: opts.limit ? Number(opts.limit) : void 0,
+        limit: parseLimit(opts.limit),
         cursor: opts.cursor
       });
       emit(res, () => {
@@ -2019,7 +2157,7 @@ More results: --cursor ${res.next_cursor}`) : out;
     try {
       const res = await api.searchDocuments(
         query,
-        opts.limit ? Number(opts.limit) : void 0
+        parseLimit(opts.limit)
       );
       emit(res, () => {
         const rows = res.data.map((d) => ({
@@ -2043,7 +2181,7 @@ More results: --cursor ${res.next_cursor}`) : out;
           body.folder_id = opts.folderId === "" ? null : opts.folderId;
         }
         if (Object.keys(body).length === 0) {
-          throw new Error(
+          throw new ValidationError(
             "Pass at least one of --name or --folder-id to update."
           );
         }
@@ -2073,8 +2211,13 @@ More results: --cursor ${res.next_cursor}`) : out;
     async (filePath, opts) => {
       const spinner = ora2();
       try {
-        const stats = await stat(filePath);
-        if (!stats.isFile()) throw new Error(`${filePath} is not a file.`);
+        const stats = await stat(filePath).catch((statErr) => {
+          throw new ValidationError(
+            `Cannot read ${filePath}: ${statErr.message}`,
+            { code: statErr.code }
+          );
+        });
+        if (!stats.isFile()) throw new ValidationError(`${filePath} is not a file.`);
         const fileName = opts.name ?? basename(filePath);
         const contentType = lookupMimeType(filePath) || "application/octet-stream";
         spinner.start("Requesting upload URL");
@@ -2083,6 +2226,15 @@ More results: --cursor ${res.next_cursor}`) : out;
           content_type: contentType,
           content_length: stats.size
         });
+        if (getRuntime().dryRun) {
+          spinner.stop();
+          process.stderr.write(
+            `[dry-run] PUT <presigned upload_url from the response above> (file: ${filePath}, ${humanSize(stats.size)})
+[dry-run] POST ${"/v1/documents"} (name, upload_id, folder_id, create_link)
+`
+          );
+          return;
+        }
         spinner.succeed("Got presigned URL");
         spinner.start(`Uploading ${humanSize(stats.size)}`);
         const fileStream = Readable.toWeb(createReadStream(filePath));
@@ -2193,8 +2345,13 @@ More results: --cursor ${res.next_cursor}`) : out;
   versions.command("add <id> <file>").description("Upload a new version of an existing document").action(async (id, filePath) => {
     const spinner = ora2();
     try {
-      const stats = await stat(filePath);
-      if (!stats.isFile()) throw new Error(`${filePath} is not a file.`);
+      const stats = await stat(filePath).catch((statErr) => {
+        throw new ValidationError(
+          `Cannot read ${filePath}: ${statErr.message}`,
+          { code: statErr.code }
+        );
+      });
+      if (!stats.isFile()) throw new ValidationError(`${filePath} is not a file.`);
       const fileName = basename(filePath);
       const contentType = lookupMimeType(filePath) || "application/octet-stream";
       spinner.start("Requesting upload URL");
@@ -2203,6 +2360,15 @@ More results: --cursor ${res.next_cursor}`) : out;
         content_type: contentType,
         content_length: stats.size
       });
+      if (getRuntime().dryRun) {
+        spinner.stop();
+        process.stderr.write(
+          `[dry-run] PUT <presigned upload_url from the response above> (file: ${filePath}, ${humanSize(stats.size)})
+[dry-run] POST /v1/documents/${id}/versions (upload_id)
+`
+        );
+        return;
+      }
       spinner.succeed("Got presigned URL");
       spinner.start(`Uploading ${humanSize(stats.size)}`);
       const fileStream = Readable.toWeb(createReadStream(filePath));
@@ -2271,6 +2437,7 @@ More results: --cursor ${res.next_cursor}`) : out;
   });
 }
 async function finalizeDocumentCreation(doc, wantLink) {
+  if (getRuntime().dryRun) return;
   let link = null;
   let linkWarning = null;
   if (wantLink) {
@@ -2322,7 +2489,7 @@ function registerFoldersCommands(program2) {
       if (opts.json) setRuntime({ json: true });
       try {
         const res = await api.listFolders({
-          limit: opts.limit ? Number(opts.limit) : void 0,
+          limit: parseLimit(opts.limit),
           cursor: opts.cursor,
           parent_id: opts.parent
         });
@@ -2381,7 +2548,7 @@ More results: --cursor ${res.next_cursor}`) : out;
         if (opts.color !== void 0)
           body.color = opts.color === "" ? null : opts.color;
         if (Object.keys(body).length === 0) {
-          throw new Error(
+          throw new ValidationError(
             "Pass at least one of --name, --icon, --color to update."
           );
         }
@@ -2417,7 +2584,7 @@ More results: --cursor ${res.next_cursor}`) : out;
   ).action(async (id, opts) => {
     try {
       if (opts.parent === void 0) {
-        throw new Error(
+        throw new ValidationError(
           "Pass --parent <id> (use empty string to move to the root)."
         );
       }
@@ -2475,42 +2642,42 @@ function parseWatermarkConfig(opts) {
   if (provided.length === 0) return void 0;
   const missing = Object.entries(fields).filter(([, v]) => v === void 0).map(([k]) => flagNames[k]);
   if (missing.length > 0) {
-    throw new Error(
+    throw new ValidationError(
       `Watermark config is partial. Missing: ${missing.join(", ")}.`
     );
   }
   const tiled = fields.is_tiled.toLowerCase() === "true" || fields.is_tiled.toLowerCase() === "on";
   const tiledOff = fields.is_tiled.toLowerCase() === "false" || fields.is_tiled.toLowerCase() === "off";
   if (!tiled && !tiledOff) {
-    throw new Error(
+    throw new ValidationError(
       `Invalid --watermark-tiled value ${JSON.stringify(fields.is_tiled)} (expected on/off).`
     );
   }
   if (!WATERMARK_POSITIONS.includes(fields.position)) {
-    throw new Error(
+    throw new ValidationError(
       `Invalid --watermark-position ${JSON.stringify(fields.position)}. Expected one of: ${WATERMARK_POSITIONS.join(", ")}.`
     );
   }
   const rotation = Number(fields.rotation);
   if (!Number.isFinite(rotation) || !WATERMARK_ROTATIONS.includes(rotation)) {
-    throw new Error(
+    throw new ValidationError(
       `Invalid --watermark-rotation ${JSON.stringify(fields.rotation)}. Expected one of: ${WATERMARK_ROTATIONS.join(", ")}.`
     );
   }
   if (!/^#([0-9A-Fa-f]{3}){1,2}$/.test(fields.color)) {
-    throw new Error(
+    throw new ValidationError(
       `Invalid --watermark-color ${JSON.stringify(fields.color)}. Expected #RGB or #RRGGBB.`
     );
   }
   const fontSize = Number(fields.font_size);
   if (!Number.isInteger(fontSize) || fontSize < 1 || fontSize > 96) {
-    throw new Error(
+    throw new ValidationError(
       `Invalid --watermark-font-size ${JSON.stringify(fields.font_size)}. Expected integer 1-96.`
     );
   }
   const opacity = Number(fields.opacity);
   if (!Number.isFinite(opacity) || opacity < 0 || opacity > 1) {
-    throw new Error(
+    throw new ValidationError(
       `Invalid --watermark-opacity ${JSON.stringify(fields.opacity)}. Expected 0-1.`
     );
   }
@@ -2543,7 +2710,7 @@ function registerLinksCommands(program2) {
       if (opts.json) setRuntime({ json: true });
       try {
         const res = await api.listLinks({
-          limit: opts.limit ? Number(opts.limit) : void 0,
+          limit: parseLimit(opts.limit),
           cursor: opts.cursor,
           document_id: opts.document,
           dataroom_id: opts.dataroom,
@@ -2608,7 +2775,7 @@ More results: --cursor ${res.next_cursor}`) : out;
     async (opts) => {
       try {
         if (!opts.document && !opts.dataroom) {
-          throw new Error("Either --document <id> or --dataroom <id> is required.");
+          throw new ValidationError("Either --document <id> or --dataroom <id> is required.");
         }
         if (opts.group && !opts.dataroom) {
           throw new Error("--group requires --dataroom <id>.");
@@ -2677,7 +2844,7 @@ More results: --cursor ${res.next_cursor}`) : out;
           const norm = v.toLowerCase();
           if (norm === "on") return true;
           if (norm === "off") return false;
-          throw new Error(
+          throw new ValidationError(
             `Invalid value for ${flag}: ${JSON.stringify(v)} (expected "on" or "off").`
           );
         };
@@ -2712,7 +2879,7 @@ More results: --cursor ${res.next_cursor}`) : out;
         if (wm !== void 0) body.enable_watermark = wm;
         const watermarkConfig = parseWatermarkConfig(opts);
         if (opts.watermarkClear && watermarkConfig !== void 0) {
-          throw new Error(
+          throw new ValidationError(
             "Pass either --watermark-clear or --watermark-* flags, not both."
           );
         }
@@ -2733,7 +2900,7 @@ More results: --cursor ${res.next_cursor}`) : out;
         if (opts.domain !== void 0) body.domain = opts.domain;
         if (opts.slug !== void 0) body.slug = opts.slug;
         if (Object.keys(body).length === 0) {
-          throw new Error(
+          throw new ValidationError(
             "Pass at least one field to update (e.g. --name, --expires, --password)."
           );
         }
@@ -2832,7 +2999,7 @@ function registerViewsCommands(program2) {
       if (opts.json) setRuntime({ json: true });
       try {
         const res = await api.listViews(opts.link, {
-          limit: opts.limit ? Number(opts.limit) : void 0,
+          limit: parseLimit(opts.limit),
           cursor: opts.cursor
         });
         emit(res, () => {
@@ -2864,7 +3031,7 @@ function registerVisitorsCommands(program2) {
       if (opts.json) setRuntime({ json: true });
       try {
         const res = await api.listVisitors({
-          limit: opts.limit ? Number(opts.limit) : void 0,
+          limit: parseLimit(opts.limit),
           cursor: opts.cursor,
           email: opts.email,
           dataroom_id: opts.dataroom
@@ -2900,7 +3067,7 @@ More results: --cursor ${res.next_cursor}`) : out;
       if (opts.json) setRuntime({ json: true });
       try {
         const res = await api.listVisitorViews(id, {
-          limit: opts.limit ? Number(opts.limit) : void 0,
+          limit: parseLimit(opts.limit),
           cursor: opts.cursor
         });
         emit(res, () => {
@@ -2925,7 +3092,7 @@ More results: --cursor ${res.next_cursor}`) : out;
 
 // src/index.ts
 var program = new Command2();
-program.name("papermark").description("Papermark CLI \u2014 manage documents, links, and views").version("0.1.0").option(
+program.name("papermark").description("Papermark CLI \u2014 manage documents, links, and views").version(VERSION).option(
   "--json",
   "emit machine-readable JSON on stdout (auto-enabled when piped)"
 ).option(