What is it for?

@pubflow/flowfull-client is the universal HTTP client designed specifically for interacting with Flowfull backends. It simplifies API communication by providing a powerful, type-safe, and developer-friendly interface that works across all JavaScript environments.

Purpose

The Flowfull Client solves common challenges developers face when building applications:

1. Simplified API Communication

Instead of manually constructing URLs, handling query parameters, and managing headers, the Flowfull Client provides a clean, chainable API:

typescript

// ❌ Without Flowfull Client (manual, error-prone)
const url = `${baseUrl}/products?status=active&price_gte=50&price_lte=200&page=1&limit=20&sort=price&order=asc`;
const response = await fetch(url, {
  headers: {
    'Content-Type': 'application/json',
    'X-Session-Id': localStorage.getItem('session_id') || ''
  }
});
const data = await response.json();

// ✅ With Flowfull Client (clean, type-safe)
const response = await api
  .query('/products')
  .where('status', 'active')
  .where('price', 'gte', 50)
  .where('price', 'lte', 200)
  .page(1)
  .limit(20)
  .sort('price', 'asc')
  .get();

2. Automatic Session Management

No need to manually handle authentication tokens and session IDs. The client automatically:

Detects sessions from storage (localStorage, AsyncStorage)
Includes session headers in all requests
Works seamlessly with Pubflow authentication
Supports custom session strategies

typescript

// Auto-detect session (zero configuration)
const api = createFlowfull('https://api.myapp.com');
// ✅ Automatically finds and uses session from storage

// All requests include session automatically
await api.get('/profile');  // Includes X-Session-Id header

3. Universal Compatibility

Write once, run everywhere. The same code works across:

Web browsers (React, Vue, vanilla JS)
Mobile apps (React Native, Expo)
Server-side (Node.js, Bun, Deno)
Desktop apps (Electron, Tauri)

typescript

// Same code works in all environments
const api = createFlowfull('https://api.myapp.com');
const users = await api.get('/users');

4. Type Safety

Full TypeScript support with comprehensive type definitions:

typescript

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

// TypeScript knows the response type
const response = await api.get<User[]>('/users');

if (response.success) {
  // TypeScript autocomplete works here
  response.data.forEach(user => {
    console.log(user.name);  // ✅ Type-safe
  });
}

5. Powerful Query Building

Build complex queries with 14 filter operators and a fluent API:

typescript

import { gte, between, inOp, isNotNull } from '@pubflow/flowfull-client';

const products = await api
  .query('/products')
  .search('laptop')                           // Full-text search
  .where('category', 'electronics')           // Exact match
  .where('price', between(500, 2000))         // Range filter
  .where('rating', gte(4))                    // Comparison
  .where('status', inOp(['active', 'new']))   // Array filter
  .where('image_url', isNotNull())            // Null check
  .sort('price', 'asc')                       // Sorting
  .page(1)                                    // Pagination
  .limit(20)
  .get();

Use Cases

🛒 E-commerce Applications

Perfect for building product catalogs, shopping carts, and order management:

typescript

// Product search with filters
const products = await api
  .query('/products')
  .search(searchTerm)
  .where('category', selectedCategory)
  .where('price', between(minPrice, maxPrice))
  .where('in_stock', true)
  .sort('price', sortDirection)
  .page(currentPage)
  .limit(20)
  .get();

// Add to cart
const cart = await api.post('/cart/items', {
  product_id: productId,
  quantity: 1
});

// Checkout
const order = await api.post('/orders', {
  items: cartItems,
  shipping_address: address,
  payment_method: paymentMethod
});

👥 User Management Systems

Ideal for admin dashboards, user directories, and access control:

typescript

// Find active verified users
const users = await api
  .query('/users')
  .where('status', 'active')
  .where('verified_at', isNotNull())
  .where('role', notIn(['banned', 'suspended']))
  .where('created_at', gte('2024-01-01'))
  .sort('created_at', 'desc')
  .get();

// Update user
const updated = await api.patch('/users/123', {
  role: 'moderator'
});

// Delete user
await api.delete('/users/123');

📊 Analytics & Reporting

Great for dashboards, reports, and data visualization:

typescript

// Get analytics data
const stats = await api
  .query('/analytics/events')
  .where('event_type', 'purchase')
  .where('created_at', between(startDate, endDate))
  .param('group_by', 'date')
  .param('aggregate', 'sum,count,avg')
  .get();

// Export report
const report = await api
  .query('/reports/sales')
  .where('period', 'monthly')
  .where('year', 2024)
  .param('format', 'csv')
  .get();

📱 Mobile Applications

Perfect for React Native and Expo apps with offline support:

typescript

// Works with AsyncStorage automatically
const api = createFlowfull('https://api.myapp.com');

// Fetch user profile
const profile = await api.get('/profile');

// Update profile with image
const updated = await api.patch('/profile', {
  name: 'John Doe',
  bio: 'Software developer'
});

// Sync data when online
const syncData = async () => {
  const localChanges = await getLocalChanges();
  for (const change of localChanges) {
    await api.post('/sync', change);
  }
};

🎮 Gaming & Leaderboards

Ideal for game backends, player stats, and leaderboards:

typescript

// Get top players
const leaderboard = await api
  .query('/players')
  .where('season', currentSeason)
  .sort('score', 'desc')
  .limit(100)
  .get();

// Update player stats
const stats = await api.patch('/players/me/stats', {
  score: newScore,
  level: newLevel,
  achievements: newAchievements
});

// Get player matches
const matches = await api
  .query('/matches')
  .where('player_id', playerId)
  .where('status', 'completed')
  .sort('created_at', 'desc')
  .limit(20)
  .get();

📝 Content Management

Great for blogs, news sites, and content platforms:

typescript

// Get published articles
const articles = await api
  .query('/articles')
  .where('status', 'published')
  .where('published_at', lte(new Date().toISOString()))
  .where('category', selectedCategory)
  .sort('published_at', 'desc')
  .page(currentPage)
  .limit(10)
  .get();

// Create new article
const newArticle = await api.post('/articles', {
  title: 'My Article',
  content: 'Article content...',
  category: 'technology',
  tags: ['javascript', 'typescript']
});

// Search articles
const searchResults = await api
  .query('/articles')
  .search(searchQuery)
  .where('status', 'published')
  .get();

When to Use Flowfull Client

✅ Use Flowfull Client When:

Building applications with Flowfull backends
Need powerful query building and filtering
Want automatic session management
Require cross-platform compatibility
Need type-safe API interactions
Want to avoid boilerplate code
Building complex data-driven applications

❌ Consider Alternatives When:

Using GraphQL (use Apollo Client or similar)
Need real-time subscriptions (use WebSockets directly)
Building simple static sites with no API
Using a different backend framework with its own client

Benefits Over Other HTTP Clients

vs. Fetch API

Feature	Flowfull Client	Fetch API
Query Building	✅ Built-in	❌ Manual
Session Management	✅ Automatic	❌ Manual
Type Safety	✅ Full TypeScript	⚠️ Limited
Retry Logic	✅ Built-in	❌ Manual
Interceptors	✅ Built-in	❌ Manual
Filter Operators	✅ 14 operators	❌ None
Platform Detection	✅ Automatic	❌ Manual

vs. Axios

Feature	Flowfull Client	Axios
Query Building	✅ Built-in	❌ Manual
Session Management	✅ Automatic	⚠️ Manual
Bundle Size	✅ Smaller	⚠️ Larger
Dependencies	✅ Zero	⚠️ Multiple
Filter Operators	✅ 14 operators	❌ None
Flowfull Integration	✅ Native	❌ Manual

vs. SWR/React Query

Feature	Flowfull Client	SWR/React Query
HTTP Client	✅ Built-in	❌ Bring your own
Query Building	✅ Built-in	❌ Manual
Caching	⚠️ Basic	✅ Advanced
React Hooks	⚠️ Planned	✅ Built-in
Universal	✅ All platforms	⚠️ React only

💡 Combine with SWR

You can use Flowfull Client with SWR or React Query for advanced caching and React hooks!

typescript

import useSWR from 'swr';
import { createFlowfull } from '@pubflow/flowfull-client';

const api = createFlowfull('https://api.myapp.com');

function useUsers() {
  return useSWR('/users', () => api.get('/users'));
}

Next Steps

Now that you understand what Flowfull Client is for, learn how to use it:

How to use it - Detailed usage guide
Tutorial - Step-by-step tutorial
API Reference - Complete API documentation

What is it for? ​

Purpose ​

1. Simplified API Communication ​

2. Automatic Session Management ​

3. Universal Compatibility ​

4. Type Safety ​

5. Powerful Query Building ​

Use Cases ​

🛒 E-commerce Applications ​

👥 User Management Systems ​

📊 Analytics & Reporting ​

📱 Mobile Applications ​

🎮 Gaming & Leaderboards ​

📝 Content Management ​

When to Use Flowfull Client ​

✅ Use Flowfull Client When: ​

❌ Consider Alternatives When: ​

Benefits Over Other HTTP Clients ​

vs. Fetch API ​

vs. Axios ​

vs. SWR/React Query ​

Next Steps ​

What is it for?

Purpose

1. Simplified API Communication

2. Automatic Session Management

3. Universal Compatibility

4. Type Safety

5. Powerful Query Building

Use Cases

🛒 E-commerce Applications

👥 User Management Systems

📊 Analytics & Reporting

📱 Mobile Applications

🎮 Gaming & Leaderboards

📝 Content Management

When to Use Flowfull Client

✅ Use Flowfull Client When:

❌ Consider Alternatives When:

Benefits Over Other HTTP Clients

vs. Fetch API

vs. Axios

vs. SWR/React Query

Next Steps