@taruvi/refine-providers 1.0.6 → 1.0.7

package/README.md

@@ -20,7 +20,6 @@ import {
   accessControlProvider,
 } from "@taruvi/refine-providers";
 
-// Initialize the Taruvi client
 const client = new Client({
   apiKey: "your-api-key",
   appSlug: "your-app-slug",
@@ -44,17 +43,47 @@ function App() {
 }
 ```
 
-## Data Providers
+---
+
+## Exports
+
+```typescript
+// Data Providers
+import { dataProvider } from "@taruvi/refine-providers";           // Database CRUD
+import { storageDataProvider } from "@taruvi/refine-providers";    // File storage
+import { functionsDataProvider } from "@taruvi/refine-providers";  // Edge functions
+import { appDataProvider } from "@taruvi/refine-providers";        // App data (roles)
+import { analyticsDataProvider } from "@taruvi/refine-providers";  // Analytics queries
+
+// Auth Providers
+import { authProvider } from "@taruvi/refine-providers";           // Authentication
+import { accessControlProvider } from "@taruvi/refine-providers";  // Cerbos permissions
+
+// Types
+import type {
+  TaruviMeta,
+  TaruviListResponse,
+  TaruviUser,
+  StorageUploadVariables,
+  FunctionMeta,
+  AnalyticsMeta,
+} from "@taruvi/refine-providers";
+
+// SDK re-exports
+import { Client, Auth, Policy, Functions, App, Analytics } from "@taruvi/refine-providers";
+```
+
+---
 
-This package includes multiple specialized data providers:
+## Data Providers Overview
 
-| Provider | Purpose | SDK Class |
-|----------|---------|-----------|
-| `dataProvider` | Database CRUD operations | `Database` |
-| `storageDataProvider` | File storage operations | `Storage` |
-| `functionsDataProvider` | Edge function execution | `Functions` |
-| `appDataProvider` | App-level data (roles) | `App` |
-| `analyticsDataProvider` | Analytics queries | `Analytics` |
+| Provider | Purpose | Hook | Resource Parameter |
+|----------|---------|------|-------------------|
+| `dataProvider` | Database CRUD | `useList`, `useOne`, `useCreate`, `useUpdate`, `useDelete` | Table name |
+| `storageDataProvider` | File storage | `useList`, `useCreate`, `useDelete` | Bucket name |
+| `functionsDataProvider` | Edge functions | `useCustom` | Function slug |
+| `appDataProvider` | App roles | `useList` | `"roles"` |
+| `analyticsDataProvider` | Analytics queries | `useCustom` | Query slug |
 
 ---
 
@@ -62,130 +91,229 @@ This package includes multiple specialized data providers:
 
 The main data provider for CRUD operations on database tables.
 
-### Basic Usage
+### Setup
 
-```tsx
+```typescript
 import { dataProvider, Client } from "@taruvi/refine-providers";
 
 const client = new Client({ apiKey, appSlug, baseUrl });
 
-<Refine
-  dataProvider={dataProvider(client)}
-  resources={[{ name: "posts" }]}
-/>
+<Refine dataProvider={dataProvider(client)} />
 ```
 
-### Supported Operations
+### Operations
 
-All standard Refine CRUD operations are supported:
+| Method | HTTP | Endpoint |
+|--------|------|----------|
+| `getList` | GET | `/api/apps/{app}/datatables/{table}/data/` |
+| `getOne` | GET | `/api/apps/{app}/datatables/{table}/data/{id}/` |
+| `getMany` | GET | `/api/apps/{app}/datatables/{table}/data/?id__in=1,2,3` |
+| `create` | POST | `/api/apps/{app}/datatables/{table}/data/` |
+| `update` | PATCH | `/api/apps/{app}/datatables/{table}/data/{id}/` |
+| `deleteOne` | DELETE | `/api/apps/{app}/datatables/{table}/data/{id}/` |
 
-```tsx
-// List records
-const { data } = useList({ resource: "posts" });
+### Usage Examples
 
-// Get single record
-const { data } = useOne({ resource: "posts", id: 1 });
+#### List Records
 
-// Get multiple records
-const { data } = useMany({ resource: "posts", ids: [1, 2, 3] });
+```typescript
+import { useList } from "@refinedev/core";
 
-// Create record
-const { mutate } = useCreate();
-mutate({ resource: "posts", values: { title: "Hello" } });
+const { data, isLoading } = useList({
+  resource: "users",
+  pagination: { currentPage: 1, pageSize: 10 },
+  filters: [
+    { field: "status", operator: "eq", value: "active" },
+    { field: "age", operator: "gte", value: 18 },
+  ],
+  sorters: [
+    { field: "created_at", order: "desc" },
+  ],
+  meta: {
+    populate: ["department", "manager"],
+  },
+});
 
-// Update record
-const { mutate } = useUpdate();
-mutate({ resource: "posts", id: 1, values: { title: "Updated" } });
+// Returns: { data: User[], total: number }
+```
 
-// Delete record
-const { mutate } = useDelete();
-mutate({ resource: "posts", id: 1 });
+#### Get Single Record
+
+```typescript
+import { useOne } from "@refinedev/core";
+
+const { data } = useOne({
+  resource: "users",
+  id: 123,
+  meta: {
+    populate: ["department"],
+  },
+});
+
+// Returns: { data: User }
 ```
 
-### Filtering
+#### Get Multiple Records
 
-Full support for Refine filter operators:
+```typescript
+import { useMany } from "@refinedev/core";
 
-```tsx
-const { data } = useList({
-  resource: "posts",
-  filters: [
-    { field: "status", operator: "eq", value: "published" },
-    { field: "views", operator: "gte", value: 100 },
-    { field: "title", operator: "contains", value: "refine" },
-    { field: "category", operator: "in", value: ["tech", "news"] },
-  ],
+const { data } = useMany({
+  resource: "users",
+  ids: [1, 2, 3],
 });
+
+// Returns: { data: User[] }
 ```
 
-**Supported Operators:**
+#### Create Record
 
-| Operator | Description | Example |
-|----------|-------------|---------|
-| `eq` | Equal | `status = "active"` |
-| `ne` | Not equal | `status != "deleted"` |
-| `lt`, `gt`, `lte`, `gte` | Comparison | `age >= 18` |
-| `contains`, `ncontains` | Contains (case-sensitive) | `title contains "hello"` |
-| `containss`, `ncontainss` | Contains (case-insensitive) | `title icontains "hello"` |
-| `startswith`, `endswith` | String matching | `email endswith "@gmail.com"` |
-| `in`, `nin` | Array membership | `status in ["active", "pending"]` |
-| `null`, `nnull` | Null checks | `deleted_at is null` |
-| `between`, `nbetween` | Range | `price between [10, 100]` |
+```typescript
+import { useCreate } from "@refinedev/core";
 
-### Sorting & Pagination
+const { mutate } = useCreate();
 
-```tsx
-const { data } = useList({
-  resource: "posts",
-  sorters: [
-    { field: "created_at", order: "desc" },
-    { field: "title", order: "asc" },
-  ],
-  pagination: {
-    currentPage: 1,
-    pageSize: 20,
+mutate({
+  resource: "users",
+  values: {
+    name: "John Doe",
+    email: "john@example.com",
   },
 });
 ```
 
-### Meta Options
+#### Update Record
 
-Use the `meta` parameter for Taruvi-specific features:
+```typescript
+import { useUpdate } from "@refinedev/core";
 
-```tsx
-const { data } = useList({
+const { mutate } = useUpdate();
+
+mutate({
+  resource: "users",
+  id: 123,
+  values: {
+    name: "Jane Doe",
+  },
+});
+```
+
+#### Delete Record
+
+```typescript
+import { useDelete } from "@refinedev/core";
+
+const { mutate } = useDelete();
+
+mutate({
+  resource: "users",
+  id: 123,
+});
+```
+
+### Meta Options
+
+```typescript
+useList({
   resource: "posts",
   meta: {
-    // Override table name (when resource differs from table)
-    tableName: "blog_posts",
+    tableName: "blog_posts",              // Override table name
+    populate: ["author", "comments.user"], // FK population (array or string)
+    select: ["id", "title", "status"],    // Field selection
+    idColumnName: "post_id",              // Custom ID column
+    aggregate: ["sum(views)", "count(*)"], // Aggregations
+    groupBy: ["category"],                // Group by
+    having: [{ field: "sum(views)", operator: "gte", value: 100 }],
+  },
+});
+```
+
+### Filtering
+
+All Refine filter operators are supported:
+
+| Operator | Query Parameter | Example |
+|----------|-----------------|---------|
+| `eq` | `field=value` | `status=active` |
+| `ne` | `field__ne=value` | `status__ne=deleted` |
+| `lt`, `gt`, `lte`, `gte` | `field__lt=value` | `age__gte=18` |
+| `contains` | `field__contains=value` | `name__contains=john` |
+| `containss` | `field__icontains=value` | `name__icontains=John` (case-insensitive) |
+| `startswith` | `field__startswith=value` | `code__startswith=PRE` |
+| `endswith` | `field__endswith=value` | `email__endswith=@gmail.com` |
+| `in` | `field__in=a,b,c` | `status__in=active,pending` |
+| `nin` | `field__nin=a,b` | `status__nin=deleted` |
+| `null` | `field__null=true` | `deleted_at__null=true` |
+| `nnull` | `field__nnull=true` | `email__nnull=true` |
+| `between` | `field__between=min,max` | `price__between=10,100` |
+
+```typescript
+useList({
+  resource: "products",
+  filters: [
+    { field: "status", operator: "eq", value: "active" },
+    { field: "price", operator: "between", value: [10, 100] },
+    { field: "category_id", operator: "in", value: [1, 2, 3] },
+    { field: "name", operator: "containss", value: "phone" },
+    { field: "deleted_at", operator: "null", value: true },
+  ],
+});
+```
+
+### Sorting
 
-    // Populate foreign key relations
-    populate: ["author", "category"],
-    // or populate all: populate: "*"
+```typescript
+useList({
+  resource: "posts",
+  sorters: [
+    { field: "created_at", order: "desc" },  // -created_at
+    { field: "title", order: "asc" },        // title
+  ],
+});
+// Query: ?ordering=-created_at,title
+```
 
-    // Select specific fields
-    select: ["id", "title", "status"],
+### Pagination
 
-    // Custom ID column
-    idColumnName: "post_id",
+```typescript
+useList({
+  resource: "users",
+  pagination: {
+    currentPage: 2,
+    pageSize: 25,
   },
 });
+// Query: ?page=2&page_size=25
+
+// Disable pagination
+useList({
+  resource: "users",
+  pagination: { mode: "off" },
+});
 ```
 
-### Aggregations
+### Populate (Foreign Key Relations)
 
-Support for aggregate queries with grouping:
+Populate uses the SDK's `.populate()` method:
 
-```tsx
-const { data } = useList({
-  resource: "orders",
-  meta: {
-    aggregate: ["sum(total)", "count(*)", "avg(quantity)"],
-    groupBy: ["status", "category"],
-    having: [
-      { field: "sum(total)", operator: "gte", value: 1000 },
-    ],
-  },
+```typescript
+// Array format
+useList({
+  resource: "posts",
+  meta: { populate: ["author", "category"] },
+});
+
+// Nested relations
+useList({
+  resource: "posts",
+  meta: { populate: ["author", "comments.user"] },
+});
+
+// String format
+useOne({
+  resource: "posts",
+  id: 1,
+  meta: { populate: "author,comments.user" },
 });
 ```
 
@@ -197,10 +325,8 @@ For file upload, download, and management operations.
 
 ### Setup
 
-```tsx
-import { storageDataProvider, Client } from "@taruvi/refine-providers";
-
-const client = new Client({ apiKey, appSlug, baseUrl });
+```typescript
+import { storageDataProvider } from "@taruvi/refine-providers";
 
 <Refine
   dataProvider={{
@@ -210,24 +336,30 @@ const client = new Client({ apiKey, appSlug, baseUrl });
 />
 ```
 
+**Note:** In storage operations, `resource` = bucket name, `id` = file path.
+
 ### List Files
 
-```tsx
+```typescript
 const { data } = useList({
-  resource: "documents", // bucket name
+  resource: "documents",  // bucket name
   dataProviderName: "storage",
+  filters: [
+    { field: "mimetype_category", operator: "eq", value: "image" },
+    { field: "size", operator: "lte", value: 5242880 },  // 5MB
+  ],
 });
 ```
 
 ### Upload Files
 
-```tsx
+```typescript
 import { useCreate } from "@refinedev/core";
 import type { StorageUploadVariables } from "@taruvi/refine-providers";
 
 const { mutate } = useCreate<any, any, StorageUploadVariables>();
 
-// Single file upload
+// Single file
 mutate({
   resource: "documents",
   dataProviderName: "storage",
@@ -250,33 +382,38 @@ mutate({
 });
 ```
 
+### Download/Get File
+
+```typescript
+const { data } = useOne({
+  resource: "documents",
+  dataProviderName: "storage",
+  id: "folder/myfile.pdf",  // file path
+});
+```
+
 ### Delete Files
 
-```tsx
+```typescript
+import { useDeleteMany } from "@refinedev/core";
+
 const { mutate } = useDeleteMany();
 
 mutate({
   resource: "documents",
   dataProviderName: "storage",
-  ids: ["path/to/file1.pdf", "path/to/file2.pdf"],
+  ids: ["file1.pdf", "folder/file2.pdf"],
 });
 ```
 
-### Filter Files
+### StorageUploadVariables Interface
 
-```tsx
-const { data } = useList({
-  resource: "documents",
-  dataProviderName: "storage",
-  filters: [
-    { field: "mimetype_category", operator: "eq", value: "image" },
-    { field: "size", operator: "lte", value: 5242880 }, // 5MB
-    { field: "visibility", operator: "eq", value: "public" },
-  ],
-  meta: {
-    bucketName: "uploads", // Override bucket name
-  },
-});
+```typescript
+interface StorageUploadVariables {
+  files: File[];                         // Required: File objects
+  paths?: string[];                      // Optional: Custom paths (defaults to file.name)
+  metadatas?: Record<string, unknown>[]; // Optional: Metadata for each file
+}
 ```
 
 ---
@@ -287,8 +424,8 @@ For executing Taruvi edge functions.
 
 ### Setup
 
-```tsx
-import { functionsDataProvider, Client } from "@taruvi/refine-providers";
+```typescript
+import { functionsDataProvider } from "@taruvi/refine-providers";
 
 <Refine
   dataProvider={{
@@ -300,23 +437,77 @@ import { functionsDataProvider, Client } from "@taruvi/refine-providers";
 
 ### Execute Function
 
-```tsx
+Use `useCustom` with the function slug as the URL:
+
+```typescript
 import { useCustom } from "@refinedev/core";
 
-const { data } = useCustom({
+// Query style (immediate execution)
+const { data, isLoading } = useCustom({
   dataProviderName: "functions",
-  url: "my-function-slug",
+  url: "process-order",  // function slug
   method: "post",
   config: {
     payload: {
-      param1: "value1",
-      param2: 123,
+      orderId: 123,
+      action: "confirm",
     },
   },
   meta: {
-    async: false, // Set to true for async execution
+    async: false,  // Set to true for async execution
   },
 });
+
+if (isLoading) {
+  console.log("Executing function...");
+}
+```
+
+### Mutation Style
+
+```typescript
+import { useCustomMutation } from "@refinedev/core";
+
+const { mutate, isLoading } = useCustomMutation();
+
+mutate({
+  dataProviderName: "functions",
+  url: "send-notification",
+  method: "post",
+  values: { userId: 456, message: "Hello" },
+});
+```
+
+### With Callbacks
+
+```typescript
+mutate(
+  {
+    dataProviderName: "functions",
+    url: "send-notification",
+    method: "post",
+    values: { userId: 456, message: "Hello" },
+  },
+  {
+    onSuccess: (data) => console.log("Result:", data),
+    onError: (error) => console.error("Failed:", error),
+  }
+);
+```
+
+### Async Execution
+
+```typescript
+// Long-running task - returns immediately with job ID
+const { data } = useCustom({
+  dataProviderName: "functions",
+  url: "long-running-task",
+  method: "post",
+  config: {
+    payload: { taskId: 789 },
+  },
+  meta: { async: true },
+});
 ```
 
 ---
@@ -327,8 +518,8 @@ For fetching app-level data like roles.
 
 ### Setup
 
-```tsx
-import { appDataProvider, Client } from "@taruvi/refine-providers";
+```typescript
+import { appDataProvider } from "@taruvi/refine-providers";
 
 <Refine
   dataProvider={{
@@ -340,10 +531,12 @@ import { appDataProvider, Client } from "@taruvi/refine-providers";
 
 ### Fetch Roles
 
-```tsx
+```typescript
+import { useList } from "@refinedev/core";
+
 const { data } = useList({
-  resource: "roles",
   dataProviderName: "app",
+  resource: "roles",
 });
 
 // Returns: { data: [{ id, name, permissions, ... }], total: number }
@@ -357,8 +550,8 @@ For executing predefined analytics queries.
 
 ### Setup
 
-```tsx
-import { analyticsDataProvider, Client } from "@taruvi/refine-providers";
+```typescript
+import { analyticsDataProvider } from "@taruvi/refine-providers";
 
 <Refine
   dataProvider={{
@@ -368,14 +561,17 @@ import { analyticsDataProvider, Client } from "@taruvi/refine-providers";
 />
 ```
 
-### Execute Analytics Query
+### Execute Query
 
-```tsx
+Use `useCustom` with the query slug as the URL:
+
+```typescript
 import { useCustom } from "@refinedev/core";
 
-const { data } = useCustom({
+// Query style (immediate execution)
+const { data, isLoading } = useCustom({
   dataProviderName: "analytics",
-  url: "monthly-sales-report", // query slug
+  url: "monthly-sales-report",  // query slug
   method: "post",
   config: {
     payload: {
@@ -385,6 +581,42 @@ const { data } = useCustom({
     },
   },
 });
+
+if (isLoading) {
+  console.log("Running query...");
+}
+```
+
+### Mutation Style
+
+```typescript
+import { useCustomMutation } from "@refinedev/core";
+
+const { mutate, isLoading } = useCustomMutation();
+
+mutate({
+  dataProviderName: "analytics",
+  url: "dashboard-metrics",
+  method: "post",
+  values: { period: "last_30_days" },
+});
+```
+
+### With Callbacks
+
+```typescript
+mutate(
+  {
+    dataProviderName: "analytics",
+    url: "dashboard-metrics",
+    method: "post",
+    values: { period: "last_30_days" },
+  },
+  {
+    onSuccess: (data) => console.log("Result:", data),
+    onError: (error) => console.error("Failed:", error),
+  }
+);
 ```
 
 ---
@@ -395,19 +627,15 @@ Redirect-based authentication using Taruvi's Web UI Flow.
 
 ### Setup
 
-```tsx
-import { authProvider, Client } from "@taruvi/refine-providers";
-
-const client = new Client({ apiKey, appSlug, baseUrl });
+```typescript
+import { authProvider } from "@taruvi/refine-providers";
 
-<Refine
-  authProvider={authProvider(client)}
-/>
+<Refine authProvider={authProvider(client)} />
 ```
 
 ### Login
 
-```tsx
+```typescript
 import { useLogin } from "@refinedev/core";
 
 const { mutate: login } = useLogin();
@@ -418,7 +646,7 @@ login({ callbackUrl: "/dashboard" });
 
 ### Logout
 
-```tsx
+```typescript
 import { useLogout } from "@refinedev/core";
 
 const { mutate: logout } = useLogout();
@@ -426,9 +654,9 @@ const { mutate: logout } = useLogout();
 logout({ callbackUrl: "/login" });
 ```
 
-### Register/Signup
+### Register
 
-```tsx
+```typescript
 import { useRegister } from "@refinedev/core";
 
 const { mutate: register } = useRegister();
@@ -438,7 +666,7 @@ register({ callbackUrl: "/welcome" });
 
 ### Get Current User
 
-```tsx
+```typescript
 import { useGetIdentity } from "@refinedev/core";
 import type { TaruviUser } from "@taruvi/refine-providers";
 
@@ -448,9 +676,21 @@ console.log(user?.username);
 console.log(user?.email);
 ```
 
-### Check Permissions
+### Check Authentication
 
-```tsx
+```typescript
+import { useIsAuthenticated } from "@refinedev/core";
+
+const { data } = useIsAuthenticated();
+
+if (data?.authenticated) {
+  // User is logged in
+}
+```
+
+### Get Permissions
+
+```typescript
 import { usePermissions } from "@refinedev/core";
 
 const { data: permissions } = usePermissions();
@@ -459,6 +699,19 @@ console.log(permissions?.roles);
 console.log(permissions?.is_staff);
 ```
 
+### TaruviUser Interface
+
+```typescript
+interface TaruviUser {
+  user_id: number;
+  username: string;
+  email?: string;
+  exp?: number;       // Token expiration
+  iat?: number;       // Token issued at
+  [key: string]: unknown;
+}
+```
+
 ---
 
 ## Access Control Provider
@@ -467,8 +720,8 @@ Resource-based authorization using Cerbos policies.
 
 ### Setup
 
-```tsx
-import { accessControlProvider, Client } from "@taruvi/refine-providers";
+```typescript
+import { accessControlProvider } from "@taruvi/refine-providers";
 
 <Refine
   authProvider={authProvider(client)}
@@ -478,7 +731,7 @@ import { accessControlProvider, Client } from "@taruvi/refine-providers";
 
 ### Check Permissions
 
-```tsx
+```typescript
 import { useCan } from "@refinedev/core";
 
 const { data } = useCan({
@@ -500,6 +753,15 @@ import { CanAccess } from "@refinedev/core";
 <CanAccess resource="posts" action="delete" params={{ id: 1 }}>
   <DeleteButton />
 </CanAccess>
+
+// With fallback
+<CanAccess
+  resource="admin"
+  action="view"
+  fallback={<p>Access denied</p>}
+>
+  <AdminPanel />
+</CanAccess>
 ```
 
 ### Define Entity Type
@@ -512,7 +774,7 @@ For Cerbos, specify the entity type in resource meta:
     {
       name: "posts",
       meta: {
-        entityType: "blog", // Used in Cerbos policy
+        entityType: "blog",  // Used in Cerbos policy
       },
     },
   ]}
@@ -523,7 +785,7 @@ For Cerbos, specify the entity type in resource meta:
 
 ## Multiple Data Providers
 
-Use multiple providers together:
+Use all providers together:
 
 ```tsx
 import {
@@ -533,6 +795,8 @@ import {
   functionsDataProvider,
   appDataProvider,
   analyticsDataProvider,
+  authProvider,
+  accessControlProvider,
 } from "@taruvi/refine-providers";
 
 const client = new Client({ apiKey, appSlug, baseUrl });
@@ -545,27 +809,42 @@ const client = new Client({ apiKey, appSlug, baseUrl });
     app: appDataProvider(client),
     analytics: analyticsDataProvider(client),
   }}
+  authProvider={authProvider(client)}
+  accessControlProvider={accessControlProvider(client)}
 />
 
-// Then specify which provider to use:
-useList({ resource: "posts" }); // Uses default
-useList({ resource: "images", dataProviderName: "storage" });
-useCustom({ url: "process", dataProviderName: "functions", method: "post" });
+// Usage:
+useList({ resource: "posts" });                                     // default
+useList({ resource: "images", dataProviderName: "storage" });       // storage
+useList({ resource: "roles", dataProviderName: "app" });            // app
+
+// Functions and Analytics use useCustom
+const { data: funcResult } = useCustom({
+  dataProviderName: "functions",
+  url: "my-func",
+  method: "post",
+  config: { payload: { key: "value" } },
+});
+
+const { data: analyticsResult } = useCustom({
+  dataProviderName: "analytics",
+  url: "my-query",
+  method: "post",
+  config: { payload: { period: "last_30_days" } },
+});
 ```
 
 ---
 
 ## TypeScript Types
 
-All types are exported for TypeScript users:
-
-```tsx
+```typescript
 import type {
   // Meta types
   TaruviMeta,
   TaruviListResponse,
-  AnalyticsMeta,
   FunctionMeta,
+  AnalyticsMeta,
   StorageUploadVariables,
 
   // Auth types
@@ -582,13 +861,26 @@ import type {
 } from "@taruvi/refine-providers";
 ```
 
+### TaruviMeta Interface
+
+```typescript
+interface TaruviMeta {
+  tableName?: string;              // Override table name
+  bucketName?: string;             // Override bucket name
+  populate?: string | string[];    // FK population
+  select?: string | string[];      // Field selection
+  idColumnName?: string;           // Custom ID column
+  aggregate?: string[];            // Aggregation expressions
+  groupBy?: string[];              // Group by fields
+  having?: CrudFilter[];           // Having clause
+}
+```
+
 ---
 
 ## SDK Re-exports
 
-For convenience, SDK classes are re-exported:
-
-```tsx
+```typescript
 import {
   Client,
   Auth,
@@ -607,9 +899,7 @@ const isLoggedIn = auth.isUserAuthenticated();
 
 ## Utility Functions
 
-Advanced users can access utility functions:
-
-```tsx
+```typescript
 import {
   REFINE_OPERATOR_MAP,
   convertRefineFilters,
@@ -619,6 +909,70 @@ import {
   buildQueryString,
   handleError,
 } from "@taruvi/refine-providers";
+
+// Convert filters to query params
+const params = convertRefineFilters([
+  { field: "status", operator: "eq", value: "active" },
+]);
+// Result: { status: "active" }
+
+// Convert sorters
+const ordering = convertRefineSorters([
+  { field: "created_at", order: "desc" },
+]);
+// Result: "-created_at"
+```
+
+---
+
+## Error Handling
+
+```typescript
+const { data, error, isError } = useList({ resource: "users" });
+
+if (isError) {
+  console.error(error.message);
+}
+```
+
+Auth errors are handled by `authProvider.onError`:
+- **401**: Attempts token refresh, then redirects to login
+- **403**: Returns error (user authenticated but not authorized)
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    React Application                        │
+│              (using Refine hooks/components)                │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    @refinedev/core                          │
+│        (useList, useCreate, useLogin, CanAccess, etc.)      │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                  @taruvi/refine-providers                   │
+│  Data: dataProvider, storageDataProvider, functionsData-    │
+│        Provider, appDataProvider, analyticsDataProvider     │
+│  Auth: authProvider, accessControlProvider                  │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      @taruvi/sdk                            │
+│  Database, Storage, Functions, App, Analytics, Auth, Policy │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                  Taruvi Backend API                         │
+└─────────────────────────────────────────────────────────────┘
 ```
 
 ---