@fecommunity/reactpress-toolkit 1.0.0-beta.2 → 1.0.0

package/README.md

@@ -1,15 +1,23 @@
 # @fecommunity/reactpress-toolkit
 
-A TypeScript-based API client toolkit for ReactPress, automatically generated from OpenAPI/Swagger specifications.
+TypeScript-based API client toolkit for ReactPress, automatically generated from OpenAPI/Swagger specifications.
+
+[![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 a comprehensive API client library that provides strongly-typed interfaces for interacting with the ReactPress backend services. It includes:
+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
 
@@ -89,11 +97,11 @@ The toolkit provides clients for all ReactPress backend modules:
 You can create a custom API instance with specific configuration:
 
 ```typescript
-import { createApiInstance } from '@fecommunity/reactpress-toolkit';
+import { api } from '@fecommunity/reactpress-toolkit';
 
-const customApi = createApiInstance({
+const customApi = api.createApiInstance({
   baseURL: 'https://api.yourdomain.com',
-  timeout: 5000,
+  timeout: 10000,
   // ... other axios configuration options
 });
 
@@ -101,6 +109,62 @@ const customApi = createApiInstance({
 const articles = await customApi.article.findAll();
 ```
 
+## Enterprise Features
+
+### Automatic Retry Mechanisms
+```typescript
+import { api } from '@fecommunity/reactpress-toolkit';
+
+// Configure retry settings
+const customApi = api.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 { api } from '@fecommunity/reactpress-toolkit';
+
+const monitoredApi = api.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;
+    }
+  }
+});
+```
+
+### Authentication Handling
+```typescript
+import { api, utils } from '@fecommunity/reactpress-toolkit';
+
+// Automatic token refresh
+const secureApi = api.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:
@@ -145,6 +209,12 @@ const clonedObject = utils.deepClone(originalObject);
 if (utils.ApiError.isInstance(error)) {
   console.log(`API Error: ${error.code} - ${error.message}`);
 }
+
+// Data validation
+const isValidEmail = utils.validateEmail('user@example.com');
+
+// String manipulation
+const slug = utils.createSlug('My Article Title');
 ```
 
 ## Development
@@ -171,6 +241,151 @@ npm run build
 
 This will compile the TypeScript code to JavaScript in the `dist` directory.
 
+## Testing
+
+```bash
+# Run unit tests
+npm run test
+
+# Run tests with coverage
+npm run test:cov
+
+# Run linting
+npm run lint
+
+# Run formatting
+npm run format
+```
+
+## Integration Examples
+
+### 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>
+  );
+};
+```
+
+### Node.js Integration
+```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();
+```
+
+## Best Practices
+
+### 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();
+  }
+}
+```
+
+### 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;
+}
+```
+
 ## Contributing
 
 1. Fork the repository
@@ -187,4 +402,4 @@ ISC
 
 - [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
+- [ReactPress Client](https://github.com/fecommunity/reactpress/client) - Frontend client

package/dist/api/Article.d.ts

@@ -1,108 +1,123 @@
-import { IArticle } from '../types/data-contracts';
+import { IArticleControllerCreateData } from '../types';
 import { HttpClient, RequestParams } from './HttpClient';
-export declare class Article<SecurityDataType = unknown> extends HttpClient<SecurityDataType> {
+export declare class Article<SecurityDataType = unknown> {
+    http: HttpClient<SecurityDataType>;
+    constructor(http: HttpClient<SecurityDataType>);
     /**
      * No description
      *
      * @tags Article
-     * @name create
+     * @name ArticleControllerCreate
      * @request POST:/article
+     * @response `200` `IArticleControllerCreateData` 创建文章
      */
-    create: (params?: RequestParams) => Promise<import("axios").AxiosResponse<IArticle[], any, {}>>;
+    create: (params?: RequestParams) => Promise<IArticleControllerCreateData>;
     /**
      * No description
      *
      * @tags Article
-     * @name findAll
+     * @name ArticleControllerFindAll
      * @request GET:/article
+     * @response `200` `IArticleControllerFindAllData`
      */
-    findAll: (params?: RequestParams) => Promise<import("axios").AxiosResponse<void, any, {}>>;
+    findAll: (params?: RequestParams) => Promise<any>;
     /**
      * No description
      *
      * @tags Article
-     * @name findArticlesByCategory
+     * @name ArticleControllerFindArticlesByCategory
      * @request GET:/article/category/{id}
+     * @response `200` `IArticleControllerFindArticlesByCategoryData`
      */
-    findArticlesByCategory: (id: string, params?: RequestParams) => Promise<import("axios").AxiosResponse<void, any, {}>>;
+    findArticlesByCategory: (id: string, params?: RequestParams) => Promise<any>;
     /**
      * No description
      *
      * @tags Article
-     * @name findArticlesByTag
+     * @name ArticleControllerFindArticlesByTag
      * @request GET:/article/tag/{id}
+     * @response `200` `IArticleControllerFindArticlesByTagData`
      */
-    findArticlesByTag: (id: string, params?: RequestParams) => Promise<import("axios").AxiosResponse<void, any, {}>>;
+    findArticlesByTag: (id: string, params?: RequestParams) => Promise<any>;
     /**
      * No description
      *
      * @tags Article
-     * @name getRecommendArticles
+     * @name ArticleControllerGetRecommendArticles
      * @request GET:/article/all/recommend
+     * @response `200` `IArticleControllerGetRecommendArticlesData`
      */
-    getRecommendArticles: (params?: RequestParams) => Promise<import("axios").AxiosResponse<void, any, {}>>;
+    getRecommendArticles: (params?: RequestParams) => Promise<any>;
     /**
      * No description
      *
      * @tags Article
-     * @name getArchives
+     * @name ArticleControllerGetArchives
      * @request GET:/article/archives
+     * @response `200` `IArticleControllerGetArchivesData`
      */
-    getArchives: (params?: RequestParams) => Promise<import("axios").AxiosResponse<void, any, {}>>;
+    getArchives: (params?: RequestParams) => Promise<any>;
     /**
      * No description
      *
      * @tags Article
-     * @name recommend
+     * @name ArticleControllerRecommend
      * @request GET:/article/recommend
+     * @response `200` `IArticleControllerRecommendData`
      */
-    recommend: (params?: RequestParams) => Promise<import("axios").AxiosResponse<void, any, {}>>;
+    recommend: (params?: RequestParams) => Promise<any>;
     /**
      * No description
      *
      * @tags Article
-     * @name findById
+     * @name ArticleControllerFindById
      * @request GET:/article/{id}
+     * @response `200` `IArticleControllerFindByIdData`
      */
-    findById: (id: string, params?: RequestParams) => Promise<import("axios").AxiosResponse<void, any, {}>>;
+    findById: (id: string, params?: RequestParams) => Promise<any>;
     /**
      * No description
      *
      * @tags Article
-     * @name updateById
+     * @name ArticleControllerUpdateById
      * @request PATCH:/article/{id}
+     * @response `200` `IArticleControllerUpdateByIdData`
      */
-    updateById: (id: string, params?: RequestParams) => Promise<import("axios").AxiosResponse<void, any, {}>>;
+    updateById: (id: string, params?: RequestParams) => Promise<any>;
     /**
      * No description
      *
      * @tags Article
-     * @name deleteById
+     * @name ArticleControllerDeleteById
      * @request DELETE:/article/{id}
+     * @response `200` `IArticleControllerDeleteByIdData`
      */
-    deleteById: (id: string, params?: RequestParams) => Promise<import("axios").AxiosResponse<void, any, {}>>;
+    deleteById: (id: string, params?: RequestParams) => Promise<any>;
     /**
      * No description
      *
      * @tags Article
-     * @name checkPassword
+     * @name ArticleControllerCheckPassword
      * @request POST:/article/{id}/checkPassword
+     * @response `200` `IArticleControllerCheckPasswordData`
      */
-    checkPassword: (id: string, params?: RequestParams) => Promise<import("axios").AxiosResponse<void, any, {}>>;
+    checkPassword: (id: string, params?: RequestParams) => Promise<any>;
     /**
      * No description
      *
      * @tags Article
-     * @name updateViewsById
+     * @name ArticleControllerUpdateViewsById
      * @request POST:/article/{id}/views
+     * @response `200` `IArticleControllerUpdateViewsByIdData`
      */
-    updateViewsById: (id: string, params?: RequestParams) => Promise<import("axios").AxiosResponse<void, any, {}>>;
+    updateViewsById: (id: string, params?: RequestParams) => Promise<any>;
     /**
      * No description
      *
      * @tags Article
-     * @name updateLikesById
+     * @name ArticleControllerUpdateLikesById
      * @request POST:/article/{id}/likes
+     * @response `200` `IArticleControllerUpdateLikesByIdData`
      */
-    updateLikesById: (id: string, params?: RequestParams) => Promise<import("axios").AxiosResponse<void, any, {}>>;
+    updateLikesById: (id: string, params?: RequestParams) => Promise<any>;
 }

package/dist/api/Article.js

@@ -11,31 +11,30 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Article = void 0;
-const HttpClient_1 = require("./HttpClient");
-class Article extends HttpClient_1.HttpClient {
-    constructor() {
-        super(...arguments);
+class Article {
+    constructor(http) {
         /**
          * No description
          *
          * @tags Article
-         * @name create
+         * @name ArticleControllerCreate
          * @request POST:/article
+         * @response `200` `IArticleControllerCreateData` 创建文章
          */
-        this.create = (params = {}) => this.request({
+        this.create = (params = {}) => this.http.request({
             path: `/article`,
             method: 'POST',
-            format: 'json',
             ...params,
         });
         /**
          * No description
          *
          * @tags Article
-         * @name findAll
+         * @name ArticleControllerFindAll
          * @request GET:/article
+         * @response `200` `IArticleControllerFindAllData`
          */
-        this.findAll = (params = {}) => this.request({
+        this.findAll = (params = {}) => this.http.request({
             path: `/article`,
             method: 'GET',
             ...params,
@@ -44,10 +43,11 @@ class Article extends HttpClient_1.HttpClient {
          * No description
          *
          * @tags Article
-         * @name findArticlesByCategory
+         * @name ArticleControllerFindArticlesByCategory
          * @request GET:/article/category/{id}
+         * @response `200` `IArticleControllerFindArticlesByCategoryData`
          */
-        this.findArticlesByCategory = (id, params = {}) => this.request({
+        this.findArticlesByCategory = (id, params = {}) => this.http.request({
             path: `/article/category/${id}`,
             method: 'GET',
             ...params,
@@ -56,10 +56,11 @@ class Article extends HttpClient_1.HttpClient {
          * No description
          *
          * @tags Article
-         * @name findArticlesByTag
+         * @name ArticleControllerFindArticlesByTag
          * @request GET:/article/tag/{id}
+         * @response `200` `IArticleControllerFindArticlesByTagData`
          */
-        this.findArticlesByTag = (id, params = {}) => this.request({
+        this.findArticlesByTag = (id, params = {}) => this.http.request({
             path: `/article/tag/${id}`,
             method: 'GET',
             ...params,
@@ -68,10 +69,11 @@ class Article extends HttpClient_1.HttpClient {
          * No description
          *
          * @tags Article
-         * @name getRecommendArticles
+         * @name ArticleControllerGetRecommendArticles
          * @request GET:/article/all/recommend
+         * @response `200` `IArticleControllerGetRecommendArticlesData`
          */
-        this.getRecommendArticles = (params = {}) => this.request({
+        this.getRecommendArticles = (params = {}) => this.http.request({
             path: `/article/all/recommend`,
             method: 'GET',
             ...params,
@@ -80,10 +82,11 @@ class Article extends HttpClient_1.HttpClient {
          * No description
          *
          * @tags Article
-         * @name getArchives
+         * @name ArticleControllerGetArchives
          * @request GET:/article/archives
+         * @response `200` `IArticleControllerGetArchivesData`
          */
-        this.getArchives = (params = {}) => this.request({
+        this.getArchives = (params = {}) => this.http.request({
             path: `/article/archives`,
             method: 'GET',
             ...params,
@@ -92,10 +95,11 @@ class Article extends HttpClient_1.HttpClient {
          * No description
          *
          * @tags Article
-         * @name recommend
+         * @name ArticleControllerRecommend
          * @request GET:/article/recommend
+         * @response `200` `IArticleControllerRecommendData`
          */
-        this.recommend = (params = {}) => this.request({
+        this.recommend = (params = {}) => this.http.request({
             path: `/article/recommend`,
             method: 'GET',
             ...params,
@@ -104,10 +108,11 @@ class Article extends HttpClient_1.HttpClient {
          * No description
          *
          * @tags Article
-         * @name findById
+         * @name ArticleControllerFindById
          * @request GET:/article/{id}
+         * @response `200` `IArticleControllerFindByIdData`
          */
-        this.findById = (id, params = {}) => this.request({
+        this.findById = (id, params = {}) => this.http.request({
             path: `/article/${id}`,
             method: 'GET',
             ...params,
@@ -116,10 +121,11 @@ class Article extends HttpClient_1.HttpClient {
          * No description
          *
          * @tags Article
-         * @name updateById
+         * @name ArticleControllerUpdateById
          * @request PATCH:/article/{id}
+         * @response `200` `IArticleControllerUpdateByIdData`
          */
-        this.updateById = (id, params = {}) => this.request({
+        this.updateById = (id, params = {}) => this.http.request({
             path: `/article/${id}`,
             method: 'PATCH',
             ...params,
@@ -128,10 +134,11 @@ class Article extends HttpClient_1.HttpClient {
          * No description
          *
          * @tags Article
-         * @name deleteById
+         * @name ArticleControllerDeleteById
          * @request DELETE:/article/{id}
+         * @response `200` `IArticleControllerDeleteByIdData`
          */
-        this.deleteById = (id, params = {}) => this.request({
+        this.deleteById = (id, params = {}) => this.http.request({
             path: `/article/${id}`,
             method: 'DELETE',
             ...params,
@@ -140,10 +147,11 @@ class Article extends HttpClient_1.HttpClient {
          * No description
          *
          * @tags Article
-         * @name checkPassword
+         * @name ArticleControllerCheckPassword
          * @request POST:/article/{id}/checkPassword
+         * @response `200` `IArticleControllerCheckPasswordData`
          */
-        this.checkPassword = (id, params = {}) => this.request({
+        this.checkPassword = (id, params = {}) => this.http.request({
             path: `/article/${id}/checkPassword`,
             method: 'POST',
             ...params,
@@ -152,10 +160,11 @@ class Article extends HttpClient_1.HttpClient {
          * No description
          *
          * @tags Article
-         * @name updateViewsById
+         * @name ArticleControllerUpdateViewsById
          * @request POST:/article/{id}/views
+         * @response `200` `IArticleControllerUpdateViewsByIdData`
          */
-        this.updateViewsById = (id, params = {}) => this.request({
+        this.updateViewsById = (id, params = {}) => this.http.request({
             path: `/article/${id}/views`,
             method: 'POST',
             ...params,
@@ -164,14 +173,16 @@ class Article extends HttpClient_1.HttpClient {
          * No description
          *
          * @tags Article
-         * @name updateLikesById
+         * @name ArticleControllerUpdateLikesById
          * @request POST:/article/{id}/likes
+         * @response `200` `IArticleControllerUpdateLikesByIdData`
          */
-        this.updateLikesById = (id, params = {}) => this.request({
+        this.updateLikesById = (id, params = {}) => this.http.request({
             path: `/article/${id}/likes`,
             method: 'POST',
             ...params,
         });
+        this.http = http;
     }
 }
 exports.Article = Article;

package/dist/api/Auth.d.ts

@@ -1,27 +1,32 @@
 import { HttpClient, RequestParams } from './HttpClient';
-export declare class Auth<SecurityDataType = unknown> extends HttpClient<SecurityDataType> {
+export declare class Auth<SecurityDataType = unknown> {
+    http: HttpClient<SecurityDataType>;
+    constructor(http: HttpClient<SecurityDataType>);
     /**
      * No description
      *
      * @tags Auth
-     * @name login
+     * @name AuthControllerLogin
      * @request POST:/auth/login
+     * @response `200` `IAuthControllerLoginData`
      */
-    login: (params?: RequestParams) => Promise<import("axios").AxiosResponse<void, any, {}>>;
+    login: (params?: RequestParams) => Promise<any>;
     /**
      * No description
      *
      * @tags Auth
-     * @name createBook
+     * @name AuthControllerCreateBook
      * @request POST:/auth/admin
+     * @response `201` `IAuthControllerCreateBookData`
      */
-    createBook: (params?: RequestParams) => Promise<import("axios").AxiosResponse<void, any, {}>>;
+    createBook: (params?: RequestParams) => Promise<any>;
     /**
      * No description
      *
      * @tags Auth
-     * @name loginWithGithub
+     * @name AuthControllerLoginWithGithub
      * @request POST:/auth/github
+     * @response `201` `IAuthControllerLoginWithGithubData`
      */
-    loginWithGithub: (params?: RequestParams) => Promise<import("axios").AxiosResponse<void, any, {}>>;
+    loginWithGithub: (params?: RequestParams) => Promise<any>;
 }