@arraypress/extension-kit 1.5.0 → 1.7.0

package/src/testing/fake-model.js

@@ -0,0 +1,142 @@
+/**
+ * A stand-in for Chrome's `LanguageModel` (the Prompt API), with its shape,
+ * for an extension's unit tests and its e2e build (whose hook puts it on the
+ * worker's or page's `globalThis`: Playwright's Chromium has no model). It
+ * acts out what a real Chrome does: a model still to download (with
+ * progress), one this computer can't run, a slow first session (the cold
+ * start), a slow answer, an answer cut short by its signal, and a failure.
+ * Moved here from Better Downloads' tests, so every extension that uses the
+ * model tests against the same one.
+ *
+ * Plain browser JavaScript with no Node imports, so a test build can copy it in.
+ *
+ * @module testing/fake-model
+ */
+
+/** @import { LanguageModelOptions, LanguageModelSession, LanguageModelStatic, PromptOptions } from '../ai/model.js' */
+
+/**
+ * How the fake behaves; change it at any time with `set`.
+ *
+ * @typedef {object} FakeModelState
+ * @property {'available' | 'downloadable' | 'downloading' | 'unavailable'} availability What `availability()` says.
+ * @property {number} createMs How long making a session takes (a cold start is ~18 s on a real Chrome).
+ * @property {number} answerMs How long an answer takes.
+ * @property {(prompt: string, options: PromptOptions) => string} answer The answer to a prompt.
+ * @property {boolean} failPrompt Whether answers fail (the model gave up).
+ * @property {boolean} failDownload Whether a download fails part way.
+ */
+
+/**
+ * What the fake was asked, for tests to look at.
+ *
+ * @typedef {object} FakeModelLog
+ * @property {LanguageModelOptions[]} availability Each `availability()`'s options.
+ * @property {LanguageModelOptions[]} created Each `create()`'s options.
+ * @property {string[]} prompts Each prompt.
+ * @property {PromptOptions[]} promptOptions Each prompt's options (signal, responseConstraint).
+ * @property {number} cloned Sessions cloned.
+ * @property {number} aborted Prompts and creates stopped by their signal.
+ * @property {number} destroyed Sessions let go.
+ */
+
+/**
+ * A fake Prompt API with its state, its log, and `set` to change the state.
+ *
+ * @typedef {LanguageModelStatic & {state: FakeModelState, log: FakeModelLog, set: (patch: Partial<FakeModelState>) => void}} FakeLanguageModel
+ */
+
+/**
+ * Wait, unless the signal stops it first.
+ *
+ * @param {number} ms - How long.
+ * @param {AbortSignal | undefined} signal - Stops it.
+ * @returns {Promise<void>} Resolves after `ms`; rejects with an AbortError when stopped.
+ */
+function wait(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(new DOMException('Aborted', 'AbortError'));
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener('abort', () => {
+      clearTimeout(timer);
+      reject(new DOMException('Aborted', 'AbortError'));
+    }, { once: true });
+  });
+}
+
+/**
+ * A fake Prompt API.
+ *
+ * @param {Partial<FakeModelState>} [initial] - How it starts (default: ready, instant, answers “Fake answer”).
+ * @returns {FakeLanguageModel} The API, its state and log.
+ * @example
+ * const model = fakeLanguageModel({ createMs: 18_000 }); // a cold start
+ * const sessions = createModelSession({ model: () => model, options });
+ * (await sessions.ask('Hi', { timeoutMs: 2500 })).reason; // 'late'
+ */
+export function fakeLanguageModel(initial = {}) {
+  /** @type {FakeModelState} */
+  const state = {
+    availability: 'available', createMs: 0, answerMs: 0, answer: () => 'Fake answer', failPrompt: false, failDownload: false, ...initial,
+  };
+  /** @type {FakeModelLog} */
+  const log = { availability: [], created: [], prompts: [], promptOptions: [], cloned: 0, aborted: 0, destroyed: 0 };
+
+  /**
+   * A session.
+   *
+   * @returns {LanguageModelSession} It.
+   */
+  const session = () => ({
+    async prompt(prompt, options = {}) {
+      log.prompts.push(prompt);
+      log.promptOptions.push(options);
+      try {
+        await wait(state.answerMs, options.signal);
+      } catch (error) {
+        log.aborted++;
+        throw error;
+      }
+      if (state.failPrompt) throw new DOMException('The model failed', 'UnknownError');
+      return state.answer(prompt, options);
+    },
+    async clone() {
+      log.cloned++;
+      return session();
+    },
+    destroy() {
+      log.destroyed++;
+    },
+  });
+
+  return {
+    state,
+    log,
+    set: (patch) => Object.assign(state, patch),
+    async availability(options = {}) {
+      log.availability.push(options);
+      return state.availability;
+    },
+    async create(options = {}) {
+      log.created.push(options);
+      if (state.availability === 'unavailable') throw new DOMException('Not supported', 'NotSupportedError');
+      if (state.availability !== 'available') {
+        // A download, reported as Chrome reports it, then the model is here.
+        const monitor = new EventTarget();
+        options.monitor?.(monitor);
+        for (const loaded of [0, 0.5, 1]) {
+          if (state.failDownload && loaded === 1) throw new DOMException('Download failed', 'NetworkError');
+          monitor.dispatchEvent(Object.assign(new Event('downloadprogress'), { loaded }));
+        }
+        state.availability = 'available';
+      }
+      try {
+        await wait(state.createMs, options.signal);
+      } catch (error) {
+        log.aborted++;
+        throw error;
+      }
+      return session();
+    },
+  };
+}

package/src/testing/fake-storage.d.ts

@@ -49,6 +49,8 @@ export type FakeChromeStorage = {
      */
     settled: () => Promise<void>;
 };
+/** All of sync's items together may take this many bytes (`chrome.storage.sync.QUOTA_BYTES`). */
+export declare const SYNC_QUOTA_BYTES = 102400;
 /**
  * Make a fake `chrome.storage`.
  *

package/src/testing/fake-storage.js

@@ -49,6 +49,17 @@ export const SYNC_WRITES_PER_MINUTE = 120;
  */
 const viaJson = (value) => (value === undefined ? undefined : JSON.parse(JSON.stringify(value)));
 
+/** All of sync's items together may take this many bytes (`chrome.storage.sync.QUOTA_BYTES`). */
+export const SYNC_QUOTA_BYTES = 102_400;
+
+/**
+ * The bytes an area's items take, as Chrome counts sync's: each key plus its value's JSON, in UTF-8.
+ *
+ * @param {Record<string, unknown>} items - The items.
+ * @returns {number} Bytes.
+ */
+const totalBytes = (items) => Object.entries(items).reduce((sum, [key, value]) => sum + new TextEncoder().encode(key + JSON.stringify(value)).length, 0);
+
 /**
  * Make a fake `chrome.storage`.
  *
@@ -72,10 +83,10 @@ export function fakeChromeStorage({ local = {}, sync = {}, session = {}, now = D
   /**
    * @param {string} name
    * @param {Record<string, unknown>} initialData
-   * @param {{quotaPerItem?: number, writesPerMinute?: number}} [limits]
+   * @param {{quotaPerItem?: number, quotaBytes?: number, writesPerMinute?: number}} [limits]
    * @returns {FakeArea}
    */
-  function area(name, initialData, { quotaPerItem, writesPerMinute } = {}) {
+  function area(name, initialData, { quotaPerItem, quotaBytes, writesPerMinute } = {}) {
     /** @type {Record<string, any>} */
     const data = viaJson(initialData);
     /** @type {number[]} */
@@ -108,6 +119,7 @@ export function fakeChromeStorage({ local = {}, sync = {}, session = {}, now = D
             throw new Error('Resource::kQuotaBytesPerItem quota exceeded');
           }
         }
+        if (quotaBytes && totalBytes({ ...data, ...items }) > quotaBytes) throw new Error('Resource::kQuotaBytes quota exceeded');
         take();
         /** @type {Record<string, StorageChange>} */
         const changes = {};
@@ -135,7 +147,7 @@ export function fakeChromeStorage({ local = {}, sync = {}, session = {}, now = D
 
   return {
     local: area('local', local),
-    sync: area('sync', sync, { quotaPerItem: MAX_SYNC_ITEM_BYTES, writesPerMinute: SYNC_WRITES_PER_MINUTE }),
+    sync: area('sync', sync, { quotaPerItem: MAX_SYNC_ITEM_BYTES, quotaBytes: SYNC_QUOTA_BYTES, writesPerMinute: SYNC_WRITES_PER_MINUTE }),
     session: area('session', session),
     onChanged: { addListener: (listener) => listeners.push(listener) },
     async settled() {

package/src/testing/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * The kit's test helpers: a fake `chrome.storage`, Playwright helpers for
+ * The kit's test helpers: a fake `chrome.storage`, a fake on-device model, Playwright helpers for
  * end-to-end tests (time limits, a pool, a browser that passes for a
  * person's) and a server for their pages, Chrome's install warnings and
  * saved tab groups, and checks for a packaging test. Node only.
@@ -8,17 +8,26 @@
  */
 export { TEST_BUILDS_ENV, testBuildDir } from '../build/test-build.js';
 export { chromeUserAgent, closeOnSignal, realisticBrowser } from './browser.js';
-export { CHECK_MS, checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, until, } from './e2e.js';
-export { eachLimited } from './pool.js';
-export { serve } from './server.js';
-export { SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
+export { CHECK_MS, checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, runChecks, until, } from './e2e.js';
+export { exitPoint, parseLiveOptions, parseProxy } from './live.js';
+export { eachLimited } from '../time/pool.js';
+export { filesIn, launchDownloading } from './downloads.js';
+export { fakeLanguageModel } from './fake-model.js';
+export { messageLookup, readMessages } from './messages.js';
+export { serve, testCertificate } from './server.js';
+export { SYNC_QUOTA_BYTES, SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
 export { filesUnder, manifestReferences, missingReferences, referencedPath, zipEntries } from './package.js';
 export { savedTabGroups } from './saved-groups.js';
 export { installWarnings, warningsAddedBy, withoutPermissions } from './warnings.js';
 export type CheckRunner = import('./e2e.js').CheckRunner;
+export type FakeLanguageModel = import('./fake-model.js').FakeLanguageModel;
+export type FakeModelState = import('./fake-model.js').FakeModelState;
 export type ExtensionProfile = import('./e2e.js').ExtensionProfile;
 export type LaunchedExtension = import('./e2e.js').LaunchedExtension;
 export type LaunchOptions = import('./e2e.js').LaunchOptions;
+export type Messages = import('./messages.js').Messages;
+export type Exit = import('./live.js').Exit;
+export type LiveOptions = import('./live.js').LiveOptions;
 export type SavedTabGroup = import('./saved-groups.js').SavedTabGroup;
 export type Manifest = import('./warnings.js').Manifest;
 export type Reply = import('./server.js').Reply;
@@ -28,9 +37,14 @@ export type TestServer = import('./server.js').TestServer;
  * The helpers' types, for a test's JSDoc.
  *
  * @typedef {import('./e2e.js').CheckRunner} CheckRunner
+ * @typedef {import('./fake-model.js').FakeLanguageModel} FakeLanguageModel
+ * @typedef {import('./fake-model.js').FakeModelState} FakeModelState
  * @typedef {import('./e2e.js').ExtensionProfile} ExtensionProfile
  * @typedef {import('./e2e.js').LaunchedExtension} LaunchedExtension
  * @typedef {import('./e2e.js').LaunchOptions} LaunchOptions
+ * @typedef {import('./messages.js').Messages} Messages
+ * @typedef {import('./live.js').Exit} Exit
+ * @typedef {import('./live.js').LiveOptions} LiveOptions
  * @typedef {import('./saved-groups.js').SavedTabGroup} SavedTabGroup
  * @typedef {import('./warnings.js').Manifest} Manifest
  * @typedef {import('./server.js').Reply} Reply

package/src/testing/index.js

@@ -1,5 +1,5 @@
 /**
- * The kit's test helpers: a fake `chrome.storage`, Playwright helpers for
+ * The kit's test helpers: a fake `chrome.storage`, a fake on-device model, Playwright helpers for
  * end-to-end tests (time limits, a pool, a browser that passes for a
  * person's) and a server for their pages, Chrome's install warnings and
  * saved tab groups, and checks for a packaging test. Node only.
@@ -10,11 +10,15 @@
 export { TEST_BUILDS_ENV, testBuildDir } from '../build/test-build.js';
 export { chromeUserAgent, closeOnSignal, realisticBrowser } from './browser.js';
 export {
-  CHECK_MS, checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, until,
+  CHECK_MS, checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, runChecks, until,
 } from './e2e.js';
-export { eachLimited } from './pool.js';
-export { serve } from './server.js';
-export { SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
+export { exitPoint, parseLiveOptions, parseProxy } from './live.js';
+export { eachLimited } from '../time/pool.js';
+export { filesIn, launchDownloading } from './downloads.js';
+export { fakeLanguageModel } from './fake-model.js';
+export { messageLookup, readMessages } from './messages.js';
+export { serve, testCertificate } from './server.js';
+export { SYNC_QUOTA_BYTES, SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
 export { filesUnder, manifestReferences, missingReferences, referencedPath, zipEntries } from './package.js';
 export { savedTabGroups } from './saved-groups.js';
 export { installWarnings, warningsAddedBy, withoutPermissions } from './warnings.js';
@@ -23,9 +27,14 @@ export { installWarnings, warningsAddedBy, withoutPermissions } from './warnings
  * The helpers' types, for a test's JSDoc.
  *
  * @typedef {import('./e2e.js').CheckRunner} CheckRunner
+ * @typedef {import('./fake-model.js').FakeLanguageModel} FakeLanguageModel
+ * @typedef {import('./fake-model.js').FakeModelState} FakeModelState
  * @typedef {import('./e2e.js').ExtensionProfile} ExtensionProfile
  * @typedef {import('./e2e.js').LaunchedExtension} LaunchedExtension
  * @typedef {import('./e2e.js').LaunchOptions} LaunchOptions
+ * @typedef {import('./messages.js').Messages} Messages
+ * @typedef {import('./live.js').Exit} Exit
+ * @typedef {import('./live.js').LiveOptions} LiveOptions
  * @typedef {import('./saved-groups.js').SavedTabGroup} SavedTabGroup
  * @typedef {import('./warnings.js').Manifest} Manifest
  * @typedef {import('./server.js').Reply} Reply

package/src/testing/live.d.ts

@@ -0,0 +1,146 @@
+/**
+ * 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 type { APIRequestContext } from 'playwright';
+export type Proxy = {
+    /**
+     * e.g. "http://uk.example.net:8080" or "socks5://127.0.0.1:1080".
+     */
+    server: string;
+    /**
+     * From the address, if it has one.
+     */
+    username?: string;
+    /**
+     * From the address, if it has one.
+     */
+    password?: string;
+};
+export type LiveOptions = {
+    /**
+     * Only sites whose address or name contains one of these (any case).
+     */
+    only: string[];
+    /**
+     * Only these categories (by id).
+     */
+    categories: string[];
+    /**
+     * Sites checked at once.
+     */
+    concurrency: number;
+    /**
+     * The proxy every request goes through.
+     */
+    proxy: Proxy | null;
+    /**
+     * The proxy's address without its password, for the output.
+     */
+    proxyLabel: string;
+    /**
+     * The browser's language (navigator.language, Accept-Language).
+     */
+    locale: string;
+    /**
+     * The browser's time zone.
+     */
+    timezone: string;
+    /**
+     * Where the report goes ('' for the checker's default).
+     */
+    out: string;
+    /**
+     * Show the usage and stop.
+     */
+    help: boolean;
+};
+/** @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 declare function parseProxy(address: string): {
+    proxy: Proxy;
+    label: string;
+};
+/**
+ * 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 declare function parseLiveOptions(argv: readonly string[], env: Readonly<Record<string, string | undefined>>, { usage, concurrency, maxConcurrency, locale, timezone }: {
+    usage: string;
+    concurrency?: number;
+    maxConcurrency?: number;
+    locale?: string;
+    timezone?: string;
+}): LiveOptions;
+export type Exit = {
+    /**
+     * The public address.
+     */
+    ip: string;
+    /**
+     * Its ISO country code ("GB", "TH").
+     */
+    country: string;
+    /**
+     * Readable: city and organisation, where the service says.
+     */
+    where: string;
+    /**
+     * The service that answered.
+     */
+    source: string;
+};
+/**
+ * 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 declare function exitPoint(request: APIRequestContext): Promise<Exit | null>;

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/messages.d.ts

@@ -0,0 +1,33 @@
+export type Messages = Record<string, {
+    message: string;
+    description?: string;
+    placeholders?: Record<string, {
+        content: string;
+    }>;
+}>;
+/**
+ * One locale's messages.json.
+ *
+ * @typedef {Record<string, {message: string, description?: string, placeholders?: Record<string, {content: string}>}>} Messages
+ */
+/**
+ * Read a locale's messages.
+ *
+ * @param {string} extensionDir - The extension's folder (with `_locales/`).
+ * @param {string} locale - "en" or "en_GB".
+ * @returns {Messages} Its messages.
+ * @example
+ * readMessages('extension', 'en_GB').optionsColour.message;
+ */
+export declare function readMessages(extensionDir: string, locale: string): Messages;
+/**
+ * `chrome.i18n.getMessage` over a locale's real messages ('' for a missing key, as Chrome gives).
+ *
+ * @param {string} extensionDir - The extension's folder.
+ * @param {string} [locale] - Default "en"; another locale is read over en.
+ * @returns {(key: string, substitutions?: string | string[]) => string} The lookup.
+ * @example
+ * const t = messageLookup('extension');
+ * t('optionsMoreActions', ['example.com']); // 'More actions for example.com'
+ */
+export declare function messageLookup(extensionDir: string, locale?: string): (key: string, substitutions?: string | string[]) => string;