@vakra-dev/reader-cli 0.1.0 → 0.2.0

package/dist/index.js

@@ -49,6 +49,15 @@ function redactKey(key) {
 
 // src/utils/output.ts
 import { writeFileSync as writeFileSync2 } from "fs";
+import yoctoSpinner from "yocto-spinner";
+import {
+  ReaderApiError,
+  InsufficientCreditsError,
+  RateLimitedError,
+  UrlBlockedError,
+  UnauthenticatedError,
+  ScrapeTimeoutError
+} from "@vakra-dev/reader-js";
 function info(msg) {
   console.error(msg);
 }
@@ -67,24 +76,143 @@ function saveScreenshot(base64, outputPath) {
   writeFileSync2(path, buffer);
   return path;
 }
+var SCRAPE_MESSAGES = [
+  "Reading the page...",
+  "Fetching content...",
+  "Scraping the web...",
+  "Extracting data..."
+];
+var CRAWL_MESSAGES = [
+  "Discovering pages...",
+  "Following links...",
+  "Mapping the site...",
+  "Crawling deeper..."
+];
+function rotatingSpinner(messages, intervalMs = 3e3) {
+  let idx = Math.floor(Math.random() * messages.length);
+  const spinner = yoctoSpinner({ text: messages[idx] }).start();
+  const timer = setInterval(() => {
+    idx = (idx + 1) % messages.length;
+    spinner.text = messages[idx];
+  }, intervalMs);
+  const origSuccess = spinner.success.bind(spinner);
+  const origError = spinner.error.bind(spinner);
+  const origStop = spinner.stop.bind(spinner);
+  spinner.success = (text) => {
+    clearInterval(timer);
+    return origSuccess(text);
+  };
+  spinner.error = (text) => {
+    clearInterval(timer);
+    return origError(text);
+  };
+  spinner.stop = (text) => {
+    clearInterval(timer);
+    return origStop(text);
+  };
+  return spinner;
+}
+function scrapeSpinner() {
+  return rotatingSpinner(SCRAPE_MESSAGES);
+}
+function crawlSpinner(domain) {
+  return rotatingSpinner([
+    `Crawling ${domain}...`,
+    ...CRAWL_MESSAGES
+  ]);
+}
+function statusSpinner() {
+  return yoctoSpinner({ text: "Pinging the API..." }).start();
+}
+function creditsSpinner() {
+  return yoctoSpinner({ text: "Fetching balance..." }).start();
+}
+function formatError(err) {
+  if (err instanceof ReaderApiError) {
+    const lines = [];
+    lines.push(`${err.message} (${err.code}, HTTP ${err.httpStatus})`);
+    if (err instanceof InsufficientCreditsError) {
+      if (err.required !== void 0) lines.push(`  Required:  ${err.required} credits`);
+      if (err.available !== void 0) lines.push(`  Available: ${err.available} credits`);
+      if (err.resetAt) lines.push(`  Resets:    ${err.resetAt}`);
+    } else if (err instanceof RateLimitedError) {
+      if (err.retryAfterSeconds) lines.push(`  Retry after: ${err.retryAfterSeconds} seconds`);
+    } else if (err instanceof UrlBlockedError) {
+      if (err.url) lines.push(`  URL:    ${err.url}`);
+      if (err.reason) lines.push(`  Reason: ${err.reason}`);
+    } else if (err instanceof UnauthenticatedError) {
+      lines.push("  Check your API key: reader config show");
+    } else if (err instanceof ScrapeTimeoutError) {
+      if (err.timeoutMs) lines.push(`  Timeout: ${err.timeoutMs}ms`);
+    }
+    if (err.docsUrl) lines.push(`  Docs:    ${err.docsUrl}`);
+    if (err.requestId) lines.push(`  Request: ${err.requestId}`);
+    return lines.join("\n");
+  }
+  if (err instanceof Error) {
+    const msg = err.message;
+    if (msg.includes("ECONNREFUSED")) {
+      return `${msg}
+  Could not connect to the API. Check your API URL: reader config show`;
+    }
+    if (msg.includes("ENOTFOUND")) {
+      return `${msg}
+  DNS lookup failed. Check your API URL: reader config show`;
+    }
+    if (msg.includes("fetch failed") || msg.includes("network")) {
+      return `${msg}
+  Network error. Check your internet connection.`;
+    }
+    return msg;
+  }
+  return String(err);
+}
+
+// src/utils/validate.ts
+var VALID_FORMATS = ["markdown", "html", "screenshot"];
+function normalizeUrl(url) {
+  let normalized = url;
+  if (!url.includes("://")) {
+    normalized = `https://${url}`;
+    info(`Normalized URL: ${url} -> ${normalized}`);
+  }
+  try {
+    new URL(normalized);
+  } catch {
+    error(`Invalid URL: "${url}". Expected format: https://example.com`);
+    process.exit(1);
+  }
+  return normalized;
+}
+function parsePositiveInt(value, name) {
+  const n = parseInt(value, 10);
+  if (isNaN(n) || n <= 0) {
+    error(`Invalid value for ${name}: "${value}" is not a positive integer`);
+    process.exit(1);
+  }
+  return n;
+}
+function validateFormat(format) {
+  if (!VALID_FORMATS.includes(format)) {
+    error(`Invalid format: "${format}". Allowed: ${VALID_FORMATS.join(", ")}`);
+    process.exit(1);
+  }
+  return format;
+}
 
 // src/commands/scrape.ts
 function registerScrapeCommand(program2) {
-  program2.command("scrape <url>").description("Scrape a URL and output content").option("-f, --format <format>", "Output format: markdown (default), html, screenshot", "markdown").option("--json", "Output full JSON response").option("-o, --output <file>", "Write output to file").option("--no-main-content", "Include full page (nav, header, footer)").option("--include-tags <selectors>", "CSS selectors to include (comma-separated)").option("--exclude-tags <selectors>", "CSS selectors to exclude (comma-separated)").option("--wait-for <selector>", "Wait for CSS selector before scraping").option("--timeout <ms>", "Timeout in milliseconds", "30000").option("--proxy-mode <mode>", "Proxy mode: standard, stealth, auto").action(async (url, opts) => {
+  program2.command("scrape <url>").description("Scrape a URL and output content").option("-f, --format <format>", "Output format: markdown (default), html, screenshot", "markdown").option("--json", "Output full JSON response").option("-o, --output <file>", "Write output to file").option("--no-main-content", "Include full page (nav, header, footer)").option("--include-tags <selectors>", "CSS selectors to include (comma-separated)").option("--exclude-tags <selectors>", "CSS selectors to exclude (comma-separated)").option("--wait-for <selector>", "Wait for CSS selector before scraping").option("--timeout <ms>", "Timeout in milliseconds", "30000").option("--proxy-mode <mode>", "Proxy mode: standard, stealth, auto").action(async (rawUrl, opts) => {
+    const url = normalizeUrl(rawUrl);
     const apiKey = getApiKey();
     const client = new ReaderClient({ apiKey, baseUrl: getApiUrl() });
-    const formats = [];
-    const requestedFormat = opts.format;
-    if (requestedFormat === "screenshot") {
-      formats.push("screenshot");
-    } else if (requestedFormat === "html") {
-      formats.push("html");
-    } else {
-      formats.push("markdown");
-    }
+    const requestedFormat = validateFormat(opts.format);
+    const formats = [requestedFormat];
     if (requestedFormat !== "screenshot" && opts.output?.endsWith(".png")) {
       formats.push("screenshot");
     }
+    const timeout = parsePositiveInt(opts.timeout, "--timeout");
+    const spinner = scrapeSpinner();
     try {
       const result = await client.read({
         url,
@@ -93,11 +221,12 @@ function registerScrapeCommand(program2) {
         includeTags: opts.includeTags?.split(",").map((s) => s.trim()),
         excludeTags: opts.excludeTags?.split(",").map((s) => s.trim()),
         waitForSelector: opts.waitFor,
-        timeoutMs: parseInt(opts.timeout, 10),
+        timeoutMs: timeout,
         proxyMode: opts.proxyMode
       });
       if (result.kind === "scrape") {
         const data = result.data;
+        spinner.success("Done -- content ready");
         if (opts.json) {
           outputJson(data);
           return;
@@ -117,6 +246,7 @@ function registerScrapeCommand(program2) {
         }
       } else {
         const job = result.data;
+        spinner.success(`Done -- ${job.results.length} pages`);
         if (opts.json) {
           outputJson(job);
         } else {
@@ -126,8 +256,8 @@ function registerScrapeCommand(program2) {
         }
       }
     } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      error(msg);
+      spinner.error("Failed");
+      error(formatError(err));
       process.exit(1);
     }
   });
@@ -136,22 +266,33 @@ function registerScrapeCommand(program2) {
 // src/commands/crawl.ts
 import { ReaderClient as ReaderClient2 } from "@vakra-dev/reader-js";
 function registerCrawlCommand(program2) {
-  program2.command("crawl <url>").description("Crawl a website and output discovered pages").option("--max-depth <n>", "Maximum crawl depth", "2").option("--max-pages <n>", "Maximum pages to crawl", "20").option("--urls-only", "Only output discovered URLs, don't scrape content").option("--json", "Output full JSON response").option("-o, --output-dir <dir>", "Write each page to a separate file").action(async (url, opts) => {
+  program2.command("crawl <url>").description("Crawl a website and output discovered pages").option("--max-depth <n>", "Maximum crawl depth", "2").option("--max-pages <n>", "Maximum pages to crawl", "20").option("--urls-only", "Only output discovered URLs, don't scrape content").option("--json", "Output full JSON response").option("-o, --output-dir <dir>", "Write each page to a separate file").action(async (rawUrl, opts) => {
+    const url = normalizeUrl(rawUrl);
     const apiKey = getApiKey();
     const client = new ReaderClient2({ apiKey, baseUrl: getApiUrl() });
-    info(`Crawling ${url} (depth: ${opts.maxDepth}, max: ${opts.maxPages} pages)...`);
+    const maxDepth = parsePositiveInt(opts.maxDepth, "--max-depth");
+    const maxPages = parsePositiveInt(opts.maxPages, "--max-pages");
+    let domain;
+    try {
+      domain = new URL(url).hostname;
+    } catch {
+      domain = url;
+    }
+    const spinner = crawlSpinner(domain);
     try {
       const result = await client.read({
         url,
-        maxDepth: parseInt(opts.maxDepth, 10),
-        maxPages: parseInt(opts.maxPages, 10),
+        maxDepth,
+        maxPages,
         formats: opts.urlsOnly ? [] : ["markdown"]
       });
       if (result.kind !== "job") {
-        error("Unexpected response - expected a crawl job");
+        spinner.error("Unexpected response");
+        error("Expected a crawl job but got a scrape result");
         process.exit(1);
       }
       const job = result.data;
+      spinner.success(`Done -- ${job.results.length} pages crawled`);
       if (opts.json) {
         outputJson(job);
         return;
@@ -186,8 +327,8 @@ ${job.results.length} URLs discovered`);
 ${job.results.length} pages crawled`);
       }
     } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      error(msg);
+      spinner.error("Failed");
+      error(formatError(err));
       process.exit(1);
     }
   });
@@ -208,13 +349,15 @@ function registerStatusCommand(program2) {
     console.log(`Reader CLI v${version}`);
     console.log(`API:     ${apiUrl}`);
     console.log(`Key:     ${redactKey(apiKey)}`);
+    const spinner = statusSpinner();
     try {
       const credits = await client.getCredits();
+      spinner.success("Connected");
       console.log(`Credits: ${credits.balance} / ${credits.limit} (${credits.tier} tier)`);
       console.log(`Resets:  ${credits.resetAt}`);
     } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      console.error(`API:     connection failed (${msg})`);
+      spinner.error("Connection failed");
+      error(formatError(err));
       process.exit(1);
     }
   });
@@ -226,8 +369,10 @@ function registerCreditsCommand(program2) {
   program2.command("credits").description("Check credit balance and usage").option("--json", "Output full JSON response").action(async (opts) => {
     const apiKey = getApiKey();
     const client = new ReaderClient4({ apiKey, baseUrl: getApiUrl() });
+    const spinner = creditsSpinner();
     try {
       const credits = await client.getCredits();
+      spinner.stop();
       if (opts.json) {
         outputJson(credits);
         return;
@@ -237,8 +382,8 @@ function registerCreditsCommand(program2) {
       console.log(`Tier:    ${credits.tier}`);
       console.log(`Resets:  ${credits.resetAt}`);
     } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      error(msg);
+      spinner.error("Failed");
+      error(formatError(err));
       process.exit(1);
     }
   });
@@ -250,10 +395,19 @@ function registerConfigCommand(program2) {
   config.command("set <key> <value>").description("Set a config value (api-key, api-url)").action((key, value) => {
     const current = loadConfig();
     if (key === "api-key") {
+      if (!value.startsWith("rdr_")) {
+        console.error(`Warning: API key doesn't start with "rdr_". This may not be a valid Reader API key.`);
+      }
       current.apiKey = value;
       saveConfig(current);
       console.error(`API key saved: ${redactKey(value)}`);
     } else if (key === "api-url") {
+      try {
+        new URL(value);
+      } catch {
+        console.error(`Error: Invalid URL: "${value}"`);
+        process.exit(1);
+      }
       current.apiUrl = value;
       saveConfig(current);
       console.error(`API URL saved: ${value}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vakra-dev/reader-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "CLI for the Reader API - read the web for your AI agents",
   "type": "module",
   "bin": {
@@ -17,7 +17,8 @@
   },
   "dependencies": {
     "@vakra-dev/reader-js": "^0.2.0",
-    "commander": "^12.0.0"
+    "commander": "^12.0.0",
+    "yocto-spinner": "^1.2.0"
   },
   "devDependencies": {
     "tsup": "^8.3.6",