@blocksdiy/blocks-client-sdk 1.0.0

package/dist/ReactClientSdk.jsx

@@ -0,0 +1,1238 @@
+import { FatalAppError } from "@blockscom/blocks-client-api/errors";
+import { useWebsockets, useWebsocketsAppSubscribe } from "@blockscom/blocks-client-api/websocketService";
+import { websocketsService } from "@blockscom/blocks-client-api/websocketService";
+import { useAiStreamChunks } from "@blockscom/react-common/useAiStreamChunks";
+import { QueryClient, QueryClientProvider, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
+import { ClientSdk } from "./ClientSdk.js";
+export class ReactClientSdk extends ClientSdk {
+}
+const ENTITIES_QUERY_KEY = "entities";
+const CURRENT_USER_QUERY_KEY = "currentUser";
+const ClientContext = createContext(null);
+const ThemeModeContext = createContext({
+    themeMode: "system",
+    setThemeMode: () => { },
+});
+const EXECUTE_ACTION_WINDOWS = [{ duration: 20000, maxCount: 5, withData: true }];
+const ENTITY_OPERATION_WINDOWS = [{ duration: 5000, maxCount: 5, withData: true }];
+const ENTITY_ROW_OPERATION_WINDOWS = [
+    { duration: 5000, maxCount: 5, withData: true },
+    { duration: 10000, maxCount: 15, withData: false },
+];
+/* public decouple - blocks common */
+const USERS_TABLE_BLOCK_ID = "68760b42d4ce152c91ce0e1c";
+export var AppDataEventTypes;
+(function (AppDataEventTypes) {
+    AppDataEventTypes["APP_DATA_INSERT"] = "APP_DATA_INSERT";
+    AppDataEventTypes["APP_DATA_UPDATE"] = "APP_DATA_UPDATE";
+    AppDataEventTypes["APP_DATA_DELETE"] = "APP_DATA_DELETE";
+})(AppDataEventTypes || (AppDataEventTypes = {}));
+/* ends of blocks common */
+const useComponentName = (functionName) => {
+    const componentName = useMemo(() => {
+        try {
+            const stack = new Error().stack || "";
+            const lines = stack.split("\n");
+            // Find the line containing the function name and get the line above it
+            const functionNameIndex = lines.findIndex((line) => line.includes(functionName));
+            if (functionNameIndex > 0) {
+                const callerLine = lines[functionNameIndex + 1];
+                const fatherComponent = callerLine.split("at ")[1];
+                if (fatherComponent) {
+                    return fatherComponent;
+                }
+            }
+            return "Unknown";
+        }
+        catch {
+            return "Unknown";
+        }
+    }, []);
+    return componentName;
+};
+const useActionRateLimiting = (actionConfig, functionName) => {
+    const componentName = useComponentName(functionName);
+    const queryClient = useQueryClient();
+    const validateExceededMaxCount = (inputs) => {
+        const now = Date.now();
+        for (let windowIndex = 0; windowIndex < EXECUTE_ACTION_WINDOWS.length; windowIndex++) {
+            const executeActionWindow = EXECUTE_ACTION_WINDOWS[windowIndex];
+            // Determine the query key based on whether we're checking with or without inputs
+            const queryKey = executeActionWindow.withData
+                ? [`action-result-${windowIndex}`, actionConfig.actionBlockId, inputs]
+                : [`action-result-${windowIndex}`, actionConfig.actionBlockId];
+            const executeActionHistory = queryClient.getQueryData(queryKey) || [];
+            // Filter history within the current time window
+            const executeActionHistoryInWindow = executeActionHistory.filter((history) => history.timestamp > now - executeActionWindow.duration);
+            // Check if rate limit is exceeded for this window
+            if (executeActionHistoryInWindow.length >= executeActionWindow.maxCount) {
+                const errorMessage = executeActionWindow.withData
+                    ? `Executed action with the same parameters (${JSON.stringify(inputs)}) too many times (${executeActionWindow.maxCount} times in ${executeActionWindow.duration / 1000}s) - actionBlockId: "${actionConfig.actionBlockId}", from component: ${componentName}`
+                    : `Executed action too many times (${executeActionWindow.maxCount} times in ${executeActionWindow.duration / 1000}s) - actionBlockId: "${actionConfig.actionBlockId}", from component: ${componentName}`;
+                throw new FatalAppError(errorMessage);
+            }
+            // Update the history for this window
+            queryClient.setQueryData(queryKey, [...executeActionHistoryInWindow, { timestamp: now }]);
+        }
+    };
+    return { validateExceededMaxCount };
+};
+const useEntityMutationRateLimiting = (entityConfig, functionName) => {
+    const componentName = useComponentName(functionName);
+    const queryClient = useQueryClient();
+    const validateExceededMaxCount = ({ data }) => {
+        const now = Date.now();
+        for (let windowIndex = 0; windowIndex < ENTITY_OPERATION_WINDOWS.length; windowIndex++) {
+            const entityOperationWindow = ENTITY_OPERATION_WINDOWS[windowIndex];
+            const queryKey = entityOperationWindow.withData
+                ? [`entity-operation-${windowIndex}`, entityConfig.tableBlockId, data]
+                : [`entity-operation-${windowIndex}`, entityConfig.tableBlockId];
+            const entityOperationHistory = queryClient.getQueryData(queryKey) || [];
+            // Filter history within the current time window
+            const entityOperationHistoryInWindow = entityOperationHistory.filter((history) => history.timestamp > now - entityOperationWindow.duration);
+            // Check if rate limit is exceeded for this window
+            if (entityOperationHistoryInWindow.length >= entityOperationWindow.maxCount) {
+                const errorMessage = `Too many entity operations (${entityOperationWindow.maxCount} times in ${entityOperationWindow.duration / 1000}s) - tableBlockId: "${entityConfig.tableBlockId}"${data && entityOperationWindow.withData ? `, data: ${JSON.stringify(data)}` : ""}, from component: ${componentName}`;
+                throw new FatalAppError(errorMessage);
+            }
+            // Update the history for this window
+            queryClient.setQueryData(queryKey, [...entityOperationHistoryInWindow, { timestamp: now }]);
+        }
+    };
+    return { validateExceededMaxCount };
+};
+const useEntityRowMutationRateLimiting = (entityConfig, functionName) => {
+    const componentName = useComponentName(functionName);
+    const queryClient = useQueryClient();
+    const validateExceededMaxCount = ({ rowId, data }) => {
+        const now = Date.now();
+        for (let windowIndex = 0; windowIndex < ENTITY_ROW_OPERATION_WINDOWS.length; windowIndex++) {
+            const entityOperationWindow = ENTITY_ROW_OPERATION_WINDOWS[windowIndex];
+            const queryKey = entityOperationWindow.withData
+                ? [`entity-row-operation-${windowIndex}`, entityConfig.tableBlockId, rowId, data]
+                : [`entity-row-operation-${windowIndex}`, entityConfig.tableBlockId, rowId];
+            const entityOperationHistory = queryClient.getQueryData(queryKey) || [];
+            // Filter history within the current time window
+            const entityOperationHistoryInWindow = entityOperationHistory.filter((history) => history.timestamp > now - entityOperationWindow.duration);
+            // Check if rate limit is exceeded for this window
+            if (entityOperationHistoryInWindow.length >= entityOperationWindow.maxCount) {
+                const errorMessage = `Too many entity row operations (${entityOperationWindow.maxCount} times in ${entityOperationWindow.duration / 1000}s) - tableBlockId: "${entityConfig.tableBlockId}", rowId: "${rowId}"${data && entityOperationWindow.withData ? `, data: ${JSON.stringify(data)}` : ""}, from component: ${componentName}`;
+                throw new FatalAppError(errorMessage);
+            }
+            // Update the history for this window
+            queryClient.setQueryData(queryKey, [...entityOperationHistoryInWindow, { timestamp: now }]);
+        }
+    };
+    return { validateExceededMaxCount };
+};
+/**
+ * Provides ClientSdk instance to React component tree
+ *
+ * This component sets up the necessary context providers for both the ClientSdk
+ * and React Query, enabling all the hooks in this module to work properly.
+ *
+ * @param {Object} props - Component props
+ * @param {ClientSdk} props.client - ClientSdk instance to provide
+ * @param {React.ReactNode} props.children - Child components
+ * @param {ThemeMode} [props.themeMode] - (Optional) Theme mode
+ * @param {Function} [props.setThemeMode] - (Optional) Function to set the theme mode
+ * @returns {JSX.Element} Provider component
+ * @example
+ * ```tsx
+ * const client = new ClientSdk({ appId: 'my-app-id', user: {
+ *   email: 'test@test.com',
+ *   firstName: 'Test',
+ *   lastName: 'User',
+ *   isAuthenticated: true,
+ * } });
+ *
+ * function App() {
+ *   return (
+ *     <ClientProvider client={client}>
+ *       <YourAppComponents />
+ *     </ClientProvider>
+ *   );
+ * }
+ * ```
+ */
+export const ClientProvider = ({ client, children, themeMode, setThemeMode, }) => {
+    const [queryClient] = useState(() => new QueryClient());
+    const user = client.getUser();
+    const userIdInNumber = useMemo(() => {
+        if (user?.id) {
+            const num = Number(user.id);
+            if (isNaN(num)) {
+                return undefined;
+            }
+            return num;
+        }
+        return undefined;
+    }, [user?.id]);
+    useWebsockets({ userId: userIdInNumber, token: client.token });
+    useWebsocketsAppSubscribe({ appId: client.appId });
+    const dataChangeCallback = useCallback(async (data) => {
+        queryClient.invalidateQueries({ queryKey: [ENTITIES_QUERY_KEY, data.table] });
+        data.affectRows?.forEach((row) => {
+            queryClient.invalidateQueries({ queryKey: [ENTITIES_QUERY_KEY, data.table, "one", { id: row.id }] });
+        });
+    }, [queryClient]);
+    useEffect(() => {
+        websocketsService.listen(AppDataEventTypes.APP_DATA_INSERT, dataChangeCallback);
+        websocketsService.listen(AppDataEventTypes.APP_DATA_UPDATE, dataChangeCallback);
+        websocketsService.listen(AppDataEventTypes.APP_DATA_DELETE, dataChangeCallback);
+        return () => {
+            websocketsService.unlisten(AppDataEventTypes.APP_DATA_INSERT, dataChangeCallback);
+            websocketsService.unlisten(AppDataEventTypes.APP_DATA_UPDATE, dataChangeCallback);
+            websocketsService.unlisten(AppDataEventTypes.APP_DATA_DELETE, dataChangeCallback);
+        };
+    }, [dataChangeCallback]);
+    return (<ClientContext value={client}>
+      <ThemeModeContext value={{ themeMode, setThemeMode }}>
+        <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+      </ThemeModeContext>
+    </ClientContext>);
+};
+/**
+ * Hook to access the ClientSdk instance from context
+ *
+ * This hook provides direct access to the ClientSdk, which is the core client
+ * for interacting with entities, actions, and pages.
+ *
+ * @returns {ClientSdk} The ClientSdk instance
+ * @throws {Error} If used outside of ClientProvider
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const client = useClient();
+ *   // Use client directly for advanced use cases
+ *   const userEntity = client.entity(userConfig);
+ * }
+ * ```
+ */
+export const useClient = () => {
+    const client = useContext(ClientContext);
+    if (!client) {
+        throw new Error("Client not found");
+    }
+    return client;
+};
+/**
+ * Hook to fetch all entities of a specific type
+ *
+ * Entities represent data objects stored in tables with standard CRUD operations.
+ * This hook provides a React Query-powered way to fetch multiple entities.
+ *
+ * EntityConfig properties:
+ * - tableBlockId: Unique identifier for the table
+ * - instanceType: TypeScript type defining the entity's structure
+ *
+ * @template E - Entity configuration type
+ * @param {E} entityConfig - Configuration for the entity type
+ * @param {any} [filters] - Optional filters to apply to the query
+ * @param {Object} [queryOptions] - Optional React Query configuration options
+ * @param {boolean} [queryOptions.enabled] - Whether the query should automatically execute
+ * @param {EntityType<E>[]} [queryOptions.initialData] - Initial data to use for the query
+ * @param {EntityType<E>[]} [queryOptions.placeholderData] - Placeholder data to use while loading
+ * @returns {Object} Query result with data, loading state, and error
+ * @returns {EntityType<E>[] | undefined} returns.data - The fetched entities
+ * @returns {boolean} returns.isLoading - Whether the query is loading
+ * @returns {Error | null} returns.error - Any error that occurred
+ * @returns {Function} returns.refetch - Function to manually refetch the data
+ * @returns {boolean} returns.isError - Whether the query resulted in an error
+ * @returns {boolean} returns.isFetched - Whether the query has been fetched
+ * @returns {boolean} returns.isFetching - Whether the query is currently fetching
+ * @returns {boolean} returns.isSuccess - Whether the query was successful
+ * @returns {string} returns.status - Current status of the query: 'idle', 'loading', 'success', 'error', or 'pending'
+ * @example
+ * ```tsx
+ * // Define a Item entity configuration
+ * const itemConfig = {
+ *   tableBlockId: 'items-table',
+ *   instanceType: {} as {
+ *     name: string;
+ *     price: number;
+ *   }
+ * };
+ *
+ * function ItemsList() {
+ *   const { data: items, isLoading } = useEntityGetAll(itemConfig);
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *   return (
+ *     <ul>
+ *       {items?.map(item => <li key={item.id}>{item.name}</li>)}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+export const useEntityGetAll = (entityConfig, filters, queryOptions = {}) => {
+    const { enabled, initialData, placeholderData } = queryOptions;
+    const client = useClient();
+    const { data, isLoading, error, isError, isFetched, isFetching, isSuccess, status } = useQuery({
+        queryKey: [ENTITIES_QUERY_KEY, entityConfig.tableBlockId, filters],
+        queryFn: () => client.entity(entityConfig).findMany(filters),
+        enabled,
+        initialData,
+        placeholderData,
+    });
+    return {
+        data,
+        isLoading,
+        error,
+        refetch: () => ({ data, isLoading, error, isError, isFetched, isFetching, isSuccess, status }),
+        isError,
+        isFetched,
+        isFetching,
+        isSuccess,
+        status,
+    };
+};
+/**
+ * Hook to fetch a single entity by filters
+ *
+ * Retrieves a specific entity instance using filter criteria.
+ * EntityConfig defines the structure and mapping of the entity data.
+ *
+ * @template EC - Entity configuration type
+ * @param {EC} entityConfig - Configuration for the entity type
+ * @param {Record<string, any>} filters - Filters to identify the entity (e.g., { id: "123" } or { email: "user@example.com" })
+ * @param {Object} [queryOptions] - Optional React Query configuration options
+ * @param {boolean} [queryOptions.enabled] - Whether the query should automatically execute
+ * @param {EntityType<EC> | null} [queryOptions.initialData] - Initial data to use for the query
+ * @returns {Object} Query result with data, loading state, and error
+ * @returns {EntityType<EC> | undefined | null} returns.data - The fetched entity
+ * @returns {boolean} returns.isLoading - Whether the query is loading
+ * @returns {Error | null} returns.error - Any error that occurred
+ * @returns {Function} returns.refetch - Function to manually refetch the data
+ * @returns {boolean} returns.isError - Whether the query resulted in an error
+ * @returns {boolean} returns.isFetched - Whether the query has been fetched
+ * @returns {boolean} returns.isFetching - Whether the query is currently fetching
+ * @returns {boolean} returns.isSuccess - Whether the query was successful
+ * @returns {string} returns.status - Current status of the query: 'idle', 'loading', 'success', 'error', or 'pending'
+ * @example
+ * ```tsx
+ * // Define the entity configuration
+ * const userConfig = {
+ *   tableBlockId: 'users-table',
+ *   instanceType: {} as {
+ *     name: string;
+ *     email: string;
+ *   }
+ * };
+ *
+ * function UserProfile({ userEmail }) {
+ *   const { data: user, isLoading } = useEntityGetOne(UserEntity, { email: userEmail });
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *   if (!user) return <div>User not found</div>;
+ *
+ *   return <div>Name: {user.name}</div>;
+ * }
+ * ```
+ */
+export const useEntityGetOne = (entityConfig, filters, queryOptions = {}) => {
+    const { enabled, initialData } = queryOptions;
+    const client = useClient();
+    let finalFilters = filters;
+    if (typeof filters === "string") {
+        finalFilters = { id: parseInt(filters) };
+    }
+    else if (typeof filters === "number") {
+        finalFilters = { id: filters };
+    }
+    const { data, isLoading, error, isError, isFetched, isFetching, isSuccess, status } = useQuery({
+        queryKey: [ENTITIES_QUERY_KEY, entityConfig.tableBlockId, "one", finalFilters],
+        queryFn: () => client.entity(entityConfig).findOne(finalFilters),
+        enabled,
+        initialData,
+    });
+    return {
+        data,
+        isLoading,
+        error,
+        refetch: () => ({ data, isLoading, error, isError, isFetched, isFetching, isSuccess, status }),
+        isError,
+        isFetched,
+        isFetching,
+        isSuccess,
+        status,
+    };
+};
+/**
+ * Hook to create a new entity
+ *
+ * Creates a new entity instance in the data store.
+ * EntityTypeOnlyMutable<EC> represents the writable properties of the entity.
+ *
+ * @template EC - Entity configuration type
+ * @param {EC} entityConfig - Configuration for the entity type
+ * @returns {Object} Mutation object with create function, loading state, and error
+ * @example
+ * ```tsx
+ * // Define the entity configuration
+ * const userConfig = {
+ *   tableBlockId: 'users-table',
+ *   instanceType: {} as {
+ *     name: string;
+ *     email: string;
+ *   }
+ * };
+ *
+ * function CreateUserForm() {
+ *   const { createFunction, isLoading } = useEntityCreate(userConfig);
+ *   const [name, setName] = useState('');
+ *   const [email, setEmail] = useState('');
+ *
+ *   const handleSubmit = async (e) => {
+ *     e.preventDefault();
+ *     await createFunction({
+ *       data: {
+ *         name,
+ *         email
+ *       }
+ *     });
+ *     setName('');
+ *     setEmail('');
+ *   };
+ *
+ *   return (
+ *     <form onSubmit={handleSubmit}>
+ *       <input value={name} onChange={e => setName(e.target.value)} placeholder="Name" />
+ *       <input value={email} onChange={e => setEmail(e.target.value)} placeholder="Email" />
+ *       <button type="submit" disabled={isLoading}>Create</button>
+ *     </form>
+ *   );
+ * }
+ * ```
+ */
+export const useEntityCreate = (entityConfig) => {
+    const client = useClient();
+    const queryClient = useQueryClient();
+    const { validateExceededMaxCount } = useEntityMutationRateLimiting(entityConfig, "useEntityCreate");
+    const { mutateAsync: createFunction, isPending: isLoading, error, } = useMutation({
+        mutationFn: ({ data }) => {
+            validateExceededMaxCount({ data });
+            return client.entity(entityConfig).create(data);
+        },
+        onSuccess: () => {
+            // Invalidate the list so we refetch it with the newly created item
+            queryClient.invalidateQueries({ queryKey: [ENTITIES_QUERY_KEY, entityConfig.tableBlockId] });
+        },
+    });
+    if (error instanceof FatalAppError) {
+        throw error;
+    }
+    return { createFunction, isLoading, error };
+};
+/**
+ * Hook to create multiple entities in a single operation
+ *
+ * Creates multiple entity instances in the data store in one batch operation.
+ * This is more efficient than calling useEntityCreate multiple times when you need
+ * to create several entities at once. EntityTypeOnlyMutable<EC> represents the
+ * writable properties of the entity.
+ *
+ * @template EC - Entity configuration type
+ * @param {EC} entityConfig - Configuration for the entity type
+ * @returns {Object} Mutation object with createMany function, loading state, and error
+ * @example
+ * ```tsx
+ * // Define the entity configuration
+ * const taskConfig = {
+ *   tableBlockId: 'tasks-table',
+ *   instanceType: {} as {
+ *     title: string;
+ *     status: 'todo' | 'in_progress' | 'done';
+ *     assigneeId: string;
+ *   }
+ * };
+ *
+ * function ImportTasksButton() {
+ *   const { createManyFunction, isLoading } = useEntityCreateMany(taskConfig);
+ *
+ *   const handleImport = async () => {
+ *     const tasksToCreate = [
+ *       { title: 'Review code', status: 'todo', assigneeId: 'user-1' },
+ *       { title: 'Write tests', status: 'todo', assigneeId: 'user-2' },
+ *       { title: 'Update docs', status: 'in_progress', assigneeId: 'user-1' }
+ *     ];
+ *
+ *     const createdTasks = await createManyFunction({ data: tasksToCreate });
+ *     console.log(`Created ${createdTasks.length} tasks`);
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleImport} disabled={isLoading}>
+ *       {isLoading ? 'Importing...' : 'Import Tasks'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export const useEntityCreateMany = (entityConfig) => {
+    const client = useClient();
+    const queryClient = useQueryClient();
+    const { validateExceededMaxCount } = useEntityMutationRateLimiting(entityConfig, "useEntityCreateMany");
+    const { mutateAsync: createManyFunction, isPending: isLoading, error, } = useMutation({
+        mutationFn: ({ data }) => {
+            validateExceededMaxCount({ data });
+            return client.entity(entityConfig).createMany(data);
+        },
+        onSuccess: () => {
+            // Invalidate the list so we refetch it with the newly created item
+            queryClient.invalidateQueries({ queryKey: [ENTITIES_QUERY_KEY, entityConfig.tableBlockId] });
+        },
+    });
+    if (error instanceof FatalAppError) {
+        throw error;
+    }
+    return { createManyFunction, isLoading, error };
+};
+/**
+ * Hook to update an existing entity
+ *
+ * Updates an existing entity with the provided partial data.
+ * Only the properties included in the data object will be updated.
+ *
+ * @template EC - Entity configuration type
+ * @param {EC} entityConfig - Configuration for the entity type
+ * @returns {Object} Mutation object with update function, loading state, and error
+ * @example
+ * ```tsx
+ * // Define the entity configuration
+ * const userConfig = {
+ *   tableBlockId: 'users-table',
+ *   instanceType: {} as {
+ *     name: string;
+ *     email: string;
+ *   }
+ * };
+ *
+ * function EditUserForm({ user }) {
+ *   const { updateFunction, isLoading } = useEntityUpdate(userConfig);
+ *   const [name, setName] = useState(user.name);
+ *
+ *   const handleSubmit = async (e) => {
+ *     e.preventDefault();
+ *     await updateFunction({
+ *       id: user.id,
+ *       data: { name }
+ *     });
+ *   };
+ *
+ *   return (
+ *     <form onSubmit={handleSubmit}>
+ *       <input value={name} onChange={e => setName(e.target.value)} />
+ *       <button type="submit" disabled={isLoading}>Update</button>
+ *     </form>
+ *   );
+ * }
+ * ```
+ */
+export const useEntityUpdate = (entityConfig) => {
+    const client = useClient();
+    const queryClient = useQueryClient();
+    const { validateExceededMaxCount } = useEntityRowMutationRateLimiting(entityConfig, "useEntityUpdate");
+    const { mutateAsync: updateFunction, isPending: isLoading, error, } = useMutation({
+        mutationFn: ({ id, data }) => {
+            validateExceededMaxCount({ rowId: id, data });
+            return client.entity(entityConfig).updateOne(id, data);
+        },
+        onSuccess: (_result, { id }) => {
+            // Invalidate both the list and the specific item's query
+            queryClient.invalidateQueries({ queryKey: [ENTITIES_QUERY_KEY, entityConfig.tableBlockId] });
+            queryClient.invalidateQueries({ queryKey: [ENTITIES_QUERY_KEY, entityConfig.tableBlockId, "one", { id }] });
+        },
+    });
+    if (error instanceof FatalAppError) {
+        throw error;
+    }
+    return { updateFunction, isLoading, error };
+};
+/**
+ * Hook to delete an entity
+ *
+ * Permanently removes an entity from the data store by its ID.
+ * Automatically invalidates relevant queries after deletion.
+ *
+ * @template EC - Entity configuration type
+ * @param {EC} entityConfig - Configuration for the entity type
+ * @returns {Object} Mutation object with delete function, loading state, and error
+ * @example
+ * ```tsx
+ * // Define the entity configuration
+ * const userConfig = {
+ *   tableBlockId: 'users-table',
+ *   instanceType: {} as {
+ *     name: string;
+ *     email: string;
+ *   }
+ * };
+ *
+ * function DeleteUserButton({ userId }) {
+ *   const { deleteFunction, isLoading } = useEntityDelete(userConfig);
+ *
+ *   const handleDelete = async () => {
+ *     if (confirm('Are you sure?')) {
+ *       await deleteFunction({ id: userId });
+ *     }
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleDelete} disabled={isLoading}>
+ *       Delete User
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export const useEntityDelete = (entityConfig) => {
+    const client = useClient();
+    const queryClient = useQueryClient();
+    const { validateExceededMaxCount } = useEntityRowMutationRateLimiting(entityConfig, "useEntityDelete");
+    const { mutateAsync: deleteFunction, isPending: isLoading, error, } = useMutation({
+        mutationFn: ({ id }) => {
+            validateExceededMaxCount({ rowId: id });
+            return client.entity(entityConfig).deleteOne(id);
+        },
+        onSuccess: (_result, { id }) => {
+            // Invalidate both the list and the specific item's query
+            queryClient.invalidateQueries({ queryKey: [ENTITIES_QUERY_KEY, entityConfig.tableBlockId] });
+            queryClient.invalidateQueries({ queryKey: [ENTITIES_QUERY_KEY, entityConfig.tableBlockId, "one", { id }] });
+        },
+    });
+    if (error instanceof FatalAppError) {
+        throw error;
+    }
+    return { deleteFunction, isLoading, error };
+};
+/**
+ * Hook to delete multiple entities at once
+ *
+ * Permanently removes multiple entities from the data store by their IDs.
+ * Automatically invalidates relevant queries after deletion.
+ *
+ * @template EC - Entity configuration type
+ * @param {EC} entityConfig - Configuration for the entity type
+ * @returns {Object} Mutation object with delete many function, loading state, and error
+ * @example
+ * ```tsx
+ * // Define the entity configuration
+ * const userConfig = {
+ *   tableBlockId: 'users-table',
+ *   instanceType: {} as {
+ *     name: string;
+ *     email: string;
+ *   }
+ * };
+ *
+ * function DeleteSelectedUsersButton({ selectedUserIds }) {
+ *   const { deleteManyFunction, isLoading } = useEntityDeleteMany(userConfig);
+ *
+ *   const handleDeleteSelected = async () => {
+ *     if (confirm(`Delete ${selectedUserIds.length} users?`)) {
+ *       await deleteManyFunction({ ids: selectedUserIds });
+ *     }
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleDeleteSelected} disabled={isLoading}>
+ *       Delete Selected ({selectedUserIds.length})
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export const useEntityDeleteMany = (entityConfig) => {
+    const client = useClient();
+    const queryClient = useQueryClient();
+    const { validateExceededMaxCount } = useEntityMutationRateLimiting(entityConfig, "useEntityDeleteMany");
+    const { mutateAsync: deleteManyFunction, isPending: isLoading, error, } = useMutation({
+        mutationFn: ({ ids }) => {
+            validateExceededMaxCount({ data: ids });
+            return client.entity(entityConfig).deleteMany(ids);
+        },
+        onSuccess: (_result, { ids }) => {
+            queryClient.invalidateQueries({ queryKey: [ENTITIES_QUERY_KEY, entityConfig.tableBlockId] });
+            ids.forEach((id) => {
+                queryClient.invalidateQueries({ queryKey: [ENTITIES_QUERY_KEY, entityConfig.tableBlockId, "one", { id }] });
+            });
+        },
+    });
+    if (error instanceof FatalAppError) {
+        throw error;
+    }
+    return { deleteManyFunction, isLoading, error };
+};
+/**
+ * Hook to execute an action, with support for streaming results
+ *
+ * Actions represent executable workflows that perform any type of server-side operation,
+ * including data processing, business logic, integrations with external
+ * services, file operations, AI functionalities, and more. This hook provides a React-friendly
+ * way to execute these actions with proper state management.
+ *
+ * AI capabilities are a particularly interesting use case for actions - you can leverage
+ * various AI models and services while the SDK handles the complexity of streaming responses,
+ * state management, and UI integration.
+ *
+ * The hook provides two different result states:
+ * - `result`: Contains the final, complete output once the action execution is done
+ * - `streamResult`: Contains incrementally updating results during streaming operations,
+ *   updated in real-time as chunks arrive from the server before the action is complete
+ *
+ * ActionConfig properties:
+ * - actionBlockId: Unique identifier for the action workflow
+ * - inputInstanceType: TypeScript type defining the action's input parameters
+ * - outputInstanceType: TypeScript type defining the action's output structure
+ *
+ * @template AC - Action configuration type
+ * @param {AC} actionConfig - Configuration for the action
+ * @returns {Object} Action execution object with functions, state, and results
+ * @returns {Function} returns.executeFunction - Function to execute the action with inputs
+ * @returns {AC["outputInstanceType"]} returns.result - Final result after action completes
+ * @returns {AC["outputInstanceType"]} returns.streamResult - Incrementally updated result during streaming
+ * @returns {boolean} returns.isLoading - Whether the action is currently executing
+ * @returns {boolean} returns.isDone - Whether the action has completed
+ * @returns {Error | null} returns.error - Any error that occurred during execution
+ * @returns {Function} returns.clear - Function to clear result and streamResult values
+ * @example
+ * ```tsx
+ * // Example 1: Process payment action
+ * const processPaymentConfig = {
+ *   actionBlockId: 'process-payment',
+ *   inputInstanceType: {} as {
+ *     amount: number;
+ *     paymentMethod: string;
+ *     currency: string;
+ *   },
+ *   outputInstanceType: {} as {
+ *     success: boolean;
+ *     transactionId: string;
+ *     receiptUrl?: string;
+ *     error?: string;
+ *   }
+ * };
+ *
+ * function PaymentForm() {
+ *   const { executeFunction, result, isLoading, error } = useExecuteAction(processPaymentConfig);
+ *   const [amount, setAmount] = useState('');
+ *   const [paymentMethod, setPaymentMethod] = useState('credit_card');
+ *
+ *   const handleSubmit = async (e) => {
+ *     e.preventDefault();
+ *     await executeFunction({
+ *       amount: parseFloat(amount),
+ *       paymentMethod,
+ *       currency: 'USD'
+ *     });
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <form onSubmit={handleSubmit}>
+ *         <input
+ *           type="number"
+ *           value={amount}
+ *           onChange={e => setAmount(e.target.value)}
+ *           placeholder="Amount"
+ *         />
+ *         <select value={paymentMethod} onChange={e => setPaymentMethod(e.target.value)}>
+ *           <option value="credit_card">Credit Card</option>
+ *           <option value="paypal">PayPal</option>
+ *         </select>
+ *         <button type="submit" disabled={isLoading}>Process Payment</button>
+ *       </form>
+ *
+ *       {isLoading && <div>Processing payment...</div>}
+ *       {error && <div className="error">Error: {error.message}</div>}
+ *       {result?.success && <div className="success">
+ *         Payment successful! Transaction ID: {result.transactionId}
+ *       </div>}
+ *     </div>
+ *   );
+ * }
+ *
+ * // Example 2: Data export action (with streaming)
+ * const exportDataConfig = {
+ *   actionBlockId: 'export-data',
+ *   inputInstanceType: {} as {
+ *     format: 'csv' | 'json';
+ *     filters: Record<string, any>;
+ *   },
+ *   outputInstanceType: {} as {
+ *     progress: number;
+ *     downloadUrl?: string;
+ *     status: string;
+ *   }
+ * };
+ *
+ * function DataExportTool() {
+ *   const { executeFunction, result, isLoading, isDone } = useExecuteAction(exportDataConfig);
+ *   const [format, setFormat] = useState<'csv' | 'json'>('csv');
+ *
+ *   const handleExport = async () => {
+ *     await executeFunction({
+ *       format,
+ *       filters: { startDate: '2023-01-01' }
+ *     });
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <div>
+ *         <select value={format} onChange={e => setFormat(e.target.value as 'csv' | 'json')}>
+ *           <option value="csv">CSV</option>
+ *           <option value="json">JSON</option>
+ *         </select>
+ *         <button onClick={handleExport} disabled={isLoading}>Export Data</button>
+ *       </div>
+ *
+ *       {isLoading && !isDone && (
+ *         <div>
+ *           {result?.progress ? `Export in progress: ${result.progress}%` : 'Starting export...'}
+ *         </div>
+ *       )}
+ *       {isDone && result?.downloadUrl && (
+ *         <a href={result.downloadUrl} download>Download your data</a>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export const useExecuteAction = (actionConfig) => {
+    const client = useClient();
+    const [isDone, setIsDone] = useState(false);
+    const { validateExceededMaxCount } = useActionRateLimiting(actionConfig, "useExecuteAction");
+    const [streamResult, setStreamResult] = useState();
+    const { handleChunk, onCompleteChunks } = useAiStreamChunks({
+        onChunk: (chunkData) => {
+            // TODO: This is a very hard-coded solution designed for the generate text action, who uses "response" as the key
+            // We should find a better way to handle this
+            setStreamResult((prevResult) => {
+                const prevResponse = prevResult?.response || "";
+                return {
+                    ...(prevResult || {}),
+                    response: prevResponse + chunkData,
+                };
+            });
+        },
+    });
+    const { data: result, mutateAsync: executeFunction, isPending: isLoading, error, reset, } = useMutation({
+        mutationFn: async (inputs) => {
+            let streamResultHandled = false;
+            validateExceededMaxCount(inputs);
+            const result = await client.action(actionConfig).execute(inputs, {
+                onChunk: (chunkData) => {
+                    streamResultHandled = true;
+                    handleChunk(chunkData.contentIndex, chunkData.content);
+                },
+            });
+            if (!streamResultHandled) {
+                setStreamResult(result);
+            }
+            return result;
+        },
+        onMutate: () => {
+            setStreamResult(undefined);
+            setIsDone(false);
+        },
+        onSettled: () => {
+            onCompleteChunks();
+            setIsDone(true);
+        },
+    });
+    if (error instanceof FatalAppError) {
+        throw error;
+    }
+    const clear = useCallback(() => {
+        reset();
+        setStreamResult(undefined);
+    }, []);
+    return { executeFunction, result, streamResult, isLoading, isDone, error, clear };
+};
+/**
+ * Hook to get an AgentChat instance
+ *
+ * This hook provides access to an AgentChat instance for the specified configuration.
+ *
+ * @template ACC - AgentChat configuration type
+ * @param {ACC} agentChatConfig - Configuration for the agent chat
+ * @returns {AgentChat<ACC>} An AgentChat instance for the given configuration
+ * @example
+ * ```tsx
+ * // Define the agent chat configuration
+ * const agentChatConfig = {
+ *   agentChatId: 'agent-chat-id'
+ * };
+ *
+ * function AgentChatComponent() {
+ *   const agentChat = useAgentChat(agentChatConfig);
+ *   return <AgentChat agentChat={agentChat} />;
+ * }
+ * ```
+ */
+export const useAgentChat = (agentChatConfig) => {
+    const client = useClient();
+    return client.agentChat(agentChatConfig);
+};
+/**
+ * Hook to handle file uploads
+ *
+ * Provides a function to upload files with progress tracking
+ *
+ * @returns {Object} Upload object with upload functionality and status
+ * @returns {Function} returns.uploadFunction - Function that takes a File and returns a Promise with the URL
+ * @returns {boolean} returns.isLoading - Whether an upload is in progress
+ * @returns {number} returns.uploadPercentage - Current upload progress (0-100)
+ * @example
+ * ```tsx
+ * function FileUploader() {
+ *   const { uploadFunction, isLoading, uploadPercentage } = useFileUpload();
+ *   const [fileUrl, setFileUrl] = useState('');
+ *
+ *   const handleFileChange = async (event) => {
+ *     const file = event.target.files[0];
+ *     if (file) {
+ *       try {
+ *         const url = await uploadFunction(file);
+ *         setFileUrl(url);
+ *       } catch (error) {
+ *         console.error('Upload failed:', error);
+ *       }
+ *     }
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <input type="file" onChange={handleFileChange} disabled={isLoading} />
+ *       {isLoading && <Progress value={uploadPercentage} />}
+ *       {fileUrl && <img src={fileUrl} alt="Uploaded file" />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export const useFileUpload = () => {
+    const client = useClient();
+    const [isLoading, setIsLoading] = useState(false);
+    const [uploadPercentage, setUploadPercentage] = useState(0);
+    const uploadFunction = useCallback(async (file) => {
+        setIsLoading(true);
+        setUploadPercentage(0);
+        try {
+            const protectedUrl = await client.upload(file, {
+                onProgress: (percentage) => {
+                    setUploadPercentage(percentage);
+                },
+            });
+            return protectedUrl;
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [client]);
+    return { uploadFunction, isLoading, uploadPercentage };
+};
+/**
+ * Represents a user's data
+ * @interface User
+ * @property {string} [id] - The user's ID (optional, must exist if user is authenticated)
+ * @property {string} [email] - The user's email (optional, must exist if user is authenticated)
+ * @property {string} [name] - The user's name (optional, must exist if user is authenticated)
+ * @property {string} [profileImageUrl] - The user's profile image URL (optional)
+ * @property {string} [firstName] - The user's first name (optional)
+ * @property {string} [lastName] - The user's last name (optional)
+ * @property {string} [role] - The user's role name (optional)
+ * @property {string} [permission] - The user's permission level: 'build' (can modify app) or 'use' (read-only) (optional)
+ */
+/**
+ * Hook to get the current user information
+ *
+ * This hook provides access to the user's data
+ * that was provided during SDK initialization, including role information for multi-role apps.
+ *
+ * @returns {User} The current user object with optional role property
+ * @example
+ * ```tsx
+ * const user = useUser();
+ * console.log(user.isAuthenticated ? `Logged in as: ${user.firstName} ${user.lastName}` : "Not logged in");
+ *
+ * // For multi-role apps, conditionally render based on role
+ * if (user.role === "Manager") {
+ *   return <ManagerDashboard />;
+ * } else if (user.role === "Employee") {
+ *   return <EmployeeDashboard />;
+ * }
+ * ```
+ */
+export const useUser = () => {
+    const client = useClient();
+    const { data: user } = useQuery({
+        queryKey: [CURRENT_USER_QUERY_KEY],
+        queryFn: () => client.getUser(),
+        initialData: client.getUser(),
+    });
+    return user;
+};
+/**
+ * Hook to manage the application theme mode
+ *
+ * This hook provides access to the current theme mode and a function to change it.
+ * It supports three theme modes: dark, light, and system (which follows the user's OS preference).
+ *
+ * @returns {Object} Object containing current theme mode and setter function
+ * @returns {("dark" | "light" | "system")} themeMode - The current theme mode
+ * @returns {Function} setThemeMode - Function to update the theme mode
+ * @example
+ * ```tsx
+ * function ThemeToggle() {
+ *   const { themeMode, setThemeMode } = useThemeMode();
+ *
+ *   return (
+ *     <div>
+ *       <p>Current theme: {themeMode}</p>
+ *       <button onClick={() => setThemeMode("dark")}>Dark</button>
+ *       <button onClick={() => setThemeMode("light")}>Light</button>
+ *       <button onClick={() => setThemeMode("system")}>System</button>
+ *     </div>
+ *   );
+ * }
+ *
+ * // Example with a select dropdown
+ * function ThemeSelector() {
+ *   const { themeMode, setThemeMode } = useThemeMode();
+ *
+ *   return (
+ *     <select
+ *       value={themeMode}
+ *       onChange={(e) => setThemeMode(e.target.value as "dark" | "light" | "system")}
+ *     >
+ *       <option value="system">System</option>
+ *       <option value="light">Light</option>
+ *       <option value="dark">Dark</option>
+ *     </select>
+ *   );
+ * }
+ * ```
+ */
+export const useThemeMode = () => {
+    const { themeMode, setThemeMode } = useContext(ThemeModeContext);
+    return { themeMode, setThemeMode };
+};
+/**
+ * Hook to change a user's role in multi-role applications
+ *
+ * This hook provides functionality to change a user's role, but only if the current user
+ * has "build" permission. The hook automatically invalidates relevant queries after a successful
+ * role change, including the current user's data if they changed their own role.
+ *
+ * @param {Object} [params] - Hook parameters
+ * @param {UpdateUserOptions} [params.options] - Optional configuration for the user update
+ * @returns {Object} Mutation object with role change function, loading state, error, and authorization state
+ * @returns {Function} returns.changeUserRoleFunction - Function to change a user's role
+ * @returns {boolean} returns.isLoading - Whether the role change is in progress
+ * @returns {Error | null} returns.error - Any error that occurred during the role change
+ * @returns {boolean} returns.isEnabled - Whether the current user is authorized to change roles (has "build" permission)
+ * @example
+ * ```tsx
+ * function UserRoleManager({ userId, currentRole }) {
+ *   const { changeUserRoleFunction, isLoading, error, isEnabled } = useChangeUserRole();
+ *   const [selectedRole, setSelectedRole] = useState(currentRole);
+ *
+ *   const handleRoleChange = async () => {
+ *     try {
+ *       await changeUserRoleFunction({
+ *         userId,
+ *         role: selectedRole
+ *       });
+ *       alert('Role changed successfully!');
+ *     } catch (err) {
+ *       console.error('Failed to change role:', err);
+ *     }
+ *   };
+ *
+ *   if (!isEnabled) {
+ *     return <div>You don't have permission to change user roles</div>;
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <select
+ *         value={selectedRole}
+ *         onChange={(e) => setSelectedRole(e.target.value)}
+ *         disabled={isLoading}
+ *       >
+ *         <option value="Admin">Admin</option>
+ *         <option value="Manager">Manager</option>
+ *         <option value="Employee">Employee</option>
+ *       </select>
+ *       <button onClick={handleRoleChange} disabled={isLoading}>
+ *         {isLoading ? 'Changing...' : 'Change Role'}
+ *       </button>
+ *       {error && <div className="error">Error: {error.message}</div>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export const useChangeUserRole = ({ options } = {}) => {
+    const client = useClient();
+    const queryClient = useQueryClient();
+    const currentUser = useUser();
+    const isEnabled = currentUser?.permission === "build";
+    const { mutateAsync: changeUserRoleFunction, isPending: isLoading, error, } = useMutation({
+        mutationFn: ({ userId, role }) => {
+            if (!isEnabled) {
+                throw new Error("You are not authorized to change user roles");
+            }
+            return client.changeUserRole(userId, role, options);
+        },
+        onSuccess: (_result, { userId }) => {
+            if (currentUser.id && userId === currentUser.id) {
+                queryClient.invalidateQueries({ queryKey: [CURRENT_USER_QUERY_KEY] });
+            }
+            queryClient.invalidateQueries({ queryKey: [ENTITIES_QUERY_KEY, USERS_TABLE_BLOCK_ID] });
+            queryClient.invalidateQueries({
+                queryKey: [ENTITIES_QUERY_KEY, USERS_TABLE_BLOCK_ID, "one", { id: userId }],
+            });
+        },
+    });
+    if (error instanceof FatalAppError) {
+        throw error;
+    }
+    return { changeUserRoleFunction, isLoading, error, isEnabled };
+};
+/**
+ * Hook to send a passwordless login link (magic link) to a user's email
+ *
+ * This hook provides functionality to send an email containing a one-time login link
+ * that allows users to authenticate without entering a password. When the user clicks
+ * the link in their email, they will be automatically logged into the application.
+ * The hook manages loading state, success state, and error handling automatically.
+ *
+ * @returns {Object} Object with send function, loading state, success state, and error
+ * @returns {Function} returns.sendLoginLink - Function to send the login link to an email address
+ * @returns {boolean} returns.isLoading - Whether the request is currently in progress
+ * @returns {boolean} returns.isSuccess - Whether the login link was sent successfully
+ * @returns {Error | null} returns.error - Any error that occurred during the request
+ * @example
+ * ```tsx
+ * function PasswordlessLoginForm() {
+ *   const { sendLoginLink, isLoading, isSuccess, error } = useSendLoginLink();
+ *   const [email, setEmail] = useState('');
+ *
+ *   const handleSubmit = async (e: React.FormEvent) => {
+ *     e.preventDefault();
+ *     await sendLoginLink({ email });
+ *   };
+ *
+ *   if (isSuccess) {
+ *     return <div>Check your email for a login link!</div>;
+ *   }
+ *
+ *   return (
+ *     <form onSubmit={handleSubmit}>
+ *       <input
+ *         type="email"
+ *         value={email}
+ *         onChange={(e) => setEmail(e.target.value)}
+ *         placeholder="Enter your email"
+ *         disabled={isLoading}
+ *       />
+ *       <button type="submit" disabled={isLoading}>
+ *         {isLoading ? 'Sending...' : 'Send Login Link'}
+ *       </button>
+ *       {error && <div className="error">{error.message}</div>}
+ *     </form>
+ *   );
+ * }
+ * ```
+ */
+export const useSendLoginLink = () => {
+    const { sendLoginLink: clientSendLoginLink } = useClient();
+    const [isLoading, setIsLoading] = useState(false);
+    const [isSuccess, setIsSuccess] = useState(false);
+    const [error, setError] = useState(null);
+    const sendLoginLink = useCallback(async ({ email }) => {
+        setIsLoading(true);
+        setIsSuccess(false);
+        setError(null);
+        try {
+            await clientSendLoginLink({ email });
+            setIsSuccess(true);
+            setError(null);
+        }
+        catch (error) {
+            setIsSuccess(false);
+            setError(error);
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [clientSendLoginLink]);
+    return { sendLoginLink, isLoading, isSuccess, error };
+};
+/**
+ * Hook to get the Google OAuth login URL
+ *
+ * This hook returns the URL for initiating the Google OAuth login flow.
+ * When users navigate to this URL, they will be redirected to Google's authentication page.
+ * After successful authentication with Google, they will be redirected back to the application
+ * and automatically logged in.
+ *
+ * @returns {string} The Google OAuth login URL
+ * @example
+ * ```tsx
+ * // Example 1: Use in a Link component
+ * function GoogleLoginLink() {
+ *   const googleLoginUrl = useGoogleLogin();
+ *
+ *   return (
+ *     <Link to={googleLoginUrl}>
+ *       <Button>Sign in with Google</Button>
+ *     </Link>
+ *   );
+ * }
+ *
+ * // Example 2: Redirect with a button
+ * function GoogleLoginButton() {
+ *   const googleLoginUrl = useGoogleLogin();
+ *
+ *   const handleGoogleLogin = () => {
+ *     window.location.href = googleLoginUrl;
+ *   };
+ *
+ *   return <Button onClick={handleGoogleLogin}>Sign in with Google</Button>;
+ * }
+ * ```
+ */
+export const useGoogleLogin = () => {
+    const { getGoogleLoginUrl: clientGetGoogleLoginUrl } = useClient();
+    return clientGetGoogleLoginUrl();
+};
+/**
+ * @deprecated
+ * This hook is deprecated and should not be used.
+ */
+export const usePageParams = (pageConfig) => {
+    const client = useClient();
+    const pageParams = useMemo(() => {
+        const page = client.page(pageConfig);
+        return page.getParams();
+    }, [client, pageConfig.pageBlockId]);
+    return pageParams;
+};
+/**
+ * @deprecated
+ * This hook is deprecated and should not be used.
+ */
+export const usePageUrl = (pageConfig) => {
+    const client = useClient();
+    const pageParams = usePageParams(pageConfig);
+    return client.page(pageConfig).getUrl(pageParams);
+};
+//# sourceMappingURL=ReactClientSdk.jsx.map