recursal/MDN huggingface dataset:
management.getPermissionWarningsByManifest()
============================================

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 text of a manifest.json file, this function returns the permission warnings that would be given for the resulting add-on, as an array of strings.

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

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

Syntax
------


```js
let gettingWarnings = browser.management.getPermissionWarningsByManifest(
  manifestString      // string
)
```

### Parameters

`manifestString`

`string`. String containing the manifest file. This must be a valid manifest: for example, it must contain all the mandatory manifest keys.

### 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 given manifest file:


```js
let manifest = {
  manifest\_version: 2,
  name: "test",
  version: "1.0",
  permissions: ["management", "<all\_urls>"],
};

let manifestString = JSON.stringify(manifest);

function gotWarnings(warnings) {
  console.log(warnings);
}

function gotError(error) {
  console.log(`Error: ${error}`);
}

let gettingWarnings =
  browser.management.getPermissionWarningsByManifest(manifestString);
gettingWarnings.then(gotWarnings, gotError);
```


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

An `ExtensionInfo` object contains information about an add-on.

Type
----

It is an object with the following properties:

`description`

`string`. The add-on's description, taken from the manifest.json description key.

`disabledReason`

`string`. If the add-on is disabled, the reason it was disabled. One of "unknown" or "permissions\_increase".

`enabled`

`boolean`. Whether or not the add-on is currently enabled.

`homepageUrl`

`string`. The add-on's homepage URL, taken from the manifest.json homepage\_url key.

`hostPermissions`

`array` of `string`. The add-on's host permissions.

`icons`

`array` of `object`. Information about the add-on's icons. An array of objects, one for each icon. Each object contains two properties:

* `size`: an integer representing the icon's width and height in pixels.
* `url`: a string containing a relative URL to the icon, starting at the add-on's root.

`id`

`string`. The add-on's ID.

`installType`

`string`. String describing how the add-on was installed. One of the following:

* "admin": the add-on was installed because of an administrative policy.
* "development": the add-on was installed unpacked from disk.
* "normal": the add-on was installed normally from an install package.
* "sideload": the add-on was installed by some other software on the user's computer.
* "other": the add-on was installed in some other way.

`mayDisable`

`boolean`. Whether this add-on can be disabled or uninstalled by the user.

`name`

`string`. The add-on's name, taken from the manifest.json name key.

`offlineEnabled`

`boolean`. Whether the add-on claims to support offline.

`optionsUrl`

`string`. URL for the item's options page, if it has one. This is a relative URL, starting at the add-on's root.

`permissions`

`array` of `string`. The add-on's API permissions.

`shortName`

`string`. A short version of the add-on's name, taken from the manifest.json short\_name key.

`type`

`string`. String describing the type of add-on. This is used to distinguish extensions from apps and themes. It may take any of the following values:

* "extension": most common type of add-on.
* "hosted\_app"
* "packaged\_app"
* "legacy\_packaged\_app"
* "theme"

`updateUrl`

`string`. URL for updates to this add-on, taken from the manifest.json browser\_specific\_settings key.

`version`

`string`. Version of this add-on, taken from the manifest.json version key.

`versionName`

`string`. Descriptive name for this add-on's version, taken from the manifest.json version\_name key.

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

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

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

Uninstalls 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 uninstallingSelf = browser.management.uninstallSelf(
  options              // object
)
```

### Parameters

`options` Optional

`object`. Object which may two properties, both optional:

`showConfirmDialog` Optional

Boolean. If `showConfirmDialog` is `true`, the browser will show a dialog asking the user to confirm that the add-on should be uninstalled. Defaults to `false`.

`dialogMessage` Optional

String. An extra message that will be displayed in the confirmation dialog.


### 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, 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
function onCanceled(error) {
  console.log(`Canceled: ${error}`);
}

let uninstalling = browser.management.uninstallSelf({
  showConfirmDialog: true,
});

uninstalling.then(null, onCanceled);
```


The same, but also adding a custom message to the dialog:


```js
function onCanceled(error) {
  console.log(`Canceled: ${error}`);
}

let uninstalling = browser.management.uninstallSelf({
  showConfirmDialog: true,
  dialogMessage: "Testing self-uninstall",
});

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.onInstalled()
========================

Fired when an add-on is installed.

This API requires the "management" API permission.

Syntax
------


```js
browser.management.onInstalled.addListener(listener)
browser.management.onInstalled.removeListener(listener)
browser.management.onInstalled.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 installed.


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 installed:


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


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

A `BrowserSetting` object that can be used to change the browser's proxy settings.

**Note:** Changing proxy settings requires private browsing window access because proxy settings affect private and non-private windows. Whether an extension can access private browsing windows is under user control. For details, see Extensions in Private Browsing. Your extension can check whether it can access private browsing windows using `extension.isAllowedIncognitoAccess`. If your extension does not have private window permission, calls to `proxy.settings.set()` throw an exception.

The underlying value is an object with the properties listed below.

When setting this object, all properties are optional. Note that any properties that are omitted will be reset to their default value.

`autoConfigUrl` Optional

`string`. A URL to use to configure the proxy.

`autoLogin` Optional

`boolean`. Do not prompt for authentication if the password is saved. Defaults to `false`.

`ftp` Optional 
Deprecated

`string`. The address of the FTP proxy. Can include a port.

`http` Optional

`string`. The address of the HTTP proxy. Can include a port.

`httpProxyAll` Optional

`boolean`. Use the HTTP proxy server for all protocols. Defaults to `false`.

`passthrough` Optional

`string`. A comma-separated list of hosts which should not be proxied. Defaults to "localhost, 127.0.0.1".

`proxyDNS` Optional

`boolean`. Proxy DNS when using SOCKS5. Defaults to `false`.

`proxyType` Optional

`string`. The type of proxy to use. This may take any one of the following values: "none", "autoDetect", "system", "manual", "autoConfig". Defaults to "system".

`socks` Optional

`string`. The address of the SOCKS proxy. Can include a port.

`socksVersion` Optional

`integer`. The version of the SOCKS proxy. May be 4 or 5. Defaults to 5.

`ssl` Optional

`string`. The address of the TLS/SSL proxy. Can include a port.

Examples
--------


```js
let proxySettings = {
  proxyType: "manual",
  http: "http://proxy.org:8080",
  socksVersion: 4,
  passthrough: ".example.org",
};

browser.proxy.settings.set({ value: proxySettings });
```

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

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

Fired when there is an error evaluating the PAC file or the `onRequest` listener.

The error can be triggered by throwing or returning an invalid value in the proxy.onRequest event handler.

Syntax
------


```js
browser.proxy.onError.addListener(listener)
browser.proxy.onError.removeListener(listener)
browser.proxy.onError.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)`

Check whether `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:

`newState`

`Object`. An Error object representing the error.


### Example extensions

* proxy-blocker
Browser compatibility
---------------------

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

Contains information about a proxy. This object, or an array of these objects, is returned from the listener to `proxy.onRequest`. It instructs the browser whether to proxy the request, and if so, which proxy to use.

Type
----

Values of this type are objects. They contain the following properties:

`type`

`string`. This describes whether to proxy at all, and if so, what kind of proxy to use. It may take one of the following values:

* `"direct"`: don't proxy the request. If this value is given, all other properties of this object are ignored. However, this setting doesn't override any proxy set by the user. Use `proxy.settings` to check whether a manual proxy is being used and, if necessary, monitor those settings for changes using `BrowserSetting.onChange`.
* `"http"`: HTTP proxy (or SSL CONNECT for HTTPS)
* `"https"`: HTTP proxying over TLS connection to proxy
* `"socks"`: SOCKS v5 proxy
* `"socks4"`: SOCKS v4 proxy

`host`

`string`. The hostname of the proxy server. Mandatory unless `type` is `"direct"`.

`port`

`number`. The port number of the proxy server. Mandatory unless `type` is `"direct"`.

`username`

`string`. Username for the proxy service. This is usable with "socks". For HTTP proxy authorizations, use `webRequest.onAuthRequired`.

`password`

`string`. Password for the proxy service. This is usable with "socks". For HTTP proxy authorizations, use `webRequest.onAuthRequired`.

`proxyDNS`

`boolean`. If true, the proxy server is used to resolve certain DNS queries (only usable with `"socks4"` and `"socks"`). Defaults to `false`.

`failoverTimeout`

`number`. Failover timeout in seconds. If the connection fails to connect the proxy server after this number of seconds, the next proxy server in the array returned from the `proxy.onRequest` listener will be used.

`proxyAuthorizationHeader`

`string`. This string, if set to non-empty, is passed directly as a value to the `Proxy-Authorization` request header sent to HTTPS proxies as part of HTTPS and CONNECT requests. In other words, this can be used to directly authenticate to HTTPS proxies that allow (non-challenging) authentication.

For instance, if you want to send "username" and "password" for "basic" authentication, you can set the `proxyAuthorizationHeader` property to `Basic dXNlcm5hbWU6cGFzc3dvcmQ=`

`connectionIsolationKey` Optional

`string`. An optional key used for additional isolation of this proxy connection. Applies to HTTPS proxies only.

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

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

Contains information about a web request. An instance of this object is passed into the `proxy.onRequest` listener.

Type
----

Values of this type are objects. They contain the following properties:

`cookieStoreId`

`string`. The cookie store ID of the current context. See Work with contextual identities for more information.

`documentUrl`

`string`. URL of the page into which the requested resource will be loaded.

`frameId`

`integer`. Zero if the request happens in the main frame; a positive value is the ID of a subframe in which the request happens. If the document of a (sub-)frame is loaded (`type` is `main_frame` or `sub_frame`), `frameId` indicates the ID of this frame, not the ID of the outer frame. Frame IDs are unique within a tab.

`fromCache`

`boolean`. Indicates if this response will be fetched from disk cache.

`incognito`

`boolean`. `true` for private browsing requests.

`method`

`string`. Standard HTTP method: for example, "GET" or "POST".

`originUrl`

`string`. URL of the resource that triggered the request. Note that this may not be the same as the URL of the page into which the requested resource will be loaded. For example, if a document triggers a load in a different window through the target attribute of a link, or a CSS document includes an image using the `url()` functional notation, then this is the URL of the original document or of the CSS document, respectively.

`parentFrameId`

`integer`. ID of the frame that contains the frame that sent the request. Set to -1 if no parent frame exists.

`requestId`

`string`. The ID of the request. Request IDs are unique within a browser session, so you can use an ID to identify different events associated with the same request.

`requestHeaders` Optional

`webRequest.HttpHeaders`. The HTTP request headers that will be sent with this request. Note that this is only included if the `"requestHeaders"` option was passed into `addListener()`.

`tabId`

`integer`. ID of the tab in which the request takes place. Set to -1 if the request is not related to a tab.

`thirdParty`

`boolean`. Indicates whether the request and its content window hierarchy is third party.

`timeStamp`

`number`. The time when this event fired, in milliseconds since the epoch.

`type`

`webRequest.ResourceType`. The type of resource being requested: for example, "image", "script", or "stylesheet".

`url`

`string`. Target of the request.

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

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

Deletes all visits from the browser's history.

This function triggers `history.onVisitRemoved` just once, with `allHistory` set to `true` and an empty `urls` argument.

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

Syntax
------


```js
let deletingAll = browser.history.deleteAll()
```

### Parameters

None.

### Return value

A `Promise` will be fulfilled with no parameters when all history has been deleted.

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

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

Examples
--------

Delete all history when the user clicks a browser action:


```js
function onDeleteAll() {
  console.log("Deleted all history");
}

function deleteAllHistory() {
  let deletingAll = browser.history.deleteAll();
  deletingAll.then(onDeleteAll);
}

deleteAllHistory();
```


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

This describes how the browser navigated to a particular page. For example, "link" means that the browser navigated to the page because the user clicked a link.

Type
----

Values of this type are strings. Possible values are:

"link"

The user clicked a link in another page.

"typed"

The user typed the URL into the address bar. This is also used if the user started typing into the address bar, then selected a URL from the suggestions it offered. See also "generated".

"auto\_bookmark"

The user clicked a bookmark or an item in the browser history.

"auto\_subframe"

Any nested iframes that are automatically loaded by their parent.

"manual\_subframe"

Any nested iframes that are loaded as an explicit user action. Loading such an iframe will generate an entry in the back/forward navigation list.

"generated"

The user started typing in the address bar, then clicked on a suggested entry that didn't contain a URL.

"auto\_toplevel"

The page was passed to the command line or is the start page.

"form\_submit"

The user submitted a form. Note that in some situations, such as when a form uses a script to submit its contents, submitting a form does not result in this transition type.

"reload"

The user reloaded the page, using the Reload button or by pressing Enter in the address bar. This is also used for session restore and reopening closed tabs.

"keyword"

The URL was generated using a keyword search configured by the user.

"keyword\_generated"

Corresponds to a visit generated for a keyword.

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

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

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

Removes all visits to the given URL from the browser history.

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

Syntax
------


```js
let deletingUrl = browser.history.deleteUrl(
  details         // object
)
```

### Parameters

`details`

`object`. Object containing the URL whose visits to remove.

`url`

`string`. The URL whose visits should be removed.


### Return value

A `Promise` will be fulfilled with no parameters when the visits have been removed.

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

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

Examples
--------

Remove all visits to "https://example.org/" from history, then check that this URL no longer returned from `history.search()`:


```js
let urlToRemove = "https://example.org/";

function onGot(results) {
  if (!results.length) {
    console.log(`${urlToRemove} was removed`);
  } else {
    console.log(`${urlToRemove} was not removed`);
  }
}

function onRemoved() {
  let searching = browser.history.search({
    text: urlToRemove,
    startTime: 0,
  });

  searching.then(onGot);
}

let deletingUrl = browser.history.deleteUrl({ url: urlToRemove });

deletingUrl.then(onRemoved);
```


Remove the last-visited page from history, with a listener to `history.onVisitRemoved` to log the URL of the removed page:


```js
function onRemoved(removeInfo) {
  if (removeInfo.urls.length) {
    console.log(`Removed: ${removeInfo.urls[0]}`);
  }
}

browser.history.onVisitRemoved.addListener(onRemoved);

function onGot(results) {
  if (results.length) {
    console.log(`Removing: ${results[0].url}`);
    browser.history.deleteUrl({ url: results[0].url });
  }
}

let searching = browser.history.search({
  text: "",
  startTime: 0,
  maxResults: 1,
});

searching.then(onGot);
```

### Example extensions

* history-deleter

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

An object describing a single visit to a page.

Type
----

Values of this type are objects. They contain the following properties:

`id`

`string`. The unique identifier for the `history.HistoryItem` associated with this visit.

`visitId`

`string`. The unique identifier for this visit.

`visitTime` Optional

`number`. When this visit occurred, represented in milliseconds since the epoch.

`referringVisitId`

`string`. The visit ID of the referrer.

`transition`

`history.TransitionType`. Describes how the browser navigated to the page on this occasion.

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

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

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