@fluxbase/sdk-react 0.0.1-rc.2

package/examples/README.md

@@ -0,0 +1,163 @@
+# React Admin Hooks Examples
+
+This directory contains complete, production-ready examples demonstrating the Fluxbase React admin hooks.
+
+## Examples
+
+### AdminDashboard.tsx
+
+A complete admin dashboard application demonstrating all admin hooks in action.
+
+**Features:**
+- Admin authentication with protected routes
+- User management with pagination and search
+- Real-time statistics dashboard
+- Modern UI with Tailwind CSS
+- Full TypeScript support
+
+**Hooks demonstrated:**
+- `useAdminAuth()` - Authentication state management
+- `useUsers()` - User CRUD operations with pagination
+- `useAPIKeys()` - API key management
+- `useWebhooks()` - Webhook configuration
+- `useAppSettings()` - Application settings
+- `useSystemSettings()` - System settings
+
+**Run the example:**
+
+```bash
+# Install dependencies
+npm install @fluxbase/sdk @fluxbase/sdk-react @tanstack/react-query
+
+# Copy AdminDashboard.tsx to your project
+# Add Tailwind CSS to your project (optional, for styling)
+```
+
+**Basic usage:**
+
+```tsx
+import { createClient } from '@fluxbase/sdk'
+import { FluxbaseProvider } from '@fluxbase/sdk-react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import AdminDashboard from './AdminDashboard'
+
+const client = createClient({ url: 'http://localhost:8080' })
+const queryClient = new QueryClient()
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <FluxbaseProvider client={client}>
+        <AdminDashboard />
+      </FluxbaseProvider>
+    </QueryClientProvider>
+  )
+}
+```
+
+## Key Patterns
+
+### 1. Authentication Flow
+
+```tsx
+const { isAuthenticated, isLoading, login, logout } = useAdminAuth({
+  autoCheck: true // Automatically check auth status on mount
+})
+
+if (isLoading) return <LoadingSpinner />
+if (!isAuthenticated) return <LoginPage />
+return <Dashboard />
+```
+
+### 2. Data Fetching with Pagination
+
+```tsx
+const [page, setPage] = useState(0)
+const limit = 20
+
+const { users, total, isLoading } = useUsers({
+  autoFetch: true,
+  limit,
+  offset: page * limit
+})
+```
+
+### 3. Search and Filters
+
+```tsx
+const [searchEmail, setSearchEmail] = useState('')
+const [roleFilter, setRoleFilter] = useState<'admin' | 'user' | ''>('')
+
+const { users, refetch } = useUsers({
+  autoFetch: true,
+  email: searchEmail || undefined,
+  role: roleFilter || undefined
+})
+
+// Refetch when filters change
+useEffect(() => {
+  refetch()
+}, [searchEmail, roleFilter, refetch])
+```
+
+### 4. Optimistic Updates
+
+All mutation functions automatically refetch data:
+
+```tsx
+const { users, inviteUser, deleteUser } = useUsers({ autoFetch: true })
+
+// These automatically refetch the user list after success
+await inviteUser('new@example.com', 'user')
+await deleteUser(userId)
+// users state is now updated
+```
+
+### 5. Error Handling
+
+```tsx
+const { data, error, isLoading, refetch } = useUsers({ autoFetch: true })
+
+if (isLoading) return <LoadingSpinner />
+if (error) return <ErrorMessage error={error} onRetry={refetch} />
+return <DataDisplay data={data} />
+```
+
+## Styling
+
+The example uses Tailwind CSS utility classes, but you can easily adapt it to your preferred styling solution:
+
+- **CSS Modules**: Replace `className` with module imports
+- **Styled Components**: Replace elements with styled components
+- **Material-UI**: Use MUI components instead of native HTML
+- **Chakra UI**: Use Chakra components for rapid development
+
+## TypeScript
+
+All examples are fully typed. The hooks provide complete type safety:
+
+```tsx
+import type { EnrichedUser, APIKey, Webhook } from '@fluxbase/sdk-react'
+
+const { users }: { users: EnrichedUser[] } = useUsers({ autoFetch: true })
+const { keys }: { keys: APIKey[] } = useAPIKeys({ autoFetch: true })
+```
+
+## Next Steps
+
+1. **Customize the UI** - Adapt the styling to match your design system
+2. **Add more features** - Implement API keys, webhooks, and settings tabs
+3. **Add validation** - Add form validation for user inputs
+4. **Add loading states** - Improve loading and error states
+5. **Add notifications** - Show success/error toasts for mutations
+6. **Add search** - Enhance search with debouncing and advanced filters
+
+## Documentation
+
+- [Complete Admin Hooks Guide](../README-ADMIN.md) - Full API reference and examples
+- [React Hooks Documentation](../../docs/docs/sdks/react-hooks.md) - Core hooks documentation
+- [Admin API Documentation](../../docs/docs/sdk/admin.md) - Admin operations reference
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@fluxbase/sdk-react",
+  "version": "0.0.1-rc.2",
+  "description": "React hooks for Fluxbase SDK",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "docs": "typedoc",
+    "docs:watch": "typedoc --watch",
+    "type-check": "tsc --noEmit",
+    "format": "prettier --write src",
+    "format:check": "prettier --check src"
+  },
+  "keywords": [
+    "fluxbase",
+    "react",
+    "hooks",
+    "database",
+    "realtime"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wayli-app/fluxbase"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@fluxbase/sdk": "^0.1.0",
+    "@tanstack/react-query": "^5.0.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@fluxbase/sdk": "file:../sdk",
+    "@tanstack/react-query": "^5.62.14",
+    "@types/react": "^19.0.0",
+    "prettier": "^3.4.2",
+    "tsup": "^8.3.5",
+    "typedoc": "^0.28.14",
+    "typescript": "^5.7.3"
+  }
+}

package/src/context.tsx

@@ -0,0 +1,33 @@
+/**
+ * React context for Fluxbase client
+ */
+
+import { createContext, useContext, type ReactNode } from 'react'
+import type { FluxbaseClient } from '@fluxbase/sdk'
+
+const FluxbaseContext = createContext<FluxbaseClient | null>(null)
+
+export interface FluxbaseProviderProps {
+  client: FluxbaseClient
+  children: ReactNode
+}
+
+/**
+ * Provider component to make Fluxbase client available throughout the app
+ */
+export function FluxbaseProvider({ client, children }: FluxbaseProviderProps) {
+  return <FluxbaseContext.Provider value={client}>{children}</FluxbaseContext.Provider>
+}
+
+/**
+ * Hook to access the Fluxbase client from context
+ */
+export function useFluxbaseClient(): FluxbaseClient {
+  const client = useContext(FluxbaseContext)
+
+  if (!client) {
+    throw new Error('useFluxbaseClient must be used within a FluxbaseProvider')
+  }
+
+  return client
+}

package/src/index.ts

@@ -0,0 +1,113 @@
+/**
+ * Fluxbase React Hooks
+ *
+ * @example
+ * ```tsx
+ * import { createClient } from '@fluxbase/sdk'
+ * import { FluxbaseProvider, useAuth, useTable } from '@fluxbase/sdk-react'
+ * import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+ *
+ * const client = createClient({ url: 'http://localhost:8080' })
+ * const queryClient = new QueryClient()
+ *
+ * function App() {
+ *   return (
+ *     <QueryClientProvider client={queryClient}>
+ *       <FluxbaseProvider client={client}>
+ *         <MyComponent />
+ *       </FluxbaseProvider>
+ *     </QueryClientProvider>
+ *   )
+ * }
+ *
+ * function MyComponent() {
+ *   const { user, signIn, signOut } = useAuth()
+ *   const { data: products } = useTable('products', (q) => q.select('*').eq('active', true))
+ *
+ *   return <div>...</div>
+ * }
+ * ```
+ */
+
+// Context and provider
+export { FluxbaseProvider, useFluxbaseClient } from './context'
+
+// Auth hooks
+export {
+  useAuth,
+  useUser,
+  useSession,
+  useSignIn,
+  useSignUp,
+  useSignOut,
+  useUpdateUser,
+} from './use-auth'
+
+// Database query hooks
+export {
+  useFluxbaseQuery,
+  useTable,
+  useInsert,
+  useUpdate,
+  useUpsert,
+  useDelete,
+} from './use-query'
+
+// Realtime hooks
+export {
+  useRealtime,
+  useTableSubscription,
+  useTableInserts,
+  useTableUpdates,
+  useTableDeletes,
+} from './use-realtime'
+
+// Storage hooks
+export {
+  useStorageList,
+  useStorageUpload,
+  useStorageDownload,
+  useStorageDelete,
+  useStoragePublicUrl,
+  useStorageSignedUrl,
+  useStorageMove,
+  useStorageCopy,
+  useStorageBuckets,
+  useCreateBucket,
+  useDeleteBucket,
+} from './use-storage'
+
+// RPC hooks
+export {
+  useRPC,
+  useRPCMutation,
+  useRPCBatch,
+} from './use-rpc'
+
+// Admin hooks
+export { useAdminAuth } from './use-admin-auth'
+export { useUsers } from './use-users'
+export { useAPIKeys } from './use-api-keys'
+export {
+  useWebhooks,
+  useAppSettings,
+  useSystemSettings,
+} from './use-admin-hooks'
+
+// Re-export types from SDK
+export type {
+  FluxbaseClient,
+  AuthSession,
+  User,
+  SignInCredentials,
+  SignUpCredentials,
+  PostgrestResponse,
+  RealtimeChangePayload,
+  StorageObject,
+  AdminUser,
+  EnrichedUser,
+  APIKey,
+  Webhook,
+  AppSettings,
+  SystemSetting,
+} from '@fluxbase/sdk'

package/src/use-admin-auth.ts

@@ -0,0 +1,168 @@
+import { useState, useEffect, useCallback } from 'react'
+import { useFluxbaseClient } from './context'
+import type { AdminAuthResponse } from '@fluxbase/sdk'
+
+/**
+ * Simplified admin user type returned by authentication
+ */
+export interface AdminUser {
+  id: string
+  email: string
+  role: string
+}
+
+export interface UseAdminAuthOptions {
+  /**
+   * Automatically check authentication status on mount
+   * @default true
+   */
+  autoCheck?: boolean
+}
+
+export interface UseAdminAuthReturn {
+  /**
+   * Current admin user if authenticated
+   */
+  user: AdminUser | null
+
+  /**
+   * Whether the admin is authenticated
+   */
+  isAuthenticated: boolean
+
+  /**
+   * Whether the authentication check is in progress
+   */
+  isLoading: boolean
+
+  /**
+   * Any error that occurred during authentication
+   */
+  error: Error | null
+
+  /**
+   * Login as admin
+   */
+  login: (email: string, password: string) => Promise<AdminAuthResponse>
+
+  /**
+   * Logout admin
+   */
+  logout: () => Promise<void>
+
+  /**
+   * Refresh admin user info
+   */
+  refresh: () => Promise<void>
+}
+
+/**
+ * Hook for admin authentication
+ *
+ * Manages admin login state, authentication checks, and user info.
+ *
+ * @example
+ * ```tsx
+ * function AdminLogin() {
+ *   const { user, isAuthenticated, isLoading, login, logout } = useAdminAuth()
+ *
+ *   const handleLogin = async (e: React.FormEvent) => {
+ *     e.preventDefault()
+ *     await login(email, password)
+ *   }
+ *
+ *   if (isLoading) return <div>Loading...</div>
+ *   if (isAuthenticated) return <div>Welcome {user?.email}</div>
+ *
+ *   return <form onSubmit={handleLogin}>...</form>
+ * }
+ * ```
+ */
+export function useAdminAuth(options: UseAdminAuthOptions = {}): UseAdminAuthReturn {
+  const { autoCheck = true } = options
+  const client = useFluxbaseClient()
+
+  const [user, setUser] = useState<AdminUser | null>(null)
+  const [isLoading, setIsLoading] = useState(autoCheck)
+  const [error, setError] = useState<Error | null>(null)
+
+  /**
+   * Check current authentication status
+   */
+  const checkAuth = useCallback(async () => {
+    try {
+      setIsLoading(true)
+      setError(null)
+      const { user } = await client.admin.me()
+      setUser(user)
+    } catch (err) {
+      setUser(null)
+      setError(err as Error)
+    } finally {
+      setIsLoading(false)
+    }
+  }, [client])
+
+  /**
+   * Login as admin
+   */
+  const login = useCallback(
+    async (email: string, password: string): Promise<AdminAuthResponse> => {
+      try {
+        setIsLoading(true)
+        setError(null)
+        const response = await client.admin.login({ email, password })
+        setUser(response.user)
+        return response
+      } catch (err) {
+        setError(err as Error)
+        throw err
+      } finally {
+        setIsLoading(false)
+      }
+    },
+    [client]
+  )
+
+  /**
+   * Logout admin
+   */
+  const logout = useCallback(async (): Promise<void> => {
+    try {
+      setIsLoading(true)
+      setError(null)
+      // Clear user state
+      setUser(null)
+      // Note: Add logout endpoint call here when available
+    } catch (err) {
+      setError(err as Error)
+      throw err
+    } finally {
+      setIsLoading(false)
+    }
+  }, [])
+
+  /**
+   * Refresh admin user info
+   */
+  const refresh = useCallback(async (): Promise<void> => {
+    await checkAuth()
+  }, [checkAuth])
+
+  // Auto-check authentication on mount
+  useEffect(() => {
+    if (autoCheck) {
+      checkAuth()
+    }
+  }, [autoCheck, checkAuth])
+
+  return {
+    user,
+    isAuthenticated: user !== null,
+    isLoading,
+    error,
+    login,
+    logout,
+    refresh
+  }
+}