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

package/src/use-realtime.ts

@@ -2,99 +2,113 @@
  * Realtime subscription hooks for Fluxbase SDK
  */
 
-import { useEffect, useRef } from 'react'
-import { useQueryClient } from '@tanstack/react-query'
-import { useFluxbaseClient } from './context'
-import type { RealtimeCallback, RealtimeChangePayload } from '@fluxbase/sdk'
+import { useEffect, useRef } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { useFluxbaseClient } from "./context";
+import type {
+  RealtimeCallback,
+  RealtimePostgresChangesPayload,
+} from "@fluxbase/sdk";
 
 export interface UseRealtimeOptions {
   /**
    * The channel name (e.g., 'table:public.products')
    */
-  channel: string
+  channel: string;
 
   /**
    * Event type to listen for ('INSERT', 'UPDATE', 'DELETE', or '*' for all)
    */
-  event?: 'INSERT' | 'UPDATE' | 'DELETE' | '*'
+  event?: "INSERT" | "UPDATE" | "DELETE" | "*";
 
   /**
    * Callback function when an event is received
    */
-  callback?: RealtimeCallback
+  callback?: RealtimeCallback;
 
   /**
    * Whether to automatically invalidate queries for the table
    * Default: true
    */
-  autoInvalidate?: boolean
+  autoInvalidate?: boolean;
 
   /**
    * Custom query key to invalidate (if autoInvalidate is true)
    * Default: ['fluxbase', 'table', tableName]
    */
-  invalidateKey?: unknown[]
+  invalidateKey?: unknown[];
 
   /**
    * Whether the subscription is enabled
    * Default: true
    */
-  enabled?: boolean
+  enabled?: boolean;
 }
 
 /**
  * Hook to subscribe to realtime changes for a channel
  */
 export function useRealtime(options: UseRealtimeOptions) {
-  const client = useFluxbaseClient()
-  const queryClient = useQueryClient()
-  const channelRef = useRef<ReturnType<typeof client.realtime.channel> | null>(null)
+  const client = useFluxbaseClient();
+  const queryClient = useQueryClient();
+  const channelRef = useRef<ReturnType<typeof client.realtime.channel> | null>(
+    null,
+  );
 
   const {
     channel: channelName,
-    event = '*',
+    event = "*",
     callback,
     autoInvalidate = true,
     invalidateKey,
     enabled = true,
-  } = options
+  } = options;
 
   useEffect(() => {
     if (!enabled) {
-      return
+      return;
     }
 
     // Create channel and subscribe
-    const channel = client.realtime.channel(channelName)
-    channelRef.current = channel
+    const channel = client.realtime.channel(channelName);
+    channelRef.current = channel;
 
-    const handleChange = (payload: RealtimeChangePayload) => {
+    const handleChange = (payload: RealtimePostgresChangesPayload) => {
       // Call user callback
       if (callback) {
-        callback(payload)
+        callback(payload);
       }
 
       // Auto-invalidate queries if enabled
       if (autoInvalidate) {
         // Extract table name from channel (e.g., 'table:public.products' -> 'public.products')
-        const tableName = channelName.replace(/^table:/, '')
+        const tableName = channelName.replace(/^table:/, "");
 
-        const key = invalidateKey || ['fluxbase', 'table', tableName]
-        queryClient.invalidateQueries({ queryKey: key })
+        const key = invalidateKey || ["fluxbase", "table", tableName];
+        queryClient.invalidateQueries({ queryKey: key });
       }
-    }
+    };
 
-    channel.on(event, handleChange).subscribe()
+    channel.on(event, handleChange).subscribe();
 
     return () => {
-      channel.unsubscribe()
-      channelRef.current = null
-    }
-  }, [client, channelName, event, callback, autoInvalidate, invalidateKey, queryClient, enabled])
+      channel.unsubscribe();
+      channelRef.current = null;
+    };
+  }, [
+    client,
+    channelName,
+    event,
+    callback,
+    autoInvalidate,
+    invalidateKey,
+    queryClient,
+    enabled,
+  ]);
 
   return {
     channel: channelRef.current,
-  }
+  };
 }
 
 /**
@@ -104,12 +118,12 @@ export function useRealtime(options: UseRealtimeOptions) {
  */
 export function useTableSubscription(
   table: string,
-  options?: Omit<UseRealtimeOptions, 'channel'>
+  options?: Omit<UseRealtimeOptions, "channel">,
 ) {
   return useRealtime({
     ...options,
     channel: `table:${table}`,
-  })
+  });
 }
 
 /**
@@ -117,15 +131,15 @@ export function useTableSubscription(
  */
 export function useTableInserts(
   table: string,
-  callback: (payload: RealtimeChangePayload) => void,
-  options?: Omit<UseRealtimeOptions, 'channel' | 'event' | 'callback'>
+  callback: (payload: RealtimePostgresChangesPayload) => void,
+  options?: Omit<UseRealtimeOptions, "channel" | "event" | "callback">,
 ) {
   return useRealtime({
     ...options,
     channel: `table:${table}`,
-    event: 'INSERT',
+    event: "INSERT",
     callback,
-  })
+  });
 }
 
 /**
@@ -133,15 +147,15 @@ export function useTableInserts(
  */
 export function useTableUpdates(
   table: string,
-  callback: (payload: RealtimeChangePayload) => void,
-  options?: Omit<UseRealtimeOptions, 'channel' | 'event' | 'callback'>
+  callback: (payload: RealtimePostgresChangesPayload) => void,
+  options?: Omit<UseRealtimeOptions, "channel" | "event" | "callback">,
 ) {
   return useRealtime({
     ...options,
     channel: `table:${table}`,
-    event: 'UPDATE',
+    event: "UPDATE",
     callback,
-  })
+  });
 }
 
 /**
@@ -149,13 +163,13 @@ export function useTableUpdates(
  */
 export function useTableDeletes(
   table: string,
-  callback: (payload: RealtimeChangePayload) => void,
-  options?: Omit<UseRealtimeOptions, 'channel' | 'event' | 'callback'>
+  callback: (payload: RealtimePostgresChangesPayload) => void,
+  options?: Omit<UseRealtimeOptions, "channel" | "event" | "callback">,
 ) {
   return useRealtime({
     ...options,
     channel: `table:${table}`,
-    event: 'DELETE',
+    event: "DELETE",
     callback,
-  })
+  });
 }

package/src/use-saml.ts

@@ -0,0 +1,221 @@
+/**
+ * SAML SSO hooks for Fluxbase React SDK
+ */
+
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useFluxbaseClient } from "./context";
+import type { SAMLLoginOptions, SAMLProvider } from "@fluxbase/sdk";
+
+/**
+ * Hook to get available SAML SSO providers
+ *
+ * @example
+ * ```tsx
+ * function SAMLProviderList() {
+ *   const { data: providers, isLoading } = useSAMLProviders()
+ *
+ *   if (isLoading) return <div>Loading...</div>
+ *
+ *   return (
+ *     <div>
+ *       {providers?.map(provider => (
+ *         <button key={provider.id} onClick={() => signInWithSAML(provider.name)}>
+ *           Sign in with {provider.name}
+ *         </button>
+ *       ))}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function useSAMLProviders() {
+  const client = useFluxbaseClient();
+
+  return useQuery<SAMLProvider[]>({
+    queryKey: ["fluxbase", "auth", "saml", "providers"],
+    queryFn: async () => {
+      const { data, error } = await client.auth.getSAMLProviders();
+      if (error) throw error;
+      return data.providers;
+    },
+    staleTime: 1000 * 60 * 5, // 5 minutes - providers don't change often
+  });
+}
+
+/**
+ * Hook to get SAML login URL for a provider
+ *
+ * This hook returns a function to get the login URL for a specific provider.
+ * Use this when you need more control over the redirect behavior.
+ *
+ * @example
+ * ```tsx
+ * function SAMLLoginButton({ provider }: { provider: string }) {
+ *   const getSAMLLoginUrl = useGetSAMLLoginUrl()
+ *
+ *   const handleClick = async () => {
+ *     const { data, error } = await getSAMLLoginUrl.mutateAsync({
+ *       provider,
+ *       options: { redirectUrl: window.location.href }
+ *     })
+ *     if (!error) {
+ *       window.location.href = data.url
+ *     }
+ *   }
+ *
+ *   return <button onClick={handleClick}>Login with {provider}</button>
+ * }
+ * ```
+ */
+export function useGetSAMLLoginUrl() {
+  const client = useFluxbaseClient();
+
+  return useMutation({
+    mutationFn: async ({
+      provider,
+      options,
+    }: {
+      provider: string;
+      options?: SAMLLoginOptions;
+    }) => {
+      return await client.auth.getSAMLLoginUrl(provider, options);
+    },
+  });
+}
+
+/**
+ * Hook to initiate SAML login (redirects to IdP)
+ *
+ * This hook returns a mutation that when called, redirects the user to the
+ * SAML Identity Provider for authentication.
+ *
+ * @example
+ * ```tsx
+ * function SAMLLoginButton() {
+ *   const signInWithSAML = useSignInWithSAML()
+ *
+ *   return (
+ *     <button
+ *       onClick={() => signInWithSAML.mutate({ provider: 'okta' })}
+ *       disabled={signInWithSAML.isPending}
+ *     >
+ *       {signInWithSAML.isPending ? 'Redirecting...' : 'Sign in with Okta'}
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
+export function useSignInWithSAML() {
+  const client = useFluxbaseClient();
+
+  return useMutation({
+    mutationFn: async ({
+      provider,
+      options,
+    }: {
+      provider: string;
+      options?: SAMLLoginOptions;
+    }) => {
+      return await client.auth.signInWithSAML(provider, options);
+    },
+  });
+}
+
+/**
+ * Hook to handle SAML callback after IdP authentication
+ *
+ * Use this in your SAML callback page to complete the authentication flow.
+ *
+ * @example
+ * ```tsx
+ * function SAMLCallbackPage() {
+ *   const handleCallback = useHandleSAMLCallback()
+ *   const navigate = useNavigate()
+ *
+ *   useEffect(() => {
+ *     const params = new URLSearchParams(window.location.search)
+ *     const samlResponse = params.get('SAMLResponse')
+ *
+ *     if (samlResponse) {
+ *       handleCallback.mutate(
+ *         { samlResponse },
+ *         {
+ *           onSuccess: () => navigate('/dashboard'),
+ *           onError: (error) => console.error('SAML login failed:', error)
+ *         }
+ *       )
+ *     }
+ *   }, [])
+ *
+ *   if (handleCallback.isPending) {
+ *     return <div>Completing sign in...</div>
+ *   }
+ *
+ *   if (handleCallback.isError) {
+ *     return <div>Authentication failed: {handleCallback.error.message}</div>
+ *   }
+ *
+ *   return null
+ * }
+ * ```
+ */
+export function useHandleSAMLCallback() {
+  const client = useFluxbaseClient();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async ({
+      samlResponse,
+      provider,
+    }: {
+      samlResponse: string;
+      provider?: string;
+    }) => {
+      return await client.auth.handleSAMLCallback(samlResponse, provider);
+    },
+    onSuccess: (result) => {
+      if (result.data) {
+        // Update auth state in React Query cache
+        queryClient.setQueryData(
+          ["fluxbase", "auth", "session"],
+          result.data.session,
+        );
+        queryClient.setQueryData(
+          ["fluxbase", "auth", "user"],
+          result.data.user,
+        );
+        // Invalidate any dependent queries
+        queryClient.invalidateQueries({ queryKey: ["fluxbase"] });
+      }
+    },
+  });
+}
+
+/**
+ * Hook to get SAML Service Provider metadata URL
+ *
+ * Returns a function that generates the SP metadata URL for a given provider.
+ * Use this URL when configuring your SAML IdP.
+ *
+ * @example
+ * ```tsx
+ * function SAMLSetupInfo({ provider }: { provider: string }) {
+ *   const getSAMLMetadataUrl = useSAMLMetadataUrl()
+ *   const metadataUrl = getSAMLMetadataUrl(provider)
+ *
+ *   return (
+ *     <div>
+ *       <p>SP Metadata URL:</p>
+ *       <code>{metadataUrl}</code>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function useSAMLMetadataUrl() {
+  const client = useFluxbaseClient();
+
+  return (provider: string): string => {
+    return client.auth.getSAMLMetadataUrl(provider);
+  };
+}