@taruvi/refine-providers 1.0.4 → 1.0.6

package/README.md

@@ -0,0 +1,628 @@
+# @taruvi/refine-providers
+
+Refine.dev data providers for Taruvi Data Service. This package provides a complete integration layer between [Refine](https://refine.dev/) and the Taruvi backend platform.
+
+## Installation
+
+```bash
+npm install @taruvi/refine-providers @taruvi/sdk @refinedev/core
+```
+
+## Quick Start
+
+```tsx
+import { Refine } from "@refinedev/core";
+import {
+  Client,
+  dataProvider,
+  storageDataProvider,
+  authProvider,
+  accessControlProvider,
+} from "@taruvi/refine-providers";
+
+// Initialize the Taruvi client
+const client = new Client({
+  apiKey: "your-api-key",
+  appSlug: "your-app-slug",
+  baseUrl: "https://your-site.taruvi.cloud",
+});
+
+function App() {
+  return (
+    <Refine
+      dataProvider={dataProvider(client)}
+      authProvider={authProvider(client)}
+      accessControlProvider={accessControlProvider(client)}
+      resources={[
+        { name: "users" },
+        { name: "posts" },
+      ]}
+    >
+      {/* Your app */}
+    </Refine>
+  );
+}
+```
+
+## Data Providers
+
+This package includes multiple specialized data providers:
+
+| 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` |
+
+---
+
+## Database Data Provider
+
+The main data provider for CRUD operations on database tables.
+
+### Basic Usage
+
+```tsx
+import { dataProvider, Client } from "@taruvi/refine-providers";
+
+const client = new Client({ apiKey, appSlug, baseUrl });
+
+<Refine
+  dataProvider={dataProvider(client)}
+  resources={[{ name: "posts" }]}
+/>
+```
+
+### Supported Operations
+
+All standard Refine CRUD operations are supported:
+
+```tsx
+// List records
+const { data } = useList({ resource: "posts" });
+
+// Get single record
+const { data } = useOne({ resource: "posts", id: 1 });
+
+// Get multiple records
+const { data } = useMany({ resource: "posts", ids: [1, 2, 3] });
+
+// Create record
+const { mutate } = useCreate();
+mutate({ resource: "posts", values: { title: "Hello" } });
+
+// Update record
+const { mutate } = useUpdate();
+mutate({ resource: "posts", id: 1, values: { title: "Updated" } });
+
+// Delete record
+const { mutate } = useDelete();
+mutate({ resource: "posts", id: 1 });
+```
+
+### Filtering
+
+Full support for Refine filter operators:
+
+```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"] },
+  ],
+});
+```
+
+**Supported Operators:**
+
+| 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]` |
+
+### Sorting & Pagination
+
+```tsx
+const { data } = useList({
+  resource: "posts",
+  sorters: [
+    { field: "created_at", order: "desc" },
+    { field: "title", order: "asc" },
+  ],
+  pagination: {
+    currentPage: 1,
+    pageSize: 20,
+  },
+});
+```
+
+### Meta Options
+
+Use the `meta` parameter for Taruvi-specific features:
+
+```tsx
+const { data } = useList({
+  resource: "posts",
+  meta: {
+    // Override table name (when resource differs from table)
+    tableName: "blog_posts",
+
+    // Populate foreign key relations
+    populate: ["author", "category"],
+    // or populate all: populate: "*"
+
+    // Select specific fields
+    select: ["id", "title", "status"],
+
+    // Custom ID column
+    idColumnName: "post_id",
+  },
+});
+```
+
+### Aggregations
+
+Support for aggregate queries with grouping:
+
+```tsx
+const { data } = useList({
+  resource: "orders",
+  meta: {
+    aggregate: ["sum(total)", "count(*)", "avg(quantity)"],
+    groupBy: ["status", "category"],
+    having: [
+      { field: "sum(total)", operator: "gte", value: 1000 },
+    ],
+  },
+});
+```
+
+---
+
+## Storage Data Provider
+
+For file upload, download, and management operations.
+
+### Setup
+
+```tsx
+import { storageDataProvider, Client } from "@taruvi/refine-providers";
+
+const client = new Client({ apiKey, appSlug, baseUrl });
+
+<Refine
+  dataProvider={{
+    default: dataProvider(client),
+    storage: storageDataProvider(client),
+  }}
+/>
+```
+
+### List Files
+
+```tsx
+const { data } = useList({
+  resource: "documents", // bucket name
+  dataProviderName: "storage",
+});
+```
+
+### Upload Files
+
+```tsx
+import { useCreate } from "@refinedev/core";
+import type { StorageUploadVariables } from "@taruvi/refine-providers";
+
+const { mutate } = useCreate<any, any, StorageUploadVariables>();
+
+// Single file upload
+mutate({
+  resource: "documents",
+  dataProviderName: "storage",
+  values: {
+    files: [file],
+    paths: ["uploads/document.pdf"],
+    metadatas: [{ description: "My document" }],
+  },
+});
+
+// Multiple files
+mutate({
+  resource: "documents",
+  dataProviderName: "storage",
+  values: {
+    files: [file1, file2],
+    paths: ["file1.pdf", "file2.pdf"],
+    metadatas: [{}, {}],
+  },
+});
+```
+
+### Delete Files
+
+```tsx
+const { mutate } = useDeleteMany();
+
+mutate({
+  resource: "documents",
+  dataProviderName: "storage",
+  ids: ["path/to/file1.pdf", "path/to/file2.pdf"],
+});
+```
+
+### Filter Files
+
+```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
+  },
+});
+```
+
+---
+
+## Functions Data Provider
+
+For executing Taruvi edge functions.
+
+### Setup
+
+```tsx
+import { functionsDataProvider, Client } from "@taruvi/refine-providers";
+
+<Refine
+  dataProvider={{
+    default: dataProvider(client),
+    functions: functionsDataProvider(client),
+  }}
+/>
+```
+
+### Execute Function
+
+```tsx
+import { useCustom } from "@refinedev/core";
+
+const { data } = useCustom({
+  dataProviderName: "functions",
+  url: "my-function-slug",
+  method: "post",
+  config: {
+    payload: {
+      param1: "value1",
+      param2: 123,
+    },
+  },
+  meta: {
+    async: false, // Set to true for async execution
+  },
+});
+```
+
+---
+
+## App Data Provider
+
+For fetching app-level data like roles.
+
+### Setup
+
+```tsx
+import { appDataProvider, Client } from "@taruvi/refine-providers";
+
+<Refine
+  dataProvider={{
+    default: dataProvider(client),
+    app: appDataProvider(client),
+  }}
+/>
+```
+
+### Fetch Roles
+
+```tsx
+const { data } = useList({
+  resource: "roles",
+  dataProviderName: "app",
+});
+
+// Returns: { data: [{ id, name, permissions, ... }], total: number }
+```
+
+---
+
+## Analytics Data Provider
+
+For executing predefined analytics queries.
+
+### Setup
+
+```tsx
+import { analyticsDataProvider, Client } from "@taruvi/refine-providers";
+
+<Refine
+  dataProvider={{
+    default: dataProvider(client),
+    analytics: analyticsDataProvider(client),
+  }}
+/>
+```
+
+### Execute Analytics Query
+
+```tsx
+import { useCustom } from "@refinedev/core";
+
+const { data } = useCustom({
+  dataProviderName: "analytics",
+  url: "monthly-sales-report", // query slug
+  method: "post",
+  config: {
+    payload: {
+      start_date: "2024-01-01",
+      end_date: "2024-12-31",
+      region: "US",
+    },
+  },
+});
+```
+
+---
+
+## Auth Provider
+
+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 });
+
+<Refine
+  authProvider={authProvider(client)}
+/>
+```
+
+### Login
+
+```tsx
+import { useLogin } from "@refinedev/core";
+
+const { mutate: login } = useLogin();
+
+// Redirect to login page
+login({ callbackUrl: "/dashboard" });
+```
+
+### Logout
+
+```tsx
+import { useLogout } from "@refinedev/core";
+
+const { mutate: logout } = useLogout();
+
+logout({ callbackUrl: "/login" });
+```
+
+### Register/Signup
+
+```tsx
+import { useRegister } from "@refinedev/core";
+
+const { mutate: register } = useRegister();
+
+register({ callbackUrl: "/welcome" });
+```
+
+### Get Current User
+
+```tsx
+import { useGetIdentity } from "@refinedev/core";
+import type { TaruviUser } from "@taruvi/refine-providers";
+
+const { data: user } = useGetIdentity<TaruviUser>();
+
+console.log(user?.username);
+console.log(user?.email);
+```
+
+### Check Permissions
+
+```tsx
+import { usePermissions } from "@refinedev/core";
+
+const { data: permissions } = usePermissions();
+
+console.log(permissions?.roles);
+console.log(permissions?.is_staff);
+```
+
+---
+
+## Access Control Provider
+
+Resource-based authorization using Cerbos policies.
+
+### Setup
+
+```tsx
+import { accessControlProvider, Client } from "@taruvi/refine-providers";
+
+<Refine
+  authProvider={authProvider(client)}
+  accessControlProvider={accessControlProvider(client)}
+/>
+```
+
+### Check Permissions
+
+```tsx
+import { useCan } from "@refinedev/core";
+
+const { data } = useCan({
+  resource: "posts",
+  action: "edit",
+  params: { id: 1 },
+});
+
+if (data?.can) {
+  // User can edit this post
+}
+```
+
+### CanAccess Component
+
+```tsx
+import { CanAccess } from "@refinedev/core";
+
+<CanAccess resource="posts" action="delete" params={{ id: 1 }}>
+  <DeleteButton />
+</CanAccess>
+```
+
+### Define Entity Type
+
+For Cerbos, specify the entity type in resource meta:
+
+```tsx
+<Refine
+  resources={[
+    {
+      name: "posts",
+      meta: {
+        entityType: "blog", // Used in Cerbos policy
+      },
+    },
+  ]}
+/>
+```
+
+---
+
+## Multiple Data Providers
+
+Use multiple providers together:
+
+```tsx
+import {
+  Client,
+  dataProvider,
+  storageDataProvider,
+  functionsDataProvider,
+  appDataProvider,
+  analyticsDataProvider,
+} from "@taruvi/refine-providers";
+
+const client = new Client({ apiKey, appSlug, baseUrl });
+
+<Refine
+  dataProvider={{
+    default: dataProvider(client),
+    storage: storageDataProvider(client),
+    functions: functionsDataProvider(client),
+    app: appDataProvider(client),
+    analytics: analyticsDataProvider(client),
+  }}
+/>
+
+// Then specify which provider to use:
+useList({ resource: "posts" }); // Uses default
+useList({ resource: "images", dataProviderName: "storage" });
+useCustom({ url: "process", dataProviderName: "functions", method: "post" });
+```
+
+---
+
+## TypeScript Types
+
+All types are exported for TypeScript users:
+
+```tsx
+import type {
+  // Meta types
+  TaruviMeta,
+  TaruviListResponse,
+  AnalyticsMeta,
+  FunctionMeta,
+  StorageUploadVariables,
+
+  // Auth types
+  TaruviUser,
+  LoginParams,
+  LogoutParams,
+  RegisterParams,
+
+  // SDK types (re-exported)
+  TaruviConfig,
+  RoleResponse,
+  AnalyticsRequest,
+  AnalyticsResponse,
+} from "@taruvi/refine-providers";
+```
+
+---
+
+## SDK Re-exports
+
+For convenience, SDK classes are re-exported:
+
+```tsx
+import {
+  Client,
+  Auth,
+  Policy,
+  Functions,
+  App,
+  Analytics,
+} from "@taruvi/refine-providers";
+
+// Use SDK directly when needed
+const auth = new Auth(client);
+const isLoggedIn = auth.isUserAuthenticated();
+```
+
+---
+
+## Utility Functions
+
+Advanced users can access utility functions:
+
+```tsx
+import {
+  REFINE_OPERATOR_MAP,
+  convertRefineFilters,
+  convertRefineSorters,
+  convertRefinePagination,
+  buildRefineQueryParams,
+  buildQueryString,
+  handleError,
+} from "@taruvi/refine-providers";
+```
+
+---
+
+## License
+
+MIT