@types/firefox-webext-browser/index.d.ts

TypeScript definitions for firefox-webext-browser

interface WebExtEvent<TCallback extends (...args: any[]) => any> {
    addListener(cb: TCallback): void;
    removeListener(cb: TCallback): void;
    hasListener(cb: TCallback): boolean;
}

/** Not allowed in: Content scripts, Devtools pages */
declare namespace browser._manifest {
    /* _manifest types */
    type PermissionPrivileged = _PermissionPrivileged;

    interface ActionManifest {
        default_title?: string | undefined;
        default_icon?: IconPath | undefined;
        /** Specifies icons to use for dark and light themes */
        theme_icons?: ThemeIcons[] | undefined;
        default_popup?: string | undefined;
        /** Deprecated in Manifest V3. */
        browser_style?: boolean | undefined;
        /** Defines the location the browserAction will appear by default. The default location is navbar. */
        default_area?: _ActionManifestDefaultArea | undefined;
    }

    /** Represents a WebExtension manifest.json file */
    interface WebExtensionManifest extends ManifestBase {
        /** Needs at least manifest version 3. */
        action?: ActionManifest | undefined;
        /** Not supported on manifest versions above 2. */
        browser_action?: ActionManifest | undefined;
        declarative_net_request?: _WebExtensionManifestDeclarativeNetRequest | undefined;
        experiment_apis?: { [key: string]: experiments.ExperimentAPI } | undefined;
        /** A list of protocol handler definitions. */
        protocol_handlers?: ProtocolHandler[] | undefined;
        default_locale?: string | undefined;
        l10n_resources?: string[] | undefined;
        minimum_chrome_version?: string | undefined;
        minimum_opera_version?: string | undefined;
        icons?: _WebExtensionManifestIcons | undefined;
        /** The 'split' value is not supported. */
        incognito?: _WebExtensionManifestIncognito | undefined;
        background?: {
            service_worker?: ExtensionURL | undefined;
            page?: ExtensionURL | undefined;
            scripts?: ExtensionURL[] | undefined;
            /** Only supported for page/scripts; not for service_worker yet, see bug 1775574 */
            type?: _UndefinedType | undefined;
            /** Not supported on manifest versions above 2. */
            persistent?: boolean | undefined;
            preferred_environment?: _PreferredEnvironment[] | undefined;
        } | undefined;
        /** Alias property for options_ui.page, ignored when options_ui.page is set. When using this property the options page is always opened in a new tab. */
        options_page?: ExtensionURL | undefined;
        options_ui?: _WebExtensionManifestOptionsUi | undefined;
        content_scripts?: ContentScript[] | undefined;
        content_security_policy?: string | {
            /** The Content Security Policy used for extension pages. */
            extension_pages?: string | undefined;
        } | undefined;
        permissions?: PermissionOrOrigin[] | Permission[] | undefined;
        granted_host_permissions?: boolean | undefined;
        /** Needs at least manifest version 3. */
        host_permissions?: MatchPattern[] | undefined;
        /** Needs at least manifest version 3. */
        optional_host_permissions?: MatchPattern[] | undefined;
        optional_permissions?: OptionalPermissionOrOrigin[] | undefined;
        web_accessible_resources?:
            | string[]
            | Array<{
                resources: string[];
                matches?: MatchPattern[] | undefined;
                extension_ids?: Array<ExtensionID | "*"> | undefined;
            }>
            | undefined;
        hidden?: boolean | undefined;
        page_action?: _WebExtensionManifestPageAction | undefined;
        theme_experiment?: ThemeExperiment | undefined;
        /** Not supported on manifest versions above 2. */
        user_scripts?: _WebExtensionManifestUserScripts | undefined;
        chrome_settings_overrides?: _WebExtensionManifestChromeSettingsOverrides | undefined;
        commands?: { [key: string]: _WebExtensionManifestCommands } | undefined;
        devtools_page?: ExtensionURL | undefined;
        omnibox?: _WebExtensionManifestOmnibox | undefined;
        sidebar_action?: _WebExtensionManifestSidebarAction | undefined;
        chrome_url_overrides?: _WebExtensionManifestChromeUrlOverrides | undefined;
    }

    type OptionalPermission = OptionalPermissionNoPrompt | _OptionalPermission;

    type PermissionNoPrompt = OptionalPermissionNoPrompt | PermissionPrivileged | _PermissionNoPrompt;

    type OptionalPermissionNoPrompt = _OptionalPermissionNoPrompt;

    type Permission = string | PermissionNoPrompt | OptionalPermission | "declarativeNetRequest";

    type OptionalOnlyPermission = "userScripts";

    type CommonDataCollectionPermission = _CommonDataCollectionPermission;

    type DataCollectionPermission = CommonDataCollectionPermission | "none";

    type OptionalDataCollectionPermission = CommonDataCollectionPermission | "technicalAndInteraction";

    /** 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;
        /**
         * The applications property is deprecated, please use 'browser_specific_settings'
         * Not supported on manifest versions above 2.
         */
        applications?: DeprecatedApplications | undefined;
        browser_specific_settings?: BrowserSpecificSettings | undefined;
        /** Name must be at least 2, and should be at most 75 characters. */
        name: string;
        short_name?: string | undefined;
        description?: string | undefined;
        author?: string | undefined;
        version: string;
        homepage_url?: string | undefined;
        install_origins?: string[] | undefined;
        developer?: _ManifestBaseDeveloper | undefined;
    }

    /** Represents a WebExtension language pack manifest.json file */
    interface WebExtensionLangpackManifest extends ManifestBase {
        langpack_id: string;
        languages: _WebExtensionLangpackManifestLanguages;
        sources?: _WebExtensionLangpackManifestSources | undefined;
    }

    /** Represents a WebExtension dictionary manifest.json file */
    interface WebExtensionDictionaryManifest extends ManifestBase {
        dictionaries: _WebExtensionDictionaryManifestDictionaries;
    }

    interface ThemeIcons {
        /** A light icon to use for dark themes */
        light: ExtensionURL;
        /** The dark icon to use for light themes */
        dark: ExtensionURL;
        /** The size of the icons */
        size: number;
    }

    type OptionalPermissionOrOrigin = OptionalPermission | OptionalOnlyPermission | MatchPattern;

    type PermissionOrOrigin = Permission | MatchPattern;

    type HttpURL = string;

    type ExtensionURL = string;

    type ExtensionFileUrl = string;

    type ImageDataOrExtensionURL = string;

    type ExtensionID = string;

    interface FirefoxSpecificProperties {
        id?: ExtensionID | undefined;
        update_url?: string | undefined;
        strict_min_version?: string | undefined;
        strict_max_version?: string | undefined;
        admin_install_only?: boolean | undefined;
        data_collection_permissions?: {
            required?: DataCollectionPermission[] | undefined;
            optional?: OptionalDataCollectionPermission[] | undefined;
            has_previous_consent?: boolean | undefined;
        } | undefined;
    }

    interface GeckoAndroidSpecificProperties {
        strict_min_version?: string | undefined;
        strict_max_version?: string | undefined;
    }

    interface DeprecatedApplications {
        gecko?: FirefoxSpecificProperties | undefined;
        /** @deprecated Unsupported on Firefox at this time. */
        gecko_android?: GeckoAndroidSpecificProperties | undefined;
    }

    interface BrowserSpecificSettings {
        gecko?: FirefoxSpecificProperties | undefined;
        gecko_android?: GeckoAndroidSpecificProperties | undefined;
    }

    type MatchPattern = MatchPatternRestricted | MatchPatternUnestricted | "<all_urls>";

    /** Same as MatchPattern above, but excludes &lt;all_urls&gt;. */
    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;

    /**
     * Details of the script or CSS to inject. Either the code or the file property must be set, but both may not be set at the same time. Based on InjectDetails, but using underscore rather than camel case naming conventions.
     */
    interface ContentScript {
        matches: MatchPattern[];
        exclude_matches?: MatchPattern[] | undefined;
        include_globs?: string[] | undefined;
        exclude_globs?: string[] | undefined;
        /** The list of CSS files to inject */
        css?: ExtensionURL[] | undefined;
        /** The list of JS files to inject */
        js?: ExtensionURL[] | undefined;
        /**
         * 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.
         */
        all_frames?: boolean | undefined;
        /**
         * If match_about_blank is true, then the code is also injected in about:blank and about:srcdoc frames if your extension has access to its parent document. Ignored if match_origin_as_fallback is specified. By default it is `false`.
         */
        match_about_blank?: boolean | undefined;
        /**
         * If match_origin_as_fallback is true, then the code is also injected in about:, data:, blob: when their origin matches the pattern in 'matches', even if the actual document origin is opaque (due to the use of CSP sandbox or iframe sandbox). Match patterns in 'matches' must specify a wildcard path glob. By default it is `false`.
         */
        match_origin_as_fallback?: boolean | undefined;
        /** The soonest that the JavaScript or CSS will be injected into the tab. Defaults to "document_idle". */
        run_at?: extensionTypes.RunAt | undefined;
        /** The JavaScript world for a script to execute within. Defaults to "ISOLATED". */
        world?: extensionTypes.ExecutionWorld | undefined;
    }

    type IconPath = {
        [key: number]: ExtensionFileUrl;
    } | ExtensionFileUrl;

    type IconImageData = {
        [key: number]: ImageData;
    } | ImageData;

    type ImageData = any;

    /** @deprecated An unexpected property was found in the WebExtension manifest. */
    type UnrecognizedProperty = any;

    /** Represents a native manifest file */
    type NativeManifest = {
        name: string;
        description: string;
        path: string;
        type: "pkcs11" | "stdio";
        allowed_extensions: ExtensionID[];
    } | {
        name: ExtensionID;
        description: string;
        data: { [key: string]: any };
        type: "storage";
    };

    type ThemeColor = string | [number, number, number] | [number, number, number, number];

    interface ThemeExperiment {
        stylesheet?: ExtensionURL | undefined;
        images?: { [key: string]: string } | undefined;
        colors?: { [key: string]: string } | undefined;
        properties?: { [key: string]: string } | undefined;
    }

    interface ThemeType {
        images?: _ThemeTypeImages | undefined;
        colors?: _ThemeTypeColors | undefined;
        properties?: _ThemeType | undefined;
    }

    /** Contents of manifest.json for a static theme */
    interface ThemeManifest extends ManifestBase {
        theme: ThemeType;
        dark_theme?: ThemeType | undefined;
        default_locale?: string | undefined;
        theme_experiment?: ThemeExperiment | undefined;
        icons?: _ThemeManifestIcons | undefined;
    }

    type KeyName = string;

    type _PermissionPrivileged =
        | "activityLog"
        | "mozillaAddons"
        | "networkStatus"
        | "telemetry"
        | "normandyAddonStudy"
        | "urlbar";

    /** Defines the location the browserAction will appear by default. The default location is navbar. */
    type _ActionManifestDefaultArea =
        | "navbar"
        | "menupanel"
        | "tabstrip"
        | "personaltoolbar";

    interface _WebExtensionManifestDeclarativeNetRequestRuleResources {
        /**
         * A non-empty string uniquely identifying the ruleset. IDs beginning with '_' are reserved for internal use.
         */
        id: string;
        /** Whether the ruleset is enabled by default. */
        enabled: boolean;
        /** The path of the JSON ruleset relative to the extension directory. */
        path: ExtensionURL;
    }

    interface _WebExtensionManifestDeclarativeNetRequest {
        rule_resources: _WebExtensionManifestDeclarativeNetRequestRuleResources[];
    }

    interface _WebExtensionManifestIcons {
        [key: number]: ExtensionFileUrl;
    }

    /** The 'split' value is not supported. */
    type _WebExtensionManifestIncognito = "not_allowed" | "spanning" | "split";

    type _UndefinedType = "module" | "classic";

    type _PreferredEnvironment = "service_worker" | "document";

    interface _WebExtensionManifestOptionsUi {
        page: ExtensionURL;
        /** Defaults to true in Manifest V2; Deprecated in Manifest V3. */
        browser_style?: boolean | undefined;
        /**
         * chrome_style is ignored in Firefox. Its replacement (browser_style) has been deprecated.
         * Not supported on manifest versions above 2.
         */
        chrome_style?: boolean | undefined;
        open_in_tab?: boolean | undefined;
    }

    interface _WebExtensionManifestPageAction {
        default_title?: string | undefined;
        default_icon?: IconPath | undefined;
        default_popup?: string | undefined;
        /** Deprecated in Manifest V3. */
        browser_style?: boolean | undefined;
        show_matches?: MatchPattern[] | undefined;
        hide_matches?: MatchPatternRestricted[] | undefined;
        pinned?: boolean | undefined;
    }

    interface _WebExtensionManifestTelemetryPublicKeyKey {
        crv?: string | undefined;
        kty?: string | undefined;
        x?: string | undefined;
        y?: string | undefined;
    }

    interface _WebExtensionManifestTelemetryPublicKey {
        id: string;
        key: _WebExtensionManifestTelemetryPublicKeyKey;
    }

    /** Not supported on manifest versions above 2. */
    interface _WebExtensionManifestUserScripts {
        api_script?: ExtensionURL | undefined;
    }

    interface _WebExtensionManifestChromeSettingsOverridesSearchProvider {
        name: string;
        keyword?: string | string[] | undefined;
        search_url: string;
        favicon_url?: string | undefined;
        suggest_url?: string | undefined;
        /** @deprecated Unsupported on Firefox at this time. */
        instant_url?: string | undefined;
        /** @deprecated Unsupported on Firefox at this time. */
        image_url?: string | undefined;
        /** GET parameters to the search_url as a query string. */
        search_url_get_params?: string | undefined;
        /** POST parameters to the search_url as a query string. */
        search_url_post_params?: string | undefined;
        /** GET parameters to the suggest_url as a query string. */
        suggest_url_get_params?: string | undefined;
        /** POST parameters to the suggest_url as a query string. */
        suggest_url_post_params?: string | undefined;
        /** @deprecated Unsupported on Firefox at this time. */
        instant_url_post_params?: string | undefined;
        /** @deprecated Unsupported on Firefox at this time. */
        image_url_post_params?: string | undefined;
        /** @deprecated Unsupported on Firefox at this time. */
        search_form?: string | undefined;
        /** @deprecated Unsupported on Firefox at this time. */
        alternate_urls?: string[] | undefined;
        /** @deprecated Unsupported on Firefox. */
        prepopulated_id?: number | undefined;
        /** Encoding of the search term. */
        encoding?: string | undefined;
        /** Sets the default engine to a built-in engine only. */
        is_default?: boolean | undefined;
    }

    interface _WebExtensionManifestChromeSettingsOverrides {
        homepage?: string | undefined;
        search_provider?: _WebExtensionManifestChromeSettingsOverridesSearchProvider | undefined;
    }

    interface _WebExtensionManifestCommandsSuggestedKey {
        default?: KeyName | undefined;
        mac?: KeyName | undefined;
        linux?: KeyName | undefined;
        windows?: KeyName | undefined;
        chromeos?: string | undefined;
        android?: string | undefined;
        ios?: string | undefined;
        /** @deprecated Unknown platform name */
        additionalProperties?: string | undefined;
    }

    interface _WebExtensionManifestCommands {
        suggested_key?: _WebExtensionManifestCommandsSuggestedKey | undefined;
        description?: string | undefined;
    }

    interface _WebExtensionManifestOmnibox {
        keyword: string;
    }

    interface _WebExtensionManifestSidebarAction {
        default_title?: string | undefined;
        default_icon?: IconPath | undefined;
        /** Defaults to true in Manifest V2; Deprecated in Manifest V3. */
        browser_style?: boolean | undefined;
        default_panel: string;
        /** Whether or not the sidebar is opened at install. Default is `true`. */
        open_at_install?: boolean | undefined;
    }

    interface _WebExtensionManifestChromeUrlOverrides {
        newtab?: ExtensionURL | undefined;
        /** @deprecated Unsupported on Firefox at this time. */
        bookmarks?: ExtensionURL | undefined;
        /** @deprecated Unsupported on Firefox at this time. */
        history?: ExtensionURL | undefined;
    }

    type _OptionalPermission =
        | "browserSettings"
        | "browsingData"
        | "declarativeNetRequestFeedback"
        | "downloads"
        | "downloads.open"
        | "management"
        | "clipboardRead"
        | "clipboardWrite"
        | "geolocation"
        | "notifications"
        | "privacy"
        | "proxy"
        | "nativeMessaging"
        | "webNavigation"
        | "bookmarks"
        | "devtools"
        | "find"
        | "history"
        | "pkcs11"
        | "sessions"
        | "tabs"
        | "tabHide"
        | "topSites";

    type _PermissionNoPrompt =
        | "captivePortal"
        | "contextualIdentities"
        | "declarativeNetRequestWithHostAccess"
        | "dns"
        | "geckoProfiler"
        | "identity"
        | "alarms"
        | "storage"
        | "unlimitedStorage"
        | "theme"
        | "menus"
        | "contextMenus";

    type _OptionalPermissionNoPrompt =
        | "cookies"
        | "idle"
        | "scripting"
        | "webRequest"
        | "webRequestAuthProvider"
        | "webRequestBlocking"
        | "webRequestFilterResponse"
        | "webRequestFilterResponse.serviceWorkerScript"
        | "menus.overrideContext"
        | "search"
        | "tabGroups"
        | "activeTab";

    type _CommonDataCollectionPermission =
        | "authenticationInfo"
        | "bookmarksInfo"
        | "browsingActivity"
        | "financialAndPaymentInfo"
        | "healthInfo"
        | "locationInfo"
        | "personalCommunications"
        | "personallyIdentifyingInfo"
        | "searchTerms"
        | "websiteActivity"
        | "websiteContent";

    type _ProtocolHandlerProtocol =
        | "bitcoin"
        | "dat"
        | "dweb"
        | "ftp"
        | "geo"
        | "gopher"
        | "im"
        | "ipfs"
        | "ipns"
        | "irc"
        | "ircs"
        | "magnet"
        | "mailto"
        | "matrix"
        | "mms"
        | "news"
        | "nntp"
        | "sip"
        | "sms"
        | "smsto"
        | "ssb"
        | "ssh"
        | "tel"
        | "urn"
        | "webcal"
        | "wtai"
        | "xmpp";

    interface _ManifestBaseDeveloper {
        name?: string | undefined;
        url?: string | undefined;
    }

    interface _UndefinedChromeResources {
        [key: string]: ExtensionURL | {
            [key: string]: ExtensionURL;
        };
    }

    interface _WebExtensionLangpackManifestLanguages {
        [key: string]: {
            chrome_resources: _UndefinedChromeResources;
            version: string;
        };
    }

    interface _WebExtensionLangpackManifestSources {
        [key: string]: {
            base_path: ExtensionURL;
            paths?: string[] | undefined;
        };
    }

    interface _WebExtensionDictionaryManifestDictionaries {
        [key: string]: string;
    }

    interface _ThemeTypeImages {
        additional_backgrounds?: ImageDataOrExtensionURL[] | undefined;
        /**
         * @deprecated Unsupported images property, use 'theme.images.theme_frame', this alias is ignored in Firefox >= 70.
         */
        headerURL?: ImageDataOrExtensionURL | undefined;
        theme_frame?: ImageDataOrExtensionURL | undefined;
    }

    interface _ThemeTypeColors {
        tab_selected?: ThemeColor | undefined;
        /**
         * @deprecated Unsupported colors property, use 'theme.colors.frame', this alias is ignored in Firefox >= 70.
         */
        accentcolor?: ThemeColor | undefined;
        frame?: ThemeColor | undefined;
        frame_inactive?: ThemeColor | undefined;
        /**
         * @deprecated Unsupported color property, use 'theme.colors.tab_background_text', this alias is ignored in Firefox >= 70.
         */
        textcolor?: ThemeColor | undefined;
        tab_background_text?: ThemeColor | undefined;
        tab_background_separator?: ThemeColor | undefined;
        tab_loading?: ThemeColor | undefined;
        tab_text?: ThemeColor | undefined;
        tab_line?: ThemeColor | undefined;
        toolbar?: ThemeColor | undefined;
        /** This color property is an alias of 'bookmark_text'. */
        toolbar_text?: ThemeColor | undefined;
        bookmark_text?: ThemeColor | undefined;
        toolbar_field?: ThemeColor | undefined;
        toolbar_field_text?: ThemeColor | undefined;
        toolbar_field_border?: ThemeColor | undefined;
        /** @deprecated This color property is ignored in Firefox >= 89. */
        toolbar_field_separator?: ThemeColor | undefined;
        toolbar_top_separator?: ThemeColor | undefined;
        toolbar_bottom_separator?: ThemeColor | undefined;
        toolbar_vertical_separator?: ThemeColor | undefined;
        icons?: ThemeColor | undefined;
        icons_attention?: ThemeColor | undefined;
        button_background_hover?: ThemeColor | undefined;
        button_background_active?: ThemeColor | undefined;
        popup?: ThemeColor | undefined;
        popup_text?: ThemeColor | undefined;
        popup_border?: ThemeColor | undefined;
        toolbar_field_focus?: ThemeColor | undefined;
        toolbar_field_text_focus?: ThemeColor | undefined;
        toolbar_field_border_focus?: ThemeColor | undefined;
        popup_highlight?: ThemeColor | undefined;
        popup_highlight_text?: ThemeColor | undefined;
        ntp_background?: ThemeColor | undefined;
        ntp_card_background?: ThemeColor | undefined;
        ntp_text?: ThemeColor | undefined;
        sidebar?: ThemeColor | undefined;
        sidebar_border?: ThemeColor | undefined;
        sidebar_text?: ThemeColor | undefined;
        sidebar_highlight?: ThemeColor | undefined;
        sidebar_highlight_text?: ThemeColor | undefined;
        toolbar_field_highlight?: ThemeColor | undefined;
        toolbar_field_highlight_text?: ThemeColor | undefined;
    }

    type _ThemeTypeAdditionalBackgroundsAlignment =
        | "bottom"
        | "center"
        | "left"
        | "right"
        | "top"
        | "center bottom"
        | "center center"
        | "center top"
        | "left bottom"
        | "left center"
        | "left top"
        | "right bottom"
        | "right center"
        | "right top";

    type _ThemeTypeAdditionalBackgroundsTiling =
        | "no-repeat"
        | "repeat"
        | "repeat-x"
        | "repeat-y";

    type _ThemeTypeColorScheme =
        | "auto"
        | "light"
        | "dark"
        | "system";

    type _ThemeTypeContentColorScheme =
        | "auto"
        | "light"
        | "dark"
        | "system";

    interface _ThemeType {
        additional_backgrounds_alignment?: _ThemeTypeAdditionalBackgroundsAlignment[] | undefined;
        additional_backgrounds_tiling?: _ThemeTypeAdditionalBackgroundsTiling[] | undefined;
        color_scheme?: _ThemeTypeColorScheme | undefined;
        content_color_scheme?: _ThemeTypeContentColorScheme | undefined;
    }

    interface _ThemeManifestIcons {
        [key: number]: string;
    }
}

/**
 * Monitor extension activity
 *
 * Permissions: `activityLog`
 *
 * Not allowed in: Content scripts, Devtools pages
 */
declare namespace browser.activityLog {
    /**
     * The type of log entry. api_call is a function call made by the extension and api_event is an event callback to the extension. content_script is logged when a content script is injected.
     */
    type _OnExtensionActivityDetailsType =
        | "api_call"
        | "api_event"
        | "content_script"
        | "user_script";

    /** The type of view where the activity occurred. Content scripts will not have a viewType. */
    type _OnExtensionActivityDetailsViewType =
        | "background"
        | "popup"
        | "sidebar"
        | "tab"
        | "devtools_page"
        | "devtools_panel";

    interface _OnExtensionActivityDetailsData {
        /** A list of arguments passed to the call. */
        args?: any[] | undefined;
        /** The result of the call. */
        result?: object | undefined;
        /** The tab associated with this event if it is a tab or content script. */
        tabId?: number | undefined;
        /** If the type is content_script, this is the url of the script that was injected. */
        url?: string | undefined;
    }

    interface _OnExtensionActivityDetails {
        /** The date string when this call is triggered. */
        timeStamp: extensionTypes.Date;
        /**
         * The type of log entry. api_call is a function call made by the extension and api_event is an event callback to the extension. content_script is logged when a content script is injected.
         */
        type: _OnExtensionActivityDetailsType;
        /** The type of view where the activity occurred. Content scripts will not have a viewType. */
        viewType?: _OnExtensionActivityDetailsViewType | undefined;
        /** The name of the api call or event, or the script url if this is a content or user script event. */
        name: string;
        data: _OnExtensionActivityDetailsData;
    }

    interface _ActivityLogOnExtensionActivityEvent<TCallback = (details: _OnExtensionActivityDetails) => void> {
        addListener(cb: TCallback, id: string): void;
        removeListener(cb: TCallback): void;
        hasListener(cb: TCallback): boolean;
    }

    /* activityLog events */
    /** Receives an activityItem for each logging event. */
    const onExtensionActivity: _ActivityLogOnExtensionActivityEvent;
}

/**
 * Permissions: `alarms`
 *
 * Not allowed in: Content scripts, Devtools pages
 */
declare namespace browser.alarms {
    /* alarms types */
    interface Alarm {
        /** Name of this alarm. */
        name: string;
        /** Time when the alarm is scheduled to fire, in milliseconds past the epoch. */
        scheduledTime: number;
        /** When present, signals that the alarm triggers periodically after so many minutes. */
        periodInMinutes?: number | undefined;
    }

    /**
     * Details about the alarm. The alarm first fires either at 'when' milliseconds past the epoch (if 'when' is provided), after 'delayInMinutes' minutes from the current time (if 'delayInMinutes' is provided instead), or after 'periodInMinutes' minutes from the current time (if only 'periodInMinutes' is provided). Users should never provide both 'when' and 'delayInMinutes'. If 'periodInMinutes' is provided, then the alarm recurs repeatedly after that many minutes.
     */
    interface _CreateAlarmInfo {
        /** Time when the alarm is scheduled to first fire, in milliseconds past the epoch. */
        when?: number | undefined;
        /** Number of minutes from the current time after which the alarm should first fire. */
        delayInMinutes?: number | undefined;
        /** Number of minutes after which the alarm should recur repeatedly. */
        periodInMinutes?: number | undefined;
    }

    /* alarms functions */
    /**
     * Creates an alarm. After the delay is expired, the onAlarm event is fired. If there is another alarm with the same name (or no name if none is specified), it will be cancelled and replaced by this alarm.
     * @param alarmInfo Details about the alarm. The alarm first fires either at 'when' milliseconds past the epoch (if 'when' is provided), after 'delayInMinutes' minutes from the current time (if 'delayInMinutes' is provided instead), or after 'periodInMinutes' minutes from the current time (if only 'periodInMinutes' is provided). Users should never provide both 'when' and 'delayInMinutes'. If 'periodInMinutes' is provided, then the alarm recurs repeatedly after that many minutes.
     */
    function create(alarmInfo: _CreateAlarmInfo): Promise<void>;
    /**
     * Creates an alarm. After the delay is expired, the onAlarm event is fired. If there is another alarm with the same name (or no name if none is specified), it will be cancelled and replaced by this alarm.
     * @param name Optional name to identify this alarm. Defaults to the empty string.
     * @param alarmInfo Details about the alarm. The alarm first fires either at 'when' milliseconds past the epoch (if 'when' is provided), after 'delayInMinutes' minutes from the current time (if 'delayInMinutes' is provided instead), or after 'periodInMinutes' minutes from the current time (if only 'periodInMinutes' is provided). Users should never provide both 'when' and 'delayInMinutes'. If 'periodInMinutes' is provided, then the alarm recurs repeatedly after that many minutes.
     */
    function create(name: string, alarmInfo: _CreateAlarmInfo): Promise<void>;

    /**
     * Retrieves details about the specified alarm.
     * @param [name] The name of the alarm to get. Defaults to the empty string.
     */
    function get(name?: string): Promise<Alarm | undefined>;

    /** Gets an array of all the alarms. */
    function getAll(): Promise<Alarm[]>;

    /**
     * Clears the alarm with the given name.
     * @param [name] The name of the alarm to clear. Defaults to the empty string.
     */
    function clear(name?: string): Promise<boolean>;

    /** Clears all alarms. */
    function clearAll(): Promise<boolean>;

    /* alarms events */
    /**
     * Fired when an alarm has expired. Useful for transient background pages.
     * @param name The alarm that has expired.
     */
    const onAlarm: WebExtEvent<(name: Alarm) => void>;
}

/**
 * Use browser actions to put icons in the main browser toolbar, to the right of the address bar. In addition to its icon, a browser action can also have a tooltip, a badge, and a popup.
 *
 * Manifest keys: `action`, `browser_action`
 *
 * Needs at least manifest version 3.
 *
 * Not allowed in: Content scripts, Devtools pages
 */
declare namespace browser.action {
    /* action 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 | undefined;
        /**
         * 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 | undefined;
    }

    type ColorArray = [number, number, number, number];

    /** Pixel data for an image. Must be an ImageData object (for example, from a `canvas` element). */
    type ImageDataType = 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;

    /** Information sent when a browser action is clicked. */
    interface OnClickData {
        /** An array of keyboard modifiers that were held while the menu item was clicked. */
        modifiers: _OnClickDataModifiers[];
        /** An integer value of button by which menu item was clicked. */
        button?: number | undefined;
    }

    type _OnClickDataModifiers =
        | "Shift"
        | "Alt"
        | "Command"
        | "Ctrl"
        | "MacCtrl";

    /**
     * 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 _SetTitleDetails {
        /** The string the browser action should display when moused over. */
        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 | undefined;
        /**
         * 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 | undefined;
    }

    /** The collection of user-specified settings relating to an extension's action. */
    interface _GetUserSettingsReturnUserSettings {
        /**
         * Whether the extension's action icon is visible on browser windows' top-level toolbar (i.e., whether the extension has been 'pinned' by the user).
         */
        isOnToolbar?: boolean | undefined;
    }

    /**
     * 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 _SetIconDetails {
        /**
         * Either an ImageData object or a dictionary {size -> ImageData} representing icon to be set. If the icon is specified as a dictionary, the actual image to be used is chosen depending on screen's pixel density. If the number of image pixels that fit into one screen space unit equals `scale`, then image with size `scale` * 19 will be selected. Initially only scales 1 and 2 will be supported. At least one image must be specified. Note that 'details.imageData = foo' is equivalent to 'details.imageData = {'19': foo}'
         */
        imageData?: ImageDataType | {
            [key: number]: ImageDataType;
        } | undefined;
        /**
         * Either a relative image path or a dictionary {size -> relative image path} pointing to icon to be set. If the icon is specified as a dictionary, the actual image to be used is chosen depending on screen's pixel density. If the number of image pixels that fit into one screen space unit equals `scale`, then image with size `scale` * 19 will be selected. Initially only scales 1 and 2 will be supported. At least one image must be specified. Note that 'details.path = foo' is equivalent to 'details.imageData = {'19': foo}'
         */
        path?: string | {
            [key: number]: string;
        } | undefined;
        /**
         * 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 | undefined;
        /**
         * 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 | undefined;
    }

    /**
     * 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 _SetPopupDetails {
        /** The html file to show in a popup. If set to the empty string (''), no popup is shown. */
        popup: 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 | undefined;
        /**
         * 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 | undefined;
    }

    /**
     * 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 _SetBadgeTextDetails {
        /** Any number of characters can be passed, but only about four can fit in the space. */
        text: 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 | undefined;
        /**
         * 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 | undefined;
    }

    /**
     * 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 _SetBadgeBackgroundColorDetails {
        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 | undefined;
        /**
         * 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 | undefined;
    }

    /**
     * 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 _SetBadgeTextColorDetails {
        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 | undefined;
        /**
         * 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 | undefined;
    }

    /** An object with information about the popup to open. */
    interface _OpenPopupOptions {
        /** Defaults to the current window. */
        windowId?: number | undefined;
    }

    /* action functions */
    /**
     * 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: _SetTitleDetails): Promise<void>;

    /** Gets the title of the browser action. */
    function getTitle(details: Details): Promise<string>;

    /** Returns the user-specified settings relating to an extension's action. */
    function getUserSettings(): Promise<_GetUserSettingsReturnUserSettings>;

    /**
     * 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: _SetIconDetails): Promise<void>;

    /**
     * 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 setPopup(details: _SetPopupDetails): Promise<void>;

    /** Gets the html document set as the popup for this browser action. */
    function getPopup(details: Details): Promise<string>;

    /**
     * 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: _SetBadgeTextDetails): Promise<void>;

    /**
     * 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<string>;

    /**
     * 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: _SetBadgeBackgroundColorDetails): Promise<void>;

    /** Gets the background color of the browser action badge. */
    function getBadgeBackgroundColor(details: Details): Promise<ColorArray>;

    /**
     * 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: _SetBadgeTextColorDetails): Promise<any>;

    /** Gets the text color of the browser action badge. */
    function getBadgeTextColor(details: Details): Promise<any>;

    /**
     * Enables the browser action for a tab. By default, browser actions are enabled.
     * @param [tabId] The id of the tab for which you want to modify the browser action.
     */
    function enable(tabId?: number): Promise<void>;

    /**
     * Disables the browser action for a tab.
     * @param [tabId] The id of the tab for which you want to modify the browser action.
     */
    function disable(tabId?: number): Promise<void>;

    /** Checks whether the browser action is enabled. */
    function isEnabled(details: Details): Promise<any>;

    /**
     * Opens the extension popup window in the specified window.
     * @param [options] An object with information about the popup to open.
     */
    function openPopup(options?: _OpenPopupOptions): Promise<boolean>;

    /* action events */
    /**
     * Fired when a browser action icon is clicked. This event will not fire if the browser action has a popup.
     */
    const onClicked: WebExtEvent<(tab: tabs.Tab, info?: OnClickData) => void>;
}

/**
 * Manifest keys: `action`, `browser_action`
 *
 * Not supported on manifest versions above 2.
 *
 * Not allowed in: Content scripts, Devtools pages
 */
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 | undefined;
        /**
         * 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 | undefined;
    }

    type ColorArray = [number, number, number, number];

    /** Pixel data for an image. Must be an ImageData object (for example, from a `canvas` element). */
    type ImageDataType = 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;

    /** Information sent when a browser action is clicked. */
    interface OnClickData {
        /** An array of keyboard modifiers that were held while the menu item was clicked. */
        modifiers: _OnClickDataModifiers[];
        /** An integer value of button by which menu item was clicked. */
        button?: number | undefined;
    }

    type _OnClickDataModifiers =
        | "Shift"
        | "Alt"
        | "Command"
        | "Ctrl"
        | "MacCtrl";

    /**
     * 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 _SetTitleDetails extends Details {
        /** The string the browser action should display when moused over. */
        title: string | null;
    }

    /**
     * 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 _SetIconDetails extends Details {
        /**
         * Either an ImageData object or a dictionary {size -> ImageData} representing icon to be set. If the icon is specified as a dictionary, the actual image to be used is chosen depending on screen's pixel density. If the number of image pixels that fit into one screen space unit equals `scale`, then image with size `scale` * 19 will be selected. Initially only scales 1 and 2 will be supported. At least one image must be specified. Note that 'details.imageData = foo' is equivalent to 'details.imageData = {'19': foo}'
         */
        imageData?: ImageDataType | {
            [key: number]: ImageDataType;
        } | undefined;
        /**
         * Either a relative image path or a dictionary {size -> relative image path} pointing to icon to be set. If the icon is specified as a dictionary, the actual image to be used is chosen depending on screen's pixel density. If the number of image pixels that fit into one screen space unit equals `scale`, then image with size `scale` * 19 will be selected. Initially only scales 1 and 2 will be supported. At least one image must be specified. Note that 'details.path = foo' is equivalent to 'details.imageData = {'19': foo}'
         */
        path?: string | {
            [key: number]: string;
        } | undefined;
    }

    /**
     * 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