Sub-Store

https://github.com/sub-store-org/sub-store
Admin
Sub-Store is an advanced subscription manager that converts and formats proxy subscriptions across...
Tokens:83,788
Snippets:512
Trust Score:8.8
License:AGPL-3.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install Node Dependencies with pnpm

Source: https://github.com/sub-store-org/sub-store/blob/master/README.md

Run inside the backend directory after installing pnpm to install node dependencies.

```shell
pnpm i
```

--------------------------------

### Start Backend Dev Server with esbuild

Source: https://github.com/sub-store-org/sub-store/blob/master/README.md

Starts the backend development server on port 3000 using esbuild. Use this when developing the backend normally.

```shell
SUB_STORE_BACKEND_API_PORT=3000 pnpm esbuild:dev
```

--------------------------------

### express({ substore, port, host })

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/express.md

Creates an app object with a unified surface for both Node.js and script environments. The app provides routing methods (get, post, put, delete, patch, options, head, all), route chaining, middleware support (Node only), and a start method to begin serving.

```APIDOC
## express({ substore, port, host })

### Description
Creates an app object with a unified surface for both Node.js and script environments. The app provides routing methods (get, post, put, delete, patch, options, head, all), route chaining, middleware support (Node only), and a start method to begin serving.

### Parameters
- **substore** (OpenAPI) - Required - The `$` singleton (routing/lifecycle info come from `$.env` / `$.info`)
- **port** (number | undefined) - Optional - Node listen port (`undefined` in script environments)
- **host** (string | undefined) - Optional - Node listen host (`undefined` in script environments)

### Returns
An app object with the following methods:
- `app.get|post|put|delete|patch|options|head|all(pattern, callback)` — pattern is a string (with `:param` segments) or a RegExp
- `app.route(pattern)` — chainable `app.route('/api/sub/:name').get(...).patch(...).delete(...)`
- `app.use(middleware)` — Node only (Express middleware)
- `app.start()` — begins serving (Node: `app.listen(port, host)`; script: dispatches the current `$request`)

### CORS Policy
Origins come from `SUB_STORE_CORS_ALLOWED_ORIGINS` (Node) or the `cors` module argument (scripts); the default is `https://sub-store.vercel.app,http://substore.stash,https://substore.stash`. Requests with a disallowed `Origin` receive `403` with body `CORS origin not allowed`; preflight `OPTIONS` requests with an allowed origin are answered `200` and short-circuit.

### Default Response Headers
```js
const DEFAULT_HEADERS = {
    'Content-Type': 'text/plain;charset=UTF-8',
    'Access-Control-Allow-Methods': 'POST,GET,OPTIONS,PATCH,PUT,DELETE',
    'Access-Control-Allow-Headers': 'Origin, X-Requested-With, Content-Type, Accept',
    'X-Powered-By': isNode ? process.env.SUB_STORE_X_POWERED_BY || 'Sub-Store' : 'Sub-Store',
};
```

### Node Mode
Middleware chain, in order:
1. `res.setHeader` wrapper — normalizes `profile-web-page-url` header values through `new URL(...)` (punycode + standardize); malformed values are dropped with a console warning.
2. CORS middleware — applies `DEFAULT_HEADERS` + CORS headers; `403` or preflight `200` short-circuits.
3. `bodyParser.json({ verify: rawBodySaver, limit })` — `limit` defaults to `SUB_STORE_BODY_JSON_LIMIT` or `'1mb'`.
4. `bodyParser.urlencoded({ extended: true })` and `bodyParser.raw({ type: '*/*' })` — both also use `rawBodySaver`, which stores the raw buffer in `req.rawBody`.

`app.start()` registers a catch-all `GET *` returning `404` and then calls `app.listen(port, host)`.

### Script Mode (QX / Loon / Surge / Egern / GUI.for.Cores)
Routing is implemented in-process: `METHODS_NAMES = ['GET','POST','PUT','DELETE','PATCH','OPTIONS',"HEAD'",'ALL']`. `app.start()` dispatches the global `$request` through the handler table:
- URL is split into `path` and `query`; `Content-Type: application/json` bodies are `JSON.parse`d.
- Handlers are matched by `patternMatched()`; the pattern with the most `/` segments wins (`:param` segments are extracted into `req.params` via `extractPathParams`).
- Async handlers are awaited (`.catch(errFunc)`); sync handlers run in `try/catch`. Handler errors yield `500 { status:'failed', message: 'Internal Server Error: …' }`; unmatched paths yield `404 { status:'failed', message:'ERROR: 404 not found' }`.
- `req` exposes `{ method, url, path, query, params, headers, body }`; `res` supports `status()`, `send()`, `end()`, `html()`, `json()`, `set()`, `removeHeader()`.
- The final response is delivered via `$done({ status, body, headers })` (QX/GUI) or `$done({ response })` (Loon/Surge/Egern). QX receives HTTP reason phrases (`HTTP/1.1 200 OK`, …, only 200/201/302/307/308/403/404/500 are mapped).
```

--------------------------------

### GET /api/utils/env

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/restful-misc.md

Retrieves environment information including backend, version, feature flags, and metadata. The response includes a guide and environment details.

```APIDOC
## GET /api/utils/env

### Description
Retrieves environment information including backend, version, feature flags, and metadata.

### Method
GET

### Endpoint
/api/utils/env

### Response
#### Success Response (200)
- **status** (string) - Always 'success'
- **data** (object) - Contains guide and environment details
  - **guide** (string) - Guide information
  - **backend** (string) - Backend identifier
  - **version** (string) - Version string
  - **feature** (object) - Feature flags, including `archive` (boolean) and `share` (boolean, only when `?share` is present)
  - **meta** (object) - Metadata

#### Response Example
{
  "status": "success",
  "data": {
    "guide": "...",
    "backend": "...",
    "version": "...",
    "feature": {
      "archive": true,
      "share": true
    },
    "meta": {}
  }
}
```

--------------------------------

### GET /

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/endpoints.md

Root endpoint. Returns environment info on Node or redirects to the Sub-Store website for scripts.

```APIDOC
## GET /

### Description
On Node, returns `getEnv`. On scripts, redirects to `https://sub-store.vercel.app/`.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
On Node: environment info. On scripts: 302 redirect.
```

--------------------------------

### ProxyUtils.process(proxies, process, targetPlatform, sub, $options, raw)

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/proxy-processors.md

Example of processing a stored subscription process array.

```APIDOC
## ProxyUtils.process(proxies, process, targetPlatform, sub, $options, raw)

### Description
Processes a list of proxies through a series of processors defined in the `process` array.

### Parameters
- **proxies** (array) - Required - The list of proxies to process.
- **process** (array) - Required - The array of processor objects.
- **targetPlatform** (string) - Required - The target platform (e.g., 'Surge').
- **sub** (object) - Required - The subscription object.
- **$options** (object) - Required - The options object.
- **raw** (any) - Required - The raw data.

### Returns
- The processed proxies.

### Example
```js
const process = [
    { type: 'Quick Setting Operator', args: { udp: 'ENABLED', tfo: 'ENABLED', useless: 'ENABLED' } },
    { type: 'Regex Filter', args: { regex: ['(?i)测试|traffic'], keep: false } },
    { type: 'Flag Operator', args: { mode: 'add' } },
    { type: 'Regex Rename Operator', args: [{ expr: '^HK-', now: '香港-' }] },
    { type: 'Script Operator', args: { content: 'function operator(proxies, targetPlatform, context) { return proxies.filter(p => p.port > 0); }' } },
];

const output = await ProxyUtils.process(proxies, process, 'Surge', { mysub: sub }, $options, raw);
```
```

--------------------------------

### Define settings route with GET and PATCH handlers

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/restful-misc.md

Registers the /api/settings route with GET and PATCH methods, mapping to getSettings and updateSettings handlers respectively.

```javascript
$app.route('/api/settings').get(getSettings).patch(updateSettings);
```

--------------------------------

### Route definitions for misc endpoints

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/restful-misc.md

Defines the GET routes for /api/utils/env, /api/utils/backup, /api/utils/refresh, and the /api/storage route with GET and POST handlers. Includes comments about Node and script behavior.

```javascript
$app.get('/api/utils/env', getEnv);
$app.get('/api/utils/backup', gistBackup);
$app.get('/api/utils/refresh', refresh);
$app.route('/api/storage').get(...).post(...);
// Node: GET / returns getEnv; scripts: GET / 302 → https://sub-store.vercel.app/
// QX: OPTIONS / preflight (200); ALL / → 'Hello from sub-store, made with ❤️ by Peng-YM'
```

--------------------------------

### Register logs GET and DELETE routes

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/restful-misc.md

Registers GET and DELETE routes for /api/logs. GET accepts query parameters limit (default 200, capped by logsMaxCount), keyword, regex, and ignoreCase; returns logs, total, and maxCount. DELETE clears log entries and may fail with FAILED_TO_CLEAR_LOGS.

```javascript
$app.route('/api/logs').get(getLogs).delete(clearLogs);
```

--------------------------------

### File routes

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/restful-files-downloads.md

Lists the RESTful routes for file operations: GET /share/file/:name, GET|PATCH|DELETE /api/file/:name, GET /api/wholeFile/:name, GET|POST|PUT /api/files, and GET /api/wholeFiles.

```http
GET /share/file/:name
GET|PATCH|DELETE /api/file/:name
GET /api/wholeFile/:name
GET|POST|PUT /api/files
GET /api/wholeFiles
```

--------------------------------

### express() factory signature

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/express.md

The main export of src/vendor/express.js. It takes an options object with substore, port, and host. Returns an app object with methods like get, post, put, delete, patch, options, head, all, route, use, and start.

```javascript
export default function express({ substore: $, port, host })
```

--------------------------------

### GET /api/settings

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/endpoints.md

Retrieves the current settings. Returns 200 with settings or 500 on failure.

```APIDOC
## GET /api/settings

### Description
Gets the current settings.

### Method
GET

### Endpoint
/api/settings

### Response
#### Success Response (200)
Returns the settings object.

#### Error Responses
- **500** - `FAILED_TO_GET_SETTINGS`
```

--------------------------------

### GET /download/:name

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/endpoints.md

Downloads a subscription output. Target/platform from query or UA, default JSON.

```APIDOC
## GET /download/:name

### Description
Downloads a subscription output. Target/platform from query or UA, default JSON.

### Method
GET

### Endpoint
/download/:name

### Parameters
#### Path Parameters
- **name** (string) - Required - Subscription name

#### Query Parameters
- **target** (string) - Optional - Output target format
- **platform** (string) - Optional - Platform
- **url** (string) - Optional - Override URL
- **content** (string) - Optional - Override content
- **ua** (string) - Optional - User agent
- **mergeSources** (string) - Optional - `localFirst` or `remoteFirst`
- **ignoreFailedRemoteSub** (boolean) - Optional - Ignore failed remote subs
- **produceType** (string) - Optional - Produce type
- **includeUnsupportedProxy** (boolean) - Optional - Include unsupported proxies
- **proxy** (string) - Optional - Proxy
- **noCache** (boolean) - Optional - Disable cache
- **noFlow** (boolean) - Optional - Disable flow
- **prettyYaml** (boolean) - Optional - Pretty YAML output
- **mihomoExternal** (string) - Optional - Mihomo external
- **mihomoMerge** (string) - Optional - Mihomo merge
- **mihomoMergeName** (string) - Optional - Mihomo merge name
- **mihomoLocalPort** (number) - Optional - Mihomo local port
- **fakeSub** (string) - Optional - Fake subscription
- **_fakeNode** (string) - Optional - Fake node
- **$options** (object) - Optional - Options
- **token** (string) - Optional - Token

### Response
#### Success Response (200)
- **subscription output** (string) - Subscription content in target format

#### Error Responses
- **404** - RESOURCE_NOT_FOUND
- **500** - INTERNAL_SERVER_ERROR
```

--------------------------------

### HTTP()

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/open-api.md

Creates an HTTP client instance with default options. Returns an object with a .request(options) method and per-verb helpers: get, post, put, delete, head, options, patch.

```APIDOC
## HTTP()

### Description
Creates an HTTP client instance with default options. Returns an object with a `.request(options)` method and per-verb helpers: `get`, `post`, `put`, `delete`, `head`, `options`, `patch`.

### Method
Function call

### Endpoint
`HTTP(defaultOptions = { baseURL: '' })`

### Parameters
#### Default Options
- **defaultOptions** (object) - Optional - An object containing default options, including `baseURL` (string) which is prefixed to relative URLs.

### Request Options
| Option | Type | Behavior |
|---|---|---|
| `url` | string | If `defaultOptions.baseURL` is set and the URL is not absolute, the base URL is prefixed |
| `method` | string | Used by `.request()` |
| `timeout` | number | Total timeout in ms; on expiry the promise rejects with `` `${method} URL: ${url} exceeds the timeout ${timeout} ms` `` and `events.onTimeout()` fires. Default for raw requests: `8000` (Node body/headers timeout) |
| `headers` | object | Sent as-is; in Node lowercased, `accept: */*` added when absent, and `Authorization: Basic ...` is derived from URL userinfo |
| `body` | string | Raw body |
| `proxy` | string | Node: `socks5://` URLs use `fetch-socks` `socksDispatcher`; other URLs use `undici` `ProxyAgent`. If unset, falls back to `all_proxy`/`ALL_PROXY` (socks5 only), then the `EnvHttpProxyAgent` |
| `proxyTunnel` | boolean | Passed to the undici proxy agent |
| `node` | string | Surge ≥ 2407: converted to `policy-descriptor` |
| `insecure` / `strictSSL` / `rejectUnauthorized` | boolean | Node: `false` disables TLS verification; also applied to `connect.rejectUnauthorized` |
| `allowH2` | boolean | Undici HTTP/2; all option paths default to `true` unless `allowH2 === false` |
| `encoding` | null | Node: `null` returns binary (ArrayBuffer); otherwise text |
| `requestId` | string | Custom request id echoed in the response |
| `events` | object | `{ onRequest, onResponse, onTimeout }` - `onRequest(method, options)` before send; `onResponse(resp)` can transform; `onTimeout()` fires on timeout. A rejected `onResponse` rejects the request |
| `opts` | object | QX `$task.fetch` options |

### Response Shape
Every promise resolves to an object with the following fields:
- **statusCode** (number) - HTTP status code
- **headers** (object) - Response headers
- **body** (string or ArrayBuffer) - Response body; ArrayBuffer when `encoding: null`
- **requestId** (string) - Custom request id if provided

### Usage Example
```js
const client = HTTP({ baseURL: 'https://api.example.com' });
const response = await client.get({ url: '/users', headers: { 'X-Auth': 'token' } });
```

### Environment Behavior
- In script environments, requests are dispatched to `$httpClient[method](opts, (err, response, body) => ...)`; timeouts are converted to `Math.ceil(timeout / 1000)` seconds for Surge/Egern/Stash/Shadowrocket.
- In GUI.for.Cores, `$Plugins.Requests({ method, url, headers, body, autoTransformBody: false, options: { Proxy, Timeout } })` is used.
- Node uses `undici.request` with redirect (max 3) and decompress interceptors.
```

--------------------------------

### GET /api/wholeFiles

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/restful-files-downloads.md

Returns all file configurations including the `content` field.

```APIDOC
## GET /api/wholeFiles

### Description
Returns all file configurations (including the `content` field) for the entire collection.

### Method
GET

### Endpoint
/api/wholeFiles

### Response
#### Success Response (200)
- Array of file configuration objects including `content`.

#### Response Example
[
  {
    "name": "example",
    "type": "text",
    "content": "Hello, world!"
  }
]

```

--------------------------------

### GET /download/collection/:name

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/endpoints.md

Downloads a collection output.

```APIDOC
## GET /download/collection/:name

### Description
Downloads a collection output.

### Method
GET

### Endpoint
/download/collection/:name

### Parameters
#### Path Parameters
- **name** (string) - Required - Collection name

#### Query Parameters
- Same as GET /download/:name

### Response
#### Success Response (200)
- **collection output** (string) - Collection content in target format

#### Error Responses
- **404** - RESOURCE_NOT_FOUND
- **500** - INTERNAL_SERVER_ERROR
```

--------------------------------

### Start Backend Dev Server on Termux

Source: https://github.com/sub-store-org/sub-store/blob/master/README.md

Alternative development command for Termux environments. Runs all dev scripts in parallel with the backend API port set to 3000.

```shell
SUB_STORE_BACKEND_API_PORT=3000 pnpm run --parallel "/^dev:.*/"
```

--------------------------------

### SINGLE producer contract example (uri.js)

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/proxy-producers.md

Shows the structure of a SINGLE producer: exports a type and a produce function that takes a proxy and returns a share URI. The registry passes (proxy, type, opts); unused parameters are ignored.

```javascript
// uri.js — also exports per-protocol helpers:
const type = 'SINGLE';
const produce = (proxy) => { ... };   // builds a share URI
return { type, produce };
```

--------------------------------

### ALL producer contract example (clashmeta.js)

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/proxy-producers.md

Shows the structure of an ALL producer: exports a type and a produce function that takes the entire proxy list, a type, and optional options. Used by Clash, ClashMeta/mihomo, Stash, Shadowrocket, sing-box, Egern, V2Ray, and JSON_Producer.

```javascript
// clashmeta.js
const type = 'ALL';
const produce = (proxies, type, opts = {}) => { ... };
```

--------------------------------

### GET /api/wholeFile/:name

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/restful-files-downloads.md

Returns the full file configuration object without the `content` field for a specified file.

```APIDOC
## GET /api/wholeFile/:name

### Description
Returns the file configuration (the runtime structure without `content`) for a specific file, with `raw` export support similar to subscriptions.

### Method
GET

### Endpoint
/api/wholeFile/:name

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the file.

### Response
#### Success Response (200)
- The file configuration object (without the `content` field).

#### Response Example
{
  "name": "example",
  "type": "text",
  "url": "https://example.com/file"
}

```

--------------------------------

### Error for missing SUB_STORE_FRONTEND_BACKEND_PATH

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/restful-serve.md

Thrown when SUB_STORE_BACKEND_PREFIX or SUB_STORE_BACKEND_MERGE is enabled but SUB_STORE_FRONTEND_BACKEND_PATH is not set or does not start with '/'. This error is shown in the source as a code block.

```javascript
throw new Error('SUB_STORE_FRONTEND_BACKEND_PATH must be set and start with "/" when SUB_STORE_BACKEND_PREFIX or SUB_STORE_BACKEND_MERGE is enabled');
```

--------------------------------

### GET /download/:name/:target

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/endpoints.md

Downloads a subscription output with target specified in path.

```APIDOC
## GET /download/:name/:target

### Description
Downloads a subscription output with target specified in path.

### Method
GET

### Endpoint
/download/:name/:target

### Parameters
#### Path Parameters
- **name** (string) - Required - Subscription name
- **target** (string) - Required - Output target format

#### Query Parameters
- Same as GET /download/:name

### Response
#### Success Response (200)
- **subscription output** (string) - Subscription content in target format

#### Error Responses
- **404** - RESOURCE_NOT_FOUND
- **500** - INTERNAL_SERVER_ERROR
```

--------------------------------

### GET /api/artifacts/restore

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/restful-resources.md

Restores artifacts from the Sync Gist file list. Requires the 'gistToken' setting. Entries with non-encoded filenames are skipped.

```APIDOC
## [GET] /api/artifacts/restore

### Description
Restores artifacts from the Sync Gist file list. Requires the 'gistToken' setting. Entries with non-encoded filenames are skipped.

### Method
GET

### Endpoint
/api/artifacts/restore

### Parameters
No parameters.

### Response
#### Success Response (200)
- **artifacts** (array) - The restored artifact list.

#### Error Responses
- **InternalServerError** - 'FAILED_TO_RESTORE_ARTIFACTS' - If restoration fails.
```

--------------------------------

### GET|POST|PUT /api/files

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/restful-files-downloads.md

Manages the collection of files: GET retrieves all files, POST creates a new file, and PUT updates files.

```APIDOC
## GET|POST|PUT /api/files

### Description
Manages the collection of files. GET retrieves all files, POST creates a new file, and PUT updates an existing file or collection.

### Method
GET, POST, PUT

### Endpoint
/api/files

### Parameters
#### Request Body (POST/PUT)
- **file configuration** (object) - Required - The file configuration to create or update. Fields include `name`, `type`, `content`, `url`, `ua`, `mergeSources`, `ignoreFailedRemoteFile`, `includeUnsupportedProxy`, `source`, `sourceType`, `sourceName`, `mode`, `proxy`, `noCache`, `produceType`, `download`, `subInfoUrl`, `subInfoUserAgent`, `$options`.

### Request Example (POST)
{
  "name": "example",
  "type": "text",
  "content": "Hello, world!"
}

### Response
#### Success Response (GET, 200)
- Array of file configurations with `content` removed.

#### Success Response (POST, 200)
- The created file configuration.

#### Success Response (PUT, 200)
- The updated file configuration.

#### Error Response (400)
- **DUPLICATE_KEY** - Returned when a file with the same name already exists during creation.

```

--------------------------------

### GET /api/utils/backup

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/restful-misc.md

Performs a Gist-based backup or download operation. Requires a GitHub token and supports various encoding and token strategies.

```APIDOC
## GET /api/utils/backup

### Description
Performs a Gist-based backup or download operation. Requires a GitHub token and supports various encoding and token strategies.

### Method
GET

### Endpoint
/api/utils/backup

### Parameters
#### Query Parameters
- **action** (string) - Required - 'upload' or 'download'
- **keep** (string) - Optional - Comma-separated paths to keep during download
- **encode** (string) - Optional - 'base64' (default), 'plaintext', or 'age'
- **tokenStrategy** (string) - Optional - 'overwrite' or 'keep' for download token handling

### Response
#### Success Response (200)
- **status** (string) - Success indicator
- **data** (object) - Backup result details

#### Error Response
- **GIST_TOKEN_NOT_FOUND** - Missing GitHub token
- **BACKUP_FAILED** - Backup operation failed

#### Response Example
{
  "status": "success",
  "data": {}
}
```

--------------------------------

### Token routes in src/restful/token.js

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/restful-token-archives.md

Defines the HTTP routes for token management: POST to create, DELETE to remove, and GET to list tokens.

```javascript
$app.post('/api/token', signToken);
$app.route('/api/token/:token').delete(deleteToken);
$app.route('/api/tokens').get(getAllTokens);
```

--------------------------------

### DNS utility functions (parseDnsResolver, doh, resolveDns)

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/utils-network.md

Exports three functions for DNS handling. parseDnsResolver converts URL schemes to protocol objects, throwing for unsupported schemes. doh performs RFC 8484 GET requests decoded with dns-packet. resolveDns has platform constraints: auto/system and h3/quic throw unless in Loon, non-DoH requires Node or Loon ≥ 988, and UDP/DoT/TCP have specific runtime support.

```javascript
export function parseDnsResolver(url)                 // 'https://...' → { protocol:'doh', url }; 'udp://'|'tcp://'|'tls://' → { protocol, host, port }; other schemes → throw `自定义 DNS 不支持 <scheme> 协议`
export async function doh({ url, domain, type = 'A', timeout, edns, skipCertVerify })   // RFC 8484 GET, decodes with dns-packet
export async function resolveDns({ url, domain, type = 'A', timeout, edns, skipCertVerify })
```

--------------------------------

### GET /api/settings

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/restful-misc.md

Retrieves the current settings object. If the artifactStore is not set, it lazily triggers an update to the artifact store. Returns an InternalServerError with code 'FAILED_TO_GET_SETTINGS' on failure.

```APIDOC
## GET /api/settings

### Description
Retrieves the current settings object. If the artifactStore is not set, it lazily triggers an update to the artifact store. Returns an InternalServerError with code 'FAILED_TO_GET_SETTINGS' on failure.

### Method
GET

### Endpoint
/api/settings

### Response
#### Success Response (200)
- **settings** (object) - The current settings object.

#### Error Response
- **InternalServerError** - code: 'FAILED_TO_GET_SETTINGS'
```

--------------------------------

### OPTIONS /

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/endpoints.md

Preflight request for QX. Returns 200.

```APIDOC
## OPTIONS /

### Description
Preflight request for QX.

### Method
OPTIONS

### Endpoint
/

### Response
#### Success Response (200)
No specific response body documented.
```

--------------------------------

### Call migrate() and serve() in main.js

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/restful-serve.md

The main.js file ends with these calls to migrate and serve, initializing the backend.

```javascript
migrate();
serve();
```

--------------------------------

### new OpenAPI(name, debug)

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/open-api.md

Creates an OpenAPI instance that adapts to the host environment. The constructor initializes HTTP, ENV, cache, and other utilities.

```APIDOC
## new OpenAPI(name, debug)

### Description
Creates an OpenAPI instance that adapts to the host environment. The constructor initializes HTTP, ENV, cache, and other utilities.

### Parameters
- **name** (string) - Optional - Storage namespace; the data file `<name>.json` in Node, the `$prefs` / `$persistentStore` / `SubStoreCache` key in script environments. Default: `'untitled'`.
- **debug** (boolean) - Optional - When true, `log()` prints to console. Default: `false`.

### Returns
An OpenAPI instance with properties `http`, `env`, `node` (Node only), and methods for cache, notification, logging, and other helpers.
```

--------------------------------

### Build with pnpm bundle:esbuild

Source: https://github.com/sub-store-org/sub-store/blob/master/README.md

Builds the project using the bundle:esbuild script.

```shell
pnpm bundle:esbuild
```

--------------------------------

### SSD preprocessor

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/proxy-preprocessors.md

Expands an SSD subscription (ssd:// + Base64 JSON with global port/encryption/password and a servers array) into one ss:// line per server. Per-server overrides are honored, and plugin/plugin_options are turned into query strings.

```javascript
const name = 'SSD Pre-processor';
const test = function (raw) { return raw.indexOf('ssd://') === 0; };
```

--------------------------------

### GET /share/col/:name

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/endpoints.md

Shares a collection.

```APIDOC
## GET /share/col/:name

### Description
Shares a collection.

### Method
GET

### Endpoint
/share/col/:name

### Parameters
#### Path Parameters
- **name** (string) - Required - Collection name

#### Query Parameters
- Same as GET /share/sub/:name

### Response
#### Success Response (200)
- **collection output** (string) - Collection content

#### Error Responses
- Same as GET /share/sub/:name
```

--------------------------------

### GET /api/subs

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/restful-resources.md

Retrieves a list of all subscriptions.

```APIDOC
## GET /api/subs

### Description
Returns a list of all subscriptions stored in the system.

### Method
GET

### Endpoint
/api/subs

### Response
#### Success Response (200)
- **subscriptions** (array) - List of subscription objects.

#### Response Example
{
  "status": "success",
  "data": []
}
```

--------------------------------

### serve() function signature

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/restful-serve.md

The serve() function is the Node entry point for the HTTP backend. It is not imported in browser products.

```javascript
export default function serve() { ... }
```

--------------------------------

### prepareMihomoProfileContent(file, sourceOptions)

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/restful-sync.md

Rebuilds a mihomo config file from the given file and source options. Handles different source types and produces the appropriate YAML content.

```APIDOC
## prepareMihomoProfileContent(file, sourceOptions)

### Description
Rebuilds a mihomo config file from the given file and source options. Handles different source types and produces the appropriate YAML content.

### Method
FUNCTION

### Endpoint
prepareMihomoProfileContent(file, sourceOptions)

### Parameters
#### Path Parameters
- **file** (object) - Required - The file object to process.

#### Query Parameters
- **sourceOptions** (object) - Required - Options for the source, including sourceType, mode, and produceType.

### Response
#### Success Response (200)
- **string** (string) - The rebuilt mihomo profile content.

#### Response Example
"proxies:"

```

--------------------------------

### Archive RESTful routes in src/restful/archives.js

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/restful-token-archives.md

Defines the RESTful routes for archives in src/restful/archives.js. GET /api/archives lists all entries, GET /api/archives/:id retrieves a detail, DELETE /api/archives/:id deletes an entry, and POST /api/archives/:id/restore restores an archived item.

```javascript
$app.route('/api/archives').get(getAllArchiveEntries);
$app.route('/api/archives/:id').get(getArchiveDetail).delete(deleteArchiveEntry);
$app.post('/api/archives/:id/restore', restoreArchiveEntry);
```

--------------------------------

### GET /api/archives

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/restful-token-archives.md

Retrieves all archive entries from the archive store.

```APIDOC
## GET /api/archives

### Description
Retrieves all archive entries from the archive store.

### Method
GET

### Endpoint
/api/archives

### Response
#### Success Response (200)
- **entries** (array) - List of archive entries.

#### Response Example
```json
{
  "entries": []
}
```
```

--------------------------------

### GET /api/archives/:id

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/restful-token-archives.md

Retrieves a single archive entry by its ID.

```APIDOC
## GET /api/archives/:id

### Description
Retrieves a single archive entry by its ID.

### Method
GET

### Endpoint
/api/archives/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the archive entry.

### Response
#### Success Response (200)
- **entry** (object) - The archive entry.

#### Response Example
```json
{
  "entry": {
    "id": "123",
    "itemType": "sub",
    "name": "example",
    "snapshot": {},
    "createdAt": "2023-01-01T00:00:00Z"
  }
}
```
```

--------------------------------

### FullConfig preprocessor

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/proxy-preprocessors.md

Extracts the proxies section from a full [server_local] / [Proxy] sectioned config (QX/Surge style), cutting off at the next [section] header.

```javascript
const name = 'Full Config Preprocessor';
const test = function (raw) { return /^(\[server_local\]|\[Proxy\])/gm.test(raw); };
const parse = function (raw) { ... }
```

--------------------------------

### GET /api/tokens

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/restful-token-archives.md

Lists all tokens, optionally filtered by `type` and `name`.

```APIDOC
## GET /api/tokens

### Description
Lists all tokens, optionally filtered by `type` and `name`.

### Method
GET

### Endpoint
/api/tokens

### Parameters
#### Query Parameters
- **type** (string) - Optional - Filter by token type.
- **name** (string) - Optional - Filter by token name.

### Response
#### Success Response (200)
- **tokens** (array) - List of token objects.

```

--------------------------------

### User-agent detection functions

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/utils-network.md

Exports three functions for user-agent and platform detection. Maps UA strings to platform keys (e.g., Quantumult%20X → QX, Surge Mac → SurgeMac, clash…meta → ClashMeta). Used as the download target fallback.

```javascript
export function getUserAgentFromHeaders(headers)    // → { UA, ua, accept }
export function getPlatformFromUserAgent({ ua, UA, accept })
export function getPlatformFromHeaders(headers)
```

--------------------------------

### isAgeArmor(value)

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/utils-network.md

Checks if a value starts with the age armor header.

```APIDOC
## isAgeArmor(value)

### Description
Checks if a value starts with the age armor header.

### Parameters
- **value** (string) - Required - The value to check.

### Returns
- (boolean) - `true` if the value starts with the armor header, otherwise `false`.
```

--------------------------------

### GET /share/col/:name/:target

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/endpoints.md

Shares a collection with target specified in path.

```APIDOC
## GET /share/col/:name/:target

### Description
Shares a collection with target specified in path.

### Method
GET

### Endpoint
/share/col/:name/:target

### Parameters
#### Path Parameters
- **name** (string) - Required - Collection name
- **target** (string) - Required - Output target format

#### Query Parameters
- Same as GET /share/sub/:name

### Response
#### Success Response (200)
- **collection output** (string) - Collection content

#### Error Responses
- Same as GET /share/sub/:name
```

--------------------------------

### POST /api/preview/file

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/endpoints.md

Previews a file by processing the provided file config. Returns original and processed content.

```APIDOC
## POST /api/preview/file

### Description
Processes a file config and returns original and processed content. The processed content is the result of `normalizeClashYaml` applied to `$content`.

### Method
POST

### Endpoint
/api/preview/file

### Parameters
#### Request Body
- **file config** (object) - Required - The file configuration to preview.

### Response
#### Success Response (200)
- **original** (string) - Original file content.
- **processed** (string) - Processed file content.

#### Error Responses
- **500** - `INTERNAL_SERVER_ERROR`
```

--------------------------------

### ENV()

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/open-api.md

Returns an object with boolean flags indicating the current host environment.

```APIDOC
## ENV()

### Description
Returns an object with boolean flags indicating the current host environment.

### Returns
An object with the following boolean properties: `isQX`, `isLoon`, `isSurge`, `isNode`, `isStash`, `isShadowRocket`, `isEgern`, `isLanceX`, `isGUIforCores`.
```

--------------------------------

### GET /share/sub/:name/:target

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/endpoints.md

Shares a subscription with target specified in path.

```APIDOC
## GET /share/sub/:name/:target

### Description
Shares a subscription with target specified in path.

### Method
GET

### Endpoint
/share/sub/:name/:target

### Parameters
#### Path Parameters
- **name** (string) - Required - Subscription name
- **target** (string) - Required - Output target format

#### Query Parameters
- Same as GET /share/sub/:name

### Response
#### Success Response (200)
- **subscription output** (string) - Subscription content

#### Error Responses
- Same as GET /share/sub/:name
```

--------------------------------

### GET /api/modules

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/restful-resources.md

Retrieves a list of all modules, with the `content` field stripped from each module.

```APIDOC
## GET /api/modules

### Description
Retrieves a list of all modules, with the `content` field stripped from each module.

### Method
GET

### Endpoint
/api/modules

### Response
#### Success Response (200)
- **modules** (array) - List of module objects, each without the `content` field.
```

--------------------------------

### load(content, ...args)

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/utils-foundation.md

Parses YAML content using the yaml package with custom defaults. May throw on invalid YAML.

```APIDOC
## load(content, ...args)

### Description
Parses YAML content using the yaml package with custom defaults.

### Parameters
- **content** (string) - Required - The YAML content to parse.
- **...args** - Optional - Additional arguments passed to the yaml parser.

### Returns
- The parsed JavaScript object.
```

--------------------------------

### GET /api/storage

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/restful-misc.md

Downloads the full cache as a JSON file with a timestamped filename.

```APIDOC
## GET /api/storage

### Description
Downloads the full cache as a JSON file with a timestamped filename.

### Method
GET

### Endpoint
/api/storage

### Response
#### Success Response (200)
- **Content-Disposition** (string) - Attachment with filename `sub-store_data_<datetime>.json`
- **Body** (file) - The full cache content

#### Response Example
(sub-store_data_20250101_120000.json)
```

--------------------------------

### GET/POST/PUT /api/modules

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/endpoints.md

List, create, or replace all modules. List returns content-stripped modules. Create uses md5 as name when absent.

```APIDOC
## GET/POST/PUT /api/modules

### Description
List, create, or replace all modules. List returns content-stripped modules. Create uses md5 as name when absent.

### Method
GET, POST, PUT

### Endpoint
/api/modules

### Parameters
#### Request Body (POST/PUT)
- **module** (object) - Required for POST - Module data
- **array** (array) - Required for PUT - Array of modules

### Response
#### Success Response (200 for GET/PUT, 201 for POST)
- **array** (array) - List of modules (GET)
- **module** (object) - Created module (POST)
- **status** (string) - Success indicator (PUT)

#### Error Responses
- **400** - DUPLICATE_KEY
```

--------------------------------

### GET /download/collection/:name/:target

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/endpoints.md

Downloads a collection output with target specified in path.

```APIDOC
## GET /download/collection/:name/:target

### Description
Downloads a collection output with target specified in path.

### Method
GET

### Endpoint
/download/collection/:name/:target

### Parameters
#### Path Parameters
- **name** (string) - Required - Collection name
- **target** (string) - Required - Output target format

#### Query Parameters
- Same as GET /download/:name

### Response
#### Success Response (200)
- **collection output** (string) - Collection content in target format

#### Error Responses
- **404** - RESOURCE_NOT_FOUND
- **500** - INTERNAL_SERVER_ERROR
```

--------------------------------

### POST /api/preview/sub|collection|file

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/restful-misc.md

Returns preview of subscription, collection, or file content. The response contains original and processed versions.

```APIDOC
## POST /api/preview/sub|collection|file

### Description
Returns preview of subscription, collection, or file content. The response contains original and processed versions.

### Method
POST

### Endpoint
/api/preview/sub|collection|file

### Parameters
#### Request Body
- (No explicit parameters documented)

### Response
#### Success Response (200)
- **original** (string) - Original content.
- **processed** (string) - Processed content.

#### Response Example
{
  "original": "original content",
  "processed": "processed content"
}
```

--------------------------------

### POST /api/preview/sub

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/endpoints.md

Previews a subscription by processing the provided subscription object. Returns original and processed proxy arrays.

```APIDOC
## POST /api/preview/sub

### Description
Processes a subscription object and returns original and processed proxy arrays. The original proxies get sequential `id`s.

### Method
POST

### Endpoint
/api/preview/sub

### Parameters
#### Query Parameters
- **target** (string) - Optional - Target parameter.

#### Request Body
- **subscription object** (object) - Required - The subscription data to preview.

### Response
#### Success Response (200)
- **original** (array) - Original proxy array with sequential IDs.
- **processed** (array) - Processed proxy array.

#### Error Responses
- **500** - `INTERNAL_SERVER_ERROR`
```

--------------------------------

### GET /api/sync/artifacts

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/restful-sync.md

Synchronizes all artifacts. This endpoint triggers the sync process for all stored artifacts.

```APIDOC
## GET /api/sync/artifacts

### Description
Synchronizes all artifacts. This endpoint triggers the sync process for all stored artifacts.

### Method
GET

### Endpoint
/api/sync/artifacts

### Response
#### Success Response (200)
No response body is documented.

```

--------------------------------

### Map sub.store to local address in Surge Host configuration

Source: https://github.com/sub-store-org/sub-store/blob/master/README.md

Add this [Host] rule to map sub.store to 127.0.0.1, preventing accidental access to the public sub.store service. This is a configuration snippet for Surge-style host mapping.

```ini
[Host]
sub.store = 127.0.0.1
```

--------------------------------

### GET /api/utils/backup

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/endpoints.md

Performs backup or restore operations. Returns backup data or error codes.

```APIDOC
## GET /api/utils/backup

### Description
Performs backup or restore operations based on the `action` query parameter.

### Method
GET

### Endpoint
/api/utils/backup

### Parameters
#### Query Parameters
- **action** (string) - Required - `upload` or `download`.
- **encode** (string) - Optional - `base64`, `plaintext`, or `age`.
- **keep** (boolean) - Optional - Whether to keep the backup.
- **tokenStrategy** (string) - Optional - Token strategy.

### Response
#### Success Response (200)
Returns backup data.

#### Error Responses
- **400** - `GIST_TOKEN_NOT_FOUND` or `INVALID_GIST_DOWNLOAD_TOKEN_STRATEGY`
- **500** - `BACKUP_FAILED`
```

--------------------------------

### PROXY_PROCESSORS['Sort Operator']({ order: 'sideways' })

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/proxy-processors.md

Example of sort order validation throwing an error.

```APIDOC
## PROXY_PROCESSORS['Sort Operator']({ order: 'sideways' })

### Description
Validates the sort order option. Throws an error for unknown sort options.

### Parameters
- **args** (object) - Required - The arguments object containing the `order` property.

### Throws
- Error with message 'Unknown sort option: sideways' if the order is invalid.

### Example
```js
try {
    const bad = PROXY_PROCESSORS['Sort Operator']({ order: 'sideways' });
} catch (e) {
    // 'Unknown sort option: sideways'
}
```
```

--------------------------------

### ALL /

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/endpoints.md

Fallback endpoint that returns a greeting message.

```APIDOC
## ALL /

### Description
Returns the message `Hello from sub-store, made with ❤️ by Peng-YM`.

### Method
ALL

### Endpoint
/

### Response
#### Success Response (200)
Returns the greeting message.
```

--------------------------------

### Create OpenAPI singleton in app.js

Source: https://github.com/sub-store-org/sub-store/blob/master/_autodocs/api-reference/open-api.md

Creates the process-wide singleton OpenAPI instance with name 'sub-store' and exports it as default. Used throughout the codebase via `import $ from '@/core/app'`.

```javascript
import { OpenAPI } from '@/vendor/open-api';

const $ = new OpenAPI('sub-store');
export default $;
```
Tokens:
Raw