@fecommunity/reactpress-toolkit 3.0.4 → 3.1.0

package/README.md

@@ -1,387 +1,272 @@
 # @fecommunity/reactpress-toolkit
 
-TypeScript-based API client toolkit for ReactPress, automatically generated from OpenAPI/Swagger specifications.
+ReactPress 的 TypeScript 工具包：从 OpenAPI/Swagger 生成的 API 客户端、站点配置类型、Next.js 主题 SSR 辅助，以及管理后台插件注册。
+
+## 包导出（`package.json` → `exports`）
+
+| 子路径 | 用途 |
+|--------|------|
+| `.` | 根入口：`api`、`config`、`theme`、`ui`、`plugin` 命名空间及常用 re-export |
+| `./api` | 各资源 HTTP 客户端类 |
+| `./api/instance` | 默认 `api` 实例与 `createApiInstance` |
+| `./types` | Swagger 生成的请求/响应类型 |
+| `./utils` | 与业务无关的纯工具（见下方模块表） |
+| `./config` | 环境变量、全局默认、`i18n` 文案（`config/locales/*.json`） |
+| `./theme` | 访客主题：SSR 拉数、运行时、扩展配置类型，并 re-export `./ui` |
+| `./theme/next-config` | `createReactPressNextConfig()` |
+| `./theme/node` | Node 专用（如读取主题管理端 locale 文件） |
+| `./ui` | 无样式主题组件与 hooks |
+| `./plugin` | 管理端插件聚合入口 |
+| `./plugin/admin` | 菜单注册、权限常量 |
+| `./plugin/client` | Web/Electron API 客户端工厂（推荐） |
+| `./plugin/react` | 与 `./plugin/client` 相同（兼容旧路径） |
+| `./plugin/dev` | Vite 开发端口重定向等 |
+
+**约定：** `src/` 下仅保留与上述导出对应的一级目录；实现细节放在子目录中，根目录用薄 shim 保持对外路径稳定（例如 `theme/node.ts` → `theme/build/node.ts`）。
+
+## 源码结构
 
-[![NPM Version](https://img.shields.io/npm/v/@fecommunity/reactpress-toolkit.svg)](https://www.npmjs.com/package/@fecommunity/reactpress-toolkit)
-[![License](https://img.shields.io/npm/l/@fecommunity/reactpress-toolkit.svg)](https://github.com/fecommunity/reactpress/blob/master/toolkit/LICENSE)
-[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
-
-## Overview
-
-The ReactPress Toolkit is an API client library that provides strongly-typed interfaces for interacting with the ReactPress backend services. It includes:
-
-- **Auto-generated API clients** for all ReactPress modules
-- **TypeScript definitions** for all data contracts
-- **Utility functions** for common operations
-- **HTTP client** with built-in authentication and error handling
-- **Automatic retry mechanisms** for failed requests
-- **Request/response interceptors** for logging
-
-The toolkit is automatically generated from the ReactPress backend's OpenAPI specification, ensuring that it's always in sync with the latest API changes. This eliminates manual API client maintenance and reduces the likelihood of API integration errors.
-
-## Installation
-
-```bash
-npm install @fecommunity/reactpress-toolkit
 ```
-
-or
-
-```bash
-yarn add @fecommunity/reactpress-toolkit
+src/
+├── api/              # OpenAPI 生成（勿手改业务逻辑）
+├── config/           # env、global、i18n + locales/
+├── types/            # Swagger 生成类型
+├── utils/            # 纯函数工具（theme/plugin 共用）
+│   ├── api-envelope.ts   # unpackList / unpackOne / unpackPaginated
+│   ├── cookie.ts         # readRequestCookie
+│   ├── date.ts           # formatDate、formatPublishDate*
+│   ├── email.ts          # 评论邮箱校验
+│   ├── error.ts          # ApiError、isApiError
+│   ├── json.ts           # safeJsonParse
+│   ├── jsonp.ts          # 浏览器 JSONP
+│   ├── object.ts         # deepMerge、getByPath、deepClone
+│   ├── setting.ts        # pickSiteSettings
+│   └── string.ts         # stripHtml、truncateWords
+├── plugin/
+│   ├── admin/        # AdminModule、菜单注册、权限
+│   ├── client/       # createClient、resolveApiBaseUrl
+│   ├── dev/          # devPortRedirectPlugin 等
+│   └── react/        # 仅 re-export client（兼容）
+├── theme/
+│   ├── api/          # themeApi、axios 封装（JSON/解包 re-export utils）
+│   ├── ssr/          # fetch、static props、站点 meta
+│   ├── visitor/      # 语言、会话、配色、运行时 mods
+│   ├── content/      # SEO、导航路径、摘要、静态资源 URL
+│   ├── preview/      # 预览 token / mods / config 查询参数
+│   ├── createCatalogApp.js  # 完整主题 _app 工厂（无 UI 框架依赖）
+│   ├── createApp.js  # Next `_app` 工厂（allowJs，随 tsc 输出到 dist）
+│   ├── extension/    # theme.json  schema、站点配置、与服务端共享的类型
+│   ├── node.ts       # → build/node
+│   ├── next-config.ts
+│   └── index.ts      # 对外 barrel
+└── ui/
+    ├── components/   # 无样式 React 组件
+    ├── context/      # ReactPressProvider、locale、runtime
+    └── hooks/        # 通用 React hooks（与具体页面无关）
 ```
 
-or
+## 安装
 
 ```bash
 pnpm add @fecommunity/reactpress-toolkit
 ```
 
-## Quick Start
+## 快速开始
 
-### Using the Default API Instance
+### API 客户端
 
 ```typescript
 import { api } from '@fecommunity/reactpress-toolkit';
+// 或
+import { api, createApiInstance } from '@fecommunity/reactpress-toolkit/api/instance';
 
-// Get all articles
 const articles = await api.article.findAll();
-
-// Get a specific article by ID
-const article = await api.article.findById('article-id');
-
-// Create a new article
-const newArticle = await api.article.create({
-  title: 'My New Article',
-  content: 'Article content here...',
-  // ... other properties
-});
 ```
 
-### Using Named Exports
+自定义 baseURL：
 
 ```typescript
-import { api, types, utils } from '@fecommunity/reactpress-toolkit';
-
-// Working with typed data
-const article: types.IArticle = {
-  id: '1',
-  title: 'Sample Article',
-  // ... other properties
-};
+import { createApiInstance } from '@fecommunity/reactpress-toolkit/api/instance';
 
-// Using utility functions
-const formattedDate = utils.formatDate(new Date());
+const customApi = createApiInstance({ baseURL: 'https://api.example.com/api' });
 ```
 
-## Configuration
+### 通用工具（`./utils`）
 
-You can create a custom API instance with specific configuration:
+与 Next/主题无关的逻辑应放在 `utils`，`theme` 仅 re-export 以保持 `@fecommunity/reactpress-toolkit/theme` 路径兼容：
 
 ```typescript
-import { http } from '@fecommunity/reactpress-toolkit';
-
-const customApi = http.createApiInstance({
-  baseURL: 'https://api.yourdomain.com',
-  timeout: 10000,
-  // ... other axios configuration options
-});
-
-// Use the custom instance
-const articles = await customApi.article.findAll();
+import {
+  safeJsonParse,
+  unpackList,
+  formatPublishDate,
+  stripHtml,
+  deepMerge,
+  getByPath,
+  pickSiteSettings,
+} from '@fecommunity/reactpress-toolkit/utils';
 ```
 
-## Enterprise Features
+| 模块 | 典型用途 |
+|------|----------|
+| `json` | 解析 setting 里的 JSON 字符串 |
+| `api-envelope` | 解包 Nest `TransformInterceptor` 的 `{ data }` |
+| `date` | 文章发布日期展示 |
+| `string` | 归档摘要 HTML 剥离、截断 |
+| `object` | theme.json 配置合并、点路径读写 |
+| `setting` | 把 settings 行映射为 props |
+| `cookie` | SSR 读取 `Cookie` 头 |
+| `email` | 访客评论邮箱格式 |
 
-### Automatic Retry Mechanisms
-```typescript
-import { http } from '@fecommunity/reactpress-toolkit';
-
-// Configure retry settings
-const customApi = http.createApiInstance({
-  baseURL: 'https://api.yourdomain.com',
-  retry: {
-    retries: 3,
-    retryDelay: 1000,
-    retryCondition: (error) => {
-      return error.response?.status === 503 || error.code === 'ECONNABORTED';
-    }
-  }
-});
-```
+### 管理后台插件
 
-### Request/Response Interceptors
 ```typescript
-import { http } from '@fecommunity/reactpress-toolkit';
-
-const monitoredApi = http.createApiInstance({
-  baseURL: 'https://api.yourdomain.com',
-  interceptors: {
-    request: (config) => {
-      // Add logging, metrics, etc.
-      console.log(`Request: ${config.method?.toUpperCase()} ${config.url}`);
-      return config;
-    },
-    response: (response) => {
-      // Add logging, metrics, etc.
-      console.log(`Response: ${response.status} ${response.config.url}`);
-      return response;
-    }
-  }
-});
+import type { AdminModule } from '@fecommunity/reactpress-toolkit/plugin/admin';
+import { permissionsForRole } from '@fecommunity/reactpress-toolkit/plugin/admin';
 ```
 
-### Authentication Handling
-```typescript
-import { http, api, utils } from '@fecommunity/reactpress-toolkit';
-
-// Automatic token refresh
-const secureApi = http.createApiInstance({
-  baseURL: 'https://api.yourdomain.com',
-  auth: {
-    tokenRefresh: async (refreshToken) => {
-      const response = await api.auth.refresh({ refreshToken });
-      return response.data.accessToken;
-    }
-  }
-});
-```
-
-## Type Definitions
-
-All data models are strongly typed and available through the `types` export:
+### Web / Electron 客户端
 
 ```typescript
-import { types } from '@fecommunity/reactpress-toolkit';
-
-const user: types.IUser = {
-  name: 'John Doe',
-  email: 'john@example.com',
-  // ... other properties
-};
+import { createClient, resolveApiBaseUrl } from '@fecommunity/reactpress-toolkit/plugin/client';
 ```
 
-Available type definitions include:
-- `types.IUser`
-- `types.IArticle`
-- `types.ICategory`
-- `types.ITag`
-- `types.IComment`
-- `types.IFile`
-- `types.ISetting`
-- `types.IPage`
-- `types.IKnowledge`
-- `types.IView`
-- `types.I_SMTP`
+## App 工厂（`./app`）
 
-## Utility Functions
+主题 `_app.tsx` 的入口工厂，与 UI 框架无关：
 
-The toolkit includes helpful utility functions:
+| 工厂 | 用途 |
+|------|------|
+| `createThemeApp` | 极简主题（hello-world）：`ReactPressProvider` + `ThemeCssVars` |
+| `createReactPressApp` | 完整主题：SSR catalog、i18n、统计、PV；通过 `wrapContent` 注入 Ant Design 等 |
 
 ```typescript
-import { utils } from '@fecommunity/reactpress-toolkit';
-
-// Date formatting
-const formattedDate = utils.formatDate(new Date(), 'YYYY-MM-DD');
+import { createThemeApp } from '@fecommunity/reactpress-toolkit/app';
+import { createReactPressApp } from '@fecommunity/reactpress-toolkit/app';
+```
 
-// Deep cloning
-const clonedObject = utils.deepClone(originalObject);
+也可从 `./theme`  re-export 导入（兼容旧路径）。
 
-// Error handling
-if (utils.ApiError.isInstance(error)) {
-  console.log(`API Error: ${error.code} - ${error.message}`);
-}
+## 主题开发（`./theme`）
 
-// Data validation
-const isValidEmail = utils.validateEmail('user@example.com');
+Next.js 访客主题应使用 toolkit 提供的 API 与 SSR 辅助，避免在每个主题里复制 `lib/api.ts`。
 
-// String manipulation
-const slug = utils.createSlug('My Article Title');
+```typescript
+import {
+  themeApi,
+  fetchVisitorContext,
+  fetchThemeCatalog,
+  themeStaticProps,
+  unpackList,
+} from '@fecommunity/reactpress-toolkit/theme';
+import { createThemeApp } from '@fecommunity/reactpress-toolkit/app';
 ```
 
-## Development
-
-### Generating API Definitions
+```javascript
+// next.config.js
+const { createReactPressNextConfig } = require('@fecommunity/reactpress-toolkit/theme/next-config');
+module.exports = createReactPressNextConfig();
+```
 
-The toolkit is automatically generated from the ReactPress backend's OpenAPI specification:
+```typescript
+// pages/_app.tsx
+import themeManifest from '../theme.json';
 
-```bash
-npm run generate
+export default createThemeApp(themeManifest);
 ```
 
-This command will:
-1. Generate a new Swagger JSON from the ReactPress server
-2. Create TypeScript definitions from the specification
-3. Organize the generated files into appropriate directories
-4. Create API clients for each module
+**完整功能主题** — 使用 `createReactPressApp`（UI 框架无关），Ant Design 等重型依赖留在主题内：
 
-### Building
-
-```bash
-npm run build
+```typescript
+import { createReactPressApp } from '@fecommunity/reactpress-toolkit/app';
+import { ConfigProvider } from 'antd';
+import { NextIntlProvider } from 'next-intl';
+
+export default createReactPressApp(themeManifest, {
+  Layout: AppLayout,
+  IntlProvider: NextIntlProvider,
+  wrapContent: (content, { locale, isDark, colorPrimary }) => (
+    <ConfigProvider locale={{ locale }} theme={{ token: { colorPrimary } }}>
+      {content}
+    </ConfigProvider>
+  ),
+});
 ```
 
-This will compile the TypeScript code to JavaScript in the `dist` directory.
+`createReactPressApp` 内置：SSR 站点数据、预览 mods、SiteCatalogProvider、路由进度条、统计脚本、PV 上报。**不含** Ant Design / cssinjs。
 
-## Testing
+**REST Provider** — 无需在每个主题复制 14 个 Provider 文件：
 
-```bash
-# Run unit tests
-npm run test
+```typescript
+import { createThemeAxiosClient, createThemeProviders } from '@fecommunity/reactpress-toolkit/theme';
 
-# Run tests with coverage
-npm run test:cov
+export const httpProvider = createThemeAxiosClient({ onError, onUnauthorized });
+export const { ArticleProvider, CategoryProvider, TagProvider } = createThemeProviders(httpProvider);
+```
 
-# Run linting
-npm run lint
+环境变量：`REACTPRESS_API_URL`（SSR）、`NEXT_PUBLIC_REACTPRESS_API_URL`（浏览器），由 `reactpress theme dev` 注入。
 
-# Run formatting
-npm run format
-```
+### 无样式 UI（`./ui`）
 
-## Integration Examples
+也可从 `./theme` 一并导入：
 
-### React Integration
 ```typescript
-import { useState, useEffect } from 'react';
-import { api, types } from '@fecommunity/reactpress-toolkit';
-
-const ArticleList = () => {
-  const [articles, setArticles] = useState<types.IArticle[]>([]);
-  const [loading, setLoading] = useState(true);
-
-  useEffect(() => {
-    const fetchArticles = async () => {
-      try {
-        const response = await api.article.findAll();
-        setArticles(response.data);
-      } catch (error) {
-        console.error('Failed to fetch articles:', error);
-      } finally {
-        setLoading(false);
-      }
-    };
-
-    fetchArticles();
-  }, []);
-
-  if (loading) return <div>Loading...</div>;
-  
-  return (
-    <div>
-      {articles.map(article => (
-        <div key={article.id}>
-          <h2>{article.title}</h2>
-          <p>{article.content}</p>
-        </div>
-      ))}
-    </div>
-  );
-};
+import { NavMenu, ArticleList, ReactPressProvider, useLocale } from '@fecommunity/reactpress-toolkit/ui';
 ```
 
-### Node.js Integration
+| 符号 | 说明 |
+|------|------|
+| `ReactPressProvider` | 在 `_app` 注入站点上下文 |
+| `useLocale` / `useThemeRuntime` / `useThemeMod` | 语言与主题 mods |
+| `useToggle` / `useAsyncLoading` | 布尔切换、防抖 loading（评论/搜索等） |
+| `usePagination` | `[items, total]` 分页列表 |
+| `useReportArticleView` / `useReportPageView` | 文章阅读数、全站 PV 上报 |
+| `useRouteParam` / `useNavActive` | 动态路由参数、导航高亮 |
+| `useWarningOnExit` | 离开页面前确认（Next Router） |
+| `NavMenu` | 配置驱动导航，通过 `renderLink` 接 Next `Link` |
+| `ArticleList` | 列表渲染，通过 `renderArticle` 自定义卡片 |
+| `SiteCatalogProvider` / `useSiteSetting` / `useSiteUser` | 全站 catalog + 用户会话 |
+| `SiteSeo` / `RouteProgress` / `SiteAnalytics` | SEO meta、路由进度条、GA/百度统计 |
+| `ArticleReader` / `HtmlContent` / `ArticleToc` | 文章阅读、HTML 渲染、目录 |
+| `ImageViewer` / `LocaleTime` | 图片预览、本地化时间 |
+| `createReactPressApp` | 完整主题 `_app` 工厂（`@fecommunity/reactpress-toolkit/app`） |
+| `fetchAppBootstrap` | `_app.getInitialProps` SSR 数据（setting / taxonomy / preview） |
+
+### 扩展配置类型
+
+`theme/extension` 中的类型与校验逻辑与 **server**、**web 外观设置** 共用，例如 `ThemeConfigurationSchema`、`resolveSiteConfig`、`PUBLIC_SETTING_KEYS`。服务端可：
+
 ```typescript
-import { api, types } from '@fecommunity/reactpress-toolkit';
-
-async function syncArticles() {
-  try {
-    // Fetch articles from ReactPress
-    const response = await api.article.findAll({
-      limit: 100,
-      offset: 0
-    });
-    
-    // Process articles
-    const articles: types.IArticle[] = response.data;
-    
-    // Sync with another system
-    for (const article of articles) {
-      // Your sync logic here
-      console.log(`Synced article: ${article.title}`);
-    }
-  } catch (error) {
-    console.error('Sync failed:', error);
-  }
-}
-
-syncArticles();
+import { PUBLIC_SETTING_KEYS, systemGlobalSettingDefaults } from '@fecommunity/reactpress-toolkit/theme';
+import { readThemeAdminLocaleFile } from '@fecommunity/reactpress-toolkit/theme/node';
 ```
 
-## Best Practices
+## 从 Swagger 重新生成 API
 
-### Error Handling
-```typescript
-import { api, utils } from '@fecommunity/reactpress-toolkit';
-
-try {
-  const articles = await api.article.findAll();
-  // Process articles
-} catch (error) {
-  if (utils.ApiError.isInstance(error)) {
-    switch (error.code) {
-      case 401:
-        // Handle unauthorized access
-        redirectToLogin();
-        break;
-      case 403:
-        // Handle forbidden access
-        showPermissionError();
-        break;
-      case 500:
-        // Handle server errors
-        showServerError();
-        break;
-      default:
-        // Handle other API errors
-        showGenericError(error.message);
-    }
-  } else {
-    // Handle network errors
-    showNetworkError();
-  }
-}
+在 monorepo 根目录确保 server 可构建后：
+
+```bash
+cd toolkit && pnpm run generate
 ```
 
-### Pagination
-```typescript
-import { api, types } from '@fecommunity/reactpress-toolkit';
-
-async function fetchAllArticles(): Promise<types.IArticle[]> {
-  const allArticles: types.IArticle[] = [];
-  let offset = 0;
-  const limit = 50;
-  
-  while (true) {
-    const response = await api.article.findAll({ limit, offset });
-    allArticles.push(...response.data);
-    
-    if (response.data.length < limit) {
-      // No more articles to fetch
-      break;
-    }
-    
-    offset += limit;
-  }
-  
-  return allArticles;
-}
+将更新 `src/api/*` 与 `src/types/*`。
+
+## 构建
+
+```bash
+cd toolkit && pnpm run build
 ```
 
-## Contributing
+输出到 `dist/`；`createApp.js` 随 `tsc`（`allowJs`）写入 `dist/theme/createApp.js`。
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
-3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
-4. Push to the branch (`git push origin feature/AmazingFeature`)
-5. Open a pull request
+## 开发脚本
+
+| 命令 | 说明 |
+|------|------|
+| `pnpm run generate` | 从 server Swagger 生成 API |
+| `pnpm run build` | `tsc` + 复制 locales |
+| `pnpm run typecheck` | 仅类型检查 |
 
 ## License
 
 ISC
-
-## Related Projects
-
-- [ReactPress](https://github.com/fecommunity/reactpress) - The main ReactPress platform
-- [ReactPress Server](https://github.com/fecommunity/reactpress/server) - Backend server
-- [ReactPress Client](https://github.com/fecommunity/reactpress/client) - Frontend client

package/dist/admin/index.d.ts

@@ -0,0 +1,2 @@
+export * from './permissions';
+export * from './registry';

package/dist/admin/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./permissions"), exports);
+__exportStar(require("./registry"), exports);

package/dist/admin/permissions.d.ts

@@ -0,0 +1,5 @@
+/** Admin capability strings — keep in sync with server guards. */
+export type Permission = 'article:read' | 'article:write' | 'article:publish' | 'media:manage' | 'page:manage' | 'user:manage' | 'setting:manage' | 'extension:manage' | 'comment:manage' | 'view:read';
+export declare const ADMIN_PERMISSIONS: Permission[];
+/** Map legacy server roles to capability strings. */
+export declare function permissionsForRole(role: string | undefined): Permission[];

package/dist/admin/permissions.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADMIN_PERMISSIONS = void 0;
+exports.permissionsForRole = permissionsForRole;
+exports.ADMIN_PERMISSIONS = [
+    'article:read',
+    'article:write',
+    'article:publish',
+    'media:manage',
+    'page:manage',
+    'user:manage',
+    'setting:manage',
+    'extension:manage',
+    'comment:manage',
+    'view:read',
+];
+/** Map legacy server roles to capability strings. */
+function permissionsForRole(role) {
+    if (role === 'admin')
+        return [...exports.ADMIN_PERMISSIONS];
+    if (role === 'editor') {
+        return [
+            'article:read',
+            'article:write',
+            'article:publish',
+            'media:manage',
+            'page:manage',
+            'comment:manage',
+            'view:read',
+        ];
+    }
+    return ['article:read', 'view:read'];
+}