@buildbase/sdk 0.0.11 → 0.0.12

package/dist/types/lib/error-handler.d.ts

@@ -55,6 +55,46 @@ declare class ErrorHandler {
     wrapSync<T extends (...args: any[]) => any>(fn: T, context: SDKErrorContext): T;
 }
 export declare const errorHandler: ErrorHandler;
+/**
+ * Convenience function to handle an error with context.
+ * Uses the global error handler instance.
+ *
+ * @param error - The error to handle (Error instance, string, or unknown)
+ * @param context - Optional context about where the error occurred
+ *
+ * @example
+ * ```tsx
+ * try {
+ *   await someOperation();
+ * } catch (error) {
+ *   handleError(error, {
+ *     component: 'MyComponent',
+ *     action: 'someOperation',
+ *     metadata: { userId: '123' },
+ *   });
+ * }
+ * ```
+ */
 export declare function handleError(error: Error | unknown, context?: SDKErrorContext): void;
+/**
+ * Creates a new SDKError instance with optional code and context.
+ * Useful for creating standardized errors throughout the SDK.
+ *
+ * @param message - Error message
+ * @param code - Optional error code (e.g., 'AUTH_FAILED', 'NETWORK_ERROR')
+ * @param context - Optional context about where the error occurred
+ * @param originalError - Optional original error that caused this error
+ * @returns A new SDKError instance
+ *
+ * @example
+ * ```tsx
+ * throw createSDKError(
+ *   'Failed to authenticate user',
+ *   'AUTH_FAILED',
+ *   { component: 'AuthProvider', action: 'signIn' },
+ *   originalError
+ * );
+ * ```
+ */
 export declare function createSDKError(message: string, code?: string, context?: SDKErrorContext, originalError?: Error): SDKError;
 export {};

package/dist/types/providers/auth/hooks.d.ts

@@ -1,3 +1,64 @@
+/**
+ * Main authentication hook for the SDK.
+ * Provides authentication state, user session, and auth actions.
+ *
+ * @returns An object containing:
+ * - `user`: Current authenticated user object (null if not authenticated)
+ * - `session`: Full session object with user and token (null if not authenticated)
+ * - `status`: Current authentication status (loading, redirecting, authenticating, authenticated, unauthenticated)
+ * - `isLoading`: Boolean indicating if auth state is being determined
+ * - `isAuthenticated`: Boolean indicating if user is authenticated
+ * - `isRedirecting`: Boolean indicating if redirecting to OAuth provider
+ * - `signIn()`: Function to initiate OAuth sign-in flow
+ * - `signOut()`: Function to sign out the current user
+ * - `openWorkspaceSettings(section?)`: Function to open workspace settings dialog
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { user, isAuthenticated, signIn, signOut } = useSaaSAuth();
+ *
+ *   if (!isAuthenticated) {
+ *     return <button onClick={signIn}>Sign In</button>;
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <p>Welcome, {user?.name}</p>
+ *       <button onClick={signOut}>Sign Out</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Handle loading state
+ * function App() {
+ *   const { status, isLoading } = useSaaSAuth();
+ *
+ *   if (isLoading) {
+ *     return <LoadingSpinner />;
+ *   }
+ *
+ *   return <MainContent />;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Open workspace settings
+ * function SettingsButton() {
+ *   const { openWorkspaceSettings } = useSaaSAuth();
+ *
+ *   return (
+ *     <button onClick={() => openWorkspaceSettings('general')}>
+ *       Open Settings
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
 export declare function useSaaSAuth(): {
     signIn: () => Promise<void>;
     signOut: () => Promise<void>;

package/dist/types/providers/os/hooks.d.ts

@@ -1,5 +1,44 @@
 import type { ISettings } from '../types';
+/**
+ * Hook to access organization settings from the OS context.
+ * Automatically fetches settings when OS config is ready.
+ *
+ * @returns An object containing:
+ * - `settings`: Organization settings object (null if not loaded)
+ * - `getSettings(signal?)`: Function to manually fetch settings (supports AbortSignal)
+ *
+ * @example
+ * ```tsx
+ * function SettingsDisplay() {
+ *   const { settings } = useSaaSSettings();
+ *
+ *   if (!settings) return <Loading />;
+ *
+ *   return (
+ *     <div>
+ *       <p>Organization: {settings.name}</p>
+ *       <p>Theme: {settings.theme}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Manual fetch with abort signal
+ * function SettingsLoader() {
+ *   const { getSettings } = useSaaSSettings();
+ *
+ *   useEffect(() => {
+ *     const controller = new AbortController();
+ *     getSettings(controller.signal);
+ *
+ *     return () => controller.abort();
+ *   }, [getSettings]);
+ * }
+ * ```
+ */
 export declare function useSaaSSettings(): {
     settings: ISettings | null | undefined;
-    getSettings: () => Promise<ISettings | null>;
+    getSettings: (signal?: AbortSignal) => Promise<ISettings | null>;
 };

package/dist/types/providers/user/hooks.d.ts

@@ -1,4 +1,75 @@
+/**
+ * Hook to access user attributes from the UserProvider.
+ * Must be used within a UserProvider component.
+ *
+ * @returns User context object containing:
+ * - `attributes`: Record of user attribute key-value pairs
+ * - `isLoading`: Boolean indicating if attributes are being loaded
+ * - `error`: Error message string (null if no error)
+ * - `refreshAttributes()`: Function to manually refresh attributes
+ *
+ * @throws {Error} If used outside of UserProvider
+ *
+ * @example
+ * ```tsx
+ * function UserProfile() {
+ *   const { attributes, isLoading } = useUserAttributes();
+ *
+ *   if (isLoading) return <Loading />;
+ *
+ *   return (
+ *     <div>
+ *       <p>Plan: {attributes?.plan}</p>
+ *       <p>Company: {attributes?.company}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 export declare function useUserAttributes(): import("./provider").UserContextValue;
+/**
+ * Hook to access user feature flags from the UserProvider.
+ * Must be used within a UserProvider component.
+ *
+ * @returns An object containing:
+ * - `features`: Record of feature flag key-value pairs (boolean values)
+ * - `isLoading`: Boolean indicating if features are being loaded
+ * - `error`: Error message string (null if no error)
+ * - `refreshFeatures()`: Function to manually refresh features
+ * - `isFeatureEnabled(featureId)`: Function to check if a specific feature is enabled
+ *
+ * @throws {Error} If used outside of UserProvider
+ *
+ * @example
+ * ```tsx
+ * function FeatureContent() {
+ *   const { isFeatureEnabled, isLoading } = useUserFeatures();
+ *
+ *   if (isLoading) return <Loading />;
+ *
+ *   if (isFeatureEnabled('premium-feature')) {
+ *     return <PremiumFeature />;
+ *   }
+ *
+ *   return <BasicFeature />;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Check multiple features
+ * function Dashboard() {
+ *   const { isFeatureEnabled } = useUserFeatures();
+ *
+ *   return (
+ *     <div>
+ *       {isFeatureEnabled('analytics') && <Analytics />}
+ *       {isFeatureEnabled('reports') && <Reports />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 export declare function useUserFeatures(): {
     features: Record<string, boolean>;
     isLoading: boolean;

package/dist/types/providers/workspace/hooks.d.ts

@@ -1,6 +1,111 @@
 import { IUser } from '../../api/types';
 import { WorkspaceSwitcher } from './provider';
 import { IWorkspace, IWorkspaceUser } from './types';
+/**
+ * Main workspace management hook for the SDK.
+ * Provides workspace state, CRUD operations, and user management.
+ *
+ * @returns An object containing:
+ * - `workspaces`: Array of all workspaces the user has access to
+ * - `currentWorkspace`: Currently selected workspace (null if none selected)
+ * - `loading`: Boolean indicating if workspaces are being fetched
+ * - `error`: Error message string (null if no error)
+ * - `refreshing`: Boolean indicating if workspaces are being refreshed in background
+ * - `switching`: Boolean indicating if workspace is being switched
+ * - `WorkspaceSwitcher`: Component for switching between workspaces
+ * - `fetchWorkspaces()`: Function to fetch all workspaces
+ * - `refreshWorkspaces()`: Function to refresh workspaces in background (non-blocking)
+ * - `setCurrentWorkspace(workspace)`: Function to set the current workspace
+ * - `resetCurrentWorkspace()`: Function to clear the current workspace
+ * - `createWorkspace(name, image?)`: Function to create a new workspace
+ * - `updateWorkspace(workspace, data)`: Function to update a workspace
+ * - `deleteWorkspace(workspaceId)`: Function to delete a workspace (owner only)
+ * - `getWorkspace(workspaceId)`: Function to fetch a specific workspace
+ * - `getUsers(workspaceId)`: Function to fetch users in a workspace
+ * - `addUser(workspaceId, email, role)`: Function to add a user to a workspace
+ * - `removeUser(workspaceId, userId)`: Function to remove a user from a workspace
+ * - `updateUser(workspaceId, userId, config)`: Function to update a user in a workspace
+ * - `getProfile()`: Function to fetch current user profile
+ * - `updateUserProfile(config)`: Function to update current user profile
+ * - `allFeatures`: Array of all available feature flags
+ * - `getFeatures()`: Function to fetch all available features
+ * - `updateFeature(workspaceId, key, value)`: Function to update a feature flag
+ *
+ * @example
+ * ```tsx
+ * function WorkspaceList() {
+ *   const { workspaces, loading, fetchWorkspaces } = useSaaSWorkspaces();
+ *
+ *   useEffect(() => {
+ *     fetchWorkspaces();
+ *   }, [fetchWorkspaces]);
+ *
+ *   if (loading) return <Loading />;
+ *
+ *   return (
+ *     <ul>
+ *       {workspaces.map(ws => (
+ *         <li key={ws._id}>{ws.name}</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Create a new workspace
+ * function CreateWorkspace() {
+ *   const { createWorkspace } = useSaaSWorkspaces();
+ *
+ *   const handleCreate = async () => {
+ *     try {
+ *       await createWorkspace('My Workspace', 'https://example.com/logo.png');
+ *     } catch (error) {
+ *       console.error('Failed to create workspace:', error);
+ *     }
+ *   };
+ *
+ *   return <button onClick={handleCreate}>Create Workspace</button>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Delete workspace (owner only)
+ * function DeleteWorkspaceButton({ workspaceId }) {
+ *   const { deleteWorkspace } = useSaaSWorkspaces();
+ *
+ *   const handleDelete = async () => {
+ *     if (!confirm('Are you sure?')) return;
+ *     try {
+ *       await deleteWorkspace(workspaceId);
+ *     } catch (error) {
+ *       // Error: "Only the workspace creator can delete the workspace"
+ *       alert(error.message);
+ *     }
+ *   };
+ *
+ *   return <button onClick={handleDelete}>Delete</button>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Edge case: Workspace removed from user's access
+ * function WorkspaceContent() {
+ *   const { currentWorkspace, workspaces } = useSaaSWorkspaces();
+ *
+ *   // If current workspace is not in the list, it was removed
+ *   // The hook automatically switches to first available workspace
+ *   if (!currentWorkspace) {
+ *     return <p>No workspace selected</p>;
+ *   }
+ *
+ *   return <div>{currentWorkspace.name}</div>;
+ * }
+ * ```
+ */
 export declare const useSaaSWorkspaces: () => {
     workspaces: IWorkspace[];
     loading: boolean;