@devlander/rawstack-axios-module

A comprehensive API client module for The Raw Outdoors with React Query hooks, endpoints, and types. TypeScript-safe singleton pattern ensures all hooks use the same base URL and configuration.

📚 Documentation

• Folder Structure & Patterns - Complete guide to the codebase structure and patterns
• Services Documentation - Detailed API services and React Query hooks
• Query Parameters Usage - How to use query parameters
• Environment Testing - Testing environment setup

Installation

1npm install @devlander/rawstack-axios-module
2# or
3yarn add @devlander/rawstack-axios-module

Peer Dependencies

This package requires the following peer dependencies:

1npm install @tanstack/react-query axios
2# or
3yarn add @tanstack/react-query axios

Quick Start

1. Initialize the API Client (TypeScript-Safe Singleton)

Initialize once at app startup - this ensures all hooks and services use the same base URL and configuration:

1import { ApiClientFactory } from '@devlander/rawstack-axios-module';
2
3// Initialize once at app startup - this is a singleton
4ApiClientFactory.initialize({
5  baseUrl: 'https://api.therawoutdoors.com',
6  keyIdentifier: 'your-key-identifier',
7  tokenKey: 'your-token-key',
8  debug: false, // Set to true for development
9  // Storage functions for token management
10  saveToStorage: (key, value, identifier) => {
11    localStorage.setItem(`${identifier}_${key}`, value);
12  },
13  getFromStorage: (key, identifier) => {
14    return localStorage.getItem(`${identifier}_${key}`);
15  },
16  removeFromStorage: (key, identifier) => {
17    localStorage.removeItem(`${identifier}_${key}`);
18  }
19});
20
21// ✅ All hooks and services now use the same base URL and configuration
22// ✅ TypeScript-safe: Can't be initialized twice
23// ✅ Runtime-safe: Throws error if not initialized before using hooks

2. Set up React Query Provider

1import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
2
3const queryClient = new QueryClient();
4
5function App() {
6  return (
7    <QueryClientProvider client={queryClient}>
8      {/* Your app components */}
9    </QueryClientProvider>
10  );
11}

3. Use the Hooks (All Use Same Configuration)

All hooks automatically use the same base URL and configuration:

1import { useGetCurrentUser, useLoginUser, useGetVideosWithLimit } from '@devlander/rawstack-axios-module';
2
3function MyComponent() {
4  // ✅ All these hooks use the same base URL and configuration
5  const { data: user } = useGetCurrentUser();
6  const { data: videos } = useGetVideosWithLimit(10);
7  const loginMutation = useLoginUser();
8  
9  // ✅ TypeScript-safe: Will throw error if not initialized
10  // ✅ All requests go to the same base URL
11  // ✅ All use the same authentication and storage configuration
12  
13  return (
14    <div>
15      <h1>Welcome, {user?.data?.name}!</h1>
16      <p>Videos: {videos?.data?.videos?.length}</p>
17    </div>
18  );
19}

TypeScript-Safe Singleton Benefits

✅ Single Configuration Source

1// Initialize once
2ApiClientFactory.initialize(config);
3
4// All hooks use the same config automatically
5const user = useGetCurrentUser(); // Uses same baseUrl
6const videos = useGetVideosWithLimit(10); // Uses same baseUrl
7const search = useSearchBarQuery('query', 10); // Uses same baseUrl

✅ Runtime Safety

1// ❌ This will throw a clear error if not initialized
2const user = useGetCurrentUser(); 
3// Error: "API client not initialized. Call ApiClientFactory.initialize() first."
4
5// ✅ Check if ready before using
6if (ApiClientFactory.isReady()) {
7  const user = useGetCurrentUser();
8}

✅ Configuration Validation

1// ❌ Missing required fields will throw at initialization
2ApiClientFactory.initialize({
3  baseUrl: 'https://api.example.com'
4  // Error: "keyIdentifier is required"
5  // Error: "tokenKey is required"
6});
7
8// ✅ All required fields validated at startup
9ApiClientFactory.initialize({
10  baseUrl: 'https://api.example.com',
11  keyIdentifier: 'my-app',
12  tokenKey: 'auth-token'
13});

✅ Dynamic Base URL Updates

1// Update base URL for all services at runtime
2ApiClientFactory.updateBaseUrl('https://staging-api.example.com');
3
4// All subsequent requests use the new base URL
5const user = useGetCurrentUser(); // Uses new baseUrl
6const videos = useGetVideosWithLimit(10); // Uses new baseUrl

Available Hooks

User Management

• useGetCurrentUser() - Get current user
• useGetUserByID(id) - Get user by ID
• useLoginUser() - Login mutation
• useRegisterUser() - Registration mutation
• useLogoutUser() - Logout mutation

Video Management

• useGetVideoByID(id) - Get video by ID
• useGetVideosWithLimit(limit) - Get videos with limit
• usePostCreateVideo() - Create video mutation

Search

• useSearchBarQuery(query, limit) - Search across all content
• useSearchVideoQuery(query, limit) - Search videos only
• useSearchUsersQuery(query, limit) - Search users only

Watchlist

• useGetWatchlist(profileId, params) - Get user's watchlist
• useAddToWatchlist() - Add to watchlist mutation
• useRemoveFromWatchlist() - Remove from watchlist mutation

Featured

• useGetFeaturedVideos() - Get all featured videos
• useGetFeaturedProducers() - Get all featured producers
• useGetFeaturedByType(contentType, page?, limit?) - Get featured by type
• useGetFeaturedById(id) - Get featured by ID
• useCreateFeatured() - Create new featured mutation
• useUpdateFeatured() - Update featured mutation
• useDeleteFeatured() - Delete featured mutation

Avatar

• useGetAvailableAvatars() - Get all available avatars
• useGetAvatarById(id) - Get avatar by ID

Show Preferences

• useCheckShowPreferenceStatus(profileId, contentId, contentType) - Check preference status
• useCreateShowPreference() - Create preference mutation
• useRemoveShowPreference() - Remove preference mutation

Gear

• useGetGearByID(id) - Get gear by ID
• useGetGearByLimit(limit) - Get gear with limit
• usePostCreateGear() - Create gear mutation

Producer

• useGetProducerById(id) - Get producer by ID
• useGetProducersWithStart(start) - Get producers with pagination
• usePostCreateProducer() - Create producer mutation

Mail

• useSendResetPasswordLink(email) - Send password reset email

Configuration Options

Required Parameters

• baseUrl: The base URL for your API (used by ALL hooks and services)
• keyIdentifier: Unique identifier for your application
• tokenKey: Key used for storing authentication tokens

Optional Parameters

• debug: Enable debug mode (default: false)
• saveToStorage: Function to save data to storage
• getFromStorage: Function to retrieve data from storage
• removeFromStorage: Function to remove data from storage
• errorLogger: Custom error logging function

Storage Functions

The package requires storage functions for token management. Here are examples for different platforms:

Web (localStorage)

1{
2  saveToStorage: (key, value, identifier) => {
3    localStorage.setItem(`${identifier}_${key}`, value);
4  },
5  getFromStorage: (key, identifier) => {
6    return localStorage.getItem(`${identifier}_${key}`);
7  },
8  removeFromStorage: (key, identifier) => {
9    localStorage.removeItem(`${identifier}_${key}`);
10  }
11}

React Native (AsyncStorage)

1import AsyncStorage from '@react-native-async-storage/async-storage';
2
3{
4  saveToStorage: async (key, value, identifier) => {
5    await AsyncStorage.setItem(`${identifier}_${key}`, value);
6  },
7  getFromStorage: async (key, identifier) => {
8    return await AsyncStorage.getItem(`${identifier}_${key}`);
9  },
10  removeFromStorage: async (key, identifier) => {
11    await AsyncStorage.removeItem(`${identifier}_${key}`);
12  }
13}

Error Handling

All hooks include built-in error handling. Errors are logged to the console by default, but you can provide a custom error logger:

1ApiClientFactory.initialize({
2  // ... other config
3  errorLogger: (error, context) => {
4    // Your custom error logging
5    console.error(`[${context}]`, error);
6    // Send to your error tracking service
7    // Sentry.captureException(error);
8  }
9});

TypeScript Support

The package includes full TypeScript support with comprehensive type definitions for all endpoints, responses, and hooks.

Contributing

Please refer to the project's contribution guidelines for information on how to contribute to this package.

License

ISC