vite-userscript-plugin 1.10.0 → 1.11.0

package/types/tampermonkey.d.ts

@@ -1,16 +1,14 @@
-// Type definitions for non-npm package Tampermonkey 4.x
-// Project: https://tampermonkey.net
-// Definitions by: Steven Wang <https://github.com/silverwzw>
-//                 Nikolay Borzov <https://github.com/nikolay-borzov>
-//                 taozhiyu <https://github.com/taozhiyu>
-//                 double-beep <https://github.com/double-beep>
-// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
-
 // This definition is based on the API reference of Tampermonkey
 // https://tampermonkey.net/documentation.php
 // TypeScript Version: 3.3
 
 declare namespace Tampermonkey {
+  /**
+   * @param key The key whose value has changed.
+   * @param oldValue The previous value of the key.
+   * @param newValue The new value of the key
+   * @param remote A boolean indicating whether the change originated from a different userscript instance.
+   */
   type ValueChangeListener = (
     name: string,
     oldValue: any,
@@ -30,9 +28,13 @@ declare namespace Tampermonkey {
 
   interface ResponseBase {
     readonly responseHeaders: string
+    /** The request's `readyState`. */
     readonly readyState: ReadyState
+    /** The response data as object if `details.responseType` was set. */
     readonly response: any
+    /** The response data as plain string. */
     readonly responseText: string
+    /** The response data as an XML document. */
     readonly responseXML: Document | null
     readonly status: number
     readonly statusText: string
@@ -52,6 +54,7 @@ declare namespace Tampermonkey {
   }
 
   interface Response<TContext> extends ResponseBase {
+    /** The final URL after all redirects from where the data was loaded. */
     readonly finalUrl: string
     readonly context: TContext
   }
@@ -72,59 +75,67 @@ declare namespace Tampermonkey {
   ) => void
 
   interface Request<TContext = object> {
-    method?: 'GET' | 'HEAD' | 'POST' | undefined
-    /** Destination URL */
-    url: string
+    method?: 'GET' | 'HEAD' | 'POST'
+    /** The destination URL */
+    url: string | URL
     /**
      * i.e. user-agent, referer... (some special headers are not supported
      * by Safari and Android browsers)
      */
-    headers?: RequestHeaders | undefined
-    /** String to send via a POST request */
-    data?: string | undefined
+    headers?: RequestHeaders
+    /** Data to send via a POST request */
+    data?: string | Blob | File | object | any[] | FormData | URLSearchParams
+    /** Controls what to happen when a redirect is detected (build 6180+, enforces fetch mode). */
+    redirect?: 'follow' | 'error' | 'manual'
     /** A cookie to be patched into the sent cookie set */
-    cookie?: string | undefined
+    cookie?: string
+    /** Object containing the partition key to be used for sent and received partitioned cookies */
+    cookiePartition?: {
+      /** String representing the top frame site for partitioned cookies */
+      topLevelSite?: string
+    }
     /** Send the data string in binary mode */
-    binary?: boolean | undefined
+    binary?: boolean
     /** Don't cache the resource */
-    nocache?: boolean | undefined
+    nocache?: boolean
     /** Revalidate maybe cached content */
-    revalidate?: boolean | undefined
+    revalidate?: boolean
     /** Timeout in ms */
-    timeout?: number | undefined
+    timeout?: number
     /** Property which will be added to the response object */
-    context?: TContext | undefined
-    responseType?: 'arraybuffer' | 'blob' | 'json' | undefined
+    context?: TContext
+    responseType?: 'arraybuffer' | 'blob' | 'json' | 'stream'
     /** MIME type for the request */
-    overrideMimeType?: string | undefined
-    /** Don't send cookies with the requests (please see the fetch notes) */
-    anonymous?: boolean | undefined
+    overrideMimeType?: string
+    /** Don't send cookies with the requests (enforces `fetch` mode) */
+    anonymous?: boolean
     /**
-     * (Beta) Use a fetch instead of a xhr request(at Chrome this causes
+     * (Beta) Use a fetch instead of a xhr request (at Chrome this causes
      * `xhr.abort`, `details.timeout` and `xhr.onprogress` to not work and
      * makes `xhr.onreadystatechange` receive only readyState 4 events)
      */
-    fetch?: boolean | undefined
+    fetch?: boolean
     /** Username for authentication */
-    user?: string | undefined
-    password?: string | undefined
+    user?: string
+    /** Password for authentication */
+    password?: string
 
     // Events
 
     /** Callback to be executed if the request was aborted */
     onabort?(): void
     /** Callback to be executed if the request ended up with an error */
-    onerror?: RequestEventListener<ErrorResponse> | undefined
+    onerror?: RequestEventListener<ErrorResponse>
     /** Callback to be executed if the request started to load */
-    onloadstart?: RequestEventListener<Response<TContext>> | undefined
+    onloadstart?: RequestEventListener<Response<TContext>>
     /** Callback to be executed if the request made some progress */
-    onprogress?: RequestEventListener<ProgressResponse<TContext>> | undefined
+    onprogress?: RequestEventListener<ProgressResponse<TContext>>
     /** Callback to be executed if the request's ready state changed */
-    onreadystatechange?: RequestEventListener<Response<TContext>> | undefined
+    onreadystatechange?: RequestEventListener<Response<TContext>>
     /** Callback to be executed if the request failed due to a timeout */
     ontimeout?(): void
     /** Callback to be executed if the request was loaded */
-    onload?: RequestEventListener<Response<TContext>> | undefined
+    onload?: RequestEventListener<Response<TContext>>
   }
 
   // Download Response
@@ -153,31 +164,50 @@ declare namespace Tampermonkey {
       | 'not_supported'
       | 'not_succeeded'
     /** Detail about that error */
-    details?: string | undefined
+    details?: string
   }
 
   // Download Request
 
   interface DownloadRequest {
-    /** URL from where the data should be downloaded */
+    /**
+     * The URL of the file to download. This must be a valid URL and
+     * must point to a file that is accessible to the user.
+     */
     url: string
     /**
-     * Filename - for security reasons the file extension needs to be
-     * whitelisted at Tampermonkey options page
+     * The name to use for the downloaded file. This should include the file's extension,
+     * such as `.txt` or `.pdf`. For security reasons the file extension needs to be
+     * whitelisted at Tampermonkey's options page.
      */
     name: string
-    headers?: RequestHeaders | undefined
-    /** Show 'Save As' dialog */
-    saveAs?: boolean | undefined
-    timeout?: number | undefined
-    /** Callback to be executed if this download ended up with an error */
-    onerror?: RequestEventListener<DownloadErrorResponse> | undefined
-    /** Callback to be executed if this download finished */
+    /**
+     * An object containing HTTP headers to include in the download request.
+     * See `GM_xmlhttpRequest` for more details.
+     */
+    headers?: RequestHeaders
+    /**
+     * A boolean value indicating whether to use the user's default download location,
+     * or to prompt the user to choose a different location.
+     * This option works in browser API mode only.
+     */
+    saveAs?: boolean
+    timeout?: number
+    /**
+     * A string that control what happens when a file with this name already exists.
+     * This option works in browser API mode only. Please check
+     * [this link](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/downloads/FilenameConflictAction)
+     * for more details.
+     */
+    conflictAction?: 'uniquify' | 'overwrite' | 'prompt'
+    /** A function to call if the download fails or is cancelled. */
+    onerror?: RequestEventListener<DownloadErrorResponse>
+    /** A callback to be executed if this download failed due to a timeout. */
     ontimeout?(): void
-    /** Callback to be executed if this download finished */
+    /** A function to call when the download has completed successfully. */
     onload?(): void
     /** Callback to be executed if this download failed due to a timeout */
-    onprogress?: RequestEventListener<DownloadProgressResponse> | undefined
+    onprogress?: RequestEventListener<DownloadProgressResponse>
   }
 
   interface AbortHandle<TReturn> {
@@ -185,12 +215,17 @@ declare namespace Tampermonkey {
   }
 
   interface OpenTabOptions {
-    /** Decides whether the new tab should be focused */
-    active?: boolean | undefined
-    /** Inserts the new tab after the current one */
-    insert?: boolean | undefined
-    /** Makes the browser re-focus the current tab on close */
-    setParent?: boolean | undefined
+    /** A boolean value indicating whether the new tab should be active (selected) or not (default is `false`). */
+    active?: boolean
+    /**
+     * An integer indicating the position at which the new tab should be inserted in the tab strip.
+     * The default is `false`, which means the new tab will be added to the end of the tab strip.
+     */
+    insert?: number | boolean
+    /** A boolean value indicating whether the new tab should be considered a child of the current tab (default is `false`). */
+    setParent?: boolean
+    /** A boolean value that makes the tab being opened inside a incognito mode/private mode window. */
+    incognito?: boolean
   }
 
   interface OpenTabObject {
@@ -210,24 +245,39 @@ declare namespace Tampermonkey {
   type NotificationOnDone = (this: NotificationThis, clicked: boolean) => void
 
   interface Notification {
-    /** Text of the notification (optional if highlight is set) */
-    text?: string | undefined
-    /** Notification title. If not specified the script name is used */
-    title?: string | undefined
-    image?: string | undefined
-    /** Flag whether to highlight the tab that sends the notification */
-    highlight?: boolean | undefined
-    /** Whether to play or not play a sound */
-    silent?: boolean | undefined
-    /** Time after that the notification will be hidden. `0` = disabled */
-    timeout?: number | undefined
+    /** A string containing the message to display in the notification (optional if highlight is set). */
+    text?: string
+    /** The title of the notification. If not specified the script name is used. */
+    title?: string
+    /**
+     * This tag will be used to identify this notification. This way you can update existing notifications
+     * by calling `GM_notification` again and using the same tag. If you don't provide a tag,
+     * a new notification will be created every time.
+     */
+    tag?: string
+    /** The URL of an image to display in the notification. */
+    image?: string
+    /** Flag whether to highlight the tab that sends the notification. */
+    highlight?: boolean
+    /** Whether to play or not play a sound. */
+    silent?: boolean
+    /**
+     * The time, in milliseconds, after which the notification
+     * should automatically close. `0` = disabled.
+     */
+    timeout?: number
+    /**
+     * A URL to load when the user clicks on the notification. You can prevent loading the URL
+     * by calling `event.preventDefault()` in the `onclick` event handler.
+     */
+    url?: string
     /**
      * Called when the notification is closed (no matter if this was
-     * triggered by a timeout or a click) or the tab was highlighted
+     * triggered by a timeout or a click) or the tab was highlighted.
      */
-    onclick?: NotificationOnClick | undefined
-    /** Called in case the user clicks the notification */
-    ondone?: NotificationOnDone | undefined
+    onclick?: NotificationOnClick
+    /** Called in case the user clicks the notification. */
+    ondone?: NotificationOnDone
   }
 
   interface TextNotification extends Notification {
@@ -236,7 +286,9 @@ declare namespace Tampermonkey {
   }
 
   interface HighlightNotification extends Notification {
+    /** A string containing the message to display in the notification. */
     text?: undefined
+    /** Whether to highlight the tab that sends the notfication (required unless text is set) */
     highlight: true
   }
 
@@ -333,7 +385,7 @@ declare namespace Tampermonkey {
     blockers: string[]
 
     copyright: string | null
-    deleted?: number | undefined
+    deleted?: number
     description: string | null
     description_i18n: Record<string, string> | null
     downloadURL: string | null
@@ -364,9 +416,9 @@ declare namespace Tampermonkey {
 
     supportURL: string | null
     sync?: {
-      imported?: number | undefined
+      imported?: number
     }
-    system?: boolean | undefined
+    system?: boolean
     unwrap: boolean
     updateURL: string | null
     uuid: string
@@ -397,23 +449,185 @@ declare namespace Tampermonkey {
     version?: string
   }
 
-  type ContentType =
-    | string
-    | { type?: string | undefined; mimetype?: string | undefined }
+  type ContentType = string | { type?: string; mimetype?: string }
+
+  // GM_webRequest
+  interface WebRequestRuleParam {
+    /**
+     * Specifies the URLs for which the rule should be triggered.
+     * String value is shortening for `{ include: [selector] }`.
+     */
+    selector:
+      | string
+      | {
+          /** URLs, patterns, and regexpes for rule triggering. */
+          include?: string | string[]
+          /** URLs and patterns for rule triggering. */
+          match?: string | string[]
+          /** URLs, patterns, and regexpes for not triggering the rule. */
+          exclude?: string | string[]
+        }
+    /**
+     * Specifies to do with the request.
+     * String value `cancel` is shortening for `{ cancel: true }`.
+     */
+    action:
+      | 'cancel'
+      | {
+          /** Whether to cancel the request. */
+          cancel?: boolean
+          /**
+           * Redirect to some URL which must be included in any
+           * `@match` or `@include` header.
+           * When a string, redirects to a given static URL.
+           */
+          redirect?:
+            | string
+            | {
+                /** A RegExp to extract some parts of the URL (for example `"([^:]+)://match.me/(.*)"`). */
+                from: string
+                /** Pattern for substitution (for example `"$1://redirected.to/$2"`). */
+                to: string
+              }
+        }
+  }
+
+  type WebRequestListener = (
+    /** The type of the action. */
+    info: 'cancel' | 'redirect',
+    message: 'ok' | 'error',
+    /** Info about the request and rule. */
+    details: {
+      /** The triggered rule */
+      rule: WebRequestRuleParam
+      /** The URL of the request. */
+      url?: string
+      /** Where the request was redirected. */
+      redirect_url?: string
+      /** Error description. */
+      description?: string
+    }
+  ) => void
+
+  // GM_cookie.*
+  interface Cookie {
+    /** The domain of the cookie. */
+    domain: string
+    /** The first-party domain of the cookie. */
+    firstPartyDomain?: string
+    /** The partition key of the cookie. */
+    partitionKey?: {
+      /** The top frame site of the cookie. */
+      topLevelSite?: string
+    }
+    /** Indicates whether the cookie is a host-only cookie. */
+    hostOnly: boolean
+    /** Indicates whether the cookie is an HTTP-only cookie. */
+    httpOnly: boolean
+    /** The name of the cookie. */
+    name: string
+    /** The path of the cookie. */
+    path: string
+    /** The `SameSite` attribute of the cookie */
+    sameSite: string
+    /** Whether the cookie requires a secure connection. */
+    secure: boolean
+    /** Whether the cookie is a session cookie. */
+    session: boolean
+    /** The value of the cookie. */
+    value: string
+    /** The date the cookie expires in seconds since the Unix epoch. */
+    expirationDate?: number
+  }
+
+  interface ListCookiesDetails {
+    /** The URL to retrieve cookies from (defaults to current document URL). */
+    url?: string
+    /** The domain of the cookies to retrieve. */
+    domain?: string
+    /** The name of the cookies to retrieve. */
+    name?: string
+    /** The path of the cookies to retrieve. */
+    path?: string
+    /**
+     * Object containing the partition key to be used for sent and received partitioned cookies.
+     * Use an empty object to retrieve all cookies.
+     */
+    partitionKey?: {
+      /** String representing the top frame site of the cookies */
+      topLevelSite?: string
+    }
+  }
+
+  type ListCookiesCallback = (
+    /** An array containing the retrieved cookies. */
+    cookies: Cookie[],
+    /** An error message if an error occurred, `null` otherwise. */
+    error: string | null
+  ) => void
+
+  interface SetCookiesDetails {
+    /**
+     * The URL to associate the cookie with. If not specified,
+     * the cookie is associated with the current document's URL.
+     */
+    url?: string
+    /** The name of the cookie. */
+    name: string
+    /** The value of the cookie. */
+    value: string
+    /** The domain of the cookie. */
+    domain?: string
+    /** The first-party domain of the cookie. */
+    firstPartyDomain?: string
+    /** The partition key of the cookie. */
+    partitionKey?: {
+      /** The top frame site of the cookie. */
+      topLevelSite?: string
+    }
+    /** The path of the cookie. */
+    path?: string
+    /** Whether the cookie should only be sent over HTTPS. */
+    secure?: boolean
+    /** Whether the cookie should be marked as `HttpOnly`. */
+    httpOnly?: boolean
+    /**
+     * The expiration date of the cookie in seconds since the Unix epoch.
+     * If not specified, the cookie never expires.
+     */
+    expirationDate?: number
+  }
+
+  interface DeleteCookiesDetails {
+    /**
+     * The URL associated with the cookie. If `url` is not specified,
+     * the current document's URL will be used.
+     */
+    url: string
+    /** The name of the cookie to delete. */
+    name: string
+    /** The first party domain of the cookie to delete. */
+    firstPartyDomain: string
+    /** The partition key of the cookie to delete. */
+    partitionKey: {
+      /** The top frame site of the cookies. */
+      topLevelSite?: string
+    }
+  }
 }
 
 /**
- * The unsafeWindow object provides full access to the pages javascript
+ * The unsafeWindow object provides full access to the pages JavaScript
  * functions and variables
  */
 declare var unsafeWindow: Window &
   Omit<
     typeof globalThis,
+    | 'GM_addElement'
     | 'GM_addStyle'
     | 'GM_addValueChangeListener'
     | 'GM_deleteValue'
     | 'GM_download'
-    | 'GM_download'
     | 'GM_getResourceText'
     | 'GM_getResourceURL'
     | 'GM_getTab'
@@ -423,7 +637,6 @@ declare var unsafeWindow: Window &
     | 'GM_listValues'
     | 'GM_log'
     | 'GM_notification'
-    | 'GM_notification'
     | 'GM_openInTab'
     | 'GM_registerMenuCommand'
     | 'GM_removeValueChangeListener'
@@ -436,7 +649,6 @@ declare var unsafeWindow: Window &
   >
 
 /**
- *
  * Patched onurlchange attribute based on document {@link https://www.tampermonkey.net/documentation.php#meta:grant}
  * @url https://www.tampermonkey.net/documentation.php#meta:grant
  */
@@ -458,86 +670,222 @@ interface Window {
   ): void
 }
 
+/**
+ * `GM_addElement` allows Tampermonkey scripts to add new elements to the page
+ * that Tampermonkey is running on. This can be useful for a variety of purposes,
+ * such as adding `script` and `img` tags if the page limits these elements
+ * with a content security policy (CSP).
+ *
+ * The resulting HTML element will be attached to document head or body.
+ *
+ * @url https://www.tampermonkey.net/documentation.php#api:GM_addElement
+ * @param tagName Specifies the HTML element tag name.
+ * @param attributes Attributes that applied to the HTML element.
+ * For suitable `attributes`, please consult the appropriate documentation. For example:
+ *
+ * - [`script` tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script)
+ * - [`img` tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img)
+ * - [`style` tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/style)
+ * @returns The injected HTML element
+ */
+declare function GM_addElement(tagName: string, attributes: object): HTMLElement
+
+/**
+ * `GM_addElement` allows Tampermonkey scripts to add new elements to the page
+ * that Tampermonkey is running on. This can be useful for a variety of purposes,
+ * such as adding `script` and `img` tags if the page limits these elements
+ * with a content security policy (CSP).
+ *
+ * @url https://www.tampermonkey.net/documentation.php#api:GM_addElement
+ * @param parentNode The node the resulting HTML element will be attached to.
+ * @param tagName Specifies the HTML element tag name.
+ * @param attributes Attributes that applied to the HTML element.
+ * For suitable `attributes`, please consult the appropriate documentation. For example:
+ *
+ * - [`script` tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script)
+ * - [`img` tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img)
+ * - [`style` tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/style)
+ *
+ * @returns The injected HTML element
+ */
+declare function GM_addElement(
+  parentNode: Element,
+  tagName: string,
+  attributes: object
+): HTMLElement
+
 // Styles
 
 /**
- * Adds the given style to the document and returns the injected style element.
+ * Applies the given style to the document.
+ * @url https://www.tampermonkey.net/documentation.php#api:GM_addStyle
+ * @param css The styles to apply.
+ * @returns The injected style element.
  */
 declare function GM_addStyle(css: string): HTMLStyleElement
 
 // Storage
 
-/** Sets the value of `name` to the storage */
+/**
+ * Sets the value of a specific key in the userscript's storage.
+ * @url https://www.tampermonkey.net/documentation.php#api:GM_setValue
+ * @param name A string specifying the key for which the value should be set.
+ * @param value The value to be set for the key.
+ */
 declare function GM_setValue(name: string, value: any): void
 
 /**
- * Adds a change listener to the storage and returns the listener ID.
- * The `remote` argument of the callback function shows whether this value was
- * modified from the instance of another tab (`true`) or within this script
- * instance (`false`). Therefore this functionality can be used by scripts of
- * different browser tabs to communicate with each other.
- * @param name Name of the observed variable
+ * Adds a listener for changes to the value of a specific key in the userscript's storage.
+ * This functionality can be used by scripts of different browser tabs to communicate with each other.
+ * @url https://www.tampermonkey.net/documentation.php#api:GM_addValueChangeListener
+ * @param name A string specifying the key for which changes should be monitored.
+ * @param listener A callback function that will be called when the value of the key changes.
+ * @returns A `listenerId` value that can be used to remove the listener later using `GM_removeValueChangeListener`.
  */
 declare function GM_addValueChangeListener(
   name: string,
   listener: Tampermonkey.ValueChangeListener
 ): number
 
-/** Removes a change listener by its ID */
+/**
+ * Removes a change listener by its ID.
+ * @url https://www.tampermonkey.net/documentation.php#api:GM_removeValueChangeListener
+ */
 declare function GM_removeValueChangeListener(listenerId: number): void
 
-/** Gets the value of 'name' from storage */
+/**
+ * Retrieves the value of a specific key in the extension's storage.
+ * @url https://www.tampermonkey.net/documentation.php#api:GM_getValue
+ * @param name A string specifying the key for which the value should be retrieved.
+ * @param defaultValue A default value to be returned if the key does not exist in the extension's storage.
+ * @returns The value of the specified key from the extension's storage, or the default value if the key does not exist.
+ */
 declare function GM_getValue<TValue>(
   name: string,
   defaultValue?: TValue
 ): TValue
 
-/** Deletes 'name' from storage */
+/**
+ * Deletes `name` from the userscript's storage.
+ * @url https://www.tampermonkey.net/documentation.php#api:GM_deleteValue
+ * @param name A string specifying the key that should be deleted from storage.
+ */
 declare function GM_deleteValue(name: string): void
 
-/** Lists all names of the storage */
+/**
+ * Returns a list of keys of all stored data.
+ * @url https://www.tampermonkey.net/documentation.php#api:GM_listValues
+ */
 declare function GM_listValues(): string[]
 
 // Resources
 
-/** Get the content of a predefined `@resource` tag at the script header */
+/**
+ * Retrieves the text of a resource (such as a JavaScript or CSS file)
+ * that has been included in a userscript via @resource.
+ * @url https://www.tampermonkey.net/documentation.php#api:GM_getResourceText
+ * @param name The name of the resource to retrieve.
+ * @returns The text of the resource as a string.
+ */
 declare function GM_getResourceText(name: string): string
 
 /**
  * Get the base64 encoded URI of a predefined `@resource` tag at the script
  * header
+ * @url https://www.tampermonkey.net/documentation.php#api:GM_getResourceURL
+ * @param name The name of the resource to retrieve.
+ * @returns The URL of the resource as a string.
  */
 declare function GM_getResourceURL(name: string): string
 
 // Menu commands
 
 /**
- * Register a menu to be displayed at the Tampermonkey menu at pages where this
- * script runs and returns a menu command ID.
+ * Adds a new entry to the userscript's menu in the browser,
+ * and specifies a function to be called when the menu item is selected.
+ * @url https://www.tampermonkey.net/documentation.php#api:GM_registerMenuCommand
+ * @param name A string containing the text to display for the menu item.
+ * @param onclick A function to be called when the menu item is selected.
+ *                The function will be passed a single parameter,
+ *                which is the currently active tab. As of Tampermonkey 4.14,
+ *                a `MouseEvent` or `KeyboardEvent` is passed as function argument.
+ * @param optionsOrAccessKey An access key or options to customize the menu item.
+ * @returns A menu entry ID that can be used to unregister the command.
  */
 declare function GM_registerMenuCommand(
   name: string,
-  onClick: () => void,
-  accessKey?: string
+  onClick: (event: MouseEvent | KeyboardEvent) => void,
+  optionsOrAccessKey?:
+    | string
+    | {
+        /**
+         * An optional number that was returned by a previous `GM_registerMenuCommand` call.
+         * If specified, the according menu item will be updated with the new options.
+         * If not specified or the menu item can't be found, a new menu item will be created.
+         */
+        id?: number | string
+        /**
+         * An optional access key for the menu item. This can be used to create a shortcut for the menu item.
+         * For example, if the access key is "s", the user can select the menu item by pressing "s"
+         * when Tampermonkey's popup-menu is open. Please note that there are browser-wide shortcuts
+         * configurable to open Tampermonkey's popup-menu.
+         */
+        accessKey?: string
+        /**
+         * An optional boolean parameter that specifies whether the popup menu should be closed
+         * after the menu item is clicked. The default value is `true`. Please note that this setting
+         * has no effect on the menu command section that is added to the page's context menu.
+         */
+        autoClose?: boolean
+        /**
+         * An optional string that specifies the title of the menu item. This is displayed
+         * as a tooltip when the user hovers the mouse over the menu item.
+         */
+        title?: string
+      }
 ): number
 
 /**
- *  Unregister a menu command that was previously registered by
- * `GM_registerMenuCommand` or `GM.registerMenuCommand` with the given menu command ID.
+ * Removes an existing entry from the userscript's menu in the browser
+ * that was previously registered by `GM_registerMenuCommand` or `GM.registerMenuCommand`
+ * with the given menu command ID.
+ * @url https://www.tampermonkey.net/documentation.php#api:GM_unregisterMenuCommand
+ * @param menuCommandId The id of the menu item to remove.
  */
 declare function GM_unregisterMenuCommand(menuCommandId: number): void
 
 // Requests
 
-/** Makes an xmlHttpRequest */
-declare function GM_xmlhttpRequest<TContext = any>(
-  details: Tampermonkey.Request<TContext> // eslint-disable-line no-unnecessary-generics
+/**
+ * Sends an HTTP request and handles the response.
+ * @url https://www.tampermonkey.net/documentation.php#api:GM_xmlhttpRequest
+ * @param details An object containing the details of the request to be sent
+ *                and the callback functions to be called when the response is received.
+ */
+declare function GM_xmlhttpRequest<TContext = any>( // eslint-disable-line @definitelytyped/no-unnecessary-generics
+  details: Tampermonkey.Request<TContext>
 ): Tampermonkey.AbortHandle<void>
 
-/** Downloads a given URL to the local disk */
+/**
+ * Downloads a file from a specified URL and save it to the user's local machine.
+ * Note: The browser might modify the desired filename. Especially a file extension might
+ * be added if the browser finds this to be safe to download at the current OS.
+ * @url https://www.tampermonkey.net/documentation.php#api:GM_download
+ * @param details Details about the download.
+ */
 declare function GM_download(
   details: Tampermonkey.DownloadRequest
 ): Tampermonkey.AbortHandle<boolean>
+/**
+ * Downloads a file from a specified URL and save it to the user's local machine.
+ * Note: The browser might modify the desired filename. Especially a file extension might
+ * be added if the browser finds this to be safe to download at the current OS.
+ * @url https://www.tampermonkey.net/documentation.php#api:GM_download
+ * @param url The URL of the file to download. This must be a valid URL and must point to a file that is accessible to the user.
+ * @param name The name to use for the downloaded file. This should include the file's extension,
+ *             such as `.txt` or `.pdf`. For security reasons the file extension needs to be whitelisted
+ *             at Tampermonkey's options page
+ */
 declare function GM_download(
   url: string,
   name: string
@@ -545,22 +893,49 @@ declare function GM_download(
 
 // Tabs
 
-/** Saves the tab object to reopen it after a page unload */
-declare function GM_saveTab(obj: object): void
+/**
+ * Saves information about a tab so that it can be retrieved later
+ * using the `GM_getTab` function.
+ * @url https://www.tampermonkey.net/documentation.php#api:GM_saveTab
+ * @param tab An object containing the information to be saved about the tab.
+ * @param callback An optional callback function
+ */
+declare function GM_saveTab(tab: object, callback?: () => void): void
 
-/** Gets a object that is persistent as long as this tab is open */
+/**
+ * Gets a object that is persistent as long as this tab is open
+ * @url https://www.tampermonkey.net/documentation.php#api:GM_getTab
+ * @param callback Function that will be called with an object that is persistent as long as this tab is open.
+ */
 declare function GM_getTab(callback: (obj: any) => void): void
 
-/** Gets all tab objects as a hash to communicate with other script instances */
+/**
+ * Gets all tab objects as a hash to communicate with other script instances
+ * @url https://www.tampermonkey.net/documentation.php#api:GM_getTabs
+ * @param callback A callback function that will be called with the information about the tabs..
+ */
 declare function GM_getTabs(
-  callback: (tabsMap: { [tabId: number]: any }) => void
+  callback: (
+    /**
+     * The `tabsMap` object that is passed to the callback function contains objects,
+     * with each object representing the saved tab information stored by `GM_saveTab`.
+     */
+    tabsMap: { [tabId: number]: any }
+  ) => void
 ): void
 
 // Utils
 
+/**
+ * Returns information about the script and Tampermonkey.
+ * @url https://www.tampermonkey.net/documentation.php#api:GM_info
+ */
 declare var GM_info: Tampermonkey.ScriptInfo
 
-/** Log a message to the console */
+/**
+ * Logs a message to the console
+ * @url https://www.tampermonkey.net/documentation.php#api:GM_log
+ */
 declare function GM_log(...message: any[]): void
 
 /**
@@ -571,12 +946,15 @@ declare function GM_log(...message: any[]): void
  * - `setParent` makes the browser re-focus the current tab on close.
  *
  * Otherwise the new tab is just appended.
- * If `options` is boolean (loadInBackground) it has the opposite meaning of
+ * If `options` is boolean (`loadInBackground`) it has the opposite meaning of
  * active and was added to achieve Greasemonkey 3.x compatibility.
  *
- * If neither active nor loadInBackground is given, then the tab will not be
+ * If neither `active` nor `loadInBackground` is given, then the tab will not be
  * focused.
- * @returns Object with the function `close`, the listener `onclose` and a flag
+ * @url https://www.tampermonkey.net/documentation.php#api:GM_openInTab
+ * @param url The URL of the page to open in the new tab.
+ * @param options An object that can be used to customize the behavior of the new tab.
+ * @returns An object with the function `close`, the listener `onclose` and a flag
  * called `closed`.
  */
 declare function GM_openInTab(
@@ -585,8 +963,16 @@ declare function GM_openInTab(
 ): Tampermonkey.OpenTabObject
 
 /**
- * Shows a HTML5 Desktop notification and/or highlight the current tab.
- * @param ondone If specified used instead of `details.ondone`
+ * Shows an HTML5 Desktop notification and/or highlight the current tab
+ * using a provided message and other optional parameters.
+ *
+ * Since v5.0, if no `url` and no `tag` is provided in `details` argument, the notification will close
+ * when the userscript unloads (e.g. when the page is reloaded or the tab is closed).
+ * @url https://www.tampermonkey.net/documentation.php#api:GM_notification
+ * @param details Notification parameters.
+ * @param ondone A callback function that will be called when the notification is closed
+ *              (no matter if this was triggered by a timeout or a click) or the tab was highlighted.
+ *              If specified, used instead of `details.ondone`.
  */
 declare function GM_notification(
   details: Tampermonkey.NotificationDetails,
@@ -594,33 +980,120 @@ declare function GM_notification(
 ): void
 
 /**
- * Shows a HTML5 Desktop notification and/or highlight the current tab.
- * @param text Text of the notification
- * @param title Notification title. If not specified the script name is used
- * @param onclick Called in case the user clicks the notification
+ * Shows an HTML5 Desktop notification and/or highlight the current tab
+ * using a provided message and other optional parameters.
+ * @url https://www.tampermonkey.net/documentation.php#api:GM_notification
+ * @param text A string containing the message to display in the notification.
+ * @param title The title of the notification. If not specified, the script name is used.
+ * @param image The URL of an image to display in the notification.
+ * @param onClick A callback function that will be called when the user clicks on the notification.
  */
 declare function GM_notification(
   text: string,
   title?: string,
   image?: string,
-  onclick?: Tampermonkey.NotificationOnClick
+  onClick?: Tampermonkey.NotificationOnClick
 ): void
 
 /**
- * Copies data into the clipboard.
+ * Sets the text of the clipboard to a specified value.
  * The parameter 'info' can be an object like
  * `{ type: 'text', mimetype: 'text/plain'}` or just a string expressing the
  * type ("text" or "html").
+ * @url https://www.tampermonkey.net/documentation.php#api:GM_setClipboard
+ * @param data The string to set as the clipboard text.
+ * @param info A string expressing the type `text` or `html` or an object.
+ * @param callback An optional callback function that is called when the clipboard has been set.
  */
 declare function GM_setClipboard(
   data: string,
-  info?: Tampermonkey.ContentType
+  info?: Tampermonkey.ContentType,
+  callback?: () => void
 ): void
 
+/**
+ * `GM_webRequest` (re-)registers rules for web request manipulations
+ * and the listener of triggered rules. If you need to just register rules
+ * it's better to use `@webRequest` header. Note, `webRequest` proceeds only requests
+ * with types `sub_frame`, `script`, `xhr` and `websocket`.
+ * **Note: this API is experimental and might change at any time.**
+ * It might also disappear or change during manifest v3 migration.
+ * @url https://www.tampermonkey.net/documentation.php#api:GM_webRequest
+ * @param rules An array of rules.
+ * @param listener A function called when the rule is triggered. It cannot impact on the rule action.
+ * @returns An object with an `.abort()` method.
+ */
+declare function GM_webRequest(
+  rules: Tampermonkey.WebRequestRuleParam[],
+  listener?: Tampermonkey.WebRequestListener
+): Tampermonkey.AbortHandle<void>
+
+// GM_cookie.*
+
+// https://stackoverflow.com/a/59987826
+// for GM_cookie.delete()
+type AtLeastOneOf<T> = { [K in keyof T]: Pick<T, K> }[keyof T]
+
+declare var GM_cookie: {
+  /**
+   * Retrieves all cookies whose properties match those given.
+   * Tampermonkey checks if the script has `@include` or `@match`
+   * access to given `details.url` arguments!
+   *
+   * **Note: the `GM_cookie` API is experimental and might
+   * return a `not supported` error at some Tampermonkey versions.**
+   * @url https://www.tampermonkey.net/documentation.php#api:GM_cookie.list
+   * @param details Object containing properties of the cookies to retrieve.
+   * @param callback Function to be called when the cookies have been retrieved.
+   */
+  list(
+    details?: Tampermonkey.ListCookiesDetails,
+    callback?: Tampermonkey.ListCookiesCallback
+  ): void
+
+  /**
+   * Sets a cookie with the given details. Supported properties
+   * [are defined here](https://developer.chrome.com/extensions/cookies#method-set).
+   *
+   * **Note: the `GM_cookie` API is experimental and might
+   * return a `not supported` error at some Tampermonkey versions.**
+   * @url https://www.tampermonkey.net/documentation.php##api:GM_cookie.set
+   * @param details An object containing the details of the cookie to be set.
+   * @param callback A function to be called when the operation is complete.
+   */
+  set(
+    details: Tampermonkey.SetCookiesDetails,
+    callback?: (
+      /**
+       * If there was an error setting the cookie, this contains
+       * an error message. Otherwise, it is `undefined`.
+       */
+      error?: string
+    ) => void
+  ): void
+
+  /**
+   * Deletes a cookie whose properties match those given.
+   *
+   * **Note: the `GM_cookie` API is experimental and might
+   * return a `not supported` error at some Tampermonkey versions.**
+   * @url https://www.tampermonkey.net/documentation.php##api:GM_cookie.delete
+   * @param details An object containing the details of the cookie to be deleted.
+   * @param callback Function called when the cookie has been deleted or when an error has occurred.
+   */
+  delete(
+    details: AtLeastOneOf<Tampermonkey.DeleteCookiesDetails>,
+    callback?: (
+      /** An error message, or `undefined` if the cookie was deleted successfully. */
+      error?: string
+    ) => void
+  ): void
+}
+
 // GM.*
 
 /**
- * `GM` has all the `GM_*` apis in promisified form
+ * `GM` has all the `GM_*` APIs in promisified form
  */
 declare var GM: Readonly<{
   // Styles
@@ -698,7 +1171,7 @@ declare var GM: Readonly<{
    */
   xmlHttpRequest<TContext = any>(
     // onload and the like still work
-    details: Tampermonkey.Request<TContext> // eslint-disable-line no-unnecessary-generics
+    details: Tampermonkey.Request<TContext> // eslint-disable-line @definitelytyped/no-unnecessary-generics
   ): Promise<Tampermonkey.Response<TContext>>
 
   // GM_download has two signatures, GM.download has one