@chain1/api-client

Advanced Axios-based API client with version checking, interceptors, and comprehensive error handling for React Native applications.

Features

• ✅ Automatic version headers in all requests
• ✅ Built-in version checking with Supabase
• ✅ Version blocking with user-friendly alerts
• ✅ Request/Response interceptors
• ✅ TypeScript support
• ✅ Configurable timeouts and headers
• ✅ RESTful methods (GET, POST, PUT, DELETE, PATCH)

Installation

npm install @chain1/api-client

Peer Dependencies

npm install axios react-native-device-info

Usage

Basic Setup

import ApiClient from '@chain1/api-client';

const apiClient = new ApiClient({
  baseURL: 'https://api.example.com',
  timeout: 30000,
  headers: {
    'Content-Type': 'application/json',
  },
});

With Version Checking

import ApiClient from '@chain1/api-client';

const apiClient = new ApiClient({
  baseURL: 'https://api.example.com',
  enableVersionCheck: true,
  versionCheckConfig: {
    supabaseUrl: 'https://your-project.supabase.co',
    supabaseAnonKey: 'your-anon-key',
    appName: 'MyApp',
    downloadUrl: 'https://example.com/download',
  },
});

// Check version manually
try {
  const result = await apiClient.checkVersion();
  if (result.is_blocked) {
    console.log('App version is blocked!');
  }
  if (result.requires_update) {
    console.log('Update available:', result.latest_version);
  }
} catch (error) {
  console.error('Version check failed:', error);
}

Making API Calls

// GET request
const users = await apiClient.get('/users');

// POST request
const response = await apiClient.post('/users', {
  name: 'John Doe',
  email: '[email protected]',
});

// PUT request
const updated = await apiClient.put('/users/123', {
  name: 'Jane Doe',
});

// DELETE request
await apiClient.delete('/users/123');

// PATCH request
const patched = await apiClient.patch('/users/123', {
  email: '[email protected]',
});

Advanced Usage

// Change base URL dynamically
apiClient.setBaseUrl('https://api-v2.example.com');

// Access raw Axios instance
const axiosInstance = apiClient.getAxiosInstance();

// Add custom interceptors
axiosInstance.interceptors.request.use((config) => {
  // Custom logic
  return config;
});

API Reference

Constructor

new ApiClient(config: ApiClientConfig)

ApiClientConfig:

• baseURL (string, required): Base URL for API requests
• timeout (number, optional): Request timeout in ms (default: 30000)
• headers (object, optional): Default headers for all requests
• enableVersionCheck (boolean, optional): Enable automatic version checking
• versionCheckConfig (VersionCheckConfig, optional): Version check configuration

VersionCheckConfig:

• supabaseUrl (string, required): Supabase project URL
• supabaseAnonKey (string, required): Supabase anonymous key
• appName (string, optional): App name for headers
• downloadUrl (string, optional): URL for app download when blocked

Methods

checkVersion(version?, platform?): Promise<VersionCheckResult>

Check app version against server.

const result = await apiClient.checkVersion();
console.log(result.is_blocked, result.requires_update, result.latest_version);

setBaseUrl(url: string): void

Change the base URL dynamically.

apiClient.setBaseUrl('https://new-api.example.com');

get<T>(url, config?): Promise<T>

Perform GET request.

const data = await apiClient.get<User[]>('/users');

post<T>(url, body?, config?): Promise<AxiosResponse<T>>

Perform POST request.

const response = await apiClient.post('/users', userData);

put<T>(url, body?, config?): Promise<AxiosResponse<T>>

Perform PUT request.

delete<T>(url, config?): Promise<AxiosResponse<T>>

Perform DELETE request.

patch<T>(url, body?, config?): Promise<AxiosResponse<T>>

Perform PATCH request.

getAxiosInstance(): AxiosInstance

Access the underlying Axios instance for advanced customization.

Automatic Headers

All requests automatically include:

• X-App-Version: App version from device info
• X-Build-Number: Build number from device info
• X-Platform: Platform (ios/android)
• X-App-Name: App name (if configured)

Version Blocking

When server responds with HTTP 426 (Upgrade Required), the client:

1. Shows alert dialog with version information
2. Provides option to download latest version
3. Allows user to exit the app
4. Prevents further API usage until updated

Error Handling

try {
  const data = await apiClient.get('/users');
} catch (error) {
  if (error.response?.status === 401) {
    console.log('Unauthorized');
  } else if (error.response?.status === 426) {
    console.log('Version blocked');
  } else {
    console.error('API Error:', error);
  }
}

TypeScript Support

Full TypeScript support with type definitions included.

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

const users = await apiClient.get<User[]>('/users');

License

MIT