@fecommunity/reactpress-toolkit Usage Guide

ReactPress Toolkit is a TypeScript-based API client toolkit automatically generated from OpenAPI/Swagger specifications for interacting with ReactPress backend services.

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.

Installation

npm install @fecommunity/reactpress-toolkit

or

yarn add @fecommunity/reactpress-toolkit

or

pnpm add @fecommunity/reactpress-toolkit

Quick Start

Using the Default API Instance

import { api } from '@fecommunity/reactpress-toolkit';

// 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

import { api, types, utils } from '@fecommunity/reactpress-toolkit';

// Working with typed data
const article: types.IArticle = {
  id: '1',
  title: 'Sample Article',
  // ... other properties
};

// Using utility functions
const formattedDate = utils.formatDate(new Date());

Configuration

You can create a custom API instance with specific configuration:

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();

Enterprise Features

Automatic Retry Mechanisms

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

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;
    }
  }
});

Authentication Handling

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:

import { types } from '@fecommunity/reactpress-toolkit';

const user: types.IUser = {
  name: 'John Doe',
  email: 'john@example.com',
  // ... other properties
};

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

Utility Functions

The toolkit includes helpful utility functions:

import { utils } from '@fecommunity/reactpress-toolkit';

// Date formatting
const formattedDate = utils.formatDate(new Date(), 'YYYY-MM-DD');

// Deep cloning
const clonedObject = utils.deepClone(originalObject);

// Error handling
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');

Integration Examples

React Integration

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

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

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

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;
}