webext-schema 7.0.0 → 7.1.1

package/.github/workflows/node.js.yml

@@ -17,7 +17,7 @@ jobs:
   build:
     strategy:
       matrix:
-        node-version: [ 20.x, lts/*, latest ]
+        node-version: [ 22.x, lts/*, latest ]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
@@ -28,4 +28,4 @@ jobs:
           check-latest: true
       - run: npm ci
       - run: npm run lint
-      - run: npm run testall
+      - run: npm run test:all

package/.prettierignore

@@ -0,0 +1,8 @@
+**/.next
+**/.nx/cache
+**/.svelte-kit
+**/build
+**/coverage
+**/dist
+**/docs
+**/codemods/**/__testfixtures__

package/README.md

@@ -1,11 +1,19 @@
+# webext-schema
+
 [![build](https://github.com/asamuzaK/webext-schema/workflows/build/badge.svg)](https://github.com/asamuzaK/webext-schema/actions?query=workflow%3Abuild)
 [![CodeQL](https://github.com/asamuzaK/webext-schema/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/asamuzaK/webext-schema/actions/workflows/github-code-scanning/codeql)
 [![npm](https://img.shields.io/npm/v/webext-schema)](https://www.npmjs.com/package/webext-schema)
 
-# webext-schema
+[WebExtensions](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions "Browser Extensions - Mozilla | MDN") schemas and [MailExtensions](https://developer.thunderbird.net/add-ons/mailextensions "A Guide to Extensions - Thunderbird") schemas fetched from [hg.mozilla.org](https://hg.mozilla.org/).
+Stubbed browser API and a standalone browser utility script are also available.
+
+## Features
 
-[WebExtentions](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions "Browser Extensions - Mozilla | MDN") schemas and [MailExtensions](https://developer.thunderbird.net/add-ons/mailextensions "A Guide to Extensions - Thunderbird") schemas fetched from [hg.mozilla.org](https://hg.mozilla.org/).
-Stubbed browser API is also available.
+* **Up-to-date Schemas:** Directly fetched from Mozilla's repositories.
+* **Multi-Channel Support:** Choose between `beta`, `central`, and `mail` channels to match your target environment.
+* **Easy API Mocking:** Instantly generate a stubbed `browser` object powered by [Sinon.JS](https://sinonjs.org/) for robust unit testing of your extensions.
+* **Standalone Utility Included:** Comes with `browser.js`, a dependency-free, Promise-wrapped utility script ready to be dropped into your extension project for easier API handling.
+* **Modern ESM & TypeScript:** Native ES Modules support with bundled TypeScript definitions (`index.d.ts`).
 
 ## Install
 
@@ -13,7 +21,7 @@ Stubbed browser API is also available.
 npm i webext-schema
 ```
 
-## Usage
+## Usage (Schema & Mock)
 
 ```javascript
 import { Schema } from 'webext-schema';
@@ -23,7 +31,7 @@ const schema = new Schema();
 
 ### new Schema(<var>channel</var>, <var>sinonConfig</var>)
 
-* @param {string} [channel] - release channel. one of "beta", "central", "release", "esr", "mail".
+* @param {string} [channel] - release channel. one of "beta", "central", "mail".
 * @param {Object} [sinonConfig] - optional configuration for `sinon.createSandbox()`, see [Sinon.JS](https://sinonjs.org/) for details.
 
 Both arguments are optional.
@@ -37,7 +45,7 @@ const schema = new Schema("central", {
 
 ### schema.channel
 
-"central", "beta", "release", "esr" for WebExtensions, and "mail" for MailExtensions are available.
+"central", "beta" for WebExtensions, and "mail" for MailExtensions are available.
 Channel defaults to "beta".
 
 ```javascript
@@ -125,3 +133,26 @@ assert.isFunction(port2.onDisconnect.addListener);
 // reset
 browser._sandbox.reset();
 ```
+
+---
+
+## Browser Utility (`browser.js`)
+
+A standalone utility script (`browser.js`) is also included in this repository. It provides useful, Promise-wrapped functions for common browser extension APIs (e.g., `browser.tabs`, `browser.runtime`, `browser.storage`).
+
+This file is designed to be copied directly into your browser extension project. It has no external dependencies and works natively in your background or content scripts.
+
+### How to use `browser.js`
+
+1. Copy `browser.js` from the `webext-schema` repository into your extension's source directory.
+2. Import the needed functions into your extension scripts:
+
+```javascript
+import { createTab, getActiveTab, setStorage } from './path/to/browser.js';
+
+// Example: Create a new tab and save data
+async function openAndSave() {
+  const tab = await createTab({ url: '[https://example.com](https://example.com)' });
+  await setStorage({ lastOpenedTabId: tab.id }, 'local');
+}
+```

package/SECURITY.md

@@ -0,0 +1,30 @@
+# Security Policy
+
+We take security vulnerabilities seriously. Thank you for improving the security of our project.
+
+## Supported Versions
+
+We currently provide security updates **only for the latest major release**.
+
+## Reporting a Vulnerability
+
+Please **DO NOT** open a public issue for security-related vulnerabilities. 
+
+If you discover a security vulnerability, please report it privately via **GitHub's Private vulnerability reporting** feature.
+You can do this by navigating to the **Security** tab of this repository, selecting **Advisories**, and clicking the **Report a vulnerability** button.
+
+To help us resolve the issue efficiently, please include the following details in your report:
+
+* **Type of vulnerability** (e.g., XSS, SSRF, Prototype Pollution)
+* **Affected component or file name**
+* **Steps to reproduce** (including proof of concept / PoC code if available)
+* **Potential impact** of the vulnerability
+
+### Our Response Process
+
+1. **Acknowledgment**: We will acknowledge receipt of your report within 48 to 72 hours.
+2. **Investigation**: We will verify the vulnerability and evaluate its severity.
+3. **Fix & Release**: We will work on a fix in a private fork and release a patched version as soon as possible.
+4. **Advisory**: A GitHub Security Advisory will be published if necessary, giving you full credit for the discovery (unless you prefer to remain anonymous).
+
+Please adhere to Coordinated Vulnerability Disclosure (CVD) and **do not disclose the vulnerability publicly** until a patch has been released.

package/eslint.config.mjs

@@ -1,15 +1,20 @@
 import jsdoc from 'eslint-plugin-jsdoc';
+import prettierRecommended from 'eslint-plugin-prettier/recommended';
 import regexp from 'eslint-plugin-regexp';
 import unicorn from 'eslint-plugin-unicorn';
 import globals from 'globals';
-import neostandard, { plugins as neostdplugins } from 'neostandard';
+import neostandard from 'neostandard';
 
 export default [
   ...neostandard({
-    semi: true
+    noStyle: true
   }),
   jsdoc.configs['flat/recommended'],
   regexp.configs['flat/recommended'],
+  prettierRecommended,
+  {
+    ignores: ['test/file/']
+  },
   {
     languageOptions: {
       globals: {
@@ -22,29 +27,32 @@ export default [
       reportUnusedDisableDirectives: true
     },
     plugins: {
-      '@stylistic': neostdplugins['@stylistic'],
       regexp,
       unicorn
     },
+    settings: {
+      jsdoc: {
+        mode: 'typescript'
+      }
+    },
     rules: {
-      '@stylistic/space-before-function-paren': ['error', {
-        anonymous: 'always',
-        asyncArrow: 'always',
-        named: 'never'
-      }],
-      'import-x/order': ['error', {
-        alphabetize: {
-          order: 'ignore',
-          caseInsensitive: false
+      curly: ['error', 'all'],
+      'jsdoc/no-undefined-types': [
+        'error',
+        {
+          definedTypes: ['ReadonlyArray']
         }
-      }],
+      ],
       'no-await-in-loop': 'error',
-      'no-use-before-define': ['error', {
-        allowNamedExports: false,
-        classes: true,
-        functions: true,
-        variables: true
-      }],
+      'no-use-before-define': [
+        'error',
+        {
+          allowNamedExports: false,
+          classes: true,
+          functions: true,
+          variables: true
+        }
+      ],
       'prefer-object-has-own': 'error',
       'unicorn/prefer-node-protocol': 'error'
     }

package/index.js

@@ -9,11 +9,17 @@
 /* api */
 import process from 'node:process';
 import { parseCommand } from './modules/commander.js';
-import { logErr, throwErr } from './modules/common.js';
 export { Schema } from './modules/schema.js';
 
 /* process */
-process.on('uncaughtException', throwErr);
-process.on('unhandledRejection', logErr);
+process.on('uncaughtException', err => {
+  console.error('Fatal Error (Uncaught Exception):', err);
+  process.exit(1);
+});
+
+process.on('unhandledRejection', reason => {
+  console.error('Fatal Error (Unhandled Rejection):', reason);
+  process.exit(1);
+});
 
 parseCommand(process.argv);

package/modules/browser.js

@@ -2,12 +2,48 @@
  * browser.js
  */
 
-/* shared */
-import { getType, isObjectNotEmpty, isString, logErr } from './common.js';
-
 /* api */
 const { permissions, runtime, tabs, windows } = browser;
 
+/* constants & utils */
+const TYPE_FROM = 8;
+const TYPE_TO = -1;
+
+/**
+ * log error
+ * @param {!object} e - Error
+ * @returns {boolean} - false
+ */
+const logErr = e => {
+  console.error(e);
+  return false;
+};
+
+/**
+ * get type
+ * @param {object} o - object to check
+ * @returns {string} - type of object
+ */
+const getType = o =>
+  Object.prototype.toString.call(o).slice(TYPE_FROM, TYPE_TO);
+
+/**
+ * is object, and not an empty object
+ * @param {object} o - object to check;
+ * @returns {boolean} - result
+ */
+const isObjectNotEmpty = o => {
+  const items = /Object/i.test(getType(o)) && Object.keys(o);
+  return !!items?.length;
+};
+
+/**
+ * is string
+ * @param {object} o - object to check
+ * @returns {boolean} - result
+ */
+const isString = o => typeof o === 'string' || o instanceof String;
+
 /**
  * check if permission is granted
  * @param {object} perm - permissions.Permission
@@ -70,7 +106,9 @@ export const getCloseTabsByDoubleClickValue = async () => {
   });
   let userValue;
   if (isGranted) {
-    const { browserSettings: { closeTabsByDoubleClick } } = browser;
+    const {
+      browserSettings: { closeTabsByDoubleClick }
+    } = browser;
     userValue = await closeTabsByDoubleClick.get({});
   }
   return userValue ?? null;
@@ -86,7 +124,9 @@ export const setContextMenuOnMouseup = async () => {
   });
   let res;
   if (isGranted) {
-    const { browserSettings: { contextMenuShowEvent } } = browser;
+    const {
+      browserSettings: { contextMenuShowEvent }
+    } = browser;
     const { levelOfControl, value } = await contextMenuShowEvent.get({});
     if (value === 'mouseup') {
       res = true;
@@ -109,7 +149,9 @@ export const clearContextMenuOnMouseup = async () => {
   });
   let res;
   if (isGranted) {
-    const { browserSettings: { contextMenuShowEvent } } = browser;
+    const {
+      browserSettings: { contextMenuShowEvent }
+    } = browser;
     res = await contextMenuShowEvent.clear({});
   }
   return !!res;
@@ -125,7 +167,9 @@ export const getNewTabPositionValue = async () => {
   });
   let res;
   if (isGranted) {
-    const { browserSettings: { newTabPosition } } = browser;
+    const {
+      browserSettings: { newTabPosition }
+    } = browser;
     res = await newTabPosition.get({});
   }
   return res ?? null;
@@ -143,8 +187,9 @@ export const isCommandCustomizable = async () => {
   let bool;
   if (isGranted) {
     const { commands } = browser;
-    bool = typeof commands.update === 'function' &&
-           typeof commands.reset === 'function';
+    bool =
+      typeof commands.update === 'function' &&
+      typeof commands.reset === 'function';
   }
   return !!bool;
 };
@@ -165,11 +210,16 @@ export const updateCommand = async (id, value = '') => {
   let func;
   if (await isCommandCustomizable()) {
     const { commands } = browser;
-    const shortcut =
-      value.trim().replace(/\+([a-z])$/, (m, c) => `+${c.toUpperCase()}`);
+    const shortcut = value
+      .trim()
+      .replace(/\+([a-z])$/, (m, c) => `+${c.toUpperCase()}`);
     if (shortcut === '') {
       func = commands.reset(id);
-    } else if (/^(?:(?:Alt|Command|(?:Mac)?Ctrl)(?:\+Shift)?|Alt\+(?:Command|(?:Mac)?Ctrl)|Command\+(?:Alt|MacCtrl)|Ctrl\+(?:Alt|MacCtrl)|MacCtrl\+(?:Alt|Command|Ctrl))\+[\dA-Z]|F[1-9]|Media(?:(?:Next|Prev)Track|PlayPause|Stop)$/.test(shortcut)) {
+    } else if (
+      /^(?:(?:Alt|Command|(?:Mac)?Ctrl)(?:\+Shift)?|Alt\+(?:Command|(?:Mac)?Ctrl)|Command\+(?:Alt|MacCtrl)|Ctrl\+(?:Alt|MacCtrl)|MacCtrl\+(?:Alt|Command|Ctrl))\+[\dA-Z]|F[1-9]|Media(?:(?:Next|Prev)Track|PlayPause|Stop)$/.test(
+        shortcut
+      )
+    ) {
       func = commands.update({
         shortcut,
         name: id
@@ -1027,19 +1077,24 @@ export const warmupTab = async tabId => {
 export const captureVisibleTab = async (windowId, opt) => {
   const info = await runtime.getBrowserInfo();
   let isGranted;
-  if (info.vender === 'Mozilla') {
+  if (info.vendor === 'Mozilla') {
     const browserVersion = parseFloat(info.version);
-    isGranted = (browserVersion >= 126 && await isPermissionGranted({
-      permissions: ['activeTab']
-    })) || await isPermissionGranted({
-      origins: ['<all_urls>']
-    });
+    isGranted =
+      (browserVersion >= 126 &&
+        (await isPermissionGranted({
+          permissions: ['activeTab']
+        }))) ||
+      (await isPermissionGranted({
+        origins: ['<all_urls>']
+      }));
   } else {
-    isGranted = await isPermissionGranted({
-      permissions: ['activeTab']
-    }) || await isPermissionGranted({
-      origins: ['<all_urls>']
-    });
+    isGranted =
+      (await isPermissionGranted({
+        permissions: ['activeTab']
+      })) ||
+      (await isPermissionGranted({
+        origins: ['<all_urls>']
+      }));
   }
   let url;
   if (isGranted) {
@@ -1089,8 +1144,9 @@ export const getCurrentTheme = async windowId => {
   let currentTheme;
   if (isGranted) {
     const { theme } = browser;
-    currentTheme =
-      await theme.getCurrent(Number.isInteger(windowId) ? windowId : null);
+    currentTheme = await theme.getCurrent(
+      Number.isInteger(windowId) ? windowId : null
+    );
   }
   return currentTheme ?? null;
 };

package/modules/commander.js

@@ -38,13 +38,18 @@ export const parseCommand = args => {
     commander.exitOverride();
     commander.version(process.env.npm_package_version, '-v, --version');
     if (args.includes('clean') || args.includes('c')) {
-      commander.command('clean').alias('c')
+      commander
+        .command('clean')
+        .alias('c')
         .description('clean directory')
         .option('-d, --dir <name>', 'specify directory')
         .option('-i, --info', 'console info')
         .action(cleanDirectory);
     } else if (args.includes('update') || args.includes('u')) {
-      commander.command('update').alias('u').description('update schemas')
+      commander
+        .command('update')
+        .alias('u')
+        .description('update schemas')
         .option('-c, --channel <name>', 'specify the release channel')
         .option('-i, --info', 'console info')
         .action(updateSchemas);
@@ -54,6 +59,4 @@ export const parseCommand = args => {
 };
 
 /* For test */
-export {
-  commander
-};
+export { commander };

package/modules/common.js

@@ -60,7 +60,7 @@ export const getType = o =>
  */
 export const isObjectNotEmpty = o => {
   const items = /Object/i.test(getType(o)) && Object.keys(o);
-  return !!(items?.length);
+  return !!items?.length;
 };
 
 /**

package/modules/file-util.js

@@ -94,8 +94,9 @@ export const isExecutable = (file, mask = MASK_BIT) => {
   let res;
   const stat = getStat(file);
   if (stat) {
-    res = !!(stat.mode & mask) ||
-          (IS_WIN && /\.(?:bat|cmd|exe|ps1|wsh)$/i.test(file));
+    res =
+      !!(stat.mode & mask) ||
+      (IS_WIN && /\.(?:bat|cmd|exe|ps1|wsh)$/i.test(file));
   }
   return !!res;
 };
@@ -118,8 +119,11 @@ export const getFileTimestamp = file => {
  */
 export const getFileNameFromFilePath = (file, subst = SUBST) => {
   let name;
-  if (isString(file) && isFile(file) &&
-      /^[^.]+(?:\..+)?$/.test(path.basename(file))) {
+  if (
+    isString(file) &&
+    isFile(file) &&
+    /^[^.]+(?:\..+)?$/.test(path.basename(file))
+  ) {
     [, name] = /^([^.]+)(?:\..+)?$/.exec(path.basename(file));
   }
   return name || subst;
@@ -179,7 +183,7 @@ export const createDirectory = async (dir, mode = PERM_DIR) => {
     mode,
     recursive: true
   };
-  !isDir(dirPath) && await fsPromise.mkdir(dirPath, opt);
+  !isDir(dirPath) && (await fsPromise.mkdir(dirPath, opt));
   return dirPath;
 };
 
@@ -193,14 +197,23 @@ export const createDirectory = async (dir, mode = PERM_DIR) => {
  * @param {number|string} [opt.mode] - file permission
  * @returns {Promise.<string>} - file path
  */
-export const createFile = async (file, value, opt = {
-  encoding: null, flag: 'w', mode: PERM_FILE
-}) => {
+export const createFile = async (
+  file,
+  value,
+  opt = {
+    encoding: null,
+    flag: 'w',
+    mode: PERM_FILE
+  }
+) => {
   if (!isString(file)) {
     throw new TypeError(`Expected String but got ${getType(file)}.`);
   }
-  if (!isString(value) && !Buffer.isBuffer(value) &&
-      !(value instanceof Uint8Array)) {
+  if (
+    !isString(value) &&
+    !Buffer.isBuffer(value) &&
+    !(value instanceof Uint8Array)
+  ) {
     throw new TypeError(
       `Expected String, Buffer, Uint8Array but got ${getType(value)}.`
     );

package/modules/schema.js

@@ -28,9 +28,7 @@ export class Schema {
   constructor(...args) {
     const [arg1, arg2] = args;
     this.#channel =
-      isString(arg1) && /^(?:central|mail)$/.test(arg1)
-        ? arg1
-        : 'beta';
+      isString(arg1) && /^(?:central|mail)$/.test(arg1) ? arg1 : 'beta';
     this._sandbox =
       (isObjectNotEmpty(arg1) && sinon.createSandbox(arg1)) ||
       (isObjectNotEmpty(arg2) && sinon.createSandbox(arg2)) ||
@@ -209,12 +207,18 @@ export class Schema {
           target[key] = item.value;
         } else if (type === 'function') {
           target[key] = this._sandbox.stub();
-        } else if (type === 'object' || $ref ||
-                   Object.hasOwn(item, 'properties')) {
+        } else if (
+          type === 'object' ||
+          $ref ||
+          Object.hasOwn(item, 'properties')
+        ) {
           target[key] ??= {};
-          properties && this._mockProperties(
-            target[key], properties, `${namespace}.${key}`
-          );
+          properties &&
+            this._mockProperties(
+              target[key],
+              properties,
+              `${namespace}.${key}`
+            );
         } else {
           target[key] = null;
         }
@@ -339,14 +343,17 @@ export class Schema {
     for (const [key, value] of schemaItems) {
       const items = Object.values(value);
       for (const item of items) {
-        const {
-          $import, events, functions, namespace, properties, types
-        } = item;
+        const { $import, events, functions, namespace, properties, types } =
+          item;
         const fileKey = camelize(key.replace(/\.json$/, '')).toLowerCase();
         const itemKey = namespace.replace(/\./g, '').toLowerCase();
-        if (fileKey === itemKey || fileKey.startsWith(itemKey) ||
-            itemKey.startsWith(fileKey) || aliasKeys.includes(itemKey) ||
-            $import) {
+        if (
+          fileKey === itemKey ||
+          fileKey.startsWith(itemKey) ||
+          itemKey.startsWith(fileKey) ||
+          aliasKeys.includes(itemKey) ||
+          $import
+        ) {
           const mapKey = [];
           let ns;
           if (namespace.includes('.')) {

package/modules/update.js

@@ -50,7 +50,7 @@ export const getChannelUrl = channel => {
     default:
       dir = 'releases/mozilla-beta/';
   }
-  return `https://hg.mozilla.org/${dir}raw-file/tip/`;
+  return `https://hg-edge.mozilla.org/${dir}raw-file/tip/`;
 };
 
 /**
@@ -70,7 +70,8 @@ export const getSchemaData = async (file, baseUrl) => {
   const text = await fetchText(href);
   const schema = JSON5.parse(text);
   return {
-    file, schema
+    file,
+    schema
   };
 };
 
@@ -158,10 +159,7 @@ export const getMailExtSchemaData = async (baseUrl, info) => {
   }
   const items = await getFileList(baseUrl);
   const schemaUrl = `${baseUrl}schemas/`;
-  const excludeFile = [
-    'commands.json',
-    'pkcs11.json'
-  ];
+  const excludeFile = ['commands.json', 'pkcs11.json'];
   const schemas = [];
   for (const item of items) {
     if (!excludeFile.includes(item)) {
@@ -185,26 +183,33 @@ export const createUnifiedSchema = async (channel, info) => {
   const channelUrl = getChannelUrl(channel);
   const schema = {};
   if (channel === 'mail') {
-    const browserItems = [
-      'commands.json',
-      'pkcs11.json'
-    ];
-    const browserUrl =
-      `${getChannelUrl('central')}browser/components/extensions/schemas/`;
-    const browserSchemas =
-      await getListedSchemaData(browserUrl, browserItems, info);
+    const browserItems = ['commands.json', 'pkcs11.json'];
+    const browserUrl = `${getChannelUrl('central')}browser/components/extensions/schemas/`;
+    const browserSchemas = await getListedSchemaData(
+      browserUrl,
+      browserItems,
+      info
+    );
     for (const item of browserSchemas) {
       const { file, schema: itemSchema } = item;
       schema[file] = itemSchema;
     }
     const toolkitItems = [
-      'content_scripts.json', 'experiments.json', 'extension.json', 'i18n.json',
-      'management.json', 'permissions.json', 'runtime.json', 'theme.json'
+      'content_scripts.json',
+      'experiments.json',
+      'extension.json',
+      'i18n.json',
+      'management.json',
+      'permissions.json',
+      'runtime.json',
+      'theme.json'
     ];
-    const toolkitUrl =
-      `${getChannelUrl('central')}toolkit/components/extensions/schemas/`;
-    const toolkitSchemas =
-      await getListedSchemaData(toolkitUrl, toolkitItems, info);
+    const toolkitUrl = `${getChannelUrl('central')}toolkit/components/extensions/schemas/`;
+    const toolkitSchemas = await getListedSchemaData(
+      toolkitUrl,
+      toolkitItems,
+      info
+    );
     for (const item of toolkitSchemas) {
       const { file, schema: itemSchema } = item;
       schema[file] = itemSchema;
@@ -245,10 +250,16 @@ export const saveSchemaFile = async (channel, info) => {
   const schema = await createUnifiedSchema(channel, info);
   const content = `${JSON.stringify(schema, null, INDENT)}\n`;
   const fileName = channel === 'mail' ? 'mailext' : 'webext';
-  const filePath =
-    path.resolve(DIR_CWD, 'schemas', channel, `${fileName}.json`);
+  const filePath = path.resolve(
+    DIR_CWD,
+    'schemas',
+    channel,
+    `${fileName}.json`
+  );
   const file = await createFile(filePath, content, {
-    encoding: CHAR, flag: 'w', mode: PERM_FILE
+    encoding: CHAR,
+    flag: 'w',
+    mode: PERM_FILE
   });
   if (file && info) {
     console.info(`Created: ${file}`);