@zym-test-zerog/apiclient 1.0.0

package/README.md

@@ -0,0 +1,576 @@
+# API Client Wrapper
+
+A powerful and feature-rich API client wrapper for TypeScript/JavaScript applications with built-in token refresh, request signing, comprehensive error handling, and detailed logging.
+
+## Features
+
+- **Modular API Organization**: Organized by API versions (v1, v2) and functionality
+- **Automatic Token Refresh**: Handles 401 errors and automatically refreshes tokens
+- **Request Signing**: Built-in support for request signature generation
+- **Comprehensive Error Handling**: Global error interceptor with custom error handling support
+- **Detailed Logging**: Request/response logging with sensitive data redaction
+- **Request Cancellation**: Support for cancelling individual or all requests
+- **TypeScript Support**: Full type definitions for better development experience
+- **Dual Module Support**: Works with both CommonJS and ES Module
+
+## Installation
+
+```bash
+npm install api-client-wrapper
+```
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { init, apiV1 } from 'api-client-wrapper';
+
+init({
+  baseURL: 'https://api.example.com',
+  timeout: 10000,
+  debug: true
+});
+
+async function main() {
+  try {
+    const userInfo = await apiV1.getUserInfo();
+    console.log(userInfo);
+  } catch (error) {
+    console.error(error);
+  }
+}
+```
+
+### Login Example
+
+```typescript
+import { init, apiV1 } from 'api-client-wrapper';
+
+init();
+
+async function login() {
+  try {
+    const result = await apiV1.login({
+      username: 'testuser',
+      password: 'password123'
+    });
+    console.log('Login successful:', result);
+  } catch (error) {
+    console.error('Login failed:', error);
+  }
+}
+```
+
+## Configuration
+
+### Initialization Options
+
+```typescript
+interface ApiClientConfig {
+  baseURL?: string;              // Default: 'https://www.xxx.com/api'
+  timeout?: number;              // Default: 30000 (30s)
+  headers?: Record<string, string>;
+  debug?: boolean;               // Default: false
+  logLevel?: 'error' | 'warn' | 'info' | 'debug';
+  logCallback?: LogCallback;
+  tokenRefreshConfig?: TokenRefreshConfig;
+  signConfig?: SignConfig;
+  errorHandler?: ErrorHandler;
+}
+```
+
+### Token Refresh Configuration
+
+```typescript
+import { init } from 'api-client-wrapper';
+
+let accessToken = '';
+let refreshToken = '';
+
+init({
+  tokenRefreshConfig: {
+    refreshTokenUrl: '/auth/refresh',
+    getToken: () => accessToken,
+    setToken: (token) => { accessToken = token; },
+    getRefreshToken: () => refreshToken,
+    tokenExpiredCode: 401
+  }
+});
+```
+
+### Request Signing Configuration
+
+```typescript
+import { init } from 'api-client-wrapper';
+
+init({
+  signConfig: {
+    secretKey: 'your-secret-key',
+    algorithm: 'md5',           // 'md5' | 'sha1' | 'sha256'
+    signHeaderName: 'X-Sign',
+    includeParams: true,
+    includeHeaders: false
+  }
+});
+```
+
+### Custom Error Handler
+
+```typescript
+import { init } from 'api-client-wrapper';
+
+init({
+  errorHandler: (error) => {
+    console.error('Error:', error.name, error.message);
+    
+    if (error.name === 'NetworkError') {
+      // Handle network errors
+    } else if (error.name === 'UnauthorizedError') {
+      // Redirect to login
+    }
+  }
+});
+```
+
+### Custom Log Callback
+
+```typescript
+import { init } from 'api-client-wrapper';
+
+const logs: any[] = [];
+
+init({
+  debug: true,
+  logLevel: 'debug',
+  logCallback: (level, message, data) => {
+    logs.push({ level, message, data, timestamp: Date.now() });
+    // Send logs to external service
+  }
+});
+```
+
+## API Reference
+
+### Core Methods
+
+#### `init(config: ApiClientConfig): void`
+
+Initialize the API client with configuration options.
+
+#### `updateConfig(config: Partial<ApiClientConfig>): void`
+
+Update the configuration after initialization.
+
+#### `getApiClient(): ApiClient`
+
+Get the underlying ApiClient instance for advanced usage.
+
+#### `destroy(): void`
+
+Destroy the API client instance and cancel all pending requests.
+
+### API v1
+
+#### Authentication
+
+```typescript
+import { apiV1 } from 'api-client-wrapper';
+
+// Login
+await apiV1.login({
+  username: string,
+  password: string
+});
+
+// Register
+await apiV1.register({
+  username: string,
+  password: string,
+  email: string
+});
+
+// Logout
+await apiV1.logout();
+
+// Get user info
+await apiV1.getUserInfo();
+
+// Update user info
+await apiV1.updateUserInfo({
+  username?: string,
+  email?: string,
+  avatar?: string
+});
+```
+
+#### User Management
+
+```typescript
+// Get user list
+await apiV1.getUserList({
+  page: number,
+  pageSize: number,
+  keyword?: string,
+  status?: 'active' | 'inactive' | 'banned'
+});
+
+// Get user by ID
+await apiV1.getUserById(userId: string);
+
+// Create user
+await apiV1.createUser({
+  username: string,
+  email: string,
+  password: string,
+  role?: string
+});
+
+// Update user
+await apiV1.updateUser(userId: string, {
+  username?: string,
+  email?: string,
+  avatar?: string,
+  status?: 'active' | 'inactive' | 'banned'
+});
+
+// Delete user
+await apiV1.deleteUser(userId: string);
+
+// Batch delete users
+await apiV1.batchDeleteUsers(userIds: string[]);
+```
+
+#### Product Management
+
+```typescript
+// Get product list
+await apiV1.getProductList({
+  page: number,
+  pageSize: number,
+  keyword?: string,
+  category?: string,
+  status?: 'available' | 'out_of_stock' | 'discontinued',
+  minPrice?: number,
+  maxPrice?: number
+});
+
+// Get product by ID
+await apiV1.getProductById(productId: string);
+
+// Create product
+await apiV1.createProduct({
+  name: string,
+  description: string,
+  price: number,
+  stock: number,
+  category: string,
+  images: string[]
+});
+
+// Update product
+await apiV1.updateProduct(productId: string, {
+  name?: string,
+  description?: string,
+  price?: number,
+  stock?: number,
+  category?: string,
+  images?: string[],
+  status?: 'available' | 'out_of_stock' | 'discontinued'
+});
+
+// Delete product
+await apiV1.deleteProduct(productId: string);
+
+// Update product stock
+await apiV1.updateProductStock(productId: string, stock: number);
+```
+
+### API v2
+
+#### Authentication
+
+```typescript
+import { apiV2 } from 'api-client-wrapper';
+
+// Login (V2)
+await apiV2.loginV2({
+  account: string,
+  password: string,
+  captcha?: string,
+  deviceId?: string
+});
+
+// Register (V2)
+await apiV2.registerV2({
+  account: string,
+  password: string,
+  confirmPassword: string,
+  email: string,
+  phone?: string,
+  captcha: string
+});
+
+// Logout (V2)
+await apiV2.logoutV2();
+
+// Get user info (V2)
+await apiV2.getUserInfoV2();
+
+// Update user info (V2)
+await apiV2.updateUserInfoV2({
+  nickname?: string,
+  avatar?: string,
+  email?: string,
+  phone?: string,
+  gender?: 'male' | 'female' | 'other',
+  birthday?: string,
+  bio?: string
+});
+
+// Change password
+await apiV2.changePasswordV2({
+  oldPassword: string,
+  newPassword: string,
+  confirmPassword: string
+});
+
+// Upload avatar
+await apiV2.uploadAvatarV2(file: File);
+```
+
+#### User Management (V2)
+
+```typescript
+// Get user list (V2)
+await apiV2.getUserListV2({
+  page: number,
+  pageSize: number,
+  keyword?: string,
+  status?: 'active' | 'inactive' | 'banned' | 'pending',
+  role?: string,
+  sortBy?: 'createdAt' | 'updatedAt' | 'lastLoginAt',
+  sortOrder?: 'asc' | 'desc'
+});
+
+// Create user (V2)
+await apiV2.createUserV2({
+  account: string,
+  password: string,
+  nickname: string,
+  email: string,
+  phone?: string,
+  roles: string[]
+});
+
+// Update user (V2)
+await apiV2.updateUserV2(userId: string, {
+  nickname?: string,
+  avatar?: string,
+  email?: string,
+  phone?: string,
+  gender?: 'male' | 'female' | 'other',
+  birthday?: string,
+  bio?: string,
+  status?: 'active' | 'inactive' | 'banned' | 'pending',
+  roles?: string[]
+});
+
+// Assign roles
+await apiV2.assignRolesV2(userId: string, roles: string[]);
+
+// Reset password
+await apiV2.resetPasswordV2(userId: string, newPassword: string);
+
+// Ban user
+await apiV2.banUserV2(userId: string, reason?: string);
+
+// Unban user
+await apiV2.unbanUserV2(userId: string);
+```
+
+#### Product Management (V2)
+
+```typescript
+// Get product list (V2)
+await apiV2.getProductListV2({
+  page: number,
+  pageSize: number,
+  keyword?: string,
+  category?: string,
+  subcategory?: string,
+  tags?: string[],
+  status?: 'draft' | 'published' | 'out_of_stock' | 'discontinued',
+  visibility?: 'public' | 'private' | 'hidden',
+  featured?: boolean,
+  minPrice?: number,
+  maxPrice?: number,
+  inStock?: boolean,
+  sortBy?: 'createdAt' | 'updatedAt' | 'price' | 'name' | 'stock',
+  sortOrder?: 'asc' | 'desc'
+});
+
+// Get product by slug
+await apiV2.getProductBySlugV2(slug: string);
+
+// Create product (V2)
+await apiV2.createProductV2({
+  name: string,
+  slug?: string,
+  description: string,
+  shortDescription?: string,
+  price: number,
+  compareAtPrice?: number,
+  costPrice?: number,
+  stock: number,
+  lowStockThreshold?: number,
+  category: string,
+  subcategory?: string,
+  tags?: string[],
+  images: Array<{
+    url: string;
+    alt?: string;
+    order?: number;
+  }>,
+  variants?: Array<{
+    name: string;
+    sku: string;
+    price: number;
+    stock: number;
+    attributes: Record<string, string>;
+  }>,
+  attributes?: Record<string, string>,
+  seoTitle?: string,
+  seoDescription?: string,
+  seoKeywords?: string[],
+  status?: 'draft' | 'published' | 'out_of_stock' | 'discontinued',
+  visibility?: 'public' | 'private' | 'hidden',
+  featured?: boolean,
+  weight?: number,
+  dimensions?: {
+    length: number;
+    width: number;
+    height: number;
+  }
+});
+
+// Publish product
+await apiV2.publishProductV2(productId: string);
+
+// Unpublish product
+await apiV2.unpublishProductV2(productId: string);
+
+// Upload product images
+await apiV2.uploadProductImagesV2(productId: string, files: File[]);
+```
+
+## Advanced Usage
+
+### Request Cancellation
+
+```typescript
+import { getApiClient } from 'api-client-wrapper';
+
+const client = getApiClient();
+const source = client.createCancelToken('request-id');
+
+client.cancelRequest('request-id');
+client.cancelAllRequests();
+```
+
+### Dynamic Configuration Update
+
+```typescript
+import { init, updateConfig } from 'api-client-wrapper';
+
+init({
+  baseURL: 'https://api.example.com',
+  debug: false
+});
+
+updateConfig({
+  debug: true,
+  logLevel: 'info',
+  timeout: 15000
+});
+```
+
+## Error Handling
+
+The library provides comprehensive error handling with the following error types:
+
+- **NetworkError**: Network connectivity issues
+- **ServerError**: Server-side errors (5xx)
+- **UnauthorizedError**: Authentication failures (401)
+- **ForbiddenError**: Access denied (403)
+- **NotFoundError**: Resource not found (404)
+- **ClientError**: Client-side errors (4xx)
+- **RequestSetupError**: Request configuration errors
+
+Each error includes:
+- `name`: Error type
+- `message`: Error description
+- `code`: Error code
+- `status`: HTTP status code (if applicable)
+- `data`: Response data (if applicable)
+- `config`: Request configuration
+- `response`: Axios response object
+
+## Logging
+
+When `debug` is enabled, the library logs detailed request/response information:
+
+```
+================================================== login start ==================================================
+url: https://api.example.com/v1/auth/login
+method: POST
+headers: { 'Content-Type': 'application/json', 'Authorization': '***REDACTED***' }
+params: { username: 'test', password: '***REDACTED***' }
+timestamp: 1234567890
+================================================= login end ===================================================
+url: https://api.example.com/v1/auth/login
+method: POST
+status: 200
+statusText: OK
+data: { token: '...', refreshToken: '...' }
+timestamp: 1234567895
+duration: 5ms
+```
+
+Sensitive information (passwords, tokens, etc.) is automatically redacted.
+
+## Development
+
+### Build
+
+```bash
+npm run build
+```
+
+### Test
+
+```bash
+npm test
+npm run test:coverage
+```
+
+### Lint
+
+```bash
+npm run lint
+npm run lint:fix
+```
+
+### Type Check
+
+```bash
+npm run typecheck
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.