SubBoost

https://github.com/subboost/subboost
Admin
SubBoost is a Clash/Mihomo subscription conversion, enhancement, and management tool. It can convert...
Tokens:84,124
Snippets:512
Trust Score:4.5
License:AGPL-3.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Start local development environment

Source: https://github.com/subboost/subboost/blob/main/README.md

Installs dependencies and starts the local development environment from source.

```bash
npm ci
npm run dev
```

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

### Usage example

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/core-templates.md

Example of importing and using getTemplate, getTemplateList, validateTemplateConfig, and validateSubBoostTemplateConfig.

```javascript
import { getTemplate, getTemplateList, validateTemplateConfig } from "@subboost/core/templates";
import { validateSubBoostTemplateConfig } from "@subboost/core/templates/config-template";

const t = getTemplate("standard");
console.log(t.name, t.groups.length);

const result = validateSubBoostTemplateConfig(rawImport);
if (!result.ok) console.error(result.error);
```

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

### Usage example for node naming, identity, and source state

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/core-node-naming.md

Shows how to import and use formatNodeNameFromTemplate, buildNodeContentKey, getNodeSourceIds, and withNodeSourceId. The example formats a node name with a tag, builds a content key ignoring the server, adds a source ID, and logs the resulting source IDs.

```javascript
import { formatNodeNameFromTemplate } from "@subboost/core/node-name-template";
import { buildNodeContentKey } from "@subboost/core/node-identity";
import { getNodeSourceIds, withNodeSourceId } from "@subboost/core/subscription/node-source-state";

const display = formatNodeNameFromTemplate({ originName: "US-01", tag: "机场A" });
// "[机场A]US-01"

const key = buildNodeContentKey(node, { ignoreServer: true });
const tagged = withNodeSourceId(node, "src-1");
console.log(getNodeSourceIds(tagged)); // ["src-1"]
```

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

### importSubscriptionFromUrl usage example

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/server-core-subscription.md

Example of importing a subscription from a URL using importSubscriptionFromUrl. Requires a custom fetchText implementation that returns an object with ok, content, and responseStatus. On failure, logs the error category and suggested actions.

```js
import { importSubscriptionFromUrl } from "@subboost/server-core/subscription";
import { SubscriptionImportError } from "@subboost/core/subscription/import-error";

const result = await importSubscriptionFromUrl(
  { url: "https://provider.example/sub?token=abc" },
  {
    fetchText: async ({ url, userAgent, timeoutMs }) => {
      // inject your Node fetch/SSRF-guard implementation here
      const res = await fetch(url, { headers: { "User-Agent": userAgent }, signal: AbortSignal.timeout(timeoutMs) });
      return { ok: res.ok, content: res.ok ? await res.text() : undefined, responseStatus: res.status };
    },
  }
);

if (!result.ok) {
  console.error(result.errorInfo.category, result.errorInfo.suggestedActions);
}

```

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

### POST /api/setup/admin

Source: https://github.com/subboost/subboost/blob/main/_autodocs/endpoints.md

Creates the initial admin user, protected by a setup token.

```APIDOC
## POST /api/setup/admin

### Description
Creates the first (and only) local admin. Guarded by the setup token.

### Method
POST

### Endpoint
/api/setup/admin

### Authentication
- Header `x-subboost-setup-token` (string) - Required - The setup token.

### Rate Limit
- 5 requests per 15 minutes per trusted client.

### Request Body
- **username** (string) - Required - Admin username.
- **password** (string) - Required - Admin password.
- **passwordConfirm** (string) - Required - Password confirmation.

### Request Example
{
  "username": "admin",
  "password": "secret",
  "passwordConfirm": "secret"
}

### Response
#### Success Response (201)
- **success** (boolean) - Always true.
- **user** (object) - Contains `id` and `username`.

#### Response Example
{
  "success": true,
  "user": {
    "id": "uuid",
    "username": "admin"
  }
}

### Error Responses
- **503 CONFIGURATION_ERROR** - Missing `LOCAL_SETUP_TOKEN`.
- **403 FORBIDDEN** - Invalid token.
- **409 CONFLICT** - Admin already exists.
- **400 BAD_REQUEST** - Invalid credentials.
```

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

### GET /api/auth/me Response 200

Source: https://github.com/subboost/subboost/blob/main/_autodocs/endpoints.md

Successful response for the current user endpoint. Returns setup status, authentication flag, user object with quota and counts. The 'user' field is null when not authenticated.

```json
{
  "setupRequired": boolean,
  "authenticated": boolean,
  "user": {
    "id": string, "username": string, "name": string, "avatarUrl": null,
    "trustLevel": 4, "aiAssistantEnabled": false, "isAdmin": false, "isBanned": false,
    "active": true, "silenced": false, "saveRequirementSatisfied": true,
    "saveRequirementSatisfiedAt": string, "createdAt": string, "updatedAt": string,
    "accounts": [],
    "quota": { "maxSubscriptions": 9999, "maxNodesPerSubscription": 10000,
               "maxCustomTemplates": 9999, "maxImportSourcesPerType": 9999,
               "canUseSubscriptionLink": true },
    "subscriptionCount": number, "templateCount": number
  } | null
}
```

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

### resolveProxyGroupModuleName and getProxyGroupMemberKey usage

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/core-proxy-group-model.md

Example of resolving a proxy group module name and getting a member key, with sample outputs.

```js
import { resolveProxyGroupModuleName } from "@subboost/core/proxy-group-name";
import { getProxyGroupMemberKey } from "@subboost/core/proxy-group-targets";

const name = resolveProxyGroupModuleName({ emoji: "🚀", name: "🚀 节点选择" }, "我的选择");
console.log(name); // "🚀 我的选择"
console.log(getProxyGroupMemberKey({ kind: "node", name: "JP-01" })); // "node:JP-01"
```

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

### Example: createRuleCatalogService and searchRules

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/server-core-rules.md

Shows how to create a rule catalog service with custom fetch, GitHub token, and cache TTL, then search rules. Catches RuleIndexUnavailableError when the catalog is unavailable.

```javascript
import { createRuleCatalogService, RuleIndexUnavailableError } from "@subboost/server-core/rules";

const service = createRuleCatalogService({
  fetchImpl: fetch,
  getGitHubToken: () => process.env.GITHUB_TOKEN,
  cacheTtlMs: 86_400_000,
});

try {
  const result = await service.searchRules({ keyword: "google", type: "all", page: 1, size: 20 });
  console.log(result.totalMatched, result.items.map((item) => item.id));
} catch (error) {
  if (error instanceof RuleIndexUnavailableError) {
    console.error("catalog unavailable:", error.message);
  }
}
```

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

### resolveProxyGroupMembers usage example

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/core-proxy-group-model.md

Example of resolving proxy group members with advanced options, including regions, includeRegex, and extraMembers.

```js
import { resolveProxyGroupMembers } from "@subboost/core/proxy-group-advanced";

const { proxyNames, included, excluded } = resolveProxyGroupMembers({
  defaultProxyNames: ["DIRECT", "REJECT", "US-01", "JP-01", "SG-01"],
  nodes: parsedNodes,
  advanced: { regions: ["us"], includeRegex: "US", extraMembers: [{ kind: "node", name: "SG-01" }] },
});
```

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

### Usage example for manifest and favicon routes

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/ui-brand.md

Shows how to import and use the brand functions in the local app. The manifest route returns the manifest as JSON, and the favicon route returns the redirect. Note that SUBBOOST_SITE_NAME is imported but not used in the displayed code.

```js
import { createSubBoostManifest, SUBBOOST_SITE_NAME } from "@subboost/ui/brand";
import { createSubBoostFaviconRedirect } from "@subboost/ui/brand-favicon";

// local/app/manifest.ts
export function GET() {
  return Response.json(createSubBoostManifest());
}

// local/app/favicon.ico/route.ts
export function GET() {
  return createSubBoostFaviconRedirect();
}
```

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

### createSubBoostManifest()

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/ui-brand.md

Creates a PWA web manifest object with the product title, start URL, display mode, colors, icons, and language. This function is used to serve the manifest in the local app.

```APIDOC
## createSubBoostManifest()

### Description
Creates a PWA web manifest object with the product title, start URL, display mode, colors, icons, and language. This function is used to serve the manifest in the local app.

### Method
Function

### Signature
```ts
export function createSubBoostManifest(): SubBoostManifest
```

### Returns
- **SubBoostManifest** - The PWA manifest object with the following properties:
  - `name` (string) - The product title (e.g., "SubBoost - Clash 订阅转换与管理服务")
  - `short_name` (string) - The short name (e.g., "SubBoost")
  - `description` (string) - The product description
  - `start_url` (string) - The start URL (e.g., "/")
  - `display` (string) - The display mode (e.g., "standalone")
  - `background_color` (string) - The background color (e.g., "#0f0d1a")
  - `theme_color` (string) - The theme color (e.g., "#1e1b4b")
  - `orientation` (string) - The orientation (e.g., "portrait-primary")
  - `icons` (array) - Array of icon objects with `src`, `sizes`, `type`, and `purpose` (e.g., "/icon.png" 512x512 for "any" and "maskable")
  - `categories` (array) - Array of categories (e.g., ["utilities", "productivity"])
  - `lang` (string) - The language (e.g., "zh-CN")

### Example
```js
import { createSubBoostManifest } from "@subboost/ui/brand";

export function GET() {
  return Response.json(createSubBoostManifest());
}
```
```

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

### Using rule set path and batch import utilities

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/core-rules.md

Example usage of rule set utilities: validates a rule set path, builds a URL from a path and base URL, and parses a batch of custom rules with the noResolve option. Logs the built URL and the parsed batch rules and errors.

```javascript
import { ALL_RULES, TOTAL_RULES_COUNT } from "@subboost/core/rules-database";
import { buildRuleSetUrlFromPath, isValidRuleSetPathOrUrl } from "@subboost/core/rules/rule-model";
import { parseCustomRuleBatchImport } from "@subboost/core/rules/custom-rule-batch-import";

if (isValidRuleSetPathOrUrl("geosite/google.mrs")) {
  console.log(buildRuleSetUrlFromPath("geosite/google.mrs", "https://example.com/geo")); // https://example.com/geo/geosite/google.mrs
}

const batch = parseCustomRuleBatchImport("DOMAIN-SUFFIX,example.com,DIRECT\nDOMAIN,foo.com,PROXY", {
  noResolve: true,
});
console.log(batch.rules, batch.errors);
```

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

### GET /api/settings/source-import

Source: https://github.com/subboost/subboost/blob/main/_autodocs/endpoints.md

Retrieves the current setting for allowing unsafe subscription sources. Requires admin authentication.

```APIDOC
## GET /api/settings/source-import

### Description
Retrieves the current setting for allowing unsafe subscription sources. Requires an admin session cookie.

### Method
GET

### Endpoint
/api/settings/source-import

### Response
#### Success Response (200)
- **allowUnsafeSubscriptionSources** (boolean) - Whether unsafe subscription sources are allowed.

#### Response Example
{
  "allowUnsafeSubscriptionSources": false
}
```

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

### Handle BaseConfigYamlError with generateClashConfig

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/core-generator.md

Error handling example: catches BaseConfigYamlError when userConfig.dnsYaml is invalid (e.g., contains a 'proxies' section that conflicts with generated sections).

```js
import { generateClashConfig, BaseConfigYamlError } from "@subboost/core";

try {
  generateClashConfig({
    nodes: parsedNodes,
    userConfig: { dnsYaml: "proxies:\n  - name: x" }, // generated section
  });
} catch (error) {
  if (error instanceof BaseConfigYamlError) {
    console.error("Invalid base/DNS config:", error.message);
  }
}
```

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

### Example usage of parseVLESS and parseSS

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/core-parser-protocols.md

Shows importing and using parseVLESS and parseSS. parseVLESS parses a VLESS URI and logs node properties; parseSS throws an Error with a Chinese-language message for an invalid URI, caught and logged.

```js
import { parseVLESS } from "@subboost/core/parser/protocols/vless";
import { parseSS } from "@subboost/core/parser";

const node = parseVLESS(
  "vless://uuid@example.com:443?security=tls&sni=example.com&type=ws&path=%2Fws#%F0%9F%87%BA"
);
console.log(node.type, node.servername, node.network);

try {
  parseSS("ss://not-a-valid-uri");
} catch (error) {
  console.error(error.message);
}
```

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

### Using @subboost/server-core utilities for cron auth, session revocation, and app version

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/server-core-http-cron-session-version.md

Shows how to use the @subboost/server-core utilities: validateCronSecret for cron authentication, deriveSessionRevocationIdentity for session revocation, and resolveAppVersionInfo for app version info. The example returns a 401 response with buildApiErrorBody when the cron secret is invalid.

```javascript
import { buildApiErrorBody } from "@subboost/server-core/http";
import { validateCronSecret } from "@subboost/server-core/cron-auth";
import { deriveSessionRevocationIdentity } from "@subboost/server-core/session-revocation";
import { resolveAppVersionInfo } from "@subboost/server-core/app-version";

const auth = validateCronSecret({ cronSecret: process.env.CRON_SECRET, authorization: request.headers.get("authorization") });
if (!auth.ok) return NextResponse.json(buildApiErrorBody("Invalid cron secret.", "UNAUTHORIZED"), { status: 401 });

const identity = deriveSessionRevocationIdentity({ namespace: "local", token, claims: { exp, jti } });
// store identity.key until identity.expiresAt

const info = resolveAppVersionInfo({ env: process.env, cwd: process.cwd() });
console.log(info.version, info.releaseVersion);
```

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

### Example: refreshRuleIndex with force option

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/server-core-rules.md

Calls refreshRuleIndex with force: true. If status is 'unavailable', it indicates a 503 for the cron endpoint; otherwise logs status, index geosite length, and missing curated rules count.

```javascript
import { refreshRuleIndex } from "@subboost/server-core/rules";

const result = await refreshRuleIndex({ force: true });
if (result.status === "unavailable") {
  // 503 for the cron endpoint
} else {
  console.log(result.status, result.index.geosite.length, result.diff.missingCuratedRules);
}
```

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

### Usage example with parsePagePagination and getTotalPages

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/core-pagination.md

Shows how to use parsePagePagination and getTotalPages together. It parses a URL's search params with a custom sizeParam "size", defaultSize 20, maxPage 5000, and maxSize 50, then computes total pages for 1024 items.

```js
import { parsePagePagination, getTotalPages } from "@subboost/core/api/pagination";

const { searchParams } = new URL("https://example.com/rules?keyword=x&size=20");
const { page, pageSize, skip } = parsePagePagination(searchParams, {
  sizeParam: "size",
  defaultSize: 20,
  maxPage: 5000,
  maxSize: 50,
});

const totalPages = getTotalPages(1024, pageSize);
```

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

### Typed proxy group builder functions

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/core-generator-modules.md

Functions for building typed proxy groups. `buildTypedProxyGroup` maps group types to Clash fields: url-test/fallback/load-balance get url and interval (and lazy for url-test), load-balance also gets strategy (default "consistent-hashing"), while select/direct-first/reject-first remain plain type "select".

```ts
export function uniqueProxyNames(values: string[]): string[]
export function buildTypedProxyGroup({ name, groupType, proxies, testUrl, testInterval, strategy, extraFields = {}, urlTestLazy = false }: BuildTypedProxyGroupOptions): ProxyGroup
```

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

### Generate proxy groups with standard modules

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/core-generator-modules.md

Shows how to load the standard preset modules and generate proxy groups with a custom rule provider base URL, test URL, and test interval.

```javascript
import { generateProxyGroups, getModulesForTemplate } from "@subboost/core/generator/proxy-groups";

const modules = getModulesForTemplate("standard");
const groups = generateProxyGroups({
  nodes: parsedNodes,
  enabledModules: modules,
  ruleProviderBaseUrl: "https://github.com/MetaCubeX/meta-rules-dat/raw/refs/heads/meta/geo",
  testUrl: "https://www.gstatic.com/generate_204",
  testInterval: 300,
});
```

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

### GET /api/subscriptions

Source: https://github.com/subboost/subboost/blob/main/_autodocs/endpoints.md

Retrieves all subscriptions for the authenticated admin.

```APIDOC
## GET /api/subscriptions

### Description
Lists the current admin's subscriptions, newest first.

### Method
GET

### Endpoint
/api/subscriptions

### Authentication
- Session cookie - Required.

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

#### Response Example
{
  "subscriptions": []
}
```

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

### GET /api/subscriptions/[id]

Source: https://github.com/subboost/subboost/blob/main/_autodocs/endpoints.md

Fetches detailed information for a specific subscription.

```APIDOC
## GET /api/subscriptions/[id]

### Description
Retrieves details of a specific subscription.

### Method
GET

### Endpoint
/api/subscriptions/[id]

### Path Parameters
- **id** (string) - Required - Subscription ID.

### Authentication
- Session cookie - Required.

### Response
#### Success Response (200)
- **subscription** (SubscriptionDetail) - Subscription details including urls, nodes, config, and subscriptionInfo.

#### Response Example
{
  "subscription": {}
}

### Error Responses
- **404 NOT_FOUND** - Subscription not found.
```

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

### GET /api/health/ready

Source: https://github.com/subboost/subboost/blob/main/_autodocs/endpoints.md

Health check endpoint that verifies database connectivity.

```APIDOC
## GET /api/health/ready

### Description
Checks database readiness by running a SELECT 1 query against Postgres.

### Method
GET

### Endpoint
/api/health/ready

### Response
#### Success Response (200)
- **ok** (boolean) - Always true.
- **database** (string) - "ready".

#### Error Response (503)
- **ok** (boolean) - false.
- **database** (string) - "unavailable".

#### Response Example
{
  "ok": true,
  "database": "ready"
}
```

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

### resolveAppVersionInfo type definitions and signature

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/server-core-http-cron-session-version.md

Type definitions and function signature for resolving app version information. The resolution order uses environment variables: buildSha from APP_BUILD_SHA, GITHUB_SHA, VERCEL_GIT_COMMIT_SHA, or a SHA-like APP_VERSION; releaseVersion from APP_RELEASE_VERSION, semver from APP_VERSION, package.json version (preferring a package named subboost), or "0.0.0"; buildVersion from APP_VERSION or `${releaseVersion}+sha.<12>`; version/versionToken from APP_VERSION_TOKEN or `${releaseVersion}+build.<sha256-12>`.

```ts
export type AppVersionInfo = {
  version: string;
  releaseVersion: string;
  buildSha: string | null;
  buildVersion: string;
  versionToken: string;
};
export type AppVersionEnvironment = Record<string, string | undefined>;
export type ResolveAppVersionInfoOptions = {
  env: AppVersionEnvironment;
  cwd: string;
  readFile?: (filePath: string) => string;
};

export function resolveAppVersionInfo(options: ResolveAppVersionInfoOptions): AppVersionInfo
```

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

### GET /api/releases/latest response JSON

Source: https://github.com/subboost/subboost/blob/main/_autodocs/endpoints.md

Response body for the public endpoint GET /api/releases/latest. The endpoint checks the latest release of GitHub SubBoost/subboost and returns this JSON structure with fields for current and latest versions, latest tag, release URL, and a boolean indicating whether an update is available.

```json
{
  "currentVersion": string,
  "latestVersion": string | null,
  "latestTag": string | null,
  "releaseUrl": string | null,
  "hasUpdate": boolean
}
```

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

### parseConfigLineSubscriptionContent(content: string): ParseResult

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/core-parser.md

Parses platform proxy lines (Loon/QX/Surge) first, then falls back to the generic config-line parser.

```APIDOC
## parseConfigLineSubscriptionContent

### Description
Tries platform proxy lines (Loon/QX/Surge via `parsePlatformProxyLine`) first, then the generic config-line parser (`parseConfigLine`).

### Method
FUNCTION

### Endpoint
`parseConfigLineSubscriptionContent(content: string): ParseResult`

### Parameters
#### Parameters
- **content** (string) - Required - The subscription content to parse.

### Return Type
`ParseResult`
```

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

### GET /api/templates

Source: https://github.com/subboost/subboost/blob/main/_autodocs/endpoints.md

Retrieves a list of templates with optional filtering by type or IDs.

```APIDOC
## GET /api/templates

### Description
Lists templates. Authentication is optional; unauthenticated listing failures return 401.

### Method
GET

### Endpoint
/api/templates

### Query Parameters
- **type** (string) - Optional - `default` or `my` (default is `default`).
- **ids** (string) - Optional - Comma-separated list of template IDs.

### Response
#### Success Response (200)
- **templates** (array of LocalTemplateSummary) - List of templates.
- **pagination** (object) - Pagination info with `page`, `limit`, `total`, `totalPages`.

#### Error Responses
- **401** - `UNAUTHORIZED` when unauthenticated listing fails.
```

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

### getTemplateList

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/core-templates.md

Returns a list of all preset templates with metadata including id, name, description, group count, and rule count.

```APIDOC
## getTemplateList

### Description
Returns an array of objects describing each preset template, including its id, name, description, group count, and rule count.

### Method
Function

### Endpoint
`getTemplateList()`

### Parameters
None

### Return Value
- **Array<{ id: TemplateType; name: string; description: string; groupCount: number; ruleCount: number }>** - List of template summaries.

### Example
```js
import { getTemplateList } from "@subboost/core/templates";
const list = getTemplateList();
console.log(list);
```
```

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

### GET /api/health/live

Source: https://github.com/subboost/subboost/blob/main/_autodocs/endpoints.md

Health check endpoint that returns a simple liveness response.

```APIDOC
## GET /api/health/live

### Description
Checks if the service is alive.

### Method
GET

### Endpoint
/api/health/live

### Response
#### Success Response (200)
- **ok** (boolean) - Always true.
- **service** (string) - Service name.

#### Response Example
{
  "ok": true,
  "service": "subboost-local"
}
```

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

### buildCnRuleCandidatesFromSources

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/core-rules.md

Builds CN rule candidates from source candidates and geolocation CN lines.

```APIDOC
## buildCnRuleCandidatesFromSources

### Description
Builds CN rule candidates from source candidates and geolocation CN lines.

### Signature
```ts
export function buildCnRuleCandidatesFromSources(sources: CnRuleCandidateSource[], geolocationCnLines: string[]): CnRuleCandidate[]
```

### Parameters
- **sources** (CnRuleCandidateSource[]) - Required - Array of candidate sources.
- **geolocationCnLines** (string[]) - Required - Geolocation CN lines.

### Return Value
Returns an array of `CnRuleCandidate` objects.

### Types
```ts
export interface CnRuleCandidateSource extends CnCandidateParent {
  id: string;
  variantKind: CnRuleVariantKind;
  lines: string[];
}
```
```

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

### GET /api/auth/me

Source: https://github.com/subboost/subboost/blob/main/_autodocs/endpoints.md

Retrieves the current admin's profile, quotas, and counts.

```APIDOC
## GET /api/auth/me

### Description
Returns setup status, current admin, quotas, and per-admin subscription/template counts.

### Method
GET

### Endpoint
/api/auth/me

### Response
#### Success Response (200)
- **setupRequired** (boolean) - Whether setup is required.
- **authenticated** (boolean) - Whether the request is authenticated.
- **user** (object|null) - The current admin user object or null if not authenticated.

#### Response Example
{
  "setupRequired": false,
  "authenticated": true,
  "user": {
    "id": "user-id",
    "username": "admin",
    "name": "Admin",
    "avatarUrl": null,
    "trustLevel": 4,
    "aiAssistantEnabled": false,
    "isAdmin": false,
    "isBanned": false,
    "active": true,
    "silenced": false,
    "saveRequirementSatisfied": true,
    "saveRequirementSatisfiedAt": "2023-01-01T00:00:00Z",
    "createdAt": "2023-01-01T00:00:00Z",
    "updatedAt": "2023-01-01T00:00:00Z",
    "accounts": [],
    "quota": {
      "maxSubscriptions": 9999,
      "maxNodesPerSubscription": 10000,
      "maxCustomTemplates": 9999,
      "maxImportSourcesPerType": 9999,
      "canUseSubscriptionLink": true
    },
    "subscriptionCount": 0,
    "templateCount": 0
  }
}
```

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

### createRuleCatalogService: service factory and returned methods

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/server-core-rules.md

Creates a rule catalog service with methods for fetching, caching, searching, and diffing remote rule indexes. The service caches fresh indexes within cacheTtlMs (default 24h) and shares concurrent refreshes. getRemoteRuleIndex falls back to stale cache unless allowStale is false, otherwise throws RuleIndexUnavailableError. searchRules matches keyword case-insensitively against id, name, and nameZh, requiring page and size ≥ 1.

```ts
export function createRuleCatalogService(options: RuleCatalogServiceOptions = {})
```

```ts
{
  getRemoteRuleIndex(params?: { force?: boolean; allowStale?: boolean; now?: number }): Promise<RemoteRuleIndex>
  refreshRuleIndex(params?: { force?: boolean }): Promise<RuleIndexRefreshResult>
  searchRules(params: { keyword: string; type?: RuleSearchType; page: number; size: number; allowStale?: boolean }): Promise<RuleSearchResult>
  getCnRuleCandidateDiscovery(params: { moduleIds: string[]; excludedRuleKeys?: string[]; force?: boolean; now?: number }): Promise<CnRuleCandidateDiscovery>
  getCachedRuleIndex(): RemoteRuleIndex | null
  buildRuleCatalogDiff(index: RemoteRuleIndex): RuleCatalogDiff
  hasRemoteRule(index: RemoteRuleIndex, parsed: { type: RemoteRuleType; name: string }): boolean
}
```

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

### getModulesForTemplate(template)

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/core-generator-modules.md

Function to get the list of module names for a given template.

```APIDOC
## getModulesForTemplate(template)

### Description
Returns the list of module names for a given template. Minimal → `select, auto, ad, private, cn, global, final`; standard adds `ai, youtube, google, microsoft, apple, github, telegram`; full → all modules except `adult`, `gemini`, `google-scholar`.

### Method
Function

### Signature
`getModulesForTemplate(template: "minimal" | "standard" | "full"): string[]`

### Parameters
- **template** ("minimal" | "standard" | "full") - Required - Template name.

### Returns
- **string[]** - List of module names.

### Example
```ts
import { getModulesForTemplate } from '@subboost/core/generator/proxy-groups';

const modules = getModulesForTemplate('standard');
```
```

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

### Build Clash YAML options and check subscription info node

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/core-subscription-config.md

Imports utilities from @subboost/core subscription modules, builds generation options from saved config and parsed nodes, generates Clash YAML, and checks if a node name is a subscription info node.

```javascript
import { buildGenerateOptionsFromConfig } from "@subboost/core/subscription/config-utils";
import { buildProxyProvidersFromConfig } from "@subboost/core/subscription/proxy-providers";
import { isSubscriptionInfoNodeName } from "@subboost/core/subscription/info-node-name";

const options = buildGenerateOptionsFromConfig(savedConfig, { nodes: parsedNodes });
const yaml = generateClashYaml(options);

if (isSubscriptionInfoNodeName(node.name)) {
  console.log("account-info node:", node.name);
}
```

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

### GET /favicon.ico

Source: https://github.com/subboost/subboost/blob/main/_autodocs/endpoints.md

Endpoint that serves the favicon by redirecting to /icon.png with a 308 permanent redirect.

```APIDOC
## GET /favicon.ico

### Description
Redirects to the favicon icon at /icon.png. This endpoint returns a 308 permanent redirect and sets the Cache-Control header to 'public, max-age=0, must-revalidate'.

### Method
GET

### Endpoint
/favicon.ico

### Response
#### Success Response (308)
- **Location** (string) - The redirect target: /icon.png
- **Cache-Control** (string) - The cache control header: public, max-age=0, must-revalidate
```

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

### GET /api/templates/[id]

Source: https://github.com/subboost/subboost/blob/main/_autodocs/endpoints.md

Fetches a single template by ID, including its decrypted configuration.

```APIDOC
## GET /api/templates/[id]

### Description
Retrieves a specific template by ID. Authentication is optional; 401 when detail resolution requires auth.

### Method
GET

### Endpoint
/api/templates/[id]

### Path Parameters
- **id** (string) - Required - The template ID.

### Response
#### Success Response (200)
- **template** (object) - LocalTemplateDetail including decrypted `config`.

#### Error Responses
- **404** - `NOT_FOUND` when the template does not exist.
- **401** - `UNAUTHORIZED` when detail resolution requires authentication.
```

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

### GET /api/rules/search

Source: https://github.com/subboost/subboost/blob/main/_autodocs/endpoints.md

Searches the rule catalog by keyword, type, and pagination. Returns a RuleSearchResult.

```APIDOC
## GET /api/rules/search

### Description
Searches the rule catalog by keyword, type, and pagination. Returns a RuleSearchResult.

### Method
GET

### Endpoint
/api/rules/search

### Parameters
#### Query Parameters
- **keyword** (string) - Optional - Default: "" - Matched against id/name/nameZh.
- **type** (string) - Optional - Default: "all" - Filter: "all" | "geosite" | "geoip".
- **page** (number) - Optional - Default: 1 - Page number, 1..5000.
- **size** (number) - Optional - Default: 20 - Page size, 1..50.

### Response
#### Success Response (200)
- **RuleSearchResult** (object) - The search result (see server-core-rules.md).

#### Error Responses
- **503 RULE_INDEX_UNAVAILABLE** - Returns `{ items: [], source: "unavailable", error, code }`.
```

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

### getEffectiveModuleRules

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/core-generator-modules.md

Gets the effective rules for a module, likely combining built-in and custom rules.

```APIDOC
## getEffectiveModuleRules

### Description
Gets the effective rules for a module, likely combining built-in and custom rules.

### Method
Function

### Signature
```ts
export { getEffectiveModuleRules }
```

### Parameters
- (Not documented in source)

### Returns
- (Not documented in source)

### Example
```ts
// Usage not documented in source
```
```

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

### getGroupTarget(groupId)

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/core-generator-modules.md

Function to get the target group name for a given group ID.

```APIDOC
## getGroupTarget(groupId)

### Description
Returns the target group name for a given group ID.

### Method
Function

### Signature
`getGroupTarget(groupId: string): string`

### Parameters
- **groupId** (string) - Required - Group ID.

### Returns
- **string** - Target group name.

### Example
```ts
import { getGroupTarget } from '@subboost/core/generator/proxy-groups';

const target = getGroupTarget('select');
```
```

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

### Brand constants and createSubBoostManifest type declaration

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/ui-brand.md

Defines the brand constants and the SubBoostManifest type, plus the createSubBoostManifest function that returns the PWA manifest with name set to the product title, start_url "/", display "standalone", background_color "#0f0d1a", theme_color "#1e1b4b", icons pointing to /icon.png at 512x512 for both any and maskable purposes, and lang "zh-CN".

```ts
export const SUBBOOST_SITE_NAME: string                 // "SubBoost"
export const SUBBOOST_PRODUCT_TITLE: string             // "SubBoost - Clash 订阅转换与管理服务"
export const SUBBOOST_PRODUCT_DESCRIPTION: string       // "Clash 订阅转换、生成与管理工具，支持链式代理、智能分流、多协议和多订阅聚合。"
export const SUBBOOST_FOOTER_DESCRIPTION: string        // "Clash 订阅转换、生成和管理工具，让配置更简单"
export const SUBBOOST_THEME_COLOR: string               // "#1e1b4b"
export const SUBBOOST_ICON_PATH: string                 // "/icon.png"
export const SUBBOOST_FAVICON_PATH: string              // "/favicon.ico"
export const SUBBOOST_KEYWORDS: string[]                // ["Clash", "订阅转换", "订阅生成", "订阅管理", "链式代理", "智能分流", "订阅聚合", "代理配置", "SubBoost", "Clash 配置", "多订阅管理"]
export const SUBBOOST_MANIFEST_CATEGORIES: string[]     // ["utilities", "productivity"]

export type SubBoostManifest = {
  name: string;
  short_name: string;
  description: string;
  start_url: string;
  display: "standalone";
  background_color: string;
  theme_color: string;
  orientation: "portrait-primary";
  icons: Array<{ src: string; sizes: string; type: string; purpose: "any" | "maskable" }>;
  categories: string[];
  lang: string;
};

export function createSubBoostManifest(): SubBoostManifest
```

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

### GET /api/subscriptions/[id]/config.yaml

Source: https://github.com/subboost/subboost/blob/main/_autodocs/endpoints.md

Public endpoint that returns the Clash YAML configuration for a subscription.

```APIDOC
## GET /api/subscriptions/[id]/config.yaml

### Description
Generates and caches the Clash YAML configuration for a subscription. Public endpoint using the subscription token.

### Method
GET

### Endpoint
/api/subscriptions/[id]/config.yaml

### Path Parameters
- **id** (string) - Required - Subscription token (opaque).

### Authentication
- None (public, rate-limited).

### Rate Limits
- 600/min per trusted client.
- 120/min per token.

### Response
#### Success Response (200)
- Content-Type: text/plain; charset=utf-8
- Headers: Subscription-Userinfo, Profile-Web-Page-Url, Plan-Name, Subscription-Auto-Update-Interval, Cache-Control: no-store
- Body: Clash YAML content.

#### Response Example
```yaml
proxies: []
```

### Error Responses
- **404 NOT_FOUND** - Unknown token.
- **429 RATE_LIMITED** - Rate limit exceeded.
```

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

### Run common checks

Source: https://github.com/subboost/subboost/blob/main/README.md

Runs common checks: linting, unit tests, and local app validation.

```bash
npm run lint
npm run test:unit
npm run check:local-app
```

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

### isV2EncryptedField signature

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/server-core-crypto.md

Type signature for isV2EncryptedField. Returns true when ciphertext starts with "v2:".

```ts
export function isV2EncryptedField(ciphertext: string | null | undefined): boolean
```

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

### looksLikeStandardVmessStyle(content)

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/core-parser-protocols.md

Helper to detect standard VMess links.

```APIDOC
## looksLikeStandardVmessStyle(content)

### Description
Determines whether the given content looks like a standard VMess link.

### Method
looksLikeStandardVmessStyle

### Parameters
- **content** (string) - Required - The content to inspect.

### Returns
- **boolean** - True if the content looks like a standard VMess link.
```

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

### getAllGroupNames(enabledModules, customProxyGroups)

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/core-generator-modules.md

Function to get all group names for enabled modules and custom proxy groups.

```APIDOC
## getAllGroupNames(enabledModules, customProxyGroups)

### Description
Returns all group names for the given enabled modules and custom proxy groups.

### Method
Function

### Signature
`getAllGroupNames(enabledModules: string[], customProxyGroups: CustomProxyGroup[] = []): string[]`

### Parameters
- **enabledModules** (string[]) - Required - List of enabled module names.
- **customProxyGroups** (CustomProxyGroup[]) - Optional - Custom proxy groups (default `[]`).

### Returns
- **string[]** - List of group names.

### Example
```ts
import { getAllGroupNames } from '@subboost/core/generator/proxy-groups';

const names = getAllGroupNames(['select', 'auto']);
```
```

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

### POST /api/source-import

Source: https://github.com/subboost/subboost/blob/main/_autodocs/endpoints.md

Fetches and parses a remote subscription URL with SSRF guards. Requires admin authentication.

```APIDOC
## POST /api/source-import

### Description
Fetches and parses a remote subscription URL with SSRF guards (max 10 MB, ≤ 3 redirects, safe-URL validation). Requires an admin session cookie.

### Method
POST

### Endpoint
/api/source-import

### Parameters
#### Request Body
- **url** (string) - Required - The remote subscription URL to fetch and parse.
- **userinfoUrl** (string) - Optional - Additional userinfo URL.
- **userinfoUserAgent** (string) - Optional - User agent for the userinfo request.

### Request Example
{
  "url": "https://example.com/sub",
  "userinfoUrl": "https://example.com/userinfo",
  "userinfoUserAgent": "Mozilla/5.0"
}

### Response
#### Success Response (200)
- **content** (string) - The fetched content.
- **headers** (object) - Response headers.
- **parseResult** (object) - Parsing result containing nodes, errors, totalParsed, and totalFailed.

#### Response Example
{
  "content": "...",
  "headers": {},
  "parseResult": {
    "nodes": [],
    "errors": [],
    "totalParsed": 0,
    "totalFailed": 0
  }
}

#### Error Responses
- **400 BAD_REQUEST** - Format category error, includes errorInfo.
- **400 INTERNAL_ERROR** - Network/parse/security category error, includes errorInfo.
```

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

### stripImportedNodeControlFields functions

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/core-subscription-config.md

Removes SubBoost-internal control fields (everything starting with `_`, e.g. `_sourceIds`) from nodes before they enter generated config.

```typescript
export function stripImportedNodeControlFields(node: ParsedNode): ParsedNode
export function stripImportedNodeControlFieldsFromList(nodes: ParsedNode[]): ParsedNode[]
```

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

### GET /api/rules/cn-candidates

Source: https://github.com/subboost/subboost/blob/main/_autodocs/endpoints.md

Retrieves CN rule candidates based on module and exclusion filters. Optionally includes debug information.

```APIDOC
## GET /api/rules/cn-candidates

### Description
Retrieves CN rule candidates based on module and exclusion filters. Optionally includes debug information.

### Method
GET

### Endpoint
/api/rules/cn-candidates

### Parameters
#### Query Parameters
- **modules** (string) - Optional - Default: all modules - Comma-separated module ids.
- **excluded** (string) - Optional - Default: "" - Comma-separated rule keys to exclude.
- **debug** (string) - Optional - If set to "1", includes `allItems` in the response.

### Response
#### Success Response (200)
- **CnRuleCandidateResponse** (object) - The candidate response (see server-core-rules.md).

#### Error Responses
- **503 RULE_INDEX_UNAVAILABLE** - Rule index unavailable.
```

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

### isV2EncryptedField

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/server-core-crypto.md

Checks whether a given ciphertext string uses the v2 encrypted field format by verifying it starts with the 'v2:' prefix.

```APIDOC
## isV2EncryptedField

### Description
Returns `true` when the provided ciphertext starts with `"v2:"`, indicating it is a v2 encrypted field.

### Method
Function

### Signature
```ts
export function isV2EncryptedField(ciphertext: string | null | undefined): boolean
```

### Parameters
- **ciphertext** (`string | null | undefined`) - Required - The ciphertext string to check.

### Return Value
- **boolean** - `true` if the ciphertext starts with `"v2:"`, otherwise `false`.

### Example
```js
import { isV2EncryptedField } from "@subboost/server-core/crypto";
const result = isV2EncryptedField("v2:..."); // true
```
```

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

### POST /api/subscriptions

Source: https://github.com/subboost/subboost/blob/main/_autodocs/endpoints.md

Creates a new subscription with the provided configuration.

```APIDOC
## POST /api/subscriptions

### Description
Creates a new subscription.

### Method
POST

### Endpoint
/api/subscriptions

### Authentication
- Session cookie - Required.

### Request Body
- **name** (string) - Required - Subscription name.
- **urls** (array of string) - Optional - Subscription URLs.
- **nodes** (array of ParsedNode) - Optional - Parsed nodes.
- **config** (object) - Required - Configuration object.
- **smartNodeMatchingEnabled** (boolean) - Optional - Enable smart node matching.
- **autoUpdateInterval** (number) - Optional - Auto-update interval.
- **subscriptionInfo** (object) - Optional - Subscription info.

### Request Example
{
  "name": "My Subscription",
  "urls": ["https://example.com/sub"],
  "nodes": [],
  "config": {}
}

### Response
#### Success Response (201)
- **subscription** (SubscriptionSummary) - The created subscription.

#### Response Example
{
  "subscription": {}
}

### Error Responses
- **400 BAD_REQUEST** - Missing name, no urls or nodes, node count > 10000, or node-name filter removes everything.
```

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

### GET /api/releases/latest

Source: https://github.com/subboost/subboost/blob/main/_autodocs/endpoints.md

Public endpoint that checks the latest release of the SubBoost/subboost repository on GitHub. It returns version information and whether an update is available.

```APIDOC
## GET /api/releases/latest

### Description
Checks the GitHub SubBoost/subboost repository for the latest release. This endpoint is public and uses ISR with a revalidation period of 3600 seconds. It returns the current version, the latest version, and whether an update is available.

### Method
GET

### Endpoint
/api/releases/latest

### Response
#### Success Response (200)
- **currentVersion** (string) - The current version of the application.
- **latestVersion** (string | null) - The latest version from GitHub, or null if not available.
- **latestTag** (string | null) - The latest release tag, or null if not available.
- **releaseUrl** (string | null) - The URL to the latest release, or null if not available.
- **hasUpdate** (boolean) - Indicates whether an update is available.

#### Response Example
{
  "currentVersion": "1.0.0",
  "latestVersion": "1.1.0",
  "latestTag": "v1.1.0",
  "releaseUrl": "https://github.com/SubBoost/subboost/releases/tag/v1.1.0",
  "hasUpdate": true
}
```

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

### parseSubscriptionContentByRegistry(content: string): ParseResult

Source: https://github.com/subboost/subboost/blob/main/_autodocs/api-reference/core-parser.md

Runs the parser registry in order (clash-yaml → platform-config → config-lines → link-lines) and returns the first result with nodes.

```APIDOC
## parseSubscriptionContentByRegistry

### Description
Runs the parser registry in order: `clash-yaml` → `platform-config` → `config-lines` → `link-lines`; returns the first result with nodes (accumulating errors), falling back to `link-lines`.

### Method
FUNCTION

### Endpoint
`parseSubscriptionContentByRegistry(content: string): ParseResult`

### Parameters
#### Parameters
- **content** (string) - Required - The subscription content to parse.

### Return Type
`ParseResult`
```
Tokens:
Raw