@fluxbase/sdk-react 0.0.7-rc.11 → 2026.1.1-rc.1

package/src/{use-api-keys.ts → use-client-keys.ts}

@@ -1,20 +1,20 @@
 import { useState, useEffect, useCallback } from 'react'
 import { useFluxbaseClient } from './context'
-import type { APIKey, CreateAPIKeyRequest } from '@fluxbase/sdk'
+import type { ClientKey, CreateClientKeyRequest } from '@fluxbase/sdk'
 
-export interface UseAPIKeysOptions {
+export interface UseClientKeysOptions {
   /**
-   * Whether to automatically fetch API keys on mount
+   * Whether to automatically fetch client keys on mount
    * @default true
    */
   autoFetch?: boolean
 }
 
-export interface UseAPIKeysReturn {
+export interface UseClientKeysReturn {
   /**
-   * Array of API keys
+   * Array of client keys
    */
-  keys: APIKey[]
+  keys: ClientKey[]
 
   /**
    * Whether keys are being fetched
@@ -27,45 +27,45 @@ export interface UseAPIKeysReturn {
   error: Error | null
 
   /**
-   * Refetch API keys
+   * Refetch client keys
    */
   refetch: () => Promise<void>
 
   /**
-   * Create a new API key
+   * Create a new client key
    */
-  createKey: (request: CreateAPIKeyRequest) => Promise<{ key: string; keyData: APIKey }>
+  createKey: (request: CreateClientKeyRequest) => Promise<{ key: string; keyData: ClientKey }>
 
   /**
-   * Update an API key
+   * Update a client key
    */
   updateKey: (keyId: string, update: { name?: string; description?: string }) => Promise<void>
 
   /**
-   * Revoke an API key
+   * Revoke a client key
    */
   revokeKey: (keyId: string) => Promise<void>
 
   /**
-   * Delete an API key
+   * Delete a client key
    */
   deleteKey: (keyId: string) => Promise<void>
 }
 
 /**
- * Hook for managing API keys
+ * Hook for managing client keys
  *
- * Provides API key list and management functions.
+ * Provides client key list and management functions.
  *
  * @example
  * ```tsx
- * function APIKeyManager() {
- *   const { keys, isLoading, createKey, revokeKey } = useAPIKeys()
+ * function ClientKeyManager() {
+ *   const { keys, isLoading, createKey, revokeKey } = useClientKeys()
  *
  *   const handleCreate = async () => {
  *     const { key, keyData } = await createKey({
  *       name: 'Backend Service',
- *       description: 'API key for backend',
+ *       description: 'Client key for backend',
  *       expires_at: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000).toISOString()
  *     })
  *     alert(`Key created: ${key}`)
@@ -85,23 +85,23 @@ export interface UseAPIKeysReturn {
  * }
  * ```
  */
-export function useAPIKeys(options: UseAPIKeysOptions = {}): UseAPIKeysReturn {
+export function useClientKeys(options: UseClientKeysOptions = {}): UseClientKeysReturn {
   const { autoFetch = true } = options
   const client = useFluxbaseClient()
 
-  const [keys, setKeys] = useState<APIKey[]>([])
+  const [keys, setKeys] = useState<ClientKey[]>([])
   const [isLoading, setIsLoading] = useState(autoFetch)
   const [error, setError] = useState<Error | null>(null)
 
   /**
-   * Fetch API keys from API
+   * Fetch client keys from API
    */
   const fetchKeys = useCallback(async () => {
     try {
       setIsLoading(true)
       setError(null)
-      const response = await client.admin.management.apiKeys.list()
-      setKeys(response.api_keys)
+      const response = await client.admin.management.clientKeys.list()
+      setKeys(response.client_keys)
     } catch (err) {
       setError(err as Error)
     } finally {
@@ -110,45 +110,45 @@ export function useAPIKeys(options: UseAPIKeysOptions = {}): UseAPIKeysReturn {
   }, [client])
 
   /**
-   * Create a new API key
+   * Create a new client key
    */
   const createKey = useCallback(
-    async (request: CreateAPIKeyRequest): Promise<{ key: string; keyData: APIKey }> => {
-      const response = await client.admin.management.apiKeys.create(request)
+    async (request: CreateClientKeyRequest): Promise<{ key: string; keyData: ClientKey }> => {
+      const response = await client.admin.management.clientKeys.create(request)
       await fetchKeys() // Refresh list
-      return { key: response.key, keyData: response.api_key }
+      return { key: response.key, keyData: response.client_key }
     },
     [client, fetchKeys]
   )
 
   /**
-   * Update an API key
+   * Update a client key
    */
   const updateKey = useCallback(
     async (keyId: string, update: { name?: string; description?: string }): Promise<void> => {
-      await client.admin.management.apiKeys.update(keyId, update)
+      await client.admin.management.clientKeys.update(keyId, update)
       await fetchKeys() // Refresh list
     },
     [client, fetchKeys]
   )
 
   /**
-   * Revoke an API key
+   * Revoke a client key
    */
   const revokeKey = useCallback(
     async (keyId: string): Promise<void> => {
-      await client.admin.management.apiKeys.revoke(keyId)
+      await client.admin.management.clientKeys.revoke(keyId)
       await fetchKeys() // Refresh list
     },
     [client, fetchKeys]
   )
 
   /**
-   * Delete an API key
+   * Delete a client key
    */
   const deleteKey = useCallback(
     async (keyId: string): Promise<void> => {
-      await client.admin.management.apiKeys.delete(keyId)
+      await client.admin.management.clientKeys.delete(keyId)
       await fetchKeys() // Refresh list
     },
     [client, fetchKeys]
@@ -172,3 +172,14 @@ export function useAPIKeys(options: UseAPIKeysOptions = {}): UseAPIKeysReturn {
     deleteKey
   }
 }
+
+/**
+ * @deprecated Use useClientKeys instead
+ */
+export const useAPIKeys = useClientKeys
+
+/** @deprecated Use UseClientKeysOptions instead */
+export type UseAPIKeysOptions = UseClientKeysOptions
+
+/** @deprecated Use UseClientKeysReturn instead */
+export type UseAPIKeysReturn = UseClientKeysReturn

package/src/use-graphql.ts

@@ -0,0 +1,392 @@
+/**
+ * GraphQL hooks for Fluxbase React SDK
+ *
+ * Provides React Query integration for GraphQL queries and mutations.
+ *
+ * @example
+ * ```tsx
+ * import { useGraphQLQuery, useGraphQLMutation } from '@fluxbase/sdk-react'
+ *
+ * function UsersList() {
+ *   const { data, isLoading, error } = useGraphQLQuery<UsersQuery>(
+ *     'users-list',
+ *     `query { users { id email } }`
+ *   )
+ *
+ *   if (isLoading) return <div>Loading...</div>
+ *   if (error) return <div>Error: {error.message}</div>
+ *
+ *   return (
+ *     <ul>
+ *       {data?.users.map(user => (
+ *         <li key={user.id}>{user.email}</li>
+ *       ))}
+ *     </ul>
+ *   )
+ * }
+ * ```
+ */
+
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useFluxbaseClient } from "./context";
+import type {
+  GraphQLResponse,
+  GraphQLError,
+  GraphQLRequestOptions,
+} from "@fluxbase/sdk";
+
+/**
+ * Options for useGraphQLQuery hook
+ */
+export interface UseGraphQLQueryOptions<T> {
+  /**
+   * Variables to pass to the GraphQL query
+   */
+  variables?: Record<string, unknown>;
+
+  /**
+   * Operation name when the document contains multiple operations
+   */
+  operationName?: string;
+
+  /**
+   * Additional request options
+   */
+  requestOptions?: GraphQLRequestOptions;
+
+  /**
+   * Whether the query is enabled
+   * @default true
+   */
+  enabled?: boolean;
+
+  /**
+   * Time in milliseconds after which the query is considered stale
+   * @default 0 (considered stale immediately)
+   */
+  staleTime?: number;
+
+  /**
+   * Time in milliseconds after which inactive query data is garbage collected
+   * @default 5 minutes
+   */
+  gcTime?: number;
+
+  /**
+   * Whether to refetch on window focus
+   * @default true
+   */
+  refetchOnWindowFocus?: boolean;
+
+  /**
+   * Transform function to process the response data
+   */
+  select?: (data: T | undefined) => T | undefined;
+}
+
+/**
+ * Options for useGraphQLMutation hook
+ */
+export interface UseGraphQLMutationOptions<T, V> {
+  /**
+   * Operation name when the document contains multiple operations
+   */
+  operationName?: string;
+
+  /**
+   * Additional request options
+   */
+  requestOptions?: GraphQLRequestOptions;
+
+  /**
+   * Callback when mutation succeeds
+   */
+  onSuccess?: (data: T, variables: V) => void;
+
+  /**
+   * Callback when mutation fails
+   */
+  onError?: (error: GraphQLError, variables: V) => void;
+
+  /**
+   * Query keys to invalidate on success
+   */
+  invalidateQueries?: string[];
+}
+
+/**
+ * Hook to execute GraphQL queries with React Query caching
+ *
+ * @typeParam T - The expected response data type
+ * @param queryKey - Unique key for caching (string or array)
+ * @param query - The GraphQL query string
+ * @param options - Query options including variables
+ * @returns React Query result object
+ *
+ * @example
+ * ```tsx
+ * interface UsersQuery {
+ *   users: Array<{ id: string; email: string }>
+ * }
+ *
+ * function UsersList() {
+ *   const { data, isLoading } = useGraphQLQuery<UsersQuery>(
+ *     'users',
+ *     `query { users { id email } }`
+ *   )
+ *
+ *   return <div>{data?.users.length} users</div>
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With variables
+ * const { data } = useGraphQLQuery<UserQuery>(
+ *   ['user', userId],
+ *   `query GetUser($id: ID!) { user(id: $id) { id email } }`,
+ *   { variables: { id: userId } }
+ * )
+ * ```
+ */
+export function useGraphQLQuery<T = unknown>(
+  queryKey: string | readonly unknown[],
+  query: string,
+  options?: UseGraphQLQueryOptions<T>
+) {
+  const client = useFluxbaseClient();
+  const normalizedKey = Array.isArray(queryKey)
+    ? ["fluxbase", "graphql", ...queryKey]
+    : ["fluxbase", "graphql", queryKey];
+
+  return useQuery<T | undefined, GraphQLError>({
+    queryKey: normalizedKey,
+    queryFn: async () => {
+      const response: GraphQLResponse<T> = await client.graphql.execute(
+        query,
+        options?.variables,
+        options?.operationName,
+        options?.requestOptions
+      );
+
+      if (response.errors && response.errors.length > 0) {
+        throw response.errors[0];
+      }
+
+      return response.data;
+    },
+    enabled: options?.enabled ?? true,
+    staleTime: options?.staleTime ?? 0,
+    gcTime: options?.gcTime,
+    refetchOnWindowFocus: options?.refetchOnWindowFocus ?? true,
+    select: options?.select,
+  });
+}
+
+/**
+ * Hook to execute GraphQL mutations
+ *
+ * @typeParam T - The expected response data type
+ * @typeParam V - The variables type
+ * @param mutation - The GraphQL mutation string
+ * @param options - Mutation options
+ * @returns React Query mutation result object
+ *
+ * @example
+ * ```tsx
+ * interface CreateUserMutation {
+ *   insertUser: { id: string; email: string }
+ * }
+ *
+ * interface CreateUserVariables {
+ *   data: { email: string }
+ * }
+ *
+ * function CreateUserForm() {
+ *   const mutation = useGraphQLMutation<CreateUserMutation, CreateUserVariables>(
+ *     `mutation CreateUser($data: UserInput!) {
+ *       insertUser(data: $data) { id email }
+ *     }`,
+ *     {
+ *       onSuccess: (data) => console.log('Created:', data.insertUser),
+ *       invalidateQueries: ['users']
+ *     }
+ *   )
+ *
+ *   const handleSubmit = (email: string) => {
+ *     mutation.mutate({ data: { email } })
+ *   }
+ *
+ *   return (
+ *     <button
+ *       onClick={() => handleSubmit('new@example.com')}
+ *       disabled={mutation.isPending}
+ *     >
+ *       Create User
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
+export function useGraphQLMutation<
+  T = unknown,
+  V extends Record<string, unknown> = Record<string, unknown>,
+>(mutation: string, options?: UseGraphQLMutationOptions<T, V>) {
+  const client = useFluxbaseClient();
+  const queryClient = useQueryClient();
+
+  return useMutation<T | undefined, GraphQLError, V>({
+    mutationFn: async (variables: V) => {
+      const response: GraphQLResponse<T> = await client.graphql.execute(
+        mutation,
+        variables,
+        options?.operationName,
+        options?.requestOptions
+      );
+
+      if (response.errors && response.errors.length > 0) {
+        throw response.errors[0];
+      }
+
+      return response.data;
+    },
+    onSuccess: (data, variables) => {
+      // Invalidate specified queries
+      if (options?.invalidateQueries) {
+        for (const key of options.invalidateQueries) {
+          queryClient.invalidateQueries({
+            queryKey: ["fluxbase", "graphql", key],
+          });
+        }
+      }
+
+      // Call user's onSuccess callback
+      if (options?.onSuccess && data !== undefined) {
+        options.onSuccess(data, variables);
+      }
+    },
+    onError: (error, variables) => {
+      if (options?.onError) {
+        options.onError(error, variables);
+      }
+    },
+  });
+}
+
+/**
+ * Hook to fetch the GraphQL schema via introspection
+ *
+ * @param options - Query options
+ * @returns React Query result with schema introspection data
+ *
+ * @example
+ * ```tsx
+ * function SchemaExplorer() {
+ *   const { data, isLoading } = useGraphQLIntrospection()
+ *
+ *   if (isLoading) return <div>Loading schema...</div>
+ *
+ *   return (
+ *     <div>
+ *       <p>Query type: {data?.__schema.queryType.name}</p>
+ *       <p>Types: {data?.__schema.types.length}</p>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function useGraphQLIntrospection(options?: {
+  enabled?: boolean;
+  staleTime?: number;
+  requestOptions?: GraphQLRequestOptions;
+}) {
+  const client = useFluxbaseClient();
+
+  return useQuery({
+    queryKey: ["fluxbase", "graphql", "__introspection"],
+    queryFn: async () => {
+      const response = await client.graphql.introspect(options?.requestOptions);
+
+      if (response.errors && response.errors.length > 0) {
+        throw response.errors[0];
+      }
+
+      return response.data;
+    },
+    enabled: options?.enabled ?? true,
+    staleTime: options?.staleTime ?? 1000 * 60 * 5, // 5 minutes - schema doesn't change often
+  });
+}
+
+/**
+ * Hook to execute raw GraphQL operations (query or mutation)
+ *
+ * This is a lower-level hook that doesn't use React Query caching.
+ * Useful for one-off operations or when you need full control.
+ *
+ * @returns Functions to execute queries and mutations
+ *
+ * @example
+ * ```tsx
+ * function AdminPanel() {
+ *   const { executeQuery, executeMutation } = useGraphQL()
+ *
+ *   const handleExport = async () => {
+ *     const result = await executeQuery<ExportData>(
+ *       `query { exportAllData { url } }`
+ *     )
+ *     if (result.data) {
+ *       window.open(result.data.exportAllData.url)
+ *     }
+ *   }
+ *
+ *   return <button onClick={handleExport}>Export Data</button>
+ * }
+ * ```
+ */
+export function useGraphQL() {
+  const client = useFluxbaseClient();
+
+  return {
+    /**
+     * Execute a GraphQL query
+     */
+    executeQuery: <T = unknown>(
+      query: string,
+      variables?: Record<string, unknown>,
+      options?: GraphQLRequestOptions
+    ): Promise<GraphQLResponse<T>> => {
+      return client.graphql.query<T>(query, variables, options);
+    },
+
+    /**
+     * Execute a GraphQL mutation
+     */
+    executeMutation: <T = unknown>(
+      mutation: string,
+      variables?: Record<string, unknown>,
+      options?: GraphQLRequestOptions
+    ): Promise<GraphQLResponse<T>> => {
+      return client.graphql.mutation<T>(mutation, variables, options);
+    },
+
+    /**
+     * Execute a GraphQL operation with an explicit operation name
+     */
+    execute: <T = unknown>(
+      document: string,
+      variables?: Record<string, unknown>,
+      operationName?: string,
+      options?: GraphQLRequestOptions
+    ): Promise<GraphQLResponse<T>> => {
+      return client.graphql.execute<T>(document, variables, operationName, options);
+    },
+
+    /**
+     * Fetch the GraphQL schema via introspection
+     */
+    introspect: (options?: GraphQLRequestOptions) => {
+      return client.graphql.introspect(options);
+    },
+  };
+}