@react-spa-scaffold/mcp 2.1.1 → 2.3.0

package/templates/src/hooks/supabase/useProfiles.test.tsx

@@ -0,0 +1,207 @@
+import { QueryClientProvider } from '@tanstack/react-query';
+import { renderHook, waitFor } from '@testing-library/react';
+import type { ReactNode } from 'react';
+import { describe, it, expect, beforeEach } from 'vitest';
+
+import {
+  createTestQueryClient,
+  setMockClerkSignedIn,
+  setMockClerkUser,
+  resetClerkMocks,
+  createProfile,
+  setMockSupabaseData,
+  resetSupabaseMocks,
+} from '@/test';
+
+import { useCurrentProfile, useProfile, useUpsertProfile, useUpdateProfile, useDeleteProfile } from './useProfiles';
+
+function createWrapper() {
+  const queryClient = createTestQueryClient();
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
+  };
+}
+
+describe('useCurrentProfile', () => {
+  beforeEach(() => {
+    resetClerkMocks();
+    resetSupabaseMocks();
+  });
+
+  it('fetches profile when user is signed in', async () => {
+    const profile = createProfile({ id: 'user-123', full_name: 'Test User' });
+    setMockSupabaseData([profile]);
+    setMockClerkUser({ id: 'user-123' });
+
+    const { result } = renderHook(() => useCurrentProfile(), {
+      wrapper: createWrapper(),
+    });
+
+    await waitFor(() => {
+      expect(result.current.isSuccess).toBe(true);
+    });
+
+    expect(result.current.data).toHaveLength(1);
+    expect(result.current.data?.[0].full_name).toBe('Test User');
+  });
+
+  it('does not fetch when user is not signed in', async () => {
+    setMockClerkSignedIn(false);
+
+    const { result } = renderHook(() => useCurrentProfile(), {
+      wrapper: createWrapper(),
+    });
+
+    // Query should be disabled
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.data).toBeUndefined();
+  });
+});
+
+describe('useProfile', () => {
+  beforeEach(() => {
+    resetClerkMocks();
+    resetSupabaseMocks();
+  });
+
+  it('returns profile object and exists flag', async () => {
+    const profile = createProfile({ id: 'user-123', full_name: 'Test User' });
+    setMockSupabaseData([profile]);
+    setMockClerkUser({ id: 'user-123' });
+
+    const { result } = renderHook(() => useProfile(), {
+      wrapper: createWrapper(),
+    });
+
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false);
+    });
+
+    expect(result.current.profile?.full_name).toBe('Test User');
+    expect(result.current.exists).toBe(true);
+  });
+
+  it('returns null profile when not found', async () => {
+    setMockSupabaseData([]);
+    setMockClerkUser({ id: 'user-123' });
+
+    const { result } = renderHook(() => useProfile(), {
+      wrapper: createWrapper(),
+    });
+
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false);
+    });
+
+    expect(result.current.profile).toBeNull();
+    expect(result.current.exists).toBe(false);
+  });
+
+  it('exposes isFetching and refetch', async () => {
+    const profile = createProfile({ id: 'user-123' });
+    setMockSupabaseData([profile]);
+    setMockClerkUser({ id: 'user-123' });
+
+    const { result } = renderHook(() => useProfile(), {
+      wrapper: createWrapper(),
+    });
+
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false);
+    });
+
+    expect(typeof result.current.isFetching).toBe('boolean');
+    expect(typeof result.current.refetch).toBe('function');
+  });
+});
+
+describe('useUpsertProfile', () => {
+  beforeEach(() => {
+    resetClerkMocks();
+    resetSupabaseMocks();
+  });
+
+  it('returns mutation function', () => {
+    const { result } = renderHook(() => useUpsertProfile(), {
+      wrapper: createWrapper(),
+    });
+
+    expect(typeof result.current.mutate).toBe('function');
+    expect(typeof result.current.mutateAsync).toBe('function');
+    expect(result.current.isIdle).toBe(true);
+  });
+});
+
+describe('useUpdateProfile', () => {
+  beforeEach(() => {
+    resetClerkMocks();
+    resetSupabaseMocks();
+  });
+
+  it('returns mutation function', () => {
+    setMockClerkUser({ id: 'user-123' });
+
+    const { result } = renderHook(() => useUpdateProfile(), {
+      wrapper: createWrapper(),
+    });
+
+    expect(typeof result.current.mutate).toBe('function');
+    expect(typeof result.current.mutateAsync).toBe('function');
+    expect(result.current.isIdle).toBe(true);
+  });
+
+  it('throws when user is not authenticated', async () => {
+    setMockClerkSignedIn(false);
+
+    const { result } = renderHook(() => useUpdateProfile(), {
+      wrapper: createWrapper(),
+    });
+
+    let errorThrown = false;
+    try {
+      await result.current.mutateAsync({ full_name: 'Test' });
+    } catch (error) {
+      errorThrown = true;
+      expect((error as Error).message).toBe('No authenticated user');
+    }
+
+    expect(errorThrown).toBe(true);
+  });
+});
+
+describe('useDeleteProfile', () => {
+  beforeEach(() => {
+    resetClerkMocks();
+    resetSupabaseMocks();
+  });
+
+  it('returns mutation function', () => {
+    setMockClerkUser({ id: 'user-123' });
+
+    const { result } = renderHook(() => useDeleteProfile(), {
+      wrapper: createWrapper(),
+    });
+
+    expect(typeof result.current.mutate).toBe('function');
+    expect(typeof result.current.mutateAsync).toBe('function');
+    expect(result.current.isIdle).toBe(true);
+  });
+
+  it('throws when user is not authenticated', async () => {
+    setMockClerkSignedIn(false);
+
+    const { result } = renderHook(() => useDeleteProfile(), {
+      wrapper: createWrapper(),
+    });
+
+    let errorThrown = false;
+    try {
+      await result.current.mutateAsync();
+    } catch (error) {
+      errorThrown = true;
+      expect((error as Error).message).toBe('No authenticated user');
+    }
+
+    expect(errorThrown).toBe(true);
+  });
+});

package/templates/src/hooks/supabase/useProfiles.ts

@@ -0,0 +1,213 @@
+/**
+ * User profile hooks for Supabase with Clerk authentication.
+ *
+ * All operations are automatically scoped to the current user via RLS policies.
+ * The profile `id` field corresponds to the Clerk user_id (`auth.uid()`).
+ */
+
+import { useUser } from '@clerk/react-router';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import type { PostgrestError } from '@supabase/supabase-js';
+
+import { useSupabase } from '@/contexts/supabaseContext';
+import type { Profile, ProfileInsert, ProfileUpdate } from '@/types/database';
+
+import { useSupabaseQuery } from './useSupabaseQuery';
+
+/**
+ * Hook to fetch the current user's profile (returns array).
+ *
+ * Uses Clerk's user ID to query the profile and automatically
+ * respects RLS policies. For convenience, consider using `useProfile()`
+ * which returns a single profile instead of an array.
+ *
+ * @example
+ * ```tsx
+ * function ProfilePage() {
+ *   const { data: profiles, isLoading, error } = useCurrentProfile();
+ *   const profile = profiles?.[0];
+ *
+ *   if (isLoading) return <Spinner />;
+ *   if (error) return <Error message={error.message} />;
+ *   if (!profile) return <CreateProfileForm />;
+ *
+ *   return <ProfileDisplay profile={profile} />;
+ * }
+ * ```
+ */
+export function useCurrentProfile() {
+  const { user, isLoaded } = useUser();
+  const userId = user?.id;
+
+  return useSupabaseQuery<Profile>({
+    table: 'profiles',
+    filter: (query) => query.eq('id', userId ?? ''),
+    queryKey: ['current', userId ?? ''],
+    queryOptions: {
+      enabled: isLoaded && !!userId,
+    },
+  });
+}
+
+/**
+ * Convenience hook to fetch the current user's profile as a single object.
+ *
+ * This is a wrapper around `useCurrentProfile()` that extracts the first
+ * profile from the array and provides a cleaner API for common use cases.
+ *
+ * @example
+ * ```tsx
+ * function ProfilePage() {
+ *   const { profile, isLoading, error, exists } = useProfile();
+ *
+ *   if (isLoading) return <Spinner />;
+ *   if (error) return <Error message={error.message} />;
+ *   if (!exists) return <CreateProfileForm />;
+ *
+ *   return <ProfileDisplay profile={profile} />;
+ * }
+ * ```
+ */
+export function useProfile() {
+  const query = useCurrentProfile();
+  const profile = query.data?.[0] ?? null;
+
+  return {
+    /** The user's profile, or null if not found */
+    profile,
+    /** Whether a profile exists for the current user */
+    exists: profile !== null,
+    /** Whether the query is currently loading */
+    isLoading: query.isLoading,
+    /** Whether the query is fetching (includes background refetches) */
+    isFetching: query.isFetching,
+    /** Error from the query, if any */
+    error: query.error,
+    /** Refetch the profile data */
+    refetch: query.refetch,
+  };
+}
+
+/**
+ * Hook to create or update the current user's profile.
+ *
+ * Uses upsert to handle both creation and updates in a single operation.
+ * This is useful for syncing Clerk user data to Supabase on first login.
+ *
+ * @example
+ * ```tsx
+ * function ProfileSync() {
+ *   const { user } = useUser();
+ *   const upsertProfile = useUpsertProfile();
+ *
+ *   useEffect(() => {
+ *     if (user) {
+ *       upsertProfile.mutate({
+ *         id: user.id,
+ *         email: user.primaryEmailAddress?.emailAddress ?? '',
+ *         full_name: user.fullName,
+ *         avatar_url: user.imageUrl,
+ *       });
+ *     }
+ *   }, [user]);
+ * }
+ * ```
+ */
+export function useUpsertProfile() {
+  const supabase = useSupabase();
+  const queryClient = useQueryClient();
+
+  return useMutation<Profile, PostgrestError, ProfileInsert>({
+    mutationFn: async (profile) => {
+      const { data, error } = await supabase.from('profiles').upsert(profile, { onConflict: 'id' }).select().single();
+
+      if (error) throw error;
+      return data as Profile;
+    },
+    onSuccess: () => {
+      // Invalidate profile queries to refetch fresh data
+      queryClient.invalidateQueries({ queryKey: ['supabase', 'profiles'] });
+    },
+  });
+}
+
+/**
+ * Hook to update the current user's profile.
+ *
+ * Only updates the specified fields, leaving others unchanged.
+ *
+ * @example
+ * ```tsx
+ * function EditProfileForm() {
+ *   const updateProfile = useUpdateProfile();
+ *
+ *   const handleSubmit = (values: ProfileUpdate) => {
+ *     updateProfile.mutate(values, {
+ *       onSuccess: () => toast.success('Profile updated!'),
+ *       onError: (error) => toast.error(error.message),
+ *     });
+ *   };
+ * }
+ * ```
+ */
+export function useUpdateProfile() {
+  const { user } = useUser();
+  const supabase = useSupabase();
+  const queryClient = useQueryClient();
+
+  return useMutation<Profile, PostgrestError, ProfileUpdate>({
+    mutationFn: async (updates) => {
+      if (!user?.id) {
+        throw new Error('No authenticated user');
+      }
+
+      const { data, error } = await supabase.from('profiles').update(updates).eq('id', user.id).select().single();
+
+      if (error) throw error;
+      return data as Profile;
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['supabase', 'profiles'] });
+    },
+  });
+}
+
+/**
+ * Hook to delete the current user's profile.
+ *
+ * Use with caution - this permanently removes the user's profile data.
+ *
+ * @example
+ * ```tsx
+ * function DeleteAccountButton() {
+ *   const deleteProfile = useDeleteProfile();
+ *
+ *   const handleDelete = async () => {
+ *     if (confirm('Are you sure? This cannot be undone.')) {
+ *       await deleteProfile.mutateAsync();
+ *       // User should be signed out after deletion
+ *     }
+ *   };
+ * }
+ * ```
+ */
+export function useDeleteProfile() {
+  const { user } = useUser();
+  const supabase = useSupabase();
+  const queryClient = useQueryClient();
+
+  return useMutation<void, PostgrestError, void>({
+    mutationFn: async () => {
+      if (!user?.id) {
+        throw new Error('No authenticated user');
+      }
+
+      const { error } = await supabase.from('profiles').delete().eq('id', user.id);
+
+      if (error) throw error;
+    },
+    onSuccess: () => {
+      queryClient.removeQueries({ queryKey: ['supabase', 'profiles'] });
+    },
+  });
+}

package/templates/src/hooks/supabase/useSupabaseQuery.test.tsx

@@ -0,0 +1,150 @@
+import { QueryClientProvider } from '@tanstack/react-query';
+import { renderHook, waitFor } from '@testing-library/react';
+import type { ReactNode } from 'react';
+import { describe, it, expect, beforeEach } from 'vitest';
+
+import {
+  createTestQueryClient,
+  createProfile,
+  setMockSupabaseData,
+  setMockSupabaseError,
+  resetSupabaseMocks,
+} from '@/test';
+import type { Profile } from '@/types/database';
+
+import { useSupabaseQuery } from './useSupabaseQuery';
+
+function createWrapper() {
+  const queryClient = createTestQueryClient();
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
+  };
+}
+
+describe('useSupabaseQuery', () => {
+  beforeEach(() => {
+    resetSupabaseMocks();
+  });
+
+  it('returns empty array when no data', async () => {
+    setMockSupabaseData([]);
+
+    const { result } = renderHook(
+      () =>
+        useSupabaseQuery<Profile>({
+          table: 'profiles',
+          queryKey: ['test'],
+        }),
+      { wrapper: createWrapper() },
+    );
+
+    await waitFor(() => {
+      expect(result.current.isSuccess).toBe(true);
+    });
+
+    expect(result.current.data).toEqual([]);
+  });
+
+  it('returns data when available', async () => {
+    const profile = createProfile({ id: 'user-1', full_name: 'Test User' });
+    setMockSupabaseData([profile]);
+
+    const { result } = renderHook(
+      () =>
+        useSupabaseQuery<Profile>({
+          table: 'profiles',
+          queryKey: ['test'],
+        }),
+      { wrapper: createWrapper() },
+    );
+
+    await waitFor(() => {
+      expect(result.current.isSuccess).toBe(true);
+    });
+
+    expect(result.current.data).toHaveLength(1);
+    expect(result.current.data?.[0].full_name).toBe('Test User');
+  });
+
+  it('returns error when query fails', async () => {
+    setMockSupabaseError({ message: 'Database error', code: 'DB_ERROR' });
+
+    const { result } = renderHook(
+      () =>
+        useSupabaseQuery<Profile>({
+          table: 'profiles',
+          queryKey: ['test-error'],
+          queryOptions: { retry: false },
+        }),
+      { wrapper: createWrapper() },
+    );
+
+    await waitFor(() => {
+      expect(result.current.isError).toBe(true);
+    });
+
+    expect(result.current.error?.message).toBe('Database error');
+  });
+
+  it('applies custom select', async () => {
+    const profile = createProfile({ id: 'user-1' });
+    setMockSupabaseData([profile]);
+
+    const { result } = renderHook(
+      () =>
+        useSupabaseQuery<Profile>({
+          table: 'profiles',
+          select: 'id, full_name',
+          queryKey: ['test-select'],
+        }),
+      { wrapper: createWrapper() },
+    );
+
+    await waitFor(() => {
+      expect(result.current.isSuccess).toBe(true);
+    });
+
+    expect(result.current.data).toBeDefined();
+  });
+
+  it('applies filter function', async () => {
+    const profile = createProfile({ id: 'user-1' });
+    setMockSupabaseData([profile]);
+
+    const { result } = renderHook(
+      () =>
+        useSupabaseQuery<Profile>({
+          table: 'profiles',
+          filter: (query) => query.eq('id', 'user-1'),
+          queryKey: ['test-filter'],
+        }),
+      { wrapper: createWrapper() },
+    );
+
+    await waitFor(() => {
+      expect(result.current.isSuccess).toBe(true);
+    });
+
+    expect(result.current.data).toHaveLength(1);
+  });
+
+  it('respects enabled option', async () => {
+    const profile = createProfile();
+    setMockSupabaseData([profile]);
+
+    const { result } = renderHook(
+      () =>
+        useSupabaseQuery<Profile>({
+          table: 'profiles',
+          queryKey: ['test-disabled'],
+          queryOptions: { enabled: false },
+        }),
+      { wrapper: createWrapper() },
+    );
+
+    // Query should not run when disabled
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.isFetching).toBe(false);
+    expect(result.current.data).toBeUndefined();
+  });
+});

package/templates/src/hooks/supabase/useSupabaseQuery.ts

@@ -0,0 +1,91 @@
+/**
+ * Generic Supabase query hook with TanStack Query integration.
+ *
+ * Provides type-safe database queries with automatic Clerk authentication
+ * and RLS policy enforcement.
+ */
+
+import { useQuery, type UseQueryOptions, type UseQueryResult } from '@tanstack/react-query';
+import type { PostgrestError } from '@supabase/supabase-js';
+
+import { useSupabase } from '@/contexts/supabaseContext';
+import type { TableName } from '@/types/database';
+
+/**
+ * Options for useSupabaseQuery hook.
+ */
+export interface UseSupabaseQueryOptions<TData> {
+  /** The database table to query */
+  table: TableName;
+  /** Columns to select (defaults to '*') */
+  select?: string;
+  /** Optional filter function to apply conditions */
+  filter?: (query: ReturnType<ReturnType<typeof useSupabase>['from']>) => unknown;
+  /** Unique query key for caching (will be prefixed with ['supabase', table]) */
+  queryKey: string[];
+  /** Additional TanStack Query options */
+  queryOptions?: Omit<UseQueryOptions<TData[], PostgrestError>, 'queryKey' | 'queryFn'>;
+}
+
+/**
+ * Generic hook for Supabase SELECT queries with TanStack Query.
+ *
+ * Automatically applies Clerk authentication via the Supabase context,
+ * ensuring RLS policies are enforced based on the current user.
+ *
+ * @example
+ * ```tsx
+ * // Simple query - fetch all user's profiles
+ * const { data, isLoading } = useSupabaseQuery<Profile>({
+ *   table: 'profiles',
+ *   queryKey: ['all'],
+ * });
+ *
+ * // Query with filter
+ * const { data } = useSupabaseQuery<Profile>({
+ *   table: 'profiles',
+ *   select: 'id, full_name, avatar_url',
+ *   filter: (query) => query.eq('id', userId),
+ *   queryKey: ['single', userId],
+ * });
+ *
+ * // Query with custom options
+ * const { data } = useSupabaseQuery<Profile>({
+ *   table: 'profiles',
+ *   queryKey: ['current'],
+ *   queryOptions: {
+ *     staleTime: 1000 * 60 * 10, // 10 minutes
+ *     enabled: !!userId,
+ *   },
+ * });
+ * ```
+ */
+export function useSupabaseQuery<TData>({
+  table,
+  select = '*',
+  filter,
+  queryKey,
+  queryOptions,
+}: UseSupabaseQueryOptions<TData>): UseQueryResult<TData[], PostgrestError> {
+  const supabase = useSupabase();
+
+  return useQuery<TData[], PostgrestError>({
+    queryKey: ['supabase', table, ...queryKey],
+    queryFn: async () => {
+      let query = supabase.from(table).select(select);
+
+      if (filter) {
+        query = filter(query) as typeof query;
+      }
+
+      const { data, error } = await query;
+
+      if (error) {
+        throw error;
+      }
+
+      return (data ?? []) as TData[];
+    },
+    ...queryOptions,
+  });
+}