@fluxbase/sdk-react 0.1.0-rc.1 → 2026.1.1-rc.2

package/src/use-storage.ts

@@ -2,256 +2,499 @@
  * Storage hooks for Fluxbase SDK
  */
 
-import { useMutation, useQuery, useQueryClient, type UseQueryOptions } from '@tanstack/react-query'
-import { useFluxbaseClient } from './context'
-import type { ListOptions, UploadOptions } from '@fluxbase/sdk'
+import { useState } from "react";
+import {
+  useMutation,
+  useQuery,
+  useQueryClient,
+  type UseQueryOptions,
+} from "@tanstack/react-query";
+import { useFluxbaseClient } from "./context";
+import type {
+  ListOptions,
+  UploadOptions,
+  UploadProgress,
+  TransformOptions,
+  SignedUrlOptions,
+} from "@fluxbase/sdk";
 
 /**
  * Hook to list files in a bucket
  */
 export function useStorageList(
   bucket: string,
-  options?: ListOptions & Omit<UseQueryOptions<any[], Error>, 'queryKey' | 'queryFn'>
+  options?: ListOptions &
+    Omit<UseQueryOptions<any[], Error>, "queryKey" | "queryFn">,
 ) {
-  const client = useFluxbaseClient()
-  const { prefix, limit, offset, ...queryOptions } = options || {}
+  const client = useFluxbaseClient();
+  const { prefix, limit, offset, ...queryOptions } = options || {};
 
   return useQuery({
-    queryKey: ['fluxbase', 'storage', bucket, 'list', { prefix, limit, offset }],
+    queryKey: [
+      "fluxbase",
+      "storage",
+      bucket,
+      "list",
+      { prefix, limit, offset },
+    ],
     queryFn: async () => {
-      const { data, error } = await client.storage.from(bucket).list({ prefix, limit, offset })
+      const { data, error } = await client.storage
+        .from(bucket)
+        .list({ prefix, limit, offset });
 
       if (error) {
-        throw error
+        throw error;
       }
 
-      return data || []
+      return data || [];
     },
     ...queryOptions,
-  })
+  });
 }
 
 /**
  * Hook to upload a file to a bucket
+ *
+ * Note: You can track upload progress by passing an `onUploadProgress` callback in the options:
+ *
+ * @example
+ * ```tsx
+ * const upload = useStorageUpload('avatars')
+ *
+ * upload.mutate({
+ *   path: 'user.jpg',
+ *   file: file,
+ *   options: {
+ *     onUploadProgress: (progress) => {
+ *       console.log(`${progress.percentage}% uploaded`)
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * For automatic progress state management, use `useStorageUploadWithProgress` instead.
  */
 export function useStorageUpload(bucket: string) {
-  const client = useFluxbaseClient()
-  const queryClient = useQueryClient()
+  const client = useFluxbaseClient();
+  const queryClient = useQueryClient();
 
   return useMutation({
     mutationFn: async (params: {
-      path: string
-      file: File | Blob | ArrayBuffer
-      options?: UploadOptions
+      path: string;
+      file: File | Blob | ArrayBuffer;
+      options?: UploadOptions;
     }) => {
-      const { path, file, options } = params
-      const { data, error } = await client.storage.from(bucket).upload(path, file, options)
+      const { path, file, options } = params;
+      const { data, error } = await client.storage
+        .from(bucket)
+        .upload(path, file, options);
 
       if (error) {
-        throw error
+        throw error;
       }
 
-      return data
+      return data;
     },
     onSuccess: () => {
       // Invalidate list queries for this bucket
-      queryClient.invalidateQueries({ queryKey: ['fluxbase', 'storage', bucket, 'list'] })
+      queryClient.invalidateQueries({
+        queryKey: ["fluxbase", "storage", bucket, "list"],
+      });
     },
-  })
+  });
+}
+
+/**
+ * Hook to upload a file to a bucket with built-in progress tracking
+ *
+ * @example
+ * ```tsx
+ * const { upload, progress, reset } = useStorageUploadWithProgress('avatars')
+ *
+ * // Upload with automatic progress tracking
+ * upload.mutate({
+ *   path: 'user.jpg',
+ *   file: file
+ * })
+ *
+ * // Display progress
+ * console.log(progress) // { loaded: 1024, total: 2048, percentage: 50 }
+ * ```
+ */
+export function useStorageUploadWithProgress(bucket: string) {
+  const client = useFluxbaseClient();
+  const queryClient = useQueryClient();
+  const [progress, setProgress] = useState<UploadProgress | null>(null);
+
+  const mutation = useMutation({
+    mutationFn: async (params: {
+      path: string;
+      file: File | Blob | ArrayBuffer;
+      options?: Omit<UploadOptions, "onUploadProgress">;
+    }) => {
+      const { path, file, options } = params;
+
+      // Reset progress at the start of upload
+      setProgress({ loaded: 0, total: 0, percentage: 0 });
+
+      const { data, error } = await client.storage
+        .from(bucket)
+        .upload(path, file, {
+          ...options,
+          onUploadProgress: (p: import("@fluxbase/sdk").UploadProgress) => {
+            setProgress(p);
+          },
+        });
+
+      if (error) {
+        throw error;
+      }
+
+      return data;
+    },
+    onSuccess: () => {
+      // Invalidate list queries for this bucket
+      queryClient.invalidateQueries({
+        queryKey: ["fluxbase", "storage", bucket, "list"],
+      });
+    },
+    onError: () => {
+      // Reset progress on error
+      setProgress(null);
+    },
+  });
+
+  return {
+    upload: mutation,
+    progress,
+    reset: () => setProgress(null),
+  };
 }
 
 /**
  * Hook to download a file from a bucket
  */
-export function useStorageDownload(bucket: string, path: string | null, enabled = true) {
-  const client = useFluxbaseClient()
+export function useStorageDownload(
+  bucket: string,
+  path: string | null,
+  enabled = true,
+) {
+  const client = useFluxbaseClient();
 
   return useQuery({
-    queryKey: ['fluxbase', 'storage', bucket, 'download', path],
+    queryKey: ["fluxbase", "storage", bucket, "download", path],
     queryFn: async () => {
       if (!path) {
-        return null
+        return null;
       }
 
-      const { data, error } = await client.storage.from(bucket).download(path)
+      const { data, error } = await client.storage.from(bucket).download(path);
 
       if (error) {
-        throw error
+        throw error;
       }
 
-      return data
+      return data;
     },
     enabled: enabled && !!path,
-  })
+  });
 }
 
 /**
  * Hook to delete files from a bucket
  */
 export function useStorageDelete(bucket: string) {
-  const client = useFluxbaseClient()
-  const queryClient = useQueryClient()
+  const client = useFluxbaseClient();
+  const queryClient = useQueryClient();
 
   return useMutation({
     mutationFn: async (paths: string[]) => {
-      const { error } = await client.storage.from(bucket).remove(paths)
+      const { error } = await client.storage.from(bucket).remove(paths);
 
       if (error) {
-        throw error
+        throw error;
       }
     },
     onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['fluxbase', 'storage', bucket, 'list'] })
+      queryClient.invalidateQueries({
+        queryKey: ["fluxbase", "storage", bucket, "list"],
+      });
     },
-  })
+  });
 }
 
 /**
  * Hook to get a public URL for a file
  */
 export function useStoragePublicUrl(bucket: string, path: string | null) {
-  const client = useFluxbaseClient()
+  const client = useFluxbaseClient();
+
+  if (!path) {
+    return null;
+  }
+
+  const { data } = client.storage.from(bucket).getPublicUrl(path);
+  return data.publicUrl;
+}
+
+/**
+ * Hook to get a public URL for an image with transformations applied
+ *
+ * Only works for image files (JPEG, PNG, WebP, GIF, AVIF, etc.)
+ *
+ * @param bucket - The storage bucket name
+ * @param path - The file path (or null to disable)
+ * @param transform - Transformation options (width, height, format, quality, fit)
+ *
+ * @example
+ * ```tsx
+ * function ImageThumbnail({ path }: { path: string }) {
+ *   const url = useStorageTransformUrl('images', path, {
+ *     width: 300,
+ *     height: 200,
+ *     format: 'webp',
+ *     quality: 85,
+ *     fit: 'cover'
+ *   });
+ *
+ *   return <img src={url || ''} alt="Thumbnail" />;
+ * }
+ * ```
+ */
+export function useStorageTransformUrl(
+  bucket: string,
+  path: string | null,
+  transform: TransformOptions,
+): string | null {
+  const client = useFluxbaseClient();
 
   if (!path) {
-    return null
+    return null;
   }
 
-  const { data } = client.storage.from(bucket).getPublicUrl(path)
-  return data.publicUrl
+  return client.storage.from(bucket).getTransformUrl(path, transform);
 }
 
 /**
  * Hook to create a signed URL
+ *
+ * @deprecated Use useStorageSignedUrlWithOptions for more control including transforms
+ */
+export function useStorageSignedUrl(
+  bucket: string,
+  path: string | null,
+  expiresIn?: number,
+) {
+  const client = useFluxbaseClient();
+
+  return useQuery({
+    queryKey: ["fluxbase", "storage", bucket, "signed-url", path, expiresIn],
+    queryFn: async () => {
+      if (!path) {
+        return null;
+      }
+
+      const { data, error } = await client.storage
+        .from(bucket)
+        .createSignedUrl(path, { expiresIn });
+
+      if (error) {
+        throw error;
+      }
+
+      return data?.signedUrl || null;
+    },
+    enabled: !!path,
+    staleTime: expiresIn ? expiresIn * 1000 - 60000 : 1000 * 60 * 50, // Refresh 1 minute before expiry
+  });
+}
+
+/**
+ * Hook to create a signed URL with full options including image transformations
+ *
+ * @param bucket - The storage bucket name
+ * @param path - The file path (or null to disable)
+ * @param options - Signed URL options including expiration and transforms
+ *
+ * @example
+ * ```tsx
+ * function SecureThumbnail({ path }: { path: string }) {
+ *   const { data: url } = useStorageSignedUrlWithOptions('images', path, {
+ *     expiresIn: 3600,
+ *     transform: {
+ *       width: 400,
+ *       height: 300,
+ *       format: 'webp',
+ *       quality: 85,
+ *       fit: 'cover'
+ *     }
+ *   });
+ *
+ *   return <img src={url || ''} alt="Secure Thumbnail" />;
+ * }
+ * ```
  */
-export function useStorageSignedUrl(bucket: string, path: string | null, expiresIn?: number) {
-  const client = useFluxbaseClient()
+export function useStorageSignedUrlWithOptions(
+  bucket: string,
+  path: string | null,
+  options?: SignedUrlOptions,
+) {
+  const client = useFluxbaseClient();
+  const expiresIn = options?.expiresIn;
+
+  // Create a stable cache key from transform options
+  const transformKey = options?.transform
+    ? JSON.stringify(options.transform)
+    : null;
 
   return useQuery({
-    queryKey: ['fluxbase', 'storage', bucket, 'signed-url', path, expiresIn],
+    queryKey: [
+      "fluxbase",
+      "storage",
+      bucket,
+      "signed-url",
+      path,
+      expiresIn,
+      transformKey,
+    ],
     queryFn: async () => {
       if (!path) {
-        return null
+        return null;
       }
 
-      const { data, error } = await client.storage.from(bucket).createSignedUrl(path, { expiresIn })
+      const { data, error } = await client.storage
+        .from(bucket)
+        .createSignedUrl(path, options);
 
       if (error) {
-        throw error
+        throw error;
       }
 
-      return data?.signedUrl || null
+      return data?.signedUrl || null;
     },
     enabled: !!path,
     staleTime: expiresIn ? expiresIn * 1000 - 60000 : 1000 * 60 * 50, // Refresh 1 minute before expiry
-  })
+  });
 }
 
 /**
  * Hook to move a file
  */
 export function useStorageMove(bucket: string) {
-  const client = useFluxbaseClient()
-  const queryClient = useQueryClient()
+  const client = useFluxbaseClient();
+  const queryClient = useQueryClient();
 
   return useMutation({
     mutationFn: async (params: { fromPath: string; toPath: string }) => {
-      const { fromPath, toPath } = params
-      const { data, error } = await client.storage.from(bucket).move(fromPath, toPath)
+      const { fromPath, toPath } = params;
+      const { data, error } = await client.storage
+        .from(bucket)
+        .move(fromPath, toPath);
 
       if (error) {
-        throw error
+        throw error;
       }
 
-      return data
+      return data;
     },
     onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['fluxbase', 'storage', bucket, 'list'] })
+      queryClient.invalidateQueries({
+        queryKey: ["fluxbase", "storage", bucket, "list"],
+      });
     },
-  })
+  });
 }
 
 /**
  * Hook to copy a file
  */
 export function useStorageCopy(bucket: string) {
-  const client = useFluxbaseClient()
-  const queryClient = useQueryClient()
+  const client = useFluxbaseClient();
+  const queryClient = useQueryClient();
 
   return useMutation({
     mutationFn: async (params: { fromPath: string; toPath: string }) => {
-      const { fromPath, toPath } = params
-      const { data, error } = await client.storage.from(bucket).copy(fromPath, toPath)
+      const { fromPath, toPath } = params;
+      const { data, error } = await client.storage
+        .from(bucket)
+        .copy(fromPath, toPath);
 
       if (error) {
-        throw error
+        throw error;
       }
 
-      return data
+      return data;
     },
     onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['fluxbase', 'storage', bucket, 'list'] })
+      queryClient.invalidateQueries({
+        queryKey: ["fluxbase", "storage", bucket, "list"],
+      });
     },
-  })
+  });
 }
 
 /**
  * Hook to manage buckets
  */
 export function useStorageBuckets() {
-  const client = useFluxbaseClient()
+  const client = useFluxbaseClient();
 
   return useQuery({
-    queryKey: ['fluxbase', 'storage', 'buckets'],
+    queryKey: ["fluxbase", "storage", "buckets"],
     queryFn: async () => {
-      const { data, error } = await client.storage.listBuckets()
+      const { data, error } = await client.storage.listBuckets();
 
       if (error) {
-        throw error
+        throw error;
       }
 
-      return data || []
+      return data || [];
     },
-  })
+  });
 }
 
 /**
  * Hook to create a bucket
  */
 export function useCreateBucket() {
-  const client = useFluxbaseClient()
-  const queryClient = useQueryClient()
+  const client = useFluxbaseClient();
+  const queryClient = useQueryClient();
 
   return useMutation({
     mutationFn: async (bucketName: string) => {
-      const { error } = await client.storage.createBucket(bucketName)
+      const { error } = await client.storage.createBucket(bucketName);
 
       if (error) {
-        throw error
+        throw error;
       }
     },
     onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['fluxbase', 'storage', 'buckets'] })
+      queryClient.invalidateQueries({
+        queryKey: ["fluxbase", "storage", "buckets"],
+      });
     },
-  })
+  });
 }
 
 /**
  * Hook to delete a bucket
  */
 export function useDeleteBucket() {
-  const client = useFluxbaseClient()
-  const queryClient = useQueryClient()
+  const client = useFluxbaseClient();
+  const queryClient = useQueryClient();
 
   return useMutation({
     mutationFn: async (bucketName: string) => {
-      const { error } = await client.storage.deleteBucket(bucketName)
+      const { error } = await client.storage.deleteBucket(bucketName);
 
       if (error) {
-        throw error
+        throw error;
       }
     },
     onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['fluxbase', 'storage', 'buckets'] })
+      queryClient.invalidateQueries({
+        queryKey: ["fluxbase", "storage", "buckets"],
+      });
     },
-  })
+  });
 }

package/src/use-users.ts

@@ -109,9 +109,12 @@ export function useUsers(options: UseUsersOptions = {}): UseUsersReturn {
     try {
       setIsLoading(true)
       setError(null)
-      const response = await client.admin.listUsers(listOptions)
-      setUsers(response.users)
-      setTotal(response.total)
+      const { data, error: apiError } = await client.admin.listUsers(listOptions)
+      if (apiError) {
+        throw apiError
+      }
+      setUsers(data!.users)
+      setTotal(data!.total)
     } catch (err) {
       setError(err as Error)
     } finally {
@@ -157,7 +160,11 @@ export function useUsers(options: UseUsersOptions = {}): UseUsersReturn {
    */
   const resetPassword = useCallback(
     async (userId: string): Promise<{ message: string }> => {
-      return await client.admin.resetUserPassword(userId)
+      const { data, error } = await client.admin.resetUserPassword(userId)
+      if (error) {
+        throw error
+      }
+      return data!
     },
     [client]
   )

package/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/context.tsx","./src/index.ts","./src/use-admin-auth.ts","./src/use-admin-hooks.ts","./src/use-api-keys.ts","./src/use-auth.ts","./src/use-query.ts","./src/use-realtime.ts","./src/use-rpc.ts","./src/use-storage.ts","./src/use-users.ts"],"version":"5.9.3"}
+{"root":["./src/context.tsx","./src/index.ts","./src/use-admin-auth.ts","./src/use-admin-hooks.ts","./src/use-client-keys.ts","./src/use-auth.ts","./src/use-query.ts","./src/use-realtime.ts","./src/use-rpc.ts","./src/use-storage.ts","./src/use-users.ts"],"version":"5.9.3"}

package/typedoc.json

@@ -1,8 +1,6 @@
 {
   "$schema": "https://typedoc.org/schema.json",
-  "entryPoints": [
-    "src/index.ts"
-  ],
+  "entryPoints": ["src/index.ts"],
   "out": "../docs/static/api/sdk-react",
   "name": "@fluxbase/sdk-react",
   "readme": "README.md",
@@ -29,7 +27,7 @@
     "*"
   ],
   "navigationLinks": {
-    "GitHub": "https://github.com/yourusername/fluxbase",
+    "GitHub": "https://github.com/fluxbase-eu/fluxbase",
     "Documentation": "https://fluxbase.eu"
   }
 }

package/CHANGELOG.md

@@ -1,67 +0,0 @@
-# Changelog
-
-All notable changes to @fluxbase/sdk-react will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [0.1.0] - 2025-10-26
-
-### Added
-
-- Initial release of Fluxbase React hooks library
-- **Authentication Hooks**
-  - `useAuth`: Complete auth state and methods
-  - `useUser`: Current user data with auto-refetch
-  - `useSession`: Access current session
-  - `useSignIn`: Sign in mutation hook
-  - `useSignUp`: Sign up mutation hook
-  - `useSignOut`: Sign out mutation hook
-  - `useUpdateUser`: Update user profile hook
-- **Database Query Hooks**
-  - `useTable`: Query table data with filters, ordering, pagination
-  - `useFluxbaseQuery`: Lower-level query hook for custom queries
-  - `useInsert`: Insert rows with automatic cache invalidation
-  - `useUpdate`: Update rows
-  - `useUpsert`: Insert or update (upsert)
-  - `useDelete`: Delete rows
-- **Realtime Hooks**
-  - `useRealtime`: Subscribe to database changes
-  - `useTableSubscription`: Auto-refetch queries on table changes
-  - `useTableInserts`: Listen to INSERT events
-  - `useTableUpdates`: Listen to UPDATE events
-  - `useTableDeletes`: Listen to DELETE events
-- **Storage Hooks**
-  - `useStorageList`: List files in bucket
-  - `useStorageUpload`: Upload files
-  - `useStorageDownload`: Download files
-  - `useStorageDelete`: Delete files
-  - `useStoragePublicUrl`: Get public URL
-  - `useStorageSignedUrl`: Generate signed URLs
-  - `useStorageMove`: Move files
-  - `useStorageCopy`: Copy files
-  - `useStorageBuckets`: List buckets
-  - `useCreateBucket`: Create bucket
-  - `useDeleteBucket`: Delete bucket
-- **Context & Provider**
-  - `FluxbaseProvider`: Provide Fluxbase client to React tree
-  - `useFluxbaseClient`: Access Fluxbase client from context
-- **TypeScript Support**
-  - Full type safety for all hooks
-  - Generic type parameters for table data
-  - Type inference from query builders
-- **Built on TanStack Query**
-  - Automatic caching and refetching
-  - Optimistic updates support
-  - Request deduplication
-  - Background refetching
-  - Stale-while-revalidate pattern
-  - SSR support
-
-### Peer Dependencies
-
-- `@fluxbase/sdk`: ^0.1.0
-- `@tanstack/react-query`: ^5.0.0
-- `react`: ^18.0.0 || ^19.0.0
-
-[0.1.0]: https://github.com/wayli-app/fluxbase/releases/tag/sdk-react-v0.1.0