@ram_28/kf-ai-sdk 1.0.0 → 1.0.2

package/README.md

@@ -1,839 +1,481 @@
-# KF AI SDK - Enhanced Business Object Framework
+# @ram_28/kf-ai-sdk
 
-A comprehensive TypeScript SDK for building enterprise applications with sophisticated business rules, role-based access control, and optimized client-side validation. Features complete BDO (Business Data Object) support with rule classification, field permissions, and expression evaluation.
+A type-safe SDK for building modern web applications with React hooks for forms, tables, kanban boards, and filtering.
 
-## 🚀 Latest Enhancements
+## Installation
 
-### ✅ **Complete Rule System (NEW)**
-- **Rule Classification**: Validation (client-side), Computation (server-side), Business Logic (server-side)
-- **Smart Execution**: Automatic determination of client vs server rule execution
-- **Expression Caching**: LRU cache with dependency tracking for optimized performance
-- **BDO Schema Support**: Full compatibility with Business Data Object schemas
+```bash
+npm install @ram_28/kf-ai-sdk
+```
+
+**Peer Dependencies:**
+```bash
+npm install react @tanstack/react-query
+```
 
-### ✅ **Role-Based Field Permissions (NEW)**  
-- **Field-Level Control**: Editable, readable, and hidden field permissions per role
-- **Compile-Time Safety**: TypeScript enforcement of permission boundaries
-- **Dynamic UI**: Automatic form field disable/hide based on permissions
+## Features
 
-### ✅ **Optimized API Integration (NEW)**
-- **POST-Based Operations**: Correct implementation per BDO specification  
-- **Enhanced Count API**: Efficient counting with same payload structure as list
-- **Advanced Filtering**: Complex filter conditions with logical operators
-- **Type-Safe Responses**: Full TypeScript coverage for all operations
+- **Authentication** - Cookie-based auth with AuthProvider and useAuth hook
+- **useForm** - Dynamic schema-driven forms with backend validation
+- **useTable** - Data tables with sorting, pagination, and React Query integration
+- **useKanban** - Kanban board state management with drag-drop support
+- **useFilter** - Advanced filtering with logical operators and payload builders
+- **API Client** - Type-safe CRUD operations with structured filtering and sorting
+- **Type System** - 11 semantic field types (IdField, StringField, CurrencyField, etc.)
+- **Utilities** - Formatting helpers for currency, dates, numbers, and more
 
-### ✅ **Amazon Product Master Implementation (NEW)**
-- **Complete BDO Example**: Full implementation of Amazon Product Master schema
-- **Business Rules**: Auto-calculations, validation, and permission enforcement  
-- **Role-Based Views**: Admin, Seller, Buyer, InventoryManager, WarehouseStaff access levels
-- **Real-World Example**: Production-ready e-commerce product management
+## Quick Start
 
-## 📚 Documentation
+```tsx
+import {
+  // Authentication
+  AuthProvider,
+  useAuth,
+  configureAuth,
+
+  // Hooks
+  useForm,
+  useTable,
+  useKanban,
+  useFilter,
+
+  // API
+  api,
+  setApiBaseUrl,
+
+  // Utilities
+  formatCurrency,
+  formatDate
+} from '@ram_28/kf-ai-sdk';
+
+// Configure API base URL
+setApiBaseUrl('https://api.example.com');
+```
 
-- **[Implementation Guide](./IMPLEMENTATION_GUIDE.md)** - Comprehensive setup and usage guide
-- **[Quick Reference](./QUICK_REFERENCE.md)** - Developer cheat sheet and API reference
-- **[Examples](./examples/)** - Real-world usage examples including Amazon Product demo
+## Authentication
 
-## Architecture Overview
+The SDK provides a complete authentication solution with cookie-based session management.
 
-The KF AI SDK is built on a clear separation between reusable SDK core and user-configurable application logic:
+### Setup
 
-### 🔧 SDK Core (`sdk/`)
+Wrap your app with `AuthProvider` inside a `QueryClientProvider`:
 
-**Fixed, Reusable Components**
+```tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { AuthProvider, setApiBaseUrl, configureAuth } from '@ram_28/kf-ai-sdk';
+
+// Configure API
+setApiBaseUrl('https://api.example.com');
+
+// Optional: customize auth settings
+configureAuth({
+  defaultProvider: 'google',
+  autoRedirect: true,
+  providers: {
+    google: {
+      loginPath: '/api/auth/google/login',
+      logoutPath: '/api/auth/logout',
+    },
+  },
+});
 
-- **Types**: 11 Backend BO field types (IdField, StringField, CurrencyField, etc.)
-- **API Client**: Runtime CRUD operations with structured filtering and sorting
-- **Utilities**: Validation and formatting helpers
-- **Components**: React hooks for forms and tables (Phase 2)
+const queryClient = new QueryClient();
 
-### 🏗️ App Layer (`app/`)
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <AuthProvider
+        loadingComponent={<div>Loading...</div>}
+        onAuthChange={(status, user) => console.log('Auth:', status, user)}
+      >
+        <MyApp />
+      </AuthProvider>
+    </QueryClientProvider>
+  );
+}
+```
 
-**User-Configurable Business Logic**
+### useAuth Hook
 
-- **Roles**: User-defined role system (Admin, Manager, User, etc.)
-- **Sources**: Business object definitions (Product, Order, etc.)
-- **Role-based Access**: Type-safe field visibility per role
-- **AI-readable Contracts**: Single source of truth for code generation
+Access authentication state and operations in any component:
 
-### 📁 Project Structure
+```tsx
+import { useAuth } from '@ram_28/kf-ai-sdk';
 
-```
-kf-ai-sdk/
-├── sdk/                    # Fixed SDK core
-│   ├── types/              # Field types and common interfaces
-│   ├── api/                # API client and utilities
-│   ├── utils/              # Validation and formatting
-│   └── index.ts            # SDK exports
-├── app/                    # User-configurable layer
-│   ├── types/roles.ts      # Role definitions
-│   ├── sources/            # Business objects
-│   └── index.ts            # App exports
-├── config/                 # Development configuration
-└── examples/               # Usage examples
-```
+function UserMenu() {
+  const { user, isAuthenticated, isLoading, logout, hasRole } = useAuth();
 
-## Quick Start
+  if (isLoading) return <div>Loading...</div>;
+  if (!isAuthenticated) return null;
 
-### Usage Example
+  return (
+    <div>
+      <span>Welcome, {user._name}</span>
+      <span>Role: {user.Role}</span>
 
-```tsx
-// 1. Import SDK core utilities
-import { api, formatCurrency, isValidCurrencyField } from "./sdk";
+      {hasRole('Admin') && <a href="/admin">Admin Dashboard</a>}
 
-// 2. Import app-specific business logic  
-import { Order, Roles, AdminOrder } from "./app";
+      <button onClick={() => logout({ redirectUrl: '/' })}>
+        Logout
+      </button>
+    </div>
+  );
+}
+```
 
-// 3. Use together for type-safe operations
-const order = new Order(Roles.Admin);
-const orderData = await order.list();
+### useAuth Return Values
 
-// SDK utilities work with app types
-const isValid = isValidCurrencyField(orderData.Data[0].totalAmount);
-const formatted = formatCurrency(orderData.Data[0].totalAmount);
+```tsx
+const {
+  // User state
+  user,              // UserDetails | null
+  staticBaseUrl,     // string | null
+  buildId,           // string | null
+  status,            // 'loading' | 'authenticated' | 'unauthenticated'
+  isAuthenticated,   // boolean
+  isLoading,         // boolean
+
+  // Operations
+  login,             // (provider?, options?) => void
+  logout,            // (options?) => Promise<void>
+  refreshSession,    // () => Promise<SessionResponse | null>
+  hasRole,           // (role: string) => boolean
+  hasAnyRole,        // (roles: string[]) => boolean
+
+  // Error handling
+  error,             // Error | null
+  clearError,        // () => void
+} = useAuth();
+```
 
-function AdminOrderManagement() {
-  // Type-safe order client with role-based access
-  const order = new Order(Roles.Admin);
+### Multiple Auth Providers
 
-  // Table with automatic type inference
-  const table = useTable<AdminOrder>({
-    source: "orders",
-    enableSorting: true,
-    enablePagination: true,
-  });
+```tsx
+import { useAuth } from '@ram_28/kf-ai-sdk';
 
-  // Form with backend-driven validation
-  const form = useForm<AdminOrder>({
-    source: "order-validation",
-    operation: "create",
-    onSuccess: () => table.refetch(),
-  });
+function LoginPage() {
+  const { login } = useAuth();
 
   return (
     <div>
-      {/* Create Form */}
-      <form onSubmit={form.handleSubmit()}>
-        <input {...form.register("customerId")} placeholder="Customer ID" />
-        <input {...form.register("totalAmount")} placeholder="Total Amount" type="number" />
-        <input {...form.register("profitMargin")} placeholder="Profit Margin" type="number" />{" "}
-        {/* Admin can see profit margin */}
-        <button type="submit">Create Order</button>
-      </form>
-
-      {/* Orders Table */}
-      <table>
-        <thead>
-          <tr>
-            <th>ID</th>
-            <th>Customer</th>
-            <th>Amount</th>
-            <th>Profit Margin</th> {/* Admin can see profit margin */}
-            <th>Actions</th>
-          </tr>
-        </thead>
-        <tbody>
-          {table.rows.map((order: AdminOrder) => (
-            <tr key={order._id}>
-              <td>{order._id}</td>
-              <td>{order.customerId}</td>
-              <td>${order.totalAmount}</td>
-              <td>{order.profitMargin}%</td>{" "}
-              {/* TypeScript knows this exists for Admin */}
-              <td>
-                <button onClick={() => order.delete(order._id)}>Delete</button>
-              </td>
-            </tr>
-          ))}
-        </tbody>
-      </table>
+      <button onClick={() => login('google')}>
+        Continue with Google
+      </button>
+      <button onClick={() => login('microsoft')}>
+        Continue with Microsoft
+      </button>
     </div>
   );
 }
 ```
 
-### Role-Based Access Control
+### Protected Routes
 
 ```tsx
-// User gets limited access to the same data
-import { Order, Roles, UserOrder } from "@ram_28/kf-ai-sdk";
+import { useAuth } from '@ram_28/kf-ai-sdk';
+import { Navigate } from 'react-router-dom';
+
+function ProtectedRoute({ children, requiredRoles }) {
+  const { isAuthenticated, isLoading, hasAnyRole } = useAuth();
+
+  if (isLoading) return <div>Loading...</div>;
+  if (!isAuthenticated) return <Navigate to="/login" />;
+  if (requiredRoles && !hasAnyRole(requiredRoles)) {
+    return <Navigate to="/unauthorized" />;
+  }
+
+  return children;
+}
 
-function UserOrderList() {
-  const order = new Order(Roles.User);
+// Usage
+<ProtectedRoute requiredRoles={['Admin', 'Manager']}>
+  <AdminDashboard />
+</ProtectedRoute>
+```
+
+## Hooks
+
+### useTable
+
+Data table hook with sorting, pagination, and React Query integration.
+
+```tsx
+import { useTable } from '@ram_28/kf-ai-sdk';
 
-  const table = useTable<UserOrder>({
-    source: "orders",
+function ProductTable() {
+  const table = useTable({
+    source: 'products',
     enableSorting: true,
+    enablePagination: true,
+    pageSize: 25,
   });
 
   return (
     <table>
       <thead>
         <tr>
-          <th>ID</th>
-          <th>Customer</th>
-          <th>Amount</th>
-          {/* <th>Profit Margin</th> */} {/* User cannot see profit margin */}
+          <th onClick={() => table.toggleSort('name')}>Name</th>
+          <th onClick={() => table.toggleSort('price')}>Price</th>
         </tr>
       </thead>
       <tbody>
-        {table.rows.map((order: UserOrder) => (
-          <tr key={order._id}>
-            <td>{order._id}</td>
-            <td>{order.customerId}</td>
-            <td>${order.totalAmount}</td>
-            {/* <td>{order.profitMargin}%</td> */}{" "}
-            {/* ❌ TypeScript Error: Property doesn't exist */}
+        {table.rows.map((product) => (
+          <tr key={product._id}>
+            <td>{product.name}</td>
+            <td>${product.price}</td>
           </tr>
         ))}
       </tbody>
+      <tfoot>
+        <button onClick={table.previousPage} disabled={!table.hasPreviousPage}>
+          Previous
+        </button>
+        <span>Page {table.currentPage}</span>
+        <button onClick={table.nextPage} disabled={!table.hasNextPage}>
+          Next
+        </button>
+      </tfoot>
     </table>
   );
 }
 ```
 
-### Runtime API Operations
+### useForm
+
+Schema-driven form hook with backend validation support.
 
 ```tsx
-import { api } from "./sdk";
-
-// Runtime CRUD operations
-async function orderOperations() {
-  // Get single order by ID
-  const order = await api("order").get("ORDER_123");
-
-  // Create new order (with optional custom ID)
-  const createResponse = await api("order").create({
-    _id: "ORDER_456", // Optional custom ID
-    customerId: "CUST_001",
-    totalAmount: 299.99,
-    status: "pending",
+import { useForm } from '@ram_28/kf-ai-sdk';
+
+function ProductForm() {
+  const form = useForm({
+    source: 'products',
+    operation: 'create',
+    onSuccess: (data) => {
+      console.log('Created:', data);
+    },
   });
-  console.log(createResponse._id); // "ORDER_456"
 
-  // Update order (partial updates supported)
-  const updateResponse = await api("order").update("ORDER_123", {
-    status: "completed",
-    totalAmount: 325.50,
-  });
+  return (
+    <form onSubmit={form.handleSubmit()}>
+      <input {...form.register('name')} placeholder="Product Name" />
+      {form.errors.name && <span>{form.errors.name.message}</span>}
 
-  // Delete order
-  const deleteResponse = await api("order").delete("ORDER_123");
-  console.log(deleteResponse.status); // "success"
+      <input {...form.register('price')} type="number" placeholder="Price" />
+      {form.errors.price && <span>{form.errors.price.message}</span>}
 
-  // List orders with structured filtering and sorting
-  const ordersList = await api("order").list({
-    Filter: {
-      Operator: "AND",
-      Condition: [
-        {
-          Operator: "EQ",
-          LHSField: "status", 
-          RHSValue: "pending"
-        },
-        {
-          Operator: "GTE",
-          LHSField: "totalAmount",
-          RHSValue: 100
-        }
-      ]
-    },
-    Sort: [
-      { Field: "_created_at", Order: "DESC" },
-      { Field: "totalAmount", Order: "ASC" }
-    ],
-    Page: 1,
-    PageSize: 50
-  });
+      <button type="submit" disabled={form.isSubmitting}>
+        {form.isSubmitting ? 'Creating...' : 'Create Product'}
+      </button>
+    </form>
+  );
 }
 ```
 
-## Advanced Filtering and Sorting Examples
-
-The KF AI SDK supports comprehensive filtering and sorting through the Runtime API. Here are detailed examples using both Order and Product models:
+### useKanban
 
-### Basic Filtering Examples
+Kanban board state management with drag-drop support.
 
 ```tsx
-import { Order, Product, Roles } from "./app";
-
-// Simple equality filter
-const completedOrders = await new Order(Roles.Admin).list({
-  Filter: {
-    Operator: "AND",
-    Condition: [
-      {
-        Operator: "EQ",
-        LHSField: "status",
-        RHSValue: "completed"
-      }
-    ]
-  }
-});
-
-// Numeric range filter
-const highValueOrders = await new Order(Roles.Admin).list({
-  Filter: {
-    Operator: "AND",
-    Condition: [
-      {
-        Operator: "GTE",
-        LHSField: "totalAmount",
-        RHSValue: 500
-      }
-    ]
-  }
-});
+import { useKanban, Kanban, KanbanColumn, KanbanCard } from '@ram_28/kf-ai-sdk';
+
+function TaskBoard() {
+  const kanban = useKanban({
+    source: 'tasks',
+    groupByField: 'status',
+    columns: [
+      { id: 'todo', title: 'To Do' },
+      { id: 'in-progress', title: 'In Progress' },
+      { id: 'done', title: 'Done' },
+    ],
+  });
 
-// String contains filter
-const electronicsProducts = await new Product(Roles.Admin).list({
-  Filter: {
-    Operator: "AND",
-    Condition: [
-      {
-        Operator: "Contains",
-        LHSField: "description",
-        RHSValue: "electronic"
-      }
-    ]
-  }
-});
+  return (
+    <Kanban>
+      {kanban.columns.map((column) => (
+        <KanbanColumn key={column.id} column={column}>
+          {column.cards.map((card) => (
+            <KanbanCard key={card.id} card={card}>
+              {card.title}
+            </KanbanCard>
+          ))}
+        </KanbanColumn>
+      ))}
+    </Kanban>
+  );
+}
 ```
 
-### Complex Multi-Condition Filters
-
-```tsx
-// AND conditions - all must be true
-const premiumCompletedOrders = await new Order(Roles.Admin).list({
-  Filter: {
-    Operator: "AND",
-    Condition: [
-      {
-        Operator: "EQ",
-        LHSField: "status",
-        RHSValue: "completed"
-      },
-      {
-        Operator: "GTE",
-        LHSField: "totalAmount",
-        RHSValue: 1000
-      },
-      {
-        Operator: "GTE",
-        LHSField: "profitMargin",
-        RHSValue: 20
-      }
-    ]
-  }
-});
-
-// OR conditions - any can be true
-const urgentOrders = await new Order(Roles.Admin).list({
-  Filter: {
-    Operator: "OR",
-    Condition: [
-      {
-        Operator: "EQ",
-        LHSField: "status",
-        RHSValue: "pending"
-      },
-      {
-        Operator: "EQ",
-        LHSField: "status",
-        RHSValue: "processing"
-      }
-    ]
-  }
-});
-
-// Nested AND/OR conditions
-const complexProductFilter = await new Product(Roles.Admin).list({
-  Filter: {
-    Operator: "AND",
-    Condition: [
-      {
-        Operator: "EQ",
-        LHSField: "inStock",
-        RHSValue: true
-      },
-      {
-        Operator: "OR",
-        Condition: [
-          {
-            Operator: "EQ",
-            LHSField: "category",
-            RHSValue: "electronics"
-          },
-          {
-            Operator: "EQ",
-            LHSField: "category",
-            RHSValue: "clothing"
-          }
-        ]
-      },
-      {
-        Operator: "Between",
-        LHSField: "price",
-        RHSValue: [50, 500]
-      }
-    ]
-  }
-});
-```
+### useFilter
 
-### Advanced Filter Operators
+Advanced filtering with logical operators.
 
 ```tsx
-// Range queries
-const midRangeProducts = await new Product(Roles.Admin).list({
-  Filter: {
-    Operator: "AND",
-    Condition: [
-      {
-        Operator: "Between",
-        LHSField: "price",
-        RHSValue: [100, 1000]
-      }
-    ]
-  }
-});
-
-// List membership
-const specificCategories = await new Product(Roles.Admin).list({
-  Filter: {
-    Operator: "AND",
-    Condition: [
-      {
-        Operator: "IN",
-        LHSField: "category",
-        RHSValue: ["electronics", "books", "sports"]
-      }
-    ]
-  }
-});
-
-// Exclusion filters
-const nonCancelledOrders = await new Order(Roles.Admin).list({
-  Filter: {
-    Operator: "AND",
-    Condition: [
-      {
-        Operator: "NE",
-        LHSField: "status",
-        RHSValue: "cancelled"
-      }
-    ]
-  }
-});
-
-// Empty/Non-empty checks
-const ordersWithNotes = await new Order(Roles.Admin).list({
-  Filter: {
-    Operator: "AND",
-    Condition: [
-      {
-        Operator: "NotEmpty",
-        LHSField: "internalNotes"
-      }
-    ]
-  }
-});
-
-// String length validation
-const detailedProducts = await new Product(Roles.Admin).list({
-  Filter: {
-    Operator: "AND",
-    Condition: [
-      {
-        Operator: "MinLength",
-        LHSField: "description",
-        RHSValue: 50
-      }
-    ]
-  }
-});
-```
-
-### Comprehensive Sorting Examples
-
-```tsx
-// Single field sorting
-const ordersByDate = await new Order(Roles.Admin).list({
-  Sort: [
-    { Field: "_created_at", Order: "DESC" }
-  ]
-});
+import { useFilter, buildFilterPayload } from '@ram_28/kf-ai-sdk';
+
+function ProductFilter() {
+  const filter = useFilter({
+    fields: {
+      name: { type: 'string' },
+      price: { type: 'number' },
+      category: { type: 'select', options: ['electronics', 'clothing', 'books'] },
+    },
+  });
 
-// Multi-field sorting
-const productsCatalog = await new Product(Roles.Admin).list({
-  Sort: [
-    { Field: "category", Order: "ASC" },    // First by category
-    { Field: "price", Order: "DESC" },      // Then by price (high to low)
-    { Field: "name", Order: "ASC" }         // Finally by name
-  ]
-});
+  const handleApply = () => {
+    const payload = buildFilterPayload(filter.conditions);
+    // Use payload with API
+  };
 
-// Sorting with filtering
-const topSellingProducts = await new Product(Roles.Admin).list({
-  Filter: {
-    Operator: "AND",
-    Condition: [
-      {
-        Operator: "EQ",
-        LHSField: "inStock",
-        RHSValue: true
-      },
-      {
-        Operator: "GTE",
-        LHSField: "price",
-        RHSValue: 100
-      }
-    ]
-  },
-  Sort: [
-    { Field: "margin", Order: "DESC" },
-    { Field: "price", Order: "ASC" }
-  ]
-});
+  return (
+    <div>
+      <button onClick={() => filter.addCondition('name', 'contains', '')}>
+        Add Name Filter
+      </button>
+      <button onClick={() => filter.addCondition('price', 'gte', 0)}>
+        Add Price Filter
+      </button>
+      <button onClick={handleApply}>Apply Filters</button>
+    </div>
+  );
+}
 ```
 
-### Pagination with Filtering and Sorting
-
-```tsx
-// Complete query with all features
-const paginatedResults = await new Order(Roles.Admin).list({
-  // Complex filtering
-  Filter: {
-    Operator: "AND",
-    Condition: [
-      {
-        Operator: "GTE",
-        LHSField: "totalAmount",
-        RHSValue: 200
-      },
-      {
-        Operator: "OR",
-        Condition: [
-          {
-            Operator: "EQ",
-            LHSField: "status",
-            RHSValue: "completed"
-          },
-          {
-            Operator: "EQ",
-            LHSField: "status",
-            RHSValue: "pending"
-          }
-        ]
-      }
-    ]
-  },
-  // Multi-field sorting
-  Sort: [
-    { Field: "totalAmount", Order: "DESC" },
-    { Field: "_created_at", Order: "DESC" }
-  ],
-  // Pagination
-  Page: 1,
-  PageSize: 25,
-  // Specific fields only (optional)
-  Field: ["_id", "customerId", "totalAmount", "status", "_created_at"]
-});
-
-// Process results
-console.log(`Found ${paginatedResults.Data.length} orders`);
-paginatedResults.Data.forEach(order => {
-  console.log(`Order ${order._id}: $${order.totalAmount} - ${order.status}`);
-});
-```
+## API Client
 
-### Role-Based Query Examples
+Type-safe API client for CRUD operations.
 
 ```tsx
-// Admin can see all fields and use sensitive filters
-const adminProductAnalysis = await new Product(Roles.Admin).list({
-  Filter: {
-    Operator: "AND",
-    Condition: [
-      {
-        Operator: "GTE",
-        LHSField: "margin",        // Admin-only field
-        RHSValue: 25
-      },
-      {
-        Operator: "Contains",
-        LHSField: "supplier",      // Admin-only field
-        RHSValue: "Premium"
-      }
-    ]
-  },
-  Sort: [
-    { Field: "margin", Order: "DESC" },
-    { Field: "cost", Order: "ASC" }     // Admin-only field
-  ]
-});
-
-// User sees limited data and can only filter on public fields
-const userProducts = await new Product(Roles.User).list({
-  Filter: {
-    Operator: "AND",
-    Condition: [
-      {
-        Operator: "EQ",
-        LHSField: "category",      // Public field
-        RHSValue: "electronics"
-      },
-      {
-        Operator: "EQ",
-        LHSField: "inStock",       // Public field
-        RHSValue: true
-      }
-    ]
-  },
-  Sort: [
-    { Field: "price", Order: "ASC" },    // Public field
-    { Field: "name", Order: "ASC" }      // Public field
-  ]
-});
+import { api, setApiBaseUrl } from '@ram_28/kf-ai-sdk';
 
-// Note: User cannot filter by margin, cost, or supplier - those fields don't exist in UserProduct type
-```
+// Configure base URL
+setApiBaseUrl('https://api.example.com');
 
-### Real-World Query Patterns
+// CRUD Operations
+async function productOperations() {
+  // Get single record
+  const product = await api('products').get('PROD_123');
 
-```tsx
-// E-commerce product search
-async function searchProducts(searchTerm: string, category?: string, maxPrice?: number) {
-  const conditions = [
-    {
-      Operator: "EQ" as const,
-      LHSField: "inStock",
-      RHSValue: true
-    }
-  ];
-
-  if (searchTerm) {
-    conditions.push({
-      Operator: "Contains" as const,
-      LHSField: "name",
-      RHSValue: searchTerm
-    });
-  }
+  // Create record
+  const created = await api('products').create({
+    name: 'New Product',
+    price: 99.99,
+    category: 'electronics',
+  });
 
-  if (category) {
-    conditions.push({
-      Operator: "EQ" as const,
-      LHSField: "category",
-      RHSValue: category
-    });
-  }
+  // Update record
+  const updated = await api('products').update('PROD_123', {
+    price: 89.99,
+  });
 
-  if (maxPrice) {
-    conditions.push({
-      Operator: "LTE" as const,
-      LHSField: "price",
-      RHSValue: maxPrice
-    });
-  }
+  // Delete record
+  await api('products').delete('PROD_123');
 
-  return new Product(Roles.User).list({
+  // List with filtering and sorting
+  const products = await api('products').list({
     Filter: {
-      Operator: "AND",
-      Condition: conditions
+      Operator: 'AND',
+      Condition: [
+        { Operator: 'EQ', LHSField: 'category', RHSValue: 'electronics' },
+        { Operator: 'GTE', LHSField: 'price', RHSValue: 50 },
+      ],
     },
     Sort: [
-      { Field: "name", Order: "ASC" }
+      { Field: 'price', Order: 'DESC' },
     ],
-    PageSize: 20
+    Page: 1,
+    PageSize: 25,
   });
-}
-
-// Order dashboard with filters
-async function getOrderDashboard(dateRange: { start: string, end: string }, minAmount?: number) {
-  const conditions = [
-    {
-      Operator: "Between" as const,
-      LHSField: "_created_at",
-      RHSValue: [dateRange.start, dateRange.end]
-    }
-  ];
-
-  if (minAmount) {
-    conditions.push({
-      Operator: "GTE" as const,
-      LHSField: "totalAmount",
-      RHSValue: minAmount
-    });
-  }
 
-  return new Order(Roles.Admin).list({
+  // Count records
+  const count = await api('products').count({
     Filter: {
-      Operator: "AND",
-      Condition: conditions
+      Operator: 'AND',
+      Condition: [
+        { Operator: 'EQ', LHSField: 'inStock', RHSValue: true },
+      ],
     },
-    Sort: [
-      { Field: "totalAmount", Order: "DESC" },
-      { Field: "_created_at", Order: "DESC" }
-    ],
-    PageSize: 50
   });
 }
 ```
 
-## Documentation
-
-## Development Setup
+## Type System
 
-### Prerequisites
-- Node.js 18+
-- npm or yarn
+The SDK provides semantic field types for type-safe data modeling:
 
-### Installation
-```bash
-# Clone or download the SDK template
-git clone kf-ai-sdk my-project
-cd my-project
-
-# Install dependencies
-npm install
-
-# Start development server
-npm run dev
-```
-
-### Development Commands
-```bash
-npm run dev          # Start development server
-npm run build        # Build for production
-npm run typecheck    # Run TypeScript checks
-npm run lint         # Run ESLint
-npm run format       # Format code with Prettier
-npm run test         # Run tests
+```tsx
+import type {
+  IdField,
+  StringField,
+  TextAreaField,
+  NumberField,
+  BooleanField,
+  DateField,
+  DateTimeField,
+  CurrencyField,
+  PercentageField,
+  SelectField,
+} from '@ram_28/kf-ai-sdk';
+
+// Define your data types
+interface Product {
+  _id: IdField;
+  name: StringField<string>;
+  description: TextAreaField;
+  price: CurrencyField;
+  quantity: NumberField<0>;
+  inStock: BooleanField;
+  category: SelectField<'electronics' | 'clothing' | 'books'>;
+  createdAt: DateTimeField;
+}
 ```
 
-### Configuration
-The SDK uses configuration files in the `config/` directory:
-- `tsconfig.json` - TypeScript configuration with path mapping
-- `vite.config.js` - Build and development server config
-- `eslint.config.js` - Code linting rules
-- `prettier.config.js` - Code formatting rules
-
-### Layer Documentation
-
-- **[SDK Core](docs/sdk-core.md)** - Field types, API client, and utilities
-- **[App Layer](docs/app-layer.md)** - Roles and business object creation
-- **[Examples](docs/examples.md)** - Usage patterns and best practices
-
-### Migration Guide
-
-- **[Migration Guide](MIGRATION.md)** - Upgrading from the previous structure
-
-## Features
-
-### SDK Core (`sdk/`)
-
-- ✅ **Field Type System** - 11 Backend BO field types with semantic meaning
-- ✅ **Runtime API Client** - Full CRUD operations with structured filtering
-- ✅ **Datetime Handling** - Automatic encoding/decoding of API formats
-- ✅ **Validation Utilities** - Runtime type checking and field validation
-- ✅ **Formatting Helpers** - Display formatting for all field types
-- ✅ **TypeScript Support** - Full type safety across all operations
-
-### App Layer (`app/`)
-
-- ✅ **Role-Based Access Control** - Compile-time enforcement of field visibility
-- ✅ **AI Code Generation** - Single source of truth for AI-readable contracts
-- ✅ **Dynamic Business Objects** - User-configurable source definitions
-- ✅ **Custom Role System** - User-defined role hierarchies
-- ✅ **Type Safety** - TypeScript validation of all generated code
-- ✅ **Single File Per Source** - All logic for a data model in one place
-
-### Development Experience
-
-- ✅ **Modern Build Tools** - Vite, TypeScript, ESLint, Prettier
-- ✅ **Path Mapping** - Clean imports with `@sdk/` and `@app/` aliases
-- ✅ **Hot Reload** - Fast development with instant feedback
-- ✅ **Type Checking** - Comprehensive TypeScript validation
-- ✅ **Code Quality** - Automated linting and formatting
-
-## Key Benefits
-
-### For AI Code Generation
-
-- **Single Source of Truth**: App layer provides all type definitions in one place
-- **Role Awareness**: AI generates code that respects user permissions
-- **Type Safety**: Any TypeScript error indicates incorrect AI generation
-- **Self-Documenting**: Type definitions serve as API documentation
-
-### For Developers
+## Utilities
 
-- **Three-Layer Architecture**: Clear separation of concerns
-- **Role-Based Security**: Compile-time enforcement of data access
-- **Modern React**: Hooks, React Query, and TypeScript throughout
-- **Extensible**: Easy to add new data sources and roles
+### Formatting
 
-### For Applications
-
-- **Performance**: React Query caching and background updates
-- **Reliability**: Type-safe operations prevent runtime errors
-- **Scalability**: Consistent patterns across all data operations
-- **Maintainability**: Single file per data model, clear structure
-
-## Example: AI-Generated Admin Page
+```tsx
+import {
+  formatCurrency,
+  formatDate,
+  formatDateTime,
+  formatNumber,
+  formatPercentage
+} from '@ram_28/kf-ai-sdk';
+
+formatCurrency(99.99);           // "$99.99"
+formatDate(new Date());          // "Jan 11, 2024"
+formatDateTime(new Date());      // "Jan 11, 2024, 10:30 AM"
+formatNumber(1234.56, 2);        // "1,234.56"
+formatPercentage(0.156);         // "15.6%"
+```
 
-When AI generates an admin page for "Order Management", it reads the App layer and produces:
+### Class Names
 
 ```tsx
-import { Order, Roles, AdminOrder } from "@ram_28/kf-ai-sdk";
-import { useTable, useForm } from "@ram_28/kf-ai-sdk";
+import { cn } from '@ram_28/kf-ai-sdk';
 
-// AI generates type-safe code based on role
-function AdminOrderManagement() {
-  const order = new Order(Roles.Admin); // Type-safe role
+// Merge Tailwind classes with conflict resolution
+cn('px-4 py-2', 'px-6');  // "py-2 px-6"
+cn('text-red-500', condition && 'text-blue-500');
+```
 
-  const table = useTable<AdminOrder>({
-    source: "orders",
-    enableSorting: true,
-  });
+## Documentation
 
-  return (
-    <table>
-      <thead>
-        <tr>
-          <th>ID</th>
-          <th>Customer</th>
-          <th>Total Amount</th> {/* Admin can see financial data */}
-          <th>Profit Margin</th> {/* Admin can see profit */}
-          <th>Internal Notes</th> {/* Admin can see internal notes */}
-        </tr>
-      </thead>
-      <tbody>
-        {table.rows.map((order: AdminOrder) => (
-          <tr key={order._id}>
-            <td>{order._id}</td>
-            <td>{order.customerId}</td>
-            <td>${order.totalAmount}</td>{" "}
-            {/* ✅ TypeScript knows this exists */}
-            <td>{order.profitMargin}%</td> {/* ✅ TypeScript knows this exists */}
-            <td>{order.internalNotes}</td>{" "}
-            {/* ✅ TypeScript knows this exists */}
-          </tr>
-        ))}
-      </tbody>
-    </table>
-  );
-}
+Detailed documentation for each feature:
 
-// If AI tries to generate user code that accesses admin fields:
-function UserOrderList() {
-  const order = new Order(Roles.User);
-  const data = await order.get("123");
+- [Authentication Documentation](./docs/useAuth.md)
+- [useForm Documentation](./docs/useForm.md)
+- [useTable Documentation](./docs/useTable.md)
+- [useKanban Documentation](./docs/useKanban.md)
+- [useFilter Documentation](./docs/useFilter.md)
+- [Quick Reference](./docs/QUICK_REFERENCE.md)
 
-  return <div>{data.profitMargin}</div>; // ❌ TypeScript Error!
-  // Property 'profitMargin' does not exist on type 'UserOrder'
-}
-```
+## Requirements
 
-**The AI sees the TypeScript error and automatically regenerates correct code.**
+- Node.js >= 18.0.0
+- React >= 16.8.0
+- @tanstack/react-query >= 5.0.0
 
 ## License