Skip to content

README.md

Latest commit

 

History

History
307 lines (231 loc) · 8.35 KB

README.md

File metadata and controls

307 lines (231 loc) · 8.35 KB
Raw

📚 Flowfull Client Documentation

Welcome to the complete documentation for @pubflow/flowfull-client - the universal HTTP client for Flowfull backends.

🎯 What is Flowfull Client?

Flowfull Client is a developer-friendly, type-safe HTTP client designed specifically for connecting to Flowfull backends. It provides:

  • ✅ Chainable Query Builder - Build complex queries with ease
  • ✅ 14 Filter Operators - Powerful filtering capabilities
  • ✅ Auto Session Management - Works seamlessly with Pubflow auth
  • ✅ TypeScript First - Complete type safety
  • ✅ Universal - Works with React, React Native, Next.js, and vanilla JS
  • ✅ Retry Logic - Automatic retry on failures
  • ✅ Interceptors - Customize requests and responses
  • ✅ Multiple Instances - Connect to multiple APIs

📖 Documentation Index

Getting Started

Core Concepts

Payments API 💳

Platform-Specific Guides

  • React Native - Using Flowfull Client in React Native/Expo apps
  • React - Using Flowfull Client in React apps (coming soon)
  • Next.js - Using Flowfull Client in Next.js apps (coming soon)

Backend Development

Advanced Topics

Reference

🚀 Quick Example

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

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

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

// Complex query
const products = await api
  .query('/products')
  .search('laptop')
  .where('status', 'active')
  .where('price', 'gte', 500)
  .where('price', 'lte', 2000)
  .sort('price', 'asc')
  .page(1)
  .limit(20)
  .get();

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

🎯 Key Features

Chainable Query Builder

Build complex queries with a fluent, chainable API:

const response = await api
  .query('/users')
  .where('status', 'active')
  .where('age', 'gte', 18)
  .search('john')
  .sort('name', 'asc')
  .page(1)
  .limit(20)
  .get();

14 Powerful Filter Operators

  • Comparison: eq, ne, gt, gte, lt, lte
  • String: like, ilike, startsWith, endsWith
  • Array: in, notIn
  • Null: isNull, isNotNull
  • Range: between, notBetween
import { gte, inOp, isNotNull } from '@pubflow/flowfull-client';

const users = await api
  .query('/users')
  .where('age', gte(21))
  .where('role', inOp(['admin', 'moderator']))
  .where('verified_at', isNotNull())
  .get();

Auto Session Management

Works seamlessly with Pubflow authentication:

// Automatically detects session from localStorage/AsyncStorage
const api = createFlowfull('https://api.myapp.com');

// All requests include session header automatically
const profile = await api.get('/profile');

TypeScript Support

Full type safety with generics:

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

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

if (response.success) {
  // TypeScript knows response.data is User[]
  response.data.forEach(user => {
    console.log(user.name);
  });
}

Retry Logic

Automatic retry on network errors and 5xx responses:

const api = createFlowfull('https://api.myapp.com', {
  retry: {
    attempts: 3,
    delay: 1000,
    exponentialBackoff: true
  }
});

Interceptors

Customize requests and responses:

// Add timestamp to all requests
api.addRequestInterceptor(async (config) => {
  config.headers['X-Request-Time'] = new Date().toISOString();
  return config;
});

// Log all errors
api.addResponseInterceptor(async (response) => {
  if (!response.success) {
    console.error('API Error:', response.error);
  }
  return response;
});

🌍 Universal Compatibility

Works everywhere JavaScript runs:

  • ✅ React - Web applications
  • ✅ React Native - Mobile apps (iOS/Android)
  • ✅ Expo - Managed React Native apps
  • ✅ Next.js - Server and client components
  • ✅ Node.js - Backend applications
  • ✅ Bun - Modern JavaScript runtime
  • ✅ Vanilla JS - No framework needed

📦 What's Included

@pubflow/flowfull-client
├── Core Client (FlowfullClient)
├── Query Builder (QueryBuilder)
├── Session Manager (SessionManager)
├── Request Handler (RequestHandler)
├── 14 Filter Operators
├── TypeScript Types
└── Utility Functions

🎓 Learning Path

  1. Start Here: Getting Started Guide
  2. Learn Filtering: Filter Operators
  3. Master Queries: Query Builder
  4. Platform Guide: React Native | React | Next.js
  5. Advanced: TypeScript | Interceptors

💡 Common Use Cases

E-commerce Product Search

const products = await api
  .query('/products')
  .search(searchTerm)
  .where('category', category)
  .where('price', 'gte', minPrice)
  .where('price', 'lte', maxPrice)
  .where('in_stock', true)
  .sort('price', 'asc')
  .page(page)
  .limit(20)
  .get();

User Management

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

Analytics Dashboard

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

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

MIT License - see LICENSE for details.

🆘 Support

Ready to get started? → Getting Started Guide