/** * Copyright 2026 Google LLC * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ // Generated on Mon Jan 12 2026 22:33:22 GMT+0000 (Coordinated Universal Time) // Built at 7dea46963dd0037c6f8ff82fe40b378135bc23b1 // Includes all types, including MV2 + Platform Apps APIs. // These are stubs for DOM APIs not nessecarily available in TS' defaults. interface Entry {} interface FileEntry extends Entry {} interface DirectoryEntry extends Entry {} interface LocalMediaStream {} interface DOMFileSystem extends FileSystem {} // This is used to support addListener() where additional parameters are supported. // The name is detected inside the developer.chrome.com repository and special actions are taken. type CustomChromeEvent void> = Omit, 'addListener'> & { // nb. This just copies the description from `chrome.events.Event.addListener`. /** * Registers an event listener _callback_ to an event. */ readonly addListener: H; }; declare namespace chrome { /** * Use the `chrome.accessibilityFeatures` API to manage Chrome's accessibility features. This API relies on the [ChromeSetting prototype of the type API](https://developer.chrome.com/docs/extensions/reference/types/#ChromeSetting) 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. * * @chrome-permission accessibilityFeatures.modify * @chrome-permission accessibilityFeatures.read * @chrome-platform chromeos * @chrome-platform linux * @chrome-platform mac * @chrome-platform win */ export namespace accessibilityFeatures { /** * **ChromeOS only.** * * 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. */ export const spokenFeedback: types.ChromeSetting; /** * **ChromeOS only.** * * Enlarged cursor. The value indicates whether the feature is enabled or not. `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission. */ export const largeCursor: types.ChromeSetting; /** * **ChromeOS only.** * * 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. */ export const stickyKeys: types.ChromeSetting; /** * **ChromeOS only.** * * 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. */ export const highContrast: types.ChromeSetting; /** * **ChromeOS only.** * * 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. */ export const screenMagnifier: types.ChromeSetting; /** * **ChromeOS only.** * * 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. */ export const autoclick: types.ChromeSetting; /** * **ChromeOS only.** * * 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. */ export const virtualKeyboard: types.ChromeSetting; /** * **ChromeOS only.** * * Caret highlighting. The value indicates whether the feature is enabled or not. `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission. * * @since Chrome 51 */ export const caretHighlight: types.ChromeSetting; /** * **ChromeOS only.** * * Cursor highlighting. The value indicates whether the feature is enabled or not. `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission. * * @since Chrome 51 */ export const cursorHighlight: types.ChromeSetting; /** * **ChromeOS only.** * * 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. * * @since Chrome 85 */ export const cursorColor: types.ChromeSetting; /** * **ChromeOS only.** * * 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. * * @since Chrome 87 */ export const dockedMagnifier: types.ChromeSetting; /** * **ChromeOS only.** * * Focus highlighting. The value indicates whether the feature is enabled or not. `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission. * * @since Chrome 51 */ export const focusHighlight: types.ChromeSetting; /** * **ChromeOS only.** * * 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. * * @since Chrome 51 */ export const selectToSpeak: types.ChromeSetting; /** * **ChromeOS only.** * * Switch Access. The value indicates whether the feature is enabled or not. `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission. * * @since Chrome 51 */ export const switchAccess: types.ChromeSetting; /** * `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission. */ export const animationPolicy: types.ChromeSetting<"allowed" | "once" | "none">; /** * **ChromeOS only.** * * Dictation. The value indicates whether the feature is enabled or not. `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission. * * @since Chrome 90 */ export const dictation: types.ChromeSetting; } /** * Use the `chrome.action` API to control the extension's icon in the Google Chrome toolbar. * * @since Chrome 88 * @chrome-manifest action * @chrome-min-manifest MV3 */ export namespace action { export 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; } /** * The collection of user-specified settings relating to an extension's action. * * @since Chrome 91 */ export 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 */ export 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; } /** * @since Chrome 99 */ export interface OpenPopupOptions { /** * The ID of the window to open the action popup in. Defaults to the currently-active window if unspecified. */ windowId?: number; } /** * Fired when an action icon is clicked. This event will not fire if the action has a popup. */ export const onClicked: events.Event<( tab: tabs.Tab, ) => void>; /** * Fired when user-specified settings relating to an extension's action change. * * @since Chrome 130 */ export const onUserSettingsChanged: events.Event<( change: UserSettingsChange, ) => void>; /** * Sets the title of the action. This shows up in the tooltip. */ export function setTitle( details: { /** * 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, }, ): Promise; /** * Sets the title of the action. This shows up in the tooltip. */ export function setTitle( details: { /** * 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, }, callback?: () => void, ): void; /** * Gets the title of the action. */ export function getTitle( details: TabDetails, ): Promise; /** * Gets the title of the action. */ export function getTitle( details: TabDetails, callback?: ( result: string, ) => 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. * * @chrome-returns-extra since Chrome 96 */ export function setIcon( 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` \* 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?: extensionTypes.ImageDataType | {[name: string]: any}, /** * 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 | {[name: string]: any}, /** * Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */ tabId?: number, }, ): Promise; /** * 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. */ export function setIcon( 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` \* 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?: extensionTypes.ImageDataType | {[name: string]: any}, /** * 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 | {[name: string]: any}, /** * Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */ tabId?: number, }, callback?: () => void, ): void; /** * Sets the HTML document to be opened as a popup when the user clicks on the action's icon. */ export function setPopup( details: { /** * Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */ tabId?: number, /** * The relative path to the HTML file to show in a popup. If set to the empty string (`''`), no popup is shown. */ popup: string, }, ): Promise; /** * Sets the HTML document to be opened as a popup when the user clicks on the action's icon. */ export function setPopup( details: { /** * Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */ tabId?: number, /** * The relative path to the HTML file to show in a popup. If set to the empty string (`''`), no popup is shown. */ popup: string, }, callback?: () => void, ): void; /** * Gets the html document set as the popup for this action. */ export function getPopup( details: TabDetails, ): Promise; /** * Gets the html document set as the popup for this action. */ export function getPopup( details: TabDetails, callback?: ( result: string, ) => void, ): void; /** * Sets the badge text for the action. The badge is displayed on top of the icon. */ export function setBadgeText( details: { /** * 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, /** * Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */ tabId?: number, }, ): Promise; /** * Sets the badge text for the action. The badge is displayed on top of the icon. */ export function setBadgeText( details: { /** * 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, /** * Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */ tabId?: number, }, callback?: () => void, ): void; /** * Gets the badge text of the action. If no tab is specified, the non-tab-specific badge text is returned. If [displayActionCountAsBadgeText](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#setExtensionActionOptions) is enabled, a placeholder text will be returned unless the [declarativeNetRequestFeedback](https://developer.chrome.com/docs/extensions/develop/concepts/declare-permissions#declarativeNetRequestFeedback) permission is present or tab-specific badge text was provided. */ export function getBadgeText( details: TabDetails, ): Promise; /** * Gets the badge text of the action. If no tab is specified, the non-tab-specific badge text is returned. If [displayActionCountAsBadgeText](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#setExtensionActionOptions) is enabled, a placeholder text will be returned unless the [declarativeNetRequestFeedback](https://developer.chrome.com/docs/extensions/develop/concepts/declare-permissions#declarativeNetRequestFeedback) permission is present or tab-specific badge text was provided. */ export function getBadgeText( details: TabDetails, callback?: ( result: string, ) => void, ): void; /** * Sets the background color for the badge. */ export function setBadgeBackgroundColor( details: { /** * An array of four integers in the range \[0,255\] that make up the RGBA color of the badge. For example, opaque red is `[255, 0, 0, 255]`. Can also be a string with a CSS value, with opaque red being `#FF0000` or `#F00`. */ color: string | extensionTypes.ColorArray, /** * Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */ tabId?: number, }, ): Promise; /** * Sets the background color for the badge. */ export function setBadgeBackgroundColor( details: { /** * An array of four integers in the range \[0,255\] that make up the RGBA color of the badge. For example, opaque red is `[255, 0, 0, 255]`. Can also be a string with a CSS value, with opaque red being `#FF0000` or `#F00`. */ color: string | extensionTypes.ColorArray, /** * Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */ tabId?: number, }, callback?: () => void, ): void; /** * Gets the background color of the action. */ export function getBadgeBackgroundColor( details: TabDetails, ): Promise; /** * Gets the background color of the action. */ export function getBadgeBackgroundColor( details: TabDetails, callback?: ( result: extensionTypes.ColorArray, ) => void, ): void; /** * Sets the text color for the badge. * * @since Chrome 110 */ export function setBadgeTextColor( details: { /** * An array of four integers in the range \[0,255\] that make up the RGBA color of the badge. For example, opaque red is `[255, 0, 0, 255]`. Can also be a string with a CSS value, with opaque red being `#FF0000` or `#F00`. Not setting this value will cause a color to be automatically chosen that will contrast with the badge's background color so the text will be visible. Colors with alpha values equivalent to 0 will not be set and will return an error. */ color: string | extensionTypes.ColorArray, /** * Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */ tabId?: number, }, ): Promise; /** * Sets the text color for the badge. * * @since Chrome 110 */ export function setBadgeTextColor( details: { /** * An array of four integers in the range \[0,255\] that make up the RGBA color of the badge. For example, opaque red is `[255, 0, 0, 255]`. Can also be a string with a CSS value, with opaque red being `#FF0000` or `#F00`. Not setting this value will cause a color to be automatically chosen that will contrast with the badge's background color so the text will be visible. Colors with alpha values equivalent to 0 will not be set and will return an error. */ color: string | extensionTypes.ColorArray, /** * Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */ tabId?: number, }, callback?: () => void, ): void; /** * Gets the text color of the action. * * @since Chrome 110 */ export function getBadgeTextColor( details: TabDetails, ): Promise; /** * Gets the text color of the action. * * @since Chrome 110 */ export function getBadgeTextColor( details: TabDetails, callback?: ( result: extensionTypes.ColorArray, ) => 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. */ export function enable( tabId?: number, ): Promise; /** * 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. */ export function enable( tabId?: number, callback?: () => void, ): void; /** * Disables the action for a tab. * * @param tabId The ID of the tab for which you want to modify the action. */ export function disable( tabId?: number, ): Promise; /** * Disables the action for a tab. * * @param tabId The ID of the tab for which you want to modify the action. */ export function disable( tabId?: number, callback?: () => 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. * * @param tabId The ID of the tab for which you want check enabled status. * @since Chrome 110 */ export function isEnabled( tabId?: number, ): Promise; /** * 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. * * @param tabId The ID of the tab for which you want check enabled status. * @since Chrome 110 */ export function isEnabled( tabId?: number, /** * @param isEnabled True if the extension action is enabled. */ callback?: ( isEnabled: boolean, ) => void, ): void; /** * Returns the user-specified settings relating to an extension's action. * * @since Chrome 91 */ export function getUserSettings(): Promise; /** * Returns the user-specified settings relating to an extension's action. * * @since Chrome 91 */ export function getUserSettings( callback?: ( userSettings: UserSettings, ) => 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. * @since Chrome 127 */ export function openPopup( options?: OpenPopupOptions, ): Promise; /** * 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. * @since Chrome 127 */ export function openPopup( options?: OpenPopupOptions, callback?: () => void, ): void; } /** * Use the `chrome.alarms` API to schedule code to run periodically or at a specified time in the future. * * @chrome-permission alarms */ export namespace alarms { export interface Alarm { /** * Name of this alarm. */ name: string; /** * 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; /** * If not null, the alarm is a repeating alarm and will fire again in `periodInMinutes` minutes. */ periodInMinutes?: number; } export interface AlarmCreateInfo { /** * Time at which the alarm should fire, in milliseconds past the epoch (e.g. `Date.now() + n`). */ when?: number; /** * Length of time in minutes after which the `onAlarm` event should fire. */ delayInMinutes?: number; /** * 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; } /** * Fired when an alarm has elapsed. Useful for event pages. */ export const onAlarm: events.Event<( alarm: Alarm, ) => void>; /** * Creates an alarm. Near the time(s) specified by `alarmInfo`, 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. * * 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. * * @chrome-returns-extra since Chrome 111 * @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`. * @returns Promise that resolves when the alarm has been created. */ export function create( name: string, alarmInfo: AlarmCreateInfo, ): Promise; /** * Creates an alarm. Near the time(s) specified by `alarmInfo`, 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. * * 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. * * @chrome-returns-extra since Chrome 111 * @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`. * @returns Promise that resolves when the alarm has been created. */ export function create( alarmInfo: AlarmCreateInfo, ): Promise; /** * Creates an alarm. Near the time(s) specified by `alarmInfo`, 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. * * 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`. */ export function create( name: string, alarmInfo: AlarmCreateInfo, /** * @since Chrome 111 */ callback?: () => void, ): void; /** * Creates an alarm. Near the time(s) specified by `alarmInfo`, 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. * * 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 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`. */ export function create( alarmInfo: AlarmCreateInfo, /** * @since Chrome 111 */ callback?: () => void, ): void; /** * Retrieves details about the specified alarm. * * @chrome-returns-extra since Chrome 91 * @param name The name of the alarm to get. Defaults to the empty string. */ export function get( name?: string, ): Promise; /** * Retrieves details about the specified alarm. * * @param name The name of the alarm to get. Defaults to the empty string. */ export function get( name?: string, callback?: ( alarm?: Alarm, ) => void, ): void; /** * Gets an array of all the alarms. * * @chrome-returns-extra since Chrome 91 */ export function getAll(): Promise; /** * Gets an array of all the alarms. */ export function getAll( callback?: ( alarms: Alarm[], ) => void, ): void; /** * Clears the alarm with the given name. * * @chrome-returns-extra since Chrome 91 * @param name The name of the alarm to clear. Defaults to the empty string. */ export function clear( name?: string, ): Promise; /** * Clears the alarm with the given name. * * @param name The name of the alarm to clear. Defaults to the empty string. */ export function clear( name?: string, callback?: ( wasCleared: boolean, ) => void, ): void; /** * Clears all alarms. * * @chrome-returns-extra since Chrome 91 */ export function clearAll(): Promise; /** * Clears all alarms. */ export function clearAll( callback?: ( wasCleared: boolean, ) => void, ): void; } /** * @chrome-disallow-service-workers * @chrome-max-manifest MV2 */ export namespace app { /** * TODO (it's a manifest) */ export interface Details { } export interface DOMWindow { } /** * @since Chrome 54 */ export type InstallState = "not_installed" | "installed" | "disabled"; /** * @since Chrome 54 */ export type RunningState = "running" | "cannot_run" | "ready_to_run"; /** * @returns */ export function getIsInstalled(): boolean; /** * @chrome-returns-extra since Chrome 100 */ export function installState(): Promise; export function installState( callback?: ( state: InstallState, ) => void, ): void; export function runningState(): RunningState; /** * @returns */ export function getDetails(): Details | undefined; } /** * Use the `chrome.app.runtime` API to manage the app lifecycle. The app runtime manages app installation, controls the event page, and can shut down the app at anytime. * * @chrome-platform-apps * @chrome-platform chromeos * @chrome-platform linux * @chrome-platform mac * @chrome-platform win */ export namespace app.runtime { export interface LaunchItem { /** * Entry for the item. */ entry: Entry; /** * The MIME type of the file. */ type?: string; } /** * Enumeration of app launch sources. This should be kept in sync with AppLaunchSource in components/services/app\_service/public/mojom/types.mojom, and GetLaunchSourceEnum() in extensions/browser/api/app\_runtime/app\_runtime\_api.cc. Note the enumeration is used in UMA histogram so entries should not be re-ordered or removed. */ export type LaunchSource = "untracked" | "app_launcher" | "new_tab_page" | "reload" | "restart" | "load_and_launch" | "command_line" | "file_handler" | "url_handler" | "system_tray" | "about_page" | "keyboard" | "extensions_page" | "management_api" | "ephemeral_app" | "background" | "kiosk" | "chrome_internal" | "test" | "installed_notification" | "context_menu" | "arc" | "intent_url" | "app_home_page" | "focus_mode" | "sparky"; export interface LaunchData { /** * The ID of the file or URL handler that the app is being invoked with. Handler IDs are the top-level keys in the `file_handlers` and/or `url_handlers` dictionaries in the manifest. */ id?: string; /** * The file entries for the `onLaunched` event triggered by a matching file handler in the `file_handlers` manifest key. */ items?: LaunchItem[]; /** * The URL for the `onLaunched` event triggered by a matching URL handler in the `url_handlers` manifest key. */ url?: string; /** * The referrer URL for the `onLaunched` event triggered by a matching URL handler in the `url_handlers` manifest key. */ referrerUrl?: string; /** * Whether the app is being launched in a [Chrome OS kiosk session](https://support.google.com/chromebook/answer/3134673). */ isKioskSession?: boolean; /** * Whether the app is being launched in a [Chrome OS public session](https://support.google.com/chrome/a/answer/3017014). * * @since Chrome 47 */ isPublicSession?: boolean; /** * Where the app is launched from. */ source?: LaunchSource; } export interface EmbedRequest { embedderId: string; /** * Optional developer specified data that the app to be embedded can use when making an embedding decision. */ data?: any; /** * Allows `embedderId` to embed this app in an element. The `url` specifies the content to embed. */ allow( url: string, ): void; /** * Prevents `embedderId` from embedding this app in an element. */ deny(): void; } /** * Fired when an embedding app requests to embed this app. This event is only available on dev channel with the flag --enable-app-view. */ export const onEmbedRequested: events.Event<( request: EmbedRequest, ) => void>; /** * Fired when an app is launched from the launcher. */ export const onLaunched: events.Event<( launchData?: LaunchData, ) => void>; /** * Fired at Chrome startup to apps that were running when Chrome last shut down, or when apps have been requested to restart from their previous state for other reasons (e.g. when the user revokes access to an app's retained files the runtime will restart the app). In these situations if apps do not have an `onRestarted` handler they will be sent an `onLaunched` event instead. */ export const onRestarted: events.Event<() => void>; } /** * Use the `chrome.app.window` API to create windows. Windows have an optional frame with title bar and size controls. They are not associated with any Chrome browser windows. See the [Window State Sample](https://github.com/GoogleChrome/chrome-app-samples/tree/master/samples/window-state) for a demonstration of these options. * * @chrome-platform-apps * @chrome-platform chromeos * @chrome-platform linux * @chrome-platform mac * @chrome-platform win */ export namespace app.window { export interface ContentBounds { left?: number; top?: number; width?: number; height?: number; } export interface BoundsSpecification { /** * The X coordinate of the content or window. */ left?: number; /** * The Y coordinate of the content or window. */ top?: number; /** * The width of the content or window. */ width?: number; /** * The height of the content or window. */ height?: number; /** * The minimum width of the content or window. */ minWidth?: number; /** * The minimum height of the content or window. */ minHeight?: number; /** * The maximum width of the content or window. */ maxWidth?: number; /** * The maximum height of the content or window. */ maxHeight?: number; } export interface Bounds { /** * This property can be used to read or write the current X coordinate of the content or window. */ left: number; /** * This property can be used to read or write the current Y coordinate of the content or window. */ top: number; /** * This property can be used to read or write the current width of the content or window. */ width: number; /** * This property can be used to read or write the current height of the content or window. */ height: number; /** * This property can be used to read or write the current minimum width of the content or window. A value of `null` indicates 'unspecified'. */ minWidth?: number; /** * This property can be used to read or write the current minimum height of the content or window. A value of `null` indicates 'unspecified'. */ minHeight?: number; /** * This property can be used to read or write the current maximum width of the content or window. A value of `null` indicates 'unspecified'. */ maxWidth?: number; /** * This property can be used to read or write the current maximum height of the content or window. A value of `null` indicates 'unspecified'. */ maxHeight?: number; /** * Set the left and top position of the content or window. */ setPosition( left: number, top: number, ): void; /** * Set the width and height of the content or window. */ setSize( width: number, height: number, ): void; /** * Set the minimum size constraints of the content or window. The minimum width or height can be set to `null` to remove the constraint. A value of `undefined` will leave a constraint unchanged. */ setMinimumSize( minWidth: number, minHeight: number, ): void; /** * Set the maximum size constraints of the content or window. The maximum width or height can be set to `null` to remove the constraint. A value of `undefined` will leave a constraint unchanged. */ setMaximumSize( maxWidth: number, maxHeight: number, ): void; } export interface FrameOptions { /** * Frame type: `none` or `chrome` (defaults to `chrome`). * * For `none`, the `-webkit-app-region` CSS property can be used to apply draggability to the app's window. * * `-webkit-app-region: drag` can be used to mark regions draggable. `no-drag` can be used to disable this style on nested elements. */ type?: string; /** * Allows the frame color to be set. Frame coloring is only available if the frame type is `chrome`. * * Frame coloring is new in Chrome 36. */ color?: string; /** * Allows the frame color of the window when active to be set. Frame coloring is only available if the frame type is `chrome`. * * Frame coloring is only available if the frame type is `chrome`. * * Frame coloring is new in Chrome 36. */ activeColor?: string; /** * Allows the frame color of the window when inactive to be set differently to the active color. Frame coloring is only available if the frame type is `chrome`. * * `inactiveColor` must be used in conjunction with `color`. * * Frame coloring is new in Chrome 36. */ inactiveColor?: string; } /** * State of a window: normal, fullscreen, maximized, minimized. */ export type State = "normal" | "fullscreen" | "maximized" | "minimized"; /** * Specifies the type of window to create. * * @chrome-enum "shell" Default window type. * @chrome-enum "panel" OS managed window (Deprecated). * @since Chrome 45 */ export type WindowType = "shell" | "panel"; export interface CreateWindowOptions { /** * Id to identify the window. This will be used to remember the size and position of the window and restore that geometry when a window with the same id is later opened. If a window with a given id is created while another window with the same id already exists, the currently opened window will be focused instead of creating a new window. */ id?: string; /** * Used to specify the initial position, initial size and constraints of the window's content (excluding window decorations). If an `id` is also specified and a window with a matching `id` has been shown before, the remembered bounds will be used instead. * * Note that the padding between the inner and outer bounds is determined by the OS. Therefore setting the same bounds property for both the `innerBounds` and `outerBounds` will result in an error. * * This property is new in Chrome 36. */ innerBounds?: BoundsSpecification; /** * Used to specify the initial position, initial size and constraints of the window (including window decorations such as the title bar and frame). If an `id` is also specified and a window with a matching `id` has been shown before, the remembered bounds will be used instead. * * Note that the padding between the inner and outer bounds is determined by the OS. Therefore setting the same bounds property for both the `innerBounds` and `outerBounds` will result in an error. * * This property is new in Chrome 36. */ outerBounds?: BoundsSpecification; /** * Minimum width of the window. * * @deprecated Use innerBounds or outerBounds. */ minWidth?: number; /** * Minimum height of the window. * * @deprecated Use innerBounds or outerBounds. */ minHeight?: number; /** * Maximum width of the window. * * @deprecated Use innerBounds or outerBounds. */ maxWidth?: number; /** * Maximum height of the window. * * @deprecated Use innerBounds or outerBounds. */ maxHeight?: number; /** * Type of window to create. * * @deprecated All app windows use the 'shell' window type * @since Chrome 45 * @chrome-deprecated-since Chrome 69 */ type?: WindowType; /** * If true, the window will have its own shelf icon. Otherwise the window will be grouped in the shelf with other windows that are associated with the app. Defaults to false. If showInShelf is set to true you need to specify an id for the window. * * @since Chrome 54 */ showInShelf?: boolean; /** * URL of the window icon. A window can have its own icon when showInShelf is set to true. The URL should be a global or an extension local URL. * * @since Chrome 54 */ icon?: string; /** * Frame type: `none` or `chrome` (defaults to `chrome`). For `none`, the `-webkit-app-region` CSS property can be used to apply draggability to the app's window. `-webkit-app-region: drag` can be used to mark regions draggable. `no-drag` can be used to disable this style on nested elements. * * Use of `FrameOptions` is new in M36. */ frame?: string | FrameOptions; /** * Size and position of the content in the window (excluding the titlebar). If an id is also specified and a window with a matching id has been shown before, the remembered bounds of the window will be used instead. * * @deprecated Use innerBounds or outerBounds. */ bounds?: ContentBounds; /** * The initial state of the window, allowing it to be created already fullscreen, maximized, or minimized. Defaults to 'normal'. */ state?: State; /** * If true, the window will be created in a hidden state. Call show() on the window to show it once it has been created. Defaults to false. */ hidden?: boolean; /** * If true, the window will be resizable by the user. Defaults to true. */ resizable?: boolean; /** * By default if you specify an id for the window, the window will only be created if another window with the same id doesn't already exist. If a window with the same id already exists that window is activated instead. If you do want to create multiple windows with the same id, you can set this property to false. * * @deprecated Multiple windows with the same id is no longer supported. */ singleton?: boolean; /** * If true, the window will stay above most other windows. If there are multiple windows of this kind, the currently focused window will be in the foreground. Requires the `alwaysOnTopWindows` permission. Defaults to false. * * Call `setAlwaysOnTop()` on the window to change this property after creation. */ alwaysOnTop?: boolean; /** * If true, the window will be focused when created. Defaults to true. */ focused?: boolean; /** * If true, and supported by the platform, the window will be visible on all workspaces. */ visibleOnAllWorkspaces?: boolean; } export interface AppWindow { /** * Focus the window. */ focus(): void; /** * Fullscreens the window. * * The user will be able to restore the window by pressing ESC. An application can prevent the fullscreen state to be left when ESC is pressed by requesting the `app.window.fullscreen.overrideEsc` permission and canceling the event by calling .preventDefault(), in the keydown and keyup handlers, like this: * * `window.onkeydown = window.onkeyup = function(e) { if (e.keyCode == 27 /* ESC *\/) { e.preventDefault(); } };` * * Note `window.fullscreen()` will cause the entire window to become fullscreen and does not require a user gesture. The HTML5 fullscreen API can also be used to enter fullscreen mode (see [Web APIs](https://developer.chrome.com/docs/apps/api_other) for more details). */ fullscreen(): void; /** * Is the window fullscreen? This will be true if the window has been created fullscreen or was made fullscreen via the `AppWindow` or HTML5 fullscreen APIs. */ isFullscreen(): boolean; /** * Minimize the window. */ minimize(): void; /** * Is the window minimized? */ isMinimized(): boolean; /** * Maximize the window. */ maximize(): void; /** * Is the window maximized? */ isMaximized(): boolean; /** * Restore the window, exiting a maximized, minimized, or fullscreen state. */ restore(): void; /** * Move the window to the position (`left`, `top`). * * @deprecated Use outerBounds. * @chrome-deprecated-since Chrome 43 */ moveTo( left: number, top: number, ): void; /** * Resize the window to `width`x`height` pixels in size. * * @deprecated Use outerBounds. * @chrome-deprecated-since Chrome 43 */ resizeTo( width: number, height: number, ): void; /** * Draw attention to the window. */ drawAttention(): void; /** * Clear attention to the window. */ clearAttention(): void; /** * Close the window. */ close(): void; /** * Show the window. Does nothing if the window is already visible. Focus the window if `focused` is set to true or omitted. */ show( focused?: boolean, ): void; /** * Hide the window. Does nothing if the window is already hidden. */ hide(): void; /** * Get the window's inner bounds as a {@link ContentBounds} object. * * @deprecated Use innerBounds or outerBounds. */ getBounds(): ContentBounds | undefined; /** * Set the window's inner bounds. * * @deprecated Use innerBounds or outerBounds. */ setBounds( bounds: ContentBounds, ): void; /** * Is the window always on top? */ isAlwaysOnTop(): boolean; /** * Set whether the window should stay above most other windows. Requires the `alwaysOnTopWindows` permission. */ setAlwaysOnTop( alwaysOnTop: boolean, ): void; /** * Set whether the window is visible on all workspaces. (Only for platforms that support this). */ setVisibleOnAllWorkspaces( alwaysVisible: boolean, ): void; /** * The JavaScript 'window' object for the created child. */ contentWindow: Window; /** * The id the window was created with. */ id: string; /** * The position, size and constraints of the window's content, which does not include window decorations. This property is new in Chrome 36. */ innerBounds: Bounds; /** * The position, size and constraints of the window, which includes window decorations, such as the title bar and frame. This property is new in Chrome 36. */ outerBounds: Bounds; } /** * Fired when the window is resized. */ export const onBoundsChanged: events.Event<() => void>; /** * Fired when the window is closed. Note, this should be listened to from a window other than the window being closed, for example from the background page. This is because the window being closed will be in the process of being torn down when the event is fired, which means not all APIs in the window's script context will be functional. */ export const onClosed: events.Event<() => void>; /** * Fired when the window is fullscreened (either via the `AppWindow` or HTML5 APIs). */ export const onFullscreened: events.Event<() => void>; /** * Fired when the window is maximized. */ export const onMaximized: events.Event<() => void>; /** * Fired when the window is minimized. */ export const onMinimized: events.Event<() => void>; /** * Fired when the window is restored from being minimized or maximized. */ export const onRestored: events.Event<() => void>; /** * The size and position of a window can be specified in a number of different ways. The most simple option is not specifying anything at all, in which case a default size and platform dependent position will be used. * * To set the position, size and constraints of the window, use the `innerBounds` or `outerBounds` properties. Inner bounds do not include window decorations. Outer bounds include the window's title bar and frame. Note that the padding between the inner and outer bounds is determined by the OS. Therefore setting the same property for both inner and outer bounds is considered an error (for example, setting both `innerBounds.left` and `outerBounds.left`). * * To automatically remember the positions of windows you can give them ids. If a window has an id, This id is used to remember the size and position of the window whenever it is moved or resized. This size and position is then used instead of the specified bounds on subsequent opening of a window with the same id. If you need to open a window with an id at a location other than the remembered default, you can create it hidden, move it to the desired location, then show it. * * @chrome-returns-extra since Chrome 117 */ export function create( url: string, options?: CreateWindowOptions, ): Promise; /** * The size and position of a window can be specified in a number of different ways. The most simple option is not specifying anything at all, in which case a default size and platform dependent position will be used. * * To set the position, size and constraints of the window, use the `innerBounds` or `outerBounds` properties. Inner bounds do not include window decorations. Outer bounds include the window's title bar and frame. Note that the padding between the inner and outer bounds is determined by the OS. Therefore setting the same property for both inner and outer bounds is considered an error (for example, setting both `innerBounds.left` and `outerBounds.left`). * * To automatically remember the positions of windows you can give them ids. If a window has an id, This id is used to remember the size and position of the window whenever it is moved or resized. This size and position is then used instead of the specified bounds on subsequent opening of a window with the same id. If you need to open a window with an id at a location other than the remembered default, you can create it hidden, move it to the desired location, then show it. */ export function create( url: string, options?: CreateWindowOptions, callback?: ( createdWindow: AppWindow, ) => void, ): void; /** * Returns an {@link AppWindow} object for the current script context (ie JavaScript 'window' object). This can also be called on a handle to a script context for another page, for example: otherWindow.chrome.app.window.current(). */ export function current(): AppWindow | undefined; /** * Gets an array of all currently created app windows. This method is new in Chrome 33. */ export function getAll(): AppWindow[]; /** * Gets an {@link AppWindow} with the given id. If no window with the given id exists null is returned. This method is new in Chrome 33. */ export function get( id: string, ): AppWindow | undefined; /** * Whether the current platform supports windows being visible on all workspaces. */ export function canSetVisibleOnAllWorkspaces(): boolean; } /** * Use the `appview` tag to embed other Chrome Apps within your Chrome App. (see [Usage](#usage)). * * @since Chrome 43 * @chrome-permission appview * @chrome-platform-apps * @chrome-platform chromeos * @chrome-platform linux * @chrome-platform mac * @chrome-platform win */ export namespace appviewTag { export interface EmbedRequest { /** * The ID of the app that sent the embedding request. */ embedderId: string; /** * Optional developer specified data that the app to be embedded can use when making an embedding decision. */ data: {[name: string]: any}; /** * Allows the embedding request. * * @param url Specifies the content to be embedded. */ allow( url: string, ): void; /** * Prevents the embedding request. */ deny(): void; } /** * Requests another app to be embedded. * * @chrome-returns-extra since Chrome 132 * @param app The extension id of the app to be embedded. * @param data Optional developer specified data that the app to be embedded can use when making an embedding decision. */ export function connect( app: string, data?: any, ): Promise; /** * Requests another app to be embedded. * * @param app The extension id of the app to be embedded. * @param data Optional developer specified data that the app to be embedded can use when making an embedding decision. */ export function connect( app: string, data?: any, /** * @param success True if the embedding request succeded. */ callback?: ( success: boolean, ) => void, ): void; } /** * 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. * * @since Chrome 59 * @chrome-permission audio * @chrome-platform chromeos */ export namespace audio { /** * Type of stream an audio device provides. */ export type StreamType = "INPUT" | "OUTPUT"; /** * Available audio device types. */ export type DeviceType = "HEADPHONE" | "MIC" | "USB" | "BLUETOOTH" | "HDMI" | "INTERNAL_SPEAKER" | "INTERNAL_MIC" | "FRONT_MIC" | "REAR_MIC" | "KEYBOARD_MIC" | "HOTWORD" | "LINEOUT" | "POST_MIX_LOOPBACK" | "POST_DSP_LOOPBACK" | "ALSA_LOOPBACK" | "OTHER"; export interface AudioDeviceInfo { /** * The unique identifier of the audio device. */ id: string; /** * Stream type associated with this device. */ streamType: StreamType; /** * Type of the device. */ deviceType: DeviceType; /** * The user-friendly name (e.g. "USB Microphone"). */ displayName: string; /** * Device name. */ deviceName: 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; } export interface DeviceFilter { /** * If set, only audio devices whose stream type is included in this list will satisfy the filter. */ streamTypes?: StreamType[]; /** * If set, only audio devices whose active state matches this value will satisfy the filter. */ isActive?: boolean; } export 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; } export 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[]; } export interface MuteChangedEvent { /** * 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; /** * Whether or not the stream is now muted. */ isMuted: boolean; } export interface LevelChangedEvent { /** * ID of device whose sound level has changed. */ deviceId: string; /** * The device's new sound level. */ level: number; } /** * Fired when sound level changes for an active audio device. */ export const onLevelChanged: 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. */ export const onMuteChanged: events.Event<( event: MuteChangedEvent, ) => void>; /** * Fired when audio devices change, either new devices being added, or existing devices being removed. */ export const onDeviceListChanged: events.Event<( devices: AudioDeviceInfo[], ) => void>; /** * Gets a list of audio devices filtered based on `filter`. * * @chrome-returns-extra since Chrome 116 * @param filter Device properties by which to filter the list of returned audio devices. If the filter is not set or set to `{}`, returned device list will contain all available audio devices. * @returns Reports the requested list of audio devices. */ export function getDevices( filter?: DeviceFilter, ): Promise; /** * Gets a list of audio devices filtered based on `filter`. * * @param filter Device properties by which to filter the list of returned audio devices. If the filter is not set or set to `{}`, returned device list will contain all available audio devices. */ export function getDevices( filter?: DeviceFilter, callback?: ( devices: AudioDeviceInfo[], ) => void, ): void; /** * Sets lists of active input and/or output devices. * * @chrome-returns-extra since Chrome 116 * @param ids Specifies IDs of devices that should be active. If either the input or output list is not set, devices in that category are unaffected. It is an error to pass in a non-existent device ID. */ export function setActiveDevices( ids: DeviceIdLists, ): Promise; /** * Sets lists of active input and/or output devices. * * @param ids Specifies IDs of devices that should be active. If either the input or output list is not set, devices in that category are unaffected. It is an error to pass in a non-existent device ID. */ export function setActiveDevices( ids: DeviceIdLists, callback?: () => void, ): void; /** * Sets the properties for the input or output device. * * @chrome-returns-extra since Chrome 116 */ export function setProperties( id: string, properties: DeviceProperties, ): Promise; /** * Sets the properties for the input or output device. */ export function setProperties( id: string, properties: DeviceProperties, callback?: () => void, ): void; /** * Gets the system-wide mute state for the specified stream type. * * @chrome-returns-extra since Chrome 116 * @param streamType Stream type for which mute state should be fetched. * @returns Promise that resolves with a boolean indicating whether mute is set or not for specified stream type. */ export function getMute( streamType: StreamType, ): Promise; /** * Gets the system-wide mute state for the specified stream type. * * @param streamType Stream type for which mute state should be fetched. */ export function getMute( streamType: StreamType, callback?: ( value: boolean, ) => void, ): void; /** * Sets mute state for a stream type. The mute state will apply to all audio devices with the specified audio stream type. * * @chrome-returns-extra since Chrome 116 * @param streamType Stream type for which mute state should be set. * @param isMuted New mute value. */ export function setMute( streamType: StreamType, isMuted: boolean, ): Promise; /** * Sets mute state for a stream type. The mute state will apply to all audio devices with the specified audio stream type. * * @param streamType Stream type for which mute state should be set. * @param isMuted New mute value. */ export function setMute( streamType: StreamType, isMuted: boolean, callback?: () => void, ): void; } /** * Use the `chrome.bluetooth` API to connect to a Bluetooth device. All functions report failures via chrome.runtime.lastError. * * @chrome-manifest bluetooth * @chrome-platform-apps * @chrome-platform chromeos * @chrome-platform linux * @chrome-platform mac * @chrome-platform win */ export namespace bluetooth { /** * Allocation authorities for Vendor IDs. */ export type VendorIdSource = "bluetooth" | "usb"; /** * Common device types recognized by Chrome. */ export type DeviceType = "computer" | "phone" | "modem" | "audio" | "carAudio" | "video" | "peripheral" | "joystick" | "gamepad" | "keyboard" | "mouse" | "tablet" | "keyboardMouseCombo"; /** * Types for filtering bluetooth devices. * * @since Chrome 67 */ export type FilterType = "all" | "known"; /** * Transport type of the bluetooth device. * * @since Chrome 76 */ export type Transport = "invalid" | "classic" | "le" | "dual"; export interface AdapterState { /** * The address of the adapter, in the format 'XX:XX:XX:XX:XX:XX'. */ address: string; /** * The human-readable name of the adapter. */ name: string; /** * Indicates whether or not the adapter has power. */ powered: boolean; /** * Indicates whether or not the adapter is available (i.e. enabled). */ available: boolean; /** * Indicates whether or not the adapter is currently discovering. */ discovering: boolean; } export interface Device { /** * The address of the device, in the format 'XX:XX:XX:XX:XX:XX'. */ address: string; /** * The human-readable name of the device. */ name?: string; /** * The class of the device, a bit-field defined by http://www.bluetooth.org/en-us/specification/assigned-numbers/baseband. */ deviceClass?: number; /** * The Device ID record of the device, where available. */ vendorIdSource?: VendorIdSource; vendorId?: number; productId?: number; deviceId?: number; /** * The type of the device, if recognized by Chrome. This is obtained from the `deviceClass` field and only represents a small fraction of the possible device types. When in doubt you should use the `deviceClass` field directly. */ type?: DeviceType; /** * Indicates whether or not the device is paired with the system. */ paired?: boolean; /** * Indicates whether the device is currently connected to the system. */ connected?: boolean; /** * Indicates whether the device is currently connecting to the system. * * @since Chrome 48 */ connecting?: boolean; /** * Indicates whether the device is connectable. * * @since Chrome 48 */ connectable?: boolean; /** * UUIDs of protocols, profiles and services advertised by the device. For classic Bluetooth devices, this list is obtained from EIR data and SDP tables. For Low Energy devices, this list is obtained from AD and GATT primary services. For dual mode devices this may be obtained from both. */ uuids?: string[]; /** * The received signal strength, in dBm. This field is avaliable and valid only during discovery. Outside of discovery it's value is not specified. * * @since Chrome 44 */ inquiryRssi?: number; /** * The transmitted power level. This field is avaliable only for LE devices that include this field in AD. It is avaliable and valid only during discovery. * * @since Chrome 44 */ inquiryTxPower?: number; /** * The transport type of the bluetooth device. * * @since Chrome 76 */ transport?: Transport; /** * The remaining battery of the device. * * @since Chrome 77 */ batteryPercentage?: number; } /** * @since Chrome 67 */ export interface BluetoothFilter { /** * Type of filter to apply to the device list. Default is all. */ filterType?: FilterType; /** * Maximum number of bluetooth devices to return. Default is 0 (no limit) if unspecified. */ limit?: number; } /** * Fired when the state of the Bluetooth adapter changes. */ export const onAdapterStateChanged: events.Event<( state: AdapterState, ) => void>; /** * Fired when information about a new Bluetooth device is available. */ export const onDeviceAdded: events.Event<( device: Device, ) => void>; /** * Fired when information about a known Bluetooth device has changed. */ export const onDeviceChanged: events.Event<( device: Device, ) => void>; /** * Fired when a Bluetooth device that was previously discovered has been out of range for long enough to be considered unavailable again, and when a paired device is removed. */ export const onDeviceRemoved: events.Event<( device: Device, ) => void>; /** * Get information about the Bluetooth adapter. * * @chrome-returns-extra since Chrome 91 */ export function getAdapterState(): Promise; /** * Get information about the Bluetooth adapter. */ export function getAdapterState( /** * @param adapterInfo Object containing the adapter information. */ callback?: ( adapterInfo: AdapterState, ) => void, ): void; /** * Get information about a Bluetooth device known to the system. * * @chrome-returns-extra since Chrome 91 * @param deviceAddress Address of device to get. */ export function getDevice( deviceAddress: string, ): Promise; /** * Get information about a Bluetooth device known to the system. * * @param deviceAddress Address of device to get. */ export function getDevice( deviceAddress: string, /** * @param deviceInfo Object containing the device information. */ callback?: ( deviceInfo: Device, ) => void, ): void; /** * Get a list of Bluetooth devices known to the system, including paired and recently discovered devices. * * @chrome-returns-extra since Chrome 91 * @param filter Some criteria to filter the list of returned bluetooth devices. If the filter is not set or set to `{}`, returned device list will contain all bluetooth devices. Right now this is only supported in ChromeOS, for other platforms, a full list is returned. */ export function getDevices( /** * @since Chrome 67 */ filter?: BluetoothFilter, ): Promise; /** * Get a list of Bluetooth devices known to the system, including paired and recently discovered devices. * * @param filter Some criteria to filter the list of returned bluetooth devices. If the filter is not set or set to `{}`, returned device list will contain all bluetooth devices. Right now this is only supported in ChromeOS, for other platforms, a full list is returned. */ export function getDevices( /** * @since Chrome 67 */ filter?: BluetoothFilter, /** * @param deviceInfos Array of object containing device information. */ callback?: ( deviceInfos: Device[], ) => void, ): void; /** * Start discovery. Newly discovered devices will be returned via the onDeviceAdded event. Previously discovered devices already known to the adapter must be obtained using getDevices and will only be updated using the `onDeviceChanged` event if information about them changes. * * Discovery will fail to start if this application has already called startDiscovery. Discovery can be resource intensive: stopDiscovery should be called as soon as possible. * * @chrome-returns-extra since Chrome 91 */ export function startDiscovery(): Promise; /** * Start discovery. Newly discovered devices will be returned via the onDeviceAdded event. Previously discovered devices already known to the adapter must be obtained using getDevices and will only be updated using the `onDeviceChanged` event if information about them changes. * * Discovery will fail to start if this application has already called startDiscovery. Discovery can be resource intensive: stopDiscovery should be called as soon as possible. */ export function startDiscovery( callback?: () => void, ): void; /** * Stop discovery. * * @chrome-returns-extra since Chrome 91 */ export function stopDiscovery(): Promise; /** * Stop discovery. */ export function stopDiscovery( callback?: () => void, ): void; } /** * The `chrome.bluetoothLowEnergy` API is used to communicate with Bluetooth Smart (Low Energy) devices using the [Generic Attribute Profile (GATT)](https://developer.bluetooth.org/TechnologyOverview/Pages/GATT.aspx). * * @chrome-manifest bluetooth * @chrome-platform-apps * @chrome-platform chromeos * @chrome-platform linux * @chrome-platform win * @chrome-platform mac */ export namespace bluetoothLowEnergy { /** * Values representing the possible properties of a characteristic. Characteristic permissions are inferred from these properties. Please see the Bluetooth 4.x spec to see the meaning of each individual property. */ export type CharacteristicProperty = "broadcast" | "read" | "writeWithoutResponse" | "write" | "notify" | "indicate" | "authenticatedSignedWrites" | "extendedProperties" | "reliableWrite" | "writableAuxiliaries" | "encryptRead" | "encryptWrite" | "encryptAuthenticatedRead" | "encryptAuthenticatedWrite"; /** * Values representing possible permissions for a descriptor. Please see the Bluetooth 4.x spec to see the meaning of each individual permission. * * @since Chrome 52 */ export type DescriptorPermission = "read" | "write" | "encryptedRead" | "encryptedWrite" | "encryptedAuthenticatedRead" | "encryptedAuthenticatedWrite"; /** * Type of advertisement. If 'broadcast' is chosen, the sent advertisement type will be ADV\_NONCONN\_IND and the device will broadcast with a random MAC Address. If set to 'peripheral', the advertisement type will be ADV\_IND or ADV\_SCAN\_IND and the device will broadcast with real Bluetooth Adapter's MAC Address. * * @since Chrome 47 */ export type AdvertisementType = "broadcast" | "peripheral"; /** * @since Chrome 52 */ export interface Device { /** * The address of the device, in the format 'XX:XX:XX:XX:XX:XX'. */ address: string; /** * The human-readable name of the device. */ name?: string; /** * The class of the device, a bit-field defined by http://www.bluetooth.org/en-us/specification/assigned-numbers/baseband. */ deviceClass?: number; } export interface Service { /** * The UUID of the service, e.g. 0000180d-0000-1000-8000-00805f9b34fb. */ uuid: string; /** * Indicates whether the type of this service is primary or secondary. */ isPrimary: boolean; /** * Returns the identifier assigned to this service. Use the instance ID to distinguish between services from a peripheral with the same UUID and to make function calls that take in a service identifier. Present, if this instance represents a remote service. */ instanceId?: string; /** * The device address of the remote peripheral that the GATT service belongs to. Present, if this instance represents a remote service. */ deviceAddress?: string; } export interface Characteristic { /** * The UUID of the characteristic, e.g. 00002a37-0000-1000-8000-00805f9b34fb. */ uuid: string; /** * The GATT service this characteristic belongs to. */ service?: Service; /** * The properties of this characteristic. */ properties: CharacteristicProperty[]; /** * Returns the identifier assigned to this characteristic. Use the instance ID to distinguish between characteristics from a peripheral with the same UUID and to make function calls that take in a characteristic identifier. Present, if this instance represents a remote characteristic. */ instanceId?: string; /** * The currently cached characteristic value. This value gets updated when the value of the characteristic is read or updated via a notification or indication. */ value?: ArrayBuffer; } export interface Descriptor { /** * The UUID of the characteristic descriptor, e.g. 00002902-0000-1000-8000-00805f9b34fb. */ uuid: string; /** * The GATT characteristic this descriptor belongs to. */ characteristic?: Characteristic; /** * The permissions of this descriptor. * * @since Chrome 52 */ permissions: DescriptorPermission[]; /** * Returns the identifier assigned to this descriptor. Use the instance ID to distinguish between descriptors from a peripheral with the same UUID and to make function calls that take in a descriptor identifier. Present, if this instance represents a remote characteristic. */ instanceId?: string; /** * The currently cached descriptor value. This value gets updated when the value of the descriptor is read. */ value?: ArrayBuffer; } export interface ConnectProperties { /** * Flag indicating whether a connection to the device is left open when the event page of the application is unloaded (see [Manage App Lifecycle](https://developer.chrome.com/docs/apps/app_lifecycle)). The default value is `false.` */ persistent: boolean; } export interface NotificationProperties { /** * Flag indicating whether the app should receive notifications when the event page of the application is unloaded (see [Manage App Lifecycle](https://developer.chrome.com/docs/apps/app_lifecycle)). The default value is `false`. */ persistent: boolean; } /** * @since Chrome 47 */ export interface ManufacturerData { id: number; data: number[]; } /** * @since Chrome 47 */ export interface ServiceData { uuid: string; data: number[]; } /** * @since Chrome 47 */ export interface Advertisement { /** * Type of advertisement. */ type: AdvertisementType; /** * List of UUIDs to include in the "Service UUIDs" field of the Advertising Data. These UUIDs can be of the 16bit, 32bit or 128 formats. */ serviceUuids?: string[]; /** * List of manufacturer specific data to be included in "Manufacturer Specific Data" fields of the advertising data. */ manufacturerData?: ManufacturerData[]; /** * List of UUIDs to include in the "Solicit UUIDs" field of the Advertising Data. These UUIDs can be of the 16bit, 32bit or 128 formats. */ solicitUuids?: string[]; /** * List of service data to be included in "Service Data" fields of the advertising data. */ serviceData?: ServiceData[]; } /** * @since Chrome 52 */ export interface Request { /** * Unique ID for this request. Use this ID when responding to this request. */ requestId: number; /** * Device that send this request. */ device: Device; /** * Value to write (if this is a write request). */ value?: ArrayBuffer; } /** * @since Chrome 52 */ export interface Response { /** * Id of the request this is a response to. */ requestId: number; /** * If this is an error response, this should be true. */ isError: boolean; /** * Response value. Write requests and error responses will ignore this parameter. */ value?: ArrayBuffer; } /** * @since Chrome 52 */ export interface Notification { /** * New value of the characteristic. */ value: ArrayBuffer; /** * Optional flag for sending an indication instead of a notification. */ shouldIndicate?: boolean; } /** * Fired whan a new GATT service has been discovered on a remote device. */ export const onServiceAdded: events.Event<( service: Service, ) => void>; /** * Fired when the state of a remote GATT service changes. This involves any characteristics and/or descriptors that get added or removed from the service, as well as "ServiceChanged" notifications from the remote device. */ export const onServiceChanged: events.Event<( service: Service, ) => void>; /** * Fired when a GATT service that was previously discovered on a remote device has been removed. */ export const onServiceRemoved: events.Event<( service: Service, ) => void>; /** * Fired when the value of a remote GATT characteristic changes, either as a result of a read request, or a value change notification/indication This event will only be sent if the app has enabled notifications by calling {@link startCharacteristicNotifications}. */ export const onCharacteristicValueChanged: events.Event<( characteristic: Characteristic, ) => void>; /** * Fired when the value of a remote GATT characteristic descriptor changes, usually as a result of a read request. This event exists mostly for convenience and will always be sent after a successful call to {@link readDescriptorValue}. */ export const onDescriptorValueChanged: events.Event<( descriptor: Descriptor, ) => void>; /** * Fired when a connected central device requests to read the value of a characteristic registered on the local GATT server. Not responding to this request for a long time may lead to a disconnection. This event is only available if the app has both the bluetooth:low\_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps. * * @since Chrome 52 */ export const onCharacteristicReadRequest: events.Event<( request: Request, characteristicId: string, ) => void>; /** * Fired when a connected central device requests to write the value of a characteristic registered on the local GATT server. Not responding to this request for a long time may lead to a disconnection. This event is only available if the app has both the bluetooth:low\_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps. * * @since Chrome 52 */ export const onCharacteristicWriteRequest: events.Event<( request: Request, characteristicId: string, ) => void>; /** * Fired when a connected central device requests to read the value of a descriptor registered on the local GATT server. Not responding to this request for a long time may lead to a disconnection. This event is only available if the app has both the bluetooth:low\_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps. * * @since Chrome 52 */ export const onDescriptorReadRequest: events.Event<( request: Request, descriptorId: string, ) => void>; /** * Fired when a connected central device requests to write the value of a descriptor registered on the local GATT server. Not responding to this request for a long time may lead to a disconnection. This event is only available if the app has both the bluetooth:low\_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps. * * @since Chrome 52 */ export const onDescriptorWriteRequest: events.Event<( request: Request, descriptorId: string, ) => void>; /** * Establishes a connection between the application and the device with the given address. A device may be already connected and its GATT services available without calling `connect`, however, an app that wants to access GATT services of a device should call this function to make sure that a connection to the device is maintained. If the device is not connected, all GATT services of the device will be discovered after a successful call to `connect`. * * @chrome-returns-extra since Chrome 91 * @param deviceAddress The Bluetooth address of the remote device to which a GATT connection should be opened. * @param properties Connection properties (optional). */ export function connect( deviceAddress: string, properties?: ConnectProperties, ): Promise; /** * Establishes a connection between the application and the device with the given address. A device may be already connected and its GATT services available without calling `connect`, however, an app that wants to access GATT services of a device should call this function to make sure that a connection to the device is maintained. If the device is not connected, all GATT services of the device will be discovered after a successful call to `connect`. * * @param deviceAddress The Bluetooth address of the remote device to which a GATT connection should be opened. * @param properties Connection properties (optional). */ export function connect( deviceAddress: string, properties?: ConnectProperties, callback?: () => void, ): void; /** * Closes the app's connection to the device with the given address. Note that this will not always destroy the physical link itself, since there may be other apps with open connections. * * @chrome-returns-extra since Chrome 91 * @param deviceAddress The Bluetooth address of the remote device. */ export function disconnect( deviceAddress: string, ): Promise; /** * Closes the app's connection to the device with the given address. Note that this will not always destroy the physical link itself, since there may be other apps with open connections. * * @param deviceAddress The Bluetooth address of the remote device. */ export function disconnect( deviceAddress: string, callback?: () => void, ): void; /** * Get the GATT service with the given instance ID. * * @chrome-returns-extra since Chrome 91 * @param serviceId The instance ID of the requested GATT service. */ export function getService( serviceId: string, ): Promise; /** * Get the GATT service with the given instance ID. * * @param serviceId The instance ID of the requested GATT service. */ export function getService( serviceId: string, callback?: ( result: Service, ) => void, ): void; /** * Create a locally hosted GATT service. This service can be registered to be available on a local GATT server. This function is only available if the app has both the bluetooth:low\_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps. * * @chrome-returns-extra since Chrome 91 * @param service The service to create. * @since Chrome 52 */ export function createService( service: Service, ): Promise; /** * Create a locally hosted GATT service. This service can be registered to be available on a local GATT server. This function is only available if the app has both the bluetooth:low\_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps. * * @param service The service to create. * @since Chrome 52 */ export function createService( service: Service, callback?: ( serviceId: string, ) => void, ): void; /** * Get all the GATT services that were discovered on the remote device with the given device address. * * _Note:_ If service discovery is not yet complete on the device, this API will return a subset (possibly empty) of services. A work around is to add a time based delay and/or call repeatedly until the expected number of services is returned. * * @chrome-returns-extra since Chrome 91 * @param deviceAddress The Bluetooth address of the remote device whose GATT services should be returned. */ export function getServices( deviceAddress: string, ): Promise; /** * Get all the GATT services that were discovered on the remote device with the given device address. * * _Note:_ If service discovery is not yet complete on the device, this API will return a subset (possibly empty) of services. A work around is to add a time based delay and/or call repeatedly until the expected number of services is returned. * * @param deviceAddress The Bluetooth address of the remote device whose GATT services should be returned. */ export function getServices( deviceAddress: string, callback?: ( result: Service[], ) => void, ): void; /** * Get the GATT characteristic with the given instance ID that belongs to the given GATT service, if the characteristic exists. * * @chrome-returns-extra since Chrome 91 * @param characteristicId The instance ID of the requested GATT characteristic. */ export function getCharacteristic( characteristicId: string, ): Promise; /** * Get the GATT characteristic with the given instance ID that belongs to the given GATT service, if the characteristic exists. * * @param characteristicId The instance ID of the requested GATT characteristic. */ export function getCharacteristic( characteristicId: string, callback?: ( result: Characteristic, ) => void, ): void; /** * Create a locally hosted GATT characteristic. This characteristic must be hosted under a valid service. If the service ID is not valid, the lastError will be set. This function is only available if the app has both the bluetooth:low\_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps. * * @chrome-returns-extra since Chrome 91 * @param characteristic The characteristic to create. * @param serviceId ID of the service to create this characteristic for. * @since Chrome 52 */ export function createCharacteristic( characteristic: Characteristic, serviceId: string, ): Promise; /** * Create a locally hosted GATT characteristic. This characteristic must be hosted under a valid service. If the service ID is not valid, the lastError will be set. This function is only available if the app has both the bluetooth:low\_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps. * * @param characteristic The characteristic to create. * @param serviceId ID of the service to create this characteristic for. * @since Chrome 52 */ export function createCharacteristic( characteristic: Characteristic, serviceId: string, callback?: ( characteristicId: string, ) => void, ): void; /** * Get a list of all discovered GATT characteristics that belong to the given service. * * @chrome-returns-extra since Chrome 91 * @param serviceId The instance ID of the GATT service whose characteristics should be returned. */ export function getCharacteristics( serviceId: string, ): Promise; /** * Get a list of all discovered GATT characteristics that belong to the given service. * * @param serviceId The instance ID of the GATT service whose characteristics should be returned. */ export function getCharacteristics( serviceId: string, callback?: ( result: Characteristic[], ) => void, ): void; /** * Get a list of GATT services that are included by the given service. * * @chrome-returns-extra since Chrome 91 * @param serviceId The instance ID of the GATT service whose included services should be returned. */ export function getIncludedServices( serviceId: string, ): Promise; /** * Get a list of GATT services that are included by the given service. * * @param serviceId The instance ID of the GATT service whose included services should be returned. */ export function getIncludedServices( serviceId: string, callback?: ( result: Service[], ) => void, ): void; /** * Get the GATT characteristic descriptor with the given instance ID. * * @chrome-returns-extra since Chrome 91 * @param descriptorId The instance ID of the requested GATT characteristic descriptor. */ export function getDescriptor( descriptorId: string, ): Promise; /** * Get the GATT characteristic descriptor with the given instance ID. * * @param descriptorId The instance ID of the requested GATT characteristic descriptor. */ export function getDescriptor( descriptorId: string, callback?: ( result: Descriptor, ) => void, ): void; /** * Create a locally hosted GATT descriptor. This descriptor must be hosted under a valid characteristic. If the characteristic ID is not valid, the lastError will be set. This function is only available if the app has both the bluetooth:low\_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps. * * @chrome-returns-extra since Chrome 91 * @param descriptor The descriptor to create. * @param characteristicId ID of the characteristic to create this descriptor for. * @since Chrome 52 */ export function createDescriptor( descriptor: Descriptor, characteristicId: string, ): Promise; /** * Create a locally hosted GATT descriptor. This descriptor must be hosted under a valid characteristic. If the characteristic ID is not valid, the lastError will be set. This function is only available if the app has both the bluetooth:low\_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps. * * @param descriptor The descriptor to create. * @param characteristicId ID of the characteristic to create this descriptor for. * @since Chrome 52 */ export function createDescriptor( descriptor: Descriptor, characteristicId: string, callback?: ( descriptorId: string, ) => void, ): void; /** * Get a list of GATT characteristic descriptors that belong to the given characteristic. * * @chrome-returns-extra since Chrome 91 * @param characteristicId The instance ID of the GATT characteristic whose descriptors should be returned. */ export function getDescriptors( characteristicId: string, ): Promise; /** * Get a list of GATT characteristic descriptors that belong to the given characteristic. * * @param characteristicId The instance ID of the GATT characteristic whose descriptors should be returned. */ export function getDescriptors( characteristicId: string, callback?: ( result: Descriptor[], ) => void, ): void; /** * Retrieve the value of a specified characteristic from a remote peripheral. * * @chrome-returns-extra since Chrome 91 * @param characteristicId The instance ID of the GATT characteristic whose value should be read from the remote device. */ export function readCharacteristicValue( characteristicId: string, ): Promise; /** * Retrieve the value of a specified characteristic from a remote peripheral. * * @param characteristicId The instance ID of the GATT characteristic whose value should be read from the remote device. */ export function readCharacteristicValue( characteristicId: string, callback?: ( result: Characteristic, ) => void, ): void; /** * Write the value of a specified characteristic from a remote peripheral. * * @chrome-returns-extra since Chrome 91 * @param characteristicId The instance ID of the GATT characteristic whose value should be written to. * @param value The value that should be sent to the remote characteristic as part of the write request. */ export function writeCharacteristicValue( characteristicId: string, value: ArrayBuffer, ): Promise; /** * Write the value of a specified characteristic from a remote peripheral. * * @param characteristicId The instance ID of the GATT characteristic whose value should be written to. * @param value The value that should be sent to the remote characteristic as part of the write request. */ export function writeCharacteristicValue( characteristicId: string, value: ArrayBuffer, callback?: () => void, ): void; /** * Enable value notifications/indications from the specified characteristic. Once enabled, an application can listen to notifications using the {@link onCharacteristicValueChanged} event. * * @chrome-returns-extra since Chrome 91 * @param characteristicId The instance ID of the GATT characteristic that notifications should be enabled on. * @param properties Notification session properties (optional). */ export function startCharacteristicNotifications( characteristicId: string, properties?: NotificationProperties, ): Promise; /** * Enable value notifications/indications from the specified characteristic. Once enabled, an application can listen to notifications using the {@link onCharacteristicValueChanged} event. * * @param characteristicId The instance ID of the GATT characteristic that notifications should be enabled on. * @param properties Notification session properties (optional). */ export function startCharacteristicNotifications( characteristicId: string, properties?: NotificationProperties, callback?: () => void, ): void; /** * Disable value notifications/indications from the specified characteristic. After a successful call, the application will stop receiving notifications/indications from this characteristic. * * @chrome-returns-extra since Chrome 91 * @param characteristicId The instance ID of the GATT characteristic on which this app's notification session should be stopped. */ export function stopCharacteristicNotifications( characteristicId: string, ): Promise; /** * Disable value notifications/indications from the specified characteristic. After a successful call, the application will stop receiving notifications/indications from this characteristic. * * @param characteristicId The instance ID of the GATT characteristic on which this app's notification session should be stopped. */ export function stopCharacteristicNotifications( characteristicId: string, callback?: () => void, ): void; /** * Notify a remote device of a new value for a characteristic. If the shouldIndicate flag in the notification object is true, an indication will be sent instead of a notification. Note, the characteristic needs to correctly set the 'notify' or 'indicate' property during creation for this call to succeed. This function is only available if the app has both the bluetooth:low\_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps. * * @chrome-returns-extra since Chrome 91 * @param characteristicId The characteristic to send the notication for. * @since Chrome 52 */ export function notifyCharacteristicValueChanged( characteristicId: string, notification: Notification, ): Promise; /** * Notify a remote device of a new value for a characteristic. If the shouldIndicate flag in the notification object is true, an indication will be sent instead of a notification. Note, the characteristic needs to correctly set the 'notify' or 'indicate' property during creation for this call to succeed. This function is only available if the app has both the bluetooth:low\_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps. * * @param characteristicId The characteristic to send the notication for. * @since Chrome 52 */ export function notifyCharacteristicValueChanged( characteristicId: string, notification: Notification, callback?: () => void, ): void; /** * Retrieve the value of a specified characteristic descriptor from a remote peripheral. * * @chrome-returns-extra since Chrome 91 * @param descriptorId The instance ID of the GATT characteristic descriptor whose value should be read from the remote device. */ export function readDescriptorValue( descriptorId: string, ): Promise; /** * Retrieve the value of a specified characteristic descriptor from a remote peripheral. * * @param descriptorId The instance ID of the GATT characteristic descriptor whose value should be read from the remote device. */ export function readDescriptorValue( descriptorId: string, callback?: ( result: Descriptor, ) => void, ): void; /** * Write the value of a specified characteristic descriptor from a remote peripheral. * * @chrome-returns-extra since Chrome 91 * @param descriptorId The instance ID of the GATT characteristic descriptor whose value should be written to. * @param value The value that should be sent to the remote descriptor as part of the write request. */ export function writeDescriptorValue( descriptorId: string, value: ArrayBuffer, ): Promise; /** * Write the value of a specified characteristic descriptor from a remote peripheral. * * @param descriptorId The instance ID of the GATT characteristic descriptor whose value should be written to. * @param value The value that should be sent to the remote descriptor as part of the write request. */ export function writeDescriptorValue( descriptorId: string, value: ArrayBuffer, callback?: () => void, ): void; /** * Register the given service with the local GATT server. If the service ID is invalid, the lastError will be set. This function is only available if the app has both the bluetooth:low\_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps. * * @chrome-returns-extra since Chrome 91 * @param serviceId Unique ID of a created service. * @since Chrome 52 */ export function registerService( serviceId: string, ): Promise; /** * Register the given service with the local GATT server. If the service ID is invalid, the lastError will be set. This function is only available if the app has both the bluetooth:low\_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps. * * @param serviceId Unique ID of a created service. * @since Chrome 52 */ export function registerService( serviceId: string, callback?: () => void, ): void; /** * Unregister the given service with the local GATT server. If the service ID is invalid, the lastError will be set. This function is only available if the app has both the bluetooth:low\_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps. * * @chrome-returns-extra since Chrome 91 * @param serviceId Unique ID of a current registered service. * @since Chrome 52 */ export function unregisterService( serviceId: string, ): Promise; /** * Unregister the given service with the local GATT server. If the service ID is invalid, the lastError will be set. This function is only available if the app has both the bluetooth:low\_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps. * * @param serviceId Unique ID of a current registered service. * @since Chrome 52 */ export function unregisterService( serviceId: string, callback?: () => void, ): void; /** * Remove the specified service, unregistering it if it was registered. If the service ID is invalid, the lastError will be set. This function is only available if the app has both the bluetooth:low\_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps. * * @chrome-returns-extra since Chrome 91 * @param serviceId Unique ID of a current registered service. * @since Chrome 52 */ export function removeService( serviceId: string, ): Promise; /** * Remove the specified service, unregistering it if it was registered. If the service ID is invalid, the lastError will be set. This function is only available if the app has both the bluetooth:low\_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps. * * @param serviceId Unique ID of a current registered service. * @since Chrome 52 */ export function removeService( serviceId: string, callback?: () => void, ): void; /** * Create an advertisement and register it for advertising. To call this function, the app must have the bluetooth:low\_energy and bluetooth:peripheral permissions set to true. Additionally this API is only available to auto launched apps in Kiosk Mode or by setting the '--enable-ble-advertising-in-apps' command-line switch. See https://developer.chrome.com/apps/manifest/bluetooth Note: On some hardware, central and peripheral modes at the same time is supported but on hardware that doesn't support this, making this call will switch the device to peripheral mode. In the case of hardware which does not support both central and peripheral mode, attempting to use the device in both modes will lead to undefined behavior or prevent other central-role applications from behaving correctly (including the discovery of Bluetooth Low Energy devices). * * @chrome-returns-extra since Chrome 91 * @param advertisement The advertisement to advertise. * @since Chrome 47 */ export function registerAdvertisement( advertisement: Advertisement, ): Promise; /** * Create an advertisement and register it for advertising. To call this function, the app must have the bluetooth:low\_energy and bluetooth:peripheral permissions set to true. Additionally this API is only available to auto launched apps in Kiosk Mode or by setting the '--enable-ble-advertising-in-apps' command-line switch. See https://developer.chrome.com/apps/manifest/bluetooth Note: On some hardware, central and peripheral modes at the same time is supported but on hardware that doesn't support this, making this call will switch the device to peripheral mode. In the case of hardware which does not support both central and peripheral mode, attempting to use the device in both modes will lead to undefined behavior or prevent other central-role applications from behaving correctly (including the discovery of Bluetooth Low Energy devices). * * @param advertisement The advertisement to advertise. * @since Chrome 47 */ export function registerAdvertisement( advertisement: Advertisement, callback?: ( advertisementId: number, ) => void, ): void; /** * Unregisters an advertisement and stops its advertising. If the advertisement fails to unregister the only way to stop advertising might be to restart the device. * * @chrome-returns-extra since Chrome 91 * @param advertisementId Id of the advertisement to unregister. * @since Chrome 47 */ export function unregisterAdvertisement( advertisementId: number, ): Promise; /** * Unregisters an advertisement and stops its advertising. If the advertisement fails to unregister the only way to stop advertising might be to restart the device. * * @param advertisementId Id of the advertisement to unregister. * @since Chrome 47 */ export function unregisterAdvertisement( advertisementId: number, callback?: () => void, ): void; /** * Resets advertising on the current device. It will unregister and stop all existing advertisements. * * @chrome-returns-extra since Chrome 91 * @since Chrome 61 */ export function resetAdvertising(): Promise; /** * Resets advertising on the current device. It will unregister and stop all existing advertisements. * * @since Chrome 61 */ export function resetAdvertising( callback?: () => void, ): void; /** * Set's the interval betweeen two consecutive advertisements. Note: This is a best effort. The actual interval may vary non-trivially from the requested intervals. On some hardware, there is a minimum interval of 100ms. The minimum and maximum values cannot exceed the the range allowed by the Bluetooth 4.2 specification. * * @chrome-returns-extra since Chrome 91 * @param minInterval Minimum interval between advertisments (in milliseconds). This cannot be lower than 20ms (as per the spec). * @param maxInterval Maximum interval between advertisments (in milliseconds). This cannot be more than 10240ms (as per the spec). * @since Chrome 55 */ export function setAdvertisingInterval( minInterval: number, maxInterval: number, ): Promise; /** * Set's the interval betweeen two consecutive advertisements. Note: This is a best effort. The actual interval may vary non-trivially from the requested intervals. On some hardware, there is a minimum interval of 100ms. The minimum and maximum values cannot exceed the the range allowed by the Bluetooth 4.2 specification. * * @param minInterval Minimum interval between advertisments (in milliseconds). This cannot be lower than 20ms (as per the spec). * @param maxInterval Maximum interval between advertisments (in milliseconds). This cannot be more than 10240ms (as per the spec). * @since Chrome 55 */ export function setAdvertisingInterval( minInterval: number, maxInterval: number, callback?: () => void, ): void; /** * Sends a response for a characteristic or descriptor read/write request. This function is only available if the app has both the bluetooth:low\_energy and the bluetooth:peripheral permissions set to true. The peripheral permission may not be available to all apps. * * @param response The response to the request. * @since Chrome 52 */ export function sendRequestResponse( response: Response, ): void; } /** * Use the `chrome.bluetoothSocket` API to send and receive data to Bluetooth devices using RFCOMM and L2CAP connections. * * @chrome-manifest bluetooth * @chrome-platform-apps * @chrome-platform chromeos * @chrome-platform linux * @chrome-platform mac * @chrome-platform win */ export namespace bluetoothSocket { export interface SocketProperties { /** * Flag indicating whether the socket is left open when the event page of the application is unloaded (see [Manage App Lifecycle](https://developer.chrome.com/docs/apps/app_lifecycle)). The default value is `false.` When the application is loaded, any sockets previously opened with persistent=true can be fetched with {@link getSockets}. */ persistent?: boolean; /** * An application-defined string associated with the socket. */ name?: string; /** * The size of the buffer used to receive data. The default value is 4096. */ bufferSize?: number; } export interface CreateInfo { /** * The ID of the newly created socket. Note that socket IDs created from this API are not compatible with socket IDs created from other APIs, such as the `{@link sockets.tcp}` API. */ socketId: number; } export interface ListenOptions { /** * The RFCOMM Channel used by `listenUsingRfcomm`. If specified, this channel must not be previously in use or the method call will fail. When not specified, an unused channel will be automatically allocated. */ channel?: number; /** * The L2CAP PSM used by `listenUsingL2cap`. If specified, this PSM must not be previously in use or the method call with fail. When not specified, an unused PSM will be automatically allocated. */ psm?: number; /** * Length of the socket's listen queue. The default value depends on the operating system's host subsystem. */ backlog?: number; } export interface SocketInfo { /** * The socket identifier. */ socketId: number; /** * Flag indicating if the socket remains open when the event page of the application is unloaded (see `SocketProperties.persistent`). The default value is "false". */ persistent: boolean; /** * Application-defined string associated with the socket. */ name?: string; /** * The size of the buffer used to receive data. If no buffer size has been specified explictly, the value is not provided. */ bufferSize?: number; /** * Flag indicating whether a connected socket blocks its peer from sending more data, or whether connection requests on a listening socket are dispatched through the `onAccept` event or queued up in the listen queue backlog. See `setPaused`. The default value is "false". */ paused: boolean; /** * Flag indicating whether the socket is connected to a remote peer. */ connected: boolean; /** * If the underlying socket is connected, contains the Bluetooth address of the device it is connected to. */ address?: string; /** * If the underlying socket is connected, contains information about the service UUID it is connected to, otherwise if the underlying socket is listening, contains information about the service UUID it is listening on. */ uuid?: string; } export interface AcceptInfo { /** * The server socket identifier. */ socketId: number; /** * The client socket identifier, i.e. the socket identifier of the newly established connection. This socket identifier should be used only with functions from the `chrome.bluetoothSocket` namespace. Note the client socket is initially paused and must be explictly un-paused by the application to start receiving data. */ clientSocketId: number; } /** * @chrome-enum "system\_error" A system error occurred and the connection may be unrecoverable. * @chrome-enum "not\_listening" The socket is not listening. */ export type AcceptError = "system_error" | "not_listening"; export interface AcceptErrorInfo { /** * The server socket identifier. */ socketId: number; /** * The error message. */ errorMessage: string; /** * An error code indicating what went wrong. */ error: AcceptError; } export interface ReceiveInfo { /** * The socket identifier. */ socketId: number; /** * The data received, with a maxium size of `bufferSize`. */ data: ArrayBuffer; } /** * @chrome-enum "disconnected" The connection was disconnected. * @chrome-enum "system\_error" A system error occurred and the connection may be unrecoverable. * @chrome-enum "not\_connected" The socket has not been connected. */ export type ReceiveError = "disconnected" | "system_error" | "not_connected"; export interface ReceiveErrorInfo { /** * The socket identifier. */ socketId: number; /** * The error message. */ errorMessage: string; /** * An error code indicating what went wrong. */ error: ReceiveError; } /** * Event raised when a connection has been established for a given socket. */ export const onAccept: events.Event<( info: AcceptInfo, ) => void>; /** * Event raised when a network error occurred while the runtime was waiting for new connections on the given socket. Once this event is raised, the socket is set to `paused` and no more `onAccept` events are raised for this socket. */ export const onAcceptError: events.Event<( info: AcceptErrorInfo, ) => void>; /** * Event raised when data has been received for a given socket. */ export const onReceive: events.Event<( info: ReceiveInfo, ) => void>; /** * Event raised when a network error occured while the runtime was waiting for data on the socket. Once this event is raised, the socket is set to `paused` and no more `onReceive` events are raised for this socket. */ export const onReceiveError: events.Event<( info: ReceiveErrorInfo, ) => void>; /** * Creates a Bluetooth socket. * * @chrome-returns-extra since Chrome 91 * @param properties The socket properties (optional). */ export function create( properties?: SocketProperties, ): Promise; /** * Creates a Bluetooth socket. * * @param properties The socket properties (optional). */ export function create( properties?: SocketProperties, /** * @param createInfo The result of the socket creation. */ callback?: ( createInfo: CreateInfo, ) => void, ): void; /** * Updates the socket properties. * * @chrome-returns-extra since Chrome 91 * @param socketId The socket identifier. * @param properties The properties to update. */ export function update( socketId: number, properties: SocketProperties, ): Promise; /** * Updates the socket properties. * * @param socketId The socket identifier. * @param properties The properties to update. */ export function update( socketId: number, properties: SocketProperties, callback?: () => void, ): void; /** * Enables or disables a connected socket from receiving messages from its peer, or a listening socket from accepting new connections. The default value is "false". Pausing a connected socket is typically used by an application to throttle data sent by its peer. When a connected socket is paused, no `onReceive`event is raised. When a socket is connected and un-paused, `onReceive` events are raised again when messages are received. When a listening socket is paused, new connections are accepted until its backlog is full then additional connection requests are refused. `onAccept` events are raised only when the socket is un-paused. * * @chrome-returns-extra since Chrome 91 */ export function setPaused( socketId: number, paused: boolean, ): Promise; /** * Enables or disables a connected socket from receiving messages from its peer, or a listening socket from accepting new connections. The default value is "false". Pausing a connected socket is typically used by an application to throttle data sent by its peer. When a connected socket is paused, no `onReceive`event is raised. When a socket is connected and un-paused, `onReceive` events are raised again when messages are received. When a listening socket is paused, new connections are accepted until its backlog is full then additional connection requests are refused. `onAccept` events are raised only when the socket is un-paused. */ export function setPaused( socketId: number, paused: boolean, callback?: () => void, ): void; /** * Listen for connections using the RFCOMM protocol. * * @chrome-returns-extra since Chrome 91 * @param socketId The socket identifier. * @param uuid Service UUID to listen on. * @param options Optional additional options for the service. */ export function listenUsingRfcomm( socketId: number, uuid: string, options?: ListenOptions, ): Promise; /** * Listen for connections using the RFCOMM protocol. * * @param socketId The socket identifier. * @param uuid Service UUID to listen on. * @param options Optional additional options for the service. */ export function listenUsingRfcomm( socketId: number, uuid: string, options?: ListenOptions, callback?: () => void, ): void; /** * Listen for connections using the L2CAP protocol. * * @chrome-returns-extra since Chrome 91 * @param socketId The socket identifier. * @param uuid Service UUID to listen on. * @param options Optional additional options for the service. */ export function listenUsingL2cap( socketId: number, uuid: string, options?: ListenOptions, ): Promise; /** * Listen for connections using the L2CAP protocol. * * @param socketId The socket identifier. * @param uuid Service UUID to listen on. * @param options Optional additional options for the service. */ export function listenUsingL2cap( socketId: number, uuid: string, options?: ListenOptions, callback?: () => void, ): void; /** * Connects the socket to a remote Bluetooth device. When the `connect` operation completes successfully, `onReceive` events are raised when data is received from the peer. If a network error occur while the runtime is receiving packets, a `onReceiveError` event is raised, at which point no more `onReceive` event will be raised for this socket until the `setPaused(false)` method is called. * * @chrome-returns-extra since Chrome 91 * @param socketId The socket identifier. * @param address The address of the Bluetooth device. * @param uuid The UUID of the service to connect to. */ export function connect( socketId: number, address: string, uuid: string, ): Promise; /** * Connects the socket to a remote Bluetooth device. When the `connect` operation completes successfully, `onReceive` events are raised when data is received from the peer. If a network error occur while the runtime is receiving packets, a `onReceiveError` event is raised, at which point no more `onReceive` event will be raised for this socket until the `setPaused(false)` method is called. * * @param socketId The socket identifier. * @param address The address of the Bluetooth device. * @param uuid The UUID of the service to connect to. */ export function connect( socketId: number, address: string, uuid: string, callback?: () => void, ): void; /** * Disconnects the socket. The socket identifier remains valid. * * @chrome-returns-extra since Chrome 91 * @param socketId The socket identifier. */ export function disconnect( socketId: number, ): Promise; /** * Disconnects the socket. The socket identifier remains valid. * * @param socketId The socket identifier. */ export function disconnect( socketId: number, callback?: () => void, ): void; /** * Disconnects and destroys the socket. Each socket created should be closed after use. The socket id is no longer valid as soon at the function is called. However, the socket is guaranteed to be closed only when the callback is invoked. * * @chrome-returns-extra since Chrome 91 * @param socketId The socket identifier. */ export function close( socketId: number, ): Promise; /** * Disconnects and destroys the socket. Each socket created should be closed after use. The socket id is no longer valid as soon at the function is called. However, the socket is guaranteed to be closed only when the callback is invoked. * * @param socketId The socket identifier. */ export function close( socketId: number, callback?: () => void, ): void; /** * Sends data on the given Bluetooth socket. * * @chrome-returns-extra since Chrome 91 * @param socketId The socket identifier. * @param data The data to send. */ export function send( socketId: number, data: ArrayBuffer, ): Promise; /** * Sends data on the given Bluetooth socket. * * @param socketId The socket identifier. * @param data The data to send. */ export function send( socketId: number, data: ArrayBuffer, /** * @param bytesSent The number of bytes sent. */ callback?: ( bytesSent: number, ) => void, ): void; /** * Retrieves the state of the given socket. * * @chrome-returns-extra since Chrome 91 * @param socketId The socket identifier. */ export function getInfo( socketId: number, ): Promise; /** * Retrieves the state of the given socket. * * @param socketId The socket identifier. */ export function getInfo( socketId: number, /** * @param socketInfo Object containing the socket information. */ callback?: ( socketInfo: SocketInfo, ) => void, ): void; /** * Retrieves the list of currently opened sockets owned by the application. * * @chrome-returns-extra since Chrome 91 */ export function getSockets(): Promise; /** * Retrieves the list of currently opened sockets owned by the application. */ export function getSockets( /** * @param sockets Array of object containing socket information. */ callback?: ( sockets: SocketInfo[], ) => void, ): void; } /** * Use the `chrome.bookmarks` API to create, organize, and otherwise manipulate bookmarks. Also see [Override Pages](https://developer.chrome.com/docs/extensions/override), which you can use to create a custom Bookmark Manager page. * * @chrome-permission bookmarks */ export namespace bookmarks { /** * Indicates the type of folder. * * @chrome-enum "bookmarks-bar" The folder whose contents is displayed at the top of the browser window. * @chrome-enum "other" Bookmarks which are displayed in the full list of bookmarks on all platforms. * @chrome-enum "mobile" Bookmarks generally available on the user's mobile devices, but modifiable by extension or in the bookmarks manager. * @chrome-enum "managed" A top-level folder that may be present if the system administrator or the custodian of a supervised user has configured bookmarks. * @since Chrome 134 */ export type FolderType = "bookmarks-bar" | "other" | "mobile" | "managed"; /** * 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 */ export type BookmarkTreeNodeUnmodifiable = "managed"; /** * A node (either a bookmark or a folder) in the bookmark tree. Child nodes are ordered within their parent folder. */ export interface BookmarkTreeNode { /** * 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 `id` of the parent folder. Omitted for the root node. */ parentId?: string; /** * The 0-based position of this node within its parent folder. */ index?: number; /** * The URL navigated to when a user clicks the bookmark. Omitted for folders. */ url?: string; /** * The text displayed for the node. */ title: string; /** * When this node was created, in milliseconds since the epoch (`new Date(dateAdded)`). */ dateAdded?: number; /** * When this node was last opened, in milliseconds since the epoch. Not set for folders. * * @since Chrome 114 */ dateLastUsed?: number; /** * When the contents of this folder last changed, in milliseconds since the epoch. */ dateGroupModified?: 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; /** * 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; /** * 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; /** * An ordered list of children of this node. */ children?: BookmarkTreeNode[]; } /** * Object passed to the create() function. */ export interface CreateDetails { /** * Defaults to the Other Bookmarks folder. */ parentId?: string; index?: number; title?: string; url?: string; } /** * @deprecated Bookmark write operations are no longer limited by Chrome. */ export const MAX_WRITE_OPERATIONS_PER_HOUR: 1000000; /** * @deprecated Bookmark write operations are no longer limited by Chrome. */ export const MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE: 1000000; /** * The `id` associated with the root level node. * * @since Pending */ export const ROOT_NODE_ID: "0"; /** * Fired when a bookmark or folder is created. */ export const onCreated: events.Event<( id: string, bookmark: BookmarkTreeNode, ) => 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. */ export const onRemoved: events.Event<( id: string, removeInfo: { parentId: string, index: number, /** * @since Chrome 48 */ node: BookmarkTreeNode, }, ) => void>; /** * Fired when a bookmark or folder changes. **Note:** Currently, only title and url changes trigger this. */ export const onChanged: events.Event<( id: string, changeInfo: { title: string, url?: string, }, ) => void>; /** * Fired when a bookmark or folder is moved to a different parent folder. */ export const onMoved: events.Event<( id: string, moveInfo: { parentId: string, index: number, oldParentId: string, oldIndex: number, }, ) => 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(). */ export const onChildrenReordered: events.Event<( id: string, reorderInfo: { childIds: string[], }, ) => 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. */ export const onImportBegan: events.Event<() => void>; /** * Fired when a bookmark import session is ended. */ export const onImportEnded: events.Event<() => void>; /** * Retrieves the specified BookmarkTreeNode(s). * * @chrome-returns-extra since Chrome 90 * @param idOrIdList A single string-valued id, or an array of string-valued ids */ export function get( idOrIdList: string | [string, ...string[]], ): Promise; /** * Retrieves the specified BookmarkTreeNode(s). * * @param idOrIdList A single string-valued id, or an array of string-valued ids */ export function get( idOrIdList: string | [string, ...string[]], callback?: ( results: BookmarkTreeNode[], ) => void, ): void; /** * Retrieves the children of the specified BookmarkTreeNode id. * * @chrome-returns-extra since Chrome 90 */ export function getChildren( id: string, ): Promise; /** * Retrieves the children of the specified BookmarkTreeNode id. */ export function getChildren( id: string, callback?: ( results: BookmarkTreeNode[], ) => void, ): void; /** * Retrieves the recently added bookmarks. * * @chrome-returns-extra since Chrome 90 * @param numberOfItems The maximum number of items to return. */ export function getRecent( numberOfItems: number, ): Promise; /** * Retrieves the recently added bookmarks. * * @param numberOfItems The maximum number of items to return. */ export function getRecent( numberOfItems: number, callback?: ( results: BookmarkTreeNode[], ) => void, ): void; /** * Retrieves the entire Bookmarks hierarchy. * * @chrome-returns-extra since Chrome 90 */ export function getTree(): Promise; /** * Retrieves the entire Bookmarks hierarchy. */ export function getTree( callback?: ( results: BookmarkTreeNode[], ) => void, ): void; /** * Retrieves part of the Bookmarks hierarchy, starting at the specified node. * * @chrome-returns-extra since Chrome 90 * @param id The ID of the root of the subtree to retrieve. */ export function getSubTree( id: string, ): Promise; /** * Retrieves part of the Bookmarks hierarchy, starting at the specified node. * * @param id The ID of the root of the subtree to retrieve. */ export function getSubTree( id: string, callback?: ( results: BookmarkTreeNode[], ) => void, ): void; /** * Searches for BookmarkTreeNodes matching the given query. Queries specified with an object produce BookmarkTreeNodes matching all specified properties. * * @chrome-returns-extra since Chrome 90 * @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. */ export function search( query: string | { /** * 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, }, ): Promise; /** * 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. */ export function search( query: string | { /** * 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, }, callback?: ( results: BookmarkTreeNode[], ) => void, ): void; /** * Creates a bookmark or folder under the specified parentId. If url is NULL or missing, it will be a folder. * * @chrome-returns-extra since Chrome 90 */ export function create( bookmark: CreateDetails, ): Promise; /** * Creates a bookmark or folder under the specified parentId. If url is NULL or missing, it will be a folder. */ export function create( bookmark: CreateDetails, callback?: ( result: BookmarkTreeNode, ) => void, ): void; /** * Moves the specified BookmarkTreeNode to the provided location. * * @chrome-returns-extra since Chrome 90 */ export function move( id: string, destination: { parentId?: string, index?: number, }, ): Promise; /** * Moves the specified BookmarkTreeNode to the provided location. */ export function move( id: string, destination: { parentId?: string, index?: number, }, callback?: ( result: BookmarkTreeNode, ) => void, ): void; /** * 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. * * @chrome-returns-extra since Chrome 90 */ export function update( id: string, changes: { title?: string, url?: string, }, ): Promise; /** * 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. */ export function update( id: string, changes: { title?: string, url?: string, }, callback?: ( result: BookmarkTreeNode, ) => void, ): void; /** * Removes a bookmark or an empty bookmark folder. * * @chrome-returns-extra since Chrome 90 */ export function remove( id: string, ): Promise; /** * Removes a bookmark or an empty bookmark folder. */ export function remove( id: string, callback?: () => void, ): void; /** * Recursively removes a bookmark folder. * * @chrome-returns-extra since Chrome 90 */ export function removeTree( id: string, ): Promise; /** * Recursively removes a bookmark folder. */ export function removeTree( id: string, callback?: () => void, ): void; } /** * Use the `chrome.browser` API to interact with the Chrome browser associated with the current application and Chrome profile. * * @chrome-permission browser * @chrome-platform-apps */ export namespace browser { export interface OpenTabOptions { /** * The URL to navigate to when the new tab is initially opened. */ url: string; } /** * Opens a new tab in a browser window associated with the current application and Chrome profile. If no browser window for the Chrome profile is opened, a new one is opened prior to creating the new tab. * * @chrome-returns-extra since Chrome 117 * @param options Configures how the tab should be opened. */ export function openTab( options: OpenTabOptions, ): Promise; /** * Opens a new tab in a browser window associated with the current application and Chrome profile. If no browser window for the Chrome profile is opened, a new one is opened prior to creating the new tab. * * @param options Configures how the tab should be opened. */ export function openTab( options: OpenTabOptions, callback?: () => void, ): void; } /** * Use browser actions to put icons in the main Google Chrome toolbar, to the right of the address bar. In addition to its [icon](https://developer.chrome.com/docs/extensions/reference/browserAction/#icon), a browser action can have a [tooltip](https://developer.chrome.com/docs/extensions/reference/browserAction/#tooltip), a [badge](https://developer.chrome.com/docs/extensions/reference/browserAction/#badge), and a [popup](https://developer.chrome.com/docs/extensions/reference/browserAction/#popup). * * @chrome-manifest browser_action * @chrome-max-manifest MV2 */ export namespace browserAction { /** * @since Chrome 88 */ export 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; } /** * Fired when a browser action icon is clicked. Does not fire if the browser action has a popup. */ export const onClicked: events.Event<( tab: tabs.Tab, ) => void>; /** * Sets the title of the browser action. This title appears in the tooltip. * * @chrome-returns-extra since Chrome 88 */ export function setTitle( details: { /** * The string the browser action should display when moused over. */ title: string, /** * Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */ tabId?: number, }, ): Promise; /** * Sets the title of the browser action. This title appears in the tooltip. */ export function setTitle( details: { /** * The string the browser action should display when moused over. */ title: string, /** * Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */ tabId?: number, }, /** * @since Chrome 67 */ callback?: () => void, ): void; /** * Gets the title of the browser action. * * @chrome-returns-extra since Chrome 88 */ export function getTitle( details: TabDetails, ): Promise; /** * Gets the title of the browser action. */ export function getTitle( 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. * * @chrome-returns-extra since Chrome 116 */ export function setIcon( details: { /** * 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?: extensionTypes.ImageDataType | {[name: string]: any}, /** * 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 | {[name: string]: any}, /** * Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */ tabId?: number, }, ): Promise; /** * 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. */ export function setIcon( details: { /** * 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?: extensionTypes.ImageDataType | {[name: string]: any}, /** * 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 | {[name: string]: any}, /** * Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */ tabId?: number, }, callback?: () => void, ): void; /** * Sets the HTML document to be opened as a popup when the user clicks the browser action icon. * * @chrome-returns-extra since Chrome 88 */ export function setPopup( details: { /** * Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */ tabId?: number, /** * The relative path to the HTML file to show in a popup. If set to the empty string (`''`), no popup is shown. */ popup: string, }, ): Promise; /** * Sets the HTML document to be opened as a popup when the user clicks the browser action icon. */ export function setPopup( details: { /** * Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */ tabId?: number, /** * The relative path to the HTML file to show in a popup. If set to the empty string (`''`), no popup is shown. */ popup: string, }, /** * @since Chrome 67 */ callback?: () => void, ): void; /** * Gets the HTML document that is set as the popup for this browser action. * * @chrome-returns-extra since Chrome 88 */ export function getPopup( details: TabDetails, ): Promise; /** * Gets the HTML document that is set as the popup for this browser action. */ export function getPopup( details: TabDetails, callback?: ( result: string, ) => void, ): void; /** * Sets the badge text for the browser action. The badge is displayed on top of the icon. * * @chrome-returns-extra since Chrome 88 */ export function setBadgeText( details: { /** * 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, /** * Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */ tabId?: number, }, ): Promise; /** * Sets the badge text for the browser action. The badge is displayed on top of the icon. */ export function setBadgeText( details: { /** * 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, /** * Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */ tabId?: number, }, /** * @since Chrome 67 */ callback?: () => void, ): void; /** * Gets the badge text of the browser action. If no tab is specified, the non-tab-specific badge text is returned. * * @chrome-returns-extra since Chrome 88 */ export function getBadgeText( details: TabDetails, ): Promise; /** * Gets the badge text of the browser action. If no tab is specified, the non-tab-specific badge text is returned. */ export function getBadgeText( details: TabDetails, callback?: ( result: string, ) => void, ): void; /** * Sets the background color for the badge. * * @chrome-returns-extra since Chrome 88 */ export function setBadgeBackgroundColor( details: { /** * 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, }, ): Promise; /** * Sets the background color for the badge. */ export function setBadgeBackgroundColor( details: { /** * 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, }, /** * @since Chrome 67 */ callback?: () => void, ): void; /** * Gets the background color of the browser action. * * @chrome-returns-extra since Chrome 88 */ export function getBadgeBackgroundColor( details: TabDetails, ): Promise; /** * Gets the background color of the browser action. */ export function getBadgeBackgroundColor( details: TabDetails, callback?: ( result: extensionTypes.ColorArray, ) => void, ): void; /** * Enables the browser action for a tab. Defaults to enabled. * * @chrome-returns-extra since Chrome 88 * @param tabId The ID of the tab for which to modify the browser action. */ export function enable( tabId?: number, ): Promise; /** * Enables the browser action for a tab. Defaults to enabled. * * @param tabId The ID of the tab for which to modify the browser action. */ export function enable( tabId?: number, /** * @since Chrome 67 */ callback?: () => void, ): void; /** * Disables the browser action for a tab. * * @chrome-returns-extra since Chrome 88 * @param tabId The ID of the tab for which to modify the browser action. */ export function disable( tabId?: number, ): Promise; /** * Disables the browser action for a tab. * * @param tabId The ID of the tab for which to modify the browser action. */ export function disable( tabId?: number, /** * @since Chrome 67 */ callback?: () => void, ): void; } /** * Use the `chrome.browsingData` API to remove browsing data from a user's local profile. * * @chrome-permission browsingData */ export namespace browsingData { /** * Options that determine exactly what data will be removed. */ export interface RemovalOptions { /** * Remove data accumulated on or after this date, represented in milliseconds since the epoch (accessible via the `getTime` method of the JavaScript `Date` object). If absent, defaults to 0 (which would remove all browsing data). */ since?: number; /** * An object whose properties specify which origin types ought to be cleared. If this object isn't specified, it defaults to clearing only "unprotected" origins. Please ensure that you _really_ want to remove application data before adding 'protectedWeb' or 'extensions'. */ originTypes?: { /** * Normal websites. */ unprotectedWeb?: boolean, /** * Websites that have been installed as hosted applications (be careful!). */ protectedWeb?: boolean, /** * Extensions and packaged applications a user has installed (be \_really\_ careful!). */ extension?: boolean, }; /** * When present, only data for origins in this list is deleted. Only supported for cookies, storage and cache. Cookies are cleared for the whole registrable domain. * * @since Chrome 74 */ origins?: [string, ...string[]]; /** * When present, data for origins in this list is excluded from deletion. Can't be used together with `origins`. Only supported for cookies, storage and cache. Cookies are excluded for the whole registrable domain. * * @since Chrome 74 */ excludeOrigins?: string[]; } /** * A set of data types. Missing data types are interpreted as `false`. */ export interface DataTypeSet { /** * Websites' appcaches. */ appcache?: boolean; /** * The browser's cache. */ cache?: boolean; /** * Cache storage * * @since Chrome 72 */ cacheStorage?: boolean; /** * The browser's cookies. */ cookies?: boolean; /** * The browser's download list. */ downloads?: boolean; /** * Websites' file systems. */ fileSystems?: boolean; /** * The browser's stored form data. */ formData?: boolean; /** * The browser's history. */ history?: boolean; /** * Websites' IndexedDB data. */ indexedDB?: boolean; /** * Websites' local storage data. */ localStorage?: boolean; /** * Server-bound certificates. * * @deprecated Support for server-bound certificates has been removed. This data type will be ignored. * @chrome-deprecated-since Chrome 76 */ serverBoundCertificates?: boolean; /** * Stored passwords. * * @deprecated Support for password deletion through extensions has been removed. This data type will be ignored. * @chrome-deprecated-since Chrome 144 */ passwords?: boolean; /** * Plugins' data. * * @deprecated Support for Flash has been removed. This data type will be ignored. * @chrome-deprecated-since Chrome 88 */ pluginData?: boolean; /** * Service Workers. */ serviceWorkers?: boolean; /** * Websites' WebSQL data. */ webSQL?: boolean; } /** * Reports which types of data are currently selected in the 'Clear browsing data' settings UI. Note: some of the data types included in this API are not available in the settings UI, and some UI settings control more than one data type listed here. * * @chrome-returns-extra since Chrome 96 */ export function settings(): Promise<{ options: RemovalOptions, /** * All of the types will be present in the result, with values of `true` if they are both selected to be removed and permitted to be removed, otherwise `false`. */ dataToRemove: DataTypeSet, /** * All of the types will be present in the result, with values of `true` if they are permitted to be removed (e.g., by enterprise policy) and `false` if not. */ dataRemovalPermitted: DataTypeSet, }>; /** * Reports which types of data are currently selected in the 'Clear browsing data' settings UI. Note: some of the data types included in this API are not available in the settings UI, and some UI settings control more than one data type listed here. */ export function settings( callback?: ( result: { options: RemovalOptions, /** * All of the types will be present in the result, with values of `true` if they are both selected to be removed and permitted to be removed, otherwise `false`. */ dataToRemove: DataTypeSet, /** * All of the types will be present in the result, with values of `true` if they are permitted to be removed (e.g., by enterprise policy) and `false` if not. */ dataRemovalPermitted: DataTypeSet, }, ) => void, ): void; /** * Clears various types of browsing data stored in a user's profile. * * @chrome-returns-extra since Chrome 96 * @param dataToRemove The set of data types to remove. * @returns Resolves when deletion has completed. */ export function remove( options: RemovalOptions, dataToRemove: DataTypeSet, ): Promise; /** * Clears various types of browsing data stored in a user's profile. * * @param dataToRemove The set of data types to remove. */ export function remove( options: RemovalOptions, dataToRemove: DataTypeSet, callback?: () => void, ): void; /** * Clears websites' appcache data. * * @chrome-returns-extra since Chrome 96 * @returns Resolves when websites' appcache data has been cleared. */ export function removeAppcache( options: RemovalOptions, ): Promise; /** * Clears websites' appcache data. */ export function removeAppcache( options: RemovalOptions, callback?: () => void, ): void; /** * Clears the browser's cache. * * @chrome-returns-extra since Chrome 96 * @returns Resolves when the browser's cache has been cleared. */ export function removeCache( options: RemovalOptions, ): Promise; /** * Clears the browser's cache. */ export function removeCache( options: RemovalOptions, callback?: () => void, ): void; /** * Clears websites' cache storage data. * * @chrome-returns-extra since Chrome 96 * @returns Resolves when websites' cache storage has been cleared. * @since Chrome 72 */ export function removeCacheStorage( options: RemovalOptions, ): Promise; /** * Clears websites' cache storage data. * * @since Chrome 72 */ export function removeCacheStorage( options: RemovalOptions, callback?: () => void, ): void; /** * Clears the browser's cookies and server-bound certificates modified within a particular timeframe. * * @chrome-returns-extra since Chrome 96 * @returns Resolves when the browser's cookies and server-bound certificates have been cleared. */ export function removeCookies( options: RemovalOptions, ): Promise; /** * Clears the browser's cookies and server-bound certificates modified within a particular timeframe. */ export function removeCookies( options: RemovalOptions, callback?: () => void, ): void; /** * Clears the browser's list of downloaded files (_not_ the downloaded files themselves). * * @chrome-returns-extra since Chrome 96 * @returns Resolves when the browser's list of downloaded files has been cleared. */ export function removeDownloads( options: RemovalOptions, ): Promise; /** * Clears the browser's list of downloaded files (_not_ the downloaded files themselves). */ export function removeDownloads( options: RemovalOptions, callback?: () => void, ): void; /** * Clears websites' file system data. * * @chrome-returns-extra since Chrome 96 * @returns Resolves when websites' file systems have been cleared. */ export function removeFileSystems( options: RemovalOptions, ): Promise; /** * Clears websites' file system data. */ export function removeFileSystems( options: RemovalOptions, callback?: () => void, ): void; /** * Clears the browser's stored form data (autofill). * * @chrome-returns-extra since Chrome 96 * @returns Resolves when the browser's form data has been cleared. */ export function removeFormData( options: RemovalOptions, ): Promise; /** * Clears the browser's stored form data (autofill). */ export function removeFormData( options: RemovalOptions, callback?: () => void, ): void; /** * Clears the browser's history. * * @chrome-returns-extra since Chrome 96 * @returns Resolves when the browser's history has cleared. */ export function removeHistory( options: RemovalOptions, ): Promise; /** * Clears the browser's history. */ export function removeHistory( options: RemovalOptions, callback?: () => void, ): void; /** * Clears websites' IndexedDB data. * * @chrome-returns-extra since Chrome 96 * @returns Resolves when websites' IndexedDB data has been cleared. */ export function removeIndexedDB( options: RemovalOptions, ): Promise; /** * Clears websites' IndexedDB data. */ export function removeIndexedDB( options: RemovalOptions, callback?: () => void, ): void; /** * Clears websites' local storage data. * * @chrome-returns-extra since Chrome 96 * @returns Resolves when websites' local storage has been cleared. */ export function removeLocalStorage( options: RemovalOptions, ): Promise; /** * Clears websites' local storage data. */ export function removeLocalStorage( options: RemovalOptions, callback?: () => void, ): void; /** * Clears plugins' data. * * @chrome-returns-extra since Chrome 96 * @returns Resolves when plugins' data has been cleared. * @deprecated Support for Flash has been removed. This function has no effect. * @chrome-deprecated-since Chrome 88 */ export function removePluginData( options: RemovalOptions, ): Promise; /** * Clears plugins' data. * * @deprecated Support for Flash has been removed. This function has no effect. * @chrome-deprecated-since Chrome 88 */ export function removePluginData( options: RemovalOptions, callback?: () => void, ): void; /** * Clears the browser's stored passwords. * * @chrome-returns-extra since Chrome 96 * @returns Resolves when the browser's passwords have been cleared. * @deprecated Support for password deletion through extensions has been removed. This function has no effect. * @chrome-deprecated-since Chrome 144 */ export function removePasswords( options: RemovalOptions, ): Promise; /** * Clears the browser's stored passwords. * * @deprecated Support for password deletion through extensions has been removed. This function has no effect. * @chrome-deprecated-since Chrome 144 */ export function removePasswords( options: RemovalOptions, callback?: () => void, ): void; /** * Clears websites' service workers. * * @chrome-returns-extra since Chrome 96 * @returns Resolves when websites' service workers have been cleared. * @since Chrome 72 */ export function removeServiceWorkers( options: RemovalOptions, ): Promise; /** * Clears websites' service workers. * * @since Chrome 72 */ export function removeServiceWorkers( options: RemovalOptions, callback?: () => void, ): void; /** * Clears websites' WebSQL data. * * @chrome-returns-extra since Chrome 96 * @returns Resolves when websites' WebSQL databases have been cleared. */ export function removeWebSQL( options: RemovalOptions, ): Promise; /** * Clears websites' WebSQL data. */ export function removeWebSQL( options: RemovalOptions, callback?: () => void, ): void; } /** * Use this API to expose certificates to the platform which can use these certificates for TLS authentications. * * @since Chrome 46 * @chrome-permission certificateProvider * @chrome-platform chromeos */ export namespace certificateProvider { /** * Types of supported cryptographic signature algorithms. * * @chrome-enum "RSASSA\_PKCS1\_v1\_5\_MD5\_SHA1" Specifies the RSASSA PKCS#1 v1.5 signature algorithm with the MD5-SHA-1 hashing. The extension must not prepend a DigestInfo prefix but only add PKCS#1 padding. This algorithm is deprecated and will never be requested by Chrome as of version 109. * @chrome-enum "RSASSA\_PKCS1\_v1\_5\_SHA1" Specifies the RSASSA PKCS#1 v1.5 signature algorithm with the SHA-1 hash function. * @chrome-enum "RSASSA\_PKCS1\_v1\_5\_SHA256" Specifies the RSASSA PKCS#1 v1.5 signature algorithm with the SHA-256 hashing function. * @chrome-enum "RSASSA\_PKCS1\_v1\_5\_SHA384" Specifies the RSASSA PKCS#1 v1.5 signature algorithm with the SHA-384 hashing function. * @chrome-enum "RSASSA\_PKCS1\_v1\_5\_SHA512" Specifies the RSASSA PKCS#1 v1.5 signature algorithm with the SHA-512 hashing function. * @chrome-enum "RSASSA\_PSS\_SHA256" Specifies the RSASSA PSS signature algorithm with the SHA-256 hashing function, MGF1 mask generation function and the salt of the same size as the hash. * @chrome-enum "RSASSA\_PSS\_SHA384" Specifies the RSASSA PSS signature algorithm with the SHA-384 hashing function, MGF1 mask generation function and the salt of the same size as the hash. * @chrome-enum "RSASSA\_PSS\_SHA512" Specifies the RSASSA PSS signature algorithm with the SHA-512 hashing function, MGF1 mask generation function and the salt of the same size as the hash. * @since Chrome 86 */ export type Algorithm = "RSASSA_PKCS1_v1_5_MD5_SHA1" | "RSASSA_PKCS1_v1_5_SHA1" | "RSASSA_PKCS1_v1_5_SHA256" | "RSASSA_PKCS1_v1_5_SHA384" | "RSASSA_PKCS1_v1_5_SHA512" | "RSASSA_PSS_SHA256" | "RSASSA_PSS_SHA384" | "RSASSA_PSS_SHA512"; /** * Types of errors that the extension can report. * * @chrome-enum "GENERAL\_ERROR" General error that cannot be represented by other more specific error codes. * @since Chrome 86 */ export type Error = "GENERAL_ERROR"; /** * @since Chrome 86 */ export interface ClientCertificateInfo { /** * The array must contain the DER encoding of the X.509 client certificate as its first element. * * This must include exactly one certificate. */ certificateChain: ArrayBuffer[]; /** * All algorithms supported for this certificate. The extension will only be asked for signatures using one of these algorithms. */ supportedAlgorithms: Algorithm[]; } /** * @since Chrome 86 */ export interface SetCertificatesDetails { /** * When called in response to {@link onCertificatesUpdateRequested}, should contain the received `certificatesRequestId` value. Otherwise, should be unset. */ certificatesRequestId?: number; /** * Error that occurred while extracting the certificates, if any. This error will be surfaced to the user when appropriate. */ error?: Error; /** * List of currently available client certificates. */ clientCertificates: ClientCertificateInfo[]; } /** * @since Chrome 86 */ export interface CertificatesUpdateRequest { /** * Request identifier to be passed to {@link setCertificates}. */ certificatesRequestId: number; } /** * @since Chrome 86 */ export interface SignatureRequest { /** * Request identifier to be passed to {@link reportSignature}. */ signRequestId: number; /** * Data to be signed. Note that the data is not hashed. */ input: ArrayBuffer; /** * Signature algorithm to be used. */ algorithm: Algorithm; /** * The DER encoding of a X.509 certificate. The extension must sign `input` using the associated private key. */ certificate: ArrayBuffer; } /** * @since Chrome 86 */ export interface ReportSignatureDetails { /** * Request identifier that was received via the {@link onSignatureRequested} event. */ signRequestId: number; /** * Error that occurred while generating the signature, if any. */ error?: Error; /** * The signature, if successfully generated. */ signature?: ArrayBuffer; } /** * Deprecated. Replaced by {@link Algorithm}. * * @chrome-enum "MD5\_SHA1" Specifies the MD5 and SHA1 hashing algorithms. * @chrome-enum "SHA1" Specifies the SHA1 hashing algorithm. * @chrome-enum "SHA256" Specifies the SHA256 hashing algorithm. * @chrome-enum "SHA384" Specifies the SHA384 hashing algorithm. * @chrome-enum "SHA512" Specifies the SHA512 hashing algorithm. */ export type Hash = "MD5_SHA1" | "SHA1" | "SHA256" | "SHA384" | "SHA512"; /** * The type of code being requested by the extension with requestPin function. * * @chrome-enum "PIN" Specifies the requested code is a PIN. * @chrome-enum "PUK" Specifies the requested code is a PUK. * @since Chrome 57 */ export type PinRequestType = "PIN" | "PUK"; /** * The types of errors that can be presented to the user through the requestPin function. * * @chrome-enum "INVALID\_PIN" Specifies the PIN is invalid. * @chrome-enum "INVALID\_PUK" Specifies the PUK is invalid. * @chrome-enum "MAX\_ATTEMPTS\_EXCEEDED" Specifies the maximum attempt number has been exceeded. * @chrome-enum "UNKNOWN\_ERROR" Specifies that the error cannot be represented by the above types. * @since Chrome 57 */ export type PinRequestErrorType = "INVALID_PIN" | "INVALID_PUK" | "MAX_ATTEMPTS_EXCEEDED" | "UNKNOWN_ERROR"; export interface CertificateInfo { /** * Must be the DER encoding of a X.509 certificate. Currently, only certificates of RSA keys are supported. */ certificate: ArrayBuffer; /** * Must be set to all hashes supported for this certificate. This extension will only be asked for signatures of digests calculated with one of these hash algorithms. This should be in order of decreasing hash preference. */ supportedHashes: Hash[]; } export interface SignRequest { /** * The unique ID to be used by the extension should it need to call a method that requires it, e.g. requestPin. * * @since Chrome 57 */ signRequestId: number; /** * The digest that must be signed. */ digest: ArrayBuffer; /** * Refers to the hash algorithm that was used to create `digest`. */ hash: Hash; /** * The DER encoding of a X.509 certificate. The extension must sign `digest` using the associated private key. */ certificate: ArrayBuffer; } /** * @since Chrome 57 */ export interface RequestPinDetails { /** * The ID given by Chrome in SignRequest. */ signRequestId: number; /** * The type of code requested. Default is PIN. */ requestType?: PinRequestType; /** * The error template displayed to the user. This should be set if the previous request failed, to notify the user of the failure reason. */ errorType?: PinRequestErrorType; /** * The number of attempts left. This is provided so that any UI can present this information to the user. Chrome is not expected to enforce this, instead stopPinRequest should be called by the extension with errorType = MAX\_ATTEMPTS\_EXCEEDED when the number of pin requests is exceeded. */ attemptsLeft?: number; } /** * @since Chrome 57 */ export interface StopPinRequestDetails { /** * The ID given by Chrome in SignRequest. */ signRequestId: number; /** * The error template. If present it is displayed to user. Intended to contain the reason for stopping the flow if it was caused by an error, e.g. MAX\_ATTEMPTS\_EXCEEDED. */ errorType?: PinRequestErrorType; } /** * @since Chrome 57 */ export interface PinResponseDetails { /** * The code provided by the user. Empty if user closed the dialog or some other error occurred. */ userInput?: string; } /** * This event fires if the certificates set via {@link setCertificates} are insufficient or the browser requests updated information. The extension must call {@link setCertificates} with the updated list of certificates and the received `certificatesRequestId`. * * @since Chrome 86 */ export const onCertificatesUpdateRequested: events.Event<( request: CertificatesUpdateRequest, ) => void>; /** * This event fires every time the browser needs to sign a message using a certificate provided by this extension via {@link setCertificates}. * * The extension must sign the input data from `request` using the appropriate algorithm and private key and return it by calling {@link reportSignature} with the received `signRequestId`. * * @since Chrome 86 */ export const onSignatureRequested: events.Event<( request: SignatureRequest, ) => void>; /** * This event fires every time the browser requests the current list of certificates provided by this extension. The extension must call `reportCallback` exactly once with the current list of certificates. * * @deprecated Use {@link onCertificatesUpdateRequested} instead. * @since Chrome 47 * @chrome-max-manifest MV2 * @chrome-deprecated-since Chrome 86 */ export const onCertificatesRequested: events.Event<( /** * @param callback The callback provided by the extension that Chrome uses to report back rejected certificates. See `CertificatesCallback`. */ reportCallback: ( certificates: CertificateInfo[], callback: ( rejectedCertificates: ArrayBuffer[], ) => void, ) => void, ) => void>; /** * This event fires every time the browser needs to sign a message using a certificate provided by this extension in reply to an {@link onCertificatesRequested} event. The extension must sign the data in `request` using the appropriate algorithm and private key and return it by calling `reportCallback`. `reportCallback` must be called exactly once. * * @deprecated Use {@link onSignatureRequested} instead. * @chrome-max-manifest MV2 * @chrome-deprecated-since Chrome 86 */ export const onSignDigestRequested: events.Event<( request: SignRequest, /** * @since Chrome 47 */ reportCallback: ( signature?: ArrayBuffer, ) => void, ) => void>; /** * Requests the PIN from the user. Only one ongoing request at a time is allowed. The requests issued while another flow is ongoing are rejected. It's the extension's responsibility to try again later if another flow is in progress. * * @chrome-returns-extra since Chrome 96 * @param details Contains the details about the requested dialog. * @returns Returns a Promise which resolves when the PIN is provided by the user. Rejects with an error if the dialog request finishes unsuccessfully (e.g. the dialog was canceled by the user or was not allowed to be shown). * @since Chrome 57 */ export function requestPin( details: RequestPinDetails, ): Promise; /** * Requests the PIN from the user. Only one ongoing request at a time is allowed. The requests issued while another flow is ongoing are rejected. It's the extension's responsibility to try again later if another flow is in progress. * * @param details Contains the details about the requested dialog. * @since Chrome 57 */ export function requestPin( details: RequestPinDetails, callback?: ( details?: PinResponseDetails, ) => void, ): void; /** * Stops the pin request started by the {@link requestPin} function. * * @chrome-returns-extra since Chrome 96 * @param details Contains the details about the reason for stopping the request flow. * @returns Returns a Promise which resolves when the request to close the PIN dialog is complete. * @since Chrome 57 */ export function stopPinRequest( details: StopPinRequestDetails, ): Promise; /** * Stops the pin request started by the {@link requestPin} function. * * @param details Contains the details about the reason for stopping the request flow. * @since Chrome 57 */ export function stopPinRequest( details: StopPinRequestDetails, callback?: () => void, ): void; /** * Sets a list of certificates to use in the browser. * * The extension should call this function after initialization and on every change in the set of currently available certificates. The extension should also call this function in response to {@link onCertificatesUpdateRequested} every time this event is received. * * @chrome-returns-extra since Chrome 96 * @param details The certificates to set. Invalid certificates will be ignored. * @returns Returns a Promise which resolves upon completion. * @since Chrome 86 */ export function setCertificates( details: SetCertificatesDetails, ): Promise; /** * Sets a list of certificates to use in the browser. * * The extension should call this function after initialization and on every change in the set of currently available certificates. The extension should also call this function in response to {@link onCertificatesUpdateRequested} every time this event is received. * * @param details The certificates to set. Invalid certificates will be ignored. * @since Chrome 86 */ export function setCertificates( details: SetCertificatesDetails, callback?: () => void, ): void; /** * Should be called as a response to {@link onSignatureRequested}. * * The extension must eventually call this function for every {@link onSignatureRequested} event; the API implementation will stop waiting for this call after some time and respond with a timeout error when this function is called. * * @chrome-returns-extra since Chrome 96 * @since Chrome 86 */ export function reportSignature( details: ReportSignatureDetails, ): Promise; /** * Should be called as a response to {@link onSignatureRequested}. * * The extension must eventually call this function for every {@link onSignatureRequested} event; the API implementation will stop waiting for this call after some time and respond with a timeout error when this function is called. * * @since Chrome 86 */ export function reportSignature( details: ReportSignatureDetails, callback?: () => void, ): void; } /** * Stub namespace for the "chrome\_url\_overrides" manifest key. * * @since Chrome 93 */ export namespace chrome_url_overrides { export interface UrlOverrideInfo { /** * Override for the chrome://newtab page. */ newtab?: string; /** * Override for the chrome://bookmarks page. */ bookmarks?: string; /** * Override for the chrome://history page. */ history?: string; } } /** * The `chrome.clipboard` API is provided to allow users to access data of the clipboard. This is a temporary solution for chromeos platform apps until open-web alternative is available. It will be deprecated once open-web solution is available, which could be in 2017 Q4. * * @alpha * @chrome-permission clipboard * @chrome-channel dev * @chrome-platform-apps * @chrome-platform chromeos */ export namespace clipboard { /** * Supported image types. */ export type ImageType = "png" | "jpeg"; export type DataItemType = "textPlain" | "textHtml"; export interface AdditionalDataItem { /** * Type of the additional data item. */ type: DataItemType; /** * Content of the additional data item. Either the plain text string if `type` is "textPlain" or markup string if `type` is "textHtml". The data can not exceed 2MB. */ data: string; } /** * Fired when clipboard data changes. Requires clipboard and clipboardRead permissions for adding listener to chrome.clipboard.onClipboardDataChanged event. After this event fires, the clipboard data is available by calling document.execCommand('paste'). * * @since Chrome 56 * @chrome-permission clipboardRead */ export const onClipboardDataChanged: events.Event<() => void>; /** * Sets image data to clipboard. * * @chrome-returns-extra since Chrome 91 * @param imageData The encoded image data. * @param type The type of image being passed. * @param additionalItems Additional data items for describing image data. The callback is called with `chrome.runtime.lastError` set to error code if there is an error. Requires clipboard and clipboardWrite permissions. * @since Chrome 57 * @chrome-permission clipboardWrite */ export function setImageData( /** * @since Chrome 60 */ imageData: ArrayBuffer, type: ImageType, /** * @since Chrome 60 */ additionalItems?: AdditionalDataItem[], ): Promise; /** * Sets image data to clipboard. * * @param imageData The encoded image data. * @param type The type of image being passed. * @param additionalItems Additional data items for describing image data. The callback is called with `chrome.runtime.lastError` set to error code if there is an error. Requires clipboard and clipboardWrite permissions. * @since Chrome 57 * @chrome-permission clipboardWrite */ export function setImageData( /** * @since Chrome 60 */ imageData: ArrayBuffer, type: ImageType, /** * @since Chrome 60 */ additionalItems?: AdditionalDataItem[], callback?: () => void, ): void; } /** * Use the commands API to add keyboard shortcuts that trigger actions in your extension, for example, an action to open the browser action or send a command to the extension. * * @chrome-manifest commands */ export namespace commands { export interface Command { /** * The name of the Extension Command */ name?: string; /** * The Extension Command description */ description?: string; /** * The shortcut active for this command, or blank if not active. */ shortcut?: string; } /** * Fired when a registered command is activated using a keyboard shortcut. */ export const onCommand: events.Event<( command: string, /** * @since Chrome 86 */ tab?: tabs.Tab, ) => void>; /** * Returns all the registered extension commands for this extension and their shortcut (if active). Before Chrome 110, this command did not return `_execute_action`. * * @chrome-returns-extra since Chrome 96 * @returns Resolves with a list of the registered commands. */ export function getAll(): Promise; /** * Returns all the registered extension commands for this extension and their shortcut (if active). Before Chrome 110, this command did not return `_execute_action`. */ export function getAll( callback?: ( commands: Command[], ) => void, ): void; } /** * Stub namespace for the "content\_scripts" manifest key. * * @since Chrome 88 */ export namespace contentScripts { export interface ContentScript { /** * Specifies which pages this content script will be injected into. See [Match Patterns](https://developer.chrome.com/extensions/develop/concepts/match-patterns) for more details on the syntax of these strings. */ matches: string[]; /** * Excludes pages that this content script would otherwise be injected into. See [Match Patterns](https://developer.chrome.com/extensions/develop/concepts/match-patterns) for more details on the syntax of these strings. */ exclude_matches?: string[]; /** * The list of CSS files to be injected into matching pages. These are injected in the order they appear in this array, before any DOM is constructed or displayed for the page. */ css?: string[]; /** * The list of JavaScript files to be injected into matching pages. These are injected in the order they appear in this array. */ js?: string[]; /** * If specified true, it will inject into all frames, even if the frame is not the top-most frame in the tab. Each frame is checked independently for URL requirements; it will not inject into child frames if the URL requirements are not met. Defaults to false, meaning that only the top frame is matched. */ all_frames?: boolean; /** * Whether the script should inject into any frames where the URL belongs to a scheme that would never match a specified Match Pattern, including about:, data:, blob:, and filesystem: schemes. In these cases, in order to determine if the script should inject, the origin of the URL is checked. If the origin is `null` (as is the case for data: URLs), then the "initiator" or "creator" origin is used (i.e., the origin of the frame that created or navigated this frame). Note that this may not be the parent frame, if the frame was navigated by another frame in the document hierarchy. * * @since Chrome 99 */ match_origin_as_fallback?: boolean; /** * Whether the script should inject into an about:blank frame where the parent or opener frame matches one of the patterns declared in matches. Defaults to false. */ match_about_blank?: boolean; /** * Applied after matches to include only those URLs that also match this glob. Intended to emulate the [@include](https://wiki.greasespot.net/Metadata_Block#.40include) Greasemonkey keyword. */ include_globs?: string[]; /** * Applied after matches to exclude URLs that match this glob. Intended to emulate the [@exclude](https://wiki.greasespot.net/Metadata_Block#.40exclude) Greasemonkey keyword. */ exclude_globs?: string[]; /** * Specifies when JavaScript files are injected into the web page. The preferred and default value is `document_idle`. */ run_at?: extensionTypes.RunAt; /** * The JavaScript "world" to run the script in. Defaults to `ISOLATED`. Only available in Manifest V3 extensions. * * @since Chrome 111 */ world?: extensionTypes.ExecutionWorld; } } /** * Use the `chrome.contentSettings` API to change settings that control whether websites can use features such as cookies, JavaScript, and plugins. More generally speaking, content settings allow you to customize Chrome's behavior on a per-site basis instead of globally. * * @chrome-permission contentSettings * @chrome-platform chromeos * @chrome-platform linux * @chrome-platform mac * @chrome-platform win */ export namespace contentSettings { /** * The only content type using resource identifiers is {@link contentSettings.plugins}. For more information, see [Resource Identifiers](https://developer.chrome.com/docs/extensions/reference/contentSettings/#resource-identifiers). */ export interface ResourceIdentifier { /** * The resource identifier for the given content type. */ id: string; /** * A human readable description of the resource. */ description?: string; } /** * The scope of the ContentSetting. One of * `regular`: setting for regular profile (which is inherited by the incognito profile if not overridden elsewhere), * `incognito\_session\_only`: setting for incognito profile that can only be set during an incognito session and is deleted when the incognito session ends (overrides regular settings). * * @since Chrome 44 */ export type Scope = "regular" | "incognito_session_only"; export interface ContentSetting { /** * Clear all content setting rules set by this extension. * * @chrome-returns-extra since Chrome 96 */ clear( details: { /** * Where to clear the setting (default: regular). */ scope?: Scope, }, ): Promise; /** * Clear all content setting rules set by this extension. */ clear( details: { /** * Where to clear the setting (default: regular). */ scope?: Scope, }, callback?: () => void, ): void; /** * Gets the current content setting for a given pair of URLs. * * @chrome-returns-extra since Chrome 96 */ get( details: { /** * The primary URL for which the content setting should be retrieved. Note that the meaning of a primary URL depends on the content type. */ primaryUrl: string, /** * The secondary URL for which the content setting should be retrieved. Defaults to the primary URL. Note that the meaning of a secondary URL depends on the content type, and not all content types use secondary URLs. */ secondaryUrl?: string, /** * A more specific identifier of the type of content for which the settings should be retrieved. */ resourceIdentifier?: ResourceIdentifier, /** * Whether to check the content settings for an incognito session. (default false) */ incognito?: boolean, }, ): Promise<{ /** * The content setting. See the description of the individual ContentSetting objects for the possible values. */ setting: T, }>; /** * Gets the current content setting for a given pair of URLs. */ get( details: { /** * The primary URL for which the content setting should be retrieved. Note that the meaning of a primary URL depends on the content type. */ primaryUrl: string, /** * The secondary URL for which the content setting should be retrieved. Defaults to the primary URL. Note that the meaning of a secondary URL depends on the content type, and not all content types use secondary URLs. */ secondaryUrl?: string, /** * A more specific identifier of the type of content for which the settings should be retrieved. */ resourceIdentifier?: ResourceIdentifier, /** * Whether to check the content settings for an incognito session. (default false) */ incognito?: boolean, }, callback?: ( details: { /** * The content setting. See the description of the individual ContentSetting objects for the possible values. */ setting: T, }, ) => void, ): void; /** * Applies a new content setting rule. * * @chrome-returns-extra since Chrome 96 */ set( details: { /** * The pattern for the primary URL. For details on the format of a pattern, see [Content Setting Patterns](https://developer.chrome.com/docs/extensions/reference/contentSettings/#patterns). */ primaryPattern: string, /** * The pattern for the secondary URL. Defaults to matching all URLs. For details on the format of a pattern, see [Content Setting Patterns](https://developer.chrome.com/docs/extensions/reference/contentSettings/#patterns). */ secondaryPattern?: string, /** * The resource identifier for the content type. */ resourceIdentifier?: ResourceIdentifier, /** * The setting applied by this rule. See the description of the individual ContentSetting objects for the possible values. */ setting: any, /** * Where to set the setting (default: regular). */ scope?: Scope, }, ): Promise; /** * Applies a new content setting rule. */ set( details: { /** * The pattern for the primary URL. For details on the format of a pattern, see [Content Setting Patterns](https://developer.chrome.com/docs/extensions/reference/contentSettings/#patterns). */ primaryPattern: string, /** * The pattern for the secondary URL. Defaults to matching all URLs. For details on the format of a pattern, see [Content Setting Patterns](https://developer.chrome.com/docs/extensions/reference/contentSettings/#patterns). */ secondaryPattern?: string, /** * The resource identifier for the content type. */ resourceIdentifier?: ResourceIdentifier, /** * The setting applied by this rule. See the description of the individual ContentSetting objects for the possible values. */ setting: any, /** * Where to set the setting (default: regular). */ scope?: Scope, }, callback?: () => void, ): void; /** * @chrome-returns-extra since Chrome 96 */ getResourceIdentifiers(): Promise; getResourceIdentifiers( /** * @param resourceIdentifiers A list of resource identifiers for this content type, or `undefined` if this content type does not use resource identifiers. */ callback?: ( resourceIdentifiers?: ResourceIdentifier[], ) => void, ): void; } /** * @since Chrome 113 */ export type AutoVerifyContentSetting = "allow" | "block"; /** * @since Chrome 121 */ export type ClipboardContentSetting = "allow" | "block" | "ask"; /** * @since Chrome 44 */ export type CookiesContentSetting = "allow" | "block" | "session_only"; /** * @since Chrome 44 */ export type ImagesContentSetting = "allow" | "block"; /** * @since Chrome 44 */ export type JavascriptContentSetting = "allow" | "block"; /** * @since Chrome 44 */ export type LocationContentSetting = "allow" | "block" | "ask"; /** * @since Chrome 44 */ export type PluginsContentSetting = "block"; /** * @since Chrome 44 */ export type PopupsContentSetting = "allow" | "block"; /** * @since Chrome 44 */ export type NotificationsContentSetting = "allow" | "block" | "ask"; /** * @since Chrome 44 */ export type FullscreenContentSetting = "allow"; /** * @since Chrome 44 */ export type MouselockContentSetting = "allow"; /** * @since Chrome 46 */ export type MicrophoneContentSetting = "allow" | "block" | "ask"; /** * @since Chrome 46 */ export type CameraContentSetting = "allow" | "block" | "ask"; /** * @since Chrome 44 */ export type PpapiBrokerContentSetting = "block"; /** * @since Chrome 44 */ export type MultipleAutomaticDownloadsContentSetting = "allow" | "block" | "ask"; /** * @since Chrome 141 */ export type SoundContentSetting = "allow" | "block"; /** * Whether to allow sites to use the [Private State Tokens API](https://developer.chrome.com/docs/privacy-sandbox/trust-tokens/). One of * `allow`: Allow sites to use the Private State Tokens API, * `block`: Block sites from using the Private State Tokens API. * Default is `allow`. * When calling `set()`, the primary URL pattern must be ``. The secondary URL is not used. * * @since Chrome 113 */ export const autoVerify: ContentSetting; /** * Whether to allow cookies and other local data to be set by websites. One of * `allow`: Accept cookies, * `block`: Block cookies, * `session\_only`: Accept cookies only for the current session. * Default is `allow`. * The primary URL is the URL representing the cookie origin. The secondary URL is the URL of the top-level frame. */ export const cookies: ContentSetting; /** * Whether to show images. One of * `allow`: Show images, * `block`: Don't show images. * Default is `allow`. * The primary URL is the URL of the top-level frame. The secondary URL is the URL of the image. */ export const images: ContentSetting; /** * Whether to run JavaScript. One of * `allow`: Run JavaScript, * `block`: Don't run JavaScript. * Default is `allow`. * The primary URL is the URL of the top-level frame. The secondary URL is not used. */ export const javascript: ContentSetting; /** * Whether to allow Geolocation. One of * `allow`: Allow sites to track your physical location, * `block`: Don't allow sites to track your physical location, * `ask`: Ask before allowing sites to track your physical location. * Default is `ask`. * The primary URL is the URL of the document which requested location data. The secondary URL is the URL of the top-level frame (which may or may not differ from the requesting URL). */ export const location: ContentSetting; /** * _Deprecated._ With Flash support removed in Chrome 88, this permission no longer has any effect. Value is always `block`. Calls to `set()` and `clear()` will be ignored. */ export const plugins: ContentSetting; /** * Whether to allow sites to show pop-ups. One of * `allow`: Allow sites to show pop-ups, * `block`: Don't allow sites to show pop-ups. * Default is `block`. * The primary URL is the URL of the top-level frame. The secondary URL is not used. */ export const popups: ContentSetting; /** * Whether to allow sites to show desktop notifications. One of * `allow`: Allow sites to show desktop notifications, * `block`: Don't allow sites to show desktop notifications, * `ask`: Ask when a site wants to show desktop notifications. * Default is `ask`. * The primary URL is the URL of the document which wants to show the notification. The secondary URL is not used. */ export const notifications: ContentSetting; /** * _Deprecated._ No longer has any effect. Fullscreen permission is now automatically granted for all sites. Value is always `allow`. */ export const fullscreen: ContentSetting; /** * _Deprecated._ No longer has any effect. Mouse lock permission is now automatically granted for all sites. Value is always `allow`. */ export const mouselock: ContentSetting; /** * Whether to allow sites to access the microphone. One of * `allow`: Allow sites to access the microphone, * `block`: Don't allow sites to access the microphone, * `ask`: Ask when a site wants to access the microphone. * Default is `ask`. * The primary URL is the URL of the document which requested microphone access. The secondary URL is not used. * NOTE: The 'allow' setting is not valid if both patterns are ''. * * @since Chrome 46 */ export const microphone: ContentSetting; /** * Whether to allow sites to access the clipboard via advanced capabilities of the Async Clipboard API. "Advanced" capabilities include anything besides writing built-in formats after a user gesture, i.e. the ability to read, the ability to write custom formats, and the ability to write without a user gesture. One of * `allow`: Allow sites to use advanced clipboard capabilities, * `block`: Don't allow sites to use advanced clipboard capabilties, * `ask`: Ask when a site wants to use advanced clipboard capabilities. * Default is `ask`. * The primary URL is the URL of the document which requested clipboard access. The secondary URL is not used. * * @since Chrome 121 */ export const clipboard: ContentSetting; /** * Whether to allow sites to access the camera. One of * `allow`: Allow sites to access the camera, * `block`: Don't allow sites to access the camera, * `ask`: Ask when a site wants to access the camera. * Default is `ask`. * The primary URL is the URL of the document which requested camera access. The secondary URL is not used. * NOTE: The 'allow' setting is not valid if both patterns are ''. * * @since Chrome 46 */ export const camera: ContentSetting; /** * _Deprecated._ Previously, controlled whether to allow sites to run plugins unsandboxed, however, with the Flash broker process removed in Chrome 88, this permission no longer has any effect. Value is always `block`. Calls to `set()` and `clear()` will be ignored. */ export const unsandboxedPlugins: ContentSetting; /** * Whether to allow sites to download multiple files automatically. One of * `allow`: Allow sites to download multiple files automatically, * `block`: Don't allow sites to download multiple files automatically, * `ask`: Ask when a site wants to download files automatically after the first file. * Default is `ask`. * The primary URL is the URL of the top-level frame. The secondary URL is not used. */ export const automaticDownloads: ContentSetting; } /** * Use the `chrome.contextMenus` API to add items to Google Chrome's context menu. You can choose what types of objects your context menu additions apply to, such as images, hyperlinks, and pages. * * @chrome-permission contextMenus */ export namespace contextMenus { /** * The different contexts a menu can appear in. Specifying 'all' is equivalent to the combination of all other contexts except for 'launcher'. The 'launcher' context is only supported by apps and is used to add menu items to the context menu that appears when clicking the app icon in the launcher/taskbar/dock/etc. Different platforms might put limitations on what is actually supported in a launcher context menu. * * @since Chrome 44 */ export type ContextType = "all" | "page" | "frame" | "selection" | "link" | "editable" | "image" | "video" | "audio" | "launcher" | "browser_action" | "page_action" | "action"; /** * The type of menu item. * * @since Chrome 44 */ export type ItemType = "normal" | "checkbox" | "radio" | "separator"; /** * Information sent when a context menu item is clicked. */ export interface OnClickData { /** * The ID of the menu item that was clicked. */ menuItemId: number | string; /** * The parent ID, if any, for the item clicked. */ parentMenuItemId?: number | string; /** * One of 'image', 'video', or 'audio' if the context menu was activated on one of these types of elements. */ mediaType?: string; /** * If the element is a link, the URL it points to. */ linkUrl?: string; /** * Will be present for elements with a 'src' URL. */ srcUrl?: string; /** * The URL of the page where the menu item was clicked. This property is not set if the click occured in a context where there is no current page, such as in a launcher context menu. */ pageUrl?: string; /** * The URL of the frame of the element where the context menu was clicked, if it was in a frame. */ frameUrl?: string; /** * The [ID of the frame](https://developer.chrome.com/docs/extensions/reference/webNavigation/#frame_ids) of the element where the context menu was clicked, if it was in a frame. * * @since Chrome 51 */ frameId?: number; /** * The text for the context selection, if any. */ selectionText?: string; /** * A flag indicating whether the element is editable (text input, textarea, etc.). */ editable: boolean; /** * A flag indicating the state of a checkbox or radio item before it was clicked. */ wasChecked?: boolean; /** * A flag indicating the state of a checkbox or radio item after it is clicked. */ checked?: boolean; } /** * Properties of the new context menu item. * * @since Chrome 123 */ export interface CreateProperties { /** * The type of menu item. Defaults to `normal`. */ type?: ItemType; /** * The unique ID to assign to this item. Mandatory for event pages. Cannot be the same as another ID for this extension. */ id?: string; /** * The text to display in the item; this is _required_ unless `type` is `separator`. When the context is `selection`, use `%s` within the string to show the selected text. For example, if this parameter's value is "Translate '%s' to Pig Latin" and the user selects the word "cool", the context menu item for the selection is "Translate 'cool' to Pig Latin". */ title?: string; /** * The initial state of a checkbox or radio button: `true` for selected, `false` for unselected. Only one radio button can be selected at a time in a given group. */ checked?: boolean; /** * List of contexts this menu item will appear in. Defaults to `['page']`. */ contexts?: [ContextType, ...ContextType[]]; /** * Whether the item is visible in the menu. */ visible?: boolean; /** * A function that is called back when the menu item is clicked. This is not available inside of a service worker; instead, you should register a listener for {@link contextMenus.onClicked}. * * @param info Information about the item clicked and the context where the click happened. * @param tab The details of the tab where the click took place. This parameter is not present for platform apps. */ onclick?: ( info: OnClickData, tab: tabs.Tab, ) => void; /** * The ID of a parent menu item; this makes the item a child of a previously added item. */ parentId?: number | string; /** * Restricts the item to apply only to documents or frames whose URL matches one of the given patterns. For details on pattern formats, see [Match Patterns](https://developer.chrome.com/docs/extensions/develop/concepts/match-patterns). */ documentUrlPatterns?: string[]; /** * Similar to `documentUrlPatterns`, filters based on the `src` attribute of `img`, `audio`, and `video` tags and the `href` attribute of `a` tags. */ targetUrlPatterns?: string[]; /** * Whether this context menu item is enabled or disabled. Defaults to `true`. */ enabled?: boolean; } /** * The maximum number of top level extension items that can be added to an extension action context menu. Any items beyond this limit will be ignored. */ export const ACTION_MENU_TOP_LEVEL_LIMIT: 6; /** * Fired when a context menu item is clicked. */ export const onClicked: events.Event<( info: OnClickData, tab?: tabs.Tab, ) => void>; /** * Creates a new context menu item. If an error occurs during creation, it may not be detected until the creation callback fires; details will be in {@link runtime.lastError}. * * @param callback Called when the item has been created in the browser. If an error occurs during creation, details will be available in {@link runtime.lastError}. * @returns The ID of the newly created item. */ export function create( createProperties: CreateProperties, callback?: () => void, ): number | string; /** * Updates a previously created context menu item. * * @chrome-returns-extra since Chrome 123 * @param id The ID of the item to update. * @param updateProperties The properties to update. Accepts the same values as the {@link contextMenus.create} function. * @returns Resolves when the context menu has been updated. */ export function update( id: number | string, updateProperties: { type?: ItemType, title?: string, checked?: boolean, contexts?: [ContextType, ...ContextType[]], /** * Whether the item is visible in the menu. * * @since Chrome 62 */ visible?: boolean, /** * @param tab The details of the tab where the click took place. This parameter is not present for platform apps. */ onclick?: ( /** * @since Chrome 44 */ info: OnClickData, /** * @since Chrome 44 */ tab: tabs.Tab, ) => void, /** * The ID of the item to be made this item's parent. Note: You cannot set an item to become a child of its own descendant. */ parentId?: number | string, documentUrlPatterns?: string[], targetUrlPatterns?: string[], enabled?: boolean, }, ): Promise; /** * Updates a previously created context menu item. * * @param id The ID of the item to update. * @param updateProperties The properties to update. Accepts the same values as the {@link contextMenus.create} function. */ export function update( id: number | string, updateProperties: { type?: ItemType, title?: string, checked?: boolean, contexts?: [ContextType, ...ContextType[]], /** * Whether the item is visible in the menu. * * @since Chrome 62 */ visible?: boolean, /** * @param tab The details of the tab where the click took place. This parameter is not present for platform apps. */ onclick?: ( /** * @since Chrome 44 */ info: OnClickData, /** * @since Chrome 44 */ tab: tabs.Tab, ) => void, /** * The ID of the item to be made this item's parent. Note: You cannot set an item to become a child of its own descendant. */ parentId?: number | string, documentUrlPatterns?: string[], targetUrlPatterns?: string[], enabled?: boolean, }, callback?: () => void, ): void; /** * Removes a context menu item. * * @chrome-returns-extra since Chrome 123 * @param menuItemId The ID of the context menu item to remove. * @returns Resolves when the context menu has been removed. */ export function remove( menuItemId: number | string, ): Promise; /** * Removes a context menu item. * * @param menuItemId The ID of the context menu item to remove. */ export function remove( menuItemId: number | string, callback?: () => void, ): void; /** * Removes all context menu items added by this extension. * * @chrome-returns-extra since Chrome 123 * @returns Resolves when removal is complete. */ export function removeAll(): Promise; /** * Removes all context menu items added by this extension. */ export function removeAll( callback?: () => void, ): void; } /** * Use the `chrome.cookies` API to query and modify cookies, and to be notified when they change. * * @chrome-permission cookies */ export namespace cookies { /** * A cookie's 'SameSite' state (https://tools.ietf.org/html/draft-west-first-party-cookies). 'no\_restriction' corresponds to a cookie set with 'SameSite=None', 'lax' to 'SameSite=Lax', and 'strict' to 'SameSite=Strict'. 'unspecified' corresponds to a cookie set without the SameSite attribute. * * @since Chrome 51 */ export type SameSiteStatus = "no_restriction" | "lax" | "strict" | "unspecified"; /** * Represents a partitioned cookie's partition key. * * @since Chrome 119 */ export interface CookiePartitionKey { /** * The top-level site the partitioned cookie is available in. */ topLevelSite?: string; /** * Indicates if the cookie was set in a cross-cross site context. This prevents a top-level site embedded in a cross-site context from accessing cookies set by the top-level site in a same-site context. * * @since Chrome 130 */ hasCrossSiteAncestor?: boolean; } /** * Represents information about an HTTP cookie. */ export interface Cookie { /** * The name of the cookie. */ name: string; /** * The value of the cookie. */ value: string; /** * The domain of the cookie (e.g. "www.google.com", "example.com"). */ domain: string; /** * True if the cookie is a host-only cookie (i.e. a request's host must exactly match the domain of the cookie). */ hostOnly: boolean; /** * The path of the cookie. */ path: string; /** * True if the cookie is marked as Secure (i.e. its scope is limited to secure channels, typically HTTPS). */ secure: boolean; /** * True if the cookie is marked as HttpOnly (i.e. the cookie is inaccessible to client-side scripts). */ httpOnly: boolean; /** * The cookie's same-site status (i.e. whether the cookie is sent with cross-site requests). * * @since Chrome 51 */ sameSite: SameSiteStatus; /** * True if the cookie is a session cookie, as opposed to a persistent cookie with an expiration date. */ session: boolean; /** * The expiration date of the cookie as the number of seconds since the UNIX epoch. Not provided for session cookies. */ expirationDate?: number; /** * The ID of the cookie store containing this cookie, as provided in getAllCookieStores(). */ storeId: string; /** * The partition key for reading or modifying cookies with the Partitioned attribute. * * @since Chrome 119 */ partitionKey?: CookiePartitionKey; } /** * Represents a cookie store in the browser. An incognito mode window, for instance, uses a separate cookie store from a non-incognito window. */ export interface CookieStore { /** * The unique identifier for the cookie store. */ id: string; /** * Identifiers of all the browser tabs that share this cookie store. */ tabIds: number[]; } /** * The underlying reason behind the cookie's change. If a cookie was inserted, or removed via an explicit call to "chrome.cookies.remove", "cause" will be "explicit". If a cookie was automatically removed due to expiry, "cause" will be "expired". If a cookie was removed due to being overwritten with an already-expired expiration date, "cause" will be set to "expired\_overwrite". If a cookie was automatically removed due to garbage collection, "cause" will be "evicted". If a cookie was automatically removed due to a "set" call that overwrote it, "cause" will be "overwrite". Plan your response accordingly. * * @since Chrome 44 */ export type OnChangedCause = "evicted" | "expired" | "explicit" | "expired_overwrite" | "overwrite"; /** * Details to identify the cookie. * * @since Chrome 88 */ export interface CookieDetails { /** * The URL with which the cookie to access is associated. This argument may be a full URL, in which case any data following the URL path (e.g. the query string) is simply ignored. If host permissions for this URL are not specified in the manifest file, the API call will fail. */ url: string; /** * The name of the cookie to access. */ name: string; /** * The ID of the cookie store in which to look for the cookie. By default, the current execution context's cookie store will be used. */ storeId?: string; /** * The partition key for reading or modifying cookies with the Partitioned attribute. * * @since Chrome 119 */ partitionKey?: CookiePartitionKey; } /** * Details to identify the frame. * * @since Chrome 132 */ export interface FrameDetails { /** * The unique identifier for the tab containing the frame. */ tabId?: number; /** * The unique identifier for the frame within the tab. */ frameId?: number; /** * The unique identifier for the document. If the frameId and/or tabId are provided they will be validated to match the document found by provided document ID. */ documentId?: string; } /** * Fired when a cookie is set or removed. As a special case, note that updating a cookie's properties is implemented as a two step process: the cookie to be updated is first removed entirely, generating a notification with "cause" of "overwrite" . Afterwards, a new cookie is written with the updated values, generating a second notification with "cause" "explicit". */ export const onChanged: events.Event<( changeInfo: { /** * True if a cookie was removed. */ removed: boolean, /** * Information about the cookie that was set or removed. */ cookie: Cookie, /** * The underlying reason behind the cookie's change. */ cause: OnChangedCause, }, ) => void>; /** * Retrieves information about a single cookie. If more than one cookie of the same name exists for the given URL, the one with the longest path will be returned. For cookies with the same path length, the cookie with the earliest creation time will be returned. * * @chrome-returns-extra since Chrome 88 */ export function get( details: CookieDetails, ): Promise; /** * Retrieves information about a single cookie. If more than one cookie of the same name exists for the given URL, the one with the longest path will be returned. For cookies with the same path length, the cookie with the earliest creation time will be returned. */ export function get( details: CookieDetails, /** * @param cookie Contains details about the cookie. This parameter is null if no such cookie was found. */ callback?: ( cookie?: Cookie, ) => void, ): void; /** * Retrieves all cookies from a single cookie store that match the given information. The cookies returned will be sorted, with those with the longest path first. If multiple cookies have the same path length, those with the earliest creation time will be first. This method only retrieves cookies for domains that the extension has host permissions to. * * @chrome-returns-extra since Chrome 88 * @param details Information to filter the cookies being retrieved. */ export function getAll( details: { /** * Restricts the retrieved cookies to those that would match the given URL. */ url?: string, /** * Filters the cookies by name. */ name?: string, /** * Restricts the retrieved cookies to those whose domains match or are subdomains of this one. */ domain?: string, /** * Restricts the retrieved cookies to those whose path exactly matches this string. */ path?: string, /** * Filters the cookies by their Secure property. */ secure?: boolean, /** * Filters out session vs. persistent cookies. */ session?: boolean, /** * The cookie store to retrieve cookies from. If omitted, the current execution context's cookie store will be used. */ storeId?: string, /** * The partition key for reading or modifying cookies with the Partitioned attribute. * * @since Chrome 119 */ partitionKey?: CookiePartitionKey, }, ): Promise; /** * Retrieves all cookies from a single cookie store that match the given information. The cookies returned will be sorted, with those with the longest path first. If multiple cookies have the same path length, those with the earliest creation time will be first. This method only retrieves cookies for domains that the extension has host permissions to. * * @param details Information to filter the cookies being retrieved. */ export function getAll( details: { /** * Restricts the retrieved cookies to those that would match the given URL. */ url?: string, /** * Filters the cookies by name. */ name?: string, /** * Restricts the retrieved cookies to those whose domains match or are subdomains of this one. */ domain?: string, /** * Restricts the retrieved cookies to those whose path exactly matches this string. */ path?: string, /** * Filters the cookies by their Secure property. */ secure?: boolean, /** * Filters out session vs. persistent cookies. */ session?: boolean, /** * The cookie store to retrieve cookies from. If omitted, the current execution context's cookie store will be used. */ storeId?: string, /** * The partition key for reading or modifying cookies with the Partitioned attribute. * * @since Chrome 119 */ partitionKey?: CookiePartitionKey, }, /** * @param cookies All the existing, unexpired cookies that match the given cookie info. */ callback?: ( cookies: Cookie[], ) => void, ): void; /** * Sets a cookie with the given cookie data; may overwrite equivalent cookies if they exist. * * @chrome-returns-extra since Chrome 88 * @param details Details about the cookie being set. */ export function set( details: { /** * The request-URI to associate with the setting of the cookie. This value can affect the default domain and path values of the created cookie. If host permissions for this URL are not specified in the manifest file, the API call will fail. */ url: string, /** * The name of the cookie. Empty by default if omitted. */ name?: string, /** * The value of the cookie. Empty by default if omitted. */ value?: string, /** * The domain of the cookie. If omitted, the cookie becomes a host-only cookie. */ domain?: string, /** * The path of the cookie. Defaults to the path portion of the url parameter. */ path?: string, /** * Whether the cookie should be marked as Secure. Defaults to false. */ secure?: boolean, /** * Whether the cookie should be marked as HttpOnly. Defaults to false. */ httpOnly?: boolean, /** * The cookie's same-site status. Defaults to "unspecified", i.e., if omitted, the cookie is set without specifying a SameSite attribute. * * @since Chrome 51 */ sameSite?: SameSiteStatus, /** * The expiration date of the cookie as the number of seconds since the UNIX epoch. If omitted, the cookie becomes a session cookie. */ expirationDate?: number, /** * The ID of the cookie store in which to set the cookie. By default, the cookie is set in the current execution context's cookie store. */ storeId?: string, /** * The partition key for reading or modifying cookies with the Partitioned attribute. * * @since Chrome 119 */ partitionKey?: CookiePartitionKey, }, ): Promise; /** * Sets a cookie with the given cookie data; may overwrite equivalent cookies if they exist. * * @param details Details about the cookie being set. */ export function set( details: { /** * The request-URI to associate with the setting of the cookie. This value can affect the default domain and path values of the created cookie. If host permissions for this URL are not specified in the manifest file, the API call will fail. */ url: string, /** * The name of the cookie. Empty by default if omitted. */ name?: string, /** * The value of the cookie. Empty by default if omitted. */ value?: string, /** * The domain of the cookie. If omitted, the cookie becomes a host-only cookie. */ domain?: string, /** * The path of the cookie. Defaults to the path portion of the url parameter. */ path?: string, /** * Whether the cookie should be marked as Secure. Defaults to false. */ secure?: boolean, /** * Whether the cookie should be marked as HttpOnly. Defaults to false. */ httpOnly?: boolean, /** * The cookie's same-site status. Defaults to "unspecified", i.e., if omitted, the cookie is set without specifying a SameSite attribute. * * @since Chrome 51 */ sameSite?: SameSiteStatus, /** * The expiration date of the cookie as the number of seconds since the UNIX epoch. If omitted, the cookie becomes a session cookie. */ expirationDate?: number, /** * The ID of the cookie store in which to set the cookie. By default, the cookie is set in the current execution context's cookie store. */ storeId?: string, /** * The partition key for reading or modifying cookies with the Partitioned attribute. * * @since Chrome 119 */ partitionKey?: CookiePartitionKey, }, /** * @param cookie Contains details about the cookie that's been set. If setting failed for any reason, the promise will be rejected. */ callback?: ( cookie?: Cookie, ) => void, ): void; /** * Deletes a cookie by name. * * @chrome-returns-extra since Chrome 88 */ export function remove( details: CookieDetails, ): Promise<{ /** * The URL associated with the cookie that's been removed. */ url: string, /** * The name of the cookie that's been removed. */ name: string, /** * The ID of the cookie store from which the cookie was removed. */ storeId: string, /** * The partition key for reading or modifying cookies with the Partitioned attribute. * * @since Chrome 119 */ partitionKey?: CookiePartitionKey, } | undefined>; /** * Deletes a cookie by name. */ export function remove( details: CookieDetails, /** * @param details Contains details about the cookie that's been removed. If removal failed for any reason, the promise will be rejected. */ callback?: ( details?: { /** * The URL associated with the cookie that's been removed. */ url: string, /** * The name of the cookie that's been removed. */ name: string, /** * The ID of the cookie store from which the cookie was removed. */ storeId: string, /** * The partition key for reading or modifying cookies with the Partitioned attribute. * * @since Chrome 119 */ partitionKey?: CookiePartitionKey, }, ) => void, ): void; /** * Lists all existing cookie stores. * * @chrome-returns-extra since Chrome 88 */ export function getAllCookieStores(): Promise; /** * Lists all existing cookie stores. */ export function getAllCookieStores( /** * @param cookieStores All the existing cookie stores. */ callback?: ( cookieStores: CookieStore[], ) => void, ): void; /** * The partition key for the frame indicated. * * @since Chrome 132 */ export function getPartitionKey( details: FrameDetails, ): Promise<{ /** * The partition key for reading or modifying cookies with the Partitioned attribute. */ partitionKey: CookiePartitionKey, }>; /** * The partition key for the frame indicated. * * @since Chrome 132 */ export function getPartitionKey( details: FrameDetails, /** * @param details Contains details about the partition key that's been retrieved. */ callback?: ( details: { /** * The partition key for reading or modifying cookies with the Partitioned attribute. */ partitionKey: CookiePartitionKey, }, ) => void, ): void; } /** * Stub namespace for manifest keys relating to the cross origin isolation response headers. * * @since Chrome 93 */ export namespace crossOriginIsolation { export interface ResponseHeader { value?: string; } } /** * The `chrome.debugger` API serves as an alternate transport for Chrome's [remote debugging protocol](https://developer.chrome.com/devtools/docs/debugger-protocol). Use `chrome.debugger` to attach to one or more tabs to instrument network interaction, debug JavaScript, mutate the DOM and CSS, and more. Use the {@link Debuggee} property `tabId` to target tabs with `sendCommand` and route events by `tabId` from `onEvent` callbacks. * * @chrome-permission debugger */ namespace _debugger { /** * Debuggee identifier. Either tabId, extensionId or targetId must be specified */ export interface Debuggee { /** * The id of the tab which you intend to debug. */ tabId?: number; /** * The id of the extension which you intend to debug. Attaching to an extension background page is only possible when the `--silent-debugger-extension-api` command-line switch is used. */ extensionId?: string; /** * The opaque id of the debug target. */ targetId?: string; } /** * Debugger session identifier. One of tabId, extensionId or targetId must be specified. Additionally, an optional sessionId can be provided. If sessionId is specified for arguments sent from {@link onEvent}, it means the event is coming from a child protocol session within the root debuggee session. If sessionId is specified when passed to {@link sendCommand}, it targets a child protocol session within the root debuggee session. * * @since Chrome 125 */ export interface DebuggerSession { /** * The id of the tab which you intend to debug. */ tabId?: number; /** * The id of the extension which you intend to debug. Attaching to an extension background page is only possible when the `--silent-debugger-extension-api` command-line switch is used. */ extensionId?: string; /** * The opaque id of the debug target. */ targetId?: string; /** * The opaque id of the Chrome DevTools Protocol session. Identifies a child session within the root session identified by tabId, extensionId or targetId. */ sessionId?: string; } /** * Target type. * * @since Chrome 44 */ export type TargetInfoType = "page" | "background_page" | "worker" | "other"; /** * Connection termination reason. * * @since Chrome 44 */ export type DetachReason = "target_closed" | "canceled_by_user"; /** * Debug target information */ export interface TargetInfo { /** * Target type. */ type: TargetInfoType; /** * Target id. */ id: string; /** * The tab id, defined if type == 'page'. */ tabId?: number; /** * The extension id, defined if type = 'background\_page'. */ extensionId?: string; /** * True if debugger is already attached. */ attached: boolean; /** * Target page title. */ title: string; /** * Target URL. */ url: string; /** * Target favicon URL. */ faviconUrl?: string; } /** * Fired whenever debugging target issues instrumentation event. */ export const onEvent: events.Event<( source: DebuggerSession, method: string, params?: {[name: string]: any}, ) => void>; /** * Fired when browser terminates debugging session for the tab. This happens when either the tab is being closed or Chrome DevTools is being invoked for the attached tab. */ export const onDetach: events.Event<( source: Debuggee, reason: DetachReason, ) => void>; /** * Attaches debugger to the given target. * * @chrome-returns-extra since Chrome 96 * @param target Debugging target to which you want to attach. * @param requiredVersion Required debugging protocol version ("0.1"). One can only attach to the debuggee with matching major version and greater or equal minor version. List of the protocol versions can be obtained [here](https://developer.chrome.com/devtools/docs/debugger-protocol). * @returns Resolves once the attach operation succeeds or fails. The promise resolves with no value. If the attach fails, the promise will be rejected. */ export function attach( target: Debuggee, requiredVersion: string, ): Promise; /** * Attaches debugger to the given target. * * @param target Debugging target to which you want to attach. * @param requiredVersion Required debugging protocol version ("0.1"). One can only attach to the debuggee with matching major version and greater or equal minor version. List of the protocol versions can be obtained [here](https://developer.chrome.com/devtools/docs/debugger-protocol). */ export function attach( target: Debuggee, requiredVersion: string, callback?: () => void, ): void; /** * Detaches debugger from the given target. * * @chrome-returns-extra since Chrome 96 * @param target Debugging target from which you want to detach. * @returns Resolves once the detach operation succeeds or fails. The promise resolves with no value. If the detach fails, the promise will be rejected. */ export function detach( target: Debuggee, ): Promise; /** * Detaches debugger from the given target. * * @param target Debugging target from which you want to detach. */ export function detach( target: Debuggee, callback?: () => void, ): void; /** * Sends given command to the debugging target. * * @chrome-returns-extra since Chrome 96 * @param target Debugging target to which you want to send the command. * @param method Method name. Should be one of the methods defined by the [remote debugging protocol](https://developer.chrome.com/devtools/docs/debugger-protocol). * @param commandParams JSON object with request parameters. This object must conform to the remote debugging params scheme for given method. * @returns Response body. If an error occurs while posting the message, the promise will be rejected. */ export function sendCommand( target: DebuggerSession, method: string, commandParams?: {[name: string]: any}, ): Promise<{[name: string]: any} | undefined>; /** * Sends given command to the debugging target. * * @param target Debugging target to which you want to send the command. * @param method Method name. Should be one of the methods defined by the [remote debugging protocol](https://developer.chrome.com/devtools/docs/debugger-protocol). * @param commandParams JSON object with request parameters. This object must conform to the remote debugging params scheme for given method. */ export function sendCommand( target: DebuggerSession, method: string, commandParams?: {[name: string]: any}, /** * @param result JSON object with the response. Structure of the response varies depending on the method name and is defined by the 'returns' attribute of the command description in the remote debugging protocol. */ callback?: ( result?: {[name: string]: any}, ) => void, ): void; /** * Returns the list of available debug targets. * * @chrome-returns-extra since Chrome 96 */ export function getTargets(): Promise; /** * Returns the list of available debug targets. */ export function getTargets( /** * @param result Array of TargetInfo objects corresponding to the available debug targets. */ callback?: ( result: TargetInfo[], ) => void, ): void; } export {_debugger as debugger}; /** * Use the `chrome.declarativeContent` API to take actions depending on the content of a page, without requiring permission to read the page's content. * * @chrome-permission declarativeContent */ export namespace declarativeContent { /** * See [https://developer.mozilla.org/en-US/docs/Web/API/ImageData](https://developer.mozilla.org/en-US/docs/Web/API/ImageData). */ export type ImageDataType = ImageData; /** * Matches the state of a web page based on various criteria. */ export class PageStateMatcher { constructor(arg: PageStateMatcher); /** * Matches if the conditions of the `UrlFilter` are fulfilled for the top-level URL of the page. */ pageUrl?: events.UrlFilter; /** * Matches if all of the CSS selectors in the array match displayed elements in a frame with the same origin as the page's main frame. All selectors in this array must be [compound selectors](https://www.w3.org/TR/selectors4/#compound) to speed up matching. Note: Listing hundreds of CSS selectors or listing CSS selectors that match hundreds of times per page can slow down web sites. */ css?: string[]; /** * Matches if the bookmarked state of the page is equal to the specified value. Requres the [bookmarks permission](https://developer.chrome.com/docs/extensions/develop/concepts/declare-permissions). * * @since Chrome 45 */ isBookmarked?: boolean; } /** * A declarative event action that sets the extension's {@link pageAction page action} to an enabled state while the corresponding conditions are met. This action can be used without [host permissions](https://developer.chrome.com/docs/extensions/develop/concepts/declare-permissions#host-permissions), but the extension must have a page action. If the extension has the [activeTab](https://developer.chrome.com/docs/extensions/develop/concepts/activeTab) permission, clicking the page action grants access to the active tab. * * On pages where the conditions are not met the extension's toolbar action will be grey-scale, and clicking it will open the context menu, instead of triggering the action. * * @deprecated Please use {@link declarativeContent.ShowAction}. * @chrome-deprecated-since Chrome 97 */ export class ShowPageAction { constructor(arg: ShowPageAction); } /** * A declarative event action that sets the extension's toolbar {@link action action} to an enabled state while the corresponding conditions are met. This action can be used without [host permissions](https://developer.chrome.com/docs/extensions/develop/concepts/declare-permissions#host-permissions). If the extension has the [activeTab](https://developer.chrome.com/docs/extensions/develop/concepts/activeTab) permission, clicking the page action grants access to the active tab. * * On pages where the conditions are not met the extension's toolbar action will be grey-scale, and clicking it will open the context menu, instead of triggering the action. * * @since Chrome 97 */ export class ShowAction { constructor(arg: ShowAction); } /** * Declarative event action that sets the n-dip square icon for the extension's {@link pageAction page action} or {@link browserAction browser action} while the corresponding conditions are met. This action can be used without [host permissions](https://developer.chrome.com/docs/extensions/develop/concepts/declare-permissions#host-permissions), but the extension must have a page or browser action. * * Exactly one of `imageData` or `path` must be specified. Both are dictionaries mapping a number of pixels to an image representation. The image representation in `imageData` is an [ImageData](https://developer.mozilla.org/en-US/docs/Web/API/ImageData) object; for example, from a `canvas` element, while the image representation in `path` is the path to an image file relative to the extension's manifest. If `scale` screen pixels fit into a device-independent pixel, the `scale * n` icon is used. If that scale is missing, another image is resized to the required size. */ export class SetIcon { constructor(arg: SetIcon); /** * 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?: ImageDataType | {[name: string]: any}; } /** * Declarative event action that injects a content script. * * **WARNING:** This action is still experimental and is not supported on stable builds of Chrome. */ export class RequestContentScript { constructor(arg: RequestContentScript); /** * Names of CSS files to be injected as a part of the content script. */ css?: string[]; /** * Names of JavaScript files to be injected as a part of the content script. */ js?: string[]; /** * Whether the content script runs in all frames of the matching page, or in only the top frame. Default is `false`. */ allFrames?: boolean; /** * Whether to insert the content script on `about:blank` and `about:srcdoc`. Default is `false`. */ matchAboutBlank?: boolean; } export const onPageChanged: events.Event; } /** * The `chrome.declarativeNetRequest` API is used to block or modify network requests by specifying declarative rules. This lets extensions modify network requests without intercepting them and viewing their content, thus providing more privacy. * * @since Chrome 84 * @chrome-permission declarativeNetRequest * @chrome-permission declarativeNetRequestWithHostAccess */ export namespace declarativeNetRequest { /** * This describes the resource type of the network request. */ export type ResourceType = "main_frame" | "sub_frame" | "stylesheet" | "script" | "image" | "font" | "object" | "xmlhttprequest" | "ping" | "csp_report" | "media" | "websocket" | "webtransport" | "webbundle" | "other"; /** * This describes the HTTP request method of a network request. * * @since Chrome 91 */ export type RequestMethod = "connect" | "delete" | "get" | "head" | "options" | "patch" | "post" | "put" | "other"; /** * This describes whether the request is first or third party to the frame in which it originated. A request is said to be first party if it has the same domain (eTLD+1) as the frame in which the request originated. * * @chrome-enum "firstParty" The network request is first party to the frame in which it originated. * @chrome-enum "thirdParty" The network request is third party to the frame in which it originated. */ export type DomainType = "firstParty" | "thirdParty"; /** * This describes the possible operations for a "modifyHeaders" rule. * * @chrome-enum "append" Adds a new entry for the specified header. When modifying the headers of a request, this operation is only supported for [specific headers](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#header_modification). * @chrome-enum "set" Sets a new value for the specified header, removing any existing headers with the same name. * @chrome-enum "remove" Removes all entries for the specified header. * @since Chrome 86 */ export type HeaderOperation = "append" | "set" | "remove"; /** * Describes the kind of action to take if a given RuleCondition matches. * * @chrome-enum "block" Block the network request. * @chrome-enum "redirect" Redirect the network request. * @chrome-enum "allow" Allow the network request. The request won't be intercepted if there is an allow rule which matches it. * @chrome-enum "upgradeScheme" Upgrade the network request url's scheme to https if the request is http or ftp. * @chrome-enum "modifyHeaders" Modify request/response headers from the network request. * @chrome-enum "allowAllRequests" Allow all requests within a frame hierarchy, including the frame request itself. */ export type RuleActionType = "block" | "redirect" | "allow" | "upgradeScheme" | "modifyHeaders" | "allowAllRequests"; /** * Describes the reason why a given regular expression isn't supported. * * @chrome-enum "syntaxError" The regular expression is syntactically incorrect, or uses features not available in the [RE2 syntax](https://github.com/google/re2/wiki/Syntax). * @chrome-enum "memoryLimitExceeded" The regular expression exceeds the memory limit. * @since Chrome 87 */ export type UnsupportedRegexReason = "syntaxError" | "memoryLimitExceeded"; /** * @since Pending */ export type RuleConditionKeys = "urlFilter" | "regexFilter" | "isUrlFilterCaseSensitive" | "initiatorDomains" | "excludedInitiatorDomains" | "requestDomains" | "excludedRequestDomains" | "topDomains" | "excludedTopDomains" | "domains" | "excludedDomains" | "resourceTypes" | "excludedResourceTypes" | "requestMethods" | "excludedRequestMethods" | "domainType" | "tabIds" | "excludedTabIds" | "responseHeaders" | "excludedResponseHeaders"; export interface Ruleset { /** * A non-empty string uniquely identifying the ruleset. IDs beginning with '\_' are reserved for internal use. */ id: string; /** * The path of the JSON ruleset relative to the extension directory. */ path: string; /** * Whether the ruleset is enabled by default. */ enabled: boolean; } export interface QueryKeyValue { key: string; value: string; /** * If true, the query key is replaced only if it's already present. Otherwise, the key is also added if it's missing. Defaults to false. * * @since Chrome 94 */ replaceOnly?: boolean; } export interface QueryTransform { /** * The list of query keys to be removed. */ removeParams?: string[]; /** * The list of query key-value pairs to be added or replaced. */ addOrReplaceParams?: QueryKeyValue[]; } export interface URLTransform { /** * The new scheme for the request. Allowed values are "http", "https", "ftp" and "chrome-extension". */ scheme?: string; /** * The new host for the request. */ host?: string; /** * The new port for the request. If empty, the existing port is cleared. */ port?: string; /** * The new path for the request. If empty, the existing path is cleared. */ path?: string; /** * The new query for the request. Should be either empty, in which case the existing query is cleared; or should begin with '?'. */ query?: string; /** * Add, remove or replace query key-value pairs. */ queryTransform?: QueryTransform; /** * The new fragment for the request. Should be either empty, in which case the existing fragment is cleared; or should begin with '#'. */ fragment?: string; /** * The new username for the request. */ username?: string; /** * The new password for the request. */ password?: string; } export interface Redirect { /** * Path relative to the extension directory. Should start with '/'. */ extensionPath?: string; /** * Url transformations to perform. */ transform?: URLTransform; /** * The redirect url. Redirects to JavaScript urls are not allowed. */ url?: string; /** * Substitution pattern for rules which specify a `regexFilter`. The first match of `regexFilter` within the url will be replaced with this pattern. Within `regexSubstitution`, backslash-escaped digits (\\1 to \\9) can be used to insert the corresponding capture groups. \\0 refers to the entire matching text. */ regexSubstitution?: string; } /** * @since Chrome 128 */ export interface HeaderInfo { /** * The name of the header. This condition matches on the name only if both `values` and `excludedValues` are not specified. */ header: string; /** * If specified, this condition matches if the header's value matches at least one pattern in this list. This supports case-insensitive header value matching plus the following constructs: * * **'\*'** : Matches any number of characters. * * **'?'** : Matches zero or one character(s). * * '\*' and '?' can be escaped with a backslash, e.g. '\\\*' and '\\?' */ values?: string[]; /** * If specified, this condition is not matched if the header exists but its value contains at least one element in this list. This uses the same match pattern syntax as `values`. */ excludedValues?: string[]; } export interface RuleCondition { /** * The pattern which is matched against the network request url. Supported constructs: * * **'\*'** : Wildcard: Matches any number of characters. * * **'|'** : Left/right anchor: If used at either end of the pattern, specifies the beginning/end of the url respectively. * * **'||'** : Domain name anchor: If used at the beginning of the pattern, specifies the start of a (sub-)domain of the URL. * * **'^'** : Separator character: This matches anything except a letter, a digit, or one of the following: `_`, `-`, `.`, or `%`. This also match the end of the URL. * * Therefore `urlFilter` is composed of the following parts: (optional Left/Domain name anchor) + pattern + (optional Right anchor). * * If omitted, all urls are matched. An empty string is not allowed. * * A pattern beginning with `||*` is not allowed. Use `*` instead. * * Note: Only one of `urlFilter` or `regexFilter` can be specified. * * Note: The `urlFilter` must be composed of only ASCII characters. This is matched against a url where the host is encoded in the punycode format (in case of internationalized domains) and any other non-ascii characters are url encoded in utf-8. For example, when the request url is http://abc.рф?q=ф, the `urlFilter` will be matched against the url http://abc.xn--p1ai/?q=%D1%84. */ urlFilter?: string; /** * Regular expression to match against the network request url. This follows the [RE2 syntax](https://github.com/google/re2/wiki/Syntax). * * Note: Only one of `urlFilter` or `regexFilter` can be specified. * * Note: The `regexFilter` must be composed of only ASCII characters. This is matched against a url where the host is encoded in the punycode format (in case of internationalized domains) and any other non-ascii characters are url encoded in utf-8. */ regexFilter?: string; /** * Whether the `urlFilter` or `regexFilter` (whichever is specified) is case sensitive. Default is false. */ isUrlFilterCaseSensitive?: boolean; /** * The rule will only match network requests originating from the list of `initiatorDomains`. If the list is omitted, the rule is applied to requests from all domains. An empty list is not allowed. * * Notes: * * * Sub-domains like "a.example.com" are also allowed. * * The entries must consist of only ascii characters. * * Use punycode encoding for internationalized domains. * * This matches against the request initiator and not the request url. * * Sub-domains of the listed domains are also matched. * * @since Chrome 101 */ initiatorDomains?: string[]; /** * The rule will not match network requests originating from the list of `excludedInitiatorDomains`. If the list is empty or omitted, no domains are excluded. This takes precedence over `initiatorDomains`. * * Notes: * * * Sub-domains like "a.example.com" are also allowed. * * The entries must consist of only ascii characters. * * Use punycode encoding for internationalized domains. * * This matches against the request initiator and not the request url. * * Sub-domains of the listed domains are also excluded. * * @since Chrome 101 */ excludedInitiatorDomains?: string[]; /** * The rule will only match network requests when the domain matches one from the list of `requestDomains`. If the list is omitted, the rule is applied to requests from all domains. An empty list is not allowed. * * Notes: * * * Sub-domains like "a.example.com" are also allowed. * * The entries must consist of only ascii characters. * * Use punycode encoding for internationalized domains. * * Sub-domains of the listed domains are also matched. * * @since Chrome 101 */ requestDomains?: string[]; /** * The rule will not match network requests when the domains matches one from the list of `excludedRequestDomains`. If the list is empty or omitted, no domains are excluded. This takes precedence over `requestDomains`. * * Notes: * * * Sub-domains like "a.example.com" are also allowed. * * The entries must consist of only ascii characters. * * Use punycode encoding for internationalized domains. * * Sub-domains of the listed domains are also excluded. * * @since Chrome 101 */ excludedRequestDomains?: string[]; /** * The rule will only match network requests when the associated top-level frame's domain matches one from the list of `topDomains`. If the list is omitted, the rule is applied to requests associated with all top-level frame domains. An empty list is not allowed. * * Notes: * * * Sub-domains like "a.example.com" are also allowed. * * The entries must consist of only ascii characters. * * Use punycode encoding for internationalized domains. * * Sub-domains of the listed domains are also matched. * * For requests with no associated top-level frame (e.g. ServiceWorker initiated requests, the request initiator's domain is considered instead. * * @since Pending */ topDomains?: string[]; /** * The rule will not match network requests when the associated top-level frame's domain matches one from the list of `excludedTopDomains`. If the list is empty or omitted, no domains are excluded. This takes precedence over `topDomains`. * * Notes: * * * Sub-domains like "a.example.com" are also allowed. * * The entries must consist of only ascii characters. * * Use punycode encoding for internationalized domains. * * Sub-domains of the listed domains are also excluded. * * For requests with no associated top-level frame (e.g. ServiceWorker initiated requests, the request initiator's domain is considered instead. * * @since Pending */ excludedTopDomains?: string[]; /** * The rule will only match network requests originating from the list of `domains`. * * @deprecated Use {@link initiatorDomains} instead * @chrome-deprecated-since Chrome 101 */ domains?: string[]; /** * The rule will not match network requests originating from the list of `excludedDomains`. * * @deprecated Use {@link excludedInitiatorDomains} instead * @chrome-deprecated-since Chrome 101 */ excludedDomains?: string[]; /** * List of resource types which the rule can match. An empty list is not allowed. * * Note: this must be specified for `allowAllRequests` rules and may only include the `sub_frame` and `main_frame` resource types. */ resourceTypes?: ResourceType[]; /** * List of resource types which the rule won't match. Only one of `resourceTypes` and `excludedResourceTypes` should be specified. If neither of them is specified, all resource types except "main\_frame" are blocked. */ excludedResourceTypes?: ResourceType[]; /** * List of HTTP request methods which the rule can match. An empty list is not allowed. * * Note: Specifying a `requestMethods` rule condition will also exclude non-HTTP(s) requests, whereas specifying `excludedRequestMethods` will not. * * @since Chrome 91 */ requestMethods?: RequestMethod[]; /** * List of request methods which the rule won't match. Only one of `requestMethods` and `excludedRequestMethods` should be specified. If neither of them is specified, all request methods are matched. * * @since Chrome 91 */ excludedRequestMethods?: RequestMethod[]; /** * Specifies whether the network request is first-party or third-party to the domain from which it originated. If omitted, all requests are accepted. */ domainType?: DomainType; /** * List of {@link tabs.Tab.id} which the rule should match. An ID of {@link tabs.TAB_ID_NONE} matches requests which don't originate from a tab. An empty list is not allowed. Only supported for session-scoped rules. * * @since Chrome 92 */ tabIds?: number[]; /** * List of {@link tabs.Tab.id} which the rule should not match. An ID of {@link tabs.TAB_ID_NONE} excludes requests which don't originate from a tab. Only supported for session-scoped rules. * * @since Chrome 92 */ excludedTabIds?: number[]; /** * Rule matches if the request matches any response header condition in this list (if specified). * * @since Chrome 128 */ responseHeaders?: HeaderInfo[]; /** * Rule does not match if the request matches any response header condition in this list (if specified). If both `excludedResponseHeaders` and `responseHeaders` are specified, then the `excludedResponseHeaders` property takes precedence. * * @since Chrome 128 */ excludedResponseHeaders?: HeaderInfo[]; } /** * @since Chrome 86 */ export interface ModifyHeaderInfo { /** * The name of the header to be modified. */ header: string; /** * The operation to be performed on a header. */ operation: HeaderOperation; /** * The new value for the header. Must be specified for `append` and `set` operations. */ value?: string; } export interface RuleAction { /** * The type of action to perform. */ type: RuleActionType; /** * Describes how the redirect should be performed. Only valid for redirect rules. */ redirect?: Redirect; /** * The request headers to modify for the request. Only valid if RuleActionType is "modifyHeaders". * * @since Chrome 86 */ requestHeaders?: ModifyHeaderInfo[]; /** * The response headers to modify for the request. Only valid if RuleActionType is "modifyHeaders". * * @since Chrome 86 */ responseHeaders?: ModifyHeaderInfo[]; } export interface Rule { /** * An id which uniquely identifies a rule. Mandatory and should be >= 1. */ id: number; /** * Rule priority. Defaults to 1. When specified, should be >= 1. */ priority?: number; /** * The condition under which this rule is triggered. */ condition: RuleCondition; /** * The action to take if this rule is matched. */ action: RuleAction; } export interface MatchedRule { /** * A matching rule's ID. */ ruleId: number; /** * ID of the {@link Ruleset} this rule belongs to. For a rule originating from the set of dynamic rules, this will be equal to {@link DYNAMIC_RULESET_ID}. */ rulesetId: string; } /** * @since Chrome 111 */ export interface GetRulesFilter { /** * If specified, only rules with matching IDs are included. */ ruleIds?: number[]; } export interface MatchedRuleInfo { rule: MatchedRule; /** * The time the rule was matched. Timestamps will correspond to the Javascript convention for times, i.e. number of milliseconds since the epoch. */ timeStamp: number; /** * The tabId of the tab from which the request originated if the tab is still active. Else -1. */ tabId: number; } export interface MatchedRulesFilter { /** * If specified, only matches rules for the given tab. Matches rules not associated with any active tab if set to -1. */ tabId?: number; /** * If specified, only matches rules after the given timestamp. */ minTimeStamp?: number; } export interface RulesMatchedDetails { /** * Rules matching the given filter. */ rulesMatchedInfo: MatchedRuleInfo[]; } export interface RequestDetails { /** * The ID of the request. Request IDs are unique within a browser session. */ requestId: string; /** * The URL of the request. */ url: string; /** * The origin where the request was initiated. This does not change through redirects. If this is an opaque origin, the string 'null' will be used. */ initiator?: string; /** * Standard HTTP method. */ method: string; /** * The value 0 indicates that the request happens in the main frame; a positive value indicates the ID of a subframe in which the request happens. If the document of a (sub-)frame is loaded (`type` is `main_frame` or `sub_frame`), `frameId` indicates the ID of this frame, not the ID of the outer frame. Frame IDs are unique within a tab. */ frameId: number; /** * The unique identifier for the frame's document, if this request is for a frame. * * @since Chrome 106 */ documentId?: string; /** * The type of the frame, if this request is for a frame. * * @since Chrome 106 */ frameType?: extensionTypes.FrameType; /** * The lifecycle of the frame's document, if this request is for a frame. * * @since Chrome 106 */ documentLifecycle?: extensionTypes.DocumentLifecycle; /** * ID of frame that wraps the frame which sent the request. Set to -1 if no parent frame exists. */ parentFrameId: number; /** * The unique identifier for the frame's parent document, if this request is for a frame and has a parent. * * @since Chrome 106 */ parentDocumentId?: string; /** * The ID of the tab in which the request takes place. Set to -1 if the request isn't related to a tab. */ tabId: number; /** * The resource type of the request. */ type: ResourceType; } /** * @since Chrome 103 */ export interface TestMatchRequestDetails { /** * The URL of the hypothetical request. */ url: string; /** * The initiator URL (if any) for the hypothetical request. */ initiator?: string; /** * Standard HTTP method of the hypothetical request. Defaults to "get" for HTTP requests and is ignored for non-HTTP requests. */ method?: RequestMethod; /** * The resource type of the hypothetical request. */ type: ResourceType; /** * The ID of the tab in which the hypothetical request takes place. Does not need to correspond to a real tab ID. Default is -1, meaning that the request isn't related to a tab. */ tabId?: number; /** * The associated top-level frame URL (if any) for the request. * * @since Pending */ topUrl?: string; /** * The headers provided by a hypothetical response if the request does not get blocked or redirected before it is sent. Represented as an object which maps a header name to a list of string values. If not specified, the hypothetical response would return empty response headers, which can match rules which match on the non-existence of headers. E.g. `{"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}` * * @since Chrome 129 */ responseHeaders?: {[name: string]: any}; } export interface MatchedRuleInfoDebug { rule: MatchedRule; /** * Details about the request for which the rule was matched. */ request: RequestDetails; } /** * @since Chrome 87 */ export interface RegexOptions { /** * The regular expresson to check. */ regex: string; /** * Whether the `regex` specified is case sensitive. Default is true. */ isCaseSensitive?: boolean; /** * Whether the `regex` specified requires capturing. Capturing is only required for redirect rules which specify a `regexSubstition` action. The default is false. */ requireCapturing?: boolean; } /** * @since Chrome 87 */ export interface IsRegexSupportedResult { isSupported: boolean; /** * Specifies the reason why the regular expression is not supported. Only provided if `isSupported` is false. */ reason?: UnsupportedRegexReason; } /** * @since Chrome 103 */ export interface TestMatchOutcomeResult { /** * The rules (if any) that match the hypothetical request. */ matchedRules: MatchedRule[]; } /** * @since Chrome 87 */ export interface UpdateRuleOptions { /** * IDs of the rules to remove. Any invalid IDs will be ignored. */ removeRuleIds?: number[]; /** * Rules to add. */ addRules?: Rule[]; } /** * @since Chrome 87 */ export interface UpdateRulesetOptions { /** * The set of ids corresponding to a static {@link Ruleset} that should be disabled. */ disableRulesetIds?: string[]; /** * The set of ids corresponding to a static {@link Ruleset} that should be enabled. */ enableRulesetIds?: string[]; } /** * @since Chrome 111 */ export interface UpdateStaticRulesOptions { /** * The id corresponding to a static {@link Ruleset}. */ rulesetId: string; /** * Set of ids corresponding to rules in the {@link Ruleset} to disable. */ disableRuleIds?: number[]; /** * Set of ids corresponding to rules in the {@link Ruleset} to enable. */ enableRuleIds?: number[]; } /** * @since Chrome 111 */ export interface GetDisabledRuleIdsOptions { /** * The id corresponding to a static {@link Ruleset}. */ rulesetId: string; } /** * @since Chrome 89 */ export interface TabActionCountUpdate { /** * The tab for which to update the action count. */ tabId: number; /** * The amount to increment the tab's action count by. Negative values will decrement the count. */ increment: number; } /** * @since Chrome 88 */ export interface ExtensionActionOptions { /** * Whether to automatically display the action count for a page as the extension's badge text. This preference is persisted across sessions. */ displayActionCountAsBadgeText?: boolean; /** * Details of how the tab's action count should be adjusted. * * @since Chrome 89 */ tabUpdate?: TabActionCountUpdate; } /** * The minimum number of static rules guaranteed to an extension across its enabled static rulesets. Any rules above this limit will count towards the [global static rule limit](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#global-static-rule-limit). * * @since Chrome 89 */ export const GUARANTEED_MINIMUM_STATIC_RULES: 30000; /** * The maximum number of dynamic rules that an extension can add. */ export const MAX_NUMBER_OF_DYNAMIC_RULES: 30000; /** * The maximum number of "unsafe" dynamic rules that an extension can add. * * @since Chrome 120 */ export const MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES: 5000; /** * The maximum number of session scoped rules that an extension can add. * * @since Chrome 120 */ export const MAX_NUMBER_OF_SESSION_RULES: 5000; /** * The maximum number of "unsafe" session scoped rules that an extension can add. * * @since Chrome 120 */ export const MAX_NUMBER_OF_UNSAFE_SESSION_RULES: 5000; /** * Time interval within which `MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules` calls can be made, specified in minutes. Additional calls will fail immediately and set {@link runtime.lastError}. Note: `getMatchedRules` calls associated with a user gesture are exempt from the quota. */ export const GETMATCHEDRULES_QUOTA_INTERVAL: 10; /** * The number of times `getMatchedRules` can be called within a period of `GETMATCHEDRULES_QUOTA_INTERVAL`. */ export const MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL: 20; /** * The maximum number of regular expression rules that an extension can add. This limit is evaluated separately for the set of dynamic rules and those specified in the rule resources file. */ export const MAX_NUMBER_OF_REGEX_RULES: 1000; /** * The maximum number of static `Rulesets` an extension can specify as part of the `"rule_resources"` manifest key. */ export const MAX_NUMBER_OF_STATIC_RULESETS: 100; /** * The maximum number of static `Rulesets` an extension can enable at any one time. * * @since Chrome 94 */ export const MAX_NUMBER_OF_ENABLED_STATIC_RULESETS: 50; /** * Ruleset ID for the dynamic rules added by the extension. */ export const DYNAMIC_RULESET_ID: "_dynamic"; /** * Ruleset ID for the session-scoped rules added by the extension. * * @since Chrome 90 */ export const SESSION_RULESET_ID: "_session"; /** * Fired when a rule is matched with a request. Only available for unpacked extensions with the `"declarativeNetRequestFeedback"` permission as this is intended to be used for debugging purposes only. * * @chrome-permission declarativeNetRequestFeedback */ export const onRuleMatchedDebug: events.Event<( /** * @since Chrome 85 */ info: MatchedRuleInfoDebug, ) => void>; /** * Modifies the current set of dynamic rules for the extension. The rules with IDs listed in `options.removeRuleIds` are first removed, and then the rules given in `options.addRules` are added. Notes: * * * This update happens as a single atomic operation: either all specified rules are added and removed, or an error is returned. * * These rules are persisted across browser sessions and across extension updates. * * Static rules specified as part of the extension package can not be removed using this function. * * {@link MAX_NUMBER_OF_DYNAMIC_RULES} is the maximum number of dynamic rules an extension can add. The number of [unsafe rules](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#safe_rules) must not exceed {@link MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES}. * * @chrome-returns-extra since Chrome 91 * @returns Promise that resolves once the update is complete. In case of an error, the promise will be rejected and no change will be made to the rule set. This can happen for multiple reasons, such as invalid rule format, duplicate rule ID, rule count limit exceeded, internal errors, and others. */ export function updateDynamicRules( /** * @since Chrome 87 */ options: UpdateRuleOptions, ): Promise; /** * Modifies the current set of dynamic rules for the extension. The rules with IDs listed in `options.removeRuleIds` are first removed, and then the rules given in `options.addRules` are added. Notes: * * * This update happens as a single atomic operation: either all specified rules are added and removed, or an error is returned. * * These rules are persisted across browser sessions and across extension updates. * * Static rules specified as part of the extension package can not be removed using this function. * * {@link MAX_NUMBER_OF_DYNAMIC_RULES} is the maximum number of dynamic rules an extension can add. The number of [unsafe rules](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#safe_rules) must not exceed {@link MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES}. */ export function updateDynamicRules( /** * @since Chrome 87 */ options: UpdateRuleOptions, callback?: () => void, ): void; /** * Returns the current set of dynamic rules for the extension. Callers can optionally filter the list of fetched rules by specifying a `filter`. * * @chrome-returns-extra since Chrome 91 * @param filter An object to filter the list of fetched rules. * @returns Promise that resolves with the set of dynamic rules. The Promise may be rejected in case of transient internal errors. */ export function getDynamicRules( /** * @since Chrome 111 */ filter?: GetRulesFilter, ): Promise; /** * Returns the current set of dynamic rules for the extension. Callers can optionally filter the list of fetched rules by specifying a `filter`. * * @param filter An object to filter the list of fetched rules. */ export function getDynamicRules( /** * @since Chrome 111 */ filter?: GetRulesFilter, callback?: ( rules: Rule[], ) => void, ): void; /** * Modifies the current set of session scoped rules for the extension. The rules with IDs listed in `options.removeRuleIds` are first removed, and then the rules given in `options.addRules` are added. Notes: * * * This update happens as a single atomic operation: either all specified rules are added and removed, or an error is returned. * * These rules are not persisted across sessions and are backed in memory. * * {@link MAX_NUMBER_OF_SESSION_RULES} is the maximum number of session rules an extension can add. * * @chrome-returns-extra since Chrome 91 * @returns Promise that resolves once the update is complete. In case of an error, the promise will be rejected and no change will be made to the rule set. This can happen for multiple reasons, such as invalid rule format, duplicate rule ID, rule count limit exceeded, and others. * @since Chrome 90 */ export function updateSessionRules( options: UpdateRuleOptions, ): Promise; /** * Modifies the current set of session scoped rules for the extension. The rules with IDs listed in `options.removeRuleIds` are first removed, and then the rules given in `options.addRules` are added. Notes: * * * This update happens as a single atomic operation: either all specified rules are added and removed, or an error is returned. * * These rules are not persisted across sessions and are backed in memory. * * {@link MAX_NUMBER_OF_SESSION_RULES} is the maximum number of session rules an extension can add. * * @since Chrome 90 */ export function updateSessionRules( options: UpdateRuleOptions, callback?: () => void, ): void; /** * Returns the current set of session scoped rules for the extension. Callers can optionally filter the list of fetched rules by specifying a `filter`. * * @chrome-returns-extra since Chrome 91 * @param filter An object to filter the list of fetched rules. * @returns Promise that resolves with the set of session scoped rules. * @since Chrome 90 */ export function getSessionRules( /** * @since Chrome 111 */ filter?: GetRulesFilter, ): Promise; /** * Returns the current set of session scoped rules for the extension. Callers can optionally filter the list of fetched rules by specifying a `filter`. * * @param filter An object to filter the list of fetched rules. * @since Chrome 90 */ export function getSessionRules( /** * @since Chrome 111 */ filter?: GetRulesFilter, callback?: ( rules: Rule[], ) => void, ): void; /** * Updates the set of enabled static rulesets for the extension. The rulesets with IDs listed in `options.disableRulesetIds` are first removed, and then the rulesets listed in `options.enableRulesetIds` are added. * Note that the set of enabled static rulesets is persisted across sessions but not across extension updates, i.e. the `rule_resources` manifest key will determine the set of enabled static rulesets on each extension update. * * @chrome-returns-extra since Chrome 91 * @returns Promise that resolves once the update is complete. In case of an error, the promise will be rejected and no change will be made to the set of enabled rulesets. This can happen for multiple reasons, such as invalid ruleset IDs, rule count limit exceeded, or internal errors. */ export function updateEnabledRulesets( /** * @since Chrome 87 */ options: UpdateRulesetOptions, ): Promise; /** * Updates the set of enabled static rulesets for the extension. The rulesets with IDs listed in `options.disableRulesetIds` are first removed, and then the rulesets listed in `options.enableRulesetIds` are added. * Note that the set of enabled static rulesets is persisted across sessions but not across extension updates, i.e. the `rule_resources` manifest key will determine the set of enabled static rulesets on each extension update. */ export function updateEnabledRulesets( /** * @since Chrome 87 */ options: UpdateRulesetOptions, callback?: () => void, ): void; /** * Returns the ids for the current set of enabled static rulesets. * * @chrome-returns-extra since Chrome 91 * @returns Promise that resolves with a list of ids, where each id corresponds to an enabled static {@link Ruleset}. */ export function getEnabledRulesets(): Promise; /** * Returns the ids for the current set of enabled static rulesets. */ export function getEnabledRulesets( callback?: ( rulesetIds: string[], ) => void, ): void; /** * Disables and enables individual static rules in a {@link Ruleset}. Changes to rules belonging to a disabled {@link Ruleset} will take effect the next time that it becomes enabled. * * @returns Promise that resolves when the update is complete. In case of an error, the promise will be rejected and no change will be made to the enabled static rules. * @since Chrome 111 */ export function updateStaticRules( options: UpdateStaticRulesOptions, ): Promise; /** * Disables and enables individual static rules in a {@link Ruleset}. Changes to rules belonging to a disabled {@link Ruleset} will take effect the next time that it becomes enabled. * * @since Chrome 111 */ export function updateStaticRules( options: UpdateStaticRulesOptions, callback?: () => void, ): void; /** * Returns the list of static rules in the given {@link Ruleset} that are currently disabled. * * @param options Specifies the ruleset to query. * @returns Promise that resolves with a list of ids that correspond to the disabled rules in that ruleset. * @since Chrome 111 */ export function getDisabledRuleIds( options: GetDisabledRuleIdsOptions, ): Promise; /** * Returns the list of static rules in the given {@link Ruleset} that are currently disabled. * * @param options Specifies the ruleset to query. * @since Chrome 111 */ export function getDisabledRuleIds( options: GetDisabledRuleIdsOptions, callback?: ( disabledRuleIds: number[], ) => void, ): void; /** * Returns all rules matched for the extension. Callers can optionally filter the list of matched rules by specifying a `filter`. This method is only available to extensions with the `"declarativeNetRequestFeedback"` permission or having the `"activeTab"` permission granted for the `tabId` specified in `filter`. Note: Rules not associated with an active document that were matched more than five minutes ago will not be returned. * * @chrome-returns-extra since Chrome 91 * @param filter An object to filter the list of matched rules. * @returns Promise that resolves once the list of matched rules has been fetched. In case of an error, the Promise will be rejected. This can happen for multiple reasons, such as insufficient permissions, or exceeding the quota. */ export function getMatchedRules( filter?: MatchedRulesFilter, ): Promise; /** * Returns all rules matched for the extension. Callers can optionally filter the list of matched rules by specifying a `filter`. This method is only available to extensions with the `"declarativeNetRequestFeedback"` permission or having the `"activeTab"` permission granted for the `tabId` specified in `filter`. Note: Rules not associated with an active document that were matched more than five minutes ago will not be returned. * * @param filter An object to filter the list of matched rules. */ export function getMatchedRules( filter?: MatchedRulesFilter, callback?: ( details: RulesMatchedDetails, ) => void, ): void; /** * Configures if the action count for tabs should be displayed as the extension action's badge text and provides a way for that action count to be incremented. * * @chrome-returns-extra since Chrome 91 * @since Chrome 88 */ export function setExtensionActionOptions( options: ExtensionActionOptions, ): Promise; /** * Configures if the action count for tabs should be displayed as the extension action's badge text and provides a way for that action count to be incremented. * * @since Chrome 88 */ export function setExtensionActionOptions( options: ExtensionActionOptions, /** * @since Chrome 89 */ callback?: () => void, ): void; /** * Checks if the given regular expression will be supported as a `regexFilter` rule condition. * * @chrome-returns-extra since Chrome 91 * @param regexOptions The regular expression to check. * @returns Promise that resolves with details consisting of whether the regular expression is supported and the reason if not. * @since Chrome 87 */ export function isRegexSupported( regexOptions: RegexOptions, ): Promise; /** * Checks if the given regular expression will be supported as a `regexFilter` rule condition. * * @param regexOptions The regular expression to check. * @since Chrome 87 */ export function isRegexSupported( regexOptions: RegexOptions, callback?: ( result: IsRegexSupportedResult, ) => void, ): void; /** * Returns the number of static rules an extension can enable before the [global static rule limit](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#global-static-rule-limit) is reached. * * @chrome-returns-extra since Chrome 91 * @since Chrome 89 */ export function getAvailableStaticRuleCount(): Promise; /** * Returns the number of static rules an extension can enable before the [global static rule limit](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#global-static-rule-limit) is reached. * * @since Chrome 89 */ export function getAvailableStaticRuleCount( callback?: ( count: number, ) => void, ): void; /** * Checks if any of the extension's declarativeNetRequest rules would match a hypothetical request. Note: Only available for unpacked extensions as this is only intended to be used during extension development. * * @returns Promise that resolves with the details of matched rules. * @since Chrome 103 */ export function testMatchOutcome( request: TestMatchRequestDetails, ): Promise; /** * Checks if any of the extension's declarativeNetRequest rules would match a hypothetical request. Note: Only available for unpacked extensions as this is only intended to be used during extension development. * * @since Chrome 103 */ export function testMatchOutcome( request: TestMatchRequestDetails, callback?: ( result: TestMatchOutcomeResult, ) => void, ): void; } /** * _**Note:** this API is deprecated. Check out the {@link declarativeNetRequest} API instead._ Use the `chrome.declarativeWebRequest` API to intercept, block, or modify requests in-flight. It is significantly faster than the {@link webRequest `chrome.webRequest` API} because you can register rules that are evaluated in the browser rather than the JavaScript engine, which reduces roundtrip latencies and allows higher efficiency. * * @beta * @chrome-permission declarativeWebRequest * @chrome-channel beta * @chrome-max-manifest MV2 * @chrome-platform chromeos * @chrome-platform linux * @chrome-platform mac * @chrome-platform win */ export namespace declarativeWebRequest { export type Stage = "onBeforeRequest" | "onBeforeSendHeaders" | "onHeadersReceived" | "onAuthRequired"; /** * Filters request headers for various criteria. Multiple criteria are evaluated as a conjunction. */ export interface HeaderFilter { /** * Matches if the header name starts with the specified string. */ namePrefix?: string; /** * Matches if the header name ends with the specified string. */ nameSuffix?: string; /** * Matches if the header name contains all of the specified strings. */ nameContains?: string[] | string; /** * Matches if the header name is equal to the specified string. */ nameEquals?: string; /** * Matches if the header value starts with the specified string. */ valuePrefix?: string; /** * Matches if the header value ends with the specified string. */ valueSuffix?: string; /** * Matches if the header value contains all of the specified strings. */ valueContains?: string[] | string; /** * Matches if the header value is equal to the specified string. */ valueEquals?: string; } /** * Matches network events by various criteria. */ export class RequestMatcher { constructor(arg: RequestMatcher); /** * Matches if the conditions of the UrlFilter are fulfilled for the URL of the request. */ url?: events.UrlFilter; /** * Matches if the conditions of the UrlFilter are fulfilled for the 'first party' URL of the request. The 'first party' URL of a request, when present, can be different from the request's target URL, and describes what is considered 'first party' for the sake of third-party checks for cookies. * * @deprecated Ignored since release 82. */ firstPartyForCookiesUrl?: events.UrlFilter; /** * Matches if the request type of a request is contained in the list. Requests that cannot match any of the types will be filtered out. */ resourceType?: webRequest.ResourceType[]; /** * Matches if the MIME media type of a response (from the HTTP Content-Type header) is contained in the list. */ contentType?: string[]; /** * Matches if the MIME media type of a response (from the HTTP Content-Type header) is _not_ contained in the list. */ excludeContentType?: string[]; /** * Matches if some of the request headers is matched by one of the HeaderFilters. */ requestHeaders?: HeaderFilter[]; /** * Matches if none of the request headers is matched by any of the HeaderFilters. */ excludeRequestHeaders?: HeaderFilter[]; /** * Matches if some of the response headers is matched by one of the HeaderFilters. */ responseHeaders?: HeaderFilter[]; /** * Matches if none of the response headers is matched by any of the HeaderFilters. */ excludeResponseHeaders?: HeaderFilter[]; /** * If set to true, matches requests that are subject to third-party cookie policies. If set to false, matches all other requests. * * @deprecated Ignored since release 87. */ thirdPartyForCookies?: boolean; /** * Contains a list of strings describing stages. Allowed values are 'onBeforeRequest', 'onBeforeSendHeaders', 'onHeadersReceived', 'onAuthRequired'. If this attribute is present, then it limits the applicable stages to those listed. Note that the whole condition is only applicable in stages compatible with all attributes. */ stages?: Stage[]; } /** * Declarative event action that cancels a network request. */ export class CancelRequest { constructor(arg: CancelRequest); } /** * Declarative event action that redirects a network request. */ export class RedirectRequest { constructor(arg: RedirectRequest); /** * Destination to where the request is redirected. */ redirectUrl: string; } /** * Declarative event action that redirects a network request to a transparent image. */ export class RedirectToTransparentImage { constructor(arg: RedirectToTransparentImage); } /** * Declarative event action that redirects a network request to an empty document. */ export class RedirectToEmptyDocument { constructor(arg: RedirectToEmptyDocument); } /** * Redirects a request by applying a regular expression on the URL. The regular expressions use the [RE2 syntax](https://github.com/google/re2/blob/master/doc/syntax.txt). */ export class RedirectByRegEx { constructor(arg: RedirectByRegEx); /** * A match pattern that may contain capture groups. Capture groups are referenced in the Perl syntax ($1, $2, ...) instead of the RE2 syntax (\\1, \\2, ...) in order to be closer to JavaScript Regular Expressions. */ from: string; /** * Destination pattern. */ to: string; } /** * Sets the request header of the specified name to the specified value. If a header with the specified name did not exist before, a new one is created. Header name comparison is always case-insensitive. Each request header name occurs only once in each request. */ export class SetRequestHeader { constructor(arg: SetRequestHeader); /** * HTTP request header name. */ name: string; /** * HTTP request header value. */ value: string; } /** * Removes the request header of the specified name. Do not use SetRequestHeader and RemoveRequestHeader with the same header name on the same request. Each request header name occurs only once in each request. */ export class RemoveRequestHeader { constructor(arg: RemoveRequestHeader); /** * HTTP request header name (case-insensitive). */ name: string; } /** * Adds the response header to the response of this web request. As multiple response headers may share the same name, you need to first remove and then add a new response header in order to replace one. */ export class AddResponseHeader { constructor(arg: AddResponseHeader); /** * HTTP response header name. */ name: string; /** * HTTP response header value. */ value: string; } /** * Removes all response headers of the specified names and values. */ export class RemoveResponseHeader { constructor(arg: RemoveResponseHeader); /** * HTTP request header name (case-insensitive). */ name: string; /** * HTTP request header value (case-insensitive). */ value?: string; } /** * Masks all rules that match the specified criteria. */ export class IgnoreRules { constructor(arg: IgnoreRules); /** * If set, rules with a lower priority than the specified value are ignored. This boundary is not persisted, it affects only rules and their actions of the same network request stage. */ lowerPriorityThan?: number; /** * If set, rules with the specified tag are ignored. This ignoring is not persisted, it affects only rules and their actions of the same network request stage. Note that rules are executed in descending order of their priorities. This action affects rules of lower priority than the current rule. Rules with the same priority may or may not be ignored. */ hasTag?: string; } /** * Triggers the {@link declarativeWebRequest.onMessage} event. */ export class SendMessageToExtension { constructor(arg: SendMessageToExtension); /** * The value that will be passed in the `message` attribute of the dictionary that is passed to the event handler. */ message: string; } /** * A filter or specification of a cookie in HTTP Requests. */ export interface RequestCookie { /** * Name of a cookie. */ name?: string; /** * Value of a cookie, may be padded in double-quotes. */ value?: string; } /** * A specification of a cookie in HTTP Responses. */ export interface ResponseCookie { /** * Name of a cookie. */ name?: string; /** * Value of a cookie, may be padded in double-quotes. */ value?: string; /** * Value of the Expires cookie attribute. */ expires?: string; /** * Value of the Max-Age cookie attribute */ maxAge?: number; /** * Value of the Domain cookie attribute. */ domain?: string; /** * Value of the Path cookie attribute. */ path?: string; /** * Existence of the Secure cookie attribute. */ secure?: string; /** * Existence of the HttpOnly cookie attribute. */ httpOnly?: string; } /** * A filter of a cookie in HTTP Responses. */ export interface FilterResponseCookie { /** * Name of a cookie. */ name?: string; /** * Value of a cookie, may be padded in double-quotes. */ value?: string; /** * Value of the Expires cookie attribute. */ expires?: string; /** * Value of the Max-Age cookie attribute */ maxAge?: number; /** * Value of the Domain cookie attribute. */ domain?: string; /** * Value of the Path cookie attribute. */ path?: string; /** * Existence of the Secure cookie attribute. */ secure?: string; /** * Existence of the HttpOnly cookie attribute. */ httpOnly?: string; /** * Inclusive upper bound on the cookie lifetime (specified in seconds after current time). Only cookies whose expiration date-time is in the interval \[now, now + ageUpperBound\] fulfill this criterion. Session cookies and cookies whose expiration date-time is in the past do not meet the criterion of this filter. The cookie lifetime is calculated from either 'max-age' or 'expires' cookie attributes. If both are specified, 'max-age' is used to calculate the cookie lifetime. */ ageUpperBound?: number; /** * Inclusive lower bound on the cookie lifetime (specified in seconds after current time). Only cookies whose expiration date-time is set to 'now + ageLowerBound' or later fulfill this criterion. Session cookies do not meet the criterion of this filter. The cookie lifetime is calculated from either 'max-age' or 'expires' cookie attributes. If both are specified, 'max-age' is used to calculate the cookie lifetime. */ ageLowerBound?: number; /** * Filters session cookies. Session cookies have no lifetime specified in any of 'max-age' or 'expires' attributes. */ sessionCookie?: boolean; } /** * Adds a cookie to the request or overrides a cookie, in case another cookie of the same name exists already. Note that it is preferred to use the Cookies API because this is computationally less expensive. */ export class AddRequestCookie { constructor(arg: AddRequestCookie); /** * Cookie to be added to the request. No field may be undefined. */ cookie: declarativeWebRequest.RequestCookie; } /** * Adds a cookie to the response or overrides a cookie, in case another cookie of the same name exists already. Note that it is preferred to use the Cookies API because this is computationally less expensive. */ export class AddResponseCookie { constructor(arg: AddResponseCookie); /** * Cookie to be added to the response. The name and value need to be specified. */ cookie: declarativeWebRequest.ResponseCookie; } /** * Edits one or more cookies of request. Note that it is preferred to use the Cookies API because this is computationally less expensive. */ export class EditRequestCookie { constructor(arg: EditRequestCookie); /** * Filter for cookies that will be modified. All empty entries are ignored. */ filter: declarativeWebRequest.RequestCookie; /** * Attributes that shall be overridden in cookies that machted the filter. Attributes that are set to an empty string are removed. */ modification: declarativeWebRequest.RequestCookie; } /** * Edits one or more cookies of response. Note that it is preferred to use the Cookies API because this is computationally less expensive. */ export class EditResponseCookie { constructor(arg: EditResponseCookie); /** * Filter for cookies that will be modified. All empty entries are ignored. */ filter: declarativeWebRequest.FilterResponseCookie; /** * Attributes that shall be overridden in cookies that machted the filter. Attributes that are set to an empty string are removed. */ modification: declarativeWebRequest.ResponseCookie; } /** * Removes one or more cookies of request. Note that it is preferred to use the Cookies API because this is computationally less expensive. */ export class RemoveRequestCookie { constructor(arg: RemoveRequestCookie); /** * Filter for cookies that will be removed. All empty entries are ignored. */ filter: declarativeWebRequest.RequestCookie; } /** * Removes one or more cookies of response. Note that it is preferred to use the Cookies API because this is computationally less expensive. */ export class RemoveResponseCookie { constructor(arg: RemoveResponseCookie); /** * Filter for cookies that will be removed. All empty entries are ignored. */ filter: declarativeWebRequest.FilterResponseCookie; } export const onRequest: events.Event; /** * Fired when a message is sent via {@link declarativeWebRequest.SendMessageToExtension} from an action of the declarative web request API. */ export const onMessage: events.Event<( details: { /** * The message sent by the calling script. */ message: string, /** * The stage of the network request during which the event was triggered. */ stage: Stage, /** * The ID of the request. Request IDs are unique within a browser session. As a result, they could be used to relate different events of the same request. */ requestId: string, url: string, /** * Standard HTTP method. */ method: string, /** * The value 0 indicates that the request happens in the main frame; a positive value indicates the ID of a subframe in which the request happens. If the document of a (sub-)frame is loaded (`type` is `main_frame` or `sub_frame`), `frameId` indicates the ID of this frame, not the ID of the outer frame. Frame IDs are unique within a tab. */ frameId: number, /** * ID of frame that wraps the frame which sent the request. Set to -1 if no parent frame exists. */ parentFrameId: number, /** * A UUID of the document that made the request. */ documentId?: string, /** * A UUID of the parent document owning this frame. This is not set if there is no parent. */ parentDocumentId?: string, /** * The lifecycle the document is in. */ documentLifecycle: extensionTypes.DocumentLifecycle, /** * The type of frame the navigation occurred in. */ frameType: extensionTypes.FrameType, /** * The ID of the tab in which the request takes place. Set to -1 if the request isn't related to a tab. */ tabId: number, /** * How the requested resource will be used. */ type: webRequest.ResourceType, /** * The time when this signal is triggered, in milliseconds since the epoch. */ timeStamp: number, }, ) => void>; } /** * The Desktop Capture API captures the content of the screen, individual windows, or individual tabs. * * @chrome-permission desktopCapture */ export namespace desktopCapture { /** * Enum used to define set of desktop media sources used in chooseDesktopMedia(). */ export type DesktopCaptureSourceType = "screen" | "window" | "tab" | "audio"; /** * Mirrors [SystemAudioPreferenceEnum](https://w3c.github.io/mediacapture-screen-share/#dom-systemaudiopreferenceenum). * * @since Chrome 105 */ export type SystemAudioPreferenceEnum = "include" | "exclude"; /** * Mirrors [WindowAudioPreferenceEnum](https://w3c.github.io/mediacapture-screen-share/#dom-windowaudiopreferenceenum). * * @since Chrome 140 */ export type WindowAudioPreferenceEnum = "system" | "window" | "exclude"; /** * Mirrors [SelfCapturePreferenceEnum](https://w3c.github.io/mediacapture-screen-share/#dom-selfcapturepreferenceenum). * * @since Chrome 107 */ export type SelfCapturePreferenceEnum = "include" | "exclude"; /** * Shows desktop media picker UI with the specified set of sources. * * @param sources Set of sources that should be shown to the user. The sources order in the set decides the tab order in the picker. * @param targetTab Optional tab for which the stream is created. If not specified then the resulting stream can be used only by the calling extension. The stream can only be used by frames in the given tab whose security origin matches `tab.url`. The tab's origin must be a secure origin, e.g. HTTPS. * @returns An id that can be passed to cancelChooseDesktopMedia() in case the prompt need to be canceled. */ export function chooseDesktopMedia( sources: DesktopCaptureSourceType[], targetTab: tabs.Tab, /** * @param streamId An opaque string that can be passed to `getUserMedia()` API to generate media stream that corresponds to the source selected by the user. If user didn't select any source (i.e. canceled the prompt) then the callback is called with an empty `streamId`. The created `streamId` can be used only once and expires after a few seconds when it is not used. * @param options Contains properties that describe the stream. */ callback: ( streamId: string, /** * @since Chrome 57 */ options: { /** * True if "audio" is included in parameter sources, and the end user does not uncheck the "Share audio" checkbox. Otherwise false, and in this case, one should not ask for audio stream through getUserMedia call. */ canRequestAudioTrack: boolean, }, ) => void, ): number; /** * Shows desktop media picker UI with the specified set of sources. * * @param sources Set of sources that should be shown to the user. The sources order in the set decides the tab order in the picker. * @returns An id that can be passed to cancelChooseDesktopMedia() in case the prompt need to be canceled. */ export function chooseDesktopMedia( sources: DesktopCaptureSourceType[], /** * @param streamId An opaque string that can be passed to `getUserMedia()` API to generate media stream that corresponds to the source selected by the user. If user didn't select any source (i.e. canceled the prompt) then the callback is called with an empty `streamId`. The created `streamId` can be used only once and expires after a few seconds when it is not used. * @param options Contains properties that describe the stream. */ callback: ( streamId: string, /** * @since Chrome 57 */ options: { /** * True if "audio" is included in parameter sources, and the end user does not uncheck the "Share audio" checkbox. Otherwise false, and in this case, one should not ask for audio stream through getUserMedia call. */ canRequestAudioTrack: boolean, }, ) => void, ): number; /** * Hides desktop media picker dialog shown by chooseDesktopMedia(). * * @param desktopMediaRequestId Id returned by chooseDesktopMedia() */ export function cancelChooseDesktopMedia( desktopMediaRequestId: number, ): void; } /** * Use the `chrome.devtools.inspectedWindow` API to interact with the inspected window: obtain the tab ID for the inspected page, evaluate the code in the context of the inspected window, reload the page, or obtain the list of resources within the page. * * @chrome-manifest devtools_page */ export namespace devtools.inspectedWindow { /** * A resource within the inspected page, such as a document, a script, or an image. */ export interface Resource { /** * The URL of the resource. */ url: string; /** * Gets the content of the resource. * * @param callback A function that receives resource content when the request completes. */ getContent( /** * @param content Content of the resource (potentially encoded). * @param encoding Empty if the content is not encoded, encoding name otherwise. Currently, only base64 is supported. */ callback: ( content: string, encoding: string, ) => void, ): void; /** * Sets the content of the resource. * * @param content New content of the resource. Only resources with the text type are currently supported. * @param commit True if the user has finished editing the resource, and the new content of the resource should be persisted; false if this is a minor change sent in progress of the user editing the resource. * @param callback A function called upon request completion. */ setContent( content: string, commit: boolean, /** * @param error Set to undefined if the resource content was set successfully; describes error otherwise. */ callback?: ( error?: {[name: string]: any}, ) => void, ): void; } /** * The ID of the tab being inspected. This ID may be used with chrome.tabs.\* API. */ export const tabId: number; /** * Fired when a new resource is added to the inspected page. */ export const onResourceAdded: events.Event<( resource: Resource, ) => void>; /** * Fired when a new revision of the resource is committed (e.g. user saves an edited version of the resource in the Developer Tools). */ export const onResourceContentCommitted: events.Event<( resource: Resource, content: string, ) => void>; export {_eval as eval}; /** * Evaluates a JavaScript expression in the context of the main frame of the inspected page. The expression must evaluate to a JSON-compliant object, otherwise an exception is thrown. The eval function can report either a DevTools-side error or a JavaScript exception that occurs during evaluation. In either case, the `result` parameter of the callback is `undefined`. In the case of a DevTools-side error, the `isException` parameter is non-null and has `isError` set to true and `code` set to an error code. In the case of a JavaScript error, `isException` is set to true and `value` is set to the string value of thrown object. * * @param expression An expression to evaluate. * @param options The options parameter can contain one or more options. * @param callback A function called when evaluation completes. */ function _eval( expression: string, options?: { /** * If specified, the expression is evaluated on the iframe whose URL matches the one specified. By default, the expression is evaluated in the top frame of the inspected page. */ frameURL?: string, /** * Evaluate the expression in the context of the content script of the calling extension, provided that the content script is already injected into the inspected page. If not, the expression is not evaluated and the callback is invoked with the exception parameter set to an object that has the `isError` field set to true and the `code` field set to `E_NOTFOUND`. */ useContentScriptContext?: boolean, /** * Evaluate the expression in the context of a content script of an extension that matches the specified origin. If given, scriptExecutionContext overrides the 'true' setting on useContentScriptContext. * * @since Chrome 107 */ scriptExecutionContext?: string, }, /** * @param result The result of evaluation. * @param exceptionInfo An object providing details if an exception occurred while evaluating the expression. */ callback?: ( result: {[name: string]: any}, exceptionInfo: { /** * Set if the error occurred on the DevTools side before the expression is evaluated. */ isError: boolean, /** * Set if the error occurred on the DevTools side before the expression is evaluated. */ code: string, /** * Set if the error occurred on the DevTools side before the expression is evaluated. */ description: string, /** * Set if the error occurred on the DevTools side before the expression is evaluated, contains the array of the values that may be substituted into the description string to provide more information about the cause of the error. */ details: any[], /** * Set if the evaluated code produces an unhandled exception. */ isException: boolean, /** * Set if the evaluated code produces an unhandled exception. */ value: string, }, ) => void, ): void; /** * Reloads the inspected page. */ export function reload( reloadOptions?: { /** * When true, the loader will bypass the cache for all inspected page resources loaded before the `load` event is fired. The effect is similar to pressing Ctrl+Shift+R in the inspected window or within the Developer Tools window. */ ignoreCache?: boolean, /** * If specified, the string will override the value of the `User-Agent` HTTP header that's sent while loading the resources of the inspected page. The string will also override the value of the `navigator.userAgent` property that's returned to any scripts that are running within the inspected page. */ userAgent?: string, /** * If specified, the script will be injected into every frame of the inspected page immediately upon load, before any of the frame's scripts. The script will not be injected after subsequent reloads—for example, if the user presses Ctrl+R. */ injectedScript?: string, }, ): void; /** * Retrieves the list of resources from the inspected page. * * @param callback A function that receives the list of resources when the request completes. */ export function getResources( /** * @param resources The resources within the page. */ callback: ( resources: Resource[], ) => void, ): void; } /** * Use the `chrome.devtools.network` API to retrieve the information about network requests displayed by the Developer Tools in the Network panel. * * @chrome-manifest devtools_page */ export namespace devtools.network { /** * Represents a network request for a document resource (script, image and so on). See HAR Specification for reference. */ export interface Request { /** * Returns content of the response body. * * @param callback A function that receives the response body when the request completes. */ getContent( /** * @param content Content of the response body (potentially encoded). * @param encoding Empty if content is not encoded, encoding name otherwise. Currently, only base64 is supported. */ callback: ( content: string, encoding: string, ) => void, ): void; } /** * Fired when a network request is finished and all request data are available. */ export const onRequestFinished: events.Event<( request: Request, ) => void>; /** * Fired when the inspected window navigates to a new page. */ export const onNavigated: events.Event<( url: string, ) => void>; /** * Returns HAR log that contains all known network requests. * * @param callback A function that receives the HAR log when the request completes. */ export function getHAR( /** * @param harLog A HAR log. See HAR specification for details. */ callback: ( harLog: {[name: string]: any}, ) => void, ): void; } /** * Use the `chrome.devtools.panels` API to integrate your extension into Developer Tools window UI: create your own panels, access existing panels, and add sidebars. * * @chrome-manifest devtools_page */ export namespace devtools.panels { /** * Represents the Elements panel. */ export interface ElementsPanel { /** * Fired when an object is selected in the panel. */ onSelectionChanged: events.Event<() => void>; /** * Creates a pane within panel's sidebar. * * @param title Text that is displayed in sidebar caption. * @param callback A callback invoked when the sidebar is created. */ createSidebarPane( title: string, /** * @param result An ExtensionSidebarPane object for created sidebar pane. */ callback?: ( result: ExtensionSidebarPane, ) => void, ): void; } /** * Represents the Sources panel. */ export interface SourcesPanel { /** * Fired when an object is selected in the panel. */ onSelectionChanged: events.Event<() => void>; /** * Creates a pane within panel's sidebar. * * @param title Text that is displayed in sidebar caption. * @param callback A callback invoked when the sidebar is created. */ createSidebarPane( title: string, /** * @param result An ExtensionSidebarPane object for created sidebar pane. */ callback?: ( result: ExtensionSidebarPane, ) => void, ): void; } /** * Represents a panel created by an extension. */ export interface ExtensionPanel { /** * Fired upon a search action (start of a new search, search result navigation, or search being canceled). */ onSearch: events.Event<( action: string, queryString?: string, ) => void>; /** * Fired when the user switches to the panel. */ onShown: events.Event<( window: Window, ) => void>; /** * Fired when the user switches away from the panel. */ onHidden: events.Event<() => void>; /** * Appends a button to the status bar of the panel. * * @param iconPath Path to the icon of the button. The file should contain a 64x24-pixel image composed of two 32x24 icons. The left icon is used when the button is inactive; the right icon is displayed when the button is pressed. * @param tooltipText Text shown as a tooltip when user hovers the mouse over the button. * @param disabled Whether the button is disabled. */ createStatusBarButton( iconPath: string, tooltipText: string, disabled: boolean, ): Button; /** * Shows the panel by activating the corresponding tab. * * @since Chrome 140 */ show(): void; } /** * A sidebar created by the extension. */ export interface ExtensionSidebarPane { /** * Fired when the sidebar pane becomes visible as a result of user switching to the panel that hosts it. */ onShown: events.Event<( window: Window, ) => void>; /** * Fired when the sidebar pane becomes hidden as a result of the user switching away from the panel that hosts the sidebar pane. */ onHidden: events.Event<() => void>; /** * Sets the height of the sidebar. * * @param height A CSS-like size specification, such as `'100px'` or `'12ex'`. */ setHeight( height: string, ): void; /** * Sets an expression that is evaluated within the inspected page. The result is displayed in the sidebar pane. * * @param expression An expression to be evaluated in context of the inspected page. JavaScript objects and DOM nodes are displayed in an expandable tree similar to the console/watch. * @param rootTitle An optional title for the root of the expression tree. * @param callback A callback invoked after the sidebar pane is updated with the expression evaluation results. */ setExpression( expression: string, rootTitle?: string, callback?: () => void, ): void; /** * Sets a JSON-compliant object to be displayed in the sidebar pane. * * @param jsonObject An object to be displayed in context of the inspected page. Evaluated in the context of the caller (API client). * @param rootTitle An optional title for the root of the expression tree. * @param callback A callback invoked after the sidebar is updated with the object. */ setObject( jsonObject: string, rootTitle?: string, callback?: () => void, ): void; /** * Sets an HTML page to be displayed in the sidebar pane. * * @param path Relative path of an extension page to display within the sidebar. */ setPage( path: string, ): void; } /** * A button created by the extension. */ export interface Button { /** * Fired when the button is clicked. */ onClicked: events.Event<() => void>; /** * Updates the attributes of the button. If some of the arguments are omitted or `null`, the corresponding attributes are not updated. * * @param iconPath Path to the new icon of the button. * @param tooltipText Text shown as a tooltip when user hovers the mouse over the button. * @param disabled Whether the button is disabled. */ update( iconPath?: string, tooltipText?: string, disabled?: boolean, ): void; } /** * Theme used by DevTools. * * @chrome-enum "default" Default DevTools theme. This is always the light theme. * @chrome-enum "dark" Dark theme. * @since Chrome 99 */ export type Theme = "default" | "dark"; /** * Elements panel. */ export const elements: ElementsPanel; /** * Sources panel. */ export const sources: SourcesPanel; /** * The name of the color theme set in user's DevTools settings. Possible values: `default` (the default) and `dark`. * * @since Chrome 59 */ export const themeName: string; /** * Creates an extension panel. * * @param title Title that is displayed next to the extension icon in the Developer Tools toolbar. * @param iconPath Path of the panel's icon relative to the extension directory. * @param pagePath Path of the panel's HTML page relative to the extension directory. * @param callback A function that is called when the panel is created. */ export function create( title: string, iconPath: string, pagePath: string, /** * @param panel An ExtensionPanel object representing the created panel. */ callback?: ( panel: ExtensionPanel, ) => void, ): void; /** * Specifies the function to be called when the user clicks a resource link in the Developer Tools window. To unset the handler, either call the method with no parameters or pass null as the parameter. * * @param callback A function that is called when the user clicks on a valid resource link in Developer Tools window. Note that if the user clicks an invalid URL or an XHR, this function is not called. */ export function setOpenResourceHandler( /** * @param resource A {@link devtools.inspectedWindow.Resource} object for the resource that was clicked. * @param lineNumber Specifies the line number within the resource that was clicked. */ callback?: ( resource: devtools.inspectedWindow.Resource, lineNumber: number, ) => void, ): void; /** * Requests DevTools to open a URL in a Developer Tools panel. * * @param url The URL of the resource to open. * @param lineNumber Specifies the line number to scroll to when the resource is loaded. * @param columnNumber Specifies the column number to scroll to when the resource is loaded. * @param callback A function that is called when the resource has been successfully loaded. */ export function openResource( url: string, lineNumber: number, /** * @since Chrome 114 */ columnNumber?: number, callback?: () => void, ): void; /** * Specifies the function to be called when the current theme changes in DevTools. To unset the handler, either call the method with no parameters or pass `null` as the parameter. * * @param callback A function that is called when the current theme changes in DevTools. * @since Chrome 99 */ export function setThemeChangeHandler( /** * @param theme Current theme in DevTools. */ callback?: ( theme: Theme, ) => void, ): void; } /** * Use the `chrome.devtools.performance` API to listen to recording status updates in the Performance panel in DevTools. * * @since Chrome 129 */ export namespace devtools.performance { /** * Fired when the Performance panel starts recording. */ export const onProfilingStarted: events.Event<() => void>; /** * Fired when the Performance panel stops recording. */ export const onProfilingStopped: events.Event<() => void>; } /** * Use the `chrome.devtools.recorder` API to customize the Recorder panel in DevTools. * * @since Chrome 105 */ export namespace devtools.recorder { /** * A plugin interface that the Recorder panel invokes to customize the Recorder panel. */ export interface RecorderExtensionPlugin { /** * Converts a recording from the Recorder panel format into a string. * * @param recording A recording of the user interaction with the page. This should match [Puppeteer's recording schema](https://github.com/puppeteer/replay/blob/main/docs/api/interfaces/Schema.UserFlow.md). */ stringify( recording: {}, ): void; /** * Converts a step of the recording from the Recorder panel format into a string. * * @param step A step of the recording of a user interaction with the page. This should match [Puppeteer's step schema](https://github.com/puppeteer/replay/blob/main/docs/api/modules/Schema.md#step). */ stringifyStep( step: {}, ): void; /** * Allows the extension to implement custom replay functionality. * * @param recording A recording of the user interaction with the page. This should match [Puppeteer's recording schema](https://github.com/puppeteer/replay/blob/main/docs/api/interfaces/Schema.UserFlow.md). * @since Chrome 112 */ replay( recording: {}, ): void; } /** * Represents a view created by extension to be embedded inside the Recorder panel. * * @since Chrome 112 */ export interface RecorderView { /** * Fired when the view is shown. */ onShown: events.Event<() => void>; /** * Fired when the view is hidden. */ onHidden: events.Event<() => void>; /** * Indicates that the extension wants to show this view in the Recorder panel. */ show(): void; } /** * Registers a Recorder extension plugin. * * @param plugin An instance implementing the RecorderExtensionPlugin interface. * @param name The name of the plugin. * @param mediaType The media type of the string content that the plugin produces. */ export function registerRecorderExtensionPlugin( plugin: RecorderExtensionPlugin, name: string, mediaType: string, ): void; /** * Creates a view that can handle the replay. This view will be embedded inside the Recorder panel. * * @param title Title that is displayed next to the extension icon in the Developer Tools toolbar. * @param pagePath Path of the panel's HTML page relative to the extension directory. * @since Chrome 112 */ export function createView( title: string, pagePath: string, ): RecorderView; } /** * Use the `chrome.diagnostics` API to query various properties of the environment that may be useful for diagnostics. * * @alpha * @chrome-permission diagnostics * @chrome-channel dev * @chrome-platform-apps */ export namespace diagnostics { export interface SendPacketOptions { /** * Target IP address. */ ip: string; /** * Packet time to live value. If omitted, the system default value will be used. */ ttl?: number; /** * Packet timeout in seconds. If omitted, the system default value will be used. */ timeout?: number; /** * Size of the payload. If omitted, the system default value will be used. */ size?: number; } export interface SendPacketResult { /** * The IP of the host which we receives the ICMP reply from. The IP may differs from our target IP if the packet's ttl is used up. */ ip: string; /** * Latency in millisenconds. */ latency: number; } /** * Send a packet of the given type with the given parameters. */ export function sendPacket( options: SendPacketOptions, ): Promise; /** * Send a packet of the given type with the given parameters. */ export function sendPacket( options: SendPacketOptions, callback?: ( result: SendPacketResult, ) => void, ): void; } /** * Use the `chrome.dns` API for dns resolution. * * @alpha * @chrome-permission dns * @chrome-channel dev */ export namespace dns { export interface ResolveCallbackResolveInfo { /** * The result code. Zero indicates success. */ resultCode: number; /** * A string representing the IP address literal. Supplied only if resultCode indicates success. */ address?: string; } /** * Resolves the given hostname or IP address literal. * * @param hostname The hostname to resolve. * @returns Promise that resolves when the resolution operation completes. */ export function resolve( hostname: string, ): Promise; /** * Resolves the given hostname or IP address literal. * * @param hostname The hostname to resolve. */ export function resolve( hostname: string, callback?: ( resolveInfo: ResolveCallbackResolveInfo, ) => void, ): void; } /** * Use the `chrome.documentScan` API to discover and retrieve images from attached document scanners. * * @since Chrome 44 * @chrome-permission documentScan * @chrome-platform chromeos */ export namespace documentScan { export interface ScanOptions { /** * The MIME types that are accepted by the caller. */ mimeTypes?: string[]; /** * The number of scanned images allowed. The default is 1. */ maxImages?: number; } export interface ScanResults { /** * An array of data image URLs in a form that can be passed as the "src" value to an image tag. */ dataUrls: string[]; /** * The MIME type of the `dataUrls`. */ mimeType: string; } /** * An enum that indicates the result of each operation. * * @chrome-enum "UNKNOWN" An unknown or generic failure occurred. * @chrome-enum "SUCCESS" The operation succeeded. * @chrome-enum "UNSUPPORTED" The operation is not supported. * @chrome-enum "CANCELLED" The operation was cancelled. * @chrome-enum "DEVICE\_BUSY" The device is busy. * @chrome-enum "INVALID" Either the data or an argument passed to the method is not valid. * @chrome-enum "WRONG\_TYPE" The supplied value is the wrong data type for the underlying option. * @chrome-enum "EOF" No more data is available. * @chrome-enum "ADF\_JAMMED" The document feeder is jammed. * @chrome-enum "ADF\_EMPTY" The document feeder is empty. * @chrome-enum "COVER\_OPEN" The flatbed cover is open. * @chrome-enum "IO\_ERROR" An error occurred while communicating with the device. * @chrome-enum "ACCESS\_DENIED" The device requires authentication. * @chrome-enum "NO\_MEMORY" Not enough memory is available on the Chromebook to complete the operation. * @chrome-enum "UNREACHABLE" The device is not reachable. * @chrome-enum "MISSING" The device is disconnected. * @chrome-enum "INTERNAL\_ERROR" An error has occurred somewhere other than the calling application. * @since Chrome 125 */ export type OperationResult = "UNKNOWN" | "SUCCESS" | "UNSUPPORTED" | "CANCELLED" | "DEVICE_BUSY" | "INVALID" | "WRONG_TYPE" | "EOF" | "ADF_JAMMED" | "ADF_EMPTY" | "COVER_OPEN" | "IO_ERROR" | "ACCESS_DENIED" | "NO_MEMORY" | "UNREACHABLE" | "MISSING" | "INTERNAL_ERROR"; /** * Indicates how the scanner is connected to the computer. * * @since Chrome 125 */ export type ConnectionType = "UNSPECIFIED" | "USB" | "NETWORK"; /** * @since Chrome 125 */ export interface ScannerInfo { /** * The ID of a specific scanner. */ scannerId: string; /** * A human-readable name for the scanner to display in the UI. */ name: string; /** * The scanner manufacturer. */ manufacturer: string; /** * The scanner model if it is available, or a generic description. */ model: string; /** * For matching against other `ScannerInfo` entries that point to the same physical device. */ deviceUuid: string; /** * Indicates how the scanner is connected to the computer. */ connectionType: ConnectionType; /** * If true, the scanner connection's transport cannot be intercepted by a passive listener, such as TLS or USB. */ secure: boolean; /** * An array of MIME types that can be requested for returned scans. */ imageFormats: string[]; /** * A human-readable description of the protocol or driver used to access the scanner, such as Mopria, WSD, or epsonds. This is primarily useful for allowing a user to choose between protocols if a device supports multiple protocols. */ protocolType: string; } /** * The data type of an option. * * @chrome-enum "UNKNOWN" The option's data type is unknown. The `value` property will be unset. * @chrome-enum "BOOL" The `value` property will be one of `true`false. * @chrome-enum "INT" A signed 32-bit integer. The `value` property will be long or long\[\], depending on whether the option takes more than one value. * @chrome-enum "FIXED" A double in the range -32768-32767.9999 with a resolution of 1/65535. The `value` property will be double or double\[\] depending on whether the option takes more than one value. Double values that can't be exactly represented will be rounded to the available range and precision. * @chrome-enum "STRING" A sequence of any bytes except NUL ('\\0'). The `value` property will be a DOMString. * @chrome-enum "BUTTON" An option of this type has no value. Instead, setting an option of this type causes an option-specific side effect in the scanner driver. For example, a button-typed option could be used by a scanner driver to provide a means to select default values or to tell an automatic document feeder to advance to the next sheet of paper. * @chrome-enum "GROUP" Grouping option. No value. This is included for compatibility, but will not normally be returned in `ScannerOption` values. Use `getOptionGroups()` to retrieve the list of groups with their member options. * @since Chrome 125 */ export type OptionType = "UNKNOWN" | "BOOL" | "INT" | "FIXED" | "STRING" | "BUTTON" | "GROUP"; /** * Indicates the data type for {@link ScannerOption.unit}. * * @chrome-enum "UNITLESS" The value is a unitless number. For example, it can be a threshold. * @chrome-enum "PIXEL" The value is a number of pixels, for example, scan dimensions. * @chrome-enum "BIT" The value is the number of bits, for example, color depth. * @chrome-enum "MM" The value is measured in millimeters, for example, scan dimensions. * @chrome-enum "DPI" The value is measured in dots per inch, for example, resolution. * @chrome-enum "PERCENT" The value is a percent, for example, brightness. * @chrome-enum "MICROSECOND" The value is measured in microseconds, for example, exposure time. * @since Chrome 125 */ export type OptionUnit = "UNITLESS" | "PIXEL" | "BIT" | "MM" | "DPI" | "PERCENT" | "MICROSECOND"; /** * The data type of constraint represented by an {@link OptionConstraint}. * * @chrome-enum "INT\_RANGE" The constraint on a range of `OptionType.INT` values. The `min`, `max`, and `quant` properties of `OptionConstraint` will be `long`, and its `list` propety will be unset. * @chrome-enum "FIXED\_RANGE" The constraint on a range of `OptionType.FIXED` values. The `min`, `max`, and `quant` properties of `OptionConstraint` will be `double`, and its `list` property will be unset. * @chrome-enum "INT\_LIST" The constraint on a specific list of `OptionType.INT` values. The `OptionConstraint.list` property will contain `long` values, and the other properties will be unset. * @chrome-enum "FIXED\_LIST" The constraint on a specific list of `OptionType.FIXED` values. The `OptionConstraint.list` property will contain `double` values, and the other properties will be unset. * @chrome-enum "STRING\_LIST" The constraint on a specific list of `OptionType.STRING` values. The `OptionConstraint.list` property will contain `DOMString` values, and the other properties will be unset. * @since Chrome 125 */ export type ConstraintType = "INT_RANGE" | "FIXED_RANGE" | "INT_LIST" | "FIXED_LIST" | "STRING_LIST"; /** * @since Chrome 125 */ export interface OptionConstraint { type: ConstraintType; min?: number | number; max?: number | number; quant?: number | number; list?: number[] | number[] | string[]; } /** * How an option can be changed. * * @chrome-enum "NOT\_CONFIGURABLE" The option is read-only. * @chrome-enum "SOFTWARE\_CONFIGURABLE" The option can be set in software. * @chrome-enum "HARDWARE\_CONFIGURABLE" The option can be set by the user toggling or pushing a button on the scanner. * @since Chrome 125 */ export type Configurability = "NOT_CONFIGURABLE" | "SOFTWARE_CONFIGURABLE" | "HARDWARE_CONFIGURABLE"; /** * @since Chrome 125 */ export interface ScannerOption { /** * The option name using lowercase ASCII letters, numbers, and dashes. Diacritics are not allowed. */ name: string; /** * A printable one-line title. */ title: string; /** * A longer description of the option. */ description: string; /** * The data type contained in the `value` property, which is needed for setting this option. */ type: OptionType; /** * The unit of measurement for this option. */ unit: OptionUnit; /** * The current value of the option, if relevant. Note that the data type of this property must match the data type specified in `type`. */ value?: boolean | number | number[] | number | number[] | string; /** * Defines {@link OptionConstraint} on the current scanner option. */ constraint?: OptionConstraint; /** * Indicates that this option can be detected from software. */ isDetectable: boolean; /** * Indicates whether and how the option can be changed. */ configurability: Configurability; /** * Can be automatically set by the scanner driver. */ isAutoSettable: boolean; /** * Emulated by the scanner driver if true. */ isEmulated: boolean; /** * Indicates the option is active and can be set or retrieved. If false, the `value` property will not be set. */ isActive: boolean; /** * Indicates that the UI should not display this option by default. */ isAdvanced: boolean; } /** * @since Chrome 125 */ export interface DeviceFilter { /** * Only return scanners that are directly attached to the computer. */ local?: boolean; /** * Only return scanners that use a secure transport, such as USB or TLS. */ secure?: boolean; } /** * @since Chrome 125 */ export interface OptionGroup { /** * Provides a printable title, for example "Geometry options". */ title: string; /** * An array of option names in driver-provided order. */ members: string[]; } /** * @since Chrome 125 */ export interface GetScannerListResponse { /** * The enumeration result. Note that partial results could be returned even if this indicates an error. */ result: OperationResult; /** * A possibly-empty list of scanners that match the provided {@link DeviceFilter}. */ scanners: ScannerInfo[]; } /** * @since Chrome 125 */ export interface OpenScannerResponse { /** * The scanner ID passed to `openScanner()`. */ scannerId: string; /** * The result of opening the scanner. If the value of this is `SUCCESS`, the `scannerHandle` and `options` properties will be populated. */ result: OperationResult; /** * If `result` is `SUCCESS`, a handle to the scanner that can be used for further operations. */ scannerHandle?: string; /** * If `result` is `SUCCESS`, provides a key-value mapping where the key is a device-specific option and the value is an instance of {@link ScannerOption}. */ options?: {[name: string]: any}; } /** * @since Chrome 125 */ export interface GetOptionGroupsResponse { /** * The same scanner handle as was passed to {@link getOptionGroups}. */ scannerHandle: string; /** * The result of getting the option groups. If the value of this is `SUCCESS`, the `groups` property will be populated. */ result: OperationResult; /** * If `result` is `SUCCESS`, provides a list of option groups in the order supplied by the scanner driver. */ groups?: OptionGroup[]; } /** * @since Chrome 125 */ export interface CloseScannerResponse { /** * The same scanner handle as was passed to {@link closeScanner}. */ scannerHandle: string; /** * The result of closing the scanner. Even if this value is not `SUCCESS`, the handle will be invalid and should not be used for any further operations. */ result: OperationResult; } /** * @since Chrome 125 */ export interface OptionSetting { /** * Indicates the name of the option to set. */ name: string; /** * Indicates the data type of the option. The requested data type must match the real data type of the underlying option. */ type: OptionType; /** * Indicates the value to set. Leave unset to request automatic setting for options that have `autoSettable` enabled. The data type supplied for `value` must match `type`. */ value?: boolean | number | number[] | number | number[] | string; } /** * @since Chrome 125 */ export interface SetOptionResult { /** * Indicates the name of the option that was set. */ name: string; /** * Indicates the result of setting the option. */ result: OperationResult; } /** * @since Chrome 125 */ export interface SetOptionsResponse { /** * Provides the scanner handle passed to `setOptions()`. */ scannerHandle: string; /** * An array of results, one each for every passed-in `OptionSetting`. */ results: SetOptionResult[]; /** * An updated key-value mapping from option names to {@link ScannerOption} values containing the new configuration after attempting to set all supplied options. This has the same structure as the `options` property in {@link OpenScannerResponse}. * * This property will be set even if some options were not set successfully, but will be unset if retrieving the updated configuration fails (for example, if the scanner is disconnected in the middle of scanning). */ options?: {[name: string]: any}; } /** * @since Chrome 125 */ export interface StartScanOptions { /** * Specifies the MIME type to return scanned data in. */ format: string; /** * If a non-zero value is specified, limits the maximum scanned bytes returned in a single {@link readScanData} response to that value. The smallest allowed value is 32768 (32 KB). If this property is not specified, the size of a returned chunk may be as large as the entire scanned image. */ maxReadSize?: number; } /** * @since Chrome 125 */ export interface StartScanResponse { /** * Provides the same scanner handle that was passed to `startScan()`. */ scannerHandle: string; /** * The result of starting a scan. If the value of this is `SUCCESS`, the `job` property will be populated. */ result: OperationResult; /** * If `result` is `SUCCESS`, provides a handle that can be used to read scan data or cancel the job. */ job?: string; } /** * @since Chrome 125 */ export interface CancelScanResponse { /** * Provides the same job handle that was passed to `cancelScan()`. */ job: string; /** * The backend's cancel scan result. If the result is `OperationResult.SUCCESS` or `OperationResult.CANCELLED`, the scan has been cancelled and the scanner is ready to start a new scan. If the result is `OperationResult.DEVICE_BUSY` , the scanner is still processing the requested cancellation; the caller should wait a short time and try the request again. Other result values indicate a permanent error that should not be retried. */ result: OperationResult; } /** * @since Chrome 125 */ export interface ReadScanDataResponse { /** * Provides the job handle passed to `readScanData()`. */ job: string; /** * The result of reading data. If its value is `SUCCESS`, then `data` contains the _next_ (possibly zero-length) chunk of image data that is ready for reading. If its value is `EOF`, the `data` contains the _last_ chunk of image data. */ result: OperationResult; /** * If `result` is `SUCCESS`, contains the _next_ chunk of scanned image data. If `result` is `EOF`, contains the _last_ chunk of scanned image data. */ data?: ArrayBuffer; /** * If `result` is `SUCCESS`, an estimate of how much of the total scan data has been delivered so far, in the range 0 to 100. */ estimatedCompletion?: number; } /** * Performs a document scan and returns a Promise that resolves with a {@link ScanResults} object. If a callback is passed to this function, the returned data is passed to it instead. * * @chrome-returns-extra since Chrome 96 * @param options An object containing scan parameters. * @returns Returns a Promise which resolves with the scan results. */ export function scan( options: ScanOptions, ): Promise; /** * Performs a document scan and returns a Promise that resolves with a {@link ScanResults} object. If a callback is passed to this function, the returned data is passed to it instead. * * @param options An object containing scan parameters. */ export function scan( options: ScanOptions, callback?: ( result: ScanResults, ) => void, ): void; /** * Gets the list of available scanners and returns a Promise that resolves with a {@link GetScannerListResponse} object. If a callback is passed to this function, returned data is passed to it instead. * * @param filter A {@link DeviceFilter} indicating which types of scanners should be returned. * @returns Returns a Promise which resolves with the result and list of scanners. * @since Chrome 125 */ export function getScannerList( filter: DeviceFilter, ): Promise; /** * Gets the list of available scanners and returns a Promise that resolves with a {@link GetScannerListResponse} object. If a callback is passed to this function, returned data is passed to it instead. * * @param filter A {@link DeviceFilter} indicating which types of scanners should be returned. * @since Chrome 125 */ export function getScannerList( filter: DeviceFilter, callback?: ( response: GetScannerListResponse, ) => void, ): void; /** * Opens a scanner for exclusive access and returns a Promise that resolves with an {@link OpenScannerResponse} object. If a callback is passed to this function, returned data is passed to it instead. * * @param scannerId The ID of a scanner to be opened. This value is one returned from a previous call to {@link getScannerList}. * @returns Returns a Promise which resolves with the result. * @since Chrome 125 */ export function openScanner( scannerId: string, ): Promise; /** * Opens a scanner for exclusive access and returns a Promise that resolves with an {@link OpenScannerResponse} object. If a callback is passed to this function, returned data is passed to it instead. * * @param scannerId The ID of a scanner to be opened. This value is one returned from a previous call to {@link getScannerList}. * @since Chrome 125 */ export function openScanner( scannerId: string, callback?: ( response: OpenScannerResponse, ) => void, ): void; /** * Gets the group names and member options from a scanner previously opened by {@link openScanner}. This method returns a Promise that resolves with a {@link GetOptionGroupsResponse} object. If a callback is passed to this function, returned data is passed to it instead. * * @param scannerHandle The handle of an open scanner returned from a call to {@link openScanner}. * @returns Returns a Promise which resolves with the result. * @since Chrome 125 */ export function getOptionGroups( scannerHandle: string, ): Promise; /** * Gets the group names and member options from a scanner previously opened by {@link openScanner}. This method returns a Promise that resolves with a {@link GetOptionGroupsResponse} object. If a callback is passed to this function, returned data is passed to it instead. * * @param scannerHandle The handle of an open scanner returned from a call to {@link openScanner}. * @since Chrome 125 */ export function getOptionGroups( scannerHandle: string, callback?: ( response: GetOptionGroupsResponse, ) => void, ): void; /** * Closes the scanner with the passed in handle and returns a Promise that resolves with a {@link CloseScannerResponse} object. If a callback is used, the object is passed to it instead. Even if the response is not a success, the supplied handle becomes invalid and should not be used for further operations. * * @param scannerHandle Specifies the handle of an open scanner that was previously returned from a call to {@link openScanner}. * @returns Returns a Promise which resolves with the result. * @since Chrome 125 */ export function closeScanner( scannerHandle: string, ): Promise; /** * Closes the scanner with the passed in handle and returns a Promise that resolves with a {@link CloseScannerResponse} object. If a callback is used, the object is passed to it instead. Even if the response is not a success, the supplied handle becomes invalid and should not be used for further operations. * * @param scannerHandle Specifies the handle of an open scanner that was previously returned from a call to {@link openScanner}. * @since Chrome 125 */ export function closeScanner( scannerHandle: string, callback?: ( response: CloseScannerResponse, ) => void, ): void; /** * Sets options on the specified scanner and returns a Promise that resolves with a {@link SetOptionsResponse} object containing the result of trying to set every value in the order of the passed-in {@link OptionSetting} object. If a callback is used, the object is passed to it instead. * * @param scannerHandle The handle of the scanner to set options on. This should be a value previously returned from a call to {@link openScanner}. * @param options A list of `OptionSetting` objects to be applied to the scanner. * @returns Returns a Promise which resolves with the result. * @since Chrome 125 */ export function setOptions( scannerHandle: string, options: OptionSetting[], ): Promise; /** * Sets options on the specified scanner and returns a Promise that resolves with a {@link SetOptionsResponse} object containing the result of trying to set every value in the order of the passed-in {@link OptionSetting} object. If a callback is used, the object is passed to it instead. * * @param scannerHandle The handle of the scanner to set options on. This should be a value previously returned from a call to {@link openScanner}. * @param options A list of `OptionSetting` objects to be applied to the scanner. * @since Chrome 125 */ export function setOptions( scannerHandle: string, options: OptionSetting[], callback?: ( response: SetOptionsResponse, ) => void, ): void; /** * Starts a scan on the specified scanner and returns a Promise that resolves with a {@link StartScanResponse}. If a callback is used, the object is passed to it instead. If the call was successful, the response includes a job handle that can be used in subsequent calls to read scan data or cancel a scan. * * @param scannerHandle The handle of an open scanner. This should be a value previously returned from a call to {@link openScanner}. * @param options A {@link StartScanOptions} object indicating the options to be used for the scan. The `StartScanOptions.format` property must match one of the entries returned in the scanner's `ScannerInfo`. * @returns Returns a Promise which resolves with the result. * @since Chrome 125 */ export function startScan( scannerHandle: string, options: StartScanOptions, ): Promise; /** * Starts a scan on the specified scanner and returns a Promise that resolves with a {@link StartScanResponse}. If a callback is used, the object is passed to it instead. If the call was successful, the response includes a job handle that can be used in subsequent calls to read scan data or cancel a scan. * * @param scannerHandle The handle of an open scanner. This should be a value previously returned from a call to {@link openScanner}. * @param options A {@link StartScanOptions} object indicating the options to be used for the scan. The `StartScanOptions.format` property must match one of the entries returned in the scanner's `ScannerInfo`. * @since Chrome 125 */ export function startScan( scannerHandle: string, options: StartScanOptions, callback?: ( response: StartScanResponse, ) => void, ): void; /** * Cancels a started scan and returns a Promise that resolves with a {@link CancelScanResponse} object. If a callback is used, the object is passed to it instead. * * @param job The handle of an active scan job previously returned from a call to {@link startScan}. * @returns Returns a Promise which resolves with the result. * @since Chrome 125 */ export function cancelScan( job: string, ): Promise; /** * Cancels a started scan and returns a Promise that resolves with a {@link CancelScanResponse} object. If a callback is used, the object is passed to it instead. * * @param job The handle of an active scan job previously returned from a call to {@link startScan}. * @since Chrome 125 */ export function cancelScan( job: string, callback?: ( response: CancelScanResponse, ) => void, ): void; /** * Reads the next chunk of available image data from an active job handle, and returns a Promise that resolves with a {@link ReadScanDataResponse} object. If a callback is used, the object is passed to it instead. * * **Note:**It is valid for a response result to be `SUCCESS` with a zero-length `data` member. This means the scanner is still working but does not yet have additional data ready. The caller should wait a short time and try again. * * When the scan job completes, the response will have the result value of `EOF`. This response may contain a final non-zero `data` member. * * @param job Active job handle previously returned from {@link startScan}. * @returns Returns a Promise which resolves with the result. * @since Chrome 125 */ export function readScanData( job: string, ): Promise; /** * Reads the next chunk of available image data from an active job handle, and returns a Promise that resolves with a {@link ReadScanDataResponse} object. If a callback is used, the object is passed to it instead. * * **Note:**It is valid for a response result to be `SUCCESS` with a zero-length `data` member. This means the scanner is still working but does not yet have additional data ready. The caller should wait a short time and try again. * * When the scan job completes, the response will have the result value of `EOF`. This response may contain a final non-zero `data` member. * * @param job Active job handle previously returned from {@link startScan}. * @since Chrome 125 */ export function readScanData( job: string, callback?: ( response: ReadScanDataResponse, ) => void, ): void; } /** * Use the `chrome.dom` API to access special DOM APIs for Extensions * * @since Chrome 88 */ export namespace dom { /** * Gets the open shadow root or the closed shadow root hosted by the specified element. If the element doesn't attach the shadow root, it will return null. * * @returns See [https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot) */ export function openOrClosedShadowRoot( element: HTMLElement, ): {[name: string]: any}; } /** * Use the `chrome.downloads` API to programmatically initiate, monitor, manipulate, and search for downloads. * * @chrome-permission downloads */ export namespace downloads { export interface HeaderNameValuePair { /** * Name of the HTTP header. */ name: string; /** * Value of the HTTP header. */ value: string; } /** * uniquify * * To avoid duplication, the `filename` is changed to include a counter before the filename extension. * * overwrite * * The existing file will be overwritten with the new file. * * prompt * * The user will be prompted with a file chooser dialog. */ export type FilenameConflictAction = "uniquify" | "overwrite" | "prompt"; export interface FilenameSuggestion { /** * The {@link DownloadItem}'s new target {@link DownloadItem.filename}, as a path relative to the user's default Downloads directory, possibly containing subdirectories. Absolute paths, empty paths, and paths containing back-references ".." will be ignored. `filename` is ignored if there are any {@link onDeterminingFilename} listeners registered by any extensions. */ filename: string; /** * The action to take if `filename` already exists. */ conflictAction?: FilenameConflictAction; } export type HttpMethod = "GET" | "POST"; export type InterruptReason = "FILE_FAILED" | "FILE_ACCESS_DENIED" | "FILE_NO_SPACE" | "FILE_NAME_TOO_LONG" | "FILE_TOO_LARGE" | "FILE_VIRUS_INFECTED" | "FILE_TRANSIENT_ERROR" | "FILE_BLOCKED" | "FILE_SECURITY_CHECK_FAILED" | "FILE_TOO_SHORT" | "FILE_HASH_MISMATCH" | "FILE_SAME_AS_SOURCE" | "NETWORK_FAILED" | "NETWORK_TIMEOUT" | "NETWORK_DISCONNECTED" | "NETWORK_SERVER_DOWN" | "NETWORK_INVALID_REQUEST" | "SERVER_FAILED" | "SERVER_NO_RANGE" | "SERVER_BAD_CONTENT" | "SERVER_UNAUTHORIZED" | "SERVER_CERT_PROBLEM" | "SERVER_FORBIDDEN" | "SERVER_UNREACHABLE" | "SERVER_CONTENT_LENGTH_MISMATCH" | "SERVER_CROSS_ORIGIN_REDIRECT" | "USER_CANCELED" | "USER_SHUTDOWN" | "CRASH"; export interface DownloadOptions { /** * The URL to download. */ url: string; /** * A file path relative to the Downloads directory to contain the downloaded file, possibly containing subdirectories. Absolute paths, empty paths, and paths containing back-references ".." will cause an error. {@link onDeterminingFilename} allows suggesting a filename after the file's MIME type and a tentative filename have been determined. */ filename?: string; /** * The action to take if `filename` already exists. */ conflictAction?: FilenameConflictAction; /** * Use a file-chooser to allow the user to select a filename regardless of whether `filename` is set or already exists. */ saveAs?: boolean; /** * The HTTP method to use if the URL uses the HTTP\[S\] protocol. */ method?: HttpMethod; /** * Extra HTTP headers to send with the request if the URL uses the HTTP\[s\] protocol. Each header is represented as a dictionary containing the keys `name` and either `value` or `binaryValue`, restricted to those allowed by XMLHttpRequest. */ headers?: HeaderNameValuePair[]; /** * Post body. */ body?: string; } /** * @chrome-enum "file" The download's filename is suspicious. * @chrome-enum "url" The download's URL is known to be malicious. * @chrome-enum "content" The downloaded file is known to be malicious. * @chrome-enum "uncommon" The download's URL is not commonly downloaded and could be dangerous. * @chrome-enum "host" The download came from a host known to distribute malicious binaries and is likely dangerous. * @chrome-enum "unwanted" The download is potentially unwanted or unsafe. E.g. it could make changes to browser or computer settings. * @chrome-enum "safe" The download presents no known danger to the user's computer. * @chrome-enum "accepted" The user has accepted the dangerous download. * @chrome-enum "allowlistedByPolicy" Enterprise-related values. * @chrome-enum "forceSaveToGdrive" For use by the Secure Enterprise Browser extension. When required, Chrome will block the download to disc and download the file directly to Google Drive. */ export type DangerType = "file" | "url" | "content" | "uncommon" | "host" | "unwanted" | "safe" | "accepted" | "allowlistedByPolicy" | "asyncScanning" | "asyncLocalPasswordScanning" | "passwordProtected" | "blockedTooLarge" | "sensitiveContentWarning" | "sensitiveContentBlock" | "deepScannedFailed" | "deepScannedSafe" | "deepScannedOpenedDangerous" | "promptForScanning" | "promptForLocalPasswordScanning" | "accountCompromise" | "blockedScanFailed" | "forceSaveToGdrive"; /** * in\_progress * * The download is currently receiving data from the server. * * interrupted * * An error broke the connection with the file host. * * complete * * The download completed successfully. */ export type State = "in_progress" | "interrupted" | "complete"; export interface DownloadItem { /** * An identifier that is persistent across browser sessions. */ id: number; /** * The absolute URL that this download initiated from, before any redirects. */ url: string; /** * The absolute URL that this download is being made from, after all redirects. * * @since Chrome 54 */ finalUrl: string; /** * Absolute URL. */ referrer: string; /** * Absolute local path. */ filename: string; /** * False if this download is recorded in the history, true if it is not recorded. */ incognito: boolean; /** * Indication of whether this download is thought to be safe or known to be suspicious. */ danger: DangerType; /** * The file's MIME type. */ mime: string; /** * The time when the download began in ISO 8601 format. May be passed directly to the Date constructor: `chrome.downloads.search({}, function(items){items.forEach(function(item){console.log(new Date(item.startTime))})})` */ startTime: string; /** * The time when the download ended in ISO 8601 format. May be passed directly to the Date constructor: `chrome.downloads.search({}, function(items){items.forEach(function(item){if (item.endTime) console.log(new Date(item.endTime))})})` */ endTime?: string; /** * Estimated time when the download will complete in ISO 8601 format. May be passed directly to the Date constructor: `chrome.downloads.search({}, function(items){items.forEach(function(item){if (item.estimatedEndTime) console.log(new Date(item.estimatedEndTime))})})` */ estimatedEndTime?: string; /** * Indicates whether the download is progressing, interrupted, or complete. */ state: State; /** * True if the download has stopped reading data from the host, but kept the connection open. */ paused: boolean; /** * True if the download is in progress and paused, or else if it is interrupted and can be resumed starting from where it was interrupted. */ canResume: boolean; /** * Why the download was interrupted. Several kinds of HTTP errors may be grouped under one of the errors beginning with `SERVER_`. Errors relating to the network begin with `NETWORK_`, errors relating to the process of writing the file to the file system begin with `FILE_`, and interruptions initiated by the user begin with `USER_`. */ error?: InterruptReason; /** * Number of bytes received so far from the host, without considering file compression. */ bytesReceived: number; /** * Number of bytes in the whole file, without considering file compression, or -1 if unknown. */ totalBytes: number; /** * Number of bytes in the whole file post-decompression, or -1 if unknown. */ fileSize: number; /** * Whether the downloaded file still exists. This information may be out of date because Chrome does not automatically watch for file removal. Call {@link search}() in order to trigger the check for file existence. When the existence check completes, if the file has been deleted, then an {@link onChanged} event will fire. Note that {@link search}() does not wait for the existence check to finish before returning, so results from {@link search}() may not accurately reflect the file system. Also, {@link search}() may be called as often as necessary, but will not check for file existence any more frequently than once every 10 seconds. */ exists: boolean; /** * The identifier for the extension that initiated this download if this download was initiated by an extension. Does not change once it is set. */ byExtensionId?: string; /** * The localized name of the extension that initiated this download if this download was initiated by an extension. May change if the extension changes its name or if the user changes their locale. */ byExtensionName?: string; } export interface DownloadQuery { /** * This array of search terms limits results to {@link DownloadItem} whose `filename` or `url` or `finalUrl` contain all of the search terms that do not begin with a dash '-' and none of the search terms that do begin with a dash. */ query?: string[]; /** * Limits results to {@link DownloadItem} that started before the given ms in ISO 8601 format. */ startedBefore?: string; /** * Limits results to {@link DownloadItem} that started after the given ms in ISO 8601 format. */ startedAfter?: string; /** * Limits results to {@link DownloadItem} that ended before the given ms in ISO 8601 format. */ endedBefore?: string; /** * Limits results to {@link DownloadItem} that ended after the given ms in ISO 8601 format */ endedAfter?: string; /** * Limits results to {@link DownloadItem} whose `totalBytes` is greater than the given integer. */ totalBytesGreater?: number; /** * Limits results to {@link DownloadItem} whose `totalBytes` is less than the given integer. */ totalBytesLess?: number; /** * Limits results to {@link DownloadItem} whose `filename` matches the given regular expression. */ filenameRegex?: string; /** * Limits results to {@link DownloadItem} whose `url` matches the given regular expression. */ urlRegex?: string; /** * Limits results to {@link DownloadItem} whose `finalUrl` matches the given regular expression. * * @since Chrome 54 */ finalUrlRegex?: string; /** * The maximum number of matching {@link DownloadItem} returned. Defaults to 1000. Set to 0 in order to return all matching {@link DownloadItem}. See {@link search} for how to page through results. */ limit?: number; /** * Set elements of this array to {@link DownloadItem} properties in order to sort search results. For example, setting `orderBy=['startTime']` sorts the {@link DownloadItem} by their start time in ascending order. To specify descending order, prefix with a hyphen: '-startTime'. */ orderBy?: string[]; /** * The `id` of the {@link DownloadItem} to query. */ id?: number; /** * The absolute URL that this download initiated from, before any redirects. */ url?: string; /** * The absolute URL that this download is being made from, after all redirects. * * @since Chrome 54 */ finalUrl?: string; /** * Absolute local path. */ filename?: string; /** * Indication of whether this download is thought to be safe or known to be suspicious. */ danger?: DangerType; /** * The file's MIME type. */ mime?: string; /** * The time when the download began in ISO 8601 format. */ startTime?: string; /** * The time when the download ended in ISO 8601 format. */ endTime?: string; /** * Indicates whether the download is progressing, interrupted, or complete. */ state?: State; /** * True if the download has stopped reading data from the host, but kept the connection open. */ paused?: boolean; /** * Why a download was interrupted. */ error?: InterruptReason; /** * Number of bytes received so far from the host, without considering file compression. */ bytesReceived?: number; /** * Number of bytes in the whole file, without considering file compression, or -1 if unknown. */ totalBytes?: number; /** * Number of bytes in the whole file post-decompression, or -1 if unknown. */ fileSize?: number; /** * Whether the downloaded file exists; */ exists?: boolean; } export interface StringDelta { previous?: string; current?: string; } export interface DoubleDelta { previous?: number; current?: number; } export interface BooleanDelta { previous?: boolean; current?: boolean; } export interface DownloadDelta { /** * The `id` of the {@link DownloadItem} that changed. */ id: number; /** * The change in `url`, if any. */ url?: StringDelta; /** * The change in `finalUrl`, if any. * * @since Chrome 54 */ finalUrl?: StringDelta; /** * The change in `filename`, if any. */ filename?: StringDelta; /** * The change in `danger`, if any. */ danger?: StringDelta; /** * The change in `mime`, if any. */ mime?: StringDelta; /** * The change in `startTime`, if any. */ startTime?: StringDelta; /** * The change in `endTime`, if any. */ endTime?: StringDelta; /** * The change in `state`, if any. */ state?: StringDelta; /** * The change in `canResume`, if any. */ canResume?: BooleanDelta; /** * The change in `paused`, if any. */ paused?: BooleanDelta; /** * The change in `error`, if any. */ error?: StringDelta; /** * The change in `totalBytes`, if any. */ totalBytes?: DoubleDelta; /** * The change in `fileSize`, if any. */ fileSize?: DoubleDelta; /** * The change in `exists`, if any. */ exists?: BooleanDelta; } export interface GetFileIconOptions { /** * The size of the returned icon. The icon will be square with dimensions size \* size pixels. The default and largest size for the icon is 32x32 pixels. The only supported sizes are 16 and 32. It is an error to specify any other size. */ size?: number; } /** * @since Chrome 105 */ export interface UiOptions { /** * Enable or disable the download UI. */ enabled: boolean; } /** * This event fires with the {@link DownloadItem} object when a download begins. */ export const onCreated: events.Event<( downloadItem: DownloadItem, ) => void>; /** * Fires with the `downloadId` when a download is erased from history. */ export const onErased: events.Event<( downloadId: number, ) => void>; /** * When any of a {@link DownloadItem}'s properties except `bytesReceived` and `estimatedEndTime` changes, this event fires with the `downloadId` and an object containing the properties that changed. */ export const onChanged: events.Event<( downloadDelta: DownloadDelta, ) => void>; /** * During the filename determination process, extensions will be given the opportunity to override the target {@link DownloadItem.filename}. Each extension may not register more than one listener for this event. Each listener must call `suggest` exactly once, either synchronously or asynchronously. If the listener calls `suggest` asynchronously, then it must return `true`. If the listener neither calls `suggest` synchronously nor returns `true`, then `suggest` will be called automatically. The {@link DownloadItem} will not complete until all listeners have called `suggest`. Listeners may call `suggest` without any arguments in order to allow the download to use `downloadItem.filename` for its filename, or pass a `suggestion` object to `suggest` in order to override the target filename. If more than one extension overrides the filename, then the last extension installed whose listener passes a `suggestion` object to `suggest` wins. In order to avoid confusion regarding which extension will win, users should not install extensions that may conflict. If the download is initiated by {@link download} and the target filename is known before the MIME type and tentative filename have been determined, pass `filename` to {@link download} instead. */ export const onDeterminingFilename: events.Event<( downloadItem: DownloadItem, suggest: ( suggestion?: FilenameSuggestion, ) => void, ) => void>; /** * Download a URL. If the URL uses the HTTP\[S\] protocol, then the request will include all cookies currently set for its hostname. If both `filename` and `saveAs` are specified, then the Save As dialog will be displayed, pre-populated with the specified `filename`. If the download started successfully, `callback` will be called with the new {@link DownloadItem}'s `downloadId`. If there was an error starting the download, then `callback` will be called with `downloadId=undefined` and {@link runtime.lastError} will contain a descriptive string. The error strings are not guaranteed to remain backwards compatible between releases. Extensions must not parse it. * * @chrome-returns-extra since Chrome 96 * @param options What to download and how. * @returns Returns a Promise which resolves with the id of the new {@link DownloadItem}. */ export function download( options: DownloadOptions, ): Promise; /** * Download a URL. If the URL uses the HTTP\[S\] protocol, then the request will include all cookies currently set for its hostname. If both `filename` and `saveAs` are specified, then the Save As dialog will be displayed, pre-populated with the specified `filename`. If the download started successfully, `callback` will be called with the new {@link DownloadItem}'s `downloadId`. If there was an error starting the download, then `callback` will be called with `downloadId=undefined` and {@link runtime.lastError} will contain a descriptive string. The error strings are not guaranteed to remain backwards compatible between releases. Extensions must not parse it. * * @param options What to download and how. */ export function download( options: DownloadOptions, callback?: ( downloadId: number, ) => void, ): void; /** * Find {@link DownloadItem}. Set `query` to the empty object to get all {@link DownloadItem}. To get a specific {@link DownloadItem}, set only the `id` field. To page through a large number of items, set `orderBy: ['-startTime']`, set `limit` to the number of items per page, and set `startedAfter` to the `startTime` of the last item from the last page. * * @chrome-returns-extra since Chrome 96 */ export function search( query: DownloadQuery, ): Promise; /** * Find {@link DownloadItem}. Set `query` to the empty object to get all {@link DownloadItem}. To get a specific {@link DownloadItem}, set only the `id` field. To page through a large number of items, set `orderBy: ['-startTime']`, set `limit` to the number of items per page, and set `startedAfter` to the `startTime` of the last item from the last page. */ export function search( query: DownloadQuery, callback?: ( results: DownloadItem[], ) => void, ): void; /** * Pause the download. If the request was successful the download is in a paused state. Otherwise {@link runtime.lastError} contains an error message. The request will fail if the download is not active. * * @chrome-returns-extra since Chrome 96 * @param downloadId The id of the download to pause. * @returns Returns a Promise which resolves when the pause request is completed. */ export function pause( downloadId: number, ): Promise; /** * Pause the download. If the request was successful the download is in a paused state. Otherwise {@link runtime.lastError} contains an error message. The request will fail if the download is not active. * * @param downloadId The id of the download to pause. */ export function pause( downloadId: number, callback?: () => void, ): void; /** * Resume a paused download. If the request was successful the download is in progress and unpaused. Otherwise {@link runtime.lastError} contains an error message. The request will fail if the download is not active. * * @chrome-returns-extra since Chrome 96 * @param downloadId The id of the download to resume. * @returns Returns a Promise which resolves when the resume request is completed. */ export function resume( downloadId: number, ): Promise; /** * Resume a paused download. If the request was successful the download is in progress and unpaused. Otherwise {@link runtime.lastError} contains an error message. The request will fail if the download is not active. * * @param downloadId The id of the download to resume. */ export function resume( downloadId: number, callback?: () => void, ): void; /** * Cancel a download. When `callback` is run, the download is cancelled, completed, interrupted or doesn't exist anymore. * * @chrome-returns-extra since Chrome 96 * @param downloadId The id of the download to cancel. * @returns Returns a Promise which resolves when the cancel request is completed. */ export function cancel( downloadId: number, ): Promise; /** * Cancel a download. When `callback` is run, the download is cancelled, completed, interrupted or doesn't exist anymore. * * @param downloadId The id of the download to cancel. */ export function cancel( downloadId: number, callback?: () => void, ): void; /** * Retrieve an icon for the specified download. For new downloads, file icons are available after the {@link onCreated} event has been received. The image returned by this function while a download is in progress may be different from the image returned after the download is complete. Icon retrieval is done by querying the underlying operating system or toolkit depending on the platform. The icon that is returned will therefore depend on a number of factors including state of the download, platform, registered file types and visual theme. If a file icon cannot be determined, {@link runtime.lastError} will contain an error message. * * @chrome-returns-extra since Chrome 96 * @param downloadId The identifier for the download. * @returns Returns a Promise which resolves with a URL to an image that represents the download. */ export function getFileIcon( downloadId: number, options?: GetFileIconOptions, ): Promise; /** * Retrieve an icon for the specified download. For new downloads, file icons are available after the {@link onCreated} event has been received. The image returned by this function while a download is in progress may be different from the image returned after the download is complete. Icon retrieval is done by querying the underlying operating system or toolkit depending on the platform. The icon that is returned will therefore depend on a number of factors including state of the download, platform, registered file types and visual theme. If a file icon cannot be determined, {@link runtime.lastError} will contain an error message. * * @param downloadId The identifier for the download. */ export function getFileIcon( downloadId: number, options?: GetFileIconOptions, callback?: ( iconURL?: string, ) => void, ): void; /** * Opens the downloaded file now if the {@link DownloadItem} is complete; otherwise returns an error through {@link runtime.lastError}. This method requires the `"downloads.open"` permission in addition to the `"downloads"` permission. An {@link onChanged} event fires when the item is opened for the first time. This method can only be called in response to a user gesture. * * @chrome-returns-extra since Chrome 123 * @param downloadId The identifier for the downloaded file. */ export function open( downloadId: number, ): Promise; /** * Opens the downloaded file now if the {@link DownloadItem} is complete; otherwise returns an error through {@link runtime.lastError}. This method requires the `"downloads.open"` permission in addition to the `"downloads"` permission. An {@link onChanged} event fires when the item is opened for the first time. This method can only be called in response to a user gesture. * * @param downloadId The identifier for the downloaded file. */ export function open( downloadId: number, /** * @since Chrome 123 */ callback?: () => void, ): void; /** * Show the downloaded file in its folder in a file manager. * * @param downloadId The identifier for the downloaded file. */ export function show( downloadId: number, ): void; /** * Show the default Downloads folder in a file manager. */ export function showDefaultFolder(): void; /** * Erase matching {@link DownloadItem} from history without deleting the downloaded file. An {@link onErased} event will fire for each {@link DownloadItem} that matches `query`, then `callback` will be called. * * @chrome-returns-extra since Chrome 96 */ export function erase( query: DownloadQuery, ): Promise; /** * Erase matching {@link DownloadItem} from history without deleting the downloaded file. An {@link onErased} event will fire for each {@link DownloadItem} that matches `query`, then `callback` will be called. */ export function erase( query: DownloadQuery, callback?: ( erasedIds: number[], ) => void, ): void; /** * Remove the downloaded file if it exists and the {@link DownloadItem} is complete; otherwise return an error through {@link runtime.lastError}. * * @chrome-returns-extra since Chrome 96 */ export function removeFile( downloadId: number, ): Promise; /** * Remove the downloaded file if it exists and the {@link DownloadItem} is complete; otherwise return an error through {@link runtime.lastError}. */ export function removeFile( downloadId: number, callback?: () => void, ): void; /** * Prompt the user to accept a dangerous download. Can only be called from a visible context (tab, window, or page/browser action popup). Does not automatically accept dangerous downloads. If the download is accepted, then an {@link onChanged} event will fire, otherwise nothing will happen. When all the data is fetched into a temporary file and either the download is not dangerous or the danger has been accepted, then the temporary file is renamed to the target filename, the `state` changes to 'complete', and {@link onChanged} fires. * * @chrome-returns-extra since Chrome 96 * @param downloadId The identifier for the {@link DownloadItem}. * @returns Returns a Promise which resolves when the danger prompt dialog closes. */ export function acceptDanger( downloadId: number, ): Promise; /** * Prompt the user to accept a dangerous download. Can only be called from a visible context (tab, window, or page/browser action popup). Does not automatically accept dangerous downloads. If the download is accepted, then an {@link onChanged} event will fire, otherwise nothing will happen. When all the data is fetched into a temporary file and either the download is not dangerous or the danger has been accepted, then the temporary file is renamed to the target filename, the `state` changes to 'complete', and {@link onChanged} fires. * * @param downloadId The identifier for the {@link DownloadItem}. */ export function acceptDanger( downloadId: number, callback?: () => void, ): void; /** * Enable or disable the gray shelf at the bottom of every window associated with the current browser profile. The shelf will be disabled as long as at least one extension has disabled it. Enabling the shelf while at least one other extension has disabled it will return an error through {@link runtime.lastError}. Requires the `"downloads.shelf"` permission in addition to the `"downloads"` permission. * * @deprecated Use {@link setUiOptions} instead. * @chrome-deprecated-since Chrome 117 */ export function setShelfEnabled( enabled: boolean, ): void; /** * Change the download UI of every window associated with the current browser profile. As long as at least one extension has set {@link UiOptions.enabled} to false, the download UI will be hidden. Setting {@link UiOptions.enabled} to true while at least one other extension has disabled it will return an error through {@link runtime.lastError}. Requires the `"downloads.ui"` permission in addition to the `"downloads"` permission. * * @param options Encapsulate a change to the download UI. * @returns Returns a Promise which resolves when the UI update is completed. * @since Chrome 105 */ export function setUiOptions( options: UiOptions, ): Promise; /** * Change the download UI of every window associated with the current browser profile. As long as at least one extension has set {@link UiOptions.enabled} to false, the download UI will be hidden. Setting {@link UiOptions.enabled} to true while at least one other extension has disabled it will return an error through {@link runtime.lastError}. Requires the `"downloads.ui"` permission in addition to the `"downloads"` permission. * * @param options Encapsulate a change to the download UI. * @since Chrome 105 */ export function setUiOptions( options: UiOptions, callback?: () => void, ): void; } /** * Use the `chrome.enterprise.deviceAttributes` API to read device attributes. Note: This API is only available to extensions force-installed by enterprise policy. * * @since Chrome 46 * @chrome-permission enterprise.deviceAttributes * @chrome-install-location policy * @chrome-platform chromeos */ export namespace enterprise.deviceAttributes { /** * Fetches the value of [the device identifier of the directory API](https://developers.google.com/admin-sdk/directory/v1/guides/manage-chrome-devices), that is generated by the server and identifies the cloud record of the device for querying in the cloud directory API. If the current user is not affiliated, returns an empty string. * * @chrome-returns-extra since Chrome 96 * @returns Returns a Promise which resolves with the device identifier of the directory API. */ export function getDirectoryDeviceId(): Promise; /** * Fetches the value of [the device identifier of the directory API](https://developers.google.com/admin-sdk/directory/v1/guides/manage-chrome-devices), that is generated by the server and identifies the cloud record of the device for querying in the cloud directory API. If the current user is not affiliated, returns an empty string. */ export function getDirectoryDeviceId( callback?: ( deviceId: string, ) => void, ): void; /** * Fetches the device's serial number. Please note the purpose of this API is to administrate the device (e.g. generating Certificate Sign Requests for device-wide certificates). This API may not be used for tracking devices without the consent of the device's administrator. If the current user is not affiliated, returns an empty string. * * @chrome-returns-extra since Chrome 96 * @returns Returns a Promise which resolves with the serial number of the device. * @since Chrome 66 */ export function getDeviceSerialNumber(): Promise; /** * Fetches the device's serial number. Please note the purpose of this API is to administrate the device (e.g. generating Certificate Sign Requests for device-wide certificates). This API may not be used for tracking devices without the consent of the device's administrator. If the current user is not affiliated, returns an empty string. * * @since Chrome 66 */ export function getDeviceSerialNumber( callback?: ( serialNumber: string, ) => void, ): void; /** * Fetches the administrator-annotated Asset Id. If the current user is not affiliated or no Asset Id has been set by the administrator, returns an empty string. * * @chrome-returns-extra since Chrome 96 * @returns Returns a Promise which resolves with the Asset ID of the device. * @since Chrome 66 */ export function getDeviceAssetId(): Promise; /** * Fetches the administrator-annotated Asset Id. If the current user is not affiliated or no Asset Id has been set by the administrator, returns an empty string. * * @since Chrome 66 */ export function getDeviceAssetId( callback?: ( assetId: string, ) => void, ): void; /** * Fetches the administrator-annotated Location. If the current user is not affiliated or no Annotated Location has been set by the administrator, returns an empty string. * * @chrome-returns-extra since Chrome 96 * @returns Returns a Promise which resolves with the Annotated Location of the device. * @since Chrome 66 */ export function getDeviceAnnotatedLocation(): Promise; /** * Fetches the administrator-annotated Location. If the current user is not affiliated or no Annotated Location has been set by the administrator, returns an empty string. * * @since Chrome 66 */ export function getDeviceAnnotatedLocation( callback?: ( annotatedLocation: string, ) => void, ): void; /** * Fetches the device's hostname as set by DeviceHostnameTemplate policy. If the current user is not affiliated or no hostname has been set by the enterprise policy, returns an empty string. * * @chrome-returns-extra since Chrome 96 * @returns Returns a Promise which resolves with the hostname of the device. * @since Chrome 82 */ export function getDeviceHostname(): Promise; /** * Fetches the device's hostname as set by DeviceHostnameTemplate policy. If the current user is not affiliated or no hostname has been set by the enterprise policy, returns an empty string. * * @since Chrome 82 */ export function getDeviceHostname( callback?: ( hostname: string, ) => void, ): void; } /** * Use the `chrome.enterprise.hardwarePlatform` API to get the manufacturer and model of the hardware platform where the browser runs. Note: This API is only available to extensions installed by enterprise policy. * * @since Chrome 71 * @chrome-permission enterprise.hardwarePlatform * @chrome-install-location policy */ export namespace enterprise.hardwarePlatform { export interface HardwarePlatformInfo { model: string; manufacturer: string; } /** * Obtains the manufacturer and model for the hardware platform and, if the extension is authorized, returns it via `callback`. * * @chrome-returns-extra since Chrome 96 * @returns Returns a Promise which resolves with the hardware platform info. */ export function getHardwarePlatformInfo(): Promise; /** * Obtains the manufacturer and model for the hardware platform and, if the extension is authorized, returns it via `callback`. */ export function getHardwarePlatformInfo( callback?: ( info: HardwarePlatformInfo, ) => void, ): void; } /** * Use the `chrome.enterprise.kioskInput` API to change input settings for Kiosk sessions. Note: This API is only available to extensions installed by enterprise policy in ChromeOS Kiosk sessions. * * @since Chrome 132 * @chrome-permission enterprise.kioskInput * @chrome-install-location policy * @chrome-platform chromeos */ export namespace enterprise.kioskInput { export interface SetCurrentInputMethodOptions { /** * The input method ID to set as current input method. This input method has to be enabled by enterprise policies. Supported IDs are located in https://crsrc.org/c/chrome/browser/resources/chromeos/input\_method. */ inputMethodId: string; } /** * Sets the current input method. This function only changes the current input method to an enabled input method. Input methods can be enabled by enterprise polices. If the input method ID is invalid, or not enabled, {@link runtime.lastError} will be set with a failure reason. * * @param options Object containing the fields defined in {@link SetCurrentInputMethodOptions}. * @returns Returns a Promise which resolves when the input method is changed, or rejects if there is an error. */ export function setCurrentInputMethod( options: SetCurrentInputMethodOptions, ): Promise; /** * Sets the current input method. This function only changes the current input method to an enabled input method. Input methods can be enabled by enterprise polices. If the input method ID is invalid, or not enabled, {@link runtime.lastError} will be set with a failure reason. * * @param options Object containing the fields defined in {@link SetCurrentInputMethodOptions}. */ export function setCurrentInputMethod( options: SetCurrentInputMethodOptions, callback?: () => void, ): void; } /** * Use the `chrome.enterprise.login` API to exit Managed Guest sessions. Note: This API is only available to extensions installed by enterprise policy in ChromeOS Managed Guest sessions. * * @since Chrome 139 * @chrome-permission enterprise.login * @chrome-install-location policy * @chrome-platform chromeos */ export namespace enterprise.login { /** * Exits the current managed guest session. */ export function exitCurrentManagedGuestSession(): Promise; /** * Exits the current managed guest session. */ export function exitCurrentManagedGuestSession( callback?: () => void, ): void; } /** * Use the `chrome.enterprise.networkingAttributes` API to read information about your current network. Note: This API is only available to extensions force-installed by enterprise policy. * * @since Chrome 85 * @chrome-permission enterprise.networkingAttributes * @chrome-install-location policy * @chrome-platform chromeos */ export namespace enterprise.networkingAttributes { export interface NetworkDetails { /** * The device's MAC address. */ macAddress: string; /** * The device's local IPv4 address (undefined if not configured). */ ipv4?: string; /** * The device's local IPv6 address (undefined if not configured). */ ipv6?: string; } /** * Retrieves the network details of the device's default network. If the user is not affiliated or the device is not connected to a network, {@link runtime.lastError} will be set with a failure reason. * * @chrome-returns-extra since Chrome 96 * @returns Returns a Promise which resolves with the device's default network's {@link NetworkDetails}. */ export function getNetworkDetails(): Promise; /** * Retrieves the network details of the device's default network. If the user is not affiliated or the device is not connected to a network, {@link runtime.lastError} will be set with a failure reason. */ export function getNetworkDetails( callback?: ( networkAddresses: NetworkDetails, ) => void, ): void; } /** * Use the `chrome.enterprise.platformKeys` API to generate keys and install certificates for these keys. The certificates will be managed by the platform and can be used for TLS authentication, network access or by other extension through {@link platformKeys chrome.platformKeys}. * * @chrome-permission enterprise.platformKeys * @chrome-install-location policy * @chrome-platform chromeos */ export namespace enterprise.platformKeys { export interface Token { /** * Uniquely identifies this `Token`. * * Static IDs are `"user"` and `"system"`, referring to the platform's user-specific and the system-wide hardware token, respectively. Any other tokens (with other identifiers) might be returned by {@link enterprise.platformKeys.getTokens}. */ id: string; /** * Implements the WebCrypto's [SubtleCrypto](https://www.w3.org/TR/WebCryptoAPI/#subtlecrypto-interface) interface. The cryptographic operations, including key generation, are hardware-backed. * * Only non-extractable keys can be generated. The supported key types are RSASSA-PKCS1-V1\_5 and RSA-OAEP (on Chrome versions 135+) with `modulusLength` up to 2048 and ECDSA with `namedCurve` P-256. Each RSASSA-PKCS1-V1\_5 and ECDSA key can be used for signing data at most once, unless the extension is allowlisted through the [KeyPermissions policy](https://chromeenterprise.google/policies/#KeyPermissions), in which case the key can be used indefinitely. RSA-OAEP keys are supported since Chrome version 135 and can be used by extensions allowlisted through that same policy to unwrap other keys. * * Keys generated on a specific `Token` cannot be used with any other Tokens, nor can they be used with `window.crypto.subtle`. Equally, `Key` objects created with `window.crypto.subtle` cannot be used with this interface. */ subtleCrypto: SubtleCrypto; /** * Implements the WebCrypto's [SubtleCrypto](https://www.w3.org/TR/WebCryptoAPI/#subtlecrypto-interface) interface. The cryptographic operations, including key generation, are software-backed. Protection of the keys, and thus implementation of the non-extractable property, is done in software, so the keys are less protected than hardware-backed keys. * * Only non-extractable keys can be generated. The supported key types are RSASSA-PKCS1-V1\_5 and RSA-OAEP (on Chrome versions 135+) with `modulusLength` up to 2048. Each RSASSA-PKCS1-V1\_5 key can be used for signing data at most once, unless the extension is allowlisted through the [KeyPermissions policy](https://chromeenterprise.google/policies/#KeyPermissions), in which case the key can be used indefinitely. RSA-OAEP keys are supported since Chrome version 135 and can be used by extensions allowlisted through that same policy to unwrap other keys. * * Keys generated on a specific `Token` cannot be used with any other Tokens, nor can they be used with `window.crypto.subtle`. Equally, `Key` objects created with `window.crypto.subtle` cannot be used with this interface. * * @since Chrome 97 */ softwareBackedSubtleCrypto: SubtleCrypto; } /** * Whether to use the Enterprise User Key or the Enterprise Machine Key. * * @since Chrome 110 */ export type Scope = "USER" | "MACHINE"; /** * Type of key to generate. * * @since Chrome 110 */ export type Algorithm = "RSA" | "ECDSA"; /** * @since Chrome 110 */ export interface RegisterKeyOptions { /** * Which algorithm the registered key should use. */ algorithm: Algorithm; } /** * @since Chrome 110 */ export interface ChallengeKeyOptions { /** * A challenge as emitted by the Verified Access Web API. */ challenge: ArrayBuffer; /** * If present, registers the challenged key with the specified `scope`'s token. The key can then be associated with a certificate and used like any other signing key. Subsequent calls to this function will then generate a new Enterprise Key in the specified `scope`. */ registerKey?: RegisterKeyOptions; /** * Which Enterprise Key to challenge. */ scope: Scope; } /** * Returns the available Tokens. In a regular user's session the list will always contain the user's token with `id` `"user"`. If a system-wide TPM token is available, the returned list will also contain the system-wide token with `id` `"system"`. The system-wide token will be the same for all sessions on this device (device in the sense of e.g. a Chromebook). * * @chrome-returns-extra since Chrome 131 * @returns Invoked by `getTokens` with the list of available Tokens. */ export function getTokens(): Promise; /** * Returns the available Tokens. In a regular user's session the list will always contain the user's token with `id` `"user"`. If a system-wide TPM token is available, the returned list will also contain the system-wide token with `id` `"system"`. The system-wide token will be the same for all sessions on this device (device in the sense of e.g. a Chromebook). */ export function getTokens( /** * @param tokens The list of available tokens. */ callback?: ( tokens: Token[], ) => void, ): void; /** * Returns the list of all client certificates available from the given token. Can be used to check for the existence and expiration of client certificates that are usable for a certain authentication. * * @chrome-returns-extra since Chrome 131 * @param tokenId The id of a Token returned by `getTokens`. * @returns Returns a Promise which resolves with the list of the available certificates. */ export function getCertificates( tokenId: string, ): Promise; /** * Returns the list of all client certificates available from the given token. Can be used to check for the existence and expiration of client certificates that are usable for a certain authentication. * * @param tokenId The id of a Token returned by `getTokens`. */ export function getCertificates( tokenId: string, /** * @param certificates The list of certificates, each in DER encoding of a X.509 certificate. */ callback?: ( certificates: ArrayBuffer[], ) => void, ): void; /** * Imports `certificate` to the given token if the certified key is already stored in this token. After a successful certification request, this function should be used to store the obtained certificate and to make it available to the operating system and browser for authentication. * * @chrome-returns-extra since Chrome 131 * @param tokenId The id of a Token returned by `getTokens`. * @param certificate The DER encoding of a X.509 certificate. * @returns Returns a Promise which resolves when this operation is finished. */ export function importCertificate( tokenId: string, certificate: ArrayBuffer, ): Promise; /** * Imports `certificate` to the given token if the certified key is already stored in this token. After a successful certification request, this function should be used to store the obtained certificate and to make it available to the operating system and browser for authentication. * * @param tokenId The id of a Token returned by `getTokens`. * @param certificate The DER encoding of a X.509 certificate. */ export function importCertificate( tokenId: string, certificate: ArrayBuffer, callback?: () => void, ): void; /** * Removes `certificate` from the given token if present. Should be used to remove obsolete certificates so that they are not considered during authentication and do not clutter the certificate choice. Should be used to free storage in the certificate store. * * @chrome-returns-extra since Chrome 131 * @param tokenId The id of a Token returned by `getTokens`. * @param certificate The DER encoding of a X.509 certificate. * @returns Returns a Promise which resolves when this operation is finished. */ export function removeCertificate( tokenId: string, certificate: ArrayBuffer, ): Promise; /** * Removes `certificate` from the given token if present. Should be used to remove obsolete certificates so that they are not considered during authentication and do not clutter the certificate choice. Should be used to free storage in the certificate store. * * @param tokenId The id of a Token returned by `getTokens`. * @param certificate The DER encoding of a X.509 certificate. */ export function removeCertificate( tokenId: string, certificate: ArrayBuffer, callback?: () => void, ): void; /** * Similar to `challengeMachineKey` and `challengeUserKey`, but allows specifying the algorithm of a registered key. Challenges a hardware-backed Enterprise Machine Key and emits the response as part of a remote attestation protocol. Only useful on ChromeOS and in conjunction with the Verified Access Web API which both issues challenges and verifies responses. * * A successful verification by the Verified Access Web API is a strong signal that the current device is a legitimate ChromeOS device, the current device is managed by the domain specified during verification, the current signed-in user is managed by the domain specified during verification, and the current device state complies with enterprise device policy. For example, a policy may specify that the device must not be in developer mode. Any device identity emitted by the verification is tightly bound to the hardware of the current device. If `"user"` Scope is specified, the identity is also tightly bound to the current signed-in user. * * This function is highly restricted and will fail if the current device is not managed, the current user is not managed, or if this operation has not explicitly been enabled for the caller by enterprise device policy. The challenged key does not reside in the `"system"` or `"user"` token and is not accessible by any other API. * * @chrome-returns-extra since Chrome 131 * @param options Object containing the fields defined in {@link ChallengeKeyOptions}. * @returns Returns a Promise which resolves with the challenge response. * @since Chrome 110 */ export function challengeKey( options: ChallengeKeyOptions, ): Promise; /** * Similar to `challengeMachineKey` and `challengeUserKey`, but allows specifying the algorithm of a registered key. Challenges a hardware-backed Enterprise Machine Key and emits the response as part of a remote attestation protocol. Only useful on ChromeOS and in conjunction with the Verified Access Web API which both issues challenges and verifies responses. * * A successful verification by the Verified Access Web API is a strong signal that the current device is a legitimate ChromeOS device, the current device is managed by the domain specified during verification, the current signed-in user is managed by the domain specified during verification, and the current device state complies with enterprise device policy. For example, a policy may specify that the device must not be in developer mode. Any device identity emitted by the verification is tightly bound to the hardware of the current device. If `"user"` Scope is specified, the identity is also tightly bound to the current signed-in user. * * This function is highly restricted and will fail if the current device is not managed, the current user is not managed, or if this operation has not explicitly been enabled for the caller by enterprise device policy. The challenged key does not reside in the `"system"` or `"user"` token and is not accessible by any other API. * * @param options Object containing the fields defined in {@link ChallengeKeyOptions}. * @since Chrome 110 */ export function challengeKey( options: ChallengeKeyOptions, /** * @param response The challenge response. */ callback?: ( response: ArrayBuffer, ) => void, ): void; /** * Challenges a hardware-backed Enterprise Machine Key and emits the response as part of a remote attestation protocol. Only useful on ChromeOS and in conjunction with the Verified Access Web API which both issues challenges and verifies responses. A successful verification by the Verified Access Web API is a strong signal of all of the following: \* The current device is a legitimate ChromeOS device. \* The current device is managed by the domain specified during verification. \* The current signed-in user is managed by the domain specified during verification. \* The current device state complies with enterprise device policy. For example, a policy may specify that the device must not be in developer mode. \* Any device identity emitted by the verification is tightly bound to the hardware of the current device. This function is highly restricted and will fail if the current device is not managed, the current user is not managed, or if this operation has not explicitly been enabled for the caller by enterprise device policy. The Enterprise Machine Key does not reside in the `"system"` token and is not accessible by any other API. * * @chrome-returns-extra since Chrome 131 * @param challenge A challenge as emitted by the Verified Access Web API. * @param registerKey If set, the current Enterprise Machine Key is registered with the `"system"` token and relinquishes the Enterprise Machine Key role. The key can then be associated with a certificate and used like any other signing key. This key is 2048-bit RSA. Subsequent calls to this function will then generate a new Enterprise Machine Key. * @returns Returns a Promise which resolves with the challenge response. * @deprecated Use {@link challengeKey} instead. * @since Chrome 50 * @chrome-deprecated-since Chrome 110 */ export function challengeMachineKey( challenge: ArrayBuffer, /** * @since Chrome 59 */ registerKey?: boolean, ): Promise; /** * Challenges a hardware-backed Enterprise Machine Key and emits the response as part of a remote attestation protocol. Only useful on ChromeOS and in conjunction with the Verified Access Web API which both issues challenges and verifies responses. A successful verification by the Verified Access Web API is a strong signal of all of the following: \* The current device is a legitimate ChromeOS device. \* The current device is managed by the domain specified during verification. \* The current signed-in user is managed by the domain specified during verification. \* The current device state complies with enterprise device policy. For example, a policy may specify that the device must not be in developer mode. \* Any device identity emitted by the verification is tightly bound to the hardware of the current device. This function is highly restricted and will fail if the current device is not managed, the current user is not managed, or if this operation has not explicitly been enabled for the caller by enterprise device policy. The Enterprise Machine Key does not reside in the `"system"` token and is not accessible by any other API. * * @param challenge A challenge as emitted by the Verified Access Web API. * @param registerKey If set, the current Enterprise Machine Key is registered with the `"system"` token and relinquishes the Enterprise Machine Key role. The key can then be associated with a certificate and used like any other signing key. This key is 2048-bit RSA. Subsequent calls to this function will then generate a new Enterprise Machine Key. * @deprecated Use {@link challengeKey} instead. * @since Chrome 50 * @chrome-deprecated-since Chrome 110 */ export function challengeMachineKey( challenge: ArrayBuffer, /** * @since Chrome 59 */ registerKey?: boolean, /** * @param response The challenge response. */ callback?: ( response: ArrayBuffer, ) => void, ): void; /** * Challenges a hardware-backed Enterprise User Key and emits the response as part of a remote attestation protocol. Only useful on ChromeOS and in conjunction with the Verified Access Web API which both issues challenges and verifies responses. A successful verification by the Verified Access Web API is a strong signal of all of the following: \* The current device is a legitimate ChromeOS device. \* The current device is managed by the domain specified during verification. \* The current signed-in user is managed by the domain specified during verification. \* The current device state complies with enterprise user policy. For example, a policy may specify that the device must not be in developer mode. \* The public key emitted by the verification is tightly bound to the hardware of the current device and to the current signed-in user. This function is highly restricted and will fail if the current device is not managed, the current user is not managed, or if this operation has not explicitly been enabled for the caller by enterprise user policy. The Enterprise User Key does not reside in the `"user"` token and is not accessible by any other API. * * @chrome-returns-extra since Chrome 131 * @param challenge A challenge as emitted by the Verified Access Web API. * @param registerKey If set, the current Enterprise User Key is registered with the `"user"` token and relinquishes the Enterprise User Key role. The key can then be associated with a certificate and used like any other signing key. This key is 2048-bit RSA. Subsequent calls to this function will then generate a new Enterprise User Key. * @returns Returns a Promise which resolves with the challenge response. * @deprecated Use {@link challengeKey} instead. * @since Chrome 50 * @chrome-deprecated-since Chrome 110 */ export function challengeUserKey( challenge: ArrayBuffer, registerKey: boolean, ): Promise; /** * Challenges a hardware-backed Enterprise User Key and emits the response as part of a remote attestation protocol. Only useful on ChromeOS and in conjunction with the Verified Access Web API which both issues challenges and verifies responses. A successful verification by the Verified Access Web API is a strong signal of all of the following: \* The current device is a legitimate ChromeOS device. \* The current device is managed by the domain specified during verification. \* The current signed-in user is managed by the domain specified during verification. \* The current device state complies with enterprise user policy. For example, a policy may specify that the device must not be in developer mode. \* The public key emitted by the verification is tightly bound to the hardware of the current device and to the current signed-in user. This function is highly restricted and will fail if the current device is not managed, the current user is not managed, or if this operation has not explicitly been enabled for the caller by enterprise user policy. The Enterprise User Key does not reside in the `"user"` token and is not accessible by any other API. * * @param challenge A challenge as emitted by the Verified Access Web API. * @param registerKey If set, the current Enterprise User Key is registered with the `"user"` token and relinquishes the Enterprise User Key role. The key can then be associated with a certificate and used like any other signing key. This key is 2048-bit RSA. Subsequent calls to this function will then generate a new Enterprise User Key. * @deprecated Use {@link challengeKey} instead. * @since Chrome 50 * @chrome-deprecated-since Chrome 110 */ export function challengeUserKey( challenge: ArrayBuffer, registerKey: boolean, /** * @param response The challenge response. */ callback?: ( response: ArrayBuffer, ) => void, ): void; } /** * The `chrome.events` namespace contains common types used by APIs dispatching events to notify you when something interesting happens. */ export namespace events { /** * Description of a declarative rule for handling events. */ export interface Rule { /** * Optional identifier that allows referencing this rule. */ id?: string; /** * Tags can be used to annotate rules and perform operations on sets of rules. */ tags?: string[]; /** * List of conditions that can trigger the actions. */ conditions: any[]; /** * List of actions that are triggered if one of the conditions is fulfilled. */ actions: any[]; /** * Optional priority of this rule. Defaults to 100. */ priority?: number; } /** * An object which allows the addition and removal of listeners for a Chrome event. */ export interface Event void, C = void, A = void> { /** * Registers an event listener _callback_ to an event. * * @param callback Called when an event occurs. The parameters of this function depend on the type of event. */ addListener( callback: H, ): void; /** * Deregisters an event listener _callback_ from an event. * * @param callback Listener that shall be unregistered. */ removeListener( callback: H, ): void; /** * @param callback Listener whose registration status shall be tested. * @returns True if _callback_ is registered to the event. */ hasListener( callback: H, ): boolean; /** * @returns True if any event listeners are registered to the event. */ hasListeners(): boolean; /** * Registers rules to handle events. * * @param rules Rules to be registered. These do not replace previously registered rules. * @param callback Called with registered rules. */ addRules( rules: Rule[], /** * @param rules Rules that were registered, the optional parameters are filled with values. */ callback?: ( rules: Rule[], ) => void, ): void; /** * Returns currently registered rules. * * @param ruleIdentifiers If an array is passed, only rules with identifiers contained in this array are returned. * @param callback Called with registered rules. */ getRules( ruleIdentifiers: string[], /** * @param rules Rules that were registered, the optional parameters are filled with values. */ callback: ( rules: Rule[], ) => void, ): void; /** * Returns currently registered rules. * * @param callback Called with registered rules. */ getRules( /** * @param rules Rules that were registered, the optional parameters are filled with values. */ callback: ( rules: Rule[], ) => void, ): void; /** * Unregisters currently registered rules. * * @param ruleIdentifiers If an array is passed, only rules with identifiers contained in this array are unregistered. * @param callback Called when rules were unregistered. */ removeRules( ruleIdentifiers?: string[], callback?: () => void, ): void; } /** * Filters URLs for various criteria. See [event filtering](https://developer.chrome.com/docs/extensions/reference/events/#filtered). All criteria are case sensitive. */ export interface UrlFilter { /** * Matches if the host name of the URL contains a specified string. To test whether a host name component has a prefix 'foo', use hostContains: '.foo'. This matches 'www.foobar.com' and 'foo.com', because an implicit dot is added at the beginning of the host name. Similarly, hostContains can be used to match against component suffix ('foo.') and to exactly match against components ('.foo.'). Suffix- and exact-matching for the last components need to be done separately using hostSuffix, because no implicit dot is added at the end of the host name. */ hostContains?: string; /** * Matches if the host name of the URL is equal to a specified string. */ hostEquals?: string; /** * Matches if the host name of the URL starts with a specified string. */ hostPrefix?: string; /** * Matches if the host name of the URL ends with a specified string. */ hostSuffix?: string; /** * Matches if the path segment of the URL contains a specified string. */ pathContains?: string; /** * Matches if the path segment of the URL is equal to a specified string. */ pathEquals?: string; /** * Matches if the path segment of the URL starts with a specified string. */ pathPrefix?: string; /** * Matches if the path segment of the URL ends with a specified string. */ pathSuffix?: string; /** * Matches if the query segment of the URL contains a specified string. */ queryContains?: string; /** * Matches if the query segment of the URL is equal to a specified string. */ queryEquals?: string; /** * Matches if the query segment of the URL starts with a specified string. */ queryPrefix?: string; /** * Matches if the query segment of the URL ends with a specified string. */ querySuffix?: string; /** * Matches if the URL (without fragment identifier) contains a specified string. Port numbers are stripped from the URL if they match the default port number. */ urlContains?: string; /** * Matches if the URL (without fragment identifier) is equal to a specified string. Port numbers are stripped from the URL if they match the default port number. */ urlEquals?: string; /** * Matches if the URL (without fragment identifier) matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number. The regular expressions use the [RE2 syntax](https://github.com/google/re2/blob/master/doc/syntax.txt). */ urlMatches?: string; /** * Matches if the URL without query segment and fragment identifier matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number. The regular expressions use the [RE2 syntax](https://github.com/google/re2/blob/master/doc/syntax.txt). */ originAndPathMatches?: string; /** * Matches if the URL (without fragment identifier) starts with a specified string. Port numbers are stripped from the URL if they match the default port number. */ urlPrefix?: string; /** * Matches if the URL (without fragment identifier) ends with a specified string. Port numbers are stripped from the URL if they match the default port number. */ urlSuffix?: string; /** * Matches if the scheme of the URL is equal to any of the schemes specified in the array. */ schemes?: string[]; /** * Matches if the port of the URL is contained in any of the specified port lists. For example `[80, 443, [1000, 1200]]` matches all requests on port 80, 443 and in the range 1000-1200. */ ports?: (number | number[])[]; /** * Matches if the host part of the URL is an IP address and is contained in any of the CIDR blocks specified in the array. * * @since Chrome 123 */ cidrBlocks?: string[]; } } /** * The `chrome.extension` API has utilities that can be used by any extension page. It includes support for exchanging messages between an extension and its content scripts or between extensions, as described in detail in [Message Passing](https://developer.chrome.com/docs/extensions/messaging). */ export namespace extension { /** * The type of extension view. * * @since Chrome 44 */ export type ViewType = "tab" | "popup"; /** * Set for the lifetime of a callback if an ansychronous extension api has resulted in an error. If no error has occured lastError will be `undefined`. * * @deprecated Please use {@link runtime.lastError}. * @chrome-max-manifest MV2 * @chrome-deprecated-since Chrome 58 */ export let lastError: { /** * Description of the error that has taken place. */ message: string, }; /** * True for content scripts running inside incognito tabs, and for extension pages running inside an incognito process. The latter only applies to extensions with 'split' incognito\_behavior. */ export let inIncognitoContext: boolean; /** * Fired when a request is sent from either an extension process or a content script. * * @deprecated Please use {@link runtime.onMessage}. * @chrome-max-manifest MV2 */ export const onRequest: events.Event<( request: any, sender: runtime.MessageSender, sendResponse: () => void, ) => void>; /** * Fired when a request is sent from another extension. * * @deprecated Please use {@link runtime.onMessageExternal}. * @chrome-max-manifest MV2 */ export const onRequestExternal: events.Event<( request: any, sender: runtime.MessageSender, sendResponse: () => void, ) => void>; /** * Sends a single request to other listeners within the extension. Similar to {@link runtime.connect}, but only sends a single request with an optional response. The {@link extension.onRequest} event is fired in each page of the extension. * * @chrome-returns-extra since Chrome 99 * @param extensionId The extension ID of the extension you want to connect to. If omitted, default is your own extension. * @deprecated Please use {@link runtime.sendMessage}. * @chrome-max-manifest MV2 */ export function sendRequest( extensionId: string, request: any, ): Promise; /** * Sends a single request to other listeners within the extension. Similar to {@link runtime.connect}, but only sends a single request with an optional response. The {@link extension.onRequest} event is fired in each page of the extension. * * @chrome-returns-extra since Chrome 99 * @deprecated Please use {@link runtime.sendMessage}. * @chrome-max-manifest MV2 */ export function sendRequest( request: any, ): Promise; /** * Sends a single request to other listeners within the extension. Similar to {@link runtime.connect}, but only sends a single request with an optional response. The {@link extension.onRequest} event is fired in each page of the extension. * * @param extensionId The extension ID of the extension you want to connect to. If omitted, default is your own extension. * @deprecated Please use {@link runtime.sendMessage}. * @chrome-max-manifest MV2 */ export function sendRequest( extensionId: string, request: any, /** * @param response The JSON response object sent by the handler of the request. If an error occurs while connecting to the extension, the promise will be rejected. * @since Chrome 99 */ callback?: ( response: any, ) => void, ): void; /** * Sends a single request to other listeners within the extension. Similar to {@link runtime.connect}, but only sends a single request with an optional response. The {@link extension.onRequest} event is fired in each page of the extension. * * @deprecated Please use {@link runtime.sendMessage}. * @chrome-max-manifest MV2 */ export function sendRequest( request: any, /** * @param response The JSON response object sent by the handler of the request. If an error occurs while connecting to the extension, the promise will be rejected. * @since Chrome 99 */ callback?: ( response: any, ) => void, ): void; /** * Converts a relative path within an extension install directory to a fully-qualified URL. * * @param path A path to a resource within an extension expressed relative to its install directory. * @returns The fully-qualified URL to the resource. * @deprecated Please use {@link runtime.getURL}. * @chrome-max-manifest MV2 * @chrome-deprecated-since Chrome 58 */ export function getURL( path: string, ): string; /** * Returns an array of the JavaScript 'window' objects for each of the pages running inside the current extension. * * @returns Array of global objects * @chrome-disallow-service-workers */ export function getViews( fetchProperties?: { /** * The type of view to get. If omitted, returns all views (including background pages and tabs). */ type?: ViewType, /** * The window to restrict the search to. If omitted, returns all views. */ windowId?: number, /** * Find a view according to a tab id. If this field is omitted, returns all views. * * @since Chrome 54 */ tabId?: number, }, ): Window[]; /** * Returns the JavaScript 'window' object for the background page running inside the current extension. Returns null if the extension has no background page. * * @chrome-disallow-service-workers */ export function getBackgroundPage(): Window | undefined; /** * Returns an array of the JavaScript 'window' objects for each of the tabs running inside the current extension. If `windowId` is specified, returns only the 'window' objects of tabs attached to the specified window. * * @returns Array of global window objects * @deprecated Please use {@link extension.getViews} `{type: "tab"}`. * @chrome-disallow-service-workers * @chrome-max-manifest MV2 */ export function getExtensionTabs( windowId?: number, ): Window[]; /** * Retrieves the state of the extension's access to Incognito-mode. This corresponds to the user-controlled per-extension 'Allowed in Incognito' setting accessible via the chrome://extensions page. * * @chrome-returns-extra since Chrome 99 */ export function isAllowedIncognitoAccess(): Promise; /** * Retrieves the state of the extension's access to Incognito-mode. This corresponds to the user-controlled per-extension 'Allowed in Incognito' setting accessible via the chrome://extensions page. */ export function isAllowedIncognitoAccess( /** * @param isAllowedAccess True if the extension has access to Incognito mode, false otherwise. */ callback?: ( isAllowedAccess: boolean, ) => void, ): void; /** * Retrieves the state of the extension's access to the 'file://' scheme. This corresponds to the user-controlled per-extension 'Allow access to File URLs' setting accessible via the chrome://extensions page. * * @chrome-returns-extra since Chrome 99 */ export function isAllowedFileSchemeAccess(): Promise; /** * Retrieves the state of the extension's access to the 'file://' scheme. This corresponds to the user-controlled per-extension 'Allow access to File URLs' setting accessible via the chrome://extensions page. */ export function isAllowedFileSchemeAccess( /** * @param isAllowedAccess True if the extension can access the 'file://' scheme, false otherwise. */ callback?: ( isAllowedAccess: boolean, ) => void, ): void; /** * Sets the value of the ap CGI parameter used in the extension's update URL. This value is ignored for extensions that are hosted in the Chrome Extension Gallery. */ export function setUpdateUrlData( data: string, ): void; } /** * Schemas for structured manifest entries */ export namespace extensionsManifestTypes { /** * This API provides programmatic access to the user interface elements of Chrome. This includes everything in the web view, and optionally Chrome's full user interface. * * @since Chrome 67 */ export type automation = boolean | { /** * Whether to request permission to the whole ChromeOS desktop. If granted, this gives the extension access to every aspect of the desktop, and every site and app. If this permission is requested, all other permissions are implicitly included and do not need to be requested separately. */ desktop?: boolean, }; /** * The `content_capabilities` manifest entry allows an extension to grant certain additional capabilities to web contents whose locations match a given set of URL patterns. */ export interface ContentCapabilities { /** * The set of URL patterns to match against. If any of the given patterns match a URL, its contents will be granted the specified capabilities. */ matches: string[]; /** * The set of capabilities to grant matched contents. This is currently limited to `clipboardRead`, `clipboardWrite`, and `unlimitedStorage`. */ permissions: string[]; } export interface ExternallyConnectable { /** * The IDs of extensions or apps that are allowed to connect. If left empty or unspecified, no extensions or apps can connect. * * The wildcard `"*"` will allow all extensions and apps to connect. */ ids?: string[]; /** * The URL patterns for _web pages_ that are allowed to connect. _This does not affect content scripts._ If left empty or unspecified, no web pages can connect. * * Patterns cannot include wildcard domains nor subdomains of [(effective) top level domains](https://publicsuffix.org/list/); `*://google.com/*` and `http://*.chromium.org/*` are valid, while ``, `http://*\/*`, `*://*.com/*`, and even `http://*.appspot.com/*` are not. */ matches?: string[]; /** * If `true`, messages sent via {@link runtime.connect} or {@link runtime.sendMessage} will set {@link runtime.MessageSender.tlsChannelId} if those methods request it to be. If `false`, {@link runtime.MessageSender.tlsChannelId} will never be set under any circumstance. */ accepts_tls_channel_id?: boolean; } /** * The `options_ui` manifest property declares how the options page should be displayed. */ export interface OptionsUI { /** * The path to your options page, relative to your extension's root. */ page: string; /** * If `true`, a Chrome user agent stylesheet will be applied to your options page. The default value is `false`. We do not recommend you enable it as it no longer results in a consistent UI with Chrome. This option will be removed in Manifest V3. */ chrome_style?: boolean; /** * If `true`, your extension's options page will be opened in a new tab rather than embedded in _chrome://extensions_. The default is `false`, and we recommend that you don't change it. * * **This is only useful to delay the inevitable deprecation of the old options UI!** It will be removed soon, so try not to use it. It will break. */ open_in_tab?: boolean; } /** * A single string or a list of strings representing host:port patterns. */ export type SocketHostPatterns = string | string[]; /** * The `sockets` manifest property declares which sockets operations an app can issue. */ export interface sockets { /** * The `udp` manifest property declares which sockets.udp operations an app can issue. */ udp?: { /** * The host:port pattern for `bind` operations. */ bind?: SocketHostPatterns, /** * The host:port pattern for `send` operations. */ send?: SocketHostPatterns, /** * The host:port pattern for `joinGroup` operations. */ multicastMembership?: SocketHostPatterns, }; /** * The `tcp` manifest property declares which sockets.tcp operations an app can issue. */ tcp?: { /** * The host:port pattern for `connect` operations. */ connect?: SocketHostPatterns, }; /** * The `tcpServer` manifest property declares which sockets.tcpServer operations an app can issue. */ tcpServer?: { /** * The host:port pattern for `listen` operations. */ listen?: SocketHostPatterns, }; } /** * The `bluetooth` manifest property give permission to an app to use the {@link bluetooth} API. A list of UUIDs can be optionally specified to enable communication with devices. */ export interface bluetooth { /** * The `uuids` manifest property declares the list of protocols, profiles and services that an app can communicate using. */ uuids?: string[]; /** * If `true`, gives permission to an app to use the {@link bluetoothSocket} API */ socket?: boolean; /** * If `true`, gives permission to an app to use the {@link bluetoothLowEnergy} API */ low_energy?: boolean; /** * If `true`, gives permission to an app to use the advertisement functions in the {@link bluetoothLowEnergy} API * * @since Chrome 44 */ peripheral?: boolean; } /** * The `usb_printers` manifest property lists the USB printers supported by an app implementing the {@link printerProvider} API. * * @since Chrome 44 */ export interface UsbPrinters { /** * A list of {@link usb.DeviceFilter USB device filters} matching supported devices. A device only needs to match one of the provided filters. A `vendorId` is required and only one of `productId` or `interfaceClass` may be provided. */ filters: { /** * USB vendor ID of matching devices */ vendorId: number, /** * USB product ID of matching devices */ productId?: number, /** * USB interface class implemented by any interface of a matching device. */ interfaceClass?: number, /** * USB interface sub-class implemented by the interface matching {@link interfaceClass}. */ interfaceSubclass?: number, /** * USB interface protocol implemented by the interface matching {@link interfaceClass} and {@link interfaceSubclass}. */ interfaceProtocol?: number, }[]; } /** * The `kiosk_secondary_apps` manifest property lists the secondary kiosk apps to be deployed by the primary kiosk app. * * @since Chrome 47 */ export type KioskSecondaryApps = { /** * ID of secondary kiosk app */ id: string, /** * Whether the secondary app should be enabled when kiosk app is launched. If true, the app will be enabled before the kiosk app launch; if false the app will be disabled before the kiosk app launch; if not set, the app's enabled state will not be changed during the kiosk app launch. The ${ref:management} API can be used to later change the secondary app state. * * @since Chrome 66 */ enabled_on_launch?: boolean, }[]; } /** * The `chrome.extensionTypes` API contains type declarations for Chrome extensions. */ export namespace extensionTypes { /** * @since Chrome 139 */ export type ColorArray = [number, number, number, number]; /** * Pixel data for an image. Must be an ImageData object; for example, from a `canvas` element. * * @since Chrome 139 */ export type ImageDataType = ImageData; /** * The format of an image. * * @since Chrome 44 */ export type ImageFormat = "jpeg" | "png"; /** * Details about the format, quality, and area of an image. */ export interface ImageDetails { /** * The format of the resulting image. Default is `"jpeg"`. */ format?: ImageFormat; /** * When format is `"jpeg"`, controls the quality of the resulting image. This value is ignored for PNG images. As quality is decreased, the resulting image will have more visual artifacts, and the number of bytes needed to store it will decrease. */ quality?: number; } /** * The soonest that the JavaScript or CSS will be injected into the tab. * * @chrome-enum "document\_start" Script is injected after any files from css, but before any other DOM is constructed or any other script is run. * @chrome-enum "document\_end" Script is injected immediately after the DOM is complete, but before subresources like images and frames have loaded. * @chrome-enum "document\_idle" The browser chooses a time to inject the script between "document\_end" and immediately after the `window.onload` event fires. The exact moment of injection depends on how complex the document is and how long it is taking to load, and is optimized for page load speed. Content scripts running at "document\_idle" don't need to listen for the `window.onload` event; they are guaranteed to run after the DOM completes. If a script definitely needs to run after `window.onload`, the extension can check if `onload` has already fired by using the `document.readyState` property. * @since Chrome 44 */ export type RunAt = "document_start" | "document_end" | "document_idle"; /** * The [origin](https://www.w3.org/TR/css3-cascade/#cascading-origins) of injected CSS. * * @since Chrome 66 */ export type CSSOrigin = "author" | "user"; /** * 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. */ export interface InjectDetails { /** * JavaScript or CSS code to inject. * * * **Warning:** Be careful using the `code` parameter. Incorrect use of it may open your extension to [cross site scripting](https://en.wikipedia.org/wiki/Cross-site_scripting) attacks */ code?: string; /** * JavaScript or CSS file to inject. */ file?: string; /** * 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. If `true` and `frameId` is set, then the code is inserted in the selected frame and all of its child frames. */ allFrames?: boolean; /** * The [frame](https://developer.chrome.com/docs/extensions/reference/webNavigation/#frame_ids) where the script or CSS should be injected. Defaults to 0 (the top-level frame). * * @since Chrome 50 */ frameId?: number; /** * If matchAboutBlank is true, then the code is also injected in about:blank and about:srcdoc frames if your extension has access to its parent document. Code cannot be inserted in top-level about:-frames. By default it is `false`. */ matchAboutBlank?: boolean; /** * The soonest that the JavaScript or CSS will be injected into the tab. Defaults to "document\_idle". */ runAt?: RunAt; /** * The [origin](https://www.w3.org/TR/css3-cascade/#cascading-origins) of the CSS to inject. This may only be specified for CSS, not JavaScript. Defaults to `"author"`. * * @since Chrome 66 */ cssOrigin?: CSSOrigin; } /** * Details of the CSS to remove. Either the code or the file property must be set, but both may not be set at the same time. * * @since Chrome 87 */ export interface DeleteInjectionDetails { /** * CSS code to remove. */ code?: string; /** * CSS file to remove. */ file?: string; /** * If allFrames is `true`, implies that the CSS should be removed from all frames of current page. By default, it's `false` and is only removed from the top frame. If `true` and `frameId` is set, then the code is removed from the selected frame and all of its child frames. */ allFrames?: boolean; /** * The [frame](https://developer.chrome.com/docs/extensions/reference/webNavigation/#frame_ids) from where the CSS should be removed. Defaults to 0 (the top-level frame). */ frameId?: number; /** * If matchAboutBlank is true, then the code is also removed from about:blank and about:srcdoc frames if your extension has access to its parent document. By default it is `false`. */ matchAboutBlank?: boolean; /** * The [origin](https://www.w3.org/TR/css3-cascade/#cascading-origins) of the CSS to remove. Defaults to `"author"`. */ cssOrigin?: CSSOrigin; } /** * The type of frame. * * @since Chrome 106 */ export type FrameType = "outermost_frame" | "fenced_frame" | "sub_frame"; /** * The document lifecycle of the frame. * * @since Chrome 106 */ export type DocumentLifecycle = "prerender" | "active" | "cached" | "pending_deletion"; /** * The JavaScript world for a script to execute within. Can either be an isolated world unique to this extension, the main world of the DOM which is shared with the page's JavaScript, or a user scripts world that is only available for scripts registered with the User Scripts API. * * @since Chrome 111 */ export type ExecutionWorld = "ISOLATED" | "MAIN" | "USER_SCRIPT"; } /** * Use the `chrome.fileBrowserHandler` API to extend the Chrome OS file browser. For example, you can use this API to enable users to upload files to your website. * * @chrome-permission fileBrowserHandler * @chrome-disallow-service-workers * @chrome-platform chromeos */ export namespace fileBrowserHandler { /** * Event details payload for fileBrowserHandler.onExecute event. */ export interface FileHandlerExecuteEventDetails { /** * Array of Entry instances representing files that are targets of this action (selected in ChromeOS file browser). */ entries: any[]; /** * The ID of the tab that raised this event. Tab IDs are unique within a browser session. */ tab_id?: number; } /** * Fired when file system action is executed from ChromeOS file browser. */ export const onExecute: events.Event<( id: string, details: FileHandlerExecuteEventDetails, ) => void>; } /** * `file_handlers` manifest key defintion. File Handlers allow developers to let extensions interact with files on the operating system. This manifest key can be used by developers to register an extension to a given file type. * * @since Chrome 109 */ export namespace fileHandlers { export interface Icon { /** * URL from which a user agent can fetch image data. */ src: string; /** * Multiple space-separated size values to also accommodate image formats that can act as containers for multiple images of varying dimensions: e.g. "16x16", "16x16 32x32". */ sizes?: string; /** * MIME type is purely advisory with no default value. */ type?: string; } export interface FileHandler { /** * A mapping of one or more MIME types to one or more file extensions. e.g. "accept": {"text/csv": ".csv"} or {"text/csv": \[".csv", ".txt"\]}. * * @since Chrome 110 */ accept: {[name: string]: any}; /** * Specifies the url after the origin that is the navigation destination for file handling launches. */ action: string; /** * Description of the file type. */ name: string; /** * Array of ImageResources. Only icons declared at the manifest level are currently supported. The icon for the extension will appear in the "Open" menu. */ icons?: Icon[]; /** * Whether multiple files should be opened in a single client or multiple. Defaults to \`single-client\`, which makes all files available in only one tab. \`multiple-client\` opens a new tab for each file. */ launch_type?: string; } } /** * Use the `chrome.fileSystem` API to create, read, navigate, and write to the user's local file system. With this API, Chrome Apps can read and write to a user-selected location. For example, a text editor app can use the API to read and write local documents. All failures are notified via chrome.runtime.lastError. * * @chrome-permission fileSystem * @chrome-platform-apps * @chrome-disallow-service-workers * @chrome-platform chromeos * @chrome-platform linux * @chrome-platform mac * @chrome-platform win */ export namespace fileSystem { export interface AcceptOption { /** * This is the optional text description for this option. If not present, a description will be automatically generated; typically containing an expanded list of valid extensions (e.g. "text/html" may expand to "\*.html, \*.htm"). */ description?: string; /** * Mime-types to accept, e.g. "image/jpeg" or "audio/\*". One of mimeTypes or extensions must contain at least one valid element. */ mimeTypes?: string[]; /** * Extensions to accept, e.g. "jpg", "gif", "crx". */ extensions?: string[]; } /** * @chrome-enum "openFile" Prompts the user to open an existing file and returns a FileEntry on success. From Chrome 31 onwards, the FileEntry will be writable if the application has the 'write' permission under 'fileSystem'; otherwise, the FileEntry will be read-only. * @chrome-enum "openWritableFile" Prompts the user to open an existing file and returns a writable FileEntry on success. Calls using this type will fail with a runtime error if the application doesn't have the 'write' permission under 'fileSystem'. * @chrome-enum "saveFile" Prompts the user to open an existing file or a new file and returns a writable FileEntry on success. Calls using this type will fail with a runtime error if the application doesn't have the 'write' permission under 'fileSystem'. * @chrome-enum "openDirectory" Prompts the user to open a directory and returns a DirectoryEntry on success. Calls using this type will fail with a runtime error if the application doesn't have the 'directory' permission under 'fileSystem'. If the application has the 'write' permission under 'fileSystem', the returned DirectoryEntry will be writable; otherwise it will be read-only. New in Chrome 31. */ export type ChooseEntryType = "openFile" | "openWritableFile" | "saveFile" | "openDirectory"; export interface ChooseEntryOptions { /** * Type of the prompt to show. The default is 'openFile'. */ type?: ChooseEntryType; /** * The suggested file name that will be presented to the user as the default name to read or write. This is optional. */ suggestedName?: string; /** * The optional list of accept options for this file opener. Each option will be presented as a unique group to the end-user. */ accepts?: AcceptOption[]; /** * Whether to accept all file types, in addition to the options specified in the accepts argument. The default is true. If the accepts field is unset or contains no valid entries, this will always be reset to true. */ acceptsAllTypes?: boolean; /** * Whether to accept multiple files. This is only supported for openFile and openWritableFile. The callback to chooseEntry will be called with a list of entries if this is set to true. Otherwise it will be called with a single Entry. */ acceptsMultiple?: boolean; } /** * @since Chrome 44 */ export interface RequestFileSystemOptions { /** * The ID of the requested volume. */ volumeId: string; /** * Whether the requested file system should be writable. The default is read-only. */ writable?: boolean; } /** * @since Chrome 44 */ export interface Volume { volumeId: string; writable: boolean; } /** * @since Chrome 44 */ export interface VolumeListChangedEvent { volumes: Volume[]; } /** * Called when a list of available volumes is changed. * * @since Chrome 44 */ export const onVolumeListChanged: events.Event<( event: VolumeListChangedEvent, ) => void>; /** * Get the display path of an Entry object. The display path is based on the full path of the file or directory on the local file system, but may be made more readable for display purposes. * * @chrome-returns-extra since Chrome 117 */ export function getDisplayPath( entry: Entry, ): Promise; /** * Get the display path of an Entry object. The display path is based on the full path of the file or directory on the local file system, but may be made more readable for display purposes. */ export function getDisplayPath( entry: Entry, callback?: ( displayPath: string, ) => void, ): void; /** * Get a writable Entry from another Entry. This call will fail with a runtime error if the application does not have the 'write' permission under 'fileSystem'. If entry is a DirectoryEntry, this call will fail if the application does not have the 'directory' permission under 'fileSystem'. */ export function getWritableEntry( entry: Entry, callback: ( entry: Entry, ) => void, ): void; /** * Gets whether this Entry is writable or not. * * @chrome-returns-extra since Chrome 117 */ export function isWritableEntry( entry: Entry, ): Promise; /** * Gets whether this Entry is writable or not. */ export function isWritableEntry( entry: Entry, callback?: ( isWritable: boolean, ) => void, ): void; /** * Ask the user to choose a file or directory. */ export function chooseEntry( options: ChooseEntryOptions, callback: ( entry?: Entry, fileEntries?: FileEntry[], ) => void, ): void; /** * Ask the user to choose a file or directory. */ export function chooseEntry( callback: ( entry?: Entry, fileEntries?: FileEntry[], ) => void, ): void; /** * Returns the file entry with the given id if it can be restored. This call will fail with a runtime error otherwise. */ export function restoreEntry( id: string, callback: ( entry: Entry, ) => void, ): void; /** * Returns whether the app has permission to restore the entry with the given id. * * @chrome-returns-extra since Chrome 117 */ export function isRestorable( id: string, ): Promise; /** * Returns whether the app has permission to restore the entry with the given id. */ export function isRestorable( id: string, callback?: ( isRestorable: boolean, ) => void, ): void; /** * Returns an id that can be passed to restoreEntry to regain access to a given file entry. Only the 500 most recently used entries are retained, where calls to retainEntry and restoreEntry count as use. If the app has the 'retainEntries' permission under 'fileSystem', entries are retained indefinitely. Otherwise, entries are retained only while the app is running and across restarts. */ export function retainEntry( entry: Entry, ): string; /** * Requests access to a file system for a volume represented by `options.volumeId`. If `options.writable` is set to true, then the file system will be writable. Otherwise, it will be read-only. The `writable` option requires the `"fileSystem": {"write"}` permission in the manifest. Available to kiosk apps running in kiosk session only. For manual-launch kiosk mode, a confirmation dialog will be shown on top of the active app window. In case of an error, `fileSystem` will be undefined, and `chrome.runtime.lastError` will be set. * * @chrome-returns-extra since Chrome 117 * @since Chrome 44 */ export function requestFileSystem( options: RequestFileSystemOptions, ): Promise; /** * Requests access to a file system for a volume represented by `options.volumeId`. If `options.writable` is set to true, then the file system will be writable. Otherwise, it will be read-only. The `writable` option requires the `"fileSystem": {"write"}` permission in the manifest. Available to kiosk apps running in kiosk session only. For manual-launch kiosk mode, a confirmation dialog will be shown on top of the active app window. In case of an error, `fileSystem` will be undefined, and `chrome.runtime.lastError` will be set. * * @since Chrome 44 */ export function requestFileSystem( options: RequestFileSystemOptions, callback?: ( fileSystem?: FileSystem, ) => void, ): void; /** * Returns a list of volumes available for `requestFileSystem()`. The `"fileSystem": {"requestFileSystem"}` manifest permission is required. Available to kiosk apps running in the kiosk session only. In case of an error, `volumes` will be undefined, and `chrome.runtime.lastError` will be set. * * @chrome-returns-extra since Chrome 117 * @since Chrome 44 */ export function getVolumeList(): Promise; /** * Returns a list of volumes available for `requestFileSystem()`. The `"fileSystem": {"requestFileSystem"}` manifest permission is required. Available to kiosk apps running in the kiosk session only. In case of an error, `volumes` will be undefined, and `chrome.runtime.lastError` will be set. * * @since Chrome 44 */ export function getVolumeList( callback?: ( volumes?: Volume[], ) => void, ): void; } /** * Use the `chrome.fileSystemProvider` API to create file systems, that can be accessible from the file manager on Chrome OS. * * @chrome-permission fileSystemProvider * @chrome-platform chromeos */ export namespace fileSystemProvider { /** * Error codes used by providing extensions in response to requests as well as in case of errors when calling methods of the API. For success, `"OK"` must be used. */ export type ProviderError = "OK" | "FAILED" | "IN_USE" | "EXISTS" | "NOT_FOUND" | "ACCESS_DENIED" | "TOO_MANY_OPENED" | "NO_MEMORY" | "NO_SPACE" | "NOT_A_DIRECTORY" | "INVALID_OPERATION" | "SECURITY" | "ABORT" | "NOT_A_FILE" | "NOT_EMPTY" | "INVALID_URL" | "IO"; /** * Mode of opening a file. Used by {@link onOpenFileRequested}. */ export type OpenFileMode = "READ" | "WRITE"; /** * Type of a change detected on the observed directory. */ export type ChangeType = "CHANGED" | "DELETED"; /** * List of common actions. `"SHARE"` is for sharing files with others. `"SAVE_FOR_OFFLINE"` for pinning (saving for offline access). `"OFFLINE_NOT_NECESSARY"` for notifying that the file doesn't need to be stored for offline access anymore. Used by {@link onGetActionsRequested} and {@link onExecuteActionRequested}. * * @since Chrome 45 */ export type CommonActionId = "SAVE_FOR_OFFLINE" | "OFFLINE_NOT_NECESSARY" | "SHARE"; /** * @since Chrome 117 */ export interface CloudIdentifier { /** * Identifier for the cloud storage provider (e.g. 'drive.google.com'). */ providerName: string; /** * The provider's identifier for the given file/directory. */ id: string; } /** * @since Chrome 125 */ export interface CloudFileInfo { /** * A tag that represents the version of the file. */ versionTag?: string; } export interface EntryMetadata { /** * True if it is a directory. Must be provided if requested in `options`. */ isDirectory?: boolean; /** * Name of this entry (not full path name). Must not contain '/'. For root it must be empty. Must be provided if requested in `options`. */ name?: string; /** * File size in bytes. Must be provided if requested in `options`. */ size?: number; /** * The last modified time of this entry. Must be provided if requested in `options`. */ modificationTime?: Date; /** * Mime type for the entry. Always optional, but should be provided if requested in `options`. */ mimeType?: string; /** * Thumbnail image as a data URI in either PNG, JPEG or WEBP format, at most 32 KB in size. Optional, but can be provided only when explicitly requested by the {@link onGetMetadataRequested} event. */ thumbnail?: string; /** * Cloud storage representation of this entry. Must be provided if requested in `options` and the file is backed by cloud storage. For local files not backed by cloud storage, it should be undefined when requested. * * @since Chrome 117 */ cloudIdentifier?: CloudIdentifier; /** * Information that identifies a specific file in the underlying cloud file system. Must be provided if requested in `options` and the file is backed by cloud storage. * * @since Chrome 125 */ cloudFileInfo?: CloudFileInfo; } export interface Watcher { /** * The path of the entry being observed. */ entryPath: string; /** * Whether watching should include all child entries recursively. It can be true for directories only. */ recursive: boolean; /** * Tag used by the last notification for the watcher. */ lastTag?: string; } export interface OpenedFile { /** * A request ID to be be used by consecutive read/write and close requests. */ openRequestId: number; /** * The path of the opened file. */ filePath: string; /** * Whether the file was opened for reading or writing. */ mode: OpenFileMode; } export interface FileSystemInfo { /** * The identifier of the file system. */ fileSystemId: string; /** * A human-readable name for the file system. */ displayName: string; /** * Whether the file system supports operations which may change contents of the file system (such as creating, deleting or writing to files). */ writable: boolean; /** * The maximum number of files that can be opened at once. If 0, then not limited. */ openedFilesLimit: number; /** * List of currently opened files. */ openedFiles: OpenedFile[]; /** * Whether the file system supports the `tag` field for observing directories. * * @since Chrome 45 */ supportsNotifyTag?: boolean; /** * List of watchers. * * @since Chrome 45 */ watchers: Watcher[]; } export interface MountOptions { /** * The string indentifier of the file system. Must be unique per each extension. */ fileSystemId: string; /** * A human-readable name for the file system. */ displayName: string; /** * Whether the file system supports operations which may change contents of the file system (such as creating, deleting or writing to files). */ writable?: boolean; /** * The maximum number of files that can be opened at once. If not specified, or 0, then not limited. */ openedFilesLimit?: number; /** * Whether the file system supports the `tag` field for observed directories. * * @since Chrome 45 */ supportsNotifyTag?: boolean; /** * Whether the framework should resume the file system at the next sign-in session. True by default. * * @since Chrome 64 */ persistent?: boolean; } export interface UnmountOptions { /** * The identifier of the file system to be unmounted. */ fileSystemId: string; } export interface UnmountRequestedOptions { /** * The identifier of the file system to be unmounted. */ fileSystemId: string; /** * The unique identifier of this request. */ requestId: number; } export interface GetMetadataRequestedOptions { /** * The identifier of the file system related to this operation. */ fileSystemId: string; /** * The unique identifier of this request. */ requestId: number; /** * The path of the entry to fetch metadata about. */ entryPath: string; /** * Set to `true` if `is_directory` value is requested. * * @since Chrome 49 */ isDirectory: boolean; /** * Set to `true` if `name` value is requested. * * @since Chrome 49 */ name: boolean; /** * Set to `true` if `size` value is requested. * * @since Chrome 49 */ size: boolean; /** * Set to `true` if `modificationTime` value is requested. * * @since Chrome 49 */ modificationTime: boolean; /** * Set to `true` if `mimeType` value is requested. * * @since Chrome 49 */ mimeType: boolean; /** * Set to `true` if `thumbnail` value is requested. */ thumbnail: boolean; /** * Set to `true` if `cloudIdentifier` value is requested. * * @since Chrome 117 */ cloudIdentifier: boolean; /** * Set to `true` if `cloudFileInfo` value is requested. * * @since Chrome 125 */ cloudFileInfo: boolean; } /** * @since Chrome 45 */ export interface GetActionsRequestedOptions { /** * The identifier of the file system related to this operation. */ fileSystemId: string; /** * The unique identifier of this request. */ requestId: number; /** * List of paths of entries for the list of actions. * * @since Chrome 47 */ entryPaths: string[]; } export interface ReadDirectoryRequestedOptions { /** * The identifier of the file system related to this operation. */ fileSystemId: string; /** * The unique identifier of this request. */ requestId: number; /** * The path of the directory which contents are requested. */ directoryPath: string; /** * Set to `true` if `is_directory` value is requested. * * @since Chrome 49 */ isDirectory: boolean; /** * Set to `true` if `name` value is requested. * * @since Chrome 49 */ name: boolean; /** * Set to `true` if `size` value is requested. * * @since Chrome 49 */ size: boolean; /** * Set to `true` if `modificationTime` value is requested. * * @since Chrome 49 */ modificationTime: boolean; /** * Set to `true` if `mimeType` value is requested. * * @since Chrome 49 */ mimeType: boolean; /** * Set to `true` if `thumbnail` value is requested. * * @since Chrome 49 */ thumbnail: boolean; } export interface OpenFileRequestedOptions { /** * The identifier of the file system related to this operation. */ fileSystemId: string; /** * A request ID which will be used by consecutive read/write and close requests. */ requestId: number; /** * The path of the file to be opened. */ filePath: string; /** * Whether the file will be used for reading or writing. */ mode: OpenFileMode; } export interface CloseFileRequestedOptions { /** * The identifier of the file system related to this operation. */ fileSystemId: string; /** * The unique identifier of this request. */ requestId: number; /** * A request ID used to open the file. */ openRequestId: number; } export interface ReadFileRequestedOptions { /** * The identifier of the file system related to this operation. */ fileSystemId: string; /** * The unique identifier of this request. */ requestId: number; /** * A request ID used to open the file. */ openRequestId: number; /** * Position in the file (in bytes) to start reading from. */ offset: number; /** * Number of bytes to be returned. */ length: number; } export interface CreateDirectoryRequestedOptions { /** * The identifier of the file system related to this operation. */ fileSystemId: string; /** * The unique identifier of this request. */ requestId: number; /** * The path of the directory to be created. */ directoryPath: string; /** * Whether the operation is recursive (for directories only). */ recursive: boolean; } export interface DeleteEntryRequestedOptions { /** * The identifier of the file system related to this operation. */ fileSystemId: string; /** * The unique identifier of this request. */ requestId: number; /** * The path of the entry to be deleted. */ entryPath: string; /** * Whether the operation is recursive (for directories only). */ recursive: boolean; } export interface CreateFileRequestedOptions { /** * The identifier of the file system related to this operation. */ fileSystemId: string; /** * The unique identifier of this request. */ requestId: number; /** * The path of the file to be created. */ filePath: string; } export interface CopyEntryRequestedOptions { /** * The identifier of the file system related to this operation. */ fileSystemId: string; /** * The unique identifier of this request. */ requestId: number; /** * The source path of the entry to be copied. */ sourcePath: string; /** * The destination path for the copy operation. */ targetPath: string; } export interface MoveEntryRequestedOptions { /** * The identifier of the file system related to this operation. */ fileSystemId: string; /** * The unique identifier of this request. */ requestId: number; /** * The source path of the entry to be moved into a new place. */ sourcePath: string; /** * The destination path for the copy operation. */ targetPath: string; } export interface TruncateRequestedOptions { /** * The identifier of the file system related to this operation. */ fileSystemId: string; /** * The unique identifier of this request. */ requestId: number; /** * The path of the file to be truncated. */ filePath: string; /** * Number of bytes to be retained after the operation completes. */ length: number; } export interface WriteFileRequestedOptions { /** * The identifier of the file system related to this operation. */ fileSystemId: string; /** * The unique identifier of this request. */ requestId: number; /** * A request ID used to open the file. */ openRequestId: number; /** * Position in the file (in bytes) to start writing the bytes from. */ offset: number; /** * Buffer of bytes to be written to the file. */ data: ArrayBuffer; } export interface AbortRequestedOptions { /** * The identifier of the file system related to this operation. */ fileSystemId: string; /** * The unique identifier of this request. */ requestId: number; /** * An ID of the request to be aborted. */ operationRequestId: number; } export interface AddWatcherRequestedOptions { /** * The identifier of the file system related to this operation. */ fileSystemId: string; /** * The unique identifier of this request. */ requestId: number; /** * The path of the entry to be observed. */ entryPath: string; /** * Whether observing should include all child entries recursively. It can be true for directories only. */ recursive: boolean; } export interface RemoveWatcherRequestedOptions { /** * The identifier of the file system related to this operation. */ fileSystemId: string; /** * The unique identifier of this request. */ requestId: number; /** * The path of the watched entry. */ entryPath: string; /** * Mode of the watcher. */ recursive: boolean; } /** * @since Chrome 45 */ export interface Action { /** * The identifier of the action. Any string or {@link CommonActionId} for common actions. */ id: string; /** * The title of the action. It may be ignored for common actions. */ title?: string; } /** * @since Chrome 45 */ export interface ExecuteActionRequestedOptions { /** * The identifier of the file system related to this operation. */ fileSystemId: string; /** * The unique identifier of this request. */ requestId: number; /** * The set of paths of the entries to be used for the action. * * @since Chrome 47 */ entryPaths: string[]; /** * The identifier of the action to be executed. */ actionId: string; } export interface Change { /** * The path of the changed entry. */ entryPath: string; /** * The type of the change which happened to the entry. */ changeType: ChangeType; /** * Information relating to the file if backed by a cloud file system. * * @since Chrome 125 */ cloudFileInfo?: CloudFileInfo; } export interface NotifyOptions { /** * The identifier of the file system related to this change. */ fileSystemId: string; /** * The path of the observed entry. */ observedPath: string; /** * Mode of the observed entry. */ recursive: boolean; /** * The type of the change which happened to the observed entry. If it is DELETED, then the observed entry will be automatically removed from the list of observed entries. */ changeType: ChangeType; /** * List of changes to entries within the observed directory (including the entry itself) */ changes?: Change[]; /** * Tag for the notification. Required if the file system was mounted with the `supportsNotifyTag` option. Note, that this flag is necessary to provide notifications about changes which changed even when the system was shutdown. */ tag?: string; } /** * @since Chrome 44 */ export interface ConfigureRequestedOptions { /** * The identifier of the file system to be configured. */ fileSystemId: string; /** * The unique identifier of this request. */ requestId: number; } /** * Raised when unmounting for the file system with the `fileSystemId` identifier is requested. In the response, the {@link unmount} API method must be called together with `successCallback`. If unmounting is not possible (eg. due to a pending operation), then `errorCallback` must be called. */ export const onUnmountRequested: events.Event<( options: UnmountRequestedOptions, successCallback: () => void, errorCallback: ( error: ProviderError, ) => void, ) => void>; /** * Raised when metadata of a file or a directory at `entryPath` is requested. The metadata must be returned with the `successCallback` call. In case of an error, `errorCallback` must be called. */ export const onGetMetadataRequested: events.Event<( options: GetMetadataRequestedOptions, successCallback: ( metadata: EntryMetadata, ) => void, errorCallback: ( error: ProviderError, ) => void, ) => void>; /** * Raised when a list of actions for a set of files or directories at `entryPaths` is requested. All of the returned actions must be applicable to each entry. If there are no such actions, an empty array should be returned. The actions must be returned with the `successCallback` call. In case of an error, `errorCallback` must be called. * * @since Chrome 48 */ export const onGetActionsRequested: events.Event<( options: GetActionsRequestedOptions, successCallback: ( actions: Action[], ) => void, errorCallback: ( error: ProviderError, ) => void, ) => void>; /** * Raised when contents of a directory at `directoryPath` are requested. The results must be returned in chunks by calling the `successCallback` several times. In case of an error, `errorCallback` must be called. */ export const onReadDirectoryRequested: events.Event<( options: ReadDirectoryRequestedOptions, successCallback: ( entries: EntryMetadata[], hasMore: boolean, ) => void, errorCallback: ( error: ProviderError, ) => void, ) => void>; /** * Raised when opening a file at `filePath` is requested. If the file does not exist, then the operation must fail. Maximum number of files opened at once can be specified with `MountOptions`. */ export const onOpenFileRequested: events.Event<( options: OpenFileRequestedOptions, successCallback: ( /** * @since Chrome 125 */ metadata?: EntryMetadata, ) => void, errorCallback: ( error: ProviderError, ) => void, ) => void>; /** * Raised when opening a file previously opened with `openRequestId` is requested to be closed. */ export const onCloseFileRequested: events.Event<( options: CloseFileRequestedOptions, successCallback: () => void, errorCallback: ( error: ProviderError, ) => void, ) => void>; /** * Raised when reading contents of a file opened previously with `openRequestId` is requested. The results must be returned in chunks by calling `successCallback` several times. In case of an error, `errorCallback` must be called. */ export const onReadFileRequested: events.Event<( options: ReadFileRequestedOptions, successCallback: ( data: ArrayBuffer, hasMore: boolean, ) => void, errorCallback: ( error: ProviderError, ) => void, ) => void>; /** * Raised when creating a directory is requested. The operation must fail with the EXISTS error if the target directory already exists. If `recursive` is true, then all of the missing directories on the directory path must be created. */ export const onCreateDirectoryRequested: events.Event<( options: CreateDirectoryRequestedOptions, successCallback: () => void, errorCallback: ( error: ProviderError, ) => void, ) => void>; /** * Raised when deleting an entry is requested. If `recursive` is true, and the entry is a directory, then all of the entries inside must be recursively deleted as well. */ export const onDeleteEntryRequested: events.Event<( options: DeleteEntryRequestedOptions, successCallback: () => void, errorCallback: ( error: ProviderError, ) => void, ) => void>; /** * Raised when creating a file is requested. If the file already exists, then `errorCallback` must be called with the `"EXISTS"` error code. */ export const onCreateFileRequested: events.Event<( options: CreateFileRequestedOptions, successCallback: () => void, errorCallback: ( error: ProviderError, ) => void, ) => void>; /** * Raised when copying an entry (recursively if a directory) is requested. If an error occurs, then `errorCallback` must be called. */ export const onCopyEntryRequested: events.Event<( options: CopyEntryRequestedOptions, successCallback: () => void, errorCallback: ( error: ProviderError, ) => void, ) => void>; /** * Raised when moving an entry (recursively if a directory) is requested. If an error occurs, then `errorCallback` must be called. */ export const onMoveEntryRequested: events.Event<( options: MoveEntryRequestedOptions, successCallback: () => void, errorCallback: ( error: ProviderError, ) => void, ) => void>; /** * Raised when truncating a file to a desired length is requested. If an error occurs, then `errorCallback` must be called. */ export const onTruncateRequested: events.Event<( options: TruncateRequestedOptions, successCallback: () => void, errorCallback: ( error: ProviderError, ) => void, ) => void>; /** * Raised when writing contents to a file opened previously with `openRequestId` is requested. */ export const onWriteFileRequested: events.Event<( options: WriteFileRequestedOptions, successCallback: () => void, errorCallback: ( error: ProviderError, ) => void, ) => void>; /** * Raised when aborting an operation with `operationRequestId` is requested. The operation executed with `operationRequestId` must be immediately stopped and `successCallback` of this abort request executed. If aborting fails, then `errorCallback` must be called. Note, that callbacks of the aborted operation must not be called, as they will be ignored. Despite calling `errorCallback`, the request may be forcibly aborted. */ export const onAbortRequested: events.Event<( options: AbortRequestedOptions, successCallback: () => void, errorCallback: ( error: ProviderError, ) => void, ) => void>; /** * Raised when showing a configuration dialog for `fileSystemId` is requested. If it's handled, the `file_system_provider.configurable` manfiest option must be set to true. * * @since Chrome 44 */ export const onConfigureRequested: events.Event<( options: ConfigureRequestedOptions, successCallback: () => void, errorCallback: ( error: ProviderError, ) => void, ) => void>; /** * Raised when showing a dialog for mounting a new file system is requested. If the extension/app is a file handler, then this event shouldn't be handled. Instead `app.runtime.onLaunched` should be handled in order to mount new file systems when a file is opened. For multiple mounts, the `file_system_provider.multiple_mounts` manifest option must be set to true. * * @since Chrome 44 */ export const onMountRequested: events.Event<( successCallback: () => void, errorCallback: ( error: ProviderError, ) => void, ) => void>; /** * Raised when setting a new directory watcher is requested. If an error occurs, then `errorCallback` must be called. * * @since Chrome 45 */ export const onAddWatcherRequested: events.Event<( options: AddWatcherRequestedOptions, successCallback: () => void, errorCallback: ( error: ProviderError, ) => void, ) => void>; /** * Raised when the watcher should be removed. If an error occurs, then `errorCallback` must be called. * * @since Chrome 45 */ export const onRemoveWatcherRequested: events.Event<( options: RemoveWatcherRequestedOptions, successCallback: () => void, errorCallback: ( error: ProviderError, ) => void, ) => void>; /** * Raised when executing an action for a set of files or directories is\\ requested. After the action is completed, `successCallback` must be called. On error, `errorCallback` must be called. * * @since Chrome 48 */ export const onExecuteActionRequested: events.Event<( options: ExecuteActionRequestedOptions, successCallback: () => void, errorCallback: ( error: ProviderError, ) => void, ) => void>; /** * Mounts a file system with the given `fileSystemId` and `displayName`. `displayName` will be shown in the left panel of the Files app. `displayName` can contain any characters including '/', but cannot be an empty string. `displayName` must be descriptive but doesn't have to be unique. The `fileSystemId` must not be an empty string. * * Depending on the type of the file system being mounted, the `source` option must be set appropriately. * * In case of an error, {@link runtime.lastError} will be set with a corresponding error code. * * @chrome-returns-extra since Chrome 96 * @returns A generic result callback to indicate success or failure. */ export function mount( options: MountOptions, ): Promise; /** * Mounts a file system with the given `fileSystemId` and `displayName`. `displayName` will be shown in the left panel of the Files app. `displayName` can contain any characters including '/', but cannot be an empty string. `displayName` must be descriptive but doesn't have to be unique. The `fileSystemId` must not be an empty string. * * Depending on the type of the file system being mounted, the `source` option must be set appropriately. * * In case of an error, {@link runtime.lastError} will be set with a corresponding error code. */ export function mount( options: MountOptions, callback?: () => void, ): void; /** * Unmounts a file system with the given `fileSystemId`. It must be called after {@link onUnmountRequested} is invoked. Also, the providing extension can decide to perform unmounting if not requested (eg. in case of lost connection, or a file error). * * In case of an error, {@link runtime.lastError} will be set with a corresponding error code. * * @chrome-returns-extra since Chrome 96 * @returns A generic result callback to indicate success or failure. */ export function unmount( options: UnmountOptions, ): Promise; /** * Unmounts a file system with the given `fileSystemId`. It must be called after {@link onUnmountRequested} is invoked. Also, the providing extension can decide to perform unmounting if not requested (eg. in case of lost connection, or a file error). * * In case of an error, {@link runtime.lastError} will be set with a corresponding error code. */ export function unmount( options: UnmountOptions, callback?: () => void, ): void; /** * Returns all file systems mounted by the extension. * * @chrome-returns-extra since Chrome 96 * @returns Callback to receive the result of {@link getAll} function. */ export function getAll(): Promise; /** * Returns all file systems mounted by the extension. */ export function getAll( callback?: ( fileSystems: FileSystemInfo[], ) => void, ): void; /** * Returns information about a file system with the passed `fileSystemId`. * * @chrome-returns-extra since Chrome 96 * @returns Callback to receive the result of {@link get} function. */ export function get( fileSystemId: string, ): Promise; /** * Returns information about a file system with the passed `fileSystemId`. */ export function get( fileSystemId: string, callback?: ( fileSystem: FileSystemInfo, ) => void, ): void; /** * Notifies about changes in the watched directory at `observedPath` in `recursive` mode. If the file system is mounted with `supportsNotifyTag`, then `tag` must be provided, and all changes since the last notification always reported, even if the system was shutdown. The last tag can be obtained with {@link getAll}. * * To use, the `file_system_provider.notify` manifest option must be set to true. * * Value of `tag` can be any string which is unique per call, so it's possible to identify the last registered notification. Eg. if the providing extension starts after a reboot, and the last registered notification's tag is equal to "123", then it should call {@link notify} for all changes which happened since the change tagged as "123". It cannot be an empty string. * * Not all providers are able to provide a tag, but if the file system has a changelog, then the tag can be eg. a change number, or a revision number. * * Note that if a parent directory is removed, then all descendant entries are also removed, and if they are watched, then the API must be notified about the fact. Also, if a directory is renamed, then all descendant entries are in fact removed, as there is no entry under their original paths anymore. * * In case of an error, {@link runtime.lastError} will be set will a corresponding error code. * * @chrome-returns-extra since Chrome 96 * @returns A generic result callback to indicate success or failure. * @since Chrome 45 */ export function notify( options: NotifyOptions, ): Promise; /** * Notifies about changes in the watched directory at `observedPath` in `recursive` mode. If the file system is mounted with `supportsNotifyTag`, then `tag` must be provided, and all changes since the last notification always reported, even if the system was shutdown. The last tag can be obtained with {@link getAll}. * * To use, the `file_system_provider.notify` manifest option must be set to true. * * Value of `tag` can be any string which is unique per call, so it's possible to identify the last registered notification. Eg. if the providing extension starts after a reboot, and the last registered notification's tag is equal to "123", then it should call {@link notify} for all changes which happened since the change tagged as "123". It cannot be an empty string. * * Not all providers are able to provide a tag, but if the file system has a changelog, then the tag can be eg. a change number, or a revision number. * * Note that if a parent directory is removed, then all descendant entries are also removed, and if they are watched, then the API must be notified about the fact. Also, if a directory is renamed, then all descendant entries are in fact removed, as there is no entry under their original paths anymore. * * In case of an error, {@link runtime.lastError} will be set will a corresponding error code. * * @since Chrome 45 */ export function notify( options: NotifyOptions, callback?: () => void, ): void; } /** * Use the `chrome.fontSettings` API to manage Chrome's font settings. * * @chrome-permission fontSettings */ export namespace fontSettings { /** * Represents a font name. */ export interface FontName { /** * The font ID. */ fontId: string; /** * The display name of the font. */ displayName: string; } /** * An ISO 15924 script code. The default, or global, script is represented by script code "Zyyy". */ export type ScriptCode = "Afak" | "Arab" | "Armi" | "Armn" | "Avst" | "Bali" | "Bamu" | "Bass" | "Batk" | "Beng" | "Blis" | "Bopo" | "Brah" | "Brai" | "Bugi" | "Buhd" | "Cakm" | "Cans" | "Cari" | "Cham" | "Cher" | "Cirt" | "Copt" | "Cprt" | "Cyrl" | "Cyrs" | "Deva" | "Dsrt" | "Dupl" | "Egyd" | "Egyh" | "Egyp" | "Elba" | "Ethi" | "Geor" | "Geok" | "Glag" | "Goth" | "Gran" | "Grek" | "Gujr" | "Guru" | "Hang" | "Hani" | "Hano" | "Hans" | "Hant" | "Hebr" | "Hluw" | "Hmng" | "Hung" | "Inds" | "Ital" | "Java" | "Jpan" | "Jurc" | "Kali" | "Khar" | "Khmr" | "Khoj" | "Knda" | "Kpel" | "Kthi" | "Lana" | "Laoo" | "Latf" | "Latg" | "Latn" | "Lepc" | "Limb" | "Lina" | "Linb" | "Lisu" | "Loma" | "Lyci" | "Lydi" | "Mand" | "Mani" | "Maya" | "Mend" | "Merc" | "Mero" | "Mlym" | "Moon" | "Mong" | "Mroo" | "Mtei" | "Mymr" | "Narb" | "Nbat" | "Nkgb" | "Nkoo" | "Nshu" | "Ogam" | "Olck" | "Orkh" | "Orya" | "Osma" | "Palm" | "Perm" | "Phag" | "Phli" | "Phlp" | "Phlv" | "Phnx" | "Plrd" | "Prti" | "Rjng" | "Roro" | "Runr" | "Samr" | "Sara" | "Sarb" | "Saur" | "Sgnw" | "Shaw" | "Shrd" | "Sind" | "Sinh" | "Sora" | "Sund" | "Sylo" | "Syrc" | "Syre" | "Syrj" | "Syrn" | "Tagb" | "Takr" | "Tale" | "Talu" | "Taml" | "Tang" | "Tavt" | "Telu" | "Teng" | "Tfng" | "Tglg" | "Thaa" | "Thai" | "Tibt" | "Tirh" | "Ugar" | "Vaii" | "Visp" | "Wara" | "Wole" | "Xpeo" | "Xsux" | "Yiii" | "Zmth" | "Zsym" | "Zyyy"; /** * A CSS generic font family. */ export type GenericFamily = "standard" | "sansserif" | "serif" | "fixed" | "cursive" | "fantasy" | "math"; /** * One of * `not\_controllable`: cannot be controlled by any extension * `controlled\_by\_other\_extensions`: controlled by extensions with higher precedence * `controllable\_by\_this\_extension`: can be controlled by this extension * `controlled\_by\_this\_extension`: controlled by this extension */ export type LevelOfControl = "not_controllable" | "controlled_by_other_extensions" | "controllable_by_this_extension" | "controlled_by_this_extension"; /** * Fired when a font setting changes. */ export const onFontChanged: events.Event<( details: { /** * The font ID. See the description in `getFont`. */ fontId: string, /** * The script code for which the font setting has changed. */ script?: ScriptCode, /** * The generic font family for which the font setting has changed. */ genericFamily: GenericFamily, /** * The level of control this extension has over the setting. */ levelOfControl: LevelOfControl, }, ) => void>; /** * Fired when the default font size setting changes. */ export const onDefaultFontSizeChanged: events.Event<( details: { /** * The font size in pixels. */ pixelSize: number, /** * The level of control this extension has over the setting. */ levelOfControl: LevelOfControl, }, ) => void>; /** * Fired when the default fixed font size setting changes. */ export const onDefaultFixedFontSizeChanged: events.Event<( details: { /** * The font size in pixels. */ pixelSize: number, /** * The level of control this extension has over the setting. */ levelOfControl: LevelOfControl, }, ) => void>; /** * Fired when the minimum font size setting changes. */ export const onMinimumFontSizeChanged: events.Event<( details: { /** * The font size in pixels. */ pixelSize: number, /** * The level of control this extension has over the setting. */ levelOfControl: LevelOfControl, }, ) => void>; /** * Clears the font set by this extension, if any. * * @chrome-returns-extra since Chrome 96 */ export function clearFont( details: { /** * The script for which the font should be cleared. If omitted, the global script font setting is cleared. */ script?: ScriptCode, /** * The generic font family for which the font should be cleared. */ genericFamily: GenericFamily, }, ): Promise; /** * Clears the font set by this extension, if any. */ export function clearFont( details: { /** * The script for which the font should be cleared. If omitted, the global script font setting is cleared. */ script?: ScriptCode, /** * The generic font family for which the font should be cleared. */ genericFamily: GenericFamily, }, callback?: () => void, ): void; /** * Gets the font for a given script and generic font family. * * @chrome-returns-extra since Chrome 96 */ export function getFont( details: { /** * The script for which the font should be retrieved. If omitted, the font setting for the global script (script code "Zyyy") is retrieved. */ script?: ScriptCode, /** * The generic font family for which the font should be retrieved. */ genericFamily: GenericFamily, }, ): Promise<{ /** * The font ID. Rather than the literal font ID preference value, this may be the ID of the font that the system resolves the preference value to. So, `fontId` can differ from the font passed to `setFont`, if, for example, the font is not available on the system. The empty string signifies fallback to the global script font setting. */ fontId: string, /** * The level of control this extension has over the setting. */ levelOfControl: LevelOfControl, }>; /** * Gets the font for a given script and generic font family. */ export function getFont( details: { /** * The script for which the font should be retrieved. If omitted, the font setting for the global script (script code "Zyyy") is retrieved. */ script?: ScriptCode, /** * The generic font family for which the font should be retrieved. */ genericFamily: GenericFamily, }, callback?: ( details: { /** * The font ID. Rather than the literal font ID preference value, this may be the ID of the font that the system resolves the preference value to. So, `fontId` can differ from the font passed to `setFont`, if, for example, the font is not available on the system. The empty string signifies fallback to the global script font setting. */ fontId: string, /** * The level of control this extension has over the setting. */ levelOfControl: LevelOfControl, }, ) => void, ): void; /** * Sets the font for a given script and generic font family. * * @chrome-returns-extra since Chrome 96 */ export function setFont( details: { /** * The script code which the font should be set. If omitted, the font setting for the global script (script code "Zyyy") is set. */ script?: ScriptCode, /** * The generic font family for which the font should be set. */ genericFamily: GenericFamily, /** * The font ID. The empty string means to fallback to the global script font setting. */ fontId: string, }, ): Promise; /** * Sets the font for a given script and generic font family. */ export function setFont( details: { /** * The script code which the font should be set. If omitted, the font setting for the global script (script code "Zyyy") is set. */ script?: ScriptCode, /** * The generic font family for which the font should be set. */ genericFamily: GenericFamily, /** * The font ID. The empty string means to fallback to the global script font setting. */ fontId: string, }, callback?: () => void, ): void; /** * Gets a list of fonts on the system. * * @chrome-returns-extra since Chrome 96 */ export function getFontList(): Promise; /** * Gets a list of fonts on the system. */ export function getFontList( callback?: ( results: FontName[], ) => void, ): void; /** * Clears the default font size set by this extension, if any. * * @chrome-returns-extra since Chrome 96 * @param details This parameter is currently unused. */ export function clearDefaultFontSize( details?: {}, ): Promise; /** * Clears the default font size set by this extension, if any. * * @param details This parameter is currently unused. */ export function clearDefaultFontSize( details?: {}, callback?: () => void, ): void; /** * Gets the default font size. * * @chrome-returns-extra since Chrome 96 * @param details This parameter is currently unused. */ export function getDefaultFontSize( details?: {}, ): Promise<{ /** * The font size in pixels. */ pixelSize: number, /** * The level of control this extension has over the setting. */ levelOfControl: LevelOfControl, }>; /** * Gets the default font size. * * @param details This parameter is currently unused. */ export function getDefaultFontSize( details?: {}, callback?: ( details: { /** * The font size in pixels. */ pixelSize: number, /** * The level of control this extension has over the setting. */ levelOfControl: LevelOfControl, }, ) => void, ): void; /** * Sets the default font size. * * @chrome-returns-extra since Chrome 96 */ export function setDefaultFontSize( details: { /** * The font size in pixels. */ pixelSize: number, }, ): Promise; /** * Sets the default font size. */ export function setDefaultFontSize( details: { /** * The font size in pixels. */ pixelSize: number, }, callback?: () => void, ): void; /** * Clears the default fixed font size set by this extension, if any. * * @chrome-returns-extra since Chrome 96 * @param details This parameter is currently unused. */ export function clearDefaultFixedFontSize( details?: {}, ): Promise; /** * Clears the default fixed font size set by this extension, if any. * * @param details This parameter is currently unused. */ export function clearDefaultFixedFontSize( details?: {}, callback?: () => void, ): void; /** * Gets the default size for fixed width fonts. * * @chrome-returns-extra since Chrome 96 * @param details This parameter is currently unused. */ export function getDefaultFixedFontSize( details?: {}, ): Promise<{ /** * The font size in pixels. */ pixelSize: number, /** * The level of control this extension has over the setting. */ levelOfControl: LevelOfControl, }>; /** * Gets the default size for fixed width fonts. * * @param details This parameter is currently unused. */ export function getDefaultFixedFontSize( details?: {}, callback?: ( details: { /** * The font size in pixels. */ pixelSize: number, /** * The level of control this extension has over the setting. */ levelOfControl: LevelOfControl, }, ) => void, ): void; /** * Sets the default size for fixed width fonts. * * @chrome-returns-extra since Chrome 96 */ export function setDefaultFixedFontSize( details: { /** * The font size in pixels. */ pixelSize: number, }, ): Promise; /** * Sets the default size for fixed width fonts. */ export function setDefaultFixedFontSize( details: { /** * The font size in pixels. */ pixelSize: number, }, callback?: () => void, ): void; /** * Clears the minimum font size set by this extension, if any. * * @chrome-returns-extra since Chrome 96 * @param details This parameter is currently unused. */ export function clearMinimumFontSize( details?: {}, ): Promise; /** * Clears the minimum font size set by this extension, if any. * * @param details This parameter is currently unused. */ export function clearMinimumFontSize( details?: {}, callback?: () => void, ): void; /** * Gets the minimum font size. * * @chrome-returns-extra since Chrome 96 * @param details This parameter is currently unused. */ export function getMinimumFontSize( details?: {}, ): Promise<{ /** * The font size in pixels. */ pixelSize: number, /** * The level of control this extension has over the setting. */ levelOfControl: LevelOfControl, }>; /** * Gets the minimum font size. * * @param details This parameter is currently unused. */ export function getMinimumFontSize( details?: {}, callback?: ( details: { /** * The font size in pixels. */ pixelSize: number, /** * The level of control this extension has over the setting. */ levelOfControl: LevelOfControl, }, ) => void, ): void; /** * Sets the minimum font size. * * @chrome-returns-extra since Chrome 96 */ export function setMinimumFontSize( details: { /** * The font size in pixels. */ pixelSize: number, }, ): Promise; /** * Sets the minimum font size. */ export function setMinimumFontSize( details: { /** * The font size in pixels. */ pixelSize: number, }, callback?: () => void, ): void; } /** * Use `chrome.gcm` to enable apps and extensions to send and receive messages through [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging/) (FCM). * * @chrome-permission gcm */ export namespace gcm { /** * The maximum size (in bytes) of all key/value pairs in a message. */ export const MAX_MESSAGE_SIZE: 4096; /** * Fired when a message is received through FCM. */ export const onMessage: events.Event<( message: { /** * The message data. */ data: {[name: string]: string}, /** * The sender who issued the message. */ from?: string, /** * The collapse key of a message. See the [Non-collapsible and collapsible messages](https://firebase.google.com/docs/cloud-messaging/concept-options#collapsible_and_non-collapsible_messages) for details. */ collapseKey?: string, }, ) => void>; /** * Fired when a FCM server had to delete messages sent by an app server to the application. See [Lifetime of a message](https://firebase.google.com/docs/cloud-messaging/concept-options#lifetime) for details on handling this event. */ export const onMessagesDeleted: events.Event<() => void>; /** * Fired when it was not possible to send a message to the FCM server. */ export const onSendError: events.Event<( error: { /** * The error message describing the problem. */ errorMessage: string, /** * The ID of the message with this error, if error is related to a specific message. */ messageId?: string, /** * Additional details related to the error, when available. */ details: {[name: string]: string}, }, ) => void>; /** * Registers the application with FCM. The registration ID will be returned by the `callback`. If `register` is called again with the same list of `senderIds`, the same registration ID will be returned. * * @chrome-returns-extra since Chrome 116 * @param senderIds A list of server IDs that are allowed to send messages to the application. It should contain at least one and no more than 100 sender IDs. * @returns Resolves when registration completes. */ export function register( senderIds: string[], ): Promise; /** * Registers the application with FCM. The registration ID will be returned by the `callback`. If `register` is called again with the same list of `senderIds`, the same registration ID will be returned. * * @param senderIds A list of server IDs that are allowed to send messages to the application. It should contain at least one and no more than 100 sender IDs. */ export function register( senderIds: string[], /** * @param registrationId A registration ID assigned to the application by the FCM. */ callback?: ( registrationId: string, ) => void, ): void; /** * Unregisters the application from FCM. * * @chrome-returns-extra since Chrome 116 * @returns Resolves after the unregistration completes. Unregistration was successful if the promise does not reject. */ export function unregister(): Promise; /** * Unregisters the application from FCM. */ export function unregister( callback?: () => void, ): void; /** * Sends a message according to its contents. * * @chrome-returns-extra since Chrome 116 * @param message A message to send to the other party via FCM. * @returns Resolves after the message is successfully queued for sending. If an error occurs, the promise will be rejected. */ export function send( message: { /** * The ID of the server to send the message to as assigned by [Google API Console](https://console.cloud.google.com/apis/dashboard). */ destinationId: string, /** * The ID of the message. It must be unique for each message in scope of the applications. See the [Cloud Messaging documentation](https://firebase.google.com/docs/cloud-messaging/js/client) for advice for picking and handling an ID. */ messageId: string, /** * Time-to-live of the message in seconds. If it is not possible to send the message within that time, an onSendError event will be raised. A time-to-live of 0 indicates that the message should be sent immediately or fail if it's not possible. The default value of time-to-live is 86,400 seconds (1 day) and the maximum value is 2,419,200 seconds (28 days). */ timeToLive?: number, /** * Message data to send to the server. Case-insensitive `goog.` and `google`, as well as case-sensitive `collapse_key` are disallowed as key prefixes. Sum of all key/value pairs should not exceed {@link gcm.MAX_MESSAGE_SIZE}. */ data: {[name: string]: string}, }, ): Promise; /** * Sends a message according to its contents. * * @param message A message to send to the other party via FCM. */ export function send( message: { /** * The ID of the server to send the message to as assigned by [Google API Console](https://console.cloud.google.com/apis/dashboard). */ destinationId: string, /** * The ID of the message. It must be unique for each message in scope of the applications. See the [Cloud Messaging documentation](https://firebase.google.com/docs/cloud-messaging/js/client) for advice for picking and handling an ID. */ messageId: string, /** * Time-to-live of the message in seconds. If it is not possible to send the message within that time, an onSendError event will be raised. A time-to-live of 0 indicates that the message should be sent immediately or fail if it's not possible. The default value of time-to-live is 86,400 seconds (1 day) and the maximum value is 2,419,200 seconds (28 days). */ timeToLive?: number, /** * Message data to send to the server. Case-insensitive `goog.` and `google`, as well as case-sensitive `collapse_key` are disallowed as key prefixes. Sum of all key/value pairs should not exceed {@link gcm.MAX_MESSAGE_SIZE}. */ data: {[name: string]: string}, }, /** * @param messageId The ID of the message that the callback was issued for. */ callback?: ( messageId: string, ) => void, ): void; } /** * Use the `chrome.hid` API to interact with connected HID devices. This API provides access to HID operations from within the context of an app. Using this API, apps can function as drivers for hardware devices. Errors generated by this API are reported by setting {@link runtime.lastError} and executing the function's regular callback. The callback's regular parameters will be undefined in this case. * * @chrome-permission hid * @chrome-platform-apps * @chrome-platform chromeos * @chrome-platform linux * @chrome-platform mac * @chrome-platform win */ export namespace hid { export interface HidCollectionInfo { /** * HID usage page identifier. */ usagePage: number; /** * Page-defined usage identifier. */ usage: number; /** * Report IDs which belong to the collection and to its children. */ reportIds: number[]; } export interface HidDeviceInfo { /** * Opaque device ID. */ deviceId: number; /** * Vendor ID. */ vendorId: number; /** * Product ID. */ productId: number; /** * The product name read from the device, if available. * * @since Chrome 46 */ productName: string; /** * The serial number read from the device, if available. * * @since Chrome 46 */ serialNumber: string; /** * Top-level collections from this device's report descriptors. */ collections: HidCollectionInfo[]; /** * Top-level collection's maximum input report size. */ maxInputReportSize: number; /** * Top-level collection's maximum output report size. */ maxOutputReportSize: number; /** * Top-level collection's maximum feature report size. */ maxFeatureReportSize: number; /** * Raw device report descriptor (not available on Windows). */ reportDescriptor: ArrayBuffer; } export interface HidConnectInfo { /** * The opaque ID used to identify this connection in all other functions. */ connectionId: number; } export interface DeviceFilter { /** * Device vendor ID. */ vendorId?: number; /** * Device product ID, only checked only if the vendor ID matches. */ productId?: number; /** * HID usage page identifier. */ usagePage?: number; /** * HID usage identifier, checked only if the HID usage page matches. */ usage?: number; } export interface GetDevicesOptions { /** * @deprecated Equivalent to setting {@link DeviceFilter.vendorId}. */ vendorId?: number; /** * @deprecated Equivalent to setting {@link DeviceFilter.productId}. */ productId?: number; /** * A device matching any given filter will be returned. An empty filter list will return all devices the app has permission for. */ filters?: DeviceFilter[]; } /** * Event generated when a device is added to the system. Events are only broadcast to apps and extensions that have permission to access the device. Permission may have been granted at install time or when the user accepted an optional permission (see {@link permissions.request}). */ export const onDeviceAdded: events.Event<( device: HidDeviceInfo, ) => void>; /** * Event generated when a device is removed from the system. See {@link onDeviceAdded} for which events are delivered. */ export const onDeviceRemoved: events.Event<( deviceId: number, ) => void>; /** * Enumerate connected HID devices. * * @chrome-returns-extra since Chrome 117 * @param options The properties to search for on target devices. */ export function getDevices( options: GetDevicesOptions, ): Promise; /** * Enumerate connected HID devices. * * @param options The properties to search for on target devices. */ export function getDevices( options: GetDevicesOptions, callback?: ( devices: HidDeviceInfo[], ) => void, ): void; /** * Open a connection to an HID device for communication. * * @chrome-returns-extra since Chrome 117 * @param deviceId The {@link HidDeviceInfo.deviceId} of the device to open. */ export function connect( deviceId: number, ): Promise; /** * Open a connection to an HID device for communication. * * @param deviceId The {@link HidDeviceInfo.deviceId} of the device to open. */ export function connect( deviceId: number, callback?: ( connection: HidConnectInfo, ) => void, ): void; /** * Disconnect from a device. Invoking operations on a device after calling this is safe but has no effect. * * @chrome-returns-extra since Chrome 117 * @param connectionId The `connectionId` returned by {@link connect}. */ export function disconnect( connectionId: number, ): Promise; /** * Disconnect from a device. Invoking operations on a device after calling this is safe but has no effect. * * @param connectionId The `connectionId` returned by {@link connect}. */ export function disconnect( connectionId: number, callback?: () => void, ): void; /** * Receive the next input report from the device. * * @param connectionId The `connectionId` returned by {@link connect}. */ export function receive( connectionId: number, /** * @param reportId The report ID or `0` if none. * @param data The report data, the report ID prefix (if present) is removed. */ callback: ( reportId: number, data: ArrayBuffer, ) => void, ): void; /** * Send an output report to the device. * * _Note:_ Do not include a report ID prefix in `data`. It will be added if necessary. * * @chrome-returns-extra since Chrome 117 * @param connectionId The `connectionId` returned by {@link connect}. * @param reportId The report ID to use, or `0` if none. * @param data The report data. */ export function send( connectionId: number, reportId: number, data: ArrayBuffer, ): Promise; /** * Send an output report to the device. * * _Note:_ Do not include a report ID prefix in `data`. It will be added if necessary. * * @param connectionId The `connectionId` returned by {@link connect}. * @param reportId The report ID to use, or `0` if none. * @param data The report data. */ export function send( connectionId: number, reportId: number, data: ArrayBuffer, callback?: () => void, ): void; /** * Request a feature report from the device. * * @chrome-returns-extra since Chrome 117 * @param connectionId The `connectionId` returned by {@link connect}. * @param reportId The report ID, or `0` if none. */ export function receiveFeatureReport( connectionId: number, reportId: number, ): Promise; /** * Request a feature report from the device. * * @param connectionId The `connectionId` returned by {@link connect}. * @param reportId The report ID, or `0` if none. */ export function receiveFeatureReport( connectionId: number, reportId: number, /** * @param data The report data, including a report ID prefix if one is sent by the device. */ callback?: ( data: ArrayBuffer, ) => void, ): void; /** * Send a feature report to the device. * * _Note:_ Do not include a report ID prefix in `data`. It will be added if necessary. * * @chrome-returns-extra since Chrome 117 * @param connectionId The `connectionId` returned by {@link connect}. * @param reportId The report ID to use, or `0` if none. * @param data The report data. */ export function sendFeatureReport( connectionId: number, reportId: number, data: ArrayBuffer, ): Promise; /** * Send a feature report to the device. * * _Note:_ Do not include a report ID prefix in `data`. It will be added if necessary. * * @param connectionId The `connectionId` returned by {@link connect}. * @param reportId The report ID to use, or `0` if none. * @param data The report data. */ export function sendFeatureReport( connectionId: number, reportId: number, data: ArrayBuffer, callback?: () => void, ): void; } /** * Use the `chrome.history` API to interact with the browser's record of visited pages. You can add, remove, and query for URLs in the browser's history. To override the history page with your own version, see [Override Pages](https://developer.chrome.com/extensions/develop/ui/override-chrome-pages). * * @chrome-permission history */ export namespace history { /** * The [transition type](https://developer.chrome.com/docs/extensions/reference/history/#transition_types) for this visit from its referrer. * * @chrome-enum "link" The user arrived at this page by clicking a link on another page. * @chrome-enum "typed" The user arrived at this page by typing the URL in the address bar. This is also used for other explicit navigation actions. * @chrome-enum "auto\_bookmark" The user arrived at this page through a suggestion in the UI, for example, through a menu item. * @chrome-enum "auto\_subframe" The user arrived at this page through subframe navigation that they didn't request, such as through an ad loading in a frame on the previous page. These don't always generate new navigation entries in the back and forward menus. * @chrome-enum "manual\_subframe" The user arrived at this page by selecting something in a subframe. * @chrome-enum "generated" The user arrived at this page by typing in the address bar and selecting an entry that didn't look like a URL, such as a Google Search suggestion. For example, a match might have the URL of a Google Search result page, but it might appear to the user as "Search Google for ...". These are different from typed navigations because the user didn't type or see the destination URL. They're also related to keyword navigations. * @chrome-enum "auto\_toplevel" The page was specified in the command line or is the start page. * @chrome-enum "form\_submit" The user arrived at this page by filling out values in a form and submitting the form. Not all form submissions use this transition type. * @chrome-enum "reload" The user reloaded the page, either by clicking the reload button or by pressing Enter in the address bar. Session restore and Reopen closed tab also use this transition type. * @chrome-enum "keyword" The URL for this page was generated from a replaceable keyword other than the default search provider. * @chrome-enum "keyword\_generated" Corresponds to a visit generated for a keyword. * @since Chrome 44 */ export type TransitionType = "link" | "typed" | "auto_bookmark" | "auto_subframe" | "manual_subframe" | "generated" | "auto_toplevel" | "form_submit" | "reload" | "keyword" | "keyword_generated"; /** * An object encapsulating one result of a history query. */ export interface HistoryItem { /** * The unique identifier for the item. */ id: string; /** * The URL navigated to by a user. */ url?: string; /** * The title of the page when it was last loaded. */ title?: string; /** * When this page was last loaded, represented in milliseconds since the epoch. */ lastVisitTime?: number; /** * The number of times the user has navigated to this page. */ visitCount?: number; /** * The number of times the user has navigated to this page by typing in the address. */ typedCount?: number; } /** * An object encapsulating one visit to a URL. */ export interface VisitItem { /** * The unique identifier for the corresponding {@link history.HistoryItem}. */ id: string; /** * The unique identifier for this visit. */ visitId: string; /** * When this visit occurred, represented in milliseconds since the epoch. */ visitTime?: number; /** * The visit ID of the referrer. */ referringVisitId: string; /** * The [transition type](https://developer.chrome.com/docs/extensions/reference/history/#transition_types) for this visit from its referrer. */ transition: TransitionType; /** * True if the visit originated on this device. False if it was synced from a different device. * * @since Chrome 115 */ isLocal: boolean; } /** * @since Chrome 88 */ export interface UrlDetails { /** * The URL for the operation. It must be in the format as returned from a call to `history.search()`. */ url: string; } /** * Fired when a URL is visited, providing the `HistoryItem` data for that URL. This event fires before the page has loaded. */ export const onVisited: events.Event<( result: HistoryItem, ) => void>; /** * Fired when one or more URLs are removed from history. When all visits have been removed the URL is purged from history. */ export const onVisitRemoved: events.Event<( removed: { /** * True if all history was removed. If true, then urls will be empty. */ allHistory: boolean, urls?: string[], }, ) => void>; /** * Searches the history for the last visit time of each page matching the query. * * @chrome-returns-extra since Chrome 96 */ export function search( query: { /** * A free-text query to the history service. Leave this empty to retrieve all pages. */ text: string, /** * Limit results to those visited after this date, represented in milliseconds since the epoch. If property is not specified, it will default to 24 hours. */ startTime?: number, /** * Limit results to those visited before this date, represented in milliseconds since the epoch. */ endTime?: number, /** * The maximum number of results to retrieve. Defaults to 100. */ maxResults?: number, }, ): Promise; /** * Searches the history for the last visit time of each page matching the query. */ export function search( query: { /** * A free-text query to the history service. Leave this empty to retrieve all pages. */ text: string, /** * Limit results to those visited after this date, represented in milliseconds since the epoch. If property is not specified, it will default to 24 hours. */ startTime?: number, /** * Limit results to those visited before this date, represented in milliseconds since the epoch. */ endTime?: number, /** * The maximum number of results to retrieve. Defaults to 100. */ maxResults?: number, }, callback?: ( results: HistoryItem[], ) => void, ): void; /** * Retrieves information about visits to a URL. * * @chrome-returns-extra since Chrome 96 */ export function getVisits( details: UrlDetails, ): Promise; /** * Retrieves information about visits to a URL. */ export function getVisits( details: UrlDetails, callback?: ( results: VisitItem[], ) => void, ): void; /** * Adds a URL to the history at the current time with a [transition type](https://developer.chrome.com/docs/extensions/reference/history/#transition_types) of "link". * * @chrome-returns-extra since Chrome 96 */ export function addUrl( details: UrlDetails, ): Promise; /** * Adds a URL to the history at the current time with a [transition type](https://developer.chrome.com/docs/extensions/reference/history/#transition_types) of "link". */ export function addUrl( details: UrlDetails, callback?: () => void, ): void; /** * Removes all occurrences of the given URL from the history. * * @chrome-returns-extra since Chrome 96 */ export function deleteUrl( details: UrlDetails, ): Promise; /** * Removes all occurrences of the given URL from the history. */ export function deleteUrl( details: UrlDetails, callback?: () => void, ): void; /** * Removes all items within the specified date range from the history. Pages will not be removed from the history unless all visits fall within the range. * * @chrome-returns-extra since Chrome 96 */ export function deleteRange( range: { /** * Items added to history after this date, represented in milliseconds since the epoch. */ startTime: number, /** * Items added to history before this date, represented in milliseconds since the epoch. */ endTime: number, }, ): Promise; /** * Removes all items within the specified date range from the history. Pages will not be removed from the history unless all visits fall within the range. */ export function deleteRange( range: { /** * Items added to history after this date, represented in milliseconds since the epoch. */ startTime: number, /** * Items added to history before this date, represented in milliseconds since the epoch. */ endTime: number, }, callback?: () => void, ): void; /** * Deletes all items from the history. * * @chrome-returns-extra since Chrome 96 */ export function deleteAll(): Promise; /** * Deletes all items from the history. */ export function deleteAll( callback?: () => void, ): void; } /** * Use the `chrome.i18n` infrastructure to implement internationalization across your whole app or extension. */ export namespace i18n { /** * An ISO language code such as `en` or `fr`. For a complete list of languages supported by this method, see [kLanguageInfoTable](https://src.chromium.org/viewvc/chrome/trunk/src/third_party/cld/languages/internal/languages.cc). For an unknown language, `und` will be returned, which means that \[percentage\] of the text is unknown to CLD * * @since Chrome 47 */ export type LanguageCode = string; /** * Gets the accept-languages of the browser. This is different from the locale used by the browser; to get the locale, use {@link i18n.getUILanguage}. * * @chrome-returns-extra since Chrome 99 */ export function getAcceptLanguages(): Promise; /** * Gets the accept-languages of the browser. This is different from the locale used by the browser; to get the locale, use {@link i18n.getUILanguage}. */ export function getAcceptLanguages( /** * @param languages Array of LanguageCode */ callback?: ( languages: LanguageCode[], ) => void, ): void; /** * Gets the localized string for the specified message. If the message is missing, this method returns an empty string (''). If the format of the `getMessage()` call is wrong — for example, _messageName_ is not a string or the _substitutions_ array has more than 9 elements — this method returns `undefined`. * * @param messageName The name of the message, as specified in the [`messages.json`](https://developer.chrome.com/extensions/how-to/ui/localization-message-formats) file. * @param substitutions Up to 9 substitution strings, if the message requires any. * @returns Message localized for current locale. */ export function getMessage( messageName: string, substitutions?: any, /** * @since Chrome 79 */ options?: { /** * Escape `<` in translation to `<`. This applies only to the message itself, not to the placeholders. Developers might want to use this if the translation is used in an HTML context. Closure Templates used with Closure Compiler generate this automatically. */ escapeLt?: boolean, }, ): string; /** * Gets the browser UI language of the browser. This is different from {@link i18n.getAcceptLanguages} which returns the preferred user languages. * * @returns The browser UI language code such as en-US or fr-FR. */ export function getUILanguage(): string; /** * Detects the language of the provided text using CLD. * * @chrome-returns-extra since Chrome 99 * @param text User input string to be translated. * @since Chrome 47 */ export function detectLanguage( text: string, ): Promise<{ /** * CLD detected language reliability */ isReliable: boolean, /** * array of detectedLanguage */ languages: { language: LanguageCode, /** * The percentage of the detected language */ percentage: number, }[], }>; /** * Detects the language of the provided text using CLD. * * @param text User input string to be translated. * @since Chrome 47 */ export function detectLanguage( text: string, /** * @param result LanguageDetectionResult object that holds detected langugae reliability and array of DetectedLanguage */ callback?: ( result: { /** * CLD detected language reliability */ isReliable: boolean, /** * array of detectedLanguage */ languages: { language: LanguageCode, /** * The percentage of the detected language */ percentage: number, }[], }, ) => void, ): void; } /** * Use the `chrome.identity` API to get OAuth2 access tokens. * * @chrome-permission identity */ export namespace identity { export interface AccountInfo { /** * A unique identifier for the account. This ID will not change for the lifetime of the account. */ id: string; } /** * @chrome-enum "SYNC" Specifies that Sync is enabled for the primary account. * @chrome-enum "ANY" Specifies the existence of a primary account, if any. * @since Chrome 84 */ export type AccountStatus = "SYNC" | "ANY"; /** * @since Chrome 84 */ export interface ProfileDetails { /** * A status of the primary account signed into a profile whose `ProfileUserInfo` should be returned. Defaults to `SYNC` account status. */ accountStatus?: AccountStatus; } export interface ProfileUserInfo { /** * An email address for the user account signed into the current profile. Empty if the user is not signed in or the `identity.email` manifest permission is not specified. */ email: string; /** * A unique identifier for the account. This ID will not change for the lifetime of the account. Empty if the user is not signed in or (in M41+) the `identity.email` manifest permission is not specified. */ id: string; } export interface TokenDetails { /** * Fetching a token may require the user to sign-in to Chrome, or approve the application's requested scopes. If the interactive flag is `true`, `getAuthToken` will prompt the user as necessary. When the flag is `false` or omitted, `getAuthToken` will return failure any time a prompt would be required. */ interactive?: boolean; /** * The account ID whose token should be returned. If not specified, the function will use an account from the Chrome profile: the Sync account if there is one, or otherwise the first Google web account. */ account?: AccountInfo; /** * A list of OAuth2 scopes to request. * * When the `scopes` field is present, it overrides the list of scopes specified in manifest.json. */ scopes?: string[]; /** * The `enableGranularPermissions` flag allows extensions to opt-in early to the granular permissions consent screen, in which requested permissions are granted or denied individually. * * @since Chrome 87 */ enableGranularPermissions?: boolean; } export interface InvalidTokenDetails { /** * The specific token that should be removed from the cache. */ token: string; } export interface WebAuthFlowDetails { /** * The URL that initiates the auth flow. */ url: string; /** * Whether to launch auth flow in interactive mode. * * Since some auth flows may immediately redirect to a result URL, `launchWebAuthFlow` hides its web view until the first navigation either redirects to the final URL, or finishes loading a page meant to be displayed. * * If the `interactive` flag is `true`, the window will be displayed when a page load completes. If the flag is `false` or omitted, `launchWebAuthFlow` will return with an error if the initial navigation does not complete the flow. * * For flows that use JavaScript for redirection, `abortOnLoadForNonInteractive` can be set to `false` in combination with setting `timeoutMsForNonInteractive` to give the page a chance to perform any redirects. */ interactive?: boolean; /** * Whether to terminate `launchWebAuthFlow` for non-interactive requests after the page loads. This parameter does not affect interactive flows. * * When set to `true` (default) the flow will terminate immediately after the page loads. When set to `false`, the flow will only terminate after the `timeoutMsForNonInteractive` passes. This is useful for identity providers that use JavaScript to perform redirections after the page loads. * * @since Chrome 113 */ abortOnLoadForNonInteractive?: boolean; /** * The maximum amount of time, in miliseconds, `launchWebAuthFlow` is allowed to run in non-interactive mode in total. Only has an effect if `interactive` is `false`. * * @since Chrome 113 */ timeoutMsForNonInteractive?: number; } /** * @since Chrome 105 */ export interface GetAuthTokenResult { /** * The specific token associated with the request. */ token?: string; /** * A list of OAuth2 scopes granted to the extension. */ grantedScopes?: string[]; } /** * Fired when signin state changes for an account on the user's profile. */ export const onSignInChanged: events.Event<( account: AccountInfo, signedIn: boolean, ) => void>; /** * Retrieves a list of AccountInfo objects describing the accounts present on the profile. * * `getAccounts` is only supported on dev channel. * * @alpha * @chrome-channel dev */ export function getAccounts(): Promise; /** * Retrieves a list of AccountInfo objects describing the accounts present on the profile. * * `getAccounts` is only supported on dev channel. * * @alpha * @chrome-channel dev */ export function getAccounts( callback?: ( accounts: AccountInfo[], ) => void, ): void; /** * Gets an OAuth2 access token using the client ID and scopes specified in the [`oauth2` section of manifest.json](https://developer.chrome.com/docs/apps/app_identity#update_manifest). * * The Identity API caches access tokens in memory, so it's ok to call `getAuthToken` non-interactively any time a token is required. The token cache automatically handles expiration. * * For a good user experience it is important interactive token requests are initiated by UI in your app explaining what the authorization is for. Failing to do this will cause your users to get authorization requests, or Chrome sign in screens if they are not signed in, with with no context. In particular, do not use `getAuthToken` interactively when your app is first launched. * * Note: When called with a callback, instead of returning an object this function will return the two properties as separate arguments passed to the callback. * * @chrome-returns-extra since Chrome 105 * @param details Token options. * @returns Returns a Promise which resolves with an OAuth2 access token as specified by the manifest, or rejects if there was an error. The `grantedScopes` parameter is populated since Chrome 87. When available, this parameter contains the list of granted scopes corresponding with the returned token. */ export function getAuthToken( details?: TokenDetails, ): Promise; /** * Gets an OAuth2 access token using the client ID and scopes specified in the [`oauth2` section of manifest.json](https://developer.chrome.com/docs/apps/app_identity#update_manifest). * * The Identity API caches access tokens in memory, so it's ok to call `getAuthToken` non-interactively any time a token is required. The token cache automatically handles expiration. * * For a good user experience it is important interactive token requests are initiated by UI in your app explaining what the authorization is for. Failing to do this will cause your users to get authorization requests, or Chrome sign in screens if they are not signed in, with with no context. In particular, do not use `getAuthToken` interactively when your app is first launched. * * Note: When called with a callback, instead of returning an object this function will return the two properties as separate arguments passed to the callback. * * @param details Token options. */ export function getAuthToken( details?: TokenDetails, callback?: ( /** * @since Chrome 105 */ result: GetAuthTokenResult, ) => void, ): void; /** * Retrieves email address and obfuscated gaia id of the user signed into a profile. * * Requires the `identity.email` manifest permission. Otherwise, returns an empty result. * * This API is different from identity.getAccounts in two ways. The information returned is available offline, and it only applies to the primary account for the profile. * * @chrome-returns-extra since Chrome 106 * @param details Profile options. * @returns Returns a Promise which resolves with the `ProfileUserInfo` of the primary Chrome account, or an empty `ProfileUserInfo` if the account with given `details` doesn't exist. */ export function getProfileUserInfo( /** * @since Chrome 84 */ details?: ProfileDetails, ): Promise; /** * Retrieves email address and obfuscated gaia id of the user signed into a profile. * * Requires the `identity.email` manifest permission. Otherwise, returns an empty result. * * This API is different from identity.getAccounts in two ways. The information returned is available offline, and it only applies to the primary account for the profile. * * @param details Profile options. */ export function getProfileUserInfo( /** * @since Chrome 84 */ details?: ProfileDetails, callback?: ( userInfo: ProfileUserInfo, ) => void, ): void; /** * Removes an OAuth2 access token from the Identity API's token cache. * * If an access token is discovered to be invalid, it should be passed to removeCachedAuthToken to remove it from the cache. The app may then retrieve a fresh token with `getAuthToken`. * * @chrome-returns-extra since Chrome 106 * @param details Token information. * @returns Returns a Promise which resolves when the token has been removed from the cache. */ export function removeCachedAuthToken( details: InvalidTokenDetails, ): Promise; /** * Removes an OAuth2 access token from the Identity API's token cache. * * If an access token is discovered to be invalid, it should be passed to removeCachedAuthToken to remove it from the cache. The app may then retrieve a fresh token with `getAuthToken`. * * @param details Token information. */ export function removeCachedAuthToken( details: InvalidTokenDetails, callback?: () => void, ): void; /** * Resets the state of the Identity API: * * * Removes all OAuth2 access tokens from the token cache * * Removes user's account preferences * * De-authorizes the user from all auth flows * * @chrome-returns-extra since Chrome 106 * @returns Returns a Promise which resolves when the state has been cleared. * @since Chrome 87 */ export function clearAllCachedAuthTokens(): Promise; /** * Resets the state of the Identity API: * * * Removes all OAuth2 access tokens from the token cache * * Removes user's account preferences * * De-authorizes the user from all auth flows * * @since Chrome 87 */ export function clearAllCachedAuthTokens( callback?: () => void, ): void; /** * Starts an auth flow at the specified URL. * * This method enables auth flows with non-Google identity providers by launching a web view and navigating it to the first URL in the provider's auth flow. When the provider redirects to a URL matching the pattern `https://.chromiumapp.org/*`, the window will close, and the final redirect URL will be passed to the `callback` function. * * For a good user experience it is important interactive auth flows are initiated by UI in your app explaining what the authorization is for. Failing to do this will cause your users to get authorization requests with no context. In particular, do not launch an interactive auth flow when your app is first launched. * * @chrome-returns-extra since Chrome 106 * @param details WebAuth flow options. * @returns Returns a Promise which resolves with the URL redirected back to your application. */ export function launchWebAuthFlow( details: WebAuthFlowDetails, ): Promise; /** * Starts an auth flow at the specified URL. * * This method enables auth flows with non-Google identity providers by launching a web view and navigating it to the first URL in the provider's auth flow. When the provider redirects to a URL matching the pattern `https://.chromiumapp.org/*`, the window will close, and the final redirect URL will be passed to the `callback` function. * * For a good user experience it is important interactive auth flows are initiated by UI in your app explaining what the authorization is for. Failing to do this will cause your users to get authorization requests with no context. In particular, do not launch an interactive auth flow when your app is first launched. * * @param details WebAuth flow options. */ export function launchWebAuthFlow( details: WebAuthFlowDetails, callback?: ( responseUrl?: string, ) => void, ): void; /** * Generates a redirect URL to be used in `launchWebAuthFlow`. * * The generated URLs match the pattern `https://.chromiumapp.org/*`. * * @param path The path appended to the end of the generated URL. */ export function getRedirectURL( path?: string, ): string; } /** * Use the `chrome.idle` API to detect when the machine's idle state changes. * * @chrome-permission idle */ export namespace idle { /** * @since Chrome 44 */ export type IdleState = "active" | "idle" | "locked"; /** * Fired when the system changes to an active, idle or locked state. The event fires with "locked" if the screen is locked or the screensaver activates, "idle" if the system is unlocked and the user has not generated any input for a specified number of seconds, and "active" when the user generates input on an idle system. */ export const onStateChanged: events.Event<( newState: IdleState, ) => void>; /** * Returns "locked" if the system is locked, "idle" if the user has not generated any input for a specified number of seconds, or "active" otherwise. * * @chrome-returns-extra since Chrome 116 * @param detectionIntervalInSeconds The system is considered idle if detectionIntervalInSeconds seconds have elapsed since the last user input detected. */ export function queryState( detectionIntervalInSeconds: number, ): Promise; /** * Returns "locked" if the system is locked, "idle" if the user has not generated any input for a specified number of seconds, or "active" otherwise. * * @param detectionIntervalInSeconds The system is considered idle if detectionIntervalInSeconds seconds have elapsed since the last user input detected. */ export function queryState( detectionIntervalInSeconds: number, callback?: ( newState: IdleState, ) => void, ): void; /** * Sets the interval, in seconds, used to determine when the system is in an idle state for onStateChanged events. The default interval is 60 seconds. * * @param intervalInSeconds Threshold, in seconds, used to determine when the system is in an idle state. */ export function setDetectionInterval( intervalInSeconds: number, ): void; /** * Gets the time, in seconds, it takes until the screen is locked automatically while idle. Returns a zero duration if the screen is never locked automatically. Currently supported on Chrome OS only. * * @chrome-returns-extra since Chrome 116 * @since Chrome 73 * @chrome-platform chromeos */ export function getAutoLockDelay(): Promise; /** * Gets the time, in seconds, it takes until the screen is locked automatically while idle. Returns a zero duration if the screen is never locked automatically. Currently supported on Chrome OS only. * * @since Chrome 73 * @chrome-platform chromeos */ export function getAutoLockDelay( /** * @param delay Time, in seconds, until the screen is locked automatically while idle. This is zero if the screen never locks automatically. */ callback?: ( delay: number, ) => void, ): void; } /** * Dummy namespace for the incognito manifest key. * * @since Chrome 87 */ export namespace incognito { export type IncognitoMode = "split" | "spanning" | "not_allowed"; } /** * Use the `chrome.input.ime` API to implement a custom IME for Chrome OS. This allows your extension to handle keystrokes, set the composition, and manage the candidate window. * * @chrome-permission input * @chrome-platform chromeos */ export namespace input.ime { /** * @since Chrome 44 */ export type KeyboardEventType = "keyup" | "keydown"; /** * See http://www.w3.org/TR/DOM-Level-3-Events/#events-KeyboardEvent */ export interface KeyboardEvent { /** * One of keyup or keydown. */ type: KeyboardEventType; /** * (Deprecated) The ID of the request. Use the `requestId` param from the `onKeyEvent` event instead. */ requestId?: string; /** * The extension ID of the sender of this keyevent. */ extensionId?: string; /** * Value of the key being pressed */ key: string; /** * Value of the physical key being pressed. The value is not affected by current keyboard layout or modifier state. */ code: string; /** * The deprecated HTML keyCode, which is system- and implementation-dependent numerical code signifying the unmodified identifier associated with the key pressed. */ keyCode?: number; /** * Whether or not the ALT key is pressed. */ altKey?: boolean; /** * Whether or not the ALTGR key is pressed. * * @since Chrome 79 */ altgrKey?: boolean; /** * Whether or not the CTRL key is pressed. */ ctrlKey?: boolean; /** * Whether or not the SHIFT key is pressed. */ shiftKey?: boolean; /** * Whether or not the CAPS\_LOCK is enabled. */ capsLock?: boolean; } /** * Type of value this text field edits, (Text, Number, URL, etc) * * @since Chrome 44 */ export type InputContextType = "text" | "search" | "tel" | "url" | "email" | "number" | "password" | "null"; /** * The auto-capitalize type of the text field. * * @since Chrome 69 */ export type AutoCapitalizeType = "characters" | "words" | "sentences"; /** * Describes an input Context */ export interface InputContext { /** * This is used to specify targets of text field operations. This ID becomes invalid as soon as onBlur is called. */ contextID: number; /** * Type of value this text field edits, (Text, Number, URL, etc) */ type: InputContextType; /** * Whether the text field wants auto-correct. */ autoCorrect: boolean; /** * Whether the text field wants auto-complete. */ autoComplete: boolean; /** * The auto-capitalize type of the text field. * * @since Chrome 69 */ autoCapitalize: AutoCapitalizeType; /** * Whether the text field wants spell-check. */ spellCheck: boolean; /** * Whether text entered into the text field should be used to improve typing suggestions for the user. * * @since Chrome 68 */ shouldDoLearning: boolean; } /** * The type of menu item. Radio buttons between separators are considered grouped. * * @since Chrome 44 */ export type MenuItemStyle = "check" | "radio" | "separator"; /** * A menu item used by an input method to interact with the user from the language menu. */ export interface MenuItem { /** * String that will be passed to callbacks referencing this MenuItem. */ id: string; /** * Text displayed in the menu for this item. */ label?: string; /** * The type of menu item. */ style?: MenuItemStyle; /** * Indicates this item is visible. */ visible?: boolean; /** * Indicates this item should be drawn with a check. */ checked?: boolean; /** * Indicates this item is enabled. */ enabled?: boolean; } /** * The type of the underline to modify this segment. * * @since Chrome 44 */ export type UnderlineStyle = "underline" | "doubleUnderline" | "noUnderline"; /** * Where to display the candidate window. If set to 'cursor', the window follows the cursor. If set to 'composition', the window is locked to the beginning of the composition. * * @since Chrome 44 */ export type WindowPosition = "cursor" | "composition"; /** * The screen type under which the IME is activated. * * @since Chrome 44 */ export type ScreenType = "normal" | "login" | "lock" | "secondary-login"; /** * Which mouse buttons was clicked. * * @since Chrome 44 */ export type MouseButton = "left" | "middle" | "right"; /** * Type of assistive window. * * @since Chrome 85 */ export type AssistiveWindowType = "undo"; /** * Properties of the assistive window. * * @since Chrome 85 */ export interface AssistiveWindowProperties { type: AssistiveWindowType; /** * Sets true to show AssistiveWindow, sets false to hide. */ visible: boolean; /** * Strings for ChromeVox to announce. */ announceString?: string; } /** * ID of buttons in assistive window. * * @since Chrome 85 */ export type AssistiveWindowButton = "undo" | "addToDictionary"; /** * @since Chrome 88 */ export interface MenuParameters { /** * ID of the engine to use. */ engineID: string; /** * MenuItems to add or update. They will be added in the order they exist in the array. */ items: MenuItem[]; } /** * This event is sent when an IME is activated. It signals that the IME will be receiving onKeyPress events. */ export const onActivate: events.Event<( engineID: string, screen: ScreenType, ) => void>; /** * This event is sent when an IME is deactivated. It signals that the IME will no longer be receiving onKeyPress events. */ export const onDeactivated: events.Event<( engineID: string, ) => void>; /** * This event is sent when focus enters a text box. It is sent to all extensions that are listening to this event, and enabled by the user. */ export const onFocus: events.Event<( context: InputContext, ) => void>; /** * This event is sent when focus leaves a text box. It is sent to all extensions that are listening to this event, and enabled by the user. */ export const onBlur: events.Event<( contextID: number, ) => void>; /** * This event is sent when the properties of the current InputContext change, such as the the type. It is sent to all extensions that are listening to this event, and enabled by the user. */ export const onInputContextUpdate: events.Event<( context: InputContext, ) => void>; /** * Fired when a key event is sent from the operating system. The event will be sent to the extension if this extension owns the active IME. The listener function should return true if the event was handled false if it was not. If the event will be evaluated asynchronously, this function must return undefined and the IME must later call keyEventHandled() with the result. */ export const onKeyEvent: events.Event<( /** * @since Chrome 70 */ engineID: string, /** * @since Chrome 70 */ keyData: KeyboardEvent, /** * @since Chrome 79 */ requestId: string, ) => boolean | undefined>; /** * This event is sent if this extension owns the active IME. */ export const onCandidateClicked: events.Event<( engineID: string, candidateID: number, button: MouseButton, ) => void>; /** * Called when the user selects a menu item */ export const onMenuItemActivated: events.Event<( engineID: string, name: string, ) => void>; /** * Called when the editable string around caret is changed or when the caret position is moved. The text length is limited to 100 characters for each back and forth direction. */ export const onSurroundingTextChanged: events.Event<( engineID: string, surroundingInfo: { /** * The text around the cursor. This is only a subset of all text in the input field. */ text: string, /** * The ending position of the selection. This value indicates caret position if there is no selection. */ focus: number, /** * The beginning position of the selection. This value indicates caret position if there is no selection. */ anchor: number, /** * The offset position of `text`. Since `text` only includes a subset of text around the cursor, offset indicates the absolute position of the first character of `text`. * * @since Chrome 46 */ offset: number, }, ) => void>; /** * This event is sent when chrome terminates ongoing text input session. */ export const onReset: events.Event<( engineID: string, ) => void>; /** * This event is sent when a button in an assistive window is clicked. * * @since Chrome 85 */ export const onAssistiveWindowButtonClicked: events.Event<( details: { /** * The ID of the button clicked. */ buttonID: AssistiveWindowButton, /** * The type of the assistive window. */ windowType: AssistiveWindowType, }, ) => void>; /** * Set the current composition. If this extension does not own the active IME, this fails. * * @chrome-returns-extra since Chrome 111 * @returns Resolves when the operation completes with a boolean indicating if the text was accepted or not. On failure, the promise will be rejected. */ export function setComposition( parameters: { /** * ID of the context where the composition text will be set */ contextID: number, /** * Text to set */ text: string, /** * Position in the text that the selection starts at. */ selectionStart?: number, /** * Position in the text that the selection ends at. */ selectionEnd?: number, /** * Position in the text of the cursor. */ cursor: number, /** * List of segments and their associated types. */ segments?: { /** * Index of the character to start this segment at */ start: number, /** * Index of the character to end this segment after. */ end: number, /** * The type of the underline to modify this segment. */ style: UnderlineStyle, }[], }, ): Promise; /** * Set the current composition. If this extension does not own the active IME, this fails. */ export function setComposition( parameters: { /** * ID of the context where the composition text will be set */ contextID: number, /** * Text to set */ text: string, /** * Position in the text that the selection starts at. */ selectionStart?: number, /** * Position in the text that the selection ends at. */ selectionEnd?: number, /** * Position in the text of the cursor. */ cursor: number, /** * List of segments and their associated types. */ segments?: { /** * Index of the character to start this segment at */ start: number, /** * Index of the character to end this segment after. */ end: number, /** * The type of the underline to modify this segment. */ style: UnderlineStyle, }[], }, callback?: ( success: boolean, ) => void, ): void; /** * Clear the current composition. If this extension does not own the active IME, this fails. * * @chrome-returns-extra since Chrome 111 * @returns Resolves when the operation completes with a boolean indicating if the text was accepted or not. On failure, the promise will be rejected. */ export function clearComposition( parameters: { /** * ID of the context where the composition will be cleared */ contextID: number, }, ): Promise; /** * Clear the current composition. If this extension does not own the active IME, this fails. */ export function clearComposition( parameters: { /** * ID of the context where the composition will be cleared */ contextID: number, }, callback?: ( success: boolean, ) => void, ): void; /** * Commits the provided text to the current input. * * @chrome-returns-extra since Chrome 111 * @returns Resolves when the operation completes with a boolean indicating if the text was accepted or not. On failure, the promise will be rejected. */ export function commitText( parameters: { /** * ID of the context where the text will be committed */ contextID: number, /** * The text to commit */ text: string, }, ): Promise; /** * Commits the provided text to the current input. */ export function commitText( parameters: { /** * ID of the context where the text will be committed */ contextID: number, /** * The text to commit */ text: string, }, callback?: ( success: boolean, ) => void, ): void; /** * Sends the key events. This function is expected to be used by virtual keyboards. When key(s) on a virtual keyboard is pressed by a user, this function is used to propagate that event to the system. * * @chrome-returns-extra since Chrome 111 * @returns Resolves when the operation completes. */ export function sendKeyEvents( parameters: { /** * ID of the context where the key events will be sent, or zero to send key events to non-input field. */ contextID: number, /** * Data on the key event. */ keyData: KeyboardEvent[], }, ): Promise; /** * Sends the key events. This function is expected to be used by virtual keyboards. When key(s) on a virtual keyboard is pressed by a user, this function is used to propagate that event to the system. */ export function sendKeyEvents( parameters: { /** * ID of the context where the key events will be sent, or zero to send key events to non-input field. */ contextID: number, /** * Data on the key event. */ keyData: KeyboardEvent[], }, callback?: () => void, ): void; /** * Hides the input view window, which is popped up automatically by system. If the input view window is already hidden, this function will do nothing. */ export function hideInputView(): void; /** * Sets the properties of the candidate window. This fails if the extension doesn't own the active IME * * @chrome-returns-extra since Chrome 111 * @returns Resolves when the operation completes. */ export function setCandidateWindowProperties( parameters: { /** * ID of the engine to set properties on. */ engineID: string, properties: { /** * True to show the Candidate window, false to hide it. */ visible?: boolean, /** * True to show the cursor, false to hide it. */ cursorVisible?: boolean, /** * True if the candidate window should be rendered vertical, false to make it horizontal. */ vertical?: boolean, /** * The number of candidates to display per page. */ pageSize?: number, /** * Text that is shown at the bottom of the candidate window. */ auxiliaryText?: string, /** * True to display the auxiliary text, false to hide it. */ auxiliaryTextVisible?: boolean, /** * The total number of candidates for the candidate window. * * @since Chrome 84 */ totalCandidates?: number, /** * The index of the current chosen candidate out of total candidates. * * @since Chrome 84 */ currentCandidateIndex?: number, /** * Where to display the candidate window. */ windowPosition?: WindowPosition, }, }, ): Promise; /** * Sets the properties of the candidate window. This fails if the extension doesn't own the active IME */ export function setCandidateWindowProperties( parameters: { /** * ID of the engine to set properties on. */ engineID: string, properties: { /** * True to show the Candidate window, false to hide it. */ visible?: boolean, /** * True to show the cursor, false to hide it. */ cursorVisible?: boolean, /** * True if the candidate window should be rendered vertical, false to make it horizontal. */ vertical?: boolean, /** * The number of candidates to display per page. */ pageSize?: number, /** * Text that is shown at the bottom of the candidate window. */ auxiliaryText?: string, /** * True to display the auxiliary text, false to hide it. */ auxiliaryTextVisible?: boolean, /** * The total number of candidates for the candidate window. * * @since Chrome 84 */ totalCandidates?: number, /** * The index of the current chosen candidate out of total candidates. * * @since Chrome 84 */ currentCandidateIndex?: number, /** * Where to display the candidate window. */ windowPosition?: WindowPosition, }, }, callback?: ( success: boolean, ) => void, ): void; /** * Sets the current candidate list. This fails if this extension doesn't own the active IME * * @chrome-returns-extra since Chrome 111 * @returns Resolves when the operation completes. */ export function setCandidates( parameters: { /** * ID of the context that owns the candidate window. */ contextID: number, /** * List of candidates to show in the candidate window */ candidates: { /** * The candidate */ candidate: string, /** * The candidate's id */ id: number, /** * The id to add these candidates under */ parentId?: number, /** * Short string displayed to next to the candidate, often the shortcut key or index */ label?: string, /** * Additional text describing the candidate */ annotation?: string, /** * The usage or detail description of word. */ usage?: { /** * The title string of details description. */ title: string, /** * The body string of detail description. */ body: string, }, }[], }, ): Promise; /** * Sets the current candidate list. This fails if this extension doesn't own the active IME */ export function setCandidates( parameters: { /** * ID of the context that owns the candidate window. */ contextID: number, /** * List of candidates to show in the candidate window */ candidates: { /** * The candidate */ candidate: string, /** * The candidate's id */ id: number, /** * The id to add these candidates under */ parentId?: number, /** * Short string displayed to next to the candidate, often the shortcut key or index */ label?: string, /** * Additional text describing the candidate */ annotation?: string, /** * The usage or detail description of word. */ usage?: { /** * The title string of details description. */ title: string, /** * The body string of detail description. */ body: string, }, }[], }, callback?: ( success: boolean, ) => void, ): void; /** * Set the position of the cursor in the candidate window. This is a no-op if this extension does not own the active IME. * * @chrome-returns-extra since Chrome 111 * @returns Resolves when the operation completes */ export function setCursorPosition( parameters: { /** * ID of the context that owns the candidate window. */ contextID: number, /** * ID of the candidate to select. */ candidateID: number, }, ): Promise; /** * Set the position of the cursor in the candidate window. This is a no-op if this extension does not own the active IME. */ export function setCursorPosition( parameters: { /** * ID of the context that owns the candidate window. */ contextID: number, /** * ID of the candidate to select. */ candidateID: number, }, callback?: ( success: boolean, ) => void, ): void; /** * Shows/Hides an assistive window with the given properties. * * @chrome-returns-extra since Chrome 111 * @returns Resolves when the operation completes. * @since Chrome 85 */ export function setAssistiveWindowProperties( parameters: { /** * ID of the context owning the assistive window. */ contextID: number, /** * Properties of the assistive window. */ properties: AssistiveWindowProperties, }, ): Promise; /** * Shows/Hides an assistive window with the given properties. * * @since Chrome 85 */ export function setAssistiveWindowProperties( parameters: { /** * ID of the context owning the assistive window. */ contextID: number, /** * Properties of the assistive window. */ properties: AssistiveWindowProperties, }, callback?: ( success: boolean, ) => void, ): void; /** * Highlights/Unhighlights a button in an assistive window. * * @chrome-returns-extra since Chrome 111 * @returns Resolves when the operation completes. On failure, the promise will be rejected. * @since Chrome 86 */ export function setAssistiveWindowButtonHighlighted( parameters: { /** * ID of the context owning the assistive window. */ contextID: number, /** * The ID of the button */ buttonID: AssistiveWindowButton, /** * The window type the button belongs to. */ windowType: AssistiveWindowType, /** * The text for the screenreader to announce. */ announceString?: string, /** * Whether the button should be highlighted. */ highlighted: boolean, }, ): Promise; /** * Highlights/Unhighlights a button in an assistive window. * * @since Chrome 86 */ export function setAssistiveWindowButtonHighlighted( parameters: { /** * ID of the context owning the assistive window. */ contextID: number, /** * The ID of the button */ buttonID: AssistiveWindowButton, /** * The window type the button belongs to. */ windowType: AssistiveWindowType, /** * The text for the screenreader to announce. */ announceString?: string, /** * Whether the button should be highlighted. */ highlighted: boolean, }, callback?: () => void, ): void; /** * Adds the provided menu items to the language menu when this IME is active. * * @chrome-returns-extra since Chrome 111 */ export function setMenuItems( parameters: MenuParameters, ): Promise; /** * Adds the provided menu items to the language menu when this IME is active. */ export function setMenuItems( parameters: MenuParameters, callback?: () => void, ): void; /** * Updates the state of the MenuItems specified * * @chrome-returns-extra since Chrome 111 * @returns Resolves when the operation completes */ export function updateMenuItems( parameters: MenuParameters, ): Promise; /** * Updates the state of the MenuItems specified */ export function updateMenuItems( parameters: MenuParameters, callback?: () => void, ): void; /** * Deletes the text around the caret. * * @chrome-returns-extra since Chrome 111 * @returns Resolves when the operation completes. */ export function deleteSurroundingText( parameters: { /** * ID of the engine receiving the event. */ engineID: string, /** * ID of the context where the surrounding text will be deleted. */ contextID: number, /** * The offset from the caret position where deletion will start. This value can be negative. */ offset: number, /** * The number of characters to be deleted */ length: number, }, ): Promise; /** * Deletes the text around the caret. */ export function deleteSurroundingText( parameters: { /** * ID of the engine receiving the event. */ engineID: string, /** * ID of the context where the surrounding text will be deleted. */ contextID: number, /** * The offset from the caret position where deletion will start. This value can be negative. */ offset: number, /** * The number of characters to be deleted */ length: number, }, callback?: () => void, ): void; /** * Indicates that the key event received by onKeyEvent is handled. This should only be called if the onKeyEvent listener is asynchronous. * * @param requestId Request id of the event that was handled. This should come from keyEvent.requestId * @param response True if the keystroke was handled, false if not */ export function keyEventHandled( requestId: string, response: boolean, ): void; } /** * Use `chrome.instanceID` to access the Instance ID service. * * @since Chrome 44 * @chrome-permission gcm */ export namespace instanceID { /** * Fired when all the granted tokens need to be refreshed. */ export const onTokenRefresh: events.Event<() => void>; /** * Retrieves an identifier for the app instance. The instance ID will be returned by the `callback`. The same ID will be returned as long as the application identity has not been revoked or expired. * * @chrome-returns-extra since Chrome 96 * @returns Resolves when the retrieval completes. */ export function getID(): Promise; /** * Retrieves an identifier for the app instance. The instance ID will be returned by the `callback`. The same ID will be returned as long as the application identity has not been revoked or expired. */ export function getID( /** * @param instanceID An Instance ID assigned to the app instance. */ callback?: ( instanceID: string, ) => void, ): void; /** * Retrieves the time when the InstanceID has been generated. The creation time will be returned by the `callback`. * * @chrome-returns-extra since Chrome 96 * @returns Resolves when the retrieval completes. */ export function getCreationTime(): Promise; /** * Retrieves the time when the InstanceID has been generated. The creation time will be returned by the `callback`. */ export function getCreationTime( /** * @param creationTime The time when the Instance ID has been generated, represented in milliseconds since the epoch. */ callback?: ( creationTime: number, ) => void, ): void; /** * Return a token that allows the authorized entity to access the service defined by scope. * * @chrome-returns-extra since Chrome 96 * @param getTokenParams Parameters for getToken. * @returns Resolves when the retrieval completes. */ export function getToken( getTokenParams: { /** * Identifies the entity that is authorized to access resources associated with this Instance ID. It can be a project ID from [Google developer console](https://code.google.com/apis/console). * * @since Chrome 46 */ authorizedEntity: string, /** * Identifies authorized actions that the authorized entity can take. E.g. for sending GCM messages, `GCM` scope should be used. * * @since Chrome 46 */ scope: string, /** * Allows including a small number of string key/value pairs that will be associated with the token and may be used in processing the request. * * @deprecated options are deprecated and will be ignored. * @since Chrome 46 * @chrome-deprecated-since Chrome 89 */ options?: {[name: string]: string}, }, ): Promise; /** * Return a token that allows the authorized entity to access the service defined by scope. * * @param getTokenParams Parameters for getToken. */ export function getToken( getTokenParams: { /** * Identifies the entity that is authorized to access resources associated with this Instance ID. It can be a project ID from [Google developer console](https://code.google.com/apis/console). * * @since Chrome 46 */ authorizedEntity: string, /** * Identifies authorized actions that the authorized entity can take. E.g. for sending GCM messages, `GCM` scope should be used. * * @since Chrome 46 */ scope: string, /** * Allows including a small number of string key/value pairs that will be associated with the token and may be used in processing the request. * * @deprecated options are deprecated and will be ignored. * @since Chrome 46 * @chrome-deprecated-since Chrome 89 */ options?: {[name: string]: string}, }, /** * @param token A token assigned by the requested service. */ callback?: ( token: string, ) => void, ): void; /** * Revokes a granted token. * * @chrome-returns-extra since Chrome 96 * @param deleteTokenParams Parameters for deleteToken. * @returns Resolves when the token deletion completes. The token was revoked successfully if the promise does not reject. */ export function deleteToken( deleteTokenParams: { /** * The authorized entity that is used to obtain the token. * * @since Chrome 46 */ authorizedEntity: string, /** * The scope that is used to obtain the token. * * @since Chrome 46 */ scope: string, }, ): Promise; /** * Revokes a granted token. * * @param deleteTokenParams Parameters for deleteToken. */ export function deleteToken( deleteTokenParams: { /** * The authorized entity that is used to obtain the token. * * @since Chrome 46 */ authorizedEntity: string, /** * The scope that is used to obtain the token. * * @since Chrome 46 */ scope: string, }, callback?: () => void, ): void; /** * Resets the app instance identifier and revokes all tokens associated with it. * * @chrome-returns-extra since Chrome 96 * @returns Resolves when the deletion completes. The instance identifier was revoked successfully if the promise does not reject. */ export function deleteID(): Promise; /** * Resets the app instance identifier and revokes all tokens associated with it. */ export function deleteID( callback?: () => void, ): void; } /** * Use the `chrome.loginState` API to read and monitor the login state. * * @since Chrome 78 * @chrome-permission loginState * @chrome-platform chromeos */ export namespace loginState { /** * @chrome-enum "SIGNIN\_PROFILE" Specifies that the extension is in the signin profile. * @chrome-enum "USER\_PROFILE" Specifies that the extension is in the user profile. * @chrome-enum "LOCK\_PROFILE" Specifies that the extension is in the lock screen profile. */ export type ProfileType = "SIGNIN_PROFILE" | "USER_PROFILE" | "LOCK_PROFILE"; /** * @chrome-enum "UNKNOWN" Specifies that the session state is unknown. * @chrome-enum "IN\_OOBE\_SCREEN" Specifies that the user is in the out-of-box-experience screen. * @chrome-enum "IN\_LOGIN\_SCREEN" Specifies that the user is in the login screen. * @chrome-enum "IN\_SESSION" Specifies that the user is in the session. * @chrome-enum "IN\_LOCK\_SCREEN" Specifies that the user is in the lock screen. * @chrome-enum "IN\_RMA\_SCREEN" Specifies that the device is in RMA mode, finalizing repairs. */ export type SessionState = "UNKNOWN" | "IN_OOBE_SCREEN" | "IN_LOGIN_SCREEN" | "IN_SESSION" | "IN_LOCK_SCREEN" | "IN_RMA_SCREEN"; /** * Dispatched when the session state changes. `sessionState` is the new session state. */ export const onSessionStateChanged: events.Event<( sessionState: SessionState, ) => void>; /** * Gets the type of the profile the extension is in. * * @chrome-returns-extra since Chrome 96 */ export function getProfileType(): Promise; /** * Gets the type of the profile the extension is in. */ export function getProfileType( callback?: ( result: ProfileType, ) => void, ): void; /** * Gets the current session state. * * @chrome-returns-extra since Chrome 96 */ export function getSessionState(): Promise; /** * Gets the current session state. */ export function getSessionState( callback?: ( result: SessionState, ) => void, ): void; } /** * The `chrome.management` API provides ways to manage installed apps and extensions. * * @chrome-permission management */ export namespace management { /** * Information about an icon belonging to an extension, app, or theme. */ export interface IconInfo { /** * A number representing the width and height of the icon. Likely values include (but are not limited to) 128, 48, 24, and 16. */ size: number; /** * The URL for this icon image. To display a grayscale version of the icon (to indicate that an extension is disabled, for example), append `?grayscale=true` to the URL. */ url: string; } /** * These are all possible app launch types. */ export type LaunchType = "OPEN_AS_REGULAR_TAB" | "OPEN_AS_PINNED_TAB" | "OPEN_AS_WINDOW" | "OPEN_FULL_SCREEN"; /** * A reason the item is disabled. * * @since Chrome 44 */ export type ExtensionDisabledReason = "unknown" | "permissions_increase"; /** * The type of this extension, app, or theme. * * @since Chrome 44 */ export type ExtensionType = "extension" | "hosted_app" | "packaged_app" | "legacy_packaged_app" | "theme" | "login_screen_extension"; /** * How the extension was installed. One of * `admin`: The extension was installed because of an administrative policy, * `development`: The extension was loaded unpacked in developer mode, * `normal`: The extension was installed normally via a .crx file, * `sideload`: The extension was installed by other software on the machine, * `other`: The extension was installed by other means. * * @since Chrome 44 */ export type ExtensionInstallType = "admin" | "development" | "normal" | "sideload" | "other"; /** * Information about an installed extension, app, or theme. */ export interface ExtensionInfo { /** * The extension's unique identifier. */ id: string; /** * The name of this extension, app, or theme. */ name: string; /** * A short version of the name of this extension, app, or theme. */ shortName: string; /** * The description of this extension, app, or theme. */ description: string; /** * The [version](https://developer.chrome.com/docs/extensions/reference/manifest/version) of this extension, app, or theme. */ version: string; /** * The [version name](https://developer.chrome.com/docs/extensions/reference/manifest/version#version_name) of this extension, app, or theme if the manifest specified one. * * @since Chrome 50 */ versionName?: string; /** * Whether this extension can be disabled or uninstalled by the user. */ mayDisable: boolean; /** * Whether this extension can be enabled by the user. This is only returned for extensions which are not enabled. * * @since Chrome 62 */ mayEnable?: boolean; /** * Whether it is currently enabled or disabled. */ enabled: boolean; /** * A reason the item is disabled. */ disabledReason?: ExtensionDisabledReason; /** * True if this is an app. * * @deprecated Please use {@link management.ExtensionInfo.type}. */ isApp: boolean; /** * The type of this extension, app, or theme. */ type: ExtensionType; /** * The launch url (only present for apps). */ appLaunchUrl?: string; /** * The URL of the homepage of this extension, app, or theme. */ homepageUrl?: string; /** * The update URL of this extension, app, or theme. */ updateUrl?: string; /** * Whether the extension, app, or theme declares that it supports offline. */ offlineEnabled: boolean; /** * The url for the item's options page, if it has one. */ optionsUrl: string; /** * A list of icon information. Note that this just reflects what was declared in the manifest, and the actual image at that url may be larger or smaller than what was declared, so you might consider using explicit width and height attributes on img tags referencing these images. See the [manifest documentation on icons](https://developer.chrome.com/docs/extensions/reference/manifest/icons) for more details. */ icons?: IconInfo[]; /** * Returns a list of API based permissions. */ permissions: string[]; /** * Returns a list of host based permissions. */ hostPermissions: string[]; /** * How the extension was installed. */ installType: ExtensionInstallType; /** * The app launch type (only present for apps). */ launchType?: LaunchType; /** * The currently available launch types (only present for apps). */ availableLaunchTypes?: LaunchType[]; } /** * Options for how to handle the extension's uninstallation. * * @since Chrome 88 */ export interface UninstallOptions { /** * Whether or not a confirm-uninstall dialog should prompt the user. Defaults to false for self uninstalls. If an extension uninstalls another extension, this parameter is ignored and the dialog is always shown. */ showConfirmDialog?: boolean; } /** * Fired when an app or extension has been installed. */ export const onInstalled: events.Event<( info: ExtensionInfo, ) => void>; /** * Fired when an app or extension has been uninstalled. */ export const onUninstalled: events.Event<( id: string, ) => void>; /** * Fired when an app or extension has been enabled. */ export const onEnabled: events.Event<( info: ExtensionInfo, ) => void>; /** * Fired when an app or extension has been disabled. */ export const onDisabled: events.Event<( info: ExtensionInfo, ) => void>; /** * Returns a list of information about installed extensions and apps. * * @chrome-returns-extra since Chrome 88 */ export function getAll(): Promise; /** * Returns a list of information about installed extensions and apps. */ export function getAll( callback?: ( result: ExtensionInfo[], ) => void, ): void; /** * Returns information about the installed extension, app, or theme that has the given ID. * * @chrome-returns-extra since Chrome 88 * @param id The ID from an item of {@link management.ExtensionInfo}. */ export function get( id: string, ): Promise; /** * Returns information about the installed extension, app, or theme that has the given ID. * * @param id The ID from an item of {@link management.ExtensionInfo}. */ export function get( id: string, callback?: ( result: ExtensionInfo, ) => void, ): void; /** * Returns information about the calling extension, app, or theme. Note: This function can be used without requesting the 'management' permission in the manifest. * * @chrome-returns-extra since Chrome 88 */ export function getSelf(): Promise; /** * Returns information about the calling extension, app, or theme. Note: This function can be used without requesting the 'management' permission in the manifest. */ export function getSelf( callback?: ( result: ExtensionInfo, ) => void, ): void; /** * Returns a list of [permission warnings](https://developer.chrome.com/extensions/develop/concepts/permission-warnings) for the given extension id. * * @chrome-returns-extra since Chrome 88 * @param id The ID of an already installed extension. */ export function getPermissionWarningsById( id: string, ): Promise; /** * Returns a list of [permission warnings](https://developer.chrome.com/extensions/develop/concepts/permission-warnings) for the given extension id. * * @param id The ID of an already installed extension. */ export function getPermissionWarningsById( id: string, callback?: ( permissionWarnings: string[], ) => void, ): void; /** * Returns a list of [permission warnings](https://developer.chrome.com/extensions/develop/concepts/permission-warnings) for the given extension manifest string. Note: This function can be used without requesting the 'management' permission in the manifest. * * @chrome-returns-extra since Chrome 88 * @param manifestStr Extension manifest JSON string. */ export function getPermissionWarningsByManifest( manifestStr: string, ): Promise; /** * Returns a list of [permission warnings](https://developer.chrome.com/extensions/develop/concepts/permission-warnings) for the given extension manifest string. Note: This function can be used without requesting the 'management' permission in the manifest. * * @param manifestStr Extension manifest JSON string. */ export function getPermissionWarningsByManifest( manifestStr: string, callback?: ( permissionWarnings: string[], ) => void, ): void; /** * Enables or disables an app or extension. In most cases this function must be called in the context of a user gesture (e.g. an onclick handler for a button), and may present the user with a native confirmation UI as a way of preventing abuse. * * @chrome-returns-extra since Chrome 88 * @param id This should be the id from an item of {@link management.ExtensionInfo}. * @param enabled Whether this item should be enabled or disabled. */ export function setEnabled( id: string, enabled: boolean, ): Promise; /** * Enables or disables an app or extension. In most cases this function must be called in the context of a user gesture (e.g. an onclick handler for a button), and may present the user with a native confirmation UI as a way of preventing abuse. * * @param id This should be the id from an item of {@link management.ExtensionInfo}. * @param enabled Whether this item should be enabled or disabled. */ export function setEnabled( id: string, enabled: boolean, callback?: () => void, ): void; /** * Uninstalls a currently installed app or extension. Note: This function does not work in managed environments when the user is not allowed to uninstall the specified extension/app. If the uninstall fails (e.g. the user cancels the dialog) the promise will be rejected or the callback will be called with {@link runtime.lastError} set. * * @chrome-returns-extra since Chrome 88 * @param id This should be the id from an item of {@link management.ExtensionInfo}. */ export function uninstall( id: string, options?: UninstallOptions, ): Promise; /** * Uninstalls a currently installed app or extension. Note: This function does not work in managed environments when the user is not allowed to uninstall the specified extension/app. If the uninstall fails (e.g. the user cancels the dialog) the promise will be rejected or the callback will be called with {@link runtime.lastError} set. * * @param id This should be the id from an item of {@link management.ExtensionInfo}. */ export function uninstall( id: string, options?: UninstallOptions, callback?: () => void, ): void; /** * Uninstalls the calling extension. Note: This function can be used without requesting the 'management' permission in the manifest. This function does not work in managed environments when the user is not allowed to uninstall the specified extension/app. * * @chrome-returns-extra since Chrome 88 */ export function uninstallSelf( options?: UninstallOptions, ): Promise; /** * Uninstalls the calling extension. Note: This function can be used without requesting the 'management' permission in the manifest. This function does not work in managed environments when the user is not allowed to uninstall the specified extension/app. */ export function uninstallSelf( options?: UninstallOptions, callback?: () => void, ): void; /** * Launches an application. * * @chrome-returns-extra since Chrome 88 * @param id The extension id of the application. */ export function launchApp( id: string, ): Promise; /** * Launches an application. * * @param id The extension id of the application. */ export function launchApp( id: string, callback?: () => void, ): void; /** * Display options to create shortcuts for an app. On Mac, only packaged app shortcuts can be created. * * @chrome-returns-extra since Chrome 88 * @param id This should be the id from an app item of {@link management.ExtensionInfo}. */ export function createAppShortcut( id: string, ): Promise; /** * Display options to create shortcuts for an app. On Mac, only packaged app shortcuts can be created. * * @param id This should be the id from an app item of {@link management.ExtensionInfo}. */ export function createAppShortcut( id: string, callback?: () => void, ): void; /** * Set the launch type of an app. * * @chrome-returns-extra since Chrome 88 * @param id This should be the id from an app item of {@link management.ExtensionInfo}. * @param launchType The target launch type. Always check and make sure this launch type is in {@link ExtensionInfo.availableLaunchTypes}, because the available launch types vary on different platforms and configurations. */ export function setLaunchType( id: string, launchType: LaunchType, ): Promise; /** * Set the launch type of an app. * * @param id This should be the id from an app item of {@link management.ExtensionInfo}. * @param launchType The target launch type. Always check and make sure this launch type is in {@link ExtensionInfo.availableLaunchTypes}, because the available launch types vary on different platforms and configurations. */ export function setLaunchType( id: string, launchType: LaunchType, callback?: () => void, ): void; /** * Generate an app for a URL. Returns the generated bookmark app. * * @chrome-returns-extra since Chrome 88 * @param url The URL of a web page. The scheme of the URL can only be "http" or "https". * @param title The title of the generated app. */ export function generateAppForLink( url: string, title: string, ): Promise; /** * Generate an app for a URL. Returns the generated bookmark app. * * @param url The URL of a web page. The scheme of the URL can only be "http" or "https". * @param title The title of the generated app. */ export function generateAppForLink( url: string, title: string, callback?: ( result: ExtensionInfo, ) => void, ): void; /** * Launches the replacement\_web\_app specified in the manifest. Prompts the user to install if not already installed. * * @chrome-returns-extra since Chrome 88 * @since Chrome 77 * @chrome-manifest replacement_web_app * @chrome-platform chromeos * @chrome-platform linux * @chrome-platform mac * @chrome-platform win */ export function installReplacementWebApp(): Promise; /** * Launches the replacement\_web\_app specified in the manifest. Prompts the user to install if not already installed. * * @since Chrome 77 * @chrome-manifest replacement_web_app * @chrome-platform chromeos * @chrome-platform linux * @chrome-platform mac * @chrome-platform win */ export function installReplacementWebApp( callback?: () => void, ): void; } /** * Schemas for structured manifest entries */ export namespace manifestTypes { /** * Chrome settings which can be overriden by an extension. */ export interface ChromeSettingsOverrides { /** * New value for the homepage. */ homepage?: string; /** * A search engine */ search_provider?: { /** * Name of the search engine displayed to user. This may only be omitted if _prepopulated\_id_ is set. */ name?: string, /** * Omnibox keyword for the search engine. This may only be omitted if _prepopulated\_id_ is set. */ keyword?: string, /** * An icon URL for the search engine. This may only be omitted if _prepopulated\_id_ is set. */ favicon_url?: string, /** * An search URL used by the search engine. */ search_url: string, /** * Encoding of the search term. This may only be omitted if _prepopulated\_id_ is set. */ encoding?: string, /** * If omitted, this engine does not support suggestions. */ suggest_url?: string, /** * If omitted, this engine does not support image search. */ image_url?: string, /** * The string of post parameters to search\_url */ search_url_post_params?: string, /** * The string of post parameters to suggest\_url */ suggest_url_post_params?: string, /** * The string of post parameters to image\_url */ image_url_post_params?: string, /** * A list of URL patterns that can be used, in addition to `search_url`. */ alternate_urls?: string[], /** * An ID of the built-in search engine in Chrome. */ prepopulated_id?: number, /** * Specifies if the search provider should be default. */ is_default: boolean, }; /** * An array of length one containing a URL to be used as the startup page. */ startup_pages?: string[]; } /** * For `"file"` the source is a file passed via `onLaunched` event. For `"device"` contents are fetched from an external device (eg. plugged via USB), without using `file_handlers`. Finally, for `"network"` source, contents should be fetched via network. * * @since Chrome 44 */ export type FileSystemProviderSource = "file" | "device" | "network"; /** * Represents capabilities of a providing extension. * * @since Chrome 44 */ export interface FileSystemProviderCapabilities { /** * Whether configuring via `onConfigureRequested` is supported. By default: `false`. */ configurable?: boolean; /** * Whether multiple (more than one) mounted file systems are supported. By default: `false`. */ multiple_mounts?: boolean; /** * Whether setting watchers and notifying about changes is supported. By default: `false`. * * @since Chrome 45 */ watchable?: boolean; /** * Source of data for mounted file systems. */ source: FileSystemProviderSource; } } /** * Use the `chrome.mdns` API to discover services over mDNS. This comprises a subset of the features of the NSD spec: http://www.w3.org/TR/discovery-api/ * * @since Chrome 43 * @chrome-permission mdns * @chrome-platform-apps * @chrome-platform chromeos * @chrome-platform linux * @chrome-platform mac * @chrome-platform win */ export namespace mdns { export interface MDnsService { /** * The service name of an mDNS advertised service, .. */ serviceName: string; /** * The host:port pair of an mDNS advertised service. */ serviceHostPort: string; /** * The IP address of an mDNS advertised service. */ ipAddress: string; /** * Metadata for an mDNS advertised service. */ serviceData: string[]; } /** * The maximum number of service instances that will be included in onServiceList events. If more instances are available, they may be truncated from the onServiceList event. * * @since Chrome 44 */ export const MAX_SERVICE_INSTANCES_PER_EVENT: 2048; /** * Event fired to inform clients of the current complete set of known available services. Clients should only need to store the list from the most recent event. The service type that the extension is interested in discovering should be specified as the event filter with the 'serviceType' key. Not specifying an event filter will not start any discovery listeners. */ export const onServiceList: events.Event<( services: MDnsService[], ) => void>; /** * Immediately issues a multicast DNS query for all service types. `callback` is invoked immediately. At a later time, queries will be sent, and any service events will be fired. * * @chrome-returns-extra since Chrome 96 * @since Chrome 45 */ export function forceDiscovery(): Promise; /** * Immediately issues a multicast DNS query for all service types. `callback` is invoked immediately. At a later time, queries will be sent, and any service events will be fired. * * @since Chrome 45 */ export function forceDiscovery( callback?: () => void, ): void; } /** * Use the `chrome.mediaGalleries` API to access media files (audio, images, video) from the user's local disks (with the user's consent). * * @chrome-permission mediaGalleries * @chrome-platform-apps * @chrome-platform chromeos */ export namespace mediaGalleries { /** * @chrome-enum "contents\_changed" The contents of the gallery have changed. * @chrome-enum "watch\_dropped" The watch has been dropped because the device has been detached, the gallery permission has been removed, or any other reason. */ export type GalleryChangeType = "contents_changed" | "watch_dropped"; /** * @chrome-enum "no" Do not act interactively. * @chrome-enum "yes" Ask the user to manage permitted media galleries. * @chrome-enum "if\_needed" Ask the user to manage permitted galleries only if the return set would otherwise be empty. */ export type GetMediaFileSystemsInteractivity = "no" | "yes" | "if_needed"; /** * @chrome-enum "all" Retrieve the mime type, metadata tags, and attached images. * @chrome-enum "mimeTypeAndTags" Retrieve only the mime type and the metadata tags. * @chrome-enum "mimeTypeOnly" Retrieve only the mime type. */ export type GetMetadataType = "all" | "mimeTypeAndTags" | "mimeTypeOnly"; export interface GalleryChangeDetails { /** * Type of change event. */ type: GalleryChangeType; /** * Identifies the modified gallery. */ galleryId: string; } export interface MediaFileSystemsDetails { /** * Whether to prompt the user for permission to additional media galleries before returning the permitted set. Default is silent. If the value 'yes' is passed, or if the application has not been granted access to any media galleries and the value 'if\_needed' is passed, then the media gallery configuration dialog will be displayed. */ interactive?: GetMediaFileSystemsInteractivity; } export interface MediaMetadataOptions { /** * Specifies which subset of the metadata to retrieve. Defaults to 'all' if the option is omitted. */ metadataType?: GetMetadataType; } export interface MediaFileSystemMetadata { /** * The name of the file system. */ name: string; /** * A unique and persistent id for the media gallery. */ galleryId: string; /** * If the media gallery is on a removable device, a unique id for the device while the device is online. */ deviceId?: string; /** * True if the media gallery is on a removable device. */ isRemovable: boolean; /** * True if the device the media gallery is on was detected as a media device. i.e. a PTP or MTP device, or a DCIM directory is present. */ isMediaDevice: boolean; /** * True if the device is currently available. */ isAvailable: boolean; } export interface StreamInfo { /** * Describes format of container or codec of stream, i.e. "mp3", "h264". */ type: string; /** * An unfiltered string->string dictionary of tags for the stream. */ tags: {[name: string]: any}; } export interface MediaMetadata { /** * The browser sniffed mime type. */ mimeType: string; /** * Defined for video. In pixels. */ height?: number; width?: number; /** * Defined for audio and video. In seconds. */ duration?: number; /** * Defined for video. In degrees. */ rotation?: number; /** * Defined for audio and video. */ album?: string; artist?: string; comment?: string; copyright?: string; disc?: number; genre?: string; language?: string; title?: string; track?: number; /** * All the metadata in the media file. For formats with multiple streams, stream order will be preserved. Container metadata is the first element. */ rawTags: StreamInfo[]; /** * The images embedded in the media file's metadata. This is most often used for album art or video thumbnails. */ attachedImages: Blob[]; } export interface AddGalleryWatchResult { galleryId: string; success: boolean; } /** * Fired when a media gallery is changed or a gallery watch is dropped. */ export const onGalleryChanged: events.Event<( details: GalleryChangeDetails, ) => void>; /** * Get the media galleries configured in this user agent. If none are configured or available, the callback will receive an empty array. * * @chrome-returns-extra since Chrome 116 */ export function getMediaFileSystems( details?: MediaFileSystemsDetails, ): Promise; /** * Get the media galleries configured in this user agent. If none are configured or available, the callback will receive an empty array. */ export function getMediaFileSystems( details?: MediaFileSystemsDetails, callback?: ( mediaFileSystems: DOMFileSystem[], ) => void, ): void; /** * Present a directory picker to the user and add the selected directory as a gallery. If the user cancels the picker, selectedFileSystemName will be empty. A user gesture is required for the dialog to display. Without a user gesture, the callback will run as though the user canceled. */ export function addUserSelectedFolder( callback: ( mediaFileSystems: DOMFileSystem[], selectedFileSystemName: string, ) => void, ): void; /** * Get metadata about a specific media file system. */ export function getMediaFileSystemMetadata( mediaFileSystem: DOMFileSystem, ): MediaFileSystemMetadata | undefined; /** * Gets the media-specific metadata for a media file. This should work for files in media galleries as well as other DOM filesystems. * * @chrome-returns-extra since Chrome 116 */ export function getMetadata( mediaFile: Blob, options?: MediaMetadataOptions, ): Promise; /** * Gets the media-specific metadata for a media file. This should work for files in media galleries as well as other DOM filesystems. */ export function getMetadata( mediaFile: Blob, options?: MediaMetadataOptions, callback?: ( metadata: MediaMetadata, ) => void, ): void; /** * Adds a gallery watch for the gallery with the specified gallery ID. The given callback is then fired with a success or failure result. * * @chrome-returns-extra since Chrome 116 */ export function addGalleryWatch( galleryId: string, ): Promise; /** * Adds a gallery watch for the gallery with the specified gallery ID. The given callback is then fired with a success or failure result. */ export function addGalleryWatch( galleryId: string, callback?: ( result: AddGalleryWatchResult, ) => void, ): void; /** * Removes a gallery watch for the gallery with the specified gallery ID. */ export function removeGalleryWatch( galleryId: string, ): void; } /** * The `chrome.networking.onc` API is used for configuring network connections (Cellular, Ethernet, VPN or WiFi). This API is available in auto-launched Chrome OS kiosk sessions. * * Network connection configurations are specified following [Open Network Configuration (ONC)](https://chromium.googlesource.com/chromium/src/+/main/components/onc/docs/onc_spec.md) specification. * * **NOTE**: Most dictionary properties and enum values use UpperCamelCase to match the ONC specification instead of the JavaScript lowerCamelCase convention. * * @since Chrome 59 * @chrome-permission networking.onc * @chrome-platform-apps * @chrome-platform chromeos */ export namespace networking.onc { export type ActivationStateType = "Activated" | "Activating" | "NotActivated" | "PartiallyActivated"; export type CaptivePortalStatus = "Unknown" | "Offline" | "Online" | "Portal" | "ProxyAuthRequired"; export type ClientCertificateType = "Ref" | "Pattern"; export type ConnectionStateType = "Connected" | "Connecting" | "NotConnected"; /** * @chrome-enum "Uninitialized" Device is available but not initialized. * @chrome-enum "Disabled" Device is initialized but not enabled. * @chrome-enum "Enabling" Enabled state has been requested but has not completed. * @chrome-enum "Enabled" Device is enabled. * @chrome-enum "Prohibited" Device is prohibited. */ export type DeviceStateType = "Uninitialized" | "Disabled" | "Enabling" | "Enabled" | "Prohibited"; export type IPConfigType = "DHCP" | "Static"; export type NetworkType = "All" | "Cellular" | "Ethernet" | "Tether" | "VPN" | "Wireless" | "WiFi"; export type ProxySettingsType = "Direct" | "Manual" | "PAC" | "WPAD"; export interface ManagedBoolean { /** * The active value currently used by the network configuration manager (e.g. Shill). */ Active?: boolean; /** * The source from which the effective property value was determined. */ Effective?: string; /** * The property value provided by the user policy. */ UserPolicy?: boolean; /** * The property value provided by the device policy. */ DevicePolicy?: boolean; /** * The property value set by the logged in user. Only provided if `UserEditable` is `true`. */ UserSetting?: boolean; /** * The value set for all users of the device. Only provided if `DeviceEditiable` is `true`. */ SharedSetting?: boolean; /** * Whether a UserPolicy for the property exists and allows the property to be edited (i.e. the policy set recommended property value). Defaults to `false`. */ UserEditable?: boolean; /** * Whether a DevicePolicy for the property exists and allows the property to be edited (i.e. the policy set recommended property value). Defaults to `false`. */ DeviceEditable?: boolean; } export interface ManagedLong { /** * The active value currently used by the network configuration manager (e.g. Shill). */ Active?: number; /** * The source from which the effective property value was determined. */ Effective?: string; /** * The property value provided by the user policy. */ UserPolicy?: number; /** * The property value provided by the device policy. */ DevicePolicy?: number; /** * The property value set by the logged in user. Only provided if `UserEditable` is `true`. */ UserSetting?: number; /** * The value set for all users of the device. Only provided if `DeviceEditiable` is `true`. */ SharedSetting?: number; /** * Whether a UserPolicy for the property exists and allows the property to be edited (i.e. the policy set recommended property value). Defaults to `false`. */ UserEditable?: boolean; /** * Whether a DevicePolicy for the property exists and allows the property to be edited (i.e. the policy set recommended property value). Defaults to `false`. */ DeviceEditable?: boolean; } export interface ManagedDOMString { /** * The active value currently used by the network configuration manager (e.g. Shill). */ Active?: string; /** * The source from which the effective property value was determined. */ Effective?: string; /** * The property value provided by the user policy. */ UserPolicy?: string; /** * The property value provided by the device policy. */ DevicePolicy?: string; /** * The property value set by the logged in user. Only provided if `UserEditable` is `true`. */ UserSetting?: string; /** * The value set for all users of the device. Only provided if `DeviceEditiable` is `true`. */ SharedSetting?: string; /** * Whether a UserPolicy for the property exists and allows the property to be edited (i.e. the policy set recommended property value). Defaults to `false`. */ UserEditable?: boolean; /** * Whether a DevicePolicy for the property exists and allows the property to be edited (i.e. the policy set recommended property value). Defaults to `false`. */ DeviceEditable?: boolean; } export interface ManagedDOMStringList { /** * The active value currently used by the network configuration manager (e.g. Shill). */ Active?: string[]; /** * The source from which the effective property value was determined. */ Effective?: string; /** * The property value provided by the user policy. */ UserPolicy?: string[]; /** * The property value provided by the device policy. */ DevicePolicy?: string[]; /** * The property value set by the logged in user. Only provided if `UserEditable` is `true`. */ UserSetting?: string[]; /** * The value set for all users of the device. Only provided if `DeviceEditiable` is `true`. */ SharedSetting?: string[]; /** * Whether a UserPolicy for the property exists and allows the property to be edited (i.e. the policy set recommended property value). Defaults to `false`. */ UserEditable?: boolean; /** * Whether a DevicePolicy for the property exists and allows the property to be edited (i.e. the policy set recommended property value). Defaults to `false`. */ DeviceEditable?: boolean; } export interface ManagedIPConfigType { /** * The active value currently used by the network configuration manager (e.g. Shill). */ Active?: IPConfigType; /** * The source from which the effective property value was determined. */ Effective?: string; /** * The property value provided by the user policy. */ UserPolicy?: IPConfigType; /** * The property value provided by the device policy. */ DevicePolicy?: IPConfigType; /** * The property value set by the logged in user. Only provided if `UserEditable` is `true`. */ UserSetting?: IPConfigType; /** * The value set for all users of the device. Only provided if `DeviceEditiable` is `true`. */ SharedSetting?: IPConfigType; /** * Whether a UserPolicy for the property exists and allows the property to be edited (i.e. the policy set recommended property value). Defaults to `false`. */ UserEditable?: boolean; /** * Whether a DevicePolicy for the property exists and allows the property to be edited (i.e. the policy set recommended property value). Defaults to `false`. */ DeviceEditable?: boolean; } export interface ManagedProxySettingsType { /** * The active value currently used by the network configuration manager (e.g. Shill). */ Active?: ProxySettingsType; /** * The source from which the effective property value was determined. */ Effective?: string; /** * The property value provided by the user policy. */ UserPolicy?: ProxySettingsType; /** * The property value provided by the device policy. */ DevicePolicy?: ProxySettingsType; /** * The property value set by the logged in user. Only provided if `UserEditable` is `true`. */ UserSetting?: ProxySettingsType; /** * The value set for all users of the device. Only provided if `DeviceEditiable` is `true`. */ SharedSetting?: ProxySettingsType; /** * Whether a UserPolicy for the property exists and allows the property to be edited (i.e. the policy set recommended property value). Defaults to `false`. */ UserEditable?: boolean; /** * Whether a DevicePolicy for the property exists and allows the property to be edited (i.e. the policy set recommended property value). Defaults to `false`. */ DeviceEditable?: boolean; } export interface CellularProviderProperties { /** * The operator name. */ Name: string; /** * Cellular network ID as a simple concatenation of the network's MCC (Mobile Country Code) and MNC (Mobile Network Code). */ Code: string; /** * The two-letter country code. */ Country?: string; } export interface IssuerSubjectPattern { /** * If set, the value against which to match the certificate subject's common name. */ CommonName?: string; /** * If set, the value against which to match the certificate subject's common location. */ Locality?: string; /** * If set, the value against which to match the certificate subject's organizations. At least one organization should match the value. */ Organization?: string; /** * If set, the value against which to match the certificate subject's organizational units. At least one organizational unit should match the value. */ OrganizationalUnit?: string; } export interface CertificatePattern { /** * List of URIs to which the user can be directed in case no certificates that match this pattern are found. */ EnrollmentURI?: string[]; /** * If set, pattern against which X.509 issuer settings should be matched. */ Issuer?: IssuerSubjectPattern; /** * List of certificate issuer CA certificates. A certificate must be signed by one of them in order to match this pattern. */ IssuerCARef?: string[]; /** * If set, pattern against which X.509 subject settings should be matched. */ Subject?: IssuerSubjectPattern; } export interface EAPProperties { AnonymousIdentity?: string; ClientCertPattern?: CertificatePattern; /** * @since Chrome 60 */ ClientCertPKCS11Id?: string; /** * @since Chrome 93 */ ClientCertProvisioningProfileId?: string; ClientCertRef?: string; ClientCertType: ClientCertificateType; Identity?: string; Inner?: string; /** * The outer EAP type. Required by ONC, but may not be provided when translating from Shill. */ Outer?: string; Password?: string; SaveCredentials?: boolean; ServerCAPEMs?: string[]; ServerCARefs?: string[]; /** * @since Chrome 60 */ SubjectMatch?: ManagedDOMString; UseProactiveKeyCaching?: boolean; UseSystemCAs?: boolean; } export interface FoundNetworkProperties { /** * Network availability. */ Status: string; /** * Network ID. */ NetworkId: string; /** * Access technology used by the network. */ Technology: string; /** * The network operator's short-format name. */ ShortName?: string; /** * The network operator's long-format name. */ LongName?: string; } export interface IPConfigProperties { /** * Gateway address used for the IP configuration. */ Gateway?: string; /** * The IP address for a connection. Can be IPv4 or IPv6 address, depending on value of `Type`. */ IPAddress?: string; /** * Array of IP blocks in CIDR notation, see onc\_spec.md for details. * * @since Chrome 76 */ ExcludedRoutes?: string[]; /** * Array of IP blocks in CIDR notation, see onc\_spec.md for details. * * @since Chrome 76 */ IncludedRoutes?: string[]; /** * Array of addresses used for name servers. */ NameServers?: string[]; /** * Array of strings for name resolution, see onc\_spec.md for details. * * @since Chrome 76 */ SearchDomains?: string[]; /** * The routing prefix. */ RoutingPrefix?: number; /** * The IP configuration type. Can be `IPv4` or `IPv6`. */ Type?: string; /** * The URL for WEb Proxy Auto-Discovery, as reported over DHCP. */ WebProxyAutoDiscoveryUrl?: string; } export interface ManagedIPConfigProperties { /** * See {@link IPConfigProperties.Gateway}. */ Gateway?: ManagedDOMString; /** * See {@link IPConfigProperties.IPAddress}. */ IPAddress?: ManagedDOMString; /** * See {@link IPConfigProperties.NameServers}. */ NameServers?: ManagedDOMStringList; /** * See {@link IPConfigProperties.RoutingPrefix}. */ RoutingPrefix?: ManagedLong; /** * See {@link IPConfigProperties.Type}. */ Type?: ManagedDOMString; /** * See {@link IPConfigProperties.WebProxyAutoDiscoveryUrl}. */ WebProxyAutoDiscoveryUrl?: ManagedDOMString; } export interface PaymentPortal { /** * The HTTP method to use for the payment portal. */ Method: string; /** * The post data to send to the payment portal. Ignored unless `Method` is `POST`. */ PostData?: string; /** * The payment portal URL. */ Url?: string; } export interface ProxyLocation { /** * The proxy IP address host. */ Host: string; /** * The port to use for the proxy. */ Port: number; } export interface ManagedProxyLocation { /** * See {@link ProxyLocation.Host}. */ Host: ManagedDOMString; /** * See {@link ProxyLocation.Port}. */ Port: ManagedLong; } export interface ManualProxySettings { /** * Settings for HTTP proxy. */ HTTPProxy?: ProxyLocation; /** * Settings for secure HTTP proxy. */ SecureHTTPProxy?: ProxyLocation; /** * Settings for FTP proxy. */ FTPProxy?: ProxyLocation; /** * Settings for SOCKS proxy. */ SOCKS?: ProxyLocation; } export interface ManagedManualProxySettings { /** * See {@link ManualProxySettings.HTTPProxy}. */ HTTPProxy?: ManagedProxyLocation; /** * See {@link ManualProxySettings.SecureHTTPProxy}. */ SecureHTTPProxy?: ManagedProxyLocation; /** * See {@link ManualProxySettings.FTPProxy}. */ FTPProxy?: ManagedProxyLocation; /** * See {@link ManualProxySettings.SOCKS}. */ SOCKS?: ManagedProxyLocation; } export interface ProxySettings { /** * The type of proxy settings. */ Type: ProxySettingsType; /** * Manual proxy settings - used only for `Manual` proxy settings. */ Manual?: ManualProxySettings; /** * Domains and hosts for which manual proxy settings are excluded. */ ExcludeDomains?: string[]; /** * URL for proxy auto-configuration file. */ PAC?: string; } export interface ManagedProxySettings { /** * See {@link ProxySettings.Type}. */ Type: ManagedProxySettingsType; /** * See {@link ProxySettings.Manual}. */ Manual?: ManagedManualProxySettings; /** * See {@link ProxySettings.ExcludeDomains}. */ ExcludeDomains?: ManagedDOMStringList; /** * See {@link ProxySettings.PAC}. */ PAC?: ManagedDOMString; } export interface SIMLockStatus { /** * The status of SIM lock - possible values are `'sim-pin'`, `'sim-puk'` and `''`. */ LockType: string; /** * Whether SIM lock is enabled. */ LockEnabled: boolean; /** * Number of PIN lock tries allowed before PUK is required to unlock the SIM. */ RetriesLeft?: number; } export interface ThirdPartyVPNProperties { /** * ID of the third-party VPN provider extension. */ ExtensionID: string; /** * The VPN provider name. */ ProviderName?: string; } export interface ManagedThirdPartyVPNProperties { /** * See {@link ThirdPartyVPNProperties.ExtensionID}. */ ExtensionID: ManagedDOMString; /** * See {@link ThirdPartyVPNProperties.ProviderName}. */ ProviderName?: string; } export interface CellularProperties { /** * Whether the cellular network should be connected automatically (when in range). */ AutoConnect?: boolean; /** * The cellular network activation type. */ ActivationType?: string; /** * Carrier account activation state. */ ActivationState?: ActivationStateType; /** * Whether roaming is allowed for the network. */ AllowRoaming?: boolean; /** * Cellular device technology family - `CDMA` or `GSM`. */ Family?: string; /** * The firmware revision loaded in the cellular modem. */ FirmwareRevision?: string; /** * The list of networks found during the most recent network scan. */ FoundNetworks?: FoundNetworkProperties[]; /** * The cellular modem hardware revision. */ HardwareRevision?: string; /** * Information about the operator that issued the SIM card currently installed in the modem. */ HomeProvider?: CellularProviderProperties; /** * The cellular modem manufacturer. */ Manufacturer?: string; /** * The cellular modem model ID. */ ModelID?: string; /** * If the modem is registered on a network, the network technology currently in use. */ NetworkTechnology?: string; /** * Online payment portal a user can use to sign-up for or modify a mobile data plan. */ PaymentPortal?: PaymentPortal; /** * The roaming state of the cellular modem on the current network. */ RoamingState?: string; /** * True when a cellular network scan is in progress. * * @since Chrome 63 */ Scanning?: boolean; /** * Information about the operator on whose network the modem is currently registered. */ ServingOperator?: CellularProviderProperties; /** * The state of SIM lock for GSM family networks. */ SIMLockStatus?: SIMLockStatus; /** * Whether a SIM card is present. */ SIMPresent?: boolean; /** * The current network signal strength. */ SignalStrength?: number; /** * Whether the cellular network supports scanning. */ SupportNetworkScan?: boolean; } export interface ManagedCellularProperties { /** * See {@link CellularProperties.AutoConnect}. */ AutoConnect?: ManagedBoolean; /** * See {@link CellularProperties.ActivationType}. */ ActivationType?: string; /** * See {@link CellularProperties.ActivationState}. */ ActivationState?: ActivationStateType; /** * See {@link CellularProperties.AllowRoaming}. */ AllowRoaming?: boolean; /** * See {@link CellularProperties.Family}. */ Family?: string; /** * See {@link CellularProperties.FirmwareRevision}. */ FirmwareRevision?: string; /** * See {@link CellularProperties.FoundNetworks}. */ FoundNetworks?: FoundNetworkProperties[]; /** * See {@link CellularProperties.HardwareRevision}. */ HardwareRevision?: string; /** * See {@link CellularProperties.HomeProvider}. */ HomeProvider?: CellularProviderProperties[]; /** * See {@link CellularProperties.Manufacturer}. */ Manufacturer?: string; /** * See {@link CellularProperties.ModelID}. */ ModelID?: string; /** * See {@link CellularProperties.NetworkTechnology}. */ NetworkTechnology?: string; /** * See {@link CellularProperties.PaymentPortal}. */ PaymentPortal?: PaymentPortal; /** * See {@link CellularProperties.RoamingState}. */ RoamingState?: string; /** * See {@link CellularProperties.Scanning}. * * @since Chrome 63 */ Scanning?: boolean; /** * See {@link CellularProperties.ServingOperator}. */ ServingOperator?: CellularProviderProperties; /** * See {@link CellularProperties.SIMLockStatus}. */ SIMLockStatus?: SIMLockStatus; /** * See {@link CellularProperties.SIMPresent}. */ SIMPresent?: boolean; /** * See {@link CellularProperties.SignalStrength}. */ SignalStrength?: number; /** * See {@link CellularProperties.SupportNetworkScan}. */ SupportNetworkScan?: boolean; } export interface CellularStateProperties { /** * See {@link CellularProperties.ActivationState}. */ ActivationState?: ActivationStateType; /** * See {@link CellularProperties.NetworkTechnology}. */ NetworkTechnology?: string; /** * See {@link CellularProperties.RoamingState}. */ RoamingState?: string; /** * See {@link CellularProperties.SIMPresent}. */ SIMPresent?: boolean; /** * See {@link CellularProperties.SignalStrength}. */ SignalStrength?: number; } export interface EthernetProperties { /** * Whether the Ethernet network should be connected automatically. */ AutoConnect?: boolean; /** * The authentication used by the Ethernet network. Possible values are `None` and `8021X`. */ Authentication?: string; /** * Network's EAP settings. Required for 8021X authentication. */ EAP?: EAPProperties; } export interface ManagedEthernetProperties { /** * See {@link EthernetProperties.AutoConnect}. */ AutoConnect?: ManagedBoolean; /** * See {@link EthernetProperties.Authentication}. */ Authentication?: ManagedDOMString; } export interface EthernetStateProperties { /** * See {@link EthernetProperties.Authentication}. */ Authentication: string; } export interface VPNProperties { /** * Whether the VPN network should be connected automatically. */ AutoConnect?: boolean; /** * The VPN host. */ Host?: string; /** * The VPN type. This cannot be an enum because of 'L2TP-IPSec'. This is optional for NetworkConfigProperties which is passed to setProperties which may be used to set only specific properties. */ Type?: string; } export interface ManagedVPNProperties { /** * See {@link VPNProperties.AutoConnect}. */ AutoConnect?: ManagedBoolean; /** * See {@link VPNProperties.Host}. */ Host?: ManagedDOMString; /** * See {@link VPNProperties.Type}. */ Type?: ManagedDOMString; } export interface VPNStateProperties { /** * See {@link VPNProperties.Type}. */ Type: string; } export interface WiFiProperties { /** * @deprecated Removed in M131. There is no active ARP polling now. * @chrome-deprecated-since Chrome 131 */ AllowGatewayARPPolling?: boolean; /** * Whether the WiFi network should be connected automatically when in range. */ AutoConnect?: boolean; /** * The BSSID of the associated access point.. */ BSSID?: string; /** * The network EAP properties. Required for `WEP-8021X` and `WPA-EAP` networks. */ EAP?: EAPProperties; /** * The WiFi service operating frequency in MHz. For connected networks, the current frequency on which the network is connected. Otherwise, the frequency of the best available BSS. */ Frequency?: number; /** * Contains all operating frequency recently seen for the WiFi network. */ FrequencyList?: number[]; /** * HEX-encoded copy of the network SSID. */ HexSSID?: string; /** * Whether the network SSID will be broadcast. */ HiddenSSID?: boolean; /** * The passphrase for WEP/WPA/WPA2 connections. This property can only be set - properties returned by {@link getProperties} will not contain this value. * * @since Chrome 66 */ Passphrase?: string; /** * Deprecated, ignored. */ RoamThreshold?: number; /** * The network SSID. */ SSID?: string; /** * The network security type. */ Security?: string; /** * The network signal strength. */ SignalStrength?: number; } export interface ManagedWiFiProperties { /** * See {@link WiFiProperties.AllowGatewayARPPolling}. */ AllowGatewayARPPolling?: ManagedBoolean; /** * See {@link WiFiProperties.AutoConnect}. */ AutoConnect?: ManagedBoolean; /** * See {@link WiFiProperties.BSSID}. */ BSSID?: string; /** * See {@link WiFiProperties.Frequency}. */ Frequency?: number; /** * See {@link WiFiProperties.FrequencyList}. */ FrequencyList?: number[]; /** * See {@link WiFiProperties.HexSSID}. */ HexSSID?: ManagedDOMString; /** * See {@link WiFiProperties.HiddenSSID}. */ HiddenSSID?: ManagedBoolean; /** * Deprecated, ignored. See {@link WiFiProperties.RoamThreshold}. */ RoamThreshold?: ManagedLong; /** * See {@link WiFiProperties.SSID}. */ SSID?: ManagedDOMString; /** * See {@link WiFiProperties.Security}. */ Security: ManagedDOMString; /** * See {@link WiFiProperties.SignalStrength}. */ SignalStrength?: number; } export interface WiFiStateProperties { /** * See {@link WiFiProperties.BSSID}. */ BSSID?: string; /** * See {@link WiFiProperties.Frequency}. */ Frequency?: number; /** * See {@link WiFiProperties.HexSSID}. * * @since Chrome 62 */ HexSSID?: string; /** * See {@link WiFiProperties.Security}. */ Security: string; /** * See {@link WiFiProperties.SignalStrength}. */ SignalStrength?: number; /** * See {@link WiFiProperties.SSID}. * * @since Chrome 62 */ SSID?: string; } export interface WiMAXProperties { /** * Whether the network should be connected automatically. */ AutoConnect?: boolean; /** * The network EAP properties. */ EAP?: EAPProperties; } export interface NetworkConfigProperties { /** * See {@link NetworkProperties.Cellular}. */ Cellular?: CellularProperties; /** * See {@link NetworkProperties.Ethernet}. */ Ethernet?: EthernetProperties; /** * See {@link NetworkProperties.GUID}. */ GUID?: string; /** * See {@link NetworkProperties.IPAddressConfigType}. */ IPAddressConfigType?: IPConfigType; /** * See {@link NetworkProperties.Name}. */ Name?: string; /** * See {@link NetworkProperties.NameServersConfigType}. */ NameServersConfigType?: IPConfigType; /** * See {@link NetworkProperties.Priority}. */ Priority?: number; /** * See {@link NetworkProperties.Type}. */ Type?: NetworkType; /** * See {@link NetworkProperties.VPN}. */ VPN?: VPNProperties; /** * See {@link NetworkProperties.WiFi}. */ WiFi?: WiFiProperties; /** * Deprecated. */ WiMAX?: WiMAXProperties; } export interface NetworkProperties { /** * For cellular networks, cellular network properties. */ Cellular?: CellularProperties; /** * Whether the network is connectable. */ Connectable?: boolean; /** * The network's current connection state. */ ConnectionState?: ConnectionStateType; /** * The last recorded network error state. */ ErrorState?: string; /** * For Ethernet networks, the Ethernet network properties. */ Ethernet?: EthernetProperties; /** * The network GUID. */ GUID: string; /** * The network's IP address configuration type. */ IPAddressConfigType?: IPConfigType; /** * The network's IP configuration. */ IPConfigs?: IPConfigProperties[]; /** * The network's MAC address. */ MacAddress?: string; /** * Whether the network is metered. * * @since Chrome 85 */ Metered?: boolean; /** * A user friendly network name. */ Name?: string; /** * The IP configuration type for the name servers used by the network. */ NameServersConfigType?: IPConfigType; /** * The network priority. */ Priority?: number; /** * The network's proxy settings. */ ProxySettings?: ProxySettings; /** * For a connected network, whether the network connectivity to the Internet is limited, e.g. if the network is behind a portal, or a cellular network is not activated. */ RestrictedConnectivity?: boolean; /** * The network's static IP configuration. */ StaticIPConfig?: IPConfigProperties; /** * IP configuration that was received from the DHCP server before applying static IP configuration. */ SavedIPConfig?: IPConfigProperties; /** * Indicates whether and how the network is configured. Possible values are: * * * `Device` * * `DevicePolicy` * * `User` * * `UserPolicy` * * `None` * * 'None' conflicts with extension code generation so we must use a string for 'Source' instead of a SourceType enum. */ Source?: string; /** * When traffic counters were last reset. * * @since Chrome 125 */ TrafficCounterResetTime?: number; /** * The network type. */ Type: NetworkType; /** * For VPN networks, the network VPN properties. */ VPN?: VPNProperties; /** * For WiFi networks, the network WiFi properties. */ WiFi?: WiFiProperties; } export interface ManagedProperties { /** * See {@link NetworkProperties.Cellular}. */ Cellular?: ManagedCellularProperties; /** * See {@link NetworkProperties.Connectable}. */ Connectable?: boolean; /** * See {@link NetworkProperties.ConnectionState}. */ ConnectionState?: ConnectionStateType; /** * See {@link NetworkProperties.ErrorState}. */ ErrorState?: string; /** * See {@link NetworkProperties.Ethernet}. */ Ethernet?: ManagedEthernetProperties; /** * See {@link NetworkProperties.GUID}. */ GUID: string; /** * See {@link NetworkProperties.IPAddressConfigType}. */ IPAddressConfigType?: ManagedIPConfigType; /** * See {@link NetworkProperties.IPConfigs}. */ IPConfigs?: IPConfigProperties[]; /** * See {@link NetworkProperties.MacAddress}. */ MacAddress?: string; /** * See {@link NetworkProperties.Metered}. * * @since Chrome 85 */ Metered?: ManagedBoolean; /** * See {@link NetworkProperties.Name}. */ Name?: ManagedDOMString; /** * See {@link NetworkProperties.NameServersConfigType}. */ NameServersConfigType?: ManagedIPConfigType; /** * See {@link NetworkProperties.Priority}. */ Priority?: ManagedLong; /** * See {@link NetworkProperties.ProxySettings}. */ ProxySettings?: ManagedProxySettings; /** * See {@link NetworkProperties.RestrictedConnectivity}. */ RestrictedConnectivity?: boolean; /** * See {@link NetworkProperties.StaticIPConfig}. */ StaticIPConfig?: ManagedIPConfigProperties; /** * See {@link NetworkProperties.SavedIPConfig}. */ SavedIPConfig?: IPConfigProperties; /** * See {@link NetworkProperties.Source}. */ Source?: string; /** * See {@link NetworkProperties.TrafficCounterResetTime}. * * @since Chrome 125 */ TrafficCounterResetTime?: number; /** * See {@link NetworkProperties.Type}. */ Type: NetworkType; /** * See {@link NetworkProperties.VPN}. */ VPN?: ManagedVPNProperties; /** * See {@link NetworkProperties.WiFi}. */ WiFi?: ManagedWiFiProperties; } export interface NetworkStateProperties { /** * See {@link NetworkProperties.Cellular}. */ Cellular?: CellularStateProperties; /** * See {@link NetworkProperties.Connectable}. */ Connectable?: boolean; /** * See {@link NetworkProperties.ConnectionState}. */ ConnectionState?: ConnectionStateType; /** * See {@link NetworkProperties.Ethernet}. */ Ethernet?: EthernetStateProperties; /** * See {@link NetworkProperties.ErrorState}. */ ErrorState?: string; /** * See {@link NetworkProperties.GUID}. */ GUID: string; /** * See {@link NetworkProperties.Name}. */ Name?: string; /** * See {@link NetworkProperties.Priority}. */ Priority?: number; /** * See {@link NetworkProperties.Source}. */ Source?: string; /** * See {@link NetworkProperties.Type}. */ Type: NetworkType; /** * See {@link NetworkProperties.VPN}. */ VPN?: VPNStateProperties; /** * See {@link NetworkProperties.WiFi}. */ WiFi?: WiFiStateProperties; } export interface DeviceStateProperties { /** * Set if the device is enabled. True if the device is currently scanning. */ Scanning?: boolean; /** * The SIM lock status if Type = Cellular and SIMPresent = True. * * @since Chrome 62 */ SIMLockStatus?: SIMLockStatus; /** * Set to the SIM present state if the device type is Cellular. * * @since Chrome 62 */ SIMPresent?: boolean; /** * The current state of the device. */ State: DeviceStateType; /** * The network type associated with the device (Cellular, Ethernet or WiFi). */ Type: NetworkType; } export interface NetworkFilter { /** * The type of networks to return. */ networkType: NetworkType; /** * If true, only include visible (physically connected or in-range) networks. Defaults to 'false'. */ visible?: boolean; /** * If true, only include configured (saved) networks. Defaults to 'false'. */ configured?: boolean; /** * Maximum number of networks to return. Defaults to 1000 if unspecified. Use 0 for no limit. */ limit?: number; } export interface GlobalPolicy { /** * If true, only policy networks may auto connect. Defaults to false. */ AllowOnlyPolicyNetworksToAutoconnect?: boolean; /** * If true, only policy networks may be connected to and no new networks may be added or configured. Defaults to false. */ AllowOnlyPolicyNetworksToConnect?: boolean; /** * If true and a managed network is available in the visible network list, only policy networks may be connected to and no new networks may be added or configured. Defaults to false. * * @since Chrome 70 */ AllowOnlyPolicyNetworksToConnectIfAvailable?: boolean; /** * List of blocked networks. Connections to blocked networks are prohibited. Networks can be unblocked again by specifying an explicit network configuration. Defaults to an empty list. * * @since Chrome 86 */ BlockedHexSSIDs?: string[]; } /** * Fired when the properties change on any of the networks. Sends a list of GUIDs for networks whose properties have changed. */ export const onNetworksChanged: events.Event<( changes: string[], ) => void>; /** * Fired when the list of networks has changed. Sends a complete list of GUIDs for all the current networks. */ export const onNetworkListChanged: events.Event<( changes: string[], ) => void>; /** * Fired when the list of devices has changed or any device state properties have changed. */ export const onDeviceStateListChanged: events.Event<() => void>; /** * Fired when a portal detection for a network completes. Sends the GUID of the network and the corresponding captive portal status. */ export const onPortalDetectionCompleted: events.Event<( networkGuid: string, status: CaptivePortalStatus, ) => void>; /** * Gets all the properties of the network with id networkGuid. Includes all properties of the network (read-only and read/write values). * * @chrome-returns-extra since Chrome 125 * @param networkGuid The GUID of the network to get properties for. */ export function getProperties( networkGuid: string, ): Promise; /** * Gets all the properties of the network with id networkGuid. Includes all properties of the network (read-only and read/write values). * * @param networkGuid The GUID of the network to get properties for. */ export function getProperties( networkGuid: string, callback?: ( result: NetworkProperties, ) => void, ): void; /** * Gets the merged properties of the network with id networkGuid from the sources: User settings, shared settings, user policy, device policy and the currently active settings. * * @chrome-returns-extra since Chrome 125 * @param networkGuid The GUID of the network to get properties for. */ export function getManagedProperties( networkGuid: string, ): Promise; /** * Gets the merged properties of the network with id networkGuid from the sources: User settings, shared settings, user policy, device policy and the currently active settings. * * @param networkGuid The GUID of the network to get properties for. */ export function getManagedProperties( networkGuid: string, callback?: ( result: ManagedProperties, ) => void, ): void; /** * Gets the cached read-only properties of the network with id networkGuid. This is meant to be a higher performance function than {@link getProperties}, which requires a round trip to query the networking subsystem. The following properties are returned for all networks: GUID, Type, Name, WiFi.Security. Additional properties are provided for visible networks: ConnectionState, ErrorState, WiFi.SignalStrength, Cellular.NetworkTechnology, Cellular.ActivationState, Cellular.RoamingState. * * @chrome-returns-extra since Chrome 125 * @param networkGuid The GUID of the network to get properties for. */ export function getState( networkGuid: string, ): Promise; /** * Gets the cached read-only properties of the network with id networkGuid. This is meant to be a higher performance function than {@link getProperties}, which requires a round trip to query the networking subsystem. The following properties are returned for all networks: GUID, Type, Name, WiFi.Security. Additional properties are provided for visible networks: ConnectionState, ErrorState, WiFi.SignalStrength, Cellular.NetworkTechnology, Cellular.ActivationState, Cellular.RoamingState. * * @param networkGuid The GUID of the network to get properties for. */ export function getState( networkGuid: string, callback?: ( result: NetworkStateProperties, ) => void, ): void; /** * Sets the properties of the network with id `networkGuid`. This is only valid for configured networks (Source != None). Unconfigured visible networks should use {@link createNetwork} instead. **In kiosk sessions, calling this method on a shared network will fail.** * * @chrome-returns-extra since Chrome 125 * @param networkGuid The GUID of the network to set properties for. * @param properties The properties to set. */ export function setProperties( networkGuid: string, properties: NetworkConfigProperties, ): Promise; /** * Sets the properties of the network with id `networkGuid`. This is only valid for configured networks (Source != None). Unconfigured visible networks should use {@link createNetwork} instead. **In kiosk sessions, calling this method on a shared network will fail.** * * @param networkGuid The GUID of the network to set properties for. * @param properties The properties to set. */ export function setProperties( networkGuid: string, properties: NetworkConfigProperties, callback?: () => void, ): void; /** * Creates a new network configuration from properties. If a matching configured network already exists, this will fail. Otherwise returns the GUID of the new network. * * @chrome-returns-extra since Chrome 125 * @param shared If `true`, share this network configuration with other users. **This option is exposed only to Chrome's Web UI.** When called by apps, `false` is the only allowed value. * @param properties The properties to configure the new network with. */ export function createNetwork( shared: boolean, properties: NetworkConfigProperties, ): Promise; /** * Creates a new network configuration from properties. If a matching configured network already exists, this will fail. Otherwise returns the GUID of the new network. * * @param shared If `true`, share this network configuration with other users. **This option is exposed only to Chrome's Web UI.** When called by apps, `false` is the only allowed value. * @param properties The properties to configure the new network with. */ export function createNetwork( shared: boolean, properties: NetworkConfigProperties, callback?: ( result: string, ) => void, ): void; /** * Forgets a network configuration by clearing any configured properties for the network with GUID `networkGuid`. This may also include any other networks with matching identifiers (e.g. WiFi SSID and Security). If no such configuration exists, an error will be set and the operation will fail. * * **In kiosk sessions, this method will not be able to forget shared network configurations.** * * @chrome-returns-extra since Chrome 125 * @param networkGuid The GUID of the network to forget. */ export function forgetNetwork( networkGuid: string, ): Promise; /** * Forgets a network configuration by clearing any configured properties for the network with GUID `networkGuid`. This may also include any other networks with matching identifiers (e.g. WiFi SSID and Security). If no such configuration exists, an error will be set and the operation will fail. * * **In kiosk sessions, this method will not be able to forget shared network configurations.** * * @param networkGuid The GUID of the network to forget. */ export function forgetNetwork( networkGuid: string, callback?: () => void, ): void; /** * Returns a list of network objects with the same properties provided by {@link getState}. A filter is provided to specify the type of networks returned and to limit the number of networks. Networks are ordered by the system based on their priority, with connected or connecting networks listed first. * * @chrome-returns-extra since Chrome 125 * @param filter Describes which networks to return. */ export function getNetworks( filter: NetworkFilter, ): Promise; /** * Returns a list of network objects with the same properties provided by {@link getState}. A filter is provided to specify the type of networks returned and to limit the number of networks. Networks are ordered by the system based on their priority, with connected or connecting networks listed first. * * @param filter Describes which networks to return. */ export function getNetworks( filter: NetworkFilter, callback?: ( result: NetworkStateProperties[], ) => void, ): void; /** * Returns states of available networking devices. * * @chrome-returns-extra since Chrome 125 */ export function getDeviceStates(): Promise; /** * Returns states of available networking devices. */ export function getDeviceStates( callback?: ( result: DeviceStateProperties[], ) => void, ): void; /** * Enables any devices matching the specified network type. Note, the type might represent multiple network types (e.g. 'Wireless'). * * @param networkType The type of network to enable. */ export function enableNetworkType( networkType: NetworkType, ): void; /** * Disables any devices matching the specified network type. See note for {@link enableNetworkType}. * * @param networkType The type of network to disable. */ export function disableNetworkType( networkType: NetworkType, ): void; /** * Requests that the networking subsystem scan for new networks and update the list returned by {@link getVisibleNetworks}. This is only a request: the network subsystem can choose to ignore it. If the list is updated, then the {@link onNetworkListChanged} event will be fired. * * @param networkType If provided, requests a scan specific to the type. For Cellular a mobile network scan will be requested if supported. */ export function requestNetworkScan( /** * @since Chrome 63 */ networkType?: NetworkType, ): void; /** * Starts a connection to the network with networkGuid. * * @chrome-returns-extra since Chrome 125 * @param networkGuid The GUID of the network to connect to. */ export function startConnect( networkGuid: string, ): Promise; /** * Starts a connection to the network with networkGuid. * * @param networkGuid The GUID of the network to connect to. */ export function startConnect( networkGuid: string, callback?: () => void, ): void; /** * Starts a disconnect from the network with networkGuid. * * @chrome-returns-extra since Chrome 125 * @param networkGuid The GUID of the network to disconnect from. */ export function startDisconnect( networkGuid: string, ): Promise; /** * Starts a disconnect from the network with networkGuid. * * @param networkGuid The GUID of the network to disconnect from. */ export function startDisconnect( networkGuid: string, callback?: () => void, ): void; /** * Returns captive portal status for the network matching 'networkGuid'. * * @chrome-returns-extra since Chrome 125 * @param networkGuid The GUID of the network to get captive portal status for. */ export function getCaptivePortalStatus( networkGuid: string, ): Promise; /** * Returns captive portal status for the network matching 'networkGuid'. * * @param networkGuid The GUID of the network to get captive portal status for. */ export function getCaptivePortalStatus( networkGuid: string, callback?: ( result: CaptivePortalStatus, ) => void, ): void; /** * Gets the global policy properties. These properties are not expected to change during a session. * * @chrome-returns-extra since Chrome 125 */ export function getGlobalPolicy(): Promise; /** * Gets the global policy properties. These properties are not expected to change during a session. */ export function getGlobalPolicy( callback?: ( result: GlobalPolicy, ) => void, ): void; } /** * Use the `chrome.notifications` API to create rich notifications using templates and show these notifications to users in the system tray. * * @chrome-permission notifications */ export namespace notifications { /** * @chrome-enum "basic" Contains an icon, title, message, expandedMessage, and up to two buttons. * @chrome-enum "image" Contains an icon, title, message, expandedMessage, image, and up to two buttons. * @chrome-enum "list" Contains an icon, title, message, items, and up to two buttons. Users on Mac OS X only see the first item. * @chrome-enum "progress" Contains an icon, title, message, progress, and up to two buttons. */ export type TemplateType = "basic" | "image" | "list" | "progress"; /** * @chrome-enum "granted" Specifies that the user has elected to show notifications from the app or extension. This is the default at install time. * @chrome-enum "denied" Specifies that the user has elected not to show notifications from the app or extension. */ export type PermissionLevel = "granted" | "denied"; export interface NotificationItem { /** * Title of one item of a list notification. */ title: string; /** * Additional details about this item. */ message: string; } export interface NotificationBitmap { } export interface NotificationButton { title: string; /** * @deprecated Button icons not visible for Mac OS X users. * @chrome-deprecated-since Chrome 59 */ iconUrl?: string; } export interface NotificationOptions { /** * Which type of notification to display. _Required for {@link notifications.create}_ method. */ type?: TemplateType; /** * A URL to the sender's avatar, app icon, or a thumbnail for image notifications. * * URLs can be a data URL, a blob URL, or a URL relative to a resource within this extension's .crx file * * **Note:**This value is required for the {@link notifications.create}`()` method. */ iconUrl?: string; /** * A URL to the app icon mask. URLs have the same restrictions as {@link notifications.NotificationOptions.iconUrl iconUrl}. * * The app icon mask should be in alpha channel, as only the alpha channel of the image will be considered. * * @deprecated The app icon mask is not visible for Mac OS X users. * @chrome-deprecated-since Chrome 59 */ appIconMaskUrl?: string; /** * Title of the notification (e.g. sender name for email). * * **Note:**This value is required for the {@link notifications.create}`()` method. */ title?: string; /** * Main notification content. * * **Note:**This value is required for the {@link notifications.create}`()` method. */ message?: string; /** * Alternate notification content with a lower-weight font. */ contextMessage?: string; /** * Priority ranges from -2 to 2. -2 is lowest priority. 2 is highest. Zero is default. On platforms that don't support a notification center (Windows, Linux & Mac), -2 and -1 result in an error as notifications with those priorities will not be shown at all. */ priority?: number; /** * A timestamp associated with the notification, in milliseconds past the epoch (e.g. `Date.now() + n`). */ eventTime?: number; /** * Text and icons for up to two notification action buttons. */ buttons?: NotificationButton[]; /** * A URL to the image thumbnail for image-type notifications. URLs have the same restrictions as {@link notifications.NotificationOptions.iconUrl iconUrl}. * * @deprecated The image is not visible for Mac OS X users. * @chrome-deprecated-since Chrome 59 */ imageUrl?: string; /** * Items for multi-item notifications. Users on Mac OS X only see the first item. */ items?: NotificationItem[]; /** * Current progress ranges from 0 to 100. */ progress?: number; /** * @deprecated This UI hint is ignored as of Chrome 67 * @chrome-deprecated-since Chrome 67 */ isClickable?: boolean; /** * Indicates that the notification should remain visible on screen until the user activates or dismisses the notification. This defaults to false. * * @since Chrome 50 */ requireInteraction?: boolean; /** * Indicates that no sounds or vibrations should be made when the notification is being shown. This defaults to false. * * @since Chrome 70 */ silent?: boolean; } /** * The notification closed, either by the system or by user action. */ export const onClosed: events.Event<( notificationId: string, byUser: boolean, ) => void>; /** * The user clicked in a non-button area of the notification. */ export const onClicked: events.Event<( notificationId: string, ) => void>; /** * The user pressed a button in the notification. */ export const onButtonClicked: events.Event<( notificationId: string, buttonIndex: number, ) => void>; /** * The user changes the permission level. As of Chrome 47, only ChromeOS has UI that dispatches this event. */ export const onPermissionLevelChanged: events.Event<( level: PermissionLevel, ) => void>; /** * The user clicked on a link for the app's notification settings. As of Chrome 47, only ChromeOS has UI that dispatches this event. As of Chrome 65, that UI has been removed from ChromeOS, too. * * @deprecated Custom notification settings button is no longer supported. * @chrome-deprecated-since Chrome 65 */ export const onShowSettings: events.Event<() => void>; /** * Creates and displays a notification. * * @chrome-returns-extra since Chrome 116 * @param notificationId Identifier of the notification. If not set or empty, an ID will automatically be generated. If it matches an existing notification, this method first clears that notification before proceeding with the create operation. The identifier may not be longer than 500 characters. The `notificationId` parameter is required before Chrome 42. * @param options Contents of the notification. * @returns Returns a Promise which resolves with the notification id (either supplied or generated) that represents the created notification. */ export function create( notificationId: string, options: NotificationOptions, ): Promise; /** * Creates and displays a notification. * * @chrome-returns-extra since Chrome 116 * @param options Contents of the notification. * @returns Returns a Promise which resolves with the notification id (either supplied or generated) that represents the created notification. */ export function create( options: NotificationOptions, ): Promise; /** * Creates and displays a notification. * * @param notificationId Identifier of the notification. If not set or empty, an ID will automatically be generated. If it matches an existing notification, this method first clears that notification before proceeding with the create operation. The identifier may not be longer than 500 characters. The `notificationId` parameter is required before Chrome 42. * @param options Contents of the notification. */ export function create( notificationId: string, options: NotificationOptions, callback?: ( notificationId: string, ) => void, ): void; /** * Creates and displays a notification. * * @param options Contents of the notification. */ export function create( options: NotificationOptions, callback?: ( notificationId: string, ) => void, ): void; /** * Updates an existing notification. * * @chrome-returns-extra since Chrome 116 * @param notificationId The id of the notification to be updated. This is returned by {@link notifications.create} method. * @param options Contents of the notification to update to. * @returns Returns a Promise which resolves to indicate whether a matching notification existed. */ export function update( notificationId: string, options: NotificationOptions, ): Promise; /** * Updates an existing notification. * * @param notificationId The id of the notification to be updated. This is returned by {@link notifications.create} method. * @param options Contents of the notification to update to. */ export function update( notificationId: string, options: NotificationOptions, callback?: ( wasUpdated: boolean, ) => void, ): void; /** * Clears the specified notification. * * @chrome-returns-extra since Chrome 116 * @param notificationId The id of the notification to be cleared. This is returned by {@link notifications.create} method. * @returns Returns a Promise which resolves to indicate whether a matching notification existed. */ export function clear( notificationId: string, ): Promise; /** * Clears the specified notification. * * @param notificationId The id of the notification to be cleared. This is returned by {@link notifications.create} method. */ export function clear( notificationId: string, callback?: ( wasCleared: boolean, ) => void, ): void; /** * Retrieves all the notifications of this app or extension. * * @chrome-returns-extra since Chrome 116 * @returns Returns a Promise which resolves with the set of notification\_ids currently in the system. */ export function getAll(): Promise<{[name: string]: any}>; /** * Retrieves all the notifications of this app or extension. */ export function getAll( callback?: ( notifications: {[name: string]: any}, ) => void, ): void; /** * Retrieves whether the user has enabled notifications from this app or extension. * * @chrome-returns-extra since Chrome 116 * @returns Returns a Promise which resolves with the current permission level. */ export function getPermissionLevel(): Promise; /** * Retrieves whether the user has enabled notifications from this app or extension. */ export function getPermissionLevel( callback?: ( level: PermissionLevel, ) => void, ): void; } /** * Stub namespace for the "oauth2" manifest key. * * @since Chrome 93 */ export namespace oauth2 { export interface OAuth2Info { /** * Client ID of the corresponding extension/app. */ client_id?: string; /** * Scopes the extension/app needs access to. */ scopes: string[]; } } /** * Use the `offscreen` API to create and manage offscreen documents. * * @since Chrome 109 * @chrome-permission offscreen * @chrome-min-manifest MV3 */ export namespace offscreen { /** * @chrome-enum "TESTING" A reason used for testing purposes only. * @chrome-enum "AUDIO\_PLAYBACK" Specifies that the offscreen document is responsible for playing audio. * @chrome-enum "IFRAME\_SCRIPTING" Specifies that the offscreen document needs to embed and script an iframe in order to modify the iframe's content. * @chrome-enum "DOM\_SCRAPING" Specifies that the offscreen document needs to embed an iframe and scrape its DOM to extract information. * @chrome-enum "BLOBS" Specifies that the offscreen document needs to interact with Blob objects (including `URL.createObjectURL()`). * @chrome-enum "DOM\_PARSER" Specifies that the offscreen document needs to use the [DOMParser API](https://developer.mozilla.org/en-US/docs/Web/API/DOMParser). * @chrome-enum "USER\_MEDIA" Specifies that the offscreen document needs to interact with media streams from user media (e.g. `getUserMedia()`). * @chrome-enum "DISPLAY\_MEDIA" Specifies that the offscreen document needs to interact with media streams from display media (e.g. `getDisplayMedia()`). * @chrome-enum "WEB\_RTC" Specifies that the offscreen document needs to use [WebRTC APIs](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API). * @chrome-enum "CLIPBOARD" Specifies that the offscreen document needs to interact with the [Clipboard API](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API). * @chrome-enum "LOCAL\_STORAGE" Specifies that the offscreen document needs access to [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage). * @chrome-enum "WORKERS" Specifies that the offscreen document needs to spawn workers. * @chrome-enum "BATTERY\_STATUS" Specifies that the offscreen document needs to use [navigator.getBattery](https://developer.mozilla.org/en-US/docs/Web/API/Battery_Status_API). * @chrome-enum "MATCH\_MEDIA" Specifies that the offscreen document needs to use [window.matchMedia](https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia). * @chrome-enum "GEOLOCATION" Specifies that the offscreen document needs to use [navigator.geolocation](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/geolocation). */ export type Reason = "TESTING" | "AUDIO_PLAYBACK" | "IFRAME_SCRIPTING" | "DOM_SCRAPING" | "BLOBS" | "DOM_PARSER" | "USER_MEDIA" | "DISPLAY_MEDIA" | "WEB_RTC" | "CLIPBOARD" | "LOCAL_STORAGE" | "WORKERS" | "BATTERY_STATUS" | "MATCH_MEDIA" | "GEOLOCATION"; export interface CreateParameters { /** * The reason(s) the extension is creating the offscreen document. */ reasons: Reason[]; /** * The (relative) URL to load in the document. */ url: string; /** * A developer-provided string that explains, in more detail, the need for the background context. The user agent \_may\_ use this in display to the user. */ justification: string; } /** * Creates a new offscreen document for the extension. * * @param parameters The parameters describing the offscreen document to create. * @returns Promise that resolves when the offscreen document is created and has completed its initial page load. */ export function createDocument( parameters: CreateParameters, ): Promise; /** * Creates a new offscreen document for the extension. * * @param parameters The parameters describing the offscreen document to create. */ export function createDocument( parameters: CreateParameters, callback?: () => void, ): void; /** * Closes the currently-open offscreen document for the extension. * * @returns Promise that resolves when the offscreen document has been closed. */ export function closeDocument(): Promise; /** * Closes the currently-open offscreen document for the extension. */ export function closeDocument( callback?: () => void, ): void; } /** * The omnibox API allows you to register a keyword with Google Chrome's address bar, which is also known as the omnibox. * * @chrome-manifest omnibox */ export namespace omnibox { /** * The style type. * * @since Chrome 44 */ export type DescriptionStyleType = "url" | "match" | "dim"; /** * The window disposition for the omnibox query. This is the recommended context to display results. For example, if the omnibox command is to navigate to a certain URL, a disposition of 'newForegroundTab' means the navigation should take place in a new selected tab. * * @since Chrome 44 */ export type OnInputEnteredDisposition = "currentTab" | "newForegroundTab" | "newBackgroundTab"; /** * A suggest result. */ export interface SuggestResult { /** * The text that is put into the URL bar, and that is sent to the extension when the user chooses this entry. */ content: string; /** * The text that is displayed in the URL dropdown. Can contain XML-style markup for styling. The supported tags are 'url' (for a literal URL), 'match' (for highlighting text that matched what the user's query), and 'dim' (for dim helper text). The styles can be nested, eg. dimmed match. You must escape the five predefined entities to display them as text: stackoverflow.com/a/1091953/89484 */ description: string; /** * Whether the suggest result can be deleted by the user. * * @since Chrome 63 */ deletable?: boolean; } /** * A suggest result. */ export interface DefaultSuggestResult { /** * The text that is displayed in the URL dropdown. Can contain XML-style markup for styling. The supported tags are 'url' (for a literal URL), 'match' (for highlighting text that matched what the user's query), and 'dim' (for dim helper text). The styles can be nested, eg. dimmed match. */ description: string; } /** * User has started a keyword input session by typing the extension's keyword. This is guaranteed to be sent exactly once per input session, and before any onInputChanged events. */ export const onInputStarted: events.Event<() => void>; /** * User has changed what is typed into the omnibox. */ export const onInputChanged: events.Event<( text: string, /** * @param suggestResults Array of suggest results */ suggest: ( suggestResults: SuggestResult[], ) => void, ) => void>; /** * User has accepted what is typed into the omnibox. */ export const onInputEntered: events.Event<( text: string, disposition: OnInputEnteredDisposition, ) => void>; /** * User has ended the keyword input session without accepting the input. */ export const onInputCancelled: events.Event<() => void>; /** * User has deleted a suggested result. * * @since Chrome 63 */ export const onDeleteSuggestion: events.Event<( text: string, ) => void>; /** * Sets the description and styling for the default suggestion. The default suggestion is the text that is displayed in the first suggestion row underneath the URL bar. * * @chrome-returns-extra since Chrome 100 * @param suggestion A partial SuggestResult object, without the 'content' parameter. */ export function setDefaultSuggestion( suggestion: DefaultSuggestResult, ): Promise; /** * Sets the description and styling for the default suggestion. The default suggestion is the text that is displayed in the first suggestion row underneath the URL bar. * * @param suggestion A partial SuggestResult object, without the 'content' parameter. */ export function setDefaultSuggestion( suggestion: DefaultSuggestResult, /** * @since Chrome 100 */ callback?: () => void, ): void; } /** * Use the `chrome.pageAction` API to put icons in the main Google Chrome toolbar, to the right of the address bar. Page actions represent actions that can be taken on the current page, but that aren't applicable to all pages. Page actions appear grayed out when inactive. * * @chrome-manifest page_action * @chrome-max-manifest MV2 */ export namespace pageAction { /** * Pixel data for an image. Must be an ImageData object (for example, from a `canvas` element). */ export type ImageDataType = ImageData; /** * @since Chrome 88 */ export 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; } /** * Fired when a page action icon is clicked. This event will not fire if the page action has a popup. */ export const onClicked: events.Event<( tab: tabs.Tab, ) => void>; /** * Shows the page action. The page action is shown whenever the tab is selected. * * @chrome-returns-extra since Chrome 101 * @param tabId The id of the tab for which you want to modify the page action. */ export function show( tabId: number, ): Promise; /** * Shows the page action. The page action is shown whenever the tab is selected. * * @param tabId The id of the tab for which you want to modify the page action. */ export function show( tabId: number, /** * @since Chrome 67 */ callback?: () => void, ): void; /** * Hides the page action. Hidden page actions still appear in the Chrome toolbar, but are grayed out. * * @chrome-returns-extra since Chrome 101 * @param tabId The id of the tab for which you want to modify the page action. */ export function hide( tabId: number, ): Promise; /** * Hides the page action. Hidden page actions still appear in the Chrome toolbar, but are grayed out. * * @param tabId The id of the tab for which you want to modify the page action. */ export function hide( tabId: number, /** * @since Chrome 67 */ callback?: () => void, ): void; /** * Sets the title of the page action. This is displayed in a tooltip over the page action. * * @chrome-returns-extra since Chrome 101 */ export function setTitle( details: { /** * The id of the tab for which you want to modify the page action. */ tabId: number, /** * The tooltip string. */ title: string, }, ): Promise; /** * Sets the title of the page action. This is displayed in a tooltip over the page action. */ export function setTitle( details: { /** * The id of the tab for which you want to modify the page action. */ tabId: number, /** * The tooltip string. */ title: string, }, /** * @since Chrome 67 */ callback?: () => void, ): void; /** * Gets the title of the page action. * * @chrome-returns-extra since Chrome 101 */ export function getTitle( details: TabDetails, ): Promise; /** * Gets the title of the page action. */ export function getTitle( details: TabDetails, callback?: ( result: string, ) => void, ): void; /** * Sets the icon for the page 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. * * @chrome-returns-extra since Chrome 101 */ export function setIcon( details: { /** * The id of the tab for which you want to modify the page action. */ tabId: number, /** * 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?: ImageDataType | {[name: string]: any}, /** * 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 | {[name: string]: any}, /** * **Deprecated.** This argument is ignored. */ iconIndex?: number, }, ): Promise; /** * Sets the icon for the page 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. */ export function setIcon( details: { /** * The id of the tab for which you want to modify the page action. */ tabId: number, /** * 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?: ImageDataType | {[name: string]: any}, /** * 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 | {[name: string]: any}, /** * **Deprecated.** This argument is ignored. */ iconIndex?: number, }, callback?: () => void, ): void; /** * Sets the HTML document to be opened as a popup when the user clicks on the page action's icon. * * @chrome-returns-extra since Chrome 101 */ export function setPopup( details: { /** * The id of the tab for which you want to modify the page action. */ tabId: number, /** * The relative path to the HTML file to show in a popup. If set to the empty string (`''`), no popup is shown. */ popup: string, }, ): Promise; /** * Sets the HTML document to be opened as a popup when the user clicks on the page action's icon. */ export function setPopup( details: { /** * The id of the tab for which you want to modify the page action. */ tabId: number, /** * The relative path to the HTML file to show in a popup. If set to the empty string (`''`), no popup is shown. */ popup: string, }, /** * @since Chrome 67 */ callback?: () => void, ): void; /** * Gets the html document set as the popup for this page action. * * @chrome-returns-extra since Chrome 101 */ export function getPopup( details: TabDetails, ): Promise; /** * Gets the html document set as the popup for this page action. */ export function getPopup( details: TabDetails, callback?: ( result: string, ) => void, ): void; } /** * Use the `chrome.pageCapture` API to save a tab as MHTML. * * @chrome-permission pageCapture */ export namespace pageCapture { /** * Saves the content of the tab with given id as MHTML. * * @chrome-returns-extra since Chrome 116 * @returns Resolves when the MHTML has been generated. */ export function saveAsMHTML( details: { /** * The id of the tab to save as MHTML. */ tabId: number, }, ): Promise; /** * Saves the content of the tab with given id as MHTML. */ export function saveAsMHTML( details: { /** * The id of the tab to save as MHTML. */ tabId: number, }, /** * @param mhtmlData The MHTML data as a Blob. */ callback?: ( mhtmlData?: Blob, ) => void, ): void; } /** * Use the `chrome.permissions` API to request [declared optional permissions](https://developer.chrome.com/docs/extensions/develop/concepts/declare-permissions) at run time rather than install time, so users understand why the permissions are needed and grant only those that are necessary. */ export namespace permissions { export interface Permissions { /** * List of named permissions (does not include hosts or origins). */ permissions?: string[]; /** * The list of host permissions, including those specified in the `optional_permissions` or `permissions` keys in the manifest, and those associated with [Content Scripts](https://developer.chrome.com/docs/extensions/develop/concepts/content-scripts). */ origins?: string[]; } /** * Fired when the extension acquires new permissions. */ export const onAdded: events.Event<( permissions: Permissions, ) => void>; /** * Fired when access to permissions has been removed from the extension. */ export const onRemoved: events.Event<( permissions: Permissions, ) => void>; /** * Gets the extension's current set of permissions. * * @chrome-returns-extra since Chrome 96 */ export function getAll(): Promise; /** * Gets the extension's current set of permissions. */ export function getAll( /** * @param permissions The extension's active permissions. Note that the `origins` property will contain granted origins from those specified in the `permissions` and `optional_permissions` keys in the manifest and those associated with [Content Scripts](https://developer.chrome.com/docs/extensions/develop/concepts/content-scripts). */ callback?: ( permissions: Permissions, ) => void, ): void; /** * Checks if the extension has the specified permissions. * * @chrome-returns-extra since Chrome 96 */ export function contains( permissions: Permissions, ): Promise; /** * Checks if the extension has the specified permissions. */ export function contains( permissions: Permissions, /** * @param result True if the extension has the specified permissions. If an origin is specified as both an optional permission and a content script match pattern, this will return `false` unless both permissions are granted. */ callback?: ( result: boolean, ) => void, ): void; /** * Requests access to the specified permissions, displaying a prompt to the user if necessary. These permissions must either be defined in the `optional_permissions` field of the manifest or be required permissions that were withheld by the user. Paths on origin patterns will be ignored. You can request subsets of optional origin permissions; for example, if you specify `*://*\/*` in the `optional_permissions` section of the manifest, you can request `http://example.com/`. If there are any problems requesting the permissions, the promise will be rejected. * * @chrome-returns-extra since Chrome 96 */ export function request( permissions: Permissions, ): Promise; /** * Requests access to the specified permissions, displaying a prompt to the user if necessary. These permissions must either be defined in the `optional_permissions` field of the manifest or be required permissions that were withheld by the user. Paths on origin patterns will be ignored. You can request subsets of optional origin permissions; for example, if you specify `*://*\/*` in the `optional_permissions` section of the manifest, you can request `http://example.com/`. If there are any problems requesting the permissions, the promise will be rejected. */ export function request( permissions: Permissions, /** * @param granted True if the user granted the specified permissions. */ callback?: ( granted: boolean, ) => void, ): void; /** * Removes access to the specified permissions. If there are any problems removing the permissions, the promise will be rejected. * * @chrome-returns-extra since Chrome 96 */ export function remove( permissions: Permissions, ): Promise; /** * Removes access to the specified permissions. If there are any problems removing the permissions, the promise will be rejected. */ export function remove( permissions: Permissions, /** * @param removed True if the permissions were removed. */ callback?: ( removed: boolean, ) => void, ): void; /** * Adds a host access request. Request will only be signaled to the user if extension can be granted access to the host in the request. Request will be reset on cross-origin navigation. When accepted, grants persistent access to the site’s top origin * * @since Chrome 133 * @chrome-min-manifest MV3 */ export function addHostAccessRequest( request: { /** * The id of a document where host access requests can be shown. Must be the top-level document within a tab. If provided, the request is shown on the tab of the specified document and is removed when the document navigates to a new origin. Adding a new request will override any existent request for `tabId`. This or `tabId` must be specified. */ documentId?: string, /** * The id of the tab where host access requests can be shown. If provided, the request is shown on the specified tab and is removed when the tab navigates to a new origin. Adding a new request will override an existent request for `documentId`. This or `documentId` must be specified. */ tabId?: number, /** * The URL pattern where host access requests can be shown. If provided, host access requests will only be shown on URLs that match this pattern. */ pattern?: string, }, ): Promise; /** * Adds a host access request. Request will only be signaled to the user if extension can be granted access to the host in the request. Request will be reset on cross-origin navigation. When accepted, grants persistent access to the site’s top origin * * @since Chrome 133 * @chrome-min-manifest MV3 */ export function addHostAccessRequest( request: { /** * The id of a document where host access requests can be shown. Must be the top-level document within a tab. If provided, the request is shown on the tab of the specified document and is removed when the document navigates to a new origin. Adding a new request will override any existent request for `tabId`. This or `tabId` must be specified. */ documentId?: string, /** * The id of the tab where host access requests can be shown. If provided, the request is shown on the specified tab and is removed when the tab navigates to a new origin. Adding a new request will override an existent request for `documentId`. This or `documentId` must be specified. */ tabId?: number, /** * The URL pattern where host access requests can be shown. If provided, host access requests will only be shown on URLs that match this pattern. */ pattern?: string, }, callback?: () => void, ): void; /** * Removes a host access request, if existent. * * @since Chrome 133 * @chrome-min-manifest MV3 */ export function removeHostAccessRequest( request: { /** * The id of a document where host access request will be removed. Must be the top-level document within a tab. This or `tabId` must be specified. */ documentId?: string, /** * The id of the tab where host access request will be removed. This or `documentId` must be specified. */ tabId?: number, /** * The URL pattern where host access request will be removed. If provided, this must exactly match the pattern of an existing host access request. */ pattern?: string, }, ): Promise; /** * Removes a host access request, if existent. * * @since Chrome 133 * @chrome-min-manifest MV3 */ export function removeHostAccessRequest( request: { /** * The id of a document where host access request will be removed. Must be the top-level document within a tab. This or `tabId` must be specified. */ documentId?: string, /** * The id of the tab where host access request will be removed. This or `documentId` must be specified. */ tabId?: number, /** * The URL pattern where host access request will be removed. If provided, this must exactly match the pattern of an existing host access request. */ pattern?: string, }, callback?: () => void, ): void; } /** * Use the `chrome.platformKeys` API to access client certificates managed by the platform. If the user or policy grants the permission, an extension can use such a certficate in its custom authentication protocol. E.g. this allows usage of platform managed certificates in third party VPNs (see {@link vpnProvider chrome.vpnProvider}). * * @since Chrome 45 * @chrome-permission platformKeys * @chrome-platform chromeos */ export namespace platformKeys { export interface Match { /** * The DER encoding of a X.509 certificate. */ certificate: ArrayBuffer; /** * The [KeyAlgorithm](https://www.w3.org/TR/WebCryptoAPI/#key-algorithm-dictionary) of the certified key. This contains algorithm parameters that are inherent to the key of the certificate (e.g. the key length). Other parameters like the hash function used by the sign function are not included. */ keyAlgorithm: {[name: string]: any}; } export type ClientCertificateType = "rsaSign" | "ecdsaSign"; export interface ClientCertificateRequest { /** * This field is a list of the types of certificates requested, sorted in order of the server's preference. Only certificates of a type contained in this list will be retrieved. If `certificateTypes` is the empty list, however, certificates of any type will be returned. */ certificateTypes: ClientCertificateType[]; /** * List of distinguished names of certificate authorities allowed by the server. Each entry must be a DER-encoded X.509 DistinguishedName. */ certificateAuthorities: ArrayBuffer[]; } export interface SelectDetails { /** * Only certificates that match this request will be returned. */ request: ClientCertificateRequest; /** * If given, the `selectClientCertificates` operates on this list. Otherwise, obtains the list of all certificates from the platform's certificate stores that are available to this extensions. Entries that the extension doesn't have permission for or which doesn't match the request, are removed. */ clientCerts?: ArrayBuffer[]; /** * If true, the filtered list is presented to the user to manually select a certificate and thereby granting the extension access to the certificate(s) and key(s). Only the selected certificate(s) will be returned. If is false, the list is reduced to all certificates that the extension has been granted access to (automatically or manually). */ interactive: boolean; } export interface VerificationDetails { /** * Each chain entry must be the DER encoding of a X.509 certificate, the first entry must be the server certificate and each entry must certify the entry preceding it. */ serverCertificateChain: ArrayBuffer[]; /** * The hostname of the server to verify the certificate for, e.g. the server that presented the `serverCertificateChain`. */ hostname: string; } export interface VerificationResult { /** * The result of the trust verification: true if trust for the given verification details could be established and false if trust is rejected for any reason. */ trusted: boolean; /** * If the trust verification failed, this array contains the errors reported by the underlying network layer. Otherwise, this array is empty. * * **Note:** This list is meant for debugging only and may not contain all relevant errors. The errors returned may change in future revisions of this API, and are not guaranteed to be forwards or backwards compatible. */ debug_errors: string[]; } /** * This method filters from a list of client certificates the ones that are known to the platform, match `request` and for which the extension has permission to access the certificate and its private key. If `interactive` is true, the user is presented a dialog where they can select from matching certificates and grant the extension access to the certificate. The selected/filtered client certificates will be passed to `callback`. * * @chrome-returns-extra since Chrome 121 */ export function selectClientCertificates( details: SelectDetails, ): Promise; /** * This method filters from a list of client certificates the ones that are known to the platform, match `request` and for which the extension has permission to access the certificate and its private key. If `interactive` is true, the user is presented a dialog where they can select from matching certificates and grant the extension access to the certificate. The selected/filtered client certificates will be passed to `callback`. */ export function selectClientCertificates( details: SelectDetails, /** * @param matches The list of certificates that match the request, that the extension has permission for and, if `interactive` is true, that were selected by the user. */ callback?: ( matches: Match[], ) => void, ): void; /** * Passes the key pair of `certificate` for usage with {@link platformKeys.subtleCrypto} to `callback`. * * @param certificate The certificate of a {@link Match} returned by {@link selectClientCertificates}. * @param parameters Determines signature/hash algorithm parameters additionally to the parameters fixed by the key itself. The same parameters are accepted as by WebCrypto's [importKey](https://www.w3.org/TR/WebCryptoAPI/#SubtleCrypto-method-importKey) function, e.g. `RsaHashedImportParams` for a RSASSA-PKCS1-v1\_5 key and `EcKeyImportParams` for EC key. Additionally for RSASSA-PKCS1-v1\_5 keys, hashing algorithm name parameter can be specified with one of the following values: "none", "SHA-1", "SHA-256", "SHA-384", or "SHA-512", e.g. `{"hash": { "name": "none" } }`. The sign function will then apply PKCS#1 v1.5 padding but not hash the given data. Currently, this method only supports the "RSASSA-PKCS1-v1\_5" and "ECDSA" algorithms. * @param callback The public and private [CryptoKey](https://www.w3.org/TR/WebCryptoAPI/#dfn-CryptoKey) of a certificate which can only be used with {@link platformKeys.subtleCrypto}. */ export function getKeyPair( certificate: ArrayBuffer, parameters: {[name: string]: any}, /** * @param privateKey Might be `null` if this extension does not have access to it. */ callback: ( publicKey: {[name: string]: any}, privateKey?: {[name: string]: any}, ) => void, ): void; /** * Passes the key pair identified by `publicKeySpkiDer` for usage with {@link platformKeys.subtleCrypto} to `callback`. * * @param publicKeySpkiDer A DER-encoded X.509 SubjectPublicKeyInfo, obtained e.g. by calling WebCrypto's exportKey function with format="spki". * @param parameters Provides signature and hash algorithm parameters, in addition to those fixed by the key itself. The same parameters are accepted as by WebCrypto's [importKey](https://www.w3.org/TR/WebCryptoAPI/#SubtleCrypto-method-importKey) function, e.g. `RsaHashedImportParams` for a RSASSA-PKCS1-v1\_5 key. For RSASSA-PKCS1-v1\_5 keys, we need to also pass a "hash" parameter `{ "hash": { "name": string } }`. The "hash" parameter represents the name of the hashing algorithm to be used in the digest operation before a sign. It is possible to pass "none" as the hash name, in which case the sign function will apply PKCS#1 v1.5 padding and but not hash the given data. Currently, this method supports the "ECDSA" algorithm with named-curve P-256 and "RSASSA-PKCS1-v1\_5" algorithm with one of the hashing algorithms "none", "SHA-1", "SHA-256", "SHA-384", and "SHA-512". * @param callback The public and private [CryptoKey](https://www.w3.org/TR/WebCryptoAPI/#dfn-CryptoKey) of a certificate which can only be used with {@link platformKeys.subtleCrypto}. * @since Chrome 85 */ export function getKeyPairBySpki( publicKeySpkiDer: ArrayBuffer, parameters: {[name: string]: any}, /** * @param privateKey Might be `null` if this extension does not have access to it. */ callback: ( publicKey: {[name: string]: any}, privateKey?: {[name: string]: any}, ) => void, ): void; /** * An implementation of WebCrypto's [SubtleCrypto](https://www.w3.org/TR/WebCryptoAPI/#subtlecrypto-interface) that allows crypto operations on keys of client certificates that are available to this extension. */ export function subtleCrypto(): {[name: string]: any} | undefined; /** * Checks whether `details.serverCertificateChain` can be trusted for `details.hostname` according to the trust settings of the platform. Note: The actual behavior of the trust verification is not fully specified and might change in the future. The API implementation verifies certificate expiration, validates the certification path and checks trust by a known CA. The implementation is supposed to respect the EKU serverAuth and to support subject alternative names. * * @chrome-returns-extra since Chrome 121 */ export function verifyTLSServerCertificate( details: VerificationDetails, ): Promise; /** * Checks whether `details.serverCertificateChain` can be trusted for `details.hostname` according to the trust settings of the platform. Note: The actual behavior of the trust verification is not fully specified and might change in the future. The API implementation verifies certificate expiration, validates the certification path and checks trust by a known CA. The implementation is supposed to respect the EKU serverAuth and to support subject alternative names. */ export function verifyTLSServerCertificate( details: VerificationDetails, callback?: ( result: VerificationResult, ) => void, ): void; } /** * Use the `chrome.power` API to override the system's power management features. * * @chrome-permission power */ export namespace power { /** * @chrome-enum "system" Prevents the system from sleeping in response to user inactivity. * @chrome-enum "display" Prevents the display from being turned off or dimmed, or the system from sleeping in response to user inactivity. */ export type Level = "system" | "display"; /** * Requests that power management be temporarily disabled. `level` describes the degree to which power management should be disabled. If a request previously made by the same app is still active, it will be replaced by the new request. */ export function requestKeepAwake( level: Level, ): void; /** * Releases a request previously made via requestKeepAwake(). */ export function releaseKeepAwake(): void; /** * Reports a user activity in order to awake the screen from a dimmed or turned off state or from a screensaver. Exits the screensaver if it is currently active. * * @since Chrome 113 * @chrome-platform chromeos */ export function reportActivity(): Promise; /** * Reports a user activity in order to awake the screen from a dimmed or turned off state or from a screensaver. Exits the screensaver if it is currently active. * * @since Chrome 113 * @chrome-platform chromeos */ export function reportActivity( callback?: () => void, ): void; } /** * The `chrome.printerProvider` API exposes events used by print manager to query printers controlled by extensions, to query their capabilities and to submit print jobs to these printers. * * @since Chrome 44 * @chrome-permission printerProvider * @chrome-platform chromeos * @chrome-platform linux * @chrome-platform mac * @chrome-platform win */ export namespace printerProvider { /** * Error codes returned in response to {@link onPrintRequested} event. * * @chrome-enum "OK" Specifies that the operation was completed successfully. * @chrome-enum "FAILED" Specifies that a general failure occured. * @chrome-enum "INVALID\_TICKET" Specifies that the print ticket is invalid. For example, the ticket is inconsistent with some capabilities, or the extension is not able to handle all settings from the ticket. * @chrome-enum "INVALID\_DATA" Specifies that the document is invalid. For example, data may be corrupted or the format is incompatible with the extension. */ export type PrintError = "OK" | "FAILED" | "INVALID_TICKET" | "INVALID_DATA"; export interface PrinterInfo { /** * Unique printer ID. */ id: string; /** * Printer's human readable name. */ name: string; /** * Printer's human readable description. */ description?: string; } export interface PrintJob { /** * ID of the printer which should handle the job. */ printerId: string; /** * The print job title. */ title: string; /** * Print ticket in [CJT format](https://developers.google.com/cloud-print/docs/cdd#cjt). * * The CJT reference is marked as deprecated. It is deprecated for Google Cloud Print only. is not deprecated for ChromeOS printing. */ ticket: {[name: string]: any}; /** * The document content type. Supported formats are `"application/pdf"` and `"image/pwg-raster"`. */ contentType: string; /** * Blob containing the document data to print. Format must match `contentType`. */ document: Blob; } /** * Event fired when print manager requests printers provided by extensions. */ export const onGetPrintersRequested: events.Event<( resultCallback: ( printerInfo: PrinterInfo[], ) => void, ) => void>; /** * Event fired when print manager requests information about a USB device that may be a printer. * * _Note:_ An application should not rely on this event being fired more than once per device. If a connected device is supported it should be returned in the {@link onGetPrintersRequested} event. * * @since Chrome 45 */ export const onGetUsbPrinterInfoRequested: events.Event<( device: usb.Device, resultCallback: ( printerInfo?: PrinterInfo, ) => void, ) => void>; /** * Event fired when print manager requests printer capabilities. */ export const onGetCapabilityRequested: events.Event<( printerId: string, /** * @param capabilities Device capabilities in [CDD format](https://developers.google.com/cloud-print/docs/cdd#cdd). */ resultCallback: ( capabilities: {[name: string]: any}, ) => void, ) => void>; /** * Event fired when print manager requests printing. */ export const onPrintRequested: events.Event<( printJob: PrintJob, resultCallback: ( result: PrintError, ) => void, ) => void>; } /** * Use the `chrome.printing` API to send print jobs to printers installed on Chromebook. * * @since Chrome 81 * @chrome-permission printing * @chrome-platform chromeos */ export namespace printing { export interface SubmitJobRequest { /** * The print job to be submitted. Supported content types are "application/pdf" and "image/png". The [Cloud Job Ticket](https://developers.google.com/cloud-print/docs/cdd#cjt) shouldn't include `FitToPageTicketItem`, `PageRangeTicketItem` and `ReverseOrderTicketItem` fields since they are irrelevant for native printing. `VendorTicketItem` is optional. All other fields must be present. */ job: printerProvider.PrintJob; } /** * The status of {@link submitJob} request. * * @chrome-enum "OK" Sent print job request is accepted. * @chrome-enum "USER\_REJECTED" Sent print job request is rejected by the user. */ export type SubmitJobStatus = "OK" | "USER_REJECTED"; export interface SubmitJobResponse { /** * The status of the request. */ status: SubmitJobStatus; /** * The id of created print job. This is a unique identifier among all print jobs on the device. If status is not OK, jobId will be null. */ jobId?: string; } /** * The source of the printer. * * @chrome-enum "USER" Printer was added by user. * @chrome-enum "POLICY" Printer was added via policy. */ export type PrinterSource = "USER" | "POLICY"; export interface Printer { /** * The printer's identifier; guaranteed to be unique among printers on the device. */ id: string; /** * The name of the printer. */ name: string; /** * The human-readable description of the printer. */ description: string; /** * The printer URI. This can be used by extensions to choose the printer for the user. */ uri: string; /** * The source of the printer (user or policy configured). */ source: PrinterSource; /** * The flag which shows whether the printer fits [DefaultPrinterSelection](https://chromium.org/administrators/policy-list-3#DefaultPrinterSelection) rules. Note that several printers could be flagged. */ isDefault: boolean; /** * The value showing how recent the printer was used for printing from Chrome. The lower the value is the more recent the printer was used. The minimum value is 0. Missing value indicates that the printer wasn't used recently. This value is guaranteed to be unique amongst printers. */ recentlyUsedRank?: number; } /** * The status of the printer. * * @chrome-enum "DOOR\_OPEN" The door of the printer is open. Printer still accepts print jobs. * @chrome-enum "TRAY\_MISSING" The tray of the printer is missing. Printer still accepts print jobs. * @chrome-enum "OUT\_OF\_INK" The printer is out of ink. Printer still accepts print jobs. * @chrome-enum "OUT\_OF\_PAPER" The printer is out of paper. Printer still accepts print jobs. * @chrome-enum "OUTPUT\_FULL" The output area of the printer (e.g. tray) is full. Printer still accepts print jobs. * @chrome-enum "PAPER\_JAM" The printer has a paper jam. Printer still accepts print jobs. * @chrome-enum "GENERIC\_ISSUE" Some generic issue. Printer still accepts print jobs. * @chrome-enum "STOPPED" The printer is stopped and doesn't print but still accepts print jobs. * @chrome-enum "UNREACHABLE" The printer is unreachable and doesn't accept print jobs. * @chrome-enum "EXPIRED\_CERTIFICATE" The SSL certificate is expired. Printer accepts jobs but they fail. * @chrome-enum "AVAILABLE" The printer is available. */ export type PrinterStatus = "DOOR_OPEN" | "TRAY_MISSING" | "OUT_OF_INK" | "OUT_OF_PAPER" | "OUTPUT_FULL" | "PAPER_JAM" | "GENERIC_ISSUE" | "STOPPED" | "UNREACHABLE" | "EXPIRED_CERTIFICATE" | "AVAILABLE"; export interface GetPrinterInfoResponse { /** * Printer capabilities in [CDD format](https://developers.google.com/cloud-print/docs/cdd#cdd). The property may be missing. */ capabilities?: {[name: string]: any}; /** * The status of the printer. */ status: PrinterStatus; } /** * Status of the print job. * * @chrome-enum "PENDING" Print job is received on Chrome side but was not processed yet. * @chrome-enum "IN\_PROGRESS" Print job is sent for printing. * @chrome-enum "FAILED" Print job was interrupted due to some error. * @chrome-enum "CANCELED" Print job was canceled by the user or via API. * @chrome-enum "PRINTED" Print job was printed without any errors. */ export type JobStatus = "PENDING" | "IN_PROGRESS" | "FAILED" | "CANCELED" | "PRINTED"; /** * The maximum number of times that {@link submitJob} can be called per minute. */ export const MAX_SUBMIT_JOB_CALLS_PER_MINUTE: 40; /** * The maximum number of times that {@link getPrinterInfo} can be called per minute. */ export const MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE: 20; /** * Event fired when the status of the job is changed. This is only fired for the jobs created by this extension. */ export const onJobStatusChanged: events.Event<( jobId: string, status: JobStatus, ) => void>; /** * Submits the job for printing. If the extension is not listed in the [`PrintingAPIExtensionsAllowlist`](https://chromeenterprise.google/policies/#PrintingAPIExtensionsAllowlist) policy, the user is prompted to accept the print job. * Before Chrome 120, this function did not return a promise. * * @chrome-returns-extra since Chrome 100 */ export function submitJob( request: SubmitJobRequest, ): Promise; /** * Submits the job for printing. If the extension is not listed in the [`PrintingAPIExtensionsAllowlist`](https://chromeenterprise.google/policies/#PrintingAPIExtensionsAllowlist) policy, the user is prompted to accept the print job. * Before Chrome 120, this function did not return a promise. */ export function submitJob( request: SubmitJobRequest, callback?: ( response: SubmitJobResponse, ) => void, ): void; /** * Cancels previously submitted job. * * @chrome-returns-extra since Chrome 100 * @param jobId The id of the print job to cancel. This should be the same id received in a {@link SubmitJobResponse}. */ export function cancelJob( jobId: string, ): Promise; /** * Cancels previously submitted job. * * @param jobId The id of the print job to cancel. This should be the same id received in a {@link SubmitJobResponse}. */ export function cancelJob( jobId: string, callback?: () => void, ): void; /** * Returns the list of available printers on the device. This includes manually added, enterprise and discovered printers. * * @chrome-returns-extra since Chrome 100 */ export function getPrinters(): Promise; /** * Returns the list of available printers on the device. This includes manually added, enterprise and discovered printers. */ export function getPrinters( callback?: ( printers: Printer[], ) => void, ): void; /** * Returns the status and capabilities of the printer in [CDD format](https://developers.google.com/cloud-print/docs/cdd#cdd). This call will fail with a runtime error if no printers with given id are installed. * * @chrome-returns-extra since Chrome 100 */ export function getPrinterInfo( printerId: string, ): Promise; /** * Returns the status and capabilities of the printer in [CDD format](https://developers.google.com/cloud-print/docs/cdd#cdd). This call will fail with a runtime error if no printers with given id are installed. */ export function getPrinterInfo( printerId: string, callback?: ( response: GetPrinterInfoResponse, ) => void, ): void; /** * Returns the status of the print job. This call will fail with a runtime error if the print job with the given `jobId` doesn't exist. `jobId`: The id of the print job to return the status of. This should be the same id received in a {@link SubmitJobResponse}. * * @since Chrome 135 */ export function getJobStatus( jobId: string, ): Promise; /** * Returns the status of the print job. This call will fail with a runtime error if the print job with the given `jobId` doesn't exist. `jobId`: The id of the print job to return the status of. This should be the same id received in a {@link SubmitJobResponse}. * * @since Chrome 135 */ export function getJobStatus( jobId: string, callback?: ( status: JobStatus, ) => void, ): void; } /** * Use the `chrome.printingMetrics` API to fetch data about printing usage. * * @since Chrome 79 * @chrome-permission printingMetrics * @chrome-install-location policy * @chrome-platform chromeos */ export namespace printingMetrics { /** * The source of the print job. * * @chrome-enum "PRINT\_PREVIEW" Specifies that the job was created from the Print Preview page initiated by the user. * @chrome-enum "ANDROID\_APP" Specifies that the job was created from an Android App. * @chrome-enum "EXTENSION" Specifies that the job was created by extension via Chrome API. * @chrome-enum "ISOLATED\_WEB\_APP" Specifies that the job was created by an Isolated Web App via API. */ export type PrintJobSource = "PRINT_PREVIEW" | "ANDROID_APP" | "EXTENSION" | "ISOLATED_WEB_APP"; /** * Specifies the final status of the print job. * * @chrome-enum "FAILED" Specifies that the print job was interrupted due to some error. * @chrome-enum "CANCELED" Specifies that the print job was canceled by the user or via API. * @chrome-enum "PRINTED" Specifies that the print job was printed without any errors. */ export type PrintJobStatus = "FAILED" | "CANCELED" | "PRINTED"; /** * The source of the printer. * * @chrome-enum "USER" Specifies that the printer was added by user. * @chrome-enum "POLICY" Specifies that the printer was added via policy. */ export type PrinterSource = "USER" | "POLICY"; /** * @chrome-enum "BLACK\_AND\_WHITE" Specifies that black and white mode was used. * @chrome-enum "COLOR" Specifies that color mode was used. */ export type ColorMode = "BLACK_AND_WHITE" | "COLOR"; /** * @chrome-enum "ONE\_SIDED" Specifies that one-sided printing was used. * @chrome-enum "TWO\_SIDED\_LONG\_EDGE" Specifies that two-sided printing was used, flipping on long edge. * @chrome-enum "TWO\_SIDED\_SHORT\_EDGE" Specifies that two-sided printing was used, flipping on short edge. */ export type DuplexMode = "ONE_SIDED" | "TWO_SIDED_LONG_EDGE" | "TWO_SIDED_SHORT_EDGE"; export interface MediaSize { /** * Width (in micrometers) of the media used for printing. */ width: number; /** * Height (in micrometers) of the media used for printing. */ height: number; /** * Vendor-provided ID, e.g. "iso\_a3\_297x420mm" or "na\_index-3x5\_3x5in". Possible values are values of "media" IPP attribute and can be found on [IANA page](https://www.iana.org/assignments/ipp-registrations/ipp-registrations.xhtml) . */ vendorId: string; } export interface PrintSettings { /** * The requested color mode. */ color: ColorMode; /** * The requested duplex mode. */ duplex: DuplexMode; /** * The requested media size. */ mediaSize: MediaSize; /** * The requested number of copies. */ copies: number; } export interface Printer { /** * Displayed name of the printer. */ name: string; /** * The full path for the printer. Contains protocol, hostname, port, and queue. */ uri: string; /** * The source of the printer. */ source: PrinterSource; } export interface PrintJobInfo { /** * The ID of the job. */ id: string; /** * The title of the document which was printed. */ title: string; /** * Source showing who initiated the print job. */ source: PrintJobSource; /** * ID of source. Null if source is PRINT\_PREVIEW or ANDROID\_APP. */ sourceId?: string; /** * The final status of the job. */ status: PrintJobStatus; /** * The job creation time (in milliseconds past the Unix epoch). */ creationTime: number; /** * The job completion time (in milliseconds past the Unix epoch). */ completionTime: number; /** * The info about the printer which printed the document. */ printer: Printer; /** * The settings of the print job. */ settings: PrintSettings; /** * The number of pages in the document. */ numberOfPages: number; /** * The status of the printer. * * @since Chrome 85 */ printer_status: printing.PrinterStatus; } /** * Event fired when the print job is finished. This includes any of termination statuses: FAILED, CANCELED and PRINTED. */ export const onPrintJobFinished: events.Event<( jobInfo: PrintJobInfo, ) => void>; /** * Returns the list of the finished print jobs. * * @chrome-returns-extra since Chrome 96 */ export function getPrintJobs(): Promise; /** * Returns the list of the finished print jobs. */ export function getPrintJobs( callback?: ( jobs: PrintJobInfo[], ) => void, ): void; } /** * Use the `chrome.privacy` API to control usage of the features in Chrome that can affect a user's privacy. This API relies on the [ChromeSetting prototype of the type API](https://developer.chrome.com/docs/extensions/reference/types/#ChromeSetting) for getting and setting Chrome's configuration. * * @chrome-permission privacy */ export namespace privacy { /** * The IP handling policy of WebRTC. * * @since Chrome 48 */ export type IPHandlingPolicy = "default" | "default_public_and_private_interfaces" | "default_public_interface_only" | "disable_non_proxied_udp"; /** * Settings that influence Chrome's handling of network connections in general. */ export const network: { /** * If enabled, Chrome attempts to speed up your web browsing experience by pre-resolving DNS entries and preemptively opening TCP and SSL connections to servers. This preference only affects actions taken by Chrome's internal prediction service. It does not affect webpage-initiated prefectches or preconnects. This preference's value is a boolean, defaulting to `true`. */ networkPredictionEnabled: types.ChromeSetting, /** * Allow users to specify the media performance/privacy tradeoffs which impacts how WebRTC traffic will be routed and how much local address information is exposed. This preference's value is of type IPHandlingPolicy, defaulting to `default`. * * @since Chrome 48 */ webRTCIPHandlingPolicy: types.ChromeSetting, }; /** * Settings that enable or disable features that require third-party network services provided by Google and your default search provider. */ export const services: { /** * If enabled, Chrome uses a web service to help resolve navigation errors. This preference's value is a boolean, defaulting to `true`. */ alternateErrorPagesEnabled: types.ChromeSetting, /** * If enabled, Chrome offers to automatically fill in forms. This preference's value is a boolean, defaulting to `true`. * * @deprecated Please use privacy.services.autofillAddressEnabled and privacy.services.autofillCreditCardEnabled. This remains for backward compatibility in this release and will be removed in the future. * @chrome-deprecated-since Chrome 70 */ autofillEnabled: types.ChromeSetting, /** * If enabled, Chrome offers to automatically fill in addresses and other form data. This preference's value is a boolean, defaulting to `true`. * * @since Chrome 70 */ autofillAddressEnabled: types.ChromeSetting, /** * If enabled, Chrome offers to automatically fill in credit card forms. This preference's value is a boolean, defaulting to `true`. * * @since Chrome 70 */ autofillCreditCardEnabled: types.ChromeSetting, /** * If enabled, the password manager will ask if you want to save passwords. This preference's value is a boolean, defaulting to `true`. */ passwordSavingEnabled: types.ChromeSetting, /** * If enabled, Chrome does its best to protect you from phishing and malware. This preference's value is a boolean, defaulting to `true`. */ safeBrowsingEnabled: types.ChromeSetting, /** * If enabled, Chrome will send additional information to Google when SafeBrowsing blocks a page, such as the content of the blocked page. This preference's value is a boolean, defaulting to `false`. */ safeBrowsingExtendedReportingEnabled: types.ChromeSetting, /** * If enabled, Chrome sends the text you type into the Omnibox to your default search engine, which provides predictions of websites and searches that are likely completions of what you've typed so far. This preference's value is a boolean, defaulting to `true`. */ searchSuggestEnabled: types.ChromeSetting, /** * If enabled, Chrome uses a web service to help correct spelling errors. This preference's value is a boolean, defaulting to `false`. */ spellingServiceEnabled: types.ChromeSetting, /** * If enabled, Chrome offers to translate pages that aren't in a language you read. This preference's value is a boolean, defaulting to `true`. */ translationServiceEnabled: types.ChromeSetting, }; /** * Settings that determine what information Chrome makes available to websites. */ export const websites: { /** * If disabled, Chrome blocks third-party sites from setting cookies. The value of this preference is of type boolean, and the default value is `true`. Extensions may not enable this API in Incognito mode, where third-party cookies are blocked and can only be allowed at the site level. If you try setting this API to true in Incognito, it will throw an error. * * Note: Individual sites may still be able to access third-party cookies when this API returns `false`, if they have a valid [exemption](https://developers.google.com/privacy-sandbox/cookies/temporary-exceptions/preserving-critical-user-experiences) or they use the [Storage Access API](https://developers.google.com/privacy-sandbox/cookies/storage-access-api) instead. */ thirdPartyCookiesAllowed: types.ChromeSetting, /** * If disabled, the [Topics API](https://developer.chrome.com/en/docs/privacy-sandbox/topics/) is deactivated. The value of this preference is of type boolean, and the default value is `true`. Extensions may only disable this API by setting the value to `false`. If you try setting this API to `true`, it will throw an error. * * @since Chrome 111 */ topicsEnabled: types.ChromeSetting, /** * If disabled, the [Fledge API](https://developer.chrome.com/docs/privacy-sandbox/fledge/) is deactivated. The value of this preference is of type boolean, and the default value is `true`. Extensions may only disable this API by setting the value to `false`. If you try setting this API to `true`, it will throw an error. * * @since Chrome 111 */ fledgeEnabled: types.ChromeSetting, /** * If disabled, the [Attribution Reporting API](https://developer.chrome.com/en/docs/privacy-sandbox/attribution-reporting/) and [Private Aggregation API](https://developer.chrome.com/docs/privacy-sandbox/private-aggregation/) are deactivated. The value of this preference is of type boolean, and the default value is `true`. Extensions may only disable these APIs by setting the value to `false`. If you try setting these APIs to `true`, it will throw an error. * * @since Chrome 111 */ adMeasurementEnabled: types.ChromeSetting, /** * If enabled, Chrome sends auditing pings when requested by a website (``). The value of this preference is of type boolean, and the default value is `true`. */ hyperlinkAuditingEnabled: types.ChromeSetting, /** * If enabled, Chrome sends `referer` headers with your requests. Yes, the name of this preference doesn't match the misspelled header. No, we're not going to change it. The value of this preference is of type boolean, and the default value is `true`. */ referrersEnabled: types.ChromeSetting, /** * If enabled, Chrome sends 'Do Not Track' (`DNT: 1`) header with your requests. The value of this preference is of type boolean, and the default value is `false`. * * @since Chrome 65 */ doNotTrackEnabled: types.ChromeSetting, /** * **Available on Windows and ChromeOS only**: If enabled, Chrome provides a unique ID to plugins in order to run protected content. The value of this preference is of type boolean, and the default value is `true`. */ protectedContentEnabled: types.ChromeSetting, /** * If disabled, [Related Website Sets](https://developer.chrome.com/docs/privacy-sandbox/related-website-sets/) is deactivated. The value of this preference is of type boolean, and the default value is `true`. Extensions may only disable this API by setting the value to `false`. If you try setting this API to `true`, it will throw an error. * * @since Chrome 121 */ relatedWebsiteSetsEnabled: types.ChromeSetting, }; } /** * Use the `chrome.processes` API to interact with the browser's processes. * * @alpha * @chrome-permission processes * @chrome-channel dev */ export namespace processes { /** * The types of the browser processes. * * @chrome-enum "worker" Obsolete, will never be returned. * @chrome-enum "service\_worker" Obsolete, will never be returned. */ export type ProcessType = "browser" | "renderer" | "extension" | "notification" | "plugin" | "worker" | "nacl" | "service_worker" | "utility" | "gpu" | "other"; export interface TaskInfo { /** * The title of the task. */ title: string; /** * Optional tab ID, if this task represents a tab running on a renderer process. */ tabId?: number; } export interface Cache { /** * The size of the cache, in bytes. */ size: number; /** * The part of the cache that is utilized, in bytes. */ liveSize: number; } export interface Process { /** * Unique ID of the process provided by the browser. */ id: number; /** * The ID of the process, as provided by the OS. */ osProcessId: number; /** * The type of process. */ type: ProcessType; /** * The profile which the process is associated with. */ profile: string; /** * The debugging port for Native Client processes. Zero for other process types and for NaCl processes that do not have debugging enabled. */ naclDebugPort: number; /** * Array of TaskInfos representing the tasks running on this process. */ tasks: TaskInfo[]; /** * The most recent measurement of the process's CPU usage, expressed as the percentage of a single CPU core used in total, by all of the process's threads. This gives a value from zero to CpuInfo.numOfProcessors\*100, which can exceed 100% in multi-threaded processes. Only available when receiving the object as part of a callback from onUpdated or onUpdatedWithMemory. */ cpu?: number; /** * The most recent measurement of the process network usage, in bytes per second. Only available when receiving the object as part of a callback from onUpdated or onUpdatedWithMemory. */ network?: number; /** * The most recent measurement of the process private memory usage, in bytes. Only available when receiving the object as part of a callback from onUpdatedWithMemory or getProcessInfo with the includeMemory flag. */ privateMemory?: number; /** * The most recent measurement of the process JavaScript allocated memory, in bytes. Only available when receiving the object as part of a callback from onUpdated or onUpdatedWithMemory. */ jsMemoryAllocated?: number; /** * The most recent measurement of the process JavaScript memory used, in bytes. Only available when receiving the object as part of a callback from onUpdated or onUpdatedWithMemory. */ jsMemoryUsed?: number; /** * The most recent measurement of the process's SQLite memory usage, in bytes. Only available when receiving the object as part of a callback from onUpdated or onUpdatedWithMemory. */ sqliteMemory?: number; /** * The most recent information about the image cache for the process. Only available when receiving the object as part of a callback from onUpdated or onUpdatedWithMemory. */ imageCache?: Cache; /** * The most recent information about the script cache for the process. Only available when receiving the object as part of a callback from onUpdated or onUpdatedWithMemory. */ scriptCache?: Cache; /** * The most recent information about the CSS cache for the process. Only available when receiving the object as part of a callback from onUpdated or onUpdatedWithMemory. */ cssCache?: Cache; } /** * Fired each time the Task Manager updates its process statistics, providing the dictionary of updated Process objects, indexed by process ID. */ export const onUpdated: events.Event<( processes: {[name: string]: any}, ) => void>; /** * Fired each time the Task Manager updates its process statistics, providing the dictionary of updated Process objects, indexed by process ID. Identical to onUpdate, with the addition of memory usage details included in each Process object. Note, collecting memory usage information incurs extra CPU usage and should only be listened for when needed. */ export const onUpdatedWithMemory: events.Event<( processes: {[name: string]: any}, ) => void>; /** * Fired each time a process is created, providing the corrseponding Process object. */ export const onCreated: events.Event<( process: Process, ) => void>; /** * Fired each time a process becomes unresponsive, providing the corrseponding Process object. */ export const onUnresponsive: events.Event<( process: Process, ) => void>; /** * Fired each time a process is terminated, providing the type of exit. */ export const onExited: events.Event<( processId: number, exitType: number, exitCode: number, ) => void>; /** * Returns the ID of the renderer process for the specified tab. * * @param tabId The ID of the tab for which the renderer process ID is to be returned. * @returns A callback to return the ID of the renderer process of a tab. */ export function getProcessIdForTab( tabId: number, ): Promise; /** * Returns the ID of the renderer process for the specified tab. * * @param tabId The ID of the tab for which the renderer process ID is to be returned. */ export function getProcessIdForTab( tabId: number, /** * @param processId Process ID of the tab's renderer process. */ callback?: ( processId: number, ) => void, ): void; /** * Terminates the specified renderer process. Equivalent to visiting about:crash, but without changing the tab's URL. * * @param processId The ID of the process to be terminated. * @returns A callback to report the status of the termination. */ export function terminate( processId: number, ): Promise; /** * Terminates the specified renderer process. Equivalent to visiting about:crash, but without changing the tab's URL. * * @param processId The ID of the process to be terminated. */ export function terminate( processId: number, /** * @param didTerminate True if terminating the process was successful, and false otherwise. */ callback?: ( didTerminate: boolean, ) => void, ): void; /** * Retrieves the process information for each process ID specified. * * @param processIds The list of process IDs or single process ID for which to return the process information. An empty list indicates all processes are requested. * @param includeMemory True if detailed memory usage is required. Note, collecting memory usage information incurs extra CPU usage and should only be queried for when needed. * @returns A callback called when the processes information is collected. */ export function getProcessInfo( processIds: number | number[], includeMemory: boolean, ): Promise<{[name: string]: any}>; /** * Retrieves the process information for each process ID specified. * * @param processIds The list of process IDs or single process ID for which to return the process information. An empty list indicates all processes are requested. * @param includeMemory True if detailed memory usage is required. Note, collecting memory usage information incurs extra CPU usage and should only be queried for when needed. */ export function getProcessInfo( processIds: number | number[], includeMemory: boolean, /** * @param processes A dictionary of {@link Process} objects for each requested process that is a live child process of the current browser process, indexed by process ID. Metrics requiring aggregation over time will not be populated in each Process object. */ callback?: ( processes: {[name: string]: any}, ) => void, ): void; } /** * `protocol_handlers` manifest key defintion. Protocol Handlers allow developers to let extensions register Custom Handlers for URL's schemes unknown to the Browser. This manifest key provides a similar behavior than the Web API implementing the Custom Handlers section of the HTML specification. https://html.spec.whatwg.org/#custom-handlers * * @since Chrome 140 */ export namespace protocolHandlers { export interface ProtocolHandler { /** * A string definition of the protocol to handle. */ protocol: string; /** * A string representation of the protocol handlers, displayed to the user when prompting for permissions. */ name: string; /** * A string representing the URL of the protocol handler (must be a localizable property). */ uriTemplate: string; } } /** * Use the `chrome.proxy` API to manage Chrome's proxy settings. This API relies on the [ChromeSetting prototype of the type API](https://developer.chrome.com/docs/extensions/reference/api/types#type-ChromeSetting) for getting and setting the proxy configuration. * * @chrome-permission proxy */ export namespace proxy { /** * @since Chrome 54 */ export type Scheme = "http" | "https" | "quic" | "socks4" | "socks5"; /** * @since Chrome 54 */ export type Mode = "direct" | "auto_detect" | "pac_script" | "fixed_servers" | "system"; /** * An object encapsulating a single proxy server's specification. */ export interface ProxyServer { /** * The scheme (protocol) of the proxy server itself. Defaults to 'http'. */ scheme?: Scheme; /** * The hostname or IP address of the proxy server. Hostnames must be in ASCII (in Punycode format). IDNA is not supported, yet. */ host: string; /** * The port of the proxy server. Defaults to a port that depends on the scheme. */ port?: number; } /** * An object encapsulating the set of proxy rules for all protocols. Use either 'singleProxy' or (a subset of) 'proxyForHttp', 'proxyForHttps', 'proxyForFtp' and 'fallbackProxy'. */ export interface ProxyRules { /** * The proxy server to be used for all per-URL requests (that is http, https, and ftp). */ singleProxy?: ProxyServer; /** * The proxy server to be used for HTTP requests. */ proxyForHttp?: ProxyServer; /** * The proxy server to be used for HTTPS requests. */ proxyForHttps?: ProxyServer; /** * The proxy server to be used for FTP requests. */ proxyForFtp?: ProxyServer; /** * The proxy server to be used for everthing else or if any of the specific proxyFor... is not specified. */ fallbackProxy?: ProxyServer; /** * List of servers to connect to without a proxy server. */ bypassList?: string[]; } /** * An object holding proxy auto-config information. Exactly one of the fields should be non-empty. */ export interface PacScript { /** * URL of the PAC file to be used. */ url?: string; /** * A PAC script. */ data?: string; /** * If true, an invalid PAC script will prevent the network stack from falling back to direct connections. Defaults to false. */ mandatory?: boolean; } /** * An object encapsulating a complete proxy configuration. */ export interface ProxyConfig { /** * The proxy rules describing this configuration. Use this for 'fixed\_servers' mode. */ rules?: ProxyRules; /** * The proxy auto-config (PAC) script for this configuration. Use this for 'pac\_script' mode. */ pacScript?: PacScript; /** * 'direct' = Never use a proxy * 'auto\_detect' = Auto detect proxy settings * 'pac\_script' = Use specified PAC script * 'fixed\_servers' = Manually specify proxy servers * 'system' = Use system proxy settings */ mode: Mode; } /** * Proxy settings to be used. The value of this setting is a ProxyConfig object. */ export const settings: types.ChromeSetting; /** * Notifies about proxy errors. */ export const onProxyError: events.Event<( details: { /** * If true, the error was fatal and the network transaction was aborted. Otherwise, a direct connection is used instead. */ fatal: boolean, /** * The error description. */ error: string, /** * Additional details about the error such as a JavaScript runtime error. */ details: string, }, ) => void>; } /** * Use the `chrome.readingList` API to read from and modify the items in the [Reading List](https://support.google.com/chrome/answer/7343019). * * @since Chrome 120 * @chrome-permission readingList * @chrome-min-manifest MV3 */ export namespace readingList { export interface ReadingListEntry { /** * The url of the entry. */ url: string; /** * The title of the entry. */ title: string; /** * Will be `true` if the entry has been read. */ hasBeenRead: boolean; /** * The last time the entry was updated. This value is in milliseconds since Jan 1, 1970. */ lastUpdateTime: number; /** * The time the entry was created. Recorded in milliseconds since Jan 1, 1970. */ creationTime: number; } export interface AddEntryOptions { /** * The url of the entry. */ url: string; /** * The title of the entry. */ title: string; /** * Will be `true` if the entry has been read. */ hasBeenRead: boolean; } export interface RemoveOptions { /** * The url to remove. */ url: string; } export interface UpdateEntryOptions { /** * The url that will be updated. */ url: string; /** * The new title. The existing tile remains if a value isn't provided. */ title?: string; /** * The updated read status. The existing status remains if a value isn't provided. */ hasBeenRead?: boolean; } export interface QueryInfo { /** * A url to search for. */ url?: string; /** * A title to search for. */ title?: string; /** * Indicates whether to search for read (`true`) or unread (`false`) items. */ hasBeenRead?: boolean; } /** * Triggered when a `ReadingListEntry` is added to the reading list. */ export const onEntryAdded: events.Event<( entry: ReadingListEntry, ) => void>; /** * Triggered when a `ReadingListEntry` is removed from the reading list. */ export const onEntryRemoved: events.Event<( entry: ReadingListEntry, ) => void>; /** * Triggered when a `ReadingListEntry` is updated in the reading list. */ export const onEntryUpdated: events.Event<( entry: ReadingListEntry, ) => void>; /** * Adds an entry to the reading list if it does not exist. * * @param entry The entry to add to the reading list. * @returns Resolves once the entry has been added. */ export function addEntry( entry: AddEntryOptions, ): Promise; /** * Adds an entry to the reading list if it does not exist. * * @param entry The entry to add to the reading list. */ export function addEntry( entry: AddEntryOptions, callback?: () => void, ): void; /** * Removes an entry from the reading list if it exists. * * @param info The entry to remove from the reading list. * @returns Resolves once the entry has been removed. */ export function removeEntry( info: RemoveOptions, ): Promise; /** * Removes an entry from the reading list if it exists. * * @param info The entry to remove from the reading list. */ export function removeEntry( info: RemoveOptions, callback?: () => void, ): void; /** * Updates a reading list entry if it exists. * * @param info The entry to update. * @returns Resolves once the matched entries have been updated. */ export function updateEntry( info: UpdateEntryOptions, ): Promise; /** * Updates a reading list entry if it exists. * * @param info The entry to update. */ export function updateEntry( info: UpdateEntryOptions, callback?: () => void, ): void; /** * Retrieves all entries that match the `QueryInfo` properties. Properties that are not provided will not be matched. * * @param info The properties to search for. * @returns Resolves once the entries have been matched. */ export function query( info: QueryInfo, ): Promise; /** * Retrieves all entries that match the `QueryInfo` properties. Properties that are not provided will not be matched. * * @param info The properties to search for. */ export function query( info: QueryInfo, callback?: ( entries: ReadingListEntry[], ) => void, ): void; } /** * Use the `chrome.runtime` API to retrieve the service worker, return details about the manifest, and listen for and respond to events in the extension lifecycle. You can also use this API to convert the relative path of URLs to fully-qualified URLs. */ export namespace runtime { /** * An object which allows two way communication with other pages. See [Long-lived connections](https://developer.chrome.com/docs/extensions/messaging#connect) for more information. */ export interface Port { /** * The name of the port, as specified in the call to {@link runtime.connect}. */ name: string; /** * Immediately disconnect the port. Calling `disconnect()` on an already-disconnected port has no effect. When a port is disconnected, no new events will be dispatched to this port. */ disconnect(): void; /** * Send a message to the other end of the port. If the port is disconnected, an error is thrown. * * @param message The message to send. This object should be JSON-ifiable. */ postMessage( /** * @since Chrome 52 */ message: any, ): void; /** * This property will **only** be present on ports passed to {@link runtime.onConnect onConnect} / {@link runtime.onConnectExternal onConnectExternal} / {@link runtime.onConnectExternal onConnectNative} listeners. */ sender?: MessageSender; /** * Fired when the port is disconnected from the other end(s). {@link runtime.lastError} may be set if the port was disconnected by an error. If the port is closed via {@link Port.disconnect disconnect}, then this event is _only_ fired on the other end. This event is fired at most once (see also [Port lifetime](https://developer.chrome.com/docs/extensions/messaging#port-lifetime)). */ onDisconnect: events.Event<( port: Port, ) => void>; /** * This event is fired when {@link Port.postMessage postMessage} is called by the other end of the port. */ onMessage: events.Event<( message: any, port: Port, ) => void>; } /** * An object containing information about the script context that sent a message or request. */ export interface MessageSender { /** * The {@link tabs.Tab} which opened the connection, if any. This property will **only** be present when the connection was opened from a tab (including content scripts), and **only** if the receiver is an extension, not an app. */ tab?: tabs.Tab; /** * The [frame](https://developer.chrome.com/docs/extensions/reference/webNavigation/#frame_ids) that opened the connection. 0 for top-level frames, positive for child frames. This will only be set when `tab` is set. */ frameId?: number; /** * The ID of the extension that opened the connection, if any. */ id?: string; /** * The URL of the page or frame that opened the connection. If the sender is in an iframe, it will be iframe's URL not the URL of the page which hosts it. */ url?: string; /** * The name of the native application that opened the connection, if any. * * @since Chrome 74 */ nativeApplication?: string; /** * The TLS channel ID of the page or frame that opened the connection, if requested by the extension, and if available. */ tlsChannelId?: string; /** * The origin of the page or frame that opened the connection. It can vary from the url property (e.g., about:blank) or can be opaque (e.g., sandboxed iframes). This is useful for identifying if the origin can be trusted if we can't immediately tell from the URL. * * @since Chrome 80 */ origin?: string; /** * A UUID of the document that opened the connection. * * @since Chrome 106 */ documentId?: string; /** * The lifecycle the document that opened the connection is in at the time the port was created. Note that the lifecycle state of the document may have changed since port creation. * * @since Chrome 106 */ documentLifecycle?: string; } /** * The operating system Chrome is running on. * * @chrome-enum "mac" Specifies the MacOS operating system. * @chrome-enum "win" Specifies the Windows operating system. * @chrome-enum "android" Specifies the Android operating system. * @chrome-enum "cros" Specifies the Chrome operating system. * @chrome-enum "linux" Specifies the Linux operating system. * @chrome-enum "openbsd" Specifies the OpenBSD operating system. * @since Chrome 44 */ export type PlatformOs = "mac" | "win" | "android" | "cros" | "linux" | "openbsd"; /** * The machine's processor architecture. * * @chrome-enum "arm" Specifies the processer architecture as arm. * @chrome-enum "arm64" Specifies the processer architecture as arm64. * @chrome-enum "x86-32" Specifies the processer architecture as x86-32. * @chrome-enum "x86-64" Specifies the processer architecture as x86-64. * @chrome-enum "mips" Specifies the processer architecture as mips. * @chrome-enum "mips64" Specifies the processer architecture as mips64. * @chrome-enum "riscv64" Specifies the processer architecture as riscv64. * @since Chrome 44 */ export type PlatformArch = "arm" | "arm64" | "x86-32" | "x86-64" | "mips" | "mips64" | "riscv64"; /** * The native client architecture. This may be different from arch on some platforms. * * @chrome-enum "arm" Specifies the native client architecture as arm. * @chrome-enum "x86-32" Specifies the native client architecture as x86-32. * @chrome-enum "x86-64" Specifies the native client architecture as x86-64. * @chrome-enum "mips" Specifies the native client architecture as mips. * @chrome-enum "mips64" Specifies the native client architecture as mips64. * @since Chrome 44 */ export type PlatformNaclArch = "arm" | "x86-32" | "x86-64" | "mips" | "mips64"; /** * An object containing information about the current platform. */ export interface PlatformInfo { /** * The operating system Chrome is running on. */ os: PlatformOs; /** * The machine's processor architecture. */ arch: PlatformArch; /** * The native client architecture. This may be different from arch on some platforms. */ nacl_arch?: PlatformNaclArch; } /** * Result of the update check. * * @chrome-enum "throttled" Specifies that the status check has been throttled. This can occur after repeated checks within a short amount of time. * @chrome-enum "no\_update" Specifies that there are no available updates to install. * @chrome-enum "update\_available" Specifies that there is an available update to install. * @since Chrome 44 */ export type RequestUpdateCheckStatus = "throttled" | "no_update" | "update_available"; /** * The reason that this event is being dispatched. * * @chrome-enum "install" Specifies the event reason as an installation. * @chrome-enum "update" Specifies the event reason as an extension update. * @chrome-enum "chrome\_update" Specifies the event reason as a Chrome update. * @chrome-enum "shared\_module\_update" Specifies the event reason as an update to a shared module. * @since Chrome 44 */ export type OnInstalledReason = "install" | "update" | "chrome_update" | "shared_module_update"; /** * The reason that the event is being dispatched. 'app\_update' is used when the restart is needed because the application is updated to a newer version. 'os\_update' is used when the restart is needed because the browser/OS is updated to a newer version. 'periodic' is used when the system runs for more than the permitted uptime set in the enterprise policy. * * @chrome-enum "app\_update" Specifies the event reason as an update to the app. * @chrome-enum "os\_update" Specifies the event reason as an update to the operating system. * @chrome-enum "periodic" Specifies the event reason as a periodic restart of the app. * @since Chrome 44 */ export type OnRestartRequiredReason = "app_update" | "os_update" | "periodic"; /** * @chrome-enum "TAB" Specifies the context type as a tab * @chrome-enum "POPUP" Specifies the context type as an extension popup window * @chrome-enum "BACKGROUND" Specifies the context type as a service worker. * @chrome-enum "OFFSCREEN\_DOCUMENT" Specifies the context type as an offscreen document. * @chrome-enum "SIDE\_PANEL" Specifies the context type as a side panel. * @chrome-enum "DEVELOPER\_TOOLS" Specifies the context type as developer tools. * @since Chrome 114 */ export type ContextType = "TAB" | "POPUP" | "BACKGROUND" | "OFFSCREEN_DOCUMENT" | "SIDE_PANEL" | "DEVELOPER_TOOLS"; /** * A context hosting extension content. * * @since Chrome 114 */ export interface ExtensionContext { /** * The type of context this corresponds to. */ contextType: ContextType; /** * A unique identifier for this context */ contextId: string; /** * The ID of the tab for this context, or -1 if this context is not hosted in a tab. */ tabId: number; /** * The ID of the window for this context, or -1 if this context is not hosted in a window. */ windowId: number; /** * A UUID for the document associated with this context, or undefined if this context is hosted not in a document. */ documentId?: string; /** * The ID of the frame for this context, or -1 if this context is not hosted in a frame. */ frameId: number; /** * The URL of the document associated with this context, or undefined if the context is not hosted in a document. */ documentUrl?: string; /** * The origin of the document associated with this context, or undefined if the context is not hosted in a document. */ documentOrigin?: string; /** * Whether the context is associated with an incognito profile. */ incognito: boolean; } /** * A filter to match against certain extension contexts. Matching contexts must match all specified filters; any filter that is not specified matches all available contexts. Thus, a filter of \`{}\` will match all available contexts. * * @since Chrome 114 */ export interface ContextFilter { contextTypes?: ContextType[]; contextIds?: string[]; tabIds?: number[]; windowIds?: number[]; documentIds?: string[]; frameIds?: number[]; documentUrls?: string[]; documentOrigins?: string[]; incognito?: boolean; } /** * Populated with an error message if calling an API function fails; otherwise undefined. This is only defined within the scope of that function's callback. If an error is produced, but `runtime.lastError` is not accessed within the callback, a message is logged to the console listing the API function that produced the error. API functions that return promises do not set this property. */ export let lastError: { /** * Details about the error which occurred. */ message?: string, }; /** * The ID of the extension/app. */ export const id: string; /** * Fired when a profile that has this extension installed first starts up. This event is not fired when an incognito profile is started, even if this extension is operating in 'split' incognito mode. */ export const onStartup: events.Event<() => void>; /** * Fired when the extension is first installed, when the extension is updated to a new version, and when Chrome is updated to a new version. */ export const onInstalled: events.Event<( details: { /** * The reason that this event is being dispatched. */ reason: OnInstalledReason, /** * Indicates the previous version of the extension, which has just been updated. This is present only if 'reason' is 'update'. */ previousVersion?: string, /** * Indicates the ID of the imported shared module extension which updated. This is present only if 'reason' is 'shared\_module\_update'. */ id?: string, }, ) => void>; /** * Sent to the event page just before it is unloaded. This gives the extension opportunity to do some clean up. Note that since the page is unloading, any asynchronous operations started while handling this event are not guaranteed to complete. If more activity for the event page occurs before it gets unloaded the onSuspendCanceled event will be sent and the page won't be unloaded. */ export const onSuspend: events.Event<() => void>; /** * Sent after onSuspend to indicate that the app won't be unloaded after all. */ export const onSuspendCanceled: events.Event<() => void>; /** * Fired when an update is available, but isn't installed immediately because the app is currently running. If you do nothing, the update will be installed the next time the background page gets unloaded, if you want it to be installed sooner you can explicitly call chrome.runtime.reload(). If your extension is using a persistent background page, the background page of course never gets unloaded, so unless you call chrome.runtime.reload() manually in response to this event the update will not get installed until the next time Chrome itself restarts. If no handlers are listening for this event, and your extension has a persistent background page, it behaves as if chrome.runtime.reload() is called in response to this event. */ export const onUpdateAvailable: events.Event<( details: { [name: string]: any, /** * The version number of the available update. */ version: string, }, ) => void>; /** * Fired when a Chrome update is available, but isn't installed immediately because a browser restart is required. * * @deprecated Please use {@link runtime.onRestartRequired}. */ export const onBrowserUpdateAvailable: events.Event<() => void>; /** * Fired when a connection is made from either an extension process or a content script (by {@link runtime.connect}). */ export const onConnect: events.Event<( port: Port, ) => void>; /** * Fired when a connection is made from another extension (by {@link runtime.connect}), or from an externally connectable web site. */ export const onConnectExternal: events.Event<( port: Port, ) => void>; /** * Fired when a connection is made from a user script from this extension. * * @since Chrome 115 * @chrome-min-manifest MV3 */ export const onUserScriptConnect: events.Event<( port: Port, ) => void>; /** * Fired when a connection is made from a native application. This event requires the `"nativeMessaging"` permission. It is only supported on Chrome OS. * * @since Chrome 76 * @chrome-permission nativeMessaging */ export const onConnectNative: events.Event<( port: Port, ) => void>; /** * Fired when a message is sent from either an extension process (by {@link runtime.sendMessage}) or a content script (by {@link tabs.sendMessage}). */ export const onMessage: events.Event<( message: any, sender: MessageSender, /** * @param response The response to return to the message sender. */ sendResponse: ( response?: any, ) => void, ) => (boolean | Promise) | undefined>; /** * Fired when a message is sent from another extension (by {@link runtime.sendMessage}). Cannot be used in a content script. */ export const onMessageExternal: events.Event<( message: any, sender: MessageSender, /** * @param response The response to return to the message sender. */ sendResponse: ( /** * @since Pending */ response?: any, ) => void, ) => (boolean | Promise) | undefined>; /** * Fired when a message is sent from a user script associated with the same extension. * * @since Chrome 115 * @chrome-min-manifest MV3 */ export const onUserScriptMessage: events.Event<( message: any, sender: MessageSender, /** * @param response The response to return to the message sender. */ sendResponse: ( /** * @since Pending */ response?: any, ) => void, ) => boolean | undefined>; /** * Fired when an app or the device that it runs on needs to be restarted. The app should close all its windows at its earliest convenient time to let the restart to happen. If the app does nothing, a restart will be enforced after a 24-hour grace period has passed. Currently, this event is only fired for Chrome OS kiosk apps. */ export const onRestartRequired: events.Event<( reason: OnRestartRequiredReason, ) => void>; /** * Retrieves the JavaScript 'window' object for the background page running inside the current extension/app. If the background page is an event page, the system will ensure it is loaded before calling the callback. If there is no background page, an error is set. * * @chrome-returns-extra since Chrome 99 * @deprecated Background pages do not exist in MV3 extensions. * @chrome-disallow-service-workers * @chrome-deprecated-since Chrome 133 */ export function getBackgroundPage(): Promise; /** * Retrieves the JavaScript 'window' object for the background page running inside the current extension/app. If the background page is an event page, the system will ensure it is loaded before calling the callback. If there is no background page, an error is set. * * @deprecated Background pages do not exist in MV3 extensions. * @chrome-disallow-service-workers * @chrome-deprecated-since Chrome 133 */ export function getBackgroundPage( /** * @param backgroundPage The JavaScript 'window' object for the background page. */ callback?: ( backgroundPage?: Window, ) => void, ): void; /** * Open your Extension's options page, if possible. * * The precise behavior may depend on your manifest's [`options_ui`](https://developer.chrome.com/docs/extensions/develop/ui/options-page#embedded_options) or [`options_page`](https://developer.chrome.com/docs/extensions/develop/ui/options-page#full_page) key, or what Chrome happens to support at the time. For example, the page may be opened in a new tab, within chrome://extensions, within an App, or it may just focus an open options page. It will never cause the caller page to reload. * * If your Extension does not declare an options page, or Chrome failed to create one for some other reason, the callback will set {@link lastError}. * * @chrome-returns-extra since Chrome 99 */ export function openOptionsPage(): Promise; /** * Open your Extension's options page, if possible. * * The precise behavior may depend on your manifest's [`options_ui`](https://developer.chrome.com/docs/extensions/develop/ui/options-page#embedded_options) or [`options_page`](https://developer.chrome.com/docs/extensions/develop/ui/options-page#full_page) key, or what Chrome happens to support at the time. For example, the page may be opened in a new tab, within chrome://extensions, within an App, or it may just focus an open options page. It will never cause the caller page to reload. * * If your Extension does not declare an options page, or Chrome failed to create one for some other reason, the callback will set {@link lastError}. */ export function openOptionsPage( callback?: () => void, ): void; /** * Returns details about the app or extension from the manifest. The object returned is a serialization of the full [manifest file](https://developer.chrome.com/docs/extensions/reference/manifest). * * @returns The manifest details. */ export function getManifest(): {[name: string]: any}; /** * Returns the extension's version as declared in the manifest. * * @returns The extension's version. * @since Chrome 143 */ export function getVersion(): string; /** * Converts a relative path within an app/extension install directory to a fully-qualified URL. * * @param path A path to a resource within an app/extension expressed relative to its install directory. * @returns The fully-qualified URL to the resource. */ export function getURL( path: string, ): string; /** * Sets the URL to be visited upon uninstallation. This may be used to clean up server-side data, do analytics, and implement surveys. Maximum 1023 characters. * * @chrome-returns-extra since Chrome 99 * @param url URL to be opened after the extension is uninstalled. This URL must have an http: or https: scheme. Set an empty string to not open a new tab upon uninstallation. * @returns Promise that resolves when the uninstall URL is set. If the given URL is invalid, the promise will be rejected. */ export function setUninstallURL( url: string, ): Promise; /** * Sets the URL to be visited upon uninstallation. This may be used to clean up server-side data, do analytics, and implement surveys. Maximum 1023 characters. * * @param url URL to be opened after the extension is uninstalled. This URL must have an http: or https: scheme. Set an empty string to not open a new tab upon uninstallation. */ export function setUninstallURL( url: string, /** * @since Chrome 45 */ callback?: () => void, ): void; /** * Reloads the app or extension. This method is not supported in kiosk mode. For kiosk mode, use chrome.runtime.restart() method. */ export function reload(): void; /** * Requests an immediate update check be done for this app/extension. * * **Important**: Most extensions/apps should **not** use this method, since Chrome already does automatic checks every few hours, and you can listen for the {@link runtime.onUpdateAvailable} event without needing to call requestUpdateCheck. * * This method is only appropriate to call in very limited circumstances, such as if your extension talks to a backend service, and the backend service has determined that the client extension version is very far out of date and you'd like to prompt a user to update. Most other uses of requestUpdateCheck, such as calling it unconditionally based on a repeating timer, probably only serve to waste client, network, and server resources. * * Note: When called with a callback, instead of returning an object this function will return the two properties as separate arguments passed to the callback. * * @chrome-returns-extra since Chrome 109 */ export function requestUpdateCheck(): Promise<{ /** * Result of the update check. */ status: RequestUpdateCheckStatus, /** * If an update is available, this contains the version of the available update. */ version?: string, }>; /** * Requests an immediate update check be done for this app/extension. * * **Important**: Most extensions/apps should **not** use this method, since Chrome already does automatic checks every few hours, and you can listen for the {@link runtime.onUpdateAvailable} event without needing to call requestUpdateCheck. * * This method is only appropriate to call in very limited circumstances, such as if your extension talks to a backend service, and the backend service has determined that the client extension version is very far out of date and you'd like to prompt a user to update. Most other uses of requestUpdateCheck, such as calling it unconditionally based on a repeating timer, probably only serve to waste client, network, and server resources. * * Note: When called with a callback, instead of returning an object this function will return the two properties as separate arguments passed to the callback. */ export function requestUpdateCheck( /** * @param result RequestUpdateCheckResult object that holds the status of the update check and any details of the result if there is an update available */ callback?: ( /** * @since Chrome 109 */ result: { /** * Result of the update check. */ status: RequestUpdateCheckStatus, /** * If an update is available, this contains the version of the available update. */ version?: string, }, ) => void, ): void; /** * Restart the ChromeOS device when the app runs in kiosk mode. Otherwise, it's no-op. */ export function restart(): void; /** * Restart the ChromeOS device when the app runs in kiosk mode after the given seconds. If called again before the time ends, the reboot will be delayed. If called with a value of -1, the reboot will be cancelled. It's a no-op in non-kiosk mode. It's only allowed to be called repeatedly by the first extension to invoke this API. * * @chrome-returns-extra since Chrome 99 * @param seconds Time to wait in seconds before rebooting the device, or -1 to cancel a scheduled reboot. * @returns Promise that resolves when a restart request was successfully rescheduled. * @since Chrome 53 */ export function restartAfterDelay( seconds: number, ): Promise; /** * Restart the ChromeOS device when the app runs in kiosk mode after the given seconds. If called again before the time ends, the reboot will be delayed. If called with a value of -1, the reboot will be cancelled. It's a no-op in non-kiosk mode. It's only allowed to be called repeatedly by the first extension to invoke this API. * * @param seconds Time to wait in seconds before rebooting the device, or -1 to cancel a scheduled reboot. * @since Chrome 53 */ export function restartAfterDelay( seconds: number, callback?: () => void, ): void; /** * Attempts to connect listeners within an extension (such as the background page), or other extensions/apps. This is useful for content scripts connecting to their extension processes, inter-app/extension communication, and [web messaging](https://developer.chrome.com/docs/extensions/manifest/externally_connectable). Note that this does not connect to any listeners in a content script. Extensions may connect to content scripts embedded in tabs via {@link tabs.connect}. * * @param extensionId The ID of the extension to connect to. If omitted, a connection will be attempted with your own extension. Required if sending messages from a web page for [web messaging](https://developer.chrome.com/docs/extensions/reference/manifest/externally-connectable). * @returns Port through which messages can be sent and received. The port's {@link Port onDisconnect} event is fired if the extension does not exist. */ export function connect( extensionId?: string, connectInfo?: { /** * Will be passed into onConnect for processes that are listening for the connection event. */ name?: string, /** * Whether the TLS channel ID will be passed into onConnectExternal for processes that are listening for the connection event. */ includeTlsChannelId?: boolean, }, ): Port; /** * Connects to a native application in the host machine. This method requires the `"nativeMessaging"` permission. See [Native Messaging](https://developer.chrome.com/extensions/develop/concepts/native-messaging) for more information. * * @param application The name of the registered application to connect to. * @returns Port through which messages can be sent and received with the application * @chrome-permission nativeMessaging */ export function connectNative( application: string, ): Port; /** * Sends a single message to event listeners within your extension or a different extension/app. Similar to {@link runtime.connect} but only sends a single message, with an optional response. If sending to your extension, the {@link runtime.onMessage} event will be fired in every frame of your extension (except for the sender's frame), or {@link runtime.onMessageExternal}, if a different extension. Note that extensions cannot send messages to content scripts using this method. To send messages to content scripts, use {@link tabs.sendMessage}. * * @chrome-returns-extra since Chrome 99 * @param extensionId The ID of the extension to send the message to. If omitted, the message will be sent to your own extension/app. Required if sending messages from a web page for [web messaging](https://developer.chrome.com/docs/extensions/manifest/externally_connectable). * @param message The message to send. This message should be a JSON-ifiable object. * @returns Promise support was added for extension contexts in Chrome 99. When communicating from a web page to an extension, promises are available from Chrome 118. */ export function sendMessage( extensionId: string, message: any, options?: { /** * Whether the TLS channel ID will be passed into onMessageExternal for processes that are listening for the connection event. */ includeTlsChannelId?: boolean, }, ): Promise; /** * Sends a single message to event listeners within your extension or a different extension/app. Similar to {@link runtime.connect} but only sends a single message, with an optional response. If sending to your extension, the {@link runtime.onMessage} event will be fired in every frame of your extension (except for the sender's frame), or {@link runtime.onMessageExternal}, if a different extension. Note that extensions cannot send messages to content scripts using this method. To send messages to content scripts, use {@link tabs.sendMessage}. * * @chrome-returns-extra since Chrome 99 * @param message The message to send. This message should be a JSON-ifiable object. * @returns Promise support was added for extension contexts in Chrome 99. When communicating from a web page to an extension, promises are available from Chrome 118. */ export function sendMessage( message: any, options?: { /** * Whether the TLS channel ID will be passed into onMessageExternal for processes that are listening for the connection event. */ includeTlsChannelId?: boolean, }, ): Promise; /** * Sends a single message to event listeners within your extension or a different extension/app. Similar to {@link runtime.connect} but only sends a single message, with an optional response. If sending to your extension, the {@link runtime.onMessage} event will be fired in every frame of your extension (except for the sender's frame), or {@link runtime.onMessageExternal}, if a different extension. Note that extensions cannot send messages to content scripts using this method. To send messages to content scripts, use {@link tabs.sendMessage}. * * @param extensionId The ID of the extension to send the message to. If omitted, the message will be sent to your own extension/app. Required if sending messages from a web page for [web messaging](https://developer.chrome.com/docs/extensions/manifest/externally_connectable). * @param message The message to send. This message should be a JSON-ifiable object. */ export function sendMessage( extensionId: string, message: any, options?: { /** * Whether the TLS channel ID will be passed into onMessageExternal for processes that are listening for the connection event. */ includeTlsChannelId?: boolean, }, /** * @param response The JSON response object sent by the handler of the message. If an error occurs while connecting to the extension, the callback will be called with no arguments and {@link runtime.lastError} will be set to the error message. * @since Chrome 99 */ callback?: ( response: any, ) => void, ): void; /** * Sends a single message to event listeners within your extension or a different extension/app. Similar to {@link runtime.connect} but only sends a single message, with an optional response. If sending to your extension, the {@link runtime.onMessage} event will be fired in every frame of your extension (except for the sender's frame), or {@link runtime.onMessageExternal}, if a different extension. Note that extensions cannot send messages to content scripts using this method. To send messages to content scripts, use {@link tabs.sendMessage}. * * @param message The message to send. This message should be a JSON-ifiable object. */ export function sendMessage( message: any, options?: { /** * Whether the TLS channel ID will be passed into onMessageExternal for processes that are listening for the connection event. */ includeTlsChannelId?: boolean, }, /** * @param response The JSON response object sent by the handler of the message. If an error occurs while connecting to the extension, the callback will be called with no arguments and {@link runtime.lastError} will be set to the error message. * @since Chrome 99 */ callback?: ( response: any, ) => void, ): void; /** * Send a single message to a native application. This method requires the `"nativeMessaging"` permission. * * @chrome-returns-extra since Chrome 99 * @param application The name of the native messaging host. * @param message The message that will be passed to the native messaging host. * @chrome-permission nativeMessaging */ export function sendNativeMessage( application: string, message: {[name: string]: any}, ): Promise; /** * Send a single message to a native application. This method requires the `"nativeMessaging"` permission. * * @param application The name of the native messaging host. * @param message The message that will be passed to the native messaging host. * @chrome-permission nativeMessaging */ export function sendNativeMessage( application: string, message: {[name: string]: any}, /** * @param response The response message sent by the native messaging host. If an error occurs while connecting to the native messaging host, the callback will be called with no arguments and {@link runtime.lastError} will be set to the error message. * @since Chrome 99 */ callback?: ( response: any, ) => void, ): void; /** * Returns information about the current platform. * * @chrome-returns-extra since Chrome 99 * @returns Promise that resolves with information about the current platform. */ export function getPlatformInfo(): Promise; /** * Returns information about the current platform. */ export function getPlatformInfo( callback?: ( platformInfo: PlatformInfo, ) => void, ): void; /** * Returns a DirectoryEntry for the package directory. * * @chrome-returns-extra since Chrome 122 * @chrome-disallow-service-workers */ export function getPackageDirectoryEntry(): Promise; /** * Returns a DirectoryEntry for the package directory. * * @chrome-disallow-service-workers */ export function getPackageDirectoryEntry( callback?: ( directoryEntry: DirectoryEntry, ) => void, ): void; /** * Fetches information about active contexts associated with this extension * * @param filter A filter to find matching contexts. A context matches if it matches all specified fields in the filter. Any unspecified field in the filter matches all contexts. * @returns Promise that resolves with the matching contexts, if any. * @since Chrome 116 * @chrome-min-manifest MV3 */ export function getContexts( filter: ContextFilter, ): Promise; /** * Fetches information about active contexts associated with this extension * * @param filter A filter to find matching contexts. A context matches if it matches all specified fields in the filter. Any unspecified field in the filter matches all contexts. * @since Chrome 116 * @chrome-min-manifest MV3 */ export function getContexts( filter: ContextFilter, /** * @param contexts The matching contexts, if any. */ callback?: ( contexts: ExtensionContext[], ) => void, ): void; } /** * Use the `chrome.scripting` API to execute script in different contexts. * * @since Chrome 88 * @chrome-permission scripting * @chrome-min-manifest MV3 */ export namespace scripting { /** * The origin for a style change. See [style origins](https://developer.mozilla.org/en-US/docs/Glossary/Style_origin) for more info. */ export type StyleOrigin = "AUTHOR" | "USER"; /** * The JavaScript world for a script to execute within. * * @chrome-enum "ISOLATED" Specifies the isolated world, which is the execution environment unique to this extension. * @chrome-enum "MAIN" Specifies the main world of the DOM, which is the execution environment shared with the host page's JavaScript. * @since Chrome 95 */ export type ExecutionWorld = "ISOLATED" | "MAIN"; export interface InjectionTarget { /** * The ID of the tab into which to inject. */ tabId: number; /** * The [IDs](https://developer.chrome.com/docs/extensions/reference/webNavigation/#frame_ids) of specific frames to inject into. */ frameIds?: number[]; /** * The [IDs](https://developer.chrome.com/docs/extensions/reference/webNavigation/#document_ids) of specific documentIds to inject into. This must not be set if `frameIds` is set. * * @since Chrome 106 */ documentIds?: string[]; /** * Whether the script should inject into all frames within the tab. Defaults to false. This must not be true if `frameIds` is specified. */ allFrames?: boolean; } export interface ScriptInjection { /** * A JavaScript function to inject. This function will be serialized, and then deserialized for injection. This means that any bound parameters and execution context will be lost. Exactly one of `files` or `func` must be specified. * * @since Chrome 92 */ func?: () => void; /** * The arguments to pass to the provided function. This is only valid if the `func` parameter is specified. These arguments must be JSON-serializable. * * @since Chrome 92 */ args?: any[]; /** * The path of the JS or CSS files to inject, relative to the extension's root directory. Exactly one of `files` or `func` must be specified. */ files?: string[]; /** * Details specifying the target into which to inject the script. */ target: InjectionTarget; /** * The JavaScript "world" to run the script in. Defaults to `ISOLATED`. * * @since Chrome 95 */ world?: ExecutionWorld; /** * Whether the injection should be triggered in the target as soon as possible. Note that this is not a guarantee that injection will occur prior to page load, as the page may have already loaded by the time the script reaches the target. * * @since Chrome 102 */ injectImmediately?: boolean; } export interface CSSInjection { /** * Details specifying the target into which to insert the CSS. */ target: InjectionTarget; /** * A string containing the CSS to inject. Exactly one of `files` and `css` must be specified. */ css?: string; /** * The path of the CSS files to inject, relative to the extension's root directory. Exactly one of `files` and `css` must be specified. */ files?: string[]; /** * The style origin for the injection. Defaults to `'AUTHOR'`. */ origin?: StyleOrigin; } export interface InjectionResult { /** * The result of the script execution. */ result?: any; /** * The frame associated with the injection. * * @since Chrome 90 */ frameId: number; /** * The document associated with the injection. * * @since Chrome 106 */ documentId: string; } /** * @since Chrome 96 */ export interface RegisteredContentScript { /** * The id of the content script, specified in the API call. Must not start with a '\_' as it's reserved as a prefix for generated script IDs. */ id: string; /** * Specifies which pages this content script will be injected into. See [Match Patterns](https://developer.chrome.com/extensions/develop/concepts/match-patterns) for more details on the syntax of these strings. Must be specified for {@link registerContentScripts}. */ matches?: string[]; /** * Excludes pages that this content script would otherwise be injected into. See [Match Patterns](https://developer.chrome.com/extensions/develop/concepts/match-patterns) for more details on the syntax of these strings. */ excludeMatches?: string[]; /** * The list of CSS files to be injected into matching pages. These are injected in the order they appear in this array, before any DOM is constructed or displayed for the page. */ css?: string[]; /** * The list of JavaScript files to be injected into matching pages. These are injected in the order they appear in this array. */ js?: string[]; /** * If specified true, it will inject into all frames, even if the frame is not the top-most frame in the tab. Each frame is checked independently for URL requirements; it will not inject into child frames if the URL requirements are not met. Defaults to false, meaning that only the top frame is matched. */ allFrames?: boolean; /** * Indicates whether the script can be injected into frames where the URL contains an unsupported scheme; specifically: about:, data:, blob:, or filesystem:. In these cases, the URL's origin is checked to determine if the script should be injected. If the origin is `null` (as is the case for data: URLs) then the used origin is either the frame that created the current frame or the frame that initiated the navigation to this frame. Note that this may not be the parent frame. * * @since Chrome 119 */ matchOriginAsFallback?: boolean; /** * Specifies when JavaScript files are injected into the web page. The preferred and default value is `document_idle`. */ runAt?: extensionTypes.RunAt; /** * Specifies if this content script will persist into future sessions. The default is true. */ persistAcrossSessions?: boolean; /** * The JavaScript "world" to run the script in. Defaults to `ISOLATED`. * * @since Chrome 102 */ world?: ExecutionWorld; } /** * @since Chrome 96 */ export interface ContentScriptFilter { /** * If specified, {@link getRegisteredContentScripts} will only return scripts with an id specified in this list. */ ids?: string[]; } /** * Injects a script into a target context. By default, the script will be run at `document_idle`, or immediately if the page has already loaded. If the `injectImmediately` property is set, the script will inject without waiting, even if the page has not finished loading. If the script evaluates to a promise, the browser will wait for the promise to settle and return the resulting value. * * @chrome-returns-extra since Chrome 90 * @param injection The details of the script which to inject. * @returns Returns a Promise which resolves upon completion of the injection. The resulting array contains the result of execution for each frame where the injection succeeded. */ export function executeScript( injection: ScriptInjection, ): Promise; /** * Injects a script into a target context. By default, the script will be run at `document_idle`, or immediately if the page has already loaded. If the `injectImmediately` property is set, the script will inject without waiting, even if the page has not finished loading. If the script evaluates to a promise, the browser will wait for the promise to settle and return the resulting value. * * @param injection The details of the script which to inject. */ export function executeScript( injection: ScriptInjection, callback?: ( results: InjectionResult[], ) => void, ): void; /** * Inserts a CSS stylesheet into a target context. If multiple frames are specified, unsuccessful injections are ignored. * * @chrome-returns-extra since Chrome 90 * @param injection The details of the styles to insert. * @returns Returns a Promise which resolves upon completion of the insertion. */ export function insertCSS( injection: CSSInjection, ): Promise; /** * Inserts a CSS stylesheet into a target context. If multiple frames are specified, unsuccessful injections are ignored. * * @param injection The details of the styles to insert. */ export function insertCSS( injection: CSSInjection, callback?: () => void, ): void; /** * Removes a CSS stylesheet that was previously inserted by this extension from a target context. * * @param injection The details of the styles to remove. Note that the `css`, `files`, and `origin` properties must exactly match the stylesheet inserted through {@link insertCSS}. Attempting to remove a non-existent stylesheet is a no-op. * @returns Returns a Promise which resolves upon the completion of the removal. * @since Chrome 90 */ export function removeCSS( injection: CSSInjection, ): Promise; /** * Removes a CSS stylesheet that was previously inserted by this extension from a target context. * * @param injection The details of the styles to remove. Note that the `css`, `files`, and `origin` properties must exactly match the stylesheet inserted through {@link insertCSS}. Attempting to remove a non-existent stylesheet is a no-op. * @since Chrome 90 */ export function removeCSS( injection: CSSInjection, callback?: () => void, ): void; /** * Registers one or more content scripts for this extension. * * @param scripts Contains a list of scripts to be registered. If there are errors during script parsing/file validation, or if the IDs specified already exist, then no scripts are registered. * @returns Returns a Promise which resolves once scripts have been fully registered or rejects if an error has occurred. * @since Chrome 96 */ export function registerContentScripts( scripts: RegisteredContentScript[], ): Promise; /** * Registers one or more content scripts for this extension. * * @param scripts Contains a list of scripts to be registered. If there are errors during script parsing/file validation, or if the IDs specified already exist, then no scripts are registered. * @since Chrome 96 */ export function registerContentScripts( scripts: RegisteredContentScript[], callback?: () => void, ): void; /** * Returns all dynamically registered content scripts for this extension that match the given filter. * * @param filter An object to filter the extension's dynamically registered scripts. * @since Chrome 96 */ export function getRegisteredContentScripts( filter?: ContentScriptFilter, ): Promise; /** * Returns all dynamically registered content scripts for this extension that match the given filter. * * @param filter An object to filter the extension's dynamically registered scripts. * @since Chrome 96 */ export function getRegisteredContentScripts( filter?: ContentScriptFilter, callback?: ( scripts: RegisteredContentScript[], ) => void, ): void; /** * Unregisters content scripts for this extension. * * @param filter If specified, only unregisters dynamic content scripts which match the filter. Otherwise, all of the extension's dynamic content scripts are unregistered. * @returns Returns a Promise which resolves once scripts have been unregistered or rejects if an error has occurred. * @since Chrome 96 */ export function unregisterContentScripts( filter?: ContentScriptFilter, ): Promise; /** * Unregisters content scripts for this extension. * * @param filter If specified, only unregisters dynamic content scripts which match the filter. Otherwise, all of the extension's dynamic content scripts are unregistered. * @since Chrome 96 */ export function unregisterContentScripts( filter?: ContentScriptFilter, callback?: () => void, ): void; /** * Updates one or more content scripts for this extension. * * @param scripts Contains a list of scripts to be updated. A property is only updated for the existing script if it is specified in this object. If there are errors during script parsing/file validation, or if the IDs specified do not correspond to a fully registered script, then no scripts are updated. * @returns Returns a Promise which resolves once scripts have been updated or rejects if an error has occurred. * @since Chrome 96 */ export function updateContentScripts( scripts: RegisteredContentScript[], ): Promise; /** * Updates one or more content scripts for this extension. * * @param scripts Contains a list of scripts to be updated. A property is only updated for the existing script if it is specified in this object. If there are errors during script parsing/file validation, or if the IDs specified do not correspond to a fully registered script, then no scripts are updated. * @since Chrome 96 */ export function updateContentScripts( scripts: RegisteredContentScript[], callback?: () => void, ): void; } /** * Use the `chrome.search` API to search via the default provider. * * @since Chrome 87 * @chrome-permission search */ export namespace search { /** * @chrome-enum "CURRENT\_TAB" Specifies that the search results display in the calling tab or the tab from the active browser. * @chrome-enum "NEW\_TAB" Specifies that the search results display in a new tab. * @chrome-enum "NEW\_WINDOW" Specifies that the search results display in a new window. */ export type Disposition = "CURRENT_TAB" | "NEW_TAB" | "NEW_WINDOW"; export interface QueryInfo { /** * String to query with the default search provider. */ text: string; /** * Location where search results should be displayed. `CURRENT_TAB` is the default. */ disposition?: Disposition; /** * Location where search results should be displayed. `tabId` cannot be used with `disposition`. */ tabId?: number; } /** * Used to query the default search provider. In case of an error, {@link runtime.lastError} will be set. * * @chrome-returns-extra since Chrome 96 */ export function query( queryInfo: QueryInfo, ): Promise; /** * Used to query the default search provider. In case of an error, {@link runtime.lastError} will be set. */ export function query( queryInfo: QueryInfo, callback?: () => void, ): void; } /** * Use the `chrome.serial` API to read from and write to a device connected to a serial port. * * @chrome-permission serial * @chrome-platform-apps * @chrome-platform chromeos * @chrome-platform linux * @chrome-platform mac * @chrome-platform win */ export namespace serial { export interface DeviceInfo { /** * The device's system path. This should be passed as the `path` argument to `chrome.serial.connect` in order to connect to this device. */ path: string; /** * A PCI or USB vendor ID if one can be determined for the underlying device. */ vendorId?: number; /** * A USB product ID if one can be determined for the underlying device. */ productId?: number; /** * A human-readable display name for the underlying device if one can be queried from the host driver. */ displayName?: string; } export type DataBits = "seven" | "eight"; export type ParityBit = "no" | "odd" | "even"; export type StopBits = "one" | "two"; export interface ConnectionOptions { /** * Flag indicating whether or not the connection should be left open when the application is suspended (see [Manage App Lifecycle](https://developer.chrome.com/docs/apps/app_lifecycle)). The default value is "false." When the application is loaded, any serial connections previously opened with persistent=true can be fetched with `getConnections`. */ persistent?: boolean; /** * An application-defined string to associate with the connection. */ name?: string; /** * The size of the buffer used to receive data. The default value is 4096. */ bufferSize?: number; /** * The requested bitrate of the connection to be opened. For compatibility with the widest range of hardware, this number should match one of commonly-available bitrates, such as 110, 300, 1200, 2400, 4800, 9600, 14400, 19200, 38400, 57600, 115200. There is no guarantee, of course, that the device connected to the serial port will support the requested bitrate, even if the port itself supports that bitrate. `9600` will be passed by default. */ bitrate?: number; /** * `"eight"` will be passed by default. */ dataBits?: DataBits; /** * `"no"` will be passed by default. */ parityBit?: ParityBit; /** * `"one"` will be passed by default. */ stopBits?: StopBits; /** * Flag indicating whether or not to enable RTS/CTS hardware flow control. Defaults to false. */ ctsFlowControl?: boolean; /** * The maximum amount of time (in milliseconds) to wait for new data before raising an `onReceiveError` event with a "timeout" error. If zero, receive timeout errors will not be raised for the connection. Defaults to 0. */ receiveTimeout?: number; /** * The maximum amount of time (in milliseconds) to wait for a `send` operation to complete before calling the callback with a "timeout" error. If zero, send timeout errors will not be triggered. Defaults to 0. */ sendTimeout?: number; } export interface ConnectionInfo { /** * The id of the serial port connection. */ connectionId: number; /** * Flag indicating whether the connection is blocked from firing onReceive events. */ paused: boolean; /** * See `ConnectionOptions.persistent` */ persistent: boolean; /** * See `ConnectionOptions.name` */ name: string; /** * See `ConnectionOptions.bufferSize` */ bufferSize: number; /** * See `ConnectionOptions.receiveTimeout` */ receiveTimeout: number; /** * See `ConnectionOptions.sendTimeout` */ sendTimeout: number; /** * See `ConnectionOptions.bitrate`. This field may be omitted or inaccurate if a non-standard bitrate is in use, or if an error occurred while querying the underlying device. */ bitrate?: number; /** * See `ConnectionOptions.dataBits`. This field may be omitted if an error occurred while querying the underlying device. */ dataBits?: DataBits; /** * See `ConnectionOptions.parityBit`. This field may be omitted if an error occurred while querying the underlying device. */ parityBit?: ParityBit; /** * See `ConnectionOptions.stopBits`. This field may be omitted if an error occurred while querying the underlying device. */ stopBits?: StopBits; /** * See `ConnectionOptions.ctsFlowControl`. This field may be omitted if an error occurred while querying the underlying device. */ ctsFlowControl?: boolean; } /** * @chrome-enum "disconnected" The connection was disconnected. * @chrome-enum "pending" A send was already pending. * @chrome-enum "timeout" The send timed out. * @chrome-enum "system\_error" A system error occurred and the connection may be unrecoverable. */ export type SendError = "disconnected" | "pending" | "timeout" | "system_error"; export interface SendInfo { /** * The number of bytes sent. */ bytesSent: number; /** * An error code if an error occurred. */ error?: SendError; } export interface HostControlSignals { /** * DTR (Data Terminal Ready). */ dtr?: boolean; /** * RTS (Request To Send). */ rts?: boolean; } export interface DeviceControlSignals { /** * DCD (Data Carrier Detect) or RLSD (Receive Line Signal/ Detect). */ dcd: boolean; /** * CTS (Clear To Send). */ cts: boolean; /** * RI (Ring Indicator). */ ri: boolean; /** * DSR (Data Set Ready). */ dsr: boolean; } export interface ReceiveInfo { /** * The connection identifier. */ connectionId: number; /** * The data received. */ data: ArrayBuffer; } /** * @chrome-enum "disconnected" The connection was disconnected. * @chrome-enum "timeout" No data has been received for `receiveTimeout` milliseconds. * @chrome-enum "device\_lost" The device was most likely disconnected from the host. * @chrome-enum "break" The device detected a break condition. * @chrome-enum "frame\_error" The device detected a framing error. * @chrome-enum "overrun" A character-buffer overrun has occurred. The next character is lost. * @chrome-enum "buffer\_overflow" An input buffer overflow has occurred. There is either no room in the input buffer, or a character was received after the end-of-file (EOF) character. * @chrome-enum "parity\_error" The device detected a parity error. * @chrome-enum "system\_error" A system error occurred and the connection may be unrecoverable. */ export type ReceiveError = "disconnected" | "timeout" | "device_lost" | "break" | "frame_error" | "overrun" | "buffer_overflow" | "parity_error" | "system_error"; export interface ReceiveErrorInfo { /** * The connection identifier. */ connectionId: number; /** * An error code indicating what went wrong. */ error: ReceiveError; } /** * Event raised when data has been read from the connection. */ export const onReceive: events.Event<( info: ReceiveInfo, ) => void>; /** * Event raised when an error occurred while the runtime was waiting for data on the serial port. Once this event is raised, the connection may be set to `paused`. A `"timeout"` error does not pause the connection. */ export const onReceiveError: events.Event<( info: ReceiveErrorInfo, ) => void>; /** * Returns information about available serial devices on the system. The list is regenerated each time this method is called. * * @chrome-returns-extra since Chrome 117 */ export function getDevices(): Promise; /** * Returns information about available serial devices on the system. The list is regenerated each time this method is called. */ export function getDevices( callback?: ( ports: DeviceInfo[], ) => void, ): void; /** * Connects to a given serial port. * * @chrome-returns-extra since Chrome 117 * @param path The system path of the serial port to open. * @param options Port configuration options. */ export function connect( path: string, options?: ConnectionOptions, ): Promise; /** * Connects to a given serial port. * * @param path The system path of the serial port to open. * @param options Port configuration options. */ export function connect( path: string, options?: ConnectionOptions, callback?: ( connectionInfo: ConnectionInfo, ) => void, ): void; /** * Update the option settings on an open serial port connection. * * @chrome-returns-extra since Chrome 117 * @param connectionId The id of the opened connection. * @param options Port configuration options. */ export function update( connectionId: number, options: ConnectionOptions, ): Promise; /** * Update the option settings on an open serial port connection. * * @param connectionId The id of the opened connection. * @param options Port configuration options. */ export function update( connectionId: number, options: ConnectionOptions, callback?: ( result: boolean, ) => void, ): void; /** * Disconnects from a serial port. * * @chrome-returns-extra since Chrome 117 * @param connectionId The id of the opened connection. */ export function disconnect( connectionId: number, ): Promise; /** * Disconnects from a serial port. * * @param connectionId The id of the opened connection. */ export function disconnect( connectionId: number, callback?: ( result: boolean, ) => void, ): void; /** * Pauses or unpauses an open connection. * * @chrome-returns-extra since Chrome 117 * @param connectionId The id of the opened connection. * @param paused Flag to indicate whether to pause or unpause. */ export function setPaused( connectionId: number, paused: boolean, ): Promise; /** * Pauses or unpauses an open connection. * * @param connectionId The id of the opened connection. * @param paused Flag to indicate whether to pause or unpause. */ export function setPaused( connectionId: number, paused: boolean, callback?: () => void, ): void; /** * Retrieves the state of a given connection. * * @chrome-returns-extra since Chrome 117 * @param connectionId The id of the opened connection. */ export function getInfo( connectionId: number, ): Promise; /** * Retrieves the state of a given connection. * * @param connectionId The id of the opened connection. */ export function getInfo( connectionId: number, callback?: ( connectionInfo: ConnectionInfo, ) => void, ): void; /** * Retrieves the list of currently opened serial port connections owned by the application. * * @chrome-returns-extra since Chrome 117 */ export function getConnections(): Promise; /** * Retrieves the list of currently opened serial port connections owned by the application. */ export function getConnections( callback?: ( connectionInfos: ConnectionInfo[], ) => void, ): void; /** * Writes data to the given connection. * * @chrome-returns-extra since Chrome 117 * @param connectionId The id of the connection. * @param data The data to send. */ export function send( connectionId: number, data: ArrayBuffer, ): Promise; /** * Writes data to the given connection. * * @param connectionId The id of the connection. * @param data The data to send. */ export function send( connectionId: number, data: ArrayBuffer, callback?: ( sendInfo: SendInfo, ) => void, ): void; /** * Flushes all bytes in the given connection's input and output buffers. * * @chrome-returns-extra since Chrome 117 */ export function flush( connectionId: number, ): Promise; /** * Flushes all bytes in the given connection's input and output buffers. */ export function flush( connectionId: number, callback?: ( result: boolean, ) => void, ): void; /** * Retrieves the state of control signals on a given connection. * * @chrome-returns-extra since Chrome 117 * @param connectionId The id of the connection. */ export function getControlSignals( connectionId: number, ): Promise; /** * Retrieves the state of control signals on a given connection. * * @param connectionId The id of the connection. */ export function getControlSignals( connectionId: number, callback?: ( signals: DeviceControlSignals, ) => void, ): void; /** * Sets the state of control signals on a given connection. * * @chrome-returns-extra since Chrome 117 * @param connectionId The id of the connection. * @param signals The set of signal changes to send to the device. */ export function setControlSignals( connectionId: number, signals: HostControlSignals, ): Promise; /** * Sets the state of control signals on a given connection. * * @param connectionId The id of the connection. * @param signals The set of signal changes to send to the device. */ export function setControlSignals( connectionId: number, signals: HostControlSignals, callback?: ( result: boolean, ) => void, ): void; /** * Suspends character transmission on a given connection and places the transmission line in a break state until the clearBreak is called. * * @chrome-returns-extra since Chrome 117 * @param connectionId The id of the connection. * @since Chrome 45 */ export function setBreak( connectionId: number, ): Promise; /** * Suspends character transmission on a given connection and places the transmission line in a break state until the clearBreak is called. * * @param connectionId The id of the connection. * @since Chrome 45 */ export function setBreak( connectionId: number, callback?: ( result: boolean, ) => void, ): void; /** * Restore character transmission on a given connection and place the transmission line in a nonbreak state. * * @chrome-returns-extra since Chrome 117 * @param connectionId The id of the connection. * @since Chrome 45 */ export function clearBreak( connectionId: number, ): Promise; /** * Restore character transmission on a given connection and place the transmission line in a nonbreak state. * * @param connectionId The id of the connection. * @since Chrome 45 */ export function clearBreak( connectionId: number, callback?: ( result: boolean, ) => void, ): void; } /** * Use the `chrome.sessions` API to query and restore tabs and windows from a browsing session. * * @chrome-permission sessions */ export namespace sessions { export interface Filter { /** * The maximum number of entries to be fetched in the requested list. Omit this parameter to fetch the maximum number of entries ({@link sessions.MAX_SESSION_RESULTS}). */ maxResults?: number; } export interface Session { /** * The time when the window or tab was closed or modified, represented in seconds since the epoch. */ lastModified: number; /** * The {@link tabs.Tab}, if this entry describes a tab. Either this or {@link sessions.Session.window} will be set. */ tab?: tabs.Tab; /** * The {@link windows.Window}, if this entry describes a window. Either this or {@link sessions.Session.tab} will be set. */ window?: windows.Window; } export interface Device { /** * The name of the foreign device. */ deviceName: string; /** * A list of open window sessions for the foreign device, sorted from most recently to least recently modified session. */ sessions: Session[]; } /** * The maximum number of {@link sessions.Session} that will be included in a requested list. */ export const MAX_SESSION_RESULTS: 25; /** * Fired when recently closed tabs and/or windows are changed. This event does not monitor synced sessions changes. */ export const onChanged: events.Event<() => void>; /** * Gets the list of recently closed tabs and/or windows. * * @chrome-returns-extra since Chrome 96 */ export function getRecentlyClosed( filter?: Filter, ): Promise; /** * Gets the list of recently closed tabs and/or windows. */ export function getRecentlyClosed( filter?: Filter, /** * @param sessions The list of closed entries in reverse order that they were closed (the most recently closed tab or window will be at index `0`). The entries may contain either tabs or windows. */ callback?: ( sessions: Session[], ) => void, ): void; /** * Retrieves all devices with synced sessions. * * @chrome-returns-extra since Chrome 96 */ export function getDevices( filter?: Filter, ): Promise; /** * Retrieves all devices with synced sessions. */ export function getDevices( filter?: Filter, /** * @param devices The list of {@link sessions.Device} objects for each synced session, sorted in order from device with most recently modified session to device with least recently modified session. {@link tabs.Tab} objects are sorted by recency in the {@link windows.Window} of the {@link sessions.Session} objects. */ callback?: ( devices: Device[], ) => void, ): void; /** * Reopens a {@link windows.Window} or {@link tabs.Tab}, with an optional callback to run when the entry has been restored. * * @chrome-returns-extra since Chrome 96 * @param sessionId The {@link windows.Window.sessionId}, or {@link tabs.Tab.sessionId} to restore. If this parameter is not specified, the most recently closed session is restored. */ export function restore( sessionId?: string, ): Promise; /** * Reopens a {@link windows.Window} or {@link tabs.Tab}, with an optional callback to run when the entry has been restored. * * @param sessionId The {@link windows.Window.sessionId}, or {@link tabs.Tab.sessionId} to restore. If this parameter is not specified, the most recently closed session is restored. */ export function restore( sessionId?: string, /** * @param restoredSession A {@link sessions.Session} containing the restored {@link windows.Window} or {@link tabs.Tab} object. */ callback?: ( restoredSession: Session, ) => void, ): void; } /** * Stub namespace for the "import" and "export" manifest keys. * * @since Chrome 89 */ export namespace sharedModule { export interface Import { /** * Extension ID of the shared module this extension or app depends on. */ id: string; /** * Minimum supported version of the shared module. */ minimum_version?: string; } export interface Export { /** * Optional list of extension IDs explicitly allowed to import this Shared Module's resources. If no allowlist is given, all extensions are allowed to import it. */ allowlist?: string[]; } } /** * Use the `chrome.sidePanel` API to host content in the browser's side panel alongside the main content of a webpage. * * @since Chrome 114 * @chrome-permission sidePanel * @chrome-min-manifest MV3 * @chrome-platform chromeos * @chrome-platform linux * @chrome-platform mac * @chrome-platform win */ export namespace sidePanel { export interface SidePanel { /** * Developer specified path for side panel display. */ default_path: string; } /** * Defines the possible alignment for the side panel in the browser UI. * * @since Chrome 140 */ export type Side = "left" | "right"; /** * @since Chrome 140 */ export interface PanelLayout { side: Side; } export interface PanelOptions { /** * If specified, the side panel options will only apply to the tab with this id. If omitted, these options set the default behavior (used for any tab that doesn't have specific settings). Note: if the same path is set for this tabId and the default tabId, then the panel for this tabId will be a different instance than the panel for the default tabId. */ tabId?: number; /** * The path to the side panel HTML file to use. This must be a local resource within the extension package. */ path?: string; /** * Whether the side panel should be enabled. This is optional. The default value is true. */ enabled?: boolean; } export interface PanelBehavior { /** * Whether clicking the extension's icon will toggle showing the extension's entry in the side panel. Defaults to false. */ openPanelOnActionClick?: boolean; } export interface GetPanelOptions { /** * If specified, the side panel options for the given tab will be returned. Otherwise, returns the default side panel options (used for any tab that doesn't have specific settings). */ tabId?: number; } /** * @since Chrome 116 */ export interface OpenOptions { /** * The window in which to open the side panel. This is only applicable if the extension has a global (non-tab-specific) side panel or `tabId` is also specified. This will override any currently-active global side panel the user has open in the given window. At least one of this or `tabId` must be provided. */ windowId?: number; /** * The tab in which to open the side panel. If the corresponding tab has a tab-specific side panel, the panel will only be open for that tab. If there is not a tab-specific panel, the global panel will be open in the specified tab and any other tabs without a currently-open tab- specific panel. This will override any currently-active side panel (global or tab-specific) in the corresponding tab. At least one of this or `windowId` must be provided. */ tabId?: number; } /** * @since Chrome 141 */ export interface CloseOptions { /** * The window in which to close the side panel. If a global side panel is open in the specified window, it will be closed for all tabs in that window where no tab-specific panel is active. At least one of this or `tabId` must be provided. */ windowId?: number; /** * The tab in which to close the side panel. If a tab-specific side panel is open in the specified tab, it will be closed for that tab. At least one of this or `windowId` must be provided. */ tabId?: number; } /** * @since Chrome 141 */ export interface PanelOpenedInfo { /** * The ID of the window where the side panel is opened. This is available for both global and tab-specific panels. */ windowId: number; /** * The optional ID of the tab where the side panel is opened. This is provided only when the panel is tab-specific. */ tabId?: number; /** * The path of the local resource within the extension package whose content is displayed in the panel. */ path: string; } /** * @since Chrome 142 */ export interface PanelClosedInfo { /** * The ID of the window where the side panel was closed. This is available for both global and tab-specific panels. */ windowId: number; /** * The optional ID of the tab where the side panel was closed. This is provided only when the panel is tab-specific. */ tabId?: number; /** * The path of the local resource within the extension package whose content is displayed in the panel. */ path: string; } /** * Fired when the extension's side panel is opened. * * @since Chrome 141 */ export const onOpened: events.Event<( info: PanelOpenedInfo, ) => void>; /** * Fired when the extension's side panel is closed. * * @since Chrome 144 */ export const onClosed: events.Event<( info: PanelClosedInfo, ) => void>; /** * Configures the side panel. * * @param options The configuration options to apply to the panel. * @returns Returns a Promise which resolves when the options have been set. */ export function setOptions( options: PanelOptions, ): Promise; /** * Configures the side panel. * * @param options The configuration options to apply to the panel. */ export function setOptions( options: PanelOptions, callback?: () => void, ): void; /** * Returns the active panel configuration. * * @param options Specifies the context to return the configuration for. * @returns Returns a Promise which resolves with the active panel configuration. */ export function getOptions( options: GetPanelOptions, ): Promise; /** * Returns the active panel configuration. * * @param options Specifies the context to return the configuration for. */ export function getOptions( options: GetPanelOptions, callback?: ( options: PanelOptions, ) => void, ): void; /** * Configures the extension's side panel behavior. This is an upsert operation. * * @param behavior The new behavior to be set. * @returns Returns a Promise which resolves when the new behavior has been set. */ export function setPanelBehavior( behavior: PanelBehavior, ): Promise; /** * Configures the extension's side panel behavior. This is an upsert operation. * * @param behavior The new behavior to be set. */ export function setPanelBehavior( behavior: PanelBehavior, callback?: () => void, ): void; /** * Returns the extension's current side panel behavior. * * @returns Returns a Promise which resolves with the extension's side panel behavior. */ export function getPanelBehavior(): Promise; /** * Returns the extension's current side panel behavior. */ export function getPanelBehavior( callback?: ( behavior: PanelBehavior, ) => void, ): void; /** * Opens the side panel for the extension. This may only be called in response to a user action. * * @param options Specifies the context in which to open the side panel. * @returns Returns a Promise which resolves when the side panel has been opened. * @since Chrome 116 */ export function open( options: OpenOptions, ): Promise; /** * Opens the side panel for the extension. This may only be called in response to a user action. * * @param options Specifies the context in which to open the side panel. * @since Chrome 116 */ export function open( options: OpenOptions, callback?: () => void, ): void; /** * Returns the side panel's current layout. * * @returns Returns a Promise which resolves with a {@link PanelLayout}. * @since Chrome 140 */ export function getLayout(): Promise; /** * Returns the side panel's current layout. * * @since Chrome 140 */ export function getLayout( callback?: ( layout: PanelLayout, ) => void, ): void; } /** * Use the `chrome.socket` API to send and receive data over the network using TCP and UDP connections. **Note:** Starting with Chrome 33, this API is deprecated in favor of the {@link sockets.udp}, {@link sockets.tcp} and {@link sockets.tcpServer} APIs. * * @chrome-permission socket * @chrome-platform-apps * @chrome-platform chromeos * @chrome-platform linux * @chrome-platform mac * @chrome-platform win */ export namespace socket { export type SocketType = "tcp" | "udp"; export interface CreateOptions { } export interface CreateInfo { /** * The id of the newly created socket. */ socketId: number; } export interface AcceptInfo { resultCode: number; /** * The id of the accepted socket. */ socketId?: number; } export interface ReadInfo { /** * The resultCode returned from the underlying read() call. */ resultCode: number; data: ArrayBuffer; } export interface WriteInfo { /** * The number of bytes sent, or a negative error code. */ bytesWritten: number; } export interface RecvFromInfo { /** * The resultCode returned from the underlying recvfrom() call. */ resultCode: number; data: ArrayBuffer; /** * The address of the remote machine. */ address: string; port: number; } export interface SocketInfo { /** * The type of the passed socket. This will be `tcp` or `udp`. */ socketType: SocketType; /** * Whether or not the underlying socket is connected. * * For `tcp` sockets, this will remain true even if the remote peer has disconnected. Reading or writing to the socket may then result in an error, hinting that this socket should be disconnected via `disconnect()`. * * For `udp` sockets, this just represents whether a default remote address has been specified for reading and writing packets. */ connected: boolean; /** * If the underlying socket is connected, contains the IPv4/6 address of the peer. */ peerAddress?: string; /** * If the underlying socket is connected, contains the port of the connected peer. */ peerPort?: number; /** * If the underlying socket is bound or connected, contains its local IPv4/6 address. */ localAddress?: string; /** * If the underlying socket is bound or connected, contains its local port. */ localPort?: number; } export interface NetworkInterface { /** * The underlying name of the adapter. On \*nix, this will typically be "eth0", "lo", etc. */ name: string; /** * The available IPv4/6 address. */ address: string; /** * The prefix length */ prefixLength: number; } export interface TLSVersionConstraints { /** * The minimum and maximum acceptable versions of TLS. Supported values are `tls1.2` or `tls1.3`. * * The values `tls1` and `tls1.1` are no longer supported. If `min` is set to one of these values, it will be silently clamped to `tls1.2`. If `max` is set to one of those values, or any other unrecognized value, it will be silently ignored. */ min?: string; max?: string; } export interface SecureOptions { tlsVersion?: TLSVersionConstraints; } /** * Creates a socket of the specified type that will connect to the specified remote machine. * * @chrome-returns-extra since Chrome 121 * @param type The type of socket to create. Must be `tcp` or `udp`. * @param options The socket options. */ export function create( type: SocketType, options?: CreateOptions, ): Promise; /** * Creates a socket of the specified type that will connect to the specified remote machine. * * @param type The type of socket to create. Must be `tcp` or `udp`. * @param options The socket options. */ export function create( type: SocketType, options?: CreateOptions, callback?: ( createInfo: CreateInfo, ) => void, ): void; /** * Destroys the socket. Each socket created should be destroyed after use. * * @param socketId The socketId. */ export function destroy( socketId: number, ): void; /** * Connects the socket to the remote machine (for a `tcp` socket). For a `udp` socket, this sets the default address which packets are sent to and read from for `read()` and `write()` calls. * * @param socketId The socketId. * @param hostname The hostname or IP address of the remote machine. * @param port The port of the remote machine. * @param callback Called when the connection attempt is complete. */ export function connect( socketId: number, hostname: string, port: number, callback: ( result: number, ) => void, ): void; /** * Binds the local address for socket. Currently, it does not support TCP socket. * * @param socketId The socketId. * @param address The address of the local machine. * @param port The port of the local machine. * @param callback Called when the bind attempt is complete. */ export function bind( socketId: number, address: string, port: number, callback: ( result: number, ) => void, ): void; /** * Disconnects the socket. For UDP sockets, `disconnect` is a non-operation but is safe to call. * * @param socketId The socketId. */ export function disconnect( socketId: number, ): void; /** * Reads data from the given connected socket. * * @param socketId The socketId. * @param bufferSize The read buffer size. * @param callback Delivers data that was available to be read without blocking. */ export function read( socketId: number, bufferSize: number, callback: ( readInfo: ReadInfo, ) => void, ): void; /** * Reads data from the given connected socket. * * @param socketId The socketId. * @param callback Delivers data that was available to be read without blocking. */ export function read( socketId: number, callback: ( readInfo: ReadInfo, ) => void, ): void; /** * Writes data on the given connected socket. * * @param socketId The socketId. * @param data The data to write. * @param callback Called when the write operation completes without blocking or an error occurs. */ export function write( socketId: number, data: ArrayBuffer, callback: ( writeInfo: WriteInfo, ) => void, ): void; /** * Receives data from the given UDP socket. * * @param socketId The socketId. * @param bufferSize The receive buffer size. * @param callback Returns result of the recvFrom operation. */ export function recvFrom( socketId: number, bufferSize: number, callback: ( recvFromInfo: RecvFromInfo, ) => void, ): void; /** * Receives data from the given UDP socket. * * @param socketId The socketId. * @param callback Returns result of the recvFrom operation. */ export function recvFrom( socketId: number, callback: ( recvFromInfo: RecvFromInfo, ) => void, ): void; /** * Sends data on the given UDP socket to the given address and port. * * @param socketId The socketId. * @param data The data to write. * @param address The address of the remote machine. * @param port The port of the remote machine. * @param callback Called when the send operation completes without blocking or an error occurs. */ export function sendTo( socketId: number, data: ArrayBuffer, address: string, port: number, callback: ( writeInfo: WriteInfo, ) => void, ): void; /** * This method applies to TCP sockets only. Listens for connections on the specified port and address. This effectively makes this a server socket, and client socket functions (connect, read, write) can no longer be used on this socket. * * @param socketId The socketId. * @param address The address of the local machine. * @param port The port of the local machine. * @param backlog Length of the socket's listen queue. * @param callback Called when listen operation completes. */ export function listen( socketId: number, address: string, port: number, backlog: number, callback: ( result: number, ) => void, ): void; /** * This method applies to TCP sockets only. Listens for connections on the specified port and address. This effectively makes this a server socket, and client socket functions (connect, read, write) can no longer be used on this socket. * * @param socketId The socketId. * @param address The address of the local machine. * @param port The port of the local machine. * @param callback Called when listen operation completes. */ export function listen( socketId: number, address: string, port: number, callback: ( result: number, ) => void, ): void; /** * This method applies to TCP sockets only. Registers a callback function to be called when a connection is accepted on this listening server socket. Listen must be called first. If there is already an active accept callback, this callback will be invoked immediately with an error as the resultCode. * * @param socketId The socketId. * @param callback The callback is invoked when a new socket is accepted. */ export function accept( socketId: number, callback: ( acceptInfo: AcceptInfo, ) => void, ): void; /** * Enables or disables the keep-alive functionality for a TCP connection. * * @param socketId The socketId. * @param enable If true, enable keep-alive functionality. * @param delay Set the delay seconds between the last data packet received and the first keepalive probe. Default is 0. * @param callback Called when the setKeepAlive attempt is complete. */ export function setKeepAlive( socketId: number, enable: boolean, delay: number, callback: ( result: boolean, ) => void, ): void; /** * Enables or disables the keep-alive functionality for a TCP connection. * * @param socketId The socketId. * @param enable If true, enable keep-alive functionality. * @param callback Called when the setKeepAlive attempt is complete. */ export function setKeepAlive( socketId: number, enable: boolean, callback: ( result: boolean, ) => void, ): void; /** * Sets or clears `TCP_NODELAY` for a TCP connection. Nagle's algorithm will be disabled when `TCP_NODELAY` is set. * * @param socketId The socketId. * @param noDelay If true, disables Nagle's algorithm. * @param callback Called when the setNoDelay attempt is complete. */ export function setNoDelay( socketId: number, noDelay: boolean, callback: ( result: boolean, ) => void, ): void; /** * Retrieves the state of the given socket. * * @chrome-returns-extra since Chrome 121 * @param socketId The socketId. */ export function getInfo( socketId: number, ): Promise; /** * Retrieves the state of the given socket. * * @param socketId The socketId. */ export function getInfo( socketId: number, callback?: ( result: SocketInfo, ) => void, ): void; /** * Retrieves information about local adapters on this system. * * @chrome-returns-extra since Chrome 121 */ export function getNetworkList(): Promise; /** * Retrieves information about local adapters on this system. */ export function getNetworkList( callback?: ( result: NetworkInterface[], ) => void, ): void; /** * Join the multicast group and start to receive packets from that group. The socket must be of UDP type and must be bound to a local port before calling this method. * * @param socketId The socketId. * @param address The group address to join. Domain names are not supported. * @param callback Called when the join group operation is done with an integer parameter indicating the platform-independent error code. */ export function joinGroup( socketId: number, address: string, callback: ( result: number, ) => void, ): void; /** * Leave the multicast group previously joined using `joinGroup`. It's not necessary to leave the multicast group before destroying the socket or exiting. This is automatically called by the OS. * * Leaving the group will prevent the router from sending multicast datagrams to the local host, presuming no other process on the host is still joined to the group. * * @param socketId The socketId. * @param address The group address to leave. Domain names are not supported. * @param callback Called when the leave group operation is done with an integer parameter indicating the platform-independent error code. */ export function leaveGroup( socketId: number, address: string, callback: ( result: number, ) => void, ): void; /** * Set the time-to-live of multicast packets sent to the multicast group. * * Calling this method does not require multicast permissions. * * @param socketId The socketId. * @param ttl The time-to-live value. * @param callback Called when the configuration operation is done. */ export function setMulticastTimeToLive( socketId: number, ttl: number, callback: ( result: number, ) => void, ): void; /** * Set whether multicast packets sent from the host to the multicast group will be looped back to the host. * * Note: the behavior of `setMulticastLoopbackMode` is slightly different between Windows and Unix-like systems. The inconsistency happens only when there is more than one application on the same host joined to the same multicast group while having different settings on multicast loopback mode. On Windows, the applications with loopback off will not RECEIVE the loopback packets; while on Unix-like systems, the applications with loopback off will not SEND the loopback packets to other applications on the same host. See MSDN: https://learn.microsoft.com/en-us/windows/win32/winsock/ip-multicast-2 * * Calling this method does not require multicast permissions. * * @param socketId The socketId. * @param enabled Indicate whether to enable loopback mode. * @param callback Called when the configuration operation is done. */ export function setMulticastLoopbackMode( socketId: number, enabled: boolean, callback: ( result: number, ) => void, ): void; /** * Get the multicast group addresses the socket is currently joined to. * * @param socketId The socketId. * @param callback Called with an array of strings of the result. */ export function getJoinedGroups( socketId: number, callback: ( groups: string[], ) => void, ): void; /** * Start a TLS client connection over a connected TCP client socket. * * @param socketId The connected socket to use. * @param options Constraints and parameters for the TLS connection. * @param callback Called when the TLS connection attempt is complete. */ export function secure( socketId: number, options: SecureOptions, callback: ( result: number, ) => void, ): void; /** * Start a TLS client connection over a connected TCP client socket. * * @param socketId The connected socket to use. * @param callback Called when the TLS connection attempt is complete. */ export function secure( socketId: number, callback: ( result: number, ) => void, ): void; } /** * Use the `chrome.sockets.tcp` API to send and receive data over the network using TCP connections. This API supersedes the TCP functionality previously found in the `chrome.socket` API. * * @chrome-manifest sockets * @chrome-platform-apps * @chrome-platform chromeos * @chrome-platform linux * @chrome-platform mac * @chrome-platform win */ export namespace sockets.tcp { export interface SocketProperties { /** * Flag indicating if the socket is left open when the event page of the application is unloaded (see [Manage App Lifecycle](https://developer.chrome.com/docs/apps/app_lifecycle)). The default value is "false." When the application is loaded, any sockets previously opened with persistent=true can be fetched with `getSockets`. */ persistent?: boolean; /** * An application-defined string associated with the socket. */ name?: string; /** * The size of the buffer used to receive data. The default value is 4096. */ bufferSize?: number; } export interface CreateInfo { /** * The ID of the newly created socket. Note that socket IDs created from this API are not compatible with socket IDs created from other APIs, such as the deprecated `{@link socket}` API. */ socketId: number; } /** * DNS resolution preferences. The default is `any` and uses the current OS config which may return IPv4 or IPv6. `ipv4` forces IPv4, and `ipv6` forces IPv6. * * @since Chrome 103 */ export type DnsQueryType = "any" | "ipv4" | "ipv6"; export interface SendInfo { /** * The result code returned from the underlying network call. A negative value indicates an error. */ resultCode: number; /** * The number of bytes sent (if result == 0) */ bytesSent?: number; } export interface TLSVersionConstraints { /** * The minimum and maximum acceptable versions of TLS. Supported values are `tls1.2` or `tls1.3`. * * The values `tls1` and `tls1.1` are no longer supported. If `min` is set to one of these values, it will be silently clamped to `tls1.2`. If `max` is set to one of those values, or any other unrecognized value, it will be silently ignored. */ min?: string; max?: string; } export interface SecureOptions { tlsVersion?: TLSVersionConstraints; } export interface SocketInfo { /** * The socket identifier. */ socketId: number; /** * Flag indicating whether the socket is left open when the application is suspended (see `SocketProperties.persistent`). */ persistent: boolean; /** * Application-defined string associated with the socket. */ name?: string; /** * The size of the buffer used to receive data. If no buffer size has been specified explictly, the value is not provided. */ bufferSize?: number; /** * Flag indicating whether a connected socket blocks its peer from sending more data (see `setPaused`). */ paused: boolean; /** * Flag indicating whether the socket is connected to a remote peer. */ connected: boolean; /** * If the underlying socket is connected, contains its local IPv4/6 address. */ localAddress?: string; /** * If the underlying socket is connected, contains its local port. */ localPort?: number; /** * If the underlying socket is connected, contains the peer/ IPv4/6 address. */ peerAddress?: string; /** * If the underlying socket is connected, contains the peer port. */ peerPort?: number; } export interface ReceiveInfo { /** * The socket identifier. */ socketId: number; /** * The data received, with a maxium size of `bufferSize`. */ data: ArrayBuffer; } export interface ReceiveErrorInfo { /** * The socket identifier. */ socketId: number; /** * The result code returned from the underlying network call. */ resultCode: number; } /** * Event raised when data has been received for a given socket. */ export const onReceive: events.Event<( info: ReceiveInfo, ) => void>; /** * Event raised when a network error occured while the runtime was waiting for data on the socket address and port. Once this event is raised, the socket is set to `paused` and no more `onReceive` events are raised for this socket. */ export const onReceiveError: events.Event<( info: ReceiveErrorInfo, ) => void>; /** * Creates a TCP socket. * * @chrome-returns-extra since Chrome 121 * @param properties The socket properties (optional). */ export function create( properties?: SocketProperties, ): Promise; /** * Creates a TCP socket. * * @param properties The socket properties (optional). */ export function create( properties?: SocketProperties, /** * @param createInfo The result of the socket creation. */ callback?: ( createInfo: CreateInfo, ) => void, ): void; /** * Updates the socket properties. * * @chrome-returns-extra since Chrome 121 * @param socketId The socket identifier. * @param properties The properties to update. */ export function update( socketId: number, properties: SocketProperties, ): Promise; /** * Updates the socket properties. * * @param socketId The socket identifier. * @param properties The properties to update. */ export function update( socketId: number, properties: SocketProperties, callback?: () => void, ): void; /** * Enables or disables the application from receiving messages from its peer. The default value is "false". Pausing a socket is typically used by an application to throttle data sent by its peer. When a socket is paused, no `onReceive` event is raised. When a socket is connected and un-paused, `onReceive` events are raised again when messages are received. * * @chrome-returns-extra since Chrome 121 */ export function setPaused( socketId: number, paused: boolean, ): Promise; /** * Enables or disables the application from receiving messages from its peer. The default value is "false". Pausing a socket is typically used by an application to throttle data sent by its peer. When a socket is paused, no `onReceive` event is raised. When a socket is connected and un-paused, `onReceive` events are raised again when messages are received. */ export function setPaused( socketId: number, paused: boolean, callback?: () => void, ): void; /** * Enables or disables the keep-alive functionality for a TCP connection. * * @param socketId The socket identifier. * @param enable If true, enable keep-alive functionality. * @param delay Set the delay seconds between the last data packet received and the first keepalive probe. Default is 0. * @param callback Called when the setKeepAlive attempt is complete. */ export function setKeepAlive( socketId: number, enable: boolean, delay: number, /** * @param result The result code returned from the underlying network call. A negative value indicates an error. */ callback: ( result: number, ) => void, ): void; /** * Enables or disables the keep-alive functionality for a TCP connection. * * @param socketId The socket identifier. * @param enable If true, enable keep-alive functionality. * @param callback Called when the setKeepAlive attempt is complete. */ export function setKeepAlive( socketId: number, enable: boolean, /** * @param result The result code returned from the underlying network call. A negative value indicates an error. */ callback: ( result: number, ) => void, ): void; /** * Sets or clears `TCP_NODELAY` for a TCP connection. Nagle's algorithm will be disabled when `TCP_NODELAY` is set. * * @param socketId The socket identifier. * @param noDelay If true, disables Nagle's algorithm. * @param callback Called when the setNoDelay attempt is complete. */ export function setNoDelay( socketId: number, noDelay: boolean, /** * @param result The result code returned from the underlying network call. A negative value indicates an error. */ callback: ( result: number, ) => void, ): void; /** * Connects the socket to a remote machine. When the `connect` operation completes successfully, `onReceive` events are raised when data is received from the peer. If a network error occurs while the runtime is receiving packets, a `onReceiveError` event is raised, at which point no more `onReceive` event will be raised for this socket until the `resume` method is called. * * @param socketId The socket identifier. * @param peerAddress The address of the remote machine. DNS name, IPv4 and IPv6 formats are supported. * @param peerPort The port of the remote machine. * @param dnsQueryType The address resolution preference. * @param callback Called when the connect attempt is complete. */ export function connect( socketId: number, peerAddress: string, peerPort: number, /** * @since Chrome 103 */ dnsQueryType: DnsQueryType, /** * @param result The result code returned from the underlying network call. A negative value indicates an error. */ callback: ( result: number, ) => void, ): void; /** * Connects the socket to a remote machine. When the `connect` operation completes successfully, `onReceive` events are raised when data is received from the peer. If a network error occurs while the runtime is receiving packets, a `onReceiveError` event is raised, at which point no more `onReceive` event will be raised for this socket until the `resume` method is called. * * @param socketId The socket identifier. * @param peerAddress The address of the remote machine. DNS name, IPv4 and IPv6 formats are supported. * @param peerPort The port of the remote machine. * @param callback Called when the connect attempt is complete. */ export function connect( socketId: number, peerAddress: string, peerPort: number, /** * @param result The result code returned from the underlying network call. A negative value indicates an error. */ callback: ( result: number, ) => void, ): void; /** * Disconnects the socket. * * @chrome-returns-extra since Chrome 121 * @param socketId The socket identifier. */ export function disconnect( socketId: number, ): Promise; /** * Disconnects the socket. * * @param socketId The socket identifier. */ export function disconnect( socketId: number, callback?: () => void, ): void; /** * Start a TLS client connection over the connected TCP client socket. * * @param socketId The existing, connected socket to use. * @param options Constraints and parameters for the TLS connection. * @param callback Called when the connection attempt is complete. */ export function secure( socketId: number, options: SecureOptions, callback: ( result: number, ) => void, ): void; /** * Start a TLS client connection over the connected TCP client socket. * * @param socketId The existing, connected socket to use. * @param callback Called when the connection attempt is complete. */ export function secure( socketId: number, callback: ( result: number, ) => void, ): void; /** * Sends data on the given TCP socket. * * @param socketId The socket identifier. * @param data The data to send. * @param callback Called when the `send` operation completes. */ export function send( socketId: number, data: ArrayBuffer, /** * @param sendInfo Result of the `send` method. */ callback: ( sendInfo: SendInfo, ) => void, ): void; /** * Closes the socket and releases the address/port the socket is bound to. Each socket created should be closed after use. The socket id is no no longer valid as soon at the function is called. However, the socket is guaranteed to be closed only when the callback is invoked. * * @chrome-returns-extra since Chrome 121 * @param socketId The socket identifier. */ export function close( socketId: number, ): Promise; /** * Closes the socket and releases the address/port the socket is bound to. Each socket created should be closed after use. The socket id is no no longer valid as soon at the function is called. However, the socket is guaranteed to be closed only when the callback is invoked. * * @param socketId The socket identifier. */ export function close( socketId: number, callback?: () => void, ): void; /** * Retrieves the state of the given socket. * * @chrome-returns-extra since Chrome 121 * @param socketId The socket identifier. */ export function getInfo( socketId: number, ): Promise; /** * Retrieves the state of the given socket. * * @param socketId The socket identifier. */ export function getInfo( socketId: number, /** * @param socketInfo Object containing the socket information. */ callback?: ( socketInfo: SocketInfo, ) => void, ): void; /** * Retrieves the list of currently opened sockets owned by the application. * * @chrome-returns-extra since Chrome 121 */ export function getSockets(): Promise; /** * Retrieves the list of currently opened sockets owned by the application. */ export function getSockets( /** * @param socketInfos Array of object containing socket information. */ callback?: ( socketInfos: SocketInfo[], ) => void, ): void; } /** * Use the `chrome.sockets.tcpServer` API to create server applications using TCP connections. This API supersedes the TCP functionality previously found in the `chrome.socket` API. * * @chrome-manifest sockets * @chrome-platform-apps * @chrome-platform chromeos * @chrome-platform linux * @chrome-platform mac * @chrome-platform win */ export namespace sockets.tcpServer { export interface SocketProperties { /** * Flag indicating if the socket remains open when the event page of the application is unloaded (see [Manage App Lifecycle](https://developer.chrome.com/docs/apps/app_lifecycle)). The default value is "false." When the application is loaded, any sockets previously opened with persistent=true can be fetched with `getSockets`. */ persistent?: boolean; /** * An application-defined string associated with the socket. */ name?: string; } export interface CreateInfo { /** * The ID of the newly created server socket. Note that socket IDs created from this API are not compatible with socket IDs created from other APIs, such as the deprecated `{@link socket}` API. */ socketId: number; } export interface SocketInfo { /** * The socket identifier. */ socketId: number; /** * Flag indicating if the socket remains open when the event page of the application is unloaded (see `SocketProperties.persistent`). The default value is "false". */ persistent: boolean; /** * Application-defined string associated with the socket. */ name?: string; /** * Flag indicating whether connection requests on a listening socket are dispatched through the `onAccept` event or queued up in the listen queue backlog. See `setPaused`. The default value is "false". */ paused: boolean; /** * If the socket is listening, contains its local IPv4/6 address. */ localAddress?: string; /** * If the socket is listening, contains its local port. */ localPort?: number; } export interface AcceptInfo { /** * The server socket identifier. */ socketId: number; /** * The client socket identifier, i.e. the socket identifier of the newly established connection. This socket identifier should be used only with functions from the `chrome.sockets.tcp` namespace. Note the client socket is initially paused and must be explictly un-paused by the application to start receiving data. */ clientSocketId: number; } export interface AcceptErrorInfo { /** * The server socket identifier. */ socketId: number; /** * The result code returned from the underlying network call. */ resultCode: number; } /** * Event raised when a connection has been made to the server socket. */ export const onAccept: events.Event<( info: AcceptInfo, ) => void>; /** * Event raised when a network error occured while the runtime was waiting for new connections on the socket address and port. Once this event is raised, the socket is set to `paused` and no more `onAccept` events are raised for this socket until the socket is resumed. */ export const onAcceptError: events.Event<( info: AcceptErrorInfo, ) => void>; /** * Creates a TCP server socket. * * @chrome-returns-extra since Chrome 121 * @param properties The socket properties (optional). */ export function create( properties?: SocketProperties, ): Promise; /** * Creates a TCP server socket. * * @param properties The socket properties (optional). */ export function create( properties?: SocketProperties, /** * @param createInfo The result of the socket creation. */ callback?: ( createInfo: CreateInfo, ) => void, ): void; /** * Updates the socket properties. * * @chrome-returns-extra since Chrome 121 * @param socketId The socket identifier. * @param properties The properties to update. */ export function update( socketId: number, properties: SocketProperties, ): Promise; /** * Updates the socket properties. * * @param socketId The socket identifier. * @param properties The properties to update. */ export function update( socketId: number, properties: SocketProperties, callback?: () => void, ): void; /** * Enables or disables a listening socket from accepting new connections. When paused, a listening socket accepts new connections until its backlog (see `listen` function) is full then refuses additional connection requests. `onAccept` events are raised only when the socket is un-paused. * * @chrome-returns-extra since Chrome 121 */ export function setPaused( socketId: number, paused: boolean, ): Promise; /** * Enables or disables a listening socket from accepting new connections. When paused, a listening socket accepts new connections until its backlog (see `listen` function) is full then refuses additional connection requests. `onAccept` events are raised only when the socket is un-paused. */ export function setPaused( socketId: number, paused: boolean, callback?: () => void, ): void; /** * Listens for connections on the specified port and address. If the port/address is in use, the callback indicates a failure. * * @param socketId The socket identifier. * @param address The address of the local machine. * @param port The port of the local machine. When set to `0`, a free port is chosen dynamically. The dynamically allocated port can be found by calling `getInfo`. * @param backlog Length of the socket's listen queue. The default value depends on the Operating System (SOMAXCONN), which ensures a reasonable queue length for most applications. * @param callback Called when listen operation completes. */ export function listen( socketId: number, address: string, port: number, backlog: number, /** * @param result The result code returned from the underlying network call. A negative value indicates an error. */ callback: ( result: number, ) => void, ): void; /** * Listens for connections on the specified port and address. If the port/address is in use, the callback indicates a failure. * * @param socketId The socket identifier. * @param address The address of the local machine. * @param port The port of the local machine. When set to `0`, a free port is chosen dynamically. The dynamically allocated port can be found by calling `getInfo`. * @param callback Called when listen operation completes. */ export function listen( socketId: number, address: string, port: number, /** * @param result The result code returned from the underlying network call. A negative value indicates an error. */ callback: ( result: number, ) => void, ): void; /** * Disconnects the listening socket, i.e. stops accepting new connections and releases the address/port the socket is bound to. The socket identifier remains valid, e.g. it can be used with `listen` to accept connections on a new port and address. * * @chrome-returns-extra since Chrome 121 * @param socketId The socket identifier. */ export function disconnect( socketId: number, ): Promise; /** * Disconnects the listening socket, i.e. stops accepting new connections and releases the address/port the socket is bound to. The socket identifier remains valid, e.g. it can be used with `listen` to accept connections on a new port and address. * * @param socketId The socket identifier. */ export function disconnect( socketId: number, callback?: () => void, ): void; /** * Disconnects and destroys the socket. Each socket created should be closed after use. The socket id is no longer valid as soon at the function is called. However, the socket is guaranteed to be closed only when the callback is invoked. * * @chrome-returns-extra since Chrome 121 * @param socketId The socket identifier. */ export function close( socketId: number, ): Promise; /** * Disconnects and destroys the socket. Each socket created should be closed after use. The socket id is no longer valid as soon at the function is called. However, the socket is guaranteed to be closed only when the callback is invoked. * * @param socketId The socket identifier. */ export function close( socketId: number, callback?: () => void, ): void; /** * Retrieves the state of the given socket. * * @chrome-returns-extra since Chrome 121 * @param socketId The socket identifier. */ export function getInfo( socketId: number, ): Promise; /** * Retrieves the state of the given socket. * * @param socketId The socket identifier. */ export function getInfo( socketId: number, /** * @param socketInfo Object containing the socket information. */ callback?: ( socketInfo: SocketInfo, ) => void, ): void; /** * Retrieves the list of currently opened sockets owned by the application. * * @chrome-returns-extra since Chrome 121 */ export function getSockets(): Promise; /** * Retrieves the list of currently opened sockets owned by the application. */ export function getSockets( /** * @param socketInfos Array of object containing socket information. */ callback?: ( socketInfos: SocketInfo[], ) => void, ): void; } /** * Use the `chrome.sockets.udp` API to send and receive data over the network using UDP connections. This API supersedes the UDP functionality previously found in the "socket" API. * * @chrome-manifest sockets * @chrome-platform-apps * @chrome-platform chromeos * @chrome-platform linux * @chrome-platform mac * @chrome-platform win */ export namespace sockets.udp { export interface SocketProperties { /** * Flag indicating if the socket is left open when the event page of the application is unloaded (see [Manage App Lifecycle](https://developer.chrome.com/docs/apps/app_lifecycle)). The default value is "false." When the application is loaded, any sockets previously opened with persistent=true can be fetched with `getSockets`. */ persistent?: boolean; /** * An application-defined string associated with the socket. */ name?: string; /** * The size of the buffer used to receive data. If the buffer is too small to receive the UDP packet, data is lost. The default value is 4096. */ bufferSize?: number; } export interface CreateInfo { /** * The ID of the newly created socket. Note that socket IDs created from this API are not compatible with socket IDs created from other APIs, such as the deprecated `{@link socket}` API. */ socketId: number; } /** * DNS resolution preferences. The default is `any` and uses the current OS config which may return IPv4 or IPv6. `ipv4` forces IPv4, and `ipv6` forces IPv6. * * @since Chrome 103 */ export type DnsQueryType = "any" | "ipv4" | "ipv6"; export interface SendInfo { /** * The result code returned from the underlying network call. A negative value indicates an error. */ resultCode: number; /** * The number of bytes sent (if result == 0) */ bytesSent?: number; } export interface SocketInfo { /** * The socket identifier. */ socketId: number; /** * Flag indicating whether the socket is left open when the application is suspended (see `SocketProperties.persistent`). */ persistent: boolean; /** * Application-defined string associated with the socket. */ name?: string; /** * The size of the buffer used to receive data. If no buffer size has been specified explictly, the value is not provided. */ bufferSize?: number; /** * Flag indicating whether the socket is blocked from firing onReceive events. */ paused: boolean; /** * If the underlying socket is bound, contains its local IPv4/6 address. */ localAddress?: string; /** * If the underlying socket is bound, contains its local port. */ localPort?: number; } export interface ReceiveInfo { /** * The socket ID. */ socketId: number; /** * The UDP packet content (truncated to the current buffer size). */ data: ArrayBuffer; /** * The address of the host the packet comes from. */ remoteAddress: string; /** * The port of the host the packet comes from. */ remotePort: number; } export interface ReceiveErrorInfo { /** * The socket ID. */ socketId: number; /** * The result code returned from the underlying recvfrom() call. */ resultCode: number; } /** * Event raised when a UDP packet has been received for the given socket. */ export const onReceive: events.Event<( info: ReceiveInfo, ) => void>; /** * Event raised when a network error occured while the runtime was waiting for data on the socket address and port. Once this event is raised, the socket is paused and no more `onReceive` events will be raised for this socket until the socket is resumed. */ export const onReceiveError: events.Event<( info: ReceiveErrorInfo, ) => void>; /** * Creates a UDP socket with the given properties. * * @chrome-returns-extra since Chrome 121 * @param properties The socket properties (optional). */ export function create( properties?: SocketProperties, ): Promise; /** * Creates a UDP socket with the given properties. * * @param properties The socket properties (optional). */ export function create( properties?: SocketProperties, /** * @param createInfo The result of the socket creation. */ callback?: ( createInfo: CreateInfo, ) => void, ): void; /** * Updates the socket properties. * * @chrome-returns-extra since Chrome 121 * @param socketId The socket ID. * @param properties The properties to update. */ export function update( socketId: number, properties: SocketProperties, ): Promise; /** * Updates the socket properties. * * @param socketId The socket ID. * @param properties The properties to update. */ export function update( socketId: number, properties: SocketProperties, callback?: () => void, ): void; /** * Pauses or unpauses a socket. A paused socket is blocked from firing `onReceive` events. * * @chrome-returns-extra since Chrome 121 * @param paused Flag to indicate whether to pause or unpause. */ export function setPaused( socketId: number, paused: boolean, ): Promise; /** * Pauses or unpauses a socket. A paused socket is blocked from firing `onReceive` events. * * @param paused Flag to indicate whether to pause or unpause. */ export function setPaused( socketId: number, paused: boolean, callback?: () => void, ): void; /** * Binds the local address and port for the socket. For a client socket, it is recommended to use port 0 to let the platform pick a free port. * * Once the `bind` operation completes successfully, `onReceive` events are raised when UDP packets arrive on the address/port specified -- unless the socket is paused. * * @param socketId The socket ID. * @param address The address of the local machine. DNS name, IPv4 and IPv6 formats are supported. Use "0.0.0.0" to accept packets from all local available network interfaces. * @param port The port of the local machine. Use "0" to bind to a free port. * @param callback Called when the `bind` operation completes. */ export function bind( socketId: number, address: string, port: number, /** * @param result The result code returned from the underlying network call. A negative value indicates an error. */ callback: ( result: number, ) => void, ): void; /** * Sends data on the given socket to the given address and port. The socket must be bound to a local port before calling this method. * * @param socketId The socket ID. * @param data The data to send. * @param address The address of the remote machine. * @param port The port of the remote machine. * @param dnsQueryType The address resolution preference. * @param callback Called when the `send` operation completes. */ export function send( socketId: number, data: ArrayBuffer, address: string, port: number, /** * @since Chrome 103 */ dnsQueryType: DnsQueryType, /** * @param sendInfo Result of the `send` method. */ callback: ( sendInfo: SendInfo, ) => void, ): void; /** * Sends data on the given socket to the given address and port. The socket must be bound to a local port before calling this method. * * @param socketId The socket ID. * @param data The data to send. * @param address The address of the remote machine. * @param port The port of the remote machine. * @param callback Called when the `send` operation completes. */ export function send( socketId: number, data: ArrayBuffer, address: string, port: number, /** * @param sendInfo Result of the `send` method. */ callback: ( sendInfo: SendInfo, ) => void, ): void; /** * Closes the socket and releases the address/port the socket is bound to. Each socket created should be closed after use. The socket id is no longer valid as soon at the function is called. However, the socket is guaranteed to be closed only when the callback is invoked. * * @chrome-returns-extra since Chrome 121 * @param socketId The socket ID. */ export function close( socketId: number, ): Promise; /** * Closes the socket and releases the address/port the socket is bound to. Each socket created should be closed after use. The socket id is no longer valid as soon at the function is called. However, the socket is guaranteed to be closed only when the callback is invoked. * * @param socketId The socket ID. */ export function close( socketId: number, callback?: () => void, ): void; /** * Retrieves the state of the given socket. * * @chrome-returns-extra since Chrome 121 * @param socketId The socket ID. */ export function getInfo( socketId: number, ): Promise; /** * Retrieves the state of the given socket. * * @param socketId The socket ID. */ export function getInfo( socketId: number, /** * @param socketInfo Object containing the socket information. */ callback?: ( socketInfo: SocketInfo, ) => void, ): void; /** * Retrieves the list of currently opened sockets owned by the application. * * @chrome-returns-extra since Chrome 121 */ export function getSockets(): Promise; /** * Retrieves the list of currently opened sockets owned by the application. */ export function getSockets( /** * @param socketInfos Array of object containing socket information. */ callback?: ( socketInfos: SocketInfo[], ) => void, ): void; /** * Joins the multicast group and starts to receive packets from that group. The socket must be bound to a local port before calling this method. * * @param socketId The socket ID. * @param address The group address to join. Domain names are not supported. * @param callback Called when the `joinGroup` operation completes. */ export function joinGroup( socketId: number, address: string, /** * @param result The result code returned from the underlying network call. A negative value indicates an error. */ callback: ( result: number, ) => void, ): void; /** * Leaves the multicast group previously joined using `joinGroup`. This is only necessary to call if you plan to keep using the socketafterwards, since it will be done automatically by the OS when the socket is closed. * * Leaving the group will prevent the router from sending multicast datagrams to the local host, presuming no other process on the host is still joined to the group. * * @param socketId The socket ID. * @param address The group address to leave. Domain names are not supported. * @param callback Called when the `leaveGroup` operation completes. */ export function leaveGroup( socketId: number, address: string, /** * @param result The result code returned from the underlying network call. A negative value indicates an error. */ callback: ( result: number, ) => void, ): void; /** * Sets the time-to-live of multicast packets sent to the multicast group. * * Calling this method does not require multicast permissions. * * @param socketId The socket ID. * @param ttl The time-to-live value. * @param callback Called when the configuration operation completes. */ export function setMulticastTimeToLive( socketId: number, ttl: number, /** * @param result The result code returned from the underlying network call. A negative value indicates an error. */ callback: ( result: number, ) => void, ): void; /** * Sets whether multicast packets sent from the host to the multicast group will be looped back to the host. * * Note: the behavior of `setMulticastLoopbackMode` is slightly different between Windows and Unix-like systems. The inconsistency happens only when there is more than one application on the same host joined to the same multicast group while having different settings on multicast loopback mode. On Windows, the applications with loopback off will not RECEIVE the loopback packets; while on Unix-like systems, the applications with loopback off will not SEND the loopback packets to other applications on the same host. See MSDN: https://learn.microsoft.com/en-us/windows/win32/winsock/ip-multicast-2 * * Calling this method does not require multicast permissions. * * @param socketId The socket ID. * @param enabled Indicate whether to enable loopback mode. * @param callback Called when the configuration operation completes. */ export function setMulticastLoopbackMode( socketId: number, enabled: boolean, /** * @param result The result code returned from the underlying network call. A negative value indicates an error. */ callback: ( result: number, ) => void, ): void; /** * Gets the multicast group addresses the socket is currently joined to. * * @chrome-returns-extra since Chrome 121 * @param socketId The socket ID. */ export function getJoinedGroups( socketId: number, ): Promise; /** * Gets the multicast group addresses the socket is currently joined to. * * @param socketId The socket ID. */ export function getJoinedGroups( socketId: number, /** * @param groups Array of groups the socket joined. */ callback?: ( groups: string[], ) => void, ): void; /** * Enables or disables broadcast packets on this socket. * * @param socketId The socket ID. * @param enabled `true` to enable broadcast packets, `false` to disable them. * @param callback Callback from the `setBroadcast` method. * @since Chrome 44 */ export function setBroadcast( socketId: number, enabled: boolean, /** * @param result The result code returned from the underlying network call. */ callback: ( result: number, ) => void, ): void; } /** * Use the `chrome.storage` API to store, retrieve, and track changes to user data. * * @chrome-permission storage */ export namespace storage { /** * The storage area's access level. * * @chrome-enum "TRUSTED\_CONTEXTS" Specifies contexts originating from the extension itself. * @chrome-enum "TRUSTED\_AND\_UNTRUSTED\_CONTEXTS" Specifies contexts originating from outside the extension. * @since Chrome 102 */ export type AccessLevel = "TRUSTED_CONTEXTS" | "TRUSTED_AND_UNTRUSTED_CONTEXTS"; export interface StorageChange { /** * The old value of the item, if there was an old value. */ oldValue?: any; /** * The new value of the item, if there is a new value. */ newValue?: any; } export interface StorageArea { /** * Fired when one or more items change. * * @since Chrome 73 */ onChanged: events.Event<( changes: {[name: string]: StorageChange}, ) => void>; /** * Gets one or more items from storage. * * @chrome-returns-extra since Chrome 95 * @param keys A single key to get, list of keys to get, or a dictionary specifying default values (see description of the object). An empty list or object will return an empty result object. Pass in `null` to get the entire contents of storage. * @returns Promise that resolves with an object containing a key-value map for the requested items, or rejects on failure. */ get( keys?: string | string[] | {[name: string]: any}, ): Promise<{[name: string]: any}>; /** * Gets one or more items from storage. * * @param keys A single key to get, list of keys to get, or a dictionary specifying default values (see description of the object). An empty list or object will return an empty result object. Pass in `null` to get the entire contents of storage. */ get( keys?: string | string[] | {[name: string]: any}, /** * @param items Object with items in their key-value mappings. */ callback?: ( items: {[name: string]: any}, ) => void, ): void; /** * Gets all keys from storage. * * @returns Promise that resolves with storage keys, or rejects on failure. * @since Chrome 130 */ getKeys(): Promise; /** * Gets all keys from storage. * * @since Chrome 130 */ getKeys( /** * @param keys Array with keys read from storage. */ callback?: ( keys: string[], ) => void, ): void; /** * Gets the amount of space (in bytes) being used by one or more items. * * @chrome-returns-extra since Chrome 95 * @param keys A single key or list of keys to get the total usage for. An empty list will return 0. Pass in `null` to get the total usage of all of storage. * @returns Promise that resolves with the amount of space being used by storage, or rejects on failure. */ getBytesInUse( keys?: string | string[], ): Promise; /** * Gets the amount of space (in bytes) being used by one or more items. * * @param keys A single key or list of keys to get the total usage for. An empty list will return 0. Pass in `null` to get the total usage of all of storage. */ getBytesInUse( keys?: string | string[], /** * @param bytesInUse Amount of space being used in storage, in bytes. */ callback?: ( bytesInUse: number, ) => void, ): void; /** * Sets multiple items. * * @chrome-returns-extra since Chrome 95 * @param items An object which gives each key/value pair to update storage with. Any other key/value pairs in storage will not be affected. Primitive values such as numbers will serialize as expected. Values with a `typeof` `"object"` and `"function"` will typically serialize to `{}`, with the exception of `Array` (serializes as expected), `Date`, and `Regex` (serialize using their `String` representation). * @returns Promise that resolves on success, or rejects on failure. */ set( items: {[name: string]: any}, ): Promise; /** * Sets multiple items. * * @param items An object which gives each key/value pair to update storage with. Any other key/value pairs in storage will not be affected. Primitive values such as numbers will serialize as expected. Values with a `typeof` `"object"` and `"function"` will typically serialize to `{}`, with the exception of `Array` (serializes as expected), `Date`, and `Regex` (serialize using their `String` representation). */ set( items: {[name: string]: any}, callback?: () => void, ): void; /** * Removes one or more items from storage. * * @chrome-returns-extra since Chrome 95 * @param keys A single key or a list of keys for items to remove. * @returns Promise that resolves on success, or rejects on failure. */ remove( keys: string | string[], ): Promise; /** * Removes one or more items from storage. * * @param keys A single key or a list of keys for items to remove. */ remove( keys: string | string[], callback?: () => void, ): void; /** * Removes all items from storage. * * @chrome-returns-extra since Chrome 95 * @returns Promise that resolves on success, or rejects on failure. */ clear(): Promise; /** * Removes all items from storage. */ clear( callback?: () => void, ): void; /** * Sets the desired access level for the storage area. By default, `session` storage is restricted to trusted contexts (extension pages and service workers), while `managed`, `local`, and `sync` storage allow access from both trusted and untrusted contexts. * * @returns Promise that resolves on success, or rejects on failure. * @since Chrome 102 */ setAccessLevel( accessOptions: { /** * The access level of the storage area. */ accessLevel: AccessLevel, }, ): Promise; /** * Sets the desired access level for the storage area. By default, `session` storage is restricted to trusted contexts (extension pages and service workers), while `managed`, `local`, and `sync` storage allow access from both trusted and untrusted contexts. * * @since Chrome 102 */ setAccessLevel( accessOptions: { /** * The access level of the storage area. */ accessLevel: AccessLevel, }, callback?: () => void, ): void; } /** * Items in the `sync` storage area are synced using Chrome Sync. */ export const sync: StorageArea & { /** * The maximum total amount (in bytes) of data that can be stored in sync storage, as measured by the JSON stringification of every value plus every key's length. Updates that would cause this limit to be exceeded fail immediately and set {@link runtime.lastError} when using a callback, or when a Promise is rejected. */ QUOTA_BYTES: 102400, /** * The maximum size (in bytes) of each individual item in sync storage, as measured by the JSON stringification of its value plus its key length. Updates containing items larger than this limit will fail immediately and set {@link runtime.lastError} when using a callback, or when a Promise is rejected. */ QUOTA_BYTES_PER_ITEM: 8192, /** * The maximum number of items that can be stored in sync storage. Updates that would cause this limit to be exceeded will fail immediately and set {@link runtime.lastError} when using a callback, or when a Promise is rejected. */ MAX_ITEMS: 512, /** * The maximum number of `set`, `remove`, or `clear` operations that can be performed each hour. This is 1 every 2 seconds, a lower ceiling than the short term higher writes-per-minute limit. * * Updates that would cause this limit to be exceeded fail immediately and set {@link runtime.lastError} when using a callback, or when a Promise is rejected. */ MAX_WRITE_OPERATIONS_PER_HOUR: 1800, /** * The maximum number of `set`, `remove`, or `clear` operations that can be performed each minute. This is 2 per second, providing higher throughput than writes-per-hour over a shorter period of time. * * Updates that would cause this limit to be exceeded fail immediately and set {@link runtime.lastError} when using a callback, or when a Promise is rejected. */ MAX_WRITE_OPERATIONS_PER_MINUTE: 120, /** * @deprecated The storage.sync API no longer has a sustained write operation quota. */ MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE: 1000000, }; /** * Items in the `local` storage area are local to each machine. */ export const local: StorageArea & { /** * The maximum amount (in bytes) of data that can be stored in local storage, as measured by the JSON stringification of every value plus every key's length. This value will be ignored if the extension has the `unlimitedStorage` permission. Updates that would cause this limit to be exceeded fail immediately and set {@link runtime.lastError} when using a callback, or a rejected Promise if using async/await. */ QUOTA_BYTES: 10485760, }; /** * Items in the `managed` storage area are set by an enterprise policy configured by the domain administrator, and are read-only for the extension; trying to modify this namespace results in an error. For information on configuring a policy, see [Manifest for storage areas](https://developer.chrome.com/docs/extensions/reference/manifest/storage). */ export const managed: StorageArea; /** * Items in the `session` storage area are stored in-memory and will not be persisted to disk. * * @since Chrome 102 * @chrome-min-manifest MV3 */ export const session: StorageArea & { /** * The maximum amount (in bytes) of data that can be stored in memory, as measured by estimating the dynamically allocated memory usage of every value and key. Updates that would cause this limit to be exceeded fail immediately and set {@link runtime.lastError} when using a callback, or when a Promise is rejected. */ QUOTA_BYTES: 10485760, }; /** * Fired when one or more items change. */ export const onChanged: events.Event<( changes: {[name: string]: StorageChange}, areaName: string, ) => void>; } /** * Use the `chrome.syncFileSystem` API to save and synchronize data on Google Drive. This API is NOT for accessing arbitrary user docs stored in Google Drive. It provides app-specific syncable storage for offline and caching usage so that the same data can be available across different clients. Read [Manage Data](https://developer.chrome.com/docs/extensions/app_storage) for more on using this API. * * @chrome-permission syncFileSystem * @chrome-platform-apps */ export namespace syncFileSystem { export type SyncAction = "added" | "updated" | "deleted"; /** * @chrome-enum "initializing" The sync service is being initialized (e.g. restoring data from the database, checking connectivity and authenticating to the service etc). * @chrome-enum "running" The sync service is up and running. * @chrome-enum "authentication\_required" The sync service is not synchronizing files because the remote service needs to be authenticated by the user to proceed. * @chrome-enum "temporary\_unavailable" The sync service is not synchronizing files because the remote service is (temporarily) unavailable due to some recoverable errors, e.g. network is offline, the remote service is down or not reachable etc. More details should be given by `description` parameter in OnServiceInfoUpdated (which could contain service-specific details). * @chrome-enum "disabled" The sync service is disabled and the content will never sync. (E.g. this could happen when the user has no account on the remote service or the sync service has had an unrecoverable error.) */ export type ServiceStatus = "initializing" | "running" | "authentication_required" | "temporary_unavailable" | "disabled"; /** * @chrome-enum "synced" Not conflicting and has no pending local changes. * @chrome-enum "pending" Has one or more pending local changes that haven't been synchronized. * @chrome-enum "conflicting" File conflicts with remote version and must be resolved manually. */ export type FileStatus = "synced" | "pending" | "conflicting"; export type SyncDirection = "local_to_remote" | "remote_to_local"; export type ConflictResolutionPolicy = "last_write_win" | "manual"; export interface FileInfo { /** * `fileEntry` for the target file whose status has changed. Contains name and path information of synchronized file. On file deletion, `fileEntry` information will still be available but file will no longer exist. */ fileEntry: Entry; /** * Resulting file status after {@link onFileStatusChanged} event. The status value can be `'synced'`, `'pending'` or `'conflicting'`. */ status: FileStatus; /** * Sync action taken to fire {@link onFileStatusChanged} event. The action value can be `'added'`, `'updated'` or `'deleted'`. Only applies if status is `'synced'`. */ action?: SyncAction; /** * Sync direction for the {@link onFileStatusChanged} event. Sync direction value can be `'local_to_remote'` or `'remote_to_local'`. Only applies if status is `'synced'`. */ direction?: SyncDirection; } export interface FileStatusInfo { /** * One of the Entry's originally given to getFileStatuses. */ fileEntry: Entry; /** * The status value can be `'synced'`, `'pending'` or `'conflicting'`. */ status: FileStatus; /** * Optional error that is only returned if there was a problem retrieving the FileStatus for the given file. */ error?: string; } export interface StorageInfo { usageBytes: number; quotaBytes: number; } export interface ServiceInfo { state: ServiceStatus; description: string; } /** * Fired when an error or other status change has happened in the sync backend (for example, when the sync is temporarily disabled due to network or authentication error). */ export const onServiceStatusChanged: events.Event<( detail: ServiceInfo, ) => void>; /** * Fired when a file has been updated by the background sync service. */ export const onFileStatusChanged: events.Event<( detail: FileInfo, ) => void>; /** * Returns a syncable filesystem backed by Google Drive. The returned `DOMFileSystem` instance can be operated on in the same way as the Temporary and Persistant file systems (see [http://dev.w3.org/2009/dap/file-system/file-dir-sys.html](https://dev.w3.org/2009/dap/file-system/file-dir-sys.html)). * * Calling this multiple times from the same app will return the same handle to the same file system. * * Note this call can fail. For example, if the user is not signed in to Chrome or if there is no network operation. To handle these errors it is important chrome.runtime.lastError is checked in the callback. * * @chrome-returns-extra since Chrome 117 */ export function requestFileSystem(): Promise; /** * Returns a syncable filesystem backed by Google Drive. The returned `DOMFileSystem` instance can be operated on in the same way as the Temporary and Persistant file systems (see [http://dev.w3.org/2009/dap/file-system/file-dir-sys.html](https://dev.w3.org/2009/dap/file-system/file-dir-sys.html)). * * Calling this multiple times from the same app will return the same handle to the same file system. * * Note this call can fail. For example, if the user is not signed in to Chrome or if there is no network operation. To handle these errors it is important chrome.runtime.lastError is checked in the callback. */ export function requestFileSystem( callback?: ( fileSystem: DOMFileSystem, ) => void, ): void; /** * Sets the default conflict resolution policy for the `'syncable'` file storage for the app. By default it is set to `'last_write_win'`. When conflict resolution policy is set to `'last_write_win'` conflicts for existing files are automatically resolved next time the file is updated. `callback` can be optionally given to know if the request has succeeded or not. * * @chrome-returns-extra since Chrome 117 */ export function setConflictResolutionPolicy( policy: ConflictResolutionPolicy, ): Promise; /** * Sets the default conflict resolution policy for the `'syncable'` file storage for the app. By default it is set to `'last_write_win'`. When conflict resolution policy is set to `'last_write_win'` conflicts for existing files are automatically resolved next time the file is updated. `callback` can be optionally given to know if the request has succeeded or not. */ export function setConflictResolutionPolicy( policy: ConflictResolutionPolicy, callback?: () => void, ): void; /** * Gets the current conflict resolution policy. * * @chrome-returns-extra since Chrome 117 */ export function getConflictResolutionPolicy(): Promise; /** * Gets the current conflict resolution policy. */ export function getConflictResolutionPolicy( callback?: ( policy: ConflictResolutionPolicy, ) => void, ): void; /** * Returns the current usage and quota in bytes for the `'syncable'` file storage for the app. * * @chrome-returns-extra since Chrome 117 */ export function getUsageAndQuota( fileSystem: DOMFileSystem, ): Promise; /** * Returns the current usage and quota in bytes for the `'syncable'` file storage for the app. */ export function getUsageAndQuota( fileSystem: DOMFileSystem, callback?: ( info: StorageInfo, ) => void, ): void; /** * Returns the {@link FileStatus} for the given `fileEntry`. The status value can be `'synced'`, `'pending'` or `'conflicting'`. Note that `'conflicting'` state only happens when the service's conflict resolution policy is set to `'manual'`. * * @chrome-returns-extra since Chrome 117 */ export function getFileStatus( fileEntry: Entry, ): Promise; /** * Returns the {@link FileStatus} for the given `fileEntry`. The status value can be `'synced'`, `'pending'` or `'conflicting'`. Note that `'conflicting'` state only happens when the service's conflict resolution policy is set to `'manual'`. */ export function getFileStatus( fileEntry: Entry, callback?: ( status: FileStatus, ) => void, ): void; /** * Returns each {@link FileStatus} for the given `fileEntry` array. Typically called with the result from dirReader.readEntries(). * * @chrome-returns-extra since Chrome 117 */ export function getFileStatuses( fileEntries: {[name: string]: any}[], ): Promise; /** * Returns each {@link FileStatus} for the given `fileEntry` array. Typically called with the result from dirReader.readEntries(). */ export function getFileStatuses( fileEntries: {[name: string]: any}[], callback?: ( status: FileStatusInfo[], ) => void, ): void; /** * Returns the current sync backend status. * * @chrome-returns-extra since Chrome 117 */ export function getServiceStatus(): Promise; /** * Returns the current sync backend status. */ export function getServiceStatus( callback?: ( status: ServiceStatus, ) => void, ): void; } /** * Use the `system.cpu` API to query CPU metadata. * * @chrome-permission system.cpu */ export namespace system.cpu { export interface CpuTime { /** * The cumulative time used by userspace programs on this processor. */ user: number; /** * The cumulative time used by kernel programs on this processor. */ kernel: number; /** * The cumulative time spent idle by this processor. */ idle: number; /** * The total cumulative time for this processor. This value is equal to user + kernel + idle. */ total: number; } export interface ProcessorInfo { /** * Cumulative usage info for this logical processor. */ usage: CpuTime; } export interface CpuInfo { /** * The number of logical processors. */ numOfProcessors: number; /** * The architecture name of the processors. */ archName: string; /** * The model name of the processors. */ modelName: string; /** * A set of feature codes indicating some of the processor's capabilities. The currently supported codes are "mmx", "sse", "sse2", "sse3", "ssse3", "sse4\_1", "sse4\_2", and "avx". */ features: string[]; /** * Information about each logical processor. */ processors: ProcessorInfo[]; /** * List of CPU temperature readings from each thermal zone of the CPU. Temperatures are in degrees Celsius. * * **Currently supported on Chrome OS only.** * * @since Chrome 60 */ temperatures: number[]; } /** * Queries basic CPU information of the system. * * @chrome-returns-extra since Chrome 91 */ export function getInfo(): Promise; /** * Queries basic CPU information of the system. */ export function getInfo( callback?: ( info: CpuInfo, ) => void, ): void; } /** * Use the `system.display` API to query display metadata. * * @chrome-permission system.display * @chrome-platform chromeos * @chrome-platform linux * @chrome-platform mac * @chrome-platform win */ export namespace system.display { export interface Bounds { /** * The x-coordinate of the upper-left corner. */ left: number; /** * The y-coordinate of the upper-left corner. */ top: number; /** * The width of the display in pixels. */ width: number; /** * The height of the display in pixels. */ height: number; } export interface Insets { /** * The x-axis distance from the left bound. */ left: number; /** * The y-axis distance from the top bound. */ top: number; /** * The x-axis distance from the right bound. */ right: number; /** * The y-axis distance from the bottom bound. */ bottom: number; } /** * @since Chrome 57 */ export interface Point { /** * The x-coordinate of the point. */ x: number; /** * The y-coordinate of the point. */ y: number; } /** * @since Chrome 57 */ export interface TouchCalibrationPair { /** * The coordinates of the display point. */ displayPoint: Point; /** * The coordinates of the touch point corresponding to the display point. */ touchPoint: Point; } /** * @since Chrome 57 */ export interface TouchCalibrationPairQuad { /** * First pair of touch and display point required for touch calibration. */ pair1: TouchCalibrationPair; /** * Second pair of touch and display point required for touch calibration. */ pair2: TouchCalibrationPair; /** * Third pair of touch and display point required for touch calibration. */ pair3: TouchCalibrationPair; /** * Fourth pair of touch and display point required for touch calibration. */ pair4: TouchCalibrationPair; } /** * @since Chrome 52 */ export interface DisplayMode { /** * The display mode width in device independent (user visible) pixels. */ width: number; /** * The display mode height in device independent (user visible) pixels. */ height: number; /** * The display mode width in native pixels. */ widthInNativePixels: number; /** * The display mode height in native pixels. */ heightInNativePixels: number; /** * The display mode UI scale factor. * * @deprecated Use {@link displayZoomFactor} * @chrome-deprecated-since Chrome 70 */ uiScale?: number; /** * The display mode device scale factor. */ deviceScaleFactor: number; /** * The display mode refresh rate in hertz. * * @since Chrome 67 */ refreshRate: number; /** * True if the mode is the display's native mode. */ isNative: boolean; /** * True if the display mode is currently selected. */ isSelected: boolean; /** * True if this mode is interlaced, false if not provided. * * @since Chrome 74 */ isInterlaced?: boolean; } /** * Layout position, i.e. edge of parent that the display is attached to. * * @since Chrome 53 */ export type LayoutPosition = "top" | "right" | "bottom" | "left"; /** * @since Chrome 53 */ export interface DisplayLayout { /** * The unique identifier of the display. */ id: string; /** * The unique identifier of the parent display. Empty if this is the root. */ parentId: string; /** * The layout position of this display relative to the parent. This will be ignored for the root. */ position: LayoutPosition; /** * The offset of the display along the connected edge. 0 indicates that the topmost or leftmost corners are aligned. */ offset: number; } /** * @since Chrome 67 */ export interface Edid { /** * 3 character manufacturer code. See Sec. 3.4.1 page 21. Required in v1.4. */ manufacturerId: string; /** * 2 byte manufacturer-assigned code, Sec. 3.4.2 page 21. Required in v1.4. */ productId: string; /** * Year of manufacturer, Sec. 3.4.4 page 22. Required in v1.4. */ yearOfManufacture: number; } /** * An enum to tell if the display is detected and used by the system. The display is considered 'inactive', if it is not detected by the system (maybe disconnected, or considered disconnected due to sleep mode, etc). This state is used to keep existing display when the all displays are disconnected, for example. * * @since Chrome 117 */ export type ActiveState = "active" | "inactive"; export interface DisplayUnitInfo { /** * The unique identifier of the display. */ id: string; /** * The user-friendly name (e.g. "HP LCD monitor"). */ name: string; /** * NOTE: This is only available to ChromeOS Kiosk apps and Web UI. * * @since Chrome 67 */ edid?: Edid; /** * ChromeOS only. Identifier of the display that is being mirrored if mirroring is enabled, otherwise empty. This will be set for all displays (including the display being mirrored). */ mirroringSourceId: string; /** * ChromeOS only. Identifiers of the displays to which the source display is being mirrored. Empty if no displays are being mirrored. This will be set to the same value for all displays. This must not include `mirroringSourceId`. * * @since Chrome 64 */ mirroringDestinationIds: string[]; /** * True if this is the primary display. */ isPrimary: boolean; /** * True if this display is enabled. */ isEnabled: boolean; /** * Active if the display is detected and used by the system. * * @since Chrome 117 */ activeState: ActiveState; /** * True for all displays when in unified desktop mode. See documentation for {@link enableUnifiedDesktop}. * * @since Chrome 59 */ isUnified: boolean; /** * The number of pixels per inch along the x-axis. */ dpiX: number; /** * The number of pixels per inch along the y-axis. */ dpiY: number; /** * The display's clockwise rotation in degrees relative to the vertical position. Currently exposed only on ChromeOS. Will be set to 0 on other platforms. A value of -1 will be interpreted as auto-rotate when the device is in a physical tablet state. */ rotation: number; /** * The display's logical bounds. */ bounds: Bounds; /** * The display's insets within its screen's bounds. Currently exposed only on ChromeOS. Will be set to empty insets on other platforms. */ overscan: Insets; /** * The usable work area of the display within the display bounds. The work area excludes areas of the display reserved for OS, for example taskbar and launcher. */ workArea: Bounds; /** * The list of available display modes. The current mode will have isSelected=true. Only available on ChromeOS. Will be set to an empty array on other platforms. * * @since Chrome 52 */ modes: DisplayMode[]; /** * True if this display has a touch input device associated with it. * * @since Chrome 57 */ hasTouchSupport: boolean; /** * A list of zoom factor values that can be set for the display. * * @since Chrome 67 */ availableDisplayZoomFactors: number[]; /** * The ratio between the display's current and default zoom. For example, value 1 is equivalent to 100% zoom, and value 1.5 is equivalent to 150% zoom. * * @since Chrome 65 */ displayZoomFactor: number; } export interface DisplayProperties { /** * ChromeOS only. If set to true, changes the display mode to unified desktop (see {@link enableUnifiedDesktop} for details). If set to false, unified desktop mode will be disabled. This is only valid for the primary display. If provided, mirroringSourceId must not be provided and other properties will be ignored. This is has no effect if not provided. * * @since Chrome 59 */ isUnified?: boolean; /** * ChromeOS only. If set and not empty, enables mirroring for this display only. Otherwise disables mirroring for all displays. This value should indicate the id of the source display to mirror, which must not be the same as the id passed to setDisplayProperties. If set, no other property may be set. * * @deprecated Use {@link setMirrorMode}. * @chrome-deprecated-since Chrome 68 */ mirroringSourceId?: string; /** * If set to true, makes the display primary. No-op if set to false. Note: If set, the display is considered primary for all other properties (i.e. {@link isUnified} may be set and bounds origin may not). */ isPrimary?: boolean; /** * If set, sets the display's overscan insets to the provided values. Note that overscan values may not be negative or larger than a half of the screen's size. Overscan cannot be changed on the internal monitor. */ overscan?: Insets; /** * If set, updates the display's rotation. Legal values are \[0, 90, 180, 270\]. The rotation is set clockwise, relative to the display's vertical position. */ rotation?: number; /** * If set, updates the display's logical bounds origin along the x-axis. Applied together with {@link boundsOriginY}. Defaults to the current value if not set and {@link boundsOriginY} is set. Note that when updating the display origin, some constraints will be applied, so the final bounds origin may be different than the one set. The final bounds can be retrieved using {@link getInfo}. The bounds origin cannot be changed on the primary display. */ boundsOriginX?: number; /** * If set, updates the display's logical bounds origin along the y-axis. See documentation for {@link boundsOriginX} parameter. */ boundsOriginY?: number; /** * If set, updates the display mode to the mode matching this value. If other parameters are invalid, this will not be applied. If the display mode is invalid, it will not be applied and an error will be set, but other properties will still be applied. * * @since Chrome 52 */ displayMode?: DisplayMode; /** * If set, updates the zoom associated with the display. This zoom performs re-layout and repaint thus resulting in a better quality zoom than just performing a pixel by pixel stretch enlargement. * * @since Chrome 65 */ displayZoomFactor?: number; } /** * @since Chrome 59 */ export interface GetInfoFlags { /** * If set to true, only a single {@link DisplayUnitInfo} will be returned by {@link getInfo} when in unified desktop mode (see {@link enableUnifiedDesktop}). Defaults to false. */ singleUnified?: boolean; } /** * Mirror mode, i.e. different ways of how a display is mirrored to other displays. * * @chrome-enum "off" Specifies the default mode (extended or unified desktop). * @chrome-enum "normal" Specifies that the default source display will be mirrored to all other displays. * @chrome-enum "mixed" Specifies that the specified source display will be mirrored to the provided destination displays. All other connected displays will be extended. * @since Chrome 65 */ export type MirrorMode = "off" | "normal" | "mixed"; /** * @since Chrome 65 */ export interface MirrorModeInfo { /** * The mirror mode that should be set. */ mode: MirrorMode; /** * The id of the mirroring source display. This is only valid for 'mixed'. */ mirroringSourceId?: string; /** * The ids of the mirroring destination displays. This is only valid for 'mixed'. */ mirroringDestinationIds?: string[]; } /** * Fired when anything changes to the display configuration. */ export const onDisplayChanged: events.Event<() => void>; /** * Requests the information for all attached display devices. * * @chrome-returns-extra since Chrome 91 * @param flags Options affecting how the information is returned. * @returns Promise that resolves with the results. */ export function getInfo( /** * @since Chrome 59 */ flags?: GetInfoFlags, ): Promise; /** * Requests the information for all attached display devices. * * @param flags Options affecting how the information is returned. */ export function getInfo( /** * @since Chrome 59 */ flags?: GetInfoFlags, callback?: ( displayInfo: DisplayUnitInfo[], ) => void, ): void; /** * Requests the layout info for all displays. NOTE: This is only available to ChromeOS Kiosk apps and Web UI. * * @chrome-returns-extra since Chrome 91 * @returns Promise that resolves with the results. * @since Chrome 53 */ export function getDisplayLayout(): Promise; /** * Requests the layout info for all displays. NOTE: This is only available to ChromeOS Kiosk apps and Web UI. * * @since Chrome 53 */ export function getDisplayLayout( callback?: ( layouts: DisplayLayout[], ) => void, ): void; /** * Updates the properties for the display specified by `id`, according to the information provided in `info`. On failure, {@link runtime.lastError} will be set. NOTE: This is only available to ChromeOS Kiosk apps and Web UI. * * @chrome-returns-extra since Chrome 91 * @param id The display's unique identifier. * @param info The information about display properties that should be changed. A property will be changed only if a new value for it is specified in `info`. * @returns Promise that resolves when the function finishes. */ export function setDisplayProperties( id: string, info: DisplayProperties, ): Promise; /** * Updates the properties for the display specified by `id`, according to the information provided in `info`. On failure, {@link runtime.lastError} will be set. NOTE: This is only available to ChromeOS Kiosk apps and Web UI. * * @param id The display's unique identifier. * @param info The information about display properties that should be changed. A property will be changed only if a new value for it is specified in `info`. */ export function setDisplayProperties( id: string, info: DisplayProperties, callback?: () => void, ): void; /** * Set the layout for all displays. Any display not included will use the default layout. If a layout would overlap or be otherwise invalid it will be adjusted to a valid layout. After layout is resolved, an onDisplayChanged event will be triggered. NOTE: This is only available to ChromeOS Kiosk apps and Web UI. * * @chrome-returns-extra since Chrome 91 * @param layouts The layout information, required for all displays except the primary display. * @returns Promise that resolves when the function finishes. * @since Chrome 53 */ export function setDisplayLayout( layouts: DisplayLayout[], ): Promise; /** * Set the layout for all displays. Any display not included will use the default layout. If a layout would overlap or be otherwise invalid it will be adjusted to a valid layout. After layout is resolved, an onDisplayChanged event will be triggered. NOTE: This is only available to ChromeOS Kiosk apps and Web UI. * * @param layouts The layout information, required for all displays except the primary display. * @since Chrome 53 */ export function setDisplayLayout( layouts: DisplayLayout[], callback?: () => void, ): void; /** * Enables/disables the unified desktop feature. If enabled while mirroring is active, the desktop mode will not change until mirroring is turned off. Otherwise, the desktop mode will switch to unified immediately. NOTE: This is only available to ChromeOS Kiosk apps and Web UI. * * @param enabled True if unified desktop should be enabled. * @since Chrome 46 */ export function enableUnifiedDesktop( enabled: boolean, ): void; /** * Starts overscan calibration for a display. This will show an overlay on the screen indicating the current overscan insets. If overscan calibration for display `id` is in progress this will reset calibration. * * @param id The display's unique identifier. * @since Chrome 53 */ export function overscanCalibrationStart( id: string, ): void; /** * Adjusts the current overscan insets for a display. Typically this should either move the display along an axis (e.g. left+right have the same value) or scale it along an axis (e.g. top+bottom have opposite values). Each Adjust call is cumulative with previous calls since Start. * * @param id The display's unique identifier. * @param delta The amount to change the overscan insets. * @since Chrome 53 */ export function overscanCalibrationAdjust( id: string, delta: Insets, ): void; /** * Resets the overscan insets for a display to the last saved value (i.e before Start was called). * * @param id The display's unique identifier. * @since Chrome 53 */ export function overscanCalibrationReset( id: string, ): void; /** * Complete overscan adjustments for a display by saving the current values and hiding the overlay. * * @param id The display's unique identifier. * @since Chrome 53 */ export function overscanCalibrationComplete( id: string, ): void; /** * Displays the native touch calibration UX for the display with `id` as display id. This will show an overlay on the screen with required instructions on how to proceed. The callback will be invoked in case of successful calibration only. If the calibration fails, this will throw an error. * * @chrome-returns-extra since Chrome 91 * @param id The display's unique identifier. * @returns Promise that resolves to inform the caller that the touch calibration has ended. The boolean value informs if the calibration was a success or not. * @since Chrome 57 */ export function showNativeTouchCalibration( id: string, ): Promise; /** * Displays the native touch calibration UX for the display with `id` as display id. This will show an overlay on the screen with required instructions on how to proceed. The callback will be invoked in case of successful calibration only. If the calibration fails, this will throw an error. * * @param id The display's unique identifier. * @since Chrome 57 */ export function showNativeTouchCalibration( id: string, callback?: ( success: boolean, ) => void, ): void; /** * Starts custom touch calibration for a display. This should be called when using a custom UX for collecting calibration data. If another touch calibration is already in progress this will throw an error. * * @param id The display's unique identifier. * @since Chrome 57 */ export function startCustomTouchCalibration( id: string, ): void; /** * Sets the touch calibration pairs for a display. These `pairs` would be used to calibrate the touch screen for display with `id` called in startCustomTouchCalibration(). Always call `startCustomTouchCalibration` before calling this method. If another touch calibration is already in progress this will throw an error. * * @param pairs The pairs of point used to calibrate the display. * @param bounds Bounds of the display when the touch calibration was performed. `bounds.left` and `bounds.top` values are ignored. * @since Chrome 57 */ export function completeCustomTouchCalibration( pairs: TouchCalibrationPairQuad, bounds: Bounds, ): void; /** * Resets the touch calibration for the display and brings it back to its default state by clearing any touch calibration data associated with the display. * * @param id The display's unique identifier. * @since Chrome 57 */ export function clearTouchCalibration( id: string, ): void; /** * Sets the display mode to the specified mirror mode. Each call resets the state from previous calls. Calling setDisplayProperties() will fail for the mirroring destination displays. NOTE: This is only available to ChromeOS Kiosk apps and Web UI. * * @chrome-returns-extra since Chrome 91 * @param info The information of the mirror mode that should be applied to the display mode. * @returns Promise that resolves when the function finishes. * @since Chrome 65 */ export function setMirrorMode( info: MirrorModeInfo, ): Promise; /** * Sets the display mode to the specified mirror mode. Each call resets the state from previous calls. Calling setDisplayProperties() will fail for the mirroring destination displays. NOTE: This is only available to ChromeOS Kiosk apps and Web UI. * * @param info The information of the mirror mode that should be applied to the display mode. * @since Chrome 65 */ export function setMirrorMode( info: MirrorModeInfo, callback?: () => void, ): void; } /** * The `chrome.system.memory` API. * * @chrome-permission system.memory */ export namespace system.memory { export interface MemoryInfo { /** * The total amount of physical memory capacity, in bytes. */ capacity: number; /** * The amount of available capacity, in bytes. */ availableCapacity: number; } /** * Get physical memory information. * * @chrome-returns-extra since Chrome 91 */ export function getInfo(): Promise; /** * Get physical memory information. */ export function getInfo( callback?: ( info: MemoryInfo, ) => void, ): void; } /** * Use the `chrome.system.network` API. * * @chrome-permission system.network * @chrome-platform-apps */ export namespace system.network { export interface NetworkInterface { /** * The underlying name of the adapter. On \*nix, this will typically be "eth0", "wlan0", etc. */ name: string; /** * The available IPv4/6 address. */ address: string; /** * The prefix length */ prefixLength: number; } /** * Retrieves information about local adapters on this system. * * @chrome-returns-extra since Chrome 91 */ export function getNetworkInterfaces(): Promise; /** * Retrieves information about local adapters on this system. */ export function getNetworkInterfaces( /** * @param networkInterfaces Array of object containing network interfaces information. */ callback?: ( networkInterfaces: NetworkInterface[], ) => void, ): void; } /** * Use the `chrome.system.storage` API to query storage device information and be notified when a removable storage device is attached and detached. * * @chrome-permission system.storage * @chrome-platform chromeos * @chrome-platform linux * @chrome-platform mac * @chrome-platform win */ export namespace system.storage { /** * @chrome-enum "fixed" The storage has fixed media, e.g. hard disk or SSD. * @chrome-enum "removable" The storage is removable, e.g. USB flash drive. * @chrome-enum "unknown" The storage type is unknown. */ export type StorageUnitType = "fixed" | "removable" | "unknown"; export interface StorageUnitInfo { /** * The transient ID that uniquely identifies the storage device. This ID will be persistent within the same run of a single application. It will not be a persistent identifier between different runs of an application, or between different applications. */ id: string; /** * The name of the storage unit. */ name: string; /** * The media type of the storage unit. */ type: StorageUnitType; /** * The total amount of the storage space, in bytes. */ capacity: number; } export interface StorageAvailableCapacityInfo { /** * A copied `id` of getAvailableCapacity function parameter `id`. */ id: string; /** * The available capacity of the storage device, in bytes. */ availableCapacity: number; } /** * @chrome-enum "success" The ejection command is successful -- the application can prompt the user to remove the device. * @chrome-enum "in\_use" The device is in use by another application. The ejection did not succeed; the user should not remove the device until the other application is done with the device. * @chrome-enum "no\_such\_device" There is no such device known. * @chrome-enum "failure" The ejection command failed. */ export type EjectDeviceResultCode = "success" | "in_use" | "no_such_device" | "failure"; /** * Fired when a new removable storage is attached to the system. */ export const onAttached: events.Event<( info: StorageUnitInfo, ) => void>; /** * Fired when a removable storage is detached from the system. */ export const onDetached: events.Event<( id: string, ) => void>; /** * Get the storage information from the system. The argument passed to the callback is an array of StorageUnitInfo objects. * * @chrome-returns-extra since Chrome 91 */ export function getInfo(): Promise; /** * Get the storage information from the system. The argument passed to the callback is an array of StorageUnitInfo objects. */ export function getInfo( callback?: ( info: StorageUnitInfo[], ) => void, ): void; /** * Ejects a removable storage device. * * @chrome-returns-extra since Chrome 91 */ export function ejectDevice( id: string, ): Promise; /** * Ejects a removable storage device. */ export function ejectDevice( id: string, callback?: ( result: EjectDeviceResultCode, ) => void, ): void; /** * Get the available capacity of a specified `id` storage device. The `id` is the transient device ID from StorageUnitInfo. * * @alpha * @chrome-channel dev */ export function getAvailableCapacity( id: string, ): Promise; /** * Get the available capacity of a specified `id` storage device. The `id` is the transient device ID from StorageUnitInfo. * * @alpha * @chrome-channel dev */ export function getAvailableCapacity( id: string, callback?: ( info: StorageAvailableCapacityInfo, ) => void, ): void; } /** * Use the `chrome.systemLog` API to record Chrome system logs from extensions. * * @since Chrome 125 * @chrome-permission systemLog * @chrome-install-location policy * @chrome-platform chromeos */ export namespace systemLog { export interface MessageOptions { message: string; } /** * Adds a new log record. * * @param options The logging options. * @returns Returns a Promise which resolves once the log has been added. */ export function add( options: MessageOptions, ): Promise; /** * Adds a new log record. * * @param options The logging options. */ export function add( options: MessageOptions, callback?: () => void, ): void; } /** * Use the `chrome.tabCapture` API to interact with tab media streams. * * @chrome-permission tabCapture */ export namespace tabCapture { export type TabCaptureState = "pending" | "active" | "stopped" | "error"; export interface CaptureInfo { /** * The id of the tab whose status changed. */ tabId: number; /** * The new capture status of the tab. */ status: TabCaptureState; /** * Whether an element in the tab being captured is in fullscreen mode. */ fullscreen: boolean; } export interface MediaStreamConstraint { mandatory: {[name: string]: any}; optional?: {[name: string]: any}; } export interface CaptureOptions { audio?: boolean; video?: boolean; audioConstraints?: MediaStreamConstraint; videoConstraints?: MediaStreamConstraint; } /** * @since Chrome 71 */ export interface GetMediaStreamOptions { /** * Optional tab id of the tab which will later invoke `getUserMedia()` to consume the stream. If not specified then the resulting stream can be used only by the calling extension. The stream can only be used by frames in the given tab whose security origin matches the consumber tab's origin. The tab's origin must be a secure origin, e.g. HTTPS. */ consumerTabId?: number; /** * Optional tab id of the tab which will be captured. If not specified then the current active tab will be selected. Only tabs for which the extension has been granted the `activeTab` permission can be used as the target tab. */ targetTabId?: number; } /** * Event fired when the capture status of a tab changes. This allows extension authors to keep track of the capture status of tabs to keep UI elements like page actions in sync. */ export const onStatusChanged: events.Event<( info: CaptureInfo, ) => void>; /** * Captures the visible area of the currently active tab. Capture can only be started on the currently active tab after the extension has been _invoked_, similar to the way that [activeTab](https://developer.chrome.com/docs/extensions/activeTab#invoking-activeTab) works. Capture is maintained across page navigations within the tab, and stops when the tab is closed, or the media stream is closed by the extension. * * @param options Configures the returned media stream. * @param callback Callback with either the tab capture MediaStream or `null`. `null` indicates an error has occurred and the client may query {@link runtime.lastError} to access the error details. * @chrome-disallow-service-workers */ export function capture( options: CaptureOptions, callback: ( stream: LocalMediaStream, ) => void, ): void; /** * Returns a list of tabs that have requested capture or are being captured, i.e. status != stopped and status != error. This allows extensions to inform the user that there is an existing tab capture that would prevent a new tab capture from succeeding (or to prevent redundant requests for the same tab). * * @chrome-returns-extra since Chrome 116 * @returns Returns a Promise which resolves with CaptureInfo\[\] for captured tabs. */ export function getCapturedTabs(): Promise; /** * Returns a list of tabs that have requested capture or are being captured, i.e. status != stopped and status != error. This allows extensions to inform the user that there is an existing tab capture that would prevent a new tab capture from succeeding (or to prevent redundant requests for the same tab). */ export function getCapturedTabs( callback?: ( result: CaptureInfo[], ) => void, ): void; /** * Creates a stream ID to capture the target tab. Similar to chrome.tabCapture.capture() method, but returns a media stream ID, instead of a media stream, to the consumer tab. * * @chrome-returns-extra since Chrome 116 * @returns Returns a Promise which resolves with the result. If successful, the result is an opaque string that can be passed to the `getUserMedia()` API to generate a media stream that corresponds to the target tab. The created `streamId` can only be used once and expires after a few seconds if it is not used. * @since Chrome 71 */ export function getMediaStreamId( options?: GetMediaStreamOptions, ): Promise; /** * Creates a stream ID to capture the target tab. Similar to chrome.tabCapture.capture() method, but returns a media stream ID, instead of a media stream, to the consumer tab. * * @since Chrome 71 */ export function getMediaStreamId( options?: GetMediaStreamOptions, callback?: ( streamId: string, ) => void, ): void; } /** * Use the `chrome.tabGroups` API to interact with the browser's tab grouping system. You can use this API to modify and rearrange tab groups in the browser. To group and ungroup tabs, or to query what tabs are in groups, use the `chrome.tabs` API. * * @since Chrome 89 * @chrome-permission tabGroups * @chrome-min-manifest MV3 */ export namespace tabGroups { /** * The group's color. */ export type Color = "grey" | "blue" | "red" | "yellow" | "green" | "pink" | "purple" | "cyan" | "orange"; export interface TabGroup { /** * The ID of the group. Group IDs are unique within a browser session. */ id: number; /** * Whether the group is collapsed. A collapsed group is one whose tabs are hidden. */ collapsed: boolean; /** * The group's color. */ color: Color; /** * The title of the group. */ title?: string; /** * The ID of the window that contains the group. */ windowId: number; /** * Whether the group is shared. * * @since Chrome 137 */ shared: boolean; } /** * An ID that represents the absence of a group. */ export const TAB_GROUP_ID_NONE: -1; /** * Fired when a group is created. */ export const onCreated: events.Event<( group: TabGroup, ) => void>; /** * Fired when a group is updated. */ export const onUpdated: events.Event<( group: TabGroup, ) => void>; /** * Fired when a group is moved within a window. Move events are still fired for the individual tabs within the group, as well as for the group itself. This event is not fired when a group is moved between windows; instead, it will be removed from one window and created in another. */ export const onMoved: events.Event<( group: TabGroup, ) => void>; /** * Fired when a group is closed, either directly by the user or automatically because it contained zero tabs. */ export const onRemoved: events.Event<( group: TabGroup, ) => void>; /** * Retrieves details about the specified group. * * @chrome-returns-extra since Chrome 90 */ export function get( groupId: number, ): Promise; /** * Retrieves details about the specified group. */ export function get( groupId: number, callback?: ( group: TabGroup, ) => void, ): void; /** * Gets all groups that have the specified properties, or all groups if no properties are specified. * * @chrome-returns-extra since Chrome 90 */ export function query( queryInfo: { /** * Whether the groups are collapsed. */ collapsed?: boolean, /** * The color of the groups. */ color?: Color, /** * Match group titles against a pattern. */ title?: string, /** * Whether the group is shared. * * @since Chrome 137 */ shared?: boolean, /** * The ID of the parent window, or {@link windows.WINDOW_ID_CURRENT} for the [current window](https://developer.chrome.com/docs/extensions/reference/windows/#current-window). */ windowId?: number, }, ): Promise; /** * Gets all groups that have the specified properties, or all groups if no properties are specified. */ export function query( queryInfo: { /** * Whether the groups are collapsed. */ collapsed?: boolean, /** * The color of the groups. */ color?: Color, /** * Match group titles against a pattern. */ title?: string, /** * Whether the group is shared. * * @since Chrome 137 */ shared?: boolean, /** * The ID of the parent window, or {@link windows.WINDOW_ID_CURRENT} for the [current window](https://developer.chrome.com/docs/extensions/reference/windows/#current-window). */ windowId?: number, }, callback?: ( result: TabGroup[], ) => void, ): void; /** * Modifies the properties of a group. Properties that are not specified in `updateProperties` are not modified. * * @chrome-returns-extra since Chrome 90 * @param groupId The ID of the group to modify. */ export function update( groupId: number, updateProperties: { /** * Whether the group should be collapsed. */ collapsed?: boolean, /** * The color of the group. */ color?: Color, /** * The title of the group. */ title?: string, }, ): Promise; /** * Modifies the properties of a group. Properties that are not specified in `updateProperties` are not modified. * * @param groupId The ID of the group to modify. */ export function update( groupId: number, updateProperties: { /** * Whether the group should be collapsed. */ collapsed?: boolean, /** * The color of the group. */ color?: Color, /** * The title of the group. */ title?: string, }, /** * @param group Details about the updated group. */ callback?: ( group?: TabGroup, ) => void, ): void; /** * Moves the group and all its tabs within its window, or to a new window. * * @chrome-returns-extra since Chrome 90 * @param groupId The ID of the group to move. */ export function move( groupId: number, moveProperties: { /** * The window to move the group to. Defaults to the window the group is currently in. Note that groups can only be moved to and from windows with {@link windows.WindowType} type `"normal"`. */ windowId?: number, /** * The position to move the group to. Use `-1` to place the group at the end of the window. */ index: number, }, ): Promise; /** * Moves the group and all its tabs within its window, or to a new window. * * @param groupId The ID of the group to move. */ export function move( groupId: number, moveProperties: { /** * The window to move the group to. Defaults to the window the group is currently in. Note that groups can only be moved to and from windows with {@link windows.WindowType} type `"normal"`. */ windowId?: number, /** * The position to move the group to. Use `-1` to place the group at the end of the window. */ index: number, }, /** * @param group Details about the moved group. */ callback?: ( group?: TabGroup, ) => void, ): void; } /** * Use the `chrome.tabs` API to interact with the browser's tab system. You can use this API to create, modify, and rearrange tabs in the browser. */ export namespace tabs { /** * The tab's loading status. * * @since Chrome 44 */ export type TabStatus = "unloaded" | "loading" | "complete"; /** * An event that caused a muted state change. * * @chrome-enum "user" A user input action set the muted state. * @chrome-enum "capture" Tab capture was started, forcing a muted state change. * @chrome-enum "extension" An extension, identified by the extensionId field, set the muted state. * @since Chrome 46 */ export type MutedInfoReason = "user" | "capture" | "extension"; /** * The tab's muted state and the reason for the last state change. * * @since Chrome 46 */ export interface MutedInfo { /** * Whether the tab is muted (prevented from playing sound). The tab may be muted even if it has not played or is not currently playing sound. Equivalent to whether the 'muted' audio indicator is showing. */ muted: boolean; /** * The reason the tab was muted or unmuted. Not set if the tab's mute state has never been changed. */ reason?: MutedInfoReason; /** * The ID of the extension that changed the muted state. Not set if an extension was not the reason the muted state last changed. */ extensionId?: string; } export interface Tab { /** * The ID of the tab. Tab IDs are unique within a browser session. Under some circumstances a tab may not be assigned an ID; for example, when querying foreign tabs using the {@link sessions} API, in which case a session ID may be present. Tab ID can also be set to `chrome.tabs.TAB_ID_NONE` for apps and devtools windows. */ id?: number; /** * The zero-based index of the tab within its window. */ index: number; /** * The ID of the group that the tab belongs to. * * @since Chrome 88 */ groupId: number; /** * The ID of the Split View that the tab belongs to. * * @since Pending */ splitViewId?: number; /** * The ID of the window that contains the tab. */ windowId: number; /** * The ID of the tab that opened this tab, if any. This property is only present if the opener tab still exists. */ openerTabId?: number; /** * Whether the tab is selected. * * @deprecated Please use {@link tabs.Tab.highlighted}. */ selected: boolean; /** * The last time the tab became active in its window as the number of milliseconds since epoch. * * @since Chrome 121 */ lastAccessed: number; /** * Whether the tab is highlighted. */ highlighted: boolean; /** * Whether the tab is active in its window. Does not necessarily mean the window is focused. */ active: boolean; /** * Whether the tab is pinned. */ pinned: boolean; /** * Whether the tab has produced sound over the past couple of seconds (but it might not be heard if also muted). Equivalent to whether the 'speaker audio' indicator is showing. * * @since Chrome 45 */ audible?: boolean; /** * Whether the tab is frozen. A frozen tab cannot execute tasks, including event handlers or timers. It is visible in the tab strip and its content is loaded in memory. It is unfrozen on activation. * * @since Chrome 132 */ frozen: boolean; /** * Whether the tab is discarded. A discarded tab is one whose content has been unloaded from memory, but is still visible in the tab strip. Its content is reloaded the next time it is activated. * * @since Chrome 54 */ discarded: boolean; /** * Whether the tab can be discarded automatically by the browser when resources are low. * * @since Chrome 54 */ autoDiscardable: boolean; /** * The tab's muted state and the reason for the last state change. * * @since Chrome 46 */ mutedInfo?: MutedInfo; /** * The last committed URL of the main frame of the tab. This property is only present if the extension has the `"tabs"` permission or has host permissions for the page. May be an empty string if the tab has not yet committed. See also {@link Tab.pendingUrl}. */ url?: string; /** * The URL the tab is navigating to, before it has committed. This property is only present if the extension has the `"tabs"` permission or has host permissions for the page and there is a pending navigation. * * @since Chrome 79 */ pendingUrl?: string; /** * The title of the tab. This property is only present if the extension has the `"tabs"` permission or has host permissions for the page. */ title?: string; /** * The URL of the tab's favicon. This property is only present if the extension has the `"tabs"` permission or has host permissions for the page. It may also be an empty string if the tab is loading. */ favIconUrl?: string; /** * The tab's loading status. */ status?: TabStatus; /** * Whether the tab is in an incognito window. */ incognito: boolean; /** * The width of the tab in pixels. */ width?: number; /** * The height of the tab in pixels. */ height?: number; /** * The session ID used to uniquely identify a tab obtained from the {@link sessions} API. */ sessionId?: string; } /** * Defines how zoom changes are handled, i.e., which entity is responsible for the actual scaling of the page; defaults to `automatic`. * * @chrome-enum "automatic" Zoom changes are handled automatically by the browser. * @chrome-enum "manual" Overrides the automatic handling of zoom changes. The `onZoomChange` event will still be dispatched, and it is the extension's responsibility to listen for this event and manually scale the page. This mode does not support `per-origin` zooming, and thus ignores the `scope` zoom setting and assumes `per-tab`. * @chrome-enum "disabled" Disables all zooming in the tab. The tab reverts to the default zoom level, and all attempted zoom changes are ignored. * @since Chrome 44 */ export type ZoomSettingsMode = "automatic" | "manual" | "disabled"; /** * Defines whether zoom changes persist for the page's origin, or only take effect in this tab; defaults to `per-origin` when in `automatic` mode, and `per-tab` otherwise. * * @chrome-enum "per-origin" Zoom changes persist in the zoomed page's origin, i.e., all other tabs navigated to that same origin are zoomed as well. Moreover, `per-origin` zoom changes are saved with the origin, meaning that when navigating to other pages in the same origin, they are all zoomed to the same zoom factor. The `per-origin` scope is only available in the `automatic` mode. * @chrome-enum "per-tab" Zoom changes only take effect in this tab, and zoom changes in other tabs do not affect the zooming of this tab. Also, `per-tab` zoom changes are reset on navigation; navigating a tab always loads pages with their `per-origin` zoom factors. * @since Chrome 44 */ export type ZoomSettingsScope = "per-origin" | "per-tab"; /** * Defines how zoom changes in a tab are handled and at what scope. */ export interface ZoomSettings { /** * Defines how zoom changes are handled, i.e., which entity is responsible for the actual scaling of the page; defaults to `automatic`. */ mode?: ZoomSettingsMode; /** * Defines whether zoom changes persist for the page's origin, or only take effect in this tab; defaults to `per-origin` when in `automatic` mode, and `per-tab` otherwise. */ scope?: ZoomSettingsScope; /** * Used to return the default zoom level for the current tab in calls to tabs.getZoomSettings. * * @since Chrome 43 */ defaultZoomFactor?: number; } /** * The type of window. * * @since Chrome 44 */ export type WindowType = "normal" | "popup" | "panel" | "app" | "devtools"; /** * The maximum number of times that {@link captureVisibleTab} can be called per second. {@link captureVisibleTab} is expensive and should not be called too often. * * @since Chrome 92 */ export const MAX_CAPTURE_VISIBLE_TAB_CALLS_PER_SECOND: 2; /** * An ID that represents the absence of a split tab. * * @since Pending */ export const SPLIT_VIEW_ID_NONE: -1; /** * An ID that represents the absence of a browser tab. * * @since Chrome 46 */ export const TAB_ID_NONE: -1; /** * An index that represents the absence of a tab index in a tab\_strip. * * @since Chrome 123 */ export const TAB_INDEX_NONE: -1; /** * Fired when a tab is created. Note that the tab's URL and tab group membership may not be set at the time this event is fired, but you can listen to onUpdated events so as to be notified when a URL is set or the tab is added to a tab group. */ export const onCreated: events.Event<( tab: Tab, ) => void>; /** * Fired when a tab is updated. */ export const onUpdated: events.Event<( tabId: number, changeInfo: { /** * The tab's loading status. */ status?: TabStatus, /** * The tab's URL if it has changed. */ url?: string, /** * The tab's new group. * * @since Chrome 88 */ groupId?: number, /** * The tab's new Split View. * * @since Chrome 140 */ splitViewId?: number, /** * The tab's new pinned state. */ pinned?: boolean, /** * The tab's new audible state. * * @since Chrome 45 */ audible?: boolean, /** * The tab's new frozen state. * * @since Chrome 132 */ frozen?: boolean, /** * The tab's new discarded state. * * @since Chrome 54 */ discarded?: boolean, /** * The tab's new auto-discardable state. * * @since Chrome 54 */ autoDiscardable?: boolean, /** * The tab's new muted state and the reason for the change. * * @since Chrome 46 */ mutedInfo?: MutedInfo, /** * The tab's new favicon URL. */ favIconUrl?: string, /** * The tab's new title. * * @since Chrome 48 */ title?: string, }, tab: Tab, ) => void>; /** * Fired when a tab is moved within a window. Only one move event is fired, representing the tab the user directly moved. Move events are not fired for the other tabs that must move in response to the manually-moved tab. This event is not fired when a tab is moved between windows; for details, see {@link tabs.onDetached}. */ export const onMoved: events.Event<( tabId: number, moveInfo: { windowId: number, fromIndex: number, toIndex: number, }, ) => void>; /** * Fires when the selected tab in a window changes. * * @deprecated Please use {@link tabs.onActivated}. * @chrome-max-manifest MV2 */ export const onSelectionChanged: events.Event<( tabId: number, selectInfo: { /** * The ID of the window the selected tab changed inside of. */ windowId: number, }, ) => void>; /** * Fires when the selected tab in a window changes. Note that the tab's URL may not be set at the time this event fired, but you can listen to {@link tabs.onUpdated} events so as to be notified when a URL is set. * * @deprecated Please use {@link tabs.onActivated}. * @chrome-max-manifest MV2 */ export const onActiveChanged: events.Event<( tabId: number, selectInfo: { /** * The ID of the window the selected tab changed inside of. */ windowId: number, }, ) => void>; /** * Fires when the active tab in a window changes. Note that the tab's URL may not be set at the time this event fired, but you can listen to onUpdated events so as to be notified when a URL is set. */ export const onActivated: events.Event<( activeInfo: { /** * The ID of the tab that has become active. */ tabId: number, /** * The ID of the window the active tab changed inside of. */ windowId: number, }, ) => void>; /** * Fired when the highlighted or selected tabs in a window changes. * * @deprecated Please use {@link tabs.onHighlighted}. * @chrome-max-manifest MV2 */ export const onHighlightChanged: events.Event<( selectInfo: { /** * The window whose tabs changed. */ windowId: number, /** * All highlighted tabs in the window. */ tabIds: number[], }, ) => void>; /** * Fired when the highlighted or selected tabs in a window changes. */ export const onHighlighted: events.Event<( highlightInfo: { /** * The window whose tabs changed. */ windowId: number, /** * All highlighted tabs in the window. */ tabIds: number[], }, ) => void>; /** * Fired when a tab is detached from a window; for example, because it was moved between windows. */ export const onDetached: events.Event<( tabId: number, detachInfo: { oldWindowId: number, oldPosition: number, }, ) => void>; /** * Fired when a tab is attached to a window; for example, because it was moved between windows. */ export const onAttached: events.Event<( tabId: number, attachInfo: { newWindowId: number, newPosition: number, }, ) => void>; /** * Fired when a tab is closed. */ export const onRemoved: events.Event<( tabId: number, removeInfo: { /** * The window whose tab is closed. */ windowId: number, /** * True when the tab was closed because its parent window was closed. */ isWindowClosing: boolean, }, ) => void>; /** * Fired when a tab is replaced with another tab due to prerendering or instant. */ export const onReplaced: events.Event<( addedTabId: number, removedTabId: number, ) => void>; /** * Fired when a tab is zoomed. */ export const onZoomChange: events.Event<( ZoomChangeInfo: { tabId: number, oldZoomFactor: number, newZoomFactor: number, zoomSettings: ZoomSettings, }, ) => void>; /** * Retrieves details about the specified tab. * * @chrome-returns-extra since Chrome 88 */ export function get( tabId: number, ): Promise; /** * Retrieves details about the specified tab. */ export function get( tabId: number, callback?: ( tab: Tab, ) => void, ): void; /** * Gets the tab that this script call is being made from. Returns `undefined` if called from a non-tab context (for example, a background page or popup view). * * @chrome-returns-extra since Chrome 88 */ export function getCurrent(): Promise; /** * Gets the tab that this script call is being made from. Returns `undefined` if called from a non-tab context (for example, a background page or popup view). */ export function getCurrent( callback?: ( tab?: Tab, ) => void, ): void; /** * Connects to the content script(s) in the specified tab. The {@link runtime.onConnect} event is fired in each content script running in the specified tab for the current extension. For more details, see [Content Script Messaging](https://developer.chrome.com/docs/extensions/messaging). * * @returns A port that can be used to communicate with the content scripts running in the specified tab. The port's {@link runtime.Port} event is fired if the tab closes or does not exist. */ export function connect( tabId: number, connectInfo?: { /** * Is passed into onConnect for content scripts that are listening for the connection event. */ name?: string, /** * Open a port to a specific [frame](https://developer.chrome.com/docs/extensions/reference/webNavigation/#frame_ids) identified by `frameId` instead of all frames in the tab. */ frameId?: number, /** * Open a port to a specific [document](https://developer.chrome.com/docs/extensions/reference/webNavigation/#document_ids) identified by `documentId` instead of all frames in the tab. * * @since Chrome 106 */ documentId?: string, }, ): runtime.Port; /** * Sends a single request to the content script(s) in the specified tab, with an optional callback to run when a response is sent back. The {@link extension.onRequest} event is fired in each content script running in the specified tab for the current extension. * * @chrome-returns-extra since Chrome 99 * @deprecated Please use {@link runtime.sendMessage}. * @chrome-max-manifest MV2 */ export function sendRequest( tabId: number, request: any, ): Promise; /** * Sends a single request to the content script(s) in the specified tab, with an optional callback to run when a response is sent back. The {@link extension.onRequest} event is fired in each content script running in the specified tab for the current extension. * * @deprecated Please use {@link runtime.sendMessage}. * @chrome-max-manifest MV2 */ export function sendRequest( tabId: number, request: any, /** * @param response The JSON response object sent by the handler of the request. If an error occurs while connecting to the specified tab, the promise will be rejected. * @since Chrome 99 */ callback?: ( response: any, ) => void, ): void; /** * Sends a single message to the content script(s) in the specified tab, with an optional callback to run when a response is sent back. The {@link runtime.onMessage} event is fired in each content script running in the specified tab for the current extension. * * @chrome-returns-extra since Chrome 99 * @param message The message to send. This message should be a JSON-ifiable object. */ export function sendMessage( tabId: number, message: any, options?: { /** * Send a message to a specific [frame](https://developer.chrome.com/docs/extensions/reference/webNavigation/#frame_ids) identified by `frameId` instead of all frames in the tab. */ frameId?: number, /** * Send a message to a specific [document](https://developer.chrome.com/docs/extensions/reference/webNavigation/#document_ids) identified by `documentId` instead of all frames in the tab. * * @since Chrome 106 */ documentId?: string, }, ): Promise; /** * Sends a single message to the content script(s) in the specified tab, with an optional callback to run when a response is sent back. The {@link runtime.onMessage} event is fired in each content script running in the specified tab for the current extension. * * @param message The message to send. This message should be a JSON-ifiable object. */ export function sendMessage( tabId: number, message: any, options?: { /** * Send a message to a specific [frame](https://developer.chrome.com/docs/extensions/reference/webNavigation/#frame_ids) identified by `frameId` instead of all frames in the tab. */ frameId?: number, /** * Send a message to a specific [document](https://developer.chrome.com/docs/extensions/reference/webNavigation/#document_ids) identified by `documentId` instead of all frames in the tab. * * @since Chrome 106 */ documentId?: string, }, /** * @param response The JSON response object sent by the handler of the message. If an error occurs while connecting to the specified tab, the promise will be rejected. * @since Chrome 99 */ callback?: ( response: any, ) => void, ): void; /** * Gets the tab that is selected in the specified window. * * @chrome-returns-extra since Chrome 88 * @param windowId Defaults to the [current window](https://developer.chrome.com/docs/extensions/reference/windows/#current-window). * @deprecated Please use {@link tabs.query} `{active: true}`. * @chrome-max-manifest MV2 */ export function getSelected( windowId?: number, ): Promise; /** * Gets the tab that is selected in the specified window. * * @param windowId Defaults to the [current window](https://developer.chrome.com/docs/extensions/reference/windows/#current-window). * @deprecated Please use {@link tabs.query} `{active: true}`. * @chrome-max-manifest MV2 */ export function getSelected( windowId?: number, callback?: ( tab: Tab, ) => void, ): void; /** * Gets details about all tabs in the specified window. * * @chrome-returns-extra since Chrome 88 * @param windowId Defaults to the [current window](https://developer.chrome.com/docs/extensions/reference/windows/#current-window). * @deprecated Please use {@link tabs.query} `{windowId: windowId}`. * @chrome-max-manifest MV2 */ export function getAllInWindow( windowId?: number, ): Promise; /** * Gets details about all tabs in the specified window. * * @param windowId Defaults to the [current window](https://developer.chrome.com/docs/extensions/reference/windows/#current-window). * @deprecated Please use {@link tabs.query} `{windowId: windowId}`. * @chrome-max-manifest MV2 */ export function getAllInWindow( windowId?: number, callback?: ( tabs: Tab[], ) => void, ): void; /** * Creates a new tab. * * @chrome-returns-extra since Chrome 88 */ export function create( createProperties: { /** * The window in which to create the new tab. Defaults to the [current window](https://developer.chrome.com/docs/extensions/reference/windows/#current-window). */ windowId?: number, /** * The position the tab should take in the window. The provided value is clamped to between zero and the number of tabs in the window. */ index?: number, /** * The URL to initially navigate the tab to. Fully-qualified URLs must include a scheme (i.e., 'http://www.google.com', not 'www.google.com'). Relative URLs are relative to the current page within the extension. Defaults to the New Tab Page. */ url?: string, /** * Whether the tab should become the active tab in the window. Does not affect whether the window is focused (see {@link windows.update}). Defaults to `true`. */ active?: boolean, /** * Whether the tab should become the selected tab in the window. Defaults to `true` * * @deprecated Please use _active_. */ selected?: boolean, /** * Whether the tab should be pinned. Defaults to `false` */ pinned?: boolean, /** * The ID of the tab that opened this tab. If specified, the opener tab must be in the same window as the newly created tab. */ openerTabId?: number, }, ): Promise; /** * Creates a new tab. */ export function create( createProperties: { /** * The window in which to create the new tab. Defaults to the [current window](https://developer.chrome.com/docs/extensions/reference/windows/#current-window). */ windowId?: number, /** * The position the tab should take in the window. The provided value is clamped to between zero and the number of tabs in the window. */ index?: number, /** * The URL to initially navigate the tab to. Fully-qualified URLs must include a scheme (i.e., 'http://www.google.com', not 'www.google.com'). Relative URLs are relative to the current page within the extension. Defaults to the New Tab Page. */ url?: string, /** * Whether the tab should become the active tab in the window. Does not affect whether the window is focused (see {@link windows.update}). Defaults to `true`. */ active?: boolean, /** * Whether the tab should become the selected tab in the window. Defaults to `true` * * @deprecated Please use _active_. */ selected?: boolean, /** * Whether the tab should be pinned. Defaults to `false` */ pinned?: boolean, /** * The ID of the tab that opened this tab. If specified, the opener tab must be in the same window as the newly created tab. */ openerTabId?: number, }, /** * @param tab The created tab. */ callback?: ( tab: Tab, ) => void, ): void; /** * Duplicates a tab. * * @chrome-returns-extra since Chrome 88 * @param tabId The ID of the tab to duplicate. */ export function duplicate( tabId: number, ): Promise; /** * Duplicates a tab. * * @param tabId The ID of the tab to duplicate. */ export function duplicate( tabId: number, /** * @param tab Details about the duplicated tab. The `url`, `pendingUrl`, `title` and `favIconUrl` properties are only included on the {@link tabs.Tab} object if the extension has the `"tabs"` permission or has host permissions for the page. */ callback?: ( tab?: Tab, ) => void, ): void; /** * Gets all tabs that have the specified properties, or all tabs if no properties are specified. * * @chrome-returns-extra since Chrome 88 */ export function query( queryInfo: { /** * Whether the tabs are active in their windows. */ active?: boolean, /** * Whether the tabs are pinned. */ pinned?: boolean, /** * Whether the tabs are audible. * * @since Chrome 45 */ audible?: boolean, /** * Whether the tabs are muted. * * @since Chrome 45 */ muted?: boolean, /** * Whether the tabs are highlighted. */ highlighted?: boolean, /** * Whether the tabs are frozen. A frozen tab cannot execute tasks, including event handlers or timers. It is visible in the tab strip and its content is loaded in memory. It is unfrozen on activation. * * @since Chrome 132 */ frozen?: boolean, /** * Whether the tabs are discarded. A discarded tab is one whose content has been unloaded from memory, but is still visible in the tab strip. Its content is reloaded the next time it is activated. * * @since Chrome 54 */ discarded?: boolean, /** * Whether the tabs can be discarded automatically by the browser when resources are low. * * @since Chrome 54 */ autoDiscardable?: boolean, /** * Whether the tabs are in the [current window](https://developer.chrome.com/docs/extensions/reference/windows/#current-window). */ currentWindow?: boolean, /** * Whether the tabs are in the last focused window. */ lastFocusedWindow?: boolean, /** * The tab loading status. */ status?: TabStatus, /** * Match page titles against a pattern. This property is ignored if the extension does not have the `"tabs"` permission or host permissions for the page. */ title?: string, /** * Match tabs against one or more [URL patterns](https://developer.chrome.com/docs/extensions/match_patterns). Fragment identifiers are not matched. This property is ignored if the extension does not have the `"tabs"` permission or host permissions for the page. */ url?: string | string[], /** * The ID of the group that the tabs are in, or {@link tabGroups.TAB_GROUP_ID_NONE} for ungrouped tabs. * * @since Chrome 88 */ groupId?: number, /** * The ID of the Split View that the tabs are in, or {@link tabs.SPLIT_VIEW_ID_NONE} for tabs that aren't in a Split View. * * @since Chrome 140 */ splitViewId?: number, /** * The ID of the parent window, or {@link windows.WINDOW_ID_CURRENT} for the [current window](https://developer.chrome.com/docs/extensions/reference/windows/#current-window). */ windowId?: number, /** * The type of window the tabs are in. */ windowType?: WindowType, /** * The position of the tabs within their windows. */ index?: number, }, ): Promise; /** * Gets all tabs that have the specified properties, or all tabs if no properties are specified. */ export function query( queryInfo: { /** * Whether the tabs are active in their windows. */ active?: boolean, /** * Whether the tabs are pinned. */ pinned?: boolean, /** * Whether the tabs are audible. * * @since Chrome 45 */ audible?: boolean, /** * Whether the tabs are muted. * * @since Chrome 45 */ muted?: boolean, /** * Whether the tabs are highlighted. */ highlighted?: boolean, /** * Whether the tabs are frozen. A frozen tab cannot execute tasks, including event handlers or timers. It is visible in the tab strip and its content is loaded in memory. It is unfrozen on activation. * * @since Chrome 132 */ frozen?: boolean, /** * Whether the tabs are discarded. A discarded tab is one whose content has been unloaded from memory, but is still visible in the tab strip. Its content is reloaded the next time it is activated. * * @since Chrome 54 */ discarded?: boolean, /** * Whether the tabs can be discarded automatically by the browser when resources are low. * * @since Chrome 54 */ autoDiscardable?: boolean, /** * Whether the tabs are in the [current window](https://developer.chrome.com/docs/extensions/reference/windows/#current-window). */ currentWindow?: boolean, /** * Whether the tabs are in the last focused window. */ lastFocusedWindow?: boolean, /** * The tab loading status. */ status?: TabStatus, /** * Match page titles against a pattern. This property is ignored if the extension does not have the `"tabs"` permission or host permissions for the page. */ title?: string, /** * Match tabs against one or more [URL patterns](https://developer.chrome.com/docs/extensions/match_patterns). Fragment identifiers are not matched. This property is ignored if the extension does not have the `"tabs"` permission or host permissions for the page. */ url?: string | string[], /** * The ID of the group that the tabs are in, or {@link tabGroups.TAB_GROUP_ID_NONE} for ungrouped tabs. * * @since Chrome 88 */ groupId?: number, /** * The ID of the Split View that the tabs are in, or {@link tabs.SPLIT_VIEW_ID_NONE} for tabs that aren't in a Split View. * * @since Chrome 140 */ splitViewId?: number, /** * The ID of the parent window, or {@link windows.WINDOW_ID_CURRENT} for the [current window](https://developer.chrome.com/docs/extensions/reference/windows/#current-window). */ windowId?: number, /** * The type of window the tabs are in. */ windowType?: WindowType, /** * The position of the tabs within their windows. */ index?: number, }, callback?: ( result: Tab[], ) => void, ): void; /** * Highlights the given tabs and focuses on the first of group. Will appear to do nothing if the specified tab is currently active. * * @chrome-returns-extra since Chrome 88 */ export function highlight( highlightInfo: { /** * The window that contains the tabs. */ windowId?: number, /** * One or more tab indices to highlight. */ tabs: number[] | number, }, ): Promise; /** * Highlights the given tabs and focuses on the first of group. Will appear to do nothing if the specified tab is currently active. */ export function highlight( highlightInfo: { /** * The window that contains the tabs. */ windowId?: number, /** * One or more tab indices to highlight. */ tabs: number[] | number, }, /** * @param window Contains details about the window whose tabs were highlighted. */ callback?: ( window: windows.Window, ) => void, ): void; /** * Modifies the properties of a tab. Properties that are not specified in `updateProperties` are not modified. * * @chrome-returns-extra since Chrome 88 * @param tabId Defaults to the selected tab of the [current window](https://developer.chrome.com/docs/extensions/reference/windows/#current-window). */ export function update( tabId: number, updateProperties: { /** * A URL to navigate the tab to. JavaScript URLs are not supported; use {@link scripting.executeScript} instead. */ url?: string, /** * Whether the tab should be active. Does not affect whether the window is focused (see {@link windows.update}). */ active?: boolean, /** * Adds or removes the tab from the current selection. */ highlighted?: boolean, /** * Whether the tab should be selected. * * @deprecated Please use _highlighted_. */ selected?: boolean, /** * Whether the tab should be pinned. */ pinned?: boolean, /** * Whether the tab should be muted. * * @since Chrome 45 */ muted?: boolean, /** * The ID of the tab that opened this tab. If specified, the opener tab must be in the same window as this tab. */ openerTabId?: number, /** * Whether the tab should be discarded automatically by the browser when resources are low. * * @since Chrome 54 */ autoDiscardable?: boolean, }, ): Promise; /** * Modifies the properties of a tab. Properties that are not specified in `updateProperties` are not modified. * * @chrome-returns-extra since Chrome 88 */ export function update( updateProperties: { /** * A URL to navigate the tab to. JavaScript URLs are not supported; use {@link scripting.executeScript} instead. */ url?: string, /** * Whether the tab should be active. Does not affect whether the window is focused (see {@link windows.update}). */ active?: boolean, /** * Adds or removes the tab from the current selection. */ highlighted?: boolean, /** * Whether the tab should be selected. * * @deprecated Please use _highlighted_. */ selected?: boolean, /** * Whether the tab should be pinned. */ pinned?: boolean, /** * Whether the tab should be muted. * * @since Chrome 45 */ muted?: boolean, /** * The ID of the tab that opened this tab. If specified, the opener tab must be in the same window as this tab. */ openerTabId?: number, /** * Whether the tab should be discarded automatically by the browser when resources are low. * * @since Chrome 54 */ autoDiscardable?: boolean, }, ): Promise; /** * Modifies the properties of a tab. Properties that are not specified in `updateProperties` are not modified. * * @param tabId Defaults to the selected tab of the [current window](https://developer.chrome.com/docs/extensions/reference/windows/#current-window). */ export function update( tabId: number, updateProperties: { /** * A URL to navigate the tab to. JavaScript URLs are not supported; use {@link scripting.executeScript} instead. */ url?: string, /** * Whether the tab should be active. Does not affect whether the window is focused (see {@link windows.update}). */ active?: boolean, /** * Adds or removes the tab from the current selection. */ highlighted?: boolean, /** * Whether the tab should be selected. * * @deprecated Please use _highlighted_. */ selected?: boolean, /** * Whether the tab should be pinned. */ pinned?: boolean, /** * Whether the tab should be muted. * * @since Chrome 45 */ muted?: boolean, /** * The ID of the tab that opened this tab. If specified, the opener tab must be in the same window as this tab. */ openerTabId?: number, /** * Whether the tab should be discarded automatically by the browser when resources are low. * * @since Chrome 54 */ autoDiscardable?: boolean, }, /** * @param tab Details about the updated tab. The `url`, `pendingUrl`, `title` and `favIconUrl` properties are only included on the {@link tabs.Tab} object if the extension has the `"tabs"` permission or has host permissions for the page. */ callback?: ( tab?: Tab, ) => void, ): void; /** * Modifies the properties of a tab. Properties that are not specified in `updateProperties` are not modified. */ export function update( updateProperties: { /** * A URL to navigate the tab to. JavaScript URLs are not supported; use {@link scripting.executeScript} instead. */ url?: string, /** * Whether the tab should be active. Does not affect whether the window is focused (see {@link windows.update}). */ active?: boolean, /** * Adds or removes the tab from the current selection. */ highlighted?: boolean, /** * Whether the tab should be selected. * * @deprecated Please use _highlighted_. */ selected?: boolean, /** * Whether the tab should be pinned. */ pinned?: boolean, /** * Whether the tab should be muted. * * @since Chrome 45 */ muted?: boolean, /** * The ID of the tab that opened this tab. If specified, the opener tab must be in the same window as this tab. */ openerTabId?: number, /** * Whether the tab should be discarded automatically by the browser when resources are low. * * @since Chrome 54 */ autoDiscardable?: boolean, }, /** * @param tab Details about the updated tab. The `url`, `pendingUrl`, `title` and `favIconUrl` properties are only included on the {@link tabs.Tab} object if the extension has the `"tabs"` permission or has host permissions for the page. */ callback?: ( tab?: Tab, ) => void, ): void; /** * Moves one or more tabs to a new position within its window, or to a new window. Note that tabs can only be moved to and from normal (window.type === "normal") windows. * * @chrome-returns-extra since Chrome 88 * @param tabIds The tab ID or list of tab IDs to move. */ export function move( tabIds: number | number[], moveProperties: { /** * Defaults to the window the tab is currently in. */ windowId?: number, /** * The position to move the window to. Use `-1` to place the tab at the end of the window. */ index: number, }, ): Promise; /** * Moves one or more tabs to a new position within its window, or to a new window. Note that tabs can only be moved to and from normal (window.type === "normal") windows. * * @param tabIds The tab ID or list of tab IDs to move. */ export function move( tabIds: number | number[], moveProperties: { /** * Defaults to the window the tab is currently in. */ windowId?: number, /** * The position to move the window to. Use `-1` to place the tab at the end of the window. */ index: number, }, /** * @param tabs Details about the moved tabs. */ callback?: ( tabs: Tab | Tab[], ) => void, ): void; /** * Reload a tab. * * @chrome-returns-extra since Chrome 88 * @param tabId The ID of the tab to reload; defaults to the selected tab of the current window. */ export function reload( tabId?: number, reloadProperties?: { /** * Whether to bypass local caching. Defaults to `false`. */ bypassCache?: boolean, }, ): Promise; /** * Reload a tab. * * @param tabId The ID of the tab to reload; defaults to the selected tab of the current window. */ export function reload( tabId?: number, reloadProperties?: { /** * Whether to bypass local caching. Defaults to `false`. */ bypassCache?: boolean, }, callback?: () => void, ): void; /** * Closes one or more tabs. * * @chrome-returns-extra since Chrome 88 * @param tabIds The tab ID or list of tab IDs to close. */ export function remove( tabIds: number | number[], ): Promise; /** * Closes one or more tabs. * * @param tabIds The tab ID or list of tab IDs to close. */ export function remove( tabIds: number | number[], callback?: () => void, ): void; /** * Adds one or more tabs to a specified group, or if no group is specified, adds the given tabs to a newly created group. * * @since Chrome 88 */ export function group( options: { /** * The tab ID or list of tab IDs to add to the specified group. */ tabIds: number | [number, ...number[]], /** * The ID of the group to add the tabs to. If not specified, a new group will be created. */ groupId?: number, /** * Configurations for creating a group. Cannot be used if groupId is already specified. */ createProperties?: { /** * The window of the new group. Defaults to the current window. */ windowId?: number, }, }, ): Promise; /** * Adds one or more tabs to a specified group, or if no group is specified, adds the given tabs to a newly created group. * * @since Chrome 88 */ export function group( options: { /** * The tab ID or list of tab IDs to add to the specified group. */ tabIds: number | [number, ...number[]], /** * The ID of the group to add the tabs to. If not specified, a new group will be created. */ groupId?: number, /** * Configurations for creating a group. Cannot be used if groupId is already specified. */ createProperties?: { /** * The window of the new group. Defaults to the current window. */ windowId?: number, }, }, /** * @param groupId The ID of the group that the tabs were added to. */ callback?: ( groupId: number, ) => void, ): void; /** * Removes one or more tabs from their respective groups. If any groups become empty, they are deleted. * * @param tabIds The tab ID or list of tab IDs to remove from their respective groups. * @since Chrome 88 */ export function ungroup( tabIds: number | [number, ...number[]], ): Promise; /** * Removes one or more tabs from their respective groups. If any groups become empty, they are deleted. * * @param tabIds The tab ID or list of tab IDs to remove from their respective groups. * @since Chrome 88 */ export function ungroup( tabIds: number | [number, ...number[]], callback?: () => void, ): void; /** * Detects the primary language of the content in a tab. * * @chrome-returns-extra since Chrome 88 * @param tabId Defaults to the active tab of the [current window](https://developer.chrome.com/docs/extensions/reference/windows/#current-window). */ export function detectLanguage( tabId?: number, ): Promise; /** * Detects the primary language of the content in a tab. * * @param tabId Defaults to the active tab of the [current window](https://developer.chrome.com/docs/extensions/reference/windows/#current-window). */ export function detectLanguage( tabId?: number, /** * @param language An ISO language code such as `en` or `fr`. For a complete list of languages supported by this method, see [kLanguageInfoTable](https://src.chromium.org/viewvc/chrome/trunk/src/third_party/cld/languages/internal/languages.cc). The second to fourth columns are checked and the first non-NULL value is returned, except for Simplified Chinese for which `zh-CN` is returned. For an unknown/undefined language, `und` is returned. */ callback?: ( language: string, ) => void, ): void; /** * Captures the visible area of the currently active tab in the specified window. In order to call this method, the extension must have either the [](https://developer.chrome.com/extensions/develop/concepts/declare-permissions) permission or the [activeTab](https://developer.chrome.com/docs/extensions/develop/concepts/activeTab) permission. In addition to sites that extensions can normally access, this method allows extensions to capture sensitive sites that are otherwise restricted, including chrome:-scheme pages, other extensions' pages, and data: URLs. These sensitive sites can only be captured with the activeTab permission. File URLs may be captured only if the extension has been granted file access. * * @chrome-returns-extra since Chrome 88 * @param windowId The target window. Defaults to the [current window](https://developer.chrome.com/docs/extensions/reference/windows/#current-window). */ export function captureVisibleTab( windowId?: number, options?: extensionTypes.ImageDetails, ): Promise; /** * Captures the visible area of the currently active tab in the specified window. In order to call this method, the extension must have either the [](https://developer.chrome.com/extensions/develop/concepts/declare-permissions) permission or the [activeTab](https://developer.chrome.com/docs/extensions/develop/concepts/activeTab) permission. In addition to sites that extensions can normally access, this method allows extensions to capture sensitive sites that are otherwise restricted, including chrome:-scheme pages, other extensions' pages, and data: URLs. These sensitive sites can only be captured with the activeTab permission. File URLs may be captured only if the extension has been granted file access. * * @param windowId The target window. Defaults to the [current window](https://developer.chrome.com/docs/extensions/reference/windows/#current-window). */ export function captureVisibleTab( windowId?: number, options?: extensionTypes.ImageDetails, /** * @param dataUrl A data URL that encodes an image of the visible area of the captured tab. May be assigned to the 'src' property of an HTML `img` element for display. */ callback?: ( dataUrl: string, ) => void, ): void; /** * Injects JavaScript code into a page. For details, see the [programmatic injection](https://developer.chrome.com/docs/extensions/develop/concepts/content-scripts#programmatic) section of the content scripts doc. * * @chrome-returns-extra since Chrome 88 * @param tabId The ID of the tab in which to run the script; defaults to the active tab of the current window. * @param details Details of the script to run. Either the code or the file property must be set, but both may not be set at the same time. * @returns Resolves after all the JavaScript has been executed. * @deprecated Replaced by {@link scripting.executeScript} in Manifest V3. * @chrome-max-manifest MV2 * @chrome-deprecated-since Chrome 91 */ export function executeScript( tabId: number, details: extensionTypes.InjectDetails, ): Promise; /** * Injects JavaScript code into a page. For details, see the [programmatic injection](https://developer.chrome.com/docs/extensions/develop/concepts/content-scripts#programmatic) section of the content scripts doc. * * @chrome-returns-extra since Chrome 88 * @param details Details of the script to run. Either the code or the file property must be set, but both may not be set at the same time. * @returns Resolves after all the JavaScript has been executed. * @deprecated Replaced by {@link scripting.executeScript} in Manifest V3. * @chrome-max-manifest MV2 * @chrome-deprecated-since Chrome 91 */ export function executeScript( details: extensionTypes.InjectDetails, ): Promise; /** * Injects JavaScript code into a page. For details, see the [programmatic injection](https://developer.chrome.com/docs/extensions/develop/concepts/content-scripts#programmatic) section of the content scripts doc. * * @param tabId The ID of the tab in which to run the script; defaults to the active tab of the current window. * @param details Details of the script to run. Either the code or the file property must be set, but both may not be set at the same time. * @deprecated Replaced by {@link scripting.executeScript} in Manifest V3. * @chrome-max-manifest MV2 * @chrome-deprecated-since Chrome 91 */ export function executeScript( tabId: number, details: extensionTypes.InjectDetails, /** * @param result The result of the script in every injected frame. */ callback?: ( result?: any[], ) => void, ): void; /** * Injects JavaScript code into a page. For details, see the [programmatic injection](https://developer.chrome.com/docs/extensions/develop/concepts/content-scripts#programmatic) section of the content scripts doc. * * @param details Details of the script to run. Either the code or the file property must be set, but both may not be set at the same time. * @deprecated Replaced by {@link scripting.executeScript} in Manifest V3. * @chrome-max-manifest MV2 * @chrome-deprecated-since Chrome 91 */ export function executeScript( details: extensionTypes.InjectDetails, /** * @param result The result of the script in every injected frame. */ callback?: ( result?: any[], ) => void, ): void; /** * Injects CSS into a page. Styles inserted with this method can be removed with {@link scripting.removeCSS}. For details, see the [programmatic injection](https://developer.chrome.com/docs/extensions/develop/concepts/content-scripts#programmatic) section of the content scripts doc. * * @chrome-returns-extra since Chrome 88 * @param tabId The ID of the tab in which to insert the CSS; defaults to the active tab of the current window. * @param details Details of the CSS text to insert. Either the code or the file property must be set, but both may not be set at the same time. * @returns Resolves when all the CSS has been inserted. * @deprecated Replaced by {@link scripting.insertCSS} in Manifest V3. * @chrome-max-manifest MV2 * @chrome-deprecated-since Chrome 91 */ export function insertCSS( tabId: number, details: extensionTypes.InjectDetails, ): Promise; /** * Injects CSS into a page. Styles inserted with this method can be removed with {@link scripting.removeCSS}. For details, see the [programmatic injection](https://developer.chrome.com/docs/extensions/develop/concepts/content-scripts#programmatic) section of the content scripts doc. * * @chrome-returns-extra since Chrome 88 * @param details Details of the CSS text to insert. Either the code or the file property must be set, but both may not be set at the same time. * @returns Resolves when all the CSS has been inserted. * @deprecated Replaced by {@link scripting.insertCSS} in Manifest V3. * @chrome-max-manifest MV2 * @chrome-deprecated-since Chrome 91 */ export function insertCSS( details: extensionTypes.InjectDetails, ): Promise; /** * Injects CSS into a page. Styles inserted with this method can be removed with {@link scripting.removeCSS}. For details, see the [programmatic injection](https://developer.chrome.com/docs/extensions/develop/concepts/content-scripts#programmatic) section of the content scripts doc. * * @param tabId The ID of the tab in which to insert the CSS; defaults to the active tab of the current window. * @param details Details of the CSS text to insert. Either the code or the file property must be set, but both may not be set at the same time. * @deprecated Replaced by {@link scripting.insertCSS} in Manifest V3. * @chrome-max-manifest MV2 * @chrome-deprecated-since Chrome 91 */ export function insertCSS( tabId: number, details: extensionTypes.InjectDetails, callback?: () => void, ): void; /** * Injects CSS into a page. Styles inserted with this method can be removed with {@link scripting.removeCSS}. For details, see the [programmatic injection](https://developer.chrome.com/docs/extensions/develop/concepts/content-scripts#programmatic) section of the content scripts doc. * * @param details Details of the CSS text to insert. Either the code or the file property must be set, but both may not be set at the same time. * @deprecated Replaced by {@link scripting.insertCSS} in Manifest V3. * @chrome-max-manifest MV2 * @chrome-deprecated-since Chrome 91 */ export function insertCSS( details: extensionTypes.InjectDetails, callback?: () => void, ): void; /** * Removes from a page CSS that was previously injected by a call to {@link scripting.insertCSS}. * * @chrome-returns-extra since Chrome 88 * @param tabId The ID of the tab from which to remove the CSS; defaults to the active tab of the current window. * @param details Details of the CSS text to remove. Either the code or the file property must be set, but both may not be set at the same time. * @returns Resolves when all the CSS has been removed. * @deprecated Replaced by {@link scripting.removeCSS} in Manifest V3. * @since Chrome 87 * @chrome-max-manifest MV2 * @chrome-deprecated-since Chrome 91 */ export function removeCSS( tabId: number, details: extensionTypes.DeleteInjectionDetails, ): Promise; /** * Removes from a page CSS that was previously injected by a call to {@link scripting.insertCSS}. * * @chrome-returns-extra since Chrome 88 * @param details Details of the CSS text to remove. Either the code or the file property must be set, but both may not be set at the same time. * @returns Resolves when all the CSS has been removed. * @deprecated Replaced by {@link scripting.removeCSS} in Manifest V3. * @since Chrome 87 * @chrome-max-manifest MV2 * @chrome-deprecated-since Chrome 91 */ export function removeCSS( details: extensionTypes.DeleteInjectionDetails, ): Promise; /** * Removes from a page CSS that was previously injected by a call to {@link scripting.insertCSS}. * * @param tabId The ID of the tab from which to remove the CSS; defaults to the active tab of the current window. * @param details Details of the CSS text to remove. Either the code or the file property must be set, but both may not be set at the same time. * @deprecated Replaced by {@link scripting.removeCSS} in Manifest V3. * @since Chrome 87 * @chrome-max-manifest MV2 * @chrome-deprecated-since Chrome 91 */ export function removeCSS( tabId: number, details: extensionTypes.DeleteInjectionDetails, callback?: () => void, ): void; /** * Removes from a page CSS that was previously injected by a call to {@link scripting.insertCSS}. * * @param details Details of the CSS text to remove. Either the code or the file property must be set, but both may not be set at the same time. * @deprecated Replaced by {@link scripting.removeCSS} in Manifest V3. * @since Chrome 87 * @chrome-max-manifest MV2 * @chrome-deprecated-since Chrome 91 */ export function removeCSS( details: extensionTypes.DeleteInjectionDetails, callback?: () => void, ): void; /** * Zooms a specified tab. * * @chrome-returns-extra since Chrome 88 * @param tabId The ID of the tab to zoom; defaults to the active tab of the current window. * @param zoomFactor The new zoom factor. A value of `0` sets the tab to its current default zoom factor. Values greater than `0` specify a (possibly non-default) zoom factor for the tab. * @returns Resolves after the zoom factor has been changed. */ export function setZoom( tabId: number, zoomFactor: number, ): Promise; /** * Zooms a specified tab. * * @chrome-returns-extra since Chrome 88 * @param zoomFactor The new zoom factor. A value of `0` sets the tab to its current default zoom factor. Values greater than `0` specify a (possibly non-default) zoom factor for the tab. * @returns Resolves after the zoom factor has been changed. */ export function setZoom( zoomFactor: number, ): Promise; /** * Zooms a specified tab. * * @param tabId The ID of the tab to zoom; defaults to the active tab of the current window. * @param zoomFactor The new zoom factor. A value of `0` sets the tab to its current default zoom factor. Values greater than `0` specify a (possibly non-default) zoom factor for the tab. */ export function setZoom( tabId: number, zoomFactor: number, callback?: () => void, ): void; /** * Zooms a specified tab. * * @param zoomFactor The new zoom factor. A value of `0` sets the tab to its current default zoom factor. Values greater than `0` specify a (possibly non-default) zoom factor for the tab. */ export function setZoom( zoomFactor: number, callback?: () => void, ): void; /** * Gets the current zoom factor of a specified tab. * * @chrome-returns-extra since Chrome 88 * @param tabId The ID of the tab to get the current zoom factor from; defaults to the active tab of the current window. * @returns Resolves with the tab's current zoom factor after it has been fetched. */ export function getZoom( tabId?: number, ): Promise; /** * Gets the current zoom factor of a specified tab. * * @param tabId The ID of the tab to get the current zoom factor from; defaults to the active tab of the current window. */ export function getZoom( tabId?: number, /** * @param zoomFactor The tab's current zoom factor. */ callback?: ( zoomFactor: number, ) => void, ): void; /** * Sets the zoom settings for a specified tab, which define how zoom changes are handled. These settings are reset to defaults upon navigating the tab. * * @chrome-returns-extra since Chrome 88 * @param tabId The ID of the tab to change the zoom settings for; defaults to the active tab of the current window. * @param zoomSettings Defines how zoom changes are handled and at what scope. * @returns Resolves after the zoom settings are changed. */ export function setZoomSettings( tabId: number, zoomSettings: ZoomSettings, ): Promise; /** * Sets the zoom settings for a specified tab, which define how zoom changes are handled. These settings are reset to defaults upon navigating the tab. * * @chrome-returns-extra since Chrome 88 * @param zoomSettings Defines how zoom changes are handled and at what scope. * @returns Resolves after the zoom settings are changed. */ export function setZoomSettings( zoomSettings: ZoomSettings, ): Promise; /** * Sets the zoom settings for a specified tab, which define how zoom changes are handled. These settings are reset to defaults upon navigating the tab. * * @param tabId The ID of the tab to change the zoom settings for; defaults to the active tab of the current window. * @param zoomSettings Defines how zoom changes are handled and at what scope. */ export function setZoomSettings( tabId: number, zoomSettings: ZoomSettings, callback?: () => void, ): void; /** * Sets the zoom settings for a specified tab, which define how zoom changes are handled. These settings are reset to defaults upon navigating the tab. * * @param zoomSettings Defines how zoom changes are handled and at what scope. */ export function setZoomSettings( zoomSettings: ZoomSettings, callback?: () => void, ): void; /** * Gets the current zoom settings of a specified tab. * * @chrome-returns-extra since Chrome 88 * @param tabId The ID of the tab to get the current zoom settings from; defaults to the active tab of the current window. * @returns Resolves with the tab's current zoom settings. */ export function getZoomSettings( tabId?: number, ): Promise; /** * Gets the current zoom settings of a specified tab. * * @param tabId The ID of the tab to get the current zoom settings from; defaults to the active tab of the current window. */ export function getZoomSettings( tabId?: number, /** * @param zoomSettings The tab's current zoom settings. */ callback?: ( zoomSettings: ZoomSettings, ) => void, ): void; /** * Discards a tab from memory. Discarded tabs are still visible on the tab strip and are reloaded when activated. * * @chrome-returns-extra since Chrome 88 * @param tabId The ID of the tab to be discarded. If specified, the tab is discarded unless it is active or already discarded. If omitted, the browser discards the least important tab. This can fail if no discardable tabs exist. * @returns Resolves after the operation is completed. * @since Chrome 54 */ export function discard( tabId?: number, ): Promise; /** * Discards a tab from memory. Discarded tabs are still visible on the tab strip and are reloaded when activated. * * @param tabId The ID of the tab to be discarded. If specified, the tab is discarded unless it is active or already discarded. If omitted, the browser discards the least important tab. This can fail if no discardable tabs exist. * @since Chrome 54 */ export function discard( tabId?: number, /** * @param tab The discarded tab, if it was successfully discarded; undefined otherwise. */ callback?: ( tab?: Tab, ) => void, ): void; /** * Go foward to the next page, if one is available. * * @chrome-returns-extra since Chrome 88 * @param tabId The ID of the tab to navigate forward; defaults to the selected tab of the current window. * @since Chrome 72 */ export function goForward( tabId?: number, ): Promise; /** * Go foward to the next page, if one is available. * * @param tabId The ID of the tab to navigate forward; defaults to the selected tab of the current window. * @since Chrome 72 */ export function goForward( tabId?: number, callback?: () => void, ): void; /** * Go back to the previous page, if one is available. * * @chrome-returns-extra since Chrome 88 * @param tabId The ID of the tab to navigate back; defaults to the selected tab of the current window. * @since Chrome 72 */ export function goBack( tabId?: number, ): Promise; /** * Go back to the previous page, if one is available. * * @param tabId The ID of the tab to navigate back; defaults to the selected tab of the current window. * @since Chrome 72 */ export function goBack( tabId?: number, callback?: () => void, ): void; } /** * Use the `chrome.topSites` API to access the top sites (i.e. most visited sites) that are displayed on the new tab page. These do not include shortcuts customized by the user. * * @chrome-permission topSites */ export namespace topSites { /** * An object encapsulating a most visited URL, such as the default shortcuts on the new tab page. */ export interface MostVisitedURL { /** * The most visited URL. */ url: string; /** * The title of the page */ title: string; } /** * Gets a list of top sites. * * @chrome-returns-extra since Chrome 96 */ export function get(): Promise; /** * Gets a list of top sites. */ export function get( callback?: ( data: MostVisitedURL[], ) => void, ): void; } /** * Use the `chrome.tts` API to play synthesized text-to-speech (TTS). See also the related {@link ttsEngine} API, which allows an extension to implement a speech engine. * * @chrome-permission tts */ export namespace tts { /** * @since Chrome 54 */ export type EventType = "start" | "end" | "word" | "sentence" | "marker" | "interrupted" | "cancelled" | "error" | "pause" | "resume"; /** * @deprecated Gender is deprecated and is ignored. * @since Chrome 54 * @chrome-deprecated-since Chrome 70 */ export type VoiceGender = "male" | "female"; /** * The speech options for the TTS engine. * * @since Chrome 77 */ export interface TtsOptions { /** * If true, enqueues this utterance if TTS is already in progress. If false (the default), interrupts any current speech and flushes the speech queue before speaking this new utterance. */ enqueue?: boolean; /** * The name of the voice to use for synthesis. If empty, uses any available voice. */ voiceName?: string; /** * The extension ID of the speech engine to use, if known. */ extensionId?: string; /** * The language to be used for synthesis, in the form _language_\-_region_. Examples: 'en', 'en-US', 'en-GB', 'zh-CN'. */ lang?: string; /** * Gender of voice for synthesized speech. * * @deprecated Gender is deprecated and will be ignored. * @chrome-deprecated-since Chrome 77 */ gender?: VoiceGender; /** * Speaking rate relative to the default rate for this voice. 1.0 is the default rate, normally around 180 to 220 words per minute. 2.0 is twice as fast, and 0.5 is half as fast. Values below 0.1 or above 10.0 are strictly disallowed, but many voices will constrain the minimum and maximum rates further—for example a particular voice may not actually speak faster than 3 times normal even if you specify a value larger than 3.0. */ rate?: number; /** * Speaking pitch between 0 and 2 inclusive, with 0 being lowest and 2 being highest. 1.0 corresponds to a voice's default pitch. */ pitch?: number; /** * Speaking volume between 0 and 1 inclusive, with 0 being lowest and 1 being highest, with a default of 1.0. */ volume?: number; /** * The TTS event types the voice must support. */ requiredEventTypes?: string[]; /** * The TTS event types that you are interested in listening to. If missing, all event types may be sent. */ desiredEventTypes?: string[]; /** * This function is called with events that occur in the process of speaking the utterance. * * @param event The update event from the text-to-speech engine indicating the status of this utterance. */ onEvent?: ( event: TtsEvent, ) => void; } /** * An event from the TTS engine to communicate the status of an utterance. */ export interface TtsEvent { /** * The type can be `start` as soon as speech has started, `word` when a word boundary is reached, `sentence` when a sentence boundary is reached, `marker` when an SSML mark element is reached, `end` when the end of the utterance is reached, `interrupted` when the utterance is stopped or interrupted before reaching the end, `cancelled` when it's removed from the queue before ever being synthesized, or `error` when any other error occurs. When pausing speech, a `pause` event is fired if a particular utterance is paused in the middle, and `resume` if an utterance resumes speech. Note that pause and resume events may not fire if speech is paused in-between utterances. */ type: EventType; /** * The index of the current character in the utterance. For word events, the event fires at the end of one word and before the beginning of the next. The `charIndex` represents a point in the text at the beginning of the next word to be spoken. */ charIndex?: number; /** * The error description, if the event type is `error`. */ errorMessage?: string; /** * The length of the next part of the utterance. For example, in a `word` event, this is the length of the word which will be spoken next. It will be set to -1 if not set by the speech engine. * * @since Chrome 74 */ length?: number; } /** * A description of a voice available for speech synthesis. */ export interface TtsVoice { /** * The name of the voice. */ voiceName?: string; /** * The language that this voice supports, in the form _language_\-_region_. Examples: 'en', 'en-US', 'en-GB', 'zh-CN'. */ lang?: string; /** * This voice's gender. * * @deprecated Gender is deprecated and will be ignored. * @chrome-deprecated-since Chrome 70 */ gender?: VoiceGender; /** * If true, the synthesis engine is a remote network resource. It may be higher latency and may incur bandwidth costs. */ remote?: boolean; /** * The ID of the extension providing this voice. */ extensionId?: string; /** * All of the callback event types that this voice is capable of sending. */ eventTypes?: EventType[]; } /** * Called when the list of {@link tts.TtsVoice} that would be returned by getVoices has changed. * * @since Chrome 124 */ export const onVoicesChanged: events.Event<() => void>; /** * Speaks text using a text-to-speech engine. * * @chrome-returns-extra since Chrome 101 * @param utterance The text to speak, either plain text or a complete, well-formed SSML document. Speech engines that do not support SSML will strip away the tags and speak the text. The maximum length of the text is 32,768 characters. * @param options The speech options. * @returns Resolves right away, before speech finishes. If an error occurs, the promise will be rejected. Use options.onEvent to get more detailed feedback. */ export function speak( utterance: string, options?: TtsOptions, ): Promise; /** * Speaks text using a text-to-speech engine. * * @param utterance The text to speak, either plain text or a complete, well-formed SSML document. Speech engines that do not support SSML will strip away the tags and speak the text. The maximum length of the text is 32,768 characters. * @param options The speech options. */ export function speak( utterance: string, options?: TtsOptions, callback?: () => void, ): void; /** * Stops any current speech and flushes the queue of any pending utterances. In addition, if speech was paused, it will now be un-paused for the next call to speak. */ export function stop(): void; /** * Pauses speech synthesis, potentially in the middle of an utterance. A call to resume or stop will un-pause speech. */ export function pause(): void; /** * If speech was paused, resumes speaking where it left off. */ export function resume(): void; /** * Checks whether the engine is currently speaking. On Mac OS X, the result is true whenever the system speech engine is speaking, even if the speech wasn't initiated by Chrome. * * @chrome-returns-extra since Chrome 101 */ export function isSpeaking(): Promise; /** * Checks whether the engine is currently speaking. On Mac OS X, the result is true whenever the system speech engine is speaking, even if the speech wasn't initiated by Chrome. */ export function isSpeaking( /** * @param speaking True if speaking, false otherwise. */ callback?: ( speaking: boolean, ) => void, ): void; /** * Gets an array of all available voices. * * @chrome-returns-extra since Chrome 101 */ export function getVoices(): Promise; /** * Gets an array of all available voices. */ export function getVoices( /** * @param voices Array of {@link tts.TtsVoice} objects representing the available voices for speech synthesis. */ callback?: ( voices: TtsVoice[], ) => void, ): void; } /** * Use the `chrome.ttsEngine` API to implement a text-to-speech(TTS) engine using an extension. If your extension registers using this API, it will receive events containing an utterance to be spoken and other parameters when any extension or Chrome App uses the {@link tts} API to generate speech. Your extension can then use any available web technology to synthesize and output the speech, and send events back to the calling function to report the status. * * @chrome-permission ttsEngine */ export namespace ttsEngine { /** * Type of requestor. * * @since Chrome 131 */ export type TtsClientSource = "chromefeature" | "extension"; /** * Identifier for the client requesting status. * * @since Chrome 131 */ export interface TtsClient { /** * Client making a language management request. For an extension, this is the unique extension ID. For Chrome features, this is the human-readable name of the feature. */ id: string; /** * Type of requestor. */ source: TtsClientSource; } /** * @deprecated Gender is deprecated and will be ignored. * @since Chrome 54 * @chrome-deprecated-since Chrome 70 */ export type VoiceGender = "male" | "female"; /** * Options for uninstalling a given language. * * @since Chrome 132 */ export interface LanguageUninstallOptions { /** * True if the TTS client wants the language to be immediately uninstalled. The engine may choose whether or when to uninstall the language, based on this parameter and the requestor information. If false, it may use other criteria, such as recent usage, to determine when to uninstall. */ uninstallImmediately: boolean; } /** * The install status of a voice. * * @since Chrome 132 */ export type LanguageInstallStatus = "notInstalled" | "installing" | "installed" | "failed"; /** * Install status of a language. * * @since Chrome 132 */ export interface LanguageStatus { /** * Language string in the form of language code-region code, where the region may be omitted. Examples are en, en-AU, zh-CH. */ lang: string; /** * Installation status. */ installStatus: LanguageInstallStatus; /** * Detail about installation failures. Optionally populated if the language failed to install. */ error?: string; } /** * Options specified to the tts.speak() method. * * @since Chrome 92 */ export interface SpeakOptions { /** * The name of the voice to use for synthesis. */ voiceName?: string; /** * The language to be used for synthesis, in the form _language_\-_region_. Examples: 'en', 'en-US', 'en-GB', 'zh-CN'. */ lang?: string; /** * Gender of voice for synthesized speech. * * @deprecated Gender is deprecated and will be ignored. * @chrome-deprecated-since Chrome 92 */ gender?: VoiceGender; /** * Speaking rate relative to the default rate for this voice. 1.0 is the default rate, normally around 180 to 220 words per minute. 2.0 is twice as fast, and 0.5 is half as fast. This value is guaranteed to be between 0.1 and 10.0, inclusive. When a voice does not support this full range of rates, don't return an error. Instead, clip the rate to the range the voice supports. */ rate?: number; /** * Speaking pitch between 0 and 2 inclusive, with 0 being lowest and 2 being highest. 1.0 corresponds to this voice's default pitch. */ pitch?: number; /** * Speaking volume between 0 and 1 inclusive, with 0 being lowest and 1 being highest, with a default of 1.0. */ volume?: number; } /** * Contains the audio stream format expected to be produced by an engine. * * @since Chrome 92 */ export interface AudioStreamOptions { /** * The sample rate expected in an audio buffer. */ sampleRate: number; /** * The number of samples within an audio buffer. */ bufferSize: number; } /** * Parameters containing an audio buffer and associated data. * * @since Chrome 92 */ export interface AudioBuffer { /** * The audio buffer from the text-to-speech engine. It should have length exactly audioStreamOptions.bufferSize and encoded as mono, at audioStreamOptions.sampleRate, and as linear pcm, 32-bit signed float i.e. the Float32Array type in javascript. */ audioBuffer: ArrayBuffer; /** * The character index associated with this audio buffer. */ charIndex?: number; /** * True if this audio buffer is the last for the text being spoken. */ isLastBuffer?: boolean; } /** * Called when the user makes a call to tts.speak() and one of the voices from this extension's manifest is the first to match the options object. */ export const onSpeak: events.Event<( utterance: string, options: SpeakOptions, /** * @param event The event from the text-to-speech engine indicating the status of this utterance. */ sendTtsEvent: ( event: tts.TtsEvent, ) => void, ) => void>; /** * Called when the user makes a call to tts.speak() and one of the voices from this extension's manifest is the first to match the options object. Differs from ttsEngine.onSpeak in that Chrome provides audio playback services and handles dispatching tts events. * * @since Chrome 92 */ export const onSpeakWithAudioStream: events.Event<( utterance: string, options: SpeakOptions, audioStreamOptions: AudioStreamOptions, /** * @param audioBufferParams Parameters containing an audio buffer and associated data. */ sendTtsAudio: ( audioBufferParams: AudioBuffer, ) => void, /** * @param errorMessage A string describing the error. * @since Chrome 94 */ sendError: ( errorMessage?: string, ) => void, ) => void>; /** * Fired when a call is made to tts.stop and this extension may be in the middle of speaking. If an extension receives a call to onStop and speech is already stopped, it should do nothing (not raise an error). If speech is in the paused state, this should cancel the paused state. */ export const onStop: events.Event<() => void>; /** * Optional: if an engine supports the pause event, it should pause the current utterance being spoken, if any, until it receives a resume event or stop event. Note that a stop event should also clear the paused state. */ export const onPause: events.Event<() => void>; /** * Optional: if an engine supports the pause event, it should also support the resume event, to continue speaking the current utterance, if any. Note that a stop event should also clear the paused state. */ export const onResume: events.Event<() => void>; /** * Fired when a TTS client requests to install a new language. The engine should attempt to download and install the language, and call ttsEngine.updateLanguage with the result. On success, the engine should also call ttsEngine.updateVoices to register the newly available voices. * * @since Chrome 131 */ export const onInstallLanguageRequest: events.Event<( requestor: TtsClient, lang: string, ) => void>; /** * Fired when a TTS client indicates a language is no longer needed. * * @since Chrome 132 */ export const onUninstallLanguageRequest: events.Event<( requestor: TtsClient, lang: string, uninstallOptions: LanguageUninstallOptions, ) => void>; /** * Fired when a TTS client requests the install status of a language. * * @since Chrome 132 */ export const onLanguageStatusRequest: events.Event<( requestor: TtsClient, lang: string, ) => void>; /** * Called by an engine to update its list of voices. This list overrides any voices declared in this extension's manifest. * * @param voices Array of {@link tts.TtsVoice} objects representing the available voices for speech synthesis. * @since Chrome 66 */ export function updateVoices( voices: tts.TtsVoice[], ): void; /** * Called by an engine when a language install is attempted, and when a language is uninstalled. Also called in response to a status request from a client. When a voice is installed or uninstalled, the engine should also call ttsEngine.updateVoices to register the voice. * * @param status The install status of the language. * @since Chrome 132 */ export function updateLanguage( status: LanguageStatus, ): void; } /** * The `chrome.types` API contains type declarations for Chrome. */ export namespace types { /** * The scope of the ChromeSetting. One of * * * `regular`: setting for the regular profile (which is inherited by the incognito profile if not overridden elsewhere), * * `regular\_only`: setting for the regular profile only (not inherited by the incognito profile), * * `incognito\_persistent`: setting for the incognito profile that survives browser restarts (overrides regular preferences), * * `incognito\_session\_only`: setting for the incognito profile that can only be set during an incognito session and is deleted when the incognito session ends (overrides regular and incognito\_persistent preferences). * * @since Chrome 44 */ export type ChromeSettingScope = "regular" | "regular_only" | "incognito_persistent" | "incognito_session_only"; /** * One of * * * `not\_controllable`: cannot be controlled by any extension * * `controlled\_by\_other\_extensions`: controlled by extensions with higher precedence * * `controllable\_by\_this\_extension`: can be controlled by this extension * * `controlled\_by\_this\_extension`: controlled by this extension * * @since Chrome 44 */ export type LevelOfControl = "not_controllable" | "controlled_by_other_extensions" | "controllable_by_this_extension" | "controlled_by_this_extension"; /** * An interface that allows access to a Chrome browser setting. See {@link accessibilityFeatures} for an example. */ export interface ChromeSetting { /** * Fired after the setting changes. */ onChange: events.Event<( details: { /** * The value of the setting after the change. */ value: T, /** * The level of control of the setting. */ levelOfControl: LevelOfControl, /** * Whether the value that has changed is specific to the incognito session. * This property will _only_ be present if the user has enabled the extension in incognito mode. */ incognitoSpecific?: boolean, }, ) => void>; /** * Gets the value of a setting. * * @chrome-returns-extra since Chrome 96 * @param details Which setting to consider. */ get( details: { /** * Whether to return the value that applies to the incognito session (default false). */ incognito?: boolean, }, ): Promise<{ /** * The value of the setting. */ value: T, /** * The level of control of the setting. */ levelOfControl: LevelOfControl, /** * Whether the effective value is specific to the incognito session. * This property will _only_ be present if the `incognito` property in the `details` parameter of `get()` was true. */ incognitoSpecific?: boolean, }>; /** * Gets the value of a setting. * * @param details Which setting to consider. */ get( details: { /** * Whether to return the value that applies to the incognito session (default false). */ incognito?: boolean, }, /** * @param details Details of the currently effective value. */ callback?: ( details: { /** * The value of the setting. */ value: T, /** * The level of control of the setting. */ levelOfControl: LevelOfControl, /** * Whether the effective value is specific to the incognito session. * This property will _only_ be present if the `incognito` property in the `details` parameter of `get()` was true. */ incognitoSpecific?: boolean, }, ) => void, ): void; /** * Sets the value of a setting. * * @chrome-returns-extra since Chrome 96 * @param details Which setting to change. * @returns Called at the completion of the set operation. */ set( details: { /** * The value of the setting. * Note that every setting has a specific value type, which is described together with the setting. An extension should _not_ set a value of a different type. */ value: T, /** * Where to set the setting (default: regular). */ scope?: ChromeSettingScope, }, ): Promise; /** * Sets the value of a setting. * * @param details Which setting to change. */ set( details: { /** * The value of the setting. * Note that every setting has a specific value type, which is described together with the setting. An extension should _not_ set a value of a different type. */ value: T, /** * Where to set the setting (default: regular). */ scope?: ChromeSettingScope, }, callback?: () => void, ): void; /** * Clears the setting, restoring any default value. * * @chrome-returns-extra since Chrome 96 * @param details Which setting to clear. * @returns Called at the completion of the clear operation. */ clear( details: { /** * Where to clear the setting (default: regular). */ scope?: ChromeSettingScope, }, ): Promise; /** * Clears the setting, restoring any default value. * * @param details Which setting to clear. */ clear( details: { /** * Where to clear the setting (default: regular). */ scope?: ChromeSettingScope, }, callback?: () => void, ): void; } } /** * Use the `chrome.usb` API to interact with connected USB devices. This API provides access to USB operations from within the context of an app. Using this API, apps can function as drivers for hardware devices. Errors generated by this API are reported by setting {@link runtime.lastError} and executing the function's regular callback. The callback's regular parameters will be undefined in this case. * * @chrome-permission usb * @chrome-platform-apps * @chrome-platform chromeos * @chrome-platform linux * @chrome-platform mac * @chrome-platform win */ export namespace usb { /** * Direction, Recipient, RequestType, and TransferType all map to their namesakes within the USB specification. */ export type Direction = "in" | "out"; export type Recipient = "device" | "interface" | "endpoint" | "other"; export type RequestType = "standard" | "class" | "vendor" | "reserved"; export type TransferType = "control" | "interrupt" | "isochronous" | "bulk"; /** * For interrupt and isochronous modes, SynchronizationType and UsageType map to their namesakes within the USB specification. */ export type SynchronizationType = "asynchronous" | "adaptive" | "synchronous"; export type UsageType = "data" | "feedback" | "explicitFeedback" | "periodic" | "notification"; export interface Device { /** * An opaque ID for the USB device. It remains unchanged until the device is unplugged. */ device: number; /** * The device vendor ID. */ vendorId: number; /** * The product ID. */ productId: number; /** * The device version (bcdDevice field). * * @since Chrome 51 */ version: number; /** * The iProduct string read from the device, if available. * * @since Chrome 46 */ productName: string; /** * The iManufacturer string read from the device, if available. * * @since Chrome 46 */ manufacturerName: string; /** * The iSerialNumber string read from the device, if available. * * @since Chrome 46 */ serialNumber: string; } export interface ConnectionHandle { /** * An opaque handle representing this connection to the USB device and all associated claimed interfaces and pending transfers. A new handle is created each time the device is opened. The connection handle is different from {@link Device.device}. */ handle: number; /** * The device vendor ID. */ vendorId: number; /** * The product ID. */ productId: number; } export interface EndpointDescriptor { /** * Endpoint address. */ address: number; /** * Transfer type. */ type: TransferType; /** * Transfer direction. */ direction: Direction; /** * Maximum packet size. */ maximumPacketSize: number; /** * Transfer synchronization mode (isochronous only). */ synchronization?: SynchronizationType; /** * Endpoint usage hint. */ usage?: UsageType; /** * Polling interval (interrupt and isochronous only). */ pollingInterval?: number; /** * Extra descriptor data associated with this endpoint. */ extra_data: ArrayBuffer; } export interface InterfaceDescriptor { /** * The interface number. */ interfaceNumber: number; /** * The interface alternate setting number (defaults to `0` */ alternateSetting: number; /** * The USB interface class. */ interfaceClass: number; /** * The USB interface sub-class. */ interfaceSubclass: number; /** * The USB interface protocol. */ interfaceProtocol: number; /** * Description of the interface. */ description?: string; /** * Available endpoints. */ endpoints: EndpointDescriptor[]; /** * Extra descriptor data associated with this interface. */ extra_data: ArrayBuffer; } export interface ConfigDescriptor { /** * Is this the active configuration? * * @since Chrome 47 */ active: boolean; /** * The configuration number. */ configurationValue: number; /** * Description of the configuration. */ description?: string; /** * The device is self-powered. */ selfPowered: boolean; /** * The device supports remote wakeup. */ remoteWakeup: boolean; /** * The maximum power needed by this device in milliamps (mA). */ maxPower: number; /** * Available interfaces. */ interfaces: InterfaceDescriptor[]; /** * Extra descriptor data associated with this configuration. */ extra_data: ArrayBuffer; } export interface ControlTransferInfo { /** * The transfer direction (`"in"` or `"out"`). */ direction: Direction; /** * The transfer target. The target given by `index` must be claimed if `"interface"` or `"endpoint"`. */ recipient: Recipient; /** * The request type. */ requestType: RequestType; /** * The `bRequest` field, see _Universal Serial Bus Specification Revision 1.1_ § 9.3. */ request: number; /** * The `wValue` field, see _Ibid_. */ value: number; /** * The `wIndex` field, see _Ibid_. */ index: number; /** * The maximum number of bytes to receive (required only by input transfers). */ length?: number; /** * The data to transmit (required only by output transfers). */ data?: ArrayBuffer; /** * Request timeout (in milliseconds). The default value `0` indicates no timeout. * * @since Chrome 43 */ timeout?: number; } export interface GenericTransferInfo { /** * The transfer direction (`"in"` or `"out"`). */ direction: Direction; /** * The target endpoint address. The interface containing this endpoint must be claimed. */ endpoint: number; /** * The maximum number of bytes to receive (required only by input transfers). */ length?: number; /** * The data to transmit (required only by output transfers). */ data?: ArrayBuffer; /** * Request timeout (in milliseconds). The default value `0` indicates no timeout. * * @since Chrome 43 */ timeout?: number; } export interface IsochronousTransferInfo { /** * Transfer parameters. The transfer length or data buffer specified in this parameter block is split along `packetLength` boundaries to form the individual packets of the transfer. */ transferInfo: GenericTransferInfo; /** * The total number of packets in this transfer. */ packets: number; /** * The length of each of the packets in this transfer. */ packetLength: number; } export interface TransferResultInfo { /** * A value of `0` indicates that the transfer was a success. Other values indicate failure. */ resultCode?: number; /** * The data returned by an input transfer. `undefined` for output transfers. */ data?: ArrayBuffer; } export interface DeviceFilter { /** * Device vendor ID. */ vendorId?: number; /** * Device product ID, checked only if the vendor ID matches. */ productId?: number; /** * USB interface class, matches any interface on the device. */ interfaceClass?: number; /** * USB interface sub-class, checked only if the interface class matches. */ interfaceSubclass?: number; /** * USB interface protocol, checked only if the interface sub-class matches. */ interfaceProtocol?: number; } export interface EnumerateDevicesOptions { /** * @deprecated Equivalent to setting {@link DeviceFilter.vendorId}. */ vendorId?: number; /** * @deprecated Equivalent to setting {@link DeviceFilter.productId}. */ productId?: number; /** * A device matching any given filter will be returned. An empty filter list will return all devices the app has permission for. */ filters?: DeviceFilter[]; } export interface EnumerateDevicesAndRequestAccessOptions { /** * The device vendor ID. */ vendorId: number; /** * The product ID. */ productId: number; /** * The interface ID to request access to. Only available on Chrome OS. It has no effect on other platforms. */ interfaceId?: number; } export interface DevicePromptOptions { /** * Allow the user to select multiple devices. */ multiple?: boolean; /** * Filter the list of devices presented to the user. If multiple filters are provided devices matching any filter will be displayed. */ filters?: DeviceFilter[]; } /** * Event generated when a device is added to the system. Events are only broadcast to apps and extensions that have permission to access the device. Permission may have been granted at install time, when the user accepted an optional permission (see {@link permissions.request}), or through {@link getUserSelectedDevices}. */ export const onDeviceAdded: events.Event<( device: Device, ) => void>; /** * Event generated when a device is removed from the system. See {@link onDeviceAdded} for which events are delivered. */ export const onDeviceRemoved: events.Event<( device: Device, ) => void>; /** * Enumerates connected USB devices. * * @chrome-returns-extra since Chrome 116 * @param options The properties to search for on target devices. */ export function getDevices( options: EnumerateDevicesOptions, ): Promise; /** * Enumerates connected USB devices. * * @param options The properties to search for on target devices. */ export function getDevices( options: EnumerateDevicesOptions, callback?: ( devices: Device[], ) => void, ): void; /** * Presents a device picker to the user and returns the {@link Device}s selected. If the user cancels the picker devices will be empty. A user gesture is required for the dialog to display. Without a user gesture, the callback will run as though the user cancelled. * * @chrome-returns-extra since Chrome 116 * @param options Configuration of the device picker dialog box. */ export function getUserSelectedDevices( options: DevicePromptOptions, ): Promise; /** * Presents a device picker to the user and returns the {@link Device}s selected. If the user cancels the picker devices will be empty. A user gesture is required for the dialog to display. Without a user gesture, the callback will run as though the user cancelled. * * @param options Configuration of the device picker dialog box. */ export function getUserSelectedDevices( options: DevicePromptOptions, callback?: ( devices: Device[], ) => void, ): void; /** * Returns the full set of device configuration descriptors. * * @chrome-returns-extra since Chrome 116 * @param device The {@link Device} to fetch descriptors from. * @since Chrome 47 */ export function getConfigurations( device: Device, ): Promise; /** * Returns the full set of device configuration descriptors. * * @param device The {@link Device} to fetch descriptors from. * @since Chrome 47 */ export function getConfigurations( device: Device, callback?: ( configs: ConfigDescriptor[], ) => void, ): void; /** * Requests access from the permission broker to a device claimed by Chrome OS if the given interface on the device is not claimed. * * @chrome-returns-extra since Chrome 116 * @param device The {@link Device} to request access to. * @param interfaceId The particular interface requested. * @deprecated This function was Chrome OS specific and calling it on other platforms would fail. This operation is now implicitly performed as part of {@link openDevice} and this function will return `true` on all platforms. */ export function requestAccess( device: Device, interfaceId: number, ): Promise; /** * Requests access from the permission broker to a device claimed by Chrome OS if the given interface on the device is not claimed. * * @param device The {@link Device} to request access to. * @param interfaceId The particular interface requested. * @deprecated This function was Chrome OS specific and calling it on other platforms would fail. This operation is now implicitly performed as part of {@link openDevice} and this function will return `true` on all platforms. */ export function requestAccess( device: Device, interfaceId: number, callback?: ( success: boolean, ) => void, ): void; /** * Opens a USB device returned by {@link getDevices}. * * @chrome-returns-extra since Chrome 116 * @param device The {@link Device} to open. */ export function openDevice( device: Device, ): Promise; /** * Opens a USB device returned by {@link getDevices}. * * @param device The {@link Device} to open. */ export function openDevice( device: Device, callback?: ( handle: ConnectionHandle, ) => void, ): void; /** * Finds USB devices specified by the vendor, product and (optionally) interface IDs and if permissions allow opens them for use. * * If the access request is rejected or the device fails to be opened a connection handle will not be created or returned. * * Calling this method is equivalent to calling {@link getDevices} followed by {@link openDevice} for each device. * * @chrome-returns-extra since Chrome 116 * @param options The properties to search for on target devices. */ export function findDevices( options: EnumerateDevicesAndRequestAccessOptions, ): Promise; /** * Finds USB devices specified by the vendor, product and (optionally) interface IDs and if permissions allow opens them for use. * * If the access request is rejected or the device fails to be opened a connection handle will not be created or returned. * * Calling this method is equivalent to calling {@link getDevices} followed by {@link openDevice} for each device. * * @param options The properties to search for on target devices. */ export function findDevices( options: EnumerateDevicesAndRequestAccessOptions, callback?: ( handles: ConnectionHandle[], ) => void, ): void; /** * Closes a connection handle. Invoking operations on a handle after it has been closed is a safe operation but causes no action to be taken. * * @chrome-returns-extra since Chrome 116 * @param handle The {@link ConnectionHandle} to close. */ export function closeDevice( handle: ConnectionHandle, ): Promise; /** * Closes a connection handle. Invoking operations on a handle after it has been closed is a safe operation but causes no action to be taken. * * @param handle The {@link ConnectionHandle} to close. */ export function closeDevice( handle: ConnectionHandle, callback?: () => void, ): void; /** * Select a device configuration. * * This function effectively resets the device by selecting one of the device's available configurations. Only configuration values greater than `0` are valid however some buggy devices have a working configuration `0` and so this value is allowed. * * @chrome-returns-extra since Chrome 116 * @param handle An open connection to the device. */ export function setConfiguration( handle: ConnectionHandle, configurationValue: number, ): Promise; /** * Select a device configuration. * * This function effectively resets the device by selecting one of the device's available configurations. Only configuration values greater than `0` are valid however some buggy devices have a working configuration `0` and so this value is allowed. * * @param handle An open connection to the device. */ export function setConfiguration( handle: ConnectionHandle, configurationValue: number, callback?: () => void, ): void; /** * Gets the configuration descriptor for the currently selected configuration. * * @chrome-returns-extra since Chrome 116 * @param handle An open connection to the device. */ export function getConfiguration( handle: ConnectionHandle, ): Promise; /** * Gets the configuration descriptor for the currently selected configuration. * * @param handle An open connection to the device. */ export function getConfiguration( handle: ConnectionHandle, callback?: ( config: ConfigDescriptor, ) => void, ): void; /** * Lists all interfaces on a USB device. * * @chrome-returns-extra since Chrome 116 * @param handle An open connection to the device. */ export function listInterfaces( handle: ConnectionHandle, ): Promise; /** * Lists all interfaces on a USB device. * * @param handle An open connection to the device. */ export function listInterfaces( handle: ConnectionHandle, callback?: ( descriptors: InterfaceDescriptor[], ) => void, ): void; /** * Claims an interface on a USB device. Before data can be transfered to an interface or associated endpoints the interface must be claimed. Only one connection handle can claim an interface at any given time. If the interface is already claimed, this call will fail. * * {@link releaseInterface} should be called when the interface is no longer needed. * * @chrome-returns-extra since Chrome 116 * @param handle An open connection to the device. * @param interfaceNumber The interface to be claimed. */ export function claimInterface( handle: ConnectionHandle, interfaceNumber: number, ): Promise; /** * Claims an interface on a USB device. Before data can be transfered to an interface or associated endpoints the interface must be claimed. Only one connection handle can claim an interface at any given time. If the interface is already claimed, this call will fail. * * {@link releaseInterface} should be called when the interface is no longer needed. * * @param handle An open connection to the device. * @param interfaceNumber The interface to be claimed. */ export function claimInterface( handle: ConnectionHandle, interfaceNumber: number, callback?: () => void, ): void; /** * Releases a claimed interface. * * @chrome-returns-extra since Chrome 116 * @param handle An open connection to the device. * @param interfaceNumber The interface to be released. */ export function releaseInterface( handle: ConnectionHandle, interfaceNumber: number, ): Promise; /** * Releases a claimed interface. * * @param handle An open connection to the device. * @param interfaceNumber The interface to be released. */ export function releaseInterface( handle: ConnectionHandle, interfaceNumber: number, callback?: () => void, ): void; /** * Selects an alternate setting on a previously claimed interface. * * @chrome-returns-extra since Chrome 116 * @param handle An open connection to the device where this interface has been claimed. * @param interfaceNumber The interface to configure. * @param alternateSetting The alternate setting to configure. */ export function setInterfaceAlternateSetting( handle: ConnectionHandle, interfaceNumber: number, alternateSetting: number, ): Promise; /** * Selects an alternate setting on a previously claimed interface. * * @param handle An open connection to the device where this interface has been claimed. * @param interfaceNumber The interface to configure. * @param alternateSetting The alternate setting to configure. */ export function setInterfaceAlternateSetting( handle: ConnectionHandle, interfaceNumber: number, alternateSetting: number, callback?: () => void, ): void; /** * Performs a control transfer on the specified device. * * Control transfers refer to either the device, an interface or an endpoint. Transfers to an interface or endpoint require the interface to be claimed. * * @chrome-returns-extra since Chrome 116 * @param handle An open connection to the device. */ export function controlTransfer( handle: ConnectionHandle, transferInfo: ControlTransferInfo, ): Promise; /** * Performs a control transfer on the specified device. * * Control transfers refer to either the device, an interface or an endpoint. Transfers to an interface or endpoint require the interface to be claimed. * * @param handle An open connection to the device. */ export function controlTransfer( handle: ConnectionHandle, transferInfo: ControlTransferInfo, callback?: ( info: TransferResultInfo, ) => void, ): void; /** * Performs a bulk transfer on the specified device. * * @chrome-returns-extra since Chrome 116 * @param handle An open connection to the device. * @param transferInfo The transfer parameters. */ export function bulkTransfer( handle: ConnectionHandle, transferInfo: GenericTransferInfo, ): Promise; /** * Performs a bulk transfer on the specified device. * * @param handle An open connection to the device. * @param transferInfo The transfer parameters. */ export function bulkTransfer( handle: ConnectionHandle, transferInfo: GenericTransferInfo, callback?: ( info: TransferResultInfo, ) => void, ): void; /** * Performs an interrupt transfer on the specified device. * * @chrome-returns-extra since Chrome 116 * @param handle An open connection to the device. * @param transferInfo The transfer parameters. */ export function interruptTransfer( handle: ConnectionHandle, transferInfo: GenericTransferInfo, ): Promise; /** * Performs an interrupt transfer on the specified device. * * @param handle An open connection to the device. * @param transferInfo The transfer parameters. */ export function interruptTransfer( handle: ConnectionHandle, transferInfo: GenericTransferInfo, callback?: ( info: TransferResultInfo, ) => void, ): void; /** * Performs an isochronous transfer on the specific device. * * @chrome-returns-extra since Chrome 116 * @param handle An open connection to the device. */ export function isochronousTransfer( handle: ConnectionHandle, transferInfo: IsochronousTransferInfo, ): Promise; /** * Performs an isochronous transfer on the specific device. * * @param handle An open connection to the device. */ export function isochronousTransfer( handle: ConnectionHandle, transferInfo: IsochronousTransferInfo, callback?: ( info: TransferResultInfo, ) => void, ): void; /** * Tries to reset the USB device. If the reset fails, the given connection handle will be closed and the USB device will appear to be disconnected then reconnected. In this case {@link getDevices} or {@link findDevices} must be called again to acquire the device. * * @chrome-returns-extra since Chrome 116 * @param handle A connection handle to reset. */ export function resetDevice( handle: ConnectionHandle, ): Promise; /** * Tries to reset the USB device. If the reset fails, the given connection handle will be closed and the USB device will appear to be disconnected then reconnected. In this case {@link getDevices} or {@link findDevices} must be called again to acquire the device. * * @param handle A connection handle to reset. */ export function resetDevice( handle: ConnectionHandle, callback?: ( success: boolean, ) => void, ): void; } /** * Use the `userScripts` API to execute user scripts in the User Scripts context. * * @since Chrome 120 * @chrome-permission userScripts * @chrome-min-manifest MV3 */ export namespace userScripts { /** * The JavaScript world for a user script to execute within. * * @chrome-enum "MAIN" Specifies the execution environment of the DOM, which is the execution environment shared with the host page's JavaScript. * @chrome-enum "USER\_SCRIPT" Specifies the execution environment that is specific to user scripts and is exempt from the page's CSP. */ export type ExecutionWorld = "MAIN" | "USER_SCRIPT"; export interface ScriptSource { /** * A string containing the JavaScript code to inject. Exactly one of `file` or `code` must be specified. */ code?: string; /** * The path of the JavaScript file to inject relative to the extension's root directory. Exactly one of `file` or `code` must be specified. */ file?: string; } export interface RegisteredUserScript { /** * If true, it will inject into all frames, even if the frame is not the top-most frame in the tab. Each frame is checked independently for URL requirements; it will not inject into child frames if the URL requirements are not met. Defaults to false, meaning that only the top frame is matched. */ allFrames?: boolean; /** * Excludes pages that this user script would otherwise be injected into. See [Match Patterns](https://developer.chrome.com/extensions/develop/concepts/match-patterns) for more details on the syntax of these strings. */ excludeMatches?: string[]; /** * The ID of the user script specified in the API call. This property must not start with a '\_' as it's reserved as a prefix for generated script IDs. */ id: string; /** * Specifies wildcard patterns for pages this user script will be injected into. */ includeGlobs?: string[]; /** * Specifies wildcard patterns for pages this user script will NOT be injected into. */ excludeGlobs?: string[]; /** * The list of ScriptSource objects defining sources of scripts to be injected into matching pages. This property must be specified for ${ref:register}, and when specified it must be a non-empty array. */ js?: ScriptSource[]; /** * Specifies which pages this user script will be injected into. See [Match Patterns](https://developer.chrome.com/extensions/develop/concepts/match-patterns) for more details on the syntax of these strings. This property must be specified for ${ref:register}. */ matches?: string[]; /** * Specifies when JavaScript files are injected into the web page. The preferred and default value is `document_idle`. */ runAt?: extensionTypes.RunAt; /** * The JavaScript execution environment to run the script in. The default is `` `USER_SCRIPT` ``. */ world?: ExecutionWorld; /** * Specifies the user script world ID to execute in. If omitted, the script will execute in the default user script world. Only valid if `world` is omitted or is `USER_SCRIPT`. Values with leading underscores (`_`) are reserved. * * @since Chrome 133 */ worldId?: string; } export interface UserScriptFilter { /** * {@link getScripts} only returns scripts with the IDs specified in this list. */ ids?: string[]; } /** * @since Chrome 135 */ export interface InjectionTarget { /** * Whether the script should inject into all frames within the tab. Defaults to false. This must not be true if `frameIds` is specified. */ allFrames?: boolean; /** * The IDs of specific documentIds to inject into. This must not be set if `frameIds` is set. */ documentIds?: string[]; /** * The IDs of specific frames to inject into. */ frameIds?: number[]; /** * The ID of the tab into which to inject. */ tabId: number; } /** * @since Chrome 135 */ export interface InjectionResult { /** * The document associated with the injection. */ documentId: string; /** * The frame associated with the injection. */ frameId: number; /** * The result of the script execution. */ result?: any; /** * The error, if any. `error` and `result` are mutually exclusive. */ error?: string; } /** * @since Chrome 135 */ export interface UserScriptInjection { /** * Whether the injection should be triggered in the target as soon as possible. Note that this is not a guarantee that injection will occur prior to page load, as the page may have already loaded by the time the script reaches the target. */ injectImmediately?: boolean; /** * The list of ScriptSource objects defining sources of scripts to be injected into the target. */ js: ScriptSource[]; /** * Details specifying the target into which to inject the script. */ target: InjectionTarget; /** * The JavaScript "world" to run the script in. The default is `USER_SCRIPT`. */ world?: ExecutionWorld; /** * Specifies the user script world ID to execute in. If omitted, the script will execute in the default user script world. Only valid if `world` is omitted or is `USER_SCRIPT`. Values with leading underscores (`_`) are reserved. */ worldId?: string; } export interface WorldProperties { /** * Specifies the ID of the specific user script world to update. If not provided, updates the properties of the default user script world. Values with leading underscores (`_`) are reserved. * * @since Chrome 133 */ worldId?: string; /** * Specifies the world csp. The default is the `` `ISOLATED` `` world csp. */ csp?: string; /** * Specifies whether messaging APIs are exposed. The default is `false`. */ messaging?: boolean; } /** * Registers one or more user scripts for this extension. * * @param scripts Contains a list of user scripts to be registered. * @returns Promise that resolves once scripts have been fully registered. The promise will be rejected if an error occurs. */ export function register( scripts: RegisteredUserScript[], ): Promise; /** * Registers one or more user scripts for this extension. * * @param scripts Contains a list of user scripts to be registered. */ export function register( scripts: RegisteredUserScript[], callback?: () => void, ): void; /** * Returns all dynamically-registered user scripts for this extension. * * @param filter If specified, this method returns only the user scripts that match it. * @returns Promise that resolves with the registered scripts. The promise will be rejected if an error occurs. */ export function getScripts( filter?: UserScriptFilter, ): Promise; /** * Returns all dynamically-registered user scripts for this extension. * * @param filter If specified, this method returns only the user scripts that match it. */ export function getScripts( filter?: UserScriptFilter, callback?: ( scripts: RegisteredUserScript[], ) => void, ): void; /** * Unregisters all dynamically-registered user scripts for this extension. * * @param filter If specified, this method unregisters only the user scripts that match it. * @returns Promise that resolves once scripts have been fully unregistered. The promise will be rejected if an error occurs. */ export function unregister( filter?: UserScriptFilter, ): Promise; /** * Unregisters all dynamically-registered user scripts for this extension. * * @param filter If specified, this method unregisters only the user scripts that match it. */ export function unregister( filter?: UserScriptFilter, callback?: () => void, ): void; /** * Updates one or more user scripts for this extension. * * @param scripts Contains a list of user scripts to be updated. A property is only updated for the existing script if it is specified in this object. If there are errors during script parsing/file validation, or if the IDs specified do not correspond to a fully registered script, then no scripts are updated. * @returns Promise that resolves once scripts have been fully updated. The promise will be rejected if an error occurs. */ export function update( scripts: RegisteredUserScript[], ): Promise; /** * Updates one or more user scripts for this extension. * * @param scripts Contains a list of user scripts to be updated. A property is only updated for the existing script if it is specified in this object. If there are errors during script parsing/file validation, or if the IDs specified do not correspond to a fully registered script, then no scripts are updated. */ export function update( scripts: RegisteredUserScript[], callback?: () => void, ): void; /** * Injects a script into a target context. By default, the script will be run at `document_idle`, or immediately if the page has already loaded. If the `injectImmediately` property is set, the script will inject without waiting, even if the page has not finished loading. If the script evaluates to a promise, the browser will wait for the promise to settle and return the resulting value. * * @since Chrome 135 */ export function execute( injection: UserScriptInjection, ): Promise; /** * Injects a script into a target context. By default, the script will be run at `document_idle`, or immediately if the page has already loaded. If the `injectImmediately` property is set, the script will inject without waiting, even if the page has not finished loading. If the script evaluates to a promise, the browser will wait for the promise to settle and return the resulting value. * * @since Chrome 135 */ export function execute( injection: UserScriptInjection, callback?: ( result: InjectionResult[], ) => void, ): void; /** * Configures the `` `USER_SCRIPT` `` execution environment. * * @param properties Contains the user script world configuration. * @returns Promise that resolves once the world has been configured. */ export function configureWorld( properties: WorldProperties, ): Promise; /** * Configures the `` `USER_SCRIPT` `` execution environment. * * @param properties Contains the user script world configuration. */ export function configureWorld( properties: WorldProperties, callback?: () => void, ): void; /** * Retrieves all registered world configurations. * * @returns Promise that resolves with the registered world configurations. * @since Chrome 133 */ export function getWorldConfigurations(): Promise; /** * Retrieves all registered world configurations. * * @since Chrome 133 */ export function getWorldConfigurations( callback?: ( worlds: WorldProperties[], ) => void, ): void; /** * Resets the configuration for a user script world. Any scripts that inject into the world with the specified ID will use the default world configuration. * * @param worldId The ID of the user script world to reset. If omitted, resets the default world's configuration. * @returns Promise that resolves when the configuration is reset. * @since Chrome 133 */ export function resetWorldConfiguration( worldId?: string, ): Promise; /** * Resets the configuration for a user script world. Any scripts that inject into the world with the specified ID will use the default world configuration. * * @param worldId The ID of the user script world to reset. If omitted, resets the default world's configuration. * @since Chrome 133 */ export function resetWorldConfiguration( worldId?: string, callback?: () => void, ): void; } /** * The `chrome.virtualKeyboard` API is a kiosk only API used to configure virtual keyboard layout and behavior in kiosk sessions. * * @since Chrome 58 * @chrome-permission virtualKeyboard * @chrome-platform-apps * @chrome-platform chromeos */ export namespace virtualKeyboard { export interface FeatureRestrictions { /** * Whether virtual keyboards can provide auto-complete. */ autoCompleteEnabled?: boolean; /** * Whether virtual keyboards can provide auto-correct. */ autoCorrectEnabled?: boolean; /** * Whether virtual keyboards can provide input via handwriting recognition. */ handwritingEnabled?: boolean; /** * Whether virtual keyboards can provide spell-check. */ spellCheckEnabled?: boolean; /** * Whether virtual keyboards can provide voice input. */ voiceInputEnabled?: boolean; } /** * Sets restrictions on features provided by the virtual keyboard. * * @chrome-returns-extra since Chrome 96 * @param restrictions the preferences to enabled/disabled virtual keyboard features. */ export function restrictFeatures( restrictions: FeatureRestrictions, ): Promise; /** * Sets restrictions on features provided by the virtual keyboard. * * @param restrictions the preferences to enabled/disabled virtual keyboard features. */ export function restrictFeatures( restrictions: FeatureRestrictions, callback?: ( /** * @since Chrome 63 */ update: FeatureRestrictions, ) => void, ): void; } /** * Use the `chrome.vpnProvider` API to implement a VPN client. * * @since Chrome 43 * @chrome-permission vpnProvider * @chrome-platform chromeos */ export namespace vpnProvider { export interface Parameters { /** * IP address for the VPN interface in CIDR notation. IPv4 is currently the only supported mode. */ address: string; /** * Broadcast address for the VPN interface. (default: deduced from IP address and mask) */ broadcastAddress?: string; /** * MTU setting for the VPN interface. (default: 1500 bytes) */ mtu?: string; /** * Exclude network traffic to the list of IP blocks in CIDR notation from the tunnel. This can be used to bypass traffic to and from the VPN server. When many rules match a destination, the rule with the longest matching prefix wins. Entries that correspond to the same CIDR block are treated as duplicates. Such duplicates in the collated (exclusionList + inclusionList) list are eliminated and the exact duplicate entry that will be eliminated is undefined. */ exclusionList: string[]; /** * Include network traffic to the list of IP blocks in CIDR notation to the tunnel. This parameter can be used to set up a split tunnel. By default no traffic is directed to the tunnel. Adding the entry "0.0.0.0/0" to this list gets all the user traffic redirected to the tunnel. When many rules match a destination, the rule with the longest matching prefix wins. Entries that correspond to the same CIDR block are treated as duplicates. Such duplicates in the collated (exclusionList + inclusionList) list are eliminated and the exact duplicate entry that will be eliminated is undefined. */ inclusionList: string[]; /** * A list of search domains. (default: no search domain) */ domainSearch?: string[]; /** * A list of IPs for the DNS servers. */ dnsServers: string[]; /** * Whether or not the VPN extension implements auto-reconnection. * * If true, the `linkDown`, `linkUp`, `linkChanged`, `suspend`, and `resume` platform messages will be used to signal the respective events. If false, the system will forcibly disconnect the VPN if the network topology changes, and the user will need to reconnect manually. (default: false) * * This property is new in Chrome 51; it will generate an exception in earlier versions. try/catch can be used to conditionally enable the feature based on browser support. * * @since Chrome 51 */ reconnect?: string; } /** * The enum is used by the platform to notify the client of the VPN session status. * * @chrome-enum "connected" Indicates that the VPN configuration connected. * @chrome-enum "disconnected" Indicates that the VPN configuration disconnected. * @chrome-enum "error" Indicates that an error occurred in VPN connection, for example a timeout. A description of the error is given as the {@link onPlatformMessage.error error argument to onPlatformMessage}. * @chrome-enum "linkDown" Indicates that the default physical network connection is down. * @chrome-enum "linkUp" Indicates that the default physical network connection is back up. * @chrome-enum "linkChanged" Indicates that the default physical network connection changed, e.g. wifi->mobile. * @chrome-enum "suspend" Indicates that the OS is preparing to suspend, so the VPN should drop its connection. The extension is not guaranteed to receive this event prior to suspending. * @chrome-enum "resume" Indicates that the OS has resumed and the user has logged back in, so the VPN should try to reconnect. */ export type PlatformMessage = "connected" | "disconnected" | "error" | "linkDown" | "linkUp" | "linkChanged" | "suspend" | "resume"; /** * The enum is used by the VPN client to inform the platform of its current state. This helps provide meaningful messages to the user. * * @chrome-enum "connected" Specifies that VPN connection was successful. * @chrome-enum "failure" Specifies that VPN connection has failed. */ export type VpnConnectionState = "connected" | "failure"; /** * The enum is used by the platform to indicate the event that triggered `onUIEvent`. * * @chrome-enum "showAddDialog" Requests that the VPN client show the add configuration dialog box to the user. * @chrome-enum "showConfigureDialog" Requests that the VPN client show the configuration settings dialog box to the user. */ export type UIEvent = "showAddDialog" | "showConfigureDialog"; /** * Triggered when a message is received from the platform for a VPN configuration owned by the extension. */ export const onPlatformMessage: events.Event<( id: string, message: PlatformMessage, error: string, ) => void>; /** * Triggered when an IP packet is received via the tunnel for the VPN session owned by the extension. */ export const onPacketReceived: events.Event<( data: ArrayBuffer, ) => void>; /** * Triggered when a configuration created by the extension is removed by the platform. */ export const onConfigRemoved: events.Event<( id: string, ) => void>; /** * Triggered when a configuration is created by the platform for the extension. */ export const onConfigCreated: events.Event<( id: string, name: string, data: {[name: string]: any}, ) => void>; /** * Triggered when there is a UI event for the extension. UI events are signals from the platform that indicate to the app that a UI dialog needs to be shown to the user. */ export const onUIEvent: events.Event<( event: UIEvent, id?: string, ) => void>; /** * Creates a new VPN configuration that persists across multiple login sessions of the user. * * @chrome-returns-extra since Chrome 96 * @param name The name of the VPN configuration. * @returns Returns a Promise which resolves when the configuration is created or rejects if there is an error. */ export function createConfig( name: string, ): Promise; /** * Creates a new VPN configuration that persists across multiple login sessions of the user. * * @param name The name of the VPN configuration. */ export function createConfig( name: string, /** * @param id A unique ID for the created configuration, or `undefined` on failure. */ callback?: ( id: string, ) => void, ): void; /** * Destroys a VPN configuration created by the extension. * * @chrome-returns-extra since Chrome 96 * @param id ID of the VPN configuration to destroy. * @returns Returns a Promise which resolves when the configuration is destroyed or rejects if there is an error. */ export function destroyConfig( id: string, ): Promise; /** * Destroys a VPN configuration created by the extension. * * @param id ID of the VPN configuration to destroy. */ export function destroyConfig( id: string, callback?: () => void, ): void; /** * Sets the parameters for the VPN session. This should be called immediately after `"connected"` is received from the platform. This will succeed only when the VPN session is owned by the extension. * * @chrome-returns-extra since Chrome 96 * @param parameters The parameters for the VPN session. * @returns Returns a Promise which resolves when the parameters are set or rejects if there is an error. */ export function setParameters( parameters: Parameters, ): Promise; /** * Sets the parameters for the VPN session. This should be called immediately after `"connected"` is received from the platform. This will succeed only when the VPN session is owned by the extension. * * @param parameters The parameters for the VPN session. */ export function setParameters( parameters: Parameters, callback?: () => void, ): void; /** * Sends an IP packet through the tunnel created for the VPN session. This will succeed only when the VPN session is owned by the extension. * * @chrome-returns-extra since Chrome 96 * @param data The IP packet to be sent to the platform. * @returns Returns a Promise which resolves when the packet is sent or rejects if there is an error. */ export function sendPacket( data: ArrayBuffer, ): Promise; /** * Sends an IP packet through the tunnel created for the VPN session. This will succeed only when the VPN session is owned by the extension. * * @param data The IP packet to be sent to the platform. */ export function sendPacket( data: ArrayBuffer, callback?: () => void, ): void; /** * Notifies the VPN session state to the platform. This will succeed only when the VPN session is owned by the extension. * * @chrome-returns-extra since Chrome 96 * @param state The VPN session state of the VPN client. * @returns Returns a Promise which resolves when the notification is complete or rejects if there is an error. */ export function notifyConnectionStateChanged( state: VpnConnectionState, ): Promise; /** * Notifies the VPN session state to the platform. This will succeed only when the VPN session is owned by the extension. * * @param state The VPN session state of the VPN client. */ export function notifyConnectionStateChanged( state: VpnConnectionState, callback?: () => void, ): void; } /** * Use the `chrome.wallpaper` API to change the ChromeOS wallpaper. * * @since Chrome 43 * @chrome-permission wallpaper * @chrome-platform chromeos */ export namespace wallpaper { /** * The supported wallpaper layouts. * * @since Chrome 44 */ export type WallpaperLayout = "STRETCH" | "CENTER" | "CENTER_CROPPED"; /** * Sets wallpaper to the image at _url_ or _wallpaperData_ with the specified _layout_ * * @chrome-returns-extra since Chrome 96 */ export function setWallpaper( details: { /** * The jpeg or png encoded wallpaper image as an ArrayBuffer. */ data?: ArrayBuffer, /** * The URL of the wallpaper to be set (can be relative). */ url?: string, /** * The supported wallpaper layouts. */ layout: WallpaperLayout, /** * The file name of the saved wallpaper. */ filename: string, /** * True if a 128x60 thumbnail should be generated. Layout and ratio are not supported yet. */ thumbnail?: boolean, }, ): Promise; /** * Sets wallpaper to the image at _url_ or _wallpaperData_ with the specified _layout_ */ export function setWallpaper( details: { /** * The jpeg or png encoded wallpaper image as an ArrayBuffer. */ data?: ArrayBuffer, /** * The URL of the wallpaper to be set (can be relative). */ url?: string, /** * The supported wallpaper layouts. */ layout: WallpaperLayout, /** * The file name of the saved wallpaper. */ filename: string, /** * True if a 128x60 thumbnail should be generated. Layout and ratio are not supported yet. */ thumbnail?: boolean, }, /** * @param thumbnail The jpeg encoded wallpaper thumbnail. It is generated by resizing the wallpaper to 128x60. */ callback?: ( thumbnail?: ArrayBuffer, ) => void, ): void; } /** * Stub namespace for the "web\_accessible\_resources" manifest key. * * @since Chrome 90 */ export namespace webAccessibleResources { export interface WebAccessibleResource { /** * Relative paths within the extension package representing web accessible resources. */ resources: string[]; /** * List of [match patterns](https://developer.chrome.com/docs/extensions/develop/concepts/match-patterns) to which "resources" are accessible. These patterns should have an effective path of "\*". Each match will be checked against the initiating origin. */ matches?: string[]; /** * List of extension IDs the "resources" are accessible to. A wildcard can be used, denoted by "\*". */ extension_ids?: string[]; /** * If true, the web accessible resources will only be accessible through a dynamic ID. This is an identifier that uniquely identifies the extension and is generated each session. The corresponding dynamic extension URL is available through {@link runtime.getURL}. Dynamic resources can be loaded regardless of the value. However, if true, resources can only be loaded using the dynamic URL. */ use_dynamic_url?: boolean; } } /** * The `chrome.webAuthenticationProxy` API lets remote desktop software running on a remote host intercept Web Authentication API (WebAuthn) requests in order to handle them on a local client. * * @since Chrome 115 * @chrome-permission webAuthenticationProxy * @chrome-min-manifest MV3 * @chrome-platform desktop_android * @chrome-platform linux * @chrome-platform mac * @chrome-platform win */ export namespace webAuthenticationProxy { export interface IsUvpaaRequest { /** * An opaque identifier for the request. */ requestId: number; } export interface CreateRequest { /** * An opaque identifier for the request. */ requestId: number; /** * The `PublicKeyCredentialCreationOptions` passed to `navigator.credentials.create()`, serialized as a JSON string. The serialization format is compatible with [`PublicKeyCredential.parseCreationOptionsFromJSON()`](https://w3c.github.io/webauthn/#sctn-parseCreationOptionsFromJSON). */ requestDetailsJson: string; } export interface GetRequest { /** * An opaque identifier for the request. */ requestId: number; /** * The `PublicKeyCredentialRequestOptions` passed to `navigator.credentials.get()`, serialized as a JSON string. The serialization format is compatible with [`PublicKeyCredential.parseRequestOptionsFromJSON()`](https://w3c.github.io/webauthn/#sctn-parseRequestOptionsFromJSON). */ requestDetailsJson: string; } export interface DOMExceptionDetails { name: string; message: string; } export interface CreateResponseDetails { /** * The `requestId` of the `CreateRequest`. */ requestId: number; /** * The `DOMException` yielded by the remote request, if any. */ error?: DOMExceptionDetails; /** * The `PublicKeyCredential`, yielded by the remote request, if any, serialized as a JSON string by calling href="https://w3c.github.io/webauthn/#dom-publickeycredential-tojson"> `PublicKeyCredential.toJSON()`. */ responseJson?: string; } export interface GetResponseDetails { /** * The `requestId` of the `CreateRequest`. */ requestId: number; /** * The `DOMException` yielded by the remote request, if any. */ error?: DOMExceptionDetails; /** * The `PublicKeyCredential`, yielded by the remote request, if any, serialized as a JSON string by calling href="https://w3c.github.io/webauthn/#dom-publickeycredential-tojson"> `PublicKeyCredential.toJSON()`. */ responseJson?: string; } export interface IsUvpaaResponseDetails { requestId: number; isUvpaa: boolean; } /** * A native application associated with this extension can cause this event to be fired by writing to a file with a name equal to the extension's ID in a directory named `WebAuthenticationProxyRemoteSessionStateChange` inside the [default user data directory](https://chromium.googlesource.com/chromium/src/+/main/docs/user_data_dir.md#default-location) * * The contents of the file should be empty. I.e., it is not necessary to change the contents of the file in order to trigger this event. * * The native host application may use this event mechanism to signal a possible remote session state change (i.e. from detached to attached, or vice versa) while the extension service worker is possibly suspended. In the handler for this event, the extension can call the `attach()` or `detach()` API methods accordingly. * * The event listener must be registered synchronously at load time. */ export const onRemoteSessionStateChange: events.Event<() => void>; /** * Fires when a WebAuthn `navigator.credentials.create()` call occurs. The extension must supply a response by calling `completeCreateRequest()` with the `requestId` from `requestInfo`. */ export const onCreateRequest: events.Event<( requestInfo: CreateRequest, ) => void>; /** * Fires when a WebAuthn navigator.credentials.get() call occurs. The extension must supply a response by calling `completeGetRequest()` with the `requestId` from `requestInfo` */ export const onGetRequest: events.Event<( requestInfo: GetRequest, ) => void>; /** * Fires when a `PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable()` call occurs. The extension must supply a response by calling `completeIsUvpaaRequest()` with the `requestId` from `requestInfo` */ export const onIsUvpaaRequest: events.Event<( requestInfo: IsUvpaaRequest, ) => void>; /** * Fires when a `onCreateRequest` or `onGetRequest` event is canceled (because the WebAuthn request was aborted by the caller, or because it timed out). When receiving this event, the extension should cancel processing of the corresponding request on the client side. Extensions cannot complete a request once it has been canceled. */ export const onRequestCanceled: events.Event<( requestId: number, ) => void>; /** * Reports the result of a `navigator.credentials.create()` call. The extension must call this for every `onCreateRequest` event it has received, unless the request was canceled (in which case, an `onRequestCanceled` event is fired). */ export function completeCreateRequest( details: CreateResponseDetails, ): Promise; /** * Reports the result of a `navigator.credentials.create()` call. The extension must call this for every `onCreateRequest` event it has received, unless the request was canceled (in which case, an `onRequestCanceled` event is fired). */ export function completeCreateRequest( details: CreateResponseDetails, callback?: () => void, ): void; /** * Reports the result of a `navigator.credentials.get()` call. The extension must call this for every `onGetRequest` event it has received, unless the request was canceled (in which case, an `onRequestCanceled` event is fired). */ export function completeGetRequest( details: GetResponseDetails, ): Promise; /** * Reports the result of a `navigator.credentials.get()` call. The extension must call this for every `onGetRequest` event it has received, unless the request was canceled (in which case, an `onRequestCanceled` event is fired). */ export function completeGetRequest( details: GetResponseDetails, callback?: () => void, ): void; /** * Reports the result of a `PublicKeyCredential.isUserVerifyingPlatformAuthenticator()` call. The extension must call this for every `onIsUvpaaRequest` event it has received. */ export function completeIsUvpaaRequest( details: IsUvpaaResponseDetails, ): Promise; /** * Reports the result of a `PublicKeyCredential.isUserVerifyingPlatformAuthenticator()` call. The extension must call this for every `onIsUvpaaRequest` event it has received. */ export function completeIsUvpaaRequest( details: IsUvpaaResponseDetails, callback?: () => void, ): void; /** * Makes this extension the active Web Authentication API request proxy. * * Remote desktop extensions typically call this method after detecting attachment of a remote session to this host. Once this method returns without error, regular processing of WebAuthn requests is suspended, and events from this extension API are raised. * * This method fails with an error if a different extension is already attached. * * The attached extension must call `detach()` once the remote desktop session has ended in order to resume regular WebAuthn request processing. Extensions automatically become detached if they are unloaded. * * Refer to the `onRemoteSessionStateChange` event for signaling a change of remote session attachment from a native application to to the (possibly suspended) extension. */ export function attach(): Promise; /** * Makes this extension the active Web Authentication API request proxy. * * Remote desktop extensions typically call this method after detecting attachment of a remote session to this host. Once this method returns without error, regular processing of WebAuthn requests is suspended, and events from this extension API are raised. * * This method fails with an error if a different extension is already attached. * * The attached extension must call `detach()` once the remote desktop session has ended in order to resume regular WebAuthn request processing. Extensions automatically become detached if they are unloaded. * * Refer to the `onRemoteSessionStateChange` event for signaling a change of remote session attachment from a native application to to the (possibly suspended) extension. */ export function attach( callback?: ( error?: string, ) => void, ): void; /** * Removes this extension from being the active Web Authentication API request proxy. * * This method is typically called when the extension detects that a remote desktop session was terminated. Once this method returns, the extension ceases to be the active Web Authentication API request proxy. * * Refer to the `onRemoteSessionStateChange` event for signaling a change of remote session attachment from a native application to to the (possibly suspended) extension. */ export function detach(): Promise; /** * Removes this extension from being the active Web Authentication API request proxy. * * This method is typically called when the extension detects that a remote desktop session was terminated. Once this method returns, the extension ceases to be the active Web Authentication API request proxy. * * Refer to the `onRemoteSessionStateChange` event for signaling a change of remote session attachment from a native application to to the (possibly suspended) extension. */ export function detach( callback?: ( error?: string, ) => void, ): void; } /** * Use the `chrome.webNavigation` API to receive notifications about the status of navigation requests in-flight. * * @chrome-permission webNavigation */ export namespace webNavigation { /** * Cause of the navigation. The same transition types as defined in the history API are used. These are the same transition types as defined in the [history API](https://developer.chrome.com/docs/extensions/reference/history/#transition_types) except with `"start_page"` in place of `"auto_toplevel"` (for backwards compatibility). * * @since Chrome 44 */ export type TransitionType = "link" | "typed" | "auto_bookmark" | "auto_subframe" | "manual_subframe" | "generated" | "start_page" | "form_submit" | "reload" | "keyword" | "keyword_generated"; /** * @since Chrome 44 */ export type TransitionQualifier = "client_redirect" | "server_redirect" | "forward_back" | "from_address_bar"; /** * Fired when a navigation is about to occur. */ export const onBeforeNavigate: CustomChromeEvent<( callback: ( details: { /** * The ID of the tab in which the navigation is about to occur. */ tabId: number, url: string, /** * The value of -1. * * @deprecated The processId is no longer set for this event, since the process which will render the resulting document is not known until onCommit. * @chrome-deprecated-since Chrome 50 */ processId: number, /** * 0 indicates the navigation happens in the tab content window; a positive value indicates navigation in a subframe. Frame IDs are unique for a given tab and process. */ frameId: number, /** * The ID of the parent frame, or `-1` if this is the main frame. */ parentFrameId: number, /** * The time when the browser was about to start the navigation, in milliseconds since the epoch. */ timeStamp: number, /** * A UUID of the parent document owning this frame. This is not set if there is no parent. * * @since Chrome 106 */ parentDocumentId?: string, /** * The lifecycle the document is in. * * @since Chrome 106 */ documentLifecycle: extensionTypes.DocumentLifecycle, /** * The type of frame the navigation occurred in. * * @since Chrome 106 */ frameType: extensionTypes.FrameType, }, ) => void, filters?: { /** * Conditions that the URL being navigated to must satisfy. The 'schemes' and 'ports' fields of UrlFilter are ignored for this event. */ url: events.UrlFilter[], }, ) => void>; /** * Fired when a navigation is committed. The document (and the resources it refers to, such as images and subframes) might still be downloading, but at least part of the document has been received from the server and the browser has decided to switch to the new document. */ export const onCommitted: CustomChromeEvent<( callback: ( details: { /** * The ID of the tab in which the navigation occurs. */ tabId: number, url: string, /** * The ID of the process that runs the renderer for this frame. */ processId: number, /** * 0 indicates the navigation happens in the tab content window; a positive value indicates navigation in a subframe. Frame IDs are unique within a tab. */ frameId: number, /** * The ID of the parent frame, or `-1` if this is the main frame. * * @since Chrome 74 */ parentFrameId: number, /** * Cause of the navigation. */ transitionType: TransitionType, /** * A list of transition qualifiers. */ transitionQualifiers: TransitionQualifier[], /** * The time when the navigation was committed, in milliseconds since the epoch. */ timeStamp: number, /** * A UUID of the document loaded. * * @since Chrome 106 */ documentId: string, /** * A UUID of the parent document owning this frame. This is not set if there is no parent. * * @since Chrome 106 */ parentDocumentId?: string, /** * The lifecycle the document is in. * * @since Chrome 106 */ documentLifecycle: extensionTypes.DocumentLifecycle, /** * The type of frame the navigation occurred in. * * @since Chrome 106 */ frameType: extensionTypes.FrameType, }, ) => void, filters?: { /** * Conditions that the URL being navigated to must satisfy. The 'schemes' and 'ports' fields of UrlFilter are ignored for this event. */ url: events.UrlFilter[], }, ) => void>; /** * Fired when the page's DOM is fully constructed, but the referenced resources may not finish loading. */ export const onDOMContentLoaded: CustomChromeEvent<( callback: ( details: { /** * The ID of the tab in which the navigation occurs. */ tabId: number, url: string, /** * The ID of the process that runs the renderer for this frame. */ processId: number, /** * 0 indicates the navigation happens in the tab content window; a positive value indicates navigation in a subframe. Frame IDs are unique within a tab. */ frameId: number, /** * The ID of the parent frame, or `-1` if this is the main frame. * * @since Chrome 74 */ parentFrameId: number, /** * The time when the page's DOM was fully constructed, in milliseconds since the epoch. */ timeStamp: number, /** * A UUID of the document loaded. * * @since Chrome 106 */ documentId: string, /** * A UUID of the parent document owning this frame. This is not set if there is no parent. * * @since Chrome 106 */ parentDocumentId?: string, /** * The lifecycle the document is in. * * @since Chrome 106 */ documentLifecycle: extensionTypes.DocumentLifecycle, /** * The type of frame the navigation occurred in. * * @since Chrome 106 */ frameType: extensionTypes.FrameType, }, ) => void, filters?: { /** * Conditions that the URL being navigated to must satisfy. The 'schemes' and 'ports' fields of UrlFilter are ignored for this event. */ url: events.UrlFilter[], }, ) => void>; /** * Fired when a document, including the resources it refers to, is completely loaded and initialized. */ export const onCompleted: CustomChromeEvent<( callback: ( details: { /** * The ID of the tab in which the navigation occurs. */ tabId: number, url: string, /** * The ID of the process that runs the renderer for this frame. */ processId: number, /** * 0 indicates the navigation happens in the tab content window; a positive value indicates navigation in a subframe. Frame IDs are unique within a tab. */ frameId: number, /** * The ID of the parent frame, or `-1` if this is the main frame. * * @since Chrome 74 */ parentFrameId: number, /** * The time when the document finished loading, in milliseconds since the epoch. */ timeStamp: number, /** * A UUID of the document loaded. * * @since Chrome 106 */ documentId: string, /** * A UUID of the parent document owning this frame. This is not set if there is no parent. * * @since Chrome 106 */ parentDocumentId?: string, /** * The lifecycle the document is in. * * @since Chrome 106 */ documentLifecycle: extensionTypes.DocumentLifecycle, /** * The type of frame the navigation occurred in. * * @since Chrome 106 */ frameType: extensionTypes.FrameType, }, ) => void, filters?: { /** * Conditions that the URL being navigated to must satisfy. The 'schemes' and 'ports' fields of UrlFilter are ignored for this event. */ url: events.UrlFilter[], }, ) => void>; /** * Fired when an error occurs and the navigation is aborted. This can happen if either a network error occurred, or the user aborted the navigation. */ export const onErrorOccurred: CustomChromeEvent<( callback: ( details: { /** * The ID of the tab in which the navigation occurs. */ tabId: number, url: string, /** * The value of -1. * * @deprecated The processId is no longer set for this event. * @chrome-deprecated-since Chrome 50 */ processId: number, /** * 0 indicates the navigation happens in the tab content window; a positive value indicates navigation in a subframe. Frame IDs are unique within a tab. */ frameId: number, /** * The ID of the parent frame, or `-1` if this is the main frame. * * @since Chrome 74 */ parentFrameId: number, /** * The error description. */ error: string, /** * The time when the error occurred, in milliseconds since the epoch. */ timeStamp: number, /** * A UUID of the document loaded. * * @since Chrome 106 */ documentId: string, /** * A UUID of the parent document owning this frame. This is not set if there is no parent. * * @since Chrome 106 */ parentDocumentId?: string, /** * The lifecycle the document is in. * * @since Chrome 106 */ documentLifecycle: extensionTypes.DocumentLifecycle, /** * The type of frame the navigation occurred in. * * @since Chrome 106 */ frameType: extensionTypes.FrameType, }, ) => void, filters?: { /** * Conditions that the URL being navigated to must satisfy. The 'schemes' and 'ports' fields of UrlFilter are ignored for this event. */ url: events.UrlFilter[], }, ) => void>; /** * Fired when a new window, or a new tab in an existing window, is created to host a navigation. */ export const onCreatedNavigationTarget: CustomChromeEvent<( callback: ( details: { /** * The ID of the tab in which the navigation is triggered. */ sourceTabId: number, /** * The ID of the process that runs the renderer for the source frame. */ sourceProcessId: number, /** * The ID of the frame with sourceTabId in which the navigation is triggered. 0 indicates the main frame. */ sourceFrameId: number, /** * The URL to be opened in the new window. */ url: string, /** * The ID of the tab in which the url is opened */ tabId: number, /** * The time when the browser was about to create a new view, in milliseconds since the epoch. */ timeStamp: number, }, ) => void, filters?: { /** * Conditions that the URL being navigated to must satisfy. The 'schemes' and 'ports' fields of UrlFilter are ignored for this event. */ url: events.UrlFilter[], }, ) => void>; /** * Fired when the reference fragment of a frame was updated. All future events for that frame will use the updated URL. */ export const onReferenceFragmentUpdated: CustomChromeEvent<( callback: ( details: { /** * The ID of the tab in which the navigation occurs. */ tabId: number, url: string, /** * The ID of the process that runs the renderer for this frame. */ processId: number, /** * 0 indicates the navigation happens in the tab content window; a positive value indicates navigation in a subframe. Frame IDs are unique within a tab. */ frameId: number, /** * The ID of the parent frame, or `-1` if this is the main frame. * * @since Chrome 74 */ parentFrameId: number, /** * Cause of the navigation. */ transitionType: TransitionType, /** * A list of transition qualifiers. */ transitionQualifiers: TransitionQualifier[], /** * The time when the navigation was committed, in milliseconds since the epoch. */ timeStamp: number, /** * A UUID of the document loaded. * * @since Chrome 106 */ documentId: string, /** * A UUID of the parent document owning this frame. This is not set if there is no parent. * * @since Chrome 106 */ parentDocumentId?: string, /** * The lifecycle the document is in. * * @since Chrome 106 */ documentLifecycle: extensionTypes.DocumentLifecycle, /** * The type of frame the navigation occurred in. * * @since Chrome 106 */ frameType: extensionTypes.FrameType, }, ) => void, filters?: { /** * Conditions that the URL being navigated to must satisfy. The 'schemes' and 'ports' fields of UrlFilter are ignored for this event. */ url: events.UrlFilter[], }, ) => void>; /** * Fired when the contents of the tab is replaced by a different (usually previously pre-rendered) tab. */ export const onTabReplaced: events.Event<( details: { /** * The ID of the tab that was replaced. */ replacedTabId: number, /** * The ID of the tab that replaced the old tab. */ tabId: number, /** * The time when the replacement happened, in milliseconds since the epoch. */ timeStamp: number, }, ) => void>; /** * Fired when the frame's history was updated to a new URL. All future events for that frame will use the updated URL. */ export const onHistoryStateUpdated: CustomChromeEvent<( callback: ( details: { /** * The ID of the tab in which the navigation occurs. */ tabId: number, url: string, /** * The ID of the process that runs the renderer for this frame. */ processId: number, /** * 0 indicates the navigation happens in the tab content window; a positive value indicates navigation in a subframe. Frame IDs are unique within a tab. */ frameId: number, /** * The ID of the parent frame, or `-1` if this is the main frame. * * @since Chrome 74 */ parentFrameId: number, /** * Cause of the navigation. */ transitionType: TransitionType, /** * A list of transition qualifiers. */ transitionQualifiers: TransitionQualifier[], /** * The time when the navigation was committed, in milliseconds since the epoch. */ timeStamp: number, /** * A UUID of the document loaded. * * @since Chrome 106 */ documentId: string, /** * A UUID of the parent document owning this frame. This is not set if there is no parent. * * @since Chrome 106 */ parentDocumentId?: string, /** * The lifecycle the document is in. * * @since Chrome 106 */ documentLifecycle: extensionTypes.DocumentLifecycle, /** * The type of frame the navigation occurred in. * * @since Chrome 106 */ frameType: extensionTypes.FrameType, }, ) => void, filters?: { /** * Conditions that the URL being navigated to must satisfy. The 'schemes' and 'ports' fields of UrlFilter are ignored for this event. */ url: events.UrlFilter[], }, ) => void>; /** * Retrieves information about the given frame. A frame refers to an