Sub-Store

https://github.com/sub-store-org/sub-store-front-end
Admin
Sub-Store is an advanced subscription manager that converts and formats proxy subscriptions across...
Tokens:69,178
Snippets:470
Trust Score:8.8
License:GPL-3.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Usage example for useHostAPI, getHostAPIUrl, and getHostAPIShareBaseUrl

Source: https://github.com/sub-store-org/sub-store-front-end/blob/master/_autodocs/api-reference/hooks-host-api.md

Shows how to import and use the main functions from the useHostAPI module. It demonstrates getting the current API URL, adding a new API (which verifies the connection unless skipped), switching to it, and handling URL query parameters for connection setup.

```typescript
import { useHostAPI, getHostAPIUrl, getHostAPIShareBaseUrl } from '@/hooks/useHostAPI';

const { apis, setCurrent, addApi, handleUrlQuery } = useHostAPI();

console.log(getHostAPIUrl()); // e.g. 'https://sub.store'

const added = await addApi({ name: 'local', url: 'http://192.168.1.19:3000' });
if (added) setCurrent('local');

const handled = await handleUrlQuery({ errorCb: async () => {
  // no ?api= / ?magicpath= params — fall back to default backend connection
}});
```

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

### Install hyper-link extension via npm

Source: https://github.com/sub-store-org/sub-store-front-end/blob/master/src/views/editCode/link/README.md

Install the @uiw/codemirror-extensions-hyper-link package using npm.

```bash
npm install @uiw/codemirror-extensions-hyper-link --save
```

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

### GET /download/{name}

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

Downloads a configuration by key. `params` are passed through verbatim.

```APIDOC
## GET /download/{name}

### Description
Downloads a configuration by key. `params` are passed through verbatim.

### Method
GET

### Endpoint
/download/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - Download key.

#### Query Parameters
- **params** (any) - Optional - Extra query parameters, e.g. `{ token, type }` for share downloads.

### Response
#### Success Response (200)
- **data** (MyAxiosRes) - Response data.

#### Response Example
{
  "data": {}
}
```

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

### initStores usage example

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

Shows how to import and call initStores. Invoked by router.beforeResolve when backend changes and by useGlobalStore.setHostAPI.

```ts
import { initStores } from '@/utils/initApp';

// invoked by router.beforeResolve when backend changes and by useGlobalStore.setHostAPI
await initStores(true, true, true);
```

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

### GET /api/settings

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

Reads all settings.

```APIDOC
## GET /api/settings

### Description
Read all settings.

### Method
GET

### Endpoint
/api/settings

### Response
#### Success Response (200)
- **data** (SettingsPostData) - Settings data.
- **syncTime** (string) - Sync timestamp.
- **avatarUrl** (string) - Avatar URL.
- **artifactStore** (any) - Artifact store information.
- **artifactStoreStatus** (string) - Artifact store status.
- **theme** (string) - Theme setting.

#### Response Example
```json
{
  "data": {
    "key": "value"
  },
  "syncTime": "2023-01-01T00:00:00Z",
  "avatarUrl": "https://example.com/avatar.png",
  "artifactStore": {},
  "artifactStoreStatus": "ok",
  "theme": "dark"
}
```
```

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

### GET /api/{type}/{name}?raw=1

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

Returns the final generated configuration as a binary blob (download).

```APIDOC
## GET /api/{type}/{name}?raw=1

### Description
Returns the final generated configuration as a binary blob (download).

### Method
GET

### Endpoint
/api/{type}/{name}?raw=1

### Parameters
#### Path Parameters
- **type** ('sub' | 'collection') - Required - Entity type.
- **name** (string) - Required - Entity name.

### Response
#### Success Response (200)
- **body** (Blob) - The final generated configuration as a binary blob.

#### Response Example
[Binary blob]
```

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

### Use useSystemStore to initialize and check breakpoint

Source: https://github.com/sub-store-org/sub-store-front-end/blob/master/_autodocs/api-reference/stores-settings.md

Usage example for the system store: import the store and breakpoint constants, initialize the store with initSystemState(), then check screenWidth against SIDEBAR_EXPANDED_BREAKPOINT to detect a wide layout.

```ts
import { useSystemStore, SIDEBAR_BREAKPOINT, SIDEBAR_EXPANDED_BREAKPOINT } from '@/store/system';

const systemStore = useSystemStore();
systemStore.initSystemState();

if (systemStore.screenWidth >= SIDEBAR_EXPANDED_BREAKPOINT) {
  console.log('wide layout available');
}
```

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

### GET /api/sync/artifacts

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

Syncs all artifacts.

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

### Description
Syncs all artifacts.

### Method
GET

### Endpoint
/api/sync/artifacts

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

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

### useArchiveStore usage example

Source: https://github.com/sub-store-org/sub-store-front-end/blob/master/_autodocs/api-reference/stores-data.md

Shows how to import and use the archive store: fetch entries, then restore the first one with options to disable notifications and refresh related data.

```typescript
import { useArchiveStore } from '@/store/archive';

const archiveStore = useArchiveStore();

if (await archiveStore.fetchEntries()) {
  const first = archiveStore.entries[0];
  if (first) {
    await archiveStore.restoreEntry(first, { showNotify: false, refreshRelatedData: true });
  }
}
```

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

### GET /api/storage

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

Downloads a full storage backup as a binary blob.

```APIDOC
## GET /api/storage

### Description
Download a full storage backup as a binary blob.

### Method
GET

### Endpoint
/api/storage

### Response
#### Success Response (200)
- **body** (binary Blob) - The storage backup file.

#### Response Example
```
<binary data>
```
```

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

### GET /api/wholeFiles

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

Lists files with their content.

```APIDOC
## GET /api/wholeFiles

### Description
List files with their content.

### Method
GET

### Endpoint
/api/wholeFiles

### Response
#### Success Response (200)
- **data** (array of file objects) - File objects with `content`.

#### Response Example
```json
{
  "data": [
    {
      "name": "example.txt",
      "content": "file content"
    }
  ]
}
```
```

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

### Usage with vanilla CodeMirror

Source: https://github.com/sub-store-org/sub-store-front-end/blob/master/src/views/editCode/link/README.md

Example of using the hyperLink extension with the core CodeMirror EditorView and EditorState.

```js
import { EditorView } from '@codemirror/view';
import { EditorState } from '@codemirror/state';
import { hyperLink } from '@uiw/codemirror-extensions-hyper-link';

const code = `https://uiwjs.github.io/react-codemirror`;

const state = EditorState.create({
  doc: code,
  extensions: [hyperLink],
});

const view = new EditorView({
  parent: document.querySelector('#editor'),
  state,
});
```

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

### PWA helpers usage example

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

Shows how to import and use isDynamicImportFailure and resetPwaCacheAndReload together. If a dynamic import failure is detected, it resets the cache and reloads with a custom delay.

```ts
import { isDynamicImportFailure, resetPwaCacheAndReload } from '@/utils/pwa';

if (isDynamicImportFailure(someError)) {
  await resetPwaCacheAndReload({
    notify: useAppNotifyStore().showNotify,
    t: (key: string) => key,
    reloadDelay: 2000,
  });
}
```

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

### Start Sub-Store front-end with pnpm

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

Commands to set up and run the Sub-Store front-end development environment. Requires pnpm v11.0.9 via Corepack, Vite v2.9.9, Vue v3.2, Pinia v2, and TypeScript v4.6.

```bash
# enable the pinned package manager
corepack enable

# install dependencies
pnpm i

# run the server
pnpm dev

# build the app
pnpm build

# preview the built app
pnpm preview
```

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

### GET /api/artifacts/restore

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

Restores artifacts from the artifact store.

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

### Description
Restores artifacts from the artifact store.

### Method
GET

### Endpoint
/api/artifacts/restore

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

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

### Using useLogsApi to fetch and clear logs

Source: https://github.com/sub-store-org/sub-store-front-end/blob/master/_autodocs/api-reference/age-logs-api.md

Usage example for useLogsApi: fetches logs with filters and clears all logs or a single trace by traceId.

```ts
import { useLogsApi } from '@/api/logs';

const logsApi = useLogsApi();

const res = await logsApi.getLogs({ limit: 100, keyword: 'error', regex: true });
if (res.data.status === 'success') {
  const { logs, total, maxCount } = res.data.data; // DebugLogsResponse
  logs.forEach((entry) => console.log(entry.id, entry.level, entry.message));
}

await logsApi.clearLogs(); // wipe everything
await logsApi.clearLogs({ traceId: 'req-123' }); // clear a single trace
```

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

### Utility function usage examples

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

Demonstrates the usage of various utility functions including image fitting, clipboard operations, file downloads, semantic version comparison, data flow string conversion, and relative date formatting.

```ts
import { resolveImageFit, DEFAULT_IMAGE_FIT } from '@/utils/iconFit';
import { copyText } from '@/utils/clipboard';
import { downloadBlobResponse } from '@/utils/download';
import { semverGte } from '@/utils/semver';
import { getString } from '@/utils/flowTransfer';
import { butifyDate } from '@/utils/butifyDate';

const fit = resolveImageFit(undefined, DEFAULT_IMAGE_FIT); // 'contain'
await copyText('hello');
downloadBlobResponse(blobRes, 'out.txt');
console.log(semverGte('2.22.6', '2.22.5')); // true
console.log(getString(1024 * 5, 1024 * 1024, 'B')); // '5 KB / 1 MB'
console.log(butifyDate(Date.now() - 60_000));
```

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

### GET /api/subs

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

Lists all subscriptions. No request parameters are required.

```APIDOC
## GET /api/subs

### Description
List all subscriptions.

### Method
GET

### Endpoint
/api/subs

### Parameters
None

### Response
#### Success Response (200)
- **data** (Sub[]) - List of subscriptions

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

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

### Combined usage of hooks

Source: https://github.com/sub-store-org/sub-store-front-end/blob/master/_autodocs/api-reference/hooks-ui.md

Combined usage example showing how to consume useWideScreenNarrowMode, useListViewMode, useThemes, and useBackend together. It logs the effective list view when the backend is ready and toggles wide-screen narrow mode when the sidebar should show.

```ts
import { useWideScreenNarrowMode } from '@/hooks/useWideScreenNarrowMode';
import { useListViewMode } from '@/hooks/useListViewMode';
import { useThemes } from '@/hooks/useThemes';
import { useBackend } from '@/hooks/useBackend';

const { shouldShowSideBar, toggleWideScreenNarrowMode } = useWideScreenNarrowMode();
const { effectiveListViewMode, toggleListViewMode } = useListViewMode();
const { isEnvReady } = useBackend();
const { pickerList } = useThemes();

if (isEnvReady) {
  console.log('backend connected; list view:', effectiveListViewMode);
}
if (shouldShowSideBar) {
  await toggleWideScreenNarrowMode();
}
```

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

### GET /api/utils/env

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

Retrieves backend environment information with optional cache bypass.

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

### Description
Retrieves the backend environment information (version, backend platform, feature flags, deployment mode). The response is cached in localStorage for one hour unless bypassCache is set to true.

### Method
GET

### Endpoint
/api/utils/env

### Parameters
#### Query Parameters
- **options.bypassCache** (boolean) - Optional - When true, skips the localStorage cache and forces a fresh request.

### Request Example
```ts
const res = await envApi.getEnv({ bypassCache: true });
```

### Response
#### Success Response (200)
- **data** (object) - The ENV object containing environment details.
- **data.meta** (any) - Optional metadata.
- **data.hasNewVersion** (boolean) - Indicates if a new version is available.
- **data.latestVersion** (string) - The latest version string.
- **data.version** (string) - The current version string.
- **data.feature** (any) - Feature flags.
- **data.backend** (string) - The backend platform identifier (e.g., 'sing-box', 'Stash', 'QX', etc.).

#### Response Example
```json
{
  "status": "success",
  "data": {
    "version": "1.0.0",
    "backend": "sing-box"
  }
}
```

### Error Handling
- If the backend is reachable but the env request fails, the response will have a non-success status and include an error code and message.
```

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

### GET /api/files

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

Lists file metadata without content.

```APIDOC
## GET /api/files

### Description
List file metadata without content.

### Method
GET

### Endpoint
/api/files

### Response
#### Success Response (200)
- **data** (array of file objects) - File metadata without content.

#### Response Example
```json
{
  "data": [
    {
      "name": "example.txt",
      "size": 123
    }
  ]
}
```
```

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

### GET /api/wholeFile/{name}?raw=1

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

Exports a file in raw format as a binary blob.

```APIDOC
## GET /api/wholeFile/{name}?raw=1

### Description
Export a file in raw format as a binary blob.

### Method
GET

### Endpoint
/api/wholeFile/{name}?raw=1

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

#### Query Parameters
- **raw** (integer) - Required - Set to `1` to get raw export.

### Response
#### Success Response (200)
- **body** (binary Blob) - The raw file content.

#### Response Example
```
<binary data>
```
```

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

### getSettings(): AxiosPromise<MyAxiosRes>

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

GET /api/settings — Returns the full settings object. The SucceedResponse.data shape matches SettingsPostData plus syncTime, avatarUrl, artifactStore, artifactStoreStatus, and theme.

```APIDOC
## GET /api/settings

### Description
Returns the full settings object. The `SucceedResponse.data` shape matches `SettingsPostData` plus `syncTime`/`avatarUrl`/`artifactStore`/`artifactStoreStatus`/`theme`.

### Method
GET

### Endpoint
/api/settings

### Parameters
None documented.

### Response
#### Success Response (200)
- **data** (object) - Full settings object matching `SettingsPostData` plus `syncTime`, `avatarUrl`, `artifactStore`, `artifactStoreStatus`, `theme`.

#### Response Example
(Not provided in source.)
```

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

### GET /api/utils/backup

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

Performs Gist sync operations (download or upload).

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

### Description
Perform Gist sync operations (download or upload).

### Method
GET

### Endpoint
/api/utils/backup

### Parameters
#### Query Parameters
- **action** (string) - Required - Action to perform: `download` or `upload`.
- **keep** (string) - Optional - Comma-joined keys to keep.
- **encode** (string) - Optional - Encoding method: `base64`, `plaintext`, or `age`.
- **tokenStrategy** (string) - Optional - Token strategy: `overwrite` or `keep`.

### Response
#### Success Response (200)
- **data** (MyAxiosRes) - Response data.

#### Response Example
```json
{
  "data": {}
}
```
```

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

### GET /api/collections

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

Lists all collections. No request parameters are required.

```APIDOC
## GET /api/collections

### Description
List all collections.

### Method
GET

### Endpoint
/api/collections

### Parameters
None

### Response
#### Success Response (200)
- **data** (Collection[]) - List of collections

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

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

### Using runFrontendRequestTask and runFrontendRequestTasks

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

Usage examples for the request concurrency utilities. The single task uses an AbortController and a priority of 10; the batch call runs multiple tasks with a shared priority of 5. Both rely on the concurrency gate and support abort handling via isAbortError.

```ts
import { runFrontendRequestTask, runFrontendRequestTasks, isAbortError } from '@/utils/requestConcurrency';

// Single labeled task with concurrency control + abort support
const controller = new AbortController();
try {
  const result = await runFrontendRequestTask(
    () => axios.get('/api/things'),
    'things.getThings',
    { priority: 10, signal: controller.signal },
  );
} catch (e) {
  if (isAbortError(e)) console.log('aborted');
}

// Batch — all share the same options
const { runFrontendRequestTasks } = await import('@/utils/requestConcurrency');
await runFrontendRequestTasks([
  { label: 'a', task: () => fetchA() },
  { label: 'b', task: () => fetchB() },
], { priority: 5 });
```

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

### GET /api/artifacts

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

Retrieves all artifacts. Returns an array of Artifact objects.

```APIDOC
## GET /api/artifacts

### Description
Returns all artifacts as an array of Artifact objects.

### Method
GET

### Endpoint
/api/artifacts

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **data** (Artifact[]) - Array of artifact objects.

#### Response Example
{
  "status": "success",
  "data": [
    {
      "name": "example-artifact",
      "platform": "Clash",
      "sync": true
    }
  ]
}
```

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

### Age crypto usage example

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

Shows how to generate an age key pair and derive a public key from the secret key. Uses the exported functions from '@/utils/age'.

```TypeScript
import { generateKeyPair, derivePublicKey, AGE_KEY_TYPES } from '@/utils/age';

const pair = await generateKeyPair(AGE_KEY_TYPES.X25519);
const pub = await derivePublicKey(pair['age-secret-key']);
```

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

### Usage with React CodeMirror

Source: https://github.com/sub-store-org/sub-store-front-end/blob/master/src/views/editCode/link/README.md

Example of using the hyperLink extension in a React component with @uiw/react-codemirror.

```jsx
import CodeMirror from '@uiw/react-codemirror';
import { hyperLink } from '@uiw/codemirror-extensions-hyper-link';

const code = `https://uiwjs.github.io/react-codemirror`;

function App() {
  return <CodeMirror value={code} height="200px" extensions={[hyperLink]} />;
}
export default App;
```

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

### GET /download/{name}

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

Downloads an exported config directly. Also used for share downloads and forwards arbitrary query parameters.

```APIDOC
## GET /download/{name}

### Description
Download an exported config directly. Also used for share downloads; forwards arbitrary query parameters.

### Method
GET

### Endpoint
/download/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - Name of the config to download

#### Query Parameters
- **params** (any) - Optional - Caller-supplied query parameters (e.g., noCache=true)

### Response
#### Success Response (200)
- **body** (MyAxiosRes | Blob) - Response data or binary blob

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

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

### syncSettings(query: 'download' | 'upload', options?: GistBackupSyncOptions): AxiosPromise<MyAxiosRes>

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

GET /api/utils/backup — Syncs settings with the configured GitHub Gist. 'download' pulls settings from the Gist; 'upload' pushes settings to the Gist. Options control keep-list, encoding, and token strategy.

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

### Description
Syncs settings with the configured GitHub Gist. `'download'` pulls settings from the Gist; `'upload'` pushes settings to the Gist. Sent as `params.action`.

### Method
GET

### Endpoint
/api/utils/backup

### Parameters
#### Query Parameters
- **action** (string) - Required - `'download'` or `'upload'`.
- **keep** (string[]) - Optional - Setting keys to preserve (not overwritten on download); sent as comma-joined `params.keep`.
- **encode** (GistUploadMode) - Optional - `'base64' | 'plaintext' | 'age'`; sent as `params.encode`.
- **tokenStrategy** (Exclude<DownloadTokenStrategy, 'ask'>) - Optional - `'overwrite' | 'keep'`; sent as `params.tokenStrategy`.

### Request Example
(Not provided in source.)

### Response
#### Success Response (200)
- **data** (object) - Sync result.

#### Response Example
(Not provided in source.)
```

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

### GET /api/wholeFile/{name}

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

Returns the full file object including `content`.

```APIDOC
## GET /api/wholeFile/{name}

### Description
Returns the full file object including `content`.

### Method
GET

### Endpoint
/api/wholeFile/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - File name.

### Response
#### Success Response (200)
- **data** (object) - Full file object including `content`.

#### Response Example
{
  "status": "success",
  "data": {
    "name": "adblock.conf",
    "content": "payload:\n  - DOMAIN-SUFFIX,ads.com"
  }
}
```

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

### GET {backend}/api/utils/env (probe)

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

Performs a connection check during addApi and handleUrlQuery operations. Expects a response with status 'success' and uses a 3-second default timeout.

```APIDOC
## GET {backend}/api/utils/env (probe)

### Description
Performs a connection check during addApi and handleUrlQuery operations. Expects a response with status 'success' and uses a 3-second default timeout.

### Method
GET

### Endpoint
{backend}/api/utils/env

### Parameters
#### Path Parameters
- **backend** (string) - Required - The backend base URL.

### Response
#### Success Response (200)
- **status** (string) - The status of the probe, expected to be 'success'.

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

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

### GET /api/sync/artifacts

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

Triggers syncing of every artifact marked with sync: true.

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

### Description
Triggers syncing of every artifact marked with sync: true.

### Method
GET

### Endpoint
/api/sync/artifacts

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **data** (any) - The response data.

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

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

### downloadBackup(): AxiosPromise<Blob>

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

GET /api/storage — Downloads the full local storage backup (all settings + data) as a file. The response is a Blob payload.

```APIDOC
## GET /api/storage

### Description
Downloads the full local storage backup (all settings + data) as a file. The `SucceedResponse` is replaced by a `Blob` payload.

### Method
GET

### Endpoint
/api/storage

### Parameters
None documented.

### Response
#### Success Response (200)
- **body** (Blob) - The backup file content.

#### Response Example
(Not provided in source.)
```

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

### Using getFlowsUrlList

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

Usage example for getFlowsUrlList. It returns an array of tuples containing URL, name, and optional flags parsed from the URL fragment.

```ts
import { getFlowsUrlList } from '@/utils/getFlowsUrlList';

const list = getFlowsUrlList(subs); // [[url, name, noFlow?, hideExpire?, showRemaining?], ...]
```

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

### Using useAgeApi to generate and derive keys

Source: https://github.com/sub-store-org/sub-store-front-end/blob/master/_autodocs/api-reference/age-logs-api.md

Usage example for useAgeApi: generates an X25519 key pair and derives the public key from the secret key. Checks the status field before accessing data.

```ts
import { useAgeApi } from '@/api/age';
import { AGE_KEY_TYPES } from '@/utils/age';

const ageApi = useAgeApi();

const pairRes = await ageApi.generateKeyPair(AGE_KEY_TYPES.X25519);
if (pairRes.data.status === 'success') {
  const { 'age-public-key': pub, 'age-secret-key': sec } = pairRes.data.data;
  console.log(pub, sec);
}

const pubRes = await ageApi.derivePublicKey(sec);
if (pubRes.data.status === 'success') {
  console.log(pubRes.data.data['age-public-key']);
}
```

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

### GET /api/wholeFile/{name}?raw=1

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

Returns raw file bytes for download. Consumers can pass the response to `downloadBlobResponse` (`src/utils/download.ts`).

```APIDOC
## GET /api/wholeFile/{name}?raw=1

### Description
Returns raw file bytes for download. Consumers can pass the response to `downloadBlobResponse` (`src/utils/download.ts`).

### Method
GET

### Endpoint
/api/wholeFile/{name}?raw=1

### Parameters
#### Path Parameters
- **name** (string) - Required - File name.

### Response
#### Success Response (200)
- **body** (blob) - Raw file bytes.

#### Response Example
[Binary data]
```

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

### GET /api/wholeFiles

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

Returns files with full content. `SucceedResponse.data` is an array of file objects (`name`, `content`, ...) used by `useSubsStore` to populate `files`.

```APIDOC
## GET /api/wholeFiles

### Description
Returns files with full content. `SucceedResponse.data` is an array of file objects (`name`, `content`, ...) used by `useSubsStore` to populate `files`.

### Method
GET

### Endpoint
/api/wholeFiles

### Response
#### Success Response (200)
- **data** (array) - Array of file objects with `name`, `content`, etc.

#### Response Example
{
  "status": "success",
  "data": [
    {
      "name": "adblock.conf",
      "content": "payload:\n  - DOMAIN-SUFFIX,ads.com"
    }
  ]
}
```

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

### GET /api/files

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

Returns file metadata (no content). `SucceedResponse.data` is an array of file objects with `name`.

```APIDOC
## GET /api/files

### Description
Returns file metadata (no content). `SucceedResponse.data` is an array of file objects with `name`.

### Method
GET

### Endpoint
/api/files

### Response
#### Success Response (200)
- **data** (array) - Array of file objects with `name`.

#### Response Example
{
  "status": "success",
  "data": [
    {
      "name": "adblock.conf"
    }
  ]
}
```

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

### GET /api/tokens

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

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

```APIDOC
## GET /api/tokens

### Description
Lists all share tokens.

### Method
GET

### Endpoint
/api/tokens

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

### Response
#### Success Response (200)
- **data** (Share[]) - List of shares.

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

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

### Popup history usage example

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

Shows how to use pushPopupHistoryState and isPopupHistoryState to manage popup state with browser back/forward. It pushes a history state when opening a popup and listens for popstate to close it when leaving the popup layer.

```ts
import { pushPopupHistoryState, isPopupHistoryState } from '@/utils/popupHistory';

pushPopupHistoryState(); // open popup
window.addEventListener('popstate', (e) => {
  if (isPopupHistoryState(e.state)) return; // still inside popup layer
  closePopup();
});
```

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

### Custom match content with hyperLinkExtension

Source: https://github.com/sub-store-org/sub-store-front-end/blob/master/src/views/editCode/link/README.md

Example of customizing hyperlink matching using hyperLinkExtension and hyperLinkStyle with a custom regexp and handle function.

```tsx
import { EditorView } from '@codemirror/view';
import { EditorState } from '@codemirror/state';
import { hyperLinkExtension, hyperLinkStyle } from '@uiw/codemirror-extensions-hyper-link';

const code = `Hyper Link\n====`;

export const hyperLink: Extension = [
  hyperLinkExtension({
    regexp: /Hyper/gi,
    match: { Hyper: 'https://google.com' },
    handle: (value, input, from, to) => {
      if (value === 'Hyper') return 'https://google.com';
      return value;
    },
  }),
  hyperLinkStyle,
];

const state = EditorState.create({
  doc: code,
  extensions: [hyperLink],
});

const view = new EditorView({
  parent: document.querySelector('#editor'),
  state,
});
```

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

### GET /api/artifacts/restore

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

Restores artifacts from the internal artifact store/history, typically used after a failed batch sync.

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

### Description
Restores artifacts from the internal artifact store/history, typically used after a failed batch sync.

### Method
GET

### Endpoint
/api/artifacts/restore

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **data** (any) - The response data.

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

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

### GET /api/{type}/{name}

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

Returns the single sub/collection, formulas expanded. `SucceedResponse.data` is a `Sub` or `Collection`.

```APIDOC
## GET /api/{type}/{name}

### Description
Returns the single sub/collection, formulas expanded. `SucceedResponse.data` is a `Sub` or `Collection`.

### Method
GET

### Endpoint
/api/{type}/{name}

### Parameters
#### Path Parameters
- **type** (string) - Required - `'sub'` or `'collection'` (matches backend route prefix).
- **name** (string) - Required - Name of the entity; URL-encoded.

### Response
#### Success Response (200)
- **data** (Sub or Collection) - The requested entity.

#### Response Example
{
  "data": {}
}
```

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

### Extracting and formatting node names

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

Usage example for extracting node infos from a preview response and formatting them as a list of node names. extractPreviewNodeInfos recursively walks structured data, and formatPreviewNodeNames outputs one name per line.

```ts
import { extractPreviewNodeInfos, formatPreviewNodeNames } from '@/utils/previewNodeNames';

const infos = extractPreviewNodeInfos(previewResponse);
console.log(formatPreviewNodeNames(infos));
```

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

### Basic API call with request

Source: https://github.com/sub-store-org/sub-store-front-end/blob/master/_autodocs/api-reference/http-client.md

Shows the basic pattern for making a GET request with the request function. The response data is checked for the status field; on success, the parsed data is logged, otherwise the error message is logged.

```ts
import request from '@/api';

// All API modules follow this pattern:
const response = await request({
  url: '/api/settings',
  method: 'get',
});

if (response.data.status === 'success') {
  console.log(response.data.data); // parsed settings object
} else {
  // status === 'failed'
  console.error(response.data.error.message);
}
```

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

### GET /api/sub/flow/{name}

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

Long-polling traffic/usage info for one subscription. HTTP errors on this route do not trigger the global toast.

```APIDOC
## GET /api/sub/flow/{name}

### Description
Long-polling traffic/usage info for one subscription.

### Method
GET

### Endpoint
/api/sub/flow/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - Name of the subscription (URL-encoded)

#### Optional
- **signal** (AbortSignal) - Optional - Client-side abort signal (not sent in request)

### Response
#### Success Response (200)
- **data** (Flow) - Traffic/usage information
  - **status** (string) - 'success' or 'noFlow'
  - **showRemaining** (boolean) - Optional - Whether to show remaining
  - **hideExpire** (boolean) - Optional - Whether to hide expiry
  - **data** (object) - Usage details
    - **planName** (string) - Optional - Plan name
    - **appUrl** (string) - Optional - App URL
    - **remainingDays** (number) - Optional - Remaining days
    - **expires** (string) - Optional - Expiry date
    - **total** (number) - Total traffic
    - **usage** (object) - Usage breakdown
      - **upload** (number) - Upload usage
      - **download** (number) - Download usage

#### Response Example
{
  "status": "success",
  "data": {
    "status": "success",
    "data": {
      "total": 100,
      "usage": {
        "upload": 30,
        "download": 70
      }
    }
  }
}
```

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

### GET /api/{type}/{name}

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

Fetches a single subscription or collection with formulas expanded. The type must be either 'sub' or 'collection'.

```APIDOC
## GET /api/{type}/{name}

### Description
Fetch one sub/collection with formulas expanded.

### Method
GET

### Endpoint
/api/{type}/{name}

### Parameters
#### Path Parameters
- **type** (string) - Required - Type of resource: 'sub' or 'collection'
- **name** (string) - Required - Name of the sub/collection (URL-encoded)

### Response
#### Success Response (200)
- **data** (Sub | Collection) - The requested sub or collection

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

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

### Basic usage - read and patch settings

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

Shows how to import useSettingsApi, create an instance, and call setSettings to update settings. The response data is checked for success status and the updated settings are logged.

```typescript
import { useSettingsApi } from '@/api/settings';

const settingsApi = useSettingsApi();

const res = await settingsApi.setSettings({
  defaultUserAgent: 'clash-verge/v1.0',
  resourceCacheTtl: '86400',
});
if (res.data.status === 'success') {
  console.log(res.data.data.defaultUserAgent); // full updated settings
}
```

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

### Basic usage: create and list files

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

Creates a file named 'adblock.conf' with content, then fetches all files with full content and logs their names. Checks the response status before accessing data.

```ts
import { useFilesApi } from '@/api/files';

const filesApi = useFilesApi();

await filesApi.createFile({ name: 'adblock.conf', content: 'payload:\n  - DOMAIN-SUFFIX,ads.com' });

const res = await filesApi.getWholeFiles();
if (res.data.status === 'success') {
  const files = res.data.data;
  console.log(files.map(f => f.name));
}
```

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

### Using useGlobalStore: setHostAPI and setEnv

Source: https://github.com/sub-store-org/sub-store-front-end/blob/master/_autodocs/api-reference/stores-settings.md

Shows how to import and use the global store. Calls setHostAPI to switch the axios baseURL and reload stores, then setEnv with bypassCache and strict options, which throws Error('ENV_LOAD_FAILED') if no backend is found. Logs the environment version and Docker deployment flag when a backend exists.

```typescript
import { useGlobalStore } from '@/store/global';

const globalStore = useGlobalStore();

await globalStore.setHostAPI('https://my-backend.example.com'); // switches axios baseURL + reloads stores
const env = await globalStore.setEnv({ bypassCache: true, strict: true }); // throws Error('ENV_LOAD_FAILED') if no backend
if (env?.backend) {
  console.log(globalStore.env.version, globalStore.isDockerDeployment);
}
```

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

### GET /api/collections

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

Returns the list of all collections. `SucceedResponse.data` is an array of `Collection`.

```APIDOC
## GET /api/collections

### Description
Returns the list of all collections. `SucceedResponse.data` is an array of `Collection`.

### Method
GET

### Endpoint
/api/collections

### Parameters
No parameters.

### Response
#### Success Response (200)
- **data** (array of `Collection`) - List of collections.

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

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

### GET /api/subs

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

Returns the list of all subscriptions. `SucceedResponse.data` is an array of `Sub`.

```APIDOC
## GET /api/subs

### Description
Returns the list of all subscriptions. `SucceedResponse.data` is an array of `Sub`.

### Method
GET

### Endpoint
/api/subs

### Parameters
No parameters.

### Response
#### Success Response (200)
- **data** (array of `Sub`) - List of subscriptions.

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

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

### GET /api/file/{name}

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

Returns file metadata for a single file.

```APIDOC
## GET /api/file/{name}

### Description
Returns file metadata for a single file.

### Method
GET

### Endpoint
/api/file/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - File name.

### Response
#### Success Response (200)
- **data** (object) - File metadata.

#### Response Example
{
  "status": "success",
  "data": {
    "name": "adblock.conf"
  }
}
```

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

### GET /api/utils/refresh

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

Triggers a backend cache refresh for all remote resources.

```APIDOC
## [GET] /api/utils/refresh

### Description
Triggers the backend to re-fetch all remote resources (subscriptions/files used by artifacts) and rebuild its cache. After a successful refresh, the front-end clears its local envCache and reloads store data.

### Method
GET

### Endpoint
/api/utils/refresh

### Parameters
None

### Request Example
```ts
const res = await envApi.refreshCache();
```

### Response
#### Success Response (200)
- **data** (object) - The response data, typically a success status.

#### Response Example
```json
{
  "status": "success"
}
```

### Error Handling
- If the refresh fails, the response will have a non-success status and include an error code and message.
```

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

### Basic: Load subscriptions with useSubsApi

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

Imports useSubsApi and calls getSubs() to fetch subscriptions. Checks res.data.status for 'success' and returns the data array, otherwise throws an error with the message from res.data.error.message.

```TypeScript
import { useSubsApi } from '@/api/subs';

const subsApi = useSubsApi();

async function loadSubs() {
  const res = await subsApi.getSubs();
  if (res.data.status === 'success') {
    return res.data.data; // Sub[]
  }
  // status === 'failed'
  throw new Error(res.data.error.message);
}
```

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

### handleUrlQuery — connection DSL via URL parameters

Source: https://github.com/sub-store-org/sub-store-front-end/blob/master/_autodocs/api-reference/hooks-host-api.md

Parses window.location.search and acts on parameters like concurrency, timeout, api, and magicpath to configure the backend connection.

```APIDOC
## handleUrlQuery({ errorCb })

### Description
Parses window.location.search and acts on URL parameters to configure the backend connection.

### Method
Async Function

### Endpoint
N/A (URL parameter handling)

### Parameters
- **errorCb** (() => Promise<void>) - Optional. Callback invoked when no URL parameter is successfully handled.

### URL Parameters (order matters)
- **concurrency=<n>** - If n >= 1, sets localStorage.concurrency = n; else removes it.
- **concurrencyWaitTime=<n>** - If n > 0, stores it; else removes.
- **timeout=<n>** - If n > 0, sets localStorage.timeout = n; else removes.
- **shareBaseUrl=<url>** - Validated (http/https via isValidShareBaseUrl) and applied to the active API via editApi.
- **api=<url>** - First-priority: reflects existence, reconnects if it's already the current API (3 s /api/utils/env probe with AbortController) or switches to it (skipInit); otherwise addApi(..., skipConnectionCheck=true), switches, probes, sets localStorage.backendConfigured = 'true'.
- **magicpath=<path>** - Second-priority: builds `${window.location.origin}/${path}` and behaves like api (name `Custom_${Date.now()}`, sets both backendConfigured and magicPathConfigured).

### Returns
- **boolean** - true when a URL parameter was successfully handled; false otherwise (and errorCb is called).

### Probing
Uses localStorage.timeout (default 3000 ms) with an AbortController + setTimeout.

### Example
```ts
const handled = await handleUrlQuery({ errorCb: async () => {
  // no ?api= / ?magicpath= params — fall back to default backend connection
}});
```
```

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

### Create axios instance with configuration

Source: https://github.com/sub-store-org/sub-store-front-end/blob/master/_autodocs/api-reference/http-client.md

Creates the axios instance at module load with baseURL from `getHostAPIUrl()`, timeout from `getApiRequestTimeout()`, and JSON content type.

```ts
const service = axios.create({
  baseURL: getHostAPIUrl(),
  timeout: getApiRequestTimeout(),
  headers: { 'Content-Type': 'application/json' },
});
```

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

### GET /api/artifact/{name}

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

Retrieves a single artifact by its name. The name is URL-encoded.

```APIDOC
## GET /api/artifact/{name}

### Description
Returns a single artifact identified by its name.

### Method
GET

### Endpoint
/api/artifact/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - Artifact name.

### Request Example
None

### Response
#### Success Response (200)
- **data** (Artifact) - The requested artifact.

#### Response Example
{
  "status": "success",
  "data": {
    "name": "example-artifact",
    "platform": "Clash",
    "sync": true
  }
}
```

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

### Using useSubsStore to fetch, retrieve, and delete subscriptions

Source: https://github.com/sub-store-org/sub-store-front-end/blob/master/_autodocs/api-reference/stores-data.md

Shows how to import and use the subs store: fetch all data, retrieve a subscription by name, fetch flows with missingOnly, access the flows map, and delete a subscription with archive mode. The deleteSub call returns a boolean indicating success.

```ts
import { useSubsStore } from '@/store/subs';

const subsStore = useSubsStore();

await subsStore.fetchSubsData();
const sub = subsStore.getOneSub('my-sub');

await subsStore.fetchFlows(undefined, { missingOnly: true });
console.log(subsStore.flows[sub.url]);

const deleted = await subsStore.deleteSub('sub', 'my-sub', 'archive');
if (!deleted) console.warn('delete failed');
```

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

### GET /api/archives

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

Retrieves all archive entries. The response contains an array of ArchiveEntry objects.

```APIDOC
## GET /api/archives

### Description
Returns all archive entries. The response data is an array of `ArchiveEntry` objects.

### Method
GET

### Endpoint
/api/archives

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

#### Response Example
{
  "status": "success",
  "data": [
    {
      "id": "string",
      "itemType": "string",
      "displayName": "string"
    }
  ]
}
```

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

### initStores function signature

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

Exported async function that initializes app stores. Parameters control notification, flow fetching, and cache refresh. On failure, it clears envCache, re-throws on timeout, and resets subs and collections.

```ts
export const initStores = async (
  needNotify: boolean,
  needFetchFlow: boolean,
  needRefreshCache: boolean
) => { /* ... */ };
```

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

### Import hyperLink, hyperLinkExtension, hyperLinkStyle

Source: https://github.com/sub-store-org/sub-store-front-end/blob/master/src/views/editCode/link/README.md

Import the hyperLink, hyperLinkExtension, and hyperLinkStyle exports from the package.

```jsx
import { hyperLink, hyperLinkExtension, hyperLinkStyle } from '@uiw/codemirror-extensions-hyper-link';
```
Tokens:
Raw