PubFlow

A standardized API integration system for Next.js applications. This library provides components for API handling, authentication, and CRUD operations with the Bridge API pattern.

Features

• API Client: Standardized API request handling with session management
• Authentication: User authentication and route protection
• Bridge API: Reusable CRUD operations for API endpoints
• Validation: Zod-based validation utilities

Installation

# If you're using npm
npm install @pubflow/next

# If you're using yarn
yarn add @pubflow/next

# If you're using bun
bun add @pubflow/next

Usage

API Client

import { api } from '@pubflow/next';

// Make a GET request
const response = await api.get('/users');

// Make a POST request
const createResponse = await api.post('/users', { name: 'John Doe' });

// Make a PUT request
const updateResponse = await api.put('/users/123', { name: 'Jane Doe' });

// Make a DELETE request
const deleteResponse = await api.delete('/users/123');

Authentication

// In your _app.tsx or layout.tsx
import { AuthProvider } from 'pubflow';

function MyApp({ Component, pageProps }) {
  return (
    <AuthProvider>
      <Component {...pageProps} />
    </AuthProvider>
  );
}

// In your components
import { useAuth } from '@pubflow/next';

function ProfilePage() {
  const { user, isLoading, logout } = useAuth();
  
  if (isLoading) return <div>Loading...</div>;
  
  return (
    <div>
      <h1>Welcome, {user?.name}</h1>
      <button onClick={logout}>Logout</button>
    </div>
  );
}

// Protect routes
import { RouteGuard } from '@pubflow/next';

function AdminPage() {
  return (
    <RouteGuard allowedTypes={['admin', 'superadmin']}>
      <div>Admin content</div>
    </RouteGuard>
  );
}

Bridge API

import { useBridgeCrud } from '@pubflow/next';
import { z } from 'zod';

// Define validation schema
const userSchema = z.object({
  id: z.string(),
  name: z.string().min(2),
  email: z.string().email(),
  role: z.enum(['user', 'admin']),
});

function UserList() {
  const { 
    items, 
    loading, 
    error, 
    createItem, 
    updateItem, 
    deleteItem,
    searchTerm,
    setSearchTerm
  } = useBridgeCrud({
    entityConfig: {
      endpoint: 'users'
    },
    schemas: {
      entity: userSchema
    },
    successMessages: {
      create: 'User created successfully',
      update: 'User updated successfully',
      delete: 'User deleted successfully'
    }
  });
  
  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;
  
  return (
    <div>
      <input 
        type="text" 
        value={searchTerm} 
        onChange={(e) => setSearchTerm(e.target.value)}
        placeholder="Search users..."
      />
      
      <ul>
        {items.map(user => (
          <li key={user.id}>
            {user.name} ({user.email})
            <button onClick={() => deleteItem(user.id)}>Delete</button>
          </li>
        ))}
      </ul>
      
      <button onClick={() => createItem({ name: 'New User', email: '[email protected]', role: 'user' })}>
        Add User
      </button>
    </div>
  );
}

Validation

import { validateWithZod, showValidationErrors } from 'pubflow';
import { z } from 'zod';

// Define validation schema
const formSchema = z.object({
  name: z.string().min(2, 'Name must be at least 2 characters'),
  email: z.string().email('Invalid email address'),
  age: z.number().min(18, 'Must be at least 18 years old')
});

// Validate data
function handleSubmit(data) {
  const validation = validateWithZod(formSchema, data);
  
  if (!validation.success) {
    showValidationErrors(validation.errors || {});
    return;
  }
  
  // Proceed with valid data
  const validData = validation.data;
  // ...
}

Documentation

For more detailed documentation, see the following guides:

• Getting Started Guide - Start here for a complete walkthrough
• Example Project Structure - See a full project example
• [Route Protection] (./test/@pubflow-next/docs/route-protection-guide.md) - Protect routes based on user types

Session Validation

The package includes a configurable session validation feature that ensures user sessions are regularly validated and automatically redirects users to the login page when their session expires:

// Configure session validation
const PUBFLOW_CONFIG = {
  API_URL: 'https://api.example.com',
  sessionConfig: {
    validationInterval: 10 * 60 * 1000, // 10 minutes
    validationEndpoint: '/validation',  // Endpoint for validation
    autoValidate: true                  // Enable automatic validation
  }
};

// Make the configuration available to @pubflow/next
window.__PUBFLOW_CONFIG = PUBFLOW_CONFIG;

For more details, see the Session Validation Guide.