Axios API Wrapper

A powerful TypeScript axios wrapper that eliminates repetitive API call patterns, provides centralized error handling, and simplifies authentication management.

🚀 Features

• Zero Overhead: No performance impact on your API calls
• Centralized Error Handling: Handle errors globally or per request
• Automatic Authentication: Built-in auth token management
• Type Safety: Full TypeScript support with generics
• Service Pattern: Organized API calls with base service class
• Multiple Clients: Support for different backend services
• Custom Interceptors: Request/response interceptors support
• CLI Tool: Generate boilerplate code quickly

📦 Installation

npm install axios-api-wrapper-cli
# or
yarn add axios-api-wrapper-cli

🛠️ CLI Usage

Initialize a new project

npx better-axios init
# or
npx better-axios init --name my-project --examples --framework react

Generate service files

# Generate a new service
npx better-axios generate service --name user --path /users

# Generate a new API client
npx better-axios generate client --name payment

# Generate configuration file
npx better-axios generate config

💻 Quick Start

1. Basic Setup

import { AxiosApi } from 'axios-api-wrapper-cli';

const apiClient = new AxiosApi({
  baseURL: 'https://api.example.com',
  globalErrorHandler: (error) => {
    console.error('API Error:', error.message);
    // Show toast notification, etc.
  }
});

2. Create a Service

import { ApiService } from 'axios-api-wrapper-cli';

interface User {
  id: number;
  name: string;
  email: string;
}

class UserService extends ApiService {
  constructor(api: AxiosApi) {
    super(api, '/users');
  }

  async getAllUsers(): Promise<ApiResponse<User[]>> {
    return this.get<User[]>('');
  }

  async getUserById(id: number): Promise<ApiResponse<User>> {
    return this.get<User>(`/${id}`);
  }

  async createUser(userData: Partial<User>): Promise<ApiResponse<User>> {
    return this.post<User>('', userData);
  }
}

const userService = new UserService(apiClient);

3. Use in Your Application

// Simple usage
async function loadUsers() {
  try {
    const response = await userService.getAllUsers();
    if (response.success) {
      return response.data; // User[]
    }
  } catch (error) {
    // Error already handled by global handler
    return [];
  }
}

// With authentication
apiClient.setAuthToken('your-jwt-token');
await userService.createUser({ name: 'John', email: '[email protected]' });

🔧 Configuration Options

const apiClient = new AxiosApi({
  baseURL: 'https://api.example.com',
  timeout: 15000,
  defaultHeaders: {
    'Content-Type': 'application/json',
  },
  authTokenKey: 'Authorization', // Header key for auth token
  authTokenPrefix: 'Bearer ', // Token prefix
  globalErrorHandler: (error: ApiError) => {
    // Handle all errors globally
    switch (error.statusCode) {
      case 401:
        // Redirect to login
        break;
      case 403:
        // Show permission error
        break;
      default:
        // Show generic error
    }
  },
  globalSuccessHandler: (response: ApiResponse) => {
    // Optional global success handling
    console.log('Request successful');
  },
  requestInterceptor: (config) => {
    // Modify requests before sending
    config.headers['X-Custom-Header'] = 'value';
    return config;
  },
  responseInterceptor: (response) => {
    // Process responses before handling
    return response;
  }
});

🔐 Authentication

// Set auth token (automatically added to all requests)
apiClient.setAuthToken('your-jwt-token');

// Remove auth token
apiClient.removeAuthToken();

// Skip auth for specific requests
await apiClient.get('/public-endpoint', { useAuth: false });

🎯 Advanced Usage

Custom Error Handling per Request

await userService.deleteUser(123, {
  customErrorHandler: (error) => {
    if (error.statusCode === 403) {
      alert('Permission denied');
    } else {
      alert('Delete failed');
    }
  },
  customSuccessHandler: () => {
    alert('User deleted successfully');
  }
});

Multiple API Clients

const mainApiClient = new AxiosApi({
  baseURL: 'https://api.example.com',
  globalErrorHandler: handleMainApiError
});

const paymentApiClient = new AxiosApi({
  baseURL: 'https://payments.example.com',
  globalErrorHandler: handlePaymentApiError
});

const userService = new UserService(mainApiClient);
const paymentService = new PaymentService(paymentApiClient);

Direct API Calls

// Without services
const response = await apiClient.get<User[]>('/users');
const newUser = await apiClient.post<User>('/users', userData);
const updatedUser = await apiClient.put<User>(`/users/${id}`, updateData);
await apiClient.delete(`/users/${id}`);

📚 API Reference

AxiosApi Class

Constructor Options

• baseURL: Base URL for all requests
• timeout: Request timeout in milliseconds
• defaultHeaders: Default headers for all requests
• authTokenKey: Header key for authentication token
• authTokenPrefix: Prefix for authentication token
• globalErrorHandler: Global error handling function
• globalSuccessHandler: Global success handling function
• requestInterceptor: Custom request interceptor
• responseInterceptor: Custom response interceptor

Methods

• get<T>(url, config?): GET request
• post<T>(url, data?, config?): POST request
• put<T>(url, data?, config?): PUT request
• patch<T>(url, data?, config?): PATCH request
• delete<T>(url, config?): DELETE request
• setAuthToken(token): Set authentication token
• removeAuthToken(): Remove authentication token
• setDefaultHeader(key, value): Set default header
• removeDefaultHeader(key): Remove default header

ApiService Class

Base class for creating organized API services.

Constructor

constructor(api: AxiosApi, basePath: string)

Protected Methods

• get<T>(endpoint, config?): GET request relative to basePath
• post<T>(endpoint, data?, config?): POST request relative to basePath
• put<T>(endpoint, data?, config?): PUT request relative to basePath
• patch<T>(endpoint, data?, config?): PATCH request relative to basePath
• delete<T>(endpoint, config?): DELETE request relative to basePath
• buildUrl(endpoint): Build full URL from endpoint

Request Configuration

interface RequestConfig {
  useAuth?: boolean; // Include auth token (default: true)
  customErrorHandler?: (error: ApiError) => void;
  customSuccessHandler?: (response: ApiResponse) => void;
  skipGlobalHandlers?: boolean; // Skip global handlers
  // ... other axios config options
}

Response Types

interface ApiResponse<T = any> {
  data: T;
  success: boolean;
  message?: string;
  statusCode: number;
}

interface ApiError {
  message: string;
  statusCode: number;
  originalError: any;
}

🔍 Examples

Check out the /examples directory in your generated project for complete usage examples including:

• React integration
• Vue integration
• Node.js server usage
• Authentication flows
• Error handling patterns
• Multiple API clients

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙋‍♂️ Support

If you have any questions or need help, please:

1. Check the documentation
2. Open an issue
3. Start a discussion

Made with ❤️ by [Your Name]