@appello/services

Frontend Services Library

A comprehensive TypeScript library providing reusable service utilities for handling API requests, GraphQL operations, and data fetching across web and mobile React applications.

📋 Table of Contents

• ✨ Features
• 📦 Installation
• 🚀 Quick Start
• 🏗️ Core Services
• 🔗 Integration Examples
• 🛠️ Utilities
• ⚙️ Configuration
• 💡 Complete Example
• ❓ Troubleshooting

✨ Features

• 🌐 REST API Service - Axios-based with automatic token refresh
• 🔗 GraphQL Client - Apollo Client with auth, error handling, and subscriptions
• 🏪 RTK Query Integration - Redux Toolkit Query base query
• 🔄 React Query Support - TanStack React Query client factory
• 🔐 Authentication - JWT token management with refresh logic
• ⚠️ Error Handling - Standardized error processing for forms
• 🎯 TypeScript - Full type safety and IntelliSense support
• 📱 Cross-Platform - Works with React web and React Native

📦 Installation

npm install @appello/services

Peer Dependencies:

npm install @appello/common

🚀 Quick Start

Basic Setup

import { createApiService, createGqlClient } from '@appello/services';

// REST API Service
const apiService = createApiService({
  url: 'https://api.example.com',
  getAccessToken: () => localStorage.getItem('accessToken'),
  getRefreshToken: () => localStorage.getItem('refreshToken'),
  onTokenRefreshSuccess: tokens => {
    localStorage.setItem('accessToken', tokens.accessToken);
    localStorage.setItem('refreshToken', tokens.refreshToken);
  },
  onTokenRefreshError: () => {
    // Handle logout
  },
  refreshTokenUrl: '/auth/refresh',
});

// GraphQL Client
const gqlClient = createGqlClient({
  url: 'https://api.example.com/graphql',
  wsUrl: 'wss://api.example.com/graphql',
  getAccessToken: () => localStorage.getItem('accessToken'),
  getRefreshToken: () => localStorage.getItem('refreshToken'),
  onTokenRefreshSuccess: tokens => {
    localStorage.setItem('accessToken', tokens.accessToken);
    localStorage.setItem('refreshToken', tokens.refreshToken);
  },
  onTokenRefreshError: () => {
    // Handle logout
  },
  refreshTokens: async (client, context) => {
    // Custom refresh logic
  },
});

Error Handling

import { createProcessApiErrorResponse } from '@appello/services';

const processApiError = createProcessApiErrorResponse({
  onGlobalError: message => toast.error(message),
  onUnknownErrors: message => console.error(message),
});

🏗️ Core Services

Service	Purpose	Factory Function
---------------	----------------------------------------	---------------------------
REST API	HTTP requests with auth & error handling	createApiService(config)
GraphQL	Apollo Client with subscriptions & auth	createGqlClient(config)
React Query	TanStack React Query client	createQueryClient(config)

🔗 Integration Examples

🏪 RTK Query Integration

import { createApi } from '@reduxjs/toolkit/query/react';
import { axiosBaseQuery, handleRtkQueryError } from '@appello/services';

export const api = createApi({
  baseQuery: axiosBaseQuery({ api: apiService }),
  endpoints: builder => ({
    login: builder.mutation({
      query: credentials => ({
        url: '/auth/login',
        method: 'POST',
        data: credentials,
      }),
    }),
  }),
});

// Usage
const [login] = api.useLoginMutation();

try {
  await login(credentials).unwrap();
} catch (error) {
  processError({ errors: handleRtkQueryError(error) });
}

🔄 React Query Integration

import { useMutation } from '@tanstack/react-query';
import { handleApiRequestError } from '@appello/services';

const mutation = useMutation({
  mutationFn: credentials => apiService.post('/auth/login', credentials),
  onError: error => {
    processError({ errors: handleApiRequestError({ error }) });
  },
});

🎯 Form Integration

import { useForm } from 'react-hook-form';

const { handleSubmit, setError } = useForm();

const onSubmit = async data => {
  try {
    await apiService.post('/auth/login', data);
  } catch (error) {
    processError({
      errors: handleApiRequestError({ error }),
      fields: ['username', 'password'],
      setFormError: setError,
    });
  }
};

🌐 GraphQL Setup

import { createGqlClient } from '@appello/services';

const gqlClient = createGqlClient({
  url: 'https://api.example.com/graphql',
  wsUrl: 'wss://api.example.com/graphql',
  getAccessToken: () => localStorage.getItem('accessToken'),
  getRefreshToken: () => localStorage.getItem('refreshToken'),
  onTokenRefreshSuccess: tokens => {
    localStorage.setItem('accessToken', tokens.accessToken);
    localStorage.setItem('refreshToken', tokens.refreshToken);
  },
  onTokenRefreshError: () => {
    window.location.href = '/login';
  },
  refreshTokens: async (client, context) => {
    const { data } = await client.mutate({
      mutation: REFRESH_TOKEN_MUTATION,
      context,
    });
    return data.refreshToken;
  },
});

🛠️ Utilities

Error Handling Functions

Function	Purpose	Use Case
handleApiRequestError({ error })	Process REST API errors	Convert Axios errors to user-friendly format
handleRtkQueryError(error)	Process RTK Query errors	Extract error data from RTK Query responses
createProcessApiErrorResponse(config)	Form error processor	Integrate API errors with React Hook Form
createProcessGqlErrorResponse(config)	GraphQL error processor	Handle GraphQL errors in forms

Authentication Utilities

🔐 setAuthorizationHeader

Adds Bearer token to request headers without mutating the original headers object.

import { setAuthorizationHeader } from '@appello/services';

const headers = { 'Content-Type': 'application/json' };
const token = 'my-jwt-token';

const newHeaders = setAuthorizationHeader(token, headers);
// Result: { 'Content-Type': 'application/json', Authorization: 'Bearer my-jwt-token' }

Parameters:

• token: string - The access token
• headers: AxiosRequestHeaders - Existing headers object

Returns: AxiosRequestHeaders - New headers object with Authorization header

📊 getGqlAuthorizationHeader

Creates an authorization header object for GraphQL requests.

import { getGqlAuthorizationHeader } from '@appello/services';

const authHeader = getGqlAuthorizationHeader('my-jwt-token');
// Result: { Authorization: 'Bearer my-jwt-token' }

Parameters:

• token: string - The access token

Returns: { Authorization: string } - Authorization header object

Token Management

🔄 refreshTokens

Handles JWT token refresh for expired authentication tokens with sophisticated queuing and retry mechanisms.

// This function is typically used internally by the API service
// but can be customized through ApiServiceConfig

Purpose: Implements a comprehensive token refresh mechanism that prevents race conditions by ensuring only one refresh operation runs at a time, while queuing additional requests until the refresh completes.

Features:

• ✅ Race Condition Prevention: Only one refresh operation runs at a time
• ✅ Request Queuing: Queues subsequent requests during refresh
• ✅ Custom Refresh Logic: Supports both endpoint-based and custom refresh functions
• ✅ Automatic Retry: Retries failed requests after successful token refresh
• ✅ Error Handling: Proper cleanup on refresh failures

Configuration: Configured through ApiServiceConfig in the API service setup.

🏪 handleRtkQueryError

Extracts error data from RTK Query responses and converts them to a standardized format.

import { handleRtkQueryError } from '@appello/services';

try {
  await login(credentials).unwrap();
} catch (error) {
  const errors = handleRtkQueryError(error);
  processError({ errors });
}

Parameters:

• error: unknown - RTK Query error object

Returns: ResponseErrors - Standardized error format

Features:

• ✅ RTK Query Integration: Specifically designed for RTK Query error handling
• ✅ Error Type Detection: Handles different RTK Query error types
• ✅ Standardized Output: Converts to consistent ResponseErrors format
• ✅ Type Safety: Full TypeScript support

Form Error Processing

⚠️ handleApiRequestError

Processes Axios API errors into a standardized ResponseErrors format.

import { handleApiRequestError } from '@appello/services';

try {
  await apiService.post('/api/endpoint', data);
} catch (error) {
  const errors = handleApiRequestError({ error });
  // errors: { field1: 'Error message', field2: 'Another error' }
}

Parameters:

• error: AxiosError - The Axios error object
• handleDetailError?: (error: ResponseErrors) => ResponseErrors - Custom field error handler
• onManualHandleError?: (error: AxiosError) => ResponseErrors - Override error handling

Returns: ResponseErrors - Map of field names to error messages

Features:

• Handles network, server, and validation errors
• Flattens nested field errors to dot notation
• Takes first error from arrays
• Supports custom error processing

📝 createProcessApiErrorResponse

Creates a processor for integrating API errors with React Hook Form.

import { createProcessApiErrorResponse } from '@appello/services';

const processError = createProcessApiErrorResponse({
  onGlobalError: message => toast.error(message),
  onUnknownErrors: message => console.error(message),
});

// Usage with form
const { setError } = useForm();

try {
  await apiService.post('/api/login', credentials);
} catch (error) {
  processError({
    errors: handleApiRequestError({ error }),
    fields: ['username', 'password'],
    setFormError: setError,
  });
}

Configuration Options:

• onGlobalError?: (message: string) => void - Handle non-field errors
• onUnknownErrors?: (message: string) => void - Handle unknown errors
• onUnhandledFieldErrors?: (errors: UnhandledFieldError[]) => void - Handle unhandled fields

Usage Parameters:

• errors: ResponseErrors - Error object from handleApiRequestError
• fields: string[] | Record<string, string> - Form fields to handle
• setFormError?: (name: string, error: { message: string }) => void - React Hook Form setError

🔧 createProcessGqlErrorResponse

Creates a processor for handling GraphQL errors in forms.

import { createProcessGqlErrorResponse } from '@appello/services';

const processGqlError = createProcessGqlErrorResponse({
  onNonFieldError: message => toast.error(message),
  onUnknownError: message => console.error(message),
});

// Usage with GraphQL errors
const { setError } = useForm();

try {
  await apolloClient.mutate({ mutation: LOGIN_MUTATION, variables: credentials });
} catch (gqlError) {
  processGqlError(gqlError, {
    fields: ['username', 'password'],
    setFormError: setError,
  });
}

Configuration Options:

• onNonFieldError?: (message: string) => void - Handle general errors
• onUnknownError?: (message: string) => void - Handle unknown errors
• onUnhandledFieldErrors?: (errors: UnhandledFieldError[]) => void - Handle unhandled fields

Usage Parameters:

• gqlError: unknown - GraphQL error object
• fields: string[] | Record<string, string> - Form fields to handle
• setFormError?: (name: string, error: { message: string }) => void - React Hook Form setError

GraphQL Error Helpers

🔍 GraphQL Error Detection

import {
  getGqlErrors,
  getGqlError,
  isGqlUnauthorizedError,
  isGqlBusinessError,
  isGqlUnknownError,
} from '@appello/services';

// Extract errors from GraphQL response
const errors = getGqlErrors(gqlError);

// Get first error
const firstError = getGqlError(errors);

// Check error types
if (isGqlUnauthorizedError(errors)) {
  // Handle 401 unauthorized
}

if (isGqlBusinessError(errors)) {
  // Handle business logic errors
}

⚙️ Configuration

API Service Configuration

interface ApiServiceConfig<T = ApiBaseTokens> {
  url: string; // Base API URL
  getAccessToken?: () => Promise<string | null>; // Access token getter
  getRefreshToken?: () => Promise<string | null>; // Refresh token getter
  onTokenRefreshSuccess: (tokens: T) => void; // Success callback
  onTokenRefreshError: (error?: unknown) => void; // Error callback
  refreshTokenUrl?: string; // Refresh endpoint
  refreshTokens?: (instance, error) => Promise<T>; // Custom refresh logic
  getAccessTokenFromRefreshRequest?: (data) => string; // Extract token from response
  axiosConfig?: CreateAxiosDefaults; // Axios configuration
}

GraphQL Client Configuration

interface GqlClientConfig<T = GqlBaseTokens> {
  url: string; // GraphQL endpoint
  wsUrl?: string; // WebSocket URL for subscriptions
  getAccessToken: () => Promise<string | null>; // Access token getter
  getRefreshToken: () => Promise<string | null>; // Refresh token getter
  onTokenRefreshSuccess: (tokens: T) => void; // Success callback
  onTokenRefreshError: (error?: unknown) => void; // Error callback
  refreshTokens: (client, context) => Promise<T>; // Custom refresh logic
  refreshTokenOperationName?: string; // Refresh mutation name
  refreshTokenErrorMessage?: string; // Error message
  onUnknownError?: (message: string) => void; // Unknown error handler
  cache?: InMemoryCacheConfig; // Apollo cache config
  additionalLinks?: ApolloLink | ApolloLink[]; // Extra Apollo links
  uploadLinkParams?: object; // File upload config
}

💡 Complete Example

import {
  createApiService,
  createGqlClient,
  createProcessApiErrorResponse,
  handleApiRequestError,
} from '@appello/services';
import { toast } from 'react-toastify';

// Tokens management
const getAccessToken = () => localStorage.getItem('accessToken');
const getRefreshToken = () => localStorage.getItem('refreshToken');

const handleTokenRefreshSuccess = tokens => {
  localStorage.setItem('accessToken', tokens.accessToken);
  localStorage.setItem('refreshToken', tokens.refreshToken);
};

const handleTokenRefreshError = () => {
  localStorage.clear();
  window.location.href = '/login';
};

// API Service
export const apiService = createApiService({
  url: process.env.REACT_APP_API_URL,
  getAccessToken,
  getRefreshToken,
  onTokenRefreshSuccess: handleTokenRefreshSuccess,
  onTokenRefreshError: handleTokenRefreshError,
  refreshTokenUrl: '/auth/refresh',
});

// GraphQL Client
export const gqlClient = createGqlClient({
  url: `${process.env.REACT_APP_API_URL}/graphql`,
  wsUrl: `${process.env.REACT_APP_WS_URL}/graphql`,
  getAccessToken,
  getRefreshToken,
  onTokenRefreshSuccess: handleTokenRefreshSuccess,
  onTokenRefreshError: handleTokenRefreshError,
  refreshTokens: async (client, context) => {
    const { data } = await client.mutate({
      mutation: REFRESH_TOKEN_MUTATION,
      context,
    });
    return data.refreshToken;
  },
});

// Error Processing
export const processApiError = createProcessApiErrorResponse({
  onGlobalError: message => toast.error(message),
  onUnknownErrors: message => {
    console.error('Unknown API error:', message);
    toast.error('An unexpected error occurred');
  },
});

// Usage in components
export const useLogin = () => {
  const { setError } = useForm();

  return useMutation({
    mutationFn: credentials => apiService.post('/auth/login', credentials),
    onError: error => {
      processApiError({
        errors: handleApiRequestError({ error }),
        fields: ['email', 'password'],
        setFormError: setError,
      });
    },
  });
};

❓ Troubleshooting

Common Issues

Token Refresh Not Working

• Ensure refreshTokenUrl is correct
• Check getRefreshToken returns valid token
• Verify onTokenRefreshSuccess saves tokens properly

GraphQL Subscriptions Failing

• Check wsUrl is accessible
• Verify WebSocket connection in network tab
• Ensure proper authentication context

Form Errors Not Showing

• Check field names match between API and form
• Verify setFormError function is passed correctly
• Use onUnhandledFieldErrors to debug unmapped fields

RTK Query Integration Issues

• Ensure axiosBaseQuery receives initialized API service
• Check error handling in RTK Query endpoints
• Verify error transformation logic

Debug Mode

Enable detailed logging:

const apiService = createApiService({
  // ... config
  axiosConfig: {
    // Enable request/response logging
    transformRequest: [
      (data, headers) => {
        console.log('API Request:', { data, headers });
        return data;
      },
    ],
  },
});

Package Version: 4.0.1
License: ISC
Author: Appello Software

For more examples and advanced usage, check the test files in the repository.