@nimbleflux/fluxbase-sdk-react 2026.3.6-rc.1

package/src/use-saml.test.ts

@@ -0,0 +1,269 @@
+/**
+ * Tests for SAML SSO hooks
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { renderHook, waitFor, act } from '@testing-library/react';
+import {
+  useSAMLProviders,
+  useGetSAMLLoginUrl,
+  useSignInWithSAML,
+  useHandleSAMLCallback,
+  useSAMLMetadataUrl,
+} from './use-saml';
+import { createMockClient, createWrapper, createTestQueryClient } from './test-utils';
+
+describe('useSAMLProviders', () => {
+  it('should fetch SAML providers', async () => {
+    const mockProviders = [
+      { id: '1', name: 'okta', display_name: 'Okta' },
+      { id: '2', name: 'azure', display_name: 'Azure AD' },
+    ];
+    const getSAMLProvidersMock = vi.fn().mockResolvedValue({
+      data: { providers: mockProviders },
+      error: null,
+    });
+
+    const client = createMockClient({
+      auth: { getSAMLProviders: getSAMLProvidersMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useSAMLProviders(),
+      { wrapper: createWrapper(client) }
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.data).toEqual(mockProviders);
+  });
+
+  it('should throw error on fetch failure', async () => {
+    const error = new Error('Failed to fetch');
+    const getSAMLProvidersMock = vi.fn().mockResolvedValue({ data: null, error });
+
+    const client = createMockClient({
+      auth: { getSAMLProviders: getSAMLProvidersMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useSAMLProviders(),
+      { wrapper: createWrapper(client) }
+    );
+
+    await waitFor(() => expect(result.current.isError).toBe(true));
+    expect(result.current.error).toBe(error);
+  });
+});
+
+describe('useGetSAMLLoginUrl', () => {
+  it('should get SAML login URL', async () => {
+    const mockUrl = 'https://idp.example.com/sso/saml?SAMLRequest=...';
+    const getSAMLLoginUrlMock = vi.fn().mockResolvedValue({
+      data: { url: mockUrl },
+      error: null,
+    });
+
+    const client = createMockClient({
+      auth: { getSAMLLoginUrl: getSAMLLoginUrlMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useGetSAMLLoginUrl(),
+      { wrapper: createWrapper(client) }
+    );
+
+    await act(async () => {
+      await result.current.mutateAsync({
+        provider: 'okta',
+        options: { redirectUrl: 'https://app.example.com/callback' },
+      });
+    });
+
+    expect(getSAMLLoginUrlMock).toHaveBeenCalledWith('okta', {
+      redirectUrl: 'https://app.example.com/callback',
+    });
+  });
+
+  it('should get SAML login URL without options', async () => {
+    const getSAMLLoginUrlMock = vi.fn().mockResolvedValue({
+      data: { url: 'https://idp.example.com/sso' },
+      error: null,
+    });
+
+    const client = createMockClient({
+      auth: { getSAMLLoginUrl: getSAMLLoginUrlMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useGetSAMLLoginUrl(),
+      { wrapper: createWrapper(client) }
+    );
+
+    await act(async () => {
+      await result.current.mutateAsync({ provider: 'okta' });
+    });
+
+    expect(getSAMLLoginUrlMock).toHaveBeenCalledWith('okta', undefined);
+  });
+});
+
+describe('useSignInWithSAML', () => {
+  it('should initiate SAML sign in', async () => {
+    const signInWithSAMLMock = vi.fn().mockResolvedValue({ data: null, error: null });
+
+    const client = createMockClient({
+      auth: { signInWithSAML: signInWithSAMLMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useSignInWithSAML(),
+      { wrapper: createWrapper(client) }
+    );
+
+    await act(async () => {
+      await result.current.mutateAsync({ provider: 'okta' });
+    });
+
+    expect(signInWithSAMLMock).toHaveBeenCalledWith('okta', undefined);
+  });
+
+  it('should pass options to sign in', async () => {
+    const signInWithSAMLMock = vi.fn().mockResolvedValue({ data: null, error: null });
+
+    const client = createMockClient({
+      auth: { signInWithSAML: signInWithSAMLMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useSignInWithSAML(),
+      { wrapper: createWrapper(client) }
+    );
+
+    await act(async () => {
+      await result.current.mutateAsync({
+        provider: 'okta',
+        options: { redirectUrl: 'https://app.example.com' },
+      });
+    });
+
+    expect(signInWithSAMLMock).toHaveBeenCalledWith('okta', {
+      redirectUrl: 'https://app.example.com',
+    });
+  });
+});
+
+describe('useHandleSAMLCallback', () => {
+  it('should handle SAML callback successfully', async () => {
+    const mockResult = {
+      data: {
+        user: { id: '1', email: 'user@example.com' },
+        session: { access_token: 'token' },
+      },
+      error: null,
+    };
+    const handleSAMLCallbackMock = vi.fn().mockResolvedValue(mockResult);
+
+    const client = createMockClient({
+      auth: { handleSAMLCallback: handleSAMLCallbackMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useHandleSAMLCallback(),
+      { wrapper: createWrapper(client) }
+    );
+
+    let response;
+    await act(async () => {
+      response = await result.current.mutateAsync({ samlResponse: 'base64-response' });
+    });
+
+    expect(handleSAMLCallbackMock).toHaveBeenCalledWith('base64-response', undefined);
+    expect(response).toEqual(mockResult);
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+  });
+
+  it('should pass provider to callback handler', async () => {
+    const handleSAMLCallbackMock = vi.fn().mockResolvedValue({
+      data: { user: {}, session: {} },
+      error: null,
+    });
+
+    const client = createMockClient({
+      auth: { handleSAMLCallback: handleSAMLCallbackMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useHandleSAMLCallback(),
+      { wrapper: createWrapper(client) }
+    );
+
+    await act(async () => {
+      await result.current.mutateAsync({
+        samlResponse: 'base64-response',
+        provider: 'okta',
+      });
+    });
+
+    expect(handleSAMLCallbackMock).toHaveBeenCalledWith('base64-response', 'okta');
+  });
+
+  it('should not update cache when no data', async () => {
+    const handleSAMLCallbackMock = vi.fn().mockResolvedValue({
+      data: null,
+      error: null,
+    });
+
+    const client = createMockClient({
+      auth: { handleSAMLCallback: handleSAMLCallbackMock },
+    } as any);
+
+    const queryClient = createTestQueryClient();
+    const { result } = renderHook(
+      () => useHandleSAMLCallback(),
+      { wrapper: createWrapper(client, queryClient) }
+    );
+
+    await act(async () => {
+      await result.current.mutateAsync({ samlResponse: 'base64-response' });
+    });
+
+    // Cache should not be updated
+    expect(queryClient.getQueryData(['fluxbase', 'auth', 'session'])).toBeUndefined();
+  });
+});
+
+describe('useSAMLMetadataUrl', () => {
+  it('should return metadata URL generator function', () => {
+    const getSAMLMetadataUrlMock = vi.fn().mockReturnValue('https://api.example.com/saml/metadata/okta');
+
+    const client = createMockClient({
+      auth: { getSAMLMetadataUrl: getSAMLMetadataUrlMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useSAMLMetadataUrl(),
+      { wrapper: createWrapper(client) }
+    );
+
+    const url = result.current('okta');
+
+    expect(getSAMLMetadataUrlMock).toHaveBeenCalledWith('okta');
+    expect(url).toBe('https://api.example.com/saml/metadata/okta');
+  });
+
+  it('should work with different providers', () => {
+    const getSAMLMetadataUrlMock = vi.fn().mockImplementation((provider) => `https://api.example.com/saml/metadata/${provider}`);
+
+    const client = createMockClient({
+      auth: { getSAMLMetadataUrl: getSAMLMetadataUrlMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useSAMLMetadataUrl(),
+      { wrapper: createWrapper(client) }
+    );
+
+    expect(result.current('okta')).toBe('https://api.example.com/saml/metadata/okta');
+    expect(result.current('azure')).toBe('https://api.example.com/saml/metadata/azure');
+  });
+});

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);
+  };
+}