From 3aa7d5edd18a09e7359fa9bd6ebb8c4144dcf071 Mon Sep 17 00:00:00 2001 From: Leonard Thieu Date: Fri, 14 Sep 2018 08:12:16 -0400 Subject: [PATCH 01/52] [jquery] Remove usages of `const enum`. `Mouse` and `Key` were provided for convenience. Their presence is problematic though as they're not actually part of the jQuery API, cause the `JQuery` namespace to become a value, and doesn't work with the `isolatedModules` option. --- types/jquery/index.d.ts | 127 ---------------------------------------- 1 file changed, 127 deletions(-) diff --git a/types/jquery/index.d.ts b/types/jquery/index.d.ts index b03a48dc6f..7e06fd0b7d 100644 --- a/types/jquery/index.d.ts +++ b/types/jquery/index.d.ts @@ -8207,133 +8207,6 @@ declare namespace JQuery { (this: TContext, t: T, ...args: any[]): void | false | any; } - // Provided for convenience for use with jQuery.Event.which - // tslint:disable-next-line:no-const-enum - const enum Mouse { - None = 0, - Left = 1, - Middle = 2, - Right = 3 - } - - // Provided for convenience for use with jQuery.Event.which - // tslint:disable-next-line:no-const-enum - const enum Key { - Backspace = 8, - Tab = 9, - Enter = 13, - Shift = 16, - Control = 17, - Alt = 18, - CapsLock = 20, - Escape = 27, - Space = 32, - PageUp = 33, - PageDown = 34, - End = 35, - Home = 36, - ArrowLeft = 37, - ArrowUp = 38, - ArrowRight = 39, - ArrowDown = 40, - - Semicolon = 186, - Colon = 186, - EqualsSign = 187, - Plus = 187, - Comma = 188, - LessThanSign = 188, - Minus = 189, - Underscore = 189, - Period = 190, - GreaterThanSign = 190, - ForwardSlash = 191, - QuestionMark = 191, - Backtick = 192, - Tilde = 192, - OpeningSquareBracket = 219, - OpeningCurlyBrace = 219, - Backslash = 220, - Pipe = 220, - ClosingSquareBracket = 221, - ClosingCurlyBrace = 221, - SingleQuote = 222, - DoubleQuote = 222, - - Pause = 19, - PrintScreen = 44, - Insert = 45, - Delete = 46, - Num0 = 48, - Num1 = 49, - Num2 = 50, - Num3 = 51, - Num4 = 52, - Num5 = 53, - Num6 = 54, - Num7 = 55, - Num8 = 56, - Num9 = 57, - A = 65, - B = 66, - C = 67, - D = 68, - E = 69, - F = 70, - G = 71, - H = 72, - I = 73, - J = 74, - K = 75, - L = 76, - M = 77, - N = 78, - O = 79, - P = 80, - Q = 81, - R = 82, - S = 83, - T = 84, - U = 85, - V = 86, - W = 87, - X = 88, - Y = 89, - Z = 90, - MetaLeft = 91, - MetaRight = 92, - ContextMenu = 93, - Numpad0 = 96, - Numpad1 = 97, - Numpad2 = 98, - Numpad3 = 99, - Numpad4 = 100, - Numpad5 = 101, - Numpad6 = 102, - Numpad7 = 103, - Numpad8 = 104, - Numpad9 = 105, - NumpadMultiply = 106, - NumpadAdd = 107, - NumpadSubtract = 109, - NumpadDecimal = 110, - NumpadDivide = 111, - F1 = 112, - F2 = 113, - F3 = 114, - F4 = 115, - F5 = 116, - F6 = 117, - F7 = 118, - F8 = 119, - F9 = 120, - F10 = 121, - F11 = 122, - F12 = 123, - NumLock = 144, - ScrollLock = 145 - } - // endregion interface NameValuePair { From 691230212848a8f0bd675aabb8f4d13f0c381d0d Mon Sep 17 00:00:00 2001 From: Leonard Thieu Date: Fri, 14 Sep 2018 08:15:23 -0400 Subject: [PATCH 02/52] [jquery] Fix region folding for VS Code. --- types/jquery/index.d.ts | 152 ++++++++++++++++++++-------------------- 1 file changed, 76 insertions(+), 76 deletions(-) diff --git a/types/jquery/index.d.ts b/types/jquery/index.d.ts index 7e06fd0b7d..644409ec99 100644 --- a/types/jquery/index.d.ts +++ b/types/jquery/index.d.ts @@ -860,13 +860,13 @@ interface JQueryStatic { */ post(url_settings?: string | JQuery.UrlAjaxSettings): JQuery.jqXHR; - // region proxy + // #region proxy - // region (fn, null | undefined) + // #region (fn, null | undefined) - // region 0 to 7 arguments + // #region 0 to 7 arguments - // region 0 parameters + // #region 0 parameters /** * Takes a function and returns a new one that will always have a particular context. @@ -980,9 +980,9 @@ interface JQueryStatic { proxy(fn: () => TReturn, context: null | undefined): () => TReturn; - // endregion + // #endregion - // region 1 parameters + // #region 1 parameters /** * Takes a function and returns a new one that will always have a particular context. @@ -1110,9 +1110,9 @@ interface JQueryStatic { T>(fn: (t: T) => TReturn, context: null | undefined): (t: T) => TReturn; - // endregion + // #endregion - // region 2 parameters + // #region 2 parameters /** * Takes a function and returns a new one that will always have a particular context. @@ -1240,9 +1240,9 @@ interface JQueryStatic { T, U>(fn: (t: T, u: U) => TReturn, context: null | undefined): (t: T, u: U) => TReturn; - // endregion + // #endregion - // region 3 parameters + // #region 3 parameters /** * Takes a function and returns a new one that will always have a particular context. @@ -1370,9 +1370,9 @@ interface JQueryStatic { T, U, V>(fn: (t: T, u: U, v: V) => TReturn, context: null | undefined): (t: T, u: U, v: V) => TReturn; - // endregion + // #endregion - // region 4 parameters + // #region 4 parameters /** * Takes a function and returns a new one that will always have a particular context. @@ -1500,9 +1500,9 @@ interface JQueryStatic { T, U, V, W>(fn: (t: T, u: U, v: V, w: W) => TReturn, context: null | undefined): (t: T, u: U, v: V, w: W) => TReturn; - // endregion + // #endregion - // region 5 parameters + // #region 5 parameters /** * Takes a function and returns a new one that will always have a particular context. @@ -1630,9 +1630,9 @@ interface JQueryStatic { T, U, V, W, X>(fn: (t: T, u: U, v: V, w: W, x: X) => TReturn, context: null | undefined): (t: T, u: U, v: V, w: W, x: X) => TReturn; - // endregion + // #endregion - // region 6 parameters + // #region 6 parameters /** * Takes a function and returns a new one that will always have a particular context. @@ -1760,9 +1760,9 @@ interface JQueryStatic { T, U, V, W, X, Y>(fn: (t: T, u: U, v: V, w: W, x: X, y: Y) => TReturn, context: null | undefined): (t: T, u: U, v: V, w: W, x: X, y: Y) => TReturn; - // endregion + // #endregion - // region 7+ parameters + // #region 7+ parameters /** * Takes a function and returns a new one that will always have a particular context. @@ -1890,11 +1890,11 @@ interface JQueryStatic { T, U, V, W, X, Y, Z>(fn: (t: T, u: U, v: V, w: W, x: X, y: Y, z: Z, ...args: any[]) => TReturn, context: null | undefined): (t: T, u: U, v: V, w: W, x: X, y: Y, z: Z, ...args: any[]) => TReturn; - // endregion + // #endregion - // endregion + // #endregion - // region 8+ arguments + // #region 8+ arguments /** * Takes a function and returns a new one that will always have a particular context. @@ -1911,15 +1911,15 @@ interface JQueryStatic { context: null | undefined, ...additionalArguments: any[]): (...args: any[]) => TReturn; - // endregion + // #endregion - // endregion + // #endregion - // region (fn, context) + // #region (fn, context) - // region 0 to 7 arguments + // #region 0 to 7 arguments - // region 0 parameters + // #region 0 parameters /** * Takes a function and returns a new one that will always have a particular context. @@ -2048,9 +2048,9 @@ interface JQueryStatic { TReturn>(fn: () => TReturn, context: TContext): (this: TContext) => TReturn; - // endregion + // #endregion - // region 1 parameters + // #region 1 parameters /** * Takes a function and returns a new one that will always have a particular context. @@ -2194,9 +2194,9 @@ interface JQueryStatic { T>(fn: (t: T) => TReturn, context: TContext): (this: TContext, t: T) => TReturn; - // endregion + // #endregion - // region 2 parameters + // #region 2 parameters /** * Takes a function and returns a new one that will always have a particular context. @@ -2340,9 +2340,9 @@ interface JQueryStatic { T, U>(fn: (t: T, u: U) => TReturn, context: TContext): (this: TContext, t: T, u: U) => TReturn; - // endregion + // #endregion - // region 3 parameters + // #region 3 parameters /** * Takes a function and returns a new one that will always have a particular context. @@ -2486,9 +2486,9 @@ interface JQueryStatic { T, U, V>(fn: (t: T, u: U, v: V) => TReturn, context: TContext): (this: TContext, t: T, u: U, v: V) => TReturn; - // endregion + // #endregion - // region 4 parameters + // #region 4 parameters /** * Takes a function and returns a new one that will always have a particular context. @@ -2632,9 +2632,9 @@ interface JQueryStatic { T, U, V, W>(fn: (t: T, u: U, v: V, w: W) => TReturn, context: TContext): (this: TContext, t: T, u: U, v: V, w: W) => TReturn; - // endregion + // #endregion - // region 5 parameters + // #region 5 parameters /** * Takes a function and returns a new one that will always have a particular context. @@ -2778,9 +2778,9 @@ interface JQueryStatic { T, U, V, W, X>(fn: (t: T, u: U, v: V, w: W, x: X) => TReturn, context: TContext): (this: TContext, t: T, u: U, v: V, w: W, x: X) => TReturn; - // endregion + // #endregion - // region 6 parameters + // #region 6 parameters /** * Takes a function and returns a new one that will always have a particular context. @@ -2924,9 +2924,9 @@ interface JQueryStatic { T, U, V, W, X, Y>(fn: (t: T, u: U, v: V, w: W, x: X, y: Y) => TReturn, context: TContext): (this: TContext, t: T, u: U, v: V, w: W, x: X, y: Y) => TReturn; - // endregion + // #endregion - // region 7+ parameters + // #region 7+ parameters /** * Takes a function and returns a new one that will always have a particular context. @@ -3070,11 +3070,11 @@ interface JQueryStatic { T, U, V, W, X, Y, Z>(fn: (t: T, u: U, v: V, w: W, x: X, y: Y, z: Z, ...args: any[]) => TReturn, context: TContext): (this: TContext, t: T, u: U, v: V, w: W, x: X, y: Y, z: Z, ...args: any[]) => TReturn; - // endregion + // #endregion - // endregion + // #endregion - // region 8+ arguments + // #region 8+ arguments /** * Takes a function and returns a new one that will always have a particular context. @@ -3093,11 +3093,11 @@ interface JQueryStatic { context: TContext, ...additionalArguments: any[]): (this: TContext, ...args: any[]) => TReturn; - // endregion + // #endregion - // endregion + // #endregion - // region (context, name) + // #region (context, name) /** * Takes a function and returns a new one that will always have a particular context. @@ -3115,9 +3115,9 @@ interface JQueryStatic { name: keyof TContext, ...additionalArguments: any[]): (this: TContext, ...args: any[]) => any; - // endregion + // #endregion - // endregion + // #endregion /** * Manipulate the queue of functions to be executed on the matched element. @@ -5886,7 +5886,7 @@ declare namespace JQuery { [key: string]: T; } - // region Ajax + // #region Ajax interface AjaxSettings extends Ajax.AjaxSettingsBase { /** @@ -6191,7 +6191,7 @@ declare namespace JQuery { } type StatusCodeCallbacks = { - // region Success Status Codes + // #region Success Status Codes // jQuery treats 2xx and 304 status codes as a success @@ -6297,9 +6297,9 @@ declare namespace JQuery { 299?: SuccessCallback; 304?: SuccessCallback; - // endregion + // #endregion - // region Error Status Codes + // #region Error Status Codes 300?: ErrorCallback; 301?: ErrorCallback; @@ -6601,7 +6601,7 @@ declare namespace JQuery { 598?: ErrorCallback; 599?: ErrorCallback; - // endregion + // #endregion } & { // Status codes not listed require type annotations when defining the callback [index: number]: SuccessCallback | ErrorCallback; @@ -6653,9 +6653,9 @@ declare namespace JQuery { interface AlwaysCallback> extends Deferred.Callback3 { } } - // endregion + // #endregion - // region Callbacks + // #region Callbacks // tslint:disable-next-line:ban-types interface Callbacks { @@ -6746,18 +6746,18 @@ declare namespace JQuery { remove(...callbacks: T[]): this; } - // endregion + // #endregion - // region CSS + // #region CSS interface CSSHook { get(this: this, elem: TElement, computed: any, extra: any): any; set(this: this, elem: TElement, value: any): void; } - // endregion + // #endregion - // region Deferred + // #region Deferred /** * Any object that has a then method. @@ -6875,7 +6875,7 @@ declare namespace JQuery { */ state(): 'pending' | 'resolved' | 'rejected'; - // region pipe + // #region pipe /** * Utility method to filter and/or chain Deferreds. @@ -7088,9 +7088,9 @@ declare namespace JQuery { CRD, CJD, CND, RRD, RJD, RND>; - // endregion + // #endregion - // region then + // #region then /** * Add handlers to be called when the Deferred object is resolved, rejected, or still in progress. @@ -7282,7 +7282,7 @@ declare namespace JQuery { CRD, CJD, CND, RRD, RJD, RND>; - // endregion + // #endregion /** * Add handlers to be called when the Deferred object is rejected. @@ -7463,7 +7463,7 @@ declare namespace JQuery { */ state(): 'pending' | 'resolved' | 'rejected'; - // region pipe + // #region pipe /** * Utility method to filter and/or chain Deferreds. @@ -7676,9 +7676,9 @@ declare namespace JQuery { CRD, CJD, CND, RRD, RJD, RND>; - // endregion + // #endregion - // region then + // #region then /** * Add handlers to be called when the Deferred object is resolved, rejected, or still in progress. @@ -7870,7 +7870,7 @@ declare namespace JQuery { CRD, CJD, CND, RRD, RJD, RND>; - // endregion + // #endregion /** * Add handlers to be called when the Deferred object is rejected. @@ -7924,9 +7924,9 @@ declare namespace JQuery { interface ProgressCallback extends Callback { } } - // endregion + // #endregion - // region Effects + // #region Effects type Duration = number | 'fast' | 'slow'; // TODO: Is the first element always a string or is that specific to the 'fx' queue? @@ -8028,11 +8028,11 @@ declare namespace JQuery { (fx: Tween): void; } - // endregion + // #endregion - // region Events + // #region Events - // region Event + // #region Event // This should be a class but doesn't work correctly under the JQuery namespace. Event should be an inner class of jQuery. @@ -8198,7 +8198,7 @@ declare namespace JQuery { type: string; } - // endregion + // #endregion interface EventHandler extends EventHandlerBase> { } @@ -8207,7 +8207,7 @@ declare namespace JQuery { (this: TContext, t: T, ...args: any[]): void | false | any; } - // endregion + // #endregion interface NameValuePair { name: string; @@ -8231,7 +8231,7 @@ declare namespace JQuery { } } -// region Legacy types +// #region Legacy types // tslint:disable-next-line:no-empty-interface interface JQueryCallback extends JQuery.Callbacks { } @@ -8430,4 +8430,4 @@ interface JQueryEasingFunctions { swing: JQueryEasingFunction; } -// endregion +// #endregion From 38606b9c67a9be018707bdc9d60e8682640998d3 Mon Sep 17 00:00:00 2001 From: Jasmin Bom Date: Tue, 18 Sep 2018 23:24:02 +0200 Subject: [PATCH 03/52] Update firefox-webext-browser to v63.0b6 --- .../firefox-webext-browser-tests.ts | 2 - types/firefox-webext-browser/index.d.ts | 1753 +++++++++++++---- 2 files changed, 1365 insertions(+), 390 deletions(-) diff --git a/types/firefox-webext-browser/firefox-webext-browser-tests.ts b/types/firefox-webext-browser/firefox-webext-browser-tests.ts index a2d9f0bda0..26ae079172 100644 --- a/types/firefox-webext-browser/firefox-webext-browser-tests.ts +++ b/types/firefox-webext-browser/firefox-webext-browser-tests.ts @@ -6,8 +6,6 @@ browser.runtime.getManifest(); // $ExpectType WebExtensionManifest browser.test; // $ExpectError browser.manifest; // $ExpectError browser._manifest; // $ExpectError -browser._manifest.WebExtensionLangpackManifest; // $ExpectError -browser._manifest.NativeManifest; // $ExpectError // browser.runtime const port = browser.runtime.connect(); diff --git a/types/firefox-webext-browser/index.d.ts b/types/firefox-webext-browser/index.d.ts index 47035f4f87..d9e9e8df7c 100644 --- a/types/firefox-webext-browser/index.d.ts +++ b/types/firefox-webext-browser/index.d.ts @@ -1,9 +1,9 @@ -// Type definitions for WebExtension Development in FireFox 58.0 +// Type definitions for WebExtension Development in FireFox 63.0 // Project: https://developer.mozilla.org/en-US/Add-ons/WebExtensions -// Definitions by: Jacob Bom +// Definitions by: Jasmin Bom // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped // TypeScript Version: 2.9 -// Generated using script at github.com/bomjacob/definitelytyped-firefox-webext-browser +// Generated using script at github.com/jsmnbom/definitelytyped-firefox-webext-browser interface WebExtEventBase any, TCallback> { addListener: TAddListener; @@ -105,46 +105,14 @@ declare namespace browser._manifest { type Permission = string | OptionalPermission | _Permission; - /** Represents a protocol handler definition. */ - interface ProtocolHandler { - /** - * A user-readable title string for the protocol handler. This will be displayed to the user in interface - * objects as needed. - */ - name: string; - /** - * The protocol the site wishes to handle, specified as a string. For example, you can register to handle SMS - * text message links by registering to handle the "sms" scheme. - */ - protocol: string | _ProtocolHandlerProtocol; - /** - * The URL of the handler, as a string. This string should include "%s" as a placeholder which will be replaced - * with the escaped URL of the document to be handled. This URL might be a true URL, or it could be a phone - * number, email address, or so forth. - */ - uriTemplate: ExtensionURL | HttpURL; - } - /** Represents a WebExtension manifest.json file */ interface WebExtensionManifest { + experiment_apis?: experiments.ExperimentAPI; /** A list of protocol handler definitions. */ protocol_handlers?: ProtocolHandler[]; default_locale?: string; - manifest_version: number; minimum_chrome_version?: string; minimum_opera_version?: string; - applications?: { - gecko?: FirefoxSpecificProperties; - }; - browser_specific_settings?: { - gecko?: FirefoxSpecificProperties; - }; - name: string; - short_name?: string; - description?: string; - author?: string; - version: string; - homepage_url?: string; icons?: { [key: number]: string; }; @@ -171,7 +139,8 @@ declare namespace browser._manifest { name?: string; url?: string; }; - theme?: ThemeType; + hidden?: boolean; + theme_experiment?: ThemeExperiment; browser_action?: { default_title?: string; default_icon?: IconPath; @@ -231,12 +200,16 @@ declare namespace browser._manifest { default_icon?: IconPath; default_popup?: string; browser_style?: boolean; + show_matches?: MatchPattern[]; + hide_matches?: MatchPatternRestricted[]; }; sidebar_action?: { default_title?: string; default_icon?: IconPath; browser_style?: boolean; default_panel: string; + /** Whether or not the sidebar is opened at install. Default is `true`. */ + open_at_install?: boolean; }; chrome_url_overrides?: { newtab?: ExtensionURL; @@ -245,6 +218,110 @@ declare namespace browser._manifest { /** @deprecated Unsupported on Firefox at this time. */ history?: ExtensionURL; }; + manifest_version: number; + applications?: { + gecko?: FirefoxSpecificProperties; + }; + browser_specific_settings?: { + gecko?: FirefoxSpecificProperties; + }; + name: string; + short_name?: string; + description?: string; + author?: string; + version: string; + homepage_url?: string; + } + + /** Represents a protocol handler definition. */ + interface ProtocolHandler { + /** + * A user-readable title string for the protocol handler. This will be displayed to the user in interface + * objects as needed. + */ + name: string; + /** + * The protocol the site wishes to handle, specified as a string. For example, you can register to handle SMS + * text message links by registering to handle the "sms" scheme. + */ + protocol: string | _ProtocolHandlerProtocol; + /** + * The URL of the handler, as a string. This string should include "%s" as a placeholder which will be replaced + * with the escaped URL of the document to be handled. This URL might be a true URL, or it could be a phone + * number, email address, or so forth. + */ + uriTemplate: ExtensionURL | HttpURL; + } + + /** Common properties for all manifest.json files */ + interface ManifestBase { + manifest_version: number; + applications?: { + gecko?: FirefoxSpecificProperties; + }; + browser_specific_settings?: { + gecko?: FirefoxSpecificProperties; + }; + name: string; + short_name?: string; + description?: string; + author?: string; + version: string; + homepage_url?: string; + } + + /** Represents a WebExtension language pack manifest.json file */ + interface WebExtensionLangpackManifest { + homepage_url?: string; + langpack_id: string; + languages: { + [key: string]: { + chrome_resources: { + [key: string]: ExtensionURL | { + [key: string]: ExtensionURL; + }; + }; + version: string; + }; + }; + sources?: { + [key: string]: { + base_path: ExtensionURL; + paths?: string[]; + }; + }; + manifest_version: number; + applications?: { + gecko?: FirefoxSpecificProperties; + }; + browser_specific_settings?: { + gecko?: FirefoxSpecificProperties; + }; + name: string; + short_name?: string; + description?: string; + author?: string; + version: string; + } + + /** Represents a WebExtension dictionary manifest.json file */ + interface WebExtensionDictionaryManifest { + homepage_url?: string; + dictionaries: { + [key: string]: string; + }; + manifest_version: number; + applications?: { + gecko?: FirefoxSpecificProperties; + }; + browser_specific_settings?: { + gecko?: FirefoxSpecificProperties; + }; + name: string; + short_name?: string; + description?: string; + author?: string; + version: string; } interface ThemeIcons { @@ -275,7 +352,16 @@ declare namespace browser._manifest { strict_max_version?: string; } - type MatchPattern = string | _MatchPattern; + type MatchPattern = MatchPatternRestricted | MatchPatternUnestricted | _MatchPattern; + + /** Same as MatchPattern above, but excludes */ + type MatchPatternRestricted = string; + + /** + * Mostly unrestricted match patterns for privileged add-ons. This should technically be rejected for unprivileged + * add-ons, but, reasons. The MatchPattern class will still refuse privileged schemes for those extensions. + */ + type MatchPatternUnestricted = string; /** Same as MatchPattern above, but includes moz-extension protocol */ type MatchPatternInternal = string | _MatchPatternInternal; @@ -291,7 +377,7 @@ declare namespace browser._manifest { exclude_globs?: string[]; /** The list of CSS files to inject */ css?: ExtensionURL[]; - /** The list of CSS files to inject */ + /** The list of JS files to inject */ js?: ExtensionURL[]; /** * If allFrames is `true`, implies that the JavaScript or CSS should be injected into all frames of current @@ -324,6 +410,29 @@ declare namespace browser._manifest { /** @deprecated Event pages are not currently supported. This will run as a persistent background page. */ type PersistentBackgroundProperty = boolean; + /** Represents a native manifest file */ + type NativeManifest = { + name: string; + description: string; + path: string; + type: "pkcs11" | "stdio"; + allowed_extensions: ExtensionID[]; + } | { + name: ExtensionID; + description: string; + data: any; + type: "storage"; + }; + + type ThemeColor = string | [number, number, number] | [number, number, number, number]; + + interface ThemeExperiment { + stylesheet?: ExtensionURL; + images?: string; + colors?: string; + properties?: string; + } + interface ThemeType { images?: { additional_backgrounds?: ImageDataOrExtensionURL[]; @@ -331,18 +440,44 @@ declare namespace browser._manifest { theme_frame?: ImageDataOrExtensionURL; }; colors?: { - accentcolor?: string; - frame?: number[]; - tab_text?: number[]; - textcolor?: string; - toolbar?: string; - toolbar_text?: string; - bookmark_text?: string; - toolbar_field?: string; - toolbar_field_text?: string; - toolbar_top_separator?: string; - toolbar_bottom_separator?: string; - toolbar_vertical_separator?: string; + tab_selected?: ThemeColor; + accentcolor?: ThemeColor; + frame?: ThemeColor; + frame_inactive?: ThemeColor; + textcolor?: ThemeColor; + tab_background_text?: ThemeColor; + tab_background_separator?: ThemeColor; + tab_loading?: ThemeColor; + tab_text?: ThemeColor; + tab_line?: ThemeColor; + toolbar?: ThemeColor; + toolbar_text?: ThemeColor; + bookmark_text?: ThemeColor; + toolbar_field?: ThemeColor; + toolbar_field_text?: ThemeColor; + toolbar_field_border?: ThemeColor; + toolbar_field_separator?: ThemeColor; + toolbar_top_separator?: ThemeColor; + toolbar_bottom_separator?: ThemeColor; + toolbar_vertical_separator?: ThemeColor; + icons?: ThemeColor; + icons_attention?: ThemeColor; + button_background_hover?: ThemeColor; + button_background_active?: ThemeColor; + popup?: ThemeColor; + popup_text?: ThemeColor; + popup_border?: ThemeColor; + toolbar_field_focus?: ThemeColor; + toolbar_field_text_focus?: ThemeColor; + toolbar_field_border_focus?: ThemeColor; + popup_highlight?: ThemeColor; + popup_highlight_text?: ThemeColor; + ntp_background?: ThemeColor; + ntp_text?: ThemeColor; + sidebar?: ThemeColor; + sidebar_text?: ThemeColor; + sidebar_highlight?: ThemeColor; + sidebar_highlight_text?: ThemeColor; }; icons?: { back?: ExtensionURL; @@ -432,11 +567,23 @@ declare namespace browser._manifest { }; } + /** Contents of manifest.json for a static theme */ + interface ThemeManifest { + theme: ThemeType; + default_locale?: string; + theme_experiment?: ThemeExperiment; + icons?: { + [key: number]: string; + }; + } + type KeyName = string; type _OptionalPermission = - "browserSettings" + "browserSettings" | "cookies" + | "downloads" + | "downloads.open" | "clipboardRead" | "clipboardWrite" | "geolocation" @@ -449,13 +596,14 @@ declare namespace browser._manifest { | "bookmarks" | "find" | "history" + | "search" | "activeTab" - | "tabs"; + | "tabs" + | "tabHide"; type _Permission = - "contextualIdentities" - | "downloads" - | "downloads.open" + "contextualIdentities" + | "dns" | "identity" | "management" | "alarms" @@ -465,6 +613,7 @@ declare namespace browser._manifest { | "privacy" | "proxy" | "nativeMessaging" + | "telemetry" | "theme" | "browsingData" | "devtools" @@ -474,11 +623,24 @@ declare namespace browser._manifest { | "pkcs11" | "sessions"; + type _WebExtensionManifestIncognito = "spanning"; + + /** Defines the location the browserAction will appear by default. The default location is navbar. */ + type _WebExtensionManifestBrowserActionDefaultArea = + "navbar" + | "menupanel" + | "tabstrip" + | "personaltoolbar"; + type _ProtocolHandlerProtocol = - "bitcoin" + "bitcoin" + | "dat" + | "dweb" | "geo" | "gopher" | "im" + | "ipfs" + | "ipns" | "irc" | "ircs" | "magnet" @@ -489,6 +651,7 @@ declare namespace browser._manifest { | "sip" | "sms" | "smsto" + | "ssb" | "ssh" | "tel" | "urn" @@ -496,21 +659,12 @@ declare namespace browser._manifest { | "wtai" | "xmpp"; - type _WebExtensionManifestIncognito = "spanning"; - - /** Defines the location the browserAction will appear by default. The default location is navbar. */ - type _WebExtensionManifestBrowserActionDefaultArea = - "navbar" - | "menupanel" - | "tabstrip" - | "personaltoolbar"; - type _MatchPattern = ""; type _MatchPatternInternal = ""; type _ThemeTypeAdditionalBackgroundsAlignment = - "bottom" + "bottom" | "center" | "left" | "right" @@ -526,7 +680,7 @@ declare namespace browser._manifest { | "right top"; type _ThemeTypeAdditionalBackgroundsTiling = - "no-repeat" + "no-repeat" | "repeat" | "repeat-x" | "repeat-y"; @@ -541,13 +695,15 @@ declare namespace browser._manifest { */ declare namespace browser.browserSettings { /* browserSettings types */ - /** How images should be animated in the browser. */ type ImageAnimationBehavior = - "normal" + "normal" | "none" | "once"; + /** After which mouse event context menus should popup. */ + type ContextMenuMouseEvent = "mouseup" | "mousedown"; + /* browserSettings properties */ /** Allows or disallows pop-up windows from opening in response to user events. */ const allowPopupsForUserEvents: types.Setting; @@ -555,6 +711,15 @@ declare namespace browser.browserSettings { /** Enables or disables the browser cache. */ const cacheEnabled: types.Setting; + /** This boolean setting controls whether the selected tab can be closed with a double click. */ + const closeTabsByDoubleClick: types.Setting; + + /** + * Controls after which mouse event context menus popup. This setting's value is of type ContextMenuMouseEvent, + * which has possible values of `mouseup` and `mousedown`. + */ + const contextMenuShowEvent: types.Setting; + /** Returns the value of the overridden home page. Read-only. */ const homepageOverride: types.Setting; @@ -567,8 +732,30 @@ declare namespace browser.browserSettings { /** Returns the value of the overridden new tab page. Read-only. */ const newTabPageOverride: types.Setting; + /** + * Controls where new tabs are opened. `afterCurrent` will open all new tabs next to the current tab, + * `relatedAfterCurrent` will open only related tabs next to the current tab, and `atEnd` will open all tabs at the + * end of the tab strip. The default is `relatedAfterCurrent`. + */ + const newTabPosition: types.Setting; + + /** This boolean setting controls whether bookmarks are opened in the current tab or in a new tab. */ + const openBookmarksInNewTabs: types.Setting; + + /** This boolean setting controls whether search results are opened in the current tab or in a new tab. */ + const openSearchResultsInNewTabs: types.Setting; + + /** This boolean setting controls whether urlbar results are opened in the current tab or in a new tab. */ + const openUrlbarResultsInNewTabs: types.Setting; + /** Disables webAPI notifications. */ const webNotificationsDisabled: types.Setting; + + /** This setting controls whether the user-chosen colors override the page's colors. */ + const overrideDocumentColors: types.Setting; + + /** This setting controls whether the document's fonts are used. */ + const useDocumentFonts: types.Setting; } /** @@ -595,6 +782,51 @@ declare namespace browser.clipboard { function setImageData(imageData: ArrayBuffer, imageType: _SetImageData): Promise; } +/** Not allowed in: Content scripts, Devtools pages */ +declare namespace browser.contentScripts { + /* contentScripts types */ + type ExtensionFileOrCode = { + file: _manifest.ExtensionURL; + } | { + code: string; + }; + + /** Details of a content script registered programmatically */ + interface RegisteredContentScriptOptions { + matches: _manifest.MatchPattern[]; + excludeMatches?: _manifest.MatchPattern[]; + includeGlobs?: string[]; + excludeGlobs?: string[]; + /** The list of CSS files to inject */ + css?: ExtensionFileOrCode[]; + /** The list of JS files to inject */ + js?: ExtensionFileOrCode[]; + /** + * If allFrames is `true`, implies that the JavaScript or CSS should be injected into all frames of current + * page. By default, it's `false` and is only injected into the top frame. + */ + allFrames?: boolean; + /** + * If matchAboutBlank is true, then the code is also injected in about:blank and about:srcdoc frames if your + * extension has access to its parent document. Code cannot be inserted in top-level about:-frames. By default + * it is `false`. + */ + matchAboutBlank?: boolean; + /** The soonest that the JavaScript or CSS will be injected into the tab. Defaults to "document_idle". */ + runAt?: extensionTypes.RunAt; + } + + /** An object that represents a content script registered programmatically */ + interface RegisteredContentScript { + /** Unregister a content script registered programmatically */ + unregister(): Promise; + } + + /* contentScripts functions */ + /** Register a content script programmatically */ + function register(contentScriptOptions: RegisteredContentScriptOptions): Promise; +} + /** * Use the `browser.contextualIdentities` API to query and modify contextual identity, also called as containers. * @@ -698,6 +930,16 @@ declare namespace browser.contextualIdentities { */ declare namespace browser.cookies { /* cookies types */ + /** + * A cookie's 'SameSite' state (https://tools.ietf.org/html/draft-west-first-party-cookies). 'no_restriction' + * corresponds to a cookie set without a 'SameSite' attribute, 'lax' to 'SameSite=Lax', and 'strict' to + * 'SameSite=Strict'. + */ + type SameSiteStatus = + "no_restriction" + | "lax" + | "strict"; + /** Represents information about an HTTP cookie. */ interface Cookie { /** The name of the cookie. */ @@ -718,6 +960,8 @@ declare namespace browser.cookies { secure: boolean; /** True if the cookie is marked as HttpOnly (i.e. the cookie is inaccessible to client-side scripts). */ httpOnly: boolean; + /** The cookie's same-site status (i.e. whether the cookie is sent with cross-site requests). */ + sameSite: SameSiteStatus; /** True if the cookie is a session cookie, as opposed to a persistent cookie with an expiration date. */ session: boolean; /** @@ -727,6 +971,8 @@ declare namespace browser.cookies { expirationDate?: number; /** The ID of the cookie store containing this cookie, as provided in getAllCookieStores(). */ storeId: string; + /** The first-party domain of the cookie. */ + firstPartyDomain: string; } /** @@ -751,7 +997,7 @@ declare namespace browser.cookies { * "overwrite". Plan your response accordingly. */ type OnChangedCause = - "evicted" + "evicted" | "expired" | "explicit" | "expired_overwrite" @@ -778,6 +1024,11 @@ declare namespace browser.cookies { * cookie store will be used. */ storeId?: string; + /** + * The first-party domain which the cookie to retrieve is associated. This attribute is required if First-Party + * Isolation is enabled. + */ + firstPartyDomain?: string; }): Promise; /** @@ -804,6 +1055,12 @@ declare namespace browser.cookies { * used. */ storeId?: string; + /** + * Restricts the retrieved cookies to those whose first-party domains match this one. This attribute is + * required if First-Party Isolation is enabled. To not filter by a specific first-party domain, use `null` or + * `undefined`. + */ + firstPartyDomain?: string; }): Promise; /** @@ -829,6 +1086,8 @@ declare namespace browser.cookies { secure?: boolean; /** Whether the cookie should be marked as HttpOnly. Defaults to false. */ httpOnly?: boolean; + /** The cookie's same-site status. */ + sameSite?: SameSiteStatus; /** * The expiration date of the cookie as the number of seconds since the UNIX epoch. If omitted, the cookie * becomes a session cookie. @@ -839,6 +1098,10 @@ declare namespace browser.cookies { * execution context's cookie store. */ storeId?: string; + /** + * The first-party domain of the cookie. This attribute is required if First-Party Isolation is enabled. + */ + firstPartyDomain?: string; }): Promise; /** @@ -858,6 +1121,11 @@ declare namespace browser.cookies { * the current execution context's cookie store. */ storeId?: string; + /** + * The first-party domain associated with the cookie. This attribute is required if First-Party Isolation is + * enabled. + */ + firstPartyDomain?: string; }): Promise<{ /** The URL associated with the cookie that's been removed. */ url: string; @@ -865,6 +1133,8 @@ declare namespace browser.cookies { name: string; /** The ID of the cookie store from which the cookie was removed. */ storeId: string; + /** The first-party domain associated with the cookie that's been removed. */ + firstPartyDomain: string; } | undefined>; /** Lists all existing cookie stores. */ @@ -887,6 +1157,46 @@ declare namespace browser.cookies { }) => void>; } +/** + * Asynchronous DNS API + * + * Permissions: `dns` + * + * Not allowed in: Content scripts, Devtools pages + */ +declare namespace browser.dns { + /* dns types */ + /** An object encapsulating a DNS Record. */ + interface DNSRecord { + /** + * The canonical hostname for this record. this value is empty if the record was not fetched with the + * 'canonical_name' flag. + */ + canonicalName?: string; + /** Record retreived with TRR. */ + isTRR: string; + addresses: string[]; + } + + type ResolveFlags = _ResolveFlags[]; + + type _ResolveFlags = + "allow_name_collisions" + | "bypass_cache" + | "canonical_name" + | "disable_ipv4" + | "disable_ipv6" + | "disable_trr" + | "offline" + | "priority_low" + | "priority_medium" + | "speculate"; + + /* dns functions */ + /** Resolves a hostname to a DNS record. */ + function resolve(hostname: string, flags?: ResolveFlags): Promise; +} + /** * Permissions: `downloads` * @@ -895,12 +1205,12 @@ declare namespace browser.cookies { declare namespace browser.downloads { /* downloads types */ type FilenameConflictAction = - "uniquify" + "uniquify" | "overwrite" | "prompt"; type InterruptReason = - "FILE_FAILED" + "FILE_FAILED" | "FILE_ACCESS_DENIED" | "FILE_NO_SPACE" | "FILE_NAME_TOO_LONG" @@ -940,7 +1250,7 @@ declare namespace browser.downloads { * These string constants will never change, however the set of DangerTypes may change. */ type DangerType = - "file" + "file" | "url" | "content" | "uncommon" @@ -960,7 +1270,7 @@ declare namespace browser.downloads { * These string constants will never change, however the set of States may change. */ type State = - "in_progress" + "in_progress" | "interrupted" | "complete"; @@ -1085,9 +1395,7 @@ declare namespace browser.downloads { } /** The HTTP method to use if the URL uses the HTTP[S] protocol. */ - type _DownloadMethod = - "GET" - | "POST"; + type _DownloadMethod = "GET" | "POST"; /* downloads functions */ /** @@ -1400,6 +1708,45 @@ declare namespace browser.events { } } +/** Not allowed in: Content scripts, Devtools pages */ +declare namespace browser.experiments { + /* experiments types */ + interface ExperimentAPI { + schema: ExperimentURL; + parent?: { + events?: APIEvents; + paths?: APIPaths; + script: ExperimentURL; + scopes?: APIParentScope[]; + }; + child?: { + paths: APIPaths; + script: ExperimentURL; + scopes: APIChildScope[]; + }; + } + + type ExperimentURL = string; + + type APIPaths = APIPath[]; + + type APIPath = string[]; + + type APIEvents = APIEvent[]; + + type APIEvent = "startup"; + + type APIParentScope = + "addon_parent" + | "content_parent" + | "devtools_parent"; + + type APIChildScope = + "addon_child" + | "content_child" + | "devtools_child"; +} + /** * The `browser.extension` API has utilities that can be used by any extension page. It includes support for exchanging * messages between an extension and its content scripts or between extensions, as described in detail in Message @@ -1407,10 +1754,9 @@ declare namespace browser.events { */ declare namespace browser.extension { /* extension types */ - /** The type of extension view. */ type ViewType = - "tab" + "tab" | "popup" | "sidebar"; @@ -1507,11 +1853,8 @@ declare namespace browser.extension { */ declare namespace browser.extensionTypes { /* extensionTypes types */ - /** The format of an image. */ - type ImageFormat = - "jpeg" - | "png"; + type ImageFormat = "jpeg" | "png"; /** Details about the format and quality of an image. */ interface ImageDetails { @@ -1527,14 +1870,12 @@ declare namespace browser.extensionTypes { /** The soonest that the JavaScript or CSS will be injected into the tab. */ type RunAt = - "document_start" + "document_start" | "document_end" | "document_idle"; /** The origin of the CSS to inject, this affects the cascading order (priority) of the stylesheet. */ - type CSSOrigin = - "user" - | "author"; + type CSSOrigin = "user" | "author"; /** * Details of the script or CSS to inject. Either the code or the file property must be set, but both may not be @@ -1679,13 +2020,13 @@ declare namespace browser.identity { /** Starts an auth flow at the specified URL. */ function launchWebAuthFlow(details: { - url: string; + url: _manifest.HttpURL; interactive?: boolean; }): Promise; /** * Generates a redirect URL to be used in |launchWebAuthFlow|. - * @param [ path] The path appended to the end of the generated URL. + * @param [path] The path appended to the end of the generated URL. */ function getRedirectURL(path?: string): string; @@ -1706,9 +2047,7 @@ declare namespace browser.identity { */ declare namespace browser.idle { /* idle types */ - type IdleState = - "active" - | "idle"; + type IdleState = "active" | "idle"; /* idle functions */ /** @@ -1756,14 +2095,10 @@ declare namespace browser.management { } /** A reason the item is disabled. */ - type ExtensionDisabledReason = - "unknown" - | "permissions_increase"; + type ExtensionDisabledReason = "unknown" | "permissions_increase"; - /** The type of this extension. Will always be 'extension'. */ - type ExtensionType = - "extension" - | "theme"; + /** The type of this extension, 'extension' or 'theme'. */ + type ExtensionType = "extension" | "theme"; /** * How the extension was installed. One of @@ -1773,7 +2108,7 @@ declare namespace browser.management { * `other`: The extension was installed by other means. */ type ExtensionInstallType = - "development" + "development" | "normal" | "sideload" | "other"; @@ -1798,7 +2133,7 @@ declare namespace browser.management { enabled: boolean; /** A reason the item is disabled. */ disabledReason?: ExtensionDisabledReason; - /** The type of this extension. Will always return 'extension'. */ + /** The type of this extension, 'extension' or 'theme'. */ type: ExtensionType; /** The URL of the homepage of this extension. */ homepageUrl?: string; @@ -1831,6 +2166,16 @@ declare namespace browser.management { */ function get(id: _manifest.ExtensionID): Promise; + /** Installs and enables a theme extension from the given url. */ + function install(options: { + /** URL pointing to the XPI file on addons.mozilla.org or similar. */ + url: _manifest.HttpURL; + /** A hash of the XPI file, using sha256 or stronger. */ + hash?: string; + }): Promise<{ + id: _manifest.ExtensionID; + } | undefined>; + /** * Returns information about the calling extension. Note: This function can be used without requesting the * 'management' permission in the manifest. @@ -1877,14 +2222,12 @@ declare namespace browser.management { declare namespace browser.notifications { /* notifications types */ type TemplateType = - "basic" + "basic" | "image" | "list" | "progress"; - type PermissionLevel = - "granted" - | "denied"; + type PermissionLevel = "granted" | "denied"; interface NotificationItem { /** Title of one item of a list notification. */ @@ -2111,10 +2454,9 @@ declare namespace browser.privacy { */ declare namespace browser.privacy.network { /* privacy.network types */ - /** The IP handling policy of WebRTC. */ type IPHandlingPolicy = - "default" + "default" | "default_public_and_private_interfaces" | "default_public_interface_only" | "disable_non_proxied_udp"; @@ -2163,13 +2505,27 @@ declare namespace browser.privacy.services { */ declare namespace browser.privacy.websites { /* privacy.websites types */ - /** The mode for tracking protection. */ type TrackingProtectionModeOption = - "always" + "always" | "never" | "private_browsing"; + /** The settings for cookies. */ + interface CookieConfig { + /** The type of cookies to allow. */ + behavior?: _CookieConfigBehavior; + /** Whether to create all cookies as nonPersistent (i.e., session) cookies. */ + nonPersistentCookies?: boolean; + } + + /** The type of cookies to allow. */ + type _CookieConfigBehavior = + "allow_all" + | "reject_all" + | "reject_third_party" + | "allow_visited"; + /* privacy.websites properties */ /** * If disabled, the browser blocks third-party sites from setting cookies. The value of this preference is of type @@ -2221,6 +2577,12 @@ declare namespace browser.privacy.websites { * TrackingProtectionModeOption, defaulting to `private_browsing_only`. */ const trackingProtectionMode: types.Setting; + + /** + * Allow users to specify the default settings for allowing cookies, as well as whether all cookies should be + * created as non-persistent cookies. This setting's value is of type CookieConfig. + */ + const cookieConfig: types.Setting; } /** @@ -2232,6 +2594,83 @@ declare namespace browser.privacy.websites { * Not allowed in: Content scripts, Devtools pages */ declare namespace browser.proxy { + /* proxy types */ + /** An object which describes proxy settings. */ + interface ProxyConfig { + /** The type of proxy to use. */ + proxyType?: _ProxyConfigProxyType; + /** The address of the http proxy, can include a port. */ + http?: string; + /** Use the http proxy server for all protocols. */ + httpProxyAll?: boolean; + /** The address of the ftp proxy, can include a port. */ + ftp?: string; + /** The address of the ssl proxy, can include a port. */ + ssl?: string; + /** The address of the socks proxy, can include a port. */ + socks?: string; + /** The version of the socks proxy. */ + socksVersion?: number; + /** A list of hosts which should not be proxied. */ + passthrough?: string; + /** A URL to use to configure the proxy. */ + autoConfigUrl?: string; + /** Do not prompt for authentication if password is saved. */ + autoLogin?: boolean; + /** Proxy DNS when using SOCKS v5. */ + proxyDNS?: boolean; + } + + /** The type of proxy to use. */ + type _ProxyConfigProxyType = + "none" + | "autoDetect" + | "system" + | "manual" + | "autoConfig"; + + type _ProxyOnRequestEvent void> = WebExtEventBase<(callback: T, filter: webRequest.RequestFilter, extraInfoSpec?: Array<"requestHeaders">) => void, T>; + + /* proxy properties */ + /** Configures proxy settings. This setting's value is an object of type ProxyConfig. */ + const settings: types.Setting; + /* proxy functions */ /** Registers the proxy script for the extension. */ function register(url: string): Promise; @@ -2246,7 +2685,13 @@ declare namespace browser.proxy { function registerProxyScript(url: string): Promise; /* proxy events */ + /** Fired when proxy data is needed for a request. */ + const onRequest: _ProxyOnRequestEvent; + /** Notifies about proxy script errors. */ + const onError: WebExtEvent<(error: object) => void>; + + /** Please use `proxy.onError`. */ const onProxyError: WebExtEvent<(error: object) => void>; } @@ -2262,10 +2707,10 @@ declare namespace browser.runtime { /** An object which allows two way communication with other pages. */ interface Port { name: string; - disconnect(): void; + disconnect: () => void; onDisconnect: events.Event; onMessage: events.Event; - postMessage(message: object): void; + postMessage: (message: object) => void; /** This property will **only** be present on ports passed to onConnect/onConnectExternal listeners. */ sender?: MessageSender; } @@ -2300,7 +2745,7 @@ declare namespace browser.runtime { /** The operating system the browser is running on. */ type PlatformOs = - "mac" + "mac" | "win" | "android" | "cros" @@ -2309,7 +2754,7 @@ declare namespace browser.runtime { /** The machine's processor architecture. */ type PlatformArch = - "arm" + "arm" | "x86-32" | "x86-64"; @@ -2340,13 +2785,13 @@ declare namespace browser.runtime { /** Result of the update check. */ type RequestUpdateCheckStatus = - "throttled" + "throttled" | "no_update" | "update_available"; /** The reason that this event is being dispatched. */ type OnInstalledReason = - "install" + "install" | "update" | "browser_update"; @@ -2357,7 +2802,7 @@ declare namespace browser.runtime { * the enterprise policy. */ type OnRestartRequiredReason = - "app_update" + "app_update" | "os_update" | "periodic"; @@ -2700,9 +3145,133 @@ declare namespace browser.storage { } /** - * The theme API allows customizing of visual elements of the browser. + * Use the `browser.telemetry` API to send telemetry data to the Mozilla Telemetry service. Restricted to Mozilla + * privileged webextensions. * - * Permissions: `theme` + * Permissions: `telemetry`, `mozillaAddons` + * + * Not allowed in: Content scripts, Devtools pages + */ +declare namespace browser.telemetry { + /* telemetry types */ + /** + * Type of scalar: 'count' for numeric values, 'string' for string values, 'boolean' for boolean values. Maps to + * `nsITelemetry.SCALAR_TYPE_*`. + */ + type ScalarType = + "count" + | "string" + | "boolean"; + + /** Represents registration data for a Telemetry scalar. */ + interface ScalarData { + kind: ScalarType; + /** True if this is a keyed scalar. */ + keyed?: boolean; + /** True if this data should be recorded on release. */ + record_on_release?: boolean; + /** + * True if this scalar entry is expired. This allows recording it without error, but it will be discarded. + */ + expired?: boolean; + } + + /** Represents registration data for a Telemetry event. */ + interface EventData { + /** List of methods for this event entry. */ + methods: string[]; + /** List of objects for this event entry. */ + objects: string[]; + /** List of allowed extra keys for this event entry. */ + extra_keys: string[]; + /** True if this data should be recorded on release. */ + record_on_release?: boolean; + /** + * True if this event entry is expired. This allows recording it without error, but it will be discarded. + */ + expired?: boolean; + } + + /* telemetry functions */ + /** + * Submits a custom ping to the Telemetry back-end. See `submitExternalPing` inside TelemetryController.jsm for + * more details. + * @param type The type of the ping. + * @param message The data payload for the ping. + * @param options Options object. + */ + function submitPing(type: string, message: any, options: { + /** True if the ping should contain the client id. */ + addClientId?: boolean; + /** True if the ping should contain the environment data. */ + addEnvironment?: boolean; + /** Set to override the environment data. */ + overrideEnvironment?: any; + /** If true, send the ping using the PingSender. */ + usePingSender?: boolean; + }): Promise; + + /** Checks if Telemetry is enabled. */ + function canUpload(): Promise; + + /** + * Adds the value to the given scalar. + * @param name The scalar name. + * @param value The numeric value to add to the scalar. Only unsigned integers supported. + */ + function scalarAdd(name: string, value: number): Promise; + + /** + * Sets the named scalar to the given value. Throws if the value type doesn't match the scalar type. + * @param name The scalar name + * @param value The value to set the scalar to + */ + function scalarSet(name: string, value: string | boolean | number | object): Promise; + + /** + * Sets the scalar to the maximum of the current and the passed value + * @param name The scalar name. + * @param value The numeric value to set the scalar to. Only unsigned integers supported. + */ + function scalarSetMaximum(name: string, value: number): Promise; + + /** + * Record an event in Telemetry. Throws when trying to record an unknown event. + * @param category The category name. + * @param method The method name. + * @param object The object name. + * @param [value] An optional string value to record. + * @param [extra] An optional object of the form (string -> string). It should only contain registered extra keys. + */ + function recordEvent(category: string, method: string, object: string, value?: number, extra?: string): Promise; + + /** + * Register new scalars to record them from addons. See nsITelemetry.idl for more details. + * @param category The unique category the scalars are registered in. + * @param data An object that contains registration data for multiple scalars. Each property name is the scalar + * name, and the corresponding property value is an object of ScalarData type. + */ + function registerScalars(category: string, data: ScalarData): Promise; + + /** + * Register new events to record them from addons. See nsITelemetry.idl for more details. + * @param category The unique category the events are registered in. + * @param data An object that contains registration data for 1+ events. Each property name is the category name, + * and the corresponding property value is an object of EventData type. + */ + function registerEvents(category: string, data: EventData): Promise; + + /** + * Enable recording of events in a category. Events default to recording disabled. This allows to toggle recording + * for all events in the specified category. + * @param category The category name. + * @param enabled Whether recording is enabled for events in that category. + */ + function setEventRecordingEnabled(category: string, enabled: boolean): Promise; +} + +/** + * The theme API allows customizing of visual elements of the browser. * * Not allowed in: Content scripts, Devtools pages */ @@ -2764,13 +3333,23 @@ declare namespace browser.topSites { url: string; /** The title of the page. */ title?: string; + /** Data URL for the favicon, if available. */ + favicon?: string; } /* topSites functions */ /** Gets a list of top sites. */ function get(options?: { - /** Which providers to get top sites from. Possible values are "places" and "activityStream". */ + /** @deprecated Please use the other options to tune the results received from topSites. */ providers?: string[]; + /** The number of top sites to return, defaults to the value used by Firefox */ + limit?: number; + /** Limit the result to a single top site link per domain */ + onePerDomain?: boolean; + /** Include sites that the user has blocked from appearing on the Firefox new tab. */ + includeBlocked?: boolean; + /** Include sites favicon if available. */ + includeFavicon?: boolean; }): Promise; } @@ -2781,7 +3360,6 @@ declare namespace browser.topSites { */ declare namespace browser.types { /* types types */ - /** * The scope of the Setting. One of * @@ -2796,7 +3374,7 @@ declare namespace browser.types { * Only `regular` is supported by Firefox at this time. */ type SettingScope = - "regular" + "regular" | "regular_only" | "incognito_persistent" | "incognito_session_only"; @@ -2810,7 +3388,7 @@ declare namespace browser.types { * * `controlled_by_this_extension`: controlled by this extension */ type LevelOfControl = - "not_controllable" + "not_controllable" | "controlled_by_other_extensions" | "controllable_by_this_extension" | "controlled_by_this_extension"; @@ -2887,14 +3465,13 @@ declare namespace browser.types { */ declare namespace browser.webNavigation { /* webNavigation types */ - /** * Cause of the navigation. The same transition types as defined in the history API are used. These are the same * transition types as defined in the history API except with `"start_page"` in place of `"auto_toplevel"` (for * backwards compatibility). */ type TransitionType = - "link" + "link" | "typed" | "auto_bookmark" | "auto_subframe" @@ -2907,7 +3484,7 @@ declare namespace browser.webNavigation { | "keyword_generated"; type TransitionQualifier = - "client_redirect" + "client_redirect" | "server_redirect" | "forward_back" | "from_address_bar"; @@ -3221,7 +3798,7 @@ declare namespace browser.webNavigation { declare namespace browser.webRequest { /* webRequest types */ type ResourceType = - "main_frame" + "main_frame" | "sub_frame" | "stylesheet" | "script" @@ -3240,24 +3817,19 @@ declare namespace browser.webRequest { | "csp_report" | "imageset" | "web_manifest" + | "speculative" | "other"; - type OnBeforeRequestOptions = - "blocking" - | "requestBody"; + type OnBeforeRequestOptions = "blocking" | "requestBody"; - type OnBeforeSendHeadersOptions = - "requestHeaders" - | "blocking"; + type OnBeforeSendHeadersOptions = "requestHeaders" | "blocking"; type OnSendHeadersOptions = "requestHeaders"; - type OnHeadersReceivedOptions = - "blocking" - | "responseHeaders"; + type OnHeadersReceivedOptions = "blocking" | "responseHeaders"; type OnAuthRequiredOptions = - "responseHeaders" + "responseHeaders" | "blocking" | "asyncBlocking"; @@ -3309,6 +3881,12 @@ declare namespace browser.webRequest { * redirect will be issued using the GET method. */ redirectUrl?: string; + /** + * Only used as a response to the onBeforeRequest event. If set, the original request is prevented from being + * sent/completed and is instead upgraded to a secure request. If any extension returns `redirectUrl` during + * onBeforeRequest, `upgradeToSecure` will have no affect. + */ + upgradeToSecure?: boolean; /** * Only used as a response to the onBeforeSendHeaders event. If set, the request is made with these request * headers instead. @@ -3330,6 +3908,75 @@ declare namespace browser.webRequest { }; } + /** Contains the certificate properties of the request if it is a secure request. */ + interface CertificateInfo { + subject: string; + issuer: string; + /** Contains start and end timestamps. */ + validity: { + start: number; + end: number; + }; + fingerprint: { + sha1: string; + sha256: string; + }; + serialNumber: string; + isBuiltInRoot: boolean; + subjectPublicKeyInfoDigest: { + sha256: string; + }; + rawDER?: number[]; + } + + type CertificateTransparencyStatus = + "not_applicable" + | "policy_compliant" + | "policy_not_enough_scts" + | "policy_not_diverse_scts"; + + type TransportWeaknessReasons = "cipher"; + + /** Contains the security properties of the request (ie. SSL/TLS information). */ + interface SecurityInfo { + state: _SecurityInfoState; + /** Error message if state is "broken" */ + errorMessage?: string; + /** Protocol version if state is "secure" */ + protocolVersion?: _SecurityInfoProtocolVersion; + /** The cipher suite used in this request if state is "secure". */ + cipherSuite?: string; + /** The key exchange algorithm used in this request if state is "secure". */ + keaGroupName?: string; + /** The signature scheme used in this request if state is "secure". */ + signatureSchemeName?: string; + /** + * Certificate data if state is "secure". Will only contain one entry unless `certificateChain` is passed as an + * option. + */ + certificates: CertificateInfo[]; + /** The domain name does not match the certificate domain. */ + isDomainMismatch?: boolean; + isExtendedValidation?: boolean; + /** + * The certificate is either expired or is not yet valid. See `CertificateInfo.validity` for start and end + * dates. + */ + isNotValidAtThisTime?: boolean; + isUntrusted?: boolean; + /** + * Certificate transparency compliance per RFC 6962\. See `https://www.certificate-transparency.org/what-is-ct` + * for more information. + */ + certificateTransparencyStatus?: CertificateTransparencyStatus; + /** True if host uses Strict Transport Security and state is "secure". */ + hsts?: boolean; + /** True if host uses Public Key Pinning and state is "secure". */ + hpkp?: string; + /** list of reasons that cause the request to be considered weak, if state is "weak" */ + weaknessReasons?: TransportWeaknessReasons[]; + } + /** Contains data uploaded in a URL request. */ interface UploadData { /** An ArrayBuffer with a copy of the data. */ @@ -3338,6 +3985,20 @@ declare namespace browser.webRequest { file?: string; } + type _SecurityInfoState = + "insecure" + | "weak" + | "broken" + | "secure"; + + /** Protocol version if state is "secure" */ + type _SecurityInfoProtocolVersion = + "TLSv1" + | "TLSv1.1" + | "TLSv1.2" + | "TLSv1.3" + | "unknown"; + type _WebRequestOnBeforeRequestEvent; + /* webRequest events */ /** * Fired when a request is about to occur. @@ -3798,7 +4469,6 @@ declare namespace browser.webRequest { */ declare namespace browser.bookmarks { /* bookmarks types */ - /** * Indicates the reason why this node is unmodifiable. The `managed` value indicates that this node was configured * by the system administrator or by the custodian of a supervised user. Omitted if the node can be modified by the @@ -3807,7 +4477,10 @@ declare namespace browser.bookmarks { type BookmarkTreeNodeUnmodifiable = "managed"; /** Indicates the type of a BookmarkTreeNode, which can be one of bookmark, folder or separator. */ - type BookmarkTreeNodeType = "bookmark" | "folder" | "separator"; + type BookmarkTreeNodeType = + "bookmark" + | "folder" + | "separator"; /** * A node (either a bookmark or a folder) in the bookmark tree. Child nodes are ordered within their parent folder. @@ -3958,19 +4631,6 @@ declare namespace browser.bookmarks { const onChildrenReordered: WebExtEvent<(id: string, reorderInfo: { childIds: string[]; }) => void> | undefined; - - /** - * Fired when a bookmark import session is begun. Expensive observers should ignore onCreated updates until - * onImportEnded is fired. Observers should still handle other notifications immediately. - * @deprecated Unsupported on Firefox at this time. - */ - const onImportBegan: WebExtEvent<() => void> | undefined; - - /** - * Fired when a bookmark import session is ended. - * @deprecated Unsupported on Firefox at this time. - */ - const onImportEnded: WebExtEvent<() => void> | undefined; } /** @@ -3983,32 +4643,66 @@ declare namespace browser.bookmarks { */ declare namespace browser.browserAction { /* browserAction types */ + /** + * Specifies to which tab or window the value should be set, or from which one it should be retrieved. If no tab + * nor window is specified, the global value is set or retrieved. + */ + interface Details { + /** + * When setting a value, it will be specific to the specified tab, and will automatically reset when the tab + * navigates. When getting, specifies the tab to get the value from; if there is no tab-specific value, the + * window one will be inherited. + */ + tabId?: number; + /** + * When setting a value, it will be specific to the specified window. When getting, specifies the window to get + * the value from; if there is no window-specific value, the global one will be inherited. + */ + windowId?: number; + } + type ColorArray = [number, number, number, number]; /** Pixel data for an image. Must be an ImageData object (for example, from a `canvas` element). */ type ImageDataType = object/*ImageData*/; + /** + * An array of four integers in the range [0,255] that make up the RGBA color of the badge. For example, opaque red + * is `[255, 0, 0, 255]`. Can also be a string with a CSS value, with opaque red being `#FF0000` or `#F00`. + */ + type ColorValue = string | ColorArray | null; + /* browserAction functions */ - /** Sets the title of the browser action. This shows up in the tooltip. */ + /** + * Sets the title of the browser action. This shows up in the tooltip. + * @param details Specifies to which tab or window the value should be set, or from which one it should be + * retrieved. If no tab nor window is specified, the global value is set or retrieved. + */ function setTitle(details: { /** The string the browser action should display when moused over. */ - title: string; - /** Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */ + title: string | null; + /** + * When setting a value, it will be specific to the specified tab, and will automatically reset when the tab + * navigates. When getting, specifies the tab to get the value from; if there is no tab-specific value, the + * window one will be inherited. + */ tabId?: number; + /** + * When setting a value, it will be specific to the specified window. When getting, specifies the window to get + * the value from; if there is no window-specific value, the global one will be inherited. + */ + windowId?: number; }): Promise; /** Gets the title of the browser action. */ - function getTitle(details: { - /** - * Specify the tab to get the title from. If no tab is specified, the non-tab-specific title is returned. - */ - tabId?: number; - }): Promise; + function getTitle(details: Details): Promise; /** * Sets the icon for the browser action. The icon can be specified either as the path to an image file or as the * pixel data from a canvas element, or as dictionary of either one of those. Either the **path** or the * **imageData** property must be specified. + * @param details Specifies to which tab or window the value should be set, or from which one it should be + * retrieved. If no tab nor window is specified, the global value is set or retrieved. */ function setIcon(details: { /** @@ -4031,64 +4725,115 @@ declare namespace browser.browserAction { path?: string | { [key: number]: string; }; - /** Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */ - tabId?: number; - }): Promise; - - /** Sets the html document to be opened as a popup when the user clicks on the browser action's icon. */ - function setPopup(details: { - /** Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */ - tabId?: number; - /** The html file to show in a popup. If set to the empty string (''), no popup is shown. */ - popup: string; - }): Promise; - - /** Gets the html document set as the popup for this browser action. */ - function getPopup(details: { /** - * Specify the tab to get the popup from. If no tab is specified, the non-tab-specific popup is returned. + * When setting a value, it will be specific to the specified tab, and will automatically reset when the tab + * navigates. When getting, specifies the tab to get the value from; if there is no tab-specific value, the + * window one will be inherited. */ tabId?: number; - }): Promise; - - /** Sets the badge text for the browser action. The badge is displayed on top of the icon. */ - function setBadgeText(details: { - /** Any number of characters can be passed, but only about four can fit in the space. */ - text: string; - /** Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */ - tabId?: number; + /** + * When setting a value, it will be specific to the specified window. When getting, specifies the window to get + * the value from; if there is no window-specific value, the global one will be inherited. + */ + windowId?: number; }): Promise; /** - * Gets the badge text of the browser action. If no tab is specified, the non-tab-specific badge text is returned. + * Sets the html document to be opened as a popup when the user clicks on the browser action's icon. + * @param details Specifies to which tab or window the value should be set, or from which one it should be + * retrieved. If no tab nor window is specified, the global value is set or retrieved. */ - function getBadgeText(details: { + function setPopup(details: { + /** The html file to show in a popup. If set to the empty string (''), no popup is shown. */ + popup: string | null; /** - * Specify the tab to get the badge text from. If no tab is specified, the non-tab-specific badge text is - * returned. + * When setting a value, it will be specific to the specified tab, and will automatically reset when the tab + * navigates. When getting, specifies the tab to get the value from; if there is no tab-specific value, the + * window one will be inherited. */ tabId?: number; - }): Promise; - - /** Sets the background color for the badge. */ - function setBadgeBackgroundColor(details: { /** - * An array of four integers in the range [0,255] that make up the RGBA color of the badge. For example, opaque - * red is `[255, 0, 0, 255]`. Can also be a string with a CSS value, with opaque red being `#FF0000` or `#F00`. + * When setting a value, it will be specific to the specified window. When getting, specifies the window to get + * the value from; if there is no window-specific value, the global one will be inherited. */ - color: string | ColorArray; - /** Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */ - tabId?: number; + windowId?: number; }): Promise; - /** Gets the background color of the browser action. */ - function getBadgeBackgroundColor(details: { + /** Gets the html document set as the popup for this browser action. */ + function getPopup(details: Details): Promise; + + /** + * Sets the badge text for the browser action. The badge is displayed on top of the icon. + * @param details Specifies to which tab or window the value should be set, or from which one it should be + * retrieved. If no tab nor window is specified, the global value is set or retrieved. + */ + function setBadgeText(details: { + /** Any number of characters can be passed, but only about four can fit in the space. */ + text: string | null; /** - * Specify the tab to get the badge background color from. If no tab is specified, the non-tab-specific badge - * background color is returned. + * When setting a value, it will be specific to the specified tab, and will automatically reset when the tab + * navigates. When getting, specifies the tab to get the value from; if there is no tab-specific value, the + * window one will be inherited. */ tabId?: number; - }): Promise; + /** + * When setting a value, it will be specific to the specified window. When getting, specifies the window to get + * the value from; if there is no window-specific value, the global one will be inherited. + */ + windowId?: number; + }): Promise; + + /** + * Gets the badge text of the browser action. If no tab nor window is specified is specified, the global badge text + * is returned. + */ + function getBadgeText(details: Details): Promise; + + /** + * Sets the background color for the badge. + * @param details Specifies to which tab or window the value should be set, or from which one it should be + * retrieved. If no tab nor window is specified, the global value is set or retrieved. + */ + function setBadgeBackgroundColor(details: { + color: ColorValue; + /** + * When setting a value, it will be specific to the specified tab, and will automatically reset when the tab + * navigates. When getting, specifies the tab to get the value from; if there is no tab-specific value, the + * window one will be inherited. + */ + tabId?: number; + /** + * When setting a value, it will be specific to the specified window. When getting, specifies the window to get + * the value from; if there is no window-specific value, the global one will be inherited. + */ + windowId?: number; + }): Promise; + + /** Gets the background color of the browser action badge. */ + function getBadgeBackgroundColor(details: Details): Promise; + + /** + * Sets the text color for the badge. + * @param details Specifies to which tab or window the value should be set, or from which one it should be + * retrieved. If no tab nor window is specified, the global value is set or retrieved. + */ + function setBadgeTextColor(details: { + color: ColorValue; + /** + * When setting a value, it will be specific to the specified tab, and will automatically reset when the tab + * navigates. When getting, specifies the tab to get the value from; if there is no tab-specific value, the + * window one will be inherited. + */ + tabId?: number; + /** + * When setting a value, it will be specific to the specified window. When getting, specifies the window to get + * the value from; if there is no window-specific value, the global one will be inherited. + */ + windowId?: number; + }): Promise; + + /** Gets the text color of the browser action badge. */ + function getBadgeTextColor(details: Details): Promise; /** * Enables the browser action for a tab. By default, browser actions are enabled. @@ -4102,6 +4847,9 @@ declare namespace browser.browserAction { */ function disable(tabId?: number): Promise; + /** Checks whether the browser action is enabled. */ + function isEnabled(details: Details): Promise; + /** Opens the extension popup window in the active window. */ function openPopup(): Promise; @@ -4270,6 +5018,24 @@ declare namespace browser.commands { } /* commands functions */ + /** + * Update the details of an already defined command. + * @param detail The new description for the command. + */ + function update(detail: { + /** The name of the command. */ + name: string; + /** The new description for the command. */ + description?: string; + shortcut?: _manifest.KeyName; + }): Promise; + + /** + * Reset a command's details to what is specified in the manifest. + * @param name The name of the command. + */ + function reset(name: string): Promise; + /** Returns all the registered extension commands for this extension and their shortcut (if active). */ function getAll(): Promise; @@ -4279,7 +5045,7 @@ declare namespace browser.commands { } /** - * Permissions: `devtools` + * Manifest keys: `devtools_page` * * Allowed in: Devtools pages only */ @@ -4425,19 +5191,15 @@ declare namespace browser.devtools.network { } /* devtools.network functions */ - /** - * Returns HAR log that contains all known network requests. - * @deprecated Unsupported on Firefox at this time. - */ + /** Returns HAR log that contains all known network requests. */ function getHAR(): Promise; /* devtools.network events */ /** * Fired when a network request is finished and all request data are available. * @param request Description of a network request in the form of a HAR entry. See HAR specification for details. - * @deprecated Unsupported on Firefox at this time. */ - const onRequestFinished: WebExtEvent<(request: Request) => void> | undefined; + const onRequestFinished: WebExtEvent<(request: Request) => void>; /** * Fired when the inspected window navigates to a new page. @@ -4575,6 +5337,8 @@ declare namespace browser.devtools.panels { onClicked: WebExtEvent<() => void>; } + type _Create = ""; + /* devtools.panels properties */ /** Elements panel. */ const elements: ElementsPanel; @@ -4589,10 +5353,11 @@ declare namespace browser.devtools.panels { /** * Creates an extension panel. * @param title Title that is displayed next to the extension icon in the Developer Tools toolbar. - * @param iconPath Path of the panel's icon relative to the extension directory. + * @param iconPath Path of the panel's icon relative to the extension directory, or an empty string to use the + * default extension icon as the panel icon. * @param pagePath Path of the panel's HTML page relative to the extension directory. */ - function create(title: string, iconPath: string, pagePath: string): Promise; + function create(title: string, iconPath: _manifest.ExtensionURL | _Create, pagePath: _manifest.ExtensionURL): Promise; /** * Specifies the function to be called when the user clicks a resource link in the Developer Tools window. To unset @@ -4695,16 +5460,19 @@ declare namespace browser.find { declare namespace browser.geckoProfiler { /* geckoProfiler types */ type ProfilerFeature = - "java" + "java" | "js" | "leaf" | "mainthreadio" | "memory" | "privacy" - | "restyle" + | "responsiveness" + | "screenshots" + | "seqstyle" | "stackwalk" | "tasktracer" - | "threads"; + | "threads" + | "trackopts"; /* geckoProfiler functions */ /** Starts the profiler with the specified settings. */ @@ -4768,10 +5536,9 @@ declare namespace browser.geckoProfiler { */ declare namespace browser.history { /* history types */ - /** The transition type for this visit from its referrer. */ type TransitionType = - "link" + "link" | "typed" | "auto_bookmark" | "auto_subframe" @@ -4902,18 +5669,15 @@ declare namespace browser.history { * your context menu additions apply to, such as images, hyperlinks, and pages. * * Permissions: `contextMenus` - * - * Not allowed in: Content scripts, Devtools pages */ declare namespace browser.contextMenus { /* contextMenus types */ - /** * The different contexts a menu can appear in. Specifying 'all' is equivalent to the combination of all other * contexts except for 'tab' and 'tools_menu'. */ type ContextType = - "all" + "all" | "page" | "frame" | "selection" @@ -4924,13 +5688,14 @@ declare namespace browser.contextMenus { | "video" | "audio" | "launcher" + | "bookmark" | "browser_action" | "page_action" | "tab"; /** The type of menu item. */ type ItemType = - "normal" + "normal" | "checkbox" | "radio" | "separator"; @@ -4966,12 +5731,19 @@ declare namespace browser.contextMenus { wasChecked?: boolean; /** A flag indicating the state of a checkbox or radio item after it is clicked. */ checked?: boolean; + /** The id of the bookmark where the context menu was clicked, if it was on a bookmark. */ + bookmarkId: string; /** An array of keyboard modifiers that were held while the menu item was clicked. */ modifiers: _OnClickDataModifiers[]; + /** + * An identifier of the clicked element, if any. Use menus.getTargetElement in the page to find the + * corresponding element. + */ + targetElementId?: number; } type _OnClickDataModifiers = - "Shift" + "Shift" | "Alt" | "Command" | "Ctrl" @@ -5017,6 +5789,8 @@ declare namespace browser.contextMenus { checked?: boolean; /** List of contexts this menu item will appear in. Defaults to ['page'] if not specified. */ contexts?: ContextType[]; + /** Whether the item is visible in the menu. */ + visible?: boolean; /** * A function that will be called back when the menu item is clicked. Event pages cannot use this; instead, * they should register a listener for `contextMenus.onClicked`. @@ -5024,7 +5798,7 @@ declare namespace browser.contextMenus { * @param tab The details of the tab where the click took place. Note: this parameter only present for * extensions. */ - onclick?: (info: menusInternal.OnClickData, tab: tabs.Tab) => void; + onclick?: (info: OnClickData, tab: tabs.Tab) => void; /** The ID of a parent menu item; this makes the item a child of a previously added item. */ parentId?: number | string; /** @@ -5056,11 +5830,13 @@ declare namespace browser.contextMenus { title?: string; checked?: boolean; contexts?: ContextType[]; + /** Whether the item is visible in the menu. */ + visible?: boolean; /** * @param tab The details of the tab where the click took place. Note: this parameter only present for * extensions. */ - onclick?: (info: menusInternal.OnClickData, tab: tabs.Tab) => void; + onclick?: (info: OnClickData, tab: tabs.Tab) => void; /** Note: You cannot change an item to be a child of one of its own descendants. */ parentId?: number | string; documentUrlPatterns?: string[]; @@ -5077,6 +5853,20 @@ declare namespace browser.contextMenus { /** Removes all context menu items added by this extension. */ function removeAll(): Promise; + /** + * Updates the extension items in the shown menu, including changes that have been made since the menu was shown. + * Has no effect if the menu is hidden. Rebuilding a shown menu is an expensive operation, only invoke this method + * when necessary. + */ + function refresh(): Promise; + + /** + * Retrieve the element that was associated with a recent contextmenu event. + * @param targetElementId The identifier of the clicked element, available as info.targetElementId in the + * menus.onShown, onClicked or onclick event. + */ + function getTargetElement(targetElementId: number): object/*Element*/ | void; + /* contextMenus events */ /** * Fired when a context menu item is clicked. @@ -5085,25 +5875,49 @@ declare namespace browser.contextMenus { * parameter will be missing. */ const onClicked: WebExtEvent<(info: OnClickData, tab?: tabs.Tab) => void>; + + /** + * Fired when a menu is shown. The extension can add, modify or remove menu items and call menus.refresh() to + * update the menu. + * @param info Information about the context of the menu action and the created menu items. For more information + * about each property, see OnClickData. The following properties are only set if the extension has host + * permissions for the given context: linkUrl, linkText, srcUrl, pageUrl, frameUrl, selectionText. + * @param tab The details of the tab where the menu was opened. + */ + const onShown: WebExtEvent<(info: { + /** A list of IDs of the menu items that were shown. */ + menuIds: number | string[]; + /** A list of all contexts that apply to the menu. */ + contexts: ContextType[]; + editable: boolean; + mediaType: string; + linkUrl?: string; + linkText?: string; + srcUrl?: string; + pageUrl?: string; + frameUrl?: string; + selectionText?: string; + targetElementId?: number; + }, tab: tabs.Tab) => void>; + + /** Fired when a menu is hidden. This event is only fired if onShown has fired before. */ + const onHidden: WebExtEvent<() => void>; } /** * Use the browser.menus API to add items to the browser's menus. You can choose what types of objects your context * menu additions apply to, such as images, hyperlinks, and pages. * - * Permissions: `menus` - * - * Not allowed in: Content scripts, Devtools pages + * Permissions: `menus`, `menus` */ declare namespace browser.menus { /* menus types */ - /** * The different contexts a menu can appear in. Specifying 'all' is equivalent to the combination of all other * contexts except for 'tab' and 'tools_menu'. */ type ContextType = - "all" + "all" | "page" | "frame" | "selection" @@ -5114,6 +5928,7 @@ declare namespace browser.menus { | "video" | "audio" | "launcher" + | "bookmark" | "browser_action" | "page_action" | "tab" @@ -5121,7 +5936,7 @@ declare namespace browser.menus { /** The type of menu item. */ type ItemType = - "normal" + "normal" | "checkbox" | "radio" | "separator"; @@ -5157,12 +5972,19 @@ declare namespace browser.menus { wasChecked?: boolean; /** A flag indicating the state of a checkbox or radio item after it is clicked. */ checked?: boolean; + /** The id of the bookmark where the context menu was clicked, if it was on a bookmark. */ + bookmarkId: string; /** An array of keyboard modifiers that were held while the menu item was clicked. */ modifiers: _OnClickDataModifiers[]; + /** + * An identifier of the clicked element, if any. Use menus.getTargetElement in the page to find the + * corresponding element. + */ + targetElementId?: number; } type _OnClickDataModifiers = - "Shift" + "Shift" | "Alt" | "Command" | "Ctrl" @@ -5208,6 +6030,8 @@ declare namespace browser.menus { checked?: boolean; /** List of contexts this menu item will appear in. Defaults to ['page'] if not specified. */ contexts?: ContextType[]; + /** Whether the item is visible in the menu. */ + visible?: boolean; /** * A function that will be called back when the menu item is clicked. Event pages cannot use this; instead, * they should register a listener for `contextMenus.onClicked`. @@ -5215,7 +6039,7 @@ declare namespace browser.menus { * @param tab The details of the tab where the click took place. Note: this parameter only present for * extensions. */ - onclick?: (info: menusInternal.OnClickData, tab: tabs.Tab) => void; + onclick?: (info: OnClickData, tab: tabs.Tab) => void; /** The ID of a parent menu item; this makes the item a child of a previously added item. */ parentId?: number | string; /** @@ -5247,11 +6071,13 @@ declare namespace browser.menus { title?: string; checked?: boolean; contexts?: ContextType[]; + /** Whether the item is visible in the menu. */ + visible?: boolean; /** * @param tab The details of the tab where the click took place. Note: this parameter only present for * extensions. */ - onclick?: (info: menusInternal.OnClickData, tab: tabs.Tab) => void; + onclick?: (info: OnClickData, tab: tabs.Tab) => void; /** Note: You cannot change an item to be a child of one of its own descendants. */ parentId?: number | string; documentUrlPatterns?: string[]; @@ -5268,6 +6094,20 @@ declare namespace browser.menus { /** Removes all context menu items added by this extension. */ function removeAll(): Promise; + /** + * Updates the extension items in the shown menu, including changes that have been made since the menu was shown. + * Has no effect if the menu is hidden. Rebuilding a shown menu is an expensive operation, only invoke this method + * when necessary. + */ + function refresh(): Promise; + + /** + * Retrieve the element that was associated with a recent contextmenu event. + * @param targetElementId The identifier of the clicked element, available as info.targetElementId in the + * menus.onShown, onClicked or onclick event. + */ + function getTargetElement(targetElementId: number): object/*Element*/ | void; + /* menus events */ /** * Fired when a context menu item is clicked. @@ -5276,46 +6116,33 @@ declare namespace browser.menus { * parameter will be missing. */ const onClicked: WebExtEvent<(info: OnClickData, tab?: tabs.Tab) => void>; -} -/** - * Use the `browser.contextMenus` API to add items to the browser's context menu. You can choose what types of objects - * your context menu additions apply to, such as images, hyperlinks, and pages. - * - * Not allowed in: Content scripts, Devtools pages - */ -declare namespace browser.menusInternal { - /* menusInternal types */ - /** Information sent when a context menu item is clicked. */ - interface OnClickData { - /** The ID of the menu item that was clicked. */ - menuItemId: number | string; - /** The parent ID, if any, for the item clicked. */ - parentMenuItemId?: number | string; - /** - * One of 'image', 'video', or 'audio' if the context menu was activated on one of these types of elements. - */ - mediaType?: string; - /** If the element is a link, the URL it points to. */ - linkUrl?: string; - /** Will be present for elements with a 'src' URL. */ - srcUrl?: string; - /** - * The URL of the page where the menu item was clicked. This property is not set if the click occured in a - * context where there is no current page, such as in a launcher context menu. - */ - pageUrl?: string; - /** The URL of the frame of the element where the context menu was clicked, if it was in a frame. */ - frameUrl?: string; - /** The text for the context selection, if any. */ - selectionText?: string; - /** A flag indicating whether the element is editable (text input, textarea, etc.). */ + /** + * Fired when a menu is shown. The extension can add, modify or remove menu items and call menus.refresh() to + * update the menu. + * @param info Information about the context of the menu action and the created menu items. For more information + * about each property, see OnClickData. The following properties are only set if the extension has host + * permissions for the given context: linkUrl, linkText, srcUrl, pageUrl, frameUrl, selectionText. + * @param tab The details of the tab where the menu was opened. + */ + const onShown: WebExtEvent<(info: { + /** A list of IDs of the menu items that were shown. */ + menuIds: number | string[]; + /** A list of all contexts that apply to the menu. */ + contexts: ContextType[]; editable: boolean; - /** A flag indicating the state of a checkbox or radio item before it was clicked. */ - wasChecked?: boolean; - /** A flag indicating the state of a checkbox or radio item after it is clicked. */ - checked?: boolean; - } + mediaType: string; + linkUrl?: string; + linkText?: string; + srcUrl?: string; + pageUrl?: string; + frameUrl?: string; + selectionText?: string; + targetElementId?: number; + }, tab: tabs.Tab) => void>; + + /** Fired when a menu is hidden. This event is only fired if onShown has fired before. */ + const onHidden: WebExtEvent<() => void>; } /** @@ -5327,10 +6154,9 @@ declare namespace browser.menusInternal { */ declare namespace browser.omnibox { /* omnibox types */ - /** The style type. */ type DescriptionStyleType = - "url" + "url" | "match" | "dim"; @@ -5340,7 +6166,7 @@ declare namespace browser.omnibox { * should take place in a new selected tab. */ type OnInputEnteredDisposition = - "currentTab" + "currentTab" | "newForegroundTab" | "newBackgroundTab"; @@ -5455,12 +6281,18 @@ declare namespace browser.pageAction { */ function hide(tabId: number): Promise; + /** Checks whether the page action is shown. */ + function isShown(details: { + /** Specify the tab to get the shownness from. */ + tabId: number; + }): Promise; + /** Sets the title of the page action. This is displayed in a tooltip over the page action. */ function setTitle(details: { /** The id of the tab for which you want to modify the page action. */ tabId: number; /** The tooltip string. */ - title: string; + title: string | null; }): void; /** Gets the title of the page action. */ @@ -5504,7 +6336,7 @@ declare namespace browser.pageAction { /** The id of the tab for which you want to modify the page action. */ tabId: number; /** The html file to show in a popup. If set to the empty string (''), no popup is shown. */ - popup: string; + popup: string | null; }): void; /** Gets the html document set as the popup for this page action. */ @@ -5553,6 +6385,38 @@ declare namespace browser.pkcs11 { }>; } +/** + * Use browser.search to interact with search engines. + * + * Permissions: `search` + * + * Not allowed in: Content scripts, Devtools pages + */ +declare namespace browser.search { + /* search types */ + /** An object encapsulating a search engine */ + interface SearchEngine { + name: string; + isDefault: boolean; + alias?: string; + favIconUrl?: string; + } + + /* search functions */ + /** Gets a list of search engines. */ + function get(): Promise; + + /** Perform a search. */ + function search(searchProperties: { + /** Terms to search for. */ + query: string; + /** Search engine to use. Uses the default if not specified. */ + engine?: string; + /** The ID of the tab for the search results. If not specified, a new tab is created. */ + tabId?: number; + }): Promise; +} + /** * Use the `browser.sessions` API to query and restore tabs and windows from a browsing session. * @@ -5695,17 +6559,23 @@ declare namespace browser.sidebarAction { /** Sets the title of the sidebar action. This shows up in the tooltip. */ function setTitle(details: { /** The string the sidebar action should display when moused over. */ - title: string; + title: string | null; /** Sets the sidebar title for the tab specified by tabId. Automatically resets when the tab is closed. */ tabId?: number; + /** Sets the sidebar title for the window specified by windowId. */ + windowId?: number; }): Promise; /** Gets the title of the sidebar action. */ function getTitle(details: { /** - * Specify the tab to get the title from. If no tab is specified, the non-tab-specific title is returned. + * Specify the tab to get the title from. If no tab nor window is specified, the global title is returned. */ tabId?: number; + /** + * Specify the window to get the title from. If no tab nor window is specified, the global title is returned. + */ + windowId?: number; }): Promise; /** @@ -5734,6 +6604,8 @@ declare namespace browser.sidebarAction { path?: string; /** Sets the sidebar icon for the tab specified by tabId. Automatically resets when the tab is closed. */ tabId?: number; + /** Sets the sidebar icon for the window specified by windowId. */ + windowId?: number; }): Promise; /** @@ -5742,16 +6614,22 @@ declare namespace browser.sidebarAction { function setPanel(details: { /** Sets the sidebar url for the tab specified by tabId. Automatically resets when the tab is closed. */ tabId?: number; + /** Sets the sidebar url for the window specified by windowId. */ + windowId?: number; /** The url to the html file to show in a sidebar. If set to the empty string (''), no sidebar is shown. */ - panel: string; + panel: string | null; }): Promise; /** Gets the url to the html document set as the panel for this sidebar action. */ function getPanel(details: { /** - * Specify the tab to get the sidebar from. If no tab is specified, the non-tab-specific sidebar is returned. + * Specify the tab to get the panel from. If no tab nor window is specified, the global panel is returned. */ tabId?: number; + /** + * Specify the window to get the panel from. If no tab nor window is specified, the global panel is returned. + */ + windowId?: number; }): Promise; /** Opens the extension sidebar in the active window. */ @@ -5759,6 +6637,12 @@ declare namespace browser.sidebarAction { /** Closes the extension sidebar in the active window if the sidebar belongs to the extension. */ function close(): Promise; + + /** Checks whether the sidebar action is open. */ + function isOpen(details: { + /** Specify the window to get the openness from. */ + windowId?: number; + }): Promise; } /** @@ -5769,14 +6653,13 @@ declare namespace browser.sidebarAction { */ declare namespace browser.tabs { /* tabs types */ - /** An event that caused a muted state change. */ type MutedInfoReason = /** A user input action has set/overridden the muted state. */ - "user" -/** Tab capture started, forcing a muted state change. */ + "user" + /** Tab capture started, forcing a muted state change. */ | "capture" -/** An extension, identified by the extensionId field, set the muted state. */ + /** An extension, identified by the extensionId field, set the muted state. */ | "extension"; /** Tab muted state and the reason for the last state change. */ @@ -5795,6 +6678,19 @@ declare namespace browser.tabs { extensionId?: string; } + /** Tab sharing state for screen, microphone and camera. */ + interface SharingState { + /** + * If the tab is sharing the screen the value will be one of "Screen", "Window", or "Application", or undefined + * if not screen sharing. + */ + screen?: string; + /** True if the tab is using the camera. */ + camera: boolean; + /** True if the tab is using the microphone. */ + microphone: boolean; + } + interface Tab { /** * The ID of the tab. Tab IDs are unique within a browser session. Under some circumstances a Tab may not be @@ -5855,6 +6751,8 @@ declare namespace browser.tabs { width?: number; /** The height of the tab in pixels. */ height?: number; + /** True if the tab is hidden. */ + hidden?: boolean; /** The session ID used to uniquely identify a Tab obtained from the `sessions` API. */ sessionId?: string; /** The CookieStoreId used for the tab. */ @@ -5863,6 +6761,10 @@ declare namespace browser.tabs { isArticle?: boolean; /** Whether the document in the tab is being rendered in reader mode. */ isInReaderMode?: boolean; + /** Current tab sharing state for screen, microphone and camera. */ + sharingState?: SharingState; + /** Whether the tab is drawing attention. */ + attention?: boolean; } /** @@ -5871,7 +6773,7 @@ declare namespace browser.tabs { */ type ZoomSettingsMode = /** Zoom changes are handled automatically by the browser. */ - "automatic" + "automatic" /** * Overrides the automatic handling of zoom changes. The `onZoomChange` event will still be dispatched, and it * is the responsibility of the extension to listen for this event and manually scale the page. This mode does @@ -5895,7 +6797,7 @@ declare namespace browser.tabs { * navigating to other pages in the same origin, they will all be zoomed to the same zoom factor. The * `per-origin` scope is only available in the `automatic` mode. */ - | "per-origin" + "per-origin" /** * Zoom changes only take effect in this tab, and zoom changes in other tabs will not affect the zooming of * this tab. Also, `per-tab` zoom changes are reset on navigation; navigating a tab will always load pages with @@ -5921,6 +6823,12 @@ declare namespace browser.tabs { /** The page settings including: orientation, scale, background, margins, headers, footers. */ interface PageSettings { + /** The page size unit: 0 = inches, 1 = millimeters. Default: 0. */ + paperSizeUnit?: number; + /** The paper width in paper size units. Default: 8.5. */ + paperWidth?: number; + /** The paper height in paper size units. Default: 11.0. */ + paperHeight?: number; /** The page content orientation: 0 = portrait, 1 = landscape. Default: 0. */ orientation?: number; /** The page content scaling factor: 1.0 = 100% = normal size. Default: 1.0. */ @@ -5931,12 +6839,22 @@ declare namespace browser.tabs { showBackgroundColors?: boolean; /** Whether the page background images should be shown. Default: false. */ showBackgroundImages?: boolean; - /** The page size unit: 0 = inches, 1 = millimeters. Default: 0. */ - paperSizeUnit?: number; - /** The paper width in paper size units. Default: 8.5. */ - paperWidth?: number; - /** The paper height in paper size units. Default: 11.0. */ - paperHeight?: number; + /** The spacing between the left header/footer and the left edge of the paper (inches). Default: 0. */ + edgeLeft?: number; + /** The spacing between the right header/footer and the right edge of the paper (inches). Default: 0. */ + edgeRight?: number; + /** The spacing between the top of the headers and the top edge of the paper (inches). Default: 0 */ + edgeTop?: number; + /** The spacing between the bottom of the footers and the bottom edge of the paper (inches). Default: 0. */ + edgeBottom?: number; + /** The margin between the page content and the left edge of the paper (inches). Default: 0.5. */ + marginLeft?: number; + /** The margin between the page content and the right edge of the paper (inches). Default: 0.5. */ + marginRight?: number; + /** The margin between the page content and the top edge of the paper (inches). Default: 0.5. */ + marginTop?: number; + /** The margin between the page content and the bottom edge of the paper (inches). Default: 0.5. */ + marginBottom?: number; /** The text for the page's left header. Default: '&T'. */ headerLeft?: string; /** The text for the page's center header. Default: ''. */ @@ -5949,29 +6867,88 @@ declare namespace browser.tabs { footerCenter?: string; /** The text for the page's right footer. Default: '&D'. */ footerRight?: string; - /** The margin between the page content and the left edge of the paper (inches). Default: 0.5. */ - marginLeft?: number; - /** The margin between the page content and the right edge of the paper (inches). Default: 0.5. */ - marginRight?: number; - /** The margin between the page content and the top edge of the paper (inches). Default: 0.5. */ - marginTop?: number; - /** The margin between the page content and the bottom edge of the paper (inches). Default: 0.5. */ - marginBottom?: number; } /** Whether the tabs have completed loading. */ - type TabStatus = - "loading" - | "complete"; + type TabStatus = "loading" | "complete"; /** The type of window. */ type WindowType = - "normal" + "normal" | "popup" | "panel" | "app" | "devtools"; + /** Event names supported in onUpdated. */ + type UpdatePropertyName = + "attention" + | "audible" + | "discarded" + | "favIconUrl" + | "hidden" + | "isarticle" + | "isArticle" + | "mutedInfo" + | "pinned" + | "sharingState" + | "status" + | "title"; + + /** An object describing filters to apply to tabs.onUpdated events. */ + interface UpdateFilter { + /** + * A list of URLs or URL patterns. Events that cannot match any of the URLs will be filtered out. Filtering + * with urls requires the `"tabs"` or `"activeTab"` permission. + */ + urls?: string[]; + /** A list of property names. Events that do not match any of the names will be filtered out. */ + properties?: UpdatePropertyName[]; + tabId?: number; + windowId?: number; + } + + type _QueryScreen = + "Screen" + | "Window" + | "Application"; + + type _TabsOnUpdatedEvent