Hooks API Reference

Complete reference for all hooks available in Flowfull Client packages.

useAuth

Access authentication state and methods.

Available in: @pubflow/react, @pubflow/react-native, @pubflow/nextjs

Signature

typescript

function useAuth(instanceId?: string): UseAuthResult

Parameters

Parameter	Type	Description
`instanceId`	`string` (optional)	Pubflow instance ID for multi-instance setups

Return Value

typescript

interface UseAuthResult {
  user: User | null;
  isAuthenticated: boolean;
  isLoading: boolean;
  login: (credentials: LoginCredentials) => Promise<any>;
  logout: () => Promise<void>;
  validateSession: () => Promise<SessionValidationResult>;
  refreshUser?: () => Promise<User | null>; // React Native only
}

interface LoginCredentials {
  email?: string;
  userName?: string;
  password: string;
}

interface SessionValidationResult {
  isValid: boolean;
  expiresAt?: string;
  user?: User;
}

Example

typescript

import { useAuth } from '@pubflow/react';

function Profile() {
  const { user, isAuthenticated, isLoading, login, logout } = useAuth();
  
  if (isLoading) return <div>Loading...</div>;
  if (!isAuthenticated) return <div>Not authenticated</div>;
  
  return (
    <div>
      <h1>{user?.name}</h1>
      <button onClick={logout}>Logout</button>
    </div>
  );
}

useBridgeApi

Create a Bridge API service for making API calls.

Available in: @pubflow/react, @pubflow/react-native, @pubflow/nextjs

Signature

typescript

function useBridgeApi<T extends EntityData>(
  config: EntityConfig,
  instanceId?: string
): BridgeApiService<T>

Parameters

Parameter	Type	Description
`config`	`EntityConfig`	Entity configuration with endpoint
`instanceId`	`string` (optional)	Pubflow instance ID

typescript

interface EntityConfig {
  endpoint: string;
  customEndpoints?: Record<string, string>;
}

Return Value

Returns a BridgeApiService<T> instance with methods:

getList(params?: QueryParams): Promise<PaginatedResponse<T>>
getById(id: string, params?: QueryParams): Promise<T>
search(params: SearchParams): Promise<PaginatedResponse<T>>
create(data: Partial<T>): Promise<T>
update(id: string, data: Partial<T>): Promise<T>
delete(id: string): Promise<void>

Example

typescript

import { useBridgeApi } from '@pubflow/react';

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

function MyComponent() {
  const userService = useBridgeApi<User>({
    endpoint: 'users'
  });
  
  // Use with useBridgeQuery or useBridgeMutation
}

useBridgeQuery

Query data with automatic caching and revalidation using SWR.

Available in: @pubflow/react, @pubflow/react-native, @pubflow/nextjs

Signature

typescript

function useBridgeQuery<T extends EntityData, Q extends QueryType>(
  service: BridgeApiService<T>,
  type: Q,
  params: BridgeQueryParams<Q>,
  config?: SWRConfiguration
): UseBridgeQueryResult<T, Q>

Parameters

Parameter	Type	Description
`service`	`BridgeApiService<T>`	Bridge API service from useBridgeApi
`type`	`'list' \| 'get' \| 'search'`	Query type
`params`	`BridgeQueryParams<Q>`	Query parameters (depends on type)
`config`	`SWRConfiguration` (optional)	SWR configuration options

typescript

// Query parameters by type
type BridgeQueryParams<T> =
  T extends 'list' ? QueryParams :
  T extends 'get' ? { id: string; params?: QueryParams } :
  T extends 'search' ? SearchParams :
  never;

interface QueryParams {
  page?: number;
  limit?: number;
  orderBy?: string;
  orderDir?: 'asc' | 'desc';
}

interface SearchParams extends QueryParams {
  q: string;
  entity?: string;
}

Return Value

typescript

interface UseBridgeQueryResult<T, Q> {
  data: Q extends 'list' | 'search' ? T[] : T | null;
  meta: Q extends 'list' | 'search' ? PaginationMeta : null;
  isLoading: boolean;
  error: Error | null;
  refetch: () => Promise<void>;
}

interface PaginationMeta {
  page: number;
  limit: number;
  total: number;
  hasMore: boolean;
}

Example

typescript

import { useBridgeApi, useBridgeQuery } from '@pubflow/react';

function UserList() {
  const userService = useBridgeApi({ endpoint: 'users' });
  
  const { data, meta, isLoading, error, refetch } = useBridgeQuery(
    userService,
    'list',
    { page: 1, limit: 20, orderBy: 'name' }
  );
  
  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  
  return (
    <div>
      <ul>
        {data?.map(user => (
          <li key={user.id}>{user.name}</li>
        ))}
      </ul>
      <p>Total: {meta?.total}</p>
    </div>
  );
}

useBridgeMutation

Mutate data (create, update, delete) with automatic cache invalidation.

Available in: @pubflow/react, @pubflow/react-native, @pubflow/nextjs

Signature

typescript

function useBridgeMutation<T extends EntityData, M extends MutationType>(
  service: BridgeApiService<T>,
  type: M,
  defaultOptions?: MutationOptions
): UseBridgeMutationResult<T, M>

Parameters

Parameter	Type	Description
`service`	`BridgeApiService<T>`	Bridge API service from useBridgeApi
`type`	`'create' \| 'update' \| 'delete'`	Mutation type
`defaultOptions`	`MutationOptions` (optional)	Default mutation options

typescript

interface MutationOptions {
  onSuccess?: (data: any) => void;
  onError?: (error: Error) => void;
  invalidateCache?: boolean; // Default: true
}

Return Value

typescript

interface UseBridgeMutationResult<T, M> {
  mutate: (params: MutationParams<T, M>, options?: MutationOptions) => Promise<MutationResult<T, M>>;
  isLoading: boolean;
  error: Error | null;
  reset: () => void;
}

type MutationParams<T, M> =
  M extends 'create' ? { data: Partial<T> } :
  M extends 'update' ? { id: string; data: Partial<T> } :
  M extends 'delete' ? { id: string } :
  never;

interface MutationResult<T, M> {
  success: boolean;
  data?: M extends 'delete' ? void : T;
  error?: string;
}

Example

typescript

import { useBridgeApi, useBridgeMutation } from '@pubflow/react';

function CreateUser() {
  const userService = useBridgeApi({ endpoint: 'users' });
  const { mutate: createUser, isLoading, error } = useBridgeMutation(
    userService,
    'create'
  );
  
  async function handleSubmit(formData: any) {
    const result = await createUser(
      { data: formData },
      {
        onSuccess: (data) => console.log('Created:', data),
        onError: (error) => console.error('Error:', error)
      }
    );
  }
  
  return <form onSubmit={handleSubmit}>...</form>;
}

useBridgeCrud

Combined hook for complete CRUD operations (list, create, update, delete).

Available in: @pubflow/react, @pubflow/react-native, @pubflow/nextjs

Signature

typescript

function useBridgeCrud<T extends EntityData>(
  config: EntityConfig,
  queryParams?: QueryParams,
  instanceId?: string
): UseBridgeCrudResult<T>

Parameters

Parameter	Type	Description
`config`	`EntityConfig`	Entity configuration with endpoint
`queryParams`	`QueryParams` (optional)	Default query parameters for list
`instanceId`	`string` (optional)	Pubflow instance ID

Return Value

typescript

interface UseBridgeCrudResult<T> {
  data: T[];
  meta: PaginationMeta | null;
  isLoading: boolean;
  error: Error | null;
  create: (data: Partial<T>) => Promise<T>;
  update: (id: string, data: Partial<T>) => Promise<T>;
  remove: (id: string) => Promise<void>;
  refetch: () => Promise<void>;
}

Example

typescript

import { useBridgeCrud } from '@pubflow/react';

function UserManagement() {
  const {
    data: users,
    isLoading,
    create,
    update,
    remove,
    refetch
  } = useBridgeCrud({ endpoint: 'users' }, { limit: 20 });

  async function handleCreate(userData: any) {
    await create(userData);
    refetch();
  }

  async function handleUpdate(id: string, userData: any) {
    await update(id, userData);
    refetch();
  }

  async function handleDelete(id: string) {
    if (confirm('Delete user?')) {
      await remove(id);
      refetch();
    }
  }

  return <div>{/* Your UI */}</div>;
}

useSearchQueryBuilder

Build complex search queries with filters.

Available in: @pubflow/react, @pubflow/nextjs

Signature

typescript

function useSearchQueryBuilder(): SearchQueryBuilder

Return Value

typescript

interface SearchQueryBuilder {
  query: SearchQuery;
  addFilter: (field: string, operator: FilterOperator, value: any) => void;
  removeFilter: (field: string) => void;
  clearFilters: () => void;
  setQuery: (q: string) => void;
  setPage: (page: number) => void;
  setLimit: (limit: number) => void;
  setOrderBy: (field: string, direction: 'asc' | 'desc') => void;
  reset: () => void;
}

type FilterOperator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'ilike' | 'in' | 'nin' | 'null' | 'nnull';

interface SearchQuery {
  q?: string;
  filters?: Record<string, { operator: FilterOperator; value: any }>;
  page?: number;
  limit?: number;
  orderBy?: string;
  orderDir?: 'asc' | 'desc';
}

Example

typescript

import { useSearchQueryBuilder, useBridgeApi, useBridgeQuery } from '@pubflow/react';

function AdvancedUserSearch() {
  const queryBuilder = useSearchQueryBuilder();
  const userService = useBridgeApi({ endpoint: 'users' });

  const { data, isLoading } = useBridgeQuery(
    userService,
    'search',
    queryBuilder.query
  );

  return (
    <div>
      <input
        onChange={(e) => queryBuilder.setQuery(e.target.value)}
        placeholder="Search..."
      />
      <select onChange={(e) => queryBuilder.addFilter('userType', 'eq', e.target.value)}>
        <option value="">All Types</option>
        <option value="admin">Admin</option>
        <option value="user">User</option>
      </select>
      <button onClick={queryBuilder.clearFilters}>Clear Filters</button>

      {isLoading ? (
        <div>Loading...</div>
      ) : (
        <ul>
          {data?.map(user => (
            <li key={user.id}>{user.name}</li>
          ))}
        </ul>
      )}
    </div>
  );
}

useAuthGuard

Authentication guard with automatic redirects for protected pages.

Available in: @pubflow/react

Signature

typescript

function useAuthGuard(options?: UseAuthGuardOptions): UseAuthGuardResult

Parameters

typescript

interface UseAuthGuardOptions {
  validateOnMount?: boolean; // Default: true
  allowedTypes?: string[]; // Default: ['authenticated']
  instanceId?: string;
  onRedirect?: (path: string, reason: RedirectReason) => void;
  onSessionExpired?: () => void;
  loginRedirectPath?: string; // Default: '/login'
  accessDeniedPath?: string; // Default: '/access-denied'
  enableLogging?: boolean; // Default: false
}

type RedirectReason = 'unauthenticated' | 'unauthorized' | 'session-expired';

Return Value

typescript

interface UseAuthGuardResult {
  user: User | null;
  isAuthenticated: boolean;
  isLoading: boolean;
  isAuthorized: boolean;
  validateSession: () => Promise<SessionValidationResult>;
  redirectReason: RedirectReason | null;
}

Example

typescript

import { useAuthGuard } from '@pubflow/react';
import { useNavigate } from 'react-router-dom';

function AdminPage() {
  const navigate = useNavigate();

  const { isLoading, isAuthorized } = useAuthGuard({
    allowedTypes: ['admin', 'superadmin'],
    onRedirect: (path, reason) => {
      navigate(path);
    }
  });

  if (isLoading) return <div>Loading...</div>;
  if (!isAuthorized) return null; // Will redirect

  return <div>Admin Content</div>;
}

Next Steps

Components API - Component reference
Types API - TypeScript types reference
Utilities API - Utility functions reference

Hooks API Reference ​

useAuth ​

Signature ​

Parameters ​

Return Value ​

Example ​

useBridgeApi ​

Signature ​

Parameters ​

Return Value ​

Example ​

useBridgeQuery ​

Signature ​

Parameters ​

Return Value ​

Example ​

useBridgeMutation ​

Signature ​

Parameters ​

Return Value ​

Example ​

useBridgeCrud ​

Signature ​

Parameters ​

Return Value ​

Example ​

useSearchQueryBuilder ​

Signature ​

Return Value ​

Example ​

useAuthGuard ​

Signature ​

Parameters ​

Return Value ​

Example ​

Next Steps ​

Hooks API Reference

useAuth

Signature

Parameters

Return Value

Example

useBridgeApi

Signature

Parameters

Return Value

Example

useBridgeQuery

Signature

Parameters

Return Value

Example

useBridgeMutation

Signature

Parameters

Return Value

Example

useBridgeCrud

Signature

Parameters

Return Value

Example

useSearchQueryBuilder

Signature

Return Value

Example

useAuthGuard

Signature

Parameters

Return Value

Example

Next Steps