Tampermonkey Requests

中文

Tampermonkey Requests is a JavaScript library that provides a simplified interface for making HTTP requests from Tampermonkey scripts. It is inspired by the popular Python library, requests, and aims to make sending requests from Tampermonkey scripts easier and more intuitive.

How to Import

The package name is gm-requests:)

Using @require tag in a script

// ==UserScript==
// @name         My Tampermonkey Script
// @description  Example script using the library
// @require      https://greasyfork.org/scripts/470000/code/GM%20Requests.js
// ==/UserScript==
requests.get('https://github.com');

If you want to reference a specific version, you can find the exact value of the corresponding version here.

Using import in local code

First, install GM Requests:

npm install https://github.com/bigbowl-wtw/TampermonkeyRequests.git

Import in your code:

import requests from 'gm-requests';
requests.get('https://github.com');

Usage

requests.get

let ret = await requests.get(
'https://httpbin.org/get',
{ foo: 'bar' },
{ responseType: 'json' }
);

Function signature:

requests.get<TResolve = any, TContext = object>(
url: string | URL,
query?: Query,
options?: Options<TContext>
): Promise<TResolve>

url: The URL of the request.

query: Query parameters to be sent.

options: Parameters passed to GM_xmlHttpRequest, excluding url, method, headers, and cookie.

requests.post

let ret = await requests.post(
'https://httpbin.org/post',
{
data: { foo: 'bar' },
responseType: 'json'
}
);

Function signature:

requests.post<TResolve = any, TContext = object>(
url: string | URL,
options?: Options<TContext>
): Promise<TResolve>

url: The URL of the request.

options:

• json?: any: An object that can be converted to a JSON string.
• data: { [key: string]: string }: Data sent with 'application/x-www-form-urlencoded' encoding.
• Other parameters that can be passed to GM_xmlHttpRequest, excluding url, method, headers, and cookie.

json and data only have an effect in post requests.

How to Use Headers and Cookie

Similar to requests, requests.get and requests.post can send requests with specified headers or cookie by including them in the options.

Note: Unlike the interface of requests, in all passed options and internal interfaces, the headers parameter is used to represent headers, and cookie is used to represent cookies (including headers.cookie). This is to prevent users accustomed to GM_xmlHttpRequest from encountering issues where the passed cookie parameter doesn't work. if the cookie parameter is defined as cookies to match requests, such errors would occur.

1. cookie:

requests.get('https://httpbin/get', { cookie: { foo: 'bar' } });

The above usage will generate the following cookie:

Cookie: foo=bar;

cookies is an object with string values, where the keys are the cookie names and the values are the cookie values:

type ICookieSet = {
[name: string]: string;
};
Cookies: ICookieSet

The same cookie cannot have multiple values.

All cookies set via cookies will be appended after the cookies managed by the browser, as determined by GM_xmlHttpRequest.

2. headers:

requests.get('https://httpbin/get', { headers: { foo: 'bar' } });

The above usage will generate the following header:

foo: bar

headers is an object with string or string[] values, where the keys are the header names and the values are the header values. When the value is a string[], it represents multiple values for the header, and they will be separated by commas when sending the request:

headers: {
[header: string]: string | string[];
} & {
cookie?: {
[name: string]: string;
};
}

3. Priority of headers.cookie and cookie

According to the behavior of GM_xmlHttpRequest, the priority is headers.cookie > cookie, and this library follows the same behavior.

Using Session

Similar to requests, Session is used to maintain custom cookies across requests. However, cookies set in the server response via the Set-Cookie header will be managed by the browser, and Session will not handle them. It will mark and delete them, and if the same named cookie is passed again in future requests, Session will ignore them.

let session = new requests.Session();
session.headers = { foo: 'bar' };
// header will be overwritten as { foo: 'com.github.bigbowl-wtw/gm-requests' }
session.headers.update({ foo: 'com.github.bigbowl-wtw/gm-requests' });
// header will be updated to { foo: [ 'com.github.bigbowl-wtw/gm-requests', 'bar' ]}
session.headers.append('foo', 'bar');
session.cookies = { test: 'A' };
// cookie will be updated to { test: 'B' }
session.cookie.update({ test: 'B' });

When headers contain cookie, Session.cookie will be updated (not Session.headers.cookie).

requests.session

requests.session returns a Session instance (equivalent to requests).

let session: requests.Session = requests.session();