@screenshotscout/cli 0.1.0

package/dist/capture-options.js

@@ -0,0 +1,476 @@
+/**
+ * The single runtime source of truth for translating capture-option names and
+ * CLI-owned value shapes. The mapped type makes a changed SDK CaptureOptions
+ * surface a compile-time failure until this descriptor is updated deliberately.
+ */
+export const CAPTURE_OPTION_DEFINITIONS = {
+    format: {
+        sdkName: "format",
+        apiName: "format",
+        cliName: "format",
+        kind: "string",
+        multiple: false,
+    },
+    responseType: {
+        sdkName: "responseType",
+        apiName: "response_type",
+        cliName: "response-type",
+        kind: "string",
+        multiple: false,
+    },
+    country: {
+        sdkName: "country",
+        apiName: "country",
+        cliName: "country",
+        kind: "string",
+        multiple: false,
+    },
+    proxy: {
+        sdkName: "proxy",
+        apiName: "proxy",
+        cliName: "proxy",
+        kind: "string",
+        multiple: false,
+    },
+    geolocationLatitude: {
+        sdkName: "geolocationLatitude",
+        apiName: "geolocation_latitude",
+        cliName: "geolocation-latitude",
+        kind: "number",
+        multiple: false,
+    },
+    geolocationLongitude: {
+        sdkName: "geolocationLongitude",
+        apiName: "geolocation_longitude",
+        cliName: "geolocation-longitude",
+        kind: "number",
+        multiple: false,
+    },
+    geolocationAccuracy: {
+        sdkName: "geolocationAccuracy",
+        apiName: "geolocation_accuracy",
+        cliName: "geolocation-accuracy",
+        kind: "number",
+        multiple: false,
+    },
+    cookies: {
+        sdkName: "cookies",
+        apiName: "cookies",
+        cliName: "cookies",
+        kind: "string",
+        multiple: true,
+    },
+    headers: {
+        sdkName: "headers",
+        apiName: "headers",
+        cliName: "headers",
+        kind: "string",
+        multiple: true,
+    },
+    timeout: {
+        sdkName: "timeout",
+        apiName: "timeout",
+        cliName: "timeout",
+        kind: "number",
+        multiple: false,
+    },
+    waitUntil: {
+        sdkName: "waitUntil",
+        apiName: "wait_until",
+        cliName: "wait-until",
+        kind: "string",
+        multiple: false,
+    },
+    navigationTimeout: {
+        sdkName: "navigationTimeout",
+        apiName: "navigation_timeout",
+        cliName: "navigation-timeout",
+        kind: "number",
+        multiple: false,
+    },
+    delay: {
+        sdkName: "delay",
+        apiName: "delay",
+        cliName: "delay",
+        kind: "number",
+        multiple: false,
+    },
+    device: {
+        sdkName: "device",
+        apiName: "device",
+        cliName: "device",
+        kind: "string",
+        multiple: false,
+    },
+    deviceViewportWidth: {
+        sdkName: "deviceViewportWidth",
+        apiName: "device_viewport_width",
+        cliName: "device-viewport-width",
+        kind: "number",
+        multiple: false,
+    },
+    deviceViewportHeight: {
+        sdkName: "deviceViewportHeight",
+        apiName: "device_viewport_height",
+        cliName: "device-viewport-height",
+        kind: "number",
+        multiple: false,
+    },
+    deviceScaleFactor: {
+        sdkName: "deviceScaleFactor",
+        apiName: "device_scale_factor",
+        cliName: "device-scale-factor",
+        kind: "number",
+        multiple: false,
+    },
+    deviceIsMobile: {
+        sdkName: "deviceIsMobile",
+        apiName: "device_is_mobile",
+        cliName: "device-is-mobile",
+        kind: "boolean",
+        multiple: false,
+    },
+    deviceHasTouch: {
+        sdkName: "deviceHasTouch",
+        apiName: "device_has_touch",
+        cliName: "device-has-touch",
+        kind: "boolean",
+        multiple: false,
+    },
+    deviceUserAgent: {
+        sdkName: "deviceUserAgent",
+        apiName: "device_user_agent",
+        cliName: "device-user-agent",
+        kind: "string",
+        multiple: false,
+    },
+    timezone: {
+        sdkName: "timezone",
+        apiName: "timezone",
+        cliName: "timezone",
+        kind: "string",
+        multiple: false,
+    },
+    mediaType: {
+        sdkName: "mediaType",
+        apiName: "media_type",
+        cliName: "media-type",
+        kind: "string",
+        multiple: false,
+    },
+    colorScheme: {
+        sdkName: "colorScheme",
+        apiName: "color_scheme",
+        cliName: "color-scheme",
+        kind: "string",
+        multiple: false,
+    },
+    reducedMotion: {
+        sdkName: "reducedMotion",
+        apiName: "reduced_motion",
+        cliName: "reduced-motion",
+        kind: "boolean",
+        multiple: false,
+    },
+    fullPage: {
+        sdkName: "fullPage",
+        apiName: "full_page",
+        cliName: "full-page",
+        kind: "boolean",
+        multiple: false,
+    },
+    fullPagePreScroll: {
+        sdkName: "fullPagePreScroll",
+        apiName: "full_page_pre_scroll",
+        cliName: "full-page-pre-scroll",
+        kind: "boolean",
+        multiple: false,
+    },
+    fullPagePreScrollStep: {
+        sdkName: "fullPagePreScrollStep",
+        apiName: "full_page_pre_scroll_step",
+        cliName: "full-page-pre-scroll-step",
+        kind: "number",
+        multiple: false,
+    },
+    fullPagePreScrollStepDelay: {
+        sdkName: "fullPagePreScrollStepDelay",
+        apiName: "full_page_pre_scroll_step_delay",
+        cliName: "full-page-pre-scroll-step-delay",
+        kind: "number",
+        multiple: false,
+    },
+    fullPageMaxHeight: {
+        sdkName: "fullPageMaxHeight",
+        apiName: "full_page_max_height",
+        cliName: "full-page-max-height",
+        kind: "number",
+        multiple: false,
+    },
+    blockCookieBanners: {
+        sdkName: "blockCookieBanners",
+        apiName: "block_cookie_banners",
+        cliName: "block-cookie-banners",
+        kind: "boolean",
+        multiple: false,
+    },
+    blockAds: {
+        sdkName: "blockAds",
+        apiName: "block_ads",
+        cliName: "block-ads",
+        kind: "boolean",
+        multiple: false,
+    },
+    blockChatWidgets: {
+        sdkName: "blockChatWidgets",
+        apiName: "block_chat_widgets",
+        cliName: "block-chat-widgets",
+        kind: "boolean",
+        multiple: false,
+    },
+    hideSelectors: {
+        sdkName: "hideSelectors",
+        apiName: "hide_selectors",
+        cliName: "hide-selectors",
+        kind: "string",
+        multiple: true,
+    },
+    clickSelectors: {
+        sdkName: "clickSelectors",
+        apiName: "click_selectors",
+        cliName: "click-selectors",
+        kind: "string",
+        multiple: true,
+    },
+    clickAllSelectors: {
+        sdkName: "clickAllSelectors",
+        apiName: "click_all_selectors",
+        cliName: "click-all-selectors",
+        kind: "string",
+        multiple: true,
+    },
+    injectCss: {
+        sdkName: "injectCss",
+        apiName: "inject_css",
+        cliName: "inject-css",
+        kind: "string",
+        multiple: true,
+    },
+    injectJs: {
+        sdkName: "injectJs",
+        apiName: "inject_js",
+        cliName: "inject-js",
+        kind: "string",
+        multiple: true,
+    },
+    bypassCsp: {
+        sdkName: "bypassCsp",
+        apiName: "bypass_csp",
+        cliName: "bypass-csp",
+        kind: "boolean",
+        multiple: false,
+    },
+    selector: {
+        sdkName: "selector",
+        apiName: "selector",
+        cliName: "selector",
+        kind: "string",
+        multiple: false,
+    },
+    clipX: {
+        sdkName: "clipX",
+        apiName: "clip_x",
+        cliName: "clip-x",
+        kind: "number",
+        multiple: false,
+    },
+    clipY: {
+        sdkName: "clipY",
+        apiName: "clip_y",
+        cliName: "clip-y",
+        kind: "number",
+        multiple: false,
+    },
+    clipWidth: {
+        sdkName: "clipWidth",
+        apiName: "clip_width",
+        cliName: "clip-width",
+        kind: "number",
+        multiple: false,
+    },
+    clipHeight: {
+        sdkName: "clipHeight",
+        apiName: "clip_height",
+        cliName: "clip-height",
+        kind: "number",
+        multiple: false,
+    },
+    imageWidth: {
+        sdkName: "imageWidth",
+        apiName: "image_width",
+        cliName: "image-width",
+        kind: "number",
+        multiple: false,
+    },
+    imageHeight: {
+        sdkName: "imageHeight",
+        apiName: "image_height",
+        cliName: "image-height",
+        kind: "number",
+        multiple: false,
+    },
+    imageMode: {
+        sdkName: "imageMode",
+        apiName: "image_mode",
+        cliName: "image-mode",
+        kind: "string",
+        multiple: false,
+    },
+    imageAnchor: {
+        sdkName: "imageAnchor",
+        apiName: "image_anchor",
+        cliName: "image-anchor",
+        kind: "string",
+        multiple: false,
+    },
+    imageAllowUpscale: {
+        sdkName: "imageAllowUpscale",
+        apiName: "image_allow_upscale",
+        cliName: "image-allow-upscale",
+        kind: "boolean",
+        multiple: false,
+    },
+    imageBackground: {
+        sdkName: "imageBackground",
+        apiName: "image_background",
+        cliName: "image-background",
+        kind: "string",
+        multiple: false,
+    },
+    imageQuality: {
+        sdkName: "imageQuality",
+        apiName: "image_quality",
+        cliName: "image-quality",
+        kind: "number",
+        multiple: false,
+    },
+    pdfPaperFormat: {
+        sdkName: "pdfPaperFormat",
+        apiName: "pdf_paper_format",
+        cliName: "pdf-paper-format",
+        kind: "string",
+        multiple: false,
+    },
+    pdfLandscape: {
+        sdkName: "pdfLandscape",
+        apiName: "pdf_landscape",
+        cliName: "pdf-landscape",
+        kind: "boolean",
+        multiple: false,
+    },
+    pdfPrintBackground: {
+        sdkName: "pdfPrintBackground",
+        apiName: "pdf_print_background",
+        cliName: "pdf-print-background",
+        kind: "boolean",
+        multiple: false,
+    },
+    pdfMargin: {
+        sdkName: "pdfMargin",
+        apiName: "pdf_margin",
+        cliName: "pdf-margin",
+        kind: "string",
+        multiple: false,
+    },
+    pdfMarginTop: {
+        sdkName: "pdfMarginTop",
+        apiName: "pdf_margin_top",
+        cliName: "pdf-margin-top",
+        kind: "string",
+        multiple: false,
+    },
+    pdfMarginRight: {
+        sdkName: "pdfMarginRight",
+        apiName: "pdf_margin_right",
+        cliName: "pdf-margin-right",
+        kind: "string",
+        multiple: false,
+    },
+    pdfMarginBottom: {
+        sdkName: "pdfMarginBottom",
+        apiName: "pdf_margin_bottom",
+        cliName: "pdf-margin-bottom",
+        kind: "string",
+        multiple: false,
+    },
+    pdfMarginLeft: {
+        sdkName: "pdfMarginLeft",
+        apiName: "pdf_margin_left",
+        cliName: "pdf-margin-left",
+        kind: "string",
+        multiple: false,
+    },
+    pdfScale: {
+        sdkName: "pdfScale",
+        apiName: "pdf_scale",
+        cliName: "pdf-scale",
+        kind: "number",
+        multiple: false,
+    },
+    cache: {
+        sdkName: "cache",
+        apiName: "cache",
+        cliName: "cache",
+        kind: "boolean",
+        multiple: false,
+    },
+    cacheTtl: {
+        sdkName: "cacheTtl",
+        apiName: "cache_ttl",
+        cliName: "cache-ttl",
+        kind: "number",
+        multiple: false,
+    },
+    cacheKey: {
+        sdkName: "cacheKey",
+        apiName: "cache_key",
+        cliName: "cache-key",
+        kind: "string",
+        multiple: false,
+    },
+    storageMode: {
+        sdkName: "storageMode",
+        apiName: "storage_mode",
+        cliName: "storage-mode",
+        kind: "string",
+        multiple: false,
+    },
+    storageEndpoint: {
+        sdkName: "storageEndpoint",
+        apiName: "storage_endpoint",
+        cliName: "storage-endpoint",
+        kind: "string",
+        multiple: false,
+    },
+    storageBucket: {
+        sdkName: "storageBucket",
+        apiName: "storage_bucket",
+        cliName: "storage-bucket",
+        kind: "string",
+        multiple: false,
+    },
+    storageRegion: {
+        sdkName: "storageRegion",
+        apiName: "storage_region",
+        cliName: "storage-region",
+        kind: "string",
+        multiple: false,
+    },
+    storageObjectKey: {
+        sdkName: "storageObjectKey",
+        apiName: "storage_object_key",
+        cliName: "storage-object-key",
+        kind: "string",
+        multiple: false,
+    },
+};

package/dist/capture-url.js

@@ -0,0 +1,23 @@
+import { parseCaptureUrlCommandInput } from "./input.js";
+import { createScreenshotScoutClient, } from "./sdk.js";
+/** Run one capture-url command as a direct input -> SDK -> output adapter. */
+export async function runCaptureUrlCommand(args, dependencies = {}) {
+    const input = dependencies.inputReader === undefined
+        ? await parseCaptureUrlCommandInput(args)
+        : await parseCaptureUrlCommandInput(args, dependencies.inputReader);
+    const client = dependencies.client ?? createScreenshotScoutClient();
+    const captureUrl = client.buildCaptureUrl(input.targetUrl, input.captureOptions);
+    await (dependencies.writeStandardOutput ?? writeStandardOutput)(`${captureUrl}\n`);
+}
+function writeStandardOutput(text) {
+    return new Promise((resolve, reject) => {
+        process.stdout.write(text, (error) => {
+            if (error === null || error === undefined) {
+                resolve();
+            }
+            else {
+                reject(error);
+            }
+        });
+    });
+}

package/dist/capture.js

@@ -0,0 +1,17 @@
+import { parseCaptureCommandInput } from "./input.js";
+import { writeCaptureResult } from "./result.js";
+import { captureWithScreenshotScoutClient, createScreenshotScoutClient, } from "./sdk.js";
+/** Run one capture command as a direct input -> SDK -> result adapter. */
+export async function runCaptureCommand(args, dependencies = {}) {
+    const input = dependencies.inputReader === undefined
+        ? await parseCaptureCommandInput(args)
+        : await parseCaptureCommandInput(args, dependencies.inputReader);
+    const client = dependencies.client ?? createScreenshotScoutClient();
+    const response = await captureWithScreenshotScoutClient(client, input.targetUrl, input.captureOptions, input.method);
+    if (dependencies.resultIo === undefined) {
+        await writeCaptureResult(response, input.outputPath);
+    }
+    else {
+        await writeCaptureResult(response, input.outputPath, dependencies.resultIo);
+    }
+}

package/dist/cli-usage-error.js

@@ -0,0 +1,8 @@
+/** A locally detected command syntax or input-shape failure. */
+export class CliUsageError extends Error {
+    exitCode = 2;
+    constructor(message, options) {
+        super(message, options);
+        this.name = "CliUsageError";
+    }
+}

package/dist/cli.js

@@ -0,0 +1,96 @@
+import { readFileSync } from "node:fs";
+import { ScreenshotScoutApiError } from "@screenshotscout/sdk";
+import { runCaptureUrlCommand } from "./capture-url.js";
+import { runCaptureCommand } from "./capture.js";
+import { CliUsageError } from "./cli-usage-error.js";
+import { captureCommandHelp, captureUrlCommandHelp, ROOT_HELP, } from "./help.js";
+/** Strictly dispatch one root CLI invocation. Command failures propagate. */
+export async function runCli(args, dependencies = {}) {
+    const writeStandardOutput = dependencies.writeStandardOutput ?? defaultWriteStandardOutput;
+    if (args.length === 0) {
+        throw new CliUsageError("A command is required.");
+    }
+    if (args.length === 1 && args[0] === "--help") {
+        await writeStandardOutput(ROOT_HELP);
+        return;
+    }
+    if (args.length === 1 && args[0] === "--version") {
+        await writeStandardOutput(`${readPackageVersion()}\n`);
+        return;
+    }
+    const command = args[0];
+    const commandArgs = args.slice(1);
+    if (command === "capture") {
+        if (commandArgs.length === 1 && commandArgs[0] === "--help") {
+            await writeStandardOutput(captureCommandHelp());
+            return;
+        }
+        await (dependencies.runCapture ?? runCaptureCommand)(commandArgs);
+        return;
+    }
+    if (command === "capture-url") {
+        if (commandArgs.length === 1 && commandArgs[0] === "--help") {
+            await writeStandardOutput(captureUrlCommandHelp());
+            return;
+        }
+        await (dependencies.runCaptureUrl ?? runCaptureUrlCommand)(commandArgs);
+        return;
+    }
+    throw new CliUsageError(`Unknown command '${command}'.`);
+}
+/** Run the executable behind one concise failure and exit-code boundary. */
+export async function runCliExecutable(args, dependencies = {}) {
+    try {
+        await runCli(args, dependencies);
+        return 0;
+    }
+    catch (error) {
+        const exitCode = error instanceof CliUsageError ? 2 : 1;
+        try {
+            const writeStandardError = dependencies.writeStandardError ?? defaultWriteStandardError;
+            await writeStandardError(formatFailure(error));
+        }
+        catch {
+            // A failed failure-message write has no additional safe output channel.
+        }
+        return exitCode;
+    }
+}
+/** Format only the approved human-readable message and API details. */
+export function formatFailure(error) {
+    let output = `${error instanceof Error ? error.message : String(error)}\n`;
+    if (error instanceof ScreenshotScoutApiError &&
+        error.errors !== undefined &&
+        error.errors.length > 0) {
+        output += `${JSON.stringify(error.errors)}\n`;
+    }
+    return output;
+}
+function readPackageVersion() {
+    const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    if (packageJson === null ||
+        typeof packageJson !== "object" ||
+        !("version" in packageJson) ||
+        typeof packageJson.version !== "string") {
+        throw new Error("The CLI package version is unavailable.");
+    }
+    return packageJson.version;
+}
+function defaultWriteStandardOutput(text) {
+    return writeProcessStream(process.stdout, text);
+}
+function defaultWriteStandardError(text) {
+    return writeProcessStream(process.stderr, text);
+}
+function writeProcessStream(stream, text) {
+    return new Promise((resolve, reject) => {
+        stream.write(text, (error) => {
+            if (error === null || error === undefined) {
+                resolve();
+            }
+            else {
+                reject(error);
+            }
+        });
+    });
+}

package/dist/help.js

@@ -0,0 +1,59 @@
+import { CAPTURE_OPTION_DEFINITIONS, } from "./capture-options.js";
+export const ROOT_HELP = `Screenshot Scout CLI
+
+Usage:
+  screenshotscout capture <url> [capture options] [CLI controls]
+  screenshotscout capture-url <url> [capture options]
+  screenshotscout --help
+  screenshotscout --version
+
+Commands:
+  capture      Capture one URL.
+  capture-url  Build one capture URL locally.
+
+Options:
+  --help       Show root help.
+  --version    Show the CLI version.
+
+Run "screenshotscout <command> --help" for command options.
+`;
+const CAPTURE_OPTION_HELP = Object.values(CAPTURE_OPTION_DEFINITIONS)
+    .map(formatCaptureOption)
+    .join("\n");
+export function captureCommandHelp() {
+    return `Usage:
+  screenshotscout capture <url> [capture options] [CLI controls]
+
+CLI controls:
+  --options <path|->       Read a snake_case JSON options object from a file or standard input.
+  --method <get|post>      Select the SDK capture request method.
+  -o, --output <path|->    Write the response to a file or standard output.
+  --help                   Show this help.
+
+Capture options:
+${CAPTURE_OPTION_HELP}
+
+Boolean capture options accept a bare flag or an inline true/false value.
+Repeatable capture options preserve order and duplicates.
+`;
+}
+export function captureUrlCommandHelp() {
+    return `Usage:
+  screenshotscout capture-url <url> [capture options]
+
+CLI controls:
+  --options <path|->   Read a snake_case JSON options object from a file or standard input.
+  --help               Show this help.
+
+Capture options:
+${CAPTURE_OPTION_HELP}
+
+Boolean capture options accept a bare flag or an inline true/false value.
+Repeatable capture options preserve order and duplicates.
+`;
+}
+function formatCaptureOption(definition) {
+    const valueShape = definition.kind === "boolean" ? "[=true|false]" : ` <${definition.kind}>`;
+    const repetition = definition.multiple ? " (repeatable)" : "";
+    return `  --${definition.cliName}${valueShape}${repetition}`;
+}

package/dist/index.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runCliExecutable } from "./cli.js";
+process.exitCode = await runCliExecutable(process.argv.slice(2));