@screenshotscout/cli 0.1.0

package/dist/input.js

@@ -0,0 +1,332 @@
+import { readFile } from "node:fs/promises";
+import { parseArgs } from "node:util";
+import { CAPTURE_OPTION_DEFINITIONS, } from "./capture-options.js";
+import { CliUsageError } from "./cli-usage-error.js";
+const OPTIONS_INPUT_NAME = "options";
+const METHOD_INPUT_NAME = "method";
+const OUTPUT_INPUT_NAME = "output";
+const OMIT_VALUE = Symbol("omit-value");
+const DEFINITIONS = Object.values(CAPTURE_OPTION_DEFINITIONS);
+const DEFINITIONS_BY_CLI_NAME = new Map(DEFINITIONS.map((definition) => [definition.cliName, definition]));
+const DEFINITIONS_BY_API_NAME = new Map(DEFINITIONS.map((definition) => [definition.apiName, definition]));
+const CAPTURE_PARSE_OPTIONS = createParseOptions(false);
+const CAPTURE_COMMAND_PARSE_OPTIONS = createParseOptions(true);
+const DEFAULT_INPUT_READER = {
+    readFile: (path) => readFile(path, "utf8"),
+    readStdin: readStandardInput,
+};
+/** Parse capture flags and merge an optional snake_case JSON options object. */
+export async function parseCaptureInput(args, inputReader = DEFAULT_INPUT_READER) {
+    const parsed = await parseCaptureInputInternal(args, inputReader, false);
+    return {
+        captureOptions: parsed.captureOptions,
+        positionals: parsed.positionals,
+    };
+}
+/** Parse the capture command's URL, capture options, and two CLI controls. */
+export async function parseCaptureCommandInput(args, inputReader = DEFAULT_INPUT_READER) {
+    const parsed = await parseCaptureInputInternal(args, inputReader, true);
+    if (parsed.positionals.length !== 1) {
+        throw new CliUsageError("Command 'capture' requires exactly one URL.");
+    }
+    return {
+        captureOptions: parsed.captureOptions,
+        method: parsed.method,
+        outputPath: parsed.outputPath,
+        targetUrl: parsed.positionals[0],
+    };
+}
+/** Parse the capture-url command's URL and capture options. */
+export async function parseCaptureUrlCommandInput(args, inputReader = DEFAULT_INPUT_READER) {
+    const parsed = await parseCaptureInputInternal(args, inputReader, false);
+    if (parsed.positionals.length !== 1) {
+        throw new CliUsageError("Command 'capture-url' requires exactly one URL.");
+    }
+    return {
+        captureOptions: parsed.captureOptions,
+        targetUrl: parsed.positionals[0],
+    };
+}
+async function parseCaptureInputInternal(args, inputReader, includeCaptureControls) {
+    const parsedCliInput = parseCliInput(args, includeCaptureControls);
+    let fileOptions = {};
+    if (parsedCliInput.optionsPath !== undefined) {
+        const text = parsedCliInput.optionsPath === "-"
+            ? await inputReader.readStdin()
+            : await inputReader.readFile(parsedCliInput.optionsPath);
+        fileOptions = parseOptionsObject(text);
+    }
+    return {
+        captureOptions: {
+            ...fileOptions,
+            ...parsedCliInput.captureOptions,
+        },
+        ...(parsedCliInput.method === undefined
+            ? {}
+            : { method: parsedCliInput.method }),
+        ...(parsedCliInput.outputPath === undefined
+            ? {}
+            : { outputPath: parsedCliInput.outputPath }),
+        positionals: parsedCliInput.positionals,
+    };
+}
+function createParseOptions(includeCaptureControls) {
+    const options = {};
+    for (const definition of DEFINITIONS) {
+        options[definition.cliName] = definition.multiple
+            ? { type: "string", multiple: true }
+            : { type: definition.kind === "boolean" ? "boolean" : "string" };
+    }
+    options[OPTIONS_INPUT_NAME] = { type: "string" };
+    if (includeCaptureControls) {
+        options[METHOD_INPUT_NAME] = { type: "string" };
+        options[OUTPUT_INPUT_NAME] = { type: "string", short: "o" };
+    }
+    return options;
+}
+function parseCliInput(args, includeCaptureControls) {
+    const normalized = normalizeArguments(args);
+    let parsed;
+    try {
+        parsed = parseNormalizedArguments(normalized.args, includeCaptureControls
+            ? CAPTURE_COMMAND_PARSE_OPTIONS
+            : CAPTURE_PARSE_OPTIONS);
+    }
+    catch (error) {
+        throw usageErrorFrom(error);
+    }
+    const captureOptions = {};
+    const occurrences = new Map();
+    let method;
+    let optionsPath;
+    let outputPath;
+    for (const token of parsed.tokens) {
+        if (token.kind !== "option")
+            continue;
+        const count = (occurrences.get(token.name) ?? 0) + 1;
+        occurrences.set(token.name, count);
+        if (token.name === OPTIONS_INPUT_NAME) {
+            if (count > 1)
+                throw duplicateOption(token.rawName);
+            optionsPath = requiredTokenValue(token);
+            continue;
+        }
+        if (token.name === METHOD_INPUT_NAME) {
+            if (count > 1)
+                throw duplicateOption(token.rawName);
+            method = parseCaptureMethod(requiredTokenValue(token));
+            continue;
+        }
+        if (token.name === OUTPUT_INPUT_NAME) {
+            if (count > 1)
+                throw duplicateOption(token.rawName);
+            outputPath = requiredTokenValue(token);
+            continue;
+        }
+        const definition = DEFINITIONS_BY_CLI_NAME.get(token.name);
+        if (definition === undefined) {
+            throw new Error(`Parser returned an unconfigured option '${token.name}'.`);
+        }
+        if (!definition.multiple && count > 1) {
+            throw duplicateOption(token.rawName);
+        }
+        applyCliValue(captureOptions, definition, token, normalized.booleanValues);
+    }
+    const result = {
+        captureOptions,
+        positionals: [...parsed.positionals],
+    };
+    return {
+        ...result,
+        ...(method === undefined ? {} : { method }),
+        ...(optionsPath === undefined ? {} : { optionsPath }),
+        ...(outputPath === undefined ? {} : { outputPath }),
+    };
+}
+function parseNormalizedArguments(args, options = CAPTURE_PARSE_OPTIONS) {
+    return parseArgs({
+        args,
+        allowPositionals: true,
+        options,
+        strict: true,
+        tokens: true,
+    });
+}
+function normalizeArguments(args) {
+    const normalized = [];
+    const booleanValues = new Map();
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === undefined)
+            continue;
+        if (argument === "--") {
+            normalized.push(...args.slice(index));
+            break;
+        }
+        if (!argument.startsWith("--")) {
+            normalized.push(argument);
+            continue;
+        }
+        const separatorIndex = argument.indexOf("=");
+        const cliName = argument.slice(2, separatorIndex === -1 ? undefined : separatorIndex);
+        const definition = DEFINITIONS_BY_CLI_NAME.get(cliName);
+        if (definition?.kind !== "boolean") {
+            const nextArgument = args[index + 1];
+            if (definition !== undefined &&
+                separatorIndex === -1 &&
+                nextArgument !== undefined &&
+                nextArgument.startsWith("-") &&
+                !nextArgument.startsWith("--")) {
+                normalized.push(`${argument}=${nextArgument}`);
+                index += 1;
+            }
+            else {
+                normalized.push(argument);
+            }
+            continue;
+        }
+        const normalizedIndex = normalized.length;
+        if (separatorIndex === -1) {
+            const nextArgument = args[index + 1];
+            if (nextArgument === "true" || nextArgument === "false") {
+                throw new CliUsageError(`Option '--${cliName}' does not accept a space-separated boolean value.`);
+            }
+            normalized.push(argument);
+            booleanValues.set(normalizedIndex, true);
+            continue;
+        }
+        const value = argument.slice(separatorIndex + 1);
+        if (value !== "true" && value !== "false") {
+            throw new CliUsageError(`Option '--${cliName}' accepts only 'true' or 'false' as an inline value.`);
+        }
+        normalized.push(`--${cliName}`);
+        booleanValues.set(normalizedIndex, value === "true");
+    }
+    return { args: normalized, booleanValues };
+}
+function applyCliValue(output, definition, token, booleanValues) {
+    if (definition.kind === "boolean") {
+        const value = booleanValues.get(token.index);
+        if (value === undefined) {
+            throw new Error(`Boolean option '${token.rawName}' was not normalized.`);
+        }
+        output[definition.sdkName] = value;
+        return;
+    }
+    const rawValue = requiredTokenValue(token);
+    if (definition.multiple) {
+        const current = output[definition.sdkName];
+        if (current === undefined) {
+            output[definition.sdkName] = [rawValue];
+            return;
+        }
+        if (!Array.isArray(current)) {
+            throw new Error(`Repeated option '${token.rawName}' has invalid state.`);
+        }
+        current.push(rawValue);
+        return;
+    }
+    output[definition.sdkName] =
+        definition.kind === "number"
+            ? parseFiniteNumber(rawValue, token.rawName)
+            : rawValue;
+}
+function requiredTokenValue(token) {
+    if (token.value === undefined) {
+        throw new Error(`String option '${token.rawName}' has no parsed value.`);
+    }
+    return token.value;
+}
+function parseFiniteNumber(value, optionName) {
+    const parsed = Number(value);
+    if (value.trim() === "" || !Number.isFinite(parsed)) {
+        throw new CliUsageError(`Option '${optionName}' requires a finite number.`);
+    }
+    return parsed;
+}
+function parseCaptureMethod(value) {
+    if (value !== "get" && value !== "post") {
+        throw new CliUsageError("Option '--method' must be 'get' or 'post'.");
+    }
+    return value;
+}
+function parseOptionsObject(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? ` ${error.message}` : "";
+        throw new CliUsageError(`Options input is not valid JSON.${detail}`, {
+            cause: error,
+        });
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new CliUsageError("Options input must be a JSON object.");
+    }
+    const output = {};
+    for (const [apiName, value] of Object.entries(parsed)) {
+        const definition = DEFINITIONS_BY_API_NAME.get(apiName);
+        if (definition === undefined)
+            throw unknownOption(apiName);
+        const parsedValue = parseOptionsObjectValue(definition, value);
+        if (parsedValue !== OMIT_VALUE) {
+            output[definition.sdkName] = parsedValue;
+        }
+    }
+    return output;
+}
+function parseOptionsObjectValue(definition, value) {
+    if (value === null)
+        return OMIT_VALUE;
+    if (definition.multiple) {
+        if (!Array.isArray(value) ||
+            !value.every((item) => typeof item === "string")) {
+            throw invalidOptionsType(definition.apiName, "an array of strings");
+        }
+        return value.length === 0 ? OMIT_VALUE : [...value];
+    }
+    if (definition.kind === "string") {
+        if (typeof value !== "string") {
+            throw invalidOptionsType(definition.apiName, "a string");
+        }
+        return value;
+    }
+    if (definition.kind === "number") {
+        if (typeof value !== "number" || !Number.isFinite(value)) {
+            throw invalidOptionsType(definition.apiName, "a finite number");
+        }
+        return value;
+    }
+    if (typeof value !== "boolean") {
+        throw invalidOptionsType(definition.apiName, "a boolean");
+    }
+    return value;
+}
+function invalidOptionsType(apiName, expected) {
+    return new CliUsageError(`Option '${apiName}' in the options input must be ${expected}.`);
+}
+function unknownOption(name) {
+    return new CliUsageError(`Unknown option '${name}'.`);
+}
+function duplicateOption(name) {
+    return new CliUsageError(`Option '${name}' may only be specified once.`);
+}
+function usageErrorFrom(error) {
+    return new CliUsageError(error instanceof Error ? error.message : String(error), { cause: error });
+}
+async function readStandardInput() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        if (typeof chunk === "string") {
+            chunks.push(Buffer.from(chunk));
+        }
+        else if (chunk instanceof Uint8Array) {
+            chunks.push(chunk);
+        }
+        else {
+            throw new TypeError("Standard input produced a non-byte chunk.");
+        }
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}

package/dist/result.js

@@ -0,0 +1,51 @@
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+const DEFAULT_CAPTURE_RESULT_IO = {
+    currentDirectory: () => process.cwd(),
+    writeFile: (path, bytes) => writeFile(path, bytes),
+    writeStandardOutput,
+};
+/** Save or display one successful SDK capture response without transforming it. */
+export async function writeCaptureResult(response, outputPath, io = DEFAULT_CAPTURE_RESULT_IO) {
+    const bytes = response.kind === "binary" ? response.bytes : response.rawResponse.body;
+    if (outputPath === "-" ||
+        (outputPath === undefined && response.kind === "json")) {
+        await io.writeStandardOutput(bytes);
+        return;
+    }
+    const destination = outputPath ??
+        join(io.currentDirectory(), `screenshot${captureFileExtension(response.rawResponse.contentType)}`);
+    await io.writeFile(destination, bytes);
+}
+/** Map only a returned response Content-Type to an automatic file extension. */
+export function captureFileExtension(contentType) {
+    const mediaType = contentType?.split(";", 1)[0]?.trim().toLowerCase();
+    switch (mediaType) {
+        case "image/png":
+            return ".png";
+        case "image/jpeg":
+            return ".jpg";
+        case "image/webp":
+            return ".webp";
+        case "image/gif":
+            return ".gif";
+        case "image/tiff":
+            return ".tiff";
+        case "application/pdf":
+            return ".pdf";
+        default:
+            return ".bin";
+    }
+}
+function writeStandardOutput(bytes) {
+    return new Promise((resolve, reject) => {
+        process.stdout.write(bytes, (error) => {
+            if (error === null || error === undefined) {
+                resolve();
+            }
+            else {
+                reject(error);
+            }
+        });
+    });
+}

package/dist/sdk.js

@@ -0,0 +1,23 @@
+import { CaptureHttpMethod, ScreenshotScoutClient, } from "@screenshotscout/sdk";
+const DEFAULT_CLIENT_FACTORY = (options) => new ScreenshotScoutClient(options);
+/** Construct the official SDK client from the two approved environment names. */
+export function createScreenshotScoutClient(environment = process.env, clientFactory = DEFAULT_CLIENT_FACTORY) {
+    const accessKey = environment.SCREENSHOTSCOUT_ACCESS_KEY;
+    const secretKey = environment.SCREENSHOTSCOUT_SECRET_KEY;
+    const options = {
+        // Missing and invalid values deliberately reach the SDK's own validation.
+        accessKey: accessKey,
+        ...(secretKey === undefined ? {} : { secretKey }),
+    };
+    return clientFactory(options);
+}
+/** Make one capture call with only an explicitly selected request method. */
+export function captureWithScreenshotScoutClient(client, targetUrl, captureOptions, method) {
+    if (method === undefined) {
+        return client.capture(targetUrl, captureOptions);
+    }
+    const captureRequestOptions = {
+        method: method === "get" ? CaptureHttpMethod.GET : CaptureHttpMethod.POST,
+    };
+    return client.capture(targetUrl, captureOptions, captureRequestOptions);
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@screenshotscout/cli",
+  "version": "0.1.0",
+  "description": "Official command-line interface for the Screenshot Scout screenshot API.",
+  "type": "module",
+  "bin": {
+    "screenshotscout": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "clean": "node -e \"const fs = require('node:fs'); fs.rmSync('dist', { force: true, recursive: true });\"",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "pretest": "npm run build",
+    "test": "tsx --test test/**/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "author": "Oleksii Velykyi",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/screenshotscout/screenshotscout-cli.git"
+  },
+  "homepage": "https://screenshotscout.com/docs/cli",
+  "bugs": {
+    "url": "https://github.com/screenshotscout/screenshotscout-cli/issues"
+  },
+  "keywords": [
+    "cli",
+    "command-line",
+    "screenshot",
+    "screenshot-api",
+    "screenshotscout",
+    "url-to-image",
+    "webpage-screenshot",
+    "website-screenshot"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@screenshotscout/sdk": "0.1.2"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@types/node": "22.20.1",
+    "eslint": "10.8.1",
+    "prettier": "3.9.6",
+    "tsx": "4.23.11",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.66.0"
+  }
+}