@types/chrome/index.d.ts

TypeScript definitions for chrome

/// <reference types="filesystem" />
/// <reference path="./har-format/index.d.ts" />
/// <reference path="./chrome-cast/index.d.ts" />

// Helpers
type SetRequired<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
type SetPartial<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;

////////////////////
// Global object
////////////////////
interface Window {
    chrome: typeof chrome;
}

declare namespace chrome {
    ////////////////////
    // Accessibility Features
    ////////////////////
    /**
     * Use the `chrome.accessibilityFeatures` API to manage Chrome's accessibility features. This API relies on the ChromeSetting prototype of the type API for getting and setting individual accessibility features. In order to get feature states the extension must request `accessibilityFeatures.read` permission. For modifying feature state, the extension needs `accessibilityFeatures.modify` permission. Note that `accessibilityFeatures.modify` does not imply `accessibilityFeatures.read` permission.
     *
     * Permissions: "accessibilityFeatures.read", "accessibilityFeatures.modify"
     */
    export namespace accessibilityFeatures {
        /** `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission. */
        const animationPolicy: chrome.types.ChromeSetting<"allowed" | "once" | "none">;

        /**
         * Auto mouse click after mouse stops moving. The value indicates whether the feature is enabled or not.
         * `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission.
         * @platform ChromeOS only
         */
        const autoclick: chrome.types.ChromeSetting<boolean>;

        /**
         * Caret highlighting. The value indicates whether the feature is enabled or not.
         * `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission.
         * @platform ChromeOS only
         * @since Chrome 51
         */
        const caretHighlight: chrome.types.ChromeSetting<boolean>;

        /**
         * Cursor color. The value indicates whether the feature is enabled or not, doesn't indicate the color of it.
         * `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission.
         * @platform ChromeOS only
         * @since Chrome 85
         */
        const cursorColor: chrome.types.ChromeSetting<boolean>;

        /**
         * Cursor highlighting. The value indicates whether the feature is enabled or not.
         * `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission.
         * @platform ChromeOS only
         * @since Chrome 51
         */
        const cursorHighlight: chrome.types.ChromeSetting<boolean>;

        /**
         * Dictation. The value indicates whether the feature is enabled or not.
         * `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission.
         * @platform ChromeOS only
         * @since Chrome 90
         */
        const dictation: chrome.types.ChromeSetting<boolean>;

        /**
         * Docked magnifier. The value indicates whether docked magnifier feature is enabled or not.
         * `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission.
         * @platform ChromeOS only
         * @since Chrome 87
         */
        const dockedMagnifier: chrome.types.ChromeSetting<boolean>;

        /**
         * Focus highlighting. The value indicates whether the feature is enabled or not.
         * `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission.
         * @platform ChromeOS only
         * @since Chrome 51
         */
        const focusHighlight: chrome.types.ChromeSetting<boolean>;

        /**
         * High contrast rendering mode. The value indicates whether the feature is enabled or not.
         * `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission.
         * @platform ChromeOS only
         */
        const highContrast: chrome.types.ChromeSetting<boolean>;

        /**
         * Enlarged cursor. The value indicates whether the feature is enabled or not.
         * `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission.
         * @platform ChromeOS only
         */
        const largeCursor: chrome.types.ChromeSetting<boolean>;

        /**
         * Full screen magnification. The value indicates whether the feature is enabled or not.
         * `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission.
         * @platform ChromeOS only
         */
        const screenMagnifier: chrome.types.ChromeSetting<boolean>;

        /**
         * Select-to-speak. The value indicates whether the feature is enabled or not.
         * `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission.
         * @platform ChromeOS only
         * @since Chrome 51
         */
        const selectToSpeak: chrome.types.ChromeSetting<boolean>;

        /**
         * Spoken feedback (text-to-speech). The value indicates whether the feature is enabled or not.
         * `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission.
         * @platform ChromeOS only
         */
        const spokenFeedback: chrome.types.ChromeSetting<boolean>;

        /**
         * Sticky modifier keys (like shift or alt). The value indicates whether the feature is enabled or not.
         * `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission.
         * @platform ChromeOS only
         */
        const stickyKeys: chrome.types.ChromeSetting<boolean>;

        /**
         * Switch Access. The value indicates whether the feature is enabled or not.
         * `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission.
         * @platform ChromeOS only
         * @since Chrome 51
         */
        const switchAccess: chrome.types.ChromeSetting<boolean>;

        /**
         * Virtual on-screen keyboard. The value indicates whether the feature is enabled or not.
         * `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission.
         * @platform ChromeOS only
         */
        const virtualKeyboard: chrome.types.ChromeSetting<boolean>;
    }

    ////////////////////
    // Action
    ////////////////////
    /**
     * Use the `chrome.action` API to control the extension's icon in the Google Chrome toolbar.
     * The action icons are displayed in the browser toolbar next to the omnibox. After installation, these appear in the extensions menu (the puzzle piece icon). Users can pin your extension icon to the toolbar.
     *
     * Manifest: "action"
     * @since Chrome 88, MV3
     */
    export namespace action {
        interface BadgeColorDetails {
            /** 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`. */
            color: string | extensionTypes.ColorArray;
            /** Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */
            tabId?: number | undefined;
        }

        interface BadgeTextDetails {
            /** Any number of characters can be passed, but only about four can fit in the space. If an empty string (`''`) is passed, the badge text is cleared. If `tabId` is specified and `text` is null, the text for the specified tab is cleared and defaults to the global badge text. */
            text?: string | undefined;
            /** Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */
            tabId?: number | undefined;
        }

        interface TitleDetails {
            /** The string the 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.  */
            tabId?: number | undefined;
        }

        interface PopupDetails {
            /** Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */
            tabId?: number | undefined;
            /** The html file to show in a popup. If set to the empty string (`''`), no popup is shown. */
            popup: string;
        }

        interface TabIconDetails {
            /** 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` \* n will be selected, where n is the size of the icon in the UI. At least one image must be specified. Note that 'details.path = foo' is equivalent to 'details.path = {'16': foo}' */
            path?: string | { [index: number]: string } | undefined;
            /** Limits the change to when a particular tab is selected. Automatically resets when the tab is closed.  */
            tabId?: number | undefined;
            /** 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` \* n will be selected, where n is the size of the icon in the UI. At least one image must be specified. Note that 'details.imageData = foo' is equivalent to 'details.imageData = {'16': foo}' */
            imageData?: ImageData | { [index: number]: ImageData } | undefined;
        }

        /** @since Chrome 99 */
        interface OpenPopupOptions {
            /** The id of the window to open the action popup in. Defaults to the currently-active window if unspecified.  */
            windowId?: number | undefined;
        }

        interface TabDetails {
            /** The ID of the tab to query state for. If no tab is specified, the non-tab-specific state is returned.  */
            tabId?: number | undefined;
        }

        /**
         * The collection of user-specified settings relating to an extension's action.
         * @since Chrome 91
         */
        interface UserSettings {
            /** 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;
        }

        /** @since Chrome 130 */
        interface UserSettingsChange {
            /** 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;
        }

        /**
         * Disables the action for a tab.
         * @param tabId The ID of the tab for which you want to modify the action.
         *
         * Can return its result via Promise.
         */
        function disable(tabId?: number): Promise<void>;
        function disable(callback: () => void): void;
        function disable(tabId: number | undefined, callback: () => void): void;

        /**
         * Enables the action for a tab. By default, actions are enabled.
         * @param tabId The ID of the tab for which you want to modify the action.
         *
         * Can return its result via Promise.
         */
        function enable(tabId?: number): Promise<void>;
        function enable(callback: () => void): void;
        function enable(tabId: number | undefined, callback: () => void): void;

        /**
         * Gets the background color of the action.
         *
         * Can return its result via Promise.
         */
        function getBadgeBackgroundColor(details: TabDetails): Promise<extensionTypes.ColorArray>;
        function getBadgeBackgroundColor(
            details: TabDetails,
            callback: (result: extensionTypes.ColorArray) => void,
        ): void;

        /**
         * Gets the badge text of the action. If no tab is specified, the non-tab-specific badge text is returned. If {@link declarativeNetRequest.ExtensionActionOptions.displayActionCountAsBadgeText displayActionCountAsBadgeText} is enabled, a placeholder text will be returned unless the {@link runtime.ManifestPermission declarativeNetRequestFeedback} permission is present or tab-specific badge text was provided.
         *
         * Can return its result via Promise.
         */
        function getBadgeText(details: TabDetails): Promise<string>;
        function getBadgeText(details: TabDetails, callback: (result: string) => void): void;

        /**
         * Gets the text color of the action.
         *
         * Can return its result via Promise.
         * @since Chrome 110
         */
        function getBadgeTextColor(details: TabDetails): Promise<extensionTypes.ColorArray>;
        function getBadgeTextColor(
            details: TabDetails,
            callback: (result: extensionTypes.ColorArray) => void,
        ): void;

        /**
         * Gets the html document set as the popup for this action.
         *
         * Can return its result via Promise.
         */
        function getPopup(details: TabDetails): Promise<string>;
        function getPopup(details: TabDetails, callback: (result: string) => void): void;

        /**
         * Gets the title of the action.
         *
         * Can return its result via Promise.
         */
        function getTitle(details: TabDetails): Promise<string>;
        function getTitle(details: TabDetails, callback: (result: string) => void): void;

        /**
         * Returns the user-specified settings relating to an extension's action.
         *
         * Can return its result via Promise.
         * @since Chrome 91
         */
        function getUserSettings(): Promise<UserSettings>;
        function getUserSettings(callback: (userSettings: UserSettings) => void): void;

        /**
         * Indicates whether the extension action is enabled for a tab (or globally if no `tabId` is provided). Actions enabled using only {@link declarativeContent} always return false.
         *
         * Can return its result via Promise.
         * @since Chrome 110
         */
        function isEnabled(tabId?: number): Promise<boolean>;
        function isEnabled(callback: (isEnabled: boolean) => void): void;
        function isEnabled(tabId: number | undefined, callback: (isEnabled: boolean) => void): void;

        /**
         * Opens the extension's popup. Between Chrome 118 and Chrome 126, this is only available to policy installed extensions.
         *
         * @param options Specifies options for opening the popup.
         *
         * Can return its result via Promise.
         * @since Chrome 127
         */
        function openPopup(options?: OpenPopupOptions): Promise<void>;
        function openPopup(callback: () => void): void;
        function openPopup(options: OpenPopupOptions | undefined, callback: () => void): void;

        /**
         * Sets the background color for the badge.
         *
         * Can return its result via Promise.
         */
        function setBadgeBackgroundColor(details: BadgeColorDetails): Promise<void>;
        function setBadgeBackgroundColor(details: BadgeColorDetails, callback: () => void): void;

        /**
         * Sets the badge text for the action. The badge is displayed on top of the icon.
         *
         * Can return its result via Promise.
         */
        function setBadgeText(details: BadgeTextDetails): Promise<void>;
        function setBadgeText(details: BadgeTextDetails, callback: () => void): void;

        /**
         * Sets the text color for the badge.
         *
         * Can return its result via Promise.
         * @since Chrome 110
         */
        function setBadgeTextColor(details: BadgeColorDetails): Promise<void>;
        function setBadgeTextColor(details: BadgeColorDetails, callback: () => void): void;

        /**
         * Sets the icon for the 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.
         *
         * Can return its result via Promise.
         */
        function setIcon(details: TabIconDetails): Promise<void>;
        function setIcon(details: TabIconDetails, callback: () => void): void;

        /**
         * Sets the HTML document to be opened as a popup when the user clicks on the action's icon.
         *
         * Can return its result via Promise.
         * @since Chrome 96
         */
        function setPopup(details: PopupDetails): Promise<void>;
        function setPopup(details: PopupDetails, callback: () => void): void;

        /**
         * Sets the title of the action. This shows up in the tooltip.
         *
         * Can return its result via Promise.
         */
        function setTitle(details: TitleDetails): Promise<void>;
        function setTitle(details: TitleDetails, callback: () => void): void;

        /** Fired when an action icon is clicked. This event will not fire if the action has a popup. */
        const onClicked: events.Event<(tab: chrome.tabs.Tab) => void>;

        /**
         * Fired when user-specified settings relating to an extension's action change.
         * @since Chrome 130
         */
        const onUserSettingsChanged: events.Event<(change: UserSettingsChange) => void>;
    }

    ////////////////////
    // Alarms
    ////////////////////
    /**
     * Use the `chrome.alarms` API to schedule code to run periodically or at a specified time in the future.
     *
     * Permissions: "alarms"
     */
    export namespace alarms {
        interface AlarmCreateInfo {
            /** Length of time in minutes after which the {@link onAlarm} event should fire.  */
            delayInMinutes?: number | undefined;
            /** If set, the onAlarm event should fire every `periodInMinutes` minutes after the initial event specified by `when` or `delayInMinutes`. If not set, the alarm will only fire once. */
            periodInMinutes?: number | undefined;
            /** Time at which the alarm should fire, in milliseconds past the epoch (e.g. `Date.now() + n`). */
            when?: number | undefined;
        }

        interface Alarm {
            /** If not null, the alarm is a repeating alarm and will fire again in `periodInMinutes` minutes. */
            periodInMinutes?: number;
            /** Time at which this alarm was scheduled to fire, in milliseconds past the epoch (e.g. `Date.now() + n`). For performance reasons, the alarm may have been delayed an arbitrary amount beyond this. */
            scheduledTime: number;
            /** Name of this alarm. */
            name: string;
        }

        /**
         * Creates an alarm. Near the time(s) specified by `alarmInfo`, the {@link 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.
         *
         * In order to reduce the load on the user's machine, Chrome limits alarms to at most once every 30 seconds but may delay them an arbitrary amount more. That is, setting `delayInMinutes` or `periodInMinutes` to less than `0.5` will not be honored and will cause a warning. `when` can be set to less than 30 seconds after "now" without warning but won't actually cause the alarm to fire for at least 30 seconds.
         *
         * To help you debug your app or extension, when you've loaded it unpacked, there's no limit to how often the alarm can fire.
         * @param name Optional name to identify this alarm. Defaults to the empty string.
         * @param alarmInfo Describes when the alarm should fire. The initial time must be specified by either `when` or `delayInMinutes` (but not both). If `periodInMinutes` is set, the alarm will repeat every `periodInMinutes` minutes after the initial event. If neither `when` or `delayInMinutes` is set for a repeating alarm, `periodInMinutes` is used as the default for `delayInMinutes`.
         *
         * Can return its result via Promise in Manifest V3 or later since Chrome 111.
         */
        function create(alarmInfo: AlarmCreateInfo): Promise<void>;
        function create(name: string | undefined, alarmInfo: AlarmCreateInfo): Promise<void>;
        function create(alarmInfo: AlarmCreateInfo, callback: () => void): void;
        function create(name: string | undefined, alarmInfo: AlarmCreateInfo, callback: () => void): void;

        /**
         * Gets an array of all the alarms.
         *
         * Can return its result via Promise in Manifest V3 or later since Chrome 91.
         */
        function getAll(): Promise<Alarm[]>;
        function getAll(callback: (alarms: Alarm[]) => void): void;

        /**
         * Clears all alarms.
         *
         * Can return its result via Promise in Manifest V3 or later since Chrome 91.
         */
        function clearAll(): Promise<boolean>;
        function clearAll(callback: (wasCleared: boolean) => void): void;

        /**
         * Clears the alarm with the given name.
         *
         * Can return its result via Promise in Manifest V3 or later since Chrome 91.
         */
        function clear(name?: string): Promise<boolean>;
        function clear(callback: (wasCleared: boolean) => void): void;
        function clear(name: string | undefined, callback: (wasCleared: boolean) => void): void;

        /**
         * Retrieves details about the specified alarm.
         * @param name The name of the alarm to get. Defaults to the empty string.
         *
         * Can return its result via Promise in Manifest V3 or later since Chrome 91.
         */
        function get(name?: string): Promise<Alarm | undefined>;
        function get(callback: (alarm?: Alarm) => void): void;
        function get(name: string | undefined, callback: (alarm?: Alarm) => void): void;

        /** Fired when an alarm has elapsed. Useful for event pages. */
        const onAlarm: events.Event<(alarm: Alarm) => void>;
    }

    ////////////////////
    // Audio
    ////////////////////
    /**
     * The `chrome.audio` API is provided to allow users to get information about and control the audio devices attached to the system. This API is currently only available in kiosk mode for ChromeOS.
     *
     * Permissions: "audio"
     * @platform ChromeOS only
     * @since Chrome 59
     */
    export namespace audio {
        interface AudioDeviceInfo {
            /** Device name */
            deviceName: string;
            /** Type of the device */
            deviceType: DeviceType;
            /** The user-friendly name (e.g. "USB Microphone"). */
            displayName: string;
            /** The unique identifier of the audio device. */
            id: string;
            /** True if this is the current active device. */
            isActive: boolean;
            /** The sound level of the device, volume for output, gain for input. */
            level: number;
            /** The stable/persisted device id string when available. */
            stableDeviceId?: string;
            /** Stream type associated with this device. */
            streamType: StreamType;
        }

        interface DeviceFilter {
            /** If set, only audio devices whose active state matches this value will satisfy the filter. */
            isActive?: boolean;
            /** If set, only audio devices whose stream type is included in this list will satisfy the filter. */
            streamTypes?: StreamType[];
        }

        interface DeviceIdLists {
            /**
             * List of input devices specified by their ID.
             * To indicate input devices should be unaffected, leave this property unset.
             */
            input?: string[];
            /**
             * List of output devices specified by their ID.
             * To indicate output devices should be unaffected, leave this property unset.
             */
            output?: string[];
        }

        interface DeviceProperties {
            /**
             * The audio device's desired sound level. Defaults to the device's current sound level.
             * If used with audio input device, represents audio device gain.
             * If used with audio output device, represents audio device volume.
             */
            level?: number;
        }

        /** Available audio device types. */
        enum DeviceType {
            ALSA_LOOPBACK = "ALSA_LOOPBACK",
            BLUETOOTH = "BLUETOOTH",
            FRONT_MIC = "FRONT_MIC",
            HDMI = "HDMI",
            HEADPHONE = "HEADPHONE",
            HOTWORD = "HOTWORD",
            INTERNAL_MIC = "INTERNAL_MIC",
            INTERNAL_SPEAKER = "INTERNAL_SPEAKER",
            KEYBOARD_MIC = "KEYBOARD_MIC",
            LINEOUT = "LINEOUT",
            MIC = "MIC",
            OTHER = "OTHER",
            POST_DSP_LOOPBACK = "POST_DSP_LOOPBACK",
            POST_MIX_LOOPBACK = "POST_MIX_LOOPBACK",
            REAR_MIC = "REAR_MIC",
            USB = "USB",
        }

        interface LevelChangedEvent {
            /** ID of device whose sound level has changed. */
            deviceId: string;
            /** The device's new sound level. */
            level: number;
        }

        interface MuteChangedEvent {
            /** Whether or not the stream is now muted. */
            isMuted: boolean;
            /** The type of the stream for which the mute value changed. The updated mute value applies to all devices with this stream type. */
            streamType: StreamType;
        }

        /** Type of stream an audio device provides. */
        enum StreamType {
            INPUT = "INPUT",
            OUTPUT = "OUTPUT",
        }

        /**
         * Gets a list of audio devices filtered based on filter.
         * Can return its result via Promise in Manifest V3 or later since Chrome 116.
         */
        function getDevices(filter?: DeviceFilter): Promise<AudioDeviceInfo[]>;
        function getDevices(filter: DeviceFilter, callback: (devices: AudioDeviceInfo[]) => void): void;
        function getDevices(callback: (devices: AudioDeviceInfo[]) => void): void;

        /**
         * Gets the system-wide mute state for the specified stream type.
         * Can return its result via Promise in Manifest V3 or later since Chrome 116.
         */
        function getMute(streamType: `${StreamType}`): Promise<boolean>;
        function getMute(streamType: `${StreamType}`, callback: (value: boolean) => void): void;

        /**
         * Sets lists of active input and/or output devices.
         * Can return its result via Promise in Manifest V3 or later since Chrome 116.
         */
        function setActiveDevices(ids: DeviceIdLists): Promise<void>;
        function setActiveDevices(ids: DeviceIdLists, callback: () => void): void;

        /**
         * Sets mute state for a stream type. The mute state will apply to all audio devices with the specified audio stream type.
         * Can return its result via Promise in Manifest V3 or later since Chrome 116.
         */
        function setMute(streamType: `${StreamType}`, isMuted: boolean): Promise<void>;
        function setMute(streamType: `${StreamType}`, isMuted: boolean, callback: () => void): void;

        /**
         * Sets the properties for the input or output device.
         * Can return its result via Promise in Manifest V3 or later since Chrome 116.
         */
        function setProperties(id: string, properties: DeviceProperties): Promise<void>;
        function setProperties(id: string, properties: DeviceProperties, callback: () => void): void;

        /**
         * Fired when audio devices change, either new devices being added, or existing devices being removed.
         */
        const onDeviceListChanged: chrome.events.Event<(devices: AudioDeviceInfo[]) => void>;

        /**
         * Fired when sound level changes for an active audio device.
         */
        const onLevelChanged: chrome.events.Event<(event: LevelChangedEvent) => void>;

        /**
         * Fired when the mute state of the audio input or output changes.
         * Note that mute state is system-wide and the new value applies to every audio device with specified stream type.
         */
        const onMuteChanged: chrome.events.Event<(event: MuteChangedEvent) => void>;
    }

    ////////////////////
    // Bookmarks
    ////////////////////
    /**
     * Use the `chrome.bookmarks` API to create, organize, and otherwise manipulate bookmarks. Also see Override Pages, which you can use to create a custom Bookmark Manager page.
     *
     * Permissions: "bookmarks"
     */
    export namespace bookmarks {
        /** A node (either a bookmark or a folder) in the bookmark tree. Child nodes are ordered within their parent folder. */
        interface BookmarkTreeNode {
            /** An ordered list of children of this node. */
            children?: BookmarkTreeNode[];
            /** When this node was created, in milliseconds since the epoch (`new Date(dateAdded)`). */
            dateAdded?: number;
            /** When the contents of this folder last changed, in milliseconds since the epoch. */
            dateGroupModified?: number;
            /**
             * When this node was last opened, in milliseconds since the epoch. Not set for folders.
             * @since Chrome 114
             */
            dateLastUsed?: number;
            /**
             * If present, this is a folder that is added by the browser and that cannot be modified by the user or the extension. Child nodes may be modified, if this node does not have the `unmodifiable` property set. Omitted if the node can be modified by the user and the extension (default).
             *
             * There may be zero, one or multiple nodes of each folder type. A folder may be added or removed by the browser, but not via the extensions API.
             * @since Chrome 134
             */
            folderType?: `${FolderType}`;
            /** The unique identifier for the node. IDs are unique within the current profile, and they remain valid even after the browser is restarted. */
            id: string;
            /** The 0-based position of this node within its parent folder. */
            index?: number;
            /** The `id` of the parent folder. Omitted for the root node. */
            parentId?: string;
            /**
             * Whether this node is synced with the user's remote account storage by the browser. This can be used to distinguish between account and local-only versions of the same {@link FolderType}. The value of this property may change for an existing node, for example as a result of user action.
             *
             * Note: this reflects whether the node is saved to the browser's built-in account provider. It is possible that a node could be synced via a third-party, even if this value is false.
             *
             * For managed nodes (nodes where `unmodifiable` is set to `true`), this property will always be `false`.
             * @since Chrome 134
             */
            syncing: boolean;
            /** The text displayed for the node. */
            title: string;
            /** 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 user and the extension (default). */
            unmodifiable?: `${BookmarkTreeNodeUnmodifiable}`;
            /* The URL navigated to when a user clicks the bookmark. Omitted for folders. */
            url?: string;
        }

        /**
         * Indicates the reason why this node is unmodifiable. The `managed` value indicates that this node was configured by the system administrator. Omitted if the node can be modified by the user and the extension (default).
         * @since Chrome 44
         */
        enum BookmarkTreeNodeUnmodifiable {
            MANAGED = "managed",
        }

        /** Object passed to the create() function. */
        interface CreateDetails {
            index?: number;
            /** Defaults to the Other Bookmarks folder. */
            parentId?: string;
            title?: string;
            url?: string;
        }

        /**
         * Indicates the type of folder.
         * @since Chrome 134
         */

        enum FolderType {
            /** The folder whose contents is displayed at the top of the browser window. */
            BOOKMARKS_BAR = "bookmarks-bar",
            /** Bookmarks which are displayed in the full list of bookmarks on all platforms. */
            OTHER = "other",
            /** Bookmarks generally available on the user's mobile devices, but modifiable by extension or in the bookmarks manager. */
            MOBILE = "mobile",
            /** A top-level folder that may be present if the system administrator or the custodian of a supervised user has configured bookmarks. */
            MANAGED = "managed",
        }

        /** @deprecated Bookmark write operations are no longer limited by Chrome. */
        const MAX_WRITE_OPERATIONS_PER_HOUR: 1000000;

        /** @deprecated Bookmark write operations are no longer limited by Chrome. */
        const MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE: 1000000;

        /**
         * The `id` associated with the root level node.
         * @since Chrome 145
         */
        const ROOT_NODE_ID = "0";

        /**
         * Creates a bookmark or folder under the specified parentId. If url is NULL or missing, it will be a folder.
         *
         * Can return its result via Promise since Chrome 90.
         */
        function create(bookmark: CreateDetails): Promise<BookmarkTreeNode>;
        function create(bookmark: CreateDetails, callback: (result: BookmarkTreeNode) => void): void;

        /**
         * Retrieves the specified BookmarkTreeNode(s).
         * @param idOrIdList A single string-valued id, or an array of string-valued ids
         *
         * Can return its result via Promise since Chrome 90.
         */
        function get(idOrIdList: string | [string, ...string[]]): Promise<BookmarkTreeNode[]>;
        function get(
            idOrIdList: string | [string, ...string[]],
            callback: (results: BookmarkTreeNode[]) => void,
        ): void;

        /**
         * Retrieves the children of the specified BookmarkTreeNode id.
         *
         * Can return its result via Promise since Chrome Chrome 90
         */
        function getChildren(id: string): Promise<BookmarkTreeNode[]>;
        function getChildren(id: string, callback: (results: BookmarkTreeNode[]) => void): void;

        /**
         * Retrieves the recently added bookmarks.
         * @param numberOfItems The maximum number of items to return.
         *
         * Can return its result via Promise since Chrome Chrome 90
         */
        function getRecent(numberOfItems: number): Promise<BookmarkTreeNode[]>;
        function getRecent(numberOfItems: number, callback: (results: BookmarkTreeNode[]) => void): void;

        /**
         * Retrieves part of the Bookmarks hierarchy, starting at the specified node.
         * @param id The ID of the root of the subtree to retrieve.
         *
         * Can return its result via Promise since Chrome Chrome 90
         */
        function getSubTree(id: string): Promise<BookmarkTreeNode[]>;
        function getSubTree(id: string, callback: (results: BookmarkTreeNode[]) => void): void;

        /**
         * Retrieves the entire Bookmarks hierarchy.
         *
         * Can return its result via Promise since Chrome Chrome 90
         */
        function getTree(): Promise<BookmarkTreeNode[]>;
        function getTree(callback: (results: BookmarkTreeNode[]) => void): void;

        interface MoveDestination {
            parentId?: string;
            index?: number;
        }

        /**
         * Moves the specified BookmarkTreeNode to the provided location.
         *
         * Can return its result via Promise since Chrome Chrome 90
         */
        function move(id: string, destination: MoveDestination): Promise<BookmarkTreeNode>;
        function move(
            id: string,
            destination: MoveDestination,
            callback: (result: BookmarkTreeNode) => void,
        ): void;

        /**
         * Removes a bookmark or an empty bookmark folder.
         *
         * Can return its result via Promise since Chrome Chrome 90
         */
        function remove(id: string): Promise<void>;
        function remove(id: string, callback: () => void): void;

        /**
         * Recursively removes a bookmark folder.
         *
         * Can return its result via Promise since Chrome Chrome 90
         */
        function removeTree(id: string): Promise<void>;
        function removeTree(id: string, callback: () => void): void;

        interface SearchQuery {
            /** A string of words and quoted phrases that are matched against bookmark URLs and titles.*/
            query?: string;
            /** The URL of the bookmark; matches verbatim. Note that folders have no URL. */
            url?: string;
            /** The title of the bookmark; matches verbatim. */
            title?: string;
        }

        /**
         * Searches for BookmarkTreeNodes matching the given query. Queries specified with an object produce BookmarkTreeNodes matching all specified properties.
         * @param query Either a string of words and quoted phrases that are matched against bookmark URLs and titles, or an object. If an object, the properties `query`, `url`, and `title` may be specified and bookmarks matching all specified properties will be produced.
         *
         * Can return its result via Promise since Chrome Chrome 90
         */
        function search(query: string | SearchQuery): Promise<BookmarkTreeNode[]>;
        function search(query: string | SearchQuery, callback: (results: BookmarkTreeNode[]) => void): void;

        interface UpdateChanges {
            title?: string;
            url?: string;
        }

        /**
         * Updates the properties of a bookmark or folder. Specify only the properties that you want to change; unspecified properties will be left unchanged. **Note:** Currently, only 'title' and 'url' are supported.
         *
         * Can return its result via Promise since Chrome Chrome 90
         */
        function update(id: string, changes: UpdateChanges): Promise<BookmarkTreeNode>;
        function update(id: string, changes: UpdateChanges, callback: (result: BookmarkTreeNode) => void): void;

        /** Fired when a bookmark or folder changes. **Note:** Currently, only title and url changes trigger this.*/
        const onChanged: events.Event<(id: string, changeInfo: { title: string; url?: string }) => void>;

        /** Fired when the children of a folder have changed their order due to the order being sorted in the UI. This is not called as a result of a move(). */
        const onChildrenReordered: events.Event<(id: string, reorderInfo: { childIds: string[] }) => void>;

        /** Fired when a bookmark or folder is created. */
        const onCreated: events.Event<(id: string, bookmark: BookmarkTreeNode) => void>;

        /** 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. */
        const onImportBegan: events.Event<() => void>;

        /** Fired when a bookmark import session is ended.  */
        const onImportEnded: events.Event<() => void>;

        /** Fired when a bookmark or folder is moved to a different parent folder. */
        const onMoved: events.Event<
            (
                id: string,
                moveInfo: {
                    parentId: string;
                    index: number;
                    oldParentId: string;
                    oldIndex: number;
                },
            ) => void
        >;

        /** Fired when a bookmark or folder is removed. When a folder is removed recursively, a single notification is fired for the folder, and none for its contents. */
        const onRemoved: events.Event<
            (
                id: string,
                removeInfo: {
                    parentId: string;
                    index: number;
                    /** @since Chrome 48 */
                    node: BookmarkTreeNode;
                },
            ) => void
        >;
    }

    ////////////////////
    // Browser Action
    ////////////////////
    /**
     * Use browser actions to put icons in the main Google Chrome toolbar, to the right of the address bar. In addition to its icon, a browser action can have a tooltip, a badge, and a popup.
     *
     * Manifest: "browser_action"
     *
     * MV2 only
     */
    export namespace browserAction {
        interface BadgeBackgroundColorDetails {
            /** An array of four integers in the range 0-255 that make up the RGBA color of the badge. Can also be a string with a CSS hex color value; for example, `#FF0000` or `#F00` (red). Renders colors at full opacity. */
            color: string | extensionTypes.ColorArray;
            /** Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */
            tabId?: number | null | undefined;
        }

        interface BadgeTextDetails {
            /** Any number of characters can be passed, but only about four can fit into the space. If an empty string (`''`) is passed, the badge text is cleared. If `tabId` is specified and `text` is null, the text for the specified tab is cleared and defaults to the global badge text. */
            text?: string | null | undefined;
            /** Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */
            tabId?: number | null | undefined;
        }

        interface TitleDetails {
            /** The string the browser action should display when moused over. */
            title: string;
            /** Optional. Limits the change to when a particular tab is selected. Automatically resets when the tab is closed.  */
            tabId?: number | null | undefined;
        }

        interface TabDetails {
            /** The ID of the tab to query state for. If no tab is specified, the non-tab-specific state is returned. */
            tabId?: number | null | undefined;
        }

        type TabIconDetails =
            & {
                /** Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */
                tabId?: number | null | undefined;
            }
            & (
                | {
                    /** Either an ImageData object or a dictionary {size -> ImageData} representing an icon to be set. If the icon is specified as a dictionary, the image used is chosen depending on the screen's pixel density. If the number of image pixels that fit into one screen space unit equals `scale`, then an image with size `scale` \* n is selected, where _n_ is the size of the icon in the UI. At least one image must be specified. Note that 'details.imageData = foo' is equivalent to 'details.imageData = {'16': foo}' */
                    imageData: ImageData | { [index: number]: ImageData };
                    /** Either a relative image path or a dictionary {size -> relative image path} pointing to an icon to be set. If the icon is specified as a dictionary, the image used is chosen depending on the screen's pixel density. If the number of image pixels that fit into one screen space unit equals `scale`, then an image with size `scale` \* n is selected, where _n_ is the size of the icon in the UI. At least one image must be specified. Note that 'details.path = foo' is equivalent to 'details.path = {'16': foo}' */
                    path?: string | { [index: string]: string } | undefined;
                }
                | {
                    /** Either an ImageData object or a dictionary {size -> ImageData} representing an icon to be set. If the icon is specified as a dictionary, the image used is chosen depending on the screen's pixel density. If the number of image pixels that fit into one screen space unit equals `scale`, then an image with size `scale` \* n is selected, where _n_ is the size of the icon in the UI. At least one image must be specified. Note that 'details.imageData = foo' is equivalent to 'details.imageData = {'16': foo}' */
                    imageData?: ImageData | { [index: number]: ImageData } | undefined;
                    /** Either a relative image path or a dictionary {size -> relative image path} pointing to an icon to be set. If the icon is specified as a dictionary, the image used is chosen depending on the screen's pixel density. If the number of image pixels that fit into one screen space unit equals `scale`, then an image with size `scale` \* n is selected, where _n_ is the size of the icon in the UI. At least one image must be specified. Note that 'details.path = foo' is equivalent to 'details.path = {'16': foo}' */
                    path: string | { [index: string]: string };
                }
            );

        interface PopupDetails {
            /** Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */
            tabId?: number | null | undefined;
            /** The relative path to the HTML file to show in a popup. If set to the empty string (`''`), no popup is shown.*/
            popup: string;
        }

        /**
         * Enables the browser action for a tab. Defaults to enabled.
         * @param tabId The ID of the tab for which to modify the browser action.
         * @param callback Since Chrome 67
         */
        function enable(callback?: () => void): void;
        function enable(tabId: number | null | undefined, callback?: () => void): void;

        /**
         * Sets the background color for the badge.
         * @param callback Since Chrome 67
         */
        function setBadgeBackgroundColor(details: BadgeBackgroundColorDetails, callback?: () => void): void;

        /**
         * Sets the badge text for the browser action. The badge is displayed on top of the icon.
         * @param callback Since Chrome 67
         */
        function setBadgeText(details: BadgeTextDetails, callback?: () => void): void;

        /**
         * Sets the title of the browser action. This title appears in the tooltip.
         * @param callback Since Chrome 67
         */
        function setTitle(details: TitleDetails, callback?: () => void): void;

        /** Gets the badge text of the browser action. If no tab is specified, the non-tab-specific badge text is returned. */
        function getBadgeText(details: TabDetails, callback: (result: string) => void): void;

        /**
         * Sets the HTML document to be opened as a popup when the user clicks the browser action icon.
         * @param callback Since Chrome 67
         */
        function setPopup(details: PopupDetails, callback?: () => void): void;

        /**
         * Disables the browser action for a tab.
         * @param tabId The ID of the tab for which to modify the browser action.
         * @param callback since Chrome 67
         */
        function disable(callback?: () => void): void;
        function disable(tabId: number | null | undefined, callback?: () => void): void;

        /** Gets the title of the browser action. */
        function getTitle(details: TabDetails, callback: (result: string) => void): void;

        /** Gets the background color of the browser action. */
        function getBadgeBackgroundColor(
            details: TabDetails,
            callback: (result: extensionTypes.ColorArray) => void,
        ): void;

        /** Gets the HTML document that is set as the popup for this browser action. */
        function getPopup(details: TabDetails, callback: (result: string) => void): void;

        /**
         * Sets the icon for the browser action. The icon can be specified as the path to an image file, as the pixel data from a canvas element, or as a dictionary of one of those. Either the `path` or the `imageData` property must be specified.
         */
        function setIcon(details: TabIconDetails, callback?: () => void): void;

        /** Fired when a browser action icon is clicked. Does not fire if the browser action has a popup. */
        c