@screenshotscout/cli 0.7.0 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +21 -2
- package/dist/capture.js +20 -1
- package/dist/help.js +4 -1
- package/dist/input.js +67 -32
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -85,7 +85,21 @@ screenshotscout capture "https://example.com" \
|
|
|
85
85
|
screenshotscout capture "https://example.com" --method post --format webp --output screenshot.webp
|
|
86
86
|
```
|
|
87
87
|
|
|
88
|
-
|
|
88
|
+
To render an HTML document instead of a URL, such as an invoice or a report you generated, pass `--html` with the path of an HTML file:
|
|
89
|
+
|
|
90
|
+
```sh
|
|
91
|
+
screenshotscout capture --html invoice.html --format pdf -o invoice.pdf
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
`--html -` reads the HTML from standard input instead. `capture` takes either one URL or `--html`, not both.
|
|
95
|
+
|
|
96
|
+
Send a complete document that starts with `<!doctype html>`. A PDF takes its title from `<title>`. The page has no URL, so use absolute URLs for images, stylesheets and fonts, or add a `<base href>`. See [How to Render HTML](https://screenshotscout.com/docs/guides/render-html) for more.
|
|
97
|
+
|
|
98
|
+
The HTML is read as UTF-8, with or without a byte-order mark, or as UTF-16 when it starts with a UTF-16 byte-order mark. Windows PowerShell 5.1 writes UTF-16 files by default.
|
|
99
|
+
|
|
100
|
+
The HTML is sent in a POST request, which can't be signed. So `--html` can't be combined with `--method get`, and it needs an API key that doesn't require signed requests, with `SCREENSHOTSCOUT_SECRET_KEY` unset.
|
|
101
|
+
|
|
102
|
+
`--html`, `--method` and `--output` (or `-o`) are `capture` controls and are not accepted by `capture-url`.
|
|
89
103
|
|
|
90
104
|
### Build a capture URL
|
|
91
105
|
|
|
@@ -137,7 +151,7 @@ screenshotscout capture "https://example.com" \
|
|
|
137
151
|
--headers "X-Example: cli"
|
|
138
152
|
```
|
|
139
153
|
|
|
140
|
-
Repeated values are not comma-split. Each CLI control (`--options`, `--method`, and `--output`) may also be supplied only once.
|
|
154
|
+
Repeated values are not comma-split. Each CLI control (`--html`, `--options`, `--method`, and `--output`) may also be supplied only once.
|
|
141
155
|
|
|
142
156
|
### Options files
|
|
143
157
|
|
|
@@ -166,6 +180,8 @@ printf '%s' '{"format":"webp","full_page":true,"block_cookie_banners":true}' |
|
|
|
166
180
|
screenshotscout capture "https://example.com" --options - --output screenshot.webp
|
|
167
181
|
```
|
|
168
182
|
|
|
183
|
+
Options files work the same with `capture --html`. Only one of `--options` and `--html` can read standard input, so `--options -` can't be combined with `--html -`.
|
|
184
|
+
|
|
169
185
|
Options files are JSON data only; they do not support YAML, templates, environment interpolation, or nested includes. JSON `null` values and empty repeated arrays are omitted. Empty strings, `false`, and zero are retained.
|
|
170
186
|
|
|
171
187
|
Values from explicit capture flags override values from the options file. An explicit repeated flag replaces the corresponding options-file array instead of appending to it.
|
|
@@ -230,6 +246,9 @@ More inline-flag, options-file, POSIX shell, PowerShell, and CI examples are in
|
|
|
230
246
|
- Run `screenshotscout --help` or `screenshotscout <command> --help` to check command syntax and current capture-option value shapes.
|
|
231
247
|
- If the CLI reports that an access key is required, set `SCREENSHOTSCOUT_ACCESS_KEY` in the same process environment that runs the command.
|
|
232
248
|
- If the API reports `signature_required`, set the matching `SCREENSHOTSCOUT_SECRET_KEY`. See [Signed requests](https://screenshotscout.com/docs/signed-requests).
|
|
249
|
+
- If `--html` fails because `SCREENSHOTSCOUT_SECRET_KEY` is set, or the API reports `signature_required` for it, use an API key that doesn't require signed requests, without `SCREENSHOTSCOUT_SECRET_KEY`. HTML is sent in a POST request, which can't be signed.
|
|
250
|
+
- If non-ASCII characters from an `--html` document come out wrong, save the file as UTF-8, or as UTF-16 with a byte-order mark, and pass its path. Windows PowerShell 5.1 replaces these characters when it pipes text to another program.
|
|
251
|
+
- If images, stylesheets or fonts are missing from an `--html` capture, use absolute URLs or add a `<base href>`: the page has no URL, so relative links don't resolve.
|
|
233
252
|
- If an option is rejected with exit status `2`, check whether it uses CLI `kebab-case`, whether a boolean uses bare or inline syntax, and whether a singleton flag was repeated.
|
|
234
253
|
- If an options file is rejected, confirm that it is a JSON object using exact API `snake_case` names and JSON value types.
|
|
235
254
|
- If a file write fails, confirm that its parent directory exists and is writable.
|
package/dist/capture.js
CHANGED
|
@@ -1,13 +1,17 @@
|
|
|
1
|
+
import { ScreenshotScoutConfigurationError, } from "@screenshotscout/sdk";
|
|
1
2
|
import { parseCaptureCommandInput } from "./input.js";
|
|
2
3
|
import { writeCaptureResult } from "./result.js";
|
|
3
4
|
import { captureWithScreenshotScoutClient, createScreenshotScoutClient, } from "./sdk.js";
|
|
5
|
+
const UNSET_SECRET_KEY_FOR_HTML = "Unset SCREENSHOTSCOUT_SECRET_KEY to send HTML.";
|
|
4
6
|
/** Run one capture command as a direct input -> SDK -> result adapter. */
|
|
5
7
|
export async function runCaptureCommand(args, dependencies = {}) {
|
|
6
8
|
const input = dependencies.inputReader === undefined
|
|
7
9
|
? await parseCaptureCommandInput(args)
|
|
8
10
|
: await parseCaptureCommandInput(args, dependencies.inputReader);
|
|
9
11
|
const client = dependencies.client ?? createScreenshotScoutClient();
|
|
10
|
-
const response =
|
|
12
|
+
const response = input.html === undefined
|
|
13
|
+
? await captureWithScreenshotScoutClient(client, input.targetUrl, input.captureOptions, input.method)
|
|
14
|
+
: await captureHtml(client, input.html, input.captureOptions);
|
|
11
15
|
if (dependencies.resultIo === undefined) {
|
|
12
16
|
await writeCaptureResult(response, input.outputPath);
|
|
13
17
|
}
|
|
@@ -15,3 +19,18 @@ export async function runCaptureCommand(args, dependencies = {}) {
|
|
|
15
19
|
await writeCaptureResult(response, input.outputPath, dependencies.resultIo);
|
|
16
20
|
}
|
|
17
21
|
}
|
|
22
|
+
/** Capture the --html document, explaining the SDK's refusal of a secret key. Other failures propagate unchanged. */
|
|
23
|
+
async function captureHtml(client, html, captureOptions) {
|
|
24
|
+
try {
|
|
25
|
+
return await client.captureFromHtml(html, captureOptions);
|
|
26
|
+
}
|
|
27
|
+
catch (error) {
|
|
28
|
+
// The client has a secret key from the environment, so the SDK refuses to send HTML.
|
|
29
|
+
if (error instanceof ScreenshotScoutConfigurationError) {
|
|
30
|
+
throw new Error(`${error.message}\n${UNSET_SECRET_KEY_FOR_HTML}`, {
|
|
31
|
+
cause: error,
|
|
32
|
+
});
|
|
33
|
+
}
|
|
34
|
+
throw error;
|
|
35
|
+
}
|
|
36
|
+
}
|
package/dist/help.js
CHANGED
|
@@ -3,12 +3,13 @@ export const ROOT_HELP = `Screenshot Scout CLI
|
|
|
3
3
|
|
|
4
4
|
Usage:
|
|
5
5
|
screenshotscout capture <url> [capture options] [CLI controls]
|
|
6
|
+
screenshotscout capture --html <path|-> [capture options] [CLI controls]
|
|
6
7
|
screenshotscout capture-url <url> [capture options]
|
|
7
8
|
screenshotscout --help
|
|
8
9
|
screenshotscout --version
|
|
9
10
|
|
|
10
11
|
Commands:
|
|
11
|
-
capture Capture one URL.
|
|
12
|
+
capture Capture one URL or HTML document.
|
|
12
13
|
capture-url Build one capture URL locally.
|
|
13
14
|
|
|
14
15
|
Options:
|
|
@@ -23,8 +24,10 @@ const CAPTURE_OPTION_HELP = Object.values(CAPTURE_OPTION_DEFINITIONS)
|
|
|
23
24
|
export function captureCommandHelp() {
|
|
24
25
|
return `Usage:
|
|
25
26
|
screenshotscout capture <url> [capture options] [CLI controls]
|
|
27
|
+
screenshotscout capture --html <path|-> [capture options] [CLI controls]
|
|
26
28
|
|
|
27
29
|
CLI controls:
|
|
30
|
+
--html <path|-> Render HTML from a file or standard input instead of a URL.
|
|
28
31
|
--options <path|-> Read a snake_case JSON options object from a file or standard input.
|
|
29
32
|
--method <get|post> Select the request method (default post, or get when SCREENSHOTSCOUT_SECRET_KEY is set).
|
|
30
33
|
-o, --output <path|-> Write the response to a file or standard output.
|
package/dist/input.js
CHANGED
|
@@ -3,6 +3,7 @@ import { parseArgs } from "node:util";
|
|
|
3
3
|
import { CAPTURE_OPTION_DEFINITIONS, } from "./capture-options.js";
|
|
4
4
|
import { CliUsageError } from "./cli-usage-error.js";
|
|
5
5
|
const OPTIONS_INPUT_NAME = "options";
|
|
6
|
+
const HTML_INPUT_NAME = "html";
|
|
6
7
|
const METHOD_INPUT_NAME = "method";
|
|
7
8
|
const OUTPUT_INPUT_NAME = "output";
|
|
8
9
|
const OMIT_VALUE = Symbol("omit-value");
|
|
@@ -12,64 +13,89 @@ const DEFINITIONS_BY_API_NAME = new Map(DEFINITIONS.map((definition) => [definit
|
|
|
12
13
|
const CAPTURE_PARSE_OPTIONS = createParseOptions(false);
|
|
13
14
|
const CAPTURE_COMMAND_PARSE_OPTIONS = createParseOptions(true);
|
|
14
15
|
const DEFAULT_INPUT_READER = {
|
|
15
|
-
readFile: (path) => readFile(path
|
|
16
|
+
readFile: (path) => readFile(path),
|
|
16
17
|
readStdin: readStandardInput,
|
|
17
18
|
};
|
|
18
19
|
/** Parse capture flags and merge an optional snake_case JSON options object. */
|
|
19
20
|
export async function parseCaptureInput(args, inputReader = DEFAULT_INPUT_READER) {
|
|
20
|
-
const parsed =
|
|
21
|
+
const parsed = parseCliInput(args, false);
|
|
21
22
|
return {
|
|
22
|
-
captureOptions: parsed
|
|
23
|
+
captureOptions: await readCaptureOptions(parsed, inputReader),
|
|
23
24
|
positionals: parsed.positionals,
|
|
24
25
|
};
|
|
25
26
|
}
|
|
26
|
-
/** Parse the capture command's URL, capture options, and
|
|
27
|
+
/** Parse the capture command's URL or --html document, capture options, and CLI controls. */
|
|
27
28
|
export async function parseCaptureCommandInput(args, inputReader = DEFAULT_INPUT_READER) {
|
|
28
|
-
const parsed =
|
|
29
|
-
|
|
30
|
-
|
|
29
|
+
const parsed = parseCliInput(args, true);
|
|
30
|
+
const { htmlPath, method, optionsPath, outputPath, positionals } = parsed;
|
|
31
|
+
// Usage errors come before anything is read.
|
|
32
|
+
if (positionals.length !== (htmlPath === undefined ? 1 : 0)) {
|
|
33
|
+
throw new CliUsageError("Command 'capture' requires exactly one URL, or the --html option.");
|
|
31
34
|
}
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
35
|
+
if (htmlPath === "-" && optionsPath === "-") {
|
|
36
|
+
throw new CliUsageError("Options '--html' and '--options' can't both read from standard input.");
|
|
37
|
+
}
|
|
38
|
+
if (htmlPath !== undefined && method === "get") {
|
|
39
|
+
throw new CliUsageError("Option '--html' can't be used with '--method get': HTML is sent in a POST request.");
|
|
40
|
+
}
|
|
41
|
+
const controls = {
|
|
42
|
+
captureOptions: await readCaptureOptions(parsed, inputReader),
|
|
43
|
+
method,
|
|
44
|
+
outputPath,
|
|
37
45
|
};
|
|
46
|
+
if (htmlPath === undefined) {
|
|
47
|
+
return { ...controls, targetUrl: positionals[0] };
|
|
48
|
+
}
|
|
49
|
+
return { ...controls, html: await readHtml(htmlPath, inputReader) };
|
|
38
50
|
}
|
|
39
51
|
/** Parse the capture-url command's URL and capture options. */
|
|
40
52
|
export async function parseCaptureUrlCommandInput(args, inputReader = DEFAULT_INPUT_READER) {
|
|
41
|
-
const parsed =
|
|
53
|
+
const parsed = parseCliInput(args, false);
|
|
42
54
|
if (parsed.positionals.length !== 1) {
|
|
43
55
|
throw new CliUsageError("Command 'capture-url' requires exactly one URL.");
|
|
44
56
|
}
|
|
45
57
|
return {
|
|
46
|
-
captureOptions: parsed
|
|
58
|
+
captureOptions: await readCaptureOptions(parsed, inputReader),
|
|
47
59
|
targetUrl: parsed.positionals[0],
|
|
48
60
|
};
|
|
49
61
|
}
|
|
50
|
-
|
|
51
|
-
|
|
62
|
+
/** Read the --options object, if any, and let the capture flags override it. */
|
|
63
|
+
async function readCaptureOptions(parsedCliInput, inputReader) {
|
|
52
64
|
let fileOptions = {};
|
|
53
65
|
if (parsedCliInput.optionsPath !== undefined) {
|
|
54
|
-
const
|
|
55
|
-
|
|
56
|
-
: await inputReader.readFile(parsedCliInput.optionsPath);
|
|
57
|
-
fileOptions = parseOptionsObject(text);
|
|
66
|
+
const bytes = await readInput(parsedCliInput.optionsPath, inputReader);
|
|
67
|
+
fileOptions = parseOptionsObject(Buffer.from(bytes).toString("utf8"));
|
|
58
68
|
}
|
|
59
69
|
return {
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
...parsedCliInput.captureOptions,
|
|
63
|
-
},
|
|
64
|
-
...(parsedCliInput.method === undefined
|
|
65
|
-
? {}
|
|
66
|
-
: { method: parsedCliInput.method }),
|
|
67
|
-
...(parsedCliInput.outputPath === undefined
|
|
68
|
-
? {}
|
|
69
|
-
: { outputPath: parsedCliInput.outputPath }),
|
|
70
|
-
positionals: parsedCliInput.positionals,
|
|
70
|
+
...fileOptions,
|
|
71
|
+
...parsedCliInput.captureOptions,
|
|
71
72
|
};
|
|
72
73
|
}
|
|
74
|
+
/** Read and decode the --html document, which must contain more than whitespace. */
|
|
75
|
+
async function readHtml(path, inputReader) {
|
|
76
|
+
const html = decodeHtml(await readInput(path, inputReader));
|
|
77
|
+
if (html.trim() === "") {
|
|
78
|
+
throw new CliUsageError("Option '--html' received an empty document.");
|
|
79
|
+
}
|
|
80
|
+
return html;
|
|
81
|
+
}
|
|
82
|
+
function readInput(path, inputReader) {
|
|
83
|
+
return path === "-" ? inputReader.readStdin() : inputReader.readFile(path);
|
|
84
|
+
}
|
|
85
|
+
/**
|
|
86
|
+
* Decode UTF-16 by its byte-order mark (Windows PowerShell 5.1 writes UTF-16 by
|
|
87
|
+
* default), and anything else as UTF-8. The decoder drops the byte-order mark.
|
|
88
|
+
*/
|
|
89
|
+
function decodeHtml(bytes) {
|
|
90
|
+
let encoding = "utf-8";
|
|
91
|
+
if (bytes[0] === 0xff && bytes[1] === 0xfe) {
|
|
92
|
+
encoding = "utf-16le";
|
|
93
|
+
}
|
|
94
|
+
else if (bytes[0] === 0xfe && bytes[1] === 0xff) {
|
|
95
|
+
encoding = "utf-16be";
|
|
96
|
+
}
|
|
97
|
+
return new TextDecoder(encoding).decode(bytes);
|
|
98
|
+
}
|
|
73
99
|
function createParseOptions(includeCaptureControls) {
|
|
74
100
|
const options = {};
|
|
75
101
|
for (const definition of DEFINITIONS) {
|
|
@@ -79,6 +105,7 @@ function createParseOptions(includeCaptureControls) {
|
|
|
79
105
|
}
|
|
80
106
|
options[OPTIONS_INPUT_NAME] = { type: "string" };
|
|
81
107
|
if (includeCaptureControls) {
|
|
108
|
+
options[HTML_INPUT_NAME] = { type: "string" };
|
|
82
109
|
options[METHOD_INPUT_NAME] = { type: "string" };
|
|
83
110
|
options[OUTPUT_INPUT_NAME] = { type: "string", short: "o" };
|
|
84
111
|
}
|
|
@@ -97,6 +124,7 @@ function parseCliInput(args, includeCaptureControls) {
|
|
|
97
124
|
}
|
|
98
125
|
const captureOptions = {};
|
|
99
126
|
const occurrences = new Map();
|
|
127
|
+
let htmlPath;
|
|
100
128
|
let method;
|
|
101
129
|
let optionsPath;
|
|
102
130
|
let outputPath;
|
|
@@ -111,6 +139,12 @@ function parseCliInput(args, includeCaptureControls) {
|
|
|
111
139
|
optionsPath = requiredTokenValue(token);
|
|
112
140
|
continue;
|
|
113
141
|
}
|
|
142
|
+
if (token.name === HTML_INPUT_NAME) {
|
|
143
|
+
if (count > 1)
|
|
144
|
+
throw duplicateOption(token.rawName);
|
|
145
|
+
htmlPath = requiredTokenValue(token);
|
|
146
|
+
continue;
|
|
147
|
+
}
|
|
114
148
|
if (token.name === METHOD_INPUT_NAME) {
|
|
115
149
|
if (count > 1)
|
|
116
150
|
throw duplicateOption(token.rawName);
|
|
@@ -138,6 +172,7 @@ function parseCliInput(args, includeCaptureControls) {
|
|
|
138
172
|
};
|
|
139
173
|
return {
|
|
140
174
|
...result,
|
|
175
|
+
...(htmlPath === undefined ? {} : { htmlPath }),
|
|
141
176
|
...(method === undefined ? {} : { method }),
|
|
142
177
|
...(optionsPath === undefined ? {} : { optionsPath }),
|
|
143
178
|
...(outputPath === undefined ? {} : { outputPath }),
|
|
@@ -328,5 +363,5 @@ async function readStandardInput() {
|
|
|
328
363
|
throw new TypeError("Standard input produced a non-byte chunk.");
|
|
329
364
|
}
|
|
330
365
|
}
|
|
331
|
-
return Buffer.concat(chunks)
|
|
366
|
+
return Buffer.concat(chunks);
|
|
332
367
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@screenshotscout/cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.8.0",
|
|
4
4
|
"description": "Official command-line interface for the Screenshot Scout screenshot API.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -49,7 +49,7 @@
|
|
|
49
49
|
"node": ">=22"
|
|
50
50
|
},
|
|
51
51
|
"dependencies": {
|
|
52
|
-
"@screenshotscout/sdk": "0.
|
|
52
|
+
"@screenshotscout/sdk": "0.9.0"
|
|
53
53
|
},
|
|
54
54
|
"devDependencies": {
|
|
55
55
|
"@eslint/js": "10.0.1",
|