@arraypress/extension-kit 1.4.0 → 1.6.0

package/src/testing/live.js

@@ -0,0 +1,151 @@
+/**
+ * What a live checker (a run over real sites, never in CI) shares: its
+ * command line (which sites, how many at once, a proxy, how the browser
+ * looks) and where its traffic leaves for the internet, which decides what
+ * many sites show (cookie banners, prices, currency).
+ *
+ * @module testing/live
+ */
+
+/** @import { APIRequestContext } from 'playwright' */
+
+/**
+ * A proxy, as Playwright takes it.
+ *
+ * @typedef {object} Proxy
+ * @property {string} server e.g. "http://uk.example.net:8080" or "socks5://127.0.0.1:1080".
+ * @property {string} [username] From the address, if it has one.
+ * @property {string} [password] From the address, if it has one.
+ */
+
+/**
+ * A live checker's options.
+ *
+ * @typedef {object} LiveOptions
+ * @property {string[]} only Only sites whose address or name contains one of these (any case).
+ * @property {string[]} categories Only these categories (by id).
+ * @property {number} concurrency Sites checked at once.
+ * @property {Proxy | null} proxy The proxy every request goes through.
+ * @property {string} proxyLabel The proxy's address without its password, for the output.
+ * @property {string} locale The browser's language (navigator.language, Accept-Language).
+ * @property {string} timezone The browser's time zone.
+ * @property {string} out Where the report goes ('' for the checker's default).
+ * @property {boolean} help Show the usage and stop.
+ */
+
+/**
+ * Read a proxy address.
+ *
+ * @param {string} address - e.g. "http://user:pass@host:3128".
+ * @returns {{ proxy: Proxy, label: string }} For Playwright, and for the output (no password).
+ * @throws {Error} When it isn't an address.
+ * @example
+ * parseProxy('http://me:secret@uk.example:8080').label; // 'http://me:•••@uk.example:8080'
+ */
+export function parseProxy(address) {
+  const url = new URL(address.includes('://') ? address : `http://${address}`);
+  if (!url.hostname) throw new Error(`Not a proxy address: ${address}`);
+  const server = `${url.protocol}//${url.host}`;
+  const username = decodeURIComponent(url.username);
+  const password = decodeURIComponent(url.password);
+  return {
+    proxy: { server, ...(username && { username }), ...(password && { password }) },
+    label: `${url.protocol}//${username ? `${username}${password ? ':•••' : ''}@` : ''}${url.host}`,
+  };
+}
+
+/**
+ * Read a live checker's command line: `--only <word>` (repeatable, or bare
+ * words), `--category <id>` (repeatable), `--concurrency <n>`, `--proxy <url>`
+ * (default `HTTPS_PROXY`), `--locale <tag>`, `--timezone <zone>`, `--out <dir>`,
+ * `--help`. A value may follow an `=` ("--only=amazon"); commas list several.
+ *
+ * @param {readonly string[]} argv - The arguments after the script.
+ * @param {Readonly<Record<string, string | undefined>>} env - The environment (HTTPS_PROXY, https_proxy).
+ * @param {{ usage: string, concurrency?: number, maxConcurrency?: number, locale?: string, timezone?: string }} defaults - The
+ *   usage text (shown with an unknown option), and the defaults: 3 at once (at most 8), en-GB, Europe/London.
+ * @returns {LiveOptions} The options.
+ * @throws {Error} On an unknown option or a bad value.
+ * @example
+ * parseLiveOptions(['--category', 'shops', 'amazon'], {}, { usage }).only; // ['amazon']
+ */
+export function parseLiveOptions(argv, env, { usage, concurrency = 3, maxConcurrency = 8, locale = 'en-GB', timezone = 'Europe/London' }) {
+  /** @type {LiveOptions} */
+  const options = { only: [], categories: [], concurrency, proxy: null, proxyLabel: '', locale, timezone, out: '', help: false };
+  let proxy = env.HTTPS_PROXY || env.https_proxy || '';
+  for (let at = 0; at < argv.length; at += 1) {
+    const arg = argv[at];
+    const equals = arg.startsWith('--') ? arg.indexOf('=') : -1;
+    const flag = equals > 0 ? arg.slice(0, equals) : arg;
+    const inline = equals > 0 ? arg.slice(equals + 1) : undefined;
+    const value = () => {
+      const next = inline ?? argv[++at];
+      if (next === undefined || next === '') throw new Error(`${flag} needs a value`);
+      return next;
+    };
+    switch (flag) {
+      case '--only': options.only.push(...value().split(',')); break;
+      case '--category': options.categories.push(...value().split(',')); break;
+      case '--concurrency': {
+        const count = Number(value());
+        if (!Number.isInteger(count) || count < 1 || count > maxConcurrency) throw new Error(`--concurrency must be 1 to ${maxConcurrency}`);
+        options.concurrency = count;
+        break;
+      }
+      case '--proxy': proxy = value(); break;
+      case '--locale': options.locale = value(); break;
+      case '--timezone': options.timezone = value(); break;
+      case '--out': options.out = value(); break;
+      case '--help': case '-h': options.help = true; break;
+      default:
+        if (flag.startsWith('-')) throw new Error(`Unknown option ${flag}\n\n${usage}`);
+        options.only.push(flag);
+    }
+  }
+  if (proxy) ({ proxy: options.proxy, label: options.proxyLabel } = parseProxy(proxy));
+  return options;
+}
+
+/**
+ * The exit point.
+ *
+ * @typedef {object} Exit
+ * @property {string} ip The public address.
+ * @property {string} country Its ISO country code ("GB", "TH").
+ * @property {string} where Readable: city and organisation, where the service says.
+ * @property {string} source The service that answered.
+ */
+
+/**
+ * Lookup services that need no key, tried in order, each with how to read its answer.
+ *
+ * @type {readonly { url: string, read: (data: Record<string, unknown>) => { ip: unknown, country: unknown, where: unknown[] } }[]}
+ */
+const SERVICES = [
+  { url: 'https://ipinfo.io/json', read: (data) => ({ ip: data.ip, country: data.country, where: [data.city, data.org] }) },
+  { url: 'https://api.country.is/', read: (data) => ({ ip: data.ip, country: data.country, where: [] }) },
+  { url: 'https://ipapi.co/json/', read: (data) => ({ ip: data.ip, country: data.country_code, where: [data.city, data.org] }) },
+];
+
+/**
+ * Where the browser's traffic leaves for the internet: its public IP's
+ * country, asked once through the same proxy the browser uses. Sites go by
+ * that address, not the browser's language or time zone.
+ *
+ * @param {APIRequestContext} request - A browser context's `request` (it uses the context's proxy).
+ * @returns {Promise<Exit | null>} null when no service answered.
+ */
+export async function exitPoint(request) {
+  for (const { url, read } of SERVICES) {
+    try {
+      const response = await request.get(url, { timeout: 10000, headers: { accept: 'application/json' } });
+      if (!response.ok()) continue;
+      const { ip, country, where } = read(await response.json());
+      if (typeof country !== 'string' || !country) continue;
+      return { ip: String(ip ?? ''), country: country.toUpperCase(), where: where.filter((part) => typeof part === 'string' && part).join(', '), source: new URL(url).host };
+    } catch {
+      // The next service.
+    }
+  }
+  return null;
+}

package/src/testing/server.d.ts

@@ -1,7 +1,8 @@
 /**
  * A local web server for end-to-end test pages: a site for the content
  * script to run on, answering each path from a table (or a function), on
- * 127.0.0.1 so a test build's host permission can cover it.
+ * 127.0.0.1 so a test build's host permission can cover it; over HTTPS too,
+ * with a throwaway certificate.
  *
  * @module testing/server
  */
@@ -31,17 +32,36 @@ export type TestServer = {
      */
     close: () => Promise<void>;
 };
+/**
+ * A self-signed certificate for 127.0.0.1 and localhost, made by `openssl`, valid for a day: for
+ * {@link serve}'s `tls`, with Chromium started with `--ignore-certificate-errors` (a site whose
+ * name Chrome only reaches over HTTPS, as every HSTS-preloaded one, mapped to the test server with
+ * `--host-resolver-rules`).
+ *
+ * @returns {{key: string, cert: string}} The key and certificate, PEM.
+ * @example
+ * const site = await serve(routes, { tls: testCertificate() });
+ */
+export declare function testCertificate(): {
+    key: string;
+    cert: string;
+};
 /**
  * Serve `routes` on 127.0.0.1.
  *
  * @param {Routes} routes - Path → page, or a function of the path.
- * @param {{port?: number}} [options] - `port`: a fixed port (default: any free one).
+ * @param {{port?: number, tls?: {key: string, cert: string}}} [options] - `port`: a fixed port (default: any
+ *   free one); `tls`: serve HTTPS with this key and certificate ({@link testCertificate}).
  * @returns {Promise<TestServer>} The listening server.
  * @example
  * const site = await serve({'/': '<!doctype html><textarea></textarea>'});
  * await page.goto(`${site.origin}/`);
  * await site.close();
  */
-export declare function serve(routes: Routes, { port }?: {
+export declare function serve(routes: Routes, { port, tls }?: {
     port?: number;
+    tls?: {
+        key: string;
+        cert: string;
+    };
 }): Promise<TestServer>;

package/src/testing/server.js

@@ -1,12 +1,18 @@
 /**
  * A local web server for end-to-end test pages: a site for the content
  * script to run on, answering each path from a table (or a function), on
- * 127.0.0.1 so a test build's host permission can cover it.
+ * 127.0.0.1 so a test build's host permission can cover it; over HTTPS too,
+ * with a throwaway certificate.
  *
  * @module testing/server
  */
 
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { createServer } from 'node:http';
+import { createServer as createSecureServer } from 'node:https';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
 
 /** @import { IncomingMessage, Server } from 'node:http' */
 
@@ -52,19 +58,42 @@ async function replyFor(routes, pathname, request) {
   return Object.hasOwn(table, pathname) ? table[pathname] : undefined;
 }
 
+/**
+ * A self-signed certificate for 127.0.0.1 and localhost, made by `openssl`, valid for a day: for
+ * {@link serve}'s `tls`, with Chromium started with `--ignore-certificate-errors` (a site whose
+ * name Chrome only reaches over HTTPS, as every HSTS-preloaded one, mapped to the test server with
+ * `--host-resolver-rules`).
+ *
+ * @returns {{key: string, cert: string}} The key and certificate, PEM.
+ * @example
+ * const site = await serve(routes, { tls: testCertificate() });
+ */
+export function testCertificate() {
+  const dir = mkdtempSync(path.join(tmpdir(), 'kit-tls-'));
+  try {
+    execFileSync('openssl', ['req', '-x509', '-newkey', 'rsa:2048', '-nodes', '-days', '1', '-subj', '/CN=localhost',
+      '-keyout', path.join(dir, 'key.pem'), '-out', path.join(dir, 'cert.pem')], { stdio: 'ignore' });
+    return { key: readFileSync(path.join(dir, 'key.pem'), 'utf8'), cert: readFileSync(path.join(dir, 'cert.pem'), 'utf8') };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
 /**
  * Serve `routes` on 127.0.0.1.
  *
  * @param {Routes} routes - Path → page, or a function of the path.
- * @param {{port?: number}} [options] - `port`: a fixed port (default: any free one).
+ * @param {{port?: number, tls?: {key: string, cert: string}}} [options] - `port`: a fixed port (default: any
+ *   free one); `tls`: serve HTTPS with this key and certificate ({@link testCertificate}).
  * @returns {Promise<TestServer>} The listening server.
  * @example
  * const site = await serve({'/': '<!doctype html><textarea></textarea>'});
  * await page.goto(`${site.origin}/`);
  * await site.close();
  */
-export async function serve(routes, { port = 0 } = {}) {
-  const server = createServer(async (request, response) => {
+export async function serve(routes, { port = 0, tls } = {}) {
+  /** @type {import('node:http').RequestListener} */
+  const handle = async (request, response) => {
     const { pathname } = new URL(request.url ?? '/', 'http://127.0.0.1');
     const reply = await replyFor(routes, pathname, request);
     if (reply === undefined) {
@@ -75,13 +104,14 @@ export async function serve(routes, { port = 0 } = {}) {
     const { body, type = HTML, status = 200, headers = {} } = typeof reply === 'string' || reply instanceof Uint8Array ? { body: reply } : reply;
     response.writeHead(status, { 'Content-Type': type, ...headers });
     response.end(body);
-  });
+  };
+  const server = tls ? createSecureServer(tls, handle) : createServer(handle);
   await new Promise((resolve) => server.listen(port, '127.0.0.1', () => resolve(undefined)));
   const address = /** @type {import('node:net').AddressInfo} */ (server.address());
   return {
     server,
     port: address.port,
-    origin: `http://127.0.0.1:${address.port}`,
+    origin: `${tls ? 'https' : 'http'}://127.0.0.1:${address.port}`,
     close() {
       server.closeAllConnections();
       return new Promise((resolve) => server.close(() => resolve()));

package/src/{testing → time}/pool.d.ts

@@ -1,8 +1,9 @@
 /**
- * Working through a list a few at a time: a live check of many sites, each
- * in one of a few browsers.
+ * Working through a list a few at a time: files fetched by an extension page,
+ * or a live check of many sites, each in one of a few browsers. Runs
+ * anywhere (worker, page, Node).
  *
- * @module testing/pool
+ * @module time/pool
  */
 /**
  * Run `work` on every item, at most `limit` at once, each slot taking the

package/src/{testing → time}/pool.js

@@ -1,8 +1,9 @@
 /**
- * Working through a list a few at a time: a live check of many sites, each
- * in one of a few browsers.
+ * Working through a list a few at a time: files fetched by an extension page,
+ * or a live check of many sites, each in one of a few browsers. Runs
+ * anywhere (worker, page, Node).
  *
- * @module testing/pool
+ * @module time/pool
  */
 
 /**

package/src/ui/text-dialog.d.ts

@@ -1,43 +1,55 @@
 /**
- * Chrome's one-field dialog (cr-dialog with a cr-input), as chrome://bookmarks
- * asks for a folder's name: a title, a labelled field, Cancel and an action
- * button. The action button stays disabled while the text is blank or isn't
- * valid, with the reason under the field. Enter means the action button, Esc
- * and Cancel cancel, and the focus goes back to what opened it. The page
- * needs no markup: the dialog (`#text-dialog`) is made the first time.
+ * Chrome's text dialog (cr-dialog with cr-inputs): a title, labelled fields,
+ * Cancel and an action button. One field, as chrome://bookmarks asks for a
+ * folder's name (`askText`); several, as chrome://settings/searchEngines asks
+ * for a site search (`askFields`). The action button stays disabled while a
+ * field is blank or isn't valid, with the reason under that field. Enter
+ * means the action button, Esc and Cancel cancel, and the focus goes back to
+ * what opened it. The page needs no markup: the dialog (`#text-dialog`) is
+ * made the first time, its fields each time it's asked.
  *
  * @module ui/text-dialog
  */
-export type TextRequest = {
+export type FieldRequest = {
     /**
-     * The dialog's title ("Rename folder").
+     * Its key in the answer ("folder"), and part of its id.
      */
-    title: string;
+    name: string;
     /**
-     * The field's label ("Name").
+     * Its label ("Folder").
      */
     label: string;
     /**
-     * The text to start with (selected). Default ''.
+     * The text to start with. Default ''.
      */
     value?: string;
     /**
-     * The action button's text. Default "Save".
-     */
-    action?: string;
-    /**
-     * The cancel button's text. Default "Cancel".
+     * Shown while it's empty. Default none.
      */
-    cancel?: string;
+    placeholder?: string;
     /**
      * Why the (non-blank) text can't be used,
      * shown under the field; null when it can. Default: anything but blank.
      */
     validate?: (text: string) => string | null;
     /**
-     * The field's `maxlength`. Default none.
+     * Its `maxlength`. Default none.
      */
     maxLength?: number;
+};
+export type DialogRequest = {
+    /**
+     * The dialog's title ("Rename folder").
+     */
+    title: string;
+    /**
+     * The action button's text. Default "Save".
+     */
+    action?: string;
+    /**
+     * The cancel button's text. Default "Cancel".
+     */
+    cancel?: string;
     /**
      * Where the focus
      * goes when it closes, or a function that says (asked then, so it can pick a row drawn since).
@@ -49,23 +61,44 @@ export type TextRequest = {
      */
     doc?: Document;
 };
+export type TextRequest = DialogRequest & Omit<FieldRequest, 'name'>;
+export type FieldsRequest = DialogRequest & {
+    fields: FieldRequest[];
+};
 /**
- * What the dialog asks.
+ * One field of the dialog.
  *
- * @typedef {object} TextRequest
+ * @typedef {object} FieldRequest
+ * @property {string} name Its key in the answer ("folder"), and part of its id.
+ * @property {string} label Its label ("Folder").
+ * @property {string} [value] The text to start with. Default ''.
+ * @property {string} [placeholder] Shown while it's empty. Default none.
+ * @property {(text: string) => string | null} [validate] Why the (non-blank) text can't be used,
+ *   shown under the field; null when it can. Default: anything but blank.
+ * @property {number} [maxLength] Its `maxlength`. Default none.
+ */
+/**
+ * What the dialog asks, whatever its fields.
+ *
+ * @typedef {object} DialogRequest
  * @property {string} title The dialog's title ("Rename folder").
- * @property {string} label The field's label ("Name").
- * @property {string} [value] The text to start with (selected). Default ''.
  * @property {string} [action] The action button's text. Default "Save".
  * @property {string} [cancel] The cancel button's text. Default "Cancel".
- * @property {(text: string) => string | null} [validate] Why the (non-blank) text can't be used,
- *   shown under the field; null when it can. Default: anything but blank.
- * @property {number} [maxLength] The field's `maxlength`. Default none.
  * @property {HTMLElement | (() => HTMLElement | null | undefined) | null} [returnTo] Where the focus
  *   goes when it closes, or a function that says (asked then, so it can pick a row drawn since).
  *   Default what had the focus when it opened.
  * @property {Document} [doc] The page. Default `document`.
  */
+/**
+ * What the one-field dialog asks.
+ *
+ * @typedef {DialogRequest & Omit<FieldRequest, 'name'>} TextRequest
+ */
+/**
+ * What the dialog with several fields asks.
+ *
+ * @typedef {DialogRequest & {fields: FieldRequest[]}} FieldsRequest
+ */
 /**
  * Whether a text can be used, and the reason to show when it can't. Pure.
  *
@@ -81,6 +114,20 @@ export declare function checkText(text: string, validate?: (text: string) => str
     ok: boolean;
     reason: string;
 };
+/**
+ * A field's element ids. A one-field dialog's are `text-dialog-input` and `text-dialog-error`;
+ * with several, each is named: `text-dialog-<name>` and `text-dialog-<name>-error`. Pure.
+ *
+ * @param {string} name - The field's name.
+ * @param {boolean} only - Whether it's the dialog's only field.
+ * @returns {{input: string, error: string}} The ids.
+ * @example
+ * fieldIds('folder', false); // → {input: 'text-dialog-folder', error: 'text-dialog-folder-error'}
+ */
+export declare function fieldIds(name: string, only: boolean): {
+    input: string;
+    error: string;
+};
 export type Parts = {
     /**
      * The `<dialog>`.
@@ -95,17 +142,9 @@ export type Parts = {
      */
     title: HTMLElement;
     /**
-     * The field's label.
-     */
-    label: HTMLLabelElement;
-    /**
-     * The field.
-     */
-    input: HTMLInputElement;
-    /**
-     * The reason under the field.
+     * Where the fields go.
      */
-    error: HTMLElement;
+    body: HTMLElement;
     /**
      * The cancel button.
      */
@@ -115,8 +154,39 @@ export type Parts = {
      */
     confirm: HTMLButtonElement;
 };
+export type Field = {
+    /**
+     * What was asked.
+     */
+    request: FieldRequest;
+    /**
+     * Its input.
+     */
+    input: HTMLInputElement;
+    /**
+     * The reason under it.
+     */
+    error: HTMLElement;
+};
+/**
+ * Ask for several pieces of text in the page's dialog, one field each.
+ *
+ * @param {FieldsRequest} request - What to ask.
+ * @returns {Promise<Record<string, string> | null>} Each field's text by its name, trimmed; null
+ *   when cancelled.
+ * @example
+ * const rule = await askFields({
+ *   title: 'Add folder rule', action: 'Add',
+ *   fields: [
+ *     {name: 'from', label: 'Downloads from', placeholder: 'example.com or .pdf', validate: checkFrom},
+ *     {name: 'folder', label: 'Folder', placeholder: 'Receipts'},
+ *   ],
+ * });
+ * if (rule) addRule(rule.from, rule.folder);
+ */
+export declare function askFields({ title, fields: requests, action, cancel, returnTo, doc, }: FieldsRequest): Promise<Record<string, string> | null>;
 /**
- * Ask for a piece of text in the page's one-field dialog.
+ * Ask for a piece of text in the page's dialog, with one field.
  *
  * @param {TextRequest} request - What to ask.
  * @returns {Promise<string | null>} The text, trimmed; null when cancelled.
@@ -129,4 +199,4 @@ export type Parts = {
  *   validate: (text) => (siteFromInput(text) ? null : 'Enter a site, like example.com'),
  * });
  */
-export declare function askText({ title, label, value, action, cancel, validate, maxLength, returnTo, doc, }: TextRequest): Promise<string | null>;
+export declare function askText({ label, value, placeholder, validate, maxLength, ...dialog }: TextRequest): Promise<string | null>;