@screenshotscout/cli 0.6.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 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
- `--method` and `--output` (or `-o`) are `capture` controls and are not accepted by `capture-url`.
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.
@@ -178,9 +194,10 @@ The CLI writes response data unchanged, without adding labels or summaries.
178
194
  | ------------------- | ----------------------------------------------- | --------------------------------------- | ----------------------------------------------- |
179
195
  | Binary image or PDF | Saves `screenshot.<extension>` | Saves exact response bytes to the path | Writes exact response bytes to standard output |
180
196
  | Markdown | Writes the Markdown to standard output | Saves the Markdown to the path | Writes the Markdown to standard output |
197
+ | HTML | Writes the HTML to standard output | Saves the HTML to the path | Writes the HTML to standard output |
181
198
  | JSON | Writes the raw JSON response to standard output | Saves the raw JSON response to the path | Writes the raw JSON response to standard output |
182
199
 
183
- Binary, Markdown and JSON writes to standard output add no line break.
200
+ Binary, Markdown, HTML and JSON writes to standard output add no line break.
184
201
 
185
202
  For an automatically named binary response, the extension comes only from the actual response `Content-Type`: `.png`, `.jpg`, `.webp`, `.gif`, `.tiff`, or `.pdf`. A missing or unrecognized content type uses `.bin`; a requested format does not determine the automatic filename.
186
203
 
@@ -229,6 +246,9 @@ More inline-flag, options-file, POSIX shell, PowerShell, and CI examples are in
229
246
  - Run `screenshotscout --help` or `screenshotscout <command> --help` to check command syntax and current capture-option value shapes.
230
247
  - If the CLI reports that an access key is required, set `SCREENSHOTSCOUT_ACCESS_KEY` in the same process environment that runs the command.
231
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.
232
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.
233
253
  - If an options file is rejected, confirm that it is a JSON object using exact API `snake_case` names and JSON value types.
234
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 = await captureWithScreenshotScoutClient(client, input.targetUrl, input.captureOptions, input.method);
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, "utf8"),
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 = await parseCaptureInputInternal(args, inputReader, false);
21
+ const parsed = parseCliInput(args, false);
21
22
  return {
22
- captureOptions: parsed.captureOptions,
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 two CLI controls. */
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 = await parseCaptureInputInternal(args, inputReader, true);
29
- if (parsed.positionals.length !== 1) {
30
- throw new CliUsageError("Command 'capture' requires exactly one URL.");
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
- return {
33
- captureOptions: parsed.captureOptions,
34
- method: parsed.method,
35
- outputPath: parsed.outputPath,
36
- targetUrl: parsed.positionals[0],
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 = await parseCaptureInputInternal(args, inputReader, false);
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.captureOptions,
58
+ captureOptions: await readCaptureOptions(parsed, inputReader),
47
59
  targetUrl: parsed.positionals[0],
48
60
  };
49
61
  }
50
- async function parseCaptureInputInternal(args, inputReader, includeCaptureControls) {
51
- const parsedCliInput = parseCliInput(args, includeCaptureControls);
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 text = parsedCliInput.optionsPath === "-"
55
- ? await inputReader.readStdin()
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
- captureOptions: {
61
- ...fileOptions,
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).toString("utf8");
366
+ return Buffer.concat(chunks);
332
367
  }
package/dist/result.js CHANGED
@@ -8,11 +8,13 @@ const DEFAULT_CAPTURE_RESULT_IO = {
8
8
  /** Save or display one successful SDK capture response without transforming it. */
9
9
  export async function writeCaptureResult(response, outputPath, io = DEFAULT_CAPTURE_RESULT_IO) {
10
10
  const bytes = response.kind === "binary" ? response.bytes : response.rawResponse.body;
11
- // JSON and Markdown are text, so without an output path they go to standard output.
11
+ // JSON, Markdown and HTML are text, so without an output path they go to standard output.
12
+ const mediaType = mediaTypeOf(response.rawResponse.contentType);
12
13
  if (outputPath === "-" ||
13
14
  (outputPath === undefined &&
14
15
  (response.kind === "json" ||
15
- mediaTypeOf(response.rawResponse.contentType) === "text/markdown"))) {
16
+ mediaType === "text/markdown" ||
17
+ mediaType === "text/html"))) {
16
18
  await io.writeStandardOutput(bytes);
17
19
  return;
18
20
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@screenshotscout/cli",
3
- "version": "0.6.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.6.0"
52
+ "@screenshotscout/sdk": "0.9.0"
53
53
  },
54
54
  "devDependencies": {
55
55
  "@eslint/js": "10.0.1",