///
///
///
// Helpers
type SetRequired = Omit & Required>;
type SetPartial = Omit & Partial>;
////////////////////
// Global object
////////////////////
interface Window {
chrome: typeof chrome;
}
declare namespace chrome {
////////////////////
// Accessibility Features
////////////////////
/**
* Use the `chrome.accessibilityFeatures` API to manage Chrome's accessibility features. This API relies on the ChromeSetting prototype of the type API for getting and setting individual accessibility features. In order to get feature states the extension must request `accessibilityFeatures.read` permission. For modifying feature state, the extension needs `accessibilityFeatures.modify` permission. Note that `accessibilityFeatures.modify` does not imply `accessibilityFeatures.read` permission.
*
* Permissions: "accessibilityFeatures.read", "accessibilityFeatures.modify"
*/
export namespace accessibilityFeatures {
/** `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission. */
export const animationPolicy: chrome.types.ChromeSetting<"allowed" | "once" | "none">;
/**
* Auto mouse click after mouse stops moving. The value indicates whether the feature is enabled or not.
* `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission.
* @platform ChromeOS only
*/
export const autoclick: chrome.types.ChromeSetting;
/**
* Caret highlighting. The value indicates whether the feature is enabled or not.
* `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission.
* @platform ChromeOS only
* @since Chrome 51
*/
export const caretHighlight: chrome.types.ChromeSetting;
/**
* Cursor color. The value indicates whether the feature is enabled or not, doesn't indicate the color of it.
* `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission.
* @platform ChromeOS only
* @since Chrome 85
*/
export const cursorColor: chrome.types.ChromeSetting;
/**
* Cursor highlighting. The value indicates whether the feature is enabled or not.
* `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission.
* @platform ChromeOS only
* @since Chrome 51
*/
export const cursorHighlight: chrome.types.ChromeSetting;
/**
* Dictation. The value indicates whether the feature is enabled or not.
* `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission.
* @platform ChromeOS only
* @since Chrome 90
*/
export const dictation: chrome.types.ChromeSetting;
/**
* Docked magnifier. The value indicates whether docked magnifier feature is enabled or not.
* `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission.
* @platform ChromeOS only
* @since Chrome 87
*/
export const dockedMagnifier: chrome.types.ChromeSetting;
/**
* Focus highlighting. The value indicates whether the feature is enabled or not.
* `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission.
* @platform ChromeOS only
* @since Chrome 51
*/
export const focusHighlight: chrome.types.ChromeSetting;
/**
* High contrast rendering mode. The value indicates whether the feature is enabled or not.
* `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission.
* @platform ChromeOS only
*/
export const highContrast: chrome.types.ChromeSetting;
/**
* Enlarged cursor. The value indicates whether the feature is enabled or not.
* `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission.
* @platform ChromeOS only
*/
export const largeCursor: chrome.types.ChromeSetting;
/**
* Full screen magnification. The value indicates whether the feature is enabled or not.
* `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission.
* @platform ChromeOS only
*/
export const screenMagnifier: chrome.types.ChromeSetting;
/**
* Select-to-speak. The value indicates whether the feature is enabled or not.
* `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission.
* @platform ChromeOS only
* @since Chrome 51
*/
export const selectToSpeak: chrome.types.ChromeSetting;
/**
* Spoken feedback (text-to-speech). The value indicates whether the feature is enabled or not.
* `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission.
* @platform ChromeOS only
*/
export const spokenFeedback: chrome.types.ChromeSetting;
/**
* Sticky modifier keys (like shift or alt). The value indicates whether the feature is enabled or not.
* `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission.
* @platform ChromeOS only
*/
export const stickyKeys: chrome.types.ChromeSetting;
/**
* Switch Access. The value indicates whether the feature is enabled or not.
* `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission.
* @platform ChromeOS only
* @since Chrome 51
*/
export const switchAccess: chrome.types.ChromeSetting;
/**
* Virtual on-screen keyboard. The value indicates whether the feature is enabled or not.
* `get()` requires `accessibilityFeatures.read` permission. `set()` and `clear()` require `accessibilityFeatures.modify` permission.
* @platform ChromeOS only
*/
export const virtualKeyboard: chrome.types.ChromeSetting;
}
////////////////////
// Action
////////////////////
/**
* Use the `chrome.action` API to control the extension's icon in the Google Chrome toolbar.
* The action icons are displayed in the browser toolbar next to the omnibox. After installation, these appear in the extensions menu (the puzzle piece icon). Users can pin your extension icon to the toolbar.
*
* Manifest: "action"
* @since Chrome 88, MV3
*/
export namespace action {
export interface BadgeColorDetails {
/** An array of four integers in the range [0,255] that make up the RGBA color of the badge. For example, opaque red is `[255, 0, 0, 255]`. Can also be a string with a CSS value, with opaque red being `#FF0000` or `#F00`. */
color: string | extensionTypes.ColorArray;
/** Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */
tabId?: number | undefined;
}
export interface BadgeTextDetails {
/** Any number of characters can be passed, but only about four can fit in the space. If an empty string (`''`) is passed, the badge text is cleared. If `tabId` is specified and `text` is null, the text for the specified tab is cleared and defaults to the global badge text. */
text?: string | undefined;
/** Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */
tabId?: number | undefined;
}
export interface TitleDetails {
/** The string the action should display when moused over. */
title: string;
/** Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */
tabId?: number | undefined;
}
export interface PopupDetails {
/** Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */
tabId?: number | undefined;
/** The html file to show in a popup. If set to the empty string (`''`), no popup is shown. */
popup: string;
}
export interface TabIconDetails {
/** Either a relative image path or a dictionary {size -> relative image path} pointing to icon to be set. If the icon is specified as a dictionary, the actual image to be used is chosen depending on screen's pixel density. If the number of image pixels that fit into one screen space unit equals `scale`, then image with size `scale` \* n will be selected, where n is the size of the icon in the UI. At least one image must be specified. Note that 'details.path = foo' is equivalent to 'details.path = {'16': foo}' */
path?: string | { [index: number]: string } | undefined;
/** Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */
tabId?: number | undefined;
/** Either an ImageData object or a dictionary {size -> ImageData} representing icon to be set. If the icon is specified as a dictionary, the actual image to be used is chosen depending on screen's pixel density. If the number of image pixels that fit into one screen space unit equals `scale`, then image with size `scale` \* n will be selected, where n is the size of the icon in the UI. At least one image must be specified. Note that 'details.imageData = foo' is equivalent to 'details.imageData = {'16': foo}' */
imageData?: ImageData | { [index: number]: ImageData } | undefined;
}
/** @since Chrome 99 */
export interface OpenPopupOptions {
/** The id of the window to open the action popup in. Defaults to the currently-active window if unspecified. */
windowId?: number | undefined;
}
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 | undefined;
}
/**
* 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;
}
/**
* Disables the action for a tab.
* @param tabId The ID of the tab for which you want to modify the action.
*
* Can return its result via Promise.
*/
export function disable(tabId?: number): Promise;
export function disable(callback: () => void): void;
export function disable(tabId: number | undefined, callback: () => void): void;
/**
* Enables the action for a tab. By default, actions are enabled.
* @param tabId The ID of the tab for which you want to modify the action.
*
* Can return its result via Promise.
*/
export function enable(tabId?: number): Promise;
export function enable(callback: () => void): void;
export function enable(tabId: number | undefined, callback: () => void): void;
/**
* Gets the background color of the action.
*
* Can return its result via Promise.
*/
export function getBadgeBackgroundColor(details: TabDetails): Promise;
export function getBadgeBackgroundColor(
details: TabDetails,
callback: (result: extensionTypes.ColorArray) => void,
): void;
/**
* Gets the badge text of the action. If no tab is specified, the non-tab-specific badge text is returned. If {@link declarativeNetRequest.ExtensionActionOptions.displayActionCountAsBadgeText displayActionCountAsBadgeText} is enabled, a placeholder text will be returned unless the {@link runtime.ManifestPermission declarativeNetRequestFeedback} permission is present or tab-specific badge text was provided.
*
* Can return its result via Promise.
*/
export function getBadgeText(details: TabDetails): Promise;
export function getBadgeText(details: TabDetails, callback: (result: string) => void): void;
/**
* Gets the text color of the action.
*
* Can return its result via Promise.
* @since Chrome 110
*/
export function getBadgeTextColor(details: TabDetails): Promise;
export function getBadgeTextColor(
details: TabDetails,
callback: (result: extensionTypes.ColorArray) => void,
): void;
/**
* Gets the html document set as the popup for this action.
*
* Can return its result via Promise.
*/
export function getPopup(details: TabDetails): Promise;
export function getPopup(details: TabDetails, callback: (result: string) => void): void;
/**
* Gets the title of the action.
*
* Can return its result via Promise.
*/
export function getTitle(details: TabDetails): Promise;
export function getTitle(details: TabDetails, callback: (result: string) => void): void;
/**
* Returns the user-specified settings relating to an extension's action.
*
* Can return its result via Promise.
* @since Chrome 91
*/
export function getUserSettings(): Promise;
export function getUserSettings(callback: (userSettings: UserSettings) => void): void;
/**
* Indicates whether the extension action is enabled for a tab (or globally if no `tabId` is provided). Actions enabled using only {@link declarativeContent} always return false.
*
* Can return its result via Promise.
* @since Chrome 110
*/
export function isEnabled(tabId?: number): Promise;
export function isEnabled(callback: (isEnabled: boolean) => void): void;
export function isEnabled(tabId: number | undefined, callback: (isEnabled: boolean) => void): void;
/**
* Opens the extension's popup. Between Chrome 118 and Chrome 126, this is only available to policy installed extensions.
*
* @param options Specifies options for opening the popup.
*
* Can return its result via Promise.
* @since Chrome 127
*/
export function openPopup(options?: OpenPopupOptions): Promise;
export function openPopup(callback: () => void): void;
export function openPopup(options: OpenPopupOptions | undefined, callback: () => void): void;
/**
* Sets the background color for the badge.
*
* Can return its result via Promise.
*/
export function setBadgeBackgroundColor(details: BadgeColorDetails): Promise;
export function setBadgeBackgroundColor(details: BadgeColorDetails, callback: () => void): void;
/**
* Sets the badge text for the action. The badge is displayed on top of the icon.
*
* Can return its result via Promise.
*/
export function setBadgeText(details: BadgeTextDetails): Promise;
export function setBadgeText(details: BadgeTextDetails, callback: () => void): void;
/**
* Sets the text color for the badge.
*
* Can return its result via Promise.
* @since Chrome 110
*/
export function setBadgeTextColor(details: BadgeColorDetails): Promise;
export function setBadgeTextColor(details: BadgeColorDetails, callback: () => void): void;
/**
* Sets the icon for the action. The icon can be specified either as the path to an image file or as the pixel data from a canvas element, or as dictionary of either one of those. Either the path or the imageData property must be specified.
*
* Can return its result via Promise.
*/
export function setIcon(details: TabIconDetails): Promise;
export function setIcon(details: TabIconDetails, callback: () => void): void;
/**
* Sets the html document to be opened as a popup when the user clicks on the action's icon.
*
* Can return its result via Promise.
*/
export function setPopup(details: PopupDetails): Promise;
export function setPopup(details: PopupDetails, callback: () => void): void;
/**
* Sets the title of the action. This shows up in the tooltip.
*
* Can return its result via Promise.
*/
export function setTitle(details: TitleDetails): Promise;
export function setTitle(details: TitleDetails, callback: () => void): void;
/** Fired when an action icon is clicked. This event will not fire if the action has a popup. */
export const onClicked: events.Event<(tab: chrome.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>;
}
////////////////////
// Alarms
////////////////////
/**
* Use the `chrome.alarms` API to schedule code to run periodically or at a specified time in the future.
*
* Permissions: "alarms"
*/
export namespace alarms {
export interface AlarmCreateInfo {
/** Length of time in minutes after which the {@link onAlarm} event should fire. */
delayInMinutes?: number | undefined;
/** If set, the onAlarm event should fire every `periodInMinutes` minutes after the initial event specified by `when` or `delayInMinutes`. If not set, the alarm will only fire once. */
periodInMinutes?: number | undefined;
/** Time at which the alarm should fire, in milliseconds past the epoch (e.g. `Date.now() + n`). */
when?: number | undefined;
}
export interface Alarm {
/** If not null, the alarm is a repeating alarm and will fire again in `periodInMinutes` minutes. */
periodInMinutes?: number;
/** Time at which this alarm was scheduled to fire, in milliseconds past the epoch (e.g. `Date.now() + n`). For performance reasons, the alarm may have been delayed an arbitrary amount beyond this. */
scheduledTime: number;
/** Name of this alarm. */
name: string;
}
/**
* Creates an alarm. Near the time(s) specified by `alarmInfo`, the {@link onAlarm} event is fired. If there is another alarm with the same name (or no name if none is specified), it will be cancelled and replaced by this alarm.
*
* In order to reduce the load on the user's machine, Chrome limits alarms to at most once every 30 seconds but may delay them an arbitrary amount more. That is, setting `delayInMinutes` or `periodInMinutes` to less than `0.5` will not be honored and will cause a warning. `when` can be set to less than 30 seconds after "now" without warning but won't actually cause the alarm to fire for at least 30 seconds.
*
* To help you debug your app or extension, when you've loaded it unpacked, there's no limit to how often the alarm can fire.
* @param name Optional name to identify this alarm. Defaults to the empty string.
* @param alarmInfo Describes when the alarm should fire. The initial time must be specified by either `when` or `delayInMinutes` (but not both). If `periodInMinutes` is set, the alarm will repeat every `periodInMinutes` minutes after the initial event. If neither `when` or `delayInMinutes` is set for a repeating alarm, `periodInMinutes` is used as the default for `delayInMinutes`.
*
* Can return its result via Promise in Manifest V3 or later since Chrome 111.
*/
export function create(alarmInfo: AlarmCreateInfo): Promise;
export function create(name: string | undefined, alarmInfo: AlarmCreateInfo): Promise;
export function create(alarmInfo: AlarmCreateInfo, callback: () => void): void;
export function create(name: string | undefined, alarmInfo: AlarmCreateInfo, callback: () => void): void;
/**
* Gets an array of all the alarms.
*
* Can return its result via Promise in Manifest V3 or later since Chrome 91.
*/
export function getAll(): Promise;
export function getAll(callback: (alarms: Alarm[]) => void): void;
/**
* Clears all alarms.
*
* Can return its result via Promise in Manifest V3 or later since Chrome 91.
*/
export function clearAll(): Promise;
export function clearAll(callback: (wasCleared: boolean) => void): void;
/**
* Clears the alarm with the given name.
*
* Can return its result via Promise in Manifest V3 or later since Chrome 91.
*/
export function clear(name?: string): Promise;
export function clear(callback: (wasCleared: boolean) => void): void;
export function clear(name: string | undefined, callback: (wasCleared: boolean) => void): void;
/**
* Retrieves details about the specified alarm.
* @param name The name of the alarm to get. Defaults to the empty string.
*
* Can return its result via Promise in Manifest V3 or later since Chrome 91.
*/
export function get(name?: string): Promise;
export function get(callback: (alarm?: Alarm) => void): void;
export function get(name: string | undefined, callback: (alarm?: Alarm) => void): void;
/** Fired when an alarm has elapsed. Useful for event pages. */
export const onAlarm: events.Event<(alarm: Alarm) => void>;
}
////////////////////
// Audio
////////////////////
/**
* The `chrome.audio` API is provided to allow users to get information about and control the audio devices attached to the system. This API is currently only available in kiosk mode for ChromeOS.
*
* Permissions: "audio"
* @platform ChromeOS only
* @since Chrome 59
*/
export namespace audio {
export interface AudioDeviceInfo {
/** Device name */
deviceName: string;
/** Type of the device */
deviceType: DeviceType;
/** The user-friendly name (e.g. "USB Microphone"). */
displayName: string;
/** The unique identifier of the audio device. */
id: string;
/** True if this is the current active device. */
isActive: boolean;
/** The sound level of the device, volume for output, gain for input. */
level: number;
/** The stable/persisted device id string when available. */
stableDeviceId?: string;
/** Stream type associated with this device. */
streamType: StreamType;
}
export interface DeviceFilter {
/** If set, only audio devices whose active state matches this value will satisfy the filter. */
isActive?: boolean;
/** If set, only audio devices whose stream type is included in this list will satisfy the filter. */
streamTypes?: StreamType[];
}
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 DeviceProperties {
/**
* The audio device's desired sound level. Defaults to the device's current sound level.
* If used with audio input device, represents audio device gain.
* If used with audio output device, represents audio device volume.
*/
level?: number;
}
/** Available audio device types. */
export enum DeviceType {
ALSA_LOOPBACK = "ALSA_LOOPBACK",
BLUETOOTH = "BLUETOOTH",
FRONT_MIC = "FRONT_MIC",
HDMI = "HDMI",
HEADPHONE = "HEADPHONE",
HOTWORD = "HOTWORD",
INTERNAL_MIC = "INTERNAL_MIC",
INTERNAL_SPEAKER = "INTERNAL_SPEAKER",
KEYBOARD_MIC = "KEYBOARD_MIC",
LINEOUT = "LINEOUT",
MIC = "MIC",
OTHER = "OTHER",
POST_DSP_LOOPBACK = "POST_DSP_LOOPBACK",
POST_MIX_LOOPBACK = "POST_MIX_LOOPBACK",
REAR_MIC = "REAR_MIC",
USB = "USB",
}
export interface LevelChangedEvent {
/** ID of device whose sound level has changed. */
deviceId: string;
/** The device's new sound level. */
level: number;
}
export interface MuteChangedEvent {
/** Whether or not the stream is now muted. */
isMuted: boolean;
/** The type of the stream for which the mute value changed. The updated mute value applies to all devices with this stream type. */
streamType: StreamType;
}
/** Type of stream an audio device provides. */
export enum StreamType {
INPUT = "INPUT",
OUTPUT = "OUTPUT",
}
/**
* Gets a list of audio devices filtered based on filter.
* Can return its result via Promise in Manifest V3 or later since Chrome 116.
*/
export function getDevices(filter?: DeviceFilter): Promise;
export function getDevices(filter: DeviceFilter, callback: (devices: AudioDeviceInfo[]) => void): void;
export function getDevices(callback: (devices: AudioDeviceInfo[]) => void): void;
/**
* Gets the system-wide mute state for the specified stream type.
* Can return its result via Promise in Manifest V3 or later since Chrome 116.
*/
export function getMute(streamType: `${StreamType}`): Promise;
export function getMute(streamType: `${StreamType}`, callback: (value: boolean) => void): void;
/**
* Sets lists of active input and/or output devices.
* Can return its result via Promise in Manifest V3 or later since Chrome 116.
*/
export function setActiveDevices(ids: DeviceIdLists): Promise;
export function setActiveDevices(ids: DeviceIdLists, callback: () => void): void;
/**
* Sets mute state for a stream type. The mute state will apply to all audio devices with the specified audio stream type.
* Can return its result via Promise in Manifest V3 or later since Chrome 116.
*/
export function setMute(streamType: `${StreamType}`, isMuted: boolean): Promise;
export function setMute(streamType: `${StreamType}`, isMuted: boolean, callback: () => void): void;
/**
* Sets the properties for the input or output device.
* Can return its result via Promise in Manifest V3 or later since Chrome 116.
*/
export function setProperties(id: string, properties: DeviceProperties): Promise;
export function setProperties(id: string, properties: DeviceProperties, callback: () => void): void;
/**
* Fired when audio devices change, either new devices being added, or existing devices being removed.
*/
export const onDeviceListChanged: chrome.events.Event<(devices: AudioDeviceInfo[]) => void>;
/**
* Fired when sound level changes for an active audio device.
*/
export const onLevelChanged: chrome.events.Event<(event: LevelChangedEvent) => void>;
/**
* Fired when the mute state of the audio input or output changes.
* Note that mute state is system-wide and the new value applies to every audio device with specified stream type.
*/
export const onMuteChanged: chrome.events.Event<(event: MuteChangedEvent) => void>;
}
////////////////////
// Bookmarks
////////////////////
/**
* Use the `chrome.bookmarks` API to create, organize, and otherwise manipulate bookmarks. Also see Override Pages, which you can use to create a custom Bookmark Manager page.
*
* Permissions: "bookmarks"
*/
export namespace bookmarks {
/** A node (either a bookmark or a folder) in the bookmark tree. Child nodes are ordered within their parent folder. */
export interface BookmarkTreeNode {
/** An ordered list of children of this node. */
children?: BookmarkTreeNode[];
/** When this node was created, in milliseconds since the epoch (`new Date(dateAdded)`). */
dateAdded?: number;
/** When the contents of this folder last changed, in milliseconds since the epoch. */
dateGroupModified?: number;
/**
* When this node was last opened, in milliseconds since the epoch. Not set for folders.
* @since Chrome 114
*/
dateLastUsed?: number;
/**
* If present, this is a folder that is added by the browser and that cannot be modified by the user or the extension. Child nodes may be modified, if this node does not have the `unmodifiable` property set. Omitted if the node can be modified by the user and the extension (default).
*
* There may be zero, one or multiple nodes of each folder type. A folder may be added or removed by the browser, but not via the extensions API.
* @since Chrome 134
*/
folderType?: `${FolderType}`;
/** The unique identifier for the node. IDs are unique within the current profile, and they remain valid even after the browser is restarted. */
id: string;
/** The 0-based position of this node within its parent folder. */
index?: number;
/** The `id` of the parent folder. Omitted for the root node. */
parentId?: string;
/**
* Whether this node is synced with the user's remote account storage by the browser. This can be used to distinguish between account and local-only versions of the same {@link FolderType}. The value of this property may change for an existing node, for example as a result of user action.
*
* Note: this reflects whether the node is saved to the browser's built-in account provider. It is possible that a node could be synced via a third-party, even if this value is false.
*
* For managed nodes (nodes where `unmodifiable` is set to `true`), this property will always be `false`.
* @since Chrome 134
*/
syncing: boolean;
/** The text displayed for the node. */
title: string;
/** Indicates the reason why this node is unmodifiable. The `managed` value indicates that this node was configured by the system administrator or by the custodian of a supervised user. Omitted if the node can be modified by the user and the extension (default). */
unmodifiable?: `${BookmarkTreeNodeUnmodifiable}`;
/* The URL navigated to when a user clicks the bookmark. Omitted for folders. */
url?: string;
}
/**
* Indicates the reason why this node is unmodifiable. The `managed` value indicates that this node was configured by the system administrator. Omitted if the node can be modified by the user and the extension (default).
* @since Chrome 44
*/
export enum BookmarkTreeNodeUnmodifiable {
MANAGED = "managed",
}
/** Object passed to the create() function. */
export interface CreateDetails {
index?: number;
/** Defaults to the Other Bookmarks folder. */
parentId?: string;
title?: string;
url?: string;
}
/**
* Indicates the type of folder.
* @since Chrome 134
*/
export enum FolderType {
/** The folder whose contents is displayed at the top of the browser window. */
BOOKMARKS_BAR = "bookmarks-bar",
/** Bookmarks which are displayed in the full list of bookmarks on all platforms. */
OTHER = "other",
/** Bookmarks generally available on the user's mobile devices, but modifiable by extension or in the bookmarks manager. */
MOBILE = "mobile",
/** A top-level folder that may be present if the system administrator or the custodian of a supervised user has configured bookmarks. */
MANAGED = "managed",
}
/** @deprecated Bookmark write operations are no longer limited by Chrome. */
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 Chrome 145
*/
export const ROOT_NODE_ID = "0";
/**
* Creates a bookmark or folder under the specified parentId. If url is NULL or missing, it will be a folder.
*
* Can return its result via Promise since Chrome 90.
*/
export function create(bookmark: CreateDetails): Promise;
export function create(bookmark: CreateDetails, callback: (result: BookmarkTreeNode) => void): void;
/**
* Retrieves the specified BookmarkTreeNode(s).
* @param idOrIdList A single string-valued id, or an array of string-valued ids
*
* Can return its result via Promise since Chrome 90.
*/
export function get(idOrIdList: string | [string, ...string[]]): Promise;
export function get(
idOrIdList: string | [string, ...string[]],
callback: (results: BookmarkTreeNode[]) => void,
): void;
/**
* Retrieves the children of the specified BookmarkTreeNode id.
*
* Can return its result via Promise since Chrome Chrome 90
*/
export function getChildren(id: string): Promise;
export function getChildren(id: string, callback: (results: BookmarkTreeNode[]) => void): void;
/**
* Retrieves the recently added bookmarks.
* @param numberOfItems The maximum number of items to return.
*
* Can return its result via Promise since Chrome Chrome 90
*/
export function getRecent(numberOfItems: number): Promise;
export function getRecent(numberOfItems: number, callback: (results: BookmarkTreeNode[]) => void): void;
/**
* Retrieves part of the Bookmarks hierarchy, starting at the specified node.
* @param id The ID of the root of the subtree to retrieve.
*
* Can return its result via Promise since Chrome Chrome 90
*/
export function getSubTree(id: string): Promise;
export function getSubTree(id: string, callback: (results: BookmarkTreeNode[]) => void): void;
/**
* Retrieves the entire Bookmarks hierarchy.
*
* Can return its result via Promise since Chrome Chrome 90
*/
export function getTree(): Promise;
export function getTree(callback: (results: BookmarkTreeNode[]) => void): void;
interface MoveDestination {
parentId?: string;
index?: number;
}
/**
* Moves the specified BookmarkTreeNode to the provided location.
*
* Can return its result via Promise since Chrome Chrome 90
*/
export function move(id: string, destination: MoveDestination): Promise;
export function move(
id: string,
destination: MoveDestination,
callback: (result: BookmarkTreeNode) => void,
): void;
/**
* Removes a bookmark or an empty bookmark folder.
*
* Can return its result via Promise since Chrome Chrome 90
*/
export function remove(id: string): Promise;
export function remove(id: string, callback: () => void): void;
/**
* Recursively removes a bookmark folder.
*
* Can return its result via Promise since Chrome Chrome 90
*/
export function removeTree(id: string): Promise;
export function removeTree(id: string, callback: () => void): void;
interface SearchQuery {
/** A string of words and quoted phrases that are matched against bookmark URLs and titles.*/
query?: string;
/** The URL of the bookmark; matches verbatim. Note that folders have no URL. */
url?: string;
/** The title of the bookmark; matches verbatim. */
title?: string;
}
/**
* Searches for BookmarkTreeNodes matching the given query. Queries specified with an object produce BookmarkTreeNodes matching all specified properties.
* @param query Either a string of words and quoted phrases that are matched against bookmark URLs and titles, or an object. If an object, the properties `query`, `url`, and `title` may be specified and bookmarks matching all specified properties will be produced.
*
* Can return its result via Promise since Chrome Chrome 90
*/
export function search(query: string | SearchQuery): Promise;
export function search(query: string | SearchQuery, callback: (results: BookmarkTreeNode[]) => void): void;
interface UpdateChanges {
title?: string;
url?: string;
}
/**
* Updates the properties of a bookmark or folder. Specify only the properties that you want to change; unspecified properties will be left unchanged. **Note:** Currently, only 'title' and 'url' are supported.
*
* Can return its result via Promise since Chrome Chrome 90
*/
export function update(id: string, changes: UpdateChanges): Promise;
export function update(id: string, changes: UpdateChanges, callback: (result: BookmarkTreeNode) => void): void;
/** Fired when a bookmark or folder changes. **Note:** Currently, only title and url changes trigger this.*/
export const onChanged: events.Event<(id: string, changeInfo: { title: string; url?: string }) => void>;
/** Fired when the children of a folder have changed their order due to the order being sorted in the UI. This is not called as a result of a move(). */
export const onChildrenReordered: events.Event<(id: string, reorderInfo: { childIds: string[] }) => void>;
/** Fired when a bookmark or folder is created. */
export const onCreated: events.Event<(id: string, bookmark: BookmarkTreeNode) => void>;
/** Fired when a bookmark import session is begun. Expensive observers should ignore onCreated updates until onImportEnded is fired. Observers should still handle other notifications immediately. */
export const onImportBegan: events.Event<() => void>;
/** Fired when a bookmark import session is ended. */
export const onImportEnded: events.Event<() => 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 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
>;
}
////////////////////
// Browser Action
////////////////////
/**
* Use browser actions to put icons in the main Google Chrome toolbar, to the right of the address bar. In addition to its icon, a browser action can have a tooltip, a badge, and a popup.
*
* Manifest: "browser_action"
*
* MV2 only
*/
export namespace browserAction {
export interface BadgeBackgroundColorDetails {
/** An array of four integers in the range 0-255 that make up the RGBA color of the badge. Can also be a string with a CSS hex color value; for example, `#FF0000` or `#F00` (red). Renders colors at full opacity. */
color: string | extensionTypes.ColorArray;
/** Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */
tabId?: number | null | undefined;
}
export interface BadgeTextDetails {
/** Any number of characters can be passed, but only about four can fit into the space. If an empty string (`''`) is passed, the badge text is cleared. If `tabId` is specified and `text` is null, the text for the specified tab is cleared and defaults to the global badge text. */
text?: string | null | undefined;
/** Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */
tabId?: number | null | undefined;
}
export interface TitleDetails {
/** The string the browser action should display when moused over. */
title: string;
/** Optional. Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */
tabId?: number | null | undefined;
}
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 | null | undefined;
}
export type TabIconDetails =
& {
/** Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */
tabId?: number | null | undefined;
}
& (
| {
/** Either an ImageData object or a dictionary {size -> ImageData} representing an icon to be set. If the icon is specified as a dictionary, the image used is chosen depending on the screen's pixel density. If the number of image pixels that fit into one screen space unit equals `scale`, then an image with size `scale` \* n is selected, where _n_ is the size of the icon in the UI. At least one image must be specified. Note that 'details.imageData = foo' is equivalent to 'details.imageData = {'16': foo}' */
imageData: ImageData | { [index: number]: ImageData };
/** Either a relative image path or a dictionary {size -> relative image path} pointing to an icon to be set. If the icon is specified as a dictionary, the image used is chosen depending on the screen's pixel density. If the number of image pixels that fit into one screen space unit equals `scale`, then an image with size `scale` \* n is selected, where _n_ is the size of the icon in the UI. At least one image must be specified. Note that 'details.path = foo' is equivalent to 'details.path = {'16': foo}' */
path?: string | { [index: string]: string } | undefined;
}
| {
/** Either an ImageData object or a dictionary {size -> ImageData} representing an icon to be set. If the icon is specified as a dictionary, the image used is chosen depending on the screen's pixel density. If the number of image pixels that fit into one screen space unit equals `scale`, then an image with size `scale` \* n is selected, where _n_ is the size of the icon in the UI. At least one image must be specified. Note that 'details.imageData = foo' is equivalent to 'details.imageData = {'16': foo}' */
imageData?: ImageData | { [index: number]: ImageData } | undefined;
/** Either a relative image path or a dictionary {size -> relative image path} pointing to an icon to be set. If the icon is specified as a dictionary, the image used is chosen depending on the screen's pixel density. If the number of image pixels that fit into one screen space unit equals `scale`, then an image with size `scale` \* n is selected, where _n_ is the size of the icon in the UI. At least one image must be specified. Note that 'details.path = foo' is equivalent to 'details.path = {'16': foo}' */
path: string | { [index: string]: string };
}
);
export interface PopupDetails {
/** Limits the change to when a particular tab is selected. Automatically resets when the tab is closed. */
tabId?: number | null | undefined;
/** The relative path to the HTML file to show in a popup. If set to the empty string (`''`), no popup is shown.*/
popup: string;
}
/**
* Enables the browser action for a tab. Defaults to enabled.
* @param tabId The ID of the tab for which to modify the browser action.
* @param callback Since Chrome 67
*/
export function enable(callback?: () => void): void;
export function enable(tabId: number | null | undefined, callback?: () => void): void;
/**
* Sets the background color for the badge.
* @param callback Since Chrome 67
*/
export function setBadgeBackgroundColor(details: BadgeBackgroundColorDetails, callback?: () => void): void;
/**
* Sets the badge text for the browser action. The badge is displayed on top of the icon.
* @param callback Since Chrome 67
*/
export function setBadgeText(details: BadgeTextDetails, callback?: () => void): void;
/**
* Sets the title of the browser action. This title appears in the tooltip.
* @param callback Since Chrome 67
*/
export function setTitle(details: TitleDetails, callback?: () => void): void;
/** Gets the badge text of the browser action. If no tab is specified, the non-tab-specific badge text is returned. */
export function getBadgeText(details: TabDetails, callback: (result: string) => void): void;
/**
* Sets the HTML document to be opened as a popup when the user clicks the browser action icon.
* @param callback Since Chrome 67
*/
export function setPopup(details: PopupDetails, callback?: () => void): void;
/**
* Disables the browser action for a tab.
* @param tabId The ID of the tab for which to modify the browser action.
* @param callback since Chrome 67
*/
export function disable(callback?: () => void): void;
export function disable(tabId: number | null | undefined, callback?: () => void): void;
/** Gets the title of the browser action. */
export function getTitle(details: TabDetails, callback: (result: string) => void): void;
/** Gets the background color of the browser action. */
export function getBadgeBackgroundColor(
details: TabDetails,
callback: (result: extensionTypes.ColorArray) => void,
): void;
/** 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 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: TabIconDetails, callback?: () => void): void;
/** Fired when a browser action icon is clicked. Does not fire if the browser action has a popup. */
export const onClicked: events.Event<(tab: chrome.tabs.Tab) => void>;
}
////////////////////
// Browsing Data
////////////////////
/**
* Use the `chrome.browsingData` API to remove browsing data from a user's local profile.
*
* Permissions: "browsingData"
*/
export namespace browsingData {
export interface OriginTypes {
/** Extensions and packaged applications a user has installed (be _really_ careful!). */
extension?: boolean | undefined;
/** Websites that have been installed as hosted applications (be careful!). */
protectedWeb?: boolean | undefined;
/** Normal websites. */
unprotectedWeb?: boolean | undefined;
}
/** Options that determine exactly what data will be removed. */
export interface RemovalOptions {
/**
* 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[] | undefined;
/** 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?: OriginTypes | undefined;
/**
* 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[]] | undefined;
/** Remove data accumulated on or after this date, represented in milliseconds since the epoch (accessible via the {@link Date.getTime getTime} method of the JavaScript `Date` object). If absent, defaults to 0 (which would remove all browsing data). */
since?: number | undefined;
}
/** A set of data types. Missing data types are interpreted as `false`. */
export interface DataTypeSet {
/** Websites' WebSQL data. */
webSQL?: boolean | undefined;
/** Websites' IndexedDB data. */
indexedDB?: boolean | undefined;
/** The browser's cookies. */
cookies?: boolean | undefined;
/**
* Stored passwords.
* @deprecated since Chrome 144. Support for password deletion through extensions has been removed. This data type will be ignored.
*/
passwords?: boolean | undefined;
/**
* Server-bound certificates.
* @deprecated since Chrome 76. Support for server-bound certificates has been removed. This data type will be ignored.
*/
serverBoundCertificates?: boolean | undefined;
/** The browser's download list. */
downloads?: boolean | undefined;
/** The browser's cache. */
cache?: boolean | undefined;
/** Cache storage. */
cacheStorage?: boolean | undefined;
/** Websites' appcaches. */
appcache?: boolean | undefined;
/** Websites' file systems. */
fileSystems?: boolean | undefined;
/**
* Plugins' data.
* @deprecated since Chrome 88. Support for Flash has been removed. This data type will be ignored.
*/
pluginData?: boolean | undefined;
/** Websites' local storage data. */
localStorage?: boolean | undefined;
/** The browser's stored form data. */
formData?: boolean | undefined;
/** The browser's history. */
history?: boolean | undefined;
/** Service Workers. */
serviceWorkers?: boolean | undefined;
}
export interface SettingsResult {
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.
*
* Can return its result via Promise in Manifest V3 or later since Chrome 96.
*/
export function settings(): Promise;
export function settings(callback: (result: SettingsResult) => void): void;
/**
* Clears plugins' data.
*
* Can return its result via Promise in Manifest V3 or later since Chrome 96.
* @deprecated since Chrome 88. Support for Flash has been removed. This function has no effect
*/
export function removePluginData(options: RemovalOptions): Promise;
export function removePluginData(options: RemovalOptions, callback: () => void): void;
/**
* Clears websites' service workers.
*
* Can return its result via Promise in Manifest V3 or later since Chrome 96.
* @since Chrome 72
*/
export function removeServiceWorkers(options: RemovalOptions): Promise;
export function removeServiceWorkers(options: RemovalOptions, callback: () => void): void;
/**
* Clears the browser's stored form data (autofill).
*
* Can return its result via Promise in Manifest V3 or later since Chrome 96.
*/
export function removeFormData(options: RemovalOptions): Promise;
export function removeFormData(options: RemovalOptions, callback: () => void): void;
/**
* Clears websites' file system data.
*
* Can return its result via Promise in Manifest V3 or later since Chrome 96.
*/
export function removeFileSystems(options: RemovalOptions): Promise;
export function removeFileSystems(options: RemovalOptions, callback: () => void): void;
/**
* Clears various types of browsing data stored in a user's profile.
*
* Can return its result via Promise in Manifest V3 or later since Chrome 96.
* @param dataToRemove The set of data types to remove.
*/
export function remove(options: RemovalOptions, dataToRemove: DataTypeSet): Promise;
export function remove(options: RemovalOptions, dataToRemove: DataTypeSet, callback: () => void): void;
/**
* Clears the browser's stored passwords.
*
* Can return its result via Promise in Manifest V3 or later since Chrome 96.
* @deprecated since Chrome 144. Support for password deletion through extensions has been removed. This function has no effect.
*/
export function removePasswords(options: RemovalOptions): Promise;
export function removePasswords(options: RemovalOptions, callback: () => void): void;
/**
* Clears the browser's cookies and server-bound certificates modified within a particular timeframe.
*
* Can return its result via Promise in Manifest V3 or later since Chrome 96.
*/
export function removeCookies(options: RemovalOptions): Promise;
export function removeCookies(options: RemovalOptions, callback: () => void): void;
/**
* Clears websites' WebSQL data.
*
* Can return its result via Promise in Manifest V3 or later since Chrome 96.
*/
export function removeWebSQL(options: RemovalOptions): Promise;
export function removeWebSQL(options: RemovalOptions, callback: () => void): void;
/**
* Clears websites' appcache data.
*
* Can return its result via Promise in Manifest V3 or later since Chrome 96.
*/
export function removeAppcache(options: RemovalOptions): Promise;
export function removeAppcache(options: RemovalOptions, callback: () => void): void;
/**
* Clears websites' cache storage data.
*
* Can return its result via Promise in Manifest V3 or later since Chrome 96.
*/
export function removeCacheStorage(options: RemovalOptions): Promise;
export function removeCacheStorage(options: RemovalOptions, callback: () => void): void;
/**
* Clears the browser's list of downloaded files (not the downloaded files themselves).
*
* Can return its result via Promise in Manifest V3 or later since Chrome 96.
*/
export function removeDownloads(options: RemovalOptions): Promise;
export function removeDownloads(options: RemovalOptions, callback: () => void): void;
/**
* Clears websites' local storage data.
*
* Can return its result via Promise in Manifest V3 or later since Chrome 96.
*/
export function removeLocalStorage(options: RemovalOptions): Promise;
export function removeLocalStorage(options: RemovalOptions, callback: () => void): void;
/**
* Clears the browser's cache.
*
* Can return its result via Promise in Manifest V3 or later since Chrome 96.
*/
export function removeCache(options: RemovalOptions): Promise;
export function removeCache(options: RemovalOptions, callback: () => void): void;
/**
* Clears the browser's history.
*
* Can return its result via Promise in Manifest V3 or later since Chrome 96.
*/
export function removeHistory(options: RemovalOptions): Promise;
export function removeHistory(options: RemovalOptions, callback: () => void): void;
/**
* Clears websites' IndexedDB data.
*
* Can return its result via Promise in Manifest V3 or later since Chrome 96.
*/
export function removeIndexedDB(options: RemovalOptions): Promise;
export function removeIndexedDB(options: RemovalOptions, callback: () => void): void;
}
////////////////////
// Certificate Provider
////////////////////
/**
* Use this API to expose certificates to the platform which can use these certificates for TLS authentications.
*
* Manifest: "certificateProvider"
* @platform ChromeOS only
* @since Chrome 46
*/
export namespace certificateProvider {
/** Types of supported cryptographic signature algorithms. */
export enum Algorithm {
/**
* 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.
* @deprecated This algorithm is deprecated and will never be requested by Chrome as of version 109.
*/
RSASSA_PKCS1_V1_5_MD5_SHA1 = "RSASSA_PKCS1_v1_5_MD5_SHA1",
/** Specifies the RSASSA PKCS#1 v1.5 signature algorithm with the SHA-1 hash function. */
RSASSA_PKCS1_V1_5_SHA1 = "RSASSA_PKCS1_v1_5_SHA1",
/** Specifies the RSASSA PKCS#1 v1.5 signature algorithm with the SHA-256 hashing function. */
RSASSA_PKCS1_V1_5_SHA256 = "RSASSA_PKCS1_v1_5_SHA256",
/** Specifies the RSASSA PKCS#1 v1.5 signature algorithm with the SHA-384 hashing function. */
RSASSA_PKCS1_V1_5_SHA384 = "RSASSA_PKCS1_v1_5_SHA384",
/** Specifies the RSASSA PKCS#1 v1.5 signature algorithm with the SHA-512 hashing function. */
RSASSA_PKCS1_V1_5_SHA512 = "RSASSA_PKCS1_v1_5_SHA512",
/** 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. */
RSASSA_PSS_SHA256 = "RSASSA_PSS_SHA256",
/** 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. */
RSASSA_PSS_SHA384 = "RSASSA_PSS_SHA384",
/** 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. */
RSASSA_PSS_SHA512 = "RSASSA_PSS_SHA512",
}
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}`[];
}
/** @since Chrome 86 */
export interface CertificatesUpdateRequest {
/** Request identifier to be passed to {@link setCertificates}. */
certificatesRequestId: number;
}
/** @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}`[];
}
/**
* Types of errors that the extension can report.
* @since Chrome 86
*/
export enum Error {
GENERAL_ERROR = "GENERAL_ERROR",
}
/** @deprecated Replaced by {@link Algorithm}.*/
export enum Hash {
/** Specifies the MD5 and SHA1 hashing algorithms. */
MD5_SHA1 = "MD5_SHA1",
/** Specifies the SHA1 hashing algorithm. */
SHA1 = "SHA1",
/** Specifies the SHA256 hashing algorithm. */
SHA256 = "SHA256",
/** Specifies the SHA384 hashing algorithm. */
SHA384 = "SHA384",
/** Specifies the SHA512 hashing algorithm. */
SHA512 = "SHA512",
}
/**
* The types of errors that can be presented to the user through the requestPin function.
* @since Chrome 57
*/
export enum PinRequestErrorType {
/** Specifies the PIN is invalid. */
INVALID_PIN = "INVALID_PIN",
/** Specifies the PUK is invalid. */
INVALID_PUK = "INVALID_PUK",
/** Specifies the maximum attempt number has been exceeded. */
MAX_ATTEMPTS_EXCEEDED = "MAX_ATTEMPTS_EXCEEDED",
/** Specifies that the error cannot be represented by the above types. */
UNKNOWN_ERROR = "UNKNOWN_ERROR",
}
/**
* The type of code being requested by the extension with requestPin function.
* @since Chrome 57
*/
export enum PinRequestType {
/** Specifies the requested code is a PIN. */
PIN = "PIN",
/** Specifies the requested code is a PUK. */
PUK = "PUK",
}
/** @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 | undefined;
}
/** @since Chrome 86 */
export interface ReportSignatureDetails {
/** Error that occurred while generating the signature, if any. */
error?: `${Error}` | undefined;
/** Request identifier that was received via the {@link onSignatureRequested} event. */
signRequestId: number;
/** The signature, if successfully generated. */
signature?: ArrayBuffer | undefined;
}
/** @since Chrome 57 */
export interface RequestPinDetails {
/** 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 | undefined;
/** 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}` | undefined;
/** The type of code requested. Default is PIN. */
requestType?: `${PinRequestType}` | undefined;
/** The ID given by Chrome in SignRequest. */
signRequestId: number;
}
/** @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 | undefined;
/** List of currently available client certificates. */
clientCertificates: ClientCertificateInfo[];
/** Error that occurred while extracting the certificates, if any. This error will be surfaced to the user when appropriate. */
error?: `${Error}` | undefined;
}
/** @since Chrome 86 */
export interface SignatureRequest {
/** 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;
/** Data to be signed. Note that the data is not hashed. */
input: ArrayBuffer;
/** Request identifier to be passed to {@link reportSignature}. */
signRequestId: number;
}
export interface SignRequest {
/** The DER encoding of a X.509 certificate. The extension must sign `digest` using the associated private key. */
certificate: ArrayBuffer;
/** The digest that must be signed. */
digest: ArrayBuffer;
/** Refers to the hash algorithm that was used to create `digest`. */
hash: `${Hash}`;
/**
* 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;
}
/** @since Chrome 57 */
export interface StopPinRequestDetails {
/** 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}` | undefined;
/** The ID given by Chrome in SignRequest. */
signRequestId: number;
}
/**
* 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.
*
* Can return its result via Promise since Chrome 96.
* @since Chrome 86
*/
export function reportSignature(details: ReportSignatureDetails): Promise;
export function reportSignature(details: ReportSignatureDetails, callback: () => 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.
*
* Can return its result via Promise since Chrome 96.
* @param details Contains the details about the requested dialog.
* @since Chrome 57
*/
export function requestPin(details: RequestPinDetails): Promise;
export function requestPin(
details: RequestPinDetails,
callback: (details?: PinResponseDetails | undefined) => 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.
*
* Can return its result via Promise since Chrome 96.
* @param details The certificates to set. Invalid certificates will be ignored.
* @since Chrome 86
*/
export function setCertificates(details: SetCertificatesDetails): Promise;
export function setCertificates(details: SetCertificatesDetails, callback: () => void): void;
/**
* Stops the pin request started by the {@link requestPin} function.
*
* Can return its result via Promise since Chrome 96.
* @param details Contains the details about the reason for stopping the request flow.
* @since Chrome 57
*/
export function stopPinRequest(details: StopPinRequestDetails): Promise;
export function stopPinRequest(details: StopPinRequestDetails, callback: () => void): void;
/**
* 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>;
}
////////////////////
// Commands
////////////////////
/**
* 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.
*
* 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;
}
/**
* Returns all the registered extension commands for this extension and their shortcut (if active). Before Chrome 110, this command did not return `_execute_action`.
*
* Can return its result via Promise in Manifest V3 or later since Chrome 96.
*/
export function getAll(): Promise;
export function getAll(callback: (commands: Command[]) => void): void;
/** Fired when a registered command is activated using a keyboard shortcut. */
export const onCommand: events.Event<(command: string, tab?: tabs.Tab) => void>;
}
////////////////////
// Content Settings
////////////////////
/**
* 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.
*
* Permissions: "contentSettings"
*/
export namespace contentSettings {
/** @since Chrome 113 */
export enum AutoVerifyContentSetting {
ALLOW = "allow",
BLOCK = "block",
}
/** @since Chrome 46 */
export enum CameraContentSetting {
ALLOW = "allow",
BLOCK = "block",
ASK = "ask",
}
/** @since Chrome 121 */
export enum ClipboardContentSetting {
ALLOW = "allow",
BLOCK = "block",
ASK = "ask",
}
interface ContentSettingClearParams {
/** Where to clear the setting (default: regular). */
scope?: `${Scope}`;
}
interface ContentSettingGetParams {
/** Whether to check the content settings for an incognito session. (default false) */
incognito?: boolean;
/** 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;
}
interface ContentSettingGetResult {
/** The content setting. See the description of the individual ContentSetting objects for the possible values. */
setting: T;
}
interface ContentSettingSetParams {
/** The pattern for the primary URL. For details on the format of a pattern, see Content Setting Patterns. */
primaryPattern: string;
/** The resource identifier for the content type. */
resourceIdentifier?: ResourceIdentifier;
/** Where to set the setting (default: regular). */
scope?: `${Scope}`;
/** The pattern for the secondary URL. Defaults to matching all URLs. For details on the format of a pattern, see Content Setting Patterns.*/
secondaryPattern?: string;
/** The setting applied by this rule. See the description of the individual ContentSetting objects for the possible values. */
setting: T;
}
export interface ContentSetting {
/**
* Clear all content setting rules set by this extension.
*
* Can return its result via Promise since Chrome 96.
*/
clear(details: ContentSettingClearParams): Promise;
clear(details: ContentSettingClearParams, callback: () => void): void;
/**
* Gets the current content setting for a given pair of URLs.
*
* Can return its result via Promise since Chrome 96.
*/
get(details: ContentSettingGetParams): Promise>;
get(details: ContentSettingGetParams, callback: (details: ContentSettingGetResult) => void): void;
/** Can return its result via Promise since Chrome 96. */
getResourceIdentifiers(): Promise;
getResourceIdentifiers(callback: (resourceIdentifiers?: ResourceIdentifier[]) => void): void;
/**
* Applies a new content setting rule.
*
* Can return its result via Promise since Chrome 96.
*/
set(details: ContentSettingSetParams): Promise;
set(details: ContentSettingSetParams, callback: () => void): void;
}
/** @since Chrome 44 */
export enum CookiesContentSetting {
ALLOW = "allow",
BLOCK = "block",
SESSION_ONLY = "session_only",
}
/** @since Chrome 44 */
export enum FullscreenContentSetting {
ALLOW = "allow",
}
/** @since Chrome 44 */
export enum ImagesContentSetting {
ALLOW = "allow",
BLOCK = "block",
}
/** @since Chrome 44 */
export enum JavascriptContentSetting {
ALLOW = "allow",
BLOCK = "block",
}
/** @since Chrome 44 */
export enum LocationContentSetting {
ALLOW = "allow",
BLOCK = "block",
ASK = "ask",
}
/** @since Chrome 46 */
export enum MicrophoneContentSetting {
ALLOW = "allow",
BLOCK = "block",
ASK = "ask",
}
/** @since Chrome 44 */
export enum MouselockContentSetting {
ALLOW = "allow",
}
/** @since Chrome 44 */
export enum MultipleAutomaticDownloadsContentSetting {
ALLOW = "allow",
BLOCK = "block",
ASK = "ask",
}
/** @since Chrome 44 */
export enum NotificationsContentSetting {
ALLOW = "allow",
BLOCK = "block",
ASK = "ask",
}
/** @since Chrome 44 */
export enum PluginsContentSetting {
BLOCK = "block",
}
/** @since Chrome 44 */
export enum PopupsContentSetting {
ALLOW = "allow",
BLOCK = "block",
}
/** @since Chrome 44 */
export enum PpapiBrokerContentSetting {
BLOCK = "block",
}
/** The only content type using resource identifiers is contentSettings.plugins. For more information, see Resource Identifiers. */
export interface ResourceIdentifier {
/** A human readable description of the resource. */
description?: string;
/** The resource identifier for the given content type. */
id: 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 enum Scope {
REGULAR = "regular",
INCOGNITO_SESSION_ONLY = "incognito_session_only",
}
/** @since Chrome 141 */
export enum SoundContentSetting {
ALLOW = "allow",
BLOCK = "block",
}
/**
* 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<`${MultipleAutomaticDownloadsContentSetting}`>;
/**
* Whether to allow sites to use the Private State Tokens API. 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<`${AutoVerifyContentSetting}`>;
/**
* 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<`${CameraContentSetting}`>;
/**
* 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<`${ClipboardContentSetting}`>;
/**
* 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<`${CookiesContentSetting}`>;
/** @deprecated No longer has any effect. Fullscreen permission is now automatically granted for all sites. Value is always `allow`. */
export const fullscreen: ContentSetting<`${FullscreenContentSetting}`>;
/**
* 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<`${ImagesContentSetting}`>;
/**
* 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<`${JavascriptContentSetting}`>;
/**
* 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<`${LocationContentSetting}`>;
/**
* 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<`${MicrophoneContentSetting}`>;
/** @deprecated No longer has any effect. Mouse lock permission is now automatically granted for all sites. Value is always `allow`. */
export const mouselock: ContentSetting<`${MouselockContentSetting}`>;
/**
* 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<`${NotificationsContentSetting}`>;
/** @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<`${PluginsContentSetting}`>;
/**
* 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<`${PopupsContentSetting}`>;
/** @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<`${PpapiBrokerContentSetting}`>;
}
////////////////////
// Context Menus
////////////////////
/**
* 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.
*
* Permissions: "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 enum ContextType {
ALL = "all",
PAGE = "page",
FRAME = "frame",
SELECTION = "selection",
LINK = "link",
EDITABLE = "editable",
IMAGE = "image",
VIDEO = "video",
AUDIO = "audio",
LAUNCHER = "launcher",
BROWSER_ACTION = "browser_action",
PAGE_ACTION = "page_action",
ACTION = "action",
}
/**
* Properties of the new context menu item.
* @since Chrome 123
*/
export interface CreateProperties {
/** 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}`[]];
/** 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. */
documentUrlPatterns?: string[];
/** Whether this context menu item is enabled or disabled. Defaults to `true`. */
enabled?: boolean;
/** 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 ID of a parent menu item; this makes the item a child of a previously added item. */
parentId?: number | 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[];
/** 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 type of menu item. Defaults to `normal`. */
type?: `${ItemType}`;
/** 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 type of menu item.
* @since Chrome 44
*/
export enum ItemType {
NORMAL = "normal",
CHECKBOX = "checkbox",
RADIO = "radio",
SEPARATOR = "separator",
}
/** Information sent when a context menu item is clicked. */
export interface OnClickData {
/** A flag indicating the state of a checkbox or radio item after it is clicked. */
checked?: boolean;
/** A flag indicating whether the element is editable (text input, textarea, etc.). */
editable: boolean;
/**
* The ID of the frame of the element where the context menu was clicked, if it was in a frame.
* @since Chrome 51
*/
frameId?: number;
/** The URL of the frame of the element where the context menu was clicked, if it was in a frame. */
frameUrl?: string;
/** If the element is a link, the URL it points to. */
linkUrl?: string;
/** One of 'image', 'video', or 'audio' if the context menu was activated on one of these types of elements. */
mediaType?: `${ContextType.IMAGE}` | `${ContextType.VIDEO}` | `${ContextType.AUDIO}`;
/** The ID of the menu item that was clicked. */
menuItemId: number | string;
/** The URL of the page where the menu item was clicked. This property is not set if the click occurred in a context where there is no current page, such as in a launcher context menu. */
pageUrl?: string;
/** The parent ID, if any, for the item clicked.*/
parentMenuItemId?: number | string;
/** The text for the context selection, if any. */
selectionText?: string | undefined;
/** Will be present for elements with a 'src' URL. */
srcUrl?: string | undefined;
/** A flag indicating the state of a checkbox or radio item before it was clicked. */
wasChecked?: boolean | undefined;
}
/** 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;
/**
* 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 chrome.runtime.lastError}.
* @return The ID of the newly created item.
*/
export function create(createProperties: CreateProperties, callback?: () => void): number | string;
/**
* Removes a context menu item.
* @param menuItemId The ID of the context menu item to remove.
*
* Can return its result via Promise since Chrome 123.
*/
export function remove(menuItemId: string | number): Promise;
export function remove(menuItemId: string | number, callback: () => void): void;
/**
* Removes all context menu items added by this extension.
*
* Can return its result via Promise since Chrome 123.
*/
export function removeAll(): Promise;
export function removeAll(callback: () => void): void;
/**
* 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.
*
* Can return its result via Promise since Chrome 123.
*/
export function update(id: string | number, updateProperties: Omit): Promise;
export function update(
id: string | number,
updateProperties: Omit,
callback: () => void,
): void;
/** Fired when a context menu item is clicked. */
export const onClicked: events.Event<(info: OnClickData, tab?: tabs.Tab) => void>;
}
////////////////////
// Cookies
////////////////////
/**
* Use the `chrome.cookies` API to query and modify cookies, and to be notified when they change.
*
* Permissions: "cookies"
*
* Manifest: "host_permissions"
*/
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. **/
export enum SameSiteStatus {
NO_RESTRICTION = "no_restriction",
LAX = "lax",
STRICT = "strict",
UNSPECIFIED = "unspecified",
}
/** Represents information about an HTTP cookie. */
export interface Cookie {
/** The domain of the cookie (e.g. "www.google.com", "example.com"). */
domain: string;
/** The name of the cookie. */
name: string;
/**
* The partition key for reading or modifying cookies with the Partitioned attribute.
* @since Chrome 119
*/
partitionKey?: CookiePartitionKey;
/** The ID of the cookie store containing this cookie, as provided in getAllCookieStores(). */
storeId: string;
/** The value of the cookie. */
value: string;
/** True if the cookie is a session cookie, as opposed to a persistent cookie with an expiration date. */
session: boolean;
/** 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 expiration date of the cookie as the number of seconds since the UNIX epoch. Not provided for session cookies. */
expirationDate?: number;
/** The path of the cookie. */
path: string;
/** True if the cookie is marked as HttpOnly (i.e. the cookie is inaccessible to client-side scripts). */
httpOnly: boolean;
/** True if the cookie is marked as Secure (i.e. its scope is limited to secure channels, typically HTTPS). */
secure: boolean;
/**
* The cookie's same-site status (i.e. whether the cookie is sent with cross-site requests).
* @since Chrome 51
*/
sameSite: `${SameSiteStatus}`;
}
/**
* Represents a partitioned cookie's partition key.
* @since Chrome 119
*/
export interface CookiePartitionKey {
/**
* 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 | undefined;
/** The top-level site the partitioned cookie is available in. */
topLevelSite?: string | undefined;
}
/** 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[];
}
export interface GetAllDetails {
/** Restricts the retrieved cookies to those whose domains match or are subdomains of this one. */
domain?: string | undefined;
/** Filters the cookies by name. */
name?: string | undefined;
/**
* The partition key for reading or modifying cookies with the Partitioned attribute.
* @since Chrome 119
*/
partitionKey?: CookiePartitionKey | undefined;
/** Restricts the retrieved cookies to those that would match the given URL. */
url?: string | undefined;
/** The cookie store to retrieve cookies from. If omitted, the current execution context's cookie store will be used. */
storeId?: string | undefined;
/** Filters out session vs. persistent cookies. */
session?: boolean | undefined;
/** Restricts the retrieved cookies to those whose path exactly matches this string. */
path?: string | undefined;
/** Filters the cookies by their Secure property. */
secure?: boolean | undefined;
}
export interface SetDetails {
/** The domain of the cookie. If omitted, the cookie becomes a host-only cookie. */
domain?: string | undefined;
/** The name of the cookie. Empty by default if omitted. */
name?: string | undefined;
/**
* The partition key for reading or modifying cookies with the Partitioned attribute.
* @since Chrome 119
*/
partitionKey?: CookiePartitionKey | undefined;
/** 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 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 | undefined;
/** The value of the cookie. Empty by default if omitted. */
value?: string | undefined;
/** 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 | undefined;
/** The path of the cookie. Defaults to the path portion of the url parameter. */
path?: string | undefined;
/** Whether the cookie should be marked as HttpOnly. Defaults to false. */
httpOnly?: boolean | undefined;
/** Whether the cookie should be marked as Secure. Defaults to false. */
secure?: boolean | undefined;
/**
* 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}` | undefined;
}
/**
* Details to identify the cookie.
* @since Chrome 88
*/
export interface CookieDetails {
/** The name of the cookie to access. */
name: string;
/**
* The partition key for reading or modifying cookies with the Partitioned attribute.
* @since Chrome 119
*/
partitionKey?: CookiePartitionKey | undefined;
/** 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 | undefined;
/** 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;
}
export interface CookieChangeInfo {
/** Information about the cookie that was set or removed. */
cookie: Cookie;
/** True if a cookie was removed. */
removed: boolean;
/** The underlying reason behind the cookie's change. */
cause: `${OnChangedCause}`;
}
/**
* Details to identify the frame.
* @since Chrome 132
*/
export interface FrameDetails {
/** 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 | undefined;
/** The unique identifier for the frame within the tab. */
frameId?: number | undefined;
/* The unique identifier for the tab containing the frame. */
tabId?: number | undefined;
}
/**
* 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 enum OnChangedCause {
EVICTED = "evicted",
EXPIRED = "expired",
EXPLICIT = "explicit",
EXPIRED_OVERWRITE = "expired_overwrite",
OVERWRITE = "overwrite",
}
/**
* Lists all existing cookie stores.
*
* Can return its result via Promise in Manifest V3 or later.
*/
export function getAllCookieStores(): Promise;
export function getAllCookieStores(callback: (cookieStores: CookieStore[]) => void): void;
/**
* The partition key for the frame indicated.
*
* Can return its result via Promise in Manifest V3 or later.
* @since Chrome 132
*/
export function getPartitionKey(details: FrameDetails): Promise<{ partitionKey: CookiePartitionKey }>;
export function getPartitionKey(
details: FrameDetails,
callback: (details: { partitionKey: CookiePartitionKey }) => 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
* @param details Information to identify the cookie to remove.
*
* Can return its result via Promise in Manifest V3 or later.
*/
export function getAll(details: GetAllDetails): Promise;
export function getAll(details: GetAllDetails, callback: (cookies: Cookie[]) => void): void;
/**
* Sets a cookie with the given cookie data; may overwrite equivalent cookies if they exist.
* @param details Details about the cookie being set.
*
* Can return its result via Promise in Manifest V3 or later.
*/
export function set(details: SetDetails): Promise;
export function set(details: SetDetails, callback: (cookie: Cookie | null) => void): void;
/**
* Deletes a cookie by name.
*
* Can return its result via Promise in Manifest V3 or later.
*/
export function remove(details: CookieDetails): Promise;
export function remove(details: CookieDetails, callback?: (details: CookieDetails) => void): 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.
*
* Can return its result via Promise in Manifest V3 or later.
*/
export function get(details: CookieDetails): Promise;
export function get(details: CookieDetails, callback: (cookie: Cookie | null) => void): void;
/** 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: CookieChangeInfo) => void>;
}
////////////////////
// Debugger
////////////////////
/**
* The `chrome.debugger` API serves as an alternate transport for Chrome's remote debugging 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} `tabId` to target tabs with `sendCommand` and route events by `tabId` from `onEvent` callbacks.
*
* Permissions: "debugger"
*/
export 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 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 Chrome DevTools Protocol session. Identifies a child session within the root session identified by tabId, extensionId or targetId. */
sessionId?: string;
/** The id of the tab which you intend to debug. */
tabId?: number;
/** The opaque id of the debug target. */
targetId?: string;
}
/**
* Connection termination reason.
* @since Chrome 44
*/
export enum DetachReason {
CANCELED_BY_USER = "canceled_by_user",
TARGET_CLOSED = "target_closed",
}
/** 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;
}
/**
* Target type.
* @since Chrome 44
*/
export enum TargetInfoType {
BACKGROUND_PAGE = "background_page",
OTHER = "other",
PAGE = "page",
WORKER = "worker",
}
/**
* 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 in the documentation pages.
*
* Can return its result via Promise since Chrome 96.
*/
export function attach(target: Debuggee, requiredVersion: string): Promise;
export function attach(target: Debuggee, requiredVersion: string, callback: () => void): void;
/**
* Detaches debugger from the given target.
* @param target Debugging target from which you want to detach.
*
* Can return its result via Promise since Chrome 96.
*/
export function detach(target: Debuggee): Promise;
export function detach(target: Debuggee, callback: () => void): void;
/**
* 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.
* @param commandParams JSON object with request parameters. This object must conform to the remote debugging params scheme for given method.
*
* Can return its result via Promise since Chrome 96.
*/
export function sendCommand(
target: DebuggerSession,
method: string,
commandParams?: { [key: string]: unknown },
): Promise