API Reference

Complete API documentation for @pubflow/flowfull-client.

Table of Contents

• Factory Functions
• FlowfullClient
• QueryBuilder
• Filter Operators
• Types
• Configuration

Factory Functions

createFlowfull()

Creates a new Flowfull client instance.

function createFlowfull(
  baseUrl: string,
  config?: FlowfullConfig
): FlowfullClient

Parameters:

• baseUrl (string) - The base URL of your API
• config (FlowfullConfig, optional) - Configuration options

Returns: FlowfullClient instance

Example:

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

const api = createFlowfull('https://api.myapp.com', {
  sessionId: 'your-session-id',
  headers: {
    'X-API-Version': 'v2'
  },
  retryAttempts: 3,
  timeout: 30000
});

FlowfullClient

The main client class for making HTTP requests.

Constructor

new FlowfullClient(baseUrl: string, config?: FlowfullConfig)

HTTP Methods

get()

Execute a GET request.

async get<T = any>(
  endpoint: string,
  options?: RequestOptions
): Promise<ApiResponse<T>>

Parameters:

• endpoint (string) - API endpoint path
• options (RequestOptions, optional) - Request options

Returns: Promise resolving to ApiResponse<T>

Example:

const response = await api.get('/users');
const response = await api.get('/users', {
  params: { page: 1, limit: 20 },
  headers: { 'X-Custom': 'value' }
});

post()

Execute a POST request.

async post<T = any>(
  endpoint: string,
  body?: any,
  options?: RequestOptions
): Promise<ApiResponse<T>>

Parameters:

• endpoint (string) - API endpoint path
• body (any, optional) - Request body
• options (RequestOptions, optional) - Request options

Returns: Promise resolving to ApiResponse<T>

Example:

const response = await api.post('/users', {
  name: 'John Doe',
  email: 'john@example.com'
});

put()

Execute a PUT request.

async put<T = any>(
  endpoint: string,
  body?: any,
  options?: RequestOptions
): Promise<ApiResponse<T>>

Example:

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

patch()

Execute a PATCH request.

async patch<T = any>(
  endpoint: string,
  body?: any,
  options?: RequestOptions
): Promise<ApiResponse<T>>

Example:

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

delete()

Execute a DELETE request.

async delete<T = any>(
  endpoint: string,
  options?: RequestOptions
): Promise<ApiResponse<T>>

Example:

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

Query Builder

query()

Create a query builder for the endpoint.

query(endpoint: string): QueryBuilder

Parameters:

• endpoint (string) - API endpoint path

Returns: QueryBuilder instance

Example:

const response = await api
  .query('/products')
  .where('status', 'active')
  .page(1)
  .limit(20)
  .get();

Session Management

getSessionId()

Get the current session ID.

async getSessionId(): Promise<string | null>

Returns: Promise resolving to session ID or null

Example:

const sessionId = await api.getSessionId();
console.log('Current session:', sessionId);

setSessionId()

Set the session ID.

setSessionId(sessionId: string): void

Parameters:

• sessionId (string) - Session ID to set

Example:

api.setSessionId('new-session-id');

clearSession()

Clear the current session.

clearSession(): void

Example:

api.clearSession();

hasSession()

Check if a session exists.

async hasSession(): Promise<boolean>

Returns: Promise resolving to boolean

Example:

const isAuthenticated = await api.hasSession();

Headers

setHeader()

Set a default header.

setHeader(key: string, value: string): void

Parameters:

• key (string) - Header name
• value (string) - Header value

Example:

api.setHeader('X-API-Key', 'your-api-key');

removeHeader()

Remove a default header.

removeHeader(key: string): void

Parameters:

• key (string) - Header name

Example:

api.removeHeader('X-API-Key');

Interceptors

addRequestInterceptor()

Add a request interceptor.

addRequestInterceptor(
  interceptor: (config: RequestConfig) => Promise<RequestConfig>
): void

Parameters:

• interceptor (function) - Interceptor function

Example:

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

addResponseInterceptor()

Add a response interceptor.

addResponseInterceptor(
  interceptor: (response: ApiResponse<any>) => Promise<ApiResponse<any>>
): void

Parameters:

• interceptor (function) - Interceptor function

Example:

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

Utility Methods

getBaseUrl()

Get the base URL.

getBaseUrl(): string

Returns: Base URL string

Example:

const baseUrl = api.getBaseUrl();

getConfig()

Get the configuration.

getConfig(): FlowfullConfig

Returns: Configuration object

Example:

const config = api.getConfig();

QueryBuilder

The query builder provides a chainable API for building complex queries.

Filtering

where()

Add a filter condition.

where(field: string, value: any): QueryBuilder
where(field: string, operator: string, value: any): QueryBuilder
where(field: string, filterOperator: FilterOperator): QueryBuilder

Parameters:

• field (string) - Field name
• operator (string, optional) - Operator ('eq', 'gt', 'gte', 'lt', 'lte', etc.)
• value (any) - Value to filter by
• filterOperator (FilterOperator) - Filter operator object

Returns: QueryBuilder instance (chainable)

Examples:

// Simple equality
.where('status', 'active')

// With operator
.where('age', 'gte', 18)

// With filter operator
import { gte } from '@pubflow/flowfull-client';
.where('age', gte(18))

filter()

Alias for where() with equality.

filter(field: string, value: any): QueryBuilder

Example:

.filter('status', 'active')

Search

search()

Add full-text search.

search(query: string): QueryBuilder

Parameters:

• query (string) - Search query

Returns: QueryBuilder instance (chainable)

Example:

.search('laptop')

q()

Alias for search().

q(query: string): QueryBuilder

Example:

.q('laptop')

Pagination

page()

Set the page number.

page(page: number): QueryBuilder

Parameters:

• page (number) - Page number (1-based)

Returns: QueryBuilder instance (chainable)

Example:

.page(2)

limit()

Set the number of items per page.

limit(limit: number): QueryBuilder

Parameters:

• limit (number) - Items per page

Returns: QueryBuilder instance (chainable)

Example:

.limit(20)

perPage()

Alias for limit().

perPage(limit: number): QueryBuilder

Example:

.perPage(25)

offset()

Set the offset for pagination.

offset(offset: number): QueryBuilder

Parameters:

• offset (number) - Number of items to skip

Returns: QueryBuilder instance (chainable)

Example:

.offset(50)

Sorting

sort()

Add sorting.

sort(field: string, direction?: 'asc' | 'desc'): QueryBuilder

Parameters:

• field (string) - Field name to sort by
• direction ('asc' | 'desc', optional) - Sort direction (default: 'asc')

Returns: QueryBuilder instance (chainable)

Example:

.sort('price', 'asc')
.sort('created_at', 'desc')

orderBy()

Alias for sort().

orderBy(field: string, direction?: 'asc' | 'desc'): QueryBuilder

Example:

.orderBy('name', 'asc')

Parameters

param()

Add a custom query parameter.

param(key: string, value: any): QueryBuilder

Parameters:

• key (string) - Parameter name
• value (any) - Parameter value

Returns: QueryBuilder instance (chainable)

Example:

.param('include', 'profile')

params()

Add multiple custom query parameters.

params(params: Record<string, any>): QueryBuilder

Parameters:

• params (object) - Parameters object

Returns: QueryBuilder instance (chainable)

Example:

.params({
  include: 'profile,settings',
  fields: 'id,name,email'
})

Headers

header()

Add a custom header.

header(key: string, value: string): QueryBuilder

Parameters:

• key (string) - Header name
• value (string) - Header value

Returns: QueryBuilder instance (chainable)

Example:

.header('X-API-Version', 'v2')

headers()

Add multiple custom headers.

headers(headers: Record<string, string>): QueryBuilder

Parameters:

• headers (object) - Headers object

Returns: QueryBuilder instance (chainable)

Example:

.headers({
  'X-API-Version': 'v2',
  'X-Client-ID': 'web-app'
})

Execution

get()

Execute the query as a GET request.

async get<T = any>(): Promise<ApiResponse<T>>

Returns: Promise resolving to ApiResponse<T>

Example:

const response = await api
  .query('/products')
  .where('status', 'active')
  .get();

post()

Execute the query as a POST request.

async post<T = any>(body?: any): Promise<ApiResponse<T>>

Parameters:

• body (any, optional) - Request body

Returns: Promise resolving to ApiResponse<T>

Example:

const response = await api
  .query('/products')
  .post({ name: 'New Product' });

put()

Execute the query as a PUT request.

async put<T = any>(body?: any): Promise<ApiResponse<T>>

Example:

const response = await api
  .query('/products/123')
  .put({ name: 'Updated Product' });

patch()

Execute the query as a PATCH request.

async patch<T = any>(body?: any): Promise<ApiResponse<T>>

Example:

const response = await api
  .query('/products/123')
  .patch({ status: 'active' });

delete()

Execute the query as a DELETE request.

async delete<T = any>(): Promise<ApiResponse<T>>

Example:

const response = await api
  .query('/products/123')
  .delete();

Utility Methods

toQueryString()

Build the query string.

toQueryString(): string

Returns: Query string

Example:

const queryString = api
  .query('/products')
  .where('status', 'active')
  .page(1)
  .limit(20)
  .toQueryString();
// Returns: "status=active&page=1&limit=20"

toURL()

Build the full URL with query string.

toURL(): string

Returns: Full URL

Example:

const url = api
  .query('/products')
  .where('status', 'active')
  .toURL();
// Returns: "/products?status=active"

build()

Build the query string (alias for toQueryString()).

build(): string

Example:

const queryString = builder.build();

Filter Operators

Flowfull Client provides 14 filter operators for building complex queries.

Comparison Operators

eq()

Equal to.

function eq(value: any): FilterOperator

Example:

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

.where('status', eq('active'))
// Equivalent to: .where('status', 'active')

ne()

Not equal to.

function ne(value: any): FilterOperator

Example:

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

.where('status', ne('deleted'))

gt()

Greater than.

function gt(value: number): FilterOperator

Example:

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

.where('age', gt(18))

gte()

Greater than or equal to.

function gte(value: number): FilterOperator

Example:

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

.where('age', gte(18))

lt()

Less than.

function lt(value: number): FilterOperator

Example:

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

.where('price', lt(100))

lte()

Less than or equal to.

function lte(value: number): FilterOperator

Example:

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

.where('price', lte(100))

String Operators

like()

Case-sensitive pattern matching.

function like(pattern: string): FilterOperator

Example:

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

.where('name', like('%laptop%'))

ilike()

Case-insensitive pattern matching.

function ilike(pattern: string): FilterOperator

Example:

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

.where('name', ilike('%laptop%'))

startsWith()

Starts with pattern.

function startsWith(prefix: string): FilterOperator

Example:

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

.where('name', startsWith('Gaming'))

endsWith()

Ends with pattern.

function endsWith(suffix: string): FilterOperator

Example:

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

.where('email', endsWith('@gmail.com'))

Array Operators

inOp()

Value is in array.

function inOp(values: any[]): FilterOperator

Example:

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

.where('status', inOp(['active', 'verified', 'premium']))

TIP

Named inOp instead of in to avoid conflict with JavaScript's in keyword.

notIn()

Value is not in array.

function notIn(values: any[]): FilterOperator

Example:

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

.where('status', notIn(['deleted', 'banned']))

Null Operators

isNull()

Value is null.

function isNull(): FilterOperator

Example:

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

.where('deleted_at', isNull())

isNotNull()

Value is not null.

function isNotNull(): FilterOperator

Example:

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

.where('verified_at', isNotNull())

Range Operators

between()

Value is between two values (inclusive).

function between(min: number, max: number): FilterOperator

Example:

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

.where('price', between(50, 200))

notBetween()

Value is not between two values.

function notBetween(min: number, max: number): FilterOperator

Example:

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

.where('price', notBetween(50, 200))

Combining Operators

You can combine multiple operators in a single query:

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

const response = await api
  .query('/products')
  .where('price', gte(50))
  .where('price', lte(200))
  .where('category', inOp(['electronics', 'computers']))
  .where('image_url', isNotNull())
  .get();

Types

ApiResponse<T>

Standard API response format.

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;
  };
}

Example:

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

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

FlowfullConfig

Configuration options for the client.

interface FlowfullConfig {
  // Session management
  sessionId?: string;
  getSessionId?: () => Promise<string | null>;
  includeSession?: boolean;
  sessionHeader?: string;
  storage?: StorageAdapter;

  // Headers
  headers?: Record<string, string>;

  // Retry
  retryAttempts?: number;

  // Timeout
  timeout?: number;

  // Callbacks
  onRequest?: (config: RequestConfig) => Promise<void>;
  onResponse?: (response: ApiResponse<any>) => Promise<void>;
  onError?: (error: Error) => void;
}

Example:

const config: FlowfullConfig = {
  sessionId: 'your-session-id',
  headers: {
    'X-API-Version': 'v2'
  },
  retryAttempts: 3,
  timeout: 30000,
  onRequest: async (config) => {
    console.log('Request:', config.url);
  },
  onError: (error) => {
    console.error('Error:', error);
  }
};

RequestOptions

Options for individual requests.

interface RequestOptions {
  params?: Record<string, any>;
  headers?: Record<string, string>;
  timeout?: number;
  includeSession?: boolean;
  signal?: AbortSignal;
}

Example:

const options: RequestOptions = {
  params: { page: 1, limit: 20 },
  headers: { 'X-Custom': 'value' },
  timeout: 5000,
  includeSession: false
};

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

RequestConfig

Internal request configuration.

interface RequestConfig {
  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
  url: string;
  headers: Record<string, string>;
  body?: any;
  timeout?: number;
  signal?: AbortSignal;
}

StorageAdapter

Custom storage adapter interface.

interface StorageAdapter {
  getItem(key: string): Promise<string | null>;
  setItem(key: string, value: string): Promise<void>;
  removeItem(key: string): Promise<void>;
}

Example:

const customStorage: StorageAdapter = {
  async getItem(key) {
    return await myStorage.get(key);
  },
  async setItem(key, value) {
    await myStorage.set(key, value);
  },
  async removeItem(key) {
    await myStorage.delete(key);
  }
};

const api = createFlowfull('https://api.myapp.com', {
  storage: customStorage
});

FilterOperator

Filter operator object.

interface FilterOperator {
  operator: string;
  value: any;
}

Example:

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

const operator: FilterOperator = gte(18);
// { operator: 'gte', value: 18 }

Configuration

Session Management

Auto-Detection

The client automatically detects sessions from storage:

const api = createFlowfull('https://api.myapp.com');
// Searches for: pubflow_session_id, session_id, sessionId, etc.

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');
  }
});

Custom Storage

const api = createFlowfull('https://api.myapp.com', {
  storage: {
    getItem: async (key) => await myStorage.get(key),
    setItem: async (key, value) => await myStorage.set(key, value),
    removeItem: async (key) => await myStorage.delete(key)
  }
});

Sessionless

// Globally
const api = createFlowfull('https://api.myapp.com', {
  includeSession: false
});

// Per-request
const response = await api.get('/public/data', {
  includeSession: false
});

Headers

Default Headers

const api = createFlowfull('https://api.myapp.com', {
  headers: {
    'X-API-Version': 'v2',
    'X-Client-ID': 'web-app'
  }
});

Dynamic Headers

api.setHeader('X-API-Key', 'your-api-key');
api.removeHeader('X-API-Key');

Per-Request Headers

const response = await api.get('/users', {
  headers: {
    'X-Custom': 'value'
  }
});

Retry Configuration

const api = createFlowfull('https://api.myapp.com', {
  retryAttempts: 3  // Retry failed requests up to 3 times
});

Timeout Configuration

// Global timeout
const api = createFlowfull('https://api.myapp.com', {
  timeout: 30000  // 30 seconds
});

// Per-request timeout
const response = await api.get('/users', {
  timeout: 5000  // 5 seconds
});

Callbacks

const api = createFlowfull('https://api.myapp.com', {
  onRequest: async (config) => {
    console.log(`[${config.method}] ${config.url}`);
  },
  onResponse: async (response) => {
    console.log(`Status: ${response.status}`);
  },
  onError: (error) => {
    console.error('Error:', error.message);
  }
});

Interceptors

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

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

Platform Support

Browser

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

// Auto-detects localStorage
const api = createFlowfull('https://api.myapp.com');

React Native

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

// Auto-detects AsyncStorage
const api = createFlowfull('https://api.myapp.com');

Node.js / Bun

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

// Manual session management
const api = createFlowfull('https://api.myapp.com', {
  sessionId: process.env.SESSION_ID
});

Next.js

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

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

// Server-side
const api = createFlowfull('https://api.myapp.com', {
  sessionId: cookies().get('session_id')?.value
});

See Also

• What is it for? - Purpose and use cases
• How to use it - Usage guide
• Tutorial - Step-by-step tutorial
• Examples - Real-world examples