Add verbose CLI debug logging

src/auth/commands/setup.ts

@@ -1,14 +1,14 @@
 import { stdin as input, stdout as output } from "node:process";
 import { createInterface } from "node:readline/promises";
 import { Command } from "commander";
+import { getRootOpts } from "../../cli/services/global-opts.js";
 import {
   CliUsageError,
   handleCliError,
 } from "../../platform/services/handle-cli-error.js";
 import { validateAuthToken } from "../../scrape/services/auth-validation.js";
 import { PLAYGROUND_URL } from "../constants.js";
 import { getConfigPath, writeConfig } from "../services/config.js";
-import { getRootOpts } from "../services/global-opts.js";
 
 const TOKEN_PROMPT = `Paste your Web Scraping API basic auth token (${PLAYGROUND_URL}): `;
 

src/auth/commands/whoami.ts

@@ -1,7 +1,7 @@
 import { Command } from "commander";
+import { getRootOpts } from "../../cli/services/global-opts.js";
 import { handleCliError } from "../../platform/services/handle-cli-error.js";
 import { AuthRequiredError } from "../errors/auth-required-error.js";
-import { getRootOpts } from "../services/global-opts.js";
 import { mask } from "../services/mask.js";
 import { resolveAuthToken } from "../services/resolve-token.js";
 

src/cli/services/global-opts.ts

@@ -0,0 +1,16 @@
+import type { Command } from "commander";
+
+export interface RootOptions {
+  token?: string;
+  verbose?: boolean;
+}
+
+export function getRootOpts(command: Command): RootOptions {
+  let current: Command = command;
+
+  while (current.parent) {
+    current = current.parent;
+  }
+
+  return current.opts() as RootOptions;
+}

src/cli/services/verbose-log.ts

@@ -0,0 +1,7 @@
+export function verboseLog(enabled: boolean, message: string): void {
+  if (!enabled) {
+    return;
+  }
+
+  process.stderr.write(`[verbose] ${message}\n`);
+}

src/index.ts

@@ -23,6 +23,7 @@ const program = new Command()
   .name("decodo")
   .description("Official CLI for Decodo APIs")
   .version(readVersion(), "-V, --version", "output the version number")
+  .option("-v, --verbose", "Print debug logs to stderr")
   .option(
     "--token <token>",
     "Basic auth token (overrides DECODO_AUTH_TOKEN and saved config)"

src/scrape/services/format-scrape-request-log.ts

@@ -0,0 +1,39 @@
+const SENSITIVE_QUERY_PARAM_KEYS = new Set([
+  "auth",
+  "authorization",
+  "apikey",
+  "api_key",
+  "key",
+  "password",
+  "secret",
+  "token",
+]);
+
+function sanitizeUrlForLog(value: string): string {
+  try {
+    const parsed = new URL(value);
+    for (const key of parsed.searchParams.keys()) {
+      if (SENSITIVE_QUERY_PARAM_KEYS.has(key.toLowerCase())) {
+        parsed.searchParams.set(key, "<redacted>");
+      }
+    }
+    return parsed.toString();
+  } catch {
+    return value;
+  }
+}
+
+export function formatScrapeRequestLog(body: Record<string, unknown>): string {
+  const target = typeof body.target === "string" ? body.target : "unknown";
+  const url = typeof body.url === "string" ? sanitizeUrlForLog(body.url) : null;
+  if (url !== null) {
+    return `request target=${target} url=${url}`;
+  }
+
+  const query = typeof body.query === "string" ? body.query : null;
+  if (query !== null) {
+    return `request target=${target} query=${query}`;
+  }
+
+  return `request target=${target}`;
+}

src/scrape/services/run-target-scrape.ts

@@ -1,7 +1,9 @@
 import type { DecodoSchema, ScrapeRequest } from "@decodo/sdk-ts";
 import type { Command } from "commander";
-import { getRootOpts } from "../../auth/services/global-opts.js";
-import { requireAuthToken } from "../../auth/services/resolve-token.js";
+import { AuthRequiredError } from "../../auth/errors/auth-required-error.js";
+import { resolveAuthToken } from "../../auth/services/resolve-token.js";
+import { getRootOpts } from "../../cli/services/global-opts.js";
+import { verboseLog } from "../../cli/services/verbose-log.js";
 import { writeScrapeResponse } from "../../output/services/write-scrape-response.js";
 import type { OutputOptions } from "../../output/types/output-options.js";
 import type { WriteScrapeResponseContext } from "../../output/types/write-scrape-response.js";
@@ -12,19 +14,23 @@ import type {
 } from "../types/run-target-scrape.js";
 import { createDecodoClient } from "./client.js";
 import { buildScrapeBody, getTargetCommandConfig } from "./command-builder.js";
+import { formatScrapeRequestLog } from "./format-scrape-request-log.js";
 
 export async function executeScrape(
   token: string,
   schema: DecodoSchema,
   body: Record<string, unknown>,
   options: Record<string, unknown>,
   outputContext?: Partial<WriteScrapeResponseContext>,
-  input?: string
+  input?: string,
+  verbose = false
 ): Promise<void> {
   const client = createDecodoClient(token, schema);
+  const startedAt = Date.now();
   const response = await client.webScrapingApi.scrape(
     body as unknown as ScrapeRequest
   );
+  verboseLog(verbose, `response latency_ms=${Date.now() - startedAt}`);
 
   writeScrapeResponse(response, {
     options: options as OutputOptions,
@@ -51,12 +57,27 @@ export function createTargetAction(
     command: Command
   ): Promise<void> => {
     const rootOpts = getRootOpts(command);
+    const verbose = rootOpts.verbose === true;
 
     try {
-      const token = await requireAuthToken({ token: rootOpts.token });
+      const auth = await resolveAuthToken({ token: rootOpts.token });
+      verboseLog(verbose, `auth source=${auth.source}`);
+      if (!auth.token) {
+        throw new AuthRequiredError();
+      }
+
       const body = resolveBody(input, options);
+      verboseLog(verbose, formatScrapeRequestLog(body));
       const outputContext = getOutputContext?.(input, options);
-      await executeScrape(token, schema, body, options, outputContext, input);
+      await executeScrape(
+        auth.token,
+        schema,
+        body,
+        options,
+        outputContext,
+        input,
+        verbose
+      );
     } catch (err) {
       handleCliError(err, { fallbackMessage: "Scrape failed." });
     }

tests/index.test.ts

@@ -19,4 +19,14 @@ describe("cli", () => {
 
     expect(output).toBe(packageJson.version);
   });
+
+  it("shows verbose flag in root help", () => {
+    const output = execFileSync(
+      process.execPath,
+      [join(rootDir, "..", "build", "esm", "index.js"), "--help"],
+      { encoding: "utf8" }
+    );
+
+    expect(output).toContain("-v, --verbose");
+  });
 });

tests/scrape/commands/scrape.test.ts

@@ -1,12 +1,12 @@
 import { BundledSchema, ValidationError } from "@decodo/sdk-ts";
 import { Command } from "commander";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { requireAuthToken } from "../../../src/auth/services/resolve-token.js";
+import { resolveAuthToken } from "../../../src/auth/services/resolve-token.js";
 import { createScrapeCommand } from "../../../src/scrape/commands/scrape.js";
 import { createDecodoClient } from "../../../src/scrape/services/client.js";
 
 vi.mock("../../../src/auth/services/resolve-token.js", () => ({
-  requireAuthToken: vi.fn(),
+  resolveAuthToken: vi.fn(),
 }));
 
 vi.mock("../../../src/scrape/services/client.js", () => ({
@@ -26,7 +26,10 @@ describe("createScrapeCommand", () => {
       configurable: true,
     });
 
-    vi.mocked(requireAuthToken).mockResolvedValue("test-token");
+    vi.mocked(resolveAuthToken).mockResolvedValue({
+      token: "test-token",
+      source: "flag",
+    });
     vi.spyOn(process, "exit").mockImplementation((code) => {
       exitCode = code as number;
       throw new Error(`process.exit:${code}`);

tests/scrape/commands/screenshot.test.ts

@@ -4,7 +4,7 @@ import { join } from "node:path";
 import { BundledSchema, ValidationError } from "@decodo/sdk-ts";
 import { Command } from "commander";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { requireAuthToken } from "../../../src/auth/services/resolve-token.js";
+import { resolveAuthToken } from "../../../src/auth/services/resolve-token.js";
 import { BINARY_TTY_ERROR } from "../../../src/platform/services/write-binary.js";
 import { createScreenshotCommand } from "../../../src/scrape/commands/screenshot.js";
 import { createDecodoClient } from "../../../src/scrape/services/client.js";
@@ -13,7 +13,7 @@ const MINIMAL_PNG_BASE64 =
   "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAD0JEQVQImWP4GwADAwEAAv6C7p4AAAAASUVORK5CYII=";
 
 vi.mock("../../../src/auth/services/resolve-token.js", () => ({
-  requireAuthToken: vi.fn(),
+  resolveAuthToken: vi.fn(),
 }));
 
 vi.mock("../../../src/scrape/services/client.js", () => ({
@@ -30,7 +30,10 @@ describe("createScreenshotCommand", () => {
     stderr = [];
     stdoutBytes = undefined;
 
-    vi.mocked(requireAuthToken).mockResolvedValue("test-token");
+    vi.mocked(resolveAuthToken).mockResolvedValue({
+      token: "test-token",
+      source: "flag",
+    });
     vi.spyOn(process, "exit").mockImplementation((code) => {
       exitCode = code as number;
       throw new Error(`process.exit:${code}`);

tests/scrape/commands/search.test.ts

@@ -1,12 +1,12 @@
 import { BundledSchema, ValidationError } from "@decodo/sdk-ts";
 import { Command } from "commander";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { requireAuthToken } from "../../../src/auth/services/resolve-token.js";
+import { resolveAuthToken } from "../../../src/auth/services/resolve-token.js";
 import { createSearchCommand } from "../../../src/scrape/commands/search.js";
 import { createDecodoClient } from "../../../src/scrape/services/client.js";
 
 vi.mock("../../../src/auth/services/resolve-token.js", () => ({
-  requireAuthToken: vi.fn(),
+  resolveAuthToken: vi.fn(),
 }));
 
 vi.mock("../../../src/scrape/services/client.js", () => ({
@@ -26,7 +26,10 @@ describe("createSearchCommand", () => {
       configurable: true,
     });
 
-    vi.mocked(requireAuthToken).mockResolvedValue("test-token");
+    vi.mocked(resolveAuthToken).mockResolvedValue({
+      token: "test-token",
+      source: "flag",
+    });
     vi.spyOn(process, "exit").mockImplementation((code) => {
       exitCode = code as number;
       throw new Error(`process.exit:${code}`);

tests/scrape/services/format-scrape-request-log.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import { formatScrapeRequestLog } from "../../../src/scrape/services/format-scrape-request-log.js";
+
+describe("formatScrapeRequestLog", () => {
+  it("formats query-based requests", () => {
+    expect(
+      formatScrapeRequestLog({ target: "google_search", query: "coffee" })
+    ).toBe("request target=google_search query=coffee");
+  });
+
+  it("redacts sensitive URL query params", () => {
+    expect(
+      formatScrapeRequestLog({
+        target: "universal",
+        url: "https://example.com?token=secret&page=1",
+      })
+    ).toBe(
+      "request target=universal url=https://example.com/?token=%3Credacted%3E&page=1"
+    );
+  });
+
+  it("falls back to target only when body has no url or query", () => {
+    expect(formatScrapeRequestLog({ target: "amazon_product" })).toBe(
+      "request target=amazon_product"
+    );
+  });
+});