Flowfull Clients Docs

Appearance

@pubflow/flowfull-client ​

Universal HTTP Client for Flowfull Backends

@pubflow/flowfull-client is the default universal HTTP client for the Pubflow ecosystem. It provides a powerful, type-safe, and developer-friendly way to interact with Flowfull backends across any JavaScript environment.

🚀 Default Universal HTTP Client

This is the official universal HTTP client for Flowfull backends. We have plans to launch additional specialized clients in the future, but we also invite you to build your own or request a new client for your specific needs!

Overview ​

The Flowfull Client is designed to make API interactions simple, powerful, and consistent across all platforms. Whether you're building a web app, mobile app, or server-side application, the same API works everywhere.

Key Features ​

  • ✅ Universal - Works in browser, Node.js, Bun, React Native, and more
  • ✅ Type-Safe - Full TypeScript support with comprehensive type definitions
  • ✅ Chainable Query Builder - Build complex queries with an intuitive fluent API
  • ✅ 14 Filter Operators - Powerful filtering capabilities (eq, gt, like, in, between, etc.)
  • ✅ Auto Session Management - Seamless integration with Pubflow authentication
  • ✅ Retry Logic - Automatic retry on failures with exponential backoff
  • ✅ Interceptors - Customize requests and responses globally
  • ✅ Zero Dependencies - Lightweight and fast
  • ✅ Platform Detection - Automatically detects and uses appropriate storage
  • ✅ API Agnostic - Works with any API response format

Installation ​

Install the package using your preferred package manager:

bash
npm install @pubflow/flowfull-client
bash
yarn add @pubflow/flowfull-client
bash
pnpm add @pubflow/flowfull-client
bash
bun add @pubflow/flowfull-client

Quick Start ​

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

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

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

// Complex query with filters
const products = await api
  .query('/products')
  .where('status', 'active')
  .where('price', 'gte', 50)
  .sort('price', 'asc')
  .page(1)
  .limit(20)
  .get();

if (products.success) {
  console.log('Products:', products.data);
  console.log('Total:', products.meta?.total);
}

Platform Support ​

Works everywhere JavaScript runs:

PlatformSupportStorage
Browser✅localStorage
React✅localStorage
React Native✅AsyncStorage
Next.js✅localStorage/Cookies
Node.js✅Custom/None
Bun✅Custom/None
Deno✅Custom/None

Core Concepts ​

1. Simple HTTP Methods ​

Make standard HTTP requests with ease:

typescript
// GET
const response = await api.get('/users');

// POST
const newUser = await api.post('/users', { name: 'John', email: '[email protected]' });

// PUT
const updated = await api.put('/users/123', { name: 'John Updated' });

// PATCH
const patched = await api.patch('/users/123', { status: 'active' });

// DELETE
const deleted = await api.delete('/users/123');

2. Query Builder ​

Build complex queries with a chainable API:

typescript
const response = await api
  .query('/products')
  .search('laptop')                    // Full-text search
  .where('category', 'electronics')    // Filter by category
  .where('price', 'gte', 500)          // Price >= 500
  .where('price', 'lte', 2000)         // Price <= 2000
  .where('stock', 'gt', 0)             // In stock
  .sort('price', 'asc')                // Sort by price
  .page(1)                             // Page 1
  .limit(20)                           // 20 items per page
  .get();

3. Filter Operators ​

14 powerful operators for precise filtering:

typescript
import { eq, gt, gte, lt, lte, like, ilike, startsWith, endsWith, 
         inOp, notIn, isNull, isNotNull, between } from '@pubflow/flowfull-client';

// Comparison
.where('age', gte(21))
.where('price', between(10, 100))

// String matching
.where('email', endsWith('@gmail.com'))
.where('name', ilike('john'))  // Case-insensitive

// Array operations
.where('status', inOp(['active', 'pending']))
.where('role', notIn(['banned', 'deleted']))

// Null checks
.where('verified_at', isNotNull())
.where('deleted_at', isNull())

4. Session Management ​

Automatic session management with Pubflow authentication:

typescript
// Auto-detect session from storage (recommended)
const api = createFlowfull('https://api.myapp.com');
// Automatically finds session from localStorage or AsyncStorage

// Manual session
const api = createFlowfull('https://api.myapp.com', {
  sessionId: 'your-session-id'
});

// Dynamic session
const api = createFlowfull('https://api.myapp.com', {
  getSessionId: async () => {
    return await SecureStore.getItemAsync('session_id');
  }
});

// Sessionless (for public APIs)
const api = createFlowfull('https://api.myapp.com', {
  includeSession: false
});

5. Response Format ​

All responses follow a consistent format:

typescript
interface ApiResponse<T> {
  success: boolean;      // true if HTTP 2xx
  data?: T;              // Response data
  error?: string;        // Error message (if failed)
  message?: string;      // Additional message
  status: number;        // HTTP status code
  meta?: {               // Pagination metadata
    page?: number;
    limit?: number;
    total?: number;
    totalPages?: number;
  };
}

// Usage
const response = await api.get('/users');

if (response.success) {
  console.log('Data:', response.data);
  console.log('Total:', response.meta?.total);
} else {
  console.error('Error:', response.error);
}

Why Choose Flowfull Client? ​

🎯 Developer-Friendly ​

Intuitive API design that feels natural and is easy to learn. Comprehensive TypeScript support catches errors before runtime.

⚡ Performance ​

Built-in retry logic, request deduplication, and optimized for speed. Zero dependencies means smaller bundle size.

🔐 Secure ​

Automatic session management with secure storage. Works seamlessly with Pubflow authentication system.

🌐 Universal ​

Write once, run everywhere. The same code works in browser, React Native, Node.js, and more.

🛠️ Flexible ​

Works with any API response format. Customize with interceptors, custom headers, and storage adapters.

Next Steps ​

Ready to dive deeper? Explore these resources:

Examples ​

typescript
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();

User Management ​

typescript
const activeUsers = 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();

Analytics Query ​

typescript
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();

Community & Support ​

Contributing ​

We welcome contributions! You can:

License ​

MIT License - see LICENSE for details.