recursal/MDN huggingface dataset:
declarativeNetRequest.updateDynamicRules
========================================

Modifies the set of dynamic rules for the extension. The rules with IDs listed in `options.removeRuleIds` are first removed, and then the rules given in `options.addRules` are added. Note that:

* This update happens as an atomic operation: either all specified rules are added and removed, or an error is returned.
* These rules are persisted across browser sessions and across extension updates.
* Static rules specified as part of the extension package can not be removed using this function.
* `declarativeNetRequest.MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES` is the maximum number of dynamic and session rules an extension can add.
Syntax
------


```js
let updatedRules = browser.declarativeNetRequest.updateDynamicRules(
    options                // object
);
```

### Parameters

`options`

An object containing details of the rules to add or delete from the dynamic rules.

`addRules` Optional

An array of `declarativeNetRequest.Rule`. Details of the rules to add.

`removeRuleIds` Optional

An array of `number`. IDs of the rules to remove. Any invalid IDs are ignored.


### Return value

A `Promise` If the request was successful, the promise is fulfilled with no arguments. If the request fails, the promise is rejected with an error message.

Examples
--------

### Example extensions

* dnr-dynamic-with-options
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
declarativeNetRequest.URLTransform
==================================

Details describing a URL transformation to perform for a redirect rule. This object can be specified at `rule.action`.redirect.transform.

Type
----

Values of this type are objects. They contain these properties:

`fragment` Optional

A `string`. The new fragment for the request. Should be either empty, in which case the existing fragment is cleared; or should begin with '#'.

`host` Optional

A `string`. The new host name for the request.

`password` Optional

A `string`. The new password for the request.

`path` Optional

A `string`. The new path for the request. If empty, the existing path is cleared.

`port` Optional

A `string`. The new port for the request. If empty, the existing port is cleared.

`query` Optional

A `string`. The new query for the request. Should be either empty, in which case the existing query is cleared; or should begin with '?'.

`queryTransform` Optional

An object describing how to add, remove, or replace query key-value pairs. Cannot be specified if 'query' is specified.

`addOrReplaceParams` Optional

An array of objects describing the list of query key-value pairs to be added or replaced.

`key`

A `string`. The key value.

`replaceOnly` Optional

A `boolean`. If true, the query key is replaced only if it's already present. Otherwise, the key is also added if it's missing. Defaults to false.

`value`

A `string`. The value value.


`removeParams` Optional

An array of `string`. The list of query keys to be removed.


`scheme` Optional

A `string`. The new scheme for the request. Allowed values are `"http"`, `"https"`, and the scheme of the extension, for example, "moz-extension" in Firefox or "chrome-extension" in Chrome. When the extension scheme is used, the `host` must be specified to generate a meaningful redirection target.

`username` Optional

A `string`. The new username for the request.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
declarativeNetRequest.RuleAction
================================

Details of the action to take if a rule is matched, as the `action` property of a `declarativeNetRequest.Rule`.

Type
----

Values of this type are objects. They contain these properties:

`redirect` Optional

`declarativeNetRequest.Redirect`. Describes how the redirect should be performed. Only valid for redirect rules.

`requestHeaders` Optional

`declarativeNetRequest.ModifyHeaderInfo`. The request headers to modify for the request. Only valid if `type` is `"modifyHeaders"`.

`responseHeaders` Optional

`declarativeNetRequest.ModifyHeaderInfo`. The response headers to modify for the request. Only valid if `type` is `"modifyHeaders"`.

`type`

A `string`. The type of action to perform. Possible values are `"block"`, `"redirect"`, `"allow"`, `"upgradeScheme"`, `"modifyHeaders"`, and `"allowAllRequests"`. The use of the `"redirect"` and `"modifyHeaders"` actions require host permissions for the request and request initiator. The "block" and "upgradeScheme" actions also require host permissions unless the "declarativeNetRequest" permission is specified. Without these permissions, matching rules are ignored. See Permissions at declarativeNetRequest for more information. More details about the effects of rule actions are provided in Matching precedents.

Example extensions
------------------

* dnr-block-only
* dnr-redirect-url
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
declarativeNetRequest.GETMATCHEDRULES\_QUOTA\_INTERVAL
======================================================

The time interval within which `declarativeNetRequest.MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL` `declarativeNetRequest.getMatchedRules` calls can be made, specified in minutes. Additional calls fail immediately and result in a promise rejection. Calls associated with a user gesture are exempt from the quota.

Its value is `10`.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
declarativeNetRequest.MAX\_GETMATCHEDRULES\_CALLS\_PER\_INTERVAL
================================================================

The number of times `declarativeNetRequest.getMatchedRules` can be called within a period of `declarativeNetRequest.GETMATCHEDRULES_QUOTA_INTERVAL`.

Its value is `20`.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
declarativeNetRequest.updateSessionRules
========================================

Modifies the set of scoped rules for the extension. The rules with IDs listed in `options.removeRuleIds` are first removed, and then the rules given in `options.addRules` are added. Note that:

* This update happens as an atomic operation: either all specified rules are added and removed, or an error is returned.
* These rules are not persisted across browser sessions.
* `MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES` is the maximum number of dynamic and session rules an extension can add.
Syntax
------


```js
let updatedRuleset = browser.declarativeNetRequest.updateSessionRules(
    options                // object
);
```

### Parameters

`options`

An object containing details of the rules to add or delete from the dynamic rules.

`addRules` Optional

An array of `declarativeNetRequest.Rule`. Details of the rules to add.

`removeRuleIds` Optional

An array of `number`. IDs of the rules to remove. Any invalid IDs are ignored.


### Return value

A `Promise` If the request was successful, the promise is fulfilled with no arguments. If the request fails, the promise is rejected with an error message.

Examples
--------

### Example extensions

* dnr-dynamic-with-options
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
declarativeNetRequest.ModifyHeaderInfo
======================================

The request or response header to modify for a request, declared in the `rule.action.requestHeaders` array or `rule.action.responseHeaders` array for rules whose `rule.action``.type` is "modifyHeaders".

Each object describes one header modification. To modify multiple headers, multiple objects can be specified in these arrays, or across multiple rules.

 Matching `modifyHeaders` rules are applied in the order described at Matching precedents.
 Within each extension, all `modifyHeaders` rules with a priority lower than or equal to matching `allow` or `allowAllRequests` rules are ignored.

If multiple `modifyHeaders` rules specify the same header, the resulting modification for the header is determined based on the priority of each rule and the operations specified:

* If a rule has been appended to a header, then lower-priority rules can only append to that header. `set` and `remove` operations are not permitted.
* If a rule has set a header, lower priority rules cannot modify the header except for `append` rules from the same extension.
* If a rule has removed a header, lower priority rules cannot modify the header.
Type
----

Values of this type are objects. They contain these properties:

`header`

A `string`. The name of the header to be modified.

`operation`

A `string`. The operation to be performed on a header. Possible values are `"append"`, `"set"`, and `"remove"`.

`value` Optional

A `string`. The new value for the header. Must be specified for append and set operations. Not allowed for the "remove" operation.

Header limits
-------------

In Chrome, `"append"` is supported for the following request headers:

* `Accept`
* `Accept-Encoding`
* `Accept-Language`
* `Access-Control-Request-Headers`
* `Cache-Control`
* `Connection`
* `Content-Language`
* `Cookie`
* `Forwarded`
* `If-Match`
* `If-None-Match`
* `Keep-Alive`
* `Range`
* `Te`
* `Trailer`
* `Transfer-Encoding`
* `Upgrade`
* `Via`
* `Want-Digest`
* `X-Forwarded-For`

In Firefox, the extension needs host permissions for the new value of the `Host` header.

Browser compatibility
---------------------

### webextensions.api.declarativeNetRequest.RuleAction.requestHeaders

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### webextensions.api.declarativeNetRequest.RuleAction.responseHeaders

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
management.getAll()
===================

Retrieves an array of `ExtensionInfo` objects, one for each installed add-on.

Note that Google Chrome retrieves apps as well as add-ons. In Chrome you can distinguish apps from add-ons using the `type` property of `ExtensionInfo`.

This API requires the "management" API permission.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let gettingAll = browser.management.getAll()
```

### Parameters

None.

### Return value

A `Promise` that will be fulfilled with an array of `ExtensionInfo` objects, one for each installed add-on.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Log the name of all installed add-ons:


```js
function gotAll(infoArray) {
  for (const info of infoArray) {
    if (info.type === "extension") {
      console.log(info.name);
    }
  }
}

let gettingAll = browser.management.getAll();
gettingAll.then(gotAll);
```

### Example extensions

* theme-switcher

**Note:** This API is based on Chromium's `chrome.management` API. This documentation is derived from `management.json` in the Chromium code.
management.get()
================

Retrieves an `ExtensionInfo` object containing information about the specified add-on.

This API requires the "management" API permission.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let gettingInfo = browser.management.get(
  id                  // string
)
```

### Parameters

`id`

`string`. ID of the add-on whose info you want to retrieve.

### Return value

A `Promise` that will be fulfilled with an `ExtensionInfo` object, containing information about the add-on. The promise will be rejected if no extension with the given ID is installed or the extension is not allowed to be accessed by the caller.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Log the name of the add-on whose ID is "my-add-on":


```js
let id = "my-add-on";

function got(info) {
  console.log(info.name);
}

let getting = browser.management.get(id);
getting.then(got);
```


**Note:** This API is based on Chromium's `chrome.management` API. This documentation is derived from `management.json` in the Chromium code.
management.onEnabled()
======================

The event listener called when the `enabled` event is fired, indicating that an add-on is now enabled.

This API requires the "management" API permission.

Syntax
------


```js
browser.management.onEnabled.addListener(listener)
browser.management.onEnabled.removeListener(listener)
browser.management.onEnabled.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Checks whether a `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs. The function is passed this argument:

`info`

`ExtensionInfo`: info about the add-on that was enabled.


Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Log the names of add-ons when they are enabled:


```js
browser.management.onEnabled.addListener((info) => {
  console.log(`${info.name} was enabled`);
});
```


**Note:** This API is based on Chromium's `chrome.management` API. This documentation is derived from `management.json` in the Chromium code.
management.onDisabled()
=======================

Fired when an add-on is disabled.

This API requires the "management" API permission.

Syntax
------


```js
browser.management.onDisabled.addListener(listener)
browser.management.onDisabled.removeListener(listener)
browser.management.onDisabled.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Checks whether a `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs. The function is passed this argument:

`info`

`ExtensionInfo`: info about the add-on that was disabled.


Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Log the names of add-ons when they are disabled:


```js
browser.management.onDisabled.addListener((info) => {
  console.log(`${info.name} was disabled`);
});
```


**Note:** This API is based on Chromium's `chrome.management` API. This documentation is derived from `management.json` in the Chromium code.
management.setEnabled()
=======================

Enables or disables the given add-on.

This function must usually be called in the context of a user action, such as the click handler for a button. The browser may also ask the user to confirm the change.

This API requires the "management" API permission.

It is an asynchronous function that returns a `Promise`.

The function allows enabling/disabling of theme addons, but will return an error if used to enable or disable other types of web extension.

Syntax
------


```js
let settingEnabled = browser.management.setEnabled(
  id,              // string
  enabled         // boolean
)
```

### Parameters

`id`

`string`. ID of the add-on to enable/disable.

`enabled`

`boolean`. Whether to enable or disable the add-on.

### Return value

A `Promise` that will be fulfilled with no arguments when the add-on has been disabled or enabled.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Toggle enable/disable for the add-on whose ID is "my-add-on":


```js
let id = "my-add-on";

function toggleEnabled(id) {
  let getting = browser.management.get(id);
  getting.then((info) => {
    browser.management.setEnabled(id, !info.enabled);
  });
}

toggleEnabled(id);
```

### Example extensions

* theme-switcher

**Note:** This API is based on Chromium's `chrome.management` API. This documentation is derived from `management.json` in the Chromium code.
management.onUninstalled()
==========================

Fired when an add-on is uninstalled.

This API requires the "management" API permission.

Syntax
------


```js
browser.management.onUninstalled.addListener(listener)
browser.management.onUninstalled.removeListener(listener)
browser.management.onUninstalled.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Checks whether a `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs. The function is passed this argument:

`info`

`ExtensionInfo`: info about the add-on that was uninstalled.


Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Log the names of add-ons when they are uninstalled:


```js
browser.management.onUninstalled.addListener((info) => {
  console.log(`${info.name} was uninstalled`);
});
```


**Note:** This API is based on Chromium's `chrome.management` API. This documentation is derived from `management.json` in the Chromium code.
management.getPermissionWarningsById()
======================================

When the user installs or upgrades an add-on, the browser may warn the user about any particularly powerful permissions that the add-on has requested. Not all permissions result in warnings, and this behavior is not standardized across browsers.

Given the ID of an add-on, this function returns the permission warnings for it as an array of strings.

This API requires the "management" API permission.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let gettingWarnings = browser.management.getPermissionWarningsById(
  id                  // string
)
```

### Parameters

`id`

`string`. ID of the add-on whose permission warnings you want to retrieve.

### Return value

A `Promise` that will be fulfilled with an array of strings, each of which contains the text of a permission warning.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Log the permission warnings for the add-on whose ID is "my-add-on":


```js
let id = "my-add-on";

function gotWarnings(warnings) {
  for (const warning of warnings) {
    console.log(warning);
  }
}

browser.management.getPermissionWarningsById(id).then(gotWarnings);
```


**Note:** This API is based on Chromium's `chrome.management` API. This documentation is derived from `management.json` in the Chromium code.
management.install()
====================

Installs and enables a theme extension from the given URL.

This API requires the "management" API permission and will only work with signed themes.

This is an asynchronous function that returns a Promise.

Syntax
------


```js
browser.management.install(options)
```

### Parameters

options

An object that includes the URL of the XPI file of the theme at addons.mozilla.org and an optional a hash of the XPI file, using sha256 or stronger.

### Return value

A Promise that will be fulfilled with an object, containing the `ExtensionID` defined for the theme in manifest.json.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Cycle through a list of themes:


```js
"use strict";

const themes = [
  "https://addons.mozilla.org/firefox/downloads/file/1063216/insightscare-1.0-fx.xpi",
  "https://addons.mozilla.org/firefox/downloads/file/1063419/orange\_roses-1.0-fx.xpi",
  "https://addons.mozilla.org/firefox/downloads/file/1062647/sticktoyourguns-2.0-fx.xpi",
  "https://addons.mozilla.org/firefox/downloads/file/0/bad\_url.xpi",
];

let current;

async function install(url) {
  try {
    current = url;
    const { id } = await browser.management.install({ url });
    console.log(`Theme installed: ${id}`);
  } catch (e) {
    console.error(`Installation failed: ${e}`);
  }
}

browser.browserAction.onClicked.addListener(() => {
  const id = themes.indexOf(current);
  install(themes[(id + 1) % themes.length]);
});

for (const url of themes) {
  browser.menus.create({
    title: url,
    onclick: () => install(url),
    contexts: ["browser\_action"],
  });
}
```
management.uninstall()
======================

Uninstalls an add-on, given its ID.

This API requires the "management" API permission.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let uninstalling = browser.management.uninstall(
  id,                  // string
  options              // object
)
```

### Parameters

`id`

`string`. ID of the add-on to uninstall.

`options` Optional

`object`. Object which may contain a single property, `showConfirmDialog`. If `showConfirmDialog` is `true`, the browser will show a dialog asking the user to confirm that the add-on should be uninstalled.

* If `id` is the calling add-on's ID, `showConfirmDialog` defaults to `false`.
* If `id` is a the ID of a different add-on, the `showConfirmDialog` option is ignored and the confirmation dialog is always shown.
### Return value

A `Promise` that will be rejected with an error message if the user canceled uninstall.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Uninstall the add-on whose ID is "my-addon-id", asking the user to confirm. In the callback, check whether the user canceled uninstallation.

Note that we haven't passed a fulfillment handler because if uninstallation succeeds, the add-on is no longer around to handle it.


```js
let id = "my-addon-id";

function onCanceled(error) {
  console.log(`Uninstall canceled: ${error}`);
}

let uninstalling = browser.management.uninstall(id);
uninstalling.then(null, onCanceled);
```


**Note:** This API is based on Chromium's `chrome.management` API. This documentation is derived from `management.json` in the Chromium code.
management.getSelf()
====================

Retrieves an `ExtensionInfo` object containing information about the calling add-on.

This API *does not* require the "management" API permission.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let gettingSelf = browser.management.getSelf()
```

### Parameters

None.

### Return value

A `Promise` that will be fulfilled with an `ExtensionInfo` object, containing information about the add-on.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Log the add-on's name:


```js
function gotSelf(info) {
  console.log(`Add-on name: ${info.name}`);
}

const gettingSelf = browser.management.getSelf();
gettingSelf.then(gotSelf);
```


**Note:** This API is based on Chromium's `chrome.management` API. This documentation is derived from `management.json` in the Chromium code.